feat(vom): fixture test

Cargo.lock

@@ -134,7 +134,7 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "anyhow",
  "bsk-protocol",
@@ -168,7 +168,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.1.11"
+version = "0.1.10"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.1.11"
+version = "0.1.10"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"

apps/extension/package.json

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

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/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");

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");
@@ -1656,7 +1726,7 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", cursor: "pointer" }),
+      expect.objectContaining({ id: 20, role: "button", name: "close", cursor: "pointer" }),
     );
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "close"');
@@ -1732,7 +1802,7 @@ describe("buildVomScene", () => {
     };
 
     const scene = buildVomScene(axNodes, captured);
-    expect(scene.nodes.find((n) => n.id === 20)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 20)).toBeUndefined();
     expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("link");
   });
 
@@ -1801,9 +1871,9 @@ describe("buildVomScene", () => {
 
     const scene = buildVomScene(axNodes, captured);
     expect(scene.nodes.find((n) => n.id === 20)).toEqual(
-      expect.objectContaining({ id: 20, role: "generic", attrs: { "aria-label": "收藏" } }),
+      expect.objectContaining({ id: 20, role: "button", attrs: { "aria-label": "收藏" } }),
     );
-    expect(scene.nodes.find((n) => n.id === 30)?.role).toBe("generic");
+    expect(scene.nodes.find((n) => n.id === 30)).toBeUndefined();
     const rendered = renderVom(scene);
     expect(rendered.text).toContain('@e1 button "收藏"');
     expect(rendered.refs.map(({ ref, backendNodeId }) => ({ ref, backendNodeId }))).toEqual([
@@ -2131,7 +2201,7 @@ describe("buildVomScene", () => {
     });
 
     expect(scene.surfaces).toEqual([
-      { triggerId: 21, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
+      { triggerId: 20, triggerAction: "hover", subItems: ["My profile", "Sign out"] },
     ]);
     expect(renderVom(scene).text).toContain(
       '@e1 button "image" [hover first: My profile | Sign out]',
@@ -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");
@@ -3155,6 +3304,98 @@ describe("handleSnapshot", () => {
     });
   });
 
+  it("decorates live observations with active controlled content", async () => {
+    const strings = [
+      "html",
+      "body",
+      "button",
+      "div",
+      "#text",
+      "role",
+      "tab",
+      "aria-selected",
+      "true",
+      "aria-controls",
+      "reviews-panel",
+      "id",
+      "static",
+      "auto",
+      "visible",
+      "1",
+      "A detailed review",
+    ];
+    const index = (value: string) => strings.indexOf(value);
+    const style = [index("static"), index("auto"), index("auto"), index("visible"), index("1")];
+    const snapshot = {
+      strings,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 3],
+            nodeName: [index("html"), index("body"), index("button"), index("div"), index("#text")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [
+              [],
+              [],
+              [
+                index("role"),
+                index("tab"),
+                index("aria-selected"),
+                index("true"),
+                index("aria-controls"),
+                index("reviews-panel"),
+              ],
+              [index("id"), index("reviews-panel")],
+              [],
+            ],
+            nodeValue: [-1, -1, -1, -1, index("A detailed review")],
+          },
+          layout: {
+            nodeIndex: [0, 1, 2, 3, 4],
+            styles: [style, style, style, style, style],
+            bounds: [
+              [0, 0, 1000, 800],
+              [0, 0, 1000, 800],
+              [20, 20, 120, 40],
+              [20, 80, 500, 200],
+              [20, 80, 200, 20],
+            ],
+            paintOrders: [0, 0, 1, 1, 1],
+          },
+        },
+      ],
+    };
+    const ax: CdpAxNode[] = [
+      {
+        nodeId: "root",
+        backendDOMNodeId: 11,
+        role: { type: "role", value: "RootWebArea" },
+        childIds: ["reviews"],
+      },
+      {
+        nodeId: "reviews",
+        parentId: "root",
+        backendDOMNodeId: 12,
+        role: { type: "role", value: "tab" },
+        name: { type: "computedString", value: "Reviews" },
+        properties: [
+          { name: "selected", value: { value: true } },
+          { name: "controls", value: { value: "reviews-panel" } },
+        ],
+      },
+    ];
+
+    const result = await captureVomObservation(
+      makeOverlayDeps(ax, snapshot, VP_METRICS).cdp,
+      4,
+      "https://example.com",
+    );
+
+    expect(result.text).toContain('@e1 tab "Reviews"');
+    expect(result.text).toContain("[§ active: Reviews]");
+    expect(result.text).toContain("A detailed review");
+  });
+
   it("does not leak form secrets through the record-safe observation payload", async () => {
     const secrets = {
       email: "user@example.com",

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

@@ -159,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,

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

@@ -36,7 +36,7 @@ function fakeSnapshotReply() {
         },
         layout: {
           nodeIndex: [1, 2, 3],
-          // styles columns follow requested computedStyles order: [position, pointer-events]
+          // Legacy fixture: omitted style columns fall back to visible defaults.
           styles: [
             [i("static"), i("auto")],
             [i("fixed"), i("auto")],
@@ -682,6 +682,84 @@ describe("captureViewModel", () => {
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
 
+  it("captures painted visibility as DOM fallback evidence", async () => {
+    const S = ["html", "body", "button", "static", "auto", "visible", "hidden", "1", "0"];
+    const i = (value: string) => S.indexOf(value);
+    const snapshot = {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 1, 1],
+            nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
+            backendNodeId: [10, 11, 12, 13, 14],
+            attributes: [[], [], [], [], []],
+          },
+          layout: {
+            nodeIndex: [1, 2, 3, 4],
+            styles: [
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("hidden"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
+            ],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 100, 30],
+              [10, 50, 100, 30],
+              [10, 90, 100, 30],
+            ],
+            paintOrders: [0, 1, 2, 3],
+          },
+        },
+      ],
+    };
+
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+
+    expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
+    expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
+    expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
+  });
+
+  it("propagates fully transparent ancestor suppression to painted descendants", async () => {
+    const S = ["html", "body", "div", "canvas", "static", "auto", "visible", "1", "0"];
+    const i = (value: string) => S.indexOf(value);
+    const snapshot = {
+      strings: S,
+      documents: [
+        {
+          nodes: {
+            parentIndex: [-1, 0, 1, 2],
+            nodeName: [i("html"), i("body"), i("div"), i("canvas")],
+            backendNodeId: [10, 11, 12, 13],
+            attributes: [[], [], [], []],
+          },
+          layout: {
+            nodeIndex: [1, 2, 3],
+            styles: [
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
+              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
+            ],
+            bounds: [
+              [0, 0, 1000, 800],
+              [10, 10, 200, 100],
+              [10, 10, 200, 100],
+            ],
+            paintOrders: [0, 1, 2],
+          },
+        },
+      ],
+    };
+
+    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+    const canvas = nodes.find((node) => node.backendNodeId === 13);
+
+    expect(canvas?.rendered).toBe(true);
+    expect(canvas?.visuallySuppressed).toBe(true);
+  });
+
   it("subtracts scroll offset to make rects viewport-relative", async () => {
     const cdp = {
       send: vi.fn(async (_t: number, method: string) => {

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

@@ -132,4 +132,67 @@ describe("captureFrameData", () => {
       ]),
     );
   });
+
+  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
+    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
+    const captured: CapturedViewModel = {
+      nodes: [owner],
+      viewport: { width: 1000, height: 800 },
+      iframeNodes: new Map(),
+      frameNodes: new Map([["main", [owner]]]),
+      rootFrameId: "main",
+      excludedBackendNodeIds: new Set(),
+    };
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Accessibility.enable") return {};
+        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
+        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
+        }
+        throw new Error(`unexpected root ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
+        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
+        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
+        if (method === "Accessibility.getFullAXTree") {
+          return {
+            nodes: [
+              {
+                nodeId: "button",
+                backendDOMNodeId: 101,
+                role: { type: "role", value: "button" },
+                name: { type: "computedString", value: "Continue" },
+              },
+            ],
+          };
+        }
+        throw new Error(`unexpected ${method}`);
+      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
+      getFrameGraph: vi.fn(async () => ({
+        rootFrameId: "main",
+        frames: [
+          { frameId: "main", target: { tabId: 4 } },
+          {
+            frameId: "child",
+            parentFrameId: "main",
+            ownerBackendNodeId: 10,
+            target: { tabId: 4, sessionId: "child-session" },
+          },
+        ],
+      })),
+    };
+
+    const documents = await captureFrameData(cdp, 4, captured);
+    const childDocument = documents.find((document) => document.frameId === "child");
+
+    expect(childDocument?.axNodes).toEqual([
+      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
+    ]);
+    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
+      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
+    );
+  });
 });

apps/extension/src/tools/vom/__tests__/name-enrichment.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it, vi } from "vitest";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CdpRunner } from "../../shared";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument, FrameOwnedAxNode } from "../frame-document";
+import { probeTooltipNames } from "../name-enrichment";
+import { buildSemanticGraph, resolveSemanticGraph } from "../semantic-graph";
+import { stableIdentifierName } from "../semantic-graph/name-evidence";
+import { frameBackendKey } from "../semantic-graph/types";
+
+function document(
+  target: CdpTarget,
+  backendNodeId: number,
+  accessibleName?: string,
+  frameId = "child",
+  x = 10,
+): FrameDocument<FrameOwnedAxNode> {
+  const node: CapturedNode = {
+    backendNodeId,
+    parentBackendNodeId: null,
+    frameId,
+    tag: "button",
+    attrs: {
+      id: "toolInsertRecord",
+      "data-test-id": "toolInsertRecord",
+      ...(accessibleName ? { "aria-label": accessibleName } : {}),
+    },
+    rect: { x, y: 20, w: 40, h: 30 },
+    localRect: { x: 2, y: 3, w: 40, h: 30 },
+    paintOrder: 1,
+    position: "static",
+    pointerEvents: "auto",
+    cursor: "pointer",
+  };
+  return {
+    frameId,
+    parentFrameId: "main",
+    contextScopeId: "child",
+    target,
+    axNodes: [],
+    domNodes: [node],
+    url: "https://example.com/frame",
+  };
+}
+
+function semantics(documents: FrameDocument<FrameOwnedAxNode>[]) {
+  return resolveSemanticGraph(
+    buildSemanticGraph({
+      documents,
+      viewport: { width: 800, height: 600 },
+      rootFrameId: documents[0]?.frameId,
+    }),
+    { identifierFallback: false },
+  );
+}
+
+describe("tooltip name enrichment", () => {
+  it("uses the owning frame target and upgrades an identifier name from a tooltip", async () => {
+    const target = { tabId: 7, sessionId: "oopif-session" };
+    let hovered = false;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hovered = (params as { x?: number }).x === 30;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 11 };
+        if (method === "DOM.resolveNode") return { object: { objectId: "button-501" } };
+        if (method === "Runtime.callFunctionOn") {
+          return { result: { value: hovered ? ["插入行"] : [] } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document(target, 501)];
+    const graph = semantics(documents);
+    const names = await probeTooltipNames(cdp, 7, documents, graph);
+
+    expect(names.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.sendToTarget).toHaveBeenCalledWith(
+      target,
+      "Page.createIsolatedWorld",
+      expect.objectContaining({ frameId: "child" }),
+    );
+
+    const sendsBeforeCache = vi.mocked(cdp.send).mock.calls.length;
+    const targetSendsBeforeCache = vi.mocked(
+      cdp.sendToTarget as NonNullable<CdpRunner["sendToTarget"]>,
+    ).mock.calls.length;
+    const cached = await probeTooltipNames(cdp, 7, documents, graph);
+    expect(cached.get(frameBackendKey("child", 501))).toBe("插入行");
+    expect(cdp.send).toHaveBeenCalledTimes(sendsBeforeCache);
+    expect(cdp.sendToTarget).toHaveBeenCalledTimes(targetSendsBeforeCache);
+  });
+
+  it("does not probe controls that already have a higher-confidence name", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [document({ tabId: 8 }, 601, "Add a new record")];
+    const names = await probeTooltipNames(cdp, 8, documents, semantics(documents));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
+  it("does not collect supplemental names from form controls", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async () => ({ executionContextId: 12 })) as CdpRunner["sendToTarget"],
+    };
+    const inputDocument = document({ tabId: 8 }, 602);
+    inputDocument.domNodes[0] = {
+      ...inputDocument.domNodes[0],
+      tag: "input",
+      attrs: { type: "email" },
+      formValue: "user@example.com",
+      formDefaultValue: "",
+      formState: "filled",
+    };
+
+    const names = await probeTooltipNames(cdp, 8, [inputDocument], semantics([inputDocument]));
+
+    expect(names.size).toBe(0);
+    expect(cdp.send).not.toHaveBeenCalled();
+    expect(cdp.sendToTarget).not.toHaveBeenCalled();
+  });
+
+  it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
+    let hoveredX = -10;
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        if (method === "Input.dispatchMouseEvent") {
+          hoveredX = (params as { x: number }).x;
+        }
+        return {};
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (target, method, params) => {
+        if (method === "Page.createIsolatedWorld") {
+          return { executionContextId: target.sessionId === "left-session" ? 21 : 22 };
+        }
+        if (method === "DOM.resolveNode") {
+          return { object: { objectId: target.sessionId === "left-session" ? "left" : "right" } };
+        }
+        if (method === "Runtime.callFunctionOn") {
+          const objectId = (params as { objectId: string }).objectId;
+          const value =
+            objectId === "left" && hoveredX === 30
+              ? ["Left action"]
+              : objectId === "right" && hoveredX === 130
+                ? ["Right action"]
+                : [];
+          return { result: { value } };
+        }
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+    const documents = [
+      document({ tabId: 9, sessionId: "left-session" }, 701, undefined, "left", 10),
+      document({ tabId: 9, sessionId: "right-session" }, 701, undefined, "right", 110),
+    ];
+
+    const names = await probeTooltipNames(cdp, 9, documents, semantics(documents));
+
+    expect(names.get(frameBackendKey("left", 701))).toBe("Left action");
+    expect(names.get(frameBackendKey("right", 701))).toBe("Right action");
+  });
+});
+
+describe("stable identifier evidence", () => {
+  it("accepts readable action identifiers and rejects framework-generated ids", () => {
+    expect(stableIdentifierName({ id: "toolInsertRecord" })).toBe("Insert record");
+    expect(stableIdentifierName({ id: "reactivateAccount" })).toBe("Reactivate account");
+    expect(stableIdentifierName({ id: "headlessui-menu-button-r1" })).toBeUndefined();
+    expect(stableIdentifierName({ id: "7f15a3bc91" })).toBeUndefined();
+  });
+});

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/__tests__/semantic-graph.test.ts

@@ -0,0 +1,782 @@
+import { isVomReferenceNode, renderVom } from "@browser-skill/vom";
+import { describe, expect, it } from "vitest";
+import type { CapturedNode } from "../capture";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticVomScene, type SemanticAxNode } from "../semantic-graph";
+
+function dom(
+  backendNodeId: number,
+  parentBackendNodeId: number | null,
+  tag: string,
+  attrs: Record<string, string> = {},
+  textContent?: string,
+): CapturedNode {
+  return {
+    backendNodeId,
+    parentBackendNodeId,
+    tag,
+    attrs,
+    rect: { x: 0, y: 0, w: 100, h: 30 },
+    paintOrder: backendNodeId,
+    position: "static",
+    pointerEvents: "auto",
+    ...(textContent ? { textContent } : {}),
+  };
+}
+
+function document(
+  frameId: string,
+  axNodes: SemanticAxNode[],
+  domNodes: CapturedNode[],
+  frame?: Pick<FrameDocument<SemanticAxNode>, "parentFrameId" | "ownerBackendNodeId">,
+): FrameDocument<SemanticAxNode> {
+  return {
+    frameId,
+    contextScopeId: frameId,
+    target: { tabId: 1 },
+    axNodes,
+    domNodes,
+    ...frame,
+  };
+}
+
+describe("semantic VOM graph", () => {
+  it("preserves backend-less AX structure without making it referenceable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              role: { type: "role", value: "toolbar" },
+              name: { type: "computedString", value: "Formatting" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "toolbar",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "toolbar",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "button"), dom(3, 1, "button")],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.role === "toolbar");
+    const buttons = scene.nodes.filter((node) => node.role === "button");
+    expect(toolbar).toEqual(expect.objectContaining({ name: "Formatting", referenceable: false }));
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(renderVom(scene).refs.map((ref) => ref.backendNodeId)).toEqual([2, 3]);
+  });
+
+  it("resolves missing AX names through one DOM naming pipeline", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["labelled", "titled", "text"],
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "titled",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+            },
+            {
+              nodeId: "text",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "button", { "aria-label": "Add row" }),
+            dom(3, 1, "button", { title: "Settings" }),
+            dom(4, 1, "button"),
+            dom(5, 4, "span", {}, "Save"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.filter((node) => node.role === "button").map((node) => node.name)).toEqual([
+      "Add row",
+      "Settings",
+      "Save",
+    ]);
+  });
+
+  it("aggregates AX text at the semantic text frontier", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["covered", "inline-only", "repeated", "labelled"],
+            },
+            {
+              nodeId: "covered",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["covered-static"],
+            },
+            {
+              nodeId: "covered-static",
+              parentId: "covered",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Covered text" },
+              childIds: ["covered-inline"],
+            },
+            {
+              nodeId: "covered-inline",
+              parentId: "covered-static",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Covered text" },
+            },
+            {
+              nodeId: "inline-only",
+              parentId: "root",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["inline-leaf"],
+            },
+            {
+              nodeId: "inline-leaf",
+              parentId: "inline-only",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Inline fallback" },
+            },
+            {
+              nodeId: "repeated",
+              parentId: "root",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "paragraph" },
+              childIds: ["first-go", "second-go"],
+            },
+            {
+              nodeId: "first-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "second-go",
+              parentId: "repeated",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Go" },
+            },
+            {
+              nodeId: "labelled",
+              parentId: "root",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["visible-label"],
+            },
+            {
+              nodeId: "visible-label",
+              parentId: "labelled",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Visible text" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "p"),
+            dom(3, 1, "p"),
+            dom(4, 1, "p"),
+            dom(5, 1, "button", { "aria-label": "Explicit action" }),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Covered text");
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Inline fallback");
+    expect(scene.nodes.find((node) => node.backendNodeId === 4)?.name).toBe("Go Go");
+    expect(scene.nodes.find((node) => node.backendNodeId === 5)?.name).toBe("Explicit action");
+    expect(renderVom(scene).text).not.toContain("Covered text Covered text");
+  });
+
+  it("uses stable identifiers only as a final name fallback", () => {
+    const base = document(
+      "main",
+      [
+        {
+          nodeId: "root",
+          backendDOMNodeId: 1,
+          role: { type: "role", value: "RootWebArea" },
+          childIds: ["fallback", "labelled", "container"],
+        },
+        {
+          nodeId: "fallback",
+          parentId: "root",
+          backendDOMNodeId: 2,
+          role: { type: "role", value: "button" },
+        },
+        {
+          nodeId: "labelled",
+          parentId: "root",
+          backendDOMNodeId: 3,
+          role: { type: "role", value: "button" },
+          name: { type: "computedString", value: "Localized name" },
+        },
+        {
+          nodeId: "container",
+          parentId: "root",
+          backendDOMNodeId: 4,
+          role: { type: "role", value: "generic" },
+        },
+      ],
+      [
+        dom(1, null, "body"),
+        dom(2, 1, "button", { "data-test-id": "toolInsertRecord" }),
+        dom(3, 1, "button", { id: "toolIgnoredFallback" }),
+        dom(4, 1, "div", { id: "toolbarContainer" }),
+      ],
+    );
+    const staticScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+    });
+    const enrichedScene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [base],
+      supplementalNames: new Map([["main\u00002", "插入行"]]),
+    });
+
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("Insert record");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe("Localized name");
+    expect(staticScene.nodes.find((node) => node.backendNodeId === 4)?.name).toBeUndefined();
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 2)?.name).toBe("插入行");
+    expect(enrichedScene.nodes.find((node) => node.backendNodeId === 3)?.name).toBe(
+      "Localized name",
+    );
+  });
+
+  it("isolates equal backend node ids in sibling frames", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 1000, height: 800 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["owner-a", "owner-b"],
+            },
+            {
+              nodeId: "owner-a",
+              parentId: "root",
+              backendDOMNodeId: 10,
+              role: { type: "role", value: "Iframe" },
+            },
+            {
+              nodeId: "owner-b",
+              parentId: "root",
+              backendDOMNodeId: 20,
+              role: { type: "role", value: "Iframe" },
+            },
+          ],
+          [dom(1, null, "body"), dom(10, 1, "iframe"), dom(20, 1, "iframe")],
+        ),
+        document(
+          "frame-a",
+          [
+            {
+              nodeId: "button-a",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["text-a"],
+            },
+            {
+              nodeId: "text-a",
+              parentId: "button-a",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Accept" },
+              childIds: ["inline-a"],
+            },
+            {
+              nodeId: "inline-a",
+              parentId: "text-a",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Accept" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 10 },
+        ),
+        document(
+          "frame-b",
+          [
+            {
+              nodeId: "button-b",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              childIds: ["text-b"],
+            },
+            {
+              nodeId: "text-b",
+              parentId: "button-b",
+              role: { type: "role", value: "StaticText" },
+              name: { type: "computedString", value: "Decline" },
+              childIds: ["inline-b"],
+            },
+            {
+              nodeId: "inline-b",
+              parentId: "text-b",
+              role: { type: "role", value: "InlineTextBox" },
+              name: { type: "computedString", value: "Decline" },
+            },
+          ],
+          [dom(5, null, "button")],
+          { parentFrameId: "main", ownerBackendNodeId: 20 },
+        ),
+      ],
+    });
+
+    const frameButtons = scene.nodes.filter((node) => node.backendNodeId === 5);
+    const owners = new Map(
+      scene.nodes
+        .filter((node) => node.backendNodeId === 10 || node.backendNodeId === 20)
+        .map((node) => [node.backendNodeId, node.id]),
+    );
+    expect(frameButtons.map((node) => node.frameId)).toEqual(["frame-a", "frame-b"]);
+    expect(frameButtons.map((node) => node.name)).toEqual(["Accept", "Decline"]);
+    expect(frameButtons.map((node) => node.parentId)).toEqual([owners.get(10), owners.get(20)]);
+    expect(renderVom(scene).refs.map((ref) => [ref.frameId, ref.backendNodeId])).toEqual([
+      ["frame-a", 5],
+      ["frame-b", 5],
+    ]);
+  });
+
+  it("requires render evidence before promoting DOM fallback semantics", () => {
+    const hiddenOwner = {
+      ...dom(10, 1, "iframe", { hidden: "" }),
+      rect: null,
+      localRect: null,
+      rendered: false,
+    };
+    const hiddenButton = {
+      ...dom(2, 1, "button", { "aria-label": "Hidden action" }),
+      rendered: false,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+            },
+          ],
+          [dom(1, null, "body"), hiddenButton, hiddenOwner],
+        ),
+        document("hidden-frame", [], [dom(20, null, "button", {}, "Frame action")], {
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+        }),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.backendNodeId === 2)).toBe(false);
+    expect(scene.nodes.some((node) => node.backendNodeId === 10)).toBe(false);
+    expect(scene.nodes.some((node) => node.frameId === "hidden-frame")).toBe(false);
+    expect(renderVom(scene).refs).toEqual([]);
+  });
+
+  it("retains rendered DOM fallback controls when AX semantics are unavailable", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [],
+          [dom(1, null, "body"), { ...dom(2, 1, "button", {}, "Save"), rendered: true }],
+        ),
+      ],
+    });
+
+    expect(renderVom(scene).refs).toEqual([
+      expect.objectContaining({ backendNodeId: 2, role: "button", name: "Save" }),
+    ]);
+  });
+
+  it("lets explicit DOM structure override ignored AX metadata", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["toolbar"],
+            },
+            {
+              nodeId: "toolbar",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              ignored: true,
+              role: { type: "role", value: "generic" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "toolbar",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "generic" },
+              childIds: ["bold", "italic"],
+            },
+            {
+              nodeId: "bold",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Bold" },
+            },
+            {
+              nodeId: "italic",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Italic" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div", { role: "toolbar" }),
+            dom(5, 2, "div"),
+            dom(3, 5, "button"),
+            dom(4, 5, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const toolbar = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(toolbar).toEqual(expect.objectContaining({ role: "toolbar" }));
+    expect(toolbar && isVomReferenceNode(toolbar)).toBe(false);
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([toolbar?.id, toolbar?.id]);
+  });
+
+  it("infers an unnamed group only from independent interaction branches", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button"), dom(4, 2, "button")],
+        ),
+      ],
+    });
+
+    const group = scene.nodes.find((node) => node.backendNodeId === 2);
+    const buttons = scene.nodes.filter((node) => [3, 4].includes(node.backendNodeId ?? -1));
+    expect(group).toEqual(expect.objectContaining({ role: "group" }));
+    expect(group?.name).toBeUndefined();
+    expect(group && isVomReferenceNode(group)).toBe(false);
+    expect(buttons.map((node) => node.parentId)).toEqual([group?.id, group?.id]);
+
+    const rendered = renderVom(scene);
+    const lines = rendered.text.split("\n");
+    const groupLine = lines.findIndex((line) => line.trim() === "group");
+    expect(groupLine).toBeGreaterThanOrEqual(0);
+    for (const ref of rendered.refs) {
+      expect(ref.line).toBeGreaterThan(groupLine);
+      expect(lines[ref.line]).toMatch(/^\s+@e\d+ button/);
+    }
+  });
+
+  it("never promotes a form value into its semantic name through supplemental evidence", () => {
+    const secret = "user@example.com";
+    const input = {
+      ...dom(2, 1, "input", { type: "email" }),
+      formValue: secret,
+      formDefaultValue: "",
+      formState: "filled" as const,
+    };
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      supplementalNames: new Map([["main\u00002", secret]]),
+      identifierFallback: false,
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["email"],
+            },
+            {
+              nodeId: "email",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "textbox" },
+              value: { value: secret },
+            },
+          ],
+          [dom(1, null, "body"), input],
+        ),
+      ],
+    });
+
+    const field = scene.nodes.find((node) => node.backendNodeId === 2);
+    expect(field?.name).toBeUndefined();
+    const rendered = renderVom(scene, { redactValues: true });
+    expect(rendered.text).toContain("•••");
+    expect(JSON.stringify(rendered)).not.toContain(secret);
+  });
+
+  it("keeps uncertain single-branch wrappers flat", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["button"],
+            },
+            {
+              nodeId: "button",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Only action" },
+            },
+          ],
+          [dom(1, null, "body"), dom(2, 1, "div"), dom(3, 2, "button")],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+    expect(scene.nodes.find((node) => node.backendNodeId === 3)?.parentId).toBe(
+      scene.nodes.find((node) => node.backendNodeId === 1)?.id,
+    );
+  });
+
+  it("does not infer across mixed content boundaries", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["wrapper"],
+            },
+            {
+              nodeId: "wrapper",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second", "paragraph"],
+            },
+            {
+              nodeId: "first",
+              parentId: "wrapper",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "wrapper",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "paragraph",
+              parentId: "wrapper",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "paragraph" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "button"),
+            dom(4, 2, "button"),
+            dom(5, 2, "p", {}, "Description"),
+          ],
+        ),
+      ],
+    });
+
+    expect(scene.nodes.some((node) => node.role === "group")).toBe(false);
+  });
+
+  it("keeps only the innermost reliable inferred group", () => {
+    const scene = buildSemanticVomScene({
+      viewport: { width: 800, height: 600 },
+      rootFrameId: "main",
+      documents: [
+        document(
+          "main",
+          [
+            {
+              nodeId: "root",
+              backendDOMNodeId: 1,
+              role: { type: "role", value: "RootWebArea" },
+              childIds: ["outer"],
+            },
+            {
+              nodeId: "outer",
+              parentId: "root",
+              backendDOMNodeId: 2,
+              role: { type: "role", value: "generic" },
+              childIds: ["inner", "third"],
+            },
+            {
+              nodeId: "inner",
+              parentId: "outer",
+              backendDOMNodeId: 3,
+              role: { type: "role", value: "generic" },
+              childIds: ["first", "second"],
+            },
+            {
+              nodeId: "first",
+              parentId: "inner",
+              backendDOMNodeId: 4,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "First" },
+            },
+            {
+              nodeId: "second",
+              parentId: "inner",
+              backendDOMNodeId: 5,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Second" },
+            },
+            {
+              nodeId: "third",
+              parentId: "outer",
+              backendDOMNodeId: 6,
+              role: { type: "role", value: "button" },
+              name: { type: "computedString", value: "Third" },
+            },
+          ],
+          [
+            dom(1, null, "body"),
+            dom(2, 1, "div"),
+            dom(3, 2, "div"),
+            dom(4, 3, "button"),
+            dom(5, 3, "button"),
+            dom(6, 2, "button"),
+          ],
+        ),
+      ],
+    });
+
+    const groups = scene.nodes.filter((node) => node.role === "group");
+    expect(groups.map((node) => node.backendNodeId)).toEqual([3]);
+    expect(scene.nodes.find((node) => node.backendNodeId === 6)?.parentId).not.toBe(groups[0]?.id);
+  });
+});

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

@@ -1,16 +1,25 @@
 // CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
 // → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
 // raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
-// shared string table); we request exactly three computed styles so the
-// `styles` columns are [position, pointer-events, cursor] in that order.
+// shared string table); requested computed styles are decoded through
+// STYLE_COL so capture and visibility policy share one explicit contract.
 
 import type { Rect, Viewport } from "@browser-skill/vom";
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
 import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
 import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
 import type { CdpRunner } from "../shared";
+import { clearHover, waitForHover } from "./hover-perception";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor"] 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>;
@@ -38,6 +47,16 @@ 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
+   * nodes remain authoritative even when they are outside the viewport.
+   */
+  rendered?: boolean;
   textContent?: string;
   formState?: "empty" | "filled" | "default";
   formValue?: string;
@@ -460,36 +479,6 @@ function hoverStateExpression(): string {
   })()`;
 }
 
-async function wait(ms: number, signal?: AbortSignal): Promise<void> {
-  throwIfAborted(signal);
-  await new Promise<void>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(captureAbortError());
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp
-    .send(tabId, "Input.dispatchMouseEvent", {
-      type: "mouseMoved",
-      x: -10,
-      y: -10,
-    })
-    .catch(() =>
-      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
-        // best effort
-      }),
-    );
-}
-
 function capturedText(node: CapturedNode): string | undefined {
   const value =
     node.attrs["aria-label"] ?? node.attrs.title ?? node.attrs.alt ?? node.textContent ?? "";
@@ -669,7 +658,7 @@ async function probeHoverSurfaces(
         try {
           await clearHover(cdp, tabId);
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -684,7 +673,7 @@ async function probeHoverSurfaces(
             y: candidate.y,
           });
           throwIfAborted(options.signal);
-          await wait(HOVER_SETTLE_MS, options.signal);
+          await waitForHover(HOVER_SETTLE_MS, options.signal);
           const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
             expression: hoverStateExpression(),
             returnByValue: true,
@@ -817,6 +806,10 @@ function parseDocumentNodes(
   const posCol = STYLE_COL.position;
   const peCol = STYLE_COL["pointer-events"];
   const cursorCol = STYLE_COL.cursor;
+  const visibilityCol = STYLE_COL.visibility;
+  const opacityCol = STYLE_COL.opacity;
+  const overflowXCol = STYLE_COL["overflow-x"];
+  const overflowYCol = STYLE_COL["overflow-y"];
   const inputValues = sparseIndexMap(dn.inputValue);
   const textValues = sparseIndexMap(dn.textValue);
   const checkedInputs = new Set(dn.inputChecked?.index ?? []);
@@ -842,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];
@@ -861,6 +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];
@@ -881,7 +880,21 @@ function parseDocumentNodes(
       position = str(strings, styleRow[posCol]) || "static";
       pointerEvents = str(strings, styleRow[peCol]) || "auto";
       cursor = str(strings, styleRow[cursorCol]) || "auto";
+      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
+      const opacity = str(strings, styleRow[opacityCol]) || "1";
+      overflowX = str(strings, styleRow[overflowXCol]) || "visible";
+      overflowY = str(strings, styleRow[overflowYCol]) || "visible";
+      visuallySuppressed ||=
+        visibility === "hidden" ||
+        visibility === "collapse" ||
+        (Number.parseFloat(opacity) || 0) <= 0;
+      rendered =
+        localRect !== null &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0;
     }
+    visuallySuppressedByNodeIndex[n] = visuallySuppressed;
 
     // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
     // geometry and are never queried by callers.
@@ -916,6 +929,10 @@ function parseDocumentNodes(
       position,
       pointerEvents,
       cursor,
+      overflowX,
+      overflowY,
+      visuallySuppressed,
+      rendered,
       textContent,
       ...(formValue !== undefined ? { formValue } : {}),
       ...(tag === "input" || tag === "textarea"
@@ -1020,7 +1037,13 @@ export async function captureViewModel(
   options: CaptureViewModelOptions = {},
 ): Promise<CapturedViewModel> {
   throwIfAborted(options.signal);
-  const metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  let metrics: LayoutMetricsReply = {};
+  try {
+    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    console.debug("[bsk capture] layout metrics unavailable", error);
+  }
   throwIfAborted(options.signal);
   const dpr = devicePixelRatio(metrics);
   const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};

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

@@ -33,25 +33,19 @@ async function discoverFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFra
 
 function transformFrameNodes(
   nodes: CapturedNode[],
-  projection: GeometryProjection,
+  projection: GeometryProjection | null,
 ): CapturedNode[] {
   return nodes.map((node) => ({
     ...node,
-    rect: (() => {
-      const bounds = projectRectToViewport(node.rect, projection);
-      return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
-    })(),
+    rect: projection
+      ? (() => {
+          const bounds = projectRectToViewport(node.rect, projection);
+          return bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
+        })()
+      : null,
   }));
 }
 
-function frameOwnerNode(captured: CapturedViewModel, frame: CdpFrame): CapturedNode | undefined {
-  if (frame.ownerBackendNodeId === undefined) return undefined;
-  const parentNodes = frame.parentFrameId
-    ? captured.frameNodes?.get(frame.parentFrameId)
-    : captured.nodes;
-  return parentNodes?.find((node) => node.backendNodeId === frame.ownerBackendNodeId);
-}
-
 async function captureMissingFrameDocuments(
   cdp: CdpRunner,
   tabId: number,
@@ -65,14 +59,20 @@ async function captureMissingFrameDocuments(
 
   for (const frame of graph.frames) {
     if (!frame.target.sessionId || captured.frameNodes.has(frame.frameId)) continue;
-    const owner = frameOwnerNode(captured, frame);
-    if (!owner?.rect || frame.ownerBackendNodeId === undefined) continue;
     try {
       const child = await captureViewModel(cdpRunnerForTarget(cdp, frame.target), tabId, {
         signal,
       });
-      const projection = await resolveFrameProjection(cdp, graph, frame.frameId);
-      if (!projection) continue;
+      let projection: GeometryProjection | null = null;
+      try {
+        projection = await resolveFrameProjection(cdp, graph, frame.frameId);
+      } catch (err) {
+        if (isAbortError(err)) throw err;
+        console.debug("[bsk observation] child frame geometry projection failed", {
+          frameId: frame.frameId,
+          err,
+        });
+      }
       const rootFrameId = child.rootFrameId ?? frame.frameId;
       const childFrames = child.frameNodes ?? new Map<string, CapturedNode[]>();
       if (!childFrames.has(rootFrameId)) childFrames.set(rootFrameId, child.nodes);
@@ -85,11 +85,13 @@ async function captureMissingFrameDocuments(
       for (const [childFrameId, nodes] of childFrames) {
         captured.frameNodes.set(childFrameId, transformFrameNodes(nodes, projection));
       }
-      captured.iframeNodes.set(
-        frame.ownerBackendNodeId,
-        captured.frameNodes.get(frame.frameId) ?? [],
-      );
-      captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      if (frame.ownerBackendNodeId !== undefined) {
+        captured.iframeNodes.set(
+          frame.ownerBackendNodeId,
+          captured.frameNodes.get(frame.frameId) ?? [],
+        );
+        captured.frameOwnerBackendNodeIds.set(frame.frameId, frame.ownerBackendNodeId);
+      }
       if (frame.parentFrameId) captured.frameParentIds.set(frame.frameId, frame.parentFrameId);
       for (const [childFrameId, ownerBackendNodeId] of child.frameOwnerBackendNodeIds ?? []) {
         captured.frameOwnerBackendNodeIds.set(childFrameId, ownerBackendNodeId);

apps/extension/src/tools/vom/hover-perception.ts

@@ -0,0 +1,37 @@
+import type { CdpRunner } from "../shared";
+
+function abortError(): Error {
+  const error = new Error("hover perception aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export async function waitForHover(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) throw abortError();
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export async function clearHover(cdp: CdpRunner, tabId: number): Promise<void> {
+  await cdp
+    .send(tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: -10,
+      y: -10,
+    })
+    .catch(() =>
+      cdp.send(tabId, "Input.dispatchMouseEvent", { type: "mouseMoved", x: 0, y: 0 }).catch(() => {
+        // Best effort cleanup.
+      }),
+    );
+}

apps/extension/src/tools/vom/name-enrichment.ts

@@ -0,0 +1,296 @@
+import { isVomReferenceNode } from "@browser-skill/vom";
+import { type CdpRunner, sendToCdpTarget } from "../shared";
+import type { FrameDocument, FrameOwnedAxNode } from "./frame-document";
+import { clearHover, waitForHover } from "./hover-perception";
+import { stableIdentifierName } from "./semantic-graph/name-evidence";
+import { frameBackendKey, type ResolvedSemanticGraph } from "./semantic-graph/types";
+
+const MAX_TOOLTIP_CANDIDATES = 8;
+const MAX_TOOLTIP_PROBE_MS = 2_400;
+const TOOLTIP_SETTLE_MS = 250;
+const CACHE_TTL_MS = 5 * 60_000;
+const MAX_CACHE_ENTRIES = 500;
+const FORM_CONTROL_TAGS = new Set(["input", "select", "textarea"]);
+
+interface TooltipCacheEntry {
+  name: string;
+  expiresAt: number;
+}
+
+interface TooltipCandidate<T extends FrameOwnedAxNode> {
+  document: FrameDocument<T>;
+  backendNodeId: number;
+  x: number;
+  y: number;
+  stableIdentifier: boolean;
+}
+
+export interface TooltipNameProbeOptions {
+  signal?: AbortSignal;
+  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
+}
+
+const tooltipCache = new Map<string, TooltipCacheEntry>();
+
+function cacheKey<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string {
+  return `${document.target.tabId}\u0000${document.frameId}\u0000${document.url ?? ""}\u0000${backendNodeId}`;
+}
+
+function cachedName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+): string | undefined {
+  const key = cacheKey(document, backendNodeId);
+  const entry = tooltipCache.get(key);
+  if (!entry) return undefined;
+  if (entry.expiresAt <= Date.now()) {
+    tooltipCache.delete(key);
+    return undefined;
+  }
+  return entry.name;
+}
+
+function storeName<T extends FrameOwnedAxNode>(
+  document: FrameDocument<T>,
+  backendNodeId: number,
+  name: string,
+): void {
+  if (tooltipCache.size >= MAX_CACHE_ENTRIES) {
+    const oldest = tooltipCache.keys().next().value;
+    if (oldest !== undefined) tooltipCache.delete(oldest);
+  }
+  tooltipCache.set(cacheKey(document, backendNodeId), {
+    name,
+    expiresAt: Date.now() + CACHE_TTL_MS,
+  });
+}
+
+function tooltipCollectorFunction(): string {
+  return `function() {
+    const ownRoot = this && typeof this.getRootNode === "function" ? this.getRootNode() : null;
+    const roots = ownRoot && ownRoot !== document ? [ownRoot, document] : [document];
+    const items = [];
+    const seen = new Set();
+    for (const root of roots) {
+      for (const el of Array.from(root.querySelectorAll("[role='tooltip']"))) {
+        const style = getComputedStyle(el);
+        const rect = el.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") continue;
+        const text = String(el.getAttribute("aria-label") || el.getAttribute("title") || el.textContent || "")
+          .replace(/\\s+/g, " ")
+          .trim();
+        if (!text || text.length > 160 || seen.has(text)) continue;
+        seen.add(text);
+        items.push(text);
+      }
+    }
+    return items.slice(0, 20);
+  }`;
+}
+
+function cleanTooltipDiff(before: string[], after: string[]): string | undefined {
+  const existing = new Set(before.map((value) => value.toLowerCase()));
+  const added = [...new Set(after.map((value) => value.replace(/\s+/g, " ").trim()))].filter(
+    (value) => value && !existing.has(value.toLowerCase()),
+  );
+  return added.length === 1 ? added[0] : undefined;
+}
+
+function candidates<T extends FrameOwnedAxNode>(
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+): TooltipCandidate<T>[] {
+  const documentByFrame = new Map(documents.map((document) => [document.frameId, document]));
+  const byFrame = new Map<string, TooltipCandidate<T>[]>();
+  for (const node of graph.nodes.values()) {
+    if (
+      node.vom.name ||
+      FORM_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "") ||
+      !node.referenceable ||
+      node.backendNodeId === undefined ||
+      !isVomReferenceNode({
+        ...node.vom,
+        id: 0,
+        parentId: null,
+        backendNodeId: node.backendNodeId,
+        frameId: node.frameId,
+        referenceable: true,
+      })
+    ) {
+      continue;
+    }
+    const document = documentByFrame.get(node.frameId);
+    const rect = node.dom?.rect;
+    if (!document || !rect || rect.w <= 0 || rect.h <= 0) continue;
+    if (
+      rect.x + rect.w <= 0 ||
+      rect.y + rect.h <= 0 ||
+      rect.x >= graph.viewport.width ||
+      rect.y >= graph.viewport.height
+    ) {
+      continue;
+    }
+    if (
+      node.vom.disabled ||
+      node.vom.inert ||
+      node.vom.pointerEvents === "none" ||
+      node.vom.sensitive
+    ) {
+      continue;
+    }
+    const frameCandidates = byFrame.get(node.frameId) ?? [];
+    frameCandidates.push({
+      document,
+      backendNodeId: node.backendNodeId,
+      x: (Math.max(0, rect.x) + Math.min(graph.viewport.width, rect.x + rect.w)) / 2,
+      y: (Math.max(0, rect.y) + Math.min(graph.viewport.height, rect.y + rect.h)) / 2,
+      stableIdentifier: stableIdentifierName(node.dom?.attrs ?? {}) !== undefined,
+    });
+    byFrame.set(node.frameId, frameCandidates);
+  }
+
+  const out: TooltipCandidate<T>[] = [];
+  for (const stableIdentifier of [true, false]) {
+    const queues = documents.map((document) =>
+      (byFrame.get(document.frameId) ?? []).filter(
+        (candidate) => candidate.stableIdentifier === stableIdentifier,
+      ),
+    );
+    for (let index = 0; queues.some((queue) => index < queue.length); index += 1) {
+      for (const queue of queues) {
+        const candidate = queue[index];
+        if (candidate) out.push(candidate);
+      }
+    }
+  }
+  return out;
+}
+
+async function executionContextId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+): Promise<number | undefined> {
+  const result = await sendToCdpTarget<{ executionContextId?: number }>(
+    cdp,
+    document.target,
+    "Page.createIsolatedWorld",
+    {
+      frameId: document.frameId,
+      worldName: "bsk-vom-tooltip",
+      grantUniveralAccess: false,
+    },
+  );
+  return result.executionContextId;
+}
+
+async function resolvedObjectId<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  contextId: number,
+  backendNodeId: number,
+): Promise<string | undefined> {
+  const result = await sendToCdpTarget<{
+    object?: { objectId?: string };
+  }>(cdp, document.target, "DOM.resolveNode", {
+    backendNodeId,
+    executionContextId: contextId,
+  });
+  return result.object?.objectId;
+}
+
+async function tooltipTexts<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<string[]> {
+  const result = await sendToCdpTarget<{
+    result?: { value?: string[] };
+  }>(cdp, document.target, "Runtime.callFunctionOn", {
+    functionDeclaration: tooltipCollectorFunction(),
+    objectId,
+    returnByValue: true,
+  });
+  return result.result?.value ?? [];
+}
+
+async function releaseObject<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  document: FrameDocument<T>,
+  objectId: string,
+): Promise<void> {
+  await sendToCdpTarget(cdp, document.target, "Runtime.releaseObject", { objectId }).catch(
+    () => undefined,
+  );
+}
+
+export async function probeTooltipNames<T extends FrameOwnedAxNode>(
+  cdp: CdpRunner,
+  tabId: number,
+  documents: FrameDocument<T>[],
+  graph: ResolvedSemanticGraph,
+  options: TooltipNameProbeOptions = {},
+): Promise<Map<string, string>> {
+  const names = new Map<string, string>();
+  const pending: TooltipCandidate<T>[] = [];
+  for (const candidate of candidates(documents, graph)) {
+    const cached = cachedName(candidate.document, candidate.backendNodeId);
+    if (cached) {
+      names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), cached);
+    } else if (pending.length < MAX_TOOLTIP_CANDIDATES) {
+      pending.push(candidate);
+    }
+  }
+  if (pending.length === 0) return names;
+
+  const started = Date.now();
+  const contexts = new Map<string, number>();
+  await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
+  try {
+    for (const candidate of pending) {
+      if (options.signal?.aborted) throw new DOMException("observation aborted", "AbortError");
+      if (Date.now() - started >= MAX_TOOLTIP_PROBE_MS) break;
+      let objectId: string | undefined;
+      try {
+        let contextId = contexts.get(candidate.document.frameId);
+        if (contextId === undefined) {
+          contextId = await executionContextId(cdp, candidate.document);
+          if (contextId === undefined) continue;
+          contexts.set(candidate.document.frameId, contextId);
+        }
+        objectId = await resolvedObjectId(
+          cdp,
+          candidate.document,
+          contextId,
+          candidate.backendNodeId,
+        );
+        if (!objectId) continue;
+        await clearHover(cdp, tabId);
+        const before = await tooltipTexts(cdp, candidate.document, objectId);
+        await cdp.send(tabId, "Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: candidate.x,
+          y: candidate.y,
+        });
+        await waitForHover(TOOLTIP_SETTLE_MS, options.signal);
+        const after = await tooltipTexts(cdp, candidate.document, objectId);
+        const name = cleanTooltipDiff(before, after);
+        if (!name) continue;
+        names.set(frameBackendKey(candidate.document.frameId, candidate.backendNodeId), name);
+        storeName(candidate.document, candidate.backendNodeId, name);
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+      } finally {
+        if (objectId) await releaseObject(cdp, candidate.document, objectId);
+        await clearHover(cdp, tabId);
+      }
+    }
+  } finally {
+    await clearHover(cdp, tabId);
+    await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
+  }
+  return names;
+}

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/tools/vom/semantic-graph/build.ts

@@ -0,0 +1,154 @@
+import type { Viewport } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import {
+  frameAxKey,
+  frameBackendKey,
+  type SemanticAxNode,
+  type SemanticFrame,
+  type SemanticGraph,
+  type SemanticGraphNode,
+  type SemanticNodeId,
+} from "./types";
+
+export interface BuildSemanticGraphInput {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}
+
+function domNodeId(frameId: string, backendNodeId: number): SemanticNodeId {
+  return JSON.stringify([frameId, "dom", backendNodeId]);
+}
+
+function axNodeId(frameId: string, nodeId: string): SemanticNodeId {
+  return JSON.stringify([frameId, "ax", nodeId]);
+}
+
+export function buildSemanticGraph(input: BuildSemanticGraphInput): SemanticGraph {
+  const rootFrameId =
+    input.rootFrameId ??
+    input.documents.find((document) => !document.parentFrameId)?.frameId ??
+    input.documents[0]?.frameId ??
+    "root";
+  const frames = new Map<string, SemanticFrame>();
+  const nodes = new Map<SemanticNodeId, SemanticGraphNode>();
+  const nodeIdsByFrame = new Map<string, SemanticNodeId[]>();
+  const nodeByFrameBackend = new Map<string, SemanticNodeId>();
+  const nodeByFrameAx = new Map<string, SemanticNodeId>();
+
+  for (const [frameOrder, document] of input.documents.entries()) {
+    frames.set(document.frameId, {
+      frameId: document.frameId,
+      ...(document.parentFrameId ? { parentFrameId: document.parentFrameId } : {}),
+      ...(document.ownerBackendNodeId !== undefined
+        ? { ownerBackendNodeId: document.ownerBackendNodeId }
+        : {}),
+      contextScopeId: document.contextScopeId,
+      target: document.target,
+      ...(document.url ? { url: document.url } : {}),
+      order: frameOrder,
+    });
+
+    const frameNodeIds: SemanticNodeId[] = [];
+    nodeIdsByFrame.set(document.frameId, frameNodeIds);
+    for (const [index, dom] of document.domNodes.entries()) {
+      const id = domNodeId(document.frameId, dom.backendNodeId);
+      const node: SemanticGraphNode = {
+        id,
+        frameId: document.frameId,
+        backendNodeId: dom.backendNodeId,
+        dom,
+        sourceOrder: index,
+        excluded:
+          document.frameId === rootFrameId &&
+          input.excludedBackendNodeIds?.has(dom.backendNodeId) === true,
+      };
+      nodes.set(id, node);
+      frameNodeIds.push(id);
+      nodeByFrameBackend.set(frameBackendKey(document.frameId, dom.backendNodeId), id);
+    }
+
+    for (const [index, ax] of document.axNodes.entries()) {
+      const joinedId =
+        typeof ax.backendDOMNodeId === "number"
+          ? nodeByFrameBackend.get(frameBackendKey(document.frameId, ax.backendDOMNodeId))
+          : undefined;
+      const id = joinedId ?? axNodeId(document.frameId, ax.nodeId);
+      const existing = nodes.get(id);
+      if (existing) {
+        existing.ax = ax;
+        existing.axNodeId = ax.nodeId;
+      } else {
+        nodes.set(id, {
+          id,
+          frameId: document.frameId,
+          ...(typeof ax.backendDOMNodeId === "number"
+            ? { backendNodeId: ax.backendDOMNodeId }
+            : {}),
+          axNodeId: ax.nodeId,
+          ax,
+          sourceOrder: document.domNodes.length + index,
+          excluded:
+            document.frameId === rootFrameId &&
+            typeof ax.backendDOMNodeId === "number" &&
+            input.excludedBackendNodeIds?.has(ax.backendDOMNodeId) === true,
+        });
+        frameNodeIds.push(id);
+      }
+      nodeByFrameAx.set(frameAxKey(document.frameId, ax.nodeId), id);
+    }
+  }
+
+  for (const document of input.documents) {
+    for (const dom of document.domNodes) {
+      const id = nodeByFrameBackend.get(frameBackendKey(document.frameId, dom.backendNodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || dom.parentBackendNodeId === null) continue;
+      node.domParentId = nodeByFrameBackend.get(
+        frameBackendKey(document.frameId, dom.parentBackendNodeId),
+      );
+    }
+    for (const ax of document.axNodes) {
+      const id = nodeByFrameAx.get(frameAxKey(document.frameId, ax.nodeId));
+      const node = id ? nodes.get(id) : undefined;
+      if (!node || !ax.parentId) continue;
+      node.axParentId = nodeByFrameAx.get(frameAxKey(document.frameId, ax.parentId));
+    }
+  }
+
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const excludedQueue: SemanticNodeId[] = [];
+  for (const node of nodes.values()) {
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    if (node.excluded) excludedQueue.push(node.id);
+  }
+  for (let index = 0; index < excludedQueue.length; index += 1) {
+    for (const childId of axChildren.get(excludedQueue[index]) ?? []) {
+      const child = nodes.get(childId);
+      if (!child || child.excluded) continue;
+      child.excluded = true;
+      excludedQueue.push(childId);
+    }
+  }
+
+  for (const frame of frames.values()) {
+    if (!frame.parentFrameId || frame.ownerBackendNodeId === undefined) continue;
+    frame.ownerNodeId = nodeByFrameBackend.get(
+      frameBackendKey(frame.parentFrameId, frame.ownerBackendNodeId),
+    );
+  }
+
+  return {
+    viewport: input.viewport,
+    rootFrameId,
+    frames,
+    nodes,
+    nodeIdsByFrame,
+    nodeByFrameBackend,
+  };
+}

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

@@ -0,0 +1,59 @@
+import type { Viewport, VomScene } from "@browser-skill/vom";
+import type { FrameDocument } from "../frame-document";
+import { buildSemanticGraph as buildGraph } from "./build";
+import { projectSemanticGraph as projectGraph } from "./project";
+import { resolveSemanticGraph as resolveGraph } from "./resolve";
+import { normalizeSemanticStructure as normalizeStructure } from "./structure";
+import type {
+  ResolvedSemanticGraph,
+  SemanticAxNode,
+  SemanticGraph,
+  StructuredSemanticGraph,
+} from "./types";
+
+export type { SemanticAxNode } from "./types";
+
+export interface SemanticVomInput {
+  documents: FrameDocument<SemanticAxNode>[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds?: ReadonlySet<number>;
+}
+
+export function buildSemanticGraph(input: SemanticVomInput): SemanticGraph {
+  return buildGraph(input);
+}
+
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
+  return resolveGraph(graph, options);
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  return normalizeStructure(graph);
+}
+
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
+  return projectGraph(graph);
+}
+
+export function buildSemanticVomScene(
+  input: SemanticVomInput & {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  },
+): VomScene {
+  return projectSemanticGraph(
+    normalizeSemanticStructure(
+      resolveSemanticGraph(buildSemanticGraph(input), {
+        supplementalNames: input.supplementalNames,
+        identifierFallback: input.identifierFallback,
+      }),
+    ),
+  );
+}

apps/extension/src/tools/vom/semantic-graph/name-evidence.ts

@@ -0,0 +1,34 @@
+const IDENTIFIER_ATTRS = ["data-testid", "data-test-id", "id"] as const;
+const GENERIC_TOKENS = new Set(["btn", "button", "control", "icon", "item", "test", "tool"]);
+const GENERATED_PREFIXES = new Set(["ember", "headlessui", "mui", "radix", "react", "rc"]);
+
+function identifierTokens(value: string): string[] {
+  return value
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .map((token) => token.toLowerCase())
+    .filter(Boolean);
+}
+
+function readableIdentifier(value: string | undefined): string | undefined {
+  const raw = value?.trim();
+  if (!raw || raw.length < 3 || raw.length > 80) return undefined;
+  if (/^[a-f0-9]{8,}$/i.test(raw)) return undefined;
+
+  const tokens = identifierTokens(raw);
+  if (GENERATED_PREFIXES.has(tokens[0])) return undefined;
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[0])) tokens.shift();
+  while (tokens.length > 1 && GENERIC_TOKENS.has(tokens[tokens.length - 1])) tokens.pop();
+  if (tokens.length === 0 || !tokens.some((token) => /[a-z]{3,}/.test(token))) return undefined;
+  return tokens
+    .map((token, index) => (index === 0 ? `${token[0].toUpperCase()}${token.slice(1)}` : token))
+    .join(" ");
+}
+
+export function stableIdentifierName(attrs: Readonly<Record<string, string>>): string | undefined {
+  for (const name of IDENTIFIER_ATTRS) {
+    const label = readableIdentifier(attrs[name]);
+    if (label) return label;
+  }
+  return undefined;
+}

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

@@ -0,0 +1,85 @@
+import type { VomNode, VomScene } from "@browser-skill/vom";
+import type { SemanticNodeId, StructuredSemanticGraph, StructuredSemanticNode } from "./types";
+
+function retained(node: StructuredSemanticNode): boolean {
+  return node.structure.kind === "keep" || node.structure.kind === "inferred-group";
+}
+
+function connectedFrameIds(graph: StructuredSemanticGraph): Set<string> {
+  const connected = new Set<string>([graph.rootFrameId]);
+  const childrenByParent = new Map<string, string[]>();
+  for (const frame of graph.frames.values()) {
+    if (!frame.parentFrameId) continue;
+    const children = childrenByParent.get(frame.parentFrameId) ?? [];
+    children.push(frame.frameId);
+    childrenByParent.set(frame.parentFrameId, children);
+  }
+  const queue = [graph.rootFrameId];
+  for (let index = 0; index < queue.length; index += 1) {
+    for (const frameId of childrenByParent.get(queue[index]) ?? []) {
+      if (connected.has(frameId)) continue;
+      const frame = graph.frames.get(frameId);
+      if (!frame?.ownerNodeId) continue;
+      const owner = graph.nodes.get(frame.ownerNodeId);
+      if (!owner || !retained(owner)) continue;
+      connected.add(frame.frameId);
+      queue.push(frame.frameId);
+    }
+  }
+  return connected;
+}
+
+function domAncestors(
+  graph: StructuredSemanticGraph,
+  node: StructuredSemanticNode,
+  numericId: ReadonlyMap<SemanticNodeId, number>,
+): number[] {
+  const ancestors: number[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let current = node.domParentId;
+  while (current && !seen.has(current)) {
+    seen.add(current);
+    const id = numericId.get(current);
+    if (id !== undefined) ancestors.push(id);
+    current = graph.nodes.get(current)?.domParentId;
+  }
+  return ancestors;
+}
+
+export function projectSemanticGraph(graph: StructuredSemanticGraph): VomScene {
+  const connectedFrames = connectedFrameIds(graph);
+  const orderedNodes = [...graph.frames.values()]
+    .filter((frame) => connectedFrames.has(frame.frameId))
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is StructuredSemanticNode => node !== undefined && retained(node))
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+
+  const numericId = new Map<SemanticNodeId, number>();
+  orderedNodes.forEach((node, index) => numericId.set(node.id, index + 1));
+  const nodes: VomNode[] = orderedNodes.map((node) => ({
+    ...node.vom,
+    id: numericId.get(node.id) as number,
+    parentId: node.semanticParentId ? (numericId.get(node.semanticParentId) ?? null) : null,
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+    ...(node.dom
+      ? {
+          domParentId:
+            node.domParentId === undefined ? null : (numericId.get(node.domParentId) ?? null),
+          domAncestorIds: domAncestors(graph, node, numericId),
+        }
+      : {}),
+  }));
+
+  return {
+    viewport: graph.viewport,
+    nodes,
+    rootFrameId: graph.rootFrameId,
+  };
+}

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

@@ -0,0 +1,521 @@
+import type { VomNode } from "@browser-skill/vom";
+import { stableIdentifierName } from "./name-evidence";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticAxNode,
+  SemanticGraph,
+  SemanticGraphNode,
+  SemanticNodeId,
+} from "./types";
+import { frameBackendKey } from "./types";
+
+const FORM_TAGS = new Set(["input", "textarea", "select"]);
+const NATIVE_CONTROL_TAGS = new Set(["button", "input", "select", "textarea"]);
+const TEXT_AX_ROLES = new Set(["statictext", "inlinetextbox", "labeltext", "text"]);
+const INTERACTIVE_ROLES = new Set([
+  "button",
+  "checkbox",
+  "combobox",
+  "link",
+  "listbox",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "option",
+  "radio",
+  "searchbox",
+  "slider",
+  "spinbutton",
+  "switch",
+  "tab",
+  "textbox",
+  "treeitem",
+]);
+const SENSITIVE_INPUT_TYPES = new Set([
+  "password",
+  "credit-card",
+  "one-time-code",
+  "current-password",
+  "new-password",
+]);
+
+function clean(value: string | undefined): string | undefined {
+  const normalized = value?.replace(/\s+/g, " ").trim();
+  return normalized || undefined;
+}
+
+function axValue(field?: { value?: string | number | boolean }): string | undefined {
+  return field?.value === undefined ? undefined : clean(String(field.value));
+}
+
+function axProperty(node: SemanticAxNode | undefined, name: string): string | undefined {
+  return axValue(node?.properties?.find((property) => property.name === name)?.value);
+}
+
+function normalizeRole(value: string | undefined): string | undefined {
+  const role = clean(value)?.toLowerCase();
+  return role || undefined;
+}
+
+function nativeRole(tag: string, attrs: Record<string, string>): string | undefined {
+  if (tag === "button") return "button";
+  if (tag === "textarea") return "textbox";
+  if (tag === "select") return attrs.multiple === undefined ? "combobox" : "listbox";
+  if (tag === "a" && attrs.href) return "link";
+  if (tag === "iframe") return "Iframe";
+  if (tag === "dialog") return "dialog";
+  if (tag === "img") return "img";
+  if (tag === "table") return "table";
+  if (tag === "tr") return "row";
+  if (tag === "th") return "columnheader";
+  if (tag === "td") return "cell";
+  if (tag === "ul" || tag === "ol") return "list";
+  if (tag === "li") return "listitem";
+  if (/^h[1-6]$/.test(tag)) return "heading";
+  if (tag === "nav") return "navigation";
+  if (tag === "main") return "main";
+  if (tag === "form") return "form";
+  if (tag === "input") {
+    const type = (attrs.type ?? "text").toLowerCase();
+    if (type === "hidden") return undefined;
+    if (type === "checkbox") return "checkbox";
+    if (type === "radio") return "radio";
+    if (type === "range") return "slider";
+    if (type === "number") return "spinbutton";
+    if (type === "search") return "searchbox";
+    if (["button", "submit", "reset", "image"].includes(type)) return "button";
+    return "textbox";
+  }
+  return undefined;
+}
+
+function domRole(tag: string, attrs: Record<string, string>): string | undefined {
+  return normalizeRole(attrs.role) ?? nativeRole(tag, attrs);
+}
+
+function resolvedRole(node: SemanticGraphNode): {
+  value?: string;
+  source: ResolvedSemanticNode["roleSource"];
+} {
+  const rawAxRole = clean(axValue(node.ax?.role));
+  const axRole = normalizeRole(rawAxRole);
+  const attrs = node.dom?.attrs ?? {};
+  const explicitDomRole = normalizeRole(attrs.role);
+  const nativeDomRole = nativeRole(node.dom?.tag.toLowerCase() ?? "", attrs);
+  const usableAxRole = node.ax?.ignored !== true;
+  if (usableAxRole && axRole && !["generic", "none", "presentation"].includes(axRole)) {
+    return { value: rawAxRole, source: "ax" };
+  }
+  if (explicitDomRole) return { value: explicitDomRole, source: "dom-explicit" };
+  if (nativeDomRole) return { value: nativeDomRole, source: "dom-native" };
+  if (rawAxRole) {
+    return { value: rawAxRole, source: usableAxRole ? "ax" : "ax-ignored" };
+  }
+  return { source: "none" };
+}
+
+function sensitive(node: SemanticGraphNode): boolean {
+  const attrs = node.dom?.attrs ?? {};
+  const type = (attrs.type ?? "").toLowerCase();
+  const autocomplete = (attrs.autocomplete ?? "").toLowerCase();
+  return (
+    type === "password" ||
+    autocomplete.startsWith("cc-") ||
+    SENSITIVE_INPUT_TYPES.has(autocomplete) ||
+    SENSITIVE_INPUT_TYPES.has(axProperty(node.ax, "inputType") ?? "")
+  );
+}
+
+function inputState(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  value: string | undefined,
+  isSensitive: boolean,
+): VomNode["inputState"] {
+  if (node.dom?.formState) return node.dom.formState;
+  const tag = node.dom?.tag.toLowerCase() ?? "";
+  if (!FORM_TAGS.has(tag) && !["textbox", "searchbox"].includes(role ?? "")) return undefined;
+  if (isSensitive) return value ? "filled" : "empty";
+  if (node.dom?.formValue !== undefined) {
+    if (node.dom.formValue === "") return "empty";
+    return node.dom.formValue === (node.dom.formDefaultValue ?? "") ? "default" : "filled";
+  }
+  return value ? "filled" : "empty";
+}
+
+function externalHrefHost(
+  href: string | undefined,
+  pageUrl: string | undefined,
+): string | undefined {
+  if (!href || !pageUrl) return undefined;
+  try {
+    const page = new URL(pageUrl);
+    const target = new URL(href, page);
+    return target.origin === page.origin ? undefined : target.hostname;
+  } catch {
+    return undefined;
+  }
+}
+
+interface ResolveIndexes {
+  domChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  axChildren: Map<SemanticNodeId, SemanticNodeId[]>;
+  domIdIndex: Map<string, SemanticNodeId>;
+  labelForIndex: Map<string, SemanticNodeId[]>;
+  domText: (nodeId: SemanticNodeId) => string | undefined;
+  axText: (nodeId: SemanticNodeId) => string | undefined;
+  hasNativeDescendant: (nodeId: SemanticNodeId) => boolean;
+}
+
+function buildIndexes(graph: SemanticGraph): ResolveIndexes {
+  const domChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const axChildren = new Map<SemanticNodeId, SemanticNodeId[]>();
+  const domIdIndex = new Map<string, SemanticNodeId>();
+  const labelForIndex = new Map<string, SemanticNodeId[]>();
+  for (const node of graph.nodes.values()) {
+    if (node.domParentId) {
+      const children = domChildren.get(node.domParentId) ?? [];
+      children.push(node.id);
+      domChildren.set(node.domParentId, children);
+    }
+    if (node.axParentId) {
+      const children = axChildren.get(node.axParentId) ?? [];
+      children.push(node.id);
+      axChildren.set(node.axParentId, children);
+    }
+    const id = clean(node.dom?.attrs.id);
+    if (id) domIdIndex.set(`${node.frameId}\u0000${id}`, node.id);
+    const targetId = clean(node.dom?.attrs.for);
+    if (node.dom?.tag.toLowerCase() === "label" && targetId) {
+      const key = `${node.frameId}\u0000${targetId}`;
+      const labels = labelForIndex.get(key) ?? [];
+      labels.push(node.id);
+      labelForIndex.set(key, labels);
+    }
+  }
+
+  for (const [parentId, children] of axChildren) {
+    const order = graph.nodes.get(parentId)?.ax?.childIds ?? [];
+    const orderByAxId = new Map(order.map((nodeId, index) => [nodeId, index]));
+    children.sort((a, b) => {
+      const aIndex = orderByAxId.get(graph.nodes.get(a)?.axNodeId ?? "") ?? -1;
+      const bIndex = orderByAxId.get(graph.nodes.get(b)?.axNodeId ?? "") ?? -1;
+      return (
+        (aIndex < 0 ? Number.MAX_SAFE_INTEGER : aIndex) -
+        (bIndex < 0 ? Number.MAX_SAFE_INTEGER : bIndex)
+      );
+    });
+  }
+
+  const textMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingText = new Set<SemanticNodeId>();
+  const domText = (nodeId: SemanticNodeId): string | undefined => {
+    if (textMemo.has(nodeId)) return textMemo.get(nodeId);
+    if (resolvingText.has(nodeId)) return undefined;
+    resolvingText.add(nodeId);
+    const node = graph.nodes.get(nodeId);
+    const parts: string[] = [];
+    const own = clean(node?.dom?.textContent);
+    if (own) parts.push(own);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = child
+        ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {})
+        : undefined;
+      if (childRole && INTERACTIVE_ROLES.has(childRole.toLowerCase())) continue;
+      const childText = domText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    resolvingText.delete(nodeId);
+    const result = clean(parts.join(" ").slice(0, 240));
+    textMemo.set(nodeId, result);
+    return result;
+  };
+
+  const axTextMemo = new Map<SemanticNodeId, string | undefined>();
+  const resolvingAxText = new Set<SemanticNodeId>();
+  const axText = (nodeId: SemanticNodeId): string | undefined => {
+    if (axTextMemo.has(nodeId)) return axTextMemo.get(nodeId);
+    if (resolvingAxText.has(nodeId)) return undefined;
+    resolvingAxText.add(nodeId);
+    const complete = (value: string | undefined): string | undefined => {
+      resolvingAxText.delete(nodeId);
+      axTextMemo.set(nodeId, value);
+      return value;
+    };
+    const node = graph.nodes.get(nodeId);
+    const role = normalizeRole(axValue(node?.ax?.role)) ?? "";
+    if (TEXT_AX_ROLES.has(role)) {
+      const own = clean(axValue(node?.ax?.name) ?? axValue(node?.ax?.value));
+      if (own) return complete(own);
+    }
+    const parts: string[] = [];
+    for (const childId of axChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole = normalizeRole(axValue(child?.ax?.role)) ?? "";
+      if (INTERACTIVE_ROLES.has(childRole)) continue;
+      const childText = axText(childId);
+      if (childText) parts.push(childText);
+      if (parts.join(" ").length >= 240) break;
+    }
+    return complete(clean(parts.join(" ").slice(0, 240)));
+  };
+
+  const nativeMemo = new Map<SemanticNodeId, boolean>();
+  const hasNativeDescendant = (nodeId: SemanticNodeId): boolean => {
+    const cached = nativeMemo.get(nodeId);
+    if (cached !== undefined) return cached;
+    nativeMemo.set(nodeId, false);
+    for (const childId of domChildren.get(nodeId) ?? []) {
+      const child = graph.nodes.get(childId);
+      const childRole =
+        (child?.ax?.ignored === true ? undefined : normalizeRole(axValue(child?.ax?.role))) ??
+        (child ? domRole(child.dom?.tag.toLowerCase() ?? "", child.dom?.attrs ?? {}) : undefined);
+      if (
+        (child?.dom && NATIVE_CONTROL_TAGS.has(child.dom.tag.toLowerCase())) ||
+        INTERACTIVE_ROLES.has(childRole ?? "") ||
+        hasNativeDescendant(childId)
+      ) {
+        nativeMemo.set(nodeId, true);
+        return true;
+      }
+    }
+    return false;
+  };
+
+  return {
+    domChildren,
+    axChildren,
+    domIdIndex,
+    labelForIndex,
+    domText,
+    axText,
+    hasNativeDescendant,
+  };
+}
+
+function ariaLabelledText(node: SemanticGraphNode, indexes: ResolveIndexes): string | undefined {
+  const ids = (node.dom?.attrs["aria-labelledby"] ?? "").split(/\s+/).filter(Boolean);
+  const parts = ids.flatMap((id) => {
+    const target = indexes.domIdIndex.get(`${node.frameId}\u0000${id}`);
+    return target ? (indexes.domText(target) ?? []) : [];
+  });
+  return clean(parts.join(" "));
+}
+
+function nativeLabelText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  const id = clean(node.dom?.attrs.id);
+  if (id) {
+    const labels = indexes.labelForIndex.get(`${node.frameId}\u0000${id}`) ?? [];
+    const explicit = clean(
+      labels
+        .map((labelId) => indexes.domText(labelId))
+        .filter(Boolean)
+        .join(" "),
+    );
+    if (explicit) return explicit;
+  }
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom?.tag.toLowerCase() === "label") return indexes.domText(parentId);
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return undefined;
+}
+
+function precedingAxText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.axParentId) return undefined;
+  const siblings = indexes.axChildren.get(node.axParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const role = normalizeRole(axValue(sibling?.ax?.role)) ?? "";
+    if (INTERACTIVE_ROLES.has(role)) break;
+    if (!TEXT_AX_ROLES.has(role) && role !== "generic") continue;
+    const text = clean(axValue(sibling?.ax?.name) ?? axValue(sibling?.ax?.value))?.replace(
+      /[：:]\s*$/,
+      "",
+    );
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function precedingDomText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  for (let offset = 1; offset <= 4 && index - offset >= 0; offset += 1) {
+    const sibling = graph.nodes.get(siblings[index - offset]);
+    const siblingRole = sibling
+      ? domRole(sibling.dom?.tag.toLowerCase() ?? "", sibling.dom?.attrs ?? {})
+      : undefined;
+    if (siblingRole && INTERACTIVE_ROLES.has(siblingRole.toLowerCase())) break;
+    const text = indexes.domText(siblings[index - offset])?.replace(/[：:]\s*$/, "");
+    if (text && text.length <= 80) return text;
+  }
+  return undefined;
+}
+
+function resolvedName(
+  node: SemanticGraphNode,
+  role: string | undefined,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+  supplementalNames: ReadonlyMap<string, string>,
+  identifierFallback: boolean,
+): string | undefined {
+  const attrs = node.dom?.attrs ?? {};
+  const formControl = FORM_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
+  const descendantText = indexes.domText(node.id);
+  const interactive =
+    INTERACTIVE_ROLES.has(role?.toLowerCase() ?? "") ||
+    NATIVE_CONTROL_TAGS.has(node.dom?.tag.toLowerCase() ?? "");
+  const candidates = [
+    node.ax?.ignored === true ? undefined : axValue(node.ax?.name),
+    ariaLabelledText(node, indexes),
+    clean(attrs["aria-label"]),
+    nativeLabelText(node, graph, indexes),
+    clean(attrs.title),
+    clean(attrs.alt),
+    node.ax?.ignored === true ? undefined : indexes.axText(node.id),
+    descendantText,
+    formControl ? precedingAxText(node, graph, indexes) : undefined,
+    formControl ? precedingDomText(node, graph, indexes) : undefined,
+    formControl ? clean(node.dom?.formPlaceholder ?? attrs.placeholder) : undefined,
+    formControl || !interactive || node.backendNodeId === undefined
+      ? undefined
+      : clean(supplementalNames.get(frameBackendKey(node.frameId, node.backendNodeId))),
+    identifierFallback && interactive ? stableIdentifierName(attrs) : undefined,
+  ];
+  let name = candidates.find((candidate) => candidate !== undefined);
+  const hasPopup = axProperty(node.ax, "hasPopup");
+  if (name && hasPopup && hasPopup !== "false") {
+    name =
+      axProperty(node.ax, "expanded") === "true" ? `${name} [expanded]` : `${name} [has-submenu]`;
+  }
+  if (!name && role?.toLowerCase() === "iframe") return clean(attrs.id);
+  return name;
+}
+
+function insideNative(node: SemanticGraphNode, graph: SemanticGraph): boolean {
+  let parentId = node.domParentId;
+  let guard = 0;
+  while (parentId && guard <= graph.nodes.size) {
+    const parent = graph.nodes.get(parentId);
+    if (!parent) break;
+    if (parent.dom && NATIVE_CONTROL_TAGS.has(parent.dom.tag.toLowerCase())) return true;
+    parentId = parent.domParentId;
+    guard += 1;
+  }
+  return false;
+}
+
+function nearbyText(
+  node: SemanticGraphNode,
+  graph: SemanticGraph,
+  indexes: ResolveIndexes,
+): string | undefined {
+  if (!node.domParentId) return undefined;
+  const siblings = indexes.domChildren.get(node.domParentId) ?? [];
+  const index = siblings.indexOf(node.id);
+  if (index < 0) return undefined;
+  const texts = siblings
+    .slice(Math.max(0, index - 3), index + 4)
+    .filter((id) => id !== node.id)
+    .flatMap((id) => indexes.domText(id) ?? [])
+    .slice(0, 3);
+  return clean(texts.join(" "));
+}
+
+export function resolveSemanticGraph(
+  graph: SemanticGraph,
+  options: {
+    supplementalNames?: ReadonlyMap<string, string>;
+    identifierFallback?: boolean;
+  } = {},
+): ResolvedSemanticGraph {
+  const indexes = buildIndexes(graph);
+  const supplementalNames = options.supplementalNames ?? new Map<string, string>();
+  const identifierFallback = options.identifierFallback ?? true;
+  const nodes = new Map<SemanticNodeId, ResolvedSemanticNode>();
+  for (const node of graph.nodes.values()) {
+    const roleResolution = resolvedRole(node);
+    const role = roleResolution.value;
+    const name = resolvedName(node, role, graph, indexes, supplementalNames, identifierFallback);
+    const isSensitive = sensitive(node);
+    const sourceValue = node.dom?.formValue ?? axValue(node.ax?.value);
+    const value = isSensitive ? undefined : sourceValue;
+    const attrs = { ...(node.dom?.attrs ?? {}) };
+    if (isSensitive) delete attrs.value;
+    const frame = graph.frames.get(node.frameId);
+    const tag = node.dom?.tag.toLowerCase() ?? "";
+    const vom: ResolvedSemanticNode["vom"] = {
+      tag,
+      rect: node.dom?.rect ?? null,
+      paintOrder: node.dom?.paintOrder ?? 0,
+      position: node.dom?.position || "static",
+      pointerEvents: node.dom?.pointerEvents || "auto",
+      ...(node.dom?.cursor ? { cursor: node.dom.cursor } : {}),
+      ...(role ? { role } : {}),
+      ...(name ? { name } : {}),
+      ...(value !== undefined ? { value } : {}),
+      ...(clean(node.dom?.formPlaceholder ?? attrs.placeholder)
+        ? { placeholder: clean(node.dom?.formPlaceholder ?? attrs.placeholder) }
+        : {}),
+      attrs,
+      ...(clean(node.dom?.textContent) ? { text: clean(node.dom?.textContent) } : {}),
+      ...(nearbyText(node, graph, indexes) ? { nearbyText: nearbyText(node, graph, indexes) } : {}),
+      inputState: inputState(node, role, sourceValue, isSensitive),
+      sensitive: isSensitive,
+      modal:
+        ["dialog", "alertdialog"].includes(role?.toLowerCase() ?? "") ||
+        tag === "dialog" ||
+        (attrs["aria-modal"] ?? "").toLowerCase() === "true",
+      disabled:
+        Object.prototype.hasOwnProperty.call(attrs, "disabled") ||
+        (attrs["aria-disabled"] ?? "").toLowerCase() === "true",
+      inert: Object.prototype.hasOwnProperty.call(attrs, "inert"),
+      hasNativeDescendant: indexes.hasNativeDescendant(node.id),
+      insideNative: insideNative(node, graph),
+      ...(role?.toLowerCase() === "link" ? { href: externalHrefHost(attrs.href, frame?.url) } : {}),
+    };
+    const selected = node.ax?.ignored === true ? undefined : axProperty(node.ax, "selected");
+    const expanded = node.ax?.ignored === true ? undefined : axProperty(node.ax, "expanded");
+    const controls = node.ax?.ignored === true ? undefined : axProperty(node.ax, "controls");
+    if (selected === "true" && !vom.attrs?.["aria-selected"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-selected": "true" };
+    }
+    if (expanded === "true" && !vom.attrs?.["aria-expanded"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-expanded": "true" };
+    }
+    if (controls && !vom.attrs?.["aria-controls"]) {
+      vom.attrs = { ...(vom.attrs ?? {}), "aria-controls": controls };
+    }
+    nodes.set(node.id, {
+      ...node,
+      vom,
+      referenceable: node.backendNodeId !== undefined,
+      roleSource: roleResolution.source,
+    });
+  }
+  return { ...graph, nodes };
+}

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

@@ -0,0 +1,456 @@
+import {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  isVomStructuralRole,
+  type VomNode,
+} from "@browser-skill/vom";
+import type {
+  ResolvedSemanticGraph,
+  ResolvedSemanticNode,
+  SemanticNodeId,
+  StructureDecision,
+  StructuredSemanticGraph,
+  StructuredSemanticNode,
+} from "./types";
+
+const TRANSPARENT_ROLES = new Set(["", "generic", "none", "presentation", "inlinetextbox"]);
+const ROOT_ROLES = new Set(["rootwebarea", "webarea"]);
+const CONTENT_BOUNDARY_ROLES = new Set([
+  "article",
+  "dialog",
+  "document",
+  "feed",
+  "form",
+  "grid",
+  "heading",
+  "iframe",
+  "list",
+  "main",
+  "navigation",
+  "paragraph",
+  "region",
+  "section",
+  "table",
+  "tree",
+]);
+
+function hasMeaningfulRelations(node: ResolvedSemanticNode): boolean {
+  const attrs = node.vom.attrs ?? {};
+  return ["aria-controls", "aria-labelledby", "aria-owns", "aria-describedby"].some((name) =>
+    attrs[name]?.trim(),
+  );
+}
+
+function explicitStructural(node: ResolvedSemanticNode): boolean {
+  return (
+    isVomStructuralRole(node.vom.role) &&
+    node.roleSource !== "none" &&
+    node.roleSource !== "ax-ignored"
+  );
+}
+
+function hasUsableAxSemantics(node: ResolvedSemanticNode): boolean {
+  return node.ax !== undefined && node.ax.ignored !== true;
+}
+
+function isRenderedDomFallback(node: ResolvedSemanticNode): boolean {
+  if (!node.dom) return false;
+  const attrs = node.dom.attrs;
+  if (
+    Object.prototype.hasOwnProperty.call(attrs, "hidden") ||
+    Object.prototype.hasOwnProperty.call(attrs, "inert") ||
+    (attrs["aria-hidden"] ?? "").toLowerCase() === "true"
+  ) {
+    return false;
+  }
+  return node.dom.rendered ?? (node.dom.localRect != null || node.dom.rect != null);
+}
+
+function initialParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+): SemanticNodeId | undefined {
+  let parentId = node.axParentId ?? node.domParentId;
+  if (node.axParentId && node.domParentId && node.axParentId !== node.domParentId) {
+    const axParent = graph.nodes.get(node.axParentId);
+    const axRole = axParent?.vom.role?.toLowerCase() ?? "";
+    const meaningfulAxParent =
+      axParent !== undefined &&
+      !ROOT_ROLES.has(axRole) &&
+      (explicitStructural(axParent) ||
+        !TRANSPARENT_ROLES.has(axRole) ||
+        Boolean(axParent.vom.name || axParent.vom.text || hasMeaningfulRelations(axParent)));
+    parentId = meaningfulAxParent ? node.axParentId : node.domParentId;
+  }
+  if (parentId) return parentId;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function orderedNodes(graph: ResolvedSemanticGraph): ResolvedSemanticNode[] {
+  return [...graph.frames.values()]
+    .sort((a, b) => a.order - b.order)
+    .flatMap((frame) =>
+      (graph.nodeIdsByFrame.get(frame.frameId) ?? [])
+        .map((id) => graph.nodes.get(id))
+        .filter((node): node is ResolvedSemanticNode => node !== undefined)
+        .sort((a, b) => a.sourceOrder - b.sourceOrder),
+    );
+}
+
+function recoveredNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+): Map<SemanticNodeId, VomNode> {
+  const numericId = new Map(nodes.map((node, index) => [node.id, index + 1]));
+  const semanticId = new Map([...numericId].map(([id, numeric]) => [numeric, id]));
+  const provisional = nodes.map((node) => ({
+    ...node.vom,
+    id: numericId.get(node.id) as number,
+    parentId: (() => {
+      const parent = initialParentId(graph, node);
+      return parent ? (numericId.get(parent) ?? null) : null;
+    })(),
+    ...(node.backendNodeId !== undefined ? { backendNodeId: node.backendNodeId } : {}),
+    frameId: node.frameId,
+    contextScopeId: graph.frames.get(node.frameId)?.contextScopeId ?? node.frameId,
+    referenceable: node.referenceable,
+  }));
+  return new Map(
+    applyVomInteractionRecovery(provisional).flatMap((node) => {
+      const id = semanticId.get(node.id);
+      return id ? [[id, node] as const] : [];
+    }),
+  );
+}
+
+function redundantSourceNodes(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+): Set<SemanticNodeId> {
+  const byKey = new Map<string, ResolvedSemanticNode[]>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const name = output.name?.trim().toLowerCase() ?? "";
+    if (!name || !isVomReferenceNode({ ...output, referenceable: true })) continue;
+    const key = `${node.frameId}\u0000${initialParentId(graph, node) ?? ""}\u0000${output.role?.toLowerCase() ?? ""}\u0000${name}\u0000${output.sensitive === true}`;
+    const matches = byKey.get(key) ?? [];
+    matches.push(node);
+    byKey.set(key, matches);
+  }
+  const redundant = new Set<SemanticNodeId>();
+  for (const matches of byKey.values()) {
+    const axOnly = matches.filter((node) => node.ax && !node.dom);
+    const domOnly = matches.filter((node) => node.dom && !node.ax);
+    if (matches.length === 2 && axOnly.length === 1 && domOnly.length === 1) {
+      redundant.add(domOnly[0].id);
+    }
+  }
+  return redundant;
+}
+
+function baseDecision(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  output: VomNode,
+  frameOwnerIds: ReadonlySet<SemanticNodeId>,
+  redundant: ReadonlySet<SemanticNodeId>,
+): StructureDecision {
+  if (node.excluded) return { kind: "excluded", reason: "excluded" };
+  if (redundant.has(node.id)) return { kind: "excluded", reason: "redundant-source" };
+  if (!hasUsableAxSemantics(node) && !isRenderedDomFallback(node)) {
+    return { kind: "excluded", reason: "non-rendered-dom-fallback" };
+  }
+  if (frameOwnerIds.has(node.id)) return { kind: "keep", reason: "frame-owner" };
+  if (node.frameId !== graph.rootFrameId && ROOT_ROLES.has(output.role?.toLowerCase() ?? "")) {
+    return { kind: "transparent", reason: "child-document-root" };
+  }
+  if (node.ax?.ignored === true && !node.dom) {
+    return { kind: "transparent", reason: "ax-ignored" };
+  }
+  const role = output.role?.toLowerCase() ?? "";
+  if (!TRANSPARENT_ROLES.has(role)) return { kind: "keep", reason: "semantic" };
+  if (
+    output.name ||
+    output.text ||
+    output.value ||
+    output.placeholder ||
+    hasMeaningfulRelations(node) ||
+    (output.rect && ["fixed", "sticky"].includes(output.position))
+  ) {
+    return { kind: "keep", reason: "semantic" };
+  }
+  return { kind: "transparent", reason: "wrapper" };
+}
+
+function buildChildren(
+  nodes: ResolvedSemanticNode[],
+  relation: "axParentId" | "domParentId",
+): Map<SemanticNodeId, SemanticNodeId[]> {
+  const children = new Map<SemanticNodeId, SemanticNodeId[]>();
+  for (const node of nodes) {
+    const parentId = node[relation];
+    if (!parentId) continue;
+    const siblings = children.get(parentId) ?? [];
+    siblings.push(node.id);
+    children.set(parentId, siblings);
+  }
+  return children;
+}
+
+function explicitDomAncestors(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const inside = new Set<SemanticNodeId>();
+  const roots = nodes.filter((node) => !node.domParentId);
+  const queue = roots.map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const parentId = queue[index];
+    const parent = graph.nodes.get(parentId);
+    const parentIsBoundary =
+      parent !== undefined &&
+      explicitStructural(parent) &&
+      !ROOT_ROLES.has(parent.vom.role?.toLowerCase() ?? "");
+    for (const childId of domChildren.get(parentId) ?? []) {
+      if (inside.has(parentId) || parentIsBoundary) inside.add(childId);
+      queue.push(childId);
+    }
+  }
+  return inside;
+}
+
+function reliableGroupCandidates(
+  graph: ResolvedSemanticGraph,
+  nodes: ResolvedSemanticNode[],
+  recovered: ReadonlyMap<SemanticNodeId, VomNode>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const insideExplicitStructure = explicitDomAncestors(graph, nodes, domChildren);
+  const remainingChildren = new Map(
+    nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]),
+  );
+  const summaries = new Map<SemanticNodeId, { blocked: boolean; interactions: number }>();
+  const queue = nodes
+    .filter((node) => (remainingChildren.get(node.id) ?? 0) === 0)
+    .map((node) => node.id);
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    const node = graph.nodes.get(nodeId);
+    const output = recovered.get(nodeId);
+    if (!node || !output) continue;
+    const role = output.role?.toLowerCase() ?? "";
+    const excluded = decisions.get(nodeId)?.kind === "excluded";
+    const blocked = excluded || explicitStructural(node) || CONTENT_BOUNDARY_ROLES.has(role);
+    const summary = excluded
+      ? { blocked: true, interactions: 0 }
+      : isVomReferenceNode(output)
+        ? { blocked: false, interactions: 1 }
+        : blocked
+          ? { blocked: true, interactions: 0 }
+          : (domChildren.get(nodeId) ?? []).reduce(
+              (combined, childId) => {
+                const child = summaries.get(childId);
+                return {
+                  blocked: combined.blocked || !child || child.blocked,
+                  interactions: Math.min(2, combined.interactions + (child?.interactions ?? 0)),
+                };
+              },
+              { blocked: false, interactions: 0 },
+            );
+    summaries.set(nodeId, summary);
+    const parentId = node.domParentId;
+    if (!parentId) continue;
+    const remaining = (remainingChildren.get(parentId) ?? 1) - 1;
+    remainingChildren.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+
+  const candidates = new Set<SemanticNodeId>();
+  for (const node of nodes) {
+    const output = recovered.get(node.id) as VomNode;
+    const role = output.role?.toLowerCase() ?? "";
+    if (
+      !node.dom ||
+      node.dom.tag.toLowerCase() !== "div" ||
+      !TRANSPARENT_ROLES.has(role) ||
+      insideExplicitStructure.has(node.id) ||
+      decisions.get(node.id)?.kind === "excluded" ||
+      node.dom.attrs.hidden !== undefined ||
+      (node.dom.attrs["aria-hidden"] ?? "").toLowerCase() === "true" ||
+      node.dom.attrs.inert !== undefined
+    ) {
+      continue;
+    }
+
+    const branches = (domChildren.get(node.id) ?? []).map((id) => summaries.get(id));
+    const blocked = branches.some((summary) => !summary || summary.blocked);
+    const contributingBranches = branches.filter(
+      (summary) => (summary?.interactions ?? 0) > 0,
+    ).length;
+    const interactions = branches.reduce(
+      (count, summary) => Math.min(2, count + (summary?.interactions ?? 0)),
+      0,
+    );
+    if (!blocked && contributingBranches >= 2 && interactions >= 2) {
+      candidates.add(node.id);
+    }
+  }
+  return candidates;
+}
+
+function leafCandidates(
+  nodes: ResolvedSemanticNode[],
+  candidates: ReadonlySet<SemanticNodeId>,
+  domChildren: ReadonlyMap<SemanticNodeId, SemanticNodeId[]>,
+): Set<SemanticNodeId> {
+  const parentById = new Map(
+    nodes.flatMap((node) => (node.domParentId ? ([[node.id, node.domParentId]] as const) : [])),
+  );
+  const childCount = new Map(nodes.map((node) => [node.id, domChildren.get(node.id)?.length ?? 0]));
+  const containsCandidate = new Set<SemanticNodeId>();
+  const queue = nodes.filter((node) => (childCount.get(node.id) ?? 0) === 0).map((node) => node.id);
+  const selected = new Set<SemanticNodeId>();
+  for (let index = 0; index < queue.length; index += 1) {
+    const nodeId = queue[index];
+    if (candidates.has(nodeId) && !containsCandidate.has(nodeId)) selected.add(nodeId);
+    const parentId = parentById.get(nodeId);
+    if (!parentId) continue;
+    if (candidates.has(nodeId) || containsCandidate.has(nodeId)) containsCandidate.add(parentId);
+    const remaining = (childCount.get(parentId) ?? 1) - 1;
+    childCount.set(parentId, remaining);
+    if (remaining === 0) queue.push(parentId);
+  }
+  return selected;
+}
+
+function nearestKept(
+  graph: ResolvedSemanticGraph,
+  startId: SemanticNodeId | undefined,
+  relation: "axParentId" | "domParentId",
+  kept: ReadonlySet<SemanticNodeId>,
+  memo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  let currentId = startId;
+  const path: SemanticNodeId[] = [];
+  const seen = new Set<SemanticNodeId>();
+  let result: SemanticNodeId | undefined;
+  while (currentId && !seen.has(currentId)) {
+    if (kept.has(currentId)) {
+      result = currentId;
+      break;
+    }
+    if (memo.has(currentId)) {
+      result = memo.get(currentId);
+      break;
+    }
+    seen.add(currentId);
+    path.push(currentId);
+    currentId = graph.nodes.get(currentId)?.[relation];
+  }
+  for (const id of path) memo.set(id, result);
+  return result;
+}
+
+function finalParentId(
+  graph: ResolvedSemanticGraph,
+  node: ResolvedSemanticNode,
+  kept: ReadonlySet<SemanticNodeId>,
+  decisions: ReadonlyMap<SemanticNodeId, StructureDecision>,
+  axParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+  domParentMemo: Map<SemanticNodeId, SemanticNodeId | undefined>,
+): SemanticNodeId | undefined {
+  const axParent = nearestKept(graph, node.axParentId, "axParentId", kept, axParentMemo);
+  const domParent = nearestKept(graph, node.domParentId, "domParentId", kept, domParentMemo);
+  const axNode = axParent ? graph.nodes.get(axParent) : undefined;
+  const domNode = domParent ? graph.nodes.get(domParent) : undefined;
+  const axIsRoot = ROOT_ROLES.has(axNode?.vom.role?.toLowerCase() ?? "");
+  const axIsExplicit = axNode ? explicitStructural(axNode) && !axIsRoot : false;
+  const domIsStructural =
+    domNode !== undefined &&
+    (explicitStructural(domNode) || decisions.get(domNode.id)?.kind === "inferred-group");
+  if (axIsExplicit) return axParent;
+  if (domIsStructural) return domParent;
+  if (axParent && !axIsRoot) return axParent;
+  if (domParent) return domParent;
+  if (axParent) return axParent;
+  if (node.frameId === graph.rootFrameId) return undefined;
+  return graph.frames.get(node.frameId)?.ownerNodeId;
+}
+
+function recoveredVom(node: VomNode, inferredGroup: boolean): ResolvedSemanticNode["vom"] {
+  const {
+    id: _id,
+    parentId: _parentId,
+    backendNodeId: _backendNodeId,
+    frameId: _frameId,
+    contextScopeId: _contextScopeId,
+    referenceable: _referenceable,
+    ...vom
+  } = node;
+  if (!inferredGroup) return vom;
+  const { name: _name, text: _text, nearbyText: _nearbyText, ...groupVom } = vom;
+  return { ...groupVom, role: "group" };
+}
+
+export function normalizeSemanticStructure(graph: ResolvedSemanticGraph): StructuredSemanticGraph {
+  const nodes = orderedNodes(graph);
+  const recovered = recoveredNodes(graph, nodes);
+  const redundant = redundantSourceNodes(graph, nodes, recovered);
+  const frameOwnerIds = new Set(
+    [...graph.frames.values()].flatMap((frame) => frame.ownerNodeId ?? []),
+  );
+  const decisions = new Map<SemanticNodeId, StructureDecision>();
+  for (const node of nodes) {
+    decisions.set(
+      node.id,
+      baseDecision(graph, node, recovered.get(node.id) as VomNode, frameOwnerIds, redundant),
+    );
+  }
+
+  const domChildren = buildChildren(nodes, "domParentId");
+  const candidates = reliableGroupCandidates(graph, nodes, recovered, decisions, domChildren);
+  for (const nodeId of leafCandidates(nodes, candidates, domChildren)) {
+    decisions.set(nodeId, {
+      kind: "inferred-group",
+      reason: "independent-interaction-branches",
+    });
+  }
+
+  const kept = new Set(
+    nodes
+      .filter((node) => {
+        const kind = decisions.get(node.id)?.kind;
+        return kind === "keep" || kind === "inferred-group";
+      })
+      .map((node) => node.id),
+  );
+  const axParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const domParentMemo = new Map<SemanticNodeId, SemanticNodeId | undefined>();
+  const structuredNodes = new Map<SemanticNodeId, StructuredSemanticNode>();
+  for (const node of nodes) {
+    const structure = decisions.get(node.id) as StructureDecision;
+    const inferredGroup = structure.kind === "inferred-group";
+    structuredNodes.set(node.id, {
+      ...node,
+      vom: recoveredVom(recovered.get(node.id) as VomNode, inferredGroup),
+      structure,
+      ...(kept.has(node.id)
+        ? {
+            semanticParentId: finalParentId(
+              graph,
+              node,
+              kept,
+              decisions,
+              axParentMemo,
+              domParentMemo,
+            ),
+          }
+        : {}),
+    });
+  }
+  return { ...graph, nodes: structuredNodes };
+}

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

