feat(vom): canvas design and fixtures

2026-09-10 13:01:23 +08:00 · 2026-09-08 16:49:43 +08:00
51 changed files with 3105 additions and 3587 deletions
@@ -38,7 +38,7 @@ jobs:
        run: cargo test --workspace --locked

  windows-daemon:
-    name: Windows daemon, installer and cancellation regression tests
+    name: Windows daemon and update regression tests
    runs-on: windows-latest

    steps:
@@ -55,16 +55,8 @@ jobs:
      - name: Run Windows update tests
        run: cargo test -p bsk --lib --locked cli::update::tests

-      - 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
+      - name: Run Windows update process tests
+        run: cargo test -p bsk --test windows_update --locked

  frontend:
    name: Frontend lint, typecheck, tests, build
@@ -147,26 +147,20 @@ 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 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.
+It injects native `browser_*` tools (no shelling out to `bsk`) and a live Web UI
+overlay of each Agent Window.

-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):
+Add it to a dsh profile, then start that profile:

 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```

-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.
+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.

 ## How It Works

@@ -125,22 +125,16 @@ 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)。它为 Agent 提供原生 `browser_*` 工具，由插件代为调用 `bsk`，并在 Web UI 中实时展示浏览器会话。
+在用 [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。

-先安装 `bsk` CLI 并连接浏览器扩展，再将插件装进 dsh profile 并启动（将 `web` 替换为你的 profile 名称）：
+把它装进某个 dsh profile，然后启动该 profile：

 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```

