From 65d3369351980a8736bbff1d384d62477a610185 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 20:14:00 -0700
Subject: [PATCH 01/10] dor iframe: transparent proxy with keyboard
 side-channel and focus model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements the "Transparent Proxy (Instrumented Iframe)" section of
docs/specs/dor-iframe.md. Instead of pointing the <iframe> at the target,
Dormouse stands up a loopback proxy that serves the bytes — which lets it
inject a shim, see the upstream result, and resolve limitations #1–#4.

Proxy host (vscode-ext/src/iframe-proxy-host.ts): a loopback-only HTTP
proxy modeled on the agent-browser stream relay, but it parses/rewrites
responses and passes WebSocket upgrades through. Loopback http upstreams
are fully instrumented (strip X-Frame-Options, drop the page CSP, inject
the fixed leader shim); a remote that refuses framing or an unreachable
server is diagnosed and served as a Dormouse error page; https/link-local
targets are refused. Each grant gets its own ephemeral server bound to one
upstream, so it is inherently not an open forwarder and root-relative
sub-resources proxy transparently with no body rewriting — and no token in
the URL, which would land in location.pathname and break client routers.

Wiring: createIframeProxyUrl on PlatformAdapter + IframeProxyResult, the
VSCodeAdapter impl, the iframe:createProxyUrl/iframe:proxyUrl messages and
router handler, and the webview frame-src CSP narrowed to the loopback
proxy origin.

Keyboard side-channel + focus model: the injected shim forwards only the
reserved leader chord (dual-tap ⌘/⇧) via postMessage; use-wall-keyboard
validates the origin against live proxy grants and re-enters the same
dispatch (#1). use-window-focused and Wall's blur handler read
document.hasFocus() so a focused iframe no longer reads as backgrounded
(#2). IframePanel registers a focus handle (focusSession can focus the
frame, #3) and adopts frame-focus as entering the pane (clicks into a
cross-origin frame don't bubble a mousedown). The proxy's served error
pages replace the blind stall hint (#4). The frame is sandboxed without
allow-top-navigation for anti-framebust.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/components/Wall.tsx                   |   8 +-
 lib/src/components/wall/IframePanel.tsx       | 182 ++++++--
 lib/src/components/wall/use-wall-keyboard.ts  |  20 +-
 lib/src/components/wall/use-window-focused.ts |   7 +-
 lib/src/lib/iframe-proxy-registry.ts          |  29 ++
 lib/src/lib/platform/types.ts                 |  23 +
 lib/src/lib/platform/vscode-adapter.ts        |  15 +-
 lib/src/lib/terminal-lifecycle.ts             |  29 ++
 lib/src/lib/terminal-registry.ts              |   2 +
 vscode-ext/src/iframe-proxy-host.ts           | 404 ++++++++++++++++++
 vscode-ext/src/message-router.ts              |  12 +
 vscode-ext/src/message-types.ts               |   4 +-
 vscode-ext/src/webview-html.ts                |  11 +-
 13 files changed, 697 insertions(+), 49 deletions(-)
 create mode 100644 lib/src/lib/iframe-proxy-registry.ts
 create mode 100644 vscode-ext/src/iframe-proxy-host.ts

diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index 2a5b7913..8924b424 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -607,7 +607,13 @@ export function Wall({
   }, []);
 
   useEffect(() => {
-    const handleBlur = () => clearSessionAttention();
+    // An iframe surface taking focus blurs this window without backgrounding the
+    // app (document.hasFocus() stays true). Only clear cross-session attention
+    // on a real blur, else focusing an iframe wipes attention (spec → "#2").
+    const handleBlur = () => {
+      if (document.hasFocus()) return;
+      clearSessionAttention();
+    };
     window.addEventListener('blur', handleBlur);
     return () => window.removeEventListener('blur', handleBlur);
   }, []);
diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 932a2beb..6970ba84 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -1,6 +1,10 @@
-import { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useContext, useEffect, useRef, useState } from 'react';
 import type { IDockviewPanelProps } from 'dockview-react';
 import { TERMINAL_BOTTOM_RADIUS_CLASS } from '../design';
+import { getPlatform } from '../../lib/platform';
+import { registerProxyOrigin } from '../../lib/iframe-proxy-registry';
+import { registerSurfaceFocusHandle } from '../../lib/terminal-registry';
+import type { IframeProxyResult } from '../../lib/platform/types';
 import { usePaneChrome } from './use-pane-chrome';
 import { WallActionsContext } from './wall-context';
 
@@ -9,34 +13,104 @@ type IframePanelParams = {
   url?: string;
 };
 
+// Sandbox the proxied frame so a tool's `if (top !== self) top.location = …`
+// framebust cannot navigate the Wall away — allow-top-navigation is omitted on
+// purpose (docs/specs/dor-iframe.md → "Anti-framebust"). Everything else a local
+// dev tool needs is granted; allow-same-origin is safe here because the frame's
+// origin (the loopback proxy) is never same-origin with the host webview.
+const PROXY_SANDBOX = 'allow-scripts allow-same-origin allow-forms allow-popups allow-modals allow-downloads';
+const IFRAME_ALLOW = 'autoplay; clipboard-read; clipboard-write; fullscreen; geolocation; microphone; camera';
+
+type Resolution =
+  | { kind: 'empty' }
+  | { kind: 'resolving' }
+  | { kind: 'proxied'; src: string; origin: string }
+  // The host can't run a proxy (e.g. the web host) — keep the blind raw-iframe
+  // fallback rather than hiding the surface (Open Decision #4).
+  | { kind: 'raw'; src: string }
+  | { kind: 'error'; reason: 'frame-refused' | 'unreachable' | 'scheme'; detail?: string };
+
+function originOf(url: string): string {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return '';
+  }
+}
+
 export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelParams>) {
   const actions = useContext(WallActionsContext);
   const elRef = useRef<HTMLDivElement>(null);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
   usePaneChrome(api, elRef);
   const url = typeof params?.url === 'string' ? params.url : '';
-  const origin = useMemo(() => {
-    try {
-      return url ? new URL(url).origin : '';
-    } catch {
-      return '';
+
+  // Ask the host to front the target with its transparent proxy. The returned
+  // URL is a loopback origin that serves the page's bytes (instrumented for
+  // loopback) so Dormouse — now the server — gets a keyboard side-channel, an
+  // accurate focus model, and real error pages. Reachability/frame-refusal are
+  // diagnosed by the proxy and shown as a served page inside the frame.
+  const [resolution, setResolution] = useState<Resolution>(() => (url ? { kind: 'resolving' } : { kind: 'empty' }));
+  useEffect(() => {
+    if (!url) {
+      setResolution({ kind: 'empty' });
+      return;
     }
+    const createProxy = getPlatform().createIframeProxyUrl;
+    if (!createProxy) {
+      setResolution({ kind: 'raw', src: url });
+      return;
+    }
+    let cancelled = false;
+    setResolution({ kind: 'resolving' });
+    createProxy(url).then(
+      (result: IframeProxyResult) => {
+        if (cancelled) return;
+        if (result.ok) setResolution({ kind: 'proxied', src: result.url, origin: originOf(result.url) });
+        else setResolution({ kind: 'error', reason: result.reason, detail: result.detail });
+      },
+      () => {
+        if (!cancelled) setResolution({ kind: 'error', reason: 'unreachable' });
+      },
+    );
+    return () => { cancelled = true; };
   }, [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);
+  // Trust postMessage from this frame's origin (validated by the Wall's
+  // keyboard/focus channel) only while the proxied surface is live.
   useEffect(() => {
-    setLoaded(false);
-    setStalled(false);
-    if (!url) return;
-    const timer = setTimeout(() => setStalled(true), 5000);
-    return () => clearTimeout(timer);
-  }, [url]);
+    if (resolution.kind !== 'proxied' || !resolution.origin) return;
+    return registerProxyOrigin(resolution.origin);
+  }, [resolution.kind === 'proxied' ? resolution.origin : null]);
+
+  // Register a focus handle so onClickPanel → enterTerminalMode can focus the
+  // frame like any other surface (spec → "#3"). Focusing the element moves
+  // keyboard focus into the frame; the shim then reports focus back to the Wall.
+  useEffect(() => {
+    if (resolution.kind !== 'proxied' && resolution.kind !== 'raw') return;
+    return registerSurfaceFocusHandle(api.id, {
+      focus: () => iframeRef.current?.focus(),
+      blur: () => iframeRef.current?.blur(),
+    });
+  }, [api.id, resolution.kind]);
+
+  // Clicking *into* a cross-origin frame doesn't bubble a mousedown to the pane,
+  // so the onMouseDown below never fires and the surface never enters
+  // passthrough. Detect the frame taking focus (window blurs while our iframe
+  // becomes activeElement, app still focused) and adopt it as entering the pane,
+  // so mode/selection stay consistent and the leader chord can round-trip out.
+  useEffect(() => {
+    if (resolution.kind !== 'proxied' && resolution.kind !== 'raw') return;
+    const onWindowBlur = () => {
+      if (document.hasFocus() && document.activeElement === iframeRef.current) {
+        actions.onClickPanel(api.id);
+      }
+    };
+    window.addEventListener('blur', onWindowBlur);
+    return () => window.removeEventListener('blur', onWindowBlur);
+  }, [api.id, resolution.kind, actions]);
+
+  const src = resolution.kind === 'proxied' || resolution.kind === 'raw' ? resolution.src : '';
 
   return (
     <div
@@ -44,27 +118,57 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
       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}
-            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>
-          )}
-        </>
+      {src ? (
+        <iframe
+          ref={iframeRef}
+          className="block h-full w-full border-0 bg-white"
+          src={src}
+          title={api.title ?? url}
+          allow={IFRAME_ALLOW}
+          {...(resolution.kind === 'proxied' ? { sandbox: PROXY_SANDBOX, 'data-dormouse-proxy': 'true' } : {})}
+          referrerPolicy="strict-origin-when-cross-origin"
+        />
       ) : (
-        <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.
-        </div>
+        <PanelMessage resolution={resolution} url={url} />
       )}
     </div>
   );
 }
