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

Release/0.2.1

.github/workflows/ci.yml

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

CHANGELOG.md

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

Cargo.lock

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

Cargo.toml

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

README.md

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

README.zh-CN.md

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

apps/extension/package.json

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

apps/extension/src/session-manager/__tests__/ref-store.test.ts

@@ -13,8 +13,6 @@ describe("RefStore", () => {
       backendNodeId: 42,
       tabId: 7,
       generation: 0,
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
     });
     expect(s.size()).toBe(1);
     expect(s.isEmpty()).toBe(false);
@@ -50,31 +48,4 @@ describe("RefStore", () => {
       cdpSessionId: "child-session",
     });
   });
-
-  it("preserves explicit capabilities for visual surface refs", () => {
-    const s = new RefStore();
-    s.set("e1", 42, {
-      tabId: 7,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-
-    expect(s.resolveEntry("e1")).toMatchObject({
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-  });
-
-  it("never grants ordinary interaction to a surface through defaults or caller input", () => {
-    const s = new RefStore();
-    s.set("e1", 42, { tabId: 7, kind: "surface" });
-    s.set("e2", 43, {
-      tabId: 7,
-      kind: "surface",
-      capabilities: ["interact", "screenshot"],
-    });
-
-    expect(s.resolveEntry("e1")?.capabilities).toEqual(["screenshot"]);
-    expect(s.resolveEntry("e2")?.capabilities).toEqual(["screenshot"]);
-  });
 });

apps/extension/src/session-manager/__tests__/surface-capture-store.test.ts

@@ -1,67 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { type SurfaceCaptureInput, SurfaceCaptureStore } from "../surface-capture-store";
-
-function input(): SurfaceCaptureInput {
-  return {
-    sessionId: "aa11",
-    tabId: 7,
-    navigationIdentity: "navigation",
-    surface: {
-      ref: "e3",
-      frameId: "main",
-      backendNodeId: 99,
-      observationGeneration: 2,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 50 },
-    imageWidth: 200,
-    imageHeight: 100,
-    viewportSignature: "viewport",
-    frameProjectionSignature: "frame",
-  };
-}
-
-describe("SurfaceCaptureStore", () => {
-  it("creates metadata-only, short-lived captures and consumes them once", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 500,
-      createId: () => "sc_test",
-    });
-    const capture = store.create(input());
-
-    expect(capture).toMatchObject({
-      id: "sc_test",
-      createdAt: 1_000,
-      expiresAt: 1_500,
-      consumed: false,
-    });
-    expect(capture).not.toHaveProperty("imageBase64");
-    expect(store.consume("sc_test")).toMatchObject({ ok: true });
-    expect(store.consume("sc_test")).toEqual({ ok: false, reason: "consumed" });
-
-    now = 1_600;
-    expect(store.size()).toBe(0);
-  });
-
-  it("rejects expired and unknown captures", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 10,
-      createId: () => "sc_expired",
-    });
-    store.create(input());
-    now = 1_010;
-
-    expect(store.consume("sc_expired")).toEqual({ ok: false, reason: "expired" });
-    expect(store.consume("sc_missing")).toEqual({ ok: false, reason: "not_found" });
-  });
-
-  it("clears every capture on session cleanup", () => {
-    const store = new SurfaceCaptureStore({ createId: () => "sc_clear" });
-    store.create(input());
-    store.clear();
-    expect(store.size()).toBe(0);
-  });
-});

apps/extension/src/session-manager/manager.ts

@@ -1,12 +1,10 @@
 import { AGENT_WINDOW_HOME, type AgentWindowApi, chromeAgentWindowApi } from "./agent-window";
 import { RefStore } from "./ref-store";
-import { SurfaceCaptureStore } from "./surface-capture-store";
 
 export interface SessionContext {
   sessionId: string;
   agentWindowId: number;
   refStore: RefStore;
-  surfaceCaptures: SurfaceCaptureStore;
   borrowedTabs: Map<number, BorrowedTab>;
   /**
    * Tabs explicitly claimed by the agent because it created them. This
@@ -212,7 +210,6 @@ export class SessionManager {
         sessionId,
         agentWindowId: windowId,
         refStore: new RefStore(),
-        surfaceCaptures: new SurfaceCaptureStore({ now: this.now }),
         borrowedTabs: new Map(),
         // The home tab is the session's first explicit claim. Every other
         // tab remains free until `tab_create` or `tab_borrow` identifies it

apps/extension/src/session-manager/ref-store.ts

@@ -1,5 +1,3 @@
-import type { Rect } from "@browser-skill/vom";
-
 /**
  * Per-session map from `@e<N>` snapshot refs to a CDP node address.
  *
@@ -14,17 +12,12 @@ import type { Rect } from "@browser-skill/vom";
  * inside the `SessionContext`.
  */
 export type BackendNodeId = number;
-export type RefCapability = "interact" | "screenshot";
-export type RefTargetKind = "dom" | "surface";
 
 export interface RefEntry {
   backendNodeId: BackendNodeId;
   tabId: number | null;
   frameId?: string;
   cdpSessionId?: string;
-  visibleRect?: Rect;
-  kind: RefTargetKind;
-  capabilities: RefCapability[];
   generation: number;
 }
 
@@ -35,19 +28,8 @@ export type RefInput =
       tabId: number;
       frameId?: string;
       cdpSessionId?: string;
-      visibleRect?: Rect;
-      kind?: RefTargetKind;
-      capabilities?: RefCapability[];
     };
 
-function capabilitiesFor(
-  kind: RefTargetKind,
-  capabilities: RefCapability[] | undefined,
-): RefCapability[] {
-  if (kind === "surface") return ["screenshot"];
-  return capabilities ?? ["interact", "screenshot"];
-}
-
 export class RefStore {
   private readonly map = new Map<string, RefEntry>();
   private generation = 0;
@@ -88,20 +70,13 @@ export class RefStore {
       tabId?: number;
       frameId?: string;
       cdpSessionId?: string;
-      visibleRect?: Rect;
-      kind?: RefTargetKind;
-      capabilities?: RefCapability[];
     } = {},
   ): void {
-    const kind = opts.kind ?? "dom";
     this.map.set(normaliseRef(ref), {
       backendNodeId: id,
       tabId: opts.tabId ?? null,
       ...(opts.frameId ? { frameId: opts.frameId } : {}),
       ...(opts.cdpSessionId ? { cdpSessionId: opts.cdpSessionId } : {}),
-      ...(opts.visibleRect ? { visibleRect: opts.visibleRect } : {}),
-      kind,
-      capabilities: capabilitiesFor(kind, opts.capabilities),
       generation: this.generation,
     });
   }
@@ -119,20 +94,14 @@ export class RefStore {
       return {
         backendNodeId: input,
         tabId: null,
-        kind: "dom",
-        capabilities: ["interact", "screenshot"],
         generation: this.generation,
       };
     }
-    const kind = input.kind ?? "dom";
     return {
       backendNodeId: input.backendNodeId,
       tabId: input.tabId,
       ...(input.frameId ? { frameId: input.frameId } : {}),
       ...(input.cdpSessionId ? { cdpSessionId: input.cdpSessionId } : {}),
-      ...(input.visibleRect ? { visibleRect: input.visibleRect } : {}),
-      kind,
-      capabilities: capabilitiesFor(kind, input.capabilities),
       generation: this.generation,
     };
   }

apps/extension/src/session-manager/surface-capture-store.ts

