fix: bugfix CI

feat: support on-demand screenshots for canvas visual refs
feat(vom): add typed visual refs and target identity validation
2026-09-10 13:01:23 +08:00 · 2026-09-10 12:23:18 +08:00 · 2026-09-10 12:21:20 +08:00 · 2026-09-10 12:21:20 +08:00 · 2026-09-10 12:21:19 +08:00 · 2026-09-10 12:21:19 +08:00
26 changed files with 3309 additions and 113 deletions
@@ -1,19 +1,11 @@
-/**
- * Per-session map from `@e<N>` snapshot refs to a CDP node address.
- *
- * Each fresh `tool.snapshot` resets the store: M6 will call
- * `replace(...)` with the new ref → node address pairs. A node address
- * includes the owning flat CDP session/frame when the element lives in
- * an OOPIF; tools resolve live geometry from that identity at call time.
- *
- * Refs are session-scoped (§7): looking up a ref in the wrong session
- * returns `null`, never silently leaks. Storing values in different
- * sessions is fine; they live in independent `RefStore` instances
- * inside the `SessionContext`.
- */
+import type { VisualCandidate } from "@/tools/vom/visual-discovery";
+
+/** Session-local refs describe the latest observation. Reusing eN does not identify
+ * which observation a caller read; generation is internal bookkeeping only. */
 export type BackendNodeId = number;