+
+function PanelMessage({ resolution, url }: { resolution: Resolution; url: string }) {
+  const base = 'flex h-full w-full items-center justify-center bg-terminal-bg px-6 text-center text-sm text-muted';
+
+  if (resolution.kind === 'resolving') {
+    return <div className={base}>Connecting to <span className="ml-1 font-semibold">{url}</span>…</div>;
+  }
+  if (resolution.kind === 'empty') {
+    return <div className={base}>No iframe URL was provided.</div>;
+  }
+  // proxied/raw render the iframe itself, never this fallback.
+  if (resolution.kind !== 'error') return null;
+  // 'error' — the proxy turned a dead end into something actionable. (Most
+  // unreachable/frame-refused cases are served as a page inside the frame; this
+  // covers the synchronous ones, chiefly an unproxyable scheme.)
+  return (
+    <div className={`${base} flex-col gap-2`}>
+      <div>{messageFor(resolution)}</div>
+      <div className="text-xs text-muted/80">
+        For arbitrary web pages, use <code className="rounded bg-app-bg px-1 py-0.5">dor ab open {url}</code>
+      </div>
+    </div>
+  );
+}
+
+function messageFor(resolution: Extract<Resolution, { kind: 'error' }>): string {
+  switch (resolution.reason) {
+    case 'scheme':
+      return resolution.detail
+        ? `Can’t frame this URL — ${resolution.detail}.`
+        : 'The iframe surface only frames local http:// servers.';
+    case 'frame-refused':
+      return 'This page refuses to be embedded in a frame.';
+    case 'unreachable':
+    default:
+      return resolution.detail ? `Couldn’t reach the server — ${resolution.detail}.` : 'Couldn’t reach the server.';
+  }
+}
diff --git a/lib/src/components/wall/use-wall-keyboard.ts b/lib/src/components/wall/use-wall-keyboard.ts
index 0c5de8ad..b538b605 100644
--- a/lib/src/components/wall/use-wall-keyboard.ts
+++ b/lib/src/components/wall/use-wall-keyboard.ts
@@ -4,6 +4,7 @@ import { handleMouseSelectionKeys } from './keyboard/handle-mouse-selection-keys
 import { handleKillConfirm } from './keyboard/handle-kill-confirm';
 import { handlePaneShortcuts } from './keyboard/handle-pane-shortcuts';
 import { handlePaneNavigation } from './keyboard/handle-pane-navigation';
+import { isProxyOrigin } from '../../lib/iframe-proxy-registry';
 import type { NavHistoryRef, WallKeyboardCtx } from './keyboard/types';
 
 export function useWallKeyboard(ctx: WallKeyboardCtx): void {
@@ -36,7 +37,24 @@ export function useWallKeyboard(ctx: WallKeyboardCtx): void {
       handlePaneNavigation(e, c, navHistory);
     };
 
+    // A focused cross-origin iframe owns the keyboard, so its keystrokes never
+    // reach the capturing window listener above. The proxy shim posts our
+    // reserved leader chord back out (docs/specs/dor-iframe.md → "The keyboard
+    // side-channel"); feed it into the same dispatch the in-document dual-tap
+    // would, after validating the message came from a live proxy origin.
+    const onMessage = (e: MessageEvent) => {
+      const data = e.data as { __dormouse?: unknown } | null;
+      if (!data || data.__dormouse !== 'leader') return;
+      if (!isProxyOrigin(e.origin)) return;
+      const c = ctxRef.current;
+      if (c.modeRef.current === 'passthrough') c.exitTerminalMode();
+    };
+
     window.addEventListener('keydown', handler, true);
-    return () => window.removeEventListener('keydown', handler, true);
+    window.addEventListener('message', onMessage);
+    return () => {
+      window.removeEventListener('keydown', handler, true);
+      window.removeEventListener('message', onMessage);
+    };
   }, []);
 }