@@ -1,100 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-
-export const SURFACE_CAPTURE_TTL_MS = 30_000;
-
-export interface SurfaceCapture {
-  id: string;
-  sessionId: string;
-  tabId: number;
-  navigationIdentity: string;
-  surface: {
-    ref: string;
-    frameId?: string;
-    backendNodeId: number;
-    observationGeneration: number;
-  };
-  topViewportRect: Rect;
-  imageWidth: number;
-  imageHeight: number;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-  createdAt: number;
-  expiresAt: number;
-  consumed: boolean;
-}
-
-export type SurfaceCaptureInput = Omit<
-  SurfaceCapture,
-  "id" | "createdAt" | "expiresAt" | "consumed"
->;
-
-export type SurfaceCaptureConsumeResult =
-  | { ok: true; capture: SurfaceCapture }
-  | { ok: false; reason: "not_found" | "expired" | "consumed" };
-
-export interface SurfaceCaptureStoreOptions {
-  now?: () => number;
-  ttlMs?: number;
-  createId?: () => string;
-}
-
-function randomCaptureId(): string {
-  const bytes = crypto.getRandomValues(new Uint8Array(12));
-  return `sc_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-}
-
-/** Per-session, metadata-only store for short-lived screenshot coordinate transactions. */
-export class SurfaceCaptureStore {
-  private readonly captures = new Map<string, SurfaceCapture>();
-  private readonly now: () => number;
-  private readonly ttlMs: number;
-  private readonly createId: () => string;
-
-  constructor(options: SurfaceCaptureStoreOptions = {}) {
-    this.now = options.now ?? Date.now;
-    this.ttlMs = options.ttlMs ?? SURFACE_CAPTURE_TTL_MS;
-    this.createId = options.createId ?? randomCaptureId;
-  }
-
-  create(input: SurfaceCaptureInput): SurfaceCapture {
-    this.purgeExpired();
-    const createdAt = this.now();
-    const capture: SurfaceCapture = {
-      ...input,
-      id: this.createId(),
-      createdAt,
-      expiresAt: createdAt + this.ttlMs,
-      consumed: false,
-    };
-    this.captures.set(capture.id, capture);
-    return capture;
-  }
-
-  consume(id: string): SurfaceCaptureConsumeResult {
-    const capture = this.captures.get(id);
-    if (!capture) return { ok: false, reason: "not_found" };
-    if (capture.expiresAt <= this.now()) {
-      this.captures.delete(id);
-      return { ok: false, reason: "expired" };
-    }
-    if (capture.consumed) return { ok: false, reason: "consumed" };
-    capture.consumed = true;
-    return { ok: true, capture };
-  }
-
-  clear(): void {
-    this.captures.clear();
-  }
-
-  size(): number {
-    this.purgeExpired();
-    return this.captures.size;
-  }
-
-  private purgeExpired(): void {
-    const now = this.now();
-    for (const [id, capture] of this.captures) {
-      if (capture.expiresAt <= now) this.captures.delete(id);
-    }
-  }
-}

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

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolveFrameProjection, resolveNodeGeometry } from "../frame-geometry";
+import { resolveNodeGeometry } from "../frame-geometry";
 import {
   clipPolygon,
   polygonArea,
@@ -10,6 +10,7 @@ import {
   rectPolygon,
   regionBounds,
 } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 
 describe("frame geometry projection", () => {
@@ -82,28 +83,24 @@ describe("frame geometry projection", () => {
         throw new Error(`unexpected child command ${method}`);
       }) as CdpRunner["sendToTarget"],
     };
-    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",
-    );
+    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");
 
     expect(projection?.edges).toEqual([
       {

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

@@ -0,0 +1,464 @@
+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,
+  snapshotCoordinates,
+  snapshotViewportRect,
+} from "../geometry/coordinate-types";
+import { GeometryContext, snapshotLayoutScale } 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 {
+        visualViewport: { clientWidth: 1000 },
+        cssVisualViewport: { clientWidth: 1000 },
+        cssLayoutViewport: { clientWidth: 1000, clientHeight: 1000 },
+      };
+    if (method === "DOM.getBoxModel")
+      return { model: { content: [52.5, 612.5, 427.5, 612.5, 427.5, 862.5, 52.5, 862.5] } };
+    if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+    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.each([0.8, 1, 1.25, 2])("normalizes snapshot layout units at scale %s", (scale) => {
+    const measured = snapshotLayoutScale({
+      visualViewport: { clientWidth: 997.25, zoom: 1.1 },
+      cssVisualViewport: { clientWidth: 997.25 / scale, zoom: 1.1 },
+      // Rounded layout dimensions must not supply the scale.
+      layoutViewport: { clientWidth: 997 },
+      cssLayoutViewport: { clientWidth: Math.floor(997.25 / scale) },
+    });
+    expect(measured).toBeCloseTo(scale, 12);
+    const coordinates = snapshotCoordinates(
+      { scrollOffsetX: 80 * scale, scrollOffsetY: 200 * scale },
+      measured,
+      { x: 999, y: 999 },
+    );
+    expect(
+      snapshotViewportRect(
+        [160 * scale, 320 * scale, 120 * scale, 40 * scale],
+        { target },
+        coordinates,
+      )?.rect,
+    ).toEqual({ x: 80, y: 120, width: 120, height: 40 });
+  });
+
+  it("uses CSS root scroll only for missing snapshot offsets, without scaling it twice", () => {
+    const coordinates = snapshotCoordinates({ scrollOffsetX: 80 }, 2, { x: 999, y: 100 });
+    expect(snapshotViewportRect([200, 800, 240, 80], { target }, coordinates)?.rect).toEqual({
+      x: 60,
+      y: 300,
+      width: 120,
+      height: 40,
+    });
+    expect(snapshotCoordinates({ scrollOffsetX: 0 }, 2)).toBeNull();
+    expect(
+      snapshotCoordinates({ scrollOffsetX: NaN, scrollOffsetY: 0 }, 2, { x: 0, y: 0 }),
+    ).toBeNull();
+  });
+
+  it("does not infer snapshot units from missing, invalid, or CSS-only metrics", () => {
+    expect(snapshotLayoutScale({ cssLayoutViewport: { clientWidth: 800 } })).toBeNull();
+    for (const raw of [0, -1, NaN, Infinity]) {
+      expect(
+        snapshotLayoutScale({
+          visualViewport: { clientWidth: raw },
+          cssVisualViewport: { clientWidth: 800 },
+        }),
+      ).toBeNull();
+    }
+    expect(
+      snapshotLayoutScale({
+        visualViewport: { clientWidth: 0, clientHeight: 600 },
+        cssVisualViewport: { clientWidth: 0, clientHeight: 300 },
+      }),
+    ).toBe(2);
+    expect(snapshotCoordinates({ scrollOffsetX: 0, scrollOffsetY: 0 }, null)).toBeNull();
+    expect(snapshotViewportRect([10, 20, 120, 40], { target }, null)).toBeNull();
+  });
+
+  it("shares in-flight frame measurements, but never shares them with the next context", async () => {
+    const cdp = driver();
+    const context = new GeometryContext(cdp, 4);
+    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, {
+      layoutUnitsPerCssPixel: 1,
+      scrollCss: { x: 0, y: 0 },
+    });
+    expect(projectSnapshotRect(input!, projection.projection)).toEqual({
+      x: 73.75,
+      y: 641.25,
+      width: 150,
+      height: 50,
+    });
+    const scrolled = snapshotViewportRect([17, 23, 120, 40], source, {
+      layoutUnitsPerCssPixel: 1,
+      scrollCss: { x: 0, y: 10 },
+    });
+    expect(projectSnapshotRect(scrolled!, projection.projection)?.y).toBe(628.75);
+    await context.snapshotProjection(source, 10, [], { width: 1000, height: 1000 });
+    expect(cdp.calls.mock.calls.filter(([, method]) => method === "DOM.resolveNode")).toHaveLength(
+      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" },
+      { layoutUnitsPerCssPixel: 1, scrollCss: { 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 },
+        { layoutUnitsPerCssPixel: 1, scrollCss: { x: 0, y: 0 } },
+      ),
+    ).toBeNull();
+    expect(
+      snapshotViewportRect(
+        [0, 0, 10, 40],
+        { target },
+        { layoutUnitsPerCssPixel: 1, scrollCss: { x: Infinity, y: 0 } },
+      ),
+    ).toBeNull();
+  });
+
+  it("does not turn a border quad or a failed owner read into a content projection", async () => {
+    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" },
+      { layoutUnitsPerCssPixel: 1, scrollCss: { 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 {
+        visualViewport: { clientWidth: 1000 },
+        cssVisualViewport: { clientWidth: 1000 },
+        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,
+    });
+  });
+});

apps/extension/src/tools/__tests__/interaction.test.ts

@@ -11,7 +11,6 @@ import {
   parseKeySpec,
   resolveKeyDescriptor,
 } from "../interaction";
-import { captureSurfaceEnvironment } from "../surface-target";
 
 function fakeAgentWindow(ids: number[]) {
   let i = 0;
@@ -55,61 +54,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
   return { cdp, tabsApi, sent };
 }
 
-async function makeSurfaceClickFixture(onMouse?: (params: Record<string, unknown>) => void) {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const fake = makeFakeCdp({
-    "Page.getFrameTree": () => ({
-      frameTree: {
-        frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-      },
-    }),
-    "Page.getLayoutMetrics": () => ({
-      cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-      cssVisualViewport: {
-        clientWidth: 800,
-        clientHeight: 600,
-        pageX: 0,
-        pageY: 0,
-        scale: 1,
-      },
-    }),
-    "DOM.getContentQuads": () => ({ quads: [[10, 20, 110, 20, 110, 60, 10, 60]] }),
-    "Runtime.evaluate": () => ({
-      result: { value: { overlayHostPresent: false, overlayHostConnected: false } },
-    }),
-    "Input.dispatchMouseEvent": (params) => {
-      onMouse?.(params as Record<string, unknown>);
-      return {};
-    },
-  });
-  const environment = await captureSurfaceEnvironment(fake.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing Surface ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, fake, capture };
-}
-
 describe("modifiersBitfield", () => {
   it("matches CDP's expected bit layout", () => {
     expect(modifiersBitfield([])).toBe(0);
@@ -179,29 +123,6 @@ describe("handleClick", () => {
     expect(fake.cdp.send).not.toHaveBeenCalled();
   });
 
-  it("rejects screenshot-only visual surface refs before issuing CDP calls", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e3", 1234, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-    const fake = makeFakeCdp({});
-
-    const res = await handleClick(
-      sm,
-      { session_id: "aa11", ref: "@e3" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "ref_capability_denied", required_capability: "interact" },
-    });
-    expect(fake.cdp.send).not.toHaveBeenCalled();
-  });
-
   it("clicks by ref, computes the quad centre, dispatches three mouse events", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
@@ -246,74 +167,6 @@ describe("handleClick", () => {
     });
   });
 
-  it.each([
-    "left",
-    "middle",
-    "right",
-  ] as const)("uses the common click executor for a %s-button Surface click", async (button) => {
-    const { manager, fake, capture } = await makeSurfaceClickFixture();
-    const result = await handleClick(
-      manager,
-      {
-        session_id: "aa11",
-        ref: "@e3",
-        capture_id: capture.id,
-        image_x: 50,
-        image_y: 20,
-        button,
-        click_count: 2,
-        modifiers: ["ctrl", "shift"],
-      },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      used_ref: "e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-      x: 35,
-      y: 30,
-    });
-    const mouse = fake.sent.filter((call) => call.method === "Input.dispatchMouseEvent");
-    expect(mouse).toHaveLength(3);
-    expect(mouse[1].params).toMatchObject({
-      type: "mousePressed",
-      button,
-      clickCount: 2,
-      modifiers: 2 | 8,
-    });
-    expect(mouse[2].params).toMatchObject({
-      type: "mouseReleased",
-      button,
-      clickCount: 2,
-    });
-  });
-
-  it("consumes a Surface capture when the common click executor fails", async () => {
-    let mouseCalls = 0;
-    const { manager, fake, capture } = await makeSurfaceClickFixture((params) => {
-      mouseCalls += 1;
-      if (params.type === "mousePressed") throw new Error("input failed");
-    });
-    const params = {
-      session_id: "aa11",
-      ref: "@e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-    };
-
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ code: "cdp_failed" });
-    expect(mouseCalls).toBe(2);
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
   it("resolves frame refs in their CDP session and dispatches input in top coordinates", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");

apps/extension/src/tools/__tests__/mouse-input.test.ts

@@ -1,119 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { dispatchMouseClick } from "../mouse-input";
-import type { CdpRunner } from "../shared";
-
-function fakeCdp(onSend?: (method: string, params: Record<string, unknown>) => void): {
-  cdp: CdpRunner;
-  events: Record<string, unknown>[];
-} {
-  const events: Record<string, unknown>[] = [];
-  return {
-    events,
-    cdp: {
-      send: vi.fn(async (_tabId, method, params) => {
-        const event = params as Record<string, unknown>;
-        events.push(event);
-        onSend?.(method, event);
-        return {} as never;
-      }),
-    },
-  };
-}
-
-describe("dispatchMouseClick", () => {
-  it("emits one move, press, and release sequence", async () => {
-    const { cdp, events } = fakeCdp();
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 12, y: 34 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("completed");
-
-    expect(events).toEqual([
-      {
-        type: "mouseMoved",
-        x: 12,
-        y: 34,
-        modifiers: 0,
-      },
-      {
-        type: "mousePressed",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-      {
-        type: "mouseReleased",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-    ]);
-  });
-
-  it("releases a pressed button when cancellation arrives", async () => {
-    const controller = new AbortController();
-    const { cdp, events } = fakeCdp((_method, event) => {
-      if (event.type === "mousePressed") controller.abort();
-    });
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          signal: controller.signal,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("cancelled");
-    expect(events.at(-1)).toMatchObject({ type: "mouseReleased" });
-  });
-
-  it("settles pointer-move hit testing before pressing", async () => {
-    vi.useFakeTimers();
-    try {
-      const { cdp, events } = fakeCdp();
-      const click = dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 32,
-        },
-      );
-
-      await vi.advanceTimersByTimeAsync(31);
-      expect(events.map((event) => event.type)).toEqual(["mouseMoved"]);
-      await vi.advanceTimersByTimeAsync(1);
-      await click;
-      expect(events.map((event) => event.type)).toEqual([
-        "mouseMoved",
-        "mousePressed",
-        "mouseReleased",
-      ]);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});

apps/extension/src/tools/__tests__/observation.test.ts

@@ -36,14 +36,6 @@ function fakeAgentWindow(ids: number[]) {
 const TINY_PNG =
   "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR4nGNgYGBgAAAABQABh6FO1AAAAABJRU5ErkJggg==";
 
-function pngWithIhdrDimensions(width: number, height: number): string {
-  const bytes = Uint8Array.from(atob(TINY_PNG), (character) => character.charCodeAt(0));
-  const view = new DataView(bytes.buffer);
-  view.setUint32(16, width);
-  view.setUint32(20, height);
-  return btoa(String.fromCharCode(...bytes));
-}
-
 function makeScreenshotDeps(
   opts: {
     cdp?: CdpRunner;
@@ -73,10 +65,11 @@ function makeFakeCdp(handlers: Record<string, (params?: object) => unknown>) {
     sent.push({ method, params });
     const handler = handlers[method];
     if (!handler && method === "Page.getLayoutMetrics") {
-      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
-    }
-    if (!handler && method === "Page.getFrameTree") {
-      return { frameTree: { frame: { id: "main", loaderId: "loader-1", url: "https://test/" } } };
+      return {
+        visualViewport: { clientWidth: 1000 },
+        cssVisualViewport: { clientWidth: 1000 },
+        cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 },
+      };
     }
     if (!handler) throw new Error(`unexpected CDP call ${method}`);
     return handler(params);
@@ -97,7 +90,6 @@ describe("stripDataUrlPrefix", () => {
 describe("parsePngDimensions", () => {
   it("parses width/height from the IHDR chunk", () => {
     expect(parsePngDimensions(TINY_PNG)).toEqual({ width: 1, height: 1 });
-    expect(parsePngDimensions(pngWithIhdrDimensions(100, 80))).toEqual({ width: 100, height: 80 });
   });
   it("returns null on non-PNG input", () => {
     expect(parsePngDimensions("not-a-png-payload-just-random-base64-text-zzzzzzzzz")).toBeNull();
@@ -132,20 +124,6 @@ describe("handleScreenshot", () => {
     expect(get).not.toHaveBeenCalled();
   });
 
-  it("fails closed when a full-tab capture is not a valid PNG", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const res = await handleScreenshot(
-      sm,
-      { session_id: "aa11" },
-      makeScreenshotDeps({
-        captureVisibleTab: vi.fn(async () => "data:image/png;base64,bm90LWEtcG5n"),
-      }),
-    );
-
-    expect(res).toMatchObject({ code: "cdp_failed", message: /invalid PNG data/ });
-  });
-
   it("returns not_found when Agent Window has no active tab", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");
@@ -292,7 +270,15 @@ describe("handleScreenshot", () => {
     expect(sent.find((c) => c.method === "Page.captureScreenshot")).toBeUndefined();
   });
 
-  it("captures a clipped PNG when ref is given", async () => {
+  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,
+  }) => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e5", 999, { tabId: 7 });
@@ -300,6 +286,10 @@ 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(
@@ -323,172 +313,8 @@ describe("handleScreenshot", () => {
         clip?: { x: number; y: number; width: number; height: number };
       }
     )?.clip;
-    expect(clip).toMatchObject({ x: 10, y: 20, width: 100, height: 40 });
-  });
-
-  it("captures a bounded visible crop for a visual surface without scrolling it", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e5", 999, {
-      tabId: 7,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-    const { cdp, sent } = makeFakeCdp({
-      "Page.getLayoutMetrics": () => ({
-        cssLayoutViewport: { clientWidth: 4096, clientHeight: 4096 },
-      }),
-      "DOM.getContentQuads": () => ({ quads: [[0, 0, 4096, 0, 4096, 4096, 0, 4096]] }),
-      "Page.captureScreenshot": () => ({ data: TINY_PNG }),
-    });
-
-    const res = await handleScreenshot(
-      sm,
-      { session_id: "aa11", ref: "@e5", tab_id: 7 },
-      makeScreenshotDeps({
-        cdp,
-        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
-        query: vi.fn(),
-        captureVisibleTab: vi.fn(),
-      }),
-    );
-
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(sent.some((call) => call.method === "DOM.scrollIntoViewIfNeeded")).toBe(false);
-    const clip = sent.find((call) => call.method === "Page.captureScreenshot")?.params as {
-      clip?: { width: number; height: number; scale: number };
-    };
-    expect(clip.clip).toMatchObject({ width: 4096, height: 4096 });
-    expect(clip.clip?.scale).toBeCloseTo(Math.sqrt(4_000_000 / (4096 * 4096)));
-    expect(res.capture).toMatchObject({
-      surface_ref: "@e5",
-      coordinate_space: "capture-image-pixel",
-    });
-    expect(ctx.surfaceCaptures.size()).toBe(1);
-  });
-
-  it("crops a visual surface screenshot to its observation-time visible region", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e5", 999, {
-      tabId: 7,
-      kind: "surface",
-      visibleRect: { x: 25, y: 30, w: 50, h: 40 },
-    });
-    const { cdp, sent } = makeFakeCdp({
-      "Page.getLayoutMetrics": () => ({
-        cssLayoutViewport: { clientWidth: 800, clientHeight: 600 },
-      }),
-      "DOM.getContentQuads": () => ({ quads: [[0, 0, 200, 0, 200, 100, 0, 100]] }),
-      "Page.captureScreenshot": () => ({ data: pngWithIhdrDimensions(100, 80) }),
-    });
-
-    const res = await handleScreenshot(
-      sm,
-      { session_id: "aa11", ref: "@e5", tab_id: 7 },
-      makeScreenshotDeps({
-        cdp,
-        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
-        query: vi.fn(),
-        captureVisibleTab: vi.fn(),
-      }),
-    );
-
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    const clip = sent.find((call) => call.method === "Page.captureScreenshot")?.params as {
-      clip?: { x: number; y: number; width: number; height: number };
-    };
-    expect(clip.clip).toMatchObject({ x: 25, y: 30, width: 50, height: 40 });
-    expect(res).toMatchObject({ width: 100, height: 80 });
-    expect(res.capture?.id).toMatch(/^sc_/);
-  });
-
-  it("routes OOPIF surface geometry through its child session and captures top coordinates", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e5", 999, {
-      tabId: 7,
-      frameId: "child-frame",
-      cdpSessionId: "child-session",
-      kind: "surface",
-      visibleRect: { x: 224, y: 346, w: 200, h: 80 },
-    });
-    const { cdp, sent } = makeFakeCdp({
-      "DOM.getBoxModel": () => ({
-        model: { content: [204, 306, 604, 306, 604, 506, 204, 506] },
-      }),
-      "Page.getLayoutMetrics": () => ({
-        cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
-      }),
-      "Page.captureScreenshot": () => ({ data: TINY_PNG }),
-    });
-    cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 7 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          ownerBackendNodeId: 99,
-          target: { tabId: 7, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const targetCalls: Array<{ sessionId?: string; method: string }> = [];
-    cdp.sendToTarget = vi.fn(async (target, method) => {
-      targetCalls.push({ sessionId: target.sessionId, method });
-      if (method === "DOM.getContentQuads") {
-        return { quads: [[10, 20, 110, 20, 110, 60, 10, 60]] };
-      }
-      if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
-      }
-      throw new Error(`unexpected child CDP call ${method}`);
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handleScreenshot(
-      sm,
-      { session_id: "aa11", ref: "@e5", tab_id: 7 },
-      makeScreenshotDeps({
-        cdp,
-        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
-        query: vi.fn(),
-        captureVisibleTab: vi.fn(),
-      }),
-    );
-
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(targetCalls).toEqual([
-      { sessionId: "child-session", method: "DOM.getContentQuads" },
-      { sessionId: "child-session", method: "Page.getLayoutMetrics" },
-    ]);
-    const clip = sent.find((call) => call.method === "Page.captureScreenshot")?.params as {
-      clip?: { x: number; y: number; width: number; height: number };
-    };
-    expect(clip.clip).toMatchObject({ x: 224, y: 346, width: 200, height: 80 });
-  });
-
-  it("fails closed when a ref capture is not a valid PNG", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e5", 999, { tabId: 7, kind: "surface" });
-    const { cdp } = makeFakeCdp({
-      "DOM.getContentQuads": () => ({ quads: [[0, 0, 50, 0, 50, 50, 0, 50]] }),
-      "Page.captureScreenshot": () => ({ data: "bm90LWEtcG5n" }),
-    });
-
-    const res = await handleScreenshot(
-      sm,
-      { session_id: "aa11", ref: "@e5", tab_id: 7 },
-      makeScreenshotDeps({
-        cdp,
-        get: vi.fn(async () => ({ id: 7, windowId: 100, active: false }) as chrome.tabs.Tab),
-        query: vi.fn(),
-        captureVisibleTab: vi.fn(),
-      }),
-    );
-
-    expect(res).toMatchObject({ code: "cdp_failed", message: /invalid PNG data/ });
+    expect(clip).toMatchObject(expected);
+    expect(sent.filter((c) => c.method === "Page.getLayoutMetrics")).toHaveLength(1);
   });
 
   it("returns not_found for unknown ref", async () => {
@@ -846,6 +672,60 @@ 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,
@@ -2672,7 +2552,11 @@ describe("handleSnapshot", () => {
       if (method === "Accessibility.enable") return {};
       if (method === "Accessibility.getFullAXTree") return { nodes };
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") throw new Error("snapshot unsupported");
@@ -2759,7 +2643,11 @@ describe("handleSnapshot", () => {
       if (method === "Accessibility.enable") return {};
       if (method === "Accessibility.getFullAXTree") return { nodes: [root, button] };
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") {
@@ -2850,7 +2738,11 @@ describe("handleSnapshot", () => {
       if (method === "Accessibility.enable") return {};
       if (method === "Accessibility.getFullAXTree") return { nodes: [root, button] };
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") {
@@ -2944,7 +2836,11 @@ describe("handleSnapshot", () => {
       if (method === "Accessibility.enable") return {};
       if (method === "Accessibility.getFullAXTree") return { nodes: [root, button] };
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") {
@@ -3024,85 +2920,6 @@ describe("handleSnapshot", () => {
     );
   });
 
-  it("discovers rendered canvases only in observe and stores a screenshot-only ref", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    const root: CdpAxNode = {
-      nodeId: "1",
-      role: { type: "role", value: "RootWebArea" },
-      name: { type: "computedString", value: "Canvas app" },
-      backendDOMNodeId: 100,
-    };
-    const strings = ["body", "canvas", "static", "auto"];
-    const i = (value: string) => strings.indexOf(value);
-    const send = vi.fn(async (_tabId: number, method: string) => {
-      if (method === "Accessibility.enable" || method === "DOMSnapshot.enable") return {};
-      if (method === "Accessibility.getFullAXTree") return { nodes: [root] };
-      if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
-      }
-      if (method === "DOMSnapshot.captureSnapshot") {
-        return {
-          strings,
-          documents: [
-            {
-              nodes: {
-                parentIndex: [-1, 0],
-                nodeName: [i("body"), i("canvas")],
-                backendNodeId: [100, 200],
-                attributes: [[], []],
-              },
-              layout: {
-                nodeIndex: [0, 1],
-                styles: [
-                  [i("static"), i("auto"), i("auto")],
-                  [i("static"), i("auto"), i("auto")],
-                ],
-                bounds: [
-                  [0, 0, 1000, 800],
-                  [20, 30, 800, 500],
-                ],
-                paintOrders: [0, 1],
-              },
-            },
-          ],
-        };
-      }
-      throw new Error(`unexpected CDP method ${method}`);
-    });
-    const deps = {
-      cdp: {
-        send: send as unknown as <T = unknown>(
-          tabId: number,
-          method: string,
-          params?: object,
-        ) => Promise<T>,
-        trackSessionTab: vi.fn(),
-      },
-      tabsApi: {
-        get: vi.fn(
-          async (tabId: number) => ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
-        ),
-        query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
-      },
-      conditionalSurfaceProbe: false,
-    };
-
-    const observed = await handleObserve(sm, { session_id: "aa11" }, deps);
-    if ("code" in observed) throw new Error(`unexpected error: ${JSON.stringify(observed)}`);
-    expect(observed.text).toContain('@e1 surface "canvas visual surface"');
-    expect(ctx.refStore.resolveEntry("e1")).toMatchObject({
-      backendNodeId: 200,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-
-    const snapshot = await handleSnapshot(sm, { session_id: "aa11" }, deps);
-    if ("code" in snapshot) throw new Error(`unexpected error: ${JSON.stringify(snapshot)}`);
-    expect(snapshot.text).not.toContain("visual surface");
-    expect(snapshot.ref_count).toBe(0);
-  });
-
   it("allows passive snapshots of explicit user-window tabs", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");
@@ -3188,7 +3005,11 @@ describe("handleSnapshot", () => {
         };
       }
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+        };
       }
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") {
@@ -3401,10 +3222,14 @@ describe("handleSnapshot", () => {
   }
 
   const VP_METRICS = {
+    visualViewport: { clientWidth: 1000 },
+    cssVisualViewport: { clientWidth: 1000 },
     cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
   };
 
-  function makeFrameAwareDeps() {
+  function makeFrameAwareDeps(
+    ownerGeometry: "unavailable" | "available" | "clipped" = "unavailable",
+  ) {
     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")];
@@ -3412,6 +3237,8 @@ describe("handleSnapshot", () => {
       strings,
       documents: [
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           frameId: "main",
           nodes: {
             parentIndex: [-1, 0, 1],
@@ -3432,6 +3259,8 @@ describe("handleSnapshot", () => {
           },
         },
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           frameId: "child",
           nodes: {
             parentIndex: [-1, 0, 1],
@@ -3484,6 +3313,16 @@ 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 };
@@ -3724,6 +3563,43 @@ 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("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();
 

apps/extension/src/tools/__tests__/session.test.ts

@@ -278,23 +278,12 @@ describe("handleSessionStop with auto-return", () => {
     expect(aw.remove).not.toHaveBeenCalled();
   });
 
-  it("clears refs and Surface captures before window teardown", async () => {
+  it("clears the RefStore before window teardown", async () => {
     const aw = fakeAgentWindow([100]);
     const sm = new SessionManager({ agentWindow: aw });
     const ctx = await sm.start("aa11");
     // Insert a fake ref so we can verify clear() ran.
     ctx.refStore.set("e1", 123, { tabId: 7 });
-    ctx.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 7,
-      navigationIdentity: "navigation",
-      surface: { ref: "e1", backendNodeId: 123, observationGeneration: 0 },
-      topViewportRect: { x: 0, y: 0, w: 100, h: 50 },
-      imageWidth: 100,
-      imageHeight: 50,
-      viewportSignature: "viewport",
-      frameProjectionSignature: "frame",
-    });
     const state: FakeState = {
       tabs: new Map(),
       windowsClosed: new Set(),
@@ -303,7 +292,6 @@ describe("handleSessionStop with auto-return", () => {
     const { tabs, windows } = makeApis(state);
     await handleSessionStop(sm, { session_id: "aa11" }, { tabManagement: { tabs, windows } });
     expect(ctx.refStore.isEmpty()).toBe(true);
-    expect(ctx.surfaceCaptures.size()).toBe(0);
   });
 
   it.each([

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

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

apps/extension/src/tools/__tests__/snapshot-ref.test.ts

@@ -24,16 +24,10 @@ describe("lookupSnapshotRef", () => {
     expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
     });
     expect(lookupSnapshotRef(ctx, "e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
     });
   });
 
@@ -59,8 +53,6 @@ describe("resolveSnapshotRef", () => {
       tabId: 4,
       frameId: "child-frame",
       cdpSessionId: "child-session",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
     });
 
     const expected = {
@@ -68,9 +60,6 @@ describe("resolveSnapshotRef", () => {
       refKey: "e3",
       frameId: "child-frame",
       cdpSessionId: "child-session",
-      kind: "dom" as const,
-      capabilities: ["interact", "screenshot"] as const,
-      generation: 0,
     };
     expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
     expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
@@ -116,29 +105,6 @@ describe("resolveSnapshotRef", () => {
     expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
-    });
-  });
-
-  it("rejects an operation outside the ref's declared capabilities", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e3", 1234, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-
-    expect(resolveSnapshotRef(ctx, "@e3", 4, "interact")).toMatchObject({
-      code: "permission_denied",
-      message: "ref @e3 does not support interact",
-      data: {
-        reason: "ref_capability_denied",
-        required_capability: "interact",
-        kind: "surface",
-      },
     });
   });
 });

apps/extension/src/tools/__tests__/surface-coordinate.test.ts

@@ -1,52 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "../surface-coordinate";
-
-describe("surface coordinate mapping", () => {
-  it("maps capture image pixels through the actual screenshot dimensions", () => {
-    expect(mapImagePointToViewport({ x: 100, y: 50, w: 400, h: 200 }, 800, 400, 200, 100)).toEqual({
-      x: 200,
-      y: 100,
-    });
-  });
-
-  it("rejects invalid image coordinates and dimensions", () => {
-    const rect = { x: 0, y: 0, w: 100, h: 50 };
-    expect(mapImagePointToViewport(rect, 100, 50, -1, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 100, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 0, 50)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.NaN, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.POSITIVE_INFINITY, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 0, 50, 0, 0)).toBeNull();
-  });
-
-  it("intersects live and observed visible regions and compares them strictly", () => {
-    const clipped = surfaceVisibleRect(
-      { x: 0, y: 0, width: 200, height: 100 },
-      { x: 25, y: 30, w: 50, h: 40 },
-    );
-    expect(clipped).toEqual({ x: 25, y: 30, w: 50, h: 40 });
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 25, y: 30, w: 50, h: 40 })).toBe(
-      true,
-    );
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 26, y: 30, w: 50, h: 40 })).toBe(
-      false,
-    );
-  });
-
-  it("checks the projected visible region rather than only its bounding box", () => {
-    const triangle = [
-      [
-        { x: 0, y: 0 },
-        { x: 100, y: 0 },
-        { x: 0, y: 100 },
-      ],
-    ];
-    expect(pointInRegion({ x: 20, y: 20 }, triangle)).toBe(true);
-    expect(pointInRegion({ x: 90, y: 90 }, triangle)).toBe(false);
-  });
-});

apps/extension/src/tools/__tests__/surface-target.test.ts

@@ -1,306 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { SessionManager } from "@/session-manager/manager";
-import type { CdpRunner } from "../shared";
-import {
-  captureSurfaceEnvironment,
-  resolveSurfacePointerTarget,
-  SURFACE_POINTER_MOVE_SETTLE_MS,
-} from "../surface-target";
-
-function fakeAgentWindow() {
-  return {
-    create: vi.fn(async () => 100),
-    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
-  };
-}
-
-function fakeBrowser() {
-  let loaderId = "loader-1";
-  let pageY = 0;
-  let quad = [10, 20, 110, 20, 110, 60, 10, 60];
-  const sent: Array<{ method: string; params?: object }> = [];
-  const cdp: CdpRunner = {
-    send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-      sent.push({ method, params });
-      if (method === "Page.getFrameTree") {
-        return {
-          frameTree: { frame: { id: "main", loaderId, url: "https://fixture.test/" } },
-        } as never;
-      }
-      if (method === "Page.getLayoutMetrics") {
-        return {
-          cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY },
-          cssVisualViewport: {
-            clientWidth: 800,
-            clientHeight: 600,
-            pageX: 0,
-            pageY,
-            scale: 1,
-          },
-        } as never;
-      }
-      if (method === "DOM.getContentQuads") return { quads: [quad] } as never;
-      throw new Error(`unexpected CDP call ${method}`);
-    }) as CdpRunner["send"],
-    trackSessionTab: vi.fn(),
-  };
-  return {
-    cdp,
-    sent,
-    setLoaderId: (value: string) => {
-      loaderId = value;
-    },
-    setPageY: (value: number) => {
-      pageY = value;
-    },
-    setQuad: (value: number[]) => {
-      quad = value;
-    },
-  };
-}
-
-async function setupCapture() {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const browser = fakeBrowser();
-  const environment = await captureSurfaceEnvironment(browser.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, browser, capture };
-}
-
-function pointParams(captureId: string) {
-  return {
-    ref: "@e3",
-    captureId,
-    imageX: 50,
-    imageY: 20,
-  };
-}
-
-describe("Surface screenshot-bound pointer target", () => {
-  it("maps one fresh capture coordinate without executing an action", async () => {
-    const { context, browser, capture } = await setupCapture();
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      usedRef: "e3",
-      point: { x: 35, y: 30 },
-      moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-      capture: { id: capture.id, imageX: 50, imageY: 20 },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-
-    const repeated = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(repeated).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_consumed" },
-    });
-  });
-
-  it("rejects a new observation generation before sending input", async () => {
-    const { context, browser, capture } = await setupCapture();
-    context.refStore.replace([
-      [
-        "e3",
-        {
-          backendNodeId: 99,
-          tabId: 4,
-          kind: "surface" as const,
-          visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-        },
-      ],
-    ]);
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(result).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_stale" },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-
-  it("rejects navigation, scroll, and visible geometry changes", async () => {
-    for (const mutate of [
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setLoaderId("loader-2"),
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setPageY(20),
-      (browser: ReturnType<typeof fakeBrowser>) =>
-        browser.setQuad([11, 20, 111, 20, 111, 60, 11, 60]),
-    ]) {
-      const { context, browser, capture } = await setupCapture();
-      mutate(browser);
-      const result = await resolveSurfacePointerTarget(
-        context,
-        { tabId: 4 },
-        pointParams(capture.id),
-        { cdp: browser.cdp },
-      );
-      expect(result).toMatchObject({
-        code: "permission_denied",
-        data: { reason: "surface_capture_stale" },
-      });
-      expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-    }
-  });
-
-  it("consumes the capture when coordinate validation fails", async () => {
-    const invalid = await setupCapture();
-    const outside = await resolveSurfacePointerTarget(
-      invalid.context,
-      { tabId: 4 },
-      { ...pointParams(invalid.capture.id), imageX: 200 },
-      { cdp: invalid.browser.cdp },
-    );
-    expect(outside).toMatchObject({
-      code: "invalid_params",
-      data: { reason: "surface_coordinate_invalid" },
-    });
-    expect(
-      await resolveSurfacePointerTarget(
-        invalid.context,
-        { tabId: 4 },
-        pointParams(invalid.capture.id),
-        { cdp: invalid.browser.cdp },
-      ),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
-  it("maps image coordinates through an OOPIF frame projection", async () => {
-    const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-    const context = await manager.start("aa11");
-    context.refStore.set("e3", 99, {
-      tabId: 4,
-      frameId: "child",
-      cdpSessionId: "child-session",
-      kind: "surface",
-      visibleRect: { x: 120, y: 110, w: 100, h: 40 },
-    });
-    const graph = {
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child",
-          parentFrameId: "main",
-          ownerBackendNodeId: 77,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    };
-    const sent: Array<{ method: string; params?: object }> = [];
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-        sent.push({ method, params });
-        if (method === "Page.getFrameTree") {
-          return {
-            frameTree: {
-              frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-            },
-          } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return {
-            cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-            cssVisualViewport: {
-              clientWidth: 800,
-              clientHeight: 600,
-              pageX: 0,
-              pageY: 0,
-              scale: 1,
-            },
-          } as never;
-        }
-        if (method === "DOM.getBoxModel") {
-          return { model: { content: [100, 100, 300, 100, 300, 200, 100, 200] } } as never;
-        }
-        if (method === "Input.dispatchMouseEvent") return {} as never;
-        throw new Error(`unexpected root CDP call ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "DOM.getContentQuads") {
-          return { quads: [[20, 10, 120, 10, 120, 50, 20, 50]] } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } } as never;
-        }
-        throw new Error(`unexpected child CDP call ${method}`);
-      }) as CdpRunner["sendToTarget"],
-      getFrameGraph: vi.fn(async () => graph),
-      trackSessionTab: vi.fn(),
-    };
-    const environment = await captureSurfaceEnvironment(cdp, 4, "child");
-    if ("code" in environment) throw new Error(environment.message);
-    const entry = context.refStore.resolveEntry("e3");
-    if (!entry) throw new Error("missing ref");
-    const capture = context.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 4,
-      navigationIdentity: environment.navigationIdentity,
-      surface: {
-        ref: "e3",
-        frameId: "child",
-        backendNodeId: 99,
-        observationGeneration: entry.generation,
-      },
-      topViewportRect: { x: 120, y: 110, w: 100, h: 40 },
-      imageWidth: 200,
-      imageHeight: 80,
-      viewportSignature: environment.viewportSignature,
-      frameProjectionSignature: environment.frameProjectionSignature,
-    });
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      {
-        ref: "@e3",
-        captureId: capture.id,
-        imageX: 100,
-        imageY: 40,
-      },
-      { cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({ point: { x: 170, y: 130 } });
-    expect(sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-});

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

@@ -1,24 +1,21 @@
-import { type CdpFrame, type CdpFrameGraph, type CdpTarget } from "@/browser-driver/frame-graph";
+import { type CdpTarget, cdpTargetKey } 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 CdpRunner, cdpRunnerForTarget, isRpcError, sendToCdpTarget } from "./shared";
+import type { CssViewport } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
+import { type CdpRunner, cdpRunnerForTarget, isRpcError } from "./shared";
 
 export interface NodeAddress {
   target: CdpTarget;
@@ -27,6 +24,8 @@ 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. */
@@ -39,145 +38,16 @@ 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,
-  graph: CdpFrameGraph,
+  context: GeometryContext,
   frameId: string,
 ): Promise<RpcError | null> {
-  const byId = frameMap(graph);
-  const ancestry = frameAncestry(graph, frameId);
+  const ancestry = await context.ancestry(frameId);
   if (!ancestry) return geometryError(`could not resolve frame ancestry for ${frameId}`);
   for (const child of [...ancestry].reverse()) {
-    const parent = child.parentFrameId ? byId.get(child.parentFrameId) : undefined;
+    const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
     if (!parent || child.ownerBackendNodeId === undefined) {
       return geometryError(`could not resolve frame owner for ${child.frameId}`);
     }
@@ -191,17 +61,20 @@ async function scrollFrameOwners(
   return null;
 }
 
-async function scrollElementWithFrameGraph(
+async function scrollElementWithContext(
   cdp: CdpRunner,
   tabId: number,
   target: CdpTarget,
   backendNodeId: number,
   frameId: string | undefined,
-  graph: CdpFrameGraph | null,
+  context: GeometryContext,
 ): Promise<RpcError | null> {
   if (frameId) {
-    if (!graph) return geometryError(`could not resolve frame graph for ${frameId}`);
-    const error = await scrollFrameOwners(cdp, tabId, graph, 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 (error) return error;
   } else if (target.sessionId) {
     return geometryError("an OOPIF node address requires frameId");
@@ -216,8 +89,15 @@ export async function scrollElementAndFramesIntoView(
   backendNodeId: number,
   frameId?: string,
 ): Promise<RpcError | null> {
-  const graph = frameId ? await loadFrameGraph(cdp, tabId) : null;
-  return scrollElementWithFrameGraph(cdp, tabId, target, backendNodeId, frameId, graph);
+  if (target.tabId !== tabId) return geometryError("node target belongs to another tab");
+  return scrollElementWithContext(
+    cdp,
+    tabId,
+    target,
+    backendNodeId,
+    frameId,
+    new GeometryContext(cdp, tabId),
+  );
 }
 
 function largestRegion(regions: Region): Polygon | null {
@@ -240,23 +120,32 @@ export async function resolveNodeGeometry(
     if (address.target.sessionId && !address.frameId) {
       return geometryError("an OOPIF node address requires frameId");
     }
-    const graph = address.frameId ? await loadFrameGraph(cdp, tabId) : null;
+    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");
+      }
+    }
     if (address.frameId && !graph) {
       return geometryError(`could not resolve frame graph for ${address.frameId}`);
     }
 
     if (options.scrollIntoView) {
-      const scrollError = await scrollElementWithFrameGraph(
+      const scrollError = await scrollElementWithContext(
         cdp,
         tabId,
         address.target,
         address.backendNodeId,
         address.frameId,
-        graph,
+        context,
       );
       if (scrollError) return scrollError;
     }
 
+    // Only topology was read above. Begin live measurements after scrolling.
     const localRegion = await nodeContentRegion(
       cdpRunnerForTarget(cdp, address.target),
       tabId,
@@ -267,7 +156,7 @@ export async function resolveNodeGeometry(
     let topVisibleRegions: Region;
     let targetActionPoint: Point | null = null;
     if (address.frameId && graph) {
-      const projection = await resolveFrameProjection(cdp, graph, address.frameId);
+      const projection = await context.targetProjection(address.frameId);
       if (!projection)
         return geometryError(`could not resolve frame geometry for ${address.frameId}`);
       topVisibleRegions = projectRegionToViewport(localRegion, projection);
@@ -290,7 +179,7 @@ export async function resolveNodeGeometry(
         targetActionPoint = localActionRegion ? polygonCentroid(localActionRegion) : null;
       }
     } else {
-      const viewport = await targetViewport(cdp, address.target);
+      const viewport = await context.viewport(address.target);
       if (!viewport) return geometryError("could not resolve top viewport geometry");
       topVisibleRegions = localRegion
         .map((polygon) =>
@@ -309,7 +198,13 @@ export async function resolveNodeGeometry(
       return { code: "permission_denied", message: "element not visible in its target" };
     }
     targetActionPoint ??= actionPoint;
-    return { topVisibleRegions, topBounds, actionPoint, targetActionPoint };
+    return {
+      topVisibleRegions,
+      topBounds,
+      actionPoint,
+      targetActionPoint,
+      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
+    };
   } catch (error) {
     return geometryError(error instanceof Error ? error.message : String(error));
   }

apps/extension/src/tools/geometry.ts

@@ -245,22 +245,3 @@ 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,
-  };
-}

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

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

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

@@ -0,0 +1,356 @@
+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; clientWidth?: number; clientHeight?: number };
+  visualViewport?: { zoom?: number; clientWidth?: number; clientHeight?: number };
+  cssLayoutViewport?: {
+    clientWidth?: number;
+    clientHeight?: number;
+    pageX?: number;
+    pageY?: number;
+  };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
+}
+
+/** Chromium emits these paired floating-point dimensions before/after dividing
+ * by LayoutZoomFactor. Integer layout viewport dimensions lose precision at
+ * fractional zoom. Neither visualViewport.scale nor .zoom is this conversion.
+ * See InspectorPageAgent::getLayoutMetrics in Chromium. */
+export function snapshotLayoutScale(metrics: LayoutMetrics): number | null {
+  for (const dimension of ["clientWidth", "clientHeight"] as const) {
+    const raw = metrics.visualViewport?.[dimension];
+    const css = metrics.cssVisualViewport?.[dimension];
+    if (
+      raw !== undefined &&
+      css !== undefined &&
+      Number.isFinite(raw) &&
+      Number.isFinite(css) &&
+      raw > 0 &&
+      css > 0
+    ) {
+      const scale = raw / css;
+      if (Number.isFinite(scale) && scale > 0) return scale;
+    }
+  }
+  return null;
+}
+
+/** The legacy field is a compatibility fallback, never a source of raster DPR. */
+export function cssViewport(metrics: LayoutMetrics): CssViewport {
+  const value = metrics.cssLayoutViewport ?? metrics.layoutViewport;
+  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;
+  }
+}

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

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

apps/extension/src/tools/interaction.ts

@@ -32,7 +32,6 @@ import { attachDialogs, markDialogCursor } from "./dialogs";
 import { backendNodeToObject } from "./element-geometry";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry, scrollElementAndFramesIntoView } from "./frame-geometry";
-import { dispatchMouseClick } from "./mouse-input";
 import {
   type CdpRunner,
   type ChromeTabsApi,
@@ -45,7 +44,6 @@ import {
   resolveTargetTab,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { resolveSurfacePointerTarget } from "./surface-target";
 
 export interface InteractionDeps {
   cdp: CdpRunner;
@@ -171,7 +169,7 @@ export async function resolveBackendNode(
     };
   }
   if (hasRef) {
-    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId, "interact");
+    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId);
     if (isRpcError(resolved)) return resolved;
     return {
       backendNodeId: resolved.backendNodeId,
@@ -244,25 +242,11 @@ export async function resolveActionTarget(
 // tool.click
 // ---------------------------------------------------------------------------
 
-interface ResolvedClickPointerTarget {
-  point: { x: number; y: number };
-  usedRef?: string;
-  usedSelector?: string;
-  moveSettleMs: number;
-  capture?: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
 export async function handleClick(
   manager: SessionManager,
   params: ClickParams,
   deps: InteractionDeps = getDefaultDeps(),
 ): Promise<ClickResult | RpcError> {
-  const hasSurfacePointParams =
-    params.capture_id !== undefined || params.image_x !== undefined || params.image_y !== undefined;
   const ctxOrErr = lookupSession(manager, params, "click");
   if (isRpcError(ctxOrErr)) return ctxOrErr;
   const ctx = ctxOrErr;
@@ -272,23 +256,6 @@ export async function handleClick(
   if (isRpcError(target)) return target;
   const denied = enforceAgentWindow(ctx, target, "click");
   if (denied) return denied;
-  if (hasSurfacePointParams) {
-    const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
-    const pointerTarget = await resolveSurfacePointerTarget(
-      ctx,
-      target,
-      {
-        ref: params.ref,
-        selector: params.selector,
-        captureId: params.capture_id,
-        imageX: params.image_x,
-        imageY: params.image_y,
-      },
-      { cdp: deps.cdp, signal: deps.signal },
-    );
-    if (isRpcError(pointerTarget)) return pointerTarget;
-    return executeResolvedClick(ctx, target, pointerTarget, params, deps, dialogCursor);
-  }
   const resolved = await resolveActionTarget(deps.cdp, ctx, target, params, "click");
   if (isRpcError(resolved)) return resolved;
   return clickResolvedTarget(ctx, resolved, params, deps);
@@ -302,6 +269,11 @@ export async function clickResolvedTarget(
 ): Promise<ClickResult | RpcError> {
   const { tab: target } = resolved;
   const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
+
+  if (throwIfAborted(deps.signal)) {
+    return { code: "cancelled", message: "click aborted" };
+  }
+
   deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
   const geometry = await resolveNodeGeometry(
     deps.cdp,
@@ -314,47 +286,20 @@ export async function clickResolvedTarget(
     { scrollIntoView: true },
   );
   if (isRpcError(geometry)) return geometry;
-  return executeResolvedClick(
-    ctx,
-    target,
-    {
-      point: geometry.actionPoint,
-      usedRef: resolved.usedRef,
-      usedSelector: resolved.usedSelector,
-      moveSettleMs: 0,
-    },
-    params,
-    deps,
-    dialogCursor,
-  );
-}
+  const centre = geometry.actionPoint;
 
-async function executeResolvedClick(
-  ctx: SessionContext,
-  target: ResolvedTargetTab,
-  pointerTarget: ResolvedClickPointerTarget,
-  params: Pick<ClickParams, "button" | "click_count" | "modifiers">,
-  deps: InteractionDeps,
-  dialogCursor: number,
-): Promise<ClickResult | RpcError> {
   if (throwIfAborted(deps.signal)) {
     return { code: "cancelled", message: "click aborted" };
   }
 
   const button: MouseButton = params.button ?? "left";
   const clickCount = params.click_count ?? 1;
-  if (!Number.isSafeInteger(clickCount) || clickCount < 1) {
-    return { code: "invalid_params", message: "click_count must be a positive integer" };
+  if (clickCount < 1) {
+    return { code: "invalid_params", message: "click_count must be greater than zero" };
   }
   const modifiers = modifiersBitfield(params.modifiers);
 
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  const overlayBlocking = await checkOverlayAtPoint(
-    deps.cdp,
-    target.tabId,
-    pointerTarget.point.x,
-    pointerTarget.point.y,
-  );
+  const overlayBlocking = await checkOverlayAtPoint(deps.cdp, target.tabId, centre.x, centre.y);
   let automationBypassEnabled = false;
   if (overlayBlocking && deps.bypassOverlay) {
     try {
@@ -366,16 +311,47 @@ async function executeResolvedClick(
   }
 
   try {
-    const dispatch = await dispatchMouseClick(deps.cdp, target.tabId, pointerTarget.point, {
+    // Move first so hover state activates, then press → release.
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: centre.x,
+      y: centre.y,
+      modifiers,
+    });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "click aborted" };
+    }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x: centre.x,
+      y: centre.y,
       button,
       clickCount,
       modifiers,
-      signal: deps.signal,
-      moveSettleMs: pointerTarget.moveSettleMs,
     });
-    if (dispatch === "cancelled") {
+    if (throwIfAborted(deps.signal)) {
+      try {
+        await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+          type: "mouseReleased",
+          x: centre.x,
+          y: centre.y,
+          button,
+          clickCount,
+          modifiers,
+        });
+      } catch (err) {
+        console.debug("[bsk interaction] best-effort mouseReleased after abort failed", err);
+      }
       return { code: "cancelled", message: "click aborted" };
     }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x: centre.x,
+      y: centre.y,
+      button,
+      clickCount,
+      modifiers,
+    });
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -393,17 +369,10 @@ async function executeResolvedClick(
 
   return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
     tab_id: target.tabId,
-    used_ref: pointerTarget.usedRef,
-    used_selector: pointerTarget.usedSelector,
-    x: pointerTarget.point.x,
-    y: pointerTarget.point.y,
-    ...(pointerTarget.capture
-      ? {
-          capture_id: pointerTarget.capture.id,
-          image_x: pointerTarget.capture.imageX,
-          image_y: pointerTarget.capture.imageY,
-        }
-      : {}),
+    used_ref: resolved.usedRef,
+    used_selector: resolved.usedSelector,
+    x: centre.x,
+    y: centre.y,
   });
 }
 

apps/extension/src/tools/mouse-input.ts

@@ -1,96 +0,0 @@
-import type { MouseButton } from "@/transport/types";
-import type { Point } from "./geometry";
-import type { CdpRunner } from "./shared";
-
-interface MouseClickDispatchOptions {
-  button: MouseButton;
-  clickCount: number;
-  modifiers: number;
-  signal?: AbortSignal;
-  moveSettleMs?: number;
-}
-
-type MouseClickDispatchResult = "completed" | "cancelled";
-
-function waitForSettle(ms: number, signal: AbortSignal | undefined): Promise<boolean> {
-  if (ms <= 0) return Promise.resolve(signal?.aborted !== true);
-  if (signal?.aborted) return Promise.resolve(false);
-  return new Promise((resolve) => {
-    let settled = false;
-    const finish = (completed: boolean) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      resolve(completed);
-    };
-    const timer = setTimeout(() => finish(true), ms);
-    const onAbort = () => finish(false);
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-/**
- * Dispatch one coherent CDP mouse click in top-viewport CSS coordinates.
- *
- * Keeping the sequence here prevents DOM and Surface interaction paths from
- * duplicating cancellation and best-effort release behavior. Callers that
- * target asynchronously hit-tested content may request a settle interval.
- */
-export async function dispatchMouseClick(
-  cdp: CdpRunner,
-  tabId: number,
-  point: Point,
-  options: MouseClickDispatchOptions,
-): Promise<MouseClickDispatchResult> {
-  const { button, clickCount, modifiers, signal, moveSettleMs = 0 } = options;
-  let pressed = false;
-  const release = () =>
-    cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseReleased",
-      x: point.x,
-      y: point.y,
-      button,
-      clickCount,
-      modifiers,
-    });
-
-  try {
-    await cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: point.x,
-      y: point.y,
-      modifiers,
-    });
-    if (!(await waitForSettle(moveSettleMs, signal))) return "cancelled";
-
-    await cdp.send(tabId, "Input.dispatchMouseEvent", {
-      type: "mousePressed",
-      x: point.x,
-      y: point.y,
-      button,
-      clickCount,
-      modifiers,
-    });
-    pressed = true;
-
-    if (signal?.aborted) {
-      await release();
-      pressed = false;
-      return "cancelled";
-    }
-
-    await release();
-    pressed = false;
-    return "completed";
-  } catch (error) {
-    if (pressed) {
-      try {
-        await release();
-      } catch (releaseError) {
-        console.debug("[bsk mouse-input] best-effort mouse release failed", releaseError);
-      }
-    }
-    throw error;
-  }
-}

apps/extension/src/tools/observation.ts

@@ -8,7 +8,6 @@ import {
   applyVomInteractionRecovery,
   type CondSurface,
   isVomReferenceNode,
-  type Rect,
   renderVom,
   type VomNode,
   type VomOptions,
@@ -35,6 +34,8 @@ 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,
@@ -48,8 +49,6 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { surfaceVisibleRect } from "./surface-coordinate";
-import { captureSurfaceEnvironment } from "./surface-target";
 import {
   type CapturedNode,
   type CapturedSurfaceProbe,
@@ -65,11 +64,6 @@ import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
-import {
-  clusterRenderedSurfaces,
-  discoverRenderedSurfaces,
-  projectRenderedSurfaces,
-} from "./vom/rendered-surfaces";
 import {
   buildSemanticGraph,
   buildSemanticVomScene,
@@ -101,9 +95,6 @@ export const normaliseRef = sharedNormaliseRef;
 // screenshot — `tool.screenshot`
 // ---------------------------------------------------------------------------
 
-const VISUAL_SURFACE_SCREENSHOT_MAX_EDGE = 2_048;
-const VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS = 4_000_000;
-
 /**
  * Strip the `data:image/...;base64,` prefix from a Chrome
  * `captureVisibleTab` dataURL and return the raw base64 payload.
@@ -118,8 +109,8 @@ export function stripDataUrlPrefix(dataUrl: string): string {
 
 /**
  * Parse a PNG's IHDR chunk and return `(width, height)`. Returns
- * `null` on malformed input so callers can reject dimensions that are
- * not authoritative instead of guessing from a CSS-space rectangle.
+ * `null` on any malformed input so callers fall back to `0/0` instead
+ * of throwing.
  *
  * PNG layout: 8-byte signature, then a 4-byte length, 4-byte type
  * ("IHDR"), then the chunk data — width is bytes 16-19 BE, height is
@@ -131,9 +122,9 @@ export function parsePngDimensions(base64: string): { width: number; height: num
     const head = base64.length > 64 ? base64.slice(0, 64) : base64;
     const bin = atob(head);
     if (bin.length < 24) return null;
-    const expectedSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-    if (expectedSignature.some((byte, index) => bin.charCodeAt(index) !== byte)) return null;
-    if (bin.slice(12, 16) !== "IHDR") return null;
+    if (bin.charCodeAt(0) !== 0x89 || bin.charCodeAt(1) !== 0x50 || bin.charCodeAt(2) !== 0x4e) {
+      return null;
+    }
     const u32 = (off: number) =>
       (bin.charCodeAt(off) << 24) |
       (bin.charCodeAt(off + 1) << 16) |
@@ -196,52 +187,27 @@ async function captureElementScreenshot(
   target: CdpTarget,
   backendNodeId: number,
   frameId?: string,
-  visualSurface = false,
-  observedVisibleRect?: Rect,
   signal?: AbortSignal,
-): Promise<
-  { image_base64: string; width: number; height: number; topViewportRect: Rect } | RpcError
-> {
+): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
   if (signal?.aborted) return cancelled("screenshot");
   const geometry = await resolveNodeGeometry(
     cdp,
     tabId,
     { target, backendNodeId, ...(frameId ? { frameId } : {}) },
-    { scrollIntoView: !visualSurface },
+    { scrollIntoView: true },
   );
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
-  const topViewportRect = surfaceVisibleRect(
-    geometry.topBounds,
-    visualSurface ? observedVisibleRect : undefined,
-  );
-  if (!topViewportRect) {
-    return { code: "permission_denied", message: "surface is no longer visible" };
-  }
-  const rect = {
-    x: topViewportRect.x,
-    y: topViewportRect.y,
-    width: topViewportRect.w,
-    height: topViewportRect.h,
-  };
-  const scale = visualSurface
-    ? Math.min(
-        1,
-        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.width,
-        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.height,
-        Math.sqrt(VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS / (rect.width * rect.height)),
-      )
-    : 1;
+  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: {
-        x: rect.x,
-        y: rect.y,
-        width: rect.width,
-        height: rect.height,
-        scale,
+        ...clip.rect,
+        scale: 1,
       },
     });
     if (signal?.aborted) return cancelled("screenshot");
@@ -249,11 +215,11 @@ async function captureElementScreenshot(
     if (!image_base64) {
       return { code: "cdp_failed", message: "Page.captureScreenshot returned no data" };
     }
-    const dims = parsePngDimensions(image_base64);
-    if (!dims) {
-      return { code: "cdp_failed", message: "Page.captureScreenshot returned invalid PNG data" };
-    }
-    return { image_base64, width: dims.width, height: dims.height, topViewportRect };
+    const dims = parsePngDimensions(image_base64) ?? {
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+    };
+    return { image_base64, width: dims.width, height: dims.height };
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -348,7 +314,7 @@ export async function handleScreenshot(
     if (!deps.cdp) {
       return { code: "cdp_failed", message: "screenshot ref capture requires CDP" };
     }
-    const node = resolveSnapshotRef(ctx, ref, target.tabId, "screenshot");
+    const node = resolveSnapshotRef(ctx, ref, target.tabId);
     if (isRpcError(node)) return node;
     if (signal?.aborted) return cancelled("screenshot");
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
@@ -368,54 +334,18 @@ export async function handleScreenshot(
           nodeTarget,
           node.backendNodeId,
           node.frameId,
-          node.kind === "surface",
-          node.visibleRect,
           signal,
         ),
       deps.sendToTab,
     );
     if (isRpcError(captured)) return captured;
     if (signal?.aborted) return cancelled("screenshot");
-    const capture =
-      node.kind === "surface"
-        ? await (async () => {
-            const environment = await captureSurfaceEnvironment(cdp, target.tabId, node.frameId);
-            if (isRpcError(environment)) return environment;
-            return ctx.surfaceCaptures.create({
-              sessionId: ctx.sessionId,
-              tabId: target.tabId,
-              navigationIdentity: environment.navigationIdentity,
-              surface: {
-                ref: node.refKey,
-                ...(node.frameId ? { frameId: node.frameId } : {}),
-                backendNodeId: node.backendNodeId,
-                observationGeneration: node.generation,
-              },
-              topViewportRect: captured.topViewportRect,
-              imageWidth: captured.width,
-              imageHeight: captured.height,
-              viewportSignature: environment.viewportSignature,
-              frameProjectionSignature: environment.frameProjectionSignature,
-            });
-          })()
-        : null;
-    if (capture && isRpcError(capture)) return capture;
     return withShotDialogs({
       image_base64: captured.image_base64,
       width: captured.width,
       height: captured.height,
       format: "png",
       tab_id: target.tabId,
-      ...(capture
-        ? {
-            capture: {
-              id: capture.id,
-              surface_ref: `@${capture.surface.ref}`,
-              coordinate_space: "capture-image-pixel" as const,
-              expires_at: capture.expiresAt,
-            },
-          }
-        : {}),
     });
   }
 
@@ -435,10 +365,7 @@ export async function handleScreenshot(
   if (isRpcError(captured)) return captured;
   if (signal?.aborted) return cancelled("screenshot");
   const image_base64 = captured;
-  const dims = parsePngDimensions(image_base64);
-  if (!dims) {
-    return { code: "cdp_failed", message: "screenshot capture returned invalid PNG data" };
-  }
+  const dims = parsePngDimensions(image_base64) ?? { width: 0, height: 0 };
   return withShotDialogs({
     image_base64,
     width: dims.width,
@@ -749,6 +676,7 @@ 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()];
@@ -772,6 +700,7 @@ 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;
@@ -1058,26 +987,19 @@ 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 cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
+    const metrics = await geometry.layoutMetrics({ tabId });
     throwIfAborted(signal, "observation");
-    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-    viewport = {
-      width: source.clientWidth ?? 0,
-      height: source.clientHeight ?? 0,
-    };
+    const source = cssViewport(metrics);
+    viewport = { width: source.width, height: source.height };
   } catch (error) {
     if (isAbortError(error)) throw error;
   }
@@ -1090,12 +1012,13 @@ async function captureForVom(
   cdp: CdpRunner,
   tabId: number,
   options: CaptureVomObservationOptions,
+  geometry: GeometryContext,
 ): Promise<CapturedViewModel> {
   try {
-    return await captureViewModel(cdp, tabId, { signal: options.signal });
+    return await captureViewModel(cdp, tabId, { signal: options.signal, geometry });
   } catch (error) {
     if (isAbortError(error)) throw error;
-    return fallbackCapturedViewModel(cdp, tabId, options.signal);
+    return fallbackCapturedViewModel(cdp, tabId, geometry, options.signal);
   }
 }
 
@@ -1157,7 +1080,6 @@ async function runHoverProbes(
 
 export interface CaptureVomObservationOptions extends VomOptions {
   conditionalSurfaceProbe?: boolean;
-  renderedSurfaceDiscovery?: boolean;
   hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
   signal?: AbortSignal;
 }
@@ -1171,9 +1093,16 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   await cdp.ensureAttachedToUrl?.(tabId, url);
   throwIfAborted(options.signal, "observation");
-  const captured = await captureForVom(cdp, tabId, options);
+  const geometry = new GeometryContext(cdp, tabId, undefined, options.signal);
+  const captured = await captureForVom(cdp, tabId, options, geometry);
   throwIfAborted(options.signal, "observation");
-  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
+  const documents = await captureFrameData<CdpAxNode>(
+    cdp,
+    tabId,
+    captured,
+    options.signal,
+    geometry,
+  );
   throwIfAborted(options.signal, "observation");
   const normalizedDocuments =
     documents.length === 1 && captured.iframeNodes.size > 0
@@ -1206,25 +1135,21 @@ export async function captureVomObservation(
     captured,
     hoverProbes.surfaceProbes,
   );
-  const observedScene = options.renderedSurfaceDiscovery
-    ? projectRenderedSurfaces(
-        decoratedScene,
-        normalizedDocuments,
-        clusterRenderedSurfaces(
-          discoverRenderedSurfaces(
-            normalizedDocuments,
-            captured.viewport,
-            captured.excludedBackendNodeIds,
-          ),
-        ),
-      )
-    : decoratedScene;
-  const rendered = renderVom(observedScene, {
+  // 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 geometry incomplete: some page or frame content has no top-level coordinates.\n"
+    : "";
+  const rendered = renderVom(decoratedScene, {
     maxDepth: options.maxDepth,
-    maxTokens: options.maxTokens,
+    maxTokens:
+      !geometryNotice || options.maxTokens === undefined
+        ? options.maxTokens
+        : Math.max(0, options.maxTokens - Math.ceil(geometryNotice.length / 4)),
     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",
@@ -1274,7 +1199,6 @@ async function handleVomObservation(
       maxTokens: params.max_tokens,
       activeRegionPolicy: true,
       conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
-      renderedSurfaceDiscovery: toolName === "observe",
       hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
       signal,
     });
@@ -1292,9 +1216,6 @@ async function handleVomObservation(
             tabId: target.tabId,
             ...(ref.frameId ? { frameId: ref.frameId } : {}),
             ...(refTarget?.sessionId ? { cdpSessionId: refTarget.sessionId } : {}),
-            ...(ref.visibleRect ? { visibleRect: ref.visibleRect } : {}),
-            ...(ref.kind ? { kind: ref.kind } : {}),
-            ...(ref.capabilities ? { capabilities: ref.capabilities } : {}),
           },
         ] as const;
       }),

apps/extension/src/tools/session.ts

@@ -271,7 +271,6 @@ export async function handleSessionStop(
 
   // Step 2: clear the per-session RefStore (review M6/M7 parity).
   ctx.refStore.clear();
-  ctx.surfaceCaptures.clear();
 
   clearRecordingForSession(params.session_id);
 

apps/extension/src/tools/snapshot-ref.ts

@@ -2,9 +2,8 @@
 // compound CDP node identity via the session RefStore, and build stable
 // `ref_not_found` errors for hard-failure tool paths.
 
-import type { Rect } from "@browser-skill/vom";
 import type { SessionContext } from "@/session-manager/manager";
-import { normaliseRef, type RefCapability, type RefTargetKind } from "@/session-manager/ref-store";
+import { normaliseRef } from "@/session-manager/ref-store";
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";
 
@@ -13,10 +12,6 @@ export interface SnapshotRefLookup {
   refKey: string;
   frameId?: string;
   cdpSessionId?: string;
-  visibleRect?: Rect;
-  kind: RefTargetKind;
-  capabilities: RefCapability[];
-  generation: number;
 }
 
 function refEntryForTab(ctx: SessionContext, refKey: string, tabId: number) {
@@ -42,10 +37,6 @@ export function lookupSnapshotRef(
     refKey,
     ...(entry.frameId ? { frameId: entry.frameId } : {}),
     ...(entry.cdpSessionId ? { cdpSessionId: entry.cdpSessionId } : {}),
-    ...(entry.visibleRect ? { visibleRect: entry.visibleRect } : {}),
-    kind: entry.kind,
-    capabilities: entry.capabilities,
-    generation: entry.generation,
   };
 }
 
@@ -58,7 +49,6 @@ export function resolveSnapshotRef(
   ctx: SessionContext,
   ref: string,
   tabId: number,
-  requiredCapability?: RefCapability,
 ): SnapshotRefLookup | RpcError {
   const looked = lookupSnapshotRef(ctx, ref, tabId);
   if (looked === null) {
@@ -68,13 +58,5 @@ export function resolveSnapshotRef(
       `ref ${ref} unknown for tab ${tabId} in session ${ctx.sessionId}`,
     );
   }
-  if (requiredCapability && !looked.capabilities.includes(requiredCapability)) {
-    return rpcError(
-      "permission_denied",
-      "ref_capability_denied",
-      `ref ${ref} does not support ${requiredCapability}`,
-      { ref: looked.refKey, required_capability: requiredCapability, kind: looked.kind },
-    );
-  }
   return looked;
 }

apps/extension/src/tools/surface-coordinate.ts

@@ -1,88 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-import type { Point, Region, ViewportRect } from "./geometry";
-
-const RECT_EPSILON = 0.01;
-
-export function surfaceVisibleRect(
-  liveRect: ViewportRect,
-  observedRect: Rect | undefined,
-): Rect | null {
-  const observed = observedRect ?? {
-    x: liveRect.x,
-    y: liveRect.y,
-    w: liveRect.width,
-    h: liveRect.height,
-  };
-  const x = Math.max(liveRect.x, observed.x);
-  const y = Math.max(liveRect.y, observed.y);
-  const right = Math.min(liveRect.x + liveRect.width, observed.x + observed.w);
-  const bottom = Math.min(liveRect.y + liveRect.height, observed.y + observed.h);
-  return right > x && bottom > y ? { x, y, w: right - x, h: bottom - y } : null;
-}
-
-export function sameRect(a: Rect, b: Rect): boolean {
-  return (
-    Math.abs(a.x - b.x) <= RECT_EPSILON &&
-    Math.abs(a.y - b.y) <= RECT_EPSILON &&
-    Math.abs(a.w - b.w) <= RECT_EPSILON &&
-    Math.abs(a.h - b.h) <= RECT_EPSILON
-  );
-}
-
-export function mapImagePointToViewport(
-  rect: Rect,
-  imageWidth: number,
-  imageHeight: number,
-  imageX: number,
-  imageY: number,
-): Point | null {
-  if (
-    !Number.isFinite(imageX) ||
-    !Number.isFinite(imageY) ||
-    !Number.isSafeInteger(imageWidth) ||
-    !Number.isSafeInteger(imageHeight) ||
-    imageWidth <= 0 ||
-    imageHeight <= 0 ||
-    imageX < 0 ||
-    imageY < 0 ||
-    imageX >= imageWidth ||
-    imageY >= imageHeight ||
-    !Number.isFinite(rect.x) ||
-    !Number.isFinite(rect.y) ||
-    !Number.isFinite(rect.w) ||
-    !Number.isFinite(rect.h) ||
-    rect.w <= 0 ||
-    rect.h <= 0
-  ) {
-    return null;
-  }
-  return {
-    x: rect.x + (imageX / imageWidth) * rect.w,
-    y: rect.y + (imageY / imageHeight) * rect.h,
-  };
-}
-
-function pointInPolygon(point: Point, polygon: Point[]): boolean {
-  for (let index = 0; index < polygon.length; index += 1) {
-    const a = polygon[index];
-    const b = polygon[(index + 1) % polygon.length];
-    const cross = (point.x - a.x) * (b.y - a.y) - (point.y - a.y) * (b.x - a.x);
-    const withinX = point.x >= Math.min(a.x, b.x) - 1e-9 && point.x <= Math.max(a.x, b.x) + 1e-9;
-    const withinY = point.y >= Math.min(a.y, b.y) - 1e-9 && point.y <= Math.max(a.y, b.y) + 1e-9;
-    if (Math.abs(cross) <= 1e-9 && withinX && withinY) return true;
-  }
-  let inside = false;
-  for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
-    const a = polygon[index];
-    const b = polygon[previous];
-    const intersects =
-      a.y > point.y !== b.y > point.y &&
-      point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x;
-    if (intersects) inside = !inside;
-  }
-  return inside;
-}
-
-export function pointInRegion(point: Point, region: Region): boolean {
-  return region.some((polygon) => polygon.length >= 3 && pointInPolygon(point, polygon));
-}

apps/extension/src/tools/surface-target.ts

@@ -1,260 +0,0 @@
-import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import type { SessionContext } from "@/session-manager/manager";
-import type { RpcError } from "@/transport/types";
-import { rpcError } from "./errors";
-import { resolveNodeGeometry } from "./frame-geometry";
-import { type CdpRunner, isRpcError, normaliseRef } from "./shared";
-import { resolveSnapshotRef } from "./snapshot-ref";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "./surface-coordinate";
-
-export interface SurfaceCaptureEnvironment {
-  navigationIdentity: string;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-}
-
-export interface SurfaceTargetResolverDeps {
-  cdp: CdpRunner;
-  signal?: AbortSignal;
-}
-
-export interface SurfacePointerTargetInput {
-  ref?: string;
-  selector?: string;
-  captureId?: string;
-  imageX?: number;
-  imageY?: number;
-}
-
-export interface ResolvedSurfacePointerTarget {
-  point: { x: number; y: number };
-  usedRef: string;
-  moveSettleMs: number;
-  capture: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
-// Canvas-style controls commonly update their pointer hit-test on the next
-// animation frame. Leave a scheduling boundary after moving and before pressing.
-export const SURFACE_POINTER_MOVE_SETTLE_MS = 32;
-
-function stale(message: string): RpcError {
-  return rpcError("permission_denied", "surface_capture_stale", message);
-}
-
-function finiteObject(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(finiteObject);
-  if (typeof value !== "object" || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .filter(
-        ([, entry]) => entry !== undefined && (typeof entry !== "number" || Number.isFinite(entry)),
-      )
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([key, entry]) => [key, finiteObject(entry)]),
-  );
-}
-
-function framePathSignature(graph: CdpFrameGraph, frameId: string | undefined): string | null {
-  if (!frameId) return "top";
-  const frames = new Map(graph.frames.map((frame) => [frame.frameId, frame]));
-  const path: Array<{
-    frameId: string;
-    parentFrameId?: string;
-    ownerBackendNodeId?: number;
-    targetSessionId?: string;
-  }> = [];
-  const seen = new Set<string>();
-  let current = frames.get(frameId);
-  while (current) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    path.push({
-      frameId: current.frameId,
-      ...(current.parentFrameId ? { parentFrameId: current.parentFrameId } : {}),
-      ...(current.ownerBackendNodeId !== undefined
-        ? { ownerBackendNodeId: current.ownerBackendNodeId }
-        : {}),
-      ...(current.target.sessionId ? { targetSessionId: current.target.sessionId } : {}),
-    });
-    if (!current.parentFrameId) return JSON.stringify(path);
-    const parent = frames.get(current.parentFrameId);
-    if (!parent) return null;
-    current = parent;
-  }
-  return null;
-}
-
-export async function captureSurfaceEnvironment(
-  cdp: CdpRunner,
-  tabId: number,
-  frameId: string | undefined,
-): Promise<SurfaceCaptureEnvironment | RpcError> {
-  try {
-    const [tree, metrics, graph] = await Promise.all([
-      cdp.send<{
-        frameTree?: { frame?: { id?: string; loaderId?: string; url?: string } };
-      }>(tabId, "Page.getFrameTree", {}),
-      cdp.send<Record<string, unknown>>(tabId, "Page.getLayoutMetrics", {}),
-      frameId && cdp.getFrameGraph ? cdp.getFrameGraph(tabId) : Promise.resolve(null),
-    ]);
-    const root = tree.frameTree?.frame;
-    if (!root?.id || !root.loaderId) {
-      return { code: "cdp_failed", message: "could not identify the current navigation" };
-    }
-    const frameProjectionSignature = frameId
-      ? graph
-        ? framePathSignature(graph, frameId)
-        : null
-      : "top";
-    if (!frameProjectionSignature) {
-      return { code: "cdp_failed", message: `could not identify frame projection for ${frameId}` };
-    }
-    return {
-      navigationIdentity: JSON.stringify({ id: root.id, loaderId: root.loaderId, url: root.url }),
-      viewportSignature: JSON.stringify(
-        finiteObject({
-          cssLayoutViewport: metrics.cssLayoutViewport,
-          cssVisualViewport: metrics.cssVisualViewport,
-        }),
-      ),
-      frameProjectionSignature,
-    };
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-}
-
-function validatePointParams(input: SurfacePointerTargetInput): RpcError | null {
-  if (!input.captureId || typeof input.captureId !== "string") {
-    return { code: "invalid_params", message: "surface point click requires capture_id" };
-  }
-  if (typeof input.imageX !== "number" || !Number.isFinite(input.imageX)) {
-    return { code: "invalid_params", message: "image_x must be a finite number" };
-  }
-  if (typeof input.imageY !== "number" || !Number.isFinite(input.imageY)) {
-    return { code: "invalid_params", message: "image_y must be a finite number" };
-  }
-  if (!input.ref || input.selector) {
-    return {
-      code: "invalid_params",
-      message: "surface point click requires one Surface ref and does not accept a selector",
-    };
-  }
-  return null;
-}
-
-function captureConsumeError(reason: "not_found" | "expired" | "consumed"): RpcError {
-  const code = reason === "not_found" ? "not_found" : "permission_denied";
-  return rpcError(code, `surface_capture_${reason}`, `surface capture is ${reason}`);
-}
-
-function aborted(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted
-    ? { code: "cancelled", message: "surface target resolution aborted" }
-    : null;
-}
-
-/** Resolve one fresh Surface capture coordinate into a validated top-viewport pointer target. */
-export async function resolveSurfacePointerTarget(
-  ctx: SessionContext,
-  target: { tabId: number; url?: string },
-  input: SurfacePointerTargetInput,
-  deps: SurfaceTargetResolverDeps,
-): Promise<ResolvedSurfacePointerTarget | RpcError> {
-  const invalid = validatePointParams(input);
-  if (invalid) return invalid;
-  const earlyAbort = aborted(deps.signal);
-  if (earlyAbort) return earlyAbort;
-
-  const consumed = ctx.surfaceCaptures.consume(input.captureId as string);
-  if (!consumed.ok) return captureConsumeError(consumed.reason);
-  const capture = consumed.capture;
-  const postConsumeAbort = aborted(deps.signal);
-  if (postConsumeAbort) return postConsumeAbort;
-
-  if (capture.sessionId !== ctx.sessionId || capture.tabId !== target.tabId) {
-    return stale("surface capture belongs to a different session or tab");
-  }
-  if (normaliseRef(input.ref as string) !== capture.surface.ref) {
-    return stale("surface ref does not match the capture");
-  }
-  const node = resolveSnapshotRef(ctx, input.ref as string, target.tabId, "screenshot");
-  if (isRpcError(node)) return stale(node.message);
-  if (
-    node.kind !== "surface" ||
-    node.backendNodeId !== capture.surface.backendNodeId ||
-    node.frameId !== capture.surface.frameId ||
-    node.generation !== capture.surface.observationGeneration
-  ) {
-    return stale("surface observation generation or node identity changed");
-  }
-
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  try {
-    await deps.cdp.ensureAttachedToUrl?.(target.tabId, target.url);
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-  const environment = await captureSurfaceEnvironment(deps.cdp, target.tabId, node.frameId);
-  if (isRpcError(environment)) return environment;
-  if (
-    environment.navigationIdentity !== capture.navigationIdentity ||
-    environment.viewportSignature !== capture.viewportSignature ||
-    environment.frameProjectionSignature !== capture.frameProjectionSignature
-  ) {
-    return stale("navigation, viewport, zoom, scroll, or frame projection changed");
-  }
-
-  const geometry = await resolveNodeGeometry(
-    deps.cdp,
-    target.tabId,
-    {
-      target: {
-        tabId: target.tabId,
-        ...(node.cdpSessionId ? { sessionId: node.cdpSessionId } : {}),
-      },
-      backendNodeId: node.backendNodeId,
-      ...(node.frameId ? { frameId: node.frameId } : {}),
-    },
-    { scrollIntoView: false },
-  );
-  if (isRpcError(geometry)) return stale(geometry.message);
-  const currentRect = surfaceVisibleRect(geometry.topBounds, node.visibleRect);
-  if (!currentRect || !sameRect(currentRect, capture.topViewportRect)) {
-    return stale("surface visible region changed");
-  }
-  const point = mapImagePointToViewport(
-    capture.topViewportRect,
-    capture.imageWidth,
-    capture.imageHeight,
-    input.imageX as number,
-    input.imageY as number,
-  );
-  if (!point || !pointInRegion(point, geometry.topVisibleRegions)) {
-    return rpcError(
-      "invalid_params",
-      "surface_coordinate_invalid",
-      "image coordinate is outside the captured Surface",
-    );
-  }
-
-  return {
-    point,
-    usedRef: capture.surface.ref,
-    moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-    capture: {
-      id: capture.id,
-      imageX: input.imageX as number,
-      imageY: input.imageY as number,
-    },
-  };
-}

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

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
+import type { CdpRunner } from "../../shared";
 import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
-import { discoverRenderedSurfaces } from "../rendered-surfaces";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
 // fixed full-screen overlay div carrying a password input.
@@ -211,7 +211,11 @@ function makeCdp(snapshot: unknown) {
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") return snapshot;
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "Runtime.evaluate") {
         return {
@@ -299,6 +303,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return hoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -362,6 +368,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return twoHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -410,6 +418,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return nestedHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -528,6 +538,9 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
+          frameId: "main",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -558,8 +571,12 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
+    const { excludedBackendNodeIds, frameExcludedBackendNodeIds } = await captureViewModel(
+      makeCdp(snapshot),
+      4,
+    );
     expect(excludedBackendNodeIds).toEqual(new Set([13, 14, 15]));
+    expect(frameExcludedBackendNodeIds?.get("main")).toEqual(excludedBackendNodeIds);
   });
 
   it("excludes overlay host matched by tag name only", async () => {
@@ -736,44 +753,6 @@ describe("captureViewModel", () => {
     expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
   });
 
-  it("propagates fully transparent ancestor suppression to painted descendants", async () => {
-    const S = ["html", "body", "div", "canvas", "static", "auto", "visible", "1", "0"];
-    const i = (value: string) => S.indexOf(value);
-    const snapshot = {
-      strings: S,
-      documents: [
-        {
-          nodes: {
-            parentIndex: [-1, 0, 1, 2],
-            nodeName: [i("html"), i("body"), i("div"), i("canvas")],
-            backendNodeId: [10, 11, 12, 13],
-            attributes: [[], [], [], []],
-          },
-          layout: {
-            nodeIndex: [1, 2, 3],
-            styles: [
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-            ],
-            bounds: [
-              [0, 0, 1000, 800],
-              [10, 10, 200, 100],
-              [10, 10, 200, 100],
-            ],
-            paintOrders: [0, 1, 2],
-          },
-        },
-      ],
-    };
-
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
-    const canvas = nodes.find((node) => node.backendNodeId === 13);
-
-    expect(canvas?.rendered).toBe(true);
-    expect(canvas?.visuallySuppressed).toBe(true);
-  });
-
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {
@@ -781,6 +760,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return fakeSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 200 },
           };
         }
@@ -793,7 +774,46 @@ describe("captureViewModel", () => {
     expect(div?.rect).toMatchObject({ y: 0, h: 600 });
   });
 
-  it("normalizes device-pixel bounds by devicePixelRatio", async () => {
+  it("normalizes snapshot-owned scroll before using a stale CSS metrics fallback", async () => {
+    const snapshot = {
+      strings: ["html", "button"],
+      documents: [
+        {
+          frameId: "root",
+          scrollOffsetX: 40,
+          scrollOffsetY: 200,
+          nodes: {
+            parentIndex: [-1, 0],
+            nodeName: [0, 1],
+            backendNodeId: [10, 11],
+            attributes: [[], []],
+          },
+          layout: { nodeIndex: [1], bounds: [[200, 800, 240, 80]] },
+        },
+      ],
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tab: number, method: string) => {
+        if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+        if (method === "Page.getLayoutMetrics")
+          return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 999, pageY: 999 },
+          };
+        return {};
+      }) as CdpRunner["send"],
+    };
+    const captured = await captureViewModel(cdp, 4);
+    expect(captured.nodes.find((node) => node.backendNodeId === 11)).toMatchObject({
+      localRect: { x: 80, y: 300, w: 120, h: 40 },
+      rect: { x: 80, y: 300, w: 120, h: 40 },
+      rendered: true,
+    });
+    expect(captured.frameGeometryIssues).toEqual([]);
+  });
+
+  it("normalizes raw snapshot bounds before viewport clipping", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
@@ -827,6 +847,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -841,6 +863,12 @@ describe("captureViewModel", () => {
       w: 1000,
       h: 800,
     });
+    expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
+      x: 0,
+      y: 0,
+      w: 1000,
+      h: 800,
+    });
   });
 
   it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -896,6 +924,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -986,9 +1016,17 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        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>,
     };
@@ -1018,7 +1056,7 @@ describe("captureViewModel", () => {
     expect(frameParentIds?.get("child-frame")).toBe("main-frame");
   });
 
-  it("captures iframe documents without requiring owner-frame geometry", async () => {
+  it("projects iframe documents independently of owner snapshot geometry", async () => {
     const S = [
       "html",
       "body",
@@ -1076,9 +1114,17 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        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>,
     };
@@ -1087,7 +1133,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).toBeNull();
+    expect(input?.rect).toEqual({ x: 120, y: 320, w: 120, h: 60 });
   });
 
   it("recursively normalizes nested iframe sub-documents", async () => {
@@ -1129,6 +1175,8 @@ describe("captureViewModel", () => {
           },
         },
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1150,6 +1198,8 @@ describe("captureViewModel", () => {
           },
         },
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
           nodes: {
             parentIndex: [-1, 0],
             nodeName: [i("body"), i("input")],
@@ -1166,16 +1216,45 @@ describe("captureViewModel", () => {
       ],
     };
     const cdp = {
-      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>,
+      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 {
+              visualViewport: { clientWidth: 1000 },
+              cssVisualViewport: { clientWidth: 1000 },
+              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>,
     };
 
     const { iframeNodes } = await captureViewModel(cdp, 4);
@@ -1189,98 +1268,7 @@ describe("captureViewModel", () => {
     expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
   });
 
-  it("keeps same-origin iframe canvas discovery in top-level CSS coordinates at dpr 1 and 2", async () => {
-    const captureAtDpr = async (dpr: number) => {
-      const S = ["html", "body", "iframe", "canvas", "static", "auto"];
-      const i = (s: string) => S.indexOf(s);
-      const scale = (values: number[]) => values.map((value) => value * dpr);
-      const snapshot = {
-        strings: S,
-        documents: [
-          {
-            frameId: "main",
-            nodes: {
-              parentIndex: [-1, 0, 1],
-              nodeName: [i("html"), i("body"), i("iframe")],
-              backendNodeId: [10, 11, 13],
-              attributes: [[], [], []],
-              contentDocumentIndex: { index: [2], value: [1] },
-            },
-            layout: {
-              nodeIndex: [1, 2],
-              styles: [
-                [i("static"), i("auto")],
-                [i("static"), i("auto")],
-              ],
-              bounds: [scale([0, 0, 1000, 800]), scale([100, 150, 300, 200])],
-              paintOrders: [0, 1],
-            },
-          },
-          {
-            frameId: "child",
-            nodes: {
-              parentIndex: [-1, 0],
-              nodeName: [i("body"), i("canvas")],
-              backendNodeId: [20, 21],
-              attributes: [[], []],
-            },
-            layout: {
-              nodeIndex: [0, 1],
-              styles: [
-                [i("static"), i("auto")],
-                [i("static"), i("auto")],
-              ],
-              bounds: [scale([0, 0, 300, 200]), scale([20, 30, 120, 60])],
-              paintOrders: [0, 1],
-            },
-          },
-        ],
-      };
-      const cdp = {
-        send: vi.fn(async (_tabId: 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 },
-              layoutViewport: { clientWidth: 1000 * dpr, clientHeight: 800 * dpr },
-            };
-          }
-          throw new Error(method);
-        }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
-      };
-      const captured = await captureViewModel(cdp, 4);
-      const childNodes = captured.frameNodes?.get("child") ?? [];
-      return discoverRenderedSurfaces(
-        [
-          {
-            frameId: "child",
-            contextScopeId: "child",
-            parentFrameId: "main",
-            ownerBackendNodeId: 13,
-            target: { tabId: 4 },
-            domNodes: childNodes,
-            axNodes: [],
-          },
-        ],
-        captured.viewport,
-      );
-    };
-
-    const atDpr1 = await captureAtDpr(1);
-    const atDpr2 = await captureAtDpr(2);
-
-    expect(atDpr1).toEqual([
-      expect.objectContaining({
-        backendNodeId: 21,
-        frameId: "child",
-        visibleRect: { x: 120, y: 180, w: 120, h: 60 },
-      }),
-    ]);
-    expect(atDpr2).toEqual(atDpr1);
-  });
-
-  it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
+  it("subtracts CSS scroll once without dividing snapshot bounds by a metrics ratio", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
@@ -1314,6 +1302,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 100 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -1347,3 +1337,200 @@ 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[]) => ({
+    scrollOffsetX: 0,
+    scrollOffsetY: 0,
+    frameId: `frame-${id}`,
+    nodes: {
+      parentIndex: [-1, ...owners.map(() => 0)],
+      nodeName: [0, ...owners.map(() => 1)],
+      backendNodeId: [1000 + id, ...owners],
+      attributes: [[], ...owners.map(() => [])],
+      contentDocumentIndex: { index: owners.map((_, i) => i + 1), value: childIndexes },
+    },
+    layout: {
+      nodeIndex: [0, ...owners.map((_, i) => i + 1)],
+      bounds: [[0, 0, 200, 100], ...owners.map(() => [0, 0, 200, 100])],
+    },
+  });
+  const snapshot = {
+    strings: ["body", "iframe"],
+    documents: [
+      document(0, [100, 101, 102, 103, 104, 105], [1, 2, 3, 4, 5, 6]),
+      document(1, [200], [7]),
+      ...Array.from({ length: 6 }, (_, i) => document(i + 2, [], [])),
+    ],
+  };
+  let active = 0;
+  let peak = 0;
+  const send = vi.fn(async (_tabId: number, method: string, params: object = {}) => {
+    const args = params as Record<string, unknown>;
+    active++;
+    peak = Math.max(peak, active);
+    try {
+      await beforeReply(method, args);
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "Page.getLayoutMetrics")
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+        };
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [0, 0, 200, 0, 200, 100, 0, 100] } };
+      if (method === "DOM.resolveNode") return { object: { objectId: String(args.backendNodeId) } };
+      if (method === "Runtime.callFunctionOn")
+        return { result: { value: { width: 200, height: 100 } } };
+      return {};
+    } finally {
+      active--;
+    }
+  });
+  return {
+    cdp: { send: send as CdpRunner["send"] },
+    send,
+    peak: () => peak,
+    active: () => active,
+    measured: () =>
+      send.mock.calls
+        .filter(([, method]) => method === "DOM.getBoxModel")
+        .map(([, , params]) => (params as { backendNodeId: number }).backendNodeId),
+  };
+}
+
+describe("sibling frame measurement scheduling", () => {
+  it("batches same-target owner sizes without changing projected results", async () => {
+    const fixture = siblingCaptureFixture();
+    const original = fixture.cdp.send;
+    const methods: string[] = [];
+    fixture.cdp.send = async (tabId, method, params) => {
+      methods.push(method);
+      if (method === "Runtime.evaluate")
+        return {
+          result: {
+            deepSerializedValue: {
+              type: "array",
+              value: [100, 101, 102, 103, 104, 105, 200].map((backendNodeId) => ({
+                type: "array",
+                value: [
+                  { type: "node", value: { backendNodeId } },
+                  { type: "string", value: JSON.stringify({ width: 200, height: 100 }) },
+                ],
+              })),
+            },
+          },
+        } as never;
+      return original(tabId, method, params);
+    };
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect(methods.filter((method) => method === "DOM.getBoxModel")).toHaveLength(7);
+    expect(methods.filter((method) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(methods.filter((method) => method === "Runtime.releaseObjectGroup")).toHaveLength(1);
+    expect(methods).not.toContain("DOM.resolveNode");
+    expect(methods).not.toContain("Runtime.callFunctionOn");
+  });
+
+  it("bounds concurrent reads, fills free slots and preserves depth-first output despite reordered replies", async () => {
+    const pending = new Map<number, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.getBoxModel" && Number(params.backendNodeId) < 200)
+        await new Promise<void>((resolve) => pending.set(Number(params.backendNodeId), resolve));
+    });
+    const capture = captureViewModel(fixture.cdp, 4);
+    await vi.waitFor(() => expect(pending.size).toBe(4));
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    pending.get(103)!();
+    await vi.waitFor(() => expect(pending.has(104)).toBe(true));
+    pending.get(104)!();
+    await vi.waitFor(() => expect(pending.has(105)).toBe(true));
+    expect(fixture.measured()).not.toContain(200);
+    for (const id of [105, 102, 101, 100]) pending.get(id)!();
+    const captured = await capture;
+    expect(captured.frameGeometryIssues).toEqual([]);
+    expect(fixture.peak()).toBe(4);
+    expect(fixture.active()).toBe(0);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103, 104, 105, 200]);
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+    expect(captured.iframeNodes.get(200)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    for (const method of [
+      "DOM.getBoxModel",
+      "DOM.resolveNode",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObject",
+    ])
+      expect(fixture.send.mock.calls.filter(([, name]) => name === method)).toHaveLength(7);
+  });
+
+  it("does not measure descendants of a failed owner and retains sibling geometry and local nodes", async () => {
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode" && params.backendNodeId === 100)
+        throw new Error("owner replaced");
+    });
+    const captured = await captureViewModel(fixture.cdp, 4);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4 }, frameId: "frame-1" },
+        ownerBackendNodeId: 100,
+      },
+      {
+        status: "blocked",
+        source: { target: { tabId: 4 }, frameId: "frame-7" },
+        cause: captured.frameGeometryIssues?.[0],
+      },
+    ]);
+    expect(fixture.measured()).not.toContain(200);
+    expect(captured.iframeNodes.get(200)?.[0]).toMatchObject({
+      tag: "body",
+      rect: null,
+      localRect: { x: 0, y: 0, w: 200, h: 100 },
+    });
+    expect(captured.iframeNodes.get(101)?.[0].rect).toEqual({ x: 0, y: 0, w: 200, h: 100 });
+    expect([...captured.iframeNodes.keys()]).toEqual([100, 200, 101, 102, 103, 104, 105]);
+  });
+
+  it("stops scheduling on cancellation and waits for resolved objects to be released", async () => {
+    const controller = new AbortController();
+    const resolutions = new Map<string, () => void>();
+    const releases = new Map<string, () => void>();
+    const fixture = siblingCaptureFixture(async (method, params) => {
+      if (method === "DOM.resolveNode")
+        await new Promise<void>((resolve) =>
+          resolutions.set(String(params.backendNodeId), resolve),
+        );
+      if (method === "Runtime.releaseObject")
+        await new Promise<void>((resolve) => releases.set(String(params.objectId), resolve));
+    });
+    let settled = false;
+    const capture = captureViewModel(fixture.cdp, 4, { signal: controller.signal });
+    const rejected = expect(capture).rejects.toMatchObject({ name: "AbortError" });
+    void capture.then(
+      () => {
+        settled = true;
+      },
+      () => {
+        settled = true;
+      },
+    );
+    await vi.waitFor(() => expect(resolutions.size).toBe(4));
+    controller.abort();
+    for (const resolve of resolutions.values()) resolve();
+    await vi.waitFor(() => expect(releases.size).toBe(4));
+    expect(settled).toBe(false);
+    expect(fixture.measured()).toEqual([100, 101, 102, 103]);
+    for (const release of releases.values()) release();
+    await rejected;
+    expect(fixture.active()).toBe(0);
+    expect(fixture.send.mock.calls.some(([, method]) => method === "Runtime.callFunctionOn")).toBe(
+      false,
+    );
+  });
+});

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

