fix(vom): add new texts and fix bugs

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

@@ -13,6 +13,8 @@ describe("RefStore", () => {
       backendNodeId: 42,
       tabId: 7,
       generation: 0,
+      kind: "dom",
+      capabilities: ["interact", "screenshot"],
     });
     expect(s.size()).toBe(1);
     expect(s.isEmpty()).toBe(false);
@@ -48,4 +50,41 @@ 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"]);
+  });
+
+  it("copies caller-owned capability arrays", () => {
+    const s = new RefStore();
+    const capabilities: Array<"interact" | "screenshot"> = ["screenshot"];
+    s.set("e1", 42, { tabId: 7, capabilities });
+
+    capabilities.push("interact");
+
+    expect(s.resolveEntry("e1")?.capabilities).toEqual(["screenshot"]);
+  });
 });

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

@@ -1,3 +1,5 @@
+import type { Rect } from "@browser-skill/vom";
+
 /**
  * Per-session map from `@e<N>` snapshot refs to a CDP node address.
  *
@@ -12,12 +14,17 @@
  * 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;
 }
 
@@ -28,8 +35,19 @@ 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 ? [...capabilities] : ["interact", "screenshot"];
+}
+
 export class RefStore {
   private readonly map = new Map<string, RefEntry>();
   private generation = 0;
@@ -70,13 +88,20 @@ 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,
     });
   }
@@ -94,14 +119,20 @@ 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/tools/__tests__/frame-geometry.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolveNodeGeometry } from "../frame-geometry";
+import {
+  createFrameGeometryContext,
+  resolveFrameProjection,
+  resolveNodeGeometry,
+} from "../frame-geometry";
 import {
   clipPolygon,
   polygonArea,
@@ -10,7 +14,6 @@ import {
   rectPolygon,
   regionBounds,
 } from "../geometry";
-import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 
 describe("frame geometry projection", () => {
@@ -38,6 +41,53 @@ describe("frame geometry projection", () => {
     expect(polygonBounds(projected.flat())).toEqual({ x: 224, y: 346, width: 200, height: 80 });
   });
 
+  it("projects nested same-target frame-local bounds through authoritative content quads", async () => {
+    const boxCalls: number[] = [];
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1_000, clientHeight: 800 } };
+        }
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 91 };
+        if (method === "Runtime.evaluate") {
+          return { result: { value: { width: 100, height: 80 } } };
+        }
+        if (method === "DOM.getBoxModel") {
+          const backendNodeId = (params as { backendNodeId?: number }).backendNodeId ?? 0;
+          boxCalls.push(backendNodeId);
+          return backendNodeId === 10
+            ? { model: { content: [30, 100.5, 330, 100.5, 330, 300.5, 30, 300.5] } }
+            : { model: { content: [45, 120.5, 145, 120.5, 145, 200.5, 45, 200.5] } };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as CdpRunner["send"],
+    };
+    const geometry = createFrameGeometryContext(cdp, {
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        {
+          frameId: "child",
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+          target: { tabId: 4 },
+        },
+        {
+          frameId: "nested",
+          parentFrameId: "child",
+          ownerBackendNodeId: 20,
+          target: { tabId: 4 },
+        },
+      ],
+    });
+
+    await expect(
+      geometry.projectFrameLocalRect("nested", { x: 12, y: 12, w: 40, h: 20 }),
+    ).resolves.toEqual({ x: 57, y: 132.5, width: 40, height: 20 });
+    await geometry.projectFrameLocalRect("nested", { x: 1, y: 1, w: 2, h: 2 });
+    expect(boxCalls.sort()).toEqual([10, 20]);
+  });
+
   it("uses a projective mapping for perspective-transformed iframe quads", () => {
     const quad: Quad = [
       { x: 0, y: 0 },
@@ -83,24 +133,28 @@ describe("frame geometry projection", () => {
         throw new Error(`unexpected child command ${method}`);
       }) as CdpRunner["sendToTarget"],
     };
-    const projection = await new GeometryContext(cdp, 4, {
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "same-process-parent",
-          parentFrameId: "main",
-          ownerBackendNodeId: 10,
-          target: { tabId: 4 },
-        },
-        {
-          frameId: "oopif",
-          parentFrameId: "same-process-parent",
-          ownerBackendNodeId: 20,
-          target: { tabId: 4, sessionId: "oopif-session" },
-        },
-      ],
-    }).targetProjection("oopif");
+    const projection = await resolveFrameProjection(
+      cdp,
+      {
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "same-process-parent",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4 },
+          },
+          {
+            frameId: "oopif",
+            parentFrameId: "same-process-parent",
+            ownerBackendNodeId: 20,
+            target: { tabId: 4, sessionId: "oopif-session" },
+          },
+        ],
+      },
+      "oopif",
+    );
 
     expect(projection?.edges).toEqual([
       {

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

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

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

@@ -123,6 +123,29 @@ 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");

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

@@ -24,10 +24,14 @@ describe("lookupSnapshotRef", () => {
     expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
+      kind: "dom",
+      capabilities: ["interact", "screenshot"],
     });
     expect(lookupSnapshotRef(ctx, "e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
+      kind: "dom",
+      capabilities: ["interact", "screenshot"],
     });
   });
 
@@ -53,6 +57,8 @@ describe("resolveSnapshotRef", () => {
       tabId: 4,
       frameId: "child-frame",
       cdpSessionId: "child-session",
+      kind: "dom",
+      capabilities: ["interact", "screenshot"],
     });
 
     const expected = {
@@ -60,6 +66,8 @@ describe("resolveSnapshotRef", () => {
       refKey: "e3",
       frameId: "child-frame",
       cdpSessionId: "child-session",
+      kind: "dom" as const,
+      capabilities: ["interact", "screenshot"] as const,
     };
     expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
     expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
@@ -105,6 +113,28 @@ describe("resolveSnapshotRef", () => {
     expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual({
       backendNodeId: 1234,
       refKey: "e3",
+      kind: "dom",
+      capabilities: ["interact", "screenshot"],
+    });
+  });
+
+  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__/visual-screenshot-plan.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import {
+  correctedVisualScreenshotScale,
+  planVisualScreenshot,
+  screenshotFitsPixelBudget,
+} from "../visual-screenshot-plan";
+
+const budget = { maxEdge: 2_048, maxPixels: 4_000_000 };
+
+describe("visual screenshot pixel planning", () => {
+  it.each([1, 1.25, 1.5, 2, 3])("accounts for raster scale %s", (rasterScaleEstimate) => {
+    const plan = planVisualScreenshot({
+      cssRect: { width: 2_000, height: 1_000 },
+      rasterScaleEstimate,
+      budget,
+    });
+    const width = 2_000 * rasterScaleEstimate * plan.clipScale;
+    const height = 1_000 * rasterScaleEstimate * plan.clipScale;
+
+    expect(Math.max(width, height)).toBeLessThanOrEqual(budget.maxEdge);
+    expect(width * height).toBeLessThanOrEqual(budget.maxPixels);
+  });
+
+  it("corrects a scale from actual PNG dimensions", () => {
+    const corrected = correctedVisualScreenshotScale({
+      previousClipScale: 1,
+      actualWidth: 4_000,
+      actualHeight: 2_000,
+      budget,
+    });
+
+    expect(corrected).not.toBeNull();
+    expect(corrected as number).toBeLessThan(2_048 / 4_000);
+    expect(screenshotFitsPixelBudget({ width: 2_000, height: 1_000 }, budget)).toBe(true);
+    expect(screenshotFitsPixelBudget({ width: 4_000, height: 2_000 }, budget)).toBe(false);
+  });
+});

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

@@ -1,21 +1,30 @@
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import {
+  type CdpFrame,
+  type CdpFrameGraph,
+  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,
+  projectRectToViewport,
   projectRegionToViewport,
+  type Quad,
   type Region,
   rectPolygon,
   regionBounds,
+  type Size,
   type ViewportRect,
 } from "./geometry";
-import type { CssViewport } from "./geometry/coordinate-types";
-import { cssViewport, GeometryContext } from "./geometry/frame-context";
-import { type CdpRunner, cdpRunnerForTarget, isRpcError } from "./shared";
+import { type CdpRunner, cdpRunnerForTarget, isRpcError, sendToCdpTarget } from "./shared";
 
 export interface NodeAddress {
   target: CdpTarget;
@@ -24,8 +33,6 @@ export interface NodeAddress {
 }
 
 export interface ResolvedNodeGeometry {
-  /** The same top-level measurement used by projection, for screenshot coordinate adaptation. */
-  topViewport: CssViewport;
   topVisibleRegions: Region;
   topBounds: ViewportRect;
   /** Point in the top-level tab viewport, used by root-target input events. */
