From fa3e08f13247edf97ee4b91c35188755a90a3a7c Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Tue, 16 Jun 2026 23:24:36 -0700
Subject: [PATCH 01/10] iframe-proxy: share the proxy across VS Code and
 standalone via lib
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move the host-agnostic proxy into lib/src/host as one TypeScript source so
both hosts run the same code instead of reimplementing it:

  - iframe-proxy-rewrite.ts — pure policy/rewriting (shim, instrumentHtml,
    refusesFraming/hasRestrictiveFrameAncestors, loopback/SSRF checks, error
    pages). Now unit-tested (17 cases), incl. the frame-ancestors logic.
  - iframe-proxy.ts — the Node http/net server, logger injected so it depends
    on neither host.
  - IframeProxyResult moves to a dependency-free leaf (platform/
    iframe-proxy-types.ts, re-exported) so the Node code doesn't pull the
    browser type-graph into a Node compile.

VS Code: iframe-proxy-host.ts collapses to a thin wrapper that injects `log`.

Standalone: build-sidecar-proxy.mjs esbuilds the shared TS into
sidecar/iframe-proxy.cjs (wired into stage/build/tauri, gitignored); the
sidecar handles iframe:createProxyUrl over stdio; a Rust
iframe_create_proxy_url command bridges it; tauri-adapter implements
createIframeProxyUrl; and the Tauri CSP gains frame-src for the loopback
proxy. IframePanel is shared, so the webview needs no changes.

Verified: lib tsc + 609 tests, VS Code bundle, sidecar cjs builds and
runtime-proxies, standalone tsc. The Rust command needs a machine with the
Rust toolchain to compile/run (cargo absent here).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                 |   1 +
 lib/src/host/iframe-proxy-rewrite.test.ts  | 117 ++++++
 lib/src/host/iframe-proxy-rewrite.ts       | 153 ++++++++
 lib/src/host/iframe-proxy.ts               | 287 ++++++++++++++
 lib/src/lib/platform/iframe-proxy-types.ts |  19 +
 lib/src/lib/platform/types.ts              |  19 +-
 lib/tsconfig.app.json                      |   4 +-
 pnpm-lock.yaml                             |   3 +
 standalone/package.json                    |   7 +-
 standalone/scripts/build-sidecar-proxy.mjs |  23 ++
 standalone/sidecar/main.js                 |   9 +
 standalone/src-tauri/src/lib.rs            |  18 +
 standalone/src-tauri/tauri.conf.json       |   2 +-
 standalone/src/tauri-adapter.ts            |  13 +-
 vscode-ext/src/iframe-proxy-host.ts        | 419 +--------------------
 15 files changed, 664 insertions(+), 430 deletions(-)
 create mode 100644 lib/src/host/iframe-proxy-rewrite.test.ts
 create mode 100644 lib/src/host/iframe-proxy-rewrite.ts
 create mode 100644 lib/src/host/iframe-proxy.ts
 create mode 100644 lib/src/lib/platform/iframe-proxy-types.ts
 create mode 100644 standalone/scripts/build-sidecar-proxy.mjs

diff --git a/.gitignore b/.gitignore
index ca51287f..ba812d73 100644
--- a/.gitignore
+++ b/.gitignore
@@ -28,6 +28,7 @@ standalone/src-tauri/binaries/
 standalone/src-tauri/gen/
 standalone/dist/
 standalone/sidecar/dor-cli/
+standalone/sidecar/iframe-proxy.cjs
 standalone/sidecar/node_modules/
 standalone/node_modules/
 