@@ -0,0 +1,127 @@
+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-layout",
+      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);
+  });
+});

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

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

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

@@ -1,4 +1,5 @@
 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";
@@ -25,12 +26,14 @@ function childSnapshot(frameId: string, backendNodeId: number) {
     strings,
     documents: [
       {
+        scrollOffsetX: 0,
+        scrollOffsetY: 0,
         frameId,
         nodes: {
           parentIndex: [-1, 0],
           nodeName: [1, 2],
           backendNodeId: [backendNodeId - 1, backendNodeId],
-          attributes: [[], []],
+          attributes: [[], []] as number[][],
         },
         layout: {
           nodeIndex: [0, 1],
@@ -50,6 +53,72 @@ 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 {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 300, clientHeight: 200 },
+        };
+      if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [50, 100, 350, 100, 350, 300, 50, 300] } };
+      if (method === "DOM.resolveNode") throw new Error("nested owner replaced");
+      return {};
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(reply) as CdpRunner["send"],
+      sendToTarget: vi.fn(reply) as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+    await captureFrameData(cdp, 4, captured);
+    expect(captured.frameGeometryIssues).toEqual([
+      {
+        status: "unavailable",
+        source: { target: { tabId: 4, sessionId: "child-session" }, frameId: "nested" },
+        ownerBackendNodeId: 101,
+      },
+    ]);
+    expect(captured.frameNodes?.get("nested")?.[1]).toMatchObject({
+      rect: null,
+      localRect: { x: 10, y: 20, w: 100, h: 40 },
+    });
+  });
+
   it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
     const leftOwner = ownerNode(10, 50);
     const rightOwner = ownerNode(20, 500);
@@ -64,13 +133,23 @@ describe("captureFrameData", () => {
     };
     const sendToTarget = vi.fn(async (target, method) => {
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") {
-        return target.sessionId === "left-session"
-          ? childSnapshot("left", 101)
-          : childSnapshot("right", 201);
+        if (target.sessionId !== "left-session") return childSnapshot("right", 201);
+        const snapshot = childSnapshot("left", 101);
+        const marker = snapshot.strings.push(OVERLAY_HOST_MARKER_ATTR) - 1;
+        const nodes = snapshot.documents[0].nodes;
+        nodes.backendNodeId.push(201); // Same id as a real button in the other target.
+        nodes.parentIndex.push(0);
+        nodes.nodeName.push(2);
+        nodes.attributes.push([marker, -1]);
+        return snapshot;
       }
       if (method === "Accessibility.getFullAXTree") return { nodes: [] };
       throw new Error(`unexpected ${method}`);
@@ -85,7 +164,11 @@ describe("captureFrameData", () => {
           return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
         }
         if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+          return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+          };
         }
         throw new Error(`unexpected root ${method}`);
       }) as CdpRunner["send"],
@@ -112,6 +195,10 @@ 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,
@@ -149,7 +236,11 @@ describe("captureFrameData", () => {
         if (method === "Accessibility.getFullAXTree") return { nodes: [] };
         if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
         if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+          return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
+          };
         }
         throw new Error(`unexpected root ${method}`);
       }) as CdpRunner["send"],
@@ -192,7 +283,7 @@ describe("captureFrameData", () => {
       expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
     ]);
     expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
-      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
+      expect.objectContaining({ rect: null, localRect: null, rendered: true }),
     );
   });
 });

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

@@ -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", () => {
+  it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", async () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -54,7 +54,7 @@ describe("buildFrameDocuments", () => {
       },
     ];
 
-    const documents = buildFrameDocuments(
+    const documents = await 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", () => {
+  it("deduplicates overlapping same-target AX results using the strongest ownership", async () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -92,7 +92,7 @@ describe("buildFrameDocuments", () => {
       },
     ];
 
-    const documents = buildFrameDocuments(
+    const documents = await 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", () => {
+  it("uses target-scoped backend ownership when OOPIF backend ids collide", async () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -129,7 +129,7 @@ describe("buildFrameDocuments", () => {
       nodes: [{ nodeId: `${frame.frameId}-node`, backendDOMNodeId: 7 }],
     }));
 
-    const documents = buildFrameDocuments(
+    const documents = await buildFrameDocuments(
       graph,
       batches,
       captured(
@@ -149,7 +149,7 @@ describe("buildFrameDocuments", () => {
     );
   });
 
-  it("uses captured frame parent identity instead of guessing from backend ids", () => {
+  it("uses captured frame parent identity instead of guessing from backend ids", async () => {
     const frameNodes = new Map([
       ["main", [domNode("main", 1)]],
       ["left", [domNode("left", 7)]],
@@ -164,11 +164,25 @@ describe("buildFrameDocuments", () => {
       nodes: [],
     }));
 
-    const documents = buildFrameDocuments(null, frames, capture);
+    const documents = await 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");
+  });
 });

apps/extension/src/tools/vom/__tests__/rendered-surfaces.test.ts

@@ -1,256 +0,0 @@
-import type { VomScene } from "@browser-skill/vom";
-import { describe, expect, it } from "vitest";
-import type { CapturedNode } from "../capture";
-import type { CapturedFrameDocument } from "../frame-capture";
-import {
-  clusterRenderedSurfaces,
-  discoverRenderedSurfaces,
-  projectRenderedSurfaces,
-} from "../rendered-surfaces";
-import type { SemanticAxNode } from "../semantic-graph";
-
-function domNode(backendNodeId: number, overrides: Partial<CapturedNode> = {}): CapturedNode {
-  return {
-    backendNodeId,
-    parentBackendNodeId: null,
-    frameId: "main",
-    ownerFrameBackendNodeId: null,
-    tag: "canvas",
-    attrs: {},
-    rect: { x: 10, y: 20, w: 800, h: 500 },
-    localRect: { x: 10, y: 20, w: 800, h: 500 },
-    paintOrder: 1,
-    position: "static",
-    pointerEvents: "auto",
-    rendered: true,
-    ...overrides,
-  };
-}
-
-function document(
-  domNodes: CapturedNode[],
-  axNodes: SemanticAxNode[] = [],
-): CapturedFrameDocument<SemanticAxNode> {
-  return {
-    frameId: domNodes[0]?.frameId ?? "main",
-    contextScopeId: domNodes[0]?.frameId ?? "main",
-    target: { tabId: 4 },
-    domNodes,
-    axNodes,
-  };
-}
-
-describe("rendered surface discovery", () => {
-  it("finds prominent rendered canvases and excludes hidden descendants", () => {
-    const visible = domNode(2, { parentBackendNodeId: 1 });
-    const hidden = domNode(3, { parentBackendNodeId: 4 });
-    const surfaces = discoverRenderedSurfaces(
-      [
-        document([
-          domNode(1, { tag: "main", rect: null, localRect: null }),
-          visible,
-          domNode(4, { tag: "section", attrs: { "aria-hidden": "true" }, rect: null }),
-          hidden,
-        ]),
-      ],
-      { width: 1280, height: 720 },
-    );
-
-    expect(surfaces).toHaveLength(1);
-    expect(surfaces[0]).toMatchObject({ backendNodeId: 2 });
-  });
-
-  it("keeps tiny canvases as individually addressable exact discoveries", () => {
-    const surfaces = discoverRenderedSurfaces(
-      [document([domNode(2, { rect: { x: 1, y: 1, w: 8, h: 8 } })])],
-      { width: 1280, height: 720 },
-    );
-    expect(surfaces).toEqual([expect.objectContaining({ backendNodeId: 2 })]);
-  });
-
-  it("keeps a surface when the canvas only has partial native accessibility content", () => {
-    const axNodes = [
-      {
-        nodeId: "canvas",
-        backendDOMNodeId: 2,
-        role: { type: "role", value: "presentation" },
-        childIds: ["button"],
-        frameId: "main",
-      },
-      {
-        nodeId: "button",
-        backendDOMNodeId: 3,
-        role: { type: "role", value: "button" },
-        frameId: "main",
-      },
-    ] as SemanticAxNode[];
-    expect(
-      discoverRenderedSurfaces([document([domNode(2)], axNodes)], { width: 1280, height: 720 }),
-    ).toEqual([expect.objectContaining({ backendNodeId: 2 })]);
-  });
-
-  it("discovers unnamed canvases without guessing labels from engineering attributes", () => {
-    const canvas = domNode(2, {
-      attrs: {
-        id: "must-not-be-a-label",
-        class: "must-not-be-a-label",
-        "data-testid": "must-not-be-a-label",
-      },
-    });
-
-    expect(discoverRenderedSurfaces([document([canvas])], { width: 1280, height: 720 })).toEqual([
-      expect.not.objectContaining({
-        label: expect.anything(),
-      }),
-    ]);
-  });
-
-  it("treats blank explicit Canvas names as unnamed", () => {
-    expect(
-      discoverRenderedSurfaces(
-        [document([domNode(2, { attrs: { "aria-label": "   ", title: "\n\t" } })])],
-        { width: 1280, height: 720 },
-      ),
-    ).toEqual([expect.not.objectContaining({ label: expect.anything() })]);
-  });
-
-  it("excludes canvases inside BrowserSkill-owned DOM subtrees", () => {
-    const owner = domNode(1, { tag: "div", rect: null, localRect: null });
-    const canvas = domNode(2, { parentBackendNodeId: 1 });
-
-    expect(
-      discoverRenderedSurfaces(
-        [document([owner, canvas])],
-        { width: 1280, height: 720 },
-        new Set([1]),
-      ),
-    ).toEqual([]);
-  });
-
-  it("excludes canvases suppressed by a fully transparent ancestor", () => {
-    const owner = domNode(1, {
-      tag: "div",
-      rect: { x: 0, y: 0, w: 900, h: 600 },
-      visuallySuppressed: true,
-    });
-    const canvas = domNode(2, { parentBackendNodeId: 1 });
-
-    expect(
-      discoverRenderedSurfaces([document([owner, canvas])], { width: 1280, height: 720 }),
-    ).toEqual([]);
-  });
-
-  it("clips canvases to overflow ancestors and drops fully clipped canvases", () => {
-    const owner = domNode(1, {
-      tag: "div",
-      rect: { x: 10, y: 20, w: 100, h: 70 },
-      overflowX: "hidden",
-      overflowY: "hidden",
-    });
-    const partial = domNode(2, {
-      parentBackendNodeId: 1,
-      rect: { x: 55, y: 30, w: 140, h: 60 },
-    });
-    const fullyClipped = domNode(3, {
-      parentBackendNodeId: 1,
-      rect: { x: 140, y: 30, w: 80, h: 50 },
-    });
-
-    expect(
-      discoverRenderedSurfaces([document([owner, partial, fullyClipped])], {
-        width: 1280,
-        height: 720,
-      }),
-    ).toEqual([
-      expect.objectContaining({
-        backendNodeId: 2,
-        visibleRect: { x: 55, y: 30, w: 55, h: 60 },
-      }),
-    ]);
-  });
-});
-
-describe("rendered surface clustering and projection", () => {
-  it("collapses overlapping canvas layers and attaches them to the nearest retained parent", () => {
-    const body = domNode(1, { tag: "body", rect: null, localRect: null });
-    const surfaces = discoverRenderedSurfaces(
-      [
-        document([
-          body,
-          domNode(2, { parentBackendNodeId: 1, paintOrder: 1 }),
-          domNode(3, { parentBackendNodeId: 1, paintOrder: 2 }),
-        ]),
-      ],
-      { width: 1280, height: 720 },
-    );
-    const groups = clusterRenderedSurfaces(surfaces);
-    const scene: VomScene = {
-      viewport: { width: 1280, height: 720 },
-      nodes: [
-        {
-          id: 10,
-          parentId: null,
-          backendNodeId: 1,
-          frameId: "main",
-          tag: "body",
-          role: "RootWebArea",
-          rect: null,
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    };
-
-    expect(groups).toHaveLength(1);
-    expect(groups[0]?.members).toHaveLength(2);
-    expect(groups[0]?.label).toBeUndefined();
-    expect(
-      projectRenderedSurfaces(
-        scene,
-        [document([body, ...surfaces.map((s) => domNode(s.backendNodeId))])],
-        groups,
-      ),
-    ).toMatchObject({
-      visualSurfaces: [expect.objectContaining({ parentId: 10, backendNodeId: 3, memberCount: 2 })],
-    });
-  });
-
-  it("does not merge a contained canvas with a larger independent canvas", () => {
-    const groups = clusterRenderedSurfaces([
-      ...discoverRenderedSurfaces(
-        [
-          document([
-            domNode(1, { tag: "main", rect: null, localRect: null }),
-            domNode(2, { parentBackendNodeId: 1 }),
-            domNode(3, {
-              parentBackendNodeId: 1,
-              rect: { x: 30, y: 40, w: 200, h: 100 },
-            }),
-          ]),
-        ],
-        { width: 1280, height: 720 },
-      ),
-    ]);
-
-    expect(groups).toHaveLength(2);
-  });
-
-  it("does not merge coincident canvases owned by different containers", () => {
-    const groups = clusterRenderedSurfaces(
-      discoverRenderedSurfaces(
-        [
-          document([
-            domNode(1, { tag: "section", rect: null, localRect: null }),
-            domNode(2, { tag: "section", rect: null, localRect: null }),
-            domNode(3, { parentBackendNodeId: 1 }),
-            domNode(4, { parentBackendNodeId: 2 }),
-          ]),
-        ],
-        { width: 1280, height: 720 },
-      ),
-    );
-
-    expect(groups).toHaveLength(2);
-  });
-});

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

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

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

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

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

@@ -1,68 +1,35 @@
-// 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.
+// Coordinate DOMSnapshot acquisition, frame geometry and hover probes.
+// Snapshot decoding and form enrichment live in their own modules.
 
-import type { Rect, Viewport } from "@browser-skill/vom";
+import type { Viewport } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
-import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
-import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
+import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
+import {
+  type FrameProjectionIssue,
+  type FrameProjectionState,
+  snapshotCoordinates,
+} from "../geometry/coordinate-types";
+import {
+  GeometryContext,
+  type LayoutMetrics,
+  snapshotLayoutScale,
+} from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
+import { 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";
 
-const REQUESTED_STYLES = [
-  "position",
-  "pointer-events",
-  "cursor",
-  "visibility",
-  "opacity",
-  "overflow-x",
-  "overflow-y",
-] 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;
-  overflowX?: string;
-  overflowY?: string;
-  /** True when this node or one of its DOM ancestors makes the subtree fully transparent/hidden. */
-  visuallySuppressed?: boolean;
-  /**
-   * 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 { CapturedNode } from "./capture-types";
 
 export type CapturedIframeNodes = Map<number, CapturedNode[]>;
 
@@ -79,266 +46,26 @@ 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;
-}
-
-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);
-  }
+  geometry?: GeometryContext;
+  target?: CdpTarget;
 }
 
 interface RuntimeEvaluateReply {
   result?: {
     value?: unknown;
-    deepSerializedValue?: DeepSerializedValue;
   };
 }
 
@@ -357,44 +84,6 @@ 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") {
@@ -804,271 +493,146 @@ 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 overflowXCol = STYLE_COL["overflow-x"];
-  const overflowYCol = STYLE_COL["overflow-y"];
-  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[] = [];
-  const visuallySuppressedByNodeIndex = new Array<boolean>(count).fill(false);
-  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 overflowX = "visible";
-    let overflowY = "visible";
-    let rendered = false;
-    let visuallySuppressed =
-      parentIdx >= 0 ? visuallySuppressedByNodeIndex[parentIdx] === true : 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";
-      overflowX = str(strings, styleRow[overflowXCol]) || "visible";
-      overflowY = str(strings, styleRow[overflowYCol]) || "visible";
-      visuallySuppressed ||=
-        visibility === "hidden" ||
-        visibility === "collapse" ||
-        (Number.parseFloat(opacity) || 0) <= 0;
-      rendered =
-        localRect !== null &&
-        visibility !== "hidden" &&
-        visibility !== "collapse" &&
-        (Number.parseFloat(opacity) || 0) > 0;
-    }
-    visuallySuppressedByNodeIndex[n] = visuallySuppressed;
-
-    // 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,
-      overflowX,
-      overflowY,
-      visuallySuppressed,
-      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>;
 }
 
-function parseChildFrameDocuments(
+async function parseChildFrameDocuments(
   documents: SnapshotDocument[],
   strings: string[],
-  dpr: number,
   parentDocIndex: number,
-  parentNodes: CapturedNode[],
   parentContext: FrameContext,
+  geometry: GeometryContext,
+  signal?: AbortSignal,
   visited = new Set<number>(),
-): ParseFrameDocumentsResult {
+): Promise<ParseFrameDocumentsResult> {
+  const frameGeometryIssues: FrameProjectionIssue[] = [];
   const iframeNodes: CapturedIframeNodes = new Map();
   const frameOwnerBackendNodeIds = new Map<string, number>();
   const frameParentIds = new Map<string, string>();
+  const frameExcludedBackendNodeIds = new Map<string, ReadonlySet<number>>();
   const excludedBackendNodeIds = new Set<number>();
   const parentDoc = documents[parentDocIndex];
   const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
   if (cdi.size === 0) {
-    return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
+    return {
+      iframeNodes,
+      frameOwnerBackendNodeIds,
+      frameParentIds,
+      frameExcludedBackendNodeIds,
+      excludedBackendNodeIds,
+      frameGeometryIssues,
+    };
   }
 
   const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
-  const parentNodeByBackendId = new Map(parentNodes.map((node) => [node.backendNodeId, node]));
 
-  for (const [nodeArrayIdx, childDocIndex] of cdi) {
-    if (visited.has(childDocIndex)) continue;
+  const children = [...cdi].flatMap(([nodeArrayIdx, childDocIndex]) => {
     const childDoc = documents[childDocIndex];
-    if (!childDoc) continue;
     const iframeBackendId = parentBackendIds[nodeArrayIdx];
-    if (iframeBackendId === undefined) continue;
-    const iframeNode = parentNodeByBackendId.get(iframeBackendId);
-    const projection =
-      parentContext.projection && iframeNode?.localRect
-        ? childFrameProjection(parentContext.projection, iframeNode.localRect)
-        : null;
+    if (visited.has(childDocIndex) || !childDoc || iframeBackendId === undefined) return [];
+    const source = { target: parentContext.target, frameId: snapshotFrameId(childDoc, strings) };
+    const coordinates = snapshotCoordinates(childDoc, parentContext.layoutUnitsPerCssPixel);
+    const parent = parentContext.projection;
+    const projection: FrameProjectionState =
+      parent.status === "available"
+        ? coordinates
+          ? { status: "unavailable", source, ownerBackendNodeId: iframeBackendId }
+          : { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" }
+        : { status: "blocked", source, cause: parent.status === "blocked" ? parent.cause : parent };
+    return [
+      {
+        childDocIndex,
+        childDoc,
+        iframeBackendId,
+        source,
+        coordinates,
+        projection: projection as FrameProjectionState,
+      },
+    ];
+  });
+  const parentProjection =
+    parentContext.projection.status === "available"
+      ? parentContext.projection.projection.geometry
+      : null;
+  if (parentProjection) {
+    // Measure only direct siblings. Recursion starts after these workers finish,
+    // so descendants never hold or recursively acquire a measurement slot.
+    const edge = parentProjection.edges[0];
+    const clips = edge
+      ? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
+      : parentProjection.sourceClips;
+    let cursor = 0;
+    let failure: unknown;
+    await Promise.all(
+      Array.from({ length: Math.min(4, children.length) }, async () => {
+        while (cursor < children.length && !signal?.aborted && !failure) {
+          const child = children[cursor++];
+          if (!child.coordinates) continue;
+          try {
+            // Owner quads are target-relative; do not apply the parent transform twice.
+            child.projection = await geometry.snapshotProjection(
+              child.source,
+              child.iframeBackendId,
+              clips,
+              parentProjection.topViewport,
+            );
+          } catch (error) {
+            failure ??= error;
+          }
+        }
+      }),
+    );
+    // Join all active reads, including object cleanup, before propagating abort.
+    if (failure) throw failure;
+  }
+  throwIfAborted(signal);
 
+  // Completion order must not change document traversal or result insertion order.
+  for (const {
+    childDocIndex,
+    childDoc,
+    iframeBackendId,
+    source,
+    projection,
+    coordinates,
+  } of children) {
+    throwIfAborted(signal);
+    if (projection.status !== "available") frameGeometryIssues.push(projection);
     const childContext: FrameContext = {
-      frameId: snapshotFrameId(childDoc, strings),
+      frameId: source.frameId,
+      target: source.target,
       ownerFrameBackendNodeId: iframeBackendId,
       projection,
-      scrollX: childDoc.scrollOffsetX ?? 0,
-      scrollY: childDoc.scrollOffsetY ?? 0,
+      coordinates,
+      layoutUnitsPerCssPixel: parentContext.layoutUnitsPerCssPixel,
     };
     const nextVisited = new Set(visited);
     nextVisited.add(childDocIndex);
-    const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
+    const parsed = await normalizeDocument(childDoc, strings, childContext, signal);
     iframeNodes.set(iframeBackendId, parsed.nodes);
     if (childContext.frameId) {
       frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
+      frameExcludedBackendNodeIds.set(childContext.frameId, parsed.index.excludedBackendNodeIds);
       if (parentContext.frameId) frameParentIds.set(childContext.frameId, parentContext.frameId);
     }
-    for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
+    for (const id of parsed.index.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
 
-    const nested = parseChildFrameDocuments(
+    const nested = await 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);
     }
@@ -1078,10 +642,19 @@ 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, excludedBackendNodeIds };
+  return {
+    iframeNodes,
+    frameOwnerBackendNodeIds,
+    frameParentIds,
+    frameExcludedBackendNodeIds,
+    excludedBackendNodeIds,
+    frameGeometryIssues,
+  };
 }
 
 export async function captureViewModel(
@@ -1090,22 +663,21 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  let metrics: LayoutMetricsReply = {};
+  const target = options.target ?? { tabId };
+  const geometry = options.geometry ?? new GeometryContext(cdp, tabId, undefined, options.signal);
+  let metrics: LayoutMetrics = {};
   try {
-    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+    metrics = await geometry.layoutMetrics(target);
   } catch (error) {
     if (isAbortError(error)) throw error;
     console.debug("[bsk capture] layout metrics unavailable", error);
   }
   throwIfAborted(options.signal);
-  const dpr = devicePixelRatio(metrics);
-  const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
   const viewport: Viewport = {
-    width: vpSrc.clientWidth ?? 0,
-    height: vpSrc.clientHeight ?? 0,
+    width: metrics.cssLayoutViewport?.clientWidth ?? 0,
+    height: metrics.cssLayoutViewport?.clientHeight ?? 0,
   };
-  const scrollX = vpSrc.pageX ?? 0;
-  const scrollY = vpSrc.pageY ?? 0;
+  const layoutUnitsPerCssPixel = snapshotLayoutScale(metrics);
 
   await cdp.send(tabId, "DOMSnapshot.enable", {});
   throwIfAborted(options.signal);
@@ -1128,23 +700,55 @@ export async function captureViewModel(
     };
   }
 
+  const source = { target, frameId: snapshotFrameId(doc0, strings) };
+  const coordinates = snapshotCoordinates(doc0, layoutUnitsPerCssPixel, {
+    x: metrics.cssLayoutViewport?.pageX,
+    y: metrics.cssLayoutViewport?.pageY,
+  });
   const topContext: FrameContext = {
     frameId: snapshotFrameId(doc0, strings),
     ownerFrameBackendNodeId: null,
-    projection: {
-      sourceClips: [],
-      edges: [],
-      topViewport: viewport,
-    },
-    scrollX,
-    scrollY,
+    target,
+    projection:
+      coordinates &&
+      [viewport.width, viewport.height].every((size) => Number.isFinite(size) && size > 0)
+        ? {
+            status: "available",
+            projection: {
+              source,
+              geometry: { sourceClips: [], edges: [], topViewport: viewport },
+            },
+          }
+        : { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" },
+    coordinates,
+    layoutUnitsPerCssPixel,
   };
-  const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
+  const mainParsed = await normalizeDocument(doc0, strings, topContext, options.signal);
   const nodes = mainParsed.nodes;
-  const excludedBackendNodeIds = new Set(mainParsed.excludedBackendNodeIds);
+  const excludedBackendNodeIds = new Set(mainParsed.index.excludedBackendNodeIds);
 
-  const frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, nodes, topContext);
+  const ownerIds = new Set<number>();
+  for (const document of documents) {
+    for (const index of document.nodes?.contentDocumentIndex?.index ?? []) {
+      const id = document.nodes?.backendNodeId?.[index];
+      if (id !== undefined) ownerIds.add(id);
+    }
+  }
+  geometry.registerSnapshotOwners(target, ownerIds);
+  const frameParsed = await parseChildFrameDocuments(
+    documents,
+    strings,
+    0,
+    topContext,
+    geometry,
+    options.signal,
+  );
   const iframeNodes = frameParsed.iframeNodes;
+  if (topContext.frameId)
+    frameParsed.frameExcludedBackendNodeIds.set(
+      topContext.frameId,
+      mainParsed.index.excludedBackendNodeIds,
+    );
   for (const id of frameParsed.excludedBackendNodeIds) {
     excludedBackendNodeIds.add(id);
   }
@@ -1169,7 +773,12 @@ export async function captureViewModel(
     viewport,
     iframeNodes,
     frameNodes,
+    frameGeometryIssues: [
+      ...(topContext.projection.status === "available" ? [] : [topContext.projection]),
+      ...frameParsed.frameGeometryIssues,
+    ],
     frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
+    frameExcludedBackendNodeIds: frameParsed.frameExcludedBackendNodeIds,
     frameParentIds: frameParsed.frameParentIds,
     ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
     excludedBackendNodeIds,

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

@@ -0,0 +1,94 @@
+import { isOverlayHostNode } from "@/lib/overlay-bridge";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+
+/** Bounds retain their raw snapshot document layout units until normalization. */
+export interface SnapshotLayout {
+  readonly boundsSpace: "snapshot-document-layout";
+  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 };
+}

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

@@ -0,0 +1,155 @@
+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);
+  }
+}

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

@@ -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,16 +21,6 @@ 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,
@@ -51,6 +41,7 @@ async function captureMissingFrameDocuments(
   tabId: number,
   graph: CdpFrameGraph,
   captured: CapturedViewModel,
+  geometry: GeometryContext,
   signal?: AbortSignal,
 ): Promise<void> {
   if (!captured.frameNodes) captured.frameNodes = new Map();
@@ -62,10 +53,20 @@ 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 resolveFrameProjection(cdp, graph, frame.frameId);
+        projection = await geometry.targetProjection(frame.frameId);
       } catch (err) {
         if (isAbortError(err)) throw err;
         console.debug("[bsk observation] child frame geometry projection failed", {
@@ -171,11 +172,12 @@ 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 discoverFrameGraph(cdp, tabId);
+  const graph = await geometry.graph();
   const frames = graph?.frames ?? [];
-  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, signal);
+  if (graph) await captureMissingFrameDocuments(cdp, tabId, graph, captured, geometry, signal);
   throwIfAborted(signal);
   const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
-  return buildFrameDocuments(graph, batches, captured);
+  return buildFrameDocuments(graph, batches, captured, signal);
 }

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

@@ -4,7 +4,8 @@ import {
   type CdpTarget,
   cdpTargetKey,
 } from "@/browser-driver/frame-graph";
-import type { CapturedNode, CapturedViewModel } from "./capture";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
 
 export interface FrameOwnedAxNode {
   nodeId: string;
@@ -23,6 +24,17 @@ 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 {
@@ -47,7 +59,7 @@ function targetBackendKey(target: CdpTarget, backendNodeId: number): string {
 function frameList<T extends FrameOwnedAxNode>(
   graph: CdpFrameGraph | null,
   batches: FrameAxBatch<T>[],
-  captured: CapturedViewModel,
+  captured: FrameDomInput,
 ): CdpFrame[] {
   const frames = new Map<string, CdpFrame>();
   for (const frame of graph?.frames ?? []) frames.set(frame.frameId, frame);
@@ -70,11 +82,14 @@ function frameList<T extends FrameOwnedAxNode>(
   });
 }
 
-export function buildFrameDocuments<T extends FrameOwnedAxNode>(
+export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   graph: CdpFrameGraph | null,
   batches: FrameAxBatch<T>[],
-  captured: CapturedViewModel,
-): FrameDocument<T>[] {
+  captured: FrameDomInput,
+  signal?: AbortSignal,
+): Promise<FrameDocument<T>[]> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  let work = 0;
   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;
@@ -83,54 +98,68 @@ export 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(batch.nodes.map((node) => [node.nodeId, node]));
-    const ownershipByNodeId = new Map<string, Ownership>();
-    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) {
-          const ownership = { frameId, strength: 3 };
-          ownershipByNodeId.set(node.nodeId, ownership);
-          return ownership;
-        }
-      }
-      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;
-        }
-      }
-      const ownership = { frameId: batch.frame.frameId, strength: 1 };
-      ownershipByNodeId.set(node.nodeId, ownership);
-      return ownership;
-    };
-
+    const nodeById = new Map<string, T>();
     for (const node of batch.nodes) {
-      const ownership = resolveOwnership(node);
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      nodeById.set(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;
+        if (frameId) {
+          ownership = { frameId, strength: 3 };
+          ownershipByNodeId.set(current.nodeId, ownership);
+          break;
+        }
+        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;
+        }
+        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 key = targetNodeKey(batch.frame.target, node.nodeId);
       const existing = candidates.get(key);
       if (!existing || ownership.strength > existing.ownership.strength) {
@@ -144,6 +173,10 @@ export 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))
@@ -169,5 +202,6 @@ export function buildFrameDocuments<T extends FrameOwnedAxNode>(
     contextScopeId: frame.frameId,
     axNodes: axNodesByFrame.get(frame.frameId) ?? [],
     domNodes: domNodesForFrame(frame.frameId),
+    excludedBackendNodeIds: captured.frameExcludedBackendNodeIds?.get(frame.frameId),
   }));
 }

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