-插件自带 `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)。
+插件自带 skill，所以在 dsh 下无需执行 `bsk install-skill`；但 `bsk` CLI 和浏览器扩展仍是前置条件。工具清单、配置项与观察浮层见[插件 README](packages/dsh-plugin-browserskill/README.md)。

 ## 工作原理

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolveNodeGeometry } from "../frame-geometry";
+import { resolveFrameProjection, resolveNodeGeometry } from "../frame-geometry";
 import {
  clipPolygon,
  polygonArea,
@@ -10,7 +10,6 @@ import {
  rectPolygon,
  regionBounds,
 } from "../geometry";
-import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";

 describe("frame geometry projection", () => {
@@ -83,24 +82,28 @@ describe("frame geometry projection", () => {
        throw new Error(`unexpected child command ${method}`);
      }) as CdpRunner["sendToTarget"],
    };
-    const projection = await new GeometryContext(cdp, 4, {
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "same-process-parent",
-          parentFrameId: "main",
-          ownerBackendNodeId: 10,
-          target: { tabId: 4 },
-        },
-        {
-          frameId: "oopif",
-          parentFrameId: "same-process-parent",
-          ownerBackendNodeId: 20,
-          target: { tabId: 4, sessionId: "oopif-session" },
-        },
-      ],
-    }).targetProjection("oopif");
+    const projection = await resolveFrameProjection(
+      cdp,
+      {
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "same-process-parent",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4 },
+          },
+          {
+            frameId: "oopif",
+            parentFrameId: "same-process-parent",
+            ownerBackendNodeId: 20,
+            target: { tabId: 4, sessionId: "oopif-session" },
+          },
+        ],
+      },
+      "oopif",
+    );

    expect(projection?.edges).toEqual([
      {
@@ -1,380 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import { resolveNodeGeometry } from "../frame-geometry";
-import { rectPolygon } from "../geometry";
-import {
-  projectSnapshotRect,
-  screenshotPageRect,
-  snapshotViewportRect,
-} from "../geometry/coordinate-types";
-import { GeometryContext } from "../geometry/frame-context";
-import type { CdpRunner } from "../shared";
-
-const target = { tabId: 4 };
-const graph: CdpFrameGraph = {
-  rootFrameId: "main",
-  frames: [
-    { frameId: "main", target },
-    { frameId: "child", parentFrameId: "main", ownerBackendNodeId: 10, target },
-  ],
-};
-
-function driver() {
-  const send = vi.fn(async (_tab: number, method: string): Promise<object> => {
-    if (method === "Page.getLayoutMetrics")
-      return { 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" } };
-    if (method === "Runtime.callFunctionOn")
-      return { result: { value: { width: 300, height: 200 } } };
-    if (method === "Runtime.releaseObject") return {};
-    throw new Error(method);
-  });
-  return { send: send as CdpRunner["send"], getFrameGraph: vi.fn(async () => graph), calls: send };
-}
-
-describe("measurement geometry context", () => {
-  it("shares in-flight frame measurements, but never shares them with the next context", async () => {
-    const cdp = driver();
-    const context = new GeometryContext(cdp, 4);
-    const results = await Promise.all(
-      Array.from({ length: 20 }, () => context.targetProjection("child")),
-    );
-    expect(results.every((value) => value === results[0])).toBe(true);
-    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(1);
-    expect(cdp.calls.mock.calls.map(([, method]) => method)).toEqual([
-      "Page.getLayoutMetrics",
-      "DOM.getBoxModel",
-    ]);
-    await new GeometryContext(cdp, 4).targetProjection("child");
-    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(2);
-    expect(cdp.calls.mock.calls).toHaveLength(4);
-  });
-
-  it("projects frame-local snapshot CSS bounds through the scaled owner content quad", async () => {
-    const cdp = driver();
-    const context = new GeometryContext(cdp, 4);
-    const source = { target, frameId: "child" };
-    const projection = await context.snapshotProjection(source, 10, [], {
-      width: 1000,
-      height: 1000,
-    });
-    if (projection.status !== "available") throw new Error("expected available projection");
-    const input = snapshotViewportRect([17, 23, 120, 40], source, { 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 });
-    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(
-      1,
-    );
-    expect(
-      cdp.calls.mock.calls.filter(([, method]) => method === "Runtime.releaseObject"),
-    ).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 },
-    )!;
-    const projection = {
-      source: { target, frameId: "main" },
-      geometry: { sourceClips: [], edges: [], topViewport: { width: 800, height: 600 } },
-    };
-    expect(projectSnapshotRect(input, projection)).toEqual({
-      x: 20,
-      y: 30,
-      width: 120,
-      height: 40,
-    });
-    expect(
-      projectSnapshotRect(input, { ...projection, source: { target, frameId: "other" } }),
-    ).toBeNull();
-    expect(
-      projectSnapshotRect(input, {
-        ...projection,
-        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();
-  });
-
-  it("does not turn a border quad or a failed owner read into a content projection", async () => {
-    const cdp: CdpRunner = {
-      send: vi.fn(async () => ({
-        model: { border: [0, 0, 100, 0, 100, 100, 0, 100] },
-      })) as CdpRunner["send"],
-    };
-    expect(
-      await new GeometryContext(cdp, 4).snapshotProjection({ target, frameId: "child" }, 10, [], {
-        width: 100,
-        height: 100,
-      }),
-    ).toEqual({
-      status: "unavailable",
-      source: { target, frameId: "child" },
-      ownerBackendNodeId: 10,
-    });
-  });
-
-  it("keeps ancestor clips in target coordinates instead of applying nested offsets twice", async () => {
-    const cdp = driver();
-    const projection = await new GeometryContext(cdp, 4).snapshotProjection(
-      { target, frameId: "nested" },
-      10,
-      [rectPolygon({ x: 60, y: 620, w: 100, h: 100 })],
-      { width: 1000, height: 1000 },
-    );
-    if (projection.status !== "available") throw new Error("expected available projection");
-    const input = snapshotViewportRect(
-      [0, 0, 300, 200],
-      { target, frameId: "nested" },
-      { x: 0, y: 0 },
-    );
-    expect(projectSnapshotRect(input!, projection.projection)).toEqual({
-      x: 60,
-      y: 620,
-      width: 100,
-      height: 100,
-    });
-  });
-
-  it("rejects malformed frame ancestry without looping", async () => {
-    const cdp = driver();
-    const cycle: CdpFrameGraph = {
-      rootFrameId: "a",
-      frames: [
-        { frameId: "a", parentFrameId: "b", target },
-        { frameId: "b", parentFrameId: "a", target },
-      ],
-    };
-    expect(await new GeometryContext(cdp, 4, cycle).targetProjection("a")).toBeNull();
-    expect(cdp.calls).not.toHaveBeenCalled();
-    const orphan: CdpFrameGraph = {
-      rootFrameId: "a",
-      frames: [{ frameId: "a", parentFrameId: "missing", target }],
-    };
-    expect(await new GeometryContext(cdp, 4, orphan).targetProjection("a")).toBeNull();
-  });
-
-  it("rejects a live node whose frame belongs to another target before any DOM input", async () => {
-    const cdp = driver();
-    expect(
-      await resolveNodeGeometry(
-        cdp,
-        4,
-        { target: { tabId: 4, sessionId: "wrong" }, frameId: "child", backendNodeId: 20 },
-        { scrollIntoView: true },
-      ),
-    ).toMatchObject({ code: "cdp_failed" });
-    expect(cdp.calls).not.toHaveBeenCalled();
-  });
-
-  it("bounds concurrent measurements and does not dispatch queued reads after cancellation", async () => {
-    let active = 0;
-    let peak = 0;
-    const release: Array<() => void> = [];
-    const send = vi.fn(async () => {
-      active++;
-      peak = Math.max(peak, active);
-      await new Promise<void>((resolve) => release.push(resolve));
-      active--;
-      return { cssLayoutViewport: { clientWidth: 100, clientHeight: 100 } };
-    });
-    const controller = new AbortController();
-    const context = new GeometryContext(
-      { send: send as CdpRunner["send"] },
-      4,
-      undefined,
-      controller.signal,
-    );
-    const tasks = Array.from({ length: 8 }, (_, index) =>
-      context.viewport({ tabId: 4, sessionId: String(index) }),
-    );
-    const settled = Promise.allSettled(tasks);
-    expect(send).toHaveBeenCalledTimes(4);
-    controller.abort();
-    for (const done of release) done();
-    const results = await settled;
-    expect(peak).toBe(4);
-    expect(send).toHaveBeenCalledTimes(4);
-    expect(results.filter((item) => item.status === "rejected")).toHaveLength(4);
-  });
-
-  it("releases an owner object even when cancellation arrives before its viewport read", async () => {
-    const controller = new AbortController();
-    const cdp = driver();
-    const original = cdp.calls.getMockImplementation()!;
-    cdp.calls.mockImplementation(async (tab, method) => {
-      const result = await original(tab, method);
-      if (method === "DOM.resolveNode") controller.abort();
-      return result;
-    });
-    const context = new GeometryContext(cdp, 4, undefined, controller.signal);
-    await expect(
-      context.snapshotProjection({ target, frameId: "child" }, 10, [], {
-        width: 1000,
-        height: 1000,
-      }),
-    ).rejects.toMatchObject({ name: "AbortError" });
-    expect(cdp.calls.mock.calls.map(([, method]) => method)).toEqual([
-      "DOM.getBoxModel",
-      "DOM.resolveNode",
-      "Runtime.releaseObject",
-    ]);
-  });
-
-  it("reads live owner geometry only after scrolling", async () => {
-    const cdp = driver();
-    const original = cdp.calls.getMockImplementation()!;
-    let scrolled = false;
-    cdp.calls.mockImplementation(async (tab, method) => {
-      if (method === "DOM.scrollIntoViewIfNeeded") {
-        scrolled = true;
-        return {};
-      }
-      if (method === "DOM.getContentQuads") {
-        expect(scrolled).toBe(true);
-        return { quads: [[60, 620, 100, 620, 100, 640, 60, 640]] };
-      }
-      if (method === "DOM.getBoxModel") expect(scrolled).toBe(true);
-      return original(tab, method);
-    });
-    expect(
-      await resolveNodeGeometry(
-        cdp,
-        4,
-        { target, frameId: "child", backendNodeId: 20 },
-        { scrollIntoView: true },
-      ),
-    ).toMatchObject({ topBounds: { x: 60, y: 620, width: 40, height: 20 } });
-    expect(cdp.getFrameGraph).toHaveBeenCalledTimes(1);
-    expect(cdp.calls.mock.calls.filter(([, method]) => method === "DOM.getBoxModel")).toHaveLength(
-      1,
-    );
-  });
-
-  it("adapts viewport CSS bounds to page DIP with scroll and browser zoom, never raster DPR", () => {
-    const viewport = { width: 1600, height: 1000, scrollX: 10, scrollY: 100, cssToDip: 0.9 };
-    const clip = screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, viewport);
-    expect(clip).toEqual({ space: "page-dip", rect: { x: 27, y: 117, width: 108, height: 36 } });
-    expect(
-      screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, { ...viewport, cssToDip: NaN }),
-    ).toBeNull();
-    expect(
-      screenshotPageRect({ x: 20, y: 30, width: 120, height: 40 }, { ...viewport, cssToDip: 0 }),
-    ).toBeNull();
-  });
-
-  it("retries a rejected measurement only in a new operation", async () => {
-    const cdp = driver();
-    cdp.calls.mockRejectedValueOnce(new Error("unavailable"));
-    const context = new GeometryContext(cdp, 4);
-    await expect(context.viewport(target)).rejects.toThrow("unavailable");
-    await expect(context.viewport(target)).rejects.toThrow("unavailable");
-    expect(cdp.calls).toHaveBeenCalledTimes(1);
-    expect(await new GeometryContext(cdp, 4).viewport(target)).toEqual({
-      width: 1000,
-      height: 1000,
-    });
-  });
-});
@@ -266,15 +266,7 @@ describe("handleScreenshot", () => {
    expect(sent.find((c) => c.method === "Page.captureScreenshot")).toBeUndefined();
  });

-  it.each([
-    { zoom: 1, scroll: 0, expected: { x: 10, y: 20, width: 100, height: 40 } },
-    { zoom: 0.9, scroll: 100, expected: { x: 9, y: 108, width: 90, height: 36 } },
-    { zoom: 1.25, scroll: 100, expected: { x: 12.5, y: 150, width: 125, height: 50 } },
-  ])("captures a ref in page DIP at zoom $zoom and scroll $scroll", async ({
-    zoom,
-    scroll,
-    expected,
-  }) => {
+  it("captures a clipped PNG when ref is given", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.refStore.set("e5", 999, { tabId: 7 });
@@ -282,10 +274,6 @@ describe("handleScreenshot", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.getContentQuads": () => ({ quads: [[10, 20, 110, 20, 110, 60, 10, 60]] }),
      "Page.captureScreenshot": () => ({ data: TINY_PNG }),
-      "Page.getLayoutMetrics": () => ({
-        cssLayoutViewport: { clientWidth: 1280, clientHeight: 720, pageX: 0, pageY: scroll },
-        cssVisualViewport: { zoom },
-      }),
    });
    const captureVisibleTab = vi.fn();
    const res = await handleScreenshot(
@@ -309,8 +297,7 @@ describe("handleScreenshot", () => {
        clip?: { x: number; y: number; width: number; height: number };
      }
    )?.clip;
-    expect(clip).toMatchObject(expected);
-    expect(sent.filter((c) => c.method === "Page.getLayoutMetrics")).toHaveLength(1);
+    expect(clip).toMatchObject({ x: 10, y: 20, width: 100, height: 40 });
  });

  it("returns not_found for unknown ref", async () => {
@@ -668,60 +655,6 @@ describe("buildVomScene", () => {
    expect(nestedInput?.parentId).toBe(result.nodes.find((item) => item.backendNodeId === 210)?.id);
  });

-  it("excludes an overlay only in its owning document when target backend ids collide", () => {
-    const owner = (id: number): CapturedNode => ({
-      backendNodeId: id,
-      parentBackendNodeId: null,
-      frameId: "main",
-      tag: "iframe",
-      attrs: {},
-      rect: { x: id * 10, y: 0, w: 200, h: 100 },
-      paintOrder: 0,
-      position: "static",
-      pointerEvents: "auto",
-    });
-    const owners = [owner(10), owner(20)];
-    const result = buildFrameVomScene(
-      [
-        {
-          frameId: "main",
-          contextScopeId: "main",
-          target: { tabId: 7 },
-          domNodes: owners,
-          axNodes: [],
-        },
-        ...["left", "right"].map((frameId, i) => ({
-          frameId,
-          contextScopeId: frameId,
-          parentFrameId: "main",
-          ownerBackendNodeId: owners[i].backendNodeId,
-          target: { tabId: 7, sessionId: frameId },
-          excludedBackendNodeIds: new Set(i === 0 ? [7] : []),
-          domNodes: [],
-          axNodes: [
-            {
-              nodeId: "button",
-              frameId,
-              backendDOMNodeId: 7,
-              role: { type: "role", value: "button" },
-              name: { type: "computedString", value: frameId + " action" },
-            },
-          ],
-        })),
-      ],
-      {
-        nodes: owners,
-        viewport: { width: 800, height: 600 },
-        iframeNodes: new Map(),
-        excludedBackendNodeIds: new Set(),
-      },
-    );
-    const rendered = renderVom(result);
-    expect(rendered.text).not.toContain("left action");
-    expect(rendered.text).toContain("right action");
-    expect(rendered.refs.find((ref) => ref.backendNodeId === 7)?.frameId).toBe("right");
-  });
-
  it("does not place a child document at the page root when its frame boundary is unresolved", () => {
    const childNode: CapturedNode = {
      backendNodeId: 101,
@@ -3201,9 +3134,7 @@ describe("handleSnapshot", () => {
    cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
  };

-  function makeFrameAwareDeps(
-    ownerGeometry: "unavailable" | "available" | "clipped" = "unavailable",
-  ) {
+  function makeFrameAwareDeps() {
    const strings = ["html", "body", "iframe", "button", "title", "Remote", "static", "auto"];
    const i = (value: string) => strings.indexOf(value);
    const styles = [i("static"), i("auto"), i("auto")];
@@ -3283,16 +3214,6 @@ describe("handleSnapshot", () => {
    ];
    const send = vi.fn(async (_tabId: number, method: string) => {
      if (method === "Page.getLayoutMetrics") return VP_METRICS;
-      if (ownerGeometry !== "unavailable") {
-        if (method === "DOM.getBoxModel") {
-          const x = ownerGeometry === "clipped" ? 10000 : 100;
-          return { model: { content: [x, 100, x + 400, 100, x + 400, 400, x, 400] } };
-        }
-        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
-        if (method === "Runtime.callFunctionOn")
-          return { result: { value: { width: 400, height: 300 } } };
-        if (method === "Runtime.releaseObject") return {};
-      }
      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
      if (method === "Accessibility.getFullAXTree") return { nodes: mainAx };
@@ -3533,43 +3454,6 @@ describe("handleSnapshot", () => {
    expect(result.text).toContain("•••");
  });

-  it.each([
-    undefined,
-    100,
-    0,
-  ])("reports unavailable iframe geometry within the observation budget %s", async (maxTokens) => {
-    const result = await captureVomObservation(makeFrameAwareDeps().cdp, 4, "https://example.com", {
-      maxTokens,
-    });
-    expect(result.text.match(/@warning/g)).toHaveLength(1);
-    expect(result.text).toContain("iframe geometry incomplete");
-    expect(result.text.startsWith("@vom 1\n")).toBe(true);
-    if (maxTokens === undefined) {
-      expect(result.truncated).toBe(false);
-      expect(result.text).toContain("Frame action");
-      expect(result.matchNodes.find((node) => node.backendNodeId === 22)).toMatchObject({
-        rect: null,
-        localRect: { x: 20, y: 30, w: 120, h: 40 },
-      });
-    }
-    if (maxTokens === 100) expect(Math.ceil(result.text.length / 4)).toBeLessThanOrEqual(maxTokens);
-  });
-
-  it.each([
-    "available",
-    "clipped",
-  ] as const)("does not report successful %s geometry as an observation failure", async (ownerGeometry) => {
-    const result = await captureVomObservation(
-      makeFrameAwareDeps(ownerGeometry).cdp,
-      4,
-      "https://example.com",
-    );
-    expect(result.text).not.toContain("@warning");
-    const node = result.matchNodes.find((item) => item.backendNodeId === 22);
-    if (ownerGeometry === "clipped") expect(node?.rect).toBeNull();
-    else expect(node?.rect).toEqual({ x: 120, y: 130, w: 120, h: 40 });
-  });
-
  it("keeps frames and rendered refs on the same frame identity", async () => {
    const deps = makeFrameAwareDeps();

@@ -1,21 +1,24 @@
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import { type CdpFrame, type CdpFrameGraph, type CdpTarget } from "@/browser-driver/frame-graph";
 import type { RpcError } from "@/transport/types";
 import { nodeContentRegion, scrollNodeIntoView } from "./element-geometry";
 import {
  clipPolygon,
+  type GeometryProjection,
  type Point,
  type Polygon,
+  type ProjectiveEdge,
+  parseCdpQuad,
  polygonArea,
  polygonCentroid,
  projectRegionToViewport,
+  type Quad,
  type Region,
  rectPolygon,
  regionBounds,
+  type Size,
  type ViewportRect,
 } from "./geometry";
-import type { CssViewport } from "./geometry/coordinate-types";
-import { cssViewport, GeometryContext } from "./geometry/frame-context";
-import { type CdpRunner, cdpRunnerForTarget, isRpcError } from "./shared";
+import { type CdpRunner, cdpRunnerForTarget, isRpcError, sendToCdpTarget } from "./shared";

 export interface NodeAddress {
  target: CdpTarget;
@@ -24,8 +27,6 @@ export interface NodeAddress {
 }

 export interface ResolvedNodeGeometry {
-  /** The same top-level measurement used by projection, for screenshot coordinate adaptation. */
-  topViewport: CssViewport;
  topVisibleRegions: Region;
  topBounds: ViewportRect;
  /** Point in the top-level tab viewport, used by root-target input events. */
@@ -38,16 +39,145 @@ function geometryError(message: string): RpcError {
  return { code: "cdp_failed", message };
 }

+function frameMap(graph: CdpFrameGraph): Map<string, CdpFrame> {
+  return new Map(graph.frames.map((frame) => [frame.frameId, frame]));
+}
+
+function targetRootFrame(byId: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
+  const seen = new Set<string>();
+  let current = frame;
+  while (current.parentFrameId) {
+    if (seen.has(current.frameId)) return null;
+    seen.add(current.frameId);
+    const parent = byId.get(current.parentFrameId);
+    if (!parent || parent.target.sessionId !== current.target.sessionId) break;
+    current = parent;
+  }
+  return current;
+}
+
+function frameAncestry(graph: CdpFrameGraph, frameId: string): CdpFrame[] | null {
+  const byId = frameMap(graph);
+  const path: CdpFrame[] = [];
+  const seen = new Set<string>();
+  let current = byId.get(frameId);
+  if (!current) return null;
+  while (current.parentFrameId) {
+    if (seen.has(current.frameId)) return null;
+    seen.add(current.frameId);
+    path.push(current);
+    const parent = byId.get(current.parentFrameId);
+    if (!parent) return null;
+    current = parent;
+  }
+  return path;
+}
+
+async function targetViewport(cdp: CdpRunner, target: CdpTarget): Promise<Size | null> {
+  const metrics = await sendToCdpTarget<{
+    cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
+    layoutViewport?: { clientWidth?: number; clientHeight?: number };
+  }>(cdp, target, "Page.getLayoutMetrics", {});
+  const viewport = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+  const width = viewport.clientWidth ?? 0;
+  const height = viewport.clientHeight ?? 0;
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
+async function ownerContentQuad(
+  cdp: CdpRunner,
+  parent: CdpFrame,
+  ownerBackendNodeId: number,
+): Promise<Quad | null> {
+  const result = await sendToCdpTarget<{ model?: { content?: number[] } }>(
+    cdp,
+    parent.target,
+    "DOM.getBoxModel",
+    { backendNodeId: ownerBackendNodeId },
+  );
+  return parseCdpQuad(result.model?.content);
+}
+
+async function sameTargetFrameClips(
+  cdp: CdpRunner,
+  byId: Map<string, CdpFrame>,
+  frame: CdpFrame,
+  targetRoot: CdpFrame,
+): Promise<Polygon[] | null> {
+  const clips: Polygon[] = [];
+  let current = frame;
+  const seen = new Set<string>();
+  while (current.frameId !== targetRoot.frameId) {
+    if (seen.has(current.frameId) || !current.parentFrameId) return null;
+    seen.add(current.frameId);
+    const parent = byId.get(current.parentFrameId);
+    if (!parent || current.ownerBackendNodeId === undefined) return null;
+    const clip = await ownerContentQuad(cdp, parent, current.ownerBackendNodeId);
+    if (!clip) return null;
+    clips.push(clip);
+    current = parent;
+  }
+  return clips;
+}
+
+export async function resolveFrameProjection(
+  cdp: CdpRunner,
+  graph: CdpFrameGraph,
+  frameId: string,
+): Promise<GeometryProjection | null> {
+  const byId = frameMap(graph);
+  const frame = byId.get(frameId);
+  if (!frame) return null;
+  let targetRoot = targetRootFrame(byId, frame);
+  if (!targetRoot) return null;
+  const sourceViewport = await targetViewport(cdp, targetRoot.target);
+  if (!sourceViewport) return null;
+  const sourceClips = await sameTargetFrameClips(cdp, byId, frame, targetRoot);
+  if (!sourceClips) return null;
+
+  const edges: ProjectiveEdge[] = [];
+  while (targetRoot.parentFrameId) {
+    const parent = byId.get(targetRoot.parentFrameId);
+    if (!parent || targetRoot.ownerBackendNodeId === undefined) return null;
+    const destinationQuad = await ownerContentQuad(cdp, parent, targetRoot.ownerBackendNodeId);
+    if (!destinationQuad) return null;
+    const source =
+      edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
+    if (!source) return null;
+    const parentTargetRoot = targetRootFrame(byId, parent);
+    if (!parentTargetRoot) return null;
+    const destinationClips = await sameTargetFrameClips(cdp, byId, parent, parentTargetRoot);
+    if (!destinationClips) return null;
+    edges.push({ sourceViewport: source, destinationQuad, destinationClips });
+    targetRoot = parentTargetRoot;
+  }
+
+  const topViewport =
+    edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
+  return topViewport ? { sourceClips, edges, topViewport } : null;
+}
+
+async function loadFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
+  if (!cdp.getFrameGraph) return null;
+  try {
+    return await cdp.getFrameGraph(tabId);
+  } catch (error) {
+    console.debug("[bsk frame-geometry] frame graph resolution failed", error);
+    return null;
+  }
+}
+
 async function scrollFrameOwners(
  cdp: CdpRunner,
  tabId: number,
-  context: GeometryContext,
+  graph: CdpFrameGraph,
  frameId: string,
 ): Promise<RpcError | null> {
-  const ancestry = await context.ancestry(frameId);
+  const byId = frameMap(graph);
+  const ancestry = frameAncestry(graph, frameId);
  if (!ancestry) return geometryError(`could not resolve frame ancestry for ${frameId}`);
  for (const child of [...ancestry].reverse()) {
-    const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
+    const parent = child.parentFrameId ? byId.get(child.parentFrameId) : undefined;
    if (!parent || child.ownerBackendNodeId === undefined) {
      return geometryError(`could not resolve frame owner for ${child.frameId}`);
    }
@@ -61,20 +191,17 @@ async function scrollFrameOwners(
  return null;
 }

-async function scrollElementWithContext(
+async function scrollElementWithFrameGraph(
  cdp: CdpRunner,
  tabId: number,
  target: CdpTarget,
  backendNodeId: number,
  frameId: string | undefined,
-  context: GeometryContext,
+  graph: CdpFrameGraph | null,
 ): Promise<RpcError | null> {
  if (frameId) {
-    const frame = await context.frame(frameId);
-    if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(target)) {
-      return geometryError("node frame does not belong to its target");
-    }
-    const error = await scrollFrameOwners(cdp, tabId, context, frameId);
+    if (!graph) return geometryError(`could not resolve frame graph for ${frameId}`);
+    const error = await scrollFrameOwners(cdp, tabId, graph, frameId);
    if (error) return error;
  } else if (target.sessionId) {
    return geometryError("an OOPIF node address requires frameId");
@@ -89,15 +216,8 @@ export async function scrollElementAndFramesIntoView(
  backendNodeId: number,
  frameId?: string,
 ): Promise<RpcError | null> {
-  if (target.tabId !== tabId) return geometryError("node target belongs to another tab");
-  return scrollElementWithContext(
-    cdp,
-    tabId,
-    target,
-    backendNodeId,
-    frameId,
-    new GeometryContext(cdp, tabId),
-  );
+  const graph = frameId ? await loadFrameGraph(cdp, tabId) : null;
+  return scrollElementWithFrameGraph(cdp, tabId, target, backendNodeId, frameId, graph);
 }

 function largestRegion(regions: Region): Polygon | null {
@@ -120,32 +240,23 @@ export async function resolveNodeGeometry(
    if (address.target.sessionId && !address.frameId) {
      return geometryError("an OOPIF node address requires frameId");
    }
-    if (address.target.tabId !== tabId) return geometryError("node target belongs to another tab");
-    const context = new GeometryContext(cdp, tabId);
-    const graph = address.frameId ? await context.graph() : null;
-    if (address.frameId && graph) {
-      const frame = await context.frame(address.frameId);
-      if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(address.target)) {
-        return geometryError("node frame does not belong to its target");
-      }
-    }
+    const graph = address.frameId ? await loadFrameGraph(cdp, tabId) : null;
    if (address.frameId && !graph) {
      return geometryError(`could not resolve frame graph for ${address.frameId}`);
    }

    if (options.scrollIntoView) {
-      const scrollError = await scrollElementWithContext(
+      const scrollError = await scrollElementWithFrameGraph(
        cdp,
        tabId,
        address.target,
        address.backendNodeId,
        address.frameId,
-        context,
+        graph,
      );
      if (scrollError) return scrollError;
    }

-    // Only topology was read above. Begin live measurements after scrolling.
    const localRegion = await nodeContentRegion(
      cdpRunnerForTarget(cdp, address.target),
      tabId,
@@ -156,7 +267,7 @@ export async function resolveNodeGeometry(
    let topVisibleRegions: Region;
    let targetActionPoint: Point | null = null;
    if (address.frameId && graph) {
-      const projection = await context.targetProjection(address.frameId);
+      const projection = await resolveFrameProjection(cdp, graph, address.frameId);
      if (!projection)
        return geometryError(`could not resolve frame geometry for ${address.frameId}`);
      topVisibleRegions = projectRegionToViewport(localRegion, projection);
@@ -179,7 +290,7 @@ export async function resolveNodeGeometry(
        targetActionPoint = localActionRegion ? polygonCentroid(localActionRegion) : null;
      }
    } else {
-      const viewport = await context.viewport(address.target);
+      const viewport = await targetViewport(cdp, address.target);
      if (!viewport) return geometryError("could not resolve top viewport geometry");
      topVisibleRegions = localRegion
        .map((polygon) =>
@@ -198,13 +309,7 @@ export async function resolveNodeGeometry(
      return { code: "permission_denied", message: "element not visible in its target" };
    }
    targetActionPoint ??= actionPoint;
-    return {
-      topVisibleRegions,
-      topBounds,
-      actionPoint,
-      targetActionPoint,
-      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
-    };
+    return { topVisibleRegions, topBounds, actionPoint, targetActionPoint };
  } catch (error) {
    return geometryError(error instanceof Error ? error.message : String(error));
  }
@@ -245,3 +245,22 @@ export function projectRectToViewport(
  if (!rect) return null;
  return regionBounds(projectRegionToViewport([rectPolygon(rect)], projection));
 }
+
+export function childFrameProjection(
+  parent: GeometryProjection,
+  ownerRectInParent: { x: number; y: number; w: number; h: number },
+): GeometryProjection {
+  const destinationQuad = rectPolygon(ownerRectInParent);
+  return {
+    sourceClips: [],
+    edges: [
+      {
+        sourceViewport: { width: ownerRectInParent.w, height: ownerRectInParent.h },
+        destinationQuad,
+        destinationClips: parent.sourceClips,
+      },
+      ...parent.edges,
+    ],
+    topViewport: parent.topViewport,
+  };
+}
@@ -1,102 +0,0 @@
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
-import type { GeometryProjection, ViewportRect } from "../geometry";
-import { projectRectToViewport } from "../geometry";
-
-export interface CoordinateOwner {
-  target: CdpTarget;
-  frameId?: string;
-}
-
-export interface FrameViewportRect {
-  space: "frame-viewport-css";
-  owner: CoordinateOwner;
-  rect: ViewportRect;
-}
-
-export interface SnapshotProjection {
-  source: CoordinateOwner;
-  geometry: GeometryProjection;
-}
-
-/** A failed owner read is different from a successfully projected, clipped-out rect. */
-export interface UnavailableFrameProjection {
-  status: "unavailable";
-  source: CoordinateOwner;
-  ownerBackendNodeId: number;
-}
-
-export type SnapshotProjectionResult =
-  | { status: "available"; projection: SnapshotProjection }
-  | UnavailableFrameProjection;
-
-/** Descendants inherit the failed boundary without attempting another owner read. */
-export type FrameProjectionIssue =
-  | UnavailableFrameProjection
-  | { status: "blocked"; source: CoordinateOwner; cause: UnavailableFrameProjection };
-
-export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
-
-/** DOMSnapshot bounds are document-relative CSS pixels, independent of raster DPR. */
-export function snapshotViewportRect(
-  bounds: number[],
-  owner: CoordinateOwner,
-  scroll: { x: number; y: number },
-): FrameViewportRect | null {
-  if (bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
-  const [x, y, width, height] = bounds;
-  if (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 },
-  };
-}
-
-export function projectSnapshotRect(
-  input: FrameViewportRect,
-  projection: SnapshotProjection,
-): ViewportRect | null {
-  if (
-    input.owner.frameId !== projection.source.frameId ||
-    cdpTargetKey(input.owner.target) !== cdpTargetKey(projection.source.target)
-  ) {
-    return null;
-  }
-  const { x, y, width: w, height: h } = input.rect;
-  return projectRectToViewport({ x, y, w, h }, projection.geometry);
-}
-
-/** CSS viewport metadata; browser zoom is distinct from raster devicePixelRatio. */
-export interface CssViewport {
-  width: number;
-  height: number;
-  scrollX: number;
-  scrollY: number;
-  cssToDip: number;
-}
-
-/** Page.captureScreenshot takes page-relative DIP, not viewport-relative CSS pixels. */
-export function screenshotPageRect(
-  rect: ViewportRect,
-  viewport: CssViewport,
-): { space: "page-dip"; rect: ViewportRect } | null {
-  const { cssToDip, scrollX, scrollY } = viewport;
-  if (
-    ![rect.x, rect.y, rect.width, rect.height, cssToDip, scrollX, scrollY].every(Number.isFinite) ||
-    cssToDip <= 0 ||
-    rect.width <= 0 ||
-    rect.height <= 0
-  )
-    return null;
-  return {
-    space: "page-dip",
-    rect: {
-      x: (rect.x + scrollX) * cssToDip,
-      y: (rect.y + scrollY) * cssToDip,
-      width: rect.width * cssToDip,
-      height: rect.height * cssToDip,
-    },
-  };
-}
@@ -1,333 +0,0 @@
-import {
-  type CdpFrame,
-  type CdpFrameGraph,
-  type CdpTarget,
-  cdpTargetKey,
-} from "@/browser-driver/frame-graph";
-import {
-  type GeometryProjection,
-  type Polygon,
-  type ProjectiveEdge,
-  parseCdpQuad,
-  type Quad,
-  type Size,
-} from "../geometry";
-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 };
-  cssLayoutViewport?: {
-    clientWidth?: number;
-    clientHeight?: number;
-    pageX?: number;
-    pageY?: number;
-  };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
-}
-
-/** 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;
-  return {
-    width: value?.clientWidth ?? 0,
-    height: value?.clientHeight ?? 0,
-    scrollX: value?.pageX ?? 0,
-    scrollY: value?.pageY ?? 0,
-    cssToDip: metrics.cssVisualViewport?.zoom ?? metrics.visualViewport?.zoom ?? 1,
-  };
-}
-
-/** One read-only measurement phase. Discard after scrolling or any later operation. */
-export class GeometryContext {
-  private readonly metrics = new Map<string, Promise<LayoutMetrics>>();
-  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>;
-  private framesPromise?: Promise<Map<string, CdpFrame>>;
-
-  constructor(
-    private readonly cdp: CdpRunner,
-    private readonly tabId: number,
-    graph?: CdpFrameGraph,
-    private readonly signal?: AbortSignal,
-  ) {
-    if (graph) this.graphPromise = Promise.resolve(graph);
-  }
-
-  private async request<T>(
-    target: CdpTarget,
-    method: string,
-    params: object,
-    cleanup = false,
-  ): Promise<T> {
-    if (!cleanup && this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
-    if (this.active >= 4) await new Promise<void>((resolve) => this.waiting.push(resolve));
-    else this.active++;
-    try {
-      if (!cleanup && this.signal?.aborted)
-        throw new DOMException("geometry aborted", "AbortError");
-      return await sendToCdpTarget<T>(this.cdp, target, method, params);
-    } finally {
-      const next = this.waiting.shift();
-      if (next) next();
-      else this.active--;
-    }
-  }
-
-  graph(): Promise<CdpFrameGraph | null> {
-    this.graphPromise ??=
-      this.cdp.getFrameGraph?.(this.tabId).catch(() => null) ?? Promise.resolve(null);
-    return this.graphPromise;
-  }
-
-  private frames(): Promise<Map<string, CdpFrame>> {
-    this.framesPromise ??= this.graph().then(
-      (graph) => new Map(graph?.frames.map((frame) => [frame.frameId, frame]) ?? []),
-    );
-    return this.framesPromise;
-  }
-
-  async frame(frameId: string): Promise<CdpFrame | undefined> {
-    return (await this.frames()).get(frameId);
-  }
-
-  /** Topology only: safe to resolve before the caller scrolls frame owners. */
-  async ancestry(frameId: string): Promise<CdpFrame[] | null> {
-    const frames = await this.frames();
-    const path: CdpFrame[] = [];
-    const seen = new Set<string>();
-    let current = frames.get(frameId);
-    if (!current) return null;
-    while (current.parentFrameId) {
-      if (seen.has(current.frameId)) return null;
-      seen.add(current.frameId);
-      path.push(current);
-      const parent = frames.get(current.parentFrameId);
-      if (!parent) return null;
-      current = parent;
-    }
-    return path;
-  }
-
-  layoutMetrics(target: CdpTarget): Promise<LayoutMetrics> {
-    const key = cdpTargetKey(target);
-    let promise = this.metrics.get(key);
-    if (!promise) {
-      promise = this.request<LayoutMetrics>(target, "Page.getLayoutMetrics", {});
-      this.metrics.set(key, promise);
-    }
-    return promise;
-  }
-
-  async viewport(target: CdpTarget): Promise<Size | null> {
-    const { width, height } = cssViewport(await this.layoutMetrics(target));
-    return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
-      ? { width, height }
-      : null;
-  }
-
-  ownerContent(target: CdpTarget, backendNodeId: number): Promise<Quad | null> {
-    const key = `${cdpTargetKey(target)}:${backendNodeId}`;
-    let promise = this.owners.get(key);
-    if (!promise) {
-      promise = this.request<{ model?: { content?: number[] } }>(target, "DOM.getBoxModel", {
-        backendNodeId,
-      }).then((reply) => parseCdpQuad(reply.model?.content));
-      this.owners.set(key, promise);
-    }
-    return promise;
-  }
-
-  /** Same-target owner quads are already target-relative, including nested owners. */
-  async snapshotProjection(
-    source: CoordinateOwner,
-    ownerBackendNodeId: number,
-    ancestorClips: Polygon[],
-    viewport: Size,
-  ): Promise<SnapshotProjectionResult> {
-    const key = `${cdpTargetKey(source.target)}:${ownerBackendNodeId}`;
-    let promise = this.snapshotOwners.get(key);
-    if (!promise) {
-      promise = this.snapshotOwner(source.target, ownerBackendNodeId);
-      this.snapshotOwners.set(key, promise);
-    }
-    let owner: { quad: Quad; size: Size } | null;
-    try {
-      owner = await promise;
-    } catch (error) {
-      if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
-        throw error;
-      console.debug("[bsk geometry] frame owner unavailable", error);
-      owner = null;
-    }
-    return owner
-      ? {
-          status: "available",
-          projection: {
-            source,
-            geometry: {
-              sourceClips: [],
-              edges: [
-                {
-                  sourceViewport: owner.size,
-                  destinationQuad: owner.quad,
-                  destinationClips: ancestorClips,
-                },
-              ],
-              topViewport: viewport,
-            },
-          },
-        }
-      : { 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",
-      { backendNodeId },
-    );
-    const objectId = resolved.object?.objectId;
-    if (!objectId) return null;
-    try {
-      const reply = await this.request<{ result?: { value?: Size }; exceptionDetails?: unknown }>(
-        target,
-        "Runtime.callFunctionOn",
-        {
-          objectId,
-          functionDeclaration: `function() {
-          if (!this.isConnected) return null;
-          const style = getComputedStyle(this);
-          return {
-            width: this.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
-            height: this.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
-          };
-        }`,
-          returnByValue: true,
-        },
-      );
-      const size = reply.result?.value;
-      return !reply.exceptionDetails &&
-        size &&
-        Number.isFinite(size.width) &&
-        Number.isFinite(size.height) &&
-        size.width > 0 &&
-        size.height > 0
-        ? { quad, size }
-        : null;
-    } finally {
-      // Cleanup must still run if cancellation arrived after resolving the object.
-      await this.request(target, "Runtime.releaseObject", { objectId }, true).catch(() => {});
-    }
-  }
-
-  private targetRoot(frames: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
-    const seen = new Set<string>();
-    let current = frame;
-    while (current.parentFrameId) {
-      if (seen.has(current.frameId)) return null;
-      seen.add(current.frameId);
-      const parent = frames.get(current.parentFrameId);
-      if (!parent) return null;
-      if (cdpTargetKey(parent.target) !== cdpTargetKey(current.target)) break;
-      current = parent;
-    }
-    return current;
-  }
-
-  private async clips(
-    frames: Map<string, CdpFrame>,
-    frame: CdpFrame,
-    root: CdpFrame,
-  ): Promise<Polygon[] | null> {
-    const clips: Polygon[] = [];
-    let current = frame;
-    const seen = new Set<string>();
-    while (current.frameId !== root.frameId) {
-      if (seen.has(current.frameId) || !current.parentFrameId) return null;
-      seen.add(current.frameId);
-      const parent = frames.get(current.parentFrameId);
-      if (!parent || current.ownerBackendNodeId === undefined) return null;
-      const quad = await this.ownerContent(parent.target, current.ownerBackendNodeId);
-      if (!quad) return null;
-      clips.push(quad);
-      current = parent;
-    }
-    return clips;
-  }
-
-  /** Input is already in the frame's CDP target viewport, not its local viewport. */
-  targetProjection(frameId: string): Promise<GeometryProjection | null> {
-    let promise = this.projections.get(frameId);
-    if (!promise) {
-      promise = this.buildTargetProjection(frameId);
-      this.projections.set(frameId, promise);
-    }
-    return promise;
-  }
-
-  private async buildTargetProjection(frameId: string): Promise<GeometryProjection | null> {
-    const frames = await this.frames();
-    const frame = frames.get(frameId);
-    if (!frame) return null;
-    let root = this.targetRoot(frames, frame);
-    if (!root) return null;
-    const sourceViewport = await this.viewport(root.target);
-    if (!sourceViewport) return null;
-    const sourceClips = await this.clips(frames, frame, root);
-    if (!sourceClips) return null;
-    const edges: ProjectiveEdge[] = [];
-    const seen = new Set<string>();
-    while (root.parentFrameId) {
-      if (seen.has(root.frameId)) return null;
-      seen.add(root.frameId);
-      const parent = frames.get(root.parentFrameId);
-      if (!parent || root.ownerBackendNodeId === undefined) return null;
-      const destinationQuad = await this.ownerContent(parent.target, root.ownerBackendNodeId);
-      const source = await this.viewport(root.target);
-      const parentRoot = this.targetRoot(frames, parent);
-      if (!destinationQuad || !source || !parentRoot) return null;
-      const destinationClips = await this.clips(frames, parent, parentRoot);
-      if (!destinationClips) return null;
-      edges.push({ sourceViewport: source, destinationQuad, destinationClips });
-      root = parentRoot;
-    }
-    const topViewport = await this.viewport(root.target);
-    return topViewport ? { sourceClips, edges, topViewport } : null;
-  }
-}
@@ -1,74 +0,0 @@
-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;
-}
@@ -34,8 +34,6 @@ import type {
 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,
@@ -199,14 +197,15 @@ async function captureElementScreenshot(
  if (isRpcError(geometry)) return geometry;
  if (signal?.aborted) return cancelled("screenshot");
  const rect = geometry.topBounds;
-  const clip = screenshotPageRect(rect, geometry.topViewport);
-  if (!clip) return { code: "cdp_failed", message: "invalid screenshot coordinate space" };

  try {
    const shot = await cdp.send<{ data?: string }>(tabId, "Page.captureScreenshot", {
      format: "png",
      clip: {
-        ...clip.rect,
+        x: rect.x,
+        y: rect.y,
+        width: rect.width,
+        height: rect.height,
        scale: 1,
      },
    });
@@ -676,7 +675,6 @@ function legacyFrameDocuments(
      ...(pageUrl ? { url: pageUrl } : {}),
      axNodes: [],
      domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
-      excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(rootFrameId),
    },
  ];
  const pending = [...captured.iframeNodes.entries()];
@@ -700,7 +698,6 @@ function legacyFrameDocuments(
        target: parent.target,
        axNodes: [],
        domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
-        excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(frameId),
      });
      pending.splice(index, 1);
      progress = true;
@@ -987,19 +984,26 @@ function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedVie
  return { viewport, nodes: [], iframeNodes: new Map(), excludedBackendNodeIds: new Set() };
 }

+interface LayoutMetricsViewportReply {
+  cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number };
+}
+
 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 });
+    const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
    throwIfAborted(signal, "observation");
-    const source = cssViewport(metrics);
-    viewport = { width: source.width, height: source.height };
+    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+    viewport = {
+      width: source.clientWidth ?? 0,
+      height: source.clientHeight ?? 0,
+    };
  } catch (error) {
    if (isAbortError(error)) throw error;
  }
@@ -1012,13 +1016,12 @@ async function captureForVom(
  cdp: CdpRunner,
  tabId: number,
  options: CaptureVomObservationOptions,
-  geometry: GeometryContext,
 ): Promise<CapturedViewModel> {
  try {
-    return await captureViewModel(cdp, tabId, { signal: options.signal, geometry });
+    return await captureViewModel(cdp, tabId, { signal: options.signal });
  } catch (error) {
    if (isAbortError(error)) throw error;
-    return fallbackCapturedViewModel(cdp, tabId, geometry, options.signal);
+    return fallbackCapturedViewModel(cdp, tabId, options.signal);
  }
 }

@@ -1093,16 +1096,9 @@ export async function captureVomObservation(
  throwIfAborted(options.signal, "observation");
  await cdp.ensureAttachedToUrl?.(tabId, url);
  throwIfAborted(options.signal, "observation");
-  const geometry = new GeometryContext(cdp, tabId, undefined, options.signal);
-  const captured = await captureForVom(cdp, tabId, options, geometry);
+  const captured = await captureForVom(cdp, tabId, options);
  throwIfAborted(options.signal, "observation");
-  const documents = await captureFrameData<CdpAxNode>(
-    cdp,
-    tabId,
-    captured,
-    options.signal,
-    geometry,
-  );
+  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
  throwIfAborted(options.signal, "observation");
  const normalizedDocuments =
    documents.length === 1 && captured.iframeNodes.size > 0
@@ -1135,21 +1131,12 @@ export async function captureVomObservation(
    captured,
    hoverProbes.surfaceProbes,
  );
-  // 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 = captured.frameGeometryIssues?.length
-    ? "@warning iframe geometry incomplete: some frame content has no top-level coordinates.\n"
-    : "";
  const rendered = renderVom(decoratedScene, {
    maxDepth: options.maxDepth,
-    maxTokens:
-      !geometryNotice || options.maxTokens === undefined
-        ? options.maxTokens
-        : Math.max(0, options.maxTokens - Math.ceil(geometryNotice.length / 4)),
+    maxTokens: options.maxTokens,
    redactValues: options.redactValues,
    activeRegionPolicy: options.activeRegionPolicy,
  });
-  if (geometryNotice) rendered.text += `\n${geometryNotice.trimEnd()}`;
  throwIfAborted(options.signal, "observation");
  return projectRecordSafeObservation({
    rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",
@@ -1,6 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
-import type { CdpRunner } from "../../shared";
 import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";

 // Minimal but format-accurate captureSnapshot reply: a body with one
@@ -528,7 +527,6 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
-          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")],
@@ -559,12 +557,8 @@ describe("captureViewModel", () => {
      ],
    };

-    const { excludedBackendNodeIds, frameExcludedBackendNodeIds } = await captureViewModel(
-      makeCdp(snapshot),
-      4,
-    );
+    const { excludedBackendNodeIds } = 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 () => {
@@ -760,7 +754,7 @@ describe("captureViewModel", () => {
    expect(div?.rect).toMatchObject({ y: 0, h: 600 });
  });

-  it("keeps CSS snapshot bounds independent of legacy metrics ratio", async () => {
+  it("normalizes device-pixel bounds by devicePixelRatio", async () => {
    const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
    const i = (s: string) => S.indexOf(s);
    const snapshot = {
@@ -808,12 +802,6 @@ describe("captureViewModel", () => {
      w: 1000,
      h: 800,
    });
-    expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
-      x: 0,
-      y: 0,
-      w: 2000,
-      h: 1600,
-    });
  });

  it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -962,12 +950,6 @@ describe("captureViewModel", () => {
            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
          };
        }
-        if (method === "DOM.getBoxModel")
-          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
-        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
-        if (method === "Runtime.callFunctionOn")
-          return { result: { value: { width: 800, height: 400 } } };
-        if (method === "Runtime.releaseObject") return {};
        throw new Error(method);
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };
@@ -997,7 +979,7 @@ describe("captureViewModel", () => {
    expect(frameParentIds?.get("child-frame")).toBe("main-frame");
  });

-  it("projects iframe documents independently of owner snapshot geometry", async () => {
+  it("captures iframe documents without requiring owner-frame geometry", async () => {
    const S = [
      "html",
      "body",
@@ -1058,12 +1040,6 @@ describe("captureViewModel", () => {
            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
          };
        }
-        if (method === "DOM.getBoxModel")
-          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
-        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
-        if (method === "Runtime.callFunctionOn")
-          return { result: { value: { width: 800, height: 400 } } };
-        if (method === "Runtime.releaseObject") return {};
        throw new Error(method);
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };
@@ -1072,7 +1048,7 @@ describe("captureViewModel", () => {
    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 });
+    expect(input?.rect).toBeNull();
  });

  it("recursively normalizes nested iframe sub-documents", async () => {
@@ -1151,43 +1127,16 @@ describe("captureViewModel", () => {
      ],
    };
    const cdp = {
-      send: vi.fn(
-        async (
-          _t: number,
-          method: string,
-          params?: { backendNodeId?: number; objectId?: string },
-        ) => {
-          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 },
-            };
-          }
-          if (method === "DOM.getBoxModel")
-            return {
-              model: {
-                content:
-                  params?.backendNodeId === 13
-                    ? [10, 20, 310, 20, 310, 220, 10, 220]
-                    : [15, 26, 115, 26, 115, 106, 15, 106],
-              },
-            };
-          if (method === "DOM.resolveNode")
-            return { object: { objectId: String(params?.backendNodeId) } };
-          if (method === "Runtime.callFunctionOn")
-            return {
-              result: {
-                value:
-                  params?.objectId === "13"
-                    ? { width: 300, height: 200 }
-                    : { width: 100, height: 80 },
-              },
-            };
-          if (method === "Runtime.releaseObject") return {};
-          throw new Error(method);
-        },
-      ) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+      send: vi.fn(async (_t: number, method: string) => {
+        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 },
+          };
+        }
+        throw new Error(method);
+      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };

    const { iframeNodes } = await captureViewModel(cdp, 4);
@@ -1201,7 +1150,7 @@ describe("captureViewModel", () => {
    expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
  });

-  it("subtracts CSS scroll once without dividing snapshot bounds by a metrics ratio", async () => {
+  it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
    const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
    const i = (s: string) => S.indexOf(s);
    const snapshot = {
@@ -1243,7 +1192,7 @@ describe("captureViewModel", () => {
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };
    const { nodes } = await captureViewModel(cdp, 4);
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
+    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
  });

  it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {
@@ -1268,194 +1217,3 @@ describe("captureViewModel", () => {
    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[]) => ({
-    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 {
-    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,
-    );
-  });
-});
@@ -1,127 +0,0 @@
-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";
-
-function node(id: number, parent: number | null): DecodedNode {
-  return {
-    backendNodeId: id,
-    parentBackendNodeId: parent,
-    tag: "div",
-    attrs: {},
-    paintOrder: 0,
-    position: "static",
-    pointerEvents: "auto",
-  };
-}
-
-describe("document facts", () => {
-  it.each([
-    1_000, 10_000, 100_000,
-  ])("indexes deep and wide inputs of %i without copying ancestors", async (count) => {
-    for (const wide of [false, true]) {
-      let reads = 0;
-      const input = Array.from({ length: count }, (_, i) => {
-        const item = node(i, i ? (wide ? 0 : i - 1) : null);
-        if (i === 0) item.attrs[OVERLAY_HOST_MARKER_ATTR] = "";
-        Object.defineProperty(item, "parentBackendNodeId", {
-          get: () => {
-            reads++;
-            return i ? (wide ? 0 : i - 1) : null;
-          },
-        });
-        return item;
-      }).reverse(); // parent need not precede child
-      const index = await buildDocumentIndex(input);
-      expect(index.nodes.size).toBe(count);
-      expect(index.excludedBackendNodeIds.size).toBe(count);
-      expect(reads).toBeLessThanOrEqual(count * 8);
-      expect(index.nodes.get(count - 1)).toBe(input[0]);
-    }
-  });
-
-  it("handles cycles and orphans and propagates overlay through shadow roots", async () => {
-    const host = { ...node(1, null), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
-    const input = [
-      node(3, 2),
-      { ...node(2, 1), tag: "#document-fragment" },
-      host,
-      node(4, 99),
-      node(5, 6),
-      node(6, 5),
-      node(7, 6),
-    ];
-    const index = await buildDocumentIndex(input);
-    expect([...index.excludedBackendNodeIds].sort()).toEqual([1, 2, 3]);
-    expect(index.nodes.size).toBe(input.length);
-  });
-
-  it("does not propagate a descendant overlay backwards into a cycle", async () => {
-    const overlay = { ...node(3, 1), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
-    const index = await buildDocumentIndex([overlay, node(1, 2), node(2, 1)]);
-    expect([...index.excludedBackendNodeIds]).toEqual([3]);
-  });
-
-  it("decodes current observation bounds, styles and attributes without projecting coordinates", async () => {
-    const strings = ["div", "aria-hidden", "true", "inert", "", "visible", "0", "static", "auto"];
-    const styles = REQUESTED_STYLES.map((style) =>
-      style === "visibility" ? 5 : style === "opacity" ? 6 : style === "position" ? 7 : 8,
-    );
-    const { nodes } = await decodeDocument(
-      {
-        nodes: { backendNodeId: [1], parentIndex: [-1], nodeName: [0], attributes: [[1, 2, 3, 4]] },
-        layout: { nodeIndex: [0], bounds: [[10, 20, 120, 40]], styles: [styles] },
-      },
-      strings,
-    );
-    expect(nodes[0].attrs).toEqual({ "aria-hidden": "true", inert: "" });
-    expect(nodes[0].layout).toEqual({
-      boundsSpace: "snapshot-document-css",
-      bounds: [10, 20, 120, 40],
-      styles: {
-        position: "static",
-        "pointer-events": "auto",
-        cursor: "auto",
-        visibility: "visible",
-        opacity: "0",
-      },
-    });
-    expect(nodes[0]).not.toHaveProperty("rect");
-    expect(nodes[0]).not.toHaveProperty("excluded");
-  });
-
-  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;
-    for (const item of input)
-      Object.defineProperty(item, "attrs", {
-        get: () => {
-          reads++;
-          if (reads === 100) controller.abort();
-          return {};
-        },
-      });
-    await expect(buildDocumentIndex(input, controller.signal)).rejects.toMatchObject({
-      name: "AbortError",
-    });
-    expect(reads).toBeLessThanOrEqual(356);
-  });
-});
@@ -1,7 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
-import { enrichFormControlStates } from "../form-capture";
-import { decodeDocument } from "../snapshot";
+import { captureViewModel } from "../capture";

 interface Control {
  id: number;
@@ -78,32 +77,21 @@ function reply(entries: Array<[number, unknown]>) {
  };
 }

-async function fakeCdp(
-  groups: Control[][],
-  evaluate: (params: Record<string, unknown>) => unknown,
-) {
+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 {};
  });
-  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 })),
-    ),
-  );
+  return { send, cdp: { send: send as CdpRunner["send"] } };
 }

 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, nodes } = await fakeCdp(
+    const { cdp } = fakeCdp(
      [
        [
          { id: 10, value: "" },
@@ -118,21 +106,21 @@ describe("form state identity", () => {
          [11, state("alice@example.com")],
        ]),
    );
-    await enrichFormControlStates(cdp, 7, nodes);
-    expect(nodes[0].find((n) => n.backendNodeId === 10)).toMatchObject({
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 10)).toMatchObject({
      formValue: "",
      formState: "empty",
      formPlaceholder: "snapshot placeholder",
    });
-    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
      formValue: "alice@example.com",
    });
-    expect(nodes[0].find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
-    expect(nodes[0].some((n) => n.backendNodeId === 99)).toBe(false);
+    expect(captured.nodes.find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
+    expect(captured.nodes.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, nodes } = await fakeCdp(
+    const { cdp } = fakeCdp(
      [
        [],
        [{ id: 11, value: "inaccessible frame" }],
@@ -145,8 +133,8 @@ describe("form state identity", () => {
          [21, state("second frame")],
        ]),
    );
-    await enrichFormControlStates(cdp, 7, nodes);
-    const controls = nodes.slice(1).flat();
+    const captured = await captureViewModel(cdp, 7);
+    const controls = [...captured.iframeNodes.values()].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");
@@ -154,6 +142,7 @@ 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 {};
    });
@@ -162,9 +151,8 @@ describe("form state identity", () => {
    });
    const cdp = { send, sendToTarget } as unknown as CdpRunner;
    for (const sessionId of ["left-frame", "right-frame"]) {
-      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);
+      const captured = await captureViewModel(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7);
+      expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
      expect(sendToTarget).toHaveBeenCalledWith(
        { tabId: 7, sessionId },
        "Runtime.releaseObjectGroup",
@@ -180,7 +168,7 @@ describe("form state identity", () => {
    "malformed",
    "invalid-state",
  ])("preserves snapshot data when enrichment is %s", async (mode) => {
-    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "snapshot value" }]], () => {
+    const { cdp, send } = 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([
@@ -190,8 +178,8 @@ describe("form state identity", () => {
        result.result.deepSerializedValue.value[0].value[1].value = "not json";
      return result;
    });
-    expect(await enrichFormControlStates(cdp, 7, nodes)).toBe(mode !== "unsupported");
-    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
      formValue: "snapshot value",
      formPlaceholder: "snapshot placeholder",
    });
@@ -200,34 +188,18 @@ describe("form state identity", () => {

  it("releases the batch's remote objects when capture is cancelled", async () => {
    const controller = new AbortController();
-    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "old" }]], () => {
+    const { cdp, send } = fakeCdp([[{ id: 11, value: "old" }]], () => {
      controller.abort();
      return reply([[11, state("new")]]);
    });
-    await expect(enrichFormControlStates(cdp, 7, nodes, controller.signal)).rejects.toMatchObject({
+    await expect(captureViewModel(cdp, 7, { signal: 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, nodes } = await fakeCdp(
+    const { cdp } = fakeCdp(
      [
        [
          { id: 11, value: "snapshot value" },
@@ -244,20 +216,20 @@ describe("form state identity", () => {
        return result;
      },
    );
-    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");
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
+    expect(captured.nodes.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, nodes } = await fakeCdp([[{ id: 11, value: "secret", type }]], () =>
+    const { cdp } = fakeCdp([[{ id: 11, value: "secret", type }]], () =>
      reply([[11, { ...state("secret"), sensitive: true }]]),
    );
-    await enrichFormControlStates(cdp, 7, nodes);
-    const control = nodes[0].find((n) => n.backendNodeId === 11);
+    const captured = await captureViewModel(cdp, 7);
+    const control = captured.nodes.find((n) => n.backendNodeId === 11);
    expect(control?.formState).toBe("filled");
    expect(control?.formValue).toBeUndefined();
    expect(control?.formDefaultValue).toBeUndefined();
@@ -274,7 +246,7 @@ describe("form state identity", () => {
      defaultValue: "",
      placeholder: "",
    }));
-    const { cdp, send, nodes } = await fakeCdp([controls], (params) => {
+    const { cdp, send } = fakeCdp([controls], (params) => {
      const doc = {
        querySelectorAll: (selector: string) =>
          selector === "input,textarea,select" ? elements : [],
@@ -285,9 +257,9 @@ describe("form state identity", () => {
      expect(entries).toHaveLength(250);
      return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
    });
-    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");
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
+    expect(captured.nodes.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"),
@@ -1,5 +1,4 @@
 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";
@@ -31,7 +30,7 @@ function childSnapshot(frameId: string, backendNodeId: number) {
          parentIndex: [-1, 0],
          nodeName: [1, 2],
          backendNodeId: [backendNodeId - 1, backendNodeId],
-          attributes: [[], []] as number[][],
+          attributes: [[], []],
        },
        layout: {
          nodeIndex: [0, 1],
@@ -51,68 +50,6 @@ function childSnapshot(frameId: string, backendNodeId: number) {
 }

 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 { 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);
@@ -131,15 +68,9 @@ describe("captureFrameData", () => {
      }
      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;
+        return target.sessionId === "left-session"
+          ? childSnapshot("left", 101)
+          : childSnapshot("right", 201);
      }
      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
      throw new Error(`unexpected ${method}`);
@@ -181,10 +112,6 @@ describe("captureFrameData", () => {

    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,
@@ -29,7 +29,7 @@ function captured(frameNodes: Map<string, CapturedNode[]>): CapturedViewModel {
 }

 describe("buildFrameDocuments", () => {
-  it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", async () => {
+  it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", () => {
    const graph: CdpFrameGraph = {
      rootFrameId: "main",
      frames: [
@@ -54,7 +54,7 @@ describe("buildFrameDocuments", () => {
      },
    ];

-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
      graph,
      batches,
      captured(
@@ -72,7 +72,7 @@ describe("buildFrameDocuments", () => {
    expect(childNodes.find((node) => node.nodeId === "virtual")?.frameId).toBe("child");
  });

-  it("deduplicates overlapping same-target AX results using the strongest ownership", async () => {
+  it("deduplicates overlapping same-target AX results using the strongest ownership", () => {
    const graph: CdpFrameGraph = {
      rootFrameId: "main",
      frames: [
@@ -92,7 +92,7 @@ describe("buildFrameDocuments", () => {
      },
    ];

-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
      graph,
      batches,
      captured(
@@ -107,7 +107,7 @@ describe("buildFrameDocuments", () => {
    expect(documents.find((document) => document.frameId === "child")?.axNodes).toHaveLength(1);
  });

-  it("uses target-scoped backend ownership when OOPIF backend ids collide", async () => {
+  it("uses target-scoped backend ownership when OOPIF backend ids collide", () => {
    const graph: CdpFrameGraph = {
      rootFrameId: "main",
      frames: [
@@ -129,7 +129,7 @@ describe("buildFrameDocuments", () => {
      nodes: [{ nodeId: `${frame.frameId}-node`, backendDOMNodeId: 7 }],
    }));

-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
      graph,
      batches,
      captured(
@@ -149,7 +149,7 @@ describe("buildFrameDocuments", () => {
    );
  });

-  it("uses captured frame parent identity instead of guessing from backend ids", async () => {
+  it("uses captured frame parent identity instead of guessing from backend ids", () => {
    const frameNodes = new Map([
      ["main", [domNode("main", 1)]],
      ["left", [domNode("left", 7)]],
@@ -164,25 +164,11 @@ describe("buildFrameDocuments", () => {
      nodes: [],
    }));

-    const documents = await buildFrameDocuments(null, frames, capture);
+    const documents = buildFrameDocuments(null, frames, capture);

    expect(documents.find((document) => document.frameId === "child")).toMatchObject({
      parentFrameId: "left",
      ownerBackendNodeId: 7,
    });
  });
-  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) => ({
-      nodeId: String(i),
-      ...(i ? { parentId: String(i - 1) } : { frameId: "main" }),
-    })).reverse();
-    const documents = await buildFrameDocuments(
-      { rootFrameId: "main", frames: [frame] },
-      [{ frame, nodes }],
-      captured(new Map()),
-    );
-    expect(documents[0].axNodes).toHaveLength(10000);
-    expect(documents[0].axNodes[0].frameId).toBe("main");
-  });
 });
@@ -1,40 +0,0 @@
-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;
-    });
-  };
-}
@@ -1,37 +0,0 @@
-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;
-}
@@ -1,27 +1,56 @@
-// Coordinate DOMSnapshot acquisition, frame geometry and hover probes.
-// Snapshot decoding and form enrichment live in their own modules.
+// CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
+// → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
+// raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
+// shared string table); requested computed styles are decoded through
+// STYLE_COL so capture and visibility policy share one explicit contract.

-import type { Viewport } from "@browser-skill/vom";
-import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { Rect, Viewport } from "@browser-skill/vom";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
-import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
-import { type FrameProjectionIssue, type FrameProjectionState } from "../geometry/coordinate-types";
-import { cssViewport, GeometryContext, type LayoutMetrics } from "../geometry/frame-context";
+import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
+import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
-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";
+const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
+const STYLE_COL = Object.fromEntries(
+  REQUESTED_STYLES.map((name, index) => [name, index]),
+) as Record<(typeof REQUESTED_STYLES)[number], number>;
+
+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 type CapturedIframeNodes = Map<number, CapturedNode[]>;

@@ -38,26 +67,266 @@ export interface CapturedViewModel {
  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;
+}
+
+function captureAbortError(): Error {
+  const error = new Error("observation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: string }).name === "AbortError"
+  );
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw captureAbortError();
+}
+
+/** Sparse array format Chrome uses for infrequently-set per-node fields. */
+interface SparseArray {
+  index: number[];
+  value: number[];
+}
+
+interface RareBooleanData {
+  index: number[];
+}
+
+interface SnapshotDocument {
+  frameId?: string | number;
+  scrollOffsetX?: number;
+  scrollOffsetY?: number;
+  nodes?: {
+    parentIndex?: number[];
+    nodeName?: number[];
+    backendNodeId?: number[];
+    attributes?: number[][];
+    /**
+     * Per-node text value (index into strings), set for `#text` / CDATA nodes.
+     * Element nodes carry -1. Same length as `backendNodeId`.
+     */
+    nodeValue?: number[];
+    /** Maps node array index → index into `documents[]` for frame content. */
+    contentDocumentIndex?: SparseArray;
+    inputValue?: SparseArray;
+    textValue?: SparseArray;
+    inputChecked?: RareBooleanData;
+    optionSelected?: RareBooleanData;
+  };
+  layout?: {
+    nodeIndex?: number[];
+    styles?: number[][];
+    bounds?: number[][];
+    paintOrders?: number[];
+  };
+}
+
+function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
+  if (typeof document.frameId === "string") return document.frameId || undefined;
+  if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
+  return undefined;
+}
+
+interface SnapshotReply {
+  strings?: string[];
+  documents?: SnapshotDocument[];
+}
+
+interface LayoutMetricsReply {
+  cssLayoutViewport?: {
+    clientWidth?: number;
+    clientHeight?: number;
+    pageX?: number;
+    pageY?: number;
+  };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
+}
+
+function isFormControlTag(tag: string): boolean {
+  return tag === "input" || tag === "textarea" || tag === "select";
+}
+
+function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
+  return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
+}
+
+function snapshotFormState(
+  value: string | undefined,
+  defaultValue: string,
+  hasDefaultValue: boolean,
+  sensitive: boolean,
+): CapturedNode["formState"] {
+  if (sensitive) {
+    if (value === undefined && !hasDefaultValue) return undefined;
+    return (value ?? defaultValue) === "" ? "empty" : "filled";
+  }
+  if (value === undefined) return undefined;
+  if (value === "") return "empty";
+  return value === defaultValue ? "default" : "filled";
+}
+
+const MAX_FORM_ENRICH_CONTROLS = 250;
+
+interface CapturedFormState {
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  state?: "empty" | "filled" | "default";
+  sensitive?: boolean;
+}
+
+interface DeepSerializedValue {
+  type: string;
+  value?: unknown;
+}
+
+function formStateBatchExpression(maxControls: number): string {
+  return `(() => {
+    const maxControls = ${JSON.stringify(maxControls)};
+    let remaining = maxControls;
+    const controlSelector = "input,textarea,select";
+    const controlState = (el) => {
+      const tag = el.tagName.toLowerCase();
+      const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
+      const sensitive = type === "password" || type === "credit-card";
+      const rawValue = typeof el.value === "string" ? el.value : "";
+      const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
+      const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
+      const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
+      return {
+        state,
+        sensitive,
+        placeholder,
+        ...(sensitive ? {} : { value: rawValue, defaultValue }),
+      };
+    };
+    const controls = [];
+    const collect = (doc) => {
+      for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
+        if (remaining <= 0) break;
+        // Deep serialization supplies the node's backend id. Keep the
+        // state as JSON so decoding needs no general-purpose V8 deserializer.
+        controls.push([el, JSON.stringify(controlState(el))]);
+        remaining -= 1;
+      }
+      for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
+        if (remaining <= 0) break;
+        let childDoc = null;
+        try { childDoc = frame.contentDocument; } catch { childDoc = null; }
+        if (childDoc) collect(childDoc);
+      }
+    };
+    collect(document);
+    return controls;
+  })()`;
+}
+
+function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
+  const states = new Map<number, CapturedFormState>();
+  const serialized = result.result?.deepSerializedValue;
+  if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
+  for (const entry of serialized.value as DeepSerializedValue[]) {
+    if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
+    const [element, json] = entry.value as DeepSerializedValue[];
+    if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
+      continue;
+    }
+    const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+    if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
+    try {
+      const state = JSON.parse(json.value) as CapturedFormState | null;
+      if (
+        !state ||
+        !["empty", "filled", "default"].includes(state.state ?? "") ||
+        typeof state.sensitive !== "boolean" ||
+        typeof state.placeholder !== "string" ||
+        (!state.sensitive &&
+          (typeof state.value !== "string" || typeof state.defaultValue !== "string"))
+      ) {
+        continue;
+      }
+      states.set(backendNodeId, state);
+    } catch {
+      // A malformed entry must not overwrite the snapshot's own state.
+    }
+  }
+  return states;
+}
+
+function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
+  for (const node of nodes) {
+    if (!isFormControlTag(node.tag)) continue;
+    const state = states.get(node.backendNodeId);
+    if (!state) continue;
+    node.formState = state.state;
+    node.formPlaceholder = state.placeholder ?? "";
+    if (state.sensitive || isSensitiveFormControl(node)) {
+      delete node.formValue;
+      delete node.formDefaultValue;
+      delete node.attrs.value;
+    } else {
+      node.formDefaultValue = state.defaultValue ?? "";
+      if (state.value !== undefined) node.formValue = state.value;
+    }
+  }
+}
+
+async function enrichFormControlStates(
+  cdp: CdpRunner,
+  tabId: number,
+  frameNodeGroups: CapturedNode[][],
+  signal?: AbortSignal,
+): Promise<void> {
+  const hasControls = frameNodeGroups.some((nodes) =>
+    nodes.some((node) => isFormControlTag(node.tag)),
+  );
+  if (!hasControls) return;
+  const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
+  try {
+    throwIfAborted(signal);
+    const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+      expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
+      objectGroup,
+      serializationOptions: {
+        serialization: "deep",
+        maxDepth: 3,
+        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+      },
+    });
+    throwIfAborted(signal);
+    // Backend ids are scoped to this capture's CDP target. OOPIF targets
+    // use their own captureViewModel call and never share this lookup.
+    const states = formStatesByBackendId(result);
+    for (const nodes of frameNodeGroups) {
+      applyFormStates(nodes, states);
+    }
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    // Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
+  } finally {
+    await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
+  }
 }

 interface RuntimeEvaluateReply {
  result?: {
    value?: unknown;
+    deepSerializedValue?: DeepSerializedValue;
  };
 }