@@ -0,0 +1,88 @@
+import type { Viewport, VomNode } from "@browser-skill/vom";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { CapturedNode } from "../capture";
+
+export interface SemanticAxNode {
+  nodeId: string;
+  frameId?: string;
+  parentId?: string;
+  backendDOMNodeId?: number;
+  ignored?: boolean;
+  role?: { type: string; value?: string };
+  name?: { type: string; value?: string };
+  description?: { value?: string };
+  value?: { value?: string | number | boolean };
+  properties?: Array<{ name?: string; value?: { value?: string | number | boolean } }>;
+  childIds?: string[];
+}
+
+export type SemanticNodeId = string;
+
+export interface SemanticFrame {
+  frameId: string;
+  parentFrameId?: string;
+  ownerBackendNodeId?: number;
+  ownerNodeId?: SemanticNodeId;
+  contextScopeId: string;
+  target: CdpTarget;
+  url?: string;
+  order: number;
+}
+
+export interface SemanticGraphNode {
+  id: SemanticNodeId;
+  frameId: string;
+  backendNodeId?: number;
+  axNodeId?: string;
+  ax?: SemanticAxNode;
+  dom?: CapturedNode;
+  axParentId?: SemanticNodeId;
+  domParentId?: SemanticNodeId;
+  sourceOrder: number;
+  excluded: boolean;
+}
+
+export interface SemanticGraph {
+  viewport: Viewport;
+  rootFrameId: string;
+  frames: Map<string, SemanticFrame>;
+  nodes: Map<SemanticNodeId, SemanticGraphNode>;
+  nodeIdsByFrame: Map<string, SemanticNodeId[]>;
+  nodeByFrameBackend: Map<string, SemanticNodeId>;
+}
+
+export interface ResolvedSemanticNode extends SemanticGraphNode {
+  vom: Omit<VomNode, "id" | "parentId" | "backendNodeId" | "frameId" | "contextScopeId">;
+  referenceable: boolean;
+  roleSource: "ax" | "ax-ignored" | "dom-explicit" | "dom-native" | "none";
+}
+
+export interface ResolvedSemanticGraph extends Omit<SemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, ResolvedSemanticNode>;
+}
+
+export type StructureDecision =
+  | { kind: "keep"; reason: "semantic" | "frame-owner" }
+  | { kind: "inferred-group"; reason: "independent-interaction-branches" }
+  | { kind: "transparent"; reason: "wrapper" | "child-document-root" | "ax-ignored" }
+  | {
+      kind: "excluded";
+      reason: "excluded" | "redundant-source" | "non-rendered-dom-fallback";
+    };
+
+export interface StructuredSemanticNode extends ResolvedSemanticNode {
+  structure: StructureDecision;
+  semanticParentId?: SemanticNodeId;
+}
+
+export interface StructuredSemanticGraph extends Omit<ResolvedSemanticGraph, "nodes"> {
+  nodes: Map<SemanticNodeId, StructuredSemanticNode>;
+}
+
+export function frameBackendKey(frameId: string, backendNodeId: number): string {
+  return `${frameId}\u0000${backendNodeId}`;
+}
+
+export function frameAxKey(frameId: string, axNodeId: string): string {
+  return `${frameId}\u0000${axNodeId}`;
+}

