@pi-archimedes/image-paste 2.10.4 → 2.11.1

package/README.md

@@ -25,7 +25,10 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 - **Markers on paste** — pasting inserts a visible `[Image #1]` placeholder at the cursor; each paste gets the next number.
 - **Attachment on submit** — when you send the message, your text is scanned for markers and the matching queued images are attached to it. Delete a marker and its image is not attached — the text is the source of truth.
 - **Inline preview** — a preview of the attached images is sent and rendered in the TUI. Previews appear where your terminal renders inline images; on a terminal that can't show them, the image is still attached — only the preview falls back.
+- **Same key, wider scope** — the paste key is Pi's own (`app.clipboard.pasteImage`), and taking it means covering everything it did, so with no image on the clipboard the handler falls back to what Pi does: copied **file paths** are inserted at the cursor with Pi's own spacing, and otherwise the clipboard **text** is inserted. One keypress produces one outcome, in that order: image, then paths, then text. Nothing on the clipboard leaves the draft untouched and says nothing, exactly as Pi does.
 - **Size guard** — 20 MiB **per image**, rejected with a clear message before it wastes context or hangs the submit.
+- **Bounded reads** — every clipboard read has a deadline (the same budget Pi gives its own clipboard commands), so a helper that stops answering — an X11/Wayland session that went unresponsive, say — reports `Clipboard paste failed: … timed out` instead of silently taking the paste key out of service for the rest of the session.
+- **Text stays text** — clipboard text is inserted as it is, with one exception: terminal escape bytes are dropped. The insert an extension has is a bracketed paste, so an escape byte coming from the clipboard would otherwise close the paste mid-string and swallow everything behind it.
 - **Model side** — the session's model must support images for the attachment to be usable.
 
 ## Paste shortcuts
@@ -37,13 +40,17 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 | Windows | `Alt+V`, `Ctrl+Alt+V` |
 
 > [!NOTE]
-> **Pi's built-in `app.clipboard.pasteImage` owns the table's first shortcut on every platform** — `Ctrl+V` on Linux/macOS, `Alt+V` on Windows — so the two conflict everywhere. When both fire on the shared key, the built-in throws warning banners (seen on Linux). Clear the built-in binding in `~/.pi/agent/keybindings.json` so the preview-enhanced handler takes the paste:
+> **Pi's built-in `app.clipboard.pasteImage` owns the table's first shortcut on every platform** — `Ctrl+V` on Linux/macOS, `Alt+V` on Windows — so the two collide everywhere. They do **not** both run: an extension shortcut wins over a built-in that is not on Pi's reserved list, so Pi reports one `[Extension issues]` line (`Extension shortcut conflict: 'ctrl+v' is built-in shortcut for app.clipboard.pasteImage and <ext>. Using <ext>`) and its own action never fires — measured on Pi 1.2.0, one `Ctrl+V`, one insertion, this extension's. Clear the built-in binding in `~/.pi/agent/keybindings.json` so the preview-enhanced handler takes the paste cleanly:
 >
 > ```json
-> { "app.clipboard.pasteImage": [] }
+> { "$schema": "https://pi.dev/schemas/keybindings.schema.json", "app.clipboard.pasteImage": [] }
 > ```
 >
