feat(upload): Ctrl+V clipboard paste with preview, confirm, and progress on the web page (#72)

Pasting an image on the upload page now stages it instead of doing nothing:
a preview panel shows the image, its size, and which project it will be
sent to, and nothing uploads until the user confirms with Send. Send stays
disabled until a project pill is picked (the destination line says so),
picking a pill live-updates the target, and the upload itself runs over
XHR so a real progress bar + percentage track it, ending in a confirmed
"Pasted into <project> ✓" state (or a Retry-able error state). Cancel
discards the staged image; pastes are ignored mid-flight so an in-progress
upload can't be swapped out from under itself.

Verified live in a real Chrome (DevTools protocol) against the built page:
staging, gating, destination update, progress mid-states, success state,
auto-clear, error/Retry path, and Cancel all behave as specified.

Tests: a unit pin for the paste-UI page contract (panel, dest, bar,
Send/Cancel, paste listener), and a new browser-tier Playwright test that
synthesizes a ClipboardEvent with a real PNG and proves the full flow ends
with the byte-identical paste-*.png on disk plus live tmux injection.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: AminDhouib

CLAUDE.md

@@ -12,7 +12,7 @@ Open every project in its own terminal, launch an AI agent in it, and auto-tile
 - The `needs_ssh` tier is CI-only by design: `tests/e2e/test_ssh.py` (dry-run pins) + `tests/e2e/test_ssh_real.py` (REAL wire — every test traverses the loopback sshd that `.github/actions/setup-ssh-server` provisions, exporting `MDTEST_SSH_PORT`/`MDTEST_SSH_KEY`/`MDTEST_SSH_HOST` and an `mdssh` alias in the runner's real `~/.ssh/config`). Locally these skip because the env vars are absent — **never install/enable an SSH server on a dev machine to run them**. Tests that seed the ssh user's real HOME (the Windows attach flagship — attach can't inject `--config` remotely) are additionally gated on `GITHUB_ACTIONS=true` / `MDTEST_ALLOW_REAL_HOME=1`. macOS window-over-SSH legs are a loud `::warning` skip (see DESIGN.md known debt).
 - dist (packaged-install) locally: `pip install build` (not a dev extra; CI installs it per-job) then `pytest tests/dist/ -m dist` — builds a wheel, installs it into a pristine no-extras venv, and drives the real installed `multideck` entry point (proves the exact `pip install` user env; import-sweep catches dev/optional-dep leaks). Window-spawn leg is win32-only and skips elsewhere; wheel build + import sweep + virgin first-run + socket-real serve run on every OS.
 - Real-PTY menu tier (`tests/e2e/test_pty_menu.py`, marker `pty`, rides the existing `end-to-end` CI job on all 3 OSes): drives the installed `python -m multideck` under a genuine pseudo-terminal — pexpect on POSIX, pywinpty/ConPTY on Windows (`pywinpty>=2.0; sys_platform=='win32'` in the `dev` extra) — via the uniform driver `tests/e2e/_pty.py`, asserting on the plain on-screen text (ANSI stripped; children run `NO_COLOR=1`) and, for first-run, the valid config written to disk. This is the only test of the real `sys.stdin.isatty()` interactive path (`CliRunner` fakes the tty). Locally it runs anywhere pexpect/pywinpty resolve.
-- Browser-upload tier (`tests/e2e/test_upload_browser.py`, marker `browser`, dedicated `browser-upload` ubuntu job, CI-only, gated on `MDTEST_BROWSER=1`): a real headless Chromium (Playwright — the `browser` extra `["playwright>=1.40"]`, NOT in `dev`, provisioned only by that job via `playwright install --with-deps chromium`) drives the real mobile upload page against a real `multideck serve` on loopback and asserts the on-disk upload is byte-identical + the page title/form contract. Locally the module skips cleanly (no `MDTEST_BROWSER`, no Playwright). Honest gap: it symlinks real `tmux` as `psmux` and stands up a real tmux session as the multiplexer shim (Linux has no `psmux` binary) — see DESIGN.md.
+- Browser-upload tier (`tests/e2e/test_upload_browser.py`, marker `browser`, dedicated `browser-upload` ubuntu job, CI-only, gated on `MDTEST_BROWSER=1`): a real headless Chromium (Playwright — the `browser` extra `["playwright>=1.40"]`, NOT in `dev`, provisioned only by that job via `playwright install --with-deps chromium`) drives the real mobile upload page against a real `multideck serve` on loopback and asserts the on-disk upload is byte-identical + the page title/form contract + the Ctrl+V clipboard-paste confirm flow (synthetic ClipboardEvent → staged preview with Send gated on project selection → XHR upload → byte-identical `paste-*.png` on disk). Locally the module skips cleanly (no `MDTEST_BROWSER`, no Playwright). Honest gap: it symlinks real `tmux` as `psmux` and stands up a real tmux session as the multiplexer shim (Linux has no `psmux` binary) — see DESIGN.md.
 - The `needs_tailscale` tier is CI-only by design (`tests/e2e/test_tailnet_real.py` + the non-required `tailnet` ubuntu job): it joins a REAL ephemeral, tag-scoped Tailscale node (`tailscale/github-action`, SHA-pinned, OAuth via `TS_OAUTH_CLIENT_ID`/`TS_OAUTH_SECRET` + `tag:ci`) and exercises `tailnet.py`'s live `tailscale` probes (`ip4`/`magicdns_host`/`probe`) plus `multideck serve`'s Tailscale-facing default bind (`/health` answers on the real Tailscale IP; the LAN wildcard is proven unbound). Gated on `MDTEST_TAILSCALE=1` — locally it skips because the var is absent; **never install/join Tailscale on a dev machine to run it** (same posture as `needs_ssh`). The OAuth secrets don't exist yet: the job detects their absence and skips LOUDLY (`::warning`, job stays green, forks never fail) — once the user adds them it goes fully live with zero code change (one-time setup steps in the job comment). Excluded from the `end-to-end` job's SSH-less run exactly like `needs_ssh`.
 - The `monitor_lab` tier is CI-only by design (`tests/platform/test_monitor_lab_tiling.py` + the `monitor_lab` CI job, windows-latest): it INSTALLS the parsec-vdd virtual-display driver to fabricate a mixed-DPI multi-monitor topology, then drives real `--go` tiling across the virtual monitors and asserts each window rect lands in its `compute_grid` cell (physical pixels). Gated on `MDTEST_MONITOR_LAB=1` — locally it skips because the var is absent; **never install the driver / set the var on a dev machine to run it** (same posture as `needs_ssh`). The lab engine is `tests/platform/monitor_lab.py` (stdlib ctypes, win32-only, import-harmless on POSIX). The offline half — `tests/unit/test_monitor_lab_topologies.py` feeding committed golden topologies (`tests/platform/fixtures/topologies/*.json`) into `compute_grid` — runs everywhere in the normal unit gate. Two more CI-only Windows interaction tiers ride in the platform-integration windows leg (same never-on-a-dev-box posture): the `wt_cold` tier (`tests/platform/test_wt_cold_start.py`, gated `MDTEST_WT_COLD=1`) pins the first-ever `wt` launch on the fresh runner against the default settle+retry tiling budget — coldness is guaranteed by CI step ordering, so it must stay the first step that can spawn wt; and the `interaction` tier (`tests/platform/test_real_hotkey.py`, gated `MDTEST_INTERACTION=1`) drives the REAL Alt+V chain — product-spawned listener, real `SendInput` chord, real CF_DIB clipboard, real `serve` + psmux inject — and would stomp a dev machine's clipboard/keystrokes, so never set the var locally. The windows leg also installs pinned psmux (v3.3.6 release zip, sha256-verified, into `%LOCALAPPDATA%\psmux`) so `tests/platform/test_real_psmux.py` (lifecycle + full attach chain in a real wt window) runs instead of skipping. Riding in the same CI job (shared `lab` fixture + driver install via `tests/platform/conftest.py`): the doctor-replay tier — `multideck doctor --json` emits monitor topology under a `monitors` key, `tests/platform/doctor_replay.py` plans an achievable lab topology from a bug-report blob, `tests/platform/test_doctor_replay.py` replays committed sample reports (`tests/platform/fixtures/doctor_reports/*.json`) live, and `tests/unit/test_doctor_replay_offline.py` pins the parse/plan/slot math (incl. negative origins) everywhere.
 - Real-writer contract tier (`tests/e2e/test_state_sink_contract.py`, marker `node_contract`, rides the existing `end-to-end` job on all 3 OSes — node is preinstalled on every hosted runner, so no CI change): `npm install`s the pinned real agent-state writer package (`ai-agent-notifier@1.0.6` — see `AINS_VERSION`) into a tmp prefix, drives its REAL hook (`src/notify.mjs`) under real node with realistic Claude `Stop`/`Notification`/`SessionStart` events and a fully-redirected HOME, then checks multideck's real `agent_state` reader against it. It PINS a headline finding (F-NC-001): the package writes ZERO `~/.multideck/state/` records (it is a pure notifier; there is no `state-sink.mjs`) — so the tier currently asserts the store stays empty and flips RED if a wired hook ever starts writing records. Skips cleanly if node/npm or the npm registry are unavailable; tmp-dir only, never touches real `~/.multideck`/`~/.claude`.

README.md

@@ -142,7 +142,7 @@ Send screenshots from your phone straight into a project's agent session:
 "settings": { "psmux": true, "uploadServer": true, "uploadPort": 8033 }
 ```
 
-`multideck serve` (or `uploadServer: true` during launch) starts a small HTTP server; `multideck mobile` prints the phone URL + a QR code you can install as a home-screen app (the QR code needs the optional `qr` extra: `pip install multideck[qr]`). Pick a project on the phone, upload an image, and its path is pasted into that project's session. The Alt+V hotkey (Windows) does the same for whatever `md:` session is focused.
+`multideck serve` (or `uploadServer: true` during launch) starts a small HTTP server; `multideck mobile` prints the phone URL + a QR code you can install as a home-screen app (the QR code needs the optional `qr` extra: `pip install multideck[qr]`). Pick a project on the phone, upload an image, and its path is pasted into that project's session. On a desktop browser you can also **Ctrl+V** an image from the clipboard: the page stages it with a preview showing which project it will go to, waits for you to confirm with **Send**, and shows live upload progress until the "pasted into …" confirmation. The Alt+V hotkey (Windows) does the same for whatever `md:` session is focused.
 
 This works **over Tailscale**: the server binds only the loopback and your machine's Tailscale IP — never the LAN wildcard — and `attach`/`mobile`/`termius` shell out to the `tailscale` CLI to resolve hosts. Devices must be on your tailnet; there is deliberately no auth token, since the bind set is the access control. To bind something else (e.g. LAN-wide), use the escape hatch: `multideck serve --host 0.0.0.0`.
 

src/multideck/upload_server.py

@@ -188,6 +188,26 @@ def _flash(
 .drop.ok{border-color:#a6e3a1;color:#a6e3a1}
 .drop.err{border-color:#f38ba8;color:#f38ba8}
 .drop input{position:absolute;inset:0;opacity:0;cursor:pointer;font-size:0}
+.paste{display:none;margin-bottom:8px;border:1.5px solid #45475a;border-radius:10px;
+  padding:10px;background:#181825}
+.paste.show{display:block}
+.paste img{display:block;max-width:100%;max-height:40vh;border-radius:6px;
+  margin:0 auto 8px;background:#11111b}
+.paste-meta{display:flex;justify-content:space-between;gap:8px;font-size:.75rem;
+  color:#9399b2;margin-bottom:8px}
+#paste-dest{color:#89b4fa;font-weight:600}
+.bar{display:none;height:6px;border-radius:3px;background:#313244;overflow:hidden;
+  margin-bottom:8px}
+.bar.show{display:block}
+#bar-fill{height:100%;width:0%;background:#89b4fa;transition:width .15s}
+.paste-actions{display:flex;gap:8px}
+.paste-actions button{flex:1;padding:9px;border:none;border-radius:8px;
+  font-weight:700;font-size:.8rem;cursor:pointer}
+#paste-send{background:#a6e3a1;color:#1e1e2e}
+#paste-send:disabled{background:#45475a;color:#6c7086;cursor:not-allowed}
+#paste-send.ok{background:#a6e3a1}
+#paste-send.err{background:#f38ba8;color:#1e1e2e}
+#paste-cancel{background:#313244;color:#bac2de}
 .toast{font-size:.75rem;color:#6c7086;text-align:center;min-height:1.1em;
   transition:color .2s}
 .toast.ok{color:#a6e3a1}
@@ -205,7 +225,7 @@ def _flash(
 <body>
 <div class="head">
   <h1>MD</h1>
-  <span>tap project &rsaquo; tap file &rsaquo; done</span>
+  <span>tap project &rsaquo; tap file or Ctrl+V &rsaquo; done</span>
 </div>
 
 <div class="pills" id="pills">PROJECTS_PLACEHOLDER</div>
@@ -214,6 +234,19 @@ def _flash(
   <span id="drop-label">select a project first</span>
   <input type="file" id="file" accept="image/*,video/*,.pdf,.txt,.json,.csv,.log" disabled>
 </div>
+
+<div class="paste" id="paste-box">
+  <img id="paste-img" alt="pasted image">
+  <div class="paste-meta">
+    <span id="paste-dest"></span>
+    <span id="paste-size"></span>
+  </div>
+  <div class="bar" id="paste-bar"><div id="bar-fill"></div></div>
+  <div class="paste-actions">
+    <button id="paste-send" disabled>Send</button>
+    <button id="paste-cancel">Cancel</button>
+  </div>
+</div>
 <div class="toast" id="toast">&nbsp;</div>
 
 <div class="install" id="install">
@@ -287,6 +320,132 @@ def _flash(
     }
   }, 2000);
 });
+
+// Ctrl+V clipboard upload: stage the pasted image (preview + target project),
+// send only on explicit confirm, and show live upload progress. XHR instead of
+// fetch because only XHR exposes upload-progress events.
+const pbox = document.getElementById('paste-box');
+const pimg = document.getElementById('paste-img');
+const pdest = document.getElementById('paste-dest');
+const psize = document.getElementById('paste-size');
+const pbar = document.getElementById('paste-bar');
+const pfill = document.getElementById('bar-fill');
+const psend = document.getElementById('paste-send');
+const pcancel = document.getElementById('paste-cancel');
+let staged = null;
+let sending = false;
+
+function fmtSize(b) {
+  if (b < 1024) return b + ' B';
+  if (b < 1048576) return (b / 1024).toFixed(1) + ' KB';
+  return (b / 1048576).toFixed(1) + ' MB';
+}
+
+function refreshPaste() {
+  if (!staged) return;
+  pdest.textContent = proj ? '→ ' + proj : 'select a project above';
+  psend.disabled = sending || !proj;
+}
+pills.forEach(p => p.addEventListener('click', refreshPaste));
+
+function clearStage() {
+  if (staged) URL.revokeObjectURL(staged.url);
+  staged = null;
+  sending = false;
+  pbox.className = 'paste';
+  pbar.className = 'bar';
+  pfill.style.width = '0%';
+  psend.className = '';
+  psend.textContent = 'Send';
+  psend.disabled = true;
+  pcancel.disabled = false;
+}
+
+window.addEventListener('paste', e => {
+  if (sending) return;  // never swap the image out from under an upload
+  const items = (e.clipboardData || {}).items || [];
+  for (const it of items) {
+    if (it.kind === 'file' && it.type.startsWith('image/')) {
+      e.preventDefault();
+      stageFile(it.getAsFile());
+      return;
+    }
+  }
+});
+
+function stageFile(file) {
+  if (staged) URL.revokeObjectURL(staged.url);
+  const ext = (file.type.split('/')[1] || 'png').replace('jpeg', 'jpg');
+  const ts = new Date().toISOString().replace(/[-:]/g, '').slice(0, 15);
+  staged = {file: file, url: URL.createObjectURL(file),
+            name: 'paste-' + ts + '.' + ext};
+  pimg.src = staged.url;
+  psize.textContent = fmtSize(file.size);
+  pfill.style.width = '0%';
+  pbar.className = 'bar';
+  psend.className = '';
+  psend.textContent = 'Send';
+  pbox.className = 'paste show';
+  toast.textContent = '\u00a0';
+  toast.className = 'toast';
+  refreshPaste();
+}
+
+function pasteFail(msg) {
+  sending = false;
+  psend.className = 'err';
+  psend.textContent = 'Retry';
+  psend.disabled = false;
+  pcancel.disabled = false;
+  toast.textContent = msg;
+  toast.className = 'toast err';
+}
+
+psend.addEventListener('click', () => {
+  if (!staged || !proj || sending) return;
+  sending = true;
+  psend.className = '';
+  psend.disabled = true;
+  pcancel.disabled = true;
+  psend.textContent = 'Sending 0%';
+  pbar.className = 'bar show';
+
+  const form = new FormData();
+  form.append('file', staged.file, staged.name);
+  form.append('project', proj);
+  form.append('inject', '1');
+
+  const xhr = new XMLHttpRequest();
+  xhr.open('POST', '/upload');
+  xhr.upload.addEventListener('progress', ev => {
+    if (!ev.lengthComputable) return;
+    const pct = Math.round(ev.loaded / ev.total * 100);
+    pfill.style.width = pct + '%';
+    psend.textContent = 'Sending ' + pct + '%';
+  });
+  xhr.addEventListener('load', () => {
+    let d = {};
+    try { d = JSON.parse(xhr.responseText); } catch (e) {}
+    if (xhr.status === 200 && d.ok) {
+      pfill.style.width = '100%';
+      psend.className = 'ok';
+      psend.textContent = (d.injected ? 'Pasted into ' + proj : 'Sent') + ' ✓';
+      toast.textContent = staged.name
+        + (d.injected ? ' pasted into ' + proj : ' sent');
+      toast.className = 'toast ok';
+      setTimeout(clearStage, 2500);
+    } else {
+      pasteFail(d.error || 'upload failed');
+    }
+  });
+  xhr.addEventListener('error', () => pasteFail('network error'));
+  xhr.send(form);
+});
+
+pcancel.addEventListener('click', () => {
+  if (sending) return;
+  clearStage();
+});
 </script>
 
 <script>

tests/e2e/test_upload_browser.py

@@ -26,6 +26,7 @@
 
 from __future__ import annotations
 
+import base64
 import http.client
 import json
 import os
@@ -307,3 +308,64 @@ def test_real_browser_upload_lands_byte_identical_file(serve, page, tmp_path):
     assert len(landed) == 1, f"expected exactly one upload, got {landed}"
     assert landed[0].read_bytes() == expected, "uploaded bytes differ on disk"
     assert landed[0].name.endswith("shot.png"), landed[0].name
+
+
+def test_clipboard_paste_upload_confirms_and_lands_byte_identical(
+    serve, page, tmp_path
+):
+    """The Ctrl+V flow in a real browser: a paste event stages the image with
+    a visible preview, the confirm step holds the upload back until a project
+    is picked (Send disabled, destination line says so), picking the project
+    names it as the target, and confirming uploads — ending in the confirmed
+    success state with the exact pasted bytes on disk.
+
+    The paste itself is a synthesized ClipboardEvent (headless Chromium has no
+    OS clipboard to press Ctrl+V against); everything downstream of the event
+    — staging, preview, confirm gating, XHR POST, tmux injection, file write —
+    is the real product path."""
+    png_path = tmp_path / "clip.png"
+    expected = _make_png(png_path)
+
+    page.goto(serve.url)
+    expect(page).to_have_title("md upload")
+
+    page.evaluate(
+        """(b64) => {
+          const bytes = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
+          const dt = new DataTransfer();
+          dt.items.add(new File([bytes], 'clip.png', {type: 'image/png'}));
+          window.dispatchEvent(new ClipboardEvent('paste', {clipboardData: dt}));
+        }""",
+        base64.b64encode(expected).decode(),
+    )
+
+    # Staged: preview panel up, image shown, but NOT sent — no project yet.
+    expect(page.locator("#paste-box")).to_be_visible()
+    expect(page.locator("#paste-img")).to_be_visible()
+    expect(page.locator("#paste-send")).to_be_disabled()
+    expect(page.locator("#paste-dest")).to_contain_text("select a project")
+
+    # Picking the project flips the destination line and arms Send.
+    page.locator(".pill", has_text=serve.TITLE).click()
+    expect(page.locator("#paste-dest")).to_contain_text(serve.TITLE)
+    expect(page.locator("#paste-send")).to_be_enabled()
+
+    page.locator("#paste-send").click()
+
+    # Confirmed: the button lands in the success state and the toast names the
+    # live injection target (a real tmux session behind the psmux shim).
+    expect(page.locator("#paste-send")).to_contain_text("✓")
+    expect(page.locator("#toast")).to_contain_text("pasted into " + serve.TITLE)
+
+    landed = _wait_until(
+        lambda: (
+            sorted(serve.uploads_dir.glob("*")) if serve.uploads_dir.is_dir() else []
+        ),
+        timeout=10,
+    )
+    assert landed, f"no file landed in {serve.uploads_dir}"
+    assert len(landed) == 1, f"expected exactly one upload, got {landed}"
+    assert landed[0].read_bytes() == expected, "pasted bytes differ on disk"
+    assert "paste-" in landed[0].name and landed[0].name.endswith(".png"), landed[
+        0
+    ].name

tests/unit/test_upload_server.py

@@ -37,6 +37,24 @@ def test_pill_wire_value_is_session_id(self):
         html = _build_html([{"name": "my.api", "session": "my-api", "path": "x"}])
         assert 'data-name="my-api"' in html
 
+    def test_clipboard_paste_ui_ships_on_the_page(self):
+        # Ctrl+V flow contract: the staged-image confirm panel (preview img,
+        # destination-project line, progress bar, explicit Send/Cancel) and the
+        # window paste listener must all be present in the served page. The
+        # real-browser behavioural proof lives in the `browser` e2e tier.
+        html = _build_html([{"name": "p", "path": "x"}])
+        for anchor in (
+            'id="paste-box"',
+            'id="paste-img"',
+            'id="paste-dest"',
+            'id="paste-bar"',
+            'id="paste-send"',
+            'id="paste-cancel"',
+            "addEventListener('paste'",
+            "XMLHttpRequest",
+        ):
+            assert anchor in html, f"paste-upload UI anchor missing: {anchor}"
+
 
 class TestConfigSessions:
     def test_carries_display_name_and_sanitized_session(self, tmp_path):