apps/extension/src/transport/types.ts

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

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

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

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; ...]`, the ref identifies a rendered canvas surface, not an interactable DOM control. Use `bsk screenshot --ref @eN --session <id>` to inspect its visible crop. 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/render_error.rs

@@ -40,6 +40,7 @@ use bsk_protocol::ErrorCode;
 pub mod reason {
     pub const AGENT_WINDOW_SCOPE: &str = "agent_window_scope";
     pub const ELEMENT_NOT_VISIBLE: &str = "element_not_visible";
+    pub const REF_CAPABILITY_DENIED: &str = "ref_capability_denied";
     pub const REF_NOT_FOUND: &str = "ref_not_found";
     pub const SELECTOR_NOT_FOUND: &str = "selector_not_found";
     pub const TARGET_NOT_FILLABLE: &str = "target_not_fillable";
@@ -228,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; run `bsk screenshot --ref <ref> --session <id>`",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::InvalidParams, reason::TARGET_NOT_SELECT) => RenderInfo {
             summary: "target element is not a <select>",
             hint: Some(
@@ -377,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 });

packages/dsh-plugin-browserskill/README.md

@@ -20,43 +20,22 @@ extension keep owning the actual browser control — this package is a thin, wel
 | `browser_snapshot` | `bsk snapshot` | Indented aria-tree snapshot with `@eN` refs for interaction tools. |
 | `browser_observe` | `bsk observe` | Semantic VOM observation (read-only) with `@eN` refs. |
 | `browser_click` | `bsk click` | Click a snapshot ref or CSS selector (button / click-count options). |
-| `browser_hover` | `bsk hover` | Hover a ref or selector and allow hover-triggered UI to settle. |
 | `browser_fill` | `bsk fill` | Fill an input / textarea / contenteditable (clears first by default). |
-| `browser_select` | `bsk select` | Select one or more option values on a `<select>`. |
 | `browser_press` | `bsk press` | Dispatch a key or combo, optionally focusing a target first. |
 | `browser_screenshot` | `bsk screenshot` | PNG capture of the tab or a ref-cropped element; inlines the image when the deployment supports image input, otherwise returns a file path. |
 | `browser_emulate` | `bsk emulate` | Apply or clear mobile device emulation on the active tab. |
-| `browser_tab_list` | `bsk tab list` | List user and/or Agent Window tabs visible to an owned session. |
-| `browser_tab_create` | `bsk tab create` | Create a foreground or background tab in the Agent Window. |
-| `browser_tab_select` | `bsk tab select` | Focus an Agent Window tab. |
-| `browser_tab_close` | `bsk tab close` | Close an Agent Window tab. |
-| `browser_tab_borrow` | `bsk tab borrow` | Move a user tab into the Agent Window for controlled interaction. |
-| `browser_tab_return` | `bsk tab return` | Return a borrowed tab to its original user window. |
-| `browser_navigate_back` / `browser_navigate_forward` | `bsk navigate-back` / `bsk navigate-forward` | Traverse tab history and wait for a lifecycle phase. |
-| `browser_reload` | `bsk reload` | Reload the active tab, optionally bypassing cache. |
-| `browser_wait_for_navigation` | `bsk wait-for-navigation` | Wait explicitly for a page lifecycle event. |
-| `browser_request_help` | `bsk request-help` | Pause for login, captcha, OTP, confirmation, or another human browser step. |
-| `browser_get_html` | `bsk get-html` | Read raw document or ref-scoped HTML after semantic observation is insufficient. |
-| `browser_console` | `bsk console` | Read buffered console/log/exception entries without evaluating JavaScript. |
-| `browser_network` | `bsk network` | Read buffered network response/failure metadata. |
-| `browser_window_resize` | `bsk window resize` | Resize the owned session's Agent Window. |
-
-`bsk evaluate` and `bsk record` are intentionally not exposed by this plugin: arbitrary page
-evaluation is a higher-risk capability, while recording is long-running and needs a dedicated
-DeepSeek Harness lifecycle before it can be added safely.
 
 ## Agent skill (progressive disclosure)
 
 Beyond the tools, the plugin publishes the **`browser-skill` agent skill** through the harness's
 official skill seam (`ctx.skills.register`): the catalog entry (name + routing description) is
 resident in `<available_skills>`, and the body is loaded only when the model invokes the `skill`
-tool. Its single source is the DSH-specific `skill/SKILL.md`, which documents only structured
-`browser_*` calls and their plugin semantics. The repository-root CLI skill is intentionally not
-concatenated: its command examples belong to a different execution interface and would bypass
-the plugin's ownership, live observation UI, cancellation, and cleanup path if followed directly.
-The build rejects internal CLI-name leakage, command-line code blocks, unknown browser tools, and
-missing supported browser tools before embedding the Markdown. Registration and every pre-step
-catalog snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
+tool. The body is assembled at build time from two parts, so there is exactly one source of
+truth: a dsh-specific prelude (`skill/prelude.md` — tool↔CLI map, owned-session semantics,
+plugin-only overrides) followed verbatim by the canonical CLI skill (`skill/SKILL.md` at the
+repo root — the same file `crates/bsk-cli/build.rs` mirrors for the CLI package; workflows,
+stop-when-done rules, refs usage, sandbox rules). Registration and every pre-step catalog
+snapshot are pure in-memory reads (no disk/process/daemon); compositions without the skill
 seam degrade silently.
 
 ## Multi-session model
@@ -109,7 +88,7 @@ All fields are optional and validated through the plugin's Schemastery `Config`:
         # lazyTools: true              # reveal browser_* tools only after the skill is invoked
 ```
 
-- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the 28
+- **`lazyTools` (default `true`)** — the final progressive-disclosure stage: the eleven
   `browser_*` tool schemas stay OUT of the system prompt (zero schema tokens) until the
   `browser-skill` skill is actually invoked — the skill catalog entry is the only
   advertisement. One successful invocation (model tool call, or a `/browser-skill` user
@@ -173,7 +152,7 @@ shell's theme cannot bleed back in.
   card). Screenshots additionally attach the image itself when the host mounts an attachment store
   and the active model route declares image input; otherwise the PNG path is returned.
 - **Web UI toolview (browser half)**: the package is dual-face. `dsh.client` (platform `web`) ships
-  `lib/client.cjs`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
+  `lib/client.js`, which registers a keyed `tool.call.toolview` view for `browser_screenshot`. The
   custom view keeps the terminal block (command + output) and, when the settled result carries an
   image block, resolves the durable attachment through the client session's authorized
   `readAttachment` RPC and renders it with the shared `MessageImage` thumbnail/lightbox atoms.
@@ -204,8 +183,8 @@ as `@wxg-prc-cpg/browser-skill-dsh-plugin`. The Cordis plugin id stays
 Trigger it by pushing a tag that matches `package.json`'s `version`:
 
 ```sh
-git tag dsh-plugin-v0.1.2
-git push origin dsh-plugin-v0.1.2
+git tag dsh-plugin-v0.1.0
+git push origin dsh-plugin-v0.1.0
 ```
 
 Or run the workflow from the Actions tab (`workflow_dispatch`). The job reads the

packages/dsh-plugin-browserskill/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wxg-prc-cpg/browser-skill-dsh-plugin",
-  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill browser automation (browser_* tools) to the model",
-  "version": "0.1.2",
+  "description": "DeepSeek Harness tool plugin that exposes BrowserSkill (bsk) browser automation to the model",
+  "version": "0.1.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -107,8 +107,6 @@
     "@deepseek-ai/dsh-client-ui-primitives": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-client-ui-tool": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-scope": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
     "@deepseek-ai/schemastery": "^3.18.1",
     "@tailwindcss/cli": "^4.3.3",

packages/dsh-plugin-browserskill/scripts/build-skill-content.mjs

@@ -1,15 +1,20 @@
-// Embed the DeepSeek Harness-specific browser skill at build time. The model-facing
-// skill deliberately documents only injected browser_* tools; the repository's CLI
-// skill is a separate interface and must never be concatenated here.
+// Assemble the plugin's skill content: a dsh-specific routing prelude, the
+// canonical CLI skill body verbatim (repo-root skill/SKILL.md — the same source
+// crates/bsk-cli's build.rs mirrors), then a dsh routing reminder postlude. The
+// original's YAML frontmatter is stripped: name/description are supplied by the
+// registration.
 // Output: src/skill-content.generated.ts (gitignored, built before tsdown and