diff --git a/lib/src/components/wall/use-window-focused.ts b/lib/src/components/wall/use-window-focused.ts
index cd750d81..4a75895d 100644
--- a/lib/src/components/wall/use-window-focused.ts
+++ b/lib/src/components/wall/use-window-focused.ts
@@ -4,7 +4,12 @@ export function useWindowFocused(): boolean {
   const [focused, setFocused] = useState(() => document.hasFocus());
   useEffect(() => {
     const onFocus = () => setFocused(true);
-    const onBlur = () => setFocused(false);
+    // Focusing one of our own iframe surfaces fires `blur` on this window even
+    // though the app hasn't been backgrounded — the focused element is just an
+    // <iframe> *inside* this document, so `document.hasFocus()` stays true.
+    // Reading it instead of blindly setting false keeps headers/attention live
+    // when an iframe takes focus (docs/specs/dor-iframe.md → "#2").
+    const onBlur = () => setFocused(document.hasFocus());
     window.addEventListener('focus', onFocus);
     window.addEventListener('blur', onBlur);
     return () => {
diff --git a/lib/src/lib/iframe-proxy-registry.ts b/lib/src/lib/iframe-proxy-registry.ts
new file mode 100644
index 00000000..321717b9
--- /dev/null
+++ b/lib/src/lib/iframe-proxy-registry.ts
@@ -0,0 +1,29 @@
+/**
+ * Tracks the loopback proxy origins of live iframe surfaces so the Wall's
+ * keyboard/focus channel can trust `postMessage` events from instrumented
+ * frames (docs/specs/dor-iframe.md → "The keyboard side-channel"). The shim we
+ * inject calls `parent.postMessage(...)`, which is cross-origin-safe by design;
+ * the Wall validates `event.origin` against this set before acting on a
+ * forwarded leader chord or focus/blur, so only a frame Dormouse itself served
+ * can drive those paths.
+ *
+ * Reference-counted because a surface can briefly re-register the same origin
+ * across a webview reload (mount of the new panel before unmount of the old).
+ */
+const proxyOriginCounts = new Map<string, number>();
+
+export function registerProxyOrigin(origin: string): () => void {
+  proxyOriginCounts.set(origin, (proxyOriginCounts.get(origin) ?? 0) + 1);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    const next = (proxyOriginCounts.get(origin) ?? 1) - 1;
+    if (next <= 0) proxyOriginCounts.delete(origin);
+    else proxyOriginCounts.set(origin, next);
+  };
+}
+
+export function isProxyOrigin(origin: string): boolean {
+  return proxyOriginCounts.has(origin);
+}
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index 601d6e66..3c2851d0 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -70,6 +70,22 @@ export interface AgentBrowserEditResult {
   error?: string;
 }
 
+/**
+ * Result of asking the host to front a `dor iframe` target with its transparent
+ * proxy (docs/specs/dor-iframe.md → "The Transparent Proxy"). On `ok` the panel
+ * points the `<iframe>` at `url` — a loopback proxy origin that fetches the
+ * target, strips frame-blocking headers (loopback only), and injects the
+ * Dormouse shim. On failure `reason` says why there is nothing to frame:
+ * `scheme` (not a proxyable `http://` upstream — e.g. an `https://` target,
+ * which v1 defers), `unreachable` (nothing answered), or `frame-refused` (a
+ * remote that forbids embedding — use `dor ab` instead). Reachability and
+ * frame-refusal are normally diagnosed lazily and surfaced as a served error
+ * *page* inside the frame, so v1 mostly returns `ok` or `scheme` here.
+ */
+export type IframeProxyResult =
+  | { ok: true; url: string }
+  | { ok: false; reason: 'frame-refused' | 'unreachable' | 'scheme'; detail?: string };
+
 export interface PlatformAdapter {
   // Lifecycle
   init(): Promise<void>;
@@ -131,6 +147,13 @@ export interface PlatformAdapter {
   // URL; absent or null falls back to ws://127.0.0.1:<port>.
   getAgentBrowserStreamUrl?(port: number): Promise<string | null>;
 
+  // iframe surface support (see docs/specs/dor-iframe.md → "The Transparent
+  // Proxy"). Stands up a loopback proxy in front of a `dor iframe` target and
+  // returns the proxy URL the panel should frame, or a structured reason it
+  // could not. Absent on hosts with no process to run a proxy (e.g. the web
+  // host), where the panel falls back to a raw, uninstrumented `<iframe>`.
+  createIframeProxyUrl?(targetUrl: string): Promise<IframeProxyResult>;
+
   // 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 80cf6fb7..1dc7ecc4 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, AgentBrowserScreenshotResult, AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from './types';
+import type { AgentBrowserCommandResult, AgentBrowserEditOp, AgentBrowserEditResult, AgentBrowserScreenshotResult, AlertStateDetail, IframeProxyResult, OpenPort, PlatformAdapter, PtyInfo } from './types';
 import { OPEN_PORT_TIMEOUT_MS } from './types';
 import { setDefaultShellOpts } from '../shell-defaults';
 import {
@@ -32,6 +32,7 @@ export class VSCodeAdapter implements PlatformAdapter {
     this.agentBrowserEdit = this.agentBrowserEdit.bind(this);
     this.agentBrowserScreenshot = this.agentBrowserScreenshot.bind(this);
     this.getAgentBrowserStreamUrl = this.getAgentBrowserStreamUrl.bind(this);
+    this.createIframeProxyUrl = this.createIframeProxyUrl.bind(this);
 
     // Seed the default shell from the extension-injected global so that
     // the first terminal on startup (which spawns synchronously on Wall
@@ -262,6 +263,18 @@ export class VSCodeAdapter implements PlatformAdapter {
     );
   }
 
+  async createIframeProxyUrl(url: string): Promise<IframeProxyResult> {
+    // The extension host stands up the loopback proxy and serves the bytes (see
+    // iframe-proxy-host.ts). On timeout, report unreachable so the panel shows a
+    // hint rather than hanging on a never-loading frame.
+    const result = await this.requestResponse<IframeProxyResult>(
+      'iframe:createProxyUrl', 'iframe:proxyUrl', { url },
+      (msg) => msg.result,
+      5000,
+    );
+    return result ?? { ok: false, reason: 'unreachable', detail: 'iframe proxy request timed out' };
+  }
+
   onPtyData(handler: (detail: { id: string; data: string }) => void): void {
     this.dataHandlers.add(handler);
   }
diff --git a/lib/src/lib/terminal-lifecycle.ts b/lib/src/lib/terminal-lifecycle.ts
index c609cb0f..3714182a 100644
--- a/lib/src/lib/terminal-lifecycle.ts
+++ b/lib/src/lib/terminal-lifecycle.ts
@@ -511,7 +511,36 @@ export function markSessionTouched(id: string): void {
   entry.untouched = false;
 }
 
+/**
+ * A non-terminal content surface's focus contract, so `focusSession` can drive
+ * it like any xterm pane. The iframe surface registers one whose `focus` moves
+ * keyboard focus into the instrumented frame (docs/specs/dor-iframe.md → "#3 —
+ * the surface registers a focus handle").
+ */
+export interface SurfaceFocusHandle {
+  focus(): void;
+  blur(): void;
+}
+
+const surfaceFocusHandles = new Map<string, SurfaceFocusHandle>();
+
+export function registerSurfaceFocusHandle(id: string, handle: SurfaceFocusHandle): () => void {
+  surfaceFocusHandles.set(id, handle);
+  return () => {
+    if (surfaceFocusHandles.get(id) === handle) surfaceFocusHandles.delete(id);
+  };
+}
+
 export function focusSession(id: string, focused: boolean): void {
+  // Non-terminal surfaces (iframe) aren't in the xterm registry — route to
+  // their focus handle so onClickPanel → enterTerminalMode focuses them too.
+  const handle = surfaceFocusHandles.get(id);
+  if (handle) {
+    if (focused) handle.focus();
+    else handle.blur();
+    return;
+  }
+
   const entry = registry.get(id);
   if (!entry) return;
 
diff --git a/lib/src/lib/terminal-registry.ts b/lib/src/lib/terminal-registry.ts
index 8277562d..a0b8faca 100644
--- a/lib/src/lib/terminal-registry.ts
+++ b/lib/src/lib/terminal-registry.ts
@@ -46,12 +46,14 @@ export {
   markSessionTouched,
   mountElement,
   refitSession,
+  registerSurfaceFocusHandle,
   restoreTerminal,
   resumeTerminal,
   setPendingShellOpts,
   swapTerminals,
   unmountElement,
 } from './terminal-lifecycle';
+export type { SurfaceFocusHandle } from './terminal-lifecycle';
 
 export { setDefaultShellOpts, getDefaultShellOpts } from './shell-defaults';
 
diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
new file mode 100644
index 00000000..61694a86
--- /dev/null
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -0,0 +1,404 @@
+/**
+ * Extension-host transparent proxy for the iframe surface
+ * (docs/specs/dor-iframe.md → "The Transparent Proxy").
+ *
+ * Instead of pointing the `<iframe>` at a `dor iframe <url>` target directly —
+ * where a cross-origin frame owns the keyboard, hides load errors, and can be
+ * refused outright — the panel points it at a loopback proxy this module stands
+ * up. Once Dormouse serves the bytes it can: (1) inject a fixed shim that
+ * forwards the reserved leader chord back to the Wall, and (2) see the upstream
+ * result and render a precise error *page* instead of a blank pane.
+ *
+ * Sibling to the agent-browser `createStreamRelayUrl` (agent-browser-host.ts):
+ * same loopback-only bind and per-surface isolation, but this one speaks HTTP —
+ * it parses and rewrites responses rather than being a dumb byte pipe — and
+ * passes WebSocket upgrades through (dev-server HMR, openvscode-server).
+ *
+ * Target policy (loopback instruments, remote diagnoses):
+ *   - Loopback http upstream  → full instrument: strip X-Frame-Options, drop the
+ *     page CSP, inject the shim. The user spawned it; framing is the intent.
+ *   - Remote http, frameable  → forward with the shim (flagged that `dor ab` is
+ *     the better tool for arbitrary browsing).
+ *   - Remote http, refuses    → never strip; serve a Dormouse error page that
+ *     points at `dor ab open <url>`.
+ *   - Unreachable             → serve a Dormouse error page.
+ * `https://` upstreams are deferred (loopback dev servers are overwhelmingly
+ * plain http); the panel reports `scheme` and falls back to a hint.
+ *
+ * Per-surface isolation, two deliberate notes vs the spec's sketch:
+ *   - Each grant gets its OWN ephemeral loopback server, so the grant's *origin*
+ *     is the grant. That makes root-relative sub-resources (`/assets/x.js`) and
+ *     absolute paths resolve and proxy transparently with zero body rewriting
+ *     (the one thing a shared `…/<token>/<path>` origin can't do — Open
+ *     Decision #2). A server bound to exactly one upstream is inherently not an
+ *     open forwarder, which is what the token grant bought the stream relay.
+ *   - No token in the URL. It would land in `location.pathname` and break
+ *     client-side routers (a React-Router/Remix dev server reads the path,
+ *     matches no route, and renders its own 404). The dedicated server +
+ *     loopback bind is the boundary instead.
+ */
+import * as http from 'http';
+import * as net from 'net';
+import { log } from './log';
+import type { IframeProxyResult } from '../../lib/src/lib/platform/types';
+
+// Sliding idle TTL: a live iframe refreshes its grant on every request, so a
+// grant only expires once its surface stops fetching (closed/killed). Lazy
+// sweep on the next createIframeProxyUrl, like the stream relay.
+const GRANT_IDLE_TTL_MS = 5 * 60_000;
+const GRANT_SWEEP_MS = 60_000;
+// Backstop against unbounded server accumulation if sweeps never run.
+const MAX_GRANTS = 32;
+const HTML_BODY_LIMIT = 32 * 1024 * 1024;
+
+// Hop-by-hop headers (RFC 7230 §6.1) plus framing headers we manage ourselves.
+// Never forwarded downstream.
+const STRIP_RESPONSE_HEADERS = new Set([
+  'connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization',
+  'te', 'trailer', 'transfer-encoding', 'upgrade',
+  // Framing controls — stripped so the proxy origin (which the webview frames)
+  // never inherits a "do not embed" from the upstream. For loopback that is the
+  // whole point; for a frameable remote there is nothing to strip anyway, and a
+  // refusing remote is diverted to an error page before we get here.
+  'x-frame-options', 'content-security-policy', 'content-security-policy-report-only',
+]);
+
+// The fixed, Dormouse-owned shim — like agent-browser's EDIT_SCRIPTS, never
+// user-supplied, so it is not an eval vector. Injected inline into served HTML
+// (loopback CSP is dropped, so an inline script runs). It reclaims ONLY the
+// reserved leader chord (dual-tap ⌘ / ⇧, matching handle-dual-tap.ts) and posts
+// it to the Wall; every other keystroke flows to the tool untouched. The focus
+// model needs no message channel — `document.hasFocus()` already stays true
+// while a descendant frame holds focus (resolves #2), and the Wall focuses the
+// frame element directly (resolves #3).
+const IFRAME_SHIM = `(function(){
+  var P=window.parent;
+  if(!P||P===window)return;
+  function tap(s,e){
+    var now=Date.now(),side=e.location===1?'left':'right';
+    if(s.side==='left'&&side==='right'&&now-s.time<500){s.side=null;return true;}
+    s.side=side;s.time=now;return false;
+  }
+  function leader(){try{P.postMessage({__dormouse:'leader'},'*');}catch(e){}}
+  var cmd={side:null,time:0},shift={side:null,time:0};
+  addEventListener('keydown',function(e){
+    if(e.key==='Meta'){if(tap(cmd,e))leader();}
+    else if(e.key==='Shift'){if(tap(shift,e))leader();}
+  },true);
+})();`;
+
+interface Grant {
+  /** The fixed upstream this grant fronts (origin + initial path). */
+  upstream: URL;
+  isLoopback: boolean;
+  port: number;
+  proxyOrigin: string;
+  server: http.Server;
+  lastUsed: number;
+}
+
+const grants = new Map<number, Grant>();
+let lastSweep = 0;
+
+/**
+ * Stand up a loopback proxy in front of `targetUrl` and return the URL the
+ * panel should frame, or a structured reason it could not. The actual upstream
+ * fetch happens lazily when the iframe loads the returned URL, so reachability
+ * and frame-refusal surface as served error pages rather than here.
+ */
+export async function createIframeProxyUrl(targetUrl: string): Promise<IframeProxyResult> {
+  let upstream: URL;
+  try {
+    upstream = new URL(targetUrl);
+  } catch {
+    return { ok: false, reason: 'scheme', detail: 'not an absolute URL' };
+  }
+  // v1 proxies http:// upstreams only — loopback dev servers are overwhelmingly
+  // plain http, and rewriting authenticated https pages is the agent-browser's
+  // job (spec → Target policy).
+  if (upstream.protocol !== 'http:') {
+    return { ok: false, reason: 'scheme', detail: `${upstream.protocol.replace(':', '')} upstreams are not proxied yet` };
+  }
+  // SSRF guard: the proxy fetches a user-supplied URL, so refuse the link-local
+  // / cloud-metadata ranges (169.254.169.254 and friends). Other private ranges
+  // are trusted — the boundary is the user's own `dor iframe` (spec → Security).
+  if (isBlockedAddress(upstream.hostname)) {
+    return { ok: false, reason: 'scheme', detail: 'link-local / metadata addresses are refused' };
+  }
+
+  const now = Date.now();
+  sweepGrants(now);
+
+  const grant: Grant = {
+    upstream,
+    isLoopback: isLoopbackHost(upstream.hostname),
+    port: 0,
+    proxyOrigin: '',
+    server: null as unknown as http.Server,
+    lastUsed: now,
+  };
+  const server = http.createServer((req, res) => handleRequest(grant, req, res));
+  server.on('upgrade', (req, socket, head) => handleUpgrade(grant, req, socket as net.Socket, head));
+  server.on('error', (err) => log.info(`[iframe-proxy] server error: ${err.message}`));
+  grant.server = server;
+
+  let port: number;
+  try {
+    port = await listen(server);
+  } catch (err) {
+    return { ok: false, reason: 'unreachable', detail: err instanceof Error ? err.message : String(err) };
+  }
+  grant.port = port;
+  grant.proxyOrigin = `http://127.0.0.1:${port}`;
+  grants.set(port, grant);
+  log.info(`[iframe-proxy] ${upstream.href} → ${grant.proxyOrigin} (loopback=${grant.isLoopback})`);
+
+  // The proxy origin maps to one fixed upstream, so the full path resolves
+  // transparently — keep the upstream's own initial path so deep-linked targets
+  // land where the user pointed.
+  return { ok: true, url: `${grant.proxyOrigin}${upstream.pathname}${upstream.search}` };
+}
+
+function listen(server: http.Server): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.unref();
+    server.listen(0, '127.0.0.1', () => {
+      const address = server.address();
+      if (address && typeof address === 'object') resolve(address.port);
+      else reject(new Error('iframe proxy failed to bind'));
+    });
+  });
+}
+
+function handleRequest(grant: Grant, req: http.IncomingMessage, res: http.ServerResponse): void {
+  grant.lastUsed = Date.now();
+  const path = req.url ?? '/';
+
+  const headers: http.OutgoingHttpHeaders = { ...req.headers };
+  headers.host = grant.upstream.host;
+  // Present the request as coming from the upstream's own origin so origin-aware
+  // dev servers (Vary: Origin, CSRF checks) treat it as same-origin, and drop
+  // Accept-Encoding so HTML comes back identity (we rewrite it).
+  if (headers.origin) headers.origin = grant.upstream.origin;
+  if (typeof headers.referer === 'string') headers.referer = headers.referer.split(grant.proxyOrigin).join(grant.upstream.origin);
+  delete headers['accept-encoding'];
+
+  const upstreamReq = http.request({
+    protocol: 'http:',
+    hostname: grant.upstream.hostname,
+    port: grant.upstream.port || 80,
+    method: req.method,
+    path,
+    headers,
+  }, (upstreamRes) => {
+    const contentType = String(upstreamRes.headers['content-type'] ?? '');
+    if (!/text\/html/i.test(contentType)) {
+      passThrough(grant, upstreamRes, res);
+      return;
+    }
+    collectBody(upstreamRes, (body) => {
+      // A remote that forbids embedding is never force-framed — serve an
+      // actionable page that points at `dor ab` instead of a blank pane.
+      if (!grant.isLoopback && refusesFraming(upstreamRes.headers)) {
+        serveErrorPage(res, frameRefusedPage(grant.upstream));
+        return;
+      }
+      const html = instrumentHtml(body);
+      const outHeaders = sanitizeResponseHeaders(grant, upstreamRes.headers);
+      outHeaders['content-type'] = 'text/html; charset=utf-8';
+      outHeaders['content-length'] = Buffer.byteLength(html).toString();
+      res.writeHead(upstreamRes.statusCode ?? 200, outHeaders);
+      res.end(html);
+    });
+  });
+  upstreamReq.on('error', (err) => serveErrorPage(res, unreachablePage(grant.upstream, err.message)));
+  req.pipe(upstreamReq);
+}
+
+// Non-HTML upstream responses are forwarded verbatim apart from the stripped
+// framing/hop-by-hop headers and a rewritten Location.
+function passThrough(grant: Grant, upstreamRes: http.IncomingMessage, res: http.ServerResponse): void {
+  const outHeaders = sanitizeResponseHeaders(grant, upstreamRes.headers);
+  res.writeHead(upstreamRes.statusCode ?? 200, outHeaders);
+  upstreamRes.pipe(res);
+}
+
+function collectBody(stream: http.IncomingMessage, done: (body: string) => void): void {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  stream.on('data', (chunk: Buffer) => {
+    size += chunk.length;
+    if (size > HTML_BODY_LIMIT) {
+      stream.destroy();
+      return;
+    }
+    chunks.push(chunk);
+  });
+  stream.on('end', () => done(Buffer.concat(chunks).toString('utf8')));
+  stream.on('error', () => done(Buffer.concat(chunks).toString('utf8')));
+}
+
+function sanitizeResponseHeaders(grant: Grant, headers: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {
+  const out: http.OutgoingHttpHeaders = {};
+  for (const [name, value] of Object.entries(headers)) {
+    if (value === undefined) continue;
+    if (STRIP_RESPONSE_HEADERS.has(name.toLowerCase())) continue;
+    out[name] = value;
+  }
+  // Keep upstream redirects on the proxy origin so they don't bounce the frame
+  // straight at the un-instrumented upstream.
+  const loc = out.location;
+  if (typeof loc === 'string' && loc.startsWith(grant.upstream.origin)) {
+    out.location = grant.proxyOrigin + loc.slice(grant.upstream.origin.length);
+  }
+  return out;
+}
+
+// Drop any in-document CSP (loopback "relax CSP") and inject the shim before
+// </head> so it runs before the tool's own scripts. The response-header CSP is
+// already stripped in sanitizeResponseHeaders.
+function instrumentHtml(body: string): string {
+  const html = body.replace(
+    /<meta[^>]+http-equiv=["']?content-security-policy["']?[^>]*>/gi,
+    '',
+  );
+  const shimTag = `<script>${IFRAME_SHIM}</script>`;
+  if (/<\/head>/i.test(html)) return html.replace(/<\/head>/i, `${shimTag}</head>`);
+  if (/<body[^>]*>/i.test(html)) return html.replace(/(<body[^>]*>)/i, `$1${shimTag}`);
+  return shimTag + html;
+}
+
+// A remote refuses framing if it sends any X-Frame-Options or a CSP
+// frame-ancestors that is not the permissive `*`. Conservative on purpose: when
+// in doubt we divert to an error page rather than show a guaranteed-blank frame.
+function refusesFraming(headers: http.IncomingHttpHeaders): boolean {
+  if (headers['x-frame-options']) return true;
+  const csp = headers['content-security-policy'];
+  const cspText = Array.isArray(csp) ? csp.join(';') : (csp ?? '');
+  const match = /frame-ancestors([^;]*)/i.exec(cspText);
+  if (!match) return false;
+  return !/\*/.test(match[1]);
+}
+
+// --- WebSocket upgrade passthrough (dev-server HMR, openvscode-server) -------
+
+// Mirrors the stream relay: once the upgrade head is rewritten (Host/Origin
+// pointed at the upstream) the proxy is a dumb byte pipe.
+function handleUpgrade(grant: Grant, req: http.IncomingMessage, socket: net.Socket, head: Buffer): void {
+  grant.lastUsed = Date.now();
+  socket.on('error', () => {});
+  const path = req.url ?? '/';
+  const targetPort = Number(grant.upstream.port) || 80;
+
+  const upstream = net.connect(targetPort, grant.upstream.hostname, () => {
+    const headerLines: string[] = [];
+    for (let i = 0; i < req.rawHeaders.length; i += 2) {
+      const name = req.rawHeaders[i];
+      const lower = name.toLowerCase();
+      if (lower === 'host') headerLines.push(`Host: ${grant.upstream.host}`);
+      else if (lower === 'origin') headerLines.push(`Origin: ${grant.upstream.origin}`);
+      else headerLines.push(`${name}: ${req.rawHeaders[i + 1]}`);
+    }
+    upstream.write(`GET ${path} HTTP/1.1\r\n${headerLines.join('\r\n')}\r\n\r\n`);
+    if (head && head.length) upstream.write(head);
+    socket.pipe(upstream);
+    upstream.pipe(socket);
+  });
+  upstream.on('error', () => socket.destroy());
+  socket.on('close', () => upstream.destroy());
+}
+
+// --- Policy helpers ----------------------------------------------------------
+
+function isLoopbackHost(hostname: string): boolean {
+  const h = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
+function isBlockedAddress(hostname: string): boolean {
+  const h = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  // IPv4 link-local / cloud metadata (169.254.0.0/16, incl. 169.254.169.254).
+  if (/^169\.254\./.test(h)) return true;
+  // IPv6 link-local (fe80::/10).
+  if (/^fe[89ab][0-9a-f]:/.test(h)) return true;
+  return false;
+}
+
+function sweepGrants(now: number): void {
+  if (now - lastSweep < GRANT_SWEEP_MS && grants.size < MAX_GRANTS) return;
+  lastSweep = now;
+  const ordered = [...grants.values()].sort((a, b) => a.lastUsed - b.lastUsed);
+  for (const grant of ordered) {
+    const expired = now - grant.lastUsed > GRANT_IDLE_TTL_MS;
+    const overCap = grants.size > MAX_GRANTS;
+    if (!expired && !overCap) break;
+    grants.delete(grant.port);
+    grant.server.close();
+    log.info(`[iframe-proxy] swept grant for ${grant.upstream.href}`);
+  }
+}
+
+// --- Served error / diagnostic pages ----------------------------------------
+
+interface ErrorPage {
+  title: string;
+  message: string;
+  hint?: string;
+}
+
+function frameRefusedPage(upstream: URL): ErrorPage {
+  return {
+    title: `${upstream.host} refuses to be embedded`,
+    message: `${upstream.host} sends a frame-blocking header (X-Frame-Options or CSP frame-ancestors), so it can’t be shown in an iframe surface.`,
+    hint: `dor ab open ${upstream.href}`,
+  };
+}
+
+function unreachablePage(upstream: URL, detail: string): ErrorPage {
+  return {
+    title: `Nothing responding at ${upstream.host}`,
+    message: `Dormouse couldn’t reach ${upstream.href} (${detail}). Is the dev server running?`,
+  };
+}
+
+function serveErrorPage(res: http.ServerResponse, page: ErrorPage): void {
+  const html = errorPageHtml(page);
+  res.writeHead(200, {
+    'content-type': 'text/html; charset=utf-8',
+    'content-length': Buffer.byteLength(html).toString(),
+    'cache-control': 'no-store',
+  });
+  res.end(html);
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function errorPageHtml(page: ErrorPage): string {
+  const hint = page.hint
+    ? `<p class="hint">Try <code>${escapeHtml(page.hint)}</code></p>`
+    : '';
+  return `<!doctype html><html><head><meta charset="utf-8">
+<style>
+  :root { color-scheme: dark; }
+  html, body { height: 100%; margin: 0; }
+  body { display: flex; align-items: center; justify-content: center;
+    background: #14161a; color: #c9ced6;
+    font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
+  .card { max-width: 34rem; padding: 1.5rem 2rem; text-align: center; }
+  h1 { margin: 0 0 .5rem; font-size: 1.05rem; font-weight: 600; color: #e7ebf1; }
+  p { margin: .5rem 0; }
+  .hint { margin-top: 1rem; }
+  code { background: #20242b; border-radius: 4px; padding: .15rem .4rem;
+    font-family: ui-monospace, SFMono-Regular, Menlo, monospace; color: #e7ebf1; }
+</style></head>
+<body><div class="card">
+  <h1>${escapeHtml(page.title)}</h1>
+  <p>${escapeHtml(page.message)}</p>
+  ${hint}
+</div></body></html>`;
+}
diff --git a/vscode-ext/src/message-router.ts b/vscode-ext/src/message-router.ts
index 96c0c987..833fd692 100644
--- a/vscode-ext/src/message-router.ts
+++ b/vscode-ext/src/message-router.ts
@@ -14,6 +14,7 @@ import type { PersistedSession } from '../../lib/src/lib/session-types';
 import type { WebviewMessage, ExtensionMessage } from './message-types';
 import type { DorControlRequest } from './pty-manager';
 import { createStreamRelayUrl, runAgentBrowserCommand, runAgentBrowserEdit, runAgentBrowserScreenshot } from './agent-browser-host';
+import { createIframeProxyUrl } from './iframe-proxy-host';
 import { log } from './log';
 
 const clipboardOps = require('../../lib/clipboard-ops.cjs') as {
@@ -400,6 +401,17 @@ export function attachRouter(
         );
         break;
       }
+      case 'iframe:createProxyUrl':
+        createIframeProxyUrl(typeof msg.url === 'string' ? msg.url : '').then(
+          (result) => webview.postMessage({
+            type: 'iframe:proxyUrl', requestId: msg.requestId, result,
+          } satisfies ExtensionMessage),
+          (err) => webview.postMessage({
+            type: 'iframe:proxyUrl', requestId: msg.requestId,
+            result: { ok: false, reason: 'unreachable', detail: err?.message ?? String(err) },
+          } 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 73f640cd..0f62e385 100644
--- a/vscode-ext/src/message-types.ts
+++ b/vscode-ext/src/message-types.ts
@@ -1,7 +1,7 @@
 import type { ActivityNotification, SessionStatus, TodoState } from '../../lib/src/lib/alert-manager';
 import type { TerminalSemanticEvent } from '../../lib/src/lib/terminal-state';
 import type { DorControlRequestPayload, DorControlResponsePayload } from '../../dor/src/protocol';
-import type { OpenPort } from '../../lib/src/lib/platform/types';
+import type { IframeProxyResult, OpenPort } from '../../lib/src/lib/platform/types';
 import type { VSCodeWorkbenchCommand } from '../../lib/src/lib/vscode-keybindings';
 
 // Messages from webview → extension host
@@ -22,6 +22,7 @@ export type WebviewMessage =
   | { 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: 'iframe:createProxyUrl'; url: string; requestId: string }
   | { type: 'dormouse:init' }
   | { type: 'dormouse:saveState'; state: unknown }
   | { type: 'dormouse:flushSessionSaveDone'; requestId: string }
@@ -62,6 +63,7 @@ export type ExtensionMessage =
   | { type: 'agentBrowser:editResult'; requestId: string; ok: boolean; text?: 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: 'iframe:proxyUrl'; requestId: string; result: IframeProxyResult }
   | {
       type: 'dormouse:newTerminal';
       shell?: string;
diff --git a/vscode-ext/src/webview-html.ts b/vscode-ext/src/webview-html.ts
index ab6fc807..4e8bf2db 100644
--- a/vscode-ext/src/webview-html.ts
+++ b/vscode-ext/src/webview-html.ts
@@ -32,11 +32,12 @@ export function getWebviewHtml(
     // 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
-    // constrains inputs to http:/https:.
-    `frame-src http: https:`,
+    // `dor iframe` frames its target through a loopback transparent proxy that
+    // the extension host stands up (iframe-proxy-host.ts), so the only origin we
+    // ever embed is 127.0.0.1/localhost on an OS-assigned port. Without a
+    // frame-src override the `default-src 'none'` fallback blocks the frame
+    // outright, leaving a blank (white) pane. See docs/specs/dor-iframe.md.
+    `frame-src http://127.0.0.1:* http://localhost:*`,
   ].join('; ');
 
   html = html.replace(

From fa0904656773ace5ca07da3cfebef9d3dc121ed9 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 20:38:40 -0700
Subject: [PATCH 02/10] dor iframe: fix cursor offset inside the proxied frame
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A cross-origin iframe is an out-of-process frame, so Chromium maps pointer
events to it relative to its nearest compositing/containing ancestor.
Dockview's root (.dv-dockview) sets `contain: layout`, which made that
far-away root the frame's coordinate origin — clicks landed offset by the
pane's distance from it (~340px for a split pane).

Give the iframe's immediate container its own identity compositing layer
(transform: translateZ(0)), co-located with the frame, so it becomes the
nearest reference and the offset collapses to ~0. translateZ(0) is
identity, so getBoundingClientRect (overlay measurement) is unaffected.

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

diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 6970ba84..8a2ed492 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -116,6 +116,14 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
     <div
       ref={elRef}
       className={`relative h-full w-full overflow-hidden bg-terminal-bg ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
+      // A cross-origin iframe is an out-of-process frame; Chromium maps pointer
+      // events to it relative to its nearest compositing/containing ancestor.
+      // Dockview's root (.dv-dockview) sets `contain: layout`, so without this
+      // the frame's reference is that far-away root and clicks land offset by the
+      // pane's distance from it. translateZ(0) gives this container its own layer
+      // co-located with the frame, collapsing the offset to ~0. It's identity, so
+      // getBoundingClientRect (overlay measurement) is unaffected.
+      style={{ transform: 'translateZ(0)' }}
       onMouseDown={() => actions.onClickPanel(api.id)}
     >
       {src ? (

From dcf453480aa313362b6707664233dcec2c4966ae Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:10:53 -0700
Subject: [PATCH 03/10] docs: update dor-iframe spec to match the implemented
 proxy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Moves "The Transparent Proxy" out of Future Work into the body as the
implemented substrate, with pointers to what shipped. Documents the two
deliberate deviations from the original sketch — per-grant dedicated
loopback server (not a shared port) and no token in the URL (a path token
breaks client-side routers) — and the new cross-origin-frame cursor-offset
fix. Marks limitations #2/#3/#4 resolved and reframes #1 as mitigated.
Adds Known v1 gaps (https deferred, absolute-origin sub-resources bypass,
buffered streaming SSR, no teardown-on-kill hook) and turns the Open
Decisions into the decisions actually made. Path 1 / Path 2 / render
backends remain future work.

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

diff --git a/docs/specs/dor-iframe.md b/docs/specs/dor-iframe.md
index d7f056ac..0d0d097b 100644
--- a/docs/specs/dor-iframe.md
+++ b/docs/specs/dor-iframe.md
@@ -6,22 +6,25 @@
 > `docs/specs/dor-agent-browser.md` for the sibling browser surface.
 
 `dor iframe <url>` opens an absolute `http(s)` URL in a high-fidelity `<iframe>`
-surface for human inspection. Unlike the agent-browser surface (a screencast of a
-real Chromium), the iframe renders the page's **own DOM** directly — zero-lag and
-pixel-perfect — but as a **separate browsing context** that Dormouse neither
-controls nor can observe.
-
-> Status: **provisional.** The surface works for displaying a page, but has
-> structural limitations (below) that keep it from being usable for real
-> interaction today. Two things follow from that: arbitrary web browsing is
-> served by the **agent-browser** surface instead (`dor ab`, see
-> [dor-agent-browser.md](dor-agent-browser.md)), and the iframe's own path
-> forward is the **transparent proxy** in Future Work below, which converts it
-> from a blind embedder into Dormouse-served content and resolves four of the
-> five limitations. Do not build features on top of the raw iframe surface until
-> that lands.
-
-## The Current Surface
+surface for human inspection. The iframe renders the page's **own DOM** directly
+— zero-lag and pixel-perfect — but in a **separate browsing context** that the
+browser, not Dormouse, drives.
+
+The surface no longer points the `<iframe>` at the target directly. It fronts the
+target with a **host-owned transparent proxy**: Dormouse serves the bytes, so it
+controls them. That converts the iframe from a blind embedder into
+Dormouse-served content, which is the one capability the raw iframe lacked — and
+from it the surface gains a keyboard side-channel for its global leader chord, an
+accurate focus model, and real error pages.
+
+> Status: **works for loopback dev servers** (implemented on the VS Code host).
+> Arbitrary web browsing is still better served by the **agent-browser** surface
+> (`dor ab`, see [dor-agent-browser.md](dor-agent-browser.md)): the iframe surface
+> proxies `http://` upstreams (loopback dev servers are overwhelmingly plain
+> http), defers `https://`, and routes a remote that refuses framing to an error
+> page pointing at `dor ab`.
+
+## The CLI → surface
 
 `dor iframe <url>` (`dor/src/commands/iframe.ts`) sends a `surface.iframe` control
 request; `parseIframeUrl` constrains inputs to absolute `http://`/`https://`
@@ -30,89 +33,23 @@ rule (`lib/src/components/Wall.tsx` → `createContentSurface`): an untouched
 terminal caller is replaced in place, anything else gets a split next to the
 caller.
 
-`IframePanel.tsx` renders a bare `<iframe src={url}>`. Because a cross-origin
-frame reports no load result, the panel can only show a **blind 5-second stall
-hint** ("if it stays blank, the server may be down, on a different scheme, or
-refusing to be embedded") — it cannot actually distinguish those cases.
-
-## Structural Limitations
-
-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. Some conflicts
-are **inherent to the browser** (only designable-around, never patchable); others
-are **fixable but not yet done**.
-
-### Inherent
-
-- **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 (a click-to-interact
-  overlay, or an accept-focus model with a mouse-driven escape).
-
-- **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.
-
-### Fixable but not yet done
-
-- **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` (it is naïve —
-  `onBlur = () => setFocused(false)`), which drives 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. The fix is to distinguish `document.activeElement` being one of our own
-  iframes from a real window blur.
-
-- **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.
-
-### Host config
-
-- **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). Today a broad
-  `frame-src http: https:` allowance is required for the surface to render at all
-  (narrowed by the proxy below).
-
----
-
-# Future Work
-
-> Designed, not yet built. Everything above describes the surface as it exists
-> today; everything below is the roadmap.
-
-The through-line: an `<iframe>` is only crippled when it points at a foreign
-context. Put a **host-owned transparent proxy** in front of it and Dormouse
-becomes the server — it controls the bytes, which is the one thing the raw iframe
-lacks. From there the surface gains a keyboard side-channel, an accurate focus
-model, and real error signals; and it becomes one render backend in a small
-family shared with agent-browser.
+`IframePanel.tsx` then asks the host to front the target with its proxy
+(`getPlatform().createIframeProxyUrl`) and frames the returned loopback URL. If
+the host has no proxy it falls back to a raw `<iframe src={url}>`; if the target
+isn't proxyable (e.g. an `https://` URL) it shows an actionable message instead.
 
 ## The Transparent Proxy (Instrumented Iframe)
 
-This is the **substrate** under everything else here. Instead of pointing the
-`<iframe>` at the target, Dormouse points it at a loopback proxy that fetches the
-target and serves it back. The moment Dormouse serves the bytes, two things become
-possible that the raw iframe cannot do — and together they resolve limitations
-#1–#4 above:
+This is the **substrate** the surface is built on. Instead of pointing the
+`<iframe>` at the target, Dormouse points it at a loopback proxy
+(`vscode-ext/src/iframe-proxy-host.ts`) that fetches the target and serves it
+back. The moment Dormouse serves the bytes, two things become possible that the
+raw iframe cannot do:
 
-1. **Inject a keyboard side-channel** so Dormouse's global chords keep working
-   inside the frame (the technique VS Code uses for its own webviews).
+1. **Inject a keyboard side-channel** so Dormouse's global leader chord keeps
+   working inside the frame (the technique VS Code uses for its own webviews).
 2. **See the upstream result**, so a refused-to-be-framed page or a dead server
-   becomes a clear error instead of a blank pane.
+   becomes a clear error page instead of a blank pane.
 
 ### The one load-bearing fact
 
@@ -122,98 +59,116 @@ from posting to the parent** — `window.parent.postMessage()` is cross-origin-s
 by design. Dormouse can never reach *in*, but a script *we put in the served HTML*
 can always call out. The only capability we need is control over the served
 bytes, which the proxy gives us. This is exactly how VS Code instruments its
-plugin webviews — serve HTML from an origin you own, inject a bootstrap that
-forwards keydowns — not a new technique, the proven one.
+plugin webviews — serve HTML from an origin you own, inject a bootstrap — not a
+new technique, the proven one.
 
 ### Target policy: loopback instruments, remote diagnoses
 
-The policy hinges on **loopback vs remote**, because only loopback targets are
-"the user's own tools" where forcing framing and stripping headers is safe and
-intended.
+| Target | Proxy behavior |
+| --- | --- |
+| **Loopback** (`localhost`/`127.0.0.1`/`[::1]`) http | Full instrument: strip `X-Frame-Options`, drop the page CSP, inject the shim, serve. The user spawned it; framing is the intent. |
+| **Remote** http, frameable | Best-effort render with the injected shim (flagged that `dor ab` is the better tool for arbitrary browsing). |
+| **Remote** http, refuses framing | **Never force-framed.** Serve a Dormouse error page with a one-click hint to `dor ab open <url>`. |
+| **Unreachable** (conn refused, DNS, non-2xx) | Serve a Dormouse error page ("is the dev server running?"). |
+| **`https://`** | Deferred. The panel reports `scheme` and points at `dor ab`. |
 
-| Target | Frame-blocking headers | Proxy behavior |
-| --- | --- | --- |
-| **Loopback** (`localhost`/`127.0.0.1`/`[::1]`) | stripped | Full instrument: relax CSP, drop `X-Frame-Options`/`frame-ancestors`, inject shim, serve. The user spawned it; framing is the intent. |
-| **Remote**, frameable | honored | Best-effort render with the leader shim, flagged that `dor ab` is the better tool. *(Open decision — may degrade to error-only.)* |
-| **Remote**, refuses framing | honored | **Do not strip.** Serve a Dormouse error page explaining why, with a one-click hint to `dor ab open <url>`. |
-| **Unreachable** (conn refused, DNS, non-2xx) | — | Serve a Dormouse error page ("is the dev server running?"). |
+We do **not** force-frame a site that refuses embedding: rewriting authenticated
+cross-origin pages is an auth/cookie/ToS dead end, and that's what the
+agent-browser surface is for. v1 proxies `http://` upstreams plus WebSocket
+upgrades; `https://` is deferred.
 
-We do **not** force-frame third-party sites: rewriting authenticated
-cross-origin pages through a proxy is an auth/cookie/ToS dead end, and that's
-what the agent-browser surface is for. v1 proxies `http://` upstreams (loopback
-dev servers are overwhelmingly plain http) plus WebSocket upgrades; `https://`
-upstreams are deferred.
+### Proxy mechanism
+
+Modeled on the agent-browser **stream relay**
+(`vscode-ext/src/agent-browser-host.ts`) — already a loopback-only, single-purpose
+forwarder. The difference: this proxy speaks **HTTP** (it parses and rewrites
+responses) and passes through **WebSocket upgrades** (dev-server HMR,
+openvscode-server's connection).
+
+- **Per-grant dedicated loopback server.** Each grant gets its own ephemeral
+  `http.Server` bound to `127.0.0.1:0`, fronting exactly **one** fixed upstream.
+  The grant's *origin* is the grant. Two consequences, and they are deliberate
+  departures from the original "single shared port + `…/<token>/<path>`" sketch:
+  - Root-relative sub-resources (`/assets/x.js`) and absolute paths resolve and
+    proxy **transparently with zero body rewriting** — a shared origin can't do
+    this without rewriting (the old Open Decision #2).
+  - **No token in the URL.** A path-prefix token would land in
+    `location.pathname`, and a client-side router (a React-Router/Remix dev
+    server) would match no route and render its own 404. A server bound to a
+    single upstream is inherently not an open forwarder, so the token bought
+    nothing here that the dedicated server doesn't already provide.
+
+  Grants use a sliding idle TTL with a lazy sweep (a live iframe refreshes on
+  every request; an idle grant's server is closed), plus a hard cap.
+- **Response rewriting.** For `text/html` from a frameable upstream: strip
+  `X-Frame-Options`, drop the page CSP (response header **and** any
+  `<meta http-equiv>`), inject the shim before `</head>`. `Host`/`Origin`/`Referer`
+  are rewritten to the upstream so origin-aware servers (`Vary: Origin`, CSRF
+  checks) see a same-origin request, and a `Location` redirect back to the
+  upstream origin is rewritten to the proxy origin so it doesn't bounce the frame
+  off-proxy. Non-HTML passes through (framing/hop-by-hop headers still stripped).
+- **WebSocket passthrough.** Upgrades are forwarded as a raw byte pipe once the
+  upgrade head is rewritten (`Host`/`Origin` → upstream), exactly like the stream
+  relay.
+- **Anti-framebust.** The `<iframe>` uses a `sandbox` without
+  `allow-top-navigation`, so a tool's `if (top !== self) top.location = …` cannot
+  navigate the Wall away.
 
 ### The keyboard side-channel (resolves #1)
 
 A fixed, Dormouse-owned script — like agent-browser's `EDIT_SCRIPTS`, never
-user-supplied, so it is not an eval vector — injected before `</head>`:
-
-```js
-// Reclaim ONLY Dormouse's reserved leader chord; everything else flows to the
-// tool untouched. The tool keeps full keyboard interactivity; Dormouse keeps
-// its global shortcuts.
-addEventListener('keydown', (e) => {
-  if (isDormouseLeader(e)) {
-    parent.postMessage({ __dormouse: 'leader-keydown', key: e.key, code: e.code,
-      ctrlKey: e.ctrlKey, metaKey: e.metaKey, altKey: e.altKey, shiftKey: e.shiftKey }, '*');
-  }
-}, true);
-addEventListener('focus', () => parent.postMessage({ __dormouse: 'focus' }, '*'), true);
-addEventListener('blur',  () => parent.postMessage({ __dormouse: 'blur'  }, '*'), true);
-```
+user-supplied, so it is not an eval vector — injected inline before `</head>`. It
+reclaims **only** the reserved leader chord (dual-tap ⌘ / ⇧, the same detection as
+`handle-dual-tap.ts`) and `postMessage`s it to the parent; **every other keystroke
+flows to the tool untouched**. The embedded tool (a code editor, a VS-Code-web
+workbench) keeps full keyboard interactivity; Dormouse keeps its one global chord.
 
-The forwarding is **asymmetric and minimal**: the embedded tool (a code editor, a
-full VS-Code-web workbench) wants nearly every keystroke and has its own
-keybindings; Dormouse only needs to reclaim its handful of global chords. The Wall
-already owns a capturing `window` keydown listener
-(`use-wall-keyboard.ts`); it gains a `message` listener that validates the origin
-against the live proxy grant, then feeds the forwarded chord into the same
-keybinding dispatch — preferably by calling the dispatcher with the serialized
-payload directly, not by re-dispatching a synthesized `KeyboardEvent` (whose
-constructor drops `keyCode`/`which`; VS Code works around it with
-`Object.defineProperty`, a wrinkle we skip by not round-tripping a DOM event).
+The Wall already owns a capturing `window` keydown listener
+(`use-wall-keyboard.ts`); it gains a `message` listener that validates
+`event.origin` against the live proxy grants (`lib/src/lib/iframe-proxy-registry.ts`)
+and feeds the forwarded chord into the same dispatch the in-document dual-tap
+would (`exitTerminalMode`) — no synthesized `KeyboardEvent` round-trip.
 
-### Accurate focus model (resolves #2 and #3)
+> Deviation from the original sketch: the shim forwards **only** the leader, not
+> `focus`/`blur`. The focus model below needs no message channel.
 
-The shim's `focus`/`blur` messages let the Wall keep an accurate model:
+### Accurate focus model (resolves #2 and #3)
 
-- **#2** — the Wall distinguishes "one of our own instrumented panes took focus"
-  from a real window blur and keeps `windowFocused` true.
-- **#3** — the surface registers a focus handle that posts a `focus-yourself`
-  message to the shim, so `onClickPanel → enterTerminalMode` can focus the pane
-  like any other surface.
+- **#2** — focusing one of our iframes fires `blur` on the parent `window` even
+  though the app isn't backgrounded; the focused element is just an `<iframe>`
+  *inside* our document, so `document.hasFocus()` stays **true**.
+  `use-window-focused.ts` and Wall's blur handler read it instead of blindly going
+  inactive, so headers/attention stay live when an iframe takes focus.
+- **#3** — `IframePanel` registers a focus handle (`registerSurfaceFocusHandle` in
+  `terminal-lifecycle.ts`) so `focusSession` focuses the frame element like any
+  other surface. And because clicking *into* a cross-origin frame doesn't bubble a
+  `mousedown` to the pane, `IframePanel` adopts "the frame took focus" (window
+  `blur` while our iframe is `document.activeElement` and the app still has focus)
+  as entering the pane — so mode/selection stay consistent and the leader chord
+  round-trips back out.
 
 ### Real error signals (resolves #4)
 
-With the proxy, **Dormouse is the server**, so it sees the upstream result and
-renders a precise error *page* (served from the proxy origin, which the iframe
-loads normally): refused framing → "`google.com` refuses to be embedded
-(`X-Frame-Options: DENY`); open it with `dor ab open https://google.com`"; server
-down → "nothing responding at `localhost:8080` — is the dev server running?".
-This turns the `google.com`-into-an-iframe dead end into an actionable message.
-
-### Proxy mechanism
-
-Modeled on the agent-browser **stream relay**
-(`vscode-ext/src/agent-browser-host.ts`) — already a loopback-only, tokenized,
-single-purpose forwarder. Differences: this proxy speaks **HTTP** (parses and
-rewrites responses) rather than being a dumb byte pipe, and passes through
-**WebSocket upgrades** (dev-server HMR, openvscode-server's connection).
-
-- **Loopback bind, per-surface token grant** (TTL + lazy sweep), exactly like
-  `createStreamRelayUrl`. The proxy forwards only to the exact granted upstream
-  for a valid token — never a general-purpose open proxy.
-- **Single origin, path-preserving.** Each grant maps a proxy URL
-  (`http://127.0.0.1:<proxyPort>/<token>/…`) to one fixed upstream; root-relative
-  URLs resolve against the proxy origin and get proxied transparently.
-- **Response rewriting.** For `text/html` from a loopback upstream: strip
-  `X-Frame-Options`, neutralize CSP `frame-ancestors`, replace the page CSP with
-  one permitting the tool plus the injected shim's nonce, inject the shim.
-  Non-HTML passes through.
-- **Anti-framebust.** The `<iframe>` uses a `sandbox` without
-  `allow-top-navigation`, so a tool's `if (top !== self) top.location = …` cannot
-  navigate the Wall away.
+With the proxy, **Dormouse is the server**, so it diagnoses lazily and serves a
+precise error *page* from the proxy origin (which frames fine): a refused remote →
+"`<host>` refuses to be embedded; `dor ab open <url>`"; a dead upstream → "nothing
+responding at `localhost:8080` — is the dev server running?". `createIframeProxyUrl`
+itself returns `{ ok: false, reason }` only for the synchronous cases (chiefly an
+unproxyable `scheme`); reachability and frame-refusal are surfaced as served
+pages.
+
+### Cursor alignment (the out-of-process-frame offset)
+
+A cross-origin iframe is an **out-of-process frame**; Chromium maps pointer events
+to it relative to its nearest compositing/containing ancestor. Dockview's root
+(`.dv-dockview`) sets `contain: layout`, so without intervention clicks land offset
+by the pane's distance from that root (hundreds of px for a split pane).
+`IframePanel` gives the iframe's **immediate container** its own identity layer
+(`transform: translateZ(0)`), co-located with the frame, so it becomes the nearest
+reference and the offset collapses to ~0. It's an identity transform, so
+`getBoundingClientRect` (overlay measurement) is unaffected. Same-origin surfaces
+(xterm, the agent-browser canvas) are immune — they recompute from
+`getBoundingClientRect`, which a cross-origin frame can't.
 
 ### Host capability and CSP
 
@@ -227,13 +182,16 @@ createIframeProxyUrl?(targetUrl: string): Promise<
 >;
 ```
 
-VS Code implements it in the extension host alongside the stream relay (a sibling
-`iframe-proxy-host.ts`). **The proxy is needed on every host** — even where a
-Tauri webview could frame `http://127.0.0.1` directly for origin reasons,
-injection still requires controlling the bytes — unlike the agent-browser relay,
-which was a VS-Code-only origin fix. With the proxy, the VS Code webview CSP
-(`vscode-ext/src/webview-html.ts`) narrows from the broad `frame-src http:
-https:` to the loopback proxy origin only:
+VS Code implements it in the extension host (`iframe-proxy-host.ts`), routed via
+`message-router.ts` / `message-types.ts` and the `vscode-adapter.ts` request/
+response pair. **The proxy is needed on every host** — even where a Tauri webview
+could frame `http://127.0.0.1` directly for origin reasons, injection still
+requires controlling the bytes — unlike the agent-browser relay, which was a
+VS-Code-only origin fix. Hosts with no process to run one (the web host) omit the
+method and the panel falls back to a raw, uninstrumented `<iframe>`.
+
+With the proxy, the VS Code webview CSP (`vscode-ext/src/webview-html.ts`) narrows
+from the old broad `frame-src http: https:` to the loopback proxy origin only:
 
 ```
 frame-src http://127.0.0.1:* http://localhost:*
@@ -241,14 +199,46 @@ frame-src http://127.0.0.1:* http://localhost:*
 
 ### Security model
 
-The same fences as the stream relay: loopback-only bind both sides; per-surface
-token grants (no open forwarder); **header-stripping restricted to loopback**
-(remote upstreams never stripped — no force-framing third-party sites); the
-injected shim is fixed and Dormouse-owned (no user script ever reaches the page).
-**SSRF consideration:** the proxy fetches a user-supplied URL (an SSRF shape, e.g.
-cloud metadata `169.254.169.254`); the trust boundary is the user's own
-`dor iframe <url>` so risk is bounded, but the proxy should consider refusing
-link-local/metadata ranges.
+The same fences as the stream relay: loopback-only bind both sides; a per-surface
+grant served by a dedicated **single-upstream** server (no open forwarder); the
+injected shim is fixed and Dormouse-owned (no user script ever reaches the page);
+header-stripping never force-frames a third-party site (a refusing remote is
+diverted to an error page, not stripped). **SSRF:** the proxy fetches a
+user-supplied URL, so it refuses link-local / cloud-metadata ranges
+(`169.254.0.0/16`, `fe80::/10`) and trusts other ranges — the trust boundary is the
+user's own `dor iframe <url>`.
+
+## Remaining limitations
+
+### Inherent (designed around, not patchable)
+
+- **Focus still leaves Dormouse for the tool's own keys.** The shim reclaims only
+  the leader chord; every other keystroke fires in the frame's document and never
+  reaches the Wall's `window` listener — *by design*, so the embedded tool keeps
+  full keyboard interactivity. The same-origin policy means the parent can't
+  observe those keys; the leader is the one chord we round-trip.
+
+### Known v1 gaps
+
+- **`https://` upstreams are deferred** — the panel shows a `scheme` message with a
+  `dor ab` hint.
+- **Absolute-origin sub-resources bypass the proxy.** The dedicated-port origin
+  makes root-relative URLs proxy transparently, but a dev server that emits
+  absolute `http://localhost:5173/…` (notably Vite's HMR `ws://localhost:5173/…`)
+  connects straight to the upstream — uninstrumented, though harmless for loopback
+  since the browser can reach it.
+- **Streaming SSR is buffered.** The proxy buffers an HTML response fully before
+  injecting the shim, adding latency for streamed responses.
+- **No teardown-on-kill hook yet.** A killed iframe surface's proxy server is
+  reaped by the idle sweep, not immediately on kill. (The shared teardown hook is
+  tracked under Path 2 below.)
+
+---
+
+# Future Work
+
+> Designed, not yet built. Everything above is implemented; everything below is
+> the roadmap. Both paths reuse the proxy + shim substrate unchanged.
 
 ## Render Backends: Two Axes
 
@@ -259,7 +249,7 @@ the grid:
 | | **Target: just a URL** | **Target: a backend Dormouse spawns & owns** |
 | --- | --- | --- |
 | **Render: screencast** (agent-browser) | `dor ab open <url>` — today | (possible, rarely wanted) |
-| **Render: embed** (proxy + shim iframe) | `dor iframe <localhost>` — above | **the plugin system (Path 2)** |
+| **Render: embed** (proxy + shim iframe) | `dor iframe <localhost>` — today | **the plugin system (Path 2)** |
 
 - **Render axis** = *how* you see it. `screencast` (real Chromium, agent-drivable,
   any URL, laggy) vs `embed` (the page's own DOM, zero-lag, loopback-only, not
@@ -278,12 +268,12 @@ embed. This is the hedge on the agent-browser bet — if the screencast's lag is
 unacceptable for a local dev server, one gesture swaps it to the zero-lag embed.
 
 **Do not fuse the surfaces into a dual-mode mega-component.** `AgentBrowserPanel`
-is already 840 lines and the input models differ fundamentally (CDP `input_*`
-messages vs native DOM). Instead, make the swap a **layout operation: replace the
-pane's renderer in place, preserving the target.** `createContentSurface` already
-replaces an untouched terminal in its slot — generalize that to "replace surface X
-with surface Y at the same dock position," triggered by a header affordance ("open
-in iframe" / "open in browser"). The substrate makes this nearly free.
+is already large and the input models differ fundamentally (CDP `input_*` messages
+vs native DOM). Instead, make the swap a **layout operation: replace the pane's
+renderer in place, preserving the target.** `createContentSurface` already replaces
+an untouched terminal in its slot — generalize that to "replace surface X with
+surface Y at the same dock position," triggered by a header affordance ("open in
+iframe" / "open in browser").
 
 ## Path 2 — Plugin System
 
@@ -295,30 +285,29 @@ per-workspace or per-pane? reuse across panes?), allocate/health-check the port,
 wire the proxy to it, and **reap the process when the pane is killed.**
 
 That last requirement is the second consumer that justifies generalizing the
-per-surface **teardown-on-kill hook** — the one-off `agent-browser` close
-currently special-cased in `Wall.tsx`'s `killPaneImmediately` (see
-[dor-agent-browser.md](dor-agent-browser.md) → Lifecycle). A plugin backend that
-leaks when its pane closes is a real bug, so the abstraction stops being premature
-exactly here.
-
-**Risk specific to the motivating example (code-server / openvscode-server):**
-it will stress the substrate more than a Vite dev server — worth a spike before
-committing. It needs `allow-same-origin allow-scripts allow-forms allow-popups
-allow-downloads allow-modals` (still omitting `allow-top-navigation` for the
-anti-framebust guarantee); may want COOP/COEP for cross-origin isolation
+per-surface **teardown-on-kill hook** — the one-off `agent-browser` close currently
+special-cased in `Wall.tsx`'s `killPaneImmediately` (see
+[dor-agent-browser.md](dor-agent-browser.md) → Lifecycle), and the same hook the
+iframe proxy server would use to close immediately instead of waiting for the idle
+sweep.
+
+**Risk specific to the motivating example (code-server / openvscode-server):** it
+will stress the substrate more than a Vite dev server — worth a spike before
+committing. It needs a broader `sandbox` (`allow-same-origin allow-scripts
+allow-forms allow-popups allow-downloads allow-modals`, still omitting
+`allow-top-navigation`); may want COOP/COEP for cross-origin isolation
 (SharedArrayBuffer) — verify against the actual target; and leans on WebSocket
 passthrough harder than most.
 
-## Open Decisions
-
-1. **Remote frameable targets** — render best-effort with the leader shim, or
-   always route remote to an error page that points at `dor ab`? The latter keeps
-   a crisp "loopback = iframe, remote = agent-browser" line.
-2. **Absolute-origin sub-resources.** Dev servers emitting absolute
-   `http://localhost:5173/...` URLs bypass the proxy origin — widen CSP to allow
-   the loopback upstream (cheap) vs. rewrite response bodies (invasive)?
-3. **SSRF range-blocking** — refuse link-local/metadata/private ranges, or trust
-   the user's own command?
-4. **Web host** — no host process to run a proxy: hide the surface, or keep the
-   blind raw-iframe fallback?
-</content>
+## Decisions made in v1
+
+1. **Remote frameable targets** → render best-effort with the leader shim
+   (loopback fully instrumented; a remote that refuses → error page). Keeps a crisp
+   "loopback = full instrument, remote = best-effort, refusing = `dor ab`" line.
+2. **Absolute-origin sub-resources** → left as a known gap. The dedicated-port
+   origin solves root-relative URLs for free; absolute upstream URLs bypass the
+   proxy rather than rewriting response bodies.
+3. **SSRF range-blocking** → refuse link-local/metadata, trust other ranges (the
+   command is the user's own).
+4. **Web host** → keep the blind raw-iframe fallback rather than hiding the
+   surface.

From 3a41436ed3b6659cb6cb3f142d514eae168aeb1d Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:19:54 -0700
Subject: [PATCH 04/10] iframe-proxy: dedup collectBody completion handler

Both the `end` and `error` stream handlers decoded the buffered body with
the same expression; hoist it to a single `complete` callback. No behavior
change.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 vscode-ext/src/iframe-proxy-host.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index 61694a86..0699257b 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -235,8 +235,9 @@ function collectBody(stream: http.IncomingMessage, done: (body: string) => void)
     }
     chunks.push(chunk);
   });
-  stream.on('end', () => done(Buffer.concat(chunks).toString('utf8')));
-  stream.on('error', () => done(Buffer.concat(chunks).toString('utf8')));
+  const complete = () => done(Buffer.concat(chunks).toString('utf8'));
+  stream.on('end', complete);
+  stream.on('error', complete);
 }
 
 function sanitizeResponseHeaders(grant: Grant, headers: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {

From 9164a43972f23b582805e481ab36331d731ad66f Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:31:21 -0700
Subject: [PATCH 05/10] iframe-proxy: preserve URL fragments

---
 docs/specs/dor-iframe.md            | 2 ++
 vscode-ext/src/iframe-proxy-host.ts | 7 ++++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/specs/dor-iframe.md b/docs/specs/dor-iframe.md
index 0d0d097b..b3418241 100644
--- a/docs/specs/dor-iframe.md
+++ b/docs/specs/dor-iframe.md
@@ -107,6 +107,8 @@ openvscode-server's connection).
   checks) see a same-origin request, and a `Location` redirect back to the
   upstream origin is rewritten to the proxy origin so it doesn't bounce the frame
   off-proxy. Non-HTML passes through (framing/hop-by-hop headers still stripped).
+  The initial framed proxy URL preserves the target's path, query, and fragment;
+  the fragment remains browser-only and is not sent on upstream HTTP requests.
 - **WebSocket passthrough.** Upgrades are forwarded as a raw byte pipe once the
   upgrade head is rewritten (`Host`/`Origin` → upstream), exactly like the stream
   relay.
diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index 0699257b..b1ba62c0 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -154,9 +154,10 @@ export async function createIframeProxyUrl(targetUrl: string): Promise<IframePro
   log.info(`[iframe-proxy] ${upstream.href} → ${grant.proxyOrigin} (loopback=${grant.isLoopback})`);
 
   // The proxy origin maps to one fixed upstream, so the full path resolves
-  // transparently — keep the upstream's own initial path so deep-linked targets
-  // land where the user pointed.
-  return { ok: true, url: `${grant.proxyOrigin}${upstream.pathname}${upstream.search}` };
+  // transparently — keep the upstream's own initial path/search/hash so
+  // deep-linked and hash-routed targets land where the user pointed. The hash is
+  // browser-only; it is preserved in the iframe URL but never sent upstream.
+  return { ok: true, url: `${grant.proxyOrigin}${upstream.pathname}${upstream.search}${upstream.hash}` };
 }
 
 function listen(server: http.Server): Promise<number> {

From 2e97fb50440a44d88047823bac6cd6e1ba3186e7 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:32:17 -0700
Subject: [PATCH 06/10] iframe-proxy: respect scoped frame ancestors

---
 docs/specs/dor-iframe.md            |  8 +++++---
 vscode-ext/src/iframe-proxy-host.ts | 22 ++++++++++++++++------
 2 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/docs/specs/dor-iframe.md b/docs/specs/dor-iframe.md
index b3418241..ed32379f 100644
--- a/docs/specs/dor-iframe.md
+++ b/docs/specs/dor-iframe.md
@@ -67,7 +67,7 @@ new technique, the proven one.
 | Target | Proxy behavior |
 | --- | --- |
 | **Loopback** (`localhost`/`127.0.0.1`/`[::1]`) http | Full instrument: strip `X-Frame-Options`, drop the page CSP, inject the shim, serve. The user spawned it; framing is the intent. |
-| **Remote** http, frameable | Best-effort render with the injected shim (flagged that `dor ab` is the better tool for arbitrary browsing). |
+| **Remote** http, frameable | Best-effort render with the injected shim (flagged that `dor ab` is the better tool for arbitrary browsing). A CSP `frame-ancestors *` is considered frameable; scoped sources such as `https://*.example.com` are restrictive. |
 | **Remote** http, refuses framing | **Never force-framed.** Serve a Dormouse error page with a one-click hint to `dor ab open <url>`. |
 | **Unreachable** (conn refused, DNS, non-2xx) | Serve a Dormouse error page ("is the dev server running?"). |
 | **`https://`** | Deferred. The panel reports `scheme` and points at `dor ab`. |
@@ -205,8 +205,10 @@ The same fences as the stream relay: loopback-only bind both sides; a per-surfac
 grant served by a dedicated **single-upstream** server (no open forwarder); the
 injected shim is fixed and Dormouse-owned (no user script ever reaches the page);
 header-stripping never force-frames a third-party site (a refusing remote is
-diverted to an error page, not stripped). **SSRF:** the proxy fetches a
-user-supplied URL, so it refuses link-local / cloud-metadata ranges
+diverted to an error page, not stripped). For CSP, only a standalone
+`frame-ancestors *` is permissive; wildcard host patterns remain restrictive.
+**SSRF:** the proxy fetches a user-supplied URL, so it refuses link-local /
+cloud-metadata ranges
 (`169.254.0.0/16`, `fe80::/10`) and trusts other ranges — the trust boundary is the
 user's own `dor iframe <url>`.
 
diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index b1ba62c0..b0dc6042 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -272,15 +272,25 @@ function instrumentHtml(body: string): string {
 }
 
 // A remote refuses framing if it sends any X-Frame-Options or a CSP
-// frame-ancestors that is not the permissive `*`. Conservative on purpose: when
-// in doubt we divert to an error page rather than show a guaranteed-blank frame.
+// frame-ancestors that is not the permissive standalone `*`. Conservative on
+// purpose: when in doubt we divert to an error page rather than show a
+// guaranteed-blank frame.
 function refusesFraming(headers: http.IncomingHttpHeaders): boolean {
   if (headers['x-frame-options']) return true;
   const csp = headers['content-security-policy'];
-  const cspText = Array.isArray(csp) ? csp.join(';') : (csp ?? '');
-  const match = /frame-ancestors([^;]*)/i.exec(cspText);
-  if (!match) return false;
-  return !/\*/.test(match[1]);
+  const policies = Array.isArray(csp) ? csp : csp ? [csp] : [];
+  return policies.some((policy) => hasRestrictiveFrameAncestors(policy));
+}
+
+function hasRestrictiveFrameAncestors(policy: string): boolean {
+  const directives = policy.split(';');
+  for (const directive of directives) {
+    const parts = directive.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0 || parts[0].toLowerCase() !== 'frame-ancestors') continue;
+    const sources = parts.slice(1);
+    if (!sources.includes('*')) return true;
+  }
+  return false;
 }
 
 // --- WebSocket upgrade passthrough (dev-server HMR, openvscode-server) -------

From f2c692a709b35f541a19fc22f16f6c66c83209be Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:32:54 -0700
Subject: [PATCH 07/10] iframe-proxy: inject shim on error pages

---
 docs/specs/dor-iframe.md            | 4 +++-
 vscode-ext/src/iframe-proxy-host.ts | 2 +-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/docs/specs/dor-iframe.md b/docs/specs/dor-iframe.md
index ed32379f..3bfe0b1b 100644
--- a/docs/specs/dor-iframe.md
+++ b/docs/specs/dor-iframe.md
@@ -157,7 +157,9 @@ precise error *page* from the proxy origin (which frames fine): a refused remote
 responding at `localhost:8080` — is the dev server running?". `createIframeProxyUrl`
 itself returns `{ ok: false, reason }` only for the synchronous cases (chiefly an
 unproxyable `scheme`); reachability and frame-refusal are surfaced as served
-pages.
+pages. These served error pages include the same fixed leader shim as proxied
+HTML, so the keyboard escape path still works after the user clicks inside an
+error state.
 
 ### Cursor alignment (the out-of-process-frame offset)
 
diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index b0dc6042..84661b2a 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -375,7 +375,7 @@ function unreachablePage(upstream: URL, detail: string): ErrorPage {
 }
 
 function serveErrorPage(res: http.ServerResponse, page: ErrorPage): void {
-  const html = errorPageHtml(page);
+  const html = instrumentHtml(errorPageHtml(page));
   res.writeHead(200, {
     'content-type': 'text/html; charset=utf-8',
     'content-length': Buffer.byteLength(html).toString(),

From a00f596026c46160dde14f062eaa20fabaafe023 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 22:53:29 -0700
Subject: [PATCH 08/10] iframe-proxy: derive proxyOrigin instead of
 ternary-in-deps

Replace the ternary-in-dependency-array for the proxy-origin registration
effect with a named derived value used by both the effect body and its
dependency array. Same behavior, reads as a plain value.

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

diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 8a2ed492..2632aac7 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -78,10 +78,11 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
 
   // Trust postMessage from this frame's origin (validated by the Wall's
   // keyboard/focus channel) only while the proxied surface is live.
+  const proxyOrigin = resolution.kind === 'proxied' ? resolution.origin : null;
   useEffect(() => {
-    if (resolution.kind !== 'proxied' || !resolution.origin) return;
-    return registerProxyOrigin(resolution.origin);
-  }, [resolution.kind === 'proxied' ? resolution.origin : null]);
+    if (!proxyOrigin) return;
+    return registerProxyOrigin(proxyOrigin);
+  }, [proxyOrigin]);
 
   // Register a focus handle so onClickPanel → enterTerminalMode can focus the
   // frame like any other surface (spec → "#3"). Focusing the element moves

From 72d13a48edefaa3ff4df1f77b5bfa4aaf6993b68 Mon Sep 17 00:00:00 2001
From: dormouse-bot <287024035+dormouse-bot@users.noreply.github.com>
Date: Wed, 17 Jun 2026 06:57:32 +0000
Subject: [PATCH 09/10] iframe-proxy: serve error page on HTML body truncation

When an upstream HTML response exceeds HTML_BODY_LIMIT, collectBody
previously destroyed the stream and handed back the partial bytes, which
were then instrumented and served as a truncated document. Serve a clear
"exceeded HTML_BODY_LIMIT of N MB" error page instead, so we never ship
half a page (where the shim may have landed past the cutoff).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 vscode-ext/src/iframe-proxy-host.ts | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index 84661b2a..fe62771e 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -198,13 +198,19 @@ function handleRequest(grant: Grant, req: http.IncomingMessage, res: http.Server
       passThrough(grant, upstreamRes, res);
       return;
     }
-    collectBody(upstreamRes, (body) => {
+    collectBody(upstreamRes, (body, truncated) => {
       // A remote that forbids embedding is never force-framed — serve an
       // actionable page that points at `dor ab` instead of a blank pane.
       if (!grant.isLoopback && refusesFraming(upstreamRes.headers)) {
         serveErrorPage(res, frameRefusedPage(grant.upstream));
         return;
       }
+      // An over-limit body can't be safely instrumented (the shim may land past
+      // the cutoff, and serving half a document is worse than an honest error).
+      if (truncated) {
+        serveErrorPage(res, bodyTooLargePage(grant.upstream));
+        return;
+      }
       const html = instrumentHtml(body);
       const outHeaders = sanitizeResponseHeaders(grant, upstreamRes.headers);
       outHeaders['content-type'] = 'text/html; charset=utf-8';
@@ -225,18 +231,20 @@ function passThrough(grant: Grant, upstreamRes: http.IncomingMessage, res: http.
   upstreamRes.pipe(res);
 }
 
-function collectBody(stream: http.IncomingMessage, done: (body: string) => void): void {
+function collectBody(stream: http.IncomingMessage, done: (body: string, truncated: boolean) => void): void {
   const chunks: Buffer[] = [];
   let size = 0;
+  let truncated = false;
   stream.on('data', (chunk: Buffer) => {
     size += chunk.length;
     if (size > HTML_BODY_LIMIT) {
+      truncated = true;
       stream.destroy();
       return;
     }
     chunks.push(chunk);
   });
-  const complete = () => done(Buffer.concat(chunks).toString('utf8'));
+  const complete = () => done(Buffer.concat(chunks).toString('utf8'), truncated);
   stream.on('end', complete);
   stream.on('error', complete);
 }
@@ -367,6 +375,15 @@ function frameRefusedPage(upstream: URL): ErrorPage {
   };
 }
 
+function bodyTooLargePage(upstream: URL): ErrorPage {
+  const limit = `${Math.round(HTML_BODY_LIMIT / (1024 * 1024))} MB`;
+  return {
+    title: `${upstream.host} sent too much HTML`,
+    message: `The HTML response from ${upstream.href} exceeded HTML_BODY_LIMIT of ${limit}, so it couldn’t be instrumented and shown in an iframe surface.`,
+    hint: `dor ab open ${upstream.href}`,
+  };
+}
+
 function unreachablePage(upstream: URL, detail: string): ErrorPage {
   return {
     title: `Nothing responding at ${upstream.host}`,

From 2d0ee432dd5812caa13afa1ada20a231339ed287 Mon Sep 17 00:00:00 2001
From: dormouse-bot <287024035+dormouse-bot@users.noreply.github.com>
Date: Wed, 17 Jun 2026 07:01:17 +0000
Subject: [PATCH 10/10] iframe-proxy: settle collectBody on truncation so error
 page serves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

stream.destroy() (no error arg) emits 'close'/'aborted' but neither
'end' nor 'error', so the listeners that call complete() never fired on
the truncation path — the over-limit branch in collectBody's callback was
unreachable and the downstream response hung with nothing served. Call
complete() explicitly after destroy(), guarded by a 'settled' flag so the
normal end/error path can't double-serve.

Co-Authored-By: Claude <noreply@anthropic.com>
---
 vscode-ext/src/iframe-proxy-host.ts | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index fe62771e..2d91bbd7 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -235,16 +235,25 @@ function collectBody(stream: http.IncomingMessage, done: (body: string, truncate
   const chunks: Buffer[] = [];
   let size = 0;
   let truncated = false;
+  let settled = false;
+  const complete = () => {
+    if (settled) return;
+    settled = true;
+    done(Buffer.concat(chunks).toString('utf8'), truncated);
+  };
   stream.on('data', (chunk: Buffer) => {
     size += chunk.length;
     if (size > HTML_BODY_LIMIT) {
       truncated = true;
+      // `destroy()` (no error) emits 'close'/'aborted' but neither 'end' nor
+      // 'error', so the listeners below would never fire — settle explicitly
+      // or the downstream response hangs with nothing served.
       stream.destroy();
+      complete();
       return;
     }
     chunks.push(chunk);
   });
-  const complete = () => done(Buffer.concat(chunks).toString('utf8'), truncated);
   stream.on('end', complete);
   stream.on('error', complete);
 }