@@ -38,16 +45,275 @@ 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 sameTargetFrameViewport(cdp: CdpRunner, frame: CdpFrame): Promise<Size | null> {
+  const world = await sendToCdpTarget<{ executionContextId?: number }>(
+    cdp,
+    frame.target,
+    "Page.createIsolatedWorld",
+    {
+      frameId: frame.frameId,
+      worldName: "bsk-frame-geometry",
+      grantUniveralAccess: false,
+    },
+  );
+  if (world.executionContextId === undefined) return null;
+  const result = await sendToCdpTarget<{ result?: { value?: unknown } }>(
+    cdp,
+    frame.target,
+    "Runtime.evaluate",
+    {
+      expression: "({width:window.innerWidth,height:window.innerHeight})",
+      contextId: world.executionContextId,
+      returnByValue: true,
+    },
+  );
+  const value = result.result?.value as { width?: unknown; height?: unknown } | undefined;
+  const width = value?.width;
+  const height = value?.height;
+  return typeof width === "number" &&
+    Number.isFinite(width) &&
+    width > 0 &&
+    typeof height === "number" &&
+    Number.isFinite(height) &&
+    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);
+}
+
+export interface FrameGeometryContext {
+  resolveFrameProjection(frameId: string): Promise<GeometryProjection | null>;
+  projectFrameLocalRect(
+    frameId: string,
+    rect: { x: number; y: number; w: number; h: number },
+  ): Promise<ViewportRect | null>;
+}
+
+export function createFrameGeometryContext(
+  cdp: CdpRunner,
+  graph: CdpFrameGraph,
+): FrameGeometryContext {
+  const byId = frameMap(graph);
+  const targetViewports = new Map<string, Promise<Size | null>>();
+  const frameViewports = new Map<string, Promise<Size | null>>();
+  const ownerQuads = new Map<string, Promise<Quad | null>>();
+  const projections = new Map<string, Promise<GeometryProjection | null>>();
+  const localProjections = new Map<string, Promise<GeometryProjection | null>>();
+
+  const cachedTargetViewport = (target: CdpTarget): Promise<Size | null> => {
+    const key = cdpTargetKey(target);
+    let value = targetViewports.get(key);
+    if (!value) {
+      value = targetViewport(cdp, target);
+      targetViewports.set(key, value);
+    }
+    return value;
+  };
+  const cachedFrameViewport = (frame: CdpFrame): Promise<Size | null> => {
+    let value = frameViewports.get(frame.frameId);
+    if (!value) {
+      const root = targetRootFrame(byId, frame);
+      value =
+        root?.frameId === frame.frameId
+          ? cachedTargetViewport(frame.target)
+          : sameTargetFrameViewport(cdp, frame);
+      frameViewports.set(frame.frameId, value);
+    }
+    return value;
+  };
+  const cachedOwnerQuad = (parent: CdpFrame, backendNodeId: number): Promise<Quad | null> => {
+    const key = `${cdpTargetKey(parent.target)}:${backendNodeId}`;
+    let value = ownerQuads.get(key);
+    if (!value) {
+      value = ownerContentQuad(cdp, parent, backendNodeId);
+      ownerQuads.set(key, value);
+    }
+    return value;
+  };
+  const cachedSameTargetClips = async (
+    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 = byId.get(current.parentFrameId);
+      if (!parent || current.ownerBackendNodeId === undefined) return null;
+      const clip = await cachedOwnerQuad(parent, current.ownerBackendNodeId);
+      if (!clip) return null;
+      clips.push(clip);
+      current = parent;
+    }
+    return clips;
+  };
+
+  const buildTargetProjection = async (frameId: string): Promise<GeometryProjection | null> => {
+    const frame = byId.get(frameId);
+    if (!frame) return null;
+    let root = targetRootFrame(byId, frame);
+    if (!root) return null;
+    const sourceViewport = await cachedTargetViewport(root.target);
+    if (!sourceViewport) return null;
+    const sourceClips = await cachedSameTargetClips(frame, root);
+    if (!sourceClips) return null;
+    const edges: ProjectiveEdge[] = [];
+    while (root.parentFrameId) {
+      const parent = byId.get(root.parentFrameId);
+      if (!parent || root.ownerBackendNodeId === undefined) return null;
+      const destinationQuad = await cachedOwnerQuad(parent, root.ownerBackendNodeId);
+      if (!destinationQuad) return null;
+      const source = await cachedTargetViewport(root.target);
+      if (!source) return null;
+      const parentRoot = targetRootFrame(byId, parent);
+      if (!parentRoot) return null;
+      const destinationClips = await cachedSameTargetClips(parent, parentRoot);
+      if (!destinationClips) return null;
+      edges.push({ sourceViewport: source, destinationQuad, destinationClips });
+      root = parentRoot;
+    }
+    const topViewport = await cachedTargetViewport(root.target);
+    return topViewport ? { sourceClips, edges, topViewport } : null;
+  };
+
+  const resolveFrameProjectionCached = (frameId: string): Promise<GeometryProjection | null> => {
+    let value = projections.get(frameId);
+    if (!value) {
+      value = buildTargetProjection(frameId);
+      projections.set(frameId, value);
+    }
+    return value;
+  };
+
+  const buildLocalProjection = async (frameId: string): Promise<GeometryProjection | null> => {
+    const frame = byId.get(frameId);
+    if (!frame) return null;
+    const root = targetRootFrame(byId, frame);
+    if (!root) return null;
+    const targetProjection = await resolveFrameProjectionCached(root.frameId);
+    if (!targetProjection) return null;
+    if (root.frameId === frame.frameId) return targetProjection;
+    if (!frame.parentFrameId || frame.ownerBackendNodeId === undefined) return null;
+    const parent = byId.get(frame.parentFrameId);
+    if (!parent) return null;
+    const sourceViewport = await cachedFrameViewport(frame);
+    const destinationQuad = await cachedOwnerQuad(parent, frame.ownerBackendNodeId);
+    const destinationClips = await cachedSameTargetClips(frame, root);
+    if (!sourceViewport || !destinationQuad || !destinationClips) return null;
+    return {
+      sourceClips: [],
+      edges: [{ sourceViewport, destinationQuad, destinationClips }, ...targetProjection.edges],
+      topViewport: targetProjection.topViewport,
+    };
+  };
+
+  const localProjection = (frameId: string): Promise<GeometryProjection | null> => {
+    let value = localProjections.get(frameId);
+    if (!value) {
+      value = buildLocalProjection(frameId);
+      localProjections.set(frameId, value);
+    }
+    return value;
+  };
+
+  return {
+    resolveFrameProjection: resolveFrameProjectionCached,
+    async projectFrameLocalRect(frameId, rect) {
+      const projection = await localProjection(frameId);
+      return projection ? projectRectToViewport(rect, projection) : null;
+    },
+  };
+}
+
+export async function resolveFrameProjection(
+  cdp: CdpRunner,
+  graph: CdpFrameGraph,
+  frameId: string,
+): Promise<GeometryProjection | null> {
+  return createFrameGeometryContext(cdp, graph).resolveFrameProjection(frameId);
+}
+
+async function loadFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
+  if (!cdp.getFrameGraph) return null;
+  try {
+    return await cdp.getFrameGraph(tabId);
+  } catch (error) {
+    console.debug("[bsk frame-geometry] frame graph resolution failed", error);
+    return null;
+  }
+}
+
 async function scrollFrameOwners(
   cdp: CdpRunner,
   tabId: number,
-  context: GeometryContext,
+  graph: CdpFrameGraph,
   frameId: string,
 ): Promise<RpcError | null> {
-  const ancestry = await context.ancestry(frameId);
+  const byId = frameMap(graph);
+  const ancestry = frameAncestry(graph, frameId);
   if (!ancestry) return geometryError(`could not resolve frame ancestry for ${frameId}`);
   for (const child of [...ancestry].reverse()) {
-    const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
+    const parent = child.parentFrameId ? byId.get(child.parentFrameId) : undefined;
     if (!parent || child.ownerBackendNodeId === undefined) {
       return geometryError(`could not resolve frame owner for ${child.frameId}`);
     }
@@ -61,20 +327,17 @@ async function scrollFrameOwners(
   return null;
 }
 
-async function scrollElementWithContext(
+async function scrollElementWithFrameGraph(
   cdp: CdpRunner,
   tabId: number,
   target: CdpTarget,
   backendNodeId: number,
   frameId: string | undefined,
-  context: GeometryContext,
+  graph: CdpFrameGraph | null,
 ): Promise<RpcError | null> {
   if (frameId) {
-    const frame = await context.frame(frameId);
-    if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(target)) {
-      return geometryError("node frame does not belong to its target");
-    }
-    const error = await scrollFrameOwners(cdp, tabId, context, frameId);
+    if (!graph) return geometryError(`could not resolve frame graph for ${frameId}`);
+    const error = await scrollFrameOwners(cdp, tabId, graph, frameId);
     if (error) return error;
   } else if (target.sessionId) {
     return geometryError("an OOPIF node address requires frameId");
@@ -89,15 +352,8 @@ export async function scrollElementAndFramesIntoView(
   backendNodeId: number,
   frameId?: string,
 ): Promise<RpcError | null> {
-  if (target.tabId !== tabId) return geometryError("node target belongs to another tab");
-  return scrollElementWithContext(
-    cdp,
-    tabId,
-    target,
-    backendNodeId,
-    frameId,
-    new GeometryContext(cdp, tabId),
-  );
+  const graph = frameId ? await loadFrameGraph(cdp, tabId) : null;
+  return scrollElementWithFrameGraph(cdp, tabId, target, backendNodeId, frameId, graph);
 }
 
 function largestRegion(regions: Region): Polygon | null {
@@ -120,32 +376,23 @@ export async function resolveNodeGeometry(
     if (address.target.sessionId && !address.frameId) {
       return geometryError("an OOPIF node address requires frameId");
     }
-    if (address.target.tabId !== tabId) return geometryError("node target belongs to another tab");
-    const context = new GeometryContext(cdp, tabId);
-    const graph = address.frameId ? await context.graph() : null;
-    if (address.frameId && graph) {
-      const frame = await context.frame(address.frameId);
-      if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(address.target)) {
-        return geometryError("node frame does not belong to its target");
-      }
-    }
+    const graph = address.frameId ? await loadFrameGraph(cdp, tabId) : null;
     if (address.frameId && !graph) {
       return geometryError(`could not resolve frame graph for ${address.frameId}`);
     }
 
     if (options.scrollIntoView) {
-      const scrollError = await scrollElementWithContext(
+      const scrollError = await scrollElementWithFrameGraph(
         cdp,
         tabId,
         address.target,
         address.backendNodeId,
         address.frameId,
-        context,
+        graph,
       );
       if (scrollError) return scrollError;
     }
 
-    // Only topology was read above. Begin live measurements after scrolling.
     const localRegion = await nodeContentRegion(
       cdpRunnerForTarget(cdp, address.target),
       tabId,
@@ -156,7 +403,7 @@ export async function resolveNodeGeometry(
     let topVisibleRegions: Region;
     let targetActionPoint: Point | null = null;
     if (address.frameId && graph) {
-      const projection = await context.targetProjection(address.frameId);
+      const projection = await resolveFrameProjection(cdp, graph, address.frameId);
       if (!projection)
         return geometryError(`could not resolve frame geometry for ${address.frameId}`);
       topVisibleRegions = projectRegionToViewport(localRegion, projection);
@@ -179,7 +426,7 @@ export async function resolveNodeGeometry(
         targetActionPoint = localActionRegion ? polygonCentroid(localActionRegion) : null;
       }
     } else {
-      const viewport = await context.viewport(address.target);
+      const viewport = await targetViewport(cdp, address.target);
       if (!viewport) return geometryError("could not resolve top viewport geometry");
       topVisibleRegions = localRegion
         .map((polygon) =>
@@ -198,13 +445,7 @@ export async function resolveNodeGeometry(
       return { code: "permission_denied", message: "element not visible in its target" };
     }
     targetActionPoint ??= actionPoint;
-    return {
-      topVisibleRegions,
-      topBounds,
-      actionPoint,
-      targetActionPoint,
-      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
-    };
+    return { topVisibleRegions, topBounds, actionPoint, targetActionPoint };
   } catch (error) {
     return geometryError(error instanceof Error ? error.message : String(error));
   }

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

@@ -1,102 +0,0 @@
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
-import type { GeometryProjection, ViewportRect } from "../geometry";
-import { projectRectToViewport } from "../geometry";
-
-export interface CoordinateOwner {
-  target: CdpTarget;
-  frameId?: string;
-}
-
-export interface FrameViewportRect {
-  space: "frame-viewport-css";
-  owner: CoordinateOwner;
-  rect: ViewportRect;
-}
-
-export interface SnapshotProjection {
-  source: CoordinateOwner;
-  geometry: GeometryProjection;
-}
-
-/** A failed owner read is different from a successfully projected, clipped-out rect. */
-export interface UnavailableFrameProjection {
-  status: "unavailable";
-  source: CoordinateOwner;
-  ownerBackendNodeId: number;
-}
-
-export type SnapshotProjectionResult =
-  | { status: "available"; projection: SnapshotProjection }
-  | UnavailableFrameProjection;
-
-/** Descendants inherit the failed boundary without attempting another owner read. */
-export type FrameProjectionIssue =
-  | UnavailableFrameProjection
-  | { status: "blocked"; source: CoordinateOwner; cause: UnavailableFrameProjection };
-
-export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
-
-/** DOMSnapshot bounds are document-relative CSS pixels, independent of raster DPR. */
-export function snapshotViewportRect(
-  bounds: number[],
-  owner: CoordinateOwner,
-  scroll: { x: number; y: number },
-): FrameViewportRect | null {
-  if (bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
-  const [x, y, width, height] = bounds;
-  if (width <= 0 || height <= 0 || !Number.isFinite(scroll.x) || !Number.isFinite(scroll.y)) {
-    return null;
-  }
-  return {
-    space: "frame-viewport-css",
-    owner,
-    rect: { x: x - scroll.x, y: y - scroll.y, width, height },
-  };
-}
-
-export function projectSnapshotRect(
-  input: FrameViewportRect,
-  projection: SnapshotProjection,
-): ViewportRect | null {
-  if (
-    input.owner.frameId !== projection.source.frameId ||
-    cdpTargetKey(input.owner.target) !== cdpTargetKey(projection.source.target)
-  ) {
-    return null;
-  }
-  const { x, y, width: w, height: h } = input.rect;
-  return projectRectToViewport({ x, y, w, h }, projection.geometry);
-}
-
-/** CSS viewport metadata; browser zoom is distinct from raster devicePixelRatio. */
-export interface CssViewport {
-  width: number;
-  height: number;
-  scrollX: number;
-  scrollY: number;
-  cssToDip: number;
-}
-
-/** Page.captureScreenshot takes page-relative DIP, not viewport-relative CSS pixels. */
-export function screenshotPageRect(
-  rect: ViewportRect,
-  viewport: CssViewport,
-): { space: "page-dip"; rect: ViewportRect } | null {
-  const { cssToDip, scrollX, scrollY } = viewport;
-  if (
-    ![rect.x, rect.y, rect.width, rect.height, cssToDip, scrollX, scrollY].every(Number.isFinite) ||
-    cssToDip <= 0 ||
-    rect.width <= 0 ||
-    rect.height <= 0
-  )
-    return null;
-  return {
-    space: "page-dip",
-    rect: {
-      x: (rect.x + scrollX) * cssToDip,
-      y: (rect.y + scrollY) * cssToDip,
-      width: rect.width * cssToDip,
-      height: rect.height * cssToDip,
-    },
-  };
-}

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

@@ -1,308 +0,0 @@
-import {
-  type CdpFrame,
-  type CdpFrameGraph,
-  type CdpTarget,
-  cdpTargetKey,
-} from "@/browser-driver/frame-graph";
-import {
-  type GeometryProjection,
-  type Polygon,
-  type ProjectiveEdge,
-  parseCdpQuad,
-  type Quad,
-  type Size,
-} from "../geometry";
-import { type CdpRunner, sendToCdpTarget } from "../shared";
-import type { CoordinateOwner, CssViewport, SnapshotProjectionResult } from "./coordinate-types";
-
-export interface LayoutMetrics {
-  cssVisualViewport?: { zoom?: number };
-  visualViewport?: { zoom?: number };
-  cssLayoutViewport?: {
-    clientWidth?: number;
-    clientHeight?: number;
-    pageX?: number;
-    pageY?: number;
-  };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
-}
-
-/** The legacy field is a compatibility fallback, never a source of raster DPR. */
-export function cssViewport(metrics: LayoutMetrics): CssViewport {
-  const value = metrics.cssLayoutViewport ?? metrics.layoutViewport;
-  return {
-    width: value?.clientWidth ?? 0,
-    height: value?.clientHeight ?? 0,
-    scrollX: value?.pageX ?? 0,
-    scrollY: value?.pageY ?? 0,
-    cssToDip: metrics.cssVisualViewport?.zoom ?? metrics.visualViewport?.zoom ?? 1,
-  };
-}
-
-/** One read-only measurement phase. Discard after scrolling or any later operation. */
-export class GeometryContext {
-  private readonly metrics = new Map<string, Promise<LayoutMetrics>>();
-  private readonly owners = new Map<string, Promise<Quad | null>>();
-  private readonly projections = new Map<string, Promise<GeometryProjection | null>>();
-  private readonly snapshotOwners = new Map<string, Promise<{ quad: Quad; size: Size } | null>>();
-  private 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 };
-  }
-
-  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 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/interaction.ts

@@ -169,7 +169,7 @@ export async function resolveBackendNode(
     };
   }
   if (hasRef) {
-    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId);
+    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId, "interact");
     if (isRpcError(resolved)) return resolved;
     return {
       backendNodeId: resolved.backendNodeId,

apps/extension/src/tools/observation.ts

@@ -1,4 +1,3 @@
-import type { CapturedSceneInput } from "./vom/facts";
 // Observation handlers — `tool.snapshot`, `tool.get_html`, `tool.screenshot`,
 // and semantic `tool.observe` (design §7). Each handler resolves the target
 // tab (defaulting to the Agent Window's active tab when omitted) and
@@ -9,6 +8,7 @@ import {
   applyVomInteractionRecovery,
   type CondSurface,
   isVomReferenceNode,
+  type Rect,
   renderVom,
   type VomNode,
   type VomOptions,
@@ -35,7 +35,6 @@ import type {
 import { attachDialogs, markDialogCursor } from "./dialogs";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry } from "./frame-geometry";
-import { screenshotPageRect } from "./geometry/coordinate-types";
 import {
   type ChromeTabsApi,
   enforceToolTargetScope,
@@ -49,15 +48,33 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { type CapturedNode, type CapturedSurfaceProbe, probeHoverSurfaces } from "./vom/capture";
-import { captureObservationFacts, semanticCapture } from "./vom/capture-coordinator";
-import type { FrameDocument as CapturedFrameDocument } from "./vom/frame-document";
+import { topLevelScreenshotRasterScale } from "./viewport-metrics";
+import {
+  correctedVisualScreenshotScale,
+  planVisualScreenshot,
+  type ScreenshotPixelBudget,
+  screenshotFitsPixelBudget,
+} from "./visual-screenshot-plan";
+import {
+  type CapturedNode,
+  type CapturedSurfaceProbe,
+  type CapturedViewModel,
+  captureViewModel,
+  collectOverlayExcludedBackendIds,
+  probeHoverSurfaces,
+} from "./vom/capture";
+import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
 import { withOverlayBypass } from "./vom/hover-perception";
 import { probeTooltipNames } from "./vom/name-enrichment";
 import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
+import {
+  clusterRenderedSurfaces,
+  discoverRenderedSurfaces,
+  projectRenderedSurfaces,
+} from "./vom/rendered-surfaces";
 import {
   buildSemanticGraph,
   buildSemanticVomScene,
@@ -89,6 +106,13 @@ export const normaliseRef = sharedNormaliseRef;
 // screenshot — `tool.screenshot`
 // ---------------------------------------------------------------------------
 
+const VISUAL_SURFACE_SCREENSHOT_MAX_EDGE = 2_048;
+const VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS = 4_000_000;
+const VISUAL_SURFACE_SCREENSHOT_BUDGET: ScreenshotPixelBudget = {
+  maxEdge: VISUAL_SURFACE_SCREENSHOT_MAX_EDGE,
+  maxPixels: VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS,
+};
+
 /**
  * Strip the `data:image/...;base64,` prefix from a Chrome
  * `captureVisibleTab` dataURL and return the raw base64 payload.
@@ -103,8 +127,8 @@ export function stripDataUrlPrefix(dataUrl: string): string {
 
 /**
  * Parse a PNG's IHDR chunk and return `(width, height)`. Returns
- * `null` on any malformed input so callers fall back to `0/0` instead
- * of throwing.
+ * `null` on malformed input so callers can reject dimensions that are
+ * not authoritative instead of guessing from a CSS-space rectangle.
  *
  * 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
@@ -116,9 +140,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;
-    if (bin.charCodeAt(0) !== 0x89 || bin.charCodeAt(1) !== 0x50 || bin.charCodeAt(2) !== 0x4e) {
-      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;
     const u32 = (off: number) =>
       (bin.charCodeAt(off) << 24) |
       (bin.charCodeAt(off + 1) << 16) |
@@ -181,6 +205,8 @@ async function captureElementScreenshot(
   target: CdpTarget,
   backendNodeId: number,
   frameId?: string,
+  visualSurface = false,
+  observedVisibleRect?: Rect,
   signal?: AbortSignal,
 ): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
   if (signal?.aborted) return cancelled("screenshot");
@@ -188,32 +214,74 @@ async function captureElementScreenshot(
     cdp,
     tabId,
     { target, backendNodeId, ...(frameId ? { frameId } : {}) },
-    { scrollIntoView: true },
+    { scrollIntoView: !visualSurface },
   );
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
-  const rect = geometry.topBounds;
-  const clip = screenshotPageRect(rect, geometry.topViewport);
-  if (!clip) return { code: "cdp_failed", message: "invalid screenshot coordinate space" };
+  const liveRect = geometry.topBounds;
+  const rect =
+    visualSurface && observedVisibleRect
+      ? (() => {
+          const x = Math.max(liveRect.x, observedVisibleRect.x);
+          const y = Math.max(liveRect.y, observedVisibleRect.y);
+          const right = Math.min(
+            liveRect.x + liveRect.width,
+            observedVisibleRect.x + observedVisibleRect.w,
+          );
+          const bottom = Math.min(
+            liveRect.y + liveRect.height,
+            observedVisibleRect.y + observedVisibleRect.h,
+          );
+          return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : null;
+        })()
+      : liveRect;
+  if (!rect) return { code: "permission_denied", message: "surface is no longer visible" };
+  const rasterScaleEstimate = visualSurface ? await topLevelScreenshotRasterScale(cdp, tabId) : 1;
+  let scale = visualSurface
+    ? planVisualScreenshot({
+        cssRect: rect,
+        rasterScaleEstimate,
+        budget: VISUAL_SURFACE_SCREENSHOT_BUDGET,
+      }).clipScale
+    : 1;
 
   try {
-    const shot = await cdp.send<{ data?: string }>(tabId, "Page.captureScreenshot", {
-      format: "png",
-      clip: {
-        ...clip.rect,
-        scale: 1,
-      },
-    });
-    if (signal?.aborted) return cancelled("screenshot");
-    const image_base64 = shot.data ?? "";
-    if (!image_base64) {
-      return { code: "cdp_failed", message: "Page.captureScreenshot returned no data" };
+    for (let attempt = 0; attempt < (visualSurface ? 2 : 1); attempt += 1) {
+      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,
+        },
+      });
+      if (signal?.aborted) return cancelled("screenshot");
+      const image_base64 = shot.data ?? "";
+      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" };
+      }
+      if (!visualSurface || screenshotFitsPixelBudget(dims, VISUAL_SURFACE_SCREENSHOT_BUDGET)) {
+        return { image_base64, width: dims.width, height: dims.height };
+      }
+      const corrected = correctedVisualScreenshotScale({
+        previousClipScale: scale,
+        actualWidth: dims.width,
+        actualHeight: dims.height,
+        budget: VISUAL_SURFACE_SCREENSHOT_BUDGET,
+      });
+      if (attempt === 1 || corrected === null) break;
+      scale = corrected;
     }
-    const dims = parsePngDimensions(image_base64) ?? {
-      width: Math.round(rect.width),
-      height: Math.round(rect.height),
+    return {
+      code: "cdp_failed",
+      message: "Page.captureScreenshot exceeded the visual surface pixel budget",
     };
-    return { image_base64, width: dims.width, height: dims.height };
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -308,8 +376,14 @@ export async function handleScreenshot(
     if (!deps.cdp) {
       return { code: "cdp_failed", message: "screenshot ref capture requires CDP" };
     }
-    const node = resolveSnapshotRef(ctx, ref, target.tabId);
+    const node = resolveSnapshotRef(ctx, ref, target.tabId, "screenshot");
     if (isRpcError(node)) return node;
+    if (node.kind === "surface" && !node.visibleRect) {
+      return {
+        code: "permission_denied",
+        message: `surface ref ${ref} has no observation-time visible bounds`,
+      };
+    }
     if (signal?.aborted) return cancelled("screenshot");
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
     await deps.cdp.ensureAttachedToUrl?.(target.tabId, target.url);
@@ -328,6 +402,8 @@ export async function handleScreenshot(
           nodeTarget,
           node.backendNodeId,
           node.frameId,
+          node.kind === "surface",
+          node.visibleRect,
           signal,
         ),
       deps.sendToTab,
@@ -359,7 +435,10 @@ export async function handleScreenshot(
   if (isRpcError(captured)) return captured;
   if (signal?.aborted) return cancelled("screenshot");
   const image_base64 = captured;
-  const dims = parsePngDimensions(image_base64) ?? { width: 0, height: 0 };
+  const dims = parsePngDimensions(image_base64);
+  if (!dims) {
+    return { code: "cdp_failed", message: "screenshot capture returned invalid PNG data" };
+  }
   return withShotDialogs({
     image_base64,
     width: dims.width,
@@ -525,7 +604,7 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
 
 function buildConditionalSurfaces(
   nodes: VomNode[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   probes: CapturedSurfaceProbe[],
 ): CondSurface[] {
   if (probes.length === 0) return [];
@@ -655,9 +734,161 @@ export interface BuildVomSceneOptions {
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
 
+function legacyFrameDocuments(
+  axNodes: CdpAxNode[],
+  captured: CapturedViewModel,
+  pageUrl?: string,
+  rootTarget: VomFrameDocument["target"] = { tabId: 0 },
+): VomFrameDocument[] {
+  const rootFrameId = captured.rootFrameId ?? "root";
+  const documents: VomFrameDocument[] = [
+    {
+      frameId: rootFrameId,
+      contextScopeId: rootFrameId,
+      target: rootTarget,
+      ...(pageUrl ? { url: pageUrl } : {}),
+      axNodes: [],
+      domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
+    },
+  ];
+  const pending = [...captured.iframeNodes.entries()];
+  let progress = true;
+  let nextSyntheticFrame = 1;
+  while (pending.length > 0 && progress) {
+    progress = false;
+    for (let index = pending.length - 1; index >= 0; index -= 1) {
+      const [ownerBackendNodeId, domNodes] = pending[index];
+      const parent = documents.find((document) =>
+        document.domNodes.some((node) => node.backendNodeId === ownerBackendNodeId),
+      );
+      if (!parent) continue;
+      const frameId =
+        domNodes.find((node) => node.frameId)?.frameId ?? `legacy-frame-${nextSyntheticFrame++}`;
+      documents.push({
+        frameId,
+        parentFrameId: parent.frameId,
+        ownerBackendNodeId,
+        contextScopeId: frameId,
+        target: parent.target,
+        axNodes: [],
+        domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
+      });
+      pending.splice(index, 1);
+      progress = true;
+    }
+  }
+
+  const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
+  const backendFrame = new Map<number, string>();
+  const childFrameByOwner = new Map<number, string>();
+  for (const document of documents) {
+    if (document.ownerBackendNodeId !== undefined) {
+      childFrameByOwner.set(document.ownerBackendNodeId, document.frameId);
+    }
+    for (const node of document.domNodes) backendFrame.set(node.backendNodeId, document.frameId);
+  }
+  const axById = new Map(axNodes.map((node) => [node.nodeId, node]));
+  const ownership = new Map<string, string>();
+  const resolving = new Set<string>();
+  const frameForAx = (node: CdpAxNode): string => {
+    const cached = ownership.get(node.nodeId);
+    if (cached) return cached;
+    let frameId: string | undefined;
+    if (node.frameId && documentByFrameId.has(node.frameId)) frameId = node.frameId;
+    if (!frameId && typeof node.backendDOMNodeId === "number") {
+      frameId = backendFrame.get(node.backendDOMNodeId);
+    }
+    if (!frameId && node.parentId && !resolving.has(node.nodeId)) {
+      const parent = axById.get(node.parentId);
+      if (parent) {
+        frameId =
+          typeof parent.backendDOMNodeId === "number"
+            ? childFrameByOwner.get(parent.backendDOMNodeId)
+            : undefined;
+        if (!frameId) {
+          resolving.add(node.nodeId);
+          frameId = frameForAx(parent);
+          resolving.delete(node.nodeId);
+        }
+      }
+    }
+    frameId ??= rootFrameId;
+    ownership.set(node.nodeId, frameId);
+    return frameId;
+  };
+  for (const node of axNodes) frameForAx(node);
+  for (const node of axNodes) {
+    const frameId = ownership.get(node.nodeId) ?? rootFrameId;
+    const document = documentByFrameId.get(frameId) ?? documents[0];
+    document.axNodes.push({
+      ...node,
+      frameId,
+      ...(node.parentId && ownership.get(node.parentId) === frameId
+        ? { parentId: node.parentId }
+        : { parentId: undefined }),
+      ...(node.childIds
+        ? { childIds: node.childIds.filter((childId) => ownership.get(childId) === frameId) }
+        : {}),
+    });
+  }
+  return documents;
+}
+
+function withLegacyBackendIds(scene: VomScene): VomScene {
+  const used = new Set<number>();
+  const idMap = new Map<number, number>();
+  let nextVirtualId = -1;
+  for (const node of scene.nodes) {
+    const preferred = node.backendNodeId;
+    const id = preferred !== undefined && !used.has(preferred) ? preferred : nextVirtualId--;
+    used.add(id);
+    idMap.set(node.id, id);
+  }
+  return {
+    ...scene,
+    nodes: scene.nodes.map((node) => ({
+      ...node,
+      id: idMap.get(node.id) as number,
+      parentId: node.parentId === null ? null : (idMap.get(node.parentId) ?? null),
+      ...(node.domParentId !== undefined
+        ? { domParentId: node.domParentId === null ? null : (idMap.get(node.domParentId) ?? null) }
+        : {}),
+      ...(node.domAncestorIds
+        ? { domAncestorIds: node.domAncestorIds.flatMap((id) => idMap.get(id) ?? []) }
+        : {}),
+    })),
+    ...(scene.surfaces
+      ? {
+          surfaces: scene.surfaces.map((surface) => ({
+            ...surface,
+            triggerId: idMap.get(surface.triggerId) ?? surface.triggerId,
+          })),
+        }
+      : {}),
+    ...(scene.activeScopeBlocks
+      ? {
+          activeScopeBlocks: scene.activeScopeBlocks.map((block) => ({
+            ...block,
+            triggerId: idMap.get(block.triggerId) ?? block.triggerId,
+          })),
+        }
+      : {}),
+  };
+}
+
+export function buildVomScene(
+  axNodes: CdpAxNode[],
+  captured: CapturedViewModel,
+  options: BuildVomSceneOptions = {},
+): VomScene {
+  return withLegacyBackendIds(
+    buildFrameVomScene(legacyFrameDocuments(axNodes, captured, options.pageUrl), captured, options),
+  );
+}
+
 export function buildFrameVomScene(
   documents: VomFrameDocument[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   options: BuildVomSceneOptions = {},
 ): VomScene {
   const scene = buildSemanticVomScene({
@@ -673,7 +904,7 @@ export function buildFrameVomScene(
 function attachCapturedSceneAnnotations(
   scene: VomScene,
   documents: VomFrameDocument[],
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   surfaceProbes: CapturedSurfaceProbe[],
 ): VomScene {
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
@@ -823,6 +1054,51 @@ export async function handleGetHtml(
   }
 }
 
+function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedViewModel {
+  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,
+  signal?: AbortSignal,
+): Promise<CapturedViewModel> {
+  throwIfAborted(signal, "observation");
+  let viewport = { width: 0, height: 0 };
+  try {
+    const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
+    throwIfAborted(signal, "observation");
+    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+    viewport = {
+      width: source.clientWidth ?? 0,
+      height: source.clientHeight ?? 0,
+    };
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+  }
+  const excludedBackendNodeIds = await collectOverlayExcludedBackendIds(cdp, tabId, signal);
+  throwIfAborted(signal, "observation");
+  return { ...emptyCapturedViewModel(viewport), excludedBackendNodeIds };
+}
+
+async function captureForVom(
+  cdp: CdpRunner,
+  tabId: number,
+  options: CaptureVomObservationOptions,
+): Promise<CapturedViewModel> {
+  try {
+    return await captureViewModel(cdp, tabId, { signal: options.signal });
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    return fallbackCapturedViewModel(cdp, tabId, options.signal);
+  }
+}
+
 export interface HoverProbeOutcome {
   /** Whether any active hover was dispatched during this observation. */
   performed: boolean;
@@ -855,7 +1131,7 @@ const NO_HOVER_PROBES: HoverProbeOutcome = {
 async function runHoverProbes(
   cdp: CdpRunner,
   tabId: number,
-  captured: CapturedSceneInput,
+  captured: CapturedViewModel,
   documents: VomFrameDocument[],
   staticSemantics: ReturnType<typeof resolveSemanticGraph>,
   options: CaptureVomObservationOptions,
@@ -881,6 +1157,7 @@ async function runHoverProbes(
 
 export interface CaptureVomObservationOptions extends VomOptions {
   conditionalSurfaceProbe?: boolean;
+  renderedSurfaceDiscovery?: boolean;
   hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
   signal?: AbortSignal;
 }
@@ -894,9 +1171,14 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   await cdp.ensureAttachedToUrl?.(tabId, url);
   throwIfAborted(options.signal, "observation");
-  const facts = await captureObservationFacts<CdpAxNode>(cdp, tabId, options.signal, url);
-  const { captured, documents: normalizedDocuments } = semanticCapture(facts);
+  const captured = await captureForVom(cdp, tabId, options);
   throwIfAborted(options.signal, "observation");
+  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
+  throwIfAborted(options.signal, "observation");
+  const normalizedDocuments =
+    documents.length === 1 && captured.iframeNodes.size > 0
+      ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
+      : documents;
   const semanticGraph = buildSemanticGraph({
     documents: normalizedDocuments,
     viewport: captured.viewport,
@@ -924,21 +1206,25 @@ export async function captureVomObservation(
     captured,
     hoverProbes.surfaceProbes,
   );
-  // Reserve space using the renderer's character-based token estimate. Like VOM
-  // headers, this integrity notice remains visible even under a tiny token budget.
-  const geometryNotice = facts.issues.some((issue) => issue.stage === "geometry")
-    ? "@warning iframe geometry incomplete: some frame content has no top-level coordinates.\n"
-    : "";
-  const rendered = renderVom(decoratedScene, {
+  const observedScene = options.renderedSurfaceDiscovery
+    ? projectRenderedSurfaces(
+        decoratedScene,
+        normalizedDocuments,
+        clusterRenderedSurfaces(
+          discoverRenderedSurfaces(
+            normalizedDocuments,
+            captured.viewport,
+            captured.excludedBackendNodeIds,
+          ),
+        ),
+      )
+    : decoratedScene;
+  const rendered = renderVom(observedScene, {
     maxDepth: options.maxDepth,
-    maxTokens:
-      !geometryNotice || options.maxTokens === undefined
-        ? options.maxTokens
-        : Math.max(0, options.maxTokens - Math.ceil(geometryNotice.length / 4)),
+    maxTokens: options.maxTokens,
     redactValues: options.redactValues,
     activeRegionPolicy: options.activeRegionPolicy,
   });
-  if (geometryNotice) rendered.text += `\n${geometryNotice.trimEnd()}`;
   throwIfAborted(options.signal, "observation");
   return projectRecordSafeObservation({
     rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",
@@ -988,6 +1274,7 @@ async function handleVomObservation(
       maxTokens: params.max_tokens,
       activeRegionPolicy: true,
       conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
+      renderedSurfaceDiscovery: toolName === "observe",
       hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
       signal,
     });
@@ -1005,6 +1292,9 @@ 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/snapshot-ref.ts

@@ -2,8 +2,9 @@
 // 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 } from "@/session-manager/ref-store";
+import { normaliseRef, type RefCapability, type RefTargetKind } from "@/session-manager/ref-store";
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";
 
@@ -12,6 +13,9 @@ export interface SnapshotRefLookup {
   refKey: string;
   frameId?: string;
   cdpSessionId?: string;
+  visibleRect?: Rect;
+  kind: RefTargetKind;
+  capabilities: RefCapability[];
 }
 
 function refEntryForTab(ctx: SessionContext, refKey: string, tabId: number) {
@@ -37,6 +41,9 @@ 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,
   };
 }
 
@@ -49,6 +56,7 @@ export function resolveSnapshotRef(
   ctx: SessionContext,
   ref: string,
   tabId: number,
+  requiredCapability?: RefCapability,
 ): SnapshotRefLookup | RpcError {
   const looked = lookupSnapshotRef(ctx, ref, tabId);
   if (looked === null) {
@@ -58,5 +66,13 @@ 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/viewport-metrics.ts

@@ -0,0 +1,18 @@
+import type { CdpRunner } from "./shared";
+
+/** Estimate the raster/CSS ratio used by top-level Page.captureScreenshot. */
+export async function topLevelScreenshotRasterScale(
+  cdp: CdpRunner,
+  tabId: number,
+): Promise<number> {
+  try {
+    const reply = await cdp.send<{ result?: { value?: unknown } }>(tabId, "Runtime.evaluate", {
+      expression: "window.devicePixelRatio",
+      returnByValue: true,
+    });
+    const value = reply.result?.value;
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 1;
+  } catch {
+    return 1;
+  }
+}

apps/extension/src/tools/visual-screenshot-plan.ts

@@ -0,0 +1,52 @@
+export interface ScreenshotPixelBudget {
+  maxEdge: number;
+  maxPixels: number;
+}
+
+export interface VisualScreenshotPlan {
+  clipScale: number;
+}
+
+export function planVisualScreenshot(input: {
+  cssRect: { width: number; height: number };
+  rasterScaleEstimate: number;
+  budget: ScreenshotPixelBudget;
+}): VisualScreenshotPlan {
+  const rasterScale =
+    Number.isFinite(input.rasterScaleEstimate) && input.rasterScaleEstimate > 0
+      ? input.rasterScaleEstimate
+      : 1;
+  const { width, height } = input.cssRect;
+  const scale = Math.min(
+    1,
+    input.budget.maxEdge / (width * rasterScale),
+    input.budget.maxEdge / (height * rasterScale),
+    Math.sqrt(input.budget.maxPixels / (width * height * rasterScale * rasterScale)),
+  );
+  return { clipScale: Math.max(Number.EPSILON, scale) };
+}
+
+export function correctedVisualScreenshotScale(input: {
+  previousClipScale: number;
+  actualWidth: number;
+  actualHeight: number;
+  budget: ScreenshotPixelBudget;
+}): number | null {
+  const correction = Math.min(
+    input.budget.maxEdge / input.actualWidth,
+    input.budget.maxEdge / input.actualHeight,
+    Math.sqrt(input.budget.maxPixels / (input.actualWidth * input.actualHeight)),
+  );
+  if (!Number.isFinite(correction) || correction >= 1 || correction <= 0) return null;
+  return Math.max(Number.EPSILON, input.previousClipScale * correction * 0.999);
+}
+
+export function screenshotFitsPixelBudget(
+  dimensions: { width: number; height: number },
+  budget: ScreenshotPixelBudget,
+): boolean {
+  return (
+    Math.max(dimensions.width, dimensions.height) <= budget.maxEdge &&
+    dimensions.width * dimensions.height <= budget.maxPixels
+  );
+}

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

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

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

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
-import { collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
-import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
+import { 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.
@@ -27,7 +27,6 @@ function fakeSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2],
           nodeType: [1, 1, 1, 1],
@@ -75,7 +74,6 @@ function hoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1],
           nodeType: [1, 1, 1],
@@ -120,7 +118,6 @@ function twoHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 1],
           nodeType: [1, 1, 1, 1],
@@ -174,7 +171,6 @@ function nestedHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
-        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2, 3],
           nodeType: [1, 1, 1, 1, 1],
@@ -248,11 +244,13 @@ function makeCdp(snapshot: unknown) {
   };
 }
 
-describe("snapshot capture and hover", () => {
+describe("captureViewModel", () => {
   it("parses nodes, attrs, rects, paint order and styles", async () => {
-    const { nodes, viewport } = semanticCapture(
-      await captureObservationFacts(makeCdp(fakeSnapshotReply()), 4),
-    ).captured;
+    const { nodes, viewport, iframeNodes } = await captureViewModel(
+      makeCdp(fakeSnapshotReply()),
+      4,
+    );
+    expect(iframeNodes.size).toBe(0);
     expect(viewport).toEqual({ width: 1000, height: 800 });
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div).toMatchObject({ tag: "div", position: "fixed", parentBackendNodeId: 11 });
@@ -264,11 +262,35 @@ describe("snapshot capture and hover", () => {
 
   it("never hovers the page while capturing", async () => {
     const cdp = makeCdp(fakeSnapshotReply());
-    semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    await captureViewModel(cdp, 4);
 
     expect(cdp.send).not.toHaveBeenCalledWith(4, "Input.dispatchMouseEvent", expect.anything());
   });
 
+  it("batch-enriches form controls without per-node object resolution", async () => {
+    const cdp = makeCdp(fakeSnapshotReply());
+    const result = await captureViewModel(cdp, 4);
+    const input = result.nodes.find((node) => node.backendNodeId === 13);
+
+    expect(input).toMatchObject({
+      formState: "filled",
+      formPlaceholder: "secret",
+      attrs: { type: "password" },
+    });
+    expect(input?.formValue).toBeUndefined();
+    expect(input?.formDefaultValue).toBeUndefined();
+    expect(cdp.send).toHaveBeenCalledWith(
+      4,
+      "Runtime.evaluate",
+      expect.objectContaining({
+        serializationOptions: expect.objectContaining({ serialization: "deep" }),
+      }),
+    );
+    expect(cdp.send).toHaveBeenCalledWith(4, "Runtime.releaseObjectGroup", expect.anything());
+    expect(cdp.send).not.toHaveBeenCalledWith(4, "DOM.resolveNode", expect.anything());
+    expect(cdp.send).not.toHaveBeenCalledWith(4, "Runtime.callFunctionOn", expect.anything());
+  });
+
   it("runs hover surface probes when explicitly enabled", async () => {
     let hoverStateCalls = 0;
     const cdp = {
@@ -308,7 +330,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -368,7 +390,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -413,7 +435,7 @@ describe("snapshot capture and hover", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const captured = await captureViewModel(cdp, 4);
     await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(hoverMoves).toBe(1);
@@ -445,7 +467,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -476,7 +497,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
     const ids = nodes.map((n) => n.backendNodeId);
     // Real page nodes survive.
     expect(ids).toContain(12);
@@ -507,7 +528,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -538,9 +558,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
     expect(excludedBackendNodeIds).toEqual(new Set([13, 14, 15]));
   });
 
@@ -561,7 +579,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i(OVERLAY_HOST_NAME)],
@@ -584,9 +601,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -609,7 +624,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -632,9 +646,7 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = semanticCapture(
-      await captureObservationFacts(makeCdp(snapshot), 4),
-    ).captured;
+    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -657,7 +669,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -680,7 +691,7 @@ describe("snapshot capture and hover", () => {
         },
       ],
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
     expect(nodes.find((n) => n.backendNodeId === 12)?.cursor).toBe("pointer");
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
@@ -692,7 +703,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 1, 1],
             nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
@@ -719,13 +729,51 @@ describe("snapshot capture and hover", () => {
       ],
     };
 
-    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
 
     expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
     expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
     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) => {
@@ -739,23 +787,24 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const { nodes } = await captureViewModel(cdp, 4);
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div?.localRect?.y).toBe(-200);
     expect(div?.rect).toMatchObject({ y: 0, h: 600 });
   });
 
-  it("keeps CSS snapshot bounds independent of legacy metrics ratio", async () => {
-    const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
+  it.each([
+    1, 2,
+  ])("keeps CSS-space bounds stable at devicePixelRatio=%i", async (deviceScaleFactor) => {
+    const S = ["html", "body", "canvas", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
-            nodeName: [i("html"), i("body"), i("div")],
+            nodeName: [i("html"), i("body"), i("canvas")],
             backendNodeId: [10, 11, 12],
             attributes: [[], [], []],
           },
@@ -766,8 +815,8 @@ describe("snapshot capture and hover", () => {
               [i("fixed"), i("auto")],
             ],
             bounds: [
-              [0, 0, 2000, 3200],
-              [0, 0, 2000, 1600],
+              [0, 0, 1000 * deviceScaleFactor, 1600 * deviceScaleFactor],
+              [0, 0, 1000 * deviceScaleFactor, 800 * deviceScaleFactor],
             ],
             paintOrders: [0, 50],
           },
@@ -781,25 +830,24 @@ describe("snapshot capture and hover", () => {
         if (method === "Page.getLayoutMetrics") {
           return {
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
-            layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
+            layoutViewport: {
+              clientWidth: 1000 * deviceScaleFactor,
+              clientHeight: 800 * deviceScaleFactor,
+            },
           };
         }
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect).toEqual({
+    const { nodes } = await captureViewModel(cdp, 4);
+    const canvas = nodes.find((node) => node.backendNodeId === 12);
+    expect(canvas?.tag).toBe("canvas");
+    expect(canvas?.rect).toEqual({
       x: 0,
       y: 0,
       w: 1000,
       h: 800,
     });
-    expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
-      x: 0,
-      y: 0,
-      w: 2000,
-      h: 1600,
-    });
   });
 
   it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -823,7 +871,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -862,7 +909,7 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const { nodes } = await captureViewModel(cdp, 4);
     const btn = nodes.find((n) => n.backendNodeId === 12);
     expect(btn?.textContent).toBe("登录");
     const link = nodes.find((n) => n.backendNodeId === 14);
@@ -872,7 +919,7 @@ describe("snapshot capture and hover", () => {
     expect(body?.textContent).toBeUndefined();
   });
 
-  it("retains explicit iframe document ownership and projected nodes", async () => {
+  it("parses iframe sub-documents and returns iframeNodes keyed by iframe backendNodeId", async () => {
     const S = [
       "html",
       "body",
@@ -949,33 +996,36 @@ describe("snapshot capture and hover", () => {
             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>,
     };
-    const facts = await captureObservationFacts(cdp, 4);
-    const root = facts.documents.find((doc) => doc.frame.frameId === "main-frame")!;
-    const child = facts.documents.find((doc) => doc.frame.frameId === "child-frame")!;
-    expect(facts.documents).toHaveLength(2);
-    expect(root.domNodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
-    const subNodes = child.domNodes;
+    const {
+      nodes,
+      iframeNodes,
+      frameNodes,
+      frameOwnerBackendNodeIds,
+      frameParentIds,
+      rootFrameId,
+    } = await captureViewModel(cdp, 4);
+    // Main frame has 4 nodes; iframe is included
+    expect(nodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
+    // iframeNodes keyed by the <iframe> element's backendNodeId=13
+    expect(iframeNodes.size).toBe(1);
+    expect(iframeNodes.has(13)).toBe(true);
+    const subNodes = iframeNodes.get(13)!;
     const input = subNodes.find((n) => n.backendNodeId === 101);
     expect(input?.tag).toBe("input");
     expect(input?.attrs.type).toBe("text");
     expect(input?.ownerFrameBackendNodeId).toBe(13);
     expect(input?.localRect).toEqual({ x: 0, y: 0, w: 200, h: 40 });
-    expect(input?.rect).toEqual({ x: 100, y: 300, w: 200, h: 40 });
-    expect(facts.rootFrameId).toBe("main-frame");
-    expect(child.frame.ownerBackendNodeId).toBe(13);
-    expect(child.frame.parentFrameId).toBe("main-frame");
+    expect(input?.rect).toBeNull();
+    expect(rootFrameId).toBe("main-frame");
+    expect(frameNodes?.get("child-frame")).toBe(subNodes);
+    expect(frameOwnerBackendNodeIds?.get("child-frame")).toBe(13);
+    expect(frameParentIds?.get("child-frame")).toBe("main-frame");
   });
 
-  it("projects iframe documents independently of owner snapshot geometry", async () => {
+  it("captures iframe documents without requiring owner-frame geometry", async () => {
     const S = [
       "html",
       "body",
@@ -993,7 +1043,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1011,7 +1060,6 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "child",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1038,23 +1086,15 @@ describe("snapshot capture and hover", () => {
             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>,
     };
 
-    const { documents } = await captureObservationFacts(cdp, 4);
-    const input = documents
-      .find((doc) => doc.frame.frameId === "child")
-      ?.domNodes?.find((n) => n.backendNodeId === 101);
+    const { iframeNodes } = await captureViewModel(cdp, 4);
+    const input = iframeNodes.get(13)?.find((n) => n.backendNodeId === 101);
 
     expect(input?.localRect).toEqual({ x: 20, y: 20, w: 120, h: 60 });
-    expect(input?.rect).toEqual({ x: 120, y: 320, w: 120, h: 60 });
+    expect(input?.rect).toBeNull();
   });
 
   it("recursively normalizes nested iframe sub-documents", async () => {
@@ -1075,7 +1115,6 @@ describe("snapshot capture and hover", () => {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1097,7 +1136,6 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "child",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1119,7 +1157,6 @@ describe("snapshot capture and hover", () => {
           },
         },
         {
-          frameId: "nested",
           nodes: {
             parentIndex: [-1, 0],
             nodeName: [i("body"), i("input")],
@@ -1136,68 +1173,121 @@ describe("snapshot capture and hover", () => {
       ],
     };
     const cdp = {
-      send: vi.fn(
-        async (
-          _t: number,
-          method: string,
-          params?: { backendNodeId?: number; objectId?: string },
-        ) => {
+      send: vi.fn(async (_t: number, method: string) => {
+        if (method === "DOMSnapshot.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+        if (method === "Page.getLayoutMetrics") {
+          return {
+            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+          };
+        }
+        throw new Error(method);
+      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+    };
+
+    const { iframeNodes } = await captureViewModel(cdp, 4);
+    const nestedIframe = iframeNodes.get(13)?.find((n) => n.backendNodeId === 23);
+    const input = iframeNodes.get(23)?.find((n) => n.backendNodeId === 31);
+
+    expect(nestedIframe?.localRect).toEqual({ x: 5, y: 6, w: 100, h: 80 });
+    expect(nestedIframe?.rect).toBeNull();
+    expect(input?.ownerFrameBackendNodeId).toBe(23);
+    expect(input?.localRect).toEqual({ x: 1, y: 2, w: 40, h: 20 });
+    expect(input?.rect).toBeNull();
+  });
+
+  it("keeps same-origin iframe canvas frame-local until frame geometry is resolved", 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 },
             };
           }
-          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>,
+        }) 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 { documents } = await captureObservationFacts(cdp, 4);
-    const nestedIframe = documents
-      .find((doc) => doc.frame.frameId === "child")
-      ?.domNodes?.find((n) => n.backendNodeId === 23);
-    const input = documents
-      .find((doc) => doc.frame.frameId === "nested")
-      ?.domNodes?.find((n) => n.backendNodeId === 31);
+    const atDpr1 = await captureAtDpr(1);
+    const atDpr2 = await captureAtDpr(2);
 
-    expect(nestedIframe?.localRect).toEqual({ x: 5, y: 6, w: 100, h: 80 });
-    expect(nestedIframe?.rect).toEqual({ x: 15, y: 26, w: 100, h: 80 });
-    expect(input?.ownerFrameBackendNodeId).toBe(23);
-    expect(input?.localRect).toEqual({ x: 1, y: 2, w: 40, h: 20 });
-    expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
+    expect(atDpr1).toEqual([]);
+    expect(atDpr2).toEqual(atDpr1);
   });
 
-  it("subtracts CSS scroll once without dividing snapshot bounds by a metrics ratio", async () => {
+  it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
       strings: S,
       documents: [
         {
-          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -1232,8 +1322,8 @@ describe("snapshot capture and hover", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
+    const { nodes } = await captureViewModel(cdp, 4);
+    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
   });
 
   it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {

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

@@ -1,110 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
-import { buildDocumentIndex, type DecodedNode } from "../facts";
-import { decodeDocument, REQUESTED_STYLES } from "../snapshot";
-
-function node(id: number, parent: number | null): DecodedNode {
-  return {
-    backendNodeId: id,
-    parentBackendNodeId: parent,
-    tag: "div",
-    attrs: {},
-    paintOrder: 0,
-    position: "static",
-    pointerEvents: "auto",
-  };
-}
-
-describe("document facts", () => {
-  it.each([
-    1_000, 10_000, 100_000,
-  ])("indexes deep and wide inputs of %i without copying ancestors", async (count) => {
-    for (const wide of [false, true]) {
-      let reads = 0;
-      const input = Array.from({ length: count }, (_, i) => {
-        const item = node(i, i ? (wide ? 0 : i - 1) : null);
-        if (i === 0) item.attrs[OVERLAY_HOST_MARKER_ATTR] = "";
-        Object.defineProperty(item, "parentBackendNodeId", {
-          get: () => {
-            reads++;
-            return i ? (wide ? 0 : i - 1) : null;
-          },
-        });
-        return item;
-      }).reverse(); // parent need not precede child
-      const index = await buildDocumentIndex(input);
-      expect(index.nodes.size).toBe(count);
-      expect(index.excludedBackendNodeIds.size).toBe(count);
-      expect(reads).toBeLessThanOrEqual(count * 8);
-      expect(index.nodes.get(count - 1)).toBe(input[0]);
-    }
-  });
-
-  it("handles cycles and orphans and propagates overlay through shadow roots", async () => {
-    const host = { ...node(1, null), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
-    const input = [
-      node(3, 2),
-      { ...node(2, 1), tag: "#document-fragment" },
-      host,
-      node(4, 99),
-      node(5, 6),
-      node(6, 5),
-      node(7, 6),
-    ];
-    const index = await buildDocumentIndex(input);
-    expect([...index.excludedBackendNodeIds].sort()).toEqual([1, 2, 3]);
-    expect(index.nodes.size).toBe(input.length);
-  });
-
-  it("does not propagate a descendant overlay backwards into a cycle", async () => {
-    const overlay = { ...node(3, 1), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
-    const index = await buildDocumentIndex([overlay, node(1, 2), node(2, 1)]);
-    expect([...index.excludedBackendNodeIds]).toEqual([3]);
-  });
-
-  it("decodes current observation bounds, styles and attributes without projecting coordinates", async () => {
-    const strings = ["div", "aria-hidden", "true", "inert", "", "visible", "0", "static", "auto"];
-    const styles = REQUESTED_STYLES.map((style) =>
-      style === "visibility" ? 5 : style === "opacity" ? 6 : style === "position" ? 7 : 8,
-    );
-    const { nodes } = await decodeDocument(
-      {
-        nodes: { backendNodeId: [1], parentIndex: [-1], nodeName: [0], attributes: [[1, 2, 3, 4]] },
-        layout: { nodeIndex: [0], bounds: [[10, 20, 120, 40]], styles: [styles] },
-      },
-      strings,
-    );
-    expect(nodes[0].attrs).toEqual({ "aria-hidden": "true", inert: "" });
-    expect(nodes[0].layout).toEqual({
-      boundsSpace: "snapshot-document-css",
-      bounds: [10, 20, 120, 40],
-      styles: {
-        position: "static",
-        "pointer-events": "auto",
-        cursor: "auto",
-        visibility: "visible",
-        opacity: "0",
-      },
-    });
-    expect(nodes[0]).not.toHaveProperty("rect");
-    expect(nodes[0]).not.toHaveProperty("excluded");
-  });
-
-  it("yields during large inputs so cancellation interrupts indexing", 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,6 @@
 import { describe, expect, it, vi } from "vitest";
 import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
-import { captureObservationFacts } from "../capture-coordinator";
+import { captureViewModel } from "../capture";
 
 interface Control {
   id: number;
@@ -106,19 +106,17 @@ describe("form state identity", () => {
           [11, state("alice@example.com")],
         ]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 10)).toMatchObject({
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 10)).toMatchObject({
       formValue: "",
       formState: "empty",
       formPlaceholder: "snapshot placeholder",
     });
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
       formValue: "alice@example.com",
     });
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)).toMatchObject({
-      formValue: "上海",
-    });
-    expect(captured.documents[0].domNodes.some((n) => n.backendNodeId === 99)).toBe(false);
+    expect(captured.nodes.find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
+    expect(captured.nodes.some((n) => n.backendNodeId === 99)).toBe(false);
   });
 
   it("does not shift state between frames when one frame is absent from the runtime batch", async () => {
@@ -135,10 +133,8 @@ describe("form state identity", () => {
           [21, state("second frame")],
         ]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    const controls = captured.documents
-      .filter((doc) => doc.frame.parentFrameId)
-      .flatMap((doc) => doc.domNodes);
+    const captured = await captureViewModel(cdp, 7);
+    const controls = [...captured.iframeNodes.values()].flat();
     expect(controls.find((n) => n.backendNodeId === 11)?.formValue).toBe("inaccessible frame");
     expect(controls.find((n) => n.backendNodeId === 21)?.formValue).toBe("second frame");
     expect(controls.find((n) => n.backendNodeId === 31)?.formValue).toBe("third frame");
@@ -155,13 +151,8 @@ describe("form state identity", () => {
     });
     const cdp = { send, sendToTarget } as unknown as CdpRunner;
     for (const sessionId of ["left-frame", "right-frame"]) {
-      const captured = await captureObservationFacts(
-        cdpRunnerForTarget(cdp, { tabId: 7, sessionId }),
-        7,
-      );
-      expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
-        sessionId,
-      );
+      const captured = await captureViewModel(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7);
+      expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
       expect(sendToTarget).toHaveBeenCalledWith(
         { tabId: 7, sessionId },
         "Runtime.releaseObjectGroup",
@@ -187,8 +178,8 @@ describe("form state identity", () => {
         result.result.deepSerializedValue.value[0].value[1].value = "not json";
       return result;
     });
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)).toMatchObject({
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)).toMatchObject({
       formValue: "snapshot value",
       formPlaceholder: "snapshot placeholder",
     });
@@ -201,7 +192,7 @@ describe("form state identity", () => {
       controller.abort();
       return reply([[11, state("new")]]);
     });
-    await expect(captureObservationFacts(cdp, 7, controller.signal)).rejects.toMatchObject({
+    await expect(captureViewModel(cdp, 7, { signal: controller.signal })).rejects.toMatchObject({
       name: "AbortError",
     });
     expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
@@ -225,13 +216,9 @@ describe("form state identity", () => {
         return result;
       },
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 11)?.formValue).toBe(
-      "snapshot value",
-    );
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 12)?.formValue).toBe(
-      "live value",
-    );
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
+    expect(captured.nodes.find((n) => n.backendNodeId === 12)?.formValue).toBe("live value");
   });
 
   it.each([
@@ -241,8 +228,8 @@ describe("form state identity", () => {
     const { cdp } = fakeCdp([[{ id: 11, value: "secret", type }]], () =>
       reply([[11, { ...state("secret"), sensitive: true }]]),
     );
-    const captured = await captureObservationFacts(cdp, 7);
-    const control = captured.documents[0].domNodes.find((n) => n.backendNodeId === 11);
+    const captured = await captureViewModel(cdp, 7);
+    const control = captured.nodes.find((n) => n.backendNodeId === 11);
     expect(control?.formState).toBe("filled");
     expect(control?.formValue).toBeUndefined();
     expect(control?.formDefaultValue).toBeUndefined();
@@ -270,13 +257,9 @@ describe("form state identity", () => {
       expect(entries).toHaveLength(250);
       return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
     });
-    const captured = await captureObservationFacts(cdp, 7);
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 250)?.formValue).toBe(
-      "live 250",
-    );
-    expect(captured.documents[0].domNodes.find((n) => n.backendNodeId === 251)?.formValue).toBe(
-      "old",
-    );
+    const captured = await captureViewModel(cdp, 7);
+    expect(captured.nodes.find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
+    expect(captured.nodes.find((n) => n.backendNodeId === 251)?.formValue).toBe("old");
     expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
     expect(
       send.mock.calls.filter(([, method]) => method === "Runtime.releaseObjectGroup"),

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

@@ -0,0 +1,378 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpRunner } from "../../shared";
+import type { CapturedNode, CapturedViewModel } from "../capture";
+import { captureFrameData } from "../frame-capture";
+
+function ownerNode(backendNodeId: number, x: number): CapturedNode {
+  return {
+    backendNodeId,
+    parentBackendNodeId: 1,
+    frameId: "main",
+    ownerFrameBackendNodeId: null,
+    tag: "iframe",
+    attrs: {},
+    rect: { x, y: 100, w: 300, h: 200 },
+    localRect: { x, y: 100, w: 300, h: 200 },
+    paintOrder: 1,
+    position: "static",
+    pointerEvents: "auto",
+  };
+}
+
+function childSnapshot(frameId: string, backendNodeId: number) {
+  const strings = [frameId, "body", "button", "static", "auto", "pointer"];
+  return {
+    strings,
+    documents: [
+      {
+        frameId,
+        nodes: {
+          parentIndex: [-1, 0],
+          nodeName: [1, 2],
+          backendNodeId: [backendNodeId - 1, backendNodeId],
+          attributes: [[], []],
+        },
+        layout: {
+          nodeIndex: [0, 1],
+          styles: [
+            [3, 4, 4],
+            [3, 4, 5],
+          ],
+          bounds: [
+            [0, 0, 300, 200],
+            [10, 20, 100, 40],
+          ],
+          paintOrders: [0, 1],
+        },
+      },
+    ],
+  };
+}
+
+describe("captureFrameData", () => {
+  it("does not request frame geometry for a root-only page", async () => {
+    const root = { ...ownerNode(1, 0), tag: "body" };
+    const captured: CapturedViewModel = {
+      nodes: [root],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [root]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const send = vi.fn(async (_tabId, method) => {
+      if (method === "Accessibility.enable") return {};
+      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+      throw new Error(`unexpected ${method}`);
+    });
+    const cdp: CdpRunner = {
+      send: send as CdpRunner["send"],
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [{ frameId: "main", target: { tabId: 4 } }],
+      })),
+    };
+
+    await captureFrameData(cdp, 4, captured);
+
+    expect(send.mock.calls.some(([, method]) => method === "Page.createIsolatedWorld")).toBe(false);
+    expect(send.mock.calls.some(([, method]) => method === "DOM.getBoxModel")).toBe(false);
+    expect(send.mock.calls.some(([, method]) => method === "Page.getLayoutMetrics")).toBe(false);
+  });
+
+  it("projects same-origin frame-local rects through the iframe content box", async () => {
+    const owner = ownerNode(10, 50);
+    const canvas: CapturedNode = {
+      backendNodeId: 101,
+      parentBackendNodeId: 100,
+      frameId: "child",
+      ownerFrameBackendNodeId: 10,
+      tag: "canvas",
+      attrs: {},
+      rect: null,
+      localRect: { x: 12, y: 12, w: 224, h: 94 },
+      paintOrder: 1,
+      position: "static",
+      pointerEvents: "auto",
+    };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map([[10, [canvas]]]),
+      frameNodes: new Map([
+        ["main", [owner]],
+        ["child", [canvas]],
+      ]),
+      frameOwnerBackendNodeIds: new Map([["child", 10]]),
+      frameParentIds: new Map([["child", "main"]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        if (method === "DOM.getBoxModel") {
+          return { model: { content: [52, 102, 352, 102, 352, 302, 52, 302] } };
+        }
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 91 };
+        if (method === "Runtime.evaluate") {
+          return { result: { value: { width: 300, height: 200 } } };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as CdpRunner["send"],
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4 },
+          },
+        ],
+      })),
+    };
+
+    await captureFrameData(cdp, 4, captured);
+
+    expect(captured.frameNodes?.get("child")?.[0]?.rect).toEqual({
+      x: 64,
+      y: 114,
+      w: 224,
+      h: 94,
+    });
+    expect(captured.iframeNodes.get(10)?.[0]?.rect).toEqual({ x: 64, y: 114, w: 224, h: 94 });
+  });
+
+  it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
+    const leftOwner = ownerNode(10, 50);
+    const rightOwner = ownerNode(20, 500);
+    const captured: CapturedViewModel = {
+      nodes: [leftOwner, rightOwner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [leftOwner, rightOwner]]]),
+      frameOwnerBackendNodeIds: new Map(),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const sendToTarget = vi.fn(async (target, method) => {
+      if (method === "Page.getLayoutMetrics") {
+        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
+      }
+      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+      if (method === "DOMSnapshot.captureSnapshot") {
+        return target.sessionId === "left-session"
+          ? childSnapshot("left", 101)
+          : childSnapshot("right", 201);
+      }
+      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+      throw new Error(`unexpected ${method}`);
+    });
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") {
+          const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
+          const x = backendNodeId === 10 ? 50 : 500;
+          return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
+        }
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "left",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "left-session" },
+          },
+          {
+            frameId: "right",
+            parentFrameId: "main",
+            ownerBackendNodeId: 20,
+            target: { tabId: 4, sessionId: "right-session" },
+          },
+        ],
+      })),
+    };
+
+    const trees = await captureFrameData(cdp, 4, captured);
+
+    expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
+    expect(
+      captured.frameNodes?.get("left")?.find((node) => node.backendNodeId === 101)?.rect,
+    ).toEqual({ x: 60, y: 120, w: 100, h: 40 });
+    expect(
+      captured.frameNodes?.get("right")?.find((node) => node.backendNodeId === 201)?.rect,
+    ).toEqual({ x: 510, y: 120, w: 100, h: 40 });
+    expect(captured.frameOwnerBackendNodeIds).toEqual(
+      new Map([
+        ["left", 10],
+        ["right", 20],
+      ]),
+    );
+    expect(captured.frameParentIds).toEqual(
+      new Map([
+        ["left", "main"],
+        ["right", "main"],
+      ]),
+    );
+  });
+
+  it("bounds concurrent same-target frame geometry resolution", async () => {
+    const owners = Array.from({ length: 8 }, (_, index) => ownerNode(10 + index, index * 40));
+    const childFrames = owners.map((owner, index) => {
+      const frameId = `child-${index}`;
+      const node: CapturedNode = {
+        backendNodeId: 100 + index,
+        parentBackendNodeId: null,
+        frameId,
+        ownerFrameBackendNodeId: owner.backendNodeId,
+        tag: "canvas",
+        attrs: {},
+        rect: null,
+        localRect: { x: 1, y: 2, w: 20, h: 10 },
+        paintOrder: 1,
+        position: "static",
+        pointerEvents: "auto",
+      };
+      return { frameId, owner, node };
+    });
+    const captured: CapturedViewModel = {
+      nodes: owners,
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(childFrames.map(({ owner, node }) => [owner.backendNodeId, [node]])),
+      frameNodes: new Map([
+        ["main", owners],
+        ...childFrames.map(({ frameId, node }): [string, CapturedNode[]] => [frameId, [node]]),
+      ]),
+      frameOwnerBackendNodeIds: new Map(
+        childFrames.map(({ frameId, owner }) => [frameId, owner.backendNodeId]),
+      ),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    let activeWorlds = 0;
+    let maxActiveWorlds = 0;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        if (method === "DOM.getBoxModel") {
+          const backendNodeId = (params as { backendNodeId?: number }).backendNodeId ?? 10;
+          const x = (backendNodeId - 10) * 40;
+          return { model: { content: [x, 100, x + 30, 100, x + 30, 120, x, 120] } };
+        }
+        if (method === "Page.createIsolatedWorld") {
+          activeWorlds += 1;
+          maxActiveWorlds = Math.max(maxActiveWorlds, activeWorlds);
+          await new Promise((resolve) => setTimeout(resolve, 5));
+          activeWorlds -= 1;
+          return { executionContextId: 90 };
+        }
+        if (method === "Runtime.evaluate") {
+          return { result: { value: { width: 30, height: 20 } } };
+        }
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        throw new Error(`unexpected ${method}`);
+      }) as CdpRunner["send"],
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          ...childFrames.map(({ frameId, owner }) => ({
+            frameId,
+            parentFrameId: "main",
+            ownerBackendNodeId: owner.backendNodeId,
+            target: { tabId: 4 },
+          })),
+        ],
+      })),
+    };
+
+    await captureFrameData(cdp, 4, captured);
+
+    expect(maxActiveWorlds).toBe(4);
+    expect(childFrames.every(({ frameId }) => captured.frameNodes?.get(frameId)?.[0]?.rect)).toBe(
+      true,
+    );
+  });
+
+  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
+    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
+        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
+        if (method === "Accessibility.getFullAXTree") {
+          return {
+            nodes: [
+              {
+                nodeId: "button",
+                backendDOMNodeId: 101,
+                role: { type: "role", value: "button" },
+                name: { type: "computedString", value: "Continue" },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+
+    const documents = await captureFrameData(cdp, 4, captured);
+    const childDocument = documents.find((document) => document.frameId === "child");
+
+    expect(childDocument?.axNodes).toEqual([
+      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
+    ]);
+    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
+      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
+    );
+  });
+});

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

@@ -1,12 +1,7 @@
-import { describe, expect, it, vi } from "vitest";
+import { describe, expect, it } from "vitest";
 import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "../capture";
-import {
-  buildFrameDocuments,
-  type FrameAxBatch,
-  type FrameDomInput,
-  type FrameOwnedAxNode,
-} from "../frame-document";
+import type { CapturedNode, CapturedViewModel } from "../capture";
+import { buildFrameDocuments, type FrameAxBatch, type FrameOwnedAxNode } from "../frame-document";
 
 function domNode(frameId: string, backendNodeId: number): CapturedNode {
   return {
@@ -22,16 +17,19 @@ function domNode(frameId: string, backendNodeId: number): CapturedNode {
   };
 }
 
-function captured(frameNodes: Map<string, CapturedNode[]>): FrameDomInput {
+function captured(frameNodes: Map<string, CapturedNode[]>): CapturedViewModel {
   return {
     nodes: frameNodes.get("main") ?? [],
+    viewport: { width: 800, height: 600 },
+    iframeNodes: new Map(),
     frameNodes,
     rootFrameId: "main",
+    excludedBackendNodeIds: new Set(),
   };
 }
 
 describe("buildFrameDocuments", () => {
-  it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", async () => {
+  it("partitions mixed AX results by node ownership and cuts cross-frame parent edges", () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -56,7 +54,7 @@ describe("buildFrameDocuments", () => {
       },
     ];
 
-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
       graph,
       batches,
       captured(
@@ -74,7 +72,7 @@ describe("buildFrameDocuments", () => {
     expect(childNodes.find((node) => node.nodeId === "virtual")?.frameId).toBe("child");
   });
 
-  it("deduplicates overlapping same-target AX results using the strongest ownership", async () => {
+  it("deduplicates overlapping same-target AX results using the strongest ownership", () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -94,7 +92,7 @@ describe("buildFrameDocuments", () => {
       },
     ];
 
-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
       graph,
       batches,
       captured(
@@ -109,7 +107,7 @@ describe("buildFrameDocuments", () => {
     expect(documents.find((document) => document.frameId === "child")?.axNodes).toHaveLength(1);
   });
 
-  it("uses target-scoped backend ownership when OOPIF backend ids collide", async () => {
+  it("uses target-scoped backend ownership when OOPIF backend ids collide", () => {
     const graph: CdpFrameGraph = {
       rootFrameId: "main",
       frames: [
@@ -131,7 +129,7 @@ describe("buildFrameDocuments", () => {
       nodes: [{ nodeId: `${frame.frameId}-node`, backendDOMNodeId: 7 }],
     }));
 
-    const documents = await buildFrameDocuments(
+    const documents = buildFrameDocuments(
       graph,
       batches,
       captured(
@@ -151,7 +149,7 @@ describe("buildFrameDocuments", () => {
     );
   });
 
-  it("uses captured frame parent identity instead of guessing from backend ids", async () => {
+  it("uses captured frame parent identity instead of guessing from backend ids", () => {
     const frameNodes = new Map([
       ["main", [domNode("main", 1)]],
       ["left", [domNode("left", 7)]],
@@ -159,51 +157,18 @@ describe("buildFrameDocuments", () => {
       ["child", [domNode("child", 9)]],
     ]);
     const capture = captured(frameNodes);
+    capture.frameOwnerBackendNodeIds = new Map([["child", 7]]);
+    capture.frameParentIds = new Map([["child", "left"]]);
     const frames = ["main", "left", "right", "child"].map((frameId) => ({
-      frame: {
-        frameId,
-        target: { tabId: 4 },
-        ...(frameId === "child" ? { parentFrameId: "left", ownerBackendNodeId: 7 } : {}),
-      },
+      frame: { frameId, target: { tabId: 4 } },
       nodes: [],
     }));
 
-    const documents = await buildFrameDocuments(null, frames, capture);
+    const documents = buildFrameDocuments(null, frames, capture);
 
     expect(documents.find((document) => document.frameId === "child")).toMatchObject({
       parentFrameId: "left",
       ownerBackendNodeId: 7,
     });
   });
-  it("rejects explicit AX frame ownership in a different target", async () => {
-    const frames = [
-      { frameId: "main", target: { tabId: 4 } },
-      { frameId: "remote", target: { tabId: 4, sessionId: "remote" } },
-    ];
-    const unresolved = vi.fn();
-    const documents = await buildFrameDocuments(
-      { rootFrameId: "main", frames },
-      [{ frame: frames[0], nodes: [{ nodeId: "wrong", frameId: "remote" }] }],
-      captured(new Map()),
-      undefined,
-      unresolved,
-    );
-    expect(documents.every((doc) => doc.axNodes.length === 0)).toBe(true);
-    expect(unresolved).toHaveBeenCalledOnce();
-  });
-
-  it("resolves a reverse-ordered deep AX parent chain without recursion", async () => {
-    const frame = { frameId: "main", target: { tabId: 4 } };
-    const nodes: FrameOwnedAxNode[] = Array.from({ length: 10000 }, (_, i) => ({
-      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

@@ -0,0 +1,386 @@
+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 clustered = 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(clustered.groups).toHaveLength(1);
+    expect(clustered.groups[0]?.memberCount).toBe(2);
+    expect(clustered.groups[0]?.label).toBeUndefined();
+    expect(
+      projectRenderedSurfaces(
+        scene,
+        [document([body, ...surfaces.map((s) => domNode(s.backendNodeId))])],
+        clustered,
+      ),
+    ).toMatchObject({
+      visualSurfaces: [expect.objectContaining({ parentId: 10, backendNodeId: 3, memberCount: 2 })],
+    });
+  });
+
+  it("does not merge a contained canvas with a larger independent canvas", () => {
+    const clustered = 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(clustered.groups).toHaveLength(2);
+  });
+
+  it("keeps the existing inclusive 90 percent stack threshold", () => {
+    const clustered = clusterRenderedSurfaces([
+      {
+        renderingKind: "canvas",
+        frameId: "main",
+        backendNodeId: 2,
+        parentBackendNodeId: 1,
+        visibleRect: { x: 0, y: 0, w: 100, h: 100 },
+        paintOrder: 1,
+      },
+      {
+        renderingKind: "canvas",
+        frameId: "main",
+        backendNodeId: 3,
+        parentBackendNodeId: 1,
+        visibleRect: { x: 5, y: 0, w: 90, h: 100 },
+        paintOrder: 2,
+      },
+    ]);
+
+    expect(clustered.groups).toEqual([expect.objectContaining({ memberCount: 2 })]);
+  });
+
+  it("does not merge coincident canvases owned by different containers", () => {
+    const clustered = 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(clustered.groups).toHaveLength(2);
+  });
+
+  it("keeps adjacent map tiles and twenty sparklines as independent surfaces", () => {
+    const surfaces = Array.from({ length: 20 }, (_, index) =>
+      domNode(100 + index, {
+        parentBackendNodeId: 1,
+        rect: { x: index * 12, y: 20, w: 10, h: 8 },
+      }),
+    );
+    const clustered = clusterRenderedSurfaces(
+      discoverRenderedSurfaces(
+        [document([domNode(1, { tag: "main", rect: null, localRect: null }), ...surfaces])],
+        { width: 1280, height: 720 },
+      ),
+    );
+
+    expect(clustered.groups).toHaveLength(20);
+    expect(clustered.groups.every((group) => group.memberCount === 1)).toBe(true);
+    expect(clustered.truncated).toBe(false);
+  });
+
+  it("clusters a large coincident stack without retaining every member", () => {
+    const surfaces = Array.from({ length: 10_000 }, (_, index) => ({
+      renderingKind: "canvas" as const,
+      frameId: "main",
+      backendNodeId: index + 1,
+      parentBackendNodeId: 1,
+      visibleRect: { x: 10, y: 20, w: 800, h: 500 },
+      paintOrder: index,
+    }));
+
+    const clustered = clusterRenderedSurfaces(surfaces);
+
+    expect(clustered.groups).toEqual([
+      expect.objectContaining({ memberCount: 10_000, representative: surfaces[9_999] }),
+    ]);
+    expect(clustered.truncated).toBe(false);
+  });
+
+  it("keeps large non-overlapping surface sets linear and independent", () => {
+    const surfaces = Array.from({ length: 10_000 }, (_, index) => ({
+      renderingKind: "canvas" as const,
+      frameId: "main",
+      backendNodeId: index + 1,
+      parentBackendNodeId: 1,
+      visibleRect: { x: index * 20, y: 0, w: 10, h: 10 },
+      paintOrder: index,
+    }));
+
+    const clustered = clusterRenderedSurfaces(surfaces);
+
+    expect(clustered.groups).toHaveLength(10_000);
+    expect(clustered.groups.every((group) => group.memberCount === 1)).toBe(true);
+    expect(clustered.truncated).toBe(false);
+  });
+
+  it("keeps the highest-priority surfaces when the computation guard truncates input", () => {
+    const surfaces = [
+      {
+        renderingKind: "canvas" as const,
+        frameId: "main",
+        backendNodeId: 1,
+        parentBackendNodeId: 10,
+        visibleRect: { x: 0, y: 0, w: 10, h: 10 },
+        paintOrder: 1,
+      },
+      {
+        renderingKind: "canvas" as const,
+        frameId: "main",
+        backendNodeId: 2,
+        parentBackendNodeId: 10,
+        visibleRect: { x: 20, y: 0, w: 100, h: 100 },
+        paintOrder: 1,
+      },
+      {
+        renderingKind: "canvas" as const,
+        frameId: "main",
+        backendNodeId: 3,
+        parentBackendNodeId: 10,
+        visibleRect: { x: 140, y: 0, w: 8, h: 8 },
+        paintOrder: 1,
+        label: "Important status",
+      },
+    ];
+
+    const clustered = clusterRenderedSurfaces(surfaces, { maxSurfaces: 2 });
+
+    expect(clustered.groups.map((group) => group.representative.backendNodeId).sort()).toEqual([
+      2, 3,
+    ]);
+    expect(clustered).toMatchObject({ truncated: true, omittedCount: 1 });
+  });
+
+  it("stops at the comparison budget without dropping already completed groups", () => {
+    const surfaces = Array.from({ length: 3 }, (_, index) => ({
+      renderingKind: "canvas" as const,
+      frameId: "main",
+      backendNodeId: index + 1,
+      parentBackendNodeId: 10,
+      visibleRect: { x: 0, y: 0, w: 100, h: 100 },
+      paintOrder: index + 1,
+    }));
+
+    const clustered = clusterRenderedSurfaces(surfaces, { maxComparisons: 1 });
+
+    expect(clustered.groups).toEqual([expect.objectContaining({ memberCount: 2 })]);
+    expect(clustered).toMatchObject({ truncated: true, omittedCount: 1 });
+  });
+});

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

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

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

@@ -1,21 +1,344 @@
-// Browser-side hover probes and overlay exclusion fallback. Static collection
-// lives in capture-coordinator; snapshot decoding has no browser dependency.
+// CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
+// → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
+// raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
+// shared string table); requested computed styles are decoded through
+// STYLE_COL so capture and visibility policy share one explicit contract.
+
+import type { Rect, Viewport } from "@browser-skill/vom";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
-import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
+import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
+import { type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
-import type { CapturedNode, CapturedSurfaceProbe } from "./facts";
-
-export type {
-  CapturedNode,
-  CapturedSurfaceProbe,
-} from "./facts";
-
-import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
 import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 
+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 CapturedIframeNodes = Map<number, CapturedNode[]>;
+
+export interface CapturedSurfaceProbe {
+  triggerBackendNodeId: number;
+  triggerPoint?: { x: number; y: number };
+  triggerAction: "hover" | "focus" | string;
+  subItems: string[];
+  confidence?: "high" | "medium" | "low";
+}
+
+export interface CapturedViewModel {
+  nodes: CapturedNode[];
+  viewport: Viewport;
+  iframeNodes: CapturedIframeNodes;
+  frameNodes?: Map<string, CapturedNode[]>;
+  frameOwnerBackendNodeIds?: Map<string, number>;
+  /** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
+  frameParentIds?: Map<string, string>;
+  rootFrameId?: string;
+  /** 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);
+  }
+}
+
 interface RuntimeEvaluateReply {
   result?: {
     value?: unknown;
+    deepSerializedValue?: DeepSerializedValue;
   };
 }
 
@@ -34,6 +357,44 @@ interface CdpDomNode {
   shadowRoots?: CdpDomNode[];
 }
 
+interface ParseDocumentResult {
+  nodes: CapturedNode[];
+  excludedBackendNodeIds: Set<number>;
+}
+
+interface FrameContext {
+  frameId?: string;
+  ownerFrameBackendNodeId: number | null;
+  projection: GeometryProjection | null;
+  scrollX: number;
+  scrollY: number;
+}
+
+function str(strings: string[], idx: number | undefined): string {
+  if (idx === undefined || idx < 0) return "";
+  return strings[idx] ?? "";
+}
+
+function devicePixelRatio(metrics: LayoutMetricsReply): number {
+  const layoutW = metrics.layoutViewport?.clientWidth ?? 0;
+  const cssW = metrics.cssLayoutViewport?.clientWidth ?? 0;
+  if (!layoutW || !cssW) return 1;
+  const dpr = layoutW / cssW;
+  if (!Number.isFinite(dpr) || dpr <= 0) return 1;
+  return dpr >= 1 ? dpr : 1;
+}
+
+function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
+  const out = new Map<number, number>();
+  if (!sparse?.index || !sparse.value) return out;
+  for (let i = 0; i < sparse.index.length; i++) {
+    const nodeIndex = sparse.index[i];
+    const docIndex = sparse.value[i];
+    if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
+  }
+  return out;
+}
+
 function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<number>): void {
   if (!node) return;
   if (typeof node.backendNodeId === "number") {
@@ -442,3 +803,371 @@ 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 {
+  iframeNodes: CapturedIframeNodes;
+  frameOwnerBackendNodeIds: Map<string, number>;
+  frameParentIds: Map<string, string>;
+  excludedBackendNodeIds: Set<number>;
+}
+
+function parseChildFrameDocuments(
+  documents: SnapshotDocument[],
+  strings: string[],
+  dpr: number,
+  parentDocIndex: number,
+  parentContext: FrameContext,
+  visited = new Set<number>(),
+): ParseFrameDocumentsResult {
+  const iframeNodes: CapturedIframeNodes = new Map();
+  const frameOwnerBackendNodeIds = new Map<string, number>();
+  const frameParentIds = new Map<string, string>();
+  const excludedBackendNodeIds = new Set<number>();
+  const parentDoc = documents[parentDocIndex];
+  const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
+  if (cdi.size === 0) {
+    return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
+  }
+
+  const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
+  for (const [nodeArrayIdx, childDocIndex] of cdi) {
+    if (visited.has(childDocIndex)) continue;
+    const childDoc = documents[childDocIndex];
+    if (!childDoc) continue;
+    const iframeBackendId = parentBackendIds[nodeArrayIdx];
+    if (iframeBackendId === undefined) continue;
+    // DOMSnapshot reports the iframe owner's border-box bounds, but child
+    // document coordinates start at the content-box origin. Preserve the
+    // frame-local rectangles here and let frame-capture normalize them with
+    // authoritative content quads once the frame graph is available.
+    const projection = null;
+
+    const childContext: FrameContext = {
+      frameId: snapshotFrameId(childDoc, strings),
+      ownerFrameBackendNodeId: iframeBackendId,
+      projection,
+      scrollX: childDoc.scrollOffsetX ?? 0,
+      scrollY: childDoc.scrollOffsetY ?? 0,
+    };
+    const nextVisited = new Set(visited);
+    nextVisited.add(childDocIndex);
+    const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
+    iframeNodes.set(iframeBackendId, parsed.nodes);
+    if (childContext.frameId) {
+      frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
+      if (parentContext.frameId) frameParentIds.set(childContext.frameId, parentContext.frameId);
+    }
+    for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
+
+    const nested = parseChildFrameDocuments(
+      documents,
+      strings,
+      dpr,
+      childDocIndex,
+      childContext,
+      nextVisited,
+    );
+    for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
+      iframeNodes.set(nestedFrameId, nestedNodes);
+    }
+    for (const [frameId, ownerBackendNodeId] of nested.frameOwnerBackendNodeIds) {
+      frameOwnerBackendNodeIds.set(frameId, ownerBackendNodeId);
+    }
+    for (const [frameId, parentFrameId] of nested.frameParentIds) {
+      frameParentIds.set(frameId, parentFrameId);
+    }
+    for (const id of nested.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
+  }
+
+  return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
+}
+
+export async function captureViewModel(
+  cdp: CdpRunner,
+  tabId: number,
+  options: CaptureViewModelOptions = {},
+): Promise<CapturedViewModel> {
+  throwIfAborted(options.signal);
+  let metrics: LayoutMetricsReply = {};
+  try {
+    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    console.debug("[bsk capture] layout metrics unavailable", error);
+  }
+  throwIfAborted(options.signal);
+  const dpr = devicePixelRatio(metrics);
+  const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
+  const viewport: Viewport = {
+    width: vpSrc.clientWidth ?? 0,
+    height: vpSrc.clientHeight ?? 0,
+  };
+  const scrollX = vpSrc.pageX ?? 0;
+  const scrollY = vpSrc.pageY ?? 0;
+
+  await cdp.send(tabId, "DOMSnapshot.enable", {});
+  throwIfAborted(options.signal);
+  const snap = await cdp.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
+    computedStyles: REQUESTED_STYLES,
+    includePaintOrder: true,
+    includeDOMRects: true,
+  });
+  throwIfAborted(options.signal);
+
+  const strings = snap.strings ?? [];
+  const documents = snap.documents ?? [];
+  const doc0 = documents[0];
+  if (!doc0?.nodes?.backendNodeId) {
+    return {
+      nodes: [],
+      viewport,
+      iframeNodes: new Map(),
+      excludedBackendNodeIds: new Set(),
+    };
+  }
+
+  const topContext: FrameContext = {
+    frameId: snapshotFrameId(doc0, strings),
+    ownerFrameBackendNodeId: null,
+    projection: {
+      sourceClips: [],
+      edges: [],
+      topViewport: viewport,
+    },
+    scrollX,
+    scrollY,
+  };
+  const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
+  const nodes = mainParsed.nodes;
+  const excludedBackendNodeIds = new Set(mainParsed.excludedBackendNodeIds);
+
+  const frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, topContext);
+  const iframeNodes = frameParsed.iframeNodes;
+  for (const id of frameParsed.excludedBackendNodeIds) {
+    excludedBackendNodeIds.add(id);
+  }
+
+  await enrichFormControlStates(cdp, tabId, [nodes, ...iframeNodes.values()], options.signal);
+  throwIfAborted(options.signal);
+
+  const frameNodes = new Map<string, CapturedNode[]>();
+  if (topContext.frameId) frameNodes.set(topContext.frameId, nodes);
+  for (const iframeFrameNodes of iframeNodes.values()) {
+    const frameId = iframeFrameNodes.find((node) => node.frameId)?.frameId;
+    if (frameId) frameNodes.set(frameId, iframeFrameNodes);
+  }
+  for (const [frameId, ownerBackendNodeId] of frameParsed.frameOwnerBackendNodeIds) {
+    if (!frameNodes.has(frameId)) {
+      frameNodes.set(frameId, iframeNodes.get(ownerBackendNodeId) ?? []);
+    }
+  }
+
+  return {
+    nodes,
+    viewport,
+    iframeNodes,
+    frameNodes,
+    frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
+    frameParentIds: frameParsed.frameParentIds,
+    ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
+    excludedBackendNodeIds,
+  };
+}

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

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

@@ -1,155 +0,0 @@
-import type { CdpRunner } from "../shared";
-import type { CapturedNode } from "./facts";
-import { isCaptureAbort as isAbortError, throwCaptureAborted as throwIfAborted } from "./facts";
-
-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

@@ -0,0 +1,230 @@
+import type { CdpFrame, CdpFrameGraph } from "@/browser-driver/frame-graph";
+import { createFrameGeometryContext } from "../frame-geometry";
+import { type CdpRunner, cdpRunnerForTarget, sendToCdpTarget } from "../shared";
+import { type CapturedNode, type CapturedViewModel, captureViewModel } from "./capture";
+import {
+  buildFrameDocuments,
+  type FrameAxBatch,
+  type FrameDocument,
+  type FrameOwnedAxNode,
+} from "./frame-document";
+
+export type FrameAxNode = FrameOwnedAxNode;
+export type CapturedFrameDocument<T extends FrameAxNode> = FrameDocument<T>;
+
+const FRAME_GEOMETRY_CONCURRENCY = 4;
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException("observation aborted", "AbortError");
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+async function forEachWithConcurrency<T>(
+  items: readonly T[],
+  concurrency: number,
+  worker: (item: T) => Promise<void>,
+): Promise<void> {
+  let next = 0;
+  const run = async () => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      await worker(items[index]);
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, run));
+}
+
+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;
+  }
+}
+
+async function captureMissingFrameDocuments(
+  cdp: CdpRunner,
+  tabId: number,
+  graph: CdpFrameGraph,
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!captured.frameNodes) captured.frameNodes = new Map();
+  if (!captured.frameOwnerBackendNodeIds) captured.frameOwnerBackendNodeIds = new Map();
+  if (!captured.frameParentIds) captured.frameParentIds = new Map();
+
+  for (const frame of graph.frames) {
+    if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
+    try {
+      const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
+        signal,
+      });
+      const rootFrameId = child.rootFrameId ?? frame.frameId;
+      const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
+      if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
+      if (rootFrameId !== frame.frameId && !childFrames.has(frame.frameId)) {
+        childFrames.set(
+          frame.frameId,
+          child.nodes.map((node) => ({ ...node, frameId: frame.frameId })),
+        );
+      }
+      for (const [childFrameId, nodes] of childFrames) {
+        captured.frameNodes.set(childFrameId, nodes);
+      }
+      if (frame.ownerBackendNodeId !== undefined) {
+        captured.iframeNodes.set(
+          frame.ownerBackendNodeId,
+          captured.frameNodes.get(frame.frameId) ?? [],
+        );
+        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      }
+      if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
+      for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
+        captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);
+      }
+      for (const [childFrameId, parentFrameId] of child.frameParentIds ?? []) {
+        captured.frameParentIds.set(childFrameId, parentFrameId);
+      }
+    } catch (err) {
+      if (isAbortError(err)) throw err;
+      console.debug("[bsk observation] child frame DOM capture failed", {
+        frameId: frame.frameId,
+        err,
+      });
+    }
+  }
+}
+
+async function normalizeFrameLocalRects(
+  cdp: CdpRunner,
+  graph: CdpFrameGraph,
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!captured.frameNodes) return;
+  const geometry = createFrameGeometryContext(cdp, graph);
+  const frameById = new Map(graph.frames.map((frame) => [frame.frameId, frame]));
+  await forEachWithConcurrency(
+    [...captured.frameNodes],
+    FRAME_GEOMETRY_CONCURRENCY,
+    async ([frameId, nodes]) => {
+      if (frameId === graph.rootFrameId || !frameById.has(frameId)) return;
+      try {
+        const normalized: CapturedNode[] = [];
+        for (const node of nodes) {
+          if (!node.localRect) {
+            normalized.push({ ...node, rect: null });
+          } else {
+            const bounds = await geometry.projectFrameLocalRect(frameId, node.localRect);
+            normalized.push({
+              ...node,
+              rect: bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null,
+            });
+          }
+        }
+        throwIfAborted(signal);
+        captured.frameNodes?.set(frameId, normalized);
+        const ownerBackendNodeId =
+          frameById.get(frameId)?.ownerBackendNodeId ??
+          captured.frameOwnerBackendNodeIds?.get(frameId);
+        if (ownerBackendNodeId !== undefined) {
+          captured.iframeNodes.set(ownerBackendNodeId, normalized);
+        }
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        console.debug("[bsk observation] frame-local geometry normalization failed", {
+          frameId,
+          err,
+        });
+        const unavailable = nodes.map((node) => ({ ...node, rect: null }));
+        captured.frameNodes?.set(frameId, unavailable);
+        const ownerBackendNodeId =
+          frameById.get(frameId)?.ownerBackendNodeId ??
+          captured.frameOwnerBackendNodeIds?.get(frameId);
+        if (ownerBackendNodeId !== undefined) {
+          captured.iframeNodes.set(ownerBackendNodeId, unavailable);
+        }
+      }
+    },
+  );
+}
+
+async function captureAxTrees<T extends FrameAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  discoveredFrames: CdpFrame[],
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+): Promise<FrameAxBatch<T>[]> {
+  let frames = [...discoveredFrames];
+  const capturedFrameIds = [...(captured.frameNodes?.keys() ?? [])];
+  if (frames.length === 0) {
+    const rootFrameId = captured.rootFrameId ?? capturedFrameIds[0] ?? "root";
+    frames = [{ frameId: rootFrameId, target: { tabId } }];
+  }
+  for (const frameId of capturedFrameIds) {
+    if (!frames.some((frame) => frame.frameId === frameId)) {
+      frames.push({ frameId, target: { tabId } });
+    }
+  }
+
+  let firstFailure: unknown;
+  const trees = await Promise.all(
+    frames.map(async (frame): Promise<FrameAxBatch<T>> => {
+      try {
+        throwIfAborted(signal);
+        await sendToCdpTarget(cdp, frame.target, "Accessibility.enable", {});
+        const result = await sendToCdpTarget<{ nodes?: T[] }>(
+          cdp,
+          frame.target,
+          "Accessibility.getFullAXTree",
+          frame.frameId === "root" ? {} : { frameId: frame.frameId },
+        );
+        throwIfAborted(signal);
+        return {
+          frame,
+          nodes: result.nodes ?? [],
+        };
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        firstFailure ??= err;
+        console.debug("[bsk observation] frame AX capture failed", {
+          frameId: frame.frameId,
+          err,
+        });
+        return { frame, nodes: [] };
+      }
+    }),
+  );
+  const capturedNodeCount = [...captured.iframeNodes.values()].reduce(
+    (count, nodes) => count + nodes.length,
+    captured.nodes.length,
+  );
+  if (firstFailure && capturedNodeCount === 0 && trees.every((tree) => tree.nodes.length === 0)) {
+    throw firstFailure;
+  }
+  return trees;
+}
+
+export async function captureFrameData<T extends FrameAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  captured: CapturedViewModel,
+  signal?: AbortSignal,
+): Promise<CapturedFrameDocument<T>[]> {
+  const graph = await discoverFrameGraph(cdp, tabId);
+  const frames = graph?.frames ?? [];
+  if (graph) {
+    await captureMissingFrameDocuments(cdp, tabId, graph, captured, signal);
+    await normalizeFrameLocalRects(cdp, graph, captured, signal);
+  }
+  throwIfAborted(signal);
+  const batches = await captureAxTrees<T>(cdp, tabId, frames, captured, signal);
+  return buildFrameDocuments(graph, batches, captured);
+}

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

@@ -4,8 +4,7 @@ import {
   type CdpTarget,
   cdpTargetKey,
 } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "./facts";
-import { captureCheckpoint } from "./facts";
+import type { CapturedNode, CapturedViewModel } from "./capture";
 
 export interface FrameOwnedAxNode {
   nodeId: string;
@@ -24,14 +23,6 @@ export interface FrameDocument<T extends FrameOwnedAxNode> extends CdpFrame {
   contextScopeId: string;
   axNodes: T[];
   domNodes: CapturedNode[];
-  excludedBackendNodeIds?: ReadonlySet<number>;
-}
-
-/** Explicit snapshot document data used to join DOM and AX ownership. */
-export interface FrameDomInput {
-  nodes: CapturedNode[];
-  rootFrameId?: string;
-  frameNodes?: ReadonlyMap<string, CapturedNode[]>;
 }
 
 interface Ownership {
@@ -56,24 +47,35 @@ function targetBackendKey(target: CdpTarget, backendNodeId: number): string {
 function frameList<T extends FrameOwnedAxNode>(
   graph: CdpFrameGraph | null,
   batches: FrameAxBatch<T>[],
+  captured: CapturedViewModel,
 ): CdpFrame[] {
   const frames = new Map<string, CdpFrame>();
   for (const frame of graph?.frames ?? []) frames.set(frame.frameId, frame);
   for (const batch of batches) {
     if (!frames.has(batch.frame.frameId)) frames.set(batch.frame.frameId, batch.frame);
   }
-  return [...frames.values()];
+  for (const frameId of captured.frameNodes?.keys() ?? []) {
+    if (!frames.has(frameId))
+      frames.set(frameId, { frameId, target: { tabId: batches[0]?.frame.target.tabId ?? 0 } });
+  }
+  return [...frames.values()].map((frame) => {
+    const ownerBackendNodeId =
+      frame.ownerBackendNodeId ?? captured.frameOwnerBackendNodeIds?.get(frame.frameId);
+    const parentFrameId = frame.parentFrameId ?? captured.frameParentIds?.get(frame.frameId);
+    return {
+      ...frame,
+      ...(ownerBackendNodeId !== undefined ? { ownerBackendNodeId } : {}),
+      ...(parentFrameId ? { parentFrameId } : {}),
+    };
+  });
 }
 
-export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
+export function buildFrameDocuments<T extends FrameOwnedAxNode>(
   graph: CdpFrameGraph | null,
   batches: FrameAxBatch<T>[],
-  captured: FrameDomInput,
-  signal?: AbortSignal,
-  unresolved?: (frame: CdpFrame) => void,
-): Promise<FrameDocument<T>[]> {
-  let work = 0;
-  const frames = frameList(graph, batches);
+  captured: CapturedViewModel,
+): FrameDocument<T>[] {
+  const frames = frameList(graph, batches, captured);
   const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
   const rootFrameId = graph?.rootFrameId ?? captured.rootFrameId ?? frames[0]?.frameId;
   const domNodesForFrame = (frameId: string): CapturedNode[] =>
@@ -81,74 +83,54 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   const backendOwner = new Map<string, string>();
   for (const frame of frames) {
     for (const node of domNodesForFrame(frame.frameId)) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
       backendOwner.set(targetBackendKey(frame.target, node.backendNodeId), frame.frameId);
     }
   }
 
   const candidates = new Map<string, OwnedCandidate<T>>();
   for (const batch of batches) {
-    const nodeById = new Map<string, T>();
-    for (const node of batch.nodes) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
-      nodeById.set(node.nodeId, node);
-    }
-    let reported = false;
+    const nodeById = new Map(batch.nodes.map((node) => [node.nodeId, node]));
     const ownershipByNodeId = new Map<string, Ownership>();
-    const resolveOwnership = async (node: T): Promise<Ownership> => {
-      const path: T[] = [];
-      const visiting = new Set<string>();
-      let current: T | undefined = node;
-      let ownership: Ownership = { frameId: batch.frame.frameId, strength: 1 };
-      while (current) {
-        if (work++ % 256 === 0) await captureCheckpoint(signal);
-        const cached = ownershipByNodeId.get(current.nodeId);
-        if (cached) {
-          ownership = cached;
-          break;
-        }
-        if (visiting.has(current.nodeId)) break;
-        visiting.add(current.nodeId);
-        if (current.frameId) {
-          const frame = frameById.get(current.frameId);
-          // An explicit contradiction must not fall through to a guessed owner.
-          if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(batch.frame.target)) {
-            if (!reported) {
-              unresolved?.(batch.frame);
-              reported = true;
-            }
-            ownership = { frameId: "", strength: 0 };
-            break;
-          }
-          ownership = { frameId: frame.frameId, strength: 4 };
-          ownershipByNodeId.set(current.nodeId, ownership);
-          break;
-        }
-        const frameId =
-          typeof current.backendDOMNodeId === "number"
-            ? backendOwner.get(targetBackendKey(batch.frame.target, current.backendDOMNodeId))
-            : undefined;
+    const resolving = new Set<string>();
+    const resolveOwnership = (node: T): Ownership => {
+      const cached = ownershipByNodeId.get(node.nodeId);
+      if (cached) return cached;
+      if (node.frameId && frameById.has(node.frameId)) {
+        const ownership = { frameId: node.frameId, strength: 4 };
+        ownershipByNodeId.set(node.nodeId, ownership);
+        return ownership;
+      }
+      if (typeof node.backendDOMNodeId === "number") {
+        const frameId = backendOwner.get(
+          targetBackendKey(batch.frame.target, node.backendDOMNodeId),
+        );
         if (frameId) {
-          ownership = { frameId, strength: 3 };
-          ownershipByNodeId.set(current.nodeId, ownership);
-          break;
+          const ownership = { frameId, strength: 3 };
+          ownershipByNodeId.set(node.nodeId, ownership);
+          return ownership;
         }
-        path.push(current);
-        current = current.parentId ? nodeById.get(current.parentId) : undefined;
       }
-      for (let i = path.length - 1; i >= 0; i--) {
-        if (work++ % 256 === 0) await captureCheckpoint(signal);
-        ownership = { frameId: ownership.frameId, strength: Math.min(2, ownership.strength) };
-        ownershipByNodeId.set(path[i].nodeId, 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;
+        }
       }
-      if (!ownershipByNodeId.has(node.nodeId)) ownershipByNodeId.set(node.nodeId, ownership);
+      const ownership = { frameId: batch.frame.frameId, strength: 1 };
+      ownershipByNodeId.set(node.nodeId, ownership);
       return ownership;
     };
 
     for (const node of batch.nodes) {
-      if (work++ % 256 === 0) await captureCheckpoint(signal);
-      const ownership = await resolveOwnership(node);
-      if (!ownership.frameId) continue;
+      const ownership = resolveOwnership(node);
       const key = targetNodeKey(batch.frame.target, node.nodeId);
       const existing = candidates.get(key);
       if (!existing || ownership.strength > existing.ownership.strength) {
@@ -162,7 +144,6 @@ export async function buildFrameDocuments<T extends FrameOwnedAxNode>(
   );
   const axNodesByFrame = new Map<string, T[]>();
   for (const candidate of candidates.values()) {
-    if (work++ % 256 === 0) await captureCheckpoint(signal);
     const { node, target, ownership } = candidate;
     const parentFrameId = node.parentId
       ? ownershipByTargetNode.get(targetNodeKey(target, node.parentId))

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

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

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

@@ -2,10 +2,7 @@ import type { Rect, RenderedRef, VomResult } from "@browser-skill/vom";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import { readRecordingDocumentIdentity } from "@/shared/recording-document-identity";
 import type { CapturedSurfaceProbe } from "./capture";
-import type {
-  FrameDocument as CapturedFrameDocument,
-  FrameOwnedAxNode as FrameAxNode,
-} from "./frame-document";
+import type { CapturedFrameDocument, FrameAxNode } from "./frame-capture";
 
 /** Frame identity needed to resolve an `@eN` that lives in an iframe. */
 export interface CaptureVomFrame {

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

@@ -0,0 +1,207 @@
+import { type Rect, selectHighestPriorityVisualSurfaces } from "@browser-skill/vom";
+import type { ClusteredRenderedSurfaces, RenderedSurface, RenderedSurfaceGroup } from "./types";
+
+const STACK_IOU_RATIO = 0.9;
+const STACK_SIZE_RATIO = 0.9;
+const SIZE_BAND_BASE = 1 / STACK_SIZE_RATIO;
+const POSITION_CELL_RATIO = 0.1;
+const MAX_CLUSTER_COMPARISONS = 1_000_000;
+const MAX_CLUSTER_SURFACES = 50_000;
+
+export interface ClusterRenderedSurfaceOptions {
+  maxComparisons?: number;
+  maxSurfaces?: number;
+}
+
+interface IndexedGroup extends RenderedSurfaceGroup {
+  creationIndex: number;
+  indexKey: string;
+}
+
+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 stackScore(a: RenderedSurface, b: RenderedSurface): number | null {
+  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);
+  const iou = union > 0 ? intersection / union : 0;
+  return iou >= STACK_IOU_RATIO && widthRatio >= STACK_SIZE_RATIO && heightRatio >= STACK_SIZE_RATIO
+    ? iou
+    : null;
+}
+
+function sizeBand(value: number): number {
+  return Math.floor(Math.log(Math.max(Number.EPSILON, value)) / Math.log(SIZE_BAND_BASE));
+}
+
+function bandSize(band: number): number {
+  return SIZE_BAND_BASE ** band;
+}
+
+function spatialKey(rect: Rect): string {
+  const widthBand = sizeBand(rect.w);
+  const heightBand = sizeBand(rect.h);
+  const cellWidth = bandSize(widthBand) * POSITION_CELL_RATIO;
+  const cellHeight = bandSize(heightBand) * POSITION_CELL_RATIO;
+  const centerX = rect.x + rect.w / 2;
+  const centerY = rect.y + rect.h / 2;
+  return `${widthBand}:${heightBand}:${Math.floor(centerX / cellWidth)}:${Math.floor(centerY / cellHeight)}`;
+}
+
+function candidateKeys(rect: Rect): string[] {
+  const keys: string[] = [];
+  const centerX = rect.x + rect.w / 2;
+  const centerY = rect.y + rect.h / 2;
+  const widthBand = sizeBand(rect.w);
+  const heightBand = sizeBand(rect.h);
+  // A >=0.9 size ratio crosses at most one logarithmic band. IoU >=0.9
+  // likewise keeps centers within one 10%-of-size position cell.
+  for (let dw = -1; dw <= 1; dw += 1) {
+    for (let dh = -1; dh <= 1; dh += 1) {
+      const candidateWidthBand = widthBand + dw;
+      const candidateHeightBand = heightBand + dh;
+      const cellWidth = bandSize(candidateWidthBand) * POSITION_CELL_RATIO;
+      const cellHeight = bandSize(candidateHeightBand) * POSITION_CELL_RATIO;
+      const cellX = Math.floor(centerX / cellWidth);
+      const cellY = Math.floor(centerY / cellHeight);
+      for (let dx = -1; dx <= 1; dx += 1) {
+        for (let dy = -1; dy <= 1; dy += 1) {
+          keys.push(`${candidateWidthBand}:${candidateHeightBand}:${cellX + dx}:${cellY + dy}`);
+        }
+      }
+    }
+  }
+  return keys;
+}
+
+function preferredRepresentative(a: RenderedSurface, b: RenderedSurface): RenderedSurface {
+  const aArea = area(a.visibleRect);
+  const bArea = area(b.visibleRect);
+  return bArea > aArea || (bArea === aArea && b.paintOrder > a.paintOrder) ? b : a;
+}
+
+function partitionKey(surface: RenderedSurface): string {
+  return `${surface.frameId}\u0000${surface.parentBackendNodeId ?? "root"}`;
+}
+
+function normalizedLimit(value: number | undefined, fallback: number): number {
+  const resolved = value ?? fallback;
+  return Number.isFinite(resolved) ? Math.max(0, Math.floor(resolved)) : fallback;
+}
+
+export function clusterRenderedSurfaces(
+  surfaces: RenderedSurface[],
+  options: ClusterRenderedSurfaceOptions = {},
+): ClusteredRenderedSurfaces {
+  const maxComparisons = normalizedLimit(options.maxComparisons, MAX_CLUSTER_COMPARISONS);
+  const maxSurfaces = normalizedLimit(options.maxSurfaces, MAX_CLUSTER_SURFACES);
+  const prioritized = selectHighestPriorityVisualSurfaces(surfaces, maxSurfaces);
+  const partitions = new Map<string, Map<string, Set<IndexedGroup>>>();
+  const groups: IndexedGroup[] = [];
+  let comparisons = 0;
+  let processed = 0;
+  let truncated = prioritized.length < surfaces.length;
+  let comparisonLimitReached = false;
+
+  for (const surface of prioritized) {
+    if (comparisons >= maxComparisons) {
+      truncated = true;
+      break;
+    }
+    const key = partitionKey(surface);
+    let index = partitions.get(key);
+    if (!index) {
+      index = new Map();
+      partitions.set(key, index);
+    }
+    const candidates = new Set<IndexedGroup>();
+    for (const candidateKey of candidateKeys(surface.visibleRect)) {
+      for (const candidate of index.get(candidateKey) ?? []) candidates.add(candidate);
+    }
+
+    let best: { group: IndexedGroup; score: number; areaDelta: number } | null = null;
+    for (const group of candidates) {
+      if (comparisons >= maxComparisons) {
+        truncated = true;
+        comparisonLimitReached = true;
+        break;
+      }
+      comparisons += 1;
+      const score = stackScore(group.representative, surface);
+      if (score === null) continue;
+      const areaDelta = Math.abs(
+        area(group.representative.visibleRect) - area(surface.visibleRect),
+      );
+      if (
+        !best ||
+        score > best.score ||
+        (score === best.score && areaDelta < best.areaDelta) ||
+        (score === best.score &&
+          areaDelta === best.areaDelta &&
+          group.creationIndex < best.group.creationIndex)
+      ) {
+        best = { group, score, areaDelta };
+      }
+    }
+    if (comparisonLimitReached) break;
+
+    if (best) {
+      const group = best.group;
+      const representative = preferredRepresentative(group.representative, surface);
+      group.memberCount += 1;
+      group.label ??= surface.label;
+      if (representative !== group.representative) {
+        index.get(group.indexKey)?.delete(group);
+        group.representative = representative;
+        group.indexKey = spatialKey(representative.visibleRect);
+        const indexed = index.get(group.indexKey) ?? new Set<IndexedGroup>();
+        indexed.add(group);
+        index.set(group.indexKey, indexed);
+      }
+      processed += 1;
+      continue;
+    }
+
+    const indexKey = spatialKey(surface.visibleRect);
+    const group: IndexedGroup = {
+      frameId: surface.frameId,
+      parentBackendNodeId: surface.parentBackendNodeId,
+      representative: surface,
+      ...(surface.label ? { label: surface.label } : {}),
+      memberCount: 1,
+      creationIndex: groups.length,
+      indexKey,
+    };
+    groups.push(group);
+    const indexed = index.get(indexKey) ?? new Set<IndexedGroup>();
+    indexed.add(group);
+    index.set(indexKey, indexed);
+    processed += 1;
+  }
+
+  return {
+    groups: groups
+      .map(({ creationIndex: _creationIndex, indexKey: _indexKey, ...group }) => group)
+      .sort(
+        (a, b) =>
+          a.frameId.localeCompare(b.frameId) ||
+          a.representative.visibleRect.y - b.representative.visibleRect.y ||
+          a.representative.visibleRect.x - b.representative.visibleRect.x,
+      ),
+    truncated,
+    ...(truncated ? { omittedCount: surfaces.length - processed } : {}),
+  };
+}

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

@@ -0,0 +1,113 @@
+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

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

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

@@ -0,0 +1,108 @@
+import type { VomScene, VomVisualSurface } from "@browser-skill/vom";
+import type { CapturedFrameDocument } from "../frame-capture";
+import type { SemanticAxNode } from "../semantic-graph";
+import type { ClusteredRenderedSurfaces, 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>[],
+  clustered: ClusteredRenderedSurfaces,
+): VomScene {
+  const index = buildProjectionIndex(scene, documents);
+  const visualSurfaces: VomVisualSurface[] = [];
+
+  for (const group of clustered.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.memberCount,
+    });
+  }
+
+  return {
+    ...scene,
+    ...(visualSurfaces.length > 0 ? { visualSurfaces } : {}),
+    ...(clustered.truncated
+      ? {
+          visualSurfacesTruncated: true,
+          ...(clustered.omittedCount !== undefined
+            ? { omittedVisualSurfaceCount: clustered.omittedCount }
+            : {}),
+        }
+      : {}),
+  };
+}

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

@@ -0,0 +1,25 @@
+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;
+  parentBackendNodeId: number | null;
+  representative: RenderedSurface;
+  label?: string;
+  memberCount: number;
+}
+
+export interface ClusteredRenderedSurfaces {
+  groups: RenderedSurfaceGroup[];
+  truncated: boolean;
+  omittedCount?: number;
+}

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

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

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

@@ -1,280 +0,0 @@
-import { type CdpFrame, type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
-import type { CapturedNode } from "./facts";
-import { captureCheckpoint, type DecodedDocument, type 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;
-  documentURL?: 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] ?? "";
-}
-
-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 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) await captureCheckpoint(signal);
-    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) await captureCheckpoint(signal);
-      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) await captureCheckpoint(signal);
-    const backendNodeId = dn.backendNodeId[n];
-    const parentIdx = dn.parentIndex?.[n] ?? -1;
-    const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
-    const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
-
-    const attrs: Record<string, string> = {};
-    const pairs = dn.attributes?.[n] ?? [];
-    for (let a = 0; a + 1 < pairs.length; a += 2) {
-      attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
-    }
-
-    const li = layoutByNode.get(n);
-    const styleRow = li === undefined ? [] : (dl?.styles?.[li] ?? []);
-    const styles: Record<string, string> = {};
-    for (const name of REQUESTED_STYLES) styles[name] = str(strings, styleRow[STYLE_COL[name]]);
-    const layout =
-      li === undefined
-        ? undefined
-        : {
-            boundsSpace: "snapshot-document-css" as const,
-            bounds: dl?.bounds?.[li],
-            styles,
-          };
-
-    const textContent = nodeTextContent.get(n)?.join(" ");
-
-    const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
-    const rawFormValue =
-      rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
-    const sensitive = isSensitiveFormControl({ tag, attrs });
-    const formDefaultValue = attrs.value ?? "";
-    const formValue = sensitive ? undefined : rawFormValue;
-    const formState = snapshotFormState(
-      rawFormValue,
-      formDefaultValue,
-      Object.prototype.hasOwnProperty.call(attrs, "value"),
-      sensitive,
-    );
-    if (sensitive) delete attrs.value;
-
-    nodes.push({
-      backendNodeId,
-      nodeType: dn.nodeType?.[n],
-      parentBackendNodeId,
-
-      tag,
-      attrs,
-      layout,
-      paintOrder: li === undefined ? 0 : (dl?.paintOrders?.[li] ?? 0),
-      position: styles.position || "static",
-      pointerEvents: styles["pointer-events"] || "auto",
-      cursor: styles.cursor || "auto",
-
-      textContent,
-      ...(formValue !== undefined ? { formValue } : {}),
-      ...(tag === "input" || tag === "textarea"
-        ? {
-            formPlaceholder: attrs.placeholder ?? "",
-            ...(!sensitive ? { formDefaultValue } : {}),
-            ...(formState ? { formState } : {}),
-          }
-        : {}),
-      ...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
-      ...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
-    });
-  }
-  return { nodes };
-}
-
-/** Snapshot membership and same-target edges are current response evidence.
- * The earlier graph only supplies compatible metadata and cross-target edges. */
-export function describeSnapshotFrames(
-  snapshot: SnapshotReply,
-  target: CdpTarget,
-  hintById: ReadonlyMap<string, CdpFrame>,
-  pageUrl?: string,
-): { frames: CdpFrame[]; ids: Set<string>; rootFrameId?: string } {
-  const raw = snapshot.documents ?? [];
-  const strings = snapshot.strings ?? [];
-  const ids = new Set<string>();
-  const invalid = new Set<string>();
-  const frames = raw.map((doc) => {
-    const frameId = snapshotFrameId(doc, strings);
-    if (!frameId) return undefined;
-    if (ids.has(frameId)) invalid.add(frameId);
-    ids.add(frameId);
-    const hint = hintById.get(frameId);
-    const compatible =
-      hint && cdpTargetKey(hint.target) === cdpTargetKey(target) ? hint : undefined;
-    const url =
-      (doc.documentURL === undefined ? undefined : strings[doc.documentURL]) || compatible?.url;
-    return { frameId, target, ...(url ? { url } : {}) } as CdpFrame;
-  });
-  const root = frames[0];
-  if (root) {
-    const hint = hintById.get(root.frameId);
-    const parent = hint?.parentFrameId ? hintById.get(hint.parentFrameId) : undefined;
-    if (
-      target.sessionId &&
-      hint &&
-      cdpTargetKey(hint.target) === cdpTargetKey(target) &&
-      parent &&
-      cdpTargetKey(parent.target) !== cdpTargetKey(target)
-    ) {
-      root.parentFrameId = parent.frameId;
-      root.ownerBackendNodeId = hint.ownerBackendNodeId;
-    }
-    if (!target.sessionId && !root.url && pageUrl) root.url = pageUrl;
-  }
-  const owned = new Set<string>();
-  for (let i = 0; i < raw.length; i++) {
-    const edges = raw[i].nodes?.contentDocumentIndex;
-    const parent = frames[i];
-    if (!parent || !edges) continue;
-    for (let e = 0; e < edges.index.length; e++) {
-      const child = frames[edges.value[e]];
-      const owner = raw[i].nodes?.backendNodeId?.[edges.index[e]];
-      if (!child || owner === undefined) continue;
-      if (child === root || child === parent || owned.has(child.frameId)) {
-        invalid.add(child.frameId);
-        continue;
-      }
-      owned.add(child.frameId);
-      child.parentFrameId = parent.frameId;
-      child.ownerBackendNodeId = owner;
-    }
-  }
-  return {
-    frames: frames.filter((frame): frame is CdpFrame => !!frame && !invalid.has(frame.frameId)),
-    ids,
-    rootFrameId: root?.frameId,
-  };
-}

apps/extension/src/transport/types.ts

@@ -23,6 +23,7 @@ export type ErrorCode =
 export type RpcErrorReason =
   | "agent_window_scope"
   | "element_not_visible"
+  | "ref_capability_denied"
   | "ref_not_found"
   | "selector_not_found"
   | "target_not_fillable"

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

@@ -0,0 +1,110 @@
+# 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.
+
+### `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.
+
+### `sparklines.html`
+
+Expected Surface labels `fixture-sparkline-01` through `fixture-sparkline-20` must all be present.
+The adjacent, non-overlapping canvases remain twenty independent screenshot-only Surface refs.
+
+## 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

@@ -0,0 +1,46 @@
+<!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

@@ -0,0 +1,28 @@
+<!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; }
+    </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("nested") === "1") {
+        const iframe = document.createElement("iframe");
+        iframe.title = "nested fixture frame";
+        iframe.src = "frame.html?label=fixture-nested-frame";
+        document.body.append(iframe);
+      }
+    </script>
+  </body>
+</html>

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

@@ -0,0 +1,22 @@
+<!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"></iframe>
+      <iframe title="cross-origin fixture" src="http://localhost:4173/frame.html?label=fixture-cross-origin-frame"></iframe>
+      <iframe title="nested fixture" src="frame.html?canvas=0&nested=1"></iframe>
+    </div>
+  </body>
+</html>

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

@@ -0,0 +1,118 @@
+<!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/sparklines.html

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Rendered Surface sparkline matrix</title>
+    <style>
+      html, body { margin: 0; font: 14px system-ui, sans-serif; }
+      body { padding: 16px; }
+      main { display: grid; grid-template-columns: repeat(5, 120px); gap: 12px; }
+      canvas { display: block; width: 100px; height: 30px; background: #eaf2f8; }
+    </style>
+  </head>
+  <body>
+    <h1>Twenty independent sparklines</h1>
+    <main id="sparklines"></main>
+    <script>
+      const host = document.querySelector("#sparklines");
+      for (let index = 1; index <= 20; index += 1) {
+        const canvas = document.createElement("canvas");
+        canvas.width = 100;
+        canvas.height = 30;
+        canvas.setAttribute("aria-label", `fixture-sparkline-${String(index).padStart(2, "0")}`);
+        host.append(canvas);
+      }
+    </script>
+  </body>
+</html>

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

@@ -0,0 +1,68 @@
+<!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

@@ -0,0 +1,22 @@
+<!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,6 +73,16 @@ 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 can actually
+inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop. 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. Do not pass a visual surface ref to click, fill, hover, or select;
+those commands intentionally reject screenshot-only refs.
+
 Escalate page reading only as needed:
 
 1. `bsk observe` for normal semantic understanding, text, controls, and refs.

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

@@ -40,6 +40,7 @@ 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";
@@ -299,6 +300,13 @@ 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 are screenshot-only; inspect `bsk screenshot --ref <ref> --session <id>` with image-understanding capability",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::InvalidParams, reason::TARGET_NOT_SELECT) => RenderInfo {
             summary: "target element is not a <select>",
             hint: Some(
@@ -564,6 +572,18 @@ 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("screenshot-only"),
+            "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 });

packages/dsh-plugin-browserskill/package.json

@@ -47,6 +47,7 @@
     "client": {
       "platform": "web",
       "inject": [
+        "@deepseek-ai/dsh-client-runtime",
         "@deepseek-ai/dsh-client-ui-tool",
         "@deepseek-ai/dsh-client-ui-layout"
       ],
@@ -68,6 +69,7 @@
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
     "@deepseek-ai/dsh-attachment": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-attachment": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.6",
@@ -80,6 +82,9 @@
     "@deepseek-ai/dsh-attachment": {
       "optional": true
     },
+    "@deepseek-ai/dsh-client-runtime": {
+      "optional": true
+    },
     "@deepseek-ai/dsh-client-ui-attachment": {
       "optional": true
     },

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

@@ -7,7 +7,6 @@
  */
 
 import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
-// Development-only types for the injected services; newer hosts no longer ship this package.
 import type { ClientContext, ISessions, SessionId } from "@deepseek-ai/dsh-client-runtime/client";
 // Type-only: pulls the 'shell.overlay' SlotMap merge into scope.
 import type {} from "@deepseek-ai/dsh-client-ui-layout/client";

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

@@ -489,7 +489,9 @@ 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. Read-only: never submits input.";
+        "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.";
     register(
       defineTool({
         name,
@@ -754,12 +756,17 @@ 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: "Snapshot ref (@e3) from the last snapshot/observe; crops to that element.",
+          description:
+            "Ref (@e3) from the last snapshot/observe; crops to that DOM element or visual surface.",
         },
       },
       output: {

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

@@ -25,6 +25,7 @@ const CLIENT_EXTERNALS: readonly string[] = [
   "@deepseek-ai/dsh-client-ui-primitives",
   "@deepseek-ai/dsh-client-ui-attachment",
   "@deepseek-ai/dsh-client-schema-form",
+  "@deepseek-ai/dsh-client-runtime/client",
 ];
 
 /** Wire/type layers with no shared runtime identity: safe to inline. */

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

@@ -29,6 +29,159 @@ 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; screenshot-only; requires=image-understanding]',
+    );
+    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; screenshot-only; requires=image-understanding]',
+    );
+    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("uses the appendix token budget 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(12);
+    expect(surfaceRefs[0]).toMatchObject({ backendNodeId: 111, name: "Important status" });
+    expect(out.truncated).toBe(false);
+  });
+
+  it("renders twenty independent sparklines without changing DOM refs", () => {
+    const input = scene([
+      node({ id: 1, role: "RootWebArea", frameId: "main" }),
+      node({ id: 2, parentId: 1, role: "button", name: "Submit", tag: "button" }),
+    ]);
+    input.visualSurfaces = Array.from({ length: 20 }, (_, index) => ({
+      parentId: 1,
+      backendNodeId: 100 + index,
+      frameId: "main",
+      renderingKind: "canvas" as const,
+      visibleRect: { x: index * 12, y: 20, w: 10, h: 8 },
+      memberCount: 1,
+    }));
+
+    const out = renderVom(input);
+
+    expect(out.refs[0]).toMatchObject({ ref: "e1", backendNodeId: 2, kind: "dom" });
+    expect(out.refs.filter((ref) => ref.kind === "surface")).toHaveLength(20);
+    expect(out.truncated).toBe(false);
+  });
+
+  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/__tests__/visual-surface-priority.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import {
+  compareVisualSurfacePriority,
+  selectHighestPriorityVisualSurfaces,
+} from "../visual-surface-priority";
+
+function surface(backendNodeId: number, area: number, label?: string) {
+  return {
+    backendNodeId,
+    frameId: "main",
+    visibleRect: { x: backendNodeId, y: 0, w: area, h: 1 },
+    ...(label ? { label } : {}),
+  };
+}
+
+describe("visual surface priority selection", () => {
+  it("matches a full priority sort when selecting a bounded prefix", () => {
+    const surfaces = Array.from({ length: 600 }, (_, index) => surface(index, index + 1));
+    surfaces[599] = surface(599, 1, "Important status");
+
+    const selected = selectHighestPriorityVisualSurfaces(surfaces, 512);
+    const expected = [...surfaces].sort(compareVisualSurfacePriority).slice(0, 512);
+
+    expect(selected).toEqual(expected);
+    expect(selected[0]?.backendNodeId).toBe(599);
+  });
+
+  it("normalizes empty, fractional, and unbounded limits", () => {
+    const surfaces = [surface(1, 1), surface(2, 2), surface(3, 3)];
+
+    expect(selectHighestPriorityVisualSurfaces(surfaces, 0)).toEqual([]);
+    expect(selectHighestPriorityVisualSurfaces(surfaces, 1.9)).toEqual([surface(3, 3)]);
+    expect(selectHighestPriorityVisualSurfaces(surfaces, Number.POSITIVE_INFINITY)).toHaveLength(3);
+  });
+});

packages/vom/src/index.ts

@@ -15,6 +15,13 @@ export type {
   VomNode,
   VomOptions,
   VomRef,
+  VomRefCapability,
   VomResult,
   VomScene,
+  VomVisualSurface,
 } from "./types";
+export {
+  compareVisualSurfacePriority,
+  selectHighestPriorityVisualSurfaces,
+  type VisualSurfacePriorityInput,
+} from "./visual-surface-priority";

packages/vom/src/render.ts

@@ -9,7 +9,9 @@ import type {
   VomOptions,
   VomResult,
   VomScene,
+  VomVisualSurface,
 } from "./types";
+import { selectHighestPriorityVisualSurfaces } from "./visual-surface-priority";
 
 const SKIP_ROLES = new Set(["generic", "none", "presentation", "inlinetextbox"]);
 
@@ -87,6 +89,8 @@ 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 DEFAULT_VISUAL_APPENDIX_TOKENS = 2_048;
+const MAX_VISUAL_SURFACE_REFS = 512;
 const MAX_SCOPE_LINES = 40;
 const RECOVERY_HANDLER_ATTRS = ["onclick", "onmousedown", "onkeydown", "onkeyup", "onkeypress"];
 const NATIVE_TAGS = new Set(["button", "input", "select", "textarea"]);
@@ -793,34 +797,117 @@ interface RenderState {
   duplicateRefNames: Set<string>;
   surfaceMap: Map<number, CondSurface>;
   scopeMap: Map<number, ActiveScopeBlock>;
+  visualSurfaces: VomVisualSurface[];
+  visualSurfacesTruncated: boolean;
+  omittedVisualSurfaceCount?: number;
+}
+
+function tryAppendLine(state: RenderState, line: string, tokenLimit = state.maxTokens): boolean {
+  const nextTokens = state.tokens + estimateTokens(line);
+  if (nextTokens > tokenLimit) return false;
+  state.lines.push(line);
+  state.tokens = nextTokens;
+  return true;
+}
+
+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; screenshot-only; requires=image-understanding]`;
+}
+
+function selectVisualSurfaces(
+  surfaces: readonly VomVisualSurface[],
+  nodesById: ReadonlyMap<number, VomNode>,
+): { selected: VomVisualSurface[]; eligibleCount: number } {
+  let eligibleCount = 0;
+  function* eligibleSurfaces(): Generator<VomVisualSurface> {
+    for (const surface of surfaces) {
+      if (surface.parentId !== null && !nodesById.has(surface.parentId)) continue;
+      eligibleCount += 1;
+      yield surface;
+    }
+  }
+  return {
+    selected: selectHighestPriorityVisualSurfaces(eligibleSurfaces(), MAX_VISUAL_SURFACE_REFS),
+    eligibleCount,
+  };
+}
+
+function emitVisualAppendix(state: RenderState): void {
+  if (state.stopped) return;
+  const { selected, eligibleCount } = selectVisualSurfaces(state.visualSurfaces, state.nodesById);
+  if (eligibleCount === 0 && !state.visualSurfacesTruncated) return;
+
+  const header = "[visual surfaces]";
+  const appendixStartTokens = state.tokens;
+  const appendixTokenLimit = Number.isFinite(state.maxTokens)
+    ? state.maxTokens
+    : appendixStartTokens + DEFAULT_VISUAL_APPENDIX_TOKENS;
+  let headerEmitted = false;
+  let emitted = 0;
+  for (const surface of selected) {
+    if (emitted >= MAX_VISUAL_SURFACE_REFS) break;
+    const ref = `e${state.nextRef}`;
+    const line = visualSurfaceLine(surface, ref);
+    const requiredTokens = estimateTokens(line) + (headerEmitted ? 0 : estimateTokens(header));
+    if (state.tokens + requiredTokens > appendixTokenLimit) break;
+    if (!headerEmitted) {
+      if (!tryAppendLine(state, header, appendixTokenLimit)) break;
+      headerEmitted = true;
+    }
+    if (!tryAppendLine(state, line, appendixTokenLimit)) break;
+    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 locallyOmitted = eligibleCount - emitted;
+  const upstreamOmitted = state.omittedVisualSurfaceCount ?? 0;
+  const omitted = locallyOmitted + upstreamOmitted;
+  if (omitted > 0 || state.visualSurfacesTruncated) {
+    state.truncated = true;
+    if (headerEmitted) {
+      const count =
+        omitted > 0 ? `${state.visualSurfacesTruncated ? "at least " : ""}${omitted}` : "some";
+      tryAppendLine(state, `  … ${count} additional visual surfaces omitted`, appendixTokenLimit);
+    }
+  }
 }
 
 function emitActiveScopeBlock(scope: ActiveScopeBlock, depth: number, state: RenderState): void {
   if (state.stopped || scope.lines.length === 0) return;
   const indent = "  ".repeat(depth);
   const header = `${indent}[§ active: ${scope.label}]`;
-  const headerTokens = estimateTokens(header);
-  if (state.tokens + headerTokens > state.maxTokens) {
+  if (!tryAppendLine(state, header)) {
     state.truncated = true;
     state.stopped = true;
     return;
   }
-  state.lines.push(header);
-  state.tokens += headerTokens;
 
   for (const text of scope.lines.slice(0, MAX_SCOPE_LINES)) {
     if (state.stopped) return;
     const clean = cleaned(text);
     if (!clean) continue;
     const line = `${indent}  ${clean}`;
-    const nextTokens = state.tokens + estimateTokens(line);
-    if (nextTokens > state.maxTokens) {
+    if (!tryAppendLine(state, line)) {
       state.truncated = true;
       state.stopped = true;
       return;
     }
-    state.lines.push(line);
-    state.tokens = nextTokens;
   }
 }
 
@@ -855,15 +942,11 @@ function renderTree(children: Map<number | null, VomNode[]>, state: RenderState)
     const context = ref ? handleContext(node, state) : [];
     const surface = state.surfaceMap.get(node.id);
     const line = renderNodeLine(node, depth, ref, context, surface, state.redactValues);
-    const nextTokens = state.tokens + estimateTokens(line);
-    if (nextTokens > state.maxTokens) {
+    if (!tryAppendLine(state, line)) {
       state.truncated = true;
       state.stopped = true;
       break;
     }
-
-    state.lines.push(line);
-    state.tokens = nextTokens;
     if (ref) {
       const name = cleaned(node.name);
       state.refs.push({
@@ -873,6 +956,8 @@ 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;
@@ -894,6 +979,9 @@ function renderNodes(
   initialLines: string[],
   surfaces: CondSurface[] = [],
   activeScopeBlocks: ActiveScopeBlock[] = [],
+  visualSurfaces: VomVisualSurface[] = [],
+  visualSurfacesTruncated = false,
+  omittedVisualSurfaceCount?: number,
 ): RenderState {
   const children = buildChildren(nodes);
   const state: RenderState = {
@@ -913,6 +1001,9 @@ function renderNodes(
     duplicateRefNames: duplicateReferenceNames(nodes),
     surfaceMap: new Map(surfaces.map((surface) => [surface.triggerId, surface])),
     scopeMap: new Map(activeScopeBlocks.map((scope) => [scope.triggerId, scope])),
+    visualSurfaces,
+    visualSurfacesTruncated,
+    omittedVisualSurfaceCount,
   };
 
   renderTree(children, state);
@@ -1124,8 +1215,21 @@ function renderDoubleLayer(scene: VomScene, layer: BlockingLayer, options: VomOp
     "@layers 2 focus=L1",
     `L1 ${layer.kind} cover=${Math.round(layer.coverage * 100)}%`,
   ];
-  const state = renderNodes(visibleNodes, options, header, scene.surfaces, scene.activeScopeBlocks);
-  state.lines.push(renderPageOcclusionLine(hiddenCount));
+  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)),
+    scene.visualSurfacesTruncated,
+    scene.omittedVisualSurfaceCount,
+  );
+  const occlusionLine = renderPageOcclusionLine(hiddenCount);
+  if (!tryAppendLine(state, occlusionLine)) state.truncated = true;
+  emitVisualAppendix(state);
 
   return {
     text: state.lines.join("\n"),
@@ -1152,7 +1256,11 @@ export function renderVom(scene: VomScene, options: VomOptions = {}): VomResult
     ],
     scene.surfaces,
     scene.activeScopeBlocks,
+    scene.visualSurfaces,
+    scene.visualSurfacesTruncated,
+    scene.omittedVisualSurfaceCount,
   );
+  emitVisualAppendix(state);
 
   return {
     text: state.lines.join("\n"),

packages/vom/src/types.ts

@@ -61,6 +61,12 @@ export interface VomScene {
   rootFrameId?: string;
   surfaces?: CondSurface[];
   activeScopeBlocks?: ActiveScopeBlock[];
+  /** Non-semantic rendered regions discovered alongside the AX/DOM tree. */
+  visualSurfaces?: VomVisualSurface[];
+  /** Upstream surface discovery/aggregation stopped at a resource guardrail. */
+  visualSurfacesTruncated?: boolean;
+  /** Exact omitted count when upstream could determine it. */
+  omittedVisualSurfaceCount?: number;
 }
 
 export interface VomOptions {
@@ -94,6 +100,22 @@ 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 {

packages/vom/src/visual-surface-priority.ts

@@ -0,0 +1,80 @@
+export interface VisualSurfacePriorityInput {
+  label?: string;
+  visibleRect: { x: number; y: number; w: number; h: number };
+  frameId: string;
+  backendNodeId: number;
+}
+
+function hasLabel(label: string | undefined): boolean {
+  return (label?.trim().length ?? 0) > 0;
+}
+
+function area(surface: VisualSurfacePriorityInput): number {
+  return Math.max(0, surface.visibleRect.w) * Math.max(0, surface.visibleRect.h);
+}
+
+/** Negative means `a` should be emitted before `b`. */
+export function compareVisualSurfacePriority(
+  a: VisualSurfacePriorityInput,
+  b: VisualSurfacePriorityInput,
+): number {
+  return (
+    Number(hasLabel(b.label)) - Number(hasLabel(a.label)) ||
+    area(b) - area(a) ||
+    a.frameId.localeCompare(b.frameId) ||
+    a.visibleRect.y - b.visibleRect.y ||
+    a.visibleRect.x - b.visibleRect.x ||
+    a.backendNodeId - b.backendNodeId
+  );
+}
+
+function siftWorstUp<T extends VisualSurfacePriorityInput>(heap: T[], start: number): void {
+  let index = start;
+  while (index > 0) {
+    const parent = Math.floor((index - 1) / 2);
+    if (compareVisualSurfacePriority(heap[index], heap[parent]) <= 0) break;
+    [heap[index], heap[parent]] = [heap[parent], heap[index]];
+    index = parent;
+  }
+}
+
+function siftWorstDown<T extends VisualSurfacePriorityInput>(heap: T[], start: number): void {
+  let index = start;
+  while (true) {
+    const left = index * 2 + 1;
+    if (left >= heap.length) return;
+    const right = left + 1;
+    let worst = left;
+    if (right < heap.length && compareVisualSurfacePriority(heap[right], heap[left]) > 0) {
+      worst = right;
+    }
+    if (compareVisualSurfacePriority(heap[worst], heap[index]) <= 0) return;
+    [heap[index], heap[worst]] = [heap[worst], heap[index]];
+    index = worst;
+  }
+}
+
+/** Selects the best `limit` surfaces and returns them in priority order. */
+export function selectHighestPriorityVisualSurfaces<T extends VisualSurfacePriorityInput>(
+  surfaces: Iterable<T>,
+  limit: number,
+): T[] {
+  if (!Number.isFinite(limit)) return [...surfaces].sort(compareVisualSurfacePriority);
+  const normalizedLimit = Math.max(0, Math.floor(limit));
+  if (normalizedLimit === 0) return [];
+  if (Array.isArray(surfaces) && surfaces.length <= normalizedLimit) {
+    return [...surfaces].sort(compareVisualSurfacePriority);
+  }
+
+  const heap: T[] = [];
+  for (const surface of surfaces) {
+    if (heap.length < normalizedLimit) {
+      heap.push(surface);
+      siftWorstUp(heap, heap.length - 1);
+    } else if (compareVisualSurfacePriority(surface, heap[0]) < 0) {
+      heap[0] = surface;
+      siftWorstDown(heap, 0);
+    }
+  }
+  return heap.sort(compareVisualSurfacePriority);
+}

skill/SKILL.md

@@ -73,6 +73,16 @@ 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 can actually
+inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop. 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. Do not pass a visual surface ref to click, fill, hover, or select;
+those commands intentionally reject screenshot-only refs.
+
 Escalate page reading only as needed:
 
 1. `bsk observe` for normal semantic understanding, text, controls, and refs.