feat(vom): two channels to deal with canvas

apps/extension/src/entrypoints/background.ts

@@ -1,7 +1,6 @@
 import { i18n } from "@browser-skill/i18n";
 import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
 import { ConnectionController } from "@/lib/connection-controller";
-import { DiagnosticLogger } from "@/lib/diagnostics";
 import { startHeartbeat } from "@/lib/heartbeat";
 import {
   getConnectionEnabled,
@@ -47,20 +46,9 @@ import type { Transport } from "@/transport/transport";
 import { WSTransport } from "@/transport/ws-transport";
 
 export default defineBackground(() => {
-  const diagnostics = new DiagnosticLogger();
-  diagnostics.record("extension.worker.started", {
-    diagnostic_build: "lumi-session-loss-v2",
-    extension_version: __BSK_EXT_VERSION__,
-    extension_runtime_id: chrome.runtime.id,
-    daemon_ws_url: __BSK_DAEMON_WS_URL__,
-  });
-  const controller = new ConnectionController(diagnostics.sink);
-  const transport = new WSTransport({
-    url: __BSK_DAEMON_WS_URL__,
-    diagnostics: diagnostics.sink,
-  });
-  diagnostics.bindTransport((frame) => transport.send(frame));
-  const sessions = new SessionManager({ diagnostics: diagnostics.sink });
+  const controller = new ConnectionController();
+  const transport = new WSTransport({ url: __BSK_DAEMON_WS_URL__ });
+  const sessions = new SessionManager();
   const cdp = new ChromiumCdp();
   const sessionsLive = attachSessionsLiveFlag({ manager: sessions });
   let overlayGeneration = 0;
@@ -121,9 +109,6 @@ export default defineBackground(() => {
   }
 
   function onOverlaySessionStateChanged(): void {
-    diagnostics.record("background.sessions.changed", {
-      live_session_ids: sessions.list().map((ctx) => ctx.sessionId),
-    });
     void sessionsLive.syncFromManager();
     const liveSessionIds = new Set(sessions.list().map((ctx) => ctx.sessionId));
     for (const sessionId of controlModes.keys()) {
@@ -161,7 +146,6 @@ export default defineBackground(() => {
     onSessionsChanged: () => {
       void sessionsLive.syncFromManager();
     },
-    diagnostics: diagnostics.sink,
   });
   const recordDeps = {
     tabsApi: chrome.tabs,
@@ -209,7 +193,6 @@ export default defineBackground(() => {
       title: i18n.t("helpRequest.notificationTitle", { ns: "extension" }),
       body: "",
     }),
-    diagnostics: diagnostics.sink,
   });
   dispatcher.start();
   if (typeof chrome.notifications?.onClicked?.addListener === "function") {
@@ -242,7 +225,6 @@ export default defineBackground(() => {
     transport,
     cdp,
     onSessionsChanged: onOverlaySessionStateChanged,
-    diagnostics: diagnostics.sink,
   });
 
   // MV3 service worker keepalive + reconnect supervisor (review M4/M5
@@ -254,7 +236,6 @@ export default defineBackground(() => {
   startKeepalive({
     transport,
     shouldConnect: () => controller.isConnectionEnabled,
-    diagnostics: diagnostics.sink,
   });
 
   // Application-level heartbeat (Chrome 116+): while the post-handshake
@@ -268,19 +249,6 @@ export default defineBackground(() => {
       controller.subscribe((snap) =>
         cb(snap.state === "connected" || snap.state === "version_skew"),
       ),
-    diagnostics: diagnostics.sink,
-  });
-
-  controller.subscribe((snapshot) => {
-    const ready = snapshot.state === "connected" || snapshot.state === "version_skew";
-    diagnostics.setTransportReady(ready);
-    diagnostics.record("background.controller.snapshot", {
-      state: snapshot.state,
-      connection_enabled: snapshot.connectionEnabled,
-      instance_id: snapshot.instanceId,
-      last_error: snapshot.lastError,
-      live_session_ids: sessions.list().map((ctx) => ctx.sessionId),
-    });
   });
 
   // Wake-driven reconnect (best effort). An MV3 service worker is killed
@@ -289,12 +257,7 @@ export default defineBackground(() => {
   // the worker and let us reconnect immediately instead of waiting for
   // the next 30s alarm tick. They only help when the daemon is actually
   // running; a cold daemon is (re)spawned by the next `bsk` command.
-  const reconnectIfNeeded = (source: string) => {
-    diagnostics.record("background.wake_reconnect.requested", {
-      source,
-      controller_enabled: controller.isConnectionEnabled,
-      transport_state: transport.state,
-    });
+  const reconnectIfNeeded = () => {
     if (!controller.isConnectionEnabled) return;
     if (transport.state === "connected") return;
     void transport.connect().catch((err) => {
@@ -302,14 +265,13 @@ export default defineBackground(() => {
     });
   };
   if (typeof chrome.runtime?.onStartup?.addListener === "function") {
-    chrome.runtime.onStartup.addListener(() => reconnectIfNeeded("runtime.onStartup"));
+    chrome.runtime.onStartup.addListener(reconnectIfNeeded);
   }
   if (typeof chrome.idle?.onStateChanged?.addListener === "function") {
     chrome.idle.onStateChanged.addListener((state) => {
-      diagnostics.record("chrome.idle.state_changed", { state });
       // "active" fires when the user returns from idle/locked — the most
       // reliable "machine just woke" signal we get.
-      if (state === "active") reconnectIfNeeded("idle.active");
+      if (state === "active") reconnectIfNeeded();
     });
     // Treat >60s of no input as idle so the active transition is timely.
     chrome.idle.setDetectionInterval?.(60);
@@ -317,21 +279,14 @@ export default defineBackground(() => {
 
   void (async () => {
     const connectionEnabled = await getConnectionEnabled();
-    diagnostics.record("background.controller.attach_started", { connectionEnabled });
     await controller.attach(transport, detectBrowserMeta(), connectionEnabled, {
       beforeDisconnect: async () => {
-        diagnostics.record("background.before_disconnect_cleanup", {
-          live_session_ids: sessions.list().map((ctx) => ctx.sessionId),
-        });
         const report = await cleanupAfterDisconnect();
         if (report.failures.length > 0) {
           console.warn("[browser-skill] session cleanup before disconnect was incomplete", report);
         }
       },
       onDisconnected: async () => {
-        diagnostics.record("background.after_disconnect_cleanup", {
-          live_session_ids: sessions.list().map((ctx) => ctx.sessionId),
-        });
         const report = await cleanupAfterDisconnect();
         if (report.failures.length > 0) {
           console.warn("[browser-skill] session cleanup after disconnect was incomplete", report);
@@ -339,7 +294,6 @@ export default defineBackground(() => {
       },
     });
   })().catch((err) => {
-    diagnostics.record("background.controller.attach_failed", { error: err });
     console.error("[browser-skill] controller failed to attach", err);
   });
 
@@ -420,15 +374,6 @@ export default defineBackground(() => {
     dbg.__bhDispatcher = dispatcher;
   }
 
-  if (typeof chrome.runtime?.onSuspend?.addListener === "function") {
-    chrome.runtime.onSuspend.addListener(() => {
-      diagnostics.record("extension.worker.suspending", {
-        live_session_ids: sessions.list().map((ctx) => ctx.sessionId),
-        transport_state: transport.state,
-      });
-    });
-  }
-
   console.info("[browser-skill] background worker initialised");
 });
 

apps/extension/src/lib/__tests__/diagnostics.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { DiagnosticLogger } from "../diagnostics";
-
-class MemoryStorage {
-  value: Record<string, unknown> = {};
-
-  async get(key: string): Promise<Record<string, unknown>> {
-    return { [key]: this.value[key] };
-  }
-
-  async set(items: Record<string, unknown>): Promise<void> {
-    this.value = { ...this.value, ...items };
-  }
-}
-
-describe("DiagnosticLogger", () => {
-  it("persists evidence before transport readiness and flushes it after reconnect", async () => {
-    const storage = new MemoryStorage();
-    const send = vi.fn();
-    const logger = new DiagnosticLogger(storage);
-    logger.bindTransport(send);
-
-    logger.record("transport.socket.closed", { code: 1006 });
-    await logger.flush();
-    expect(send).not.toHaveBeenCalled();
-
-    logger.setTransportReady(true);
-    await logger.flush();
-
-    expect(send).toHaveBeenCalledOnce();
-    expect(send.mock.calls[0]?.[0]).toMatchObject({
-      event: "browser.diagnostic",
-      payload: {
-        schema_version: 1,
-        entries: [
-          {
-            event: "transport.socket.closed",
-            fields: { code: 1006 },
-          },
-        ],
-      },
-    });
-    expect(storage.value.bsk_diagnostic_events_v1).toEqual([]);
-  });
-
-  it("keeps persisted evidence when the transport rejects the flush", async () => {
-    const storage = new MemoryStorage();
-    const logger = new DiagnosticLogger(storage);
-    logger.bindTransport(() => {
-      throw new Error("socket closed");
-    });
-    logger.record("session.stop.requested", { session_id: "abcd" });
-
-    logger.setTransportReady(true);
-    await logger.flush();
-
-    expect(storage.value.bsk_diagnostic_events_v1).toMatchObject([
-      { event: "session.stop.requested", fields: { session_id: "abcd" } },
-    ]);
-  });
-
-  it("does not resend an acknowledged event when send records a new event", async () => {
-    const storage = new MemoryStorage();
-    const batches: Array<{ payload?: { entries?: Array<{ event: string }> } }> = [];
-    const logger = new DiagnosticLogger(storage);
-    logger.record("dispatcher.rpc.received", { rpc_id: "one" });
-    await logger.flush();
-    logger.bindTransport((frame) => {
-      batches.push(frame as { payload?: { entries?: Array<{ event: string }> } });
-      if (batches.length === 1) {
-        logger.record("dispatcher.rpc.response_sent", { rpc_id: "one" });
-      }
-    });
-
-    logger.setTransportReady(true);
-    await logger.flush();
-    await logger.flush();
-
-    expect(batches.map((batch) => batch.payload?.entries?.map((entry) => entry.event))).toEqual([
-      ["dispatcher.rpc.received"],
-      ["dispatcher.rpc.response_sent"],
-    ]);
-    expect(storage.value.bsk_diagnostic_events_v1).toEqual([]);
-  });
-});

apps/extension/src/lib/connection-controller.ts

@@ -6,7 +6,6 @@ import {
 } from "../transport/handshake";
 import type { Transport } from "../transport/transport";
 import type { ConnectionState, HandshakeResult } from "../transport/types";
-import type { DiagnosticSink } from "./diagnostics";
 import { getLabel, getOrCreateInstanceId } from "./instance-id";
 import { compareProtocol, parseProtocolMajor } from "./semver";
 
@@ -52,11 +51,6 @@ export class ConnectionController {
   private handshakeAbort: AbortController | null = null;
   private handshakeRetryTimer: ReturnType<typeof setTimeout> | null = null;
   private suppressDisconnectRecovery = false;
-  private readonly diagnostics?: DiagnosticSink;
-
-  constructor(diagnostics?: DiagnosticSink) {
-    this.diagnostics = diagnostics;
-  }
 
   get isConnectionEnabled(): boolean {
     return this.connectionEnabled;
@@ -95,20 +89,8 @@ export class ConnectionController {
     this.lifecycleHooks = lifecycleHooks;
     this.instanceId = await getOrCreateInstanceId();
     this.label = await getLabel();
-    this.diagnostics?.("controller.attach", {
-      instance_id: this.instanceId,
-      connection_enabled: connectionEnabled,
-      transport_state: transport.state,
-    });
 
     transport.onConnectionStateChange((s) => {
-      this.diagnostics?.("controller.transport_state", {
-        transport_state: s,
-        controller_state: this.currentState,
-        connection_generation: this.connectionGeneration,
-        suppress_disconnect_recovery: this.suppressDisconnectRecovery,
-        recovery_inflight: this.disconnectRecovery !== null,
-      });
       if (s === "disconnected") {
         // An in-flight handshake belongs to the dead connection — cancel it so
         // a late resolution can never clobber the next attempt.
@@ -121,9 +103,6 @@ export class ConnectionController {
             // handshake bounce); the caller owns the reconnect policy there.
             this.suppressDisconnectRecovery = false;
           } else {
-            this.diagnostics?.("controller.disconnect_recovery.requested", {
-              connection_generation: this.connectionGeneration,
-            });
             void this.recoverFromDisconnect();
           }
         }
@@ -182,12 +161,6 @@ export class ConnectionController {
     const generation = ++this.connectionGeneration;
     const abort = new AbortController();
     this.handshakeAbort = abort;
-    this.diagnostics?.("controller.handshake.started", {
-      connection_generation: generation,
-      browser_name: browser.name,
-      browser_version: browser.version,
-      instance_id: this.instanceId,
-    });
     void this.runHandshake(browser, generation, abort.signal);
   }
 
@@ -224,21 +197,11 @@ export class ConnectionController {
       }
       this.clearHandshakeRetry();
       this.lastError = null;
-      this.diagnostics?.("controller.handshake.completed", {
-        connection_generation: generation,
-        verdict: verdict.kind,
-        daemon_version: outcome.result.version,
-        daemon_protocol: outcome.result.protocol_version,
-      });
       this.setState(verdict.kind);
     } catch (err) {
       if (generation !== this.connectionGeneration || signal.aborted || isAbortError(err)) return;
       this.handshake = null;
       this.lastError = err instanceof Error ? err.message : String(err);
-      this.diagnostics?.("controller.handshake.failed", {
-        connection_generation: generation,
-        error: err,
-      });
       // Bounce the half-open socket deliberately; the retry timer below owns
       // the reconnect, so skip unexpected-loss recovery for this disconnect.
       this.suppressDisconnectRecovery = true;
@@ -265,57 +228,23 @@ export class ConnectionController {
   }
 
   private recoverFromDisconnect(): Promise<void> {
-    if (this.disconnectRecovery) {
-      this.diagnostics?.("controller.disconnect_recovery.coalesced", {
-        connection_generation: this.connectionGeneration,
-      });
-      return this.disconnectRecovery;
-    }
+    if (this.disconnectRecovery) return this.disconnectRecovery;
     const recovery = (async () => {
-      const recoveryGeneration = this.connectionGeneration;
-      this.diagnostics?.("controller.disconnect_recovery.started", {
-        recovery_generation: recoveryGeneration,
-      });
       // WSTransport schedules its reconnect timer immediately after notifying
       // state listeners. Yield once, then disconnect explicitly so that timer
       // is cancelled before local session teardown begins.
       await Promise.resolve();
-      if (!this.connectionEnabled || !this.transport) {
-        this.diagnostics?.("controller.disconnect_recovery.skipped", {
-          recovery_generation: recoveryGeneration,
-          reason: "disabled_or_missing_transport",
-        });
-        return;
-      }
+      if (!this.connectionEnabled || !this.transport) return;
       // Another path already reconnected while we yielded — nothing to do.
-      if (this.currentState !== "disconnected") {
-        this.diagnostics?.("controller.disconnect_recovery.skipped", {
-          recovery_generation: recoveryGeneration,
-          reason: "state_already_changed",
-          current_state: this.currentState,
-        });
-        return;
-      }
+      if (this.currentState !== "disconnected") return;
       await this.transport.disconnect().catch(() => {});
       try {
-        this.diagnostics?.("controller.disconnect_cleanup.started", {
-          recovery_generation: recoveryGeneration,
-          current_generation: this.connectionGeneration,
-        });
         await this.lifecycleHooks.onDisconnected?.();
-        this.diagnostics?.("controller.disconnect_cleanup.completed", {
-          recovery_generation: recoveryGeneration,
-          current_generation: this.connectionGeneration,
-        });
       } catch (err) {
         console.warn("[browser-skill] session cleanup after disconnect failed", err);
       }
       if (!this.connectionEnabled) return;
       try {
-        this.diagnostics?.("controller.disconnect_reconnect.started", {
-          recovery_generation: recoveryGeneration,
-          current_generation: this.connectionGeneration,
-        });
         await this.transport.connect();
       } catch (err) {
         this.lastError = err instanceof Error ? err.message : String(err);
@@ -323,39 +252,22 @@ export class ConnectionController {
       }
     })();
     this.disconnectRecovery = recovery.finally(() => {
-      this.diagnostics?.("controller.disconnect_recovery.completed", {
-        connection_generation: this.connectionGeneration,
-        current_state: this.currentState,
-      });
       this.disconnectRecovery = null;
     });
     return this.disconnectRecovery;
   }
 
   private cancelHandshake(): void {
-    const previousGeneration = this.connectionGeneration;
     this.connectionGeneration += 1;
-    this.diagnostics?.("controller.handshake.cancelled", {
-      previous_generation: previousGeneration,
-      next_generation: this.connectionGeneration,
-      had_abort_controller: this.handshakeAbort !== null,
-    });
     this.handshakeAbort?.abort();
     this.handshakeAbort = null;
   }
 
   private scheduleHandshakeRetry(browser: { name: string; version: string }): void {
     if (this.handshakeRetryTimer || !this.connectionEnabled) return;
-    this.diagnostics?.("controller.handshake_retry.scheduled", {
-      delay_ms: HANDSHAKE_RETRY_DELAY_MS,
-      connection_generation: this.connectionGeneration,
-    });
     this.handshakeRetryTimer = setTimeout(() => {
       this.handshakeRetryTimer = null;
       if (!this.connectionEnabled || !this.transport) return;
-      this.diagnostics?.("controller.handshake_retry.timer_fired", {
-        connection_generation: this.connectionGeneration,
-      });
       void this.transport.connect().catch((err) => {
         this.lastError = err instanceof Error ? err.message : String(err);
         this.setState("disconnected");

apps/extension/src/lib/diagnostics.ts

@@ -1,178 +0,0 @@
-import type { ProtocolFrame } from "@/transport/types";
-
-const STORAGE_KEY = "bsk_diagnostic_events_v1";
-const MAX_ENTRIES = 500;
-
-export type DiagnosticFields = Record<string, unknown>;
-export type DiagnosticSink = (event: string, fields?: DiagnosticFields) => void;
-
-export interface DiagnosticEntry {
-  id: string;
-  sequence: number;
-  timestamp: string;
-  monotonic_ms: number;
-  worker_boot_id: string;
-  event: string;
-  fields: DiagnosticFields;
-}
-
-interface DiagnosticStorage {
-  get(key: string): Promise<Record<string, unknown>>;
-  set(items: Record<string, unknown>): Promise<void>;
-}
-
-function defaultStorage(): DiagnosticStorage | null {
-  if (typeof chrome === "undefined" || !chrome.storage?.local) return null;
-  return {
-    get: (key) => chrome.storage.local.get(key),
-    set: (items) => chrome.storage.local.set(items),
-  };
-}
-
-function makeBootId(): string {
-  try {
-    return crypto.randomUUID();
-  } catch {
-    return `worker-${Date.now()}-${Math.random().toString(16).slice(2)}`;
-  }
-}
-
-function normalise(value: unknown): unknown {
-  if (value instanceof Error) {
-    return { name: value.name, message: value.message, stack: value.stack };
-  }
-  if (typeof value === "bigint") return value.toString();
-  if (Array.isArray(value)) return value.map(normalise);
-  if (value && typeof value === "object") {
-    return Object.fromEntries(
-      Object.entries(value as Record<string, unknown>).map(([key, child]) => [
-        key,
-        normalise(child),
-      ]),
-    );
-  }
-  return value;
-}
-
-/**
- * Persistent diagnostics for the MV3 background worker.
- *
- * Events are first written to chrome.storage.local so a worker termination or
- * dead WebSocket does not erase the evidence. Once the post-handshake link is
- * ready, pending entries are forwarded to the daemon as one
- * `browser.diagnostic` event and removed from the local queue.
- */
-export class DiagnosticLogger {
-  readonly workerBootId: string;
-  readonly sink: DiagnosticSink;
-
-  private sequence = 0;
-  private storageQueue: Promise<void> = Promise.resolve();
-  private flushPromise: Promise<void> | null = null;
-  private flushRequested = false;
-  private send: ((frame: ProtocolFrame) => void) | null = null;
-  private transportReady = false;
-  private readonly storage: DiagnosticStorage | null;
-
-  constructor(storage: DiagnosticStorage | null = defaultStorage()) {
-    this.workerBootId = makeBootId();
-    this.storage = storage;
-    this.sink = (event, fields = {}) => this.record(event, fields);
-  }
-
-  bindTransport(send: (frame: ProtocolFrame) => void): void {
-    this.send = send;
-  }
-
-  setTransportReady(ready: boolean): void {
-    this.transportReady = ready;
-    if (ready) void this.flush();
-  }
-
-  record(event: string, fields: DiagnosticFields = {}): void {
-    const sequence = ++this.sequence;
-    const entry: DiagnosticEntry = {
-      id: `${this.workerBootId}:${sequence}`,
-      sequence,
-      timestamp: new Date().toISOString(),
-      monotonic_ms: Math.round(performance.now()),
-      worker_boot_id: this.workerBootId,
-      event,
-      fields: normalise(fields) as DiagnosticFields,
-    };
-    console.info("[bsk diagnostic]", entry);
-    this.storageQueue = this.storageQueue
-      .then(async () => {
-        if (!this.storage) return;
-        const stored = await this.storage.get(STORAGE_KEY);
-        const previous = Array.isArray(stored[STORAGE_KEY])
-          ? (stored[STORAGE_KEY] as DiagnosticEntry[])
-          : [];
-        await this.storage.set({
-          [STORAGE_KEY]: [...previous, entry].slice(-MAX_ENTRIES),
-        });
-      })
-      .catch((error) => {
-        console.warn("[bsk diagnostic] failed to persist event", error);
-      });
-    if (this.transportReady) void this.flush();
-  }
-
-  flush(): Promise<void> {
-    if (this.flushPromise) {
-      this.flushRequested = true;
-      return this.flushPromise;
-    }
-    const running = (async () => {
-      await this.storageQueue;
-      if (!this.transportReady || !this.send || !this.storage) return;
-      const stored = await this.storage.get(STORAGE_KEY);
-      const entries = Array.isArray(stored[STORAGE_KEY])
-        ? (stored[STORAGE_KEY] as DiagnosticEntry[])
-        : [];
-      if (entries.length === 0) return;
-      try {
-        this.send({
-          event: "browser.diagnostic",
-          payload: {
-            schema_version: 1,
-            worker_boot_id: this.workerBootId,
-            entries,
-          },
-        });
-      } catch (error) {
-        console.warn("[bsk diagnostic] daemon flush failed", error);
-        return;
-      }
-      const sentIds = new Set(entries.map((entry) => entry.id));
-      // Serialize acknowledgement behind every record write that may have
-      // started while send() was in progress. Without this, a concurrent
-      // record can read the pre-ack queue and write an already-sent entry
-      // back into storage, causing the next batch to duplicate it.
-      this.storageQueue = this.storageQueue
-        .then(async () => {
-          const current = await this.storage?.get(STORAGE_KEY);
-          const currentEntries = Array.isArray(current?.[STORAGE_KEY])
-            ? (current[STORAGE_KEY] as DiagnosticEntry[])
-            : [];
-          await this.storage?.set({
-            [STORAGE_KEY]: currentEntries.filter((entry) => !sentIds.has(entry.id)),
-          });
-        })
-        .catch((error) => {
-          console.warn("[bsk diagnostic] failed to acknowledge event batch", error);
-        });
-      await this.storageQueue;
-    })().catch((error) => {
-      console.warn("[bsk diagnostic] flush failed", error);
-    });
-    this.flushPromise = running.finally(() => {
-      this.flushPromise = null;
-      if (this.flushRequested && this.transportReady) {
-        this.flushRequested = false;
-        void this.flush();
-      }
-    });
-    return this.flushPromise;
-  }
-}

apps/extension/src/lib/heartbeat.ts

@@ -21,7 +21,6 @@
  * after the handshake has landed.
  */
 
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import type { ProtocolFrame } from "@/transport/types";
 
 export const HEARTBEAT_EVENT = "system.heartbeat";
@@ -47,7 +46,6 @@ export interface HeartbeatOptions {
   intervalMs?: number;
   /** Inject fake timers (tests). */
   timers?: HeartbeatTimers;
-  diagnostics?: DiagnosticSink;
 }
 
 export interface HeartbeatHandle {
@@ -76,9 +74,7 @@ export function startHeartbeat(options: HeartbeatOptions): HeartbeatHandle {
   const beat = () => {
     try {
       options.send({ event: HEARTBEAT_EVENT, payload: {} });
-      options.diagnostics?.("heartbeat.sent");
     } catch (err) {
-      options.diagnostics?.("heartbeat.send_failed", { error: err });
       // The socket raced a close between the state change and this
       // tick. The transport's own reconnect path recovers; swallow so
       // the interval keeps running (it is cleared on the disconnect
@@ -91,14 +87,12 @@ export function startHeartbeat(options: HeartbeatOptions): HeartbeatHandle {
     if (timer !== null) {
       timers.clearInterval(timer);
       timer = null;
-      options.diagnostics?.("heartbeat.timer.stopped");
     }
   };
 
   const start = () => {
     if (timer !== null) return;
     timer = timers.setInterval(beat, intervalMs);
-    options.diagnostics?.("heartbeat.timer.started", { interval_ms: intervalMs });
   };
 
   const unsubscribe = options.onActiveChange((active) => {

apps/extension/src/lib/keepalive.ts

@@ -20,7 +20,6 @@
  * SW idle threshold.
  */
 
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import type { Transport } from "@/transport/transport";
 
 export const KEEPALIVE_ALARM_NAME = "bh-keepalive";
@@ -60,7 +59,6 @@ export interface KeepaliveOptions {
   alarmName?: string;
   /** Override the alarm period (tests). */
   periodMin?: number;
-  diagnostics?: DiagnosticSink;
 }
 
 export interface KeepaliveHandle {
@@ -81,24 +79,11 @@ export function startKeepalive(options: KeepaliveOptions): KeepaliveHandle {
   const period = options.periodMin ?? KEEPALIVE_PERIOD_MIN;
 
   const tick = async () => {
-    if (options.shouldConnect && !options.shouldConnect()) {
-      options.diagnostics?.("keepalive.tick.skipped", { reason: "connection_disabled" });
-      return;
-    }
-    if (options.transport.state === "connected") {
-      options.diagnostics?.("keepalive.tick.healthy", { transport_state: "connected" });
-      return;
-    }
-    options.diagnostics?.("keepalive.reconnect.started", {
-      transport_state: options.transport.state,
-    });
+    if (options.shouldConnect && !options.shouldConnect()) return;
+    if (options.transport.state === "connected") return;
     try {
       await options.transport.connect();
-      options.diagnostics?.("keepalive.reconnect.completed", {
-        transport_state: options.transport.state,
-      });
     } catch (err) {
-      options.diagnostics?.("keepalive.reconnect.failed", { error: err });
       console.debug("[bsk keepalive] connect attempt failed", err);
     }
   };

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/disconnect-cleanup.ts

@@ -1,4 +1,3 @@
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import { handleSessionStop, type SessionStopDeps } from "@/tools/session";
 import type { SessionManager } from "./manager";
 
@@ -16,7 +15,6 @@ export interface DisconnectCleanupOptions {
   manager: SessionManager;
   sessionStopDeps?: SessionStopDeps;
   onSessionsChanged?: () => void;
-  diagnostics?: DiagnosticSink;
 }
 
 /**
@@ -31,15 +29,7 @@ export function createDisconnectCleanup(options: DisconnectCleanupOptions) {
   let inFlight: Promise<DisconnectCleanupReport> | null = null;
 
   return (): Promise<DisconnectCleanupReport> => {
-    if (inFlight) {
-      options.diagnostics?.("disconnect_cleanup.coalesced", {
-        live_session_ids: options.manager.list().map((ctx) => ctx.sessionId),
-      });
-      return inFlight;
-    }
-    options.diagnostics?.("disconnect_cleanup.scheduled", {
-      live_session_ids: options.manager.list().map((ctx) => ctx.sessionId),
-    });
+    if (inFlight) return inFlight;
     inFlight = cleanupSessions(options).finally(() => {
       inFlight = null;
     });
@@ -52,17 +42,8 @@ async function cleanupSessions(
 ): Promise<DisconnectCleanupReport> {
   const stoppedSessionIds: string[] = [];
   const failures: DisconnectCleanupFailure[] = [];
-  const capturedSessions = options.manager.list();
-  options.diagnostics?.("disconnect_cleanup.started", {
-    captured_session_ids: capturedSessions.map((ctx) => ctx.sessionId),
-  });
 
-  for (const ctx of capturedSessions) {
-    options.diagnostics?.("disconnect_cleanup.session_stop.started", {
-      session_id: ctx.sessionId,
-      agent_window_id: ctx.agentWindowId,
-      still_registered: options.manager.has(ctx.sessionId),
-    });
+  for (const ctx of options.manager.list()) {
     try {
       const result = await handleSessionStop(
         options.manager,
@@ -81,26 +62,14 @@ async function cleanupSessions(
         continue;
       }
       stoppedSessionIds.push(ctx.sessionId);
-      options.diagnostics?.("disconnect_cleanup.session_stop.completed", {
-        session_id: ctx.sessionId,
-      });
     } catch (err) {
       failures.push({
         sessionId: ctx.sessionId,
         message: err instanceof Error ? err.message : String(err),
       });
-      options.diagnostics?.("disconnect_cleanup.session_stop.failed", {
-        session_id: ctx.sessionId,
-        error: err,
-      });
     }
   }
 
   options.onSessionsChanged?.();
-  options.diagnostics?.("disconnect_cleanup.completed", {
-    stopped_session_ids: stoppedSessionIds,
-    failures,
-    remaining_session_ids: options.manager.list().map((ctx) => ctx.sessionId),
-  });
   return { stoppedSessionIds, failures };
 }

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

@@ -1,4 +1,3 @@
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import type { Transport } from "@/transport/transport";
 import type { EventFrame } from "@/transport/types";
 import type { SessionManager } from "./manager";
@@ -25,7 +24,6 @@ export interface SessionEventHandlerOptions {
    * `chrome.storage.session` "sessions live" flag (review M4/M5 I3).
    */
   onSessionsChanged?: () => void;
-  diagnostics?: DiagnosticSink;
 }
 
 function chromeWindowEvents(): WindowRemovedListener {
@@ -52,11 +50,6 @@ export function attachSessionEventHandler(options: SessionEventHandlerOptions):
 
   const onRemoved = (windowId: number): void => {
     const ctx = manager.findByWindowId(windowId);
-    options.diagnostics?.("chrome.window.removed", {
-      window_id: windowId,
-      matched_session_id: ctx?.sessionId ?? null,
-      live_session_ids: manager.list().map((entry) => entry.sessionId),
-    });
     if (!ctx) return;
     const returnFailures = Array.from(ctx.borrowedTabs.keys()).map((tabId) => ({
       tab_id: tabId,
@@ -88,16 +81,7 @@ export function attachSessionEventHandler(options: SessionEventHandlerOptions):
         };
         try {
           transport.send(event);
-          options.diagnostics?.("session.window_closed.sent", {
-            session_id: ctx.sessionId,
-            window_id: windowId,
-          });
         } catch (err) {
-          options.diagnostics?.("session.window_closed.send_failed", {
-            session_id: ctx.sessionId,
-            window_id: windowId,
-            error: err,
-          });
           console.warn("[bh] could not push session.window_closed event", err);
         }
       })

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

@@ -1,4 +1,3 @@
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import { AGENT_WINDOW_HOME, type AgentWindowApi, chromeAgentWindowApi } from "./agent-window";
 import { RefStore } from "./ref-store";
 
@@ -24,7 +23,6 @@ export interface BorrowReservation {
 export interface SessionManagerOptions {
   agentWindow?: AgentWindowApi;
   now?: () => number;
-  diagnostics?: DiagnosticSink;
 }
 
 /** Options for starting a session's Agent Window. */
@@ -85,12 +83,10 @@ export class SessionManager {
   private readonly borrowReservations = new Map<number, string>();
   private readonly agentWindow: AgentWindowApi;
   private readonly now: () => number;
-  private readonly diagnostics?: DiagnosticSink;
 
   constructor(options: SessionManagerOptions = {}) {
     this.agentWindow = options.agentWindow ?? chromeAgentWindowApi;
     this.now = options.now ?? Date.now;
-    this.diagnostics = options.diagnostics;
   }
 
   has(sessionId: string): boolean {
@@ -173,13 +169,6 @@ export class SessionManager {
    * daemon in the `tool.session_start` reply.
    */
   async start(sessionId: string, opts: SessionStartOptions = {}): Promise<SessionContext> {
-    this.diagnostics?.("session_manager.start.requested", {
-      session_id: sessionId,
-      existing_session_ids: this.list().map((ctx) => ctx.sessionId),
-      focused: opts.focused ?? null,
-      size: opts.size ?? null,
-      signal_aborted: opts.signal?.aborted ?? false,
-    });
     if (this.sessions.has(sessionId)) {
       throw new Error(`[bh] session ${sessionId} already exists`);
     }
@@ -189,10 +178,6 @@ export class SessionManager {
     try {
       const { signal: _signal, ...createOptions } = opts;
       windowId = await this.agentWindow.create(AGENT_WINDOW_HOME, createOptions);
-      this.diagnostics?.("session_manager.window.created", {
-        session_id: sessionId,
-        agent_window_id: windowId,
-      });
       throwIfSessionStartAborted(opts.signal);
       await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
       throwIfSessionStartAborted(opts.signal);
@@ -206,18 +191,8 @@ export class SessionManager {
       };
       this.sessions.set(sessionId, ctx);
       this.windowIndex.set(windowId, sessionId);
-      this.diagnostics?.("session_manager.start.committed", {
-        session_id: sessionId,
-        agent_window_id: windowId,
-        live_session_ids: this.list().map((entry) => entry.sessionId),
-      });
       return ctx;
     } catch (startupError) {
-      this.diagnostics?.("session_manager.start.failed", {
-        session_id: sessionId,
-        agent_window_id: windowId,
-        error: startupError,
-      });
       if (windowId !== null) {
         try {
           await this.agentWindow.remove(windowId);
@@ -241,28 +216,12 @@ export class SessionManager {
     options: { dropOnly?: boolean } = {},
   ): Promise<SessionContext | null> {
     const ctx = this.sessions.get(sessionId);
-    this.diagnostics?.("session_manager.stop.requested", {
-      session_id: sessionId,
-      drop_only: options.dropOnly ?? false,
-      existed: ctx !== undefined,
-      live_session_ids: this.list().map((entry) => entry.sessionId),
-    });
     if (!ctx) return null;
     if (!options.dropOnly) {
       await this.agentWindow.remove(ctx.agentWindowId);
-      this.diagnostics?.("session_manager.window.removed", {
-        session_id: sessionId,
-        agent_window_id: ctx.agentWindowId,
-      });
     }
     this.sessions.delete(sessionId);
     this.windowIndex.delete(ctx.agentWindowId);
-    this.diagnostics?.("session_manager.stop.committed", {
-      session_id: sessionId,
-      agent_window_id: ctx.agentWindowId,
-      drop_only: options.dropOnly ?? false,
-      live_session_ids: this.list().map((entry) => entry.sessionId),
-    });
     return ctx;
   }
 

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/tools/__tests__/interaction.test.ts

@@ -123,6 +123,29 @@ describe("handleClick", () => {
     expect(fake.cdp.send).not.toHaveBeenCalled();
   });
 
+  it("rejects screenshot-only visual surface refs before issuing CDP calls", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, {
+      tabId: 4,
+      kind: "surface",
+      capabilities: ["screenshot"],
+    });
+    const fake = makeFakeCdp({});
+
+    const res = await handleClick(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi },
+    );
+
+    expect(res).toMatchObject({
+      code: "permission_denied",
+      data: { reason: "ref_capability_denied", required_capability: "interact" },
+    });
+    expect(fake.cdp.send).not.toHaveBeenCalled();
+  });
+
   it("clicks by ref, computes the quad centre, dispatches three mouse events", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
@@ -456,30 +479,6 @@ describe("handleClick", () => {
     expect(res).toMatchObject({ code: "not_found", data: { reason: "selector_not_found" } });
   });
 
-  it("returns invalid_selector when Chrome rejects non-CSS selector syntax", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "DOM.getDocument": () => ({ root: { nodeId: 1 } }),
-      "DOM.querySelector": () => {
-        throw new Error('{"code":-32000,"message":"DOM Error while querying"}');
-      },
-    });
-    const res = await handleClick(
-      sm,
-      { session_id: "aa11", selector: "text=下午 12~18点" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-    expect(res).toMatchObject({
-      code: "invalid_params",
-      message: "selector is not valid CSS: text=下午 12~18点",
-      data: {
-        reason: "invalid_selector",
-        selector: "text=下午 12~18点",
-      },
-    });
-  });
-
   it("respects the AbortSignal", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");

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

@@ -300,6 +300,76 @@ 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)));
+  });
+
+  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: 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)}`);
+    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 });
+  });
+
   it("returns not_found for unknown ref", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     await sm.start("aa11");
@@ -2693,6 +2763,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__/snapshot-ref.test.ts

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

apps/extension/src/tools/dispatcher.ts

@@ -1,4 +1,3 @@
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import { OVERLAY_AUTOMATION_BYPASS } from "@/lib/overlay-bridge";
 import type { SessionManager } from "@/session-manager/manager";
 import type { Transport } from "@/transport/transport";
@@ -119,7 +118,6 @@ export interface DispatcherDeps {
   approveBorrow?: BorrowConfirmationApprover;
   /** i18n notification copy for `tool.request_help` (resolved per-call). */
   helpNotificationCopy?: () => { title: string; body: string };
-  diagnostics?: DiagnosticSink;
 }
 
 /**
@@ -147,7 +145,6 @@ export class ToolDispatcher {
   private readonly onBrowserControlResumed?: (sessionId: string) => void;
   private readonly approveBorrow?: BorrowConfirmationApprover;
   private readonly helpNotificationCopy?: () => { title: string; body: string };
-  private readonly diagnostics?: DiagnosticSink;
   private subscription: { dispose(): void } | null = null;
   private readonly hoverBypassTabs = new Map<number, string>();
   private readonly hoverLatches = new Map<number, HoverLatch>();
@@ -168,7 +165,6 @@ export class ToolDispatcher {
     this.onBrowserControlResumed = deps.onBrowserControlResumed;
     this.approveBorrow = deps.approveBorrow;
     this.helpNotificationCopy = deps.helpNotificationCopy;
-    this.diagnostics = deps.diagnostics;
   }
 
   start(): void {
@@ -196,16 +192,6 @@ export class ToolDispatcher {
   private async dispatch(msg: ProtocolFrame): Promise<void> {
     if (!isRequestFrame(msg)) return;
     const req = msg as RequestFrame;
-    const requestSessionId = (req.params as { session_id?: unknown } | undefined)?.session_id;
-    const startedAt = performance.now();
-    this.diagnostics?.("dispatcher.rpc.received", {
-      rpc_id: req.id,
-      method: req.method,
-      session_id: typeof requestSessionId === "string" ? requestSessionId : null,
-      transport_state: this.transport.state,
-      live_session_ids: this.sessions.list().map((ctx) => ctx.sessionId),
-      inflight_rpc_ids: Array.from(this.inflightAbortControllers.keys()),
-    });
 
     // Cancel frames take a fast path: trip the matching controller
     // (if any), reply with `{cancelled}` so the daemon can answer
@@ -214,12 +200,6 @@ export class ToolDispatcher {
       const params = (req.params as { rpc_id?: string } | undefined) ?? {};
       const target = typeof params.rpc_id === "string" ? params.rpc_id : "";
       const ac = target ? this.inflightAbortControllers.get(target) : undefined;
-      this.diagnostics?.("dispatcher.cancel.received", {
-        rpc_id: req.id,
-        target_rpc_id: target,
-        target_found: ac !== undefined,
-        inflight_rpc_ids: Array.from(this.inflightAbortControllers.keys()),
-      });
       if (ac) {
         try {
           ac.abort();
@@ -233,17 +213,7 @@ export class ToolDispatcher {
       };
       try {
         this.transport.send(reply);
-        this.diagnostics?.("dispatcher.cancel.ack_sent", {
-          rpc_id: req.id,
-          target_rpc_id: target,
-          cancelled: ac !== undefined,
-        });
       } catch (sendErr) {
-        this.diagnostics?.("dispatcher.cancel.ack_failed", {
-          rpc_id: req.id,
-          target_rpc_id: target,
-          error: sendErr,
-        });
         console.warn("[bsk dispatcher] failed to ack cancel", sendErr);
       }
       return;
@@ -268,13 +238,6 @@ export class ToolDispatcher {
         }
       }
     } catch (err) {
-      this.diagnostics?.("dispatcher.rpc.invoke_failed", {
-        rpc_id: req.id,
-        method: req.method,
-        session_id: typeof requestSessionId === "string" ? requestSessionId : null,
-        abort_signal: ac.signal.aborted,
-        error: err,
-      });
       if (isAbortLikeError(err)) {
         body = {
           id: req.id,
@@ -295,27 +258,8 @@ export class ToolDispatcher {
     let sent = true;
     try {
       this.transport.send(body);
-      this.diagnostics?.("dispatcher.rpc.response_sent", {
-        rpc_id: req.id,
-        method: req.method,
-        session_id: typeof requestSessionId === "string" ? requestSessionId : null,
-        response_kind: "error" in body ? "error" : "ok",
-        error_code: "error" in body ? body.error.code : null,
-        elapsed_ms: Math.round(performance.now() - startedAt),
-        transport_state: this.transport.state,
-        live_session_ids: this.sessions.list().map((ctx) => ctx.sessionId),
-      });
     } catch (sendErr) {
       sent = false;
-      this.diagnostics?.("dispatcher.rpc.response_send_failed", {
-        rpc_id: req.id,
-        method: req.method,
-        session_id: typeof requestSessionId === "string" ? requestSessionId : null,
-        started_session_id: startedSession,
-        elapsed_ms: Math.round(performance.now() - startedAt),
-        transport_state: this.transport.state,
-        error: sendErr,
-      });
       // Transport is dead by the time we want to reply. Drop the link
       // proactively so the alarm-driven keepalive reconnects sooner
       // and the daemon's pending RPC times out cleanly instead of
@@ -334,23 +278,12 @@ export class ToolDispatcher {
       try {
         const ctx = await this.sessions.stop(startedSession);
         if (ctx) {
-          this.diagnostics?.("dispatcher.session_start.rolled_back", {
-            rpc_id: req.id,
-            session_id: startedSession,
-            agent_window_id: ctx.agentWindowId,
-            reason: "response_send_failed",
-          });
           console.warn(
             "[bsk dispatcher] rolled back orphan session after send failure",
             startedSession,
           );
         }
       } catch (rollbackErr) {
-        this.diagnostics?.("dispatcher.session_start.rollback_failed", {
-          rpc_id: req.id,
-          session_id: startedSession,
-          error: rollbackErr,
-        });
         console.warn("[bsk dispatcher] session rollback after send failure failed", rollbackErr);
       }
     }

apps/extension/src/tools/interaction.ts

@@ -106,14 +106,6 @@ function isAbortLikeError(err: unknown): boolean {
   return err instanceof DOMException && err.name === "AbortError";
 }
 
-function isInvalidCssSelectorError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err);
-  return (
-    message.includes("DOM Error while querying") ||
-    /invalid selector|not a valid selector|querySelector.*failed/i.test(message)
-  );
-}
-
 async function wait(ms: number, signal?: AbortSignal): Promise<void> {
   if (signal?.aborted) throw new DOMException("aborted", "AbortError");
   await new Promise<void>((resolve, reject) => {
@@ -167,7 +159,7 @@ 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,
@@ -216,14 +208,6 @@ async function resolveBackendNode(
     }
     return { backendNodeId, cdpTarget: { tabId: target.tabId }, usedSelector: params.selector };
   } catch (err) {
-    if (isInvalidCssSelectorError(err)) {
-      return rpcError(
-        "invalid_params",
-        "invalid_selector",
-        `selector is not valid CSS: ${params.selector}`,
-        { selector: params.selector },
-      );
-    }
     return {
       code: "cdp_failed",
       message: err instanceof Error ? err.message : String(err),

apps/extension/src/tools/observation.ts

@@ -8,6 +8,7 @@ import {
   applyVomInteractionRecovery,
   type CondSurface,
   isVomReferenceNode,
+  type Rect,
   renderVom,
   type VomNode,
   type VomOptions,
@@ -59,6 +60,11 @@ import {
   type CaptureVomObservationResult,
   projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
+import {
+  clusterRenderedSurfaces,
+  discoverRenderedSurfaces,
+  projectRenderedSurfaces,
+} from "./vom/rendered-surfaces";
 import {
   buildSemanticGraph,
   buildSemanticVomScene,
@@ -90,6 +96,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.
@@ -182,6 +191,8 @@ async function captureElementScreenshot(
   target: CdpTarget,
   backendNodeId: number,
   frameId?: string,
+  visualSurface = false,
+  observedVisibleRect?: Rect,
   signal?: AbortSignal,
 ): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
   if (signal?.aborted) return cancelled("screenshot");
@@ -189,11 +200,36 @@ async function captureElementScreenshot(
     cdp,
     tabId,
     { target, backendNodeId, ...(frameId ? { frameId } : {}) },
-    { scrollIntoView: true },
+    { scrollIntoView: !visualSurface },
   );
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
-  const rect = geometry.topBounds;
+  const liveRect = geometry.topBounds;
+  const rect =
+    visualSurface && observedVisibleRect
+      ? (() => {
+          const x = Math.max(liveRect.x, observedVisibleRect.x);
+          const y = Math.max(liveRect.y, observedVisibleRect.y);
+          const right = Math.min(
+            liveRect.x + liveRect.width,
+            observedVisibleRect.x + observedVisibleRect.w,
+          );
+          const bottom = Math.min(
+            liveRect.y + liveRect.height,
+            observedVisibleRect.y + observedVisibleRect.h,
+          );
+          return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : null;
+        })()
+      : liveRect;
+  if (!rect) return { code: "permission_denied", message: "surface is no longer visible" };
+  const 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", {
@@ -203,7 +239,7 @@ async function captureElementScreenshot(
         y: rect.y,
         width: rect.width,
         height: rect.height,
-        scale: 1,
+        scale,
       },
     });
     if (signal?.aborted) return cancelled("screenshot");
@@ -310,7 +346,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);
@@ -330,6 +366,8 @@ export async function handleScreenshot(
           nodeTarget,
           node.backendNodeId,
           node.frameId,
+          node.kind === "surface",
+          node.visibleRect,
           signal,
         ),
       deps.sendToTab,
@@ -1023,6 +1061,7 @@ async function captureForVom(
 
 export interface CaptureVomObservationOptions extends VomOptions {
   conditionalSurfaceProbe?: boolean;
+  renderedSurfaceDiscovery?: boolean;
   hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
   signal?: AbortSignal;
 }
@@ -1064,7 +1103,20 @@ export async function captureVomObservation(
     ),
   );
   const decoratedScene = attachCapturedSceneAnnotations(scene, normalizedDocuments, captured);
-  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,
@@ -1115,6 +1167,7 @@ async function handleVomObservation(
       maxTokens: params.max_tokens,
       activeRegionPolicy: true,
       conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
+      renderedSurfaceDiscovery: toolName === "observe",
       hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
       signal,
     });
@@ -1132,6 +1185,9 @@ async function handleVomObservation(
             tabId: target.tabId,
             ...(ref.frameId ? { frameId: ref.frameId } : {}),
             ...(refTarget?.sessionId ? { cdpSessionId: refTarget.sessionId } : {}),
+            ...(ref.visibleRect ? { visibleRect: ref.visibleRect } : {}),
+            ...(ref.kind ? { kind: ref.kind } : {}),
+            ...(ref.capabilities ? { capabilities: ref.capabilities } : {}),
           },
         ] as const;
       }),

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

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

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

@@ -722,6 +722,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) => {

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, 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
@@ -796,6 +808,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 ?? []);
@@ -821,6 +835,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];
@@ -840,7 +855,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];
@@ -863,12 +882,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.
@@ -903,6 +929,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,8 +23,8 @@ export type ErrorCode =
 export type RpcErrorReason =
   | "agent_window_scope"
   | "element_not_visible"
+  | "ref_capability_denied"
   | "ref_not_found"
-  | "invalid_selector"
   | "selector_not_found"
   | "target_not_fillable"
   | "target_not_select"

apps/extension/src/transport/ws-transport.ts

@@ -1,4 +1,3 @@
-import type { DiagnosticSink } from "@/lib/diagnostics";
 import type { ConnectionStateHandler, Disposable, FrameHandler, Transport } from "./transport";
 import type { ConnectionState, ProtocolFrame } from "./types";
 
@@ -19,7 +18,6 @@ export interface WSTransportOptions {
    * Inject a fake WebSocket constructor in tests; defaults to `globalThis.WebSocket`.
    */
   webSocketFactory?: WebSocketFactory;
-  diagnostics?: DiagnosticSink;
 }
 
 interface CloseLikeEvent {
@@ -46,7 +44,6 @@ export class WSTransport implements Transport {
   private readonly factory: WebSocketFactory;
   private readonly initialDelayMs: number;
   private readonly maxDelayMs: number;
-  private readonly diagnostics?: DiagnosticSink;
 
   private socket: WebSocket | null = null;
   private currentState: ConnectionState = "disconnected";
@@ -66,7 +63,6 @@ export class WSTransport implements Transport {
     this.factory = options.webSocketFactory ?? ((url: string) => new WebSocket(url));
     this.initialDelayMs = options.reconnect?.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
     this.maxDelayMs = options.reconnect?.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
-    this.diagnostics = options.diagnostics;
   }
 
   get state(): ConnectionState {
@@ -74,13 +70,6 @@ export class WSTransport implements Transport {
   }
 
   connect(): Promise<void> {
-    this.diagnostics?.("transport.connect.requested", {
-      state: this.currentState,
-      socket_generation: this.socketGeneration,
-      has_socket: this.socket !== null,
-      has_connecting_promise: this.connectingPromise !== null,
-      has_reconnect_timer: this.reconnectTimer !== null,
-    });
     if (this.currentState === "connected") return Promise.resolve();
 
     this.explicitlyClosed = false;
@@ -105,11 +94,6 @@ export class WSTransport implements Transport {
   }
 
   async disconnect(): Promise<void> {
-    this.diagnostics?.("transport.disconnect.requested", {
-      state: this.currentState,
-      socket_generation: this.socketGeneration,
-      has_socket: this.socket !== null,
-    });
     this.explicitlyClosed = true;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -140,12 +124,6 @@ export class WSTransport implements Transport {
 
   send(msg: ProtocolFrame): void {
     if (!this.socket || this.socket.readyState !== 1 /* OPEN */) {
-      this.diagnostics?.("transport.send.rejected", {
-        state: this.currentState,
-        socket_generation: this.socketGeneration,
-        socket_ready_state: this.socket?.readyState ?? null,
-        frame_kind: "method" in msg ? msg.method : "event" in msg ? msg.event : "response",
-      });
       throw new Error("[WSTransport] cannot send while not connected");
     }
     this.socket.send(JSON.stringify(msg));
@@ -174,16 +152,10 @@ export class WSTransport implements Transport {
     const generation = ++this.socketGeneration;
     const socket = this.factory(this.url);
     this.socket = socket;
-    this.diagnostics?.("transport.socket.created", {
-      socket_generation: generation,
-      reconnect_attempt: this.reconnectAttempt,
-      url: this.url,
-    });
 
     socket.addEventListener("open", () => {
       if (!this.isCurrentSocket(socket, generation)) return;
       this.reconnectAttempt = 0;
-      this.diagnostics?.("transport.socket.open", { socket_generation: generation });
       this.setState("connected");
       const resolve = this.resolveConnect;
       this.resolveConnect = null;
@@ -202,7 +174,6 @@ export class WSTransport implements Transport {
     });
 
     socket.addEventListener("error", () => {
-      this.diagnostics?.("transport.socket.error", { socket_generation: generation });
       // The 'close' handler always fires after 'error' in browsers, so we
       // just record the error and let close drive reconnect logic.
     });
@@ -226,16 +197,7 @@ export class WSTransport implements Transport {
   }
 
   private handleClose(socket: WebSocket, generation: number, _ev: CloseLikeEvent): void {
-    const isCurrent = this.isCurrentSocket(socket, generation);
-    this.diagnostics?.("transport.socket.close", {
-      socket_generation: generation,
-      current_socket_generation: this.socketGeneration,
-      is_current: isCurrent,
-      explicitly_closed: this.explicitlyClosed,
-      close_code: _ev.code ?? null,
-      close_reason: _ev.reason ?? "",
-    });
-    if (!isCurrent) return;
+    if (!this.isCurrentSocket(socket, generation)) return;
     this.socket = null;
     if (this.explicitlyClosed) {
       this.setState("disconnected");
@@ -249,18 +211,9 @@ export class WSTransport implements Transport {
     if (this.reconnectTimer) return;
     const delay = Math.min(this.initialDelayMs * 2 ** this.reconnectAttempt, this.maxDelayMs);
     this.reconnectAttempt += 1;
-    this.diagnostics?.("transport.reconnect.scheduled", {
-      delay_ms: delay,
-      reconnect_attempt: this.reconnectAttempt,
-      socket_generation: this.socketGeneration,
-    });
     this.reconnectTimer = setTimeout(() => {
       this.reconnectTimer = null;
       if (this.explicitlyClosed) return;
-      this.diagnostics?.("transport.reconnect.timer_fired", {
-        reconnect_attempt: this.reconnectAttempt,
-        socket_generation: this.socketGeneration,
-      });
       void this.connect().catch((err) => {
         console.debug("[WSTransport] reconnect attempt failed", err);
       });
@@ -273,13 +226,7 @@ export class WSTransport implements Transport {
 
   private setState(next: ConnectionState): void {
     if (this.currentState === next) return;
-    const previous = this.currentState;
     this.currentState = next;
-    this.diagnostics?.("transport.state.changed", {
-      previous,
-      next,
-      socket_generation: this.socketGeneration,
-    });
     for (const h of this.stateHandlers) {
       try {
         h(next);

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

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

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

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

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

@@ -0,0 +1,28 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      html, body { margin: 0; font: 14px system-ui, sans-serif; }
+      body { padding: 12px; background: #fdfefe; }
+      canvas { display: block; width: 220px; height: 90px; background: #d5f5e3; border: 2px solid #1e8449; }
+      iframe { width: 280px; height: 150px; margin-top: 10px; border: 2px solid #85929e; }
+    </style>
+  </head>
+  <body>
+    <canvas id="frame-canvas" width="220" height="90"></canvas>
+    <script>
+      const params = new URLSearchParams(location.search);
+      const canvas = document.querySelector("#frame-canvas");
+      if (params.get("canvas") === "0") canvas.remove();
+      else canvas.setAttribute("aria-label", params.get("label") || "fixture-frame-default");
+      if (params.get("nested") === "1") {
+        const iframe = document.createElement("iframe");
+        iframe.title = "nested fixture frame";
+        iframe.src = "frame.html?label=fixture-nested-frame";
+        document.body.append(iframe);
+      }
+    </script>
+  </body>
+</html>

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

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

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

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

apps/extension/test-fixtures/rendered-surfaces/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>
+

apps/extension/wxt.config.ts

@@ -22,8 +22,7 @@ export default defineConfig({
   outDir: "dist",
   modules: ["@wxt-dev/module-react"],
   manifest: {
-    name: "BrowserSkill (Lumi Diagnostics)",
-    version_name: `${EXTENSION_VERSION}-lumi-session-loss-v2`,
+    name: "BrowserSkill",
     description:
       "Let AI agents use your logged-in browser in a separate Agent Window—without interrupting your work. Powered by the bsk CLI.",
     // Flat debugger sessions are required to address out-of-process iframes.
@@ -46,7 +45,7 @@ export default defineConfig({
       128: "icon/logo.png",
     },
     action: {
-      default_title: "BrowserSkill (Lumi Diagnostics)",
+      default_title: "BrowserSkill",
       default_icon: {
         16: "icon/logo.png",
         32: "icon/logo.png",

crates/bsk-cli/skill/SKILL.md

@@ -80,6 +80,8 @@ Prefer `@eN` refs from the latest snapshot over raw CSS selectors. Use `--ref` /
 
 When VOM renders `[hover first: …]` on an element, the listed items are not currently clickable refs. Run `bsk hover <that-ref> --session <id>`, then immediately run `bsk snapshot` or `bsk observe` again and click the newly visible menu item ref. Do not click the trigger itself unless the user explicitly wants the trigger action.
 
+When `bsk observe` renders `@eN surface ... [visual-only; requires=image-understanding; ...]`, the ref identifies rendered canvas content that is not represented by the text observation, not an interactable DOM control. Keep using any reliable DOM/AX text and controls that appear alongside it. If you can actually inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop. If you lack multimodal or image-reading capability, do not take a screenshot and pretend to know its contents, and never guess coordinates; tell the user that they need to switch to a model with image-understanding capability. Do not pass a visual surface ref to click, fill, hover, or select; those commands intentionally reject screenshot-only refs.
+
 ## Observation priority
 
 Start with `bsk observe` to understand page structure, text, controls, element refs, and conditional hover/focus surfaces. Use `bsk snapshot` only when you need the stricter static accessibility tree or VOM is insufficient. Only escalate to raw HTML or screenshots when the latest observation cannot answer the question:

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

@@ -497,21 +497,4 @@ mod tests {
                 .contains("CSS selector")
         );
     }
-
-    #[test]
-    fn invalid_selector_explains_css_contract_in_json() {
-        let cli = CliError::from_rpc(RpcError {
-            code: ErrorCode::InvalidParams,
-            message: "selector is not valid CSS: text=submit".into(),
-            data: Some(serde_json::json!({ "reason": "invalid_selector" })),
-        });
-        let exit = cli.exit_code();
-        let hint = hint_for(&cli, render_info_for(&cli).as_ref());
-        let json = json_error_string(&cli, exit, hint);
-        let parsed: serde_json::Value = serde_json::from_str(&json).unwrap();
-        let hint = parsed.get("hint").and_then(|v| v.as_str()).unwrap();
-        assert!(hint.contains("CSS selector"));
-        assert!(hint.contains("text="));
-        assert!(hint.contains("@eN"));
-    }
 }

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

@@ -40,8 +40,8 @@ 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 INVALID_SELECTOR: &str = "invalid_selector";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
     pub const TARGET_NOT_SELECT: &str = "target_not_select";
@@ -222,13 +222,6 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             hint: Some("verify the CSS selector or wait for the element to appear before retrying"),
             exit_code: base.exit_code,
         },
-        (ErrorCode::InvalidParams, reason::INVALID_SELECTOR) => RenderInfo {
-            summary: "selector is not valid CSS",
-            hint: Some(
-                "use a standard CSS selector or a fresh @eN ref; Playwright text= selectors and XPath are not supported",
-            ),
-            exit_code: base.exit_code,
-        },
         (ErrorCode::InvalidParams, reason::TARGET_NOT_FILLABLE) => RenderInfo {
             summary: "target element is not fillable",
             hint: Some(
@@ -236,6 +229,13 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
             ),
             exit_code: base.exit_code,
         },
+        (ErrorCode::PermissionDenied, reason::REF_CAPABILITY_DENIED) => RenderInfo {
+            summary: "snapshot ref does not support this operation",
+            hint: Some(
+                "visual surface refs are screenshot-only; inspect `bsk screenshot --ref <ref> --session <id>` with image-understanding capability",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::InvalidParams, reason::TARGET_NOT_SELECT) => RenderInfo {
             summary: "target element is not a <select>",
             hint: Some(
@@ -385,6 +385,18 @@ mod tests {
         assert!(!info.summary.contains("sandbox"));
     }
 
+    #[test]
+    fn ref_capability_denied_explains_visual_surface_refs() {
+        let data = serde_json::json!({ "reason": reason::REF_CAPABILITY_DENIED });
+        let info = info_for_error(ErrorCode::PermissionDenied, Some(&data));
+        assert_eq!(info.summary, "snapshot ref does not support this operation");
+        assert!(
+            info.hint.unwrap().contains("screenshot-only"),
+            "expected visual-surface-specific hint"
+        );
+        assert_eq!(info.exit_code, 1);
+    }
+
     #[test]
     fn session_busy_overrides_timeout_copy() {
         let data = serde_json::json!({ "reason": reason::SESSION_BUSY });

crates/bsk-cli/src/daemon/browsers.rs

@@ -223,14 +223,6 @@ impl BrowserRegistry {
                 "browser reconnect: replacing previous registration"
             );
         }
-        tracing::info!(
-            diagnostic = true,
-            event = "browser.registry.insert",
-            id = %client.id,
-            generation = client.generation,
-            previous_generation = guard.get(&client.id).map(|previous| previous.generation),
-            "diagnostic browser registry mutation"
-        );
         guard.insert(client.id.clone(), client);
     }
 
@@ -247,31 +239,16 @@ impl BrowserRegistry {
     /// took over the same `id` while the old socket was tearing down
     /// (review M4/M5 round 2 Important #1). Returns the removed entry
     /// when a removal actually happened.
-    #[track_caller]
     pub fn remove_if_generation_matches(
         &self,
         id: &BrowserId,
         generation: u64,
     ) -> Option<std::sync::Arc<BrowserClient>> {
-        let caller = std::panic::Location::caller();
         let mut guard = self.inner.lock().expect("browser registry poisoned");
-        let current_generation = guard.get(id).map(|current| current.generation);
-        let removed = match guard.get(id) {
+        match guard.get(id) {
             Some(current) if current.generation == generation => guard.remove(id),
             _ => None,
-        };
-        tracing::info!(
-            diagnostic = true,
-            event = "browser.registry.remove_if_generation_matches",
-            id = %id,
-            requested_generation = generation,
-            ?current_generation,
-            removed = removed.is_some(),
-            caller_file = caller.file(),
-            caller_line = caller.line(),
-            "diagnostic browser registry mutation"
-        );
-        removed
+        }
     }
 
     pub fn get(&self, id: &BrowserId) -> Option<std::sync::Arc<BrowserClient>> {

crates/bsk-cli/src/daemon/ipc.rs

@@ -37,7 +37,7 @@ use serde::{Deserialize, Serialize};
 use serde_json::Value;
 use tokio::sync::Notify;
 use tokio::task::JoinHandle;
-use tracing::{debug, info, warn};
+use tracing::{debug, warn};
 
 use super::abort::AbortRegistry;
 use super::queue::{DEFAULT_TOOL_TIMEOUT, DispatchError};
@@ -197,22 +197,7 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
         let status = status.clone();
         let state = Arc::clone(&state);
         Box::pin(async move {
-            let method_name = format!("{method:?}");
-            let diagnostic_rpc_id = rpc_id.clone();
-            let session_id = params
-                .get("session_id")
-                .and_then(Value::as_str)
-                .map(str::to_owned);
-            let started = Instant::now();
-            info!(
-                diagnostic = true,
-                event = "ipc.rpc.started",
-                rpc_id = %diagnostic_rpc_id,
-                method = %method_name,
-                session = session_id.as_deref().unwrap_or(""),
-                "diagnostic IPC RPC"
-            );
-            let body = match method {
+            match method {
                 Method::SystemPing => {
                     let result = PingResult { pong: true };
                     ResponseBody::Ok(serde_json::to_value(result).unwrap_or(Value::Null))
@@ -276,23 +261,7 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                     message: format!("method not implemented yet: {other:?}"),
                     data: None,
                 }),
-            };
-            let (outcome, error_code) = match &body {
-                ResponseBody::Ok(_) => ("ok", String::new()),
-                ResponseBody::Err(error) => ("error", format!("{:?}", error.code)),
-            };
-            info!(
-                diagnostic = true,
-                event = "ipc.rpc.completed",
-                rpc_id = %diagnostic_rpc_id,
-                method = %method_name,
-                session = session_id.as_deref().unwrap_or(""),
-                outcome,
-                error_code = %error_code,
-                elapsed_ms = started.elapsed().as_millis() as u64,
-                "diagnostic IPC RPC"
-            );
-            body
+            }
         })
     })
 }
@@ -496,14 +465,8 @@ fn handle_cancel(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
     };
     let local = state.abort_registry.cancel(&params.rpc_id);
     let mut cancelled = local;
-    let mut surface = if local { "abort_registry" } else { "none" };
     if !local && let Some(snap) = state.tool_inflight.cancel(&params.rpc_id) {
         cancelled = true;
-        surface = if snap.ws_rpc_id.is_some() {
-            "tool_inflight_forwarded"
-        } else {
-            "tool_inflight_queued"
-        };
         // Forward the WS-side cancel only when the worker has
         // already promoted the entry to "forwarded"; queued entries
         // short-circuit on their own pre-flight without ever
@@ -521,14 +484,6 @@ fn handle_cancel(state: &Arc<DaemonState>, params: Value) -> ResponseBody {
             );
         }
     }
-    info!(
-        diagnostic = true,
-        event = "ipc.cancel.resolved",
-        target_rpc_id = %params.rpc_id,
-        cancelled,
-        surface,
-        "diagnostic IPC cancellation"
-    );
     ResponseBody::Ok(serde_json::to_value(CancelResult { cancelled }).unwrap_or(Value::Null))
 }
 

crates/bsk-cli/src/daemon/queue.rs

@@ -41,7 +41,7 @@ use bsk_protocol::{ErrorCode, Frame, Method, RequestFrame, ResponseBody, RpcErro
 use rand::Rng;
 use serde_json::Value;
 use tokio::sync::{mpsc, oneshot};
-use tracing::{debug, info, warn};
+use tracing::{debug, warn};
 
 use super::abort::AbortToken;
 use super::browsers::BrowserRegistry;
@@ -515,16 +515,6 @@ async fn forward_one(
     sessions: &Arc<SessionRegistry>,
     job: &ToolJob,
 ) -> Result<Value, RpcError> {
-    let started = std::time::Instant::now();
-    info!(
-        diagnostic = true,
-        event = "tool.dispatch.started",
-        session = %sid,
-        method = ?job.method,
-        has_inflight = job.inflight.is_some(),
-        has_lifecycle_cancel = job.lifecycle_cancel.is_some(),
-        "diagnostic tool dispatch"
-    );
     // Pre-flight: a cancel that landed while this job was still in
     // the per-session channel must short-circuit before any session
     // / browser resolution work, and before any WS frame leaves the
@@ -545,13 +535,6 @@ async fn forward_one(
         ));
     }
     let Some(session) = sessions.get(sid) else {
-        warn!(
-            diagnostic = true,
-            event = "tool.dispatch.session_missing",
-            session = %sid,
-            method = ?job.method,
-            "diagnostic tool dispatch"
-        );
         return Err(RpcError {
             code: ErrorCode::NotFound,
             message: format!("session {sid} no longer exists"),
@@ -559,14 +542,6 @@ async fn forward_one(
         });
     };
     let Some(client) = browsers.get(&session.browser_id) else {
-        warn!(
-            diagnostic = true,
-            event = "tool.dispatch.browser_missing",
-            session = %sid,
-            method = ?job.method,
-            browser = %session.browser_id,
-            "diagnostic tool dispatch"
-        );
         return Err(RpcError {
             code: ErrorCode::NotFound,
             message: "owning browser is no longer connected".into(),
@@ -583,16 +558,6 @@ async fn forward_one(
         method: job.method.clone(),
         params: Some(job.params.clone()),
     });
-    info!(
-        diagnostic = true,
-        event = "tool.dispatch.forwarding",
-        session = %sid,
-        method = ?job.method,
-        browser = %session.browser_id,
-        browser_generation = client.generation,
-        ws_rpc_id = %rpc_id,
-        "diagnostic tool dispatch"
-    );
     // Promote the inflight entry to "forwarded" AND push the WS
     // request frame to the sink inside the same critical section
     // (review round 2 C1). The closure runs while the entry's inner
@@ -752,18 +717,6 @@ async fn forward_one(
             });
         }
     };
-    info!(
-        diagnostic = true,
-        event = "tool.dispatch.response",
-        session = %sid,
-        method = ?job.method,
-        browser = %session.browser_id,
-        browser_generation = client.generation,
-        ws_rpc_id = %rpc_id,
-        elapsed_ms = started.elapsed().as_millis() as u64,
-        response_is_error = matches!(&response.body, ResponseBody::Err(_)),
-        "diagnostic tool dispatch"
-    );
     match response.body {
         ResponseBody::Ok(v) => Ok(v),
         ResponseBody::Err(err) => Err(err),

crates/bsk-cli/src/daemon/sessions.rs

@@ -105,22 +105,12 @@ impl SessionRegistry {
 
     pub fn insert(&self, session: Session) {
         let session_id = session.id.clone();
-        let browser_id = session.browser_id.clone();
-        let agent_window_id = session.agent_window_id;
         let mut sessions = self.inner.lock().expect("session registry poisoned");
         sessions.insert(session_id.clone(), session);
         self.last_activity
             .lock()
             .expect("session activity registry poisoned")
-            .insert(session_id.clone(), Instant::now());
-        tracing::info!(
-            diagnostic = true,
-            event = "session.registry.insert",
-            session = %session_id,
-            browser = %browser_id,
-            ?agent_window_id,
-            "diagnostic session registry mutation"
-        );
+            .insert(session_id, Instant::now());
     }
 
     /// Reserve a fresh, collision-free [`SessionId`] under the registry
@@ -162,13 +152,6 @@ impl SessionRegistry {
                 .lock()
                 .expect("session activity registry poisoned")
                 .insert(candidate.clone(), Instant::now());
-            tracing::info!(
-                diagnostic = true,
-                event = "session.registry.reserve",
-                session = %candidate,
-                browser = %browser_id,
-                "diagnostic session registry mutation"
-            );
             return Some(candidate);
         }
         None
@@ -186,24 +169,13 @@ impl SessionRegistry {
         let mut guard = self.inner.lock().expect("session registry poisoned");
         let session = guard.get_mut(session_id)?;
         session.agent_window_id = agent_window_id;
-        tracing::info!(
-            diagnostic = true,
-            event = "session.registry.commit",
-            session = %session_id,
-            browser = %session.browser_id,
-            ?agent_window_id,
-            "diagnostic session registry mutation"
-        );
         Some(session.clone())
     }
 
     /// Drop a placeholder reservation, used on extension error/timeout
     /// paths so failed reservations do not accumulate.
-    #[track_caller]
     pub fn cancel_reservation(&self, session_id: &SessionId) {
-        let caller = std::panic::Location::caller();
-        let removed = self
-            .inner
+        self.inner
             .lock()
             .expect("session registry poisoned")
             .remove(session_id);
@@ -211,20 +183,9 @@ impl SessionRegistry {
             .lock()
             .expect("session activity registry poisoned")
             .remove(session_id);
-        tracing::info!(
-            diagnostic = true,
-            event = "session.registry.cancel_reservation",
-            session = %session_id,
-            existed = removed.is_some(),
-            caller_file = caller.file(),
-            caller_line = caller.line(),
-            "diagnostic session registry mutation"
-        );
     }
 
-    #[track_caller]
     pub fn remove(&self, id: &SessionId) -> Option<Session> {
-        let caller = std::panic::Location::caller();
         let removed = self
             .inner
             .lock()
@@ -234,17 +195,6 @@ impl SessionRegistry {
             .lock()
             .expect("session activity registry poisoned")
             .remove(id);
-        tracing::info!(
-            diagnostic = true,
-            event = "session.registry.remove",
-            session = %id,
-            existed = removed.is_some(),
-            browser = removed.as_ref().map(|session| session.browser_id.0.as_str()),
-            agent_window_id = removed.as_ref().and_then(|session| session.agent_window_id),
-            caller_file = caller.file(),
-            caller_line = caller.line(),
-            "diagnostic session registry mutation"
-        );
         removed
     }
 
@@ -293,9 +243,7 @@ impl SessionRegistry {
     }
 
     /// Drop all sessions owned by `browser_id` (e.g. on disconnect).
-    #[track_caller]
     pub fn purge_browser(&self, browser_id: &BrowserId) -> Vec<Session> {
-        let caller = std::panic::Location::caller();
         let mut guard = self.inner.lock().expect("session registry poisoned");
         let drained: Vec<Session> = guard
             .values()
@@ -312,20 +260,6 @@ impl SessionRegistry {
         for session in &drained {
             activity.remove(&session.id);
         }
-        let session_ids: Vec<&str> = drained
-            .iter()
-            .map(|session| session.id.0.as_str())
-            .collect();
-        tracing::info!(
-            diagnostic = true,
-            event = "session.registry.purge_browser",
-            browser = %browser_id,
-            sessions = ?session_ids,
-            count = drained.len(),
-            caller_file = caller.file(),
-            caller_line = caller.line(),
-            "diagnostic session registry mutation"
-        );
         drained
     }
 

crates/bsk-cli/src/daemon/start.rs

@@ -40,8 +40,6 @@ pub(crate) const DAEMONIZED_ENV: &str = "BSK_DAEMONIZED";
 /// daemon lock, IPC socket, and WS port — before taking over.
 pub(crate) const DAEMON_REPLACEMENT_WAIT_ENV: &str = "BSK_DAEMON_REPLACES_PID";
 
-const LUMI_DIAGNOSTIC_BUILD: &str = "lumi-session-loss-v2";
-
 /// Concrete daemon configuration resolved from CLI flags / defaults.
 #[derive(Debug, Clone)]
 pub struct DaemonConfig {
@@ -253,7 +251,6 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
             pid = info.pid,
             ws_port = info.ws_port,
             sock = %sock_path.display(),
-            diagnostic_build = LUMI_DIAGNOSTIC_BUILD,
             "daemon ready"
         );
 
@@ -591,9 +588,7 @@ pub(crate) fn spawn_update_check_task(
                     // The session gate is read after the fetch, as late
                     // as possible before the binary gets replaced.
                     let active_sessions = state.sessions.len();
-                    // Keep this local diagnostic build in place until a
-                    // reproduction has uploaded its extension-side evidence.
-                    let auto_update = false;
+                    let auto_update = update::auto_update_enabled() && exe_path.is_some();
                     update::auto_update_step(
                         candidate.as_ref(),
                         auto_update,
@@ -737,11 +732,7 @@ fn init_tracing() -> Option<tracing_appender::non_blocking::WorkerGuard> {
     use tracing_subscriber::prelude::*;
 
     let log_dir = paths::log_dir().ok();
-    let env_filter = EnvFilter::try_from_default_env()
-        .unwrap_or_else(|_| EnvFilter::new("info"))
-        // Lumi commonly runs with RUST_LOG=warn. This local build must retain
-        // BrowserSkill's INFO diagnostics even under that host-wide setting.
-        .add_directive("bsk=info".parse().expect("valid diagnostic log directive"));
+    let env_filter = EnvFilter::try_from_default_env().unwrap_or_else(|_| EnvFilter::new("info"));
 
     let (file_layer, guard) = if let Some(dir) = log_dir {
         let appender = tracing_appender::rolling::daily(&dir, "daemon.log");

crates/bsk-cli/src/daemon/ws.rs

@@ -233,14 +233,6 @@ async fn drive_connection(
         .ok_or_else(|| anyhow!("handshake missing params"))?;
     let params: HandshakeParams = serde_json::from_value(params_raw)
         .map_err(|err| anyhow!("invalid HandshakeParams: {err}"))?;
-    info!(
-        diagnostic = true,
-        event = "browser.handshake.received",
-        browser = %params.instance_id,
-        extension_version = %params.version,
-        extension_protocol = %params.protocol_version,
-        "diagnostic browser handshake"
-    );
 
     // Version compatibility (design §10, M10.4): protocol_version only.
     let our_app_version: Version = env!("CARGO_PKG_VERSION")
@@ -358,7 +350,7 @@ async fn drive_connection(
     // Pump loop: outbound frames from sink → ws; inbound from ws → resolve.
     let pump_state = Arc::clone(&state);
     let pump_browser = Arc::clone(&client);
-    let result_outcome: anyhow::Result<String> = async {
+    let result_outcome: anyhow::Result<()> = async {
         loop {
             tokio::select! {
                 outbound = rx.recv() => {
@@ -367,7 +359,7 @@ async fn drive_connection(
                             let json = serde_json::to_string(&frame)?;
                             writer.send(Message::Text(json)).await?;
                         }
-                        None => break Ok("outbound_channel_closed".to_string()),
+                        None => break,
                     }
                 }
                 msg = reader.next() => {
@@ -389,37 +381,18 @@ async fn drive_connection(
                             pump_browser.touch();
                         }
                         Some(Ok(Message::Frame(_))) => {}
-                        Some(Ok(Message::Close(frame))) => {
-                            let reason = frame
-                                .map(|frame| format!("peer_close code={:?} reason={}", frame.code, frame.reason))
-                                .unwrap_or_else(|| "peer_close_without_frame".to_string());
-                            break Ok(reason);
-                        }
-                        None => break Ok("peer_eof".to_string()),
+                        Some(Ok(Message::Close(_))) | None => break,
                         Some(Err(err)) => {
                             warn!(%err, "ws read error");
-                            break Ok(format!("read_error: {err}"));
+                            break;
                         }
                     }
                 }
             }
         }
+        Ok(())
     }
     .await;
-    let pump_exit_reason = match &result_outcome {
-        Ok(reason) => reason.clone(),
-        Err(err) => format!("pump_error: {err:#}"),
-    };
-    info!(
-        diagnostic = true,
-        event = "browser.websocket.pump_exit",
-        id = %browser_id,
-        generation,
-        reason = %pump_exit_reason,
-        last_seen_idle_ms = client.idle_for().as_millis() as u64,
-        session_ids = ?state.sessions.ids_for_browser(&browser_id),
-        "diagnostic browser websocket exit"
-    );
 
     // Cleanup: drop browser + purge its sessions, but only if the
     // registry still holds *this* generation. If a reconnect already
@@ -443,7 +416,7 @@ async fn drive_connection(
             "browser disconnected; newer reconnect already owns this id, leaving sessions intact"
         );
     }
-    result_outcome.map(|_| ())
+    result_outcome
 }
 
 async fn handle_inbound_text(state: &Arc<DaemonState>, client: &Arc<BrowserClient>, text: &str) {
@@ -469,38 +442,6 @@ async fn handle_inbound_text(state: &Arc<DaemonState>, client: &Arc<BrowserClien
                 client.mark_heartbeat_seen();
                 debug!(id = %client.id, "heartbeat");
             }
-            bsk_protocol::EventKind::BrowserDiagnostic => {
-                let entries = ev.payload.get("entries").and_then(|value| value.as_array());
-                info!(
-                    diagnostic = true,
-                    event = "extension.diagnostic.batch",
-                    browser = %client.id,
-                    generation = client.generation,
-                    worker_boot_id = ev.payload.get("worker_boot_id").and_then(|value| value.as_str()).unwrap_or("unknown"),
-                    count = entries.map_or(0, Vec::len),
-                    "received extension diagnostic batch"
-                );
-                if let Some(entries) = entries {
-                    for entry in entries {
-                        info!(
-                            diagnostic = true,
-                            event = "extension.diagnostic.entry",
-                            browser = %client.id,
-                            generation = client.generation,
-                            entry = %entry,
-                            "extension diagnostic"
-                        );
-                    }
-                } else {
-                    warn!(
-                        diagnostic = true,
-                        event = "extension.diagnostic.invalid",
-                        browser = %client.id,
-                        payload = %ev.payload,
-                        "extension diagnostic payload missing entries"
-                    );
-                }
-            }
             bsk_protocol::EventKind::SessionWindowClosed => {
                 handle_session_window_closed(state, &client.id, &ev.payload);
             }

crates/bsk-protocol/src/frame.rs

@@ -58,10 +58,6 @@ pub enum EventKind {
     BrowserDisconnected,
     #[serde(rename = "browser.connected")]
     BrowserConnected,
-    /// Structured diagnostics emitted by locally instrumented extension
-    /// builds. Production peers may ignore this event safely.
-    #[serde(rename = "browser.diagnostic")]
-    BrowserDiagnostic,
 }
 
 #[derive(Debug, Clone, PartialEq)]
@@ -260,27 +256,6 @@ mod tests {
         assert_eq!(frame.event, EventKind::SystemHeartbeat);
     }
 
-    #[test]
-    fn browser_diagnostic_event_frame_round_trips_from_extension_shape() {
-        let wire = serde_json::json!({
-            "event": "browser.diagnostic",
-            "payload": {
-                "schema_version": 1,
-                "worker_boot_id": "worker-1",
-                "entries": [{ "event": "extension.worker.started" }]
-            }
-        });
-        let frame: EventFrame = serde_json::from_value(wire).unwrap();
-        assert_eq!(frame.event, EventKind::BrowserDiagnostic);
-        assert_eq!(
-            frame
-                .payload
-                .get("worker_boot_id")
-                .and_then(|value| value.as_str()),
-            Some("worker-1")
-        );
-    }
-
     #[test]
     fn session_user_interrupt_serialises_as_snake_case() {
         let v = serde_json::to_value(EventKind::SessionUserInterrupt).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,
@@ -752,12 +754,17 @@ function defineBrowserOperations(deps: ToolDeps, register: DefinitionRegistrar):
       name: "inspect.screenshot",
       description:
         "Capture a PNG screenshot of the session's active tab, or crop to a snapshot ref element. " +
+        "This is the supported operation for visual surface refs emitted by inspect.observe. Only use " +
+        "it to interpret a visual-only surface when you can inspect image output. If you lack multimodal " +
+        "or image-reading capability, tell the user to switch to a model with image understanding; do " +
+        "not guess content or coordinates. " +
         "Returns the image itself when the deployment supports image input, otherwise a file path.",
       parameters: {
         session: SESSION_PARAM,
         ref: {
           type: "string",
-          description: "Snapshot ref (@e3) from the last snapshot/observe; crops to that element.",
+          description:
+            "Ref (@e3) from the last snapshot/observe; crops to that DOM element or visual surface.",
         },
       },
       output: {

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

@@ -29,6 +29,66 @@ 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(
+      '@e1 surface "Data grid" [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" [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("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"]);
@@ -737,6 +738,53 @@ interface RenderState {
   duplicateRefNames: Set<string>;
   surfaceMap: Map<number, CondSurface>;
   scopeMap: Map<number, ActiveScopeBlock>;
+  visualSurfaces: Map<number | null, VomVisualSurface[]>;
+}
+
+function groupedByParent<T extends { parentId: number | null }>(
+  items: T[],
+): Map<number | null, T[]> {
+  const grouped = new Map<number | null, T[]>();
+  for (const item of items) {
+    const siblings = grouped.get(item.parentId) ?? [];
+    siblings.push(item);
+    grouped.set(item.parentId, siblings);
+  }
+  return grouped;
+}
+
+function emitVisualEntries(parentId: number | null, depth: number, state: RenderState): void {
+  if (state.stopped) return;
+  for (const surface of state.visualSurfaces.get(parentId) ?? []) {
+    if (depth > state.maxDepth) {
+      state.truncated = true;
+      continue;
+    }
+    const ref = `e${state.nextRef}`;
+    const label = cleaned(surface.label) ?? `${surface.renderingKind} visual surface`;
+    const layers = surface.memberCount > 1 ? `; layers=${surface.memberCount}` : "";
+    const line = `${"  ".repeat(depth)}@${ref} surface ${JSON.stringify(label)} [rendering=${surface.renderingKind}${layers}; visual-only; requires=image-understanding; use: bsk screenshot --ref @${ref}]`;
+    const nextTokens = state.tokens + estimateTokens(line);
+    if (nextTokens > state.maxTokens) {
+      state.truncated = true;
+      state.stopped = true;
+      return;
+    }
+    state.lines.push(line);
+    state.tokens = nextTokens;
+    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;
+  }
 }
 
 function emitActiveScopeBlock(scope: ActiveScopeBlock, depth: number, state: RenderState): void {
@@ -812,6 +860,8 @@ function renderTree(
         ...(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;
@@ -821,10 +871,12 @@ function renderTree(
     if (scope) emitActiveScopeBlock(scope, depth + 1, state);
 
     if ((ref && shouldSkipRedundantRefChildren(node)) || shouldSkipRedundantChildren(node, state)) {
+      emitVisualEntries(node.id, depth + 1, state);
       continue;
     }
     renderTree(children, node.id, depth + 1, state);
   }
+  emitVisualEntries(parentId, depth, state);
 }
 
 function renderNodes(
@@ -833,6 +885,7 @@ function renderNodes(
   initialLines: string[],
   surfaces: CondSurface[] = [],
   activeScopeBlocks: ActiveScopeBlock[] = [],
+  visualSurfaces: VomVisualSurface[] = [],
 ): RenderState {
   const children = buildChildren(nodes);
   const state: RenderState = {
@@ -851,6 +904,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: groupedByParent(visualSurfaces),
   };
 
   renderTree(children, null, 1, state);
@@ -1056,7 +1110,16 @@ 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);
+  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)),
+  );
   state.lines.push(renderPageOcclusionLine(hiddenCount));
 
   return {
@@ -1084,6 +1147,7 @@ export function renderVom(scene: VomScene, options: VomOptions = {}): VomResult
     ],
     scene.surfaces,
     scene.activeScopeBlocks,
+    scene.visualSurfaces,
   );
 
   return {

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

@@ -80,6 +80,8 @@ Prefer `@eN` refs from the latest snapshot over raw CSS selectors. Use `--ref` /
 
 When VOM renders `[hover first: …]` on an element, the listed items are not currently clickable refs. Run `bsk hover <that-ref> --session <id>`, then immediately run `bsk snapshot` or `bsk observe` again and click the newly visible menu item ref. Do not click the trigger itself unless the user explicitly wants the trigger action.
 
+When `bsk observe` renders `@eN surface ... [visual-only; requires=image-understanding; ...]`, the ref identifies rendered canvas content that is not represented by the text observation, not an interactable DOM control. Keep using any reliable DOM/AX text and controls that appear alongside it. If you can actually inspect image output, use `bsk screenshot --ref @eN --session <id>` to obtain the visible crop. If you lack multimodal or image-reading capability, do not take a screenshot and pretend to know its contents, and never guess coordinates; tell the user that they need to switch to a model with image-understanding capability. Do not pass a visual surface ref to click, fill, hover, or select; those commands intentionally reject screenshot-only refs.
+
 ## Observation priority
 
 Start with `bsk observe` to understand page structure, text, controls, element refs, and conditional hover/focus surfaces. Use `bsk snapshot` only when you need the stricter static accessibility tree or VOM is insufficient. Only escalate to raw HTML or screenshots when the latest observation cannot answer the question: