refactor(tui): read clipboard images through the clipboard service

Author: TheGreatAxios

docs/ARCHITECTURE.md

@@ -443,7 +443,7 @@ OpenTUI (`@opentui/core`) is the shipping shell; the Ink/React tree has been del
 - **Runner host** (`runner-host.ts`) — Runner-facing mount: catalog assembly from live config, chrome pushes on session change, subagent observe resolution, and session teardown (quitting is Ctrl+C twice, owned by the shell).
 - **Overlays and pickers** — Resume picker (`src/tui/pick-session.ts`) uses `runListModal` (`src/tui/list-modal.ts`). Slash-command surfaces (`/model`, `/settings`, `/permissions`, `/plugins`, etc.) route through `openCommandSurface` (`src/tui/command-surfaces.ts`).
 - **Auto mode** — Toggled by CLI flags only (`--auto` / `--no-auto`); there is currently no in-session key bound to it.
-- **Send-path ingest** — Submit, leftover send, and live steer run `ingestOperatorPrompt` (`src/tui/prompt-attachments.ts`): inline image-path mentions become attachments (`findImagePathMentions` / `imageAttachmentFromPath`); `@file` contents are inlined and `@dir` mentions become a directory summary (`resolveAtMentions` in `mention-resolution.ts`). The mention popup splices paths into the prompt (`spliceMentionCompletion`); it does not send. Ctrl+V / Ctrl+P (and `/paste-image`) attach a macOS clipboard PNG (`attachClipboardImage` in `shell.ts` → `readClipboardImage`); Cmd+V stays text (bracketed paste). Linux/Windows bitmap clipboard paste is not supported.
+- **Send-path ingest** — Submit, leftover send, and live steer run `ingestOperatorPrompt` (`src/tui/prompt-attachments.ts`): inline image-path mentions become attachments (`findImagePathMentions` / `imageAttachmentFromPath`); `@file` contents are inlined and `@dir` mentions become a directory summary (`resolveAtMentions` in `mention-resolution.ts`). The mention popup splices paths into the prompt (`spliceMentionCompletion`); it does not send. Ctrl+V / Ctrl+P (and `/paste-image`) attach an image from the system clipboard (`attachClipboardImage` in `shell.ts` → `readClipboardImage`); Cmd+V stays text (bracketed paste). Image clipboard reads go through the OpenTUI clipboard service (PNG, JPEG, GIF, WebP) on platforms whose host backend supports them.
 
 Known keybindings: `Ctrl+C` interrupts the in-flight run, and quits on a second press inside a two-second window.
 

docs/IMPLEMENTATION.md

@@ -235,10 +235,10 @@ a path into the prompt (`spliceMentionCompletion`). Attachments land at send
 time, not at accept time.
 
 Ctrl+V / Ctrl+P and `/paste-image` call `attachClipboardImage` (`shell.ts`) →
-`readClipboardImage` (`image-attachments.ts`), which reads a macOS clipboard
-PNG via osascript `«class PNGf»`. Cmd+V is terminal bracketed paste and stays
-text. Linux and Windows bitmap clipboard paste is a separate product gap; do
-not treat bracketed-paste path text as a paste-time image gesture.
+`readClipboardImage` (`image-attachments.ts`), which reads PNG, JPEG, GIF, or
+WebP through the OpenTUI clipboard service. Cmd+V is terminal bracketed paste
+and stays text. Do not treat bracketed-paste path text as a paste-time image
+gesture.
 
 ## Configuration
 

docs/TUI.md

@@ -878,11 +878,11 @@ sent messages. Once a real `paste` event has fired even once, the fallback
 heuristic is permanently skipped for the rest of the session
 (`src/tui/shell/keys.ts`, the `sawBracketedPaste` guard).
 