@@ -0,0 +1,78 @@
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import {
+  type FrameProjectionState,
+  projectSnapshotRect,
+  type SnapshotCoordinates,
+  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;
+  coordinates: SnapshotCoordinates | null;
+  layoutUnitsPerCssPixel: number | null;
+}
+
+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 bounds = node.layout?.bounds ?? [];
+    const input = snapshotViewportRect(
+      bounds,
+      { target: context.target, frameId: context.frameId },
+      context.coordinates,
+    );
+    const local = input?.rect;
+    const rect =
+      input && context.projection.status === "available"
+        ? projectSnapshotRect(input, context.projection.projection)
+        : null;
+    const visibility = node.layout?.styles.visibility || "visible";
+    const opacity = node.layout?.styles.opacity || "1";
+    nodes.push({
+      ...node,
+      ...(context.frameId ? { frameId: context.frameId } : {}),
+      ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
+      localRect: local ? { x: local.x, y: local.y, w: local.width, h: local.height } : null,
+      rect: rect ? { x: rect.x, y: rect.y, w: rect.width, h: rect.height } : null,
+      rendered:
+        bounds.length >= 4 &&
+        bounds.slice(0, 4).every(Number.isFinite) &&
+        bounds[2] > 0 &&
+        bounds[3] > 0 &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0,
+    });
+  }
+  const index = await buildDocumentIndex(nodes, signal);
+  return {
+    nodes: nodes.filter(
+      (node) => !node.tag.startsWith("#") && !index.excludedBackendNodeIds.has(node.backendNodeId),
+    ),
+    index,
+  };
+}

apps/extension/src/tools/vom/record-safe-observation.ts

@@ -2,7 +2,10 @@ 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 { CapturedFrameDocument, FrameAxNode } from "./frame-capture";
+import type {
+  FrameDocument as CapturedFrameDocument,
+  FrameOwnedAxNode as FrameAxNode,
+} from "./frame-document";
 
 /** Frame identity needed to resolve an `@eN` that lives in an iframe. */
 export interface CaptureVomFrame {

apps/extension/src/tools/vom/rendered-surfaces/cluster.ts

@@ -1,65 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-import type { RenderedSurface, RenderedSurfaceGroup } from "./types";
-
-const STACK_IOU_RATIO = 0.9;
-const STACK_SIZE_RATIO = 0.9;
-
-function area(rect: Rect): number {
-  return Math.max(0, rect.w) * Math.max(0, rect.h);
-}
-
-function intersectionArea(a: Rect, b: Rect): number {
-  const width = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x));
-  const height = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y));
-  return width * height;
-}
-
-function sameVisualStack(a: RenderedSurface, b: RenderedSurface): boolean {
-  if (a.frameId !== b.frameId) return false;
-  if (a.parentBackendNodeId !== b.parentBackendNodeId) return false;
-  const aArea = area(a.visibleRect);
-  const bArea = area(b.visibleRect);
-  const intersection = intersectionArea(a.visibleRect, b.visibleRect);
-  const union = aArea + bArea - intersection;
-  const widthRatio =
-    Math.min(a.visibleRect.w, b.visibleRect.w) / Math.max(a.visibleRect.w, b.visibleRect.w);
-  const heightRatio =
-    Math.min(a.visibleRect.h, b.visibleRect.h) / Math.max(a.visibleRect.h, b.visibleRect.h);
-  return (
-    union > 0 &&
-    intersection / union >= STACK_IOU_RATIO &&
-    widthRatio >= STACK_SIZE_RATIO &&
-    heightRatio >= STACK_SIZE_RATIO
-  );
-}
-
-function toGroup(members: RenderedSurface[]): RenderedSurfaceGroup {
-  const representative = [...members].sort(
-    (a, b) => area(b.visibleRect) - area(a.visibleRect) || b.paintOrder - a.paintOrder,
-  )[0];
-  return {
-    frameId: representative.frameId,
-    members,
-    representative,
-    label: members.map((surface) => surface.label).find((label) => label !== undefined),
-  };
-}
-
-export function clusterRenderedSurfaces(surfaces: RenderedSurface[]): RenderedSurfaceGroup[] {
-  const groups: RenderedSurface[][] = [];
-  for (const surface of surfaces) {
-    const matching = groups.find((group) =>
-      group.some((member) => sameVisualStack(member, surface)),
-    );
-    if (matching) matching.push(surface);
-    else groups.push([surface]);
-  }
-  return groups
-    .map(toGroup)
-    .sort(
-      (a, b) =>
-        a.frameId.localeCompare(b.frameId) ||
-        a.representative.visibleRect.y - b.representative.visibleRect.y ||
-        a.representative.visibleRect.x - b.representative.visibleRect.x,
-    );
-}

apps/extension/src/tools/vom/rendered-surfaces/discovery.ts

@@ -1,113 +0,0 @@
-import type { Rect, Viewport } from "@browser-skill/vom";
-import type { CapturedNode } from "../capture";
-import type { CapturedFrameDocument } from "../frame-capture";
-import type { SemanticAxNode } from "../semantic-graph";
-import type { RenderedSurface } from "./types";
-
-function clean(value: string | undefined): string | undefined {
-  const normalized = value?.replace(/\s+/g, " ").trim();
-  return normalized || undefined;
-}
-
-function intersectViewport(rect: Rect, viewport: Viewport): Rect | null {
-  return intersectRect(rect, { x: 0, y: 0, w: viewport.width, h: viewport.height });
-}
-
-function intersectRect(a: Rect, b: Rect): Rect | null {
-  const x = Math.max(a.x, b.x);
-  const y = Math.max(a.y, b.y);
-  const right = Math.min(a.x + a.w, b.x + b.w);
-  const bottom = Math.min(a.y + a.h, b.y + b.h);
-  if (right <= x || bottom <= y) return null;
-  return { x, y, w: right - x, h: bottom - y };
-}
-
-const CLIPPING_OVERFLOW = new Set(["auto", "clip", "hidden", "scroll"]);
-
-function clipToOverflowAncestors(
-  node: CapturedNode,
-  rect: Rect,
-  nodesByBackend: ReadonlyMap<number, CapturedNode>,
-): Rect | null {
-  let clipped: Rect | null = rect;
-  let parentBackendNodeId = node.parentBackendNodeId;
-  let guard = 0;
-  while (clipped && parentBackendNodeId !== null && guard <= nodesByBackend.size) {
-    const parent = nodesByBackend.get(parentBackendNodeId);
-    if (!parent) break;
-    if (parent.rect) {
-      const clipX = CLIPPING_OVERFLOW.has(parent.overflowX ?? "visible");
-      const clipY = CLIPPING_OVERFLOW.has(parent.overflowY ?? "visible");
-      if (clipX || clipY) {
-        const clipRect = {
-          x: clipX ? parent.rect.x : clipped.x,
-          y: clipY ? parent.rect.y : clipped.y,
-          w: clipX ? parent.rect.w : clipped.w,
-          h: clipY ? parent.rect.h : clipped.h,
-        };
-        clipped = intersectRect(clipped, clipRect);
-      }
-    }
-    parentBackendNodeId = parent.parentBackendNodeId;
-    guard += 1;
-  }
-  return clipped;
-}
-
-function excludedByDomPolicy(
-  node: CapturedNode,
-  nodesByBackend: Map<number, CapturedNode>,
-  excludedBackendNodeIds: ReadonlySet<number>,
-): boolean {
-  let current: CapturedNode | undefined = node;
-  let guard = 0;
-  while (current && guard <= nodesByBackend.size) {
-    if (excludedBackendNodeIds.has(current.backendNodeId)) return true;
-    if (current.visuallySuppressed === true) return true;
-    const attrs = current.attrs;
-    if (
-      Object.prototype.hasOwnProperty.call(attrs, "hidden") ||
-      Object.prototype.hasOwnProperty.call(attrs, "inert") ||
-      (attrs["aria-hidden"] ?? "").toLowerCase() === "true"
-    ) {
-      return true;
-    }
-    current =
-      current.parentBackendNodeId === null
-        ? undefined
-        : nodesByBackend.get(current.parentBackendNodeId);
-    guard += 1;
-  }
-  return false;
-}
-
-export function discoverRenderedSurfaces(
-  documents: CapturedFrameDocument<SemanticAxNode>[],
-  viewport: Viewport,
-  excludedBackendNodeIds: ReadonlySet<number> = new Set(),
-): RenderedSurface[] {
-  const surfaces: RenderedSurface[] = [];
-  for (const document of documents) {
-    const nodesByBackend = new Map(document.domNodes.map((node) => [node.backendNodeId, node]));
-    for (const node of document.domNodes) {
-      if (node.tag.toLowerCase() !== "canvas" || node.rendered !== true || !node.rect) continue;
-      if (excludedByDomPolicy(node, nodesByBackend, excludedBackendNodeIds)) continue;
-      const viewportRect = intersectViewport(node.rect, viewport);
-      const visibleRect = viewportRect
-        ? clipToOverflowAncestors(node, viewportRect, nodesByBackend)
-        : null;
-      if (!visibleRect) continue;
-      const label = clean(node.attrs["aria-label"] ?? node.attrs.title);
-      surfaces.push({
-        renderingKind: "canvas",
-        frameId: document.frameId,
-        backendNodeId: node.backendNodeId,
-        parentBackendNodeId: node.parentBackendNodeId,
-        visibleRect,
-        paintOrder: node.paintOrder,
-        ...(label ? { label } : {}),
-      });
-    }
-  }
-  return surfaces;
-}

apps/extension/src/tools/vom/rendered-surfaces/index.ts

@@ -1,4 +0,0 @@
-export { clusterRenderedSurfaces } from "./cluster";
-export { discoverRenderedSurfaces } from "./discovery";
-export { projectRenderedSurfaces } from "./project";
-export type { RenderedSurface, RenderedSurfaceGroup } from "./types";

apps/extension/src/tools/vom/rendered-surfaces/project.ts

@@ -1,100 +0,0 @@
-import type { VomScene, VomVisualSurface } from "@browser-skill/vom";
-import type { CapturedFrameDocument } from "../frame-capture";
-import type { SemanticAxNode } from "../semantic-graph";
-import type { RenderedSurfaceGroup } from "./types";
-
-function frameBackendKey(frameId: string, backendNodeId: number): string {
-  return `${frameId}\u0000${backendNodeId}`;
-}
-
-interface ProjectionIndex {
-  sceneByBackend: ReadonlyMap<string, number>;
-  documentByFrame: ReadonlyMap<string, CapturedFrameDocument<SemanticAxNode>>;
-  domByFrame: ReadonlyMap<
-    string,
-    ReadonlyMap<number, CapturedFrameDocument<SemanticAxNode>["domNodes"][number]>
-  >;
-  rootSceneIdByFrame: ReadonlyMap<string, number>;
-}
-
-function nearestSceneParent(index: ProjectionIndex, group: RenderedSurfaceGroup): number | null {
-  const document = index.documentByFrame.get(group.frameId);
-  const domByBackend = index.domByFrame.get(group.frameId) ?? new Map();
-  let parentBackendNodeId = group.representative.parentBackendNodeId;
-  let guard = 0;
-  while (parentBackendNodeId !== null && guard <= domByBackend.size) {
-    const sceneId = index.sceneByBackend.get(frameBackendKey(group.frameId, parentBackendNodeId));
-    if (sceneId !== undefined) return sceneId;
-    parentBackendNodeId = domByBackend.get(parentBackendNodeId)?.parentBackendNodeId ?? null;
-    guard += 1;
-  }
-
-  if (document?.parentFrameId && document.ownerBackendNodeId !== undefined) {
-    const owner = index.sceneByBackend.get(
-      frameBackendKey(document.parentFrameId, document.ownerBackendNodeId),
-    );
-    if (owner !== undefined) return owner;
-  }
-
-  return index.rootSceneIdByFrame.get(group.frameId) ?? null;
-}
-
-function buildProjectionIndex(
-  scene: VomScene,
-  documents: CapturedFrameDocument<SemanticAxNode>[],
-): ProjectionIndex {
-  const rootSceneIdByFrame = new Map<string, number>();
-  for (const node of scene.nodes) {
-    if (
-      node.frameId &&
-      !rootSceneIdByFrame.has(node.frameId) &&
-      ["rootwebarea", "webarea"].includes(node.role?.toLowerCase() ?? "")
-    ) {
-      rootSceneIdByFrame.set(node.frameId, node.id);
-    }
-  }
-  return {
-    sceneByBackend: new Map(
-      scene.nodes.flatMap((node) =>
-        node.backendNodeId === undefined
-          ? []
-          : [[frameBackendKey(node.frameId ?? "", node.backendNodeId), node.id] as const],
-      ),
-    ),
-    documentByFrame: new Map(documents.map((document) => [document.frameId, document])),
-    domByFrame: new Map(
-      documents.map((document) => [
-        document.frameId,
-        new Map(document.domNodes.map((node) => [node.backendNodeId, node])),
-      ]),
-    ),
-    rootSceneIdByFrame,
-  };
-}
-
-export function projectRenderedSurfaces(
-  scene: VomScene,
-  documents: CapturedFrameDocument<SemanticAxNode>[],
-  groups: RenderedSurfaceGroup[],
-): VomScene {
-  const index = buildProjectionIndex(scene, documents);
-  const visualSurfaces: VomVisualSurface[] = [];
-
-  for (const group of groups) {
-    const parentId = nearestSceneParent(index, group);
-    visualSurfaces.push({
-      parentId,
-      backendNodeId: group.representative.backendNodeId,
-      frameId: group.frameId,
-      renderingKind: "canvas",
-      visibleRect: group.representative.visibleRect,
-      ...(group.label ? { label: group.label } : {}),
-      memberCount: group.members.length,
-    });
-  }
-
-  return {
-    ...scene,
-    ...(visualSurfaces.length > 0 ? { visualSurfaces } : {}),
-  };
-}

apps/extension/src/tools/vom/rendered-surfaces/types.ts

@@ -1,18 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-
-export interface RenderedSurface {
-  renderingKind: "canvas";
-  frameId: string;
-  backendNodeId: number;
-  parentBackendNodeId: number | null;
-  visibleRect: Rect;
-  paintOrder: number;
-  label?: string;
-}
-
-export interface RenderedSurfaceGroup {
-  frameId: string;
-  members: RenderedSurface[];
-  representative: RenderedSurface;
-  label?: string;
-}

apps/extension/src/tools/vom/semantic-graph/build.ts

@@ -61,8 +61,9 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
         dom,
         sourceOrder: index,
         excluded:
-          document.frameId === rootFrameId &&
-          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
+          document.excludedBackendNodeIds?.has(dom.backendNodeId) === true ||
+          (document.frameId === rootFrameId &&
+            input.excludedBackendNodeIds?.has(dom.backendNodeId) === true),
       };
       nodes.set(id, node);
       frameNodeIds.push(id);
@@ -90,9 +91,10 @@ export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGrap
           ax,
           sourceOrder: document.domNodes.length + index,
           excluded:
-            document.frameId === rootFrameId &&
             typeof ax.backendDOMNodeId === "number" &&
-            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
+            (document.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true ||
+              (document.frameId === rootFrameId &&
+                input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true)),
         });
         frameNodeIds.push(id);
       }

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

@@ -0,0 +1,224 @@
+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-layout" 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 };
+}

apps/extension/src/transport/types.ts

@@ -23,7 +23,6 @@ export type ErrorCode =
 export type RpcErrorReason =
   | "agent_window_scope"
   | "element_not_visible"
-  | "ref_capability_denied"
   | "ref_not_found"
   | "selector_not_found"
   | "target_not_fillable"
@@ -49,11 +48,6 @@ export type RpcErrorReason =
   | "download_capture_failed"
   | "transfer_outcome_unknown"
   | "transfer_timeout"
-  | "surface_capture_not_found"
-  | "surface_capture_expired"
-  | "surface_capture_consumed"
-  | "surface_capture_stale"
-  | "surface_coordinate_invalid"
   | "cleanup_failed";
 
 export type TransferEffectState = "none" | "committed" | "unknown";
@@ -325,17 +319,9 @@ export interface ScreenshotResult {
   height: number;
   format: string;
   tab_id: number;
-  capture?: SurfaceCaptureInfo;
   dialogs?: JavaScriptDialogInfo[];
 }
 