diff --git a/lib/src/host/iframe-proxy-rewrite.test.ts b/lib/src/host/iframe-proxy-rewrite.test.ts
new file mode 100644
index 00000000..394f882f
--- /dev/null
+++ b/lib/src/host/iframe-proxy-rewrite.test.ts
@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import {
+  hasRestrictiveFrameAncestors,
+  refusesFraming,
+  instrumentHtml,
+  isLoopbackHost,
+  isBlockedAddress,
+  IFRAME_SHIM,
+  errorPageHtml,
+  frameRefusedPage,
+} from './iframe-proxy-rewrite';
+
+describe('hasRestrictiveFrameAncestors', () => {
+  it('treats a standalone * as permissive', () => {
+    expect(hasRestrictiveFrameAncestors('frame-ancestors *')).toBe(false);
+    expect(hasRestrictiveFrameAncestors("default-src 'self'; frame-ancestors *")).toBe(false);
+  });
+
+  it('treats a scoped wildcard source as restrictive', () => {
+    // The naive `/\*/` test would wrongly pass this — it contains a `*`.
+    expect(hasRestrictiveFrameAncestors('frame-ancestors https://*.example.com')).toBe(true);
+  });
+
+  it('treats self / none / scoped hosts as restrictive', () => {
+    expect(hasRestrictiveFrameAncestors("frame-ancestors 'self'")).toBe(true);
+    expect(hasRestrictiveFrameAncestors("frame-ancestors 'none'")).toBe(true);
+    expect(hasRestrictiveFrameAncestors('frame-ancestors https://example.com')).toBe(true);
+  });
+
+  it('ignores other directives and is case/space tolerant', () => {
+    expect(hasRestrictiveFrameAncestors("script-src 'self'")).toBe(false);
+    expect(hasRestrictiveFrameAncestors('FRAME-ANCESTORS   *')).toBe(false);
+    expect(hasRestrictiveFrameAncestors('  frame-ancestors   https://x.com  ;  ')).toBe(true);
+  });
+});
+
+describe('refusesFraming', () => {
+  it('refuses on any X-Frame-Options', () => {
+    expect(refusesFraming({ 'x-frame-options': 'DENY' })).toBe(true);
+    expect(refusesFraming({ 'x-frame-options': 'SAMEORIGIN' })).toBe(true);
+  });
+
+  it('allows when there is no framing header', () => {
+    expect(refusesFraming({})).toBe(false);
+    expect(refusesFraming({ 'content-security-policy': "default-src 'self'" })).toBe(false);
+  });
+
+  it('honors a restrictive CSP frame-ancestors', () => {
+    expect(refusesFraming({ 'content-security-policy': "frame-ancestors 'self'" })).toBe(true);
+    expect(refusesFraming({ 'content-security-policy': 'frame-ancestors *' })).toBe(false);
+  });
+
+  it('refuses if any of multiple CSP headers is restrictive', () => {
+    expect(refusesFraming({
+      'content-security-policy': ['frame-ancestors *', "frame-ancestors 'self'"],
+    })).toBe(true);
+  });
+});
+
+describe('instrumentHtml', () => {
+  it('injects the shim before </head>', () => {
+    const out = instrumentHtml('<html><head><title>x</title></head><body>hi</body></html>');
+    expect(out).toContain("__dormouse:'leader'");
+    expect(out).toMatch(/<\/script><\/head>/);
+    expect(out).toContain('<title>x</title>');
+  });
+
+  it('falls back to after <body> when there is no head', () => {
+    const out = instrumentHtml('<body>hi</body>');
+    expect(out).toMatch(/<body>\s*<script>/);
+  });
+
+  it('strips an in-document CSP meta', () => {
+    const out = instrumentHtml('<head><meta http-equiv="Content-Security-Policy" content="default-src \'none\'"></head>');
+    expect(out).not.toMatch(/http-equiv=["']?content-security-policy/i);
+  });
+
+  it('carries the leader-only shim (no focus/blur channel)', () => {
+    expect(IFRAME_SHIM).toContain("__dormouse:'leader'");
+    expect(IFRAME_SHIM).not.toContain('focus');
+  });
+});
+
+describe('isLoopbackHost', () => {
+  it('recognizes loopback hosts', () => {
+    for (const h of ['localhost', '127.0.0.1', '127.0.0.2', '::1', '[::1]']) {
+      expect(isLoopbackHost(h)).toBe(true);
+    }
+  });
+  it('rejects remote hosts', () => {
+    for (const h of ['example.com', '10.0.0.5', '192.168.1.2']) {
+      expect(isLoopbackHost(h)).toBe(false);
+    }
+  });
+});
+
+describe('isBlockedAddress', () => {
+  it('blocks link-local / cloud-metadata ranges', () => {
+    expect(isBlockedAddress('169.254.169.254')).toBe(true);
+    expect(isBlockedAddress('169.254.0.1')).toBe(true);
+    expect(isBlockedAddress('fe80::1')).toBe(true);
+  });
+  it('allows ordinary hosts', () => {
+    expect(isBlockedAddress('127.0.0.1')).toBe(false);
+    expect(isBlockedAddress('localhost')).toBe(false);
+    expect(isBlockedAddress('example.com')).toBe(false);
+  });
+});
+
+describe('errorPageHtml', () => {
+  it('renders a frameable page with the dor ab hint, escaping the target', () => {
+    const html = errorPageHtml(frameRefusedPage(new URL('https://example.com/a"b')));
+    expect(html).toContain('refuses to be embedded');
+    expect(html).toContain('dor ab open');
+    expect(html).not.toContain('a"b'); // escaped
+  });
+});
diff --git a/lib/src/host/iframe-proxy-rewrite.ts b/lib/src/host/iframe-proxy-rewrite.ts
new file mode 100644
index 00000000..7ed92a56
--- /dev/null
+++ b/lib/src/host/iframe-proxy-rewrite.ts
@@ -0,0 +1,153 @@
+/**
+ * Pure, dependency-free helpers for the iframe transparent proxy
+ * (docs/specs/dor-iframe.md → "The Transparent Proxy").
+ *
+ * Split out from the Node server (`iframe-proxy.ts`) so the policy/rewriting
+ * logic is shared by every host that runs the proxy (VS Code extension host,
+ * Tauri sidecar) and is unit-testable without standing up a server. Nothing
+ * here imports `http`/`net`; headers are typed structurally so this file is
+ * runtime-agnostic.
+ */
+
+/** Header bag shape both `http.IncomingHttpHeaders` and a plain map satisfy. */
+export type ProxyHeaders = Record<string, string | string[] | undefined>;
+
+// Hop-by-hop headers (RFC 7230 §6.1) plus framing headers we manage ourselves.
+// Never forwarded downstream.
+export 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).
+export 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);
+})();`;
+
+// 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
+// stripped separately via STRIP_RESPONSE_HEADERS.
+export 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 standalone `*`. Conservative on
+// purpose: when in doubt we divert to an error page rather than show a
+// guaranteed-blank frame.
+export function refusesFraming(headers: ProxyHeaders): boolean {
+  if (headers['x-frame-options']) return true;
+  const csp = headers['content-security-policy'];
+  const policies = Array.isArray(csp) ? csp : csp ? [csp] : [];
+  return policies.some((policy) => hasRestrictiveFrameAncestors(policy));
+}
+
+export 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;
+}
+
+export function isLoopbackHost(hostname: string): boolean {
+  const h = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  return h === 'localhost' || h === '127.0.0.1' || h === '::1' || h.startsWith('127.');
+}
+
+export 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;
+}
+
+// --- Served error / diagnostic pages ----------------------------------------
+
+export interface ErrorPage {
+  title: string;
+  message: string;
+  hint?: string;
+}
+
+export 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}`,
+  };
+}
+
+export 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?`,
+  };
+}
+
+export function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+export 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/lib/src/host/iframe-proxy.ts b/lib/src/host/iframe-proxy.ts
new file mode 100644
index 00000000..ec69bd7f
--- /dev/null
+++ b/lib/src/host/iframe-proxy.ts
@@ -0,0 +1,287 @@
+/**
+ * Host-agnostic 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.
+ *
+ * This is the shared Node server, consumed by both hosts that can run one — the
+ * VS Code extension host (`vscode-ext/src/iframe-proxy-host.ts`) and the Tauri
+ * sidecar (bundled in via `standalone/scripts/build-sidecar-proxy.mjs`). Only
+ * the policy/rewriting logic lives in `./iframe-proxy-rewrite` (pure, tested);
+ * this file is the `http`/`net` plumbing. The logger is injected so neither host
+ * has to depend on the other's logging.
+ *
+ * Sibling to the agent-browser stream relay: same loopback-only bind and
+ * per-surface isolation, but this one speaks HTTP (parses and rewrites
+ * responses) and passes WebSocket upgrades through (dev-server HMR,
+ * openvscode-server).
+ *
+ * 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.
+ *     A server bound to exactly one upstream is inherently not an open forwarder.
+ *   - 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 type { IframeProxyResult } from '../lib/platform/iframe-proxy-types';
+import {
+  STRIP_RESPONSE_HEADERS,
+  errorPageHtml,
+  frameRefusedPage,
+  instrumentHtml,
+  isBlockedAddress,
+  isLoopbackHost,
+  refusesFraming,
+  unreachablePage,
+  type ErrorPage,
+} from './iframe-proxy-rewrite';
+
+// 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;
+
+/** Host-supplied logger; defaults to a no-op so the module is usable bare. */
+export type ProxyLogger = (message: string) => void;
+let log: ProxyLogger = () => {};
+
+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,
+  opts?: { log?: ProxyLogger },
+): Promise<IframeProxyResult> {
+  if (opts?.log) log = opts.log;
+
+  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(`[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(`[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/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> {
+  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);
+  });
+  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 {
+  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;
+}
+
+// --- 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());
+}
+
+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(`[iframe-proxy] swept grant for ${grant.upstream.href}`);
+  }
+}
+
+function serveErrorPage(res: http.ServerResponse, page: ErrorPage): void {
+  const html = instrumentHtml(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);
+}
diff --git a/lib/src/lib/platform/iframe-proxy-types.ts b/lib/src/lib/platform/iframe-proxy-types.ts
new file mode 100644
index 00000000..cee410e4
--- /dev/null
+++ b/lib/src/lib/platform/iframe-proxy-types.ts
@@ -0,0 +1,19 @@
+/**
+ * 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.
+ *
+ * Kept in its own dependency-free file so the Node proxy in `lib/src/host/`
+ * can import it without dragging the browser-typed `platform/types` graph into
+ * a Node tsconfig (and vice-versa).
+ */
+export type IframeProxyResult =
+  | { ok: true; url: string }
+  | { ok: false; reason: 'frame-refused' | 'unreachable' | 'scheme'; detail?: string };
diff --git a/lib/src/lib/platform/types.ts b/lib/src/lib/platform/types.ts
index adb5af4a..21a74232 100644
--- a/lib/src/lib/platform/types.ts
+++ b/lib/src/lib/platform/types.ts
@@ -1,5 +1,8 @@
 import type { AlertState } from '../alert-manager';
 import type { VSCodeWorkbenchCommand } from '../vscode-keybindings';
+// Defined in its own dependency-free file so the Node proxy in lib/src/host can
+// share it without pulling this browser-typed module into a Node tsconfig.
+import type { IframeProxyResult } from './iframe-proxy-types';
 
 export interface PtyInfo {
   id: string;
@@ -71,21 +74,7 @@ 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 type { IframeProxyResult };
 
 export interface PlatformAdapter {
   // Lifecycle
diff --git a/lib/tsconfig.app.json b/lib/tsconfig.app.json
index d0aceb3a..2c282eef 100644
--- a/lib/tsconfig.app.json
+++ b/lib/tsconfig.app.json
@@ -21,5 +21,7 @@
     }
   },
   "include": ["src"],
-  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx"]
+  // The pure rewrite helpers typecheck here (DOM provides URL); the Node proxy
+  // server is esbuild-only (bundled per host), like the rest of our host code.
+  "exclude": ["src/**/*.test.ts", "src/**/*.test.tsx", "src/host/iframe-proxy.ts"]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a2a36892..e6b7ea74 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -155,6 +155,9 @@ importers:
       '@vitejs/plugin-react':
         specifier: ^6.0.2
         version: 6.0.2(vite@8.0.14(esbuild@0.28.0)(jiti@2.7.0))
+      esbuild:
+        specifier: ^0.28.0
+        version: 0.28.0
       jsdom:
         specifier: ^29.1.1
         version: 29.1.1
diff --git a/standalone/package.json b/standalone/package.json
index 0348e351..fe0890b7 100644
--- a/standalone/package.json
+++ b/standalone/package.json
@@ -6,9 +6,11 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "pnpm stage:dor-cli && tsc -b && vite build",
+    "build": "pnpm stage && tsc -b && vite build",
+    "stage": "pnpm stage:dor-cli && pnpm stage:sidecar-proxy",
     "stage:dor-cli": "pnpm --filter dor build && node scripts/stage-dor-cli.mjs",
-    "tauri": "pnpm stage:dor-cli && tauri",
+    "stage:sidecar-proxy": "node scripts/build-sidecar-proxy.mjs",
+    "tauri": "pnpm stage && tauri",
     "test": "vitest run"
   },
   "dependencies": {
@@ -31,6 +33,7 @@
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.2",
+    "esbuild": "^0.28.0",
     "jsdom": "^29.1.1",
     "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3",
diff --git a/standalone/scripts/build-sidecar-proxy.mjs b/standalone/scripts/build-sidecar-proxy.mjs
new file mode 100644
index 00000000..bbb33a03
--- /dev/null
+++ b/standalone/scripts/build-sidecar-proxy.mjs
@@ -0,0 +1,23 @@
+// Bundle the host-agnostic iframe proxy (lib/src/host/iframe-proxy.ts, shared
+// with the VS Code extension host) into a CommonJS file the Node sidecar can
+// require. Keeps the proxy as a single TypeScript source while the sidecar
+// itself stays plain CJS. See docs/specs/dor-iframe.md → "The Transparent Proxy".
+import { build } from 'esbuild';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const entry = path.resolve(here, '../../lib/src/host/iframe-proxy.ts');
+const outfile = path.resolve(here, '../sidecar/iframe-proxy.cjs');
+
+await build({
+  entryPoints: [entry],
+  outfile,
+  bundle: true,
+  platform: 'node', // node builtins (http/net) stay external automatically
+  format: 'cjs',
+  target: 'node22',
+  logLevel: 'warning',
+});
+
+console.log(`[sidecar] built ${path.relative(process.cwd(), outfile)}`);
diff --git a/standalone/sidecar/main.js b/standalone/sidecar/main.js
index 8fba3ba2..4ceca7b3 100644
--- a/standalone/sidecar/main.js
+++ b/standalone/sidecar/main.js
@@ -11,6 +11,9 @@ const nodePty = require('node-pty');
 const { create } = require('./pty-core');
 const clipboard = require('./clipboard-ops');
 const { createDorControlServer } = require('./dor-control-server');
+// Built from lib/src/host/iframe-proxy.ts (shared with the VS Code host) by
+// scripts/build-sidecar-proxy.mjs. See docs/specs/dor-iframe.md.
+const { createIframeProxyUrl } = require('./iframe-proxy.cjs');
 
 function send(event, data) {
   process.stdout.write(JSON.stringify({ event, data }) + '\n');
@@ -52,6 +55,12 @@ rl.on('line', (line) => {
       case 'pty:getShells':  mgr.getShells(data.requestId); break;
       case 'pty:gracefulKillAll': mgr.gracefulKillAll(data.timeout); break;
       case 'dor:controlResponse': dorControl?.respond(data); break;
+      case 'iframe:createProxyUrl':
+        // Log to stderr — stdout is the JSON-lines protocol channel.
+        respondAsync('iframe:proxyUrl', data.requestId, async () => ({
+          result: await createIframeProxyUrl(data.target, { log: (m) => console.error(m) }),
+        }));
+        break;
       case 'clipboard:readFiles':
         respondAsync('clipboard:files', data.requestId, async () => ({
           paths: await clipboard.readClipboardFilePaths(),
diff --git a/standalone/src-tauri/src/lib.rs b/standalone/src-tauri/src/lib.rs
index 813dadba..3bb71bf2 100644
--- a/standalone/src-tauri/src/lib.rs
+++ b/standalone/src-tauri/src/lib.rs
@@ -312,6 +312,23 @@ fn pty_get_scrollback(
         .and_then(|data| data.as_str().map(String::from)))
 }
 
+// Stands up the loopback iframe proxy in the sidecar and returns the
+// IframeProxyResult JSON the webview's IframePanel expects. The proxy server is
+// the shared lib/src/host/iframe-proxy.ts; this only bridges the request.
+#[tauri::command]
+fn iframe_create_proxy_url(
+    state: tauri::State<'_, SidecarState>,
+    target: String,
+) -> Result<JsonValue, String> {
+    let response = request_from_sidecar_timeout(
+        &state,
+        "iframe:createProxyUrl",
+        serde_json::json!({ "target": target }),
+        Duration::from_secs(5),
+    )?;
+    Ok(response.get("result").cloned().unwrap_or(JsonValue::Null))
+}
+
 #[tauri::command]
 fn read_clipboard_file_paths(
     state: tauri::State<'_, SidecarState>,
@@ -786,6 +803,7 @@ pub fn run() {
             pty_get_cwd,
             pty_get_open_ports,
             pty_get_scrollback,
+            iframe_create_proxy_url,
             pty_request_init,
             dor_control_response,
             kill_sidecar_now,
diff --git a/standalone/src-tauri/tauri.conf.json b/standalone/src-tauri/tauri.conf.json
index cb13f1b1..593b7c8b 100644
--- a/standalone/src-tauri/tauri.conf.json
+++ b/standalone/src-tauri/tauri.conf.json
@@ -23,7 +23,7 @@
       }
     ],
     "security": {
-      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src ipc: http://ipc.localhost"
+      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src ipc: http://ipc.localhost; frame-src http://127.0.0.1:* http://localhost:*"
     }
   },
   "bundle": {
diff --git a/standalone/src/tauri-adapter.ts b/standalone/src/tauri-adapter.ts
index 47f35d6d..0bbe5926 100644
--- a/standalone/src/tauri-adapter.ts
+++ b/standalone/src/tauri-adapter.ts
@@ -1,7 +1,7 @@
 import { invoke as rawInvoke } from "@tauri-apps/api/core";
 import { listen } from "@tauri-apps/api/event";
 import { open } from "@tauri-apps/plugin-shell";
-import type { AlertStateDetail, OpenPort, PlatformAdapter, PtyInfo } from "dormouse-lib/lib/platform/types";
+import type { AlertStateDetail, IframeProxyResult, OpenPort, PlatformAdapter, PtyInfo } from "dormouse-lib/lib/platform/types";
 import { AlertManager, type SessionStatus } from "dormouse-lib/lib/alert-manager";
 import { normalizeExternalUri } from "dormouse-lib/lib/external-links";
 import {
@@ -214,6 +214,17 @@ export class TauriAdapter implements PlatformAdapter {
     } catch { return null; }
   }
 
+  async createIframeProxyUrl(targetUrl: string): Promise<IframeProxyResult> {
+    // The sidecar stands up the loopback proxy and serves the bytes (shared
+    // lib/src/host/iframe-proxy.ts). On failure, report unreachable so the panel
+    // shows a hint rather than a never-loading frame.
+    try {
+      return await rawInvoke<IframeProxyResult>("iframe_create_proxy_url", { target: targetUrl });
+    } catch (err) {
+      return { ok: false, reason: "unreachable", detail: err instanceof Error ? err.message : String(err) };
+    }
+  }
+
   openExternal(uri: string): void {
     const normalized = normalizeExternalUri(uri);
     if (!normalized) return;
diff --git a/vscode-ext/src/iframe-proxy-host.ts b/vscode-ext/src/iframe-proxy-host.ts
index 84661b2a..76114b4b 100644
--- a/vscode-ext/src/iframe-proxy-host.ts
+++ b/vscode-ext/src/iframe-proxy-host.ts
@@ -1,416 +1,15 @@
 /**
- * Extension-host transparent proxy for the iframe surface
- * (docs/specs/dor-iframe.md → "The Transparent Proxy").
+ * VS Code extension-host binding for the iframe 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.
+ * The proxy itself is host-agnostic and lives in `lib/src/host/iframe-proxy.ts`
+ * (shared with the Tauri sidecar — see docs/specs/dor-iframe.md → "The
+ * Transparent Proxy"). This file only injects the VS Code logger; the
+ * message-router calls `createIframeProxyUrl` exactly as before.
  */
-import * as http from 'http';
-import * as net from 'net';
-import { log } from './log';
+import { createIframeProxyUrl as createProxy } from '../../lib/src/host/iframe-proxy';
 import type { IframeProxyResult } from '../../lib/src/lib/platform/types';
+import { log } from './log';
 
-// 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/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> {
-  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);
-  });
-  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 {
-  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 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 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) -------
-
-// 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 = instrumentHtml(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>`;
+export function createIframeProxyUrl(targetUrl: string): Promise<IframeProxyResult> {
+  return createProxy(targetUrl, { log: (msg) => log.info(msg) });
 }

From 03c673ca3cbaf8a067a611edf9a31e74ce280126 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 00:30:51 -0700
Subject: [PATCH 02/10] standalone: alias `dor` in Vite so lib source resolves
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Standalone's Vite aliased `dormouse-lib` to lib source but not `dor`, and
leaned on tsconfig `paths` for it — which Vite doesn't apply to lib's own
files (governed by lib's paths-less tsconfig), and `dor` has no package
`exports` to fall back on. So any lib file importing `dor/*` (e.g. Wall.tsx
→ `dor/commands/shell-quote`) failed to resolve, and the standalone app's
full UI never booted in dev. Add the `dor` → ../dor/src alias and an
fs.allow entry, mirroring how `dormouse-lib` is already handled.

Verified: standalone `vite build` transforms all modules with no resolution
errors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 standalone/vite.config.ts | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/standalone/vite.config.ts b/standalone/vite.config.ts
index 5bda5eb1..d5c6c4c8 100644
--- a/standalone/vite.config.ts
+++ b/standalone/vite.config.ts
@@ -4,6 +4,7 @@ import tailwindcss from "@tailwindcss/vite";
 import path from "path";
 
 const libDir = path.resolve(__dirname, "../lib");
+const dorDir = path.resolve(__dirname, "../dor");
 
 // https://v2.tauri.app/start/frontend/vite/
 const host = process.env.TAURI_DEV_HOST;
@@ -14,6 +15,10 @@ export default defineConfig({
     dedupe: ["react", "react-dom"],
     alias: {
       "dormouse-lib": path.resolve(libDir, "src"),
+      // lib source imports the `dor` workspace package via the `dor/*` tsconfig
+      // path; Vite governs lib files by lib's (paths-less) tsconfig, and `dor`
+      // has no package exports, so resolve it explicitly the same way as lib.
+      dor: path.resolve(dorDir, "src"),
     },
   },
   // Tauri expects a fixed port; fail if that port is not available
@@ -23,8 +28,8 @@ export default defineConfig({
     strictPort: true,
     hmr: host ? { protocol: "ws", host, port: 1421 } : undefined,
     fs: {
-      // Allow serving files from the lib workspace package
-      allow: [libDir, "."],
+      // Allow serving files from the lib and dor workspace packages
+      allow: [libDir, dorDir, "."],
     },
   },
   // Tauri CLI reads this env var to know where the dev server is

From c6d0115f52a33d1423c4331e61ea9f533ebb0ec2 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 09:43:04 -0700
Subject: [PATCH 03/10] iframe: fix selection, command-mode focus, and reloads
 in the WebKit webview
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Shaking out the iframe surface in the standalone (WKWebView) host surfaced
several interaction bugs the Chromium webview hid:

- Click now selects the pane. WebKit doesn't fire the iframe element's
  `focus` for a cross-origin click, and dockview's `api.isActive` is true
  per-group (so the old guard skipped adoption in a split). The shim — which
  runs inside the frame — posts `pointerdown`; the panel adopts it as
  entering the pane (select + passthrough). Navigation is keyboard-only, so
  it never triggers this.

- Command-mode keys work after the leader. Exiting passthrough now blurs the
  frame *and* parks focus on the pane root (top document), since blurring a
  cross-origin frame doesn't reliably hand focus back on WebKit; without it
  the frame kept focus and arrow navigation never reached the Wall.

- The frame no longer reloads when its pane is (de)activated. dockview's
  default `onlyWhenVisible` renderer detaches/reattaches panel DOM, which
  reloads an <iframe>; iframe panels now use `renderer: 'always'`.

- Clicking no longer blanks the frame / traps focus. Adoption keys off the
  frame's own focus/pointer signals (rising-edge) rather than a window-`blur`
  heuristic that also fired on the transition away, and the focus handle
  never re-focuses an already-focused frame.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/components/Wall.tsx               |  5 ++
 lib/src/components/wall/IframePanel.tsx   | 58 +++++++++++++++--------
 lib/src/host/iframe-proxy-rewrite.test.ts |  9 ++--
 lib/src/host/iframe-proxy-rewrite.ts      | 21 ++++----
 4 files changed, 59 insertions(+), 34 deletions(-)

diff --git a/lib/src/components/Wall.tsx b/lib/src/components/Wall.tsx
index a3fa4fa2..503798a6 100644
--- a/lib/src/components/Wall.tsx
+++ b/lib/src/components/Wall.tsx
@@ -928,6 +928,10 @@ export function Wall({
         tabComponent: 'surface',
         title,
         params,
+        // Keep iframes mounted across (de)activation — dockview's default
+        // onlyWhenVisible renderer detaches/reattaches panel DOM, and moving an
+        // <iframe> in the DOM reloads it (docs/specs/dor-iframe.md).
+        renderer: component === 'iframe' ? 'always' : undefined,
         position: { referencePanel: referencePanel.id, direction: 'within' },
       });
       disposeSession(reference.id);
@@ -945,6 +949,7 @@ export function Wall({
       tabComponent: 'surface',
       title,
       params,
+      renderer: component === 'iframe' ? 'always' : undefined,
       position: { referencePanel: referencePanel.id, direction: dockDirection },
     });
     selectPane(newId);
diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 2632aac7..78878a77 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -84,39 +84,55 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
     return registerProxyOrigin(proxyOrigin);
   }, [proxyOrigin]);
 
+  // A cross-origin click reaches only the frame, so the Wall never sees the
+  // mousedown — and on WebKit the iframe element's own `focus` event doesn't
+  // fire for it either. The shim posts `pointerdown` from inside the frame;
+  // adopt it as entering the pane (select + passthrough), exactly like clicking
+  // any other pane. Only genuine clicks emit `pointerdown`, so command-mode
+  // arrow navigation never triggers it, and onClickPanel is idempotent for
+  // repeat clicks. (We can't gate on dockview's `api.isActive`: in a split each
+  // sole panel is always "active" within its own group.)
+  useEffect(() => {
+    if (!proxyOrigin) return;
+    const onMessage = (e: MessageEvent) => {
+      if (e.origin !== proxyOrigin) return;
+      if ((e.data as { __dormouse?: unknown } | null)?.__dormouse !== 'pointerdown') return;
+      actions.onClickPanel(api.id);
+    };
+    window.addEventListener('message', onMessage);
+    return () => window.removeEventListener('message', onMessage);
+  }, [api, proxyOrigin, actions]);
+
   // 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.
+  // frame like any other surface (spec → "#3"), and exitTerminalMode can hand
+  // focus back. Focusing the element moves keyboard focus into the frame.
   useEffect(() => {
     if (resolution.kind !== 'proxied' && resolution.kind !== 'raw') return;
     return registerSurfaceFocusHandle(api.id, {
-      focus: () => iframeRef.current?.focus(),
-      blur: () => iframeRef.current?.blur(),
+      // Skip if the frame already holds focus: re-focusing a cross-origin frame
+      // on WebKit can blank it (the frame is already focused after a click).
+      focus: () => {
+        if (document.activeElement !== iframeRef.current) iframeRef.current?.focus();
+      },
+      // Pull focus back into the top document so the Wall's window keydown
+      // listener receives command-mode keys after the leader exits passthrough —
+      // blurring a cross-origin frame doesn't reliably hand focus back on WebKit.
+      blur: () => {
+        iframeRef.current?.blur();
+        elRef.current?.focus();
+      },
     });
   }, [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
       ref={elRef}
-      className={`relative h-full w-full overflow-hidden bg-terminal-bg ${TERMINAL_BOTTOM_RADIUS_CLASS}`}
+      // tabIndex makes this focusable so the focus handle can park focus here
+      // (in the top document) when the frame blurs; outline-none hides the ring.
+      tabIndex={-1}
+      className={`relative h-full w-full overflow-hidden bg-terminal-bg outline-none ${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
diff --git a/lib/src/host/iframe-proxy-rewrite.test.ts b/lib/src/host/iframe-proxy-rewrite.test.ts
index 394f882f..ee722246 100644
--- a/lib/src/host/iframe-proxy-rewrite.test.ts
+++ b/lib/src/host/iframe-proxy-rewrite.test.ts
@@ -60,7 +60,7 @@ describe('refusesFraming', () => {
 describe('instrumentHtml', () => {
   it('injects the shim before </head>', () => {
     const out = instrumentHtml('<html><head><title>x</title></head><body>hi</body></html>');
-    expect(out).toContain("__dormouse:'leader'");
+    expect(out).toContain('__dormouse');
     expect(out).toMatch(/<\/script><\/head>/);
     expect(out).toContain('<title>x</title>');
   });
@@ -75,9 +75,10 @@ describe('instrumentHtml', () => {
     expect(out).not.toMatch(/http-equiv=["']?content-security-policy/i);
   });
 
-  it('carries the leader-only shim (no focus/blur channel)', () => {
-    expect(IFRAME_SHIM).toContain("__dormouse:'leader'");
-    expect(IFRAME_SHIM).not.toContain('focus');
+  it('forwards the leader chord and a pointerdown select signal', () => {
+    expect(IFRAME_SHIM).toContain('__dormouse');
+    expect(IFRAME_SHIM).toContain("'leader'");
+    expect(IFRAME_SHIM).toContain("'pointerdown'");
   });
 });
 
diff --git a/lib/src/host/iframe-proxy-rewrite.ts b/lib/src/host/iframe-proxy-rewrite.ts
index 7ed92a56..f0effccc 100644
--- a/lib/src/host/iframe-proxy-rewrite.ts
+++ b/lib/src/host/iframe-proxy-rewrite.ts
@@ -26,26 +26,29 @@ export const STRIP_RESPONSE_HEADERS = new Set([
 
 // 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).
+// (loopback CSP is dropped, so an inline script runs). It posts two things to
+// the Wall and nothing else (every other keystroke flows to the tool):
+//   - `leader`: the reserved dual-tap ⌘/⇧ chord (matching handle-dual-tap.ts),
+//     so the global chord keeps working with the frame focused (#1).
+//   - `pointerdown`: a click landed in the frame. A cross-origin click reaches
+//     only the frame, so the Wall can't see it; this lets it select the pane /
+//     enter passthrough (#3). It's genuine user input, so it can't loop with the
+//     parent's programmatic focus.
 export const IFRAME_SHIM = `(function(){
   var P=window.parent;
   if(!P||P===window)return;
+  function post(t){try{P.postMessage({__dormouse:t},'*');}catch(e){}}
   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();}
+    if(e.key==='Meta'){if(tap(cmd,e))post('leader');}
+    else if(e.key==='Shift'){if(tap(shift,e))post('leader');}
   },true);
+  addEventListener('pointerdown',function(){post('pointerdown');},true);
 })();`;
 
 // Drop any in-document CSP (loopback "relax CSP") and inject the shim before

From 35becb814be5d2937a7561b499b847fc1fa284cb Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 10:26:20 -0700
Subject: [PATCH 04/10] standalone: grant window is-focused +
 internal-toggle-maximize permissions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The AppBar calls getCurrentWindow().isFocused() and toggleMaximize(); in
Tauri v2 the JS toggleMaximize() invokes the `internal_toggle_maximize`
command, which `allow-toggle-maximize` doesn't cover. Both were denied at
runtime ("not allowed" — core:window:allow-is-focused /
allow-internal-toggle-maximize). Add the two permissions to the default
capability. Validated by cargo check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 standalone/src-tauri/capabilities/default.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/standalone/src-tauri/capabilities/default.json b/standalone/src-tauri/capabilities/default.json
index 92d765a4..89bddd8e 100644
--- a/standalone/src-tauri/capabilities/default.json
+++ b/standalone/src-tauri/capabilities/default.json
@@ -8,9 +8,11 @@
     "core:event:allow-unlisten",
     "core:window:allow-minimize",
     "core:window:allow-toggle-maximize",
+    "core:window:allow-internal-toggle-maximize",
     "core:window:allow-close",
     "core:window:allow-destroy",
     "core:window:allow-is-maximized",
+    "core:window:allow-is-focused",
     "core:window:allow-start-dragging",
     "shell:default",
     "updater:default"

From c399b495762e8b10b2eb38de340c3904e37b24c7 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 10:26:30 -0700
Subject: [PATCH 05/10] iframe-proxy: fail gracefully on a stalled or dead
 upstream
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The proxy had no upstream timeout, so a hung dev server left the frame
blank indefinitely with no feedback. Harden it:

- 30s idle timeout on the upstream socket → a served, actionable error
  page. Idle-based, so streaming/SSR responses are never cut off.
- Distinct pages: "isn't responding (may be optimizing) — try reloading"
  vs "couldn't connect — is the dev server running?".
- Guard against a double writeHead crash if the upstream errors after we've
  started streaming the response.
- Abort the in-flight upstream fetch when the frame navigates away/closes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/host/iframe-proxy-rewrite.test.ts |  7 ++++++
 lib/src/host/iframe-proxy-rewrite.ts      |  7 ++++++
 lib/src/host/iframe-proxy.ts              | 27 ++++++++++++++++++++++-
 3 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/lib/src/host/iframe-proxy-rewrite.test.ts b/lib/src/host/iframe-proxy-rewrite.test.ts
index ee722246..44e38250 100644
--- a/lib/src/host/iframe-proxy-rewrite.test.ts
+++ b/lib/src/host/iframe-proxy-rewrite.test.ts
@@ -8,6 +8,7 @@ import {
   IFRAME_SHIM,
   errorPageHtml,
   frameRefusedPage,
+  timedOutPage,
 } from './iframe-proxy-rewrite';
 
 describe('hasRestrictiveFrameAncestors', () => {
@@ -115,4 +116,10 @@ describe('errorPageHtml', () => {
     expect(html).toContain('dor ab open');
     expect(html).not.toContain('a"b'); // escaped
   });
+
+  it('renders a timed-out page that suggests reloading', () => {
+    const html = errorPageHtml(timedOutPage(new URL('http://localhost:5173/')));
+    expect(html).toContain('isn’t responding');
+    expect(html).toMatch(/reload/i);
+  });
 });
diff --git a/lib/src/host/iframe-proxy-rewrite.ts b/lib/src/host/iframe-proxy-rewrite.ts
index f0effccc..ff7fb99c 100644
--- a/lib/src/host/iframe-proxy-rewrite.ts
+++ b/lib/src/host/iframe-proxy-rewrite.ts
@@ -124,6 +124,13 @@ export function unreachablePage(upstream: URL, detail: string): ErrorPage {
   };
 }
 
+export function timedOutPage(upstream: URL): ErrorPage {
+  return {
+    title: `${upstream.host} isn’t responding`,
+    message: `Dormouse connected to ${upstream.host} but it didn’t respond in time — the dev server may be busy (e.g. optimizing dependencies). Try reloading.`,
+  };
+}
+
 export function escapeHtml(value: string): string {
   return value
     .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
diff --git a/lib/src/host/iframe-proxy.ts b/lib/src/host/iframe-proxy.ts
index ec69bd7f..78547959 100644
--- a/lib/src/host/iframe-proxy.ts
+++ b/lib/src/host/iframe-proxy.ts
@@ -42,6 +42,7 @@ import {
   isBlockedAddress,
   isLoopbackHost,
   refusesFraming,
+  timedOutPage,
   unreachablePage,
   type ErrorPage,
 } from './iframe-proxy-rewrite';
@@ -54,6 +55,10 @@ 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;
+// Idle timeout on the upstream socket (no bytes flowing). Generous so a slow or
+// streaming dev server isn't cut off, but bounded so a hung upstream becomes a
+// visible error page instead of an indefinitely blank frame.
+const UPSTREAM_IDLE_TIMEOUT_MS = 30_000;
 
 /** Host-supplied logger; defaults to a no-op so the module is usable bare. */
 export type ProxyLogger = (message: string) => void;
@@ -190,7 +195,27 @@ function handleRequest(grant: Grant, req: http.IncomingMessage, res: http.Server
       res.end(html);
     });
   });
-  upstreamReq.on('error', (err) => serveErrorPage(res, unreachablePage(grant.upstream, err.message)));
+  upstreamReq.on('error', (err) => {
+    // Once we've begun streaming the response we can't swap in an error page —
+    // just tear down. Otherwise serve an actionable page: distinguish "didn't
+    // respond in time" (dev server busy/optimizing) from "couldn't connect"
+    // (dev server down).
+    if (res.headersSent || res.writableEnded) {
+      res.destroy();
+      return;
+    }
+    const code = (err as { code?: string }).code;
+    serveErrorPage(res, code === 'ETIMEDOUT'
+      ? timedOutPage(grant.upstream)
+      : unreachablePage(grant.upstream, err.message));
+  });
+  // Fire on socket inactivity (not total duration), so active/streaming
+  // responses are never cut off; a stalled upstream surfaces as a timeout page.
+  upstreamReq.setTimeout(UPSTREAM_IDLE_TIMEOUT_MS, () => {
+    upstreamReq.destroy(Object.assign(new Error('upstream timed out'), { code: 'ETIMEDOUT' }));
+  });
+  // If the frame navigates away or is closed, stop fetching upstream.
+  res.on('close', () => { if (!res.writableEnded) upstreamReq.destroy(); });
   req.pipe(upstreamReq);
 }
 

From 14f74f03f9dc50cde4c10e2ace7c19149cdcb4bf Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 10:38:25 -0700
Subject: [PATCH 06/10] iframe-proxy: stream HTML instead of buffering the
 whole document

Inject the shim into the <head> as bytes arrive, then pipe the rest
untouched, rather than buffering the entire response before serving. Cuts
first-paint latency on large/streaming-SSR pages (e.g. a 200KB React Router
document) and bounds memory to the <head> region.

Subtleties handled: the insertion point (</head>, else <body>, else a cap)
can split across chunk boundaries, so we accumulate until it appears; the
head prefix is processed as latin1 (byte-preserving) so rewriting ASCII tags
and re-encoding can't corrupt a multibyte char split mid-byte; after
injection we hand the remainder to a raw pipe (backpressure + end for free),
with a `handled` flag so the manual end path and the pipe don't both close
the response. The response is now chunked (instrumentation changes length).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/host/iframe-proxy.ts | 73 ++++++++++++++++++++++--------------
 1 file changed, 45 insertions(+), 28 deletions(-)

diff --git a/lib/src/host/iframe-proxy.ts b/lib/src/host/iframe-proxy.ts
index 78547959..83938e23 100644
--- a/lib/src/host/iframe-proxy.ts
+++ b/lib/src/host/iframe-proxy.ts
@@ -54,7 +54,9 @@ 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;
+// We only buffer the <head> region (to find the shim insertion point); if no
+// </head>/<body> shows up within this many bytes, inject at the front and pipe.
+const HEAD_STREAM_CAP = 512 * 1024;
 // Idle timeout on the upstream socket (no bytes flowing). Generous so a slow or
 // streaming dev server isn't cut off, but bounded so a hung upstream becomes a
 // visible error page instead of an indefinitely blank frame.
@@ -180,20 +182,14 @@ function handleRequest(grant: Grant, req: http.IncomingMessage, res: http.Server
       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);
-    });
+    // A remote that forbids embedding is never force-framed — the headers tell
+    // us, so we can divert to an actionable page without reading the body.
+    if (!grant.isLoopback && refusesFraming(upstreamRes.headers)) {
+      upstreamRes.destroy();
+      serveErrorPage(res, frameRefusedPage(grant.upstream));
+      return;
+    }
+    streamHtml(grant, upstreamRes, res);
   });
   upstreamReq.on('error', (err) => {
     // Once we've begun streaming the response we can't swap in an error page —
@@ -227,20 +223,41 @@ function passThrough(grant: Grant, upstreamRes: http.IncomingMessage, res: http.
   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);
+// Inject the shim into the <head> while streaming, without buffering the whole
+// document: accumulate only until the insertion point (</head>, else <body>,
+// else the cap), instrument that prefix, then pipe the rest through untouched.
+// latin1 is byte-preserving, so searching/rewriting ASCII tags and re-encoding
+// can't corrupt multibyte bytes in <head> (e.g. an em-dash in <title>). The
+// response is chunked (no content-length) since instrumentation changes length.
+function streamHtml(grant: Grant, upstreamRes: http.IncomingMessage, res: http.ServerResponse): void {
+  const outHeaders = sanitizeResponseHeaders(grant, upstreamRes.headers);
+  outHeaders['content-type'] = 'text/html; charset=utf-8';
+  delete outHeaders['content-length'];
+  res.writeHead(upstreamRes.statusCode ?? 200, outHeaders);
+
+  let pending = Buffer.alloc(0);
+  let handled = false;
+
+  const onData = (chunk: Buffer) => {
+    pending = Buffer.concat([pending, chunk]);
+    const text = pending.toString('latin1');
+    if (pending.length <= HEAD_STREAM_CAP && !/<\/head>/i.test(text) && !/<body[^>]*>/i.test(text)) return;
+    // Found the insertion point (or hit the cap): instrument the buffered
+    // prefix, then hand the remainder to a raw pipe (backpressure + end).
+    handled = true;
+    upstreamRes.off('data', onData);
+    res.write(Buffer.from(instrumentHtml(text), 'latin1'));
+    pending = Buffer.alloc(0);
+    upstreamRes.pipe(res);
+  };
+
+  upstreamRes.on('data', onData);
+  upstreamRes.on('end', () => {
+    if (handled) return; // the pipe ends `res`
+    // Whole document arrived before any head marker — instrument and finish.
+    res.end(Buffer.from(instrumentHtml(pending.toString('latin1')), 'latin1'));
   });
-  const complete = () => done(Buffer.concat(chunks).toString('utf8'));
-  stream.on('end', complete);
-  stream.on('error', complete);
+  upstreamRes.on('error', () => { if (!res.writableEnded) res.destroy(); });
 }
 
 function sanitizeResponseHeaders(grant: Grant, headers: http.IncomingHttpHeaders): http.OutgoingHttpHeaders {

From d085bc50344a71d42bf6b07c8e99a6a3ca0fb25a Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 10:40:51 -0700
Subject: [PATCH 07/10] iframe-proxy: integration tests for the streaming proxy
 server

The Node proxy server was esbuild-only (no tsc/unit coverage); add an
end-to-end test that fronts a real loopback upstream with createIframeProxyUrl
and fetches through the proxy. Covers the parts most likely to rot:

- streaming shim injection when </head> and a multibyte char both split
  across chunk boundaries (the latin1 byte-preservation path),
- loopback instrumentation (XFO/CSP stripped, shim before </head>, content
  and chunked encoding preserved),
- non-HTML passthrough, Location rewrite onto the proxy origin,
- scheme + SSRF admission rejects, and the unreachable error page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/host/iframe-proxy.test.ts | 140 ++++++++++++++++++++++++++++++
 1 file changed, 140 insertions(+)
 create mode 100644 lib/src/host/iframe-proxy.test.ts

diff --git a/lib/src/host/iframe-proxy.test.ts b/lib/src/host/iframe-proxy.test.ts
new file mode 100644
index 00000000..c8381c60
--- /dev/null
+++ b/lib/src/host/iframe-proxy.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import * as http from 'node:http';
+import { createIframeProxyUrl } from './iframe-proxy';
+
+// Integration coverage for the Node proxy server (esbuild-only otherwise): we
+// stand up a real loopback upstream, front it with createIframeProxyUrl, and
+// fetch through the returned proxy URL — exercising the streaming shim
+// injection, header rewriting, and error paths end to end.
+
+const NO_LOG = { log: () => {} };
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+const upstreams: http.Server[] = [];
+afterEach(() => {
+  for (const s of upstreams.splice(0)) s.close();
+});
+
+function upstream(handler: http.RequestListener): Promise<number> {
+  const server = http.createServer(handler);
+  upstreams.push(server);
+  return new Promise((resolve) => server.listen(0, '127.0.0.1', () => {
+    const a = server.address();
+    resolve(typeof a === 'object' && a ? a.port : 0);
+  }));
+}
+
+interface Fetched { status: number; headers: http.IncomingHttpHeaders; body: string }
+function get(url: string): Promise<Fetched> {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      const chunks: Buffer[] = [];
+      res.on('data', (c: Buffer) => chunks.push(c));
+      res.on('end', () => resolve({ status: res.statusCode ?? 0, headers: res.headers, body: Buffer.concat(chunks).toString('utf8') }));
+    }).on('error', reject);
+  });
+}
+
+async function frame(target: string): Promise<string> {
+  const r = await createIframeProxyUrl(target, NO_LOG);
+  if (!r.ok) throw new Error(`expected ok, got ${JSON.stringify(r)}`);
+  return r.url;
+}
+
+describe('createIframeProxyUrl — admission', () => {
+  it('rejects non-http schemes (https deferred)', async () => {
+    const r = await createIframeProxyUrl('https://example.com/', NO_LOG);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe('scheme');
+  });
+
+  it('refuses link-local / cloud-metadata addresses (SSRF)', async () => {
+    const r = await createIframeProxyUrl('http://169.254.169.254/latest/meta-data/', NO_LOG);
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toBe('scheme');
+  });
+
+  it('preserves the target path + query in the framed URL', async () => {
+    const port = await upstream((_q, s) => { s.writeHead(200, { 'content-type': 'text/html' }); s.end('<html><head></head><body>x</body></html>'); });
+    const url = await frame(`http://127.0.0.1:${port}/app/page?q=1`);
+    const u = new URL(url);
+    expect(u.hostname).toBe('127.0.0.1');
+    expect(u.pathname).toBe('/app/page');
+    expect(u.search).toBe('?q=1');
+  });
+});
+
+describe('iframe proxy — serving', () => {
+  it('instruments loopback HTML: strips XFO + CSP, injects the shim, keeps content', async () => {
+    const port = await upstream((_q, s) => {
+      s.writeHead(200, {
+        'content-type': 'text/html',
+        'x-frame-options': 'DENY',
+        'content-security-policy': "frame-ancestors 'none'",
+      });
+      s.end(`<html><head><meta http-equiv="Content-Security-Policy" content="default-src 'none'"><title>t</title></head><body>hello</body></html>`);
+    });
+    const res = await get(await frame(`http://127.0.0.1:${port}/`));
+
+    expect(res.status).toBe(200);
+    expect(res.headers['x-frame-options']).toBeUndefined();
+    expect(res.headers['content-security-policy']).toBeUndefined();
+    expect(res.body).not.toMatch(/http-equiv=["']?content-security-policy/i);
+    expect(res.body).toContain('__dormouse');
+    expect(res.body).toMatch(/<\/script><\/head>/);
+    expect(res.body).toContain('<body>hello</body>');
+  });
+
+  it('streams: injects the shim when </head> and a multibyte char split across chunks', async () => {
+    const html = Buffer.from('<html><head><title>A—B</title></head><body>hello—world</body></html>', 'utf8');
+    const headIdx = html.indexOf('</head>') + 3;                          // inside the tag
+    const emIdx = html.indexOf(Buffer.from([0xe2, 0x80, 0x94])) + 1;      // inside the em-dash bytes
+    const [a, b] = [emIdx, headIdx].sort((x, y) => x - y);
+    const slices = [html.subarray(0, a), html.subarray(a, b), html.subarray(b)];
+    const port = await upstream(async (_q, s) => {
+      s.writeHead(200, { 'content-type': 'text/html' });
+      for (const slice of slices) { s.write(slice); await delay(2); }
+      s.end();
+    });
+    const res = await get(await frame(`http://127.0.0.1:${port}/`));
+
+    expect(res.body).toContain('__dormouse');
+    expect(res.body).toMatch(/<\/script><\/head>/);
+    expect(res.body).toContain('A—B');          // multibyte split mid-byte, intact
+    expect(res.body).toContain('hello—world');  // body (after the streamed head) intact
+    // Instrumentation changes length → chunked, not a (now-wrong) content-length.
+    expect(res.headers['content-length']).toBeUndefined();
+    expect(res.headers['transfer-encoding']).toBe('chunked');
+  });
+
+  it('passes non-HTML through untouched (no shim), still stripping framing headers', async () => {
+    const port = await upstream((_q, s) => {
+      s.writeHead(200, { 'content-type': 'application/javascript', 'x-frame-options': 'SAMEORIGIN' });
+      s.end('export const x = 1;');
+    });
+    const res = await get(await frame(`http://127.0.0.1:${port}/dep.js`));
+
+    expect(res.body).toBe('export const x = 1;');
+    expect(res.body).not.toContain('__dormouse');
+    expect(res.headers['x-frame-options']).toBeUndefined();
+  });
+
+  it('rewrites an upstream-origin Location redirect onto the proxy origin', async () => {
+    let upstreamOrigin = '';
+    const port = await upstream((_q, s) => { s.writeHead(302, { location: `${upstreamOrigin}/next` }); s.end(); });
+    upstreamOrigin = `http://127.0.0.1:${port}`;
+    const url = await frame(`http://127.0.0.1:${port}/`);
+    const res = await get(url); // http.get does not follow redirects
+
+    expect(res.status).toBe(302);
+    expect(res.headers.location).toBe(`${new URL(url).origin}/next`);
+  });
+
+  it('serves an actionable error page (frameable) when the upstream is unreachable', async () => {
+    const res = await get(await frame('http://127.0.0.1:1/')); // port 1: connection refused
+
+    expect(res.status).toBe(200);
+    expect(res.body).toMatch(/dev server running|couldn’t reach/i);
+    expect(res.headers['x-frame-options']).toBeUndefined();
+  });
+});

From 4f0f4786ec7d4a93dfe339ebafa2ce02d2a28212 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 10:48:06 -0700
Subject: [PATCH 08/10] iframe-proxy-registry: use a Set instead of a refcount
 Map
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Each proxied surface gets its own ephemeral loopback origin (a unique
OS-assigned port per grant), so an origin is only ever held by one live
surface — the reference count could never exceed 1. Drop the
Map<string,number> (and its `?? 0`/`?? 1` asymmetry) for a plain Set. API
and behavior unchanged.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 lib/src/lib/iframe-proxy-registry.ts | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/lib/src/lib/iframe-proxy-registry.ts b/lib/src/lib/iframe-proxy-registry.ts
index 321717b9..8329cd9f 100644
--- a/lib/src/lib/iframe-proxy-registry.ts
+++ b/lib/src/lib/iframe-proxy-registry.ts
@@ -4,26 +4,24 @@
  * 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.
+ * forwarded leader chord, so only a frame Dormouse itself served can drive it.
  *
- * 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).
+ * A plain Set suffices: each proxied surface gets its own ephemeral loopback
+ * origin (a unique OS-assigned port per grant), so an origin is only ever held
+ * by one live surface at a time — there's nothing to reference-count.
  */
-const proxyOriginCounts = new Map<string, number>();
+const proxyOrigins = new Set<string>();
 
 export function registerProxyOrigin(origin: string): () => void {
-  proxyOriginCounts.set(origin, (proxyOriginCounts.get(origin) ?? 0) + 1);
+  proxyOrigins.add(origin);
   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);
+    proxyOrigins.delete(origin);
   };
 }
 
 export function isProxyOrigin(origin: string): boolean {
-  return proxyOriginCounts.has(origin);
+  return proxyOrigins.has(origin);
 }