-// before vitest), so registration is a pure in-memory read.
+// before vitest) so the markdown ships inlined in the bundle and registration
+// is a pure in-memory read — never a per-step disk access.
 import { readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const pkg = join(here, "..");
-const source = readFileSync(join(pkg, "skill", "SKILL.md"), "utf8");
+const prelude = readFileSync(join(pkg, "skill", "prelude.md"), "utf8");
+const upstream = readFileSync(join(pkg, "..", "..", "skill", "SKILL.md"), "utf8");
+const postlude = readFileSync(join(pkg, "skill", "postlude.md"), "utf8");
 
 function stripFrontmatter(markdown) {
   if (!markdown.startsWith("---\n")) return markdown;
@@ -17,69 +22,18 @@ function stripFrontmatter(markdown) {
   return end === -1 ? markdown : markdown.slice(end + 5).replace(/^\s*\n/, "");
 }
 
-const SUPPORTED_BROWSER_TOOLS = [
-  "browser_session_start",
-  "browser_session_stop",
-  "browser_session_list",
-  "browser_navigate",
-  "browser_navigate_back",
-  "browser_navigate_forward",
-  "browser_reload",
-  "browser_wait_for_navigation",
-  "browser_snapshot",
-  "browser_observe",
-  "browser_get_html",
-  "browser_screenshot",
-  "browser_console",
-  "browser_network",
-  "browser_click",
-  "browser_hover",
-  "browser_fill",
-  "browser_select",
-  "browser_press",
-  "browser_tab_list",
-  "browser_tab_create",
-  "browser_tab_select",
-  "browser_tab_close",
-  "browser_tab_borrow",
-  "browser_tab_return",
-  "browser_request_help",
-  "browser_emulate",
-  "browser_window_resize",
-];
-
-function validateModelFacingSkill(markdown) {
-  if (/\bbsk\b/i.test(markdown)) {
-    throw new Error("DSH skill must not expose the internal CLI name");
-  }
-  if (/```(?:bash|sh|shell)\b/i.test(markdown)) {
-    throw new Error("DSH skill must not contain command-line code blocks");
-  }
-
-  const mentioned = new Set(markdown.match(/\bbrowser_[a-z][a-z_]*\b/g) ?? []);
-  const supported = new Set(SUPPORTED_BROWSER_TOOLS);
-  const unknown = [...mentioned].filter((name) => !supported.has(name));
-  const missing = SUPPORTED_BROWSER_TOOLS.filter((name) => !mentioned.has(name));
-  if (unknown.length > 0) {
-    throw new Error(`DSH skill mentions unsupported browser tools: ${unknown.join(", ")}`);
-  }
-  if (missing.length > 0) {
-    throw new Error(`DSH skill omits supported browser tools: ${missing.join(", ")}`);
-  }
-}
-
 const NAME = "browser-skill";
 const DESCRIPTION =
-  "Browser automation against the user's logged-in Chromium through this plugin's injected " +
-  "browser_* tools. Use to visit and read pages, fill forms, click through flows, inspect tabs, " +
-  "debug page activity, or smoke-test UI changes in a managed Agent Window.";
+  "Browser automation against the user's logged-in Chromium through this plugin's injected browser_* tools; never invoke bsk through bash or shell. " +
+  "tools (bsk engine): visit and read pages, fill forms, click through flows, scrape data, " +
+  "smoke-test UI changes. Use when a task needs a real browser; requires the bsk CLI and the " +
+  "browser-skill extension connected.";
 
-const content = `${stripFrontmatter(source).trim()}\n`;
-validateModelFacingSkill(content);
+const content = `${prelude.trim()}\n\n${stripFrontmatter(upstream).trim()}\n\n${postlude.trim()}\n`;
 
 const banner =
   "// GENERATED by scripts/build-skill-content.mjs — do not edit.\n" +
-  "// Source: skill/SKILL.md (DeepSeek Harness browser_* tool instructions).\n";
+  "// Sources: skill/prelude.md + ../../../skill/SKILL.md + skill/postlude.md.\n";
 
 writeFileSync(
   join(pkg, "src", "skill-content.generated.ts"),

packages/dsh-plugin-browserskill/skill/SKILL.md

@@ -1,271 +0,0 @@
----
-name: browser-skill
-description: |
-  Use the injected browser_* tools to automate the user's logged-in Chromium
-  browser in a managed Agent Window.
----
-
-# browser-skill for DeepSeek Harness
-
-Drive the user's real Chromium browser through the structured `browser_*` tools provided by this
-plugin. The browser keeps the user's existing logins and cookies while isolating automation in an
-Agent Window. Use the tool schemas exactly as exposed by DeepSeek Harness; arguments are structured
-fields, not command-line flags.
-
-## Tool availability
-
-Loading this skill reveals the browser tools for the rest of the conversation. If the tools were
-hidden before this skill was loaded, start browser work only after the skill invocation succeeds.
-
-All browser operations must use the injected tools directly. Do not translate the examples in this
-document into terminal commands or invoke another process to control the browser. Direct tool calls
-preserve session ownership, the live observation window, tool cards, cancellation, and cleanup.
-
-## When to use
-
-- Visit and read pages that require the user's existing browser session.
-- Fill forms, select options, click through bounded flows, or smoke-test a web UI.
-- Inspect tabs, page structure, screenshots, console messages, or network metadata.
-- Work with a user tab after explicitly borrowing it into the Agent Window.
-
-Do not use browser automation for tasks that need only local files, a purpose-built API, or an
-explanation. Never extract credentials, cookies, tokens, or other secrets. Do not keep control of a
-personal tab longer than the immediate task requires.
-
-## Mandatory workflow
-
-Every browser task follows this lifecycle:
-
-1. Call `browser_session_start` and retain its returned `sessionId`.
-2. Use that session for every browser operation. Pass `session` explicitly when more than one
-   session exists.
-3. Call `browser_session_stop` when the bounded goal is reached or an error ends the task. Treat
-   cleanup like a `finally` path unless the user explicitly asks to keep the session open.
-
-Conceptual tool-call sequence:
-
-```text
-browser_session_start({ url: "https://example.com" })
-browser_observe({ session: sessionId })
-browser_click({ session: sessionId, target: "@e4" })
-browser_observe({ session: sessionId })
-browser_session_stop({ session: sessionId })
-```
-
-The plugin owns only sessions created by `browser_session_start`. `browser_session_list` reports
-only those owned sessions. Never guess or reuse a session id from another program. When `session`
-is omitted, most tools use the most recently started or used owned session; explicit ids are safer
-for multi-session work.
-
-## Stop when the goal is met
-
-Browser work is a bounded task, not open-ended browsing.
-
-1. Define one observable success condition from the user's request.
-2. Take the shortest path: observe, act, then perform at most one relevant check.
-3. Stop immediately when success is visible. Do not refresh, navigate, click, or perform extra
-   verification after success.
-4. If a human-only step appears, use `browser_request_help`. If an action fails twice without
-   progress, pause instead of brute-forcing.
-5. When uncertain, make at most one fresh observation. If the state is still ambiguous, ask the
-   user rather than continuing to click.
-
-## Core interaction loop
-
-Use `browser_navigate` to open a destination in the active Agent Window tab, then inspect the page
-before interacting:
-
-1. `browser_observe` is the primary semantic view. It returns roles, states, text, and `@eN` refs,
-   including hints about conditional hover or focus surfaces.
-2. `browser_snapshot` is the static accessibility-tree fallback when the semantic view is
-   insufficient or a stricter tree is useful.
-3. Prefer a fresh `@eN` ref over a raw CSS selector for `browser_click`, `browser_hover`,
-   `browser_fill`, `browser_select`, and targeted `browser_press` calls.
-4. Observe again after navigation or a meaningful DOM change before using another ref.
-
-Refs invalidate after navigation and may also become stale after large DOM changes. Never carry a
-ref to a new page. If an observation marks a control as hover-triggered, call `browser_hover` on the
-trigger, observe again, and then act on the newly visible ref.
-
-Use interaction tools according to their schemas:
-
-- `browser_click`: click a ref or selector; optionally choose mouse button and click count.
-- `browser_hover`: move to a ref or selector and allow hover UI to settle; then observe again.
-- `browser_fill`: clear and fill a text-capable element; set `noClear` only when appending is
-  intentional.
-- `browser_select`: pass `values` as an array, including for a single option.
-- `browser_press`: send a key or combo, optionally focusing `target` first.
-
-Actions may trigger a navigation after the action itself returns. Use
-`browser_wait_for_navigation` only when that lifecycle wait is actually needed, then observe the
-new page.
-
-## Observation and page reading priority
-
-Escalate page reading only as needed:
-
-1. `browser_observe` for normal semantic understanding and interaction refs.
-2. `browser_snapshot` for a stricter static accessibility tree.
-3. `browser_get_html` for hidden DOM, metadata, or exact markup that the semantic views cannot
-   provide. A `ref` must come from a fresh observation; keep `maxBytes` bounded.
-4. `browser_screenshot` for layout, styling, canvas, image content, or another genuinely visual
-   question. Pass a fresh `ref` to crop to one element, or omit it for the visible tab.
-
-Do not start with raw HTML or a screenshot merely to discover ordinary controls. Screenshots may
-return an inline image or a saved path depending on the deployment.
-
-## Tabs and the Agent Window boundary
-
-Write actions normally affect only Agent Window tabs.
-
-- `browser_tab_list` lists `agent`, `user`, or `all` tabs visible to the owned session. Use
-  `scope: "user"` to locate a user tab before borrowing it.
-- `browser_tab_create` creates an Agent Window tab. It is active by default; set `active: false`
-  for a background tab.
-- `browser_tab_select` focuses an Agent Window tab.
-- `browser_tab_close` closes an Agent Window tab.
-- `browser_tab_borrow` moves a chosen user tab into the Agent Window before any write action.
-- `browser_tab_return` returns a borrowed tab to its original window and position. Return it as
-  soon as the immediate task is finished; stopping the session is only the fallback cleanup.
-
-Use only a `tabId` returned by `browser_tab_list` or `browser_tab_create`. Do not assume a tab id
-from page position or title.
-
-## Navigation and lifecycle
-
-- `browser_navigate` opens a URL and can wait for a requested lifecycle phase.
-- `browser_navigate_back` and `browser_navigate_forward` move one history entry.
-- `browser_reload` reloads the current tab; use `hard: true` only when bypassing cache is necessary.
-- `browser_wait_for_navigation` waits for a lifecycle event after an action that did not already
-  wait. Avoid speculative waits when no navigation is expected.
-
-After navigation, history traversal, or reload, discard old refs and call `browser_observe` or
-`browser_snapshot` again.
-
-## Ask the user for browser help
-
-Call `browser_request_help` for login, captcha, OTP, payment confirmation, consent, or another step
-that requires the user. Give a clear `prompt`; when the prompt refers to a concrete control, pass
-its fresh ref or selector in `targets` so the overlay can highlight it. Use `title` only when it
-adds clarity.
-
-Optional `completionCriteria` can finish the pause automatically when the page has an explicit,
-stable success signal. It supports `any` or `all` conditions using `urlContains`, `urlMatches`,
-`selectorExists`, `selectorMissing`, `textExists`, or `textMissing`, plus `stableForMs`.
-
-```text
-browser_request_help({
-  session: sessionId,
-  title: "Sign in required",
-  prompt: "Complete sign-in, then return control after the account page appears.",
-  targets: ["@e7"],
-  timeoutMs: 300000,
-  completionCriteria: {
-    any: [{ urlContains: "/account" }, { selectorExists: "[data-testid='account-menu']" }],
-    stableForMs: 1000
-  }
-})
-```
-
-Interpret outcomes deliberately:
-
-- `continued` or `completed`: the user returned control or the explicit detector matched. Observe
-  again before reasoning about the new state or using refs.
-- `cancelled`: stop the requested flow.
-- `timed_out`: report the timeout; do not repeatedly reopen the prompt.
-- `disabled`: unattended mode does not allow help; proceed only if safe or stop gracefully.
-- `navigated`: legacy outcome; do not treat navigation alone as proof of success.
-
-## Debugging without page scripting
-
-Use the read-only debugging tools only when relevant to the user's task:
-
-- `browser_console` reads buffered console messages, browser logs, and JavaScript exceptions.
-  Set `includeStack: true` when stack frames are useful.
-- `browser_network` reads buffered response and failure metadata. It does not return request or
-  response headers or bodies and does not modify traffic.
-
-Both tools accept `tabId`, `since`, `limit`, and `maxTextChars`. Their result returns `nextSince`;
-pass that value as the next `since` cursor instead of repeatedly requesting the same entries.
-
-Arbitrary page script evaluation and interaction recording are intentionally unsupported in this
-DeepSeek Harness plugin. Do not invent tool names or route around this limitation. If the task
-strictly requires either capability, explain that it is not available in this phase.
-
-## Window and device controls
-
-- `browser_window_resize` changes the Agent Window's outer `width` and `height`; each dimension
-  must be from 100 through 7680 CSS pixels.
-- `browser_emulate` applies a built-in device preset or explicit viewport settings to the active
-  tab. Explicit `width` and `height` must be supplied together. `mobile: true` also requires both
-  dimensions. Use `off: true` alone to clear emulation. Emulation is per-tab and new tabs do not
-  inherit it.
-
-## Tool reference
-
-### Sessions
-
-| Tool | Purpose |
-| --- | --- |
-| `browser_session_start` | Start an owned Agent Window session, optionally with URL, size, browser instance, focus behavior, or device preset. |
-| `browser_session_stop` | Stop an owned session and close its Agent Window. |
-| `browser_session_list` | List owned sessions and identify the current one. |
-
-### Navigation and reading
-
-| Tool | Purpose |
-| --- | --- |
-| `browser_navigate` | Navigate the active tab to a URL. |
-| `browser_navigate_back` | Go back one history entry. |
-| `browser_navigate_forward` | Go forward one history entry. |
-| `browser_reload` | Reload the active tab, optionally bypassing cache. |
-| `browser_wait_for_navigation` | Wait for an expected page lifecycle event. |
-| `browser_observe` | Read the primary semantic page representation with refs. |
-| `browser_snapshot` | Read the static accessibility-tree fallback with refs. |
-| `browser_get_html` | Read raw document or ref-scoped HTML as a last resort. |
-| `browser_screenshot` | Capture the visible tab or a ref-cropped element. |
-
-### Interaction
-
-| Tool | Purpose |
-| --- | --- |
-| `browser_click` | Click a ref or CSS selector. |
-| `browser_hover` | Hover a ref or selector to reveal conditional UI. |
-| `browser_fill` | Fill a text-capable element. |
-| `browser_select` | Select one or more option values. |
-| `browser_press` | Send a keyboard key or combo. |
-
-### Tabs
-
-| Tool | Purpose |
-| --- | --- |
-| `browser_tab_list` | List visible user and Agent Window tabs. |
-| `browser_tab_create` | Create an Agent Window tab. |
-| `browser_tab_select` | Focus an Agent Window tab. |
-| `browser_tab_close` | Close an Agent Window tab. |
-| `browser_tab_borrow` | Move a user tab into the Agent Window. |
-| `browser_tab_return` | Return a borrowed tab to its original window. |
-
-### Assistance, diagnostics, and display
-
-| Tool | Purpose |
-| --- | --- |
-| `browser_request_help` | Pause for an explicit user browser step. |
-| `browser_console` | Read buffered console and exception entries. |
-| `browser_network` | Read buffered response and failure metadata. |
-| `browser_window_resize` | Resize the Agent Window. |
-| `browser_emulate` | Apply or clear per-tab device emulation. |
-
-## Error handling and final checklist
-
-On a stale ref, observe again and retry once with a fresh ref. On a closed or unknown tab, list
-tabs instead of guessing. On an unknown session, list owned sessions or start a new one; never try
-foreign ids. On timeout, decide whether one longer, purposeful wait is justified. Avoid repeated
-actions with unchanged state.
-
-Before finishing a browser task, verify that:
-
-- The user's observable goal is met, or the blocker is clearly reported.
-- Any borrowed tab has been returned when practical.
-- The owned session has been stopped unless the user explicitly asked to keep it open.
-- No further page action is taken after success.

packages/dsh-plugin-browserskill/skill/postlude.md

@@ -0,0 +1,10 @@
+---
+
+## DSH routing reminder
+
+The CLI-oriented reference above describes behavior, not the execution mechanism in
+DeepSeek Harness. For every browser operation, call the injected `browser_*` model
+tool. Do not translate these examples into `bash` commands and do not execute `bsk`
+directly; the plugin invokes `bsk` internally. In particular, always begin with
+`browser_session_start`, pass its returned session id to subsequent `browser_*`
+tools, and finish with `browser_session_stop`.

packages/dsh-plugin-browserskill/skill/prelude.md

@@ -0,0 +1,71 @@
+# browser-skill (dsh edition)
+
+## DSH tool-routing requirement (highest priority)
+
+This skill is running inside DeepSeek Harness, where the plugin has injected
+structured `browser_*` model tools. **Always call those injected `browser_*` tools
+for browser work. Never use `bash`, `shell`, `exec`, or another tool to invoke the
+`bsk` CLI directly.** The CLI command names shown below are only conceptual
+mappings for understanding the tools; they are not instructions to run commands.
+If a `browser_*` tool is available, using the CLI directly is incorrect because it
+bypasses plugin session ownership, observation UI, tool cards, and cleanup.
+
+Use the injected tool whose name matches the operation, for example:
+`browser_session_start`, `browser_navigate`, `browser_observe`, `browser_snapshot`,
+`browser_click`, `browser_fill`, `browser_press`, `browser_screenshot`, and
+`browser_session_stop`. Pass arguments as the tool schema specifies (not CLI flags).
+
+Drive the user's **real Chromium browser** (logins, cookies, Agent Window isolation)
+through this plugin's `browser_*` tools. Each injected tool is implemented by the
+plugin using the `bsk` engine internally — the model must not invoke that engine
+itself. The workflow, judgment rules, and safety constraints remain identical to
+the canonical CLI skill.
+
+> **Tool availability**: invoking this skill (which you just did) makes the plugin's
+> `browser_*` tools available for the rest of the session — they are injected on
+> successful skill load. Until then they are deliberately hidden, so do not attempt
+> a browser action before loading this skill.
+
+## Tool ↔ CLI map
+
+The tools below are thin, structured wrappers over the bsk CLI verbs of the same
+name; `session` parameters take the 4-letter session id (no `--session` flag
+spelling here):
+
+| dsh tool | bsk equivalent |
+|---|---|
+| `browser_session_start` / `browser_session_stop` / `browser_session_list` | `bsk session start/stop/list` |
+| `browser_navigate` | `bsk navigate` |
+| `browser_snapshot` / `browser_observe` | `bsk snapshot` / `bsk observe` |
+| `browser_click` / `browser_fill` / `browser_press` | `bsk click` / `bsk fill` / `bsk press` |
+| `browser_screenshot` | `bsk screenshot` |
+| `browser_emulate` | `bsk emulate` |
+
+(`bsk console` / `bsk network` have no tool counterpart in this plugin yet.)
+
+Plugin-specific semantics that override or narrow the CLI rules below:
+
+- **Owned sessions only**: this plugin sees and acts on just the sessions IT
+  started via `browser_session_start`. `browser_session_list` shows only those
+  (with the current marker); passing a session id created by another program
+  (or person) sharing the bsk daemon is refused outright — never retry those
+  with the same id.
+- **Current session**: omitted `session` parameters resolve to the most
+  recently started or used OWNED session. With several sessions in flight,
+  pass `session` explicitly to avoid surprises.
+- **Screenshots**: when the model route accepts images, `browser_screenshot`
+  returns the PNG inline as an image attachment; otherwise it returns the
+  saved file path.
+- **`browser_emulate mobile`**: requires `width`+`height` — the bsk daemon
+  refuses `--mobile` without viewport dimensions.
+- **Live observation**: in the dsh Web UI, every owned session is watched by
+  the floating overlay (thumbnails, action, interrupt) — observational side
+  traffic is free and never steals your command turn; just keep acting.
+
+The canonical CLI skill body follows verbatim (source of truth: `skill/SKILL.md`
+in the BrowserSkill repo, mirrored by build into `crates/bsk-cli/skill/SKILL.md`).
+Read `bsk <verb> --session <id>` as "the `browser_<verb>` tool with
+`session: <id>`"; everything else — when to use, the stop-when-done rules, the
+interaction loop, refs, sandbox rules — applies unchanged.
+
+---

packages/dsh-plugin-browserskill/src/archive-cleanup.ts

@@ -1,108 +0,0 @@
-/**
- * Archive-triggered bsk session cleanup. DSH conversation archival writes
- * the workspace registry's durable global state, which the storage domain
- * broadcasts as `domain/changed` ({domain: 'workspace', table: ''}) with
- * the new `archivedSessionIds`. The watcher diffs that set and stops every
- * bsk session owned by a freshly archived conversation — archived sessions
- * are hidden from every surface, so their Agent Windows would otherwise
- * linger with no way back to them.
- *
- * Ownership lineage: browser_session_start records the calling agent's
- * session id PLUS every ancestor along `header.parentSession` (a subagent's
- * browsers are reaped when any ancestor is archived, the root conversation
- * included). Lineage is resolved through the host session store; an
- * unloaded ancestor simply ends the walk.
- */
-
-import type { Context } from "@deepseek-ai/cordis";
-import type { ObservationService } from "./observation";
-import type { SessionRegistry } from "./sessions";
-
-/** The wire shape of a `domain/changed` frame (see dsh-storage-domain). */
-interface DomainChange {
-  domain?: string;
-  table?: string;
-  value?: unknown;
-}
-
-/** The workspace registry's durable global singleton slice we read. */
-interface WorkspaceGlobal {
-  archivedSessionIds?: unknown;
-}
-
-/** Structural host session store face: only the lineage read is needed. */
-interface SessionStoreLike {
-  get(id: string): { header: { parentSession?: string } } | undefined;
-}
-
-/** Cap on lineage walks — defensive against a malformed parent chain. */
-const MAX_LINEAGE_DEPTH = 16;
-
-/**
- * The DSH session ids that own a tool call's browser sessions: the calling
- * agent's own session plus every ancestor along the seed lineage. Empty
- * when the call carried no agent identity (those sessions outlive any
- * archive cleanup by design — nothing can name their owner).
- */
-export function ownerSessionIds(ctx: Context, agentId: string | undefined): string[] {
-  if (agentId === undefined) return [];
-  const store = ctx.get("sessions") as SessionStoreLike | undefined;
-  const ids: string[] = [];
-  let current: string | undefined = agentId;
-  for (let depth = 0; current !== undefined && depth < MAX_LINEAGE_DEPTH; depth += 1) {
-    if (ids.includes(current)) break; // a cycle in stored headers must not loop
-    ids.push(current);
-    current = store?.get(current)?.header.parentSession;
-  }
-  return ids;
-}
-
-/**
- * Watch conversation archival and stop the bsk sessions it opened. Returns
- * the disposer (plugin unload). In compositions without the workspace
- * domain (headless), the event simply never fires — and a context without
- * the events mixin degrades to a no-op like the other optional seams.
- */
-export function armArchiveCleanup(
-  ctx: Context,
-  registry: SessionRegistry,
-  observation: ObservationService,
-): () => void {
-  // 'domain/changed' lives outside the vendored Events type map, so the
-  // listener goes through a structural view of the events mixin.
-  const on = (
-    ctx as { on?: (event: string, listener: (change: DomainChange) => void) => () => void }
-  ).on;
-  if (typeof on !== "function") return () => {};
-
-  /** Archived ids already accounted for; lazily seeded from the registry. */
-  let seen: Set<string> | undefined;
-  const initialize = (): Set<string> => {
-    if (seen === undefined) {
-      const registryService = ctx.get("workspaceRegistry") as
-        | { archivedSessionIds?: readonly string[] }
-        | undefined;
-      seen = new Set(registryService?.archivedSessionIds ?? []);
-    }
-    return seen;
-  };
-
-  return on.call(ctx, "domain/changed", (change: DomainChange) => {
-    if (change?.domain !== "workspace" || change?.table !== "") return;
-    const archived = (change.value as WorkspaceGlobal | undefined)?.archivedSessionIds;
-    if (!Array.isArray(archived)) return;
-    const previous = initialize();
-    const fresh = archived.filter(
-      (id): id is string => typeof id === "string" && !previous.has(id),
-    );
-    seen = new Set(archived.filter((id): id is string => typeof id === "string"));
-    for (const dshSessionId of fresh) {
-      for (const sessionId of registry.ownedByDsh(dshSessionId)) {
-        // stopSession owns the full teardown (kill in-flight tools, queue
-        // the daemon stop, drop registry + observation entries); a failure
-        // just leaves the session for idle timeout or unload cleanup.
-        void observation.stopSession(sessionId).catch(() => {});
-      }
-    }
-  });
-}

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.module.css

@@ -30,51 +30,17 @@
   color: var(--card-foreground);
 }
 
-/* Sidebar carrier: fill the better-sidebar tab area and let the body flex
-   (the tab content container owns the outer sizing). */
-.sidebar-tab {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-  min-height: 0;
-}
-
-.sidebar-tab > * {
-  flex: 1;
-  min-height: 0;
-}
-
-/* The BSK product mark in the sidebar tab strip (the source artwork already
-   carries rounded corners — just soften the square to match). */
-.brand-icon {
-  display: block;
-  border-radius: 22%;
-}
-
 .header {
   display: flex;
   align-items: center;
   gap: 6px;
   padding: 6px 8px;
+  cursor: move;
   user-select: none;
   touch-action: none;
   border-bottom: 1px solid var(--border);
 }
 
-/* Only the floating card drags by its header — the sidebar tab does not. */
-.header[data-draggable] {
-  cursor: move;
-}
-
-/* In the sidebar the status row is chrome, not a card edge: drop its bottom
-   border. A fixed-height bordered row can never track the shell header's
-   hairline across the panel boundary (its height varies per window), and
-   the BSK warm border tint clashes with the sidebar's neutral hairlines —
-   borderless, the stage's own background provides the separation. */
-.sidebar-tab .header {
-  border-bottom: none;
-}
-
 .status-text {
   flex: 1;
   min-width: 0;
@@ -165,12 +131,6 @@
   border-top: 1px solid var(--border);
 }
 
-.actions-group {
-  display: inline-flex;
-  align-items: center;
-  gap: 4px;
-}
-
 .tool-wrap {
   position: relative;
   display: inline-flex;
@@ -205,14 +165,8 @@
   color: var(--destructive);
 }
 
-/* Stop session: danger-tinted like interrupt. */
-.tool-stop {
-  color: var(--destructive);
-}
-
-/* Hover the wrap (not just :hover on the button) so the tooltip target
-   lights the icon up too. The corner resize handles sit above this bar, so
-   the outer sliver of the corner-most buttons starts a resize instead. */
+/* Hover the wrap (not just :hover on the button) so the tooltip target and
+   the left-corner resize overlay still light the icon up. */
 .tool-wrap:hover .tool-button:not(:disabled) {
   color: var(--foreground);
   background: var(--accent);
@@ -227,15 +181,6 @@
   background: var(--accent);
 }
 
-/* The armed (confirm) state of the stop button: solid destructive fill so
-   the second click reads as final. Written at the wrap-hover specificity so
-   the hover rules above never wash it out. */
-.tool-button.tool-stop-armed,
-.tool-wrap:hover .tool-button.tool-stop-armed {
-  color: var(--destructive-foreground);
-  background: var(--destructive);
-}
-
 .hint {
   position: absolute;
   bottom: calc(100% + 4px);
@@ -258,16 +203,13 @@
   right: 0;
 }
 
-/* Invisible hit targets — no grip glyph; all four corners resize. Must sit
-   above the bottom .actions bar (z-index 3): it spans the full card width
-   and would otherwise swallow every pointer event aimed at the sw/se
-   corners. The top corners already win because .header is not positioned. */
+/* Invisible hit targets — no grip glyph; all four corners resize. */
 .resize-handle {
   position: absolute;
   width: 16px;
   height: 16px;
   touch-action: none;
-  z-index: 4;
+  z-index: 2;
 }
 
 .resize-handle[data-corner="nw"] {

packages/dsh-plugin-browserskill/src/client/ObservationOverlay.tsx

@@ -3,18 +3,13 @@
 // composer's way); collapsed = a status capsule; "pop out" upgrades the same
 // content to a native Document PiP window (user gesture required by the
 // browser). Multi-session renders a meeting-style strip under the focus view.
-// When the dsh-better-sidebar plugin is installed the tracking view moves
-// into a sidebar tab instead (see observation-sidebar.tsx) and this floating
-// card hides itself via the sidebar-mode flag. Visuals follow the
-// BrowserSkill product family: @browser-skill/ui components and oklch tokens
-// on a .bsk-obs scope root, so the card reads as BSK's own surface without
-// leaking styles into (or inheriting themes from) the shell.
+// Visuals follow the BrowserSkill product family: @browser-skill/ui components
+// and oklch tokens on a .bsk-obs scope root, so the card reads as BSK's own
+// surface without leaking styles into (or inheriting themes from) the shell.
 
 import { cn } from "@browser-skill/ui";
 import {
   RiArrowDownSLine,
-  RiCheckLine,
-  RiCloseCircleLine,
   RiErrorWarningLine,
   RiPictureInPicture2Line,
   RiPushpinFill,
@@ -30,8 +25,6 @@ const IconPip = asIcon(RiPictureInPicture2Line);
 const IconDown = asIcon(RiArrowDownSLine);
 const IconWarn = asIcon(RiErrorWarningLine);
 const IconPin = asIcon(RiPushpinFill);
-const IconCloseSession = asIcon(RiCloseCircleLine);
-const IconCheck = asIcon(RiCheckLine);
 
 import {
   type ReactNode,
@@ -46,12 +39,11 @@ import { createPortal } from "react-dom";
 import type { SessionObservation } from "../observation";
 import css from "./ObservationOverlay.module.css";
 import type { ObservationClientStore } from "./observation-store";
-import { focusOf, statusOf, useObservationView, usePip } from "./observation-view";
-import { getSidebarMode, subscribeSidebarMode } from "./sidebar-mode";
 
-// The pure view helpers live in observation-view (shared with the sidebar
-// tab); re-export so existing imports of this module keep working.
-export { focusOf, statusOf };
+/** Minimal Document PiP surface (TS lib.dom lacks it). */
+interface DocumentPip {
+  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
+}
 
 interface Point {
   x: number;
@@ -69,6 +61,11 @@ const EDGE_MARGIN = 16;
 /** Default dock: top-right, just under the shell's top bar (no spacing tokens exist in dsh 0.1). */
 const TOP_OFFSET = 64;
 
+function pipApi(): DocumentPip | undefined {
+  if (typeof window === "undefined") return undefined;
+  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
+}
+
 function clampSize(size: Size, viewport: Size): Size {
   const maxW = viewport.w * 0.8;
   const maxH = viewport.h * 0.8;
@@ -117,6 +114,23 @@ function formatElapsed(sinceMs: number, nowMs: number): string {
   return `${mm}:${ss}`;
 }
 
+/**
+ * Auto-follow focus: the most recently touched session, but never yank focus
+ * to a session whose latest action failed (errors flag the strip item, they
+ * do not steal the stage) or one already reported dead.
+ */
+export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
+  if (sessions.length === 0) return undefined;
+  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
+  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
+  return healthy ?? byRecency[0];
+}
+
+export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
+  if (obs.lastError !== undefined && obs.action === "idle") return "error";
+  return obs.action === "idle" ? "idle" : "active";
+}
+
 /** Compact toolbar icon: no label, hover bubble for the name / semantics. */
 function IconAction(props: {
   label: string;
@@ -152,83 +166,6 @@ function IconAction(props: {
   );
 }
 
-/** How long the stop button stays armed before the confirm click expires. */
-const STOP_ARM_MS = 3000;
-
-/**
- * Stop-session button with a lightweight two-click confirm: the first click
- * arms the button (solid red, check icon, short expiry), the second executes
- * the stop. No dialog, no layout shift — and a stray single click can never
- * close an Agent Window.
- */
-function StopSessionAction(props: {
-  sessionId: string | undefined;
-  onStop: (sessionId: string) => Promise<boolean>;
-}) {
-  const { sessionId, onStop } = props;
-  const [hover, setHover] = useState(false);
-  const [armed, setArmed] = useState(false);
-  const [stopping, setStopping] = useState(false);
-
-  useEffect(() => {
-    if (!armed) return;
-    const timer = setTimeout(() => setArmed(false), STOP_ARM_MS);
-    return () => clearTimeout(timer);
-  }, [armed]);
-
-  // The focused session can vanish mid-arm (stopped elsewhere): disarm.
-  useEffect(() => {
-    if (sessionId === undefined) setArmed(false);
-  }, [sessionId]);
-
-  const disabled = sessionId === undefined || stopping;
-  const label = stopping
-    ? "Stopping session…"
-    : armed
-      ? `Confirm stop session ${sessionId ?? ""}`
-      : `Stop session ${sessionId ?? ""}`;
-  const hint = stopping
-    ? "Closing the Agent Window…"
-    : armed
-      ? `Click again to stop session ${sessionId ?? ""} and close its Agent Window.`
-      : `Stop session ${sessionId ?? ""} and close its Agent Window.`;
-
-  return (
-    <span
-      className={css["tool-wrap"]}
-      onPointerEnter={() => setHover(true)}
-      onPointerLeave={() => setHover(false)}
-    >
-      <button
-        type="button"
-        className={cn(css["tool-button"], css["tool-stop"], armed && css["tool-stop-armed"])}
-        disabled={disabled}
-        aria-label={label}
-        aria-pressed={armed}
-        data-armed={armed || undefined}
-        onClick={() => {
-          if (sessionId === undefined || stopping) return;
-          if (!armed) {
-            setArmed(true);
-            return;
-          }
-          setArmed(false);
-          setStopping(true);
-          const target = sessionId;
-          void onStop(target).finally(() => setStopping(false));
-        }}
-      >
-        {armed ? <IconCheck size={16} /> : <IconCloseSession size={16} />}
-      </button>
-      {hover ? (
-        <span className={css.hint} role="tooltip">
-          {hint}
-        </span>
-      ) : null}
-    </span>
-  );
-}
-
 /** Flat status dot, specced after the BSK popup's ConnectionStatusIndicator. */
 function StatusDot({ state }: { state: "active" | "idle" | "error" | "dead" }) {
   const color =
@@ -309,8 +246,8 @@ function StripItem(props: {
   );
 }
 
-/** The floating card / PiP / sidebar-tab shared content. */
-export function OverlayBody(props: {
+/** The floating card / PiP shared content. */
+function OverlayBody(props: {
   store: ObservationClientStore;
   focus: SessionObservation | undefined;
   sessions: readonly SessionObservation[];
@@ -373,7 +310,6 @@ export function OverlayBody(props: {
       <div
         className={css.header}
         data-testid="obs-header"
-        data-draggable={onHeaderPointerDown !== undefined || undefined}
         onPointerDown={onHeaderPointerDown}
         role="presentation"
       >
@@ -427,21 +363,15 @@ export function OverlayBody(props: {
         </div>
       ) : null}
       <div className={css.actions}>
-        <div className={css["actions-group"]}>
-          <IconAction
-            label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
-            hint="Stop the current browser action."
-            disabled={!canInterrupt}
-            danger
-            onClick={onInterrupt}
-          >
-            <IconStop size={16} />
-          </IconAction>
-          <StopSessionAction
-            sessionId={focus?.sessionId}
-            onStop={(sessionId) => store.stopSession(sessionId)}
-          />
-        </div>
+        <IconAction
+          label={interrupting ? "Interrupting…" : "Interrupt the current browser action"}
+          hint="Stop the current browser action."
+          disabled={!canInterrupt}
+          danger
+          onClick={onInterrupt}
+        >
+          <IconStop size={16} />
+        </IconAction>
         {onPopOut !== undefined ? (
           <IconAction
             label="Pop out into a mini window"
@@ -457,17 +387,25 @@ export function OverlayBody(props: {
   );
 }
 
+/** Clone the host document's style/link nodes into a PiP window. */
+function cloneStylesInto(pipWindow: Window): void {
+  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
+    pipWindow.document.head.appendChild(node.cloneNode(true));
+  }
+}
+
 export function ObservationOverlay({ store }: { store: ObservationClientStore }) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store);
-  // While the better-sidebar plugin carries the tracking view, this floating
-  // card (and its capsule) stays out of the way; an already-open PiP window
-  // keeps its portal until the user closes it.
-  const sidebarMode = useSyncExternalStore(subscribeSidebarMode, getSidebarMode);
+  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
+  useEffect(() => {
+    store.start();
+    return () => store.stop();
+  }, [store]);
 
   const [collapsed, setCollapsed] = useState(false);
   const [pos, setPos] = useState<Point | null>(null);
   const [size, setSize] = useState<Size>(DEFAULT_SIZE);
-  const { pipWindow, pipSupported, popOut } = usePip();
+  const [pipWindow, setPipWindow] = useState<Window | null>(null);
+  const [pinnedId, setPinnedId] = useState<string | null>(null);
   const dragRef = useRef<{
     kind: "move" | "resize";
     corner?: ResizeCorner;
@@ -476,6 +414,23 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     base: Point & Size;
   } | null>(null);
 
+  // Elapsed-time ticker: 1s while anything is active.
+  const anyActive = snapshot.sessions.some((s) => s.action !== "idle");
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    if (!anyActive) return;
+    const timer = setInterval(() => setNow(Date.now()), 1000);
+    return () => clearInterval(timer);
+  }, [anyActive]);
+
+  // Focus: the pinned session wins while it still exists; otherwise auto-follow.
+  const pinned =
+    pinnedId !== null ? snapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
+  const focus = pinned ?? focusOf(snapshot.sessions);
+  const onTogglePin = useCallback((sessionId: string) => {
+    setPinnedId((current) => (current === sessionId ? null : sessionId));
+  }, []);
+
   const viewport = (): Size => ({ w: window.innerWidth, h: window.innerHeight });
 
   const onPointerMove = useCallback((event: PointerEvent) => {
@@ -556,21 +511,34 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     document.addEventListener("pointerup", onPointerUp);
   };
 
+  const popOut = async (): Promise<void> => {
+    const pip = pipApi();
+    if (pip === undefined) return;
+    try {
+      const win = await pip.requestWindow({ width: size.w, height: size.h });
+      cloneStylesInto(win);
+      win.addEventListener("pagehide", () => setPipWindow(null));
+      setPipWindow(win);
+    } catch {
+      // requestWindow rejects without a user gesture (or when the window was
+      // closed mid-request): stay on the in-page card, no state change.
+    }
+  };
+
+  // Hidden while no owned session exists (and no PiP is up).
+  if (snapshot.sessions.length === 0 && pipWindow === null) return null;
+
   const body = (
     <OverlayBody
       store={store}
       focus={focus}
       sessions={snapshot.sessions}
       available={snapshot.available}
-      pinnedId={pinnedId}
+      pinnedId={pinned !== undefined ? pinnedId : null}
       onTogglePin={onTogglePin}
       now={now}
       inPip={pipWindow !== null}
-      onPopOut={
-        pipWindow === null && pipSupported
-          ? () => popOut({ width: size.w, height: size.h })
-          : undefined
-      }
+      onPopOut={pipWindow === null && pipApi() !== undefined ? () => void popOut() : undefined}
       onCollapse={pipWindow === null ? () => setCollapsed(true) : undefined}
       onHeaderPointerDown={pipWindow === null ? beginMove : undefined}
     />
@@ -580,12 +548,6 @@ export function ObservationOverlay({ store }: { store: ObservationClientStore })
     return createPortal(body, pipWindow.document.body);
   }
 
-  // The sidebar tab is the carrier now — no floating card, no capsule.
-  if (sidebarMode) return null;
-
-  // Hidden while no owned session exists (and no PiP is up).
-  if (snapshot.sessions.length === 0) return null;
-
   if (collapsed) {
     const state = focus !== undefined ? statusOf(focus) : "idle";
     return (

packages/dsh-plugin-browserskill/src/client/brand-icon.ts

@@ -1,8 +0,0 @@
-/**
- * The BrowserSkill product mark (apps/extension/assets/logo.png, downscaled
- * to 32px and inlined): the sidebar tab icon, so the tracking view reads as
- * BSK's own surface next to better-sidebar's built-in "browser" tab.
- * Regenerate with: resize the source to 32x32 PNG and replace the payload.
- */
-export const BSK_LOGO_URL =
-  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAJGklEQVR42m2X248c2V3HP79zTlV19/TcPOOZWY+vsdmQFdngTQJswgs3hQ15iCJslAey+8xDAIHgH+CBNxIpj0gkEXnAKyKQWITEJlKWXSssEMfJRmuMHa/W9njHMz3Tl+nprsv5/XiomlugpdN16lR1n9/1e75fAbAbeLlO3Pz2ly4vjO7+sRbF58oiP49FEREOPwaIYQjS3IvUy0fP66kAZoYJIM7SpPVY0uy14cyzXzn9u9+4c+MG/vp1otiNa16uvxr7X/+1L3bK3lcTyU9P80ilR/uKCGYHOxxd6s2kmdaGIVYb1qyY1e8HD63UUblstwirf9J95fW/sRvXvAD0v/6Z6/O68Xf5/pS8kigiTsTkuCfIwfzAxQN37chjaAyt594JIXE4gbKMhog6Nd/qthi7lVe6L3/nG7Jz4/fPJ9u3b4U4WSwiKog/EcsTLh+PSuO3GXYs/D44QnBgyniQs7OV0+8bOxPPM6c9l660VEyF0Nmrlp9/IYT+/S/PUJ4a5C46EW8HnjVhBKjXaHJfz9Xq95xzhMThHZR5xXBrwtPNnP6eRzvzhJWzrF1d5UI759//9iYra5lrt1ycDeXsaOf+n4Y4HX8+r9SciasLS/6P12LHoyF47wipYKpM9gqePpyyvVMxjBn+1DILH17l0rkZlhYcLetT3n/A5FGfTtvTCh4ibjpVI81/J0il62V1rNStLp6j4jowxwiJh2iMevtsbU3pjYQim6Nz9hJLH13i8mrGbJgSxjuUvQfEjT2GOw4Zddh0BakPtFPH/jRKqaCSrwetKi9mKIIYhyFuOg6TurCcF7ae5ty5t48/vcTiz3+Ei+szLC06WnGA7TykfNCnmObk5nAtj+53yDcTZteMwZOChbkMVa3/14DCJBBBFBxyopndUUBqwwxu/XjAJ778Bc4ul+R3fgyj9yg/GDMpFZxHgoe0hQ9QDRzFI48zqHzJeKhcvNKiLAyiQ1BwgsOcqNZ9Xo96rgaVgmqdiBACH740y/1/+j4b7w1x80tUkwLM4VptJAQMcN6o+p7iYQIqhBQmsUIrR7cd0NI12ODAwJnWTpvZoRGqdRrS1CECeR7Z2NzHRBjeecgbX/kut39UUlx5ATe3gFUlAM5Tb/4oHCJl0oadUcFsK8E5sFh7ZaqgEFBr3KyhxAySxDMplDv3BuztlmhhZC6QqONDrXkW28Kbf/1d7A9+i6vPr7N/e5vQDZQ7jvxxUqdPwFRwHaP3sGR1boZYGabWwHdd7MHMMBUMh5mRJp6tnZx33tllJbS53J1jZj6BKpKPpkhZ8e5mj3Nf/FV+8ZOnmNz6Pr6TUvUcxeOAc0cN6xwUoWIyUhZXMqqq6bKmrQ0hWBQzdXX+nGOwV3LnJ30+trjE8mxGUUVG/Qn7owkt7/hpb5fwmat84qXz5P95EwmOqh8oNkKTSkFqICTJYDgpCOppZYGyjIfgdoApQRScCtEgDZ5b93dxuWd3OuWD8T5pqbSLyEyWcHdrh+S3r/Kpz15i/z/eQhIh9hOKjQRTyBYgFhAndSpDW+gNC+ZbGR6jjM3BVsNsXQNqhqpiOPIicuXcLFvdKT7xtNXTG+X0Bopt9Wi9dJUXX7rI5O23kNQRB4F8I0CEzgr0/B7t2YB/2iJOQDrK8HHJ+dkZqqI+JfUAYRXMGc6pM1MBBa2Ubttz5ews51c6XFjr8OJHT5N0HPIbz/Ppz11h/+03IXVUg4T8ccAidFaNp7LHzdd2uXdvj866gQq5L8nHMD+TUJUG0aAyJBqidZQcUfFqeK2vlEo1rYh5iUXl6eMB5eoKv37tOUb/9q+4LBD7gXKj3ry7Ak/iHrdeH/ArC7P07ykPekMWzkFvkNMmkHkgagNoDciogYKzaGg0YgSNYLEJj0ndfiGj6o/Z3i5or5+j2BTKJwlawcwKbMQ9fvK9Ib+QtgitQMg8d384wVYLdocls1mCad1+Fg1TDgeV4UxFTB2ow44NjQ5rwcwZ+MjqmLe/dZOBLOHHCeUUZteED+Ie73xvyHNpmyx1TERozXieW1/mO/+yzWhTWVtsU5aCqKvRT4+GmRDEHGJ6yPPMBHNGeqbCdwqs02X9l14g/a8H3PzWm/zyp1ZZXgn8tDfgnbeGPN/qIEDSyhh7w2OcPZWRsESWCq3EoVFPksZDMuUIps7qLjDUQBxkZ0tcu8KSGdIXPo3OLbOSdfj4YMIPbg6ZXxux9wRmWimFKe0k0J7v8H5vQHchpSoiC536bKhKEDlCJzM7JLJqhqtxoEYoUcEFw/Yduh8Jl38OP7eAlBOm29ssziV87JlluqMOL15ZZWVlhu0yMrfYxQQmZUU3TbCmnog1mRE1xOp9xOoaEwVRI9QnUGOECLoPNlcRlucJ6xeIgx3K/3kX23pINWnRdnBxtYNWkbkkMJ5JSLKEwaSgRFlsJWh1mNBDfsEBzZGaYIiBIgRtImCmmArhlBFOR1Q9xZ3b6OOHWFnifEq1U/84TpXgHL4hUh7hv3t91pY6eCeUpTYs2o6RisYEO6B5hpoSRCWaanNAGP5UVZ+r+YB4dxcbZ4QVx/Q9wSYg/uDYNvKyoorwgyfbtDuBC6c65HmFa5Jsh56f3NgO4iGeYC68n8Ty2WkphAUVv2hoLuggoXgUcJkRh0rVF7wHi3Vw1YxuSMh1zMpcmw8tdynzCmmCL1JjzQG3lpNU37xAdNnjYC79xywUfzbJNboEX214iqeeuN/IrkKw6BAvNUiJ1a2K0HKOT144jQBFoTWRayrc9LhWa1TTUTNqJ038wCf/LO//xZfWWw9u/zCt8uWpSiTixZ3UeJzQPkerdkyq1RryZwVN87CJBALR0ExULMtG4/VnPy4AG3/4m19YGG/9fT7NmZpEhzg5lCNHOo//774u7UYp2WEt1XrSftYMTcF32ynbrfmXz3ztjW86u3bNn/nq69/eaZ/6PUlbm/PB+YSapUozMG2uB0M5fI7WSKoKasjBu6qHczEjwWQ2iJc03XmaLb5y5mtvfNOuNeLUruHlVeK7f/7yxbXBu39U5sXnq7I8L2pH6rwRgCZyUpeKnZSOB5K2EbT1l5hPk0c+zV7bXXzmry7/5T/cvXENf/1V4v8CSYIrURx3kHgAAAAASUVORK5CYII=";

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

@@ -1,9 +1,7 @@
 /**
  * dsh-plugin-browserskill browser half: the `browser_screenshot` keyed
- * toolview plus the observation overlay (live thumbnails + interrupt). The
- * default carrier is a floating card on the `shell.overlay` seat; when the
- * dsh-better-sidebar plugin provides its `betterSidebar` service, the view
- * moves into a sidebar tab instead (see observation-sidebar.tsx).
+ * toolview plus the observation overlay (live thumbnails + interrupt) floating
+ * over the shell via the `shell.overlay` seat.
  */
 
 import type { ImageAttachmentRef } from "@deepseek-ai/dsh-attachment";
@@ -17,7 +15,6 @@ import { createElement } from "react";
 import "./bsk-tokens.nomodule.css";
 import "./bsk-ui.nomodule.css";
 import { ObservationOverlay } from "./ObservationOverlay";
-import { type BetterSidebarLike, registerObservationSidebar } from "./observation-sidebar";
 import { type EventSourceLike, ObservationClientStore } from "./observation-store";
 import { ScreenshotToolView } from "./ScreenshotToolView";
 
@@ -84,14 +81,4 @@ export function apply(ctx: ClientContext): void {
       createElement(ObservationOverlay, { store }),
     ),
   );
-  // Optional carrier upgrade: when the dsh-better-sidebar plugin is installed,
-  // its service moves the tracking view into a sidebar tab (the floating
-  // overlay hides itself through the sidebar-mode flag). In profiles without
-  // the sidebar plugin this fiber never runs and nothing changes.
-  ctx.inject(["betterSidebar"], (injected) =>
-    registerObservationSidebar(
-      (injected as unknown as { betterSidebar: BetterSidebarLike }).betterSidebar,
-      store,
-    ),
-  );
 }

packages/dsh-plugin-browserskill/src/client/observation-sidebar.tsx

@@ -1,256 +0,0 @@
-// better-sidebar carrier for the observation view. When the
-// dsh-better-sidebar plugin is installed its client publishes a
-// `betterSidebar` cordis service; the client entry then runs the
-// registration below and the tracking view moves from the floating card
-// into a single-instance sidebar tab (Document PiP pop-out stays available
-// from inside the tab). Detection is purely service-based — profiles
-// without the sidebar plugin never start this fiber and keep the floating
-// overlay.
-
-import { createElement, type ReactNode } from "react";
-import { createPortal } from "react-dom";
-import { BSK_LOGO_URL } from "./brand-icon";
-import { OverlayBody } from "./ObservationOverlay";
-import css from "./ObservationOverlay.module.css";
-import type { ObservationClientStore } from "./observation-store";
-import { useObservationView, usePip, visibleToScope } from "./observation-view";
-import { setSidebarMode } from "./sidebar-mode";
-
-/** The tab title — "Browser Skill", distinct from the sidebar's built-in "browser" tab. */
-const TAB_TITLE = "Browser Skill";
-
-/** Tab strip icon: the BrowserSkill product mark at the requested size. */
-function TabIcon({ size }: { size: number }) {
-  return (
-    <img
-      src={BSK_LOGO_URL}
-      width={size}
-      height={size}
-      alt=""
-      aria-hidden
-      className={css["brand-icon"]}
-    />
-  );
-}
-
-/**
- * Structural mirrors of dsh-better-sidebar's client service surface (only
- * the slices this integration touches — see the upstream
- * lib/types/client/service.d.ts). Declared locally so the plugin carries no
- * dependency on the sidebar package; the service contract has been stable
- * since v0.4.0 and newer capabilities arrive behind its `features` list.
- */
-export interface SidebarTabLike {
-  id: string;
-  type: string;
-  title: string;
-}
-
-export interface SidebarLeafLike {
-  kind: "leaf";
-  id: string;
-  tabs: SidebarTabLike[];
-  active: string | null;
-}
-
-export interface SidebarSplitLike {
-  kind: "split";
-  id: string;
-  dir: "row" | "col";
-  sizes: number[];
-  children: SidebarNodeLike[];
-}
-
-export type SidebarNodeLike = SidebarLeafLike | SidebarSplitLike;
-
-export interface SidebarStateLike {
-  splits: SidebarNodeLike;
-  bottomSplits: SidebarNodeLike;
-  /** Whether the right panel is expanded (the merged drawer on narrow screens). */
-  panelOpen?: boolean;
-}
-
-export interface SidebarSnapshotLike {
-  sessionId?: string;
-  state?: SidebarStateLike;
-}
-
-/** Props every tab component receives (the slices we read). */
-export interface TabComponentPropsLike {
-  /** The conversation this sidebar instance belongs to. */
-  scope: { sessionId: string };
-}
-
-export interface TabDescriptorLike {
-  id: string;
-  title: string | (() => string);
-  icon?: ReactNode | ((size: number) => ReactNode);
-  order?: number;
-  /** Single-instance: opening focuses the existing tab instead of duplicating. */
-  single?: boolean;
-  /** Small pill on the tab strip; null/undefined hides it. */
-  badge?: (
-    ctx: unknown,
-    scope: { sessionId: string },
-    state: unknown,
-  ) => string | number | null | undefined;
-  component: (props: TabComponentPropsLike) => ReactNode;
-}
-
-export interface BetterSidebarLike {
-  registerTab(descriptor: TabDescriptorLike): () => void;
-  openTab(seed: {
-    type: string;
-    title?: string;
-    /** Content seed (lands on tab.path); content opens expand the panel. */
-    path?: string;
-  }): void;
-  getSnapshot(): SidebarSnapshotLike;
-  /** Sidebar state feed (v0.12+): session switches, state and prefs changes. */
-  subscribeState?: (listener: () => void) => () => void;
-  isTabEnabled(id: string): boolean;
-}
-
-/** The registered tab type id (also the SidebarTab.type value). */
-export const OBSERVATION_TAB_TYPE = "browserskill:observation";
-
-/**
- * Inert content seed carried on auto-opened tabs: its mere presence makes
- * the sidebar treat the open as a content open (expanding the hosting panel
- * so the tracking view lands in sight). Never read by our component.
- */
-export const OBSERVATION_TAB_PATH = "browser-skill:observation";
-
-/**
- * The observation tab body: the same OverlayBody the floating card renders,
- * minus the card chrome (no drag header, no collapse — the sidebar tab bar
- * owns those), plus the PiP pop-out upgrade. The view is scoped to the
- * sidebar's conversation: only browser sessions started by it (or its
- * descendants) show here — the floating card keeps the global view.
- */
-export function ObservationSidebarTab({
-  store,
-  scopeId,
-}: {
-  store: ObservationClientStore;
-  scopeId: string;
-}) {
-  const { snapshot, focus, pinnedId, onTogglePin, now } = useObservationView(store, scopeId);
-  const { pipWindow, pipSupported, popOut } = usePip();
-
-  const body = (
-    <OverlayBody
-      store={store}
-      focus={focus}
-      sessions={snapshot.sessions}
-      available={snapshot.available}
-      pinnedId={pinnedId}
-      onTogglePin={onTogglePin}
-      now={now}
-      inPip={pipWindow !== null}
-      onPopOut={pipWindow === null && pipSupported ? () => popOut() : undefined}
-    />
-  );
-
-  if (pipWindow !== null) {
-    return createPortal(body, pipWindow.document.body);
-  }
-  return <div className={css["sidebar-tab"]}>{body}</div>;
-}
-
-function* leafNodes(node: SidebarNodeLike): Generator<SidebarLeafLike> {
-  if (node.kind === "leaf") {
-    yield node;
-    return;
-  }
-  for (const child of node.children) yield* leafNodes(child);
-}
-
-/** Whether a tab of our type is already open in either sidebar workbench. */
-export function observationTabOpen(state: SidebarStateLike | undefined): boolean {
-  if (state === undefined) return false;
-  for (const root of [state.splits, state.bottomSplits]) {
-    for (const leaf of leafNodes(root)) {
-      if (leaf.tabs.some((tab) => tab.type === OBSERVATION_TAB_TYPE)) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Register the observation sidebar tab and flip the carrier flag. Returns
- * the disposer the cordis fiber invokes when the sidebar service goes away
- * (plugin unload/HMR): the floating overlay then resumes as the carrier.
- */
-export function registerObservationSidebar(
-  service: BetterSidebarLike,
-  store: ObservationClientStore,
-): () => void {
-  setSidebarMode(true);
-  // Hold the feed for the whole sidebar lifetime so the auto-open watcher
-  // sees new sessions even while the tab itself is closed.
-  store.acquire();
-  const disposeTab = service.registerTab({
-    id: OBSERVATION_TAB_TYPE,
-    title: TAB_TITLE,
-    icon: (size: number) => createElement(TabIcon, { size }),
-    single: true,
-    // The badge counts only sessions visible to the tab strip's own
-    // conversation (global sessions from other conversations stay hidden,
-    // mirroring the tab body's scoped view).
-    badge: (_ctx, scope) => {
-      const count = store
-        .getSnapshot()
-        .sessions.filter((s) => visibleToScope(s, scope.sessionId)).length;
-      return count > 0 ? count : null;
-    },
-    component: (props) =>
-      createElement(ObservationSidebarTab, { store, scopeId: props.scope.sessionId }),
-  });
-
-  // Auto-open the tab when a browser session VISIBLE TO the active
-  // conversation appears (and right away when one is already live). The
-  // evaluation runs on observation publishes AND on sidebar state changes:
-  // the latter covers the sidebar store's async init (its state is
-  // undefined for the first beats after page load) and conversation
-  // switches. The open carries a content seed (`path`): only content opens
-  // land in sight — the sidebar expands the hosting panel for them. While
-  // the panel is OPEN an existing tab is never re-focused — the user may
-  // be reading another page on purpose; while it is collapsed a NEW
-  // session (0→N) nudges the tab back into sight, mirroring how the
-  // floating card used to reappear.
-  const activeVisibleCount = (): number => {
-    const activeId = service.getSnapshot().sessionId;
-    if (activeId === undefined) return 0;
-    return store.getSnapshot().sessions.filter((s) => visibleToScope(s, activeId)).length;
-  };
-  let previousVisible = activeVisibleCount();
-  const evaluate = (): void => {
-    const count = activeVisibleCount();
-    const { state, sessionId } = service.getSnapshot();
-    if (
-      state !== undefined &&
-      sessionId !== undefined &&
-      service.isTabEnabled(OBSERVATION_TAB_TYPE)
-    ) {
-      const open = observationTabOpen(state);
-      if (count > 0 && !open) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      } else if (previousVisible === 0 && count > 0 && open && state.panelOpen === false) {
-        service.openTab({ type: OBSERVATION_TAB_TYPE, path: OBSERVATION_TAB_PATH });
-      }
-    }
-    previousVisible = count;
-  };
-  evaluate();
-  const unsubscribe = store.subscribe(evaluate);
-  const unsubscribeState = service.subscribeState?.(evaluate);
-
-  return () => {
-    unsubscribe();
-    unsubscribeState?.();
-    disposeTab();
-    store.release();
-    setSidebarMode(false);
-  };
-}

packages/dsh-plugin-browserskill/src/client/observation-store.ts

@@ -53,7 +53,6 @@ export interface OverlaySnapshot {
 const STATE_URL = "/bsk-observation/state";
 const EVENTS_URL = "/bsk-observation/events";
 const INTERRUPT_URL = "/bsk-observation/interrupt";
-const STOP_URL = "/bsk-observation/stop";
 
 function revoke(url: string | undefined): void {
   if (url !== undefined && typeof URL.revokeObjectURL === "function") {
@@ -79,8 +78,6 @@ export class ObservationClientStore {
   };
   private available = true;
   private started = false;
-  /** Refcount of mounted consumers (overlay card, sidebar tab, sidebar fiber). */
-  private consumers = 0;
 
   constructor(private readonly deps: ObservationClientDeps) {}
 
@@ -192,23 +189,6 @@ export class ObservationClientStore {
     this.publish();
   }
 
-  /**
-   * Hold the feed for one consumer's lifetime: the stream starts with the
-   * first holder and stops with the last release. Several carriers can share
-   * the store (the floating card, the better-sidebar tab, and the sidebar
-   * integration fiber) without one unmount killing the others' updates.
-   */
-  acquire(): void {
-    this.consumers += 1;
-    if (this.consumers === 1) this.start();
-  }
-
-  release(): void {
-    if (this.consumers === 0) return;
-    this.consumers -= 1;
-    if (this.consumers === 0) this.stop();
-  }
-
   /** Forget one session's tracked + held frames, revoking their blob URLs. */
   private dropThumb(sessionId: string): void {
     const attachmentId = this.thumbBySession.get(sessionId);
@@ -312,23 +292,4 @@ export class ObservationClientStore {
       return false;
     }
   }
-
-  /**
-   * Stop one session and close its Agent Window. The session's removal
-   * arrives through the SSE remove event — no local state is touched here.
-   */
-  async stopSession(sessionId: string): Promise<boolean> {
-    try {
-      const res = await this.deps.fetchFn(STOP_URL, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ sessionId }),
-      });
-      if (!res.ok) return false;
-      const body = (await res.json()) as { stopped?: boolean };
-      return body.stopped === true;
-    } catch {
-      return false;
-    }
-  }
 }

packages/dsh-plugin-browserskill/src/client/observation-view.ts

@@ -1,148 +0,0 @@
-/**
- * Shared view logic for the observation carriers (the floating overlay card
- * and the better-sidebar tab): the store-backed view model (snapshot, focus
- * pinning, elapsed ticker) and the Document PiP pop-out. Extracted from
- * ObservationOverlay so both carriers run the same focus/interrupt behavior
- * without duplicating hooks.
- */
-
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
-import type { SessionObservation } from "../observation";
-import type { ObservationClientStore, OverlaySnapshot } from "./observation-store";
-
-/**
- * Auto-follow focus: the most recently touched session, but never yank focus
- * to a session whose latest action failed (errors flag the strip item, they
- * do not steal the stage) or one already reported dead.
- */
-export function focusOf(sessions: readonly SessionObservation[]): SessionObservation | undefined {
-  if (sessions.length === 0) return undefined;
-  const byRecency = [...sessions].sort((a, b) => b.since - a.since);
-  const healthy = byRecency.find((s) => s.lastError === undefined && s.dead !== true);
-  return healthy ?? byRecency[0];
-}
-
-export function statusOf(obs: SessionObservation): "active" | "idle" | "error" {
-  if (obs.lastError !== undefined && obs.action === "idle") return "error";
-  return obs.action === "idle" ? "idle" : "active";
-}
-
-/** Minimal Document PiP surface (TS lib.dom lacks it). */
-export interface DocumentPip {
-  requestWindow(options?: { width?: number; height?: number }): Promise<Window>;
-}
-
-export function pipApi(): DocumentPip | undefined {
-  if (typeof window === "undefined") return undefined;
-  return (window as unknown as { documentPictureInPicture?: DocumentPip }).documentPictureInPicture;
-}
-
-/** Clone the host document's style/link nodes into a PiP window. */
-export function cloneStylesInto(pipWindow: Window): void {
-  for (const node of document.querySelectorAll('link[rel="stylesheet"], style')) {
-    pipWindow.document.head.appendChild(node.cloneNode(true));
-  }
-}
-
-export interface ObservationView {
-  readonly snapshot: OverlaySnapshot;
-  /** Pinned session wins while it still exists; otherwise auto-follow. */
-  readonly focus: SessionObservation | undefined;
-  readonly pinnedId: string | null;
-  readonly onTogglePin: (sessionId: string) => void;
-  /** 1s ticker while anything is active (drives the elapsed readout). */
-  readonly now: number;
-}
-
-/**
- * Whether one session is visible on a surface scoped to one DSH
- * conversation: sessions started by that conversation or its descendants
- * (the lineage ancestors ride along on the entry). Untracked sessions (no
- * owner recorded) are hidden from scoped surfaces but stay in global views.
- */
-export function visibleToScope(obs: SessionObservation, scopeId: string): boolean {
-  return obs.dshSessionIds?.includes(scopeId) === true;
-}
-
-/**
- * The store-backed observation view model. Holds the feed for the component
- * lifetime (refcounted — overlapping carriers never kill each other's
- * stream). `scopeId` narrows the view to one DSH conversation's sessions
- * (the better-sidebar tab); undefined keeps the global view (floating
- * card, PiP).
- */
-export function useObservationView(
-  store: ObservationClientStore,
-  scopeId?: string,
-): ObservationView {
-  const snapshot = useSyncExternalStore(store.subscribe, store.getSnapshot);
-  useEffect(() => {
-    store.acquire();
-    return () => store.release();
-  }, [store]);
-
-  const scopedSnapshot: OverlaySnapshot =
-    scopeId === undefined
-      ? snapshot
-      : {
-          ...snapshot,
-          sessions: snapshot.sessions.filter((s) => visibleToScope(s, scopeId)),
-        };
-
-  const [pinnedId, setPinnedId] = useState<string | null>(null);
-  const pinned =
-    pinnedId !== null ? scopedSnapshot.sessions.find((s) => s.sessionId === pinnedId) : undefined;
-  const focus = pinned ?? focusOf(scopedSnapshot.sessions);
-  const onTogglePin = useCallback((sessionId: string) => {
-    setPinnedId((current) => (current === sessionId ? null : sessionId));
-  }, []);
-
-  const anyActive = scopedSnapshot.sessions.some((s) => s.action !== "idle");
-  const [now, setNow] = useState(() => Date.now());
-  useEffect(() => {
-    if (!anyActive) return;
-    const timer = setInterval(() => setNow(Date.now()), 1000);
-    return () => clearInterval(timer);
-  }, [anyActive]);
-
-  return {
-    snapshot: scopedSnapshot,
-    focus,
-    pinnedId: pinned !== undefined ? pinnedId : null,
-    onTogglePin,
-    now,
-  };
-}
-
-export interface PipHandle {
-  /** The open PiP window, or null while the content renders in its carrier. */
-  readonly pipWindow: Window | null;
-  /** Whether the browser exposes Document PiP (Chrome-only today). */
-  readonly pipSupported: boolean;
-  /**
-   * Upgrade the content into a native PiP window. Rejects silently without a
-   * user gesture (or when closed mid-request): the carrier keeps the content.
-   */
-  readonly popOut: (size?: { width: number; height: number }) => void;
-}
-
-export function usePip(): PipHandle {
-  const [pipWindow, setPipWindow] = useState<Window | null>(null);
-  const popOut = useCallback((size?: { width: number; height: number }): void => {
-    const pip = pipApi();
-    if (pip === undefined) return;
-    void pip
-      .requestWindow(size)
-      .then((win) => {
-        cloneStylesInto(win);
-        win.addEventListener("pagehide", () => setPipWindow(null));
-        setPipWindow(win);
-      })
-      .catch(() => {});
-  }, []);
-  // Unmounting the carrier (tab close, conversation switch, plugin HMR) does
-  // not destroy the PiP browsing context: close it ourselves or it survives
-  // as a blank window. close() on an already-closed window is a no-op.
-  useEffect(() => () => pipWindow?.close(), [pipWindow]);
-  return { pipWindow, pipSupported: pipApi() !== undefined, popOut };
-}

packages/dsh-plugin-browserskill/src/client/sidebar-mode.ts

@@ -1,26 +0,0 @@
-/**
- * Carrier switch for the observation view: while the better-sidebar
- * integration fiber is alive (the dsh-better-sidebar plugin provides its
- * `betterSidebar` service), the tracking view lives in a sidebar tab and the
- * floating overlay card/capsule hides itself. The flag is a tiny external
- * store so the overlay can read it through useSyncExternalStore and flip
- * without a remount when the sidebar plugin (un)loads.
- */
-
-let active = false;
-const listeners = new Set<() => void>();
-
-export function getSidebarMode(): boolean {
-  return active;
-}
-
-export function subscribeSidebarMode(listener: () => void): () => void {
-  listeners.add(listener);
-  return () => listeners.delete(listener);
-}
-
-export function setSidebarMode(next: boolean): void {
-  if (active === next) return;
-  active = next;
-  for (const listener of [...listeners]) listener();
-}

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

@@ -12,14 +12,13 @@
 
 import type { Context } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { armArchiveCleanup } from "./archive-cleanup";
 import { armLazyTools } from "./lazy-tools";
 import { ObservationService } from "./observation";
 import { registerObservationRoutes } from "./observation-http";
 import { KeyedExecutor } from "./queue";
 import { type BskRunner, createBskRunner } from "./runner";
 import { SessionRegistry } from "./sessions";
-import { armAgentScopedBskSkill, registerBskSkill } from "./skill";
+import { registerBskSkill } from "./skill";
 import { type PluginConfig, registerTools } from "./tools";
 
 export const name = "dsh-plugin-browserskill";
@@ -95,11 +94,6 @@ export function apply(
   // ONLY model-visible advertisement — the tool suite reveals itself on a
   // successful skill invocation (or a session whose history already has one).
   const unregisterSkill = registerBskSkill(ctx);
-  // A same-name CLI skill left in ~/.agents is discovered in the nearer preset
-  // layer and shadows the global registration above. Re-register through every
-  // exact agent context at startup so DSH always loads the browser_* protocol
-  // instructions; the shared CLI skill remains untouched for other agents.
-  const disarmAgentSkill = armAgentScopedBskSkill(ctx);
   const removeSuite = resolved.lazyTools
     ? armLazyTools(ctx, () =>
         registerTools({ ctx, runner, registry, config: resolved, observation, queue }),
@@ -113,10 +107,6 @@ export function apply(
     removeRoutes = registerObservationRoutes(injected, observation);
     return () => removeRoutes();
   });
-  // Reap a conversation's browsers when the conversation itself is archived:
-  // archived sessions are hidden from every surface, so their Agent Windows
-  // would otherwise linger unreachable until idle timeout or unload.
-  const disarmArchiveCleanup = armArchiveCleanup(ctx, registry, observation);
 
   // Non-blocking install probe: warn early when bsk is missing instead of
   // failing the first tool call with a bare spawn error. Uses --version on
@@ -140,20 +130,20 @@ export function apply(
   ctx.effect(() => {
     return () => {
       removeSuite();
-      disarmAgentSkill();
       unregisterSkill();
       removeRoutes();
-      disarmArchiveCleanup();
+      observation.dispose();
       runner.killAll();
       const stops = registry
         .ownedIds()
-        .map((sessionId) => observation.stopSession(sessionId).catch(() => false));
-      return Promise.all(stops).then(() => observation.dispose());
+        .map((sessionId) =>
+          runner.run(["session", "stop", sessionId], { timeoutMs: 15_000 }).catch(() => {}),
+        );
+      return Promise.all(stops).then(() => {});
     };
   });
 }
 
-export { armArchiveCleanup, ownerSessionIds } from "./archive-cleanup";
 export type { ObservationEvent, ObservationOptions, SessionObservation } from "./observation";
 export { ObservationService } from "./observation";
 export { registerObservationRoutes } from "./observation-http";

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

@@ -1,6 +1,6 @@
 /**
  * Lazy tool-schema injection ("progressive disclosure", final stage): with
- * `lazyTools` on (the default), the 28 browser_* tool schemas stay OUT of the
+ * `lazyTools` on (the default), the 11 browser_* tool schemas stay OUT of the
  * system prompt until the `browser-skill` skill has actually been invoked —
  * the skill catalog entry is the only advertisement. One successful
  * invocation (model tool call, or a user's `/browser-skill` gesture) reveals
@@ -96,7 +96,7 @@ export function hasSuccessfulSkillInvocation(events: readonly SessionEventLike[]
 /**
  * Arm the lazy reveal. Returns a disposer tearing down listeners and — when
  * the reveal already happened — the tool suite itself.
- * @param registerSuite - registers the 28 browser_* tools, returns their disposer.
+ * @param registerSuite - registers the 11 browser_* tools, returns their disposer.
  */
 export function armLazyTools(ctx: Context, registerSuite: () => () => void): () => void {
   let suiteDisposer: (() => void) | undefined;

packages/dsh-plugin-browserskill/src/observation-http.ts

@@ -8,7 +8,6 @@
  *   GET  /bsk-observation/state      → { sessions, available }
  *   GET  /bsk-observation/events     → SSE stream of ObservationEvent
  *   POST /bsk-observation/interrupt  → body {sessionId?} → {interrupted: boolean}
- *   POST /bsk-observation/stop       → body {sessionId} → {stopped: boolean}
  *   GET  /bsk-observation/thumbnail/<attachmentId> → image bytes
  *
  * Routes exist only when a webServer service is mounted (web composition);
@@ -167,42 +166,6 @@ export function registerObservationRoutes(
         });
       },
     }),
-    webServer.register({
-      kind: "exact",
-      path: `${ROUTE_BASE}/stop`,
-      handler: (req, res) => {
-        if (req.method !== "POST") {
-          sendJson(res, 405, { error: "method not allowed" });
-          return;
-        }
-        if (fenceRejected(req, res)) return;
-        let body = "";
-        req.on("data", (chunk: Buffer | string) => {
-          body += chunk;
-        });
-        req.on("end", () => {
-          let sessionId: string | undefined;
-          try {
-            const parsed = JSON.parse(body || "{}") as { sessionId?: unknown };
-            if (typeof parsed.sessionId === "string" && parsed.sessionId !== "") {
-              sessionId = parsed.sessionId;
-            }
-          } catch {
-            sendJson(res, 400, { error: "invalid JSON body" });
-            return;
-          }
-          // A destructive call always names its target (never "current").
-          if (sessionId === undefined) {
-            sendJson(res, 400, { error: "sessionId required" });
-            return;
-          }
-          void observation.stopSession(sessionId).then(
-            (stopped) => sendJson(res, 200, { stopped }),
-            () => sendJson(res, 500, { error: "stop failed" }),
-          );
-        });
-      },
-    }),
     webServer.register({
       kind: "prefix",
       path: `${ROUTE_BASE}/thumbnail`,

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

@@ -18,7 +18,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Context } from "@deepseek-ai/cordis";
 import type { KeyedExecutor } from "./queue";
-import { BskError, type BskRunner, parseBskJson, runWithSessionBusyRetry } from "./runner";
+import type { BskRunner } from "./runner";
 import type { SessionRegistry } from "./sessions";
 
 /** One owned session's live observation record (wire-stable shape). */
@@ -39,13 +39,6 @@ export interface SessionObservation {
    * greys it out until it is stopped/removed. No more frames are requested.
    */
   dead?: boolean;
-  /**
-   * The DSH conversations this session belongs to (the starting agent's
-   * session plus its seed-lineage ancestors), recorded at start. Scoped
-   * surfaces (the better-sidebar tab) filter by it; absent means untracked
-   * ownership — visible only in the global (unscoped) view.
-   */
-  dshSessionIds?: string[];
 }
 
 /** Incremental event carried to subscribers (SSE on the wire). */
@@ -90,10 +83,6 @@ export class ObservationService {
   private readonly listeners = new Set<(event: ObservationEvent) => void>();
   private readonly captureTimers = new Map<string, unknown>();
   private readonly captureInFlight = new Set<string>();
-  /** Captures intentionally cancelled to make way for foreground work. */
-  private readonly capturePreempted = new Set<string>();
-  /** Number of queued/running model-facing calls that currently outrank thumbnails. */
-  private readonly foregroundDepth = new Map<string, number>();
   private readonly captureFailures = new Map<string, number>();
   private readonly lastActivity = new Map<string, number>();
   /** Ephemeral frame id → PNG bytes. Only the live ring members are present. */
@@ -164,13 +153,11 @@ export class ObservationService {
   /** Register a fresh owned session (called from browser_session_start). */
   addSession(sessionId: string, url?: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
-    const dshSessionIds = this.deps.registry.dshOwnersOf(sessionId);
     this.put({
       sessionId,
       ...(url !== undefined ? { url } : {}),
       action: "idle",
       since: this.scheduler.now(),
-      ...(dshSessionIds.length > 0 ? { dshSessionIds } : {}),
     });
     this.lastActivity.set(sessionId, this.scheduler.now());
     this.scheduleCapture(sessionId, 0);
@@ -179,8 +166,6 @@ export class ObservationService {
   /** Drop a session (called from browser_session_stop). */
   removeSession(sessionId: string): void {
     this.cancelCapture(sessionId);
-    this.foregroundDepth.delete(sessionId);
-    this.capturePreempted.delete(sessionId);
     this.captureFailures.delete(sessionId);
     this.lastActivity.delete(sessionId);
     this.dropSessionFrames(sessionId);
@@ -192,37 +177,6 @@ export class ObservationService {
     }
   }
 
-  /**
-   * Give model-facing work priority over the best-effort thumbnail lane.
-   * The first lease cancels a pending timer and gracefully interrupts an
-   * active bsk screenshot; the last release schedules one fresh frame.
-   */
-  acquireForeground(sessionId: string): () => void {
-    if (!this.deps.options.enabled || this.disposed || !this.observations.has(sessionId)) {
-      return () => {};
-    }
-    const depth = this.foregroundDepth.get(sessionId) ?? 0;
-    this.foregroundDepth.set(sessionId, depth + 1);
-    if (depth === 0) {
-      this.cancelCapture(sessionId);
-      if (this.deps.runner.killFor(`observation:${sessionId}`) > 0) {
-        this.capturePreempted.add(sessionId);
-      }
-    }
-    let released = false;
-    return () => {
-      if (released) return;
-      released = true;
-      const remaining = (this.foregroundDepth.get(sessionId) ?? 1) - 1;
-      if (remaining > 0) {
-        this.foregroundDepth.set(sessionId, remaining);
-        return;
-      }
-      this.foregroundDepth.delete(sessionId);
-      if (!this.disposed && this.observations.has(sessionId)) this.scheduleCapture(sessionId, 0);
-    };
-  }
-
   /** Mark an action starting on a session (tool entry instrumentation). */
   beginAction(sessionId: string, action: string): void {
     if (!this.deps.options.enabled || this.disposed) return;
@@ -250,7 +204,7 @@ export class ObservationService {
     if (error !== undefined) next.lastError = error;
     else delete next.lastError;
     this.put(next);
-    if (!this.foregroundDepth.has(sessionId)) this.scheduleCapture(sessionId, 0);
+    this.scheduleCapture(sessionId, 0);
   }
 
   /** Record the settled page URL (navigate success / start with url). */
@@ -274,55 +228,6 @@ export class ObservationService {
     return this.deps.runner.killFor(target) > 0;
   }
 
-  /**
-   * Stop one owned session and close its Agent Window (the overlay's stop
-   * button — same end state as `browser_session_stop`). Never waits behind a
-   * hung in-flight command: tool children are killed first so the session's
-   * keyed queue drains immediately, and no further captures queue up. A
-   * session the daemon already forgot stops idempotently — the goal state
-   * (entry gone) is identical.
-   * @returns false only for a foreign session; bsk failures reject so callers
-   * can preserve the structured error instead of silently leaving a ghost.
-   */
-  async stopSession(sessionId: string, signal?: AbortSignal): Promise<boolean> {
-    if (!this.deps.registry.isOwned(sessionId)) return false;
-    const releaseForeground = this.acquireForeground(sessionId);
-    let actionError: string | undefined;
-    this.beginAction(sessionId, "stopping");
-    try {
-      this.deps.runner.killFor(sessionId);
-      const result = await this.deps.queue.run(
-        sessionId,
-        () =>
-          runWithSessionBusyRetry(
-            () =>
-              this.deps.runner.run(["session", "stop", sessionId], {
-                signal,
-                timeoutMs: 30_000,
-                tag: sessionId,
-              }),
-            signal,
-          ),
-        signal,
-      );
-      if (result.aborted) throw abortError();
-      try {
-        parseBskJson(result, "session stop");
-      } catch (error) {
-        if (!isSessionNotFoundError(error)) throw error;
-      }
-      this.deps.registry.remove(sessionId);
-      this.removeSession(sessionId);
-      return true;
-    } catch (error) {
-      actionError = error instanceof Error ? error.message.split("\n")[0] : String(error);
-      throw error;
-    } finally {
-      this.endAction(sessionId, actionError);
-      releaseForeground();
-    }
-  }
-
   /**
    * Read one captured thumbnail from the in-process ring. Powers the plugin's
    * own HTTP thumbnail route — frames are plugin-owned runtime data, never
@@ -343,8 +248,6 @@ export class ObservationService {
     for (const sessionId of [...this.captureTimers.keys()]) this.cancelCapture(sessionId);
     this.captureTimers.clear();
     this.captureInFlight.clear();
-    this.capturePreempted.clear();
-    this.foregroundDepth.clear();
     this.captureFailures.clear();
     this.lastActivity.clear();
     this.frames.clear();
@@ -371,7 +274,6 @@ export class ObservationService {
   /** Schedule the next capture for a session; `delayMs` 0 means "as soon as the event loop allows". */
   private scheduleCapture(sessionId: string, delayMs?: number): void {
     if (!this.deps.options.enabled || this.disposed) return;
-    if (this.foregroundDepth.has(sessionId)) return;
     const entry = this.observations.get(sessionId);
     if (entry === undefined || entry.dead === true) return;
     this.cancelCapture(sessionId);
@@ -408,15 +310,12 @@ export class ObservationService {
     const outPath = join(tmpdir(), `bsk-obs-${this.scratchNamespace}-${sessionKey}.png`);
     let writtenPath = outPath;
     try {
-      const result = await this.deps.queue.run(sessionId, () => {
-        // A foreground lease may have arrived while this capture was queued.
-        if (this.foregroundDepth.has(sessionId)) return Promise.resolve(undefined);
-        return this.deps.runner.run(["screenshot", "--session", sessionId, "--out", outPath], {
+      const result = await this.deps.queue.run(sessionId, () =>
+        this.deps.runner.run(["screenshot", "--session", sessionId, "--out", outPath], {
           timeoutMs: 15_000,
           tag: `observation:${sessionId}`,
-        });
-      });
-      if (result === undefined) return;
+        }),
+      );
       if (result.code !== 0) {
         let code: string | undefined;
         try {
@@ -424,12 +323,8 @@ export class ObservationService {
         } catch {
           code = undefined;
         }
-        if (isSessionNotFoundCode(code)) {
-          // Observation entries are owned sessions. If the daemon has already
-          // forgotten one (external close / restart), reconcile both stores so
-          // the PiP cannot retain a ghost strip or keep retrying screenshots.
-          this.deps.registry.remove(sessionId);
-          this.removeSession(sessionId);
+        if (code === "session_not_found") {
+          this.markDead(sessionId);
           return;
         }
         throw new Error(`screenshot exited ${result.code}`);
@@ -444,17 +339,12 @@ export class ObservationService {
       this.setAvailable(true);
       this.publishFrame(sessionId, entry, data);
     } catch {
-      // Foreground preemption is healthy scheduling, not browser/daemon
-      // unavailability; do not let normal tool traffic trip capture backoff.
-      if (!this.capturePreempted.delete(sessionId)) {
-        // Silent by design: keep the previous frame, count toward backoff.
-        this.captureFailures.set(sessionId, (this.captureFailures.get(sessionId) ?? 0) + 1);
-        this.globalFailures += 1;
-        if (this.globalFailures >= FAILURE_BACKOFF_THRESHOLD) this.setAvailable(false);
-      }
+      // Silent by design: keep the previous frame, count toward backoff.
+      this.captureFailures.set(sessionId, (this.captureFailures.get(sessionId) ?? 0) + 1);
+      this.globalFailures += 1;
+      if (this.globalFailures >= FAILURE_BACKOFF_THRESHOLD) this.setAvailable(false);
     } finally {
       await unlink(writtenPath).catch(() => {});
-      this.capturePreempted.delete(sessionId);
       this.captureInFlight.delete(sessionId);
       if (!this.disposed && this.observations.has(sessionId)) this.scheduleCapture(sessionId);
     }
@@ -485,20 +375,14 @@ export class ObservationService {
     this.hashes.delete(sessionId);
     this.seqs.delete(sessionId);
   }
-}
 
-function isSessionNotFoundCode(code: string | undefined): boolean {
-  return code === "not_found" || code === "session_not_found";
-}
-
-function isSessionNotFoundError(error: unknown): boolean {
-  return error instanceof BskError && isSessionNotFoundCode(error.code);
-}
-
-function abortError(): Error {
-  const error = new Error("tool call aborted");
-  error.name = "AbortError";
-  return error;
+  /** Mark a session dead: grey it out, stop asking for frames, keep the entry for the strip. */
+  private markDead(sessionId: string): void {
+    const entry = this.observations.get(sessionId);
+    if (entry === undefined || entry.dead === true) return;
+    this.cancelCapture(sessionId);
+    this.put({ ...entry, dead: true, action: "idle" });
+  }
 }
 
 /** Map a bsk command label onto its observation action verb. */
@@ -516,48 +400,14 @@ export function actionForLabel(label: string): string {
       return "observing";
     case "click":
       return "clicking";
-    case "hover":
-      return "hovering";
     case "fill":
       return "filling";
-    case "select":
-      return "selecting";
     case "press":
       return "pressing";
     case "screenshot":
       return "capturing";
     case "emulate":
       return "emulating";
-    case "tab list":
-      return "listing tabs";
-    case "tab create":
-      return "creating tab";
-    case "tab close":
-      return "closing tab";
-    case "tab select":
-      return "selecting tab";
-    case "tab borrow":
-      return "borrowing tab";
-    case "tab return":
-      return "returning tab";
-    case "navigate-back":
-      return "navigating back";
-    case "navigate-forward":
-      return "navigating forward";
-    case "reload":
-      return "reloading";
-    case "wait-for-navigation":
-      return "waiting for navigation";
-    case "request-help":
-      return "waiting for user";
-    case "get-html":
-      return "reading HTML";
-    case "console":
-      return "reading console";
-    case "network":
-      return "reading network";
-    case "window resize":
-      return "resizing window";
     default:
       return label;
   }

packages/dsh-plugin-browserskill/src/phase-one-runtime.ts

@@ -1,58 +0,0 @@
-import type { ToolDefinition, ToolResult, ToolRunContext } from "@deepseek-ai/dsh-tools";
-import type { ToolDeps } from "./tools";
-
-export type ToolRegistrar = (definition: ToolDefinition) => () => void;
-
-type TerminalPresentation = { card: "terminal"; output: string; exitCode: number } | undefined;
-
-/** Existing tool runtime seams reused by the phase-one capability modules. */
-export interface PhaseOneRuntime {
-  run(
-    exec: ToolRunContext,
-    args: string[],
-    label: string,
-    observeSession?: string,
-    runnerTimeoutMs?: number,
-  ): Promise<unknown>;
-  commandLine(args: string[]): string;
-  presentTerminalResult: (_args: never, result: ToolResult) => TerminalPresentation;
-}
-
-export function requireNonEmpty(value: string, name: string): void {
-  if (value.trim().length === 0) throw new Error(`${name} must be a non-empty string`);
-}
-
-export function requirePositive(value: number | undefined, name: string): void {
-  if (value !== undefined && value <= 0) throw new Error(`${name} must be greater than zero`);
-}
-
-/** CLI positional target detection is shared by hover/select/request-help. */
-export function isSnapshotRef(target: string): boolean {
-  return /^@?e\d+$/.test(target);
-}
-
-/**
- * Give the child enough time to honour a command-level timeout plus IPC
- * settlement slack, without shortening the plugin's configured default.
- */
-export function runnerTimeout(deps: ToolDeps, commandTimeoutMs: number | undefined): number {
-  if (commandTimeoutMs === undefined) return deps.config.defaultTimeoutMs;
-  return Math.max(deps.config.defaultTimeoutMs, commandTimeoutMs + 15_000);
-}
-
-export function appendTarget(args: string[], target: string): void {
-  args.push(target);
-}
-
-export function appendTabId(args: string[], tabId: number | undefined): void {
-  if (tabId !== undefined) args.push("--tab-id", String(tabId));
-}
-
-export function appendWaitOptions(
-  args: string[],
-  waitUntil: string | undefined,
-  timeoutMs: number | undefined,
-): void {
-  if (waitUntil !== undefined) args.push("--wait-until", waitUntil);
-  if (timeoutMs !== undefined) args.push("--timeout", `${timeoutMs}ms`);
-}

packages/dsh-plugin-browserskill/src/phase-one-tools-interaction.ts

@@ -1,197 +0,0 @@
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import {
-  appendTabId,
-  appendTarget,
-  type PhaseOneRuntime,
-  requireNonEmpty,
-  requirePositive,
-  runnerTimeout,
-  type ToolRegistrar,
-} from "./phase-one-runtime";
-import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
-import type { ToolDeps } from "./tools";
-
-const MODIFIERS = ["alt", "ctrl", "meta", "shift"] as const;
-
-/** Add hover and select without bypassing session ownership or observation. */
-export function registerPhaseOneInteractionTools(
-  deps: ToolDeps,
-  register: ToolRegistrar,
-  runtime: PhaseOneRuntime,
-): void {
-  const { registry } = deps;
-
-  register(
-    defineTool({
-      name: "browser_hover",
-      description:
-        "Move the mouse over a snapshot ref or CSS selector to reveal hover-triggered UI. " +
-        "Run browser_observe or browser_snapshot again afterwards to discover newly visible refs.",
-      parameters: {
-        target: {
-          type: "string",
-          required: true,
-          description: "Snapshot ref (@e3 / e3) or CSS selector of the element to hover.",
-        },
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        modifiers: {
-          type: "array",
-          items: { type: "string", enum: MODIFIERS },
-          description: "Keyboard modifiers held during the mouse move.",
-        },
-        settleMs: {
-          type: "integer",
-          description: "Milliseconds to wait for hover-triggered UI to settle (default: 200).",
-        },
-        timeoutMs: TIMEOUT_MS_PARAM,
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            x: { type: "number", required: true },
-            y: { type: "number", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text: `[session ${value.session}] hovered at (${value.x}, ${value.y}) on tab ${value.tabId}`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        requireNonEmpty(args.target, "target");
-        requirePositive(args.timeoutMs, "timeoutMs");
-        requirePositive(args.settleMs, "settleMs");
-        const sessionId = registry.resolve(args.session, "browser_hover");
-        const cmdArgs = ["hover", "--session", sessionId];
-        appendTabId(cmdArgs, args.tabId);
-        if (args.modifiers !== undefined && args.modifiers.length > 0) {
-          cmdArgs.push("--modifiers", args.modifiers.join(","));
-        }
-        if (args.settleMs !== undefined) cmdArgs.push("--settle", `${args.settleMs}ms`);
-        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
-        appendTarget(cmdArgs, args.target);
-        const reply = (await runtime.run(
-          exec,
-          cmdArgs,
-          "hover",
-          sessionId,
-          runnerTimeout(deps, args.timeoutMs),
-        )) as { tab_id: number; x: number; y: number };
-        return { session: sessionId, tabId: reply.tab_id, x: reply.x, y: reply.y };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "hover",
-          args.target,
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Hover an element",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_select",
-      description:
-        "Set a select element's option values. Pass one value for a normal select or multiple " +
-        "values for a multi-select; values replace the current selection.",
-      parameters: {
-        target: {
-          type: "string",
-          required: true,
-          description: "Snapshot ref (@e3 / e3) or CSS selector of the select element.",
-        },
-        values: {
-          type: "array",
-          required: true,
-          items: { type: "string" },
-          description: "Option value attributes to select; at least one value is required.",
-        },
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        timeoutMs: TIMEOUT_MS_PARAM,
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            multiple: { type: "boolean", required: true },
-            selectedValues: {
-              type: "array",
-              required: true,
-              items: { type: "string" },
-            },
-            selectedLabels: {
-              type: "array",
-              required: true,
-              items: { type: "string" },
-            },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] selected ` +
-              `${value.selectedValues.join(", ") || "(none)"} on tab ${value.tabId}`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        requireNonEmpty(args.target, "target");
-        requirePositive(args.timeoutMs, "timeoutMs");
-        if (args.values.length === 0) throw new Error("values must contain at least one option");
-        const sessionId = registry.resolve(args.session, "browser_select");
-        const cmdArgs = ["select", "--session", sessionId];
-        appendTabId(cmdArgs, args.tabId);
-        for (const value of args.values) cmdArgs.push("--value", value);
-        if (args.timeoutMs !== undefined) cmdArgs.push("--timeout", `${args.timeoutMs}ms`);
-        appendTarget(cmdArgs, args.target);
-        const reply = (await runtime.run(
-          exec,
-          cmdArgs,
-          "select",
-          sessionId,
-          runnerTimeout(deps, args.timeoutMs),
-        )) as {
-          tab_id: number;
-          multiple: boolean;
-          selected_values: string[];
-          selected_labels: string[];
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          multiple: reply.multiple,
-          selectedValues: reply.selected_values,
-          selectedLabels: reply.selected_labels,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "select",
-          args.target,
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: `Select ${args.values.length} option${args.values.length === 1 ? "" : "s"}`,
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-}

packages/dsh-plugin-browserskill/src/phase-one-tools-navigation.ts

@@ -1,230 +0,0 @@
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import {
-  appendTabId,
-  appendWaitOptions,
-  type PhaseOneRuntime,
-  requirePositive,
-  runnerTimeout,
-  type ToolRegistrar,
-} from "./phase-one-runtime";
-import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM, WAIT_UNTIL_PARAM } from "./tool-params";
-import type { ToolDeps } from "./tools";
-
-interface RawHistoryResult {
-  tab_id: number;
-  previous_url?: string;
-  final_url?: string;
-  reached: string;
-  error_text?: string;
-}
-
-const HISTORY_OUTPUT = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    session: { type: "string", required: true },
-    tabId: { type: "integer", required: true },
-    previousUrl: { type: "string" },
-    finalUrl: { type: "string" },
-    reached: { type: "string", required: true },
-    errorText: { type: "string" },
-  },
-} as const;
-
-function mapHistory(sessionId: string, reply: RawHistoryResult) {
-  return {
-    session: sessionId,
-    tabId: reply.tab_id,
-    ...(reply.previous_url !== undefined ? { previousUrl: reply.previous_url } : {}),
-    ...(reply.final_url !== undefined ? { finalUrl: reply.final_url } : {}),
-    reached: reply.reached,
-    ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
-  };
-}
-
-/** Add browser history, reload, and explicit lifecycle waiting. */
-export function registerPhaseOneNavigationTools(
-  deps: ToolDeps,
-  register: ToolRegistrar,
-  runtime: PhaseOneRuntime,
-): void {
-  const { registry } = deps;
-
-  const registerHistory = (direction: "back" | "forward") => {
-    const toolName = `browser_navigate_${direction}` as const;
-    const command = `navigate-${direction}`;
-    register(
-      defineTool({
-        name: toolName,
-        description: `Navigate the active Agent Window tab ${direction} by one history entry.`,
-        parameters: {
-          session: SESSION_PARAM,
-          tabId: TAB_ID_PARAM,
-          waitUntil: WAIT_UNTIL_PARAM,
-          timeoutMs: TIMEOUT_MS_PARAM,
-        },
-        output: {
-          schema: HISTORY_OUTPUT,
-          render: (_args, value) => [
-            {
-              type: "text",
-              text:
-                `[session ${value.session}] navigated ${direction} on tab ${value.tabId}` +
-                (value.finalUrl !== undefined ? ` to ${value.finalUrl}` : "") +
-                ` (reached: ${value.reached})` +
-                (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
-            },
-          ],
-        },
-        async execute(args, exec) {
-          requirePositive(args.timeoutMs, "timeoutMs");
-          const sessionId = registry.resolve(args.session, toolName);
-          const cmdArgs = [command, "--session", sessionId];
-          appendTabId(cmdArgs, args.tabId);
-          appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
-          const reply = (await runtime.run(
-            exec,
-            cmdArgs,
-            command,
-            sessionId,
-            runnerTimeout(deps, args.timeoutMs),
-          )) as RawHistoryResult;
-          if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
-          return mapHistory(sessionId, reply);
-        },
-        presentCall: (args) => ({
-          card: "terminal",
-          title: runtime.commandLine([command, "--session", args.session ?? "(current)"]),
-          description: `Navigate ${direction}`,
-        }),
-        presentResult: runtime.presentTerminalResult,
-      }),
-    );
-  };
-  registerHistory("back");
-  registerHistory("forward");
-
-  register(
-    defineTool({
-      name: "browser_reload",
-      description:
-        "Reload the active Agent Window tab and wait for a lifecycle phase. Set hard=true to " +
-        "bypass the HTTP cache.",
-      parameters: {
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        waitUntil: WAIT_UNTIL_PARAM,
-        timeoutMs: TIMEOUT_MS_PARAM,
-        hard: { type: "boolean", description: "Bypass the HTTP cache while reloading." },
-      },
-      output: {
-        schema: HISTORY_OUTPUT,
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] reloaded tab ${value.tabId}` +
-              (value.finalUrl !== undefined ? ` at ${value.finalUrl}` : "") +
-              ` (reached: ${value.reached})` +
-              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
-          },
-        ],
-      },
-      async execute(args, exec) {
-        requirePositive(args.timeoutMs, "timeoutMs");
-        const sessionId = registry.resolve(args.session, "browser_reload");
-        const cmdArgs = ["reload", "--session", sessionId];
-        appendTabId(cmdArgs, args.tabId);
-        appendWaitOptions(cmdArgs, args.waitUntil, args.timeoutMs);
-        if (args.hard === true) cmdArgs.push("--hard");
-        const reply = (await runtime.run(
-          exec,
-          cmdArgs,
-          "reload",
-          sessionId,
-          runnerTimeout(deps, args.timeoutMs),
-        )) as RawHistoryResult;
-        if (reply.final_url !== undefined) deps.observation.setUrl(sessionId, reply.final_url);
-        return mapHistory(sessionId, reply);
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "reload",
-          "--session",
-          args.session ?? "(current)",
-          ...(args.hard === true ? ["--hard"] : []),
-        ]),
-        description: "Reload the active tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_wait_for_navigation",
-      description:
-        "Wait for a page lifecycle event on the active Agent Window tab. Use after an action " +
-        "that may navigate when the action result itself does not wait for navigation.",
-      parameters: {
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        waitUntil: WAIT_UNTIL_PARAM,
-        timeoutMs: TIMEOUT_MS_PARAM,
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            reached: { type: "string", required: true },
-            errorText: { type: "string" },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] navigation wait on tab ${value.tabId}: ${value.reached}` +
-              (value.errorText !== undefined ? ` — ${value.errorText}` : ""),
-          },
-        ],
-      },
-      async execute(args, exec) {
-        requirePositive(args.timeoutMs, "timeoutMs");
-        const sessionId = registry.resolve(args.session, "browser_wait_for_navigation");
-        const timeoutMs = args.timeoutMs ?? 30_000;
-        const cmdArgs = ["wait-for-navigation", "--session", sessionId];
-        appendTabId(cmdArgs, args.tabId);
-        if (args.waitUntil !== undefined) cmdArgs.push("--wait-until", args.waitUntil);
-        cmdArgs.push("--timeout", `${timeoutMs}ms`);
-        const reply = (await runtime.run(
-          exec,
-          cmdArgs,
-          "wait-for-navigation",
-          sessionId,
-          runnerTimeout(deps, timeoutMs),
-        )) as { tab_id: number; reached: string; error_text?: string };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          reached: reply.reached,
-          ...(reply.error_text !== undefined ? { errorText: reply.error_text } : {}),
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "wait-for-navigation",
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Wait for page navigation",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-}

packages/dsh-plugin-browserskill/src/phase-one-tools-support.ts

@@ -1,672 +0,0 @@
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import {
-  appendTabId,
-  isSnapshotRef,
-  type PhaseOneRuntime,
-  requireNonEmpty,
-  requirePositive,
-  runnerTimeout,
-  type ToolRegistrar,
-} from "./phase-one-runtime";
-import { SESSION_PARAM, TAB_ID_PARAM, TIMEOUT_MS_PARAM } from "./tool-params";
-import type { ToolDeps } from "./tools";
-
-interface HelpConditionInput {
-  urlContains?: string;
-  urlMatches?: string;
-  selectorExists?: string;
-  selectorMissing?: string;
-  textExists?: string;
-  textMissing?: string;
-}
-
-interface CompletionCriteriaInput {
-  any?: HelpConditionInput[];
-  all?: HelpConditionInput[];
-  stableForMs?: number;
-}
-
-interface RawConsoleFrame {
-  function_name?: string;
-  url?: string;
-  line?: number;
-  column?: number;
-}
-
-interface RawConsoleEntry {
-  sequence: number;
-  kind: string;
-  level: string;
-  text: string;
-  url?: string;
-  line?: number;
-  column?: number;
-  timestamp?: number;
-  stack_trace?: RawConsoleFrame[];
-  truncated?: boolean;
-}
-
-interface RawNetworkEntry {
-  sequence: number;
-  kind: "response" | "failure";
-  method?: string;
-  url?: string;
-  status?: number;
-  status_text?: string;
-  mime_type?: string;
-  resource_type?: string;
-  error_text?: string;
-  timestamp?: number;
-  truncated?: boolean;
-}
-
-const HELP_CONDITION_SCHEMA = {
-  type: "object",
-  additionalProperties: false,
-  properties: {
-    urlContains: { type: "string" },
-    urlMatches: { type: "string" },
-    selectorExists: { type: "string" },
-    selectorMissing: { type: "string" },
-    textExists: { type: "string" },
-    textMissing: { type: "string" },
-  },
-} as const;
-
-const DEBUG_PARAMETERS = {
-  session: SESSION_PARAM,
-  tabId: TAB_ID_PARAM,
-  since: {
-    type: "integer",
-    description: "Return entries with a sequence strictly greater than this cursor.",
-  },
-  limit: {
-    type: "integer",
-    description: "Maximum entries to return (default: 50, daemon cap: 200).",
-  },
-  maxTextChars: {
-    type: "integer",
-    description: "Maximum characters per entry text/URL (default: 1000, daemon cap: 4096).",
-  },
-} as const;
-
-function mapCondition(condition: HelpConditionInput) {
-  return {
-    ...(condition.urlContains !== undefined ? { url_contains: condition.urlContains } : {}),
-    ...(condition.urlMatches !== undefined ? { url_matches: condition.urlMatches } : {}),
-    ...(condition.selectorExists !== undefined
-      ? { selector_exists: condition.selectorExists }
-      : {}),
-    ...(condition.selectorMissing !== undefined
-      ? { selector_missing: condition.selectorMissing }
-      : {}),
-    ...(condition.textExists !== undefined ? { text_exists: condition.textExists } : {}),
-    ...(condition.textMissing !== undefined ? { text_missing: condition.textMissing } : {}),
-  };
-}
-
-function mapCompletionCriteria(criteria: CompletionCriteriaInput) {
-  return {
-    ...(criteria.any !== undefined ? { any: criteria.any.map(mapCondition) } : {}),
-    ...(criteria.all !== undefined ? { all: criteria.all.map(mapCondition) } : {}),
-    ...(criteria.stableForMs !== undefined ? { stable_for_ms: criteria.stableForMs } : {}),
-  };
-}
-
-function validateDebugArgs(args: { since?: number; limit?: number; maxTextChars?: number }): void {
-  if (args.since !== undefined && args.since < 0) {
-    throw new Error("since must be zero or greater");
-  }
-  requirePositive(args.limit, "limit");
-  requirePositive(args.maxTextChars, "maxTextChars");
-}
-
-function appendDebugOptions(
-  args: string[],
-  options: { tabId?: number; since?: number; limit?: number; maxTextChars?: number },
-): void {
-  appendTabId(args, options.tabId);
-  if (options.since !== undefined) args.push("--since", String(options.since));
-  if (options.limit !== undefined) args.push("--limit", String(options.limit));
-  if (options.maxTextChars !== undefined) {
-    args.push("--max-text-chars", String(options.maxTextChars));
-  }
-}
-
-/** Human help, raw HTML, diagnostics, and Agent Window sizing. */
-export function registerPhaseOneSupportTools(
-  deps: ToolDeps,
-  register: ToolRegistrar,
-  runtime: PhaseOneRuntime,
-): void {
-  const { registry } = deps;
-
-  register(
-    defineTool({
-      name: "browser_request_help",
-      description:
-        "Pause browser automation and ask the user to complete an in-page step such as login, " +
-        "captcha, OTP, or confirmation. After continued/completed, observe again before using refs.",
-      parameters: {
-        prompt: {
-          type: "string",
-          required: true,
-          description: "Clear instructions shown to the user in the browser help overlay.",
-        },
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        title: { type: "string", description: "Optional title for the help overlay." },
-        targets: {
-          type: "array",
-          items: { type: "string" },
-          description: "Snapshot refs or CSS selectors to scroll to and highlight for the user.",
-        },
-        timeoutMs: {
-          ...TIMEOUT_MS_PARAM,
-          description: "Maximum wait for the user in milliseconds (default: 300000).",
-        },
-        completionCriteria: {
-          type: "object",
-          additionalProperties: false,
-          description: "Optional explicit success detector for automatic completion.",
-          properties: {
-            any: { type: "array", items: HELP_CONDITION_SCHEMA },
-            all: { type: "array", items: HELP_CONDITION_SCHEMA },
-            stableForMs: {
-              type: "integer",
-              description: "How long criteria must remain true before completing.",
-            },
-          },
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            outcome: {
-              type: "string",
-              required: true,
-              enum: ["continued", "cancelled", "timed_out", "completed", "navigated", "disabled"],
-            },
-            completedBy: { type: "string" },
-            note: { type: "string" },
-            resolvedTargets: {
-              type: "array",
-              items: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  matched: { type: "boolean", required: true },
-                  ref: { type: "string" },
-                  selector: { type: "string" },
-                },
-              },
-            },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] user help outcome on tab ${value.tabId}: ${value.outcome}` +
-              (value.note !== undefined ? ` — ${value.note}` : "") +
-              (value.resolvedTargets !== undefined
-                ? `\ntargets: ${value.resolvedTargets
-                    .map(
-                      (target) =>
-                        `${target.ref ?? target.selector ?? "(unknown)"}=${target.matched ? "matched" : "not found"}`,
-                    )
-                    .join(", ")}`
-                : ""),
-          },
-        ],
-      },
-      async execute(args, exec) {
-        requireNonEmpty(args.prompt, "prompt");
-        if (args.title !== undefined) requireNonEmpty(args.title, "title");
-        requirePositive(args.timeoutMs, "timeoutMs");
-        for (const target of args.targets ?? []) requireNonEmpty(target, "target");
-        const criteria = args.completionCriteria as CompletionCriteriaInput | undefined;
-        if (criteria?.stableForMs !== undefined && criteria.stableForMs < 0) {
-          throw new Error("completionCriteria.stableForMs must be zero or greater");
-        }
-        const sessionId = registry.resolve(args.session, "browser_request_help");
-        const timeoutMs = args.timeoutMs ?? 300_000;
-        const cmdArgs = [
-          "request-help",
-          "--session",
-          sessionId,
-          "--prompt",
-          args.prompt,
-          "--timeout",
-          `${timeoutMs}ms`,
-        ];
-        appendTabId(cmdArgs, args.tabId);
-        if (args.title !== undefined) cmdArgs.push("--title", args.title);
-        for (const target of args.targets ?? []) cmdArgs.push("--target", target);
-        if (criteria !== undefined) {
-          cmdArgs.push("--completion-criteria", JSON.stringify(mapCompletionCriteria(criteria)));
-        }
-        const reply = (await runtime.run(
-          exec,
-          cmdArgs,
-          "request-help",
-          sessionId,
-          runnerTimeout(deps, timeoutMs),
-        )) as {
-          outcome: "continued" | "cancelled" | "timed_out" | "completed" | "navigated" | "disabled";
-          completed_by?: string;
-          note?: string;
-          tab_id: number;
-          resolved_targets?: { matched: boolean; ref?: string; selector?: string }[];
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          outcome: reply.outcome,
-          ...(reply.completed_by !== undefined ? { completedBy: reply.completed_by } : {}),
-          ...(reply.note !== undefined ? { note: reply.note } : {}),
-          ...(reply.resolved_targets !== undefined
-            ? { resolvedTargets: reply.resolved_targets }
-            : {}),
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine(["request-help", "--session", args.session ?? "(current)"]),
-        description: "Ask the user for browser help",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_get_html",
-      description:
-        "Read raw DOM HTML from the active Agent Window tab, optionally scoped to a fresh " +
-        "snapshot ref. Use only when browser_observe/browser_snapshot cannot answer the question.",
-      parameters: {
-        session: SESSION_PARAM,
-        tabId: TAB_ID_PARAM,
-        ref: { type: "string", description: "Fresh snapshot ref that scopes the HTML subtree." },
-        maxBytes: {
-          type: "integer",
-          description: "Maximum returned HTML bytes before truncation (default: 524288).",
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            html: { type: "string", required: true },
-            truncated: { type: "boolean", required: true },
-            byteSize: { type: "integer", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              value.html +
-              (value.truncated ? `\n(HTML truncated; original size ${value.byteSize} bytes)` : ""),
-          },
-        ],
-      },
-      isConcurrencySafe: () => true,
-      async execute(args, exec) {
-        if (args.ref !== undefined) {
-          requireNonEmpty(args.ref, "ref");
-          if (!isSnapshotRef(args.ref)) throw new Error("ref must be a snapshot ref such as @e3");
-        }
-        requirePositive(args.maxBytes, "maxBytes");
-        const sessionId = registry.resolve(args.session, "browser_get_html");
-        const cmdArgs = ["get-html", "--session", sessionId];
-        appendTabId(cmdArgs, args.tabId);
-        if (args.ref !== undefined) cmdArgs.push("--ref", args.ref);
-        if (args.maxBytes !== undefined) cmdArgs.push("--max-bytes", String(args.maxBytes));
-        const reply = (await runtime.run(exec, cmdArgs, "get-html", sessionId)) as {
-          tab_id: number;
-          html: string;
-          truncated?: boolean;
-          byte_size: number;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          html: reply.html,
-          truncated: reply.truncated ?? false,
-          byteSize: reply.byte_size,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "get-html",
-          "--session",
-          args.session ?? "(current)",
-          ...(args.ref !== undefined ? ["--ref", args.ref] : []),
-        ]),
-        description: "Read raw page HTML",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_console",
-      description:
-        "Read buffered console messages, browser log entries, and JavaScript exceptions from a tab. " +
-        "This is read-only and does not evaluate JavaScript.",
-      parameters: {
-        ...DEBUG_PARAMETERS,
-        includeStack: {
-          type: "boolean",
-          description: "Include structured stack frames in returned console entries.",
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            entries: {
-              type: "array",
-              required: true,
-              items: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  sequence: { type: "integer", required: true },
-                  kind: { type: "string", required: true },
-                  level: { type: "string", required: true },
-                  text: { type: "string", required: true },
-                  url: { type: "string" },
-                  line: { type: "integer" },
-                  column: { type: "integer" },
-                  timestamp: { type: "number" },
-                  stackTrace: {
-                    type: "array",
-                    required: true,
-                    items: {
-                      type: "object",
-                      additionalProperties: false,
-                      properties: {
-                        functionName: { type: "string" },
-                        url: { type: "string" },
-                        line: { type: "integer" },
-                        column: { type: "integer" },
-                      },
-                    },
-                  },
-                  truncated: { type: "boolean", required: true },
-                },
-              },
-            },
-            nextSince: { type: "integer", required: true },
-            truncated: { type: "boolean", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              value.entries.length === 0
-                ? "(no console messages captured)"
-                : value.entries
-                    .map((entry) => {
-                      const location =
-                        entry.url === undefined
-                          ? ""
-                          : ` ${entry.url}${entry.line !== undefined ? `:${entry.line}` : ""}${entry.column !== undefined ? `:${entry.column}` : ""}`;
-                      const stack = entry.stackTrace
-                        .map(
-                          (frame) =>
-                            `\n  at ${frame.functionName ?? "<anonymous>"} ${frame.url ?? ""}` +
-                            `${frame.line !== undefined ? `:${frame.line}` : ""}` +
-                            `${frame.column !== undefined ? `:${frame.column}` : ""}`,
-                        )
-                        .join("");
-                      return `#${entry.sequence} ${entry.level} ${entry.kind}${location} ${entry.text}${stack}`;
-                    })
-                    .join("\n") +
-                  (value.truncated
-                    ? `\n(output truncated; continue with since=${value.nextSince})`
-                    : ""),
-          },
-        ],
-      },
-      isConcurrencySafe: () => true,
-      async execute(args, exec) {
-        validateDebugArgs(args);
-        const sessionId = registry.resolve(args.session, "browser_console");
-        const cmdArgs = ["console", "--session", sessionId];
-        appendDebugOptions(cmdArgs, args);
-        if (args.includeStack === true) cmdArgs.push("--include-stack");
-        const reply = (await runtime.run(exec, cmdArgs, "console", sessionId)) as {
-          tab_id: number;
-          entries?: RawConsoleEntry[];
-          next_since: number;
-          truncated?: boolean;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          entries: (reply.entries ?? []).map((entry) => ({
-            sequence: entry.sequence,
-            kind: entry.kind,
-            level: entry.level,
-            text: entry.text,
-            ...(entry.url !== undefined ? { url: entry.url } : {}),
-            ...(entry.line !== undefined ? { line: entry.line } : {}),
-            ...(entry.column !== undefined ? { column: entry.column } : {}),
-            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
-            stackTrace: (entry.stack_trace ?? []).map((frame) => ({
-              ...(frame.function_name !== undefined ? { functionName: frame.function_name } : {}),
-              ...(frame.url !== undefined ? { url: frame.url } : {}),
-              ...(frame.line !== undefined ? { line: frame.line } : {}),
-              ...(frame.column !== undefined ? { column: frame.column } : {}),
-            })),
-            truncated: entry.truncated ?? false,
-          })),
-          nextSince: reply.next_since,
-          truncated: reply.truncated ?? false,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine(["console", "--session", args.session ?? "(current)"]),
-        description: "Read browser console messages",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_network",
-      description:
-        "Read buffered network responses and failures from a tab. Returns metadata only; request " +
-        "and response headers and bodies are not captured.",
-      parameters: DEBUG_PARAMETERS,
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            entries: {
-              type: "array",
-              required: true,
-              items: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  sequence: { type: "integer", required: true },
-                  kind: { type: "string", required: true, enum: ["response", "failure"] },
-                  method: { type: "string" },
-                  url: { type: "string" },
-                  status: { type: "integer" },
-                  statusText: { type: "string" },
-                  mimeType: { type: "string" },
-                  resourceType: { type: "string" },
-                  errorText: { type: "string" },
-                  timestamp: { type: "number" },
-                  truncated: { type: "boolean", required: true },
-                },
-              },
-            },
-            nextSince: { type: "integer", required: true },
-            truncated: { type: "boolean", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              value.entries.length === 0
-                ? "(no network activity captured)"
-                : value.entries
-                    .map((entry) =>
-                      entry.kind === "failure"
-                        ? `#${entry.sequence} FAILED ${entry.method ?? "?"} ${entry.url ?? "(unknown)"} — ${entry.errorText ?? "failed"}`
-                        : `#${entry.sequence} ${entry.status ?? "?"} ${entry.method ?? "?"} ${entry.url ?? "(unknown)"}`,
-                    )
-                    .join("\n") +
-                  (value.truncated
-                    ? `\n(output truncated; continue with since=${value.nextSince})`
-                    : ""),
-          },
-        ],
-      },
-      isConcurrencySafe: () => true,
-      async execute(args, exec) {
-        validateDebugArgs(args);
-        const sessionId = registry.resolve(args.session, "browser_network");
-        const cmdArgs = ["network", "--session", sessionId];
-        appendDebugOptions(cmdArgs, args);
-        const reply = (await runtime.run(exec, cmdArgs, "network", sessionId)) as {
-          tab_id: number;
-          entries?: RawNetworkEntry[];
-          next_since: number;
-          truncated?: boolean;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          entries: (reply.entries ?? []).map((entry) => ({
-            sequence: entry.sequence,
-            kind: entry.kind,
-            ...(entry.method !== undefined ? { method: entry.method } : {}),
-            ...(entry.url !== undefined ? { url: entry.url } : {}),
-            ...(entry.status !== undefined ? { status: entry.status } : {}),
-            ...(entry.status_text !== undefined ? { statusText: entry.status_text } : {}),
-            ...(entry.mime_type !== undefined ? { mimeType: entry.mime_type } : {}),
-            ...(entry.resource_type !== undefined ? { resourceType: entry.resource_type } : {}),
-            ...(entry.error_text !== undefined ? { errorText: entry.error_text } : {}),
-            ...(entry.timestamp !== undefined ? { timestamp: entry.timestamp } : {}),
-            truncated: entry.truncated ?? false,
-          })),
-          nextSince: reply.next_since,
-          truncated: reply.truncated ?? false,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine(["network", "--session", args.session ?? "(current)"]),
-        description: "Read browser network activity",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_window_resize",
-      description: "Resize the owned session's Agent Window using outer CSS-pixel dimensions.",
-      parameters: {
-        width: {
-          type: "integer",
-          required: true,
-          description: "Agent Window outer width in CSS pixels (100..=7680).",
-        },
-        height: {
-          type: "integer",
-          required: true,
-          description: "Agent Window outer height in CSS pixels (100..=7680).",
-        },
-        session: SESSION_PARAM,
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            windowId: { type: "integer", required: true },
-            width: { type: "integer", required: true },
-            height: { type: "integer", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text: `[session ${value.session}] resized window ${value.windowId} to ${value.width}x${value.height}`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        if (args.width < 100 || args.width > 7680 || args.height < 100 || args.height > 7680) {
-          throw new Error("width and height must each be in the range 100..=7680");
-        }
-        const sessionId = registry.resolve(args.session, "browser_window_resize");
-        const reply = (await runtime.run(
-          exec,
-          [
-            "window",
-            "resize",
-            "--session",
-            sessionId,
-            "--width",
-            String(args.width),
-            "--height",
-            String(args.height),
-          ],
-          "window resize",
-          sessionId,
-        )) as { window_id: number; width: number; height: number };
-        return {
-          session: sessionId,
-          windowId: reply.window_id,
-          width: reply.width,
-          height: reply.height,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "window",
-          "resize",
-          "--session",
-          args.session ?? "(current)",
-          "--width",
-          String(args.width),
-          "--height",
-          String(args.height),
-        ]),
-        description: "Resize the Agent Window",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-}

packages/dsh-plugin-browserskill/src/phase-one-tools-tabs.ts

@@ -1,402 +0,0 @@
-import { defineTool } from "@deepseek-ai/dsh-tools";
-import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
-import { requireNonEmpty } from "./phase-one-runtime";
-import { SESSION_PARAM } from "./tool-params";
-import type { ToolDeps } from "./tools";
-
-const TAB_ID_REQUIRED = {
-  type: "integer",
-  required: true,
-  description: "Chrome tab id returned by browser_tab_list or browser_tab_create.",
-} as const;
-
-interface RawTabInfo {
-  tab_id: number;
-  title?: string;
-  url?: string;
-  window_id?: number;
-  active?: boolean;
-  scope?: "user" | "agent";
-}
-
-/** Add Agent Window tab management while preserving the owned-session boundary. */
-export function registerPhaseOneTabTools(
-  deps: ToolDeps,
-  register: ToolRegistrar,
-  runtime: PhaseOneRuntime,
-): void {
-  const { registry } = deps;
-
-  register(
-    defineTool({
-      name: "browser_tab_list",
-      description:
-        "List tabs visible to an owned browser session. Other sessions' Agent Windows remain " +
-        "hidden; use scope=user to find a user tab before borrowing it.",
-      parameters: {
-        session: SESSION_PARAM,
-        scope: {
-          type: "string",
-          enum: ["user", "agent", "all"],
-          description: "Which tabs to list (default: all).",
-        },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabs: {
-              type: "array",
-              required: true,
-              items: {
-                type: "object",
-                additionalProperties: false,
-                properties: {
-                  tabId: { type: "integer", required: true },
-                  title: { type: "string" },
-                  url: { type: "string" },
-                  windowId: { type: "integer" },
-                  active: { type: "boolean" },
-                  scope: { type: "string", enum: ["user", "agent"] },
-                },
-              },
-            },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              value.tabs.length === 0
-                ? `[session ${value.session}] no matching tabs`
-                : value.tabs
-                    .map(
-                      (tab) =>
-                        `${tab.tabId} [${tab.scope ?? "unknown"}]${tab.active === true ? " [active]" : ""} ` +
-                        `${tab.title ?? "(untitled)"} — ${tab.url ?? "(unknown URL)"}`,
-                    )
-                    .join("\n"),
-          },
-        ],
-      },
-      isConcurrencySafe: () => true,
-      async execute(args, exec) {
-        const sessionId = registry.resolve(args.session, "browser_tab_list");
-        const cmdArgs = ["tab", "list", "--session", sessionId];
-        if (args.scope !== undefined) cmdArgs.push("--scope", args.scope);
-        const reply = (await runtime.run(exec, cmdArgs, "tab list", sessionId)) as {
-          tabs: RawTabInfo[];
-        };
-        return {
-          session: sessionId,
-          tabs: reply.tabs.map((tab) => ({
-            tabId: tab.tab_id,
-            ...(tab.title !== undefined ? { title: tab.title } : {}),
-            ...(tab.url !== undefined ? { url: tab.url } : {}),
-            ...(tab.window_id !== undefined ? { windowId: tab.window_id } : {}),
-            ...(tab.active !== undefined ? { active: tab.active } : {}),
-            ...(tab.scope !== undefined ? { scope: tab.scope } : {}),
-          })),
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "list",
-          "--session",
-          args.session ?? "(current)",
-          ...(args.scope !== undefined ? ["--scope", args.scope] : []),
-        ]),
-        description: "List browser tabs",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_tab_create",
-      description:
-        "Create a tab inside the owned session's Agent Window. The tab is focused by default; " +
-        "set active=false to open it in the background.",
-      parameters: {
-        session: SESSION_PARAM,
-        url: { type: "string", description: "Initial URL (default: chrome://newtab/)." },
-        active: { type: "boolean", description: "Whether to focus the new tab (default: true)." },
-        index: { type: "integer", description: "Insertion index in the Agent Window tab strip." },
-      },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            windowId: { type: "integer", required: true },
-            url: { type: "string", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text: `[session ${value.session}] created tab ${value.tabId} in window ${value.windowId} (${value.url || "pending URL"})`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        if (args.url !== undefined) requireNonEmpty(args.url, "url");
-        const sessionId = registry.resolve(args.session, "browser_tab_create");
-        const cmdArgs = ["tab", "create", "--session", sessionId];
-        if (args.url !== undefined) cmdArgs.push("--url", args.url);
-        if (args.active === false) cmdArgs.push("--no-active");
-        if (args.index !== undefined) cmdArgs.push("--index", String(args.index));
-        const reply = (await runtime.run(exec, cmdArgs, "tab create", sessionId)) as {
-          tab_id: number;
-          window_id: number;
-          url: string;
-        };
-        if (args.active !== false && reply.url.length > 0) {
-          deps.observation.setUrl(sessionId, reply.url);
-        }
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          windowId: reply.window_id,
-          url: reply.url,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "create",
-          "--session",
-          args.session ?? "(current)",
-          ...(args.url !== undefined ? ["--url", args.url] : []),
-        ]),
-        description: "Create an Agent Window tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_tab_close",
-      description: "Close a tab in the owned session's Agent Window.",
-      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-          },
-        },
-        render: (_args, value) => [
-          { type: "text", text: `[session ${value.session}] closed tab ${value.tabId}` },
-        ],
-      },
-      async execute(args, exec) {
-        const sessionId = registry.resolve(args.session, "browser_tab_close");
-        const reply = (await runtime.run(
-          exec,
-          ["tab", "close", String(args.tabId), "--session", sessionId],
-          "tab close",
-          sessionId,
-        )) as { tab_id: number };
-        return { session: sessionId, tabId: reply.tab_id };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "close",
-          String(args.tabId),
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Close an Agent Window tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_tab_select",
-      description: "Focus a tab in the owned session's Agent Window.",
-      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            windowId: { type: "integer", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text: `[session ${value.session}] selected tab ${value.tabId} in window ${value.windowId}`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        const sessionId = registry.resolve(args.session, "browser_tab_select");
-        const reply = (await runtime.run(
-          exec,
-          ["tab", "select", String(args.tabId), "--session", sessionId],
-          "tab select",
-          sessionId,
-        )) as { tab_id: number; window_id: number };
-        return { session: sessionId, tabId: reply.tab_id, windowId: reply.window_id };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "select",
-          String(args.tabId),
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Select an Agent Window tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_tab_borrow",
-      description:
-        "Move a user-window tab into the owned session's Agent Window for controlled interaction. " +
-        "Return it with browser_tab_return when finished; stopping the session also auto-returns it.",
-      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            originalWindowId: { type: "integer", required: true },
-            originalIndex: { type: "integer", required: true },
-            agentWindowId: { type: "integer", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] borrowed tab ${value.tabId} from window ` +
-              `${value.originalWindowId} into Agent Window ${value.agentWindowId}`,
-          },
-        ],
-      },
-      async execute(args, exec) {
-        const sessionId = registry.resolve(args.session, "browser_tab_borrow");
-        const reply = (await runtime.run(
-          exec,
-          ["tab", "borrow", String(args.tabId), "--session", sessionId],
-          "tab borrow",
-          sessionId,
-        )) as {
-          tab_id: number;
-          original_window_id: number;
-          original_index: number;
-          agent_window_id: number;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          originalWindowId: reply.original_window_id,
-          originalIndex: reply.original_index,
-          agentWindowId: reply.agent_window_id,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "borrow",
-          String(args.tabId),
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Borrow a user tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-
-  register(
-    defineTool({
-      name: "browser_tab_return",
-      description: "Return a borrowed tab to its original user window and tab-strip position.",
-      parameters: { tabId: TAB_ID_REQUIRED, session: SESSION_PARAM },
-      output: {
-        schema: {
-          type: "object",
-          additionalProperties: false,
-          properties: {
-            session: { type: "string", required: true },
-            tabId: { type: "integer", required: true },
-            returnedToWindowId: { type: "integer", required: true },
-            returnedToIndex: { type: "integer", required: true },
-            fallback: { type: "boolean", required: true },
-          },
-        },
-        render: (_args, value) => [
-          {
-            type: "text",
-            text:
-              `[session ${value.session}] returned tab ${value.tabId} to window ` +
-              `${value.returnedToWindowId} at index ${value.returnedToIndex}` +
-              (value.fallback ? " (original window unavailable; used fallback)" : ""),
-          },
-        ],
-      },
-      async execute(args, exec) {
-        const sessionId = registry.resolve(args.session, "browser_tab_return");
-        const reply = (await runtime.run(
-          exec,
-          ["tab", "return", String(args.tabId), "--session", sessionId],
-          "tab return",
-          sessionId,
-        )) as {
-          tab_id: number;
-          returned_to_window_id: number;
-          returned_to_index: number;
-          fallback?: boolean;
-        };
-        return {
-          session: sessionId,
-          tabId: reply.tab_id,
-          returnedToWindowId: reply.returned_to_window_id,
-          returnedToIndex: reply.returned_to_index,
-          fallback: reply.fallback ?? false,
-        };
-      },
-      presentCall: (args) => ({
-        card: "terminal",
-        title: runtime.commandLine([
-          "tab",
-          "return",
-          String(args.tabId),
-          "--session",
-          args.session ?? "(current)",
-        ]),
-        description: "Return a borrowed tab",
-      }),
-      presentResult: runtime.presentTerminalResult,
-    }),
-  );
-}

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

@@ -1,18 +0,0 @@
-import type { PhaseOneRuntime, ToolRegistrar } from "./phase-one-runtime";
-import { registerPhaseOneInteractionTools } from "./phase-one-tools-interaction";
-import { registerPhaseOneNavigationTools } from "./phase-one-tools-navigation";
-import { registerPhaseOneSupportTools } from "./phase-one-tools-support";
-import { registerPhaseOneTabTools } from "./phase-one-tools-tabs";
-import type { ToolDeps } from "./tools";
-
-/** Register the first DSH capability-parity tranche on the existing runtime. */
-export function registerPhaseOneTools(
-  deps: ToolDeps,
-  register: ToolRegistrar,
-  runtime: PhaseOneRuntime,
-): void {
-  registerPhaseOneInteractionTools(deps, register, runtime);
-  registerPhaseOneTabTools(deps, register, runtime);
-  registerPhaseOneNavigationTools(deps, register, runtime);
-  registerPhaseOneSupportTools(deps, register, runtime);
-}

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

@@ -64,17 +64,14 @@ export interface BskRunner {
   killFor(tag: string): number;
 }
 
-// Business RPCs translate SIGINT into the daemon's cancel(rpc_id) protocol.
-// Give that bounded reconciliation path time to settle before the hard kill.
-const KILL_GRACE_MS = 3000;
-const SESSION_BUSY_RETRY_DELAY_MS = 100;
+const KILL_GRACE_MS = 2000;
 
 export function createBskRunner(bskPath: string, spawnImpl: SpawnImpl = spawn): BskRunner {
   const live = new Map<ChildProcess, string | undefined>();
 
   function killChild(child: ChildProcess): void {
     if (child.exitCode !== null || child.signalCode !== null) return;
-    child.kill("SIGINT");
+    child.kill("SIGTERM");
     const force = setTimeout(() => {
       if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
     }, KILL_GRACE_MS);
@@ -166,60 +163,6 @@ export function isCommandNotFound(error: unknown): boolean {
   );
 }
 
-/** True only for the daemon's transient per-session reconciliation window. */
-export function isSessionBusyResult(result: BskRunResult): boolean {
-  if (result.code === 0) return false;
-  try {
-    const body = JSON.parse(result.stdout) as BskErrorBody;
-    const reason =
-      typeof body.data === "object" && body.data !== null && "reason" in body.data
-        ? (body.data as { reason?: unknown }).reason
-        : undefined;
-    return reason === "session_busy";
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Retry exactly once after the tiny daemon-settlement race that can follow a
- * graceful SIGINT cancellation. Other errors and persistent busy states stay
- * visible to callers.
- */
-export async function runWithSessionBusyRetry(
-  run: () => Promise<BskRunResult>,
-  signal?: AbortSignal,
-): Promise<BskRunResult> {
-  const first = await run();
-  if (!isSessionBusyResult(first)) return first;
-  await abortableDelay(SESSION_BUSY_RETRY_DELAY_MS, signal);
-  return run();
-}
-
-function abortableDelay(ms: number, signal?: AbortSignal): Promise<void> {
-  if (signal?.aborted) return Promise.reject(abortError());
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(done, ms);
-    timer.unref();
-    const onAbort = () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-      reject(abortError());
-    };
-    function done() {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-function abortError(): Error {
-  const error = new Error("tool call aborted");
-  error.name = "AbortError";
-  return error;
-}
-
 /** Install guidance shown when the bsk CLI cannot be spawned. */
 export function bskInstallMessage(bskPath: string): string {
   return (
@@ -239,7 +182,7 @@ export function parseBskJson(result: BskRunResult, commandLabel: string): unknow
     throw new BskError(`bsk ${commandLabel} timed out`, { timedOut: true });
   }
   const body = result.stdout.trim();
-  // Killed by our own interrupt (SIGINT from killFor), not by the abort path:
+  // Killed by our own interrupt (SIGTERM from killFor), not by the abort path:
   // say so instead of doubling the generic label into the message.
   if (result.code === null && !result.aborted && !result.timedOut) {
     throw new BskError(`bsk ${commandLabel} was interrupted (process killed)`);

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

@@ -24,13 +24,6 @@ export interface TrackedSession {
 export class SessionRegistry {
   private readonly sessions = new Map<string, TrackedSession>();
   private currentId: string | undefined;
-  /**
-   * bsk session id → the DSH session ids that may clean it up: the agent
-   * session that started it plus every ancestor along the seed lineage, so
-   * archiving a conversation at ANY level of the chain reaps its browsers
-   * (see archive-cleanup.ts).
-   */
-  private readonly dshOwners = new Map<string, ReadonlySet<string>>();
   /**
    * Slots reserved by in-flight starts. reserveStart/completeStart/abandonStart
    * run synchronously around the async spawn, so concurrent starts can never
@@ -79,37 +72,12 @@ export class SessionRegistry {
   /** Forget a session; falls back to the most recent remaining one. */
   remove(sessionId: string): void {
     this.sessions.delete(sessionId);
-    this.dshOwners.delete(sessionId);
     if (this.currentId === sessionId) {
       const rest = [...this.sessions.values()];
       this.currentId = rest.length > 0 ? rest[rest.length - 1].sessionId : undefined;
     }
   }
 
-  /**
-   * Record which DSH conversation(s) a freshly started bsk session belongs
-   * to (the starting agent's session plus its ancestors). No-op without ids
-   * — e.g. a start whose caller carried no agent identity.
-   */
-  trackOwner(sessionId: string, dshSessionIds: readonly string[]): void {
-    if (dshSessionIds.length === 0 || !this.sessions.has(sessionId)) return;
-    this.dshOwners.set(sessionId, new Set(dshSessionIds));
-  }
-
-  /** bsk session ids owned by the given DSH conversation (or its descendants). */
-  ownedByDsh(dshSessionId: string): string[] {
-    const owned: string[] = [];
-    for (const [sessionId, owners] of this.dshOwners) {
-      if (owners.has(dshSessionId)) owned.push(sessionId);
-    }
-    return owned;
-  }
-
-  /** The DSH conversation ids owning one bsk session (empty when untracked). */
-  dshOwnersOf(sessionId: string): string[] {
-    return [...(this.dshOwners.get(sessionId) ?? [])];
-  }
-
   /** Mark an owned session as most recently used (recency order refresh). */
   private touch(sessionId: string): void {
     const existing = this.sessions.get(sessionId);

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

@@ -2,14 +2,13 @@
  * Progressive disclosure of the BrowserSkill agent skill through the harness's
  * official skill seam (`ctx.skills`). The catalog entry (name + description)
  * is resident; the body is loaded only when the model invokes the `skill`
- * tool. The dedicated DeepSeek Harness markdown is embedded into a static
- * module at build time, so registration and every pre-step catalog snapshot
- * are pure in-memory reads — no disk, no process, no daemon. The CLI-oriented
- * repository skill is intentionally a separate interface.
+ * tool. The markdown is build-time assembled into a static module (dsh
+ * prelude + the canonical CLI skill body verbatim), so registration and every
+ * pre-step catalog snapshot are pure in-memory reads — no disk, no process,
+ * no daemon.
  */
 
 import type { Context } from "@deepseek-ai/cordis";
-import type { Agent } from "@deepseek-ai/dsh-agent";
 import {
   BSK_SKILL_DESCRIPTION,
   BSK_SKILL_MARKDOWN,
@@ -26,13 +25,8 @@ interface SkillsLike {
   }): () => void;
 }
 
-/** Structural view of the live-agent registry (absent in bare compositions). */
-interface AgentsLike {
-  list(): Agent[];
-}
-
 /**
- * Publish the browser skill as an embedded runtime skill. Returns the unregistration
+ * Publish the BSK skill as an embedded runtime skill. Returns the unregistration
  * disposer. A composition without the `skills` service (or with dsh-tool-skill
  * retired) leaves the rest of the plugin unaffected — the no-op is silent.
  */
@@ -49,54 +43,3 @@ export function registerBskSkill(ctx: Context): () => void {
     source: "bundled",
   });
 }
-
-/**
- * Install the DSH-specific browser skill into every exact agent scope.
- *
- * DSH merges skill layers nearest-first (`agent -> preset -> global`). A legacy
- * CLI skill installed at `~/.agents/skills/browser-skill` is discovered by the
- * preset filesystem provider and therefore shadows a plugin-level registration.
- * Registering the embedded skill through `agent.ctx` makes the DSH protocol
- * contract authoritative for that agent without touching the shared CLI skill.
- *
- * New agents are handled at `agent/session-start`, the first supported startup
- * injection point and still before the first prompt assembly. Existing agents
- * are registered immediately so plugin reloads take effect without recreating
- * the conversation. Returns a disposer for all plugin-owned registrations.
- */
-export function armAgentScopedBskSkill(ctx: Context): () => void {
-  const registrations = new Map<Agent, () => void>();
-  let active = true;
-
-  const registerForAgent = (agent: Agent): void => {
-    if (!active || registrations.has(agent)) return;
-    registrations.set(agent, registerBskSkill(agent.ctx));
-  };
-
-  let stopSessionStart = () => {};
-  let stopDisposed = () => {};
-  if (typeof ctx.on === "function") {
-    stopSessionStart = ctx.on("agent/session-start", ({ agent }) => {
-      registerForAgent(agent);
-    });
-    stopDisposed = ctx.on("agent/disposed", ({ agent }) => {
-      // Agent-scoped effects have already unwound at this lifecycle edge. Drop
-      // the retained disposer without invoking it against a disposed context.
-      registrations.delete(agent);
-    });
-  }
-
-  const agents = ctx.get("agents") as AgentsLike | undefined | null;
-  if (agents != null && typeof agents.list === "function") {
-    for (const agent of agents.list()) registerForAgent(agent);
-  }
-
-  return () => {
-    if (!active) return;
-    active = false;
-    stopDisposed();
-    stopSessionStart();
-    for (const unregister of [...registrations.values()].reverse()) unregister();
-    registrations.clear();
-  };
-}

packages/dsh-plugin-browserskill/src/tool-params.ts

@@ -1,24 +0,0 @@
-/** Shared model-facing parameter schemas for browser tools. */
-
-export const SESSION_PARAM = {
-  type: "string",
-  description:
-    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
-    "Omit to use the current session (the one most recently started or used).",
-} as const;
-
-export const TAB_ID_PARAM = {
-  type: "integer",
-  description: "Target tab id. Omit to use the Agent Window's active tab.",
-} as const;
-
-export const WAIT_UNTIL_PARAM = {
-  type: "string",
-  enum: ["load", "domcontentloaded", "networkidle", "commit"],
-  description: "Page lifecycle phase to wait for (default: load).",
-} as const;
-
-export const TIMEOUT_MS_PARAM = {
-  type: "integer",
-  description: "Command timeout in milliseconds; must be greater than zero.",
-} as const;

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

@@ -17,20 +17,11 @@ import {
   type ToolResult,
   type ToolRunContext,
 } from "@deepseek-ai/dsh-tools";
-import { ownerSessionIds } from "./archive-cleanup";
 import { trySaveScreenshot } from "./image";
 import { actionForLabel, type ObservationService } from "./observation";
-import { registerPhaseOneTools } from "./phase-one-tools";
 import type { KeyedExecutor } from "./queue";
-import {
-  type BskRunner,
-  bskInstallMessage,
-  isCommandNotFound,
-  parseBskJson,
-  runWithSessionBusyRetry,
-} from "./runner";
+import { type BskRunner, bskInstallMessage, isCommandNotFound, parseBskJson } from "./runner";
 import type { SessionRegistry } from "./sessions";
-import { SESSION_PARAM } from "./tool-params";
 
 /** Plugin configuration resolved from the Schemastery schema in index.ts. */
 export interface PluginConfig {
@@ -70,6 +61,13 @@ const DEVICE_PRESETS = [
   "galaxy-tab-s8",
 ] as const;
 
+const SESSION_PARAM = {
+  type: "string",
+  description:
+    "bsk session id to act on; must be one created by this plugin's browser_session_start. " +
+    "Omit to use the current session (the one most recently started or used).",
+} as const;
+
 /**
  * Run one bsk command and return its parsed JSON payload, or throw.
  * `observeSession` marks the run as model-facing work on that session: it is
@@ -83,10 +81,7 @@ async function runBsk(
   args: string[],
   label: string,
   observeSession?: string,
-  runnerTimeoutMs?: number,
 ): Promise<unknown> {
-  const releaseForeground =
-    observeSession !== undefined ? deps.observation.acquireForeground(observeSession) : undefined;
   // beginAction must fire only when the task actually starts inside the
   // per-session queue — marking it while still queued would overwrite the
   // in-flight action's label (and flash it idle on a queued abort).
@@ -100,15 +95,11 @@ async function runBsk(
           began = true;
           deps.observation.beginAction(observeSession, actionForLabel(label));
         }
-        return runWithSessionBusyRetry(
-          () =>
-            deps.runner.run(args, {
-              signal: exec.signal,
-              timeoutMs: runnerTimeoutMs ?? deps.config.defaultTimeoutMs,
-              ...(observeSession !== undefined ? { tag: observeSession } : {}),
-            }),
-          exec.signal,
-        );
+        return deps.runner.run(args, {
+          signal: exec.signal,
+          timeoutMs: deps.config.defaultTimeoutMs,
+          ...(observeSession !== undefined ? { tag: observeSession } : {}),
+        });
       };
       result =
         observeSession !== undefined
@@ -133,7 +124,6 @@ async function runBsk(
     if (observeSession !== undefined && began) {
       deps.observation.endAction(observeSession, actionError);
     }
-    releaseForeground?.();
   }
 }
 
@@ -255,9 +245,6 @@ export function registerTools(deps: ToolDeps): () => void {
           browserInstanceId: reply.browser_instance_id,
           startedAtMs: Date.now(),
         });
-        // Ownership for archive cleanup: the calling conversation and its
-        // ancestors reap this session when any of them is archived.
-        registry.trackOwner(reply.session_id, ownerSessionIds(deps.ctx, exec.agent?.id));
         deps.observation.addSession(reply.session_id, args.url);
         try {
           if (args.device !== undefined) {
@@ -280,15 +267,22 @@ export function registerTools(deps: ToolDeps): () => void {
           }
         } catch (error) {
           // A half-initialized session must not leak: stop it before surfacing.
-          // Reuse the same capture-preempting, idempotent path as explicit and
-          // overlay stops; local ownership is dropped even when daemon cleanup
-          // itself fails, because this start never becomes usable to the model.
-          try {
-            await deps.observation.stopSession(reply.session_id);
-          } catch {
-            registry.remove(reply.session_id);
-            deps.observation.removeSession(reply.session_id);
+          // The stop funnels through the session's queue (an in-flight command
+          // — e.g. an observation capture — would otherwise make the daemon
+          // refuse it), with one retry for good measure.
+          for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+              const stopped = await deps.queue.run(reply.session_id, () =>
+                deps.runner.run(["session", "stop", reply.session_id], { timeoutMs: 30_000 }),
+              );
+              if (stopped.code === 0) break;
+            } catch {
+              // retry once, then give up quietly (registry/observation are
+              // cleaned below either way; the daemon reaps orphans).
+            }
           }
+          registry.remove(reply.session_id);
+          deps.observation.removeSession(reply.session_id);
           throw error;
         }
         return {
@@ -332,15 +326,9 @@ export function registerTools(deps: ToolDeps): () => void {
       },
       async execute(args, exec) {
         const sessionId = registry.resolveForStop(args.session);
-        try {
-          const stopped = await deps.observation.stopSession(sessionId, exec.signal);
-          if (!stopped) throw new Error(`browser session ${sessionId} is not owned by this plugin`);
-        } catch (error) {
-          if (isCommandNotFound(error)) {
-            throw new Error(bskInstallMessage(deps.config.bskPath));
-          }
-          throw error;
-        }
+        await runBsk(deps, exec, ["session", "stop", sessionId], "session stop", sessionId);
+        registry.remove(sessionId);
+        deps.observation.removeSession(sessionId);
         return { stopped: sessionId };
       },
       presentCall: (args) => ({
@@ -497,7 +485,8 @@ export function registerTools(deps: ToolDeps): () => void {
       ? "Capture an indented aria-tree snapshot of the session's active tab. Interactive elements " +
         "carry @eN refs for browser_click / browser_fill. Prefer browser_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_click / browser_fill. Read-only: never submits input.";
+        "probes) with @eN refs. Visual surface refs are screenshot-only; DOM refs support interaction. " +
+        "Read-only: never submits input.";
     register(
       defineTool({
         name,
@@ -760,12 +749,14 @@ export function registerTools(deps: ToolDeps): () => void {
       name: "browser_screenshot",
       description:
         "Capture a PNG screenshot of the session's active tab, or crop to a snapshot ref element. " +
-        "Returns the image itself when the deployment supports image input, otherwise a file path.",
+        "This is the supported operation for visual surface refs emitted by browser_observe. 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: {
@@ -967,12 +958,6 @@ export function registerTools(deps: ToolDeps): () => void {
       presentResult: presentTerminalResult,
     }),
   );
-  registerPhaseOneTools(deps, register, {
-    run: (exec, args, label, observeSession, runnerTimeoutMs) =>
-      runBsk(deps, exec, args, label, observeSession, runnerTimeoutMs),
-    commandLine: (args) => cmdline(deps, args),
-    presentTerminalResult,
-  });
   return () => {
     for (const dispose of disposers.splice(0)) dispose();
   };

packages/dsh-plugin-browserskill/tests/archive-cleanup.test.ts

@@ -1,157 +0,0 @@
-// Archive-triggered cleanup: lineage resolution for browser-session
-// ownership, the registry's owner index, and the domain/changed watcher
-// that reaps a freshly archived conversation's bsk sessions.
-
-import { describe, expect, it, vi } from "vitest";
-import { armArchiveCleanup, ownerSessionIds } from "../src/archive-cleanup";
-import type { ObservationService } from "../src/observation";
-import { SessionRegistry } from "../src/sessions";
-
-/** A ctx stub carrying a session store with the given lineage headers. */
-function ctxWithSessions(headers: Record<string, { parentSession?: string }>) {
-  return {
-    get: (key: string) =>
-      key === "sessions"
-        ? {
-            get: (id: string) => (headers[id] === undefined ? undefined : { header: headers[id] }),
-          }
-        : undefined,
-  } as never;
-}
-
-describe("ownerSessionIds", () => {
-  it("walks the seed lineage to the root; empty without an agent identity", () => {
-    expect(ownerSessionIds(ctxWithSessions({}), undefined)).toEqual([]);
-    const ctx = ctxWithSessions({
-      child: { parentSession: "parent" },
-      parent: { parentSession: "root" },
-      root: {},
-    });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "parent", "root"]);
-  });
-
-  it("stops the walk at an unloaded ancestor", () => {
-    const ctx = ctxWithSessions({ child: { parentSession: "gone" } });
-    expect(ownerSessionIds(ctx, "child")).toEqual(["child", "gone"]);
-  });
-
-  it("never loops on a malformed parent cycle", () => {
-    const ctx = ctxWithSessions({
-      a: { parentSession: "b" },
-      b: { parentSession: "a" },
-    });
-    expect(ownerSessionIds(ctx, "a")).toEqual(["a", "b"]);
-  });
-});
-
-describe("SessionRegistry owner tracking", () => {
-  function start(registry: SessionRegistry, sessionId: string): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId, startedAtMs: 1 });
-  }
-
-  it("indexes owners and forgets them on remove; ignores empty/unknown ownership", () => {
-    const registry = new SessionRegistry(5);
-    start(registry, "bsk1");
-    start(registry, "bsk2");
-    registry.trackOwner("bsk1", ["conv-a", "root"]);
-    registry.trackOwner("bsk2", ["conv-b"]);
-    expect(registry.ownedByDsh("root")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-a")).toEqual(["bsk1"]);
-    expect(registry.ownedByDsh("conv-b")).toEqual(["bsk2"]);
-    expect(registry.ownedByDsh("nobody")).toEqual([]);
-    registry.remove("bsk1");
-    expect(registry.ownedByDsh("root")).toEqual([]);
-    // Empty owner lists and unknown session ids record nothing.
-    registry.trackOwner("bsk2", []);
-    registry.trackOwner("ghost", ["conv-c"]);
-    expect(registry.ownedByDsh("conv-c")).toEqual([]);
-  });
-});
-
-describe("armArchiveCleanup", () => {
-  function harness(opts: { archived?: string[] } = {}) {
-    const registry = new SessionRegistry(5);
-    const observation = { stopSession: vi.fn(async () => true) };
-    const listeners = new Set<(change: unknown) => void>();
-    const ctx = {
-      get: (key: string) =>
-        key === "workspaceRegistry" ? { archivedSessionIds: opts.archived ?? [] } : undefined,
-      on: (event: string, listener: (change: unknown) => void) => {
-        if (event === "domain/changed") listeners.add(listener);
-        return () => listeners.delete(listener);
-      },
-    };
-    const emit = (change: unknown) => {
-      for (const listener of [...listeners]) listener(change);
-    };
-    return {
-      registry,
-      observation: observation as unknown as ObservationService,
-      stopSession: observation.stopSession,
-      emit,
-      arm: () =>
-        armArchiveCleanup(ctx as never, registry, observation as unknown as ObservationService),
-    };
-  }
-
-  function startOwned(registry: SessionRegistry, bskId: string, owners: string[]): void {
-    registry.reserveStart();
-    registry.completeStart({ sessionId: bskId, startedAtMs: 1 });
-    registry.trackOwner(bskId, owners);
-  }
-
-  it("stops every bsk session owned by a freshly archived conversation, until disarmed", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a", "root"]);
-    startOwned(h.registry, "bsk2", ["conv-b"]);
-    const disarm = h.arm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    expect(h.stopSession).toHaveBeenCalledWith("bsk1");
-    // After the disposer runs the watcher is silent again.
-    disarm();
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["root", "conv-b"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-  });
-
-  it("ignores pre-archived ids, foreign domains, and malformed frames", () => {
-    const h = harness({ archived: ["old-conv"] });
-    startOwned(h.registry, "bsk1", ["old-conv"]);
-    startOwned(h.registry, "bsk2", ["conv-a"]);
-    h.arm();
-    // Seeded from the registry: the pre-archived id must not retro-fire.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["old-conv"] } });
-    h.emit({ domain: "settings", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "rows", value: { archivedSessionIds: ["conv-a"] } });
-    h.emit({ domain: "workspace", table: "", value: {} });
-    expect(h.stopSession).not.toHaveBeenCalled();
-    // A genuinely new archive still fires.
-    h.emit({
-      domain: "workspace",
-      table: "",
-      value: { archivedSessionIds: ["old-conv", "conv-a"] },
-    });
-    expect(h.stopSession).toHaveBeenCalledWith("bsk2");
-  });
-
-  it("treats a re-archived session as fresh again after unarchive", () => {
-    const h = harness();
-    startOwned(h.registry, "bsk1", ["conv-a"]);
-    h.arm();
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(1);
-    // Unarchive, then re-archive: the second archival cleans up again.
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: [] } });
-    h.emit({ domain: "workspace", table: "", value: { archivedSessionIds: ["conv-a"] } });
-    expect(h.stopSession).toHaveBeenCalledTimes(2);
-  });
-});

packages/dsh-plugin-browserskill/tests/client/observation-overlay.test.tsx

@@ -4,7 +4,7 @@
 // upgrade/fallback (mocked documentPictureInPicture). NOTE: use RTL's waitFor
 // (act-flushing), not vi.waitFor, when asserting store-driven UI updates.
 
-import { act, cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { applyResize, ObservationOverlay } from "../../src/client/ObservationOverlay";
 import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
@@ -157,45 +157,6 @@ describe("ObservationOverlay", () => {
     await screen.findByText(/s1 · clicking/);
   });
 
-  it("stop session: the first click only arms the confirm, the second posts", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    await screen.findByText(/s1 · idle/);
-    const stop = screen.getByRole("button", { name: "Stop session s1" });
-    fireEvent.click(stop);
-    // Armed: a plain click must never close an Agent Window by itself.
-    expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    const confirm = await screen.findByRole("button", { name: "Confirm stop session s1" });
-    expect(confirm.getAttribute("aria-pressed")).toBe("true");
-    fireEvent.click(confirm);
-    await waitFor(() =>
-      expect(
-        h.fetches.some(
-          (f) => f.url === "/bsk-observation/stop" && f.init?.body === '{"sessionId":"s1"}',
-        ),
-      ).toBe(true),
-    );
-  });
-
-  it("disarms the stop confirm after the expiry window", async () => {
-    const h = makeHarness([{ sessionId: "s1", action: "idle", since: Date.now() }]);
-    render(<ObservationOverlay store={h.store} />);
-    const stop = await screen.findByRole("button", { name: "Stop session s1" });
-    vi.useFakeTimers();
-    try {
-      fireEvent.click(stop);
-      // Synchronous queries only: waitFor-style finds hang under fake timers.
-      expect(screen.getByRole("button", { name: "Confirm stop session s1" })).toBeTruthy();
-      act(() => {
-        vi.advanceTimersByTime(3100);
-      });
-      expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-      expect(h.fetches.some((f) => f.url === "/bsk-observation/stop")).toBe(false);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-
   it("resizes within min/max clamps", async () => {
     const h = makeHarness([BUSY]);
     render(<ObservationOverlay store={h.store} />);
@@ -261,7 +222,6 @@ describe("ObservationOverlay", () => {
         addEventListener: (name: string, fn: () => void) => {
           listeners.set(name, [...(listeners.get(name) ?? []), fn]);
         },
-        close: vi.fn(),
       } as unknown as Window;
     });
     (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
@@ -276,28 +236,6 @@ describe("ObservationOverlay", () => {
     await screen.findByTestId("obs-card");
   });
 
-  it("closes the PiP window when the carrier unmounts", async () => {
-    const h = makeHarness([BUSY]);
-    const pipDoc = document.implementation.createHTMLDocument("pip");
-    const close = vi.fn();
-    const requestWindow = vi.fn(async () => {
-      return {
-        document: pipDoc,
-        addEventListener: () => {},
-        close,
-      } as unknown as Window;
-    });
-    (window as unknown as Record<string, unknown>).documentPictureInPicture = { requestWindow };
-    const { unmount } = render(<ObservationOverlay store={h.store} />);
-    const popout = await screen.findByRole("button", { name: /Pop out/ });
-    fireEvent.click(popout);
-    await waitFor(() => expect(pipDoc.body.textContent).toContain("s1"));
-    // Unmounting (tab close, conversation switch, plugin HMR) closes the PiP
-    // instead of leaving a blank window behind.
-    unmount();
-    expect(close).toHaveBeenCalledTimes(1);
-  });
-
   it("renders the strip for two sessions and pins focus on click", async () => {
     const older: SessionObservation = {
       sessionId: "s1",

packages/dsh-plugin-browserskill/tests/client/observation-sidebar.test.tsx

@@ -1,331 +0,0 @@
-// @vitest-environment happy-dom
-// better-sidebar carrier: tab registration + auto-open, the sidebar-mode
-// flag hiding the floating overlay, PiP pop-out from the tab, and the
-// store's refcounted acquire/release across overlapping carriers.
-
-import { cleanup, render, screen, waitFor } from "@testing-library/react";
-import { afterEach, describe, expect, it, vi } from "vitest";
-import { ObservationOverlay } from "../../src/client/ObservationOverlay";
-import {
-  type BetterSidebarLike,
-  OBSERVATION_TAB_PATH,
-  OBSERVATION_TAB_TYPE,
-  ObservationSidebarTab,
-  observationTabOpen,
-  registerObservationSidebar,
-  type SidebarNodeLike,
-  type SidebarStateLike,
-  type TabDescriptorLike,
-} from "../../src/client/observation-sidebar";
-import { type EventSourceLike, ObservationClientStore } from "../../src/client/observation-store";
-import { getSidebarMode, setSidebarMode } from "../../src/client/sidebar-mode";
-import type { SessionObservation } from "../../src/observation";
-
-// Owned by the sidebar mock's active conversation ("conv-1") so the scoped
-// visibility logic lets it through; FOREIGN belongs to another conversation.
-const BUSY: SessionObservation = {
-  sessionId: "s1",
-  action: "clicking",
-  since: Date.now() - 7000,
-  dshSessionIds: ["conv-1"],
-};
-const FOREIGN: SessionObservation = {
-  sessionId: "s9",
-  action: "clicking",
-  since: Date.now() - 5000,
-  dshSessionIds: ["other-conv"],
-};
-
-interface Harness {
-  store: ObservationClientStore;
-  es: () => EventSourceLike | undefined;
-  push: (sessions: SessionObservation[]) => void;
-}
-
-function makeHarness(initial: SessionObservation[]): Harness {
-  let es: EventSourceLike | undefined;
-  let current = initial;
-  const store = new ObservationClientStore({
-    fetchFn: async (url: string) => {
-      if (url === "/bsk-observation/state") {
-        return { ok: true, json: async () => ({ sessions: current }) };
-      }
-      return { ok: true, json: async () => ({ interrupted: true }) };
-    },
-    eventSourceFactory: () => {
-      es = { onmessage: null, close: vi.fn() };
-      return es;
-    },
-    loadImage: async (id: string) => `blob:${id}`,
-  });
-  return {
-    store,
-    es: () => es,
-    push: (sessions) => {
-      current = sessions;
-      for (const s of sessions) {
-        es?.onmessage?.({ data: JSON.stringify({ type: "upsert", session: s }) });
-      }
-      if (sessions.length === 0) es?.onmessage?.({ data: JSON.stringify({ type: "reset" }) });
-    },
-  };
-}
-
-function leafWith(type: string, panelOpen = true): SidebarStateLike {
-  return {
-    panelOpen,
-    splits: {
-      kind: "split",
-      id: "root",
-      dir: "row",
-      sizes: [1],
-      children: [
-        {
-          kind: "leaf",
-          id: "pane-1",
-          active: type,
-          tabs: [{ id: type, type, title: type }],
-        },
-      ],
-    },
-    bottomSplits: { kind: "leaf", id: "pane-2", active: null, tabs: [] },
-  };
-}
-
-interface SidebarMock {
-  service: BetterSidebarLike;
-  descriptor: () => TabDescriptorLike;
-  openTab: ReturnType<typeof vi.fn>;
-  disposeTab: ReturnType<typeof vi.fn>;
-  setState: (state: SidebarStateLike | undefined) => void;
-}
-
-/** Insert a tab into the first leaf of the main tree (mirrors a real open). */
-function withTabOpened(state: SidebarStateLike, type: string): SidebarStateLike {
-  let done = false;
-  const walk = (node: SidebarNodeLike): SidebarNodeLike => {
-    if (done) return node;
-    if (node.kind === "leaf") {
-      done = true;
-      return { ...node, active: type, tabs: [...node.tabs, { id: type, type, title: type }] };
-    }
-    return { ...node, children: node.children.map(walk) };
-  };
-  return { ...state, splits: walk(state.splits) };
-}
-
-function makeSidebar(
-  initialState: SidebarStateLike | undefined = leafWith("explorer"),
-): SidebarMock {
-  let descriptor: TabDescriptorLike | undefined;
-  let state: SidebarStateLike | undefined = initialState;
-  const openTab = vi.fn((seed: { type: string }) => {
-    // Mirror the real feedback loop: a created tab lands in the state, so
-    // later evaluations see it open (single-instance dedupe re-focuses).
-    if (state !== undefined && !observationTabOpen(state)) {
-      state = withTabOpened(state, seed.type);
-    }
-  });
-  const disposeTab = vi.fn();
-  const service: BetterSidebarLike = {
-    registerTab: (next) => {
-      descriptor = next;
-      return disposeTab;
-    },
-    openTab,
-    getSnapshot: () => ({ sessionId: "conv-1", state }),
-    isTabEnabled: () => true,
-  };
-  return {
-    service,
-    descriptor: () => {
-      if (descriptor === undefined) throw new Error("no tab registered");
-      return descriptor;
-    },
-    openTab,
-    disposeTab,
-    setState: (next) => {
-      state = next;
-    },
-  };
-}
-
-afterEach(() => {
-  cleanup();
-  setSidebarMode(false);
-});
-
-describe("registerObservationSidebar", () => {
-  it("registers a single-instance tab and holds the feed for its lifetime", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    expect(getSidebarMode()).toBe(false);
-    const dispose = registerObservationSidebar(sidebar.service, h.store);
-    expect(getSidebarMode()).toBe(true);
-    // The fiber holds the observation feed itself, so the auto-open watcher
-    // sees new sessions even while the tab is closed.
-    expect(h.es()).toBeDefined();
-    const descriptor = sidebar.descriptor();
-    expect(descriptor.id).toBe(OBSERVATION_TAB_TYPE);
-    expect(descriptor.single).toBe(true);
-    expect(descriptor.title).toBe("Browser Skill");
-    dispose();
-    expect(getSidebarMode()).toBe(false);
-    expect(sidebar.disposeTab).toHaveBeenCalledTimes(1);
-    expect(h.es()?.close).toHaveBeenCalled?.();
-  });
-
-  it("opens the tab right away when a session is already live at activation", async () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    // The initial state fetch lands asynchronously; the 0→N watcher then fires.
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("auto-opens on the first session but never re-focuses an open tab", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // First session arrives: the tab lands in the sidebar.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-    // The sidebar now reports the tab open (persisted/restored): further
-    // session arrivals must not steal focus from whatever the user reads.
-    sidebar.setState(leafWith(OBSERVATION_TAB_TYPE));
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s2" }]);
-    h.push([]);
-    h.push([{ ...BUSY, sessionId: "s3" }]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).toHaveBeenCalledTimes(1);
-  });
-
-  it("does not open while the sidebar has no active session state", () => {
-    const h = makeHarness([BUSY]);
-    const sidebar = makeSidebar(undefined);
-    registerObservationSidebar(sidebar.service, h.store);
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-  });
-
-  it("nudges an existing tab back into sight when the panel is collapsed", async () => {
-    const h = makeHarness([]);
-    // Tab already open (persisted), but the panel is collapsed: a new
-    // session should surface the tracking view again (focus + expand via a
-    // content open), like the floating card reappearing.
-    const sidebar = makeSidebar(leafWith(OBSERVATION_TAB_TYPE, false));
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([BUSY]);
-    await waitFor(() =>
-      expect(sidebar.openTab).toHaveBeenCalledWith({
-        type: OBSERVATION_TAB_TYPE,
-        path: OBSERVATION_TAB_PATH,
-      }),
-    );
-  });
-
-  it("shows the visible session count as the tab badge", () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    const badge = sidebar.descriptor().badge;
-    const scope = { sessionId: "conv-1" };
-    expect(badge?.(undefined, scope, undefined)).toBeNull();
-    h.store.acquire();
-    h.push([BUSY, FOREIGN]);
-    expect(badge?.(undefined, scope, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "other-conv" }, undefined)).toBe(1);
-    expect(badge?.(undefined, { sessionId: "nobody" }, undefined)).toBeNull();
-    h.store.release();
-  });
-
-  it("does not auto-open for sessions owned by other conversations", async () => {
-    const h = makeHarness([]);
-    const sidebar = makeSidebar();
-    registerObservationSidebar(sidebar.service, h.store);
-    h.push([FOREIGN]);
-    await waitFor(() => expect(h.store.getSnapshot().sessions.length).toBe(1));
-    expect(sidebar.openTab).not.toHaveBeenCalled();
-    // A session visible to the active conversation does open the tab.
-    h.push([BUSY]);
-    await waitFor(() => expect(sidebar.openTab).toHaveBeenCalledTimes(1));
-  });
-});
-
-describe("observationTabOpen", () => {
-  it("finds the tab in either workbench tree", () => {
-    expect(observationTabOpen(undefined)).toBe(false);
-    expect(observationTabOpen(leafWith("explorer"))).toBe(false);
-    expect(observationTabOpen(leafWith(OBSERVATION_TAB_TYPE))).toBe(true);
-    const inBottom: SidebarStateLike = {
-      splits: { kind: "leaf", id: "p1", active: null, tabs: [] },
-      bottomSplits: {
-        kind: "leaf",
-        id: "p2",
-        active: OBSERVATION_TAB_TYPE,
-        tabs: [{ id: OBSERVATION_TAB_TYPE, type: OBSERVATION_TAB_TYPE, title: "Browser" }],
-      },
-    };
-    expect(observationTabOpen(inBottom)).toBe(true);
-  });
-});
-
-describe("ObservationSidebarTab", () => {
-  it("renders the tracking view without card chrome (no collapse, no drag header)", async () => {
-    const h = makeHarness([BUSY]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByRole("button", { name: "Collapse" })).toBeNull();
-    expect(screen.getByTestId("obs-header").dataset.draggable).toBeUndefined();
-    // No resize handles — the sidebar owns the geometry.
-    expect(screen.queryByTestId("obs-resize-se")).toBeNull();
-    // Session controls ride along: interrupt + stop-with-confirm.
-    expect(screen.getByRole("button", { name: "Stop session s1" })).toBeTruthy();
-  });
-
-  it("scopes the view to the sidebar's conversation", async () => {
-    const h = makeHarness([BUSY, FOREIGN]);
-    render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    // Focus and content belong to the owned session; the foreign one never
-    // reaches the stage, the status line, or the strip (which needs 2+).
-    await screen.findByText(/s1 · clicking/);
-    expect(screen.queryByText(/s9/)).toBeNull();
-    expect(screen.queryByTestId("obs-strip")).toBeNull();
-    // Scoping to the other conversation swaps what's visible.
-    render(<ObservationSidebarTab store={h.store} scopeId="other-conv" />);
-    await screen.findByText(/s9 · clicking/);
-  });
-});
-
-describe("carrier switching", () => {
-  it("hides the floating overlay while sidebar mode is active", async () => {
-    const h = makeHarness([]);
-    const { container } = render(<ObservationOverlay store={h.store} />);
-    h.push([BUSY]);
-    await screen.findByTestId("obs-card");
-    setSidebarMode(true);
-    await waitFor(() => expect(container.firstChild).toBeNull());
-    setSidebarMode(false);
-    await screen.findByTestId("obs-card");
-  });
-
-  it("keeps the feed alive across overlapping carriers (refcount)", async () => {
-    const h = makeHarness([]);
-    const overlay = render(<ObservationOverlay store={h.store} />);
-    await waitFor(() => expect(h.es()).toBeDefined());
-    // A second carrier mounts (the sidebar tab), then the overlay unmounts:
-    // the stream must survive for the remaining consumer.
-    const tab = render(<ObservationSidebarTab store={h.store} scopeId="conv-1" />);
-    overlay.unmount();
-    h.push([BUSY]);
-    await screen.findByText(/s1 · clicking/);
-    expect(h.es()?.close ?? vi.fn()).not.toHaveBeenCalled();
-    tab.unmount();
-  });
-});

packages/dsh-plugin-browserskill/tests/client/screenshot-toolview.test.tsx

@@ -137,9 +137,6 @@ describe("client plugin registration", () => {
     const sessions = { binding: () => undefined };
     const ctx = {
       get: (key: string) => (key === "sessions" ? sessions : undefined),
-      // cordis ctx.inject: the betterSidebar carrier upgrade stays dormant in
-      // this composition (the callback only runs once the service exists).
-      inject: (_deps: string[], _fn: (injected: unknown) => unknown) => {},
       slots: {
         inject: (_name: string, fn: () => unknown) => fn(),
         register: (slot: { name: string; key?: string; id?: string }, view: unknown) => {

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

@@ -61,8 +61,6 @@ function fakeRunner(
   opts: {
     screenshotFails?: boolean;
     screenshotNotFound?: boolean;
-    stopNotFound?: boolean;
-    stopFails?: boolean;
     killCount?: number;
     screenshotBytes?: () => Uint8Array;
   } = {},
@@ -74,26 +72,11 @@ function fakeRunner(
     killed,
     async run(args: string[], options: BskRunOptions = {}): Promise<BskRunResult> {
       calls.push({ args, options });
-      if (args[0] === "session" && args[1] === "stop") {
-        if (opts.stopNotFound) {
-          return {
-            code: 4,
-            stdout: JSON.stringify({ code: "not_found", message: "no such session" }),
-            stderr: "",
-            timedOut: false,
-            aborted: false,
-          };
-        }
-        if (opts.stopFails) {
-          return { code: 1, stdout: "", stderr: "boom", timedOut: false, aborted: false };
-        }
-        return { code: 0, stdout: "{}", stderr: "", timedOut: false, aborted: false };
-      }
       if (args[0] === "screenshot") {
         if (opts.screenshotNotFound) {
           return {
             code: 4,
-            stdout: JSON.stringify({ code: "not_found", message: "no such session" }),
+            stdout: JSON.stringify({ code: "session_not_found", message: "no such session" }),
             stderr: "",
             timedOut: false,
             aborted: false,
@@ -197,23 +180,6 @@ describe("state machine", () => {
     expect(events[events.length - 1].type).toBe("reset");
   });
 
-  it("stamps the registry-recorded DSH owners onto new entries", () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    own(registry, "s2");
-    registry.trackOwner("s1", ["conv-a", "root"]);
-    const { service } = setup({ registry });
-    service.addSession("s1");
-    service.addSession("s2");
-    expect(service.getState()).toEqual([
-      { sessionId: "s1", action: "idle", since: 1_000_000, dshSessionIds: ["conv-a", "root"] },
-      { sessionId: "s2", action: "idle", since: 1_000_000 },
-    ]);
-    // The owner stamp survives later upserts (action/url/frame churn).
-    service.beginAction("s1", "clicking");
-    expect(service.getState()[0].dshSessionIds).toEqual(["conv-a", "root"]);
-  });
-
   it("ignores instrumentation for unknown sessions (owned-only by construction)", () => {
     const { service } = setup({});
     service.beginAction("foreign", "clicking");
@@ -224,57 +190,6 @@ describe("state machine", () => {
 });
 
 describe("thumbnail cadence", () => {
-  it("gives foreground work priority and resumes with one fresh capture", async () => {
-    const scheduler = fakeScheduler();
-    let finishCapture: ((result: BskRunResult) => void) | undefined;
-    const killed: string[] = [];
-    const runner: FakeRunner = {
-      calls: [],
-      killed,
-      run(args) {
-        if (args[0] !== "screenshot") {
-          return Promise.resolve({
-            code: 0,
-            stdout: "{}",
-            stderr: "",
-            timedOut: false,
-            aborted: false,
-          });
-        }
-        return new Promise((resolve) => {
-          finishCapture = resolve;
-        });
-      },
-      killAll() {},
-      killFor(tag) {
-        killed.push(tag);
-        if (tag === "observation:s1" && finishCapture !== undefined) {
-          finishCapture({
-            code: 5,
-            stdout: JSON.stringify({ code: "cancelled", message: "cancelled" }),
-            stderr: "",
-            timedOut: false,
-            aborted: false,
-          });
-          finishCapture = undefined;
-          return 1;
-        }
-        return 0;
-      },
-    };
-    const { service } = setup({ runner, scheduler });
-    service.addSession("s1");
-    scheduler.runNext();
-    await waitFor(() => finishCapture !== undefined);
-
-    const release = service.acquireForeground("s1");
-    expect(killed).toEqual(["observation:s1"]);
-    await waitFor(() => scheduler.pending().length === 0);
-    release();
-    expect(service.isAvailable()).toBe(true);
-    expect(scheduler.pending()).toEqual([0]);
-  });
-
   it("captures immediately on add and after action end, then fast-cadences while active", async () => {
     const scheduler = fakeScheduler();
     const runner = fakeRunner();
@@ -392,57 +307,6 @@ describe("interrupt routing", () => {
   });
 });
 
-describe("stopSession", () => {
-  it("stops an owned session: kills in-flight tools, runs session stop, removes the entry", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    expect(registry.isOwned("s1")).toBe(true);
-
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(runner.killed).toEqual(["observation:s1", "s1"]);
-    const stop = runner.calls.find((c) => c.args[0] === "session" && c.args[1] === "stop");
-    expect(stop?.args).toEqual(["session", "stop", "s1"]);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(service.getState()).toEqual([]);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("refuses foreign sessions without touching the runner", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner();
-    const { service } = setup({ registry, runner });
-    await expect(service.stopSession("foreign")).resolves.toBe(false);
-    expect(runner.killed).toEqual([]);
-    expect(runner.calls).toEqual([]);
-  });
-
-  it("stops idempotently when the daemon already forgot the session (dead entries)", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopNotFound: true });
-    const { service, events } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).resolves.toBe(true);
-    expect(registry.isOwned("s1")).toBe(false);
-    expect(events[events.length - 1]).toMatchObject({ type: "remove" });
-  });
-
-  it("rejects and keeps the entry when the stop itself fails", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const runner = fakeRunner({ stopFails: true });
-    const { service } = setup({ registry, runner });
-    service.addSession("s1");
-    await expect(service.stopSession("s1")).rejects.toThrow(/boom/);
-    expect(registry.isOwned("s1")).toBe(true);
-    expect(service.getState().map((s) => s.sessionId)).toEqual(["s1"]);
-  });
-});
-
 describe("HTTP/SSE interface", () => {
   interface RecordedRoute {
     path: string;
@@ -541,45 +405,11 @@ describe("HTTP/SSE interface", () => {
     await interruptRoute?.handler(postReq, interruptRes.res as never);
     expect(JSON.parse(interruptRes.res.body())).toEqual({ interrupted: true });
 
-    // stop (POST {sessionId}): owned session stops and leaves the state
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const stopRes = fakeRes();
-    await stopRoute?.handler(postReq, stopRes.res as never);
-    // The stop is async behind the response-less handler — poll the state.
-    await waitFor(() => service.getState().length === 0);
-    expect(JSON.parse(stopRes.res.body())).toEqual({ stopped: true });
-
     dispose();
     expect(routes.size).toBe(0);
     service.dispose();
   });
 
-  it("refuses a stop without a sessionId", async () => {
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const { service } = setup({ registry });
-    const { routes, webServer } = routeHarness();
-    const ctx = { get: (key: string) => (key === "webServer" ? webServer : undefined) } as never;
-    const dispose = registerObservationRoutes(ctx, service);
-
-    const stopRoute = routes.get("/bsk-observation/stop");
-    const res = fakeRes();
-    const emptyReq = fakeReq({
-      method: "POST",
-      headers: { host: "127.0.0.1:3999", "content-type": "application/json" },
-      on: (event: string, fn: (chunk?: string) => void) => {
-        if (event === "data") fn("{}");
-        if (event === "end") fn();
-      },
-    });
-    await stopRoute?.handler(emptyReq, res.res as never);
-    expect(res.res.status).toBe(400);
-    expect(registry.isOwned("s1")).toBe(true);
-
-    dispose();
-    service.dispose();
-  });
-
   it("fences off non-loopback, cross-site, and simple-request traffic", async () => {
     const registry = new SessionRegistry(5);
     own(registry, "s1");
@@ -641,7 +471,7 @@ describe("HTTP/SSE interface", () => {
   });
 });
 
-describe("availability and missing sessions", () => {
+describe("availability and dead sessions", () => {
   it("flips availability off after repeated global failures and back on success", async () => {
     const scheduler = fakeScheduler();
     const runner = fakeRunner({ screenshotFails: true });
@@ -661,18 +491,23 @@ describe("availability and missing sessions", () => {
     service.dispose();
   });
 
-  it("removes an owned ghost on not_found and stops asking for frames", async () => {
+  it("marks a session dead on session_not_found and stops asking for frames", async () => {
     const scheduler = fakeScheduler();
     const runner = fakeRunner({ screenshotNotFound: true });
-    const registry = new SessionRegistry(5);
-    own(registry, "s1");
-    const { service, events } = setup({ runner, scheduler, registry });
+    const { service, events } = setup({ runner, scheduler });
     service.addSession("s1");
     scheduler.runNext();
-    await waitFor(() => events.some((e) => e.type === "remove"));
-    expect(service.getState()).toEqual([]);
-    expect(registry.isOwned("s1")).toBe(false);
+    await waitFor(() => events.some((e) => e.type === "upsert" && e.session?.dead === true));
+    expect(service.getState()[0].dead).toBe(true);
+    expect(service.getState()[0].action).toBe("idle");
+    // No further captures are scheduled for a dead session.
     expect(scheduler.pending()).toEqual([]);
+    // Instrumentation is dropped for dead sessions.
+    service.beginAction("s1", "clicking");
+    expect(service.getState()[0].action).toBe("idle");
+    // A dead session leaves cleanly.
+    service.removeSession("s1");
+    expect(service.getState()).toEqual([]);
   });
 
   it("clears lastError on the next action and keeps it on failure", () => {
@@ -695,9 +530,6 @@ describe("actionForLabel", () => {
     expect(actionForLabel("navigate")).toBe("navigating");
     expect(actionForLabel("screenshot")).toBe("capturing");
     expect(actionForLabel("session start")).toBe("starting");
-    expect(actionForLabel("tab borrow")).toBe("borrowing tab");
-    expect(actionForLabel("request-help")).toBe("waiting for user");
-    expect(actionForLabel("wait-for-navigation")).toBe("waiting for navigation");
   });
 });
 

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

@@ -1,14 +1,7 @@
 import type { ChildProcess } from "node:child_process";
 import { EventEmitter } from "node:events";
 import { describe, expect, it } from "vitest";
-import {
-  type BskRunResult,
-  createBskRunner,
-  isCommandNotFound,
-  isSessionBusyResult,
-  parseBskJson,
-  runWithSessionBusyRetry,
-} from "../src/runner";
+import { type BskRunResult, createBskRunner, isCommandNotFound, parseBskJson } from "../src/runner";
 
 /** Minimal fake ChildProcess driven by the test. */
 class FakeChild extends EventEmitter {
@@ -70,7 +63,7 @@ describe("createBskRunner", () => {
     controller.abort();
     const result = await promise;
     expect(result.aborted).toBe(true);
-    expect(child.killedWith).toContain("SIGINT");
+    expect(child.killedWith).toContain("SIGTERM");
   });
 
   it("kills the child on timeout", async () => {
@@ -87,7 +80,7 @@ describe("createBskRunner", () => {
     const promise = runner.run(["session", "list"]);
     runner.killAll();
     const result = await promise;
-    expect(child.killedWith).toContain("SIGINT");
+    expect(child.killedWith).toContain("SIGTERM");
     expect(result.code).toBeNull();
   });
 });
@@ -147,51 +140,3 @@ describe("isCommandNotFound", () => {
     expect(isCommandNotFound(new Error("other"))).toBe(false);
   });
 });
-
-describe("session busy reconciliation", () => {
-  const busy: BskRunResult = {
-    code: 4,
-    stdout: JSON.stringify({
-      code: "timeout",
-      message: "session already has an unfinished command",
-      data: { reason: "session_busy" },
-    }),
-    stderr: "",
-    timedOut: false,
-    aborted: false,
-  };
-  const ok: BskRunResult = {
-    code: 0,
-    stdout: "{}",
-    stderr: "",
-    timedOut: false,
-    aborted: false,
-  };
-
-  it("recognizes only the structured session_busy reason", () => {
-    expect(isSessionBusyResult(busy)).toBe(true);
-    expect(isSessionBusyResult({ ...busy, stdout: '{"code":"timeout"}' })).toBe(false);
-    expect(isSessionBusyResult(ok)).toBe(false);
-  });
-
-  it("retries one transient busy result and returns the settled response", async () => {
-    const replies = [busy, ok];
-    let calls = 0;
-    const result = await runWithSessionBusyRetry(async () => {
-      calls += 1;
-      return replies.shift() ?? ok;
-    });
-    expect(result).toBe(ok);
-    expect(calls).toBe(2);
-  });
-
-  it("does not loop on a persistent busy result", async () => {
-    let calls = 0;
-    const result = await runWithSessionBusyRetry(async () => {
-      calls += 1;
-      return busy;
-    });
-    expect(result).toBe(busy);
-    expect(calls).toBe(2);
-  });
-});

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

@@ -1,18 +1,15 @@
-// Browser skill injection: registration wiring, catalog content, progressive-load
+// BSK skill injection: registration wiring, catalog content, progressive-load
 // weight, and silent degradation without the skill seam.
 
-import { Context } from "@deepseek-ai/cordis";
-import { createScope, scopeTarget } from "@deepseek-ai/dsh-scope";
-import { SkillRegistry } from "@deepseek-ai/dsh-skill";
 import { describe, expect, it } from "vitest";
-import { armAgentScopedBskSkill, registerBskSkill } from "../src/skill";
+import { registerBskSkill } from "../src/skill";
 
 function fakeCtx(skills?: unknown) {
   return { get: (key: string) => (key === "skills" ? skills : undefined) } as never;
 }
 
 describe("registerBskSkill", () => {
-  it("registers the catalog entry with the DSH browser-tool body", () => {
+  it("registers the catalog entry with the assembled body", () => {
     const registrations: { skill: Record<string, unknown>; disposer: () => void }[] = [];
     const skills = {
       register(skill: Record<string, unknown>) {
@@ -29,51 +26,23 @@ describe("registerBskSkill", () => {
     expect(skill.name).toBe("browser-skill");
     expect(typeof skill.description).toBe("string");
     expect(String(skill.description)).toContain("browser_*");
+    // body = dsh prelude + canonical CLI skill body + dsh postlude
     const content = String(skill.content);
-    const mentionedTools = [...new Set(content.match(/\bbrowser_[a-z][a-z_]*\b/g) ?? [])].sort();
-    expect(mentionedTools).toEqual([
-      "browser_click",
-      "browser_console",
-      "browser_emulate",
-      "browser_fill",
-      "browser_get_html",
-      "browser_hover",
-      "browser_navigate",
-      "browser_navigate_back",
-      "browser_navigate_forward",
-      "browser_network",
-      "browser_observe",
-      "browser_press",
-      "browser_reload",
-      "browser_request_help",
-      "browser_screenshot",
-      "browser_select",
-      "browser_session_list",
-      "browser_session_start",
-      "browser_session_stop",
-      "browser_snapshot",
-      "browser_tab_borrow",
-      "browser_tab_close",
-      "browser_tab_create",
-      "browser_tab_list",
-      "browser_tab_return",
-      "browser_tab_select",
-      "browser_wait_for_navigation",
-      "browser_window_resize",
-    ]);
-    expect(String(skill.description)).not.toMatch(/\bbsk\b/i);
-    expect(content).not.toMatch(/\bbsk\b/i);
-    expect(content).not.toMatch(/```(?:bash|sh|shell)\b/i);
-    expect(content).not.toMatch(/--[a-z]/);
-    expect(content).toContain("All browser operations must use the injected tools directly");
+    expect(content).toContain("browser_observe");
+    expect(String(skill.description)).toContain("never invoke bsk through bash or shell");
+    expect(content).toContain("Always call those injected `browser_*` tools");
+    expect(content).toContain("Never use `bash`, `shell`, `exec`");
+    expect(content).toContain("## DSH routing reminder");
+    expect(content.trimEnd()).toMatch(
+      /always begin with[\s\S]*`browser_session_start`[\s\S]*`browser_session_stop`\.$/,
+    );
+    expect(content).toContain("Owned sessions only");
     expect(content).toContain("Mandatory workflow");
     expect(content).toContain("Refs invalidate after navigation");
-    expect(content).toContain("evaluation and interaction recording are intentionally unsupported");
     expect(content.length).toBeGreaterThan(10_000);
     expect(skill.source).toBe("bundled");
-    // Source frontmatter is registration metadata and must not leak into the body.
-    expect(content.startsWith("---")).toBe(false);
-    expect(content).not.toContain("name: browser-skill\ndescription:");
+    // the original YAML frontmatter must not leak into the body
+    expect(content.includes("name: browser-skill\ndescription:")).toBe(false);
     // disposer passthrough
     unregister();
     expect(skill.__disposed).toBe(true);
@@ -103,88 +72,3 @@ describe("registerBskSkill", () => {
     expect(() => disposer()).not.toThrow();
   });
 });