@@ -76,6 +345,44 @@ interface CdpDomNode {
  shadowRoots?: CdpDomNode[];
 }

+interface ParseDocumentResult {
+  nodes: CapturedNode[];
+  excludedBackendNodeIds: Set<number>;
+}
+
+interface FrameContext {
+  frameId?: string;
+  ownerFrameBackendNodeId: number | null;
+  projection: GeometryProjection | null;
+  scrollX: number;
+  scrollY: number;
+}
+
+function str(strings: string[], idx: number | undefined): string {
+  if (idx === undefined || idx < 0) return "";
+  return strings[idx] ?? "";
+}
+
+function devicePixelRatio(metrics: LayoutMetricsReply): number {
+  const layoutW = metrics.layoutViewport?.clientWidth ?? 0;
+  const cssW = metrics.cssLayoutViewport?.clientWidth ?? 0;
+  if (!layoutW || !cssW) return 1;
+  const dpr = layoutW / cssW;
+  if (!Number.isFinite(dpr) || dpr <= 0) return 1;
+  return dpr >= 1 ? dpr : 1;
+}
+
+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++) {
+    const nodeIndex = sparse.index[i];
+    const docIndex = sparse.value[i];
+    if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
+  }
+  return out;
+}
+
 function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<number>): void {
  if (!node) return;
  if (typeof node.backendNodeId === "number") {
@@ -485,108 +792,230 @@ export async function collectOverlayExcludedBackendIds(
  return excluded;
 }

+/**
+ * Parse one DOMSnapshot document into CapturedNode[].
+ *
+ * @param doc   - the raw DOMSnapshot document object
+ * @param strings - the shared string table for the whole snapshot
+ * @param dpr   - device-pixel-ratio from Page.getLayoutMetrics
+ * @param context - frame coordinate context; output rects are top viewport-relative
+ */
+function parseDocumentNodes(
+  doc: SnapshotDocument,
+  strings: string[],
+  dpr: number,
+  context: FrameContext,
+): ParseDocumentResult {
+  const dn = doc.nodes;
+  const dl = doc.layout;
+  if (!dn?.backendNodeId) {
+    return { nodes: [], excludedBackendNodeIds: new Set() };
+  }
+
+  const count = dn.backendNodeId.length;
+  const layoutByNode = new Map<number, number>();
+  (dl?.nodeIndex ?? []).forEach((nodeIdx, layoutIdx) => layoutByNode.set(nodeIdx, layoutIdx));
+
+  // The agent's own overlay (WXT shadow host, marked with OVERLAY_HOST_MARKER_ATTR)
+  // is injected into the page and its open shadow root
+  // is inlined by DOMSnapshot as descendants of the host. Its fixed
+  // full-viewport click-blocker would otherwise dominate occlusion detection
+  // and hide the real page, so mark the host + its whole subtree excluded.
+  // parentIndex always references an earlier node, so one forward pass suffices.
+  const excluded = new Array<boolean>(count).fill(false);
+  const excludedBackendNodeIds = new Set<number>();
+  for (let n = 0; n < count; n++) {
+    const parentIdx = dn.parentIndex?.[n] ?? -1;
+    const inherited = parentIdx >= 0 && excluded[parentIdx];
+    let isOverlayHost = inherited;
+    if (!isOverlayHost) {
+      const pairs = dn.attributes?.[n] ?? [];
+      const attrNames: string[] = [];
+      for (let a = 0; a + 1 < pairs.length; a += 2) {
+        attrNames.push(str(strings, pairs[a]));
+      }
+      isOverlayHost = isOverlayHostNode(str(strings, dn.nodeName?.[n]), attrNames);
+    }
+    if (!isOverlayHost) continue;
+    excluded[n] = true;
+    const backendNodeId = dn.backendNodeId[n];
+    if (backendNodeId !== undefined) {
+      excludedBackendNodeIds.add(backendNodeId);
+    }
+  }
+
+  const posCol = STYLE_COL.position;
+  const peCol = STYLE_COL["pointer-events"];
+  const cursorCol = STYLE_COL.cursor;
+  const visibilityCol = STYLE_COL.visibility;
+  const opacityCol = STYLE_COL.opacity;
+  const inputValues = sparseIndexMap(dn.inputValue);
+  const textValues = sparseIndexMap(dn.textValue);
+  const checkedInputs = new Set(dn.inputChecked?.index ?? []);
+  const selectedOptions = new Set(dn.optionSelected?.index ?? []);
+
+  // Collect visible text from #text child nodes so element CapturedNodes
+  // carry a textContent value usable as a button/link label fallback.
+  // nodeValue is a parallel array: string index for text nodes, -1 otherwise.
+  const nodeTextContent = new Map<number, string>();
+  if (dn.nodeValue) {
+    for (let n = 0; n < count; n++) {
+      const nvIdx = dn.nodeValue[n] ?? -1;
+      if (nvIdx < 0) continue;
+      const text = str(strings, nvIdx).trim();
+      if (!text) continue;
+      const parentIdx = dn.parentIndex?.[n] ?? -1;
+      if (parentIdx >= 0) {
+        const existing = nodeTextContent.get(parentIdx);
+        nodeTextContent.set(parentIdx, existing ? `${existing} ${text}` : text);
+      }
+    }
+  }
+
+  // Build CapturedNodes.
+  const nodes: CapturedNode[] = [];
+  for (let n = 0; n < count; n++) {
+    if (excluded[n]) continue;
+    const backendNodeId = dn.backendNodeId[n];
+    const parentIdx = dn.parentIndex?.[n] ?? -1;
+    const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
+    const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
+
+    const attrs: Record<string, string> = {};
+    const pairs = dn.attributes?.[n] ?? [];
+    for (let a = 0; a + 1 < pairs.length; a += 2) {
+      attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
+    }
+
+    let rect: Rect | null = null;
+    let localRect: Rect | null = null;
+    let paintOrder = 0;
+    let position = "static";
+    let pointerEvents = "auto";
+    let cursor = "auto";
+    let rendered = false;
+    const li = layoutByNode.get(n);
+    if (li !== undefined) {
+      const b = dl?.bounds?.[li];
+      if (b && b.length >= 4 && b[2] > 0 && b[3] > 0) {
+        localRect = {
+          x: b[0] / dpr - context.scrollX,
+          y: b[1] / dpr - context.scrollY,
+          w: b[2] / dpr,
+          h: b[3] / dpr,
+        };
+        const bounds = context.projection
+          ? projectRectToViewport(localRect, context.projection)
+          : null;
+        rect = bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+      }
+      paintOrder = dl?.paintOrders?.[li] ?? 0;
+      const styleRow = dl?.styles?.[li] ?? [];
+      position = str(strings, styleRow[posCol]) || "static";
+      pointerEvents = str(strings, styleRow[peCol]) || "auto";
+      cursor = str(strings, styleRow[cursorCol]) || "auto";
+      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
+      const opacity = str(strings, styleRow[opacityCol]) || "1";
+      rendered =
+        localRect !== null &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0;
+    }
+
+    // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
+    // geometry and are never queried by callers.
+    if (tag.startsWith("#")) continue;
+
+    const textContent = nodeTextContent.get(n);
+
+    const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
+    const rawFormValue =
+      rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
+    const sensitive = isSensitiveFormControl({ tag, attrs });
+    const formDefaultValue = attrs.value ?? "";
+    const formValue = sensitive ? undefined : rawFormValue;
+    const formState = snapshotFormState(
+      rawFormValue,
+      formDefaultValue,
+      Object.prototype.hasOwnProperty.call(attrs, "value"),
+      sensitive,
+    );
+    if (sensitive) delete attrs.value;
+
+    nodes.push({
+      backendNodeId,
+      parentBackendNodeId,
+      ...(context.frameId ? { frameId: context.frameId } : {}),
+      ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
+      tag,
+      attrs,
+      rect,
+      localRect,
+      paintOrder,
+      position,
+      pointerEvents,
+      cursor,
+      rendered,
+      textContent,
+      ...(formValue !== undefined ? { formValue } : {}),
+      ...(tag === "input" || tag === "textarea"
+        ? {
+            formPlaceholder: attrs.placeholder ?? "",
+            ...(!sensitive ? { formDefaultValue } : {}),
+            ...(formState ? { formState } : {}),
+          }
+        : {}),
+      ...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
+      ...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
+    });
+  }
+  return { nodes, excludedBackendNodeIds };
+}
+
 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(
+function parseChildFrameDocuments(
  documents: SnapshotDocument[],
  strings: string[],
+  dpr: number,
  parentDocIndex: number,
+  parentNodes: CapturedNode[],
  parentContext: FrameContext,
-  geometry: GeometryContext,
-  signal?: AbortSignal,
  visited = new Set<number>(),
-): Promise<ParseFrameDocumentsResult> {
-  const frameGeometryIssues: FrameProjectionIssue[] = [];
+): ParseFrameDocumentsResult {
  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,
-    };
+    return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
  }

  const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
+  const parentNodeByBackendId = new Map(parentNodes.map((node) => [node.backendNodeId, node]));

-  const children = [...cdi].flatMap(([nodeArrayIdx, childDocIndex]) => {
+  for (const [nodeArrayIdx, childDocIndex] of cdi) {
+    if (visited.has(childDocIndex)) continue;
    const childDoc = documents[childDocIndex];
+    if (!childDoc) continue;
    const iframeBackendId = parentBackendIds[nodeArrayIdx];
-    if (visited.has(childDocIndex) || !childDoc || iframeBackendId === undefined) return [];
-    const source = { target: parentContext.target, frameId: snapshotFrameId(childDoc, strings) };
-    const parent = parentContext.projection;
-    const projection: FrameProjectionState =
-      parent.status === "available"
-        ? { status: "unavailable", source, ownerBackendNodeId: iframeBackendId }
-        : { status: "blocked", source, cause: parent.status === "blocked" ? parent.cause : parent };
-    return [
-      {
-        childDocIndex,
-        childDoc,
-        iframeBackendId,
-        source,
-        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++];
-          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);
+    if (iframeBackendId === undefined) continue;
+    const iframeNode = parentNodeByBackendId.get(iframeBackendId);
+    const projection =
+      parentContext.projection && iframeNode?.localRect
+        ? childFrameProjection(parentContext.projection, iframeNode.localRect)
+        : null;

-  // Completion order must not change document traversal or result insertion order.
-  for (const { childDocIndex, childDoc, iframeBackendId, source, projection } of children) {
-    throwIfAborted(signal);
-    if (projection.status !== "available") frameGeometryIssues.push(projection);
    const childContext: FrameContext = {
-      frameId: source.frameId,
-      target: source.target,
+      frameId: snapshotFrameId(childDoc, strings),
      ownerFrameBackendNodeId: iframeBackendId,
      projection,
      scrollX: childDoc.scrollOffsetX ?? 0,
@@ -594,25 +1023,23 @@ async function parseChildFrameDocuments(
    };
    const nextVisited = new Set(visited);
    nextVisited.add(childDocIndex);
-    const parsed = await normalizeDocument(childDoc, strings, childContext, signal);
+    const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
    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);
+    for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);

-    const nested = await parseChildFrameDocuments(
+    const nested = parseChildFrameDocuments(
      documents,
      strings,
+      dpr,
      childDocIndex,
+      parsed.nodes,
      childContext,
-      geometry,
-      signal,
      nextVisited,
    );
-    frameGeometryIssues.push(...nested.frameGeometryIssues);
    for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
      iframeNodes.set(nestedFrameId, nestedNodes);
    }
@@ -622,19 +1049,10 @@ async function parseChildFrameDocuments(
    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,
-  };
+  return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
 }

 export async function captureViewModel(
@@ -643,20 +1061,22 @@ export async function captureViewModel(
  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 = {};
+  let metrics: LayoutMetricsReply = {};
  try {
-    metrics = await geometry.layoutMetrics(target);
+    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
  } catch (error) {
    if (isAbortError(error)) throw error;
    console.debug("[bsk capture] layout metrics unavailable", error);
  }
  throwIfAborted(options.signal);
-  const measured = cssViewport(metrics);
-  const viewport: Viewport = { width: measured.width, height: measured.height };
-  const scrollX = measured.scrollX;
-  const scrollY = measured.scrollY;
+  const dpr = devicePixelRatio(metrics);
+  const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+  const viewport: Viewport = {
+    width: vpSrc.clientWidth ?? 0,
+    height: vpSrc.clientHeight ?? 0,
+  };
+  const scrollX = vpSrc.pageX ?? 0;
+  const scrollY = vpSrc.pageY ?? 0;

  await cdp.send(tabId, "DOMSnapshot.enable", {});
  throwIfAborted(options.signal);
@@ -682,43 +1102,20 @@ export async function captureViewModel(
  const topContext: FrameContext = {
    frameId: snapshotFrameId(doc0, strings),
    ownerFrameBackendNodeId: null,
-    target,
    projection: {
-      status: "available",
-      projection: {
-        source: { target, frameId: snapshotFrameId(doc0, strings) },
-        geometry: { sourceClips: [], edges: [], topViewport: viewport },
-      },
+      sourceClips: [],
+      edges: [],
+      topViewport: viewport,
    },
    scrollX,
    scrollY,
  };
-  const mainParsed = await normalizeDocument(doc0, strings, topContext, options.signal);
+  const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
  const nodes = mainParsed.nodes;
-  const excludedBackendNodeIds = new Set(mainParsed.index.excludedBackendNodeIds);
+  const excludedBackendNodeIds = new Set(mainParsed.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 frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, nodes, topContext);
  const iframeNodes = frameParsed.iframeNodes;
-  if (topContext.frameId)
-    frameParsed.frameExcludedBackendNodeIds.set(
-      topContext.frameId,
-      mainParsed.index.excludedBackendNodeIds,
-    );
  for (const id of frameParsed.excludedBackendNodeIds) {
    excludedBackendNodeIds.add(id);
  }
@@ -743,9 +1140,7 @@ export async function captureViewModel(
    viewport,
    iframeNodes,
    frameNodes,
-    frameGeometryIssues: frameParsed.frameGeometryIssues,
    frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
-    frameExcludedBackendNodeIds: frameParsed.frameExcludedBackendNodeIds,
    frameParentIds: frameParsed.frameParentIds,
    ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
    excludedBackendNodeIds,
@@ -1,94 +0,0 @@
-import { isOverlayHostNode } from "@/lib/overlay-bridge";
-import { createCaptureCheckpoint } from "./capture-abort";
-import type { CapturedNode } from "./capture-types";
-
-/** Bounds retain their snapshot document CSS units until normalization. */
-export interface SnapshotLayout {
-  readonly boundsSpace: "snapshot-document-css";
-  bounds?: number[];
-  styles: Readonly<Record<string, string>>;
-}
-
-export interface DecodedNode extends Omit<CapturedNode, "rect" | "localRect" | "rendered"> {
-  nodeType?: number;
-  layout?: SnapshotLayout;
-}
-
-export interface NodeFacts extends CapturedNode {
-  nodeType?: number;
-  layout?: SnapshotLayout;
-}
-
-export interface DocumentIndex<T extends DecodedNode = NodeFacts> {
-  readonly nodes: ReadonlyMap<number, T>;
-  readonly excludedBackendNodeIds: ReadonlySet<number>;
-}
-
-export interface DecodedDocument {
-  nodes: DecodedNode[];
-}
-
-/** 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) {
-      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) {
-      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) {
-        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
-          .slice(path.findIndex((item) => item.backendNodeId === current!.backendNodeId))
-          .some((item) => isOverlayHostNode(item.tag, Object.keys(item.attrs)));
-        break;
-      }
-      visiting.add(current.backendNodeId);
-      path.push(current);
-      if (current.parentBackendNodeId === null) {
-        current = undefined;
-        break;
-      }
-      current = nodes.get(current.parentBackendNodeId);
-    }
-    if (current && overlayByNode.has(current.backendNodeId))
-      overlay = overlayByNode.get(current.backendNodeId)!;
-    for (let i = path.length - 1; i >= 0; i--) {
-      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);
-      if (overlay) excludedBackendNodeIds.add(item.backendNodeId);
-    }
-  }
-  return { nodes, excludedBackendNodeIds };
-}
@@ -1,155 +0,0 @@
-import type { CdpRunner } from "../shared";
-import { isAbortError, throwIfAborted } from "./capture-abort";
-import type { CapturedNode } from "./capture-types";
-
-interface RuntimeEvaluateReply {
-  result?: { deepSerializedValue?: DeepSerializedValue };
-}
-const MAX_FORM_ENRICH_CONTROLS = 250;
-
-interface CapturedFormState {
-  value?: string;
-  defaultValue?: string;
-  placeholder?: string;
-  state?: "empty" | "filled" | "default";
-  sensitive?: boolean;
-}
-
-interface DeepSerializedValue {
-  type: string;
-  value?: unknown;
-}
-
-function formStateBatchExpression(maxControls: number): string {
-  return `(() => {
-    const maxControls = ${JSON.stringify(maxControls)};
-    let remaining = maxControls;
-    const controlSelector = "input,textarea,select";
-    const controlState = (el) => {
-      const tag = el.tagName.toLowerCase();
-      const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
-      const sensitive = type === "password" || type === "credit-card";
-      const rawValue = typeof el.value === "string" ? el.value : "";
-      const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
-      const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
-      const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
-      return {
-        state,
-        sensitive,
-        placeholder,
-        ...(sensitive ? {} : { value: rawValue, defaultValue }),
-      };
-    };
-    const controls = [];
-    const collect = (doc) => {
-      for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
-        if (remaining <= 0) break;
-        // Deep serialization supplies the node's backend id. Keep the
-        // state as JSON so decoding needs no general-purpose V8 deserializer.
-        controls.push([el, JSON.stringify(controlState(el))]);
-        remaining -= 1;
-      }
-      for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
-        if (remaining <= 0) break;
-        let childDoc = null;
-        try { childDoc = frame.contentDocument; } catch { childDoc = null; }
-        if (childDoc) collect(childDoc);
-      }
-    };
-    collect(document);
-    return controls;
-  })()`;
-}
-
-function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
-  const states = new Map<number, CapturedFormState>();
-  const serialized = result.result?.deepSerializedValue;
-  if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
-  for (const entry of serialized.value as DeepSerializedValue[]) {
-    if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
-    const [element, json] = entry.value as DeepSerializedValue[];
-    if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
-      continue;
-    }
-    const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
-    if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
-    try {
-      const state = JSON.parse(json.value) as CapturedFormState | null;
-      if (
-        !state ||
-        !["empty", "filled", "default"].includes(state.state ?? "") ||
-        typeof state.sensitive !== "boolean" ||
-        typeof state.placeholder !== "string" ||
-        (!state.sensitive &&
-          (typeof state.value !== "string" || typeof state.defaultValue !== "string"))
-      ) {
-        continue;
-      }
-      states.set(backendNodeId, state);
-    } catch {
-      // A malformed entry must not overwrite the snapshot's own state.
-    }
-  }
-  return states;
-}
-
-function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
-  for (const node of nodes) {
-    if (!["input", "textarea", "select"].includes(node.tag)) continue;
-    const state = states.get(node.backendNodeId);
-    if (!state) continue;
-    node.formState = state.state;
-    node.formPlaceholder = state.placeholder ?? "";
-    if (
-      state.sensitive ||
-      (node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password")
-    ) {
-      delete node.formValue;
-      delete node.formDefaultValue;
-      delete node.attrs.value;
-    } else {
-      node.formDefaultValue = state.defaultValue ?? "";
-      if (state.value !== undefined) node.formValue = state.value;
-    }
-  }
-}
-
-export async function enrichFormControlStates(
-  cdp: CdpRunner,
-  tabId: number,
-  frameNodeGroups: CapturedNode[][],
-  signal?: AbortSignal,
-): Promise<boolean> {
-  const hasControls = frameNodeGroups.some((nodes) =>
-    nodes.some((node) => ["input", "textarea", "select"].includes(node.tag)),
-  );
-  if (!hasControls) return true;
-  const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
-  try {
-    throwIfAborted(signal);
-    const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-      expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
-      objectGroup,
-      serializationOptions: {
-        serialization: "deep",
-        maxDepth: 3,
-        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
-      },
-    });
-    throwIfAborted(signal);
-    // Backend ids are scoped to this capture's CDP target. OOPIF targets
-    // have separate enrichment calls and never share this lookup.
-    const states = formStatesByBackendId(result);
-    for (const nodes of frameNodeGroups) {
-      applyFormStates(nodes, states);
-    }
-    return true;
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    // Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
-    return false;
-  } finally {
-    await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
-    throwIfAborted(signal);
-  }
-}
@@ -1,6 +1,6 @@
 import type { CdpFrame, CdpFrameGraph } from "@/browser-driver/frame-graph";
+import { resolveFrameProjection } from "../frame-geometry";
 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 {
@@ -21,6 +21,16 @@ function isAbortError(err: unknown): boolean {
  return err instanceof Error && err.name === "AbortError";
 }

+async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
+  if (!cdp.getFrameGraph) return null;
+  try {
+    return await cdp.getFrameGraph(tabId);
+  } catch (err) {
+    console.debug("[bsk observation] frame graph capture failed", err);
+    return null;
+  }
+}
+
 function transformFrameNodes(
  nodes: CapturedNode[],
  projection: GeometryProjection | null,
@@ -41,7 +51,6 @@ async function captureMissingFrameDocuments(
  tabId: number,
  graph: CdpFrameGraph,
  captured: CapturedViewModel,
-  geometry: GeometryContext,
  signal?: AbortSignal,
 ): Promise<void> {
  if (!captured.frameNodes) captured.frameNodes = new Map();
@@ -53,20 +62,10 @@ async function captureMissingFrameDocuments(
    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);
+        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
      } catch (err) {
        if (isAbortError(err)) throw err;
        console.debug("[bsk observation] child frame geometry projection failed", {
@@ -172,12 +171,11 @@ export async function captureFrameData<T extends FrameAxNode>(
  tabId: number,
  captured: CapturedViewModel,
  signal?: AbortSignal,
-  geometry = new GeometryContext(cdp, tabId, undefined, signal),
 ): Promise<CapturedFrameDocument<T>[]> {
-  const graph = await geometry.graph();
+  const graph = await discoverFrameGraph(cdp, tabId);
  const frames = graph?.frames ?? [];
-  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, geometry, signal);
+  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, signal);
  throwIfAborted(signal);
  const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
-  return buildFrameDocuments(graph, batches, captured, signal);
+  return buildFrameDocuments(graph, batches, captured);
 }
@@ -4,8 +4,7 @@ import {
  type CdpTarget,
  cdpTargetKey,
 } from "@/browser-driver/frame-graph";
-import { createCaptureCheckpoint } from "./capture-abort";
-import type { CapturedNode } from "./capture-types";
+import type { CapturedNode, CapturedViewModel } from "./capture";

 export interface FrameOwnedAxNode {
  nodeId: string;
@@ -24,17 +23,6 @@ export interface FrameDocument<T extends FrameOwnedAxNode> extends CdpFrame {
  contextScopeId: string;
  axNodes: T[];
  domNodes: CapturedNode[];
-  excludedBackendNodeIds?: ReadonlySet<number>;
-}
-
-/** Explicit snapshot document data used to join DOM and AX ownership. */
-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 {
@@ -59,7 +47,7 @@ function targetBackendKey(target: CdpTarget, backendNodeId: number): string {
 function frameList<T extends FrameOwnedAxNode>(
  graph: CdpFrameGraph | null,
  batches: FrameAxBatch<T>[],
-  captured: FrameDomInput,
+  captured: CapturedViewModel,
 ): CdpFrame[] {
  const frames = new Map<string, CdpFrame>();
  for (const frame of graph?.frames ?? []) frames.set(frame.frameId, frame);
@@ -82,14 +70,11 @@ function frameList<T extends FrameOwnedAxNode>(
  });
 }

-export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
+export function buildFrameDocuments<T extends FrameOwnedAxNode>(
  graph: CdpFrameGraph | null,
  batches: FrameAxBatch<T>[],
-  captured: FrameDomInput,
-  signal?: AbortSignal,
-): Promise<FrameDocument<T>[]> {
-  const checkpoint = createCaptureCheckpoint(signal);
-  let work = 0;
+  captured: CapturedViewModel,
+): FrameDocument<T>[] {
  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;
@@ -98,68 +83,54 @@ 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) {
-        const pending = checkpoint();
-        if (pending) await pending;
-      }
      backendOwner.set(targetBackendKey(frame.target, node.backendNodeId), frame.frameId);
    }
  }

  const candidates = new Map<string, OwnedCandidate<T>>();
  for (const batch of batches) {
-    const nodeById = new Map<string, T>();
-    for (const node of batch.nodes) {
-      if (work++ % 256 === 0) {
-        const pending = checkpoint();
-        if (pending) await pending;
-      }
-      nodeById.set(node.nodeId, node);
-    }
+    const nodeById = new Map(batch.nodes.map((node) => [node.nodeId, node]));
    const ownershipByNodeId = new Map<string, 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) {
-          const pending = checkpoint();
-          if (pending) await pending;
-        }
-        const cached = ownershipByNodeId.get(current.nodeId);
-        if (cached) {
-          ownership = cached;
-          break;
-        }
-        if (visiting.has(current.nodeId)) break;
-        visiting.add(current.nodeId);
-        if (current.frameId && frameById.has(current.frameId)) {
-          ownership = { frameId: current.frameId, strength: 4 };
-          ownershipByNodeId.set(current.nodeId, ownership);
-          break;
-        }
-        const frameId =
-          typeof current.backendDOMNodeId === "number"
-            ? backendOwner.get(targetBackendKey(batch.frame.target, current.backendDOMNodeId))
-            : undefined;
+    const resolving = new Set<string>();
+    const resolveOwnership = (node: T): Ownership => {
+      const cached = ownershipByNodeId.get(node.nodeId);
+      if (cached) return cached;
+      if (node.frameId && frameById.has(node.frameId)) {
+        const ownership = { frameId: node.frameId, strength: 4 };
+        ownershipByNodeId.set(node.nodeId, ownership);
+        return ownership;
+      }
+      if (typeof node.backendDOMNodeId === "number") {
+        const frameId = backendOwner.get(
+          targetBackendKey(batch.frame.target, node.backendDOMNodeId),
+        );
        if (frameId) {
-          ownership = { frameId, strength: 3 };
-          ownershipByNodeId.set(current.nodeId, ownership);
-          break;
+          const ownership = { frameId, strength: 3 };
+          ownershipByNodeId.set(node.nodeId, ownership);
+          return ownership;
        }
-        path.push(current);
-        current = current.parentId ? nodeById.get(current.parentId) : undefined;
      }
-      for (let i = path.length - 1; i >= 0; i--) {
-        if (work++ % 256 === 0) {
-          const pending = checkpoint();
-          if (pending) await pending;
+      if (node.parentId && !resolving.has(node.nodeId)) {
+        const parent = nodeById.get(node.parentId);
+        if (parent) {
+          resolving.add(node.nodeId);
+          const inherited = resolveOwnership(parent);
+          resolving.delete(node.nodeId);
+          const ownership = {
+            frameId: inherited.frameId,
+            strength: Math.min(2, inherited.strength),
+          };
+          ownershipByNodeId.set(node.nodeId, ownership);
+          return ownership;
        }
-        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);
+      const ownership = { frameId: batch.frame.frameId, strength: 1 };
+      ownershipByNodeId.set(node.nodeId, ownership);
+      return ownership;
+    };
+
+    for (const node of batch.nodes) {
+      const ownership = resolveOwnership(node);
      const key = targetNodeKey(batch.frame.target, node.nodeId);
      const existing = candidates.get(key);
      if (!existing || ownership.strength > existing.ownership.strength) {
@@ -173,10 +144,6 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
  );
  const axNodesByFrame = new Map<string, T[]>();
  for (const candidate of candidates.values()) {
-    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))
@@ -202,6 +169,5 @@ 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),
  }));
 }
@@ -1,73 +0,0 @@
-import type { CdpTarget } from "@/browser-driver/frame-graph";
-import {
-  type FrameProjectionState,
-  projectSnapshotRect,
-  snapshotViewportRect,
-} from "../geometry/coordinate-types";
-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;
-  scrollX: number;
-  scrollY: number;
-}
-
-export interface NormalizedDocument {
-  nodes: NodeFacts[];
-  index: DocumentIndex;
-}
-
-/** 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,
-): 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;
-    }
-    const node = decoded.nodes[i];
-    const input = snapshotViewportRect(
-      node.layout?.bounds ?? [],
-      { target: context.target, frameId: context.frameId },
-      { x: context.scrollX, y: context.scrollY },
-    );
-    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:
-        !!local &&
-        visibility !== "hidden" &&
-        visibility !== "collapse" &&
-        (Number.parseFloat(opacity) || 0) > 0,
-    });
-  }
-  const index = await buildDocumentIndex(nodes, signal);
-  return {
-    nodes: nodes.filter(
-      (node) => !node.tag.startsWith("#") && !index.excludedBackendNodeIds.has(node.backendNodeId),
-    ),
-    index,
-  };
-}
@@ -2,10 +2,7 @@ import type { Rect, RenderedRef, VomResult } from "@browser-skill/vom";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { readRecordingDocumentIdentity } from "@/shared/recording-document-identity";
 import type { CapturedSurfaceProbe } from "./capture";
-import type {
-  FrameDocument as CapturedFrameDocument,
-  FrameOwnedAxNode as FrameAxNode,
-} from "./frame-document";
+import type { CapturedFrameDocument, FrameAxNode } from "./frame-capture";

 /** Frame identity needed to resolve an `@eN` that lives in an iframe. */
 export interface CaptureVomFrame {
@@ -61,9 +61,8 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
        dom,
        sourceOrder: index,
        excluded:
-          document.excludedBackendNodeIds?.has(dom.backendNodeId) === true ||
-          (document.frameId === rootFrameId &&
-            input.excludedBackendNodeIds?.has(dom.backendNodeId) === true),
+          document.frameId === rootFrameId &&
+          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
      };
      nodes.set(id, node);
      frameNodeIds.push(id);
@@ -91,10 +90,9 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
          ax,
          sourceOrder: document.domNodes.length + index,
          excluded:
+            document.frameId === rootFrameId &&
            typeof ax.backendDOMNodeId === "number" &&
-            (document.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true ||
-              (document.frameId === rootFrameId &&
-                input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true)),
+            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
        });
        frameNodeIds.push(id);
      }