-Ctrl+V and Ctrl+P attach a PNG from the macOS clipboard
+Ctrl+V and Ctrl+P attach an image from the system clipboard
 (`attachClipboardImage` in `src/tui/shell/prompt.ts` → `readClipboardImage` in
-`image-attachments.ts`).
-Cmd+V stays text (bracketed paste above). Clipboard image attach is
-macOS-only; Linux/Windows bitmap clipboard paste is not supported.
+`image-attachments.ts`, which reads through the OpenTUI clipboard service).
+Cmd+V stays text (bracketed paste above). The host clipboard backend reads
+PNG, JPEG, GIF, and WebP where the platform supports image clipboard data.
 `/paste-image` is the same attach path.
 
 @-mention path completion opens a popup keyed off the `@token` under the

src/tui/image-attachments.clipboard.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+
+import { readClipboardImage } from "./image-attachments.js";
+
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==",
+  "base64",
+);
+
+describe("readClipboardImage", () => {
+  test("turns clipboard image bytes into an attachment without a source path", async () => {
+    const result = await readClipboardImage(() =>
+      Promise.resolve({
+        ok: true,
+        mimeType: "image/png",
+        bytes: PNG,
+      }),
+    );
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.attachment.path).toBeUndefined();
+    expect(result.attachment.contentType).toBe("image/png");
+    expect(result.attachment.name.startsWith("clipboard-")).toBe(true);
+    expect(result.attachment.data.byteLength).toBeGreaterThan(0);
+  });
+
+  test("passes a clipboard miss through", async () => {
+    const result = await readClipboardImage(() =>
+      Promise.resolve({ ok: false, reason: "no image found on the clipboard" }),
+    );
+    expect(result).toEqual({
+      ok: false,
+      reason: "no image found on the clipboard",
+    });
+  });
+});

src/tui/image-attachments.ts

@@ -3,6 +3,10 @@ import { homedir, tmpdir } from "node:os";
 import { readFile, stat, unlink, writeFile } from "node:fs/promises";
 import { spawn } from "node:child_process";
 import type { MessageAttachment } from "@intx/types/runtime";
+import {
+  readSystemClipboardImage,
+  type ClipboardImageBytes,
+} from "./system-clipboard.js";
 
 export const MAX_IMAGE_ATTACHMENT_BYTES = 10 * 1024 * 1024;
 
@@ -335,48 +339,39 @@ function replaceExtension(name: string, contentType: string): string {
   return `${dot === -1 ? name : name.slice(0, dot)}.${ext}`;
 }
 
