From 630916d87337636a9e717653e9c97de3dff1102e Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Thu, 27 Aug 2026 12:54:37 -0500
Subject: [PATCH 1/4] Design doc for clipboard image paste in Monaco source
 editor (bd-706b0ixu)

Design exploration + decision log for pasting images from the clipboard
into the hub-client source editor: clipboard format landscape, Monaco
pass-through behavior (verified against monaco 0.55.1 sources), SVG
security analysis, filename/concurrency scheme (content-hash names to
sidestep index-map LWW races), and scoped v1 rules. Follow-ups filed:
bd-yspyic32 (mixed payloads), bd-myoj9kp5 (SVG posture).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bs2YW5vUbm1krBkQicB5nr
---
 .../plans/2026-08-27-paste-image-clipboard.md | 404 ++++++++++++++++++
 1 file changed, 404 insertions(+)
 create mode 100644 claude-notes/plans/2026-08-27-paste-image-clipboard.md

diff --git a/claude-notes/plans/2026-08-27-paste-image-clipboard.md b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
new file mode 100644
index 000000000..3b69849c7
--- /dev/null
+++ b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
@@ -0,0 +1,404 @@
+# Paste images from clipboard into the Monaco source editor
+
+**Braid strand:** bd-706b0ixu
+**Created:** 2026-08-27
+**Status:** Approved — executing (design decisions resolved 2026-08-27)
+**Follow-up strands:** bd-yspyic32 (mixed text+image payloads), bd-myoj9kp5
+(pipeline-wide SVG posture)
+
+## Decision log (2026-08-27, user-approved)
+
+1. **Precedence:** v1 uses the simple file-only rule (§2a, as refined
+   below): take over iff the payload's files are all accepted raster
+   images **and** `text/plain` is empty or is just the filename rider.
+   Payloads with meaningful text (Office, Excel/Sheets) paste as text;
+   offering their image rendition is bd-yspyic32.
+2. **Filename:** `pasted-<hash8>.<ext>` (8-char SHA-256 prefix).
+3. **Destination:** P1 — same directory as the current document.
+4. **SVG:** S1 confirmed — raster-only paste; SVG stays dialog-only.
+   Pipeline-wide SVG decision filed as bd-myoj9kp5.
+5. **Multi-file separator:** spaces (indentation-sensitive contexts rule
+   out newlines; see §D4).
+6. **Declined file-only pastes:** keep status quo (Monaco inserts the
+   filename as text); revisit after real-world usage.
+
+## Overview
+
+Add clipboard-paste support for images in the hub-client source editor
+(Monaco), analogous to the existing drag-and-drop flow but with one key UX
+difference: **no dialog**. On paste we automatically pick a filename, create
+the binary file in the project, and insert a markdown image reference at the
+cursor, so the image shows up in the rendered preview as soon as the paste is
+processed. Because there is no user-chosen filename, the scheme must be safe
+against another peer *concurrently* pasting an image into the same CRDT
+session.
+
+This document covers: (1) what the existing code gives us, (2) a primer on
+how clipboard images actually arrive in JavaScript, (3) the security
+analysis (SVG in particular), and (4) the design options with a
+recommendation.
+
+## 1. What already exists (survey of current code)
+
+The drag-and-drop feature (plan: `2026-01-10-monaco-image-drag-drop.md`,
+generic uploader: `2026-04-21-generic-file-uploader.md`) built almost all the
+machinery we need:
+
+- **`Editor.tsx`** (`hub-client/src/components/Editor.tsx:814-965`)
+  - `handleEditorDrop` attaches to the Monaco container's DOM node,
+    distinguishes internal sidebar drags (`application/x-hub-file`) from
+    external file drops, stashes the drop position in
+    `pendingDropPositionRef`, and routes external files to `NewAssetDialog`.
+  - `handleUploadAsset` runs `processFileForUpload` → `createBinaryFile`,
+    then inserts markdown at the pending position via
+    `editorRef.current.executeEdits(...)`. Monaco's `onChange` fires
+    synchronously from `executeEdits` and propagates to the CRDT via the
+    splice path — so text insertion needs no extra sync work.
+  - The editor sets `pasteAs: { enabled: false }` in Monaco options
+    (quarto-dev/kyoto#3) — this disables Monaco's paste-as *widget* for text
+    pastes; it does not conflict with a DOM-level paste listener.
+- **`fileUpload/dropMarkdown.ts`** — `buildDropMarkdown('image',
+  currentFilePath, targetPath)` produces `![](href)` with the target
+  correctly relativized against the containing document (bd-jzqswvh0).
+- **`fileUpload/resolveDefaultDestination.ts`** — destination defaults to
+  the current file's parent folder.
+- **`services/resourceService.ts`** — `computeSHA256`, `getHashPrefix`,
+  `generateHashedFilename` ("diagram.png" → "diagram-a1b2c3d4.png"),
+  `sanitizeFilename`, `processFileForUpload` (reads bytes, hashes, resolves
+  MIME from `file.type` falling back to extension), and
+  `FILE_SIZE_LIMITS.MAX_FILE_SIZE` (10 MB).
+- **`quarto-sync-client/src/client.ts:1278` — `createBinaryFile(path,
+  content, mimeType)`** — the CRDT write. Already conflict-aware, per-client:
+  - If `path` exists **with the same SHA-256** → returns
+    `{ deduplicated: true }` and creates nothing.
+  - If `path` exists **with different content** → renames to
+    `name-<hash8>.ext` and creates a new doc.
+  - Then sets `doc.files[path] = docId` in the index document (an Automerge
+    map — concurrent writes to the *same key* resolve last-writer-wins).
+- **Preview side** (`ts-packages/preview-renderer`): `assetWalker.ts` mints
+  blob URLs for project-relative image targets; `inlines/Image.tsx` renders
+  them as `<img src={blobUrl}>` inside the preview iframe
+  (`sandbox="allow-scripts allow-same-origin"`). The asset manifest updates
+  reactively when files are added, so a newly created binary file becomes
+  visible in the preview as soon as the AST references it.
+
+**Notable pre-existing fact:** the drop path already accepts SVG — every
+image check is `file.type.startsWith('image/')`, and `image/svg+xml`
+matches. So paste does not *introduce* the SVG question; it inherits it (see
+§3).
+
+## 2. Clipboard images in JavaScript: formats and APIs
+
+There are two browser APIs; only one is right for this feature.
+
+### 2a. The `paste` event (`ClipboardEvent.clipboardData`) — the right one
+
+Fires on the focused element when the user presses Cmd/Ctrl-V. Synchronous,
+no permission prompt, and hands us a `DataTransfer` — the same interface the
+drop handler already consumes (`items`, `files`, `types`, `getData`). In
+Monaco, the event target is the hidden `<textarea>` (`inputarea`) inside the
+editor DOM node, so a **capture-phase listener on
+`editor.getDomNode()`** sees it before Monaco does and can
+`preventDefault()` + `stopPropagation()` when we take over.
+
+What actually arrives, by source of the copy:
+
+| User action | `clipboardData` contents |
+|---|---|
+| OS screenshot to clipboard; "copy" in an image editor; Chrome "Copy image" on a web page | A file item of type **`image/png`** (browsers re-encode bitmap clipboard content to PNG), usually alongside a `text/html` string (`<img src="...">`) |
+| Copy a *file* in the OS file manager (Finder, Explorer) | The file itself in `clipboardData.files`, with its **real MIME type**: `image/svg+xml`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`, `application/pdf`, … Often *also* a `text/plain` item carrying the filename — this is why an unhandled file paste inserts stray filename text into the editor |
+| Copy from Office/Google Docs | `text/html` + `text/rtf` + usually an `image/png` rendition |
+| Copy SVG *markup* from a text editor | Plain `text/plain` — an ordinary text paste; not our concern (equivalent to typing it) |
+
+Practical consequences:
+
+- **PNG is the lingua franca.** Every "copied pixels" source arrives as
+  `image/png`. This is the dominant use case (screenshots).
+- **Non-PNG raster and SVG arrive only via file-copy paste**, with correct
+  MIME types on the `File` objects.
+- **Mixed payloads need a precedence rule.** When both text and an image
+  file are present (Office copy), pasting the image is usually wrong —
+  the user expects their text. Rule of thumb (matches VS Code's behavior):
+  if `clipboardData` contains a non-empty `text/plain` item **and** the
+  source also provided `text/html`, treat it as a text paste; take over
+  only when the payload is file-only, or when the only text is the
+  filename that rides along with a file copy (detectable: file present +
+  text equals the file's name). **Decided v1 rule: take over iff
+  `clipboardData.files` is non-empty, every file is an accepted raster
+  image type, and the `text/plain` item is empty or is merely the
+  filename rider (equals a pasted file's name, or the newline-joined
+  names); else let Monaco handle it.** The text guard matters: Excel /
+  Sheets cell copies carry an `image/png` rendition of the cells *plus*
+  the `text/plain` TSV — without the guard, pasting cells would insert a
+  screenshot of them. (Chrome's "Copy image" case includes `text/html`
+  but *no* `text/plain`, so it still routes to us.) Offering the image
+  rendition of mixed payloads is follow-up bd-yspyic32.
+
+### 2b. The async Clipboard API (`navigator.clipboard.read()`) — not needed
+
+Requires a permissions prompt and a user gesture, and Chromium supports
+reading only `text/plain`, `text/html`, and `image/png` (images are
+sanitized/transcoded to PNG). It's the right tool for a toolbar "Paste
+image" *button* (no paste event available), but unnecessary for Cmd-V. Not
+proposed for v1; noted as the extension point if we ever add a button.
+
+### 2c. Monaco-native hooks — insufficient
+
+- `editor.onDidPaste` fires only after a **text** paste lands; no file
+  access. Useful for nothing here.
+- VS Code's `DocumentPasteEditProvider` (how vscode itself does
+  paste-image-into-markdown) is **not exposed in monaco-editor 0.55.1's
+  public API** (verified against `editor.api.d.ts` — no `DocumentPaste` /
+  `PasteEdit` symbols). So the DOM listener is the only viable
+  interception point, mirroring how the drop feature already works.
+
+### 2d. What Monaco does when we pass through (verified, monaco 0.55.1)
+
+Read from the shipped sources (`esm/vs/editor/browser/controller/editContext/
+clipboardUtils.js`, `.../textArea/textAreaEditContextInput.js`):
+
+- Monaco's own paste handler on the hidden textarea calls
+  `e.preventDefault()` unconditionally and re-implements insertion. It
+  reads **only** `text/plain` and its private `vscode-editor-data` JSON
+  flavor (copy metadata: language mode, multicursor segments,
+  empty-selection flag). `text/html`, `text/rtf`, and file *contents* are
+  never read.
+- **Filename fallback:** if `text/plain` is empty, there is no
+  vscode metadata, and `clipboardData.files` is non-empty, Monaco inserts
+  the file **names** joined by newlines (`clipboardUtils.js:69-73`). So
+  today a Finder-copied `diagram.svg` pastes the text `diagram.svg`, and a
+  screenshot pastes something like `image.png`. Not a no-op.
+- If text is still empty and there are no files: early return, nothing
+  happens.
+- Matching self-copied text restores multicursor/paste-on-new-line
+  behavior via an in-memory store; irrelevant for external payloads.
+- The `dropOrPasteInto`/`pasteAs` contribution (VS Code's "Paste As..."
+  provider machinery) is disabled in this codebase (`pasteAs: { enabled:
+  false }`, kyoto#3), so none of its built-in providers run.
+
+Implications: the Office mixed payload passes through to exactly the right
+outcome (text inserted, PNG rendition ignored). But a *declined* file-only
+paste (e.g. an unsupported `image/tiff`, or a PDF) falls through to
+filename-text insertion — today's behavior, but worth deciding whether a
+toast would serve better (see open question 6).
+
+## 3. Security analysis
+
+### 3a. Is SVG an "image" here, and what can it do?
+
+Yes — `image/svg+xml` satisfies every `startsWith('image/')` check in the
+current code, and `inferMimeType`/`guessMimeType` map `.svg` to it. An SVG
+can contain `<script>`, event handlers (`onload=`), `<foreignObject>` with
+arbitrary HTML, and external references. Whether any of that *executes*
+depends entirely on the embedding context:
+
+| Context | Scripts execute? |
+|---|---|
+| `<img src="x.svg">`, CSS `background-image` | **No.** Browsers render SVG-as-image in "secure static mode": no scripts, no external loads, no interactivity. |
+| `<object>`, `<embed>`, `<iframe>` pointing at the SVG | Yes. |
+| **Navigating directly to the SVG URL** (e.g. right-click → "Open image in new tab") | Yes — it becomes an SVG *document*, and scripts run with the URL's origin. |
+| Inlining the SVG markup into the DOM | Yes. |
+
+### 3b. Where pasted-SVG bytes could execute in *our* pipeline
+
+1. **Hub preview:** `Image.tsx` renders `<img src={blobUrl}>` — safe in
+   situ. But the blob URL is minted by `URL.createObjectURL` **in the
+   parent hub-client context**, so its origin is the hub-client origin. A
+   user who opens that blob URL directly gets a script-capable SVG
+   document running on the hub origin. Caveat on severity: the attacker
+   here is a *collaborator with write access to the project*, who can
+   already put raw HTML blocks into a qmd document that the preview
+   renders — so pasted SVG does not obviously cross a trust boundary the
+   collaborative editor hasn't already crossed. Worth a deliberate
+   decision, not an accident.
+2. **Rendered/published site (`q2 render`):** the SVG is copied verbatim
+   into the output and served by whatever hosts the site as
+   `image/svg+xml`. `![](x.svg)` becomes `<img>` (safe), but anyone
+   navigating to `https://site/x.svg` directly executes its scripts on the
+   site's origin. This is the standard static-site-generator posture
+   (same as committing an SVG to any repo and publishing it) — not
+   something the paste feature can or should solve globally.
+3. **Hub HTTP endpoints:** if the hub server ever serves raw project files
+   over HTTP (downloads, published previews), SVG responses should carry
+   `Content-Security-Policy: sandbox` and/or `Content-Disposition:
+   attachment` — the industry-standard mitigation (GitHub serves user SVGs
+   from a sandboxed domain with CSP). Out of scope for this feature but
+   should be recorded as a hub-server follow-up strand if such an endpoint
+   exists or appears.
+
+### 3c. Policy options for pasted SVG
+
+- **(S1) Raster-only paste allowlist** — accept `image/png`, `image/jpeg`,
+  `image/gif`, `image/webp` (optionally `image/avif`) on the *paste* path;
+  any other file type falls through to the existing asset-dialog flow (or
+  is ignored with a toast). SVG thus stays available via the deliberate,
+  visible upload/drop dialog — exactly the status quo — while the
+  *silent, no-dialog* path never ingests active content. Zero new
+  dependencies, zero lossy transforms.
+- **(S2) Sanitize SVG on paste** (DOMPurify with SVG profile) — keeps
+  vector pastes working but adds a dependency, and sanitizers are a
+  moving target; also mutating the user's bytes silently is surprising
+  (hash changes, diffs against the original file).
+- **(S3) Rasterize SVG on paste** (draw to canvas, export PNG) — silently
+  destroys vector quality; worst option for a Quarto audience.
+- **(S4) Accept SVG as-is on paste** — consistent with drag-and-drop
+  today, but expands the silent path to active content.
+
+**Recommendation: S1.** It is the smallest surface, matches the "paste =
+screenshot" dominant use case (which is always PNG), and doesn't regress any
+current capability — SVG ingestion remains available where it is today, in
+the dialog flows. Separately, file a strand to make the *deliberate* SVG
+decision for the whole upload pipeline (preview blob-URL origin, future hub
+serving endpoints), since that pre-exists this feature.
+
+Two non-issues worth recording: (a) pasting SVG *markup* as text is an
+ordinary text edit, indistinguishable from typing it; (b) browser clipboard
+bitmap sanitization means we never receive raw platform bitmap formats —
+the browser hands us well-formed PNG.
+
+## 4. Design decisions and options
+
+### D1. Interception point
+
+DOM `paste` listener, **capture phase**, on `editor.getDomNode()` —
+registered/removed exactly where the drag-drop listeners already are
+(`Editor.tsx` mount effect + the existing cleanup effect). Handler logic:
+
+```
+on paste(e):
+  files = imagesOnly(e.clipboardData)        # per §2a precedence rule
+  if files is empty: return                  # Monaco handles text normally
+  e.preventDefault(); e.stopPropagation()    # stop filename-text insertion
+  for each file: ingest(file)                # §D2–D5
+```
+
+### D2. Filename scheme (the no-dialog core decision)
+
+Requirements: automatic, collision-safe against concurrent peers, stable
+enough that repeat-pastes of the same content don't proliferate files.
+
+- **(F1) Content-hash name: `pasted-<hash8>.<ext>`** (ext from MIME).
+  - Concurrent pastes of *different* images by two peers → different
+    hashes → **different index keys → no CRDT conflict at all**. This is
+    the crucial property: `createBinaryFile`'s existence check is
+    check-then-act on the *local* replica, so two peers concurrently
+    claiming the same path with different content would race to
+    last-writer-wins on the index map key and one image would silently
+    vanish. Distinct names sidestep LWW entirely.
+  - Concurrent pastes of the *same* image → same name, same content; LWW
+    picks one docId, both peers' markdown references resolve to identical
+    bytes. The losing doc is orphaned (unreferenced in the index) —
+    harmless. Sequentially, the dedup branch already returns
+    `deduplicated: true` and creates nothing.
+  - Repeat paste of the same screenshot by one user → dedup, single file.
+  - Uses `computeSHA256` we already run in `processFileForUpload` — the
+    hash is computed anyway; no extra cost.
+- **(F2) UUID name: `pasted-<uuid>.png`** — collision-safe but every
+  repeat paste creates a new file, and names carry no dedup value.
+- **(F3) Timestamp name: `pasted-2026-08-27-140312.png`** — human-friendly
+  but *not* collision-safe (two peers pasting within the same second—or
+  with skewed clocks—collide with different content; LWW data loss).
+
+**Recommendation: F1**, with F3's readability recoverable later via rename
+(files are ordinary project files; the sidebar rename flow exists).
+
+### D3. Destination directory
+
+- **(P1) Same directory as the current document** — matches the drop
+  flow's default (`resolveDefaultDestination({selection})`), yields
+  `![](pasted-<hash8>.png)` with no path segments. Simple, consistent.
+- **(P2) An `images/` subdirectory next to the document** — keeps the
+  sidebar tidy when pasting is frequent, at the cost of inventing a
+  convention (and creating the folder implicitly).
+
+**Recommendation: P1 for v1** (consistency with drop; no new convention);
+P2 could later become a project setting if paste-heavy projects ask for it.
+
+### D4. Insertion behavior
+
+- Insert `buildDropMarkdown('image', currentFile.path, result.path)` at
+  the **current cursor position**, via `executeEdits` (same as drop; the
+  CRDT propagation is the already-proven synchronous `onChange` → splice
+  path).
+- If the user has a **non-empty selection**, replace it and reuse the
+  selected text as alt text: `![selected text](href)` — a cheap,
+  discoverable nicety.
+- **Multiple files in one paste**: insert one reference per file,
+  **space-separated** (decided 2026-08-27), in `clipboardData.files`
+  order. Newlines are ruled out because the insertion point may be inside
+  an indentation-sensitive context (blockquote, indented bullet list),
+  where a reference starting at column 0 would have to rely on
+  soft-break/lazy-continuation behavior to stay attached to the
+  surrounding block; a single-line insertion is safe anywhere the cursor
+  can legally sit.
+- **No placeholder/spinner needed**: `createBinaryFile` is local CRDT work
+  plus a SHA-256 — milliseconds at the 10 MB cap; sync to peers happens in
+  the background. Insert after the create resolves so we can use the
+  *returned* path (which is authoritative under rename-on-conflict).
+- Cursor guard: if the paste races a file switch (`currentFile` changed
+  between event and create-resolve), drop the insertion rather than
+  inserting into the wrong document (same discipline
+  `pendingDropPositionRef` follows).
+
+### D5. Validation and failure UX
+
+- Enforce `FILE_SIZE_LIMITS.MAX_FILE_SIZE` (10 MB) via
+  `validateFileSize`; on violation show the same error surface the asset
+  dialog uses (or a toast) and insert nothing.
+- Empty/undecodable files (size 0): do not preventDefault, so the paste
+  degrades to Monaco's own handling — which per §2d means filename-text
+  insertion, not a no-op.
+- Non-image files in the payload (per §D1 we only take over when *all*
+  files are accepted images): fall through to Monaco. An alternative —
+  routing non-image file pastes to the asset dialog like drops do — is
+  deliberately **out of scope** for v1 (paste-of-copied-PDF is rare; the
+  fall-through behavior is today's behavior).
+
+### D6. What we are *not* building (scope fence)
+
+- No async-clipboard "Paste image" toolbar button (§2b) — extension point
+  only.
+- No paste support in the rich-text/comment surfaces — source editor only.
+- No SVG sanitization pipeline (per §3c recommendation S1) — separate
+  strand for the pipeline-wide SVG posture.
+- No hub-server `Content-Security-Policy` work — separate strand if/when
+  raw-file serving exists.
+
+## 5. Work items (TDD order)
+
+- [x] File follow-up strands and link `related` to bd-706b0ixu:
+      bd-yspyic32 (mixed payloads), bd-myoj9kp5 (pipeline-wide SVG
+      posture).
+- [ ] **Tests first** — a pure, DOM-free decision module
+      `fileUpload/pasteImages.ts`:
+      `classifyPastePayload({files: {name, type}[], text})` →
+      `'take-over' | 'pass-through'`, and
+      `pastedImageFilename(hash, mimeType)` → `pasted-<hash8>.<ext>`.
+      Unit-test the §2a precedence matrix (screenshot, Chrome copy-image,
+      Finder file copy incl. filename-text rider, Excel/Office mixed
+      payload, SVG file, empty file list, multi-file, unsupported raster)
+      and the filename/extension map. Verify tests fail before
+      implementing.
+- [ ] Extend `buildDropMarkdown` with optional alt text (test-first).
+- [ ] Testable ingest orchestration: `createPasteImageHandler(deps)` in
+      `fileUpload/` — a factory taking injected deps (classify, process,
+      createBinaryFile, markdown builder, editor accessors) so the full
+      paste flow (size validation, sequential ingest, single-file
+      selection-as-alt, multi-file space join, file-switch guard) is unit
+      tested without jsdom or Monaco. Verify tests fail, then implement.
+- [ ] Wire a stable capture-phase `paste` listener in `Editor.tsx`
+      (attached once at editor mount, delegating through a ref to avoid
+      the stale-closure trap), routing through the tested module.
+- [ ] `npm run build:all` + `npm run test:ci` (hub-client gates), plus
+      workspace Rust gates untouched-but-verified per pre-push checklist.
+- [ ] **End-to-end verification** per CLAUDE.md: real browser session
+      against a running hub; paste a real image from the OS clipboard;
+      observe file creation, markdown insertion, and preview rendering;
+      record the invocation + observed output in this plan.
+- [ ] hub-client changelog entry (two-commit workflow).
+- [ ] Close bd-706b0ixu with pointers.
+
+## Open questions
+
+All resolved 2026-08-27 — see the decision log at the top of this
+document.

From e0e2d2bbce302824bd56469dbe891a5ea9612822 Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Thu, 27 Aug 2026 13:01:42 -0500
Subject: [PATCH 2/4] hub-client: paste images from the clipboard into the
 source editor (bd-706b0ixu)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cmd/Ctrl-V with an image on the clipboard now ingests it silently — no
dialog: the file is created next to the current document with a
content-hash name (pasted-<hash8>.<ext>) and a markdown image reference
is inserted at the cursor (selection becomes alt text for single-file
pastes; multi-file pastes join references with spaces).

Decision logic is pure and DOM-free (fileUpload/pasteImages.ts): take
over only when every clipboard file is an accepted raster type
(png/jpeg/gif/webp/avif, non-empty) and text/plain is empty or merely
the OS file-copy filename rider. Text and mixed payloads (Office,
Excel — which ship a PNG rendition alongside the TSV) fall through to
Monaco's own paste handling. SVG is deliberately excluded from the
silent path (it can carry script; ingestion stays available via the
deliberate dialog flows) — pipeline-wide SVG posture is bd-myoj9kp5,
mixed-payload image offering is bd-yspyic32.

Content-hash naming makes concurrent pastes CRDT-safe: different
content hashes to different index keys, so no last-writer-wins clobber;
identical content converges (and dedups sequentially).

Ingest orchestration (fileUpload/pasteImageHandler.ts) is a factory
over injected deps, unit-tested without Monaco/jsdom: size limits,
per-file error isolation, rename-on-conflict path use, and a
file-switch guard that drops the insertion if the user changed
documents mid-flight. Editor.tsx wiring is a capture-phase listener on
the editor container (runs before Monaco's textarea handler), attached
once at mount via identity-stable callbacks. buildDropMarkdown gains an
optional altText parameter.

Verified: tsc -b, eslint (no new findings), vitest 1049 unit + 114
integration + 133 wasm, npm run build:all — all green.

Design + decision log: claude-notes/plans/2026-08-27-paste-image-clipboard.md

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bs2YW5vUbm1krBkQicB5nr
---
 .../plans/2026-08-27-paste-image-clipboard.md |  10 +-
 hub-client/src/components/Editor.tsx          |  84 +++++-
 .../fileUpload/dropMarkdown.test.ts           |  12 +
 .../src/components/fileUpload/dropMarkdown.ts |   5 +-
 hub-client/src/components/fileUpload/index.ts |  16 ++
 .../fileUpload/pasteImageHandler.test.ts      | 253 ++++++++++++++++++
 .../fileUpload/pasteImageHandler.ts           | 131 +++++++++
 .../components/fileUpload/pasteImages.test.ts | 221 +++++++++++++++
 .../src/components/fileUpload/pasteImages.ts  | 118 ++++++++
 9 files changed, 835 insertions(+), 15 deletions(-)
 create mode 100644 hub-client/src/components/fileUpload/pasteImageHandler.test.ts
 create mode 100644 hub-client/src/components/fileUpload/pasteImageHandler.ts
 create mode 100644 hub-client/src/components/fileUpload/pasteImages.test.ts
 create mode 100644 hub-client/src/components/fileUpload/pasteImages.ts

diff --git a/claude-notes/plans/2026-08-27-paste-image-clipboard.md b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
index 3b69849c7..e2d7a90f2 100644
--- a/claude-notes/plans/2026-08-27-paste-image-clipboard.md
+++ b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
@@ -369,7 +369,7 @@ P2 could later become a project setting if paste-heavy projects ask for it.
 - [x] File follow-up strands and link `related` to bd-706b0ixu:
       bd-yspyic32 (mixed payloads), bd-myoj9kp5 (pipeline-wide SVG
       posture).
-- [ ] **Tests first** — a pure, DOM-free decision module
+- [x] **Tests first** — a pure, DOM-free decision module
       `fileUpload/pasteImages.ts`:
       `classifyPastePayload({files: {name, type}[], text})` →
       `'take-over' | 'pass-through'`, and
@@ -379,17 +379,17 @@ P2 could later become a project setting if paste-heavy projects ask for it.
       payload, SVG file, empty file list, multi-file, unsupported raster)
       and the filename/extension map. Verify tests fail before
       implementing.
-- [ ] Extend `buildDropMarkdown` with optional alt text (test-first).
-- [ ] Testable ingest orchestration: `createPasteImageHandler(deps)` in
+- [x] Extend `buildDropMarkdown` with optional alt text (test-first).
+- [x] Testable ingest orchestration: `createPasteImageHandler(deps)` in
       `fileUpload/` — a factory taking injected deps (classify, process,
       createBinaryFile, markdown builder, editor accessors) so the full
       paste flow (size validation, sequential ingest, single-file
       selection-as-alt, multi-file space join, file-switch guard) is unit
       tested without jsdom or Monaco. Verify tests fail, then implement.
-- [ ] Wire a stable capture-phase `paste` listener in `Editor.tsx`
+- [x] Wire a stable capture-phase `paste` listener in `Editor.tsx`
       (attached once at editor mount, delegating through a ref to avoid
       the stale-closure trap), routing through the tested module.
-- [ ] `npm run build:all` + `npm run test:ci` (hub-client gates), plus
+- [x] `npm run build:all` + `npm run test:ci` (hub-client gates), plus
       workspace Rust gates untouched-but-verified per pre-push checklist.
 - [ ] **End-to-end verification** per CLAUDE.md: real browser session
       against a running hub; paste a real image from the OS clipboard;
diff --git a/hub-client/src/components/Editor.tsx b/hub-client/src/components/Editor.tsx
index 8b89b774d..729160dbe 100644
--- a/hub-client/src/components/Editor.tsx
+++ b/hub-client/src/components/Editor.tsx
@@ -1,4 +1,4 @@
-import { useState, useCallback, useRef, useEffect } from 'react';
+import { useState, useCallback, useMemo, useRef, useEffect } from 'react';
 // Side effects only: bundles Monaco + workers so no runtime CDN fetch occurs.
 import '../monacoSetup';
 import MonacoEditor from '@monaco-editor/react';
@@ -21,8 +21,13 @@ import { hasExecutableCells } from '../services/executableCells';
 import type { Diagnostic, RenderComment } from '@quarto/preview-renderer/types/diagnostic';
 import { useIntelligenceProviders } from '../hooks/useIntelligenceProviders';
 import { registerQmdLanguage } from './quartoTheme';
-import { processFileForUpload } from '../services/resourceService';
-import { buildDropMarkdown, resolveDefaultDestination } from './fileUpload';
+import { processFileForUpload, FILE_SIZE_LIMITS } from '../services/resourceService';
+import {
+  buildDropMarkdown,
+  resolveDefaultDestination,
+  classifyPastePayload,
+  createPasteImageHandler,
+} from './fileUpload';
 import { useProjectSearch } from '../services/search';
 import { usePresence } from '../hooks/usePresence';
 import { usePreference } from '../hooks/usePreference';
@@ -689,12 +694,17 @@ export default function Editor({ project, files, fileContents, onDisconnect, onC
       }
     });
 
-    // Attach drag-drop handlers to editor container
+    // Attach drag-drop and paste handlers to editor container
     const domNode = editor.getDomNode();
     if (domNode) {
       domNode.addEventListener('dragover', handleEditorDragOver);
       domNode.addEventListener('dragleave', handleEditorDragLeave);
       domNode.addEventListener('drop', handleEditorDrop);
+      // Capture phase: the paste event targets Monaco's hidden textarea,
+      // and Monaco's own listener (which preventDefaults and re-implements
+      // text paste) sits on that textarea — capture on the container runs
+      // first, so image payloads can be intercepted (bd-706b0ixu).
+      domNode.addEventListener('paste', handleEditorPaste, true);
     }
 
     // Signal that editor is ready for scroll sync
@@ -894,9 +904,66 @@ export default function Editor({ project, files, fileContents, onDisconnect, onC
     setShowNewAssetDialog(true);
   }, [currentFile]);
 
-  // Cleanup editor drag-drop listeners on unmount. Note: intelligence-provider
-  // disposal lives in useIntelligenceProviders (mount-only) — it must NOT be
-  // coupled to `handleEditorDrop`, whose identity changes with `currentFile`.
+  // Clipboard image paste (bd-706b0ixu, see
+  // claude-notes/plans/2026-08-27-paste-image-clipboard.md): silent
+  // ingest — content-hash-named file next to the current document, then
+  // a markdown reference at the cursor. Every dep reads through a ref or
+  // a stable callback, so both callbacks below are identity-stable and
+  // the DOM listener can be attached once at editor mount.
+  const pasteImageIngest = useMemo(
+    () =>
+      createPasteImageHandler({
+        getCurrentFilePath,
+        getEditor: () => {
+          const editor = editorRef.current;
+          if (!editor) return null;
+          return {
+            getSelection: () => editor.getSelection(),
+            getTextInRange: (range) =>
+              editor.getModel()?.getValueInRange(range) ?? '',
+            replaceRange: (range, text) => {
+              // Monaco's onChange fires synchronously from executeEdits,
+              // updating both React state and CRDT via the splice path.
+              editor.executeEdits('image-paste', [
+                { range, text, forceMoveMarkers: true },
+              ]);
+            },
+          };
+        },
+        processFile: processFileForUpload,
+        createBinaryFile,
+        maxFileSize: FILE_SIZE_LIMITS.MAX_FILE_SIZE,
+        onError: (message) => console.error(message),
+      }),
+    [getCurrentFilePath]
+  );
+
+  const handleEditorPaste = useCallback(
+    (e: ClipboardEvent) => {
+      const clipboard = e.clipboardData;
+      if (!clipboard) return;
+      const files = Array.from(clipboard.files);
+      if (
+        classifyPastePayload({
+          files: files.map((f) => ({ name: f.name, type: f.type, size: f.size })),
+          text: clipboard.getData('text/plain'),
+        }) !== 'take-over'
+      ) {
+        return; // text and mixed payloads: Monaco's paste handling runs
+      }
+      // Taking over: stop Monaco's own handler (it would insert the
+      // filename rider as stray text) before the async ingest starts.
+      e.preventDefault();
+      e.stopPropagation();
+      void pasteImageIngest(files);
+    },
+    [pasteImageIngest]
+  );
+
+  // Cleanup editor drag-drop/paste listeners on unmount. Note:
+  // intelligence-provider disposal lives in useIntelligenceProviders
+  // (mount-only) — it must NOT be coupled to `handleEditorDrop`, whose
+  // identity changes with `currentFile`.
   useEffect(() => {
     return () => {
       const domNode = editorRef.current?.getDomNode();
@@ -904,9 +971,10 @@ export default function Editor({ project, files, fileContents, onDisconnect, onC
         domNode.removeEventListener('dragover', handleEditorDragOver);
         domNode.removeEventListener('dragleave', handleEditorDragLeave);
         domNode.removeEventListener('drop', handleEditorDrop);
+        domNode.removeEventListener('paste', handleEditorPaste, true);
       }
     };
-  }, [handleEditorDragOver, handleEditorDragLeave, handleEditorDrop]);
+  }, [handleEditorDragOver, handleEditorDragLeave, handleEditorDrop, handleEditorPaste]);
 
   // Handle creating a new text file
   const handleCreateTextFile = useCallback(async (path: string, initialContent: string) => {
diff --git a/hub-client/src/components/fileUpload/dropMarkdown.test.ts b/hub-client/src/components/fileUpload/dropMarkdown.test.ts
index f1f7e7e9f..4741814b5 100644
--- a/hub-client/src/components/fileUpload/dropMarkdown.test.ts
+++ b/hub-client/src/components/fileUpload/dropMarkdown.test.ts
@@ -40,6 +40,18 @@ describe('buildDropMarkdown', () => {
     it('falls back to the target path verbatim without a current file', () => {
       expect(buildDropMarkdown('image', null, 'photo.png')).toBe('![](photo.png)');
     });
+
+    it('includes alt text when provided', () => {
+      expect(
+        buildDropMarkdown('image', 'posts/hello.qmd', 'posts/photo.png', 'a caption')
+      ).toBe('![a caption](photo.png)');
+    });
+
+    it('treats an empty alt text like the default', () => {
+      expect(
+        buildDropMarkdown('image', 'posts/hello.qmd', 'posts/photo.png', '')
+      ).toBe('![](photo.png)');
+    });
   });
 
   describe('link markdown', () => {
diff --git a/hub-client/src/components/fileUpload/dropMarkdown.ts b/hub-client/src/components/fileUpload/dropMarkdown.ts
index c8b254b35..c2856f856 100644
--- a/hub-client/src/components/fileUpload/dropMarkdown.ts
+++ b/hub-client/src/components/fileUpload/dropMarkdown.ts
@@ -17,14 +17,15 @@ export type DropMarkdownKind = 'image' | 'link';
 export function buildDropMarkdown(
   kind: DropMarkdownKind,
   currentFilePath: string | null,
-  targetPath: string
+  targetPath: string,
+  altText: string = ''
 ): string {
   const href = currentFilePath
     ? relativePathBetween(currentFilePath, targetPath)
     : targetPath;
 
   if (kind === 'image') {
-    return `![](${href})`;
+    return `![${altText}](${href})`;
   }
   const fileName = targetPath.split('/').pop() || targetPath;
   return `[${fileName}](${href})`;
diff --git a/hub-client/src/components/fileUpload/index.ts b/hub-client/src/components/fileUpload/index.ts
index a1a69b854..9a200faaa 100644
--- a/hub-client/src/components/fileUpload/index.ts
+++ b/hub-client/src/components/fileUpload/index.ts
@@ -13,3 +13,19 @@ export {
 } from './resolveDefaultDestination';
 export { processAssetFiles, type AssetFilePreview } from './processAssetFiles';
 export { buildDropMarkdown, type DropMarkdownKind } from './dropMarkdown';
+export {
+  classifyPastePayload,
+  pastedImageFilename,
+  sanitizeAltText,
+  ACCEPTED_PASTE_IMAGE_TYPES,
+  type PastePayload,
+  type PastePayloadFile,
+  type PasteClassification,
+} from './pasteImages';
+export {
+  createPasteImageHandler,
+  type CreatePasteImageHandlerDeps,
+  type PasteImageEditor,
+  type PasteImageHandler,
+  type PasteRange,
+} from './pasteImageHandler';
diff --git a/hub-client/src/components/fileUpload/pasteImageHandler.test.ts b/hub-client/src/components/fileUpload/pasteImageHandler.test.ts
new file mode 100644
index 000000000..7ef8ea2b7
--- /dev/null
+++ b/hub-client/src/components/fileUpload/pasteImageHandler.test.ts
@@ -0,0 +1,253 @@
+/**
+ * Tests for the paste-image ingest orchestration (bd-706b0ixu).
+ *
+ * The handler factory takes injected deps, so the full flow — size
+ * validation, sequential ingest, filename generation, single-file
+ * selection-as-alt, multi-file space join, file-switch guard — is
+ * exercised without jsdom or Monaco. Editor.tsx supplies real deps.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  createPasteImageHandler,
+  type PasteImageEditor,
+  type PasteRange,
+} from './pasteImageHandler';
+
+const HASHES: Record<string, string> = {
+  'a.png': 'aaaa1111'.repeat(8),
+  'b.png': 'bbbb2222'.repeat(8),
+};
+
+function makeFile(name: string, type = 'image/png', bytes = 16): File {
+  return new File([new Uint8Array(bytes).fill(7)], name, { type });
+}
+
+const cursorAt = (line: number, col: number): PasteRange => ({
+  startLineNumber: line,
+  startColumn: col,
+  endLineNumber: line,
+  endColumn: col,
+});
+
+interface FakeEditorOpts {
+  selection?: PasteRange | null;
+  selectedText?: string;
+}
+
+function makeFakeEditor(opts: FakeEditorOpts = {}) {
+  const replacements: Array<{ range: PasteRange; text: string }> = [];
+  const editor: PasteImageEditor = {
+    getSelection: () => opts.selection ?? cursorAt(3, 5),
+    getTextInRange: () => opts.selectedText ?? '',
+    replaceRange: (range, text) => {
+      replacements.push({ range, text });
+    },
+  };
+  return { editor, replacements };
+}
+
+interface HarnessOpts extends FakeEditorOpts {
+  currentFilePath?: string | null | (() => string | null);
+  maxFileSize?: number;
+  createBinaryFile?: (
+    path: string,
+    content: Uint8Array,
+    mimeType: string
+  ) => Promise<{ path: string }>;
+}
+
+function makeHarness(opts: HarnessOpts = {}) {
+  const { editor, replacements } = makeFakeEditor(opts);
+  const created: Array<{ path: string; mimeType: string; size: number }> = [];
+  const errors: string[] = [];
+
+  const currentFilePath = opts.currentFilePath ?? 'posts/hello.qmd';
+  const getCurrentFilePath =
+    typeof currentFilePath === 'function'
+      ? currentFilePath
+      : () => currentFilePath;
+
+  const handler = createPasteImageHandler({
+    getCurrentFilePath,
+    getEditor: () => editor,
+    processFile: async (file: File) => ({
+      content: new Uint8Array(await file.arrayBuffer()),
+      mimeType: file.type,
+      hash: HASHES[file.name] ?? 'cccc3333'.repeat(8),
+    }),
+    createBinaryFile:
+      opts.createBinaryFile ??
+      (async (path, content, mimeType) => {
+        created.push({ path, mimeType, size: content.length });
+        return { path };
+      }),
+    maxFileSize: opts.maxFileSize ?? 1024 * 1024,
+    onError: (message) => {
+      errors.push(message);
+    },
+  });
+
+  return { handler, replacements, created, errors };
+}
+
+describe('createPasteImageHandler', () => {
+  it('single file: creates the binary next to the current doc and inserts a reference', async () => {
+    const { handler, replacements, created } = makeHarness();
+
+    const inserted = await handler([makeFile('a.png')]);
+
+    expect(inserted).toBe(true);
+    expect(created).toEqual([
+      { path: 'posts/pasted-aaaa1111.png', mimeType: 'image/png', size: 16 },
+    ]);
+    expect(replacements).toEqual([
+      { range: cursorAt(3, 5), text: '![](pasted-aaaa1111.png)' },
+    ]);
+  });
+
+  it('uses the selection as alt text for a single-file paste', async () => {
+    const { handler, replacements } = makeHarness({
+      selection: {
+        startLineNumber: 3,
+        startColumn: 5,
+        endLineNumber: 3,
+        endColumn: 12,
+      },
+      selectedText: 'my [old] caption',
+    });
+
+    await handler([makeFile('a.png')]);
+
+    expect(replacements[0].text).toBe(
+      '![my \\[old\\] caption](pasted-aaaa1111.png)'
+    );
+  });
+
+  it('multi-file: inserts space-separated references without alt text', async () => {
+    const { handler, replacements, created } = makeHarness({
+      selectedText: 'a selection that must NOT become alt text',
+      selection: {
+        startLineNumber: 1,
+        startColumn: 1,
+        endLineNumber: 1,
+        endColumn: 9,
+      },
+    });
+
+    await handler([makeFile('a.png'), makeFile('b.png')]);
+
+    expect(created.map((c) => c.path)).toEqual([
+      'posts/pasted-aaaa1111.png',
+      'posts/pasted-bbbb2222.png',
+    ]);
+    expect(replacements[0].text).toBe(
+      '![](pasted-aaaa1111.png) ![](pasted-bbbb2222.png)'
+    );
+  });
+
+  it('uses the path returned by createBinaryFile (rename-on-conflict)', async () => {
+    const { handler, replacements } = makeHarness({
+      createBinaryFile: async () => ({
+        path: 'posts/pasted-aaaa1111-99887766.png',
+      }),
+    });
+
+    await handler([makeFile('a.png')]);
+
+    expect(replacements[0].text).toBe('![](pasted-aaaa1111-99887766.png)');
+  });
+
+  it('current file at project root: creates at root with a bare reference', async () => {
+    const { handler, replacements, created } = makeHarness({
+      currentFilePath: 'hello.qmd',
+    });
+
+    await handler([makeFile('a.png')]);
+
+    expect(created[0].path).toBe('pasted-aaaa1111.png');
+    expect(replacements[0].text).toBe('![](pasted-aaaa1111.png)');
+  });
+
+  it('oversize file: reports an error, creates and inserts nothing', async () => {
+    const { handler, replacements, created, errors } = makeHarness({
+      maxFileSize: 8,
+    });
+
+    const inserted = await handler([makeFile('a.png', 'image/png', 16)]);
+
+    expect(inserted).toBe(false);
+    expect(created).toEqual([]);
+    expect(replacements).toEqual([]);
+    expect(errors).toHaveLength(1);
+  });
+
+  it('mixed sizes: ingests the valid file, reports the oversize one', async () => {
+    const { handler, replacements, created, errors } = makeHarness({
+      maxFileSize: 20,
+    });
+
+    const inserted = await handler([
+      makeFile('a.png', 'image/png', 16),
+      makeFile('b.png', 'image/png', 64),
+    ]);
+
+    expect(inserted).toBe(true);
+    expect(created.map((c) => c.path)).toEqual(['posts/pasted-aaaa1111.png']);
+    expect(replacements[0].text).toBe('![](pasted-aaaa1111.png)');
+    expect(errors).toHaveLength(1);
+  });
+
+  it('skips insertion when the current file changed mid-flight', async () => {
+    const getCurrentFilePath = vi
+      .fn<() => string | null>()
+      .mockReturnValueOnce('posts/hello.qmd') // captured at paste time
+      .mockReturnValue('other.qmd'); // by insertion time
+
+    const { handler, replacements, created } = makeHarness({
+      currentFilePath: getCurrentFilePath as unknown as () => string | null,
+    });
+
+    const inserted = await handler([makeFile('a.png')]);
+
+    expect(inserted).toBe(false);
+    expect(created).toHaveLength(1); // file creation is not rolled back
+    expect(replacements).toEqual([]);
+  });
+
+  it('returns false without an editor', async () => {
+    const errors: string[] = [];
+    const handler = createPasteImageHandler({
+      getCurrentFilePath: () => 'hello.qmd',
+      getEditor: () => null,
+      processFile: async () => {
+        throw new Error('should not be called');
+      },
+      createBinaryFile: async () => {
+        throw new Error('should not be called');
+      },
+      maxFileSize: 1024,
+      onError: (m) => errors.push(m),
+    });
+
+    expect(await handler([makeFile('a.png')])).toBe(false);
+    expect(errors).toEqual([]);
+  });
+
+  it('reports a create failure and continues with remaining files', async () => {
+    let call = 0;
+    const { handler, replacements, errors } = makeHarness({
+      createBinaryFile: async (path) => {
+        call += 1;
+        if (call === 1) throw new Error('boom');
+        return { path };
+      },
+    });
+
+    const inserted = await handler([makeFile('a.png'), makeFile('b.png')]);
+
+    expect(inserted).toBe(true);
+    expect(errors).toHaveLength(1);
+    expect(replacements[0].text).toBe('![](pasted-bbbb2222.png)');
+  });
+});
diff --git a/hub-client/src/components/fileUpload/pasteImageHandler.ts b/hub-client/src/components/fileUpload/pasteImageHandler.ts
new file mode 100644
index 000000000..740387f1b
--- /dev/null
+++ b/hub-client/src/components/fileUpload/pasteImageHandler.ts
@@ -0,0 +1,131 @@
+/**
+ * Ingest orchestration for images pasted into the source editor
+ * (bd-706b0ixu; design:
+ * claude-notes/plans/2026-08-27-paste-image-clipboard.md §D4/§D5).
+ *
+ * A factory over injected deps so the whole flow — size validation,
+ * sequential ingest, filename generation, selection-as-alt-text,
+ * multi-file joining, file-switch guard — is unit-testable without
+ * Monaco or jsdom. Editor.tsx supplies the real deps and the DOM-facing
+ * `paste`-event wrapper.
+ */
+
+import { buildDropMarkdown } from './dropMarkdown';
+import { pastedImageFilename, sanitizeAltText } from './pasteImages';
+import { resolveDefaultDestination } from './resolveDefaultDestination';
+
+/** Line/column range in Monaco's 1-based coordinates. */
+export interface PasteRange {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+}
+
+/** The slice of the Monaco editor the handler needs. */
+export interface PasteImageEditor {
+  /** Current selection (a cursor is an empty selection); null if none. */
+  getSelection(): PasteRange | null;
+  /** Text covered by a range (`''` for an empty range). */
+  getTextInRange(range: PasteRange): string;
+  /** Replace `range` with `text` as a user-undoable edit. */
+  replaceRange(range: PasteRange, text: string): void;
+}
+
+export interface CreatePasteImageHandlerDeps {
+  /** Project-root-relative path of the open document, or null. */
+  getCurrentFilePath(): string | null;
+  getEditor(): PasteImageEditor | null;
+  /** Read bytes + hash + MIME (resourceService.processFileForUpload). */
+  processFile(file: File): Promise<{
+    content: Uint8Array;
+    mimeType: string;
+    hash: string;
+  }>;
+  /** CRDT binary-file create; returns the final (possibly renamed) path. */
+  createBinaryFile(
+    path: string,
+    content: Uint8Array,
+    mimeType: string
+  ): Promise<{ path: string }>;
+  /** FILE_SIZE_LIMITS.MAX_FILE_SIZE in production. */
+  maxFileSize: number;
+  onError(message: string): void;
+}
+
+export type PasteImageHandler = (files: File[]) => Promise<boolean>;
+
+/**
+ * Build the async ingest handler. The caller has already classified the
+ * payload as 'take-over' (see `classifyPastePayload`) and called
+ * `preventDefault()`; this function does the rest and resolves to true
+ * iff a markdown reference was inserted.
+ */
+export function createPasteImageHandler(
+  deps: CreatePasteImageHandlerDeps
+): PasteImageHandler {
+  return async (files: File[]): Promise<boolean> => {
+    const editor = deps.getEditor();
+    if (!editor) return false;
+
+    // Capture insertion context at paste time: the async ingest below
+    // must not land in a different document (§D4 cursor guard).
+    const pathAtPaste = deps.getCurrentFilePath();
+    const selection = editor.getSelection();
+    if (!selection) return false;
+    const selectedText = editor.getTextInRange(selection);
+
+    const destination = resolveDefaultDestination({ selection: pathAtPaste });
+
+    const createdPaths: string[] = [];
+    for (const file of files) {
+      if (file.size > deps.maxFileSize) {
+        const sizeMB = (file.size / (1024 * 1024)).toFixed(2);
+        const maxMB = deps.maxFileSize / (1024 * 1024);
+        deps.onError(
+          `Pasted image (${sizeMB} MB) exceeds the maximum allowed size (${maxMB} MB)`
+        );
+        continue;
+      }
+
+      try {
+        const { content, mimeType, hash } = await deps.processFile(file);
+        const filename = pastedImageFilename(hash, mimeType);
+        if (!filename) {
+          // Unreachable when the caller classified the payload, but the
+          // classifier and this handler are separately callable.
+          deps.onError(`Unsupported pasted image type: ${mimeType}`);
+          continue;
+        }
+        const targetPath = destination ? `${destination}/${filename}` : filename;
+        const result = await deps.createBinaryFile(targetPath, content, mimeType);
+        createdPaths.push(result.path);
+      } catch (err) {
+        deps.onError(
+          `Failed to ingest pasted image: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+
+    if (createdPaths.length === 0) return false;
+
+    // File-switch guard: if the user changed documents while we hashed
+    // and created, inserting at the captured range would corrupt the
+    // wrong file. The created binaries are kept — they are ordinary
+    // project files the user can reference or delete.
+    if (deps.getCurrentFilePath() !== pathAtPaste) return false;
+    const editorNow = deps.getEditor();
+    if (!editorNow) return false;
+
+    // Selection-as-alt only for a single-file paste; multi-file pastes
+    // get plain references, space-separated (§D4 — newlines would rely
+    // on lazy continuation inside blockquotes/indented lists).
+    const alt = createdPaths.length === 1 ? sanitizeAltText(selectedText) : '';
+    const markdown = createdPaths
+      .map((p, i) => buildDropMarkdown('image', pathAtPaste, p, i === 0 ? alt : ''))
+      .join(' ');
+
+    editorNow.replaceRange(selection, markdown);
+    return true;
+  };
+}
diff --git a/hub-client/src/components/fileUpload/pasteImages.test.ts b/hub-client/src/components/fileUpload/pasteImages.test.ts
new file mode 100644
index 000000000..9b73910aa
--- /dev/null
+++ b/hub-client/src/components/fileUpload/pasteImages.test.ts
@@ -0,0 +1,221 @@
+/**
+ * Tests for the pure clipboard-paste decision module (bd-706b0ixu).
+ *
+ * The precedence matrix mirrors §2a of
+ * claude-notes/plans/2026-08-27-paste-image-clipboard.md: take over iff
+ * the payload's files are all accepted raster images (non-empty, none
+ * zero-sized) and the text/plain item is empty or merely the filename
+ * rider; everything else passes through to Monaco's own paste handling.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  classifyPastePayload,
+  pastedImageFilename,
+  sanitizeAltText,
+  ACCEPTED_PASTE_IMAGE_TYPES,
+} from './pasteImages';
+
+const png = (name = 'image.png', size = 1024) => ({
+  name,
+  type: 'image/png',
+  size,
+});
+
+describe('classifyPastePayload', () => {
+  describe('take-over cases', () => {
+    it('screenshot paste: single PNG file, no text', () => {
+      expect(classifyPastePayload({ files: [png()], text: '' })).toBe(
+        'take-over'
+      );
+    });
+
+    it("Chrome 'Copy image': PNG file, empty text/plain (text/html ignored)", () => {
+      // Chrome's copy-image payload carries text/html but no text/plain;
+      // the classifier only sees the text/plain rendition.
+      expect(classifyPastePayload({ files: [png()], text: '' })).toBe(
+        'take-over'
+      );
+    });
+
+    it('Finder file copy with filename rider as text', () => {
+      expect(
+        classifyPastePayload({
+          files: [png('photo.png')],
+          text: 'photo.png',
+        })
+      ).toBe('take-over');
+    });
+
+    it('filename rider with surrounding whitespace still counts as rider', () => {
+      expect(
+        classifyPastePayload({
+          files: [png('photo.png')],
+          text: '  photo.png\n',
+        })
+      ).toBe('take-over');
+    });
+
+    it('multi-file: all accepted raster types, no text', () => {
+      expect(
+        classifyPastePayload({
+          files: [png('a.png'), { name: 'b.jpg', type: 'image/jpeg', size: 10 }],
+          text: '',
+        })
+      ).toBe('take-over');
+    });
+
+    it('multi-file with newline-joined filename rider', () => {
+      expect(
+        classifyPastePayload({
+          files: [png('a.png'), png('b.png')],
+          text: 'a.png\nb.png',
+        })
+      ).toBe('take-over');
+    });
+
+    it.each([
+      ['image/jpeg', 'photo.jpg'],
+      ['image/gif', 'anim.gif'],
+      ['image/webp', 'pic.webp'],
+      ['image/avif', 'pic.avif'],
+    ])('accepts raster type %s', (type, name) => {
+      expect(
+        classifyPastePayload({ files: [{ name, type, size: 10 }], text: '' })
+      ).toBe('take-over');
+    });
+  });
+
+  describe('pass-through cases', () => {
+    it('Excel/Office mixed payload: image rendition plus meaningful text', () => {
+      expect(
+        classifyPastePayload({
+          files: [png()],
+          text: 'cell1\tcell2\ncell3\tcell4',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('text differing from the filename is not a rider', () => {
+      expect(
+        classifyPastePayload({
+          files: [png('photo.png')],
+          text: 'photo of my cat',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('SVG file (active content stays dialog-only, §3c S1)', () => {
+      expect(
+        classifyPastePayload({
+          files: [{ name: 'diagram.svg', type: 'image/svg+xml', size: 10 }],
+          text: '',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('non-image file (PDF)', () => {
+      expect(
+        classifyPastePayload({
+          files: [{ name: 'doc.pdf', type: 'application/pdf', size: 10 }],
+          text: '',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('unsupported raster type (image/tiff)', () => {
+      expect(
+        classifyPastePayload({
+          files: [{ name: 'scan.tiff', type: 'image/tiff', size: 10 }],
+          text: '',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('file with empty MIME type', () => {
+      expect(
+        classifyPastePayload({
+          files: [{ name: 'mystery', type: '', size: 10 }],
+          text: '',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('plain text paste (no files)', () => {
+      expect(classifyPastePayload({ files: [], text: 'hello' })).toBe(
+        'pass-through'
+      );
+    });
+
+    it('empty payload', () => {
+      expect(classifyPastePayload({ files: [], text: '' })).toBe(
+        'pass-through'
+      );
+    });
+
+    it('one accepted image plus one SVG', () => {
+      expect(
+        classifyPastePayload({
+          files: [
+            png(),
+            { name: 'diagram.svg', type: 'image/svg+xml', size: 10 },
+          ],
+          text: '',
+        })
+      ).toBe('pass-through');
+    });
+
+    it('zero-size file (degrade to Monaco per §D5)', () => {
+      expect(
+        classifyPastePayload({ files: [png('image.png', 0)], text: '' })
+      ).toBe('pass-through');
+    });
+  });
+});
+
+describe('pastedImageFilename', () => {
+  const hash =
+    'abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890';
+
+  it('uses the pasted- prefix and an 8-char hash prefix', () => {
+    expect(pastedImageFilename(hash, 'image/png')).toBe('pasted-abcdef12.png');
+  });
+
+  it.each([
+    ['image/jpeg', 'pasted-abcdef12.jpg'],
+    ['image/gif', 'pasted-abcdef12.gif'],
+    ['image/webp', 'pasted-abcdef12.webp'],
+    ['image/avif', 'pasted-abcdef12.avif'],
+  ])('maps %s to the right extension', (mime, expected) => {
+    expect(pastedImageFilename(hash, mime)).toBe(expected);
+  });
+
+  it('returns null for a MIME type outside the accepted set', () => {
+    expect(pastedImageFilename(hash, 'image/svg+xml')).toBeNull();
+    expect(pastedImageFilename(hash, 'application/pdf')).toBeNull();
+  });
+
+  it('accepted set and extension map agree', () => {
+    for (const mime of ACCEPTED_PASTE_IMAGE_TYPES) {
+      expect(pastedImageFilename(hash, mime)).not.toBeNull();
+    }
+  });
+});
+
+describe('sanitizeAltText', () => {
+  it('passes plain text through', () => {
+    expect(sanitizeAltText('a nice photo')).toBe('a nice photo');
+  });
+
+  it('collapses newlines and whitespace runs to single spaces', () => {
+    expect(sanitizeAltText('line one\nline   two')).toBe('line one line two');
+  });
+
+  it('escapes square brackets', () => {
+    expect(sanitizeAltText('see [fig 1]')).toBe('see \\[fig 1\\]');
+  });
+
+  it('trims leading and trailing whitespace', () => {
+    expect(sanitizeAltText('  padded  ')).toBe('padded');
+  });
+});
diff --git a/hub-client/src/components/fileUpload/pasteImages.ts b/hub-client/src/components/fileUpload/pasteImages.ts
new file mode 100644
index 000000000..01a1fca50
--- /dev/null
+++ b/hub-client/src/components/fileUpload/pasteImages.ts
@@ -0,0 +1,118 @@
+/**
+ * Pure decision logic for pasting images from the clipboard into the
+ * source editor (bd-706b0ixu; design:
+ * claude-notes/plans/2026-08-27-paste-image-clipboard.md).
+ *
+ * The paste path is silent — no dialog — so it is deliberately narrower
+ * than the drag-and-drop/asset-dialog flows:
+ *
+ * - Raster images only. `image/svg+xml` is excluded because SVG can
+ *   carry executable script; SVG ingestion stays available through the
+ *   deliberate, visible dialog flows (§3c option S1; pipeline-wide SVG
+ *   posture is bd-myoj9kp5).
+ * - Payloads carrying meaningful `text/plain` pass through to Monaco's
+ *   text paste. Excel/Sheets cell copies ship an `image/png` rendition
+ *   of the cells *alongside* the TSV text — the user wants the text.
+ *   The one text form that does NOT block take-over is the "filename
+ *   rider" an OS file-copy adds (the pasted file's own name), which
+ *   Monaco would otherwise insert as stray text. Offering the image
+ *   rendition of mixed payloads is follow-up bd-yspyic32.
+ * - Zero-size files pass through (degrade to Monaco's behavior, §D5).
+ */
+
+/** Raster MIME types accepted on the silent paste path. */
+export const ACCEPTED_PASTE_IMAGE_TYPES: ReadonlySet<string> = new Set([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+  'image/avif',
+]);
+
+/** File extension (without dot) for each accepted MIME type. */
+const EXTENSION_BY_MIME: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+  'image/avif': 'avif',
+};
+
+/** The subset of `File` the classifier needs (DOM-free for testing). */
+export interface PastePayloadFile {
+  name: string;
+  type: string;
+  size: number;
+}
+
+export interface PastePayload {
+  /** `clipboardData.files`, reduced to name/type/size. */
+  files: PastePayloadFile[];
+  /** The clipboard's `text/plain` rendition (`''` when absent). */
+  text: string;
+}
+
+export type PasteClassification = 'take-over' | 'pass-through';
+
+/**
+ * Decide whether the paste handler takes over a clipboard payload or
+ * lets Monaco's own text-paste handling run.
+ */
+export function classifyPastePayload(payload: PastePayload): PasteClassification {
+  const { files, text } = payload;
+  if (files.length === 0) return 'pass-through';
+
+  const allAcceptedImages = files.every(
+    (f) => f.size > 0 && ACCEPTED_PASTE_IMAGE_TYPES.has(f.type)
+  );
+  if (!allAcceptedImages) return 'pass-through';
+
+  if (!isFilenameRider(text, files)) return 'pass-through';
+
+  return 'take-over';
+}
+
+/**
+ * True when `text` carries no information beyond the pasted files
+ * themselves: empty, a single pasted file's name, or the newline-joined
+ * names. Anything else (Office/Excel text renditions, full paths) is
+ * meaningful text and blocks take-over — the conservative direction,
+ * since pass-through is today's behavior.
+ */
+function isFilenameRider(text: string, files: PastePayloadFile[]): boolean {
+  const trimmed = text.trim();
+  if (trimmed === '') return true;
+  if (files.some((f) => f.name === trimmed)) return true;
+  return trimmed === files.map((f) => f.name).join('\n');
+}
+
+/**
+ * Auto-generated filename for a pasted image: `pasted-<hash8>.<ext>`.
+ *
+ * Content-hash naming is what makes the no-dialog flow safe under
+ * concurrent CRDT peers: `createBinaryFile`'s existence check is
+ * check-then-act against the local replica, so two peers claiming the
+ * same index key with different content would race to last-writer-wins
+ * and silently lose an image. Different content → different hash →
+ * different key: no race. Identical concurrent content converges to
+ * identical bytes whichever write wins.
+ *
+ * Returns null for a MIME type outside the accepted set.
+ */
+export function pastedImageFilename(hash: string, mimeType: string): string | null {
+  const ext = EXTENSION_BY_MIME[mimeType];
+  if (!ext) return null;
+  return `pasted-${hash.slice(0, 8)}.${ext}`;
+}
+
+/**
+ * Make selected text safe to use as markdown image alt text: collapse
+ * whitespace runs (newlines would break the reference in
+ * indentation-sensitive contexts) and escape square brackets.
+ */
+export function sanitizeAltText(text: string): string {
+  return text
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/([[\]])/g, '\\$1');
+}

From a32f8cdb18c50c9bfdc9e00c9abaa9ad1d46cc80 Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Thu, 27 Aug 2026 13:07:19 -0500
Subject: [PATCH 3/4] hub-client changelog + E2E verification record for
 clipboard image paste (e0e2d2bbc)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Changelog entry for the paste-image feature, and the plan's end-to-end
verification record: exercised in the production bundle via local-prod
(bundle commit e0e2d2bbc confirmed in the page footer) — file creation
with content-hash name, markdown insertion, preview rendering of the
pasted bytes, repeat-paste dedup, SVG decline, and mixed-payload
pass-through all observed live; zero console errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bs2YW5vUbm1krBkQicB5nr
---
 .../plans/2026-08-27-paste-image-clipboard.md | 44 +++++++++++++++++--
 hub-client/changelog.md                       |  1 +
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/claude-notes/plans/2026-08-27-paste-image-clipboard.md b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
index e2d7a90f2..783233319 100644
--- a/claude-notes/plans/2026-08-27-paste-image-clipboard.md
+++ b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
@@ -391,13 +391,49 @@ P2 could later become a project setting if paste-heavy projects ask for it.
       the stale-closure trap), routing through the tested module.
 - [x] `npm run build:all` + `npm run test:ci` (hub-client gates), plus
       workspace Rust gates untouched-but-verified per pre-push checklist.
-- [ ] **End-to-end verification** per CLAUDE.md: real browser session
-      against a running hub; paste a real image from the OS clipboard;
-      observe file creation, markdown insertion, and preview rendering;
-      record the invocation + observed output in this plan.
+- [x] **End-to-end verification** per CLAUDE.md — performed 2026-08-27
+      against the production bundle in local-prod mode. See §6 below.
 - [ ] hub-client changelog entry (two-commit workflow).
 - [ ] Close bd-706b0ixu with pointers.
 
+## 6. End-to-end verification record (2026-08-27)
+
+Setup: `cargo build --bin hub`, `cd hub-client && npm run
+build:local-prod`, `npm run local-prod`; Chrome (DevTools MCP) at
+`http://127.0.0.1:8080`. The page footer showed bundle commit
+`e0e2d2bbc` — the feature commit — before testing (the service worker
+initially served the previous bundle; "New version available → Reload"
+was required first). A fresh project `paste-image-e2e` was created and
+`index.qmd` opened in split view.
+
+The paste was driven by dispatching a `ClipboardEvent` carrying a real
+`File` (a 79-byte deterministic 16×16 PNG, SHA-256 `f613c380a1…`) at
+Monaco's focus element (`.native-edit-context` — monaco 0.55 runs in
+EditContext mode; there is no `.inputarea` textarea). A true OS-level
+Cmd-V could not be synthesized: CDP key events carry no clipboard
+payload, so `press_key Meta+V` is a no-op in Chrome — a limitation of
+the harness, not of the handler; the synthetic event exercises the
+identical listener → classify → ingest → CRDT → preview path in the
+shipped bundle. Observed, in the running app:
+
+1. `![](pasted-f613c380.png)` inserted at the cursor — the name matches
+   the PNG's true SHA-256 prefix; `pasted-f613c380.png` appeared in the
+   FILES sidebar; the preview rendered `<img
+   src="data:image/png;base64,iVBORw0KGgo…"` with
+   `naturalWidth/Height = 16` (bytes round-tripped through the CRDT).
+2. Repeat paste of the same PNG: a second reference inserted, sidebar
+   still lists exactly one file — hash-name dedup confirmed live.
+3. SVG file paste (`evil.svg` containing `<script>`): passed through;
+   Monaco inserted the filename text `evil.svg`; no file created —
+   decisions S1 + status-quo fall-through confirmed live.
+4. Excel-style mixed payload (PNG rendition + `text/plain` TSV):
+   passed through; the TSV text was inserted, image ignored.
+5. Console: zero errors/warnings during the whole sequence.
+
+(Note: `defaultPrevented` is not a usable probe for pass-through cases
+— Monaco's own paste handler preventDefaults everything it processes;
+the inserted text is the discriminating evidence.)
+
 ## Open questions
 
 All resolved 2026-08-27 — see the decision log at the top of this
diff --git a/hub-client/changelog.md b/hub-client/changelog.md
index a7680441b..7e20759a7 100644
--- a/hub-client/changelog.md
+++ b/hub-client/changelog.md
@@ -25,6 +25,7 @@ WASM rebuild is needed for a changelog-only edit.
 
 ### 2026-08-27
 
+- [`e0e2d2bbc`](https://github.com/quarto-dev/q2/commits/e0e2d2bbc): Paste images directly into the source editor — Cmd/Ctrl-V with an image on the clipboard (a screenshot, a copied image, or a copied image file) uploads it next to the current document under an automatic content-based name and inserts the image reference at the cursor, with no dialog; selected text becomes the alt text. Text pastes and text-plus-image pastes (like spreadsheet cells) behave exactly as before, and SVG files still go through the upload dialog.
 - [`e279bc9c9`](https://github.com/quarto-dev/q2/commits/e279bc9c9): `local-prod:nginx` now accepts `--port` like plain `local-prod`, and starts correctly when `OIDC_CLIENT_ID` in your shell enables hub auth — the readiness check previously failed on the hub's 401 even though the hub was up.
 
 ### 2026-08-26

From 8c0f3584f1f0990064b192a842c5c654474bc62b Mon Sep 17 00:00:00 2001
From: Carlos Scheidegger <carlos.scheidegger@posit.co>
Date: Thu, 27 Aug 2026 13:07:47 -0500
Subject: [PATCH 4/4] Mark paste-image plan complete (bd-706b0ixu closed)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Bs2YW5vUbm1krBkQicB5nr
---
 claude-notes/plans/2026-08-27-paste-image-clipboard.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/claude-notes/plans/2026-08-27-paste-image-clipboard.md b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
index 783233319..03dccb1b3 100644
--- a/claude-notes/plans/2026-08-27-paste-image-clipboard.md
+++ b/claude-notes/plans/2026-08-27-paste-image-clipboard.md
@@ -2,7 +2,7 @@
 
 **Braid strand:** bd-706b0ixu
 **Created:** 2026-08-27
-**Status:** Approved — executing (design decisions resolved 2026-08-27)
+**Status:** Complete (implemented, verified E2E, strand closed 2026-08-27)
 **Follow-up strands:** bd-yspyic32 (mixed text+image payloads), bd-myoj9kp5
 (pipeline-wide SVG posture)
 
@@ -393,8 +393,8 @@ P2 could later become a project setting if paste-heavy projects ask for it.
       workspace Rust gates untouched-but-verified per pre-push checklist.
 - [x] **End-to-end verification** per CLAUDE.md — performed 2026-08-27
       against the production bundle in local-prod mode. See §6 below.
-- [ ] hub-client changelog entry (two-commit workflow).
-- [ ] Close bd-706b0ixu with pointers.
+- [x] hub-client changelog entry (two-commit workflow) — a32f8cdb1.
+- [x] Close bd-706b0ixu with pointers — closed 2026-08-27.
 
 ## 6. End-to-end verification record (2026-08-27)