dor iframe: transparent proxy for the iframe surface

[nedtwigg]

dor iframe: transparent proxy for the iframe surface

Implements the "Transparent Proxy (Instrumented Iframe)" section of docs/specs/dor-iframe.md. dor iframe <url> previously pointed a raw <iframe> at the target — a separate browsing context Dormouse couldn't observe or control, which made it unusable for real interaction (focus left Dormouse, blocked pages showed a blank pane, no error signals). This fronts the target with a host-owned loopback proxy so Dormouse serves the bytes, and from that one capability the surface gains a keyboard side-channel, an accurate focus model, and real error pages. It's now usable for loopback dev servers.

How it works

Instead of framing the target, the panel asks the host for a proxy URL (createIframeProxyUrl) and frames that. The proxy (vscode-ext/src/iframe-proxy-host.ts) fetches the upstream and serves it back on loopback, with policy by target:

Target	Behavior
Loopback http	Full instrument: strip X-Frame-Options, drop page CSP, inject the shim
Remote http, frameable	Best-effort render with the shim
Remote http, refuses framing	Served error page pointing at dor ab open <url>
Unreachable	Served error page ("is the dev server running?")
https	Deferred — panel shows a dor ab hint

• Keyboard side-channel (limitation maybe: drop node-pty for a Rust backend #1): a fixed, Dormouse-owned inline shim forwards only the reserved leader chord (dual-tap ⌘/⇧) via postMessage; every other keystroke flows to the tool. The Wall validates event.origin against live proxy grants and re-enters the same dispatch (exitTerminalMode).
• Focus model (Leaky-bucket mechanism for soft-TODOs #2/Fix terminal spawning #3): a focused iframe blurs the parent window without backgrounding the app, so we read document.hasFocus() (stays true while a descendant frame holds focus) instead of going inactive; the surface registers a focus handle so focusSession can focus it, and adopts "frame took focus" as entering the pane (clicking a cross-origin frame doesn't bubble mousedown).
• Error signals (split a pane and keep the cwd #4): the proxy is the server, so it serves precise error pages from the proxy origin (themselves instrumented with the shim, so the leader chord works there too).
• WebSocket passthrough for dev-server HMR; anti-framebust via sandbox without allow-top-navigation; SSRF guard refusing link-local/metadata ranges.
• Frame-refusal detection parses CSP frame-ancestors per-directive and treats only a standalone * as permissive — a scoped source like https://*.example.com is correctly classed as refusing rather than slipping through to a blank frame.
• URL fidelity: the framed proxy URL preserves the target's path, query, and fragment (hash-routed SPAs land on the right route); the fragment stays browser-only and is never sent upstream.
• Cursor alignment: a cross-origin iframe is an out-of-process frame, and dockview's contain: layout root made Chromium map pointer events to the wrong origin (clicks landed offset). Fixed by giving the iframe's container its own identity compositing layer (transform: translateZ(0)).
• CSP narrowed from frame-src http: https: to frame-src http://127.0.0.1:* http://localhost:*.

Design notes (deliberate deviations from the original spec sketch)

• Per-grant dedicated loopback server, not a shared port. The grant's origin is the grant, so root-relative sub-resources proxy transparently with zero body rewriting, and a server bound to one upstream is inherently not an open forwarder.
• No token in the URL. A path-prefix token landed in location.pathname and broke client-side routers (a React-Router/Remix dev server matched no route and rendered its own 404). The dedicated server is the isolation boundary instead.

The spec (docs/specs/dor-iframe.md) is updated to match: the proxy moves out of "Future Work," limitations #2–#4 are marked resolved, and the open decisions become the decisions actually made. Path 1 (swappable render backend) and Path 2 (plugin system) remain future work.

Host coverage

Implemented for the VS Code host. Other hosts degrade gracefully — createIframeProxyUrl is optional; where it's absent the panel falls back to a raw, uninstrumented <iframe>.

Known gap: standalone (Tauri) does not yet implement createIframeProxyUrl, so dor iframe there falls back to the raw frame (no shim/error pages/header handling) — the same host-parity gap the agent-browser stream relay already has. Bringing it to parity means running the proxy from the Tauri sidecar and extracting the host-agnostic proxy helpers (incl. the frame-ancestors parsing) into a shared, DOM-free module. Tracked as a follow-up.

Testing

• Runtime smoke test of the proxy (loopback instrumentation, header stripping, shim injection, root-relative routing, path preservation, unreachable/scheme/SSRF handling, WebSocket upgrade).
• Lib tsc -b clean; full lib suite green (592 tests); extension bundles clean.
• Manually verified in VS Code against a React-Router dev server: page loads, leader chord round-trips out of the frame, cursor aligned.

Known v1 gaps

• https upstreams deferred.
• Absolute-origin sub-resources (e.g. Vite's ws://localhost:5173 HMR) bypass the proxy — harmless for loopback, but uninstrumented.
• HTML responses are buffered before shim injection (latency for streamed SSR).
• No teardown-on-kill hook yet — a killed surface's proxy server is reaped by the idle sweep (the shared hook is tracked under Path 2).
• hasRestrictiveFrameAncestors is not unit-tested (vscode-ext has no test harness); covered when the helpers move to the shared lib/ module.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mouseterm with    Cloudflare Pages

Latest commit:	2d0ee43
Status:	✅  Deploy successful!
Preview URL:	https://d40838a8.mouseterm.pages.dev
Branch Preview URL:	https://iframe-shim.mouseterm.pages.dev

View logs

[dormouse-bot]

Solid, carefully-reasoned implementation — the focus model, the faithful shim port of handle-dual-tap, and the per-grant single-upstream isolation all hang together well. One latent edge case worth a look (inline).

[nedtwigg]

@dormouse-bot if we hit truncation, I definitely do not want to serve the truncated HTML. I want to serve a page that says "Error, exceeded HTML_BODY_LIMIT of XXX". Push a commit to make it that way.

[dormouse-bot]

Done in 72d13a4 (pushed to iframe-shim).

collectBody now tracks whether it hit HTML_BODY_LIMIT and reports it to the caller. When truncated, handleRequest serves a bodyTooLargePage error page ("…exceeded HTML_BODY_LIMIT of 32 MB…") from the proxy origin instead of instrumenting and serving the partial bytes. The error page is itself shim-instrumented (so the leader chord still works there) and points at dor ab open <url> as the fallback.

Extension bundles clean via esbuild.