-
-describe("armAgentScopedBskSkill", () => {
-  it("overrides a nearer legacy CLI skill when the DSH agent starts", async () => {
-    const root = new Context();
-    const skillFiber = root.plugin(SkillRegistry);
-    await skillFiber;
-
-    // The plugin's original registration is global.
-    registerBskSkill(skillFiber.ctx);
-
-    // Model the standard preset's filesystem discovery of
-    // ~/.agents/skills/browser-skill. Its nearer scope wins before the fix.
-    const presetKey = { preset: "standard" };
-    const presetScope = createScope(skillFiber.ctx, presetKey);
-    presetScope.ctx.skills.register({
-      name: "browser-skill",
-      description: "Legacy BrowserSkill CLI instructions",
-      content: "Use bsk shell commands.",
-      source: "user-agents",
-    });
-
-    const agentKey = { agent: "test-agent" };
-    const agentScope = createScope(skillFiber.ctx, agentKey, { parent: presetKey });
-    const agent = {
-      id: "test-agent",
-      ctx: agentScope.ctx,
-    } as never;
-    const agents = { list: () => [] };
-    const pluginCtx = skillFiber.ctx.extend({ agents });
-
-    const before = await skillFiber.ctx.skills.get("browser-skill", { scope: agentKey });
-    expect(before?.content).toBe("Use bsk shell commands.");
-    expect(before?.source).toBe("user-agents");
-
-    const disarm = armAgentScopedBskSkill(pluginCtx);
-    pluginCtx.emit(scopeTarget(agent, agentKey), "agent/session-start", {
-      agent,
-      source: "startup",
-    });
-
-    const after = await skillFiber.ctx.skills.get("browser-skill", { scope: agentKey });
-    expect(after?.content).toContain("All browser operations must use the injected tools directly");
-    expect(after?.content).not.toMatch(/\bbsk\b/i);
-    expect(after?.source).toBe("bundled");
-
-    disarm();
-    await agentScope.dispose();
-    await presetScope.dispose();
-    await skillFiber.dispose();
-  });
-
-  it("installs on existing agents for plugin reload and disposes registrations", () => {
-    const registered: Record<string, unknown>[] = [];
-    let disposed = 0;
-    const agent = {
-      ctx: fakeCtx({
-        register(skill: Record<string, unknown>) {
-          registered.push(skill);
-          return () => {
-            disposed += 1;
-          };
-        },
-      }),
-    } as never;
-    const listeners = new Map<string, (payload: { agent: never }) => void>();
-    const ctx = {
-      get: (key: string) => (key === "agents" ? { list: () => [agent] } : undefined),
-      on(event: string, listener: (payload: { agent: never }) => void) {
-        listeners.set(event, listener);
-        return () => listeners.delete(event);
-      },
-    } as never;
-
-    const disarm = armAgentScopedBskSkill(ctx);
-    expect(registered).toHaveLength(1);
-
-    // A later lifecycle notification for the same agent must not duplicate it.
-    listeners.get("agent/session-start")?.({ agent });
-    expect(registered).toHaveLength(1);
-
-    disarm();
-    expect(disposed).toBe(1);
-    expect(listeners.size).toBe(0);
-  });
-});

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