From 8886025d78053eb5a449eb9b7af3914870f8f93a Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 11:09:34 -0700
Subject: [PATCH 09/10] iframe: preserve raw fallback focus adoption

---
 lib/src/components/wall/IframePanel.test.tsx | 99 ++++++++++++++++++++
 lib/src/components/wall/IframePanel.tsx      | 15 +++
 2 files changed, 114 insertions(+)
 create mode 100644 lib/src/components/wall/IframePanel.test.tsx

diff --git a/lib/src/components/wall/IframePanel.test.tsx b/lib/src/components/wall/IframePanel.test.tsx
new file mode 100644
index 00000000..2895f225
--- /dev/null
+++ b/lib/src/components/wall/IframePanel.test.tsx
@@ -0,0 +1,99 @@
+/**
+ * @vitest-environment jsdom
+ */
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import type { IDockviewPanelProps } from 'dockview-react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { FakePtyAdapter, setPlatform } from '../../lib/platform';
+import { IframePanel } from './IframePanel';
+import { WallActionsContext, type WallActions } from './wall-context';
+
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+
+function stubActions(overrides: Partial<WallActions> = {}): WallActions {
+  return {
+    onKill: vi.fn(),
+    onMinimize: vi.fn(),
+    onAlertButton: vi.fn(() => 'noop'),
+    onToggleTodo: vi.fn(),
+    onSplitH: vi.fn(),
+    onSplitV: vi.fn(),
+    onZoom: vi.fn(),
+    onClickPanel: vi.fn(),
+    onFocusPane: vi.fn(),
+    onStartRename: vi.fn(),
+    onFinishRename: vi.fn(() => ({ accepted: true })),
+    onCancelRename: vi.fn(),
+    ...overrides,
+  };
+}
+
+function panelProps(id: string): IDockviewPanelProps<{ url: string }> {
+  return {
+    api: { id, title: 'Raw iframe' },
+    params: { url: 'http://example.test/app' },
+  } as unknown as IDockviewPanelProps<{ url: string }>;
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  setPlatform(new FakePtyAdapter());
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.restoreAllMocks();
+});
+
+async function renderPanel(actions: WallActions): Promise<HTMLIFrameElement> {
+  await act(async () => {
+    root.render(
+      <WallActionsContext.Provider value={actions}>
+        <IframePanel {...panelProps('iframe-raw')} />
+      </WallActionsContext.Provider>,
+    );
+  });
+
+  const iframe = container.querySelector('iframe');
+  if (!iframe) throw new Error('missing iframe');
+  return iframe;
+}
+
+describe('IframePanel', () => {
+  it('adopts clicks into the raw iframe fallback via window blur focus', async () => {
+    const onClickPanel = vi.fn();
+    const actions = stubActions({ onClickPanel });
+    const iframe = await renderPanel(actions);
+
+    vi.spyOn(document, 'hasFocus').mockReturnValue(true);
+    vi.spyOn(document, 'activeElement', 'get').mockReturnValue(iframe);
+
+    act(() => {
+      window.dispatchEvent(new Event('blur'));
+    });
+
+    expect(onClickPanel).toHaveBeenCalledWith('iframe-raw');
+  });
+
+  it('does not adopt a raw iframe blur when the app itself lost focus', async () => {
+    const onClickPanel = vi.fn();
+    const actions = stubActions({ onClickPanel });
+    const iframe = await renderPanel(actions);
+
+    vi.spyOn(document, 'hasFocus').mockReturnValue(false);
+    vi.spyOn(document, 'activeElement', 'get').mockReturnValue(iframe);
+
+    act(() => {
+      window.dispatchEvent(new Event('blur'));
+    });
+
+    expect(onClickPanel).not.toHaveBeenCalled();
+  });
+});
diff --git a/lib/src/components/wall/IframePanel.tsx b/lib/src/components/wall/IframePanel.tsx
index 78878a77..01a29a9e 100644
--- a/lib/src/components/wall/IframePanel.tsx
+++ b/lib/src/components/wall/IframePanel.tsx
@@ -103,6 +103,21 @@ export function IframePanel({ api, params }: IDockviewPanelProps<IframePanelPara
     return () => window.removeEventListener('message', onMessage);
   }, [api, proxyOrigin, actions]);
 