-export interface RefEntry {
+export interface DomRefEntry {
+  readonly kind: "dom";
  backendNodeId: BackendNodeId;
  tabId: number | null;
  frameId?: string;
@@ -21,7 +13,15 @@ export interface RefEntry {
  generation: number;
 }

+export interface VisualRefInput {
+  readonly kind: "visual-region";
+  readonly candidate: VisualCandidate;
+}
+
+export type RefEntry = DomRefEntry | (VisualRefInput & { readonly generation: number });
+
 export type RefInput =
+  | VisualRefInput
  | BackendNodeId
  | {
      backendNodeId: BackendNodeId;
@@ -31,7 +31,7 @@ export type RefInput =
    };

 export class RefStore {
-  private readonly map = new Map<string, RefEntry>();
+  private map = new Map<string, RefEntry>();
  private generation = 0;

  size(): number {
@@ -44,7 +44,7 @@ export class RefStore {

  resolve(ref: string, opts: { tabId?: number } = {}): BackendNodeId | null {
    const entry = this.map.get(normaliseRef(ref));
-    if (!entry) return null;
+    if (!entry || entry.kind !== "dom") return null;
    if (opts.tabId !== undefined && entry.tabId !== opts.tabId) return null;
    return entry.backendNodeId;
  }
@@ -58,9 +58,11 @@ export class RefStore {
   * Used after every fresh `tool.snapshot`.
   */
  replace(entries: Iterable<readonly [string, RefInput]>): void {
-    this.map.clear();
-    this.generation += 1;
-    for (const [ref, input] of entries) this.map.set(normaliseRef(ref), this.entry(input));
+    const generation = this.generation + 1;
+    const next = new Map<string, RefEntry>();
+    for (const [ref, input] of entries) next.set(normaliseRef(ref), this.entry(input, generation));
+    this.map = next;
+    this.generation = generation;
  }

  set(
@@ -73,6 +75,7 @@ export class RefStore {
    } = {},
  ): void {
    this.map.set(normaliseRef(ref), {
+      kind: "dom",
      backendNodeId: id,
      tabId: opts.tabId ?? null,
      ...(opts.frameId ? { frameId: opts.frameId } : {}),
@@ -89,20 +92,37 @@ export class RefStore {
    return this.map.entries();
  }

-  private entry(input: RefInput): RefEntry {
+  private entry(input: RefInput, generation: number): RefEntry {
+    if (typeof input !== "number" && "kind" in input) {
+      const { document } = input.candidate;
+      if (
+        !document?.attachmentId ||
+        !document.frameId ||
+        !Number.isSafeInteger(document.target?.tabId) ||
+        !Number.isSafeInteger(document.documentElementBackendNodeId) ||
+        document.documentElementBackendNodeId <= 0 ||
+        !Number.isSafeInteger(input.candidate.backendNodeId) ||
+        input.candidate.backendNodeId <= 0
+      )
+        throw new TypeError("visual ref requires a verified DOM identity and anchor");
+      // Preserve the read-only evidence and shared clipping chain; do not clone ancestors per ref.
+      return { kind: "visual-region", candidate: input.candidate, generation };
+    }
    if (typeof input === "number") {
      return {
+        kind: "dom",
        backendNodeId: input,
        tabId: null,
-        generation: this.generation,
+        generation,
      };
    }
    return {
+      kind: "dom",
      backendNodeId: input.backendNodeId,
      tabId: input.tabId,
      ...(input.frameId ? { frameId: input.frameId } : {}),
      ...(input.cdpSessionId ? { cdpSessionId: input.cdpSessionId } : {}),
-      generation: this.generation,
+      generation,
    };
  }
 }
@@ -405,6 +405,7 @@ describe("handleRequestHelp", () => {
              agentWindowId: 99,
              refStore: {
                resolveEntry: () => ({
+                  kind: "dom",
                  backendNodeId: 42,
                  tabId: 5,
                  frameId: "child",
@@ -3813,7 +3813,9 @@ describe("handleSnapshot", () => {

    if ("code" in result) throw new Error(`unexpected error: ${JSON.stringify(result)}`);
    expect(result.text).toContain('@e1 button "Frame action"');
-    const frameRef = [...ctx.refStore.entries()].find(([, entry]) => entry.backendNodeId === 22);
+    const frameRef = [...ctx.refStore.entries()].find(
+      ([, entry]) => entry.kind === "dom" && entry.backendNodeId === 22,
+    );
    expect(frameRef?.[1]).toMatchObject({
      tabId: 4,
      frameId: "child",
@@ -0,0 +1,199 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import { RefStore, type VisualRefInput } from "@/session-manager/ref-store";
+import { handleDownload } from "../download";
+import { handleRequestHelp, resetHelpLifecycleForTests } from "../human-loop";
+import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "../interaction";
+import { handleGetHtml } from "../observation";
+import type { CdpRunner } from "../shared";
+import { lookupRefTarget, lookupSnapshotRef, resolveSnapshotRef } from "../snapshot-ref";
+import { handleUpload } from "../upload";
+
+function visual(): VisualRefInput {
+  return {
+    kind: "visual-region",
+    candidate: {
+      document: {
+        attachmentId: "a",
+        target: { tabId: 4, sessionId: "child" },
+        frameId: "frame",
+        documentElementBackendNodeId: 1,
+      },
+      backendNodeId: 42,
+      parentBackendNodeId: 1,
+      region: {
+        status: "available",
+        borderBox: { x: 0, y: 0, width: 100, height: 50 },
+        crop: { x: 0, y: 0, width: 100, height: 50 },
+      },
+    },
+  };
+}
+
+async function setup() {
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("test");
+  ctx.refStore.replace([
+    ["e1", visual()],
+    ["e2", { backendNodeId: 43, tabId: 4 }],
+  ]);
+  const send = vi.fn(async () => {
+    throw new Error("unexpected target operation");
+  });
+  const cdp = { send, sendToTarget: send, trackSessionTab: vi.fn() } as unknown as CdpRunner;
+  const tab = { id: 4, windowId: 100, active: true, url: "https://example.com" } as chrome.tabs.Tab;
+  const tabsApi = { get: vi.fn(async () => tab), query: vi.fn(async () => [tab]) };
+  return { manager, ctx, send, cdp, tabsApi };
+}
+
+describe("typed visual refs", () => {
+  afterEach(() => resetHelpLifecycleForTests());
+
+  it("keeps candidate evidence and cannot resolve a visual anchor as a bare DOM node", () => {
+    const store = new RefStore();
+    const input = visual();
+    store.replace([
+      ["@e1", input],
+      ["e2", { backendNodeId: 43, tabId: 4 }],
+    ]);
+    const entry = store.resolveEntry("e1");
+    expect(entry?.kind).toBe("visual-region");
+    if (entry?.kind !== "visual-region") throw new Error("missing visual ref");
+    expect(entry.candidate).toBe(input.candidate);
+    expect(entry.generation).toBe(1);
+    expect(store.resolve("@e1")).toBeNull();
+    expect(store.resolve("e2")).toBe(43);
+    // The latest observation replaces both target kinds; eN strings carry no generation.
+    store.replace([["e1", { backendNodeId: 99, tabId: 4 }]]);
+    expect(store.resolve("e1")).toBe(99);
+    expect(store.resolveEntry("e1")).toMatchObject({ kind: "dom", generation: 2 });
+    expect(store.resolveEntry("e2")).toBeNull();
+  });
+
+  it("rejects missing visual identity without partially publishing a replacement", () => {
+    const store = new RefStore();
+    store.set("e1", 10, { tabId: 4 });
+    const invalid = visual();
+    invalid.candidate.document.attachmentId = "";
+    expect(() =>
+      store.replace([
+        ["e2", 20],
+        ["e3", invalid],
+      ]),
+    ).toThrow(TypeError);
+    expect(store.resolveEntry("e1")).toMatchObject({ generation: 0, backendNodeId: 10 });
+    expect(store.size()).toBe(1);
+    store.replace([["e1", visual()]]);
+    expect(store.resolveEntry("e1")?.generation).toBe(1);
+  });
+
+  it("isolates tabs/sessions and distinguishes unsupported targets from missing refs", async () => {
+    const { ctx } = await setup();
+    expect(lookupRefTarget(ctx, "@e1", 4)?.kind).toBe("visual-region");
+    expect(lookupRefTarget(ctx, "e1", 5)).toBeNull();
+    expect(lookupSnapshotRef(ctx, "e1", 4)).toBeNull();
+    expect(resolveSnapshotRef(ctx, "e1", 4)).toMatchObject({
+      code: "unsupported",
+      data: { reason: "ref_kind_unsupported" },
+    });
+    expect(resolveSnapshotRef(ctx, "e1", 5)).toMatchObject({
+      code: "not_found",
+      data: { reason: "ref_not_found" },
+    });
+    expect(lookupRefTarget({ ...ctx, refStore: new RefStore() }, "e1", 4)).toBeNull();
+    expect(lookupSnapshotRef(ctx, "e2", 4)).toMatchObject({ backendNodeId: 43 });
+  });
+
+  it.each([
+    "click",
+    "fill",
+    "hover",
+    "press",
+    "select",
+    "get_html",
+  ])("rejects visual refs in %s before target effects", async (tool) => {
+    const { manager, send, cdp, tabsApi } = await setup();
+    const params = { session_id: "test", tab_id: 4, ref: "@e1" };
+    const deps = { cdp, tabsApi };
+    let result: unknown;
+    switch (tool) {
+      case "click":
+        result = await handleClick(manager, params, deps);
+        break;
+      case "fill":
+        result = await handleFill(manager, { ...params, value: "hello" }, deps);
+        break;
+      case "hover":
+        result = await handleHover(manager, params, deps);
+        break;
+      case "press":
+        result = await handlePress(manager, { ...params, key: "Enter" }, deps);
+        break;
+      case "select":
+        result = await handleSelect(manager, { ...params, values: ["one"] }, deps);
+        break;
+      case "get_html":
+        result = await handleGetHtml(manager, params, deps);
+        break;
+    }
+    expect(result).toMatchObject({ code: "unsupported", data: { reason: "ref_kind_unsupported" } });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "input",
+    "drop",
+    "download",
+  ] as const)("rejects visual refs before %s file-transfer setup", async (mode) => {
+    const { manager, send, cdp, tabsApi } = await setup();
+    const params = { session_id: "test", tab_id: 4, ref: "e1" };
+    const result =
+      mode === "download"
+        ? await handleDownload(
+            manager,
+            { ...params, browser_relative_dir: "test" },
+            { cdp, tabsApi },
+          )
+        : await handleUpload(
+            manager,
+            {
+              ...params,
+              mode,
+              files: [{ transfer_id: "test", name: "test.txt", staged_path: "/unused/test.txt" }],
+            },
+            { cdp, tabsApi },
+          );
+    expect(result).toMatchObject({ code: "unsupported", data: { reason: "ref_kind_unsupported" } });
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it("does not scroll or highlight a visual anchor in human help", async () => {
+    const { manager, cdp, tabsApi, send } = await setup();
+    const sendToTab = vi.fn(async (_tab: number, _message: unknown) => ({
+      type: "bsk-help-response",
+      outcome: "continued",
+    }));
+    const result = await handleRequestHelp(
+      manager,
+      { session_id: "test", tab_id: 4, prompt: "help", targets: [{ ref: "@e1" }] },
+      {
+        cdp,
+        tabsApi,
+        sendToTab,
+        windows: { update: vi.fn(async () => ({}) as never) },
+        activateTab: vi.fn(async () => {}),
+        notifications: null,
+        autoAttachLifecycle: false,
+      },
+    );
+    expect(result).toMatchObject({ resolved_targets: [{ ref: "@e1", matched: false }] });
+    expect(send).not.toHaveBeenCalled();
+    expect(sendToTab.mock.calls[0][1]).toMatchObject({ rects: [], selectors: [] });
+  });
+});
@@ -0,0 +1,382 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import { SessionManager } from "@/session-manager/manager";
+import { handleScreenshot } from "../observation";
+import type { CdpRunner } from "../shared";
+import { captureVisualScreenshot, visualScreenshotScale } from "../visual-screenshot";
+import type { VisualCandidate, VisualFramePath } from "../vom/visual-discovery";
+
+const styles = {
+  position: "static",
+  visibility: "visible",
+  opacity: "1",
+  display: "block",
+  "overflow-x": "visible",
+  "overflow-y": "visible",
+  transform: "none",
+  zoom: "1",
+  "clip-path": "none",
+  "mask-image": "none",
+  rotate: "none",
+  scale: "none",
+  perspective: "none",
+  clip: "auto",
+  contain: "none",
+  "overflow-clip-margin": "0px",
+};
+const rect = (x = 10, y = 20, width = 100, height = 40) => ({ x, y, width, height });
+const root = {
+  attachmentId: "a",
+  target: { tabId: 4 },
+  frameId: "top",
+  documentElementBackendNodeId: 1,
+};
+function row(id: number, tag: string, box = rect()) {
+  return {
+    node: { backend: id },
+    tag,
+    box,
+    client: box,
+    contentSize: { width: box.width, height: box.height },
+    styles: { ...styles },
+  };
+}
+function encode(value: unknown): unknown {
+  if (value === null) return { type: "null" };
+  if (Array.isArray(value)) return { type: "array", value: value.map(encode) };
+  if (typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    if ("backend" in record) return { type: "node", value: { backendNodeId: record.backend } };
+    return { type: "object", value: Object.entries(record).map(([k, v]) => [k, encode(v)]) };
+  }
+  return { type: typeof value, value };
+}
+function png(width: number, height: number) {
+  const bytes = new Uint8Array(33);
+  bytes.set([137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82]);
+  const view = new DataView(bytes.buffer);
+  view.setUint32(16, width);
+  view.setUint32(20, height);
+  return btoa(String.fromCharCode(...bytes));
+}
+function fixture(child = false, oopif = false) {
+  const parent: VisualFramePath = { document: root };
+  const frame: VisualFramePath = child
+    ? {
+        document: {
+          ...root,
+          frameId: "child",
+          documentElementBackendNodeId: 11,
+          target: oopif ? { tabId: 4, sessionId: "oopif" } : { tabId: 4 },
+        },
+        parent: { frame: parent, ownerBackendNodeId: 2 },
+      }
+    : parent;
+  const crop = child ? rect(120, 240, 200, 80) : rect();
+  const candidate: VisualCandidate = {
+    document: frame.document,
+    backendNodeId: child ? 12 : 3,
+    parentBackendNodeId: frame.document.documentElementBackendNodeId,
+    framePath: frame,
+    region: { status: "available", borderBox: crop, crop },
+  };
+  const topRows = child
+    ? [row(2, "iframe", rect(100, 200, 400, 200)), row(1, "html", rect(0, 0, 1200, 800))]
+    : [row(3, "canvas"), row(1, "html", rect(0, 0, 1200, 800))];
+  if (child) topRows[0].contentSize = { width: 200, height: 100 };
+  const childRows = [row(12, "canvas"), row(11, "html", rect(0, 0, 200, 100))];
+  let calls = 0;
+  const control = {
+    wrongOwner: false,
+    rootChanged: false,
+    failRead: false,
+    abortRead: false,
+    dpr: 1,
+    shots: [png(crop.width, crop.height)],
+  };
+  const controller = new AbortController();
+  const send = vi.fn(
+    async (target: CdpTarget, method: string, params: Record<string, unknown> = {}) => {
+      if (method === "DOM.getFrameOwner") return { backendNodeId: control.wrongOwner ? 999 : 2 };
+      if (method === "Page.createIsolatedWorld")
+        return { executionContextId: params.frameId === "child" ? 11 : 1 };
+      if (method === "DOM.resolveNode")
+        return { object: { objectId: String(params.backendNodeId) } };
+      if (method === "Runtime.callFunctionOn") {
+        const isChild = params.objectId === "12";
+        if (!(params.functionDeclaration as string).includes("styleNames"))
+          return {
+            result: {
+              deepSerializedValue: {
+                type: "node",
+                value: { backendNodeId: control.rootChanged ? 999 : isChild ? 11 : 1 },
+              },
+            },
+          };
+        if (control.failRead) throw new Error("read failed");
+        if (control.abortRead) controller.abort();
+        return {
+          result: {
+            deepSerializedValue: encode({
+              top: !isChild,
+              dpr: control.dpr,
+              rows: isChild ? childRows : topRows,
+            }),
+          },
+        };
+      }
+      if (method === "Runtime.releaseObjectGroup") return {};
+      // OOPIF projection uses the full viewport for scale, independently of
+      // the scrollbar-excluding layout viewport used for clipping.
+      if (method === "Runtime.evaluate" && target.sessionId === "oopif") {
+        expect(params).toMatchObject({
+          expression: "({ width: window.innerWidth, height: window.innerHeight })",
+          returnByValue: true,
+        });
+        return { result: { value: { width: 200, height: 100 } } };
+      }
+      if (method === "Page.getLayoutMetrics")
+        return {
+          cssLayoutViewport: { clientWidth: 1200, clientHeight: 800, pageX: 0, pageY: 0 },
+          cssVisualViewport: { scale: 1, zoom: 1 },
+        };
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [100, 200, 500, 200, 500, 400, 100, 400] } };
+      if (method === "Page.captureScreenshot")
+        return { data: control.shots[Math.min(calls++, control.shots.length - 1)] };
+      throw new Error(`unexpected ${method} ${target.sessionId}`);
+    },
+  );
+  const cdp = {
+    send: ((tabId, method, params) =>
+      send({ tabId }, method, params as Record<string, unknown>)) as CdpRunner["send"],
+    sendToTarget: send as unknown as CdpRunner["sendToTarget"],
+    getAttachmentId: () => "a",
+    getFrameGraph: vi.fn(async () => {
+      throw new Error("whole page discovery forbidden");
+    }),
+  };
+  return { candidate, cdp, send, control, controller, topRows, childRows };
+}
+
+describe("visual screenshot", () => {
+  it.each([
+    [false, false],
+    [true, false],
+    [true, true],
+  ])("screenshots the local target child=%s oopif=%s without whole-page discovery", async (child, oopif) => {
+    const f = fixture(child, oopif);
+    const result = await captureVisualScreenshot(f.cdp, f.candidate);
+    expect(result).toMatchObject({ width: child ? 200 : 100, height: child ? 80 : 40 });
+    expect(f.cdp.getFrameGraph).not.toHaveBeenCalled();
+    const names = f.send.mock.calls.map((c) => c[1]);
+    expect(names.filter((n) => n === "DOM.getFrameOwner")).toHaveLength(child ? 1 : 0);
+    expect(names.filter((n) => n === "DOM.resolveNode")).toHaveLength(child ? 2 : 1);
+    expect(names.some((n) => /scroll|DOMSnapshot|getFrameTree|Accessibility/.test(n))).toBe(false);
+    expect(f.send.mock.calls.find((c) => c[1] === "Page.captureScreenshot")?.[2]).toMatchObject({
+      clip: { ...f.candidate.region.crop, scale: 1 },
+    });
+  });
+  it.each([
+    false,
+    true,
+  ])("projects a nested child through a parent target oopif=%s", async (oopif) => {
+    const f = fixture(true, oopif);
+    const parent = f.candidate.framePath!;
+    const document = {
+      ...parent.document,
+      frameId: "grandchild",
+      documentElementBackendNodeId: 21,
+    };
+    const crop = rect(130, 250, 40, 20);
+    const candidate: VisualCandidate = {
+      ...f.candidate,
+      document,
+      backendNodeId: 22,
+      framePath: { document, parent: { frame: parent, ownerBackendNodeId: 12 } },
+      region: { status: "available", borderBox: crop, crop },
+    };
+    f.childRows[0].tag = "iframe";
+    f.control.shots = [png(40, 20)];
+    const original = f.send.getMockImplementation()!;
+    f.send.mockImplementation(async (target, method, params = {}) => {
+      if (method === "DOM.getFrameOwner" && params.frameId === "grandchild")
+        return { backendNodeId: 12 };
+      if (method === "Runtime.callFunctionOn" && params.objectId === "22") {
+        if (!(params.functionDeclaration as string).includes("styleNames"))
+          return {
+            result: { deepSerializedValue: { type: "node", value: { backendNodeId: 21 } } },
+          };
+        return {
+          result: {
+            deepSerializedValue: encode({
+              top: false,
+              dpr: 1,
+              rows: [row(22, "canvas", rect(5, 5, 20, 10)), row(21, "html", rect(0, 0, 100, 40))],
+            }),
+          },
+        };
+      }
+      if (method === "DOM.getBoxModel" && params.backendNodeId === 12)
+        return {
+          model: {
+            content: oopif
+              ? [10, 20, 110, 20, 110, 60, 10, 60]
+              : [120, 240, 320, 240, 320, 320, 120, 320],
+          },
+        };
+      if (method === "Page.getLayoutMetrics" && target.sessionId)
+        return {
+          cssLayoutViewport: { clientWidth: 200, clientHeight: 100, pageX: 0, pageY: 0 },
+          cssVisualViewport: { scale: 1, zoom: 1 },
+        };
+      return original(target, method, params);
+    });
+    expect(await captureVisualScreenshot(f.cdp, candidate)).toMatchObject({
+      width: 40,
+      height: 20,
+    });
+    expect(f.send.mock.calls.filter((c) => c[1] === "DOM.getFrameOwner")).toHaveLength(2);
+    expect(f.send.mock.calls.find((c) => c[1] === "Page.captureScreenshot")?.[2]).toMatchObject({
+      clip: crop,
+    });
+    expect(f.cdp.getFrameGraph).not.toHaveBeenCalled();
+  });
+
+  it("runs the live reader on only connected local ancestry", async () => {
+    const f = fixture();
+    await captureVisualScreenshot(f.cdp, f.candidate);
+    const params = f.send.mock.calls.find(
+      (c) =>
+        c[1] === "Runtime.callFunctionOn" &&
+        String(c[2]?.functionDeclaration).includes("styleNames"),
+    )![2]!;
+    const read = new Function(`return (${params.functionDeclaration});`)() as (
+      this: Element,
+      names: string[],
+    ) => { rows: { node: Element }[] } | null;
+    const canvas = document.createElement("canvas");
+    document.body.append(canvas);
+    try {
+      const result = read.call(canvas, ["display"]);
+      expect(result?.rows.map((row) => row.node)).toEqual([
+        canvas,
+        document.body,
+        document.documentElement,
+      ]);
+      canvas.remove();
+      expect(read.call(canvas, ["display"])).toBeNull();
+      const other = document.implementation.createHTMLDocument();
+      const foreign = other.createElement("canvas");
+      other.body.append(foreign);
+      expect(foreign.ownerDocument).toBe(other);
+      expect(read.call(foreign, ["display"])).toBeNull();
+    } finally {
+      canvas.remove();
+    }
+  });
+
+  it("keeps requests constant as ordinary ancestry grows", async () => {
+    const small = fixture(),
+      large = fixture();
+    large.topRows.splice(
+      1,
+      0,
+      ...Array.from({ length: 100 }, (_, i) => row(100 + i, "div", rect(0, 0, 1200, 800))),
+    );
+    await captureVisualScreenshot(small.cdp, small.candidate);
+    await captureVisualScreenshot(large.cdp, large.candidate);
+    expect(large.send.mock.calls.map((c) => c[1])).toEqual(small.send.mock.calls.map((c) => c[1]));
+  });
+  it("preserves missing-path candidates but cannot execute them", async () => {
+    const f = fixture();
+    const { framePath: _, ...candidate } = f.candidate;
+    expect(await captureVisualScreenshot(f.cdp, candidate)).toMatchObject({
+      data: { reason: "visual_target_changed" },
+    });
+    expect(f.send).not.toHaveBeenCalled();
+  });
+  it.each([0.249, 0.25, 0.251])("compares rectangle edges with tolerance %s", async (delta) => {
+    const f = fixture();
+    f.topRows[0].box.x += delta;
+    const result = await captureVisualScreenshot(f.cdp, f.candidate);
+    expect("code" in result).toBe(delta > 0.25);
+  });
+  it("rejects a new clipping ancestor even if the resulting crop is identical", async () => {
+    const f = fixture();
+    const clip = row(8, "div", rect(0, 0, 1200, 800));
+    clip.styles["overflow-x"] = "hidden";
+    f.topRows.splice(1, 0, clip);
+    expect(await captureVisualScreenshot(f.cdp, f.candidate)).toMatchObject({
+      data: { reason: "visual_target_changed" },
+    });
+    expect(f.send.mock.calls.some((c) => c[1] === "Page.captureScreenshot")).toBe(false);
+  });
+  it("rejects changed owner and changed DOM before capture", async () => {
+    for (const kind of ["wrongOwner", "rootChanged"] as const) {
+      const f = fixture(true);
+      f.control[kind] = true;
+      expect(await captureVisualScreenshot(f.cdp, f.candidate)).toMatchObject({
+        data: { reason: "visual_target_changed" },
+      });
+      expect(f.send.mock.calls.some((c) => c[1] === "Page.captureScreenshot")).toBe(false);
+    }
+  });
+  it("releases retained objects on read failure and cancellation", async () => {
+    for (const kind of ["failRead", "abortRead"] as const) {
+      const f = fixture();
+      f.control[kind] = true;
+      const result = await captureVisualScreenshot(f.cdp, f.candidate, f.controller.signal);
+      expect(result).toMatchObject({ code: kind === "abortRead" ? "cancelled" : "cdp_failed" });
+      expect(f.send.mock.calls.at(-1)?.[1]).toBe("Runtime.releaseObjectGroup");
+    }
+  });
+  it("plans pixels without enlarging images and retries at most once", async () => {
+    expect(visualScreenshotScale(4096, 2048, 2)).toBe(0.25);
+    expect(visualScreenshotScale(4000, 4000, 1)).toBe(0.5);
+    const f = fixture();
+    f.control.shots = [png(3000, 3000), png(1800, 1800)];
+    expect(await captureVisualScreenshot(f.cdp, f.candidate)).toMatchObject({
+      width: 1800,
+      height: 1800,
+    });
+    const shots = f.send.mock.calls.filter((c) => c[1] === "Page.captureScreenshot");
+    expect(shots).toHaveLength(2);
+    expect((shots[1][2]!.clip as { scale: number }).scale).toBeLessThan(1);
+    const fail = fixture();
+    fail.control.shots = [png(3000, 3000)];
+    expect(await captureVisualScreenshot(fail.cdp, fail.candidate)).toMatchObject({
+      data: { reason: "visual_pixel_budget_exceeded" },
+    });
+    expect(fail.send.mock.calls.filter((c) => c[1] === "Page.captureScreenshot")).toHaveLength(2);
+  });
+  it("rejects invalid PNG without guessing dimensions", async () => {
+    const f = fixture();
+    f.control.shots = ["invalid"];
+    expect(await captureVisualScreenshot(f.cdp, f.candidate)).toMatchObject({
+      data: { reason: "screenshot_capture_failed" },
+    });
+  });
+  it("dispatches a visual ref through the screenshot tool and restores overlays", async () => {
+    const f = fixture();
+    const manager = new SessionManager({
+      agentWindow: {
+        create: async () => 100,
+        remove: async () => {},
+        ensureActiveTab: async () => 4,
+      },
+    });
+    const ctx = await manager.start("test");
+    ctx.refStore.replace([["e1", { kind: "visual-region", candidate: f.candidate }]]);
+    const tab = { id: 4, windowId: 100, active: true } as chrome.tabs.Tab;
+    const tabsApi = { get: async () => tab, query: async () => [tab] };
+    const sendToTab = vi.fn(async () => ({}));
+    const result = await handleScreenshot(
+      manager,
+      { session_id: "test", ref: "e1" },
+      { cdp: f.cdp, tabsApi, captureApi: { ...tabsApi, captureVisibleTab: vi.fn() }, sendToTab },
+    );
+    expect(result).toMatchObject({ width: 100, height: 40, format: "png" });
+    expect(sendToTab).toHaveBeenCalledTimes(2);
+  });
+});
@@ -20,8 +20,13 @@ import type { CoordinateOwner, CssViewport, SnapshotProjectionResult } from "./c
 import { readSnapshotOwnerSizes } from "./snapshot-owner-sizes";

 export interface LayoutMetrics {
-  cssVisualViewport?: { zoom?: number; clientWidth?: number; clientHeight?: number };
-  visualViewport?: { zoom?: number; clientWidth?: number; clientHeight?: number };
+  cssVisualViewport?: {
+    zoom?: number;
+    scale?: number;
+    clientWidth?: number;
+    clientHeight?: number;
+  };
+  visualViewport?: { zoom?: number; scale?: number; clientWidth?: number; clientHeight?: number };
  cssLayoutViewport?: {
    clientWidth?: number;
    clientHeight?: number;
@@ -207,11 +212,16 @@ export class GeometryContext {
    ownerBackendNodeId: number,
    ancestorClips: Polygon[],
    viewport: Size,
+    contentSize?: Size,
  ): Promise<SnapshotProjectionResult> {
    const key = `${cdpTargetKey(source.target)}:${ownerBackendNodeId}`;
    let promise = this.snapshotOwners.get(key);
    if (!promise) {
-      promise = this.snapshotOwner(source.target, ownerBackendNodeId);
+      promise = contentSize
+        ? this.ownerContent(source.target, ownerBackendNodeId).then((quad) =>
+            quad ? { quad, size: contentSize } : null,
+          )
+        : this.snapshotOwner(source.target, ownerBackendNodeId);
      this.snapshotOwners.set(key, promise);
    }
    let owner: { quad: Quad; size: Size } | null;
@@ -1,3 +1,8 @@
+import { parsePngDimensions } from "./png";
+import { captureVisualScreenshot } from "./visual-screenshot";
+
+export { parsePngDimensions } from "./png";
+
 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
@@ -48,7 +53,7 @@ import {
  normaliseRef as sharedNormaliseRef,
  type ToolEffect,
 } from "./shared";
-import { resolveSnapshotRef } from "./snapshot-ref";
+import { lookupRefTarget, 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";
@@ -101,38 +106,6 @@ export function stripDataUrlPrefix(dataUrl: string): string {
  return m ? dataUrl.slice(m[0].length) : dataUrl;
 }

-/**
- * 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.
- *
- * 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
- * 20-23 BE.
- */
-export function parsePngDimensions(base64: string): { width: number; height: number } | null {
-  try {
-    // atob is available in MV3 service workers.
-    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 u32 = (off: number) =>
-      (bin.charCodeAt(off) << 24) |
-      (bin.charCodeAt(off + 1) << 16) |
-      (bin.charCodeAt(off + 2) << 8) |
-      bin.charCodeAt(off + 3);
-    const width = u32(16) >>> 0;
-    const height = u32(20) >>> 0;
-    if (width === 0 || height === 0) return null;
-    return { width, height };
-  } catch {
-    return null;
-  }
-}
-
 export interface ScreenshotDeps {
  cdp?: SharedCdpRunner;
  tabsApi: ChromeTabsApi;
@@ -308,6 +281,17 @@ export async function handleScreenshot(
    if (!deps.cdp) {
      return { code: "cdp_failed", message: "screenshot ref capture requires CDP" };
    }
+    const entry = lookupRefTarget(ctx, ref, target.tabId);
+    if (entry?.kind === "visual-region") {
+      deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
+      const captured = await withExtensionOverlayHidden(
+        target.tabId,
+        () => captureVisualScreenshot(deps.cdp!, entry.candidate, signal),
+        deps.sendToTab,
+      );
+      if (isRpcError(captured)) return captured;
+      return withShotDialogs({ ...captured, format: "png", tab_id: target.tabId });
+    }
    const node = resolveSnapshotRef(ctx, ref, target.tabId);
    if (isRpcError(node)) return node;
    if (signal?.aborted) return cancelled("screenshot");
@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * 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
+ * 20-23 BE.
+ */
+export function parsePngDimensions(base64: string): { width: number; height: number } | null {
+  try {
+    // atob is available in MV3 service workers.
+    const head = base64.length > 64 ? base64.slice(0, 64) : base64;
+    const bin = atob(head);
+    if (bin.length < 33) return null;
+    if (bin.slice(0, 8) !== "\x89PNG\r\n\x1a\n" || bin.slice(8, 16) !== "\x00\x00\x00\x0dIHDR") {
+      return null;
+    }
+    const u32 = (off: number) =>
+      (bin.charCodeAt(off) << 24) |
+      (bin.charCodeAt(off + 1) << 16) |
+      (bin.charCodeAt(off + 2) << 8) |
+      bin.charCodeAt(off + 3);
+    const width = u32(16) >>> 0;
+    const height = u32(20) >>> 0;
+    if (width === 0 || height === 0) return null;
+    return { width, height };
+  } catch {
+    return null;
+  }
+}
@@ -3,7 +3,7 @@
 // `ref_not_found` errors for hard-failure tool paths.

 import type { SessionContext } from "@/session-manager/manager";
-import { normaliseRef } from "@/session-manager/ref-store";
+import { normaliseRef, type RefEntry } from "@/session-manager/ref-store";
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";

@@ -14,14 +14,22 @@ export interface SnapshotRefLookup {
  cdpSessionId?: string;
 }

-function refEntryForTab(ctx: SessionContext, refKey: string, tabId: number) {
+/** Typed lookup never turns a visual anchor into a DOM operation target. */
+export function lookupRefTarget(
+  ctx: SessionContext,
+  refKey: string,
+  tabId: number,
+): RefEntry | null {
  const entry = ctx.refStore.resolveEntry(refKey);
-  return entry?.tabId === tabId ? entry : null;
+  if (!entry) return null;
+  const ownerTabId =
+    entry.kind === "visual-region" ? entry.candidate.document.target.tabId : entry.tabId;
+  return ownerTabId === tabId ? entry : null;
 }

 /**
 * Soft lookup: returns `null` when the ref is unknown or bound to a
- * different tab. Used by paths that report `matched: false` instead of
+ * different tab, or is a visual region. Used by paths that report `matched: false` instead of
 * emitting an RPC error (e.g. `tool.request_help`).
 */
 export function lookupSnapshotRef(
@@ -30,8 +38,8 @@ export function lookupSnapshotRef(
  tabId: number,
 ): SnapshotRefLookup | null {
  const refKey = normaliseRef(ref);
-  const entry = refEntryForTab(ctx, refKey, tabId);
-  if (!entry) return null;
+  const entry = lookupRefTarget(ctx, refKey, tabId);
+  if (!entry || entry.kind !== "dom") return null;
  return {
    backendNodeId: entry.backendNodeId,
    refKey,
@@ -50,6 +58,13 @@ export function resolveSnapshotRef(
  ref: string,
  tabId: number,
 ): SnapshotRefLookup | RpcError {
+  const entry = lookupRefTarget(ctx, ref, tabId);
+  if (entry?.kind === "visual-region")
+    return rpcError(
+      "unsupported",
+      "ref_kind_unsupported",
+      `ref ${ref} is a visual region, not a DOM operation target`,
+    );
  const looked = lookupSnapshotRef(ctx, ref, tabId);
  if (looked === null) {
    return rpcError(
@@ -0,0 +1,382 @@
+import type { CdpFrame } from "@/browser-driver/frame-graph";
+import type { RpcError } from "@/transport/types";
+import { rpcError } from "./errors";
+import {
+  type GeometryProjection,
+  projectRectToViewport,
+  type Size,
+  type ViewportRect,
+} from "./geometry";
+import { type CssViewport, screenshotPageRect } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
+import { parsePngDimensions } from "./png";
+import { type CdpRunner, sendToCdpTarget } from "./shared";
+import { isAbortError, throwIfAborted } from "./vom/capture-abort";
+import { resolveVerifiedNode } from "./vom/document-identity";
+import type { DocumentIdentity } from "./vom/facts";
+import { VISUAL_STYLES } from "./vom/snapshot";
+import type { VisualCandidate, VisualFramePath } from "./vom/visual-discovery";
+import {
+  EMPTY_VISUAL_CONTEXT,
+  extendVisualContext,
+  projectVisualBox,
+  resolveVisualRegion,
+  type VisualClipSource,
+  type VisualContext,
+  visualProjectionIssue,
+} from "./vom/visual-region";
+
+interface LiveRow {
+  node: number;
+  tag: string;
+  box: ViewportRect;
+  client: ViewportRect;
+  contentSize: Size;
+  styles: Record<string, string>;
+}
+interface LiveFrame {
+  top: boolean;
+  dpr: number;
+  rows: LiveRow[]; // Anchor first, root last.
+}
+
+// Read only one current ancestry, including shadow hosts, in the verified isolated world.
+const READ_ANCESTRY = `function(styleNames) {
+  if (!this.isConnected || this.ownerDocument !== document) return null;
+  const rows = [];
+  for (let node = this; node; node = node.parentElement || node.getRootNode().host) {
+    if (!(node instanceof Element)) return null;
+    const s = getComputedStyle(node), r = node.getBoundingClientRect();
+    rows.push({ node, tag: node.localName,
+      box: { x:r.x, y:r.y, width:r.width, height:r.height },
+      client: { x:r.x+node.clientLeft, y:r.y+node.clientTop, width:node.clientWidth, height:node.clientHeight },
+      contentSize: { width:node.clientWidth-parseFloat(s.paddingLeft)-parseFloat(s.paddingRight), height:node.clientHeight-parseFloat(s.paddingTop)-parseFloat(s.paddingBottom) },
+      styles: Object.fromEntries(styleNames.map(key => [key,s.getPropertyValue(key)])) });
+  }
+  return { top: window === window.top, dpr: devicePixelRatio, rows };
+}`;
+
+interface DeepValue {
+  type: string;
+  value?: unknown;
+}
+/** This read returns JSON primitives plus DOM nodes (backend IDs), never remote object handles. */
+function decode(value: DeepValue): unknown {
+  if (value.type === "node") return (value.value as { backendNodeId?: number })?.backendNodeId;
+  if (value.type === "array") return (value.value as DeepValue[]).map(decode);
+  if (value.type === "object")
+    return Object.fromEntries(
+      (value.value as [string, DeepValue][]).map(([key, item]) => [key, decode(item)]),
+    );
+  if (value.type === "null") return null;
+  if (["string", "number", "boolean"].includes(value.type)) return value.value;
+  throw new Error("unexpected live ancestry serialization");
+}
+
+function stale(message: string): RpcError {
+  return rpcError(
+    "not_found",
+    "visual_target_changed",
+    `${message}; observe again before requesting a screenshot`,
+  );
+}
+
+function sameIdentity(a: DocumentIdentity, b: DocumentIdentity): boolean {
+  return (
+    a.attachmentId === b.attachmentId &&
+    a.frameId === b.frameId &&
+    a.target.tabId === b.target.tabId &&
+    a.target.sessionId === b.target.sessionId &&
+    a.documentElementBackendNodeId === b.documentElementBackendNodeId
+  );
+}
+
+function closeRect(a: ViewportRect, b: ViewportRect): boolean {
+  return [
+    a.x - b.x,
+    a.y - b.y,
+    a.x + a.width - b.x - b.width,
+    a.y + a.height - b.y - b.height,
+  ].every((delta) => Number.isFinite(delta) && Math.abs(delta) <= 0.25);
+}
+
+function sameClips(a?: VisualClipSource, b?: VisualClipSource): boolean {
+  while (a && b) {
+    if (
+      !sameIdentity(a.document, b.document) ||
+      a.backendNodeId !== b.backendNodeId ||
+      a.x !== b.x ||
+      a.y !== b.y ||
+      a.overflowX !== b.overflowX ||
+      a.overflowY !== b.overflowY ||
+      !closeRect(a.box, b.box)
+    )
+      return false;
+    a = a.parent;
+    b = b.parent;
+  }
+  return !a && !b;
+}
+
+/** Scale affects raster size only, never the selected CSS region. */
+export function visualScreenshotScale(width: number, height: number, pixelsPerCss: number): number {
+  if (![width, height, pixelsPerCss].every((n) => Number.isFinite(n) && n > 0))
+    throw new Error("invalid screenshot pixel dimensions");
+  return Math.min(
+    1,
+    2048 / (Math.max(width, height) * pixelsPerCss),
+    Math.sqrt(4_000_000 / (width * height * pixelsPerCss * pixelsPerCss)),
+  );
+}
+
+async function readFrame(
+  cdp: CdpRunner,
+  document: DocumentIdentity,
+  anchor: number,
+  signal?: AbortSignal,
+): Promise<LiveFrame | RpcError> {
+  const verified = await resolveVerifiedNode(cdp, document, anchor, signal);
+  if (verified.status !== "current") return stale(`visual DOM identity ${verified.status}`);
+  try {
+    throwIfAborted(signal);
+    const reply = await sendToCdpTarget<{
+      result?: { deepSerializedValue?: DeepValue };
+      exceptionDetails?: unknown;
+    }>(cdp, document.target, "Runtime.callFunctionOn", {
+      objectId: verified.objectId,
+      objectGroup: verified.objectGroup,
+      functionDeclaration: READ_ANCESTRY,
+      arguments: [{ value: VISUAL_STYLES }],
+      serializationOptions: {
+        serialization: "deep",
+        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+      },
+    });
+    throwIfAborted(signal);
+    if (reply.exceptionDetails || !reply.result?.deepSerializedValue)
+      return stale("visual ancestry unavailable");
+    const result = decode(reply.result.deepSerializedValue) as LiveFrame | null;
+    if (
+      !result?.rows?.length ||
+      result.rows[0].node !== anchor ||
+      result.rows.at(-1)?.node !== document.documentElementBackendNodeId ||
+      !result.rows.every((row) => Number.isSafeInteger(row.node) && row.node > 0)
+    )
+      return stale("visual ancestry incomplete");
+    if (cdp.getAttachmentId?.(document.target.tabId) !== document.attachmentId)
+      return stale("visual attachment changed");
+    return result;
+  } finally {
+    await sendToCdpTarget(cdp, document.target, "Runtime.releaseObjectGroup", {
+      objectGroup: verified.objectGroup,
+    }).catch(() => {});
+    throwIfAborted(signal);
+  }
+}
+
+/** All live reads for one screenshot use this one measurement context. */
+async function resolveVisualRegionNow(
+  cdp: CdpRunner,
+  candidate: VisualCandidate,
+  signal?: AbortSignal,
+): Promise<{ crop: ViewportRect; viewport: CssViewport; dpr: number } | RpcError> {
+  throwIfAborted(signal);
+  if (!candidate.framePath || !sameIdentity(candidate.document, candidate.framePath.document))
+    return stale("visual frame path unavailable");
+  const path: { frame: VisualFramePath; anchor: number }[] = [];
+  const seen = new Set<string>();
+  let frame: VisualFramePath | undefined = candidate.framePath;
+  let anchor = candidate.backendNodeId;
+  while (frame) {
+    if (
+      seen.has(frame.document.frameId) ||
+      frame.document.target.tabId !== candidate.document.target.tabId ||
+      cdp.getAttachmentId?.(frame.document.target.tabId) !== frame.document.attachmentId
+    )
+      return stale("invalid visual frame path");
+    seen.add(frame.document.frameId);
+    path.push({ frame, anchor });
+    anchor = frame.parent?.ownerBackendNodeId ?? 0;
+    frame = frame.parent?.frame;
+  }
+  path.reverse();
+  const frames: CdpFrame[] = path.map(({ frame }) => ({
+    frameId: frame.document.frameId,
+    target: frame.document.target,
+    ...(frame.parent
+      ? {
+          parentFrameId: frame.parent.frame.document.frameId,
+          ownerBackendNodeId: frame.parent.ownerBackendNodeId,
+        }
+      : {}),
+  }));
+  // Validate each recorded edge instead of asking the driver to fill all page owners.
+  for (const { frame } of path) {
+    if (!frame.parent) continue;
+    throwIfAborted(signal);
+    const owner = await sendToCdpTarget<{ backendNodeId?: number }>(
+      cdp,
+      frame.parent.frame.document.target,
+      "DOM.getFrameOwner",
+      { frameId: frame.document.frameId },
+    );
+    if (owner.backendNodeId !== frame.parent.ownerBackendNodeId)
+      return stale("visual frame owner changed");
+  }
+  const geometry = new GeometryContext(
+    cdp,
+    candidate.document.target.tabId,
+    { rootFrameId: frames[0].frameId, frames },
+    signal,
+  );
+  let context: VisualContext = EMPTY_VISUAL_CONTEXT;
+  let parentRead: LiveFrame | undefined;
+  let finalRegion: VisualCandidate["region"] | undefined;
+  let topDpr = 0;
+  for (let i = 0; i < path.length; i++) {
+    const { frame, anchor } = path[i];
+    const live = await readFrame(cdp, frame.document, anchor, signal);
+    if ("code" in live) return live;
+    if (live.top !== (i === 0)) return stale("visual root frame changed");
+    if (i === 0) topDpr = live.dpr;
+    const metrics = await geometry.layoutMetrics(frame.document.target);
+    const viewport = cssViewport(metrics);
+    const projections: GeometryProjection[] = [];
+    if (frame.parent) {
+      const parent = frame.parent.frame.document;
+      const size = parentRead!.rows[0].contentSize;
+      if (![size.width, size.height].every((n) => Number.isFinite(n) && n > 0))
+        return stale("iframe content size unavailable");
+      const parentViewport = await geometry.viewport(parent.target);
+      if (!parentViewport) return stale("parent viewport unavailable");
+      const local = await geometry.snapshotProjection(
+        { target: parent.target, frameId: frame.document.frameId },
+        frame.parent.ownerBackendNodeId,
+        [],
+        parentViewport,
+        size,
+      );
+      const outer = await geometry.targetProjection(parent.frameId);
+      if (local.status !== "available" || !outer)
+        return stale("visual frame projection unavailable");
+      projections.push(local.projection.geometry, outer);
+    } else projections.push({ sourceClips: [], edges: [], topViewport: viewport });
+    const issue = visualProjectionIssue({
+      projections,
+      coordinates: { layoutUnitsPerCssPixel: 1, scrollCss: { x: 0, y: 0 } },
+      pageScale: metrics.cssVisualViewport?.scale ?? metrics.visualViewport?.scale,
+    });
+    if (issue) return stale(issue);
+    for (let j = live.rows.length - 1; j >= 0; j--) {
+      const row = live.rows[j];
+      const isAnchor = j === 0;
+      const node = {
+        document: frame.document,
+        backendNodeId: row.node,
+        styles: row.styles,
+        clientBox: projectVisualBox(row.client, projections),
+      };
+      context = extendVisualContext(
+        context,
+        node,
+        !isAnchor && row.tag !== "iframe" && row.tag !== "frame",
+      );
+    }
+    if (i < path.length - 1) {
+      const owner = live.rows[0];
+      context = {
+        ...context,
+        hidden:
+          context.hidden ||
+          owner.styles.visibility === "hidden" ||
+          owner.styles.visibility === "collapse",
+        transformed: false,
+        localClip: false,
+        unpositionedClip: false,
+      };
+    } else {
+      const row = live.rows[0];
+      if (row.tag !== "canvas") return stale("visual anchor is no longer Canvas");
+      let visible: ViewportRect | null = row.box;
+      for (const projection of projections)
+        visible = visible
+          ? projectRectToViewport(
+              { x: visible.x, y: visible.y, w: visible.width, h: visible.height },
+              projection,
+            )
+          : null;
+      const region = resolveVisualRegion({
+        borderBox: projectVisualBox(row.box, projections),
+        frameVisibleBox: visible,
+        context,
+        visibility: row.styles.visibility,
+      });
+      if (region.status !== "available")
+        return stale(
+          `visual region ${region.status}${region.status === "unavailable" ? `: ${region.reason}` : ""}`,
+        );
+      finalRegion = region;
+    }
+    parentRead = live;
+  }
+  if (
+    !finalRegion ||
+    !closeRect(candidate.region.borderBox, finalRegion.borderBox) ||
+    !closeRect(candidate.region.crop, finalRegion.crop) ||
+    !sameClips(candidate.region.clips, finalRegion.clips)
+  )
+    return stale("visual region changed");
+  const viewport = cssViewport(await geometry.layoutMetrics(frames[0].target));
+  return { crop: finalRegion.crop, viewport, dpr: topDpr };
+}
+
+/** One target only. No frame discovery, scrolling, AX, or snapshot recapture. */
+export async function captureVisualScreenshot(
+  cdp: CdpRunner,
+  candidate: VisualCandidate,
+  signal?: AbortSignal,
+): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
+  try {
+    const region = await resolveVisualRegionNow(cdp, candidate, signal);
+    if ("code" in region) return region;
+    const clip = screenshotPageRect(region.crop, region.viewport);
+    if (!clip) return stale("invalid screenshot coordinates");
+    let scale = visualScreenshotScale(region.crop.width, region.crop.height, region.dpr);
+    for (let attempt = 0; attempt < 2; attempt++) {
+      throwIfAborted(signal);
+      if (
+        cdp.getAttachmentId?.(candidate.document.target.tabId) !== candidate.document.attachmentId
+      )
+        return stale("visual attachment changed");
+      const shot = await cdp.send<{ data?: string }>(
+        candidate.document.target.tabId,
+        "Page.captureScreenshot",
+        { format: "png", captureBeyondViewport: false, clip: { ...clip.rect, scale } },
+      );
+      throwIfAborted(signal);
+      const dims = shot.data ? parsePngDimensions(shot.data) : null;
+      if (!dims)
+        return rpcError(
+          "cdp_failed",
+          "screenshot_capture_failed",
+          "visual screenshot returned invalid PNG dimensions",
+        );
+      const correction = visualScreenshotScale(dims.width, dims.height, 1);
+      if (correction === 1) return { image_base64: shot.data!, ...dims };
+      scale *= correction * 0.99;
+    }
+    return rpcError(
+      "cdp_failed",
+      "visual_pixel_budget_exceeded",
+      "visual screenshot exceeds the pixel budget",
+    );
+  } catch (error) {
+    if (isAbortError(error) || signal?.aborted)
+      return { code: "cancelled", message: "visual screenshot aborted" };
+    return rpcError(
+      "cdp_failed",
+      "screenshot_capture_failed",
+      error instanceof Error ? error.message : String(error),
+    );
+  }
+}
@@ -5,12 +5,15 @@ import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
 import { captureVomObservation } from "../../observation";
 import type { CdpRunner } from "../../shared";
 import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
-import { buildSemanticGraph } from "../semantic-graph/build";
-import { REQUESTED_STYLES, type SnapshotReply } from "../snapshot";
+import { buildSemanticGraph, buildSemanticVomScene } from "../semantic-graph";
+import { REQUESTED_STYLES, type SnapshotReply, VISUAL_STYLES } from "../snapshot";
+import { deduplicateVisualCandidates } from "../visual-dedup";
+import { discoverVisualCandidates } from "../visual-discovery";

 function fixture(
  options: {
    frames?: CdpFrame[];
+    canvas?: boolean;
    after?: Record<string, { element?: number; missing?: boolean; unreadable?: boolean }>;
    fail?: string;
    missingIdentity?: boolean;
@@ -78,23 +81,27 @@ function fixture(
      if (method === "Page.getLayoutMetrics")
        result = {
          visualViewport: { clientWidth: 1000 },
-          cssVisualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000, scale: 1 },
          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
        };
      if (method === "DOMSnapshot.captureSnapshot") {
        snapshots++;
-        expect((params as { computedStyles: unknown }).computedStyles).toEqual(REQUESTED_STYLES);
+        const requested = (params as { computedStyles: readonly string[] }).computedStyles;
+        expect([REQUESTED_STYLES, VISUAL_STYLES]).toContainEqual(requested);
        result = {
          strings: [
            "#document",
            "html",
-            "button",
+            options.canvas ? "canvas" : "button",
            OVERLAY_HOST_MARKER_ATTR,
            "",
            "visible",
            "1",
            "static",
            "auto",
+            "block",
+            "none",
+            "0px",
          ],
          documents: frames
            .filter(
@@ -144,10 +151,18 @@ function fixture(
                    [0, 0, 1000, 800],
                    [10, 20, 100, 40],
                  ],
-                  styles: [
-                    [7, 8, 8, 5, 6],
-                    [7, 8, 8, 5, 6],
+                  clientRects: [
+                    [0, 0, 1000, 800],
+                    [0, 0, 100, 40],
                  ],
+                  styles: Array.from({ length: 2 }, () =>
+                    requested.map(
+                      (name) =>
+                        [7, 8, 8, 5, 6, 9, 5, 5, 10, 6, 10, 10, 10, 10, 10, 8, 10, 11][
+                          VISUAL_STYLES.indexOf(name as (typeof VISUAL_STYLES)[number])
+                        ],
+                    ),
+                  ),
                },
              };
            }),
@@ -193,7 +208,7 @@ describe("captureObservationFacts", () => {
      if (method === "Page.getLayoutMetrics")
        return {
          visualViewport: { clientWidth: 2000 },
-          cssVisualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000, scale: 1 },
          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 999, pageY: 999 },
        } as never;
      const reply = await original(target, method, params);
@@ -659,7 +674,7 @@ describe("OOPIF capture", () => {
      if (method === "Page.getLayoutMetrics") {
        return {
          visualViewport: { clientWidth: 1000 },
-          cssVisualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000, scale: 1 },
          cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 },
        };
      }
@@ -685,7 +700,7 @@ describe("OOPIF capture", () => {
        if (method === "Page.getLayoutMetrics") {
          return {
            visualViewport: { clientWidth: 1000 },
-            cssVisualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000, scale: 1 },
            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
          };
        }
@@ -767,7 +782,7 @@ describe("OOPIF capture", () => {
      if (method === "Page.getLayoutMetrics")
        return {
          visualViewport: { clientWidth: 1000 },
-          cssVisualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000, scale: 1 },
          cssLayoutViewport: { clientWidth: 300, clientHeight: 200 },
        };
      if (method === "DOMSnapshot.captureSnapshot")
@@ -829,7 +844,7 @@ describe("OOPIF capture", () => {
        if (method === "Page.getLayoutMetrics") {
          return {
            visualViewport: { clientWidth: 1000 },
-            cssVisualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000, scale: 1 },
            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
          };
        }
@@ -919,7 +934,7 @@ function siblingCaptureFixture(
      if (method === "Page.getLayoutMetrics")
        return {
          visualViewport: { clientWidth: 1000 },
-          cssVisualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000, scale: 1 },
          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 },
        };
      if (method === "DOM.getBoxModel")
@@ -1127,7 +1142,7 @@ describe("snapshot document provenance", () => {
          : method === "Page.getLayoutMetrics"
            ? {
                visualViewport: { clientWidth: 1000 },
-                cssVisualViewport: { clientWidth: 1000 },
+                cssVisualViewport: { clientWidth: 1000, scale: 1 },
                cssLayoutViewport: { clientWidth: 200, clientHeight: 100 },
              }
            : {}) as T,
@@ -1363,3 +1378,101 @@ describe("AX frame scheduling", () => {
    expect(active).toBe(0);
  });
 });
+
+describe("visual facts integration", () => {
+  it("defaults to base facts across targets and shares semantic behavior with visual capture", async () => {
+    const base = fixture({ canvas: true });
+    const visual = fixture({ canvas: true });
+    const baseFacts = await captureObservationFacts(base.cdp, 4);
+    const visualFacts = await captureObservationFacts(visual.cdp, 4, undefined, undefined, {
+      includeVisualFacts: true,
+    });
+    expect(baseFacts.visualFactsCollected).toBe(false);
+    expect(visualFacts.visualFactsCollected).toBe(true);
+    expect(baseFacts.documents).toHaveLength(4);
+    expect(visualFacts.documents).toHaveLength(4);
+    for (const doc of baseFacts.documents) {
+      expect(doc.geometry).toBeUndefined();
+      expect(doc.index.ancestryComplete).toBeUndefined();
+      for (const node of doc.index.nodes.values()) {
+        expect(node.parentMissing).toBeUndefined();
+        expect(node.layout?.clientRect).toBeUndefined();
+        if (node.layout) expect(Object.keys(node.layout.styles)).toEqual([...REQUESTED_STYLES]);
+      }
+    }
+    // This fixture has no child frame projection measurements. Enabling visual
+    // collection must preserve that missing evidence, not invent geometry.
+    expect(
+      visualFacts.documents.find((doc) => doc.frame.frameId === "main")?.geometry,
+    ).toBeDefined();
+    expect(visualFacts.documents.filter((doc) => doc.geometry)).toHaveLength(1);
+    for (const doc of visualFacts.documents) {
+      expect(doc.index.ancestryComplete).toBeDefined();
+      for (const node of doc.index.nodes.values())
+        if (node.layout) {
+          expect(Object.keys(node.layout.styles)).toEqual([...VISUAL_STYLES]);
+          expect(Object.keys(node.layout.styles).some((key) => key.includes("radius"))).toBe(false);
+        }
+    }
+    for (const [capture, expected] of [
+      [base, REQUESTED_STYLES],
+      [visual, VISUAL_STYLES],
+    ] as const) {
+      const calls = capture.logs.filter((c) => c.method === "DOMSnapshot.captureSnapshot");
+      expect(calls).toHaveLength(2);
+      for (const call of calls) expect(call.params.computedStyles).toEqual(expected);
+    }
+    expect(base.logs.map((c) => [c.target, c.method])).toEqual(
+      visual.logs.map((c) => [c.target, c.method]),
+    );
+    const scene = (input: typeof baseFacts) =>
+      buildSemanticVomScene({
+        documents: semanticCapture(input).documents,
+        viewport: input.viewport,
+        rootFrameId: input.rootFrameId,
+        excludedBackendNodeIds: semanticCapture(input).captured.excludedBackendNodeIds,
+      });
+    expect(scene(baseFacts)).toEqual(scene(visualFacts));
+    const before = base.logs.length;
+    expect(await discoverVisualCandidates(baseFacts)).toMatchObject({
+      complete: false,
+      candidates: [],
+      issues: [{ reason: "visual-facts-not-collected" }],
+    });
+    expect(base.logs).toHaveLength(before);
+  });
+
+  it("passes actual snapshot styles, client units, projection and identity to pure discovery without additional CDP", async () => {
+    const { cdp, logs } = fixture({
+      canvas: true,
+      frames: [{ frameId: "main", target: { tabId: 4 } }],
+    });
+    const facts = await captureObservationFacts(cdp, 4, undefined, undefined, {
+      includeVisualFacts: true,
+    });
+    const before = logs.length;
+    const result = await discoverVisualCandidates(facts);
+    expect(logs).toHaveLength(before);
+    expect(logs.filter((call) => call.method === "DOMSnapshot.captureSnapshot")).toHaveLength(1);
+    expect(result.complete).toBe(true);
+    expect(result.candidates).toHaveLength(1);
+    expect(result.candidates[0]).toMatchObject({
+      document: { frameId: "main", documentElementBackendNodeId: 1 },
+      region: { crop: { x: 10, y: 20, width: 100, height: 40 } },
+    });
+    const deduplicated = await deduplicateVisualCandidates(result);
+    expect(deduplicated.candidates).toEqual(result.candidates);
+    expect(deduplicated.candidates[0]).toBe(result.candidates[0]);
+    expect(deduplicated).toMatchObject({
+      candidateCount: 1,
+      deduplicatedCount: 0,
+      dedupDegraded: false,
+    });
+    expect(logs).toHaveLength(before);
+    expect(facts.documents[0].index.nodes.get(2)?.layout?.clientRect).toEqual([0, 0, 100, 40]);
+    expect(facts.documents[0].geometry?.pageScale).toBe(1);
+    const baseline = fixture({ frames: [{ frameId: "main", target: { tabId: 4 } }] });
+    await captureObservationFacts(baseline.cdp, 4);
+    expect(logs.map((call) => call.method)).toEqual(baseline.logs.map((call) => call.method));
+  });
+});
@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpRunner } from "../../shared";
+import { verifyDocumentIdentity, verifyVisualTargetIdentity } from "../document-identity";
+import type { VisualCandidate } from "../visual-discovery";
+
+const candidate: VisualCandidate = {
+  document: {
+    attachmentId: "attached",
+    target: { tabId: 4, sessionId: "child-session" },
+    frameId: "child-frame",
+    documentElementBackendNodeId: 10,
+  },
+  backendNodeId: 20,
+  parentBackendNodeId: 10,
+  region: {
+    status: "available",
+    borderBox: { x: 0, y: 0, width: 10, height: 10 },
+    crop: { x: 0, y: 0, width: 10, height: 10 },
+  },
+};
+
+function fixture(
+  options: {
+    connected?: boolean;
+    sameDocument?: boolean;
+    root?: number;
+    missing?: boolean;
+    fail?: string;
+    abortAt?: string;
+    detachAt?: string;
+  } = {},
+) {
+  const controller = new AbortController();
+  let attachment = "attached";
+  const send = vi.fn(
+    async (_tab: number, _session: string, method: string, params: Record<string, unknown>) => {
+      if (options.abortAt === method) controller.abort();
+      if (options.detachAt === method) attachment = "new-attachment";
+      if (options.fail === method) throw new Error("CDP failed");
+      if (method === "Page.createIsolatedWorld") return { executionContextId: 7 };
+      if (method === "DOM.resolveNode")
+        return options.missing ? {} : { object: { objectId: "anchor" } };
+      if (method === "Runtime.evaluate" || method === "Runtime.callFunctionOn") {
+        let root: unknown = {};
+        if (method === "Runtime.callFunctionOn") {
+          const document = { documentElement: {} };
+          // Exercise the actual predicate, including connection and owner checks.
+          root = new Function("document", `return (${params.functionDeclaration}).call(this)`).call(
+            {
+              isConnected: options.connected ?? true,
+              ownerDocument: options.sameDocument === false ? {} : document,
+            },
+            document,
+          );
+        }
+        return {
+          result: {
+            deepSerializedValue:
+              root === null
+                ? { type: "null" }
+                : { type: "node", value: { backendNodeId: options.root ?? 10 } },
+          },
+        };
+      }
+      if (method === "Runtime.releaseObjectGroup") return {};
+      throw new Error(`unexpected ${method}`);
+    },
+  );
+  const cdp = {
+    send: vi.fn(),
+    sendToTarget: (
+      target: { tabId: number; sessionId?: string },
+      method: string,
+      params: Record<string, unknown>,
+    ) => send(target.tabId, target.sessionId!, method, params),
+    getAttachmentId: () => attachment,
+  } as unknown as CdpRunner;
+  return { cdp, send, controller };
+}
+
+describe("visual target identity", () => {
+  it("uses the exact frame and target with bounded local reads and releases objects", async () => {
+    const { cdp, send } = fixture();
+    expect(await verifyVisualTargetIdentity(cdp, candidate)).toBe("current");
+    expect(send.mock.calls.map((c) => c[2])).toEqual([
+      "Page.createIsolatedWorld",
+      "DOM.resolveNode",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObjectGroup",
+    ]);
+    expect(
+      send.mock.calls.every(([tab, session]) => tab === 4 && session === "child-session"),
+    ).toBe(true);
+    expect(send.mock.calls[0][3]).toMatchObject({ frameId: "child-frame" });
+    expect(send.mock.calls[1][3]).toMatchObject({ backendNodeId: 20, executionContextId: 7 });
+    expect(send.mock.calls[2][3]).toMatchObject({ objectId: "anchor" });
+    expect(send.mock.calls[3][3].objectGroup).toBe(send.mock.calls[1][3].objectGroup);
+  });
+
+  it.each([
+    { connected: false },
+    { sameDocument: false },
+    { root: 11 },
+  ])("rejects detached/adopted/replaced DOM: %j", async (options) => {
+    const { cdp } = fixture(options);
+    expect(await verifyVisualTargetIdentity(cdp, candidate)).toBe("changed");
+  });
+
+  it("does not add anchor reads to existing capture identity verification", async () => {
+    const { cdp, send } = fixture();
+    expect(await verifyDocumentIdentity(cdp, candidate.document)).toBe("current");
+    expect(send.mock.calls.map((c) => c[2])).toEqual([
+      "Page.createIsolatedWorld",
+      "Runtime.evaluate",
+      "Runtime.releaseObjectGroup",
+    ]);
+  });
+
+  it.each([
+    "Page.createIsolatedWorld",
+    "DOM.resolveNode",
+    "Runtime.callFunctionOn",
+  ])("fails closed and cleans up when %s fails", async (fail) => {
+    const { cdp, send } = fixture({ fail });
+    expect(await verifyVisualTargetIdentity(cdp, candidate)).toBe("unavailable");
+    expect(send.mock.calls.at(-1)?.[2]).toBe("Runtime.releaseObjectGroup");
+  });
+
+  it("rejects attachment changes before and during verification", async () => {
+    const first = fixture();
+    expect(
+      await verifyVisualTargetIdentity({ ...first.cdp, getAttachmentId: () => "other" }, candidate),
+    ).toBe("changed");
+    expect(first.send).not.toHaveBeenCalled();
+    const second = fixture({ detachAt: "Runtime.callFunctionOn" });
+    expect(await verifyVisualTargetIdentity(second.cdp, candidate)).toBe("changed");
+    const missing = fixture({ missing: true });
+    expect(await verifyVisualTargetIdentity(missing.cdp, candidate)).toBe("unavailable");
+  });
+
+  it.each([
+    "DOM.resolveNode",
+    "Runtime.callFunctionOn",
+  ])("propagates cancellation at %s after releasing the object group", async (abortAt) => {
+    const { cdp, send, controller } = fixture({ abortAt });
+    await expect(
+      verifyVisualTargetIdentity(cdp, candidate, controller.signal),
+    ).rejects.toMatchObject({ name: "AbortError" });
+    expect(send.mock.calls.at(-1)?.[2]).toBe("Runtime.releaseObjectGroup");
+  });
+});
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
 import { createCaptureCheckpoint } from "../capture-abort";
 import { buildDocumentIndex, type DecodedNode } from "../facts";
-import { decodeDocument, REQUESTED_STYLES } from "../snapshot";
+import { decodeDocument, REQUESTED_STYLES, VISUAL_SNAPSHOT } from "../snapshot";

 function node(id: number, parent: number | null): DecodedNode {
  return {
@@ -125,3 +125,44 @@ describe("document facts", () => {
    expect(reads).toBeLessThanOrEqual(356);
  });
 });
+
+describe("visual ancestry facts", () => {
+  it("distinguishes document roots, malformed roots, missing parents and cycles", async () => {
+    const input = [
+      { ...node(0, null), nodeType: 9 },
+      { ...node(1, 0), nodeType: 1 },
+      { ...node(2, 1), nodeType: 11 },
+      node(3, 2),
+      node(4, 99),
+      node(5, 6),
+      node(6, 5),
+      node(7, 5),
+      { ...node(8, null), nodeType: 1 },
+      { ...node(9, null), nodeType: 9, parentMissing: true },
+    ];
+    const index = await buildDocumentIndex(input.reverse(), undefined, true);
+    for (const id of [0, 1, 2, 3]) expect(index.ancestryComplete!.get(id)).toBe(true);
+    for (const id of [4, 5, 6, 7, 8, 9]) expect(index.ancestryComplete!.get(id)).toBe(false);
+  });
+
+  it("retains client offsets in their source units and does not disguise missing parent indices", async () => {
+    const decoded = await decodeDocument(
+      {
+        nodes: { backendNodeId: [1, 2], nodeType: [1, 1], nodeName: [0, 0], parentIndex: [99] },
+        layout: {
+          nodeIndex: [0],
+          bounds: [[745, 455.625, 97, 59.5]],
+          clientRects: [[5, 5, 68, 38]],
+        },
+      },
+      ["div"],
+      undefined,
+      VISUAL_SNAPSHOT,
+    );
+    expect(decoded.nodes[0].layout?.clientRect).toEqual([5, 5, 68, 38]);
+    expect(decoded.nodes[0].layout?.bounds).toEqual([745, 455.625, 97, 59.5]);
+    expect(decoded.nodes.every((node) => node.parentMissing)).toBe(true);
+    const index = await buildDocumentIndex(decoded.nodes, undefined, true);
+    expect([...index.ancestryComplete!.values()]).toEqual([false, false]);
+  });
+});
@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { deduplicateVisualCandidates, MAX_VISUAL_DEDUP_KEYS } from "../visual-dedup";
+import type { VisualCandidate, VisualDiscoveryResult } from "../visual-discovery";
+
+function candidate(id: number, width = 100, parent = 1): VisualCandidate {
+  const crop = { x: 0, y: 0, width, height: 100 };
+  return {
+    document: {
+      attachmentId: "a",
+      target: { tabId: 1 },
+      frameId: "main",
+      documentElementBackendNodeId: 1,
+    },
+    backendNodeId: id,
+    parentBackendNodeId: parent,
+    region: { status: "available", borderBox: crop, crop },
+  };
+}
+function discovery(candidates: VisualCandidate[]): VisualDiscoveryResult {
+  return { candidates, complete: true, issues: [], captureIssues: [] };
+}
+
+describe("visual candidate deduplication", () => {
+  it("preserves small, unnamed and labelled candidates and their original evidence", async () => {
+    const small = { ...candidate(3, 1), label: '  A "label"\n😀' };
+    const large = candidate(2, 1000);
+    const input = discovery([small, large]);
+    Object.freeze(input.candidates);
+    Object.freeze(small);
+    Object.freeze(large);
+    for (let i = 0; i < 2; i++) {
+      const result = await deduplicateVisualCandidates(input);
+      expect(result.candidates).toEqual([small, large]);
+      expect(result.candidates[0]).toBe(small);
+      expect(result.candidates[1]).toBe(large);
+      expect(result).toMatchObject({
+        candidateCount: 2,
+        deduplicatedCount: 0,
+        dedupDegraded: false,
+      });
+    }
+  });
+
+  it("only deduplicates exact crops within the same full DOM identity and direct parent", async () => {
+    const base = candidate(20);
+    const variants = [
+      candidate(30, 100, 2),
+      { ...candidate(40), parentBackendNodeId: null },
+      ...["x", "y", "width", "height"].map((axis) => ({
+        ...base,
+        region: {
+          ...base.region,
+          crop: {
+            ...base.region.crop,
+            [axis]: base.region.crop[axis as keyof typeof base.region.crop] + 0.001,
+          },
+        },
+      })),
+      ...[
+        { frameId: "child" },
+        { target: { tabId: 2 } },
+        { target: { tabId: 1, sessionId: "remote" } },
+        { documentElementBackendNodeId: 9 },
+        { attachmentId: "b" },
+      ].map((identity) => ({ ...base, document: { ...base.document, ...identity } })),
+    ];
+    const duplicate = { ...candidate(10), label: "Not a new target" };
+    const result = await deduplicateVisualCandidates(discovery([base, ...variants, duplicate]));
+    expect(result.candidates).toEqual([base, ...variants]);
+    expect(result.candidates[0]).toBe(base);
+    expect(result.deduplicatedCount).toBe(1);
+  });
+
+  it.each([
+    50_001, 100_000,
+  ])("keeps all %s distinct candidates including the last tiny Canvas", async (count) => {
+    const input = Array.from({ length: count }, (_, i) => candidate(i + 1, 100, i + 1));
+    input[count - 1] = candidate(count, 1, count);
+    // A remembered key still deduplicates; an unremembered key passes through.
+    input.push({ ...input[0] }, { ...input[count - 1] });
+    const result = await deduplicateVisualCandidates(discovery(input));
+    expect(result.candidates).toEqual([...input.slice(0, count), input[count + 1]]);
+    expect(result.candidates[count - 1]).toBe(input[count - 1]);
+    expect(result).toMatchObject({
+      candidateCount: count + 2,
+      deduplicatedCount: 1,
+      dedupDegraded: true,
+    });
+  });
+
+  it("does not report degradation when every key fits", async () => {
+    const input = Array.from({ length: MAX_VISUAL_DEDUP_KEYS }, (_, i) => candidate(i, 1, i));
+    input.push({ ...input[0] });
+    const result = await deduplicateVisualCandidates(discovery(input));
+    expect(result.candidates).toHaveLength(MAX_VISUAL_DEDUP_KEYS);
+    expect(result.dedupDegraded).toBe(false);
+    expect(result.deduplicatedCount).toBe(1);
+  });
+
+  it("preserves upstream unknowns without counting issues as Canvas nodes", async () => {
+    const input: VisualDiscoveryResult = {
+      ...discovery([candidate(2)]),
+      complete: false,
+      issues: [{ reason: "geometry-unavailable", target: { tabId: 1 }, frameId: "missing" }],
+      captureIssues: [{ stage: "ax", reason: "capture-unavailable", target: { tabId: 1 } }],
+    };
+    const result = await deduplicateVisualCandidates(input);
+    expect(result.complete).toBe(false);
+    expect(result.candidateCount).toBe(1);
+    expect(result.issues).toBe(input.issues);
+    expect(result.captureIssues).toBe(input.captureIssues);
+    const absent = await deduplicateVisualCandidates({
+      ...input,
+      candidates: [],
+      issues: [{ reason: "visual-facts-not-collected" }],
+    });
+    expect(absent).toMatchObject({
+      complete: false,
+      candidateCount: 0,
+      issues: [{ reason: "visual-facts-not-collected" }],
+    });
+    expect(await deduplicateVisualCandidates(discovery([]))).toMatchObject({
+      complete: true,
+      candidates: [],
+      candidateCount: 0,
+      dedupDegraded: false,
+    });
+  });
+
+  it("drains cancellation through the shared checkpoint", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      deduplicateVisualCandidates(discovery([]), controller.signal),
+    ).rejects.toMatchObject({ name: "AbortError" });
+    const during = new AbortController();
+    const input = discovery(Array.from({ length: 100_000 }, (_, i) => candidate(i, 100, i)));
+    const timer = setTimeout(() => during.abort(), 0);
+    try {
+      await expect(deduplicateVisualCandidates(input, during.signal)).rejects.toMatchObject({
+        name: "AbortError",
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+});
@@ -0,0 +1,528 @@
+import { describe, expect, it } from "vitest";
+import type { CdpFrame } from "@/browser-driver/frame-graph";
+import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import type { GeometryProjection } from "../../geometry";
+import { buildDocumentIndex, type DocumentFacts, type ObservationFacts } from "../facts";
+import type { FrameOwnedAxNode } from "../frame-document";
+import { normalizeDocument } from "../normalize";
+import { VISUAL_SNAPSHOT, VISUAL_STYLES } from "../snapshot";
+import { discoverVisualCandidates } from "../visual-discovery";
+
+const defaults: Record<string, string> = {
+  position: "static",
+  "pointer-events": "auto",
+  cursor: "auto",
+  visibility: "visible",
+  opacity: "1",
+  display: "block",
+  "overflow-x": "visible",
+  "overflow-y": "visible",
+  transform: "none",
+  zoom: "1",
+  "clip-path": "none",
+  "mask-image": "none",
+  rotate: "none",
+  scale: "none",
+  perspective: "none",
+  clip: "auto",
+  contain: "none",
+  "overflow-clip-margin": "0px",
+};
+const projection: GeometryProjection = {
+  sourceClips: [],
+  edges: [],
+  topViewport: { width: 1000, height: 800 },
+};
+interface Spec {
+  id: number;
+  parent?: number;
+  tag?: string;
+  styles?: Record<string, string>;
+  bounds?: number[] | null;
+  client?: number[];
+  attrs?: Record<string, string>;
+}
+async function document(
+  nodes: Spec[],
+  options: {
+    frame?: CdpFrame;
+    projection?: GeometryProjection;
+    pageScale?: number;
+    scrollY?: number;
+    layoutScale?: number;
+  } = {},
+): Promise<DocumentFacts<FrameOwnedAxNode>> {
+  const frame = options.frame ?? { frameId: "main", target: { tabId: 1 } };
+  const strings: string[] = [];
+  const str = (value: string) => {
+    const index = strings.indexOf(value);
+    if (index >= 0) return index;
+    strings.push(value);
+    return strings.length - 1;
+  };
+  const input: Spec[] = [
+    { id: 0, tag: "#document", bounds: null },
+    { id: 1, parent: 0, tag: "html", bounds: [0, 0, 1000, 800] },
+    ...nodes,
+  ];
+  const layouts = input.filter((node) => node.bounds !== null);
+  const normalized = await normalizeDocument(
+    {
+      nodes: {
+        backendNodeId: input.map((n) => n.id),
+        nodeType: input.map((n) =>
+          n.tag === "#document" ? 9 : n.tag === "#document-fragment" ? 11 : 1,
+        ),
+        parentIndex: input.map((n) =>
+          n.parent === undefined ? -1 : input.findIndex((p) => p.id === n.parent),
+        ),
+        nodeName: input.map((n) => str(n.tag ?? "canvas")),
+        attributes: input.map((n) =>
+          Object.entries(n.attrs ?? {}).flatMap(([k, v]) => [str(k), str(v)]),
+        ),
+      },
+      layout: {
+        nodeIndex: layouts.map((n) => input.indexOf(n)),
+        bounds: layouts.map((n) => n.bounds ?? [10, 20, 120, 40]),
+        clientRects: layouts.map((n) => n.client ?? [0, 0, 1000, 800]),
+        styles: layouts.map((n) =>
+          VISUAL_STYLES.map((key) => str({ ...defaults, ...n.styles }[key])),
+        ),
+      },
+    },
+    strings,
+    {
+      frameId: frame.frameId,
+      ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
+      target: frame.target,
+      projection: {
+        status: "available",
+        projection: {
+          source: { target: frame.target, frameId: frame.frameId },
+          geometry: options.projection ?? projection,
+        },
+      },
+      coordinates: {
+        layoutUnitsPerCssPixel: options.layoutScale ?? 1,
+        scrollCss: { x: 0, y: options.scrollY ?? 0 },
+      },
+      pageScale: options.pageScale ?? 1,
+    },
+    undefined,
+    VISUAL_SNAPSHOT,
+  );
+  return {
+    frame,
+    identity: {
+      attachmentId: "attached",
+      target: frame.target,
+      frameId: frame.frameId,
+      documentElementBackendNodeId: 1,
+    },
+    index: normalized.index,
+    geometry: normalized.geometry,
+    domNodes: normalized.nodes,
+    axNodes: [],
+  };
+}
+function facts(
+  documents: DocumentFacts<FrameOwnedAxNode>[],
+  issues: ObservationFacts<FrameOwnedAxNode>["issues"] = [],
+): ObservationFacts<FrameOwnedAxNode> {
+  return {
+    visualFactsCollected: true,
+    rootFrameId: "main",
+    documents,
+    viewport: { width: 1000, height: 800 },
+    issues,
+    startedAt: 1,
+    finishedAt: 2,
+  };
+}
+
+describe("Canvas discovery", () => {
+  it("shares frame address paths from existing Facts without changing candidate evidence", async () => {
+    const parent = await document([{ id: 2, parent: 1, tag: "iframe" }]);
+    const child = await document(
+      [
+        { id: 3, parent: 1 },
+        { id: 4, parent: 1 },
+      ],
+      {
+        frame: {
+          frameId: "child",
+          parentFrameId: "main",
+          ownerBackendNodeId: 2,
+          target: { tabId: 1 },
+        },
+      },
+    );
+    const result = await discoverVisualCandidates(facts([child, parent]));
+    expect(result.candidates).toHaveLength(2);
+    const path = result.candidates[0].framePath;
+    expect(path).toBe(result.candidates[1].framePath);
+    expect(path?.document).toBe(child.identity);
+    expect(path?.parent?.ownerBackendNodeId).toBe(2);
+    expect(path?.parent?.frame.document).toBe(parent.identity);
+    expect(path?.parent?.frame.parent).toBeUndefined();
+  });
+
+  it("distinguishes visual facts not collected from complete empty discovery and honors cancellation", async () => {
+    const empty = facts([]);
+    expect(await discoverVisualCandidates(empty)).toMatchObject({
+      complete: true,
+      candidates: [],
+      issues: [],
+    });
+    expect(await discoverVisualCandidates({ ...empty, visualFactsCollected: false })).toMatchObject(
+      { complete: false, candidates: [], issues: [{ reason: "visual-facts-not-collected" }] },
+    );
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      discoverVisualCandidates({ ...empty, visualFactsCollected: false }, controller.signal),
+    ).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("discovers Canvas and frame contents without corner radius facts", async () => {
+    const own = await document([{ id: 2, parent: 1, styles: {} }]);
+    expect(await discoverVisualCandidates(facts([own]))).toMatchObject({
+      candidates: [{ backendNodeId: 2 }],
+      complete: true,
+      issues: [],
+    });
+    const parent = await document([{ id: 2, parent: 1, tag: "iframe", styles: {} }]);
+    const child = await document([{ id: 3, parent: 1 }], {
+      frame: {
+        frameId: "child",
+        parentFrameId: "main",
+        ownerBackendNodeId: 2,
+        target: { tabId: 1 },
+      },
+    });
+    expect(await discoverVisualCandidates(facts([parent, child]))).toMatchObject({
+      candidates: [{ backendNodeId: 3 }],
+      complete: true,
+      issues: [],
+    });
+  });
+
+  it.each([
+    0.8, 1, 1.25, 2,
+  ])("combines layout-unit bounds with CSS client clips at scale %s", async (scale) => {
+    const doc = await document(
+      [
+        {
+          id: 2,
+          parent: 1,
+          tag: "div",
+          bounds: [100, 200, 64, 34].map((n) => n * scale),
+          client: [2, 2, 60, 30],
+          styles: { "overflow-x": "hidden", "overflow-y": "hidden" },
+        },
+        { id: 3, parent: 2, bounds: [102, 202, 120, 40].map((n) => n * scale) },
+      ],
+      { layoutScale: scale, scrollY: 75 },
+    );
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.issues).toEqual([]);
+    const expected = {
+      borderBox: { x: 102, y: 127, width: 120, height: 40 },
+      crop: { x: 102, y: 127, width: 60, height: 30 },
+    };
+    for (const box of ["borderBox", "crop"] as const)
+      for (const key of ["x", "y", "width", "height"] as const)
+        expect(result.candidates[0].region[box][key]).toBeCloseTo(expected[box][key], 8);
+  });
+
+  it("normalizes a zero-width ancestor origin before one-axis clipping", async () => {
+    const doc = await document(
+      [
+        {
+          id: 2,
+          parent: 1,
+          tag: "div",
+          bounds: [200, 400, 0, 60],
+          client: [0, 0, 0, 30],
+          styles: { "overflow-y": "hidden" },
+        },
+        { id: 3, parent: 2, bounds: [200, 400, 240, 80] },
+      ],
+      { layoutScale: 2, scrollY: 75 },
+    );
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.issues).toEqual([]);
+    expect(result.candidates[0].region.crop).toEqual({ x: 100, y: 125, width: 120, height: 30 });
+  });
+
+  it("keeps unnamed, semantic, aria-hidden, inert, pointer-none and visibility override Canvas", async () => {
+    const doc = await document([
+      { id: 2, parent: 1 },
+      { id: 3, parent: 1, attrs: { "aria-label": "Chart" } },
+      {
+        id: 4,
+        parent: 1,
+        attrs: { "aria-hidden": "true", inert: "" },
+        styles: { "pointer-events": "none" },
+      },
+      { id: 5, parent: 1, tag: "div", styles: { visibility: "hidden" } },
+      { id: 6, parent: 5, styles: { visibility: "visible" } },
+      { id: 7, parent: 1, attrs: { hidden: "" }, styles: { display: "block" } },
+    ]);
+    doc.axNodes.push({ nodeId: "canvas", backendDOMNodeId: 2 } as FrameOwnedAxNode);
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.candidates.map((c) => c.backendNodeId)).toEqual([2, 3, 4, 6, 7]);
+    expect(result.candidates[1].label).toBe("Chart");
+    expect(result.complete).toBe(true);
+  });
+
+  it("excludes CSS transparent subtrees, hidden/zero/no-layout/fully clipped nodes and overlays", async () => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div", styles: { opacity: "0" } },
+      { id: 3, parent: 2 },
+      { id: 4, parent: 1, styles: { visibility: "hidden" } },
+      { id: 5, parent: 1, bounds: [0, 0, 0, 40] },
+      { id: 6, parent: 1, bounds: null },
+      { id: 7, parent: 1, bounds: [1200, 0, 100, 50] },
+      { id: 8, parent: 1, tag: "div", attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } },
+      { id: 9, parent: 8, tag: "#document-fragment", bounds: null },
+      { id: 10, parent: 9 },
+    ]);
+    expect(await discoverVisualCandidates(facts([doc]))).toMatchObject({
+      candidates: [],
+      issues: [],
+      complete: true,
+    });
+  });
+
+  it.each([
+    ["both", "hidden", "hidden", [0, 0, 60, 30], [60, 30]],
+    ["x", "clip", "visible", [0, 0, 60, 20], [60, 40]],
+    ["border", "hidden", "hidden", [5, 5, 68, 38], [64, 34]],
+  ])("uses client box for %s clipping", async (_name, x, y, client, expected) => {
+    const doc = await document([
+      {
+        id: 2,
+        parent: 1,
+        tag: "div",
+        bounds: [0, 0, 78, 48],
+        client: client as number[],
+        styles: { "overflow-x": x as string, "overflow-y": y as string },
+      },
+      {
+        id: 3,
+        parent: 2,
+        bounds: x === "clip" || _name === "both" ? [0, 0, 120, 40] : [9, 9, 120, 40],
+      },
+    ]);
+    const [candidate] = (await discoverVisualCandidates(facts([doc]))).candidates;
+    expect([candidate.region.crop.width, candidate.region.crop.height]).toEqual(expected);
+    expect(candidate.region.clips?.backendNodeId).toBe(2);
+  });
+
+  it("keeps Canvas border-box and clips partial viewport intersections", async () => {
+    const doc = await document([{ id: 2, parent: 1, bounds: [950, 20, 130, 50] }]);
+    const [candidate] = (await discoverVisualCandidates(facts([doc]))).candidates;
+    expect(candidate.region.borderBox.width).toBe(130);
+    expect(candidate.region.crop).toEqual({ x: 950, y: 20, width: 50, height: 50 });
+  });
+
+  it("propagates owner ancestry across targets, without depending on semantic parents", async () => {
+    const parent = await document([
+      {
+        id: 2,
+        parent: 1,
+        tag: "div",
+        bounds: [0, 0, 200, 100],
+        client: [0, 0, 200, 100],
+        styles: { "overflow-x": "hidden", "overflow-y": "hidden" },
+      },
+      { id: 3, parent: 2, tag: "iframe", bounds: [100, 0, 200, 200] },
+    ]);
+    parent.domNodes.splice(0); // Visual discovery never reads the semantic subset.
+    const child = await document([{ id: 2, parent: 1, bounds: [0, 0, 200, 200] }], {
+      frame: {
+        frameId: "child",
+        parentFrameId: "main",
+        ownerBackendNodeId: 3,
+        target: { tabId: 1, sessionId: "remote" },
+      },
+      projection: {
+        ...projection,
+        edges: [
+          {
+            sourceViewport: { width: 200, height: 200 },
+            destinationQuad: [
+              { x: 100, y: 0 },
+              { x: 300, y: 0 },
+              { x: 300, y: 200 },
+              { x: 100, y: 200 },
+            ],
+          },
+        ],
+      },
+    });
+    const result = await discoverVisualCandidates(facts([child, parent]));
+    expect(result.complete).toBe(true);
+    expect(result.candidates[0]).toMatchObject({
+      document: { frameId: "child", target: { sessionId: "remote" } },
+      region: { crop: { x: 100, y: 0, width: 100, height: 100 } },
+    });
+    const owner = parent.index.nodes.get(3)!;
+    owner.layout!.styles = { ...owner.layout!.styles, visibility: "hidden" };
+    expect((await discoverVisualCandidates(facts([parent, child]))).candidates).toHaveLength(0);
+  });
+
+  it.each<Record<string, string>>([
+    { transform: "matrix(0,1,-1,0,0,0)" },
+    { "clip-path": "circle(50%)" },
+    { "mask-image": "url(mask)" },
+    { zoom: "1.25", "overflow-x": "hidden" },
+  ])("reports unsupported ancestor geometry: %o", async (styles) => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div", styles },
+      { id: 3, parent: 2 },
+    ]);
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.candidates).toHaveLength(0);
+    expect(result.issues[0].reason).toBe("geometry-unsupported");
+  });
+
+  it("supports positive scale without overflow, rejects pinch and non-rectangular frame projection", async () => {
+    const nodes = [
+      {
+        id: 2,
+        parent: 1,
+        styles: { transform: "matrix(1.25,0,0,1.25,0,0)" },
+        bounds: [10, 20, 150, 50],
+      },
+    ];
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes)]))).candidates,
+    ).toHaveLength(1);
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes, { pageScale: 1.5 })]))).issues[0]
+        .reason,
+    ).toBe("geometry-unsupported");
+    const rotated = {
+      ...projection,
+      edges: [
+        {
+          sourceViewport: { width: 200, height: 200 },
+          destinationQuad: [
+            { x: 10, y: 0 },
+            { x: 200, y: 10 },
+            { x: 190, y: 200 },
+            { x: 0, y: 190 },
+          ] as [
+            { x: number; y: number },
+            { x: number; y: number },
+            { x: number; y: number },
+            { x: number; y: number },
+          ],
+        },
+      ],
+    };
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes, { projection: rotated })])))
+        .issues[0].reason,
+    ).toBe("geometry-unsupported");
+  });
+
+  it("keeps partial capture separate from valid geometry, rejects unverified identities", async () => {
+    const doc = await document([{ id: 2, parent: 1 }]);
+    const partial = facts(
+      [doc],
+      [{ target: doc.frame.target, frameId: "main", stage: "ax", reason: "capture-unavailable" }],
+    );
+    const result = await discoverVisualCandidates(partial);
+    expect(result.candidates).toHaveLength(1);
+    expect(result.captureIssues).toBe(partial.issues);
+    expect(result.complete).toBe(false);
+    const unverified = { ...doc, identity: undefined };
+    const failed = await discoverVisualCandidates(facts([unverified]));
+    expect(failed.candidates).toHaveLength(0);
+    expect(failed.issues[0].reason).toBe("identity-unverified");
+  });
+
+  it("does not trust orphan, cyclic, boxless or missing frame-owner ancestry", async () => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div" },
+      { id: 3, parent: 2 },
+    ]);
+    for (const parent of [99, 3]) {
+      doc.index.nodes.get(2)!.parentBackendNodeId = parent;
+      const index = await buildDocumentIndex([...doc.index.nodes.values()], undefined, true);
+      const result = await discoverVisualCandidates(facts([{ ...doc, index }]));
+      expect(result.candidates).toHaveLength(0);
+      expect(result.issues[0].reason).toBe("ancestry-incomplete");
+    }
+    const boxless = await document([
+      { id: 2, parent: 1, tag: "div", bounds: null },
+      { id: 3, parent: 2 },
+    ]);
+    expect((await discoverVisualCandidates(facts([boxless]))).issues[0].reason).toBe(
+      "facts-unavailable",
+    );
+    const child = {
+      ...doc,
+      frame: { ...doc.frame, frameId: "child", parentFrameId: "absent", ownerBackendNodeId: 2 },
+    };
+    expect((await discoverVisualCandidates(facts([child]))).issues[0].reason).toBe(
+      "ownership-unresolved",
+    );
+  });
+
+  it("is deterministic, does not deduplicate or mutate inputs", async () => {
+    const input = facts([
+      await document([
+        { id: 2, parent: 1 },
+        { id: 3, parent: 1 },
+      ]),
+    ]);
+    const freeze = (value: unknown): void => {
+      if (!value || typeof value !== "object" || Object.isFrozen(value)) return;
+      if (value instanceof Map) for (const item of value.values()) freeze(item);
+      for (const item of Object.values(value)) freeze(item);
+      Object.freeze(value);
+    };
+    freeze(input);
+    const first = await discoverVisualCandidates(input);
+    expect(await discoverVisualCandidates(input)).toEqual(first);
+    expect(first.candidates).toHaveLength(2);
+  });
+
+  it.each([
+    1000, 10000, 100000,
+  ])("memoizes deep ancestry across %i nodes and checks cancellation", async (count) => {
+    const doc = await document([{ id: 2, parent: 1 }]);
+    const template = doc.index.nodes.get(2)!;
+    let reads = 0;
+    const input = [doc.index.nodes.get(0)!, doc.index.nodes.get(1)!];
+    for (let id = 2; id < count + 2; id++) {
+      const node = {
+        ...template,
+        backendNodeId: id,
+        tag: id < count / 2 ? "div" : "canvas",
+        parentBackendNodeId: id < count / 2 ? id - 1 : count / 2 - 1,
+      };
+      Object.defineProperty(node, "parentBackendNodeId", {
+        get: () => {
+          reads++;
+          return id < count / 2 ? id - 1 : count / 2 - 1;
+        },
+      });
+      input.push(node);
+    }
+    const index = await buildDocumentIndex(input, undefined, true);
+    reads = 0;
+    const result = await discoverVisualCandidates(facts([{ ...doc, index }]));
+    expect(result.candidates).toHaveLength(count / 2 + 2);
+    expect(reads).toBeLessThan(count * 5);
+    const controller = new AbortController();
+    controller.abort();
+    await expect(discoverVisualCandidates(facts([doc]), controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+  });
+});
@@ -0,0 +1,250 @@
+import { describe, expect, it } from "vitest";
+import {
+  EMPTY_VISUAL_CONTEXT,
+  extendVisualContext,
+  projectVisualBox,
+  resolveVisualRegion,
+  type VisualAncestor,
+} from "../visual-region";
+
+const styles = {
+  position: "static",
+  visibility: "visible",
+  opacity: "1",
+  display: "block",
+  transform: "none",
+  zoom: "1",
+  "overflow-x": "visible",
+  "overflow-y": "visible",
+  "clip-path": "none",
+  "mask-image": "none",
+  rotate: "none",
+  scale: "none",
+  perspective: "none",
+  clip: "auto",
+  contain: "none",
+  "overflow-clip-margin": "0px",
+};
+const ancestor: VisualAncestor = {
+  document: {
+    attachmentId: "a",
+    target: { tabId: 1 },
+    frameId: "main",
+    documentElementBackendNodeId: 1,
+  },
+  backendNodeId: 2,
+  styles,
+  clientBox: { x: 5, y: 5, width: 60, height: 30 },
+};
+const box = { x: 0, y: 0, width: 120, height: 40 };
+
+describe("shared visual region rules", () => {
+  it.each([
+    "visible",
+    "hidden",
+    "auto",
+    "scroll",
+    "clip",
+  ])("keeps %s screenshot bounds independent of rounded styling", (overflow) => {
+    for (const clipContents of [true, false]) {
+      const node = {
+        ...ancestor,
+        styles: { ...styles, "overflow-x": overflow, "overflow-y": overflow },
+      };
+      const baseline = extendVisualContext(EMPTY_VISUAL_CONTEXT, node, clipContents);
+      for (const radius of ["0px", "8px", "50%", "4px 8px"]) {
+        const rounded = extendVisualContext(
+          EMPTY_VISUAL_CONTEXT,
+          {
+            ...node,
+            styles: {
+              ...node.styles,
+              "border-top-left-radius": radius,
+              "border-top-right-radius": radius,
+              "border-bottom-left-radius": radius,
+              "border-bottom-right-radius": radius,
+            },
+          },
+          clipContents,
+        );
+        expect(rounded).toEqual(baseline);
+        expect(
+          resolveVisualRegion({
+            borderBox: box,
+            frameVisibleBox: box,
+            visibility: "visible",
+            context: rounded,
+          }),
+        ).toMatchObject({ status: "available" });
+        expect(
+          resolveVisualRegion({
+            borderBox: box,
+            frameVisibleBox: box,
+            visibility: "hidden",
+            context: rounded,
+          }),
+        ).toEqual({ status: "empty" });
+        if (clipContents && overflow !== "visible")
+          expect(
+            resolveVisualRegion({
+              borderBox: box,
+              frameVisibleBox: { x: 80, y: 0, width: 20, height: 20 },
+              visibility: "visible",
+              context: rounded,
+            }),
+          ).toEqual({ status: "empty" });
+      }
+    }
+  });
+
+  it("accepts independently supplied normalized facts and preserves clipping policy", () => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, "overflow-x": "hidden" },
+    });
+    expect(
+      resolveVisualRegion({ borderBox: box, frameVisibleBox: box, visibility: "visible", context }),
+    ).toMatchObject({
+      status: "available",
+      crop: { x: 5, y: 0, width: 60, height: 40 },
+      clips: { overflowX: "hidden", overflowY: "visible" },
+    });
+    const differentPolicy = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, "overflow-x": "scroll" },
+    });
+    expect(differentPolicy.clip).toEqual(context.clip);
+    expect(differentPolicy.clips).not.toEqual(context.clips);
+  });
+
+  it("distinguishes fully clipped, missing client geometry and invalid rectangles", () => {
+    const clipping = { ...ancestor, styles: { ...styles, "overflow-x": "hidden" } };
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...clipping,
+      clientBox: { x: 0, y: 0, width: 0, height: 20 },
+    });
+    expect(
+      resolveVisualRegion({ borderBox: box, frameVisibleBox: box, visibility: "visible", context })
+        .status,
+    ).toBe("empty");
+    const unavailable = extendVisualContext(EMPTY_VISUAL_CONTEXT, { ...clipping, clientBox: null });
+    expect(
+      resolveVisualRegion({
+        borderBox: box,
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: unavailable,
+      }),
+    ).toEqual({ status: "unavailable", reason: "geometry-unavailable" });
+    expect(
+      resolveVisualRegion({
+        borderBox: { ...box, x: NaN },
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: EMPTY_VISUAL_CONTEXT,
+      }).status,
+    ).toBe("unavailable");
+    expect(projectVisualBox({ x: 5, y: 5, width: 0, height: 20 }, [])).toEqual({
+      x: 5,
+      y: 5,
+      width: 0,
+      height: 20,
+    });
+  });
+
+  it.each<Record<string, string>>([
+    { rotate: "45deg" },
+    { scale: "-1 1" },
+    { perspective: "100px" },
+    { clip: "rect(0px, 20px, 20px, 0px)" },
+    { contain: "paint" },
+    { "overflow-x": "clip", "overflow-clip-margin": "10px" },
+    { transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0.01,0,0,0,1)" },
+  ])("refuses unsupported CSS evidence without changing DOM geometry: %o", (change) => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, ...change },
+    });
+    expect(context.issue).toBe("geometry-unsupported");
+  });
+
+  it("accepts axis-preserving matrix3d translation and independent positive scale", () => {
+    for (const change of [
+      { transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,10,20,0,1)" },
+      { scale: "1.25" },
+    ])
+      expect(
+        extendVisualContext(EMPTY_VISUAL_CONTEXT, { ...ancestor, styles: { ...styles, ...change } })
+          .issue,
+      ).toBeUndefined();
+  });
+
+  it.each([
+    "matrix(1,0,0,1,0,0)",
+    "matrix(1,0,0,1,10,20)",
+  ])("accepts unscaled overflow transform %s", (transform) => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: {
+        ...styles,
+        transform,
+        position: "relative",
+        "overflow-x": "hidden",
+        "overflow-y": "hidden",
+      },
+    });
+    expect(context.issue).toBeUndefined();
+    const child = extendVisualContext(
+      context,
+      {
+        ...ancestor,
+        styles: {
+          ...styles,
+          position: "absolute",
+          "overflow-x": "clip",
+          "overflow-y": "clip",
+          "overflow-clip-margin": "content-box",
+        },
+      },
+      false,
+    );
+    expect(
+      resolveVisualRegion({
+        borderBox: box,
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: child,
+      }),
+    ).toMatchObject({ status: "available", crop: { x: 5, y: 5, width: 60, height: 30 } });
+  });
+
+  it("supports positioned overflow containers but refuses uncertain out-of-flow clipping", () => {
+    const overflow = { ...ancestor, styles: { ...styles, "overflow-x": "hidden" } };
+    const staticParent = extendVisualContext(EMPTY_VISUAL_CONTEXT, overflow);
+    expect(
+      extendVisualContext(
+        staticParent,
+        { ...ancestor, styles: { ...styles, position: "absolute" } },
+        false,
+      ).issue,
+    ).toBe("geometry-unsupported");
+    const positionedParent = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...overflow,
+      styles: { ...overflow.styles, position: "relative" },
+    });
+    const child = extendVisualContext(
+      positionedParent,
+      { ...ancestor, styles: { ...styles, position: "absolute" } },
+      false,
+    );
+    expect(child.issue).toBeUndefined();
+    expect(child.clip).toEqual(positionedParent.clip);
+    expect(
+      extendVisualContext(
+        positionedParent,
+        { ...ancestor, styles: { ...styles, position: "fixed" } },
+        false,
+      ).issue,
+    ).toBe("geometry-unsupported");
+  });
+});
@@ -22,7 +22,12 @@ import {
  type FrameOwnedAxNode,
 } from "./frame-document";
 import { type NormalizedFrameDocument, normalizeSnapshot } from "./normalize";
