[iamnbutler]

Part of #3. desktop_insert can now paste an image or files through a temporary clipboard, with the same restore rules as text.

Request

• format: "image" with one absolute path (PNG, JPEG or TIFF, at most 10 MiB and 64 MP; original bytes and type are kept), or format: "files" with 1–32 absolute paths.
• No text or route in that form.
• Optional clipboard: "restore" (the default) or "replace".

Route, fixed before any input

• Guarded mode (restore) pastes only into a focused AXTextArea that meets both conditions:
  • its ancestry proves native text (TextInputRoute.resolve(container:) == .nativeAX, so not web content or Electron);
  • its complete text and selection can be read.
• Any other receiver is refused before the clipboard is touched, with PASTE_UNVERIFIABLE_RECEIVER. The hint offers clipboard: "replace", or desktop_clipboard_write followed by Command-V.

Observed consumption

• Expected edit: the selection is replaced by one U+FFFC per item, and the caret sits after them.
• If AXAttributedStringForRange marks any of those characters with AXAttachment, it must mark all of them (attachment_evidence: "attachment_attribute"). If it marks none, or can't be read, the replacement characters and caret decide ("replacement_characters"). A partly marked range does not count.
• After that, the text paste rules apply unchanged:
  • the reservation is taken before V goes down;
  • the edit is polled for 2 s, and when it appears the reservation is released and the clipboard restored (generation-checked);
  • otherwise the reservation is kept, and its proof re-runs on each later write.

clipboard: "replace"

• A claimed write that never reads or keeps the prior clipboard. Clipboard read permission isn't needed.
• No paste reservation is taken. Admission still refuses while another unresolved paste holds the gate.
• The same exact-target focus checks apply. When the text can't be read, only the exact focus is revalidated.
• clipboard_cleanup: "left_replaced". The result is completed only if the expected edit is observed; otherwise it is unknown with INSERTION_UNVERIFIED. The hint says to inspect before the next clipboard write, because a pending Command-V pastes whatever the clipboard holds then.

Native (peekaboo-attachment-insert.patch, appended last)

• insertLiteralText becomes one caller of pasteThroughClipboard(write, expectation, replace, …). Text insertion behaves exactly as before; its predicate is the attachments: 0 case.
• New attachmentInsert Bridge op (131 ops). It reuses the literal-insert response and descriptor.
• The snapshot, lease and receipt code moves into a shared handleGuardedPaste.
• ClipboardWriteRequest(fileURLs:) writes one public.file-url item per path through the claimed temporary write.
• ClipboardService.prepareReplacingWrite() is added.
• The native client gets the new fields, the allowlist entry, and the PASTE_UNVERIFIABLE_RECEIVER mapping. Its action input limit rises to 14 MiB, for image insertions only.

Docs: the tool description, the docs/tools.md row and paragraph (which links the Finder copy recipe), and the patches README entry.

Checks

• npm run check and npm test pass (56 tests, 4 new).
• The native build passes.
• Swift tests, foreground and isolated:
  • ClipboardAttachmentWriteTests: 3 new;
  • ClipboardTemporaryWriteTests, ClipboardWriteRequestTests, ClipboardReadAccessTests and ClipboardPasteTransactionGateTests;
  • PeekabooBridgeRequestPlanTests, PeekabooBridgeOperationSemanticPlanTests and PeekabooBridgeOperationResultSemanticsTests, with the counts at 131.
• Pending (screen locked): every live check, which also needs a dev host. Listed in Run the live checks deferred while the screen was locked #42.

Follow-up (not in this PR): pasting files into a Finder folder, with a host-side filesystem predicate. Until then, use desktop_clipboard_write with files, then Command-V.