-export async function readClipboardImage(): Promise<ClipboardImageResult> {
-  if (process.platform !== "darwin") {
+export async function readClipboardImage(
+  source: () => Promise<ClipboardImageBytes> = readSystemClipboardImage,
+): Promise<ClipboardImageResult> {
+  const read = await source();
+  if (!read.ok) return read;
+
+  const ext = extensionForMime(read.mimeType);
+  const tmpPath = join(
+    tmpdir(),
+    `corbits-clipboard-${process.pid}-${Date.now()}.${ext}`,
+  );
+  try {
+    await writeFile(tmpPath, read.bytes);
+    const attachment = await imageAttachmentFromPath(tmpPath);
+    if (!attachment.ok) return attachment;
+    const { path: _path, ...clipboardAttachment } = attachment.attachment;
     return {
-      ok: false,
-      reason: "clipboard image paste is currently supported on macOS",
+      ok: true,
+      attachment: {
+        ...clipboardAttachment,
+        name: `clipboard-${new Date().toISOString().replace(/[:.]/g, "-")}.${ext}`,
+      },
     };
-  }
-
-  const tmpPath = `/tmp/corbits-clipboard-${process.pid}-${Date.now()}.png`;
-  const script = `
-set outPath to POSIX file ${JSON.stringify(tmpPath)}
-try
-  set pngData to the clipboard as «class PNGf»
-  set outFile to open for access outPath with write permission
-  set eof of outFile to 0
-  write pngData to outFile
-  close access outFile
-on error errMsg
-  try
-    close access outPath
-  end try
-  error errMsg
-end try
-`;
-
-  const result = await runProcess("osascript", ["-e", script]);
-  if (result.code !== 0) {
+  } catch {
+    return { ok: false, reason: "could not read an image from the clipboard" };
+  } finally {
     await unlink(tmpPath).catch(() => undefined);
-    return { ok: false, reason: "no PNG image found on the clipboard" };
   }
+}
 
-  const attachment = await imageAttachmentFromPath(tmpPath);
-  await unlink(tmpPath).catch(() => undefined);
-  if (!attachment.ok) return attachment;
-  const { path: _path, ...clipboardAttachment } = attachment.attachment;
-  return {
-    ok: true,
-    attachment: {
-      ...clipboardAttachment,
-      name: `clipboard-${new Date().toISOString().replace(/[:.]/g, "-")}.png`,
-    },
-  };
+function extensionForMime(mimeType: string): string {
+  if (mimeType === "image/jpeg") return "jpg";
+  return mimeType.split("/")[1] ?? "img";
 }
 
 export function formatAttachmentSummary(

src/tui/system-clipboard.test.ts

@@ -2,7 +2,10 @@ import { describe, expect, test } from "bun:test";
 import type { ClipboardService, ClipboardWriteResult } from "@opentui/core";
 import { withMockedModuleDuring } from "../../testkit/mock-module.js";
 
-import { createSystemClipboard } from "./system-clipboard.js";
+import {
+  createSystemClipboard,
+  readSystemClipboardImage,
+} from "./system-clipboard.js";
 
 const boundary = {
   capabilities: null,
@@ -88,4 +91,30 @@ describe("system clipboard", () => {
       createSystemClipboard(boundary, service).writeText("payload"),
     ).rejects.toThrow(/host: failed, terminal: local-failure/);
   });
+
+  test("reads an image representation from the clipboard service", async () => {
+    const bytes = new Uint8Array([1, 2, 3]);
+    const seen: string[][] = [];
+    const image = await readSystemClipboardImage({
+      read: (options) => {
+        seen.push([...options.preferredTypes]);
+        return Promise.resolve({
+          status: "read",
+          representation: { mimeType: "image/png", bytes },
+        });
+      },
+    });
+    expect(seen[0]).toContain("image/png");
+    expect(image).toEqual({ ok: true, mimeType: "image/png", bytes });
+  });
+
+  test("maps an empty clipboard read to a miss", async () => {
+    const image = await readSystemClipboardImage({
+      read: () => Promise.resolve({ status: "empty" }),
+    });
+    expect(image).toEqual({
+      ok: false,
+      reason: "no image found on the clipboard",
+    });
+  });
 });

src/tui/system-clipboard.ts

@@ -18,6 +18,56 @@ import {
 
 import type { ClipboardPort } from "./copy-path.js";
 
+const IMAGE_PREFERRED_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+] as const;
+
+export type ClipboardImageBytes =
+  | { readonly ok: true; readonly mimeType: string; readonly bytes: Uint8Array }
+  | { readonly ok: false; readonly reason: string };
+
+export async function readSystemClipboardImage(
+  service: Pick<ClipboardService, "read"> = createClipboard({
+    host: createHostClipboard(),
+    terminal: {
+      remote: false,
+      writeText: () => ({ status: "not-attempted", capability: "unsupported" }),
+      clear: () => ({ status: "not-attempted", capability: "unsupported" }),
+    },
+  }),
+): Promise<ClipboardImageBytes> {
+  const result = await service.read({
+    preferredTypes: IMAGE_PREFERRED_TYPES,
+  });
+  if (result.status === "read") {
+    const mimeType = result.representation.mimeType;
+    if (
+      !IMAGE_PREFERRED_TYPES.includes(
+        mimeType as (typeof IMAGE_PREFERRED_TYPES)[number],
+      )
+    ) {
+      return { ok: false, reason: "clipboard did not contain an image" };
+    }
+    return { ok: true, mimeType, bytes: result.representation.bytes };
+  }
+  if (result.status === "empty") {
+    return { ok: false, reason: "no image found on the clipboard" };
+  }
+  if (result.status === "unsupported") {
+    return {
+      ok: false,
+      reason: "clipboard image paste is not supported here",
+    };
+  }
+  if (result.status === "failed") {
+    return { ok: false, reason: result.error.message };
+  }
+  return { ok: false, reason: "could not read an image from the clipboard" };
+}
+
 export function createSystemClipboard(
   renderer: RendererClipboardBoundary,
   service: ClipboardService = createClipboard({