-import { describeSnapshotFrames, REQUESTED_STYLES, type SnapshotReply } from "./snapshot";
+import {
+  BASIC_SNAPSHOT,
+  describeSnapshotFrames,
+  type SnapshotReply,
+  VISUAL_SNAPSHOT,
+} from "./snapshot";

 interface TargetBatch<T extends FrameOwnedAxNode> {
  target: CdpTarget;
@@ -69,7 +74,9 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
  tabId: number,
  signal?: AbortSignal,
  pageUrl?: string,
+  options: { includeVisualFacts?: boolean } = {},
 ): Promise<ObservationFacts<T>> {
+  const profile = options.includeVisualFacts ? VISUAL_SNAPSHOT : BASIC_SNAPSHOT;
  const startedAt = Date.now();
  throwCaptureAborted(signal);
  let graph: CdpFrameGraph | undefined;
@@ -125,7 +132,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
        throwCaptureAborted(signal);
        batch.snapshotAttachmentId = cdp.getAttachmentId?.(tabId);
        const snapshot = await scoped.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
-          computedStyles: REQUESTED_STYLES,
+          computedStyles: profile.computedStyles,
          includePaintOrder: true,
          includeDOMRects: true,
        });
@@ -146,6 +153,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
          issues,
          signal,
          observed.rootFrameId,