@@ -1,224 +0,0 @@
-import { createCaptureCheckpoint } from "./capture-abort";
-import type { CapturedNode } from "./capture-types";
-import type { DecodedDocument, DecodedNode } from "./facts";
-export const REQUESTED_STYLES = [
-  "position",
-  "pointer-events",
-  "cursor",
-  "visibility",
-  "opacity",
-] as const;
-const STYLE_COL = Object.fromEntries(
-  REQUESTED_STYLES.map((name, index) => [name, index]),
-) as Record<(typeof REQUESTED_STYLES)[number], number>;
-/** Sparse array format Chrome uses for infrequently-set per-node fields. */
-interface SparseArray {
-  index: number[];
-  value: number[];
-}
-
-interface RareBooleanData {
-  index: number[];
-}
-
-export interface SnapshotDocument {
-  frameId?: string | number;
-  scrollOffsetX?: number;
-  scrollOffsetY?: number;
-  nodes?: {
-    parentIndex?: number[];
-    nodeName?: number[];
-    nodeType?: number[];
-    backendNodeId?: number[];
-    attributes?: number[][];
-    /**
-     * Per-node text value (index into strings), set for `#text` / CDATA nodes.
-     * Element nodes carry -1. Same length as `backendNodeId`.
-     */
-    nodeValue?: number[];
-    /** Maps node array index → index into `documents[]` for frame content. */
-    contentDocumentIndex?: SparseArray;
-    inputValue?: SparseArray;
-    textValue?: SparseArray;
-    inputChecked?: RareBooleanData;
-    optionSelected?: RareBooleanData;
-  };
-  layout?: {
-    nodeIndex?: number[];
-    styles?: number[][];
-    bounds?: number[][];
-    paintOrders?: number[];
-  };
-}
-
-export function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
-  if (typeof document.frameId === "string") return document.frameId || undefined;
-  if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
-  return undefined;
-}
-
-export interface SnapshotReply {
-  strings?: string[];
-  documents?: SnapshotDocument[];
-}
-
-function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
-  return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
-}
-
-function snapshotFormState(
-  value: string | undefined,
-  defaultValue: string,
-  hasDefaultValue: boolean,
-  sensitive: boolean,
-): CapturedNode["formState"] {
-  if (sensitive) {
-    if (value === undefined && !hasDefaultValue) return undefined;
-    return (value ?? defaultValue) === "" ? "empty" : "filled";
-  }
-  if (value === undefined) return undefined;
-  if (value === "") return "empty";
-  return value === defaultValue ? "default" : "filled";
-}
-
-function str(strings: string[], idx: number | undefined): string {
-  if (idx === undefined || idx < 0) return "";
-  return strings[idx] ?? "";
-}
-
-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++) {
-    const nodeIndex = sparse.index[i];
-    const docIndex = sparse.value[i];
-    if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
-  }
-  return out;
-}
-
-export async function decodeDocument(
-  doc: SnapshotDocument,
-  strings: string[],
-  signal?: AbortSignal,
-): Promise<DecodedDocument> {
-  const checkpoint = createCaptureCheckpoint(signal);
-  const dn = doc.nodes;
-  const dl = doc.layout;
-  if (!dn?.backendNodeId) {
-    return { nodes: [] };
-  }
-
-  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) {
-      const pending = checkpoint();
-      if (pending) await pending;
-    }
-    layoutByNode.set(dl!.nodeIndex![i], i);
-  }
-
-  const inputValues = sparseIndexMap(dn.inputValue);
-  const textValues = sparseIndexMap(dn.textValue);
-  const checkedInputs = new Set(dn.inputChecked?.index ?? []);
-  const selectedOptions = new Set(dn.optionSelected?.index ?? []);
-
-  // Collect visible text from #text child nodes so element CapturedNodes
-  // carry a textContent value usable as a button/link label fallback.
-  // nodeValue is a parallel array: string index for text nodes, -1 otherwise.
-  const nodeTextContent = new Map<number, string[]>();
-  if (dn.nodeValue) {
-    for (let n = 0; n < count; n++) {
-      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();
-      if (!text) continue;
-      const parentIdx = dn.parentIndex?.[n] ?? -1;
-      if (parentIdx >= 0) {
-        const existing = nodeTextContent.get(parentIdx);
-        if (existing) existing.push(text);
-        else nodeTextContent.set(parentIdx, [text]);
-      }
-    }
-  }
-
-  // Decode fields without assigning a coordinate projection or semantic policy.
-  const nodes: DecodedNode[] = [];
-  for (let n = 0; n < count; n++) {
-    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;
-    const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
-
-    const attrs: Record<string, string> = {};
-    const pairs = dn.attributes?.[n] ?? [];
-    for (let a = 0; a + 1 < pairs.length; a += 2) {
-      attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
-    }
-
-    const li = layoutByNode.get(n);
-    const styleRow = li === undefined ? [] : (dl?.styles?.[li] ?? []);
-    const styles: Record<string, string> = {};
-    for (const name of REQUESTED_STYLES) styles[name] = str(strings, styleRow[STYLE_COL[name]]);
-    const layout =
-      li === undefined
-        ? undefined
-        : {
-            boundsSpace: "snapshot-document-css" as const,
-            bounds: dl?.bounds?.[li],
-            styles,
-          };
-
-    const textContent = nodeTextContent.get(n)?.join(" ");
-
-    const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
-    const rawFormValue =
-      rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
-    const sensitive = isSensitiveFormControl({ tag, attrs });
-    const formDefaultValue = attrs.value ?? "";
-    const formValue = sensitive ? undefined : rawFormValue;
-    const formState = snapshotFormState(
-      rawFormValue,
-      formDefaultValue,
-      Object.prototype.hasOwnProperty.call(attrs, "value"),
-      sensitive,
-    );
-    if (sensitive) delete attrs.value;
-
-    nodes.push({
-      backendNodeId,
-      nodeType: dn.nodeType?.[n],
-      parentBackendNodeId,
-
-      tag,
-      attrs,
-      layout,
-      paintOrder: li === undefined ? 0 : (dl?.paintOrders?.[li] ?? 0),
-      position: styles.position || "static",
-      pointerEvents: styles["pointer-events"] || "auto",
-      cursor: styles.cursor || "auto",
-
-      textContent,
-      ...(formValue !== undefined ? { formValue } : {}),
-      ...(tag === "input" || tag === "textarea"
-        ? {
-            formPlaceholder: attrs.placeholder ?? "",
-            ...(!sensitive ? { formDefaultValue } : {}),
-            ...(formState ? { formState } : {}),
-          }
-        : {}),
-      ...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
-      ...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
-    });
-  }
-  return { nodes };
-}
@@ -0,0 +1,119 @@
+# Visual observation design fixtures
+
+These are synthetic, site-independent inputs for the visual observation architecture in
+[the design](../../../../docs/design/visual-observation.md). They contain no original page
+data, account identifiers, external fonts or production selectors. They are not a production
+discovery implementation.
+
+Use [the acceptance checklist](../../../../docs/design/visual-observation-acceptance.md)
+for each PR's steps and success criteria. No separate report is required.
+Historical probe success does not certify future production modules.
+
+## Browser contract probe
+
+Requires Node.js with built-in WebSocket support (Node 22+) and an installed Chrome. No extra
+packages, user profile, extension, or login are required.
+
+From the repository root:
+
+```sh
+node apps/extension/test-fixtures/visual-observation/probe.mjs /tmp/bsk-visual-evidence
+```
+
+On platforms other than macOS, set `CHROME_PATH` to the installed Chrome executable. The probe
+starts its own headless Chrome with an ephemeral profile and a loopback fixture server. It
+removes the profile and stops Chrome/server on completion or failure. `report.json`, raw CDP
+replies and PNGs are written to the explicitly supplied directory; do not commit them.
+
+The probe verifies CSS exposure versus visibility, snapshot units, DPR raster dimensions,
+CSS zoom, frame content origins, child scrolling, nested same-target geometry, a confirmed
+OOPIF target, and navigation/document.open identity behavior. It records page-scale emulation
+separately; that is **not** browser UI zoom. It does not certify production VOM behavior, arbitrary
+occlusion, exact clip-path geometry, or all browser versions.
+
+## Minimal end-to-end reproduction
+
+```sh
+python3 -m http.server 4177 --bind 127.0.0.1 \
+  --directory apps/extension/test-fixtures/visual-observation
+bsk session start --width 1440 --height 1100
+bsk navigate http://127.0.0.1:4177/table.html --session <session>
+bsk observe --session <session>
+bsk screenshot --session <session> --out /tmp/bsk-table.png
+bsk session stop <session>
+```
+
+Always stop the session and the local server. Use a foreground Agent Window and confirm the
+painted grid is visible before interpreting the observation. `load`, AX toolbar appearance,
+and background screenshots alone do not prove a canvas has drawn.
+
+`table.html` embeds `grid.html` through `localhost` from a `127.0.0.1` parent. The grid has DOM
+toolbar controls and one unlabeled Canvas with three synthetic columns and six painted rows.
+
+Main baseline: `Page action`, `Insert record`, and `Filter` are referenceable; the painted
+`Canvas column A/B/C` and `Canvas row 1..6` have no textual observation representation or visual
+ref, despite an untruncated result. This is a **known gap**, not a golden expectation that future
+implementations must preserve.
+
+Future acceptance: retain the DOM controls and add a screenshot-only visual ref for the visible
+grid, with correct frame projection. Do not invent AX cell text. Validate the corresponding
+screenshot, then move/remove/resize and re-observe according to the freshness contract.
+
+## Discovery policy cases
+
+At a 1440×1100 window and without scrolling:
+
+| Canvas ID | Expected candidate in the new design | Reason |
+|---|---|---|
+| plain | yes | No name required |
+| named | yes | Name does not establish complete pixel semantics |
+| aria-hidden | yes | Accessibility exclusion is not visual exclusion |
+| inert | yes | Inertness is not visual hiding |
+| pointer-none | yes | Screenshot observation does not require pointer interaction |
+| visibility-override | yes | Child restores computed visibility |
+| opacity-parent | no | Ancestor makes subtree transparent |
+| display-none | no | No layout box |
+| visibility-hidden | no | Computed visibility suppresses this element |
+| zero | no | Empty geometry |
+| hidden-overridden | yes | CSS display overrides normal hidden presentation |
+| partial-clip | yes, 60×30 crop | Supported overflow intersection |
+| full-clip | no | Fully outside ancestor clip |
+| axis-clip | yes, x clipped only | overflow-x:clip and overflow-y:visible remain independent |
+| border-clip | yes, clipped to client box | Ancestor border box is not its scrollport |
+| border-canvas | yes, border-box region | Observation and live screenshot resolver must use the same box kind |
+| fallback | yes | AX fallback is not full pixel coverage |
+| stack-a / stack-b | one output entry after selection | Same document/parent/exact crop; not proof of a logical object |
+
+`checkVisibility()` is used in the probe only for CSS suppression evidence; it does not establish
+viewport intersection, ancestor overflow clipping, or absence of occlusion. `frame.html` supplies
+known local coordinates, bordered owners, nested frames and scrollable content for independent
+geometry verification. The fixture IDs must never enter production discovery code.
+
+## Renderer operation counts
+
+After installing the repository's normal dependencies:
+
+```sh
+node apps/extension/test-fixtures/visual-observation/measure-render.mjs /tmp/bsk-render-evidence
+```
+
+This instruments a temporary copy of the current renderer, runs the installed Vitest, and writes
+the source hash and loop counters to `render-counts.json`. It checks instrumentation sites and
+fails explicitly when source structure changes; update the diagnostic deliberately then. It never
+modifies production sources and never asserts that today's quadratic costs must persist.
+
+The wide fixture contains N headings followed by N equally named buttons in a common context.
+The deep fixture contains 2,000/4,000 transparent wrappers. Counters cover render-stack visits,
+ordered DOM context candidates, and same-container sibling visits. They are not a complete CPU
+profile or an assertion about the complexity of all VOM stages.
+
+Use these existing-renderer counts only as a before/after regression baseline. Improving the
+historical algorithm is not a prerequisite for Canvas work. New Canvas stages need their own
+workload models and measurements; do not copy this renderer's algorithms or use these counts
+as evidence that visual discovery, clipping, selection, or screenshot execution is efficient.
+
+## Review boundary
+
+Commit only these synthetic fixtures, diagnostic tools, and reviewed design/evidence summaries.
+Keep local browser profiles, original internal-site screenshots/HTML/observations, generated
+captures, temporary source instrumentation and build outputs outside the changeset.
@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>Frame geometry contract</title>
+  <style>
+    body { margin: 0; width: 600px; height: 900px; }
+    canvas { position: absolute; left: 17px; top: 23px; width: 120px; height: 40px; }
+    iframe { position: absolute; left: 30px; top: 90px; width: 180px; height: 100px; border: 7px solid #555; }
+  </style>
+  <canvas id="frame-canvas" width="120" height="40"></canvas>
+  <script>
+    const context = document.querySelector("canvas").getContext("2d");
+    context.fillStyle = "#15803d";
+    context.fillRect(0, 0, 120, 40);
+    context.fillStyle = "white";
+    context.fillText("FRAME PIXELS", 4, 24);
+    if (new URLSearchParams(location.search).has("nested")) {
+      const child = document.createElement("iframe");
+      child.title = "nested same-target frame";
+      child.src = "/frame.html";
+      document.body.append(child);
+    }
+    window.fixtureReady = true;
+  </script>
+</html>
@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>Canvas grid</title>
+  <style>
+    body { margin: 0; font: 16px sans-serif; }
+    nav { height: 40px; }
+    canvas { display: block; width: 780px; height: 360px; }
+  </style>
+  <nav><button type="button">Insert record</button> <button type="button">Filter</button></nav>
+  <canvas width="1560" height="720"></canvas>
+  <script>
+    const context = document.querySelector("canvas").getContext("2d");
+    context.scale(2, 2);
+    context.fillStyle = "white";
+    context.fillRect(0, 0, 780, 360);
+    context.strokeStyle = "#777";
+    for (let x = 0; x <= 780; x += 260) { context.beginPath(); context.moveTo(x, 0); context.lineTo(x, 350); context.stroke(); }
+    for (let y = 0; y <= 350; y += 50) { context.beginPath(); context.moveTo(0, y); context.lineTo(780, y); context.stroke(); }
+    context.fillStyle = "#111";
+    context.font = "16px sans-serif";
+    ["Canvas column A", "Canvas column B", "Canvas column C"].forEach((label, i) => context.fillText(label, i * 260 + 12, 30));
+    for (let row = 1; row <= 6; row++) context.fillText(`Canvas row ${row}`, 12, row * 50 + 30);
+    window.fixtureReady = true;
+  </script>
+</html>
@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>Visual observation contract fixture</title>
+  <style>
+    body { margin: 0; min-height: 1800px; font: 14px sans-serif; }
+    #cases { display: grid; grid-template-columns: repeat(4, 180px); gap: 12px; padding: 20px; }
+    .case { width: 160px; height: 70px; }
+    canvas { width: 120px; height: 40px; }
+    .clip { width: 60px; height: 30px; overflow: hidden; }
+    .axis-clip { width: 60px; height: 20px; overflow-x: clip; overflow-y: visible; }
+    #same, #cross { position: absolute; top: 600px; width: 300px; height: 220px; border: 10px solid #555; }
+    #same { left: 40px; }
+    #cross { left: 400px; }
+  </style>
+  <h1>Canvas contract</h1>
+  <button type="button" id="control">Ordinary DOM control</button>
+  <div id="cases">
+    <div class="case"><canvas id="plain"></canvas></div>
+    <div class="case"><canvas id="named" aria-label="Named chart"></canvas></div>
+    <div class="case" aria-hidden="true"><canvas id="aria-hidden"></canvas></div>
+    <div class="case" inert><canvas id="inert"></canvas></div>
+    <div class="case"><canvas id="pointer-none" style="pointer-events:none"></canvas></div>
+    <div class="case" style="visibility:hidden"><canvas id="visibility-override" style="visibility:visible"></canvas></div>
+    <div class="case" style="opacity:0"><canvas id="opacity-parent"></canvas></div>
+    <div class="case"><canvas id="display-none" style="display:none"></canvas></div>
+    <div class="case"><canvas id="visibility-hidden" style="visibility:hidden"></canvas></div>
+    <div class="case"><canvas id="zero" style="width:0"></canvas></div>
+    <div class="case"><canvas id="hidden-overridden" hidden style="display:block"></canvas></div>
+    <div class="case"><div class="clip"><canvas id="partial-clip"></canvas></div></div>
+    <div class="case"><div class="clip"><canvas id="full-clip" style="margin-left:80px"></canvas></div></div>
+    <div class="case"><canvas id="fallback">Accessible fallback is not pixel content</canvas></div>
+    <div class="case"><div class="axis-clip"><canvas id="axis-clip"></canvas></div></div>
+    <div class="case"><div id="border-clip-owner" style="width:60px;height:30px;border:5px solid black;padding:4px;overflow:hidden"><canvas id="border-clip"></canvas></div></div>
+    <div class="case"><canvas id="border-canvas" style="border:5px solid black"></canvas></div>
+    <div class="case" style="position:relative"><canvas id="stack-a"></canvas><canvas id="stack-b" style="position:absolute;left:0;top:0"></canvas></div>
+  </div>
+  <iframe id="same" title="same target"></iframe>
+  <iframe id="cross" title="cross site"></iframe>
+  <script>
+    for (const canvas of document.querySelectorAll("canvas")) {
+      canvas.width = 120;
+      canvas.height = 40;
+      const context = canvas.getContext("2d");
+      context.fillStyle = "#1d4ed8";
+      context.fillRect(0, 0, 120, 40);
+      context.fillStyle = "white";
+      context.fillText("PIXEL TABLE 42", 5, 24);
+    }
+    if (!new URLSearchParams(location.search).has("noFrames")) {
+      document.querySelector("#same").src = "/frame.html?nested=1";
+      document.querySelector("#cross").src = `${location.protocol}//localhost:${location.port}/frame.html`;
+    }
+    window.fixtureReady = true;
+  </script>
+</html>
@@ -0,0 +1,86 @@
+// Diagnostic, not a golden test requiring the current quadratic cost to persist.
+// Instrument a temporary copy; never modify the production renderer.
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../..");
+const output = process.argv[2];
+if (!output || !path.isAbsolute(output))
+  throw new Error("Pass an absolute evidence output directory");
+const require = createRequire(path.join(root, "apps/extension/package.json"));
+const vitestDirectory = path.dirname(require.resolve("vitest/package.json"));
+const temporary = await mkdtemp(path.join(os.tmpdir(), "bsk-render-measure-"));
+await mkdir(output, { recursive: true });
+try {
+  const source = await readFile(path.join(root, "packages/vom/src/render.ts"), "utf8");
+  let instrumented = source;
+  for (const [needle, field] of [
+    ["const { node, depth } = stack.pop() as { node: VomNode; depth: number };", "renderVisits"],
+    ["for (const candidate of orderedCandidates) {", "contextCandidates"],
+    ["for (const sibling of siblings) {", "siblingVisits"],
+  ]) {
+    assert.equal(instrumented.split(needle).length, 2, `Update measurement site: ${field}`);
+    instrumented = instrumented.replace(needle, `${needle} designCounts.${field}++;`);
+  }
+  instrumented = `export const designCounts = {renderVisits:0,contextCandidates:0,siblingVisits:0};\n${instrumented}`;
+  await writeFile(path.join(temporary, "render.ts"), instrumented);
+  for (const file of ["layers.ts", "types.ts"])
+    await copyFile(path.join(root, "packages/vom/src", file), path.join(temporary, file));
+  const reportPath = path.join(output, "render-counts.json");
+  await writeFile(
+    path.join(temporary, "measure.test.ts"),
+    `
+import {writeFileSync} from 'node:fs';
+import {test,expect} from ${JSON.stringify(path.join(vitestDirectory, "dist/index.js"))};
+import {renderVom,designCounts} from './render';
+test('measure operation counts',()=>{
+  const rows=[];
+  const make=(id,extra={})=>({id,parentId:1,backendNodeId:id,tag:'div',role:'generic',rect:{x:0,y:0,w:100,h:20},paintOrder:0,position:'static',pointerEvents:'auto',contextScopeId:'root',...extra});
+  const run=(shape,n,nodes)=>{
+    Object.assign(designCounts,{renderVisits:0,contextCandidates:0,siblingVisits:0});
+    const result=renderVom({viewport:{width:1440,height:1000},nodes},{maxTokens:Infinity});
+    rows.push({shape,n,counts:{...designCounts},refs:result.refs.length});
+  };
+  for(const n of [100,200,400]){
+    const nodes=[make(1,{parentId:null,role:'RootWebArea',name:'Doc'})];
+    for(let i=0;i<n;i++)nodes.push(make(i+2,{role:'heading',name:'Region '+i,domParentId:1,domAncestorIds:[1]}));
+    for(let i=0;i<n;i++)nodes.push(make(n+i+2,{tag:'button',role:'button',name:'View',domParentId:1,domAncestorIds:[1]}));
+    run('wide',n,nodes);
+  }
+  for(const n of [2000,4000]){
+    const nodes=[make(1,{parentId:null,role:'RootWebArea',name:'Doc'})];
+    for(let i=2;i<=n;i++)nodes.push(make(i,{parentId:i-1}));
+    nodes.push(make(n+1,{parentId:n,role:'button',tag:'button',name:'Unique control'}));
+    run('deep',n,nodes);
+  }
+  expect(rows.at(-1).refs).toBe(1);
+  writeFileSync(${JSON.stringify(reportPath)},JSON.stringify({sourceSha256:${JSON.stringify(createHash("sha256").update(source).digest("hex"))},rows},null,2));
+});
+`,
+  );
+  const config = path.join(temporary, "vitest.config.mjs");
+  await writeFile(
+    config,
+    `export default {test:{environment:'node',include:[${JSON.stringify(path.join(temporary, "measure.test.ts"))}]}};`,
+  );
+  const result = spawnSync(
+    process.execPath,
+    [path.join(vitestDirectory, "vitest.mjs"), "run", "--config", config],
+    { cwd: root, encoding: "utf8", timeout: 60000 },
+  );
+  await writeFile(
+    path.join(output, "render-measure.log"),
+    `${result.stdout ?? ""}\n${result.stderr ?? ""}`,
+  );
+  if (result.error) throw result.error;
+  assert.equal(result.status, 0, `Measurement failed; see ${output}/render-measure.log`);
+  process.stdout.write(`${reportPath}\n`);
+} finally {
+  await rm(temporary, { recursive: true, force: true });
+}
@@ -0,0 +1,533 @@
+// Standalone browser contract probe. No extension, credentials or user profile.
+// Raw replies and screenshots are written only to the caller-supplied directory.
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const fixtureDirectory = path.dirname(fileURLToPath(import.meta.url));
+const output = process.argv[2];
+if (!output || !path.isAbsolute(output))
+  throw new Error("Pass an absolute evidence output directory");
+const chromePath =
+  process.env.CHROME_PATH ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const styles = [
+  "position",
+  "pointer-events",
+  "cursor",
+  "visibility",
+  "opacity",
+  "overflow-x",
+  "overflow-y",
+  "display",
+];
+const checks = [];
+function check(name, condition) {
+  checks.push({ name, passed: Boolean(condition) });
+  assert.ok(condition, name);
+}
+
+class Cdp {
+  nextId = 0;
+  pending = new Map();
+  events = [];
+  counts = {};
+  async connect(url) {
+    this.socket = new WebSocket(url);
+    this.socket.addEventListener("message", ({ data }) => {
+      const reply = JSON.parse(data);
+      if (!reply.id) {
+        this.events.push(reply);
+        return;
+      }
+      const task = this.pending.get(reply.id);
+      if (!task) return;
+      this.pending.delete(reply.id);
+      clearTimeout(task.timer);
+      if (reply.error) task.reject(new Error(JSON.stringify(reply.error)));
+      else task.resolve(reply.result);
+    });
+    await new Promise((resolve, reject) => {
+      this.socket.addEventListener("open", resolve, { once: true });
+      this.socket.addEventListener("error", reject, { once: true });
+    });
+  }
+  send(method, params = {}, sessionId) {
+    const id = ++this.nextId;
+    this.counts[method] = (this.counts[method] ?? 0) + 1;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`CDP timeout: ${method}`));
+      }, 10000);
+      this.pending.set(id, { resolve, reject, timer });
+      this.socket.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+  }
+  close() {
+    for (const task of this.pending.values()) {
+      clearTimeout(task.timer);
+      task.reject(new Error("CDP closed"));
+    }
+    this.pending.clear();
+    this.socket?.close();
+  }
+}
+
+function decodedCanvases(snapshot) {
+  return snapshot.documents.flatMap((document) => {
+    const layoutByNode = new Map(document.layout.nodeIndex.map((node, index) => [node, index]));
+    return document.nodes.nodeName.flatMap((name, index) => {
+      if (snapshot.strings[name] !== "CANVAS") return [];
+      const attrs = document.nodes.attributes[index];
+      const attributes = {};
+      for (let i = 0; i < attrs.length; i += 2)
+        attributes[snapshot.strings[attrs[i]]] = snapshot.strings[attrs[i + 1]];
+      const layoutIndex = layoutByNode.get(index) ?? -1;
+      return [
+        {
+          id: attributes.id,
+          backendNodeId: document.nodes.backendNodeId[index],
+          frameId: snapshot.strings[document.frameId],
+          attributes,
+          bounds: layoutIndex < 0 ? null : document.layout.bounds[layoutIndex],
+          styles:
+            layoutIndex < 0
+              ? null
+              : Object.fromEntries(
+                  styles.map((style, i) => [
+                    style,
+                    snapshot.strings[document.layout.styles[layoutIndex][i]],
+                  ]),
+                ),
+        },
+      ];
+    });
+  });
+}
+
+await mkdir(output, { recursive: true });
+const profile = await mkdtemp(path.join(os.tmpdir(), "bsk-visual-probe-"));
+const server = http.createServer(async (request, response) => {
+  const name = new URL(request.url, "http://fixture").pathname;
+  if (!["/index.html", "/frame.html"].includes(name)) {
+    response.writeHead(404).end();
+    return;
+  }
+  try {
+    response.setHeader("Content-Type", "text/html; charset=utf-8");
+    response.end(await readFile(path.join(fixtureDirectory, name.slice(1))));
+  } catch {
+    response.writeHead(500).end();
+  }
+});
+const cdp = new Cdp();
+let chrome;
+let report = {};
+try {
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const port = server.address().port;
+  chrome = spawn(
+    chromePath,
+    [
+      "--headless=new",
+      `--user-data-dir=${profile}`,
+      "--remote-debugging-port=0",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--site-per-process",
+      "--window-size=1440,1100",
+      "about:blank",
+    ],
+    { stdio: "ignore" },
+  );
+  chrome.on("error", (error) => {
+    report.launchError = error.message;
+  });
+  let activePort;
+  for (let attempt = 0; attempt < 100; attempt++) {
+    try {
+      activePort = (await readFile(path.join(profile, "DevToolsActivePort"), "utf8"))
+        .trim()
+        .split("\n");
+      break;
+    } catch {
+      await pause(100);
+    }
+  }
+  if (!activePort)
+    throw new Error(report.launchError ?? "Chrome did not expose DevToolsActivePort");
+  await cdp.connect(`ws://127.0.0.1:${activePort[0]}${activePort[1]}`);
+  report.browser = await cdp.send("Browser.getVersion");
+  const { targetId } = await cdp.send("Target.createTarget", { url: "about:blank" });
+  const { sessionId: root } = await cdp.send("Target.attachToTarget", { targetId, flatten: true });
+  const send = (method, params = {}) => cdp.send(method, params, root);
+  const evaluate = async (expression, session = root, contextId) => {
+    const result = await cdp.send(
+      "Runtime.evaluate",
+      { expression, returnByValue: true, awaitPromise: true, ...(contextId ? { contextId } : {}) },
+      session,
+    );
+    if (result.exceptionDetails) throw new Error(JSON.stringify(result.exceptionDetails));
+    return result.result.value;
+  };
+  await send("Page.enable");
+  await send("Runtime.enable");
+  async function navigate(url) {
+    await send("Page.navigate", { url });
+    for (let i = 0; i < 100; i++) {
+      if (await evaluate("document.readyState === 'complete' && window.fixtureReady === true"))
+        return;
+      await pause(50);
+    }
+    throw new Error("Fixture did not become ready");
+  }
+  const url = `http://127.0.0.1:${port}/index.html`;
+  await navigate(`${url}?noFrames=1`);
+  async function capture(label) {
+    const metrics = await send("Page.getLayoutMetrics");
+    const snapshot = await send("DOMSnapshot.captureSnapshot", {
+      computedStyles: styles,
+      includePaintOrder: true,
+      includeDOMRects: true,
+    });
+    const ax = await send("Accessibility.getFullAXTree");
+    const runtime = await evaluate(`Array.from(document.querySelectorAll('canvas'), el => {
+      const r=el.getBoundingClientRect(), s=getComputedStyle(el);
+      return {id:el.id,rect:{x:r.x,y:r.y,w:r.width,h:r.height},visibility:s.visibility,display:s.display,
+        checkVisibility:el.checkVisibility({opacityProperty:true,visibilityProperty:true}),
+        dpr:devicePixelRatio,scrollX,scrollY}; })`);
+    const result = { metrics, snapshot, ax, runtime, canvases: decodedCanvases(snapshot) };
+    await writeFile(path.join(output, `${label}.json`), JSON.stringify(result, null, 2));
+    return result;
+  }
+  const baseline = await capture("root-baseline");
+  const rootImage = await send("Page.captureScreenshot", { format: "png" });
+  await writeFile(path.join(output, "root.png"), Buffer.from(rootImage.data, "base64"));
+  const runtime = Object.fromEntries(baseline.runtime.map((node) => [node.id, node]));
+  for (const id of [
+    "plain",
+    "named",
+    "aria-hidden",
+    "inert",
+    "pointer-none",
+    "visibility-override",
+    "hidden-overridden",
+    "fallback",
+  ])
+    check(`CSS visible: ${id}`, runtime[id].checkVisibility);
+  for (const id of ["opacity-parent", "display-none", "visibility-hidden"])
+    check(`CSS suppressed: ${id}`, !runtime[id].checkVisibility);
+  check("painted text is absent from AX", !JSON.stringify(baseline.ax).includes("PIXEL TABLE 42"));
+  report.css = baseline.runtime;
+  const bordered = baseline.canvases.find((node) => node.id === "border-canvas");
+  report.canvasBox = await send("DOM.getBoxModel", { backendNodeId: bordered.backendNodeId });
+  check(
+    "Canvas snapshot uses border box",
+    bordered.bounds[2] === 130 &&
+      report.canvasBox.model.border[2] - report.canvasBox.model.border[0] === 130 &&
+      report.canvasBox.model.content[2] - report.canvasBox.model.content[0] === 120,
+  );
+  const rootDocument = baseline.snapshot.documents[0];
+  const ownerNode = rootDocument.nodes.attributes.findIndex((attrs) =>
+    attrs.some(
+      (value, index) => index % 2 === 1 && baseline.snapshot.strings[value] === "border-clip-owner",
+    ),
+  );
+  const ownerLayout = rootDocument.layout.nodeIndex.indexOf(ownerNode);
+  report.clipClientBox = {
+    snapshot: rootDocument.layout.clientRects[ownerLayout],
+    runtime: await evaluate(
+      "(() => {const e=document.getElementById('border-clip-owner');return [e.clientLeft,e.clientTop,e.clientWidth,e.clientHeight]})()",
+    ),
+  };
+  check(
+    "snapshot client rect contains local client offsets and size",
+    JSON.stringify(report.clipClientBox.snapshot) ===
+      JSON.stringify(report.clipClientBox.runtime) &&
+      JSON.stringify(report.clipClientBox.runtime) === "[5,5,68,38]",
+  );
+  report.clips = await evaluate(`['partial-clip','full-clip','axis-clip'].map(id=>{
+    const el=document.getElementById(id),p=el.parentElement,s=getComputedStyle(p);
+    const a=el.getBoundingClientRect(),b=p.getBoundingClientRect();
+    return {id,overflowX:s.overflowX,overflowY:s.overflowY,
+      child:{x:a.x,y:a.y,w:a.width,h:a.height},parent:{x:b.x,y:b.y,w:b.width,h:b.height}};
+  })`);
+  const [partial, full, axis] = report.clips;
+  check(
+    "partial overflow crop dimensions",
+    partial.parent.w === 60 &&
+      partial.parent.h === 30 &&
+      partial.child.x === partial.parent.x &&
+      partial.child.y === partial.parent.y,
+  );
+  check(
+    "fully clipped candidate lies beyond ancestor",
+    full.child.x >= full.parent.x + full.parent.w,
+  );
+  check(
+    "single-axis clip remains independent in computed style",
+    axis.overflowX === "clip" && axis.overflowY === "visible" && axis.child.h > axis.parent.h,
+  );
+  const samples = [];
+  for (let i = 0; i < 12; i++)
+    samples.push(
+      await evaluate(
+        "JSON.stringify(document.querySelector('#plain').getBoundingClientRect().toJSON())",
+      ),
+    );
+  check("static rect stable over 12 reads", new Set(samples).size === 1);
+  await evaluate("document.querySelector('#plain').style.transform='translateX(0.5px)'");
+  report.halfPixelMovement = await evaluate(
+    "document.querySelector('#plain').getBoundingClientRect().x",
+  );
+  await evaluate("document.querySelector('#plain').style.transform=''");
+  report.raster = [];
+  for (const dpr of [1, 1.5, 2]) {
+    await send("Emulation.setDeviceMetricsOverride", {
+      width: 1000,
+      height: 900,
+      deviceScaleFactor: dpr,
+      mobile: false,
+    });
+    const state = await capture(`dpr-${dpr}`);
+    const image = await send("Page.captureScreenshot", {
+      format: "png",
+      clip: { x: 20, y: 100, width: 120, height: 40, scale: 1 },
+    });
+    const bytes = Buffer.from(image.data, "base64");
+    const dimensions = { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+    report.raster.push({
+      dpr,
+      dimensions,
+      metrics: state.metrics,
+      plain: state.canvases.find((node) => node.id === "plain"),
+    });
+    check(
+      `screenshot raster DPR ${dpr}`,
+      dimensions.width === 120 * dpr && dimensions.height === 40 * dpr,
+    );
+  }
+  await send("Emulation.clearDeviceMetricsOverride");
+  await evaluate("document.body.style.zoom='1.25'");
+  const cssZoom = await capture("css-zoom-1.25");
+  check(
+    "CSS zoom is reflected in snapshot geometry",
+    cssZoom.canvases.find((n) => n.id === "plain").bounds[2] === 150,
+  );
+  report.cssZoom = {
+    runtime: cssZoom.runtime[0],
+    snapshot: cssZoom.canvases.find((n) => n.id === "plain"),
+  };
+  await evaluate("document.body.style.zoom=''");
+  await send("Emulation.setPageScaleFactor", { pageScaleFactor: 1.5 });
+  report.pageScale = (await capture("page-scale-1.5")).metrics;
+  await send("Emulation.setPageScaleFactor", { pageScaleFactor: 1 });
+  await evaluate("scrollTo(0,100)");
+  const scrolled = await capture("scroll-100");
+  check(
+    "snapshot document bounds stable under scroll",
+    JSON.stringify(scrolled.canvases.find((n) => n.id === "plain").bounds) ===
+      JSON.stringify(baseline.canvases.find((n) => n.id === "plain").bounds),
+  );
+  check(
+    "runtime viewport y follows scroll",
+    scrolled.runtime[0].rect.y === baseline.runtime[0].rect.y - 100,
+  );
+  await navigate(url);
+  await pause(200);
+  const targets = await cdp.send("Target.getTargets");
+  const iframeTarget = targets.targetInfos.find(
+    (target) => target.type === "iframe" && target.url.startsWith(`http://localhost:${port}/`),
+  );
+  check("cross-site frame is an actual OOPIF target", iframeTarget);
+  const { sessionId: child } = await cdp.send("Target.attachToTarget", {
+    targetId: iframeTarget.targetId,
+    flatten: true,
+  });
+  report.frames = {};
+  for (const [name, session] of [
+    ["root", root],
+    ["oopif", child],
+  ]) {
+    const tree = await cdp.send("Page.getFrameTree", {}, session);
+    const snapshot = await cdp.send(
+      "DOMSnapshot.captureSnapshot",
+      { computedStyles: styles, includeDOMRects: true },
+      session,
+    );
+    const frameRows = [];
+    const stack = [tree.frameTree];
+    while (stack.length) {
+      const node = stack.pop();
+      const world = await cdp.send(
+        "Page.createIsolatedWorld",
+        { frameId: node.frame.id, worldName: "bsk-design-probe" },
+        session,
+      );
+      const local = await evaluate(
+        "({url:location.pathname,innerWidth,innerHeight,scrollX,scrollY,canvas:document.querySelector('canvas').getBoundingClientRect().toJSON()})",
+        session,
+        world.executionContextId,
+      );
+      let owner;
+      if (node.frame.parentId) {
+        // All owners in this fixture live in the root target; child content can be OOPIF.
+        const address = await send("DOM.getFrameOwner", { frameId: node.frame.id });
+        owner = await send("DOM.getBoxModel", { backendNodeId: address.backendNodeId });
+      }
+      frameRows.push({ frame: node.frame, local, owner });
+      stack.push(...(node.childFrames ?? []));
+    }
+    report.frames[name] = { tree, snapshot, canvases: decodedCanvases(snapshot), frameRows };
+  }
+  check(
+    "same-target snapshot includes nested documents",
+    report.frames.root.snapshot.documents.length === 3,
+  );
+  check("oopif snapshot isolated from root", report.frames.oopif.snapshot.documents.length === 1);
+  const sameRow = report.frames.root.frameRows.find(
+    (row) => row.owner && row.local.innerWidth === 300,
+  );
+  const nestedRow = report.frames.root.frameRows.find(
+    (row) => row.owner && row.local.innerWidth === 180,
+  );
+  check(
+    "same frame content origin includes border",
+    sameRow.owner.model.content[0] === 50 && sameRow.owner.model.content[1] === 610,
+  );
+  check(
+    "nested owner quad is already target-root relative",
+    nestedRow.owner.model.content[0] === 87 && nestedRow.owner.model.content[1] === 707,
+  );
+  const crossRow = report.frames.oopif.frameRows[0];
+  check(
+    "OOPIF owner content origin",
+    crossRow.owner.model.content[0] === 410 && crossRow.owner.model.content[1] === 610,
+  );
+  const sameFrame = sameRow.frame.id;
+  const world = await send("Page.createIsolatedWorld", {
+    frameId: sameFrame,
+    worldName: "bsk-design-probe",
+  });
+  await evaluate("scrollTo(0,10)", root, world.executionContextId);
+  const frameScroll = await send("DOMSnapshot.captureSnapshot", {
+    computedStyles: styles,
+    includeDOMRects: true,
+  });
+  report.frameScroll = {
+    documents: frameScroll.documents.map((d) => ({
+      frameId: frameScroll.strings[d.frameId],
+      scrollOffsetY: d.scrollOffsetY,
+    })),
+    canvases: decodedCanvases(frameScroll),
+    local: await evaluate(
+      "document.querySelector('canvas').getBoundingClientRect().toJSON()",
+      root,
+      world.executionContextId,
+    ),
+  };
+  check("frame scroll is local", report.frameScroll.local.y === 13);
+  check(
+    "frame snapshot stays document-relative after child scroll",
+    report.frameScroll.canvases.find((n) => n.frameId === sameFrame).bounds[1] === 23,
+  );
+  await evaluate("scrollTo(0,0)", root, world.executionContextId);
+  await evaluate(
+    "document.querySelector('#same').style.transformOrigin='0 0';document.querySelector('#same').style.transform='scale(1.25)'",
+  );
+  const sameOwner = await send("DOM.getFrameOwner", { frameId: sameFrame });
+  report.transformedOwner = await send("DOM.getBoxModel", {
+    backendNodeId: sameOwner.backendNodeId,
+  });
+  check(
+    "scaled frame owner content width",
+    report.transformedOwner.model.content[2] - report.transformedOwner.model.content[0] === 375,
+  );
+  await evaluate("document.querySelector('#same').style.transform=''");
+  const screenshot = await send("Page.captureScreenshot", { format: "png" });
+  await writeFile(path.join(output, "frames.png"), Buffer.from(screenshot.data, "base64"));
+  const before = (await send("Page.getFrameTree")).frameTree.frame;
+  const oldDocument = (await send("DOM.getDocument")).root.backendNodeId;
+  await evaluate("history.replaceState(null,'','#same-document')");
+  const sameDocument = (await send("Page.getFrameTree")).frameTree.frame;
+  const sameDocumentBackend = (await send("DOM.getDocument")).root.backendNodeId;
+  await navigate(`${url}?noFrames=1&navigation=2`);
+  const after = (await send("Page.getFrameTree")).frameTree.frame;
+  const newDocument = (await send("DOM.getDocument")).root.backendNodeId;
+  report.identity = { before, sameDocument, after, oldDocument, sameDocumentBackend, newDocument };
+  check("same-document navigation preserves loader", before.loaderId === sameDocument.loaderId);
+  check("cross-document navigation changes loader", before.loaderId !== after.loaderId);
+  check("frame id survives document replacement", before.id === after.id);
+  check(
+    "document backend identity changes on navigation",
+    oldDocument !== newDocument && oldDocument === sameDocumentBackend,
+  );
+  const documentTree = await send("DOM.getDocument");
+  report.identity.htmlBeforeOpen = documentTree.root.children.find(
+    (node) => node.nodeType === 1,
+  ).backendNodeId;
+  const anchorNode = await send("DOM.querySelector", {
+    nodeId: documentTree.root.nodeId,
+    selector: "canvas",
+  });
+  const anchor = await send("DOM.describeNode", { nodeId: anchorNode.nodeId });
+  await evaluate(
+    "document.open(); document.write('<!doctype html><title>Replacement</title><canvas></canvas>'); document.close()",
+  );
+  report.identity.documentOpen = (await send("Page.getFrameTree")).frameTree.frame;
+  const afterOpenTree = await send("DOM.getDocument");
+  report.identity.documentOpenBackend = afterOpenTree.root.backendNodeId;
+  report.identity.htmlAfterOpen = afterOpenTree.root.children.find(
+    (node) => node.nodeType === 1,
+  ).backendNodeId;
+  check(
+    "document.open replaces documentElement identity",
+    report.identity.htmlBeforeOpen !== report.identity.htmlAfterOpen,
+  );
+  try {
+    const object = await send("DOM.resolveNode", { backendNodeId: anchor.node.backendNodeId });
+    const connected = await send("Runtime.callFunctionOn", {
+      objectId: object.object.objectId,
+      functionDeclaration: "function(){return this.isConnected}",
+      returnByValue: true,
+    });
+    report.identity.oldAnchorConnected = connected.result.value;
+  } catch {
+    report.identity.oldAnchorConnected = false;
+  }
+  check(
+    "document.open invalidates old anchor even if document identifiers survive",
+    report.identity.oldAnchorConnected === false,
+  );
+  report.counts = cdp.counts;
+  report.checks = checks;
+  process.stdout.write(
+    `${JSON.stringify({ browser: report.browser.product, checks: checks.length, output })}\n`,
+  );
+} catch (error) {
+  report.error = error.stack;
+  report.checks = checks;
+  process.exitCode = 1;
+  process.stderr.write(`${error.stack}\n`);
+} finally {
+  await writeFile(path.join(output, "report.json"), JSON.stringify(report, null, 2));
+  cdp.close();
+  if (chrome && chrome.exitCode === null) {
+    const exited = once(chrome, "exit");
+    chrome.kill("SIGTERM");
+    await Promise.race([exited, pause(2000)]);
+    if (chrome.exitCode === null) {
+      chrome.kill("SIGKILL");
+      await exited;
+    }
+  }
+  await new Promise((resolve) => server.close(resolve));
+  await rm(profile, { recursive: true, force: true });
+}
@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <meta charset="utf-8">
+  <title>Embedded Canvas table reproduction</title>
+  <style>
+    body { font: 16px sans-serif; }
+    iframe { display: block; width: 800px; height: 440px; border: 8px solid #ccc; }
+  </style>
+  <h1>Embedded table</h1>
+  <button type="button">Page action</button>
+  <iframe title="Table application"></iframe>
+  <script>
+    document.querySelector("iframe").src = `http://localhost:${location.port}/grid.html`;
+  </script>
+</html>
@@ -73,14 +73,6 @@ 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();
@@ -96,16 +88,16 @@ where
    let outcome = tokio::select! {
        biased;
        res = &mut main_fut => res?,
-        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");
+        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");
            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,
-                        "cancel grace elapsed; synthesising cancelled error"
+                        "SIGINT: cancel grace elapsed; synthesising cancelled error"
                    );
                    return Err(CliError::from_rpc(RpcError {
                        code: ErrorCode::Cancelled,
@@ -120,46 +112,6 @@ 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.
 ///
@@ -194,57 +146,8 @@ fn random_short_id() -> String {
    bytes.iter().map(|b| format!("{b:02x}")).collect()
 }

-/// 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.
+/// Wait for either Ctrl-C or process SIGTERM. Returning here means
+/// the user has asked us to stop.
 async fn wait_for_sigint() -> anyhow::Result<()> {
    tokio::signal::ctrl_c().await.context("listen for SIGINT")?;
    Ok(())
@@ -9,7 +9,8 @@ use anyhow::Context;
 use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
-    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult,
+    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult, TransferIdParams,
+    TransferReleaseResult,
 };
 use clap::Args;
 use uuid::Uuid;
@@ -69,7 +70,13 @@ 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 _ = crate::cli::business_rpc::release_transfers(&info.sock_path, [transfer_id.as_str()]);
+    let _: Result<TransferReleaseResult, CliError> = crate::cli::business_rpc::call(
+        info.sock_path,
+        "transfer-release",
+        Method::TransferRelease,
+        Some(TransferIdParams { transfer_id }),
+        Duration::from_secs(5),
+    );
    write_result?;
    match format {
        Format::Json => {
@@ -10,7 +10,8 @@ use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
    TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
-    TransferIdParams, TransferReadyResult, UploadFile, UploadMode, UploadParams, UploadResult,
+    TransferIdParams, TransferReadyResult, TransferReleaseResult, UploadFile, UploadMode,
+    UploadParams, UploadResult,
 };
 use clap::{Args, ValueEnum};

@@ -68,12 +69,14 @@ 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 {
-        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);
+        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);
+            }
        }
    }
    let params = UploadParams {
@@ -99,17 +102,6 @@ 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.
@@ -126,12 +118,7 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
    Ok(())
 }

-fn stage_file(
-    sock: &Path,
-    session: &str,
-    path: &PathBuf,
-    staged: &mut Vec<(String, String)>,
-) -> Result<(), CliError> {
+fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, String), CliError> {
    let mut file = File::open(path)
        .with_context(|| format!("open upload file {}", path.display()))
        .map_err(CliError::Local)?;
@@ -162,39 +149,55 @@ fn stage_file(
        }),
        Duration::from_secs(10),
    )?;
-    // 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 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;
        }
