feat(vom): actions refactor

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

apps/extension/src/tools/interaction.ts

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

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

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

apps/extension/src/tools/observation.ts

@@ -8,6 +8,7 @@ import {
   applyVomInteractionRecovery,
   type CondSurface,
   isVomReferenceNode,
+  type Rect,
   renderVom,
   type VomNode,
   type VomOptions,
@@ -47,6 +48,8 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
+import { surfaceVisibleRect } from "./surface-coordinate";
+import { captureSurfaceEnvironment } from "./surface-target";
 import {
   type CapturedNode,
   type CapturedSurfaceProbe,
@@ -62,6 +65,11 @@ import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
+import {
+  clusterRenderedSurfaces,
+  discoverRenderedSurfaces,
+  projectRenderedSurfaces,
+} from "./vom/rendered-surfaces";
 import {
   buildSemanticGraph,
   buildSemanticVomScene,
@@ -93,6 +101,9 @@ export const normaliseRef = sharedNormaliseRef;
 // screenshot — `tool.screenshot`
 // ---------------------------------------------------------------------------
 
+const VISUAL_SURFACE_SCREENSHOT_MAX_EDGE = 2_048;
+const VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS = 4_000_000;
+
 /**
  * Strip the `data:image/...;base64,` prefix from a Chrome
  * `captureVisibleTab` dataURL and return the raw base64 payload.
@@ -107,8 +118,8 @@ export function stripDataUrlPrefix(dataUrl: string): string {
 
 /**
  * Parse a PNG's IHDR chunk and return `(width, height)`. Returns
- * `null` on any malformed input so callers fall back to `0/0` instead
- * of throwing.
+ * `null` on malformed input so callers can reject dimensions that are
+ * not authoritative instead of guessing from a CSS-space rectangle.
  *
  * PNG layout: 8-byte signature, then a 4-byte length, 4-byte type
  * ("IHDR"), then the chunk data — width is bytes 16-19 BE, height is
@@ -120,9 +131,9 @@ export function parsePngDimensions(base64: string): { width: number; height: num
     const head = base64.length > 64 ? base64.slice(0, 64) : base64;
     const bin = atob(head);
     if (bin.length < 24) return null;
-    if (bin.charCodeAt(0) !== 0x89 || bin.charCodeAt(1) !== 0x50 || bin.charCodeAt(2) !== 0x4e) {
-      return null;
-    }
+    const expectedSignature = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+    if (expectedSignature.some((byte, index) => bin.charCodeAt(index) !== byte)) return null;
+    if (bin.slice(12, 16) !== "IHDR") return null;
     const u32 = (off: number) =>
       (bin.charCodeAt(off) << 24) |
       (bin.charCodeAt(off + 1) << 16) |
@@ -185,18 +196,42 @@ async function captureElementScreenshot(
   target: CdpTarget,
   backendNodeId: number,
   frameId?: string,
+  visualSurface = false,
+  observedVisibleRect?: Rect,
   signal?: AbortSignal,
-): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
+): Promise<
+  { image_base64: string; width: number; height: number; topViewportRect: Rect } | RpcError
+> {
   if (signal?.aborted) return cancelled("screenshot");
   const geometry = await resolveNodeGeometry(
     cdp,
     tabId,
     { target, backendNodeId, ...(frameId ? { frameId } : {}) },
-    { scrollIntoView: true },
+    { scrollIntoView: !visualSurface },
   );
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
-  const rect = geometry.topBounds;
+  const topViewportRect = surfaceVisibleRect(
+    geometry.topBounds,
+    visualSurface ? observedVisibleRect : undefined,
+  );
+  if (!topViewportRect) {
+    return { code: "permission_denied", message: "surface is no longer visible" };
+  }
+  const rect = {
+    x: topViewportRect.x,
+    y: topViewportRect.y,
+    width: topViewportRect.w,
+    height: topViewportRect.h,
+  };
+  const scale = visualSurface
+    ? Math.min(
+        1,
+        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.width,
+        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.height,
+        Math.sqrt(VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS / (rect.width * rect.height)),
+      )
+    : 1;
 
   try {
     const shot = await cdp.send<{ data?: string }>(tabId, "Page.captureScreenshot", {
@@ -206,7 +241,7 @@ async function captureElementScreenshot(
         y: rect.y,
         width: rect.width,
         height: rect.height,
-        scale: 1,
+        scale,
       },
     });
     if (signal?.aborted) return cancelled("screenshot");
@@ -214,11 +249,11 @@ async function captureElementScreenshot(
     if (!image_base64) {
       return { code: "cdp_failed", message: "Page.captureScreenshot returned no data" };
     }
-    const dims = parsePngDimensions(image_base64) ?? {
-      width: Math.round(rect.width),
-      height: Math.round(rect.height),
-    };
-    return { image_base64, width: dims.width, height: dims.height };
+    const dims = parsePngDimensions(image_base64);
+    if (!dims) {
+      return { code: "cdp_failed", message: "Page.captureScreenshot returned invalid PNG data" };
+    }
+    return { image_base64, width: dims.width, height: dims.height, topViewportRect };
   } catch (err) {
     return {
       code: "cdp_failed",
@@ -313,7 +348,7 @@ export async function handleScreenshot(
     if (!deps.cdp) {
       return { code: "cdp_failed", message: "screenshot ref capture requires CDP" };
     }
-    const node = resolveSnapshotRef(ctx, ref, target.tabId);
+    const node = resolveSnapshotRef(ctx, ref, target.tabId, "screenshot");
     if (isRpcError(node)) return node;
     if (signal?.aborted) return cancelled("screenshot");
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
@@ -333,18 +368,54 @@ export async function handleScreenshot(
           nodeTarget,
           node.backendNodeId,
           node.frameId,
+          node.kind === "surface",
+          node.visibleRect,
           signal,
         ),
       deps.sendToTab,
     );
     if (isRpcError(captured)) return captured;
     if (signal?.aborted) return cancelled("screenshot");
+    const capture =
+      node.kind === "surface"
+        ? await (async () => {
+            const environment = await captureSurfaceEnvironment(cdp, target.tabId, node.frameId);
+            if (isRpcError(environment)) return environment;
+            return ctx.surfaceCaptures.create({
+              sessionId: ctx.sessionId,
+              tabId: target.tabId,
+              navigationIdentity: environment.navigationIdentity,
+              surface: {
+                ref: node.refKey,
+                ...(node.frameId ? { frameId: node.frameId } : {}),
+                backendNodeId: node.backendNodeId,
+                observationGeneration: node.generation,
+              },
+              topViewportRect: captured.topViewportRect,
+              imageWidth: captured.width,
+              imageHeight: captured.height,
+              viewportSignature: environment.viewportSignature,
+              frameProjectionSignature: environment.frameProjectionSignature,
+            });
+          })()
+        : null;
+    if (capture && isRpcError(capture)) return capture;
     return withShotDialogs({
       image_base64: captured.image_base64,
       width: captured.width,
       height: captured.height,
       format: "png",
       tab_id: target.tabId,
+      ...(capture
+        ? {
+            capture: {
+              id: capture.id,
+              surface_ref: `@${capture.surface.ref}`,
+              coordinate_space: "capture-image-pixel" as const,
+              expires_at: capture.expiresAt,
+            },
+          }
+        : {}),
     });
   }
 
@@ -364,7 +435,10 @@ export async function handleScreenshot(
   if (isRpcError(captured)) return captured;
   if (signal?.aborted) return cancelled("screenshot");
   const image_base64 = captured;
-  const dims = parsePngDimensions(image_base64) ?? { width: 0, height: 0 };
+  const dims = parsePngDimensions(image_base64);
+  if (!dims) {
+    return { code: "cdp_failed", message: "screenshot capture returned invalid PNG data" };
+  }
   return withShotDialogs({
     image_base64,
     width: dims.width,
@@ -1083,6 +1157,7 @@ async function runHoverProbes(
 
 export interface CaptureVomObservationOptions extends VomOptions {
   conditionalSurfaceProbe?: boolean;
+  renderedSurfaceDiscovery?: boolean;
   hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
   signal?: AbortSignal;
 }
@@ -1131,7 +1206,20 @@ export async function captureVomObservation(
     captured,
     hoverProbes.surfaceProbes,
   );
-  const rendered = renderVom(decoratedScene, {
+  const observedScene = options.renderedSurfaceDiscovery
+    ? projectRenderedSurfaces(
+        decoratedScene,
+        normalizedDocuments,
+        clusterRenderedSurfaces(
+          discoverRenderedSurfaces(
+            normalizedDocuments,
+            captured.viewport,
+            captured.excludedBackendNodeIds,
+          ),
+        ),
+      )
+    : decoratedScene;
+  const rendered = renderVom(observedScene, {
     maxDepth: options.maxDepth,
     maxTokens: options.maxTokens,
     redactValues: options.redactValues,
@@ -1186,6 +1274,7 @@ async function handleVomObservation(
       maxTokens: params.max_tokens,
       activeRegionPolicy: true,
       conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
+      renderedSurfaceDiscovery: toolName === "observe",
       hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
       signal,
     });
@@ -1203,6 +1292,9 @@ async function handleVomObservation(
             tabId: target.tabId,
             ...(ref.frameId ? { frameId: ref.frameId } : {}),
             ...(refTarget?.sessionId ? { cdpSessionId: refTarget.sessionId } : {}),
+            ...(ref.visibleRect ? { visibleRect: ref.visibleRect } : {}),
+            ...(ref.kind ? { kind: ref.kind } : {}),
+            ...(ref.capabilities ? { capabilities: ref.capabilities } : {}),
           },
         ] as const;
       }),

apps/extension/src/tools/session.ts

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

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

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

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

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

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

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

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

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
 import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
+import { discoverRenderedSurfaces } from "../rendered-surfaces";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
 // fixed full-screen overlay div carrying a password input.
@@ -735,6 +736,44 @@ describe("captureViewModel", () => {
     expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
   });
 
+  it("propagates fully transparent ancestor suppression to painted descendants", async () => {
+    const S = ["html", "body", "div", "canvas", "static", "auto", "visible", "1", "0"];
+    const i = (value: string) => S.indexOf(value);
+    const snapshot = {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 2],
+            nodeName: [i("html"), i("body"), i("div"), i("canvas")],
+            backendNodeId: [10, 11, 12, 13],
+            attributes: [[], [], [], []],
+          },
+          layout: {
+            nodeIndex: [1, 2, 3],
+            styles: [
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+            ],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 200, 100],
+              [10, 10, 200, 100],
+            ],
+            paintOrders: [0, 1, 2],
+          },
+        },
+      ],
+    };
+
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+    const canvas = nodes.find((node) => node.backendNodeId === 13);
+
+    expect(canvas?.rendered).toBe(true);
+    expect(canvas?.visuallySuppressed).toBe(true);
+  });
+
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {
@@ -1150,6 +1189,97 @@ describe("captureViewModel", () => {
     expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
   });
 
+  it("keeps same-origin iframe canvas discovery in top-level CSS coordinates at dpr 1 and 2", async () => {
+    const captureAtDpr = async (dpr: number) => {
+      const S = ["html", "body", "iframe", "canvas", "static", "auto"];
+      const i = (s: string) => S.indexOf(s);
+      const scale = (values: number[]) => values.map((value) => value * dpr);
+      const snapshot = {
+        strings: S,
+        documents: [
+          {
+            frameId: "main",
+            nodes: {
+              parentIndex: [-1, 0, 1],
+              nodeName: [i("html"), i("body"), i("iframe")],
+              backendNodeId: [10, 11, 13],
+              attributes: [[], [], []],
+              contentDocumentIndex: { index: [2], value: [1] },
+            },
+            layout: {
+              nodeIndex: [1, 2],
+              styles: [
+                [i("static"), i("auto")],
+                [i("static"), i("auto")],
+              ],
+              bounds: [scale([0, 0, 1000, 800]), scale([100, 150, 300, 200])],
+              paintOrders: [0, 1],
+            },
+          },
+          {
+            frameId: "child",
+            nodes: {
+              parentIndex: [-1, 0],
+              nodeName: [i("body"), i("canvas")],
+              backendNodeId: [20, 21],
+              attributes: [[], []],
+            },
+            layout: {
+              nodeIndex: [0, 1],
+              styles: [
+                [i("static"), i("auto")],
+                [i("static"), i("auto")],
+              ],
+              bounds: [scale([0, 0, 300, 200]), scale([20, 30, 120, 60])],
+              paintOrders: [0, 1],
+            },
+          },
+        ],
+      };
+      const cdp = {
+        send: vi.fn(async (_tabId: number, method: string) => {
+          if (method === "DOMSnapshot.enable") return {};
+          if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+          if (method === "Page.getLayoutMetrics") {
+            return {
+              cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+              layoutViewport: { clientWidth: 1000 * dpr, clientHeight: 800 * dpr },
+            };
+          }
+          throw new Error(method);
+        }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+      };
+      const captured = await captureViewModel(cdp, 4);
+      const childNodes = captured.frameNodes?.get("child") ?? [];
+      return discoverRenderedSurfaces(
+        [
+          {
+            frameId: "child",
+            contextScopeId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 13,
+            target: { tabId: 4 },
+            domNodes: childNodes,
+            axNodes: [],
+          },
+        ],
+        captured.viewport,
+      );
+    };
+
+    const atDpr1 = await captureAtDpr(1);
+    const atDpr2 = await captureAtDpr(2);
+
+    expect(atDpr1).toEqual([
+      expect.objectContaining({
+        backendNodeId: 21,
+        frameId: "child",
+        visibleRect: { x: 120, y: 180, w: 120, h: 60 },
+      }),
+    ]);
+    expect(atDpr2).toEqual(atDpr1);
+  });
+
   it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);

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

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

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

@@ -11,7 +11,15 @@ import { childFrameProjection, type GeometryProjection, projectRectToViewport }
 import type { CdpRunner } from "../shared";
 import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
+const REQUESTED_STYLES = [
+  "position",
+  "pointer-events",
+  "cursor",
+  "visibility",
+  "opacity",
+  "overflow-x",
+  "overflow-y",
+] as const;
 const STYLE_COL = Object.fromEntries(
   REQUESTED_STYLES.map((name, index) => [name, index]),
 ) as Record<(typeof REQUESTED_STYLES)[number], number>;
@@ -39,6 +47,10 @@ export interface CapturedNode {
    * `textContent`: the live parser always sets it, hand-built fixtures may not.
    */
   cursor?: string;
+  overflowX?: string;
+  overflowY?: string;
+  /** True when this node or one of its DOM ancestors makes the subtree fully transparent/hidden. */
+  visuallySuppressed?: boolean;
   /**
    * Whether the live DOM snapshot provides a painted, non-hidden box for this
    * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
@@ -849,6 +861,8 @@ function parseDocumentNodes(
   const cursorCol = STYLE_COL.cursor;
   const visibilityCol = STYLE_COL.visibility;
   const opacityCol = STYLE_COL.opacity;
+  const overflowXCol = STYLE_COL["overflow-x"];
+  const overflowYCol = STYLE_COL["overflow-y"];
   const inputValues = sparseIndexMap(dn.inputValue);
   const textValues = sparseIndexMap(dn.textValue);
   const checkedInputs = new Set(dn.inputChecked?.index ?? []);
@@ -874,6 +888,7 @@ function parseDocumentNodes(
 
   // Build CapturedNodes.
   const nodes: CapturedNode[] = [];
+  const visuallySuppressedByNodeIndex = new Array<boolean>(count).fill(false);
   for (let n = 0; n < count; n++) {
     if (excluded[n]) continue;
     const backendNodeId = dn.backendNodeId[n];
@@ -893,7 +908,11 @@ function parseDocumentNodes(
     let position = "static";
     let pointerEvents = "auto";
     let cursor = "auto";
+    let overflowX = "visible";
+    let overflowY = "visible";
     let rendered = false;
+    let visuallySuppressed =
+      parentIdx >= 0 ? visuallySuppressedByNodeIndex[parentIdx] === true : false;
     const li = layoutByNode.get(n);
     if (li !== undefined) {
       const b = dl?.bounds?.[li];
@@ -916,12 +935,19 @@ function parseDocumentNodes(
       cursor = str(strings, styleRow[cursorCol]) || "auto";
       const visibility = str(strings, styleRow[visibilityCol]) || "visible";
       const opacity = str(strings, styleRow[opacityCol]) || "1";
+      overflowX = str(strings, styleRow[overflowXCol]) || "visible";
+      overflowY = str(strings, styleRow[overflowYCol]) || "visible";
+      visuallySuppressed ||=
+        visibility === "hidden" ||
+        visibility === "collapse" ||
+        (Number.parseFloat(opacity) || 0) <= 0;
       rendered =
         localRect !== null &&
         visibility !== "hidden" &&
         visibility !== "collapse" &&
         (Number.parseFloat(opacity) || 0) > 0;
     }
+    visuallySuppressedByNodeIndex[n] = visuallySuppressed;
 
     // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
     // geometry and are never queried by callers.
@@ -956,6 +982,9 @@ function parseDocumentNodes(
       position,
       pointerEvents,
       cursor,
+      overflowX,
+      overflowY,
+      visuallySuppressed,
       rendered,
       textContent,
       ...(formValue !== undefined ? { formValue } : {}),

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

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

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

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

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

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

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

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

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

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

apps/extension/src/transport/types.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

crates/bsk-cli/skill/SKILL.md

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

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

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

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

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

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

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

crates/bsk-cli/tests/cli_parse.rs

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

crates/bsk-cli/tests/tools_ipc.rs

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

crates/bsk-cli/tests/tools_m7_ipc.rs

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

crates/bsk-protocol/schema/tool_click_params.json

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

crates/bsk-protocol/schema/tool_click_result.json

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

crates/bsk-protocol/schema/tool_screenshot_result.json

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

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

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

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

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

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

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

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

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

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

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

packages/vom/src/index.ts

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

packages/vom/src/render.ts

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

packages/vom/src/types.ts

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

skill/SKILL.md

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