fix(observation): preserve snapshot unit normalization after document extraction

Release/0.2.1

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
         run: cargo test --workspace --locked
 
   windows-daemon:
-    name: Windows daemon and update regression tests
+    name: Windows daemon, installer and cancellation regression tests
     runs-on: windows-latest
 
     steps:
@@ -55,8 +55,16 @@ jobs:
       - name: Run Windows update tests
         run: cargo test -p bsk --lib --locked cli::update::tests
 
-      - name: Run Windows update process tests
-        run: cargo test -p bsk --test windows_update --locked
+      - name: Run Windows update and cancellation process tests
+        run: cargo test -p bsk --test windows_update --test windows_parent_cancel --locked
+
+      - name: Run installer tests (Windows PowerShell 5.1)
+        shell: powershell
+        run: ./scripts/install-windows.test.ps1
+
+      - name: Run installer tests (PowerShell 7)
+        shell: pwsh
+        run: ./scripts/install-windows.test.ps1
 
   frontend:
     name: Frontend lint, typecheck, tests, build

CHANGELOG.md

@@ -5,7 +5,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
 
-## [Unreleased]
+## [0.2.1] - 2026-09-09
+
+### Changed
+- DSH Plugin: clarified installation, configuration, profile restart, and upgrade instructions
+
+### Fixed
+- CLI: reliable Windows self-updates, including executable replacement and daemon restart
+- CLI: Windows named-pipe connection continuity and stale daemon process detection
+- Windows installer: PowerShell 5.1 compatibility, path quoting, and staged executable replacement
+- CLI / DSH Plugin: cancellation propagation and upload/download cleanup when the parent process exits
+- Extension: tab ownership and session cleanup when agent tabs fail to open or borrowed tabs are returned or closed
+- Extension: navigation recovery when other extensions restrict Chrome DevTools Protocol access
+- Extension: background input filling, automatic append behavior, and verification of field values before reporting success
+- Extension: match observed form state to the correct element after page changes
+- Extension: UUID generation fallback for recording and overlays on insecure origins
+- Browser locale matching for regional language variants
+- DSH Plugin: observation state synchronization, thumbnail capture lifecycle, and stale preview cleanup
+- DSH Plugin: removed the obsolete client runtime host dependency
 
 ## [0.2.0] - 2026-09-02
 

Cargo.lock

@@ -134,7 +134,7 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "anyhow",
  "base64",
@@ -169,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -43,7 +43,7 @@ rand = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }
 
 # Workspace crates (version required for `cargo publish` of dependents)
-bsk-protocol = { version = "0.2.0", path = "crates/bsk-protocol" }
+bsk-protocol = { version = "0.2.1", path = "crates/bsk-protocol" }
 
 [profile.release]
 strip = "symbols"

README.md

@@ -147,20 +147,26 @@ Start a new Agent session and write a prompt that needs the browser, for example
 Using [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)?
 BrowserSkill ships a first-class dsh plugin on npm as
 [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin).
-It injects native `browser_*` tools (no shelling out to `bsk`) and a live Web UI
-overlay of each Agent Window.
+It gives the agent native `browser_*` tools and a live view of its browser sessions
+in the Web UI. The plugin runs `bsk` on the agent's behalf.
 
-Add it to a dsh profile, then start that profile:
+Install the `bsk` CLI and connect the browser extension first. Then add the plugin
+to a dsh profile and start it (replace `web` with your profile name):
 
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
 
-The plugin carries its own copy of the skill, so `bsk install-skill` is not needed
-for dsh — but the `bsk` CLI and the browser extension are still prerequisites. See
-the [plugin README](packages/dsh-plugin-browserskill/README.md) for the tool list,
-configuration, and the observation overlay.
+The plugin includes the `browser-skill` skill, so `bsk install-skill` is not needed
+for dsh. Installed plugins do not update automatically. To upgrade this plugin:
+
+```sh
+dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
+```
+
+Restart the profile after upgrading. See the
+[plugin README](packages/dsh-plugin-browserskill/README.md) for usage and configuration.
 
 ## How It Works
 

README.zh-CN.md

@@ -125,16 +125,22 @@ bsk install-skill
 
 ## DeepSeek Harness 插件
 
-在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它会注入原生 `browser_*` 工具（无需再通过 Shell 调用 `bsk`），并在 Web UI 中实时观察每个 Agent Window。
+在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它为 Agent 提供原生 `browser_*` 工具，由插件代为调用 `bsk`，并在 Web UI 中实时展示浏览器会话。
 
-把它装进某个 dsh profile，然后启动该 profile：
+先安装 `bsk` CLI 并连接浏览器扩展，再将插件装进 dsh profile 并启动（将 `web` 替换为你的 profile 名称）：
 
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
 
-插件自带 skill，所以在 dsh 下无需执行 `bsk install-skill`；但 `bsk` CLI 和浏览器扩展仍是前置条件。工具清单、配置项与观察浮层见[插件 README](packages/dsh-plugin-browserskill/README.md)。
+插件自带 `browser-skill` skill，所以在 dsh 下无需执行 `bsk install-skill`。已安装的插件不会自动更新；升级此插件请运行：
+
+```sh
+dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
+```
+
+升级后重启该 profile。用法与配置见[插件 README](packages/dsh-plugin-browserskill/README.md)。
 
 ## 工作原理
 

apps/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browser-skill/extension",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": true,
   "type": "module",
   "scripts": {

apps/extension/src/tools/__tests__/geometry-context.test.ts

@@ -5,9 +5,10 @@ import { rectPolygon } from "../geometry";
 import {
   projectSnapshotRect,
   screenshotPageRect,
+  snapshotCoordinates,
   snapshotViewportRect,
 } from "../geometry/coordinate-types";
-import { GeometryContext } from "../geometry/frame-context";
+import { GeometryContext, snapshotLayoutScale } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 
 const target = { tabId: 4 };
@@ -22,7 +23,11 @@ const graph: CdpFrameGraph = {
 function driver() {
   const send = vi.fn(async (_tab: number, method: string): Promise<object> => {
     if (method === "Page.getLayoutMetrics")
-      return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 1000 } };
+      return {
+        visualViewport: { clientWidth: 1000 },
+        cssVisualViewport: { clientWidth: 1000 },
+        cssLayoutViewport: { clientWidth: 1000, clientHeight: 1000 },
+      };
     if (method === "DOM.getBoxModel")
       return { model: { content: [52.5, 612.5, 427.5, 612.5, 427.5, 862.5, 52.5, 862.5] } };
     if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
@@ -35,6 +40,63 @@ function driver() {
 }
 
 describe("measurement geometry context", () => {
+  it.each([0.8, 1, 1.25, 2])("normalizes snapshot layout units at scale %s", (scale) => {
+    const measured = snapshotLayoutScale({
+      visualViewport: { clientWidth: 997.25, zoom: 1.1 },
+      cssVisualViewport: { clientWidth: 997.25 / scale, zoom: 1.1 },
+      // Rounded layout dimensions must not supply the scale.
+      layoutViewport: { clientWidth: 997 },
+      cssLayoutViewport: { clientWidth: Math.floor(997.25 / scale) },
+    });
+    expect(measured).toBeCloseTo(scale, 12);
+    const coordinates = snapshotCoordinates(
+      { scrollOffsetX: 80 * scale, scrollOffsetY: 200 * scale },
+      measured,
+      { x: 999, y: 999 },
+    );
+    expect(
+      snapshotViewportRect(
+        [160 * scale, 320 * scale, 120 * scale, 40 * scale],
+        { target },
+        coordinates,
+      )?.rect,
+    ).toEqual({ x: 80, y: 120, width: 120, height: 40 });
+  });
+
+  it("uses CSS root scroll only for missing snapshot offsets, without scaling it twice", () => {
+    const coordinates = snapshotCoordinates({ scrollOffsetX: 80 }, 2, { x: 999, y: 100 });
+    expect(snapshotViewportRect([200, 800, 240, 80], { target }, coordinates)?.rect).toEqual({
+      x: 60,
+      y: 300,
+      width: 120,
+      height: 40,
+    });
+    expect(snapshotCoordinates({ scrollOffsetX: 0 }, 2)).toBeNull();
+    expect(
+      snapshotCoordinates({ scrollOffsetX: NaN, scrollOffsetY: 0 }, 2, { x: 0, y: 0 }),
+    ).toBeNull();
+  });
+
+  it("does not infer snapshot units from missing, invalid, or CSS-only metrics", () => {
+    expect(snapshotLayoutScale({ cssLayoutViewport: { clientWidth: 800 } })).toBeNull();
+    for (const raw of [0, -1, NaN, Infinity]) {
+      expect(
+        snapshotLayoutScale({
+          visualViewport: { clientWidth: raw },
+          cssVisualViewport: { clientWidth: 800 },
+        }),
+      ).toBeNull();
+    }
+    expect(
+      snapshotLayoutScale({
+        visualViewport: { clientWidth: 0, clientHeight: 600 },
+        cssVisualViewport: { clientWidth: 0, clientHeight: 300 },
+      }),
+    ).toBe(2);
+    expect(snapshotCoordinates({ scrollOffsetX: 0, scrollOffsetY: 0 }, null)).toBeNull();
+    expect(snapshotViewportRect([10, 20, 120, 40], { target }, null)).toBeNull();
+  });
+
   it("shares in-flight frame measurements, but never shares them with the next context", async () => {
     const cdp = driver();
     const context = new GeometryContext(cdp, 4);
@@ -61,14 +123,20 @@ describe("measurement geometry context", () => {
       height: 1000,
     });
     if (projection.status !== "available") throw new Error("expected available projection");
-    const input = snapshotViewportRect([17, 23, 120, 40], source, { x: 0, y: 0 });
+    const input = snapshotViewportRect([17, 23, 120, 40], source, {
+      layoutUnitsPerCssPixel: 1,
+      scrollCss: { x: 0, y: 0 },
+    });
     expect(projectSnapshotRect(input!, projection.projection)).toEqual({
       x: 73.75,
       y: 641.25,
       width: 150,
       height: 50,
     });
-    const scrolled = snapshotViewportRect([17, 23, 120, 40], source, { x: 0, y: 10 });
+    const scrolled = snapshotViewportRect([17, 23, 120, 40], source, {
+      layoutUnitsPerCssPixel: 1,
+      scrollCss: { x: 0, y: 10 },
+    });
     expect(projectSnapshotRect(scrolled!, projection.projection)?.y).toBe(628.75);
     await context.snapshotProjection(source, 10, [], { width: 1000, height: 1000 });
     expect(cdp.calls.mock.calls.filter(([, method]) => method === "DOM.resolveNode")).toHaveLength(
@@ -79,11 +147,101 @@ describe("measurement geometry context", () => {
     ).toHaveLength(1);
   });
 
+  it("falls back only for missing or invalid batch entries and does not reuse sizes across contexts", async () => {
+    const cdp = driver();
+    const original = cdp.send;
+    const calls: string[] = [];
+    cdp.send = async (tabId, method, params) => {
+      calls.push(method);
+      if (method === "Runtime.evaluate")
+        return {
+          result: {
+            deepSerializedValue: {
+              type: "array",
+              value: [
+                {
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 10 } },
+                    { type: "string", value: '{"width":300,"height":200}' },
+                  ],
+                },
+                {
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 11 } },
+                    { type: "string", value: '{"width":0,"height":200}' },
+                  ],
+                },
+              ],
+            },
+          },
+        } as never;
+      if (method === "Runtime.releaseObjectGroup") return {} as never;
+      return original(tabId, method, params);
+    };
+    const context = new GeometryContext(cdp, 4);
+    context.registerSnapshotOwners(target, new Set([10, 11]));
+    const values = await Promise.all(
+      [10, 11].map((id) =>
+        context.snapshotProjection({ target, frameId: String(id) }, id, [], {
+          width: 1000,
+          height: 1000,
+        }),
+      ),
+    );
+    expect(values.every((value) => value.status === "available")).toBe(true);
+    expect(calls.filter((method) => method === "DOM.resolveNode")).toHaveLength(1);
+    expect(calls.filter((method) => method === "Runtime.evaluate")).toHaveLength(1);
+    await new GeometryContext(cdp, 4).snapshotProjection({ target, frameId: "child" }, 10, [], {
+      width: 1000,
+      height: 1000,
+    });
+    expect(calls.filter((method) => method === "DOM.resolveNode")).toHaveLength(2);
+  });
+
+  it("waits for batch object cleanup and propagates cancellation", async () => {
+    const cdp = driver();
+    const original = cdp.send;
+    const controller = new AbortController();
+    let release!: () => void;
+    let cleanup!: () => void;
+    const started = new Promise<void>((resolve) => {
+      cleanup = resolve;
+    });
+    cdp.send = async (tabId, method, params) => {
+      if (method === "Runtime.evaluate") return {} as never;
+      if (method === "Runtime.releaseObjectGroup") {
+        cleanup();
+        await new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        return {} as never;
+      }
+      return original(tabId, method, params);
+    };
+    const context = new GeometryContext(cdp, 4, undefined, controller.signal);
+    context.registerSnapshotOwners(target, new Set([10, 11]));
+    let settled = false;
+    const operation = context
+      .snapshotProjection({ target, frameId: "child" }, 10, [], { width: 1000, height: 1000 })
+      .finally(() => {
+        settled = true;
+      });
+    const rejected = expect(operation).rejects.toMatchObject({ name: "AbortError" });
+    await started;
+    controller.abort();
+    expect(settled).toBe(false);
+    release();
+    await rejected;
+    expect(cdp.calls.mock.calls.some(([, method]) => method === "DOM.resolveNode")).toBe(false);
+  });
+
   it("rejects owner mismatches and invalid numeric bounds", () => {
     const input = snapshotViewportRect(
       [30, 50, 120, 40],
       { target, frameId: "main" },
-      { x: 10, y: 20 },
+      { layoutUnitsPerCssPixel: 1, scrollCss: { x: 10, y: 20 } },
     )!;
     const projection = {
       source: { target, frameId: "main" },
@@ -104,8 +262,20 @@ describe("measurement geometry context", () => {
         source: { target: { tabId: 5 }, frameId: "main" },
       }),
     ).toBeNull();
-    expect(snapshotViewportRect([0, 0, NaN, 40], { target }, { x: 0, y: 0 })).toBeNull();
-    expect(snapshotViewportRect([0, 0, 10, 40], { target }, { x: Infinity, y: 0 })).toBeNull();
+    expect(
+      snapshotViewportRect(
+        [0, 0, NaN, 40],
+        { target },
+        { layoutUnitsPerCssPixel: 1, scrollCss: { x: 0, y: 0 } },
+      ),
+    ).toBeNull();
+    expect(
+      snapshotViewportRect(
+        [0, 0, 10, 40],
+        { target },
+        { layoutUnitsPerCssPixel: 1, scrollCss: { x: Infinity, y: 0 } },
+      ),
+    ).toBeNull();
   });
 
   it("does not turn a border quad or a failed owner read into a content projection", async () => {
@@ -138,7 +308,7 @@ describe("measurement geometry context", () => {
     const input = snapshotViewportRect(
       [0, 0, 300, 200],
       { target, frameId: "nested" },
-      { x: 0, y: 0 },
+      { layoutUnitsPerCssPixel: 1, scrollCss: { x: 0, y: 0 } },
     );
     expect(projectSnapshotRect(input!, projection.projection)).toEqual({
       x: 60,
@@ -188,7 +358,11 @@ describe("measurement geometry context", () => {
       peak = Math.max(peak, active);
       await new Promise<void>((resolve) => release.push(resolve));
       active--;
-      return { cssLayoutViewport: { clientWidth: 100, clientHeight: 100 } };
+      return {
+        visualViewport: { clientWidth: 1000 },
+        cssVisualViewport: { clientWidth: 1000 },
+        cssLayoutViewport: { clientWidth: 100, clientHeight: 100 },
+      };
     });
     const controller = new AbortController();
     const context = new GeometryContext(

apps/extension/src/tools/__tests__/snapshot-coordinates.browser.test.ts

@@ -0,0 +1,237 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import type { CdpFrame, CdpFrameGraph, CdpTarget } from "@/browser-driver/frame-graph";
+import { GeometryContext } from "../geometry/frame-context";
+import type { CdpRunner } from "../shared";
+import { captureViewModel } from "../vom/capture";
+import { captureFrameData } from "../vom/frame-capture";
+
+type Send = <T = Record<string, unknown>>(
+  method: string,
+  params?: object,
+  sessionId?: string,
+) => Promise<T>;
+type Tree = { frame: { id: string; parentId?: string; name?: string }; childFrames?: Tree[] };
+type Rect = { x: number; y: number; w: number; h: number };
+type Oracle = { probe: Rect; owners: Record<string, { x: number; y: number; scale: number }> };
+
+// The independent oracle uses DOM border boxes and this fixture's axis-aligned
+// iframe transforms. No production snapshot conversion/projection builds expectations.
+const oracleExpression = `(() => {
+  const box = document.querySelector('#probe').getBoundingClientRect();
+  const owners = {};
+  for (const frame of document.querySelectorAll('iframe')) {
+    const rect = frame.getBoundingClientRect();
+    const style = getComputedStyle(frame);
+    const scale = rect.width / frame.offsetWidth;
+    owners[frame.name] = {
+      x: rect.x + (frame.clientLeft + parseFloat(style.paddingLeft)) * scale,
+      y: rect.y + (frame.clientTop + parseFloat(style.paddingTop)) * scale,
+      scale,
+    };
+  }
+  return { probe: { x: box.x, y: box.y, w: box.width, h: box.height }, owners };
+})()`;
+
+describe.skipIf(!process.env.BSK_GEOMETRY_CHROME)("real DOMSnapshot coordinate contract", () => {
+  it.each([
+    { deviceScale: 1, zoom: 1 },
+    { deviceScale: 0.8, zoom: 1 },
+    { deviceScale: 1, zoom: 1.25 },
+    { deviceScale: 2, zoom: 1 },
+    { deviceScale: 2, zoom: 0.8 },
+  ])("matches DOM geometry at device scale $deviceScale and zoom $zoom", async (configuration) => {
+    const evalRoot = new URL("../../../../../evals/browser/", import.meta.url);
+    const { createEvalServer } = await import(new URL("lib/server.mjs", evalRoot).href);
+    const { withChrome } = await import(
+      new URL("cases/regression/snapshot-coordinates/chrome.mjs", evalRoot).href
+    );
+    const server = createEvalServer();
+    const { baseUrl } = await server.start();
+    try {
+      await withChrome(
+        { executable: process.env.BSK_GEOMETRY_CHROME, ...configuration },
+        async (send: Send) => {
+          const { targetId } = await send<{ targetId: string }>("Target.createTarget", {
+            url: "about:blank",
+          });
+          const { sessionId: rootSession } = await send<{ sessionId: string }>(
+            "Target.attachToTarget",
+            { targetId, flatten: true },
+          );
+          await send(
+            "Page.navigate",
+            { url: `${baseUrl}/snapshot-coordinates?run=coordinates` },
+            rootSession,
+          );
+          await expect
+            .poll(
+              () =>
+                server
+                  .snapshot("coordinates")
+                  .events.some(
+                    (event: { type: string; data: { root?: boolean } }) =>
+                      event.type === "geometry.ready" && event.data.root,
+                  ),
+              { timeout: 10_000 },
+            )
+            .toBe(true);
+
+          const targets = await send<{ targetInfos: { targetId: string; type: string }[] }>(
+            "Target.getTargets",
+          );
+          const sessions = [rootSession];
+          for (const target of targets.targetInfos.filter((target) => target.type === "iframe")) {
+            const { sessionId } = await send<{ sessionId: string }>("Target.attachToTarget", {
+              targetId: target.targetId,
+              flatten: true,
+            });
+            sessions.push(sessionId);
+          }
+          expect(sessions.length).toBe(2); // The cross-site fixture must actually be an OOPIF.
+          const frames: CdpFrame[] = [];
+          const names = new Map<string, string>();
+          const sessionFor = (target: CdpTarget) => target.sessionId ?? rootSession;
+          for (const sessionId of sessions) {
+            const { frameTree } = await send<{ frameTree: Tree }>(
+              "Page.getFrameTree",
+              {},
+              sessionId,
+            );
+            const target: CdpTarget = {
+              tabId: 1,
+              ...(sessionId === rootSession ? {} : { sessionId }),
+            };
+            const visit = (tree: Tree, parentFrameId = tree.frame.parentId) => {
+              frames.push({ frameId: tree.frame.id, parentFrameId, target });
+              names.set(tree.frame.id, tree.frame.name ?? "");
+              for (const child of tree.childFrames ?? []) visit(child, tree.frame.id);
+            };
+            visit(frameTree);
+          }
+          expect(frames).toHaveLength(5);
+          for (const frame of frames) {
+            if (!frame.parentFrameId) continue;
+            const parent = frames.find((item) => item.frameId === frame.parentFrameId)!;
+            const owner = await send<{ backendNodeId: number }>(
+              "DOM.getFrameOwner",
+              { frameId: frame.frameId },
+              sessionFor(parent.target),
+            );
+            frame.ownerBackendNodeId = owner.backendNodeId;
+          }
+          const graph: CdpFrameGraph = { rootFrameId: frames[0].frameId, frames };
+          const calls: string[] = [];
+          const cdp: CdpRunner = {
+            send: (tabId, method, params) => {
+              calls.push(`${tabId}:${method}`);
+              return send(method, params, rootSession);
+            },
+            sendToTarget: (target, method, params) => {
+              calls.push(`${target.sessionId ?? target.tabId}:${method}`);
+              return send(method, params, sessionFor(target));
+            },
+            getFrameGraph: async () => graph,
+          };
+          const oracles = new Map<string, Oracle>();
+          for (const frame of frames) {
+            const session = sessionFor(frame.target);
+            const { executionContextId } = await send<{ executionContextId: number }>(
+              "Page.createIsolatedWorld",
+              { frameId: frame.frameId, worldName: "coordinate-oracle" },
+              session,
+            );
+            await expect
+              .poll(
+                async () => {
+                  const ready = await send<{ result: { value: boolean } }>(
+                    "Runtime.evaluate",
+                    {
+                      expression: 'document.documentElement.dataset.geometryReady === "true"',
+                      contextId: executionContextId,
+                      returnByValue: true,
+                    },
+                    session,
+                  );
+                  return ready.result.value;
+                },
+                { timeout: 5_000 },
+              )
+              .toBe(true);
+            // Establish scroll after cross-process target creation/layout settles.
+            const scroll = frame.parentFrameId
+              ? names.get(frame.frameId) === "nested"
+                ? [10, 20]
+                : [40, 100]
+              : [80, 240];
+            await send(
+              "Runtime.evaluate",
+              {
+                expression: `(async () => { scrollTo(${scroll.join(",")}); await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))); })()`,
+                contextId: executionContextId,
+                awaitPromise: true,
+              },
+              session,
+            );
+            const reply = await send<{ result: { value: Oracle } }>(
+              "Runtime.evaluate",
+              { expression: oracleExpression, contextId: executionContextId, returnByValue: true },
+              session,
+            );
+            oracles.set(frame.frameId, reply.result.value);
+          }
+          const geometry = new GeometryContext(cdp, 1, graph);
+          const captured = await captureViewModel(cdp, 1, { geometry });
+          await captureFrameData(cdp, 1, captured, undefined, geometry);
+          expect(captured.frameGeometryIssues).toEqual([]);
+          for (const frame of frames) {
+            const node = captured.frameNodes
+              ?.get(frame.frameId)
+              ?.find((node) => node.attrs.id === "probe");
+            expect(node, `missing probe in ${names.get(frame.frameId) || "root"}`).toBeDefined();
+            const local = oracles.get(frame.frameId)!.probe;
+            const top = { ...local };
+            let current = frame;
+            while (current.parentFrameId) {
+              const owner = oracles.get(current.parentFrameId)!.owners[names.get(current.frameId)!];
+              top.x = owner.x + top.x * owner.scale;
+              top.y = owner.y + top.y * owner.scale;
+              top.w *= owner.scale;
+              top.h *= owner.scale;
+              current = frames.find((item) => item.frameId === current.parentFrameId)!;
+            }
+            expect(
+              node!.rect,
+              JSON.stringify({
+                frame: names.get(frame.frameId),
+                local,
+                top,
+                viewport: captured.viewport,
+              }),
+            ).not.toBeNull();
+            for (const key of ["x", "y", "w", "h"] as const) {
+              expect(
+                Math.abs(node!.localRect![key] - local[key]),
+                `${names.get(frame.frameId)} local ${key}`,
+              ).toBeLessThan(2);
+              expect(
+                Math.abs(node!.rect![key] - top[key]),
+                `${names.get(frame.frameId)} top ${key}`,
+              ).toBeLessThan(2);
+            }
+          }
+          expect(calls.filter((call) => call.endsWith(":Page.getLayoutMetrics"))).toHaveLength(
+            sessions.length,
+          );
+          const metrics = await send<{
+            cssVisualViewport: { zoom: number };
+            visualViewport: { clientWidth: number };
+          }>("Page.getLayoutMetrics", {}, rootSession);
+          expect(metrics.cssVisualViewport.zoom).toBeCloseTo(configuration.zoom, 4);
+        },
+      );
+    } finally {
+      await server.stop();
+    }
+  }, 30_000);
+});

apps/extension/src/tools/geometry/coordinate-types.ts

@@ -25,6 +25,12 @@ export interface UnavailableFrameProjection {
   ownerBackendNodeId: number;
 }
 
+export interface UnavailableSnapshotCoordinates {
+  status: "unavailable";
+  source: CoordinateOwner;
+  reason: "snapshot-coordinates-unavailable";
+}
+
 export type SnapshotProjectionResult =
   | { status: "available"; projection: SnapshotProjection }
   | UnavailableFrameProjection;
@@ -32,25 +38,74 @@ export type SnapshotProjectionResult =
 /** Descendants inherit the failed boundary without attempting another owner read. */
 export type FrameProjectionIssue =
   | UnavailableFrameProjection
-  | { status: "blocked"; source: CoordinateOwner; cause: UnavailableFrameProjection };
+  | UnavailableSnapshotCoordinates
+  | {
+      status: "blocked";
+      source: CoordinateOwner;
+      cause: UnavailableFrameProjection | UnavailableSnapshotCoordinates;
+    };
 
 export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
 
-/** DOMSnapshot bounds are document-relative CSS pixels, independent of raster DPR. */
+export interface SnapshotCoordinates {
+  layoutUnitsPerCssPixel: number;
+  scrollCss: { x: number; y: number };
+}
+
+/** Snapshot scroll offsets share the raw layout units of its bounds. Only a
+ * target's root document may fall back to that target's CSS layout viewport. */
+export function snapshotCoordinates(
+  document: { scrollOffsetX?: number; scrollOffsetY?: number },
+  layoutUnitsPerCssPixel: number | null,
+  rootScrollCss?: { x?: number; y?: number },
+): SnapshotCoordinates | null {
+  if (
+    layoutUnitsPerCssPixel === null ||
+    !Number.isFinite(layoutUnitsPerCssPixel) ||
+    layoutUnitsPerCssPixel <= 0
+  )
+    return null;
+  const x =
+    document.scrollOffsetX === undefined
+      ? rootScrollCss?.x
+      : document.scrollOffsetX / layoutUnitsPerCssPixel;
+  const y =
+    document.scrollOffsetY === undefined
+      ? rootScrollCss?.y
+      : document.scrollOffsetY / layoutUnitsPerCssPixel;
+  if (x === undefined || y === undefined || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { layoutUnitsPerCssPixel, scrollCss: { x, y } };
+}
+
+/** Convert raw document-relative Blink layout units exactly once, before any
+ * CSS viewport clipping or frame projection. This scale is not screenshot zoom. */
 export function snapshotViewportRect(
   bounds: number[],
   owner: CoordinateOwner,
-  scroll: { x: number; y: number },
+  coordinates: SnapshotCoordinates | null,
 ): FrameViewportRect | null {
-  if (bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
+  if (!coordinates || bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
+  const { layoutUnitsPerCssPixel: scale, scrollCss: scroll } = coordinates;
   const [x, y, width, height] = bounds;
-  if (width <= 0 || height <= 0 || !Number.isFinite(scroll.x) || !Number.isFinite(scroll.y)) {
+  if (
+    !Number.isFinite(scale) ||
+    scale <= 0 ||
+    width <= 0 ||
+    height <= 0 ||
+    !Number.isFinite(scroll.x) ||
+    !Number.isFinite(scroll.y)
+  ) {
     return null;
   }
   return {
     space: "frame-viewport-css",
     owner,
-    rect: { x: x - scroll.x, y: y - scroll.y, width, height },
+    rect: {
+      x: x / scale - scroll.x,
+      y: y / scale - scroll.y,
+      width: width / scale,
+      height: height / scale,
+    },
   };
 }
 

apps/extension/src/tools/geometry/frame-context.ts

@@ -15,9 +15,11 @@ import {
 import { type CdpRunner, sendToCdpTarget } from "../shared";
 import type { CoordinateOwner, CssViewport, SnapshotProjectionResult } from "./coordinate-types";
 
+import { readSnapshotOwnerSizes } from "./snapshot-owner-sizes";
+
 export interface LayoutMetrics {
-  cssVisualViewport?: { zoom?: number };
-  visualViewport?: { zoom?: number };
+  cssVisualViewport?: { zoom?: number; clientWidth?: number; clientHeight?: number };
+  visualViewport?: { zoom?: number; clientWidth?: number; clientHeight?: number };
   cssLayoutViewport?: {
     clientWidth?: number;
     clientHeight?: number;
@@ -27,6 +29,29 @@ export interface LayoutMetrics {
   layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
 }
 
+/** Chromium emits these paired floating-point dimensions before/after dividing
+ * by LayoutZoomFactor. Integer layout viewport dimensions lose precision at
+ * fractional zoom. Neither visualViewport.scale nor .zoom is this conversion.
+ * See InspectorPageAgent::getLayoutMetrics in Chromium. */
+export function snapshotLayoutScale(metrics: LayoutMetrics): number | null {
+  for (const dimension of ["clientWidth", "clientHeight"] as const) {
+    const raw = metrics.visualViewport?.[dimension];
+    const css = metrics.cssVisualViewport?.[dimension];
+    if (
+      raw !== undefined &&
+      css !== undefined &&
+      Number.isFinite(raw) &&
+      Number.isFinite(css) &&
+      raw > 0 &&
+      css > 0
+    ) {
+      const scale = raw / css;
+      if (Number.isFinite(scale) && scale > 0) return scale;
+    }
+  }
+  return null;
+}
+
 /** The legacy field is a compatibility fallback, never a source of raster DPR. */
 export function cssViewport(metrics: LayoutMetrics): CssViewport {
   const value = metrics.cssLayoutViewport ?? metrics.layoutViewport;
@@ -45,6 +70,7 @@ export class GeometryContext {
   private readonly owners = new Map<string, Promise<Quad | null>>();
   private readonly projections = new Map<string, Promise<GeometryProjection | null>>();
   private readonly snapshotOwners = new Map<string, Promise<{ quad: Quad; size: Size } | null>>();
+  private readonly sizeBatches = new Map<string, () => Promise<Map<number, Size>>>();
   private active = 0;
   private readonly waiting: Array<() => void> = [];
   private graphPromise?: Promise<CdpFrameGraph | null>;
@@ -186,12 +212,34 @@ export class GeometryContext {
       : { status: "unavailable", source, ownerBackendNodeId };
   }
 
+  /** Register one target's snapshot owners; the batch starts only when a
+   * projection actually needs a size. Single owners keep the cheaper old path. */
+  registerSnapshotOwners(target: CdpTarget, owners: ReadonlySet<number>): void {
+    const key = cdpTargetKey(target);
+    if (owners.size < 2 || this.sizeBatches.has(key)) return;
+    let pending: Promise<Map<number, Size>> | undefined;
+    this.sizeBatches.set(key, () => {
+      pending ??= readSnapshotOwnerSizes(
+        (method, params, cleanup) => this.request(target, method, params, cleanup),
+        owners,
+      ).catch((error) => {
+        if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
+          throw error;
+        return new Map<number, Size>();
+      });
+      return pending;
+    });
+  }
+
   private async snapshotOwner(
     target: CdpTarget,
     backendNodeId: number,
   ): Promise<{ quad: Quad; size: Size } | null> {
     const quad = await this.ownerContent(target, backendNodeId);
     if (!quad) return null;
+    const batchSize = (await this.sizeBatches.get(cdpTargetKey(target))?.())?.get(backendNodeId);
+    if (this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
+    if (batchSize) return { quad, size: batchSize };
     const resolved = await this.request<{ object?: { objectId?: string } }>(
       target,
       "DOM.resolveNode",

apps/extension/src/tools/geometry/snapshot-owner-sizes.ts

@@ -0,0 +1,74 @@
+import type { Size } from "../geometry";
+
+interface SerializedValue {
+  type: string;
+  value?: unknown;
+}
+
+type Send = <T>(method: string, params: object, cleanup?: boolean) => Promise<T>;
+
+/** Batch only accessible frame owners. Missing/shadow/cross-origin owners keep
+ * the existing node-scoped read; no page-wide style columns are requested. */
+export async function readSnapshotOwnerSizes(
+  send: Send,
+  owners: ReadonlySet<number>,
+): Promise<Map<number, Size>> {
+  const sizes = new Map<number, Size>();
+  const objectGroup = `bsk-frame-sizes-${crypto.randomUUID()}`;
+  try {
+    const reply = await send<{ result?: { deepSerializedValue?: SerializedValue } }>(
+      "Runtime.evaluate",
+      {
+        expression: `(() => {
+          const result = [];
+          const documents = [document];
+          for (let i = 0; i < documents.length && result.length < ${owners.size}; i++) {
+            for (const owner of documents[i].querySelectorAll('iframe,frame')) {
+              if (result.length >= ${owners.size}) break;
+              if (!owner.isConnected) continue;
+              const style = getComputedStyle(owner);
+              result.push([owner, JSON.stringify({
+                width: owner.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
+                height: owner.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+              })]);
+              try { if (owner.contentDocument) documents.push(owner.contentDocument); } catch {}
+            }
+          }
+          return result;
+        })()`,
+        objectGroup,
+        serializationOptions: {
+          serialization: "deep",
+          maxDepth: 3,
+          additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+        },
+      },
+    );
+    const result = reply.result?.deepSerializedValue;
+    if (result?.type !== "array" || !Array.isArray(result.value)) return sizes;
+    for (const entry of result.value as SerializedValue[]) {
+      if (entry.type !== "array" || !Array.isArray(entry.value)) continue;
+      const [node, data] = entry.value as SerializedValue[];
+      if (node?.type !== "node" || data?.type !== "string" || typeof data.value !== "string")
+        continue;
+      const id = (node.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+      if (id === undefined || !owners.has(id)) continue;
+      try {
+        const size = JSON.parse(data.value) as Size;
+        if (
+          size &&
+          Number.isFinite(size.width) &&
+          Number.isFinite(size.height) &&
+          size.width > 0 &&
+          size.height > 0
+        )
+          sizes.set(id, size);
+      } catch {
+        /* An invalid entry uses the existing individual read. */
+      }
+    }
+  } finally {
+    await send("Runtime.releaseObjectGroup", { objectGroup }, true).catch(() => {});
+  }
+  return sizes;
+}

apps/extension/src/tools/observation.ts

@@ -1,4 +1,3 @@
-import type { CapturedSceneInput } from "./vom/facts";
 // Observation handlers — `tool.snapshot`, `tool.get_html`, `tool.screenshot`,
 // and semantic `tool.observe` (design §7). Each handler resolves the target
 // tab (defaulting to the Agent Window's active tab when omitted) and
@@ -36,6 +35,7 @@ import { attachDialogs, markDialogCursor } from "./dialogs";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry } from "./frame-geometry";
 import { screenshotPageRect } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
 import {
   type ChromeTabsApi,
   enforceToolTargetScope,
@@ -49,9 +49,15 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { type CapturedNode, type CapturedSurfaceProbe, probeHoverSurfaces } from "./vom/capture";
-import { captureObservationFacts, semanticCapture } from "./vom/capture-coordinator";
-import type { FrameDocument as CapturedFrameDocument } from "./vom/frame-document";
+import {
+  type CapturedNode,
+  type CapturedSurfaceProbe,
+  type CapturedViewModel,
+  captureViewModel,
+  collectOverlayExcludedBackendIds,
+  probeHoverSurfaces,
+} from "./vom/capture";
+import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
 import { withOverlayBypass } from "./vom/hover-perception";
 import { probeTooltipNames } from "./vom/name-enrichment";
 import {
@@ -525,7 +531,7 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
 
 function buildConditionalSurfaces(
   nodes: VomNode[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   probes: CapturedSurfaceProbe[],
 ): CondSurface[] {
   if (probes.length === 0) return [];
@@ -655,9 +661,163 @@ export interface BuildVomSceneOptions {
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
 
+function legacyFrameDocuments(
+  axNodes: CdpAxNode[],
+  captured: CapturedViewModel,
+  pageUrl?: string,
+  rootTarget: VomFrameDocument["target"] = { tabId: 0 },
+): VomFrameDocument[] {
+  const rootFrameId = captured.rootFrameId ?? "root";
+  const documents: VomFrameDocument[] = [
+    {
+      frameId: rootFrameId,
+      contextScopeId: rootFrameId,
+      target: rootTarget,
+      ...(pageUrl ? { url: pageUrl } : {}),
+      axNodes: [],
+      domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
+      excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(rootFrameId),
+    },
+  ];
+  const pending = [...captured.iframeNodes.entries()];
+  let progress = true;
+  let nextSyntheticFrame = 1;
+  while (pending.length > 0 && progress) {
+    progress = false;
+    for (let index = pending.length - 1; index >= 0; index -= 1) {
+      const [ownerBackendNodeId, domNodes] = pending[index];
+      const parent = documents.find((document) =>
+        document.domNodes.some((node) => node.backendNodeId === ownerBackendNodeId),
+      );
+      if (!parent) continue;
+      const frameId =
+        domNodes.find((node) => node.frameId)?.frameId ?? `legacy-frame-${nextSyntheticFrame++}`;
+      documents.push({
+        frameId,
+        parentFrameId: parent.frameId,
+        ownerBackendNodeId,
+        contextScopeId: frameId,
+        target: parent.target,
+        axNodes: [],
+        domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
+        excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(frameId),
+      });
+      pending.splice(index, 1);
+      progress = true;
+    }
+  }
+
+  const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
+  const backendFrame = new Map<number, string>();
+  const childFrameByOwner = new Map<number, string>();
+  for (const document of documents) {
+    if (document.ownerBackendNodeId !== undefined) {
+      childFrameByOwner.set(document.ownerBackendNodeId, document.frameId);
+    }
+    for (const node of document.domNodes) backendFrame.set(node.backendNodeId, document.frameId);
+  }
+  const axById = new Map(axNodes.map((node) => [node.nodeId, node]));
+  const ownership = new Map<string, string>();
+  const resolving = new Set<string>();
+  const frameForAx = (node: CdpAxNode): string => {
+    const cached = ownership.get(node.nodeId);
+    if (cached) return cached;
+    let frameId: string | undefined;
+    if (node.frameId && documentByFrameId.has(node.frameId)) frameId = node.frameId;
+    if (!frameId && typeof node.backendDOMNodeId === "number") {
+      frameId = backendFrame.get(node.backendDOMNodeId);
+    }
+    if (!frameId && node.parentId && !resolving.has(node.nodeId)) {
+      const parent = axById.get(node.parentId);
+      if (parent) {
+        frameId =
+          typeof parent.backendDOMNodeId === "number"
+            ? childFrameByOwner.get(parent.backendDOMNodeId)
+            : undefined;
+        if (!frameId) {
+          resolving.add(node.nodeId);
+          frameId = frameForAx(parent);
+          resolving.delete(node.nodeId);
+        }
+      }
+    }
+    frameId ??= rootFrameId;
+    ownership.set(node.nodeId, frameId);
+    return frameId;
+  };
+  for (const node of axNodes) frameForAx(node);
+  for (const node of axNodes) {
+    const frameId = ownership.get(node.nodeId) ?? rootFrameId;
+    const document = documentByFrameId.get(frameId) ?? documents[0];
+    document.axNodes.push({
+      ...node,
+      frameId,
+      ...(node.parentId && ownership.get(node.parentId) === frameId
+        ? { parentId: node.parentId }
+        : { parentId: undefined }),
+      ...(node.childIds
+        ? { childIds: node.childIds.filter((childId) => ownership.get(childId) === frameId) }
+        : {}),
+    });
+  }
+  return documents;
+}
+
+function withLegacyBackendIds(scene: VomScene): VomScene {
+  const used = new Set<number>();
+  const idMap = new Map<number, number>();
+  let nextVirtualId = -1;
+  for (const node of scene.nodes) {
+    const preferred = node.backendNodeId;
+    const id = preferred !== undefined && !used.has(preferred) ? preferred : nextVirtualId--;
+    used.add(id);
+    idMap.set(node.id, id);
+  }
+  return {
+    ...scene,
+    nodes: scene.nodes.map((node) => ({
+      ...node,
+      id: idMap.get(node.id) as number,
+      parentId: node.parentId === null ? null : (idMap.get(node.parentId) ?? null),
+      ...(node.domParentId !== undefined
+        ? { domParentId: node.domParentId === null ? null : (idMap.get(node.domParentId) ?? null) }
+        : {}),
+      ...(node.domAncestorIds
+        ? { domAncestorIds: node.domAncestorIds.flatMap((id) => idMap.get(id) ?? []) }
+        : {}),
+    })),
+    ...(scene.surfaces
+      ? {
+          surfaces: scene.surfaces.map((surface) => ({
+            ...surface,
+            triggerId: idMap.get(surface.triggerId) ?? surface.triggerId,
+          })),
+        }
+      : {}),
+    ...(scene.activeScopeBlocks
+      ? {
+          activeScopeBlocks: scene.activeScopeBlocks.map((block) => ({
+            ...block,
+            triggerId: idMap.get(block.triggerId) ?? block.triggerId,
+          })),
+        }
+      : {}),
+  };
+}
+
+export function buildVomScene(
+  axNodes: CdpAxNode[],
+  captured: CapturedViewModel,
+  options: BuildVomSceneOptions = {},
+): VomScene {
+  return withLegacyBackendIds(
+    buildFrameVomScene(legacyFrameDocuments(axNodes, captured, options.pageUrl), captured, options),
+  );
+}
+
 export function buildFrameVomScene(
   documents: VomFrameDocument[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   options: BuildVomSceneOptions = {},
 ): VomScene {
   const scene = buildSemanticVomScene({
@@ -673,7 +833,7 @@ export function buildFrameVomScene(
 function attachCapturedSceneAnnotations(
   scene: VomScene,
   documents: VomFrameDocument[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   surfaceProbes: CapturedSurfaceProbe[],
 ): VomScene {
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
@@ -823,6 +983,45 @@ export async function handleGetHtml(
   }
 }
 
+function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedViewModel {
+  return { viewport, nodes: [], iframeNodes: new Map(), excludedBackendNodeIds: new Set() };
+}
+
+async function fallbackCapturedViewModel(
+  cdp: CdpRunner,
+  tabId: number,
+  geometry: GeometryContext,
+  signal?: AbortSignal,
+): Promise<CapturedViewModel> {
+  throwIfAborted(signal, "observation");
+  let viewport = { width: 0, height: 0 };
+  try {
+    const metrics = await geometry.layoutMetrics({ tabId });
+    throwIfAborted(signal, "observation");
+    const source = cssViewport(metrics);
+    viewport = { width: source.width, height: source.height };
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+  }
+  const excludedBackendNodeIds = await collectOverlayExcludedBackendIds(cdp, tabId, signal);
+  throwIfAborted(signal, "observation");
+  return { ...emptyCapturedViewModel(viewport), excludedBackendNodeIds };
+}
+
+async function captureForVom(
+  cdp: CdpRunner,
+  tabId: number,
+  options: CaptureVomObservationOptions,
+  geometry: GeometryContext,
+): Promise<CapturedViewModel> {
+  try {
+    return await captureViewModel(cdp, tabId, { signal: options.signal, geometry });
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return fallbackCapturedViewModel(cdp, tabId, geometry, options.signal);
+  }
+}
+
 export interface HoverProbeOutcome {
   /** Whether any active hover was dispatched during this observation. */
   performed: boolean;
@@ -855,7 +1054,7 @@ const NO_HOVER_PROBES: HoverProbeOutcome = {
 async function runHoverProbes(
   cdp: CdpRunner,
   tabId: number,
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   documents: VomFrameDocument[],
   staticSemantics: ReturnType<typeof resolveSemanticGraph>,
   options: CaptureVomObservationOptions,
@@ -894,9 +1093,21 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   await cdp.ensureAttachedToUrl?.(tabId, url);
   throwIfAborted(options.signal, "observation");
-  const facts = await captureObservationFacts<CdpAxNode>(cdp, tabId, options.signal, url);
-  const { captured, documents: normalizedDocuments } = semanticCapture(facts);
+  const geometry = new GeometryContext(cdp, tabId, undefined, options.signal);
+  const captured = await captureForVom(cdp, tabId, options, geometry);
   throwIfAborted(options.signal, "observation");
+  const documents = await captureFrameData<CdpAxNode>(
+    cdp,
+    tabId,
+    captured,
+    options.signal,
+    geometry,
+  );
+  throwIfAborted(options.signal, "observation");
+  const normalizedDocuments =
+    documents.length === 1 && captured.iframeNodes.size > 0
+      ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
+      : documents;
   const semanticGraph = buildSemanticGraph({
     documents: normalizedDocuments,
     viewport: captured.viewport,
@@ -926,8 +1137,8 @@ export async function captureVomObservation(
   );
   // Reserve space using the renderer's character-based token estimate. Like VOM
   // headers, this integrity notice remains visible even under a tiny token budget.
-  const geometryNotice = facts.issues.some((issue) => issue.stage === "geometry")
-    ? "@warning iframe geometry incomplete: some frame content has no top-level coordinates.\n"
+  const geometryNotice = captured.frameGeometryIssues?.length
+    ? "@warning geometry incomplete: some page or frame content has no top-level coordinates.\n"
     : "";
   const rendered = renderVom(decoratedScene, {
     maxDepth: options.maxDepth,

apps/extension/src/tools/vom/__tests__/capture-coordinator.test.ts

@@ -1,914 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
-import { cdpTargetKey } from "@/browser-driver/frame-graph";
-import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
-import type { CdpRunner } from "../../shared";
-import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
-import { buildSemanticGraph } from "../semantic-graph/build";
-import { REQUESTED_STYLES } from "../snapshot";
-
-function fixture(
-  options: { frames?: CdpFrame[]; fail?: string; omitDocument?: string; overlay?: string } = {},
-) {
-  const frames = options.frames ?? [
-    { frameId: "main", target: { tabId: 4 } },
-    {
-      frameId: "same",
-      parentFrameId: "main",
-      ownerBackendNodeId: 3,
-      target: { tabId: 4 },
-    },
-    {
-      frameId: "nested",
-      parentFrameId: "same",
-      ownerBackendNodeId: 13,
-      target: { tabId: 4 },
-    },
-    {
-      frameId: "remote",
-      parentFrameId: "main",
-      ownerBackendNodeId: 4,
-      target: { tabId: 4, sessionId: "remote" },
-    },
-  ];
-  const elements = new Map(
-    frames.map((frame, i) => [frame.frameId, frame.target.sessionId ? 1 : i * 10 + 1]),
-  );
-  const logs: Array<{ target: CdpTarget; method: string; params: Record<string, unknown> }> = [];
-  const send = vi.fn(
-    async <T>(target: CdpTarget, method: string, params: object = {}): Promise<T> => {
-      logs.push({ target, method, params: params as Record<string, unknown> });
-      const args = params as Record<string, string | number>;
-      if (options.fail === `${target.sessionId ?? "main"}:${method}`)
-        throw new Error("fixture failure");
-      let result: unknown = {};
-      if (method === "Page.getLayoutMetrics")
-        result = { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-      if (method === "DOMSnapshot.captureSnapshot") {
-        expect((params as { computedStyles: unknown }).computedStyles).toEqual(REQUESTED_STYLES);
-        result = {
-          strings: [
-            "#document",
-            "html",
-            "button",
-            OVERLAY_HOST_MARKER_ATTR,
-            "",
-            "visible",
-            "1",
-            "static",
-            "auto",
-          ],
-          documents: frames
-            .filter(
-              (frame) =>
-                cdpTargetKey(frame.target) === cdpTargetKey(target) &&
-                frame.frameId !== options.omitDocument,
-            )
-            .map((frame) => {
-              const element = elements.get(frame.frameId)!;
-              return {
-                frameId: frame.frameId,
-                nodes: {
-                  backendNodeId: [element - 1, element + 10000, element, element + 1],
-                  nodeName: [0, 1, 1, 2],
-                  nodeType: [9, 10, 1, 1],
-                  parentIndex: [-1, 0, 0, 2],
-                  attributes: [[], [], [], frame.frameId === options.overlay ? [3, 4] : []],
-                },
-                layout: {
-                  nodeIndex: [2, 3],
-                  bounds: [
-                    [0, 0, 1000, 800],
-                    [10, 20, 100, 40],
-                  ],
-                  styles: [
-                    [7, 8, 8, 5, 6],
-                    [7, 8, 8, 5, 6],
-                  ],
-                },
-              };
-            }),
-        };
-      }
-      if (method === "Accessibility.getFullAXTree") {
-        const frameId = String(args.frameId);
-        result = {
-          nodes: [
-            {
-              nodeId: `${frameId}-button`,
-              frameId,
-              backendDOMNodeId: elements.get(frameId)! + 1,
-              role: { value: "button" },
-              name: { value: frameId },
-            },
-          ],
-        };
-      }
-      return result as T;
-    },
-  );
-  const cdp: CdpRunner = {
-    getFrameGraph: async () => ({ rootFrameId: frames[0].frameId, frames }),
-    send: (tabId, method, params) =>
-      (send as NonNullable<CdpRunner["sendToTarget"]>)({ tabId }, method, params),
-    sendToTarget: send as NonNullable<CdpRunner["sendToTarget"]>,
-  };
-  return { cdp, logs, elements };
-}
-
-describe("captureObservationFacts", () => {
-  it("collects each target once and scopes equal backend IDs", async () => {
-    const { cdp, logs } = fixture();
-    const facts = await captureObservationFacts(cdp, 4);
-    expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(2);
-    expect(logs.filter((call) => call.method === "Accessibility.enable")).toHaveLength(2);
-    expect(logs.filter((call) => call.method === "Accessibility.getFullAXTree")).toHaveLength(4);
-    const main = facts.documents.find((doc) => doc.frame.frameId === "main")!;
-    const remote = facts.documents.find((doc) => doc.frame.frameId === "remote")!;
-    expect(main.index.nodes.get(2)).not.toBe(remote.index.nodes.get(2));
-    expect(main.index.nodes.get(2)?.parentBackendNodeId).toBe(1);
-    expect(main.index.nodes.get(10001)?.nodeType).toBe(10);
-    expect(remote.axNodes[0].frameId).toBe("remote");
-    expect(main.index.nodes.get(2)).toBe(main.domNodes.find((node) => node.backendNodeId === 2));
-    expect(facts.finishedAt).toBeGreaterThanOrEqual(facts.startedAt);
-  });
-
-  it("does not retry failed or missing documents and retains valid AX-only semantics", async () => {
-    const { cdp, logs } = fixture({
-      fail: "remote:DOMSnapshot.captureSnapshot",
-      omitDocument: "same",
-    });
-    const facts = await captureObservationFacts(cdp, 4);
-    const remote = facts.documents.find((doc) => doc.frame.frameId === "remote")!;
-    expect(remote.domNodes).toHaveLength(0);
-    expect(remote.axNodes).toHaveLength(1);
-    expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(2);
-    expect(facts.issues).toContainEqual(
-      expect.objectContaining({ frameId: "same", stage: "dom", reason: "capture-unavailable" }),
-    );
-    expect(facts.issues).toContainEqual(
-      expect.objectContaining({ target: { tabId: 4, sessionId: "remote" }, stage: "dom" }),
-    );
-  });
-
-  it("excludes overlay AX in its own document without excluding equal IDs elsewhere", async () => {
-    const facts = await captureObservationFacts(fixture({ overlay: "remote" }).cdp, 4);
-    const { documents } = semanticCapture(facts);
-    const graph = buildSemanticGraph({
-      documents,
-      viewport: facts.viewport,
-      rootFrameId: facts.rootFrameId,
-    });
-    expect(
-      [...graph.nodes.values()].find(
-        (node) => node.frameId === "remote" && node.backendNodeId === 2,
-      )?.excluded,
-    ).toBe(true);
-    expect(
-      [...graph.nodes.values()].find((node) => node.frameId === "main" && node.backendNodeId === 2)
-        ?.excluded,
-    ).toBe(false);
-  });
-
-  it.each([
-    "cancel",
-    "worker-abort",
-  ] as const)("joins target cleanup and stops claiming targets after %s", async (mode) => {
-    const frames = Array.from({ length: 5 }, (_, i) => ({
-      frameId: `f${i}`,
-      target: { tabId: 4, ...(i ? { sessionId: `s${i}` } : {}) },
-    }));
-    const { cdp } = fixture({ frames });
-    const original = cdp.sendToTarget!;
-    const pending = new Map<string, { resolve: () => void; reject: (error: Error) => void }>();
-    const calls: Array<{ target: string; method: string }> = [];
-    let release: (() => void) | undefined;
-    let released = false;
-    const send: NonNullable<CdpRunner["sendToTarget"]> = async <T>(
-      target: CdpTarget,
-      method: string,
-      params?: object,
-    ) => {
-      calls.push({ target: target.sessionId ?? "main", method });
-      if (method === "DOMSnapshot.captureSnapshot" && target.sessionId) {
-        await new Promise<void>((resolve, reject) =>
-          pending.set(target.sessionId!, { resolve, reject }),
-        );
-      }
-      if (method === "Runtime.releaseObjectGroup") {
-        await new Promise<void>((resolve) => {
-          release = resolve;
-        });
-        released = true;
-      }
-      const result = await original<T>(target, method, params);
-      if (method === "DOMSnapshot.captureSnapshot" && !target.sessionId)
-        (result as { strings: string[] }).strings[2] = "input";
-      return result;
-    };
-    cdp.sendToTarget = send;
-    cdp.send = (tabId, method, params) => send({ tabId }, method, params);
-    const controller = new AbortController();
-    let settled = false;
-    const capture = captureObservationFacts(cdp, 4, controller.signal);
-    const rejected = expect(capture).rejects.toMatchObject({ name: "AbortError" });
-    void capture.then(
-      () => {
-        settled = true;
-      },
-      () => {
-        settled = true;
-      },
-    );
-    await vi.waitFor(() => {
-      expect(pending.size).toBe(3);
-      expect(release).toBeDefined();
-    });
-    if (mode === "cancel") controller.abort();
-    // Cancellation may race with an ordinary transport rejection. Without an
-    // external signal, an escaping AbortError still terminates the worker pool.
-    pending
-      .get("s1")!
-      .reject(
-        mode === "cancel"
-          ? new Error("transport closed")
-          : new DOMException("target aborted", "AbortError"),
-      );
-    pending.get("s2")!.resolve();
-    pending.get("s3")!.resolve();
-    await vi.waitFor(() => {
-      if (mode === "worker-abort")
-        expect(
-          calls.some(
-            (call) => call.target === "s3" && call.method === "Accessibility.getFullAXTree",
-          ),
-        ).toBe(true);
-      else
-        expect(
-          calls.some(
-            (call) => call.target === "s3" && call.method === "DOMSnapshot.captureSnapshot",
-          ),
-        ).toBe(true);
-    });
-    // Allow worker rejection and the outer promise chain to run while cleanup
-    // is deliberately held. The old fail-fast pool settles here.
-    await new Promise((resolve) => setTimeout(resolve, 0));
-    expect(settled).toBe(false);
-    expect(released).toBe(false);
-    expect(calls.some((call) => call.target === "s4")).toBe(false);
-    if (mode === "cancel")
-      expect(
-        calls.some(
-          (call) => call.method === "Accessibility.enable" || call.method === "DOM.getDocument",
-        ),
-      ).toBe(false);
-    release!();
-    await rejected;
-    expect(released).toBe(true);
-    expect(calls.some((call) => call.target === "s4")).toBe(false);
-  });
-
-  it("bounds collection across many targets and stops scheduling after cancellation", async () => {
-    const frames = Array.from({ length: 12 }, (_, i) => ({
-      frameId: `f${i}`,
-      target: { tabId: 4, ...(i ? { sessionId: `s${i}` } : {}) },
-    }));
-    const { cdp } = fixture({ frames });
-    let active = 0,
-      peak = 0;
-    const original = cdp.sendToTarget!;
-    const send: NonNullable<CdpRunner["sendToTarget"]> = async (target, method, params) => {
-      active++;
-      peak = Math.max(peak, active);
-      try {
-        await new Promise((resolve) => setTimeout(resolve, 1));
-        return await original(target, method, params);
-      } finally {
-        active--;
-      }
-    };
-    cdp.sendToTarget = send;
-    cdp.send = (tabId, method, params) => send({ tabId }, method, params);
-    await captureObservationFacts(cdp, 4);
-    // This fixture has no frame edges, so no concurrent owner requests.
-    expect(peak).toBeLessThanOrEqual(4);
-    expect(peak).toBeGreaterThan(1);
-    const controller = new AbortController();
-    controller.abort();
-    await expect(captureObservationFacts(cdp, 4, controller.signal)).rejects.toMatchObject({
-      name: "AbortError",
-    });
-    expect(active).toBe(0);
-  });
-});
-
-function childSnapshot(frameId: string, backendNodeId: number) {
-  const strings = [frameId, "body", "button", "static", "auto", "pointer"];
-  return {
-    strings,
-    documents: [
-      {
-        frameId,
-        nodes: {
-          parentIndex: [-1, 0],
-          nodeName: [1, 2],
-          backendNodeId: [backendNodeId - 1, backendNodeId],
-          attributes: [[], []],
-        },
-        layout: {
-          nodeIndex: [0, 1],
-          styles: [
-            [3, 4, 4],
-            [3, 4, 5],
-          ],
-          bounds: [
-            [0, 0, 300, 200],
-            [10, 20, 100, 40],
-          ],
-          paintOrders: [0, 1],
-        },
-      },
-    ],
-  };
-}
-
-describe("OOPIF capture", () => {
-  it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
-    const sendToTarget = vi.fn(async (target, method) => {
-      if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
-      }
-      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
-      if (method === "DOMSnapshot.captureSnapshot") {
-        return target.sessionId === "left-session"
-          ? childSnapshot("left", 101)
-          : childSnapshot("right", 201);
-      }
-      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-      throw new Error(`unexpected ${method}`);
-    });
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method, params) => {
-        if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("main", 1);
-        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-        if (method === "DOM.getBoxModel") {
-          const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
-          const x = backendNodeId === 10 ? 50 : 500;
-          return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-        }
-        throw new Error(`unexpected root ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "left",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "left-session" },
-          },
-          {
-            frameId: "right",
-            parentFrameId: "main",
-            ownerBackendNodeId: 20,
-            target: { tabId: 4, sessionId: "right-session" },
-          },
-        ],
-      })),
-    };
-
-    const { documents: trees } = semanticCapture(await captureObservationFacts(cdp, 4));
-
-    expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
-    expect(
-      trees
-        .find((doc) => doc.frameId === "left")
-        ?.domNodes?.find((node) => node.backendNodeId === 101)?.rect,
-    ).toEqual({ x: 60, y: 120, w: 100, h: 40 });
-    expect(
-      trees
-        .find((doc) => doc.frameId === "right")
-        ?.domNodes?.find((node) => node.backendNodeId === 201)?.rect,
-    ).toEqual({ x: 510, y: 120, w: 100, h: 40 });
-    expect(
-      new Map(
-        trees
-          .filter((doc) => doc.ownerBackendNodeId !== undefined)
-          .map((doc) => [doc.frameId, doc.ownerBackendNodeId]),
-      ),
-    ).toEqual(
-      new Map([
-        ["left", 10],
-        ["right", 20],
-      ]),
-    );
-    expect(
-      new Map(
-        trees.filter((doc) => doc.parentFrameId).map((doc) => [doc.frameId, doc.parentFrameId]),
-      ),
-    ).toEqual(
-      new Map([
-        ["left", "main"],
-        ["right", "main"],
-      ]),
-    );
-  });
-
-  it("retains nested owner failures when merging a captured OOPIF", async () => {
-    const child = childSnapshot("child", 101);
-    const nested = childSnapshot("nested", 201);
-    const document = child.documents[0];
-    const snapshot = {
-      strings: child.strings,
-      documents: [
-        {
-          ...document,
-          nodes: { ...document.nodes, contentDocumentIndex: { index: [1], value: [1] } },
-        },
-        nested.documents[0],
-      ],
-    };
-    const reply = async (_target: unknown, method: string) => {
-      if (method === "Page.getLayoutMetrics")
-        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200 } };
-      if (method === "DOMSnapshot.captureSnapshot")
-        return typeof _target === "number" ? childSnapshot("main", 11) : snapshot;
-      if (method === "DOM.getBoxModel")
-        return { model: { content: [50, 100, 350, 100, 350, 300, 50, 300] } };
-      if (method === "DOM.resolveNode") throw new Error("nested owner replaced");
-      return {};
-    };
-    const cdp: CdpRunner = {
-      send: vi.fn(reply) as CdpRunner["send"],
-      sendToTarget: vi.fn(reply) as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "nested",
-            parentFrameId: "child",
-            ownerBackendNodeId: 101,
-            target: { tabId: 4, sessionId: "child-session" },
-          },
-          {
-            frameId: "child",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "child-session" },
-          },
-        ],
-      })),
-    };
-    const captured = await captureObservationFacts(cdp, 4);
-    expect(
-      captured.issues
-        .filter((issue) => issue.projectionIssue)
-        .map((issue) => issue.projectionIssue),
-    ).toEqual([
-      {
-        status: "unavailable",
-        source: { target: { tabId: 4, sessionId: "child-session" }, frameId: "nested" },
-        ownerBackendNodeId: 101,
-      },
-    ]);
-    expect(
-      captured.documents.find((doc) => doc.frame.frameId === "nested")?.domNodes[1],
-    ).toMatchObject({
-      rect: null,
-      localRect: { x: 10, y: 20, w: 100, h: 40 },
-    });
-  });
-
-  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method) => {
-        if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("main", 1);
-        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-        }
-        throw new Error(`unexpected root ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
-        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
-        if (method === "Accessibility.getFullAXTree") {
-          return {
-            nodes: [
-              {
-                nodeId: "button",
-                backendDOMNodeId: 101,
-                role: { type: "role", value: "button" },
-                name: { type: "computedString", value: "Continue" },
-              },
-            ],
-          };
-        }
-        throw new Error(`unexpected ${method}`);
-      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "child",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "child-session" },
-          },
-        ],
-      })),
-    };
-
-    const { documents } = semanticCapture(await captureObservationFacts(cdp, 4));
-    const childDocument = documents.find((document) => document.frameId === "child");
-
-    expect(childDocument?.axNodes).toEqual([
-      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
-    ]);
-    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
-      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
-    );
-  });
-});
-
-// Six sibling frames and one nested frame exercise scheduling through the real capture entry.
-function siblingCaptureFixture(
-  beforeReply: (method: string, params: Record<string, unknown>) => Promise<void> = async () => {},
-) {
-  const document = (id: number, owners: number[], childIndexes: number[]) => ({
-    frameId: `frame-${id}`,
-    nodes: {
-      parentIndex: [-1, ...owners.map(() => 0)],
-      nodeName: [0, ...owners.map(() => 1)],
-      backendNodeId: [1000 + id, ...owners],
-      attributes: [[], ...owners.map(() => [])],
-      contentDocumentIndex: { index: owners.map((_, i) => i + 1), value: childIndexes },
-    },
-    layout: {
-      nodeIndex: [0, ...owners.map((_, i) => i + 1)],
-      bounds: [[0, 0, 200, 100], ...owners.map(() => [0, 0, 200, 100])],
-    },
-  });
-  const snapshot = {
-    strings: ["body", "iframe"],
-    documents: [
-      document(0, [100, 101, 102, 103, 104, 105], [1, 2, 3, 4, 5, 6]),
-      document(1, [200], [7]),
-      ...Array.from({ length: 6 }, (_, i) => document(i + 2, [], [])),
-    ],
-  };
-  let active = 0;
-  let peak = 0;
-  const send = vi.fn(async (_tabId: number, method: string, params: object = {}) => {
-    const args = params as Record<string, unknown>;
-    active++;
-    peak = Math.max(peak, active);
-    try {
-      await beforeReply(method, args);
-      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
-      if (method === "Page.getLayoutMetrics")
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-      if (method === "DOM.getBoxModel")
-        return { model: { content: [0, 0, 200, 0, 200, 100, 0, 100] } };
-      if (method === "DOM.resolveNode") return { object: { objectId: String(args.backendNodeId) } };
-      if (method === "Runtime.callFunctionOn")
-        return { result: { value: { width: 200, height: 100 } } };
-      return {};
-    } finally {
-      active--;
-    }
-  });
-  return {
-    snapshot,
-    cdp: { send: send as CdpRunner["send"] },
-    send,
-    peak: () => peak,
-    active: () => active,
-    measured: () =>
-      send.mock.calls
-        .filter(([, method]) => method === "DOM.getBoxModel")
-        .map(([, , params]) => (params as { backendNodeId: number }).backendNodeId),
-  };
-}
-
-describe("snapshot document provenance", () => {
-  it.each([
-    "new-child",
-    "new-root",
-    "stale-owner",
-  ])("retains current snapshot evidence with %s graph data", async (mode) => {
-    const f = siblingCaptureFixture();
-    const cdp: CdpRunner = {
-      ...f.cdp,
-      getFrameGraph: async () => ({
-        rootFrameId: mode === "new-root" ? "old-root" : "frame-0",
-        frames: [
-          { frameId: mode === "new-root" ? "old-root" : "frame-0", target: { tabId: 4 } },
-          ...(mode === "stale-owner"
-            ? [
-                {
-                  frameId: "frame-1",
-                  parentFrameId: "frame-0",
-                  ownerBackendNodeId: 999,
-                  target: { tabId: 4 },
-                },
-              ]
-            : []),
-        ],
-      }),
-    };
-    const facts = await captureObservationFacts(cdp, 4);
-    expect(facts.rootFrameId).toBe("frame-0");
-    expect(facts.documents.find((doc) => doc.frame.frameId === "frame-1")).toMatchObject({
-      frame: { ownerBackendNodeId: 100 },
-      domNodes: [
-        expect.objectContaining({ rect: { x: 0, y: 0, w: 200, h: 100 } }),
-        expect.anything(),
-      ],
-    });
-    expect(
-      facts.documents.find((doc) => doc.frame.frameId === "frame-7")?.domNodes[0].rect,
-    ).not.toBeNull();
-    expect(f.measured()).not.toContain(999);
-    expect(
-      f.send.mock.calls.filter(([, method]) => method === "DOMSnapshot.captureSnapshot"),
-    ).toHaveLength(1);
-    expect(
-      f.send.mock.calls.some(
-        ([, method, params]) =>
-          method === "Accessibility.getFullAXTree" &&
-          (params as { frameId?: string }).frameId === "frame-7",
-      ),
-    ).toBe(true);
-  });
-
-  it("uses snapshot URLs before graph URLs and limits the caller URL to the root", async () => {
-    const f = siblingCaptureFixture();
-    f.snapshot.strings.push("https://current.test/page", "https://child.test/page");
-    Object.assign(f.snapshot.documents[0], { documentURL: 2 });
-    Object.assign(f.snapshot.documents[1], { documentURL: 3 });
-    const facts = await captureObservationFacts(
-      {
-        ...f.cdp,
-        getFrameGraph: async () => ({
-          rootFrameId: "frame-0",
-          frames: [{ frameId: "frame-0", target: { tabId: 4 }, url: "https://old.test/" }],
-        }),
-      },
-      4,
-      undefined,
-      "https://caller.test/",
-    );
-    expect(facts.documents.find((doc) => doc.frame.frameId === "frame-0")?.frame.url).toBe(
-      "https://current.test/page",
-    );
-    expect(facts.documents.find((doc) => doc.frame.frameId === "frame-1")?.frame.url).toBe(
-      "https://child.test/page",
-    );
-    expect(
-      facts.documents.find((doc) => doc.frame.frameId === "frame-2")?.frame.url,
-    ).toBeUndefined();
-  });
-
-  it("accepts a migrated snapshot claim without merging AX from the old target", async () => {
-    const f = siblingCaptureFixture();
-    const cdp: CdpRunner = {
-      ...f.cdp,
-      getFrameGraph: async () => ({
-        rootFrameId: "frame-0",
-        frames: [
-          { frameId: "frame-0", target: { tabId: 4 } },
-          {
-            frameId: "frame-1",
-            parentFrameId: "frame-0",
-            ownerBackendNodeId: 100,
-            target: { tabId: 4, sessionId: "old" },
-          },
-        ],
-      }),
-      sendToTarget: async <T>(_target: CdpTarget, method: string): Promise<T> =>
-        (method === "Accessibility.getFullAXTree"
-          ? { nodes: [{ nodeId: "stale", role: { value: "button" }, name: { value: "stale" } }] }
-          : {}) as T,
-    };
-    const facts = await captureObservationFacts(cdp, 4);
-    const current = facts.documents.find((doc) => doc.frame.frameId === "frame-1");
-    expect(current?.frame.target).toEqual({ tabId: 4 });
-    expect(current?.domNodes.length).toBeGreaterThan(0);
-    expect(current?.axNodes).toEqual([]);
-  });
-
-  it.each([
-    0, 1,
-  ])("rejects duplicate snapshot frame identity at document %i without overwriting", async (index) => {
-    const f = siblingCaptureFixture();
-    f.snapshot.documents.push(f.snapshot.documents[index]);
-    if (index === 0) {
-      await expect(captureObservationFacts(f.cdp, 4)).rejects.toThrow(
-        "root document ownership is ambiguous",
-      );
-    } else {
-      const facts = await captureObservationFacts(f.cdp, 4);
-      expect(facts.documents.map((doc) => doc.frame.frameId)).not.toContain("frame-1");
-      expect(facts.documents.map((doc) => doc.frame.frameId)).not.toContain("frame-7");
-      expect(
-        facts.documents.find((doc) => doc.frame.frameId === "frame-2")?.domNodes.length,
-      ).toBeGreaterThan(0);
-    }
-  });
-
-  it("retains the caller URL in the root AX-only fallback", async () => {
-    const cdp: CdpRunner = {
-      getFrameGraph: async () => {
-        throw new Error("no graph");
-      },
-      send: async <T>(_tabId: number, method: string): Promise<T> => {
-        if (method === "DOMSnapshot.captureSnapshot") throw new Error("no snapshot");
-        return (
-          method === "Accessibility.getFullAXTree"
-            ? { nodes: [{ nodeId: "root", role: { value: "RootWebArea" } }] }
-            : {}
-        ) as T;
-      },
-    };
-    const facts = await captureObservationFacts(cdp, 4, undefined, "https://page.test/");
-    expect(facts.documents[0].frame.url).toBe("https://page.test/");
-    expect(facts.documents[0].axNodes).toHaveLength(1);
-  });
-
-  it("retains disconnected document data without inventing top-level geometry", async () => {
-    const f = siblingCaptureFixture();
-    f.snapshot.documents[0].nodes.contentDocumentIndex = { index: [], value: [] };
-    const facts = await captureObservationFacts(f.cdp, 4);
-    expect(
-      facts.documents.find((doc) => doc.frame.frameId === "frame-1")?.domNodes[0],
-    ).toMatchObject({ rect: null, localRect: { x: 0, y: 0, w: 200, h: 100 } });
-    expect(f.measured()).toEqual([]);
-    expect(facts.issues).toContainEqual(
-      expect.objectContaining({ frameId: "frame-1", stage: "ownership" }),
-    );
-  });
-
-  it.each([
-    false,
-    true,
-  ])("isolates competing target claims independent of batch order %s", async (reverse) => {
-    const f = siblingCaptureFixture();
-    const remote = {
-      frameId: "frame-1",
-      parentFrameId: "frame-0",
-      ownerBackendNodeId: 100,
-      target: { tabId: 4, sessionId: "remote" },
-    };
-    const main = { frameId: "frame-0", target: { tabId: 4 } };
-    const cdp: CdpRunner = {
-      ...f.cdp,
-      getFrameGraph: async () => ({
-        rootFrameId: "frame-0",
-        frames: reverse ? [remote, main] : [main, remote],
-      }),
-      sendToTarget: async <T>(_target: CdpTarget, method: string): Promise<T> =>
-        (method === "DOMSnapshot.captureSnapshot"
-          ? { ...f.snapshot, documents: [f.snapshot.documents[1]] }
-          : method === "Page.getLayoutMetrics"
-            ? { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } }
-            : {}) as T,
-    };
-    const facts = await captureObservationFacts(cdp, 4);
-    expect(facts.documents.map((doc) => doc.frame.frameId)).not.toContain("frame-1");
-    expect(facts.documents.map((doc) => doc.frame.frameId)).not.toContain("frame-7");
-    expect(
-      facts.documents.find((doc) => doc.frame.frameId === "frame-2")?.domNodes[0].rect,
-    ).not.toBeNull();
-    expect(facts.issues).toContainEqual(
-      expect.objectContaining({ frameId: "frame-1", stage: "ownership" }),
-    );
-  });
-});
-
-describe("sibling frame measurement scheduling", () => {
-  it("bounds concurrent reads, fills free slots and preserves breadth-first output despite reordered replies", async () => {
-    const pending = new Map<number, () => void>();
-    const fixture = siblingCaptureFixture(async (method, params) => {
-      if (method === "DOM.getBoxModel" && Number(params.backendNodeId) < 200)
-        await new Promise<void>((resolve) => pending.set(Number(params.backendNodeId), resolve));
-    });
-    const capture = captureObservationFacts(fixture.cdp, 4);
-    await vi.waitFor(() => expect(pending.size).toBe(4));
-    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
-    pending.get(103)!();
-    await vi.waitFor(() => expect(pending.has(104)).toBe(true));
-    pending.get(104)!();
-    await vi.waitFor(() => expect(pending.has(105)).toBe(true));
-    expect(fixture.measured()).not.toContain(200);
-    for (const id of [105, 102, 101, 100]) pending.get(id)!();
-    const captured = await capture;
-    expect(
-      captured.issues
-        .filter((issue) => issue.stage === "geometry")
-        .map((issue) => issue.projectionIssue),
-    ).toEqual([]);
-    expect(fixture.peak()).toBe(4);
-    expect(fixture.active()).toBe(0);
-    expect(fixture.measured()).toEqual([100, 101, 102, 103, 104, 105, 200]);
-    expect(captured.documents.map((doc) => doc.frame.frameId)).toEqual(
-      Array.from({ length: 8 }, (_, i) => `frame-${i}`),
-    );
-    expect(
-      captured.documents.find((doc) => doc.frame.frameId === "frame-7")?.domNodes[0].rect,
-    ).toEqual({ x: 0, y: 0, w: 200, h: 100 });
-    for (const method of [
-      "DOM.getBoxModel",
-      "DOM.resolveNode",
-      "Runtime.callFunctionOn",
-      "Runtime.releaseObject",
-    ])
-      expect(fixture.send.mock.calls.filter(([, name]) => name === method)).toHaveLength(7);
-  });
-
-  it("does not measure descendants of a failed owner and retains sibling geometry and local nodes", async () => {
-    const fixture = siblingCaptureFixture(async (method, params) => {
-      if (method === "DOM.resolveNode" && params.backendNodeId === 100)
-        throw new Error("owner replaced");
-    });
-    const captured = await captureObservationFacts(fixture.cdp, 4);
-    expect(
-      captured.issues
-        .filter((issue) => issue.stage === "geometry")
-        .map((issue) => issue.projectionIssue),
-    ).toEqual([
-      {
-        status: "unavailable",
-        source: { target: { tabId: 4 }, frameId: "frame-1" },
-        ownerBackendNodeId: 100,
-      },
-      {
-        status: "blocked",
-        source: { target: { tabId: 4 }, frameId: "frame-7" },
-        cause: captured.issues.find((issue) => issue.frameId === "frame-1")?.projectionIssue,
-      },
-    ]);
-    expect(fixture.measured()).not.toContain(200);
-    expect(
-      captured.documents.find((doc) => doc.frame.frameId === "frame-7")?.domNodes[0],
-    ).toMatchObject({
-      tag: "body",
-      rect: null,
-      localRect: { x: 0, y: 0, w: 200, h: 100 },
-    });
-    expect(
-      captured.documents.find((doc) => doc.frame.frameId === "frame-2")?.domNodes[0].rect,
-    ).toEqual({ x: 0, y: 0, w: 200, h: 100 });
-    expect(captured.documents.map((doc) => doc.frame.frameId)).toEqual(
-      Array.from({ length: 8 }, (_, i) => `frame-${i}`),
-    );
-  });
-
-  it("stops scheduling on cancellation and waits for resolved objects to be released", async () => {
-    const controller = new AbortController();
-    const resolutions = new Map<string, () => void>();
-    const releases = new Map<string, () => void>();
-    const fixture = siblingCaptureFixture(async (method, params) => {
-      if (method === "DOM.resolveNode")
-        await new Promise<void>((resolve) =>
-          resolutions.set(String(params.backendNodeId), resolve),
-        );
-      if (method === "Runtime.releaseObject")
-        await new Promise<void>((resolve) => releases.set(String(params.objectId), resolve));
-    });
-    let settled = false;
-    const capture = captureObservationFacts(fixture.cdp, 4, controller.signal);
-    const rejected = expect(capture).rejects.toMatchObject({ name: "AbortError" });
-    void capture.then(
-      () => {
-        settled = true;
-      },
-      () => {
-        settled = true;
-      },
-    );
-    await vi.waitFor(() => expect(resolutions.size).toBe(4));
-    controller.abort();
-    for (const resolve of resolutions.values()) resolve();
-    await vi.waitFor(() => expect(releases.size).toBe(4));
-    expect(settled).toBe(false);
-    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
-    for (const release of releases.values()) release();
-    await rejected;
-    expect(fixture.active()).toBe(0);
-    expect(fixture.send.mock.calls.some(([, method]) => method === "Runtime.callFunctionOn")).toBe(
-      false,
-    );
-  });
-});

apps/extension/src/tools/vom/__tests__/capture.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
-import { collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
-import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
+import type { CdpRunner } from "../../shared";
+import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
 // fixed full-screen overlay div carrying a password input.
@@ -27,7 +27,6 @@ function fakeSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2],
           nodeType: [1, 1, 1, 1],
@@ -75,7 +74,6 @@ function hoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1],
           nodeType: [1, 1, 1],
@@ -120,7 +118,6 @@ function twoHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 1],
           nodeType: [1, 1, 1, 1],
@@ -174,7 +171,6 @@ function nestedHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2, 3],
           nodeType: [1, 1, 1, 1, 1],
@@ -215,7 +211,11 @@ function makeCdp(snapshot: unknown) {
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") return snapshot;
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "Runtime.evaluate") {
         return {
@@ -248,11 +248,13 @@ function makeCdp(snapshot: unknown) {
   };
 }
 
-describe("snapshot capture and hover", () => {
+describe("captureViewModel", () => {
   it("parses nodes, attrs, rects, paint order and styles", async () => {
-    const { nodes, viewport } = semanticCapture(
-      await captureObservationFacts(makeCdp(fakeSnapshotReply()), 4),
-    ).captured;
+    const { nodes, viewport, iframeNodes } = await captureViewModel(
+      makeCdp(fakeSnapshotReply()),
+      4,
+    );
+    expect(iframeNodes.size).toBe(0);
     expect(viewport).toEqual({ width: 1000, height: 800 });
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div).toMatchObject({ tag: "div", position: "fixed", parentBackendNodeId: 11 });
@@ -264,11 +266,35 @@ describe("snapshot capture and hover", () => {
 
   it("never hovers the page while capturing", async () => {
     const cdp = makeCdp(fakeSnapshotReply());
-    semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    await captureViewModel(cdp, 4);
 
     expect(cdp.send).not.toHaveBeenCalledWith(4, "Input.dispatchMouseEvent", expect.anything());
   });
 
+  it("batch-enriches form controls without per-node object resolution", async () => {
+    const cdp = makeCdp(fakeSnapshotReply());
+    const result = await captureViewModel(cdp, 4);
+    const input = result.nodes.find((node) => node.backendNodeId === 13);
+
+    expect(input).toMatchObject({
+      formState: "filled",
+      formPlaceholder: "secret",
+      attrs: { type: "password" },
+    });
+    expect(input?.formValue).toBeUndefined();
+    expect(input?.formDefaultValue).toBeUndefined();
+    expect(cdp.send).toHaveBeenCalledWith(
+      4,
+      "Runtime.evaluate",
+      expect.objectContaining({
+        serializationOptions: expect.objectContaining({ serialization: "deep" }),
+      }),
+    );
+    expect(cdp.send).toHaveBeenCalledWith(4, "Runtime.releaseObjectGroup", expect.anything());
+    expect(cdp.send).not.toHaveBeenCalledWith(4, "DOM.resolveNode", expect.anything());
+    expect(cdp.send).not.toHaveBeenCalledWith(4, "Runtime.callFunctionOn", expect.anything());
+  });
+
   it("runs hover surface probes when explicitly enabled", async () => {
     let hoverStateCalls = 0;
     const cdp = {
@@ -277,6 +303,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return hoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -308,7 +336,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -340,6 +368,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return twoHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -368,7 +398,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -388,6 +418,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return nestedHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -413,7 +445,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(hoverMoves).toBe(1);
@@ -445,7 +477,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -476,7 +507,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
     const ids = nodes.map((n) => n.backendNodeId);
     // Real page nodes survive.
     expect(ids).toContain(12);
@@ -507,7 +538,9 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
+          frameId: "main",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -538,10 +571,12 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { excludedBackendNodeIds, frameExcludedBackendNodeIds } = await captureViewModel(
+      makeCdp(snapshot),
+      4,
+    );
     expect(excludedBackendNodeIds).toEqual(new Set([13, 14, 15]));
+    expect(frameExcludedBackendNodeIds?.get("main")).toEqual(excludedBackendNodeIds);
   });
 
   it("excludes overlay host matched by tag name only", async () => {
@@ -561,7 +596,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i(OVERLAY_HOST_NAME)],
@@ -584,9 +618,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -609,7 +641,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -632,9 +663,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -657,7 +686,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -680,7 +708,7 @@ describe("snapshot capture and hover", () => {
         },
       ],
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.find((n) => n.backendNodeId === 12)?.cursor).toBe("pointer");
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
@@ -692,7 +720,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 1, 1],
             nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
@@ -719,7 +746,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
 
     expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
     expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
@@ -733,26 +760,66 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return fakeSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 200 },
           };
         }
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const { nodes } = await captureViewModel(cdp, 4);
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div?.localRect?.y).toBe(-200);
     expect(div?.rect).toMatchObject({ y: 0, h: 600 });
   });
 
-  it("keeps CSS snapshot bounds independent of legacy metrics ratio", async () => {
+  it("normalizes snapshot-owned scroll before using a stale CSS metrics fallback", async () => {
+    const snapshot = {
+      strings: ["html", "button"],
+      documents: [
+        {
+          frameId: "root",
+          scrollOffsetX: 40,
+          scrollOffsetY: 200,
+          nodes: {
+            parentIndex: [-1, 0],
+            nodeName: [0, 1],
+            backendNodeId: [10, 11],
+            attributes: [[], []],
+          },
+          layout: { nodeIndex: [1], bounds: [[200, 800, 240, 80]] },
+        },
+      ],
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tab: number, method: string) => {
+        if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+        if (method === "Page.getLayoutMetrics")
+          return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 999, pageY: 999 },
+          };
+        return {};
+      }) as CdpRunner["send"],
+    };
+    const captured = await captureViewModel(cdp, 4);
+    expect(captured.nodes.find((node) => node.backendNodeId === 11)).toMatchObject({
+      localRect: { x: 80, y: 300, w: 120, h: 40 },
+      rect: { x: 80, y: 300, w: 120, h: 40 },
+      rendered: true,
+    });
+    expect(captured.frameGeometryIssues).toEqual([]);
+  });
+
+  it("normalizes raw snapshot bounds before viewport clipping", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -780,6 +847,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -787,7 +856,7 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const { nodes } = await captureViewModel(cdp, 4);
     expect(nodes.find((n) => n.backendNodeId === 12)?.rect).toEqual({
       x: 0,
       y: 0,
@@ -797,8 +866,8 @@ describe("snapshot capture and hover", () => {
     expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
       x: 0,
       y: 0,
-      w: 2000,
-      h: 1600,
+      w: 1000,
+      h: 800,
     });
   });
 
@@ -823,7 +892,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -856,13 +924,15 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const { nodes } = await captureViewModel(cdp, 4);
     const btn = nodes.find((n) => n.backendNodeId === 12);
     expect(btn?.textContent).toBe("登录");
     const link = nodes.find((n) => n.backendNodeId === 14);
@@ -872,7 +942,7 @@ describe("snapshot capture and hover", () => {
     expect(body?.textContent).toBeUndefined();
   });
 
-  it("retains explicit iframe document ownership and projected nodes", async () => {
+  it("parses iframe sub-documents and returns iframeNodes keyed by iframe backendNodeId", async () => {
     const S = [
       "html",
       "body",
@@ -946,6 +1016,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -958,21 +1030,30 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const facts = await captureObservationFacts(cdp, 4);
-    const root = facts.documents.find((doc) => doc.frame.frameId === "main-frame")!;
-    const child = facts.documents.find((doc) => doc.frame.frameId === "child-frame")!;
-    expect(facts.documents).toHaveLength(2);
-    expect(root.domNodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
-    const subNodes = child.domNodes;
+    const {
+      nodes,
+      iframeNodes,
+      frameNodes,
+      frameOwnerBackendNodeIds,
+      frameParentIds,
+      rootFrameId,
+    } = await captureViewModel(cdp, 4);
+    // Main frame has 4 nodes; iframe is included
+    expect(nodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
+    // iframeNodes keyed by the <iframe> element's backendNodeId=13
+    expect(iframeNodes.size).toBe(1);
+    expect(iframeNodes.has(13)).toBe(true);
+    const subNodes = iframeNodes.get(13)!;
     const input = subNodes.find((n) => n.backendNodeId === 101);
     expect(input?.tag).toBe("input");
     expect(input?.attrs.type).toBe("text");
     expect(input?.ownerFrameBackendNodeId).toBe(13);
     expect(input?.localRect).toEqual({ x: 0, y: 0, w: 200, h: 40 });
     expect(input?.rect).toEqual({ x: 100, y: 300, w: 200, h: 40 });
-    expect(facts.rootFrameId).toBe("main-frame");
-    expect(child.frame.ownerBackendNodeId).toBe(13);
-    expect(child.frame.parentFrameId).toBe("main-frame");
+    expect(rootFrameId).toBe("main-frame");
+    expect(frameNodes?.get("child-frame")).toBe(subNodes);
+    expect(frameOwnerBackendNodeIds?.get("child-frame")).toBe(13);
+    expect(frameParentIds?.get("child-frame")).toBe("main-frame");
   });
 
   it("projects iframe documents independently of owner snapshot geometry", async () => {
@@ -993,7 +1074,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1011,7 +1091,6 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "child",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1035,6 +1114,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -1048,10 +1129,8 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const { documents } = await captureObservationFacts(cdp, 4);
-    const input = documents
-      .find((doc) => doc.frame.frameId === "child")
-      ?.domNodes?.find((n) => n.backendNodeId === 101);
+    const { iframeNodes } = await captureViewModel(cdp, 4);
+    const input = iframeNodes.get(13)?.find((n) => n.backendNodeId === 101);
 
     expect(input?.localRect).toEqual({ x: 20, y: 20, w: 120, h: 60 });
     expect(input?.rect).toEqual({ x: 120, y: 320, w: 120, h: 60 });
@@ -1075,7 +1154,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1097,7 +1175,8 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "child",
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1119,7 +1198,8 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "nested",
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           nodes: {
             parentIndex: [-1, 0],
             nodeName: [i("body"), i("input")],
@@ -1146,6 +1226,8 @@ describe("snapshot capture and hover", () => {
           if (method === "DOMSnapshot.captureSnapshot") return snapshot;
           if (method === "Page.getLayoutMetrics") {
             return {
+              visualViewport: { clientWidth: 1000 },
+              cssVisualViewport: { clientWidth: 1000 },
               cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
             };
           }
@@ -1175,13 +1257,9 @@ describe("snapshot capture and hover", () => {
       ) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const { documents } = await captureObservationFacts(cdp, 4);
-    const nestedIframe = documents
-      .find((doc) => doc.frame.frameId === "child")
-      ?.domNodes?.find((n) => n.backendNodeId === 23);
-    const input = documents
-      .find((doc) => doc.frame.frameId === "nested")
-      ?.domNodes?.find((n) => n.backendNodeId === 31);
+    const { iframeNodes } = await captureViewModel(cdp, 4);
+    const nestedIframe = iframeNodes.get(13)?.find((n) => n.backendNodeId === 23);
+    const input = iframeNodes.get(23)?.find((n) => n.backendNodeId === 31);
 
     expect(nestedIframe?.localRect).toEqual({ x: 5, y: 6, w: 100, h: 80 });
     expect(nestedIframe?.rect).toEqual({ x: 15, y: 26, w: 100, h: 80 });
@@ -1197,7 +1275,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -1225,6 +1302,8 @@ describe("snapshot capture and hover", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 100 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -1232,8 +1311,8 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
+    const { nodes } = await captureViewModel(cdp, 4);
+    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
   });
 
   it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {
@@ -1258,3 +1337,200 @@ describe("snapshot capture and hover", () => {
     expect(excluded).toEqual(new Set([200, 201, 202]));
   });
 });
+
+// Six sibling frames and one nested frame exercise scheduling through the real capture entry.
+function siblingCaptureFixture(
+  beforeReply: (method: string, params: Record<string, unknown>) => Promise<void> = async () => {},
+) {
+  const document = (id: number, owners: number[], childIndexes: number[]) => ({
+    scrollOffsetX: 0,
+    scrollOffsetY: 0,
+    frameId: `frame-${id}`,
+    nodes: {
+      parentIndex: [-1, ...owners.map(() => 0)],
+      nodeName: [0, ...owners.map(() => 1)],
+      backendNodeId: [1000 + id, ...owners],
+      attributes: [[], ...owners.map(() => [])],
+      contentDocumentIndex: { index: owners.map((_, i) => i + 1), value: childIndexes },
+    },
+    layout: {
+      nodeIndex: [0, ...owners.map((_, i) => i + 1)],
+      bounds: [[0, 0, 200, 100], ...owners.map(() => [0, 0, 200, 100])],
+    },
+  });
+  const snapshot = {
+    strings: ["body", "iframe"],
+    documents: [
+      document(0, [100, 101, 102, 103, 104, 105], [1, 2, 3, 4, 5, 6]),
+      document(1, [200], [7]),
+      ...Array.from({ length: 6 }, (_, i) => document(i + 2, [], [])),
+    ],
+  };
+  let active = 0;
+  let peak = 0;
+  const send = vi.fn(async (_tabId: number, method: string, params: object = {}) => {
+    const args = params as Record<string, unknown>;
+    active++;
+    peak = Math.max(peak, active);
+    try {
+      await beforeReply(method, args);
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "Page.getLayoutMetrics")
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+        };
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [0, 0, 200, 0, 200, 100, 0, 100] } };
+      if (method === "DOM.resolveNode") return { object: { objectId: String(args.backendNodeId) } };
+      if (method === "Runtime.callFunctionOn")
+        return { result: { value: { width: 200, height: 100 } } };
+      return {};
+    } finally {
+      active--;
+    }
+  });
+  return {
+    cdp: { send: send as CdpRunner["send"] },
+    send,
+    peak: () => peak,
+    active: () => active,
+    measured: () =>
+      send.mock.calls
+        .filter(([, method]) => method === "DOM.getBoxModel")
+        .map(([, , params]) => (params as { backendNodeId: number }).backendNodeId),
+  };
+}
+
+describe("sibling frame measurement scheduling", () => {
+  it("batches same-target owner sizes without changing projected results", async () => {
+    const fixture = siblingCaptureFixture();
+    const original = fixture.cdp.send;
+    const methods: string[] = [];
+    fixture.cdp.send = async (tabId, method, params) => {
+      methods.push(method);
+      if (method === "Runtime.evaluate")
+        return {
+          result: {
+            deepSerializedValue: {
+              type: "array",
+              value: [100, 101, 102, 103, 104, 105, 200].map((backendNodeId) => ({
+                type: "array",
+                value: [
+                  { type: "node", value: { backendNodeId } },
+                  { type: "string", value: JSON.stringify({ width: 200, height: 100 }) },
+                ],
+              })),
+            },
+          },
+        } as never;
+      return original(tabId, method, params);
+    };
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect(methods.filter((method) => method === "DOM.getBoxModel")).toHaveLength(7);
+    expect(methods.filter((method) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(methods.filter((method) => method === "Runtime.releaseObjectGroup")).toHaveLength(1);
+    expect(methods).not.toContain("DOM.resolveNode");
+    expect(methods).not.toContain("Runtime.callFunctionOn");
+  });
+
+  it("bounds concurrent reads, fills free slots and preserves depth-first output despite reordered replies", async () => {
+    const pending = new Map<number, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.getBoxModel" && Number(params.backendNodeId) < 200)
+        await new Promise<void>((resolve) => pending.set(Number(params.backendNodeId), resolve));
+    });
+    const capture = captureViewModel(fixture.cdp, 4);
+    await vi.waitFor(() => expect(pending.size).toBe(4));
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    pending.get(103)!();
+    await vi.waitFor(() => expect(pending.has(104)).toBe(true));
+    pending.get(104)!();
+    await vi.waitFor(() => expect(pending.has(105)).toBe(true));
+    expect(fixture.measured()).not.toContain(200);
+    for (const id of [105, 102, 101, 100]) pending.get(id)!();
+    const captured = await capture;
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect(fixture.peak()).toBe(4);
+    expect(fixture.active()).toBe(0);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103, 104, 105, 200]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    for (const method of [
+      "DOM.getBoxModel",
+      "DOM.resolveNode",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObject",
+    ])
+      expect(fixture.send.mock.calls.filter(([, name]) => name === method)).toHaveLength(7);
+  });
+
+  it("does not measure descendants of a failed owner and retains sibling geometry and local nodes", async () => {
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode" && params.backendNodeId === 100)
+        throw new Error("owner replaced");
+    });
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4 }, frameId: "frame-1" },
+        ownerBackendNodeId: 100,
+      },
+      {
+        status: "blocked",
+        source: { target: { tabId: 4 }, frameId: "frame-7" },
+        cause: captured.frameGeometryIssues?.[0],
+      },
+    ]);
+    expect(fixture.measured()).not.toContain(200);
+    expect(captured.iframeNodes.get(200)?.[0]).toMatchObject({
+      tag: "body",
+      rect: null,
+      localRect: { x: 0, y: 0, w: 200, h: 100 },
+    });
+    expect(captured.iframeNodes.get(101)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+  });
+
+  it("stops scheduling on cancellation and waits for resolved objects to be released", async () => {
+    const controller = new AbortController();
+    const resolutions = new Map<string, () => void>();
+    const releases = new Map<string, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode")
+        await new Promise<void>((resolve) =>
+          resolutions.set(String(params.backendNodeId), resolve),
+        );
+      if (method === "Runtime.releaseObject")
+        await new Promise<void>((resolve) => releases.set(String(params.objectId), resolve));
+    });
+    let settled = false;
+    const capture = captureViewModel(fixture.cdp, 4, { signal: controller.signal });
+    const rejected = expect(capture).rejects.toMatchObject({ name: "AbortError" });
+    void capture.then(
+      () => {
+        settled = true;
+      },
+      () => {
+        settled = true;
+      },
+    );
+    await vi.waitFor(() => expect(resolutions.size).toBe(4));
+    controller.abort();
+    for (const resolve of resolutions.values()) resolve();
+    await vi.waitFor(() => expect(releases.size).toBe(4));
+    expect(settled).toBe(false);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    for (const release of releases.values()) release();
+    await rejected;
+    expect(fixture.active()).toBe(0);
+    expect(fixture.send.mock.calls.some(([, method]) => method === "Runtime.callFunctionOn")).toBe(
+      false,
+    );
+  });
+});

apps/extension/src/tools/vom/__tests__/facts.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import { createCaptureCheckpoint } from "../capture-abort";
 import { buildDocumentIndex, type DecodedNode } from "../facts";
 import { decodeDocument, REQUESTED_STYLES } from "../snapshot";
 
@@ -76,7 +77,7 @@ describe("document facts", () => {
     );
     expect(nodes[0].attrs).toEqual({ "aria-hidden": "true", inert: "" });
     expect(nodes[0].layout).toEqual({
-      boundsSpace: "snapshot-document-css",
+      boundsSpace: "snapshot-document-layout",
       bounds: [10, 20, 120, 40],
       styles: {
         position: "static",
@@ -90,7 +91,23 @@ describe("document facts", () => {
     expect(nodes[0]).not.toHaveProperty("excluded");
   });
 
-  it("yields during large inputs so cancellation interrupts indexing", async () => {
+  it("keeps short blocks synchronous and checks cancellation after yielding", async () => {
+    const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+    try {
+      const controller = new AbortController();
+      const checkpoint = createCaptureCheckpoint(controller.signal);
+      for (let i = 0; i < 20; i++) expect(checkpoint()).toBeUndefined();
+      clock.mockReturnValue(9);
+      const pending = checkpoint();
+      expect(pending).toBeInstanceOf(Promise);
+      controller.abort();
+      await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+    } finally {
+      clock.mockRestore();
+    }
+  });
+
+  it("checks cancellation at bounded indexing blocks", async () => {
     const controller = new AbortController();
     const input = Array.from({ length: 100_000 }, (_, i) => node(i, i ? i - 1 : null));
     let reads = 0;

apps/extension/src/tools/vom/__tests__/form-state.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
-import { captureObservationFacts } from "../capture-coordinator";
+import { enrichFormControlStates } from "../form-capture";
+import { decodeDocument } from "../snapshot";
 
 interface Control {
   id: number;
@@ -77,21 +78,32 @@ function reply(entries: Array<[number, unknown]>) {
   };
 }
 
-function fakeCdp(groups: Control[][], evaluate: (params: Record<string, unknown>) => unknown) {
+async function fakeCdp(
+  groups: Control[][],
+  evaluate: (params: Record<string, unknown>) => unknown,
+) {
   const snap = snapshot(groups);
   const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
-    if (method === "DOMSnapshot.captureSnapshot") return snap;
     if (method === "Runtime.evaluate") return evaluate(params as Record<string, unknown>);
     return {};
   });
-  return { send, cdp: { send: send as CdpRunner["send"] } };
+  const nodes = await decodeControls(snap);
+  return { send, cdp: { send: send as CdpRunner["send"] }, nodes };
+}
+
+async function decodeControls(snap: ReturnType<typeof snapshot>) {
+  return Promise.all(
+    snap.documents.map(async (doc) =>
+      (await decodeDocument(doc, snap.strings)).nodes.map((node) => ({ ...node, rect: null })),
+    ),
+  );
 }
 
 describe("form state identity", () => {
   it("matches reordered controls by identity and preserves controls missing from the batch", async () => {
     // The snapshot includes a shadow input. The runtime query skips it,
     // encounters a new input, and sees the remaining inputs in a new order.
-    const { cdp } = fakeCdp(
+    const { cdp, nodes } = await fakeCdp(
       [
         [
           { id: 10, value: "" },
@@ -106,23 +118,21 @@ describe("form state identity", () => {
           [11, state("alice@example.com")],
         ]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 10)).toMatchObject({
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 10)).toMatchObject({
       formValue: "",
       formState: "empty",
       formPlaceholder: "snapshot placeholder",
     });
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
       formValue: "alice@example.com",
     });
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)).toMatchObject({
-      formValue: "上海",
-    });
-    expect(captured.documents[0].domNodes.some((n) => n.backendNodeId === 99)).toBe(false);
+    expect(nodes[0].find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
+    expect(nodes[0].some((n) => n.backendNodeId === 99)).toBe(false);
   });
 
   it("does not shift state between frames when one frame is absent from the runtime batch", async () => {
-    const { cdp } = fakeCdp(
+    const { cdp, nodes } = await fakeCdp(
       [
         [],
         [{ id: 11, value: "inaccessible frame" }],
@@ -135,10 +145,8 @@ describe("form state identity", () => {
           [21, state("second frame")],
         ]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    const controls = captured.documents
-      .filter((doc) => doc.frame.parentFrameId)
-      .flatMap((doc) => doc.domNodes);
+    await enrichFormControlStates(cdp, 7, nodes);
+    const controls = nodes.slice(1).flat();
     expect(controls.find((n) => n.backendNodeId === 11)?.formValue).toBe("inaccessible frame");
     expect(controls.find((n) => n.backendNodeId === 21)?.formValue).toBe("second frame");
     expect(controls.find((n) => n.backendNodeId === 31)?.formValue).toBe("third frame");
@@ -146,7 +154,6 @@ describe("form state identity", () => {
 
   it("keeps identical backend ids in different OOPIF targets separate", async () => {
     const sendToTarget = vi.fn(async (target, method) => {
-      if (method === "DOMSnapshot.captureSnapshot") return snapshot([[{ id: 11, value: "old" }]]);
       if (method === "Runtime.evaluate") return reply([[11, state(target.sessionId)]]);
       return {};
     });
@@ -155,13 +162,9 @@ describe("form state identity", () => {
     });
     const cdp = { send, sendToTarget } as unknown as CdpRunner;
     for (const sessionId of ["left-frame", "right-frame"]) {
-      const captured = await captureObservationFacts(
-        cdpRunnerForTarget(cdp, { tabId: 7, sessionId }),
-        7,
-      );
-      expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
-        sessionId,
-      );
+      const nodes = await decodeControls(snapshot([[{ id: 11, value: "old" }]]));
+      await enrichFormControlStates(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7, nodes);
+      expect(nodes[0].find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
       expect(sendToTarget).toHaveBeenCalledWith(
         { tabId: 7, sessionId },
         "Runtime.releaseObjectGroup",
@@ -177,7 +180,7 @@ describe("form state identity", () => {
     "malformed",
     "invalid-state",
   ])("preserves snapshot data when enrichment is %s", async (mode) => {
-    const { cdp, send } = fakeCdp([[{ id: 11, value: "snapshot value" }]], () => {
+    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "snapshot value" }]], () => {
       if (mode === "unsupported") throw new Error("serialization unsupported");
       if (mode === "legacy") return { result: { value: { controls: [state("wrong value")] } } };
       const result = reply([
@@ -187,8 +190,8 @@ describe("form state identity", () => {
         result.result.deepSerializedValue.value[0].value[1].value = "not json";
       return result;
     });
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+    expect(await enrichFormControlStates(cdp, 7, nodes)).toBe(mode !== "unsupported");
+    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
       formValue: "snapshot value",
       formPlaceholder: "snapshot placeholder",
     });
@@ -197,18 +200,34 @@ describe("form state identity", () => {
 
   it("releases the batch's remote objects when capture is cancelled", async () => {
     const controller = new AbortController();
-    const { cdp, send } = fakeCdp([[{ id: 11, value: "old" }]], () => {
+    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "old" }]], () => {
       controller.abort();
       return reply([[11, state("new")]]);
     });
-    await expect(captureObservationFacts(cdp, 7, controller.signal)).rejects.toMatchObject({
+    await expect(enrichFormControlStates(cdp, 7, nodes, controller.signal)).rejects.toMatchObject({
       name: "AbortError",
     });
     expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
   });
 
+  it("does not report success when cancelled during object cleanup", async () => {
+    const controller = new AbortController();
+    const nodes = await decodeControls(snapshot([[{ id: 11, value: "old" }]]));
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Runtime.evaluate") return reply([[11, state("new")]]);
+        if (method === "Runtime.releaseObjectGroup") controller.abort();
+        return {};
+      }) as CdpRunner["send"],
+    };
+    await expect(enrichFormControlStates(cdp, 7, nodes, controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(cdp.send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
   it("skips entries without node identity while still applying valid entries", async () => {
-    const { cdp } = fakeCdp(
+    const { cdp, nodes } = await fakeCdp(
       [
         [
           { id: 11, value: "snapshot value" },
@@ -225,24 +244,20 @@ describe("form state identity", () => {
         return result;
       },
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
-      "snapshot value",
-    );
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)?.formValue).toBe(
-      "live value",
-    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
+    expect(nodes[0].find((n) => n.backendNodeId === 12)?.formValue).toBe("live value");
   });
 
   it.each([
     "password",
     "text",
   ])("redacts a sensitive %s control after identity matching", async (type) => {
-    const { cdp } = fakeCdp([[{ id: 11, value: "secret", type }]], () =>
+    const { cdp, nodes } = await fakeCdp([[{ id: 11, value: "secret", type }]], () =>
       reply([[11, { ...state("secret"), sensitive: true }]]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    const control = captured.documents[0].domNodes.find((n) => n.backendNodeId === 11);
+    await enrichFormControlStates(cdp, 7, nodes);
+    const control = nodes[0].find((n) => n.backendNodeId === 11);
     expect(control?.formState).toBe("filled");
     expect(control?.formValue).toBeUndefined();
     expect(control?.formDefaultValue).toBeUndefined();
@@ -259,7 +274,7 @@ describe("form state identity", () => {
       defaultValue: "",
       placeholder: "",
     }));
-    const { cdp, send } = fakeCdp([controls], (params) => {
+    const { cdp, send, nodes } = await fakeCdp([controls], (params) => {
       const doc = {
         querySelectorAll: (selector: string) =>
           selector === "input,textarea,select" ? elements : [],
@@ -270,13 +285,9 @@ describe("form state identity", () => {
       expect(entries).toHaveLength(250);
       return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
     });
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 250)?.formValue).toBe(
-      "live 250",
-    );
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 251)?.formValue).toBe(
-      "old",
-    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
+    expect(nodes[0].find((n) => n.backendNodeId === 251)?.formValue).toBe("old");
     expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
     expect(
       send.mock.calls.filter(([, method]) => method === "Runtime.releaseObjectGroup"),

apps/extension/src/tools/vom/__tests__/frame-capture.test.ts

@@ -0,0 +1,289 @@
+import { describe, expect, it, vi } from "vitest";
+import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import type { CdpRunner } from "../../shared";
+import type { CapturedNode, CapturedViewModel } from "../capture";
+import { captureFrameData } from "../frame-capture";
+
+function ownerNode(backendNodeId: number, x: number): CapturedNode {
+  return {
+    backendNodeId,
+    parentBackendNodeId: 1,
+    frameId: "main",
+    ownerFrameBackendNodeId: null,
+    tag: "iframe",
+    attrs: {},
+    rect: { x, y: 100, w: 300, h: 200 },
+    localRect: { x, y: 100, w: 300, h: 200 },
+    paintOrder: 1,
+    position: "static",
+    pointerEvents: "auto",
+  };
+}
+
+function childSnapshot(frameId: string, backendNodeId: number) {
+  const strings = [frameId, "body", "button", "static", "auto", "pointer"];
+  return {
+    strings,
+    documents: [
+      {
+        scrollOffsetX: 0,
+        scrollOffsetY: 0,
+        frameId,
+        nodes: {
+          parentIndex: [-1, 0],
+          nodeName: [1, 2],
+          backendNodeId: [backendNodeId - 1, backendNodeId],
+          attributes: [[], []] as number[][],
+        },
+        layout: {
+          nodeIndex: [0, 1],
+          styles: [
+            [3, 4, 4],
+            [3, 4, 5],
+          ],
+          bounds: [
+            [0, 0, 300, 200],
+            [10, 20, 100, 40],
+          ],
+          paintOrders: [0, 1],
+        },
+      },
+    ],
+  };
+}
+
+describe("captureFrameData", () => {
+  it("retains nested owner failures when merging a captured OOPIF", async () => {
+    const owner = ownerNode(10, 50);
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const child = childSnapshot("child", 101);
+    const nested = childSnapshot("nested", 201);
+    const document = child.documents[0];
+    const snapshot = {
+      strings: child.strings,
+      documents: [
+        {
+          ...document,
+          nodes: { ...document.nodes, contentDocumentIndex: { index: [1], value: [1] } },
+        },
+        nested.documents[0],
+      ],
+    };
+    const reply = async (_target: unknown, method: string) => {
+      if (method === "Page.getLayoutMetrics")
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 300, clientHeight: 200 },
+        };
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [50, 100, 350, 100, 350, 300, 50, 300] } };
+      if (method === "DOM.resolveNode") throw new Error("nested owner replaced");
+      return {};
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(reply) as CdpRunner["send"],
+      sendToTarget: vi.fn(reply) as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+    await captureFrameData(cdp, 4, captured);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4, sessionId: "child-session" }, frameId: "nested" },
+        ownerBackendNodeId: 101,
+      },
+    ]);
+    expect(captured.frameNodes?.get("nested")?.[1]).toMatchObject({
+      rect: null,
+      localRect: { x: 10, y: 20, w: 100, h: 40 },
+    });
+  });
+
+  it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
+    const leftOwner = ownerNode(10, 50);
+    const rightOwner = ownerNode(20, 500);
+    const captured: CapturedViewModel = {
+      nodes: [leftOwner, rightOwner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [leftOwner, rightOwner]]]),
+      frameOwnerBackendNodeIds: new Map(),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const sendToTarget = vi.fn(async (target, method) => {
+      if (method === "Page.getLayoutMetrics") {
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 },
+        };
+      }
+      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+      if (method === "DOMSnapshot.captureSnapshot") {
+        if (target.sessionId !== "left-session") return childSnapshot("right", 201);
+        const snapshot = childSnapshot("left", 101);
+        const marker = snapshot.strings.push(OVERLAY_HOST_MARKER_ATTR) - 1;
+        const nodes = snapshot.documents[0].nodes;
+        nodes.backendNodeId.push(201); // Same id as a real button in the other target.
+        nodes.parentIndex.push(0);
+        nodes.nodeName.push(2);
+        nodes.attributes.push([marker, -1]);
+        return snapshot;
+      }
+      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+      throw new Error(`unexpected ${method}`);
+    });
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") {
+          const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
+          const x = backendNodeId === 10 ? 50 : 500;
+          return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
+        }
+        if (method === "Page.getLayoutMetrics") {
+          return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+          };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "left",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "left-session" },
+          },
+          {
+            frameId: "right",
+            parentFrameId: "main",
+            ownerBackendNodeId: 20,
+            target: { tabId: 4, sessionId: "right-session" },
+          },
+        ],
+      })),
+    };
+
+    const trees = await captureFrameData(cdp, 4, captured);
+
+    expect(trees.find((tree) => tree.frameId === "left")?.excludedBackendNodeIds).toEqual(
+      new Set([201]),
+    );
+    expect(trees.find((tree) => tree.frameId === "right")?.excludedBackendNodeIds?.size).toBe(0);
+    expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
+    expect(
+      captured.frameNodes?.get("left")?.find((node) => node.backendNodeId === 101)?.rect,
+    ).toEqual({ x: 60, y: 120, w: 100, h: 40 });
+    expect(
+      captured.frameNodes?.get("right")?.find((node) => node.backendNodeId === 201)?.rect,
+    ).toEqual({ x: 510, y: 120, w: 100, h: 40 });
+    expect(captured.frameOwnerBackendNodeIds).toEqual(
+      new Map([
+        ["left", 10],
+        ["right", 20],
+      ]),
+    );
+    expect(captured.frameParentIds).toEqual(
+      new Map([
+        ["left", "main"],
+        ["right", "main"],
+      ]),
+    );
+  });
+
+  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
+    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
+        if (method === "Page.getLayoutMetrics") {
+          return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+          };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
+        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
+        if (method === "Accessibility.getFullAXTree") {
+          return {
+            nodes: [
+              {
+                nodeId: "button",
+                backendDOMNodeId: 101,
+                role: { type: "role", value: "button" },
+                name: { type: "computedString", value: "Continue" },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+
+    const documents = await captureFrameData(cdp, 4, captured);
+    const childDocument = documents.find((document) => document.frameId === "child");
+
+    expect(childDocument?.axNodes).toEqual([
+      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
+    ]);
+    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
+      expect.objectContaining({ rect: null, localRect: null, rendered: true }),
+    );
+  });
+});

apps/extension/src/tools/vom/__tests__/frame-document.test.ts

@@ -1,12 +1,7 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "../capture";
-import {
-  buildFrameDocuments,
-  type FrameAxBatch,
-  type FrameDomInput,
-  type FrameOwnedAxNode,
-} from "../frame-document";
+import type { CapturedNode, CapturedViewModel } from "../capture";
+import { buildFrameDocuments, type FrameAxBatch, type FrameOwnedAxNode } from "../frame-document";
 
 function domNode(frameId: string, backendNodeId: number): CapturedNode {
   return {
@@ -22,11 +17,14 @@ function domNode(frameId: string, backendNodeId: number): CapturedNode {
   };
 }
 
-function captured(frameNodes: Map<string, CapturedNode[]>): FrameDomInput {
+function captured(frameNodes: Map<string, CapturedNode[]>): CapturedViewModel {
   return {
     nodes: frameNodes.get("main") ?? [],
+    viewport: { width: 800, height: 600 },
+    iframeNodes: new Map(),
     frameNodes,
     rootFrameId: "main",
+    excludedBackendNodeIds: new Set(),
   };
 }
 
@@ -159,12 +157,10 @@ describe("buildFrameDocuments", () => {
       ["child", [domNode("child", 9)]],
     ]);
     const capture = captured(frameNodes);
+    capture.frameOwnerBackendNodeIds = new Map([["child", 7]]);
+    capture.frameParentIds = new Map([["child", "left"]]);
     const frames = ["main", "left", "right", "child"].map((frameId) => ({
-      frame: {
-        frameId,
-        target: { tabId: 4 },
-        ...(frameId === "child" ? { parentFrameId: "left", ownerBackendNodeId: 7 } : {}),
-      },
+      frame: { frameId, target: { tabId: 4 } },
       nodes: [],
     }));
 
@@ -175,23 +171,6 @@ describe("buildFrameDocuments", () => {
       ownerBackendNodeId: 7,
     });
   });
-  it("rejects explicit AX frame ownership in a different target", async () => {
-    const frames = [
-      { frameId: "main", target: { tabId: 4 } },
-      { frameId: "remote", target: { tabId: 4, sessionId: "remote" } },
-    ];
-    const unresolved = vi.fn();
-    const documents = await buildFrameDocuments(
-      { rootFrameId: "main", frames },
-      [{ frame: frames[0], nodes: [{ nodeId: "wrong", frameId: "remote" }] }],
-      captured(new Map()),
-      undefined,
-      unresolved,
-    );
-    expect(documents.every((doc) => doc.axNodes.length === 0)).toBe(true);
-    expect(unresolved).toHaveBeenCalledOnce();
-  });
-
   it("resolves a reverse-ordered deep AX parent chain without recursion", async () => {
     const frame = { frameId: "main", target: { tabId: 4 } };
     const nodes: FrameOwnedAxNode[] = Array.from({ length: 10000 }, (_, i) => ({

apps/extension/src/tools/vom/capture-abort.ts

@@ -0,0 +1,40 @@
+function captureAbortError(): Error {
+  const error = new Error("observation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: string }).name === "AbortError"
+  );
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw captureAbortError();
+}
+
+/** Check at bounded work blocks; yield only after a processing slice is spent.
+ * Each caller owns its deadline, so unrelated captures do not share state. */
+export function createCaptureCheckpoint(signal?: AbortSignal): () => Promise<void> | undefined {
+  throwIfAborted(signal);
+  let deadline = performance.now() + 8;
+  return () => {
+    throwIfAborted(signal);
+    if (performance.now() < deadline) return;
+    return new Promise<void>((resolve) => {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = () => {
+        channel.port1.close();
+        channel.port2.close();
+        resolve();
+      };
+      channel.port2.postMessage(null);
+    }).then(() => {
+      throwIfAborted(signal);
+      deadline = performance.now() + 8;
+    });
+  };
+}

apps/extension/src/tools/vom/capture-coordinator.ts

@@ -1,334 +0,0 @@
-import {
-  type CdpFrame,
-  type CdpFrameGraph,
-  type CdpTarget,
-  cdpTargetKey,
-} from "@/browser-driver/frame-graph";
-import { cssViewport, GeometryContext } from "../geometry/frame-context";
-import { type CdpRunner, cdpRunnerForTarget } from "../shared";
-import { collectOverlayExcludedBackendIds } from "./capture";
-import type { CapturedSceneInput } from "./facts";
-import {
-  buildDocumentIndex,
-  type CaptureIssue,
-  isCaptureAbort,
-  type ObservationFacts,
-  throwCaptureAborted,
-} from "./facts";
-import { enrichFormControlStates } from "./form-capture";
-import {
-  buildFrameDocuments,
-  type FrameAxBatch,
-  type FrameDocument,
-  type FrameOwnedAxNode,
-} from "./frame-document";
-import { type NormalizedDocument, normalizeSnapshot } from "./normalize";
-import { describeSnapshotFrames, REQUESTED_STYLES, type SnapshotReply } from "./snapshot";
-
-interface TargetBatch<T extends FrameOwnedAxNode> {
-  target: CdpTarget;
-  frames: CdpFrame[];
-  documents: NormalizedDocument[];
-  ax: FrameAxBatch<T>[];
-  fallbackExcluded: Set<number>;
-  snapshotFrameIds?: Set<string>;
-  rootFrameId?: string;
-}
-
-/** A fixed worker pool scoped to one capture; each worker issues at most one
- * collection request at a time. Geometry has its own measurement-phase bound. */
-async function collectTargets<T>(
-  items: readonly T[],
-  collect: (item: T) => Promise<void>,
-  signal?: AbortSignal,
-): Promise<void> {
-  let cursor = 0;
-  let failed = false;
-  let failure: unknown;
-  await Promise.all(
-    Array.from({ length: Math.min(4, items.length) }, async () => {
-      try {
-        while (cursor < items.length && !failed && !signal?.aborted) {
-          const item = items[cursor++];
-          await collect(item);
-        }
-      } catch (error) {
-        if (!failed) failure = error;
-        failed = true;
-      }
-    }),
-  );
-  // A worker's rejection must not let the capture outlive its own task scope.
-  // In-flight reads and their finally blocks settle before cancellation/failure.
-  throwCaptureAborted(signal);
-  if (failed) throw failure;
-}
-
-export async function captureObservationFacts<T extends FrameOwnedAxNode>(
-  cdp: CdpRunner,
-  tabId: number,
-  signal?: AbortSignal,
-  pageUrl?: string,
-): Promise<ObservationFacts<T>> {
-  const startedAt = Date.now();
-  throwCaptureAborted(signal);
-  let graph: CdpFrameGraph | undefined;
-  try {
-    graph = await cdp.getFrameGraph?.(tabId);
-  } catch (error) {
-    if (isCaptureAbort(error)) throw error;
-  }
-  throwCaptureAborted(signal);
-  const geometry = new GeometryContext(cdp, tabId, graph, signal);
-  const issues: CaptureIssue[] = [];
-  const graphFrames = new Map(graph?.frames.map((frame) => [frame.frameId, frame]) ?? []);
-  const groups = new Map<string, TargetBatch<T>>();
-  for (const frame of graph?.frames ?? []) {
-    const key = cdpTargetKey(frame.target);
-    let group = groups.get(key);
-    if (!group) {
-      group = {
-        target: frame.target,
-        frames: [],
-        documents: [],
-        ax: [],
-        fallbackExcluded: new Set(),
-      };
-      groups.set(key, group);
-    }
-    group.frames.push(
-      !frame.target.sessionId && frame.frameId === graph?.rootFrameId && !frame.url && pageUrl
-        ? { ...frame, url: pageUrl }
-        : frame,
-    );
-  }
-  if (!groups.has(cdpTargetKey({ tabId })))
-    groups.set(cdpTargetKey({ tabId }), {
-      target: { tabId },
-      frames: [],
-      documents: [],
-      ax: [],
-      fallbackExcluded: new Set(),
-    });
-  const batches = [...groups.values()];
-  const unavailable = (batch: TargetBatch<T>, stage: CaptureIssue["stage"], frameId?: string) =>
-    issues.push({ target: batch.target, frameId, stage, reason: "capture-unavailable" });
-  let firstFailure: unknown;
-  await collectTargets(
-    batches,
-    async (batch) => {
-      const scoped = cdpRunnerForTarget(cdp, batch.target);
-      try {
-        throwCaptureAborted(signal);
-        await scoped.send(tabId, "DOMSnapshot.enable", {});
-        throwCaptureAborted(signal);
-        const snapshot = await scoped.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
-          computedStyles: REQUESTED_STYLES,
-          includePaintOrder: true,
-          includeDOMRects: true,
-        });
-        throwCaptureAborted(signal);
-        const observed = describeSnapshotFrames(snapshot, batch.target, graphFrames, pageUrl);
-        batch.snapshotFrameIds = observed.ids;
-        batch.rootFrameId = observed.rootFrameId;
-        // Keep graph-only frames for AX fallback, never in preference to observed membership.
-        batch.frames = [
-          ...observed.frames,
-          ...batch.frames.filter((frame) => !observed.ids.has(frame.frameId)),
-        ];
-        batch.documents = await normalizeSnapshot(
-          snapshot,
-          batch.target,
-          batch.frames.filter((frame) => observed.ids.has(frame.frameId)),
-          geometry,
-          issues,
-          signal,
-          observed.rootFrameId,
-        );
-        const formsAvailable = await enrichFormControlStates(
-          scoped,
-          tabId,
-          batch.documents.map((doc) => doc.domNodes),
-          signal,
-        );
-        throwCaptureAborted(signal);
-        if (!formsAvailable) unavailable(batch, "forms");
-        const present = new Set(batch.documents.map((doc) => doc.frame.frameId));
-        for (const frame of batch.frames)
-          if (!present.has(frame.frameId)) unavailable(batch, "dom", frame.frameId);
-      } catch (error) {
-        throwCaptureAborted(signal);
-        if (isCaptureAbort(error)) throw error;
-        firstFailure ??= error;
-        unavailable(batch, "dom");
-        batch.fallbackExcluded = await collectOverlayExcludedBackendIds(scoped, tabId, signal);
-      }
-      if (!batch.frames.length && !graph)
-        batch.frames = [
-          {
-            frameId: "root",
-            target: batch.target,
-            ...(!batch.target.sessionId && pageUrl ? { url: pageUrl } : {}),
-          },
-        ];
-      try {
-        throwCaptureAborted(signal);
-        await scoped.send(tabId, "Accessibility.enable", {});
-      } catch (error) {
-        throwCaptureAborted(signal);
-        if (isCaptureAbort(error)) throw error;
-        firstFailure ??= error;
-        unavailable(batch, "ax");
-        return;
-      }
-      for (const frame of batch.frames) {
-        try {
-          throwCaptureAborted(signal);
-          const result = await scoped.send<{ nodes?: T[] }>(
-            tabId,
-            "Accessibility.getFullAXTree",
-            frame.frameId === "root" ? {} : { frameId: frame.frameId },
-          );
-          throwCaptureAborted(signal);
-          batch.ax.push({ frame, nodes: result.nodes ?? [] });
-        } catch (error) {
-          throwCaptureAborted(signal);
-          if (isCaptureAbort(error)) throw error;
-          firstFailure ??= error;
-          unavailable(batch, "ax", frame.frameId);
-        }
-      }
-    },
-    signal,
-  );
-
-  // A snapshot claim outranks an old graph hint. Conflicting actual claims
-  // cannot be resolved by completion order or by overwriting a frameId map.
-  const claims = new Map<string, string>();
-  const invalid = new Set<string>();
-  for (const batch of batches) {
-    const targetKey = cdpTargetKey(batch.target);
-    for (const id of batch.snapshotFrameIds ?? []) {
-      const previous = claims.get(id);
-      if (previous !== undefined && previous !== targetKey) invalid.add(id);
-      claims.set(id, targetKey);
-    }
-    const accepted = new Set(batch.frames.map((frame) => frame.frameId));
-    for (const id of batch.snapshotFrameIds ?? []) if (!accepted.has(id)) invalid.add(id);
-  }
-  const currentFrames = batches.flatMap((batch) =>
-    batch.frames.filter(
-      (frame) =>
-        !claims.has(frame.frameId) || claims.get(frame.frameId) === cdpTargetKey(batch.target),
-    ),
-  );
-  const children = new Map<string, string[]>();
-  for (const frame of currentFrames) {
-    if (!frame.parentFrameId) continue;
-    const siblings = children.get(frame.parentFrameId);
-    if (siblings) siblings.push(frame.frameId);
-    else children.set(frame.parentFrameId, [frame.frameId]);
-  }
-  const blocked = [...invalid];
-  for (let i = 0; i < blocked.length; i++) {
-    for (const child of children.get(blocked[i]) ?? []) {
-      if (!invalid.has(child)) {
-        invalid.add(child);
-        blocked.push(child);
-      }
-    }
-  }
-  for (const frame of currentFrames) {
-    if (invalid.has(frame.frameId))
-      issues.push({
-        target: frame.target,
-        frameId: frame.frameId,
-        stage: "ownership",
-        reason: "frame-ownership-unresolved",
-      });
-  }
-  const rootBatch = batches.find((batch) => !batch.target.sessionId);
-  const rootFrameId =
-    rootBatch?.rootFrameId ?? graph?.rootFrameId ?? rootBatch?.frames[0]?.frameId ?? "root";
-  if (invalid.has(rootFrameId)) throw new Error("observation root document ownership is ambiguous");
-  const frames = currentFrames.filter((frame) => !invalid.has(frame.frameId));
-  const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
-  const belongs = (frame: CdpFrame) => {
-    const current = frameById.get(frame.frameId);
-    return current && cdpTargetKey(current.target) === cdpTargetKey(frame.target);
-  };
-  const decoded = new Map(
-    batches
-      .flatMap((batch) => batch.documents)
-      .filter((doc) => belongs(doc.frame))
-      .map((doc) => [doc.frame.frameId, doc]),
-  );
-  const ax = batches.flatMap((batch) => batch.ax).filter((batch) => belongs(batch.frame));
-  const documents = await buildFrameDocuments(
-    { rootFrameId, frames },
-    ax,
-    {
-      nodes: [],
-      rootFrameId,
-      frameNodes: new Map([...decoded].map(([id, doc]) => [id, doc.domNodes])),
-    },
-    signal,
-    (frame) =>
-      issues.push({
-        target: frame.target,
-        frameId: frame.frameId,
-        stage: "ownership",
-        reason: "frame-ownership-unresolved",
-      }),
-  );
-  let viewport = { width: 0, height: 0 };
-  try {
-    const measured = cssViewport(await geometry.layoutMetrics({ tabId }));
-    viewport = { width: measured.width, height: measured.height };
-  } catch (error) {
-    if (isCaptureAbort(error)) throw error;
-  }
-  const facts: ObservationFacts<T>["documents"][number][] = [];
-  for (const document of documents) {
-    const doc = decoded.get(document.frameId);
-    const index = doc?.index ?? (await buildDocumentIndex([], signal));
-    const fallback = groups.get(cdpTargetKey(document.target))?.fallbackExcluded;
-    const { domNodes, axNodes, contextScopeId: _scope, ...frame } = document;
-    facts.push({
-      frame,
-      index: fallback?.size ? { ...index, excludedBackendNodeIds: fallback } : index,
-      domNodes,
-      axNodes,
-    });
-  }
-  throwCaptureAborted(signal);
-  if (firstFailure && facts.every((doc) => !doc.domNodes.length && !doc.axNodes.length))
-    throw firstFailure;
-  return { rootFrameId, viewport, documents: facts, issues, startedAt, finishedAt: Date.now() };
-}
-
-/** Existing semantic consumers get a narrow view; no raw snapshot
- * data can leak through recording's allowlisted output DTO. */
-export function semanticCapture<T extends FrameOwnedAxNode>(
-  facts: ObservationFacts<T>,
-): { captured: CapturedSceneInput; documents: FrameDocument<T>[] } {
-  const documents = facts.documents.map((doc) => ({
-    ...doc.frame,
-    contextScopeId: doc.frame.frameId,
-    domNodes: doc.domNodes.filter(
-      (node) => !doc.index.excludedBackendNodeIds.has(node.backendNodeId),
-    ),
-    axNodes: doc.axNodes,
-    excludedBackendNodeIds: doc.index.excludedBackendNodeIds,
-  }));
-  const root = documents.find((doc) => doc.frameId === facts.rootFrameId);
-  return {
-    documents,
-    captured: {
-      nodes: root?.domNodes ?? [],
-      viewport: facts.viewport,
-      rootFrameId: facts.rootFrameId,
-      excludedBackendNodeIds: root?.excludedBackendNodeIds ?? new Set(),
-    },
-  };
-}

apps/extension/src/tools/vom/capture-types.ts

@@ -0,0 +1,37 @@
+import type { Rect } from "@browser-skill/vom";
+
+export interface CapturedNode {
+  backendNodeId: number;
+  parentBackendNodeId: number | null;
+  frameId?: string;
+  /** Owning iframe backend node id; `null` for the top-level document. */
+  ownerFrameBackendNodeId?: number | null;
+  tag: string;
+  attrs: Record<string, string>;
+  /** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
+  rect: Rect | null;
+  /** Frame-local viewport-relative CSS px before top-level projection. */
+  localRect?: Rect | null;
+  paintOrder: number;
+  position: string;
+  pointerEvents: string;
+  /**
+   * computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
+   * that a non-semantic element (a `<div>`/`<span>` with a click handler)
+   * is actually an interactive control — used by the adapter to surface
+   * custom buttons/checkboxes the AX tree drops as `generic`. Optional like
+   * `textContent`: the live parser always sets it, hand-built fixtures may not.
+   */
+  cursor?: string;
+  /**
+   * Whether the live DOM snapshot provides a painted, non-hidden box for this
+   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
+   * nodes remain authoritative even when they are outside the viewport.
+   */
+  rendered?: boolean;
+  textContent?: string;
+  formState?: "empty" | "filled" | "default";
+  formValue?: string;
+  formDefaultValue?: string;
+  formPlaceholder?: string;
+}

apps/extension/src/tools/vom/capture.ts

@@ -1,17 +1,67 @@
-// Browser-side hover probes and overlay exclusion fallback. Static collection
-// lives in capture-coordinator; snapshot decoding has no browser dependency.
+// Coordinate DOMSnapshot acquisition, frame geometry and hover probes.
+// Snapshot decoding and form enrichment live in their own modules.
+
+import type { Viewport } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
+import {
+  type FrameProjectionIssue,
+  type FrameProjectionState,
+  snapshotCoordinates,
+} from "../geometry/coordinate-types";
+import {
+  GeometryContext,
+  type LayoutMetrics,
+  snapshotLayoutScale,
+} from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
-import type { CapturedNode, CapturedSurfaceProbe } from "./facts";
-
-export type {
-  CapturedNode,
-  CapturedSurfaceProbe,
-} from "./facts";
-
-import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
+import { isAbortError, throwIfAborted } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+import { enrichFormControlStates } from "./form-capture";
 import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
+import { type FrameContext, normalizeDocument } from "./normalize";
+import {
+  REQUESTED_STYLES,
+  type SnapshotDocument,
+  type SnapshotReply,
+  snapshotFrameId,
+  sparseIndexMap,
+} from "./snapshot";
+
+export type { CapturedNode } from "./capture-types";
+
+export type CapturedIframeNodes = Map<number, CapturedNode[]>;
+
+export interface CapturedSurfaceProbe {
+  triggerBackendNodeId: number;
+  triggerPoint?: { x: number; y: number };
+  triggerAction: "hover" | "focus" | string;
+  subItems: string[];
+  confidence?: "high" | "medium" | "low";
+}
+
+export interface CapturedViewModel {
+  nodes: CapturedNode[];
+  viewport: Viewport;
+  iframeNodes: CapturedIframeNodes;
+  frameNodes?: Map<string, CapturedNode[]>;
+  frameExcludedBackendNodeIds?: Map<string, ReadonlySet<number>>;
+  frameOwnerBackendNodeIds?: Map<string, number>;
+  /** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
+  frameParentIds?: Map<string, string>;
+  rootFrameId?: string;
+  /** Failed boundaries and descendants blocked by them; clipping is not a failure. */
+  frameGeometryIssues?: FrameProjectionIssue[];
+  /** Backend node ids belonging to the agent overlay host + its shadow subtree. */
+  excludedBackendNodeIds: Set<number>;
+}
+
+export interface CaptureViewModelOptions {
+  signal?: AbortSignal;
+  geometry?: GeometryContext;
+  target?: CdpTarget;
+}
 
 interface RuntimeEvaluateReply {
   result?: {
@@ -442,3 +492,295 @@ export async function collectOverlayExcludedBackendIds(
   }
   return excluded;
 }
+
+interface ParseFrameDocumentsResult {
+  frameGeometryIssues: FrameProjectionIssue[];
+  iframeNodes: CapturedIframeNodes;
+  frameOwnerBackendNodeIds: Map<string, number>;
+  frameParentIds: Map<string, string>;
+  frameExcludedBackendNodeIds: Map<string, ReadonlySet<number>>;
+  excludedBackendNodeIds: Set<number>;
+}
+
+async function parseChildFrameDocuments(
+  documents: SnapshotDocument[],
+  strings: string[],
+  parentDocIndex: number,
+  parentContext: FrameContext,
+  geometry: GeometryContext,
+  signal?: AbortSignal,
+  visited = new Set<number>(),
+): Promise<ParseFrameDocumentsResult> {
+  const frameGeometryIssues: FrameProjectionIssue[] = [];
+  const iframeNodes: CapturedIframeNodes = new Map();
+  const frameOwnerBackendNodeIds = new Map<string, number>();
+  const frameParentIds = new Map<string, string>();
+  const frameExcludedBackendNodeIds = new Map<string, ReadonlySet<number>>();
+  const excludedBackendNodeIds = new Set<number>();
+  const parentDoc = documents[parentDocIndex];
+  const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
+  if (cdi.size === 0) {
+    return {
+      iframeNodes,
+      frameOwnerBackendNodeIds,
+      frameParentIds,
+      frameExcludedBackendNodeIds,
+      excludedBackendNodeIds,
+      frameGeometryIssues,
+    };
+  }
+
+  const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
+
+  const children = [...cdi].flatMap(([nodeArrayIdx, childDocIndex]) => {
+    const childDoc = documents[childDocIndex];
+    const iframeBackendId = parentBackendIds[nodeArrayIdx];
+    if (visited.has(childDocIndex) || !childDoc || iframeBackendId === undefined) return [];
+    const source = { target: parentContext.target, frameId: snapshotFrameId(childDoc, strings) };
+    const coordinates = snapshotCoordinates(childDoc, parentContext.layoutUnitsPerCssPixel);
+    const parent = parentContext.projection;
+    const projection: FrameProjectionState =
+      parent.status === "available"
+        ? coordinates
+          ? { status: "unavailable", source, ownerBackendNodeId: iframeBackendId }
+          : { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" }
+        : { status: "blocked", source, cause: parent.status === "blocked" ? parent.cause : parent };
+    return [
+      {
+        childDocIndex,
+        childDoc,
+        iframeBackendId,
+        source,
+        coordinates,
+        projection: projection as FrameProjectionState,
+      },
+    ];
+  });
+  const parentProjection =
+    parentContext.projection.status === "available"
+      ? parentContext.projection.projection.geometry
+      : null;
+  if (parentProjection) {
+    // Measure only direct siblings. Recursion starts after these workers finish,
+    // so descendants never hold or recursively acquire a measurement slot.
+    const edge = parentProjection.edges[0];
+    const clips = edge
+      ? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
+      : parentProjection.sourceClips;
+    let cursor = 0;
+    let failure: unknown;
+    await Promise.all(
+      Array.from({ length: Math.min(4, children.length) }, async () => {
+        while (cursor < children.length && !signal?.aborted && !failure) {
+          const child = children[cursor++];
+          if (!child.coordinates) continue;
+          try {
+            // Owner quads are target-relative; do not apply the parent transform twice.
+            child.projection = await geometry.snapshotProjection(
+              child.source,
+              child.iframeBackendId,
+              clips,
+              parentProjection.topViewport,
+            );
+          } catch (error) {
+            failure ??= error;
+          }
+        }
+      }),
+    );
+    // Join all active reads, including object cleanup, before propagating abort.
+    if (failure) throw failure;
+  }
+  throwIfAborted(signal);
+
+  // Completion order must not change document traversal or result insertion order.
+  for (const {
+    childDocIndex,
+    childDoc,
+    iframeBackendId,
+    source,
+    projection,
+    coordinates,
+  } of children) {
+    throwIfAborted(signal);
+    if (projection.status !== "available") frameGeometryIssues.push(projection);
+    const childContext: FrameContext = {
+      frameId: source.frameId,
+      target: source.target,
+      ownerFrameBackendNodeId: iframeBackendId,
+      projection,
+      coordinates,
+      layoutUnitsPerCssPixel: parentContext.layoutUnitsPerCssPixel,
+    };
+    const nextVisited = new Set(visited);
+    nextVisited.add(childDocIndex);
+    const parsed = await normalizeDocument(childDoc, strings, childContext, signal);
+    iframeNodes.set(iframeBackendId, parsed.nodes);
+    if (childContext.frameId) {
+      frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
+      frameExcludedBackendNodeIds.set(childContext.frameId, parsed.index.excludedBackendNodeIds);
+      if (parentContext.frameId) frameParentIds.set(childContext.frameId, parentContext.frameId);
+    }
+    for (const id of parsed.index.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
+
+    const nested = await parseChildFrameDocuments(
+      documents,
+      strings,
+      childDocIndex,
+      childContext,
+      geometry,
+      signal,
+      nextVisited,
+    );
+    frameGeometryIssues.push(...nested.frameGeometryIssues);
+    for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
+      iframeNodes.set(nestedFrameId, nestedNodes);
+    }
+    for (const [frameId, ownerBackendNodeId] of nested.frameOwnerBackendNodeIds) {
+      frameOwnerBackendNodeIds.set(frameId, ownerBackendNodeId);
+    }
+    for (const [frameId, parentFrameId] of nested.frameParentIds) {
+      frameParentIds.set(frameId, parentFrameId);
+    }
+    for (const [frameId, excluded] of nested.frameExcludedBackendNodeIds)
+      frameExcludedBackendNodeIds.set(frameId, excluded);
+    for (const id of nested.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
+  }
+
+  return {
+    iframeNodes,
+    frameOwnerBackendNodeIds,
+    frameParentIds,
+    frameExcludedBackendNodeIds,
+    excludedBackendNodeIds,
+    frameGeometryIssues,
+  };
+}
+
+export async function captureViewModel(
+  cdp: CdpRunner,
+  tabId: number,
+  options: CaptureViewModelOptions = {},
+): Promise<CapturedViewModel> {
+  throwIfAborted(options.signal);
+  const target = options.target ?? { tabId };
+  const geometry = options.geometry ?? new GeometryContext(cdp, tabId, undefined, options.signal);
+  let metrics: LayoutMetrics = {};
+  try {
+    metrics = await geometry.layoutMetrics(target);
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    console.debug("[bsk capture] layout metrics unavailable", error);
+  }
+  throwIfAborted(options.signal);
+  const viewport: Viewport = {
+    width: metrics.cssLayoutViewport?.clientWidth ?? 0,
+    height: metrics.cssLayoutViewport?.clientHeight ?? 0,
+  };
+  const layoutUnitsPerCssPixel = snapshotLayoutScale(metrics);
+
+  await cdp.send(tabId, "DOMSnapshot.enable", {});
+  throwIfAborted(options.signal);
+  const snap = await cdp.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
+    computedStyles: REQUESTED_STYLES,
+    includePaintOrder: true,
+    includeDOMRects: true,
+  });
+  throwIfAborted(options.signal);
+
+  const strings = snap.strings ?? [];
+  const documents = snap.documents ?? [];
+  const doc0 = documents[0];
+  if (!doc0?.nodes?.backendNodeId) {
+    return {
+      nodes: [],
+      viewport,
+      iframeNodes: new Map(),
+      excludedBackendNodeIds: new Set(),
+    };
+  }
+
+  const source = { target, frameId: snapshotFrameId(doc0, strings) };
+  const coordinates = snapshotCoordinates(doc0, layoutUnitsPerCssPixel, {
+    x: metrics.cssLayoutViewport?.pageX,
+    y: metrics.cssLayoutViewport?.pageY,
+  });
+  const topContext: FrameContext = {
+    frameId: snapshotFrameId(doc0, strings),
+    ownerFrameBackendNodeId: null,
+    target,
+    projection:
+      coordinates &&
+      [viewport.width, viewport.height].every((size) => Number.isFinite(size) && size > 0)
+        ? {
+            status: "available",
+            projection: {
+              source,
+              geometry: { sourceClips: [], edges: [], topViewport: viewport },
+            },
+          }
+        : { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" },
+    coordinates,
+    layoutUnitsPerCssPixel,
+  };
+  const mainParsed = await normalizeDocument(doc0, strings, topContext, options.signal);
+  const nodes = mainParsed.nodes;
+  const excludedBackendNodeIds = new Set(mainParsed.index.excludedBackendNodeIds);
+
+  const ownerIds = new Set<number>();
+  for (const document of documents) {
+    for (const index of document.nodes?.contentDocumentIndex?.index ?? []) {
+      const id = document.nodes?.backendNodeId?.[index];
+      if (id !== undefined) ownerIds.add(id);
+    }
+  }
+  geometry.registerSnapshotOwners(target, ownerIds);
+  const frameParsed = await parseChildFrameDocuments(
+    documents,
+    strings,
+    0,
+    topContext,
+    geometry,
+    options.signal,
+  );
+  const iframeNodes = frameParsed.iframeNodes;
+  if (topContext.frameId)
+    frameParsed.frameExcludedBackendNodeIds.set(
+      topContext.frameId,
+      mainParsed.index.excludedBackendNodeIds,
+    );
+  for (const id of frameParsed.excludedBackendNodeIds) {
+    excludedBackendNodeIds.add(id);
+  }
+
+  await enrichFormControlStates(cdp, tabId, [nodes, ...iframeNodes.values()], options.signal);
+  throwIfAborted(options.signal);
+
+  const frameNodes = new Map<string, CapturedNode[]>();
+  if (topContext.frameId) frameNodes.set(topContext.frameId, nodes);
+  for (const iframeFrameNodes of iframeNodes.values()) {
+    const frameId = iframeFrameNodes.find((node) => node.frameId)?.frameId;
+    if (frameId) frameNodes.set(frameId, iframeFrameNodes);
+  }
+  for (const [frameId, ownerBackendNodeId] of frameParsed.frameOwnerBackendNodeIds) {
+    if (!frameNodes.has(frameId)) {
+      frameNodes.set(frameId, iframeNodes.get(ownerBackendNodeId) ?? []);
+    }
+  }
+
+  return {
+    nodes,
+    viewport,
+    iframeNodes,
+    frameNodes,
+    frameGeometryIssues: [
+      ...(topContext.projection.status === "available" ? [] : [topContext.projection]),
+      ...frameParsed.frameGeometryIssues,
+    ],
+    frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
+    frameExcludedBackendNodeIds: frameParsed.frameExcludedBackendNodeIds,
+    frameParentIds: frameParsed.frameParentIds,
+    ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
+    excludedBackendNodeIds,
+  };
+}

apps/extension/src/tools/vom/facts.ts

@@ -1,64 +1,10 @@
-import type { Rect, Viewport } from "@browser-skill/vom";
-import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
 import { isOverlayHostNode } from "@/lib/overlay-bridge";
-import type { FrameProjectionIssue } from "../geometry/coordinate-types";
-import type { FrameOwnedAxNode } from "./frame-document";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
 
-export interface CapturedNode {
-  backendNodeId: number;
-  parentBackendNodeId: number | null;
-  frameId?: string;
-  /** Owning iframe backend node id; `null` for the top-level document. */
-  ownerFrameBackendNodeId?: number | null;
-  tag: string;
-  attrs: Record<string, string>;
-  /** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
-  rect: Rect | null;
-  /** Frame-local viewport-relative CSS px before top-level projection. */
-  localRect?: Rect | null;
-  paintOrder: number;
-  position: string;
-  pointerEvents: string;
-  /**
-   * computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
-   * that a non-semantic element (a `<div>`/`<span>` with a click handler)
-   * is actually an interactive control — used by the adapter to surface
-   * custom buttons/checkboxes the AX tree drops as `generic`. Optional like
-   * `textContent`: the live parser always sets it, hand-built fixtures may not.
-   */
-  cursor?: string;
-  /**
-   * Whether the live DOM snapshot provides a painted, non-hidden box for this
-   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
-   * nodes remain authoritative even when they are outside the viewport.
-   */
-  rendered?: boolean;
-  textContent?: string;
-  formState?: "empty" | "filled" | "default";
-  formValue?: string;
-  formDefaultValue?: string;
-  formPlaceholder?: string;
-}
-
-export interface CapturedSurfaceProbe {
-  triggerBackendNodeId: number;
-  triggerPoint?: { x: number; y: number };
-  triggerAction: "hover" | "focus" | string;
-  subItems: string[];
-  confidence?: "high" | "medium" | "low";
-}
-
-/** Narrow input shared by the existing semantic scene/hover consumers. */
-export interface CapturedSceneInput {
-  nodes: CapturedNode[];
-  viewport: Viewport;
-  rootFrameId?: string;
-  excludedBackendNodeIds: ReadonlySet<number>;
-}
-
-/** Bounds retain their snapshot document CSS units until normalization. */
+/** Bounds retain their raw snapshot document layout units until normalization. */
 export interface SnapshotLayout {
-  readonly boundsSpace: "snapshot-document-css";
+  readonly boundsSpace: "snapshot-document-layout";
   bounds?: number[];
   styles: Readonly<Record<string, string>>;
 }
@@ -82,78 +28,40 @@ export interface DecodedDocument {
   nodes: DecodedNode[];
 }
 
-export interface CaptureIssue {
-  /** Owner failure or inherited blockage; absent for other geometry failures. */
-  projectionIssue?: FrameProjectionIssue;
-  target: CdpTarget;
-  frameId?: string;
-  stage: "dom" | "ax" | "ownership" | "geometry" | "forms";
-  reason: "capture-unavailable" | "frame-ownership-unresolved" | "geometry-unavailable";
-}
-
-export interface DocumentFacts<T extends FrameOwnedAxNode> {
-  readonly frame: CdpFrame;
-  readonly index: DocumentIndex;
-  readonly domNodes: CapturedNode[];
-  readonly axNodes: T[];
-}
-
-export interface ObservationFacts<T extends FrameOwnedAxNode> {
-  readonly rootFrameId: string;
-  readonly viewport: Viewport;
-  readonly documents: readonly DocumentFacts<T>[];
-  readonly issues: readonly CaptureIssue[];
-  readonly startedAt: number;
-  readonly finishedAt: number;
-}
-
-export function throwCaptureAborted(signal?: AbortSignal): void {
-  if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
-}
-
-export function isCaptureAbort(error: unknown): boolean {
-  return error instanceof Error && error.name === "AbortError";
-}
-
-/** Called only at bounded block boundaries, not once per node. */
-export async function captureCheckpoint(signal?: AbortSignal): Promise<void> {
-  throwCaptureAborted(signal);
-  await new Promise<void>((resolve) => {
-    const channel = new MessageChannel();
-    channel.port1.onmessage = () => {
-      channel.port1.close();
-      channel.port2.close();
-      resolve();
-    };
-    channel.port2.postMessage(null);
-  });
-  throwCaptureAborted(signal);
-}
-
 /** All snapshot nodes participate, including document and shadow roots. This
  * preserves overlay propagation when the semantic adapter omits those nodes. */
 export async function buildDocumentIndex<T extends DecodedNode>(
   input: readonly T[],
   signal?: AbortSignal,
 ): Promise<DocumentIndex<T>> {
+  const checkpoint = createCaptureCheckpoint(signal);
   const nodes = new Map<number, T>();
   const overlayByNode = new Map<number, boolean>();
   const excludedBackendNodeIds = new Set<number>();
   for (let i = 0; i < input.length; i++) {
-    if (i % 256 === 0) await captureCheckpoint(signal);
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
     const node = input[i];
     nodes.set(node.backendNodeId, node);
   }
   let work = 0;
   for (const node of input) {
-    if (work++ % 256 === 0) await captureCheckpoint(signal);
+    if (work++ % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
     if (overlayByNode.has(node.backendNodeId)) continue;
     const path: DecodedNode[] = [];
     const visiting = new Set<number>();
     let current: DecodedNode | undefined = node;
     let overlay = false;
     while (current && !overlayByNode.has(current.backendNodeId)) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
       if (visiting.has(current.backendNodeId)) {
         // Only an overlay inside the cycle may mark the cycle and its descendants.
         overlay = path
@@ -172,7 +80,10 @@ export async function buildDocumentIndex<T extends DecodedNode>(
     if (current && overlayByNode.has(current.backendNodeId))
       overlay = overlayByNode.get(current.backendNodeId)!;
     for (let i = path.length - 1; i >= 0; i--) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
       const item = path[i];
       overlay = overlay || isOverlayHostNode(item.tag, Object.keys(item.attrs));
       overlayByNode.set(item.backendNodeId, overlay);

apps/extension/src/tools/vom/form-capture.ts

@@ -1,6 +1,6 @@
 import type { CdpRunner } from "../shared";
-import type { CapturedNode } from "./facts";
-import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
+import { isAbortError, throwIfAborted } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
 
 interface RuntimeEvaluateReply {
   result?: { deepSerializedValue?: DeepSerializedValue };

apps/extension/src/tools/vom/frame-capture.ts

@@ -0,0 +1,183 @@
+import type { CdpFrame, CdpFrameGraph } from "@/browser-driver/frame-graph";
+import { type GeometryProjection, projectRectToViewport } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
+import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
+import { type CapturedNode, type CapturedViewModel, captureViewModel } from "./capture";
+import {
+  buildFrameDocuments,
+  type FrameAxBatch,
+  type FrameDocument,
+  type FrameOwnedAxNode,
+} from "./frame-document";
+
+export type FrameAxNode = FrameOwnedAxNode;
+export type CapturedFrameDocument<T extends FrameAxNode> = FrameDocument<T>;
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+function transformFrameNodes(
+  nodes: CapturedNode[],
+  projection: GeometryProjection | null,
+): CapturedNode[] {
+  return nodes.map((node) => ({
+    ...node,
+    rect: projection
+      ? (() => {
+          const bounds = projectRectToViewport(node.rect, projection);
+          return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+        })()
+      : null,
+  }));
+}
+
+async function captureMissingFrameDocuments(
+  cdp: CdpRunner,
+  tabId: number,
+  graph: CdpFrameGraph,
+  captured: CapturedViewModel,
+  geometry: GeometryContext,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!captured.frameNodes) captured.frameNodes = new Map();
+  if (!captured.frameOwnerBackendNodeIds) captured.frameOwnerBackendNodeIds = new Map();
+  if (!captured.frameParentIds) captured.frameParentIds = new Map();
+
+  for (const frame of graph.frames) {
+    if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
+    try {
+      const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
+        signal,
+        geometry,
+        target: frame.target,
+      });
+      if (child.frameExcludedBackendNodeIds?.size) {
+        captured.frameExcludedBackendNodeIds ??= new Map();
+        for (const [id, excluded] of child.frameExcludedBackendNodeIds)
+          captured.frameExcludedBackendNodeIds.set(id, excluded);
+      }
+      if (child.frameGeometryIssues?.length) {
+        (captured.frameGeometryIssues ??= []).push(...child.frameGeometryIssues);
+      }
+      let projection: GeometryProjection | null = null;
+      try {
+        projection = await geometry.targetProjection(frame.frameId);
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        console.debug("[bsk observation] child frame geometry projection failed", {
+          frameId: frame.frameId,
+          err,
+        });
+      }
+      const rootFrameId = child.rootFrameId ?? frame.frameId;
+      const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
+      if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
+      if (rootFrameId !== frame.frameId && !childFrames.has(frame.frameId)) {
+        childFrames.set(
+          frame.frameId,
+          child.nodes.map((node) => ({ ...node, frameId: frame.frameId })),
+        );
+      }
+      for (const [childFrameId, nodes] of childFrames) {
+        captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
+      }
+      if (frame.ownerBackendNodeId !== undefined) {
+        captured.iframeNodes.set(
+          frame.ownerBackendNodeId,
+          captured.frameNodes.get(frame.frameId) ?? [],
+        );
+        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      }
+      if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
+      for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
+        captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);
+      }
+      for (const [childFrameId, parentFrameId] of child.frameParentIds ?? []) {
+        captured.frameParentIds.set(childFrameId, parentFrameId);
+      }
+    } catch (err) {
+      if (isAbortError(err)) throw err;
+      console.debug("[bsk observation] child frame DOM capture failed", {
+        frameId: frame.frameId,
+        err,
+      });
+    }
+  }
+}
+
+async function captureAxTrees<T extends FrameAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  discoveredFrames: CdpFrame[],
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+): Promise<FrameAxBatch<T>[]> {
+  let frames = [...discoveredFrames];
+  const capturedFrameIds = [...(captured.frameNodes?.keys() ?? [])];
+  if (frames.length === 0) {
+    const rootFrameId = captured.rootFrameId ?? capturedFrameIds[0] ?? "root";
+    frames = [{ frameId: rootFrameId, target: { tabId } }];
+  }
+  for (const frameId of capturedFrameIds) {
+    if (!frames.some((frame) => frame.frameId === frameId)) {
+      frames.push({ frameId, target: { tabId } });
+    }
+  }
+
+  let firstFailure: unknown;
+  const trees = await Promise.all(
+    frames.map(async (frame): Promise<FrameAxBatch<T>> => {
+      try {
+        throwIfAborted(signal);
+        await sendToCdpTarget(cdp, frame.target, "Accessibility.enable", {});
+        const result = await sendToCdpTarget<{ nodes?: T[] }>(
+          cdp,
+          frame.target,
+          "Accessibility.getFullAXTree",
+          frame.frameId === "root" ? {} : { frameId: frame.frameId },
+        );
+        throwIfAborted(signal);
+        return {
+          frame,
+          nodes: result.nodes ?? [],
+        };
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        firstFailure ??= err;
+        console.debug("[bsk observation] frame AX capture failed", {
+          frameId: frame.frameId,
+          err,
+        });
+        return { frame, nodes: [] };
+      }
+    }),
+  );
+  const capturedNodeCount = [...captured.iframeNodes.values()].reduce(
+    (count, nodes) => count + nodes.length,
+    captured.nodes.length,
+  );
+  if (firstFailure && capturedNodeCount === 0 && trees.every((tree) => tree.nodes.length === 0)) {
+    throw firstFailure;
+  }
+  return trees;
+}
+
+export async function captureFrameData<T extends FrameAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+  geometry = new GeometryContext(cdp, tabId, undefined, signal),
+): Promise<CapturedFrameDocument<T>[]> {
+  const graph = await geometry.graph();
+  const frames = graph?.frames ?? [];
+  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, geometry, signal);
+  throwIfAborted(signal);
+  const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
+  return buildFrameDocuments(graph, batches, captured, signal);
+}

apps/extension/src/tools/vom/frame-document.ts

@@ -4,8 +4,8 @@ import {
   type CdpTarget,
   cdpTargetKey,
 } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "./facts";
-import { captureCheckpoint } from "./facts";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
 
 export interface FrameOwnedAxNode {
   nodeId: string;
@@ -32,6 +32,9 @@ export interface FrameDomInput {
   nodes: CapturedNode[];
   rootFrameId?: string;
   frameNodes?: ReadonlyMap<string, CapturedNode[]>;
+  frameOwnerBackendNodeIds?: ReadonlyMap<string, number>;
+  frameParentIds?: ReadonlyMap<string, string>;
+  frameExcludedBackendNodeIds?: ReadonlyMap<string, ReadonlySet<number>>;
 }
 
 interface Ownership {
@@ -56,13 +59,27 @@ function targetBackendKey(target: CdpTarget, backendNodeId: number): string {
 function frameList<T extends FrameOwnedAxNode>(
   graph: CdpFrameGraph | null,
   batches: FrameAxBatch<T>[],
+  captured: FrameDomInput,
 ): CdpFrame[] {
   const frames = new Map<string, CdpFrame>();
   for (const frame of graph?.frames ?? []) frames.set(frame.frameId, frame);
   for (const batch of batches) {
     if (!frames.has(batch.frame.frameId)) frames.set(batch.frame.frameId, batch.frame);
   }
-  return [...frames.values()];
+  for (const frameId of captured.frameNodes?.keys() ?? []) {
+    if (!frames.has(frameId))
+      frames.set(frameId, { frameId, target: { tabId: batches[0]?.frame.target.tabId ?? 0 } });
+  }
+  return [...frames.values()].map((frame) => {
+    const ownerBackendNodeId =
+      frame.ownerBackendNodeId ?? captured.frameOwnerBackendNodeIds?.get(frame.frameId);
+    const parentFrameId = frame.parentFrameId ?? captured.frameParentIds?.get(frame.frameId);
+    return {
+      ...frame,
+      ...(ownerBackendNodeId !== undefined ? { ownerBackendNodeId } : {}),
+      ...(parentFrameId ? { parentFrameId } : {}),
+    };
+  });
 }
 
 export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
@@ -70,10 +87,10 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   batches: FrameAxBatch<T>[],
   captured: FrameDomInput,
   signal?: AbortSignal,
-  unresolved?: (frame: CdpFrame) => void,
 ): Promise<FrameDocument<T>[]> {
+  const checkpoint = createCaptureCheckpoint(signal);
   let work = 0;
-  const frames = frameList(graph, batches);
+  const frames = frameList(graph, batches, captured);
   const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
   const rootFrameId = graph?.rootFrameId ?? captured.rootFrameId ?? frames[0]?.frameId;
   const domNodesForFrame = (frameId: string): CapturedNode[] =>
@@ -81,7 +98,10 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   const backendOwner = new Map<string, string>();
   for (const frame of frames) {
     for (const node of domNodesForFrame(frame.frameId)) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
       backendOwner.set(targetBackendKey(frame.target, node.backendNodeId), frame.frameId);
     }
   }
@@ -90,18 +110,23 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   for (const batch of batches) {
     const nodeById = new Map<string, T>();
     for (const node of batch.nodes) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
       nodeById.set(node.nodeId, node);
     }
-    let reported = false;
     const ownershipByNodeId = new Map<string, Ownership>();
-    const resolveOwnership = async (node: T): Promise<Ownership> => {
+    for (const node of batch.nodes) {
       const path: T[] = [];
       const visiting = new Set<string>();
       let current: T | undefined = node;
       let ownership: Ownership = { frameId: batch.frame.frameId, strength: 1 };
       while (current) {
-        if (work++ % 256 === 0) await captureCheckpoint(signal);
+        if (work++ % 256 === 0) {
+          const pending = checkpoint();
+          if (pending) await pending;
+        }
         const cached = ownershipByNodeId.get(current.nodeId);
         if (cached) {
           ownership = cached;
@@ -109,18 +134,8 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
         }
         if (visiting.has(current.nodeId)) break;
         visiting.add(current.nodeId);
-        if (current.frameId) {
-          const frame = frameById.get(current.frameId);
-          // An explicit contradiction must not fall through to a guessed owner.
-          if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(batch.frame.target)) {
-            if (!reported) {
-              unresolved?.(batch.frame);
-              reported = true;
-            }
-            ownership = { frameId: "", strength: 0 };
-            break;
-          }
-          ownership = { frameId: frame.frameId, strength: 4 };
+        if (current.frameId && frameById.has(current.frameId)) {
+          ownership = { frameId: current.frameId, strength: 4 };
           ownershipByNodeId.set(current.nodeId, ownership);
           break;
         }
@@ -137,18 +152,14 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
         current = current.parentId ? nodeById.get(current.parentId) : undefined;
       }
       for (let i = path.length - 1; i >= 0; i--) {
-        if (work++ % 256 === 0) await captureCheckpoint(signal);
+        if (work++ % 256 === 0) {
+          const pending = checkpoint();
+          if (pending) await pending;
+        }
         ownership = { frameId: ownership.frameId, strength: Math.min(2, ownership.strength) };
         ownershipByNodeId.set(path[i].nodeId, ownership);
       }
       if (!ownershipByNodeId.has(node.nodeId)) ownershipByNodeId.set(node.nodeId, ownership);
-      return ownership;
-    };
-
-    for (const node of batch.nodes) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
-      const ownership = await resolveOwnership(node);
-      if (!ownership.frameId) continue;
       const key = targetNodeKey(batch.frame.target, node.nodeId);
       const existing = candidates.get(key);
       if (!existing || ownership.strength > existing.ownership.strength) {
@@ -162,7 +173,10 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   );
   const axNodesByFrame = new Map<string, T[]>();
   for (const candidate of candidates.values()) {
-    if (work++ % 256 === 0) await captureCheckpoint(signal);
+    if (work++ % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
     const { node, target, ownership } = candidate;
     const parentFrameId = node.parentId
       ? ownershipByTargetNode.get(targetNodeKey(target, node.parentId))
@@ -188,5 +202,6 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
     contextScopeId: frame.frameId,
     axNodes: axNodesByFrame.get(frame.frameId) ?? [],
     domNodes: domNodesForFrame(frame.frameId),
+    excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(frame.frameId),
   }));
 }

apps/extension/src/tools/vom/normalize.ts

@@ -1,233 +1,78 @@
-import type { Viewport } from "@browser-skill/vom";
-import { type CdpFrame, type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
-import { type GeometryProjection, projectRectToViewport } from "../geometry";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import {
   type FrameProjectionState,
   projectSnapshotRect,
+  type SnapshotCoordinates,
   snapshotViewportRect,
 } from "../geometry/coordinate-types";
-import { cssViewport, GeometryContext } from "../geometry/frame-context";
-import type { CapturedNode } from "./facts";
-import {
-  buildDocumentIndex,
-  type CaptureIssue,
-  captureCheckpoint,
-  type DocumentIndex,
-  isCaptureAbort,
-  type NodeFacts,
-  throwCaptureAborted,
-} from "./facts";
-import {
-  decodeDocument,
-  type SnapshotDocument,
-  type SnapshotReply,
-  snapshotFrameId,
-} from "./snapshot";
+import { createCaptureCheckpoint } from "./capture-abort";
+import { buildDocumentIndex, type DocumentIndex, type NodeFacts } from "./facts";
+import { decodeDocument, type SnapshotDocument } from "./snapshot";
+
+export interface FrameContext {
+  frameId?: string;
+  ownerFrameBackendNodeId: number | null;
+  projection: FrameProjectionState;
+  target: CdpTarget;
+  coordinates: SnapshotCoordinates | null;
+  layoutUnitsPerCssPixel: number | null;
+}
 
 export interface NormalizedDocument {
+  nodes: NodeFacts[];
   index: DocumentIndex;
-  frame: CdpFrame;
-  domNodes: CapturedNode[];
 }
 
-/** One target's snapshot. Source ownership is checked before interpreting any
- * coordinates. Snapshot and live quad coordinates are deliberately not conflated. */
-export async function normalizeSnapshot(
-  snapshot: SnapshotReply,
-  target: CdpTarget,
-  frames: readonly CdpFrame[],
-  geometry: GeometryContext,
-  issues: CaptureIssue[],
+/** Interpret one document using a supplied projection. No live reads or frame scheduling. */
+export async function normalizeDocument(
+  doc: SnapshotDocument,
+  strings: string[],
+  context: FrameContext,
   signal?: AbortSignal,
-  rootFrameId?: string,
-): Promise<NormalizedDocument[]> {
-  const strings = snapshot.strings ?? [];
-  const raw = snapshot.documents ?? [];
-  const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
-  const sources = new Map<string, SnapshotDocument>();
-  for (const doc of raw) {
-    const id = snapshotFrameId(doc, strings);
-    if (!id || !frameById.has(id) || sources.has(id)) {
-      issues.push({
-        target,
-        frameId: id,
-        stage: "ownership",
-        reason: "frame-ownership-unresolved",
-      });
-      continue;
+): Promise<NormalizedDocument> {
+  const decoded = await decodeDocument(doc, strings, signal);
+  const checkpoint = createCaptureCheckpoint(signal);
+  const nodes: NodeFacts[] = [];
+  for (let i = 0; i < decoded.nodes.length; i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
     }
-    sources.set(id, doc);
-  }
-  let viewport: Viewport = { width: 0, height: 0 };
-  let scrollX = 0,
-    scrollY = 0;
-  try {
-    const measured = cssViewport(await geometry.layoutMetrics(target));
-    viewport = { width: measured.width, height: measured.height };
-    scrollX = measured.scrollX;
-    scrollY = measured.scrollY;
-  } catch (error) {
-    if (isCaptureAbort(error)) throw error;
-  }
-
-  const children = new Map<string, CdpFrame[]>();
-  const pending: CdpFrame[] = [];
-  for (const frame of frames) {
-    if (!frame.parentFrameId || !frameById.has(frame.parentFrameId)) pending.push(frame);
-    else {
-      const siblings = children.get(frame.parentFrameId);
-      if (siblings) siblings.push(frame);
-      else children.set(frame.parentFrameId, [frame]);
-    }
-  }
-  const projections = new Map<string, FrameProjectionState | null>();
-  const result: NormalizedDocument[] = [];
-  let targetProjection: GeometryProjection | null = null;
-  const targetRoot = rootFrameId ? frameById.get(rootFrameId) : undefined;
-  if (target.sessionId && targetRoot) {
-    try {
-      const known = await geometry.frame(targetRoot.frameId);
-      if (known && cdpTargetKey(known.target) === cdpTargetKey(target))
-        targetProjection = await geometry.targetProjection(targetRoot.frameId);
-    } catch (error) {
-      if (isCaptureAbort(error)) throw error;
-    }
-  }
-  const visited = new Set<string>();
-  const remaining = frames[Symbol.iterator]();
-  for (let cursor = 0; visited.size < frames.length; cursor++) {
-    if (cursor >= pending.length) {
-      let next = remaining.next();
-      while (!next.done && visited.has(next.value.frameId)) next = remaining.next();
-      if (next.done) break;
-      pending.push(next.value);
-    }
-    if (cursor % 256 === 0) await captureCheckpoint(signal);
-    const frame = pending[cursor];
-    if (visited.has(frame.frameId)) continue;
-    visited.add(frame.frameId);
-    for (const child of children.get(frame.frameId) ?? []) pending.push(child);
-    const doc = sources.get(frame.frameId);
-    if (!doc) continue;
-    const source = { target, frameId: frame.frameId };
-    const state: FrameProjectionState | null =
-      frame.frameId === rootFrameId
-        ? {
-            status: "available",
-            projection: { source, geometry: { sourceClips: [], edges: [], topViewport: viewport } },
-          }
-        : (projections.get(frame.frameId) ?? null);
-    if (!state && frame.frameId !== rootFrameId)
-      issues.push({
-        target,
-        frameId: frame.frameId,
-        stage: "ownership",
-        reason: "frame-ownership-unresolved",
-      });
-    projections.set(frame.frameId, state);
-    const projection = state?.status === "available" ? state.projection : null;
-    if (!projection || (target.sessionId && !targetProjection))
-      issues.push({
-        target,
-        frameId: frame.frameId,
-        stage: "geometry",
-        reason: "geometry-unavailable",
-        ...(state && state.status !== "available" ? { projectionIssue: state } : {}),
-      });
-
-    // Only direct siblings share this pool. Keep normalization in its existing
-    // breadth-first order, independent of owner read completion order.
-    const siblings = (children.get(frame.frameId) ?? []).filter((child) =>
-      sources.has(child.frameId),
+    const node = decoded.nodes[i];
+    const bounds = node.layout?.bounds ?? [];
+    const input = snapshotViewportRect(
+      bounds,
+      { target: context.target, frameId: context.frameId },
+      context.coordinates,
     );
-    const edge = projection?.geometry.edges[0];
-    const clips = edge
-      ? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
-      : (projection?.geometry.sourceClips ?? []);
-    let next = 0;
-    let failure: unknown;
-    await Promise.all(
-      Array.from({ length: Math.min(4, siblings.length) }, async () => {
-        while (next < siblings.length && !signal?.aborted && !failure) {
-          const child = siblings[next++];
-          const childSource = { target, frameId: child.frameId };
-          if (!projection) {
-            projections.set(
-              child.frameId,
-              state && state.status !== "available"
-                ? {
-                    status: "blocked",
-                    source: childSource,
-                    cause: state.status === "blocked" ? state.cause : state,
-                  }
-                : null,
-            );
-            continue;
-          }
-          if (child.ownerBackendNodeId === undefined) {
-            projections.set(child.frameId, null);
-            continue;
-          }
-          try {
-            projections.set(
-              child.frameId,
-              await geometry.snapshotProjection(
-                childSource,
-                child.ownerBackendNodeId,
-                clips,
-                viewport,
-              ),
-            );
-          } catch (error) {
-            failure ??= error;
-          }
-        }
-      }),
-    );
-    // Join active reads and their cleanup before returning cancellation.
-    if (failure) throw failure;
-    throwCaptureAborted(signal);
-    const decoded = await decodeDocument(doc, strings, signal);
-    const nodes: NodeFacts[] = [];
-    for (let i = 0; i < decoded.nodes.length; i++) {
-      if (i % 256 === 0) await captureCheckpoint(signal);
-      const node = decoded.nodes[i];
-      const input = snapshotViewportRect(node.layout?.bounds ?? [], source, {
-        x: doc.scrollOffsetX ?? (frame.frameId === rootFrameId ? scrollX : 0),
-        y: doc.scrollOffsetY ?? (frame.frameId === rootFrameId ? scrollY : 0),
-      });
-      const local = input?.rect;
-      let rect = input && projection ? projectSnapshotRect(input, projection) : null;
-      if (rect && target.sessionId)
-        rect = targetProjection
-          ? projectRectToViewport(
-              { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
-              targetProjection,
-            )
-          : null;
-      const styles = node.layout?.styles;
-      const visibility = styles?.visibility || "visible";
-      const opacity = styles?.opacity || "1";
-      nodes.push({
-        ...node,
-        frameId: frame.frameId,
-        ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
-        localRect: local ? { x: local.x, y: local.y, w: local.width, h: local.height } : null,
-        rect: rect ? { x: rect.x, y: rect.y, w: rect.width, h: rect.height } : null,
-        rendered:
-          !!local &&
-          visibility !== "hidden" &&
-          visibility !== "collapse" &&
-          (Number.parseFloat(opacity) || 0) > 0,
-      });
-    }
-    const index = await buildDocumentIndex(nodes, signal);
-    const domNodes = nodes.filter((node) => !node.tag.startsWith("#"));
-    result.push({
-      index,
-      frame,
-      domNodes,
+    const local = input?.rect;
+    const rect =
+      input && context.projection.status === "available"
+        ? projectSnapshotRect(input, context.projection.projection)
+        : null;
+    const visibility = node.layout?.styles.visibility || "visible";
+    const opacity = node.layout?.styles.opacity || "1";
+    nodes.push({
+      ...node,
+      ...(context.frameId ? { frameId: context.frameId } : {}),
+      ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
+      localRect: local ? { x: local.x, y: local.y, w: local.width, h: local.height } : null,
+      rect: rect ? { x: rect.x, y: rect.y, w: rect.width, h: rect.height } : null,
+      rendered:
+        bounds.length >= 4 &&
+        bounds.slice(0, 4).every(Number.isFinite) &&
+        bounds[2] > 0 &&
+        bounds[3] > 0 &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0,
     });
   }
-  return result;
+  const index = await buildDocumentIndex(nodes, signal);
+  return {
+    nodes: nodes.filter(
+      (node) => !node.tag.startsWith("#") && !index.excludedBackendNodeIds.has(node.backendNodeId),
+    ),
+    index,
+  };
 }

apps/extension/src/tools/vom/snapshot.ts

@@ -1,6 +1,6 @@
-import { type CdpFrame, type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "./facts";
-import { captureCheckpoint, type DecodedDocument, type DecodedNode } from "./facts";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+import type { DecodedDocument, DecodedNode } from "./facts";
 export const REQUESTED_STYLES = [
   "position",
   "pointer-events",
@@ -23,7 +23,6 @@ interface RareBooleanData {
 
 export interface SnapshotDocument {
   frameId?: string | number;
-  documentURL?: number;
   scrollOffsetX?: number;
   scrollOffsetY?: number;
   nodes?: {
@@ -87,7 +86,7 @@ function str(strings: string[], idx: number | undefined): string {
   return strings[idx] ?? "";
 }
 
-function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
+export function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
   const out = new Map<number, number>();
   if (!sparse?.index || !sparse.value) return out;
   for (let i = 0; i < sparse.index.length; i++) {
@@ -103,6 +102,7 @@ export async function decodeDocument(
   strings: string[],
   signal?: AbortSignal,
 ): Promise<DecodedDocument> {
+  const checkpoint = createCaptureCheckpoint(signal);
   const dn = doc.nodes;
   const dl = doc.layout;
   if (!dn?.backendNodeId) {
@@ -112,7 +112,10 @@ export async function decodeDocument(
   const count = dn.backendNodeId.length;
   const layoutByNode = new Map<number, number>();
   for (let i = 0; i < (dl?.nodeIndex?.length ?? 0); i++) {
-    if (i % 256 === 0) await captureCheckpoint(signal);
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
     layoutByNode.set(dl!.nodeIndex![i], i);
   }
 
@@ -127,7 +130,10 @@ export async function decodeDocument(
   const nodeTextContent = new Map<number, string[]>();
   if (dn.nodeValue) {
     for (let n = 0; n < count; n++) {
-      if (n % 256 === 0) await captureCheckpoint(signal);
+      if (n % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
       const nvIdx = dn.nodeValue[n] ?? -1;
       if (nvIdx < 0) continue;
       const text = str(strings, nvIdx).trim();
@@ -144,7 +150,10 @@ export async function decodeDocument(
   // Decode fields without assigning a coordinate projection or semantic policy.
   const nodes: DecodedNode[] = [];
   for (let n = 0; n < count; n++) {
-    if (n % 256 === 0) await captureCheckpoint(signal);
+    if (n % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
     const backendNodeId = dn.backendNodeId[n];
     const parentIdx = dn.parentIndex?.[n] ?? -1;
     const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
@@ -164,7 +173,7 @@ export async function decodeDocument(
       li === undefined
         ? undefined
         : {
-            boundsSpace: "snapshot-document-css" as const,
+            boundsSpace: "snapshot-document-layout" as const,
             bounds: dl?.bounds?.[li],
             styles,
           };
@@ -213,68 +222,3 @@ export async function decodeDocument(
   }
   return { nodes };
 }
-
-/** Snapshot membership and same-target edges are current response evidence.
- * The earlier graph only supplies compatible metadata and cross-target edges. */
-export function describeSnapshotFrames(
-  snapshot: SnapshotReply,
-  target: CdpTarget,
-  hintById: ReadonlyMap<string, CdpFrame>,
-  pageUrl?: string,
-): { frames: CdpFrame[]; ids: Set<string>; rootFrameId?: string } {
-  const raw = snapshot.documents ?? [];
-  const strings = snapshot.strings ?? [];
-  const ids = new Set<string>();
-  const invalid = new Set<string>();
-  const frames = raw.map((doc) => {
-    const frameId = snapshotFrameId(doc, strings);
-    if (!frameId) return undefined;
-    if (ids.has(frameId)) invalid.add(frameId);
-    ids.add(frameId);
-    const hint = hintById.get(frameId);
-    const compatible =
-      hint && cdpTargetKey(hint.target) === cdpTargetKey(target) ? hint : undefined;
-    const url =
-      (doc.documentURL === undefined ? undefined : strings[doc.documentURL]) || compatible?.url;
-    return { frameId, target, ...(url ? { url } : {}) } as CdpFrame;
-  });
-  const root = frames[0];
-  if (root) {
-    const hint = hintById.get(root.frameId);
-    const parent = hint?.parentFrameId ? hintById.get(hint.parentFrameId) : undefined;
-    if (
-      target.sessionId &&
-      hint &&
-      cdpTargetKey(hint.target) === cdpTargetKey(target) &&
-      parent &&
-      cdpTargetKey(parent.target) !== cdpTargetKey(target)
-    ) {
-      root.parentFrameId = parent.frameId;
-      root.ownerBackendNodeId = hint.ownerBackendNodeId;
-    }
-    if (!target.sessionId && !root.url && pageUrl) root.url = pageUrl;
-  }
-  const owned = new Set<string>();
-  for (let i = 0; i < raw.length; i++) {
-    const edges = raw[i].nodes?.contentDocumentIndex;
-    const parent = frames[i];
-    if (!parent || !edges) continue;
-    for (let e = 0; e < edges.index.length; e++) {
-      const child = frames[edges.value[e]];
-      const owner = raw[i].nodes?.backendNodeId?.[edges.index[e]];
-      if (!child || owner === undefined) continue;
-      if (child === root || child === parent || owned.has(child.frameId)) {
-        invalid.add(child.frameId);
-        continue;
-      }
-      owned.add(child.frameId);
-      child.parentFrameId = parent.frameId;
-      child.ownerBackendNodeId = owner;
-    }
-  }
-  return {
-    frames: frames.filter((frame): frame is CdpFrame => !!frame && !invalid.has(frame.frameId)),
-    ids,
-    rootFrameId: root?.frameId,
-  };
-}

crates/bsk-cli/src/cli/business_rpc.rs

@@ -73,6 +73,14 @@ where
     P: Serialize + Send + 'static,
     R: DeserializeOwned + Send + 'static,
 {
+    let parent_cancel = stdin_cancellation();
+    if parent_cancel.as_ref().is_some_and(|rx| *rx.borrow()) {
+        return Err(CliError::from_rpc(RpcError {
+            code: ErrorCode::Cancelled,
+            message: "parent closed the cancellation pipe".into(),
+            data: Some(serde_json::json!({"reason": "cancelled_before_dispatch"})),
+        }));
+    }
     let rpc_id: RpcId = format!("{}-{}", rpc_id_prefix, random_short_id());
     let mut client = IpcClient::connect(sock.clone()).await?;
     let rpc_id_for_call = rpc_id.clone();
@@ -88,16 +96,16 @@ where
     let outcome = tokio::select! {
         biased;
         res = &mut main_fut => res?,
-        sig = wait_for_sigint() => {
-            sig.context("install SIGINT handler").map_err(CliError::Local)?;
-            debug!(rpc_id = %rpc_id_for_cancel, "SIGINT: forwarding cancel to daemon");
+        sig = wait_for_cancel(parent_cancel) => {
+            sig.context("wait for cancellation").map_err(CliError::Local)?;
+            debug!(rpc_id = %rpc_id_for_cancel, "forwarding cancel to daemon");
             let _ = send_cancel(&sock, &rpc_id_for_cancel).await;
             match tokio::time::timeout(CANCEL_RESPONSE_GRACE, &mut main_fut).await {
                 Ok(res) => res?,
                 Err(_) => {
                     debug!(
                         rpc_id = %rpc_id_for_cancel,
-                        "SIGINT: cancel grace elapsed; synthesising cancelled error"
+                        "cancel grace elapsed; synthesising cancelled error"
                     );
                     return Err(CliError::from_rpc(RpcError {
                         code: ErrorCode::Cancelled,
@@ -112,6 +120,46 @@ where
     outcome.map_err(CliError::from_rpc)
 }
 
+/// Release caller-owned staging even after cancellation. This deliberately
+/// exposes only transfer.release, not a general bypass for business RPCs.
+/// The entire batch, including connection setup, shares one bounded budget.
+pub fn release_transfers<'a>(
+    sock: &Path,
+    transfer_ids: impl IntoIterator<Item = &'a str>,
+) -> Result<(), CliError> {
+    use bsk_protocol::tools::{TransferIdParams, TransferReleaseResult};
+    const CLEANUP_TIMEOUT: Duration = Duration::from_secs(5);
+    let ids: Vec<_> = transfer_ids.into_iter().collect();
+    if ids.is_empty() {
+        return Ok(());
+    }
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .context("build runtime for transfer cleanup")?;
+    rt.block_on(async {
+        tokio::time::timeout(CLEANUP_TIMEOUT, async {
+            let mut client = IpcClient::connect(sock).await?;
+            for id in ids {
+                client
+                    .call::<_, TransferReleaseResult>(
+                        "transfer-release",
+                        Method::TransferRelease,
+                        Some(TransferIdParams {
+                            transfer_id: id.to_string(),
+                        }),
+                        CLEANUP_TIMEOUT,
+                    )
+                    .await?
+                    .map_err(CliError::from_rpc)?;
+            }
+            Ok::<_, CliError>(())
+        })
+        .await
+        .context("transfer cleanup exceeded its total time budget")?
+    })
+}
+
 /// Send a `cancel { rpc_id }` frame over a fresh connection so it
 /// lands on the daemon while the original call is still parked.
 ///
@@ -146,8 +194,57 @@ fn random_short_id() -> String {
     bytes.iter().map(|b| format!("{b:02x}")).collect()
 }
 
-/// Wait for either Ctrl-C or process SIGTERM. Returning here means
-/// the user has asked us to stop.
+/// Opt-in control pipe for parent processes that cannot send Ctrl-C (Node on
+/// Windows). One reader survives the short-lived runtimes used by multi-RPC
+/// commands such as upload. Ordinary CLI stdin and terminal Ctrl-C are unchanged.
+fn stdin_cancellation() -> Option<tokio::sync::watch::Receiver<bool>> {
+    if std::env::var("BSK_CANCEL_ON_STDIN_CLOSE").as_deref() != Ok("1") {
+        return None;
+    }
+    static CANCEL: std::sync::OnceLock<tokio::sync::watch::Receiver<bool>> =
+        std::sync::OnceLock::new();
+    Some(
+        CANCEL
+            .get_or_init(|| {
+                let (tx, rx) = tokio::sync::watch::channel(false);
+                std::thread::spawn(move || {
+                    use std::io::Read;
+                    let mut stdin = std::io::stdin().lock();
+                    let mut buf = [0; 64];
+                    loop {
+                        match stdin.read(&mut buf) {
+                            Ok(0) => break,
+                            Ok(_) => {}
+                            Err(err) if err.kind() == std::io::ErrorKind::Interrupted => continue,
+                            Err(_) => break,
+                        }
+                    }
+                    let _ = tx.send(true);
+                });
+                rx
+            })
+            .clone(),
+    )
+}
+
+async fn wait_for_cancel(
+    parent_cancel: Option<tokio::sync::watch::Receiver<bool>>,
+) -> anyhow::Result<()> {
+    let parent_closed = async move {
+        match parent_cancel {
+            Some(mut rx) => {
+                let _ = rx.wait_for(|closed| *closed).await;
+            }
+            None => std::future::pending::<()>().await,
+        }
+    };
+    tokio::select! {
+        result = wait_for_sigint() => result,
+        _ = parent_closed => Ok(()),
+    }
+}
+
+/// Wait for terminal Ctrl-C.
 async fn wait_for_sigint() -> anyhow::Result<()> {
     tokio::signal::ctrl_c().await.context("listen for SIGINT")?;
     Ok(())

crates/bsk-cli/src/cli/download.rs

@@ -9,8 +9,7 @@ use anyhow::Context;
 use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
-    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult, TransferIdParams,
-    TransferReleaseResult,
+    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult,
 };
 use clap::Args;
 use uuid::Uuid;
@@ -70,13 +69,7 @@ pub fn dispatch(args: DownloadArgs, format: Format) -> Result<(), CliError> {
         CliError::Local(anyhow::anyhow!("daemon returned no download transfer id"))
     })?;
     let write_result = write_transfer(&info.sock_path, &transfer_id, &args.out, args.overwrite);
-    let _: Result<TransferReleaseResult, CliError> = crate::cli::business_rpc::call(
-        info.sock_path,
-        "transfer-release",
-        Method::TransferRelease,
-        Some(TransferIdParams { transfer_id }),
-        Duration::from_secs(5),
-    );
+    let _ = crate::cli::business_rpc::release_transfers(&info.sock_path, [transfer_id.as_str()]);
     write_result?;
     match format {
         Format::Json => {

crates/bsk-cli/src/cli/upload.rs

@@ -10,8 +10,7 @@ use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
     TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
-    TransferIdParams, TransferReadyResult, TransferReleaseResult, UploadFile, UploadMode,
-    UploadParams, UploadResult,
+    TransferIdParams, TransferReadyResult, UploadFile, UploadMode, UploadParams, UploadResult,
 };
 use clap::{Args, ValueEnum};
 
@@ -69,14 +68,12 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
     let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
     let mut staged = Vec::new();
     for path in &args.files {
-        match stage_file(&info.sock_path, &args.session, path) {
-            Ok(file) => staged.push(file),
-            Err(err) => {
-                for (id, _) in &staged {
-                    let _ = release(&info.sock_path, id);
-                }
-                return Err(err);
-            }
+        if let Err(err) = stage_file(&info.sock_path, &args.session, path, &mut staged) {
+            let _ = crate::cli::business_rpc::release_transfers(
+                &info.sock_path,
+                staged.iter().map(|(id, _)| id.as_str()),
+            );
+            return Err(err);
         }
     }
     let params = UploadParams {
@@ -102,6 +99,17 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
         Some(params),
         ipc_timeout(args.timeout),
     );
+    // The helper can reject cancellation before handing any request to the
+    // daemon. In that case staging still belongs to this CLI.
+    if result.as_ref().is_err_and(|err| {
+        err.data()
+            .is_some_and(|data| data["reason"] == "cancelled_before_dispatch")
+    }) {
+        let _ = crate::cli::business_rpc::release_transfers(
+            &info.sock_path,
+            staged.iter().map(|(id, _)| id.as_str()),
+        );
+    }
     // Once tool.upload is dispatched, staging ownership belongs to the
     // session. A transport timeout cannot prove that Chrome did not attach
     // the file, so releasing here could invalidate a late successful attach.
@@ -118,7 +126,12 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
     Ok(())
 }
 
-fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, String), CliError> {
+fn stage_file(
+    sock: &Path,
+    session: &str,
+    path: &PathBuf,
+    staged: &mut Vec<(String, String)>,
+) -> Result<(), CliError> {
     let mut file = File::open(path)
         .with_context(|| format!("open upload file {}", path.display()))
         .map_err(CliError::Local)?;
@@ -149,55 +162,39 @@ fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, Str
         }),
         Duration::from_secs(10),
     )?;
-    let staged = (|| {
-        let mut offset = 0u64;
-        let mut buf = vec![0u8; begin.chunk_size as usize];
-        loop {
-            let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
-            if n == 0 {
-                break;
-            }
-            let reply: TransferChunkResult = crate::cli::business_rpc::call(
-                sock.to_path_buf(),
-                "transfer-chunk",
-                Method::TransferChunk,
-                Some(TransferChunkParams {
-                    transfer_id: begin.transfer_id.clone(),
-                    offset,
-                    data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
-                }),
-                Duration::from_secs(30),
-            )?;
-            offset = reply.next_offset;
+    // Record ownership immediately so one error path releases both completed
+    // files and the current partially staged file.
+    staged.push((begin.transfer_id.clone(), name));
+    let mut offset = 0u64;
+    let mut buf = vec![0u8; begin.chunk_size as usize];
+    loop {
+        let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
+        if n == 0 {
+            break;
         }
-        let _: TransferReadyResult = crate::cli::business_rpc::call(
+        let reply: TransferChunkResult = crate::cli::business_rpc::call(
             sock.to_path_buf(),
-            "transfer-finish",
-            Method::TransferFinish,
-            Some(TransferIdParams {
+            "transfer-chunk",
+            Method::TransferChunk,
+            Some(TransferChunkParams {
                 transfer_id: begin.transfer_id.clone(),
+                offset,
+                data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
             }),
-            Duration::from_secs(10),
+            Duration::from_secs(30),
         )?;
-        Ok::<_, CliError>(())
-    })();
-    if let Err(err) = staged {
-        let _ = release(sock, &begin.transfer_id);
-        return Err(err);
+        offset = reply.next_offset;
     }
-    Ok((begin.transfer_id, name))
-}
-
-fn release(sock: &Path, id: &str) -> Result<TransferReleaseResult, CliError> {
-    crate::cli::business_rpc::call(
+    let _: TransferReadyResult = crate::cli::business_rpc::call(
         sock.to_path_buf(),
-        "transfer-release",
-        Method::TransferRelease,
+        "transfer-finish",
+        Method::TransferFinish,
         Some(TransferIdParams {
-            transfer_id: id.to_string(),
+            transfer_id: begin.transfer_id.clone(),
         }),
-        Duration::from_secs(5),
-    )
+        Duration::from_secs(10),
+    )?;
+    Ok(())
 }
 
 fn ipc_timeout(timeout_ms: u32) -> Duration {

crates/bsk-cli/tests/windows_parent_cancel.rs

@@ -0,0 +1,342 @@
+//! Real Windows CLI cancellation, including caller-owned transfer cleanup.
+#![cfg(windows)]
+
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use bsk::daemon::{file_transfer::TransferRegistry, info::DaemonInfo};
+use bsk_protocol::tools::{TransferBeginParams, TransferIdParams};
+use bsk_protocol::{ErrorCode, Frame, Method, ResponseBody, ResponseFrame, RpcError};
+use serde_json::json;
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::net::windows::named_pipe::ServerOptions;
+use tokio::process::Command;
+use tokio::sync::{Notify, watch};
+
+fn response<T: serde::Serialize>(result: Result<T, RpcError>) -> ResponseBody {
+    match result {
+        Ok(value) => ResponseBody::Ok(serde_json::to_value(value).unwrap()),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+#[test]
+fn stdin_close_cancels_business_but_releases_resources_with_a_bounded_budget() {
+    // Resolve the production registry's root before starting any runtime threads.
+    let registry_home = tempfile::tempdir().unwrap();
+    let original_home = std::env::var_os("BSK_HOME");
+    unsafe {
+        std::env::set_var("BSK_HOME", registry_home.path());
+    }
+    let transfers = Arc::new(TransferRegistry::new().unwrap());
+    unsafe {
+        match original_home {
+            Some(value) => std::env::set_var("BSK_HOME", value),
+            None => std::env::remove_var("BSK_HOME"),
+        }
+    }
+    transfers.initialize().unwrap();
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(exercise(
+            transfers,
+            &registry_home.path().join("run/transfers"),
+        ));
+}
+
+async fn exercise(transfers: Arc<TransferRegistry>, staging_root: &Path) {
+    for mode in [
+        "wait",
+        "upload",
+        "upload-multi",
+        "upload-before-dispatch",
+        "download",
+        "upload-multi-stall",
+        "ordinary",
+    ] {
+        let home = tempfile::tempdir().unwrap();
+        let pipe_name = format!(r"\\.\pipe\bsk-parent-cancel-{}", uuid::Uuid::new_v4());
+        let info = DaemonInfo::now(std::process::id(), (&pipe_name).into(), 0, "0.2.0");
+        std::fs::write(
+            home.path().join("daemon.json"),
+            serde_json::to_vec(&info).unwrap(),
+        )
+        .unwrap();
+        let mut pipe = ServerOptions::new()
+            .first_pipe_instance(true)
+            .create(&pipe_name)
+            .unwrap();
+        let registered = Arc::new(Notify::new());
+        let pending = Arc::new(Mutex::new(None::<String>));
+        let ids = Arc::new(Mutex::new(Vec::<String>::new()));
+        let released = Arc::new(Mutex::new(Vec::<String>::new()));
+        let received = Arc::new(Mutex::new(Vec::<Method>::new()));
+        let download_id = if mode == "download" {
+            let staging = transfers.begin_download("fixture").unwrap();
+            let browser_dir = home.path().join("BrowserSkill").join(&staging.transfer_id);
+            std::fs::create_dir_all(&browser_dir).unwrap();
+            let file = browser_dir.join("download.txt");
+            std::fs::write(&file, b"download fixture").unwrap();
+            transfers
+                .import_download(&staging.transfer_id, &file)
+                .unwrap();
+            ids.lock().unwrap().push(staging.transfer_id.clone());
+            Some(staging.transfer_id)
+        } else {
+            None
+        };
+        let (cancel, cancelled) = watch::channel(false);
+        let ready = Arc::clone(&registered);
+        let name = pipe_name.clone();
+        let registry = Arc::clone(&transfers);
+        let server_ids = Arc::clone(&ids);
+        let server_released = Arc::clone(&released);
+        let server_received = Arc::clone(&received);
+        let server = tokio::spawn(async move {
+            let mut connections = tokio::task::JoinSet::new();
+            loop {
+                pipe.connect().await.unwrap();
+                let next = ServerOptions::new().create(&name).unwrap();
+                let connection = std::mem::replace(&mut pipe, next);
+                let ready = Arc::clone(&ready);
+                let pending = Arc::clone(&pending);
+                let cancel = cancel.clone();
+                let mut cancelled = cancelled.clone();
+                let name = name.clone();
+                let registry = Arc::clone(&registry);
+                let ids = Arc::clone(&server_ids);
+                let released = Arc::clone(&server_released);
+                let received = Arc::clone(&server_received);
+                let download_id = download_id.clone();
+                connections.spawn(async move {
+                    let (read, mut write) = tokio::io::split(connection);
+                    let mut reader = BufReader::new(read);
+                    let mut line = String::new();
+                    while reader.read_line(&mut line).await.unwrap_or(0) > 0 {
+                        let Frame::Request(req) = serde_json::from_str::<Frame>(&line).unwrap()
+                        else {
+                            panic!("expected request");
+                        };
+                        line.clear();
+                        received.lock().unwrap().push(req.method.clone());
+                        let params = req.params.clone().unwrap_or_default();
+                        let body = match req.method {
+                            Method::SystemStatus => ResponseBody::Ok(json!({
+                                "daemon_version": "0.2.0", "protocol_version": "1.1",
+                                "pid": std::process::id(), "uptime_secs": 0,
+                                "ws_port": 0, "sock_path": name,
+                                "browsers": [], "sessions": [], "version_skew_browsers": []
+                            })),
+                            Method::TransferBegin => {
+                                let begin = registry
+                                    .begin_upload(serde_json::from_value(params).unwrap())
+                                    .unwrap();
+                                ids.lock().unwrap().push(begin.transfer_id.clone());
+                                response(Ok(begin))
+                            }
+                            Method::ToolDownload => ResponseBody::Ok(json!({
+                                "tab_id": 1, "suggested_filename": "download.txt",
+                                "byte_size": 16, "transfer_id": download_id,
+                            })),
+                            Method::ToolWaitMs if mode == "ordinary" => {
+                                ResponseBody::Ok(json!({"waited_ms": 1}))
+                            }
+                            Method::TransferChunk
+                                if mode == "upload-before-dispatch"
+                                    || (mode.contains("multi")
+                                        && ids.lock().unwrap().len() == 1) =>
+                            {
+                                response(
+                                    registry.write_chunk(serde_json::from_value(params).unwrap()),
+                                )
+                            }
+                            Method::TransferFinish if mode != "upload-before-dispatch" => response(
+                                registry.finish_upload(serde_json::from_value(params).unwrap()),
+                            ),
+                            Method::ToolWaitMs
+                            | Method::TransferChunk
+                            | Method::TransferRead
+                            | Method::TransferFinish => {
+                                *pending.lock().unwrap() = Some(req.id.clone());
+                                ready.notify_one();
+                                cancelled.wait_for(|value| *value).await.unwrap();
+                                if mode == "upload-before-dispatch" {
+                                    // Finish won the race with cancellation, but tool.upload must
+                                    // not be dispatched and the CLI still owns the staging.
+                                    response(
+                                        registry
+                                            .finish_upload(serde_json::from_value(params).unwrap()),
+                                    )
+                                } else {
+                                    ResponseBody::Err(RpcError {
+                                        code: ErrorCode::Cancelled,
+                                        message: "parent cancellation reached daemon".into(),
+                                        data: None,
+                                    })
+                                }
+                            }
+                            Method::Cancel => {
+                                let target = params["rpc_id"].as_str().unwrap();
+                                assert_eq!(pending.lock().unwrap().as_deref(), Some(target));
+                                cancel.send(true).unwrap();
+                                ResponseBody::Ok(json!({"cancelled": true}))
+                            }
+                            Method::TransferRelease => {
+                                let params: TransferIdParams =
+                                    serde_json::from_value(params).unwrap();
+                                released.lock().unwrap().push(params.transfer_id.clone());
+                                if mode.contains("stall") {
+                                    std::future::pending::<()>().await;
+                                }
+                                response(Ok(registry.release(params)))
+                            }
+                            other => panic!("unexpected request after cancellation: {other:?}"),
+                        };
+                        let response = Frame::Response(ResponseFrame { id: req.id, body });
+                        let mut bytes = serde_json::to_vec(&response).unwrap();
+                        bytes.push(b'\n');
+                        if write.write_all(&bytes).await.is_err() {
+                            break;
+                        }
+                    }
+                });
+            }
+        });
+
+        let mut cmd = Command::new(env!("CARGO_BIN_EXE_bsk"));
+        cmd.env("BSK_HOME", home.path())
+            .env("BSK_AUTO_UPDATE", "off")
+            .env_remove("BSK_CANCEL_ON_STDIN_CLOSE")
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .creation_flags(0x0800_0000)
+            .kill_on_drop(true);
+        if mode.starts_with("upload") {
+            let source = home.path().join("upload.txt");
+            // Declare 300 MiB without allocating or transferring that much data.
+            std::fs::File::create(&source)
+                .unwrap()
+                .set_len(if mode == "upload-before-dispatch" {
+                    16
+                } else {
+                    300 * 1024 * 1024
+                })
+                .unwrap();
+            cmd.args(["upload", "--session", "fixture", "--selector", "input"]);
+            if mode.contains("multi") {
+                let first = home.path().join("first.txt");
+                std::fs::write(&first, b"first file").unwrap();
+                cmd.arg("--file").arg(first);
+            }
+            cmd.arg("--file").arg(source);
+        } else if mode == "download" {
+            let out = home.path().join("out.txt");
+            std::fs::write(&out, b"existing output").unwrap();
+            cmd.args([
+                "download",
+                "--session",
+                "fixture",
+                "--selector",
+                "a",
+                "--overwrite",
+                "--out",
+            ])
+            .arg(out);
+        } else {
+            cmd.args(["wait-ms", if mode == "ordinary" { "1ms" } else { "60s" }]);
+        }
+        cmd.arg("--json");
+        if mode == "ordinary" {
+            cmd.stdin(std::process::Stdio::null());
+        } else {
+            cmd.env("BSK_CANCEL_ON_STDIN_CLOSE", "1")
+                .stdin(std::process::Stdio::piped());
+        }
+        let mut child = cmd.spawn().unwrap();
+        if mode != "ordinary" {
+            tokio::time::timeout(Duration::from_secs(10), registered.notified())
+                .await
+                .expect("CLI registered business RPC");
+            child
+                .stdin
+                .as_mut()
+                .unwrap()
+                .write_all(b"still connected")
+                .await
+                .unwrap();
+            drop(child.stdin.take());
+        }
+        let start = Instant::now();
+        let output = tokio::time::timeout(Duration::from_secs(8), child.wait_with_output())
+            .await
+            .expect("CLI must settle promptly, including cleanup")
+            .unwrap();
+        server.abort();
+        let _ = server.await;
+        assert_eq!(
+            output.status.code(),
+            Some(if mode == "ordinary" { 0 } else { 2 }),
+            "{mode}: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        if mode != "ordinary" {
+            let body: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+            assert_eq!(body["code"], "cancelled");
+            if mode != "upload-before-dispatch" {
+                assert_eq!(body["message"], "parent cancellation reached daemon");
+            }
+            let received = received.lock().unwrap();
+            let cancel = received.iter().position(|m| *m == Method::Cancel).unwrap();
+            assert!(
+                received[cancel + 1..]
+                    .iter()
+                    .all(|m| *m == Method::TransferRelease),
+                "only cleanup may follow cancellation: {received:?}"
+            );
+        }
+        let ids = ids.lock().unwrap();
+        if mode.contains("stall") {
+            assert_eq!(released.lock().unwrap().len(), 1);
+            assert!(start.elapsed() >= Duration::from_secs(4));
+            // The CLI cannot force an unresponsive daemon to clean up.
+            transfers.release_session("fixture");
+        } else {
+            assert_eq!(
+                *released.lock().unwrap(),
+                *ids,
+                "{mode}: every allocation must be released"
+            );
+            for id in ids.iter() {
+                assert!(!staging_root.join(id).exists(), "staging leaked: {id}");
+            }
+            if mode.starts_with("upload") {
+                let retry = transfers
+                    .begin_upload(TransferBeginParams {
+                        session_id: "fixture".into(),
+                        name: "retry.txt".into(),
+                        byte_size: 300 * 1024 * 1024,
+                    })
+                    .expect("same session must have room for another 300 MiB upload");
+                transfers.release(TransferIdParams {
+                    transfer_id: retry.transfer_id,
+                });
+            }
+        }
+        if mode == "download" {
+            assert_eq!(
+                std::fs::read(home.path().join("out.txt")).unwrap(),
+                b"existing output"
+            );
+            assert!(
+                !std::fs::read_dir(home.path())
+                    .unwrap()
+                    .flatten()
+                    .any(|entry| entry.file_name().to_string_lossy().ends_with(".part"))
+            );
+        }
+    }
+}

evals/browser/cases/regression/snapshot-coordinates/README.md

@@ -0,0 +1,44 @@
+# DOMSnapshot layout-unit regression (#195)
+
+Source: https://github.com/Tencent/BrowserSkill/pull/195
+
+DOMSnapshot bounds and document scroll offsets retain Blink layout units. Treating them as CSS
+pixels changes both positions and sizes under device scaling/browser zoom, before iframe
+projection or viewport clipping even starts.
+
+The fixture contains a scrolled root, a scrolled same-process iframe, an OOPIF served from the
+other loopback hostname, and a nested iframe in each. Owners have borders, padding and CSS
+transforms. The geometry test compares the production capture's local and top-level rectangles
+against independent DOM border boxes, with at most 2 CSS pixels of layout rounding. It also
+checks that each target reads layout metrics only once. No credentials or personal tabs are used.
+
+Run the geometric assertions with Node 22+ and a local Chrome executable:
+
+```sh
+BSK_GEOMETRY_CHROME=/path/to/chrome pnpm --filter @browser-skill/extension exec vitest run \
+  src/tools/__tests__/snapshot-coordinates.browser.test.ts
+```
+
+The test launches and cleans up its own headless Chrome profiles. It explicitly verifies the
+requested browser zoom and OOPIF topology, so unsupported setups fail rather than silently
+testing a different configuration. It is skipped in ordinary unit runs unless the executable
+is specified. No browser download or new package dependency is required.
+
+The corpus smoke case checks fixture readiness and observable semantics through the real CLI:
+
+```sh
+BSK_AUTO_UPDATE=off pnpm eval:browser smoke --case snapshot-coordinates --bsk ./target/debug/bsk
+```
+
+Smoke alone does **not** certify coordinate accuracy; CLI observations do not expose raw boxes.
+Use the geometric test above for the regression's numeric assertions.
+
+## Separate existing boundary
+
+The OOPIF root uses non-occupying scrollbars in the unit-conversion regression. Root and
+same-process frames retain normal scrollbars. Append `&classic-scrollbars` to the fixture URL
+to reproduce the separate existing OOPIF projection issue: `targetProjection()` maps the CSS
+layout viewport (which excludes occupying scrollbars) onto the entire owner content quad.
+This inflates the projected coordinates when scrollbars occupy space. Main already has that
+mapping; fixing it also changes shared live geometry and is outside this snapshot-unit fix.
+The test does not relax its numeric tolerance to absorb that error.

evals/browser/cases/regression/snapshot-coordinates/chrome.mjs

@@ -0,0 +1,99 @@
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// This regression owns its browser/profile. It never attaches to a user's Chrome.
+export async function withChrome({ executable, deviceScale, zoom }, run) {
+  const profile = await mkdtemp(join(tmpdir(), "bsk-snapshot-coordinates-"));
+  let chrome;
+  let socket;
+  const pending = new Map();
+  try {
+    await mkdir(join(profile, "Default"));
+    await writeFile(
+      join(profile, "Default", "Preferences"),
+      JSON.stringify({
+        partition: { default_zoom_level: { x: Math.log(zoom) / Math.log(1.2) } },
+      }),
+    );
+    chrome = spawn(
+      executable,
+      [
+        "--headless=new",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-extensions",
+        "--site-per-process",
+        "--remote-debugging-port=0",
+        "--window-size=1600,1200",
+        `--force-device-scale-factor=${deviceScale}`,
+        `--user-data-dir=${profile}`,
+        "about:blank",
+      ],
+      { stdio: ["ignore", "ignore", "pipe"] },
+    );
+    const endpoint = await new Promise((resolve, reject) => {
+      let output = "";
+      const timeout = setTimeout(
+        () => reject(new Error(`Chrome startup timed out: ${output}`)),
+        15_000,
+      );
+      const fail = (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      };
+      chrome.once("error", fail);
+      chrome.once("exit", (code) => fail(new Error(`Chrome exited (${code}): ${output}`)));
+      chrome.stderr.on("data", (chunk) => {
+        output += chunk;
+        const match = output.match(/DevTools listening on (ws:\/\/\S+)/);
+        if (match) {
+          clearTimeout(timeout);
+          resolve(match[1]);
+        }
+      });
+    });
+    socket = new WebSocket(endpoint);
+    await new Promise((resolve, reject) => {
+      socket.addEventListener("open", resolve, { once: true });
+      socket.addEventListener("error", reject, { once: true });
+    });
+    socket.addEventListener("message", ({ data }) => {
+      const reply = JSON.parse(data);
+      const request = pending.get(reply.id);
+      if (!request) return;
+      clearTimeout(request.timeout);
+      pending.delete(reply.id);
+      if (reply.error) request.reject(new Error(JSON.stringify(reply.error)));
+      else request.resolve(reply.result);
+    });
+    let sequence = 0;
+    const send = (method, params = {}, sessionId) =>
+      new Promise((resolve, reject) => {
+        const id = ++sequence;
+        const timeout = setTimeout(() => {
+          pending.delete(id);
+          reject(new Error(`CDP timed out: ${method}`));
+        }, 10_000);
+        pending.set(id, { resolve, reject, timeout });
+        socket.send(JSON.stringify({ id, method, params, sessionId }));
+      });
+    await run(send);
+  } finally {
+    for (const request of pending.values()) {
+      clearTimeout(request.timeout);
+      request.reject(new Error("regression browser closed"));
+    }
+    socket?.close();
+    if (chrome && chrome.exitCode === null && chrome.signalCode === null) {
+      const exited = once(chrome, "exit");
+      const timeout = setTimeout(() => chrome.kill("SIGKILL"), 5_000);
+      chrome.kill();
+      await exited;
+      clearTimeout(timeout);
+    }
+    await rm(profile, { recursive: true, force: true });
+  }
+}

evals/browser/cases/regression/snapshot-coordinates/snapshot-coordinates.case.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "../../../schemas/case.schema.json",
+  "schemaVersion": 1,
+  "id": "snapshot-coordinates",
+  "title": "Scrolled and nested frame coordinate fixture",
+  "suite": "regression",
+  "tags": ["geometry", "iframe", "scroll"],
+  "fixture": { "startPath": "/snapshot-coordinates" },
+  "prompts": {
+    "en": "Open {url}, observe the page and its frames, report the GEOMETRY marker, then close the session.",
+    "zh-CN": "打开 {url}，观察页面及其 iframe，报告 GEOMETRY 标记，然后关闭会话。"
+  },
+  "coverage": ["session.start", "session.stop", "page.navigate", "inspect.observe"],
+  "assertions": {
+    "site": [
+      {
+        "label": "root fixture scrolled and settled",
+        "type": "geometry.ready",
+        "where": { "data.root": true },
+        "minCount": 1
+      }
+    ],
+    "response": [{ "label": "observed the fixture marker", "includes": "GEOMETRY-195" }],
+    "adapter": [{ "label": "browser session was closed", "key": "sessionStopped" }]
+  },
+  "smoke": {
+    "steps": [
+      { "action": "navigate" },
+      { "action": "wait-site-event", "type": "geometry.ready", "where": { "root": true } },
+      { "action": "observe" }
+    ]
+  }
+}

evals/browser/cases/regression/snapshot-coordinates/snapshot-coordinates.fixture.mjs

@@ -0,0 +1,52 @@
+import { page, withRun } from "../../../lib/fixtures.mjs";
+
+export default {
+  id: "snapshot-coordinates",
+  routes: ["/snapshot-coordinates", "/snapshot-coordinates/frame", "/snapshot-coordinates/nested"],
+  render({ pathname, runId, query }) {
+    const root = pathname === "/snapshot-coordinates";
+    const nested = pathname.endsWith("/nested");
+    return page({
+      title: "Snapshot coordinate regression",
+      body: `
+        <style>
+          main { margin: 0; width: auto; }
+          body { width: 2000px; height: 2400px; }
+          html { overflow-anchor: none; }
+          ${query.get("scrollbars") === "none" ? "html { scrollbar-width: none; }" : ""}
+          button { position: absolute; box-sizing: border-box; padding: 0; border: 2px solid black; border-radius: 0; }
+          #probe { left: ${root ? 180 : 100}px; top: ${root ? 360 : 160}px; width: 120px; height: 40px; }
+          iframe { position: absolute; box-sizing: content-box; width: 320px; height: 220px;
+            border: 6px solid black; padding: 8px; transform: scale(1.25); transform-origin: 0 0; }
+          #same { left: 340px; top: 400px; }
+          #cross { left: 820px; top: 400px; }
+          #nested { left: 150px; top: 210px; width: 130px; height: 70px; border-width: 2px; padding: 4px; transform: scale(0.8); }
+          ${nested ? "#probe { left: 30px; top: 40px; width: 60px; height: 20px; }" : ""}
+        </style>
+        <button id="probe" data-geometry-probe>GEOMETRY-195</button>
+        ${root ? `<iframe id="same" name="same" title="same-process frame" src="${withRun("/snapshot-coordinates/frame", runId)}"></iframe><iframe id="cross" name="cross" title="cross-site frame"></iframe>` : ""}
+        ${!root && !nested ? `<iframe id="nested" name="nested" title="nested frame" src="${withRun("/snapshot-coordinates/nested", runId)}"></iframe>` : ""}
+      `,
+      script: `
+        history.scrollRestoration = "manual";
+        const cross = document.querySelector("#cross");
+        if (cross) {
+          const url = new URL(${JSON.stringify(withRun("/snapshot-coordinates/frame", runId))}, location.href);
+          url.hostname = location.hostname === "127.0.0.1" ? "localhost" : "127.0.0.1";
+          // Isolate unit conversion from the pre-existing OOPIF scrollbar-width
+          // projection issue. ?classic-scrollbars retains that separate reproduction.
+          if (!new URLSearchParams(location.search).has("classic-scrollbars")) url.searchParams.set("scrollbars", "none");
+          cross.src = url.href;
+        }
+        window.addEventListener("load", () => {
+          scrollTo(${root ? "80, 240" : nested ? "10, 20" : "40, 100"});
+          requestAnimationFrame(() => requestAnimationFrame(() => {
+            window.geometryReady = true;
+            document.documentElement.dataset.geometryReady = "true";
+            browserEval.send("geometry.ready", { root: ${root} });
+          }));
+        });
+      `,
+    });
+  },
+};

evals/browser/tests/eval.test.mjs

@@ -41,17 +41,22 @@ test("case manifests are discovered, ordered, and grouped into suites", () => {
       "diagnostics",
       "mobile-emulation",
       "generated-form",
+      "snapshot-coordinates",
     ],
   );
-  assert.deepEqual(repositorySummary(cases, fixtureRegistry).suites, { core: 6, matrix: 1 });
+  assert.deepEqual(repositorySummary(cases, fixtureRegistry).suites, {
+    core: 6,
+    matrix: 1,
+    regression: 1,
+  });
 });
 
 test("repository validation links every case to a fixture and valid workflow evidence", () => {
   assert.deepEqual(validateRepositoryCases(cases, fixtureRegistry), []);
   const summary = repositorySummary(cases, fixtureRegistry);
-  assert.equal(summary.cases, 7);
-  assert.equal(summary.fixtureModules, 8);
-  assert.equal(summary.fixtureRoutes, 12);
+  assert.equal(summary.cases, 8);
+  assert.equal(summary.fixtureModules, 9);
+  assert.equal(summary.fixtureRoutes, 15);
 });
 
 test("manifest validation rejects unknown operations and incomplete workflow steps", () => {

install.ps1

@@ -21,6 +21,7 @@ $ErrorActionPreference = "Stop"
 
 $Repo = if ($env:BSK_REPO) { $env:BSK_REPO } else { "Tencent/BrowserSkill" }
 $InstallDir = if ($env:BSK_INSTALL_DIR) { $env:BSK_INSTALL_DIR } else { Join-Path $HOME ".local\bin" }
+$InstallDir = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($InstallDir)
 $GitHub = "https://github.com/${Repo}"
 
 function Write-Log {
@@ -64,7 +65,7 @@ function Get-PlatformTriple {
 function Add-ToUserPath {
     param([string]$Dir)
 
-    $currentUserPath = [Environment]::GetEnvironmentVariable("PATH", "User") -split ";" | Where-Object { $_ }
+    $currentUserPath = @([Environment]::GetEnvironmentVariable("PATH", "User") -split ";" | Where-Object { $_ })
 
     if ($currentUserPath -contains $Dir) {
         Write-Log "$Dir is already in your user PATH"
@@ -90,30 +91,59 @@ function Add-ToSessionPath {
 # ── Git Bash (bash environment) PATH helper ──────────────────────────────────
 
 function Add-ToBashProfile {
-    param([string]$Dir)
+    param([string]$Dir, [string]$BashRc = (Join-Path $HOME ".bashrc"))
 
     # Convert Windows path (e.g. C:\Users\foo\.local\bin) to Git-Bash Unix-style (/c/Users/foo/.local/bin)
     $unixPath = $Dir -replace '\\', '/'
     if ($unixPath -match '^([A-Z]):(.*)$') {
         $unixPath = '/' + $matches[1].ToLower() + $matches[2]
     }
-    $bashRc = Join-Path $HOME ".bashrc"
-    $exportLine = "export PATH=""${unixPath}:`$PATH""  # bsk CLI"
+    # Single-quote the literal directory; only the existing PATH is expanded.
+    $shellQuote = "'" + [char]34 + "'" + [char]34 + "'"
+    $quotedPath = "'" + $unixPath.Replace("'", $shellQuote) + "'"
+    $exportLine = "export PATH=${quotedPath}:`"`$PATH`"  # bsk CLI"
 
-    if (Test-Path $bashRc) {
-        $content = Get-Content $bashRc -Raw -ErrorAction SilentlyContinue
-        if ($content -match [regex]::Escape($unixPath)) {
+    if (Test-Path -LiteralPath $BashRc) {
+        $content = [System.IO.File]::ReadAllText($BashRc)
+        if ($content.Contains($exportLine)) {
             Write-Log "$unixPath is already in ~/.bashrc"
             return
         }
     }
 
-    Add-Content $bashRc "`n$exportLine" -Encoding ASCII
+    # Explicit BOM-less UTF-8 also works in Windows PowerShell 5.1.
+    [System.IO.File]::AppendAllText($BashRc, "`n$exportLine`n", (New-Object System.Text.UTF8Encoding($false)))
     Write-Log "added ${unixPath} to ~/.bashrc"
 }
 
 # ── Main ──────────────────────────────────────────────────────────────────────
 
+# Stage on the destination volume before stopping the daemon. Never truncate
+# the installed executable: failed replacement must leave it usable.
+function Install-Binary {
+    param([string]$Source, [string]$Target)
+
+    $staged = "$Target.install-$([Guid]::NewGuid().ToString('N'))"
+    try {
+        [System.IO.File]::Copy($Source, $staged)
+        if ([System.IO.File]::Exists($Target)) {
+            # Use the downloaded CLI: older versions have broken Windows
+            # liveness checks. Stop verifies daemon identity before terminating it.
+            & $Source daemon stop
+            if ($LASTEXITCODE -ne 0) { throw "could not stop bsk daemon; existing installation was not replaced" }
+            # PowerShell 5.1 converts $null to an empty path for string parameters.
+            [System.IO.File]::Replace($staged, $Target, [NullString]::Value)
+            Write-Log "daemon will restart automatically on the next browser command"
+        }
+        else {
+            [System.IO.File]::Move($staged, $Target)
+        }
+    }
+    finally {
+        if ([System.IO.File]::Exists($staged)) { [System.IO.File]::Delete($staged) }
+    }
+}
+
 function Main {
     $platform = Get-PlatformTriple
 
@@ -184,7 +214,7 @@ function Main {
             New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
         }
 
-        Copy-Item -Path (Join-Path $tempDir "bsk.exe") -Destination (Join-Path $InstallDir "bsk.exe") -Force
+        Install-Binary -Source (Join-Path $tempDir "bsk.exe") -Target (Join-Path $InstallDir "bsk.exe")
 
         Write-Log "installed bsk to $InstallDir\bsk.exe"
 
@@ -199,12 +229,8 @@ function Main {
 
         # Verify
         $bskPath = Join-Path $InstallDir "bsk.exe"
-        if (Get-Command bsk -ErrorAction SilentlyContinue) {
-            & bsk --version
-        }
-        else {
-            Write-Log "verify install: & ""$bskPath"" --version"
-        }
+        & $bskPath --version
+        if ($LASTEXITCODE -ne 0) { throw "installed bsk failed verification" }
 
         Write-Log "done"
         Write-Host ""

packages/dsh-plugin-browserskill/README.md

@@ -1,13 +1,51 @@
-# dsh-plugin-browserskill
+# BrowserSkill for DeepSeek Harness
 
-npm: [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)
+[![npm version](https://img.shields.io/npm/v/@wxg-prc-cpg/browser-skill-dsh-plugin)](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)
 
-A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) tool plugin that exposes
-[BrowserSkill](https://github.com/Tencent/BrowserSkill) (`bsk`) browser automation to the model.
+Use [BrowserSkill](https://github.com/Tencent/BrowserSkill) in
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`) to browse
+websites, fill forms, and capture screenshots through native `browser_*` tools.
+Browser tasks run in Agent Windows, with a live view in the dsh Web UI.
 
-Each action maps to one `bsk <cmd> --json` invocation: the plugin spawns the bsk CLI, parses its
-structured JSON output, and returns a canonical typed value. The bsk daemon, browser, and browser
-extension keep owning the actual browser control — this package is a thin, well-typed bridge.
+## Installation
+
+Before installing the plugin:
+
+- Install [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) and
+  [pnpm](https://pnpm.io/installation), which dsh uses to manage plugins.
+- Install the `bsk` CLI and connect the BrowserSkill extension in Chrome or Edge.
+  Follow the [BrowserSkill setup guide](https://github.com/Tencent/BrowserSkill#quick-start).
+- Make sure `bsk` is on the `PATH` used to start dsh, or set `bskPath` in the plugin configuration.
+
+Install the plugin into the `web` profile, then start it:
+
+```sh
+dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
+dsh --profile web
+```
+
+Replace `web` with your profile name if you use a different profile. The plugin
+includes the `browser-skill` skill; no separate `bsk install-skill` step is needed.
+
+In a conversation, try:
+
+```text
+/browser-skill open example.com and summarize the page.
+```
+
+By default, the browser tools become available when the skill is invoked.
+
+## Updating
+
+Installed plugins do not update automatically. To upgrade this plugin to npm's
+`latest` version, including versions outside the profile's saved dependency range:
+
+```sh
+dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
+```
+
+Restart that dsh profile after upgrading. This command updates the plugin; update
+the `bsk` CLI and browser extension separately when a release requires it.
 
 ## Tools
 
@@ -20,23 +58,7 @@ extension keep owning the actual browser control — this package is a thin, wel
 | `browser_tabs` | `list`, `create`, `select`, `close`, `borrow`, `return` | Manage Agent Window tabs and temporarily borrow user tabs. |
 | `browser_assist` | `resize`, `emulate`, `request-help` | Resize or emulate the browser and pause for human-only steps. |
 
-`bsk evaluate` and `bsk record` are intentionally not exposed by this plugin: arbitrary page
-evaluation is a higher-risk capability, while recording is long-running and needs a dedicated
-DeepSeek Harness lifecycle before it can be added safely.
-
-## Agent skill (progressive disclosure)
-
-Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
-official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
-resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
-tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
-`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
-concatenated: its command examples belong to a different execution interface and would bypass
-the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
-The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
-missing supported browser tools before embedding the Markdown. Registration and every pre-step
-catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
-seam degrade silently.
+Arbitrary page-script evaluation and interaction recording are not supported.
 
 ## Multi-session model
 
@@ -55,136 +77,73 @@ an explicit `session` argument naming a foreign or unknown id is rejected, the `
 `browser_session` shows plugin-created sessions only (no daemon-wide view), and stop/unload cleanup
 can never touch a session owned by another program.
 
-## Installation
-
-The plugin follows the standard dsh bundle layout (`dsh.bundle` manifest + `cordis.patch.yml`):
-
-```sh
-dsh plugin --profile <name> add @wxg-prc-cpg/browser-skill-dsh-plugin
-dsh --profile <name>
-```
-
-Prerequisite: the `bsk` CLI must be installed and on `PATH`, and the BrowserSkill browser extension
-(Chrome or Edge) must be connected — see the
-[BrowserSkill README](https://github.com/Tencent/BrowserSkill). When bsk is missing, tool calls fail
-with install guidance instead of a bare spawn error.
-
 ## Configuration
 
-All fields are optional and validated through the plugin's Schemastery `Config`:
+After installing the plugin, edit your profile's `cordis.patch.yml`. For the `web`
+profile, the default location is `~/.dsh/profiles/web/cordis.patch.yml`. If you set
+`DSH_HOME`, use `$DSH_HOME/profiles/web/cordis.patch.yml` instead. Replace `web` with
+your profile name as needed.
+
+If the file contains only comments and `[]`, keep the comments and replace `[]`
+with the YAML below. If it already contains patch entries, add this entry to the
+existing list or edit its existing `id: browserskill` entry. Keep a single
+top-level YAML list. This overrides the plugin registered by the installed bundle:
 
 ```yaml
-# cordis.patch.yml override example
-- insert:
-    - id: browserskill
-      name: "@wxg-prc-cpg/browser-skill-dsh-plugin"
-      config:
-        bskPath: bsk          # path to the bsk binary (default: resolve from PATH)
-        defaultTimeoutMs: 120000
-        maxSessions: 5
-        # observationEnabled: true     # live PiP/overlay observation (below)
-        # thumbnailIntervalMs: 1500    # frame cadence while a session is active
-        # idleIntervalMs: 8000         # idle cadence / recent-activity window
-        # lazyTools: true              # reveal browser_* tools only after the skill is invoked
+- id: browserskill
+  config:
+    bskPath: bsk
+    defaultTimeoutMs: 120000
+    maxSessions: 5
+    observationEnabled: true
+    thumbnailIntervalMs: 1500
+    idleIntervalMs: 8000
+    lazyTools: true
 ```
 
-- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the six
-  `browser_*` tool schemas stay OUT of the system prompt (zero schema tokens) until the
-  `browser-skill` skill is actually invoked — the skill catalog entry is the only
-  advertisement. One successful invocation (model tool call, or a `/browser-skill` user
-  gesture) registers the whole suite for the rest of the process; repeated invocations are
-  no-ops, and sessions resumed with a past invocation in their durable log reveal the suite
-  on entry. Set `false` for the legacy always-on registration.
+Change `bskPath` to the full path of your CLI binary if it is not on dsh's `PATH`.
+A patch replaces the entry's entire `config` object, so keep all overrides you need
+together in that object.
 
-## Observation overlay (PiP mini-window)
+Configuration changes follow `dsh.profile.patchReload` in the profile's
+`package.json`: `live` (the default for `web`) applies changes when you save the
+patch file; `startup` requires restarting the profile. Restart after upgrading
+the plugin in either case.
 
-When the plugin runs inside the dsh Web UI, an **observation overlay** floats over the app
-(registered into the `shell.overlay` seat): a breathing thumbnail per owned session plus its
-current action and elapsed time. The card docks at the top-right of the content area (clear of
-the composer and the shell's header controls) and wears the **BrowserSkill product family's own
-look**: the overlay reuses `@browser-skill/ui` components (`Button`, `cn`) and its oklch design
-tokens (`--card`, `--primary`, `--destructive`, `--ring`, …), status dots spec'd after the
-extension popup's connection indicator, and Remix icons. The BSK utility sheet is compiled
-scoped under the `.bsk-obs` root class (`scripts/build-client-css.mjs`), so the overlay looks
-like the BrowserSkill extension without leaking a single selector into the host shell — and the
-shell's theme cannot bleed back in.
+All fields are optional; omitted fields use the defaults below:
 
-- **Lifecycle**: hidden while the plugin owns no sessions; appears on the first
-  `browser_session` start action; disappears when all sessions stop (or the plugin unloads).
-- **Focus view**: status row (green/idle/red dot + session + action + mm:ss), the latest page
-  frame (while viewed, refreshes every ~1.5s while active, ~8s when idle; the last good frame stays on
-  stage while the next one loads, and is kept on errors so the card does not flash),
-  and a compact icon toolbar (Interrupt + Pop out, hover for the label).
-- **Interrupt**: one click kills the in-flight bsk command of the focus session (same semantics
-  as the chat Stop button — the current action fails, the agent run may continue). Strip items
-  carry their own hover interrupt button.
-- **Multi-session strip**: every session gets a tile (mini frame + id + status dot); focus
-  auto-follows the most recently active session; clicking a tile pins focus (pin badge, click
-  again to release); errored sessions get a red edge without stealing focus; sessions the daemon
-  lost are greyed out; prolonged daemon/browser outage shows "browser unavailable" and greys
-  the interrupt button until captures recover.
-- **Drag & resize**: drag the header to move the card; drag any of the four
-  corners to resize (min 240×180, max 80% of the viewport; no visible grip).
-  Both are remembered for the page lifetime.
-- **Pop out (PiP)**: upgrades the card into a native Document PiP window (requires a user
-  gesture, per browser rules), sized from the current card; closing the PiP falls back to the
-  in-page card with state intact. Browsers without Document PiP simply hide the button.
-- **Screenshot demand**: the client requests periodic screenshots while an observation view is
-  visible, using the PiP document's visibility when popped out. Hidden or collapsed views can
-  keep subscribing to state without requesting screenshots. The first screenshot subscriber
-  starts capture scheduling; the last one's departure cancels timers and skips queued captures.
-  An already running capture may finish. Demand applies to the service's owned sessions, not just
-  the selected session.
-- **Wire**: `GET /bsk-observation/events` is the live synchronization channel (SSE). Every connection,
-  including reconnects, starts with `{ type: "snapshot", sessions, available }`, followed by
-  `upsert`, `remove`, `reset`, and `availability` events on the same stream. Replace local state
-  with each snapshot before applying subsequent events. Use `?thumbnails=0` for state-only
-  subscriptions or `?thumbnails=1` to request screenshots; omitting the parameter defaults to
-  requesting screenshots for compatibility. Closing the stream releases its screenshot demand.
-  `GET /bsk-observation/state` remains a one-time `{ sessions, available }` read and does not
-  request screenshots. It has no ordering guarantee relative to a separate SSE connection;
-  live clients should initialize and resynchronize from the stream's snapshot instead.
-  The host also serves `POST /bsk-observation/interrupt`, `POST /bsk-observation/stop`, and
-  `GET /bsk-observation/thumbnail/<attachmentId>` through the dsh `webServer` route seam
-  (dsh 0.1's Typert Remote pipeline is closed to out-of-tree packages). All commands for one
-  session — tool calls and frame captures alike — run through a per-session FIFO, because the
-  daemon accepts only one unfinished command per session.
-- **Programmatic subscription**: `ObservationService.subscribe(listener, { thumbnails: false })`
-  subscribes to state without requesting screenshots. On an active service, the listener receives
-  the initial `snapshot` synchronously, before `subscribe` returns, then receives subsequent
-  changes. `thumbnails` defaults to `true`, so callers should choose it explicitly. The returned
-  unsubscribe function is safe to call repeatedly and releases this subscription's screenshot
-  demand. Subscribing after service disposal is a no-op.
-- **Trust model**: these routes expose live screenshots (and an interrupt write), so they
-  replicate the browser-trust fence dsh applies to its own `/api` routes: the request Host
-  must be a loopback authority (`localhost`, `127.0.0.0/8`, `[::1]`), a present Origin must
-  match the Host, `sec-fetch-site: cross-site` is refused, and POST requires an
-  `application/json` body (cross-site simple requests can never satisfy that). The channel is
-  therefore built for **loopback-only serving** — binding the dsh web server to `0.0.0.0` and
-  reaching it through a LAN address will (deliberately) fail the fence; do not put these
-  routes behind a non-loopback reverse proxy without adding your own authentication.
-- Configure with `observationEnabled` / `thumbnailIntervalMs` / `idleIntervalMs`.
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `bskPath` | `bsk` | Path to the CLI binary. |
+| `defaultTimeoutMs` | `120000` | Default command timeout in milliseconds. |
+| `maxSessions` | `5` | Maximum concurrent sessions started by this plugin. |
+| `observationEnabled` | `true` | Enable live browser observation. |
+| `thumbnailIntervalMs` | `1500` | Screenshot interval for active sessions, in milliseconds. |
+| `idleIntervalMs` | `8000` | Screenshot interval for idle sessions and the recent-activity window, in milliseconds. |
+| `lazyTools` | `true` | Reveal the browser tools when the skill is invoked. Set `false` to register them at startup. |
 
-## Behavior notes
+With `lazyTools: true`, only the skill's catalog entry is initially advertised to
+the model. The six `browser_*` tool schemas are added to the system prompt after
+the `browser-skill` skill is successfully invoked, either by the model or through
+`/browser-skill`. Set `lazyTools: false` to make the tools available immediately.
 
-- **Cancellation**: aborting a tool call (`exec.signal`) kills the underlying bsk child process,
-  matching BrowserSkill's cooperative tool-cancellation model.
-- **UI cards**: calls render as terminal cards (command line as title, output as the completed
-  card). Screenshots additionally attach the image itself when the host mounts an attachment store
-  and the active model route declares image input; otherwise the PNG path is returned.
-- **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
-  `lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_inspect`. The
-  custom view keeps a terminal block for every inspect action and, when a screenshot result carries
-  an image block, resolves the durable attachment through the client session's authorized
-  `readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
-  The other five tools keep the stock terminal card. The bundle follows the dsh client
-  contract: a CJS closure factory handed to `window.__ModuleLoader__.load`, platform modules
-  (`react`, `dsh-client-ui-*`) external, everything else inlined, CSS Modules compiled by
-  lightningcss.
-- **Errors**: non-zero bsk exits surface the CLI's JSON error envelope (`code`, `message`, `hint`)
-  so the model gets the daemon's actionable guidance.
-- **Long-running work** (e.g. `bsk record`) is not backgrounded via `ctx.jobs` yet — tracked as a
-  follow-up.
+## Live browser view
+
+The dsh Web UI shows the plugin's browser sessions in a floating panel. If your
+profile provides the `dsh-better-sidebar` integration, the view appears in a
+**Browser Skill** sidebar tab instead.
+
+- See the current action, elapsed time, and recent screenshot for each session.
+- Select a session to focus on it. The sidebar view follows the current conversation.
+- Use **Interrupt** to cancel the current browser command. The agent may continue
+  with another action afterward.
+- Drag or resize the floating panel, or use **Pop out** to open a Picture-in-Picture
+  window in browsers that support it.
+- Periodic screenshots are requested while a browser observation view is visible.
+  Configure the active and idle intervals with the options above.
+
+The observation endpoints require a loopback address such as `localhost` or
+`127.0.0.1`. Access through a LAN hostname or non-loopback reverse proxy is not supported.
 
 ## Development
 
@@ -195,22 +154,47 @@ pnpm --filter @wxg-prc-cpg/browser-skill-dsh-plugin test     # unit tests mock b
 pnpm --filter @wxg-prc-cpg/browser-skill-dsh-plugin build    # tsdown -> lib/
 ```
 
+See the [development notes](https://github.com/Tencent/BrowserSkill/blob/main/packages/dsh-plugin-browserskill/docs/development.md)
+for skill registration, tool results, and observation APIs in the current source.
+
 ## Publishing
 
-The GitHub Actions workflow **Release dsh plugin** publishes this package to npm
-as `@wxg-prc-cpg/browser-skill-dsh-plugin`. The Cordis plugin id, client
-bundle registration, and `cordis.patch.yml` name are the same specifier so
-dsh can import and materialize the plugin without a ModuleLoader id mismatch.
+The [Release dsh plugin workflow](https://github.com/Tencent/BrowserSkill/blob/main/.github/workflows/release-dsh-plugin.yml)
+publishes the package and this README to npm. Pushing a `dsh-plugin-vX.Y.Z` tag
+triggers it; ordinary commits to `main` do not.
 
-Trigger it by pushing a tag that matches `package.json`'s `version`:
+1. Commit this README and any other changes intended for the release.
+2. From the repository root, run the
+   [release script](https://github.com/Tencent/BrowserSkill/blob/main/scripts/release.mjs)
+   with a new stable version, replacing `<version>` below. The script updates the
+   CLI, extension, and DSH plugin versions, commits the version changes, and creates
+   their release tags:
 
-```sh
-git tag dsh-plugin-v0.1.2
-git push origin dsh-plugin-v0.1.2
-```
+   ```sh
+   node scripts/release.mjs <version>
+   ```
 
-Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the
-`NPM_TOKEN` secret from the `npm-publish` GitHub Environment.
+3. Push the version commit to the release branch, then push the DSH plugin tag
+   created by the script, using the same `<version>`:
+
+   ```sh
+   git push origin HEAD
+   git push origin dsh-plugin-v<version>
+   ```
+
+   This publishes the DSH plugin. Push the CLI and extension tags separately when
+   those components are ready for release.
+
+The workflow checks the version, runs typechecks and tests, builds the package,
+and publishes it to npm.
+
+You can also run the workflow manually from GitHub Actions on the intended release
+ref. Both triggers require an unpublished version and the `NPM_TOKEN` secret in the
+`npm-publish` GitHub Environment.
+
+npm updates the package README only when a new version is published, including
+for documentation-only changes. Published versions cannot be overwritten. See
+[npm's README update rules](https://docs.npmjs.com/about-package-readme-files/).
 
 ## License
 

packages/dsh-plugin-browserskill/docs/development.md

@@ -0,0 +1,90 @@
+# DSH plugin development notes
+
+For installation, usage, and configuration, see the [plugin README](../README.md).
+These notes describe the current source on this branch; a published npm version may
+not include later changes.
+
+## Tool execution
+
+The plugin runs the `bsk` CLI and parses its JSON output. The daemon and browser
+extension perform the browser operations. The published package name is also the
+Cordis plugin id, client bundle registration id, and `cordis.patch.yml` plugin name.
+Keep these identifiers aligned so dsh can load both halves of the plugin.
+
+## Agent skill
+
+Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
+official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
+resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
+tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
+`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
+concatenated: its command examples belong to a different execution interface and would bypass
+the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
+The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
+missing supported browser tools before embedding the Markdown. Registration and every pre-step
+catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
+seam degrade silently.
+
+With `lazyTools: true`, the six tool schemas stay out of the system prompt until
+the skill is successfully invoked. Registration happens once and lasts until the
+plugin is unloaded. Repeated invocations do not register duplicate tools. Entering
+a resumed conversation whose history contains a successful skill invocation also
+registers the tools. Setting `lazyTools: false` registers them at plugin startup.
+
+## Observation subscriptions and routes
+
+- **Screenshot demand**: the client requests periodic screenshots while an observation view is
+  visible, using the PiP document's visibility when popped out. Hidden or collapsed views can
+  keep subscribing to state without requesting screenshots. The first screenshot subscriber
+  starts capture scheduling; the last one's departure cancels timers and skips queued captures.
+  An already running capture may finish. Demand applies to the service's owned sessions, not just
+  the selected session.
+- **Wire**: `GET /bsk-observation/events` is the live synchronization channel (SSE). Every connection,
+  including reconnects, starts with `{ type: "snapshot", sessions, available }`, followed by
+  `upsert`, `remove`, `reset`, and `availability` events on the same stream. Replace local state
+  with each snapshot before applying subsequent events. Use `?thumbnails=0` for state-only
+  subscriptions or `?thumbnails=1` to request screenshots; omitting the parameter defaults to
+  requesting screenshots for compatibility. Closing the stream releases its screenshot demand.
+  `GET /bsk-observation/state` remains a one-time `{ sessions, available }` read and does not
+  request screenshots. It has no ordering guarantee relative to a separate SSE connection;
+  live clients should initialize and resynchronize from the stream's snapshot instead.
+  The host also serves `POST /bsk-observation/interrupt`, `POST /bsk-observation/stop`, and
+  `GET /bsk-observation/thumbnail/<attachmentId>` through the dsh `webServer` route seam
+  (dsh 0.1's Typert Remote pipeline is closed to out-of-tree packages). All commands for one
+  session — tool calls and frame captures alike — run through a per-session FIFO, because the
+  daemon accepts only one unfinished command per session.
+- **Programmatic subscription**: `ObservationService.subscribe(listener, { thumbnails: false })`
+  subscribes to state without requesting screenshots. On an active service, the listener receives
+  the initial `snapshot` synchronously, before `subscribe` returns, then receives subsequent
+  changes. `thumbnails` defaults to `true`, so callers should choose it explicitly. The returned
+  unsubscribe function is safe to call repeatedly and releases this subscription's screenshot
+  demand. Subscribing after service disposal is a no-op.
+- **Trust model**: these routes expose live screenshots (and an interrupt write), so they
+  replicate the browser-trust fence dsh applies to its own `/api` routes: the request Host
+  must be a loopback authority (`localhost`, `127.0.0.0/8`, `[::1]`), a present Origin must
+  match the Host, `sec-fetch-site: cross-site` is refused, and POST requires an
+  `application/json` body (cross-site simple requests can never satisfy that). The channel is
+  therefore built for **loopback-only serving** — binding the dsh web server to `0.0.0.0` and
+  reaching it through a LAN address will (deliberately) fail the fence; do not put these
+  routes behind a non-loopback reverse proxy without adding your own authentication.
+
+## Tool results and cancellation
+
+- **Cancellation**: aborting a tool call (`exec.signal`) kills the underlying bsk child process,
+  matching BrowserSkill's cooperative tool-cancellation model.
+- **UI cards**: calls render as terminal cards (command line as title, output as the completed
+  card). Screenshots additionally attach the image itself when the host mounts an attachment store
+  and the active model route declares image input; otherwise the PNG path is returned.
+- **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
+  `lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_inspect`. The
+  custom view keeps a terminal block for every inspect action and, when a screenshot result carries
+  an image block, resolves the durable attachment through the client session's authorized
+  `readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
+  The other five tools keep the stock terminal card. The bundle follows the dsh client
+  contract: a CJS closure factory handed to `window.__ModuleLoader__.load`, platform modules
+  (`react`, `dsh-client-ui-*`) external, everything else inlined, CSS Modules compiled by
+  lightningcss.
+- **Errors**: non-zero bsk exits surface the CLI's JSON error envelope (`code`, `message`, `hint`)
+  so the model gets the daemon's actionable guidance.
+- **Long-running work** (e.g. `bsk record`) is not backgrounded via `ctx.jobs` yet — tracked as a
+  follow-up.

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
   "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

packages/dsh-plugin-browserskill/src/runner.ts

@@ -5,7 +5,7 @@
  * map the CLI's JSON error envelope onto a thrown `BskError`.
  */
 
-import { type ChildProcess, spawn } from "node:child_process";
+import { type ChildProcess, type SpawnOptionsWithoutStdio, spawn } from "node:child_process";
 
 /** Shape of the JSON error envelope `bsk --json` prints on failure. */
 export interface BskErrorBody {
@@ -53,7 +53,11 @@ export interface BskRunOptions {
 }
 
 /** Minimal spawn signature so tests can substitute a fake child process. */
-export type SpawnImpl = (command: string, args: string[]) => ChildProcess;
+export type SpawnImpl = (
+  command: string,
+  args: string[],
+  options?: SpawnOptionsWithoutStdio,
+) => ChildProcess;
 
 export interface BskRunner {
   /** Run `bsk <args...> --json` and collect its output. */
@@ -64,29 +68,66 @@ export interface BskRunner {
   killFor(tag: string): number;
 }
 
-// Business RPCs translate SIGINT into the daemon's cancel(rpc_id) protocol.
-// Give that bounded reconciliation path time to settle before the hard kill.
+// Business RPCs translate Ctrl-C / opt-in stdin EOF into cancel(rpc_id).
+// Allow reconciliation before hard-killing an old or unresponsive CLI.
 const KILL_GRACE_MS = 3000;
+// Windows IPC may spend 5s connecting, 2s cancelling, 2s settling,
+// and up to 5s releasing the entire batch of caller-owned transfers.
+const WINDOWS_KILL_GRACE_MS = 15_000;
 const SESSION_BUSY_RETRY_DELAY_MS = 100;
 
 export function createBskRunner(bskPath: string, spawnImpl: SpawnImpl = spawn): BskRunner {
   const live = new Map<ChildProcess, string | undefined>();
+  const windows = process.platform === "win32";
+  const cancelling = new Set<ChildProcess>();
 
   function killChild(child: ChildProcess): void {
-    if (child.exitCode !== null || child.signalCode !== null) return;
-    child.kill("SIGINT");
-    const force = setTimeout(() => {
-      if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
-    }, KILL_GRACE_MS);
+    if (child.exitCode !== null || child.signalCode !== null || cancelling.has(child)) return;
+    cancelling.add(child);
+    // Node kills Windows children outright for SIGINT. EOF asks the CLI to
+    // send its existing cancel RPC and wait for browser reconciliation.
+    if (windows && child.stdin) child.stdin.end();
+    else child.kill("SIGINT");
+    const force = setTimeout(
+      () => {
+        if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+      },
+      windows ? WINDOWS_KILL_GRACE_MS : KILL_GRACE_MS,
+    );
     force.unref();
+    child.once("close", () => {
+      clearTimeout(force);
+      cancelling.delete(child);
+    });
   }
 
   return {
     run(args, options = {}) {
+      if (options.signal?.aborted) {
+        return Promise.resolve({
+          code: null,
+          stdout: "",
+          stderr: "",
+          timedOut: false,
+          aborted: true,
+        });
+      }
       return new Promise<BskRunResult>((resolve, reject) => {
         let child: ChildProcess;
         try {
-          child = spawnImpl(bskPath, [...args, "--json"]);
+          child = spawnImpl(
+            bskPath,
+            [...args, "--json"],
+            windows
+              ? {
+                  windowsHide: true,
+                  env: { ...process.env, BSK_CANCEL_ON_STDIN_CLOSE: "1" },
+                }
+              : undefined,
+          );
+          // A child exiting while cancellation closes stdin may report EPIPE.
+          // Its close/error event remains the authority for the run result.
+          child.stdin?.on("error", () => {});
         } catch (error) {
           reject(error);
           return;

packages/dsh-plugin-browserskill/tests/runner.test.ts

@@ -1,6 +1,7 @@
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { describe, expect, it } from "vitest";
+import { PassThrough } from "node:stream";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   type BskRunResult,
   createBskRunner,
@@ -92,6 +93,77 @@ describe("createBskRunner", () => {
   });
 });
 
+describe("Windows parent cancellation", () => {
+  const originalPlatform = Object.getOwnPropertyDescriptor(process, "platform")!;
+  beforeEach(() => Object.defineProperty(process, "platform", { value: "win32" }));
+  afterEach(() => {
+    Object.defineProperty(process, "platform", originalPlatform);
+    vi.useRealTimers();
+  });
+
+  it("opts in to stdin cancellation and waits for CLI reconciliation", async () => {
+    const child = Object.assign(new FakeChild(), { stdin: new PassThrough() });
+    const spawn = vi.fn(() => child as unknown as ChildProcess);
+    const runner = createBskRunner("bsk", spawn);
+    const abort = new AbortController();
+    const result = runner.run(["snapshot"], { signal: abort.signal });
+    expect(spawn.mock.calls[0]).toEqual([
+      "bsk",
+      ["snapshot", "--json"],
+      {
+        windowsHide: true,
+        env: { ...process.env, BSK_CANCEL_ON_STDIN_CLOSE: "1" },
+      },
+    ]);
+    abort.abort();
+    expect(child.stdin.writableEnded).toBe(true);
+    expect(child.killedWith).toEqual([]);
+    // Closing an already-exited child's pipe must not crash the host.
+    child.stdin.emit("error", Object.assign(new Error("closed"), { code: "EPIPE" }));
+    child.finish(2, '{"code":"cancelled"}');
+    expect(await result).toMatchObject({ code: 2, aborted: true });
+  });
+
+  it("bounds cancellation of an old or unresponsive CLI", async () => {
+    vi.useFakeTimers();
+    const child = Object.assign(new FakeChild(), { stdin: new PassThrough() });
+    const runner = createBskRunner("bsk", fakeSpawn([child]));
+    const result = runner.run(["snapshot"], { timeoutMs: 5 });
+    await vi.advanceTimersByTimeAsync(5);
+    expect(child.stdin.writableEnded).toBe(true);
+    expect(child.killedWith).toEqual([]);
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(child.killedWith).toEqual([]);
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(child.killedWith).toEqual(["SIGKILL"]);
+    expect(await result).toMatchObject({ timedOut: true });
+  });
+
+  it("cancels only the requested tag and clears the fallback after exit", async () => {
+    vi.useFakeTimers();
+    const a = Object.assign(new FakeChild(), { stdin: new PassThrough() });
+    const b = Object.assign(new FakeChild(), { stdin: new PassThrough() });
+    const runner = createBskRunner("bsk", fakeSpawn([a, b]));
+    const first = runner.run(["snapshot"], { tag: "a" });
+    const second = runner.run(["snapshot"], { tag: "b" });
+    expect(runner.killFor("a")).toBe(1);
+    expect(a.stdin.writableEnded).toBe(true);
+    expect(b.stdin.writableEnded).toBe(false);
+    a.finish(2);
+    b.finish(0);
+    await Promise.all([first, second]);
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
+  it("does not start work for an already-aborted call", async () => {
+    const spawn = vi.fn();
+    const runner = createBskRunner("bsk", spawn);
+    const signal = AbortSignal.abort();
+    expect(await runner.run(["snapshot"], { signal })).toMatchObject({ aborted: true });
+    expect(spawn).not.toHaveBeenCalled();
+  });
+});
+
 describe("parseBskJson", () => {
   const base: BskRunResult = { code: 0, stdout: "", stderr: "", timedOut: false, aborted: false };
 

scripts/install-windows.test.ps1

@@ -0,0 +1,135 @@
+#Requires -Version 5.1
+param([string]$BskPath = (Join-Path $PSScriptRoot "../target/debug/bsk.exe"))
+$ErrorActionPreference = "Stop"
+
+# Load definitions, never Main: no downloads or changes to the real user PATH.
+$installer = Join-Path $PSScriptRoot "../install.ps1"
+$tokens = $null
+$errors = $null
+$ast = [System.Management.Automation.Language.Parser]::ParseFile($installer, [ref]$tokens, [ref]$errors)
+if ($errors.Count) { throw ($errors | Out-String) }
+foreach ($statement in $ast.EndBlock.Statements) {
+    if ($statement -is [System.Management.Automation.Language.FunctionDefinitionAst]) {
+        $definition = $statement.Extent.Text
+        if ($statement.Name -eq "Add-ToUserPath") {
+            $definition = $definition.Replace('[Environment]::GetEnvironmentVariable("PATH", "User")', '$script:UserPath')
+            $definition = $definition.Replace('[Environment]::SetEnvironmentVariable("PATH", $newUserPath, "User")', '$script:UserPath = $newUserPath')
+        }
+        Invoke-Expression $definition
+    }
+}
+function Assert-Equal($Actual, $Expected) {
+    if ($Actual -cne $Expected) { throw "expected [$Expected], got [$Actual]" }
+}
+function Assert-Fails([scriptblock]$Action) {
+    $failed = $false
+    try { & $Action } catch { $failed = $true }
+    if (-not $failed) { throw "expected failure" }
+}
+
+$dir = 'C:\Users\Alice\.local\bin'
+foreach ($existing in @('', 'C:\WindowsApps', 'C:\A;C:\B')) {
+    $script:UserPath = $existing
+    Add-ToUserPath $dir
+    $expected = if ($existing) { "$existing;$dir" } else { $dir }
+    Assert-Equal $script:UserPath $expected
+    Add-ToUserPath $dir
+    Assert-Equal $script:UserPath $expected
+}
+
+$root = Join-Path ([IO.Path]::GetTempPath()) ("bsk-install-test-" + [Guid]::NewGuid().ToString('N'))
+[IO.Directory]::CreateDirectory($root) | Out-Null
+$oldBskHome = $env:BSK_HOME
+$oldAutoUpdate = $env:BSK_AUTO_UPDATE
+$daemon = $null
+try {
+    $utf8 = New-Object System.Text.UTF8Encoding($false)
+    $bashRc = Join-Path $root ".bashrc"
+    $existing = "# existing 中文 configuration" + [char]10
+    [IO.File]::WriteAllText($bashRc, $existing, $utf8)
+    $special = 'C:\Users\张三 space $HOME $(echo unsafe) ! & [x] O''Brien\.local\bin'
+    Add-ToBashProfile $special $bashRc
+    $first = [IO.File]::ReadAllText($bashRc)
+    if (-not $first.StartsWith($existing)) { throw "existing bashrc content changed" }
+    if (-not $first.Contains('张三')) { throw "Unicode path was lost" }
+    Add-ToBashProfile $special $bashRc
+    Assert-Equal ([IO.File]::ReadAllText($bashRc)) $first
+    $bytes = [IO.File]::ReadAllBytes($bashRc)
+    if ($bytes[0] -eq 0xEF) { throw "unexpected UTF-8 BOM" }
+
+    $bash = [IO.Path]::GetFullPath((Join-Path (Split-Path (Get-Command git).Source -Parent) "../bin/bash.exe"))
+    if (-not (Test-Path -LiteralPath $bash)) { throw "Git Bash is required for quoting regression" }
+    $env:BSK_TEST_RC = $bashRc
+    $probe = Join-Path $root 'probe.sh'
+    [IO.File]::WriteAllText($probe, 'source "$BSK_TEST_RC"; printf "%s\n" "${PATH%%:*}"', $utf8)
+    $actual = & $bash --noprofile --norc $probe
+    if ($LASTEXITCODE -ne 0) { throw "Git Bash failed" }
+    Assert-Equal $actual ('/c' + $special.Substring(2).Replace('\', '/'))
+
+    $env:BSK_HOME = Join-Path $root "home"
+    $env:BSK_AUTO_UPDATE = "off"
+    [IO.Directory]::CreateDirectory($env:BSK_HOME) | Out-Null
+    $sourceDir = Join-Path $root "download"
+    [IO.Directory]::CreateDirectory($sourceDir) | Out-Null
+    $source = Join-Path $sourceDir "bsk.exe"
+    [IO.File]::Copy((Resolve-Path -LiteralPath $BskPath).Path, $source)
+    $targetDir = Join-Path $root "中文 space [x] & install"
+    [IO.Directory]::CreateDirectory($targetDir) | Out-Null
+    $target = Join-Path $targetDir "bsk.exe"
+    Install-Binary $source $target
+    Assert-Equal (Get-FileHash -LiteralPath $target).Hash (Get-FileHash -LiteralPath $source).Hash
+
+    $daemon = Start-Process -FilePath $target -ArgumentList @('daemon', 'start', '--foreground', '--port', '0') -WindowStyle Hidden -PassThru
+    $infoPath = Join-Path $env:BSK_HOME "daemon.json"
+    $deadline = [DateTime]::UtcNow.AddSeconds(15)
+    while (-not [IO.File]::Exists($infoPath)) {
+        if ($daemon.HasExited -or [DateTime]::UtcNow -gt $deadline) { throw "daemon failed to start" }
+        Start-Sleep -Milliseconds 50
+    }
+    # PE overlays distinguish old/new executables without another build.
+    $stream = [IO.File]::OpenWrite($source)
+    try {
+        $stream.Seek(0, [IO.SeekOrigin]::End) | Out-Null
+        $marker = $utf8.GetBytes("installer replacement regression")
+        $stream.Write($marker, 0, $marker.Length)
+    } finally { $stream.Dispose() }
+    Install-Binary $source $target
+    if (-not $daemon.WaitForExit(5000)) { throw "old daemon still running" }
+    Assert-Equal (Get-FileHash -LiteralPath $target).Hash (Get-FileHash -LiteralPath $source).Hash
+    & $target --version
+    if ($LASTEXITCODE -ne 0) { throw "replacement is not executable" }
+
+    # Refuse replacement when daemon identity cannot be verified.
+    [IO.File]::WriteAllText($infoPath, 'invalid daemon metadata')
+    $before = (Get-FileHash -LiteralPath $target).Hash
+    Assert-Fails { Install-Binary $source $target }
+    Assert-Equal (Get-FileHash -LiteralPath $target).Hash $before
+    [IO.File]::Delete($infoPath)
+
+    # A remaining lock must fail without truncation or staging debris.
+    $lock = [IO.File]::Open($target, [IO.FileMode]::Open, [IO.FileAccess]::Read, [IO.FileShare]::None)
+    try { Assert-Fails { Install-Binary $source $target } } finally { $lock.Dispose() }
+    Assert-Equal (Get-FileHash -LiteralPath $target).Hash $before
+    if (@(Get-ChildItem -LiteralPath $targetDir -Filter "*.install-*").Count) { throw "staging files leaked" }
+    Write-Host "Windows installer regressions passed ($($PSVersionTable.PSVersion))"
+}
+catch {
+    Write-Host ($_ | Out-String)
+    Write-Host $_.ScriptStackTrace
+    throw
+}
+finally {
+    if ($daemon -and -not $daemon.HasExited) {
+        Stop-Process -Id $daemon.Id -Force
+        $daemon.WaitForExit(5000) | Out-Null
+    }
+    $env:BSK_HOME = $oldBskHome
+    $env:BSK_AUTO_UPDATE = $oldAutoUpdate
+    Remove-Item Env:BSK_TEST_RC -ErrorAction SilentlyContinue
+    # Resolve and verify before recursive cleanup; only this fixture is removed.
+    $resolvedRoot = [IO.Path]::GetFullPath($root)
+    $tempRoot = [IO.Path]::GetFullPath([IO.Path]::GetTempPath()).TrimEnd('\') + '\'
+    if (-not $resolvedRoot.StartsWith($tempRoot, [StringComparison]::OrdinalIgnoreCase) -or
+        -not ([IO.Path]::GetFileName($resolvedRoot)).StartsWith('bsk-install-test-')) { throw "invalid cleanup path" }
+    Remove-Item -LiteralPath $resolvedRoot -Recurse -Force
+}

scripts/release.mjs

@@ -174,16 +174,22 @@ function updateChangelog(version) {
 
   const today = new Date().toISOString().slice(0, 10);
   const escapedVer = version.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const versionHeading = new RegExp(`^## \\[${escapedVer}\\](?:\\s|$)`, "m");
 
   // First: fill in any date-placeholder line for this version (e.g. "## [0.2.0] - 2026-09-XX")
   const versionPlaceholder = new RegExp(`^## \\[${escapedVer}\\]\\s*-\\s*\\d{4}-\\d{2}-XX`, "m");
   if (versionPlaceholder.test(content)) {
     content = content.replace(versionPlaceholder, `## [${version}] - ${today}`);
-  } else {
-    // Otherwise: insert a new section after [Unreleased]
+  } else if (!versionHeading.test(content)) {
+    // Preserve prepared release entries; new versions go before the release history.
+    const heading = `## [${version}] - ${today}`;
     const unreleased = /^## \[Unreleased\]/m;
     if (unreleased.test(content)) {
-      content = content.replace(unreleased, `## [Unreleased]\n\n## [${version}] - ${today}`);
+      content = content.replace(unreleased, `## [Unreleased]\n\n${heading}`);
+    } else if (/^## /m.test(content)) {
+      content = content.replace(/^## /m, `${heading}\n\n## `);
+    } else {
+      content = `${content.trimEnd()}\n\n${heading}\n`;
     }
   }