+          profile,
        );
        const formsAvailable = await enrichFormControlStates(
          scoped,
@@ -375,6 +383,7 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
    facts.push({
      frame,
      identity: identities.get(document.frameId),
+      ...(doc?.geometry ? { geometry: doc.geometry } : {}),
      index: fallback?.size ? { ...index, excludedBackendNodeIds: fallback } : index,
      domNodes,
      axNodes,
@@ -383,7 +392,15 @@ export async function captureObservationFacts<T extends FrameOwnedAxNode>(
  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() };
+  return {
+    visualFactsCollected: profile.includeVisualFacts,
+    rootFrameId,
+    viewport,
+    documents: facts,
+    issues,
+    startedAt,
+    finishedAt: Date.now(),
+  };
 }

 /** Existing semantic consumers get a narrow view; no raw snapshot
@@ -2,6 +2,7 @@ import type { CdpRunner } from "../shared";
 import { sendToCdpTarget } from "../shared";
 import { isAbortError, throwIfAborted } from "./capture-abort";
 import type { DocumentIdentity } from "./facts";
+import type { VisualCandidate } from "./visual-discovery";

 /** Compare the snapshot root with the current root in that exact frame.
 * Deep serialization supplies the backend ID without a separate describeNode. */
@@ -10,44 +11,110 @@ export async function verifyDocumentIdentity(
  identity: DocumentIdentity,
  signal?: AbortSignal,
 ): Promise<"current" | "changed" | "unavailable"> {
+  return (await verifyIdentity(cdp, identity, signal)).status;
+}
+
+/** Verify the visual anchor in its original frame; geometry is checked by screenshot execution. */
+export async function verifyVisualTargetIdentity(
+  cdp: CdpRunner,
+  candidate: VisualCandidate,
+  signal?: AbortSignal,
+): Promise<"current" | "changed" | "unavailable"> {
+  return (await verifyIdentity(cdp, candidate.document, signal, candidate.backendNodeId)).status;
+}
+
+export type VerifiedNodeResult =
+  | { status: "changed" | "unavailable" }
+  | { status: "current"; objectId: string; objectGroup: string };
+
+/** Caller must release objectGroup in finally after its local read. */
+export async function resolveVerifiedNode(
+  cdp: CdpRunner,
+  identity: DocumentIdentity,
+  backendNodeId: number,
+  signal?: AbortSignal,
+): Promise<VerifiedNodeResult> {
+  const result = await verifyIdentity(cdp, identity, signal, backendNodeId, true);
+  return result.status === "current" && result.objectId && result.objectGroup
+    ? { status: "current", objectId: result.objectId, objectGroup: result.objectGroup }
+    : { status: result.status === "changed" ? "changed" : "unavailable" };
+}
+
+async function verifyIdentity(
+  cdp: CdpRunner,
+  identity: DocumentIdentity,
+  signal?: AbortSignal,
+  anchorBackendNodeId?: number,
+  retain = false,
+): Promise<{
+  status: "current" | "changed" | "unavailable";
+  objectId?: string;
+  objectGroup?: string;
+}> {
  const attached = () => cdp.getAttachmentId?.(identity.target.tabId) === identity.attachmentId;
  throwIfAborted(signal);
-  if (!attached()) return "changed";
+  if (!attached()) return { status: "changed" };
  const objectGroup = `bsk-document-identity-${crypto.randomUUID()}`;
  const send = <T>(method: string, params: object) => {
    throwIfAborted(signal);
    return sendToCdpTarget<T>(cdp, identity.target, method, params);
  };
+  let objectId: string | undefined;
+  let retained = false;
  try {
    const world = await send<{ executionContextId: number }>("Page.createIsolatedWorld", {
      frameId: identity.frameId,
      worldName: "bsk-document-identity",
    });
-    const reply = await send<{
+    const serializationOptions = {
+      serialization: "deep",
+      additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+    };
+    type RootReply = {
      result?: { deepSerializedValue?: { type: string; value?: { backendNodeId?: number } } };
-    }>("Runtime.evaluate", {
-      expression: "document.documentElement",
-      contextId: world.executionContextId,
-      objectGroup,
-      serializationOptions: {
-        serialization: "deep",
-        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
-      },
-    });
-    if (!attached()) return "changed";
+    };
+    let reply: RootReply;
+    if (anchorBackendNodeId === undefined) {
+      reply = await send<RootReply>("Runtime.evaluate", {
+        expression: "document.documentElement",
+        contextId: world.executionContextId,
+        objectGroup,
+        serializationOptions,
+      });
+    } else {
+      const anchor = await send<{ object?: { objectId?: string } }>("DOM.resolveNode", {
+        backendNodeId: anchorBackendNodeId,
+        executionContextId: world.executionContextId,
+        objectGroup,
+      });
+      if (!anchor.object?.objectId) return { status: "unavailable" };
+      objectId = anchor.object.objectId;
+      reply = await send<RootReply>("Runtime.callFunctionOn", {
+        objectId: anchor.object.objectId,
+        functionDeclaration:
+          "function() { return this.isConnected && this.ownerDocument === document ? document.documentElement : null; }",
+        objectGroup,
+        serializationOptions,
+      });
+    }
+    if (!attached()) return { status: "changed" };
    const root = reply.result?.deepSerializedValue;
-    if (root?.type === "null") return "changed";
+    if (root?.type === "null") return { status: "changed" };
    const id = root?.type === "node" ? root.value?.backendNodeId : undefined;
-    if (id === undefined) return "unavailable";
-    return id === identity.documentElementBackendNodeId ? "current" : "changed";
+    if (id === undefined) return { status: "unavailable" };
+    if (id !== identity.documentElementBackendNodeId) return { status: "changed" };
+    throwIfAborted(signal);
+    retained = retain && !!objectId;
+    return { status: "current", ...(retained ? { objectId, objectGroup } : {}) };
  } catch (error) {
    throwIfAborted(signal);
    if (isAbortError(error)) throw error;
-    return attached() ? "unavailable" : "changed";
+    return { status: attached() ? "unavailable" : "changed" };
  } finally {
-    await sendToCdpTarget(cdp, identity.target, "Runtime.releaseObjectGroup", {
-      objectGroup,
-    }).catch(() => {});
+    if (!retained)
+      await sendToCdpTarget(cdp, identity.target, "Runtime.releaseObjectGroup", {
+        objectGroup,
+      }).catch(() => {});
    throwIfAborted(signal);
  }
 }
@@ -1,7 +1,8 @@
 import type { 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 { GeometryProjection } from "../geometry";
+import type { FrameProjectionIssue, SnapshotCoordinates } from "../geometry/coordinate-types";
 import { createCaptureCheckpoint } from "./capture-abort";
 import type { CapturedNode } from "./capture-types";
 import type { FrameOwnedAxNode } from "./frame-document";
@@ -10,21 +11,26 @@ import type { FrameOwnedAxNode } from "./frame-document";
 export interface SnapshotLayout {
  readonly boundsSpace: "snapshot-document-layout";
  bounds?: number[];
+  /** [clientLeft, clientTop, clientWidth, clientHeight], untransformed local CSS units. */
+  clientRect?: number[];
  styles: Readonly<Record<string, string>>;
 }

 export interface DecodedNode extends Omit<CapturedNode, "rect" | "localRect" | "rendered"> {
  nodeType?: number;
+  parentMissing?: boolean;
  layout?: SnapshotLayout;
 }

 export interface NodeFacts extends CapturedNode {
  nodeType?: number;
+  parentMissing?: boolean;
  layout?: SnapshotLayout;
 }

 export interface DocumentIndex<T extends DecodedNode = NodeFacts> {
  readonly nodes: ReadonlyMap<number, T>;
+  readonly ancestryComplete?: ReadonlyMap<number, boolean>;
  readonly excludedBackendNodeIds: ReadonlySet<number>;
 }

@@ -37,10 +43,12 @@ export interface DecodedDocument {
 export async function buildDocumentIndex<T extends DecodedNode>(
  input: readonly T[],
  signal?: AbortSignal,
+  includeVisualFacts = false,
 ): Promise<DocumentIndex<T>> {
  const checkpoint = createCaptureCheckpoint(signal);
  const nodes = new Map<number, T>();
  const overlayByNode = new Map<number, boolean>();
+  const ancestryComplete = includeVisualFacts ? new Map<number, boolean>() : undefined;
  const excludedBackendNodeIds = new Set<number>();
  for (let i = 0; i < input.length; i++) {
    if (i % 256 === 0) {
@@ -61,6 +69,7 @@ export async function buildDocumentIndex<T extends DecodedNode>(
    const visiting = new Set<number>();
    let current: DecodedNode | undefined = node;
    let overlay = false;
+    let complete = false;
    while (current && !overlayByNode.has(current.backendNodeId)) {
      if (work++ % 256 === 0) {
        const pending = checkpoint();
@@ -76,13 +85,16 @@ export async function buildDocumentIndex<T extends DecodedNode>(
      visiting.add(current.backendNodeId);
      path.push(current);
      if (current.parentBackendNodeId === null) {
+        if (ancestryComplete) complete = !current.parentMissing && current.nodeType === 9;
        current = undefined;
        break;
      }
      current = nodes.get(current.parentBackendNodeId);
    }
-    if (current && overlayByNode.has(current.backendNodeId))
+    if (current && overlayByNode.has(current.backendNodeId)) {
      overlay = overlayByNode.get(current.backendNodeId)!;
+      if (ancestryComplete) complete = ancestryComplete.get(current.backendNodeId) === true;
+    }
    for (let i = path.length - 1; i >= 0; i--) {
      if (work++ % 256 === 0) {
        const pending = checkpoint();
@@ -91,10 +103,14 @@ export async function buildDocumentIndex<T extends DecodedNode>(
      const item = path[i];
      overlay = overlay || isOverlayHostNode(item.tag, Object.keys(item.attrs));
      overlayByNode.set(item.backendNodeId, overlay);
+      if (ancestryComplete) {
+        complete = complete && !item.parentMissing;
+        ancestryComplete.set(item.backendNodeId, complete);
+      }
      if (overlay) excludedBackendNodeIds.add(item.backendNodeId);
    }
  }
-  return { nodes, excludedBackendNodeIds };
+  return { nodes, ...(ancestryComplete ? { ancestryComplete } : {}), excludedBackendNodeIds };
 }

 export interface DocumentIdentity {
@@ -127,7 +143,16 @@ export interface CaptureIssue {
    | "geometry-unavailable";
 }

+/** Shared per document; never retain the live GeometryContext in published facts. */
+export interface DocumentGeometry {
+  readonly projections: readonly GeometryProjection[];
+  readonly coordinates: SnapshotCoordinates;
+  /** Visual viewport scale (pinch), distinct from browser UI zoom. */
+  readonly pageScale?: number;
+}
+
 export interface DocumentFacts<T extends FrameOwnedAxNode> {
+  readonly geometry?: DocumentGeometry;
  readonly frame: CdpFrame;
  readonly identity?: DocumentIdentity;
  readonly index: DocumentIndex;
@@ -136,6 +161,8 @@ export interface DocumentFacts<T extends FrameOwnedAxNode> {
 }

 export interface ObservationFacts<T extends FrameOwnedAxNode> {
+  /** Whether visual collection was enabled; partial capture failures remain in issues. */
+  readonly visualFactsCollected: boolean;
  readonly rootFrameId: string;
  readonly viewport: Viewport;
  readonly documents: readonly DocumentFacts<T>[];
@@ -18,10 +18,18 @@ import {
  isAbortError as isCaptureAbort,
  throwIfAborted as throwCaptureAborted,
 } from "./capture-abort";
-import { buildDocumentIndex, type CaptureIssue, type DocumentIndex, type NodeFacts } from "./facts";
 import {
+  buildDocumentIndex,
+  type CaptureIssue,
+  type DocumentGeometry,
+  type DocumentIndex,
+  type NodeFacts,
+} from "./facts";
+import {
+  BASIC_SNAPSHOT,
  decodeDocument,
  type SnapshotDocument,
+  type SnapshotProfile,
  type SnapshotReply,
  snapshotFrameId,
 } from "./snapshot";
@@ -33,9 +41,11 @@ export interface FrameContext {
  targetProjection?: GeometryProjection | null;
  target: CdpTarget;
  coordinates: SnapshotCoordinates | null;
+  pageScale?: number;
 }

 export interface NormalizedDocument {
+  geometry?: DocumentGeometry;
  nodes: NodeFacts[];
  index: DocumentIndex;
  documentElementBackendNodeId?: number;
@@ -47,8 +57,9 @@ export async function normalizeDocument(
  strings: string[],
  context: FrameContext,
  signal?: AbortSignal,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
 ): Promise<NormalizedDocument> {
-  const decoded = await decodeDocument(doc, strings, signal);
+  const decoded = await decodeDocument(doc, strings, signal, profile);
  const checkpoint = createCaptureCheckpoint(signal);
  const nodes: NodeFacts[] = [];
  for (let i = 0; i < decoded.nodes.length; i++) {
@@ -93,12 +104,27 @@ export async function normalizeDocument(
        (Number.parseFloat(opacity) || 0) > 0,
    });
  }
-  const index = await buildDocumentIndex(nodes, signal);
+  const index = await buildDocumentIndex(nodes, signal, profile.includeVisualFacts);
  return {
    nodes: nodes.filter(
      (node) => !node.tag.startsWith("#") && !index.excludedBackendNodeIds.has(node.backendNodeId),
    ),
    index,
+    ...(profile.includeVisualFacts &&
+    context.coordinates &&
+    context.projection?.status === "available" &&
+    context.targetProjection !== null
+      ? {
+          geometry: {
+            projections: [
+              context.projection.projection.geometry,
+              ...(context.targetProjection ? [context.targetProjection] : []),
+            ],
+            coordinates: context.coordinates,
+            pageScale: context.pageScale,
+          },
+        }
+      : {}),
    documentElementBackendNodeId: nodes.find(
      (node) =>
        node.nodeType === 1 &&
@@ -122,6 +148,7 @@ export async function normalizeSnapshot(
  issues: CaptureIssue[],
  signal?: AbortSignal,
  rootFrameId?: string,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
 ): Promise<NormalizedFrameDocument[]> {
  const strings = snapshot.strings ?? [];
  const raw = snapshot.documents ?? [];
@@ -313,11 +340,15 @@ export async function normalizeSnapshot(
        frameId: frame.frameId,
        ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
        projection: state,
+        ...(profile.includeVisualFacts
+          ? { pageScale: metrics.cssVisualViewport?.scale ?? metrics.visualViewport?.scale }
+          : {}),
        target,
        ...(target.sessionId ? { targetProjection } : {}),
        coordinates,
      },
      signal,
+      profile,
    );
    result.push({ ...normalized, frame });
  }
@@ -9,9 +9,30 @@ export const REQUESTED_STYLES = [
  "visibility",
  "opacity",
 ] as const;
-const STYLE_COL = Object.fromEntries(
-  REQUESTED_STYLES.map((name, index) => [name, index]),
-) as Record<(typeof REQUESTED_STYLES)[number], number>;
+export const VISUAL_STYLES = [
+  ...REQUESTED_STYLES,
+  "display",
+  "overflow-x",
+  "overflow-y",
+  "transform",
+  "zoom",
+  "clip-path",
+  "mask-image",
+  "rotate",
+  "scale",
+  "perspective",
+  "clip",
+  "contain",
+  "overflow-clip-margin",
+] as const;
+
+/** The same profile owns request columns, decoding and visual-only derived facts. */
+export const BASIC_SNAPSHOT = {
+  includeVisualFacts: false,
+  computedStyles: REQUESTED_STYLES,
+} as const;
+export const VISUAL_SNAPSHOT = { includeVisualFacts: true, computedStyles: VISUAL_STYLES } as const;
+export type SnapshotProfile = typeof BASIC_SNAPSHOT | typeof VISUAL_SNAPSHOT;
 /** Sparse array format Chrome uses for infrequently-set per-node fields. */
 interface SparseArray {
  index: number[];
@@ -49,6 +70,7 @@ export interface SnapshotDocument {
    nodeIndex?: number[];
    styles?: number[][];
    bounds?: number[][];
+    clientRects?: number[][];
    paintOrders?: number[];
  };
 }
@@ -103,6 +125,7 @@ export async function decodeDocument(
  doc: SnapshotDocument,
  strings: string[],
  signal?: AbortSignal,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
 ): Promise<DecodedDocument> {
  const checkpoint = createCaptureCheckpoint(signal);
  const dn = doc.nodes;
@@ -170,13 +193,17 @@ export async function decodeDocument(
    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]]);
+    for (let i = 0; i < profile.computedStyles.length; i++)
+      styles[profile.computedStyles[i]] = str(strings, styleRow[i]);
    const layout =
      li === undefined
        ? undefined
        : {
            boundsSpace: "snapshot-document-layout" as const,
            bounds: dl?.bounds?.[li],
+            ...(profile.includeVisualFacts && dl?.clientRects?.[li]
+              ? { clientRect: dl.clientRects[li] }
+              : {}),
            styles,
          };

@@ -200,6 +227,10 @@ export async function decodeDocument(
      backendNodeId,
      nodeType: dn.nodeType?.[n],
      parentBackendNodeId,
+      ...(profile.includeVisualFacts &&
+      (dn.parentIndex?.[n] === undefined || (parentIdx >= 0 && parentBackendNodeId === null))
+        ? { parentMissing: true }
+        : {}),

      tag,
      attrs,
@@ -0,0 +1,64 @@
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { VisualCandidate, VisualDiscoveryResult } from "./visual-discovery";
+
+export const MAX_VISUAL_DEDUP_KEYS = 50_000;
+
+export interface VisualDedupResult extends VisualDiscoveryResult {
+  /** Known valid candidates in this capture, not the total Canvas count on the page. */
+  readonly candidateCount: number;
+  /** Candidates actually removed by exact coverage deduplication. */
+  readonly deduplicatedCount: number;
+  readonly dedupDegraded: boolean;
+}
+
+/** Keep the first real anchor for each exact DOM/parent/crop key, in encounter order.
+ * Once the key set is full, unknown keys pass through: capacity never drops candidates. */
+export async function deduplicateVisualCandidates(
+  discovery: VisualDiscoveryResult,
+  signal?: AbortSignal,
+): Promise<VisualDedupResult> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  const keys = new Set<string>();
+  const candidates: VisualCandidate[] = [];
+  let deduplicatedCount = 0;
+  let dedupDegraded = false;
+  for (let i = 0; i < discovery.candidates.length; i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const candidate = discovery.candidates[i];
+    const {
+      document,
+      region: { crop },
+    } = candidate;
+    const key = JSON.stringify([
+      document.attachmentId,
+      document.target.tabId,
+      document.target.sessionId ?? null,
+      document.frameId,
+      document.documentElementBackendNodeId,
+      candidate.parentBackendNodeId,
+      crop.x,
+      crop.y,
+      crop.width,
+      crop.height,
+    ]);
+    if (keys.has(key)) {
+      deduplicatedCount++;
+      continue;
+    }
+    if (keys.size < MAX_VISUAL_DEDUP_KEYS) keys.add(key);
+    else dedupDegraded = true;
+    candidates.push(candidate);
+  }
+  const pending = checkpoint();
+  if (pending) await pending;
+  return {
+    ...discovery,
+    candidates,
+    candidateCount: discovery.candidates.length,
+    deduplicatedCount,
+    dedupDegraded,
+  };
+}
@@ -0,0 +1,341 @@
+import { type CdpTarget } from "@/browser-driver/frame-graph";
+import type { ViewportRect } from "../geometry";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type {
+  CaptureIssue,
+  DocumentFacts,
+  DocumentIdentity,
+  NodeFacts,
+  ObservationFacts,
+} from "./facts";
+import type { FrameOwnedAxNode } from "./frame-document";
+import {
+  EMPTY_VISUAL_CONTEXT,
+  extendVisualContext,
+  projectVisualBox,
+  resolveVisualRegion,
+  type VisualContext,
+  type VisualIssueReason,
+  type VisualRegionResult,
+  visualProjectionIssue,
+} from "./visual-region";
+
+/** Shared observation-time addresses, not cached live geometry. */
+export interface VisualFramePath {
+  readonly document: DocumentIdentity;
+  readonly parent?: { readonly ownerBackendNodeId: number; readonly frame: VisualFramePath };
+}
+
+export interface VisualCandidate {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly parentBackendNodeId: number | null;
+  readonly label?: string;
+  /** Absent when execution ancestry could not be established; discovery is still retained. */
+  readonly framePath?: VisualFramePath;
+  readonly region: Extract<VisualRegionResult, { status: "available" }>;
+}
+
+export type VisualDiscoveryIssue =
+  | {
+      readonly reason: "visual-facts-not-collected";
+      readonly target?: never;
+      readonly frameId?: never;
+      readonly backendNodeId?: never;
+    }
+  | {
+      readonly target: CdpTarget;
+      readonly frameId: string;
+      readonly backendNodeId?: number;
+      readonly reason: VisualIssueReason;
+    };
+
+export interface VisualDiscoveryResult {
+  readonly candidates: readonly VisualCandidate[];
+  readonly issues: readonly VisualDiscoveryIssue[];
+  /** Preserve upstream failures, including those that do not invalidate Canvas geometry. */
+  readonly captureIssues: readonly CaptureIssue[];
+  readonly complete: boolean;
+}
+
+type Document = DocumentFacts<FrameOwnedAxNode>;
+interface NodeContext {
+  self: VisualContext;
+  children: VisualContext;
+}
+
+function viewportRect(
+  rect: { x: number; y: number; w: number; h: number } | null | undefined,
+): ViewportRect | null {
+  return rect ? { x: rect.x, y: rect.y, width: rect.w, height: rect.h } : null;
+}
+
+/** Client offsets are unscaled local CSS units. Only ordinary, untransformed
+ * overflow chains consume this adapter; other combinations are rejected by policy. */
+function clientBox(node: NodeFacts, document: Document): ViewportRect | null {
+  const client = node.layout?.clientRect;
+  const bounds = node.layout?.bounds;
+  const border =
+    node.localRect ??
+    (bounds?.length === 4 && bounds.every(Number.isFinite) && document.geometry
+      ? {
+          x:
+            bounds[0] / document.geometry.coordinates.layoutUnitsPerCssPixel -
+            document.geometry.coordinates.scrollCss.x,
+          y:
+            bounds[1] / document.geometry.coordinates.layoutUnitsPerCssPixel -
+            document.geometry.coordinates.scrollCss.y,
+        }
+      : null);
+  if (
+    !client ||
+    client.length !== 4 ||
+    !client.every(Number.isFinite) ||
+    client[2] < 0 ||
+    client[3] < 0 ||
+    !border ||
+    !document.geometry
+  )
+    return null;
+  return projectVisualBox(
+    { x: border.x + client[0], y: border.y + client[1], width: client[2], height: client[3] },
+    document.geometry.projections,
+  );
+}
+
+/** Pure Facts consumer: no CDP, ref registration, selection, or semantic keep/drop.
+ * Both frame and node ancestry are memoized in this call, using iterative walks. */
+export async function discoverVisualCandidates(
+  facts: ObservationFacts<FrameOwnedAxNode>,
+  signal?: AbortSignal,
+): Promise<VisualDiscoveryResult> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  if (!facts.visualFactsCollected)
+    return {
+      candidates: [],
+      complete: false,
+      captureIssues: facts.issues,
+      issues: [{ reason: "visual-facts-not-collected" }],
+    };
+  let work = 0;
+  const candidates: VisualCandidate[] = [];
+  const issues: VisualDiscoveryIssue[] = [];
+  const documents = new Map(facts.documents.map((document) => [document.frame.frameId, document]));
+  const framePaths = new Map<string, VisualFramePath>();
+  const contexts = new Map<string, Map<number, NodeContext>>();
+  const roots = new Map<string, VisualContext>();
+
+  async function nodeContext(document: Document, id: number): Promise<NodeContext> {
+    const cache = contexts.get(document.frame.frameId)!;
+    const path: NodeFacts[] = [];
+    let node = document.index.nodes.get(id);
+    while (node && !cache.has(node.backendNodeId)) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (
+        !document.index.ancestryComplete?.get(node.backendNodeId) ||
+        path.length >= document.index.nodes.size
+      ) {
+        const incomplete = {
+          ...roots.get(document.frame.frameId)!,
+          issue: roots.get(document.frame.frameId)!.issue ?? ("ancestry-incomplete" as const),
+        };
+        cache.set(node.backendNodeId, { self: incomplete, children: incomplete });
+        break;
+      }
+      path.push(node);
+      node =
+        node.parentBackendNodeId === null
+          ? undefined
+          : document.index.nodes.get(node.parentBackendNodeId);
+    }
+    let parent = node
+      ? cache.get(node.backendNodeId)!.children
+      : roots.get(document.frame.frameId)!;
+    for (let i = path.length - 1; i >= 0; i--) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      const current = path[i];
+      let self = parent;
+      let children = parent;
+      if (document.index.excludedBackendNodeIds.has(current.backendNodeId)) {
+        self = children = { ...parent, hidden: true };
+      } else if (current.nodeType === 1) {
+        if (!current.layout) {
+          // An element without layout is not evidence that descendants are hidden
+          // (e.g. a boxless ancestor). Keep the missing style evidence explicit.
+          self = children = { ...parent, issue: parent.issue ?? "facts-unavailable" };
+        } else if (document.identity) {
+          const ancestor = {
+            document: document.identity,
+            backendNodeId: current.backendNodeId,
+            styles: current.layout.styles,
+            clientBox: clientBox(current, document),
+          };
+          children = extendVisualContext(
+            parent,
+            ancestor,
+            current.tag !== "iframe" && current.tag !== "frame",
+          );
+          self = current.tag === "canvas" ? extendVisualContext(parent, ancestor, false) : children;
+        }
+      }
+      const result = { self, children };
+      cache.set(current.backendNodeId, result);
+      parent = children;
+    }
+    return (
+      cache.get(id) ?? {
+        self: { ...parent, issue: "ancestry-incomplete" },
+        children: { ...parent, issue: "ancestry-incomplete" },
+      }
+    );
+  }
+
+  // Process parent documents first, independent of snapshot/target completion order.
+  for (const document of facts.documents) {
+    const path: Document[] = [];
+    const visiting = new Set<string>();
+    let current: Document | undefined = document;
+    while (current && !roots.has(current.frame.frameId)) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (visiting.has(current.frame.frameId)) {
+        roots.set(current.frame.frameId, {
+          ...EMPTY_VISUAL_CONTEXT,
+          issue: "ownership-unresolved",
+        });
+        contexts.set(current.frame.frameId, new Map());
+        break;
+      }
+      visiting.add(current.frame.frameId);
+      path.push(current);
+      current = current.frame.parentFrameId
+        ? documents.get(current.frame.parentFrameId)
+        : undefined;
+    }
+    for (let i = path.length - 1; i >= 0; i--) {
+      const doc = path[i];
+      const { frame } = doc;
+      let root: VisualContext = roots.get(frame.frameId) ?? EMPTY_VISUAL_CONTEXT;
+      if (frame.parentFrameId) {
+        const parent = documents.get(frame.parentFrameId);
+        if (
+          !parent ||
+          !roots.has(parent.frame.frameId) ||
+          frame.ownerBackendNodeId === undefined ||
+          !parent.identity
+        ) {
+          root = { ...root, issue: "ownership-unresolved" };
+        } else {
+          const owner = parent.index.nodes.get(frame.ownerBackendNodeId);
+          const ownerState = await nodeContext(parent, frame.ownerBackendNodeId);
+          root = {
+            ...ownerState.children,
+            // CSS visibility inside a child document cannot override its hidden owner.
+            hidden:
+              ownerState.children.hidden ||
+              owner?.layout?.styles.visibility === "hidden" ||
+              owner?.layout?.styles.visibility === "collapse",
+            // Frame scaling is already interpreted by the shared content-quad projection.
+            transformed: false,
+            localClip: false,
+            unpositionedClip: false,
+          };
+        }
+      } else if (frame.frameId !== facts.rootFrameId)
+        root = { ...root, issue: "ownership-unresolved" };
+      root = {
+        ...root,
+        issue:
+          root.issue ??
+          (!doc.identity ? "identity-unverified" : visualProjectionIssue(doc.geometry)),
+      };
+      if (doc.identity) {
+        const parentPath = frame.parentFrameId ? framePaths.get(frame.parentFrameId) : undefined;
+        if (!frame.parentFrameId && frame.frameId === facts.rootFrameId)
+          framePaths.set(frame.frameId, { document: doc.identity });
+        else if (parentPath && frame.ownerBackendNodeId !== undefined)
+          framePaths.set(frame.frameId, {
+            document: doc.identity,
+            parent: { ownerBackendNodeId: frame.ownerBackendNodeId, frame: parentPath },
+          });
+      }
+      roots.set(frame.frameId, root);
+      contexts.set(frame.frameId, new Map());
+    }
+  }
+
+  for (const document of facts.documents) {
+    for (const node of document.index.nodes.values()) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (node.tag !== "canvas" || document.index.excludedBackendNodeIds.has(node.backendNodeId))
+        continue;
+      // No layout/zero size is positive evidence of no screenshot area for this node.
+      if (!node.layout) continue;
+      const bounds = node.layout.bounds;
+      if (
+        bounds?.length === 4 &&
+        bounds.every(Number.isFinite) &&
+        (bounds[2] <= 0 || bounds[3] <= 0)
+      )
+        continue;
+      const context = (await nodeContext(document, node.backendNodeId)).self;
+      const local = viewportRect(node.localRect);
+      const borderBox =
+        local && document.geometry ? projectVisualBox(local, document.geometry.projections) : null;
+      const region = resolveVisualRegion({
+        borderBox,
+        frameVisibleBox: viewportRect(node.rect),
+        context,
+        visibility: node.layout.styles.visibility,
+      });
+      if (region.status === "unavailable") {
+        issues.push({
+          target: document.frame.target,
+          frameId: document.frame.frameId,
+          backendNodeId: node.backendNodeId,
+          reason: region.reason,
+        });
+      } else if (region.status === "available" && document.identity) {
+        const label = node.attrs["aria-label"]?.trim() || node.attrs.title?.trim();
+        candidates.push({
+          document: document.identity,
+          framePath: framePaths.get(document.frame.frameId),
+          backendNodeId: node.backendNodeId,
+          parentBackendNodeId: node.parentBackendNodeId,
+          ...(label ? { label } : {}),
+          region,
+        });
+      }
+    }
+  }
+  // AX-only/missing documents have no Canvas nodes to carry the missing evidence.
+  const reportedFrames = new Set(issues.map((issue) => issue.frameId));
+  for (const document of facts.documents) {
+    const reason = roots.get(document.frame.frameId)?.issue;
+    if (
+      reason &&
+      !reportedFrames.has(document.frame.frameId) &&
+      (!document.identity || !document.index.nodes.size)
+    )
+      issues.push({ target: document.frame.target, frameId: document.frame.frameId, reason });
+  }
+  const pending = checkpoint();
+  if (pending) await pending;
+  return {
+    candidates,
+    issues,
+    captureIssues: facts.issues,
+    complete: issues.length === 0 && facts.issues.length === 0,
+  };
+}
@@ -0,0 +1,318 @@
+import {
+  type GeometryProjection,
+  type Polygon,
+  projectPolygon,
+  rectPolygon,
+  regionBounds,
+  type ViewportRect,
+} from "../geometry";
+import type { DocumentGeometry, DocumentIdentity } from "./facts";
+
+export type VisualIssueReason =
+  | "ancestry-incomplete"
+  | "facts-unavailable"
+  | "geometry-unavailable"
+  | "geometry-unsupported"
+  | "identity-unverified"
+  | "ownership-unresolved";
+
+/** Top viewport CSS coordinates. Unconstrained axes have infinite bounds. */
+export interface VisualClip {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/** Shared persistent chain: one entry per clipping ancestor, not per Canvas. */
+export interface VisualClipSource {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly x: boolean;
+  readonly y: boolean;
+  readonly overflowX: string;
+  readonly overflowY: string;
+  readonly box: ViewportRect;
+  readonly parent?: VisualClipSource;
+}
+
+export interface VisualContext {
+  readonly clip: VisualClip;
+  readonly clips?: VisualClipSource;
+  readonly hidden: boolean;
+  /** A local CSS scale/zoom makes snapshot client offsets ambiguous. */
+  readonly transformed: boolean;
+  readonly localClip?: boolean;
+  /** Overflow between an absolute target and its nearest positioned ancestor. */
+  readonly unpositionedClip?: boolean;
+  readonly issue?: VisualIssueReason;
+}
+
+export const EMPTY_VISUAL_CONTEXT: VisualContext = {
+  clip: { left: -Infinity, top: -Infinity, right: Infinity, bottom: Infinity },
+  hidden: false,
+  transformed: false,
+};
+
+function axisRect(polygon: Polygon): boolean {
+  if (polygon.length !== 4 || polygon.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y)))
+    return false;
+  const [a, b, c, d] = polygon;
+  return a.y === b.y && b.x === c.x && c.y === d.y && d.x === a.x && b.x > a.x && d.y > a.y;
+}
+
+/** Check evidence before projectRectToViewport can reduce a polygon to its bounds. */
+export function visualProjectionIssue(
+  geometry: DocumentGeometry | undefined,
+): VisualIssueReason | undefined {
+  if (!geometry || !geometry.projections.length || geometry.pageScale === undefined)
+    return "geometry-unavailable";
+  if (!Number.isFinite(geometry.pageScale) || geometry.pageScale <= 0)
+    return "geometry-unavailable";
+  if (geometry.pageScale !== 1) return "geometry-unsupported";
+  const { layoutUnitsPerCssPixel, scrollCss } = geometry.coordinates;
+  if (
+    !Number.isFinite(layoutUnitsPerCssPixel) ||
+    layoutUnitsPerCssPixel <= 0 ||
+    ![scrollCss.x, scrollCss.y].every(Number.isFinite)
+  )
+    return "geometry-unavailable";
+  for (const projection of geometry.projections) {
+    if (
+      ![projection.topViewport.width, projection.topViewport.height].every(
+        (n) => Number.isFinite(n) && n > 0,
+      )
+    )
+      return "geometry-unavailable";
+    if (projection.sourceClips.some((clip) => !axisRect(clip))) return "geometry-unsupported";
+    for (const edge of projection.edges) {
+      if (
+        ![edge.sourceViewport.width, edge.sourceViewport.height].every(
+          (n) => Number.isFinite(n) && n > 0,
+        )
+      )
+        return "geometry-unavailable";
+      if (!axisRect(edge.destinationQuad) || edge.destinationClips?.some((clip) => !axisRect(clip)))
+        return "geometry-unsupported";
+    }
+  }
+}
+
+/** Uses the same projection math as DOM geometry, without clipping away box origins. */
+export function projectVisualBox(
+  box: ViewportRect,
+  projections: readonly GeometryProjection[],
+): ViewportRect | null {
+  let polygon: Polygon = rectPolygon({ x: box.x, y: box.y, w: box.width, h: box.height });
+  for (const projection of projections)
+    for (const edge of projection.edges) polygon = projectPolygon(polygon, edge);
+  // Preserve zero-size client boxes: they can prove a fully clipped axis.
+  if (box.width === 0 || box.height === 0) {
+    const [a, , c] = polygon;
+    return { x: a.x, y: a.y, width: c.x - a.x, height: c.y - a.y };
+  }
+  return regionBounds([polygon]);
+}
+
+function axisTransformScale(value: string): [number, number] | null {
+  if (value === "none") return [1, 1];
+  const match = /^matrix(3d)?\(([^)]+)\)$/.exec(value);
+  if (!match) return null;
+  const values = match[2].split(",").map((part) => Number(part.trim()));
+  if (!values.every(Number.isFinite)) return null;
+  if (match[1])
+    return values.length === 16 &&
+      values[0] > 0 &&
+      values[5] > 0 &&
+      values[10] === 1 &&
+      values[15] === 1 &&
+      [1, 2, 3, 4, 6, 7, 8, 9, 11, 14].every((index) => values[index] === 0)
+      ? [values[0], values[5]]
+      : null;
+  return values.length === 6 && values[0] > 0 && values[3] > 0 && values[1] === 0 && values[2] === 0
+    ? [values[0], values[3]]
+    : null;
+}
+
+export interface VisualAncestor {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly styles: Readonly<Record<string, string>>;
+  /** Already in top viewport CSS units, from a source-specific adapter. */
+  readonly clientBox?: ViewportRect | null;
+}
+
+/** One ancestor step, reusable by discovery and the future live local adapter. */
+export function extendVisualContext(
+  parent: VisualContext,
+  node: VisualAncestor,
+  clipContents = true,
+): VisualContext {
+  const styles = node.styles;
+  const opacity = styles.opacity?.trim() ? Number(styles.opacity) : NaN;
+  const zoom = styles.zoom === "normal" ? 1 : styles.zoom?.trim() ? Number(styles.zoom) : NaN;
+  const scale =
+    styles.scale === "none" ? [1] : (styles.scale ?? "").trim().split(/\s+/).map(Number);
+  const scaleSupported =
+    scale.length >= 1 &&
+    scale.length <= 3 &&
+    scale.every((n) => Number.isFinite(n) && n > 0) &&
+    (scale.length < 3 || scale[2] === 1);
+  const transformScale = axisTransformScale(styles.transform ?? "");
+  // Identity/translation changes origins, which bounds already capture, but
+  // leaves client offsets in the same units. Only scaling makes them ambiguous.
+  const transformed =
+    parent.transformed ||
+    transformScale?.some((n) => n !== 1) === true ||
+    zoom !== 1 ||
+    scale.some((n) => n !== 1);
+  const hidden = parent.hidden || opacity === 0 || styles.display === "none";
+  let issue = parent.issue;
+  if (
+    !Number.isFinite(opacity) ||
+    !Number.isFinite(zoom) ||
+    zoom <= 0 ||
+    !styles.display ||
+    !styles.visibility
+  )
+    issue ??= "facts-unavailable";
+  if (!styles.transform || !styles["clip-path"] || !styles["mask-image"])
+    issue ??= "facts-unavailable";
+  else if (!transformScale || styles["clip-path"] !== "none" || styles["mask-image"] !== "none")
+    issue ??= "geometry-unsupported";
+
+  if (
+    !["rotate", "scale", "perspective", "clip", "contain", "overflow-clip-margin"].every(
+      (key) => styles[key],
+    )
+  )
+    issue ??= "facts-unavailable";
+  else if (
+    !scaleSupported ||
+    !["none", "0deg"].includes(styles.rotate) ||
+    styles.perspective !== "none" ||
+    styles.clip !== "auto" ||
+    /(?:^|\s)(paint|strict|content)(?:$|\s)/.test(styles.contain)
+  )
+    issue ??= "geometry-unsupported";
+  // Do not pretend every DOM ancestor clips out-of-flow descendants. Support
+  // the ordinary positioned-container case; other containing-block cases stay explicit.
+  if (
+    (styles.position === "absolute" && parent.unpositionedClip) ||
+    (styles.position === "fixed" && parent.localClip)
+  )
+    issue ??= "geometry-unsupported";
+  const overflow = [styles["overflow-x"], styles["overflow-y"]];
+  if (clipContents && overflow.includes("clip") && styles["overflow-clip-margin"] !== "0px")
+    issue ??= "geometry-unsupported";
+  if (
+    overflow.some(
+      (value) => !["visible", "hidden", "clip", "scroll", "auto", "overlay"].includes(value),
+    )
+  )
+    issue ??= "facts-unavailable";
+  const [x, y] = overflow.map((value) => value !== "visible");
+  let clip = parent.clip;
+  let clips = parent.clips;
+  if (clipContents && (x || y)) {
+    if (transformed) issue ??= "geometry-unsupported";
+    const box = node.clientBox;
+    if (
+      !box ||
+      ![box.x, box.y, box.width, box.height].every(Number.isFinite) ||
+      box.width < 0 ||
+      box.height < 0
+    )
+      issue ??= "geometry-unavailable";
+    else {
+      clip = {
+        left: x ? Math.max(clip.left, box.x) : clip.left,
+        right: x ? Math.min(clip.right, box.x + box.width) : clip.right,
+        top: y ? Math.max(clip.top, box.y) : clip.top,
+        bottom: y ? Math.min(clip.bottom, box.y + box.height) : clip.bottom,
+      };
+      clips = {
+        document: node.document,
+        backendNodeId: node.backendNodeId,
+        x,
+        y,
+        overflowX: styles["overflow-x"],
+        overflowY: styles["overflow-y"],
+        box,
+        parent: clips,
+      };
+    }
+  }
+  const clipsHere = clipContents && (x || y);
+  return {
+    hidden,
+    transformed,
+    issue,
+    clip,
+    clips,
+    localClip: parent.localClip || clipsHere,
+    unpositionedClip:
+      styles.position !== "static" ||
+      styles.transform !== "none" ||
+      /(?:^|\s)layout(?:$|\s)/.test(styles.contain ?? "")
+        ? false
+        : parent.unpositionedClip || clipsHere,
+  };
+}
+
+/** A page screenshot rectangle, not an exact mask of visible Canvas pixels.
+ * Rounded corners are rendered by the browser and do not invalidate this range. */
+export type VisualRegionResult =
+  | { status: "available"; borderBox: ViewportRect; crop: ViewportRect; clips?: VisualClipSource }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: VisualIssueReason };
+
+/** Box and frameVisibleBox must come from the same box kind (Canvas border-box).
+ * Frame/viewport clipping is supplied by the shared geometry adapter. */
+export function resolveVisualRegion(input: {
+  borderBox: ViewportRect | null;
+  frameVisibleBox: ViewportRect | null;
+  context: VisualContext;
+  visibility: string;
+}): VisualRegionResult {
+  const { borderBox, frameVisibleBox, context, visibility } = input;
+  if (context.hidden || visibility === "hidden" || visibility === "collapse")
+    return { status: "empty" };
+  if (context.issue) return { status: "unavailable", reason: context.issue };
+  if (visibility !== "visible") return { status: "unavailable", reason: "facts-unavailable" };
+  if (!borderBox) return { status: "unavailable", reason: "geometry-unavailable" };
+  if (!frameVisibleBox) return { status: "empty" };
+  if (
+    ![
+      borderBox.x,
+      borderBox.y,
+      borderBox.width,
+      borderBox.height,
+      frameVisibleBox.x,
+      frameVisibleBox.y,
+      frameVisibleBox.width,
+      frameVisibleBox.height,
+    ].every(Number.isFinite)
+  )
+    return { status: "unavailable", reason: "geometry-unavailable" };
+  if (
+    borderBox.width <= 0 ||
+    borderBox.height <= 0 ||
+    frameVisibleBox.width < 0 ||
+    frameVisibleBox.height < 0 ||
+    Object.values(context.clip).some(Number.isNaN)
+  )
+    return { status: "unavailable", reason: "geometry-unavailable" };
+  const x = Math.max(frameVisibleBox.x, context.clip.left);
+  const y = Math.max(frameVisibleBox.y, context.clip.top);
+  const right = Math.min(frameVisibleBox.x + frameVisibleBox.width, context.clip.right);
+  const bottom = Math.min(frameVisibleBox.y + frameVisibleBox.height, context.clip.bottom);
+  return right > x && bottom > y
+    ? {
+        status: "available",
+        borderBox,
+        crop: { x, y, width: right - x, height: bottom - y },
+        clips: context.clips,
+      }
+    : { status: "empty" };
+}
@@ -24,6 +24,9 @@ export type RpcErrorReason =
  | "agent_window_scope"
  | "element_not_visible"
  | "ref_not_found"
+  | "ref_kind_unsupported"
+  | "visual_target_changed"
+  | "visual_pixel_budget_exceeded"
  | "selector_not_found"
  | "target_not_fillable"
  | "fill_value_invalid"
@@ -40,6 +40,9 @@ 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 VISUAL_TARGET_CHANGED: &str = "visual_target_changed";
+    pub const VISUAL_PIXEL_BUDGET_EXCEEDED: &str = "visual_pixel_budget_exceeded";
+    pub const REF_KIND_UNSUPPORTED: &str = "ref_kind_unsupported";
    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";
@@ -247,6 +250,25 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
            ),
            exit_code: base.exit_code,
        },
+        (ErrorCode::NotFound, reason::VISUAL_TARGET_CHANGED) => RenderInfo {
+            summary: "visual target needs a fresh observation",
+            hint: Some(
+                "observe the page again and use the current visual ref; the previous identity or region cannot be used",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::VISUAL_PIXEL_BUDGET_EXCEEDED) => RenderInfo {
+            summary: "visual screenshot exceeds the image size limit",
+            hint: Some("the screenshot could not be reduced within the pixel budget"),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::Unsupported, reason::REF_KIND_UNSUPPORTED) => RenderInfo {
+            summary: "this tool does not support the ref target type",
+            hint: Some(
+                "use a DOM ref for DOM operations; visual-region refs require an available visual screenshot path",
+            ),
+            exit_code: base.exit_code,
+        },
        (ErrorCode::NotFound, reason::REF_NOT_FOUND) => RenderInfo {
            summary: "snapshot ref was not found for this tab",
            hint: Some("rerun `bsk snapshot` for the current tab and use one of the returned refs"),
@@ -664,6 +686,25 @@ mod tests {
        assert!(info.summary.contains("timed out after browser dispatch"));
    }

+    #[test]
+    fn visual_screenshot_failures_have_specific_guidance() {
+        let changed = serde_json::json!({ "reason": reason::VISUAL_TARGET_CHANGED });
+        let info = info_for_error(ErrorCode::NotFound, Some(&changed));
+        assert!(info.hint.unwrap().contains("observe"));
+        let budget = serde_json::json!({ "reason": reason::VISUAL_PIXEL_BUDGET_EXCEEDED });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&budget));
+        assert!(info.summary.contains("image size limit"));
+    }
+
+    #[test]
+    fn visual_ref_type_error_has_specific_guidance() {
+        let data = serde_json::json!({ "reason": reason::REF_KIND_UNSUPPORTED });
+        let info = info_for_error(ErrorCode::Unsupported, Some(&data));
+        assert!(info.summary.contains("ref target type"));
+        assert!(info.hint.unwrap().contains("DOM ref"));
+        assert_eq!(info.exit_code, info_for(ErrorCode::Unsupported).exit_code);
+    }
+
    #[test]
    fn ref_not_found_overrides_not_found_copy() {
        let data = serde_json::json!({ "reason": reason::REF_NOT_FOUND });
Author	SHA1	Message	Date
Ljy-0827	e4d91976d4	fix: bugfix CI	2026-09-10 12:23:18 +08:00
Ljy-0827	31ddcb139c	feat: support on-demand screenshots for canvas visual refs	2026-09-10 12:21:20 +08:00
Ljy-0827	a6de73aea3	feat(vom): add typed visual refs and target identity validation	2026-09-10 12:21:20 +08:00
Ljy-0827	fecb38b44c	refactor(vom): preserve complete canvas candidates with exact deduplication	2026-09-10 12:21:19 +08:00
Ljy-0827	52a8e65b34	fix(vom): fix border radius incorrectly reject canvas	2026-09-10 12:21:19 +08:00
Ljy-0827	eb6cc0419b	feat(vom): discover canvas candidates and resolve visible regions	2026-09-10 12:21:19 +08:00