fix(webview): let a proxied single-page app route on its own path, and recover a frame that reloads

[shenlvkang-collab]

Summary

Stacked on #401 (its commit is the first in this branch; only the second commit is new). It fixes a bug that exists independently of #401: any single-page app opened as a web tab.

Symptom. A dashboard served through a web tab paints its HTML and CSS, then replaces them with its own "page not found" the moment its script runs. Reproduced with a minimal history-routed page: through the proxy, location.pathname is /webview/<cap>/, which no React Router / Vue Router / Vite dev-server app has a route for.

Fix, two halves.

1. Route masking in the runtime shim. Before any page script runs, the shim rewrites the history entry to the path the page would see on its own origin (history.replaceState, which browsers allow inside the sandboxed frame — verified in Chromium). Only what the page reads changes: <base> still resolves relative URLs inside the prefix and every root-absolute sink is rewritten back into it. Because the masked document URL means the Referer-keyed 404 rescue can no longer help a request the shim misses, the remaining URL-taking entry points (Worker, SharedWorker, navigator.sendBeacon, window.open) are now covered by the shim as well.
2. Lost-frame recovery. A navigation the page starts itself afterwards — location.reload() (a dev server's full-reload HMR), a root-absolute location.href — lands on Codeman's root with no capability anywhere (no prefix, no cookie in an opaque-origin frame, a Referer naming the masked page). It is recognised by shape only (Sec-Fetch-Dest: iframe, Accept: text/html, a path Codeman does not serve) and answered with a static page whose only script posts {type:'codeman:webview-lost', path} to the parent. The owning tab matches the frame by event.source (never by the payload), sanitises the path to a same-origin one, and remounts the frame inside the prefix at that path, bounded to 5 recoveries per minute per frame. The unauthenticated form is answered in the auth middleware before the credential checks, so a dev server that reloads on every save cannot rate-limit its own user out of Codeman; the authenticated form (Basic auth, trusted mode) is answered by the 404 handler. The page carries default-src 'none' plus the hash of its one script, and referrer: no-referrer.

This also turns the documented "root-absolute location navigation escapes the prefix" limit into a recovered case.

Verified end to end (Playwright, sandboxed frame, a history-routed test page): boots on / and its fetch('/api/data') succeeds; a reload inside the frame comes back routed on the path it had pushed; location.href = '/about' comes back on /about; a deep link opens on its path; no 4xx on the wire.

Docs: docs/web-tabs.md (layers 5–6, Known limits). Changeset: patch.

Test plan

• test/webview-proxy.test.ts: masking (path/search/hash, landing page → /, non-prefixed document untouched), rewrites still applied after masking, window.open patch; isLostWebviewFrameNavigation shape checks; the recovery page's script hash matches its CSP.
• test/webview-auth-exemption.test.ts: a lost frame gets the recovery page (200, HTML, CSP); never for /, a registered route, or a plain navigation; 20 recoveries do not trip the auth failure limit.
• test/webview-loopback-links.test.ts: remount at the lost path inside the prefix, bare reload → landing page, foreign event.source / malformed payload ignored, //host/x cannot jump the frame, loop bounded.
• Full test/webview-* set green; tsc --noEmit, eslint, prettier.

🤖 Generated with Claude Code