-> **First-run offer (once ever, all platforms)** — when installed via the suite, on the first TUI session with image-paste enabled, if `~/.pi/agent/keybindings.json` doesn't exist yet, the suite offers to create it with exactly the snippet above: accepting creates the file and attempts an automatic reload where the runtime supports it (on current Pi 0.85.1 you're notified to run `/reload`, and the cleared binding applies once it runs), declining or cancelling (Esc) never asks again — re-open by deleting `archimedes.imagePaste.keybindingsPromptDone` from `~/.pi/agent/settings.json`.
+> The `$schema` line is optional — Pi skips that key when it loads the file — but it lets an editor validate the file against Pi's published keybindings schema, and it is exactly what the first-run offer below writes.
+>
+> **First-run offer (once ever, all platforms)** — when installed via the suite, on the first TUI session with image-paste enabled and with the suite going to hold the paste key (i.e. `suppressNativePaste` is not `false`), if `~/.pi/agent/keybindings.json` doesn't exist yet, the suite offers to create it with exactly the snippet above: accepting creates the file and then tells you to run `/reload` (measured on Pi 1.2.0, the context an event handler receives has no `reload`, so the automatic path is a notification and the cleared binding applies once you run it), declining or cancelling (Esc) never asks again — re-open by deleting `archimedes.imagePaste.keybindingsPromptDone` from `~/.pi/agent/settings.json`. With `suppressNativePaste: false` the offer never appears — an install that will not bind the key has nothing to unbind — and that way of skipping does not spend `keybindingsPromptDone`, so turning the flag back on still brings the offer.
+>
+> **Handing the key back to Pi** — `archimedes.imagePaste.suppressNativePaste: false` does two things, and both are needed: the package removes its own `app.clipboard.pasteImage` entry from `~/.pi/agent/keybindings.json` (that entry only, and only when the file holds nothing but it and this package's own `"$schema"` line — anything else is left byte-for-byte alone with a warning that names an entry only when the file really holds one), **and** it registers no paste shortcut at all. The second half is what makes the first one reachable: while a shortcut is registered Pi keeps it and its restored binding never runs. So with the flag off you get Pi's paste and lose this package's image attach, queue and preview on the paste key. `/new` or `/reload` applies a change to the setting — no restart. If the file could not be cleaned it is left exactly as it is and you get one warning naming it. What the key then does depends on the file: if it still carries `"app.clipboard.pasteImage": []` (or Pi's old name for that same action, `"pasteImage": []`, which Pi still reads as an unbinding), nothing answers the key until you delete that entry; if it does not — only `$schema`, other keys, or JSON that does not parse or cannot be read (Pi discards a file it cannot use and every action keeps its default) — Pi's own paste is already answering it. The warning names the file in every case, and the entry only where one is actually in there: a file of foreign keys, or a `$schema`-only file, is told there is nothing of ours to remove and nothing for it to edit, and a file that cannot be read or parsed is handed back to you to check, with Pi's fallback stated so you know what it is doing in the meantime.
 
 ## Per-platform requirements
 
@@ -58,6 +65,7 @@ New to Pi? Pi itself is a one-time global install and needs Node.js ≥ 22.19.0.
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `enabled` | bool | `true` | On/off for the extension, via `/plugins` (suite-managed) |
+| `suppressNativePaste` | bool | `true` | `false` gives the paste key back to Pi: the suite's `app.clipboard.pasteImage` entry is removed from `~/.pi/agent/keybindings.json` (only that entry, only if the file holds nothing else but the suite's own `"$schema"` line) **and** no paste shortcut is registered. It also keeps the first-run offer silent — there is nothing to unbind — without spending `keybindingsPromptDone`, so turning it back on still brings the offer. You get Pi's paste and lose image attach / queue / preview on those keys. Applies at the next `/new` or `/reload`. Anything that is not the strict boolean `false` — `"false"`, `0` — keeps the default. |
 | `keybindingsPromptDone` | bool | `false` | Set true once the first-run keybindings.json offer has been answered (accept or decline); delete to re-open the offer |
 
 In the suite on/off is managed by the suite: toggle via `/plugins` (`archimedes.imagePaste.enabled`, default on).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/image-paste",
-  "version": "2.10.4",
+  "version": "2.11.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"
@@ -19,15 +19,15 @@
     "./keybinding-offer": "./src/keybinding-offer.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.10.4"
+    "@pi-archimedes/core": "2.11.1"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.86.0",
     "@earendil-works/pi-tui": ">=0.86.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.87.0",
-    "@earendil-works/pi-tui": "^0.87.0",
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-tui": "1.2.0",
     "typescript": "^6.0.0"
   },
   "pi": {

package/src/clipboard.test.ts

@@ -28,7 +28,24 @@ vi.mock("node:child_process", async (importOriginal) => {
   };
 });
 
