Correct stale spec pointers and comments in the iframe panel, browser URL helpers, and lint scripts

lib/src/components/motion-test-utils.ts

@@ -2,9 +2,10 @@ import { afterEach, beforeEach } from 'vitest';
 
 /**
  * Install a fake clock, `requestAnimationFrame`, and `matchMedia` around every
- * test in the calling file: `performance.now` reads the clock, frames run only
+ * test in the calling scope: `performance.now` reads the clock, frames run only
  * when a test advances it, and reduced motion is off until a test turns it on.
- * Call once at the top level of a test file.
+ * Call once at the top level of a test file, or inside a `describe` to cover
+ * only that suite.
  */
 export function installFakeFrames() {
   let clock = 0;

lib/src/components/wall/IframePanel.tsx

@@ -26,8 +26,8 @@ import { isRealBlur } from '../../lib/window-focus';
 
 // Sandbox every framed page, proxied or raw, so a tool's
 // `if (top !== self) top.location = …` framebust cannot navigate the Wall away —
-// allow-top-navigation is omitted on purpose (docs/specs/dor-browser.md →
-// "Iframe Renderer"). Everything else a local dev tool needs is granted;
+// allow-top-navigation is omitted on purpose (docs/specs/security-local.md →
+// "Browser panes"). Everything else a local dev tool needs is granted;
 // allow-same-origin is safe because the frame's origin (the loopback proxy, or
 // the upstream itself on a host with no proxy) is never same-origin with the
 // host webview — except the website playground's first-party viewer pages,

lib/src/components/wall/browser-url.ts

@@ -1,11 +1,13 @@
 /**
- * Small URL helpers for the agent-browser surface header
+ * Small URL helpers for the browser surface
  * (see docs/specs/dor-browser.md → "Browser Chrome").
  *
  * The header shows a tab's URL as host+path (Chrome-style, the scheme and any
  * query/hash dropped) and, when that URL is loopback, correlates its port to a
- * Dormouse terminal pane. Both jobs are pure string parsing kept out of the
- * components so they can be unit-tested directly.
+ * Dormouse terminal pane. `browserSurfaceUrl` and `iframeRefusal` guard what a
+ * browser pane may frame; `iframeRefusal` alone reads the platform, to learn
+ * whether this host has the iframe proxy. The rest is pure string parsing kept
+ * out of the components so it can be unit-tested directly.
  */
 import type { AgentBrowserTab } from '../../lib/agent-browser-tab';
 import { isLoopbackHostname } from '../../lib/ip-literal';

lib/src/lib/vscode-message-token.ts

@@ -15,8 +15,9 @@
  * cannot read the parent's globals across origins, so it cannot produce the
  * token, and the adapter drops anything that doesn't carry it.
  *
- * The spec section above covers why a token rather than an `event.source` /
- * `event.origin` check, and why this is not the CSP nonce.
+ * `docs/specs/vscode.rationale.md` → "Webview message authentication" covers
+ * why a token rather than an `event.source` / `event.origin` check, and why
+ * this is not the CSP nonce.
  */
 
 /** Global the host injects the per-boot token into. */

scripts/loopback-lint-selftest.mjs

@@ -83,8 +83,8 @@ for (const [name, source] of FIXTURES) {
   );
 }
 
-// `.mts` and `.cts` are TypeScript too, and the spec, the audit prompt and this
-// lint's own header all say it scans every tracked JavaScript and TypeScript
+// `.mts` and `.cts` are TypeScript too, and the audit prompt and this lint's
+// own header both say it scans every tracked JavaScript and TypeScript
 // file. Without this case that claim rests on an extension list nothing reads.
 selftest.withAppended(
   EXT_TARGET,
@@ -144,8 +144,8 @@ selftest.finish(
   'Each fixture adds one unguarded loopback listener. A case that stays green means\n'
   + 'LISTEN_RE in scripts/loopback-lint.mjs does not match that bind form — and a form\n'
   + 'reported with no fixture is one nothing has ever matched. Either way the\n'
-  + '"A new non-test listener without a guard reference fails the build"\n'
-  + 'clause in docs/specs/security-local.md -> "Loopback Listeners" is not true of it.\n'
+  + 'guard-reference half of S141 in docs/specs/security-local.md ->\n'
+  + '"Loopback Listeners" is not enforced for it.\n'
   + 'A green extension case means SOURCE_EXT does not read that file type, so the\n'
   + '"all tracked JavaScript and TypeScript" scope is narrower than it claims.\n'
   + 'The test case must stay green and appear under the test heading. A green\n'

scripts/security-audit-local.sh

@@ -328,7 +328,7 @@ if [ $# -gt 0 ]; then
 fi
 
 # Every domain, sequentially rather than fanned out. CI parallelises because it is
-# paying wall-clock for a nightly; locally, serial output is readable and a
+# paying wall-clock for a nightly; locally, serial output is readable and
 # each domain's failure is recorded while the remaining domains still run.
 status=0
 run_github_state || status=1

standalone/src/window-recovery.ts

@@ -14,7 +14,7 @@ import { readPersistedWindow, windowPaneIds, type PersistedWindow } from "dormou
 /**
  * A single synchronous key/value slot the host persists natively, holding the
  * stored `PersistedWindow` as JSON (`docs/specs/transport.md` → "Persisted
- * session"). `localStorage` (browser-dev sidecar) and the Rust-backed
+ * session types"). `localStorage` (browser-dev sidecar) and the Rust-backed
  * `TauriSessionStore` both satisfy it (`docs/specs/standalone.md` §Persistence).
  */
 export interface SessionKeyValueStore {