-        let reply: TransferChunkResult = crate::cli::business_rpc::call(
+        let _: TransferReadyResult = crate::cli::business_rpc::call(
            sock.to_path_buf(),
-            "transfer-chunk",
-            Method::TransferChunk,
-            Some(TransferChunkParams {
+            "transfer-finish",
+            Method::TransferFinish,
+            Some(TransferIdParams {
                transfer_id: begin.transfer_id.clone(),
-                offset,
-                data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
            }),
-            Duration::from_secs(30),
+            Duration::from_secs(10),
        )?;
-        offset = reply.next_offset;
+        Ok::<_, CliError>(())
+    })();
+    if let Err(err) = staged {
+        let _ = release(sock, &begin.transfer_id);
+        return Err(err);
    }
-    let _: TransferReadyResult = crate::cli::business_rpc::call(
+    Ok((begin.transfer_id, name))
+}
+
+fn release(sock: &Path, id: &str) -> Result<TransferReleaseResult, CliError> {
+    crate::cli::business_rpc::call(
        sock.to_path_buf(),
-        "transfer-finish",
-        Method::TransferFinish,
+        "transfer-release",
+        Method::TransferRelease,
        Some(TransferIdParams {
-            transfer_id: begin.transfer_id.clone(),
+            transfer_id: id.to_string(),
        }),
-        Duration::from_secs(10),
-    )?;
-    Ok(())
+        Duration::from_secs(5),
+    )
 }

 fn ipc_timeout(timeout_ms: u32) -> Duration {
@@ -1,342 +0,0 @@
-//! 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"))
-            );
-        }
-    }
-}
@@ -0,0 +1,184 @@
+# Visual observation：验收清单
+
+新 agent 先读 [架构与 PR 划分](visual-observation.md)，再按本清单验收当前 PR；无需聊天记录，也无需另写报告、逐项编号或填写模板。历史结果见 [PR 0 证据](visual-observation-evidence.md)，不能代替本次执行。
+
+## 怎么开始
+
+- 查看分支、HEAD 和工作区改动，确认当前做哪个 PR。PR 0 基于 main `3c5f838`；后续模块对照其前置基线，最终回归对照 main。注意未跟踪文件也属于改动。
+- 当前仅有设计、合成 fixture 和诊断脚本；未来模块尚未实现。只验收当前阶段及受影响的已有功能，不要求提前完成后续 PR。
+- 测试放在模块附近，调用实际生产代码。未接线模块可用人工输入和 CDP stub；实现 PR 写明运行命令即可，不强制新建指定目录、命名或诊断 API。
+- 浏览器验收前核实 CLI 版本，并重新 build、确认扩展 reload。PATH 中的 bsk 曾经比仓库版本旧，不能只凭版本号认定运行了目标代码。
+- 不 commit/push。截图、原始页面内容和一次性实验放临时目录；只把长期需要的设计、fixture 和测试留在仓库。
+
+## 现有验证入口
+
+从仓库根目录运行，命令成功退出且相关断言通过才算成功：
+
+```sh
+pnpm vom:test
+pnpm --filter @browser-skill/extension test src/tools/__tests__/frame-geometry.test.ts src/tools/__tests__/element-geometry.test.ts src/tools/__tests__/observation.test.ts src/tools/__tests__/snapshot-ref.test.ts src/tools/__tests__/interaction.test.ts src/tools/vom src/session-manager/__tests__/ref-store.test.ts
+pnpm exec biome check apps/extension/test-fixtures/visual-observation
+VISUAL_EVIDENCE="$(mktemp -d /tmp/bsk-visual-acceptance.XXXXXX)"
+node apps/extension/test-fixtures/visual-observation/probe.mjs "$VISUAL_EVIDENCE/browser-contract"
+node apps/extension/test-fixtures/visual-observation/measure-render.mjs "$VISUAL_EVIDENCE/performance"
+```
+
+probe 需要 Node 22+ 和 Chrome，配置见 [fixture 说明](../../apps/extension/test-fixtures/visual-observation/README.md)。它验证浏览器事实，不代表后续生产模块已经通过。measure-render 用于旧 renderer 对照，不要求修复历史复杂度。
+
+实现 PR 还需运行所属模块的新测试、`pnpm --filter @browser-skill/extension compile`、`pnpm ext:test` 和 `pnpm ext:build`。仅修改文档时检查链接和内容即可，不必重跑浏览器。已有失败应说明，不在范围外顺手修复。
+
+## 每个 PR 怎么算完成
+
+### PR 0：设计与复现
+
+只有文档、合成 fixture 和诊断变动；架构、边界及后续 PR 的完成条件明确。现有测试通过；probe 的 checks 非空且全部通过（本版 39 项）；measure-render 产生五组 wide/deep 结果。
+
+按下方浏览器步骤，在 main 重现“表格已绘制，但 observe 没有视觉入口”。合成页面和原始 iWiki 分别确认。原始页面未加载、无权限或缺入口时说明阻塞，不能算已复现。入库内容不含内部页面地址、标识或截图。
+
+### PR 1：几何与身份
+
+数值误差：纯函数输入允许 1e-6 CSS px；真实浏览器每条边允许 0.25 CSS px。坐标类型不能混传；动态 frame 归属需运行时检查。
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| top document bounds=(30,50,120,40)，document scroll=(10,20)，viewport=800×600 | top border region=(20,30,120,40)；不受 backing store 尺寸影响 |
+| 使用 frame.html：local Canvas=(17,23,120,40)，same owner content origin=(50,610)；nested origin=(87,707)；OOPIF origin=(410,610) | top origins 分别=(67,633)、(104,730)、(427,633)；不能重复给 nested 加父偏移；owner border 不能代替 content |
+| child scrollY=10；same frame owner origin 不变 | Canvas top y=623，local y=13；snapshot document y=23；scroll 只扣一次 |
+| same iframe 以自身左上角为原点 scale(1.25)，原 border origin=(40,600)，border=10 | owner content origin=(52.5,612.5)，Canvas top=(73.75,641.25)，尺寸150×50 |
+| Canvas content 120×40，border 每边5；overflow owner CSS width60/height30/border5/padding4 | Canvas region 宽130高50，live 验证同 box；owner clientRect=(5,5,68,38)，不能使用78×48 border范围作为clip |
+| DPR=1/1.5/2，CSS Canvas120×40；UI zoom与CSS zoom分别处理 | DPR不直接除掉 CSS rect；raster 预测与实际图片分别记录；不以layout/css宽度比作为万能DPR |
+| 分别构造缺失 owner、失效 frame、旋转、透视、mask、clip-path、活动pinch、变换的overflow祖先 | 前两项 geometry-unavailable，后六类 geometry-unsupported；无伪造精确 region ref、无按border猜偏移 |
+| 同一操作并发请求同一frame 20次，再开启第二次操作 | 第一次每个metrics来源、owner quad、frame投影最多构建/请求一次；第二次重新获取；异常promise不泄漏到其他操作 |
+
+### PR 2：采集与共享事实
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| target A/B 各含 backendNodeId=7，frame/document不同 | 两个lookup结果独立；AX join、overlay排除和父子查找不串target |
+| 4个frame分属2个target，其中一个target有3份document；均成功采集 | 每target恰好一次DOMSnapshot；每frame恰好一次AX批次；失败重试不混入成功请求数；无按frame重复snapshot |
+| 采集中模拟frame detach或loader/documentElement更换 | 丢弃受影响document的混合事实并标记原因；其他完整document可保留；不得把新AX接到旧DOM |
+| 输入10,000深链、10,000兄弟、孤儿及A→B→A环 | 无栈溢出/无限循环；孤儿/环有明确不完整状态；不生成完整祖先证据；context推导每有效节点至多一次 |
+| opacity0祖先；visibility:hidden祖先+visible子；aria-hidden/inert祖先 | 分别得到视觉透明、子可见、语义/交互状态独立；不折叠为同一个excluded |
+| 一个frame采集失败，其他frame有语义节点；全部成功但无Canvas | 前者partial且保留其他语义；后者empty而非unavailable；错误原因可追踪到frame及阶段 |
+| 注入CDP调用记录和hover探针；纯计算中途取消 | 所有静态DOM/AX捕获先于hover输入；取消后下一工作块不继续处理，未执行的输入/截图为0；取消不变成普通空结果 |
+
+### PR 3：视觉发现
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| index.html?noFrames=1 的plain、named、aria-hidden、inert、pointer-none、visibility-override、hidden-overridden、fallback | 八个均为候选；无label不影响发现，有AX/fallback不抑制候选 |
+| opacity-parent、display-none、visibility-hidden、zero、full-clip | 五个均无候选，原因分别能追踪到视觉/几何规则；不能把aria-hidden列为原因 |
+| partial-clip、axis-clip、border-clip、border-canvas | crop尺寸分别60×30、60×40、64×34、130×50；边界来自client box/同种Canvas box |
+| 同frame中删除语义parent，再保持DOM/几何不变 | 候选仍存在、地址不变；语义context可变为null；frame owner本身无法解析时不是该用例 |
+| 连续两次输入同一只读Facts；对Facts启用深冻结 | 候选内容一致，无输入mutation，无CDP调用；去重前stack-a/b仍是两个候选 |
+| 普通候选部分越出viewport；完全越界；overlay-owned Canvas；unsupported clip | 分别交集区域、无候选、排除、明确unsupported状态；不把未知状态伪装成empty |
+
+### PR 4：选择与预算
+
+预算按每个输出行的 `ceil(line.length/4)` 求和（UTF-16 length），包括头部和截断提示。H 为完整协议头成本，V 为固定行 `[visual] Canvas regions present; use screenshot` 的成本。
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| 同context：无名1000×800候选A，有名10×10候选B，K=1 | 选A；名称不能压倒区域面积 |
+| 同document/parent且crop完全相同的A/B；另一个parent的C；crop右边相差0.01的D；相邻tile E | A/B仅输出一个代表；C/D/E独立保留；不输出layers=N作为业务解释 |
+| 面积相同的候选随机打乱20次，地址/位置保持不变 | 排序相同；tie-break顺序固定为frameId、top y、left x、backendNodeId（同一观察内）；去重代表取该顺序最小者；字符串按代码单元字典序、数值按数值升序 |
+| 50,001个不同key，最后一个为最大Canvas，K=1 | 最后最大者仍被选中；dedup key峰值≤50,000；标记dedup-degraded；未因容量耗尽停扫描 |
+| 100,000候选、K=1/32/512；另测K=0 | 选中数量≤K、heap峰值≤K、exact-key之外的模糊pair比较为0；K=0不产生ref候选；结果与独立全排序小规模oracle一致 |
+| 带blocking layer的纯输入，候选context在L1、背景、未知各一个 | L1优先，背景不标为物理不可见，未知不伪装L1；同层再按面积及固定 tie-break 排序；不修改Facts |
+| 预算H-1 | 新observe规划返回insufficient-budget，工具映射invalid_params并给minimum=H；无新文本/ref提交；snapshot旧路径不改变 |
+| 有候选，预算H、H+V-1、H+V | 前两个输出合法协议头、无悬空ref、truncated=true；H+V能保留固定视觉提示；全部账本≤预算 |
+| 没有显式maxTokens，候选足够多 | 视觉附加部分cost≤2048；最终视觉条目≤512；不是对整个旧语义输出强加2048 |
+| 标签含200个Unicode code point、引号、换行、代理对emoji | 标签先截至160 code point再JSON escape，按最终行核算；无断开的代理对，无换行注入额外条目；写不下的行不产生ref |
+| finite预算取H+V、64、128、256、2048（小于H时拒绝），混合长短条目 | 每次总账本≤budget；输出决定可重复；已知omitted才给精确数，候选/去重组/上游未知数量不混加 |
+
+### PR 5：类型化 ref
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| 注册DOM和visual-region两个判别目标 | kind决定操作资格；类型测试不能构造visual+interact矛盾状态；不额外接受调用者capability数组 |
+| 同名ref置于两个session/tab；输入@e1与e1 | canonical形式可解析；不同session/tab不串目标；未知目标为既有not_found类错误 |
+| 对visual ref调用click/fill/hover/select/get_html/人工帮助DOM定位入口 | 全部按主设计拒绝；CDP输入、DOM HTML读取、DOM高亮等该工具副作用次数为0；不能偷偷降为anchor操作 |
+| loader变化、target重attach、documentElement替换；另测history.replaceState不改身份 | 前三者拒绝旧目标；最后不单凭URL变化拒绝；实际anchor仍需连接 |
+| document.open保留loader/document backend但替换html和Canvas | 旧ref失效；只比较loader的实现必须被此测试击败 |
+| 第二次observe重新绑定e1；第一次ref字符串再次输入 | 明确验证“最新观察映射”而非声称能识别旧字符串；新映射仅来自成功提交；旧DOM工具回归通过 |
+
+### PR 6：截图执行
+
+首次 clipScale 为 `min(1, 2048/(max(w,h)*r), sqrt(4000000/(w*h*r*r)))`；r 来自实际 metrics 适配，最终仍检查真实 PNG 尺寸。
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| visual ref解析成功并截图；DOM ref另测 | visual路径scrollIntoView次数0；DOM路径保持BASE策略；visual实时box种类与观察一致 |
+| 同anchor四边分别移动0.249、0.25、0.251 CSS px；分别改尺寸/裁剪策略 | 前两种仅数值误差可接受，0.251拒绝；document/裁剪策略变化不受容差豁免；不靠old∩live返回小片段 |
+| 保持身份/几何，重绘Canvas颜色；另移除Canvas | 重绘允许取得当前图像；移除拒绝；不承诺像素快照或把颜色改变误报为stale |
+| css4096×2048,rasterEstimate2；css4000×4000,rasterEstimate1 | 首次clipScale分别0.25、0.5（不放大，取edge/area/1最小值）；实际成功尺寸每边≤2048、面积≤4,000,000 |
+| mock第一次图片3000×3000，第二次2000×2000；再测两次均3000×3000 | 第一组重试一次并成功，第二组恰好两次后pixel-budget-exceeded；不能无限重试或返回超限图 |
+| 空data、非法PNG头、0尺寸、负/非有限几何 | 明确失败，不能猜测width/height；此项不要求将PNG头检查宣称为完整解码校验 |
+| capture前取消；overlay抑制后CDP失败；采集时出现dialog | 取消前不再capture；成功/失败/取消均恢复overlay；dialog机制保持既有契约；无额外输入 |
+
+### PR 7：observe 接线
+
+| 怎么测 | 什么算成功 |
+|---|---|
+| 固定SemanticScene，无视觉候选；普通预算，与BASE replay同一输入 | 语义文本、ref相对顺序、role/name一致；不因为新通道重跑semantic pipeline |
+| 同SemanticScene加两个视觉候选，大预算 | 原DOM ref顺序不变，视觉ref在其后；每个输出ref均可在registry找到同目标，registry无未输出新ref |
+| DOM文本多到耗尽除预留外的预算 | 固定视觉提示可见（预算允许时）；truncated=true；不是DOM stopped后无条件跳过视觉提示 |
+| 视觉capture unavailable但语义成功 | 语义结果保留，观察状态能区分empty/unavailable/truncated；debug reason准确且无原始DOM泄漏 |
+| snapshot、recording调用、hover probe on/off与BASE对比 | snapshot不新增visual；recording不隐式启用发现；probe默认off，on时仍在静态采集后；相应既有测试通过 |
+| blocking layer混合DOM/visual、重复候选、不同预算 | 输出层策略与选择模块的活跃层策略一致；头、摘要、条目、occlusion/omitted行均纳入账本；无悬空ref |
+
+### PR 8：整体验收
+
+复跑上述模块测试、下方性能对照和浏览器场景，确认原始 iWiki 的缺口已解决。检查没有站点特判、重复的几何/预算权威实现或遗留的替代路径；没有顺带扩展到 OCR、逻辑画布聚合或旧算法重写。不能只凭合成页面通过宣布原始问题解决。
+
+## 性能怎么验
+
+在相关模块实现时检查，不拖到最后统一补。旧路径和新增 Canvas 成本分开看：
+
+- **旧路径**：同输入对照 main/前置基线，已有 render/context/sibling 工作量、语义构建次数和 DOM 操作请求不增加；保留 #165 的回归。不要求消除旧算法的历史二次项。
+- **无 Canvas**：允许必要检测与共享几何成本，但不构建视觉专用索引、不发视觉专用 CDP 请求、不重复跑语义链路。
+- **新增树处理**：deep/wide 节点数取 1k、10k、100k；每节点 context 至多推导一次，每条边每个索引 pass 至多访问一次，pass 数不随规模增加。无递归溢出、每候选完整祖先遍历或全祖先数组复制。
+- **选择**：候选数取 1k、10k、100k，K 取 1、32、512；堆峰值不超过 K，去重 key 不超过 50,000，无模糊两两比较。比较计数符合具体算法推导的上界；小规模结果与独立全排序对照一致，容量耗尽后仍能选中最后的大图。
+- **请求与取消**：每 target 一次 snapshot、每 frame 一次 AX 批次；单次操作内几何请求共享，不跨操作复用 live cache。几何最大并发 4，新增计算每块最多 256 项并实际让出事件循环，取消后不再启动下一块。
+- **接线后耗时**：同机器、浏览器和固定内容，分别测无 Canvas 页与合成表格页。各预热 3 次，再基线/新版本交替各 20 次，比较中位数和 p95；旧阶段与新增成本分开。旧阶段中位数增加超过 max(基线 10%, 2ms) 时复测，两轮均超过且可归因于改动则未通过；噪声无法排除则说明尚未确认。操作数仍须满足前述条件，不能用耗时阈值代替它们。
+
+计数可以由测试插桩取得，不必为验收增加生产接口。性能结果只需说明旧路径是否回退、新增路径的规模与成本，不需要另填表格。
+
+## 浏览器怎么验
+
+### 合成表格（PR 0 复现；PR 7/8 验证修复）
+
+1. 核实 `bsk --version`、`bsk browsers`、`bsk status`；运行 `pnpm ext:build`，确认用户已 reload `apps/extension/dist/chrome-mv3`。
+2. 单独启动服务器：`python3 -m http.server 4177 --bind 127.0.0.1 --directory apps/extension/test-fixtures/visual-observation`。
+3. `bsk session start --width 1440 --height 1100`，使用返回的 session id 打开下列页面。尖括号替换为实际值，每条命令传同一 session。
+
+```sh
+bsk navigate http://127.0.0.1:4177/table.html --session <session> --json
+bsk observe --session <session> --json
+bsk screenshot --session <session> --out <临时目录>/table.png --json
+```
+
+4. 把窗口放前台，实际看到三列六行后再采集 observe。load 完成、AX 工具栏出现或背景占位截图都不能证明表格已经绘制。
+5. main 应有 Page action、Insert record、Filter 三个 DOM 控件，truncated=false，但无表格视觉入口。这是 PR 0 的缺口复现。
+6. 新实现应保留三个控件，并增加 visual ref。用本次返回的 ref 执行 `bsk screenshot --ref <ref> --session <session> --out <临时目录>/crop.png`，实际查看图片：包含 Canvas column A/B/C 和六行，裁剪对应 780×360 CSS px 的表格区域，不能错到工具栏或 iframe 边框。PNG 满足每边 2048、总像素 4,000,000 的上限。无需生成单元格语义。
+
+### 几何与动态场景
+
+PR 1 验证实际生产几何模块；PR 6 验证截图执行；PR 8 复验完整链路。未接 observe 时可注入人工 facts/ref，但必须调用实际模块，不能以独立 probe 代替实现测试。
+
+- 必测缩放集合：DPR 1/1.5/2 × top/frame；真实 UI zoom 100%/90% × top/frame；CSS zoom 1.25 的 top Canvas；frame scale 1.25 的 same/nested/OOPIF。按 PR 1 的坐标预期核对。OOPIF 需确认实际 iframe target，跨 origin 本身不够。
+- UI zoom 要通过浏览器菜单或原生快捷键确认，不能以 CSS zoom 或 pinch emulation 替代。旋转、mask、clip-path、活动 pinch、变换 overflow 按不支持策略降级，不输出猜测的精确 ref。
+- 使用 `index.html?noFrames=1` 的 `#plain`，每个实验从 reload 后的新 ref 开始：平移 1px、宽度改为 121px → 旧 ref 截图要求重新观察；移除节点或 document.open → 旧目标失效；仅重绘颜色 → 截图成功且是新颜色。不要在重新 observe 后拿重用的 eN 字符串声称验证了旧 ref。
+- visual ref 的 click/fill/hover/select/get_html/DOM 高亮拒绝测试只在合成页或自动测试运行，确认拒绝前没有派发输入、读 HTML 或高亮副作用。
+
+### 原始 iWiki（PR 0 与 PR 8）
+
+入口与就绪说明在本机临时文件 `/private/tmp/bsk-visual-design/private-reproduction.md`。文件丢失或登录失效时向用户取得入口/权限，说明这一项未完成；继续独立的合成验证。
+
+保持只读。前台实际看到表格后采集 observe 和截图：PR 0 确认缺口；PR 8 确认外围 DOM 控件仍在、新 visual ref 能截到实际表格。不要编辑单元格，不要求原页面永久维持历史的 63 个 ref。私有内容不入库。
+
+结束后停止自己的 session、服务器及临时 Chrome，恢复修改过的 zoom/emulation，不关闭其他任务资源。
+
+## 做完怎么回复
+
+直接告诉用户：验了哪个 PR、跑了什么、是否符合上述成功条件；若有失败或未做的检查，说明具体原因。必要时附关键测试输出或截图路径。无需单独报告文件、hash 清单、状态统计或全量日志归档；没运行、被跳过或受阻的项目不要写成通过。
@@ -0,0 +1,235 @@
+# Visual observation：PR 0 验证结果与架构决策
+
+日期：2026-09-08。生产基线：main `3c5f838`。分支：`codex/visual-observation-design`。
+
+本次只新增设计、合成 fixture 和诊断工具。没有生产算法变更，没有 commit/push。
+总体设计及后续 PR 依赖见 [架构与实施计划](visual-observation.md)。
+本文是历史证据；新会话请按 [验收清单](visual-observation-acceptance.md) 执行相关检查并说明结果，不继承本文的通过结论。
+
+## 1. 环境与证据等级
+
+| 环境 | 实际版本/说明 |
+|---|---|
+| PATH 中的 bsk | 0.1.7，未用于有效页面基线 |
+| 仓库已有 target/debug/bsk | 0.2.0；`update --check` 报告发布最新版也是 0.2.0，没有安装更新 |
+| daemon / connected extension | 0.2.0，protocol 1.1 |
+| 页面基线 Chrome | 151.0.0.0，由 bsk browsers 报告 |
+| 生产扩展构建 | `pnpm ext:build`，用户 reload 当前 main 基线构建后采集 |
+| 独立协议实验 Chrome | 152.0.7977.76，临时无登录 profile；与用户浏览器不是同一个运行实例 |
+| 基线测试 | VOM 47 tests / 2 files；相关扩展 217 tests / 14 files；全部通过 |
+
+页面结果是实际 bsk + reload 扩展的结果。协议实验是独立 Chrome 的真实 CDP 响应。
+临时 replay 是将合成响应送入 main adapter 的诊断，不代表另一条真实浏览器完整运行。
+不同证据不混用，版本号本身不证明构建 commit。
+
+所有内部页面原文、地址、iframe 标识、截图和用户信息仅保存在本机临时目录，不进入仓库。
+本文仅保存匿名化事实，仓库 fixture 完全独立构造。
+
+## 2. 原始问题已确认：表格加载完成后仍有观察缺口
+
+有效就绪条件：前台可见页面已经绘制出网格、列标题和六行表格。不能使用以下替代条件：
+
+- `document.readyState === complete`。
+- AX 已有嵌入应用的工具栏。
+- 页面出现 iframe。
+- 背景截图仍为站点加载 logo。
+
+本次初始后台窗口恰好出现“AX 已有工具栏，图像仍为加载占位”的情况。这些样本已排除。
+在前台绘制完成后重新取得匹配的截图和 observe，结果为：
+
+| 事实 | 结果 |
+|---|---|
+| 实际截图 | 可见列标题、网格与六行表格 |
+| main observe | 63 个 ref，含外围和嵌入应用工具栏 |
+| truncated | false |
+| 表格列内容 | 没有相应文本表示 |
+| visual ref | 没有 |
+| 直接打开已观察到的嵌入应用 | 发现一个无 aria-label 的 Canvas，CSS 尺寸 1450×835、backing store 2900×1670，DPR 2 |
+
+直接打开嵌入应用用于验证其渲染介质；其宽度变化是独立 tab 布局，不能拿这组坐标当父页面中的 crop。
+父页面的截图/VOM 对照与直接嵌入页的 DOM 证据分别记录。
+
+结论：主要能力缺口是视觉内容没有观察入口；不属于这次有效样本的文本预算耗尽。
+新架构不能承诺从 Canvas 自动恢复单元格语义；正确结果是保留工具栏，并提供可截图的区域入口。
+
+## 3. 合成最小复现
+
+`table.html` → 跨站点 `grid.html`：一个 iframe、DOM 工具栏、一个无名 Canvas。
+Canvas 绘制三列、六行，所有文字与原页面无关。
+
+main 实际输出的关键部分：
+
+```text
+@view 1440x923
+@e1 button "Page action"
+Iframe "Table application"
+  navigation
+    @e2 button "Insert record"
+    @e3 button "Filter"
+```
+
+`ref_count=3`，`truncated=false`。截图已人工确认包含 `Canvas column A/B/C` 和六行。
+这些像素文字既没有文本表示，也没有 visual ref。该最小复现已覆盖原场景的关键结构，
+无需站点权限或生产选择器。
+
+## 4. CSS 与语义/交互分离
+
+真实浏览器实验确认：
+
+- aria-hidden 祖先、inert 祖先、pointer-events:none 不会使 Canvas 自动视觉消失。
+- `visibility:hidden` 祖先下的 `visibility:visible` 子 Canvas 可以恢复可见。
+- `hidden` 元素被 `display:block` 覆盖时仍可绘制。
+- opacity:0 祖先会使子树透明；不能仅检查 Canvas 自己的 opacity。
+- display:none 无 layout bounds；visibility:hidden 可以仍有 bounds。
+- AX fallback 文本不包含绘制的 `PIXEL TABLE 42`，不能用 fallback 存在作为发现去重条件。
+
+决定：事实层分别保存 computed visibility、透明继承、语义暴露和交互属性。
+视觉发现不读取 semantic keep/drop 结果；祖先索引只能传播符合属性语义的状态。
+
+`checkVisibility()` 的实验作用仅限 CSS suppression，不用它证明 overflow、viewport 或遮挡结果。
+常规 overflow 由独立几何规则负责；任意遮挡不进入首版精确能力范围。
+
+## 5. 单位、frame 投影与截图
+
+### 5.1 DPR 与截图像素是不同契约
+
+独立 Chrome 上对相同 120×40 CSS clip 的结果：
+
+| Emulated DPR | DOMSnapshot Canvas w×h | Screenshot w×h | layoutViewport/cssLayoutViewport 宽度比 |
+|---|---|---|---|
+| 1 | 120×40 | 120×40 | 1 |
+| 1.5 | 120×40 | 180×60 | 1 |
+| 2 | 120×40 | 240×80 | 1 |
+
+因此该比值不能用作通用截图 DPR。原始 DOMSnapshot 单位与截图 raster scale 必须分别适配，
+输出 PNG 尺寸是最终预算事实。不能把本组 DPR emulation 结果泛化为所有浏览器缩放组合。
+
+### 5.2 三种缩放分别记账
+
+- CSS `zoom:1.25`：120px 宽 Canvas 的布局 bounds 为 150px，运行时几何同步变化。
+- Emulation.setPageScaleFactor(1.5)：记录为 page-scale/pinch 类证据，不充当 UI zoom。
+- 用户 Chrome 原生 UI 缩放到 90%：界面明确显示 90%，DPR 从 2 变为约 1.8，innerWidth 从 1440 变为 1600，visualViewport.scale 仍为 1；Canvas CSS 宽约 120.0000076，截图仍是 2880px 宽。main VOM 视口为 1600×1025。已恢复 100%。
+
+现有 bsk 的 Meta+- CDP 输入未改变浏览器缩放，所以该无效果尝试不算缩放验证；
+有效样本来自原生浏览器 UI 操作。真实 UI zoom 仅验证了上述点，不能宣称完整 zoom 矩阵已通过。
+
+决定：使用 CSS 视口空间作为发现/截图区域公共契约；精确单位 adapter 的实现还必须在 PR 1
+跑计划内组合回归，不用一个比例同时解决所有协议字段。
+
+### 5.3 Frame 空间与 main 已知偏移
+
+fixture local Canvas 原点为 (17,23)。
+
+| 场景 | 实测 owner content 原点（target root） | 正确 top Canvas 原点 | main parser replay |
+|---|---|---|---|
+| 同 target frame，10px border | (50,610) | (67,633) | (57,623) |
+| 上述 frame 内 nested，另有 7px border | (87,707) | (104,730) | (87,713) |
+| OOPIF，10px border | (410,610) | (427,633) | 本表不混入非完整 replay 的 OOPIF 结果 |
+
+根 target 的 DOMSnapshot 含三份 document（top/same/nested）；OOPIF 在单独 target 中只返回自己的 document。
+probe 通过实际 `TargetInfo.type=iframe` 验证 OOPIF，而非仅根据 origin 推断进程隔离。
+
+子 frame scrollY=10 后，runtime local y 从 23 变为 13，snapshot document y 仍为 23。
+owner scale(1.25) 后 content quad 宽度变为 375，child innerWidth 仍为 300。
+
+决定：frame-local 原始矩形必须先减该 document 的滚动，再经过一次权威投影；同 target 的
+owner quad 已是 target-root 坐标，不能重复逐层加偏移。禁止 border-box 替代 content origin。
+
+Box 种类也必须进入契约：带 5px border 的 120px Canvas，其 snapshot/border quad 宽 130，
+content quad 宽 120。视觉入口采用 border-box，实时验证同种 box；iframe 投影则采用 content quad。
+带 border/padding 的 overflow owner，snapshot.clientRects 对应 `[clientLeft,clientTop,clientWidth,clientHeight]`，
+本 fixture 为 `[5,5,68,38]`。裁剪边界应从 client box 派生，不能直接拿 ancestor border bounds。
+单轴 `overflow-x:clip;overflow-y:visible` 的 computed style 保持分轴，必须分轴传播。
+
+CSS zoom 1.25 后，上述 owner 的 bounds 变为 `[745,455.625,97,59.5]`，clientRects 仍为
+`[5,5,68,38]`，offsetRects 为 `[596,365,78,48]`。直接按 border-width 比例推导 client box
+会混入不同空间与整数取整。首版将有 CSS zoom/DOM transform 的 overflow 祖先组合明确降级，
+不承诺精确 crop；普通未变换 overflow 及 iframe content-quad 投影保留支持。
+
+## 6. Document 与 ref 时效
+
+真实 CDP 实验：
+
+| 操作 | frameId | loaderId | document backend | anchor |
+|---|---|---|---|---|
+| history.replaceState | 不变 | 不变 | 不变 | 仍属于当前树 |
+| 跨 document 导航 | 不变 | 变化 | 变化 | 旧目标不可继续视为当前内容 |
+| document.open/write/close | 不变 | 不变 | 本次实验不变 | 旧 Canvas 失去连接，documentElement 被替换 |
+
+决定：身份取 target attachment epoch + frameId + loaderId + documentElement backend identity；
+工具执行时仍检查 anchor.isConnected 及其所属 documentElement。不能仅凭 loaderId 判断有效。
+DOMSnapshot 可提供根元素 backend identity，frame graph 需要保留 loaderId；当前 main graph
+没有该字段，这是后续数据契约的明确修改点。
+
+12 次静态几何采样完全相同；0.5px 移动可被检测；真实 90% 缩放引入约 1e-5 CSS px 的
+数值误差。首版采用最大边误差 0.25 CSS px 作为保守工程阈值，超出要求重新 observe。
+这不是大规模统计得到的通用稳定性保证；改变阈值需更新其测试及行为文档。
+
+既有 eN 被下一次观察重用后，单靠旧字符串不能检测它来自上一代。内部 generation 不消除
+该协议限制。本次不改变协议，只验证当前存储目标的身份/几何。Canvas 可以在身份与几何
+不变时重绘；截图始终表达执行时图像，不承诺观察时像素快照。
+
+## 7. 既有路径回归基线：用于防止负优化
+
+诊断复制当前 renderer 到临时目录，在三个明确循环点加计数；生产文件未改变。
+复现命令见 [fixture README](../../apps/extension/test-fixtures/visual-observation/README.md)。
+
+| 输入 | Render stack visits | DOM context candidates | Same-container sibling visits |
+|---|---:|---:|---:|
+| 100 headings + 100 View buttons | 201 | 10,000 | 15,050 |
+| 200 headings + 200 View buttons | 401 | 40,000 | 60,100 |
+| 400 headings + 400 View buttons | 801 | 160,000 | 240,200 |
+| 2,000 transparent wrappers + control | 2,001 | 0 | 0 |
+| 4,000 transparent wrappers + control | 4,001 | 0 | 0 |
+
+显式栈访问线性并通过深树输入；本组宽树上下文计数呈二次增长。这里记录的是现有路径的
+特征，供后续同输入比较是否发生回退，不是本次要求修复的问题，也不是 Canvas 新算法的模板。
+计数不是完整 CPU profile，更不能替代 Canvas 发现、裁剪、选择和截图各自的性能测试。
+
+处理边界：
+
+1. 既有语义、DOM 操作和截图路径对照 main 不发生性能回退；不把历史算法优化列为本次前置依赖。
+2. Canvas 新路径按自己的规模和访问模式论证算法；发现、裁剪、去重、选择和截图分别验收。
+3. 精确 crop key 去重的选择来自首版的覆盖等价契约和新增成本分析，与 #165 采用什么算法无关。
+4. PR 7/8 分别报告既有路径回归、无 Canvas 页面的额外成本、有 Canvas 页面的新增成本。
+   新功能有合理的额外成本不等于旧算法负优化；重复执行旧工作则属于需要消除的回退。
+
+## 8. 锁定首版策略与退化
+
+| 决策 | 首版契约 | 理由/验收 |
+|---|---|---|
+| 去重 | 同 document + 同直接 parent + 四条 crop 边完全相等 | 无模糊聚类；误差导致重复比误合并更可控 |
+| 索引容量 | 50,000 keys；耗尽后其余候选继续未去重选择 | 内存有界，不因早期小图耗尽而停止后续发现 |
+| K | min(预算推导容量, 512) | 所有行仍逐条核算可变成本 |
+| 默认视觉预算 | 未给总 maxTokens 时 2048 estimated tokens | 有显式 maxTokens 时全部纳入同一预算 |
+| 摘要预留 | 固定提示行按实际估算器成本预留 | 不用不可验证的固定 token 常量表示某段文本 |
+| 几何时效 | 最大边差 > 0.25 CSS px 即重新观察 | 身份和裁剪策略变化独立拒绝 |
+| 图像 | max edge 2048、max pixels 4,000,000、最多两次 capture | 成功必须以实际尺寸满足后置条件 |
+| 外部几何并发 | 4 | 单操作缓存；操作结束释放 |
+| 新增纯计算取消 | 每 256 项形成工作块并让出事件循环 | 不仅是轮询无法及时更新的 signal |
+
+这些数值是可审查的首版资源政策，不是声称已证明用户体验最优的测量结果。
+参数可以在对应模块 PR 中经新的证据调整，但必须一并更新契约及测试。
+
+进一步收敛：首版精确区域支持轴向矩形、普通 overflow 链、正向轴对齐平移/缩放与 frame。
+旋转、透视、clip-path、mask、活动 pinch-zoom 进入明确的 geometry-unsupported 降级，
+不给看似精确的 region ref，提示现有视口截图途径。不会把包围矩形偷换成精确区域。
+
+## 9. 已执行的检查与下一阶段门槛
+
+已执行：
+
+- main VOM tests：47 passed。
+- main 相关 extension tests：217 passed，含 frame/element geometry、observation、interaction、ref-store、VOM。
+- `pnpm ext:build` 成功，用户 reload 后采集有效页面基线。
+- 独立 Chrome browser contract probe：39 个断言通过；可复现命令见 fixture README。
+- main 合成 capture replay、显式栈/上下文操作计数。
+- 实际 Chrome UI 90% zoom 样本，恢复 100%。
+- 原始表格与合成嵌入式表格均人工查看截图，并与未截断 observe 对照。
+
+PR 0 交付的是已明确边界的设计和基线，不是未来功能已经通过：新的 discovery、typed ref、
+freshness resolver、pixel planner 和 renderer 接线尚未实现。后续每个 PR 必须验证自己的
+生产实现，不能把本次浏览器事实验证替代实现验收。
+
+人工证据不设置默认 CI 对内网站点的访问依赖。合成 probe 可按需执行；页面原文不进仓库。
+后续 PR 的职责和验收保持在主设计中，本文负责记录证据、决策及没有作出的保证。
@@ -0,0 +1,675 @@
+# BrowserSkill 视觉观察：架构设计、边界约束与 PR 实施计划
+
+> 日期：2026-09-08  
+> 状态：PR 0 设计验证稿；基线、浏览器实验和参数决策见 [验证结果](visual-observation-evidence.md)。生产实现尚未开始。执行步骤和成功条件见 [验收清单](visual-observation-acceptance.md)，无需另写报告。  
+> 实施基线：从实施时确认的 main 新建分支；本次分析使用本地 main `3c5f838`。  
+> 参考材料：当前 `fix/vom-canvas-observation` 分支、PR #165、此前的 visual-surface 架构蓝图。旧实现和旧测试是证据来源，不是不可改变的规格。  
+> 本次范围：设计规格及可复现的合成 fixture/诊断工具；不修改生产代码，不继承旧分支提交。
+
+## 1. 设计结论
+
+本次工程的目标是：
+
+**为 VOM 建立独立的视觉观察通道，共享可靠的采集与几何基础，通过明确的区域身份提供截图能力，并使处理成本随输入规模可预测增长。**
+
+工作方式是先确定整体架构、行为契约、模块依赖、复杂度和验收矩阵，再分 PR 实现。分步实现不等于分步思考架构。任何实现阶段需要改变已定契约时，必须先更新设计及相关验收项，不得用局部特殊分支掩盖契约冲突。
+
+本次不是一次目录整理，也不是通用视觉理解平台重写。设计完整覆盖当前能力的生命周期，但不为尚无需求和证据的未来能力预建实现。
+
+### 1.1 必须成立的五个结果
+
+1. observe 能表达“这里存在需要看图理解的 Canvas 内容”，不依赖该元素是否有可用 AX 语义。
+2. 视觉入口的 document、frame、target、节点及坐标归属明确。
+3. 视觉 ref 与 DOM 操作 ref 具有明确且不可矛盾的工具契约。
+4. 截图解析当前目标并验证时效，返回浏览器最终合成的当前图像及真实尺寸。
+5. 采集、索引、发现、选择、输出和截图均有复杂度或资源上限，并从首个实现 PR 开始验证。
+
+### 1.2 不能用来证明成功的指标
+
+- 代码文件拆得更多。
+- 旧分支全部测试通过，但没有重新审核测试中的行为假设。
+- 能识别某个特定 嵌入式 Canvas 表格 页面，却依赖站点 class、URL 或布局常量。
+- 单个简单页面运行很快，但没有最坏输入分析。
+- 文本出现 surface 标记，但其截图对应关系、时效和工具限制没有验证。
+
+## 2. 问题本质与现状
+
+### 2.1 main 的基础能力
+
+当前 main 的主要路径为：
+
+```text
+DOMSnapshot + 各 frame 的 AX
+  → FrameDocument
+  → semantic graph：构建、解析、结构整理
+  → VomScene
+  → VOM 文本及 DOM ref
+```
+
+已经存在 frame document、语义图、几何模块、ref store、截图路径和显式栈渲染器。应复用这些职责，不在旁边建立第二套长期运行的采集、frame traversal 或语义树。
+
+缺口是：元素的 DOM/AX 描述不等于 Canvas 内部的文字、图形和布局。补 role、名称或普通可点击 ref，并不能建立完整的视觉观察能力。
+
+### 2.2 必须分别解决的问题
+
+| 问题 | 要回答的具体问题 | 不属于该问题的内容 |
+|---|---|---|
+| 视觉发现 | 哪些 Canvas 构成可观察候选？ | 它是否可点击、输出多少条 |
+| 空间定位 | 候选在顶层视口的区域是什么？ | 它是否重要、属于哪个业务画布 |
+| 输出选择 | 有限预算下展示哪些入口？ | 改写几何事实、推断业务实体 |
+| ref 身份 | 入口绑定什么目标、允许哪些工具使用？ | 像素缩放、内容识别 |
+| 时效验证 | 当前目标是否仍符合此次观察契约？ | 保证 Canvas 像素未发生重绘 |
+| 图像获取 | 如何获取当前合成区域并限制成本？ | 重建 Canvas 内部对象 |
+
+### 2.3 当前分支值得保留与需要重审的部分
+
+值得保留：语义/视觉双通道、视觉附录、单节点截图锚点、frame 几何共享、像素预算、相关失败场景和 fixture。
+
+需要重审：
+
+- 将 `aria-hidden`、`inert` 与视觉隐藏合并排除。语义暴露、交互资格、视觉存在是不同维度。
+- 将旧区域与实时区域的交集当作时效验证。区域重合不能证明目标仍对应原观察。
+- 将几何重合和共同父节点解释成逻辑画布身份。
+- 将名称有无作为重要性的绝对优先条件，可能让大量有标签的小图排在无标签主画布之前。
+- 视觉附录依赖 DOM 渲染后的剩余预算，可能使视觉通道完全消失。
+- 在每个候选上重复祖先遍历，或假设引入空间索引便自动消除了最坏二次复杂度。
+
+PR #165 优化了既有渲染及上下文查询路径。本次将它作为性能回归保护基线，不作为 Canvas 算法模板，也不据此要求重做原有算法。Canvas 的发现、裁剪、选择和截图具有不同的数据规模与访问模式，应分别设计和验证适合自己的算法。
+
+PR 0 已在用户指定页面确认：表格实际绘制后，main 输出外围工具栏而没有表格列内容及视觉入口，且未截断。直接打开嵌入应用确认存在无标签 Canvas。内部页面资料仅留临时目录；入库使用匿名化结论和独立合成 fixture。
+
+## 3. 范围收敛
+
+### 3.1 本次纳入
+
+- Canvas 元素锚定的视觉观察入口。
+- 顶层、同 target 子 frame、OOPIF 及嵌套 frame 的身份和坐标归属。
+- 已明确支持的视口及 overflow 裁剪。
+- 无标签、存在 AX、不可交互但有视觉内容等候选情况。
+- 有界输出选择及保守的重复截图入口去重。
+- 视觉 ref 的工具契约和 document/几何时效检查。
+- 截图区域解析、像素预算、真实输出尺寸验证和有界重试。
+- 深层 DOM、密集小图、重叠 Canvas 和多 frame 的性能约束。
+
+### 3.2 本次不纳入
+
+- OCR、图像语义识别、Canvas 内部对象树。
+- 画布内部点选、拖拽或内部对象 ref。
+- 地图 tile 拼接、跨节点逻辑画布聚合、多 anchor 区域。
+- 面向所有 SVG、视频、CSS 背景等介质的通用发现插件系统。
+- 任意页面遮挡、透明度、clip-path 和 mask 的精确像素级重建。
+- 改写所有现有语义算法、表单、hover probe 或 recording 协议。
+- 新的 ref 字符串协议、跨 observe 持久对象 ID、分页接口。
+
+边界外的能力可以提出独立设计，不能通过放宽当前去重阈值或给单节点 target 塞可选字段实现。
+
+## 4. 总体架构
+
+```mermaid
+flowchart TD
+    Browser[浏览器 / CDP] --> Capture[CaptureCoordinator]
+    Capture --> Batch[RawCaptureBatch]
+    Batch --> Geometry[GeometryContext]
+    Batch --> Normalize[Normalize + DocumentIndex]
+    Geometry --> Normalize
+    Normalize --> Facts[ObservationFacts]
+    Facts --> Semantic[现有 SemanticPipeline]
+    Facts --> Discover[VisualDiscovery]
+    Discover --> Candidates[VisualCandidates]
+    Semantic --> SemanticScene[SemanticScene]
+    Candidates --> Select[VisualSelection]
+    SemanticScene --> Context[输出上下文 / 活跃层策略]
+    Context --> Select
+    SemanticScene --> Renderer[ObservationRenderer + BudgetPlan]
+    Select --> Renderer
+    Renderer --> Output[文本 + Typed Ref Descriptors]
+    Output --> Registry[RefRegistry]
+    Registry --> Resolve[当前目标及区域解析]
+    Browser --> Resolve
+    Resolve --> Pixel[PixelPlanner]
+    Pixel --> Shot[CaptureExecutor]
+    Browser --> Shot
+```
+
+### 4.1 架构原则
+
+1. 共享事实，分开解释。视觉存在不复用语义节点的保留/排除结论。
+2. 语义关系是视觉区域的可选上下文，不是视觉身份的根。
+3. 几何只有一套解释和投影实现，观察与工具执行使用不同生命周期的上下文。
+4. renderer 只处理数据；浏览器调用止于采集或工具执行边界。
+5. 预算选择只影响输出，不回写采集事实。
+6. ref 的 kind 决定工具适用性，不能由调用者传入另一份可矛盾能力数组。
+7. 模块失败必须可归因；不能将“没有候选”与“采集失败”混为一谈。
+8. 所有资源限制都具有可解释的退化行为，不只是一句“超过上限停止”。
+
+## 5. 模块划分与实现位置
+
+以下为目标职责和建议位置，不要求第一个 PR 搬动全部文件。迁移文件与修改算法尽量分开；模块完成切换后删除被替代路径。
+
+```text
+apps/extension/src/tools/
+  observation.ts                    # 工具入口与结果接线，逐步减去内部实现
+  observation/
+    capture-coordinator.ts          # CDP 编排及批次生命周期
+    capture-types.ts                # 原始批次、归属、阶段状态
+    normalize.ts                    # 原始节点 → 归一化事实
+    document-index.ts               # 按 document 建立共享索引
+    facts.ts                        # 下游可读事实契约
+  geometry/
+    coordinate-types.ts
+    frame-context.ts                # frame/target 投影权威入口
+    primitives.ts                   # 复用/迁入现有数学实现
+  vom/
+    capture.ts                      # 保留或拆出的 DOMSnapshot adapter
+    frame-document.ts               # 复用现有 frame 归属逻辑
+    semantic-graph/                 # 保留语义职责
+    visual/
+      types.ts
+      discovery.ts
+      selection.ts
+      coverage-dedup.ts
+  refs/
+    target.ts
+    resolve.ts
+  screenshot/
+    resolve-region.ts
+    pixel-plan.ts
+    capture.ts
+
+apps/extension/src/session-manager/
+  ref-store.ts                      # session 生命周期与注册存储
+
+packages/vom/src/
+  types.ts                          # 纯场景及渲染契约
+  render.ts                         # 保留显式栈语义遍历
+  render-budget.ts                  # 唯一输出预算核算
+  visual-appendix.ts                # 纯数据视觉条目输出
+```
+
+不同时保留旧 `geometry.ts` 与新 primitives 的两套数学实现。上述目录可按现有工程规范调整，但职责与依赖不得随意调整。
+
+### 5.1 CaptureCoordinator
+
+输入：tab/target、已验证的 URL、取消信号、采集选项。  
+输出：带来源、时间范围、document 身份和阶段状态的 RawCaptureBatch。
+
+- 按 target 分组采集；DOMSnapshot 每 target 一次成功采集，重试单独计数且有界。
+- AX 按协议支持的 frame/target 组织，数量有预算。
+- 原始采集完成后才能运行会改变页面状态的 hover probe，保留已有行为顺序。
+- 明确记录无法采集的 frame，不能把失败 frame 的数据借用其他 target 补齐。
+- 不判断 Canvas 重要性，不投放 ref。
+
+批次是来源和生命周期边界，不是浏览器原子事务。`Readonly` 或冻结对象不能证明各 CDP 响应来自同一瞬间。遇到可检测的导航/document 更换时应中止或有界重采集，不能拼接不同 document 的数据。
+
+### 5.2 GeometryContext
+
+输入：该次操作的 frame graph、原始 metrics、按需取得的 owner quad。  
+输出：frame-local/target-local 到 top-viewport 的投影、裁剪及当前节点区域解析。
+
+- 坐标类型同时携带空间及所属 frame/target；仅标记 `frame-local` 不足以防止错 frame 使用。
+- 原始 DOMSnapshot 单位、CSS 视口单位、截图像素单位分别适配。
+- Canvas 视觉入口采用元素 border-box 的可截图区域；实时解析明确请求同一种 box，不能沿用默认 content-quad 路径再将边框差异误判为移动。iframe 子视口投影仍采用 owner content quad，两者职责不同。
+- 普通 overflow 裁剪使用 ancestor client/scrollport box，不使用祖先 border bounds。adapter 保留 includeDOMRects 的 client offsets/size 及其单位；存在缩放时先转换到相同坐标空间，禁止直接相加不同单位。证据不足时明确降级，不猜测 border/padding 常量。
+- 一个操作内复用 metrics、owner quad 和 projection promise；不跨 observe 或 tool execution 复用 live geometry。
+- 合成变换可以预计算；裁剪边界复杂度须真实计入，不能靠 promise cache 就宣称全部计算线性。
+- 不允许通过 iframe border box 加减常量替代有证据支持的 content geometry。
+
+### 5.3 Normalize / ObservationFacts / DocumentIndex
+
+输入：原始批次及几何上下文。  
+输出：按 document 隔离的只读事实和有界共享索引。
+
+- Raw node 不能含语义不明的 top rect；normalized node 的派生字段由 normalization 创建。
+- 节点 key 包含 document/target 所属信息，不能仅用 backendNodeId 跨 target 建表。
+- 建立 node lookup、parent/children 等基础索引；派生索引必须有明确消费者和复杂度。
+- 用显式栈和 visiting/visited 状态处理任意深度及异常环。
+- orphan 保留“祖先信息不完整”状态；可以在已知范围内生成保守候选，但不能伪装成完整裁剪证据。
+- 视觉样式、AX 暴露、交互资格分开保存，禁止万能 `excluded` 字段承载全部规则。
+- 不给每个节点复制完整祖先数组或完整裁剪链；必要时共享结构或按需解析，计入内存预算。
+
+### 5.4 SemanticPipeline
+
+消费归一化事实，输出现有语义场景。通过窄 adapter 接入新事实契约；迁移完成后删除不再需要的 adapter。
+
+- 不因为视觉发现需求改变 semantic keep/drop、名称恢复或可交互推断规则。
+- 不把视觉候选塞回语义树遍历。
+- PR #165 的显式栈、上下文索引及行为回归保留。
+- 偶然发现的既有语义性能问题只作范围外记录，不构成本次工作项或前置依赖。本次只要求不使原有路径发生性能回退。
+
+### 5.5 VisualDiscovery
+
+输入：ObservationFacts。  
+输出：候选及发现状态，不含最终 ref，不依赖 token 预算。
+
+候选表达一个 Canvas 节点锚定的截图区域。必须具有可解析地址、支持范围内的几何证据和非空候选区域。
+
+- 无 label 不排除；有 AX 内容也不能证明像素内容已被完整描述。
+- `aria-hidden`、`inert`、`pointer-events:none` 不单独构成视觉排除原因。
+- 零尺寸、无渲染区域、已证实的完全透明/隐藏、支持范围内的完全裁剪可排除。
+- `visibility` 等继承与覆盖行为必须按实际 CSS 语义处理，不能把祖先 hidden 一律不可逆传播。
+- `hidden` 等属性不应替代最终渲染事实；存在特殊状态时按实验确认的规则处理。
+- agent 自身 overlay 排除应按所属 document/target 传播。
+- 常规轴向 overflow 累积在一致的坐标空间计算；变换后不能把 top-space 包围矩形当作精确 local-axis clip。
+- 不重建任意遮挡。几何区域是截图候选范围，不保证范围内每个像素均来自该 Canvas。
+
+### 5.6 VisualSelection / CoverageDedup
+
+输入：候选、输出上下文及预算规划所需参数。  
+输出：选中候选、明确的遗漏/退化状态。
+
+- 默认以区域覆盖量等可解释几何依据排序；label 是命名事实，不作为压倒面积的优先条件。
+- 活跃层优先级属于选择策略；被降低优先级不等于物理不可见。
+- 排序键预计算；同层按可见面积降序，再按 frameId、top y、left x、backendNodeId 升序决定顺序。字符串按代码单元字典序、数值按数值比较；同一精确去重组取该顺序最小者。不把跨批次 backend id 稳定性作为保证。
+- 去重只减少重复截图入口，不产生新的 logical surface。
+- 首版仅在同 document、同直接 DOM parent、四条裁剪边数值完全相同的候选之间去重，使用精确 key 的 Map；不使用近似 IoU、尺寸 band 或空间邻居比较。亚像素不同的范围保留独立入口。
+- 首版不输出无法证明的 `layers=N` 业务解释。去重成员只是覆盖证据，不是内部对象模型。
+- 精确去重索引达到 50,000 个 key 后，剩余候选以未去重形式继续进入有界选择，记录去重退化；不得直接丢掉剩余区域。索引已知 key 仍可命中去重。
+- 即使没有去重，top-K 选择和总输出成本也必须有界。
+
+### 5.7 ObservationRenderer / BudgetPlan
+
+输入：SemanticScene、视觉选择结果和输出预算。  
+输出：文本及与已提交行严格对应的 typed ref descriptors。
+
+- 唯一模块核算总文本预算；摘要、头部、条目和截断提示全部计入。新 observe 的统一账本为每个实际输出行分别 `ceil(line.length / 4)` 后求和，length 使用 JavaScript UTF-16 单位；不混用整段核算与逐行核算。
+- 保留语义显式栈和 DOM ref 相对顺序；视觉条目在语义阶段之后提交。
+- 有视觉候选时，规划阶段预留简短视觉提示；其余视觉条目使用明确分配的剩余预算。
+- 极小预算不保证语义与视觉同时完整，必须产生确定的截断结果。
+- 写入行与提交 ref 在逻辑上原子：未写入的条目不能留下可解析 ref。
+- 使用既有 token 估算方法时，预算表示“估算 token 上限”，不能宣称精确模型 tokenizer 上限。
+- 新 observe 预算规划若发现显式预算不足以容纳最小协议头，返回 insufficient-budget，由工具层映射为既有 invalid_params，附最低估算成本；不生成半截协议头或新 ref。snapshot 的旧预算语义不在本次顺带改变。这是 observe 极小预算的明确兼容性例外。逐行统一账本也可能改变临界预算的截断位置；足够预算下无 Canvas 的语义文本及顺序保持不变。
+- 首版固定视觉提示为 `[visual] Canvas regions present; use screenshot`，成本由同一估算器计算。有候选但条目不足时仍尝试保留提示；连提示也容不下则只返回合法的截断语义输出，truncated=true。未知计数不伪装成精确遗漏数。
+- 输出标签最多 160 个 Unicode code point，再经 JSON escaping 与整行成本核算；排序不依赖标签长度。原始采集输入量 B 仍单独计入，不因输出裁剪便宣称采集内存有界。
+- `snapshot` 继续使用既定静态语义输出；新视觉入口首先仅接入 `observe`。不要顺带改变 recording/其他调用方默认选项。
+
+### 5.8 RefRegistry / Resolve
+
+保存 session/tab 隔离的目标描述。DOM 与视觉目标通过判别联合区分；kind 为权威，外部展示能力可从 kind 派生。
+
+```ts
+// 概念契约，具体类型名与仓库适配时确定。
+type RefTarget =
+  | { kind: "dom"; address: NodeAddress }
+  | {
+      kind: "visual-region";
+      anchor: NodeAddress;
+      observed: ObservedGeometry;
+      observationId: ObservationId;
+    };
+
+// NodeAddress 必须能表示 tab、CDP target、frame、document 身份及 backend node。
+// 坐标值同时保留所属空间及 owner，不使用无归属 Rect 穿越模块边界。
+```
+
+工具适用性：
+
+| 消费入口 | DOM ref | Visual ref |
+|---|---|---|
+| screenshot | 维持既有 DOM 截图策略 | 使用视觉区域策略 |
+| click/fill/hover/select 等 | 维持既有检查 | 拒绝，且拒绝发生在派发输入前 |
+| get_html | 维持既有行为 | 拒绝；不隐式降级为 anchor 的 HTML |
+| 人工帮助定位 | 维持既有行为 | 若当前入口必须解释为 DOM 目标则拒绝；未来支持视觉区域需另立契约 |
+
+所有 ref 消费者都必须通过类型化 resolver，不能依赖调用者记得传可选 capability 参数。
+
+现有 `eN` 重用存在明确限制：如果新的 observe 已将 `e1` 重新绑定，单凭客户端传来的旧字符串 `e1` 无法判断它来自上一代。内部 generation 不会自动解决该问题。观察身份采用 target attach epoch + frameId + loaderId + documentElement backend identity，并在执行时验证 anchor 仍连接到匹配的 documentElement；loaderId 单独不足以覆盖 document.open。
+
+本次保留当前“最新观察映射”的外部语义；只承诺能检测当前已存条目的 document/节点/几何失效，不承诺识别所有跨代旧字符串。彻底解决需独立协议设计。
+
+### 5.9 ScreenshotExecution
+
+分成三部分：
+
+1. `resolve-region`：按目标种类解析当前身份与几何、验证 document 和区域变化。
+2. `pixel-plan`：纯数值函数，输出 clip scale 等计划。
+3. `capture`：overlay suppression、CDP 截图、真实尺寸读取、有界重试、取消及 dialog 集成。
+
+- Visual ref 不自动滚动，不通过旧、新区域交集掩盖位移。
+- 首版对超过既定容差的位移、尺寸或裁剪变化返回“需要重新观察”；容差在 PR 0 由测量误差证据锁定。
+- 截图返回执行时浏览器最终合成图，不是观察时像素快照。
+- document 身份验证不能替代几何验证；几何相同也不能证明 Canvas 内容未重绘。
+- 像素规划采用明确 metrics 适配值；真实 PNG 尺寸是输出预算后置条件的依据。
+- 尺寸头校验不宣称完整 PNG 内容验证；缺失/不合法数据与预算超限分开归因。
+- 成功返回必须满足像素上限；有界重试仍失败则返回失败，不能猜测尺寸或无界重拍。
+
+## 6. 算法与资源预算
+
+### 6.0 两类独立的性能责任
+
+**既有路径：防止回退。** 在相同输入、选项和环境下对照 main，检查原有语义处理、DOM ref、普通交互与截图的工作量、内存和实际耗时。不得因接入 Canvas 而重复运行语义解析、重建已有索引、增加原有节点的上下文查询，或撤销 #165 的优化。本次不要求把既有算法统一改成某个复杂度。
+
+**新增路径：独立设计。** 围绕 Canvas 数量、frame 数量、裁剪复杂度、输出预算及截图像素量分析新成本；不照搬旧 renderer 的算法，也不以“旧算法使用了索引/显式栈”代替新问题的算法论证。下文复杂度与资源要求约束新增或本次实际改动的职责。
+
+性能验收分三组，分别报告，不能互相替代：
+
+| 验收组 | 对照方式 | 必须说明的结果 |
+|---|---|---|
+| 既有语义/操作路径 | 同一输入在 main 与新分支运行，隔离新增视觉工作 | 既有阶段未引入额外遍历、重复请求或可归因的性能回退 |
+| 无 Canvas 页面 | 实际完整 observe 对照 | 仅保留必要的候选检测开销；确认无候选后不建视觉索引、不执行视觉几何查询或截图 |
+| 有 Canvas 页面 | 单独测量视觉各阶段，再测完整 observe | 新成本与 C/F/P/K/像素等规模相符，资源有界；不把合理的新功能成本误记为旧算法退化 |
+
+实际耗时需要多次同环境对照并结合操作数判断，不能仅凭一个容易波动的耗时值下结论。新增字段采集或共享模块调整的额外开销也必须归因并报告，不能藏在“原有成本”中。
+
+### 6.1 规模定义
+
+| 符号 | 含义 |
+|---|---|
+| B | 原始协议数据及字符串总量 |
+| N | 采集 DOM 节点数 |
+| A | AX 节点数 |
+| F / T | frame 数 / CDP target 数 |
+| C | 视觉候选数 |
+| K | 最大选中输出条目数 |
+| Q | 去重实际候选比较次数 |
+| P | 几何计算量，如顶点处理、裁剪操作总数 |
+| H | 语义上下文查询实际处理的数据总量 |
+| L | 最终输出文本长度 |
+
+不能忽略 B、P、H 后笼统宣称整个管线 `O(N)`。原始数据解码至少与输入量相关，复杂裁剪和语义上下文的总成本需要显式计算。
+
+### 6.2 模块性能契约
+
+| 阶段 | 复杂度/上限目标 | 禁止的实现 |
+|---|---|---|
+| 原始解码 | 与 B 线性相关 | 为每个节点重新解码共享列或字符串 |
+| 文档索引 | `O(N + A + F)`，不含协议字节解码 | 每个候选全文扫描 |
+| 可合成祖先状态 | `O(N)` 建立，候选常数次查询 | 每 Canvas 完整祖先 walk |
+| Frame 几何 | 变换/证据按 frame 复用，额外成本计入 P | 每 node 查询 metrics/quad |
+| 发现 | 索引后 `O(C)`，额外几何成本计入 P | 发现函数内重新查 CDP |
+| top-K | `O(C log(K+1) + K log(K+1))` | 无需要地重复全量排序 |
+| 去重 | 精确 key Map，摊销 O(C)，索引至多 50,000 个 key；首版 Q=0 | 引入模糊匹配和同 bucket 两两比较 |
+| 新增视觉渲染与既有渲染接线 | 新增工作按选中条目及 L 核算；既有 H 对照 main 不回退 | 为视觉条目重新执行语义遍历或扫描全部节点 |
+| 截图 | 调用和重试次数有界，成功图像像素数有界 | 无限重试、猜测输出尺寸 |
+
+K 从预算允许的最小条目成本推导，并受异常安全上限约束；实际每行仍核算成本。面积优先 top-K 不应被描述为严格求解“可变长度条目预算最优装包”，本次不实现此类优化问题。
+
+### 6.3 首版资源参数及锁定规则
+
+以下是 PR 0 锁定的首版策略参数。它们是有明确退化语义的工程预算，不是性能最优值的统计结论；调整须更新对应契约测试：
+
+- Visual 截图最大边：2048 px；最大面积：4,000,000 pixels。
+- 单次视觉截图最多 2 次 capture 尝试。
+- Frame 几何外部请求最大并发：4。
+- K 异常安全上限 512；正常数量由预算与条目成本决定。
+- 几何变化阈值：top-viewport CSS px 的四条边最大差值超过 0.25 即要求重新 observe；document、anchor、裁剪策略改变不受该容差豁免。
+- 没有显式 maxTokens 时，视觉通道估算 token 预算 2048；有显式预算时，优先为固定摘要行按当前估算器计算实际预留量，条目用剩余预算，全部计入同一总预算。
+- 精确覆盖去重索引最多 50,000 个 key；耗尽后继续未去重 top-K，标记 dedup-degraded；不得停止扫描剩余候选。
+- 新增纯计算阶段每 256 个节点/候选形成可取消工作块；需要实际让出事件循环，而不是只读一个尚无机会更新的 AbortSignal。
+
+每个限额均须有单位、适用阶段、计数口径和耗尽行为。数字集中在所属模块策略配置中，不散落为多个含义相近的常量。若 PR 0 未锁定参数及退化契约，对应实现 PR 不得以随意常量合入。
+
+### 6.4 性能测试方法
+
+- 节点访问、祖先推导、候选比较、CDP 请求数、最大并发及中间集合大小均做可断言计数。
+- 对新增树处理使用深树/宽树测试，证明无调用栈溢出或重复全量扫描；既有 renderer 的对应输入用于 main 前后回归对照，不要求本次消除其历史复杂度。
+- 规模翻倍时检查操作数增长是否符合分析，避免只看一次墙钟时间。
+- 精确去重索引至少测试：全部重合、亚像素差异、同 crop 不同 parent、全部互不相交、容量耗尽；未来若引入空间索引，必须另增退化测试。
+- 大量有名小图与无名主画布并存，验证排序不会因标签策略丢失主要区域。
+- 保留 #165 回归；为新增模块增加性能契约，而不是声称旧测试覆盖整个链路。
+- 真实耗时基准用于观察额外成本和实际收益，需记录环境；不使用耗时阈值代替算法验证。按验收清单的性能步骤 预热 3 次、交替采样 20 次，分别报告旧阶段和新增成本；旧阶段中位数增加超过 max(基线 10%, 2ms) 时独立复测，两轮均超过且可归因于改动则 FAIL，无法排除噪声则 BLOCKED。
+
+## 7. 失败、降级与一致性
+
+内部状态至少区分：
+
+```text
+capture-unavailable
+document-changed
+frame-ownership-unresolved
+geometry-unavailable
+geometry-unsupported
+outside-supported-clip
+discovery-partial
+selection-truncated
+dedup-degraded
+target-detached
+geometry-changed
+image-invalid
+pixel-budget-exceeded
+```
+
+这些是内部分类，不要求逐项扩展外部 RPC code。外部沿用既有错误分类并给出准确 message/必要 detail；不可把所有时效或几何失败叫权限问题。
+
+原则：
+
+- 视觉分支失败不应使已获得的语义结果无故丢失。
+- 没有候选、没有预算、没有采集成功必须可区分。
+- exact omitted count 只在可计算时输出；原始候选数与去重后的区域数不能相加冒充精确数量。
+- 捕获批次不保证页面静止；可检测的身份变化必须处理，不可检测的像素重绘不作虚假保证。
+- 取消在阶段边界和有界工作块之间检查，不能在大型纯计算循环结束后才响应。
+
+## 8. 兼容性与影响面约束
+
+1. 从 main 新建实现分支；不将当前分支整体 cherry-pick 作为迁移方式。
+2. 没有视觉候选的页面，语义文本、DOM ref 相对顺序和操作行为维持原有契约。
+   例外为上述 observe 显式预算小于最小协议头的 invalid_params 行为及统一账本导致的临界预算截断位置变化；足够预算不改变旧语义。
+3. 有视觉候选的 observe 允许新增视觉文本，并按新预算规划改变截断位置；这是明确行为变化。
+4. `snapshot`、recording、hover probe 默认行为不随视觉通道接入而隐式改变。
+5. 修正已证明错误的坐标允许改变输出位置，不以错误 golden 为兼容目标。
+6. 几何共享改动必须覆盖已有 DOM 点击/截图路径回归；不以 Canvas 测试代替。
+7. CLI/协议外形优先保持；确需新增外部字段、错误子码或参数时，必须在对应 PR 明确列出全部消费者。
+8. 不进行无关格式化、目录大搬迁、依赖升级或语义启发式修改。
+9. 不长期保留两套 capture decoder、metrics adapter、frame resolver、token accounting 或 pixel planner。
+10. 不把站点特征、fixture 标签、CSS class 或 URL 放入生产决策。
+
+## 9. 设计验证清单与关闭方式
+
+| 待验证项 | 证据 | 必须形成的决定 |
+|---|---|---|
+| 嵌入式 Canvas 表格 原始失败 | main 的观察输出、对应截图及结构证据 | 失败归属、最小复现和成功标准 |
+| DOMSnapshot / metrics 单位 | DPR、zoom、scroll、frame 矩阵 | 原始单位适配和转换入口（实验结论见证据文档） |
+| frame / target 坐标 | 同 target、OOPIF、nested、带边框/变换样例 | content quad 来源、坐标归属及支持范围 |
+| document 身份 | 导航、同 frame document 替换、target 重建 | 使用哪些现有标识/事件，何时失效 |
+| CSS 视觉规则 | visibility 覆盖、opacity、hidden、单轴 overflow | 可合成状态和不支持情况 |
+| 时效容差 | 静止页面测量噪声、可控移动/缩放/裁剪变化 | 容差单位、比较规则和失败行为 |
+| 预算 | 调用方 max_tokens 使用方式、密集画布样例 | 提示预留、K、限额与截断规则 |
+| 去重 | 重合、近重合、不同父节点、相邻 tile | 首版等价规则和 Q 上限 |
+
+验证结果与最终决定见 [PR 0 证据及决策](visual-observation-evidence.md)。首版精确几何支持收敛到已验证的轴向矩形、正向轴对齐平移/缩放、普通 frame/overflow 链。旋转、透视、clip-path、mask 和活动 pinch-zoom 不承诺精确区域 ref：返回 geometry-unsupported 状态并提示使用现有视口截图。后续扩展必须独立验证。浏览器 UI zoom 与 CSS zoom 分开验证，不能用 pinch emulation 代替 UI zoom。
+
+进一步限定：CSS zoom/DOM transform 作用于 overflow 裁剪祖先的组合，首版也进入 geometry-unsupported。
+实验表明 snapshot.bounds 已缩放，而 clientRects/offsetRects 仍有未缩放和整数取整语义，不能靠一个宽度比准确恢复所有边。
+普通 Canvas 的 CSS zoom bounds 与 iframe content quad 缩放仍可使用；这不意味着缩放后的任意 DOM scrollport 都已获得精确支持。
+Facts 必须保留 client box、transform/zoom 及 clip-path/mask 等支持性证据，discovery 返回状态而不是另写近似投影。
+
+## 10. PR 划分与依赖
+
+PR 0 是设计与证据入口；PR 1—6 建立模块；PR 7 接入公开 observe；PR 8 完成跨模块验收和迁移收尾。编号是顺序计划，不是实际 GitHub PR 编号。
+
+```text
+PR 0 设计规格与实验
+  └─ PR 1 几何与身份契约
+       └─ PR 2 采集批次与共享事实
+            └─ PR 3 视觉发现
+                 └─ PR 4 选择、去重与预算
+
+PR 1 + PR 2 ──→ PR 5 类型化 ref
+PR 1 + PR 5 ──→ PR 6 视觉截图执行
+
+PR 2 + PR 3 + PR 4 + PR 5 + PR 6
+  └─ PR 7 observe 组合与接线
+       └─ PR 8 整体验收与迁移收尾
+```
+
+独立模块可以使用人工输入测试，不必等待真实上游接线。实现可依赖前序已合入 main 的 PR，避免多个大型长期分支互相漂移。阶段未接线的模块必须有紧邻的消费计划，不保留无期限死代码或对用户暴露半成品。
+
+### PR 0：规格收敛、最小复现与基线
+
+完成：
+
+- 审核现有分支 fixture，区分正确规格与需要推翻的预期。
+- 记录 嵌入式 Canvas 表格 原始失败及 main 基线，建立独立于站点的最小 fixture。
+- 完成第 9 节实验，锁定核心数据类型、支持范围、容差和资源参数。
+- 固定 #165 的相关回归结果和操作数基线；不夸大旧测试覆盖范围。
+- 将行为契约映射到后续每个模块的测试清单。
+
+不做：生产算法替换、全目录迁移、正式视觉通道接入。
+
+验收：核心身份、坐标、裁剪、预算和失效规则不存在未指定行为；未支持情况有明确策略。若仍有未知项，先调整范围而不是让后续 PR 猜测。
+
+### PR 1：统一几何与节点身份契约
+
+完成：
+
+- 引入有 owner 的坐标和地址类型，区分 frame/target/top/CSS/image 空间。
+- 统一 metrics 解释、frame projection 和 owner geometry 查询。
+- 共享单次操作内的 promise cache；保证采集和执行使用独立上下文。
+- 给既有 DOM 几何入口做窄适配；移除已被替代的投影路径。
+
+不做：Canvas 发现、排序、ref 外部行为变化。
+
+验收：scroll、border、同 target、OOPIF、nested、支持范围内的 transform/DPR/zoom 矩阵通过；已有 DOM 点击与截图回归通过；请求计数和几何成本可解释。
+
+### PR 2：采集批次、归一化事实和共享索引
+
+完成：
+
+- 将原始解码、采集编排、normalization 明确分开。
+- 按 target 去重采集，记录 document 身份、时间范围和阶段失败。
+- 建立 ObservationFacts、document 隔离 lookup/children 索引和正确的祖先状态结构。
+- 现有 SemanticPipeline 通过 adapter 消费新事实；保持 hover 在静态采集后发生。
+- 删除不再使用的可变中间态和重复解码/归属推断路径。
+
+不做：变更语义保留规则、视觉输出和截图政策。
+
+验收：语义回归及 frame ownership 通过；deep/wide/orphan/cycle 有明确结果；解码、索引、采集数量符合预算；无每节点完整祖先复制。
+
+### PR 3：纯数据视觉候选发现
+
+完成：
+
+- 实现 VisualCandidate 及 discoverVisualCandidates。
+- 落实无标签、有 AX、aria-hidden/inert/pointer-events、透明/隐藏、裁剪规则。
+- 候选关联 document/anchor/geometry，语义上下文只作为可选信息。
+- 返回发现失败或不完整状态，避免与无候选混淆。
+
+不做：ref 分配、截图、token 排序、逻辑画布合并。
+
+验收：每条发现规则都有正反 fixture；输入同一份事实输出确定；索引后的候选发现不重复扫 DOM 或走完整祖先链；不增加 CDP 调用。
+
+### PR 4：有界选择、保守去重与输出预算计划
+
+完成：
+
+- 明确几何优先排序及确定性 tie-breaker，预计算比较键。
+- 实现有界 top-K，K 受文本预算和安全限额约束。
+- 实现精确覆盖 key 去重及索引容量耗尽后“继续未去重选择”的退化行为；首版 Q=0，不进行模糊两两比较。
+- 建立纯 BudgetPlan 和视觉摘要/条目格式，统一预算核算契约。
+- 明确候选数、输出数、遗漏数及去重退化信息的口径。
+
+不做：多 anchor target、业务画布推断、生产 observe 接线。
+
+验收：密集小图、无名主画布、全部重合、同 bucket 不等价、极小预算均有确定结果；比较次数、堆大小、输出成本有界。
+
+### PR 5：类型化 ref 注册与工具解析
+
+完成：
+
+- RefStore 保存判别联合，绑定 document 及 observation 信息。
+- kind 派生工具适用性，删除可独立构造的矛盾 capability 状态。
+- 审核并迁移截图、交互、get_html、人工帮助等全部 ref 消费者。
+- 保持 eN 外部语义，文档明确跨代字符串识别限制。
+
+不做：引入新版 ref 协议、自动把视觉 ref 当 DOM anchor 使用。
+
+验收：跨 session/tab 隔离；document 失效；全部工具矩阵通过；拒绝在输入派发前发生；旧 DOM ref 行为保持。
+
+### PR 6：视觉截图的区域解析、像素规划与执行
+
+完成：
+
+- 分离 resolve-region、pixel-plan、capture executor。
+- 实现 visual 不滚动、身份验证、几何容差及重新观察错误。
+- 实现真实输出尺寸后置条件、有界重试和准确失败归因。
+- 复用 overlay suppression、取消和 dialog 机制。
+
+不做：Canvas 内部截图、像素冻结、多节点 union、内部点交互。
+
+验收：移动/缩放/裁剪变化、节点移除、document 替换、DPR/zoom、无效图像、超预算和取消路径通过；成功图像符合像素预算；现有 DOM 截图回归通过。
+
+### PR 7：观察结果组合与 observe 接线
+
+完成：
+
+- 将 Facts 的语义/视觉两路结果交给统一输出规划和 renderer。
+- 保留 #165 显式栈和 DOM ref 相对顺序，追加视觉条目。
+- 仅对已写入条目提交 ref，失败/截断状态正确传递。
+- 视觉提示参与预先预算，避免 DOM 耗尽预算后完全无提示。
+- 仅在 observe 默认启用新视觉通道；必要的 CLI/skill 使用说明同步更新。
+
+不做：顺带修改 snapshot、recording 或 hover 默认策略。
+
+验收：从人工 facts 到文本/ref 的集成测试、真实单 Canvas observe → screenshot 闭环通过；无 Canvas 页面回归通过；极小预算无悬空 ref。
+
+### PR 8：跨模块验收、性能证据与收尾
+
+完成：
+
+- 在真实浏览器运行完整 fixture 矩阵和 嵌入式 Canvas 表格 原始场景，保存可复现结果。
+- 验证整个管线的请求数量、集合规模、比较次数、深树安全和真实耗时。
+- 检查新模块是否存在重复解释、长期 adapter、无消费者代码或语义影响扩散。
+- 收尾剩余迁移文档、调试信息说明、支持范围和已知限制。
+
+不做：把此前未测试的性能正确性全部拖到本 PR，也不接纳新的功能范围。
+
+验收：第 11 节全部通过；若发现某模块契约错误，修正在该模块并补对应验收，不在最终接线处加站点特判。
+
+## 11. 总体验收矩阵
+
+本节是范围索引，具体怎么做、什么算成功见 [验收清单](visual-observation-acceptance.md)。新会话按当前 PR 执行并直接说明结果即可，无需报告模板或逐项登记。修改契约时同步清单，避免两套标准。
+
+| 维度 | 必测场景 | 主要责任 |
+|---|---|---|
+| 发现 | 无名、有 AX、aria-hidden、inert、pointer-events:none | PR 3 |
+| 视觉状态 | 零尺寸、透明祖先、visibility 覆盖、支持范围内 hidden 状态 | PR 0/2/3 |
+| 裁剪 | viewport、单轴/嵌套 overflow、支持范围内变换 | PR 1/2/3 |
+| frame | 同 target、OOPIF、nested、border、缺失 owner | PR 1/2 |
+| 身份 | target 冲突、节点移除、导航、document 替换 | PR 2/5/6 |
+| 输出 | DOM 顺序、视觉提示、modal 策略、极小预算、遗漏口径 | PR 4/7 |
+| ref | 工具矩阵、跨 tab/session、无悬空 ref | PR 5/7 |
+| 截图 | 几何变化、DPR/zoom、实际像素、重试、overlay | PR 6 |
+| 算法 | 深树、宽树、高密度、全部重合、索引退化 | 各模块 PR |
+| 回归 | #165、普通 DOM 点击/截图、snapshot、recording、hover | PR 1/2/7/8 |
+| 产品结果 | main 原始失败与新链路的 嵌入式 Canvas 表格 场景对照 | PR 0/8 |
+
+## 12. 相比旧蓝图的明确调整
+
+| 旧方向 | 本文调整 | 原因 |
+|---|---|---|
+| 全链路 transaction 先行 | 建立来源明确的 capture batch；不承诺原子快照 | 生命周期模型不能代替一致性证据 |
+| candidate → stack → logical surface 必经分层 | candidate + 输出覆盖去重；logical surface 不进入本次 | 限制身份模型及截图复杂度 |
+| 统一祖先 excluded | 视觉、语义、交互状态分开 | 避免加速错误规则 |
+| 各阶段一律兼容 adapter | 仅消费者迁移需要时使用，并随切换删除 | 避免临时抽象堆积 |
+| 性能作为后续优化阶段 | 每个模块设计/实现均有复杂度与计数验收 | 防止功能完成后再补算法 |
+| renderer 最后尝试附录 | 先规划预算，再分阶段输出 | 避免视觉入口系统性消失 |
+| observed rect 与 live rect 求交 | 身份和几何分别验证 | 避免成功返回错误截图片段 |
+| generation 暗示 freshness 已解决 | 明确现有 eN 重用限制 | 防止无法实现的旧字符串识别承诺 |
+| 当前测试全部视为兼容基准 | 先审核期望，再保留正确回归 | 测试不能替代行为规格 |
+
+## 13. 完成定义与设计变更纪律
+
+工程完成必须同时满足：
+
+- 五条核心结果全部成立，真实 嵌入式 Canvas 表格 场景及独立 fixture 均有证据。
+- 每个模块只有一个权威实现，依赖方向与本文一致。
+- 坐标和节点地址跨边界时身份明确，失败可归因。
+- 视觉发现不依赖语义树保留结果，不混淆视觉与交互属性。
+- 性能上限及退化可测试；复杂度没有遗漏协议输入量和几何工作量。
+- 现有语义、DOM 操作及 #165 成果受到明确回归保护。
+- 当前支持范围、近似/拒绝行为和 ref freshness 限制已记录。
+- 不存在为了通过原始站点而增加的生产特判。
+
+每个实现 PR 的描述必须写明：解决哪个独立问题、改变哪个契约、哪些行为允许变化、验证哪些正确性与性能要求、删除哪条旧路径。若没有删除旧路径，应说明保留原因和明确的后续消费/移除 PR。
+
+新的案例若属于已定规则范围，应修复负责该规则的模块；若要求改变目标身份、几何支持或对外协议，应先形成设计变更。不得在 observation 接线、renderer 或截图执行末端不断补跨层例外。
+
+## 14. 参考与证据来源
+
+- 本地 main：`3c5f838`；当前分析分支：`fix/vom-canvas-observation`。
+- PR #165 本地合并提交：`5ed8287`；实现提交：`641d934`。涉及 renderer 上下文索引、显式栈等优化。
+- 主要代码范围：`apps/extension/src/tools/observation.ts`、`tools/vom/capture.ts`、`tools/vom/frame-capture.ts`、`tools/vom/semantic-graph/`、`tools/frame-geometry.ts`、`session-manager/ref-store.ts`、`packages/vom/src/render.ts`。
+- 当前分支参考：`tools/vom/rendered-surfaces/`、`tools/visual-screenshot-plan.ts` 及相关 fixture/test。
+- 原 visual-surface 架构蓝图作为历史参考，不是本设计的执行规格。
+- 浏览器语义参考：[aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden)、[inert](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/inert)、[visibility](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/visibility)。本次 CDP 单位、frame 和身份实验结论见验证结果文档；支持范围之外的行为不作推断。
+
+本文中的路径为代码职责定位，最终目录命名可适配工程规范；行为契约、问题边界、复杂度预算和验收要求不能因此省略。
@@ -21,7 +21,6 @@ $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 {
@@ -65,7 +64,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"
@@ -91,59 +90,30 @@ function Add-ToSessionPath {
 # ── Git Bash (bash environment) PATH helper ──────────────────────────────────

 function Add-ToBashProfile {
-    param([string]$Dir, [string]$BashRc = (Join-Path $HOME ".bashrc"))
+    param([string]$Dir)

    # 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]
    }
-    # 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"
+    $bashRc = Join-Path $HOME ".bashrc"
+    $exportLine = "export PATH=""${unixPath}:`$PATH""  # bsk CLI"

-    if (Test-Path -LiteralPath $BashRc) {
-        $content = [System.IO.File]::ReadAllText($BashRc)
-        if ($content.Contains($exportLine)) {
+    if (Test-Path $bashRc) {
+        $content = Get-Content $bashRc -Raw -ErrorAction SilentlyContinue
+        if ($content -match [regex]::Escape($unixPath)) {
            Write-Log "$unixPath is already in ~/.bashrc"
            return
        }
    }

-    # 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)))
+    Add-Content $bashRc "`n$exportLine" -Encoding ASCII
    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

@@ -214,7 +184,7 @@ function Main {
            New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null
        }

-        Install-Binary -Source (Join-Path $tempDir "bsk.exe") -Target (Join-Path $InstallDir "bsk.exe")
+        Copy-Item -Path (Join-Path $tempDir "bsk.exe") -Destination (Join-Path $InstallDir "bsk.exe") -Force

        Write-Log "installed bsk to $InstallDir\bsk.exe"

@@ -229,8 +199,12 @@ function Main {

        # Verify
        $bskPath = Join-Path $InstallDir "bsk.exe"
-        & $bskPath --version
-        if ($LASTEXITCODE -ne 0) { throw "installed bsk failed verification" }
+        if (Get-Command bsk -ErrorAction SilentlyContinue) {
+            & bsk --version
+        }
+        else {
+            Write-Log "verify install: & ""$bskPath"" --version"
+        }

        Write-Log "done"
        Write-Host ""
@@ -1,51 +1,13 @@
-# BrowserSkill for DeepSeek Harness
+# dsh-plugin-browserskill

-[![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)
+npm: [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)

-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.
+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.

-## 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.
+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.

 ## Tools

@@ -58,7 +20,23 @@ the `bsk` CLI and browser extension separately when a release requires it.
 | `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. |

-Arbitrary page-script evaluation and interaction recording are not supported.
+`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.

 ## Multi-session model

@@ -77,73 +55,136 @@ 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.

-## Configuration
+## Installation

-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.
+The plugin follows the standard dsh bundle layout (`dsh.bundle` manifest + `cordis.patch.yml`):

-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
- id: browserskill
-  config:
-    bskPath: bsk
-    defaultTimeoutMs: 120000
-    maxSessions: 5
-    observationEnabled: true
-    thumbnailIntervalMs: 1500
-    idleIntervalMs: 8000
-    lazyTools: true
+```sh
+dsh plugin --profile <name> add @wxg-prc-cpg/browser-skill-dsh-plugin
+dsh --profile <name>
 ```

-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.
+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 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.
+## Configuration

-All fields are optional; omitted fields use the defaults below:
+All fields are optional and validated through the plugin's Schemastery `Config`:

-| 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. |
+```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
+```

-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.
+- **`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.

-## Live browser view
+## Observation overlay (PiP mini-window)

-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.
+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.

- 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.
+- **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`.

-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.
+## Behavior notes
+
+- **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.

 ## Development

@@ -154,47 +195,22 @@ 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 [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.
+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.

-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:
+Trigger it by pushing a tag that matches `package.json`'s `version`:

-   ```sh
-   node scripts/release.mjs <version>
-   ```
+```sh
+git tag dsh-plugin-v0.1.2
+git push origin dsh-plugin-v0.1.2
+```

-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/).
+Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the
+`NPM_TOKEN` secret from the `npm-publish` GitHub Environment.

 ## License

@@ -1,90 +0,0 @@
-# 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.
@@ -47,6 +47,7 @@
    "client": {
      "platform": "web",
      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
        "@deepseek-ai/dsh-client-ui-tool",
        "@deepseek-ai/dsh-client-ui-layout"
      ],
@@ -68,6 +69,7 @@
  "peerDependencies": {
    "@deepseek-ai/cordis": "^4.0.1",
    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
    "@deepseek-ai/dsh-client-ui-attachment": "^0.1.0-rc.6",
    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
    "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.6",
@@ -80,6 +82,9 @@
    "@deepseek-ai/dsh-attachment": {
      "optional": true
    },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
    "@deepseek-ai/dsh-client-ui-attachment": {
      "optional": true
    },
@@ -7,7 +7,6 @@
 */

 import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
-// Development-only types for the injected services; newer hosts no longer ship this package.
 import type { ClientContext, ISessions, SessionId } from "@deepseek-ai/dsh-client-runtime/client";
 // Type-only: pulls the 'shell.overlay' SlotMap merge into scope.
 import type {} from "@deepseek-ai/dsh-client-ui-layout/client";
@@ -5,7 +5,7 @@
 * map the CLI's JSON error envelope onto a thrown `BskError`.
 */

-import { type ChildProcess, type SpawnOptionsWithoutStdio, spawn } from "node:child_process";
+import { type ChildProcess, spawn } from "node:child_process";

 /** Shape of the JSON error envelope `bsk --json` prints on failure. */
 export interface BskErrorBody {
@@ -53,11 +53,7 @@ export interface BskRunOptions {
 }

 /** Minimal spawn signature so tests can substitute a fake child process. */
-export type SpawnImpl = (
-  command: string,
-  args: string[],
-  options?: SpawnOptionsWithoutStdio,
-) => ChildProcess;
+export type SpawnImpl = (command: string, args: string[]) => ChildProcess;

 export interface BskRunner {
  /** Run `bsk <args...> --json` and collect its output. */
@@ -68,66 +64,29 @@ export interface BskRunner {
  killFor(tag: string): number;
 }

-// Business RPCs translate Ctrl-C / opt-in stdin EOF into cancel(rpc_id).
-// Allow reconciliation before hard-killing an old or unresponsive CLI.
+// Business RPCs translate SIGINT into the daemon's cancel(rpc_id) protocol.
+// Give that bounded reconciliation path time to settle before the hard kill.
 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 || 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,
-    );
+    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);
    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"],
-            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", () => {});
+          child = spawnImpl(bskPath, [...args, "--json"]);
        } catch (error) {
          reject(error);
          return;
@@ -1,7 +1,6 @@
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { PassThrough } from "node:stream";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import {
  type BskRunResult,
  createBskRunner,
@@ -93,77 +92,6 @@ 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 };

@@ -25,6 +25,7 @@ const CLIENT_EXTERNALS: readonly string[] = [
  "@deepseek-ai/dsh-client-ui-primitives",
  "@deepseek-ai/dsh-client-ui-attachment",
  "@deepseek-ai/dsh-client-schema-form",
+  "@deepseek-ai/dsh-client-runtime/client",
 ];

 /** Wire/type layers with no shared runtime identity: safe to inline. */
@@ -1,135 +0,0 @@
-#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
-}