+  // Raw fallback frames have no injected shim, but focusing a cross-origin
+  // iframe still blurs the parent window while the document itself remains
+  // focused. Adopt that as entering the pane so hosts without a proxy keep the
+  // same click/focus behavior, albeit without the proxied leader side-channel.
+  useEffect(() => {
+    if (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]);
+
   // Register a focus handle so onClickPanel → enterTerminalMode can focus the
   // frame like any other surface (spec → "#3"), and exitTerminalMode can hand
   // focus back. Focusing the element moves keyboard focus into the frame.

From 854cec5d349c36fdad7869ecf29c18e784685218 Mon Sep 17 00:00:00 2001
From: Ned Twigg <ned.twigg@diffplug.com>
Date: Wed, 17 Jun 2026 11:11:05 -0700
Subject: [PATCH 10/10] docs: update iframe proxy spec

---
 docs/specs/dor-iframe.md | 81 ++++++++++++++++++++++++----------------
 1 file changed, 48 insertions(+), 33 deletions(-)

diff --git a/docs/specs/dor-iframe.md b/docs/specs/dor-iframe.md
index 3bfe0b1b..33a19036 100644
--- a/docs/specs/dor-iframe.md
+++ b/docs/specs/dor-iframe.md
@@ -17,12 +17,13 @@ Dormouse-served content, which is the one capability the raw iframe lacked — a
 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`.
+> Status: **works for loopback dev servers** in hosts that can run the shared
+> Node proxy (VS Code extension host and standalone/Tauri sidecar). 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
 
@@ -42,9 +43,9 @@ isn't proxyable (e.g. an `https://` URL) it shows an actionable message instead.
 
 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:
+(`lib/src/host/iframe-proxy.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 leader chord keeps
    working inside the frame (the technique VS Code uses for its own webviews).
@@ -85,6 +86,10 @@ forwarder. The difference: this proxy speaks **HTTP** (it parses and rewrites
 responses) and passes through **WebSocket upgrades** (dev-server HMR,
 openvscode-server's connection).
 
+Source of truth: `lib/src/host/iframe-proxy.ts` owns the shared HTTP/WebSocket
+server, while `lib/src/host/iframe-proxy-rewrite.ts` owns the dependency-free
+policy, HTML instrumentation, framing checks, and served error pages.
+
 - **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
@@ -109,6 +114,9 @@ openvscode-server's connection).
   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.
+  HTML injection streams: the proxy buffers only until `</head>`, `<body>`, or a
+  bounded prefix cap, instruments that prefix, then pipes the rest of the
+  upstream response through without waiting for the full document.
 - **WebSocket passthrough.** Upgrades are forwarded as a raw byte pipe once the
   upgrade head is rewritten (`Host`/`Origin` → upstream), exactly like the stream
   relay.
@@ -116,23 +124,28 @@ openvscode-server's connection).
   `allow-top-navigation`, so a tool's `if (top !== self) top.location = …` cannot
   navigate the Wall away.
 
-### The keyboard side-channel (resolves #1)
+### The iframe shim message channel (resolves #1 and proxied click adoption)
 
 A fixed, Dormouse-owned script — like agent-browser's `EDIT_SCRIPTS`, never
-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.
+user-supplied, so it is not an eval vector — injected inline before `</head>`.
+It posts only Dormouse-owned control messages to the parent:
+
+- `leader`: the reserved leader chord (dual-tap ⌘ / ⇧, the same detection as
+  `handle-dual-tap.ts`).
+- `pointerdown`: genuine user pointerdown inside the cross-origin frame, so the
+  panel can adopt the click as pane selection + passthrough entry.
+
+Every other keystroke and pointer event 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 and a click-adoption signal.
 
 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.
-
-> Deviation from the original sketch: the shim forwards **only** the leader, not
-> `focus`/`blur`. The focus model below needs no message channel.
+would (`exitTerminalMode`) — no synthesized `KeyboardEvent` round-trip. The
+iframe panel separately listens for the same validated proxy origin and treats a
+`pointerdown` message as `onClickPanel(api.id)`.
 
 ### Accurate focus model (resolves #2 and #3)
 
@@ -143,11 +156,12 @@ would (`exitTerminalMode`) — no synthesized `KeyboardEvent` round-trip.
   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.
+  other surface. Because clicking *into* a cross-origin frame doesn't bubble a
+  `mousedown` to the pane, proxied frames adopt the shim's validated
+  `pointerdown` message as entering the pane. The raw fallback has no shim, so it
+  preserves the older focus heuristic: window `blur` while our iframe is
+  `document.activeElement` and the app still has focus. Both paths keep
+  mode/selection consistent when the frame owns focus.
 
 ### Real error signals (resolves #4)
 
@@ -186,13 +200,16 @@ createIframeProxyUrl?(targetUrl: string): Promise<
 >;
 ```
 
-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>`.
+VS Code implements it in the extension host (`vscode-ext/src/iframe-proxy-host.ts`),
+routed via `message-router.ts` / `message-types.ts` and the `vscode-adapter.ts`
+request/response pair. Standalone implements the same adapter method through
+`standalone/src/tauri-adapter.ts` → `iframe_create_proxy_url` in
+`standalone/src-tauri/src/lib.rs` → the sidecar's `iframe:createProxyUrl` command,
+which loads the bundled shared proxy. **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. 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:
@@ -233,8 +250,6 @@ user's own `dor iframe <url>`.
   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.)