From 8ea9c668f8af2d156c737037f2922acd4f2c081b Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Thu, 11 Jun 2026 23:32:27 -0700
Subject: [PATCH 01/25] Allow framing in dor iframe surfaces and fix blank-pane
 footguns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The webview CSP was `default-src 'none'` with no frame-src, so every
<iframe> the IframePanel mounted was blocked outright — producing a blank
white pane for any `dor iframe <url>`. Add `frame-src http: https:`
(parseIframeUrl already constrains inputs to http/https).

Also fix two things that sent debugging down the wrong path:
- iframe command help examples used https://localhost:5173, wrong for a
  typical dev server; switch to http:// (+ snapshot).
- IframePanel now shows a stall hint if the frame hasn't loaded within
  5s, since cross-origin frames never report errors to the embedder.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 dor/src/commands/iframe.ts              |  6 ++--
 dor/test/snapshots/help/iframe.md       |  6 ++--
 lib/src/components/wall/IframePanel.tsx | 42 +++++++++++++++++++------
 vscode-ext/src/webview-html.ts          |  5 +++
 4 files changed, 44 insertions(+), 15 deletions(-)

diff --git a/dor/src/commands/iframe.ts b/dor/src/commands/iframe.ts
index ac7b7e17..18a93649 100644
--- a/dor/src/commands/iframe.ts
+++ b/dor/src/commands/iframe.ts
@@ -34,15 +34,15 @@ If the caller surface is an untouched terminal, Dormouse replaces that terminal
 The URL must be an absolute http:// or https:// URL. Dormouse does not infer schemes.
 
 Text output:
-  created surface:3  "https://localhost:5173"
-  replaced surface:1  "https://localhost:5173"
+  created surface:3  "http://localhost:5173"
+  replaced surface:1  "http://localhost:5173"
 
 JSON output:
   {
     "status": "created",
     "surface_id": "pane-abc",
     "surface_ref": "surface:3",
-    "url": "https://localhost:5173",
+    "url": "http://localhost:5173",
     "minimized": false
   }`,
     },
diff --git a/dor/test/snapshots/help/iframe.md b/dor/test/snapshots/help/iframe.md
index 3a4fedde..899e1562 100644
--- a/dor/test/snapshots/help/iframe.md
+++ b/dor/test/snapshots/help/iframe.md
@@ -14,15 +14,15 @@ If the caller surface is an untouched terminal, Dormouse replaces that terminal
 The URL must be an absolute http:// or https:// URL. Dormouse does not infer schemes.
 
 Text output:
-  created surface:3  "https://localhost:5173"
-  replaced surface:1  "https://localhost:5173"
+  created surface:3  "http://localhost:5173"
+  replaced surface:1  "http://localhost:5173"
 
 JSON output:
   {
     "status": "created",
     "surface_id": "pane-abc",
     "surface_ref": "surface:3",
-    "url": "https://localhost:5173",
+    "url": "http://localhost:5173",
     "minimized": false
   }
 
diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index b2220aef..5e838f8a 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -1,4 +1,4 @@
-import { useContext, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import { useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
 import {
@@ -26,6 +26,22 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
     }
   }, [url]);
 
+  // A cross-origin iframe never reports HTTP errors or CSP/X-Frame-Options
+  // blocks to us — onError doesn't fire, and onLoad fires even for a blocked
+  // frame. So we can't detect failure directly; instead we surface a hint if
+  // the frame hasn't reported a load within a few seconds, which covers the
+  // common dead ends (server down, wrong scheme, refused framing) without
+  // hiding a slow-but-fine page once it loads.
+  const [loaded, setLoaded] = useState(false);
+  const [stalled, setStalled] = useState(false);
+  useEffect(() => {
+    setLoaded(false);
+    setStalled(false);
+    if (!url) return;
+    const timer = setTimeout(() => setStalled(true), 5000);
+    return () => clearTimeout(timer);
+  }, [url]);
+
   useEffect(() => {
     if (!elRef.current) return;
     paneElements.set(api.id, elRef.current);
@@ -60,17 +76,25 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
   return (
     <div
       ref={elRef}
-      className={`h-full w-full overflow-hidden bg-terminal-bg ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
+      className={`relative h-full w-full overflow-hidden bg-terminal-bg ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
       onMouseDown={() => actions.onClickPanel(api.id)}
     >
       {url ? (
-        <iframe
-          className="block h-full w-full border-0 bg-white"
-          src={url}
-          title={api.title ?? url}
-          allow="autoplay; clipboard-read; clipboard-write; fullscreen; geolocation; microphone; camera"
-          referrerPolicy={origin ? 'strict-origin-when-cross-origin' : undefined}
-        />
+        <>
+          <iframe
+            className="block h-full w-full border-0 bg-white"
+            src={url}
+            title={api.title ?? url}
+            allow="autoplay; clipboard-read; clipboard-write; fullscreen; geolocation; microphone; camera"
+            referrerPolicy={origin ? 'strict-origin-when-cross-origin' : undefined}
+            onLoad={() => setLoaded(true)}
+          />
+          {!loaded && stalled && (
+            <div className="pointer-events-none absolute inset-x-0 bottom-0 bg-terminal-bg/90 px-4 py-2 text-xs text-muted">
+              Still loading <span className="font-semibold">{url}</span> — if it stays blank, the server may be down, on a different scheme (http vs https), or refusing to be embedded in a frame.
+            </div>
+          )}
+        </>
       ) : (
         <div className="flex h-full w-full items-center justify-center bg-terminal-bg px-4 text-sm text-muted">
           No iframe URL was provided.
diff --git a/vscode-ext/src/webview-html.ts b/vscode-ext/src/webview-html.ts
index 5c0a0563..ee5fcb5c 100644
--- a/vscode-ext/src/webview-html.ts
+++ b/vscode-ext/src/webview-html.ts
@@ -30,6 +30,11 @@ export function getWebviewHtml(
     `font-src ${webview.cspSource}`,
     `img-src ${webview.cspSource} data: blob:`,
     `connect-src ${webview.cspSource}`,
+    // `dor iframe` opens arbitrary absolute http(s) URLs in an iframe surface.
+    // Without a frame-src override the `default-src 'none'` fallback blocks the
+    // frame outright, leaving a blank (white) pane. parseIframeUrl already
+    // constrains inputs to http:/https:.
+    `frame-src http: https:`,
   ].join('; ');
 
   html = html.replace(

From bbbff8cf51c6a0c23f0f344b6709e69d798a21fc Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Thu, 11 Jun 2026 23:43:27 -0700
Subject: [PATCH 02/25] Document dor iframe surface limitations and provisional
 status

The iframe surface conflicts with Dormouse's single-document input/focus
model in ways mostly inherent to cross-origin frames (focused frame owns
the keyboard; parent can't intercept; framing refusals give no error
signal). Record these in the spec, mark the surface provisional, and note
the likely path is an agent-browser surface instead of shipping iframe.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-cli.md | 50 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/docs/specs/dor-cli.md b/docs/specs/dor-cli.md
index 8b093bd7..c5f8f89c 100644
--- a/docs/specs/dor-cli.md
+++ b/docs/specs/dor-cli.md
@@ -133,6 +133,56 @@ Invariants:
 - Workspace/window refs and target flags will be added only when Dormouse
   actually supports them.
 
+## Iframe Surface: Limitations And Status
+
+> Status: **provisional.** The `dor iframe` surface works for displaying a page,
+> but has structural limitations (below) that may keep it from shipping. The
+> likely path forward is to ship an **agent-browser** surface instead — a
+> Dormouse-controlled browser view (see `lib/src/components/wall/AgentBrowserPanel.tsx`)
+> that does not embed a foreign page as a peer browsing context — and to drop or
+> hide `dor iframe`. Do not build features on top of the iframe surface until
+> this is resolved.
+
+An `<iframe>` pointed at an arbitrary URL is a **separate browsing context** from
+the Wall. Dormouse's input, focus, and attention model assumes a single
+same-document context, so the iframe surface conflicts with it in ways that are
+inherent to the browser, not bugs we can patch away:
+
+- **Focus leaves Dormouse entirely.** When the iframe gains focus, a focused
+  cross-origin frame owns the keyboard. Its keystrokes fire in *its* document and
+  never reach the parent. Dormouse's global shortcuts are a capturing `window`
+  keydown listener (`lib/src/components/wall/use-wall-keyboard.ts`), so dual-tap-⌘,
+  pane navigation, split, and kill all go dead until focus returns to the Wall.
+  The same-origin policy means the parent cannot observe or intercept those keys —
+  this cannot be fixed, only designed around (e.g. a click-to-interact overlay, or
+  an accept-focus model with a mouse-driven escape affordance).
+
+- **The app reads iframe-focus as being backgrounded.** Focusing the iframe fires
+  a `blur` on the parent `window`. Current handlers treat that as the whole app
+  losing focus: `Wall.tsx` clears cross-session attention, and
+  `use-window-focused.ts` flips `windowFocused` to `false`, which drives the
+  active styling (e.g. `SurfacePaneHeader.tsx`'s `isActiveHeader`). The result is
+  every header/focus-ring goes inactive and attention clears the instant the
+  iframe is focused. This part *is* fixable (distinguish `document.activeElement`
+  being one of our own iframes from a real window blur) but is not yet done.
+
+- **No programmatic focus handle.** `focusSession` (`lib/src/lib/terminal-lifecycle.ts`)
+  only knows xterm terminals in a registry. The iframe pane is not registered, so
+  `onClickPanel → enterTerminalMode → focusSession(iframeId)` is a no-op: Dormouse
+  cannot focus the iframe programmatically and cannot tell when it is focused.
+
+- **Some sites refuse to be framed, with no error signal.** Servers that send
+  `X-Frame-Options` or a CSP `frame-ancestors` directive cannot be embedded at
+  all, yielding a blank pane. Cross-origin frames do not report load errors to the
+  embedder (`onError` never fires; `onLoad` fires even for a blocked frame), so the
+  surface cannot reliably distinguish "loading", "blocked", and "broken". The
+  current `IframePanel` shows a best-effort stall hint after a timeout only.
+
+- **The VS Code webview must opt into framing.** The webview CSP
+  (`vscode-ext/src/webview-html.ts`) is `default-src 'none'`; without a `frame-src`
+  directive every `<iframe>` is blocked outright (blank white pane). A
+  `frame-src http: https:` allowance is required for the surface to render at all.
+
 ## Current Implemented Commands
 
 Implemented commands call private `surface.*` control methods. `surface.list`

From cf72ab0b464d166e57738148b0975da8db1c7eb1 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 14:08:54 -0700
Subject: [PATCH 03/25] Spec the dor agent-browser surface as the iframe
 alternative
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add docs/specs/dor-agent-browser.md: dor ab delegates 100% to the user's
agent-browser install, rendered in a Dormouse-native canvas surface
(viewer client, not a fork) — so it keeps Dormouse's focus model where the
iframe surface can't. Covers the workspace-scoped --key model, the
session:surface registry, in-surface tab presentation, lifecycle, and the
frames/input/tabs delegated channels. Cross-link it from dor-cli.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md | 199 ++++++++++++++++++++++++++++++++
 docs/specs/dor-cli.md           |   8 +-
 2 files changed, 205 insertions(+), 2 deletions(-)
 create mode 100644 docs/specs/dor-agent-browser.md

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
new file mode 100644
index 00000000..8afd8b11
--- /dev/null
+++ b/docs/specs/dor-agent-browser.md
@@ -0,0 +1,199 @@
+# Dor Agent-Browser Surface
+
+> See `docs/specs/glossary.md` for canonical Session and Pane vocabulary, and
+> `docs/specs/dor-cli.md` for the shared `dor` CLI, surface handle model, and
+> host control plumbing this surface builds on.
+
+`dor agent-browser` (alias `dor ab`) shows a live, interactive browser **inside**
+Dormouse by delegating 100% to the user's own
+[agent-browser](https://github.com/vercel-labs/agent-browser) install. It is a
+**viewer client, not a fork**: every piece of browser behavior — Chromium, CDP,
+the screencast, the entire command surface — stays in `agent-browser`. Dormouse
+adds only a thin surface that renders the session's video stream, forwards input,
+and presents tabs. We reimplement none of agent-browser's behavior, the same way
+an HTTP client is not a fork of the server.
+
+This is the chosen alternative to the iframe surface (see
+`dor-cli.md` → "Iframe Surface: Limitations And Status"). Because the browser
+renders to a Dormouse-owned `<canvas>` rather than a cross-origin `<iframe>`,
+Dormouse keeps its own keydown listener and never loses focus control: the
+keyboard model that breaks for iframes does not apply here.
+
+## Delegation Boundary
+
+`dor ab` resolves the user's `agent-browser` binary on `PATH` (override with
+`DORMOUSE_AGENT_BROWSER_BIN`). It is **not bundled or vendored**; if it is
+missing, the command fails with an install hint
+(`npm i -g agent-browser`). The version is therefore always the user's own —
+commands and the stream protocol are version-matched by construction.
+
+`dor ab <args...>` is a near-transparent passthrough to `agent-browser <args...>`.
+Dormouse intercepts exactly one flag — `--key` (below) — translating it to an
+`agent-browser --session` selector; every other argument is forwarded verbatim,
+including subcommands that do not exist yet. Three behaviors are delegated rather
+than reimplemented:
+
+| Concern | Delegated to |
+| --- | --- |
+| Video (frames) | agent-browser session **stream** WebSocket |
+| Input (mouse/keyboard) | **CDP** `Input.*`, proxied by the Dormouse host |
+| Tabs | agent-browser **`tab list` / `tab <n>` / `tab close`** |
+
+## The `--key` Model
+
+`--key <name>` is the primary interface. It is **workspace-scoped** and defaults
+to `--key default`, so a human running `dor ab` and a coding agent running
+`dor ab` from any terminal in the same workspace land on the **same** browser
+surface. This is the 80% case: one browser everyone iterates on. A second
+concurrent browser is one flag away:
+
+```
+dor ab open http://localhost:5173        # → key "default"
+dor ab --key storybook open http://localhost:6006
+dor ab click @e3                          # drives key "default"
+dor ab --key storybook reload             # drives key "storybook"
+```
+
+Workspace scoping is automatic: `dor ab` routes its control request to the Wall
+that owns the invoking terminal surface, and the Wall is per-workspace, so key
+resolution is scoped to the right workspace with no extra plumbing.
+
+### Key → session naming
+
+A managed `--key` maps to a namespaced agent-browser session:
+
+```
+session = "dormouse/<workspaceId>/<key>"
+```
+
+`<workspaceId>` is hardcoded `1` until Dormouse exposes real workspaces (see
+`dor-cli.md` → Handle Model); it is encoded now to avoid a later rename.
+Namespacing keeps managed keys from colliding with sessions a user created
+directly via plain `agent-browser`.
+
+### `--key` vs raw `--session`
+
+`--key` (managed, namespaced) and `--session` (your point 2: attach to a session
+by its literal agent-browser name) are **mutually exclusive**. `--key default`
+applies only when neither is given. `--session <raw>` is the bring-your-own
+escape hatch for attaching to a session some other tool created; Dormouse still
+opens/reuses a surface for it but performs no namespacing.
+
+## Session ↔ Surface Mapping
+
+The session name is the single source of truth. The Wall holds a registry:
+
+```
+key (or raw session) → { session, surfaceId }
+```
+
+- **1:1, auto-managed.** The first `dor ab` for a session with no surface creates
+  a browser surface (split next to the caller, same placement rule as
+  `dor iframe`). Later commands for that session reuse it. No 1:many mirroring.
+- **Two namespaces, reconciled.** Every other `dor` command addresses a *surface*
+  (`surface:3`, `title:…`); agent-browser addresses a *session*. Driving the
+  browser is **session-keyed exclusively** (via `--key`/`--session`). Layout
+  commands (`dor split`, `dor kill`, move) still treat the pane as an ordinary
+  surface. The pane is addressable two ways for two purposes; there is no
+  dual-identity ambiguity because only one namespace ever drives the browser.
+- **Targeting by surface is supported but secondary.** A surface ref resolves
+  *to* its bound session; `--key` remains the primary interface.
+
+## Tabs
+
+A session may have any number of tabs (page targets). Dormouse has no tab model
+and gains none: **one session is always exactly one surface**, regardless of tab
+count. Tabs live entirely inside that surface's chrome.
+
+- **Integrated mode (1 tab):** the page title sits in the Dormouse surface
+  header. No tab strip — the pretty, default case.
+- **Multi-tab mode (≥2 tabs):** a tab strip renders *below* the Dormouse header,
+  inside the surface body (title + favicon + close `×` per tab; no manual "+").
+  The strip is a thin view over `agent-browser tab list`; selecting a tab issues
+  `tab <n>` (the frame stream and CDP input follow the active target because
+  "active tab" is an agent-browser operation); the `×` issues `tab close`. When
+  the session returns to one tab, the surface drops back to integrated mode.
+- **Orthogonal to minimize.** Internal tab count is invisible when the surface is
+  minimized: title-only along the bottom whether it holds 1 tab or 9. Dormouse's
+  binary "you're looking at it or you're not" model is preserved.
+
+Tab behaviors:
+
+- **`dor ab open <url>` navigates the active tab; it does not spawn one.** New
+  tabs arrive only from the web (popups, `target=_blank`) or an explicit
+  `dor ab tab new`. The agent drives the active tab; the web spawns extras —
+  which is what naturally moves the surface into multi-tab mode.
+- **Web-opened tabs are focused** (enter multi-tab mode, select the newest),
+  matching typical browser foregrounding; reversible by clicking back. Dormouse
+  does not fight the web's popup / open-in-new-tab behavior.
+
+## Lifecycle
+
+Surface lifetime and browser lifetime are bound, both directions:
+
+- **Kill the surface → close the browser.** `dor kill` / the header `×` /
+  `dor ab … close` tears down the session (`agent-browser --session <resolved>
+  close`).
+- **Session dies externally → tear down the surface.** If the browser exits
+  (crash, or a plain `agent-browser close` elsewhere), the stream reports
+  `connected: false`; the Wall removes or placeholders the surface.
+
+## Channels
+
+Mirrors the validated `~/Documents/dev/agent-proto` prototype.
+
+### Frames (out)
+
+The webview connects directly to the session stream WebSocket and renders frames
+to a `<canvas>`:
+
+- Port discovery: `agent-browser --session <s> stream status --json` →
+  `{ "port": <n>, ... }` ⇒ `ws://127.0.0.1:<n>`. Streaming is always enabled;
+  `AGENT_BROWSER_STREAM_PORT` pins a port.
+- Frame message: `{ "type": "frame", "data": "<base64 jpeg>", "metadata": {
+  deviceWidth, deviceHeight, pageScaleFactor, scrollOffsetX, scrollOffsetY, … } }`.
+  Decode → `drawImage`; map pointer coordinates through `metadata` device size vs
+  canvas size.
+
+### Input (in)
+
+Chrome refuses CDP WebSocket connections from regular http(s) origins, so the
+webview **cannot** speak CDP directly. Input is proxied by the Dormouse host
+(sidecar / `pty-host`, the same process that already bridges control requests):
+the host holds one persistent browser-level CDP WebSocket plus a flattened
+`Target.attachToTarget` session and dispatches `Input.dispatchMouseEvent` /
+`Input.dispatchKeyEvent`. The host re-resolves the active page target on
+navigation (the prototype's `/cdp-target`).
+
+Focus behaves like a terminal surface: click-to-focus; keystrokes forward to the
+browser only while the surface is selected and in interact mode. Because Dormouse
+owns the keydown listener (unlike an iframe), the leader chord always returns
+control to the Wall.
+
+### Tabs
+
+`agent-browser tab list` (strip contents), `tab <n>` (switch), `tab close`
+(per-tab `×`) — all verbatim passthrough.
+
+## Implementation Touchpoints
+
+| Piece | Location |
+| --- | --- |
+| `dor ab` command (passthrough + `--key` intercept) | `dor/src/commands/agent-browser.ts` (new) |
+| Control method `surface.agentBrowser` request/response | `dor/src/commands/types.ts`, `dor/src/control-client.ts` (mirror `surface.iframe`, types.ts:109, control-client.ts:71) |
+| Surface component (canvas viewer + WS client + tab strip) | `lib/src/components/wall/AgentBrowserPanel.tsx` (currently a stub) |
+| Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
+| Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
+| CDP input proxy | host: `standalone/sidecar/*`, `vscode-ext/src/pty-host.js` |
+
+## VS Code Webview CSP
+
+The VS Code webview CSP (`vscode-ext/src/webview-html.ts`) must allow the stream
+WebSocket:
+
+```
+connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>
+```
+
+The canvas is drawn from base64 frame data, so no `img-src` change is needed, and
+no `frame-src` is involved — there is no iframe.
diff --git a/docs/specs/dor-cli.md b/docs/specs/dor-cli.md
index c5f8f89c..5ab612be 100644
--- a/docs/specs/dor-cli.md
+++ b/docs/specs/dor-cli.md
@@ -140,8 +140,9 @@ Invariants:
 > likely path forward is to ship an **agent-browser** surface instead — a
 > Dormouse-controlled browser view (see `lib/src/components/wall/AgentBrowserPanel.tsx`)
 > that does not embed a foreign page as a peer browsing context — and to drop or
-> hide `dor iframe`. Do not build features on top of the iframe surface until
-> this is resolved.
+> hide `dor iframe`. That surface is specified in
+> [dor-agent-browser.md](dor-agent-browser.md). Do not build features on top of
+> the iframe surface until this is resolved.
 
 An `<iframe>` pointed at an arbitrary URL is a **separate browsing context** from
 the Wall. Dormouse's input, focus, and attention model assumes a single
@@ -213,5 +214,8 @@ from `command-detail`.
 - `dor read` [impl](../../dor/src/commands/read.ts) [docs](../../dor/test/snapshots/help/read.md)
 - `dor kill` [impl](../../dor/src/commands/kill.ts) [docs](../../dor/test/snapshots/help/kill.md)
 - `dor iframe` [impl](../../dor/src/commands/iframe.ts) [docs](../../dor/test/snapshots/help/iframe.md)
+- `dor agent-browser` / `dor ab` — delegates to the user's `agent-browser`,
+  rendered in a Dormouse-native surface; see [dor-agent-browser.md](dor-agent-browser.md)
+  (the chosen alternative to the iframe surface)
 - `dor list-panes` [impl](../../dor/src/commands/list-panes.ts) [docs](../../dor/test/snapshots/help/list-panes.md)
 - `dor list-pane-surfaces` [impl](../../dor/src/commands/list-pane-surfaces.ts) [docs](../../dor/test/snapshots/help/list-pane-surfaces.md)

From 287d25bd9473daa27284748361276c4aafd7466f Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 14:28:44 -0700
Subject: [PATCH 04/25] =?UTF-8?q?dor=20ab:=20passthrough=20CLI=20with=20--?=
 =?UTF-8?q?key=E2=86=92session=20translation=20(Phase=201)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spike outcome: agent-browser's stream WS natively accepts input_mouse/
input_keyboard (verified 0.27.0), so the host CDP proxy is eliminated.
Session names cannot contain '/', so managed keys map to
dormouse.<workspaceId>.<key>. The stream WS rejects non-localhost Origins,
so VS Code will need a loopback origin-stripping relay (Phase 7).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md                          | 261 ++++++++++++++++++
 docs/specs/dor-agent-browser.md               |  63 ++++-
 dor/src/cli.ts                                |  29 +-
 dor/src/commands/agent-browser.ts             | 232 ++++++++++++++++
 dor/src/commands/types.ts                     |  28 ++
 dor/src/control-client.ts                     |   6 +
 dor/src/node-runtime.d.ts                     |  15 +
 dor/test/cli-output.test.mjs                  | 116 ++++++++
 .../agent-browser-key-session-conflict.snap   |   5 +
 .../agent-browser-missing-binary.snap         |   5 +
 .../snapshots/agent-browser-passthrough.snap  |   6 +
 dor/test/snapshots/help/agent-browser.md      |  41 +++
 dor/test/snapshots/help/dor.md                |   2 +
 13 files changed, 793 insertions(+), 16 deletions(-)
 create mode 100644 DOR_AGENT_BROWSER.md
 create mode 100644 dor/src/commands/agent-browser.ts
 create mode 100644 dor/test/snapshots/agent-browser-key-session-conflict.snap
 create mode 100644 dor/test/snapshots/agent-browser-missing-binary.snap
 create mode 100644 dor/test/snapshots/agent-browser-passthrough.snap
 create mode 100644 dor/test/snapshots/help/agent-browser.md

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
new file mode 100644
index 00000000..5b5e86fe
--- /dev/null
+++ b/DOR_AGENT_BROWSER.md
@@ -0,0 +1,261 @@
+# DOR_AGENT_BROWSER — Implementation Plan
+
+Implementation plan for the `dor agent-browser` / `dor ab` surface.
+
+**Design spec (read first):** [`docs/specs/dor-agent-browser.md`](docs/specs/dor-agent-browser.md).
+This plan does not restate the design — it sequences the build and says how to
+verify each step. When the plan and the spec disagree, the spec wins; if the
+build forces a design change, update the spec in the same commit.
+
+**Reference prototype:** `~/Documents/dev/agent-proto` (`serve.mjs` + `viewer.html`).
+A working end-to-end viewer: stream-WS frames + CDP-proxied input + active-target
+re-resolution. Treat it as the source of truth for the channel mechanics.
+
+---
+
+## Locked decisions (do not relitigate)
+
+These are settled in the spec; the implementation follows them:
+
+- Viewer client, **not a fork**. Resolve the user's `agent-browser` on `PATH`
+  (`DORMOUSE_AGENT_BROWSER_BIN` override); never bundle it.
+- `--key <name>` is primary, workspace-scoped, default `default`; maps to session
+  `dormouse/<workspaceId>/<key>` (`workspaceId` hardcoded `1`). Mutually exclusive
+  with raw `--session`.
+- Session is the join key; **1:1 with an auto-managed surface**; no 1:many.
+- Surface kill ↔ session close, both directions.
+- One session = one surface regardless of tab count; tabs live **inside** the
+  surface (integrated vs multi-tab strip), orthogonal to minimize.
+- Three delegated channels: frames (stream WS), input (CDP via host proxy — but
+  see the spike below), tabs (`tab list/<n>/close`).
+
+---
+
+## Dev loop & prerequisites
+
+- `agent-browser` installed on PATH (`agent-browser --version`; tested against
+  `0.27.0`). `npm i -g agent-browser` if missing.
+- CLI-only iteration: `cd dor && pnpm build && node --test test/cli-output.test.mjs`.
+- Full app: `pnpm build:vscode` then `pnpm --filter dormouse dogfood`, reload the
+  VS Code window. (`dogfood:vscode` does **not** exist at the repo root.)
+- Manual channel checks against a live session:
+  ```
+  agent-browser --session dormouse/1/default open http://localhost:5173
+  agent-browser --session dormouse/1/default stream status --json   # → { port }
+  agent-browser --session dormouse/1/default tab list --json
+  ```
+
+---
+
+## Architecture at a glance
+
+```
+dor ab <args>  ──(resolve --key→session, exec)──▶  agent-browser  (user's binary)
+      │
+      └─(control: surface.agentBrowser {key,session,wsPort})─▶ Wall registry → surface
+                                                                      │
+AgentBrowserPanel (webview):                                          │
+  • frames:  ws://127.0.0.1:<port>  ──── direct ───▶  canvas          │
+  • input:   pointer/key ─▶ host (CDP proxy) ─▶ Chrome   ◀── see spike ┘
+  • tabs:    tab list/<n>/close  (delegated via dor ab passthrough or control)
+```
+
+The host CDP proxy is the only genuinely new long-lived plumbing. The webview
+**cannot** open a CDP WebSocket directly (Chrome refuses CDP from non-localhost
+origins), so a host process (sidecar / `pty-host`) must hold the CDP socket and
+forward input. **Unless the spike below removes that need.**
+
+---
+
+## ⚠️ Spike first: can input ride the stream WS directly?
+
+The prototype proxies input through CDP. But agent-browser's stream WS protocol
+documents **native input messages** (`input_mouse`, `input_keyboard`,
+`input_touch`). If those work, the webview can send input over the **same
+ws://localhost socket it already opened for frames** — eliminating the host CDP
+proxy entirely and collapsing the hardest phase.
+
+**Spike (do this before Phase 4):**
+1. `agent-browser --session s open <url>` + `stream status --json` for the port.
+2. Open that WS from a throwaway Node script; send
+   `{"type":"input_mouse","eventType":"mousePressed","x":100,"y":200,"button":"left","clickCount":1}`
+   then `mouseReleased`; confirm the page reacts (e.g. a button click).
+3. Repeat for `input_keyboard` (keyDown/keyUp + a focused field).
+
+**Decision:**
+- **Works** → use stream-native input, skip the host CDP proxy, and **update the
+  spec's "Input (in)" section** to match. Phase 4 shrinks to "send input_* over
+  the frame socket."
+- **Insufficient** (missing key codes, IME, uploads, modifier handling) → keep the
+  CDP-via-host-proxy design as spec'd and port `serve.mjs`'s approach.
+
+Record the outcome at the top of Phase 4 before building it.
+
+**SPIKE OUTCOME (2026-06-12, agent-browser 0.27.0): stream-native input WORKS.**
+Click, typing (with `text`), and `mouseWheel` scrolling all confirmed against a
+live session. The CDP host proxy is dead. Additional discoveries:
+- Session names must not contain `/` (daemon dies on startup — the name becomes
+  a socket path). Managed sessions are `dormouse.<workspaceId>.<key>`; spec
+  updated.
+- The stream WS pushes `status` and `tabs` messages, so the tab strip needs no
+  polling; only tab *actions* need the CLI.
+- The stream WS **rejects upgrades with a non-localhost `Origin`** (403 for
+  `vscode-webview://…`; `tauri://localhost` and absent Origin are allowed). VS
+  Code needs a loopback origin-stripping TCP relay in the extension host
+  (Phase 7); standalone connects directly. Spec updated.
+
+---
+
+## Phases
+
+Build leaf-up. Each phase is independently verifiable; the surface is usable for
+real (frames visible) by end of Phase 3.
+
+### Phase 1 — `dor ab` command (passthrough + `--key`)
+
+CLI leaf, no rendering. Mirror an existing command end-to-end.
+
+- **Files:** `dor/src/commands/agent-browser.ts` (new, mirror
+  `dor/src/commands/iframe.ts`); register in `dor/src/cli.ts` `COMMANDS` +
+  `ROUTES` with **both** keys `'agent-browser'` and `'ab'` pointing at the same
+  `.command` (confirm stricli renders the alias acceptably in help — adjust if it
+  duplicates the entry).
+- **Behavior:** parse/strip `--key` (default `default`) and `--session`; error if
+  both given; resolve `--key` → `dormouse/1/<key>`; forward all remaining args
+  verbatim to the resolved `agent-browser --session <s> …`. Resolve the binary
+  via `DORMOUSE_AGENT_BROWSER_BIN` ?? PATH; friendly error + install hint if
+  absent.
+- **Tests/snapshots:** add `dor/test/snapshots/help/agent-browser.md`; extend
+  `dor/test/cli-output.test.mjs` for: `--help`, `--key`/`--session` mutual
+  exclusion error, missing-binary error, and the key→session translation.
+- **Verify:** `node --test test/cli-output.test.mjs` green; `dor ab open <url>`
+  drives the right session from a terminal (no surface yet).
+- **Spec:** "Delegation Boundary", "The `--key` Model".
+
+### Phase 2 — `surface.agentBrowser` control method + Wall registry
+
+Wire surface creation; the surface can stay the stub.
+
+- **Files:** `dor/src/commands/types.ts` (add `AgentBrowserSurfaceRequest/Response`
+  + `ControlClient.agentBrowserSurface`, mirror `IframeSurface*` at types.ts:109);
+  `dor/src/control-client.ts` (map to `'surface.agentBrowser'`, mirror line 71);
+  `lib/src/components/Wall.tsx` (handler mirroring the `surface.iframe` handler at
+  Wall.tsx:1255 + `createIframeSurface` at Wall.tsx:888; add the
+  `key→{session,surfaceId}` registry).
+- **Behavior:** first call for a session with no surface → create (split next to
+  caller, iframe placement rule); subsequent calls reuse. Pass `wsPort` (from
+  `stream status --json`) + session into panel params.
+- **Verify:** `dor ab open <url>` twice with same key → one surface, reused;
+  different `--key` → second surface. (Stub still renders.)
+- **Spec:** "Session ↔ Surface Mapping".
+
+### Phase 3 — Frames channel (the payoff)
+
+Replace the `AgentBrowserPanel` stub with a live canvas viewer.
+
+- **Files:** `lib/src/components/wall/AgentBrowserPanel.tsx` (currently a stub).
+- **Behavior:** connect `ws://127.0.0.1:<wsPort>`; on `{type:'frame'}` decode
+  base64 JPEG → `drawImage` on a `<canvas>`; track `metadata` device size for
+  later coordinate mapping; handle status messages (`connected`,
+  `screencasting`) for placeholder states. Port `viewer.html`'s frame loop.
+- **Verify:** `dor ab open http://localhost:5173` shows the live page in the
+  surface; navigations update.
+- **Spec:** "Channels → Frames (out)".
+
+### Phase 4 — Input channel
+
+**Resolve the spike first** and note the outcome here. Then either:
+
+- **Stream-native:** send `input_mouse`/`input_keyboard` over the frame socket;
+  map canvas → device coords via `metadata` (port `toViewport` from the
+  prototype). Update the spec's Input section.
+- **CDP-via-host-proxy:** add a long-lived CDP connection manager in the host
+  (`standalone/sidecar/*`, `vscode-ext/src/pty-host.js`) holding the browser-level
+  CDP WS + flattened `Target.attachToTarget` session, dispatching
+  `Input.dispatchMouseEvent`/`dispatchKeyEvent`; add a webview→host input message
+  path through the adapters (`lib/src/lib/platform/vscode-adapter.ts`,
+  `standalone/src/tauri-adapter.ts`, `vscode-ext/src/message-router.ts`); throttle
+  `mousemove`; re-resolve the active target on navigation (prototype's
+  `/cdp-target`).
+- **Focus:** terminal-surface semantics — click-to-focus, forward keys only while
+  selected + in interact mode; leader chord returns to the Wall (Dormouse owns the
+  keydown listener — `lib/src/components/wall/use-wall-keyboard.ts`).
+- **Verify:** click and type into the embedded page; ⌘-leader still navigates panes.
+- **Spec:** "Channels → Input (in)".
+
+### Phase 5 — Tabs
+
+- **Files:** `AgentBrowserPanel.tsx` (tab strip below header).
+- **Behavior:** poll/refresh `tab list` → integrated (1) vs multi-tab (≥2) strip
+  (title + favicon + close ×); selecting → `tab <n>` (stream/input follow active
+  target); × → `tab close`; focus newest web-opened tab; `dor ab open` navigates
+  active, never spawns.
+- **Verify:** trigger a `target=_blank`/popup → strip appears, newest focused,
+  closing extras returns to integrated mode; minimized surface stays title-only.
+- **Spec:** "Tabs".
+
+### Phase 6 — Lifecycle
+
+- **Behavior:** surface kill (`dor kill` / header × / `dor ab … close`) →
+  `agent-browser --session <s> close` + registry cleanup; external session death
+  (stream `connected:false`) → remove/placeholder the surface.
+- **Verify:** kill surface → browser process exits; `agent-browser close`
+  elsewhere → surface tears down.
+- **Spec:** "Lifecycle".
+
+### Phase 7 — VS Code CSP + dogfood
+
+- **Files:** `vscode-ext/src/webview-html.ts` — add
+  `connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>`. No
+  `frame-src`/`img-src` change (canvas from base64, no iframe).
+- **Verify:** `pnpm build:vscode` + `pnpm --filter dormouse dogfood`, reload; full
+  flow works in the real extension. Also smoke-test the standalone (Tauri) build.
+- **Spec:** "VS Code Webview CSP".
+
+---
+
+## Testing strategy
+
+- **CLI:** snapshot + behavior tests alongside the other commands
+  (`dor/test/cli-output.test.mjs`, `dor/test/snapshots/`). This is the
+  highest-leverage automated coverage — Phases 1–2 are fully testable headless.
+- **Channels:** mostly manual against a live `agent-browser` (frames/input/tabs
+  need a real browser). The spike script and the prototype are the harness.
+- **Run `node --test` in `dor/` after every CLI change; snapshots will catch help
+  drift** (see how the iframe help snapshot is maintained).
+
+---
+
+## Risks & edge cases
+
+- **Input spike is the pivot.** It decides whether Phase 4 is small (stream-native)
+  or the largest phase (host CDP proxy + new adapter message path). Spike before
+  committing to either.
+- **CDP origin refusal** (if proxying): the webview cannot hold the CDP socket;
+  it must live in the host. Don't try to connect CDP from the panel.
+- **Coordinate mapping:** canvas size ≠ device size; scale through frame
+  `metadata` (`deviceWidth/Height`, `pageScaleFactor`, scroll offsets). Port
+  `toViewport` rather than reinventing.
+- **Stream port churn:** OS-assigned per session; always read `stream status
+  --json` fresh, don't cache across session restarts. `AGENT_BROWSER_STREAM_PORT`
+  can pin it if needed.
+- **Zero-tab state:** closing the last page leaves a context with no page — define
+  the surface's empty state (placeholder, not a crash).
+- **Mousemove chatter** (CDP path): throttle webview→host input.
+- **`--headed` passthrough** pops a separate OS window (defeats embedding). Decide
+  whether to warn/block; spec currently leaves passthrough verbatim.
+- **stricli alias rendering:** verify `ab` appears sanely in `dor --help` / `dor ab
+  --help`; adjust ROUTES if it duplicates.
+
+---
+
+## Definition of done
+
+- `dor ab` and `dor ab --key <name>` open/reuse browser surfaces per the registry;
+  CLI snapshot tests pass.
+- Frames render live; input works; ⌘-leader still controls the Wall.
+- Tabs present integrated vs multi-tab per spec; minimize stays binary.
+- Surface kill ↔ session close both directions.
+- Works in `dogfood` (VS Code) and standalone; CSP allows the stream WS.
+- Spec updated for any design change the build forced (especially the input
+  channel after the spike).
diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 8afd8b11..96c1ce81 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -36,8 +36,8 @@ than reimplemented:
 | Concern | Delegated to |
 | --- | --- |
 | Video (frames) | agent-browser session **stream** WebSocket |
-| Input (mouse/keyboard) | **CDP** `Input.*`, proxied by the Dormouse host |
-| Tabs | agent-browser **`tab list` / `tab <n>` / `tab close`** |
+| Input (mouse/keyboard) | the same stream WebSocket's native **`input_*`** messages |
+| Tabs | stream `tabs` messages (read) + **`tab list` / `tab <n>` / `tab close`** (act) |
 
 ## The `--key` Model
 
@@ -63,13 +63,16 @@ resolution is scoped to the right workspace with no extra plumbing.
 A managed `--key` maps to a namespaced agent-browser session:
 
 ```
-session = "dormouse/<workspaceId>/<key>"
+session = "dormouse.<workspaceId>.<key>"
 ```
 
 `<workspaceId>` is hardcoded `1` until Dormouse exposes real workspaces (see
 `dor-cli.md` → Handle Model); it is encoded now to avoid a later rename.
 Namespacing keeps managed keys from colliding with sessions a user created
-directly via plain `agent-browser`.
+directly via plain `agent-browser`. Dots, not slashes: agent-browser session
+names become socket paths, and a `/` in the name kills the daemon on startup
+(verified against 0.27.0). Keys are validated to `[A-Za-z0-9._-]+` for the
+same reason.
 
 ### `--key` vs raw `--session`
 
@@ -157,13 +160,19 @@ to a `<canvas>`:
 
 ### Input (in)
 
-Chrome refuses CDP WebSocket connections from regular http(s) origins, so the
-webview **cannot** speak CDP directly. Input is proxied by the Dormouse host
-(sidecar / `pty-host`, the same process that already bridges control requests):
-the host holds one persistent browser-level CDP WebSocket plus a flattened
-`Target.attachToTarget` session and dispatches `Input.dispatchMouseEvent` /
-`Input.dispatchKeyEvent`. The host re-resolves the active page target on
-navigation (the prototype's `/cdp-target`).
+The stream WebSocket natively accepts input messages, so the webview sends
+input on the **same socket it already opened for frames** — there is no CDP
+connection and no host input proxy. (Verified against 0.27.0: `input_mouse`
+press/release/move/wheel and `input_keyboard` keyDown/keyUp with `text` all
+work, including scroll. The daemon dispatches to the active target itself, so
+tab switches need no input re-attachment.)
+
+- Mouse: `{ type: "input_mouse", eventType: "mousePressed" | "mouseReleased" |
+  "mouseMoved" | "mouseWheel", x, y, button, clickCount, deltaX?, deltaY?,
+  modifiers }` — coordinates mapped from canvas space to device space via frame
+  `metadata`.
+- Keyboard: `{ type: "input_keyboard", eventType: "keyDown" | "keyUp", key,
+  code, text?, windowsVirtualKeyCode?, modifiers }`.
 
 Focus behaves like a terminal surface: click-to-focus; keystrokes forward to the
 browser only while the surface is selected and in interact mode. Because Dormouse
@@ -172,8 +181,11 @@ control to the Wall.
 
 ### Tabs
 
-`agent-browser tab list` (strip contents), `tab <n>` (switch), `tab close`
-(per-tab `×`) — all verbatim passthrough.
+The stream WebSocket pushes `{ type: "tabs", tabs: [{ tabId, title, url,
+active }] }` messages, which feed the strip for free. Tab *actions* still go
+through the CLI — `tab <n>` (switch), `tab close` (per-tab `×`) — issued by the
+host on the webview's behalf (a webview cannot spawn processes; see
+`agentBrowserCommand` below).
 
 ## Implementation Touchpoints
 
@@ -184,9 +196,21 @@ control to the Wall.
 | Surface component (canvas viewer + WS client + tab strip) | `lib/src/components/wall/AgentBrowserPanel.tsx` (currently a stub) |
 | Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
 | Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
-| CDP input proxy | host: `standalone/sidecar/*`, `vscode-ext/src/pty-host.js` |
+| Host CLI runner (`agentBrowserCommand`) + VS Code stream relay | `lib/src/lib/platform/types.ts` (optional adapter methods), `vscode-ext/src/message-router.ts`, `vscode-ext/src/agent-browser-host.ts` |
+
+### Host capabilities
+
+Two narrow host capabilities back the surface, both optional on
+`PlatformAdapter` so hosts degrade gracefully:
 
-## VS Code Webview CSP
+- **`agentBrowserCommand(session, args)`** — runs the user's agent-browser
+  binary for tab actions (`tab <n>`, `tab close`, `tab new`) and lifecycle
+  (`close`). The host validates `args[0]` against an allowlist (`tab`,
+  `close`); this is not a general exec channel.
+- **`getAgentBrowserStreamUrl(port)`** — returns the WebSocket URL the webview
+  should use for the session stream (see CSP/origin below).
+
+## VS Code Webview CSP and Stream Origin
 
 The VS Code webview CSP (`vscode-ext/src/webview-html.ts`) must allow the stream
 WebSocket:
@@ -197,3 +221,12 @@ connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>
 
 The canvas is drawn from base64 frame data, so no `img-src` change is needed, and
 no `frame-src` is involved — there is no iframe.
+
+CSP alone is not enough in VS Code: the agent-browser stream server rejects
+WebSocket upgrades whose `Origin` is not localhost-or-absent (verified against
+0.27.0: `vscode-webview://…` → 403; `tauri://localhost` and plain localhost →
+allowed; no override env var exists). The VS Code extension host therefore runs
+a loopback-only TCP relay that strips the `Origin` header and pipes bytes to
+`127.0.0.1:<streamPort>`; `getAgentBrowserStreamUrl` returns the relay URL
+(`ws://127.0.0.1:<relayPort>/stream/<streamPort>`). The standalone (Tauri)
+webview connects directly — its origin is allowed.
diff --git a/dor/src/cli.ts b/dor/src/cli.ts
index 1d2d9a9a..7aad01e1 100644
--- a/dor/src/cli.ts
+++ b/dor/src/cli.ts
@@ -6,6 +6,7 @@ import {
   type ApplicationText,
   type StricliProcess,
 } from '@stricli/core';
+import { agentBrowserCommand, runAgentBrowserCli } from './commands/agent-browser.js';
 import { ensureCommand } from './commands/ensure.js';
 import { iframeCommand } from './commands/iframe.js';
 import { killCommand } from './commands/kill.js';
@@ -27,6 +28,10 @@ import type {
 } from './commands/types.js';
 
 export type {
+  AgentBrowserExec,
+  AgentBrowserExecResult,
+  AgentBrowserSurfaceRequest,
+  AgentBrowserSurfaceResponse,
   CliEnv,
   CliOptions,
   CliResult,
@@ -64,6 +69,7 @@ const COMMANDS = [
   readCommand,
   killCommand,
   iframeCommand,
+  agentBrowserCommand,
   listPanesCommand,
   listPaneSurfacesCommand,
 ] as const satisfies readonly Command[];
@@ -76,6 +82,7 @@ const ROUTES = {
   read: readCommand.command,
   kill: killCommand.command,
   iframe: iframeCommand.command,
+  'agent-browser': agentBrowserCommand.command,
   'list-panes': listPanesCommand.command,
   'list-pane-surfaces': listPaneSurfacesCommand.command,
 };
@@ -122,7 +129,16 @@ interface CaptureProcess extends StricliProcess {
   };
 }
 
-export async function runCli(argv: string[], options: CliOptions = {}): Promise<CliResult> {
+export async function runCli(rawArgv: string[], options: CliOptions = {}): Promise<CliResult> {
+  const argv = normalizeAgentBrowserAlias(rawArgv);
+
+  // `dor ab <args...>` forwards args verbatim to agent-browser, so they must
+  // never reach stricli's flag parser. Only a bare `--help`/`-h` (or
+  // `dor help agent-browser`, normalized above) falls through to stricli.
+  if (argv[0] === 'agent-browser' && !isAgentBrowserHelpInvocation(argv)) {
+    return runAgentBrowserCli(argv.slice(1), options);
+  }
+
   const helpTarget = getHelpTarget(argv);
   const [commandName, ...args] = rewriteHelpArgv(argv);
 
@@ -147,6 +163,17 @@ export async function runCli(argv: string[], options: CliOptions = {}): Promise<
   };
 }
 
+/** `ab` is the documented short alias for `agent-browser`, in any help form. */
+function normalizeAgentBrowserAlias(argv: string[]): string[] {
+  if (argv[0] === 'ab') return ['agent-browser', ...argv.slice(1)];
+  if (argv[0] === 'help' && argv[1] === 'ab') return ['help', 'agent-browser', ...argv.slice(2)];
+  return argv;
+}
+
+function isAgentBrowserHelpInvocation(argv: string[]): boolean {
+  return argv.length === 2 && (argv[1] === '--help' || argv[1] === '-h');
+}
+
 type HelpTarget =
   | { scope: 'root' }
   | { scope: 'command'; commandName: string };
diff --git a/dor/src/commands/agent-browser.ts b/dor/src/commands/agent-browser.ts
new file mode 100644
index 00000000..ed74e3e5
--- /dev/null
+++ b/dor/src/commands/agent-browser.ts
@@ -0,0 +1,232 @@
+/**
+ * `dor agent-browser` (alias `dor ab`) — near-transparent passthrough to the
+ * user's own agent-browser binary, plus Dormouse surface management.
+ *
+ * Dormouse intercepts exactly two flags: `--key` (managed, workspace-scoped,
+ * default "default") and `--session` (raw escape hatch). Everything else is
+ * forwarded verbatim to `agent-browser --session <resolved> <args...>`. After
+ * a successful forwarded command, the stream WebSocket port is read via
+ * `stream status --json` and a `surface.agentBrowser` control request asks the
+ * Wall to create or reuse the browser surface bound to that session.
+ *
+ * The stricli command registered here exists only to serve `--help`; real
+ * invocations are intercepted in `runCli` before stricli parses argv, because
+ * forwarded agent-browser args (e.g. `open --headed`) must not be parsed as
+ * dor flags.
+ */
+
+import { buildCommand } from '@stricli/core';
+import { spawn } from 'node:child_process';
+import type {
+  AgentBrowserExecResult,
+  CliOptions,
+  CliResult,
+  Command,
+  DorCommandContext,
+  ParseResult,
+} from './types.js';
+import { fail, resolveControlClient, stringParser } from './shared.js';
+
+/** Hardcoded until Dormouse exposes real workspaces; encoded now to avoid a rename. */
+const WORKSPACE_ID = '1';
+
+const INSTALL_HINT = 'npm i -g agent-browser';
+
+// agent-browser session names become filesystem paths (socket dir), so `/` is
+// not usable as a namespace separator — the daemon fails to start. Dots keep
+// the managed namespace readable: dormouse.<workspaceId>.<key>.
+const KEY_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+export function sessionForKey(key: string): string {
+  return `dormouse.${WORKSPACE_ID}.${key}`;
+}
+
+export const agentBrowserCommand: Command = {
+  name: 'agent-browser',
+  helpPatches: [
+    {
+      scope: 'root',
+      findReplace: ['agent-browser [--key name] [--session name]<TO-EOL>', 'agent-browser [--key name|--session name] [args...]\n'],
+    },
+    {
+      scope: 'command-usage',
+      findReplace: ['agent-browser [--key name] [--session name]<TO-EOL>', 'agent-browser [--key name|--session name] [args...]\n'],
+    },
+  ],
+  command: buildCommand<{ key?: string; session?: string }, [...args: string[]], DorCommandContext>({
+    docs: {
+      brief: 'Drive a browser surface via your agent-browser install (alias: dor ab).',
+      fullDescription: `Forwards all arguments verbatim to your own agent-browser binary and binds the session to a Dormouse browser surface.
+
+dor intercepts exactly two flags:
+  --key <name>      Managed, workspace-scoped browser identity (default "default").
+                    Maps to agent-browser session dormouse.1.<name>.
+  --session <name>  Attach to a raw agent-browser session by its literal name.
+                    Mutually exclusive with --key.
+
+Everything else — subcommands, flags, selectors — is agent-browser's own
+command surface. The binary is resolved from PATH (override with
+DORMOUSE_AGENT_BROWSER_BIN) and is never bundled; install it with:
+  ${INSTALL_HINT}
+
+After a successful command, dor opens (or reuses) the browser surface bound to
+the session: one session is always exactly one surface.
+
+Examples:
+  dor ab open http://localhost:5173        # key "default"
+  dor ab --key storybook open http://localhost:6006
+  dor ab click @e3                          # drives key "default"
+  dor ab --key storybook reload             # drives key "storybook"`,
+    },
+    parameters: {
+      flags: {
+        key: { kind: 'parsed', parse: stringParser, brief: 'Workspace-scoped browser key (default "default").', optional: true, placeholder: 'name' },
+        session: { kind: 'parsed', parse: stringParser, brief: 'Raw agent-browser session name (mutually exclusive with --key).', optional: true, placeholder: 'name' },
+      },
+      positional: {
+        kind: 'array',
+        parameter: { parse: stringParser, brief: 'Arguments forwarded verbatim to agent-browser.', placeholder: 'args' },
+        minimum: 0,
+      },
+    },
+    func: async function (this: DorCommandContext, _flags: { key?: string; session?: string }, ..._args: string[]): Promise<void | Error> {
+      // runCli intercepts every non-help agent-browser invocation before
+      // stricli; reaching this func means that interception regressed.
+      return new Error('internal: agent-browser passthrough was not intercepted');
+    },
+  }),
+};
+
+interface ResolvedSessionFlags {
+  /** Managed key; undefined when the caller attached via raw --session. */
+  key?: string;
+  session: string;
+  rest: string[];
+}
+
+export function extractSessionFlags(args: string[]): ParseResult<ResolvedSessionFlags> {
+  let key: string | undefined;
+  let session: string | undefined;
+  const rest: string[] = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+    const flag = arg === '--key' || arg.startsWith('--key=')
+      ? '--key'
+      : arg === '--session' || arg.startsWith('--session=')
+        ? '--session'
+        : null;
+    if (!flag) {
+      rest.push(arg);
+      continue;
+    }
+
+    let value: string | undefined;
+    if (arg.includes('=')) {
+      value = arg.slice(arg.indexOf('=') + 1);
+    } else {
+      value = args[index + 1];
+      index += 1;
+    }
+    if (!value || value.startsWith('-')) {
+      return { ok: false, message: `${flag} requires a value` };
+    }
+    if (flag === '--key') key = value;
+    else session = value;
+  }
+
+  if (key !== undefined && session !== undefined) {
+    return { ok: false, message: '--key and --session are mutually exclusive' };
+  }
+  if (key !== undefined && !KEY_PATTERN.test(key)) {
+    return { ok: false, message: `--key must match ${KEY_PATTERN} (it becomes part of an agent-browser session name)` };
+  }
+
+  if (session !== undefined) {
+    return { ok: true, value: { session, rest } };
+  }
+  const resolvedKey = key ?? 'default';
+  return { ok: true, value: { key: resolvedKey, session: sessionForKey(resolvedKey), rest } };
+}
+
+export async function runAgentBrowserCli(args: string[], options: CliOptions): Promise<CliResult> {
+  const flags = extractSessionFlags(args);
+  if (!flags.ok) return fail(flags.message);
+  const { key, session, rest } = flags.value;
+
+  const env = options.env ?? {};
+  const binary = env.DORMOUSE_AGENT_BROWSER_BIN || 'agent-browser';
+  const exec = options.execAgentBrowser ?? execAgentBrowserProcess;
+
+  let result: AgentBrowserExecResult;
+  try {
+    result = await exec(binary, ['--session', session, ...rest]);
+  } catch (error) {
+    if (isMissingBinaryError(error)) {
+      return fail(`agent-browser was not found (looked for '${binary}'). Install it with: ${INSTALL_HINT}`);
+    }
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+
+  let stderrSuffix = '';
+  if (shouldManageSurface(result.exitCode, rest)) {
+    const clientResult = resolveControlClient(options);
+    // Outside a Dormouse terminal there is no control endpoint; stay a pure
+    // passthrough rather than nagging about the missing surface.
+    if (clientResult.ok) {
+      try {
+        const status = await exec(binary, ['--session', session, 'stream', 'status', '--json']);
+        const wsPort = parseStreamPort(status.stdout);
+        await clientResult.value.agentBrowserSurface({ key, session, wsPort });
+      } catch (error) {
+        stderrSuffix = `Warning: could not open the Dormouse browser surface: ${error instanceof Error ? error.message : String(error)}\n`;
+      }
+    }
+  }
+
+  return {
+    exitCode: result.exitCode,
+    stdout: result.stdout,
+    stderr: result.stderr + stderrSuffix,
+  };
+}
+
+function shouldManageSurface(exitCode: number, rest: string[]): boolean {
+  if (exitCode !== 0 || rest.length === 0) return false;
+  if (rest.includes('--help') || rest.includes('-h')) return false;
+  // `close` tears the session down; the Wall notices the stream dropping and
+  // placeholders the surface, so opening one here would be self-defeating.
+  const subcommand = rest.find((arg) => !arg.startsWith('-'));
+  return subcommand !== undefined && subcommand !== 'close';
+}
+
+function parseStreamPort(stdout: string): number | undefined {
+  try {
+    const parsed = JSON.parse(stdout) as { port?: unknown; data?: { port?: unknown } };
+    const port = parsed.data?.port ?? parsed.port;
+    return typeof port === 'number' && Number.isFinite(port) ? port : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function isMissingBinaryError(error: unknown): boolean {
+  return !!error && typeof error === 'object' && (error as { code?: unknown }).code === 'ENOENT';
+}
+
+// agent-browser talks to a daemon, so forwarded commands return quickly;
+// buffering output until exit keeps this transport-agnostic with runCli's
+// captured stdout/stderr at the cost of not streaming long-running output.
+function execAgentBrowserProcess(binary: string, args: string[]): Promise<AgentBrowserExecResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk: unknown) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk: unknown) => { stderr += String(chunk); });
+    child.on('error', reject);
+    child.on('close', (code: number | null) => {
+      resolve({ exitCode: code ?? 1, stdout, stderr });
+    });
+  });
+}
diff --git a/dor/src/commands/types.ts b/dor/src/commands/types.ts
index 371b3116..a2898c66 100644
--- a/dor/src/commands/types.ts
+++ b/dor/src/commands/types.ts
@@ -120,6 +120,23 @@ export interface IframeSurfaceResponse {
   minimized: boolean;
 }
 
+export interface AgentBrowserSurfaceRequest {
+  /** Managed workspace-scoped key; absent when attaching via raw --session. */
+  key?: string;
+  /** Resolved agent-browser session name — the join key for the surface. */
+  session: string;
+  /** Session stream WebSocket port from `stream status --json`. */
+  wsPort?: number;
+}
+
+export interface AgentBrowserSurfaceResponse {
+  status: 'created' | 'existing' | 'replaced';
+  surfaceId?: string;
+  surfaceRef: string;
+  session: string;
+  minimized: boolean;
+}
+
 export interface ControlClient {
   listSurfaces(request: ListSurfacesRequest): Promise<ListSurfacesResponse>;
   splitSurface(request: SplitSurfaceRequest): Promise<SplitSurfaceResponse>;
@@ -128,8 +145,18 @@ export interface ControlClient {
   readSurface(request: ReadSurfaceRequest): Promise<ReadSurfaceResponse>;
   killSurface(request: KillSurfaceRequest): Promise<KillSurfaceResponse>;
   iframeSurface(request: IframeSurfaceRequest): Promise<IframeSurfaceResponse>;
+  agentBrowserSurface(request: AgentBrowserSurfaceRequest): Promise<AgentBrowserSurfaceResponse>;
 }
 
+export interface AgentBrowserExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Runs the user's agent-browser binary; injectable so CLI tests stay hermetic. */
+export type AgentBrowserExec = (binary: string, args: string[]) => Promise<AgentBrowserExecResult>;
+
 export interface CliEnv {
   [key: string]: string | undefined;
 }
@@ -139,6 +166,7 @@ export interface CliOptions {
   client?: ControlClient;
   readStdin?: () => Promise<string>;
   versionMetadata?: VersionMetadata;
+  execAgentBrowser?: AgentBrowserExec;
 }
 
 export interface CliResult {
diff --git a/dor/src/control-client.ts b/dor/src/control-client.ts
index 82935cad..59ca5dff 100644
--- a/dor/src/control-client.ts
+++ b/dor/src/control-client.ts
@@ -1,5 +1,7 @@
 import { createConnection } from 'node:net';
 import type {
+  AgentBrowserSurfaceRequest,
+  AgentBrowserSurfaceResponse,
   ControlClient,
   EnsureSurfaceRequest,
   EnsureSurfaceResponse,
@@ -72,6 +74,10 @@ export class SocketControlClient implements ControlClient {
     return this.request<IframeSurfaceResponse>('surface.iframe', request);
   }
 
+  agentBrowserSurface(request: AgentBrowserSurfaceRequest): Promise<AgentBrowserSurfaceResponse> {
+    return this.request<AgentBrowserSurfaceResponse>('surface.agentBrowser', request);
+  }
+
   private request<T>(method: string, params: unknown): Promise<T> {
     const requestId = `dor-${this.idBase}-${++this.nextRequestId}`;
     return new Promise((resolve, reject) => {
diff --git a/dor/src/node-runtime.d.ts b/dor/src/node-runtime.d.ts
index e0b668d3..836d8da4 100644
--- a/dor/src/node-runtime.d.ts
+++ b/dor/src/node-runtime.d.ts
@@ -17,6 +17,21 @@ declare module 'node:child_process' {
     encoding: 'utf8';
     timeout?: number;
   }): string;
+
+  export interface ChildProcessStream {
+    on(event: 'data', listener: (chunk: unknown) => void): void;
+  }
+
+  export interface ChildProcess {
+    stdout: ChildProcessStream;
+    stderr: ChildProcessStream;
+    on(event: 'error', listener: (error: Error) => void): void;
+    on(event: 'close', listener: (code: number | null) => void): void;
+  }
+
+  export function spawn(command: string, args: readonly string[], options: {
+    stdio: readonly ['ignore', 'pipe', 'pipe'];
+  }): ChildProcess;
 }
 
 declare const process: {
diff --git a/dor/test/cli-output.test.mjs b/dor/test/cli-output.test.mjs
index 5542d5f3..bcaef4c3 100644
--- a/dor/test/cli-output.test.mjs
+++ b/dor/test/cli-output.test.mjs
@@ -128,6 +128,30 @@ function fixtureClient(surfacesFixture = fixtureSurfaces) {
         minimized: request.minimized,
       };
     },
+    async agentBrowserSurface(request) {
+      this.requests.push({ method: 'agentBrowserSurface', request });
+      return {
+        status: 'created',
+        surfaceId: '33333333-3333-4333-8333-333333333333',
+        surfaceRef: 'surface:3',
+        session: request.session,
+        minimized: false,
+      };
+    },
+  };
+}
+
+function fakeAgentBrowser({ exitCode = 0, stdout = '✓ ok\n', stderr = '' } = {}) {
+  const calls = [];
+  return {
+    calls,
+    exec: async (binary, args) => {
+      calls.push([binary, ...args]);
+      if (args.includes('stream')) {
+        return { exitCode: 0, stdout: '{"success":true,"data":{"port":61141}}\n', stderr: '' };
+      }
+      return { exitCode, stdout, stderr };
+    },
   };
 }
 
@@ -392,6 +416,98 @@ test('iframe invalid url output', async () => {
   await snapshot('iframe-invalid-url', await runCli(['iframe', 'localhost:5173'], { client: fixtureClient() }));
 });
 
+test('agent-browser passthrough output', async () => {
+  const ab = fakeAgentBrowser({ stdout: '✓ \n  http://localhost:5173\n' });
+  await snapshot(
+    'agent-browser-passthrough',
+    await runCli(['ab', 'open', 'http://localhost:5173'], { client: fixtureClient(), execAgentBrowser: ab.exec }),
+  );
+});
+
+test('agent-browser resolves --key to a namespaced session and opens a surface', async () => {
+  const ab = fakeAgentBrowser();
+  const client = fixtureClient();
+  await runCli(['ab', '--key', 'storybook', 'open', 'http://localhost:6006'], { client, execAgentBrowser: ab.exec });
+  assert.deepEqual(ab.calls, [
+    ['agent-browser', '--session', 'dormouse.1.storybook', 'open', 'http://localhost:6006'],
+    ['agent-browser', '--session', 'dormouse.1.storybook', 'stream', 'status', '--json'],
+  ]);
+  assert.deepEqual(client.requests, [{
+    method: 'agentBrowserSurface',
+    request: { key: 'storybook', session: 'dormouse.1.storybook', wsPort: 61141 },
+  }]);
+});
+
+test('agent-browser defaults to --key default', async () => {
+  const ab = fakeAgentBrowser();
+  const client = fixtureClient();
+  await runCli(['agent-browser', 'open', 'http://localhost:5173'], { client, execAgentBrowser: ab.exec });
+  assert.equal(ab.calls[0][2], 'dormouse.1.default');
+  assert.deepEqual(client.requests[0].request, { key: 'default', session: 'dormouse.1.default', wsPort: 61141 });
+});
+
+test('agent-browser raw --session skips key namespacing', async () => {
+  const ab = fakeAgentBrowser();
+  const client = fixtureClient();
+  await runCli(['ab', '--session', 'mine', 'snapshot'], { client, execAgentBrowser: ab.exec });
+  assert.equal(ab.calls[0][2], 'mine');
+  assert.deepEqual(client.requests[0].request, { key: undefined, session: 'mine', wsPort: 61141 });
+});
+
+test('agent-browser close skips surface management', async () => {
+  const ab = fakeAgentBrowser();
+  const client = fixtureClient();
+  await runCli(['ab', 'close'], { client, execAgentBrowser: ab.exec });
+  assert.deepEqual(ab.calls, [['agent-browser', '--session', 'dormouse.1.default', 'close']]);
+  assert.deepEqual(client.requests, []);
+});
+
+test('agent-browser without a control endpoint stays a pure passthrough', async () => {
+  const ab = fakeAgentBrowser();
+  const result = await runCli(['ab', 'open', 'http://localhost:5173'], { execAgentBrowser: ab.exec });
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.stderr, '');
+  assert.deepEqual(ab.calls, [['agent-browser', '--session', 'dormouse.1.default', 'open', 'http://localhost:5173']]);
+});
+
+test('agent-browser forwards child exit code and skips surface on failure', async () => {
+  const ab = fakeAgentBrowser({ exitCode: 1, stderr: '✗ boom\n' });
+  const client = fixtureClient();
+  const result = await runCli(['ab', 'open', 'nope'], { client, execAgentBrowser: ab.exec });
+  assert.equal(result.exitCode, 1);
+  assert.equal(result.stderr, '✗ boom\n');
+  assert.deepEqual(client.requests, []);
+});
+
+test('agent-browser key/session conflict output', async () => {
+  const ab = fakeAgentBrowser();
+  await snapshot(
+    'agent-browser-key-session-conflict',
+    await runCli(['ab', '--key', 'a', '--session', 'b', 'open', 'x'], { client: fixtureClient(), execAgentBrowser: ab.exec }),
+  );
+});
+
+test('agent-browser missing binary output', async () => {
+  const enoent = Object.assign(new Error("spawn agent-browser ENOENT"), { code: 'ENOENT' });
+  await snapshot(
+    'agent-browser-missing-binary',
+    await runCli(['ab', 'open', 'http://localhost:5173'], {
+      client: fixtureClient(),
+      execAgentBrowser: async () => { throw enoent; },
+    }),
+  );
+});
+
+test('agent-browser respects DORMOUSE_AGENT_BROWSER_BIN', async () => {
+  const ab = fakeAgentBrowser();
+  await runCli(['ab', 'snapshot'], {
+    client: fixtureClient(),
+    execAgentBrowser: ab.exec,
+    env: { DORMOUSE_AGENT_BROWSER_BIN: '/opt/custom/agent-browser' },
+  });
+  assert.equal(ab.calls[0][0], '/opt/custom/agent-browser');
+});
+
 test('list-panes text output', async () => {
   await snapshot('list-panes-text', await runCli(['list-panes'], { client: fixtureClient() }));
 });
diff --git a/dor/test/snapshots/agent-browser-key-session-conflict.snap b/dor/test/snapshots/agent-browser-key-session-conflict.snap
new file mode 100644
index 00000000..8d589a2c
--- /dev/null
+++ b/dor/test/snapshots/agent-browser-key-session-conflict.snap
@@ -0,0 +1,5 @@
+exitCode: 1
+stdout:
+
+stderr:
+Error: --key and --session are mutually exclusive
diff --git a/dor/test/snapshots/agent-browser-missing-binary.snap b/dor/test/snapshots/agent-browser-missing-binary.snap
new file mode 100644
index 00000000..a3f2eadc
--- /dev/null
+++ b/dor/test/snapshots/agent-browser-missing-binary.snap
@@ -0,0 +1,5 @@
+exitCode: 1
+stdout:
+
+stderr:
+Error: agent-browser was not found (looked for 'agent-browser'). Install it with: npm i -g agent-browser
diff --git a/dor/test/snapshots/agent-browser-passthrough.snap b/dor/test/snapshots/agent-browser-passthrough.snap
new file mode 100644
index 00000000..b36a8ad8
--- /dev/null
+++ b/dor/test/snapshots/agent-browser-passthrough.snap
@@ -0,0 +1,6 @@
+exitCode: 0
+stdout:
+✓ 
+  http://localhost:5173
+
+stderr:
diff --git a/dor/test/snapshots/help/agent-browser.md b/dor/test/snapshots/help/agent-browser.md
new file mode 100644
index 00000000..aa38bf02
--- /dev/null
+++ b/dor/test/snapshots/help/agent-browser.md
@@ -0,0 +1,41 @@
+# dor agent-browser
+
+Invocation: `dor agent-browser --help`
+
+```text
+USAGE
+  dor agent-browser [--key name|--session name] [args...]
+  dor agent-browser --help
+
+Forwards all arguments verbatim to your own agent-browser binary and binds the session to a Dormouse browser surface.
+
+dor intercepts exactly two flags:
+  --key <name>      Managed, workspace-scoped browser identity (default "default").
+                    Maps to agent-browser session dormouse.1.<name>.
+  --session <name>  Attach to a raw agent-browser session by its literal name.
+                    Mutually exclusive with --key.
+
+Everything else — subcommands, flags, selectors — is agent-browser's own
+command surface. The binary is resolved from PATH (override with
+DORMOUSE_AGENT_BROWSER_BIN) and is never bundled; install it with:
+  npm i -g agent-browser
+
+After a successful command, dor opens (or reuses) the browser surface bound to
+the session: one session is always exactly one surface.
+
+Examples:
+  dor ab open http://localhost:5173        # key "default"
+  dor ab --key storybook open http://localhost:6006
+  dor ab click @e3                          # drives key "default"
+  dor ab --key storybook reload             # drives key "storybook"
+
+FLAGS
+     [--key]      Workspace-scoped browser key (default "default").
+     [--session]  Raw agent-browser session name (mutually exclusive with --key).
+  -h  --help      Print help information and exit
+      --          All subsequent inputs should be interpreted as arguments
+
+ARGUMENTS
+  args...  Arguments forwarded verbatim to agent-browser.
+
+```
diff --git a/dor/test/snapshots/help/dor.md b/dor/test/snapshots/help/dor.md
index 1fa268da..d7a91a67 100644
--- a/dor/test/snapshots/help/dor.md
+++ b/dor/test/snapshots/help/dor.md
@@ -11,6 +11,7 @@ USAGE
   dor read [--json] [--lines count] [--scrollback] [--surface id|ref|index]
   dor kill --surface id|ref|index [--confirm-if-read text|--confirm-dangerously]
   dor iframe [--json] [--minimize] [--surface id|ref|index] <url>
+  dor agent-browser [--key name|--session name] [args...]
   dor list-panes [--id-format refs|uuids|both] [--json]
   dor list-pane-surfaces [--id-format refs|uuids|both] [--json] [--pane id|ref|index]
   dor --help
@@ -29,6 +30,7 @@ COMMANDS
   read                Read terminal text from a surface.
   kill                Kill a terminal surface.
   iframe              Open a URL in an iframe surface.
+  agent-browser       Drive a browser surface via your agent-browser install (alias: dor ab).
   list-panes          List visible panes.
   list-pane-surfaces  List surfaces in a pane.
 

From 8d4f6719c28de9df4781f29d9dc636e434926164 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 14:31:28 -0700
Subject: [PATCH 05/25] =?UTF-8?q?Wall:=20surface.agentBrowser=20control=20?=
 =?UTF-8?q?method=20with=20session=E2=86=94surface=20reuse=20(Phase=202)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The session→surface registry is derived from panel/door params (single
source of truth, survives webview reloads). createIframeSurface is
generalized to createContentSurface, shared by iframe and agent-browser.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 lib/src/components/Wall.tsx | 119 +++++++++++++++++++++++++++++++++---
 1 file changed, 109 insertions(+), 10 deletions(-)

diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 69d1e70d..42c1c45c 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -96,15 +96,18 @@ type DorControlParams = {
   direction?: unknown;
   input?: unknown;
   inputCount?: unknown;
+  key?: unknown;
   lines?: unknown;
   minimized?: unknown;
   pane?: string;
+  session?: unknown;
   surface?: unknown;
   title?: unknown;
   url?: unknown;
   workspace?: string;
   window?: string;
   scrollback?: unknown;
+  wsPort?: unknown;
 };
 
 // The webview view of a control request: the shared wire payload, but with
@@ -885,14 +888,23 @@ export function Wall({
     return { ok: true, value: { id: newId, ref: surfaceRefForId(newId) } };
   }, [generatePaneId, minimizePane, selectPane, surfaceRefForId]);
 
-  const createIframeSurface = useCallback(({
+  /**
+   * Create a non-terminal content surface (iframe, agent-browser) next to a
+   * reference surface: an untouched terminal caller is replaced in place,
+   * anything else gets a split (the `dor iframe` placement rule).
+   */
+  const createContentSurface = useCallback(({
+    component,
     minimized,
+    params,
     reference,
-    url,
+    title,
   }: {
+    component: 'iframe' | 'agent-browser';
     minimized: boolean;
+    params: Record<string, unknown>;
     reference: DorSurface;
-    url: string;
+    title: string;
   }): ParseResult<{
     id: string;
     ref: string;
@@ -904,14 +916,12 @@ export function Wall({
     if (!referencePanel) return { ok: false, message: `surface '${reference.ref}' is not visible` };
 
     const newId = generatePaneId();
-    const title = iframeTitle(url);
-    const params = { surfaceType: 'iframe', url };
     const replaceUntouchedTerminal = reference.type === 'terminal' && isUntouched(reference.id);
 
     if (replaceUntouchedTerminal) {
       api.addPanel({
         id: newId,
-        component: 'iframe',
+        component,
         tabComponent: 'surface',
         title,
         params,
@@ -928,7 +938,7 @@ export function Wall({
     freshlySpawnedRef.current.set(newId, dockDirection === 'below' ? 'top' : 'left');
     api.addPanel({
       id: newId,
-      component: 'iframe',
+      component,
       tabComponent: 'surface',
       title,
       params,
@@ -944,6 +954,24 @@ export function Wall({
     return { ok: true, value: { id: newId, ref: surfaceRefForId(newId), status: 'created' } };
   }, [generatePaneId, minimizePane, selectPane, surfaceRefForId]);
 
+  /**
+   * The agent-browser session ↔ surface registry, derived from panel/door
+   * params rather than kept as separate state so it survives webview reloads.
+   * Returns the surface bound to `session`, or null if none exists.
+   */
+  const findAgentBrowserSurface = useCallback((session: string): { id: string; minimized: boolean } | null => {
+    const isMatch = (params: unknown) =>
+      !!params && typeof params === 'object' &&
+      (params as { surfaceType?: unknown }).surfaceType === 'agent-browser' &&
+      (params as { session?: unknown }).session === session;
+
+    const panel = apiRef.current?.panels.find((candidate) => isMatch(candidate.params));
+    if (panel) return { id: panel.id, minimized: false };
+    const door = doorsRef.current.find((candidate) => isMatch(candidate.params));
+    if (door) return { id: door.id, minimized: true };
+    return null;
+  }, []);
+
   // Listen for external "new terminal" requests (e.g. from the standalone AppBar)
   useEffect(() => {
     const handler = (e: Event) => {
@@ -1263,10 +1291,12 @@ export function Wall({
           detail.respond({ ok: false, error: target.message });
           return;
         }
-        const result = createIframeSurface({
+        const result = createContentSurface({
+          component: 'iframe',
           minimized: booleanParam(params.minimized),
+          params: { surfaceType: 'iframe', url },
           reference: target.value,
-          url,
+          title: iframeTitle(url),
         });
         if (!result.ok) {
           detail.respond({ ok: false, error: result.message });
@@ -1285,12 +1315,81 @@ export function Wall({
         return;
       }
 
+      if (detail.method === 'surface.agentBrowser') {
+        const session = stringParam(params.session);
+        if (!session) {
+          detail.respond({ ok: false, error: 'session is required' });
+          return;
+        }
+        const key = stringParam(params.key);
+        const wsPort = numberParam(params.wsPort);
+
+        const existing = findAgentBrowserSurface(session);
+        if (existing) {
+          // Reuse: refresh the stream port (OS-assigned, churns across session
+          // restarts) so the panel reconnects to the live stream.
+          if (!existing.minimized && wsPort !== undefined) {
+            api.getPanel(existing.id)?.api.updateParameters({ wsPort });
+          } else if (existing.minimized && wsPort !== undefined) {
+            const nextDoors = doorsRef.current.map((door) => door.id === existing.id
+              ? { ...door, params: { ...door.params, wsPort } }
+              : door);
+            doorsRef.current = nextDoors;
+            setDoors(nextDoors);
+          }
+          detail.respond({
+            ok: true,
+            result: {
+              status: 'existing',
+              surfaceId: existing.id,
+              surfaceRef: surfaceRefForId(existing.id),
+              session,
+              minimized: existing.minimized,
+            },
+          });
+          return;
+        }
+
+        const target = resolveVisibleSurface(api, stringParam(params.surface), detail.surfaceId);
+        if (!target.ok) {
+          detail.respond({ ok: false, error: target.message });
+          return;
+        }
+        const result = createContentSurface({
+          component: 'agent-browser',
+          minimized: booleanParam(params.minimized),
+          params: {
+            surfaceType: 'agent-browser',
+            session,
+            ...(key !== undefined ? { key } : {}),
+            ...(wsPort !== undefined ? { wsPort } : {}),
+          },
+          reference: target.value,
+          title: key ?? session,
+        });
+        if (!result.ok) {
+          detail.respond({ ok: false, error: result.message });
+          return;
+        }
+        detail.respond({
+          ok: true,
+          result: {
+            status: result.value.status,
+            surfaceId: result.value.id,
+            surfaceRef: result.value.ref,
+            session,
+            minimized: booleanParam(params.minimized),
+          },
+        });
+        return;
+      }
+
       detail.respond({ ok: false, error: `unsupported Dormouse control method '${detail.method}'` });
     };
 
     window.addEventListener('dormouse:control-request', handler);
     return () => window.removeEventListener('dormouse:control-request', handler);
-  }, [buildDorSurfaces, createIframeSurface, createSplitSurface, findSurfaceIdByUserTitle, killPaneImmediately, resolveVisibleSurface, surfaceRefForId]);
+  }, [buildDorSurfaces, createContentSurface, createSplitSurface, findAgentBrowserSurface, findSurfaceIdByUserTitle, killPaneImmediately, resolveVisibleSurface, surfaceRefForId]);
 
   const addSplitPanel = useCallback((
     id: string | null,

From 2725ed2b639d73e87f40f36df4433f7aa837b8fb Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 14:37:53 -0700
Subject: [PATCH 06/25] AgentBrowserPanel: live canvas viewer with
 stream-native input and tabs (Phases 3-7)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Frames: stream WS → createImageBitmap → canvas, with out-of-order drop
  and capped-backoff reconnect; placeholder states for no-session /
  no-page / session-ended.
- Input: input_mouse/input_keyboard on the same socket, terminal-style
  focus semantics (forward only while selected + passthrough; the wall's
  dual-tap leader still escapes).
- Tabs: strip fed by pushed tabs messages; switch/close via the host's
  allowlisted agentBrowserCommand; web-opened tabs get focused; header
  title follows the active tab.
- Lifecycle: killing the surface closes the session (killPaneImmediately).
- VS Code: CSP connect-src ws://, plus a loopback origin-stripping TCP
  relay in the extension host because the stream server 403s
  vscode-webview:// origins (verified live: 101 + frames through relay).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md               |  12 +-
 lib/src/components/Wall.tsx                   |   9 +-
 lib/src/components/wall/AgentBrowserPanel.tsx | 441 +++++++++++++++++-
 lib/src/lib/platform/types.ts                 |  19 +
 lib/src/lib/platform/vscode-adapter.ts        |  21 +-
 vscode-ext/src/agent-browser-host.ts          | 129 +++++
 vscode-ext/src/message-router.ts              |  23 +
 vscode-ext/src/message-types.ts               |   4 +
 vscode-ext/src/webview-html.ts                |   4 +-
 9 files changed, 650 insertions(+), 12 deletions(-)
 create mode 100644 vscode-ext/src/agent-browser-host.ts

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 96c1ce81..c8601d66 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -111,11 +111,13 @@ count. Tabs live entirely inside that surface's chrome.
 - **Integrated mode (1 tab):** the page title sits in the Dormouse surface
   header. No tab strip — the pretty, default case.
 - **Multi-tab mode (≥2 tabs):** a tab strip renders *below* the Dormouse header,
-  inside the surface body (title + favicon + close `×` per tab; no manual "+").
-  The strip is a thin view over `agent-browser tab list`; selecting a tab issues
-  `tab <n>` (the frame stream and CDP input follow the active target because
-  "active tab" is an agent-browser operation); the `×` issues `tab close`. When
-  the session returns to one tab, the surface drops back to integrated mode.
+  inside the surface body (title + close `×` per tab; no manual "+", and no
+  favicons — the webview CSP blocks arbitrary external images). The strip is a
+  thin view over the stream's pushed `tabs` messages; selecting a tab issues
+  `tab <tabId>` (the frame stream and input follow the active target because
+  "active tab" is an agent-browser operation); the `×` issues
+  `tab close <tabId>`. When the session returns to one tab, the surface drops
+  back to integrated mode.
 - **Orthogonal to minimize.** Internal tab count is invisible when the surface is
   minimized: title-only along the bottom whether it holds 1 tab or 9. Dormouse's
   binary "you're looking at it or you're not" model is preserved.
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 42c1c45c..6b71b32c 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -502,7 +502,14 @@ export function Wall({
 
   const killPaneImmediately = useCallback((id: string) => {
     const api = apiRef.current;
-    if (!api?.getPanel(id)) return;
+    const panel = api?.getPanel(id);
+    if (!api || !panel) return;
+    // Surface lifetime and browser lifetime are bound: killing an
+    // agent-browser surface closes its session (spec → Lifecycle).
+    const panelParams = panel.params as { surfaceType?: unknown; session?: unknown } | undefined;
+    if (panelParams?.surfaceType === 'agent-browser' && typeof panelParams.session === 'string') {
+      getPlatform().agentBrowserCommand?.(panelParams.session, ['close']).catch(() => {});
+    }
     orchestrateKill(api, id, selectPane, setSelectedId, killInProgressRef, overlayElRef);
     fireEvent({ type: 'kill', id });
   }, [fireEvent, selectPane]);
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 12742e83..8565fd1c 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -1,17 +1,110 @@
-import { useContext, useEffect, useLayoutEffect, useRef } from 'react';
+/**
+ * Live agent-browser session viewer (see docs/specs/dor-agent-browser.md).
+ *
+ * One WebSocket — the session's stream socket — carries everything: JPEG
+ * frames out, `input_mouse`/`input_keyboard` in, plus pushed `status` and
+ * `tabs` messages. Tab actions (switch/close) go through the host's
+ * `agentBrowserCommand` because a webview cannot spawn the agent-browser CLI.
+ */
+import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
+import { clsx } from 'clsx';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
+import { getPlatform } from '../../lib/platform';
 import {
   FreshlySpawnedContext,
+  ModeContext,
   PaneElementsContext,
+  SelectedIdContext,
   WallActionsContext,
 } from './wall-context';
 
-export function AgentBrowserPanel({ api }: IDockviewPanelProps) {
+type AgentBrowserPanelParams = {
+  surfaceType?: string;
+  session?: string;
+  key?: string;
+  wsPort?: number;
+};
+
+type StreamTab = {
+  tabId: string;
+  title: string | null;
+  url: string;
+  active: boolean;
+};
+
+type StreamStatus = {
+  connected: boolean;
+  screencasting: boolean;
+};
+
+// Mirrors agent-browser's own viewer: `text` is what makes typing land, and
+// the keyCode map covers the editing/navigation keys CDP wants spelled out.
+const SPECIAL_KEYS: Record<string, { text?: string; keyCode: number }> = {
+  Enter: { text: '\r', keyCode: 13 },
+  Tab: { text: '\t', keyCode: 9 },
+  Backspace: { text: '\b', keyCode: 8 },
+  Escape: { keyCode: 27 },
+  ArrowLeft: { keyCode: 37 },
+  ArrowUp: { keyCode: 38 },
+  ArrowRight: { keyCode: 39 },
+  ArrowDown: { keyCode: 40 },
+  Delete: { keyCode: 46 },
+  Home: { keyCode: 36 },
+  End: { keyCode: 35 },
+  PageUp: { keyCode: 33 },
+  PageDown: { keyCode: 34 },
+};
+
+const MOUSE_BUTTONS: Record<number, string> = { 0: 'left', 1: 'middle', 2: 'right' };
+const MOUSE_BUTTON_MASKS: Record<number, number> = { 0: 1, 1: 4, 2: 2 };
+
+function modifiers(e: { altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean }): number {
+  return (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0);
+}
+
+function tabDisplayTitle(tab: StreamTab): string {
+  const title = tab.title?.trim();
+  if (title) return title;
+  try {
+    const parsed = new URL(tab.url);
+    const path = parsed.pathname === '/' ? '' : parsed.pathname;
+    return `${parsed.host}${path}` || tab.url;
+  } catch {
+    return tab.url || 'untitled';
+  }
+}
+
+export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrowserPanelParams>) {
   const actions = useContext(WallActionsContext);
   const { elements: paneElements, bumpVersion } = useContext(PaneElementsContext);
   const freshlySpawned = useContext(FreshlySpawnedContext);
+  const mode = useContext(ModeContext);
+  const selectedId = useContext(SelectedIdContext);
   const elRef = useRef<HTMLDivElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  const session = params?.session;
+  const wsPort = params?.wsPort;
+  const interactive = mode === 'passthrough' && selectedId === api.id;
+  const interactiveRef = useRef(interactive);
+  interactiveRef.current = interactive;
+
+  const wsRef = useRef<WebSocket | null>(null);
+  const frameSeqRef = useRef(0);
+  const deviceRef = useRef({ width: 1280, height: 720 });
+  const [status, setStatus] = useState<StreamStatus | null>(null);
+  const [hasFrame, setHasFrame] = useState(false);
+  const [connectionLost, setConnectionLost] = useState(false);
+  const [tabs, setTabs] = useState<StreamTab[]>([]);
+  const knownTabIdsRef = useRef<Set<string>>(new Set());
+
+  const runAgentBrowser = useCallback((args: string[]) => {
+    if (!session) return;
+    getPlatform().agentBrowserCommand?.(session, args).catch(() => {});
+  }, [session]);
+
+  // --- pane registration + spawn animation (shared surface boilerplate) ---
 
   useEffect(() => {
     if (!elRef.current) return;
@@ -44,13 +137,353 @@ export function AgentBrowserPanel({ api }: IDockviewPanelProps) {
     };
   }, [api, freshlySpawned]);
 
+  // --- stream connection ---
+
+  useEffect(() => {
+    if (!wsPort) return;
+    let disposed = false;
+    let ws: WebSocket | null = null;
+    let retryTimer: ReturnType<typeof setTimeout> | undefined;
+    let failures = 0;
+
+    const drawFrame = (data: string, metadata?: { deviceWidth?: number; deviceHeight?: number }) => {
+      if (metadata?.deviceWidth && metadata?.deviceHeight) {
+        deviceRef.current = { width: metadata.deviceWidth, height: metadata.deviceHeight };
+      }
+      const seq = ++frameSeqRef.current;
+      const binary = atob(data);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+      createImageBitmap(new Blob([bytes], { type: 'image/jpeg' })).then((bitmap) => {
+        // JPEG decodes are async; drop frames that finished out of order.
+        if (disposed || seq !== frameSeqRef.current) {
+          bitmap.close();
+          return;
+        }
+        const canvas = canvasRef.current;
+        if (!canvas) {
+          bitmap.close();
+          return;
+        }
+        if (canvas.width !== bitmap.width) canvas.width = bitmap.width;
+        if (canvas.height !== bitmap.height) canvas.height = bitmap.height;
+        canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+        bitmap.close();
+        setHasFrame(true);
+      }).catch(() => {});
+    };
+
+    const handleMessage = (raw: unknown) => {
+      if (typeof raw !== 'string') return;
+      let msg: any;
+      try {
+        msg = JSON.parse(raw);
+      } catch {
+        return;
+      }
+      if (msg.type === 'frame' && typeof msg.data === 'string') {
+        drawFrame(msg.data, msg.metadata);
+      } else if (msg.type === 'status') {
+        setStatus({ connected: msg.connected === true, screencasting: msg.screencasting === true });
+        if (msg.connected === false) setConnectionLost(true);
+        else setConnectionLost(false);
+        if (typeof msg.viewportWidth === 'number' && typeof msg.viewportHeight === 'number') {
+          deviceRef.current = { width: msg.viewportWidth, height: msg.viewportHeight };
+        }
+      } else if (msg.type === 'tabs' && Array.isArray(msg.tabs)) {
+        const next: StreamTab[] = msg.tabs
+          .filter((t: any) => typeof t?.tabId === 'string')
+          .map((t: any) => ({
+            tabId: t.tabId,
+            title: typeof t.title === 'string' ? t.title : null,
+            url: typeof t.url === 'string' ? t.url : '',
+            active: t.active === true,
+          }));
+        // Web-opened tabs (popups, target=_blank) are focused, matching
+        // browser foregrounding. Skip the first message — that's catch-up,
+        // not a popup.
+        const known = knownTabIdsRef.current;
+        if (known.size > 0) {
+          const fresh = next.filter((t) => !known.has(t.tabId));
+          const newest = fresh[fresh.length - 1];
+          if (newest && !newest.active) runAgentBrowser(['tab', newest.tabId]);
+        }
+        knownTabIdsRef.current = new Set(next.map((t) => t.tabId));
+        setTabs(next);
+      }
+    };
+
+    const connect = async () => {
+      let url: string | null = null;
+      try {
+        url = (await getPlatform().getAgentBrowserStreamUrl?.(wsPort)) ?? null;
+      } catch {
+        url = null;
+      }
+      if (disposed) return;
+      ws = new WebSocket(url ?? `ws://127.0.0.1:${wsPort}`);
+      wsRef.current = ws;
+      ws.onopen = () => {
+        failures = 0;
+        setConnectionLost(false);
+      };
+      ws.onmessage = (ev) => handleMessage(ev.data);
+      ws.onclose = () => {
+        wsRef.current = null;
+        if (disposed) return;
+        failures += 1;
+        // The port dies with the session, so repeated refusals mean the
+        // browser is gone; keep a slow retry alive in case it comes back on
+        // the same port, but a new `dor ab` updating wsPort is the real path.
+        if (failures >= 3) setConnectionLost(true);
+        retryTimer = setTimeout(connect, Math.min(1000 * 2 ** failures, 10000));
+      };
+      ws.onerror = () => {};
+    };
+
+    setHasFrame(false);
+    setConnectionLost(false);
+    void connect();
+    return () => {
+      disposed = true;
+      if (retryTimer !== undefined) clearTimeout(retryTimer);
+      wsRef.current = null;
+      ws?.close();
+    };
+  }, [wsPort, runAgentBrowser]);
+
+  // --- header title follows the active tab ---
+
+  useEffect(() => {
+    const active = tabs.find((tab) => tab.active) ?? tabs[0];
+    if (active) api.setTitle(tabDisplayTitle(active));
+  }, [tabs, api]);
+
+  // --- input forwarding (stream-native input_* messages) ---
+
+  const send = useCallback((payload: Record<string, unknown>) => {
+    const ws = wsRef.current;
+    if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(payload));
+  }, []);
+
+  const toDevice = useCallback((e: { clientX: number; clientY: number }): { x: number; y: number } | null => {
+    const canvas = canvasRef.current;
+    if (!canvas) return null;
+    const rect = canvas.getBoundingClientRect();
+    if (!rect.width || !rect.height) return null;
+    const device = deviceRef.current;
+    return {
+      x: Math.round((e.clientX - rect.left) * (device.width / rect.width)),
+      y: Math.round((e.clientY - rect.top) * (device.height / rect.height)),
+    };
+  }, []);
+
+  const buttonsHeldRef = useRef(0);
+  const lastMoveRef = useRef(0);
+  const lastClickRef = useRef({ t: 0, x: 0, y: 0, count: 0, button: -1 });
+
+  const clickCountFor = (button: number, x: number, y: number): number => {
+    const last = lastClickRef.current;
+    const now = performance.now();
+    const sameSpot = Math.abs(x - last.x) < 5 && Math.abs(y - last.y) < 5;
+    if (now - last.t < 500 && sameSpot && button === last.button) {
+      last.count = Math.min(3, last.count + 1);
+    } else {
+      lastClickRef.current = { t: now, x, y, count: 1, button };
+    }
+    lastClickRef.current.t = now;
+    return lastClickRef.current.count;
+  };
+
+  const onCanvasMouseDown = (e: React.MouseEvent) => {
+    if (!interactiveRef.current) return;
+    e.preventDefault();
+    const point = toDevice(e);
+    if (!point) return;
+    buttonsHeldRef.current |= MOUSE_BUTTON_MASKS[e.button] ?? 0;
+    send({
+      type: 'input_mouse',
+      eventType: 'mousePressed',
+      x: point.x,
+      y: point.y,
+      button: MOUSE_BUTTONS[e.button] ?? 'left',
+      buttons: buttonsHeldRef.current,
+      clickCount: clickCountFor(e.button, point.x, point.y),
+      modifiers: modifiers(e),
+    });
+  };
+
+  const onCanvasMouseUp = (e: React.MouseEvent) => {
+    if (!interactiveRef.current) return;
+    e.preventDefault();
+    const point = toDevice(e);
+    if (!point) return;
+    buttonsHeldRef.current &= ~(MOUSE_BUTTON_MASKS[e.button] ?? 0);
+    send({
+      type: 'input_mouse',
+      eventType: 'mouseReleased',
+      x: point.x,
+      y: point.y,
+      button: MOUSE_BUTTONS[e.button] ?? 'left',
+      buttons: buttonsHeldRef.current,
+      clickCount: lastClickRef.current.count,
+      modifiers: modifiers(e),
+    });
+  };
+
+  const onCanvasMouseMove = (e: React.MouseEvent) => {
+    if (!interactiveRef.current) return;
+    const now = performance.now();
+    if (now - lastMoveRef.current < 8) return;
+    lastMoveRef.current = now;
+    const point = toDevice(e);
+    if (!point) return;
+    const held = buttonsHeldRef.current;
+    send({
+      type: 'input_mouse',
+      eventType: 'mouseMoved',
+      x: point.x,
+      y: point.y,
+      button: held ? (held & 1 ? 'left' : held & 2 ? 'right' : 'middle') : 'none',
+      buttons: held,
+      modifiers: modifiers(e),
+    });
+  };
+
+  // Wheel needs a non-passive listener to preventDefault, which JSX onWheel
+  // does not guarantee.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    const onWheel = (e: WheelEvent) => {
+      if (!interactiveRef.current) return;
+      e.preventDefault();
+      const point = toDevice(e);
+      if (!point) return;
+      send({
+        type: 'input_mouse',
+        eventType: 'mouseWheel',
+        x: point.x,
+        y: point.y,
+        button: 'none',
+        clickCount: 0,
+        deltaX: e.deltaX,
+        deltaY: e.deltaY,
+        modifiers: modifiers(e),
+      });
+    };
+    canvas.addEventListener('wheel', onWheel, { passive: false });
+    return () => canvas.removeEventListener('wheel', onWheel);
+  }, [send, toDevice]);
+
+  const sendKey = (e: React.KeyboardEvent, eventType: 'keyDown' | 'keyUp') => {
+    const info = SPECIAL_KEYS[e.key];
+    send({
+      type: 'input_keyboard',
+      eventType,
+      key: e.key,
+      code: e.code,
+      text: eventType === 'keyDown' ? info?.text ?? (e.key.length === 1 ? e.key : undefined) : undefined,
+      windowsVirtualKeyCode: info?.keyCode ?? (e.key.length === 1 ? e.key.charCodeAt(0) : 0),
+      modifiers: modifiers(e),
+    });
+  };
+
+  const onKeyDown = (e: React.KeyboardEvent) => {
+    if (!interactiveRef.current) return;
+    e.preventDefault();
+    sendKey(e, 'keyDown');
+  };
+
+  const onKeyUp = (e: React.KeyboardEvent) => {
+    if (!interactiveRef.current) return;
+    e.preventDefault();
+    sendKey(e, 'keyUp');
+  };
+
+  // Hold DOM focus while interactive so keystrokes land here, mirroring how
+  // xterm holds focus for terminal surfaces.
+  useEffect(() => {
+    if (interactive) elRef.current?.focus({ preventScroll: true });
+  }, [interactive]);
+
+  // --- tab strip actions ---
+
+  const selectTab = (tab: StreamTab) => {
+    if (!tab.active) runAgentBrowser(['tab', tab.tabId]);
+  };
+
+  const closeTab = (tab: StreamTab) => {
+    runAgentBrowser(['tab', 'close', tab.tabId]);
+  };
+
+  // --- placeholder state ---
+
+  const placeholder = (() => {
+    if (!wsPort) return `Waiting for browser session ${session ?? ''} — run dor ab open <url>`;
+    if (connectionLost || status?.connected === false) {
+      return `Browser session ${session ?? ''} ended — run dor ab open <url> to restart it, or close this surface.`;
+    }
+    if (!hasFrame) {
+      return status && !status.screencasting
+        ? 'No page is open — run dor ab open <url>'
+        : `Connecting to ${session ?? 'browser session'}…`;
+    }
+    return null;
+  })();
+
   return (
     <div
       ref={elRef}
-      className={`flex h-full w-full items-center justify-center overflow-hidden bg-terminal-bg px-4 text-center text-sm text-muted ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
+      tabIndex={-1}
+      className={`flex h-full w-full flex-col overflow-hidden bg-terminal-bg outline-none ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
       onMouseDown={() => actions.onClickPanel(api.id)}
+      onKeyDown={onKeyDown}
+      onKeyUp={onKeyUp}
     >
-      agent-browser surface stub
+      {tabs.length >= 2 && (
+        <div className="flex shrink-0 items-center gap-0.5 overflow-x-auto border-b border-border bg-surface-raised px-1 py-0.5">
+          {tabs.map((tab) => (
+            <div
+              key={tab.tabId}
+              title={tab.url}
+              className={clsx(
+                'group flex min-w-0 max-w-48 cursor-pointer items-center gap-1 rounded px-2 py-0.5 text-xs',
+                tab.active ? 'bg-terminal-bg text-foreground' : 'text-muted hover:bg-terminal-bg/60',
+              )}
+              onClick={() => selectTab(tab)}
+            >
+              <span className="truncate">{tabDisplayTitle(tab)}</span>
+              <button
+                type="button"
+                aria-label="Close tab"
+                className="shrink-0 rounded px-0.5 text-muted opacity-0 transition-opacity hover:text-foreground group-hover:opacity-100"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  closeTab(tab);
+                }}
+              >
+                ×
+              </button>
+            </div>
+          ))}
+        </div>
+      )}
+      <div className="relative flex min-h-0 flex-1 items-center justify-center">
+        <canvas
+          ref={canvasRef}
+          className={clsx('max-h-full max-w-full select-none', !hasFrame && 'hidden')}
+          onMouseDown={onCanvasMouseDown}
+          onMouseUp={onCanvasMouseUp}
+          onMouseMove={onCanvasMouseMove}
+          onContextMenu={(e) => {
+            if (interactiveRef.current) e.preventDefault();
+          }}
+        />
+        {placeholder && (
+          <div className="px-4 text-center text-sm text-muted">{placeholder}</div>
+        )}
+      </div>
     </div>
   );
 }
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index e9461e66..b409cf57 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -34,6 +34,16 @@ export const OPEN_PORT_TIMEOUT_MS = 3000;
 
 export type AlertStateDetail = { id: string } & AlertState;
 
+export interface AgentBrowserCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Subcommands the host will run on the webview's behalf — this is a narrow
+ * channel for tab actions and session teardown, not a general exec path. */
+export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'close'] as const;
+
 export interface PlatformAdapter {
   // Lifecycle
   init(): Promise<void>;
@@ -71,6 +81,15 @@ export interface PlatformAdapter {
   // VS Code-only escape hatch for mirrored workbench shortcuts from webviews.
   runWorkbenchCommand?(command: VSCodeWorkbenchCommand): void;
 
+  // agent-browser surface support (see docs/specs/dor-agent-browser.md).
+  // Runs the user's agent-browser binary against a session; the host validates
+  // args[0] against AGENT_BROWSER_ALLOWED_SUBCOMMANDS.
+  agentBrowserCommand?(session: string, args: string[]): Promise<AgentBrowserCommandResult>;
+  // The WebSocket URL for a session's stream port. Hosts whose webview origin
+  // the agent-browser stream server rejects (VS Code) return a relay URL;
+  // absent or null falls back to ws://127.0.0.1:<port>.
+  getAgentBrowserStreamUrl?(port: number): Promise<string | null>;
+
   // PTY event listeners
   onPtyData(handler: (detail: { id: string; data: string }) => void): void;
   offPtyData(handler: (detail: { id: string; data: string }) => void): void;
diff --git a/lib/src/lib/platform/vscode-adapter.ts b/lib/src/lib/platform/vscode-adapter.ts
index 025ec189..0e692c96 100644
--- a/lib/src/lib/platform/vscode-adapter.ts
+++ b/lib/src/lib/platform/vscode-adapter.ts
@@ -1,4 +1,4 @@
-import type { AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
+import type { AgentBrowserCommandResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
 import { OPEN_PORT_TIMEOUT_MS } from './types';
 import { setDefaultShellOpts } from '../shell-defaults';
 import {
@@ -215,6 +215,25 @@ export class VSCodeAdapter implements PlatformAdapter {
     this.vscode.postMessage({ type: 'dormouse:runWorkbenchCommand', command });
   }
 
+  async agentBrowserCommand(session: string, args: string[]): Promise<AgentBrowserCommandResult> {
+    const result = await this.requestResponse<AgentBrowserCommandResult>(
+      'agentBrowser:command', 'agentBrowser:commandResult', { session, args },
+      (msg) => ({ exitCode: msg.exitCode, stdout: msg.stdout, stderr: msg.stderr }),
+      10000,
+    );
+    return result ?? { exitCode: 1, stdout: '', stderr: 'agent-browser command timed out' };
+  }
+
+  getAgentBrowserStreamUrl(port: number): Promise<string | null> {
+    // The agent-browser stream server rejects vscode-webview:// origins, so
+    // the extension host relays the stream (see agent-browser-host.ts).
+    return this.requestResponse<string | null>(
+      'agentBrowser:getStreamUrl', 'agentBrowser:streamUrl', { port },
+      (msg) => msg.url,
+      5000,
+    );
+  }
+
   onPtyData(handler: (detail: { id: string; data: string }) => void): void {
     this.dataHandlers.add(handler);
   }
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
new file mode 100644
index 00000000..ba621a50
--- /dev/null
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -0,0 +1,129 @@
+/**
+ * Extension-host support for the agent-browser surface
+ * (docs/specs/dor-agent-browser.md → "Host capabilities").
+ *
+ * Two narrow capabilities, both on behalf of the webview:
+ *
+ * 1. `runAgentBrowserCommand` — runs the user's agent-browser binary against a
+ *    session for tab actions and session teardown. Subcommands are
+ *    allowlisted; this is not a general exec channel.
+ *
+ * 2. `ensureStreamRelayPort` — a loopback-only TCP relay that strips the
+ *    `Origin` header from WebSocket upgrade requests. The agent-browser stream
+ *    server returns 403 for `vscode-webview://` origins (only localhost or
+ *    absent origins are accepted), so the webview cannot connect directly; it
+ *    connects to ws://127.0.0.1:<relayPort>/stream/<streamPort> instead and
+ *    the relay pipes bytes to 127.0.0.1:<streamPort>.
+ */
+import * as net from 'net';
+import { spawn } from 'child_process';
+import { log } from './log';
+
+const ALLOWED_SUBCOMMANDS = new Set(['tab', 'close']);
+
+export interface AgentBrowserCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export function runAgentBrowserCommand(session: string, args: string[]): Promise<AgentBrowserCommandResult> {
+  if (typeof session !== 'string' || !session) {
+    return Promise.resolve({ exitCode: 1, stdout: '', stderr: 'session is required' });
+  }
+  const subcommand = args[0];
+  if (!subcommand || !ALLOWED_SUBCOMMANDS.has(subcommand)) {
+    return Promise.resolve({ exitCode: 1, stdout: '', stderr: `agent-browser subcommand '${subcommand ?? ''}' is not allowed from the webview` });
+  }
+
+  const binary = process.env.DORMOUSE_AGENT_BROWSER_BIN || 'agent-browser';
+  return new Promise((resolve) => {
+    const child = spawn(binary, ['--session', session, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (chunk) => { stdout += String(chunk); });
+    child.stderr.on('data', (chunk) => { stderr += String(chunk); });
+    child.on('error', (err) => {
+      log.info(`[agent-browser] spawn failed: ${err.message}`);
+      resolve({ exitCode: 1, stdout: '', stderr: err.message });
+    });
+    child.on('close', (code) => {
+      resolve({ exitCode: code ?? 1, stdout, stderr });
+    });
+  });
+}
+
+let relayPortPromise: Promise<number> | null = null;
+
+export function ensureStreamRelayPort(): Promise<number> {
+  if (!relayPortPromise) {
+    relayPortPromise = new Promise<number>((resolve, reject) => {
+      const server = net.createServer(handleRelayClient);
+      server.on('error', (err) => {
+        log.info(`[agent-browser] stream relay error: ${err.message}`);
+        relayPortPromise = null;
+        reject(err);
+      });
+      server.unref();
+      server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        if (address && typeof address === 'object') {
+          log.info(`[agent-browser] stream relay listening on 127.0.0.1:${address.port}`);
+          resolve(address.port);
+        } else {
+          reject(new Error('stream relay failed to bind'));
+        }
+      });
+    });
+  }
+  return relayPortPromise;
+}
+
+// The relay is loopback-only on both sides: it accepts connections from
+// 127.0.0.1 and dials only 127.0.0.1:<port>. It rewrites the upgrade request
+// head (path → "/", Origin dropped, Host rewritten) and from then on is a dumb
+// byte pipe in both directions.
+function handleRelayClient(client: net.Socket): void {
+  let head = Buffer.alloc(0);
+  client.on('error', () => {});
+
+  const onData = (chunk: Buffer) => {
+    head = Buffer.concat([head, chunk]);
+    const headEnd = head.indexOf('\r\n\r\n');
+    if (headEnd === -1) {
+      if (head.length > 16384) client.destroy();
+      return;
+    }
+    client.off('data', onData);
+    client.pause();
+
+    const headText = head.subarray(0, headEnd).toString('latin1');
+    const remainder = head.subarray(headEnd + 4);
+    const requestMatch = /^GET \/stream\/(\d{1,5}) HTTP\/1\.1\r\n/.exec(headText);
+    const targetPort = requestMatch ? Number(requestMatch[1]) : 0;
+    if (!targetPort || targetPort > 65535) {
+      client.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+      return;
+    }
+
+    const headerLines = headText.split('\r\n').slice(1).filter((line) => {
+      const name = line.slice(0, line.indexOf(':')).trim().toLowerCase();
+      return name !== 'origin';
+    }).map((line) => (
+      line.toLowerCase().startsWith('host:') ? `Host: 127.0.0.1:${targetPort}` : line
+    ));
+    const rewritten = `GET / HTTP/1.1\r\n${headerLines.join('\r\n')}\r\n\r\n`;
+
+    const upstream = net.connect(targetPort, '127.0.0.1', () => {
+      upstream.write(rewritten);
+      if (remainder.length) upstream.write(remainder);
+      client.pipe(upstream);
+      upstream.pipe(client);
+      client.resume();
+    });
+    upstream.on('error', () => client.destroy());
+    client.on('close', () => upstream.destroy());
+  };
+
+  client.on('data', onData);
+}
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 85d78491..286c1324 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -13,6 +13,7 @@ import type { TerminalSemanticEvent } from '../../lib/src/lib/terminal-state';
 import type { PersistedSession } from '../../lib/src/lib/session-types';
 import type { WebviewMessage, ExtensionMessage } from './message-types';
 import type { DorControlRequest } from './pty-manager';
+import { ensureStreamRelayPort, runAgentBrowserCommand } from './agent-browser-host';
 import { log } from './log';
 
 const clipboardOps = require('../../lib/clipboard-ops.cjs') as {
@@ -351,6 +352,28 @@ export function attachRouter(
           void vscode.commands.executeCommand(msg.command);
         }
         break;
+      case 'agentBrowser:command':
+        runAgentBrowserCommand(msg.session, Array.isArray(msg.args) ? msg.args : []).then((result) => {
+          webview.postMessage({
+            type: 'agentBrowser:commandResult', requestId: msg.requestId, ...result,
+          } satisfies ExtensionMessage);
+        });
+        break;
+      case 'agentBrowser:getStreamUrl': {
+        const streamPort = Number.isInteger(msg.port) && msg.port > 0 && msg.port <= 65535 ? msg.port : null;
+        if (!streamPort) {
+          webview.postMessage({ type: 'agentBrowser:streamUrl', requestId: msg.requestId, url: null } satisfies ExtensionMessage);
+          break;
+        }
+        ensureStreamRelayPort().then(
+          (relayPort) => webview.postMessage({
+            type: 'agentBrowser:streamUrl', requestId: msg.requestId,
+            url: `ws://127.0.0.1:${relayPort}/stream/${streamPort}`,
+          } satisfies ExtensionMessage),
+          () => webview.postMessage({ type: 'agentBrowser:streamUrl', requestId: msg.requestId, url: null } satisfies ExtensionMessage),
+        );
+        break;
+      }
       case 'dormouse:init': {
         // Webview has (re-)initialized — subscribe to live events.
         // Tear down previous subscriptions first (webview was destroyed and recreated).
diff --git a/vscode-ext/src/message-types.ts b/vscode-ext/src/message-types.ts
index ba609ebe..c787c805 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -18,6 +18,8 @@ export type WebviewMessage =
   | { type: 'clipboard:readImage'; requestId: string }
   | { type: 'dormouse:openExternal'; uri: string }
   | { type: 'dormouse:runWorkbenchCommand'; command: VSCodeWorkbenchCommand }
+  | { type: 'agentBrowser:command'; session: string; args: string[]; requestId: string }
+  | { type: 'agentBrowser:getStreamUrl'; port: number; requestId: string }
   | { type: 'dormouse:init' }
   | { type: 'dormouse:saveState'; state: unknown }
   | { type: 'dormouse:flushSessionSaveDone'; requestId: string }
@@ -54,6 +56,8 @@ export type ExtensionMessage =
   | { type: 'pty:shells'; shells: Array<{ name: string; path: string; args: string[] }>; requestId?: string }
   | { type: 'clipboard:files'; paths: string[] | null; requestId: string }
   | { type: 'clipboard:image'; path: string | null; requestId: string }
+  | { type: 'agentBrowser:commandResult'; requestId: string; exitCode: number; stdout: string; stderr: string }
+  | { type: 'agentBrowser:streamUrl'; requestId: string; url: string | null }
   | {
       type: 'dormouse:newTerminal';
       shell?: string;
diff --git a/vscode-ext/src/webview-html.ts b/vscode-ext/src/webview-html.ts
index ee5fcb5c..ab6fc807 100644
--- a/vscode-ext/src/webview-html.ts
+++ b/vscode-ext/src/webview-html.ts
@@ -29,7 +29,9 @@ export function getWebviewHtml(
     `script-src 'nonce-${nonce}'`,
     `font-src ${webview.cspSource}`,
     `img-src ${webview.cspSource} data: blob:`,
-    `connect-src ${webview.cspSource}`,
+    // ws: entries cover the agent-browser stream relay (frames + input for
+    // browser surfaces; see docs/specs/dor-agent-browser.md).
+    `connect-src ${webview.cspSource} ws://127.0.0.1:* ws://localhost:*`,
     // `dor iframe` opens arbitrary absolute http(s) URLs in an iframe surface.
     // Without a frame-src override the `default-src 'none'` fallback blocks the
     // frame outright, leaving a blank (white) pane. parseIframeUrl already

From e9abbbb009905b0692a64754129ab3aaaac05ef8 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 14:38:59 -0700
Subject: [PATCH 07/25] Record agent-browser implementation status in plan doc

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
index 5b5e86fe..f0fa692a 100644
--- a/DOR_AGENT_BROWSER.md
+++ b/DOR_AGENT_BROWSER.md
@@ -2,6 +2,23 @@
 
 Implementation plan for the `dor agent-browser` / `dor ab` surface.
 
+## Implementation status (2026-06-12)
+
+All seven phases are built; see the spike outcome under Phase 4 for the three
+design changes the build forced (dot-separated session names, stream-native
+input replacing the CDP proxy, VS Code origin-stripping relay). Verified so
+far: CLI phases headless (`dor/test`), stream input + relay live against
+agent-browser 0.27.0. Outstanding:
+
+- **In-app dogfood pass** (VS Code): extension is built and installed; needs a
+  window reload and a `dor ab open` walk-through of frames/input/tabs/kill.
+- **Standalone (Tauri) gaps:** frames + input work (its origin is allowed, so
+  it connects to the stream directly), but `agentBrowserCommand` is not
+  implemented in the Tauri adapter — tab switch/close, popup auto-focus, and
+  kill→session-close are inert there until the sidecar grows that capability.
+- **Favicons** are omitted from the tab strip (webview CSP blocks external
+  images); spec updated.
+
 **Design spec (read first):** [`docs/specs/dor-agent-browser.md`](docs/specs/dor-agent-browser.md).
 This plan does not restate the design — it sequences the build and says how to
 verify each step. When the plan and the spec disagree, the spec wins; if the

From 9fa38f14c8c09a655888b0760e86c82c1919d853 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 15:16:53 -0700
Subject: [PATCH 08/25] Fix dogfood round 1: input mapping, keyboard focus,
 host binary resolution
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Mouse offset: screencast frames can be SHORTER than the viewport
  (observed 1280×577 vs 1280×720 device), so scaling y by deviceHeight
  stretched clicks downward. Map into frame pixels and apply one uniform
  deviceWidth/frameWidth scale instead.
- Keyboard dead: clicking the non-focusable canvas blurred focus to
  <body> (tabIndex=-1 ancestors don't receive click focus, and the first
  click predates the interactive flip). Focus the pane explicitly on
  mousedown (rAF-deferred past dockview's focus churn) and add a
  window-capture fallback that forwards keys whenever the pane is
  interactive but focus fell through.
- Tab actions inert: the GUI extension host's PATH lacks nvm shims, so
  spawn('agent-browser') ENOENTed silently. dor ab now resolves the
  absolute binary path in the invoking terminal and threads it through
  the surface request → panel params → host, which falls back through
  DORMOUSE_AGENT_BROWSER_BIN and PATH on ENOENT. Failures now
  console.warn instead of being swallowed.

Daemon-side behavior verified live: input coords dispatch 1:1 in
viewport CSS px; tab t<N>/close work and the stream re-broadcasts tabs
on activation changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 dor/src/commands/agent-browser.ts             | 30 +++++++-
 dor/src/commands/types.ts                     |  3 +
 dor/src/node-runtime.d.ts                     |  4 +
 dor/test/cli-output.test.mjs                  | 26 ++++++-
 lib/src/components/Wall.tsx                   | 24 ++++--
 lib/src/components/wall/AgentBrowserPanel.tsx | 73 ++++++++++++++++---
 lib/src/lib/platform/types.ts                 |  6 +-
 lib/src/lib/platform/vscode-adapter.ts        |  4 +-
 vscode-ext/src/agent-browser-host.ts          | 35 +++++++--
 vscode-ext/src/message-router.ts              |  6 +-
 vscode-ext/src/message-types.ts               |  2 +-
 11 files changed, 180 insertions(+), 33 deletions(-)

diff --git a/dor/src/commands/agent-browser.ts b/dor/src/commands/agent-browser.ts
index ed74e3e5..00aed56f 100644
--- a/dor/src/commands/agent-browser.ts
+++ b/dor/src/commands/agent-browser.ts
@@ -17,7 +17,9 @@
 
 import { buildCommand } from '@stricli/core';
 import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
 import type {
+  CliEnv,
   AgentBrowserExecResult,
   CliOptions,
   CliResult,
@@ -177,7 +179,17 @@ export async function runAgentBrowserCli(args: string[], options: CliOptions): P
       try {
         const status = await exec(binary, ['--session', session, 'stream', 'status', '--json']);
         const wsPort = parseStreamPort(status.stdout);
-        await clientResult.value.agentBrowserSurface({ key, session, wsPort });
+        // The Dormouse host (e.g. a GUI-launched VS Code extension host) may
+        // not share this terminal's PATH, so resolve the binary to an
+        // absolute path here, where the user's environment is authoritative,
+        // and pass it along for host-side tab/close commands.
+        const binaryPath = resolveBinaryPath(binary, env);
+        await clientResult.value.agentBrowserSurface({
+          key,
+          session,
+          wsPort,
+          ...(binaryPath ? { binaryPath } : {}),
+        });
       } catch (error) {
         stderrSuffix = `Warning: could not open the Dormouse browser surface: ${error instanceof Error ? error.message : String(error)}\n`;
       }
@@ -200,6 +212,22 @@ function shouldManageSurface(exitCode: number, rest: string[]): boolean {
   return subcommand !== undefined && subcommand !== 'close';
 }
 
+export function resolveBinaryPath(binary: string, env: CliEnv): string | undefined {
+  if (binary.includes('/') || binary.includes('\\')) return binary;
+  const pathVar = env.PATH;
+  if (!pathVar) return undefined;
+  const isWindows = process.platform === 'win32';
+  const names = isWindows ? [`${binary}.cmd`, `${binary}.exe`, `${binary}.bat`] : [binary];
+  for (const dir of pathVar.split(isWindows ? ';' : ':')) {
+    if (!dir) continue;
+    for (const name of names) {
+      const candidate = `${dir}${isWindows ? '\\' : '/'}${name}`;
+      if (existsSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
 function parseStreamPort(stdout: string): number | undefined {
   try {
     const parsed = JSON.parse(stdout) as { port?: unknown; data?: { port?: unknown } };
diff --git a/dor/src/commands/types.ts b/dor/src/commands/types.ts
index a2898c66..dc948dcb 100644
--- a/dor/src/commands/types.ts
+++ b/dor/src/commands/types.ts
@@ -127,6 +127,9 @@ export interface AgentBrowserSurfaceRequest {
   session: string;
   /** Session stream WebSocket port from `stream status --json`. */
   wsPort?: number;
+  /** Absolute path of the agent-browser binary, resolved with the invoking
+   * terminal's PATH so the host (which may lack it) can run tab/close. */
+  binaryPath?: string;
 }
 
 export interface AgentBrowserSurfaceResponse {
diff --git a/dor/src/node-runtime.d.ts b/dor/src/node-runtime.d.ts
index 836d8da4..7197daa7 100644
--- a/dor/src/node-runtime.d.ts
+++ b/dor/src/node-runtime.d.ts
@@ -34,6 +34,10 @@ declare module 'node:child_process' {
   }): ChildProcess;
 }
 
+declare module 'node:fs' {
+  export function existsSync(path: string): boolean;
+}
+
 declare const process: {
   platform: string;
   ppid: number;
diff --git a/dor/test/cli-output.test.mjs b/dor/test/cli-output.test.mjs
index bcaef4c3..9331fd6d 100644
--- a/dor/test/cli-output.test.mjs
+++ b/dor/test/cli-output.test.mjs
@@ -498,14 +498,36 @@ test('agent-browser missing binary output', async () => {
   );
 });
 
-test('agent-browser respects DORMOUSE_AGENT_BROWSER_BIN', async () => {
+test('agent-browser respects DORMOUSE_AGENT_BROWSER_BIN and forwards it as binaryPath', async () => {
   const ab = fakeAgentBrowser();
+  const client = fixtureClient();
   await runCli(['ab', 'snapshot'], {
-    client: fixtureClient(),
+    client,
     execAgentBrowser: ab.exec,
     env: { DORMOUSE_AGENT_BROWSER_BIN: '/opt/custom/agent-browser' },
   });
   assert.equal(ab.calls[0][0], '/opt/custom/agent-browser');
+  assert.equal(client.requests[0].request.binaryPath, '/opt/custom/agent-browser');
+});
+
+test('agent-browser resolves the binary on PATH to an absolute binaryPath', async () => {
+  const { mkdtemp, writeFile: write, rm } = await import('node:fs/promises');
+  const { tmpdir } = await import('node:os');
+  const dir = await mkdtemp(join(tmpdir(), 'dor-ab-'));
+  try {
+    const binPath = join(dir, 'agent-browser');
+    await write(binPath, '#!/bin/sh\n', { mode: 0o755 });
+    const ab = fakeAgentBrowser();
+    const client = fixtureClient();
+    await runCli(['ab', 'snapshot'], {
+      client,
+      execAgentBrowser: ab.exec,
+      env: { PATH: `/nonexistent:${dir}` },
+    });
+    assert.equal(client.requests[0].request.binaryPath, binPath);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
 });
 
 test('list-panes text output', async () => {
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 6b71b32c..078b9f69 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -99,6 +99,7 @@ type DorControlParams = {
   key?: unknown;
   lines?: unknown;
   minimized?: unknown;
+  binaryPath?: unknown;
   pane?: string;
   session?: unknown;
   surface?: unknown;
@@ -506,9 +507,10 @@ export function Wall({
     if (!api || !panel) return;
     // Surface lifetime and browser lifetime are bound: killing an
     // agent-browser surface closes its session (spec → Lifecycle).
-    const panelParams = panel.params as { surfaceType?: unknown; session?: unknown } | undefined;
+    const panelParams = panel.params as { surfaceType?: unknown; session?: unknown; binaryPath?: unknown } | undefined;
     if (panelParams?.surfaceType === 'agent-browser' && typeof panelParams.session === 'string') {
-      getPlatform().agentBrowserCommand?.(panelParams.session, ['close']).catch(() => {});
+      const binaryPath = typeof panelParams.binaryPath === 'string' ? panelParams.binaryPath : undefined;
+      getPlatform().agentBrowserCommand?.(panelParams.session, ['close'], binaryPath).catch(() => {});
     }
     orchestrateKill(api, id, selectPane, setSelectedId, killInProgressRef, overlayElRef);
     fireEvent({ type: 'kill', id });
@@ -1330,16 +1332,22 @@ export function Wall({
         }
         const key = stringParam(params.key);
         const wsPort = numberParam(params.wsPort);
+        const binaryPath = stringParam(params.binaryPath);
+        const refreshedParams = {
+          ...(wsPort !== undefined ? { wsPort } : {}),
+          ...(binaryPath !== undefined ? { binaryPath } : {}),
+        };
 
         const existing = findAgentBrowserSurface(session);
         if (existing) {
           // Reuse: refresh the stream port (OS-assigned, churns across session
-          // restarts) so the panel reconnects to the live stream.
-          if (!existing.minimized && wsPort !== undefined) {
-            api.getPanel(existing.id)?.api.updateParameters({ wsPort });
-          } else if (existing.minimized && wsPort !== undefined) {
+          // restarts) so the panel reconnects to the live stream, and the
+          // resolved binary path alongside it.
+          if (!existing.minimized && Object.keys(refreshedParams).length > 0) {
+            api.getPanel(existing.id)?.api.updateParameters(refreshedParams);
+          } else if (existing.minimized && Object.keys(refreshedParams).length > 0) {
             const nextDoors = doorsRef.current.map((door) => door.id === existing.id
-              ? { ...door, params: { ...door.params, wsPort } }
+              ? { ...door, params: { ...door.params, ...refreshedParams } }
               : door);
             doorsRef.current = nextDoors;
             setDoors(nextDoors);
@@ -1369,7 +1377,7 @@ export function Wall({
             surfaceType: 'agent-browser',
             session,
             ...(key !== undefined ? { key } : {}),
-            ...(wsPort !== undefined ? { wsPort } : {}),
+            ...refreshedParams,
           },
           reference: target.value,
           title: key ?? session,
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 8565fd1c..0645e803 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -24,6 +24,7 @@ type AgentBrowserPanelParams = {
   session?: string;
   key?: string;
   wsPort?: number;
+  binaryPath?: string;
 };
 
 type StreamTab = {
@@ -99,10 +100,22 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
   const [tabs, setTabs] = useState<StreamTab[]>([]);
   const knownTabIdsRef = useRef<Set<string>>(new Set());
 
+  const binaryPath = params?.binaryPath;
   const runAgentBrowser = useCallback((args: string[]) => {
     if (!session) return;
-    getPlatform().agentBrowserCommand?.(session, args).catch(() => {});
-  }, [session]);
+    const command = getPlatform().agentBrowserCommand;
+    if (!command) {
+      console.warn('[agent-browser] this host cannot run agent-browser commands; tab actions are unavailable');
+      return;
+    }
+    command(session, args, binaryPath).then((result) => {
+      if (result.exitCode !== 0) {
+        console.warn(`[agent-browser] ${args.join(' ')} failed:`, result.stderr || result.stdout || `exit ${result.exitCode}`);
+      }
+    }).catch((error) => {
+      console.warn(`[agent-browser] ${args.join(' ')} failed:`, error);
+    });
+  }, [session, binaryPath]);
 
   // --- pane registration + spawn animation (shared surface boilerplate) ---
 
@@ -268,13 +281,18 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
 
   const toDevice = useCallback((e: { clientX: number; clientY: number }): { x: number; y: number } | null => {
     const canvas = canvasRef.current;
-    if (!canvas) return null;
+    if (!canvas || !canvas.width || !canvas.height) return null;
     const rect = canvas.getBoundingClientRect();
     if (!rect.width || !rect.height) return null;
-    const device = deviceRef.current;
+    // Map into frame pixels (the canvas intrinsic grid), then apply ONE
+    // uniform frame→CSS-pixel scale derived from the widths. The frame can be
+    // SHORTER than the viewport (observed 1280×577 vs a 1280×720 device), so
+    // scaling y by deviceHeight/rect.height stretches clicks downward —
+    // frame pixels map 1:1 onto viewport CSS pixels, top-aligned.
+    const frameToDevice = deviceRef.current.width ? deviceRef.current.width / canvas.width : 1;
     return {
-      x: Math.round((e.clientX - rect.left) * (device.width / rect.width)),
-      y: Math.round((e.clientY - rect.top) * (device.height / rect.height)),
+      x: Math.round((e.clientX - rect.left) * (canvas.width / rect.width) * frameToDevice),
+      y: Math.round((e.clientY - rect.top) * (canvas.height / rect.height) * frameToDevice),
     };
   }, []);
 
@@ -297,7 +315,11 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
 
   const onCanvasMouseDown = (e: React.MouseEvent) => {
     if (!interactiveRef.current) return;
+    // preventDefault stops the browser's focus-shift default action (a click
+    // on a non-focusable canvas would otherwise blur to <body>), and the
+    // explicit focus claims keystrokes for this pane.
     e.preventDefault();
+    elRef.current?.focus({ preventScroll: true });
     const point = toDevice(e);
     if (!point) return;
     buttonsHeldRef.current |= MOUSE_BUTTON_MASKS[e.button] ?? 0;
@@ -376,7 +398,10 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     return () => canvas.removeEventListener('wheel', onWheel);
   }, [send, toDevice]);
 
-  const sendKey = (e: React.KeyboardEvent, eventType: 'keyDown' | 'keyUp') => {
+  const sendKey = useCallback((
+    e: { key: string; code: string; altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean },
+    eventType: 'keyDown' | 'keyUp',
+  ) => {
     const info = SPECIAL_KEYS[e.key];
     send({
       type: 'input_keyboard',
@@ -387,7 +412,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       windowsVirtualKeyCode: info?.keyCode ?? (e.key.length === 1 ? e.key.charCodeAt(0) : 0),
       modifiers: modifiers(e),
     });
-  };
+  }, [send]);
 
   const onKeyDown = (e: React.KeyboardEvent) => {
     if (!interactiveRef.current) return;
@@ -407,6 +432,29 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     if (interactive) elRef.current?.focus({ preventScroll: true });
   }, [interactive]);
 
+  // Fallback: if focus fell through to <body> (dockview focus churn, clicks
+  // racing the passthrough transition), forward keys from the window so the
+  // pane never goes keyboard-dead while interactive. Events targeted inside
+  // the pane are skipped — the React handlers above already cover those. The
+  // Wall's own capture listener registered earlier, so its dual-tap leader
+  // still runs first.
+  useEffect(() => {
+    if (!interactive) return;
+    const forward = (e: KeyboardEvent) => {
+      if (!interactiveRef.current || e.defaultPrevented) return;
+      const el = elRef.current;
+      if (el && e.target instanceof Node && el.contains(e.target)) return;
+      e.preventDefault();
+      sendKey(e, e.type === 'keydown' ? 'keyDown' : 'keyUp');
+    };
+    window.addEventListener('keydown', forward, true);
+    window.addEventListener('keyup', forward, true);
+    return () => {
+      window.removeEventListener('keydown', forward, true);
+      window.removeEventListener('keyup', forward, true);
+    };
+  }, [interactive, sendKey]);
+
   // --- tab strip actions ---
 
   const selectTab = (tab: StreamTab) => {
@@ -437,7 +485,12 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       ref={elRef}
       tabIndex={-1}
       className={`flex h-full w-full flex-col overflow-hidden bg-terminal-bg outline-none ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
-      onMouseDown={() => actions.onClickPanel(api.id)}
+      onMouseDown={() => {
+        actions.onClickPanel(api.id);
+        // Deferred so it lands after dockview's own focus handling for this
+        // mousedown (same trick as enterTerminalMode's focusSession).
+        requestAnimationFrame(() => elRef.current?.focus({ preventScroll: true }));
+      }}
       onKeyDown={onKeyDown}
       onKeyUp={onKeyUp}
     >
@@ -472,7 +525,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       <div className="relative flex min-h-0 flex-1 items-center justify-center">
         <canvas
           ref={canvasRef}
-          className={clsx('max-h-full max-w-full select-none', !hasFrame && 'hidden')}
+          className={clsx('block max-h-full max-w-full select-none', !hasFrame && 'hidden')}
           onMouseDown={onCanvasMouseDown}
           onMouseUp={onCanvasMouseUp}
           onMouseMove={onCanvasMouseMove}
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index b409cf57..4e5a996f 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -83,8 +83,10 @@ export interface PlatformAdapter {
 
   // agent-browser surface support (see docs/specs/dor-agent-browser.md).
   // Runs the user's agent-browser binary against a session; the host validates
-  // args[0] against AGENT_BROWSER_ALLOWED_SUBCOMMANDS.
-  agentBrowserCommand?(session: string, args: string[]): Promise<AgentBrowserCommandResult>;
+  // args[0] against AGENT_BROWSER_ALLOWED_SUBCOMMANDS. `binaryPath` is the
+  // absolute path resolved by `dor ab` in the invoking terminal — the host's
+  // own PATH (e.g. a GUI-launched extension host) may not find the binary.
+  agentBrowserCommand?(session: string, args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult>;
   // The WebSocket URL for a session's stream port. Hosts whose webview origin
   // the agent-browser stream server rejects (VS Code) return a relay URL;
   // absent or null falls back to ws://127.0.0.1:<port>.
diff --git a/lib/src/lib/platform/vscode-adapter.ts b/lib/src/lib/platform/vscode-adapter.ts
index 0e692c96..094fc96f 100644
--- a/lib/src/lib/platform/vscode-adapter.ts
+++ b/lib/src/lib/platform/vscode-adapter.ts
@@ -215,9 +215,9 @@ export class VSCodeAdapter implements PlatformAdapter {
     this.vscode.postMessage({ type: 'dormouse:runWorkbenchCommand', command });
   }
 
-  async agentBrowserCommand(session: string, args: string[]): Promise<AgentBrowserCommandResult> {
+  async agentBrowserCommand(session: string, args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult> {
     const result = await this.requestResponse<AgentBrowserCommandResult>(
-      'agentBrowser:command', 'agentBrowser:commandResult', { session, args },
+      'agentBrowser:command', 'agentBrowser:commandResult', { session, args, binaryPath },
       (msg) => ({ exitCode: msg.exitCode, stdout: msg.stdout, stderr: msg.stderr }),
       10000,
     );
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index ba621a50..e0630cf0 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -27,23 +27,46 @@ export interface AgentBrowserCommandResult {
   stderr: string;
 }
 
-export function runAgentBrowserCommand(session: string, args: string[]): Promise<AgentBrowserCommandResult> {
+export async function runAgentBrowserCommand(session: string, args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult> {
   if (typeof session !== 'string' || !session) {
-    return Promise.resolve({ exitCode: 1, stdout: '', stderr: 'session is required' });
+    return { exitCode: 1, stdout: '', stderr: 'session is required' };
   }
   const subcommand = args[0];
   if (!subcommand || !ALLOWED_SUBCOMMANDS.has(subcommand)) {
-    return Promise.resolve({ exitCode: 1, stdout: '', stderr: `agent-browser subcommand '${subcommand ?? ''}' is not allowed from the webview` });
+    return { exitCode: 1, stdout: '', stderr: `agent-browser subcommand '${subcommand ?? ''}' is not allowed from the webview` };
   }
 
-  const binary = process.env.DORMOUSE_AGENT_BROWSER_BIN || 'agent-browser';
+  // The extension host's PATH is often the GUI login PATH (no nvm/volta
+  // shims), so prefer the absolute path `dor ab` resolved in the user's
+  // terminal; fall through on ENOENT in case it has gone stale.
+  const candidates = [...new Set([
+    binaryPath,
+    process.env.DORMOUSE_AGENT_BROWSER_BIN,
+    'agent-browser',
+  ].filter((c): c is string => !!c))];
+
+  let lastError = '';
+  for (const binary of candidates) {
+    const result = await spawnAgentBrowser(binary, ['--session', session, ...args]);
+    if (result !== 'ENOENT') return result;
+    lastError = `'${binary}' was not found`;
+    log.info(`[agent-browser] ${lastError}; trying next candidate`);
+  }
+  return { exitCode: 1, stdout: '', stderr: `agent-browser binary not found (${lastError})` };
+}
+
+function spawnAgentBrowser(binary: string, args: string[]): Promise<AgentBrowserCommandResult | 'ENOENT'> {
   return new Promise((resolve) => {
-    const child = spawn(binary, ['--session', session, ...args], { stdio: ['ignore', 'pipe', 'pipe'] });
+    const child = spawn(binary, args, { stdio: ['ignore', 'pipe', 'pipe'] });
     let stdout = '';
     let stderr = '';
     child.stdout.on('data', (chunk) => { stdout += String(chunk); });
     child.stderr.on('data', (chunk) => { stderr += String(chunk); });
-    child.on('error', (err) => {
+    child.on('error', (err: NodeJS.ErrnoException) => {
+      if (err.code === 'ENOENT') {
+        resolve('ENOENT');
+        return;
+      }
       log.info(`[agent-browser] spawn failed: ${err.message}`);
       resolve({ exitCode: 1, stdout: '', stderr: err.message });
     });
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 286c1324..0dd494fb 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -353,7 +353,11 @@ export function attachRouter(
         }
         break;
       case 'agentBrowser:command':
-        runAgentBrowserCommand(msg.session, Array.isArray(msg.args) ? msg.args : []).then((result) => {
+        runAgentBrowserCommand(
+          msg.session,
+          Array.isArray(msg.args) ? msg.args : [],
+          typeof msg.binaryPath === 'string' ? msg.binaryPath : undefined,
+        ).then((result) => {
           webview.postMessage({
             type: 'agentBrowser:commandResult', requestId: msg.requestId, ...result,
           } satisfies ExtensionMessage);
diff --git a/vscode-ext/src/message-types.ts b/vscode-ext/src/message-types.ts
index c787c805..e9b684c1 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -18,7 +18,7 @@ export type WebviewMessage =
   | { type: 'clipboard:readImage'; requestId: string }
   | { type: 'dormouse:openExternal'; uri: string }
   | { type: 'dormouse:runWorkbenchCommand'; command: VSCodeWorkbenchCommand }
-  | { type: 'agentBrowser:command'; session: string; args: string[]; requestId: string }
+  | { type: 'agentBrowser:command'; session: string; args: string[]; binaryPath?: string; requestId: string }
   | { type: 'agentBrowser:getStreamUrl'; port: number; requestId: string }
   | { type: 'dormouse:init' }
   | { type: 'dormouse:saveState'; state: unknown }

From 93b0137f73fded2d21ad51c5d963ac26acd986f9 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Fri, 12 Jun 2026 15:46:57 -0700
Subject: [PATCH 09/25] Keyboard passthrough: real VK codes, modifier chords,
 clipboard paste bridge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three daemon protocol discoveries (all verified live against 0.27.0):
- input_keyboard events WITHOUT a text field are silently dropped — which
  was eating arrows, Escape, modifier keys, and every chord. Always send
  text ('' for non-text keys).
- windowsVirtualKeyCode from key.charCodeAt(0) is wrong: '.' is 46 =
  VK_DELETE, so periods acted as Delete (bug inherited from
  agent-browser's own viewer). Proper VK map by physical key code.
- macOS native editing chords (cmd-A/C/X/Z) don't act via CDP
  dispatchKeyEvent without the commands hint, which the stream protocol
  drops — upstream limitation; pages still receive the chords for their
  own JS shortcuts. Verified shift+Home / shift+arrows select correctly.

text is suppressed while ctrl/cmd is held so chords act instead of
inserting characters. cmd/ctrl-V now types the LOCAL clipboard into the
page (per-char keyDown replay) — plain forwarding would paste the
embedded Chromium's empty clipboard — and the Wall's pty-paste handler
yields all clipboard chords on non-terminal surfaces so it stops
swallowing cmd-V before the panel sees it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md               | 76 ++++++++++++++-
 lib/src/components/wall/AgentBrowserPanel.tsx | 96 ++++++++++++++++---
 .../keyboard/handle-mouse-selection-keys.ts   | 13 +++
 lib/src/lib/clipboard.ts                      |  2 +-
 4 files changed, 170 insertions(+), 17 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index c8601d66..bbb311d1 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -132,6 +132,49 @@ Tab behaviors:
   matching typical browser foregrounding; reversible by clicking back. Dormouse
   does not fight the web's popup / open-in-new-tab behavior.
 
+## Screen Modes (Zoom)
+
+Each browser surface has a **screen mode** that controls the agent-browser
+viewport and how the frame fills the pane. It is a thin convenience over
+agent-browser's own `set viewport` / `set device` — it wraps none of
+agent-browser's other `set` options, which stay reachable via `dor ab set …`
+passthrough. Three presets, default **`ONE_TO_ONE`**:
+
+| Mode | Icon | agent-browser viewport | Canvas |
+| --- | --- | --- | --- |
+| `ONE_TO_ONE` | `FrameCornersIcon` | `set viewport <paneW> <paneH>` (DPR 1), re-issued (debounced ~200ms) as the pane resizes | frame ≈ pane → renders pixel-for-pixel; the page reflows responsively to the pane |
+| `DESKTOP` | `DesktopIcon` | `set viewport 1280 720` (DPR 1 — typical non-retina desktop; a tunable constant) | fixed frame scaled to **contain** (letterboxed) |
+| `PHONE` | `DeviceMobileIcon` | `set device "iPhone 14"` (390×844 @ DPR 3, mobile UA + touch) | fixed frame scaled to **contain** |
+
+The panel's existing contain-scaling (`max-h-full max-w-full`) and
+canvas→device coordinate mapping (via frame `metadata`) already handle the
+`DESKTOP`/`PHONE` letterboxing; no input-mapping change is needed. `ONE_TO_ONE`
+is the responsive case — resize the pane and the page reflows, the way a browser
+window would.
+
+- **Indicator & control.** The mode icon sits immediately to the **right of the
+  title** in the surface header. Clicking cycles
+  `ONE_TO_ONE → DESKTOP → PHONE → ONE_TO_ONE`. In command mode, `s` cycles the
+  focused browser surface's mode (gated to agent-browser surfaces, the way `t` /
+  `a` are gated to panes in `handle-pane-shortcuts.ts`).
+- **`CUSTOM` state.** If the live viewport (from frame
+  `metadata.deviceWidth/Height`) does not match the active preset's target —
+  e.g. the user ran `dor ab set viewport …` / `set device …` directly — the
+  indicator shows a distinct `CUSTOM` glyph (e.g. `SlidersHorizontalIcon`) so it
+  reflects reality, not intent (mirroring how the tab strip reflects pushed
+  state). Toggling from `CUSTOM` re-enters the cycle at `ONE_TO_ONE`. This is how
+  "custom resolutions and other agent-browser options" are accommodated without
+  the presets trying to enumerate them.
+- **Default & persistence.** New surfaces start `ONE_TO_ONE`. The chosen mode is
+  per-surface and persists in saved session state (`session-types.ts`,
+  `session-save.ts`); on (re)attach Dormouse re-asserts it by issuing the
+  corresponding `set`.
+- **Mechanism & host capability.** Mode changes issue `set viewport` / `set
+  device` through `agentBrowserCommand`, whose allowlist must be extended from
+  `{tab, close}` to also permit `set`. Like tab actions, the control inherits
+  that host capability: on adapters that do not implement `agentBrowserCommand`
+  (currently Tauri), the resize is inert and the control degrades accordingly.
+
 ## Lifecycle
 
 Surface lifetime and browser lifetime are bound, both directions:
@@ -174,7 +217,26 @@ tab switches need no input re-attachment.)
   modifiers }` — coordinates mapped from canvas space to device space via frame
   `metadata`.
 - Keyboard: `{ type: "input_keyboard", eventType: "keyDown" | "keyUp", key,
-  code, text?, windowsVirtualKeyCode?, modifiers }`.
+  code, text, windowsVirtualKeyCode, modifiers }`.
+
+Keyboard caveats (all verified against 0.27.0):
+
+- **`text` must always be present.** The daemon silently drops any
+  `input_keyboard` whose `text` field is absent — arrows, Escape, modifier
+  keys, every chord. `text: ""` dispatches a proper non-text key event;
+  printable keyDowns carry the character. `text` is suppressed (sent as `""`)
+  while ctrl/cmd is held so chords act as chords rather than inserting text.
+- **`windowsVirtualKeyCode` needs a real VK map**, never
+  `key.charCodeAt(0)` — `.` is char 46 = VK_DELETE, so periods turn into
+  Delete presses (agent-browser's own bundled viewer has this bug).
+- **Paste is bridged.** cmd/ctrl-V types the *local* clipboard into the page
+  as per-character keyDown events; plain forwarding would paste the embedded
+  Chromium's own (empty) clipboard.
+- **macOS native editing chords (cmd-A/C/X/Z) do not act** inside the embedded
+  Chromium: CDP `Input.dispatchKeyEvent` needs the `commands` hint for
+  OS-level editing commands on macOS, and the stream protocol does not forward
+  it (upstream limitation). Pages still *receive* the chord keydowns, so web
+  apps' own JS shortcuts (e.g. cmd-K) work.
 
 Focus behaves like a terminal surface: click-to-focus; keystrokes forward to the
 browser only while the surface is selected and in interact mode. Because Dormouse
@@ -195,7 +257,10 @@ host on the webview's behalf (a webview cannot spawn processes; see
 | --- | --- |
 | `dor ab` command (passthrough + `--key` intercept) | `dor/src/commands/agent-browser.ts` (new) |
 | Control method `surface.agentBrowser` request/response | `dor/src/commands/types.ts`, `dor/src/control-client.ts` (mirror `surface.iframe`, types.ts:109, control-client.ts:71) |
-| Surface component (canvas viewer + WS client + tab strip) | `lib/src/components/wall/AgentBrowserPanel.tsx` (currently a stub) |
+| Surface component (canvas viewer + WS client + tab strip + screen-mode state / `set` issuance / pane-resize tracking) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
+| Screen-mode indicator/control, right of the title (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
+| Command-mode `s` (cycle screen mode, gated to agent-browser surfaces) | `lib/src/components/wall/keyboard/handle-pane-shortcuts.ts` |
+| Per-surface screen-mode persistence | `lib/src/lib/session-types.ts`, `lib/src/lib/session-save.ts` |
 | Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
 | Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
 | Host CLI runner (`agentBrowserCommand`) + VS Code stream relay | `lib/src/lib/platform/types.ts` (optional adapter methods), `vscode-ext/src/message-router.ts`, `vscode-ext/src/agent-browser-host.ts` |
@@ -206,9 +271,10 @@ Two narrow host capabilities back the surface, both optional on
 `PlatformAdapter` so hosts degrade gracefully:
 
 - **`agentBrowserCommand(session, args)`** — runs the user's agent-browser
-  binary for tab actions (`tab <n>`, `tab close`, `tab new`) and lifecycle
-  (`close`). The host validates `args[0]` against an allowlist (`tab`,
-  `close`); this is not a general exec channel.
+  binary for tab actions (`tab <n>`, `tab close`, `tab new`), screen-mode
+  resizing (`set viewport`, `set device`), and lifecycle (`close`). The host
+  validates `args[0]` against an allowlist (`tab`, `set`, `close`); this is not
+  a general exec channel.
 - **`getAgentBrowserStreamUrl(port)`** — returns the WebSocket URL the webview
   should use for the session stream (see CSP/origin below).
 
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 0645e803..edcdf24a 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -11,6 +11,7 @@ import type { IDockviewPanelProps } from 'dockview-react';
 import { clsx } from 'clsx';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
 import { getPlatform } from '../../lib/platform';
+import { readTextFromClipboard } from '../../lib/clipboard';
 import {
   FreshlySpawnedContext,
   ModeContext,
@@ -39,8 +40,8 @@ type StreamStatus = {
   screencasting: boolean;
 };
 
-// Mirrors agent-browser's own viewer: `text` is what makes typing land, and
-// the keyCode map covers the editing/navigation keys CDP wants spelled out.
+// `text` is what makes typing land; windowsVirtualKeyCode is what makes
+// non-text keys and modifier chords act. Keyed by KeyboardEvent.key.
 const SPECIAL_KEYS: Record<string, { text?: string; keyCode: number }> = {
   Enter: { text: '\r', keyCode: 13 },
   Tab: { text: '\t', keyCode: 9 },
@@ -51,12 +52,53 @@ const SPECIAL_KEYS: Record<string, { text?: string; keyCode: number }> = {
   ArrowRight: { keyCode: 39 },
   ArrowDown: { keyCode: 40 },
   Delete: { keyCode: 46 },
+  Insert: { keyCode: 45 },
   Home: { keyCode: 36 },
   End: { keyCode: 35 },
   PageUp: { keyCode: 33 },
   PageDown: { keyCode: 34 },
+  Shift: { keyCode: 16 },
+  Control: { keyCode: 17 },
+  Alt: { keyCode: 18 },
+  Meta: { keyCode: 91 },
+  CapsLock: { keyCode: 20 },
+  ContextMenu: { keyCode: 93 },
 };
 
+// Windows virtual-key codes for printable keys, keyed by KeyboardEvent.code
+// (the physical key, so shifted variants share an entry). Letters and digits
+// are handled structurally in virtualKeyCode. Never derive a VK from
+// `key.charCodeAt(0)`: '.' is 46, which is VK_DELETE — the daemon deletes
+// instead of typing a period.
+const OEM_VK_BY_CODE: Record<string, number> = {
+  Space: 32,
+  Semicolon: 186,
+  Equal: 187,
+  Comma: 188,
+  Minus: 189,
+  Period: 190,
+  Slash: 191,
+  Backquote: 192,
+  BracketLeft: 219,
+  Backslash: 220,
+  BracketRight: 221,
+  Quote: 222,
+  NumpadDecimal: 110,
+  NumpadDivide: 111,
+  NumpadMultiply: 106,
+  NumpadSubtract: 109,
+  NumpadAdd: 107,
+};
+
+function virtualKeyCode(key: string, code: string): number {
+  const special = SPECIAL_KEYS[key];
+  if (special) return special.keyCode;
+  if (/^Key[A-Z]$/.test(code)) return code.charCodeAt(3);
+  if (/^(Digit|Numpad)[0-9]$/.test(code)) return code.charCodeAt(code.length - 1) + (code.startsWith('Numpad') ? 48 : 0);
+  if (/^F([1-9]|1[0-2])$/.test(code)) return 111 + Number(code.slice(1));
+  return OEM_VK_BY_CODE[code] ?? 0;
+}
+
 const MOUSE_BUTTONS: Record<number, string> = { 0: 'left', 1: 'middle', 2: 'right' };
 const MOUSE_BUTTON_MASKS: Record<number, number> = { 0: 1, 1: 4, 2: 2 };
 
@@ -398,26 +440,57 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     return () => canvas.removeEventListener('wheel', onWheel);
   }, [send, toDevice]);
 
-  const sendKey = useCallback((
-    e: { key: string; code: string; altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean },
-    eventType: 'keyDown' | 'keyUp',
-  ) => {
+  type KeyLike = { key: string; code: string; altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean };
+
+  const sendKey = useCallback((e: KeyLike, eventType: 'keyDown' | 'keyUp') => {
     const info = SPECIAL_KEYS[e.key];
+    // Under ctrl/cmd the key is a shortcut, not text — sending text would make
+    // e.g. cmd-A insert an "a" instead of acting as a chord.
+    const wantsText = eventType === 'keyDown' && !e.ctrlKey && !e.metaKey;
     send({
       type: 'input_keyboard',
       eventType,
       key: e.key,
       code: e.code,
-      text: eventType === 'keyDown' ? info?.text ?? (e.key.length === 1 ? e.key : undefined) : undefined,
-      windowsVirtualKeyCode: info?.keyCode ?? (e.key.length === 1 ? e.key.charCodeAt(0) : 0),
+      // The daemon (verified 0.27.0) silently DROPS any event whose text field
+      // is absent — arrows, Escape, modifier keys, chords. An empty string
+      // dispatches a proper non-text key event, so always send a string.
+      text: wantsText ? info?.text ?? (e.key.length === 1 ? e.key : '') : '',
+      windowsVirtualKeyCode: virtualKeyCode(e.key, e.code),
       modifiers: modifiers(e),
     });
   }, [send]);
 
+  // cmd/ctrl-V types the LOCAL clipboard into the page. Plain key forwarding
+  // would trigger paste of the embedded Chromium's own (empty) clipboard, so
+  // bridge by replaying the text as per-character keyDown events.
+  const insertText = useCallback((text: string) => {
+    for (const ch of text) {
+      if (ch === '\r') continue;
+      if (ch === '\n') {
+        send({ type: 'input_keyboard', eventType: 'keyDown', key: 'Enter', code: 'Enter', text: '\r', windowsVirtualKeyCode: 13, modifiers: 0 });
+        send({ type: 'input_keyboard', eventType: 'keyUp', key: 'Enter', code: 'Enter', text: '', windowsVirtualKeyCode: 13, modifiers: 0 });
+      } else {
+        send({ type: 'input_keyboard', eventType: 'keyDown', key: ch, code: '', text: ch, windowsVirtualKeyCode: 0, modifiers: 0 });
+        send({ type: 'input_keyboard', eventType: 'keyUp', key: ch, code: '', text: '', windowsVirtualKeyCode: 0, modifiers: 0 });
+      }
+    }
+  }, [send]);
+
+  const handleKeyDownLike = useCallback((e: KeyLike) => {
+    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'v') {
+      void readTextFromClipboard().then((text) => {
+        if (text) insertText(text);
+      });
+      return;
+    }
+    sendKey(e, 'keyDown');
+  }, [insertText, sendKey]);
+
   const onKeyDown = (e: React.KeyboardEvent) => {
     if (!interactiveRef.current) return;
     e.preventDefault();
-    sendKey(e, 'keyDown');
+    handleKeyDownLike(e);
   };
 
   const onKeyUp = (e: React.KeyboardEvent) => {
@@ -445,7 +518,8 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       const el = elRef.current;
       if (el && e.target instanceof Node && el.contains(e.target)) return;
       e.preventDefault();
-      sendKey(e, e.type === 'keydown' ? 'keyDown' : 'keyUp');
+      if (e.type === 'keydown') handleKeyDownLike(e);
+      else sendKey(e, 'keyUp');
     };
     window.addEventListener('keydown', forward, true);
     window.addEventListener('keyup', forward, true);
@@ -453,7 +527,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       window.removeEventListener('keydown', forward, true);
       window.removeEventListener('keyup', forward, true);
     };
-  }, [interactive, sendKey]);
+  }, [interactive, handleKeyDownLike, sendKey]);
 
   // --- tab strip actions ---
 
diff --git a/lib/src/components/wall/keyboard/handle-mouse-selection-keys.ts b/lib/src/components/wall/keyboard/handle-mouse-selection-keys.ts
index 0d49a612..f892794e 100644
--- a/lib/src/components/wall/keyboard/handle-mouse-selection-keys.ts
+++ b/lib/src/components/wall/keyboard/handle-mouse-selection-keys.ts
@@ -30,6 +30,11 @@ export function handleMouseSelectionKeys(e: KeyboardEvent, ctx: WallKeyboardCtx)
   const sid = ctx.selectedIdRef.current;
   if (!sid) return false;
 
+  // These chords copy/paste against a terminal's pty and mouse selection.
+  // Non-terminal surfaces (agent-browser, iframe) own their clipboard keys —
+  // e.g. AgentBrowserPanel forwards cmd-V to the embedded page — so yield.
+  if (surfaceTypeForId(ctx, sid) !== 'terminal') return false;
+
   const mouseState = getMouseSelectionState(sid);
   const sel = mouseState.selection;
 
@@ -78,3 +83,11 @@ export function handleMouseSelectionKeys(e: KeyboardEvent, ctx: WallKeyboardCtx)
   }
   return false;
 }
+
+function surfaceTypeForId(ctx: WallKeyboardCtx, id: string): string {
+  const panelParams = ctx.apiRef?.current?.getPanel(id)?.params as { surfaceType?: unknown } | undefined;
+  if (typeof panelParams?.surfaceType === 'string') return panelParams.surfaceType;
+  const door = ctx.doorsRef?.current?.find((candidate) => candidate.id === id);
+  const doorType = (door?.params as { surfaceType?: unknown } | undefined)?.surfaceType;
+  return typeof doorType === 'string' ? doorType : 'terminal';
+}
diff --git a/lib/src/lib/clipboard.ts b/lib/src/lib/clipboard.ts
index 3d0027aa..a92751df 100644
--- a/lib/src/lib/clipboard.ts
+++ b/lib/src/lib/clipboard.ts
@@ -62,7 +62,7 @@ export function pasteFilePaths(terminalId: string, paths: string[]): void {
   writePasteToPty(terminalId, text);
 }
 
-async function readTextFromClipboard(): Promise<string> {
+export async function readTextFromClipboard(): Promise<string> {
   // Prefer the platform's native text read when available — navigator.clipboard.readText()
   // on macOS WKWebView pops a "Paste from <App>" confirmation menu at the cursor every
   // time it's invoked from JS, which defeats the point of a paste shortcut.

From e9263b4739c80316c83827744a0eb5a35dc7741c Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 15 Jun 2026 15:56:39 -0700
Subject: [PATCH 10/25] Draft upstream issue: stream input_keyboard drops CDP
 commands field

macOS native editing chords (Cmd+C/X/A/Z) are no-ops over the stream
because input_keyboard has no field mapping to CDP
Input.dispatchKeyEvent.commands. Includes a verified standalone repro
against agent-browser 0.27.0. To be filed at vercel-labs/agent-browser.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 ISSUE.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)
 create mode 100644 ISSUE.md

diff --git a/ISSUE.md b/ISSUE.md
new file mode 100644
index 00000000..7b3a5ce1
--- /dev/null
+++ b/ISSUE.md
@@ -0,0 +1,90 @@
+## Summary
+
+The streaming WebSocket's `input_keyboard` message can deliver text, navigation keys, and modifier-bit chords, but it has **no way to trigger macOS native editing commands** (select-all, copy, cut, paste, undo, redo). On macOS, Chromium implements these via the responder chain, not via raw modifier+key events, so CDP exposes them through the `commands` array on `Input.dispatchKeyEvent` (e.g. `commands: ["selectAll"]`). The stream protocol's `input_keyboard` message exposes no equivalent field, and passing `commands` inline is dropped by the daemon. As a result, a human pair-browsing in the viewport (or any stream client) cannot Cmd+A / Cmd+C / Cmd+X / Cmd+Z inside the remote page on macOS.
+
+Note this is distinct from web-app JS shortcuts: pages still *receive* the chord keydowns (so a page's own `cmd+k` handler fires). What's missing is OS-level **editing** behavior in native inputs/textareas.
+
+## Environment
+
+- agent-browser **0.27.0**
+- macOS, Chrome for Testing (default `chrome` engine)
+- Connecting directly to the session stream WS (`stream status --json` → `ws://127.0.0.1:<port>`)
+
+## Reproduction
+
+Standalone, no dashboard required:
+
+```js
+// cmdkey-repro.mjs  —  node cmdkey-repro.mjs   (agent-browser on PATH, macOS)
+import { execFileSync } from 'node:child_process';
+const SESSION = 'cmdkey-repro';
+const ab = (...a) => execFileSync('agent-browser', ['--session', SESSION, ...a], { encoding: 'utf8' });
+const setField = (v, c) => ab('eval', `(()=>{const f=document.getElementById('f');f.value=${JSON.stringify(v)};f.focus();f.setSelectionRange(${c},${c});})()`);
+const val = () => JSON.parse(ab('eval', `document.getElementById('f').value`).trim());
+
+ab('open', 'data:text/html,' + encodeURIComponent('<input id=f autofocus value="hello world">'));
+const port = JSON.parse(ab('stream', 'status', '--json')).data.port;
+const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+await new Promise((res, rej) => { ws.onopen = res; ws.onerror = () => rej(new Error('ws failed')); });
+ws.onmessage = () => {};
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+const send = (o) => ws.send(JSON.stringify({ type: 'input_keyboard', text: '', ...o }));
+
+// 1. Cmd+A as a modifier chord (modifiers bit 4 = Meta), then type X.
+//    If select-all fired, the field becomes "X".
+setField('hello world', 11);
+send({ eventType: 'keyDown', key: 'Meta', code: 'MetaLeft', windowsVirtualKeyCode: 91, modifiers: 4 });
+send({ eventType: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
+send({ eventType: 'keyUp',   key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
+send({ eventType: 'keyUp',   key: 'Meta', code: 'MetaLeft', windowsVirtualKeyCode: 91, modifiers: 0 });
+send({ eventType: 'keyDown', key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88, text: 'X' });
+send({ eventType: 'keyUp',   key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88 });
+await sleep(400);
+console.log('1. Cmd+A chord then X          ->', JSON.stringify(val()), '  (want "X")');
+
+// 2. Same, but with the CDP `commands` hint passed inline.
+setField('hello world', 11);
+send({ eventType: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4, commands: ['selectAll'] });
+send({ eventType: 'keyUp',   key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
+send({ eventType: 'keyDown', key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88, text: 'X' });
+send({ eventType: 'keyUp',   key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88 });
+await sleep(400);
+console.log('2. commands:["selectAll"]      ->', JSON.stringify(val()), '  (want "X")');
+
+// 3. Control case: Shift+Home (pure modifier selection, no native command) then Y.
+setField('hello world', 11);
+send({ eventType: 'keyDown', key: 'Shift', code: 'ShiftLeft', windowsVirtualKeyCode: 16, modifiers: 8 });
+send({ eventType: 'keyDown', key: 'Home', code: 'Home', windowsVirtualKeyCode: 36, modifiers: 8 });
+send({ eventType: 'keyUp',   key: 'Home', code: 'Home', windowsVirtualKeyCode: 36, modifiers: 8 });
+send({ eventType: 'keyUp',   key: 'Shift', code: 'ShiftLeft', windowsVirtualKeyCode: 16, modifiers: 0 });
+send({ eventType: 'keyDown', key: 'Y', code: 'KeyY', windowsVirtualKeyCode: 89, text: 'Y' });
+send({ eventType: 'keyUp',   key: 'Y', code: 'KeyY', windowsVirtualKeyCode: 89 });
+await sleep(400);
+console.log('3. Shift+Home then Y (control) ->', JSON.stringify(val()), '  (want "Y")');
+
+ws.close(); ab('close');
+```
+
+## Expected vs. Actual
+
+```
+1. Cmd+A chord then X          -> "hello worldX"   (want "X")   ❌ select-all did not fire
+2. commands:["selectAll"]      -> "hello worldX"   (want "X")   ❌ commands field ignored
+3. Shift+Home then Y (control) -> "Y"              (want "Y")   ✅ modifier selection works
+```
+
+Case 3 confirms the `modifiers` bitfield itself works end-to-end; only the native editing-command path is missing. The same holds for Cmd+C / Cmd+X / Cmd+Z.
+
+## Root cause
+
+CDP `Input.dispatchKeyEvent` accepts an optional `commands` array for macOS editing operations (`selectAll`, `copy`, `cut`, `paste`, `undo`, `redo`, …). On macOS these are how Chromium applies edit chords — a raw `keyDown` with `metaKey` set is not sufficient. The stream `input_keyboard` message has no field that maps to `commands`, and the daemon's deserializer drops the field when sent inline, so it can never reach `Input.dispatchKeyEvent`.
+
+## Suggested fix
+
+1. Add an optional `commands: string[]` field to the `input_keyboard` stream message and forward it to CDP `Input.dispatchKeyEvent.commands`.
+2. In the dashboard viewport's keyboard forwarder, populate it for editing chords on macOS — e.g. map `Meta+a/c/x/v/z/Shift+z` → `["selectAll"]` / `["copy"]` / `["cut"]` / `["paste"]` / `["undo"]` / `["redo"]` — alongside the existing modifier-bit handling.
+
+## Prior art
+
+- #980 / #983 added modifier-chord parsing (and `text` suppression under Ctrl/Meta) to the CLI `press` command, but it sends modifier bits only — it does **not** populate CDP `commands`, so native macOS editing chords are unaffected by that fix.
+- #1380 / #836 are the related "wrong `windowsVirtualKeyCode`" thread for the same `input_keyboard` forwarding path; this report is the separate, still-open editing-command gap.

From 691994ff32c37e1180a972f17314fef7d8edd7d7 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 15 Jun 2026 16:02:21 -0700
Subject: [PATCH 11/25] agent-browser: emulate macOS native editing chords via
 host edit channel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stream input_keyboard path can't trigger native cmd-A/C/X on macOS
(CDP drops the commands field). Add a narrow, purpose-built host
capability agentBrowserEdit(session, op) where op is selectAll|copy|cut:
the webview only picks an op name, the host owns the fixed eval JS and
runs it over the daemon's CDP connection, then writes copy/cut text to
the OS clipboard (vscode.env.clipboard). This is option (b) — no
arbitrary-eval channel exposed to the webview.

- selectAll: el.select() / execCommand('selectAll')
- copy: read selection -> OS clipboard
- cut: copy + splice-delete selection
- undo/redo deliberately left as no-ops (execCommand('undo') is
  unreliable for CDP-typed input); pending the upstream commands fix
- absent on hosts that can't run the binary (standalone) -> chords fall
  through to plain key forwarding so page JS shortcuts still fire

All three host-owned eval scripts verified verbatim against a live
0.27.0 session (selectAll selects, copy/cut return the right text, cut
splices the field, collapsed selection copies nothing). lib 545/545.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md               | 22 +++++--
 lib/src/components/wall/AgentBrowserPanel.tsx | 23 ++++++-
 lib/src/lib/platform/types.ts                 | 19 ++++++
 lib/src/lib/platform/vscode-adapter.ts        | 11 +++-
 vscode-ext/src/agent-browser-host.ts          | 63 +++++++++++++++++--
 vscode-ext/src/message-router.ts              | 13 +++-
 vscode-ext/src/message-types.ts               |  2 +
 7 files changed, 140 insertions(+), 13 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index bbb311d1..582e17d8 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -232,11 +232,23 @@ Keyboard caveats (all verified against 0.27.0):
 - **Paste is bridged.** cmd/ctrl-V types the *local* clipboard into the page
   as per-character keyDown events; plain forwarding would paste the embedded
   Chromium's own (empty) clipboard.
-- **macOS native editing chords (cmd-A/C/X/Z) do not act** inside the embedded
-  Chromium: CDP `Input.dispatchKeyEvent` needs the `commands` hint for
-  OS-level editing commands on macOS, and the stream protocol does not forward
-  it (upstream limitation). Pages still *receive* the chord keydowns, so web
-  apps' own JS shortcuts (e.g. cmd-K) work.
+- **macOS native editing chords (cmd-A/C/X) are emulated via the host edit
+  channel,** not the stream. CDP `Input.dispatchKeyEvent` needs the `commands`
+  hint for OS-level editing on macOS, and the stream protocol drops it (upstream
+  limitation — see the filed issue). So instead of forwarding those chords, the
+  panel routes the *intent* to the host's `agentBrowserEdit(session, op)`
+  capability, which runs a host-owned `eval` over the daemon's CDP connection:
+  - `selectAll` → `el.select()` / `execCommand('selectAll')`.
+  - `copy` → read the selection, write it to the **OS clipboard**
+    (`vscode.env.clipboard`). Copying from the embedded browser lands in your
+    real clipboard, which is the desired UX anyway.
+  - `cut` → copy + delete the selection.
+  The webview only picks one of these three op names; the host owns the JS, so
+  this is a purpose-built channel, not arbitrary eval. **cmd-Z/⇧Z (undo/redo)
+  are not emulated** — `execCommand('undo')` is unreliable for CDP-typed input;
+  they remain no-ops pending the upstream `commands` fix. On hosts without the
+  capability (standalone/Tauri), the chords fall through to plain key
+  forwarding, so pages' own JS shortcuts still fire.
 
 Focus behaves like a terminal surface: click-to-focus; keystrokes forward to the
 browser only while the surface is selected and in interact mode. Because Dormouse
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index edcdf24a..387b4d5e 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -99,6 +99,9 @@ function virtualKeyCode(key: string, code: string): number {
   return OEM_VK_BY_CODE[code] ?? 0;
 }
 
+// Cmd/Ctrl + these map to native editing ops the stream input path can't do.
+const EDIT_OPS = { a: 'selectAll', c: 'copy', x: 'cut' } as const;
+
 const MOUSE_BUTTONS: Record<number, string> = { 0: 'left', 1: 'middle', 2: 'right' };
 const MOUSE_BUTTON_MASKS: Record<number, number> = { 0: 1, 1: 4, 2: 2 };
 
@@ -478,14 +481,30 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
   }, [send]);
 
   const handleKeyDownLike = useCallback((e: KeyLike) => {
-    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'v') {
+    const mod = e.metaKey || e.ctrlKey;
+    if (mod && e.key.toLowerCase() === 'v') {
       void readTextFromClipboard().then((text) => {
         if (text) insertText(text);
       });
       return;
     }
+    // macOS native editing chords (select-all/copy/cut) don't fire over the
+    // stream input path (CDP commands field is dropped). Route the intent
+    // through the host's purpose-built edit channel instead. If the host
+    // lacks it (e.g. standalone), fall through so the page still gets the
+    // chord for its own JS shortcuts.
+    if (mod && !e.altKey && !e.shiftKey) {
+      const op = EDIT_OPS[e.key.toLowerCase() as keyof typeof EDIT_OPS];
+      const edit = getPlatform().agentBrowserEdit;
+      if (op && edit && session) {
+        edit(session, op, binaryPath).then((r) => {
+          if (!r.ok && r.error) console.warn(`[agent-browser] ${op} failed:`, r.error);
+        }).catch((err) => console.warn(`[agent-browser] ${op} failed:`, err));
+        return;
+      }
+    }
     sendKey(e, 'keyDown');
-  }, [insertText, sendKey]);
+  }, [insertText, sendKey, session, binaryPath]);
 
   const onKeyDown = (e: React.KeyboardEvent) => {
     if (!interactiveRef.current) return;
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index 4e5a996f..b67f9a6b 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -44,6 +44,20 @@ export interface AgentBrowserCommandResult {
  * channel for tab actions and session teardown, not a general exec path. */
 export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'close'] as const;
 
+/** Native editing operations that the stream's input_keyboard path cannot
+ * trigger on macOS (CDP drops the `commands` field — see
+ * docs/specs/dor-agent-browser.md and the upstream issue). The host owns the
+ * exact JS for each; the webview only picks one of these names, so this stays
+ * a purpose-built channel rather than an arbitrary-eval one. */
+export type AgentBrowserEditOp = 'selectAll' | 'copy' | 'cut';
+
+export interface AgentBrowserEditResult {
+  ok: boolean;
+  /** Text the host placed on the OS clipboard (copy/cut); omitted for selectAll. */
+  text?: string;
+  error?: string;
+}
+
 export interface PlatformAdapter {
   // Lifecycle
   init(): Promise<void>;
@@ -87,6 +101,11 @@ export interface PlatformAdapter {
   // absolute path resolved by `dor ab` in the invoking terminal — the host's
   // own PATH (e.g. a GUI-launched extension host) may not find the binary.
   agentBrowserCommand?(session: string, args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult>;
+  // Performs a native editing operation (select-all/copy/cut) the stream input
+  // path can't, via the daemon's CDP-backed eval. The host owns the JS and,
+  // for copy/cut, writes the result to the OS clipboard. Absent on hosts that
+  // can't run the binary (degrades to plain key forwarding).
+  agentBrowserEdit?(session: string, op: AgentBrowserEditOp, binaryPath?: string): Promise<AgentBrowserEditResult>;
   // The WebSocket URL for a session's stream port. Hosts whose webview origin
   // the agent-browser stream server rejects (VS Code) return a relay URL;
   // absent or null falls back to ws://127.0.0.1:<port>.
diff --git a/lib/src/lib/platform/vscode-adapter.ts b/lib/src/lib/platform/vscode-adapter.ts
index 094fc96f..ce3a31e4 100644
--- a/lib/src/lib/platform/vscode-adapter.ts
+++ b/lib/src/lib/platform/vscode-adapter.ts
@@ -1,4 +1,4 @@
-import type { AgentBrowserCommandResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
+import type { AgentBrowserCommandResult, AgentBrowserEditOp, AgentBrowserEditResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
 import { OPEN_PORT_TIMEOUT_MS } from './types';
 import { setDefaultShellOpts } from '../shell-defaults';
 import {
@@ -224,6 +224,15 @@ export class VSCodeAdapter implements PlatformAdapter {
     return result ?? { exitCode: 1, stdout: '', stderr: 'agent-browser command timed out' };
   }
 
+  async agentBrowserEdit(session: string, op: AgentBrowserEditOp, binaryPath?: string): Promise<AgentBrowserEditResult> {
+    const result = await this.requestResponse<AgentBrowserEditResult>(
+      'agentBrowser:edit', 'agentBrowser:editResult', { session, op, binaryPath },
+      (msg) => ({ ok: msg.ok, text: msg.text, error: msg.error }),
+      10000,
+    );
+    return result ?? { ok: false, error: 'agent-browser edit timed out' };
+  }
+
   getAgentBrowserStreamUrl(port: number): Promise<string | null> {
     // The agent-browser stream server rejects vscode-webview:// origins, so
     // the extension host relays the stream (see agent-browser-host.ts).
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index e0630cf0..9f0797df 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -15,6 +15,7 @@
  *    connects to ws://127.0.0.1:<relayPort>/stream/<streamPort> instead and
  *    the relay pipes bytes to 127.0.0.1:<streamPort>.
  */
+import * as vscode from 'vscode';
 import * as net from 'net';
 import { spawn } from 'child_process';
 import { log } from './log';
@@ -27,6 +28,24 @@ export interface AgentBrowserCommandResult {
   stderr: string;
 }
 
+export type AgentBrowserEditOp = 'selectAll' | 'copy' | 'cut';
+
+export interface AgentBrowserEditResult {
+  ok: boolean;
+  text?: string;
+  error?: string;
+}
+
+// The host owns the exact JS for each editing op — the webview only selects a
+// name, so this never becomes an arbitrary-eval channel. copy/cut return the
+// selected text; selectAll returns ''. Inputs/textareas use selection ranges;
+// everything else falls back to the Selection API + execCommand.
+const EDIT_SCRIPTS: Record<AgentBrowserEditOp, string> = {
+  selectAll: `(()=>{const el=document.activeElement;if(el&&'select'in el&&'value'in el){el.select();}else{document.execCommand('selectAll');}return'';})()`,
+  copy: `(()=>{const el=document.activeElement;if(el&&'selectionStart'in el&&el.selectionStart!=null){return el.value.slice(el.selectionStart,el.selectionEnd);}return String(window.getSelection()||'');})()`,
+  cut: `(()=>{const el=document.activeElement;if(el&&'selectionStart'in el&&el.selectionStart!=null){const s=el.selectionStart,e=el.selectionEnd,t=el.value.slice(s,e);el.setRangeText('',s,e,'end');el.dispatchEvent(new Event('input',{bubbles:true}));return t;}const sel=String(window.getSelection()||'');if(sel)document.execCommand('delete');return sel;})()`,
+};
+
 export async function runAgentBrowserCommand(session: string, args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult> {
   if (typeof session !== 'string' || !session) {
     return { exitCode: 1, stdout: '', stderr: 'session is required' };
@@ -35,10 +54,46 @@ export async function runAgentBrowserCommand(session: string, args: string[], bi
   if (!subcommand || !ALLOWED_SUBCOMMANDS.has(subcommand)) {
     return { exitCode: 1, stdout: '', stderr: `agent-browser subcommand '${subcommand ?? ''}' is not allowed from the webview` };
   }
+  return runWithBinaryFallback(['--session', session, ...args], binaryPath);
+}
+
+export async function runAgentBrowserEdit(session: string, op: AgentBrowserEditOp, binaryPath?: string): Promise<AgentBrowserEditResult> {
+  if (typeof session !== 'string' || !session) {
+    return { ok: false, error: 'session is required' };
+  }
+  const script = EDIT_SCRIPTS[op];
+  if (!script) {
+    return { ok: false, error: `unknown edit op '${op}'` };
+  }
+
+  const result = await runWithBinaryFallback(['--session', session, 'eval', script, '--json'], binaryPath);
+  if (result.exitCode !== 0) {
+    return { ok: false, error: result.stderr.trim() || `eval exited ${result.exitCode}` };
+  }
+
+  // eval --json envelope: { success, data: { result }, error }.
+  let text = '';
+  try {
+    const envelope = JSON.parse(result.stdout) as { success?: boolean; data?: { result?: unknown }; error?: unknown };
+    if (envelope.success === false) {
+      return { ok: false, error: typeof envelope.error === 'string' ? envelope.error : `${op} failed` };
+    }
+    if (typeof envelope.data?.result === 'string') text = envelope.data.result;
+  } catch {
+    return { ok: false, error: `could not parse eval output for ${op}` };
+  }
+
+  if (op === 'selectAll') return { ok: true };
+  // Land the grabbed text on the user's real OS clipboard. Skip empty so an
+  // empty selection doesn't clobber what's already there.
+  if (text) await vscode.env.clipboard.writeText(text);
+  return { ok: true, text };
+}
 
-  // The extension host's PATH is often the GUI login PATH (no nvm/volta
-  // shims), so prefer the absolute path `dor ab` resolved in the user's
-  // terminal; fall through on ENOENT in case it has gone stale.
+// The extension host's PATH is often the GUI login PATH (no nvm/volta shims),
+// so prefer the absolute path `dor ab` resolved in the user's terminal; fall
+// through on ENOENT in case it has gone stale.
+async function runWithBinaryFallback(args: string[], binaryPath?: string): Promise<AgentBrowserCommandResult> {
   const candidates = [...new Set([
     binaryPath,
     process.env.DORMOUSE_AGENT_BROWSER_BIN,
@@ -47,7 +102,7 @@ export async function runAgentBrowserCommand(session: string, args: string[], bi
 
   let lastError = '';
   for (const binary of candidates) {
-    const result = await spawnAgentBrowser(binary, ['--session', session, ...args]);
+    const result = await spawnAgentBrowser(binary, args);
     if (result !== 'ENOENT') return result;
     lastError = `'${binary}' was not found`;
     log.info(`[agent-browser] ${lastError}; trying next candidate`);
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 0dd494fb..bcdc5635 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -13,7 +13,7 @@ import type { TerminalSemanticEvent } from '../../lib/src/lib/terminal-state';
 import type { PersistedSession } from '../../lib/src/lib/session-types';
 import type { WebviewMessage, ExtensionMessage } from './message-types';
 import type { DorControlRequest } from './pty-manager';
-import { ensureStreamRelayPort, runAgentBrowserCommand } from './agent-browser-host';
+import { ensureStreamRelayPort, runAgentBrowserCommand, runAgentBrowserEdit } from './agent-browser-host';
 import { log } from './log';
 
 const clipboardOps = require('../../lib/clipboard-ops.cjs') as {
@@ -363,6 +363,17 @@ export function attachRouter(
           } satisfies ExtensionMessage);
         });
         break;
+      case 'agentBrowser:edit':
+        runAgentBrowserEdit(
+          msg.session,
+          msg.op,
+          typeof msg.binaryPath === 'string' ? msg.binaryPath : undefined,
+        ).then((result) => {
+          webview.postMessage({
+            type: 'agentBrowser:editResult', requestId: msg.requestId, ...result,
+          } satisfies ExtensionMessage);
+        });
+        break;
       case 'agentBrowser:getStreamUrl': {
         const streamPort = Number.isInteger(msg.port) && msg.port > 0 && msg.port <= 65535 ? msg.port : null;
         if (!streamPort) {
diff --git a/vscode-ext/src/message-types.ts b/vscode-ext/src/message-types.ts
index e9b684c1..ac59c640 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -19,6 +19,7 @@ export type WebviewMessage =
   | { type: 'dormouse:openExternal'; uri: string }
   | { type: 'dormouse:runWorkbenchCommand'; command: VSCodeWorkbenchCommand }
   | { type: 'agentBrowser:command'; session: string; args: string[]; binaryPath?: string; requestId: string }
+  | { type: 'agentBrowser:edit'; session: string; op: 'selectAll' | 'copy' | 'cut'; binaryPath?: string; requestId: string }
   | { type: 'agentBrowser:getStreamUrl'; port: number; requestId: string }
   | { type: 'dormouse:init' }
   | { type: 'dormouse:saveState'; state: unknown }
@@ -57,6 +58,7 @@ export type ExtensionMessage =
   | { type: 'clipboard:files'; paths: string[] | null; requestId: string }
   | { type: 'clipboard:image'; path: string | null; requestId: string }
   | { type: 'agentBrowser:commandResult'; requestId: string; exitCode: number; stdout: string; stderr: string }
+  | { type: 'agentBrowser:editResult'; requestId: string; ok: boolean; text?: string; error?: string }
   | { type: 'agentBrowser:streamUrl'; requestId: string; url: string | null }
   | {
       type: 'dormouse:newTerminal';

From 95299aaafbbfda926a4776ce154498120670f664 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 15 Jun 2026 19:32:14 -0700
Subject: [PATCH 12/25] Spec: rework viewport section to SYNCED/SCALED
 indicator + edit-channel keyboard caveats

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md | 159 +++++++++++++++++++++++---------
 1 file changed, 113 insertions(+), 46 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 582e17d8..e3076305 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -132,48 +132,115 @@ Tab behaviors:
   matching typical browser foregrounding; reversible by clicking back. Dormouse
   does not fight the web's popup / open-in-new-tab behavior.
 
-## Screen Modes (Zoom)
-
-Each browser surface has a **screen mode** that controls the agent-browser
-viewport and how the frame fills the pane. It is a thin convenience over
-agent-browser's own `set viewport` / `set device` — it wraps none of
-agent-browser's other `set` options, which stay reachable via `dor ab set …`
-passthrough. Three presets, default **`ONE_TO_ONE`**:
-
-| Mode | Icon | agent-browser viewport | Canvas |
-| --- | --- | --- | --- |
-| `ONE_TO_ONE` | `FrameCornersIcon` | `set viewport <paneW> <paneH>` (DPR 1), re-issued (debounced ~200ms) as the pane resizes | frame ≈ pane → renders pixel-for-pixel; the page reflows responsively to the pane |
-| `DESKTOP` | `DesktopIcon` | `set viewport 1280 720` (DPR 1 — typical non-retina desktop; a tunable constant) | fixed frame scaled to **contain** (letterboxed) |
-| `PHONE` | `DeviceMobileIcon` | `set device "iPhone 14"` (390×844 @ DPR 3, mobile UA + touch) | fixed frame scaled to **contain** |
-
-The panel's existing contain-scaling (`max-h-full max-w-full`) and
-canvas→device coordinate mapping (via frame `metadata`) already handle the
-`DESKTOP`/`PHONE` letterboxing; no input-mapping change is needed. `ONE_TO_ONE`
-is the responsive case — resize the pane and the page reflows, the way a browser
-window would.
-
-- **Indicator & control.** The mode icon sits immediately to the **right of the
-  title** in the surface header. Clicking cycles
-  `ONE_TO_ONE → DESKTOP → PHONE → ONE_TO_ONE`. In command mode, `s` cycles the
-  focused browser surface's mode (gated to agent-browser surfaces, the way `t` /
-  `a` are gated to panes in `handle-pane-shortcuts.ts`).
-- **`CUSTOM` state.** If the live viewport (from frame
-  `metadata.deviceWidth/Height`) does not match the active preset's target —
-  e.g. the user ran `dor ab set viewport …` / `set device …` directly — the
-  indicator shows a distinct `CUSTOM` glyph (e.g. `SlidersHorizontalIcon`) so it
-  reflects reality, not intent (mirroring how the tab strip reflects pushed
-  state). Toggling from `CUSTOM` re-enters the cycle at `ONE_TO_ONE`. This is how
-  "custom resolutions and other agent-browser options" are accommodated without
-  the presets trying to enumerate them.
-- **Default & persistence.** New surfaces start `ONE_TO_ONE`. The chosen mode is
-  per-surface and persists in saved session state (`session-types.ts`,
-  `session-save.ts`); on (re)attach Dormouse re-asserts it by issuing the
-  corresponding `set`.
-- **Mechanism & host capability.** Mode changes issue `set viewport` / `set
-  device` through `agentBrowserCommand`, whose allowlist must be extended from
-  `{tab, close}` to also permit `set`. Like tab actions, the control inherits
-  that host capability: on adapters that do not implement `agentBrowserCommand`
-  (currently Tauri), the resize is inert and the control degrades accordingly.
+## Screen Indicator & Viewport
+
+The surface viewport is governed by agent-browser's own `set viewport` / `set
+device`. Dormouse does not invent a parallel "mode" enum; instead the header
+carries a **two-state indicator that reflects reality**, and a modal that is
+nothing more than a GUI front-end for those native `set` commands.
+
+### The indicator (SYNCED / SCALED)
+
+Immediately to the **right of the title**, the header shows one of two derived
+states — never a stored mode:
+
+- **`SYNCED`** — the browser's live viewport **and** DPI exactly equal the pane's
+  pixel size, so frames map 1:1 with no scaling.
+- **`SCALED`** — anything else; the frame is letterboxed/zoomed to fit the pane.
+
+Both are computed from the stream: viewport from frame
+`metadata.deviceWidth/Height`, DPI inferred as `frameBitmap.width /
+metadata.deviceWidth`. Because it is derived, the indicator is correct no matter
+*how* the viewport was set — modal, `dor ab set …`, or a raw `agent-browser`
+call. The panel's existing contain-scaling (`max-h-full max-w-full`) and
+coordinate mapping already produce the `SCALED` letterboxing; `SYNCED` is simply
+the case where the frame equals the pane. There is **no keyboard shortcut**.
+
+### The modal
+
+Clicking the indicator opens a modal — three mutually exclusive targets:
+
+```
+╭─ Screen — surface:3 ────────────────────────────────────────╮
+│                                                              │
+│   Currently  SCALED                                          │
+│   browser 393×852 @3x   ·   pane 980×560 @2x   (zoomed)       │
+│                                                              │
+│   ( ) Sync to pane                                           │
+│       viewport follows the pane, pixel-for-pixel             │
+│       → now: 980×560 @2x                                      │
+│                                                              │
+│   (•) Device           all devices emulate touch + mobile UA │
+│       ┌──────────────────┐  ┌──────────────────┐            │
+│       │ • iPhone 16      │  │   iPhone 16 Pro  │             │
+│       │   iPhone 17      │  │   iPhone 15      │             │
+│       │   Pixel 9        │  │   Galaxy S25     │             │
+│       │   iPad           │  │   iPad Pro       │             │
+│       └──────────────────┘  └──────────────────┘            │
+│       iPhone 16 · 393×852 @3x                                │
+│                                                              │
+│   ( ) Custom     W [ 1280 ]   H [ 720 ]    DPI [ 1 ]         │
+│                                                              │
+│                                   [ Cancel ]   [ Apply ]     │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+Each target maps to a native command — the modal issues exactly what a user
+could type:
+
+| Target | Native command issued |
+| --- | --- |
+| **Sync to pane** | `set viewport <paneCssW> <paneCssH> <displayDpr>`, re-issued (debounced ~200ms) on pane resize |
+| **Device** | `set device <name>` — the fixed registry only (`iPhone 15`, `iPhone 16`, `iPhone 16 Pro`, `iPhone 17`, `iPad`, `iPad Pro`, `Pixel 9`, `Galaxy S25`); bundles viewport + DPR + touch + mobile UA |
+| **Custom** | `set viewport <w> <h> <dpi>` |
+
+The device registry is fixed (no custom descriptors), and touch / mobile-UA are
+**only** available bundled inside `set device` — there is no standalone touch
+setting (verified against 0.27.0). So Sync/Custom are never touch; only Device
+is. The modal **reads the live viewport on open** and pre-selects accordingly:
+*Sync* if sync is engaged and matching, else the registry device whose
+dimensions match, else *Custom* pre-filled with the current dims. Like the
+indicator, the modal reflects reality rather than a stored intent.
+
+### Transparency with `dor ab set …`
+
+There is nothing extra to "expose" — **the modal *is* a GUI for native
+`agent-browser set`.** Device/Custom issue the same `set device` / `set
+viewport` a user runs as `dor ab set …`. Two issue paths converge on one
+session — the terminal's `dor ab` execs agent-browser directly; the webview
+modal goes through the host's `agentBrowserCommand` — and the daemon serializes
+them. Whichever wrote last, the `SYNCED`/`SCALED` indicator and the modal's
+pre-fill reflect it.
+
+**Sync is the one non-native concept.** agent-browser has no "follow the pane"
+mode; *Sync to pane* is a Dormouse behavior that auto-issues native `set
+viewport <pane>` and re-issues on resize. Coexistence is **last-writer-wins**:
+Dormouse tracks the viewport it last issued (`lastIssued`); when a frame reports
+a viewport matching neither `lastIssued` nor the current pane, an external setter
+(`dor ab set …`) intervened, so Dormouse **disengages sync** and the indicator
+falls to `SCALED`. (Evaluate this only when the pane size is stable and Dormouse
+has already issued for it, so a resize transient — a frame at the old size before
+the re-issue lands — is not mistaken for an external override.)
+
+> **Known limitation: there is currently no way to re-trigger sync from the
+> CLI.** Because sync is not an agent-browser concept, `dor ab` has no verb for
+> it; once an external `set` disengages sync, re-enabling it means reopening the
+> modal and choosing *Sync to pane*. (A Dormouse-reserved `dor ab` verb could add
+> this later, at the cost of the first non-passthrough subcommand.)
+
+### Mechanism, persistence, host capability
+
+- Modal and sync issue `set viewport` / `set device` through
+  `agentBrowserCommand`, whose allowlist includes `set` (alongside `tab`,
+  `close`).
+- The only Dormouse-side state worth persisting is **whether sync is engaged**;
+  device/custom viewports live in the agent-browser session itself and survive
+  reattach. On reattach Dormouse re-engages sync if it was engaged
+  (`session-types.ts`, `session-save.ts`).
+- Like tab actions, this inherits the `agentBrowserCommand` host capability: on
+  adapters that do not implement it (currently Tauri), modal-driven resizes are
+  inert and the control degrades accordingly. (`dor ab set …` from a terminal
+  still works there, since it execs agent-browser directly.)
 
 ## Lifecycle
 
@@ -269,10 +336,10 @@ host on the webview's behalf (a webview cannot spawn processes; see
 | --- | --- |
 | `dor ab` command (passthrough + `--key` intercept) | `dor/src/commands/agent-browser.ts` (new) |
 | Control method `surface.agentBrowser` request/response | `dor/src/commands/types.ts`, `dor/src/control-client.ts` (mirror `surface.iframe`, types.ts:109, control-client.ts:71) |
-| Surface component (canvas viewer + WS client + tab strip + screen-mode state / `set` issuance / pane-resize tracking) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
-| Screen-mode indicator/control, right of the title (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
-| Command-mode `s` (cycle screen mode, gated to agent-browser surfaces) | `lib/src/components/wall/keyboard/handle-pane-shortcuts.ts` |
-| Per-surface screen-mode persistence | `lib/src/lib/session-types.ts`, `lib/src/lib/session-save.ts` |
+| Surface component (canvas viewer + WS client + tab strip + sync tracking / `set` issuance / SYNCED-SCALED derivation) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
+| SYNCED/SCALED indicator right of the title; opens the screen modal (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
+| Screen modal (Sync / Device-registry / Custom; issues native `set …`) | `lib/src/components/wall/AgentBrowserScreenModal.tsx` (new) |
+| Per-surface "sync engaged" persistence | `lib/src/lib/session-types.ts`, `lib/src/lib/session-save.ts` |
 | Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
 | Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
 | Host CLI runner (`agentBrowserCommand`) + VS Code stream relay | `lib/src/lib/platform/types.ts` (optional adapter methods), `vscode-ext/src/message-router.ts`, `vscode-ext/src/agent-browser-host.ts` |

From 76828f4030ca65d1e6372fd17d0fbfdd28c79810 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 15 Jun 2026 19:52:05 -0700
Subject: [PATCH 13/25] Didn't mean to commit this.

---
 ISSUE.md | 90 --------------------------------------------------------
 1 file changed, 90 deletions(-)
 delete mode 100644 ISSUE.md

diff --git a/ISSUE.md b/ISSUE.md
deleted file mode 100644
index 7b3a5ce1..00000000
--- a/ISSUE.md
+++ /dev/null
@@ -1,90 +0,0 @@
-## Summary
-
-The streaming WebSocket's `input_keyboard` message can deliver text, navigation keys, and modifier-bit chords, but it has **no way to trigger macOS native editing commands** (select-all, copy, cut, paste, undo, redo). On macOS, Chromium implements these via the responder chain, not via raw modifier+key events, so CDP exposes them through the `commands` array on `Input.dispatchKeyEvent` (e.g. `commands: ["selectAll"]`). The stream protocol's `input_keyboard` message exposes no equivalent field, and passing `commands` inline is dropped by the daemon. As a result, a human pair-browsing in the viewport (or any stream client) cannot Cmd+A / Cmd+C / Cmd+X / Cmd+Z inside the remote page on macOS.
-
-Note this is distinct from web-app JS shortcuts: pages still *receive* the chord keydowns (so a page's own `cmd+k` handler fires). What's missing is OS-level **editing** behavior in native inputs/textareas.
-
-## Environment
-
-- agent-browser **0.27.0**
-- macOS, Chrome for Testing (default `chrome` engine)
-- Connecting directly to the session stream WS (`stream status --json` → `ws://127.0.0.1:<port>`)
-
-## Reproduction
-
-Standalone, no dashboard required:
-
-```js
-// cmdkey-repro.mjs  —  node cmdkey-repro.mjs   (agent-browser on PATH, macOS)
-import { execFileSync } from 'node:child_process';
-const SESSION = 'cmdkey-repro';
-const ab = (...a) => execFileSync('agent-browser', ['--session', SESSION, ...a], { encoding: 'utf8' });
-const setField = (v, c) => ab('eval', `(()=>{const f=document.getElementById('f');f.value=${JSON.stringify(v)};f.focus();f.setSelectionRange(${c},${c});})()`);
-const val = () => JSON.parse(ab('eval', `document.getElementById('f').value`).trim());
-
-ab('open', 'data:text/html,' + encodeURIComponent('<input id=f autofocus value="hello world">'));
-const port = JSON.parse(ab('stream', 'status', '--json')).data.port;
-const ws = new WebSocket(`ws://127.0.0.1:${port}`);
-await new Promise((res, rej) => { ws.onopen = res; ws.onerror = () => rej(new Error('ws failed')); });
-ws.onmessage = () => {};
-const sleep = (ms) => new Promise(r => setTimeout(r, ms));
-const send = (o) => ws.send(JSON.stringify({ type: 'input_keyboard', text: '', ...o }));
-
-// 1. Cmd+A as a modifier chord (modifiers bit 4 = Meta), then type X.
-//    If select-all fired, the field becomes "X".
-setField('hello world', 11);
-send({ eventType: 'keyDown', key: 'Meta', code: 'MetaLeft', windowsVirtualKeyCode: 91, modifiers: 4 });
-send({ eventType: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
-send({ eventType: 'keyUp',   key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
-send({ eventType: 'keyUp',   key: 'Meta', code: 'MetaLeft', windowsVirtualKeyCode: 91, modifiers: 0 });
-send({ eventType: 'keyDown', key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88, text: 'X' });
-send({ eventType: 'keyUp',   key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88 });
-await sleep(400);
-console.log('1. Cmd+A chord then X          ->', JSON.stringify(val()), '  (want "X")');
-
-// 2. Same, but with the CDP `commands` hint passed inline.
-setField('hello world', 11);
-send({ eventType: 'keyDown', key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4, commands: ['selectAll'] });
-send({ eventType: 'keyUp',   key: 'a', code: 'KeyA', windowsVirtualKeyCode: 65, modifiers: 4 });
-send({ eventType: 'keyDown', key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88, text: 'X' });
-send({ eventType: 'keyUp',   key: 'X', code: 'KeyX', windowsVirtualKeyCode: 88 });
-await sleep(400);
-console.log('2. commands:["selectAll"]      ->', JSON.stringify(val()), '  (want "X")');
-
-// 3. Control case: Shift+Home (pure modifier selection, no native command) then Y.
-setField('hello world', 11);
-send({ eventType: 'keyDown', key: 'Shift', code: 'ShiftLeft', windowsVirtualKeyCode: 16, modifiers: 8 });
-send({ eventType: 'keyDown', key: 'Home', code: 'Home', windowsVirtualKeyCode: 36, modifiers: 8 });
-send({ eventType: 'keyUp',   key: 'Home', code: 'Home', windowsVirtualKeyCode: 36, modifiers: 8 });
-send({ eventType: 'keyUp',   key: 'Shift', code: 'ShiftLeft', windowsVirtualKeyCode: 16, modifiers: 0 });
-send({ eventType: 'keyDown', key: 'Y', code: 'KeyY', windowsVirtualKeyCode: 89, text: 'Y' });
-send({ eventType: 'keyUp',   key: 'Y', code: 'KeyY', windowsVirtualKeyCode: 89 });
-await sleep(400);
-console.log('3. Shift+Home then Y (control) ->', JSON.stringify(val()), '  (want "Y")');
-
-ws.close(); ab('close');
-```
-
-## Expected vs. Actual
-
-```
-1. Cmd+A chord then X          -> "hello worldX"   (want "X")   ❌ select-all did not fire
-2. commands:["selectAll"]      -> "hello worldX"   (want "X")   ❌ commands field ignored
-3. Shift+Home then Y (control) -> "Y"              (want "Y")   ✅ modifier selection works
-```
-
-Case 3 confirms the `modifiers` bitfield itself works end-to-end; only the native editing-command path is missing. The same holds for Cmd+C / Cmd+X / Cmd+Z.
-
-## Root cause
-
-CDP `Input.dispatchKeyEvent` accepts an optional `commands` array for macOS editing operations (`selectAll`, `copy`, `cut`, `paste`, `undo`, `redo`, …). On macOS these are how Chromium applies edit chords — a raw `keyDown` with `metaKey` set is not sufficient. The stream `input_keyboard` message has no field that maps to `commands`, and the daemon's deserializer drops the field when sent inline, so it can never reach `Input.dispatchKeyEvent`.
-
-## Suggested fix
-
-1. Add an optional `commands: string[]` field to the `input_keyboard` stream message and forward it to CDP `Input.dispatchKeyEvent.commands`.
-2. In the dashboard viewport's keyboard forwarder, populate it for editing chords on macOS — e.g. map `Meta+a/c/x/v/z/Shift+z` → `["selectAll"]` / `["copy"]` / `["cut"]` / `["paste"]` / `["undo"]` / `["redo"]` — alongside the existing modifier-bit handling.
-
-## Prior art
-
-- #980 / #983 added modifier-chord parsing (and `text` suppression under Ctrl/Meta) to the CLI `press` command, but it sends modifier bits only — it does **not** populate CDP `commands`, so native macOS editing chords are unaffected by that fix.
-- #1380 / #836 are the related "wrong `windowsVirtualKeyCode`" thread for the same `input_keyboard` forwarding path; this report is the separate, still-open editing-command gap.

From 00f75363b925be5f8e68fd554a83c7c2a7a47b3f Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Mon, 15 Jun 2026 22:28:51 -0700
Subject: [PATCH 14/25] =?UTF-8?q?agent-browser:=20Phase=208=20=E2=80=94=20?=
 =?UTF-8?q?SYNCED/SCALED=20screen=20indicator=20+=20viewport=20modal?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds the header screen indicator and its viewport modal, a GUI front-end for
native `agent-browser set viewport` / `set device`, plus the one Dormouse-side
concept (Sync-to-pane). Built leaf-up per DOR_AGENT_BROWSER.md Phase 8.

- Allowlist `set` in both host command allowlists (lib + vscode-ext).
- Per-surface bridge (`agent-browser-screen.ts`) connecting the pane body
  (state/actions) to its tab header and the modal — a surface-id controller
  registry + modal-open store, both useSyncExternalStore.
- Panel: derive SYNCED/SCALED, ResizeObserver sync-to-pane (debounced),
  last-writer-wins disengage, auto-engage on create, re-sync on session
  restart; persist `syncEngaged` via dockview panel params (layout blob).
- Header chip gated strictly on controller presence; opens the modal.
- Modal (Sync / Device-registry / Custom) pre-filled from the live snapshot;
  suppresses Wall keys; Apply disabled with a note when the host can't run
  commands (Tauri).

Build-forced corrections (verified against agent-browser 0.27.0):
- The screencast is CSS-pixel resolution; the JPEG never encodes the browser
  DPR (`set viewport 800 600 2` == `@1`), so DPR is unrecoverable from frames.
  SYNCED is a pure viewport-CSS-size match; DPR is issued, not compared. The
  prior DPR-inference would have read SCALED forever on retina.
- engageSync must force a re-issue even when already engaged.
- Disengage only after a frame confirms the issued size landed, so a stale
  pre-resize frame isn't mistaken for an external override.
- Call host adapter methods through the instance, not a detached reference —
  `const cmd = getPlatform().agentBrowserCommand; cmd(...)` dropped `this` and
  threw on `this.requestResponse`, silently breaking every webview→host
  command (set, tab switch/close, edit chords). Fixed at both call sites.

Spec + plan updated for the persistence channel and DPR findings. New unit
tests for the screen registry; lib suite green (549).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md                          | 110 ++++++++
 docs/specs/dor-agent-browser.md               |  52 ++--
 .../AgentBrowserScreenModalHost.tsx           |  44 +++
 lib/src/components/Wall.tsx                   |   5 +
 lib/src/components/wall/AgentBrowserPanel.tsx | 253 +++++++++++++++++-
 .../wall/AgentBrowserScreenModal.tsx          | 241 +++++++++++++++++
 lib/src/components/wall/SurfacePaneHeader.tsx |  21 ++
 .../wall/agent-browser-screen.test.ts         | 118 ++++++++
 .../components/wall/agent-browser-screen.ts   | 180 +++++++++++++
 lib/src/lib/platform/types.ts                 |   5 +-
 vscode-ext/src/agent-browser-host.ts          |   2 +-
 11 files changed, 1004 insertions(+), 27 deletions(-)
 create mode 100644 lib/src/components/AgentBrowserScreenModalHost.tsx
 create mode 100644 lib/src/components/wall/AgentBrowserScreenModal.tsx
 create mode 100644 lib/src/components/wall/agent-browser-screen.test.ts
 create mode 100644 lib/src/components/wall/agent-browser-screen.ts

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
index f0fa692a..eb348152 100644
--- a/DOR_AGENT_BROWSER.md
+++ b/DOR_AGENT_BROWSER.md
@@ -276,3 +276,113 @@ Replace the `AgentBrowserPanel` stub with a live canvas viewer.
 - Works in `dogfood` (VS Code) and standalone; CSP allows the stream WS.
 - Spec updated for any design change the build forced (especially the input
   channel after the spike).
+
+---
+
+## Phase 8 — Screen indicator (SYNCED/SCALED) + viewport modal
+
+**Spec:** "Screen Indicator & Viewport". A two-state header indicator derived
+from reality, plus a modal that is purely a GUI front-end for native
+`agent-browser set viewport` / `set device`. No keyboard shortcut.
+
+**The architectural wrinkle to solve first.** The indicator lives in
+`SurfacePaneHeader` (a dockview *tab* component) but the live state (viewport,
+pane size, sync) and the action (`runAgentBrowser`) live in `AgentBrowserPanel`
+(the *body* component). They are separate components for one pane, so they need a
+per-surface bridge. Use the patterns already in the tree: a surface-id-keyed
+registry like `terminal-lifecycle.ts` + a `useSyncExternalStore` store like
+`external-link-confirmation.ts`. Build that bridge in 8b before the UI.
+
+Leaf-up, each step independently verifiable:
+
+### 8a — Allowlist `set`
+
+- Add `'set'` to **both** allowlists: `AGENT_BROWSER_ALLOWED_SUBCOMMANDS`
+  (`lib/src/lib/platform/types.ts:45`) and `ALLOWED_SUBCOMMANDS`
+  (`vscode-ext/src/agent-browser-host.ts:23`). Still `args[0]`-gated — not a
+  general exec channel.
+- **Verify:** from the panel, `runAgentBrowser(['set','viewport','800','600','1'])`
+  resizes the live browser (frames reflow).
+
+### 8b — Per-surface screen bridge
+
+- New `lib/src/components/wall/agent-browser-screen.ts`: registry keyed by
+  surface id, each entry exposing `subscribe`/`snapshot` of
+  `{ state: 'SYNCED'|'SCALED', viewport:{w,h,dpr}, paneCss:{w,h}, displayDpr,
+  syncEngaged }` and actions `{ engageSync(), applyDevice(name),
+  applyViewport(w,h,dpr), openModal() }`.
+- `AgentBrowserPanel` registers its controller on mount (with `session` /
+  `binaryPath`), unregisters on unmount. Presence of a controller for `api.id`
+  is how the header knows a pane is an agent-browser surface.
+
+### 8c — Derive SYNCED/SCALED in the panel + publish
+
+- Compute from `deviceRef` (browser CSS viewport) and `canvas.width /
+  deviceRef.width` (inferred DPR) vs pane CSS size (`getBoundingClientRect` on
+  `elRef`) and `window.devicePixelRatio`. `SYNCED` iff dims + DPR match within a
+  tolerance (guard fractional-DPR off-by-one). Publish to the registry **only on
+  flip or dim change** — never per frame (don't thrash the header).
+- **Verify:** resize the pane / change display scale → indicator value flips.
+
+### 8d — Sync-to-pane + reconciliation (panel)
+
+- While `syncEngaged`: `ResizeObserver` on `elRef` → re-issue `set viewport
+  <cssW> <cssH> <displayDpr>` debounced ~200ms; track `lastIssued`.
+- **Disengage rule:** when a frame reports a viewport matching neither
+  `lastIssued` nor the current pane (evaluated only when the pane is stable and
+  after we've issued), set `syncEngaged=false`. This is what lets `dor ab set …`
+  and modal Device/Custom transparently take over.
+- **Default on create: auto-engage sync** (decided) — a fresh browser surface
+  starts `SYNCED`, responsive to the pane, not at native 1280×720. Spec updated.
+- **Verify:** engage sync → `SYNCED`, resizes stay `SYNCED`; run `dor ab set
+  device "iPhone 16"` in a terminal → sync disengages, `SCALED`.
+
+### 8e — Header indicator
+
+- In `SurfacePaneHeader`, if a controller exists for `api.id`, render the
+  `SYNCED`/`SCALED` chip immediately right of the title; click → `openModal()`.
+  Gate strictly on controller presence so terminals/iframes are untouched.
+- **Verify:** chip shows only on browser surfaces, reflects state, click opens.
+
+### 8f — The modal
+
+- New `lib/src/components/wall/AgentBrowserScreenModal.tsx`, mounted via a host
+  in `Wall` (mirror `ExternalLinkModalHost`). Reads the controller snapshot and
+  pre-selects: *Sync* (if engaged + matching), else the registry device whose
+  dims match, else *Custom* prefilled with current dims. Radios: **Sync to pane**
+  / **Device** (fixed registry: iPhone 15/16/16 Pro/17, iPad, iPad Pro, Pixel 9,
+  Galaxy S25) / **Custom** (W/H/DPI). Apply → `engageSync()` / `applyDevice()` /
+  `applyViewport()`. Suppress Wall keys while open via `DialogKeyboardContext`
+  (`setDialogKeyboardActive`); Esc cancels.
+- **Device dims: apply-then-reflect** (decided) — the CLI doesn't expose a
+  device's dims up front, so choosing a device issues `set device <name>` and the
+  detail line fills in from the next frames. No hardcoded dims map. Spec updated.
+- **Verify:** pick iPhone 16 → `SCALED` + phone frame; Custom 800×600 → applies;
+  Sync → `SYNCED`.
+
+### 8g — Persistence
+
+- Persist `syncEngaged` per agent-browser surface. **Built via dockview panel
+  params** (`AgentBrowserPanel` writes `api.updateParameters({ syncEngaged })`
+  and seeds from `params.syncEngaged`), which round-trip through the serialized
+  layout blob — the same channel that already carries `session`/`wsPort` across
+  reloads — so no `session-types.ts`/`session-save.ts` change was needed. Device/
+  custom viewports live in the agent-browser session and survive reattach on
+  their own; sync re-engages on reattach iff it was engaged.
+- **Verify:** save/restore preserves sync; save/restore with a device keeps that
+  device (from the session).
+
+### 8h — Host-capability degradation
+
+- Without `agentBrowserCommand` (Tauri today), modal Apply / Sync are inert —
+  disable Apply or show a note, mirroring tab-action degradation. `dor ab set …`
+  from a terminal still works there (execs directly).
+
+### Definition of done (Phase 8)
+
+- Header shows `SYNCED`/`SCALED`, derived from frames, only on browser surfaces.
+- Modal applies Sync / Device / Custom via native `set`; pre-fills from reality.
+- `dor ab set …` from a terminal disengages sync and the indicator follows —
+  CLI and GUI stay consistent.
+- `syncEngaged` persists; standalone degrades gracefully.
+- Spec updated for the two decisions (create-default, device-dims).
diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index e3076305..6919d6d9 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -144,17 +144,23 @@ nothing more than a GUI front-end for those native `set` commands.
 Immediately to the **right of the title**, the header shows one of two derived
 states — never a stored mode:
 
-- **`SYNCED`** — the browser's live viewport **and** DPI exactly equal the pane's
+- **`SYNCED`** — the browser's live viewport (CSS pixels) equals the pane's CSS
   pixel size, so frames map 1:1 with no scaling.
 - **`SCALED`** — anything else; the frame is letterboxed/zoomed to fit the pane.
 
-Both are computed from the stream: viewport from frame
-`metadata.deviceWidth/Height`, DPI inferred as `frameBitmap.width /
-metadata.deviceWidth`. Because it is derived, the indicator is correct no matter
-*how* the viewport was set — modal, `dor ab set …`, or a raw `agent-browser`
-call. The panel's existing contain-scaling (`max-h-full max-w-full`) and
-coordinate mapping already produce the `SCALED` letterboxing; `SYNCED` is simply
-the case where the frame equals the pane. There is **no keyboard shortcut**.
+The viewport is read from the stream (`status.viewportWidth/Height`, equal to
+frame `metadata.deviceWidth/Height`) and compared against the pane's CSS size
+(`getBoundingClientRect`). **DPR is not part of the comparison:** the screencast
+is delivered at CSS-pixel resolution, so the JPEG never encodes the browser's
+device pixel ratio (verified 0.27.0 — `set viewport 800 600 2` yields the same
+800×600 frame as `@1`); it is therefore unrecoverable from frames. Dormouse still
+*issues* `displayDpr` when syncing so the page renders at the right density, but
+the indicator is a pure CSS-size match. Because it is derived, the indicator is
+correct no matter *how* the viewport was set — modal, `dor ab set …`, or a raw
+`agent-browser` call. The panel's existing contain-scaling (`max-h-full
+max-w-full`) and coordinate mapping already produce the `SCALED` letterboxing;
+`SYNCED` is simply the case where the viewport equals the pane. There is **no
+keyboard shortcut**.
 
 ### The modal
 
@@ -198,9 +204,17 @@ The device registry is fixed (no custom descriptors), and touch / mobile-UA are
 **only** available bundled inside `set device` — there is no standalone touch
 setting (verified against 0.27.0). So Sync/Custom are never touch; only Device
 is. The modal **reads the live viewport on open** and pre-selects accordingly:
-*Sync* if sync is engaged and matching, else the registry device whose
-dimensions match, else *Custom* pre-filled with the current dims. Like the
-indicator, the modal reflects reality rather than a stored intent.
+*Sync* if sync is engaged and matching, otherwise *Custom* pre-filled with the
+current dims. Like the indicator, the modal reflects reality rather than a stored
+intent.
+
+The CLI does not expose a device's dimensions ahead of time, so device sizing is
+**apply-then-reflect**: choosing a device issues `set device <name>`, and the
+detail line (`iPhone 16 · 393×852 @3x`) fills in from the next frames rather than
+being known up front. The same gap means the modal **cannot pre-select a device
+by matching dims** — with no dims map to compare against, a non-synced viewport
+pre-selects *Custom* (the device list still shows the live `SYNCED`/`SCALED`
+readout, just without a radio pre-checked on a specific device).
 
 ### Transparency with `dor ab set …`
 
@@ -214,7 +228,10 @@ pre-fill reflect it.
 
 **Sync is the one non-native concept.** agent-browser has no "follow the pane"
 mode; *Sync to pane* is a Dormouse behavior that auto-issues native `set
-viewport <pane>` and re-issues on resize. Coexistence is **last-writer-wins**:
+viewport <pane>` and re-issues on resize. **A freshly created browser surface
+auto-engages sync**, so it starts `SYNCED` — pixel-for-pixel and responsive to
+the pane — rather than at agent-browser's native 1280×720. Coexistence is
+**last-writer-wins**:
 Dormouse tracks the viewport it last issued (`lastIssued`); when a frame reports
 a viewport matching neither `lastIssued` nor the current pane, an external setter
 (`dor ab set …`) intervened, so Dormouse **disengages sync** and the indicator
@@ -235,8 +252,12 @@ the re-issue lands — is not mistaken for an external override.)
   `close`).
 - The only Dormouse-side state worth persisting is **whether sync is engaged**;
   device/custom viewports live in the agent-browser session itself and survive
-  reattach. On reattach Dormouse re-engages sync if it was engaged
-  (`session-types.ts`, `session-save.ts`).
+  reattach. `syncEngaged` rides in the surface's dockview **panel params**, which
+  already round-trip through the serialized layout blob (the same channel that
+  carries `session`/`wsPort` across webview reloads), so it persists with no
+  `session-types.ts`/`session-save.ts` changes; the panel seeds its initial state
+  from `params.syncEngaged` (absent ⇒ fresh surface ⇒ auto-engage), so reattach
+  re-engages sync iff it was engaged.
 - Like tab actions, this inherits the `agentBrowserCommand` host capability: on
   adapters that do not implement it (currently Tauri), modal-driven resizes are
   inert and the control degrades accordingly. (`dor ab set …` from a terminal
@@ -339,7 +360,8 @@ host on the webview's behalf (a webview cannot spawn processes; see
 | Surface component (canvas viewer + WS client + tab strip + sync tracking / `set` issuance / SYNCED-SCALED derivation) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
 | SYNCED/SCALED indicator right of the title; opens the screen modal (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
 | Screen modal (Sync / Device-registry / Custom; issues native `set …`) | `lib/src/components/wall/AgentBrowserScreenModal.tsx` (new) |
-| Per-surface "sync engaged" persistence | `lib/src/lib/session-types.ts`, `lib/src/lib/session-save.ts` |
+| Per-surface "sync engaged" persistence | the surface's dockview **panel params** (`syncEngaged`), persisted via the serialized layout blob — no `session-types.ts`/`session-save.ts` change |
+| Per-surface screen bridge (header↔body↔modal) | `lib/src/components/wall/agent-browser-screen.ts` (new); modal host `lib/src/components/AgentBrowserScreenModalHost.tsx` (new) |
 | Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
 | Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
 | Host CLI runner (`agentBrowserCommand`) + VS Code stream relay | `lib/src/lib/platform/types.ts` (optional adapter methods), `vscode-ext/src/message-router.ts`, `vscode-ext/src/agent-browser-host.ts` |
diff --git a/lib/src/components/AgentBrowserScreenModalHost.tsx b/lib/src/components/AgentBrowserScreenModalHost.tsx
new file mode 100644
index 00000000..8ca7291f
--- /dev/null
+++ b/lib/src/components/AgentBrowserScreenModalHost.tsx
@@ -0,0 +1,44 @@
+import { useEffect } from 'react';
+import { AgentBrowserScreenModal } from './wall/AgentBrowserScreenModal';
+import {
+  closeAgentBrowserScreenModal,
+  useAgentBrowserScreenController,
+  useOpenAgentBrowserScreenModalId,
+} from './wall/agent-browser-screen';
+
+/**
+ * Mounts the agent-browser screen modal when a surface requests it, mirroring
+ * ExternalLinkModalHost. `resolveLabel` turns a surface id into its display ref
+ * (e.g. `surface:3`) for the title.
+ */
+export function AgentBrowserScreenModalHost({
+  onKeyboardActiveChange,
+  resolveLabel,
+}: {
+  onKeyboardActiveChange: (active: boolean) => void;
+  resolveLabel: (surfaceId: string) => string;
+}) {
+  const id = useOpenAgentBrowserScreenModalId();
+  const controller = useAgentBrowserScreenController(id ?? '');
+  const open = id !== null && controller !== null;
+
+  useEffect(() => {
+    onKeyboardActiveChange(open);
+    return () => onKeyboardActiveChange(false);
+  }, [onKeyboardActiveChange, open]);
+
+  // The surface was killed (or detached) while its modal was open — drop it.
+  useEffect(() => {
+    if (id !== null && controller === null) closeAgentBrowserScreenModal();
+  }, [id, controller]);
+
+  if (!id || !controller) return null;
+
+  return (
+    <AgentBrowserScreenModal
+      controller={controller}
+      label={resolveLabel(id)}
+      onClose={closeAgentBrowserScreenModal}
+    />
+  );
+}
diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 078b9f69..8fe67d2d 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -9,6 +9,7 @@ import {
 import 'dockview-react/dist/styles/dockview.css';
 import { Baseboard } from './Baseboard';
 import { ExternalLinkModalHost } from './ExternalLinkModalHost';
+import { AgentBrowserScreenModalHost } from './AgentBrowserScreenModalHost';
 import { KILL_CONFIRM_MS, KILL_SHAKE_MS, KillConfirmOverlay, randomKillChar, type ConfirmKill } from './KillConfirm';
 import {
   clearSessionAttention,
@@ -1580,6 +1581,10 @@ export function Wall({
             />
 
             <ExternalLinkModalHost onKeyboardActiveChange={setDialogKeyboardActive} />
+            <AgentBrowserScreenModalHost
+              onKeyboardActiveChange={setDialogKeyboardActive}
+              resolveLabel={surfaceRefForId}
+            />
 
           </div>
           </DialogKeyboardContext.Provider>
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 387b4d5e..fac06f61 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -6,12 +6,20 @@
  * `tabs` messages. Tab actions (switch/close) go through the host's
  * `agentBrowserCommand` because a webview cannot spawn the agent-browser CLI.
  */
-import { useCallback, useContext, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { clsx } from 'clsx';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
 import { getPlatform } from '../../lib/platform';
 import { readTextFromClipboard } from '../../lib/clipboard';
+import {
+  openAgentBrowserScreenModal,
+  registerAgentBrowserScreen,
+  type ScreenActions,
+  type ScreenRegistration,
+  type ScreenSnapshot,
+  type ScreenState,
+} from './agent-browser-screen';
 import {
   FreshlySpawnedContext,
   ModeContext,
@@ -26,8 +34,24 @@ type AgentBrowserPanelParams = {
   key?: string;
   wsPort?: number;
   binaryPath?: string;
+  /** Whether sync-to-pane is engaged; persists via the dockview layout blob so
+   *  a re-attached surface re-engages sync if it was engaged. Absent on a fresh
+   *  surface ⇒ auto-engage (see docs/specs/dor-agent-browser.md). */
+  syncEngaged?: boolean;
 };
 
+// SYNCED is "browser viewport CSS size == pane CSS size". The screencast is
+// always delivered at CSS-pixel resolution — the frame never encodes the
+// browser's DPR (verified 0.27.0: `set viewport 800 600 2` yields the same
+// 800×600 JPEG as @1) — so DPR is unrecoverable from frames and plays no part
+// in the match; we still *issue* displayDpr so the page renders at the right
+// density. Dims can be a pixel off after rounding, so compare with a tolerance.
+const DIM_TOLERANCE = 1;
+
+function dimsMatch(a: { w: number; h: number }, b: { w: number; h: number }): boolean {
+  return Math.abs(a.w - b.w) <= DIM_TOLERANCE && Math.abs(a.h - b.h) <= DIM_TOLERANCE;
+}
+
 type StreamTab = {
   tabId: string;
   title: string | null;
@@ -128,6 +152,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
   const mode = useContext(ModeContext);
   const selectedId = useContext(SelectedIdContext);
   const elRef = useRef<HTMLDivElement>(null);
+  const viewportRef = useRef<HTMLDivElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
 
   const session = params?.session;
@@ -148,12 +173,14 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
   const binaryPath = params?.binaryPath;
   const runAgentBrowser = useCallback((args: string[]) => {
     if (!session) return;
-    const command = getPlatform().agentBrowserCommand;
-    if (!command) {
+    // Call through the adapter instance — pulling the method into a bare
+    // variable would detach `this` and break its internal `requestResponse`.
+    const platform = getPlatform();
+    if (!platform.agentBrowserCommand) {
       console.warn('[agent-browser] this host cannot run agent-browser commands; tab actions are unavailable');
       return;
     }
-    command(session, args, binaryPath).then((result) => {
+    platform.agentBrowserCommand(session, args, binaryPath).then((result) => {
       if (result.exitCode !== 0) {
         console.warn(`[agent-browser] ${args.join(' ')} failed:`, result.stderr || result.stdout || `exit ${result.exitCode}`);
       }
@@ -161,6 +188,101 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       console.warn(`[agent-browser] ${args.join(' ')} failed:`, error);
     });
   }, [session, binaryPath]);
+  const runAgentBrowserRef = useRef(runAgentBrowser);
+  runAgentBrowserRef.current = runAgentBrowser;
+
+  // --- screen indicator (SYNCED/SCALED) + sync-to-pane ---
+  //
+  // A fresh surface auto-engages sync (no persisted flag); a re-attached one
+  // restores whatever was persisted into the layout blob.
+  const [syncEngaged, setSyncEngaged] = useState<boolean>(params?.syncEngaged ?? true);
+  const syncEngagedRef = useRef(syncEngaged);
+  syncEngagedRef.current = syncEngaged;
+  // The pane size we last issued `set viewport` for; null while not driving the
+  // viewport (device/custom, or never issued). Used both to skip redundant
+  // re-issues and to detect an external `set …` taking over.
+  const lastIssuedRef = useRef<{ w: number; h: number; dpr: number } | null>(null);
+  // True once a frame has confirmed `lastIssued` actually landed. Until then,
+  // frames still at the browser's pre-resize size are our own `set` not having
+  // taken effect yet — not an external override.
+  const syncConfirmedRef = useRef(false);
+  const lastPublishedRef = useRef<ScreenSnapshot | null>(null);
+  const registrationRef = useRef<ScreenRegistration | null>(null);
+
+  const computeSnapshot = useCallback((): ScreenSnapshot => {
+    const rect = viewportRef.current?.getBoundingClientRect();
+    const displayDpr = window.devicePixelRatio || 1;
+    const device = deviceRef.current;
+    const paneCss = { w: rect ? Math.round(rect.width) : 0, h: rect ? Math.round(rect.height) : 0 };
+    // DPR can't be read back from frames, so report the density we'd sync to.
+    const viewport = { w: device.width, h: device.height, dpr: displayDpr };
+    const state: ScreenState = dimsMatch(viewport, paneCss) ? 'SYNCED' : 'SCALED';
+    return { state, viewport, paneCss, displayDpr, syncEngaged: syncEngagedRef.current };
+  }, []);
+
+  // Publish to the registry only when something the header/modal cares about
+  // changed — never per frame (the frame loop calls this every paint).
+  const publishScreen = useCallback(() => {
+    const next = computeSnapshot();
+    const prev = lastPublishedRef.current;
+    const changed =
+      !prev ||
+      prev.state !== next.state ||
+      prev.viewport.w !== next.viewport.w ||
+      prev.viewport.h !== next.viewport.h ||
+      prev.viewport.dpr !== next.viewport.dpr ||
+      prev.displayDpr !== next.displayDpr ||
+      prev.syncEngaged !== next.syncEngaged ||
+      !dimsMatch(prev.paneCss, next.paneCss);
+    if (changed) {
+      lastPublishedRef.current = next;
+      registrationRef.current?.update(next);
+    }
+  }, [computeSnapshot]);
+
+  // Push the current pane size to the browser as a native `set viewport`.
+  const issueSyncToPane = useCallback(() => {
+    // Hosts without agentBrowserCommand (Tauri today) can't drive the viewport;
+    // stay silent rather than warn on every resize. The surface just reads
+    // SCALED, which is accurate.
+    if (!getPlatform().agentBrowserCommand) return;
+    const el = viewportRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const w = Math.round(rect.width);
+    const h = Math.round(rect.height);
+    if (!w || !h) return;
+    const dpr = window.devicePixelRatio || 1;
+    const prev = lastIssuedRef.current;
+    if (prev && prev.w === w && prev.h === h && Math.abs(prev.dpr - dpr) <= 0.001) return;
+    lastIssuedRef.current = { w, h, dpr };
+    syncConfirmedRef.current = false;
+    runAgentBrowserRef.current(['set', 'viewport', String(w), String(h), String(dpr)]);
+  }, []);
+
+  // Last-writer-wins: drop sync when an external `dor ab set …` takes the
+  // viewport away from what we issued. The trap is that right after we issue a
+  // new size, the browser keeps streaming the OLD size for a few frames — those
+  // must NOT count as external. So we only disengage once a frame has first
+  // *confirmed* our issued size landed, and a later frame then deviates.
+  const maybeDisengageSync = useCallback(() => {
+    if (!syncEngagedRef.current) return;
+    const issued = lastIssuedRef.current;
+    const el = viewportRef.current;
+    if (!issued || !el) return;
+    const rect = el.getBoundingClientRect();
+    const pane = { w: Math.round(rect.width), h: Math.round(rect.height) };
+    // Mid-resize: we haven't issued for the pane's current size yet.
+    if (!dimsMatch(issued, pane)) return;
+    const device = { w: deviceRef.current.width, h: deviceRef.current.height };
+    if (dimsMatch(device, issued)) {
+      syncConfirmedRef.current = true; // our `set` landed
+      return;
+    }
+    // Frame differs from what we issued: a pre-landing stale frame until
+    // confirmed; an external override once confirmed.
+    if (syncConfirmedRef.current) setSyncEngaged(false);
+  }, []);
 
   // --- pane registration + spawn animation (shared surface boilerplate) ---
 
@@ -228,6 +350,11 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
         canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
         bitmap.close();
         setHasFrame(true);
+        // The frame just told us the browser's live viewport + DPR; reconcile
+        // sync and refresh the indicator. publishScreen self-gates, so this is
+        // cheap despite running every paint.
+        maybeDisengageSync();
+        publishScreen();
       }).catch(() => {});
     };
 
@@ -247,6 +374,8 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
         else setConnectionLost(false);
         if (typeof msg.viewportWidth === 'number' && typeof msg.viewportHeight === 'number') {
           deviceRef.current = { width: msg.viewportWidth, height: msg.viewportHeight };
+          maybeDisengageSync();
+          publishScreen();
         }
       } else if (msg.type === 'tabs' && Array.isArray(msg.tabs)) {
         const next: StreamTab[] = msg.tabs
@@ -308,7 +437,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       wsRef.current = null;
       ws?.close();
     };
-  }, [wsPort, runAgentBrowser]);
+  }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen]);
 
   // --- header title follows the active tab ---
 
@@ -317,6 +446,107 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     if (active) api.setTitle(tabDisplayTitle(active));
   }, [tabs, api]);
 
+  // --- screen controller: register for the header/modal bridge ---
+
+  // Stable across renders (reads refs / stable setters), so the registered
+  // controller never goes stale. Engaging always re-issues (clears lastIssued)
+  // so it reclaims the viewport even from an external device.
+  const screenActions = useMemo<ScreenActions>(() => ({
+    engageSync() {
+      // Clear lastIssued so the issue below isn't skipped, and issue now rather
+      // than relying on the syncEngaged effect — re-selecting Sync while already
+      // engaged must still reclaim the viewport (e.g. from an external `set`).
+      lastIssuedRef.current = null;
+      setSyncEngaged(true);
+      issueSyncToPane();
+    },
+    applyDevice(name) {
+      lastIssuedRef.current = null;
+      setSyncEngaged(false);
+      runAgentBrowserRef.current(['set', 'device', name]);
+    },
+    applyViewport(w, h, dpr) {
+      lastIssuedRef.current = null;
+      setSyncEngaged(false);
+      runAgentBrowserRef.current(['set', 'viewport', String(w), String(h), String(dpr)]);
+    },
+    openModal() {
+      openAgentBrowserScreenModal(api.id);
+    },
+  }), [api.id, issueSyncToPane]);
+
+  useEffect(() => {
+    const registration = registerAgentBrowserScreen(api.id, {
+      snapshot: computeSnapshot(),
+      actions: screenActions,
+      hostCapable: !!getPlatform().agentBrowserCommand,
+    });
+    registrationRef.current = registration;
+    lastPublishedRef.current = null;
+    publishScreen();
+    return () => {
+      registration.dispose();
+      registrationRef.current = null;
+    };
+  }, [api.id, screenActions, computeSnapshot, publishScreen]);
+
+  // Persist sync state into the panel params so it round-trips through the
+  // dockview layout blob (and survives reattach). Skip no-op writes.
+  useEffect(() => {
+    if (params?.syncEngaged !== syncEngaged) api.updateParameters({ syncEngaged });
+  }, [syncEngaged, params?.syncEngaged, api]);
+
+  // Reflect a sync flip in the indicator immediately, without waiting for the
+  // next frame.
+  useEffect(() => {
+    publishScreen();
+  }, [syncEngaged, publishScreen]);
+
+  // While sync is engaged, follow the pane: re-issue `set viewport` (debounced)
+  // on resize. ResizeObserver fires once on observe, giving the initial sync;
+  // the explicit call covers re-engaging at an unchanged size.
+  useEffect(() => {
+    if (!syncEngaged) return;
+    const el = viewportRef.current;
+    if (!el) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const observer = new ResizeObserver(() => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        issueSyncToPane();
+        publishScreen();
+      }, 200);
+    });
+    observer.observe(el);
+    issueSyncToPane();
+    return () => {
+      observer.disconnect();
+      if (timer) clearTimeout(timer);
+    };
+  }, [syncEngaged, issueSyncToPane, publishScreen]);
+
+  // A new/restarted session (wsPort change) comes up at agent-browser's native
+  // viewport; if sync is engaged, reclaim the pane size. Clearing lastIssued is
+  // essential — it otherwise still holds the previous session's pane size and
+  // issueSyncToPane would no-op, leaving the fresh browser unsynced (SCALED).
+  useEffect(() => {
+    if (!wsPort || !syncEngagedRef.current) return;
+    lastIssuedRef.current = null;
+    issueSyncToPane();
+  }, [wsPort, issueSyncToPane]);
+
+  // Display-scale (DPR) changes don't resize the pane, so ResizeObserver misses
+  // them; a window resize is the available signal. Recompute the indicator and,
+  // if synced, re-issue at the new DPR.
+  useEffect(() => {
+    const onWindowResize = () => {
+      if (syncEngagedRef.current) issueSyncToPane();
+      publishScreen();
+    };
+    window.addEventListener('resize', onWindowResize);
+    return () => window.removeEventListener('resize', onWindowResize);
+  }, [issueSyncToPane, publishScreen]);
+
   // --- input forwarding (stream-native input_* messages) ---
 
   const send = useCallback((payload: Record<string, unknown>) => {
@@ -495,9 +725,10 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     // chord for its own JS shortcuts.
     if (mod && !e.altKey && !e.shiftKey) {
       const op = EDIT_OPS[e.key.toLowerCase() as keyof typeof EDIT_OPS];
-      const edit = getPlatform().agentBrowserEdit;
-      if (op && edit && session) {
-        edit(session, op, binaryPath).then((r) => {
+      // Call through the adapter instance — detaching the method drops `this`.
+      const platform = getPlatform();
+      if (op && platform.agentBrowserEdit && session) {
+        platform.agentBrowserEdit(session, op, binaryPath).then((r) => {
           if (!r.ok && r.error) console.warn(`[agent-browser] ${op} failed:`, r.error);
         }).catch((err) => console.warn(`[agent-browser] ${op} failed:`, err));
         return;
@@ -536,6 +767,10 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       if (!interactiveRef.current || e.defaultPrevented) return;
       const el = elRef.current;
       if (el && e.target instanceof Node && el.contains(e.target)) return;
+      // A screen modal (or any dialog) renders outside the pane element, so the
+      // contains() check above misses it; without this, typing into the modal's
+      // Custom W/H/DPI fields would be swallowed and forwarded to the browser.
+      if (e.target instanceof Element && e.target.closest('[role="dialog"]')) return;
       e.preventDefault();
       if (e.type === 'keydown') handleKeyDownLike(e);
       else sendKey(e, 'keyUp');
@@ -615,7 +850,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
           ))}
         </div>
       )}
-      <div className="relative flex min-h-0 flex-1 items-center justify-center">
+      <div ref={viewportRef} className="relative flex min-h-0 flex-1 items-center justify-center">
         <canvas
           ref={canvasRef}
           className={clsx('block max-h-full max-w-full select-none', !hasFrame && 'hidden')}
diff --git a/lib/src/components/wall/AgentBrowserScreenModal.tsx b/lib/src/components/wall/AgentBrowserScreenModal.tsx
new file mode 100644
index 00000000..816d993c
--- /dev/null
+++ b/lib/src/components/wall/AgentBrowserScreenModal.tsx
@@ -0,0 +1,241 @@
+/**
+ * Screen / viewport modal for an agent-browser surface
+ * (docs/specs/dor-agent-browser.md → "Screen Indicator & Viewport → The
+ * modal"). It is purely a GUI front-end for native `agent-browser set
+ * viewport` / `set device`, plus the one Dormouse-side concept, *Sync to pane*.
+ *
+ * Three mutually exclusive targets:
+ *   - Sync to pane → engageSync()  (auto-issues `set viewport <pane>` on resize)
+ *   - Device       → applyDevice() (fixed registry; bundles viewport+DPR+touch+UA)
+ *   - Custom       → applyViewport()
+ *
+ * It reads the live snapshot on open and pre-selects accordingly, reflecting
+ * reality rather than a stored intent.
+ */
+import { useMemo, useRef, useState } from 'react';
+import { ModalCloseButton, ModalFrame, modalActionButton } from '../design';
+import type { ScreenController, ScreenSnapshot } from './agent-browser-screen';
+import { useAgentBrowserScreenSnapshot } from './agent-browser-screen';
+
+// Fixed registry — the CLI's own device set. No custom descriptors; touch +
+// mobile UA come only bundled inside `set device` (verified against 0.27.0).
+const DEVICES = [
+  'iPhone 15',
+  'iPhone 16',
+  'iPhone 16 Pro',
+  'iPhone 17',
+  'iPad',
+  'iPad Pro',
+  'Pixel 9',
+  'Galaxy S25',
+] as const;
+
+type Target = 'sync' | 'device' | 'custom';
+
+function formatDpr(dpr: number): string {
+  return `${Number.isInteger(dpr) ? dpr : Math.round(dpr * 100) / 100}x`;
+}
+
+export function AgentBrowserScreenModal({
+  controller,
+  label,
+  onClose,
+}: {
+  controller: ScreenController;
+  label: string;
+  onClose: () => void;
+}) {
+  const live = useAgentBrowserScreenSnapshot(controller);
+  // Snapshot the state the modal opened with for pre-selection; the live one
+  // still drives the "Currently" readout so it tracks external changes.
+  const [initial] = useState<ScreenSnapshot | null>(() => controller.snapshot());
+  const snapshot = live ?? initial;
+
+  const cancelRef = useRef<HTMLButtonElement>(null);
+  const hostCapable = controller.hostCapable;
+
+  // Pre-select: Sync if engaged + actually synced; otherwise Custom prefilled
+  // with the current dims. (A device can't be pre-matched — the CLI doesn't
+  // expose device dims up front, so there's no dims map to compare against.)
+  const initialTarget: Target =
+    initial?.syncEngaged && initial.state === 'SYNCED' ? 'sync' : 'custom';
+  const [target, setTarget] = useState<Target>(initialTarget);
+  const [device, setDevice] = useState<string>(DEVICES[1]); // iPhone 16
+  const [customW, setCustomW] = useState(String(initial?.viewport.w ?? 1280));
+  const [customH, setCustomH] = useState(String(initial?.viewport.h ?? 720));
+  const [customDpi, setCustomDpi] = useState(String(initial?.viewport.dpr ?? 1));
+
+  const customValid = useMemo(() => {
+    const w = Number(customW);
+    const h = Number(customH);
+    const dpi = Number(customDpi);
+    return Number.isInteger(w) && w > 0 && Number.isInteger(h) && h > 0 && dpi > 0 && Number.isFinite(dpi);
+  }, [customW, customH, customDpi]);
+
+  const applyDisabled = !hostCapable || (target === 'custom' && !customValid);
+
+  const apply = () => {
+    if (applyDisabled) return;
+    if (target === 'sync') controller.actions.engageSync();
+    else if (target === 'device') controller.actions.applyDevice(device);
+    else controller.actions.applyViewport(Number(customW), Number(customH), Number(customDpi));
+    onClose();
+  };
+
+  const vp = snapshot?.viewport;
+  const pane = snapshot?.paneCss;
+
+  return (
+    <ModalFrame
+      titleId="agent-browser-screen-modal-title"
+      layer="critical"
+      backdrop="strong"
+      elevation="modal"
+      overlayClassName="px-4 py-6"
+      className="w-full max-w-[30rem]"
+      initialFocusRef={cancelRef}
+      onEscape={onClose}
+    >
+      <div className="flex items-start gap-3">
+        <h2
+          id="agent-browser-screen-modal-title"
+          className="min-w-0 flex-1 text-sm leading-5 text-foreground"
+        >
+          Screen — <span className="font-semibold">{label}</span>
+        </h2>
+        <ModalCloseButton onClick={onClose} />
+      </div>
+
+      {snapshot && vp && pane && (
+        <div className="mt-3 text-xs text-muted">
+          Currently <span className="font-semibold text-foreground">{snapshot.state}</span>
+          <div className="mt-0.5 font-mono">
+            browser {vp.w}×{vp.h}
+            {'  ·  '}
+            pane {pane.w}×{pane.h} @{formatDpr(snapshot.displayDpr)}
+          </div>
+        </div>
+      )}
+
+      <div className="mt-4 flex flex-col gap-3 text-sm">
+        <label className="flex cursor-pointer items-start gap-2">
+          <input
+            type="radio"
+            name="screen-target"
+            className="mt-0.5"
+            checked={target === 'sync'}
+            onChange={() => setTarget('sync')}
+          />
+          <span className="min-w-0">
+            <span className="text-foreground">Sync to pane</span>
+            <span className="mt-0.5 block text-xs text-muted">
+              viewport follows the pane, pixel-for-pixel
+              {pane ? ` → now: ${pane.w}×${pane.h} @${formatDpr(snapshot?.displayDpr ?? 1)}` : ''}
+            </span>
+          </span>
+        </label>
+
+        <label className="flex cursor-pointer items-start gap-2">
+          <input
+            type="radio"
+            name="screen-target"
+            className="mt-0.5"
+            checked={target === 'device'}
+            onChange={() => setTarget('device')}
+          />
+          <span className="min-w-0 flex-1">
+            <span className="text-foreground">Device</span>
+            <span className="ml-2 text-xs text-muted">emulates touch + mobile UA</span>
+            <span className="mt-1.5 grid grid-cols-2 gap-1">
+              {DEVICES.map((name) => (
+                <button
+                  key={name}
+                  type="button"
+                  onClick={() => { setTarget('device'); setDevice(name); }}
+                  className={`rounded border px-2 py-1 text-left text-xs transition-colors ${
+                    target === 'device' && device === name
+                      ? 'border-focus-ring bg-header-inactive-bg text-foreground'
+                      : 'border-border text-muted hover:text-foreground'
+                  }`}
+                >
+                  {name}
+                </button>
+              ))}
+            </span>
+            <span className="mt-1 block text-xs text-muted">
+              dimensions fill in after applying
+            </span>
+          </span>
+        </label>
+
+        <label className="flex cursor-pointer items-start gap-2">
+          <input
+            type="radio"
+            name="screen-target"
+            className="mt-0.5"
+            checked={target === 'custom'}
+            onChange={() => setTarget('custom')}
+          />
+          <span className="flex min-w-0 flex-1 flex-wrap items-center gap-2">
+            <span className="text-foreground">Custom</span>
+            <DimInput label="W" value={customW} onChange={setCustomW} onFocus={() => setTarget('custom')} />
+            <DimInput label="H" value={customH} onChange={setCustomH} onFocus={() => setTarget('custom')} />
+            <DimInput label="DPI" value={customDpi} onChange={setCustomDpi} onFocus={() => setTarget('custom')} />
+          </span>
+        </label>
+      </div>
+
+      {!hostCapable && (
+        <p className="mt-3 text-xs text-muted">
+          This host can't drive the browser viewport; run <span className="font-mono">dor ab set …</span> from a
+          terminal instead.
+        </p>
+      )}
+
+      <div className="mt-4 flex justify-end gap-2 text-xs">
+        <button
+          ref={cancelRef}
+          type="button"
+          onClick={onClose}
+          className={`${modalActionButton({ tone: 'secondary' })} min-w-[5rem]`}
+        >
+          Cancel
+        </button>
+        <button
+          type="button"
+          onClick={apply}
+          disabled={applyDisabled}
+          className={`${modalActionButton({ tone: 'primary' })} min-w-[5rem]`}
+        >
+          Apply
+        </button>
+      </div>
+    </ModalFrame>
+  );
+}
+
+function DimInput({
+  label,
+  value,
+  onChange,
+  onFocus,
+}: {
+  label: string;
+  value: string;
+  onChange: (next: string) => void;
+  onFocus: () => void;
+}) {
+  return (
+    <span className="inline-flex items-center gap-1 text-xs text-muted">
+      {label}
+      <input
+        type="text"
+        inputMode="numeric"
+        value={value}
+        onFocus={onFocus}
+        onChange={(e) => onChange(e.target.value.replace(/[^0-9.]/g, ''))}
+        className="w-16 rounded border border-border bg-app-bg px-1.5 py-1 font-mono text-foreground outline-none focus:border-focus-ring"
+      />
+    </span>
+  );
+}
diff --git a/lib/src/components/wall/SurfacePaneHeader.tsx b/lib/src/components/wall/SurfacePaneHeader.tsx
index 6c9cac74..2c5495c8 100644
--- a/lib/src/components/wall/SurfacePaneHeader.tsx
+++ b/lib/src/components/wall/SurfacePaneHeader.tsx
@@ -10,6 +10,10 @@ import {
 } from '@phosphor-icons/react';
 import { HeaderActionButton } from '../HeaderActionButton';
 import { TERMINAL_TOP_RADIUS_CLASS } from '../design';
+import {
+  useAgentBrowserScreenController,
+  useAgentBrowserScreenSnapshot,
+} from './agent-browser-screen';
 import {
   ModeContext,
   SelectedIdContext,
@@ -26,12 +30,29 @@ export function SurfacePaneHeader({ api }: IDockviewPanelHeaderProps) {
   const actions = useContext(WallActionsContext);
   const isActiveHeader = mode === 'passthrough' && selectedId === api.id && windowFocused;
 
+  // Presence of a screen controller for this pane is exactly what marks it an
+  // agent-browser surface — terminals/iframes never register one, so the chip
+  // is strictly scoped to browser surfaces.
+  const screen = useAgentBrowserScreenController(api.id);
+  const screenSnapshot = useAgentBrowserScreenSnapshot(screen);
+
   return (
     <div
       className={`flex h-full w-full cursor-grab items-center gap-1.5 ${TERMINAL_TOP_RADIUS_CLASS} pl-2 pr-[5px] text-sm leading-none font-mono select-none active:cursor-grabbing ${isActiveHeader ? 'bg-header-active-bg text-header-active-fg' : 'bg-header-inactive-bg text-header-inactive-fg'}`}
       onMouseDown={() => actions.onClickPanel(api.id)}
     >
       <span className="min-w-0 flex-1 truncate font-medium">{api.title ?? api.id}</span>
+      {screen && screenSnapshot && (
+        <button
+          type="button"
+          onClick={(e) => { e.stopPropagation(); screen.actions.openModal(); }}
+          aria-label={`Screen: ${screenSnapshot.state} — change viewport`}
+          title="Screen / viewport"
+          className="shrink-0 rounded px-1 py-0.5 text-xs leading-none font-semibold tracking-[0.08em] text-current/70 transition-colors hover:bg-current/10 hover:text-current"
+        >
+          {screenSnapshot.state}
+        </button>
+      )}
       <div className="ml-1 hidden shrink-0 items-center gap-0.5 min-[420px]:flex">
         <HeaderActionButton
           className="flex h-5 min-w-5 items-center justify-center rounded transition-colors hover:bg-current/10"
diff --git a/lib/src/components/wall/agent-browser-screen.test.ts b/lib/src/components/wall/agent-browser-screen.test.ts
new file mode 100644
index 00000000..1d4b7a60
--- /dev/null
+++ b/lib/src/components/wall/agent-browser-screen.test.ts
@@ -0,0 +1,118 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  closeAgentBrowserScreenModal,
+  getAgentBrowserScreenController,
+  getOpenAgentBrowserScreenModalId,
+  openAgentBrowserScreenModal,
+  registerAgentBrowserScreen,
+  subscribeAgentBrowserScreenModal,
+  subscribeAgentBrowserScreenPresence,
+  type ScreenActions,
+  type ScreenSnapshot,
+} from './agent-browser-screen';
+
+const SNAPSHOT: ScreenSnapshot = {
+  state: 'SCALED',
+  viewport: { w: 1280, h: 720, dpr: 1 },
+  paneCss: { w: 980, h: 560 },
+  displayDpr: 2,
+  syncEngaged: true,
+};
+
+function stubActions(): ScreenActions {
+  return { engageSync: vi.fn(), applyDevice: vi.fn(), applyViewport: vi.fn(), openModal: vi.fn() };
+}
+
+describe('agent-browser screen registry', () => {
+  it('registers a controller, notifies presence, and disposes', () => {
+    let presence = 0;
+    const unsubscribe = subscribeAgentBrowserScreenPresence(() => {
+      presence += 1;
+    });
+
+    expect(getAgentBrowserScreenController('pane-1')).toBeNull();
+
+    const registration = registerAgentBrowserScreen('pane-1', {
+      snapshot: SNAPSHOT,
+      actions: stubActions(),
+      hostCapable: true,
+    });
+    expect(presence).toBe(1);
+
+    const controller = getAgentBrowserScreenController('pane-1');
+    expect(controller).not.toBeNull();
+    expect(controller?.snapshot()).toEqual(SNAPSHOT);
+    expect(controller?.hostCapable).toBe(true);
+
+    registration.dispose();
+    expect(presence).toBe(2);
+    expect(getAgentBrowserScreenController('pane-1')).toBeNull();
+
+    unsubscribe();
+  });
+
+  it('publishes snapshot updates to subscribers', () => {
+    const registration = registerAgentBrowserScreen('pane-2', {
+      snapshot: SNAPSHOT,
+      actions: stubActions(),
+      hostCapable: false,
+    });
+    const controller = getAgentBrowserScreenController('pane-2')!;
+
+    let updates = 0;
+    const unsubscribe = controller.subscribe(() => {
+      updates += 1;
+    });
+
+    const next: ScreenSnapshot = { ...SNAPSHOT, state: 'SYNCED' };
+    registration.update(next);
+    expect(updates).toBe(1);
+    expect(controller.snapshot()).toEqual(next);
+
+    unsubscribe();
+    registration.dispose();
+  });
+
+  it('a stale registration does not clobber a re-registered surface on dispose', () => {
+    const first = registerAgentBrowserScreen('pane-3', {
+      snapshot: SNAPSHOT,
+      actions: stubActions(),
+      hostCapable: true,
+    });
+    const second = registerAgentBrowserScreen('pane-3', {
+      snapshot: SNAPSHOT,
+      actions: stubActions(),
+      hostCapable: true,
+    });
+    const live = getAgentBrowserScreenController('pane-3');
+
+    // Disposing the superseded registration must not remove the live one.
+    first.dispose();
+    expect(getAgentBrowserScreenController('pane-3')).toBe(live);
+
+    second.dispose();
+    expect(getAgentBrowserScreenController('pane-3')).toBeNull();
+  });
+
+  it('tracks which surface has its modal open', () => {
+    let changes = 0;
+    const unsubscribe = subscribeAgentBrowserScreenModal(() => {
+      changes += 1;
+    });
+    expect(getOpenAgentBrowserScreenModalId()).toBeNull();
+
+    openAgentBrowserScreenModal('pane-9');
+    expect(getOpenAgentBrowserScreenModalId()).toBe('pane-9');
+    expect(changes).toBe(1);
+
+    // Re-opening the same id is a no-op (no spurious notification).
+    openAgentBrowserScreenModal('pane-9');
+    expect(changes).toBe(1);
+
+    closeAgentBrowserScreenModal();
+    expect(getOpenAgentBrowserScreenModalId()).toBeNull();
+    expect(changes).toBe(2);
+
+    unsubscribe();
+  });
+});
diff --git a/lib/src/components/wall/agent-browser-screen.ts b/lib/src/components/wall/agent-browser-screen.ts
new file mode 100644
index 00000000..8fa20551
--- /dev/null
+++ b/lib/src/components/wall/agent-browser-screen.ts
@@ -0,0 +1,180 @@
+/**
+ * Per-surface bridge between an agent-browser pane's body (AgentBrowserPanel)
+ * and its tab header (SurfacePaneHeader) + the screen modal, which are
+ * separate components for one pane (see docs/specs/dor-agent-browser.md →
+ * "Screen Indicator & Viewport").
+ *
+ * The panel owns the live state (viewport, pane size, sync) and the action
+ * (`runAgentBrowser`); the header and modal only read a snapshot and invoke
+ * actions. So the panel registers a controller keyed by its surface id; the
+ * header derives "this pane is an agent-browser surface" purely from the
+ * presence of a controller for `api.id`.
+ *
+ * Two stores, both consumed via useSyncExternalStore:
+ *   1. a surface-id-keyed controller registry (presence + per-controller
+ *      snapshot subscription), mirroring `terminal-lifecycle.ts`;
+ *   2. a single "which surface's screen modal is open" value, mirroring
+ *      `external-link-confirmation.ts`.
+ */
+import { useSyncExternalStore } from 'react';
+
+export type ScreenState = 'SYNCED' | 'SCALED';
+
+export interface ScreenSnapshot {
+  state: ScreenState;
+  /** The browser's live CSS viewport + inferred device pixel ratio. */
+  viewport: { w: number; h: number; dpr: number };
+  /** The pane's CSS pixel size (the canvas render area). */
+  paneCss: { w: number; h: number };
+  /** The Dormouse window's device pixel ratio. */
+  displayDpr: number;
+  syncEngaged: boolean;
+}
+
+export interface ScreenActions {
+  /** Follow the pane pixel-for-pixel (Dormouse-side behavior, not native). */
+  engageSync(): void;
+  /** Issue native `set device <name>` (bundles viewport + DPR + touch + UA). */
+  applyDevice(name: string): void;
+  /** Issue native `set viewport <w> <h> <dpr>`. */
+  applyViewport(w: number, h: number, dpr: number): void;
+  /** Open the screen modal for this surface. */
+  openModal(): void;
+}
+
+export interface ScreenController {
+  readonly id: string;
+  subscribe(listener: () => void): () => void;
+  snapshot(): ScreenSnapshot;
+  readonly actions: ScreenActions;
+  /** Whether the host can run `agentBrowserCommand` (false ⇒ resizes inert). */
+  readonly hostCapable: boolean;
+}
+
+interface ScreenEntry {
+  snapshot: ScreenSnapshot;
+  listeners: Set<() => void>;
+  controller: ScreenController;
+}
+
+const registry = new Map<string, ScreenEntry>();
+const presenceListeners = new Set<() => void>();
+
+function emitPresence(): void {
+  for (const listener of presenceListeners) listener();
+}
+
+export interface ScreenRegistration {
+  /** Push a new snapshot; notifies subscribers. Callers should pass a fresh
+   *  object only when something actually changed (the panel gates on flip /
+   *  dim change to avoid thrashing the header per frame). */
+  update(snapshot: ScreenSnapshot): void;
+  dispose(): void;
+}
+
+/** Register a surface's screen controller (panel mount). `actions` must be a
+ *  stable object whose methods read the panel's current closures (e.g. via
+ *  refs), so the controller never goes stale across panel re-renders. */
+export function registerAgentBrowserScreen(
+  id: string,
+  init: { snapshot: ScreenSnapshot; actions: ScreenActions; hostCapable: boolean },
+): ScreenRegistration {
+  const entry: ScreenEntry = {
+    snapshot: init.snapshot,
+    listeners: new Set(),
+    controller: {
+      id,
+      subscribe(listener) {
+        entry.listeners.add(listener);
+        return () => entry.listeners.delete(listener);
+      },
+      snapshot: () => entry.snapshot,
+      actions: init.actions,
+      hostCapable: init.hostCapable,
+    },
+  };
+  registry.set(id, entry);
+  emitPresence();
+  return {
+    update(snapshot) {
+      entry.snapshot = snapshot;
+      for (const listener of entry.listeners) listener();
+    },
+    dispose() {
+      if (registry.get(id) === entry) {
+        registry.delete(id);
+        emitPresence();
+      }
+    },
+  };
+}
+
+export function getAgentBrowserScreenController(id: string): ScreenController | null {
+  return registry.get(id)?.controller ?? null;
+}
+
+export function subscribeAgentBrowserScreenPresence(listener: () => void): () => void {
+  presenceListeners.add(listener);
+  return () => {
+    presenceListeners.delete(listener);
+  };
+}
+
+// --- screen modal open state (one at a time) ---
+
+let modalSurfaceId: string | null = null;
+const modalListeners = new Set<() => void>();
+
+function emitModalChange(): void {
+  for (const listener of modalListeners) listener();
+}
+
+export function openAgentBrowserScreenModal(id: string): void {
+  if (modalSurfaceId === id) return;
+  modalSurfaceId = id;
+  emitModalChange();
+}
+
+export function closeAgentBrowserScreenModal(): void {
+  if (modalSurfaceId === null) return;
+  modalSurfaceId = null;
+  emitModalChange();
+}
+
+export function getOpenAgentBrowserScreenModalId(): string | null {
+  return modalSurfaceId;
+}
+
+export function subscribeAgentBrowserScreenModal(listener: () => void): () => void {
+  modalListeners.add(listener);
+  return () => {
+    modalListeners.delete(listener);
+  };
+}
+
+// --- React hooks ---
+
+/** The controller for a surface, or null if it isn't an agent-browser surface.
+ *  Re-renders when controllers register/unregister (presence). */
+export function useAgentBrowserScreenController(id: string): ScreenController | null {
+  return useSyncExternalStore(
+    subscribeAgentBrowserScreenPresence,
+    () => getAgentBrowserScreenController(id),
+  );
+}
+
+const NO_SUBSCRIBE = () => () => {};
+
+/** A controller's live snapshot (SYNCED/SCALED + dims), or null. Re-renders on
+ *  every published snapshot for that controller. */
+export function useAgentBrowserScreenSnapshot(controller: ScreenController | null): ScreenSnapshot | null {
+  return useSyncExternalStore(
+    controller ? controller.subscribe : NO_SUBSCRIBE,
+    () => controller?.snapshot() ?? null,
+  );
+}
+
+/** The surface id whose screen modal is open, or null. */
+export function useOpenAgentBrowserScreenModalId(): string | null {
+  return useSyncExternalStore(subscribeAgentBrowserScreenModal, getOpenAgentBrowserScreenModalId);
+}
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index b67f9a6b..bbe0bd94 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -41,8 +41,9 @@ export interface AgentBrowserCommandResult {
 }
 
 /** Subcommands the host will run on the webview's behalf — this is a narrow
- * channel for tab actions and session teardown, not a general exec path. */
-export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'close'] as const;
+ * channel for tab actions, screen-mode resizing (`set viewport` / `set
+ * device`), and session teardown, not a general exec path. */
+export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'set', 'close'] as const;
 
 /** Native editing operations that the stream's input_keyboard path cannot
  * trigger on macOS (CDP drops the `commands` field — see
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index 9f0797df..5f668693 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -20,7 +20,7 @@ import * as net from 'net';
 import { spawn } from 'child_process';
 import { log } from './log';
 
-const ALLOWED_SUBCOMMANDS = new Set(['tab', 'close']);
+const ALLOWED_SUBCOMMANDS = new Set(['tab', 'set', 'close']);
 
 export interface AgentBrowserCommandResult {
   exitCode: number;

From 55bc7d32c4c3ce430ca8b5c5adc3a44e276e6709 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 08:13:02 -0700
Subject: [PATCH 15/25] agent-browser: display crisp HiDPI screenshots, paced
 by stream-frame pulses
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The stream's screencast is CSS-resolution only — Chromium's Page.startScreencast
captures in DIP and offers no deviceScaleFactor/scale knob (verified against the
CDP spec, crbug 781117, and probes: our own screencast at DSF=2 still returns 1x;
only Page.captureScreenshot honors DPR). So on Retina the screencast upscales to
mush regardless of who drives it. agent-browser's own `screenshot` command, by
contrast, is device-resolution (2560x1600 for a 1280x800@2 pane) and ~17fps via
the daemon's existing connection — no second CDP client, no session→Chrome
mapping, stays a viewer.

So: display device-resolution screenshots, and use screencast frames purely as
"page changed" pulses signalling when to grab a fresh one. Frames are no longer
decoded/drawn (just read for viewport + indicator), which also drops per-frame
decode work.

Backpressure (latest-only, self-throttling):
- at most one screenshot in flight; a pulse during a shot sets `dirty` (no
  queue) so bursts collapse to one follow-up, latest wins;
- a seq guard drops any out-of-order decode so a stale shot never paints over a
  newer one;
- next shot waits ~1.5x the measured (EWMA) capture time since the last start,
  so slow capture backs off (~2/3 duty), with a 50ms floor against tight loops;
- a static page produces no pulses, hence no shots and no cost.

Host capability `agentBrowserScreenshot` (vscode-ext): runs `screenshot` to a
reused temp file and returns the bytes base64. Falls back to rendering the
screencast frames where the host can't screenshot (Tauri).

Also bind the agent-browser adapter methods in the constructor — detached
`getPlatform().agentBrowserX` references drop `this` and throw on
requestResponse; this had to be fixed at three call sites already.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/components/wall/AgentBrowserPanel.tsx | 159 +++++++++++++++---
 lib/src/lib/platform/types.ts                 |  22 ++-
 lib/src/lib/platform/vscode-adapter.ts        |  21 ++-
 vscode-ext/src/agent-browser-host.ts          |  53 +++++-
 vscode-ext/src/message-router.ts              |  13 +-
 vscode-ext/src/message-types.ts               |   2 +
 6 files changed, 244 insertions(+), 26 deletions(-)

diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index fac06f61..53d7da9d 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -190,6 +190,128 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
   }, [session, binaryPath]);
   const runAgentBrowserRef = useRef(runAgentBrowser);
   runAgentBrowserRef.current = runAgentBrowser;
+  const sessionRef = useRef(session);
+  sessionRef.current = session;
+  const binaryPathRef = useRef(binaryPath);
+  binaryPathRef.current = binaryPath;
+
+  // --- display: crisp HiDPI screenshots, paced by stream-frame "pulses" ---
+  //
+  // The stream's screencast is CSS-resolution only (Chromium's
+  // Page.startScreencast ignores deviceScaleFactor — see the spec), so on a
+  // Retina display its frames upscale to mush. Instead we DISPLAY
+  // device-resolution screenshots (`agent-browser screenshot`, which honors the
+  // session DPR) and use the screencast frames purely as "the page changed"
+  // pulses telling us when to grab a fresh one.
+  //
+  // Backpressure (we only ever want the latest, and must slow down if capture
+  // can't keep up): at most one screenshot in flight; a pulse during a shot
+  // sets `dirty` (no queue — bursts collapse to one follow-up, latest wins);
+  // the next shot won't start until at least one shot-duration (adaptive EWMA)
+  // has passed since the last one began, so a slow capture self-throttles. A
+  // static page produces no pulses, so no shots and no cost.
+  const drawBitmap = useCallback((bitmap: ImageBitmap) => {
+    const canvas = canvasRef.current;
+    if (!canvas) {
+      bitmap.close();
+      return;
+    }
+    if (canvas.width !== bitmap.width) canvas.width = bitmap.width;
+    if (canvas.height !== bitmap.height) canvas.height = bitmap.height;
+    canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
+    bitmap.close();
+    setHasFrame(true);
+  }, []);
+  const drawBitmapRef = useRef(drawBitmap);
+  drawBitmapRef.current = drawBitmap;
+
+  const screenshotCapableRef = useRef(false);
+  screenshotCapableRef.current = !!getPlatform().agentBrowserScreenshot && !!session;
+
+  const screenshotLoop = useMemo(() => {
+    let inFlight = false;
+    let dirty = false;
+    let seq = 0;
+    let lastStart = 0;
+    let avgMs = 120;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let disposed = false;
+
+    const display = (dataBase64: string, mime: string, mySeq: number) => {
+      const binary = atob(dataBase64);
+      const bytes = new Uint8Array(binary.length);
+      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+      createImageBitmap(new Blob([bytes], { type: mime })).then((bitmap) => {
+        // A newer shot landed first (or we're gone) — drop this one.
+        if (disposed || mySeq !== seq) {
+          bitmap.close();
+          return;
+        }
+        drawBitmapRef.current(bitmap);
+      }).catch((err) => console.warn(`[agent-browser] screenshot decode failed:`, err));
+    };
+
+    const take = () => {
+      // Call through the adapter instance — a detached method reference drops
+      // `this` and throws on its internal `requestResponse`.
+      const platform = getPlatform();
+      const sess = sessionRef.current;
+      if (!platform.agentBrowserScreenshot || !sess) return;
+      inFlight = true;
+      dirty = false;
+      const mySeq = ++seq;
+      lastStart = performance.now();
+      platform.agentBrowserScreenshot(sess, { format: 'jpeg', quality: 85 }, binaryPathRef.current).then((res) => {
+        avgMs = avgMs * 0.6 + (performance.now() - lastStart) * 0.4;
+        inFlight = false;
+        if (res.ok && res.dataBase64) display(res.dataBase64, res.mime || 'image/jpeg', mySeq);
+        else console.warn('[agent-browser] screenshot failed:', res.error ?? '(no data)');
+        if (dirty) schedule();
+      }).catch((err) => {
+        console.warn('[agent-browser] screenshot error:', err);
+        inFlight = false;
+        if (dirty) schedule();
+      });
+    };
+
+    const schedule = () => {
+      if (disposed) return;
+      if (inFlight) {
+        dirty = true;
+        return;
+      }
+      // Space shots to ~1.5× the measured capture time since the last START:
+      // the slower capture gets, the more we back off (≈⅔ duty cycle), and the
+      // 50ms floor stops a fast/cached/error return from spinning a tight loop.
+      const floor = Math.max(50, avgMs * 1.5);
+      const wait = lastStart + floor - performance.now();
+      if (wait > 0) {
+        dirty = true;
+        if (timer === undefined) {
+          timer = setTimeout(() => {
+            timer = undefined;
+            if (dirty && !inFlight) take();
+          }, wait);
+        }
+        return;
+      }
+      take();
+    };
+
+    return {
+      pulse: () => {
+        if (disposed || !screenshotCapableRef.current) return;
+        dirty = true;
+        schedule();
+      },
+      dispose: () => {
+        disposed = true;
+        if (timer !== undefined) clearTimeout(timer);
+      },
+    };
+  }, []);
+
+  useEffect(() => () => screenshotLoop.dispose(), [screenshotLoop]);
 
   // --- screen indicator (SYNCED/SCALED) + sync-to-pane ---
   //
@@ -326,10 +448,9 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     let retryTimer: ReturnType<typeof setTimeout> | undefined;
     let failures = 0;
 
-    const drawFrame = (data: string, metadata?: { deviceWidth?: number; deviceHeight?: number }) => {
-      if (metadata?.deviceWidth && metadata?.deviceHeight) {
-        deviceRef.current = { width: metadata.deviceWidth, height: metadata.deviceHeight };
-      }
+    // Fallback only (hosts without the screenshot capability, e.g. Tauri):
+    // render the CSS-resolution screencast frame directly.
+    const drawScreencastFrame = (data: string) => {
       const seq = ++frameSeqRef.current;
       const binary = atob(data);
       const bytes = new Uint8Array(binary.length);
@@ -340,21 +461,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
           bitmap.close();
           return;
         }
-        const canvas = canvasRef.current;
-        if (!canvas) {
-          bitmap.close();
-          return;
-        }
-        if (canvas.width !== bitmap.width) canvas.width = bitmap.width;
-        if (canvas.height !== bitmap.height) canvas.height = bitmap.height;
-        canvas.getContext('2d')?.drawImage(bitmap, 0, 0);
-        bitmap.close();
-        setHasFrame(true);
-        // The frame just told us the browser's live viewport + DPR; reconcile
-        // sync and refresh the indicator. publishScreen self-gates, so this is
-        // cheap despite running every paint.
-        maybeDisengageSync();
-        publishScreen();
+        drawBitmapRef.current(bitmap);
       }).catch(() => {});
     };
 
@@ -367,7 +474,17 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
         return;
       }
       if (msg.type === 'frame' && typeof msg.data === 'string') {
-        drawFrame(msg.data, msg.metadata);
+        // The frame carries the browser's live viewport; update it, reconcile
+        // sync, and refresh the indicator (publishScreen self-gates). Then use
+        // the frame as a "page changed" pulse to grab a crisp screenshot — or,
+        // where the host can't screenshot, render the frame itself.
+        if (msg.metadata?.deviceWidth && msg.metadata?.deviceHeight) {
+          deviceRef.current = { width: msg.metadata.deviceWidth, height: msg.metadata.deviceHeight };
+        }
+        maybeDisengageSync();
+        publishScreen();
+        if (screenshotCapableRef.current) screenshotLoop.pulse();
+        else drawScreencastFrame(msg.data);
       } else if (msg.type === 'status') {
         setStatus({ connected: msg.connected === true, screencasting: msg.screencasting === true });
         if (msg.connected === false) setConnectionLost(true);
@@ -437,7 +554,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       wsRef.current = null;
       ws?.close();
     };
-  }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen]);
+  }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen, screenshotLoop]);
 
   // --- header title follows the active tab ---
 
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index bbe0bd94..a16375a4 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -42,8 +42,18 @@ export interface AgentBrowserCommandResult {
 
 /** Subcommands the host will run on the webview's behalf — this is a narrow
  * channel for tab actions, screen-mode resizing (`set viewport` / `set
- * device`), and session teardown, not a general exec path. */
-export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'set', 'close'] as const;
+ * device`), HiDPI frame capture (`screenshot`), and session teardown, not a
+ * general exec path. */
+export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'set', 'screenshot', 'close'] as const;
+
+export interface AgentBrowserScreenshotResult {
+  ok: boolean;
+  /** base64-encoded image bytes (no data: prefix); present iff ok. */
+  dataBase64?: string;
+  /** e.g. 'image/jpeg' | 'image/png'. */
+  mime?: string;
+  error?: string;
+}
 
 /** Native editing operations that the stream's input_keyboard path cannot
  * trigger on macOS (CDP drops the `commands` field — see
@@ -107,6 +117,14 @@ export interface PlatformAdapter {
   // for copy/cut, writes the result to the OS clipboard. Absent on hosts that
   // can't run the binary (degrades to plain key forwarding).
   agentBrowserEdit?(session: string, op: AgentBrowserEditOp, binaryPath?: string): Promise<AgentBrowserEditResult>;
+  // Captures a single device-resolution (HiDPI) frame via the user's
+  // agent-browser `screenshot` command and returns it base64-encoded. The
+  // stream's screencast is CSS-resolution only (a Chromium limitation —
+  // Page.startScreencast ignores deviceScaleFactor), so the panel displays
+  // these crisp screenshots instead, using stream frames only as change
+  // signals. Absent on hosts that can't run the binary (degrades to rendering
+  // the screencast frames directly).
+  agentBrowserScreenshot?(session: string, opts: { format?: 'jpeg' | 'png'; quality?: number }, binaryPath?: string): Promise<AgentBrowserScreenshotResult>;
   // The WebSocket URL for a session's stream port. Hosts whose webview origin
   // the agent-browser stream server rejects (VS Code) return a relay URL;
   // absent or null falls back to ws://127.0.0.1:<port>.
diff --git a/lib/src/lib/platform/vscode-adapter.ts b/lib/src/lib/platform/vscode-adapter.ts
index ce3a31e4..a77ff3f4 100644
--- a/lib/src/lib/platform/vscode-adapter.ts
+++ b/lib/src/lib/platform/vscode-adapter.ts
@@ -1,4 +1,4 @@
-import type { AgentBrowserCommandResult, AgentBrowserEditOp, AgentBrowserEditResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
+import type { AgentBrowserCommandResult, AgentBrowserEditOp, AgentBrowserEditResult, AgentBrowserScreenshotResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
 import { OPEN_PORT_TIMEOUT_MS } from './types';
 import { setDefaultShellOpts } from '../shell-defaults';
 import {
@@ -24,6 +24,15 @@ export class VSCodeAdapter implements PlatformAdapter {
   constructor() {
     this.vscode = acquireVsCodeApi();
 
+    // These get called through detached references in the agent-browser panel
+    // (e.g. `getPlatform().agentBrowserScreenshot`), which would otherwise drop
+    // `this` and throw on the internal `requestResponse`. Bind them once so any
+    // call style is safe.
+    this.agentBrowserCommand = this.agentBrowserCommand.bind(this);
+    this.agentBrowserEdit = this.agentBrowserEdit.bind(this);
+    this.agentBrowserScreenshot = this.agentBrowserScreenshot.bind(this);
+    this.getAgentBrowserStreamUrl = this.getAgentBrowserStreamUrl.bind(this);
+
     // Seed the default shell from the extension-injected global so that
     // the first terminal on startup (which spawns synchronously on Wall
     // mount) picks up the selected shell, not the platform default.
@@ -233,6 +242,16 @@ export class VSCodeAdapter implements PlatformAdapter {
     return result ?? { ok: false, error: 'agent-browser edit timed out' };
   }
 
+  async agentBrowserScreenshot(session: string, opts: { format?: 'jpeg' | 'png'; quality?: number }, binaryPath?: string): Promise<AgentBrowserScreenshotResult> {
+    const result = await this.requestResponse<AgentBrowserScreenshotResult>(
+      'agentBrowser:screenshot', 'agentBrowser:screenshotResult',
+      { session, format: opts.format, quality: opts.quality, binaryPath },
+      (msg) => ({ ok: msg.ok, dataBase64: msg.dataBase64, mime: msg.mime, error: msg.error }),
+      10000,
+    );
+    return result ?? { ok: false, error: 'agent-browser screenshot timed out' };
+  }
+
   getAgentBrowserStreamUrl(port: number): Promise<string | null> {
     // The agent-browser stream server rejects vscode-webview:// origins, so
     // the extension host relays the stream (see agent-browser-host.ts).
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index 5f668693..84614ad2 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -17,10 +17,13 @@
  */
 import * as vscode from 'vscode';
 import * as net from 'net';
+import * as os from 'os';
+import * as path from 'path';
+import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
 import { log } from './log';
 
-const ALLOWED_SUBCOMMANDS = new Set(['tab', 'set', 'close']);
+const ALLOWED_SUBCOMMANDS = new Set(['tab', 'set', 'screenshot', 'close']);
 
 export interface AgentBrowserCommandResult {
   exitCode: number;
@@ -36,6 +39,13 @@ export interface AgentBrowserEditResult {
   error?: string;
 }
 
+export interface AgentBrowserScreenshotResult {
+  ok: boolean;
+  dataBase64?: string;
+  mime?: string;
+  error?: string;
+}
+
 // The host owns the exact JS for each editing op — the webview only selects a
 // name, so this never becomes an arbitrary-eval channel. copy/cut return the
 // selected text; selectAll returns ''. Inputs/textareas use selection ranges;
@@ -90,6 +100,47 @@ export async function runAgentBrowserEdit(session: string, op: AgentBrowserEditO
   return { ok: true, text };
 }
 
+// Reused per session so we don't litter tmp with one file per frame; the panel
+// guarantees one screenshot in flight per surface, so overwriting is safe.
+function screenshotPath(session: string, ext: string): string {
+  const safe = session.replace(/[^A-Za-z0-9._-]/g, '_');
+  return path.join(os.tmpdir(), `dormouse-ab-shot-${safe}.${ext}`);
+}
+
+// Capture one device-resolution frame via the user's agent-browser `screenshot`
+// command (which honors the session's viewport/DPR, unlike the CSS-resolution
+// screencast) and return it base64-encoded. agent-browser writes a file and
+// reports the path; we read it back and hand the bytes to the webview.
+export async function runAgentBrowserScreenshot(
+  session: string,
+  opts: { format?: 'jpeg' | 'png'; quality?: number },
+  binaryPath?: string,
+): Promise<AgentBrowserScreenshotResult> {
+  if (typeof session !== 'string' || !session) {
+    return { ok: false, error: 'session is required' };
+  }
+  const format = opts.format === 'png' ? 'png' : 'jpeg';
+  const ext = format === 'png' ? 'png' : 'jpg';
+  const out = screenshotPath(session, ext);
+  const args = ['--session', session, 'screenshot', out, '--screenshot-format', format];
+  if (format === 'jpeg') {
+    const q = Number.isFinite(opts.quality) ? Math.min(100, Math.max(1, Math.round(opts.quality as number))) : 85;
+    args.push('--screenshot-quality', String(q));
+  }
+  const result = await runWithBinaryFallback(args, binaryPath);
+  if (result.exitCode !== 0) {
+    log.info(`[agent-browser] screenshot failed (exit ${result.exitCode}): ${result.stderr.trim() || result.stdout.trim()}`);
+    return { ok: false, error: result.stderr.trim() || `screenshot exited ${result.exitCode}` };
+  }
+  try {
+    const bytes = await fs.readFile(out);
+    return { ok: true, dataBase64: bytes.toString('base64'), mime: format === 'png' ? 'image/png' : 'image/jpeg' };
+  } catch (err) {
+    log.info(`[agent-browser] screenshot read failed: ${err instanceof Error ? err.message : String(err)}`);
+    return { ok: false, error: `could not read screenshot file: ${err instanceof Error ? err.message : String(err)}` };
+  }
+}
+
 // The extension host's PATH is often the GUI login PATH (no nvm/volta shims),
 // so prefer the absolute path `dor ab` resolved in the user's terminal; fall
 // through on ENOENT in case it has gone stale.
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index bcdc5635..25f50820 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -13,7 +13,7 @@ import type { TerminalSemanticEvent } from '../../lib/src/lib/terminal-state';
 import type { PersistedSession } from '../../lib/src/lib/session-types';
 import type { WebviewMessage, ExtensionMessage } from './message-types';
 import type { DorControlRequest } from './pty-manager';
-import { ensureStreamRelayPort, runAgentBrowserCommand, runAgentBrowserEdit } from './agent-browser-host';
+import { ensureStreamRelayPort, runAgentBrowserCommand, runAgentBrowserEdit, runAgentBrowserScreenshot } from './agent-browser-host';
 import { log } from './log';
 
 const clipboardOps = require('../../lib/clipboard-ops.cjs') as {
@@ -374,6 +374,17 @@ export function attachRouter(
           } satisfies ExtensionMessage);
         });
         break;
+      case 'agentBrowser:screenshot':
+        runAgentBrowserScreenshot(
+          msg.session,
+          { format: msg.format, quality: msg.quality },
+          typeof msg.binaryPath === 'string' ? msg.binaryPath : undefined,
+        ).then((result) => {
+          webview.postMessage({
+            type: 'agentBrowser:screenshotResult', requestId: msg.requestId, ...result,
+          } satisfies ExtensionMessage);
+        });
+        break;
       case 'agentBrowser:getStreamUrl': {
         const streamPort = Number.isInteger(msg.port) && msg.port > 0 && msg.port <= 65535 ? msg.port : null;
         if (!streamPort) {
diff --git a/vscode-ext/src/message-types.ts b/vscode-ext/src/message-types.ts
index ac59c640..01391ec3 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -20,6 +20,7 @@ export type WebviewMessage =
   | { type: 'dormouse:runWorkbenchCommand'; command: VSCodeWorkbenchCommand }
   | { type: 'agentBrowser:command'; session: string; args: string[]; binaryPath?: string; requestId: string }
   | { type: 'agentBrowser:edit'; session: string; op: 'selectAll' | 'copy' | 'cut'; binaryPath?: string; requestId: string }
+  | { type: 'agentBrowser:screenshot'; session: string; format?: 'jpeg' | 'png'; quality?: number; binaryPath?: string; requestId: string }
   | { type: 'agentBrowser:getStreamUrl'; port: number; requestId: string }
   | { type: 'dormouse:init' }
   | { type: 'dormouse:saveState'; state: unknown }
@@ -59,6 +60,7 @@ export type ExtensionMessage =
   | { type: 'clipboard:image'; path: string | null; requestId: string }
   | { type: 'agentBrowser:commandResult'; requestId: string; exitCode: number; stdout: string; stderr: string }
   | { type: 'agentBrowser:editResult'; requestId: string; ok: boolean; text?: string; error?: string }
+  | { type: 'agentBrowser:screenshotResult'; requestId: string; ok: boolean; dataBase64?: string; mime?: string; error?: string }
   | { type: 'agentBrowser:streamUrl'; requestId: string; url: string | null }
   | {
       type: 'dormouse:newTerminal';

From e5f10775b091ee1b98c43750fc2087c6506ecd5e Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 11:22:01 -0700
Subject: [PATCH 16/25] spec: headed pop-out + document the shipped
 HiDPI-screenshot pipeline
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Spec (docs/specs/dor-agent-browser.md):
- New "Headed Pop-Out" section. Pop-out relaunches a surface's browser headed
  as a real OS window the user drives directly; the pane becomes a clean
  placeholder (no screencast of the headed window — sidesteps headed-screencast
  / off-screen-occlusion / window-tracking). GUI-only, randomKillChar()-
  confirmed. Identity-preserving relaunch keeps the session name so `dor ab`
  keeps targeting it. v1 carries ordered tab URLs only (profile/login
  persistence is a named follow-up spike). Best-effort positioning over the
  pane rect, center-on-monitor fallback (always in VS Code, always on Wayland).
  No control tab: the headed window ending by any gesture auto-reverts to a
  headless surface reopening the last non-empty tab list; only `dor kill` tears
  down. Platform-gated capability matrix (Tauri-first; VS Code can't position;
  Wayland can't self-position; web hides it).
- Corrected two now-stale parts to match shipped code: "Frames (out)" now
  documents the screenshot-pulse pipeline (was screencast-to-canvas), and the
  Host capabilities list gains agentBrowserScreenshot/agentBrowserEdit + a
  planned pop-out entry.

Plan (DOR_AGENT_BROWSER.md):
- Phase 9 (DONE) records the HiDPI screenshot streaming as shipped.
- Phase 10 sequences headed pop-out leaf-up (host capability, affordance+confirm,
  relaunch+reopen+position, placeholder, lifecycle, cross-platform), plus a
  profile-persistence spike.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md            | 102 +++++++++++++++++
 docs/specs/dor-agent-browser.md | 194 ++++++++++++++++++++++++++++++--
 2 files changed, 284 insertions(+), 12 deletions(-)

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
index eb348152..7d486ad8 100644
--- a/DOR_AGENT_BROWSER.md
+++ b/DOR_AGENT_BROWSER.md
@@ -386,3 +386,105 @@ Leaf-up, each step independently verifiable:
   CLI and GUI stay consistent.
 - `syncEngaged` persists; standalone degrades gracefully.
 - Spec updated for the two decisions (create-default, device-dims).
+
+---
+
+## Phase 9 — HiDPI screenshot streaming (DONE)
+
+**Spec:** "Channels → Frames (out)". Shipped (commit `55bc7d3`).
+
+The stream's screencast is CSS-resolution only — Chromium's
+`Page.startScreencast` ignores `deviceScaleFactor` (verified against the CDP
+spec, crbug 781117, and probes incl. our own CDP screencast + the proposed
+`maxWidth=css*dpr` snippet — all 1×; only `Page.captureScreenshot` honors DPR).
+So the panel **displays device-resolution screenshots** and uses screencast
+frames purely as "page changed" pulses.
+
+- Host capability `agentBrowserScreenshot(session, {format, quality})` runs
+  `agent-browser screenshot` to a temp file and returns the bytes base64
+  (`vscode-ext/src/agent-browser-host.ts`, `message-router.ts`,
+  `message-types.ts`, `vscode-adapter.ts`, `platform/types.ts`).
+- `AgentBrowserPanel` no longer decodes/draws stream frames; each is a pulse.
+  Backpressure: one shot in flight, dirty-coalesce (latest wins), seq-guard
+  against out-of-order decodes, adaptive ~1.5×-capture-time pacing (≈⅔ duty,
+  50ms floor). Static page ⇒ no pulses ⇒ no cost. ~17fps JPEG q85 device-res.
+- Fallback to rendering screencast frames where `agentBrowserScreenshot` is
+  absent (Tauri).
+- Adapter methods bound in the constructor — detached `getPlatform().agentBrowserX`
+  references drop `this` and throw on `requestResponse` (bit us 3×).
+
+## Phase 10 — Headed pop-out (planned)
+
+**Spec:** "Headed Pop-Out". A header affordance that relaunches the surface's
+browser **headed** as a real OS window the user drives directly; the Dormouse
+pane becomes a clean placeholder. GUI-only, `randomKillChar()`-confirmed,
+platform-gated. **Build leaf-up; this is desktop-only (Tauri-first), degraded in
+VS Code, hidden on web.**
+
+### 10pre — Profile-persistence spike (prerequisite-ish)
+
+- Without it, pop-out drops cookies/login (ephemeral temp profile), so it's
+  frustrating for authenticated sites. Spike a stable per-session user-data-dir
+  (or `agent-browser state save`/`load`) so logins survive the relaunch.
+- Decoupled from the v1 ship (v1 = URLs-only), but the first thing that makes
+  pop-out genuinely useful. Land before or shortly after 10a–10f.
+
+### 10a — Host capability: headed relaunch + window control
+
+- New optional `PlatformAdapter` methods (mirror `agentBrowserScreenshot`):
+  relaunch a session **headed** with window-position args, **raise** a window
+  (by session/process), and resolve the **pane→screen rectangle** (Tauri only).
+- Allowlist the headed `open`/launch path; degrade where unimplemented.
+- **Verify:** from a terminal/host call, a session reopens headed as a window.
+
+### 10b — Affordance + confirm
+
+- Pop-out arrow in `SurfacePaneHeader` action cluster, agent-browser surfaces
+  only, gated on host capability (hidden on web). Click → `randomKillChar()`
+  overlay (mirror `KillConfirm`/`KillConfirmOverlay`).
+- **Verify:** chip shows only on browser surfaces with a capable host; confirm
+  overlay gates the action.
+
+### 10c — Relaunch headed + reopen tabs + position
+
+- Capture the ordered tab URL list (+ active) from the live `tabs` stream.
+- Keep the session name; relaunch headed; reopen each URL in order, focus the
+  active one. Best-effort position over the pane rect; **center on monitor**
+  when coords are unavailable (always VS Code, always Wayland).
+- **Verify:** pop-out reopens all tabs in order; lands over the pane (Tauri/mac)
+  or centered (VS Code).
+
+### 10d — Pane placeholder mode
+
+- Clean placeholder copy; **Bring to front** (host raise) + **Pop back in**
+  (closes the window → 10e revert). Stream stays connected for `tabs`/`status`
+  only; frame display / screenshots / input / chip / tab strip inert.
+- **Verify:** popped-out pane shows placeholder; bring-to-front raises; pop back
+  in returns to headless.
+
+### 10e — Lifecycle
+
+- Headed window ends (any gesture) → **auto-revert**: relaunch headless, resume
+  streaming, reopen the **last non-empty tab list**. Decoupled from teardown.
+- `dor kill` / pane `×` → the only teardown (close window + session).
+- App quit → clean up headed windows (no orphans).
+- **Verify:** close window (1 tab) → that tab returns headless; close 3-tab
+  window → 3 return; `dor kill` ends it; quitting leaves no stray Chrome.
+
+### 10f — Cross-platform gating
+
+- VS Code: spawns headed but can't position → center; bring-to-front best-effort.
+- Wayland: center, raise may be unavailable. Windows: per-monitor/fractional DPI
+  math for pane→window. Web: affordance hidden.
+- **Verify (needs real hardware):** Windows high-DPI placement; a Wayland session
+  centers and doesn't crash; macOS positions over the pane.
+
+### Definition of done (Phase 10)
+
+- Pop-out relaunches headed, reopens tabs in order, positions best-effort.
+- Pane is a clean placeholder with bring-to-front + pop-back-in.
+- Any window-end auto-reverts to headless (last non-empty tabs); only `dor kill`
+  tears down; no orphan windows on quit.
+- Confirmed via `randomKillChar()`; GUI-only; platform-gated with graceful
+  degradation.
+- (Stretch) profile persistence so logins survive the relaunch.
diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 6919d6d9..611f1d6e 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -272,24 +272,184 @@ Surface lifetime and browser lifetime are bound, both directions:
   close`).
 - **Session dies externally → tear down the surface.** If the browser exits
   (crash, or a plain `agent-browser close` elsewhere), the stream reports
-  `connected: false`; the Wall removes or placeholders the surface.
+  `connected: false`; the Wall removes or placeholders the surface. (Exception:
+  while a surface is **popped out**, see below, the headed window closing is
+  expected and reverts the pane rather than tearing it down.)
+
+## Headed Pop-Out
+
+The headless + streamed-screenshot surface is the default everywhere: it is
+crisp, deterministic, and **uniformly portable** (no OS window, no positioning,
+no DPI/Wayland concerns; works identically on win/mac/linux, in VS Code, and on
+web). But streaming can't match a *real* window for hands-on interactivity —
+IME composition, file uploads, smooth scrolling, native editing chords,
+extensions, DevTools, native dialogs. **Pop-out** is the escape hatch: it
+relaunches the surface's browser **headed**, as an ordinary OS window the user
+drives directly. It is a deliberate, occasional mode, not the rendering path.
+
+Because Chrome's headed/headless choice is fixed at process launch (no live
+toggle — verified), pop-out is a **relaunch**, not a move. The design embraces
+that: the user interacts with the headed window natively, so Dormouse does
+**not** screencast it — the in-Dormouse pane becomes a stub. This sidesteps the
+headed-screencast, off-screen-occlusion, and window-tracking problems entirely.
+
+### Affordance
+
+A pop-out control (arrow icon) sits in the surface header's action cluster, on
+**agent-browser surfaces only** and only where the host can spawn a headed
+window (gated on a host capability; see below). Web hosts, which cannot spawn OS
+windows, omit it. Pop-out is **GUI-only** — like *Sync to pane*, it is a
+Dormouse behavior with no `agent-browser` equivalent, so it gets no `dor ab`
+verb.
+
+Because pop-out is destructive of live state (it relaunches the browser and, in
+v1, drops scroll/DOM/login — see below), the click is **confirmed the same way
+as kill**: a `randomKillChar()`-style overlay requires typing the shown
+character, so a stray click can't discard your live page (mirror `KillConfirm` /
+`KillConfirmOverlay`).
+
+### Identity-preserving relaunch
+
+Pop-out **keeps the session name** (`dormouse.<workspaceId>.<key>`); only the
+underlying Chrome process changes (now headed, new stream port). The
+key→`{session, surfaceId}` registry is untouched, so **`dor ab --key …`
+continues to drive the same surface transparently** — navigation and commands
+now land in the headed window. `dor ab open <url>` still navigates the active
+tab; it does not spawn one.
+
+### State carried across the relaunch
+
+Pop-out preserves **what it can**, and is honest that it is a *reload*, not a
+continuation:
+
+- **v1: the ordered list of tab URLs + which was active.** On relaunch the
+  headed window reopens each URL as a tab in the same order and focuses the
+  previously-active one.
+- **Lost (v1):** live DOM, scroll position, form inputs, `sessionStorage`,
+  in-memory JS/SPA route state — and, because agent-browser launches each Chrome
+  with an ephemeral temp profile, **cookies/login**. So a popped-out window
+  starts logged out unless/until profile persistence lands.
+- **Planned (profile spike):** persist cookies/storage via a stable
+  user-data-dir (or `agent-browser state save`/`load`) so logins survive the
+  relaunch — without it, pop-out is frustrating for authenticated sites, so this
+  is a known and wanted follow-up, not a maybe. v1 still ships URLs-only.
+
+### The pane while popped out
+
+The pane **stays open** and switches to a **clean placeholder** (no dimmed last
+frame):
+
+- Copy indicating the surface is open in a separate window.
+- A **"Bring to front"** action that best-effort raises/focuses the headed
+  window (may be unavailable on some platforms — see cross-platform).
+- A **"Pop back in"** action that closes the headed window, which triggers the
+  auto-revert below (relaunch headless, resume streaming, reopen the tabs) —
+  i.e. it is the same path as the user dismissing the window themselves.
+- Frame display, screenshot capture, input forwarding, the SYNCED/SCALED chip,
+  and the tab strip are all inert (you interact with the real window). But the
+  **stream WS stays connected** to keep observing `tabs`/`status`: we track the
+  **last non-empty tab list** (what to reopen on revert) and watch for
+  `connected: false` (the window ended).
+
+### Positioning
+
+Placement is **best-effort, one-time, and does not follow** (a separate OS
+window won't track the pane after spawn):
+
+- If the host can resolve the pane's screen rectangle, place the headed window's
+  **content area** over it (accounting for window chrome and the target
+  display's DPR).
+- Otherwise — **always in VS Code** (the sandboxed webview cannot read screen
+  coordinates) and **on Wayland** (clients cannot self-position) — fall back to
+  **centering on the current monitor**.
+
+### Window identity
+
+There is **no control tab** (it would only have been needed to distinguish the
+two close gestures, which the unified lifecycle below removes). Window identity
+is therefore best-effort: *Bring to front* raises the OS window via the host
+(by the session's process), not via an anchor tab. A Dormouse-flavored window
+title isn't guaranteed — a Chrome window's title follows its active tab — so it's
+a nice-to-have, not relied upon.
+
+### Lifecycle (pop-out)
+
+The headed window ending and the surface being disposed are **decoupled**: the
+only thing that tears a surface down is Dormouse's own kill. Everything else just
+moves the surface between headed and headless.
+
+- **The headed window ends** — by any gesture (window `×` / `⌘⇧W`, or closing
+  the last tab; without a control tab these are indistinguishable, and they
+  behave the same) → **auto-revert**: relaunch the session headless, resume
+  streaming in the pane, and reopen the **last non-empty tab list** in order. So
+  closing the final tab reopens *that* tab back in Dormouse; closing a
+  three-tab window reopens those three. The surface is never lost this way.
+  (The pane's *Pop back in* button takes this same path by closing the window
+  for you.)
+- **Kill the Dormouse pane / `dor kill`** → the only teardown: close the headed
+  window + session (the normal surface↔session binding). This is the way to
+  actually be done with the browser.
+- **Dormouse/editor quits** → headed windows must be cleaned up; no orphans
+  (agent-browser's daemon outlives the editor, so shutdown closes managed
+  sessions explicitly).
+
+### Host capability & cross-platform
+
+Pop-out needs host support beyond `agentBrowserCommand`: relaunching a session
+**headed** with window-position args, optionally **raising** a window, and
+optionally resolving the **pane→screen rectangle**. As with other host
+capabilities, adapters degrade rather than fail:
+
+| Host / platform | Spawn headed | Position over pane | Bring to front |
+| --- | --- | --- | --- |
+| Standalone (Tauri), macOS / Windows / Linux-X11 | yes | yes (best-effort) | yes |
+| Standalone, Linux-**Wayland** | yes | **no** → center | best-effort / maybe no |
+| VS Code (any OS) | yes | **no** → center (webview can't read screen coords) | best-effort |
+| Web | **no** (affordance hidden) | — | — |
+
+Windows adds per-monitor / fractional-DPI math for the pane→window mapping;
+macOS Retina works as tested; Wayland cannot self-position or reliably raise, so
+it always centers. The feature is therefore a **platform-gated enhancement**,
+never load-bearing — the streamed surface remains the portable baseline on every
+target.
 
 ## Channels
 
 Mirrors the validated `~/Documents/dev/agent-proto` prototype.
 
-### Frames (out)
+### Frames (out) — screenshot display, screencast-paced
 
-The webview connects directly to the session stream WebSocket and renders frames
-to a `<canvas>`:
+The stream's screencast is **CSS-resolution only**: Chromium's
+`Page.startScreencast` captures in DIP and has no deviceScaleFactor/scale knob,
+so on a HiDPI display its frames upscale to mush. (Verified against the CDP spec
+— screencast metadata is defined in DIP, `maxWidth/maxHeight` only *downscale* —
+and by probe: our own screencast at `deviceScaleFactor: 2` still returns 1×;
+only `Page.captureScreenshot` honors DPR. This is a Chromium limitation, not
+agent-browser's, so owning the CDP connection wouldn't change it.)
+
+So Dormouse **displays device-resolution screenshots** and uses the screencast
+purely as a **change signal**:
 
 - Port discovery: `agent-browser --session <s> stream status --json` →
   `{ "port": <n>, ... }` ⇒ `ws://127.0.0.1:<n>`. Streaming is always enabled;
   `AGENT_BROWSER_STREAM_PORT` pins a port.
-- Frame message: `{ "type": "frame", "data": "<base64 jpeg>", "metadata": {
-  deviceWidth, deviceHeight, pageScaleFactor, scrollOffsetX, scrollOffsetY, … } }`.
-  Decode → `drawImage`; map pointer coordinates through `metadata` device size vs
-  canvas size.
+- Each `{ "type": "frame", "metadata": { deviceWidth, deviceHeight, … } }`
+  message is a "page changed" **pulse** (and updates the live viewport for the
+  indicator and input mapping). The frame's own JPEG is **not** decoded/drawn.
+- On a pulse, capture a crisp frame via the host's `agentBrowserScreenshot`
+  (`agent-browser screenshot`, which honors the session viewport/DPR — device
+  resolution, e.g. 2560×1600 for a 1280×800@2 pane) and `drawImage` it to the
+  canvas.
+- **Backpressure (latest-only, self-throttling):** at most one screenshot in
+  flight; a pulse during a shot sets a `dirty` flag (no queue — bursts collapse
+  to one follow-up, latest wins); a sequence guard drops out-of-order decodes;
+  the next shot waits ~1.5× the measured (EWMA) capture time since the last
+  start (≈⅔ duty), with a floor against tight loops. A static page produces no
+  pulses, hence no shots and no cost. (~17 fps JPEG q85 on an M-series Mac.)
+- **Fallback:** on hosts without `agentBrowserScreenshot` (e.g. Tauri today),
+  render the CSS-resolution screencast frame directly instead.
+- Pointer coordinates map through the pane rect vs `metadata` device size
+  (aspect-preserving; independent of the screenshot's pixel size).
 
 ### Input (in)
 
@@ -368,16 +528,26 @@ host on the webview's behalf (a webview cannot spawn processes; see
 
 ### Host capabilities
 
-Two narrow host capabilities back the surface, both optional on
-`PlatformAdapter` so hosts degrade gracefully:
+Narrow host capabilities back the surface, all optional on `PlatformAdapter` so
+hosts degrade gracefully:
 
 - **`agentBrowserCommand(session, args)`** — runs the user's agent-browser
   binary for tab actions (`tab <n>`, `tab close`, `tab new`), screen-mode
   resizing (`set viewport`, `set device`), and lifecycle (`close`). The host
-  validates `args[0]` against an allowlist (`tab`, `set`, `close`); this is not
-  a general exec channel.
+  validates `args[0]` against an allowlist (`tab`, `set`, `screenshot`,
+  `close`); this is not a general exec channel.
+- **`agentBrowserScreenshot(session, { format, quality })`** — captures one
+  device-resolution frame via `agent-browser screenshot` (which honors the
+  session DPR, unlike the screencast) and returns it base64. Drives the crisp
+  display path; absent ⇒ the panel falls back to rendering screencast frames.
+- **`agentBrowserEdit(session, op)`** — host-owned `eval` for the macOS editing
+  chords (select-all/copy/cut) the stream input path can't dispatch.
 - **`getAgentBrowserStreamUrl(port)`** — returns the WebSocket URL the webview
   should use for the session stream (see CSP/origin below).
+- **(Planned) headed pop-out** — relaunch a session headed with window-position
+  args, raise a window, and resolve the pane→screen rectangle (see Headed
+  Pop-Out). Platform-gated; degrades to center-on-monitor where positioning
+  isn't possible.
 
 ## VS Code Webview CSP and Stream Origin
 

From cabab63aaf113edaabd25eded067630ef9ea07b3 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 11:44:33 -0700
Subject: [PATCH 17/25] spec: describe the built surface; move pop-out to
 Future Expansions

The spec was accreting planned work inline. Restructure it into a concise
description of what's actually built (Delegation, --key, mapping, tabs, screen
indicator, lifecycle, channels, touchpoints, host capabilities, CSP), with a
clearly-separated "Future Expansions" section at the bottom holding the Headed
Pop-Out design and other planned items (profile persistence, CLI sync verb,
undo/redo). Tightened the completed-feature prose along the way.

Slim DOR_AGENT_BROWSER.md to match: the built phases now live in the spec, so
the plan doc drops the completed-phase log and keeps only the forward build
sequence (Phase 10 pop-out + profile spike) plus the dev loop.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md            | 433 ++------------------------------
 docs/specs/dor-agent-browser.md | 382 ++++++++++++----------------
 2 files changed, 178 insertions(+), 637 deletions(-)

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
index 7d486ad8..d3261724 100644
--- a/DOR_AGENT_BROWSER.md
+++ b/DOR_AGENT_BROWSER.md
@@ -1,425 +1,31 @@
 # DOR_AGENT_BROWSER — Implementation Plan
 
-Implementation plan for the `dor agent-browser` / `dor ab` surface.
+The `dor agent-browser` / `dor ab` surface is **built and shipped**. Its design
+and current behavior are described in
+[`docs/specs/dor-agent-browser.md`](docs/specs/dor-agent-browser.md) — that spec
+is the source of truth. This doc tracks only the **remaining build work**; the
+spec's "Future Expansions" section is the design for it.
 
-## Implementation status (2026-06-12)
+## Dev loop
 
-All seven phases are built; see the spike outcome under Phase 4 for the three
-design changes the build forced (dot-separated session names, stream-native
-input replacing the CDP proxy, VS Code origin-stripping relay). Verified so
-far: CLI phases headless (`dor/test`), stream input + relay live against
-agent-browser 0.27.0. Outstanding:
-
-- **In-app dogfood pass** (VS Code): extension is built and installed; needs a
-  window reload and a `dor ab open` walk-through of frames/input/tabs/kill.
-- **Standalone (Tauri) gaps:** frames + input work (its origin is allowed, so
-  it connects to the stream directly), but `agentBrowserCommand` is not
-  implemented in the Tauri adapter — tab switch/close, popup auto-focus, and
-  kill→session-close are inert there until the sidecar grows that capability.
-- **Favicons** are omitted from the tab strip (webview CSP blocks external
-  images); spec updated.
-
-**Design spec (read first):** [`docs/specs/dor-agent-browser.md`](docs/specs/dor-agent-browser.md).
-This plan does not restate the design — it sequences the build and says how to
-verify each step. When the plan and the spec disagree, the spec wins; if the
-build forces a design change, update the spec in the same commit.
-
-**Reference prototype:** `~/Documents/dev/agent-proto` (`serve.mjs` + `viewer.html`).
-A working end-to-end viewer: stream-WS frames + CDP-proxied input + active-target
-re-resolution. Treat it as the source of truth for the channel mechanics.
-
----
-
-## Locked decisions (do not relitigate)
-
-These are settled in the spec; the implementation follows them:
-
-- Viewer client, **not a fork**. Resolve the user's `agent-browser` on `PATH`
-  (`DORMOUSE_AGENT_BROWSER_BIN` override); never bundle it.
-- `--key <name>` is primary, workspace-scoped, default `default`; maps to session
-  `dormouse/<workspaceId>/<key>` (`workspaceId` hardcoded `1`). Mutually exclusive
-  with raw `--session`.
-- Session is the join key; **1:1 with an auto-managed surface**; no 1:many.
-- Surface kill ↔ session close, both directions.
-- One session = one surface regardless of tab count; tabs live **inside** the
-  surface (integrated vs multi-tab strip), orthogonal to minimize.
-- Three delegated channels: frames (stream WS), input (CDP via host proxy — but
-  see the spike below), tabs (`tab list/<n>/close`).
-
----
-
-## Dev loop & prerequisites
-
-- `agent-browser` installed on PATH (`agent-browser --version`; tested against
-  `0.27.0`). `npm i -g agent-browser` if missing.
+- `agent-browser` on `PATH` (`agent-browser --version`; tested against `0.27.0`).
 - CLI-only iteration: `cd dor && pnpm build && node --test test/cli-output.test.mjs`.
-- Full app: `pnpm build:vscode` then `pnpm --filter dormouse dogfood`, reload the
-  VS Code window. (`dogfood:vscode` does **not** exist at the repo root.)
-- Manual channel checks against a live session:
-  ```
-  agent-browser --session dormouse/1/default open http://localhost:5173
-  agent-browser --session dormouse/1/default stream status --json   # → { port }
-  agent-browser --session dormouse/1/default tab list --json
-  ```
-
----
-
-## Architecture at a glance
-
-```
-dor ab <args>  ──(resolve --key→session, exec)──▶  agent-browser  (user's binary)
-      │
-      └─(control: surface.agentBrowser {key,session,wsPort})─▶ Wall registry → surface
-                                                                      │
-AgentBrowserPanel (webview):                                          │
-  • frames:  ws://127.0.0.1:<port>  ──── direct ───▶  canvas          │
-  • input:   pointer/key ─▶ host (CDP proxy) ─▶ Chrome   ◀── see spike ┘
-  • tabs:    tab list/<n>/close  (delegated via dor ab passthrough or control)
-```
-
-The host CDP proxy is the only genuinely new long-lived plumbing. The webview
-**cannot** open a CDP WebSocket directly (Chrome refuses CDP from non-localhost
-origins), so a host process (sidecar / `pty-host`) must hold the CDP socket and
-forward input. **Unless the spike below removes that need.**
-
----
-
-## ⚠️ Spike first: can input ride the stream WS directly?
-
-The prototype proxies input through CDP. But agent-browser's stream WS protocol
-documents **native input messages** (`input_mouse`, `input_keyboard`,
-`input_touch`). If those work, the webview can send input over the **same
-ws://localhost socket it already opened for frames** — eliminating the host CDP
-proxy entirely and collapsing the hardest phase.
-
-**Spike (do this before Phase 4):**
-1. `agent-browser --session s open <url>` + `stream status --json` for the port.
-2. Open that WS from a throwaway Node script; send
-   `{"type":"input_mouse","eventType":"mousePressed","x":100,"y":200,"button":"left","clickCount":1}`
-   then `mouseReleased`; confirm the page reacts (e.g. a button click).
-3. Repeat for `input_keyboard` (keyDown/keyUp + a focused field).
-
-**Decision:**
-- **Works** → use stream-native input, skip the host CDP proxy, and **update the
-  spec's "Input (in)" section** to match. Phase 4 shrinks to "send input_* over
-  the frame socket."
-- **Insufficient** (missing key codes, IME, uploads, modifier handling) → keep the
-  CDP-via-host-proxy design as spec'd and port `serve.mjs`'s approach.
-
-Record the outcome at the top of Phase 4 before building it.
-
-**SPIKE OUTCOME (2026-06-12, agent-browser 0.27.0): stream-native input WORKS.**
-Click, typing (with `text`), and `mouseWheel` scrolling all confirmed against a
-live session. The CDP host proxy is dead. Additional discoveries:
-- Session names must not contain `/` (daemon dies on startup — the name becomes
-  a socket path). Managed sessions are `dormouse.<workspaceId>.<key>`; spec
-  updated.
-- The stream WS pushes `status` and `tabs` messages, so the tab strip needs no
-  polling; only tab *actions* need the CLI.
-- The stream WS **rejects upgrades with a non-localhost `Origin`** (403 for
-  `vscode-webview://…`; `tauri://localhost` and absent Origin are allowed). VS
-  Code needs a loopback origin-stripping TCP relay in the extension host
-  (Phase 7); standalone connects directly. Spec updated.
+- Lib unit tests: `cd lib && npx vitest run`.
+- Full app: `pnpm build:vscode` then `pnpm --filter dormouse dogfood`, then reload
+  the VS Code window. Standalone: smoke-test the Tauri build separately.
+- Channel behaviors (frames/input/tabs/screenshots) are mostly manual against a
+  live `agent-browser`; the probes under `~/.agent-browser/tmp/probe-*.mjs` are
+  the harness for protocol questions.
 
 ---
 
-## Phases
-
-Build leaf-up. Each phase is independently verifiable; the surface is usable for
-real (frames visible) by end of Phase 3.
-
-### Phase 1 — `dor ab` command (passthrough + `--key`)
-
-CLI leaf, no rendering. Mirror an existing command end-to-end.
-
-- **Files:** `dor/src/commands/agent-browser.ts` (new, mirror
-  `dor/src/commands/iframe.ts`); register in `dor/src/cli.ts` `COMMANDS` +
-  `ROUTES` with **both** keys `'agent-browser'` and `'ab'` pointing at the same
-  `.command` (confirm stricli renders the alias acceptably in help — adjust if it
-  duplicates the entry).
-- **Behavior:** parse/strip `--key` (default `default`) and `--session`; error if
-  both given; resolve `--key` → `dormouse/1/<key>`; forward all remaining args
-  verbatim to the resolved `agent-browser --session <s> …`. Resolve the binary
-  via `DORMOUSE_AGENT_BROWSER_BIN` ?? PATH; friendly error + install hint if
-  absent.
-- **Tests/snapshots:** add `dor/test/snapshots/help/agent-browser.md`; extend
-  `dor/test/cli-output.test.mjs` for: `--help`, `--key`/`--session` mutual
-  exclusion error, missing-binary error, and the key→session translation.
-- **Verify:** `node --test test/cli-output.test.mjs` green; `dor ab open <url>`
-  drives the right session from a terminal (no surface yet).
-- **Spec:** "Delegation Boundary", "The `--key` Model".
-
-### Phase 2 — `surface.agentBrowser` control method + Wall registry
-
-Wire surface creation; the surface can stay the stub.
-
-- **Files:** `dor/src/commands/types.ts` (add `AgentBrowserSurfaceRequest/Response`
-  + `ControlClient.agentBrowserSurface`, mirror `IframeSurface*` at types.ts:109);
-  `dor/src/control-client.ts` (map to `'surface.agentBrowser'`, mirror line 71);
-  `lib/src/components/Wall.tsx` (handler mirroring the `surface.iframe` handler at
-  Wall.tsx:1255 + `createIframeSurface` at Wall.tsx:888; add the
-  `key→{session,surfaceId}` registry).
-- **Behavior:** first call for a session with no surface → create (split next to
-  caller, iframe placement rule); subsequent calls reuse. Pass `wsPort` (from
-  `stream status --json`) + session into panel params.
-- **Verify:** `dor ab open <url>` twice with same key → one surface, reused;
-  different `--key` → second surface. (Stub still renders.)
-- **Spec:** "Session ↔ Surface Mapping".
-
-### Phase 3 — Frames channel (the payoff)
-
-Replace the `AgentBrowserPanel` stub with a live canvas viewer.
-
-- **Files:** `lib/src/components/wall/AgentBrowserPanel.tsx` (currently a stub).
-- **Behavior:** connect `ws://127.0.0.1:<wsPort>`; on `{type:'frame'}` decode
-  base64 JPEG → `drawImage` on a `<canvas>`; track `metadata` device size for
-  later coordinate mapping; handle status messages (`connected`,
-  `screencasting`) for placeholder states. Port `viewer.html`'s frame loop.
-- **Verify:** `dor ab open http://localhost:5173` shows the live page in the
-  surface; navigations update.
-- **Spec:** "Channels → Frames (out)".
-
-### Phase 4 — Input channel
-
-**Resolve the spike first** and note the outcome here. Then either:
-
-- **Stream-native:** send `input_mouse`/`input_keyboard` over the frame socket;
-  map canvas → device coords via `metadata` (port `toViewport` from the
-  prototype). Update the spec's Input section.
-- **CDP-via-host-proxy:** add a long-lived CDP connection manager in the host
-  (`standalone/sidecar/*`, `vscode-ext/src/pty-host.js`) holding the browser-level
-  CDP WS + flattened `Target.attachToTarget` session, dispatching
-  `Input.dispatchMouseEvent`/`dispatchKeyEvent`; add a webview→host input message
-  path through the adapters (`lib/src/lib/platform/vscode-adapter.ts`,
-  `standalone/src/tauri-adapter.ts`, `vscode-ext/src/message-router.ts`); throttle
-  `mousemove`; re-resolve the active target on navigation (prototype's
-  `/cdp-target`).
-- **Focus:** terminal-surface semantics — click-to-focus, forward keys only while
-  selected + in interact mode; leader chord returns to the Wall (Dormouse owns the
-  keydown listener — `lib/src/components/wall/use-wall-keyboard.ts`).
-- **Verify:** click and type into the embedded page; ⌘-leader still navigates panes.
-- **Spec:** "Channels → Input (in)".
-
-### Phase 5 — Tabs
-
-- **Files:** `AgentBrowserPanel.tsx` (tab strip below header).
-- **Behavior:** poll/refresh `tab list` → integrated (1) vs multi-tab (≥2) strip
-  (title + favicon + close ×); selecting → `tab <n>` (stream/input follow active
-  target); × → `tab close`; focus newest web-opened tab; `dor ab open` navigates
-  active, never spawns.
-- **Verify:** trigger a `target=_blank`/popup → strip appears, newest focused,
-  closing extras returns to integrated mode; minimized surface stays title-only.
-- **Spec:** "Tabs".
-
-### Phase 6 — Lifecycle
-
-- **Behavior:** surface kill (`dor kill` / header × / `dor ab … close`) →
-  `agent-browser --session <s> close` + registry cleanup; external session death
-  (stream `connected:false`) → remove/placeholder the surface.
-- **Verify:** kill surface → browser process exits; `agent-browser close`
-  elsewhere → surface tears down.
-- **Spec:** "Lifecycle".
-
-### Phase 7 — VS Code CSP + dogfood
-
-- **Files:** `vscode-ext/src/webview-html.ts` — add
-  `connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>`. No
-  `frame-src`/`img-src` change (canvas from base64, no iframe).
-- **Verify:** `pnpm build:vscode` + `pnpm --filter dormouse dogfood`, reload; full
-  flow works in the real extension. Also smoke-test the standalone (Tauri) build.
-- **Spec:** "VS Code Webview CSP".
-
----
-
-## Testing strategy
-
-- **CLI:** snapshot + behavior tests alongside the other commands
-  (`dor/test/cli-output.test.mjs`, `dor/test/snapshots/`). This is the
-  highest-leverage automated coverage — Phases 1–2 are fully testable headless.
-- **Channels:** mostly manual against a live `agent-browser` (frames/input/tabs
-  need a real browser). The spike script and the prototype are the harness.
-- **Run `node --test` in `dor/` after every CLI change; snapshots will catch help
-  drift** (see how the iframe help snapshot is maintained).
-
----
-
-## Risks & edge cases
-
-- **Input spike is the pivot.** It decides whether Phase 4 is small (stream-native)
-  or the largest phase (host CDP proxy + new adapter message path). Spike before
-  committing to either.
-- **CDP origin refusal** (if proxying): the webview cannot hold the CDP socket;
-  it must live in the host. Don't try to connect CDP from the panel.
-- **Coordinate mapping:** canvas size ≠ device size; scale through frame
-  `metadata` (`deviceWidth/Height`, `pageScaleFactor`, scroll offsets). Port
-  `toViewport` rather than reinventing.
-- **Stream port churn:** OS-assigned per session; always read `stream status
-  --json` fresh, don't cache across session restarts. `AGENT_BROWSER_STREAM_PORT`
-  can pin it if needed.
-- **Zero-tab state:** closing the last page leaves a context with no page — define
-  the surface's empty state (placeholder, not a crash).
-- **Mousemove chatter** (CDP path): throttle webview→host input.
-- **`--headed` passthrough** pops a separate OS window (defeats embedding). Decide
-  whether to warn/block; spec currently leaves passthrough verbatim.
-- **stricli alias rendering:** verify `ab` appears sanely in `dor --help` / `dor ab
-  --help`; adjust ROUTES if it duplicates.
-
----
-
-## Definition of done
-
-- `dor ab` and `dor ab --key <name>` open/reuse browser surfaces per the registry;
-  CLI snapshot tests pass.
-- Frames render live; input works; ⌘-leader still controls the Wall.
-- Tabs present integrated vs multi-tab per spec; minimize stays binary.
-- Surface kill ↔ session close both directions.
-- Works in `dogfood` (VS Code) and standalone; CSP allows the stream WS.
-- Spec updated for any design change the build forced (especially the input
-  channel after the spike).
-
----
-
-## Phase 8 — Screen indicator (SYNCED/SCALED) + viewport modal
-
-**Spec:** "Screen Indicator & Viewport". A two-state header indicator derived
-from reality, plus a modal that is purely a GUI front-end for native
-`agent-browser set viewport` / `set device`. No keyboard shortcut.
-
-**The architectural wrinkle to solve first.** The indicator lives in
-`SurfacePaneHeader` (a dockview *tab* component) but the live state (viewport,
-pane size, sync) and the action (`runAgentBrowser`) live in `AgentBrowserPanel`
-(the *body* component). They are separate components for one pane, so they need a
-per-surface bridge. Use the patterns already in the tree: a surface-id-keyed
-registry like `terminal-lifecycle.ts` + a `useSyncExternalStore` store like
-`external-link-confirmation.ts`. Build that bridge in 8b before the UI.
-
-Leaf-up, each step independently verifiable:
-
-### 8a — Allowlist `set`
-
-- Add `'set'` to **both** allowlists: `AGENT_BROWSER_ALLOWED_SUBCOMMANDS`
-  (`lib/src/lib/platform/types.ts:45`) and `ALLOWED_SUBCOMMANDS`
-  (`vscode-ext/src/agent-browser-host.ts:23`). Still `args[0]`-gated — not a
-  general exec channel.
-- **Verify:** from the panel, `runAgentBrowser(['set','viewport','800','600','1'])`
-  resizes the live browser (frames reflow).
-
-### 8b — Per-surface screen bridge
-
-- New `lib/src/components/wall/agent-browser-screen.ts`: registry keyed by
-  surface id, each entry exposing `subscribe`/`snapshot` of
-  `{ state: 'SYNCED'|'SCALED', viewport:{w,h,dpr}, paneCss:{w,h}, displayDpr,
-  syncEngaged }` and actions `{ engageSync(), applyDevice(name),
-  applyViewport(w,h,dpr), openModal() }`.
-- `AgentBrowserPanel` registers its controller on mount (with `session` /
-  `binaryPath`), unregisters on unmount. Presence of a controller for `api.id`
-  is how the header knows a pane is an agent-browser surface.
-
-### 8c — Derive SYNCED/SCALED in the panel + publish
-
-- Compute from `deviceRef` (browser CSS viewport) and `canvas.width /
-  deviceRef.width` (inferred DPR) vs pane CSS size (`getBoundingClientRect` on
-  `elRef`) and `window.devicePixelRatio`. `SYNCED` iff dims + DPR match within a
-  tolerance (guard fractional-DPR off-by-one). Publish to the registry **only on
-  flip or dim change** — never per frame (don't thrash the header).
-- **Verify:** resize the pane / change display scale → indicator value flips.
-
-### 8d — Sync-to-pane + reconciliation (panel)
-
-- While `syncEngaged`: `ResizeObserver` on `elRef` → re-issue `set viewport
-  <cssW> <cssH> <displayDpr>` debounced ~200ms; track `lastIssued`.
-- **Disengage rule:** when a frame reports a viewport matching neither
-  `lastIssued` nor the current pane (evaluated only when the pane is stable and
-  after we've issued), set `syncEngaged=false`. This is what lets `dor ab set …`
-  and modal Device/Custom transparently take over.
-- **Default on create: auto-engage sync** (decided) — a fresh browser surface
-  starts `SYNCED`, responsive to the pane, not at native 1280×720. Spec updated.
-- **Verify:** engage sync → `SYNCED`, resizes stay `SYNCED`; run `dor ab set
-  device "iPhone 16"` in a terminal → sync disengages, `SCALED`.
-
-### 8e — Header indicator
-
-- In `SurfacePaneHeader`, if a controller exists for `api.id`, render the
-  `SYNCED`/`SCALED` chip immediately right of the title; click → `openModal()`.
-  Gate strictly on controller presence so terminals/iframes are untouched.
-- **Verify:** chip shows only on browser surfaces, reflects state, click opens.
-
-### 8f — The modal
-
-- New `lib/src/components/wall/AgentBrowserScreenModal.tsx`, mounted via a host
-  in `Wall` (mirror `ExternalLinkModalHost`). Reads the controller snapshot and
-  pre-selects: *Sync* (if engaged + matching), else the registry device whose
-  dims match, else *Custom* prefilled with current dims. Radios: **Sync to pane**
-  / **Device** (fixed registry: iPhone 15/16/16 Pro/17, iPad, iPad Pro, Pixel 9,
-  Galaxy S25) / **Custom** (W/H/DPI). Apply → `engageSync()` / `applyDevice()` /
-  `applyViewport()`. Suppress Wall keys while open via `DialogKeyboardContext`
-  (`setDialogKeyboardActive`); Esc cancels.
-- **Device dims: apply-then-reflect** (decided) — the CLI doesn't expose a
-  device's dims up front, so choosing a device issues `set device <name>` and the
-  detail line fills in from the next frames. No hardcoded dims map. Spec updated.
-- **Verify:** pick iPhone 16 → `SCALED` + phone frame; Custom 800×600 → applies;
-  Sync → `SYNCED`.
-
-### 8g — Persistence
-
-- Persist `syncEngaged` per agent-browser surface. **Built via dockview panel
-  params** (`AgentBrowserPanel` writes `api.updateParameters({ syncEngaged })`
-  and seeds from `params.syncEngaged`), which round-trip through the serialized
-  layout blob — the same channel that already carries `session`/`wsPort` across
-  reloads — so no `session-types.ts`/`session-save.ts` change was needed. Device/
-  custom viewports live in the agent-browser session and survive reattach on
-  their own; sync re-engages on reattach iff it was engaged.
-- **Verify:** save/restore preserves sync; save/restore with a device keeps that
-  device (from the session).
-
-### 8h — Host-capability degradation
-
-- Without `agentBrowserCommand` (Tauri today), modal Apply / Sync are inert —
-  disable Apply or show a note, mirroring tab-action degradation. `dor ab set …`
-  from a terminal still works there (execs directly).
-
-### Definition of done (Phase 8)
-
-- Header shows `SYNCED`/`SCALED`, derived from frames, only on browser surfaces.
-- Modal applies Sync / Device / Custom via native `set`; pre-fills from reality.
-- `dor ab set …` from a terminal disengages sync and the indicator follows —
-  CLI and GUI stay consistent.
-- `syncEngaged` persists; standalone degrades gracefully.
-- Spec updated for the two decisions (create-default, device-dims).
-
----
-
-## Phase 9 — HiDPI screenshot streaming (DONE)
-
-**Spec:** "Channels → Frames (out)". Shipped (commit `55bc7d3`).
-
-The stream's screencast is CSS-resolution only — Chromium's
-`Page.startScreencast` ignores `deviceScaleFactor` (verified against the CDP
-spec, crbug 781117, and probes incl. our own CDP screencast + the proposed
-`maxWidth=css*dpr` snippet — all 1×; only `Page.captureScreenshot` honors DPR).
-So the panel **displays device-resolution screenshots** and uses screencast
-frames purely as "page changed" pulses.
-
-- Host capability `agentBrowserScreenshot(session, {format, quality})` runs
-  `agent-browser screenshot` to a temp file and returns the bytes base64
-  (`vscode-ext/src/agent-browser-host.ts`, `message-router.ts`,
-  `message-types.ts`, `vscode-adapter.ts`, `platform/types.ts`).
-- `AgentBrowserPanel` no longer decodes/draws stream frames; each is a pulse.
-  Backpressure: one shot in flight, dirty-coalesce (latest wins), seq-guard
-  against out-of-order decodes, adaptive ~1.5×-capture-time pacing (≈⅔ duty,
-  50ms floor). Static page ⇒ no pulses ⇒ no cost. ~17fps JPEG q85 device-res.
-- Fallback to rendering screencast frames where `agentBrowserScreenshot` is
-  absent (Tauri).
-- Adapter methods bound in the constructor — detached `getPlatform().agentBrowserX`
-  references drop `this` and throw on `requestResponse` (bit us 3×).
-
 ## Phase 10 — Headed pop-out (planned)
 
-**Spec:** "Headed Pop-Out". A header affordance that relaunches the surface's
-browser **headed** as a real OS window the user drives directly; the Dormouse
-pane becomes a clean placeholder. GUI-only, `randomKillChar()`-confirmed,
-platform-gated. **Build leaf-up; this is desktop-only (Tauri-first), degraded in
-VS Code, hidden on web.**
+**Spec:** "Future Expansions → Headed Pop-Out". A header affordance that
+relaunches the surface's browser **headed** as a real OS window the user drives
+directly; the Dormouse pane becomes a clean placeholder. GUI-only,
+`randomKillChar()`-confirmed, platform-gated. **Build leaf-up; desktop-only
+(Tauri-first), degraded in VS Code, hidden on web.**
 
 ### 10pre — Profile-persistence spike (prerequisite-ish)
 
@@ -427,7 +33,8 @@ VS Code, hidden on web.**
   frustrating for authenticated sites. Spike a stable per-session user-data-dir
   (or `agent-browser state save`/`load`) so logins survive the relaunch.
 - Decoupled from the v1 ship (v1 = URLs-only), but the first thing that makes
-  pop-out genuinely useful. Land before or shortly after 10a–10f.
+  pop-out genuinely useful. Also benefits the streamed surface (logins survive
+  daemon restarts). Land before or shortly after 10a–10f.
 
 ### 10a — Host capability: headed relaunch + window control
 
diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 611f1d6e..870bb9f1 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -9,9 +9,9 @@ Dormouse by delegating 100% to the user's own
 [agent-browser](https://github.com/vercel-labs/agent-browser) install. It is a
 **viewer client, not a fork**: every piece of browser behavior — Chromium, CDP,
 the screencast, the entire command surface — stays in `agent-browser`. Dormouse
-adds only a thin surface that renders the session's video stream, forwards input,
-and presents tabs. We reimplement none of agent-browser's behavior, the same way
-an HTTP client is not a fork of the server.
+adds only a thin surface that renders the session, forwards input, and presents
+tabs. We reimplement none of agent-browser's behavior, the same way an HTTP
+client is not a fork of the server.
 
 This is the chosen alternative to the iframe surface (see
 `dor-cli.md` → "Iframe Surface: Limitations And Status"). Because the browser
@@ -35,7 +35,7 @@ than reimplemented:
 
 | Concern | Delegated to |
 | --- | --- |
-| Video (frames) | agent-browser session **stream** WebSocket |
+| Video (frames) | agent-browser session **stream** WebSocket, as change signals (see Channels → Frames) |
 | Input (mouse/keyboard) | the same stream WebSocket's native **`input_*`** messages |
 | Tabs | stream `tabs` messages (read) + **`tab list` / `tab <n>` / `tab close`** (act) |
 
@@ -76,11 +76,11 @@ same reason.
 
 ### `--key` vs raw `--session`
 
-`--key` (managed, namespaced) and `--session` (your point 2: attach to a session
-by its literal agent-browser name) are **mutually exclusive**. `--key default`
-applies only when neither is given. `--session <raw>` is the bring-your-own
-escape hatch for attaching to a session some other tool created; Dormouse still
-opens/reuses a surface for it but performs no namespacing.
+`--key` (managed, namespaced) and `--session` (attach to a session by its literal
+agent-browser name) are **mutually exclusive**. `--key default` applies only when
+neither is given. `--session <raw>` is the bring-your-own escape hatch for
+attaching to a session some other tool created; Dormouse still opens/reuses a
+surface for it but performs no namespacing.
 
 ## Session ↔ Surface Mapping
 
@@ -145,22 +145,20 @@ Immediately to the **right of the title**, the header shows one of two derived
 states — never a stored mode:
 
 - **`SYNCED`** — the browser's live viewport (CSS pixels) equals the pane's CSS
-  pixel size, so frames map 1:1 with no scaling.
-- **`SCALED`** — anything else; the frame is letterboxed/zoomed to fit the pane.
+  pixel size, so the display maps 1:1 with no scaling.
+- **`SCALED`** — anything else; the display is letterboxed/zoomed to fit the pane.
 
 The viewport is read from the stream (`status.viewportWidth/Height`, equal to
 frame `metadata.deviceWidth/Height`) and compared against the pane's CSS size
 (`getBoundingClientRect`). **DPR is not part of the comparison:** the screencast
-is delivered at CSS-pixel resolution, so the JPEG never encodes the browser's
-device pixel ratio (verified 0.27.0 — `set viewport 800 600 2` yields the same
-800×600 frame as `@1`); it is therefore unrecoverable from frames. Dormouse still
+is delivered at CSS-pixel resolution, so it never encodes the browser's device
+pixel ratio (verified 0.27.0 — `set viewport 800 600 2` yields the same 800×600
+frame as `@1`); it is therefore unrecoverable from frames. Dormouse still
 *issues* `displayDpr` when syncing so the page renders at the right density, but
 the indicator is a pure CSS-size match. Because it is derived, the indicator is
 correct no matter *how* the viewport was set — modal, `dor ab set …`, or a raw
-`agent-browser` call. The panel's existing contain-scaling (`max-h-full
-max-w-full`) and coordinate mapping already produce the `SCALED` letterboxing;
-`SYNCED` is simply the case where the viewport equals the pane. There is **no
-keyboard shortcut**.
+`agent-browser` call. `SYNCED` is simply the case where the viewport equals the
+pane. There is **no keyboard shortcut**.
 
 ### The modal
 
@@ -170,7 +168,7 @@ Clicking the indicator opens a modal — three mutually exclusive targets:
 ╭─ Screen — surface:3 ────────────────────────────────────────╮
 │                                                              │
 │   Currently  SCALED                                          │
-│   browser 393×852 @3x   ·   pane 980×560 @2x   (zoomed)       │
+│   browser 393×852   ·   pane 980×560 @2x                     │
 │                                                              │
 │   ( ) Sync to pane                                           │
 │       viewport follows the pane, pixel-for-pixel             │
@@ -183,7 +181,7 @@ Clicking the indicator opens a modal — three mutually exclusive targets:
 │       │   Pixel 9        │  │   Galaxy S25     │             │
 │       │   iPad           │  │   iPad Pro       │             │
 │       └──────────────────┘  └──────────────────┘            │
-│       iPhone 16 · 393×852 @3x                                │
+│       iPhone 16 · 393×852                                    │
 │                                                              │
 │   ( ) Custom     W [ 1280 ]   H [ 720 ]    DPI [ 1 ]         │
 │                                                              │
@@ -206,62 +204,48 @@ setting (verified against 0.27.0). So Sync/Custom are never touch; only Device
 is. The modal **reads the live viewport on open** and pre-selects accordingly:
 *Sync* if sync is engaged and matching, otherwise *Custom* pre-filled with the
 current dims. Like the indicator, the modal reflects reality rather than a stored
-intent.
-
-The CLI does not expose a device's dimensions ahead of time, so device sizing is
-**apply-then-reflect**: choosing a device issues `set device <name>`, and the
-detail line (`iPhone 16 · 393×852 @3x`) fills in from the next frames rather than
-being known up front. The same gap means the modal **cannot pre-select a device
-by matching dims** — with no dims map to compare against, a non-synced viewport
-pre-selects *Custom* (the device list still shows the live `SYNCED`/`SCALED`
-readout, just without a radio pre-checked on a specific device).
-
-### Transparency with `dor ab set …`
-
-There is nothing extra to "expose" — **the modal *is* a GUI for native
-`agent-browser set`.** Device/Custom issue the same `set device` / `set
-viewport` a user runs as `dor ab set …`. Two issue paths converge on one
-session — the terminal's `dor ab` execs agent-browser directly; the webview
-modal goes through the host's `agentBrowserCommand` — and the daemon serializes
-them. Whichever wrote last, the `SYNCED`/`SCALED` indicator and the modal's
-pre-fill reflect it.
+intent. The CLI does not expose a device's dimensions ahead of time, so device
+sizing is **apply-then-reflect**: choosing a device issues `set device <name>`,
+and its detail line fills in from the next frames rather than being known up
+front (the same gap means the modal cannot pre-select a device by matching dims).
+
+**Transparency with `dor ab set …`.** There is nothing extra to "expose" — the
+modal *is* a GUI for native `agent-browser set`. Device/Custom issue the same
+`set device` / `set viewport` a user runs as `dor ab set …`. Two issue paths
+converge on one session — the terminal's `dor ab` execs agent-browser directly;
+the webview modal goes through the host's `agentBrowserCommand` — and the daemon
+serializes them. Whichever wrote last, the indicator and the modal's pre-fill
+reflect it.
 
 **Sync is the one non-native concept.** agent-browser has no "follow the pane"
 mode; *Sync to pane* is a Dormouse behavior that auto-issues native `set
 viewport <pane>` and re-issues on resize. **A freshly created browser surface
 auto-engages sync**, so it starts `SYNCED` — pixel-for-pixel and responsive to
 the pane — rather than at agent-browser's native 1280×720. Coexistence is
-**last-writer-wins**:
-Dormouse tracks the viewport it last issued (`lastIssued`); when a frame reports
-a viewport matching neither `lastIssued` nor the current pane, an external setter
-(`dor ab set …`) intervened, so Dormouse **disengages sync** and the indicator
-falls to `SCALED`. (Evaluate this only when the pane size is stable and Dormouse
-has already issued for it, so a resize transient — a frame at the old size before
-the re-issue lands — is not mistaken for an external override.)
-
-> **Known limitation: there is currently no way to re-trigger sync from the
-> CLI.** Because sync is not an agent-browser concept, `dor ab` has no verb for
-> it; once an external `set` disengages sync, re-enabling it means reopening the
-> modal and choosing *Sync to pane*. (A Dormouse-reserved `dor ab` verb could add
-> this later, at the cost of the first non-passthrough subcommand.)
-
-### Mechanism, persistence, host capability
-
-- Modal and sync issue `set viewport` / `set device` through
-  `agentBrowserCommand`, whose allowlist includes `set` (alongside `tab`,
-  `close`).
+**last-writer-wins**: Dormouse tracks the viewport it last issued (`lastIssued`)
+and only treats a deviating frame as an external override once a frame has first
+*confirmed* the issued size landed (so a resize transient isn't mistaken for an
+external `dor ab set …`). When an external setter wins, Dormouse disengages sync
+and the indicator falls to `SCALED`.
+
+> **Known limitation: no way to re-trigger sync from the CLI.** Because sync is
+> not an agent-browser concept, `dor ab` has no verb for it; once an external
+> `set` disengages sync, re-enabling it means reopening the modal and choosing
+> *Sync to pane*.
+
+Persistence and degradation:
+
 - The only Dormouse-side state worth persisting is **whether sync is engaged**;
   device/custom viewports live in the agent-browser session itself and survive
   reattach. `syncEngaged` rides in the surface's dockview **panel params**, which
   already round-trip through the serialized layout blob (the same channel that
   carries `session`/`wsPort` across webview reloads), so it persists with no
   `session-types.ts`/`session-save.ts` changes; the panel seeds its initial state
-  from `params.syncEngaged` (absent ⇒ fresh surface ⇒ auto-engage), so reattach
-  re-engages sync iff it was engaged.
+  from `params.syncEngaged` (absent ⇒ fresh surface ⇒ auto-engage).
 - Like tab actions, this inherits the `agentBrowserCommand` host capability: on
   adapters that do not implement it (currently Tauri), modal-driven resizes are
-  inert and the control degrades accordingly. (`dor ab set …` from a terminal
-  still works there, since it execs agent-browser directly.)
+  inert. (`dor ab set …` from a terminal still works there, since it execs
+  agent-browser directly.)
 
 ## Lifecycle
 
@@ -272,158 +256,17 @@ Surface lifetime and browser lifetime are bound, both directions:
   close`).
 - **Session dies externally → tear down the surface.** If the browser exits
   (crash, or a plain `agent-browser close` elsewhere), the stream reports
-  `connected: false`; the Wall removes or placeholders the surface. (Exception:
-  while a surface is **popped out**, see below, the headed window closing is
-  expected and reverts the pane rather than tearing it down.)
-
-## Headed Pop-Out
-
-The headless + streamed-screenshot surface is the default everywhere: it is
-crisp, deterministic, and **uniformly portable** (no OS window, no positioning,
-no DPI/Wayland concerns; works identically on win/mac/linux, in VS Code, and on
-web). But streaming can't match a *real* window for hands-on interactivity —
-IME composition, file uploads, smooth scrolling, native editing chords,
-extensions, DevTools, native dialogs. **Pop-out** is the escape hatch: it
-relaunches the surface's browser **headed**, as an ordinary OS window the user
-drives directly. It is a deliberate, occasional mode, not the rendering path.
-
-Because Chrome's headed/headless choice is fixed at process launch (no live
-toggle — verified), pop-out is a **relaunch**, not a move. The design embraces
-that: the user interacts with the headed window natively, so Dormouse does
-**not** screencast it — the in-Dormouse pane becomes a stub. This sidesteps the
-headed-screencast, off-screen-occlusion, and window-tracking problems entirely.
-
-### Affordance
-
-A pop-out control (arrow icon) sits in the surface header's action cluster, on
-**agent-browser surfaces only** and only where the host can spawn a headed
-window (gated on a host capability; see below). Web hosts, which cannot spawn OS
-windows, omit it. Pop-out is **GUI-only** — like *Sync to pane*, it is a
-Dormouse behavior with no `agent-browser` equivalent, so it gets no `dor ab`
-verb.
-
-Because pop-out is destructive of live state (it relaunches the browser and, in
-v1, drops scroll/DOM/login — see below), the click is **confirmed the same way
-as kill**: a `randomKillChar()`-style overlay requires typing the shown
-character, so a stray click can't discard your live page (mirror `KillConfirm` /
-`KillConfirmOverlay`).
-
-### Identity-preserving relaunch
-
-Pop-out **keeps the session name** (`dormouse.<workspaceId>.<key>`); only the
-underlying Chrome process changes (now headed, new stream port). The
-key→`{session, surfaceId}` registry is untouched, so **`dor ab --key …`
-continues to drive the same surface transparently** — navigation and commands
-now land in the headed window. `dor ab open <url>` still navigates the active
-tab; it does not spawn one.
-
-### State carried across the relaunch
-
-Pop-out preserves **what it can**, and is honest that it is a *reload*, not a
-continuation:
-
-- **v1: the ordered list of tab URLs + which was active.** On relaunch the
-  headed window reopens each URL as a tab in the same order and focuses the
-  previously-active one.
-- **Lost (v1):** live DOM, scroll position, form inputs, `sessionStorage`,
-  in-memory JS/SPA route state — and, because agent-browser launches each Chrome
-  with an ephemeral temp profile, **cookies/login**. So a popped-out window
-  starts logged out unless/until profile persistence lands.
-- **Planned (profile spike):** persist cookies/storage via a stable
-  user-data-dir (or `agent-browser state save`/`load`) so logins survive the
-  relaunch — without it, pop-out is frustrating for authenticated sites, so this
-  is a known and wanted follow-up, not a maybe. v1 still ships URLs-only.
-
-### The pane while popped out
-
-The pane **stays open** and switches to a **clean placeholder** (no dimmed last
-frame):
-
-- Copy indicating the surface is open in a separate window.
-- A **"Bring to front"** action that best-effort raises/focuses the headed
-  window (may be unavailable on some platforms — see cross-platform).
-- A **"Pop back in"** action that closes the headed window, which triggers the
-  auto-revert below (relaunch headless, resume streaming, reopen the tabs) —
-  i.e. it is the same path as the user dismissing the window themselves.
-- Frame display, screenshot capture, input forwarding, the SYNCED/SCALED chip,
-  and the tab strip are all inert (you interact with the real window). But the
-  **stream WS stays connected** to keep observing `tabs`/`status`: we track the
-  **last non-empty tab list** (what to reopen on revert) and watch for
-  `connected: false` (the window ended).
-
-### Positioning
-
-Placement is **best-effort, one-time, and does not follow** (a separate OS
-window won't track the pane after spawn):
-
-- If the host can resolve the pane's screen rectangle, place the headed window's
-  **content area** over it (accounting for window chrome and the target
-  display's DPR).
-- Otherwise — **always in VS Code** (the sandboxed webview cannot read screen
-  coordinates) and **on Wayland** (clients cannot self-position) — fall back to
-  **centering on the current monitor**.
-
-### Window identity
-
-There is **no control tab** (it would only have been needed to distinguish the
-two close gestures, which the unified lifecycle below removes). Window identity
-is therefore best-effort: *Bring to front* raises the OS window via the host
-(by the session's process), not via an anchor tab. A Dormouse-flavored window
-title isn't guaranteed — a Chrome window's title follows its active tab — so it's
-a nice-to-have, not relied upon.
-
-### Lifecycle (pop-out)
-
-The headed window ending and the surface being disposed are **decoupled**: the
-only thing that tears a surface down is Dormouse's own kill. Everything else just
-moves the surface between headed and headless.
-
-- **The headed window ends** — by any gesture (window `×` / `⌘⇧W`, or closing
-  the last tab; without a control tab these are indistinguishable, and they
-  behave the same) → **auto-revert**: relaunch the session headless, resume
-  streaming in the pane, and reopen the **last non-empty tab list** in order. So
-  closing the final tab reopens *that* tab back in Dormouse; closing a
-  three-tab window reopens those three. The surface is never lost this way.
-  (The pane's *Pop back in* button takes this same path by closing the window
-  for you.)
-- **Kill the Dormouse pane / `dor kill`** → the only teardown: close the headed
-  window + session (the normal surface↔session binding). This is the way to
-  actually be done with the browser.
-- **Dormouse/editor quits** → headed windows must be cleaned up; no orphans
-  (agent-browser's daemon outlives the editor, so shutdown closes managed
-  sessions explicitly).
-
-### Host capability & cross-platform
-
-Pop-out needs host support beyond `agentBrowserCommand`: relaunching a session
-**headed** with window-position args, optionally **raising** a window, and
-optionally resolving the **pane→screen rectangle**. As with other host
-capabilities, adapters degrade rather than fail:
-
-| Host / platform | Spawn headed | Position over pane | Bring to front |
-| --- | --- | --- | --- |
-| Standalone (Tauri), macOS / Windows / Linux-X11 | yes | yes (best-effort) | yes |
-| Standalone, Linux-**Wayland** | yes | **no** → center | best-effort / maybe no |
-| VS Code (any OS) | yes | **no** → center (webview can't read screen coords) | best-effort |
-| Web | **no** (affordance hidden) | — | — |
-
-Windows adds per-monitor / fractional-DPI math for the pane→window mapping;
-macOS Retina works as tested; Wayland cannot self-position or reliably raise, so
-it always centers. The feature is therefore a **platform-gated enhancement**,
-never load-bearing — the streamed surface remains the portable baseline on every
-target.
+  `connected: false`; the Wall removes or placeholders the surface.
 
 ## Channels
 
-Mirrors the validated `~/Documents/dev/agent-proto` prototype.
-
 ### Frames (out) — screenshot display, screencast-paced
 
 The stream's screencast is **CSS-resolution only**: Chromium's
 `Page.startScreencast` captures in DIP and has no deviceScaleFactor/scale knob,
 so on a HiDPI display its frames upscale to mush. (Verified against the CDP spec
 — screencast metadata is defined in DIP, `maxWidth/maxHeight` only *downscale* —
-and by probe: our own screencast at `deviceScaleFactor: 2` still returns 1×;
+and by probe: our own CDP screencast at `deviceScaleFactor: 2` still returns 1×;
 only `Page.captureScreenshot` honors DPR. This is a Chromium limitation, not
 agent-browser's, so owning the CDP connection wouldn't change it.)
 
@@ -487,9 +330,7 @@ Keyboard caveats (all verified against 0.27.0):
   panel routes the *intent* to the host's `agentBrowserEdit(session, op)`
   capability, which runs a host-owned `eval` over the daemon's CDP connection:
   - `selectAll` → `el.select()` / `execCommand('selectAll')`.
-  - `copy` → read the selection, write it to the **OS clipboard**
-    (`vscode.env.clipboard`). Copying from the embedded browser lands in your
-    real clipboard, which is the desired UX anyway.
+  - `copy` → read the selection, write it to the **OS clipboard**.
   - `cut` → copy + delete the selection.
   The webview only picks one of these three op names; the host owns the JS, so
   this is a purpose-built channel, not arbitrary eval. **cmd-Z/⇧Z (undo/redo)
@@ -515,16 +356,15 @@ host on the webview's behalf (a webview cannot spawn processes; see
 
 | Piece | Location |
 | --- | --- |
-| `dor ab` command (passthrough + `--key` intercept) | `dor/src/commands/agent-browser.ts` (new) |
-| Control method `surface.agentBrowser` request/response | `dor/src/commands/types.ts`, `dor/src/control-client.ts` (mirror `surface.iframe`, types.ts:109, control-client.ts:71) |
-| Surface component (canvas viewer + WS client + tab strip + sync tracking / `set` issuance / SYNCED-SCALED derivation) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
-| SYNCED/SCALED indicator right of the title; opens the screen modal (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
-| Screen modal (Sync / Device-registry / Custom; issues native `set …`) | `lib/src/components/wall/AgentBrowserScreenModal.tsx` (new) |
-| Per-surface "sync engaged" persistence | the surface's dockview **panel params** (`syncEngaged`), persisted via the serialized layout blob — no `session-types.ts`/`session-save.ts` change |
-| Per-surface screen bridge (header↔body↔modal) | `lib/src/components/wall/agent-browser-screen.ts` (new); modal host `lib/src/components/AgentBrowserScreenModalHost.tsx` (new) |
-| Surface registration | `lib/src/components/Wall.tsx:339` (`'agent-browser': AgentBrowserPanel`) |
-| Control handler + key→session registry | `lib/src/components/Wall.tsx` (mirror the `surface.iframe` handler at Wall.tsx:1255) |
-| Host CLI runner (`agentBrowserCommand`) + VS Code stream relay | `lib/src/lib/platform/types.ts` (optional adapter methods), `vscode-ext/src/message-router.ts`, `vscode-ext/src/agent-browser-host.ts` |
+| `dor ab` command (passthrough + `--key` intercept) | `dor/src/commands/agent-browser.ts` |
+| Control method `surface.agentBrowser` request/response | `dor/src/commands/types.ts`, `dor/src/control-client.ts` |
+| Surface component (canvas viewer + WS client + tab strip + screenshot loop + sync tracking + SYNCED/SCALED) | `lib/src/components/wall/AgentBrowserPanel.tsx` |
+| SYNCED/SCALED indicator + opens the screen modal (agent-browser surfaces only) | `lib/src/components/wall/SurfacePaneHeader.tsx` |
+| Screen modal (Sync / Device-registry / Custom; issues native `set …`) | `lib/src/components/wall/AgentBrowserScreenModal.tsx` |
+| Per-surface screen bridge (header↔body↔modal) + modal host | `lib/src/components/wall/agent-browser-screen.ts`, `lib/src/components/AgentBrowserScreenModalHost.tsx` |
+| Per-surface `syncEngaged` persistence | dockview **panel params**, via the serialized layout blob (no `session-types.ts`/`session-save.ts` change) |
+| Surface registration + control handler + key→session registry | `lib/src/components/Wall.tsx` |
+| Host capabilities + VS Code stream relay | `lib/src/lib/platform/types.ts`, `lib/src/lib/platform/vscode-adapter.ts`, `vscode-ext/src/agent-browser-host.ts`, `vscode-ext/src/message-router.ts` |
 
 ### Host capabilities
 
@@ -544,10 +384,11 @@ hosts degrade gracefully:
   chords (select-all/copy/cut) the stream input path can't dispatch.
 - **`getAgentBrowserStreamUrl(port)`** — returns the WebSocket URL the webview
   should use for the session stream (see CSP/origin below).
-- **(Planned) headed pop-out** — relaunch a session headed with window-position
-  args, raise a window, and resolve the pane→screen rectangle (see Headed
-  Pop-Out). Platform-gated; degrades to center-on-monitor where positioning
-  isn't possible.
+
+> **Footgun:** these adapter methods use `this.requestResponse` internally and
+> are **bound in the adapter constructor**, because the panel calls some through
+> detached references (`getPlatform().agentBrowserScreenshot`) which would
+> otherwise drop `this`.
 
 ## VS Code Webview CSP and Stream Origin
 
@@ -558,8 +399,8 @@ WebSocket:
 connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>
 ```
 
-The canvas is drawn from base64 frame data, so no `img-src` change is needed, and
-no `frame-src` is involved — there is no iframe.
+The canvas is drawn from base64 data, so no `img-src` change is needed, and no
+`frame-src` is involved — there is no iframe.
 
 CSP alone is not enough in VS Code: the agent-browser stream server rejects
 WebSocket upgrades whose `Origin` is not localhost-or-absent (verified against
@@ -569,3 +410,96 @@ a loopback-only TCP relay that strips the `Origin` header and pipes bytes to
 `127.0.0.1:<streamPort>`; `getAgentBrowserStreamUrl` returns the relay URL
 (`ws://127.0.0.1:<relayPort>/stream/<streamPort>`). The standalone (Tauri)
 webview connects directly — its origin is allowed.
+
+---
+
+# Future Expansions
+
+> Designed, not yet built. Everything above describes the surface as it exists
+> today; everything below is planned.
+
+## Headed Pop-Out
+
+The headless + streamed-screenshot surface above is the default everywhere: it is
+crisp, deterministic, and **uniformly portable** (no OS window, no positioning,
+no DPI/Wayland concerns; works identically on win/mac/linux, in VS Code, and on
+web). But streaming can't match a *real* window for hands-on interactivity — IME
+composition, file uploads, smooth scrolling, native editing chords, extensions,
+DevTools, native dialogs. **Pop-out** is the escape hatch: it relaunches the
+surface's browser **headed**, as an ordinary OS window the user drives directly.
+A deliberate, occasional mode, not the rendering path.
+
+Because Chrome's headed/headless choice is fixed at process launch (no live
+toggle — verified), pop-out is a **relaunch**, not a move. The design embraces
+that: the user interacts with the headed window natively, so Dormouse does
+**not** screencast it — the in-Dormouse pane becomes a stub. This sidesteps the
+headed-screencast, off-screen-occlusion, and window-tracking problems entirely.
+
+**Affordance.** A pop-out arrow in the surface header's action cluster, on
+agent-browser surfaces only, gated on a host capability (hidden on web). GUI-only
+— like *Sync to pane* it has no `agent-browser` equivalent, so no `dor ab` verb.
+Because it is destructive of live state, the click is confirmed with a
+`randomKillChar()`-style type-the-character overlay (mirror `KillConfirm`).
+
+**Identity-preserving relaunch.** Pop-out keeps the session name; only the Chrome
+process changes (headed, new stream port). The key→`{session, surfaceId}`
+registry is untouched, so `dor ab --key …` keeps driving the same surface
+transparently.
+
+**State carried.** v1 preserves the **ordered tab URL list + which was active**
+and reopens them in order. Lost in v1: live DOM, scroll, form inputs,
+`sessionStorage`, and — because agent-browser uses an ephemeral temp profile —
+**cookies/login**. The **profile-persistence spike** (stable user-data-dir or
+`agent-browser state save`/`load`) is the wanted follow-up that makes pop-out
+usable for authenticated sites.
+
+**The pane while popped out.** Stays open as a clean placeholder: copy that it's
+in a separate window, a best-effort **Bring to front**, and **Pop back in**
+(closes the window → triggers the revert below). Frame display / screenshots /
+input / chip / tab strip are inert, but the stream WS stays connected to observe
+`tabs`/`status` — we track the **last non-empty tab list** and watch for
+`connected: false`.
+
+**Positioning.** Best-effort, one-time, does **not** follow: place the headed
+window's content area over the pane's screen rect when the host can resolve it;
+otherwise — **always in VS Code** (sandboxed webview) and **on Wayland** (clients
+can't self-position) — center on the current monitor.
+
+**Window identity.** No control tab. *Bring to front* raises the OS window via
+the host (by the session's process); a Dormouse-flavored window title isn't
+guaranteed (a Chrome window's title follows its active tab).
+
+**Lifecycle.** The headed window ending and the surface being disposed are
+**decoupled**:
+
+- **The headed window ends** — by any gesture (window `×`/`⌘⇧W`, or closing the
+  last tab; without a control tab these are indistinguishable) → **auto-revert**:
+  relaunch headless, resume streaming, reopen the **last non-empty tab list** in
+  order. So closing the final tab reopens *that* tab; closing a three-tab window
+  reopens those three. The surface is never lost this way.
+- **Kill the Dormouse pane / `dor kill`** → the only teardown.
+- **Dormouse/editor quits** → headed windows are cleaned up; no orphans.
+
+**Host capability & cross-platform.** Needs host support beyond
+`agentBrowserCommand`: relaunch headed with window-position args, raise a window,
+resolve the pane→screen rect. Adapters degrade rather than fail:
+
+| Host / platform | Spawn headed | Position over pane | Bring to front |
+| --- | --- | --- | --- |
+| Standalone (Tauri), macOS / Windows / Linux-X11 | yes | yes (best-effort) | yes |
+| Standalone, Linux-**Wayland** | yes | **no** → center | best-effort / maybe no |
+| VS Code (any OS) | yes | **no** → center (webview can't read screen coords) | best-effort |
+| Web | **no** (affordance hidden) | — | — |
+
+Windows adds per-monitor / fractional-DPI math; Wayland can't self-position or
+reliably raise, so it always centers. The feature is therefore a **platform-gated
+enhancement**, never load-bearing — the streamed surface stays the portable
+baseline on every target.
+
+## Other planned
+
+- **Profile persistence** (above) — also benefits the streamed surface (logins
+  survive daemon restarts), not just pop-out.
+- **Re-trigger sync from the CLI** — a Dormouse-reserved `dor ab` verb, at the
+  cost of the first non-passthrough subcommand.
+- **Undo/redo chords** — blocked on the upstream stream-input `commands` fix.

From 297fc6bdb66d07e8a6a3431b77e7179491214409 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 11:54:54 -0700
Subject: [PATCH 18/25] agent-browser: don't parse discarded screencast frames
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We display device-resolution screenshots and use stream frames only as
"page changed" pulses, so a frame's base64-JPEG payload is thrown away. On an
animating page that's ~13 MB/s of frame data at 1080p/60fps being JSON.parsed
(and allocated as a throwaway ~216 KB string) on the webview main thread, where
it competes with screenshot rendering.

Probed the screencast: rate is ~60fps independent of viewport size, and there's
no resolution/fps/quality knob (only AGENT_BROWSER_STREAM_PORT) — frame size is
the viewport, which our screenshots share, so we can't shrink it. But we don't
have to parse it: frames are the only large messages, so pulse on any message
over a 16 KB threshold and skip the parse + allocation entirely. The viewport
(for the indicator + input mapping) already comes from the small `status`
messages, which fire on every change. Smaller messages still parse, so a rare
tiny-viewport frame under the cutoff still pulses correctly.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md               | 13 +++++++++---
 lib/src/components/wall/AgentBrowserPanel.tsx | 20 ++++++++++++++++++-
 2 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 870bb9f1..717a4449 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -276,9 +276,16 @@ purely as a **change signal**:
 - Port discovery: `agent-browser --session <s> stream status --json` →
   `{ "port": <n>, ... }` ⇒ `ws://127.0.0.1:<n>`. Streaming is always enabled;
   `AGENT_BROWSER_STREAM_PORT` pins a port.
-- Each `{ "type": "frame", "metadata": { deviceWidth, deviceHeight, … } }`
-  message is a "page changed" **pulse** (and updates the live viewport for the
-  indicator and input mapping). The frame's own JPEG is **not** decoded/drawn.
+- Each `{ "type": "frame", … }` message is a "page changed" **pulse**. The
+  frame's own JPEG is **not** decoded/drawn — in fact it is **not even parsed**:
+  frames are the only large stream messages (a base64 JPEG, ~150–220 KB at
+  desktop sizes; an animating page streams ~13 MB/s of them at 1080p/60fps that
+  we'd otherwise `JSON.parse` and throw away), so we pulse on any message over a
+  size threshold and skip the parse + allocation. The live viewport (for the
+  indicator and input mapping) comes from the small `status` messages, which fire
+  whenever it changes. Frame size is fixed to the viewport — the screencast has
+  no resolution/fps knob (only `AGENT_BROWSER_STREAM_PORT`), and its rate is
+  ~60fps regardless of size, so there's nothing to shrink anyway.
 - On a pulse, capture a crisp frame via the host's `agentBrowserScreenshot`
   (`agent-browser screenshot`, which honors the session viewport/DPR — device
   resolution, e.g. 2560×1600 for a 1280×800@2 pane) and `drawImage` it to the
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 53d7da9d..079745b9 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -52,6 +52,15 @@ function dimsMatch(a: { w: number; h: number }, b: { w: number; h: number }): bo
   return Math.abs(a.w - b.w) <= DIM_TOLERANCE && Math.abs(a.h - b.h) <= DIM_TOLERANCE;
 }
 
+// Stream messages above this size are frames (a base64 JPEG — ~150–220 KB at
+// desktop sizes); `status`/`tabs` are well under 16 KB. We display screenshots,
+// not frames, so a frame's payload is discarded — there's no point paying
+// JSON.parse + a throwaway allocation for it (measured ~13 MB/s at 1080p/60fps
+// on an animating page). We pulse on the raw message and read the viewport from
+// the small `status` messages instead. Smaller messages still get parsed, so a
+// rare tiny-viewport frame falling under the cutoff still pulses correctly.
+const FRAME_PULSE_THRESHOLD = 16384;
+
 type StreamTab = {
   tabId: string;
   title: string | null;
@@ -531,7 +540,16 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
         failures = 0;
         setConnectionLost(false);
       };
-      ws.onmessage = (ev) => handleMessage(ev.data);
+      ws.onmessage = (ev) => {
+        // Fast-path discarded frames: any large message is a screencast frame
+        // whose pixels we don't display, so pulse without parsing the payload.
+        const data = ev.data;
+        if (screenshotCapableRef.current && typeof data === 'string' && data.length > FRAME_PULSE_THRESHOLD) {
+          screenshotLoop.pulse();
+          return;
+        }
+        handleMessage(data);
+      };
       ws.onclose = () => {
         wsRef.current = null;
         if (disposed) return;

From 1b706cd89087afb6d6f05af924a9bdb95ffe36ba Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 12:26:33 -0700
Subject: [PATCH 19/25] agent-browser: binary screenshot transport + extract
 panel modules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Transport: ship screenshot frames as raw bytes (Uint8Array over the webview
structured-clone channel) instead of base64. Removes the host-side
toString('base64'), the webview atob + per-byte decode loop, and ~33% transfer
inflation per shot — the largest, most frequent payload in the surface.
Dogfood-confirmed VS Code preserves the Uint8Array across the boundary.

Quality (pure extractions, behavior-preserving):
- use-pane-chrome.ts: the pane register/unregister + spawn-animation effects,
  previously copy-pasted byte-for-byte in TerminalPanel/IframePanel/
  AgentBrowserPanel, are now one shared hook.
- agent-browser-input.ts: the pure keyboard/mouse→CDP translation (VK tables,
  virtualKeyCode, modifiers, mouse maps, edit ops) lifted out of the panel, with
  agent-browser-input.test.ts covering the '.'=VK_DELETE footgun + modifier mask.
- agent-browser-screenshot-loop.ts: the backpressure state machine as
  createScreenshotLoop({getSession,getBinaryPath,isCapable,draw}); the panel
  wires it in a one-line useMemo.

AgentBrowserPanel drops ~190 lines and now reads as transport + sync + render.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/components/wall/AgentBrowserPanel.tsx | 245 +++---------------
 lib/src/components/wall/IframePanel.tsx       |  43 +--
 lib/src/components/wall/TerminalPanel.tsx     |  39 +--
 .../wall/agent-browser-input.test.ts          |  45 ++++
 .../components/wall/agent-browser-input.ts    |  74 ++++++
 .../wall/agent-browser-screenshot-loop.ts     | 108 ++++++++
 lib/src/components/wall/use-pane-chrome.ts    |  51 ++++
 lib/src/lib/platform/types.ts                 |   5 +-
 lib/src/lib/platform/vscode-adapter.ts        |   2 +-
 vscode-ext/src/agent-browser-host.ts          |   9 +-
 vscode-ext/src/message-types.ts               |   2 +-
 11 files changed, 329 insertions(+), 294 deletions(-)
 create mode 100644 lib/src/components/wall/agent-browser-input.test.ts
 create mode 100644 lib/src/components/wall/agent-browser-input.ts
 create mode 100644 lib/src/components/wall/agent-browser-screenshot-loop.ts
 create mode 100644 lib/src/components/wall/use-pane-chrome.ts

diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 079745b9..155f35c3 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -6,7 +6,7 @@
  * `tabs` messages. Tab actions (switch/close) go through the host's
  * `agentBrowserCommand` because a webview cannot spawn the agent-browser CLI.
  */
-import { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { clsx } from 'clsx';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
@@ -21,9 +21,17 @@ import {
   type ScreenState,
 } from './agent-browser-screen';
 import {
-  FreshlySpawnedContext,
+  EDIT_OPS,
+  MOUSE_BUTTONS,
+  MOUSE_BUTTON_MASKS,
+  SPECIAL_KEYS,
+  modifiers,
+  virtualKeyCode,
+} from './agent-browser-input';
+import { createScreenshotLoop } from './agent-browser-screenshot-loop';
+import { usePaneChrome } from './use-pane-chrome';
+import {
   ModeContext,
-  PaneElementsContext,
   SelectedIdContext,
   WallActionsContext,
 } from './wall-context';
@@ -73,75 +81,6 @@ type StreamStatus = {
   screencasting: boolean;
 };
 
-// `text` is what makes typing land; windowsVirtualKeyCode is what makes
-// non-text keys and modifier chords act. Keyed by KeyboardEvent.key.
-const SPECIAL_KEYS: Record<string, { text?: string; keyCode: number }> = {
-  Enter: { text: '\r', keyCode: 13 },
-  Tab: { text: '\t', keyCode: 9 },
-  Backspace: { text: '\b', keyCode: 8 },
-  Escape: { keyCode: 27 },
-  ArrowLeft: { keyCode: 37 },
-  ArrowUp: { keyCode: 38 },
-  ArrowRight: { keyCode: 39 },
-  ArrowDown: { keyCode: 40 },
-  Delete: { keyCode: 46 },
-  Insert: { keyCode: 45 },
-  Home: { keyCode: 36 },
-  End: { keyCode: 35 },
-  PageUp: { keyCode: 33 },
-  PageDown: { keyCode: 34 },
-  Shift: { keyCode: 16 },
-  Control: { keyCode: 17 },
-  Alt: { keyCode: 18 },
-  Meta: { keyCode: 91 },
-  CapsLock: { keyCode: 20 },
-  ContextMenu: { keyCode: 93 },
-};
-
-// Windows virtual-key codes for printable keys, keyed by KeyboardEvent.code
-// (the physical key, so shifted variants share an entry). Letters and digits
-// are handled structurally in virtualKeyCode. Never derive a VK from
-// `key.charCodeAt(0)`: '.' is 46, which is VK_DELETE — the daemon deletes
-// instead of typing a period.
-const OEM_VK_BY_CODE: Record<string, number> = {
-  Space: 32,
-  Semicolon: 186,
-  Equal: 187,
-  Comma: 188,
-  Minus: 189,
-  Period: 190,
-  Slash: 191,
-  Backquote: 192,
-  BracketLeft: 219,
-  Backslash: 220,
-  BracketRight: 221,
-  Quote: 222,
-  NumpadDecimal: 110,
-  NumpadDivide: 111,
-  NumpadMultiply: 106,
-  NumpadSubtract: 109,
-  NumpadAdd: 107,
-};
-
-function virtualKeyCode(key: string, code: string): number {
-  const special = SPECIAL_KEYS[key];
-  if (special) return special.keyCode;
-  if (/^Key[A-Z]$/.test(code)) return code.charCodeAt(3);
-  if (/^(Digit|Numpad)[0-9]$/.test(code)) return code.charCodeAt(code.length - 1) + (code.startsWith('Numpad') ? 48 : 0);
-  if (/^F([1-9]|1[0-2])$/.test(code)) return 111 + Number(code.slice(1));
-  return OEM_VK_BY_CODE[code] ?? 0;
-}
-
-// Cmd/Ctrl + these map to native editing ops the stream input path can't do.
-const EDIT_OPS = { a: 'selectAll', c: 'copy', x: 'cut' } as const;
-
-const MOUSE_BUTTONS: Record<number, string> = { 0: 'left', 1: 'middle', 2: 'right' };
-const MOUSE_BUTTON_MASKS: Record<number, number> = { 0: 1, 1: 4, 2: 2 };
-
-function modifiers(e: { altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean }): number {
-  return (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0);
-}
-
 function tabDisplayTitle(tab: StreamTab): string {
   const title = tab.title?.trim();
   if (title) return title;
@@ -154,15 +93,21 @@ function tabDisplayTitle(tab: StreamTab): string {
   }
 }
 
+// Decode a base64 screencast frame to an ImageBitmap (the fallback display path
+// for hosts that can't screenshot). Callers apply their own freshness guard.
+function decodeScreencastFrame(dataBase64: string): Promise<ImageBitmap> {
+  const bytes = Uint8Array.from(atob(dataBase64), (c) => c.charCodeAt(0));
+  return createImageBitmap(new Blob([bytes], { type: 'image/jpeg' }));
+}
+
 export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrowserPanelParams>) {
   const actions = useContext(WallActionsContext);
-  const { elements: paneElements, bumpVersion } = useContext(PaneElementsContext);
-  const freshlySpawned = useContext(FreshlySpawnedContext);
   const mode = useContext(ModeContext);
   const selectedId = useContext(SelectedIdContext);
   const elRef = useRef<HTMLDivElement>(null);
   const viewportRef = useRef<HTMLDivElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
+  usePaneChrome(api, elRef);
 
   const session = params?.session;
   const wsPort = params?.wsPort;
@@ -206,19 +151,10 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
 
   // --- display: crisp HiDPI screenshots, paced by stream-frame "pulses" ---
   //
-  // The stream's screencast is CSS-resolution only (Chromium's
-  // Page.startScreencast ignores deviceScaleFactor — see the spec), so on a
-  // Retina display its frames upscale to mush. Instead we DISPLAY
-  // device-resolution screenshots (`agent-browser screenshot`, which honors the
-  // session DPR) and use the screencast frames purely as "the page changed"
-  // pulses telling us when to grab a fresh one.
-  //
-  // Backpressure (we only ever want the latest, and must slow down if capture
-  // can't keep up): at most one screenshot in flight; a pulse during a shot
-  // sets `dirty` (no queue — bursts collapse to one follow-up, latest wins);
-  // the next shot won't start until at least one shot-duration (adaptive EWMA)
-  // has passed since the last one began, so a slow capture self-throttles. A
-  // static page produces no pulses, so no shots and no cost.
+  // The screencast is CSS-resolution only, so we DISPLAY device-resolution
+  // screenshots and use stream frames purely as "page changed" pulses. The
+  // backpressure machine lives in createScreenshotLoop; here we just supply the
+  // live session/binary/capability (via refs) and the canvas draw.
   const drawBitmap = useCallback((bitmap: ImageBitmap) => {
     const canvas = canvasRef.current;
     if (!canvas) {
@@ -231,94 +167,16 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     bitmap.close();
     setHasFrame(true);
   }, []);
-  const drawBitmapRef = useRef(drawBitmap);
-  drawBitmapRef.current = drawBitmap;
 
   const screenshotCapableRef = useRef(false);
   screenshotCapableRef.current = !!getPlatform().agentBrowserScreenshot && !!session;
 
-  const screenshotLoop = useMemo(() => {
-    let inFlight = false;
-    let dirty = false;
-    let seq = 0;
-    let lastStart = 0;
-    let avgMs = 120;
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    let disposed = false;
-
-    const display = (dataBase64: string, mime: string, mySeq: number) => {
-      const binary = atob(dataBase64);
-      const bytes = new Uint8Array(binary.length);
-      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
-      createImageBitmap(new Blob([bytes], { type: mime })).then((bitmap) => {
-        // A newer shot landed first (or we're gone) — drop this one.
-        if (disposed || mySeq !== seq) {
-          bitmap.close();
-          return;
-        }
-        drawBitmapRef.current(bitmap);
-      }).catch((err) => console.warn(`[agent-browser] screenshot decode failed:`, err));
-    };
-
-    const take = () => {
-      // Call through the adapter instance — a detached method reference drops
-      // `this` and throws on its internal `requestResponse`.
-      const platform = getPlatform();
-      const sess = sessionRef.current;
-      if (!platform.agentBrowserScreenshot || !sess) return;
-      inFlight = true;
-      dirty = false;
-      const mySeq = ++seq;
-      lastStart = performance.now();
-      platform.agentBrowserScreenshot(sess, { format: 'jpeg', quality: 85 }, binaryPathRef.current).then((res) => {
-        avgMs = avgMs * 0.6 + (performance.now() - lastStart) * 0.4;
-        inFlight = false;
-        if (res.ok && res.dataBase64) display(res.dataBase64, res.mime || 'image/jpeg', mySeq);
-        else console.warn('[agent-browser] screenshot failed:', res.error ?? '(no data)');
-        if (dirty) schedule();
-      }).catch((err) => {
-        console.warn('[agent-browser] screenshot error:', err);
-        inFlight = false;
-        if (dirty) schedule();
-      });
-    };
-
-    const schedule = () => {
-      if (disposed) return;
-      if (inFlight) {
-        dirty = true;
-        return;
-      }
-      // Space shots to ~1.5× the measured capture time since the last START:
-      // the slower capture gets, the more we back off (≈⅔ duty cycle), and the
-      // 50ms floor stops a fast/cached/error return from spinning a tight loop.
-      const floor = Math.max(50, avgMs * 1.5);
-      const wait = lastStart + floor - performance.now();
-      if (wait > 0) {
-        dirty = true;
-        if (timer === undefined) {
-          timer = setTimeout(() => {
-            timer = undefined;
-            if (dirty && !inFlight) take();
-          }, wait);
-        }
-        return;
-      }
-      take();
-    };
-
-    return {
-      pulse: () => {
-        if (disposed || !screenshotCapableRef.current) return;
-        dirty = true;
-        schedule();
-      },
-      dispose: () => {
-        disposed = true;
-        if (timer !== undefined) clearTimeout(timer);
-      },
-    };
-  }, []);
+  const screenshotLoop = useMemo(() => createScreenshotLoop({
+    getSession: () => sessionRef.current,
+    getBinaryPath: () => binaryPathRef.current,
+    isCapable: () => screenshotCapableRef.current,
+    draw: drawBitmap,
+  }), [drawBitmap]);
 
   useEffect(() => () => screenshotLoop.dispose(), [screenshotLoop]);
 
@@ -415,39 +273,6 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     if (syncConfirmedRef.current) setSyncEngaged(false);
   }, []);
 
-  // --- pane registration + spawn animation (shared surface boilerplate) ---
-
-  useEffect(() => {
-    if (!elRef.current) return;
-    paneElements.set(api.id, elRef.current);
-    bumpVersion();
-    return () => {
-      paneElements.delete(api.id);
-      bumpVersion();
-    };
-  }, [api.id, paneElements, bumpVersion]);
-
-  useLayoutEffect(() => {
-    const direction = freshlySpawned.get(api.id);
-    if (!direction) return;
-    freshlySpawned.delete(api.id);
-    const groupEl = api.group?.element;
-    if (!groupEl) return;
-    const className = `pane-spawning-from-${direction}`;
-    const animationName = `pane-spawn-from-${direction}`;
-    groupEl.classList.add(className);
-    const onEnd = (ev: AnimationEvent) => {
-      if (ev.animationName !== animationName) return;
-      groupEl.classList.remove(className);
-      groupEl.removeEventListener('animationend', onEnd);
-    };
-    groupEl.addEventListener('animationend', onEnd);
-    return () => {
-      groupEl.removeEventListener('animationend', onEnd);
-      groupEl.classList.remove(className);
-    };
-  }, [api, freshlySpawned]);
-
   // --- stream connection ---
 
   useEffect(() => {
@@ -461,16 +286,13 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     // render the CSS-resolution screencast frame directly.
     const drawScreencastFrame = (data: string) => {
       const seq = ++frameSeqRef.current;
-      const binary = atob(data);
-      const bytes = new Uint8Array(binary.length);
-      for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
-      createImageBitmap(new Blob([bytes], { type: 'image/jpeg' })).then((bitmap) => {
+      decodeScreencastFrame(data).then((bitmap) => {
         // JPEG decodes are async; drop frames that finished out of order.
         if (disposed || seq !== frameSeqRef.current) {
           bitmap.close();
           return;
         }
-        drawBitmapRef.current(bitmap);
+        drawBitmap(bitmap);
       }).catch(() => {});
     };
 
@@ -496,8 +318,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
         else drawScreencastFrame(msg.data);
       } else if (msg.type === 'status') {
         setStatus({ connected: msg.connected === true, screencasting: msg.screencasting === true });
-        if (msg.connected === false) setConnectionLost(true);
-        else setConnectionLost(false);
+        setConnectionLost(msg.connected === false);
         if (typeof msg.viewportWidth === 'number' && typeof msg.viewportHeight === 'number') {
           deviceRef.current = { width: msg.viewportWidth, height: msg.viewportHeight };
           maybeDisengageSync();
@@ -572,7 +393,7 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
       wsRef.current = null;
       ws?.close();
     };
-  }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen, screenshotLoop]);
+  }, [wsPort, runAgentBrowser, maybeDisengageSync, publishScreen, screenshotLoop, drawBitmap]);
 
   // --- header title follows the active tab ---
 
diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 5e838f8a..932a2beb 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -1,11 +1,8 @@
-import { useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useContext, useEffect, useMemo, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
-import {
-  FreshlySpawnedContext,
-  PaneElementsContext,
-  WallActionsContext,
-} from './wall-context';
+import { usePaneChrome } from './use-pane-chrome';
+import { WallActionsContext } from './wall-context';
 
 type IframePanelParams = {
   surfaceType?: string;
@@ -14,9 +11,8 @@ type IframePanelParams = {
 
 export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelParams>) {
   const actions = useContext(WallActionsContext);
-  const { elements: paneElements, bumpVersion } = useContext(PaneElementsContext);
-  const freshlySpawned = useContext(FreshlySpawnedContext);
   const elRef = useRef<HTMLDivElement>(null);
+  usePaneChrome(api, elRef);
   const url = typeof params?.url === 'string' ? params.url : '';
   const origin = useMemo(() => {
     try {
@@ -42,37 +38,6 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
     return () => clearTimeout(timer);
   }, [url]);
 
-  useEffect(() => {
-    if (!elRef.current) return;
-    paneElements.set(api.id, elRef.current);
-    bumpVersion();
-    return () => {
-      paneElements.delete(api.id);
-      bumpVersion();
-    };
-  }, [api.id, paneElements, bumpVersion]);
-
-  useLayoutEffect(() => {
-    const direction = freshlySpawned.get(api.id);
-    if (!direction) return;
-    freshlySpawned.delete(api.id);
-    const groupEl = api.group?.element;
-    if (!groupEl) return;
-    const className = `pane-spawning-from-${direction}`;
-    const animationName = `pane-spawn-from-${direction}`;
-    groupEl.classList.add(className);
-    const onEnd = (ev: AnimationEvent) => {
-      if (ev.animationName !== animationName) return;
-      groupEl.classList.remove(className);
-      groupEl.removeEventListener('animationend', onEnd);
-    };
-    groupEl.addEventListener('animationend', onEnd);
-    return () => {
-      groupEl.removeEventListener('animationend', onEnd);
-      groupEl.classList.remove(className);
-    };
-  }, [api, freshlySpawned]);
-
   return (
     <div
       ref={elRef}
diff --git a/lib/src/components/wall/TerminalPanel.tsx b/lib/src/components/wall/TerminalPanel.tsx
index 4dc651c7..84980942 100644
--- a/lib/src/components/wall/TerminalPanel.tsx
+++ b/lib/src/components/wall/TerminalPanel.tsx
@@ -1,11 +1,10 @@
-import { useContext, useEffect, useLayoutEffect, useRef } from 'react';
+import { useContext, useRef } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { TerminalPane } from '../TerminalPane';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
+import { usePaneChrome } from './use-pane-chrome';
 import {
-  FreshlySpawnedContext,
   ModeContext,
-  PaneElementsContext,
   WallActionsContext,
   SelectedIdContext,
 } from './wall-context';
@@ -14,41 +13,9 @@ export function TerminalPanel({ api }: IDockviewPanelProps) {
   const mode = useContext(ModeContext);
   const selectedId = useContext(SelectedIdContext);
   const actions = useContext(WallActionsContext);
-  const { elements: paneElements, bumpVersion } = useContext(PaneElementsContext);
-  const freshlySpawned = useContext(FreshlySpawnedContext);
   const isFocused = mode === 'passthrough' && selectedId === api.id;
   const elRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!elRef.current) return;
-    paneElements.set(api.id, elRef.current);
-    bumpVersion();
-    return () => {
-      paneElements.delete(api.id);
-      bumpVersion();
-    };
-  }, [api.id, paneElements, bumpVersion]);
-
-  useLayoutEffect(() => {
-    const direction = freshlySpawned.get(api.id);
-    if (!direction) return;
-    freshlySpawned.delete(api.id);
-    const groupEl = api.group?.element;
-    if (!groupEl) return;
-    const className = `pane-spawning-from-${direction}`;
-    const animationName = `pane-spawn-from-${direction}`;
-    groupEl.classList.add(className);
-    const onEnd = (ev: AnimationEvent) => {
-      if (ev.animationName !== animationName) return;
-      groupEl.classList.remove(className);
-      groupEl.removeEventListener('animationend', onEnd);
-    };
-    groupEl.addEventListener('animationend', onEnd);
-    return () => {
-      groupEl.removeEventListener('animationend', onEnd);
-      groupEl.classList.remove(className);
-    };
-  }, [api, freshlySpawned]);
+  usePaneChrome(api, elRef);
 
   return (
     <div ref={elRef} className={`h-full w-full overflow-hidden bg-terminal-bg ${TERMINAL_BOTTOM_RADIUS_CLASS}`} onMouseDown={() => actions.onClickPanel(api.id)}>
diff --git a/lib/src/components/wall/agent-browser-input.test.ts b/lib/src/components/wall/agent-browser-input.test.ts
new file mode 100644
index 00000000..fd453a82
--- /dev/null
+++ b/lib/src/components/wall/agent-browser-input.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { modifiers, virtualKeyCode } from './agent-browser-input';
+
+describe('virtualKeyCode', () => {
+  it('maps printable OEM keys to their real VK, not the char code', () => {
+    // The footgun: '.'.charCodeAt(0) === 46 === VK_DELETE. The physical-key
+    // table must win so a period types a period.
+    expect(virtualKeyCode('.', 'Period')).toBe(190);
+    expect(virtualKeyCode('.', 'Period')).not.toBe(46);
+    expect(virtualKeyCode(',', 'Comma')).toBe(188);
+    expect(virtualKeyCode('/', 'Slash')).toBe(191);
+    expect(virtualKeyCode(' ', 'Space')).toBe(32);
+  });
+
+  it('maps letters and digits structurally from the physical code', () => {
+    expect(virtualKeyCode('a', 'KeyA')).toBe(65); // VK_A
+    expect(virtualKeyCode('A', 'KeyA')).toBe(65); // shifted shares the code
+    expect(virtualKeyCode('z', 'KeyZ')).toBe(90);
+    expect(virtualKeyCode('1', 'Digit1')).toBe(49); // VK_1
+    expect(virtualKeyCode('1', 'Numpad1')).toBe(97); // VK_NUMPAD1
+  });
+
+  it('maps function and special keys', () => {
+    expect(virtualKeyCode('F1', 'F1')).toBe(112);
+    expect(virtualKeyCode('F12', 'F12')).toBe(123);
+    expect(virtualKeyCode('Enter', 'Enter')).toBe(13);
+    expect(virtualKeyCode('ArrowLeft', 'ArrowLeft')).toBe(37);
+    expect(virtualKeyCode('Escape', 'Escape')).toBe(27);
+  });
+
+  it('falls back to 0 for unknown keys', () => {
+    expect(virtualKeyCode('Unidentified', 'Unidentified')).toBe(0);
+  });
+});
+
+describe('modifiers', () => {
+  it('packs alt/ctrl/meta/shift into the CDP bitmask', () => {
+    expect(modifiers({ altKey: false, ctrlKey: false, metaKey: false, shiftKey: false })).toBe(0);
+    expect(modifiers({ altKey: true, ctrlKey: false, metaKey: false, shiftKey: false })).toBe(1);
+    expect(modifiers({ altKey: false, ctrlKey: true, metaKey: false, shiftKey: false })).toBe(2);
+    expect(modifiers({ altKey: false, ctrlKey: false, metaKey: true, shiftKey: false })).toBe(4);
+    expect(modifiers({ altKey: false, ctrlKey: false, metaKey: false, shiftKey: true })).toBe(8);
+    expect(modifiers({ altKey: true, ctrlKey: true, metaKey: true, shiftKey: true })).toBe(15);
+  });
+});
diff --git a/lib/src/components/wall/agent-browser-input.ts b/lib/src/components/wall/agent-browser-input.ts
new file mode 100644
index 00000000..9273b290
--- /dev/null
+++ b/lib/src/components/wall/agent-browser-input.ts
@@ -0,0 +1,74 @@
+/**
+ * Pure keyboard/mouse → agent-browser stream-input translation. Kept out of the
+ * panel so the mapping (especially the windows-virtual-key table, which has a
+ * nasty `.`=VK_DELETE footgun) is independently testable.
+ */
+
+// `text` is what makes typing land; windowsVirtualKeyCode is what makes
+// non-text keys and modifier chords act. Keyed by KeyboardEvent.key.
+export const SPECIAL_KEYS: Record<string, { text?: string; keyCode: number }> = {
+  Enter: { text: '\r', keyCode: 13 },
+  Tab: { text: '\t', keyCode: 9 },
+  Backspace: { text: '\b', keyCode: 8 },
+  Escape: { keyCode: 27 },
+  ArrowLeft: { keyCode: 37 },
+  ArrowUp: { keyCode: 38 },
+  ArrowRight: { keyCode: 39 },
+  ArrowDown: { keyCode: 40 },
+  Delete: { keyCode: 46 },
+  Insert: { keyCode: 45 },
+  Home: { keyCode: 36 },
+  End: { keyCode: 35 },
+  PageUp: { keyCode: 33 },
+  PageDown: { keyCode: 34 },
+  Shift: { keyCode: 16 },
+  Control: { keyCode: 17 },
+  Alt: { keyCode: 18 },
+  Meta: { keyCode: 91 },
+  CapsLock: { keyCode: 20 },
+  ContextMenu: { keyCode: 93 },
+};
+
+// Windows virtual-key codes for printable keys, keyed by KeyboardEvent.code
+// (the physical key, so shifted variants share an entry). Letters and digits
+// are handled structurally in virtualKeyCode. Never derive a VK from
+// `key.charCodeAt(0)`: '.' is 46, which is VK_DELETE — the daemon deletes
+// instead of typing a period.
+export const OEM_VK_BY_CODE: Record<string, number> = {
+  Space: 32,
+  Semicolon: 186,
+  Equal: 187,
+  Comma: 188,
+  Minus: 189,
+  Period: 190,
+  Slash: 191,
+  Backquote: 192,
+  BracketLeft: 219,
+  Backslash: 220,
+  BracketRight: 221,
+  Quote: 222,
+  NumpadDecimal: 110,
+  NumpadDivide: 111,
+  NumpadMultiply: 106,
+  NumpadSubtract: 109,
+  NumpadAdd: 107,
+};
+
+export function virtualKeyCode(key: string, code: string): number {
+  const special = SPECIAL_KEYS[key];
+  if (special) return special.keyCode;
+  if (/^Key[A-Z]$/.test(code)) return code.charCodeAt(3);
+  if (/^(Digit|Numpad)[0-9]$/.test(code)) return code.charCodeAt(code.length - 1) + (code.startsWith('Numpad') ? 48 : 0);
+  if (/^F([1-9]|1[0-2])$/.test(code)) return 111 + Number(code.slice(1));
+  return OEM_VK_BY_CODE[code] ?? 0;
+}
+
+// Cmd/Ctrl + these map to native editing ops the stream input path can't do.
+export const EDIT_OPS = { a: 'selectAll', c: 'copy', x: 'cut' } as const;
+
+export const MOUSE_BUTTONS: Record<number, string> = { 0: 'left', 1: 'middle', 2: 'right' };
+export const MOUSE_BUTTON_MASKS: Record<number, number> = { 0: 1, 1: 4, 2: 2 };
+
+export function modifiers(e: { altKey: boolean; ctrlKey: boolean; metaKey: boolean; shiftKey: boolean }): number {
+  return (e.altKey ? 1 : 0) | (e.ctrlKey ? 2 : 0) | (e.metaKey ? 4 : 0) | (e.shiftKey ? 8 : 0);
+}
diff --git a/lib/src/components/wall/agent-browser-screenshot-loop.ts b/lib/src/components/wall/agent-browser-screenshot-loop.ts
new file mode 100644
index 00000000..399f98a7
--- /dev/null
+++ b/lib/src/components/wall/agent-browser-screenshot-loop.ts
@@ -0,0 +1,108 @@
+import { getPlatform } from '../../lib/platform';
+
+export interface ScreenshotLoopDeps {
+  getSession: () => string | undefined;
+  getBinaryPath: () => string | undefined;
+  isCapable: () => boolean;
+  draw: (bitmap: ImageBitmap) => void;
+}
+
+export interface ScreenshotLoop {
+  /** A "page changed" signal — schedule a fresh shot (coalesced + throttled). */
+  pulse(): void;
+  dispose(): void;
+}
+
+/**
+ * Display crisp HiDPI screenshots, paced by stream-frame "pulses". The
+ * screencast is CSS-resolution only (Chromium's `Page.startScreencast` ignores
+ * deviceScaleFactor), so the panel uses its frames only as change signals and
+ * displays device-resolution screenshots captured via the host.
+ *
+ * Backpressure (we only ever want the latest, and must slow down if capture
+ * can't keep up): at most one screenshot in flight; a pulse during a shot sets
+ * `dirty` (no queue — bursts collapse to one follow-up, latest wins); the next
+ * shot won't start until at least one shot-duration (adaptive EWMA) has passed
+ * since the last one began, so a slow capture self-throttles. A static page
+ * produces no pulses, so no shots and no cost.
+ */
+export function createScreenshotLoop(deps: ScreenshotLoopDeps): ScreenshotLoop {
+  let inFlight = false;
+  let dirty = false;
+  let seq = 0;
+  let lastStart = 0;
+  let avgMs = 120;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+
+  const display = (bytes: Uint8Array, mime: string, mySeq: number) => {
+    // The bytes are ArrayBuffer-backed (readFile → structured clone); narrow off
+    // the ArrayBufferLike default so they satisfy BlobPart.
+    const part = bytes as Uint8Array<ArrayBuffer>;
+    createImageBitmap(new Blob([part], { type: mime })).then((bitmap) => {
+      // A newer shot landed first (or we're gone) — drop this one.
+      if (disposed || mySeq !== seq) {
+        bitmap.close();
+        return;
+      }
+      deps.draw(bitmap);
+    }).catch((err) => console.warn('[agent-browser] screenshot decode failed:', err));
+  };
+
+  const take = () => {
+    const platform = getPlatform();
+    const session = deps.getSession();
+    if (!platform.agentBrowserScreenshot || !session) return;
+    inFlight = true;
+    dirty = false;
+    const mySeq = ++seq;
+    lastStart = performance.now();
+    platform.agentBrowserScreenshot(session, { format: 'jpeg', quality: 85 }, deps.getBinaryPath()).then((res) => {
+      avgMs = avgMs * 0.6 + (performance.now() - lastStart) * 0.4;
+      inFlight = false;
+      if (res.ok && res.bytes) display(res.bytes, res.mime || 'image/jpeg', mySeq);
+      else console.warn('[agent-browser] screenshot failed:', res.error ?? '(no data)');
+      if (dirty) schedule();
+    }).catch((err) => {
+      console.warn('[agent-browser] screenshot error:', err);
+      inFlight = false;
+      if (dirty) schedule();
+    });
+  };
+
+  const schedule = () => {
+    if (disposed) return;
+    if (inFlight) {
+      dirty = true;
+      return;
+    }
+    // Space shots to ~1.5× the measured capture time since the last START: the
+    // slower capture gets, the more we back off (≈⅔ duty cycle), and the 50ms
+    // floor stops a fast/cached/error return from spinning a tight loop.
+    const floor = Math.max(50, avgMs * 1.5);
+    const wait = lastStart + floor - performance.now();
+    if (wait > 0) {
+      dirty = true;
+      if (timer === undefined) {
+        timer = setTimeout(() => {
+          timer = undefined;
+          if (dirty && !inFlight) take();
+        }, wait);
+      }
+      return;
+    }
+    take();
+  };
+
+  return {
+    pulse: () => {
+      if (disposed || !deps.isCapable()) return;
+      dirty = true;
+      schedule();
+    },
+    dispose: () => {
+      disposed = true;
+      if (timer !== undefined) clearTimeout(timer);
+    },
+  };
+}
diff --git a/lib/src/components/wall/use-pane-chrome.ts b/lib/src/components/wall/use-pane-chrome.ts
new file mode 100644
index 00000000..675c7f0e
--- /dev/null
+++ b/lib/src/components/wall/use-pane-chrome.ts
@@ -0,0 +1,51 @@
+import { useContext, useEffect, useLayoutEffect, type RefObject } from 'react';
+import type { IDockviewPanelProps } from 'dockview-react';
+import { FreshlySpawnedContext, PaneElementsContext } from './wall-context';
+
+/**
+ * Shared surface-pane boilerplate used by every panel component
+ * (terminal / iframe / agent-browser):
+ *
+ * - registers the pane's root element in `PaneElementsContext` so overlays can
+ *   measure it, and unregisters on unmount;
+ * - runs the `pane-spawn-from-<direction>` animation once when the pane was
+ *   freshly spawned.
+ */
+export function usePaneChrome(
+  api: IDockviewPanelProps['api'],
+  elRef: RefObject<HTMLDivElement | null>,
+): void {
+  const { elements: paneElements, bumpVersion } = useContext(PaneElementsContext);
+  const freshlySpawned = useContext(FreshlySpawnedContext);
+
+  useEffect(() => {
+    if (!elRef.current) return;
+    paneElements.set(api.id, elRef.current);
+    bumpVersion();
+    return () => {
+      paneElements.delete(api.id);
+      bumpVersion();
+    };
+  }, [api.id, paneElements, bumpVersion, elRef]);
+
+  useLayoutEffect(() => {
+    const direction = freshlySpawned.get(api.id);
+    if (!direction) return;
+    freshlySpawned.delete(api.id);
+    const groupEl = api.group?.element;
+    if (!groupEl) return;
+    const className = `pane-spawning-from-${direction}`;
+    const animationName = `pane-spawn-from-${direction}`;
+    groupEl.classList.add(className);
+    const onEnd = (ev: AnimationEvent) => {
+      if (ev.animationName !== animationName) return;
+      groupEl.classList.remove(className);
+      groupEl.removeEventListener('animationend', onEnd);
+    };
+    groupEl.addEventListener('animationend', onEnd);
+    return () => {
+      groupEl.removeEventListener('animationend', onEnd);
+      groupEl.classList.remove(className);
+    };
+  }, [api, freshlySpawned]);
+}
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index a16375a4..e7cd98aa 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -48,8 +48,9 @@ export const AGENT_BROWSER_ALLOWED_SUBCOMMANDS = ['tab', 'set', 'screenshot', 'c
 
 export interface AgentBrowserScreenshotResult {
   ok: boolean;
-  /** base64-encoded image bytes (no data: prefix); present iff ok. */
-  dataBase64?: string;
+  /** Raw image bytes (transferred over the host↔webview channel via structured
+   *  clone, so no base64 round-trip); present iff ok. */
+  bytes?: Uint8Array;
   /** e.g. 'image/jpeg' | 'image/png'. */
   mime?: string;
   error?: string;
diff --git a/lib/src/lib/platform/vscode-adapter.ts b/lib/src/lib/platform/vscode-adapter.ts
index a77ff3f4..80cf6fb7 100644
--- a/lib/src/lib/platform/vscode-adapter.ts
+++ b/lib/src/lib/platform/vscode-adapter.ts
@@ -246,7 +246,7 @@ export class VSCodeAdapter implements PlatformAdapter {
     const result = await this.requestResponse<AgentBrowserScreenshotResult>(
       'agentBrowser:screenshot', 'agentBrowser:screenshotResult',
       { session, format: opts.format, quality: opts.quality, binaryPath },
-      (msg) => ({ ok: msg.ok, dataBase64: msg.dataBase64, mime: msg.mime, error: msg.error }),
+      (msg) => ({ ok: msg.ok, bytes: msg.bytes, mime: msg.mime, error: msg.error }),
       10000,
     );
     return result ?? { ok: false, error: 'agent-browser screenshot timed out' };
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index 84614ad2..ef5defa1 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -41,7 +41,7 @@ export interface AgentBrowserEditResult {
 
 export interface AgentBrowserScreenshotResult {
   ok: boolean;
-  dataBase64?: string;
+  bytes?: Uint8Array;
   mime?: string;
   error?: string;
 }
@@ -133,8 +133,11 @@ export async function runAgentBrowserScreenshot(
     return { ok: false, error: result.stderr.trim() || `screenshot exited ${result.exitCode}` };
   }
   try {
-    const bytes = await fs.readFile(out);
-    return { ok: true, dataBase64: bytes.toString('base64'), mime: format === 'png' ? 'image/png' : 'image/jpeg' };
+    const buffer = await fs.readFile(out);
+    // A Uint8Array view over exactly this file's bytes; structured-clone copies
+    // it across the webview boundary (no base64 round-trip).
+    const bytes = new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+    return { ok: true, bytes, mime: format === 'png' ? 'image/png' : 'image/jpeg' };
   } catch (err) {
     log.info(`[agent-browser] screenshot read failed: ${err instanceof Error ? err.message : String(err)}`);
     return { ok: false, error: `could not read screenshot file: ${err instanceof Error ? err.message : String(err)}` };
diff --git a/vscode-ext/src/message-types.ts b/vscode-ext/src/message-types.ts
index 01391ec3..73f640cd 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -60,7 +60,7 @@ export type ExtensionMessage =
   | { type: 'clipboard:image'; path: string | null; requestId: string }
   | { type: 'agentBrowser:commandResult'; requestId: string; exitCode: number; stdout: string; stderr: string }
   | { type: 'agentBrowser:editResult'; requestId: string; ok: boolean; text?: string; error?: string }
-  | { type: 'agentBrowser:screenshotResult'; requestId: string; ok: boolean; dataBase64?: string; mime?: string; error?: string }
+  | { type: 'agentBrowser:screenshotResult'; requestId: string; ok: boolean; bytes?: Uint8Array; mime?: string; error?: string }
   | { type: 'agentBrowser:streamUrl'; requestId: string; url: string | null }
   | {
       type: 'dormouse:newTerminal';

From 1f8cd0f1d96cabfdc29cb83c17d938eafca5fc1e Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 12:29:26 -0700
Subject: [PATCH 20/25] stories: AgentBrowserScreenModal (Sync / Device /
 Custom)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Storybook story for the screen/viewport modal, backed by a standalone mock
ScreenController (fixed, memoised snapshot — no registry). Variants cover the
pre-selection branches and degradation: Synced (pre-selects Sync), ScaledCustom
(pre-selects Custom prefilled with live dims), PhoneViewport, and HostIncapable
(Apply disabled + dor-ab note).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../AgentBrowserScreenModal.stories.tsx       | 128 ++++++++++++++++++
 1 file changed, 128 insertions(+)
 create mode 100644 lib/src/stories/AgentBrowserScreenModal.stories.tsx

diff --git a/lib/src/stories/AgentBrowserScreenModal.stories.tsx b/lib/src/stories/AgentBrowserScreenModal.stories.tsx
new file mode 100644
index 00000000..3369a33b
--- /dev/null
+++ b/lib/src/stories/AgentBrowserScreenModal.stories.tsx
@@ -0,0 +1,128 @@
+import { useMemo } from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { AgentBrowserScreenModal } from '../components/wall/AgentBrowserScreenModal';
+import type { ScreenController, ScreenSnapshot, ScreenState } from '../components/wall/agent-browser-screen';
+
+interface StoryArgs {
+  state: ScreenState;
+  /** Browser CSS viewport + inferred DPR. */
+  vpW: number;
+  vpH: number;
+  vpDpr: number;
+  /** Pane CSS size. */
+  paneW: number;
+  paneH: number;
+  /** Dormouse window DPR. */
+  displayDpr: number;
+  syncEngaged: boolean;
+  /** false ⇒ host can't drive the viewport (Tauri) ⇒ Apply disabled + note. */
+  hostCapable: boolean;
+}
+
+// A standalone controller backed by a fixed snapshot — no registry, no live
+// updates. `snapshot()` must return a stable reference for useSyncExternalStore,
+// so it's memoised per args.
+function useMockController(args: StoryArgs): ScreenController {
+  return useMemo<ScreenController>(() => {
+    const snapshot: ScreenSnapshot = {
+      state: args.state,
+      viewport: { w: args.vpW, h: args.vpH, dpr: args.vpDpr },
+      paneCss: { w: args.paneW, h: args.paneH },
+      displayDpr: args.displayDpr,
+      syncEngaged: args.syncEngaged,
+    };
+    return {
+      id: 'story',
+      subscribe: () => () => {},
+      snapshot: () => snapshot,
+      hostCapable: args.hostCapable,
+      actions: {
+        engageSync: () => console.log('[story] engageSync'),
+        applyDevice: (name) => console.log('[story] applyDevice', name),
+        applyViewport: (w, h, dpr) => console.log('[story] applyViewport', w, h, dpr),
+        openModal: () => {},
+      },
+    };
+  }, [args.state, args.vpW, args.vpH, args.vpDpr, args.paneW, args.paneH, args.displayDpr, args.syncEngaged, args.hostCapable]);
+}
+
+function AgentBrowserScreenModalStory(args: StoryArgs) {
+  const controller = useMockController(args);
+  return (
+    <div className="relative h-[560px] w-[760px] overflow-hidden rounded bg-app-bg font-mono text-terminal-fg">
+      <div className="p-4 text-sm text-muted">agent-browser surface — click the SYNCED/SCALED chip to open this.</div>
+      <AgentBrowserScreenModal controller={controller} label="surface:3" onClose={() => console.log('[story] close')} />
+    </div>
+  );
+}
+
+const meta: Meta<typeof AgentBrowserScreenModalStory> = {
+  title: 'Modals/AgentBrowserScreenModal',
+  component: AgentBrowserScreenModalStory,
+  argTypes: {
+    state: { control: 'inline-radio', options: ['SYNCED', 'SCALED'] },
+    vpW: { control: 'number' },
+    vpH: { control: 'number' },
+    vpDpr: { control: 'number' },
+    paneW: { control: 'number' },
+    paneH: { control: 'number' },
+    displayDpr: { control: 'number' },
+    syncEngaged: { control: 'boolean' },
+    hostCapable: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof AgentBrowserScreenModalStory>;
+
+// Synced + matching ⇒ pre-selects "Sync to pane".
+export const Synced: Story = {
+  args: {
+    state: 'SYNCED',
+    vpW: 980, vpH: 560, vpDpr: 2,
+    paneW: 980, paneH: 560,
+    displayDpr: 2,
+    syncEngaged: true,
+    hostCapable: true,
+  },
+};
+
+// Scaled (an external `set viewport` took over) ⇒ pre-selects Custom, prefilled
+// with the live browser dims.
+export const ScaledCustom: Story = {
+  args: {
+    state: 'SCALED',
+    vpW: 1280, vpH: 720, vpDpr: 1,
+    paneW: 980, paneH: 560,
+    displayDpr: 2,
+    syncEngaged: false,
+    hostCapable: true,
+  },
+};
+
+// A phone-emulating viewport (e.g. after `set device "iPhone 16"`). Still
+// pre-selects Custom (devices can't be pre-matched without a dims map), but the
+// Device list is the obvious next pick.
+export const PhoneViewport: Story = {
+  args: {
+    state: 'SCALED',
+    vpW: 393, vpH: 852, vpDpr: 3,
+    paneW: 980, paneH: 560,
+    displayDpr: 2,
+    syncEngaged: false,
+    hostCapable: true,
+  },
+};
+
+// Host can't drive the viewport (Tauri) ⇒ Apply is disabled and a note points
+// the user at `dor ab set …`.
+export const HostIncapable: Story = {
+  args: {
+    state: 'SCALED',
+    vpW: 1280, vpH: 720, vpDpr: 1,
+    paneW: 980, paneH: 560,
+    displayDpr: 2,
+    syncEngaged: false,
+    hostCapable: false,
+  },
+};

From d684354c288dfc1a3a7ddc5f33b2b94ebd447fb8 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 12:35:22 -0700
Subject: [PATCH 21/25] agent-browser: icon the screen indicator
 (FrameCorners=synced, Resize=scaled)

Replace the SYNCED/SCALED text chip with header-sized icons (FrameCornersIcon
for SYNCED, ResizeIcon for SCALED), matching the other header action buttons.
State stays conveyed via aria-label + tooltip.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/components/wall/SurfacePaneHeader.tsx | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/lib/src/components/wall/SurfacePaneHeader.tsx b/lib/src/components/wall/SurfacePaneHeader.tsx
index 2c5495c8..cab7dd40 100644
--- a/lib/src/components/wall/SurfacePaneHeader.tsx
+++ b/lib/src/components/wall/SurfacePaneHeader.tsx
@@ -4,6 +4,8 @@ import {
   ArrowLineDownIcon,
   ArrowsInIcon,
   ArrowsOutIcon,
+  FrameCornersIcon,
+  ResizeIcon,
   SplitHorizontalIcon,
   SplitVerticalIcon,
   XIcon,
@@ -47,10 +49,12 @@ export function SurfacePaneHeader({ api }: IDockviewPanelHeaderProps) {
           type="button"
           onClick={(e) => { e.stopPropagation(); screen.actions.openModal(); }}
           aria-label={`Screen: ${screenSnapshot.state} — change viewport`}
-          title="Screen / viewport"
-          className="shrink-0 rounded px-1 py-0.5 text-xs leading-none font-semibold tracking-[0.08em] text-current/70 transition-colors hover:bg-current/10 hover:text-current"
+          title={`Screen: ${screenSnapshot.state} — change viewport`}
+          className="flex h-5 min-w-5 shrink-0 items-center justify-center rounded text-current/70 transition-colors hover:bg-current/10 hover:text-current"
         >
-          {screenSnapshot.state}
+          {screenSnapshot.state === 'SYNCED'
+            ? <FrameCornersIcon size={14} />
+            : <ResizeIcon size={14} />}
         </button>
       )}
       <div className="ml-1 hidden shrink-0 items-center gap-0.5 min-[420px]:flex">

From f2d4f88cf92208f40a17a34bf53b423612c3d7c7 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 12:41:58 -0700
Subject: [PATCH 22/25] Remove DOR_AGENT_BROWSER.md implementation plan
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phases 1–9 are landed and the forward-looking pop-out design lives in the spec
(docs/specs/dor-agent-browser.md → Headed Pop-Out), so the working plan doc has
served its purpose.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 DOR_AGENT_BROWSER.md | 97 --------------------------------------------
 1 file changed, 97 deletions(-)
 delete mode 100644 DOR_AGENT_BROWSER.md

diff --git a/DOR_AGENT_BROWSER.md b/DOR_AGENT_BROWSER.md
deleted file mode 100644
index d3261724..00000000
--- a/DOR_AGENT_BROWSER.md
+++ /dev/null
@@ -1,97 +0,0 @@
-# DOR_AGENT_BROWSER — Implementation Plan
-
-The `dor agent-browser` / `dor ab` surface is **built and shipped**. Its design
-and current behavior are described in
-[`docs/specs/dor-agent-browser.md`](docs/specs/dor-agent-browser.md) — that spec
-is the source of truth. This doc tracks only the **remaining build work**; the
-spec's "Future Expansions" section is the design for it.
-
-## Dev loop
-
-- `agent-browser` on `PATH` (`agent-browser --version`; tested against `0.27.0`).
-- CLI-only iteration: `cd dor && pnpm build && node --test test/cli-output.test.mjs`.
-- Lib unit tests: `cd lib && npx vitest run`.
-- Full app: `pnpm build:vscode` then `pnpm --filter dormouse dogfood`, then reload
-  the VS Code window. Standalone: smoke-test the Tauri build separately.
-- Channel behaviors (frames/input/tabs/screenshots) are mostly manual against a
-  live `agent-browser`; the probes under `~/.agent-browser/tmp/probe-*.mjs` are
-  the harness for protocol questions.
-
----
-
-## Phase 10 — Headed pop-out (planned)
-
-**Spec:** "Future Expansions → Headed Pop-Out". A header affordance that
-relaunches the surface's browser **headed** as a real OS window the user drives
-directly; the Dormouse pane becomes a clean placeholder. GUI-only,
-`randomKillChar()`-confirmed, platform-gated. **Build leaf-up; desktop-only
-(Tauri-first), degraded in VS Code, hidden on web.**
-
-### 10pre — Profile-persistence spike (prerequisite-ish)
-
-- Without it, pop-out drops cookies/login (ephemeral temp profile), so it's
-  frustrating for authenticated sites. Spike a stable per-session user-data-dir
-  (or `agent-browser state save`/`load`) so logins survive the relaunch.
-- Decoupled from the v1 ship (v1 = URLs-only), but the first thing that makes
-  pop-out genuinely useful. Also benefits the streamed surface (logins survive
-  daemon restarts). Land before or shortly after 10a–10f.
-
-### 10a — Host capability: headed relaunch + window control
-
-- New optional `PlatformAdapter` methods (mirror `agentBrowserScreenshot`):
-  relaunch a session **headed** with window-position args, **raise** a window
-  (by session/process), and resolve the **pane→screen rectangle** (Tauri only).
-- Allowlist the headed `open`/launch path; degrade where unimplemented.
-- **Verify:** from a terminal/host call, a session reopens headed as a window.
-
-### 10b — Affordance + confirm
-
-- Pop-out arrow in `SurfacePaneHeader` action cluster, agent-browser surfaces
-  only, gated on host capability (hidden on web). Click → `randomKillChar()`
-  overlay (mirror `KillConfirm`/`KillConfirmOverlay`).
-- **Verify:** chip shows only on browser surfaces with a capable host; confirm
-  overlay gates the action.
-
-### 10c — Relaunch headed + reopen tabs + position
-
-- Capture the ordered tab URL list (+ active) from the live `tabs` stream.
-- Keep the session name; relaunch headed; reopen each URL in order, focus the
-  active one. Best-effort position over the pane rect; **center on monitor**
-  when coords are unavailable (always VS Code, always Wayland).
-- **Verify:** pop-out reopens all tabs in order; lands over the pane (Tauri/mac)
-  or centered (VS Code).
-
-### 10d — Pane placeholder mode
-
-- Clean placeholder copy; **Bring to front** (host raise) + **Pop back in**
-  (closes the window → 10e revert). Stream stays connected for `tabs`/`status`
-  only; frame display / screenshots / input / chip / tab strip inert.
-- **Verify:** popped-out pane shows placeholder; bring-to-front raises; pop back
-  in returns to headless.
-
-### 10e — Lifecycle
-
-- Headed window ends (any gesture) → **auto-revert**: relaunch headless, resume
-  streaming, reopen the **last non-empty tab list**. Decoupled from teardown.
-- `dor kill` / pane `×` → the only teardown (close window + session).
-- App quit → clean up headed windows (no orphans).
-- **Verify:** close window (1 tab) → that tab returns headless; close 3-tab
-  window → 3 return; `dor kill` ends it; quitting leaves no stray Chrome.
-
-### 10f — Cross-platform gating
-
-- VS Code: spawns headed but can't position → center; bring-to-front best-effort.
-- Wayland: center, raise may be unavailable. Windows: per-monitor/fractional DPI
-  math for pane→window. Web: affordance hidden.
-- **Verify (needs real hardware):** Windows high-DPI placement; a Wayland session
-  centers and doesn't crash; macOS positions over the pane.
-
-### Definition of done (Phase 10)
-
-- Pop-out relaunches headed, reopens tabs in order, positions best-effort.
-- Pane is a clean placeholder with bring-to-front + pop-back-in.
-- Any window-end auto-reverts to headless (last non-empty tabs); only `dor kill`
-  tears down; no orphan windows on quit.
-- Confirmed via `randomKillChar()`; GUI-only; platform-gated with graceful
-  degradation.
-- (Stretch) profile persistence so logins survive the relaunch.

From fbae5f81fc82a68d795fcb9f98a5f43fb4546183 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 12:59:20 -0700
Subject: [PATCH 23/25] agent-browser: tokenize the VS Code stream relay
 (one-use grants)

The loopback relay previously accepted any /stream/<port> upgrade, so any
local process could pipe to an arbitrary stream port through it. Mint a
short-lived, single-use token+port grant per surface: getAgentBrowserStreamUrl
now hands back ws://127.0.0.1:<relayPort>/stream/<streamPort>/<token>, and the
relay rejects (403) any request whose token/port doesn't match an unexpired
grant, consuming it on use. Grants are swept lazily.

Also:
- reset knownTabIds on (re)connect so stale tab ids don't suppress popups
  after a stream reconnect
- dedup AgentBrowser{Command,Edit,Screenshot}Result / EditOp and the
  subcommand allowlist in agent-browser-host against the canonical
  definitions in lib platform/types (single source of truth)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md               | 10 ++-
 lib/src/components/wall/AgentBrowserPanel.tsx |  2 +
 lib/src/lib/platform/types.ts                 |  4 +-
 vscode-ext/src/agent-browser-host.ts          | 83 ++++++++++++-------
 vscode-ext/src/message-router.ts              |  8 +-
 5 files changed, 67 insertions(+), 40 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 717a4449..2fc79890 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -413,10 +413,12 @@ CSP alone is not enough in VS Code: the agent-browser stream server rejects
 WebSocket upgrades whose `Origin` is not localhost-or-absent (verified against
 0.27.0: `vscode-webview://…` → 403; `tauri://localhost` and plain localhost →
 allowed; no override env var exists). The VS Code extension host therefore runs
-a loopback-only TCP relay that strips the `Origin` header and pipes bytes to
-`127.0.0.1:<streamPort>`; `getAgentBrowserStreamUrl` returns the relay URL
-(`ws://127.0.0.1:<relayPort>/stream/<streamPort>`). The standalone (Tauri)
-webview connects directly — its origin is allowed.
+a loopback-only TCP relay that strips the `Origin` header and pipes bytes only
+to a stream port it has explicitly authorized. `getAgentBrowserStreamUrl` asks
+the host for a short-lived, one-use relay URL
+(`ws://127.0.0.1:<relayPort>/stream/<streamPort>/<token>`); the relay rejects
+requests without a matching token/port grant. The standalone (Tauri) webview
+connects directly — its origin is allowed.
 
 ---
 
diff --git a/lib/src/components/wall/AgentBrowserPanel.tsx b/lib/src/components/wall/AgentBrowserPanel.tsx
index 155f35c3..4bed9745 100644
--- a/lib/src/components/wall/AgentBrowserPanel.tsx
+++ b/lib/src/components/wall/AgentBrowserPanel.tsx
@@ -282,6 +282,8 @@ export function AgentBrowserPanel({ api, params }: IDockviewPanelProps<AgentBrow
     let retryTimer: ReturnType<typeof setTimeout> | undefined;
     let failures = 0;
 
+    knownTabIdsRef.current = new Set();
+
     // Fallback only (hosts without the screenshot capability, e.g. Tauri):
     // render the CSS-resolution screencast frame directly.
     const drawScreencastFrame = (data: string) => {
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index e7cd98aa..5816d90d 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -127,8 +127,8 @@ export interface PlatformAdapter {
   // the screencast frames directly).
   agentBrowserScreenshot?(session: string, opts: { format?: 'jpeg' | 'png'; quality?: number }, binaryPath?: string): Promise<AgentBrowserScreenshotResult>;
   // The WebSocket URL for a session's stream port. Hosts whose webview origin
-  // the agent-browser stream server rejects (VS Code) return a relay URL;
-  // absent or null falls back to ws://127.0.0.1:<port>.
+  // the agent-browser stream server rejects (VS Code) return a tokenized relay
+  // URL; absent or null falls back to ws://127.0.0.1:<port>.
   getAgentBrowserStreamUrl?(port: number): Promise<string | null>;
 
   // PTY event listeners
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index ef5defa1..acdf21a1 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -8,12 +8,12 @@
  *    session for tab actions and session teardown. Subcommands are
  *    allowlisted; this is not a general exec channel.
  *
- * 2. `ensureStreamRelayPort` — a loopback-only TCP relay that strips the
+ * 2. `createStreamRelayUrl` — a loopback-only TCP relay that strips the
  *    `Origin` header from WebSocket upgrade requests. The agent-browser stream
  *    server returns 403 for `vscode-webview://` origins (only localhost or
  *    absent origins are accepted), so the webview cannot connect directly; it
- *    connects to ws://127.0.0.1:<relayPort>/stream/<streamPort> instead and
- *    the relay pipes bytes to 127.0.0.1:<streamPort>.
+ *    connects to a short-lived tokenized relay URL instead and the relay pipes
+ *    bytes only to the authorized 127.0.0.1:<streamPort>.
  */
 import * as vscode from 'vscode';
 import * as net from 'net';
@@ -21,30 +21,20 @@ import * as os from 'os';
 import * as path from 'path';
 import { promises as fs } from 'fs';
 import { spawn } from 'child_process';
+import { randomBytes } from 'crypto';
 import { log } from './log';
+import {
+  AGENT_BROWSER_ALLOWED_SUBCOMMANDS,
+  type AgentBrowserCommandResult,
+  type AgentBrowserEditOp,
+  type AgentBrowserEditResult,
+  type AgentBrowserScreenshotResult,
+} from '../../lib/src/lib/platform/types';
 
-const ALLOWED_SUBCOMMANDS = new Set(['tab', 'set', 'screenshot', 'close']);
-
-export interface AgentBrowserCommandResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-}
-
-export type AgentBrowserEditOp = 'selectAll' | 'copy' | 'cut';
-
-export interface AgentBrowserEditResult {
-  ok: boolean;
-  text?: string;
-  error?: string;
-}
-
-export interface AgentBrowserScreenshotResult {
-  ok: boolean;
-  bytes?: Uint8Array;
-  mime?: string;
-  error?: string;
-}
+const ALLOWED_SUBCOMMANDS = new Set<string>(AGENT_BROWSER_ALLOWED_SUBCOMMANDS);
+const STREAM_RELAY_TOKEN_BYTES = 32;
+const STREAM_RELAY_GRANT_TTL_MS = 60_000;
+const STREAM_RELAY_GRANT_SWEEP_MS = 30_000;
 
 // The host owns the exact JS for each editing op — the webview only selects a
 // name, so this never becomes an arbitrary-eval channel. copy/cut return the
@@ -186,8 +176,19 @@ function spawnAgentBrowser(binary: string, args: string[]): Promise<AgentBrowser
 }
 
 let relayPortPromise: Promise<number> | null = null;
+const streamRelayGrants = new Map<string, { port: number; expiresAt: number }>();
+let lastStreamRelayGrantSweep = 0;
+
+export async function createStreamRelayUrl(streamPort: number): Promise<string> {
+  const relayPort = await ensureStreamRelayPort();
+  const token = randomBytes(STREAM_RELAY_TOKEN_BYTES).toString('hex');
+  const now = Date.now();
+  sweepStreamRelayGrants(now);
+  streamRelayGrants.set(token, { port: streamPort, expiresAt: now + STREAM_RELAY_GRANT_TTL_MS });
+  return `ws://127.0.0.1:${relayPort}/stream/${streamPort}/${token}`;
+}
 
-export function ensureStreamRelayPort(): Promise<number> {
+function ensureStreamRelayPort(): Promise<number> {
   if (!relayPortPromise) {
     relayPortPromise = new Promise<number>((resolve, reject) => {
       const server = net.createServer(handleRelayClient);
@@ -211,10 +212,27 @@ export function ensureStreamRelayPort(): Promise<number> {
   return relayPortPromise;
 }
 
+function sweepStreamRelayGrants(now = Date.now()): void {
+  if (now - lastStreamRelayGrantSweep < STREAM_RELAY_GRANT_SWEEP_MS) return;
+  lastStreamRelayGrantSweep = now;
+  for (const [token, grant] of streamRelayGrants) {
+    if (grant.expiresAt <= now) streamRelayGrants.delete(token);
+  }
+}
+
+function consumeStreamRelayGrant(token: string, port: number): boolean {
+  const now = Date.now();
+  sweepStreamRelayGrants(now);
+  const grant = streamRelayGrants.get(token);
+  if (!grant) return false;
+  streamRelayGrants.delete(token);
+  return grant.expiresAt > now && grant.port === port;
+}
+
 // The relay is loopback-only on both sides: it accepts connections from
-// 127.0.0.1 and dials only 127.0.0.1:<port>. It rewrites the upgrade request
-// head (path → "/", Origin dropped, Host rewritten) and from then on is a dumb
-// byte pipe in both directions.
+// 127.0.0.1 and dials only an explicitly granted 127.0.0.1:<port>. It rewrites
+// the upgrade request head (path → "/", Origin dropped, Host rewritten) and
+// from then on is a dumb byte pipe in both directions.
 function handleRelayClient(client: net.Socket): void {
   let head = Buffer.alloc(0);
   client.on('error', () => {});
@@ -231,12 +249,17 @@ function handleRelayClient(client: net.Socket): void {
 
     const headText = head.subarray(0, headEnd).toString('latin1');
     const remainder = head.subarray(headEnd + 4);
-    const requestMatch = /^GET \/stream\/(\d{1,5}) HTTP\/1\.1\r\n/.exec(headText);
+    const requestMatch = /^GET \/stream\/(\d{1,5})\/([a-f0-9]{64}) HTTP\/1\.1\r\n/i.exec(headText);
     const targetPort = requestMatch ? Number(requestMatch[1]) : 0;
     if (!targetPort || targetPort > 65535) {
       client.end('HTTP/1.1 400 Bad Request\r\n\r\n');
       return;
     }
+    const token = requestMatch?.[2] ?? '';
+    if (!consumeStreamRelayGrant(token, targetPort)) {
+      client.end('HTTP/1.1 403 Forbidden\r\n\r\n');
+      return;
+    }
 
     const headerLines = headText.split('\r\n').slice(1).filter((line) => {
       const name = line.slice(0, line.indexOf(':')).trim().toLowerCase();
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 25f50820..96c0c987 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -13,7 +13,7 @@ import type { TerminalSemanticEvent } from '../../lib/src/lib/terminal-state';
 import type { PersistedSession } from '../../lib/src/lib/session-types';
 import type { WebviewMessage, ExtensionMessage } from './message-types';
 import type { DorControlRequest } from './pty-manager';
-import { ensureStreamRelayPort, runAgentBrowserCommand, runAgentBrowserEdit, runAgentBrowserScreenshot } from './agent-browser-host';
+import { createStreamRelayUrl, runAgentBrowserCommand, runAgentBrowserEdit, runAgentBrowserScreenshot } from './agent-browser-host';
 import { log } from './log';
 
 const clipboardOps = require('../../lib/clipboard-ops.cjs') as {
@@ -391,10 +391,10 @@ export function attachRouter(
           webview.postMessage({ type: 'agentBrowser:streamUrl', requestId: msg.requestId, url: null } satisfies ExtensionMessage);
           break;
         }
-        ensureStreamRelayPort().then(
-          (relayPort) => webview.postMessage({
+        createStreamRelayUrl(streamPort).then(
+          (url) => webview.postMessage({
             type: 'agentBrowser:streamUrl', requestId: msg.requestId,
-            url: `ws://127.0.0.1:${relayPort}/stream/${streamPort}`,
+            url,
           } satisfies ExtensionMessage),
           () => webview.postMessage({ type: 'agentBrowser:streamUrl', requestId: msg.requestId, url: null } satisfies ExtensionMessage),
         );

From dae3e43b9b564c5ffbbf9045be32fa160bda3958 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 13:15:26 -0700
Subject: [PATCH 24/25] spec: propose browser-chrome header (nav + URL +
 connection)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Future Expansions proposal for the agent-browser surface header: mirror Chrome's
toolbar (sync chip far-left, then back/forward/refresh, then URL), show the URL
instead of the HTML title, badge non-default --key surfaces, and — the
differentiated piece — surface the dev-server connection by correlating a
loopback :port to the Dormouse terminal pane serving it (jump-to-terminal).

Verified against agent-browser 0.27.0 and the codebase:
- back/forward/reload are native commands (history nav confirmed) → just
  allowlist them on agentBrowserCommand, no eval fallback.
- getOpenPorts is fully plumbed + tested but has zero UI consumers — the per-OS
  port detection is done; the correlation store/chip are greenfield.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md | 103 ++++++++++++++++++++++++++++++++
 1 file changed, 103 insertions(+)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index 2fc79890..f4a8072c 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -512,3 +512,106 @@ baseline on every target.
 - **Re-trigger sync from the CLI** — a Dormouse-reserved `dor ab` verb, at the
   cost of the first non-passthrough subcommand.
 - **Undo/redo chords** — blocked on the upstream stream-input `commands` fix.
+
+## Browser-chrome header (nav + URL + connection)
+
+Today the surface header shows the active tab's **HTML `<title>`** and the
+SYNCED/SCALED icon, and offers no navigation. For a dev workflow the HTML title
+("Vite + React") tells you less than the **URL** — and less still than *where the
+URL comes from*. This proposal reshapes the header to read like a browser and to
+surface the one thing only Dormouse can show: that a localhost page is being
+served by another pane in the same workspace.
+
+### Layout — mirror Chrome's toolbar
+
+Left→right, matching a real browser so it reads as "browser-ish":
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│ ⤢   ←  →  ⟳    (storybook) localhost:5173   ◉ pnpm dev          ⬍ ⬌ ⤢   _  ✕ │
+└──────────────────────────────────────────────────────────────────────────────┘
+ sync  back/fwd/    key      URL              dev-server          split/zoom  min/
+ chip  refresh      badge    (host+path)      connection          (collapse)  kill
+```
+
+- **Sync chip → far left.** The SYNCED/SCALED icon (`FrameCorners`/`Resize`,
+  click → screen modal) moves from "right of the title" to the very left edge,
+  out of the way of the new nav controls. Behavior unchanged.
+- **Back / forward / refresh** sit where Chrome puts them, immediately left of
+  the URL.
+- **URL is the primary text**, replacing the HTML title (below). The flexible
+  spacer lives after the URL so the layout buttons stay right-aligned.
+
+All of this is **browser-surface only**, gated on the screen-controller presence
+exactly like today's chip; terminals/iframes are untouched. The header is
+shared (`SurfacePaneHeader.tsx`), and it is already tight and responsive
+(`min-[420px]` collapse). Priority order under width pressure: **sync + URL/
+connection always visible; nav buttons next; split/zoom collapse first** (kill
+stays).
+
+### URL over HTML title
+
+Show the active tab's **URL (host + path)** as the header's primary text;
+**demote the HTML `<title>` to the tooltip**. The URL already rides the `tabs`
+stream (`tabDisplayTitle` even falls back to host+path today) — this just flips
+the preference. The HTML title stays useful in the **multi-tab strip** to tell
+tabs apart, so the change is scoped to the single-surface header.
+
+### `--key` badge
+
+The `--key` (default `default`) is what `dor ab --key … ` targets, so with two
+or more browser surfaces it's exactly what you need to see. Render a small badge
+for **non-default keys only** (skip `default`), as a **separate element — not a
+string prefix on the title** — because the title is persisted (door labels,
+session save) and we don't want `(storybook)` leaking into saved state. It's
+already in `params.key`; raw `--session` surfaces (no key) show nothing (or a
+truncated session) rather than a badge.
+
+### Dev-server connection (the differentiated piece)
+
+When the active tab URL is **loopback** (`localhost` / `127.0.0.1:<port>`),
+correlate `<port>` to the Dormouse **terminal pane serving it** and surface that
+link — e.g. `◉ pnpm dev :5173` — that **jumps to / focuses that terminal** on
+click. Dormouse is the only tool that owns both the browser surface and the
+terminals, and the building block already exists: `PlatformAdapter.getOpenPorts(id)`
+returns the TCP ports a terminal's process tree is listening on. This answers
+"where is this localhost coming from?" and makes the relationship navigable.
+
+Mechanics & wrinkles:
+
+- **Where it lives.** A panel doesn't know other panes' ports, so the
+  port→pane correlation belongs in the **Wall** (or a shared port store the Wall
+  feeds), with the header consuming the resolved `{ paneId, label }`. The header
+  click calls back into the Wall to focus that pane.
+- **The capability exists but is dormant.** `getOpenPorts` is fully plumbed and
+  tested (adapter → message-router → `pty-manager` → per-OS lsof/PowerShell) but
+  currently has **no UI consumer** — so the hard part (per-OS port detection) is
+  done, and this feature is its first consumer; the correlation store + chip are
+  greenfield, nothing to reuse.
+- **Cost.** `getOpenPorts` has a ~3s timeout; polling every pane continuously is
+  wasteful. Compute **on demand only when the active URL is loopback**, on a
+  slow refresh, and cache.
+- **Fallbacks (degrade to just the URL):** non-loopback URL; no pane matches the
+  port; the dev server bound `0.0.0.0`/a specific interface; a tunneled/proxied
+  domain; or (rarely) two panes claiming the port.
+- **Bidirectional (later):** a terminal serving a port could conversely show
+  "viewed in `surface:3`". Out of scope for v1; the port store would make it
+  cheap.
+
+### Back / forward / refresh mechanics
+
+- **All three are native agent-browser commands** — `back`, `forward`, `reload`
+  (verified 0.27.0: `back`/`forward` actually move history). So each is just a
+  new entry on the `agentBrowserCommand` allowlist (`reload`, `back`, `forward`)
+  issued like tab actions — **no eval fallback needed**.
+- **No enabled-state.** `canGoBack`/`canGoForward` are not in the stream, so the
+  buttons are **always enabled** (click no-ops at the ends) rather than greyed —
+  acceptable, matching most embedded browsers. Deriving real enablement would
+  need an extra channel and isn't worth it for v1.
+
+### Touchpoints
+
+`SurfacePaneHeader.tsx` (the browser-only header branch: reorder, nav buttons,
+URL, key badge, connection chip), `Wall.tsx` (new port→pane correlation store +
+focus callback — `getOpenPorts` is already plumbed but unused), and the
+`agentBrowserCommand` allowlist (add `reload`, `back`, `forward`).

From 72de8606667a4db22d24f33b559940b0f40b03a1 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 13:17:24 -0700
Subject: [PATCH 25/25] agent-browser: fix stale "base64" screenshot-transport
 docs (PR #140 review)

The screenshot transport is raw Uint8Array bytes over structured clone, not
base64. Correct the two flagged doc comments (platform types, agent-browser-host)
plus the same stale wording in the spec's host-capabilities list, and tighten the
CSP note ("in-memory image bytes via createImageBitmap" rather than "base64").

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/specs/dor-agent-browser.md      | 10 ++++++----
 lib/src/lib/platform/types.ts        |  2 +-
 vscode-ext/src/agent-browser-host.ts |  2 +-
 3 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/specs/dor-agent-browser.md b/docs/specs/dor-agent-browser.md
index f4a8072c..ab0a3fc9 100644
--- a/docs/specs/dor-agent-browser.md
+++ b/docs/specs/dor-agent-browser.md
@@ -385,8 +385,9 @@ hosts degrade gracefully:
   `close`); this is not a general exec channel.
 - **`agentBrowserScreenshot(session, { format, quality })`** — captures one
   device-resolution frame via `agent-browser screenshot` (which honors the
-  session DPR, unlike the screencast) and returns it base64. Drives the crisp
-  display path; absent ⇒ the panel falls back to rendering screencast frames.
+  session DPR, unlike the screencast) and returns the raw bytes (a `Uint8Array`
+  over structured clone, no base64 round-trip). Drives the crisp display path;
+  absent ⇒ the panel falls back to rendering screencast frames.
 - **`agentBrowserEdit(session, op)`** — host-owned `eval` for the macOS editing
   chords (select-all/copy/cut) the stream input path can't dispatch.
 - **`getAgentBrowserStreamUrl(port)`** — returns the WebSocket URL the webview
@@ -406,8 +407,9 @@ WebSocket:
 connect-src ws://127.0.0.1:* ws://localhost:* <existing cspSource>
 ```
 
-The canvas is drawn from base64 data, so no `img-src` change is needed, and no
-`frame-src` is involved — there is no iframe.
+The canvas is drawn from in-memory image bytes (`createImageBitmap` over a
+`Blob`, never an `<img src>` to an external URL), so no `img-src` change is
+needed, and no `frame-src` is involved — there is no iframe.
 
 CSP alone is not enough in VS Code: the agent-browser stream server rejects
 WebSocket upgrades whose `Origin` is not localhost-or-absent (verified against
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index 5816d90d..601d6e66 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -119,7 +119,7 @@ export interface PlatformAdapter {
   // can't run the binary (degrades to plain key forwarding).
   agentBrowserEdit?(session: string, op: AgentBrowserEditOp, binaryPath?: string): Promise<AgentBrowserEditResult>;
   // Captures a single device-resolution (HiDPI) frame via the user's
-  // agent-browser `screenshot` command and returns it base64-encoded. The
+  // agent-browser `screenshot` command and returns the raw image bytes. The
   // stream's screencast is CSS-resolution only (a Chromium limitation —
   // Page.startScreencast ignores deviceScaleFactor), so the panel displays
   // these crisp screenshots instead, using stream frames only as change
diff --git a/vscode-ext/src/agent-browser-host.ts b/vscode-ext/src/agent-browser-host.ts
index acdf21a1..773959b7 100644
--- a/vscode-ext/src/agent-browser-host.ts
+++ b/vscode-ext/src/agent-browser-host.ts
@@ -99,7 +99,7 @@ function screenshotPath(session: string, ext: string): string {
 
 // Capture one device-resolution frame via the user's agent-browser `screenshot`
 // command (which honors the session's viewport/DPR, unlike the CSS-resolution
-// screencast) and return it base64-encoded. agent-browser writes a file and
+// screencast) and return the raw image bytes. agent-browser writes a file and
 // reports the path; we read it back and hand the bytes to the webview.
 export async function runAgentBrowserScreenshot(
   session: string,