-export interface SurfaceCaptureInfo {
-  id: string;
-  surface_ref: string;
-  coordinate_space: "capture-image-pixel";
-  expires_at: number;
-}
-
 export interface SnapshotParams {
   session_id: string;
   tab_id?: number;
@@ -454,9 +440,6 @@ export interface ClickParams {
   click_count?: number;
   modifiers?: KeyModifier[];
   timeout_ms?: number;
-  capture_id?: string;
-  image_x?: number;
-  image_y?: number;
 }
 
 export interface ClickResult {
@@ -465,9 +448,6 @@ export interface ClickResult {
   used_selector?: string;
   x: number;
   y: number;
-  capture_id?: string;
-  image_x?: number;
-  image_y?: number;
   dialogs?: JavaScriptDialogInfo[];
 }
 

apps/extension/test-fixtures/rendered-surfaces/README.md

@@ -1,113 +0,0 @@
-# Rendered Surface browser fixtures
-
-These pages exercise Canvas discovery through a real browser DOMSnapshot and AX tree. They are deliberately framework- and site-independent.
-
-## Serve
-
-From the repository root:
-
-```bash
-python3 -m http.server 4173 --bind 127.0.0.1 \
-  --directory apps/extension/test-fixtures/rendered-surfaces
-```
-
-Use an Agent Window large enough to keep the primary matrix visible:
-
-```bash
-bsk session start --width 1440 --height 1100
-bsk navigate http://127.0.0.1:4173/index.html --session <id>
-bsk observe --session <id>
-```
-
-Always stop the session after the run.
-
-## Pages
-
-### `index.html`
-
-Expected individual Surface labels:
-
-- `fixture-basic-large`
-- `fixture-tiny-8px`
-- `fixture-pointer-events-none`
-- `fixture-partial-ax`
-- `fixture-contained-outer`
-- `fixture-contained-inner`
-- `fixture-different-parent-a`
-- `fixture-different-parent-b`
-
-Expected one grouped Surface:
-
-- `fixture-layered-group`, with `layers=2`
-
-Expected absent:
-
-- `fixture-display-none`
-- `fixture-visibility-hidden`
-- `fixture-opacity-zero`
-- `fixture-parent-opacity-zero`
-- `fixture-hidden-attribute`
-- `fixture-inert-parent`
-- `fixture-aria-hidden-parent`
-- `fixture-zero-size`
-- `fixture-offscreen-right`
-- `fixture-fully-overflow-clipped`
-
-`fixture-partially-overflow-clipped` must remain present because part of it is visible. Its screenshot must contain only the browser's final composited view.
-
-### `unlabeled.html`
-
-This page contains eight Canvas elements but must render seven generic Surface markers because
-the two coincident layers form one group.
-
-- Every marker uses the stable fallback label `canvas visual surface`.
-- Exactly one marker has `layers=2`.
-- The two contained canvases remain separate markers.
-- `id`, `class`, `data-testid`, nearby prose, and fallback AX content never become a Surface label.
-- Blank `aria-label` and `title` values behave as no label.
-- Fallback AX content does not suppress the corresponding Surface.
-
-### `frames.html`
-
-Expected Surface labels:
-
-- `fixture-same-origin-frame`
-- `fixture-cross-origin-frame`
-- `fixture-nested-frame`
-
-The cross-origin frame uses `http://localhost:4173` while the parent uses `http://127.0.0.1:4173`. With Chromium site isolation this exercises the OOPIF path without an external service.
-
-Each frame Canvas also exposes a `pointer status` live region. A successful
-screenshot-bound point click must report
-`down button=0 buttons=1 hoverReady=true; click received` and turn the Canvas
-yellow. The hover flag is set on the animation frame after `pointermove`, so the
-fixture verifies both child-document delivery and the scheduling boundary
-required before `pointerdown`, rather than merely validating projected
-coordinates or a successful CDP response.
-
-### `viewport.html`
-
-Run with a `900x700` Agent Window.
-
-- `fixture-partial-viewport` is partly visible and must be represented.
-- `fixture-below-fold` is absent initially.
-- After scrolling it into view and observing again, `fixture-below-fold` must be represented with a fresh ref.
-
-### `dynamic.html`
-
-Use the normal DOM buttons and re-observe after each action:
-
-- Initial state: `fixture-dynamic` absent.
-- After **Insert canvas**: present.
-- After **Resize to zero**: absent.
-- After **Restore size**: present with a fresh ref.
-- After **Remove canvas**: absent.
-
-## Invariants
-
-- `snapshot` must not emit any of these Surface markers.
-- `observe` must emit only currently visible Canvas surfaces.
-- Existing DOM/AX controls remain readable alongside Surface markers.
-- Missing labels never prevent discovery; naming and discovery are independent.
-- A Surface ref allows `screenshot --ref` and rejects ordinary click/fill/hover/select.
-- No fixture URL, id, label, or layout constant may appear in production discovery code.

apps/extension/test-fixtures/rendered-surfaces/dynamic.html

@@ -1,46 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Rendered Surface dynamic matrix</title>
-    <style>
-      html, body { margin: 0; font: 14px system-ui, sans-serif; }
-      body { padding: 16px; }
-      .controls { display: flex; gap: 8px; margin-bottom: 16px; }
-      button { padding: 8px 12px; }
-      canvas { display: block; width: 260px; height: 120px; background: #e8daef; border: 2px solid #7d3c98; }
-    </style>
-  </head>
-  <body>
-    <h1>Dynamic Canvas lifecycle</h1>
-    <div class="controls">
-      <button id="insert" type="button">Insert canvas</button>
-      <button id="zero" type="button">Resize to zero</button>
-      <button id="restore" type="button">Restore size</button>
-      <button id="remove" type="button">Remove canvas</button>
-    </div>
-    <div id="mount"></div>
-    <script>
-      const mount = document.querySelector("#mount");
-      const getCanvas = () => mount.querySelector("canvas");
-      document.querySelector("#insert").addEventListener("click", () => {
-        if (getCanvas()) return;
-        const canvas = document.createElement("canvas");
-        canvas.width = 260;
-        canvas.height = 120;
-        canvas.setAttribute("aria-label", "fixture-dynamic");
-        mount.append(canvas);
-      });
-      document.querySelector("#zero").addEventListener("click", () => {
-        const canvas = getCanvas();
-        if (canvas) canvas.style.cssText = "width:0;height:0;border:0";
-      });
-      document.querySelector("#restore").addEventListener("click", () => {
-        const canvas = getCanvas();
-        if (canvas) canvas.removeAttribute("style");
-      });
-      document.querySelector("#remove").addEventListener("click", () => getCanvas()?.remove());
-    </script>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/frame.html

@@ -1,52 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <style>
-      html, body { margin: 0; font: 14px system-ui, sans-serif; }
-      body { padding: 12px; background: #fdfefe; }
-      canvas { display: block; width: 220px; height: 90px; background: #d5f5e3; border: 2px solid #1e8449; }
-      iframe { width: 280px; height: 150px; margin-top: 10px; border: 2px solid #85929e; }
-      #pointer-status { margin: 8px 0 0; min-height: 20px; }
-    </style>
-  </head>
-  <body>
-    <canvas id="frame-canvas" width="220" height="90"></canvas>
-    <script>
-      const params = new URLSearchParams(location.search);
-      const canvas = document.querySelector("#frame-canvas");
-      if (params.get("canvas") === "0") canvas.remove();
-      else {
-        canvas.setAttribute("aria-label", params.get("label") || "fixture-frame-default");
-        if (params.get("interactive") === "1") {
-          const status = document.createElement("p");
-          status.id = "pointer-status";
-          status.setAttribute("aria-live", "polite");
-          status.textContent = "pointer status: idle";
-          canvas.insertAdjacentElement("afterend", status);
-          let hoverReady = false;
-          canvas.addEventListener("pointermove", () => {
-            hoverReady = false;
-            requestAnimationFrame(() => {
-              hoverReady = true;
-            });
-          });
-          canvas.addEventListener("pointerdown", (event) => {
-            status.textContent = `pointer status: down button=${event.button} buttons=${event.buttons} hoverReady=${hoverReady}`;
-            if (event.buttons === 1 && hoverReady) canvas.style.background = "#f9e79f";
-          });
-          canvas.addEventListener("click", () => {
-            status.textContent += "; click received";
-          });
-        }
-      }
-      if (params.get("nested") === "1") {
-        const iframe = document.createElement("iframe");
-        iframe.title = "nested fixture frame";
-        iframe.src = "frame.html?label=fixture-nested-frame&interactive=1";
-        document.body.append(iframe);
-      }
-    </script>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/frames.html

@@ -1,22 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Rendered Surface frame matrix</title>
-    <style>
-      html, body { margin: 0; font: 14px system-ui, sans-serif; }
-      body { padding: 16px; }
-      .frames { display: grid; grid-template-columns: repeat(3, 320px); gap: 16px; }
-      iframe { width: 300px; height: 300px; border: 2px solid #5d6d7e; }
-    </style>
-  </head>
-  <body>
-    <h1>Frame matrix</h1>
-    <div class="frames">
-      <iframe title="same-origin fixture" src="frame.html?label=fixture-same-origin-frame&interactive=1"></iframe>
-      <iframe title="cross-origin fixture" src="http://localhost:4173/frame.html?label=fixture-cross-origin-frame&interactive=1"></iframe>
-      <iframe title="nested fixture" src="frame.html?canvas=0&nested=1"></iframe>
-    </div>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/index.html

@@ -1,118 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Rendered Surface discovery matrix</title>
-    <style>
-      * { box-sizing: border-box; }
-      html, body { margin: 0; min-height: 100%; font: 14px/1.4 system-ui, sans-serif; }
-      body { padding: 16px; background: #f4f6f8; color: #17202a; }
-      h1 { margin: 0 0 12px; font-size: 20px; }
-      .matrix { display: grid; grid-template-columns: repeat(4, minmax(220px, 1fr)); gap: 12px; }
-      .case { min-height: 150px; padding: 10px; overflow: hidden; border: 1px solid #aeb6bf; border-radius: 6px; background: white; }
-      .case h2 { margin: 0 0 8px; font-size: 13px; }
-      canvas { display: block; background: #d6eaf8; border: 2px solid #2874a6; }
-      .stack { position: relative; width: 180px; height: 90px; }
-      .stack canvas { position: absolute; inset: 0; width: 180px; height: 90px; }
-      .stack canvas + canvas { background: rgb(244 208 63 / 45%); border-color: #b7950b; }
-      .contained { position: relative; width: 190px; height: 100px; }
-      .contained > canvas:first-child { width: 190px; height: 100px; }
-      .contained > canvas:last-child { position: absolute; left: 55px; top: 30px; width: 70px; height: 40px; background: #fadbd8; border-color: #c0392b; }
-      .same-place { position: relative; width: 180px; height: 90px; }
-      .same-place > div { position: absolute; inset: 0; }
-      .same-place canvas { width: 180px; height: 90px; }
-      .same-place > div:last-child canvas { border-color: #7d3c98; background: rgb(210 180 222 / 35%); }
-      .clip-box { width: 100px; height: 70px; overflow: hidden; border: 2px dashed #566573; }
-      .partially-clipped { width: 140px; height: 60px; transform: translateX(45px); }
-      .fully-clipped { width: 80px; height: 50px; transform: translateX(130px); }
-      .tiny { width: 8px; height: 8px; border-width: 1px; }
-    </style>
-  </head>
-  <body>
-    <h1>Rendered Surface discovery matrix</h1>
-    <main class="matrix">
-      <section class="case">
-        <h2>Visible named canvas</h2>
-        <canvas aria-label="fixture-basic-large" width="200" height="90"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Tiny canvas remains addressable</h2>
-        <canvas class="tiny" aria-label="fixture-tiny-8px" width="8" height="8"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Visible but pointer-events none</h2>
-        <canvas aria-label="fixture-pointer-events-none" width="180" height="80" style="pointer-events: none"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Partial AX/fallback content</h2>
-        <canvas aria-label="fixture-partial-ax" width="180" height="80">
-          <button type="button">Fallback button must not suppress the surface</button>
-        </canvas>
-      </section>
-
-      <section class="case">
-        <h2>Two real rendering layers</h2>
-        <div class="stack">
-          <canvas aria-label="fixture-layered-group" width="180" height="90"></canvas>
-          <canvas width="180" height="90"></canvas>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>Contained canvases are independent</h2>
-        <div class="contained">
-          <canvas aria-label="fixture-contained-outer" width="190" height="100"></canvas>
-          <canvas aria-label="fixture-contained-inner" width="70" height="40"></canvas>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>Same geometry, different parents</h2>
-        <div class="same-place">
-          <div><canvas aria-label="fixture-different-parent-a" width="180" height="90"></canvas></div>
-          <div><canvas aria-label="fixture-different-parent-b" width="180" height="90"></canvas></div>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>Partially overflow-clipped</h2>
-        <div class="clip-box">
-          <canvas class="partially-clipped" aria-label="fixture-partially-overflow-clipped" width="140" height="60"></canvas>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>Fully overflow-clipped</h2>
-        <div class="clip-box">
-          <canvas class="fully-clipped" aria-label="fixture-fully-overflow-clipped" width="80" height="50"></canvas>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>CSS-hidden variants</h2>
-        <canvas aria-label="fixture-display-none" width="80" height="40" style="display: none"></canvas>
-        <canvas aria-label="fixture-visibility-hidden" width="80" height="40" style="visibility: hidden"></canvas>
-        <canvas aria-label="fixture-opacity-zero" width="80" height="40" style="opacity: 0"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Hidden ancestor variants</h2>
-        <div style="opacity: 0"><canvas aria-label="fixture-parent-opacity-zero" width="80" height="40"></canvas></div>
-        <div hidden><canvas aria-label="fixture-hidden-attribute" width="80" height="40"></canvas></div>
-        <div inert><canvas aria-label="fixture-inert-parent" width="80" height="40"></canvas></div>
-        <div aria-hidden="true"><canvas aria-label="fixture-aria-hidden-parent" width="80" height="40"></canvas></div>
-      </section>
-
-      <section class="case">
-        <h2>Zero-size and offscreen</h2>
-        <canvas aria-label="fixture-zero-size" width="80" height="40" style="width: 0; height: 0; border: 0"></canvas>
-        <canvas aria-label="fixture-offscreen-right" width="80" height="40" style="position: fixed; left: 5000px; top: 0"></canvas>
-      </section>
-    </main>
-  </body>
-</html>
-

apps/extension/test-fixtures/rendered-surfaces/unlabeled.html

@@ -1,68 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Unlabeled Rendered Surface matrix</title>
-    <style>
-      * { box-sizing: border-box; }
-      html, body { margin: 0; min-height: 100%; font: 14px/1.4 system-ui, sans-serif; }
-      body { padding: 16px; background: #f4f6f8; color: #17202a; }
-      h1 { margin: 0 0 12px; font-size: 20px; }
-      .matrix { display: grid; grid-template-columns: repeat(3, minmax(240px, 1fr)); gap: 12px; }
-      .case { min-height: 150px; padding: 10px; overflow: hidden; border: 1px solid #aeb6bf; border-radius: 6px; background: white; }
-      .case h2 { margin: 0 0 8px; font-size: 13px; }
-      .case p { margin: 0 0 8px; }
-      canvas { display: block; background: #d6eaf8; border: 2px solid #2874a6; }
-      .stack { position: relative; width: 180px; height: 90px; }
-      .stack canvas { position: absolute; inset: 0; width: 180px; height: 90px; }
-      .stack canvas + canvas { background: rgb(244 208 63 / 45%); border-color: #b7950b; }
-      .contained { position: relative; width: 190px; height: 100px; }
-      .contained > canvas:first-child { width: 190px; height: 100px; }
-      .contained > canvas:last-child { position: absolute; left: 55px; top: 30px; width: 70px; height: 40px; background: #fadbd8; border-color: #c0392b; }
-    </style>
-  </head>
-  <body>
-    <h1>Unlabeled Rendered Surface matrix</h1>
-    <main class="matrix">
-      <section class="case">
-        <h2>Only engineering attributes</h2>
-        <canvas id="must-not-be-a-label" class="must-not-be-a-label" data-testid="must-not-be-a-label" width="200" height="90"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Blank explicit names</h2>
-        <canvas aria-label="   " title="   " width="180" height="80"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Nearby prose is not a Canvas name</h2>
-        <p>must-not-be-inferred-as-a-surface-label</p>
-        <canvas width="180" height="80"></canvas>
-      </section>
-
-      <section class="case">
-        <h2>Fallback AX content does not name or suppress the Canvas</h2>
-        <canvas width="180" height="80">
-          <button type="button">Fallback control remains separate</button>
-        </canvas>
-      </section>
-
-      <section class="case">
-        <h2>Unnamed rendering layers still cluster</h2>
-        <div class="stack">
-          <canvas width="180" height="90"></canvas>
-          <canvas width="180" height="90"></canvas>
-        </div>
-      </section>
-
-      <section class="case">
-        <h2>Unnamed contained canvases stay independent</h2>
-        <div class="contained">
-          <canvas width="190" height="100"></canvas>
-          <canvas width="70" height="40"></canvas>
-        </div>
-      </section>
-    </main>
-  </body>
-</html>

apps/extension/test-fixtures/rendered-surfaces/viewport.html

@@ -1,22 +0,0 @@
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Rendered Surface viewport matrix</title>
-    <style>
-      html, body { margin: 0; font: 14px system-ui, sans-serif; }
-      body { min-height: 1800px; padding: 16px; }
-      canvas { display: block; background: #fdebd0; border: 2px solid #ca6f1e; }
-      #partial { position: fixed; left: -70px; top: 120px; width: 180px; height: 100px; }
-      #below { position: absolute; left: 40px; top: 1350px; width: 240px; height: 120px; }
-    </style>
-  </head>
-  <body>
-    <h1>Viewport matrix</h1>
-    <p>The orange canvas on the left is intentionally clipped by the viewport.</p>
-    <canvas id="partial" aria-label="fixture-partial-viewport" width="180" height="100"></canvas>
-    <canvas id="below" aria-label="fixture-below-fold" width="240" height="120"></canvas>
-  </body>
-</html>
-

crates/bsk-cli/skill/SKILL.md

@@ -73,28 +73,6 @@ CSS-only hover menu looks like from here. It hovers a bounded set of likely trig
 few seconds and touches the live page; once you know which element hides the menu, `bsk hover <ref>`
 is cheaper and more precise.
 
-When `bsk observe` renders
-`@eN surface ... [visual-only; requires=image-understanding; ...]`, the ref identifies rendered
-canvas content that is not represented by the text observation, not an interactable DOM control.
-Keep using any reliable DOM/AX text and controls that appear alongside it. If you lack multimodal or
-image-reading capability, do not take a screenshot and pretend to know its contents, and never guess
-coordinates; tell the user that they need to switch to a model with image-understanding capability.
-
-If you can actually inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain
-the visible crop and its short-lived, single-use Surface capture id. Only when the task requires a
-point action and the image provides a clear target, bind that exact screenshot to the click command:
-
-```bash
-bsk click @eN --capture <capture-id> --image-x <px> --image-y <px> --session <id>
-```
-
-Coordinates are pixels in the returned capture image, not viewport CSS coordinates. Re-observing,
-navigating, scrolling, resizing, zooming, changing Frame projection, expiry, or reusing the capture
-makes the action fail; take a new Surface screenshot instead of adjusting or retrying coordinates.
-A point click does not reveal Canvas semantics and must not be followed by an assumed fill/press
-workflow. Without all three capture arguments, visual Surface refs remain screenshot-only and
-click/fill/hover/select reject them.
-
 Escalate page reading only as needed:
 
 1. `bsk observe` for normal semantic understanding, text, controls, and refs.
@@ -147,7 +125,6 @@ Required flags that are easy to get wrong:
 bsk fill <ref> --value <text>      bsk select <ref> --value <option-value>
 bsk screenshot --out <path>        bsk emulate --device <preset-id>
 bsk upload <ref> --file <path>     bsk download <ref> --out <path>
-bsk click <surface-ref> --capture <id> --image-x <px> --image-y <px>
 ```
 
 `select` matches an option's `value` attribute, not its visible label. Device preset ids are

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

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

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

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

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

@@ -136,18 +136,6 @@ pub struct ClickArgs {
 
     #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
     pub timeout: u32,
-
-    /// Capture id returned by `bsk screenshot --ref <surface>`.
-    #[arg(long)]
-    pub capture: Option<String>,
-
-    /// X coordinate in capture-image pixels. Requires `--capture` and `--image-y`.
-    #[arg(long = "image-x", allow_hyphen_values = true)]
-    pub image_x: Option<f64>,
-
-    /// Y coordinate in capture-image pixels. Requires `--capture` and `--image-x`.
-    #[arg(long = "image-y", allow_hyphen_values = true)]
-    pub image_y: Option<f64>,
 }
 
 pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
@@ -159,14 +147,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
     )?;
     let modifiers = parse_modifiers(&args.modifiers)
         .map_err(|e| CliError::Local(anyhow::anyhow!("--modifiers: {e}")))?;
-    let point_arg_count = usize::from(args.capture.is_some())
-        + usize::from(args.image_x.is_some())
-        + usize::from(args.image_y.is_some());
-    if point_arg_count != 0 && point_arg_count != 3 {
-        return Err(CliError::Local(anyhow::anyhow!(
-            "--capture, --image-x, and --image-y must be given together"
-        )));
-    }
     let params = ClickParams {
         session_id: args.session.clone(),
         ref_,
@@ -180,9 +160,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
             Some(modifiers)
         },
         timeout_ms: Some(args.timeout),
-        capture_id: args.capture.clone(),
-        image_x: args.image_x,
-        image_y: args.image_y,
     };
     let reply: ClickResult = call(
         info.sock_path,
@@ -206,14 +183,6 @@ pub fn dispatch_click(args: ClickArgs, format: Format) -> Result<(), CliError> {
                 "click ok tab={} target={target} at=({}, {})",
                 reply.tab_id, reply.x, reply.y
             );
-            if let Some(capture_id) = &reply.capture_id {
-                println!(
-                    "capture={} image=({}, {}) coordinate_space=capture-image-pixel",
-                    capture_id,
-                    reply.image_x.unwrap_or_default(),
-                    reply.image_y.unwrap_or_default()
-                );
-            }
             print_dialog_summaries(&reply.dialogs);
         }
     }

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

@@ -40,7 +40,6 @@ use bsk_protocol::ErrorCode;
 pub mod reason {
     pub const AGENT_WINDOW_SCOPE: &str = "agent_window_scope";
     pub const ELEMENT_NOT_VISIBLE: &str = "element_not_visible";
-    pub const REF_CAPABILITY_DENIED: &str = "ref_capability_denied";
     pub const REF_NOT_FOUND: &str = "ref_not_found";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
@@ -65,11 +64,6 @@ pub mod reason {
     pub const DOWNLOAD_CAPTURE_FAILED: &str = "download_capture_failed";
     pub const TRANSFER_OUTCOME_UNKNOWN: &str = "transfer_outcome_unknown";
     pub const TRANSFER_TIMEOUT: &str = "transfer_timeout";
-    pub const SURFACE_CAPTURE_NOT_FOUND: &str = "surface_capture_not_found";
-    pub const SURFACE_CAPTURE_EXPIRED: &str = "surface_capture_expired";
-    pub const SURFACE_CAPTURE_CONSUMED: &str = "surface_capture_consumed";
-    pub const SURFACE_CAPTURE_STALE: &str = "surface_capture_stale";
-    pub const SURFACE_COORDINATE_INVALID: &str = "surface_coordinate_invalid";
     pub const SESSION_BUSY: &str = crate::rpc_reason::SESSION_BUSY;
     pub const RECORD_START_PAGE_UNREACHABLE: &str = "record_start_page_unreachable";
 }
@@ -305,13 +299,6 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
-        (ErrorCode::PermissionDenied, reason::REF_CAPABILITY_DENIED) => RenderInfo {
-            summary: "snapshot ref does not support this operation",
-            hint: Some(
-                "visual Surface refs require image understanding; inspect `bsk screenshot --ref <ref> --session <id>`, then bind its capture id and image coordinates to `bsk click`",
-            ),
-            exit_code: base.exit_code,
-        },
         (ErrorCode::InvalidParams, reason::TARGET_NOT_SELECT) => RenderInfo {
             summary: "target element is not a <select>",
             hint: Some(
@@ -354,41 +341,6 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
-        (ErrorCode::NotFound, reason::SURFACE_CAPTURE_NOT_FOUND) => RenderInfo {
-            summary: "surface capture transaction was not found",
-            hint: Some(
-                "take a fresh surface screenshot and use its capture id with coordinates from that image",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_EXPIRED) => RenderInfo {
-            summary: "surface capture transaction has expired",
-            hint: Some(
-                "take a fresh surface screenshot, then click promptly with that capture id and image coordinates",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_CONSUMED) => RenderInfo {
-            summary: "surface capture transaction was already used",
-            hint: Some(
-                "each capture id is single-use; take a fresh surface screenshot before another point action",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::PermissionDenied, reason::SURFACE_CAPTURE_STALE) => RenderInfo {
-            summary: "page state changed since the surface screenshot",
-            hint: Some(
-                "take a fresh surface screenshot and choose coordinates from the new image before retrying",
-            ),
-            exit_code: base.exit_code,
-        },
-        (ErrorCode::InvalidParams, reason::SURFACE_COORDINATE_INVALID) => RenderInfo {
-            summary: "surface image coordinate is invalid",
-            hint: Some(
-                "use finite pixel coordinates inside the captured image; its top-left corner is (0, 0)",
-            ),
-            exit_code: base.exit_code,
-        },
         (
             ErrorCode::CdpFailed | ErrorCode::Timeout | ErrorCode::InvalidParams,
             reason::RECORD_START_PAGE_UNREACHABLE,
@@ -612,18 +564,6 @@ mod tests {
         assert_eq!(info.exit_code, 3);
     }
 
-    #[test]
-    fn ref_capability_denied_explains_visual_surface_refs() {
-        let data = serde_json::json!({ "reason": reason::REF_CAPABILITY_DENIED });
-        let info = info_for_error(ErrorCode::PermissionDenied, Some(&data));
-        assert_eq!(info.summary, "snapshot ref does not support this operation");
-        assert!(
-            info.hint.unwrap().contains("capture id"),
-            "expected visual-surface-specific hint"
-        );
-        assert_eq!(info.exit_code, 1);
-    }
-
     #[test]
     fn session_busy_overrides_timeout_copy() {
         let data = serde_json::json!({ "reason": reason::SESSION_BUSY });
@@ -724,25 +664,6 @@ mod tests {
         assert!(info.summary.contains("timed out after browser dispatch"));
     }
 
-    #[test]
-    fn surface_capture_stale_requests_a_fresh_screenshot() {
-        let data = serde_json::json!({ "reason": reason::SURFACE_CAPTURE_STALE });
-        let info = info_for_error(ErrorCode::PermissionDenied, Some(&data));
-        assert_eq!(
-            info.summary,
-            "page state changed since the surface screenshot"
-        );
-        assert!(info.hint.unwrap().contains("fresh surface screenshot"));
-    }
-
-    #[test]
-    fn surface_coordinate_invalid_explains_image_pixel_bounds() {
-        let data = serde_json::json!({ "reason": reason::SURFACE_COORDINATE_INVALID });
-        let info = info_for_error(ErrorCode::InvalidParams, Some(&data));
-        assert_eq!(info.summary, "surface image coordinate is invalid");
-        assert!(info.hint.unwrap().contains("top-left corner is (0, 0)"));
-    }
-
     #[test]
     fn ref_not_found_overrides_not_found_copy() {
         let data = serde_json::json!({ "reason": reason::REF_NOT_FOUND });

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

@@ -59,7 +59,7 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
         .map_err(CliError::Local)?;
     match format {
         Format::Json => {
-            let mut json = serde_json::json!({
+            let json = serde_json::json!({
                 "tab_id": reply.tab_id,
                 "width": reply.width,
                 "height": reply.height,
@@ -67,10 +67,6 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
                 "path": out_path.to_string_lossy(),
                 "byte_size": bytes.len(),
             });
-            if let Some(capture) = &reply.capture {
-                json["capture"] = serde_json::to_value(capture)
-                    .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?;
-            }
             println!(
                 "{}",
                 serde_json::to_string_pretty(&json)
@@ -79,12 +75,6 @@ fn run(sock: PathBuf, args: ScreenshotArgs, format: Format) -> Result<(), CliErr
         }
         Format::Human => {
             println!("{}", out_path.display());
-            if let Some(capture) = &reply.capture {
-                println!(
-                    "capture={} surface={} coordinate_space={} expires_at={}",
-                    capture.id, capture.surface_ref, capture.coordinate_space, capture.expires_at
-                );
-            }
             print_dialog_summaries(&reply.dialogs);
         }
     }

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

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

crates/bsk-cli/tests/cli_parse.rs

@@ -237,29 +237,6 @@ fn parses_click_count_alias() {
     assert_eq!(args.click_count, 2);
 }
 
-#[test]
-fn parses_surface_capture_image_coordinates() {
-    let cli = parse(&[
-        "bsk",
-        "click",
-        "@e1",
-        "--session",
-        "s1",
-        "--capture",
-        "sc_test",
-        "--image-x",
-        "160.5",
-        "--image-y",
-        "-1",
-    ]);
-    let Command::Click(args) = cli.command else {
-        panic!("expected click command");
-    };
-    assert_eq!(args.capture.as_deref(), Some("sc_test"));
-    assert_eq!(args.image_x, Some(160.5));
-    assert_eq!(args.image_y, Some(-1.0));
-}
-
 #[test]
 fn parses_hover_with_settle() {
     let cli = parse(&[

crates/bsk-cli/tests/tools_ipc.rs

@@ -238,7 +238,6 @@ async fn screenshot_returns_image_base64_with_dimensions() {
                 height: 600,
                 format: "png".into(),
                 tab_id: 7,
-                capture: None,
                 dialogs: vec![],
             })
             .unwrap(),
@@ -287,7 +286,6 @@ async fn screenshot_forwards_ref_to_extension() {
                 height: 60,
                 format: "png".into(),
                 tab_id: 7,
-                capture: None,
                 dialogs: vec![],
             })
             .unwrap(),

crates/bsk-cli/tests/tools_m7_ipc.rs

@@ -354,9 +354,6 @@ async fn click_round_trips_ref_and_modifiers() {
                 used_selector: None,
                 x: 12.5,
                 y: 34.0,
-                capture_id: None,
-                image_x: None,
-                image_y: None,
                 dialogs: vec![],
             })
             .unwrap(),
@@ -376,9 +373,6 @@ async fn click_round_trips_ref_and_modifiers() {
             click_count: Some(1),
             modifiers: Some(vec![KeyModifier::Ctrl, KeyModifier::Shift]),
             timeout_ms: Some(5_000),
-            capture_id: None,
-            image_x: None,
-            image_y: None,
         },
     )
     .await
@@ -616,9 +610,6 @@ async fn m7_tools_propagate_extension_errors() {
             click_count: None,
             modifiers: None,
             timeout_ms: Some(5_000),
-            capture_id: None,
-            image_x: None,
-            image_y: None,
         },
     )
     .await

crates/bsk-cli/tests/windows_parent_cancel.rs

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

crates/bsk-protocol/schema/tool_click_params.json

@@ -16,13 +16,6 @@
         }
       ]
     },
-    "capture_id": {
-      "description": "Short-lived capture id returned by a visual Surface screenshot.",
-      "type": [
-        "string",
-        "null"
-      ]
-    },
     "click_count": {
       "description": "Number of consecutive mouse presses (double-click = 2).",
       "type": [
@@ -32,22 +25,6 @@
       "format": "uint32",
       "minimum": 1.0
     },
-    "image_x": {
-      "description": "X coordinate in the capture image's pixel coordinate space.",
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
-    "image_y": {
-      "description": "Y coordinate in the capture image's pixel coordinate space.",
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
     "modifiers": {
       "type": [
         "array",

crates/bsk-protocol/schema/tool_click_result.json

@@ -8,12 +8,6 @@
     "y"
   ],
   "properties": {
-    "capture_id": {
-      "type": [
-        "string",
-        "null"
-      ]
-    },
     "dialogs": {
       "description": "Native JS dialogs observed and auto-handled during this call.",
       "type": "array",
@@ -21,20 +15,6 @@
         "$ref": "#/definitions/JavaScriptDialogInfo"
       }
     },
-    "image_x": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
-    "image_y": {
-      "type": [
-        "number",
-        "null"
-      ],
-      "format": "double"
-    },
     "tab_id": {
       "type": "integer",
       "format": "int64"

crates/bsk-protocol/schema/tool_screenshot_result.json

@@ -8,16 +8,6 @@
     "tab_id"
   ],
   "properties": {
-    "capture": {
-      "anyOf": [
-        {
-          "$ref": "#/definitions/SurfaceCaptureInfo"
-        },
-        {
-          "type": "null"
-        }
-      ]
-    },
     "dialogs": {
       "type": "array",
       "items": {
@@ -119,31 +109,6 @@
         "prompt",
         "beforeunload"
       ]
-    },
-    "SurfaceCaptureInfo": {
-      "type": "object",
-      "required": [
-        "coordinate_space",
-        "expires_at",
-        "id",
-        "surface_ref"
-      ],
-      "properties": {
-        "coordinate_space": {
-          "type": "string"
-        },
-        "expires_at": {
-          "type": "integer",
-          "format": "uint64",
-          "minimum": 0.0
-        },
-        "id": {
-          "type": "string"
-        },
-        "surface_ref": {
-          "type": "string"
-        }
-      }
     }
   }
 }

crates/bsk-protocol/src/tools/interaction.rs

@@ -67,15 +67,6 @@ pub struct ClickParams {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     #[schemars(range(min = 1))]
     pub timeout_ms: Option<u32>,
-    /// Short-lived capture id returned by a visual Surface screenshot.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture_id: Option<String>,
-    /// X coordinate in the capture image's pixel coordinate space.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_x: Option<f64>,
-    /// Y coordinate in the capture image's pixel coordinate space.
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_y: Option<f64>,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
@@ -89,12 +80,6 @@ pub struct ClickResult {
     /// agents can correlate with a follow-up `tool.screenshot`.
     pub x: f64,
     pub y: f64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture_id: Option<String>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_x: Option<f64>,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub image_y: Option<f64>,
     /// Native JS dialogs observed and auto-handled during this call.
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub dialogs: Vec<JavaScriptDialogInfo>,
@@ -303,9 +288,6 @@ mod tests {
             click_count: Some(1),
             modifiers: Some(vec![KeyModifier::Ctrl]),
             timeout_ms: Some(5_000),
-            capture_id: Some("sc_test".into()),
-            image_x: Some(160.0),
-            image_y: Some(90.0),
         };
         let v = serde_json::to_value(&p).unwrap();
         assert_eq!(v.get("ref").and_then(|v| v.as_str()), Some("@e3"));

crates/bsk-protocol/src/tools/observation.rs

@@ -233,20 +233,10 @@ pub struct ScreenshotResult {
     /// Always `"png"` in v0.1; reserved for future JPEG / WebP support.
     pub format: String,
     pub tab_id: i64,
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub capture: Option<SurfaceCaptureInfo>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub dialogs: Vec<JavaScriptDialogInfo>,
 }
 
-#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
-pub struct SurfaceCaptureInfo {
-    pub id: String,
-    pub surface_ref: String,
-    pub coordinate_space: String,
-    pub expires_at: u64,
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -328,12 +318,6 @@ mod tests {
             height: 600,
             format: "png".into(),
             tab_id: 7,
-            capture: Some(SurfaceCaptureInfo {
-                id: "sc_test".into(),
-                surface_ref: "@e3".into(),
-                coordinate_space: "capture-image-pixel".into(),
-                expires_at: 1_700_000_030_000,
-            }),
             dialogs: vec![],
         };
         let v = serde_json::to_value(&r).unwrap();

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

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

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

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

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

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

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

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

evals/browser/tests/eval.test.mjs

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

install.ps1

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

packages/dsh-plugin-browserskill/README.md

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

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

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

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
   "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -47,7 +47,6 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-tool",
         "@deepseek-ai/dsh-client-ui-layout"
       ],
@@ -69,7 +68,6 @@
   "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",
@@ -82,9 +80,6 @@
     "@deepseek-ai/dsh-attachment": {
       "optional": true
     },
-    "@deepseek-ai/dsh-client-runtime": {
-      "optional": true
-    },
     "@deepseek-ai/dsh-client-ui-attachment": {
       "optional": true
     },

packages/dsh-plugin-browserskill/src/client/index.ts

@@ -7,6 +7,7 @@
  */
 
 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";

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

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

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

@@ -489,9 +489,7 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       ? "Capture an indented aria-tree snapshot of the session's active tab. Interactive elements " +
         "carry @eN refs for browser_interact actions. Prefer browser_inspect action=observe for a richer semantic view."
       : "Produce a semantic VOM observation of the session's active tab (roles, states, perception " +
-        "probes) with @eN refs for browser_interact actions. Visual-only surfaces require image " +
-        "understanding and their refs are screenshot-only; keep using any DOM/AX semantics rendered " +
-        "alongside them. Read-only: never submits input.";
+        "probes) with @eN refs for browser_interact actions. Read-only: never submits input.";
     register(
       defineTool({
         name,
@@ -563,8 +561,7 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       name: "interact.click",
       description:
         "Click an element in the session's active tab. Target is a snapshot ref (@e3) from the " +
-        "last browser_inspect observation, or a CSS selector. A visual Surface requires the " +
-        "captureId and image coordinates returned by browser_inspect action=screenshot.",
+        "last browser_inspect observation, or a CSS selector.",
       parameters: {
         target: {
           type: "string",
@@ -581,24 +578,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
           type: "integer",
           description: "Number of consecutive presses (double-click = 2).",
         },
-        modifiers: {
-          type: "array",
-          items: { type: "string", enum: ["alt", "ctrl", "meta", "shift"] },
-          description: "Keyboard modifiers held during the click.",
-        },
-        captureId: {
-          type: "string",
-          description:
-            "Short-lived Surface capture id returned by browser_inspect action=screenshot.",
-        },
-        imageX: {
-          type: "number",
-          description: "X coordinate in capture-image pixels; requires captureId and imageY.",
-        },
-        imageY: {
-          type: "number",
-          description: "Y coordinate in capture-image pixels; requires captureId and imageX.",
-        },
       },
       output: {
         schema: {
@@ -609,7 +588,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             tabId: { type: "integer", required: true },
             x: { type: "number", required: true },
             y: { type: "number", required: true },
-            captureId: { type: "string" },
           },
         },
         render: (_args, value) => [
@@ -621,44 +599,17 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       },
       async execute(args, exec) {
         if (args.target.trim().length === 0) throw new Error("target must be a non-empty string");
-        const pointArgCount =
-          Number(args.captureId !== undefined) +
-          Number(args.imageX !== undefined) +
-          Number(args.imageY !== undefined);
-        if (pointArgCount !== 0 && pointArgCount !== 3) {
-          throw new Error("captureId, imageX, and imageY must be given together");
-        }
         const sessionId = registry.resolve(args.session, "browser_interact(action=click)");
         const cmdArgs = ["click", "--session", sessionId];
         if (args.button !== undefined) cmdArgs.push("--button", args.button);
         if (args.clickCount !== undefined) cmdArgs.push("--click-count", String(args.clickCount));
-        if (args.modifiers !== undefined && args.modifiers.length > 0) {
-          cmdArgs.push("--modifiers", args.modifiers.join(","));
-        }
-        if (args.captureId !== undefined) {
-          cmdArgs.push(
-            "--capture",
-            args.captureId,
-            "--image-x",
-            String(args.imageX),
-            "--image-y",
-            String(args.imageY),
-          );
-        }
         cmdArgs.push(args.target);
         const reply = (await runBsk(deps, exec, cmdArgs, "click", sessionId)) as {
           tab_id: number;
           x: number;
           y: number;
-          capture_id?: string;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          x: reply.x,
-          y: reply.y,
-          ...(reply.capture_id !== undefined ? { captureId: reply.capture_id } : {}),
         };
+        return { session: sessionId, tabId: reply.tab_id, x: reply.x, y: reply.y };
       },
       presentCall: (args) => ({
         card: "terminal",
@@ -803,17 +754,12 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       name: "inspect.screenshot",
       description:
         "Capture a PNG screenshot of the session's active tab, or crop to a snapshot ref element. " +
-        "This is the supported operation for visual surface refs emitted by inspect.observe. Only use " +
-        "it to interpret a visual-only surface when you can inspect image output. If you lack multimodal " +
-        "or image-reading capability, tell the user to switch to a model with image understanding; do " +
-        "not guess content or coordinates. " +
         "Returns the image itself when the deployment supports image input, otherwise a file path.",
       parameters: {
         session: SESSION_PARAM,
         ref: {
           type: "string",
-          description:
-            "Ref (@e3) from the last snapshot/observe; crops to that DOM element or visual surface.",
+          description: "Snapshot ref (@e3) from the last snapshot/observe; crops to that element.",
         },
       },
       output: {
@@ -827,8 +773,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             width: { type: "integer", required: true },
             height: { type: "integer", required: true },
             byteSize: { type: "integer", required: true },
-            captureId: { type: "string" },
-            captureExpiresAt: { type: "integer" },
             image: {
               type: "object",
               additionalProperties: false,
@@ -852,11 +796,7 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             value.image !== undefined
               ? `[session ${value.session}] screenshot of tab ${value.tabId} (${value.width}x${value.height}px)`
               : `[session ${value.session}] screenshot saved to ${value.path} (${value.width}x${value.height}px, ${value.byteSize} bytes) — this deployment cannot inline images; read the file to view it`;
-          const captureText =
-            value.captureId !== undefined
-              ? ` Surface capture ${value.captureId} uses capture-image-pixel coordinates and expires at ${value.captureExpiresAt}.`
-              : "";
-          const blocks: ContentBlock[] = [{ type: "text", text: text + captureText }];
+          const blocks: ContentBlock[] = [{ type: "text", text }];
           if (value.image !== undefined) {
             blocks.push({
               type: "image",
@@ -895,7 +835,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             height: number;
             path: string;
             byte_size: number;
-            capture?: { id: string; expires_at: number };
           };
           writtenPath = reply.path;
           const data = await readFile(reply.path);
@@ -909,9 +848,6 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
             width: reply.width,
             height: reply.height,
             byteSize: reply.byte_size,
-            ...(reply.capture !== undefined
-              ? { captureId: reply.capture.id, captureExpiresAt: reply.capture.expires_at }
-              : {}),
             ...(ref !== undefined
               ? {
                   image: {

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

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

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

@@ -478,12 +478,12 @@ describe("interaction tools", () => {
     emulate: { tab_id: 7, cleared: false },
   };
 
-  it("interact.click maps target, button, click count, and modifiers", async () => {
+  it("interact.click maps target, button, and click count", async () => {
     const { tools, calls } = setup(responses);
     await startSession(tools);
     const click = tools.get("interact.click");
     const value = (await click?.execute(
-      { target: "@e1", button: "right", clickCount: 2, modifiers: ["ctrl", "shift"] },
+      { target: "@e1", button: "right", clickCount: 2 },
       makeExec(),
     )) as { session: string; x: number; y: number };
     expect(value).toMatchObject({ session: "s1", x: 10, y: 20 });
@@ -495,43 +495,6 @@ describe("interaction tools", () => {
       "right",
       "--click-count",
       "2",
-      "--modifiers",
-      "ctrl,shift",
-      "@e1",
-    ]);
-  });
-
-  it("interact.click forwards a complete Surface capture coordinate transaction", async () => {
-    const { tools, calls } = setup({
-      ...responses,
-      click: {
-        tab_id: 7,
-        used_ref: "e1",
-        x: 110,
-        y: 70,
-        capture_id: "sc_test",
-        image_x: 200,
-        image_y: 100,
-      },
-    });
-    await startSession(tools);
-    const click = tools.get("interact.click");
-    const value = await click?.execute(
-      { target: "@e1", captureId: "sc_test", imageX: 200, imageY: 100 },
-      makeExec(),
-    );
-
-    expect(value).toMatchObject({ captureId: "sc_test", x: 110, y: 70 });
-    expect(calls[1].args).toEqual([
-      "click",
-      "--session",
-      "s1",
-      "--capture",
-      "sc_test",
-      "--image-x",
-      "200",
-      "--image-y",
-      "100",
       "@e1",
     ]);
   });
@@ -960,32 +923,6 @@ describe("inspect.screenshot", () => {
     expect(rendered?.every((block) => block.type === "text")).toBe(true);
   });
 
-  it("returns Surface capture metadata alongside the screenshot", async () => {
-    const path = pngFile();
-    const { tools } = setup({
-      "session start": START_REPLY("s1"),
-      screenshot: {
-        tab_id: 7,
-        width: 800,
-        height: 600,
-        format: "png",
-        path,
-        byte_size: 8,
-        capture: { id: "sc_test", expires_at: 1700000030000 },
-      },
-    });
-    await startSession(tools);
-    const screenshot = tools.get("inspect.screenshot");
-    const value = await screenshot?.execute({ ref: "@e1" }, makeExec());
-
-    expect(value).toMatchObject({
-      captureId: "sc_test",
-      captureExpiresAt: 1700000030000,
-    });
-    const rendered = screenshot?.output.render({ session: "s1" }, value as never);
-    expect(rendered?.[0]).toMatchObject({ type: "text", text: expect.stringContaining("sc_test") });
-  });
-
   it("commits the image through the attachment store on an image-capable route", async () => {
     const path = pngFile();
     const services = {

packages/dsh-plugin-browserskill/tsdown.config.ts

@@ -25,7 +25,6 @@ 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. */

packages/vom/src/__tests__/render.test.ts

@@ -29,139 +29,6 @@ function coreRefs(refs: ReturnType<typeof renderVom>["refs"]) {
 }
 
 describe("renderVom single-layer page", () => {
-  it("renders visual surfaces as screenshot-only refs", () => {
-    const input = scene([
-      node({ id: 1, role: "RootWebArea", frameId: "main" }),
-      node({ id: 2, parentId: 1, role: "Iframe", frameId: "main", backendNodeId: 20 }),
-    ]);
-    input.visualSurfaces = [
-      {
-        parentId: 2,
-        backendNodeId: 99,
-        frameId: "child",
-        renderingKind: "canvas",
-        visibleRect: { x: 10, y: 20, w: 800, h: 500 },
-        label: "Data grid",
-        memberCount: 2,
-      },
-    ];
-    const out = renderVom(input);
-
-    expect(out.text).toContain("[visual surfaces]");
-    expect(out.text).toContain(
-      '@e1 surface "Data grid" [bounds=10,20,800,500; rendering=canvas; layers=2; visual-only; requires=image-understanding; use: bsk screenshot --ref @e1]',
-    );
-    expect(out.refs).toContainEqual(
-      expect.objectContaining({
-        ref: "e1",
-        backendNodeId: 99,
-        kind: "surface",
-        visibleRect: { x: 10, y: 20, w: 800, h: 500 },
-        capabilities: ["screenshot"],
-      }),
-    );
-  });
-
-  it("renders an unnamed visual surface with a stable generic label", () => {
-    const input = scene([node({ id: 1, role: "RootWebArea", frameId: "main" })]);
-    input.visualSurfaces = [
-      {
-        parentId: 1,
-        backendNodeId: 99,
-        frameId: "main",
-        renderingKind: "canvas",
-        visibleRect: { x: 10, y: 20, w: 800, h: 500 },
-        memberCount: 1,
-      },
-    ];
-
-    const out = renderVom(input);
-
-    expect(out.text).toContain(
-      '@e1 surface "canvas visual surface" [bounds=10,20,800,500; rendering=canvas; visual-only; requires=image-understanding; use: bsk screenshot --ref @e1]',
-    );
-    expect(out.refs).toContainEqual(
-      expect.objectContaining({
-        ref: "e1",
-        name: "canvas visual surface",
-        kind: "surface",
-        capabilities: ["screenshot"],
-      }),
-    );
-  });
-
-  it("appends visual refs after DOM refs so canvas density cannot renumber controls", () => {
-    const input = scene([
-      node({ id: 1, role: "RootWebArea", frameId: "main" }),
-      node({ id: 2, parentId: 1, role: "button", name: "Submit", tag: "button" }),
-    ]);
-    input.visualSurfaces = [
-      {
-        parentId: 1,
-        backendNodeId: 99,
-        frameId: "main",
-        renderingKind: "canvas",
-        visibleRect: { x: 10, y: 20, w: 80, h: 50 },
-        memberCount: 1,
-      },
-    ];
-
-    const withoutVisuals = renderVom({ ...input, visualSurfaces: [] });
-    const withVisuals = renderVom(input);
-
-    expect(withoutVisuals.refs[0]).toMatchObject({ ref: "e1", backendNodeId: 2, kind: "dom" });
-    expect(withVisuals.refs[0]).toMatchObject({ ref: "e1", backendNodeId: 2, kind: "dom" });
-    expect(withVisuals.refs[1]).toMatchObject({ ref: "e2", backendNodeId: 99, kind: "surface" });
-    expect(withVisuals.text.indexOf('@e1 button "Submit"')).toBeLessThan(
-      withVisuals.text.indexOf("[visual surfaces]"),
-    );
-  });
-
-  it("bounds visual output and prefers explicitly labeled surfaces", () => {
-    const input = scene([node({ id: 1, role: "RootWebArea", frameId: "main" })]);
-    input.visualSurfaces = Array.from({ length: 12 }, (_, index) => ({
-      parentId: 1,
-      backendNodeId: 100 + index,
-      frameId: "main",
-      renderingKind: "canvas" as const,
-      visibleRect: { x: index * 10, y: 20, w: 8, h: 8 },
-      ...(index === 11 ? { label: "Important status" } : {}),
-      memberCount: 1,
-    }));
-
-    const out = renderVom(input);
-    const surfaceRefs = out.refs.filter((ref) => ref.kind === "surface");
-
-    expect(surfaceRefs).toHaveLength(8);
-    expect(surfaceRefs[0]).toMatchObject({ backendNodeId: 111, name: "Important status" });
-    expect(out.text).toContain("… 4 additional visual surfaces omitted");
-    expect(out.truncated).toBe(true);
-  });
-
-  it("does not let a visual surface exhaust the budget before later DOM content", () => {
-    const input = scene([
-      node({ id: 1, role: "RootWebArea", name: "Doc", frameId: "main" }),
-      node({ id: 2, parentId: 1, role: "button", name: "First", tag: "button" }),
-      node({ id: 3, parentId: 1, role: "button", name: "Later", tag: "button" }),
-    ]);
-    input.visualSurfaces = [
-      {
-        parentId: 1,
-        backendNodeId: 99,
-        frameId: "main",
-        renderingKind: "canvas",
-        visibleRect: { x: 10, y: 20, w: 800, h: 500 },
-        memberCount: 1,
-      },
-    ];
-
-    const out = renderVom(input, { maxTokens: 30 });
-
-    expect(out.text).toContain('@e2 button "Later"');
-    expect(out.refs.filter((ref) => ref.kind === "surface")).toHaveLength(0);
-    expect(out.truncated).toBe(true);
-  });
-
   it("does not derive handle context across frame scopes", () => {
     const out = renderVom(
       scene([

packages/vom/src/index.ts

@@ -15,8 +15,6 @@ export type {
   VomNode,
   VomOptions,
   VomRef,
-  VomRefCapability,
   VomResult,
   VomScene,
-  VomVisualSurface,
 } from "./types";

packages/vom/src/render.ts

@@ -9,7 +9,6 @@ import type {
   VomOptions,
   VomResult,
   VomScene,
-  VomVisualSurface,
 } from "./types";
 
 const SKIP_ROLES = new Set(["generic", "none", "presentation", "inlinetextbox"]);
@@ -88,7 +87,6 @@ const MAX_CUSTOM_RECOVERY_AREA = 180_000;
 const MAX_RECOVERABLE_SINGLE_INTENT_AREA = 360_000;
 const MAX_HANDLE_CONTEXT_ITEMS = 3;
 const MAX_SURFACE_ITEMS = 12;
-const MAX_VISUAL_SURFACES = 8;
 const MAX_SCOPE_LINES = 40;
 const RECOVERY_HANDLER_ATTRS = ["onclick", "onmousedown", "onkeydown", "onkeyup", "onkeypress"];
 const NATIVE_TAGS = new Set(["button", "input", "select", "textarea"]);
@@ -795,108 +793,6 @@ interface RenderState {
   duplicateRefNames: Set<string>;
   surfaceMap: Map<number, CondSurface>;
   scopeMap: Map<number, ActiveScopeBlock>;
-  visualSurfaces: VomVisualSurface[];
-}
-
-function visualSurfaceArea(surface: VomVisualSurface): number {
-  return Math.max(0, surface.visibleRect.w) * Math.max(0, surface.visibleRect.h);
-}
-
-function compareVisualSurfaces(a: VomVisualSurface, b: VomVisualSurface): number {
-  const aLabeled = cleaned(a.label) !== undefined;
-  const bLabeled = cleaned(b.label) !== undefined;
-  return (
-    Number(bLabeled) - Number(aLabeled) ||
-    visualSurfaceArea(b) - visualSurfaceArea(a) ||
-    a.frameId.localeCompare(b.frameId) ||
-    a.visibleRect.y - b.visibleRect.y ||
-    a.visibleRect.x - b.visibleRect.x ||
-    a.backendNodeId - b.backendNodeId
-  );
-}
-
-function visualSurfaceLine(surface: VomVisualSurface, ref: string): string {
-  const label = cleaned(surface.label) ?? `${surface.renderingKind} visual surface`;
-  const layers = surface.memberCount > 1 ? `; layers=${surface.memberCount}` : "";
-  const { x, y, w, h } = surface.visibleRect;
-  const bounds = [x, y, w, h].map(Math.round).join(",");
-  return `  @${ref} surface ${JSON.stringify(label)} [bounds=${bounds}; rendering=${surface.renderingKind}${layers}; visual-only; requires=image-understanding; use: bsk screenshot --ref @${ref}]`;
-}
-
-function selectVisualSurfaces(
-  surfaces: readonly VomVisualSurface[],
-  nodesById: ReadonlyMap<number, VomNode>,
-): { selected: VomVisualSurface[]; eligibleCount: number } {
-  const selected: VomVisualSurface[] = [];
-  let eligibleCount = 0;
-
-  for (const surface of surfaces) {
-    if (surface.parentId !== null && !nodesById.has(surface.parentId)) continue;
-    eligibleCount += 1;
-
-    const insertionIndex = selected.findIndex(
-      (candidate) => compareVisualSurfaces(surface, candidate) < 0,
-    );
-    if (insertionIndex < 0) {
-      if (selected.length < MAX_VISUAL_SURFACES) selected.push(surface);
-      continue;
-    }
-    selected.splice(insertionIndex, 0, surface);
-    if (selected.length > MAX_VISUAL_SURFACES) selected.pop();
-  }
-
-  return { selected, eligibleCount };
-}
-
-function emitVisualAppendix(state: RenderState): void {
-  if (state.stopped) return;
-  const { selected, eligibleCount } = selectVisualSurfaces(state.visualSurfaces, state.nodesById);
-  if (eligibleCount === 0) return;
-
-  const header = "[visual surfaces]";
-  let headerEmitted = false;
-  let emitted = 0;
-  for (const surface of selected) {
-    const ref = `e${state.nextRef}`;
-    const line = visualSurfaceLine(surface, ref);
-    const nextTokens =
-      state.tokens + estimateTokens(line) + (headerEmitted ? 0 : estimateTokens(header));
-    if (nextTokens > state.maxTokens) break;
-    if (!headerEmitted) {
-      state.lines.push(header);
-      state.tokens += estimateTokens(header);
-      headerEmitted = true;
-    }
-    state.lines.push(line);
-    state.tokens += estimateTokens(line);
-    const label = cleaned(surface.label) ?? `${surface.renderingKind} visual surface`;
-    state.refs.push({
-      ref,
-      backendNodeId: surface.backendNodeId,
-      frameId: surface.frameId,
-      visibleRect: surface.visibleRect,
-      role: "surface",
-      name: label,
-      kind: "surface",
-      capabilities: ["screenshot"],
-      line: state.lines.length - 1,
-    });
-    state.nextRef += 1;
-    emitted += 1;
-  }
-
-  const omitted = eligibleCount - emitted;
-  if (omitted > 0) {
-    state.truncated = true;
-    if (headerEmitted) {
-      const summary = `  … ${omitted} additional visual surfaces omitted`;
-      const nextTokens = state.tokens + estimateTokens(summary);
-      if (nextTokens <= state.maxTokens) {
-        state.lines.push(summary);
-        state.tokens = nextTokens;
-      }
-    }
-  }
 }
 
 function emitActiveScopeBlock(scope: ActiveScopeBlock, depth: number, state: RenderState): void {
@@ -977,8 +873,6 @@ function renderTree(children: Map<number | null, VomNode[]>, state: RenderState)
         ...(node.role ? { role: node.role } : {}),
         ...(name ? { name } : {}),
         ...(context.length > 0 ? { ctx: context.join(" > ") } : {}),
-        kind: "dom",
-        capabilities: ["interact", "screenshot"],
         line: state.lines.length - 1,
       });
       state.nextRef += 1;
@@ -1000,7 +894,6 @@ function renderNodes(
   initialLines: string[],
   surfaces: CondSurface[] = [],
   activeScopeBlocks: ActiveScopeBlock[] = [],
-  visualSurfaces: VomVisualSurface[] = [],
 ): RenderState {
   const children = buildChildren(nodes);
   const state: RenderState = {
@@ -1020,7 +913,6 @@ function renderNodes(
     duplicateRefNames: duplicateReferenceNames(nodes),
     surfaceMap: new Map(surfaces.map((surface) => [surface.triggerId, surface])),
     scopeMap: new Map(activeScopeBlocks.map((scope) => [scope.triggerId, scope])),
-    visualSurfaces,
   };
 
   renderTree(children, state);
@@ -1232,20 +1124,8 @@ function renderDoubleLayer(scene: VomScene, layer: BlockingLayer, options: VomOp
     "@layers 2 focus=L1",
     `L1 ${layer.kind} cover=${Math.round(layer.coverage * 100)}%`,
   ];
-  const visibleSurface = (parentId: number | null): boolean =>
-    parentId === null || included.has(parentId);
-  const state = renderNodes(
-    visibleNodes,
-    options,
-    header,
-    scene.surfaces,
-    scene.activeScopeBlocks,
-    scene.visualSurfaces?.filter((surface) => visibleSurface(surface.parentId)),
-  );
-  const occlusionLine = renderPageOcclusionLine(hiddenCount);
-  state.lines.push(occlusionLine);
-  state.tokens += estimateTokens(occlusionLine);
-  emitVisualAppendix(state);
+  const state = renderNodes(visibleNodes, options, header, scene.surfaces, scene.activeScopeBlocks);
+  state.lines.push(renderPageOcclusionLine(hiddenCount));
 
   return {
     text: state.lines.join("\n"),
@@ -1272,9 +1152,7 @@ export function renderVom(scene: VomScene, options: VomOptions = {}): VomResult
     ],
     scene.surfaces,
     scene.activeScopeBlocks,
-    scene.visualSurfaces,
   );
-  emitVisualAppendix(state);
 
   return {
     text: state.lines.join("\n"),

packages/vom/src/types.ts

@@ -61,8 +61,6 @@ export interface VomScene {
   rootFrameId?: string;
   surfaces?: CondSurface[];
   activeScopeBlocks?: ActiveScopeBlock[];
-  /** Non-semantic rendered regions discovered alongside the AX/DOM tree. */
-  visualSurfaces?: VomVisualSurface[];
 }
 
 export interface VomOptions {
@@ -96,22 +94,6 @@ export interface VomRef {
   ref: string;
   backendNodeId: number;
   frameId?: string;
-  /** Observation-time top-viewport crop for screenshot-only surfaces. */
-  visibleRect?: Rect;
-  kind?: "dom" | "surface";
-  capabilities?: VomRefCapability[];
-}
-
-export type VomRefCapability = "interact" | "screenshot";
-
-export interface VomVisualSurface {
-  parentId: number | null;
-  backendNodeId: number;
-  frameId: string;
-  renderingKind: "canvas";
-  visibleRect: Rect;
-  label?: string;
-  memberCount: number;
 }
 
 export interface RenderedRef extends VomRef {

scripts/install-windows.test.ps1

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