From a311e0f2efe25bf808ff146a410b3c2236838078 Mon Sep 17 00:00:00 2001
From: dormouse-bot <287024035+dormouse-bot@users.noreply.github.com>
Date: Thu, 18 Jun 2026 08:08:12 +0000
Subject: [PATCH 1/2] docs: index dor-iframe and dor-agent-browser specs in
 AGENTS.md

Both surface specs were missing from the AGENTS.md spec index that points
agents to "read the relevant spec before modifying a feature it covers."
dor-iframe.md (added 2026-06-16, extended by #143) and dor-agent-browser.md
(added 2026-06-12) parallel the already-indexed dor-cli.md they build on.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 5956e45f..265a99ae 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,6 +33,8 @@ The primary job of a spec is to be an accurate reference for the current state o
 - **`docs/specs/glossary.md`** — Canonical vocabulary for Session states, layers (Process / Registry / View / Link / Activity / Snapshot), transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state or a verb.
 - **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode behavior.
 - **`docs/specs/dor-cli.md`** - the `dor` CLI which is prepended onto the path of every terminal that dormouse launches.
+- **`docs/specs/dor-agent-browser.md`** — The `dor agent-browser` (`dor ab`) surface: a viewer client that delegates entirely to the user's own agent-browser install, rendering its screencast to a Dormouse-owned `<canvas>`, forwarding mouse/keyboard input, and presenting tabs. Builds on the surface handle model in `dor-cli.md`. Read this when touching: `dor/src/commands/agent-browser.ts`, `lib/src/components/wall/AgentBrowserPanel.tsx`, `lib/src/components/wall/agent-browser-{input,ports,screen,screenshot-loop}.ts`, `lib/src/components/AgentBrowserScreenModalHost.tsx`, `lib/src/components/wall/AgentBrowserScreenModal.tsx`, `vscode-ext/src/agent-browser-host.ts`, or the agent-browser surface wiring in `Wall.tsx`.
+- **`docs/specs/dor-iframe.md`** — The `dor iframe` surface: an `<iframe>` fronted by a host-owned transparent proxy that serves the target's bytes so Dormouse can inject a keyboard side-channel (leader chord + pointerdown), model focus, and render real error pages instead of a blank pane. Builds on the surface handle model in `dor-cli.md`; sibling of `dor-agent-browser.md`. Read this when touching: `dor/src/commands/iframe.ts`, `lib/src/components/wall/IframePanel.tsx`, `lib/src/host/iframe-proxy.ts`, `lib/src/host/iframe-proxy-rewrite.ts`, `lib/src/lib/iframe-proxy-registry.ts`, `lib/src/lib/platform/iframe-proxy-types.ts`, `vscode-ext/src/iframe-proxy-host.ts`, or the iframe surface wiring in `Wall.tsx`.
 - **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle, bell button visual states and interaction, door alert indicators, hardening (a11y, motion, i18n, overflow), notification protocols (`OSC 9` / `OSC 9;4` / `OSC 99` / `OSC 777` / `BEL`), the `ActivityNotification` model, notification text handling and security, and the notification preview/detail UI. Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, `AlertManager` notification/progress paths, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, the `a`/`t` keyboard shortcuts, or TODO notification preview UI. Layout.md defers to this spec for all alert/TODO behavior.
 - **`docs/specs/terminal-state.md`** — Terminal semantic state for CWD, shell prompt/editing/running/finished lifecycle, command runs, terminal title fallback, normalized semantic OSC events (`OSC 7`, `OSC 9;9`, `OSC 133`, `OSC 633`, `OSC 1337`, `OSC 0/2`), title-candidate diagnostics, header derivation, and grouping keys. Read this when touching `terminal-state.ts`, `terminal-state-store.ts`, semantic event parsing in `terminal-protocol.ts`, adapter semantic event forwarding, or derived pane/door labels.
 - **`docs/specs/terminal-escapes.md`** — Registry of every terminal escape sequence Dormouse parses or responds to: supported OSCs with pointers to the spec defining their behavior (alert.md or terminal-state.md), the canonical parsing-location and `pty:data` strip semantics, supported CSI sequences (`CSI > q`, DECSET/DECRST observation, kitty keyboard protocol) and replay-time CSI filtering, iTerm2 self-identification (env vars, fail-inertly rule), and known-unimplemented iTerm2 and clipboard-capable sequences. Read this when touching: OSC parsing at the PTY data boundary, CSI handlers in `terminal-protocol.ts` / `mouse-mode-observer.ts` / `terminal-report-filter.ts`, the iTerm2 identity env vars (`TERM_PROGRAM`, `LC_TERMINAL`), or adding support for a new escape sequence.

From 603b6126289bf70c6ba3b6bfabedf245df865895 Mon Sep 17 00:00:00 2001
From: dormouse-bot <dormouse-bot@users.noreply.github.com>
Date: Fri, 19 Jun 2026 23:04:38 +0000
Subject: [PATCH 2/2] docs: index unified dor-browser spec after #156 merge

#156 removed dor-iframe.md and dor-agent-browser.md, replacing both with
dor-browser.md. Merge main and collapse the two index entries into one
pointing at the unified browser surface spec.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENTS.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 265a99ae..d51365a9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -33,8 +33,7 @@ The primary job of a spec is to be an accurate reference for the current state o
 - **`docs/specs/glossary.md`** — Canonical vocabulary for Session states, layers (Process / Registry / View / Link / Activity / Snapshot), transition verbs, and the Liskov contract on Registry APIs. Read this first. Other specs defer to it when naming a state or a verb.
 - **`docs/specs/layout.md`** — Tiling layout, pane/door containers, dockview configuration, modes (passthrough/command), keyboard shortcuts, selection overlay, spatial navigation, minimize/reattach, inline rename, session lifecycle, session persistence, and theming. Read this when touching: `Wall.tsx`, `Baseboard.tsx`, `Door.tsx`, `TerminalPane.tsx`, `spatial-nav.ts`, `layout-snapshot.ts`, `terminal-registry.ts`, `session-save.ts`, `session-restore.ts`, `reconnect.ts`, `index.css`, `theme.css`, or any keyboard/navigation/mode behavior.
 - **`docs/specs/dor-cli.md`** - the `dor` CLI which is prepended onto the path of every terminal that dormouse launches.
-- **`docs/specs/dor-agent-browser.md`** — The `dor agent-browser` (`dor ab`) surface: a viewer client that delegates entirely to the user's own agent-browser install, rendering its screencast to a Dormouse-owned `<canvas>`, forwarding mouse/keyboard input, and presenting tabs. Builds on the surface handle model in `dor-cli.md`. Read this when touching: `dor/src/commands/agent-browser.ts`, `lib/src/components/wall/AgentBrowserPanel.tsx`, `lib/src/components/wall/agent-browser-{input,ports,screen,screenshot-loop}.ts`, `lib/src/components/AgentBrowserScreenModalHost.tsx`, `lib/src/components/wall/AgentBrowserScreenModal.tsx`, `vscode-ext/src/agent-browser-host.ts`, or the agent-browser surface wiring in `Wall.tsx`.
-- **`docs/specs/dor-iframe.md`** — The `dor iframe` surface: an `<iframe>` fronted by a host-owned transparent proxy that serves the target's bytes so Dormouse can inject a keyboard side-channel (leader chord + pointerdown), model focus, and render real error pages instead of a blank pane. Builds on the surface handle model in `dor-cli.md`; sibling of `dor-agent-browser.md`. Read this when touching: `dor/src/commands/iframe.ts`, `lib/src/components/wall/IframePanel.tsx`, `lib/src/host/iframe-proxy.ts`, `lib/src/host/iframe-proxy-rewrite.ts`, `lib/src/lib/iframe-proxy-registry.ts`, `lib/src/lib/platform/iframe-proxy-types.ts`, `vscode-ext/src/iframe-proxy-host.ts`, or the iframe surface wiring in `Wall.tsx`.
+- **`docs/specs/dor-browser.md`** — The unified `dor` browser surface: a single `BrowserPanel` (`surfaceType: 'browser'`) with a swappable `renderMode` (`ab-screencast` / `ab-popout` / `iframe`). Covers the `dor ab` / `dor agent-browser` screencast viewer that delegates to the user's own agent-browser install (canvas screencast, input forwarding, tabs, pop-out modal) and the `dor iframe` renderer (an `<iframe>` fronted by a host-owned transparent proxy that injects a keyboard side-channel, models focus, and renders real error pages). Builds on the surface handle model in `dor-cli.md`. Read this when touching: `lib/src/components/wall/BrowserPanel.tsx`, `browser-surface.ts`, `browser-url.ts`, `AgentBrowserPanel.tsx`, `IframePanel.tsx`, `SurfacePaneHeader.tsx`, `AgentBrowserScreenModal.tsx`, `lib/src/components/wall/agent-browser-{connection,ports,screen,screenshot-loop,sessions,input}.ts`, `lib/src/lib/agent-browser-tab.ts`, `lib/src/host/agent-browser-host.ts`, `lib/src/host/iframe-proxy.ts`, `iframe-proxy-rewrite.ts`, `lib/src/lib/iframe-proxy-registry.ts`, `lib/src/lib/platform/iframe-proxy-types.ts`, `dor/src/commands/agent-browser.ts`, `dor/src/commands/iframe.ts`, `vscode-ext/src/agent-browser-host.ts`, `vscode-ext/src/iframe-proxy-host.ts`, or the browser surface wiring in `Wall.tsx`.
 - **`docs/specs/alert.md`** — Activity monitoring state machine, alert trigger/clearing rules, attention model, TODO lifecycle, bell button visual states and interaction, door alert indicators, hardening (a11y, motion, i18n, overflow), notification protocols (`OSC 9` / `OSC 9;4` / `OSC 99` / `OSC 777` / `BEL`), the `ActivityNotification` model, notification text handling and security, and the notification preview/detail UI. Read this when touching: `activity-monitor.ts`, `alert-manager.ts`, `AlertManager` notification/progress paths, the alert bell or TODO pill in `Wall.tsx` (TerminalPaneHeader), alert indicators in `Door.tsx`, the `a`/`t` keyboard shortcuts, or TODO notification preview UI. Layout.md defers to this spec for all alert/TODO behavior.
 - **`docs/specs/terminal-state.md`** — Terminal semantic state for CWD, shell prompt/editing/running/finished lifecycle, command runs, terminal title fallback, normalized semantic OSC events (`OSC 7`, `OSC 9;9`, `OSC 133`, `OSC 633`, `OSC 1337`, `OSC 0/2`), title-candidate diagnostics, header derivation, and grouping keys. Read this when touching `terminal-state.ts`, `terminal-state-store.ts`, semantic event parsing in `terminal-protocol.ts`, adapter semantic event forwarding, or derived pane/door labels.
 - **`docs/specs/terminal-escapes.md`** — Registry of every terminal escape sequence Dormouse parses or responds to: supported OSCs with pointers to the spec defining their behavior (alert.md or terminal-state.md), the canonical parsing-location and `pty:data` strip semantics, supported CSI sequences (`CSI > q`, DECSET/DECRST observation, kitty keyboard protocol) and replay-time CSI filtering, iTerm2 self-identification (env vars, fail-inertly rule), and known-unimplemented iTerm2 and clipboard-capable sequences. Read this when touching: OSC parsing at the PTY data boundary, CSI handlers in `terminal-protocol.ts` / `mouse-mode-observer.ts` / `terminal-report-filter.ts`, the iTerm2 identity env vars (`TERM_PROGRAM`, `LC_TERMINAL`), or adding support for a new escape sequence.