-import { readClipboardImage, readClipboardImageViaNativeModule } from "./clipboard.js";
+// A clipboard reader has no UI handle, and the console is not a surface: the
+// oversized-image report goes to the diagnostics sink (core/src/log.ts).
+const mockDiag = vi.hoisted(() => vi.fn());
+vi.mock("@pi-archimedes/core/log", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@pi-archimedes/core/log")>();
+  return { ...real, diag: mockDiag };
+});
+
+import {
+  buildPathInsertion,
+  clipboardTextForEditor,
+  isImageFilePath,
+  NATIVE_READ_TIMEOUT_MS,
+  readClipboardFilePaths,
+  readClipboardImage,
+  readClipboardImageViaNativeModule,
+  readClipboardText,
+} from "./clipboard.js";
 
 function createMockChildProcess(stdoutData = "", exitCode = 0) {
   const child = new EventEmitter() as any;
@@ -183,7 +200,7 @@ describe("readClipboardImage", () => {
       });
     });
 
-    it("logs a console.warn when PowerShell stdout exceeds MAX_BUFFER_BYTES", async () => {
+    it("diagnoses the log when PowerShell stdout exceeds MAX_BUFFER_BYTES", async () => {
       mockGetNativeClipboard.mockReturnValue(undefined);
       const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
 
@@ -200,9 +217,11 @@ describe("readClipboardImage", () => {
 
       const result = await readClipboardImage({ platform: "win32", environment: {} });
 
-      expect(warnSpy).toHaveBeenCalledWith(
+      expect(mockDiag).toHaveBeenCalledWith(
+        "image-paste",
         "[archimedes] Clipboard image exceeded maximum buffer size (50MB)",
       );
+      expect(warnSpy).not.toHaveBeenCalled();
       expect(result).toBeNull();
       warnSpy.mockRestore();
     });
@@ -309,3 +328,478 @@ describe("readClipboardImage", () => {
     });
   });
 });
+
+// ── File paths on the clipboard (pi's "paste files" branch) ─────────────────
+//
+// pi reads them with `getNativeClipboard()?.getFilePaths?.()`
+// (`dist/utils/clipboard.js:83-86`). The optional call is load-bearing for
+// this package: the peer floor is pi/pi-tui `>=0.86.0` and `getFilePaths` is
+// newer than that, and it is absent on the Linux helper even in 1.2.0
+// (measured on this machine: `typeof getNativeClipboard().getFilePaths ===
+// "undefined"`, `dist/native-platform.d.ts:8` declares it optional).
+
+describe("readClipboardFilePaths", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("returns the helper's paths verbatim", async () => {
+    mockGetNativeClipboard.mockReturnValue({ getFilePaths: vi.fn().mockResolvedValue(["/tmp/a.txt", "/tmp/b.txt"]) });
+
+    await expect(readClipboardFilePaths()).resolves.toEqual(["/tmp/a.txt", "/tmp/b.txt"]);
+  });
+
+  it("returns null on a helper without getFilePaths (the Linux 1.2.0 shape) instead of throwing", async () => {
+    mockGetNativeClipboard.mockReturnValue({});
+
+    await expect(readClipboardFilePaths()).resolves.toBeNull();
+  });
+
+  it("returns null when no clipboard helper loads at all", async () => {
+    mockGetNativeClipboard.mockReturnValue(undefined);
+
+    await expect(readClipboardFilePaths()).resolves.toBeNull();
+  });
+
+  it.each([[null], [undefined], [[]]])("normalises an empty file list (%p) to null", async (returnValue) => {
+    mockGetNativeClipboard.mockReturnValue({ getFilePaths: vi.fn().mockResolvedValue(returnValue) });
+
+    await expect(readClipboardFilePaths()).resolves.toBeNull();
+  });
+
+  it("lets a transfer failure reach the caller, as pi does", async () => {
+    mockGetNativeClipboard.mockReturnValue({
+      getFilePaths: vi.fn().mockRejectedValue(new Error("clipboard transfer failed")),
+    });
+
+    // pi does not catch here either — `handleClipboardPaste`'s own try/catch
+    // turns it into the failure notice, and so does ours.
+    await expect(readClipboardFilePaths()).rejects.toThrow("clipboard transfer failed");
+  });
+});
+
+// ── Clipboard text (pi's fallback branch) ──────────────────────────────────
+//
+// Mirrors `readClipboardText()` in pi's `dist/utils/clipboard.js:58-81`, which
+// is not reachable from a package (pi's exports are "." and "./rpc-entry";
+// `dist/index.d.ts:38` re-exports only `copyToClipboard`). The candidate order
+// is pi's and it is not decoration: on this Wayland machine the X11 helper
+// loads but every read fails on `Invalid MIT-MAGIC-COOKIE-1 key`, so a
+// native-first reader would lose text that `wl-paste` returns instantly.
+
+describe("readClipboardText", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  function textCommands(): string[] {
+    return mockSpawnSync.mock.calls.map((call) => String(call[0]));
+  }
+
+  it("reads Wayland text through wl-paste --no-newline --type text", async () => {
+    mockSpawnSync.mockImplementation((command: string) => ({
+      status: command === "wl-paste" ? 0 : 1,
+      stdout: Buffer.from("wayland text"),
+      error: undefined,
+    }));
+
+    const result = await readClipboardText({ platform: "linux", environment: { WAYLAND_DISPLAY: "wayland-0" } });
+
+    expect(mockSpawnSync.mock.calls[0]?.slice(0, 2)).toEqual(["wl-paste", ["--no-newline", "--type", "text"]]);
+    expect(result).toBe("wayland text");
+  });
+
+  it("tries xclip then xsel on X11, in pi's order", async () => {
+    mockSpawnSync.mockImplementation((command: string) => ({
+      status: command === "xclip" ? 1 : 0,
+      stdout: Buffer.from("xsel text"),
+      error: undefined,
+    }));
+
+    const result = await readClipboardText({ platform: "linux", environment: { DISPLAY: ":0" } });
+
+    expect(textCommands()).toEqual(["xclip", "xsel"]);
+    expect(mockSpawnSync.mock.calls[0]?.slice(0, 2)).toEqual(["xclip", ["-selection", "clipboard", "-out"]]);
+    expect(mockSpawnSync.mock.calls[1]?.slice(0, 2)).toEqual(["xsel", ["--clipboard", "--output"]]);
+    expect(result).toBe("xsel text");
+  });
+
+  it("prefers termux-clipboard-get under Termux", async () => {
+    mockSpawnSync.mockImplementation(() => ({ status: 0, stdout: Buffer.from("termux text"), error: undefined }));
+
+    const result = await readClipboardText({
+      platform: "android",
+      environment: { TERMUX_VERSION: "0.118.0" },
+    });
+
+    expect(textCommands()).toEqual(["termux-clipboard-get"]);
+    expect(result).toBe("termux text");
+  });
+
+  it("shells out nothing on macOS and reads through the native helper", async () => {
+    const getText = vi.fn().mockResolvedValue("native text");
+    mockGetNativeClipboard.mockReturnValue({ getText });
+
+    const result = await readClipboardText({ platform: "darwin", environment: {} });
+
+    expect(mockSpawnSync).not.toHaveBeenCalled();
+    expect(getText).toHaveBeenCalled();
+    expect(result).toBe("native text");
+  });
+
+  it("stops at a command that succeeded with empty output instead of falling through to the helper", async () => {
+    // pi returns `bytes.toString("utf8") || null` for the first command that
+    // ran cleanly: an empty text/plain is an answer, not a failure to retry
+    // somewhere else (an empty clipboard must stay empty).
+    mockSpawnSync.mockImplementation(() => ({ status: 0, stdout: Buffer.alloc(0), error: undefined }));
+    const getText = vi.fn().mockResolvedValue("stale native image text");
+    mockGetNativeClipboard.mockReturnValue({ getText });
+
+    const result = await readClipboardText({ platform: "linux", environment: { WAYLAND_DISPLAY: "wayland-0" } });
+
+    expect(result).toBeNull();
+    expect(getText).not.toHaveBeenCalled();
+  });
+
+  it("falls through a candidate that exited non-zero, then to the native helper", async () => {
+    mockSpawnSync.mockImplementation(() => ({ status: 1, stdout: Buffer.alloc(0), error: undefined }));
+    const getText = vi.fn().mockResolvedValue("native fallback");
+    mockGetNativeClipboard.mockReturnValue({ getText });
+
+    const result = await readClipboardText({ platform: "linux", environment: { DISPLAY: ":0" } });
+
+    expect(textCommands()).toEqual(["xclip", "xsel"]);
+    expect(result).toBe("native fallback");
+  });
+
+  it("falls through a missing command (ENOENT) rather than reporting empty text", async () => {
+    mockSpawnSync.mockImplementation(() => ({
+      status: null,
+      stdout: Buffer.alloc(0),
+      error: Object.assign(new Error("spawn xclip ENOENT"), { code: "ENOENT" }),
+    }));
+    const getText = vi.fn().mockResolvedValue("native fallback");
+    mockGetNativeClipboard.mockReturnValue({ getText });
+
+    const result = await readClipboardText({ platform: "linux", environment: { DISPLAY: ":0" } });
+
+    expect(textCommands()).toEqual(["xclip", "xsel"]);
+    expect(result).toBe("native fallback");
+  });
+
+  it("returns null when the native helper has no text, is absent, or throws", async () => {
+    mockGetNativeClipboard.mockReturnValue({ getText: vi.fn().mockResolvedValue(null) });
+    await expect(readClipboardText({ platform: "darwin", environment: {} })).resolves.toBeNull();
+
+    mockGetNativeClipboard.mockReturnValue({ getText: vi.fn().mockRejectedValue(new Error("no display")) });
+    await expect(readClipboardText({ platform: "darwin", environment: {} })).resolves.toBeNull();
+
+    mockGetNativeClipboard.mockReturnValue(undefined);
+    await expect(readClipboardText({ platform: "darwin", environment: {} })).resolves.toBeNull();
+  });
+
+  it("treats an empty string from the native helper as no text", async () => {
+    mockGetNativeClipboard.mockReturnValue({ getText: vi.fn().mockResolvedValue("") });
+
+    await expect(readClipboardText({ platform: "darwin", environment: {} })).resolves.toBeNull();
+  });
+});
+
+// ── pi's path-insertion spacing rule, mirrored ─────────────────────────────
+//
+// Quoted from pi 1.2.0 `dist/modes/interactive/interactive-mode.js`:
+//
+//   2504  const paths = this.isBashMode ? filePaths.map(quoteIfNeeded).join(" ") : filePaths.join("\n");
+//   2505  const cursor = this.editor.getCursor?.();
+//   2506  const currentLine = cursor ? (this.editor.getText().split("\n")[cursor.line] ?? "") : "";
+//   2507  const characterBeforeCursor = cursor && cursor.col > 0 ? currentLine[cursor.col - 1] : "";
+//   2508  const characterAfterCursor = cursor ? currentLine[cursor.col] : "";
+//   2509  const leadingSpace = characterBeforeCursor && !/\s/.test(characterBeforeCursor) ? " " : "";
+//   2510  const trailingSpace = characterAfterCursor && !/\s/.test(characterAfterCursor) ? " " : "";
+//   2511  this.editor.insertTextAtCursor?.(`${leadingSpace}${paths}${trailingSpace}`);
+//
+// `buildPathInsertion` is that block, with the editor read replaced by
+// arguments so it can be asserted per case. `applyPathInsertion` in the test
+// is the `insertTextAtCursor` half: text before the cursor + insertion + text
+// after it.
+
+function applyPathInsertion(editorText: string, insertion: string, cursor: { line: number; col: number }): string {
+  const lines = editorText.split("\n");
+  const line = lines[cursor.line] ?? "";
+  lines[cursor.line] = line.slice(0, cursor.col) + insertion + line.slice(cursor.col);
+  return lines.join("\n");
+}
+
+const endOf = (editorText: string): { line: number; col: number } => {
+  const lines = editorText.split("\n");
+  return { line: lines.length - 1, col: lines[lines.length - 1]!.length };
+};
+
+describe("isImageFilePath", () => {
+  // The predicate a "should this path be read as an image?" decision would
+  // make. Its first caller is a test (see the no-double-attach case in
+  // paste-dispatch.test.ts), because the dispatch deliberately never reads an
+  // image off disk — but the check still has to answer correctly, and once did
+  // not: the extension set is dotted (".png") while `split(".").pop()` returns
+  // the extension bare ("png"), so every path came back false.
+  it.each([["/tmp/screenshot.png"], ["/tmp/Photo.JPG"], ["./capture.jpeg"], ["image.gif"]])(
+    "recognises %s", (filePath) => {
+      expect(isImageFilePath(filePath)).toBe(true);
+    },
+  );
+
+  it.each([["/tmp/report.pdf"], ["/tmp/script.ts"], ["/tmp/no-extension"], ["archive.tar"]])(
+    "rejects %s",
+    (filePath) => {
+      expect(isImageFilePath(filePath)).toBe(false);
+    },
+  );
+});
+
+describe("native clipboard reads are bounded, so ctrl+v cannot hang", () => {
+  // The pi clipboard contract has no deadline: `getImage`/`getText`/`getFilePaths`
+  // are plain promises, and an unresponsive X11/Wayland session blocks inside
+  // the native call. The shortcut handler holds a `_pasting` mutex for the
+  // lifetime of a dispatch, so one read that never settles makes every later
+  // `ctrl+v` a silent no-op for the rest of the session — a dead key, with
+  // nothing on screen to explain it. Every native read therefore carries the
+  // same budget as one CLI read (`READ_TIMEOUT_MS`), which is what these
+  // promises are measured against.
+  const neverSettles = <T>(): Promise<T> => new Promise<T>(() => {});
+  const missingCLITools = (): void => {
+    mockSpawnSync.mockImplementation(() => ({
+      status: null,
+      stdout: Buffer.alloc(0),
+      error: Object.assign(new Error("spawnSync ENOENT"), { code: "ENOENT" }),
+    }));
+  };
+
+  it("readClipboardImage rejects with a timeout rather than hanging on a silent helper", async () => {
+    vi.useFakeTimers();
+    try {
+      missingCLITools();
+      mockGetNativeClipboard.mockReturnValue({ getImage: neverSettles });
+      const read = readClipboardImage({
+        platform: "linux",
+        environment: { WAYLAND_DISPLAY: "wayland-0" },
+      });
+      const outcome = read.then(
+        () => "resolved",
+        (error: unknown) => (error instanceof Error ? error.message : String(error)),
+      );
+
+      // Not a hair-trigger: a slow-but-living helper is not cut off early.
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS / 2);
+      await expect(Promise.race([outcome, Promise.resolve("still running")])).resolves.toBe(
+        "still running",
+      );
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS);
+      await expect(outcome).resolves.toMatch(/timed out/i);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("readClipboardFilePaths falls through to the next branch when the helper never answers", async () => {
+    vi.useFakeTimers();
+    try {
+      mockGetNativeClipboard.mockReturnValue({ getFilePaths: neverSettles });
+      const read = readClipboardFilePaths();
+      let settled = false;
+      const outcome = read.then((paths) => {
+        settled = true;
+        return paths;
+      });
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS / 2);
+      expect(settled).toBe(false);
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS);
+      // `null`, not a rejection: a hung file-path read must not cost the user
+      // the text that is also on the clipboard.
+      await expect(outcome).resolves.toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("readClipboardText reads no text when the helper never answers", async () => {
+    vi.useFakeTimers();
+    try {
+      // No CLI candidates on this platform, so the helper is the only reader.
+      mockGetNativeClipboard.mockReturnValue({ getText: neverSettles });
+      const read = readClipboardText({ platform: "darwin", environment: {} });
+      let settled = false;
+      const outcome = read.then((text) => {
+        settled = true;
+        return text;
+      });
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS / 2);
+      expect(settled).toBe(false);
+
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS);
+      await expect(outcome).resolves.toBeNull();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("still returns bytes that arrive inside the deadline", async () => {
+    vi.useFakeTimers();
+    try {
+      missingCLITools();
+      mockGetNativeClipboard.mockReturnValue({
+        getImage: () => {
+          return new Promise<Uint8Array>((resolve) => {
+            setTimeout(() => resolve(new Uint8Array([9, 8, 7])), 100);
+          });
+        },
+      });
+      const read = readClipboardImage({
+        platform: "linux",
+        environment: { WAYLAND_DISPLAY: "wayland-0" },
+      });
+      await vi.advanceTimersByTimeAsync(200);
+      await expect(read).resolves.toEqual({ bytes: new Uint8Array([9, 8, 7]), mimeType: "image/png" });
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+  it("still gives PowerShell a turn when the native helper hangs (win32)", async () => {
+    vi.useFakeTimers();
+    try {
+      mockGetNativeClipboard.mockReturnValue({ getImage: neverSettles });
+      // PowerShell answers "no image" (non-zero exit / empty stdout).
+      mockSpawn.mockImplementation(() => createMockChildProcess("", 1));
+
+      const read = readClipboardImage({ platform: "win32", environment: {} });
+      await vi.advanceTimersByTimeAsync(NATIVE_READ_TIMEOUT_MS + 50);
+
+      // The timeout must not short-circuit the platform fallback: an answer
+      // from PowerShell is an answer, so the read resolves quietly instead of
+      // reporting the hung native helper.
+      await expect(read).resolves.toBeNull();
+      expect(mockSpawn).toHaveBeenCalled();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});
+
+describe("clipboardTextForEditor: what may go through pasteToEditor", () => {
+  // `ctx.ui.pasteToEditor` is a bracketed paste (interactive-mode.js:2075), so
+  // the paste framing is the one thing clipboard content must not carry: pi-tui
+  // ends the paste at the first `\x1b[201~` (components/editor.js:576-587) and
+  // the rest of the clipboard is lost. Measured end-to-end in
+  // paste-dispatch.test.ts; this is the pure rule.
+  it("drops the escape byte that would close the paste early, keeping the rest", () => {
+    expect(clipboardTextForEditor("hi\u001b[201~!echo pwned\r")).toBe("hi[201~!echo pwned\r");
+  });
+
+  it("drops a bare escape byte and leaves every other character alone", () => {
+    expect(clipboardTextForEditor("hi\u001b[31mred")).toBe("hi[31mred");
+  });
+
+  it("returns ordinary text (including newlines and tabs) untouched", () => {
+    const ordinary = "two lines\nand a\ttab, a NUL \u0000 and a trailing newline\n";
+    expect(clipboardTextForEditor(ordinary)).toBe(ordinary);
+  });
+});
+
+describe("buildPathInsertion: pi's spacing rule (interactive-mode.js:2504-2511)", () => {
+  it("empty editor: the path alone, no padding", () => {
+    const insertion = buildPathInsertion(["/tmp/a.txt"], "");
+
+    expect(insertion).toBe("/tmp/a.txt");
+    expect(applyPathInsertion("", insertion, endOf(""))).toBe("/tmp/a.txt");
+  });
+
+  it("draft ending in a word: one leading space, no trailing space", () => {
+    const insertion = buildPathInsertion(["/tmp/a.txt"], "look at");
+
+    expect(insertion).toBe(" /tmp/a.txt");
+    expect(applyPathInsertion("look at", insertion, endOf("look at"))).toBe("look at /tmp/a.txt");
+  });
+
+  it("draft ending in a newline: no padding at all (the cursor is on an empty line)", () => {
+    const insertion = buildPathInsertion(["/tmp/a.txt"], "look at\n");
+
+    expect(insertion).toBe("/tmp/a.txt");
+    expect(applyPathInsertion("look at\n", insertion, endOf("look at\n"))).toBe("look at\n/tmp/a.txt");
+  });
+
+  it("cursor mid-line between word characters: spaces on both sides", () => {
+    const editorText = "alpha";
+    const cursor = { line: 0, col: 4 };
+
+    const insertion = buildPathInsertion(["/tmp/a.txt"], editorText, cursor);
+
+    expect(insertion).toBe(" /tmp/a.txt ");
+    expect(applyPathInsertion(editorText, insertion, cursor)).toBe("alph /tmp/a.txt a");
+  });
+
+  it("cursor after a space and before a word: no leading space, trailing space kept", () => {
+    const editorText = "a b";
+    const cursor = { line: 0, col: 2 };
+
+    expect(buildPathInsertion(["/tmp/a.txt"], editorText, cursor)).toBe("/tmp/a.txt ");
+  });
+
+  it("cursor at the start of a line whose predecessor ends in a word: no leading space (the rule is per line)", () => {
+    const editorText = "one\ntwo";
+    const cursor = { line: 1, col: 0 };
+
+    // No leading space: the character before the cursor is *nothing on this
+    // line*, not the 'e' on the line above — pi reads currentLine, not the
+    // whole text (:2506-2507). The trailing space does appear, because the
+    // text after the cursor on this line ('t') is not whitespace (:2510).
+    expect(buildPathInsertion(["/tmp/a.txt"], editorText, cursor)).toBe("/tmp/a.txt ");
+    expect(applyPathInsertion(editorText, buildPathInsertion(["/tmp/a.txt"], editorText, cursor), cursor)).toBe(
+      "one\n/tmp/a.txt two",
+    );
+  });
+
+  it("multi-path clipboard: newline-joined inside one pair of spaces", () => {
+    const editorText = "compare";
+    const cursor = { line: 0, col: 3 };
+
+    const insertion = buildPathInsertion(["/tmp/one.txt", "/tmp/two.txt"], editorText, cursor);
+
+    expect(insertion).toBe(" /tmp/one.txt\n/tmp/two.txt ");
+    expect(applyPathInsertion(editorText, insertion, cursor)).toBe("com /tmp/one.txt\n/tmp/two.txt pare");
+  });
+
+  it("bash draft: shell-quoted paths joined with spaces (pi's isBashMode branch)", () => {
+    const editorText = "!ls ";
+
+    // interactive-mode.js:2504 — `filePaths.map(quoteIfNeeded).join(" ")`, and
+    // pi's isBashMode is the draft's `!` prefix (:2470).
+    expect(buildPathInsertion(["/tmp/a file.txt", "/tmp/plain.txt"], editorText)).toBe(
+      "'/tmp/a file.txt' /tmp/plain.txt",
+    );
+  });
+
+  it("bash draft escapes an embedded single quote exactly as quoteIfNeeded does", () => {
+    // interactive-mode.js:170 — `'${value.replace(/'/g, `'\\''`)}'`: every '
+    // becomes '\'' and the whole thing is wrapped in single quotes.
+    expect(buildPathInsertion(["'/q'"], "!echo ")).toBe("''\\''/q'\\'''");
+  });
+
+  it("bash draft quotes an empty path and leaves safe characters bare", () => {
+    // quoteIfNeeded requires length > 0 to skip quoting, so "" becomes ''.
+    expect(buildPathInsertion([""], "!echo ")).toBe("''");
+    expect(buildPathInsertion(["a-zA-Z0-9_-.@~:/"], "!echo ")).toBe("a-zA-Z0-9_-.@~:/");
+  });
+
+  it("defaults to the end of the draft, which is all the extension API can observe", () => {
+    const editorText = "one\ntwo";
+
+    // Same answer as asking for the end-of-text cursor explicitly: pi's rule
+    // applied at the only position ctx.ui exposes (no cursor accessor exists).
+    expect(buildPathInsertion(["/tmp/a.txt"], editorText)).toBe(
+      buildPathInsertion(["/tmp/a.txt"], editorText, endOf(editorText)),
+    );
+  });
+});