@@ -142,33 +142,16 @@ describe("tool registration", () => {
     const { tools } = setup({});
     expect([...tools.keys()].sort()).toEqual([
       "browser_click",
-      "browser_console",
       "browser_emulate",
       "browser_fill",
-      "browser_get_html",
-      "browser_hover",
       "browser_navigate",
-      "browser_navigate_back",
-      "browser_navigate_forward",
-      "browser_network",
       "browser_observe",
       "browser_press",
-      "browser_reload",
-      "browser_request_help",
       "browser_screenshot",
-      "browser_select",
       "browser_session_list",
       "browser_session_start",
       "browser_session_stop",
       "browser_snapshot",
-      "browser_tab_borrow",
-      "browser_tab_close",
-      "browser_tab_create",
-      "browser_tab_list",
-      "browser_tab_return",
-      "browser_tab_select",
-      "browser_wait_for_navigation",
-      "browser_window_resize",
     ]);
   });
 
@@ -453,336 +436,6 @@ describe("interaction tools", () => {
       /mutually exclusive/,
     );
   });
-
-  it("browser_hover and browser_select map their structured arguments", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      hover: { tab_id: 7, used_ref: "@e3", x: 12, y: 24 },
-      select: {
-        tab_id: 7,
-        used_ref: "@e4",
-        multiple: true,
-        selected_values: ["a", "b"],
-        selected_labels: ["Alpha", "Beta"],
-      },
-    });
-    await startSession(tools);
-    const hovered = (await tools
-      .get("browser_hover")
-      ?.execute(
-        { target: "@e3", modifiers: ["shift"], settleMs: 250, timeoutMs: 2000 },
-        makeExec(),
-      )) as { x: number; y: number };
-    expect(hovered).toMatchObject({ x: 12, y: 24 });
-    expect(calls[1].args).toEqual([
-      "hover",
-      "--session",
-      "s1",
-      "--modifiers",
-      "shift",
-      "--settle",
-      "250ms",
-      "--timeout",
-      "2000ms",
-      "@e3",
-    ]);
-
-    const selected = (await tools
-      .get("browser_select")
-      ?.execute({ target: "@e4", values: ["a", "b"], tabId: 7 }, makeExec())) as {
-      selectedValues: string[];
-      selectedLabels: string[];
-    };
-    expect(selected).toMatchObject({
-      selectedValues: ["a", "b"],
-      selectedLabels: ["Alpha", "Beta"],
-    });
-    expect(calls[2].args).toEqual([
-      "select",
-      "--session",
-      "s1",
-      "--tab-id",
-      "7",
-      "--value",
-      "a",
-      "--value",
-      "b",
-      "@e4",
-    ]);
-  });
-});
-
-describe("phase-one tab tools", () => {
-  it("maps list/create/close/select/borrow/return through the owned session", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      "tab list": {
-        tabs: [
-          {
-            tab_id: 7,
-            title: "Example",
-            url: "https://example.test",
-            window_id: 2,
-            active: true,
-            scope: "agent",
-          },
-        ],
-      },
-      "tab create": { tab_id: 8, window_id: 2, url: "https://new.test" },
-      "tab close": { tab_id: 8 },
-      "tab select": { tab_id: 7, window_id: 2 },
-      "tab borrow": {
-        tab_id: 20,
-        original_window_id: 9,
-        original_index: 1,
-        agent_window_id: 2,
-      },
-      "tab return": {
-        tab_id: 20,
-        returned_to_window_id: 9,
-        returned_to_index: 1,
-        fallback: false,
-      },
-    });
-    await startSession(tools);
-
-    const listed = (await tools
-      .get("browser_tab_list")
-      ?.execute({ scope: "agent" }, makeExec())) as { tabs: { tabId: number }[] };
-    expect(listed.tabs[0].tabId).toBe(7);
-    const created = (await tools
-      .get("browser_tab_create")
-      ?.execute({ url: "https://new.test", active: false, index: 1 }, makeExec())) as {
-      tabId: number;
-    };
-    expect(created.tabId).toBe(8);
-    await tools.get("browser_tab_close")?.execute({ tabId: 8 }, makeExec());
-    await tools.get("browser_tab_select")?.execute({ tabId: 7 }, makeExec());
-    const borrowed = (await tools
-      .get("browser_tab_borrow")
-      ?.execute({ tabId: 20 }, makeExec())) as { originalWindowId: number };
-    expect(borrowed.originalWindowId).toBe(9);
-    const returned = (await tools
-      .get("browser_tab_return")
-      ?.execute({ tabId: 20 }, makeExec())) as { fallback: boolean };
-    expect(returned.fallback).toBe(false);
-
-    expect(calls.slice(1).map((call) => call.args)).toEqual([
-      ["tab", "list", "--session", "s1", "--scope", "agent"],
-      [
-        "tab",
-        "create",
-        "--session",
-        "s1",
-        "--url",
-        "https://new.test",
-        "--no-active",
-        "--index",
-        "1",
-      ],
-      ["tab", "close", "8", "--session", "s1"],
-      ["tab", "select", "7", "--session", "s1"],
-      ["tab", "borrow", "20", "--session", "s1"],
-      ["tab", "return", "20", "--session", "s1"],
-    ]);
-  });
-});
-
-describe("phase-one navigation tools", () => {
-  it("maps back/forward/reload/wait and preserves timeout budgets", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      "navigate-back": {
-        tab_id: 7,
-        previous_url: "https://b.test",
-        final_url: "https://a.test",
-        reached: "load",
-      },
-      "navigate-forward": {
-        tab_id: 7,
-        previous_url: "https://a.test",
-        final_url: "https://b.test",
-        reached: "load",
-      },
-      reload: {
-        tab_id: 7,
-        previous_url: "https://b.test",
-        final_url: "https://b.test",
-        reached: "networkidle",
-      },
-      "wait-for-navigation": { tab_id: 7, reached: "timeout", error_text: "no navigation" },
-    });
-    await startSession(tools);
-    await tools
-      .get("browser_navigate_back")
-      ?.execute({ tabId: 7, waitUntil: "commit", timeoutMs: 1000 }, makeExec());
-    await tools.get("browser_navigate_forward")?.execute({}, makeExec());
-    await tools
-      .get("browser_reload")
-      ?.execute({ hard: true, waitUntil: "networkidle" }, makeExec());
-    const waited = (await tools
-      .get("browser_wait_for_navigation")
-      ?.execute({ timeoutMs: 2500 }, makeExec())) as { reached: string; errorText: string };
-    expect(waited).toMatchObject({ reached: "timeout", errorText: "no navigation" });
-    expect(calls[1].args).toEqual([
-      "navigate-back",
-      "--session",
-      "s1",
-      "--tab-id",
-      "7",
-      "--wait-until",
-      "commit",
-      "--timeout",
-      "1000ms",
-    ]);
-    expect(calls[2].args).toEqual(["navigate-forward", "--session", "s1"]);
-    expect(calls[3].args).toEqual([
-      "reload",
-      "--session",
-      "s1",
-      "--wait-until",
-      "networkidle",
-      "--hard",
-    ]);
-    expect(calls[4].args).toEqual([
-      "wait-for-navigation",
-      "--session",
-      "s1",
-      "--timeout",
-      "2500ms",
-    ]);
-    expect(calls[4].options.timeoutMs).toBe(120_000);
-  });
-});
-
-describe("phase-one support tools", () => {
-  it("maps request-help targets and structured completion criteria", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      "request-help": {
-        outcome: "completed",
-        completed_by: "system",
-        note: "signed in",
-        tab_id: 7,
-        resolved_targets: [{ matched: true, ref: "@e3" }],
-      },
-    });
-    await startSession(tools);
-    const value = (await tools.get("browser_request_help")?.execute(
-      {
-        prompt: "Please sign in",
-        title: "Login required",
-        targets: ["@e3", "#submit"],
-        timeoutMs: 300_000,
-        completionCriteria: {
-          any: [{ urlContains: "/dashboard" }, { selectorExists: "[data-user]" }],
-          stableForMs: 1000,
-        },
-      },
-      makeExec(),
-    )) as { outcome: string; note: string };
-    expect(value).toMatchObject({ outcome: "completed", note: "signed in" });
-    expect(calls[1].options.timeoutMs).toBe(315_000);
-    expect(calls[1].args.slice(0, 8)).toEqual([
-      "request-help",
-      "--session",
-      "s1",
-      "--prompt",
-      "Please sign in",
-      "--timeout",
-      "300000ms",
-      "--title",
-    ]);
-    const criteriaIndex = calls[1].args.indexOf("--completion-criteria");
-    expect(JSON.parse(calls[1].args[criteriaIndex + 1])).toEqual({
-      any: [{ url_contains: "/dashboard" }, { selector_exists: "[data-user]" }],
-      stable_for_ms: 1000,
-    });
-  });
-
-  it("maps get-html, console, and network results without raw shell access", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      "get-html": { tab_id: 7, html: "<main>Hi</main>", truncated: false, byte_size: 15 },
-      console: {
-        tab_id: 7,
-        entries: [
-          {
-            sequence: 3,
-            kind: "exception",
-            level: "error",
-            text: "boom",
-            stack_trace: [{ function_name: "run", url: "https://a.test/app.js", line: 4 }],
-          },
-        ],
-        next_since: 3,
-        truncated: false,
-      },
-      network: {
-        tab_id: 7,
-        entries: [
-          {
-            sequence: 5,
-            kind: "response",
-            method: "GET",
-            url: "https://a.test/api",
-            status: 200,
-            mime_type: "application/json",
-          },
-        ],
-        next_since: 5,
-        truncated: false,
-      },
-    });
-    await startSession(tools);
-    const html = (await tools
-      .get("browser_get_html")
-      ?.execute({ ref: "@e2", maxBytes: 2048 }, makeExec())) as { html: string };
-    expect(html.html).toBe("<main>Hi</main>");
-    const consoleValue = (await tools
-      .get("browser_console")
-      ?.execute({ since: 1, limit: 10, includeStack: true }, makeExec())) as {
-      entries: { stackTrace: { functionName: string }[] }[];
-    };
-    expect(consoleValue.entries[0].stackTrace[0].functionName).toBe("run");
-    const networkValue = (await tools
-      .get("browser_network")
-      ?.execute({ tabId: 7, maxTextChars: 512 }, makeExec())) as {
-      entries: { mimeType: string }[];
-    };
-    expect(networkValue.entries[0].mimeType).toBe("application/json");
-    expect(calls.slice(1).map((call) => call.args)).toEqual([
-      ["get-html", "--session", "s1", "--ref", "@e2", "--max-bytes", "2048"],
-      ["console", "--session", "s1", "--since", "1", "--limit", "10", "--include-stack"],
-      ["network", "--session", "s1", "--tab-id", "7", "--max-text-chars", "512"],
-    ]);
-  });
-
-  it("resizes only within the CLI-supported range", async () => {
-    const { tools, calls } = setup({
-      "session start": START_REPLY("s1"),
-      "window resize": { window_id: 2, width: 1280, height: 800 },
-    });
-    await startSession(tools);
-    const resize = tools.get("browser_window_resize");
-    const value = (await resize?.execute({ width: 1280, height: 800 }, makeExec())) as {
-      windowId: number;
-    };
-    expect(value.windowId).toBe(2);
-    expect(calls[1].args).toEqual([
-      "window",
-      "resize",
-      "--session",
-      "s1",
-      "--width",
-      "1280",
-      "--height",
-      "800",
-    ]);
-    await expect(resize?.execute({ width: 99, height: 800 }, makeExec())).rejects.toThrow(
-      /100\.\.=7680/,
-    );
-  });
 });
 
 describe("browser_screenshot", () => {

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; 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; 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([
@@ -333,6 +393,84 @@ describe("renderVom single-layer page", () => {
     expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
   });
 
+  it("does not treat implementation CSS classes as control names", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          attrs: { onclick: "handleClick()" },
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          tag: "svg",
+          attrs: { class: "kocomz" },
+        }),
+      ]),
+    );
+
+    expect(out.text).not.toContain("kocomz");
+    expect(out.refs).toEqual([]);
+  });
+
+  it("recovers icon controls only from explicit semantic icon evidence", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          attrs: { onclick: "handleFilter()" },
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          tag: "svg",
+          attrs: { "aria-label": "Filter rows", class: "kocomz" },
+        }),
+      ]),
+    );
+
+    expect(out.text).toContain('@e1 button "Filter rows"');
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+  });
+
+  it("keeps a semantic image as evidence for its clickable wrapper", () => {
+    const out = renderVom(
+      scene([
+        node({ id: 1, role: "RootWebArea", name: "Doc" }),
+        node({
+          id: 2,
+          parentId: 1,
+          role: "generic",
+          cursor: "pointer",
+          rect: { x: 20, y: 20, w: 40, h: 40 },
+        }),
+        node({
+          id: 3,
+          parentId: 2,
+          role: "img",
+          name: "Account",
+          cursor: "pointer",
+          tag: "div",
+        }),
+      ]),
+    );
+
+    expect(out.text).toContain('@e1 button "Account"');
+    expect(coreRefs(out.refs)).toEqual([{ ref: "e1", backendNodeId: 2 }]);
+  });
+
   it("keeps the deepest custom control when wrapper and child both look clickable", () => {
     const out = renderVom(
       scene([

packages/vom/src/index.ts

@@ -1,4 +1,9 @@
-export { applyVomInteractionRecovery, isVomReferenceNode, renderVom } from "./render";
+export {
+  applyVomInteractionRecovery,
+  isVomReferenceNode,
+  isVomStructuralRole,
+  renderVom,
+} from "./render";
 export type {
   ActiveScopeBlock,
   BlockingLayer,
@@ -10,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"]);
@@ -75,6 +76,10 @@ const STRUCTURAL_ROLES = new Set([
   "webarea",
 ]);
 
+export function isVomStructuralRole(role: string | undefined): boolean {
+  return STRUCTURAL_ROLES.has(role?.toLowerCase() ?? "");
+}
+
 const SENSITIVE_MASK = "•••";
 const DEFAULT_MAX_DEPTH = Number.POSITIVE_INFINITY;
 const DEFAULT_MAX_TOKENS = Number.POSITIVE_INFINITY;
@@ -193,13 +198,16 @@ function shouldRender(node: VomNode): boolean {
   const role = normalizedRole(node);
   if (SKIP_ROLES.has(role)) return false;
   if (INTERACTIVE_ROLES.has(role)) return true;
-  if (STRUCTURAL_ROLES.has(role)) return true;
+  if (isVomStructuralRole(role)) return true;
 
   return cleaned(node.name) !== undefined;
 }
 
 export function isVomReferenceNode(node: VomNode): boolean {
-  return INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node);
+  return (
+    node.referenceable !== false &&
+    (INTERACTIVE_ROLES.has(normalizedRole(node)) || isUrlBearingStructuralAction(node))
+  );
 }
 
 function hasRecoveryHandler(node: VomNode): boolean {
@@ -219,14 +227,30 @@ function isContentEditable(node: VomNode): boolean {
   return contentEditable === "true" || contentEditable === "plaintext-only";
 }
 
-function iconKeyword(value: string | undefined): string | undefined {
-  const cleanedValue = cleaned(value);
-  if (!cleanedValue) return undefined;
-  const last = cleanedValue
-    .split(/[#/.\s:_-]+/)
+const ICON_REFERENCE_MARKERS = new Set(["glyph", "icon", "icons", "symbol"]);
+const ICON_REFERENCE_DECORATORS = new Set(["fill", "filled", "line", "outline", "outlined"]);
+
+function iconReferenceName(value: string | undefined): string | undefined {
+  const reference = cleaned(value);
+  if (!reference) return undefined;
+  const fragment = reference.includes("#") ? reference.slice(reference.lastIndexOf("#") + 1) : "";
+  const tokens = (fragment || reference)
+    ?.split(/[#/.\s:_-]+/)
     .filter(Boolean)
-    .pop();
-  return last && /^[a-z][a-z0-9_-]{1,32}$/i.test(last) ? last.toLowerCase() : undefined;
+    .map((token) => token.toLowerCase());
+  if (tokens.length === 0) return undefined;
+  if (fragment) {
+    const semanticTokens = tokens.filter(
+      (token) => !ICON_REFERENCE_MARKERS.has(token) && !ICON_REFERENCE_DECORATORS.has(token),
+    );
+    return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
+  }
+  const marker = tokens.findLastIndex((token) => ICON_REFERENCE_MARKERS.has(token));
+  if (marker < 0) return undefined;
+  const semanticTokens = tokens
+    .slice(marker + 1)
+    .filter((token) => !ICON_REFERENCE_DECORATORS.has(token));
+  return semanticTokens.length > 0 ? semanticTokens.join(" ") : undefined;
 }
 
 function iconHintFromSubtree(
@@ -238,12 +262,12 @@ function iconHintFromSubtree(
   for (const child of children.get(node.id) ?? []) {
     const attrs = child.attrs ?? {};
     const hint =
-      iconKeyword(attrs["aria-label"]) ??
-      iconKeyword(attrs.title) ??
-      iconKeyword(attrs.href) ??
-      iconKeyword(attrs["xlink:href"]) ??
-      iconKeyword(attrs.class) ??
-      iconKeyword(child.text);
+      cleaned(attrs["aria-label"]) ??
+      cleaned(attrs.title) ??
+      (normalizedRole(child) === "img" ? cleaned(child.name) : undefined) ??
+      (["img", "svg", "use"].includes(normalizedTag(child))
+        ? (iconReferenceName(attrs.href) ?? iconReferenceName(attrs["xlink:href"]))
+        : undefined);
     if (hint) return hint;
     const nested = iconHintFromSubtree(child, children, depth + 1);
     if (nested) return nested;
@@ -269,6 +293,7 @@ function recoveredRole(
   node: VomNode,
   children?: Map<number | null, VomNode[]>,
 ): string | undefined {
+  const currentRole = normalizedRole(node);
   const explicitRole = node.attrs?.role?.toLowerCase() ?? "";
   const hasHandler = hasRecoveryHandler(node);
   const focusable = isFocusable(node);
@@ -290,7 +315,9 @@ function recoveredRole(
       : "button";
   }
   if (hasHandler && hasName) return "button";
-  if (node.cursor === "pointer" && hasName) return "button";
+  if ((!currentRole || SKIP_ROLES.has(currentRole)) && node.cursor === "pointer" && hasName) {
+    return "button";
+  }
   return undefined;
 }
 
@@ -711,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; 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 {
@@ -786,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;
@@ -795,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(
@@ -807,6 +885,7 @@ function renderNodes(
   initialLines: string[],
   surfaces: CondSurface[] = [],
   activeScopeBlocks: ActiveScopeBlock[] = [],
+  visualSurfaces: VomVisualSurface[] = [],
 ): RenderState {
   const children = buildChildren(nodes);
   const state: RenderState = {
@@ -825,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);
@@ -1030,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 {
@@ -1058,6 +1147,7 @@ export function renderVom(scene: VomScene, options: VomOptions = {}): VomResult
     ],
     scene.surfaces,
     scene.activeScopeBlocks,
+    scene.visualSurfaces,
   );
 
   return {

packages/vom/src/types.ts

@@ -24,6 +24,8 @@ export interface VomNode {
   backendNodeId?: number;
   frameId?: string;
   contextScopeId?: string;
+  /** False for semantic-only nodes that cannot be addressed through CDP. */
+  referenceable?: boolean;
 
   role?: string;
   name?: string;
@@ -59,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 {
@@ -92,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 {

pnpm-lock.yaml

@@ -114,12 +114,6 @@ importers:
       '@deepseek-ai/dsh-llm':
         specifier: ^0.1.0-rc.6
         version: 0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-attachment@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-brand@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-brand@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1))(@deepseek-ai/dsh-timeout@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))
-      '@deepseek-ai/dsh-scope':
-        specifier: ^0.1.0-rc.6
-        version: 0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1))
-      '@deepseek-ai/dsh-skill':
-        specifier: ^0.1.0-rc.6
-        version: 0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1))(@deepseek-ai/dsh-llm@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-attachment@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-brand@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-brand@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1))(@deepseek-ai/dsh-timeout@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1))))(@deepseek-ai/dsh-scope@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)(@deepseek-ai/dsh-invariants@0.1.0-rc.6(@deepseek-ai/cordis@4.0.1)))
       '@deepseek-ai/dsh-tools':
         specifier: ^0.1.0-rc.6
         version: 0.1.0-rc.6(f8724372086ccc1457fc84e7becee2e0)

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; ...]`, the ref identifies a rendered canvas surface, not an interactable DOM control. Use `bsk screenshot --ref @eN --session <id>` to inspect its visible crop. 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: