refactor(vom): preserve complete canvas candidates with exact deduplication

feat(interaction): add scroll-to-element primitive

.github/workflows/ci.yml

@@ -37,6 +37,35 @@ jobs:
       - name: Run Rust tests
         run: cargo test --workspace --locked
 
+  windows-daemon:
+    name: Windows daemon, installer and cancellation regression tests
+    runs-on: windows-latest
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Run Windows named-pipe tests
+        run: cargo test -p bsk --lib --locked daemon::ipc::windows::tests
+
+      - name: Run Windows process liveness tests
+        run: cargo test -p bsk --lib --locked daemon::lockfile::tests
+
+      - name: Run Windows update tests
+        run: cargo test -p bsk --lib --locked cli::update::tests
+
+      - name: Run Windows update and cancellation process tests
+        run: cargo test -p bsk --test windows_update --test windows_parent_cancel --locked
+
+      - name: Run installer tests (Windows PowerShell 5.1)
+        shell: powershell
+        run: ./scripts/install-windows.test.ps1
+
+      - name: Run installer tests (PowerShell 7)
+        shell: pwsh
+        run: ./scripts/install-windows.test.ps1
+
   frontend:
     name: Frontend lint, typecheck, tests, build
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -7,6 +7,30 @@ Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
 
 ## [Unreleased]
 
+### Added
+
+- [Scroll-to element primitive](docs/scroll-to.md) across CLI, Extension and DSH Plugin,
+  with ancestor-clipped visible bounds, iframe support and cooperative cancellation
+
+## [0.2.1] - 2026-09-09
+
+### Changed
+- DSH Plugin: clarified installation, configuration, profile restart, and upgrade instructions
+
+### Fixed
+- CLI: reliable Windows self-updates, including executable replacement and daemon restart
+- CLI: Windows named-pipe connection continuity and stale daemon process detection
+- Windows installer: PowerShell 5.1 compatibility, path quoting, and staged executable replacement
+- CLI / DSH Plugin: cancellation propagation and upload/download cleanup when the parent process exits
+- Extension: tab ownership and session cleanup when agent tabs fail to open or borrowed tabs are returned or closed
+- Extension: navigation recovery when other extensions restrict Chrome DevTools Protocol access
+- Extension: background input filling, automatic append behavior, and verification of field values before reporting success
+- Extension: match observed form state to the correct element after page changes
+- Extension: UUID generation fallback for recording and overlays on insecure origins
+- Browser locale matching for regional language variants
+- DSH Plugin: observation state synchronization, thumbnail capture lifecycle, and stale preview cleanup
+- DSH Plugin: removed the obsolete client runtime host dependency
+
 ## [0.2.0] - 2026-09-02
 
 ### Added

Cargo.lock

@@ -134,7 +134,7 @@ dependencies = [
 
 [[package]]
 name = "bsk"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "anyhow",
  "base64",
@@ -169,7 +169,7 @@ dependencies = [
 
 [[package]]
 name = "bsk-protocol"
-version = "0.2.0"
+version = "0.2.1"
 dependencies = [
  "schemars",
  "semver",

Cargo.toml

@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]
 
 [workspace.package]
-version = "0.2.0"
+version = "0.2.1"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -43,7 +43,7 @@ rand = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }
 
 # Workspace crates (version required for `cargo publish` of dependents)
-bsk-protocol = { version = "0.2.0", path = "crates/bsk-protocol" }
+bsk-protocol = { version = "0.2.1", path = "crates/bsk-protocol" }
 
 [profile.release]
 strip = "symbols"

README.md

@@ -147,20 +147,26 @@ Start a new Agent session and write a prompt that needs the browser, for example
 Using [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`)?
 BrowserSkill ships a first-class dsh plugin on npm as
 [`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin).
-It injects native `browser_*` tools (no shelling out to `bsk`) and a live Web UI
-overlay of each Agent Window.
+It gives the agent native `browser_*` tools and a live view of its browser sessions
+in the Web UI. The plugin runs `bsk` on the agent's behalf.
 
-Add it to a dsh profile, then start that profile:
+Install the `bsk` CLI and connect the browser extension first. Then add the plugin
+to a dsh profile and start it (replace `web` with your profile name):
 
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
 
-The plugin carries its own copy of the skill, so `bsk install-skill` is not needed
-for dsh — but the `bsk` CLI and the browser extension are still prerequisites. See
-the [plugin README](packages/dsh-plugin-browserskill/README.md) for the tool list,
-configuration, and the observation overlay.
+The plugin includes the `browser-skill` skill, so `bsk install-skill` is not needed
+for dsh. Installed plugins do not update automatically. To upgrade this plugin:
+
+```sh
+dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
+```
+
+Restart the profile after upgrading. See the
+[plugin README](packages/dsh-plugin-browserskill/README.md) for usage and configuration.
 
 ## How It Works
 
@@ -201,6 +207,9 @@ through the [plugin](#deepseek-harness-plugin): the agent calls injected
 
 ## For Developers
 
+The [scroll-to primitive reference](docs/scroll-to.md) covers its CLI, protocol
+and plugin entry points, visible bounds and interruption behavior.
+
 The repository is a Cargo + pnpm workspace:
 
 - `crates/bsk-cli` — `bsk` CLI and local daemon

README.zh-CN.md

@@ -125,16 +125,22 @@ bsk install-skill
 
 ## DeepSeek Harness 插件
 
-在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它会注入原生 `browser_*` 工具（无需再通过 Shell 调用 `bsk`），并在 Web UI 中实时观察每个 Agent Window。
+在用 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）？BrowserSkill 提供了官方 dsh 插件，已发布到 npm：[`@wxg-prc-cpg/browser-skill-dsh-plugin`](https://www.npmjs.com/package/@wxg-prc-cpg/browser-skill-dsh-plugin)。它为 Agent 提供原生 `browser_*` 工具，由插件代为调用 `bsk`，并在 Web UI 中实时展示浏览器会话。
 
-把它装进某个 dsh profile，然后启动该 profile：
+先安装 `bsk` CLI 并连接浏览器扩展，再将插件装进 dsh profile 并启动（将 `web` 替换为你的 profile 名称）：
 
 ```sh
 dsh plugin --profile web add @wxg-prc-cpg/browser-skill-dsh-plugin
 dsh --profile web
 ```
 
-插件自带 skill，所以在 dsh 下无需执行 `bsk install-skill`；但 `bsk` CLI 和浏览器扩展仍是前置条件。工具清单、配置项与观察浮层见[插件 README](packages/dsh-plugin-browserskill/README.md)。
+插件自带 `browser-skill` skill，所以在 dsh 下无需执行 `bsk install-skill`。已安装的插件不会自动更新；升级此插件请运行：
+
+```sh
+dsh plugin --profile web update @wxg-prc-cpg/browser-skill-dsh-plugin --latest
+```
+
+升级后重启该 profile。用法与配置见[插件 README](packages/dsh-plugin-browserskill/README.md)。
 
 ## 工作原理
 
@@ -171,6 +177,8 @@ Agent 不直接与浏览器通信。它通过 `bsk` CLI 下发浏览器任务；
 
 ## 面向开发者
 
+[scroll-to 原语说明](docs/scroll-to.md)介绍 CLI、协议和插件入口，以及可见区域、错误和中断语义。
+
 本仓库是 Cargo + pnpm workspace：
 
 - `crates/bsk-cli` — `bsk` CLI 与本地 daemon

apps/extension/package.json

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

apps/extension/src/browser-driver/__tests__/chromium-cdp.test.ts

@@ -29,6 +29,24 @@ function fakeApi() {
 }
 
 describe("ChromiumCdp", () => {
+  it("changes attachment identity only across real debugger attachments", async () => {
+    const { api, onEvent, onDetach } = fakeApi();
+    const cdp = new ChromiumCdp(api);
+    expect(cdp.getAttachmentId(4)).toBeUndefined();
+    await cdp.ensureAttached(4);
+    const first = cdp.getAttachmentId(4);
+    expect(first).toBeTruthy();
+    await cdp.ensureAttached(4);
+    onEvent.fire({ tabId: 4 }, "Target.attachedToTarget", { sessionId: "child" });
+    expect(cdp.getAttachmentId(4)).toBe(first);
+    onDetach.fire({ tabId: 4 }, "target_closed");
+    expect(cdp.getAttachmentId(4)).toBeUndefined();
+    await cdp.ensureAttached(4);
+    expect(cdp.getAttachmentId(4)).not.toBe(first);
+    await cdp.detach(4);
+    expect(cdp.getAttachmentId(4)).toBeUndefined();
+  });
+
   it("discovers multiple iframe targets and recursively routes nested OOPIF commands", async () => {
     const { api, onEvent } = fakeApi();
     (api.sendCommand as ReturnType<typeof vi.fn>).mockImplementation(
@@ -254,6 +272,69 @@ describe("ChromiumCdp", () => {
     expect(cdp.isAttached(7)).toBe(false);
   });
 
+  it.each([
+    false,
+    true,
+  ])("waits for detach before reconnecting a returned tab (detach rejects: %s)", async (rejectDetach) => {
+    const { api } = fakeApi();
+    const attached = new Set<number>();
+    let finishDetach!: () => void;
+    vi.mocked(api.attach).mockImplementation(async ({ tabId }) => {
+      if (attached.has(tabId!)) throw new Error("Another debugger is already attached");
+      attached.add(tabId!);
+    });
+    vi.mocked(api.detach).mockImplementation(async ({ tabId }) => {
+      attached.delete(tabId!);
+    });
+    vi.mocked(api.detach).mockImplementationOnce(
+      ({ tabId }) =>
+        new Promise<void>((resolve, reject) => {
+          finishDetach = () => {
+            attached.delete(tabId!);
+            if (rejectDetach) reject(new Error("tab already detached"));
+            else resolve();
+          };
+        }),
+    );
+    const cdp = new ChromiumCdp(api);
+    cdp.trackSessionTab("aa11", 7);
+    await cdp.ensureAttached(7);
+    const returning = cdp.releaseSessionTab("aa11", 7);
+    await vi.waitFor(() => expect(api.detach).toHaveBeenCalledOnce());
+    let duplicateDetachFinished = false;
+    const duplicateDetach = cdp.detach(7).then(() => {
+      duplicateDetachFinished = true;
+    });
+
+    cdp.trackSessionTab("bb22", 7);
+    // Register rejection handlers immediately; the pre-fix driver rejects
+    // both commands while the browser still has the previous attachment.
+    const pending = Promise.allSettled([
+      cdp.send(7, "Runtime.evaluate", { expression: "document.title" }),
+      cdp.send(7, "DOM.getDocument"),
+    ]);
+    await cdp.send(8, "DOM.getDocument");
+    const finishedEarly = duplicateDetachFinished;
+    finishDetach();
+    await Promise.all([returning, duplicateDetach]);
+
+    expect(await pending).toEqual([
+      { status: "fulfilled", value: { ok: true } },
+      { status: "fulfilled", value: { ok: true } },
+    ]);
+    expect(finishedEarly).toBe(false);
+    expect(vi.mocked(api.attach).mock.calls.filter(([target]) => target.tabId === 7)).toHaveLength(
+      2,
+    );
+    expect(cdp.isAttached(7)).toBe(true);
+    expect(cdp.isAttached(8)).toBe(true);
+    await cdp.detachSession("bb22");
+    expect(api.detach).toHaveBeenCalledTimes(2);
+    expect(cdp.isAttached(7)).toBe(false);
+    expect(attached.has(7)).toBe(false);
+    expect(cdp.isAttached(8)).toBe(true);
+  });
+
   it("detachAll() iterates every cached tab", async () => {
     const { api } = fakeApi();
     const cdp = new ChromiumCdp(api);
@@ -651,6 +732,155 @@ describe("ChromiumCdp", () => {
     expect(cdp.networkEntriesSince(33, 0, 50, 1000).entries[0].url).toBeUndefined();
   });
 
+  it("releases only the returning session's claim on a tab", async () => {
+    const { api } = fakeApi();
+    const cdp = new ChromiumCdp(api);
+    await cdp.ensureAttached(1);
+    await cdp.ensureAttached(2);
+    cdp.trackSessionTab("aa11", 1);
+    cdp.trackSessionTab("bb22", 1);
+    cdp.trackSessionTab("aa11", 2);
+
+    await cdp.releaseSessionTab("unknown", 1);
+    await cdp.releaseSessionTab("aa11", 1);
+    expect(api.detach).not.toHaveBeenCalled();
+
+    await cdp.releaseSessionTab("bb22", 1);
+    await cdp.releaseSessionTab("bb22", 1);
+    expect(api.detach).toHaveBeenCalledExactlyOnceWith({ tabId: 1 });
+    expect(cdp.isAttached(2)).toBe(true);
+
+    await cdp.detachSession("aa11");
+    expect(api.detach).toHaveBeenCalledTimes(2);
+    expect(api.detach).toHaveBeenLastCalledWith({ tabId: 2 });
+  });
+
+  it.each([
+    false,
+    true,
+  ])("releases a tab with an attachment in flight (new owner: %s)", async (newOwner) => {
+    const { api } = fakeApi();
+    let finishAttach!: () => void;
+    vi.mocked(api.attach).mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishAttach = resolve;
+        }),
+    );
+    const cdp = new ChromiumCdp(api);
+    cdp.trackSessionTab("aa11", 1);
+    const attaching = cdp.ensureAttached(1);
+    const releasing = cdp.releaseSessionTab("aa11", 1);
+    if (newOwner) cdp.trackSessionTab("bb22", 1);
+    finishAttach();
+    await Promise.all([attaching, releasing]);
+
+    expect(cdp.isAttached(1)).toBe(newOwner);
+    expect(api.detach).toHaveBeenCalledTimes(newOwner ? 0 : 1);
+  });
+
+  it("stops accepting dialogs on a returned tab even when another session keeps CDP attached", async () => {
+    const { api, onEvent } = fakeApi();
+    let controlled = true;
+    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog: () => controlled });
+    cdp.trackSessionTab("aa11", 1);
+    cdp.trackSessionTab("bb22", 1);
+    await cdp.ensureAttached(1);
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
+      type: "confirm",
+      message: "before return",
+    });
+    await vi.waitFor(() => expect(cdp.dialogsSince(1, 0)).toHaveLength(1));
+    vi.mocked(api.sendCommand).mockClear();
+
+    controlled = false;
+    await cdp.releaseSessionTab("aa11", 1);
+    expect(cdp.isAttached(1)).toBe(true);
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
+      type: "confirm",
+      message: "after return",
+    });
+    await Promise.resolve();
+    expect(api.sendCommand).not.toHaveBeenCalled();
+    expect(cdp.dialogsSince(1, 0)).toHaveLength(1);
+
+    controlled = true;
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", {
+      type: "alert",
+      message: "borrowed again",
+    });
+    await vi.waitFor(() => expect(cdp.dialogsSince(1, 0)).toHaveLength(2));
+    expect(api.sendCommand).toHaveBeenCalledExactlyOnceWith(
+      { tabId: 1 },
+      "Page.handleJavaScriptDialog",
+      { accept: true },
+    );
+  });
+
+  it("ignores dialog events after detach, including a pending eligibility check", async () => {
+    const { api, onEvent } = fakeApi();
+    let resolveEligibility!: (value: boolean) => void;
+    const shouldAutoAcceptDialog = vi.fn(
+      () =>
+        new Promise<boolean>((resolve) => {
+          resolveEligibility = resolve;
+        }),
+    );
+    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog });
+    await cdp.ensureAttached(1);
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
+    await cdp.detach(1);
+    resolveEligibility(true);
+    await Promise.resolve();
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
+
+    expect(shouldAutoAcceptDialog).toHaveBeenCalledOnce();
+    expect(api.sendCommand).not.toHaveBeenCalledWith(
+      expect.anything(),
+      "Page.handleJavaScriptDialog",
+      expect.anything(),
+    );
+    expect(cdp.dialogsSince(1, 0)).toEqual([]);
+  });
+
+  it("does not accept dialogs when the tab's current scope cannot be determined", async () => {
+    const { api, onEvent } = fakeApi();
+    const shouldAutoAcceptDialog = vi.fn(async () => {
+      throw new Error("tab is gone");
+    });
+    const cdp = new ChromiumCdp(api, { shouldAutoAcceptDialog });
+    await cdp.ensureAttached(1);
+    vi.mocked(api.sendCommand).mockClear();
+
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "confirm" });
+    await Promise.resolve();
+
+    expect(shouldAutoAcceptDialog).toHaveBeenCalledWith(1);
+    expect(api.sendCommand).not.toHaveBeenCalled();
+    expect(cdp.dialogsSince(1, 0)).toEqual([]);
+  });
+
+  it("does not restore dialog state when an acceptance completes after detach", async () => {
+    const { api, onEvent } = fakeApi();
+    const cdp = new ChromiumCdp(api);
+    await cdp.ensureAttached(1);
+    let finishAccept!: () => void;
+    vi.mocked(api.sendCommand).mockImplementationOnce(
+      () =>
+        new Promise<void>((resolve) => {
+          finishAccept = resolve;
+        }),
+    );
+
+    onEvent.fire({ tabId: 1 }, "Page.javascriptDialogOpening", { type: "alert" });
+    await cdp.detach(1);
+    finishAccept();
+    await Promise.resolve();
+
+    expect(cdp.dialogsSince(1, 0)).toEqual([]);
+    expect(cdp.dialogCursor(1)).toBe(0);
+  });
+
   it("detachSession only detaches tabs no other session owns", async () => {
     const { api } = fakeApi();
     const cdp = new ChromiumCdp(api);

apps/extension/src/browser-driver/chromium-cdp.ts

@@ -164,7 +164,9 @@ async function settleBeforeDeadline(promises: Promise<void>[], deadline: number)
 export class ChromiumCdp {
   private readonly api: CdpDebuggerApi;
   private readonly attachedTabs = new Set<number>();
+  private readonly attachmentIds = new Map<number, string>();
   private readonly attachInFlight = new Map<number, Promise<void>>();
+  private readonly detachInFlight = new Map<number, Promise<void>>();
   private readonly tabOwners = new Map<number, Set<string>>();
   private readonly dialogBuffers = new Map<number, JavaScriptDialogInfo[]>();
   private readonly dialogSequences = new Map<number, number>();
@@ -182,7 +184,13 @@ export class ChromiumCdp {
   private networkSubscription: { dispose(): void } | null = null;
   private frameTargetSubscription: { dispose(): void } | null = null;
 
-  constructor(api: CdpDebuggerApi = chromeDebuggerApi) {
+  constructor(
+    api: CdpDebuggerApi = chromeDebuggerApi,
+    private readonly options: {
+      /** CDP observation alone does not authorize dismissing user dialogs. */
+      shouldAutoAcceptDialog?: (tabId: number) => boolean | Promise<boolean>;
+    } = {},
+  ) {
     this.api = api;
     this.bindAutoDetach();
     this.bindDialogHandler();
@@ -191,8 +199,17 @@ export class ChromiumCdp {
     this.bindFrameTargetHandler();
   }
 
+  /** Identity of this actual debugger attachment, independent of frame topology. */
+  getAttachmentId(tabId: number): string | undefined {
+    return this.attachmentIds.get(tabId);
+  }
+
   /** Attach to `tabId` if we haven't already in this driver. */
   async ensureAttached(tabId: number): Promise<void> {
+    // Returning a tab clears the cache before Chrome finishes detaching.
+    // New observers must wait before opening the next connection to that tab.
+    const detaching = this.detachInFlight.get(tabId);
+    if (detaching) await detaching;
     if (this.attachedTabs.has(tabId)) return;
     const existing = this.attachInFlight.get(tabId);
     if (existing) {
@@ -206,6 +223,7 @@ export class ChromiumCdp {
         await this.enableConsoleDomains(tabId);
         await this.enableNetworkDomainBestEffort(tabId);
         this.attachedTabs.add(tabId);
+        this.attachmentIds.set(tabId, crypto.randomUUID());
         await this.enableFrameDiscovery({ tabId }).catch((err) => {
           console.debug("[bsk cdp] frame discovery unavailable", { tabId, err });
         });
@@ -425,20 +443,32 @@ export class ChromiumCdp {
 
   /** Detach if attached; never throws. */
   async detach(tabId: number): Promise<void> {
+    const existing = this.detachInFlight.get(tabId);
+    if (existing) {
+      await existing;
+      return;
+    }
     this.attachInFlight.delete(tabId);
     if (!this.attachedTabs.has(tabId)) return;
     this.attachedTabs.delete(tabId);
+    this.attachmentIds.delete(tabId);
     this.clearDialogState(tabId);
     this.clearConsoleState(tabId);
     this.clearNetworkState(tabId);
     this.clearFrameState(tabId);
-    try {
-      await this.api.detach({ tabId });
-    } catch (err) {
-      // Tab may already be gone — Chrome auto-detaches on close. Log
-      // at debug so production builds aren't noisy.
-      console.debug("[bsk cdp] detach failed (likely tab already closed)", err);
-    }
+    const detach = (async () => {
+      try {
+        await this.api.detach({ tabId });
+      } catch (err) {
+        // Tab may already be gone — Chrome auto-detaches on close. Log
+        // at debug so production builds aren't noisy.
+        console.debug("[bsk cdp] detach failed (likely tab already closed)", err);
+      }
+    })().finally(() => {
+      this.detachInFlight.delete(tabId);
+    });
+    this.detachInFlight.set(tabId, detach);
+    await detach;
   }
 
   /** True iff `ensureAttached(tabId)` has succeeded since the last detach. */
@@ -453,6 +483,17 @@ export class ChromiumCdp {
     this.tabOwners.set(tabId, owners);
   }
 
+  /** Release one session's claim, preserving attachments still used by another. */
+  async releaseSessionTab(sessionId: string, tabId: number): Promise<void> {
+    const owners = this.tabOwners.get(tabId);
+    if (!owners?.delete(sessionId) || owners.size > 0) return;
+    this.tabOwners.delete(tabId);
+    // An observation may still be attaching when the tab is returned. Wait
+    // for it so detach cannot miss the attachment or remove a new owner's claim.
+    await this.attachInFlight.get(tabId)?.catch(() => {});
+    if (!this.tabOwners.has(tabId)) await this.detach(tabId);
+  }
+
   /** Subscribe to all CDP events. Returned disposable removes the listener. */
   onEvent(handler: (source: CdpDebuggee, method: string, params: unknown) => void): {
     dispose(): void;
@@ -469,6 +510,7 @@ export class ChromiumCdp {
     this.attachInFlight.clear();
     this.tabOwners.clear();
     this.attachedTabs.clear();
+    this.attachmentIds.clear();
     this.dialogBuffers.clear();
     this.dialogSequences.clear();
     this.consoleBuffers.clear();
@@ -639,13 +681,23 @@ export class ChromiumCdp {
   }
 
   private async onJavaScriptDialogOpening(tabId: number, params: unknown): Promise<void> {
+    if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
     const parsed = parseDialogOpeningParams(params);
     try {
+      if (
+        this.options.shouldAutoAcceptDialog &&
+        !(await this.options.shouldAutoAcceptDialog(tabId))
+      ) {
+        return;
+      }
+      // The tab may have been returned while its current scope was checked.
+      if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
       const handleParams: { accept: boolean; promptText?: string } = { accept: true };
       if (parsed.type === "prompt") {
         handleParams.promptText = parsed.defaultPrompt ?? "";
       }
       await this.api.sendCommand({ tabId }, "Page.handleJavaScriptDialog", handleParams);
+      if (!this.attachedTabs.has(tabId) && !this.attachInFlight.has(tabId)) return;
       const sequence = (this.dialogSequences.get(tabId) ?? 0) + 1;
       this.dialogSequences.set(tabId, sequence);
       this.appendDialog(tabId, {
@@ -805,6 +857,7 @@ export class ChromiumCdp {
     const listener = (source: chrome.debugger.Debuggee, _reason: string) => {
       if (typeof source.tabId === "number") {
         this.attachedTabs.delete(source.tabId);
+        this.attachmentIds.delete(source.tabId);
         this.attachInFlight.delete(source.tabId);
         this.tabOwners.delete(source.tabId);
         this.clearDialogState(source.tabId);
@@ -835,15 +888,9 @@ export class ChromiumCdp {
 
   /** Detach tabs only when no other live session has claimed them. */
   async detachSession(sessionId: string): Promise<void> {
-    const tabsToDetach: number[] = [];
-    for (const [tabId, owners] of this.tabOwners) {
-      owners.delete(sessionId);
-      if (owners.size === 0) {
-        this.tabOwners.delete(tabId);
-        tabsToDetach.push(tabId);
-      }
-    }
-    await Promise.all(tabsToDetach.map((tabId) => this.detach(tabId)));
+    await Promise.all(
+      Array.from(this.tabOwners.keys(), (tabId) => this.releaseSessionTab(sessionId, tabId)),
+    );
   }
 }
 

apps/extension/src/entrypoints/background.ts

@@ -51,7 +51,12 @@ export default defineBackground(() => {
   const controller = new ConnectionController();
   const transport = new WSTransport({ url: __BSK_DAEMON_WS_URL__ });
   const sessions = new SessionManager();
-  const cdp = new ChromiumCdp();
+  const cdp = new ChromiumCdp(undefined, {
+    shouldAutoAcceptDialog: async (tabId) => {
+      const tab = await chrome.tabs.get(tabId);
+      return sessions.findByWindowId(tab.windowId) !== null;
+    },
+  });
   const sessionsLive = attachSessionsLiveFlag({ manager: sessions });
   let overlayGeneration = 0;
   const controlModes = new Map<string, OverlayMode>();

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

@@ -49,6 +49,47 @@ describe("ToolDispatcher", () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    "tool.snapshot",
+    "tool.evaluate",
+    "tool.get_html",
+    "tool.console",
+  ])("annotates Chrome extension-access failures from %s", async (method) => {
+    const tab = { id: 7, windowId: 4242, active: true, url: "https://example.test" };
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => tab),
+        query: vi.fn(async () => [tab]),
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: vi.fn(),
+        ensureActiveTab: vi.fn(),
+      },
+    });
+    await sessions.start("test");
+    const error = new Error("Cannot access a chrome-extension:// URL of different extension");
+    const cdp = {
+      send: vi.fn().mockRejectedValue(error),
+      ensureConsoleCapture: vi.fn().mockRejectedValue(error),
+      consoleEntriesSince: vi.fn(),
+    } as unknown as TestDispatcherCdp;
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp });
+    dispatcher.start();
+    deliver(makeRequest(method, { session_id: "test", expression: "document.title" }));
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+    expect(sent[0]).toMatchObject({
+      error: {
+        code: "cdp_failed",
+        data: { reason: "cdp_extension_access_denied" },
+      },
+    });
+    dispatcher.stop();
+  });
+
   it("uses the configured recording runtime for start and stop", async () => {
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({
@@ -558,6 +599,79 @@ describe("ToolDispatcher", () => {
     expect(onSessionsChanged).toHaveBeenCalledTimes(2);
   });
 
+  it.each([
+    "focus",
+    "blur",
+    "scroll_to",
+  ] as const)("routes %s with hover cleanup and cooperative cancellation", async (action) => {
+    const tab = { id: 7, windowId: 4242, active: true };
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => tab),
+        query: vi.fn(async () => [tab]),
+        sendMessage: vi.fn(async () => undefined),
+      },
+    });
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: async () => 4242,
+        remove: async () => {},
+        ensureActiveTab: async () => 7,
+      },
+    });
+    const ctx = await sessions.start("aa11");
+    ctx.refStore.set("e1", 12, { tabId: 7 });
+    const { transport, sent, deliver } = fakeTransport();
+    const onBrowserControlResumed = vi.fn();
+    let resolveNode: ((value: object) => void) | undefined;
+    const cdp = {
+      send: vi.fn(async (_tabId: number, method: string) => {
+        if (method === "DOM.resolveNode")
+          return new Promise((resolve) => {
+            resolveNode = resolve;
+          });
+        if (method === "Runtime.callFunctionOn") return { result: { value: true } };
+        return {};
+      }),
+    } as unknown as TestDispatcherCdp;
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp, onBrowserControlResumed });
+    const hover = dispatcher as unknown as {
+      rememberHover: (sessionId: string, result: object) => void;
+      setHoverBypass: (sessionId: string, tabId: number, enabled: boolean) => Promise<void>;
+    };
+    hover.rememberHover("aa11", { tab_id: 7, x: 10, y: 20 });
+    await hover.setHoverBypass("aa11", 7, true);
+    dispatcher.start();
+    deliver(makeRequest(`tool.${action}`, { session_id: "aa11", ref: "e1" }));
+    await vi.waitFor(() => expect(resolveNode).toBeDefined());
+    expect(onBrowserControlResumed).toHaveBeenCalledWith("aa11");
+    deliver({ id: "cancel-focus", method: "cancel", params: { rpc_id: "r-1" } });
+    resolveNode!({ object: { objectId: "focus-target" } });
+    await vi.waitFor(() => expect(sent).toHaveLength(2));
+    expect(sent).toContainEqual({ id: "cancel-focus", result: { cancelled: true } });
+    expect(sent).toContainEqual({
+      id: "r-1",
+      error: expect.objectContaining({ code: "cancelled" }),
+    });
+    expect(cdp.send).not.toHaveBeenCalledWith(7, "DOM.focus", expect.anything());
+    expect(cdp.send).not.toHaveBeenCalledWith(7, "Runtime.callFunctionOn", expect.anything());
+    if (action === "scroll_to") {
+      expect(cdp.send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", {
+        objectGroup: expect.any(String),
+      });
+    } else {
+      expect(cdp.send).toHaveBeenCalledWith(7, "Runtime.releaseObject", {
+        objectId: "focus-target",
+      });
+    }
+    expect(chrome.tabs.sendMessage).toHaveBeenCalledWith(
+      7,
+      expect.objectContaining({ enabled: false }),
+    );
+    expect(dispatcher.inflightAbortControllers.size).toBe(0);
+    dispatcher.stop();
+  });
+
   it("invokes onBrowserControlResumed for browser-control tools but not passive reads", async () => {
     vi.stubGlobal("chrome", {
       tabs: {
@@ -747,6 +861,135 @@ describe("ToolDispatcher", () => {
     );
   });
 
+  it.each([
+    { tab_id: 7, code: "not_found" },
+    { tab_id: undefined, code: "invalid_params" },
+  ])("keeps hover when tab_return is rejected with $code", async ({ tab_id, code }) => {
+    const sendMessage = vi.fn(async () => undefined);
+    vi.stubGlobal("chrome", {
+      tabs: {
+        sendMessage,
+        get: vi.fn(async () => ({ id: 7, windowId: 100, active: true })),
+        query: vi.fn(async () => [{ id: 7, windowId: 100, active: true }]),
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 100),
+        remove: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
+      },
+    });
+    await sessions.start("aa11");
+    const cdp = {
+      send: vi.fn(async <T>() => ({}) as T),
+      detachSession: vi.fn(async () => {}),
+      releaseSessionTab: vi.fn(async () => {}),
+    };
+    const dispatcher = new ToolDispatcher({
+      transport,
+      sessions,
+      cdp: cdp as unknown as TestDispatcherCdp,
+    });
+    const helpers = dispatcher as unknown as {
+      rememberHover: (sessionId: string, result: unknown) => unknown;
+      setHoverBypass: (sessionId: string, tabId: number, enabled: boolean) => Promise<void>;
+      withHoverReassert: <T>(
+        params: { session_id: string; tab_id?: number },
+        work: () => Promise<T>,
+      ) => Promise<T>;
+    };
+    helpers.rememberHover("aa11", { tab_id: 7, x: 10, y: 20 });
+    await helpers.setHoverBypass("aa11", 7, true);
+    dispatcher.start();
+    deliver(makeRequest("tool.tab_return", { session_id: "aa11", tab_id }));
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+
+    expect(sent[0]).toMatchObject({ error: { code } });
+    expect(cdp.releaseSessionTab).not.toHaveBeenCalled();
+    expect(sendMessage).not.toHaveBeenCalledWith(7, expect.objectContaining({ enabled: false }));
+    await helpers.withHoverReassert({ session_id: "aa11", tab_id: 7 }, async () => ({}));
+    expect(cdp.send).toHaveBeenCalledExactlyOnceWith(7, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: 10,
+      y: 20,
+    });
+    dispatcher.stop();
+  });
+
+  it("releases the returned tab's hover before moving it and leaves other tabs alone", async () => {
+    const sendMessage = vi.fn(async () => undefined);
+    const move = vi.fn(async () => {
+      expect(sendMessage).toHaveBeenCalledWith(7, expect.objectContaining({ enabled: false }));
+      return { id: 7, windowId: 200, index: 4 };
+    });
+    vi.stubGlobal("chrome", {
+      tabs: { sendMessage, move },
+      windows: { get: vi.fn(async () => ({ id: 200 })) },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 100),
+        remove: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
+      },
+    });
+    const ctx = await sessions.start("aa11");
+    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
+    const cdp = {
+      send: vi.fn(async <T>() => ({}) as T),
+      detachSession: vi.fn(async () => {}),
+      releaseSessionTab: vi.fn(async () => {}),
+    };
+    const dispatcher = new ToolDispatcher({
+      transport,
+      sessions,
+      cdp: cdp as unknown as TestDispatcherCdp,
+    });
+    const helpers = dispatcher as unknown as {
+      rememberHover: (sessionId: string, result: unknown) => unknown;
+      setHoverBypass: (sessionId: string, tabId: number, enabled: boolean) => Promise<void>;
+      withHoverReassert: <T>(
+        params: { session_id: string; tab_id?: number },
+        work: () => Promise<T>,
+      ) => Promise<T>;
+    };
+    for (const [sessionId, tabId] of [
+      ["aa11", 7],
+      ["aa11", 8],
+      ["bb22", 9],
+    ] as const) {
+      helpers.rememberHover(sessionId, { tab_id: tabId, x: 10, y: 20 });
+      await helpers.setHoverBypass(sessionId, tabId, true);
+    }
+    dispatcher.start();
+    deliver(makeRequest("tool.tab_return", { session_id: "aa11", tab_id: 7 }));
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+
+    expect(sent[0]).toMatchObject({ result: { tab_id: 7, returned_to_window_id: 200 } });
+    expect(cdp.releaseSessionTab).toHaveBeenCalledExactlyOnceWith("aa11", 7);
+    await helpers.withHoverReassert({ session_id: "aa11", tab_id: 7 }, async () => ({}));
+    expect(cdp.send).not.toHaveBeenCalled();
+    for (const [sessionId, tabId] of [
+      ["aa11", 8],
+      ["bb22", 9],
+    ] as const) {
+      expect(sendMessage).not.toHaveBeenCalledWith(
+        tabId,
+        expect.objectContaining({ enabled: false }),
+      );
+      await helpers.withHoverReassert({ session_id: sessionId, tab_id: tabId }, async () => ({}));
+      expect(cdp.send).toHaveBeenLastCalledWith(tabId, "Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: 10,
+        y: 20,
+      });
+    }
+    dispatcher.stop();
+  });
+
   it("transfers hover overlay bypass ownership between sessions", async () => {
     vi.stubGlobal("chrome", {
       tabs: {

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

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import type { RpcError } from "@/transport/types";
+import { cdpError, classifyCdpError } from "../errors";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+
+describe("CDP extension access errors", () => {
+  it("classifies both Chrome Error instances and string failures", () => {
+    for (const error of [new Error(denied), denied]) {
+      expect(cdpError(error)).toEqual({
+        code: "cdp_failed",
+        message: denied,
+        data: { reason: "cdp_extension_access_denied" },
+      });
+    }
+  });
+
+  it("preserves transfer outcome and cleanup instructions when CDP was denied", () => {
+    const error: RpcError = {
+      code: "cdp_failed",
+      message: denied,
+      data: {
+        reason: "transfer_outcome_unknown",
+        effect_state: "unknown",
+        cleanup_state: "failed",
+      },
+    };
+    expect(classifyCdpError(error)).toBe(error);
+  });
+
+  it("leaves other error codes and unrelated debugger failures unchanged", () => {
+    for (const error of [
+      { code: "permission_denied", message: denied },
+      { code: "cdp_failed", message: "Another debugger is already attached" },
+    ] satisfies RpcError[]) {
+      expect(classifyCdpError(error)).toBe(error);
+    }
+  });
+});

apps/extension/src/tools/__tests__/file-transfer.test.ts

@@ -436,6 +436,8 @@ describe("file transfer tools", () => {
         if (method === "DOM.getContentQuads") {
           return { quads: [[10, 20, 210, 20, 210, 120, 10, 120]] };
         }
+        if (method === "Runtime.evaluate")
+          return { result: { value: { width: 400, height: 300 } } };
         if (method === "Page.getLayoutMetrics") {
           return { cssLayoutViewport: { clientWidth: 400, clientHeight: 300 } };
         }

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

@@ -0,0 +1,573 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import type { CdpRunner } from "@/tools/shared";
+import { handleFill } from "../interaction";
+
+interface ScriptParams {
+  functionDeclaration: string;
+  arguments?: Array<{ value: unknown }>;
+}
+
+async function setup(markup = '<input value="old">') {
+  document.body.innerHTML = markup;
+  const element = document.body.firstElementChild as HTMLInputElement;
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("aa11");
+  ctx.refStore.set("e1", 12, { tabId: 4 });
+  const script = vi.fn(async (params: ScriptParams): Promise<unknown> => {
+    try {
+      const fn = new Function(`return (${params.functionDeclaration})`)();
+      return {
+        result: {
+          value: await fn.apply(
+            element,
+            (params.arguments ?? []).map((arg) => arg.value),
+          ),
+        },
+      };
+    } catch {
+      return { exceptionDetails: { text: "test page script failed" } };
+    }
+  });
+  // Number/email controls have a browser caret even though their selection
+  // getters return null. Model that caret instead of assuming it is at the end.
+  const hiddenCaret = { start: 0, end: 0 };
+  const moveToEnd = vi.fn(async () => {
+    if (typeof element.selectionStart === "number") {
+      element.setSelectionRange(element.value.length, element.value.length);
+    } else {
+      hiddenCaret.start = hiddenCaret.end = element.value.length;
+    }
+  });
+  const insert = vi.fn(async (text: string) => {
+    const focused = document.activeElement as HTMLInputElement;
+    if (focused.readOnly || focused.disabled) return;
+    const start = focused.selectionStart ?? hiddenCaret.start;
+    const end = focused.selectionEnd ?? hiddenCaret.end;
+    const value = focused.value.slice(0, start) + text + focused.value.slice(end);
+    focused.value = focused.maxLength >= 0 ? value.slice(0, focused.maxLength) : value;
+    hiddenCaret.start = hiddenCaret.end = Math.min(start + text.length, focused.value.length);
+    focused.dispatchEvent(new Event("input", { bubbles: true }));
+  });
+  const release = vi.fn(async () => ({}));
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    switch (method) {
+      case "DOM.describeNode":
+        return {
+          node: {
+            nodeName: element.tagName,
+            attributes: Array.from(element.attributes).flatMap((attr) => [attr.name, attr.value]),
+          },
+        };
+      case "DOM.scrollIntoViewIfNeeded":
+        return {};
+      case "DOM.focus":
+        element.focus();
+        return {};
+      case "DOM.resolveNode":
+        return { object: { objectId: "fill-target" } };
+      case "Runtime.callFunctionOn":
+        return script(params as ScriptParams);
+      case "Input.insertText":
+        await insert((params as { text: string }).text);
+        return {};
+      case "Input.dispatchKeyEvent":
+        if ((params as { commands?: string[] }).commands?.includes("moveToEndOfDocument")) {
+          await moveToEnd();
+        }
+        return {};
+      case "Runtime.releaseObject":
+        return release();
+      default:
+        throw new Error(`unexpected ${method}`);
+    }
+  });
+  return {
+    element,
+    hiddenCaret,
+    moveToEnd,
+    script,
+    insert,
+    release,
+    send,
+    fill: (value = "hello", clearBefore = true, signal?: AbortSignal) =>
+      handleFill(
+        manager,
+        { session_id: "aa11", ref: "e1", value, clear_before: clearBefore },
+        {
+          cdp: { send: send as CdpRunner["send"] },
+          tabsApi: {
+            get: async (id) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab,
+            query: async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab],
+          },
+          signal,
+        },
+      ),
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+});
+
+describe("fill result verification", () => {
+  it.each([
+    "readonly",
+    "disabled",
+  ])("preserves a %s field before rejecting it", async (attribute) => {
+    const h = await setup(`<input ${attribute} value="old">`);
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "target_not_fillable" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    "checkbox",
+    "radio",
+    "range",
+    "date",
+    "file",
+  ])("rejects an unsupported %s input before clearing", async (type) => {
+    const h = await setup(`<input type="${type}">`);
+    const before = h.element.value;
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "target_not_fillable" },
+    });
+    expect(h.element.value).toBe(before);
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("rejects an overlong value before clearing", async () => {
+    const h = await setup('<input maxlength="3" value="old">');
+    expect(await h.fill()).toMatchObject({
+      code: "invalid_params",
+      message: /maxlength/,
+      data: { reason: "fill_value_invalid" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    true,
+    false,
+  ])("classifies a DOM.focus rejection on a disabled=%s target", async (disabled) => {
+    const h = await setup(`<input ${disabled ? "disabled" : ""} value="old">`);
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      if (method === "DOM.focus") throw new Error("Element is not focusable");
+      return send(tabId, method, params);
+    });
+    expect(await h.fill()).toMatchObject({
+      code: disabled ? "invalid_params" : "cdp_failed",
+      data: { reason: disabled ? "target_not_fillable" : "fill_failed" },
+    });
+    expect(h.element.value).toBe("old");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("fills a background document without requiring foreground browser focus", async () => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("hello");
+  });
+
+  it("restores focus once after clearing without typing into another field", async () => {
+    const h = await setup();
+    const other = document.createElement("input");
+    document.body.append(other);
+    h.element.addEventListener("input", () => other.focus());
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("hello");
+    expect(other.value).toBe("");
+    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
+  });
+
+  it.each([
+    "focus",
+    "value",
+  ])("rechecks %s after restoring focus, without retrying again", async (action) => {
+    const h = await setup();
+    const other = document.createElement("input");
+    document.body.append(other);
+    h.element.addEventListener(
+      "input",
+      () => {
+        other.focus();
+        h.element.addEventListener("focus", () => {
+          if (action === "focus") queueMicrotask(() => other.focus());
+          else h.element.value = "changed";
+        });
+      },
+      { once: true },
+    );
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: action === "focus" ? "fill_focus_lost" : "fill_target_changed" },
+    });
+    expect(other.value).toBe("");
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(h.send.mock.calls.filter(([, method]) => method === "DOM.focus")).toHaveLength(2);
+  });
+
+  it.each([
+    "remove",
+    "readonly",
+    "restore",
+    "microtask-restore",
+  ])("stops when clearing causes the page to %s the target", async (action) => {
+    const h = await setup();
+    h.element.addEventListener("input", () => {
+      if (action === "remove") h.element.remove();
+      if (action === "readonly") h.element.readOnly = true;
+      if (action === "restore") h.element.value = "restored";
+      if (action === "microtask-restore")
+        queueMicrotask(() => {
+          h.element.value = "restored";
+        });
+    });
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_target_changed" },
+    });
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("fails when insertText is acknowledged without changing the value", async () => {
+    const h = await setup();
+    h.insert.mockImplementation(async () => {});
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("detects truncation when maxlength changes after preparation", async () => {
+    const h = await setup();
+    h.element.addEventListener(
+      "input",
+      () => {
+        h.element.maxLength = 3;
+      },
+      { once: true },
+    );
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("hel");
+  });
+
+  it.each([
+    "input",
+    "change",
+    "microtask-change",
+  ])("detects a value reverted by the %s handler", async (event) => {
+    const h = await setup();
+    h.element.addEventListener(event === "microtask-change" ? "change" : event, () => {
+      if (event === "microtask-change")
+        queueMicrotask(() => {
+          h.element.value = "";
+        });
+      else h.element.value = "";
+    });
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed", message: /expected value/ });
+  });
+
+  it("compares content rather than length without including field values in the error", async () => {
+    const h = await setup('<input type="password">');
+    h.element.addEventListener("change", () => {
+      h.element.value = "other-secret";
+    });
+    const result = await h.fill("given-secret");
+    expect(result).toMatchObject({ code: "cdp_failed", message: /expected value/ });
+    expect(JSON.stringify(result)).not.toMatch(/given-secret|other-secret/);
+  });
+
+  it("does not report success for a target replaced by a change handler", async () => {
+    const h = await setup();
+    h.element.addEventListener("change", () => h.element.replaceWith(h.element.cloneNode()));
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_target_changed" },
+    });
+  });
+
+  it.each([
+    1, 2, 3, 4, 5,
+  ])("rejects script exceptions at phase %s and releases the target", async (phase) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const run = h.script.getMockImplementation()!;
+    let count = 0;
+    h.script.mockImplementation(async (params) =>
+      ++count === phase ? { exceptionDetails: { text: "page secret" } } : run(params),
+    );
+    const result = await h.fill();
+    expect(result).toMatchObject({ code: "cdp_failed", data: { reason: "fill_failed" } });
+    expect(JSON.stringify(result)).not.toContain("page secret");
+    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([1, 2, 3, 5])("rejects missing results at phase %s", async (phase) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const run = h.script.getMockImplementation()!;
+    let count = 0;
+    h.script.mockImplementation(async (params) =>
+      ++count === phase ? { result: { type: "undefined" } } : run(params),
+    );
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
+    if (phase <= 3) expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each(["input", "change"])("checks state after nested microtasks from %s", async (event) => {
+    const h = await setup();
+    h.element.addEventListener(event, () => {
+      queueMicrotask(() =>
+        queueMicrotask(() => {
+          h.element.value = "reverted";
+        }),
+      );
+    });
+    expect(await h.fill()).toMatchObject({ code: "cdp_failed" });
+    if (event === "input") expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "<input>",
+    '<input type="password">',
+    "<textarea></textarea>",
+  ])("verifies successful text in %s", async (markup) => {
+    const h = await setup(markup);
+    expect(await h.fill("你好🙂")).toMatchObject({ value_length: 4 });
+    expect(h.element.value).toBe("你好🙂");
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("verifies append against the old value plus the requested text", async () => {
+    const h = await setup();
+    h.element.focus();
+    h.element.setSelectionRange(3, 3);
+    expect(await h.fill("!", false)).toMatchObject({ value_length: 4 });
+    expect(h.element.value).toBe("old!");
+  });
+
+  it.each([
+    ["<textarea></textarea>", "a\r\nb", "a\nb"],
+    ["<input>", "a\nb", "a b"],
+    ["<input>", "a\r\nb", "a b"],
+    [
+      '<input type="email" multiple>',
+      " a@example.com , b@example.com ",
+      "a@example.com,b@example.com",
+    ],
+  ])("accepts native normalization for %s", async (markup, requested, normalized) => {
+    if (markup.startsWith("<textarea")) {
+      // Happy DOM does not implement Chrome's textarea line-ending normalization.
+      const setter = Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, "value")!.set!;
+      vi.spyOn(HTMLTextAreaElement.prototype, "value", "set").mockImplementation(function (
+        this: HTMLTextAreaElement,
+        value,
+      ) {
+        setter.call(this, value.replace(/\r\n?/g, "\n"));
+      });
+    }
+    const h = await setup(markup);
+    h.insert.mockImplementation(async () => {
+      h.element.value = normalized;
+    });
+    expect(await h.fill(requested)).toMatchObject({ value_length: normalized.length });
+  });
+
+  it("does not count an editable padding break as an extra typed character", async () => {
+    const h = await setup('<div contenteditable="true" tabindex="0"></div>');
+    // These two layout/editability properties are missing in Happy DOM.
+    let innerText = "";
+    Object.defineProperty(h.element, "isContentEditable", { get: () => true });
+    Object.defineProperty(h.element, "innerText", { get: () => innerText });
+    h.insert.mockImplementation(async () => {
+      h.element.innerHTML = "one<div><br></div>";
+      innerText = "one\n\n";
+    });
+    expect(await h.fill("one\n")).toMatchObject({ value_length: 4 });
+  });
+
+  it.each([
+    [0, 0],
+    [1, 1],
+    [0, 3],
+  ])("appends after moving selection %s:%s to the end", async (start, end) => {
+    const h = await setup();
+    h.element.focus();
+    h.element.setSelectionRange(start, end);
+    expect(await h.fill("🙂", false)).toMatchObject({ value_length: 5 });
+    expect(h.element.value).toBe("old🙂");
+  });
+
+  it.each(
+    ["number", "email"].flatMap((type) =>
+      [
+        [0, 0],
+        [1, 1],
+        [0, 2],
+      ].map(([start, end]) => ({ type, start, end })),
+    ),
+  )("appends to $type from selection $start:$end without using its unsupported API", async ({
+    type,
+    start,
+    end,
+  }) => {
+    const h = await setup(`<input type="${type}" value="12">`);
+    Object.assign(h.hiddenCaret, { start, end });
+    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
+    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
+    const selection = vi.spyOn(h.element, "setSelectionRange").mockImplementation(() => {
+      throw new DOMException("unsupported", "InvalidStateError");
+    });
+    expect(await h.fill("3", false)).toMatchObject({ value_length: 3 });
+    expect(h.element.value).toBe("123");
+    expect(selection).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "number",
+    "email",
+  ])("does not report successful %s append when the caret command is ignored", async (type) => {
+    const h = await setup(`<input type="${type}" value="12">`);
+    vi.spyOn(h.element, "selectionStart", "get").mockReturnValue(null);
+    vi.spyOn(h.element, "selectionEnd", "get").mockReturnValue(null);
+    h.moveToEnd.mockResolvedValueOnce(undefined);
+    expect(await h.fill("3", false)).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("312");
+    expect(h.insert).toHaveBeenCalledOnce();
+  });
+
+  it("rejects invalid number text before clearing", async () => {
+    const h = await setup('<input type="number" value="12">');
+    expect(await h.fill("abc")).toMatchObject({
+      code: "invalid_params",
+      data: { reason: "fill_value_invalid" },
+    });
+    expect(h.element.value).toBe("12");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("reports page formatting as unconfirmed without retrying the write", async () => {
+    const h = await setup();
+    h.element.addEventListener("change", () => {
+      h.element.value = h.element.value.toUpperCase();
+    });
+    expect(await h.fill()).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "fill_value_mismatch" },
+    });
+    expect(h.element.value).toBe("HELLO");
+    expect(h.insert).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    ["focus", false],
+    ["focus", true],
+    ["value", false],
+    ["value", true],
+    ["cancel", false],
+    ["cancel", true],
+    ["throw", false],
+    ["throw", true],
+  ] as const)("stops when positioning triggers %s (clear=%s) and releases the key", async (action, clearBefore) => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    const controller = new AbortController();
+    const other = document.createElement("input");
+    document.body.append(other);
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      const reply = await send(tabId, method, params);
+      if (
+        method === "Input.dispatchKeyEvent" &&
+        (params as { type: string }).type === "rawKeyDown"
+      ) {
+        if (action === "focus") other.focus();
+        if (action === "value") h.element.value = "changed";
+        if (action === "cancel") controller.abort();
+        if (action === "throw") throw new Error("dispatch failed");
+      }
+      return reply;
+    });
+    const result = await h.fill("!", clearBefore, controller.signal);
+    expect(result).toMatchObject({ code: action === "cancel" ? "cancelled" : "cdp_failed" });
+    expect(h.insert).not.toHaveBeenCalled();
+    expect(other.value).toBe("");
+    expect(h.send).toHaveBeenCalledWith(
+      4,
+      "Input.dispatchKeyEvent",
+      expect.objectContaining({ type: "keyUp" }),
+    );
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([true, false])("verifies an empty request with clear_before=%s", async (clearBefore) => {
+    const h = await setup();
+    expect(await h.fill("", clearBefore)).toMatchObject({ value_length: clearBefore ? 0 : 3 });
+    expect(h.element.value).toBe(clearBefore ? "" : "old");
+    expect(h.insert).not.toHaveBeenCalled();
+  });
+
+  it("cancels after insertion without sending change events", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    h.insert.mockImplementation(async () => controller.abort());
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.script).toHaveBeenCalledTimes(2);
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("cancels after resolving the remote object without clearing the field", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    const send = h.send.getMockImplementation()!;
+    h.send.mockImplementation(async (tabId, method, params) => {
+      const result = await send(tabId, method, params);
+      if (method === "DOM.resolveNode") controller.abort();
+      return result;
+    });
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.element.value).toBe("old");
+    expect(h.script).not.toHaveBeenCalled();
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("honors cancellation during verification", async () => {
+    const h = await setup();
+    const controller = new AbortController();
+    h.element.addEventListener("change", () => controller.abort());
+    expect(await h.fill("hello", true, controller.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("keeps the verified outcome when releasing the remote object fails", async () => {
+    const h = await setup();
+    h.release.mockRejectedValueOnce(new Error("target closed"));
+    expect(await h.fill()).toMatchObject({ value_length: 5 });
+  });
+});

apps/extension/src/tools/__tests__/focus.browser.test.ts

@@ -0,0 +1,166 @@
+// @vitest-environment node
+// Opt in with BSK_FOCUS_CHROME=/path/to/chrome; each test owns its browser/profile.
+import { describe, expect, it } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import { handleBlur, handleFocus } from "../interaction";
+import type { CdpRunner } from "../shared";
+
+type Send = <T = Record<string, unknown>>(
+  method: string,
+  params?: object,
+  sessionId?: string,
+) => Promise<T>;
+
+async function withFocusBrowser(
+  run: (h: {
+    evaluate: (expression: string) => Promise<unknown>;
+    ref: () => Promise<void>;
+    focus: (signal?: AbortSignal) => ReturnType<typeof handleFocus>;
+    blur: (signal?: AbortSignal) => ReturnType<typeof handleBlur>;
+    calls: string[];
+    afterCommand: { current: (method: string) => void };
+  }) => Promise<void>,
+) {
+  // Reuse the existing isolated Chrome launcher; no new browser dependency.
+  const { withChrome } = await import(
+    new URL(
+      "../../../../../evals/browser/cases/regression/snapshot-coordinates/chrome.mjs",
+      import.meta.url,
+    ).href
+  );
+  await withChrome(
+    { executable: process.env.BSK_FOCUS_CHROME, deviceScale: 1, zoom: 1 },
+    async (send: Send) => {
+      const { targetId } = await send<{ targetId: string }>("Target.createTarget", {
+        url: "about:blank",
+      });
+      const { sessionId } = await send<{ sessionId: string }>("Target.attachToTarget", {
+        targetId,
+        flatten: true,
+      });
+      await send("Page.bringToFront", {}, sessionId);
+      const evaluate = async (expression: string) => {
+        const reply = await send<{ result: { value: unknown }; exceptionDetails?: unknown }>(
+          "Runtime.evaluate",
+          { expression, returnByValue: true },
+          sessionId,
+        );
+        expect(reply.exceptionDetails).toBeUndefined();
+        return reply.result.value;
+      };
+      await evaluate(
+        `document.body.innerHTML = '<input id="target"><input id="other">'; window.probe = document.querySelector('#target');`,
+      );
+      const manager = new SessionManager({
+        agentWindow: {
+          create: async () => 100,
+          remove: async () => {},
+          ensureActiveTab: async () => 4,
+        },
+      });
+      const ctx = await manager.start("aa11");
+      const calls: string[] = [];
+      const afterCommand = { current: (_method: string) => {} };
+      const cdp: CdpRunner = {
+        send: async (_tabId, method, params) => {
+          calls.push(method);
+          const result = await send(method, params, sessionId);
+          afterCommand.current(method);
+          return result as never;
+        },
+      };
+      const deps = {
+        cdp,
+        tabsApi: {
+          get: async (id: number) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab,
+          query: async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab],
+        },
+      };
+      await run({
+        evaluate,
+        calls,
+        afterCommand,
+        ref: async () => {
+          const { result } = await send<{ result: { objectId: string } }>(
+            "Runtime.evaluate",
+            { expression: "window.probe" },
+            sessionId,
+          );
+          const { node } = await send<{ node: { backendNodeId: number } }>(
+            "DOM.describeNode",
+            { objectId: result.objectId },
+            sessionId,
+          );
+          await send("Runtime.releaseObject", { objectId: result.objectId }, sessionId);
+          ctx.refStore.set("e1", node.backendNodeId, { tabId: 4 });
+        },
+        focus: (signal) =>
+          handleFocus(manager, { session_id: "aa11", ref: "e1" }, { ...deps, signal }),
+        blur: (signal) =>
+          handleBlur(manager, { session_id: "aa11", ref: "e1" }, { ...deps, signal }),
+      });
+    },
+  );
+}
+
+describe.skipIf(!process.env.BSK_FOCUS_CHROME)("real browser focus and blur", () => {
+  it.each(["light", "open", "closed"])("verifies focus and blur in %s DOM", async (mode) => {
+    await withFocusBrowser(async (h) => {
+      if (mode !== "light")
+        await h.evaluate(`(() => {
+        const host = document.createElement('div'); document.body.append(host);
+        const nested = document.createElement('div'); host.attachShadow({mode:'${mode}'}).append(nested);
+        const input = document.createElement('input'); nested.attachShadow({mode:'${mode}'}).append(input);
+        window.probe = input;
+      })()`);
+      await h.ref();
+      expect(await h.focus()).toMatchObject({ focused: true });
+      expect(await h.evaluate("window.probe.matches(':focus')")).toBe(true);
+      expect(await h.blur()).toMatchObject({ was_focused: true, focused: false });
+      expect(await h.evaluate("window.probe.matches(':focus')")).toBe(false);
+      expect(h.calls.filter((method) => method === "Runtime.releaseObject")).toHaveLength(2);
+    });
+  });
+
+  it("detects focus changes from event-handler microtasks", async () => {
+    await withFocusBrowser(async (h) => {
+      await h.ref();
+      await h.evaluate(
+        "window.probe.addEventListener('focus', () => queueMicrotask(() => document.querySelector('#other').focus()), {once:true})",
+      );
+      expect(await h.focus()).toMatchObject({ code: "cdp_failed" });
+      expect(await h.focus()).toMatchObject({ focused: true });
+      await h.evaluate(
+        "window.probe.addEventListener('blur', () => queueMicrotask(() => window.probe.focus()), {once:true})",
+      );
+      expect(await h.blur()).toMatchObject({ code: "cdp_failed" });
+      expect(await h.evaluate("window.probe.matches(':focus')")).toBe(true);
+    });
+  });
+
+  it("cancels before blur while still releasing the resolved object", async () => {
+    await withFocusBrowser(async (h) => {
+      await h.ref();
+      await h.focus();
+      const abort = new AbortController();
+      h.afterCommand.current = (method) => {
+        if (method === "DOM.resolveNode") abort.abort();
+      };
+      expect(await h.blur(abort.signal)).toMatchObject({ code: "cancelled" });
+      expect(await h.evaluate("window.probe.matches(':focus')")).toBe(true);
+      expect(h.calls.at(-1)).toBe("Runtime.releaseObject");
+    });
+  });
+
+  it("reports a page exception with its cause", async () => {
+    await withFocusBrowser(async (h) => {
+      await h.ref();
+      await h.evaluate("window.probe.blur = () => { throw new Error('page blur failed'); }");
+      expect(await h.blur()).toMatchObject({
+        code: "cdp_failed",
+        message: expect.stringContaining("page blur failed"),
+      });
+      expect(h.calls.at(-1)).toBe("Runtime.releaseObject");
+    });
+  });
+});

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

@@ -0,0 +1,293 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import { SessionManager } from "@/session-manager/manager";
+import { handleBlur, handleFocus } from "../interaction";
+import type { CdpRunner } from "../shared";
+
+interface ScriptParams {
+  functionDeclaration: string;
+}
+interface Call {
+  target: CdpTarget;
+  method: string;
+}
+
+async function setup(element?: HTMLElement, childSession = false) {
+  if (!element) {
+    document.body.innerHTML = '<input id="target"><input id="other">';
+    element = document.querySelector<HTMLInputElement>("#target")!;
+  }
+  const targetElement = element;
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("aa11");
+  ctx.refStore.set("e1", 12, {
+    tabId: 4,
+    ...(childSession ? { frameId: "child", cdpSessionId: "child-session" } : {}),
+  });
+  const calls: Call[] = [];
+  const afterCommand = vi.fn<(call: Call) => void>();
+  const script = vi.fn(async (params: ScriptParams) => {
+    try {
+      const fn = new Function(`return (${params.functionDeclaration})`)();
+      return { result: { value: await fn.call(targetElement) } };
+    } catch (error) {
+      return { exceptionDetails: { text: "Uncaught", exception: { description: String(error) } } };
+    }
+  });
+  const focus = vi.fn(() => targetElement.focus());
+  const release = vi.fn(async () => ({}));
+  const send = async (target: CdpTarget, method: string, params?: object) => {
+    const call = { target, method };
+    calls.push(call);
+    try {
+      switch (method) {
+        case "DOM.getDocument":
+          return { root: { nodeId: 1 } };
+        case "DOM.querySelector":
+          return { nodeId: 2 };
+        case "DOM.describeNode":
+          return { node: { backendNodeId: 12 } };
+        case "DOM.scrollIntoViewIfNeeded":
+          return {};
+        case "DOM.resolveNode":
+          return { object: { objectId: "focus-target" } };
+        case "DOM.focus":
+          focus();
+          return {};
+        case "Runtime.callFunctionOn":
+          return await script(params as ScriptParams);
+        case "Runtime.releaseObject":
+          return await release();
+        default:
+          throw new Error(`unexpected ${method}`);
+      }
+    } finally {
+      afterCommand(call);
+    }
+  };
+  const cdp: CdpRunner = {
+    send: (tabId, method, params) => send({ tabId }, method, params) as never,
+    sendToTarget: send as CdpRunner["sendToTarget"],
+    getFrameGraph: vi.fn(async () => ({
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        ...(childSession
+          ? [
+              {
+                frameId: "child",
+                parentFrameId: "main",
+                ownerBackendNodeId: 99,
+                target: { tabId: 4, sessionId: "child-session" },
+              },
+            ]
+          : []),
+      ],
+    })),
+  };
+  const tabsApi = {
+    get: vi.fn(async (id: number) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab),
+    query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+  };
+  return {
+    element: targetElement,
+    calls,
+    afterCommand,
+    script,
+    focus,
+    release,
+    cdp,
+    tabsApi,
+    run: (
+      action: "focus" | "blur",
+      signal?: AbortSignal,
+      params: { ref?: string; selector?: string; tab_id?: number } = { ref: "e1" },
+    ) =>
+      (action === "focus" ? handleFocus : handleBlur)(
+        manager,
+        { session_id: "aa11", ...params },
+        { cdp, tabsApi, signal },
+      ),
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  document.body.innerHTML = "";
+});
+
+describe("focus and blur state verification", () => {
+  it.each(["open", "closed"] as const)("handles nested %s shadow roots", async (mode) => {
+    const host = document.createElement("div");
+    document.body.append(host);
+    const outer = host.attachShadow({ mode });
+    const innerHost = document.createElement("div");
+    outer.append(innerHost);
+    const inner = innerHost.attachShadow({ mode });
+    const element = document.createElement("input");
+    inner.append(element);
+    const h = await setup(element);
+    expect(await h.run("focus")).toMatchObject({ focused: true });
+    expect(inner.activeElement).toBe(element);
+    expect(await h.run("blur")).toMatchObject({ was_focused: true, focused: false });
+    expect(inner.activeElement).toBeNull();
+    expect(h.release).toHaveBeenCalledTimes(2);
+  });
+
+  it("keeps DOM focus usable when the document is in the background", async () => {
+    const h = await setup();
+    vi.spyOn(document, "hasFocus").mockReturnValue(false);
+    expect(await h.run("focus")).toMatchObject({ focused: true });
+    expect(await h.run("blur")).toMatchObject({ was_focused: true, focused: false });
+  });
+
+  it("blurring an unfocused target preserves the other element's focus", async () => {
+    const h = await setup();
+    const other = document.querySelector<HTMLInputElement>("#other")!;
+    other.focus();
+    expect(await h.run("blur")).toMatchObject({ was_focused: false, focused: false });
+    expect(document.activeElement).toBe(other);
+  });
+
+  it("detects focus redirected by a focus handler's microtask", async () => {
+    const h = await setup();
+    h.element.addEventListener("focus", () =>
+      queueMicrotask(() => document.querySelector<HTMLInputElement>("#other")!.focus()),
+    );
+    expect(await h.run("focus")).toMatchObject({
+      code: "cdp_failed",
+      message: "target element did not become focused",
+    });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("does not report blur success when a microtask restores focus", async () => {
+    const h = await setup();
+    h.element.focus();
+    h.element.addEventListener("blur", () => queueMicrotask(() => h.element.focus()));
+    expect(await h.run("blur")).toMatchObject({
+      code: "cdp_failed",
+      message: "target element remained focused after blur()",
+    });
+    expect(document.activeElement).toBe(h.element);
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each(["focus", "blur"] as const)("rejects a detached %s target", async (action) => {
+    const h = await setup();
+    h.element.remove();
+    expect(await h.run(action)).toMatchObject({ code: "cdp_failed" });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it("preserves a script exception's cause", async () => {
+    const h = await setup();
+    vi.spyOn(h.element, "blur").mockImplementation(() => {
+      throw new Error("page blur failed");
+    });
+    expect(await h.run("blur")).toMatchObject({
+      code: "cdp_failed",
+      message: expect.stringContaining("page blur failed"),
+    });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each(["focus", "blur"] as const)("rejects malformed %s script results", async (action) => {
+    const h = await setup();
+    h.script.mockResolvedValueOnce({ result: { value: null } });
+    expect(await h.run(action)).toMatchObject({
+      code: "cdp_failed",
+      message: expect.stringContaining("unexpected result"),
+    });
+    expect(h.release).toHaveBeenCalledOnce();
+  });
+
+  it.each([
+    "focus",
+    "blur",
+  ] as const)("keeps %s, verification and cleanup in the OOPIF session", async (action) => {
+    const h = await setup(undefined, true);
+    if (action === "blur") h.element.focus();
+    expect(await h.run(action)).toMatchObject({ focused: action === "focus" });
+    const targetCalls = h.calls.filter((call) => call.method !== "DOM.scrollIntoViewIfNeeded");
+    expect(targetCalls.every((call) => call.target.sessionId === "child-session")).toBe(true);
+    expect(targetCalls.at(-1)?.method).toBe("Runtime.releaseObject");
+  });
+
+  it.each(["focus", "blur"] as const)("rejects %s on a user tab before CDP", async (action) => {
+    const h = await setup();
+    h.tabsApi.get.mockResolvedValue({ id: 9, windowId: 200, active: true } as chrome.tabs.Tab);
+    expect(await h.run(action, undefined, { ref: "e1", tab_id: 9 })).toMatchObject({
+      code: "permission_denied",
+    });
+    expect(h.calls).toEqual([]);
+  });
+
+  it("does not replace a successful result when navigation disposed the remote object", async () => {
+    const h = await setup();
+    h.release.mockRejectedValue(new Error("Cannot find context"));
+    expect(await h.run("focus")).toMatchObject({ focused: true });
+  });
+});
+
+describe("focus and blur cancellation", () => {
+  const boundaries = [
+    "DOM.getDocument",
+    "DOM.querySelector",
+    "DOM.describeNode",
+    "DOM.resolveNode",
+    "Runtime.callFunctionOn",
+  ];
+  for (const action of ["focus", "blur"] as const) {
+    it.each(
+      action === "focus" ? [...boundaries, "DOM.scrollIntoViewIfNeeded", "DOM.focus"] : boundaries,
+    )(`${action} stops after cancellation during %s`, async (method) => {
+      const h = await setup();
+      const abort = new AbortController();
+      let cancelledAfter = 0;
+      h.afterCommand.mockImplementation((call) => {
+        if (call.method === method && !abort.signal.aborted) {
+          cancelledAfter = h.calls.length;
+          abort.abort();
+        }
+      });
+      expect(await h.run(action, abort.signal, { selector: "#target" })).toMatchObject({
+        code: "cancelled",
+      });
+      expect(abort.signal.aborted).toBe(true);
+      expect(
+        h.calls.slice(cancelledAfter).every((call) => call.method === "Runtime.releaseObject"),
+      ).toBe(true);
+      if (h.calls.some((call) => call.method === "DOM.resolveNode"))
+        expect(h.release).toHaveBeenCalledOnce();
+    });
+
+    it(`${action} stops if cancellation arrives while resolving the tab`, async () => {
+      const h = await setup();
+      const abort = new AbortController();
+      h.tabsApi.query.mockImplementation(async () => {
+        abort.abort();
+        return [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab];
+      });
+      expect(await h.run(action, abort.signal)).toMatchObject({ code: "cancelled" });
+      expect(h.calls).toEqual([]);
+    });
+  }
+
+  it("does not scroll frame owners after cancellation in an OOPIF", async () => {
+    const h = await setup(undefined, true);
+    const abort = new AbortController();
+    h.afterCommand.mockImplementation((call) => {
+      if (call.method === "DOM.scrollIntoViewIfNeeded") abort.abort();
+    });
+    expect(await h.run("focus", abort.signal)).toMatchObject({ code: "cancelled" });
+    expect(h.calls.filter((call) => call.method === "DOM.scrollIntoViewIfNeeded")).toHaveLength(1);
+    expect(h.focus).not.toHaveBeenCalled();
+  });
+});

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

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from "vitest";
-import { resolveFrameProjection, resolveNodeGeometry } from "../frame-geometry";
+import { resolveNodeGeometry } from "../frame-geometry";
 import {
   clipPolygon,
   polygonArea,
@@ -10,9 +10,141 @@ import {
   rectPolygon,
   regionBounds,
 } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";
 
+function scrollbarDriver(
+  visible = { width: 185, height: 89 },
+  frameSize: unknown = { width: 200, height: 100 },
+) {
+  const send = vi.fn(async (target: { sessionId?: string }, method: string) => {
+    if (method === "Runtime.evaluate") return { result: { value: frameSize } };
+    if (method === "Page.getLayoutMetrics")
+      return {
+        cssLayoutViewport: {
+          clientWidth: target.sessionId ? visible.width : 800,
+          clientHeight: target.sessionId ? visible.height : 600,
+        },
+      };
+    if (method === "DOM.getBoxModel")
+      return {
+        model: {
+          content: target.sessionId
+            ? [0, 0, 200, 0, 200, 100, 0, 100]
+            : [100, 100, 500, 100, 500, 300, 100, 300],
+        },
+      };
+    if (method === "DOM.getContentQuads")
+      return { quads: [[180, 80, 230, 80, 230, 120, 180, 120]] };
+    throw new Error(`unexpected ${method}`);
+  });
+  const cdp: CdpRunner = {
+    send: (tabId, method) => send({ tabId } as never, method) as never,
+    sendToTarget: send as CdpRunner["sendToTarget"],
+    getFrameGraph: async () => ({
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        {
+          frameId: "child",
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+          target: { tabId: 4, sessionId: "child" },
+        },
+        {
+          frameId: "same-child",
+          parentFrameId: "child",
+          ownerBackendNodeId: 20,
+          target: { tabId: 4, sessionId: "child" },
+        },
+      ],
+    }),
+  };
+  return { cdp, send };
+}
+
 describe("frame geometry projection", () => {
+  it.each([
+    { width: 200, height: 100 },
+    { width: 185, height: 100 },
+    { width: 200, height: 89 },
+    { width: 185, height: 89 },
+  ])("preserves scale and clips scrollbar strips for visible viewport $width × $height", async (visible) => {
+    const { cdp, send } = scrollbarDriver(visible);
+    const geometry = await resolveNodeGeometry(cdp, 4, {
+      target: { tabId: 4, sessionId: "child" },
+      frameId: "child",
+      backendNodeId: 101,
+    });
+    expect(geometry).toMatchObject({
+      topBounds: {
+        x: 460,
+        y: 260,
+        width: (visible.width - 180) * 2,
+        height: (visible.height - 80) * 2,
+      },
+      actionPoint: { x: 460 + visible.width - 180, y: 260 + visible.height - 80 },
+      targetActionPoint: { x: (180 + visible.width) / 2, y: (80 + visible.height) / 2 },
+    });
+    expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(send.mock.calls.filter(([, method]) => method === "Page.getLayoutMetrics")).toHaveLength(
+      2,
+    );
+  });
+
+  it("shares the full viewport read across same-target frames, and refreshes it next operation", async () => {
+    const { cdp, send } = scrollbarDriver();
+    const context = new GeometryContext(cdp, 4);
+    await Promise.all([context.targetProjection("child"), context.targetProjection("same-child")]);
+    expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
+    await new GeometryContext(cdp, 4).targetProjection("child");
+    expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(2);
+  });
+
+  it.each([
+    null,
+    {},
+    { width: 0, height: 100 },
+    { width: 200, height: NaN },
+  ])("rejects unavailable full viewport dimensions: %j", async (size) => {
+    const { cdp } = scrollbarDriver(undefined, size);
+    expect(await new GeometryContext(cdp, 4).targetProjection("child")).toBeNull();
+  });
+
+  it("clips an inner OOPIF against an intermediate OOPIF's occupied scrollbar strips", async () => {
+    const { cdp } = scrollbarDriver();
+    const outer = cdp.sendToTarget!;
+    cdp.sendToTarget = async (target, method, params) => {
+      if (method === "DOM.getBoxModel")
+        return { model: { content: [150, 60, 250, 60, 250, 120, 150, 120] } } as never;
+      if (target.sessionId !== "inner") return outer(target, method, params);
+      if (method === "Runtime.evaluate")
+        return { result: { value: { width: 100, height: 60 } } } as never;
+      if (method === "Page.getLayoutMetrics")
+        return { cssLayoutViewport: { clientWidth: 90, clientHeight: 50 } } as never;
+      if (method === "DOM.getContentQuads")
+        return { quads: [[0, 0, 100, 0, 100, 60, 0, 60]] } as never;
+      throw new Error(`unexpected ${method}`);
+    };
+    const graph = await cdp.getFrameGraph!(4);
+    graph.frames[2] = {
+      frameId: "inner",
+      parentFrameId: "child",
+      ownerBackendNodeId: 20,
+      target: { tabId: 4, sessionId: "inner" },
+    };
+    cdp.getFrameGraph = async () => graph;
+    expect(
+      await resolveNodeGeometry(cdp, 4, {
+        target: { tabId: 4, sessionId: "inner" },
+        frameId: "inner",
+        backendNodeId: 101,
+      }),
+    ).toMatchObject({
+      topBounds: { x: 400, y: 220, width: 70, height: 58 },
+    });
+  });
+
   it("keeps region bounds separate from polygon area", () => {
     const region = [
       rectPolygon({ x: 0, y: 0, w: 10, h: 10 }),
@@ -76,34 +208,32 @@ describe("frame geometry projection", () => {
     const cdp: CdpRunner = {
       send: send as CdpRunner["send"],
       sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Runtime.evaluate")
+          return { result: { value: { width: 200, height: 100 } } };
         if (method === "Page.getLayoutMetrics") {
           return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
         }
         throw new Error(`unexpected child command ${method}`);
       }) as CdpRunner["sendToTarget"],
     };
-    const projection = await resolveFrameProjection(
-      cdp,
-      {
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "same-process-parent",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4 },
-          },
-          {
-            frameId: "oopif",
-            parentFrameId: "same-process-parent",
-            ownerBackendNodeId: 20,
-            target: { tabId: 4, sessionId: "oopif-session" },
-          },
-        ],
-      },
-      "oopif",
-    );
+    const projection = await new GeometryContext(cdp, 4, {
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        {
+          frameId: "same-process-parent",
+          parentFrameId: "main",
+          ownerBackendNodeId: 10,
+          target: { tabId: 4 },
+        },
+        {
+          frameId: "oopif",
+          parentFrameId: "same-process-parent",
+          ownerBackendNodeId: 20,
+          target: { tabId: 4, sessionId: "oopif-session" },
+        },
+      ],
+    }).targetProjection("oopif");
 
     expect(projection?.edges).toEqual([
       {
@@ -138,6 +268,8 @@ describe("frame geometry projection", () => {
         throw new Error(`unexpected root command ${method}`);
       }) as CdpRunner["send"],
       sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Runtime.evaluate")
+          return { result: { value: { width: 200, height: 100 } } };
         if (method === "Page.getLayoutMetrics") {
           return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
         }
@@ -199,6 +331,8 @@ describe("frame geometry projection", () => {
       }) as CdpRunner["send"],
       sendToTarget: vi.fn(async (_target, method) => {
         if (method === "DOM.scrollIntoViewIfNeeded") return {};
+        if (method === "Runtime.evaluate")
+          return { result: { value: { width: 200, height: 100 } } };
         if (method === "Page.getLayoutMetrics") {
           return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
         }

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

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

apps/extension/src/tools/__tests__/human-loop.test.ts

@@ -433,6 +433,7 @@ describe("handleRequestHelp", () => {
       if (method === "DOM.getContentQuads") {
         return { quads: [[10, 20, 110, 20, 110, 60, 10, 60]] };
       }
+      if (method === "Runtime.evaluate") return { result: { value: { width: 200, height: 100 } } };
       if (method === "Page.getLayoutMetrics") {
         return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
       }

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

@@ -2,8 +2,10 @@ import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import type { CdpRunner } from "@/tools/shared";
 import {
+  handleBlur,
   handleClick,
   handleFill,
+  handleFocus,
   handleHover,
   handlePress,
   handleSelect,
@@ -201,6 +203,7 @@ describe("handleClick", () => {
       if (method === "DOM.getContentQuads") {
         return { quads: [[10, 20, 110, 20, 110, 60, 10, 60]] };
       }
+      if (method === "Runtime.evaluate") return { result: { value: { width: 200, height: 100 } } };
       if (method === "Page.getLayoutMetrics") {
         return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } };
       }
@@ -220,6 +223,7 @@ describe("handleClick", () => {
       { sessionId: "child-session", method: "DOM.scrollIntoViewIfNeeded" },
       { sessionId: "child-session", method: "DOM.getContentQuads" },
       { sessionId: "child-session", method: "Page.getLayoutMetrics" },
+      { sessionId: "child-session", method: "Runtime.evaluate" },
     ]);
     expect(fake.sent.filter((call) => call.method === "Input.dispatchMouseEvent")).toHaveLength(3);
   });
@@ -540,6 +544,176 @@ describe("handleHover", () => {
   });
 });
 
+describe("handleFocus and handleBlur", () => {
+  it("focuses a ref and verifies the deep active element", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, { tabId: 4 });
+    const fake = makeFakeCdp({
+      "DOM.scrollIntoViewIfNeeded": () => ({}),
+      "DOM.focus": () => ({}),
+      "DOM.resolveNode": () => ({ object: { objectId: "focus-target" } }),
+      "Runtime.callFunctionOn": () => ({ result: { value: true } }),
+    });
+
+    const res = await handleFocus(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi },
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res).toMatchObject({ tab_id: 4, used_ref: "e3", focused: true });
+    expect(fake.sent.map((call) => call.method)).toEqual([
+      "DOM.scrollIntoViewIfNeeded",
+      "DOM.resolveNode",
+      "DOM.focus",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObject",
+    ]);
+  });
+
+  it("focuses an OOPIF ref in its CDP session", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, {
+      tabId: 4,
+      frameId: "child-frame",
+      cdpSessionId: "child-session",
+    });
+    const fake = makeFakeCdp({
+      "DOM.scrollIntoViewIfNeeded": () => ({}),
+    });
+    fake.cdp.getFrameGraph = vi.fn(async () => ({
+      rootFrameId: "main",
+      frames: [
+        { frameId: "main", target: { tabId: 4 } },
+        {
+          frameId: "child-frame",
+          parentFrameId: "main",
+          ownerBackendNodeId: 99,
+          target: { tabId: 4, sessionId: "child-session" },
+        },
+      ],
+    }));
+    const targetCalls: Array<{ sessionId?: string; method: string }> = [];
+    fake.cdp.sendToTarget = vi.fn(async (target, method) => {
+      targetCalls.push({ sessionId: target.sessionId, method });
+      if (method === "DOM.scrollIntoViewIfNeeded") return {};
+      if (method === "DOM.focus" || method === "Runtime.releaseObject") return {};
+      if (method === "DOM.resolveNode") return { object: { objectId: "focus-target" } };
+      if (method === "Runtime.callFunctionOn") return { result: { value: true } };
+      throw new Error(`unexpected child CDP call ${method}`);
+    }) as CdpRunner["sendToTarget"];
+
+    const res = await handleFocus(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi },
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res.focused).toBe(true);
+    expect(targetCalls).toEqual([
+      { sessionId: "child-session", method: "DOM.scrollIntoViewIfNeeded" },
+      { sessionId: "child-session", method: "DOM.resolveNode" },
+      { sessionId: "child-session", method: "DOM.focus" },
+      { sessionId: "child-session", method: "Runtime.callFunctionOn" },
+      { sessionId: "child-session", method: "Runtime.releaseObject" },
+    ]);
+  });
+
+  it("does not focus after cancellation during scrolling", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, { tabId: 4 });
+    const abort = new AbortController();
+    const fake = makeFakeCdp({
+      "DOM.scrollIntoViewIfNeeded": () => {
+        abort.abort();
+        return {};
+      },
+    });
+
+    const res = await handleFocus(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi, signal: abort.signal },
+    );
+
+    expect(res).toMatchObject({ code: "cancelled" });
+    expect(fake.sent.some((call) => call.method === "DOM.focus")).toBe(false);
+  });
+
+  it("blurs a ref and returns its previous focus state", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, { tabId: 4 });
+    const fake = makeFakeCdp({
+      "DOM.resolveNode": () => ({ object: { objectId: "focus-target" } }),
+      "Runtime.callFunctionOn": vi
+        .fn()
+        .mockResolvedValueOnce({ result: { value: { ok: true, was_focused: true } } })
+        .mockResolvedValueOnce({ result: { value: false } }),
+    });
+
+    const res = await handleBlur(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi },
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res).toMatchObject({
+      tab_id: 4,
+      used_ref: "e3",
+      was_focused: true,
+      focused: false,
+    });
+    expect(fake.sent.map((call) => call.method)).toEqual([
+      "DOM.resolveNode",
+      "Runtime.callFunctionOn",
+      "Runtime.callFunctionOn",
+      "Runtime.releaseObject",
+    ]);
+  });
+
+  it("rejects a target that does not implement blur", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.refStore.set("e3", 1234, { tabId: 4 });
+    const fake = makeFakeCdp({
+      "DOM.resolveNode": () => ({ object: { objectId: "focus-target" } }),
+      "Runtime.callFunctionOn": () => ({
+        result: { value: { ok: false, was_focused: false, focused: false } },
+      }),
+    });
+
+    const res = await handleBlur(
+      sm,
+      { session_id: "aa11", ref: "@e3" },
+      { cdp: fake.cdp, tabsApi: fake.tabsApi },
+    );
+
+    expect(res).toMatchObject({ code: "invalid_params", message: /does not support blur/ });
+  });
+});
+
+function successfulFillScript(params: unknown) {
+  const script = params as { arguments?: Array<{ value: unknown }>; functionDeclaration: string };
+  const args = script.arguments ?? [];
+  return {
+    result: {
+      value:
+        args.length === 2
+          ? { before: "", expected: args[0].value }
+          : script.functionDeclaration.startsWith("function(expected)")
+            ? { connected: true, matches: true, valueLength: String(args[0].value).length }
+            : "ready",
+    },
+  };
+}
+
 describe("handleFill", () => {
   it("returns not_found for unknown ref", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
@@ -586,7 +760,8 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -600,13 +775,12 @@ describe("handleFill", () => {
     expect(res.used_ref).toBe("e1");
     const insert = fake.sent.find((c) => c.method === "Input.insertText");
     expect(insert?.params).toEqual({ text: "hello" });
-    // clear_before defaults to true → callFunctionOn invoked once to
-    // clear, once to fire input/change after typing.
+    // Foreground replacement needs no extra caret-positioning round trip.
     const callFns = fake.sent.filter((c) => c.method === "Runtime.callFunctionOn");
-    expect(callFns.length).toBeGreaterThanOrEqual(2);
+    expect(callFns).toHaveLength(4);
   });
 
-  it("clear_before=false skips the wipe call", async () => {
+  it("passes clear_before=false to preparation and verifies the result", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");
     ctx.refStore.set("e1", 1, { tabId: 4 });
@@ -618,12 +792,12 @@ describe("handleFill", () => {
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-2" } }),
       "Runtime.callFunctionOn": (p) => {
-        const fn = (p as { functionDeclaration?: string }).functionDeclaration ?? "";
-        // No "this.value = ''" clearing on a no-clear path; only the
-        // post-input dispatchEvent.
-        expect(fn).not.toMatch(/this\.value\s*=\s*''/);
-        return { result: { type: "undefined" } };
+        const args = (p as { arguments?: Array<{ value: unknown }> }).arguments ?? [];
+        if (args.length === 2) expect(args[1].value).toBe(false);
+        return successfulFillScript(p);
       },
+      "Input.dispatchKeyEvent": () => ({}),
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(
@@ -650,7 +824,8 @@ describe("handleFill", () => {
       "DOM.scrollIntoViewIfNeeded": () => ({}),
       "DOM.focus": () => ({}),
       "DOM.resolveNode": () => ({ object: { objectId: "obj-3" } }),
-      "Runtime.callFunctionOn": () => ({ result: { type: "undefined" } }),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
       "Input.insertText": () => ({}),
     });
     const res = await handleFill(

apps/extension/src/tools/__tests__/navigation-recovery.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import type { BrowserNavigationApi } from "../browser-navigation";
+import { handleNavigate, handleReload } from "../navigation";
+import type { CdpRunner } from "../shared";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+const url = "https://example.test/recovered";
+
+function event<T extends (...args: never[]) => void>() {
+  const listeners = new Set<T>();
+  return {
+    listeners,
+    addListener: (listener: T) => listeners.add(listener),
+    removeListener: (listener: T) => listeners.delete(listener),
+    fire: (...args: Parameters<T>) => {
+      for (const listener of [...listeners]) listener(...args);
+    },
+  };
+}
+
+async function fixture() {
+  const manager = new SessionManager({
+    agentWindow: {
+      create: vi.fn(async () => 100),
+      remove: vi.fn(async () => {}),
+      ensureActiveTab: vi.fn(async () => 4),
+    },
+  });
+  await manager.start("test");
+  type Listener = Parameters<BrowserNavigationApi["onCommitted"]["addListener"]>[0];
+  const events = {
+    onCommitted: event<Listener>(),
+    onDOMContentLoaded: event<Listener>(),
+    onCompleted: event<Listener>(),
+    onErrorOccurred: event<Listener>(),
+  };
+  const cdpEvents = event<Parameters<NonNullable<CdpRunner["onEvent"]>>[0]>();
+  const state = { blocked: true, destinationBlocked: false, emitIdle: true };
+  const send = vi.fn(async (_tabId: number, method: string) => {
+    if (state.blocked) throw new Error(denied);
+    if (method === "Page.getFrameTree") {
+      return { frameTree: { frame: { id: "main", loaderId: "new-loader" } } };
+    }
+    if (method === "Runtime.evaluate") return { result: { value: "complete" } };
+    if (method === "Page.setLifecycleEventsEnabled" && state.emitIdle) {
+      cdpEvents.fire({ tabId: 4 }, "Page.lifecycleEvent", {
+        frameId: "main",
+        loaderId: "new-loader",
+        name: "networkIdle",
+      });
+    }
+    if (method === "Page.navigate") return { frameId: "main", loaderId: "new-loader" };
+    return {};
+  });
+  const cdp: CdpRunner = {
+    send: send as CdpRunner["send"],
+    onEvent: (listener) => {
+      cdpEvents.addListener(listener);
+      return { dispose: () => cdpEvents.removeListener(listener) };
+    },
+  };
+  const main = { tabId: 4, frameId: 0, documentId: "new-document" };
+  const navigate = async () => {
+    state.blocked = state.destinationBlocked;
+    events.onCommitted.fire(main);
+    events.onDOMContentLoaded.fire(main);
+    events.onCompleted.fire(main);
+  };
+  const browserNavigation = { ...events, update: vi.fn(navigate), reload: vi.fn(navigate) };
+  const tab = { id: 4, windowId: 100, active: true, url } as chrome.tabs.Tab;
+  const tabsApi = { get: vi.fn(async () => tab), query: vi.fn(async () => [tab]) };
+  const deps = { cdp, tabsApi, browserNavigation, defaultTimeoutMs: 1000 };
+  const expectCleanedUp = () => {
+    for (const entry of Object.values(events)) expect(entry.listeners.size).toBe(0);
+    expect(cdpEvents.listeners.size).toBe(0);
+  };
+  return { manager, deps, state, send, events, main, cdpEvents, expectCleanedUp };
+}
+
+describe("navigation after Chrome denies extension-frame access", () => {
+  it.each([
+    "load",
+    "commit",
+    "domcontentloaded",
+    "networkidle",
+  ] as const)("recovers the same tab with the requested %s checkpoint", async (waitUntil) => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: waitUntil,
+      },
+      f.deps,
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, final_url: url, reached: waitUntil });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledExactlyOnceWith(4, { url });
+    expect(f.send.mock.calls.some(([, method]) => method === "Page.navigate")).toBe(false);
+    expect(f.send).toHaveBeenCalledWith(4, "Page.enable", {});
+    f.expectCleanedUp();
+  });
+
+  it("recovers reload through tabs.reload and preserves hard reload", async () => {
+    const f = await fixture();
+    const result = await handleReload(f.manager, { session_id: "test", hard: true }, f.deps);
+    expect(result).toMatchObject({ tab_id: 4, reached: "load" });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledExactlyOnceWith(4, {
+      bypassCache: true,
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("reports the restriction when reload leaves the conflicting frame present", async () => {
+    const f = await fixture();
+    f.state.destinationBlocked = true;
+    const result = await handleReload(f.manager, { session_id: "test" }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("does not fall back for unrelated debugger failures", async () => {
+    const f = await fixture();
+    f.send.mockRejectedValue(new Error("Another debugger is already attached"));
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      message: "Another debugger is already attached",
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("does not replay navigation when a dispatched CDP command fails", async () => {
+    const f = await fixture();
+    f.state.blocked = false;
+    const send = f.send.getMockImplementation()!;
+    f.send.mockImplementation(async (tabId, method) => {
+      if (method === "Page.navigate") throw new Error(denied);
+      return send(tabId, method);
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("keeps the Agent Window guard in front of the recovery", async () => {
+    const f = await fixture();
+    f.deps.tabsApi.get.mockResolvedValue({
+      id: 4,
+      windowId: 200,
+      active: true,
+      url,
+    } as chrome.tabs.Tab);
+    const result = await handleNavigate(f.manager, { session_id: "test", tab_id: 4, url }, f.deps);
+    expect(result).toMatchObject({ code: "permission_denied" });
+    expect(f.send).not.toHaveBeenCalled();
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+  });
+
+  it("ignores old-document, subframe, and other-tab completion events", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    let settled = false;
+    const work = handleNavigate(f.manager, { session_id: "test", url }, f.deps).then((result) => {
+      settled = true;
+      return result;
+    });
+    await vi.waitFor(() => expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce());
+    f.events.onCompleted.fire(f.main);
+    f.events.onCommitted.fire({ ...f.main, tabId: 9 });
+    f.events.onCommitted.fire({ ...f.main, frameId: 1 });
+    f.events.onCompleted.fire(f.main);
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.events.onCommitted.fire(f.main);
+    f.events.onCompleted.fire({ ...f.main, documentId: "old-document" });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.state.blocked = false;
+    f.events.onCompleted.fire(f.main);
+    expect(await work).toMatchObject({ reached: "load" });
+    f.expectCleanedUp();
+  });
+
+  it("does not infer network idle from a browser load event", async () => {
+    const f = await fixture();
+    f.state.emitIdle = false;
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: "networkidle",
+        timeout_ms: 10,
+      },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners on timeout", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url, timeout_ms: 10 },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("does not navigate an already-cancelled request", async () => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      {
+        ...f.deps,
+        signal: AbortSignal.abort(),
+      },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners when cancelled after dispatch", async () => {
+    const f = await fixture();
+    const ac = new AbortController();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      ac.abort();
+    });
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      { ...f.deps, signal: ac.signal },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("reports browser navigation errors and releases listeners", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      f.events.onErrorOccurred.fire({ ...f.main, error: "net::ERR_NAME_NOT_RESOLVED" });
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({ code: "cdp_failed", message: "net::ERR_NAME_NOT_RESOLVED" });
+    f.expectCleanedUp();
+  });
+});

apps/extension/src/tools/__tests__/scroll.browser.test.ts

@@ -0,0 +1,348 @@
+// @vitest-environment node
+// Opt in with BSK_SCROLL_CHROME=/path/to/chrome. Uses an isolated browser/profile.
+import { describe, expect, it } from "vitest";
+import type { CdpFrame, CdpFrameGraph, CdpTarget } from "@/browser-driver/frame-graph";
+import { SessionManager } from "@/session-manager/manager";
+import type { ViewportRect } from "../geometry";
+import { handleScrollTo } from "../scroll";
+import type { CdpRunner } from "../shared";
+
+type Send = <T = Record<string, unknown>>(
+  method: string,
+  params?: object,
+  sessionId?: string,
+) => Promise<T>;
+type Tree = { frame: { id: string; parentId?: string; name?: string }; childFrames?: Tree[] };
+
+async function withBrowser(
+  run: (h: Awaited<ReturnType<typeof harness>>) => Promise<void>,
+  zoom = 1,
+) {
+  const { withChrome } = await import(
+    new URL(
+      "../../../../../evals/browser/cases/regression/snapshot-coordinates/chrome.mjs",
+      import.meta.url,
+    ).href
+  );
+  await withChrome(
+    { executable: process.env.BSK_SCROLL_CHROME, deviceScale: 1, zoom },
+    async (send: Send) => run(await harness(send)),
+  );
+}
+
+async function harness(send: Send) {
+  const { targetId } = await send<{ targetId: string }>("Target.createTarget", {
+    url: "about:blank",
+  });
+  const { sessionId: rootSession } = await send<{ sessionId: string }>("Target.attachToTarget", {
+    targetId,
+    flatten: true,
+  });
+  await send("Page.bringToFront", {}, rootSession);
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("aa11");
+  const calls: { method: string; sessionId?: string }[] = [];
+  const after = { command: (_method: string) => {} };
+  const sessionFor = (target: CdpTarget) => target.sessionId ?? rootSession;
+  const forward = async <T>(target: CdpTarget, method: string, params?: object): Promise<T> => {
+    calls.push({ method, sessionId: target.sessionId });
+    const result = await send<T>(method, params, sessionFor(target));
+    after.command(method);
+    return result;
+  };
+  const cdp: CdpRunner = {
+    send: (_tab, method, params) => forward({ tabId: 4 }, method, params),
+    sendToTarget: forward,
+  };
+  const evaluate = async <T>(expression: string, frame?: CdpFrame): Promise<T> => {
+    const session = frame ? sessionFor(frame.target) : rootSession;
+    const world = frame
+      ? await send<{ executionContextId: number }>(
+          "Page.createIsolatedWorld",
+          {
+            frameId: frame.frameId,
+            worldName: "scroll-oracle",
+          },
+          session,
+        )
+      : undefined;
+    const reply = await send<{ result: { value: T }; exceptionDetails?: unknown }>(
+      "Runtime.evaluate",
+      {
+        expression,
+        contextId: world?.executionContextId,
+        returnByValue: true,
+        awaitPromise: true,
+      },
+      session,
+    );
+    expect(reply.exceptionDetails).toBeUndefined();
+    return reply.result.value;
+  };
+  const rememberRef = (frame: CdpFrame, backendNodeId: number) =>
+    ctx.refStore.set("e1", backendNodeId, {
+      tabId: 4,
+      frameId: frame.frameId,
+      cdpSessionId: frame.target.sessionId,
+    });
+  const ref = async (frame: CdpFrame, selector = "#probe") => {
+    const { executionContextId } = await send<{ executionContextId: number }>(
+      "Page.createIsolatedWorld",
+      {
+        frameId: frame.frameId,
+        worldName: "scroll-oracle",
+      },
+      sessionFor(frame.target),
+    );
+    const { result } = await send<{ result: { objectId: string } }>(
+      "Runtime.evaluate",
+      {
+        expression: `document.querySelector(${JSON.stringify(selector)})`,
+        contextId: executionContextId,
+      },
+      sessionFor(frame.target),
+    );
+    const { node } = await send<{ node: { backendNodeId: number } }>(
+      "DOM.describeNode",
+      { objectId: result.objectId },
+      sessionFor(frame.target),
+    );
+    await send("Runtime.releaseObject", { objectId: result.objectId }, sessionFor(frame.target));
+    rememberRef(frame, node.backendNodeId);
+  };
+  const scroll = (target: { selector: string } | { ref: string }, signal?: AbortSignal) =>
+    handleScrollTo(
+      manager,
+      { session_id: "aa11", ...target },
+      {
+        cdp,
+        signal,
+        tabsApi: {
+          get: async (id) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab,
+          query: async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab],
+        },
+      },
+    );
+  const loadFrames = async () => {
+    const { targetInfos } = await send<{ targetInfos: { targetId: string; type: string }[] }>(
+      "Target.getTargets",
+    );
+    const sessions = [rootSession];
+    for (const target of targetInfos.filter((t) => t.type === "iframe")) {
+      const { sessionId } = await send<{ sessionId: string }>("Target.attachToTarget", {
+        targetId: target.targetId,
+        flatten: true,
+      });
+      sessions.push(sessionId);
+    }
+    const frames: (CdpFrame & { name: string })[] = [];
+    for (const session of sessions) {
+      const { frameTree } = await send<{ frameTree: Tree }>("Page.getFrameTree", {}, session);
+      const target = { tabId: 4, ...(session !== rootSession ? { sessionId: session } : {}) };
+      const visit = (tree: Tree, parentFrameId = tree.frame.parentId) => {
+        frames.push({ frameId: tree.frame.id, parentFrameId, target, name: tree.frame.name ?? "" });
+        for (const child of tree.childFrames ?? []) visit(child, tree.frame.id);
+      };
+      visit(frameTree);
+    }
+    for (const frame of frames) {
+      if (!frame.parentFrameId) continue;
+      const parent = frames.find((f) => f.frameId === frame.parentFrameId)!;
+      const owner = await send<{ backendNodeId: number }>(
+        "DOM.getFrameOwner",
+        { frameId: frame.frameId },
+        sessionFor(parent.target),
+      );
+      frame.ownerBackendNodeId = owner.backendNodeId;
+    }
+    const graph: CdpFrameGraph = { rootFrameId: frames[0].frameId, frames };
+    cdp.getFrameGraph = async () => graph;
+    return frames;
+  };
+  return { send, rootSession, evaluate, ref, rememberRef, scroll, loadFrames, calls, after };
+}
+
+function intersection(a: ViewportRect, b: ViewportRect): ViewportRect | null {
+  const x = Math.max(a.x, b.x),
+    y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width),
+    bottom = Math.min(a.y + a.height, b.y + b.height);
+  return right > x && bottom > y ? { x, y, width: right - x, height: bottom - y } : null;
+}
+
+function expectRect(actual: unknown, expected: ViewportRect) {
+  expect(actual).not.toHaveProperty("code");
+  for (const key of ["x", "y", "width", "height"] as const)
+    expect(Math.abs((actual as ViewportRect)[key] - expected[key]), key).toBeLessThan(2);
+}
+
+describe.skipIf(!process.env.BSK_SCROLL_CHROME)("real browser scroll-to", () => {
+  it("scrolls ordinary elements and reports the clipped portion of nested scrollers", async () => {
+    await withBrowser(async (h) => {
+      for (const html of [
+        '<div style="height:2200px"></div><div id="target" style="width:100px;height:40px"></div>',
+        '<div style="height:200px"></div><div id="clip" style="height:80px;width:200px;overflow:auto"><div id="target" style="width:100px;height:400px"></div></div>',
+        '<div style="height:200px"></div><div id="clip" style="height:80px;width:200px;overflow:auto;transform:scale(1.25);transform-origin:0 0"><div id="target" style="width:100px;height:400px"></div></div>',
+      ]) {
+        await h.evaluate(`document.body.innerHTML = ${JSON.stringify(html)}`);
+        const result = await h.scroll({ selector: "#target" });
+        const oracle = await h.evaluate<{ rect: ViewportRect; clip?: ViewportRect }>(`({
+          rect: document.querySelector('#target').getBoundingClientRect().toJSON(),
+          clip: document.querySelector('#clip')?.getBoundingClientRect().toJSON()
+        })`);
+        expectRect(result, oracle.clip ? intersection(oracle.rect, oracle.clip)! : oracle.rect);
+      }
+    });
+  });
+
+  it.each([
+    "visibility:hidden",
+    "opacity:0",
+    "display:none",
+    "content-visibility:hidden",
+  ])("rejects %s targets", async (style) => {
+    await withBrowser(async (h) => {
+      await h.evaluate(
+        `document.body.innerHTML = '<div style="${style}"><button id="target">Target</button></div>'`,
+      );
+      expect(await h.scroll({ selector: "#target" })).toMatchObject({
+        code: "permission_denied",
+        data: { reason: "element_not_visible" },
+      });
+    });
+  });
+
+  it("rejects targets fully outside an overflow:clip ancestor", async () => {
+    await withBrowser(async (h) => {
+      await h.evaluate(
+        `document.body.innerHTML = '<div style="height:80px;overflow:clip"><div style="height:150px"></div><button id="target">Target</button></div>'`,
+      );
+      expect(await h.scroll({ selector: "#target" })).toMatchObject({ code: "permission_denied" });
+    });
+  });
+
+  it.each(["open", "closed"])("clips %s shadow-root refs", async (mode) => {
+    await withBrowser(async (h) => {
+      await h.evaluate(`(() => {
+        const host = document.createElement('div'); document.body.append(host);
+        const root = host.attachShadow({mode:'${mode}'});
+        root.innerHTML = '<div style="height:60px;overflow:auto"><button id="probe" style="height:200px;width:100px">Target</button></div>';
+        window.probe = root.querySelector('#probe');
+      })()`);
+      const frames = await h.loadFrames();
+      const { result } = await h.send<{ result: { objectId: string } }>(
+        "Runtime.evaluate",
+        { expression: "window.probe" },
+        h.rootSession,
+      );
+      // Build the ref from the actual closed-root node, as an observation does.
+      const { node } = await h.send<{ node: { backendNodeId: number } }>(
+        "DOM.describeNode",
+        { objectId: result.objectId },
+        h.rootSession,
+      );
+      await h.send("Runtime.releaseObject", { objectId: result.objectId }, h.rootSession);
+      h.rememberRef(frames[0], node.backendNodeId);
+      expect(await h.scroll({ ref: "e1" })).toMatchObject({ height: 60 });
+    });
+  });
+
+  it("cancels after scrolling and releases the measurement object without follow-up reads", async () => {
+    await withBrowser(async (h) => {
+      await h.evaluate("document.body.innerHTML = '<button id=target>Target</button>'");
+      const abort = new AbortController();
+      h.after.command = (method) => {
+        if (method === "DOM.resolveNode") abort.abort();
+      };
+      expect(await h.scroll({ selector: "#target" }, abort.signal)).toMatchObject({
+        code: "cancelled",
+      });
+      expect(h.calls.at(-1)!.method).toBe("Runtime.releaseObjectGroup");
+      expect(h.calls.some((call) => call.method === "Runtime.callFunctionOn")).toBe(false);
+    });
+  });
+
+  it.each([
+    { fixture: "snapshot-coordinates", zoom: 1 },
+    { fixture: "snapshot-coordinates", zoom: 1.25 },
+    { fixture: "oopif-scrollbars", zoom: 1 },
+    { fixture: "oopif-scrollbars", zoom: 0.8 },
+  ])("scrolls nested frames: $fixture at zoom $zoom", async ({ fixture, zoom }) => {
+    const { createEvalServer } = await import(
+      new URL("../../../../../evals/browser/lib/server.mjs", import.meta.url).href
+    );
+    const server = createEvalServer();
+    const { baseUrl } = await server.start();
+    try {
+      await withBrowser(async (h) => {
+        await h.send("Page.navigate", { url: `${baseUrl}/${fixture}?run=scroll` }, h.rootSession);
+        await expect
+          .poll(
+            () =>
+              server
+                .snapshot("scroll")
+                .events.some(
+                  (e: { type: string; data: { root?: boolean } }) =>
+                    e.type === "geometry.ready" && e.data.root,
+                ),
+            { timeout: 10_000 },
+          )
+          .toBe(true);
+        const frames = await h.loadFrames();
+        expect(frames.length).toBe(fixture === "snapshot-coordinates" ? 5 : 3);
+        for (const frame of frames) {
+          await h.ref(frame);
+          const result = await h.scroll({ ref: "e1" });
+          // Independent DOM oracle: CSS border boxes plus this fixture's known
+          // axis-aligned iframe scales. Re-read after each scroll changes layout.
+          let rect = await h.evaluate<ViewportRect>(
+            "document.querySelector('#probe').getBoundingClientRect().toJSON()",
+            frame,
+          );
+          let current = frame;
+          while (true) {
+            const viewport = await h.evaluate<ViewportRect>(
+              "({ x:0, y:0, width:document.documentElement.clientWidth, height:document.documentElement.clientHeight })",
+              current,
+            );
+            rect = intersection(rect, viewport)!;
+            if (!current.parentFrameId) break;
+            const parent = frames.find((f) => f.frameId === current.parentFrameId)!;
+            const owner = await h.evaluate<{ x: number; y: number; scale: number }>(
+              `(() => {
+              const iframe = document.querySelector('iframe[name="${current.name}"]');
+              const r = iframe.getBoundingClientRect(); const s = getComputedStyle(iframe);
+              const scale = r.width / iframe.offsetWidth;
+              return { x:r.x + (iframe.clientLeft + parseFloat(s.paddingLeft))*scale,
+                y:r.y + (iframe.clientTop + parseFloat(s.paddingTop))*scale, scale };
+            })()`,
+              parent,
+            );
+            rect = {
+              x: owner.x + rect.x * owner.scale,
+              y: owner.y + rect.y * owner.scale,
+              width: rect.width * owner.scale,
+              height: rect.height * owner.scale,
+            };
+            current = parent;
+          }
+          expectRect(result, rect);
+        }
+        const child = frames.find((frame) => frame.parentFrameId === frames[0].frameId)!;
+        await h.ref(child);
+        await h.evaluate(
+          `document.querySelector('iframe[name="${child.name}"]').style.opacity = '0'`,
+        );
+        expect(await h.scroll({ ref: "e1" })).toMatchObject({ code: "permission_denied" });
+      }, zoom);
+    } finally {
+      await server.stop();
+    }
+  }, 30_000);
+});

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

@@ -0,0 +1,310 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { CdpFrameGraph, CdpTarget } from "@/browser-driver/frame-graph";
+import { SessionManager } from "@/session-manager/manager";
+import type { JavaScriptDialogInfo, ScrollToParams } from "@/transport/types";
+import type { ViewportRect } from "../geometry";
+import { handleScrollTo } from "../scroll";
+import type { CdpRunner } from "../shared";
+
+interface Call {
+  target: CdpTarget;
+  method: string;
+  params?: Record<string, unknown>;
+  aborted: boolean;
+}
+
+async function fixture(frame: "top" | "same-target" | "oopif" = "top") {
+  const manager = new SessionManager({
+    agentWindow: {
+      create: async () => 100,
+      remove: async () => {},
+      ensureActiveTab: async () => 4,
+    },
+  });
+  const ctx = await manager.start("aa11");
+  ctx.refStore.set("e3", 1234, {
+    tabId: 4,
+    ...(frame !== "top" ? { frameId: "child" } : {}),
+    ...(frame === "oopif" ? { cdpSessionId: "child-session" } : {}),
+  });
+  const abort = new AbortController();
+  const graph: CdpFrameGraph = {
+    rootFrameId: "main",
+    frames: [
+      { frameId: "main", target: { tabId: 4 } },
+      {
+        frameId: "child",
+        parentFrameId: "main",
+        ownerBackendNodeId: 99,
+        target: { tabId: 4, ...(frame === "oopif" ? { sessionId: "child-session" } : {}) },
+      },
+    ],
+  };
+  const rectangles = new Map<number, ViewportRect | null>([
+    [1234, { x: 10, y: 20, width: 100, height: 40 }],
+    [99, { x: 204, y: 306, width: 400, height: 200 }],
+  ]);
+  const calls: Call[] = [];
+  const hooks = {
+    after: (_call: Call) => {},
+    reply: (_call: Call): object | undefined => undefined,
+  };
+  const send = async <T>(target: CdpTarget, method: string, params?: object): Promise<T> => {
+    const call = {
+      target,
+      method,
+      params: params as Call["params"],
+      aborted: abort.signal.aborted,
+    };
+    calls.push(call);
+    const override = hooks.reply(call);
+    hooks.after(call);
+    if (override) return override as T;
+    const args = call.params ?? {};
+    const replies: Record<string, unknown> = {
+      "DOM.getDocument": { root: { nodeId: 1 } },
+      "DOM.querySelector": { nodeId: 2 },
+      "DOM.describeNode": { node: { backendNodeId: 1234 } },
+      "DOM.scrollIntoViewIfNeeded": {},
+      "DOM.resolveNode": { object: { objectId: String(args.backendNodeId) } },
+      "Runtime.callFunctionOn": {
+        result: {
+          value: String(args.functionDeclaration).includes("IntersectionObserver")
+            ? rectangles.get(Number(args.objectId))
+            : { width: 200, height: 100 },
+        },
+      },
+      "Runtime.releaseObject": {},
+      "Runtime.releaseObjectGroup": {},
+      "Runtime.evaluate": { result: { value: { width: 200, height: 100 } } },
+      "Page.getLayoutMetrics": {
+        cssLayoutViewport: {
+          clientWidth: target.sessionId ? 185 : 1280,
+          clientHeight: target.sessionId ? 89 : 720,
+        },
+      },
+      "DOM.getBoxModel": { model: { content: [204, 306, 604, 306, 604, 506, 204, 506] } },
+    };
+    if (!(method in replies)) throw new Error(`unexpected CDP call ${method}`);
+    return replies[method] as T;
+  };
+  const cdp: CdpRunner = {
+    send: (tabId, method, params) => send({ tabId }, method, params),
+    sendToTarget: send,
+    getFrameGraph: vi.fn(async () => {
+      hooks.after({ target: { tabId: 4 }, method: "getFrameGraph", aborted: abort.signal.aborted });
+      return graph;
+    }),
+    trackSessionTab: vi.fn(),
+  };
+  const tabsApi = {
+    get: vi.fn(async (id: number) => ({ id, windowId: 100, active: true }) as chrome.tabs.Tab),
+    query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+  };
+  const run = (params: Partial<ScrollToParams> = {}) =>
+    handleScrollTo(
+      manager,
+      { session_id: "aa11", ref: "@e3", ...params },
+      { cdp, tabsApi, signal: abort.signal },
+    );
+  return { ctx, cdp, graph, rectangles, calls, hooks, abort, tabsApi, run };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+describe("handleScrollTo", () => {
+  it("scrolls a ref and returns renderer-clipped bounds", async () => {
+    const f = await fixture();
+    expect(await f.run()).toMatchObject({
+      tab_id: 4,
+      used_ref: "e3",
+      x: 10,
+      y: 20,
+      width: 100,
+      height: 40,
+    });
+    expect(f.calls[0]).toMatchObject({
+      method: "DOM.scrollIntoViewIfNeeded",
+      params: { backendNodeId: 1234 },
+    });
+    const group = f.calls.find((call) => call.method === "DOM.resolveNode")!.params!.objectGroup;
+    expect(f.calls.at(-1)).toMatchObject({
+      method: "Runtime.releaseObjectGroup",
+      params: { objectGroup: group },
+    });
+  });
+
+  it("resolves a selector and tracks the attached tab even when it is missing", async () => {
+    const f = await fixture();
+    expect(await f.run({ ref: undefined, selector: "#target" })).toMatchObject({
+      used_selector: "#target",
+    });
+    f.hooks.reply = ({ method }) => (method === "DOM.querySelector" ? { nodeId: 0 } : undefined);
+    expect(await f.run({ ref: undefined, selector: "#missing" })).toMatchObject({
+      code: "not_found",
+      data: { reason: "selector_not_found" },
+    });
+    expect(f.cdp.trackSessionTab).toHaveBeenCalledWith("aa11", 4);
+  });
+
+  it.each([
+    "same-target",
+    "oopif",
+  ] as const)("projects %s refs and scrolls their owners", async (frame) => {
+    const f = await fixture(frame);
+    expect(await f.run()).toMatchObject({ x: 224, y: 346, width: 200, height: 80 });
+    expect(
+      f.calls
+        .filter((call) => call.method === "DOM.scrollIntoViewIfNeeded")
+        .map((call) => call.params!.backendNodeId),
+    ).toEqual([99, 1234]);
+    expect(f.cdp.getFrameGraph).toHaveBeenCalledTimes(1);
+    if (frame === "oopif")
+      expect(f.calls.find((call) => call.params?.backendNodeId === 1234)!.target.sessionId).toBe(
+        "child-session",
+      );
+  });
+
+  it("clips OOPIF bounds to occupied scrollbars without changing the frame scale", async () => {
+    const f = await fixture("oopif");
+    f.rectangles.set(1234, { x: 180, y: 80, width: 5, height: 9 });
+    expect(await f.run()).toMatchObject({ x: 564, y: 466, width: 10, height: 18 });
+  });
+
+  it("clips against the iframe owner's ordinary DOM ancestors", async () => {
+    const f = await fixture("oopif");
+    f.rectangles.set(99, { x: 204, y: 306, width: 400, height: 80 });
+    expect(await f.run()).toMatchObject({ x: 224, y: 346, width: 200, height: 40 });
+  });
+
+  it.each([1234, 99])("rejects a hidden or fully clipped node %i", async (node) => {
+    const f = await fixture("oopif");
+    f.rectangles.set(node, null);
+    expect(await f.run()).toMatchObject({
+      code: "permission_denied",
+      data: { reason: "element_not_visible" },
+    });
+    expect(f.calls.at(-1)!.method).toBe("Runtime.releaseObjectGroup");
+  });
+
+  it.each([
+    { ref: undefined },
+    { selector: "#target" },
+    { timeout_ms: 0 },
+  ])("rejects invalid params %j", async (params) => {
+    const f = await fixture();
+    expect(await f.run(params)).toMatchObject({ code: "invalid_params" });
+    expect(f.calls).toEqual([]);
+  });
+
+  it.each(["stale", "other-tab"])("rejects %s refs before scrolling", async (mode) => {
+    const f = await fixture();
+    if (mode === "stale") f.ctx.refStore.clear();
+    else f.ctx.refStore.set("e3", 1234, { tabId: 8 });
+    expect(await f.run()).toMatchObject({ code: "not_found", data: { reason: "ref_not_found" } });
+    expect(f.calls).toEqual([]);
+  });
+
+  it("enforces the Agent Window boundary", async () => {
+    const f = await fixture();
+    f.tabsApi.query.mockResolvedValue([{ id: 4, windowId: 200, active: true } as chrome.tabs.Tab]);
+    f.tabsApi.get.mockResolvedValue({ id: 4, windowId: 200, active: true } as chrome.tabs.Tab);
+    expect(await f.run({ tab_id: 4 })).toMatchObject({ code: "permission_denied" });
+    expect(f.calls).toEqual([]);
+  });
+
+  it.each([
+    "getFrameGraph",
+    "DOM.scrollIntoViewIfNeeded",
+    "DOM.resolveNode",
+    "Runtime.callFunctionOn",
+    "Page.getLayoutMetrics",
+    "Runtime.evaluate",
+    "DOM.getBoxModel",
+  ])("honors cancellation during %s and only cleans up afterwards", async (method) => {
+    const f = await fixture("oopif");
+    f.hooks.after = (call) => {
+      if (call.method === method) f.abort.abort();
+    };
+    expect(await f.run()).toMatchObject({ code: "cancelled" });
+    expect(
+      f.calls.filter((call) => call.aborted && call.method !== "Runtime.releaseObjectGroup"),
+    ).toEqual([]);
+  });
+
+  it.each([
+    "DOM.getDocument",
+    "DOM.querySelector",
+    "DOM.describeNode",
+  ])("cancels selector resolution during %s", async (method) => {
+    const f = await fixture();
+    f.hooks.after = (call) => {
+      if (call.method === method) f.abort.abort();
+    };
+    expect(await f.run({ ref: undefined, selector: "#target" })).toMatchObject({
+      code: "cancelled",
+    });
+    expect(f.calls.filter((call) => call.aborted)).toEqual([]);
+  });
+
+  it("does not start after early cancellation", async () => {
+    const f = await fixture();
+    f.abort.abort();
+    expect(await f.run()).toMatchObject({ code: "cancelled" });
+    expect(f.calls).toEqual([]);
+    expect(f.tabsApi.query).not.toHaveBeenCalled();
+  });
+
+  it("does not issue fallback scrolling after cancellation", async () => {
+    const f = await fixture();
+    f.hooks.reply = ({ method }) => {
+      if (method === "DOM.scrollIntoViewIfNeeded") {
+        f.abort.abort();
+        throw new Error("scroll failed");
+      }
+      return undefined;
+    };
+    expect(await f.run()).toMatchObject({ code: "cancelled" });
+    expect(f.calls.map((call) => call.method)).toEqual(["DOM.scrollIntoViewIfNeeded"]);
+  });
+
+  it("stops target scrolling after a deadline expires while scrolling its owner", async () => {
+    const f = await fixture("oopif");
+    const now = vi.spyOn(Date, "now").mockReturnValue(100);
+    f.hooks.after = ({ method }) => {
+      if (method === "DOM.scrollIntoViewIfNeeded") now.mockReturnValue(201);
+    };
+    expect(await f.run({ timeout_ms: 100 })).toMatchObject({ code: "timeout" });
+    expect(f.calls.filter((call) => call.method === "DOM.scrollIntoViewIfNeeded")).toHaveLength(1);
+  });
+
+  it("reports measurement exceptions and releases objects even if cleanup fails", async () => {
+    const f = await fixture();
+    f.hooks.reply = ({ method }) => {
+      if (method === "Runtime.callFunctionOn")
+        return { exceptionDetails: { text: "measurement failed" } };
+      if (method === "Runtime.releaseObjectGroup") throw new Error("target closed");
+      return undefined;
+    };
+    expect(await f.run()).toMatchObject({ code: "cdp_failed", message: "measurement failed" });
+    expect(f.calls.at(-1)!.method).toBe("Runtime.releaseObjectGroup");
+  });
+
+  it("attaches dialogs observed during scrolling", async () => {
+    const f = await fixture();
+    f.cdp.dialogCursor = () => 5;
+    const dialogs: JavaScriptDialogInfo[] = [
+      {
+        sequence: 6,
+        tab_id: 4,
+        type: "alert",
+        message: "scrolled",
+        handled: "accepted",
+        url: "https://example.test",
+      },
+    ];
+    f.cdp.dialogsSince = vi.fn(() => dialogs);
+    expect(await f.run()).toHaveProperty("dialogs", dialogs);
+    expect(f.cdp.dialogsSince).toHaveBeenCalledWith(4, 5);
+  });
+});

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

@@ -257,11 +257,15 @@ describe("handleSessionStop with auto-return", () => {
       moves: [],
     };
     const { tabs, windows } = makeApis(state, { moveThrowsFor: new Set([1]) });
+    const cdp = {
+      detachSession: vi.fn(async () => {}),
+      releaseSessionTab: vi.fn(async () => {}),
+    };
 
     const res = await handleSessionStop(
       sm,
       { session_id: "aa11" },
-      { tabManagement: { tabs, windows } },
+      { cdp, tabManagement: { tabs, windows } },
     );
     if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
     expect(res.return_failures?.map((f) => f.tab_id)).toEqual([1]);
@@ -269,6 +273,8 @@ describe("handleSessionStop with auto-return", () => {
     expect(sm.has("aa11")).toBe(true);
     expect(ctx.borrowedTabs.has(1)).toBe(true);
     expect(ctx.borrowedTabs.has(2)).toBe(false);
+    expect(cdp.releaseSessionTab).toHaveBeenCalledExactlyOnceWith("aa11", 2);
+    expect(cdp.detachSession).not.toHaveBeenCalled();
     expect(aw.remove).not.toHaveBeenCalled();
   });
 

apps/extension/src/tools/__tests__/snapshot-coordinates.browser.test.ts

@@ -0,0 +1,355 @@
+// @vitest-environment node
+import { describe, expect, it } from "vitest";
+import type { CdpFrame, CdpFrameGraph, CdpTarget } from "@/browser-driver/frame-graph";
+import { resolveNodeGeometry } from "../frame-geometry";
+import type { CdpRunner } from "../shared";
+import { captureObservationFacts } from "../vom/capture-coordinator";
+
+type Send = <T = Record<string, unknown>>(
+  method: string,
+  params?: object,
+  sessionId?: string,
+) => Promise<T>;
+type Tree = { frame: { id: string; parentId?: string; name?: string }; childFrames?: Tree[] };
+type Rect = { x: number; y: number; w: number; h: number };
+type Oracle = {
+  probes: Record<string, Rect>;
+  viewport: { width: number; height: number };
+  owners: Record<string, { x: number; y: number; scale: number }>;
+};
+
+function clip(rect: Rect, viewport: Oracle["viewport"]): Rect | null {
+  const x = Math.max(0, rect.x),
+    y = Math.max(0, rect.y);
+  const right = Math.min(viewport.width, rect.x + rect.w);
+  const bottom = Math.min(viewport.height, rect.y + rect.h);
+  return right > x && bottom > y ? { x, y, w: right - x, h: bottom - y } : null;
+}
+
+// The independent oracle uses DOM border boxes and this fixture's axis-aligned
+// iframe transforms. No production snapshot conversion/projection builds expectations.
+const oracleExpression = `(() => {
+  const probes = {};
+  for (const node of document.querySelectorAll('[data-geometry-probe]')) {
+    const box = node.getBoundingClientRect();
+    probes[node.id] = { x: box.x, y: box.y, w: box.width, h: box.height };
+  }
+  const owners = {};
+  for (const frame of document.querySelectorAll('iframe')) {
+    const rect = frame.getBoundingClientRect();
+    const style = getComputedStyle(frame);
+    const scale = rect.width / frame.offsetWidth;
+    owners[frame.name] = {
+      x: rect.x + (frame.clientLeft + parseFloat(style.paddingLeft)) * scale,
+      y: rect.y + (frame.clientTop + parseFloat(style.paddingTop)) * scale,
+      scale,
+    };
+  }
+  return { probes, viewport: { width: document.documentElement.clientWidth, height: document.documentElement.clientHeight }, owners };
+})()`;
+
+describe.skipIf(!process.env.BSK_GEOMETRY_CHROME)("real DOMSnapshot coordinate contract", () => {
+  it.each(
+    [
+      { deviceScale: 1, zoom: 1 },
+      { deviceScale: 0.8, zoom: 1 },
+      { deviceScale: 1, zoom: 1.25 },
+      { deviceScale: 2, zoom: 1 },
+      { deviceScale: 2, zoom: 0.8 },
+    ]
+      .flatMap((configuration) => [
+        { ...configuration, fixture: "snapshot-coordinates", scrollbars: "none" },
+        { ...configuration, fixture: "oopif-scrollbars", scrollbars: "both" },
+      ])
+      .concat(
+        ["vertical", "horizontal", "none"].map((scrollbars) => ({
+          deviceScale: 1,
+          zoom: 1,
+          fixture: "oopif-scrollbars",
+          scrollbars,
+        })),
+      ),
+  )("$fixture: device scale $deviceScale, zoom $zoom, scrollbars $scrollbars", async (configuration) => {
+    const evalRoot = new URL("../../../../../evals/browser/", import.meta.url);
+    const { createEvalServer } = await import(new URL("lib/server.mjs", evalRoot).href);
+    const { withChrome } = await import(
+      new URL("cases/regression/snapshot-coordinates/chrome.mjs", evalRoot).href
+    );
+    const server = createEvalServer();
+    const { baseUrl } = await server.start();
+    try {
+      await withChrome(
+        { executable: process.env.BSK_GEOMETRY_CHROME, ...configuration },
+        async (send: Send) => {
+          const { targetId } = await send<{ targetId: string }>("Target.createTarget", {
+            url: "about:blank",
+          });
+          const { sessionId: rootSession } = await send<{ sessionId: string }>(
+            "Target.attachToTarget",
+            { targetId, flatten: true },
+          );
+          await send(
+            "Page.navigate",
+            {
+              url: `${baseUrl}/${configuration.fixture}?run=coordinates&scrollbars=${configuration.scrollbars}`,
+            },
+            rootSession,
+          );
+          await expect
+            .poll(
+              () =>
+                server
+                  .snapshot("coordinates")
+                  .events.some(
+                    (event: { type: string; data: { root?: boolean } }) =>
+                      event.type === "geometry.ready" && event.data.root,
+                  ),
+              { timeout: 10_000 },
+            )
+            .toBe(true);
+
+          const targets = await send<{ targetInfos: { targetId: string; type: string }[] }>(
+            "Target.getTargets",
+          );
+          const sessions = [rootSession];
+          for (const target of targets.targetInfos.filter((target) => target.type === "iframe")) {
+            const { sessionId } = await send<{ sessionId: string }>("Target.attachToTarget", {
+              targetId: target.targetId,
+              flatten: true,
+            });
+            sessions.push(sessionId);
+          }
+          expect(sessions.length).toBe(configuration.fixture === "oopif-scrollbars" ? 3 : 2);
+          const frames: CdpFrame[] = [];
+          const names = new Map<string, string>();
+          const sessionFor = (target: CdpTarget) => target.sessionId ?? rootSession;
+          for (const sessionId of sessions) {
+            const { frameTree } = await send<{ frameTree: Tree }>(
+              "Page.getFrameTree",
+              {},
+              sessionId,
+            );
+            const target: CdpTarget = {
+              tabId: 1,
+              ...(sessionId === rootSession ? {} : { sessionId }),
+            };
+            const visit = (tree: Tree, parentFrameId = tree.frame.parentId) => {
+              frames.push({ frameId: tree.frame.id, parentFrameId, target });
+              names.set(tree.frame.id, tree.frame.name ?? "");
+              for (const child of tree.childFrames ?? []) visit(child, tree.frame.id);
+            };
+            visit(frameTree);
+          }
+          expect(frames).toHaveLength(configuration.fixture === "oopif-scrollbars" ? 3 : 5);
+          for (const frame of frames) {
+            if (!frame.parentFrameId) continue;
+            const parent = frames.find((item) => item.frameId === frame.parentFrameId)!;
+            const owner = await send<{ backendNodeId: number }>(
+              "DOM.getFrameOwner",
+              { frameId: frame.frameId },
+              sessionFor(parent.target),
+            );
+            frame.ownerBackendNodeId = owner.backendNodeId;
+          }
+          const graph: CdpFrameGraph = { rootFrameId: frames[0].frameId, frames };
+          const calls: string[] = [];
+          const cdp: CdpRunner = {
+            send: (tabId, method, params) => {
+              calls.push(`${tabId}:${method}`);
+              return send(method, params, rootSession);
+            },
+            sendToTarget: (target, method, params) => {
+              calls.push(`${target.sessionId ?? target.tabId}:${method}`);
+              if (
+                method === "Runtime.evaluate" &&
+                (params as { expression?: string })?.expression?.includes("window.innerWidth")
+              )
+                calls.push(`${target.sessionId ?? target.tabId}:viewport-size`);
+              return send(method, params, sessionFor(target));
+            },
+            getFrameGraph: async () => graph,
+            getAttachmentId: () => rootSession,
+          };
+          const oracles = new Map<string, Oracle>();
+          for (const frame of frames) {
+            const session = sessionFor(frame.target);
+            const { executionContextId } = await send<{ executionContextId: number }>(
+              "Page.createIsolatedWorld",
+              { frameId: frame.frameId, worldName: "coordinate-oracle" },
+              session,
+            );
+            await expect
+              .poll(
+                async () => {
+                  const ready = await send<{ result: { value: boolean } }>(
+                    "Runtime.evaluate",
+                    {
+                      expression: 'document.documentElement.dataset.geometryReady === "true"',
+                      contextId: executionContextId,
+                      returnByValue: true,
+                    },
+                    session,
+                  );
+                  return ready.result.value;
+                },
+                { timeout: 5_000 },
+              )
+              .toBe(true);
+            // Establish scroll after cross-process target creation/layout settles.
+            const scroll = frame.parentFrameId
+              ? names.get(frame.frameId) === "nested"
+                ? [10, 20]
+                : [40, 100]
+              : [80, 240];
+            await send(
+              "Runtime.evaluate",
+              {
+                expression: `(async () => { scrollTo(${scroll.join(",")}); await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))); })()`,
+                contextId: executionContextId,
+                awaitPromise: true,
+              },
+              session,
+            );
+            const reply = await send<{ result: { value: Oracle } }>(
+              "Runtime.evaluate",
+              { expression: oracleExpression, contextId: executionContextId, returnByValue: true },
+              session,
+            );
+            oracles.set(frame.frameId, reply.result.value);
+          }
+          const childViewport = await send<{
+            result: {
+              value: { width: number; height: number; clientWidth: number; clientHeight: number };
+            };
+          }>(
+            "Runtime.evaluate",
+            {
+              expression:
+                "({ width: innerWidth, height: innerHeight, clientWidth: document.documentElement.clientWidth, clientHeight: document.documentElement.clientHeight })",
+              returnByValue: true,
+            },
+            sessions[1],
+          );
+          for (const dimension of ["Width", "Height"] as const) {
+            const occupied =
+              childViewport.result.value[dimension === "Width" ? "width" : "height"] -
+              childViewport.result.value[`client${dimension}`];
+            if (
+              configuration.scrollbars === "both" ||
+              configuration.scrollbars === (dimension === "Width" ? "vertical" : "horizontal")
+            )
+              expect(occupied).toBeGreaterThan(0);
+            else expect(occupied).toBe(0);
+          }
+          const facts = await captureObservationFacts(cdp, 1);
+          expect(facts.issues).toEqual([]);
+          expect(calls.filter((call) => call.endsWith(":Page.getLayoutMetrics"))).toHaveLength(
+            sessions.length,
+          );
+          // Identity verification also uses Runtime.evaluate; count the full viewport reads separately.
+          const viewportReadsBeforeLive = calls.filter((call) => call.endsWith(":viewport-size"));
+          expect(new Set(viewportReadsBeforeLive).size).toBe(viewportReadsBeforeLive.length);
+          expect(viewportReadsBeforeLive.length).toBeLessThanOrEqual(sessions.length - 1);
+          for (const frame of frames) {
+            for (const [id, local] of Object.entries(oracles.get(frame.frameId)!.probes)) {
+              const node = facts.documents
+                .find((doc) => doc.frame.frameId === frame.frameId)
+                ?.domNodes.find((node) => node.attrs.id === id);
+              expect(node, `missing ${id} in ${names.get(frame.frameId) || "root"}`).toBeDefined();
+              let top = clip(local, oracles.get(frame.frameId)!.viewport);
+              let current = frame;
+              while (top && current.parentFrameId) {
+                const parentOracle = oracles.get(current.parentFrameId)!;
+                const owner = parentOracle.owners[names.get(current.frameId)!];
+                top = clip(
+                  {
+                    x: owner.x + top.x * owner.scale,
+                    y: owner.y + top.y * owner.scale,
+                    w: top.w * owner.scale,
+                    h: top.h * owner.scale,
+                  },
+                  parentOracle.viewport,
+                );
+                current = frames.find((item) => item.frameId === current.parentFrameId)!;
+              }
+              for (const key of ["x", "y", "w", "h"] as const)
+                expect(
+                  Math.abs(node!.localRect![key] - local[key]),
+                  `${names.get(frame.frameId)} ${id} local ${key}`,
+                ).toBeLessThan(2);
+              if (!top) {
+                expect(node!.rect, `${id} must be clipped out`).toBeNull();
+                if (configuration.fixture === "oopif-scrollbars")
+                  expect(
+                    await resolveNodeGeometry(cdp, 1, {
+                      target: frame.target,
+                      frameId: frame.frameId,
+                      backendNodeId: node!.backendNodeId,
+                    }),
+                  ).toMatchObject({ code: "permission_denied" });
+                continue;
+              }
+              expect(node!.rect).not.toBeNull();
+              for (const key of ["x", "y", "w", "h"] as const)
+                expect(
+                  Math.abs(node!.rect![key] - top[key]),
+                  `${names.get(frame.frameId)} ${id} top ${key}`,
+                ).toBeLessThan(2);
+              if (configuration.fixture !== "oopif-scrollbars") continue;
+              const live = await resolveNodeGeometry(cdp, 1, {
+                target: frame.target,
+                frameId: frame.frameId,
+                backendNodeId: node!.backendNodeId,
+              });
+              if ("code" in live) throw new Error(live.message);
+              for (const [key, liveKey] of [
+                ["x", "x"],
+                ["y", "y"],
+                ["w", "width"],
+                ["h", "height"],
+              ] as const)
+                expect(
+                  Math.abs(live.topBounds[liveKey] - top[key]),
+                  `${id} live ${key}`,
+                ).toBeLessThan(2);
+              const before = server.snapshot("coordinates").events.length;
+              for (const type of ["mousePressed", "mouseReleased"])
+                await send(
+                  "Input.dispatchMouseEvent",
+                  { type, ...live.actionPoint, button: "left", clickCount: 1 },
+                  rootSession,
+                );
+              await expect
+                .poll(
+                  () =>
+                    server
+                      .snapshot("coordinates")
+                      .events.slice(before)
+                      .some(
+                        (event: { type: string; path: string; data: { probe?: string } }) =>
+                          event.type === "geometry.clicked" &&
+                          event.data.probe === id &&
+                          event.path ===
+                            (frame.parentFrameId
+                              ? names.get(frame.frameId) === "nested"
+                                ? "/oopif-scrollbars/nested"
+                                : "/oopif-scrollbars/frame"
+                              : "/oopif-scrollbars"),
+                      ),
+                  { timeout: 3000 },
+                )
+                .toBe(true);
+            }
+          }
+          const metrics = await send<{
+            cssVisualViewport: { zoom: number };
+            visualViewport: { clientWidth: number };
+          }>("Page.getLayoutMetrics", {}, rootSession);
+          expect(metrics.cssVisualViewport.zoom).toBeCloseTo(configuration.zoom, 4);
+        },
+      );
+    } finally {
+      await server.stop();
+    }
+  }, 30_000);
+});

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

@@ -1,5 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
+import { type CdpDebuggerApi, ChromiumCdp } from "@/browser-driver/chromium-cdp";
 import { SessionManager } from "@/session-manager/manager";
+import { handleHover } from "../interaction";
 import {
   type AgentOverlayResetApi,
   type ChromeWindowsApi,
@@ -547,6 +549,148 @@ describe("handleTabBorrow", () => {
 });
 
 describe("handleTabReturn", () => {
+  it.each([
+    "not_found",
+    "cdp_failed",
+  ])("detaches after selector resolution fails with %s", async (code) => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
+    const state: FakeTabState = {
+      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
+      nextTabId: 50,
+      windowsClosed: new Set(),
+    };
+    const { api } = makeTabMutationApi(state);
+    const { api: windows } = makeWindowsApi(state);
+    const debuggerApi = {
+      attach: vi.fn(async () => {}),
+      detach: vi.fn(async () => {}),
+      sendCommand: vi.fn(async (_target: unknown, method: string) => {
+        if (method === "DOM.getDocument") return { root: { nodeId: 1 } };
+        if (method === "DOM.querySelector") {
+          if (code === "cdp_failed") throw new Error("selector query failed");
+          return { nodeId: 0 };
+        }
+        return {};
+      }),
+      onEvent: { addListener: vi.fn(), removeListener: vi.fn() },
+      onDetach: { addListener: vi.fn(), removeListener: vi.fn() },
+    };
+    const cdp = new ChromiumCdp(debuggerApi as unknown as CdpDebuggerApi);
+
+    const hover = await handleHover(
+      sm,
+      { session_id: "aa11", tab_id: 7, selector: "#missing" },
+      {
+        cdp,
+        tabsApi: { get: api.get, query: vi.fn(async () => []) },
+      },
+    );
+    expect(hover).toMatchObject({ code });
+    expect(cdp.isAttached(7)).toBe(true);
+
+    const returned = await handleTabReturn(
+      sm,
+      { session_id: "aa11", tab_id: 7 },
+      {
+        tabs: api,
+        windows,
+        cdp,
+        agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
+      },
+    );
+    expect(returned).toMatchObject({ returned_to_window_id: 200 });
+    expect(ctx.borrowedTabs.has(7)).toBe(false);
+    expect(cdp.isAttached(7)).toBe(false);
+    expect(debuggerApi.detach).toHaveBeenCalledExactlyOnceWith({ tabId: 7 });
+    cdp.dispose();
+  });
+
+  it("honours cancellation while preparing a validated return", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
+    const state: FakeTabState = {
+      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
+      nextTabId: 50,
+      windowsClosed: new Set(),
+    };
+    const { api, spies } = makeTabMutationApi(state);
+    const { api: windows } = makeWindowsApi(state);
+    const controller = new AbortController();
+    const beforeReturn = vi.fn(async () => {
+      controller.abort();
+    });
+    const result = await handleTabReturn(
+      sm,
+      { session_id: "aa11", tab_id: 7 },
+      {
+        tabs: api,
+        windows,
+        signal: controller.signal,
+        beforeReturn,
+      },
+    );
+
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(beforeReturn).toHaveBeenCalledExactlyOnceWith("aa11", 7);
+    expect(spies.move).not.toHaveBeenCalled();
+    expect(ctx.borrowedTabs.has(7)).toBe(true);
+  });
+
+  it.each([
+    "original",
+    "fallback",
+    "cleanup_failed",
+    "failed",
+    "cancelled",
+  ])("releases CDP only after a successful return (%s)", async (mode) => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    ctx.borrowedTabs.set(7, { tabId: 7, originalWindowId: 200, originalIndex: 4 });
+    const state: FakeTabState = {
+      tabs: new Map([[7, { id: 7, windowId: 100 } as chrome.tabs.Tab]]),
+      nextTabId: 50,
+      windowsClosed: new Set(),
+    };
+    const { api, spies } = makeTabMutationApi(state);
+    const { api: windowsApi } = makeWindowsApi(state, { lastFocused: 500 });
+    const success = mode !== "failed" && mode !== "cancelled";
+    if (mode === "fallback") spies.move.mockRejectedValueOnce(new Error("original move failed"));
+    if (mode === "failed") spies.move.mockRejectedValue(new Error("move failed"));
+    let windowAtRelease: number | undefined;
+    const cdp = {
+      releaseSessionTab: vi.fn(async () => {
+        windowAtRelease = state.tabs.get(7)?.windowId;
+        if (mode === "cleanup_failed") throw new Error("debugger release failed");
+      }),
+    };
+    const controller = new AbortController();
+    if (mode === "cancelled") controller.abort();
+
+    const result = await handleTabReturn(
+      sm,
+      { session_id: "aa11", tab_id: 7 },
+      {
+        tabs: api,
+        windows: windowsApi,
+        cdp,
+        signal: controller.signal,
+        agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
+      },
+    );
+
+    expect("code" in result).toBe(!success);
+    expect(ctx.borrowedTabs.has(7)).toBe(!success);
+    expect(cdp.releaseSessionTab).toHaveBeenCalledTimes(success ? 1 : 0);
+    if (success) {
+      expect(cdp.releaseSessionTab).toHaveBeenCalledWith("aa11", 7);
+      expect(windowAtRelease).toBe(mode === "fallback" ? 500 : 200);
+      expect(spies.move).toHaveBeenCalledTimes(mode === "fallback" ? 2 : 1);
+    }
+  });
+
   it("returns the tab to its original window/index and clears borrowedTabs", async () => {
     const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
     const ctx = await sm.start("aa11");

apps/extension/src/tools/browser-navigation.ts

@@ -0,0 +1,110 @@
+import type { RpcError, WaitUntil } from "@/transport/types";
+import { cdpError } from "./errors";
+
+interface NavigationEvent {
+  tabId: number;
+  frameId: number;
+  documentId?: string;
+  error?: string;
+}
+
+interface NavigationEvents {
+  addListener(listener: (details: NavigationEvent) => void): void;
+  removeListener(listener: (details: NavigationEvent) => void): void;
+}
+
+/** Normal browser navigation remains available when chrome.debugger is denied. */
+export interface BrowserNavigationApi {
+  update(tabId: number, props: { url: string }): Promise<unknown>;
+  reload(tabId: number, props: { bypassCache: boolean }): Promise<void>;
+  onCommitted: NavigationEvents;
+  onDOMContentLoaded: NavigationEvents;
+  onCompleted: NavigationEvents;
+  onErrorOccurred: NavigationEvents;
+}
+
+export const chromeBrowserNavigationApi: BrowserNavigationApi = {
+  update: (tabId, props) => chrome.tabs.update(tabId, props),
+  reload: (tabId, props) => chrome.tabs.reload(tabId, props),
+  get onCommitted() {
+    return chrome.webNavigation.onCommitted;
+  },
+  get onDOMContentLoaded() {
+    return chrome.webNavigation.onDOMContentLoaded;
+  },
+  get onCompleted() {
+    return chrome.webNavigation.onCompleted;
+  },
+  get onErrorOccurred() {
+    return chrome.webNavigation.onErrorOccurred;
+  },
+};
+
+export type NavigationOutcome =
+  | { reached: "match" | "timeout" | "cancelled"; lastLifecycle?: string }
+  | { reached: "failed"; error: RpcError };
+
+/** Subscribe before dispatch and ignore the departing document's load events. */
+export async function navigateWithBrowserApi(
+  api: BrowserNavigationApi,
+  tabId: number,
+  action: () => Promise<unknown>,
+  waitUntil: Exclude<WaitUntil, "networkidle">,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<NavigationOutcome> {
+  if (signal?.aborted) return { reached: "cancelled" };
+  if (timeoutMs <= 0) return { reached: "timeout" };
+  let committed = false;
+  let documentId: string | undefined;
+  let lastLifecycle: string | undefined;
+  let finish!: (outcome: NavigationOutcome) => void;
+  const outcome = new Promise<NavigationOutcome>((resolve) => {
+    finish = resolve;
+  });
+  const isMainFrame = (details: NavigationEvent) =>
+    details.tabId === tabId && details.frameId === 0;
+  const onCommitted = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    committed = true;
+    documentId = details.documentId;
+    lastLifecycle = "commit";
+    if (waitUntil === "commit") finish({ reached: "match", lastLifecycle });
+  };
+  const onDOMContentLoaded = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    lastLifecycle = "DOMContentLoaded";
+    if (waitUntil === "domcontentloaded") finish({ reached: "match", lastLifecycle });
+  };
+  const onCompleted = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    finish({ reached: "match", lastLifecycle: "load" });
+  };
+  const onError = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    finish({ reached: "failed", error: cdpError(details.error ?? "browser navigation failed") });
+  };
+  const onAbort = () => finish({ reached: "cancelled", lastLifecycle });
+  const subscriptions = [
+    [api.onCommitted, onCommitted],
+    [api.onDOMContentLoaded, onDOMContentLoaded],
+    [api.onCompleted, onCompleted],
+    [api.onErrorOccurred, onError],
+  ] as const;
+  for (const [event, listener] of subscriptions) event.addListener(listener);
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => finish({ reached: "timeout", lastLifecycle }), timeoutMs);
+  try {
+    if (signal?.aborted) return { reached: "cancelled" };
+    await action();
+    return await outcome;
+  } catch (error) {
+    return { reached: "failed", error: cdpError(error) };
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+    for (const [event, listener] of subscriptions) event.removeListener(listener);
+  }
+}

apps/extension/src/tools/dispatcher.ts

@@ -2,12 +2,14 @@ import { OVERLAY_AUTOMATION_BYPASS } from "@/lib/overlay-bridge";
 import type { SessionManager } from "@/session-manager/manager";
 import type { Transport } from "@/transport/transport";
 import type {
+  BlurParams,
   ClickParams,
   ConsoleParams,
   DownloadParams,
   EmulateParams,
   EvaluateParams,
   FillParams,
+  FocusParams,
   GetHtmlParams,
   HoverParams,
   HoverResult,
@@ -27,6 +29,7 @@ import type {
   ResponseFrame,
   RpcError,
   ScreenshotParams,
+  ScrollToParams,
   SelectParams,
   SnapshotParams,
   UploadParams,
@@ -36,9 +39,18 @@ import { isRequestFrame } from "@/transport/types";
 import { handleConsole } from "./console";
 import { handleDownload } from "./download";
 import { type EmulateCdpRunner, handleEmulate } from "./emulate";
+import { classifyCdpError } from "./errors";
 import { handleEvaluate } from "./evaluate";
 import { handleRequestHelp } from "./human-loop";
-import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
+import {
+  handleBlur,
+  handleClick,
+  handleFill,
+  handleFocus,
+  handleHover,
+  handlePress,
+  handleSelect,
+} from "./interaction";
 import {
   handleNavigate,
   handleNavigateBack,
@@ -60,6 +72,7 @@ import {
   handleRecordStop,
   type RecordRuntimeDeps,
 } from "./record";
+import { handleScrollTo } from "./scroll";
 import {
   handleSessionStart,
   handleSessionStop,
@@ -239,7 +252,7 @@ export class ToolDispatcher {
       if (sessionId) this.onBrowserControlResumed?.(sessionId);
       const result = await this.invoke(req, ac.signal);
       if (isRpcError(result)) {
-        body = { id: req.id, error: result };
+        body = { id: req.id, error: classifyCdpError(result) };
       } else {
         body = { id: req.id, result };
         if (req.method === "tool.session_start") {
@@ -345,7 +358,11 @@ export class ToolDispatcher {
         return result;
       }
       case "tool.tab_return":
-        return handleTabReturn(this.sessions, req.params as TabReturnParams, { signal });
+        return handleTabReturn(this.sessions, req.params as TabReturnParams, {
+          signal,
+          cdp: this.cdp,
+          beforeReturn: (sessionId, tabId) => this.releaseHoverLatch(sessionId, tabId),
+        });
       case "tool.window_resize":
         return handleWindowResize(
           this.sessions,
@@ -510,6 +527,39 @@ export class ToolDispatcher {
         );
         return this.rememberHover((req.params as HoverParams).session_id, result);
       }
+      case "tool.scroll_to":
+        return this.withHoverReleaseForRequest(
+          req.params as ScrollToParams,
+          () =>
+            handleScrollTo(
+              this.sessions,
+              req.params as ScrollToParams,
+              this.cdp ? { cdp: this.cdp, tabsApi: chromeTabsApi, signal } : undefined,
+            ),
+          signal,
+        );
+      case "tool.focus":
+        return this.withHoverReleaseForRequest(
+          req.params as FocusParams,
+          () =>
+            handleFocus(
+              this.sessions,
+              req.params as FocusParams,
+              this.cdp ? { cdp: this.cdp, tabsApi: chromeTabsApi, signal } : undefined,
+            ),
+          signal,
+        );
+      case "tool.blur":
+        return this.withHoverReleaseForRequest(
+          req.params as BlurParams,
+          () =>
+            handleBlur(
+              this.sessions,
+              req.params as BlurParams,
+              this.cdp ? { cdp: this.cdp, tabsApi: chromeTabsApi, signal } : undefined,
+            ),
+          signal,
+        );
       case "tool.fill":
         return this.withHoverReleaseForRequest(
           req.params as FillParams,
@@ -780,6 +830,9 @@ function sessionIdForBrowserControlMethod(req: RequestFrame): string | null {
     case "tool.reload":
     case "tool.click":
     case "tool.hover":
+    case "tool.scroll_to":
+    case "tool.focus":
+    case "tool.blur":
     case "tool.fill":
     case "tool.press":
     case "tool.select":

apps/extension/src/tools/errors.ts

@@ -13,6 +13,34 @@ import type {
 
 export type { RpcErrorData, RpcErrorReason };
 
+/** Chrome checks the whole tab's frame tree, including other extensions' frames. */
+export function isCdpExtensionAccessDenied(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Cannot access a chrome-extension:// URL of different extension");
+}
+
+/** Preserve more specific reasons, especially file-transfer outcome/cleanup details. */
+export function classifyCdpError(error: RpcError): RpcError {
+  if (
+    error.code !== "cdp_failed" ||
+    error.data?.reason ||
+    !isCdpExtensionAccessDenied(error.message)
+  ) {
+    return error;
+  }
+  return {
+    ...error,
+    data: { ...error.data, reason: "cdp_extension_access_denied" },
+  };
+}
+
+export function cdpError(error: unknown): RpcError {
+  return classifyCdpError({
+    code: "cdp_failed",
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
 export interface TransferErrorOptions {
   effectState: TransferEffectState;
   phase: string;

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

@@ -1,24 +1,21 @@
-import { type CdpFrame, type CdpFrameGraph, type CdpTarget } from "@/browser-driver/frame-graph";
+import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
 import type { RpcError } from "@/transport/types";
 import { nodeContentRegion, scrollNodeIntoView } from "./element-geometry";
 import {
   clipPolygon,
-  type GeometryProjection,
   type Point,
   type Polygon,
-  type ProjectiveEdge,
-  parseCdpQuad,
   polygonArea,
   polygonCentroid,
   projectRegionToViewport,
-  type Quad,
   type Region,
   rectPolygon,
   regionBounds,
-  type Size,
   type ViewportRect,
 } from "./geometry";
-import { type CdpRunner, cdpRunnerForTarget, isRpcError, sendToCdpTarget } from "./shared";
+import type { CssViewport } from "./geometry/coordinate-types";
+import { cssViewport, GeometryContext } from "./geometry/frame-context";
+import { type CdpRunner, cdpRunnerForTarget, isRpcError } from "./shared";
 
 export interface NodeAddress {
   target: CdpTarget;
@@ -27,6 +24,8 @@ export interface NodeAddress {
 }
 
 export interface ResolvedNodeGeometry {
+  /** The same top-level measurement used by projection, for screenshot coordinate adaptation. */
+  topViewport: CssViewport;
   topVisibleRegions: Region;
   topBounds: ViewportRect;
   /** Point in the top-level tab viewport, used by root-target input events. */
@@ -39,145 +38,16 @@ function geometryError(message: string): RpcError {
   return { code: "cdp_failed", message };
 }
 
-function frameMap(graph: CdpFrameGraph): Map<string, CdpFrame> {
-  return new Map(graph.frames.map((frame) => [frame.frameId, frame]));
-}
-
-function targetRootFrame(byId: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
-  const seen = new Set<string>();
-  let current = frame;
-  while (current.parentFrameId) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent || parent.target.sessionId !== current.target.sessionId) break;
-    current = parent;
-  }
-  return current;
-}
-
-function frameAncestry(graph: CdpFrameGraph, frameId: string): CdpFrame[] | null {
-  const byId = frameMap(graph);
-  const path: CdpFrame[] = [];
-  const seen = new Set<string>();
-  let current = byId.get(frameId);
-  if (!current) return null;
-  while (current.parentFrameId) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    path.push(current);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent) return null;
-    current = parent;
-  }
-  return path;
-}
-
-async function targetViewport(cdp: CdpRunner, target: CdpTarget): Promise<Size | null> {
-  const metrics = await sendToCdpTarget<{
-    cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
-    layoutViewport?: { clientWidth?: number; clientHeight?: number };
-  }>(cdp, target, "Page.getLayoutMetrics", {});
-  const viewport = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-  const width = viewport.clientWidth ?? 0;
-  const height = viewport.clientHeight ?? 0;
-  return width > 0 && height > 0 ? { width, height } : null;
-}
-
-async function ownerContentQuad(
-  cdp: CdpRunner,
-  parent: CdpFrame,
-  ownerBackendNodeId: number,
-): Promise<Quad | null> {
-  const result = await sendToCdpTarget<{ model?: { content?: number[] } }>(
-    cdp,
-    parent.target,
-    "DOM.getBoxModel",
-    { backendNodeId: ownerBackendNodeId },
-  );
-  return parseCdpQuad(result.model?.content);
-}
-
-async function sameTargetFrameClips(
-  cdp: CdpRunner,
-  byId: Map<string, CdpFrame>,
-  frame: CdpFrame,
-  targetRoot: CdpFrame,
-): Promise<Polygon[] | null> {
-  const clips: Polygon[] = [];
-  let current = frame;
-  const seen = new Set<string>();
-  while (current.frameId !== targetRoot.frameId) {
-    if (seen.has(current.frameId) || !current.parentFrameId) return null;
-    seen.add(current.frameId);
-    const parent = byId.get(current.parentFrameId);
-    if (!parent || current.ownerBackendNodeId === undefined) return null;
-    const clip = await ownerContentQuad(cdp, parent, current.ownerBackendNodeId);
-    if (!clip) return null;
-    clips.push(clip);
-    current = parent;
-  }
-  return clips;
-}
-
-export async function resolveFrameProjection(
-  cdp: CdpRunner,
-  graph: CdpFrameGraph,
-  frameId: string,
-): Promise<GeometryProjection | null> {
-  const byId = frameMap(graph);
-  const frame = byId.get(frameId);
-  if (!frame) return null;
-  let targetRoot = targetRootFrame(byId, frame);
-  if (!targetRoot) return null;
-  const sourceViewport = await targetViewport(cdp, targetRoot.target);
-  if (!sourceViewport) return null;
-  const sourceClips = await sameTargetFrameClips(cdp, byId, frame, targetRoot);
-  if (!sourceClips) return null;
-
-  const edges: ProjectiveEdge[] = [];
-  while (targetRoot.parentFrameId) {
-    const parent = byId.get(targetRoot.parentFrameId);
-    if (!parent || targetRoot.ownerBackendNodeId === undefined) return null;
-    const destinationQuad = await ownerContentQuad(cdp, parent, targetRoot.ownerBackendNodeId);
-    if (!destinationQuad) return null;
-    const source =
-      edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
-    if (!source) return null;
-    const parentTargetRoot = targetRootFrame(byId, parent);
-    if (!parentTargetRoot) return null;
-    const destinationClips = await sameTargetFrameClips(cdp, byId, parent, parentTargetRoot);
-    if (!destinationClips) return null;
-    edges.push({ sourceViewport: source, destinationQuad, destinationClips });
-    targetRoot = parentTargetRoot;
-  }
-
-  const topViewport =
-    edges.length === 0 ? sourceViewport : await targetViewport(cdp, targetRoot.target);
-  return topViewport ? { sourceClips, edges, topViewport } : null;
-}
-
-async function loadFrameGraph(cdp: CdpRunner, tabId: number): Promise<CdpFrameGraph | null> {
-  if (!cdp.getFrameGraph) return null;
-  try {
-    return await cdp.getFrameGraph(tabId);
-  } catch (error) {
-    console.debug("[bsk frame-geometry] frame graph resolution failed", error);
-    return null;
-  }
-}
-
 async function scrollFrameOwners(
   cdp: CdpRunner,
   tabId: number,
-  graph: CdpFrameGraph,
+  context: GeometryContext,
   frameId: string,
 ): Promise<RpcError | null> {
-  const byId = frameMap(graph);
-  const ancestry = frameAncestry(graph, frameId);
+  const ancestry = await context.ancestry(frameId);
   if (!ancestry) return geometryError(`could not resolve frame ancestry for ${frameId}`);
   for (const child of [...ancestry].reverse()) {
-    const parent = child.parentFrameId ? byId.get(child.parentFrameId) : undefined;
+    const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
     if (!parent || child.ownerBackendNodeId === undefined) {
       return geometryError(`could not resolve frame owner for ${child.frameId}`);
     }
@@ -191,17 +61,20 @@ async function scrollFrameOwners(
   return null;
 }
 
-async function scrollElementWithFrameGraph(
+async function scrollElementWithContext(
   cdp: CdpRunner,
   tabId: number,
   target: CdpTarget,
   backendNodeId: number,
   frameId: string | undefined,
-  graph: CdpFrameGraph | null,
+  context: GeometryContext,
 ): Promise<RpcError | null> {
   if (frameId) {
-    if (!graph) return geometryError(`could not resolve frame graph for ${frameId}`);
-    const error = await scrollFrameOwners(cdp, tabId, graph, frameId);
+    const frame = await context.frame(frameId);
+    if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(target)) {
+      return geometryError("node frame does not belong to its target");
+    }
+    const error = await scrollFrameOwners(cdp, tabId, context, frameId);
     if (error) return error;
   } else if (target.sessionId) {
     return geometryError("an OOPIF node address requires frameId");
@@ -216,8 +89,15 @@ export async function scrollElementAndFramesIntoView(
   backendNodeId: number,
   frameId?: string,
 ): Promise<RpcError | null> {
-  const graph = frameId ? await loadFrameGraph(cdp, tabId) : null;
-  return scrollElementWithFrameGraph(cdp, tabId, target, backendNodeId, frameId, graph);
+  if (target.tabId !== tabId) return geometryError("node target belongs to another tab");
+  return scrollElementWithContext(
+    cdp,
+    tabId,
+    target,
+    backendNodeId,
+    frameId,
+    new GeometryContext(cdp, tabId),
+  );
 }
 
 function largestRegion(regions: Region): Polygon | null {
@@ -240,23 +120,32 @@ export async function resolveNodeGeometry(
     if (address.target.sessionId && !address.frameId) {
       return geometryError("an OOPIF node address requires frameId");
     }
-    const graph = address.frameId ? await loadFrameGraph(cdp, tabId) : null;
+    if (address.target.tabId !== tabId) return geometryError("node target belongs to another tab");
+    const context = new GeometryContext(cdp, tabId);
+    const graph = address.frameId ? await context.graph() : null;
+    if (address.frameId && graph) {
+      const frame = await context.frame(address.frameId);
+      if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(address.target)) {
+        return geometryError("node frame does not belong to its target");
+      }
+    }
     if (address.frameId && !graph) {
       return geometryError(`could not resolve frame graph for ${address.frameId}`);
     }
 
     if (options.scrollIntoView) {
-      const scrollError = await scrollElementWithFrameGraph(
+      const scrollError = await scrollElementWithContext(
         cdp,
         tabId,
         address.target,
         address.backendNodeId,
         address.frameId,
-        graph,
+        context,
       );
       if (scrollError) return scrollError;
     }
 
+    // Only topology was read above. Begin live measurements after scrolling.
     const localRegion = await nodeContentRegion(
       cdpRunnerForTarget(cdp, address.target),
       tabId,
@@ -267,12 +156,13 @@ export async function resolveNodeGeometry(
     let topVisibleRegions: Region;
     let targetActionPoint: Point | null = null;
     if (address.frameId && graph) {
-      const projection = await resolveFrameProjection(cdp, graph, address.frameId);
+      const projection = await context.targetProjection(address.frameId);
       if (!projection)
         return geometryError(`could not resolve frame geometry for ${address.frameId}`);
       topVisibleRegions = projectRegionToViewport(localRegion, projection);
       if (address.target.sessionId) {
-        const localViewport = projection.edges[0]?.sourceViewport ?? projection.topViewport;
+        const localViewport = await context.viewport(address.target);
+        if (!localViewport) return geometryError("could not resolve target viewport geometry");
         const localVisibleRegions = localRegion
           .map((polygon) =>
             clipPolygon(
@@ -290,7 +180,7 @@ export async function resolveNodeGeometry(
         targetActionPoint = localActionRegion ? polygonCentroid(localActionRegion) : null;
       }
     } else {
-      const viewport = await targetViewport(cdp, address.target);
+      const viewport = await context.viewport(address.target);
       if (!viewport) return geometryError("could not resolve top viewport geometry");
       topVisibleRegions = localRegion
         .map((polygon) =>
@@ -309,7 +199,13 @@ export async function resolveNodeGeometry(
       return { code: "permission_denied", message: "element not visible in its target" };
     }
     targetActionPoint ??= actionPoint;
-    return { topVisibleRegions, topBounds, actionPoint, targetActionPoint };
+    return {
+      topVisibleRegions,
+      topBounds,
+      actionPoint,
+      targetActionPoint,
+      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
+    };
   } catch (error) {
     return geometryError(error instanceof Error ? error.message : String(error));
   }

apps/extension/src/tools/geometry.ts

@@ -245,22 +245,3 @@ export function projectRectToViewport(
   if (!rect) return null;
   return regionBounds(projectRegionToViewport([rectPolygon(rect)], projection));
 }
-
-export function childFrameProjection(
-  parent: GeometryProjection,
-  ownerRectInParent: { x: number; y: number; w: number; h: number },
-): GeometryProjection {
-  const destinationQuad = rectPolygon(ownerRectInParent);
-  return {
-    sourceClips: [],
-    edges: [
-      {
-        sourceViewport: { width: ownerRectInParent.w, height: ownerRectInParent.h },
-        destinationQuad,
-        destinationClips: parent.sourceClips,
-      },
-      ...parent.edges,
-    ],
-    topViewport: parent.topViewport,
-  };
-}

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

@@ -0,0 +1,157 @@
+import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { GeometryProjection, ViewportRect } from "../geometry";
+import { projectRectToViewport } from "../geometry";
+
+export interface CoordinateOwner {
+  target: CdpTarget;
+  frameId?: string;
+}
+
+export interface FrameViewportRect {
+  space: "frame-viewport-css";
+  owner: CoordinateOwner;
+  rect: ViewportRect;
+}
+
+export interface SnapshotProjection {
+  source: CoordinateOwner;
+  geometry: GeometryProjection;
+}
+
+/** A failed owner read is different from a successfully projected, clipped-out rect. */
+export interface UnavailableFrameProjection {
+  status: "unavailable";
+  source: CoordinateOwner;
+  ownerBackendNodeId: number;
+}
+
+export interface UnavailableSnapshotCoordinates {
+  status: "unavailable";
+  source: CoordinateOwner;
+  reason: "snapshot-coordinates-unavailable";
+}
+
+export type SnapshotProjectionResult =
+  | { status: "available"; projection: SnapshotProjection }
+  | UnavailableFrameProjection;
+
+/** Descendants inherit the failed boundary without attempting another owner read. */
+export type FrameProjectionIssue =
+  | UnavailableFrameProjection
+  | UnavailableSnapshotCoordinates
+  | {
+      status: "blocked";
+      source: CoordinateOwner;
+      cause: UnavailableFrameProjection | UnavailableSnapshotCoordinates;
+    };
+
+export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
+
+export interface SnapshotCoordinates {
+  layoutUnitsPerCssPixel: number;
+  scrollCss: { x: number; y: number };
+}
+
+/** Snapshot scroll offsets share the raw layout units of its bounds. Only a
+ * target's root document may fall back to that target's CSS layout viewport. */
+export function snapshotCoordinates(
+  document: { scrollOffsetX?: number; scrollOffsetY?: number },
+  layoutUnitsPerCssPixel: number | null,
+  rootScrollCss?: { x?: number; y?: number },
+): SnapshotCoordinates | null {
+  if (
+    layoutUnitsPerCssPixel === null ||
+    !Number.isFinite(layoutUnitsPerCssPixel) ||
+    layoutUnitsPerCssPixel <= 0
+  )
+    return null;
+  const x =
+    document.scrollOffsetX === undefined
+      ? rootScrollCss?.x
+      : document.scrollOffsetX / layoutUnitsPerCssPixel;
+  const y =
+    document.scrollOffsetY === undefined
+      ? rootScrollCss?.y
+      : document.scrollOffsetY / layoutUnitsPerCssPixel;
+  if (x === undefined || y === undefined || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { layoutUnitsPerCssPixel, scrollCss: { x, y } };
+}
+
+/** Convert raw document-relative Blink layout units exactly once, before any
+ * CSS viewport clipping or frame projection. This scale is not screenshot zoom. */
+export function snapshotViewportRect(
+  bounds: number[],
+  owner: CoordinateOwner,
+  coordinates: SnapshotCoordinates | null,
+): FrameViewportRect | null {
+  if (!coordinates || bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
+  const { layoutUnitsPerCssPixel: scale, scrollCss: scroll } = coordinates;
+  const [x, y, width, height] = bounds;
+  if (
+    !Number.isFinite(scale) ||
+    scale <= 0 ||
+    width <= 0 ||
+    height <= 0 ||
+    !Number.isFinite(scroll.x) ||
+    !Number.isFinite(scroll.y)
+  ) {
+    return null;
+  }
+  return {
+    space: "frame-viewport-css",
+    owner,
+    rect: {
+      x: x / scale - scroll.x,
+      y: y / scale - scroll.y,
+      width: width / scale,
+      height: height / scale,
+    },
+  };
+}
+
+export function projectSnapshotRect(
+  input: FrameViewportRect,
+  projection: SnapshotProjection,
+): ViewportRect | null {
+  if (
+    input.owner.frameId !== projection.source.frameId ||
+    cdpTargetKey(input.owner.target) !== cdpTargetKey(projection.source.target)
+  ) {
+    return null;
+  }
+  const { x, y, width: w, height: h } = input.rect;
+  return projectRectToViewport({ x, y, w, h }, projection.geometry);
+}
+
+/** CSS viewport metadata; browser zoom is distinct from raster devicePixelRatio. */
+export interface CssViewport {
+  width: number;
+  height: number;
+  scrollX: number;
+  scrollY: number;
+  cssToDip: number;
+}
+
+/** Page.captureScreenshot takes page-relative DIP, not viewport-relative CSS pixels. */
+export function screenshotPageRect(
+  rect: ViewportRect,
+  viewport: CssViewport,
+): { space: "page-dip"; rect: ViewportRect } | null {
+  const { cssToDip, scrollX, scrollY } = viewport;
+  if (
+    ![rect.x, rect.y, rect.width, rect.height, cssToDip, scrollX, scrollY].every(Number.isFinite) ||
+    cssToDip <= 0 ||
+    rect.width <= 0 ||
+    rect.height <= 0
+  )
+    return null;
+  return {
+    space: "page-dip",
+    rect: {
+      x: (rect.x + scrollX) * cssToDip,
+      y: (rect.y + scrollY) * cssToDip,
+      width: rect.width * cssToDip,
+      height: rect.height * cssToDip,
+    },
+  };
+}

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

@@ -0,0 +1,400 @@
+import {
+  type CdpFrame,
+  type CdpFrameGraph,
+  type CdpTarget,
+  cdpTargetKey,
+} from "@/browser-driver/frame-graph";
+import {
+  type GeometryProjection,
+  type Polygon,
+  type ProjectiveEdge,
+  parseCdpQuad,
+  projectPolygon,
+  type Quad,
+  type Size,
+  viewportPolygon,
+} from "../geometry";
+import { type CdpRunner, sendToCdpTarget } from "../shared";
+import type { CoordinateOwner, CssViewport, SnapshotProjectionResult } from "./coordinate-types";
+
+import { readSnapshotOwnerSizes } from "./snapshot-owner-sizes";
+
+export interface LayoutMetrics {
+  cssVisualViewport?: {
+    zoom?: number;
+    scale?: number;
+    clientWidth?: number;
+    clientHeight?: number;
+  };
+  visualViewport?: { zoom?: number; scale?: number; clientWidth?: number; clientHeight?: number };
+  cssLayoutViewport?: {
+    clientWidth?: number;
+    clientHeight?: number;
+    pageX?: number;
+    pageY?: number;
+  };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
+}
+
+/** Chromium emits these paired floating-point dimensions before/after dividing
+ * by LayoutZoomFactor. Integer layout viewport dimensions lose precision at
+ * fractional zoom. Neither visualViewport.scale nor .zoom is this conversion.
+ * See InspectorPageAgent::getLayoutMetrics in Chromium. */
+export function snapshotLayoutScale(metrics: LayoutMetrics): number | null {
+  for (const dimension of ["clientWidth", "clientHeight"] as const) {
+    const raw = metrics.visualViewport?.[dimension];
+    const css = metrics.cssVisualViewport?.[dimension];
+    if (
+      raw !== undefined &&
+      css !== undefined &&
+      Number.isFinite(raw) &&
+      Number.isFinite(css) &&
+      raw > 0 &&
+      css > 0
+    ) {
+      const scale = raw / css;
+      if (Number.isFinite(scale) && scale > 0) return scale;
+    }
+  }
+  return null;
+}
+
+/** The legacy field is a compatibility fallback, never a source of raster DPR. */
+export function cssViewport(metrics: LayoutMetrics): CssViewport {
+  const value = metrics.cssLayoutViewport ?? metrics.layoutViewport;
+  return {
+    width: value?.clientWidth ?? 0,
+    height: value?.clientHeight ?? 0,
+    scrollX: value?.pageX ?? 0,
+    scrollY: value?.pageY ?? 0,
+    cssToDip: metrics.cssVisualViewport?.zoom ?? metrics.visualViewport?.zoom ?? 1,
+  };
+}
+
+/** One read-only measurement phase. Discard after scrolling or any later operation. */
+export class GeometryContext {
+  private readonly metrics = new Map<string, Promise<LayoutMetrics>>();
+  private readonly frameViewports = new Map<string, Promise<Size | null>>();
+  private readonly owners = new Map<string, Promise<Quad | null>>();
+  private readonly projections = new Map<string, Promise<GeometryProjection | null>>();
+  private readonly snapshotOwners = new Map<string, Promise<{ quad: Quad; size: Size } | null>>();
+  private readonly sizeBatches = new Map<string, () => Promise<Map<number, Size>>>();
+  private active = 0;
+  private readonly waiting: Array<() => void> = [];
+  private graphPromise?: Promise<CdpFrameGraph | null>;
+  private framesPromise?: Promise<Map<string, CdpFrame>>;
+
+  constructor(
+    private readonly cdp: CdpRunner,
+    private readonly tabId: number,
+    graph?: CdpFrameGraph,
+    private readonly signal?: AbortSignal,
+  ) {
+    if (graph) this.graphPromise = Promise.resolve(graph);
+  }
+
+  private async request<T>(
+    target: CdpTarget,
+    method: string,
+    params: object,
+    cleanup = false,
+  ): Promise<T> {
+    if (!cleanup && this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
+    if (this.active >= 4) await new Promise<void>((resolve) => this.waiting.push(resolve));
+    else this.active++;
+    try {
+      if (!cleanup && this.signal?.aborted)
+        throw new DOMException("geometry aborted", "AbortError");
+      return await sendToCdpTarget<T>(this.cdp, target, method, params);
+    } finally {
+      const next = this.waiting.shift();
+      if (next) next();
+      else this.active--;
+    }
+  }
+
+  graph(): Promise<CdpFrameGraph | null> {
+    this.graphPromise ??=
+      this.cdp.getFrameGraph?.(this.tabId).catch(() => null) ?? Promise.resolve(null);
+    return this.graphPromise;
+  }
+
+  private frames(): Promise<Map<string, CdpFrame>> {
+    this.framesPromise ??= this.graph().then(
+      (graph) => new Map(graph?.frames.map((frame) => [frame.frameId, frame]) ?? []),
+    );
+    return this.framesPromise;
+  }
+
+  async frame(frameId: string): Promise<CdpFrame | undefined> {
+    return (await this.frames()).get(frameId);
+  }
+
+  /** Topology only: safe to resolve before the caller scrolls frame owners. */
+  async ancestry(frameId: string): Promise<CdpFrame[] | null> {
+    const frames = await this.frames();
+    const path: CdpFrame[] = [];
+    const seen = new Set<string>();
+    let current = frames.get(frameId);
+    if (!current) return null;
+    while (current.parentFrameId) {
+      if (seen.has(current.frameId)) return null;
+      seen.add(current.frameId);
+      path.push(current);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent) return null;
+      current = parent;
+    }
+    return path;
+  }
+
+  layoutMetrics(target: CdpTarget): Promise<LayoutMetrics> {
+    const key = cdpTargetKey(target);
+    let promise = this.metrics.get(key);
+    if (!promise) {
+      promise = this.request<LayoutMetrics>(target, "Page.getLayoutMetrics", {});
+      this.metrics.set(key, promise);
+    }
+    return promise;
+  }
+
+  async viewport(target: CdpTarget): Promise<Size | null> {
+    const { width, height } = cssViewport(await this.layoutMetrics(target));
+    return Number.isFinite(width) && Number.isFinite(height) && width > 0 && height > 0
+      ? { width, height }
+      : null;
+  }
+
+  /** The full OOPIF viewport maps to its owner's content quad. Layout metrics
+   * exclude occupied scrollbars and remain the clipping boundary, not the scale. */
+  private frameViewport(target: CdpTarget): Promise<Size | null> {
+    const key = cdpTargetKey(target);
+    let promise = this.frameViewports.get(key);
+    if (!promise) {
+      promise = this.request<{ result?: { value?: Size }; exceptionDetails?: unknown }>(
+        target,
+        "Runtime.evaluate",
+        {
+          expression: "({ width: window.innerWidth, height: window.innerHeight })",
+          returnByValue: true,
+        },
+      ).then(({ result, exceptionDetails }) => {
+        const size = result?.value;
+        return !exceptionDetails &&
+          size &&
+          Number.isFinite(size.width) &&
+          Number.isFinite(size.height) &&
+          size.width > 0 &&
+          size.height > 0
+          ? size
+          : null;
+      });
+      this.frameViewports.set(key, promise);
+    }
+    return promise;
+  }
+
+  ownerContent(target: CdpTarget, backendNodeId: number): Promise<Quad | null> {
+    const key = `${cdpTargetKey(target)}:${backendNodeId}`;
+    let promise = this.owners.get(key);
+    if (!promise) {
+      promise = this.request<{ model?: { content?: number[] } }>(target, "DOM.getBoxModel", {
+        backendNodeId,
+      }).then((reply) => parseCdpQuad(reply.model?.content));
+      this.owners.set(key, promise);
+    }
+    return promise;
+  }
+
+  /** Same-target owner quads are already target-relative, including nested owners. */
+  async snapshotProjection(
+    source: CoordinateOwner,
+    ownerBackendNodeId: number,
+    ancestorClips: Polygon[],
+    viewport: Size,
+  ): Promise<SnapshotProjectionResult> {
+    const key = `${cdpTargetKey(source.target)}:${ownerBackendNodeId}`;
+    let promise = this.snapshotOwners.get(key);
+    if (!promise) {
+      promise = this.snapshotOwner(source.target, ownerBackendNodeId);
+      this.snapshotOwners.set(key, promise);
+    }
+    let owner: { quad: Quad; size: Size } | null;
+    try {
+      owner = await promise;
+    } catch (error) {
+      if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
+        throw error;
+      console.debug("[bsk geometry] frame owner unavailable", error);
+      owner = null;
+    }
+    return owner
+      ? {
+          status: "available",
+          projection: {
+            source,
+            geometry: {
+              sourceClips: [],
+              edges: [
+                {
+                  sourceViewport: owner.size,
+                  destinationQuad: owner.quad,
+                  destinationClips: ancestorClips,
+                },
+              ],
+              topViewport: viewport,
+            },
+          },
+        }
+      : { status: "unavailable", source, ownerBackendNodeId };
+  }
+
+  /** Register one target's snapshot owners; the batch starts only when a
+   * projection actually needs a size. Single owners keep the cheaper old path. */
+  registerSnapshotOwners(target: CdpTarget, owners: ReadonlySet<number>): void {
+    const key = cdpTargetKey(target);
+    if (owners.size < 2 || this.sizeBatches.has(key)) return;
+    let pending: Promise<Map<number, Size>> | undefined;
+    this.sizeBatches.set(key, () => {
+      pending ??= readSnapshotOwnerSizes(
+        (method, params, cleanup) => this.request(target, method, params, cleanup),
+        owners,
+      ).catch((error) => {
+        if (error && typeof error === "object" && "name" in error && error.name === "AbortError")
+          throw error;
+        return new Map<number, Size>();
+      });
+      return pending;
+    });
+  }
+
+  private async snapshotOwner(
+    target: CdpTarget,
+    backendNodeId: number,
+  ): Promise<{ quad: Quad; size: Size } | null> {
+    const quad = await this.ownerContent(target, backendNodeId);
+    if (!quad) return null;
+    const batchSize = (await this.sizeBatches.get(cdpTargetKey(target))?.())?.get(backendNodeId);
+    if (this.signal?.aborted) throw new DOMException("geometry aborted", "AbortError");
+    if (batchSize) return { quad, size: batchSize };
+    const resolved = await this.request<{ object?: { objectId?: string } }>(
+      target,
+      "DOM.resolveNode",
+      { backendNodeId },
+    );
+    const objectId = resolved.object?.objectId;
+    if (!objectId) return null;
+    try {
+      const reply = await this.request<{ result?: { value?: Size }; exceptionDetails?: unknown }>(
+        target,
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: `function() {
+          if (!this.isConnected) return null;
+          const style = getComputedStyle(this);
+          return {
+            width: this.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
+            height: this.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+          };
+        }`,
+          returnByValue: true,
+        },
+      );
+      const size = reply.result?.value;
+      return !reply.exceptionDetails &&
+        size &&
+        Number.isFinite(size.width) &&
+        Number.isFinite(size.height) &&
+        size.width > 0 &&
+        size.height > 0
+        ? { quad, size }
+        : null;
+    } finally {
+      // Cleanup must still run if cancellation arrived after resolving the object.
+      await this.request(target, "Runtime.releaseObject", { objectId }, true).catch(() => {});
+    }
+  }
+
+  private targetRoot(frames: Map<string, CdpFrame>, frame: CdpFrame): CdpFrame | null {
+    const seen = new Set<string>();
+    let current = frame;
+    while (current.parentFrameId) {
+      if (seen.has(current.frameId)) return null;
+      seen.add(current.frameId);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent) return null;
+      if (cdpTargetKey(parent.target) !== cdpTargetKey(current.target)) break;
+      current = parent;
+    }
+    return current;
+  }
+
+  private async clips(
+    frames: Map<string, CdpFrame>,
+    frame: CdpFrame,
+    root: CdpFrame,
+  ): Promise<Polygon[] | null> {
+    const clips: Polygon[] = [];
+    let current = frame;
+    const seen = new Set<string>();
+    while (current.frameId !== root.frameId) {
+      if (seen.has(current.frameId) || !current.parentFrameId) return null;
+      seen.add(current.frameId);
+      const parent = frames.get(current.parentFrameId);
+      if (!parent || current.ownerBackendNodeId === undefined) return null;
+      const quad = await this.ownerContent(parent.target, current.ownerBackendNodeId);
+      if (!quad) return null;
+      clips.push(quad);
+      current = parent;
+    }
+    return clips;
+  }
+
+  /** Input is already in the frame's CDP target viewport, not its local viewport. */
+  targetProjection(frameId: string): Promise<GeometryProjection | null> {
+    let promise = this.projections.get(frameId);
+    if (!promise) {
+      promise = this.buildTargetProjection(frameId);
+      this.projections.set(frameId, promise);
+    }
+    return promise;
+  }
+
+  private async buildTargetProjection(frameId: string): Promise<GeometryProjection | null> {
+    const frames = await this.frames();
+    const frame = frames.get(frameId);
+    if (!frame) return null;
+    let root = this.targetRoot(frames, frame);
+    if (!root) return null;
+    const sourceViewport = await this.viewport(root.target);
+    if (!sourceViewport) return null;
+    const sourceClips = await this.clips(frames, frame, root);
+    if (!sourceClips) return null;
+    const edges: ProjectiveEdge[] = [];
+    const seen = new Set<string>();
+    while (root.parentFrameId) {
+      if (seen.has(root.frameId)) return null;
+      seen.add(root.frameId);
+      const parent = frames.get(root.parentFrameId);
+      if (!parent || root.ownerBackendNodeId === undefined) return null;
+      const destinationQuad = await this.ownerContent(parent.target, root.ownerBackendNodeId);
+      if (!destinationQuad) return null;
+      const source = await this.frameViewport(root.target);
+      const visible = await this.viewport(root.target);
+      const parentRoot = this.targetRoot(frames, parent);
+      if (!source || !visible || !parentRoot) return null;
+      const destinationClips = await this.clips(frames, parent, parentRoot);
+      if (!destinationClips) return null;
+      const edge = { sourceViewport: source, destinationQuad, destinationClips };
+      // Keep scrollbar strips clipped at every target boundary, including
+      // intermediate OOPIFs. Project the clip with the same full-viewport scale.
+      if (source.width !== visible.width || source.height !== visible.height)
+        destinationClips.push(projectPolygon(viewportPolygon(visible), edge));
+      edges.push(edge);
+      root = parentRoot;
+    }
+    const topViewport = await this.viewport(root.target);
+    return topViewport ? { sourceClips, edges, topViewport } : null;
+  }
+}

apps/extension/src/tools/geometry/snapshot-owner-sizes.ts

@@ -0,0 +1,74 @@
+import type { Size } from "../geometry";
+
+interface SerializedValue {
+  type: string;
+  value?: unknown;
+}
+
+type Send = <T>(method: string, params: object, cleanup?: boolean) => Promise<T>;
+
+/** Batch only accessible frame owners. Missing/shadow/cross-origin owners keep
+ * the existing node-scoped read; no page-wide style columns are requested. */
+export async function readSnapshotOwnerSizes(
+  send: Send,
+  owners: ReadonlySet<number>,
+): Promise<Map<number, Size>> {
+  const sizes = new Map<number, Size>();
+  const objectGroup = `bsk-frame-sizes-${crypto.randomUUID()}`;
+  try {
+    const reply = await send<{ result?: { deepSerializedValue?: SerializedValue } }>(
+      "Runtime.evaluate",
+      {
+        expression: `(() => {
+          const result = [];
+          const documents = [document];
+          for (let i = 0; i < documents.length && result.length < ${owners.size}; i++) {
+            for (const owner of documents[i].querySelectorAll('iframe,frame')) {
+              if (result.length >= ${owners.size}) break;
+              if (!owner.isConnected) continue;
+              const style = getComputedStyle(owner);
+              result.push([owner, JSON.stringify({
+                width: owner.clientWidth - parseFloat(style.paddingLeft) - parseFloat(style.paddingRight),
+                height: owner.clientHeight - parseFloat(style.paddingTop) - parseFloat(style.paddingBottom)
+              })]);
+              try { if (owner.contentDocument) documents.push(owner.contentDocument); } catch {}
+            }
+          }
+          return result;
+        })()`,
+        objectGroup,
+        serializationOptions: {
+          serialization: "deep",
+          maxDepth: 3,
+          additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+        },
+      },
+    );
+    const result = reply.result?.deepSerializedValue;
+    if (result?.type !== "array" || !Array.isArray(result.value)) return sizes;
+    for (const entry of result.value as SerializedValue[]) {
+      if (entry.type !== "array" || !Array.isArray(entry.value)) continue;
+      const [node, data] = entry.value as SerializedValue[];
+      if (node?.type !== "node" || data?.type !== "string" || typeof data.value !== "string")
+        continue;
+      const id = (node.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+      if (id === undefined || !owners.has(id)) continue;
+      try {
+        const size = JSON.parse(data.value) as Size;
+        if (
+          size &&
+          Number.isFinite(size.width) &&
+          Number.isFinite(size.height) &&
+          size.width > 0 &&
+          size.height > 0
+        )
+          sizes.set(id, size);
+      } catch {
+        /* An invalid entry uses the existing individual read. */
+      }
+    }
+  } finally {
+    await send("Runtime.releaseObjectGroup", { objectGroup }, true).catch(() => {});
+  }
+  return sizes;
+}

apps/extension/src/tools/interaction.ts

@@ -1,5 +1,4 @@
-// DOM interaction tools — `tool.click`, `tool.fill`, `tool.press`, and
-// `tool.select`.
+// DOM interaction tools — click, hover, focus/blur, fill, press, and select.
 //
 // All interaction tools:
 // 1. Resolve target tab (sandbox: must be inside Agent Window).
@@ -14,10 +13,14 @@ import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import type { SessionContext, SessionManager } from "@/session-manager/manager";
 import type {
+  BlurParams,
+  BlurResult,
   ClickParams,
   ClickResult,
   FillParams,
   FillResult,
+  FocusParams,
+  FocusResult,
   HoverParams,
   HoverResult,
   KeyModifier,
@@ -183,6 +186,8 @@ export async function resolveBackendNode(
   }
   // selector path
   try {
+    // Selector lookup itself attaches CDP, even when no element is found.
+    cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
     const doc = await cdp.send<{ root?: { nodeId?: number } }>(target.tabId, "DOM.getDocument", {
       depth: 0,
     });
@@ -225,6 +230,207 @@ export async function resolveBackendNode(
   }
 }
 
+// Check the target's own root, then its hosts: closed shadow roots are not
+// reachable via host.shadowRoot. DOM focus remains meaningful in background tabs.
+const FOCUS_CHECK = `function() {
+  if (!this.isConnected) return false;
+  let element = this;
+  while (element) {
+    const root = element.getRootNode();
+    if (root.activeElement !== element) return false;
+    element = root.host;
+  }
+  return true;
+}`;
+
+const BLUR_TARGET = `function() {
+  if (!this.isConnected) throw new Error('blur target is detached');
+  const wasFocused = (${FOCUS_CHECK}).call(this);
+  if (typeof this.blur !== 'function') return { ok: false, was_focused: wasFocused };
+  this.blur();
+  return { ok: true, was_focused: wasFocused };
+}`;
+
+interface FocusScriptReply<T> {
+  result?: { value?: T };
+  exceptionDetails?: { text?: string; exception?: { description?: string } };
+}
+
+function checkFocusAbort(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw new DOMException("interaction aborted", "AbortError");
+}
+
+// Only focus/blur use this view. Guard every CDP boundary, including commands
+// inside selector resolution and frame scrolling, without changing other tools.
+function focusCdp(cdp: CdpRunner, signal: AbortSignal | undefined): CdpRunner {
+  const send = <T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T> => {
+    checkFocusAbort(signal);
+    return cdpRunnerForTarget(cdp, target).send<T>(target.tabId, method, params);
+  };
+  return {
+    send: (tabId, method, params) => send({ tabId }, method, params),
+    sendToTarget: send,
+    trackSessionTab: cdp.trackSessionTab?.bind(cdp),
+    getFrameGraph: cdp.getFrameGraph
+      ? (tabId) => {
+          checkFocusAbort(signal);
+          return cdp.getFrameGraph!(tabId);
+        }
+      : undefined,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// tool.focus / tool.blur
+// ---------------------------------------------------------------------------
+
+export function handleFocus(
+  manager: SessionManager,
+  params: FocusParams,
+  deps: InteractionDeps = getDefaultDeps(),
+): Promise<FocusResult | RpcError> {
+  return changeFocus(manager, params, deps, "focus");
+}
+
+export function handleBlur(
+  manager: SessionManager,
+  params: BlurParams,
+  deps: InteractionDeps = getDefaultDeps(),
+): Promise<BlurResult | RpcError> {
+  return changeFocus(manager, params, deps, "blur");
+}
+
+function changeFocus(
+  manager: SessionManager,
+  params: FocusParams,
+  deps: InteractionDeps,
+  action: "focus",
+): Promise<FocusResult | RpcError>;
+function changeFocus(
+  manager: SessionManager,
+  params: BlurParams,
+  deps: InteractionDeps,
+  action: "blur",
+): Promise<BlurResult | RpcError>;
+async function changeFocus(
+  manager: SessionManager,
+  params: FocusParams | BlurParams,
+  deps: InteractionDeps,
+  action: "focus" | "blur",
+): Promise<FocusResult | BlurResult | RpcError> {
+  const ctx = lookupSession(manager, params, action);
+  if (isRpcError(ctx)) return ctx;
+  const cdp = focusCdp(deps.cdp, deps.signal);
+  let objectId: string | undefined;
+  let cleanupCdp: CdpRunner | undefined;
+  let tabId: number | undefined;
+  try {
+    checkFocusAbort(deps.signal);
+    const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+    checkFocusAbort(deps.signal);
+    if (isRpcError(target)) return target;
+    const denied = enforceAgentWindow(ctx, target, action);
+    if (denied) return denied;
+    tabId = target.tabId;
+    const dialogCursor = markDialogCursor(deps.cdp, tabId);
+    const node = await resolveBackendNode(cdp, ctx, target, params, action);
+    checkFocusAbort(deps.signal);
+    if (isRpcError(node)) return node;
+    const nodeCdp = cdpRunnerForTarget(cdp, node.cdpTarget);
+    cleanupCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
+    deps.cdp.trackSessionTab?.(ctx.sessionId, tabId);
+
+    if (action === "focus") {
+      const scrollErr = await scrollElementAndFramesIntoView(
+        cdp,
+        tabId,
+        node.cdpTarget,
+        node.backendNodeId,
+        node.frameId,
+      );
+      checkFocusAbort(deps.signal);
+      if (scrollErr) return scrollErr;
+    }
+    const resolved = await backendNodeToObject(nodeCdp, tabId, node.backendNodeId);
+    // Keep the handle before checking cancellation so finally can release it.
+    if (!isRpcError(resolved)) objectId = resolved;
+    checkFocusAbort(deps.signal);
+    if (isRpcError(resolved)) return resolved;
+
+    const runScript = async <T>(functionDeclaration: string): Promise<T | undefined> => {
+      const reply = await nodeCdp.send<FocusScriptReply<T>>(
+        target.tabId,
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration,
+          returnByValue: true,
+        },
+      );
+      checkFocusAbort(deps.signal);
+      if (reply.exceptionDetails) {
+        const details = reply.exceptionDetails;
+        throw new Error(
+          `${action} script failed: ${details.exception?.description ?? details.text ?? "unknown exception"}`,
+        );
+      }
+      return reply.result?.value;
+    };
+
+    let wasFocused: boolean | undefined;
+    if (action === "focus") {
+      await nodeCdp.send(tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
+      checkFocusAbort(deps.signal);
+    } else {
+      const mutation = await runScript<{ ok: boolean; was_focused: boolean }>(BLUR_TARGET);
+      if (typeof mutation?.ok !== "boolean" || typeof mutation.was_focused !== "boolean") {
+        throw new Error("blur script returned an unexpected result");
+      }
+      if (!mutation.ok) {
+        return { code: "invalid_params", message: "target element does not support blur()" };
+      }
+      wasFocused = mutation.was_focused;
+    }
+    // Use a separate call so microtasks from focus/blur handlers finish before
+    // we report success. In particular, a blur handler can restore focus.
+    const focused = await runScript<boolean>(FOCUS_CHECK);
+    if (typeof focused !== "boolean") {
+      throw new Error(`${action} verification returned an unexpected result`);
+    }
+    if (focused !== (action === "focus")) {
+      throw new Error(
+        action === "focus"
+          ? "target element did not become focused"
+          : "target element remained focused after blur()",
+      );
+    }
+    return attachDialogs(deps.cdp, tabId, dialogCursor, {
+      tab_id: tabId,
+      used_ref: node.usedRef,
+      used_selector: node.usedSelector,
+      focused,
+      ...(action === "blur" ? { was_focused: wasFocused! } : {}),
+    });
+  } catch (err) {
+    return (
+      throwIfAborted(deps.signal) ?? {
+        code: "cdp_failed",
+        message: err instanceof Error ? err.message : String(err),
+      }
+    );
+  } finally {
+    if (objectId !== undefined && cleanupCdp && tabId !== undefined) {
+      // Cleanup must also run after cancellation. Navigation may have already
+      // disposed the object, which must not replace the operation's result.
+      try {
+        await cleanupCdp.send(tabId, "Runtime.releaseObject", { objectId });
+      } catch {
+        // The target or execution context may no longer exist.
+      }
+    }
+  }
+}
+
 export async function resolveActionTarget(
   cdp: CdpRunner,
   ctx: SessionContext,
@@ -607,6 +813,53 @@ type SelectMutationResult =
 // tool.fill
 // ---------------------------------------------------------------------------
 
+type FillFailureReason =
+  | "target_not_fillable"
+  | "fill_value_invalid"
+  | "fill_target_changed"
+  | "fill_focus_lost"
+  | "fill_value_mismatch"
+  | "fill_failed";
+
+type FillPreparation =
+  | { before: string; expected: string }
+  | { reason: FillFailureReason; error: string };
+
+type FillReadiness = "ready" | "background" | "fill_target_changed" | "fill_focus_lost";
+
+function fillError(reason: FillFailureReason, message: string): RpcError {
+  return rpcError(
+    reason === "target_not_fillable" || reason === "fill_value_invalid"
+      ? "invalid_params"
+      : "cdp_failed",
+    reason,
+    message,
+  );
+}
+
+interface FillScriptReply<T> {
+  result?: { value?: T };
+  exceptionDetails?: unknown;
+}
+
+const FILL_EDITABLE_FUNCTION = `function() {
+  const tag = this.tagName.toLowerCase();
+  const supported = tag === 'input'
+    ? ['text', 'search', 'tel', 'url', 'email', 'password', 'number'].includes(this.type)
+    : tag === 'textarea' || this.isContentEditable;
+  return this.isConnected && supported && !this.readOnly && !this.matches(':disabled');
+}`;
+
+// Chrome renders a trailing editable newline with an empty <div><br></div>.
+// innerText includes the padding break; it is not an extra typed character.
+const FILL_VALUE_FUNCTION = `function() {
+  if (!this.isContentEditable) return this.value;
+  const value = this.innerText;
+  const tail = this.lastChild;
+  const padding = tail && tail.nodeName === 'DIV' && tail.childNodes.length === 1 && tail.firstChild.nodeName === 'BR';
+  return padding && value.endsWith('\\n\\n') ? value.slice(0, -1) : value;
+}`;
+
 export async function handleFill(
   manager: SessionManager,
   params: FillParams,
@@ -658,12 +911,8 @@ export async function handleFill(
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
-    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
   }
 
   if (throwIfAborted(deps.signal)) {
@@ -676,57 +925,252 @@ export async function handleFill(
   const clearBefore = params.clear_before ?? true;
 
   try {
-    if (clearBefore) {
-      // Clear input/textarea value or wipe contenteditable innerText,
-      // then fire `input` so frameworks observe the empty state.
-      await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
-        objectId,
-        functionDeclaration: `function() {
-          if (this.isContentEditable) { this.textContent = ''; }
-          else {
-            const proto = this instanceof HTMLTextAreaElement
-              ? HTMLTextAreaElement.prototype
-              : HTMLInputElement.prototype;
-            const descriptor = Object.getOwnPropertyDescriptor(proto, 'value');
-            if (descriptor && descriptor.set) descriptor.set.call(this, '');
-            else this.value = '';
-          }
-          this.dispatchEvent(new Event('input', { bubbles: true }));
-        }`,
-        returnByValue: true,
-      });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    try {
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
+    } catch (error) {
+      // Chrome rejects DOM.focus for disabled controls, including inherited
+      // fieldset state. Classify the live target before treating this as a
+      // browser failure; the normal path needs no extra round trip.
+      const editable = await nodeCdp.send<FillScriptReply<boolean>>(
+        target.tabId,
+        "Runtime.callFunctionOn",
+        { objectId, functionDeclaration: FILL_EDITABLE_FUNCTION, returnByValue: true },
+      );
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      if (!editable.exceptionDetails && editable.result?.value === false) {
+        return fillError(
+          "target_not_fillable",
+          "fill target is not editable or its input type is unsupported",
+        );
+      }
+      throw error;
     }
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
+    // Check editability before clearing. Keep the expected result tied to
+    // this object, including the existing value on the append path.
+    const prepared = await nodeCdp.send<FillScriptReply<FillPreparation>>(
+      target.tabId,
+      "Runtime.callFunctionOn",
+      {
+        objectId,
+        functionDeclaration: `function(value, clearBefore) {
+          const tag = this.tagName.toLowerCase();
+          const native = tag === 'input' || tag === 'textarea';
+          if (!(${FILL_EDITABLE_FUNCTION}).call(this)) return { reason: 'target_not_fillable', error: 'fill target is not editable or its input type is unsupported' };
+          if (this.getRootNode().activeElement !== this) return { reason: 'fill_focus_lost', error: 'fill target does not have focus' };
+          const before = clearBefore ? '' : (${FILL_VALUE_FUNCTION}).call(this);
+          let expected = before + value;
+          if (native) {
+            // Use the browser's own value sanitization (e.g. textarea
+            // line endings) without changing the live control.
+            const normalizer = this.ownerDocument.createElement(tag);
+            if (tag === 'input') {
+              normalizer.type = this.type;
+              normalizer.multiple = this.multiple;
+            }
+            // insertText treats line breaks in a single-line input as spaces.
+            if (tag === 'input') expected = expected.replace(/\\r\\n|\\r|\\n/g, ' ');
+            normalizer.value = expected;
+            if (expected !== '' && normalizer.value === '' && this.type === 'number') {
+              return { reason: 'fill_value_invalid', error: 'fill value is not valid for a number input' };
+            }
+            expected = normalizer.value;
+            if (this.type !== 'number' && this.maxLength >= 0 && expected.length > this.maxLength) {
+              return { reason: 'fill_value_invalid', error: 'fill value exceeds the target maxlength' };
+            }
+          } else {
+            expected = expected.replace(/\\r\\n?/g, '\\n');
+          }
+          if (clearBefore) {
+            if (native) {
+              const proto = tag === 'textarea' ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+              Object.getOwnPropertyDescriptor(proto, 'value').set.call(this, '');
+            } else {
+              this.textContent = '';
+            }
+            this.dispatchEvent(new Event('input', { bubbles: true }));
+          }
+          return { before, expected };
+        }`,
+        arguments: [{ value: params.value }, { value: clearBefore }],
+        returnByValue: true,
+      },
+    );
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (prepared.exceptionDetails) {
+      return fillError("fill_failed", "fill preparation script failed");
+    }
+    const preparation = prepared.result?.value;
+    if (preparation && "error" in preparation) {
+      return fillError(preparation.reason, preparation.error);
+    }
+    if (typeof preparation?.before !== "string" || typeof preparation?.expected !== "string") {
+      return fillError("fill_failed", "fill preparation returned an unexpected result");
+    }
+    // A separate call runs after the clearing event's microtasks drain.
+    // DOM focus works in background tabs. Use document.hasFocus() only to
+    // detect deferred focus events, never to reject background input.
+    const checkReady = async (): Promise<FillReadiness | RpcError> => {
+      const reply = await nodeCdp.send<FillScriptReply<FillReadiness>>(
+        target.tabId,
+        "Runtime.callFunctionOn",
+        {
+          objectId,
+          functionDeclaration: `function(before) {
+            if (!(${FILL_EDITABLE_FUNCTION}).call(this) ||
+                (${FILL_VALUE_FUNCTION}).call(this) !== before) return 'fill_target_changed';
+            if (this.getRootNode().activeElement !== this) return 'fill_focus_lost';
+            return this.ownerDocument.hasFocus() ? 'ready' : 'background';
+          }`,
+          arguments: [{ value: preparation.before }],
+          returnByValue: true,
+        },
+      );
+      const state = reply.result?.value;
+      if (
+        reply.exceptionDetails ||
+        (state !== "ready" &&
+          state !== "background" &&
+          state !== "fill_target_changed" &&
+          state !== "fill_focus_lost")
+      ) {
+        return fillError(
+          "fill_failed",
+          "fill readiness script failed or returned an unexpected result",
+        );
+      }
+      return state;
+    };
+    let ready = await checkReady();
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    // Restore focus once only if clearing left this same target editable
+    // and unchanged. Recheck after focus handlers have run.
+    if (clearBefore && ready === "fill_focus_lost") {
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      ready = await checkReady();
+    }
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (typeof ready !== "string") return ready;
+    if (ready !== "ready" && ready !== "background") {
+      return fillError(ready, "fill target changed or lost focus before typing");
+    }
+    if (params.value !== "" && (!clearBefore || ready === "background")) {
+      // Native editing commands also support number/email inputs, whose
+      // selection APIs cannot set a caret, and multiline contenteditables.
+      // Also do this for background replacement: CDP input focuses the
+      // renderer, delivering deferred focus events before it inserts text.
+      // Use a command-only event so this does not invoke an End shortcut.
+      try {
+        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", {
+          type: "rawKeyDown",
+          commands: ["moveToEndOfDocument"],
+        });
+      } finally {
+        await deps.cdp.send(target.tabId, "Input.dispatchKeyEvent", { type: "keyUp" });
+      }
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      // Focus and key handlers can change the target or move focus too.
+      ready = await checkReady();
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      if (typeof ready !== "string") return ready;
+      if (ready !== "ready" && ready !== "background") {
+        return fillError(ready, "fill target changed or lost focus while positioning the caret");
+      }
+    }
     // CDP `Input.insertText` handles IME / multi-byte input out of the
     // box, much more reliably than per-key `dispatchKeyEvent`.
-    await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    if (params.value !== "") {
+      await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    }
     if (throwIfAborted(deps.signal)) {
       return { code: "cancelled", message: "fill aborted" };
     }
-    // Fire `input` + `change` so React / Vue controlled inputs commit.
-    await nodeCdp.send(target.tabId, "Runtime.callFunctionOn", {
+    // Keep the existing notifications, then read in a separate call so
+    // nested microtasks queued by the page cannot race the verification.
+    const notified = await nodeCdp.send<FillScriptReply<unknown>>(
+      target.tabId,
+      "Runtime.callFunctionOn",
+      {
+        objectId,
+        functionDeclaration: `function() {
+          this.dispatchEvent(new Event('input', { bubbles: true }));
+          this.dispatchEvent(new Event('change', { bubbles: true }));
+        }`,
+        returnByValue: true,
+      },
+    );
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    if (notified.exceptionDetails) {
+      return fillError("fill_failed", "fill notification script failed");
+    }
+    const verified = await nodeCdp.send<
+      FillScriptReply<{ connected: boolean; matches: boolean; valueLength: number }>
+    >(target.tabId, "Runtime.callFunctionOn", {
       objectId,
-      functionDeclaration: `function() {
-        this.dispatchEvent(new Event('input', { bubbles: true }));
-        this.dispatchEvent(new Event('change', { bubbles: true }));
-      }`,
+      functionDeclaration: `function(expected) {
+          const value = (${FILL_VALUE_FUNCTION}).call(this);
+          return { connected: this.isConnected, matches: value === expected, valueLength: value.length };
+        }`,
+      arguments: [{ value: preparation.expected }],
       returnByValue: true,
     });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    const verification = verified.result?.value;
+    if (
+      verified.exceptionDetails ||
+      typeof verification?.connected !== "boolean" ||
+      typeof verification?.matches !== "boolean" ||
+      typeof verification?.valueLength !== "number"
+    ) {
+      return fillError(
+        "fill_failed",
+        "fill verification script failed or returned an unexpected result",
+      );
+    }
+    if (!verification.connected) {
+      return fillError("fill_target_changed", "fill target was removed or replaced during input");
+    }
+    if (!verification.matches) {
+      return fillError(
+        "fill_value_mismatch",
+        "fill could not verify the expected value; observe the page before deciding whether to retry",
+      );
+    }
+    return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+      tab_id: target.tabId,
+      used_ref: node.usedRef,
+      used_selector: node.usedSelector,
+      value_length: verification.valueLength,
+    });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return fillError("fill_failed", err instanceof Error ? err.message : String(err));
+  } finally {
+    await nodeCdp.send(target.tabId, "Runtime.releaseObject", { objectId }).catch(() => undefined);
   }
-
-  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-    tab_id: target.tabId,
-    used_ref: node.usedRef,
-    used_selector: node.usedSelector,
-    value_length: params.value.length,
-  });
 }
 
 // ---------------------------------------------------------------------------

apps/extension/src/tools/navigation.ts

@@ -28,7 +28,13 @@ import type {
   RpcError,
   WaitUntil,
 } from "@/transport/types";
+import {
+  type BrowserNavigationApi,
+  chromeBrowserNavigationApi,
+  navigateWithBrowserApi,
+} from "./browser-navigation";
 import { attachDialogs, markDialogCursor } from "./dialogs";
+import { cdpError, isCdpExtensionAccessDenied } from "./errors";
 import {
   type CdpRunner,
   type ChromeTabsApi,
@@ -42,6 +48,7 @@ import {
 export interface NavigationDeps {
   cdp: CdpRunner;
   tabsApi: ChromeTabsApi;
+  browserNavigation?: BrowserNavigationApi;
   /** Optional AbortSignal — M7 abort hook (M10.2 will wire the full chain). */
   signal?: AbortSignal;
   /** Override default timeout when the caller omits `timeout_ms`. */
@@ -479,6 +486,81 @@ async function readTabUrl(api: ChromeTabsApi, tabId: number): Promise<string | u
   }
 }
 
+/** Recover only a failed preflight; never replay an already-dispatched navigation. */
+async function recoverBrowserNavigation(
+  deps: NavigationDeps,
+  tabId: number,
+  action: (api: BrowserNavigationApi) => Promise<unknown>,
+  waitUntil: WaitUntil,
+  timeoutMs: number,
+): Promise<ReloadResult | RpcError> {
+  const abort = linkedAbortSignal(deps.signal);
+  const deadline = Date.now() + timeoutMs;
+  const api = deps.browserNavigation ?? chromeBrowserNavigationApi;
+  try {
+    let outcome = await navigateWithBrowserApi(
+      api,
+      tabId,
+      () => action(api),
+      waitUntil === "networkidle" ? "commit" : waitUntil,
+      timeoutMs,
+      abort.signal,
+    );
+    if (outcome.reached === "failed") return outcome.error;
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    if (outcome.reached === "match") {
+      // A completed reload is not a recovery if the restricted frame remains.
+      await deps.cdp.send(tabId, "Page.enable", {});
+      if (abort.signal.aborted)
+        return { code: "cancelled", message: "navigation recovery aborted" };
+      if (waitUntil === "networkidle") {
+        // webNavigation cannot prove network idle. Subscribe on the new
+        // document before enabling CDP lifecycle events after its commit.
+        const frame = await readMainFrameInfo(deps.cdp, tabId);
+        if (!frame.frameId) return cdpError("no main frame after navigation");
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+          outcome = { reached: "timeout", lastLifecycle: "commit" };
+        } else {
+          const wait = startLifecycleWait(
+            deps.cdp,
+            tabId,
+            frame.frameId,
+            "networkIdle",
+            remaining,
+            abort.signal,
+            { loaderId: frame.loaderId ?? undefined },
+          );
+          await deps.cdp.send(tabId, "Page.setLifecycleEventsEnabled", { enabled: true });
+          outcome = await wait.promise;
+        }
+      }
+    }
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    return {
+      tab_id: tabId,
+      final_url: await readTabUrl(deps.tabsApi, tabId),
+      reached: outcome.reached === "match" ? waitUntil : "timeout",
+      ...(outcome.reached === "timeout"
+        ? {
+            error_text: `timed out waiting for ${waitUntil} during navigation recovery after ${timeoutMs}ms`,
+          }
+        : {}),
+    };
+  } catch (error) {
+    return abort.signal.aborted
+      ? { code: "cancelled", message: "navigation recovery aborted" }
+      : cdpError(error);
+  } finally {
+    abort.abort();
+    abort.cleanup();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // tool.navigate
 // ---------------------------------------------------------------------------
@@ -505,7 +587,20 @@ export async function handleNavigate(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.update(target.tabId, { url: params.url }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, { ...recovered, url: params.url });
+    }
     const expected = cdpLifecycleName(waitUntil);
     const beforeReadyState = await probeMainFrameReadyState(deps.cdp, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
@@ -574,10 +669,7 @@ export async function handleNavigate(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 
@@ -727,7 +819,24 @@ export async function handleReload(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.reload(target.tabId, { bypassCache: ignoreCache }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+        ...recovered,
+        previous_url: previousUrl,
+      });
+    }
     const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
     const expected = cdpLifecycleName(waitUntil);
@@ -776,10 +885,7 @@ export async function handleReload(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 

apps/extension/src/tools/observation.ts

@@ -1,3 +1,4 @@
+import type { CapturedSceneInput } from "./vom/facts";
 // Observation handlers — `tool.snapshot`, `tool.get_html`, `tool.screenshot`,
 // and semantic `tool.observe` (design §7). Each handler resolves the target
 // tab (defaulting to the Agent Window's active tab when omitted) and
@@ -34,6 +35,7 @@ import type {
 import { attachDialogs, markDialogCursor } from "./dialogs";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry } from "./frame-geometry";
+import { screenshotPageRect } from "./geometry/coordinate-types";
 import {
   type ChromeTabsApi,
   enforceToolTargetScope,
@@ -47,15 +49,9 @@ import {
   type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import {
-  type CapturedNode,
-  type CapturedSurfaceProbe,
-  type CapturedViewModel,
-  captureViewModel,
-  collectOverlayExcludedBackendIds,
-  probeHoverSurfaces,
-} from "./vom/capture";
-import { type CapturedFrameDocument, captureFrameData } from "./vom/frame-capture";
+import { type CapturedNode, type CapturedSurfaceProbe, probeHoverSurfaces } from "./vom/capture";
+import { captureObservationFacts, semanticCapture } from "./vom/capture-coordinator";
+import type { FrameDocument as CapturedFrameDocument } from "./vom/frame-document";
 import { withOverlayBypass } from "./vom/hover-perception";
 import { probeTooltipNames } from "./vom/name-enrichment";
 import {
@@ -197,15 +193,14 @@ async function captureElementScreenshot(
   if (isRpcError(geometry)) return geometry;
   if (signal?.aborted) return cancelled("screenshot");
   const rect = geometry.topBounds;
+  const clip = screenshotPageRect(rect, geometry.topViewport);
+  if (!clip) return { code: "cdp_failed", message: "invalid screenshot coordinate space" };
 
   try {
     const shot = await cdp.send<{ data?: string }>(tabId, "Page.captureScreenshot", {
       format: "png",
       clip: {
-        x: rect.x,
-        y: rect.y,
-        width: rect.width,
-        height: rect.height,
+        ...clip.rect,
         scale: 1,
       },
     });
@@ -530,7 +525,7 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
 
 function buildConditionalSurfaces(
   nodes: VomNode[],
-  captured: CapturedViewModel,
+  captured: CapturedSceneInput,
   probes: CapturedSurfaceProbe[],
 ): CondSurface[] {
   if (probes.length === 0) return [];
@@ -660,161 +655,9 @@ export interface BuildVomSceneOptions {
 
 export type VomFrameDocument = CapturedFrameDocument<CdpAxNode>;
 
-function legacyFrameDocuments(
-  axNodes: CdpAxNode[],
-  captured: CapturedViewModel,
-  pageUrl?: string,
-  rootTarget: VomFrameDocument["target"] = { tabId: 0 },
-): VomFrameDocument[] {
-  const rootFrameId = captured.rootFrameId ?? "root";
-  const documents: VomFrameDocument[] = [
-    {
-      frameId: rootFrameId,
-      contextScopeId: rootFrameId,
-      target: rootTarget,
-      ...(pageUrl ? { url: pageUrl } : {}),
-      axNodes: [],
-      domNodes: captured.nodes.map((node) => ({ ...node, frameId: node.frameId ?? rootFrameId })),
-    },
-  ];
-  const pending = [...captured.iframeNodes.entries()];
-  let progress = true;
-  let nextSyntheticFrame = 1;
-  while (pending.length > 0 && progress) {
-    progress = false;
-    for (let index = pending.length - 1; index >= 0; index -= 1) {
-      const [ownerBackendNodeId, domNodes] = pending[index];
-      const parent = documents.find((document) =>
-        document.domNodes.some((node) => node.backendNodeId === ownerBackendNodeId),
-      );
-      if (!parent) continue;
-      const frameId =
-        domNodes.find((node) => node.frameId)?.frameId ?? `legacy-frame-${nextSyntheticFrame++}`;
-      documents.push({
-        frameId,
-        parentFrameId: parent.frameId,
-        ownerBackendNodeId,
-        contextScopeId: frameId,
-        target: parent.target,
-        axNodes: [],
-        domNodes: domNodes.map((node) => ({ ...node, frameId: node.frameId ?? frameId })),
-      });
-      pending.splice(index, 1);
-      progress = true;
-    }
-  }
-
-  const documentByFrameId = new Map(documents.map((document) => [document.frameId, document]));
-  const backendFrame = new Map<number, string>();
-  const childFrameByOwner = new Map<number, string>();
-  for (const document of documents) {
-    if (document.ownerBackendNodeId !== undefined) {
-      childFrameByOwner.set(document.ownerBackendNodeId, document.frameId);
-    }
-    for (const node of document.domNodes) backendFrame.set(node.backendNodeId, document.frameId);
-  }
-  const axById = new Map(axNodes.map((node) => [node.nodeId, node]));
-  const ownership = new Map<string, string>();
-  const resolving = new Set<string>();
-  const frameForAx = (node: CdpAxNode): string => {
-    const cached = ownership.get(node.nodeId);
-    if (cached) return cached;
-    let frameId: string | undefined;
-    if (node.frameId && documentByFrameId.has(node.frameId)) frameId = node.frameId;
-    if (!frameId && typeof node.backendDOMNodeId === "number") {
-      frameId = backendFrame.get(node.backendDOMNodeId);
-    }
-    if (!frameId && node.parentId && !resolving.has(node.nodeId)) {
-      const parent = axById.get(node.parentId);
-      if (parent) {
-        frameId =
-          typeof parent.backendDOMNodeId === "number"
-            ? childFrameByOwner.get(parent.backendDOMNodeId)
-            : undefined;
-        if (!frameId) {
-          resolving.add(node.nodeId);
-          frameId = frameForAx(parent);
-          resolving.delete(node.nodeId);
-        }
-      }
-    }
-    frameId ??= rootFrameId;
-    ownership.set(node.nodeId, frameId);
-    return frameId;
-  };
-  for (const node of axNodes) frameForAx(node);
-  for (const node of axNodes) {
-    const frameId = ownership.get(node.nodeId) ?? rootFrameId;
-    const document = documentByFrameId.get(frameId) ?? documents[0];
-    document.axNodes.push({
-      ...node,
-      frameId,
-      ...(node.parentId && ownership.get(node.parentId) === frameId
-        ? { parentId: node.parentId }
-        : { parentId: undefined }),
-      ...(node.childIds
-        ? { childIds: node.childIds.filter((childId) => ownership.get(childId) === frameId) }
-        : {}),
-    });
-  }
-  return documents;
-}
-
-function withLegacyBackendIds(scene: VomScene): VomScene {
-  const used = new Set<number>();
-  const idMap = new Map<number, number>();
-  let nextVirtualId = -1;
-  for (const node of scene.nodes) {
-    const preferred = node.backendNodeId;
-    const id = preferred !== undefined && !used.has(preferred) ? preferred : nextVirtualId--;
-    used.add(id);
-    idMap.set(node.id, id);
-  }
-  return {
-    ...scene,
-    nodes: scene.nodes.map((node) => ({
-      ...node,
-      id: idMap.get(node.id) as number,
-      parentId: node.parentId === null ? null : (idMap.get(node.parentId) ?? null),
-      ...(node.domParentId !== undefined
-        ? { domParentId: node.domParentId === null ? null : (idMap.get(node.domParentId) ?? null) }
-        : {}),
-      ...(node.domAncestorIds
-        ? { domAncestorIds: node.domAncestorIds.flatMap((id) => idMap.get(id) ?? []) }
-        : {}),
-    })),
-    ...(scene.surfaces
-      ? {
-          surfaces: scene.surfaces.map((surface) => ({
-            ...surface,
-            triggerId: idMap.get(surface.triggerId) ?? surface.triggerId,
-          })),
-        }
-      : {}),
-    ...(scene.activeScopeBlocks
-      ? {
-          activeScopeBlocks: scene.activeScopeBlocks.map((block) => ({
-            ...block,
-            triggerId: idMap.get(block.triggerId) ?? block.triggerId,
-          })),
-        }
-      : {}),
-  };
-}
-
-export function buildVomScene(
-  axNodes: CdpAxNode[],
-  captured: CapturedViewModel,
-  options: BuildVomSceneOptions = {},
-): VomScene {
-  return withLegacyBackendIds(
-    buildFrameVomScene(legacyFrameDocuments(axNodes, captured, options.pageUrl), captured, options),
-  );
-}
-
 export function buildFrameVomScene(
   documents: VomFrameDocument[],
-  captured: CapturedViewModel,
+  captured: CapturedSceneInput,
   options: BuildVomSceneOptions = {},
 ): VomScene {
   const scene = buildSemanticVomScene({
@@ -830,7 +673,7 @@ export function buildFrameVomScene(
 function attachCapturedSceneAnnotations(
   scene: VomScene,
   documents: VomFrameDocument[],
-  captured: CapturedViewModel,
+  captured: CapturedSceneInput,
   surfaceProbes: CapturedSurfaceProbe[],
 ): VomScene {
   const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
@@ -980,51 +823,6 @@ export async function handleGetHtml(
   }
 }
 
-function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedViewModel {
-  return { viewport, nodes: [], iframeNodes: new Map(), excludedBackendNodeIds: new Set() };
-}
-
-interface LayoutMetricsViewportReply {
-  cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number };
-}
-
-async function fallbackCapturedViewModel(
-  cdp: CdpRunner,
-  tabId: number,
-  signal?: AbortSignal,
-): Promise<CapturedViewModel> {
-  throwIfAborted(signal, "observation");
-  let viewport = { width: 0, height: 0 };
-  try {
-    const metrics = await cdp.send<LayoutMetricsViewportReply>(tabId, "Page.getLayoutMetrics", {});
-    throwIfAborted(signal, "observation");
-    const source = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-    viewport = {
-      width: source.clientWidth ?? 0,
-      height: source.clientHeight ?? 0,
-    };
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-  }
-  const excludedBackendNodeIds = await collectOverlayExcludedBackendIds(cdp, tabId, signal);
-  throwIfAborted(signal, "observation");
-  return { ...emptyCapturedViewModel(viewport), excludedBackendNodeIds };
-}
-
-async function captureForVom(
-  cdp: CdpRunner,
-  tabId: number,
-  options: CaptureVomObservationOptions,
-): Promise<CapturedViewModel> {
-  try {
-    return await captureViewModel(cdp, tabId, { signal: options.signal });
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    return fallbackCapturedViewModel(cdp, tabId, options.signal);
-  }
-}
-
 export interface HoverProbeOutcome {
   /** Whether any active hover was dispatched during this observation. */
   performed: boolean;
@@ -1057,7 +855,7 @@ const NO_HOVER_PROBES: HoverProbeOutcome = {
 async function runHoverProbes(
   cdp: CdpRunner,
   tabId: number,
-  captured: CapturedViewModel,
+  captured: CapturedSceneInput,
   documents: VomFrameDocument[],
   staticSemantics: ReturnType<typeof resolveSemanticGraph>,
   options: CaptureVomObservationOptions,
@@ -1096,14 +894,9 @@ export async function captureVomObservation(
   throwIfAborted(options.signal, "observation");
   await cdp.ensureAttachedToUrl?.(tabId, url);
   throwIfAborted(options.signal, "observation");
-  const captured = await captureForVom(cdp, tabId, options);
+  const facts = await captureObservationFacts<CdpAxNode>(cdp, tabId, options.signal, url);
+  const { captured, documents: normalizedDocuments } = semanticCapture(facts);
   throwIfAborted(options.signal, "observation");
-  const documents = await captureFrameData<CdpAxNode>(cdp, tabId, captured, options.signal);
-  throwIfAborted(options.signal, "observation");
-  const normalizedDocuments =
-    documents.length === 1 && captured.iframeNodes.size > 0
-      ? legacyFrameDocuments(documents[0].axNodes, captured, url, documents[0].target)
-      : documents;
   const semanticGraph = buildSemanticGraph({
     documents: normalizedDocuments,
     viewport: captured.viewport,
@@ -1131,12 +924,43 @@ export async function captureVomObservation(
     captured,
     hoverProbes.surfaceProbes,
   );
+  // Reserve space using the renderer's character-based token estimate. Like VOM
+  // headers, this integrity notice remains visible even under a tiny token budget.
+  const notices: string[] = [];
+  if (facts.issues.some((issue) => issue.stage === "geometry"))
+    notices.push(
+      "@warning geometry incomplete: some page or frame content has no top-level coordinates.",
+    );
+  const incompleteStages = ["dom", "ax", "forms", "ownership"].filter((stage) =>
+    facts.issues.some((issue) => issue.stage === stage),
+  );
+  if (incompleteStages.length)
+    notices.push(
+      `@warning observation incomplete: some ${incompleteStages.join(", ")} data is unavailable or omitted.`,
+    );
+  if (
+    facts.issues.some(
+      (issue) => issue.stage === "identity" && issue.reason !== "identity-unverified",
+    )
+  )
+    notices.push(
+      "@warning observation incomplete: some documents were omitted because their identity changed or could not be revalidated.",
+    );
+  if (facts.issues.some((issue) => issue.reason === "identity-unverified"))
+    notices.push(
+      "@warning document identity unverified: some retained documents could not be checked for changes during capture.",
+    );
+  const captureNotice = notices.join("\n");
   const rendered = renderVom(decoratedScene, {
     maxDepth: options.maxDepth,
-    maxTokens: options.maxTokens,
+    maxTokens:
+      !captureNotice || options.maxTokens === undefined
+        ? options.maxTokens
+        : Math.max(0, options.maxTokens - Math.ceil((captureNotice.length + 1) / 4)),
     redactValues: options.redactValues,
     activeRegionPolicy: options.activeRegionPolicy,
   });
+  if (captureNotice) rendered.text += `\n${captureNotice}`;
   throwIfAborted(options.signal, "observation");
   return projectRecordSafeObservation({
     rootFrameId: captured.rootFrameId ?? normalizedDocuments[0]?.frameId ?? "root",

apps/extension/src/tools/scroll-visibility.ts

@@ -0,0 +1,142 @@
+import { cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { NodeAddress } from "./frame-geometry";
+import {
+  clipPolygon,
+  projectRegionToViewport,
+  type Region,
+  rectPolygon,
+  regionBounds,
+  type ViewportRect,
+} from "./geometry";
+import { GeometryContext } from "./geometry/frame-context";
+import { type CdpRunner, sendToCdpTarget } from "./shared";
+
+// Ask the renderer to apply containing-block clips (including shadow DOM),
+// instead of treating layout quads as visible pixels. Each document is measured
+// locally; the existing frame projections supply the top-viewport coordinates.
+// IntersectionObserver reports a bounding rectangle, not an occlusion/hit test.
+const VISIBLE_RECT = `function(timeoutMs) {
+  const element = this;
+  const visible = () => element.isConnected && element.checkVisibility({
+    checkOpacity: true, checkVisibilityCSS: true, contentVisibilityAuto: true
+  });
+  if (typeof element.checkVisibility !== 'function' || !visible()) return null;
+  return new Promise((resolve, reject) => {
+    const observer = new IntersectionObserver(([entry]) => {
+      clearTimeout(timer);
+      observer.disconnect();
+      const rect = entry.intersectionRect;
+      resolve(visible() && entry.isIntersecting && rect.width > 0 && rect.height > 0
+        ? { x: rect.x, y: rect.y, width: rect.width, height: rect.height }
+        : null);
+    }, { root: element.ownerDocument });
+    const timer = setTimeout(() => {
+      observer.disconnect();
+      reject(new Error('scroll-to visibility measurement timed out'));
+    }, timeoutMs);
+    observer.observe(element);
+  });
+}`;
+
+async function visibleRect(
+  cdp: CdpRunner,
+  address: NodeAddress,
+  deadline: number,
+): Promise<ViewportRect | null> {
+  const resolved = await sendToCdpTarget<{ object?: { objectId?: string } }>(
+    cdp,
+    address.target,
+    "DOM.resolveNode",
+    { backendNodeId: address.backendNodeId },
+  );
+  if (!resolved.object?.objectId) throw new Error("scroll-to could not resolve the target element");
+  const reply = await sendToCdpTarget<{
+    result?: { value?: ViewportRect | null };
+    exceptionDetails?: { text?: string; exception?: { description?: string } };
+  }>(cdp, address.target, "Runtime.callFunctionOn", {
+    objectId: resolved.object.objectId,
+    functionDeclaration: VISIBLE_RECT,
+    // Bound this read even if a background document stops rendering. Its
+    // observer always disconnects; cancellation cannot leave a live observer.
+    arguments: [{ value: Math.max(1, Math.min(1_000, deadline - Date.now())) }],
+    awaitPromise: true,
+    returnByValue: true,
+  });
+  if (reply.exceptionDetails) {
+    const details = reply.exceptionDetails;
+    throw new Error(details.exception?.description ?? details.text ?? "visibility script failed");
+  }
+  const rect = reply.result?.value;
+  if (rect === null) return null;
+  if (
+    !rect ||
+    ![rect.x, rect.y, rect.width, rect.height].every(Number.isFinite) ||
+    rect.width <= 0 ||
+    rect.height <= 0
+  ) {
+    throw new Error("scroll-to visibility measurement returned invalid bounds");
+  }
+  return rect;
+}
+
+async function projectRect(
+  context: GeometryContext,
+  address: NodeAddress,
+  rect: ViewportRect,
+): Promise<Region> {
+  let region: Region = [rectPolygon({ x: rect.x, y: rect.y, w: rect.width, h: rect.height })];
+  if (!address.frameId) return region;
+  const frame = await context.frame(address.frameId);
+  if (!frame || cdpTargetKey(frame.target) !== cdpTargetKey(address.target)) {
+    throw new Error("scroll-to frame no longer belongs to its target");
+  }
+  const parent = frame.parentFrameId ? await context.frame(frame.parentFrameId) : undefined;
+  if (parent && cdpTargetKey(parent.target) === cdpTargetKey(frame.target)) {
+    // DOM rectangles are document-local. Same-target iframe quads are already
+    // target-local, so cross this one boundary before the target projection.
+    const viewport = await context.viewport(frame.target);
+    if (frame.ownerBackendNodeId === undefined || !viewport) {
+      throw new Error("scroll-to could not resolve the frame viewport");
+    }
+    const local = await context.snapshotProjection(address, frame.ownerBackendNodeId, [], viewport);
+    if (local.status !== "available") throw new Error("scroll-to could not project the frame");
+    region = projectRegionToViewport(region, local.projection.geometry);
+  }
+  const projection = await context.targetProjection(frame.frameId);
+  if (!projection) throw new Error("scroll-to could not project the target viewport");
+  return projectRegionToViewport(region, projection);
+}
+
+/** Only scroll-to needs renderer-clipped bounds; other interaction geometry is unchanged. */
+export async function scrollVisibleBounds(
+  cdp: CdpRunner,
+  tabId: number,
+  address: NodeAddress,
+  deadline: number,
+): Promise<ViewportRect | null> {
+  const context = new GeometryContext(cdp, tabId);
+  const rect = await visibleRect(cdp, address, deadline);
+  if (!rect) return null;
+  let region = await projectRect(context, address, rect);
+  if (address.frameId) {
+    const ancestry = await context.ancestry(address.frameId);
+    if (!ancestry) throw new Error("scroll-to could not resolve the frame ancestry");
+    for (const child of ancestry) {
+      const parent = child.parentFrameId ? await context.frame(child.parentFrameId) : undefined;
+      if (!parent || child.ownerBackendNodeId === undefined) {
+        throw new Error("scroll-to could not resolve the frame owner");
+      }
+      const owner = {
+        target: parent.target,
+        frameId: parent.frameId,
+        backendNodeId: child.ownerBackendNodeId,
+      };
+      // A visible child document can still have a hidden or clipped iframe.
+      const ownerRect = await visibleRect(cdp, owner, deadline);
+      if (!ownerRect) return null;
+      const clips = await projectRect(context, owner, ownerRect);
+      region = region.flatMap((polygon) => clips.map((clip) => clipPolygon(polygon, clip)));
+    }
+  }
+  return regionBounds(region);
+}

apps/extension/src/tools/scroll.ts

@@ -0,0 +1,137 @@
+import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
+import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { SessionManager } from "@/session-manager/manager";
+import type { RpcError, ScrollToParams, ScrollToResult } from "@/transport/types";
+import { attachDialogs, markDialogCursor } from "./dialogs";
+import { cdpError, rpcError } from "./errors";
+import { scrollElementAndFramesIntoView } from "./frame-geometry";
+import { resolveBackendNode } from "./interaction";
+import { scrollVisibleBounds } from "./scroll-visibility";
+import {
+  type CdpRunner,
+  type ChromeTabsApi,
+  chromeTabsApi,
+  enforceAgentWindow,
+  isRpcError,
+  lookupSession,
+  resolveTargetTab,
+  sendToCdpTarget,
+} from "./shared";
+
+export interface ScrollToDeps {
+  cdp: CdpRunner;
+  tabsApi: ChromeTabsApi;
+  signal?: AbortSignal;
+}
+
+let defaultDeps: { cdp: ChromiumCdp; tabsApi: ChromeTabsApi } | null = null;
+function getDefaultDeps(): { cdp: ChromiumCdp; tabsApi: ChromeTabsApi } {
+  if (!defaultDeps) defaultDeps = { cdp: new ChromiumCdp(), tabsApi: chromeTabsApi };
+  return defaultDeps;
+}
+
+export async function handleScrollTo(
+  manager: SessionManager,
+  params: ScrollToParams,
+  deps: ScrollToDeps = getDefaultDeps(),
+): Promise<ScrollToResult | RpcError> {
+  const ctxOrErr = lookupSession(manager, params, "scroll-to");
+  if (isRpcError(ctxOrErr)) return ctxOrErr;
+  const ctx = ctxOrErr;
+  const timeout = params.timeout_ms ?? 30_000;
+  if (!Number.isInteger(timeout) || timeout <= 0) {
+    return { code: "invalid_params", message: "timeout_ms must be a positive integer" };
+  }
+  const deadline = Date.now() + timeout;
+  const checkActive = () => {
+    if (deps.signal?.aborted) throw new DOMException("scroll-to aborted", "AbortError");
+    if (Date.now() >= deadline) throw new DOMException("scroll-to timed out", "TimeoutError");
+  };
+  const objectGroup = `bsk-scroll-${crypto.randomUUID()}`;
+  const objectTargets = new Map<string, CdpTarget>();
+  const send = async <T>(target: CdpTarget, method: string, args?: object): Promise<T> => {
+    checkActive();
+    // Also own objects allocated by the shared scroll fallback. Record the
+    // target before awaiting so cancellation cannot skip their cleanup.
+    if (method === "DOM.resolveNode") objectTargets.set(cdpTargetKey(target), target);
+    const result = await sendToCdpTarget<T>(
+      deps.cdp,
+      target,
+      method,
+      method === "DOM.resolveNode" ? { ...args, objectGroup } : args,
+    );
+    checkActive();
+    return result;
+  };
+  let graph: ReturnType<NonNullable<CdpRunner["getFrameGraph"]>> | undefined;
+  const cdp: CdpRunner = {
+    send: (tabId, method, args) => send({ tabId }, method, args),
+    sendToTarget: send,
+    trackSessionTab: deps.cdp.trackSessionTab?.bind(deps.cdp),
+    getFrameGraph: deps.cdp.getFrameGraph
+      ? async (tabId) => {
+          checkActive();
+          graph ??= deps.cdp.getFrameGraph!(tabId);
+          const result = await graph;
+          checkActive();
+          return result;
+        }
+      : undefined,
+  };
+  try {
+    checkActive();
+    const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+    checkActive();
+    if (isRpcError(target)) return target;
+    const denied = enforceAgentWindow(ctx, target, "scroll-to");
+    if (denied) return denied;
+    const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
+    const node = await resolveBackendNode(cdp, ctx, target, params, "scroll-to");
+    checkActive();
+    if (isRpcError(node)) return node;
+    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
+    const scrollError = await scrollElementAndFramesIntoView(
+      cdp,
+      target.tabId,
+      node.cdpTarget,
+      node.backendNodeId,
+      node.frameId,
+    );
+    checkActive();
+    if (scrollError) return scrollError;
+    const bounds = await scrollVisibleBounds(
+      cdp,
+      target.tabId,
+      {
+        target: node.cdpTarget,
+        backendNodeId: node.backendNodeId,
+        frameId: node.frameId,
+      },
+      deadline,
+    );
+    checkActive();
+    if (!bounds)
+      return rpcError(
+        "permission_denied",
+        "element_not_visible",
+        "scroll-to target has no visible area",
+      );
+    return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+      tab_id: target.tabId,
+      used_ref: node.usedRef,
+      used_selector: node.usedSelector,
+      ...bounds,
+    });
+  } catch (error) {
+    if (deps.signal?.aborted) return { code: "cancelled", message: "scroll-to aborted" };
+    if (Date.now() >= deadline) return { code: "timeout", message: "scroll-to timed out" };
+    return cdpError(error);
+  } finally {
+    // Cleanup bypasses the cancellation guard and cannot replace the result.
+    for (const target of objectTargets.values()) {
+      await sendToCdpTarget(deps.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }).catch(
+        () => {},
+      );
+    }
+  }
+}

apps/extension/src/tools/session.ts

@@ -2,7 +2,7 @@ import { type SessionManager, SessionStartCleanupError } from "@/session-manager
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";
 import { clearRecordingForSession } from "./record";
-import type { ChromeTabsApi } from "./shared";
+import type { CdpRunner, ChromeTabsApi } from "./shared";
 import { isRpcError } from "./shared";
 import { returnBorrowedTab, type TabManagementDeps } from "./tabs";
 
@@ -84,7 +84,7 @@ export interface SessionStopResult {
 
 export interface SessionStopDeps {
   signal?: AbortSignal;
-  cdp?: {
+  cdp?: Pick<CdpRunner, "releaseSessionTab"> & {
     detachSession(sessionId: string): Promise<void>;
   };
   /**
@@ -209,6 +209,7 @@ export async function handleSessionStop(
     try {
       const tabManagement = {
         ...(deps.tabManagement ?? {}),
+        cdp: deps.cdp ?? deps.tabManagement?.cdp,
         signal: deps.signal,
         isAgentWindowId:
           deps.tabManagement?.isAgentWindowId ??

apps/extension/src/tools/shared.ts

@@ -55,8 +55,10 @@ export interface CdpRunner {
   sendToTarget?<T = unknown>(target: CdpTarget, method: string, params?: object): Promise<T>;
   detach?(tabId: number): Promise<void>;
   getFrameGraph?(tabId: number): Promise<CdpFrameGraph>;
+  getAttachmentId?(tabId: number): string | undefined;
   ensureAttachedToUrl?(tabId: number, expectedUrl: string | undefined): Promise<void>;
   trackSessionTab?(sessionId: string, tabId: number): void;
+  releaseSessionTab?(sessionId: string, tabId: number): Promise<void>;
   onEvent?(handler: (source: CdpDebuggee, method: string, params: unknown) => void): {
     dispose(): void;
   };

apps/extension/src/tools/tabs.ts

@@ -10,7 +10,7 @@ import {
 import type { SessionContext, SessionManager } from "@/session-manager/manager";
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";
-import { isRpcError, lookupSession } from "./shared";
+import { type CdpRunner, isRpcError, lookupSession } from "./shared";
 
 export type TabScope = "user" | "agent" | "all";
 
@@ -287,6 +287,10 @@ export interface TabManagementDeps {
   approveBorrow?: BorrowConfirmationApprover;
   /** Clears Agent-scoped overlays after a borrowed tab is returned. */
   agentOverlayReset?: AgentOverlayResetApi;
+  /** Releases this session's CDP claim after a borrowed tab is returned. */
+  cdp?: Pick<CdpRunner, "releaseSessionTab">;
+  /** Runs after tab_return validation, before moving the borrowed tab. */
+  beforeReturn?: (sessionId: string, tabId: number) => Promise<void>;
   /**
    * Reports whether `windowId` is any live session's Agent Window.
    * `tab_return`'s fallback window picker uses this to avoid moving a
@@ -945,16 +949,22 @@ async function cleanupUnusedFallbackWindow(
   }
 }
 
-function resetAgentOverlaysInReturnedTab(
+async function releaseReturnedTabState(
   ctx: SessionContext,
   tabId: number,
   deps: TabManagementDeps,
-): void {
+): Promise<void> {
   void getAgentOverlayResetApi(deps)
     .resetAgentOverlays(tabId, ctx.sessionId)
     .catch((err) => {
       console.debug("[bsk tab_return] agent overlay reset failed", err);
     });
+  try {
+    await deps.cdp?.releaseSessionTab?.(ctx.sessionId, tabId);
+  } catch (err) {
+    // A successful move must not be retried because debugger cleanup failed.
+    console.debug("[bsk tab_return] CDP release failed", err);
+  }
 }
 
 /**
@@ -1028,7 +1038,7 @@ export async function returnBorrowedTab(
     });
     const movedTab = Array.isArray(moved) ? moved[0] : moved;
     const finalIndex = typeof movedTab?.index === "number" ? movedTab.index : targetIndex;
-    resetAgentOverlaysInReturnedTab(ctx, tabId, deps);
+    await releaseReturnedTabState(ctx, tabId, deps);
     return {
       tabId,
       toWindowId: targetWindowId,
@@ -1070,7 +1080,7 @@ export async function returnBorrowedTab(
         });
         const movedTab = Array.isArray(moved) ? moved[0] : moved;
         const finalIndex = typeof movedTab?.index === "number" ? movedTab.index : target.index;
-        resetAgentOverlaysInReturnedTab(ctx, tabId, deps);
+        await releaseReturnedTabState(ctx, tabId, deps);
         return {
           tabId,
           toWindowId: target.windowId,
@@ -1116,6 +1126,7 @@ export async function handleTabReturn(
       message: `tab_return: tab ${params.tab_id} is not borrowed by this session`,
     };
   }
+  await deps.beforeReturn?.(ctx.sessionId, params.tab_id);
   const outcome = await returnBorrowedTab(ctx, params.tab_id, {
     ...deps,
     isAgentWindowId:

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

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import { OVERLAY_HOST_MARKER_ATTR, OVERLAY_HOST_NAME } from "../../../lib/overlay-bridge";
-import { captureViewModel, collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
+import { collectOverlayExcludedBackendIds, probeHoverSurfaces } from "../capture";
+import { captureObservationFacts, semanticCapture } from "../capture-coordinator";
 
 // Minimal but format-accurate captureSnapshot reply: a body with one
 // fixed full-screen overlay div carrying a password input.
@@ -26,6 +27,7 @@ function fakeSnapshotReply() {
     strings: S,
     documents: [
       {
+        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2],
           nodeType: [1, 1, 1, 1],
@@ -73,6 +75,7 @@ function hoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
+        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1],
           nodeType: [1, 1, 1],
@@ -117,6 +120,7 @@ function twoHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
+        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 1],
           nodeType: [1, 1, 1, 1],
@@ -170,6 +174,7 @@ function nestedHoverTriggerSnapshotReply() {
     strings: S,
     documents: [
       {
+        frameId: "root",
         nodes: {
           parentIndex: [-1, 0, 1, 2, 3],
           nodeType: [1, 1, 1, 1, 1],
@@ -210,38 +215,48 @@ function makeCdp(snapshot: unknown) {
       if (method === "DOMSnapshot.enable") return {};
       if (method === "DOMSnapshot.captureSnapshot") return snapshot;
       if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 } };
+        return {
+          visualViewport: { clientWidth: 1000 },
+          cssVisualViewport: { clientWidth: 1000 },
+          cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+        };
       }
       if (method === "Runtime.evaluate") {
         return {
           result: {
-            value: {
-              controls: [
+            deepSerializedValue: {
+              type: "array",
+              value: [
                 {
-                  state: "filled",
-                  sensitive: true,
-                  defaultValue: "hunter2",
-                  value: "hunter2",
-                  placeholder: "secret",
+                  type: "array",
+                  value: [
+                    { type: "node", value: { backendNodeId: 13 } },
+                    {
+                      type: "string",
+                      value: JSON.stringify({
+                        state: "filled",
+                        sensitive: true,
+                        placeholder: "secret",
+                      }),
+                    },
+                  ],
                 },
               ],
-              childFrames: [],
             },
           },
         };
       }
+      if (method === "Runtime.releaseObjectGroup") return {};
       throw new Error(`unexpected ${method}`);
     }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
   };
 }
 
-describe("captureViewModel", () => {
+describe("snapshot capture and hover", () => {
   it("parses nodes, attrs, rects, paint order and styles", async () => {
-    const { nodes, viewport, iframeNodes } = await captureViewModel(
-      makeCdp(fakeSnapshotReply()),
-      4,
-    );
-    expect(iframeNodes.size).toBe(0);
+    const { nodes, viewport } = semanticCapture(
+      await captureObservationFacts(makeCdp(fakeSnapshotReply()), 4),
+    ).captured;
     expect(viewport).toEqual({ width: 1000, height: 800 });
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div).toMatchObject({ tag: "div", position: "fixed", parentBackendNodeId: 11 });
@@ -253,32 +268,11 @@ describe("captureViewModel", () => {
 
   it("never hovers the page while capturing", async () => {
     const cdp = makeCdp(fakeSnapshotReply());
-    await captureViewModel(cdp, 4);
+    semanticCapture(await captureObservationFacts(cdp, 4)).captured;
 
     expect(cdp.send).not.toHaveBeenCalledWith(4, "Input.dispatchMouseEvent", expect.anything());
   });
 
-  it("batch-enriches form controls without per-node object resolution", async () => {
-    const cdp = makeCdp(fakeSnapshotReply());
-    const result = await captureViewModel(cdp, 4);
-    const input = result.nodes.find((node) => node.backendNodeId === 13);
-
-    expect(input).toMatchObject({
-      formState: "filled",
-      formPlaceholder: "secret",
-      attrs: { type: "password" },
-    });
-    expect(input?.formValue).toBeUndefined();
-    expect(input?.formDefaultValue).toBeUndefined();
-    expect(cdp.send).toHaveBeenCalledWith(
-      4,
-      "Runtime.evaluate",
-      expect.objectContaining({ returnByValue: true }),
-    );
-    expect(cdp.send).not.toHaveBeenCalledWith(4, "DOM.resolveNode", expect.anything());
-    expect(cdp.send).not.toHaveBeenCalledWith(4, "Runtime.callFunctionOn", expect.anything());
-  });
-
   it("runs hover surface probes when explicitly enabled", async () => {
     let hoverStateCalls = 0;
     const cdp = {
@@ -287,6 +281,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return hoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -318,7 +314,7 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = await captureViewModel(cdp, 4);
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -350,6 +346,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return twoHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -378,7 +376,7 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = await captureViewModel(cdp, 4);
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(surfaceProbes).toEqual([
@@ -398,6 +396,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return nestedHoverTriggerSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
@@ -423,7 +423,7 @@ describe("captureViewModel", () => {
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const captured = await captureViewModel(cdp, 4);
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     await probeHoverSurfaces(cdp, 4, captured.nodes);
 
     expect(hoverMoves).toBe(1);
@@ -455,6 +455,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -485,7 +486,7 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
     const ids = nodes.map((n) => n.backendNodeId);
     // Real page nodes survive.
     expect(ids).toContain(12);
@@ -516,6 +517,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 0, 3, 4],
             nodeName: [i("html"), i("body"), i("div"), i(OVERLAY_HOST_NAME), i("div"), i("button")],
@@ -546,7 +548,9 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
+    const { excludedBackendNodeIds } = semanticCapture(
+      await captureObservationFacts(makeCdp(snapshot), 4),
+    ).captured;
     expect(excludedBackendNodeIds).toEqual(new Set([13, 14, 15]));
   });
 
@@ -567,6 +571,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i(OVERLAY_HOST_NAME)],
@@ -589,7 +594,9 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
+    const { nodes, excludedBackendNodeIds } = semanticCapture(
+      await captureObservationFacts(makeCdp(snapshot), 4),
+    ).captured;
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -612,6 +619,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -634,7 +642,9 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { nodes, excludedBackendNodeIds } = await captureViewModel(makeCdp(snapshot), 4);
+    const { nodes, excludedBackendNodeIds } = semanticCapture(
+      await captureObservationFacts(makeCdp(snapshot), 4),
+    ).captured;
     expect(nodes.map((n) => n.backendNodeId)).not.toContain(13);
     expect(excludedBackendNodeIds).toEqual(new Set([13]));
   });
@@ -657,6 +667,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -679,7 +690,7 @@ describe("captureViewModel", () => {
         },
       ],
     };
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
     expect(nodes.find((n) => n.backendNodeId === 12)?.cursor).toBe("pointer");
     expect(nodes.find((n) => n.backendNodeId === 11)?.cursor).toBe("auto");
   });
@@ -691,6 +702,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1, 1, 1],
             nodeName: [i("html"), i("body"), i("button"), i("button"), i("button")],
@@ -717,7 +729,7 @@ describe("captureViewModel", () => {
       ],
     };
 
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(makeCdp(snapshot), 4)).captured;
 
     expect(nodes.find((node) => node.backendNodeId === 12)?.rendered).toBe(true);
     expect(nodes.find((node) => node.backendNodeId === 13)?.rendered).toBe(false);
@@ -731,25 +743,28 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return fakeSnapshotReply();
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 200 },
           };
         }
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = await captureViewModel(cdp, 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     const div = nodes.find((n) => n.backendNodeId === 12);
     expect(div?.localRect?.y).toBe(-200);
     expect(div?.rect).toMatchObject({ y: 0, h: 600 });
   });
 
-  it("normalizes device-pixel bounds by devicePixelRatio", async () => {
+  it("normalizes raw snapshot bounds before viewport clipping", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -777,6 +792,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -784,13 +801,19 @@ describe("captureViewModel", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = await captureViewModel(cdp, 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     expect(nodes.find((n) => n.backendNodeId === 12)?.rect).toEqual({
       x: 0,
       y: 0,
       w: 1000,
       h: 800,
     });
+    expect(nodes.find((n) => n.backendNodeId === 12)?.localRect).toEqual({
+      x: 0,
+      y: 0,
+      w: 1000,
+      h: 800,
+    });
   });
 
   it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -814,6 +837,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -846,13 +870,15 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = await captureViewModel(cdp, 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     const btn = nodes.find((n) => n.backendNodeId === 12);
     expect(btn?.textContent).toBe("登录");
     const link = nodes.find((n) => n.backendNodeId === 14);
@@ -862,7 +888,7 @@ describe("captureViewModel", () => {
     expect(body?.textContent).toBeUndefined();
   });
 
-  it("parses iframe sub-documents and returns iframeNodes keyed by iframe backendNodeId", async () => {
+  it("retains explicit iframe document ownership and projected nodes", async () => {
     const S = [
       "html",
       "body",
@@ -936,39 +962,38 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        if (method === "DOM.getBoxModel")
+          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
+        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+        if (method === "Runtime.callFunctionOn")
+          return { result: { value: { width: 800, height: 400 } } };
+        if (method === "Runtime.releaseObject") return {};
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const {
-      nodes,
-      iframeNodes,
-      frameNodes,
-      frameOwnerBackendNodeIds,
-      frameParentIds,
-      rootFrameId,
-    } = await captureViewModel(cdp, 4);
-    // Main frame has 4 nodes; iframe is included
-    expect(nodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
-    // iframeNodes keyed by the <iframe> element's backendNodeId=13
-    expect(iframeNodes.size).toBe(1);
-    expect(iframeNodes.has(13)).toBe(true);
-    const subNodes = iframeNodes.get(13)!;
+    const facts = await captureObservationFacts(cdp, 4);
+    const root = facts.documents.find((doc) => doc.frame.frameId === "main-frame")!;
+    const child = facts.documents.find((doc) => doc.frame.frameId === "child-frame")!;
+    expect(facts.documents).toHaveLength(2);
+    expect(root.domNodes.find((n) => n.backendNodeId === 13)?.tag).toBe("iframe");
+    const subNodes = child.domNodes;
     const input = subNodes.find((n) => n.backendNodeId === 101);
     expect(input?.tag).toBe("input");
     expect(input?.attrs.type).toBe("text");
     expect(input?.ownerFrameBackendNodeId).toBe(13);
     expect(input?.localRect).toEqual({ x: 0, y: 0, w: 200, h: 40 });
     expect(input?.rect).toEqual({ x: 100, y: 300, w: 200, h: 40 });
-    expect(rootFrameId).toBe("main-frame");
-    expect(frameNodes?.get("child-frame")).toBe(subNodes);
-    expect(frameOwnerBackendNodeIds?.get("child-frame")).toBe(13);
-    expect(frameParentIds?.get("child-frame")).toBe("main-frame");
+    expect(facts.rootFrameId).toBe("main-frame");
+    expect(child.frame.ownerBackendNodeId).toBe(13);
+    expect(child.frame.parentFrameId).toBe("main-frame");
   });
 
-  it("captures iframe documents without requiring owner-frame geometry", async () => {
+  it("projects iframe documents independently of owner snapshot geometry", async () => {
     const S = [
       "html",
       "body",
@@ -986,6 +1011,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1003,6 +1029,7 @@ describe("captureViewModel", () => {
           },
         },
         {
+          frameId: "child",
           scrollOffsetX: 0,
           scrollOffsetY: 0,
           nodes: {
@@ -1026,18 +1053,28 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 1000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
           };
         }
+        if (method === "DOM.getBoxModel")
+          return { model: { content: [100, 300, 900, 300, 900, 700, 100, 700] } };
+        if (method === "DOM.resolveNode") return { object: { objectId: "owner" } };
+        if (method === "Runtime.callFunctionOn")
+          return { result: { value: { width: 800, height: 400 } } };
+        if (method === "Runtime.releaseObject") return {};
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const { iframeNodes } = await captureViewModel(cdp, 4);
-    const input = iframeNodes.get(13)?.find((n) => n.backendNodeId === 101);
+    const { documents } = await captureObservationFacts(cdp, 4);
+    const input = documents
+      .find((doc) => doc.frame.frameId === "child")
+      ?.domNodes?.find((n) => n.backendNodeId === 101);
 
     expect(input?.localRect).toEqual({ x: 20, y: 20, w: 120, h: 60 });
-    expect(input?.rect).toBeNull();
+    expect(input?.rect).toEqual({ x: 120, y: 320, w: 120, h: 60 });
   });
 
   it("recursively normalizes nested iframe sub-documents", async () => {
@@ -1058,6 +1095,7 @@ describe("captureViewModel", () => {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1079,6 +1117,9 @@ describe("captureViewModel", () => {
           },
         },
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
+          frameId: "child",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("iframe")],
@@ -1100,6 +1141,9 @@ describe("captureViewModel", () => {
           },
         },
         {
+          scrollOffsetX: 0,
+          scrollOffsetY: 0,
+          frameId: "nested",
           nodes: {
             parentIndex: [-1, 0],
             nodeName: [i("body"), i("input")],
@@ -1116,21 +1160,54 @@ describe("captureViewModel", () => {
       ],
     };
     const cdp = {
-      send: vi.fn(async (_t: number, method: string) => {
-        if (method === "DOMSnapshot.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return snapshot;
-        if (method === "Page.getLayoutMetrics") {
-          return {
-            cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
-          };
-        }
-        throw new Error(method);
-      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
+      send: vi.fn(
+        async (
+          _t: number,
+          method: string,
+          params?: { backendNodeId?: number; objectId?: string },
+        ) => {
+          if (method === "DOMSnapshot.enable") return {};
+          if (method === "DOMSnapshot.captureSnapshot") return snapshot;
+          if (method === "Page.getLayoutMetrics") {
+            return {
+              visualViewport: { clientWidth: 1000 },
+              cssVisualViewport: { clientWidth: 1000 },
+              cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 0 },
+            };
+          }
+          if (method === "DOM.getBoxModel")
+            return {
+              model: {
+                content:
+                  params?.backendNodeId === 13
+                    ? [10, 20, 310, 20, 310, 220, 10, 220]
+                    : [15, 26, 115, 26, 115, 106, 15, 106],
+              },
+            };
+          if (method === "DOM.resolveNode")
+            return { object: { objectId: String(params?.backendNodeId) } };
+          if (method === "Runtime.callFunctionOn")
+            return {
+              result: {
+                value:
+                  params?.objectId === "13"
+                    ? { width: 300, height: 200 }
+                    : { width: 100, height: 80 },
+              },
+            };
+          if (method === "Runtime.releaseObject") return {};
+          throw new Error(method);
+        },
+      ) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
 
-    const { iframeNodes } = await captureViewModel(cdp, 4);
-    const nestedIframe = iframeNodes.get(13)?.find((n) => n.backendNodeId === 23);
-    const input = iframeNodes.get(23)?.find((n) => n.backendNodeId === 31);
+    const { documents } = await captureObservationFacts(cdp, 4);
+    const nestedIframe = documents
+      .find((doc) => doc.frame.frameId === "child")
+      ?.domNodes?.find((n) => n.backendNodeId === 23);
+    const input = documents
+      .find((doc) => doc.frame.frameId === "nested")
+      ?.domNodes?.find((n) => n.backendNodeId === 31);
 
     expect(nestedIframe?.localRect).toEqual({ x: 5, y: 6, w: 100, h: 80 });
     expect(nestedIframe?.rect).toEqual({ x: 15, y: 26, w: 100, h: 80 });
@@ -1139,13 +1216,14 @@ describe("captureViewModel", () => {
     expect(input?.rect).toEqual({ x: 16, y: 28, w: 40, h: 20 });
   });
 
-  it("normalizes bounds then subtracts CSS scroll at dpr>1", async () => {
+  it("subtracts CSS scroll once without dividing snapshot bounds by a metrics ratio", async () => {
     const S = ["html", "body", "div", "position", "fixed", "static", "pointer-events", "auto"];
     const i = (s: string) => S.indexOf(s);
     const snapshot = {
       strings: S,
       documents: [
         {
+          frameId: "root",
           nodes: {
             parentIndex: [-1, 0, 1],
             nodeName: [i("html"), i("body"), i("div")],
@@ -1173,6 +1251,8 @@ describe("captureViewModel", () => {
         if (method === "DOMSnapshot.captureSnapshot") return snapshot;
         if (method === "Page.getLayoutMetrics") {
           return {
+            visualViewport: { clientWidth: 2000 },
+            cssVisualViewport: { clientWidth: 1000 },
             cssLayoutViewport: { clientWidth: 1000, clientHeight: 800, pageX: 0, pageY: 100 },
             layoutViewport: { clientWidth: 2000, clientHeight: 1600 },
           };
@@ -1180,7 +1260,7 @@ describe("captureViewModel", () => {
         throw new Error(method);
       }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
     };
-    const { nodes } = await captureViewModel(cdp, 4);
+    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
     expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
   });
 

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

@@ -0,0 +1,168 @@
+import { describe, expect, it, vi } from "vitest";
+import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import { createCaptureCheckpoint } from "../capture-abort";
+import { buildDocumentIndex, type DecodedNode } from "../facts";
+import { decodeDocument, REQUESTED_STYLES, VISUAL_SNAPSHOT } from "../snapshot";
+
+function node(id: number, parent: number | null): DecodedNode {
+  return {
+    backendNodeId: id,
+    parentBackendNodeId: parent,
+    tag: "div",
+    attrs: {},
+    paintOrder: 0,
+    position: "static",
+    pointerEvents: "auto",
+  };
+}
+
+describe("document facts", () => {
+  it.each([
+    1_000, 10_000, 100_000,
+  ])("indexes deep and wide inputs of %i without copying ancestors", async (count) => {
+    for (const wide of [false, true]) {
+      let reads = 0;
+      const input = Array.from({ length: count }, (_, i) => {
+        const item = node(i, i ? (wide ? 0 : i - 1) : null);
+        if (i === 0) item.attrs[OVERLAY_HOST_MARKER_ATTR] = "";
+        Object.defineProperty(item, "parentBackendNodeId", {
+          get: () => {
+            reads++;
+            return i ? (wide ? 0 : i - 1) : null;
+          },
+        });
+        return item;
+      }).reverse(); // parent need not precede child
+      const index = await buildDocumentIndex(input);
+      expect(index.nodes.size).toBe(count);
+      expect(index.excludedBackendNodeIds.size).toBe(count);
+      expect(reads).toBeLessThanOrEqual(count * 8);
+      expect(index.nodes.get(count - 1)).toBe(input[0]);
+    }
+  });
+
+  it("handles cycles and orphans and propagates overlay through shadow roots", async () => {
+    const host = { ...node(1, null), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
+    const input = [
+      node(3, 2),
+      { ...node(2, 1), tag: "#document-fragment" },
+      host,
+      node(4, 99),
+      node(5, 6),
+      node(6, 5),
+      node(7, 6),
+    ];
+    const index = await buildDocumentIndex(input);
+    expect([...index.excludedBackendNodeIds].sort()).toEqual([1, 2, 3]);
+    expect(index.nodes.size).toBe(input.length);
+  });
+
+  it("does not propagate a descendant overlay backwards into a cycle", async () => {
+    const overlay = { ...node(3, 1), attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } };
+    const index = await buildDocumentIndex([overlay, node(1, 2), node(2, 1)]);
+    expect([...index.excludedBackendNodeIds]).toEqual([3]);
+  });
+
+  it("decodes current observation bounds, styles and attributes without projecting coordinates", async () => {
+    const strings = ["div", "aria-hidden", "true", "inert", "", "visible", "0", "static", "auto"];
+    const styles = REQUESTED_STYLES.map((style) =>
+      style === "visibility" ? 5 : style === "opacity" ? 6 : style === "position" ? 7 : 8,
+    );
+    const { nodes } = await decodeDocument(
+      {
+        nodes: { backendNodeId: [1], parentIndex: [-1], nodeName: [0], attributes: [[1, 2, 3, 4]] },
+        layout: { nodeIndex: [0], bounds: [[10, 20, 120, 40]], styles: [styles] },
+      },
+      strings,
+    );
+    expect(nodes[0].attrs).toEqual({ "aria-hidden": "true", inert: "" });
+    expect(nodes[0].layout).toEqual({
+      boundsSpace: "snapshot-document-layout",
+      bounds: [10, 20, 120, 40],
+      styles: {
+        position: "static",
+        "pointer-events": "auto",
+        cursor: "auto",
+        visibility: "visible",
+        opacity: "0",
+      },
+    });
+    expect(nodes[0]).not.toHaveProperty("rect");
+    expect(nodes[0]).not.toHaveProperty("excluded");
+  });
+
+  it("keeps short blocks synchronous and checks cancellation after yielding", async () => {
+    const clock = vi.spyOn(performance, "now").mockReturnValue(0);
+    try {
+      const controller = new AbortController();
+      const checkpoint = createCaptureCheckpoint(controller.signal);
+      for (let i = 0; i < 20; i++) expect(checkpoint()).toBeUndefined();
+      clock.mockReturnValue(9);
+      const pending = checkpoint();
+      expect(pending).toBeInstanceOf(Promise);
+      controller.abort();
+      await expect(pending).rejects.toMatchObject({ name: "AbortError" });
+    } finally {
+      clock.mockRestore();
+    }
+  });
+
+  it("checks cancellation at bounded indexing blocks", async () => {
+    const controller = new AbortController();
+    const input = Array.from({ length: 100_000 }, (_, i) => node(i, i ? i - 1 : null));
+    let reads = 0;
+    for (const item of input)
+      Object.defineProperty(item, "attrs", {
+        get: () => {
+          reads++;
+          if (reads === 100) controller.abort();
+          return {};
+        },
+      });
+    await expect(buildDocumentIndex(input, controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(reads).toBeLessThanOrEqual(356);
+  });
+});
+
+describe("visual ancestry facts", () => {
+  it("distinguishes document roots, malformed roots, missing parents and cycles", async () => {
+    const input = [
+      { ...node(0, null), nodeType: 9 },
+      { ...node(1, 0), nodeType: 1 },
+      { ...node(2, 1), nodeType: 11 },
+      node(3, 2),
+      node(4, 99),
+      node(5, 6),
+      node(6, 5),
+      node(7, 5),
+      { ...node(8, null), nodeType: 1 },
+      { ...node(9, null), nodeType: 9, parentMissing: true },
+    ];
+    const index = await buildDocumentIndex(input.reverse(), undefined, true);
+    for (const id of [0, 1, 2, 3]) expect(index.ancestryComplete!.get(id)).toBe(true);
+    for (const id of [4, 5, 6, 7, 8, 9]) expect(index.ancestryComplete!.get(id)).toBe(false);
+  });
+
+  it("retains client offsets in their source units and does not disguise missing parent indices", async () => {
+    const decoded = await decodeDocument(
+      {
+        nodes: { backendNodeId: [1, 2], nodeType: [1, 1], nodeName: [0, 0], parentIndex: [99] },
+        layout: {
+          nodeIndex: [0],
+          bounds: [[745, 455.625, 97, 59.5]],
+          clientRects: [[5, 5, 68, 38]],
+        },
+      },
+      ["div"],
+      undefined,
+      VISUAL_SNAPSHOT,
+    );
+    expect(decoded.nodes[0].layout?.clientRect).toEqual([5, 5, 68, 38]);
+    expect(decoded.nodes[0].layout?.bounds).toEqual([745, 455.625, 97, 59.5]);
+    expect(decoded.nodes.every((node) => node.parentMissing)).toBe(true);
+    const index = await buildDocumentIndex(decoded.nodes, undefined, true);
+    expect([...index.ancestryComplete!.values()]).toEqual([false, false]);
+  });
+});

apps/extension/src/tools/vom/__tests__/form-state.test.ts

@@ -0,0 +1,298 @@
+import { describe, expect, it, vi } from "vitest";
+import { type CdpRunner, cdpRunnerForTarget } from "../../shared";
+import { enrichFormControlStates } from "../form-capture";
+import { decodeDocument } from "../snapshot";
+
+interface Control {
+  id: number;
+  value: string;
+  type?: string;
+}
+
+function snapshot(groups: Control[][]) {
+  const strings: string[] = [];
+  const str = (value: string) => {
+    let index = strings.indexOf(value);
+    if (index < 0) index = strings.push(value) - 1;
+    return index;
+  };
+  const documents = groups.map((controls, groupIndex) => ({
+    frameId: `frame-${groupIndex}`,
+    nodes: {
+      parentIndex: [-1, 0, ...controls.map(() => 1)],
+      nodeName: [str("html"), str("body"), ...controls.map(() => str("input"))],
+      backendNodeId: [8000 + groupIndex * 2, 8001 + groupIndex * 2, ...controls.map((c) => c.id)],
+      attributes: [
+        [],
+        [],
+        ...controls.map((c) => [
+          str("type"),
+          str(c.type ?? "text"),
+          str("placeholder"),
+          str("snapshot placeholder"),
+        ]),
+      ],
+      inputValue: {
+        index: controls.map((_, i) => i + 2),
+        value: controls.map((c) => str(c.value)),
+      },
+      contentDocumentIndex: { index: [] as number[], value: [] as number[] },
+    },
+  }));
+  const root = documents[0].nodes;
+  for (let i = 1; i < documents.length; i++) {
+    root.contentDocumentIndex.index.push(root.backendNodeId.length);
+    root.contentDocumentIndex.value.push(i);
+    root.parentIndex.push(1);
+    root.nodeName.push(str("iframe"));
+    root.backendNodeId.push(9000 + i);
+    root.attributes.push([]);
+  }
+  return { strings, documents };
+}
+
+function state(value: string) {
+  return {
+    value,
+    defaultValue: "",
+    placeholder: "live placeholder",
+    state: value ? "filled" : "empty",
+    sensitive: false,
+  };
+}
+
+function reply(entries: Array<[number, unknown]>) {
+  return {
+    result: {
+      deepSerializedValue: {
+        type: "array",
+        value: entries.map(([backendNodeId, fields]) => ({
+          type: "array",
+          value: [
+            { type: "node", value: { backendNodeId } },
+            { type: "string", value: JSON.stringify(fields) },
+          ],
+        })),
+      },
+    },
+  };
+}
+
+async function fakeCdp(
+  groups: Control[][],
+  evaluate: (params: Record<string, unknown>) => unknown,
+) {
+  const snap = snapshot(groups);
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    if (method === "Runtime.evaluate") return evaluate(params as Record<string, unknown>);
+    return {};
+  });
+  const nodes = await decodeControls(snap);
+  return { send, cdp: { send: send as CdpRunner["send"] }, nodes };
+}
+
+async function decodeControls(snap: ReturnType<typeof snapshot>) {
+  return Promise.all(
+    snap.documents.map(async (doc) =>
+      (await decodeDocument(doc, snap.strings)).nodes.map((node) => ({ ...node, rect: null })),
+    ),
+  );
+}
+
+describe("form state identity", () => {
+  it("matches reordered controls by identity and preserves controls missing from the batch", async () => {
+    // The snapshot includes a shadow input. The runtime query skips it,
+    // encounters a new input, and sees the remaining inputs in a new order.
+    const { cdp, nodes } = await fakeCdp(
+      [
+        [
+          { id: 10, value: "" },
+          { id: 11, value: "old email" },
+          { id: 12, value: "old city" },
+        ],
+      ],
+      () =>
+        reply([
+          [99, state("new control")],
+          [12, state("上海")],
+          [11, state("alice@example.com")],
+        ]),
+    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 10)).toMatchObject({
+      formValue: "",
+      formState: "empty",
+      formPlaceholder: "snapshot placeholder",
+    });
+    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
+      formValue: "alice@example.com",
+    });
+    expect(nodes[0].find((n) => n.backendNodeId === 12)).toMatchObject({ formValue: "上海" });
+    expect(nodes[0].some((n) => n.backendNodeId === 99)).toBe(false);
+  });
+
+  it("does not shift state between frames when one frame is absent from the runtime batch", async () => {
+    const { cdp, nodes } = await fakeCdp(
+      [
+        [],
+        [{ id: 11, value: "inaccessible frame" }],
+        [{ id: 21, value: "old second" }],
+        [{ id: 31, value: "old third" }],
+      ],
+      () =>
+        reply([
+          [31, state("third frame")],
+          [21, state("second frame")],
+        ]),
+    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    const controls = nodes.slice(1).flat();
+    expect(controls.find((n) => n.backendNodeId === 11)?.formValue).toBe("inaccessible frame");
+    expect(controls.find((n) => n.backendNodeId === 21)?.formValue).toBe("second frame");
+    expect(controls.find((n) => n.backendNodeId === 31)?.formValue).toBe("third frame");
+  });
+
+  it("keeps identical backend ids in different OOPIF targets separate", async () => {
+    const sendToTarget = vi.fn(async (target, method) => {
+      if (method === "Runtime.evaluate") return reply([[11, state(target.sessionId)]]);
+      return {};
+    });
+    const send = vi.fn(async () => {
+      throw new Error("unexpected top-level target");
+    });
+    const cdp = { send, sendToTarget } as unknown as CdpRunner;
+    for (const sessionId of ["left-frame", "right-frame"]) {
+      const nodes = await decodeControls(snapshot([[{ id: 11, value: "old" }]]));
+      await enrichFormControlStates(cdpRunnerForTarget(cdp, { tabId: 7, sessionId }), 7, nodes);
+      expect(nodes[0].find((n) => n.backendNodeId === 11)?.formValue).toBe(sessionId);
+      expect(sendToTarget).toHaveBeenCalledWith(
+        { tabId: 7, sessionId },
+        "Runtime.releaseObjectGroup",
+        expect.anything(),
+      );
+    }
+    expect(send).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    "unsupported",
+    "legacy",
+    "malformed",
+    "invalid-state",
+  ])("preserves snapshot data when enrichment is %s", async (mode) => {
+    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "snapshot value" }]], () => {
+      if (mode === "unsupported") throw new Error("serialization unsupported");
+      if (mode === "legacy") return { result: { value: { controls: [state("wrong value")] } } };
+      const result = reply([
+        [11, mode === "invalid-state" ? { value: "wrong value" } : state("wrong value")],
+      ]);
+      if (mode === "malformed")
+        result.result.deepSerializedValue.value[0].value[1].value = "not json";
+      return result;
+    });
+    expect(await enrichFormControlStates(cdp, 7, nodes)).toBe(mode !== "unsupported");
+    expect(nodes[0].find((n) => n.backendNodeId === 11)).toMatchObject({
+      formValue: "snapshot value",
+      formPlaceholder: "snapshot placeholder",
+    });
+    expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
+  it("releases the batch's remote objects when capture is cancelled", async () => {
+    const controller = new AbortController();
+    const { cdp, send, nodes } = await fakeCdp([[{ id: 11, value: "old" }]], () => {
+      controller.abort();
+      return reply([[11, state("new")]]);
+    });
+    await expect(enrichFormControlStates(cdp, 7, nodes, controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
+  it("does not report success when cancelled during object cleanup", async () => {
+    const controller = new AbortController();
+    const nodes = await decodeControls(snapshot([[{ id: 11, value: "old" }]]));
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method) => {
+        if (method === "Runtime.evaluate") return reply([[11, state("new")]]);
+        if (method === "Runtime.releaseObjectGroup") controller.abort();
+        return {};
+      }) as CdpRunner["send"],
+    };
+    await expect(enrichFormControlStates(cdp, 7, nodes, controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+    expect(cdp.send).toHaveBeenCalledWith(7, "Runtime.releaseObjectGroup", expect.anything());
+  });
+
+  it("skips entries without node identity while still applying valid entries", async () => {
+    const { cdp, nodes } = await fakeCdp(
+      [
+        [
+          { id: 11, value: "snapshot value" },
+          { id: 12, value: "old value" },
+        ],
+      ],
+      () => {
+        const result = reply([
+          [11, state("wrong value")],
+          [12, state("live value")],
+        ]);
+        const element = result.result.deepSerializedValue.value[0].value[0];
+        delete (element.value as { backendNodeId?: number }).backendNodeId;
+        return result;
+      },
+    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 11)?.formValue).toBe("snapshot value");
+    expect(nodes[0].find((n) => n.backendNodeId === 12)?.formValue).toBe("live value");
+  });
+
+  it.each([
+    "password",
+    "text",
+  ])("redacts a sensitive %s control after identity matching", async (type) => {
+    const { cdp, nodes } = await fakeCdp([[{ id: 11, value: "secret", type }]], () =>
+      reply([[11, { ...state("secret"), sensitive: true }]]),
+    );
+    await enrichFormControlStates(cdp, 7, nodes);
+    const control = nodes[0].find((n) => n.backendNodeId === 11);
+    expect(control?.formState).toBe("filled");
+    expect(control?.formValue).toBeUndefined();
+    expect(control?.formDefaultValue).toBeUndefined();
+    expect(control?.attrs.value).toBeUndefined();
+  });
+
+  it("keeps one bounded batch without per-control CDP queries", async () => {
+    const controls = Array.from({ length: 251 }, (_, i) => ({ id: i + 1, value: "old" }));
+    const elements = controls.map((c) => ({
+      backendNodeId: c.id,
+      tagName: "INPUT",
+      type: "text",
+      value: `live ${c.id}`,
+      defaultValue: "",
+      placeholder: "",
+    }));
+    const { cdp, send, nodes } = await fakeCdp([controls], (params) => {
+      const doc = {
+        querySelectorAll: (selector: string) =>
+          selector === "input,textarea,select" ? elements : [],
+      };
+      const entries = new Function("document", `return ${params.expression}`)(doc) as Array<
+        [{ backendNodeId: number }, string]
+      >;
+      expect(entries).toHaveLength(250);
+      return reply(entries.map(([element, json]) => [element.backendNodeId, JSON.parse(json)]));
+    });
+    await enrichFormControlStates(cdp, 7, nodes);
+    expect(nodes[0].find((n) => n.backendNodeId === 250)?.formValue).toBe("live 250");
+    expect(nodes[0].find((n) => n.backendNodeId === 251)?.formValue).toBe("old");
+    expect(send.mock.calls.filter(([, method]) => method === "Runtime.evaluate")).toHaveLength(1);
+    expect(
+      send.mock.calls.filter(([, method]) => method === "Runtime.releaseObjectGroup"),
+    ).toHaveLength(1);
+    expect(send).not.toHaveBeenCalledWith(7, "DOM.resolveNode", expect.anything());
+    expect(send).not.toHaveBeenCalledWith(7, "Runtime.callFunctionOn", expect.anything());
+  });
+});

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

@@ -1,198 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpRunner } from "../../shared";
-import type { CapturedNode, CapturedViewModel } from "../capture";
-import { captureFrameData } from "../frame-capture";
-
-function ownerNode(backendNodeId: number, x: number): CapturedNode {
-  return {
-    backendNodeId,
-    parentBackendNodeId: 1,
-    frameId: "main",
-    ownerFrameBackendNodeId: null,
-    tag: "iframe",
-    attrs: {},
-    rect: { x, y: 100, w: 300, h: 200 },
-    localRect: { x, y: 100, w: 300, h: 200 },
-    paintOrder: 1,
-    position: "static",
-    pointerEvents: "auto",
-  };
-}
-
-function childSnapshot(frameId: string, backendNodeId: number) {
-  const strings = [frameId, "body", "button", "static", "auto", "pointer"];
-  return {
-    strings,
-    documents: [
-      {
-        frameId,
-        nodes: {
-          parentIndex: [-1, 0],
-          nodeName: [1, 2],
-          backendNodeId: [backendNodeId - 1, backendNodeId],
-          attributes: [[], []],
-        },
-        layout: {
-          nodeIndex: [0, 1],
-          styles: [
-            [3, 4, 4],
-            [3, 4, 5],
-          ],
-          bounds: [
-            [0, 0, 300, 200],
-            [10, 20, 100, 40],
-          ],
-          paintOrders: [0, 1],
-        },
-      },
-    ],
-  };
-}
-
-describe("captureFrameData", () => {
-  it("captures and positions multiple OOPIF documents missing from the root snapshot", async () => {
-    const leftOwner = ownerNode(10, 50);
-    const rightOwner = ownerNode(20, 500);
-    const captured: CapturedViewModel = {
-      nodes: [leftOwner, rightOwner],
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      frameNodes: new Map([["main", [leftOwner, rightOwner]]]),
-      frameOwnerBackendNodeIds: new Map(),
-      rootFrameId: "main",
-      excludedBackendNodeIds: new Set(),
-    };
-    const sendToTarget = vi.fn(async (target, method) => {
-      if (method === "Page.getLayoutMetrics") {
-        return { cssLayoutViewport: { clientWidth: 300, clientHeight: 200, pageX: 0, pageY: 0 } };
-      }
-      if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
-      if (method === "DOMSnapshot.captureSnapshot") {
-        return target.sessionId === "left-session"
-          ? childSnapshot("left", 101)
-          : childSnapshot("right", 201);
-      }
-      if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-      throw new Error(`unexpected ${method}`);
-    });
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method, params) => {
-        if (method === "Accessibility.enable") return {};
-        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-        if (method === "DOM.getBoxModel") {
-          const backendNodeId = (params as { backendNodeId?: number })?.backendNodeId;
-          const x = backendNodeId === 10 ? 50 : 500;
-          return { model: { content: [x, 100, x + 300, 100, x + 300, 300, x, 300] } };
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-        }
-        throw new Error(`unexpected root ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: sendToTarget as unknown as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "left",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "left-session" },
-          },
-          {
-            frameId: "right",
-            parentFrameId: "main",
-            ownerBackendNodeId: 20,
-            target: { tabId: 4, sessionId: "right-session" },
-          },
-        ],
-      })),
-    };
-
-    const trees = await captureFrameData(cdp, 4, captured);
-
-    expect(trees.map((tree) => tree.frameId)).toEqual(["main", "left", "right"]);
-    expect(
-      captured.frameNodes?.get("left")?.find((node) => node.backendNodeId === 101)?.rect,
-    ).toEqual({ x: 60, y: 120, w: 100, h: 40 });
-    expect(
-      captured.frameNodes?.get("right")?.find((node) => node.backendNodeId === 201)?.rect,
-    ).toEqual({ x: 510, y: 120, w: 100, h: 40 });
-    expect(captured.frameOwnerBackendNodeIds).toEqual(
-      new Map([
-        ["left", 10],
-        ["right", 20],
-      ]),
-    );
-    expect(captured.frameParentIds).toEqual(
-      new Map([
-        ["left", "main"],
-        ["right", "main"],
-      ]),
-    );
-  });
-
-  it("keeps OOPIF semantics when viewport projection is unavailable", async () => {
-    const owner = { ...ownerNode(10, 50), rect: null, localRect: null };
-    const captured: CapturedViewModel = {
-      nodes: [owner],
-      viewport: { width: 1000, height: 800 },
-      iframeNodes: new Map(),
-      frameNodes: new Map([["main", [owner]]]),
-      rootFrameId: "main",
-      excludedBackendNodeIds: new Set(),
-    };
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId, method) => {
-        if (method === "Accessibility.enable") return {};
-        if (method === "Accessibility.getFullAXTree") return { nodes: [] };
-        if (method === "DOM.getBoxModel") throw new Error("owner geometry unavailable");
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 1000, clientHeight: 800 } };
-        }
-        throw new Error(`unexpected root ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "Page.getLayoutMetrics") throw new Error("viewport unavailable");
-        if (method === "DOMSnapshot.enable" || method === "Accessibility.enable") return {};
-        if (method === "DOMSnapshot.captureSnapshot") return childSnapshot("child", 101);
-        if (method === "Accessibility.getFullAXTree") {
-          return {
-            nodes: [
-              {
-                nodeId: "button",
-                backendDOMNodeId: 101,
-                role: { type: "role", value: "button" },
-                name: { type: "computedString", value: "Continue" },
-              },
-            ],
-          };
-        }
-        throw new Error(`unexpected ${method}`);
-      }) as unknown as NonNullable<CdpRunner["sendToTarget"]>,
-      getFrameGraph: vi.fn(async () => ({
-        rootFrameId: "main",
-        frames: [
-          { frameId: "main", target: { tabId: 4 } },
-          {
-            frameId: "child",
-            parentFrameId: "main",
-            ownerBackendNodeId: 10,
-            target: { tabId: 4, sessionId: "child-session" },
-          },
-        ],
-      })),
-    };
-
-    const documents = await captureFrameData(cdp, 4, captured);
-    const childDocument = documents.find((document) => document.frameId === "child");
-
-    expect(childDocument?.axNodes).toEqual([
-      expect.objectContaining({ backendDOMNodeId: 101, frameId: "child" }),
-    ]);
-    expect(childDocument?.domNodes.find((node) => node.backendNodeId === 101)).toEqual(
-      expect.objectContaining({ rect: null, localRect: { x: 10, y: 20, w: 100, h: 40 } }),
-    );
-  });
-});

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

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

apps/extension/src/tools/vom/__tests__/visual-dedup.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "vitest";
+import { deduplicateVisualCandidates, MAX_VISUAL_DEDUP_KEYS } from "../visual-dedup";
+import type { VisualCandidate, VisualDiscoveryResult } from "../visual-discovery";
+
+function candidate(id: number, width = 100, parent = 1): VisualCandidate {
+  const crop = { x: 0, y: 0, width, height: 100 };
+  return {
+    document: {
+      attachmentId: "a",
+      target: { tabId: 1 },
+      frameId: "main",
+      documentElementBackendNodeId: 1,
+    },
+    backendNodeId: id,
+    parentBackendNodeId: parent,
+    region: { status: "available", borderBox: crop, crop },
+  };
+}
+function discovery(candidates: VisualCandidate[]): VisualDiscoveryResult {
+  return { candidates, complete: true, issues: [], captureIssues: [] };
+}
+
+describe("visual candidate deduplication", () => {
+  it("preserves small, unnamed and labelled candidates and their original evidence", async () => {
+    const small = { ...candidate(3, 1), label: '  A "label"\n😀' };
+    const large = candidate(2, 1000);
+    const input = discovery([small, large]);
+    Object.freeze(input.candidates);
+    Object.freeze(small);
+    Object.freeze(large);
+    for (let i = 0; i < 2; i++) {
+      const result = await deduplicateVisualCandidates(input);
+      expect(result.candidates).toEqual([small, large]);
+      expect(result.candidates[0]).toBe(small);
+      expect(result.candidates[1]).toBe(large);
+      expect(result).toMatchObject({
+        candidateCount: 2,
+        deduplicatedCount: 0,
+        dedupDegraded: false,
+      });
+    }
+  });
+
+  it("only deduplicates exact crops within the same full DOM identity and direct parent", async () => {
+    const base = candidate(20);
+    const variants = [
+      candidate(30, 100, 2),
+      { ...candidate(40), parentBackendNodeId: null },
+      ...["x", "y", "width", "height"].map((axis) => ({
+        ...base,
+        region: {
+          ...base.region,
+          crop: {
+            ...base.region.crop,
+            [axis]: base.region.crop[axis as keyof typeof base.region.crop] + 0.001,
+          },
+        },
+      })),
+      ...[
+        { frameId: "child" },
+        { target: { tabId: 2 } },
+        { target: { tabId: 1, sessionId: "remote" } },
+        { documentElementBackendNodeId: 9 },
+        { attachmentId: "b" },
+      ].map((identity) => ({ ...base, document: { ...base.document, ...identity } })),
+    ];
+    const duplicate = { ...candidate(10), label: "Not a new target" };
+    const result = await deduplicateVisualCandidates(discovery([base, ...variants, duplicate]));
+    expect(result.candidates).toEqual([base, ...variants]);
+    expect(result.candidates[0]).toBe(base);
+    expect(result.deduplicatedCount).toBe(1);
+  });
+
+  it.each([
+    50_001, 100_000,
+  ])("keeps all %s distinct candidates including the last tiny Canvas", async (count) => {
+    const input = Array.from({ length: count }, (_, i) => candidate(i + 1, 100, i + 1));
+    input[count - 1] = candidate(count, 1, count);
+    // A remembered key still deduplicates; an unremembered key passes through.
+    input.push({ ...input[0] }, { ...input[count - 1] });
+    const result = await deduplicateVisualCandidates(discovery(input));
+    expect(result.candidates).toEqual([...input.slice(0, count), input[count + 1]]);
+    expect(result.candidates[count - 1]).toBe(input[count - 1]);
+    expect(result).toMatchObject({
+      candidateCount: count + 2,
+      deduplicatedCount: 1,
+      dedupDegraded: true,
+    });
+  });
+
+  it("does not report degradation when every key fits", async () => {
+    const input = Array.from({ length: MAX_VISUAL_DEDUP_KEYS }, (_, i) => candidate(i, 1, i));
+    input.push({ ...input[0] });
+    const result = await deduplicateVisualCandidates(discovery(input));
+    expect(result.candidates).toHaveLength(MAX_VISUAL_DEDUP_KEYS);
+    expect(result.dedupDegraded).toBe(false);
+    expect(result.deduplicatedCount).toBe(1);
+  });
+
+  it("preserves upstream unknowns without counting issues as Canvas nodes", async () => {
+    const input: VisualDiscoveryResult = {
+      ...discovery([candidate(2)]),
+      complete: false,
+      issues: [{ reason: "geometry-unavailable", target: { tabId: 1 }, frameId: "missing" }],
+      captureIssues: [{ stage: "ax", reason: "capture-unavailable", target: { tabId: 1 } }],
+    };
+    const result = await deduplicateVisualCandidates(input);
+    expect(result.complete).toBe(false);
+    expect(result.candidateCount).toBe(1);
+    expect(result.issues).toBe(input.issues);
+    expect(result.captureIssues).toBe(input.captureIssues);
+    const absent = await deduplicateVisualCandidates({
+      ...input,
+      candidates: [],
+      issues: [{ reason: "visual-facts-not-collected" }],
+    });
+    expect(absent).toMatchObject({
+      complete: false,
+      candidateCount: 0,
+      issues: [{ reason: "visual-facts-not-collected" }],
+    });
+    expect(await deduplicateVisualCandidates(discovery([]))).toMatchObject({
+      complete: true,
+      candidates: [],
+      candidateCount: 0,
+      dedupDegraded: false,
+    });
+  });
+
+  it("drains cancellation through the shared checkpoint", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      deduplicateVisualCandidates(discovery([]), controller.signal),
+    ).rejects.toMatchObject({ name: "AbortError" });
+    const during = new AbortController();
+    const input = discovery(Array.from({ length: 100_000 }, (_, i) => candidate(i, 100, i)));
+    const timer = setTimeout(() => during.abort(), 0);
+    try {
+      await expect(deduplicateVisualCandidates(input, during.signal)).rejects.toMatchObject({
+        name: "AbortError",
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+  });
+});

apps/extension/src/tools/vom/__tests__/visual-discovery.test.ts

@@ -0,0 +1,502 @@
+import { describe, expect, it } from "vitest";
+import type { CdpFrame } from "@/browser-driver/frame-graph";
+import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import type { GeometryProjection } from "../../geometry";
+import { buildDocumentIndex, type DocumentFacts, type ObservationFacts } from "../facts";
+import type { FrameOwnedAxNode } from "../frame-document";
+import { normalizeDocument } from "../normalize";
+import { VISUAL_SNAPSHOT, VISUAL_STYLES } from "../snapshot";
+import { discoverVisualCandidates } from "../visual-discovery";
+
+const defaults: Record<string, string> = {
+  position: "static",
+  "pointer-events": "auto",
+  cursor: "auto",
+  visibility: "visible",
+  opacity: "1",
+  display: "block",
+  "overflow-x": "visible",
+  "overflow-y": "visible",
+  transform: "none",
+  zoom: "1",
+  "clip-path": "none",
+  "mask-image": "none",
+  rotate: "none",
+  scale: "none",
+  perspective: "none",
+  clip: "auto",
+  contain: "none",
+  "overflow-clip-margin": "0px",
+};
+const projection: GeometryProjection = {
+  sourceClips: [],
+  edges: [],
+  topViewport: { width: 1000, height: 800 },
+};
+interface Spec {
+  id: number;
+  parent?: number;
+  tag?: string;
+  styles?: Record<string, string>;
+  bounds?: number[] | null;
+  client?: number[];
+  attrs?: Record<string, string>;
+}
+async function document(
+  nodes: Spec[],
+  options: {
+    frame?: CdpFrame;
+    projection?: GeometryProjection;
+    pageScale?: number;
+    scrollY?: number;
+    layoutScale?: number;
+  } = {},
+): Promise<DocumentFacts<FrameOwnedAxNode>> {
+  const frame = options.frame ?? { frameId: "main", target: { tabId: 1 } };
+  const strings: string[] = [];
+  const str = (value: string) => {
+    const index = strings.indexOf(value);
+    if (index >= 0) return index;
+    strings.push(value);
+    return strings.length - 1;
+  };
+  const input: Spec[] = [
+    { id: 0, tag: "#document", bounds: null },
+    { id: 1, parent: 0, tag: "html", bounds: [0, 0, 1000, 800] },
+    ...nodes,
+  ];
+  const layouts = input.filter((node) => node.bounds !== null);
+  const normalized = await normalizeDocument(
+    {
+      nodes: {
+        backendNodeId: input.map((n) => n.id),
+        nodeType: input.map((n) =>
+          n.tag === "#document" ? 9 : n.tag === "#document-fragment" ? 11 : 1,
+        ),
+        parentIndex: input.map((n) =>
+          n.parent === undefined ? -1 : input.findIndex((p) => p.id === n.parent),
+        ),
+        nodeName: input.map((n) => str(n.tag ?? "canvas")),
+        attributes: input.map((n) =>
+          Object.entries(n.attrs ?? {}).flatMap(([k, v]) => [str(k), str(v)]),
+        ),
+      },
+      layout: {
+        nodeIndex: layouts.map((n) => input.indexOf(n)),
+        bounds: layouts.map((n) => n.bounds ?? [10, 20, 120, 40]),
+        clientRects: layouts.map((n) => n.client ?? [0, 0, 1000, 800]),
+        styles: layouts.map((n) =>
+          VISUAL_STYLES.map((key) => str({ ...defaults, ...n.styles }[key])),
+        ),
+      },
+    },
+    strings,
+    {
+      frameId: frame.frameId,
+      ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
+      target: frame.target,
+      projection: {
+        status: "available",
+        projection: {
+          source: { target: frame.target, frameId: frame.frameId },
+          geometry: options.projection ?? projection,
+        },
+      },
+      coordinates: {
+        layoutUnitsPerCssPixel: options.layoutScale ?? 1,
+        scrollCss: { x: 0, y: options.scrollY ?? 0 },
+      },
+      pageScale: options.pageScale ?? 1,
+    },
+    undefined,
+    VISUAL_SNAPSHOT,
+  );
+  return {
+    frame,
+    identity: {
+      attachmentId: "attached",
+      target: frame.target,
+      frameId: frame.frameId,
+      documentElementBackendNodeId: 1,
+    },
+    index: normalized.index,
+    geometry: normalized.geometry,
+    domNodes: normalized.nodes,
+    axNodes: [],
+  };
+}
+function facts(
+  documents: DocumentFacts<FrameOwnedAxNode>[],
+  issues: ObservationFacts<FrameOwnedAxNode>["issues"] = [],
+): ObservationFacts<FrameOwnedAxNode> {
+  return {
+    visualFactsCollected: true,
+    rootFrameId: "main",
+    documents,
+    viewport: { width: 1000, height: 800 },
+    issues,
+    startedAt: 1,
+    finishedAt: 2,
+  };
+}
+
+describe("Canvas discovery", () => {
+  it("distinguishes visual facts not collected from complete empty discovery and honors cancellation", async () => {
+    const empty = facts([]);
+    expect(await discoverVisualCandidates(empty)).toMatchObject({
+      complete: true,
+      candidates: [],
+      issues: [],
+    });
+    expect(await discoverVisualCandidates({ ...empty, visualFactsCollected: false })).toMatchObject(
+      { complete: false, candidates: [], issues: [{ reason: "visual-facts-not-collected" }] },
+    );
+    const controller = new AbortController();
+    controller.abort();
+    await expect(
+      discoverVisualCandidates({ ...empty, visualFactsCollected: false }, controller.signal),
+    ).rejects.toMatchObject({ name: "AbortError" });
+  });
+
+  it("discovers Canvas and frame contents without corner radius facts", async () => {
+    const own = await document([{ id: 2, parent: 1, styles: {} }]);
+    expect(await discoverVisualCandidates(facts([own]))).toMatchObject({
+      candidates: [{ backendNodeId: 2 }],
+      complete: true,
+      issues: [],
+    });
+    const parent = await document([{ id: 2, parent: 1, tag: "iframe", styles: {} }]);
+    const child = await document([{ id: 3, parent: 1 }], {
+      frame: {
+        frameId: "child",
+        parentFrameId: "main",
+        ownerBackendNodeId: 2,
+        target: { tabId: 1 },
+      },
+    });
+    expect(await discoverVisualCandidates(facts([parent, child]))).toMatchObject({
+      candidates: [{ backendNodeId: 3 }],
+      complete: true,
+      issues: [],
+    });
+  });
+
+  it.each([
+    0.8, 1, 1.25, 2,
+  ])("combines layout-unit bounds with CSS client clips at scale %s", async (scale) => {
+    const doc = await document(
+      [
+        {
+          id: 2,
+          parent: 1,
+          tag: "div",
+          bounds: [100, 200, 64, 34].map((n) => n * scale),
+          client: [2, 2, 60, 30],
+          styles: { "overflow-x": "hidden", "overflow-y": "hidden" },
+        },
+        { id: 3, parent: 2, bounds: [102, 202, 120, 40].map((n) => n * scale) },
+      ],
+      { layoutScale: scale, scrollY: 75 },
+    );
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.issues).toEqual([]);
+    const expected = {
+      borderBox: { x: 102, y: 127, width: 120, height: 40 },
+      crop: { x: 102, y: 127, width: 60, height: 30 },
+    };
+    for (const box of ["borderBox", "crop"] as const)
+      for (const key of ["x", "y", "width", "height"] as const)
+        expect(result.candidates[0].region[box][key]).toBeCloseTo(expected[box][key], 8);
+  });
+
+  it("normalizes a zero-width ancestor origin before one-axis clipping", async () => {
+    const doc = await document(
+      [
+        {
+          id: 2,
+          parent: 1,
+          tag: "div",
+          bounds: [200, 400, 0, 60],
+          client: [0, 0, 0, 30],
+          styles: { "overflow-y": "hidden" },
+        },
+        { id: 3, parent: 2, bounds: [200, 400, 240, 80] },
+      ],
+      { layoutScale: 2, scrollY: 75 },
+    );
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.issues).toEqual([]);
+    expect(result.candidates[0].region.crop).toEqual({ x: 100, y: 125, width: 120, height: 30 });
+  });
+
+  it("keeps unnamed, semantic, aria-hidden, inert, pointer-none and visibility override Canvas", async () => {
+    const doc = await document([
+      { id: 2, parent: 1 },
+      { id: 3, parent: 1, attrs: { "aria-label": "Chart" } },
+      {
+        id: 4,
+        parent: 1,
+        attrs: { "aria-hidden": "true", inert: "" },
+        styles: { "pointer-events": "none" },
+      },
+      { id: 5, parent: 1, tag: "div", styles: { visibility: "hidden" } },
+      { id: 6, parent: 5, styles: { visibility: "visible" } },
+      { id: 7, parent: 1, attrs: { hidden: "" }, styles: { display: "block" } },
+    ]);
+    doc.axNodes.push({ nodeId: "canvas", backendDOMNodeId: 2 } as FrameOwnedAxNode);
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.candidates.map((c) => c.backendNodeId)).toEqual([2, 3, 4, 6, 7]);
+    expect(result.candidates[1].label).toBe("Chart");
+    expect(result.complete).toBe(true);
+  });
+
+  it("excludes CSS transparent subtrees, hidden/zero/no-layout/fully clipped nodes and overlays", async () => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div", styles: { opacity: "0" } },
+      { id: 3, parent: 2 },
+      { id: 4, parent: 1, styles: { visibility: "hidden" } },
+      { id: 5, parent: 1, bounds: [0, 0, 0, 40] },
+      { id: 6, parent: 1, bounds: null },
+      { id: 7, parent: 1, bounds: [1200, 0, 100, 50] },
+      { id: 8, parent: 1, tag: "div", attrs: { [OVERLAY_HOST_MARKER_ATTR]: "" } },
+      { id: 9, parent: 8, tag: "#document-fragment", bounds: null },
+      { id: 10, parent: 9 },
+    ]);
+    expect(await discoverVisualCandidates(facts([doc]))).toMatchObject({
+      candidates: [],
+      issues: [],
+      complete: true,
+    });
+  });
+
+  it.each([
+    ["both", "hidden", "hidden", [0, 0, 60, 30], [60, 30]],
+    ["x", "clip", "visible", [0, 0, 60, 20], [60, 40]],
+    ["border", "hidden", "hidden", [5, 5, 68, 38], [64, 34]],
+  ])("uses client box for %s clipping", async (_name, x, y, client, expected) => {
+    const doc = await document([
+      {
+        id: 2,
+        parent: 1,
+        tag: "div",
+        bounds: [0, 0, 78, 48],
+        client: client as number[],
+        styles: { "overflow-x": x as string, "overflow-y": y as string },
+      },
+      {
+        id: 3,
+        parent: 2,
+        bounds: x === "clip" || _name === "both" ? [0, 0, 120, 40] : [9, 9, 120, 40],
+      },
+    ]);
+    const [candidate] = (await discoverVisualCandidates(facts([doc]))).candidates;
+    expect([candidate.region.crop.width, candidate.region.crop.height]).toEqual(expected);
+    expect(candidate.region.clips?.backendNodeId).toBe(2);
+  });
+
+  it("keeps Canvas border-box and clips partial viewport intersections", async () => {
+    const doc = await document([{ id: 2, parent: 1, bounds: [950, 20, 130, 50] }]);
+    const [candidate] = (await discoverVisualCandidates(facts([doc]))).candidates;
+    expect(candidate.region.borderBox.width).toBe(130);
+    expect(candidate.region.crop).toEqual({ x: 950, y: 20, width: 50, height: 50 });
+  });
+
+  it("propagates owner ancestry across targets, without depending on semantic parents", async () => {
+    const parent = await document([
+      {
+        id: 2,
+        parent: 1,
+        tag: "div",
+        bounds: [0, 0, 200, 100],
+        client: [0, 0, 200, 100],
+        styles: { "overflow-x": "hidden", "overflow-y": "hidden" },
+      },
+      { id: 3, parent: 2, tag: "iframe", bounds: [100, 0, 200, 200] },
+    ]);
+    parent.domNodes.splice(0); // Visual discovery never reads the semantic subset.
+    const child = await document([{ id: 2, parent: 1, bounds: [0, 0, 200, 200] }], {
+      frame: {
+        frameId: "child",
+        parentFrameId: "main",
+        ownerBackendNodeId: 3,
+        target: { tabId: 1, sessionId: "remote" },
+      },
+      projection: {
+        ...projection,
+        edges: [
+          {
+            sourceViewport: { width: 200, height: 200 },
+            destinationQuad: [
+              { x: 100, y: 0 },
+              { x: 300, y: 0 },
+              { x: 300, y: 200 },
+              { x: 100, y: 200 },
+            ],
+          },
+        ],
+      },
+    });
+    const result = await discoverVisualCandidates(facts([child, parent]));
+    expect(result.complete).toBe(true);
+    expect(result.candidates[0]).toMatchObject({
+      document: { frameId: "child", target: { sessionId: "remote" } },
+      region: { crop: { x: 100, y: 0, width: 100, height: 100 } },
+    });
+    const owner = parent.index.nodes.get(3)!;
+    owner.layout!.styles = { ...owner.layout!.styles, visibility: "hidden" };
+    expect((await discoverVisualCandidates(facts([parent, child]))).candidates).toHaveLength(0);
+  });
+
+  it.each<Record<string, string>>([
+    { transform: "matrix(0,1,-1,0,0,0)" },
+    { "clip-path": "circle(50%)" },
+    { "mask-image": "url(mask)" },
+    { zoom: "1.25", "overflow-x": "hidden" },
+  ])("reports unsupported ancestor geometry: %o", async (styles) => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div", styles },
+      { id: 3, parent: 2 },
+    ]);
+    const result = await discoverVisualCandidates(facts([doc]));
+    expect(result.candidates).toHaveLength(0);
+    expect(result.issues[0].reason).toBe("geometry-unsupported");
+  });
+
+  it("supports positive scale without overflow, rejects pinch and non-rectangular frame projection", async () => {
+    const nodes = [
+      {
+        id: 2,
+        parent: 1,
+        styles: { transform: "matrix(1.25,0,0,1.25,0,0)" },
+        bounds: [10, 20, 150, 50],
+      },
+    ];
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes)]))).candidates,
+    ).toHaveLength(1);
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes, { pageScale: 1.5 })]))).issues[0]
+        .reason,
+    ).toBe("geometry-unsupported");
+    const rotated = {
+      ...projection,
+      edges: [
+        {
+          sourceViewport: { width: 200, height: 200 },
+          destinationQuad: [
+            { x: 10, y: 0 },
+            { x: 200, y: 10 },
+            { x: 190, y: 200 },
+            { x: 0, y: 190 },
+          ] as [
+            { x: number; y: number },
+            { x: number; y: number },
+            { x: number; y: number },
+            { x: number; y: number },
+          ],
+        },
+      ],
+    };
+    expect(
+      (await discoverVisualCandidates(facts([await document(nodes, { projection: rotated })])))
+        .issues[0].reason,
+    ).toBe("geometry-unsupported");
+  });
+
+  it("keeps partial capture separate from valid geometry, rejects unverified identities", async () => {
+    const doc = await document([{ id: 2, parent: 1 }]);
+    const partial = facts(
+      [doc],
+      [{ target: doc.frame.target, frameId: "main", stage: "ax", reason: "capture-unavailable" }],
+    );
+    const result = await discoverVisualCandidates(partial);
+    expect(result.candidates).toHaveLength(1);
+    expect(result.captureIssues).toBe(partial.issues);
+    expect(result.complete).toBe(false);
+    const unverified = { ...doc, identity: undefined };
+    const failed = await discoverVisualCandidates(facts([unverified]));
+    expect(failed.candidates).toHaveLength(0);
+    expect(failed.issues[0].reason).toBe("identity-unverified");
+  });
+
+  it("does not trust orphan, cyclic, boxless or missing frame-owner ancestry", async () => {
+    const doc = await document([
+      { id: 2, parent: 1, tag: "div" },
+      { id: 3, parent: 2 },
+    ]);
+    for (const parent of [99, 3]) {
+      doc.index.nodes.get(2)!.parentBackendNodeId = parent;
+      const index = await buildDocumentIndex([...doc.index.nodes.values()], undefined, true);
+      const result = await discoverVisualCandidates(facts([{ ...doc, index }]));
+      expect(result.candidates).toHaveLength(0);
+      expect(result.issues[0].reason).toBe("ancestry-incomplete");
+    }
+    const boxless = await document([
+      { id: 2, parent: 1, tag: "div", bounds: null },
+      { id: 3, parent: 2 },
+    ]);
+    expect((await discoverVisualCandidates(facts([boxless]))).issues[0].reason).toBe(
+      "facts-unavailable",
+    );
+    const child = {
+      ...doc,
+      frame: { ...doc.frame, frameId: "child", parentFrameId: "absent", ownerBackendNodeId: 2 },
+    };
+    expect((await discoverVisualCandidates(facts([child]))).issues[0].reason).toBe(
+      "ownership-unresolved",
+    );
+  });
+
+  it("is deterministic, does not deduplicate or mutate inputs", async () => {
+    const input = facts([
+      await document([
+        { id: 2, parent: 1 },
+        { id: 3, parent: 1 },
+      ]),
+    ]);
+    const freeze = (value: unknown): void => {
+      if (!value || typeof value !== "object" || Object.isFrozen(value)) return;
+      if (value instanceof Map) for (const item of value.values()) freeze(item);
+      for (const item of Object.values(value)) freeze(item);
+      Object.freeze(value);
+    };
+    freeze(input);
+    const first = await discoverVisualCandidates(input);
+    expect(await discoverVisualCandidates(input)).toEqual(first);
+    expect(first.candidates).toHaveLength(2);
+  });
+
+  it.each([
+    1000, 10000, 100000,
+  ])("memoizes deep ancestry across %i nodes and checks cancellation", async (count) => {
+    const doc = await document([{ id: 2, parent: 1 }]);
+    const template = doc.index.nodes.get(2)!;
+    let reads = 0;
+    const input = [doc.index.nodes.get(0)!, doc.index.nodes.get(1)!];
+    for (let id = 2; id < count + 2; id++) {
+      const node = {
+        ...template,
+        backendNodeId: id,
+        tag: id < count / 2 ? "div" : "canvas",
+        parentBackendNodeId: id < count / 2 ? id - 1 : count / 2 - 1,
+      };
+      Object.defineProperty(node, "parentBackendNodeId", {
+        get: () => {
+          reads++;
+          return id < count / 2 ? id - 1 : count / 2 - 1;
+        },
+      });
+      input.push(node);
+    }
+    const index = await buildDocumentIndex(input, undefined, true);
+    reads = 0;
+    const result = await discoverVisualCandidates(facts([{ ...doc, index }]));
+    expect(result.candidates).toHaveLength(count / 2 + 2);
+    expect(reads).toBeLessThan(count * 5);
+    const controller = new AbortController();
+    controller.abort();
+    await expect(discoverVisualCandidates(facts([doc]), controller.signal)).rejects.toMatchObject({
+      name: "AbortError",
+    });
+  });
+});

apps/extension/src/tools/vom/__tests__/visual-region.test.ts

@@ -0,0 +1,250 @@
+import { describe, expect, it } from "vitest";
+import {
+  EMPTY_VISUAL_CONTEXT,
+  extendVisualContext,
+  projectVisualBox,
+  resolveVisualRegion,
+  type VisualAncestor,
+} from "../visual-region";
+
+const styles = {
+  position: "static",
+  visibility: "visible",
+  opacity: "1",
+  display: "block",
+  transform: "none",
+  zoom: "1",
+  "overflow-x": "visible",
+  "overflow-y": "visible",
+  "clip-path": "none",
+  "mask-image": "none",
+  rotate: "none",
+  scale: "none",
+  perspective: "none",
+  clip: "auto",
+  contain: "none",
+  "overflow-clip-margin": "0px",
+};
+const ancestor: VisualAncestor = {
+  document: {
+    attachmentId: "a",
+    target: { tabId: 1 },
+    frameId: "main",
+    documentElementBackendNodeId: 1,
+  },
+  backendNodeId: 2,
+  styles,
+  clientBox: { x: 5, y: 5, width: 60, height: 30 },
+};
+const box = { x: 0, y: 0, width: 120, height: 40 };
+
+describe("shared visual region rules", () => {
+  it.each([
+    "visible",
+    "hidden",
+    "auto",
+    "scroll",
+    "clip",
+  ])("keeps %s screenshot bounds independent of rounded styling", (overflow) => {
+    for (const clipContents of [true, false]) {
+      const node = {
+        ...ancestor,
+        styles: { ...styles, "overflow-x": overflow, "overflow-y": overflow },
+      };
+      const baseline = extendVisualContext(EMPTY_VISUAL_CONTEXT, node, clipContents);
+      for (const radius of ["0px", "8px", "50%", "4px 8px"]) {
+        const rounded = extendVisualContext(
+          EMPTY_VISUAL_CONTEXT,
+          {
+            ...node,
+            styles: {
+              ...node.styles,
+              "border-top-left-radius": radius,
+              "border-top-right-radius": radius,
+              "border-bottom-left-radius": radius,
+              "border-bottom-right-radius": radius,
+            },
+          },
+          clipContents,
+        );
+        expect(rounded).toEqual(baseline);
+        expect(
+          resolveVisualRegion({
+            borderBox: box,
+            frameVisibleBox: box,
+            visibility: "visible",
+            context: rounded,
+          }),
+        ).toMatchObject({ status: "available" });
+        expect(
+          resolveVisualRegion({
+            borderBox: box,
+            frameVisibleBox: box,
+            visibility: "hidden",
+            context: rounded,
+          }),
+        ).toEqual({ status: "empty" });
+        if (clipContents && overflow !== "visible")
+          expect(
+            resolveVisualRegion({
+              borderBox: box,
+              frameVisibleBox: { x: 80, y: 0, width: 20, height: 20 },
+              visibility: "visible",
+              context: rounded,
+            }),
+          ).toEqual({ status: "empty" });
+      }
+    }
+  });
+
+  it("accepts independently supplied normalized facts and preserves clipping policy", () => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, "overflow-x": "hidden" },
+    });
+    expect(
+      resolveVisualRegion({ borderBox: box, frameVisibleBox: box, visibility: "visible", context }),
+    ).toMatchObject({
+      status: "available",
+      crop: { x: 5, y: 0, width: 60, height: 40 },
+      clips: { overflowX: "hidden", overflowY: "visible" },
+    });
+    const differentPolicy = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, "overflow-x": "scroll" },
+    });
+    expect(differentPolicy.clip).toEqual(context.clip);
+    expect(differentPolicy.clips).not.toEqual(context.clips);
+  });
+
+  it("distinguishes fully clipped, missing client geometry and invalid rectangles", () => {
+    const clipping = { ...ancestor, styles: { ...styles, "overflow-x": "hidden" } };
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...clipping,
+      clientBox: { x: 0, y: 0, width: 0, height: 20 },
+    });
+    expect(
+      resolveVisualRegion({ borderBox: box, frameVisibleBox: box, visibility: "visible", context })
+        .status,
+    ).toBe("empty");
+    const unavailable = extendVisualContext(EMPTY_VISUAL_CONTEXT, { ...clipping, clientBox: null });
+    expect(
+      resolveVisualRegion({
+        borderBox: box,
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: unavailable,
+      }),
+    ).toEqual({ status: "unavailable", reason: "geometry-unavailable" });
+    expect(
+      resolveVisualRegion({
+        borderBox: { ...box, x: NaN },
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: EMPTY_VISUAL_CONTEXT,
+      }).status,
+    ).toBe("unavailable");
+    expect(projectVisualBox({ x: 5, y: 5, width: 0, height: 20 }, [])).toEqual({
+      x: 5,
+      y: 5,
+      width: 0,
+      height: 20,
+    });
+  });
+
+  it.each<Record<string, string>>([
+    { rotate: "45deg" },
+    { scale: "-1 1" },
+    { perspective: "100px" },
+    { clip: "rect(0px, 20px, 20px, 0px)" },
+    { contain: "paint" },
+    { "overflow-x": "clip", "overflow-clip-margin": "10px" },
+    { transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0.01,0,0,0,1)" },
+  ])("refuses unsupported CSS evidence without changing DOM geometry: %o", (change) => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: { ...styles, ...change },
+    });
+    expect(context.issue).toBe("geometry-unsupported");
+  });
+
+  it("accepts axis-preserving matrix3d translation and independent positive scale", () => {
+    for (const change of [
+      { transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,10,20,0,1)" },
+      { scale: "1.25" },
+    ])
+      expect(
+        extendVisualContext(EMPTY_VISUAL_CONTEXT, { ...ancestor, styles: { ...styles, ...change } })
+          .issue,
+      ).toBeUndefined();
+  });
+
+  it.each([
+    "matrix(1,0,0,1,0,0)",
+    "matrix(1,0,0,1,10,20)",
+  ])("accepts unscaled overflow transform %s", (transform) => {
+    const context = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...ancestor,
+      styles: {
+        ...styles,
+        transform,
+        position: "relative",
+        "overflow-x": "hidden",
+        "overflow-y": "hidden",
+      },
+    });
+    expect(context.issue).toBeUndefined();
+    const child = extendVisualContext(
+      context,
+      {
+        ...ancestor,
+        styles: {
+          ...styles,
+          position: "absolute",
+          "overflow-x": "clip",
+          "overflow-y": "clip",
+          "overflow-clip-margin": "content-box",
+        },
+      },
+      false,
+    );
+    expect(
+      resolveVisualRegion({
+        borderBox: box,
+        frameVisibleBox: box,
+        visibility: "visible",
+        context: child,
+      }),
+    ).toMatchObject({ status: "available", crop: { x: 5, y: 5, width: 60, height: 30 } });
+  });
+
+  it("supports positioned overflow containers but refuses uncertain out-of-flow clipping", () => {
+    const overflow = { ...ancestor, styles: { ...styles, "overflow-x": "hidden" } };
+    const staticParent = extendVisualContext(EMPTY_VISUAL_CONTEXT, overflow);
+    expect(
+      extendVisualContext(
+        staticParent,
+        { ...ancestor, styles: { ...styles, position: "absolute" } },
+        false,
+      ).issue,
+    ).toBe("geometry-unsupported");
+    const positionedParent = extendVisualContext(EMPTY_VISUAL_CONTEXT, {
+      ...overflow,
+      styles: { ...overflow.styles, position: "relative" },
+    });
+    const child = extendVisualContext(
+      positionedParent,
+      { ...ancestor, styles: { ...styles, position: "absolute" } },
+      false,
+    );
+    expect(child.issue).toBeUndefined();
+    expect(child.clip).toEqual(positionedParent.clip);
+    expect(
+      extendVisualContext(
+        positionedParent,
+        { ...ancestor, styles: { ...styles, position: "fixed" } },
+        false,
+      ).issue,
+    ).toBe("geometry-unsupported");
+  });
+});

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

@@ -0,0 +1,40 @@
+function captureAbortError(): Error {
+  const error = new Error("observation aborted");
+  error.name = "AbortError";
+  return error;
+}
+
+export function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    (error as { name?: string }).name === "AbortError"
+  );
+}
+
+export function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) throw captureAbortError();
+}
+
+/** Check at bounded work blocks; yield only after a processing slice is spent.
+ * Each caller owns its deadline, so unrelated captures do not share state. */
+export function createCaptureCheckpoint(signal?: AbortSignal): () => Promise<void> | undefined {
+  throwIfAborted(signal);
+  let deadline = performance.now() + 8;
+  return () => {
+    throwIfAborted(signal);
+    if (performance.now() < deadline) return;
+    return new Promise<void>((resolve) => {
+      const channel = new MessageChannel();
+      channel.port1.onmessage = () => {
+        channel.port1.close();
+        channel.port2.close();
+        resolve();
+      };
+      channel.port2.postMessage(null);
+    }).then(() => {
+      throwIfAborted(signal);
+      deadline = performance.now() + 8;
+    });
+  };
+}

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

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

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

@@ -0,0 +1,37 @@
+import type { Rect } from "@browser-skill/vom";
+
+export interface CapturedNode {
+  backendNodeId: number;
+  parentBackendNodeId: number | null;
+  frameId?: string;
+  /** Owning iframe backend node id; `null` for the top-level document. */
+  ownerFrameBackendNodeId?: number | null;
+  tag: string;
+  attrs: Record<string, string>;
+  /** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
+  rect: Rect | null;
+  /** Frame-local viewport-relative CSS px before top-level projection. */
+  localRect?: Rect | null;
+  paintOrder: number;
+  position: string;
+  pointerEvents: string;
+  /**
+   * computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
+   * that a non-semantic element (a `<div>`/`<span>` with a click handler)
+   * is actually an interactive control — used by the adapter to surface
+   * custom buttons/checkboxes the AX tree drops as `generic`. Optional like
+   * `textContent`: the live parser always sets it, hand-built fixtures may not.
+   */
+  cursor?: string;
+  /**
+   * Whether the live DOM snapshot provides a painted, non-hidden box for this
+   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
+   * nodes remain authoritative even when they are outside the viewport.
+   */
+  rendered?: boolean;
+  textContent?: string;
+  formState?: "empty" | "filled" | "default";
+  formValue?: string;
+  formDefaultValue?: string;
+  formPlaceholder?: string;
+}

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

@@ -1,298 +1,19 @@
-// CDP capture adapter: DOMSnapshot.captureSnapshot + Page.getLayoutMetrics
-// → CapturedNode[] + Viewport. This is the ONLY VOM module that touches
-// raw CDP. The captureSnapshot reply is columnar (parallel arrays + a
-// shared string table); requested computed styles are decoded through
-// STYLE_COL so capture and visibility policy share one explicit contract.
-
-import type { Rect, Viewport } from "@browser-skill/vom";
+// Browser-side hover probes and overlay exclusion fallback. Static collection
+// lives in capture-coordinator; snapshot decoding has no browser dependency.
 import { evaluateHoverTrigger } from "@/lib/hover-trigger-policy";
-import { isOverlayHostNode, OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
-import { childFrameProjection, type GeometryProjection, projectRectToViewport } from "../geometry";
+import { OVERLAY_HOST_SELECTOR } from "../../lib/overlay-bridge";
 import type { CdpRunner } from "../shared";
+import type { CapturedNode } from "./capture-types";
+import type { CapturedSurfaceProbe } from "./facts";
+
+export type {
+  CapturedNode,
+  CapturedSurfaceProbe,
+} from "./facts";
+
+import { isAbortError, throwIfAborted } from "./capture-abort";
 import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";
 
-const REQUESTED_STYLES = ["position", "pointer-events", "cursor", "visibility", "opacity"] as const;
-const STYLE_COL = Object.fromEntries(
-  REQUESTED_STYLES.map((name, index) => [name, index]),
-) as Record<(typeof REQUESTED_STYLES)[number], number>;
-
-export interface CapturedNode {
-  backendNodeId: number;
-  parentBackendNodeId: number | null;
-  frameId?: string;
-  /** Owning iframe backend node id; `null` for the top-level document. */
-  ownerFrameBackendNodeId?: number | null;
-  tag: string;
-  attrs: Record<string, string>;
-  /** Top-level viewport-relative CSS px, clipped to the owning frame viewport. */
-  rect: Rect | null;
-  /** Frame-local viewport-relative CSS px before top-level projection. */
-  localRect?: Rect | null;
-  paintOrder: number;
-  position: string;
-  pointerEvents: string;
-  /**
-   * computed `cursor`. `cursor: pointer` is the strongest CDP-free signal
-   * that a non-semantic element (a `<div>`/`<span>` with a click handler)
-   * is actually an interactive control — used by the adapter to surface
-   * custom buttons/checkboxes the AX tree drops as `generic`. Optional like
-   * `textContent`: the live parser always sets it, hand-built fixtures may not.
-   */
-  cursor?: string;
-  /**
-   * Whether the live DOM snapshot provides a painted, non-hidden box for this
-   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
-   * nodes remain authoritative even when they are outside the viewport.
-   */
-  rendered?: boolean;
-  textContent?: string;
-  formState?: "empty" | "filled" | "default";
-  formValue?: string;
-  formDefaultValue?: string;
-  formPlaceholder?: string;
-}
-
-export type CapturedIframeNodes = Map<number, CapturedNode[]>;
-
-export interface CapturedSurfaceProbe {
-  triggerBackendNodeId: number;
-  triggerPoint?: { x: number; y: number };
-  triggerAction: "hover" | "focus" | string;
-  subItems: string[];
-  confidence?: "high" | "medium" | "low";
-}
-
-export interface CapturedViewModel {
-  nodes: CapturedNode[];
-  viewport: Viewport;
-  iframeNodes: CapturedIframeNodes;
-  frameNodes?: Map<string, CapturedNode[]>;
-  frameOwnerBackendNodeIds?: Map<string, number>;
-  /** Explicit DOMSnapshot frame ancestry; never inferred from backend node ids. */
-  frameParentIds?: Map<string, string>;
-  rootFrameId?: string;
-  /** Backend node ids belonging to the agent overlay host + its shadow subtree. */
-  excludedBackendNodeIds: Set<number>;
-}
-
-export interface CaptureViewModelOptions {
-  signal?: AbortSignal;
-}
-
-function captureAbortError(): Error {
-  const error = new Error("observation aborted");
-  error.name = "AbortError";
-  return error;
-}
-
-function isAbortError(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    (error as { name?: string }).name === "AbortError"
-  );
-}
-
-function throwIfAborted(signal: AbortSignal | undefined): void {
-  if (signal?.aborted) throw captureAbortError();
-}
-
-/** Sparse array format Chrome uses for infrequently-set per-node fields. */
-interface SparseArray {
-  index: number[];
-  value: number[];
-}
-
-interface RareBooleanData {
-  index: number[];
-}
-
-interface SnapshotDocument {
-  frameId?: string | number;
-  scrollOffsetX?: number;
-  scrollOffsetY?: number;
-  nodes?: {
-    parentIndex?: number[];
-    nodeName?: number[];
-    backendNodeId?: number[];
-    attributes?: number[][];
-    /**
-     * Per-node text value (index into strings), set for `#text` / CDATA nodes.
-     * Element nodes carry -1. Same length as `backendNodeId`.
-     */
-    nodeValue?: number[];
-    /** Maps node array index → index into `documents[]` for frame content. */
-    contentDocumentIndex?: SparseArray;
-    inputValue?: SparseArray;
-    textValue?: SparseArray;
-    inputChecked?: RareBooleanData;
-    optionSelected?: RareBooleanData;
-  };
-  layout?: {
-    nodeIndex?: number[];
-    styles?: number[][];
-    bounds?: number[][];
-    paintOrders?: number[];
-  };
-}
-
-function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
-  if (typeof document.frameId === "string") return document.frameId || undefined;
-  if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
-  return undefined;
-}
-
-interface SnapshotReply {
-  strings?: string[];
-  documents?: SnapshotDocument[];
-}
-
-interface LayoutMetricsReply {
-  cssLayoutViewport?: {
-    clientWidth?: number;
-    clientHeight?: number;
-    pageX?: number;
-    pageY?: number;
-  };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
-}
-
-function isFormControlTag(tag: string): boolean {
-  return tag === "input" || tag === "textarea" || tag === "select";
-}
-
-function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
-  return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
-}
-
-function snapshotFormState(
-  value: string | undefined,
-  defaultValue: string,
-  hasDefaultValue: boolean,
-  sensitive: boolean,
-): CapturedNode["formState"] {
-  if (sensitive) {
-    if (value === undefined && !hasDefaultValue) return undefined;
-    return (value ?? defaultValue) === "" ? "empty" : "filled";
-  }
-  if (value === undefined) return undefined;
-  if (value === "") return "empty";
-  return value === defaultValue ? "default" : "filled";
-}
-
-const MAX_FORM_ENRICH_CONTROLS = 250;
-
-interface CapturedFormState {
-  value?: string;
-  defaultValue?: string;
-  placeholder?: string;
-  state?: "empty" | "filled" | "default";
-  sensitive?: boolean;
-}
-
-interface CapturedFrameFormState {
-  controls: CapturedFormState[];
-  childFrames: CapturedFrameFormState[];
-}
-
-function formStateBatchExpression(maxControls: number): string {
-  return `(() => {
-    const maxControls = ${JSON.stringify(maxControls)};
-    let remaining = maxControls;
-    const controlSelector = "input,textarea,select";
-    const controlState = (el) => {
-      const tag = el.tagName.toLowerCase();
-      const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
-      const sensitive = type === "password" || type === "credit-card";
-      const rawValue = typeof el.value === "string" ? el.value : "";
-      const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
-      const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
-      const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
-      return {
-        state,
-        sensitive,
-        placeholder,
-        ...(sensitive ? {} : { value: rawValue, defaultValue }),
-      };
-    };
-    const collect = (doc) => {
-      const controls = [];
-      for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
-        if (remaining <= 0) break;
-        controls.push(controlState(el));
-        remaining -= 1;
-      }
-      const childFrames = [];
-      for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
-        let childDoc = null;
-        try { childDoc = frame.contentDocument; } catch { childDoc = null; }
-        childFrames.push(childDoc && remaining > 0 ? collect(childDoc) : { controls: [], childFrames: [] });
-      }
-      return { controls, childFrames };
-    };
-    return collect(document);
-  })()`;
-}
-
-function flattenFrameFormStates(
-  frame: CapturedFrameFormState | undefined,
-  out: CapturedFormState[][] = [],
-): CapturedFormState[][] {
-  if (!frame) return out;
-  out.push(Array.isArray(frame.controls) ? frame.controls : []);
-  for (const child of Array.isArray(frame.childFrames) ? frame.childFrames : []) {
-    flattenFrameFormStates(child, out);
-  }
-  return out;
-}
-
-function applyFormStates(nodes: CapturedNode[], states: CapturedFormState[]): void {
-  let index = 0;
-  for (const node of nodes) {
-    if (!isFormControlTag(node.tag)) continue;
-    const state = states[index];
-    index += 1;
-    if (!state) continue;
-    node.formState = state.state;
-    node.formPlaceholder = state.placeholder ?? "";
-    if (state.sensitive || isSensitiveFormControl(node)) {
-      delete node.formValue;
-      delete node.formDefaultValue;
-      delete node.attrs.value;
-    } else {
-      node.formDefaultValue = state.defaultValue ?? "";
-      if (state.value !== undefined) node.formValue = state.value;
-    }
-  }
-}
-
-async function enrichFormControlStates(
-  cdp: CdpRunner,
-  tabId: number,
-  frameNodeGroups: CapturedNode[][],
-  signal?: AbortSignal,
-): Promise<void> {
-  const hasControls = frameNodeGroups.some((nodes) =>
-    nodes.some((node) => isFormControlTag(node.tag)),
-  );
-  if (!hasControls) return;
-  try {
-    throwIfAborted(signal);
-    const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-      expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
-      returnByValue: true,
-    });
-    throwIfAborted(signal);
-    const frameStates = flattenFrameFormStates(runtimeValue<CapturedFrameFormState>(result));
-    for (let i = 0; i < frameNodeGroups.length; i += 1) {
-      applyFormStates(frameNodeGroups[i], frameStates[i] ?? []);
-    }
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    // Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
-  }
-}
-
 interface RuntimeEvaluateReply {
   result?: {
     value?: unknown;
@@ -314,44 +35,6 @@ interface CdpDomNode {
   shadowRoots?: CdpDomNode[];
 }
 
-interface ParseDocumentResult {
-  nodes: CapturedNode[];
-  excludedBackendNodeIds: Set<number>;
-}
-
-interface FrameContext {
-  frameId?: string;
-  ownerFrameBackendNodeId: number | null;
-  projection: GeometryProjection | null;
-  scrollX: number;
-  scrollY: number;
-}
-
-function str(strings: string[], idx: number | undefined): string {
-  if (idx === undefined || idx < 0) return "";
-  return strings[idx] ?? "";
-}
-
-function devicePixelRatio(metrics: LayoutMetricsReply): number {
-  const layoutW = metrics.layoutViewport?.clientWidth ?? 0;
-  const cssW = metrics.cssLayoutViewport?.clientWidth ?? 0;
-  if (!layoutW || !cssW) return 1;
-  const dpr = layoutW / cssW;
-  if (!Number.isFinite(dpr) || dpr <= 0) return 1;
-  return dpr >= 1 ? dpr : 1;
-}
-
-function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
-  const out = new Map<number, number>();
-  if (!sparse?.index || !sparse.value) return out;
-  for (let i = 0; i < sparse.index.length; i++) {
-    const nodeIndex = sparse.index[i];
-    const docIndex = sparse.value[i];
-    if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
-  }
-  return out;
-}
-
 function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<number>): void {
   if (!node) return;
   if (typeof node.backendNodeId === "number") {
@@ -760,358 +443,3 @@ export async function collectOverlayExcludedBackendIds(
   }
   return excluded;
 }
-
-/**
- * Parse one DOMSnapshot document into CapturedNode[].
- *
- * @param doc   - the raw DOMSnapshot document object
- * @param strings - the shared string table for the whole snapshot
- * @param dpr   - device-pixel-ratio from Page.getLayoutMetrics
- * @param context - frame coordinate context; output rects are top viewport-relative
- */
-function parseDocumentNodes(
-  doc: SnapshotDocument,
-  strings: string[],
-  dpr: number,
-  context: FrameContext,
-): ParseDocumentResult {
-  const dn = doc.nodes;
-  const dl = doc.layout;
-  if (!dn?.backendNodeId) {
-    return { nodes: [], excludedBackendNodeIds: new Set() };
-  }
-
-  const count = dn.backendNodeId.length;
-  const layoutByNode = new Map<number, number>();
-  (dl?.nodeIndex ?? []).forEach((nodeIdx, layoutIdx) => layoutByNode.set(nodeIdx, layoutIdx));
-
-  // The agent's own overlay (WXT shadow host, marked with OVERLAY_HOST_MARKER_ATTR)
-  // is injected into the page and its open shadow root
-  // is inlined by DOMSnapshot as descendants of the host. Its fixed
-  // full-viewport click-blocker would otherwise dominate occlusion detection
-  // and hide the real page, so mark the host + its whole subtree excluded.
-  // parentIndex always references an earlier node, so one forward pass suffices.
-  const excluded = new Array<boolean>(count).fill(false);
-  const excludedBackendNodeIds = new Set<number>();
-  for (let n = 0; n < count; n++) {
-    const parentIdx = dn.parentIndex?.[n] ?? -1;
-    const inherited = parentIdx >= 0 && excluded[parentIdx];
-    let isOverlayHost = inherited;
-    if (!isOverlayHost) {
-      const pairs = dn.attributes?.[n] ?? [];
-      const attrNames: string[] = [];
-      for (let a = 0; a + 1 < pairs.length; a += 2) {
-        attrNames.push(str(strings, pairs[a]));
-      }
-      isOverlayHost = isOverlayHostNode(str(strings, dn.nodeName?.[n]), attrNames);
-    }
-    if (!isOverlayHost) continue;
-    excluded[n] = true;
-    const backendNodeId = dn.backendNodeId[n];
-    if (backendNodeId !== undefined) {
-      excludedBackendNodeIds.add(backendNodeId);
-    }
-  }
-
-  const posCol = STYLE_COL.position;
-  const peCol = STYLE_COL["pointer-events"];
-  const cursorCol = STYLE_COL.cursor;
-  const visibilityCol = STYLE_COL.visibility;
-  const opacityCol = STYLE_COL.opacity;
-  const inputValues = sparseIndexMap(dn.inputValue);
-  const textValues = sparseIndexMap(dn.textValue);
-  const checkedInputs = new Set(dn.inputChecked?.index ?? []);
-  const selectedOptions = new Set(dn.optionSelected?.index ?? []);
-
-  // Collect visible text from #text child nodes so element CapturedNodes
-  // carry a textContent value usable as a button/link label fallback.
-  // nodeValue is a parallel array: string index for text nodes, -1 otherwise.
-  const nodeTextContent = new Map<number, string>();
-  if (dn.nodeValue) {
-    for (let n = 0; n < count; n++) {
-      const nvIdx = dn.nodeValue[n] ?? -1;
-      if (nvIdx < 0) continue;
-      const text = str(strings, nvIdx).trim();
-      if (!text) continue;
-      const parentIdx = dn.parentIndex?.[n] ?? -1;
-      if (parentIdx >= 0) {
-        const existing = nodeTextContent.get(parentIdx);
-        nodeTextContent.set(parentIdx, existing ? `${existing} ${text}` : text);
-      }
-    }
-  }
-
-  // Build CapturedNodes.
-  const nodes: CapturedNode[] = [];
-  for (let n = 0; n < count; n++) {
-    if (excluded[n]) continue;
-    const backendNodeId = dn.backendNodeId[n];
-    const parentIdx = dn.parentIndex?.[n] ?? -1;
-    const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
-    const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
-
-    const attrs: Record<string, string> = {};
-    const pairs = dn.attributes?.[n] ?? [];
-    for (let a = 0; a + 1 < pairs.length; a += 2) {
-      attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
-    }
-
-    let rect: Rect | null = null;
-    let localRect: Rect | null = null;
-    let paintOrder = 0;
-    let position = "static";
-    let pointerEvents = "auto";
-    let cursor = "auto";
-    let rendered = false;
-    const li = layoutByNode.get(n);
-    if (li !== undefined) {
-      const b = dl?.bounds?.[li];
-      if (b && b.length >= 4 && b[2] > 0 && b[3] > 0) {
-        localRect = {
-          x: b[0] / dpr - context.scrollX,
-          y: b[1] / dpr - context.scrollY,
-          w: b[2] / dpr,
-          h: b[3] / dpr,
-        };
-        const bounds = context.projection
-          ? projectRectToViewport(localRect, context.projection)
-          : null;
-        rect = bounds ? { x: bounds.x, y: bounds.y, w: bounds.width, h: bounds.height } : null;
-      }
-      paintOrder = dl?.paintOrders?.[li] ?? 0;
-      const styleRow = dl?.styles?.[li] ?? [];
-      position = str(strings, styleRow[posCol]) || "static";
-      pointerEvents = str(strings, styleRow[peCol]) || "auto";
-      cursor = str(strings, styleRow[cursorCol]) || "auto";
-      const visibility = str(strings, styleRow[visibilityCol]) || "visible";
-      const opacity = str(strings, styleRow[opacityCol]) || "1";
-      rendered =
-        localRect !== null &&
-        visibility !== "hidden" &&
-        visibility !== "collapse" &&
-        (Number.parseFloat(opacity) || 0) > 0;
-    }
-
-    // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
-    // geometry and are never queried by callers.
-    if (tag.startsWith("#")) continue;
-
-    const textContent = nodeTextContent.get(n);
-
-    const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
-    const rawFormValue =
-      rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
-    const sensitive = isSensitiveFormControl({ tag, attrs });
-    const formDefaultValue = attrs.value ?? "";
-    const formValue = sensitive ? undefined : rawFormValue;
-    const formState = snapshotFormState(
-      rawFormValue,
-      formDefaultValue,
-      Object.prototype.hasOwnProperty.call(attrs, "value"),
-      sensitive,
-    );
-    if (sensitive) delete attrs.value;
-
-    nodes.push({
-      backendNodeId,
-      parentBackendNodeId,
-      ...(context.frameId ? { frameId: context.frameId } : {}),
-      ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
-      tag,
-      attrs,
-      rect,
-      localRect,
-      paintOrder,
-      position,
-      pointerEvents,
-      cursor,
-      rendered,
-      textContent,
-      ...(formValue !== undefined ? { formValue } : {}),
-      ...(tag === "input" || tag === "textarea"
-        ? {
-            formPlaceholder: attrs.placeholder ?? "",
-            ...(!sensitive ? { formDefaultValue } : {}),
-            ...(formState ? { formState } : {}),
-          }
-        : {}),
-      ...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
-      ...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
-    });
-  }
-  return { nodes, excludedBackendNodeIds };
-}
-
-interface ParseFrameDocumentsResult {
-  iframeNodes: CapturedIframeNodes;
-  frameOwnerBackendNodeIds: Map<string, number>;
-  frameParentIds: Map<string, string>;
-  excludedBackendNodeIds: Set<number>;
-}
-
-function parseChildFrameDocuments(
-  documents: SnapshotDocument[],
-  strings: string[],
-  dpr: number,
-  parentDocIndex: number,
-  parentNodes: CapturedNode[],
-  parentContext: FrameContext,
-  visited = new Set<number>(),
-): ParseFrameDocumentsResult {
-  const iframeNodes: CapturedIframeNodes = new Map();
-  const frameOwnerBackendNodeIds = new Map<string, number>();
-  const frameParentIds = new Map<string, string>();
-  const excludedBackendNodeIds = new Set<number>();
-  const parentDoc = documents[parentDocIndex];
-  const cdi = sparseIndexMap(parentDoc?.nodes?.contentDocumentIndex);
-  if (cdi.size === 0) {
-    return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
-  }
-
-  const parentBackendIds = parentDoc?.nodes?.backendNodeId ?? [];
-  const parentNodeByBackendId = new Map(parentNodes.map((node) => [node.backendNodeId, node]));
-
-  for (const [nodeArrayIdx, childDocIndex] of cdi) {
-    if (visited.has(childDocIndex)) continue;
-    const childDoc = documents[childDocIndex];
-    if (!childDoc) continue;
-    const iframeBackendId = parentBackendIds[nodeArrayIdx];
-    if (iframeBackendId === undefined) continue;
-    const iframeNode = parentNodeByBackendId.get(iframeBackendId);
-    const projection =
-      parentContext.projection && iframeNode?.localRect
-        ? childFrameProjection(parentContext.projection, iframeNode.localRect)
-        : null;
-
-    const childContext: FrameContext = {
-      frameId: snapshotFrameId(childDoc, strings),
-      ownerFrameBackendNodeId: iframeBackendId,
-      projection,
-      scrollX: childDoc.scrollOffsetX ?? 0,
-      scrollY: childDoc.scrollOffsetY ?? 0,
-    };
-    const nextVisited = new Set(visited);
-    nextVisited.add(childDocIndex);
-    const parsed = parseDocumentNodes(childDoc, strings, dpr, childContext);
-    iframeNodes.set(iframeBackendId, parsed.nodes);
-    if (childContext.frameId) {
-      frameOwnerBackendNodeIds.set(childContext.frameId, iframeBackendId);
-      if (parentContext.frameId) frameParentIds.set(childContext.frameId, parentContext.frameId);
-    }
-    for (const id of parsed.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
-
-    const nested = parseChildFrameDocuments(
-      documents,
-      strings,
-      dpr,
-      childDocIndex,
-      parsed.nodes,
-      childContext,
-      nextVisited,
-    );
-    for (const [nestedFrameId, nestedNodes] of nested.iframeNodes) {
-      iframeNodes.set(nestedFrameId, nestedNodes);
-    }
-    for (const [frameId, ownerBackendNodeId] of nested.frameOwnerBackendNodeIds) {
-      frameOwnerBackendNodeIds.set(frameId, ownerBackendNodeId);
-    }
-    for (const [frameId, parentFrameId] of nested.frameParentIds) {
-      frameParentIds.set(frameId, parentFrameId);
-    }
-    for (const id of nested.excludedBackendNodeIds) excludedBackendNodeIds.add(id);
-  }
-
-  return { iframeNodes, frameOwnerBackendNodeIds, frameParentIds, excludedBackendNodeIds };
-}
-
-export async function captureViewModel(
-  cdp: CdpRunner,
-  tabId: number,
-  options: CaptureViewModelOptions = {},
-): Promise<CapturedViewModel> {
-  throwIfAborted(options.signal);
-  let metrics: LayoutMetricsReply = {};
-  try {
-    metrics = await cdp.send<LayoutMetricsReply>(tabId, "Page.getLayoutMetrics", {});
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    console.debug("[bsk capture] layout metrics unavailable", error);
-  }
-  throwIfAborted(options.signal);
-  const dpr = devicePixelRatio(metrics);
-  const vpSrc = metrics.cssLayoutViewport ?? metrics.layoutViewport ?? {};
-  const viewport: Viewport = {
-    width: vpSrc.clientWidth ?? 0,
-    height: vpSrc.clientHeight ?? 0,
-  };
-  const scrollX = vpSrc.pageX ?? 0;
-  const scrollY = vpSrc.pageY ?? 0;
-
-  await cdp.send(tabId, "DOMSnapshot.enable", {});
-  throwIfAborted(options.signal);
-  const snap = await cdp.send<SnapshotReply>(tabId, "DOMSnapshot.captureSnapshot", {
-    computedStyles: REQUESTED_STYLES,
-    includePaintOrder: true,
-    includeDOMRects: true,
-  });
-  throwIfAborted(options.signal);
-
-  const strings = snap.strings ?? [];
-  const documents = snap.documents ?? [];
-  const doc0 = documents[0];
-  if (!doc0?.nodes?.backendNodeId) {
-    return {
-      nodes: [],
-      viewport,
-      iframeNodes: new Map(),
-      excludedBackendNodeIds: new Set(),
-    };
-  }
-
-  const topContext: FrameContext = {
-    frameId: snapshotFrameId(doc0, strings),
-    ownerFrameBackendNodeId: null,
-    projection: {
-      sourceClips: [],
-      edges: [],
-      topViewport: viewport,
-    },
-    scrollX,
-    scrollY,
-  };
-  const mainParsed = parseDocumentNodes(doc0, strings, dpr, topContext);
-  const nodes = mainParsed.nodes;
-  const excludedBackendNodeIds = new Set(mainParsed.excludedBackendNodeIds);
-
-  const frameParsed = parseChildFrameDocuments(documents, strings, dpr, 0, nodes, topContext);
-  const iframeNodes = frameParsed.iframeNodes;
-  for (const id of frameParsed.excludedBackendNodeIds) {
-    excludedBackendNodeIds.add(id);
-  }
-
-  await enrichFormControlStates(cdp, tabId, [nodes, ...iframeNodes.values()], options.signal);
-  throwIfAborted(options.signal);
-
-  const frameNodes = new Map<string, CapturedNode[]>();
-  if (topContext.frameId) frameNodes.set(topContext.frameId, nodes);
-  for (const iframeFrameNodes of iframeNodes.values()) {
-    const frameId = iframeFrameNodes.find((node) => node.frameId)?.frameId;
-    if (frameId) frameNodes.set(frameId, iframeFrameNodes);
-  }
-  for (const [frameId, ownerBackendNodeId] of frameParsed.frameOwnerBackendNodeIds) {
-    if (!frameNodes.has(frameId)) {
-      frameNodes.set(frameId, iframeNodes.get(ownerBackendNodeId) ?? []);
-    }
-  }
-
-  return {
-    nodes,
-    viewport,
-    iframeNodes,
-    frameNodes,
-    frameOwnerBackendNodeIds: frameParsed.frameOwnerBackendNodeIds,
-    frameParentIds: frameParsed.frameParentIds,
-    ...(topContext.frameId ? { rootFrameId: topContext.frameId } : {}),
-    excludedBackendNodeIds,
-  };
-}

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

@@ -0,0 +1,53 @@
+import type { CdpRunner } from "../shared";
+import { sendToCdpTarget } from "../shared";
+import { isAbortError, throwIfAborted } from "./capture-abort";
+import type { DocumentIdentity } from "./facts";
+
+/** Compare the snapshot root with the current root in that exact frame.
+ * Deep serialization supplies the backend ID without a separate describeNode. */
+export async function verifyDocumentIdentity(
+  cdp: CdpRunner,
+  identity: DocumentIdentity,
+  signal?: AbortSignal,
+): Promise<"current" | "changed" | "unavailable"> {
+  const attached = () => cdp.getAttachmentId?.(identity.target.tabId) === identity.attachmentId;
+  throwIfAborted(signal);
+  if (!attached()) return "changed";
+  const objectGroup = `bsk-document-identity-${crypto.randomUUID()}`;
+  const send = <T>(method: string, params: object) => {
+    throwIfAborted(signal);
+    return sendToCdpTarget<T>(cdp, identity.target, method, params);
+  };
+  try {
+    const world = await send<{ executionContextId: number }>("Page.createIsolatedWorld", {
+      frameId: identity.frameId,
+      worldName: "bsk-document-identity",
+    });
+    const reply = await send<{
+      result?: { deepSerializedValue?: { type: string; value?: { backendNodeId?: number } } };
+    }>("Runtime.evaluate", {
+      expression: "document.documentElement",
+      contextId: world.executionContextId,
+      objectGroup,
+      serializationOptions: {
+        serialization: "deep",
+        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+      },
+    });
+    if (!attached()) return "changed";
+    const root = reply.result?.deepSerializedValue;
+    if (root?.type === "null") return "changed";
+    const id = root?.type === "node" ? root.value?.backendNodeId : undefined;
+    if (id === undefined) return "unavailable";
+    return id === identity.documentElementBackendNodeId ? "current" : "changed";
+  } catch (error) {
+    throwIfAborted(signal);
+    if (isAbortError(error)) throw error;
+    return attached() ? "unavailable" : "changed";
+  } finally {
+    await sendToCdpTarget(cdp, identity.target, "Runtime.releaseObjectGroup", {
+      objectGroup,
+    }).catch(() => {});
+    throwIfAborted(signal);
+  }
+}

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

@@ -0,0 +1,182 @@
+import type { Viewport } from "@browser-skill/vom";
+import type { CdpFrame, CdpTarget } from "@/browser-driver/frame-graph";
+import { isOverlayHostNode } from "@/lib/overlay-bridge";
+import type { GeometryProjection } from "../geometry";
+import type { FrameProjectionIssue, SnapshotCoordinates } from "../geometry/coordinate-types";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+import type { FrameOwnedAxNode } from "./frame-document";
+
+/** Bounds retain their raw snapshot document layout units until normalization. */
+export interface SnapshotLayout {
+  readonly boundsSpace: "snapshot-document-layout";
+  bounds?: number[];
+  /** [clientLeft, clientTop, clientWidth, clientHeight], untransformed local CSS units. */
+  clientRect?: number[];
+  styles: Readonly<Record<string, string>>;
+}
+
+export interface DecodedNode extends Omit<CapturedNode, "rect" | "localRect" | "rendered"> {
+  nodeType?: number;
+  parentMissing?: boolean;
+  layout?: SnapshotLayout;
+}
+
+export interface NodeFacts extends CapturedNode {
+  nodeType?: number;
+  parentMissing?: boolean;
+  layout?: SnapshotLayout;
+}
+
+export interface DocumentIndex<T extends DecodedNode = NodeFacts> {
+  readonly nodes: ReadonlyMap<number, T>;
+  readonly ancestryComplete?: ReadonlyMap<number, boolean>;
+  readonly excludedBackendNodeIds: ReadonlySet<number>;
+}
+
+export interface DecodedDocument {
+  nodes: DecodedNode[];
+}
+
+/** All snapshot nodes participate, including document and shadow roots. This
+ * preserves overlay propagation when the semantic adapter omits those nodes. */
+export async function buildDocumentIndex<T extends DecodedNode>(
+  input: readonly T[],
+  signal?: AbortSignal,
+  includeVisualFacts = false,
+): Promise<DocumentIndex<T>> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  const nodes = new Map<number, T>();
+  const overlayByNode = new Map<number, boolean>();
+  const ancestryComplete = includeVisualFacts ? new Map<number, boolean>() : undefined;
+  const excludedBackendNodeIds = new Set<number>();
+  for (let i = 0; i < input.length; i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const node = input[i];
+    nodes.set(node.backendNodeId, node);
+  }
+  let work = 0;
+  for (const node of input) {
+    if (work++ % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    if (overlayByNode.has(node.backendNodeId)) continue;
+    const path: DecodedNode[] = [];
+    const visiting = new Set<number>();
+    let current: DecodedNode | undefined = node;
+    let overlay = false;
+    let complete = false;
+    while (current && !overlayByNode.has(current.backendNodeId)) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (visiting.has(current.backendNodeId)) {
+        // Only an overlay inside the cycle may mark the cycle and its descendants.
+        overlay = path
+          .slice(path.findIndex((item) => item.backendNodeId === current!.backendNodeId))
+          .some((item) => isOverlayHostNode(item.tag, Object.keys(item.attrs)));
+        break;
+      }
+      visiting.add(current.backendNodeId);
+      path.push(current);
+      if (current.parentBackendNodeId === null) {
+        if (ancestryComplete) complete = !current.parentMissing && current.nodeType === 9;
+        current = undefined;
+        break;
+      }
+      current = nodes.get(current.parentBackendNodeId);
+    }
+    if (current && overlayByNode.has(current.backendNodeId)) {
+      overlay = overlayByNode.get(current.backendNodeId)!;
+      if (ancestryComplete) complete = ancestryComplete.get(current.backendNodeId) === true;
+    }
+    for (let i = path.length - 1; i >= 0; i--) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      const item = path[i];
+      overlay = overlay || isOverlayHostNode(item.tag, Object.keys(item.attrs));
+      overlayByNode.set(item.backendNodeId, overlay);
+      if (ancestryComplete) {
+        complete = complete && !item.parentMissing;
+        ancestryComplete.set(item.backendNodeId, complete);
+      }
+      if (overlay) excludedBackendNodeIds.add(item.backendNodeId);
+    }
+  }
+  return { nodes, ...(ancestryComplete ? { ancestryComplete } : {}), excludedBackendNodeIds };
+}
+
+export interface DocumentIdentity {
+  attachmentId: string;
+  target: CdpTarget;
+  frameId: string;
+  documentElementBackendNodeId: number;
+}
+
+/** Narrow input shared by the existing semantic scene/hover consumers. */
+export interface CapturedSceneInput {
+  nodes: CapturedNode[];
+  viewport: Viewport;
+  rootFrameId?: string;
+  excludedBackendNodeIds: ReadonlySet<number>;
+}
+
+export interface CaptureIssue {
+  /** Owner failure or inherited blockage; absent for other geometry failures. */
+  projectionIssue?: FrameProjectionIssue;
+  target: CdpTarget;
+  frameId?: string;
+  stage: "dom" | "ax" | "identity" | "ownership" | "geometry" | "forms";
+  reason:
+    | "document-changed"
+    | "identity-unavailable"
+    | "identity-unverified"
+    | "capture-unavailable"
+    | "frame-ownership-unresolved"
+    | "geometry-unavailable";
+}
+
+/** Shared per document; never retain the live GeometryContext in published facts. */
+export interface DocumentGeometry {
+  readonly projections: readonly GeometryProjection[];
+  readonly coordinates: SnapshotCoordinates;
+  /** Visual viewport scale (pinch), distinct from browser UI zoom. */
+  readonly pageScale?: number;
+}
+
+export interface DocumentFacts<T extends FrameOwnedAxNode> {
+  readonly geometry?: DocumentGeometry;
+  readonly frame: CdpFrame;
+  readonly identity?: DocumentIdentity;
+  readonly index: DocumentIndex;
+  readonly domNodes: CapturedNode[];
+  readonly axNodes: T[];
+}
+
+export interface ObservationFacts<T extends FrameOwnedAxNode> {
+  /** Whether visual collection was enabled; partial capture failures remain in issues. */
+  readonly visualFactsCollected: boolean;
+  readonly rootFrameId: string;
+  readonly viewport: Viewport;
+  readonly documents: readonly DocumentFacts<T>[];
+  readonly issues: readonly CaptureIssue[];
+  readonly startedAt: number;
+  readonly finishedAt: number;
+}
+
+export interface CapturedSurfaceProbe {
+  triggerBackendNodeId: number;
+  triggerPoint?: { x: number; y: number };
+  triggerAction: "hover" | "focus" | string;
+  subItems: string[];
+  confidence?: "high" | "medium" | "low";
+}
+
+export type { CapturedNode } from "./capture-types";

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

@@ -0,0 +1,155 @@
+import type { CdpRunner } from "../shared";
+import { isAbortError, throwIfAborted } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+
+interface RuntimeEvaluateReply {
+  result?: { deepSerializedValue?: DeepSerializedValue };
+}
+const MAX_FORM_ENRICH_CONTROLS = 250;
+
+interface CapturedFormState {
+  value?: string;
+  defaultValue?: string;
+  placeholder?: string;
+  state?: "empty" | "filled" | "default";
+  sensitive?: boolean;
+}
+
+interface DeepSerializedValue {
+  type: string;
+  value?: unknown;
+}
+
+function formStateBatchExpression(maxControls: number): string {
+  return `(() => {
+    const maxControls = ${JSON.stringify(maxControls)};
+    let remaining = maxControls;
+    const controlSelector = "input,textarea,select";
+    const controlState = (el) => {
+      const tag = el.tagName.toLowerCase();
+      const type = tag === "input" ? String(el.type || "text").toLowerCase() : tag;
+      const sensitive = type === "password" || type === "credit-card";
+      const rawValue = typeof el.value === "string" ? el.value : "";
+      const defaultValue = typeof el.defaultValue === "string" ? el.defaultValue : "";
+      const placeholder = typeof el.placeholder === "string" ? el.placeholder : "";
+      const state = rawValue === "" ? "empty" : rawValue === defaultValue ? "default" : "filled";
+      return {
+        state,
+        sensitive,
+        placeholder,
+        ...(sensitive ? {} : { value: rawValue, defaultValue }),
+      };
+    };
+    const controls = [];
+    const collect = (doc) => {
+      for (const el of Array.from(doc.querySelectorAll(controlSelector))) {
+        if (remaining <= 0) break;
+        // Deep serialization supplies the node's backend id. Keep the
+        // state as JSON so decoding needs no general-purpose V8 deserializer.
+        controls.push([el, JSON.stringify(controlState(el))]);
+        remaining -= 1;
+      }
+      for (const frame of Array.from(doc.querySelectorAll("iframe"))) {
+        if (remaining <= 0) break;
+        let childDoc = null;
+        try { childDoc = frame.contentDocument; } catch { childDoc = null; }
+        if (childDoc) collect(childDoc);
+      }
+    };
+    collect(document);
+    return controls;
+  })()`;
+}
+
+function formStatesByBackendId(result: RuntimeEvaluateReply): Map<number, CapturedFormState> {
+  const states = new Map<number, CapturedFormState>();
+  const serialized = result.result?.deepSerializedValue;
+  if (serialized?.type !== "array" || !Array.isArray(serialized.value)) return states;
+  for (const entry of serialized.value as DeepSerializedValue[]) {
+    if (entry?.type !== "array" || !Array.isArray(entry.value)) continue;
+    const [element, json] = entry.value as DeepSerializedValue[];
+    if (element?.type !== "node" || json?.type !== "string" || typeof json.value !== "string") {
+      continue;
+    }
+    const backendNodeId = (element.value as { backendNodeId?: number } | undefined)?.backendNodeId;
+    if (typeof backendNodeId !== "number" || !Number.isSafeInteger(backendNodeId)) continue;
+    try {
+      const state = JSON.parse(json.value) as CapturedFormState | null;
+      if (
+        !state ||
+        !["empty", "filled", "default"].includes(state.state ?? "") ||
+        typeof state.sensitive !== "boolean" ||
+        typeof state.placeholder !== "string" ||
+        (!state.sensitive &&
+          (typeof state.value !== "string" || typeof state.defaultValue !== "string"))
+      ) {
+        continue;
+      }
+      states.set(backendNodeId, state);
+    } catch {
+      // A malformed entry must not overwrite the snapshot's own state.
+    }
+  }
+  return states;
+}
+
+function applyFormStates(nodes: CapturedNode[], states: Map<number, CapturedFormState>): void {
+  for (const node of nodes) {
+    if (!["input", "textarea", "select"].includes(node.tag)) continue;
+    const state = states.get(node.backendNodeId);
+    if (!state) continue;
+    node.formState = state.state;
+    node.formPlaceholder = state.placeholder ?? "";
+    if (
+      state.sensitive ||
+      (node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password")
+    ) {
+      delete node.formValue;
+      delete node.formDefaultValue;
+      delete node.attrs.value;
+    } else {
+      node.formDefaultValue = state.defaultValue ?? "";
+      if (state.value !== undefined) node.formValue = state.value;
+    }
+  }
+}
+
+export async function enrichFormControlStates(
+  cdp: CdpRunner,
+  tabId: number,
+  frameNodeGroups: CapturedNode[][],
+  signal?: AbortSignal,
+): Promise<boolean> {
+  const hasControls = frameNodeGroups.some((nodes) =>
+    nodes.some((node) => ["input", "textarea", "select"].includes(node.tag)),
+  );
+  if (!hasControls) return true;
+  const objectGroup = `bsk-vom-forms-${crypto.randomUUID()}`;
+  try {
+    throwIfAborted(signal);
+    const result = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+      expression: formStateBatchExpression(MAX_FORM_ENRICH_CONTROLS),
+      objectGroup,
+      serializationOptions: {
+        serialization: "deep",
+        maxDepth: 3,
+        additionalParameters: { maxNodeDepth: 0, includeShadowTree: "none" },
+      },
+    });
+    throwIfAborted(signal);
+    // Backend ids are scoped to this capture's CDP target. OOPIF targets
+    // have separate enrichment calls and never share this lookup.
+    const states = formStatesByBackendId(result);
+    for (const nodes of frameNodeGroups) {
+      applyFormStates(nodes, states);
+    }
+    return true;
+  } catch (error) {
+    if (isAbortError(error)) throw error;
+    // Best-effort enrichment. DOMSnapshot/AX data still carries the nodes.
+    return false;
+  } finally {
+    await cdp.send(tabId, "Runtime.releaseObjectGroup", { objectGroup }).catch(() => undefined);
+    throwIfAborted(signal);
+  }
+}

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

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

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

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

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

@@ -0,0 +1,356 @@
+import type { Viewport } from "@browser-skill/vom";
+import { type CdpFrame, type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import { type GeometryProjection, projectRectToViewport } from "../geometry";
+import {
+  type FrameProjectionState,
+  projectSnapshotRect,
+  type SnapshotCoordinates,
+  snapshotCoordinates,
+  snapshotViewportRect,
+} from "../geometry/coordinate-types";
+import {
+  GeometryContext,
+  type LayoutMetrics,
+  snapshotLayoutScale,
+} from "../geometry/frame-context";
+import {
+  createCaptureCheckpoint,
+  isAbortError as isCaptureAbort,
+  throwIfAborted as throwCaptureAborted,
+} from "./capture-abort";
+import {
+  buildDocumentIndex,
+  type CaptureIssue,
+  type DocumentGeometry,
+  type DocumentIndex,
+  type NodeFacts,
+} from "./facts";
+import {
+  BASIC_SNAPSHOT,
+  decodeDocument,
+  type SnapshotDocument,
+  type SnapshotProfile,
+  type SnapshotReply,
+  snapshotFrameId,
+} from "./snapshot";
+
+export interface FrameContext {
+  frameId?: string;
+  ownerFrameBackendNodeId: number | null;
+  projection: FrameProjectionState | null;
+  targetProjection?: GeometryProjection | null;
+  target: CdpTarget;
+  coordinates: SnapshotCoordinates | null;
+  pageScale?: number;
+}
+
+export interface NormalizedDocument {
+  geometry?: DocumentGeometry;
+  nodes: NodeFacts[];
+  index: DocumentIndex;
+  documentElementBackendNodeId?: number;
+}
+
+/** Interpret one document using a supplied projection. No live reads or frame scheduling. */
+export async function normalizeDocument(
+  doc: SnapshotDocument,
+  strings: string[],
+  context: FrameContext,
+  signal?: AbortSignal,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
+): Promise<NormalizedDocument> {
+  const decoded = await decodeDocument(doc, strings, signal, profile);
+  const checkpoint = createCaptureCheckpoint(signal);
+  const nodes: NodeFacts[] = [];
+  for (let i = 0; i < decoded.nodes.length; i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const node = decoded.nodes[i];
+    const bounds = node.layout?.bounds ?? [];
+    const input = snapshotViewportRect(
+      bounds,
+      { target: context.target, frameId: context.frameId },
+      context.coordinates,
+    );
+    const local = input?.rect;
+    let rect =
+      input && context.projection?.status === "available"
+        ? projectSnapshotRect(input, context.projection.projection)
+        : null;
+    if (rect && context.targetProjection !== undefined)
+      rect = context.targetProjection
+        ? projectRectToViewport(
+            { x: rect.x, y: rect.y, w: rect.width, h: rect.height },
+            context.targetProjection,
+          )
+        : null;
+    const visibility = node.layout?.styles.visibility || "visible";
+    const opacity = node.layout?.styles.opacity || "1";
+    nodes.push({
+      ...node,
+      ...(context.frameId ? { frameId: context.frameId } : {}),
+      ownerFrameBackendNodeId: context.ownerFrameBackendNodeId,
+      localRect: local ? { x: local.x, y: local.y, w: local.width, h: local.height } : null,
+      rect: rect ? { x: rect.x, y: rect.y, w: rect.width, h: rect.height } : null,
+      rendered:
+        bounds.length >= 4 &&
+        bounds.slice(0, 4).every(Number.isFinite) &&
+        bounds[2] > 0 &&
+        bounds[3] > 0 &&
+        visibility !== "hidden" &&
+        visibility !== "collapse" &&
+        (Number.parseFloat(opacity) || 0) > 0,
+    });
+  }
+  const index = await buildDocumentIndex(nodes, signal, profile.includeVisualFacts);
+  return {
+    nodes: nodes.filter(
+      (node) => !node.tag.startsWith("#") && !index.excludedBackendNodeIds.has(node.backendNodeId),
+    ),
+    index,
+    ...(profile.includeVisualFacts &&
+    context.coordinates &&
+    context.projection?.status === "available" &&
+    context.targetProjection !== null
+      ? {
+          geometry: {
+            projections: [
+              context.projection.projection.geometry,
+              ...(context.targetProjection ? [context.targetProjection] : []),
+            ],
+            coordinates: context.coordinates,
+            pageScale: context.pageScale,
+          },
+        }
+      : {}),
+    documentElementBackendNodeId: nodes.find(
+      (node) =>
+        node.nodeType === 1 &&
+        node.parentBackendNodeId !== null &&
+        index.nodes.get(node.parentBackendNodeId)?.nodeType === 9,
+    )?.backendNodeId,
+  };
+}
+
+export interface NormalizedFrameDocument extends NormalizedDocument {
+  frame: CdpFrame;
+}
+
+/** One target's snapshot. Source ownership is checked before interpreting any
+ * coordinates. Snapshot and live quad coordinates are deliberately not conflated. */
+export async function normalizeSnapshot(
+  snapshot: SnapshotReply,
+  target: CdpTarget,
+  frames: readonly CdpFrame[],
+  geometry: GeometryContext,
+  issues: CaptureIssue[],
+  signal?: AbortSignal,
+  rootFrameId?: string,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
+): Promise<NormalizedFrameDocument[]> {
+  const strings = snapshot.strings ?? [];
+  const raw = snapshot.documents ?? [];
+  const ownerIds = new Set<number>();
+  for (const document of raw) {
+    for (const index of document.nodes?.contentDocumentIndex?.index ?? []) {
+      const id = document.nodes?.backendNodeId?.[index];
+      if (id !== undefined) ownerIds.add(id);
+    }
+  }
+  geometry.registerSnapshotOwners(target, ownerIds);
+  const frameById = new Map(frames.map((frame) => [frame.frameId, frame]));
+  const sources = new Map<string, SnapshotDocument>();
+  for (const doc of raw) {
+    const id = snapshotFrameId(doc, strings);
+    if (!id || !frameById.has(id) || sources.has(id)) {
+      issues.push({
+        target,
+        frameId: id,
+        stage: "ownership",
+        reason: "frame-ownership-unresolved",
+      });
+      continue;
+    }
+    sources.set(id, doc);
+  }
+  let metrics: LayoutMetrics = {};
+  try {
+    metrics = await geometry.layoutMetrics(target);
+  } catch (error) {
+    if (isCaptureAbort(error)) throw error;
+  }
+  const viewport: Viewport = {
+    width: metrics.cssLayoutViewport?.clientWidth ?? 0,
+    height: metrics.cssLayoutViewport?.clientHeight ?? 0,
+  };
+  const layoutUnitsPerCssPixel = snapshotLayoutScale(metrics);
+  const viewportAvailable = [viewport.width, viewport.height].every(
+    (size) => Number.isFinite(size) && size > 0,
+  );
+
+  const children = new Map<string, CdpFrame[]>();
+  const pending: CdpFrame[] = [];
+  for (const frame of frames) {
+    if (!frame.parentFrameId || !frameById.has(frame.parentFrameId)) pending.push(frame);
+    else {
+      const siblings = children.get(frame.parentFrameId);
+      if (siblings) siblings.push(frame);
+      else children.set(frame.parentFrameId, [frame]);
+    }
+  }
+  const projections = new Map<string, FrameProjectionState | null>();
+  const result: NormalizedFrameDocument[] = [];
+  let targetProjection: GeometryProjection | null = null;
+  const targetRoot = rootFrameId ? frameById.get(rootFrameId) : undefined;
+  if (target.sessionId && targetRoot) {
+    try {
+      const known = await geometry.frame(targetRoot.frameId);
+      if (known && cdpTargetKey(known.target) === cdpTargetKey(target))
+        targetProjection = await geometry.targetProjection(targetRoot.frameId);
+    } catch (error) {
+      if (isCaptureAbort(error)) throw error;
+    }
+  }
+  const checkpoint = createCaptureCheckpoint(signal);
+  const visited = new Set<string>();
+  const remaining = frames[Symbol.iterator]();
+  for (let cursor = 0; visited.size < frames.length; cursor++) {
+    if (cursor >= pending.length) {
+      let next = remaining.next();
+      while (!next.done && visited.has(next.value.frameId)) next = remaining.next();
+      if (next.done) break;
+      pending.push(next.value);
+    }
+    if (cursor % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const frame = pending[cursor];
+    if (visited.has(frame.frameId)) continue;
+    visited.add(frame.frameId);
+    for (const child of children.get(frame.frameId) ?? []) pending.push(child);
+    const doc = sources.get(frame.frameId);
+    if (!doc) continue;
+    const source = { target, frameId: frame.frameId };
+    const coordinates = snapshotCoordinates(
+      doc,
+      layoutUnitsPerCssPixel,
+      frame.frameId === rootFrameId
+        ? { x: metrics.cssLayoutViewport?.pageX, y: metrics.cssLayoutViewport?.pageY }
+        : undefined,
+    );
+    let state: FrameProjectionState | null =
+      frame.frameId === rootFrameId
+        ? viewportAvailable && coordinates
+          ? {
+              status: "available",
+              projection: {
+                source,
+                geometry: { sourceClips: [], edges: [], topViewport: viewport },
+              },
+            }
+          : { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" }
+        : (projections.get(frame.frameId) ?? null);
+    if (!state && frame.frameId !== rootFrameId)
+      issues.push({
+        target,
+        frameId: frame.frameId,
+        stage: "ownership",
+        reason: "frame-ownership-unresolved",
+      });
+    if (!coordinates && (!state || state.status === "available"))
+      state = { status: "unavailable", source, reason: "snapshot-coordinates-unavailable" };
+    projections.set(frame.frameId, state);
+    const projection = state?.status === "available" ? state.projection : null;
+    if (!projection || (target.sessionId && !targetProjection))
+      issues.push({
+        target,
+        frameId: frame.frameId,
+        stage: "geometry",
+        reason: "geometry-unavailable",
+        ...(state && state.status !== "available" ? { projectionIssue: state } : {}),
+      });
+
+    // Only direct siblings share this pool. Keep normalization in its existing
+    // breadth-first order, independent of owner read completion order.
+    const siblings = (children.get(frame.frameId) ?? []).filter((child) =>
+      sources.has(child.frameId),
+    );
+    const edge = projection?.geometry.edges[0];
+    const clips = edge
+      ? [edge.destinationQuad, ...(edge.destinationClips ?? [])]
+      : (projection?.geometry.sourceClips ?? []);
+    let next = 0;
+    let failure: unknown;
+    await Promise.all(
+      Array.from({ length: Math.min(4, siblings.length) }, async () => {
+        while (next < siblings.length && !signal?.aborted && !failure) {
+          const child = siblings[next++];
+          const childSource = { target, frameId: child.frameId };
+          if (!projection) {
+            projections.set(
+              child.frameId,
+              state && state.status !== "available"
+                ? {
+                    status: "blocked",
+                    source: childSource,
+                    cause: state.status === "blocked" ? state.cause : state,
+                  }
+                : null,
+            );
+            continue;
+          }
+          if (child.ownerBackendNodeId === undefined) {
+            projections.set(child.frameId, null);
+            continue;
+          }
+          if (!snapshotCoordinates(sources.get(child.frameId)!, layoutUnitsPerCssPixel)) {
+            projections.set(child.frameId, {
+              status: "unavailable",
+              source: childSource,
+              reason: "snapshot-coordinates-unavailable",
+            });
+            continue;
+          }
+          try {
+            projections.set(
+              child.frameId,
+              await geometry.snapshotProjection(
+                childSource,
+                child.ownerBackendNodeId,
+                clips,
+                viewport,
+              ),
+            );
+          } catch (error) {
+            failure ??= error;
+          }
+        }
+      }),
+    );
+    // Join active reads and their cleanup before returning cancellation.
+    if (failure) throw failure;
+    throwCaptureAborted(signal);
+    const normalized = await normalizeDocument(
+      doc,
+      strings,
+      {
+        frameId: frame.frameId,
+        ownerFrameBackendNodeId: frame.ownerBackendNodeId ?? null,
+        projection: state,
+        ...(profile.includeVisualFacts
+          ? { pageScale: metrics.cssVisualViewport?.scale ?? metrics.visualViewport?.scale }
+          : {}),
+        target,
+        ...(target.sessionId ? { targetProjection } : {}),
+        coordinates,
+      },
+      signal,
+      profile,
+    );
+    result.push({ ...normalized, frame });
+  }
+  return result;
+}

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

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

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

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

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

@@ -0,0 +1,322 @@
+import { type CdpFrame, type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { CapturedNode } from "./capture-types";
+import type { DecodedDocument, DecodedNode } from "./facts";
+export const REQUESTED_STYLES = [
+  "position",
+  "pointer-events",
+  "cursor",
+  "visibility",
+  "opacity",
+] as const;
+export const VISUAL_STYLES = [
+  ...REQUESTED_STYLES,
+  "display",
+  "overflow-x",
+  "overflow-y",
+  "transform",
+  "zoom",
+  "clip-path",
+  "mask-image",
+  "rotate",
+  "scale",
+  "perspective",
+  "clip",
+  "contain",
+  "overflow-clip-margin",
+] as const;
+
+/** The same profile owns request columns, decoding and visual-only derived facts. */
+export const BASIC_SNAPSHOT = {
+  includeVisualFacts: false,
+  computedStyles: REQUESTED_STYLES,
+} as const;
+export const VISUAL_SNAPSHOT = { includeVisualFacts: true, computedStyles: VISUAL_STYLES } as const;
+export type SnapshotProfile = typeof BASIC_SNAPSHOT | typeof VISUAL_SNAPSHOT;
+/** Sparse array format Chrome uses for infrequently-set per-node fields. */
+interface SparseArray {
+  index: number[];
+  value: number[];
+}
+
+interface RareBooleanData {
+  index: number[];
+}
+
+export interface SnapshotDocument {
+  frameId?: string | number;
+  documentURL?: number;
+  scrollOffsetX?: number;
+  scrollOffsetY?: number;
+  nodes?: {
+    parentIndex?: number[];
+    nodeName?: number[];
+    nodeType?: number[];
+    backendNodeId?: number[];
+    attributes?: number[][];
+    /**
+     * Per-node text value (index into strings), set for `#text` / CDATA nodes.
+     * Element nodes carry -1. Same length as `backendNodeId`.
+     */
+    nodeValue?: number[];
+    /** Maps node array index → index into `documents[]` for frame content. */
+    contentDocumentIndex?: SparseArray;
+    inputValue?: SparseArray;
+    textValue?: SparseArray;
+    inputChecked?: RareBooleanData;
+    optionSelected?: RareBooleanData;
+  };
+  layout?: {
+    nodeIndex?: number[];
+    styles?: number[][];
+    bounds?: number[][];
+    clientRects?: number[][];
+    paintOrders?: number[];
+  };
+}
+
+export function snapshotFrameId(document: SnapshotDocument, strings: string[]): string | undefined {
+  if (typeof document.frameId === "string") return document.frameId || undefined;
+  if (typeof document.frameId === "number") return str(strings, document.frameId) || undefined;
+  return undefined;
+}
+
+export interface SnapshotReply {
+  strings?: string[];
+  documents?: SnapshotDocument[];
+}
+
+function isSensitiveFormControl(node: Pick<CapturedNode, "tag" | "attrs">): boolean {
+  return node.tag === "input" && (node.attrs.type ?? "").toLowerCase() === "password";
+}
+
+function snapshotFormState(
+  value: string | undefined,
+  defaultValue: string,
+  hasDefaultValue: boolean,
+  sensitive: boolean,
+): CapturedNode["formState"] {
+  if (sensitive) {
+    if (value === undefined && !hasDefaultValue) return undefined;
+    return (value ?? defaultValue) === "" ? "empty" : "filled";
+  }
+  if (value === undefined) return undefined;
+  if (value === "") return "empty";
+  return value === defaultValue ? "default" : "filled";
+}
+
+function str(strings: string[], idx: number | undefined): string {
+  if (idx === undefined || idx < 0) return "";
+  return strings[idx] ?? "";
+}
+
+export function sparseIndexMap(sparse: SparseArray | undefined): Map<number, number> {
+  const out = new Map<number, number>();
+  if (!sparse?.index || !sparse.value) return out;
+  for (let i = 0; i < sparse.index.length; i++) {
+    const nodeIndex = sparse.index[i];
+    const docIndex = sparse.value[i];
+    if (nodeIndex !== undefined && docIndex !== undefined) out.set(nodeIndex, docIndex);
+  }
+  return out;
+}
+
+export async function decodeDocument(
+  doc: SnapshotDocument,
+  strings: string[],
+  signal?: AbortSignal,
+  profile: SnapshotProfile = BASIC_SNAPSHOT,
+): Promise<DecodedDocument> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  const dn = doc.nodes;
+  const dl = doc.layout;
+  if (!dn?.backendNodeId) {
+    return { nodes: [] };
+  }
+
+  const count = dn.backendNodeId.length;
+  const layoutByNode = new Map<number, number>();
+  for (let i = 0; i < (dl?.nodeIndex?.length ?? 0); i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    layoutByNode.set(dl!.nodeIndex![i], i);
+  }
+
+  const inputValues = sparseIndexMap(dn.inputValue);
+  const textValues = sparseIndexMap(dn.textValue);
+  const checkedInputs = new Set(dn.inputChecked?.index ?? []);
+  const selectedOptions = new Set(dn.optionSelected?.index ?? []);
+
+  // Collect visible text from #text child nodes so element CapturedNodes
+  // carry a textContent value usable as a button/link label fallback.
+  // nodeValue is a parallel array: string index for text nodes, -1 otherwise.
+  const nodeTextContent = new Map<number, string[]>();
+  if (dn.nodeValue) {
+    for (let n = 0; n < count; n++) {
+      if (n % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      const nvIdx = dn.nodeValue[n] ?? -1;
+      if (nvIdx < 0) continue;
+      const text = str(strings, nvIdx).trim();
+      if (!text) continue;
+      const parentIdx = dn.parentIndex?.[n] ?? -1;
+      if (parentIdx >= 0) {
+        const existing = nodeTextContent.get(parentIdx);
+        if (existing) existing.push(text);
+        else nodeTextContent.set(parentIdx, [text]);
+      }
+    }
+  }
+
+  // Decode fields without assigning a coordinate projection or semantic policy.
+  const nodes: DecodedNode[] = [];
+  for (let n = 0; n < count; n++) {
+    if (n % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const backendNodeId = dn.backendNodeId[n];
+    const parentIdx = dn.parentIndex?.[n] ?? -1;
+    const parentBackendNodeId = parentIdx >= 0 ? (dn.backendNodeId[parentIdx] ?? null) : null;
+    const tag = str(strings, dn.nodeName?.[n]).toLowerCase();
+
+    const attrs: Record<string, string> = {};
+    const pairs = dn.attributes?.[n] ?? [];
+    for (let a = 0; a + 1 < pairs.length; a += 2) {
+      attrs[str(strings, pairs[a]).toLowerCase()] = str(strings, pairs[a + 1]);
+    }
+
+    const li = layoutByNode.get(n);
+    const styleRow = li === undefined ? [] : (dl?.styles?.[li] ?? []);
+    const styles: Record<string, string> = {};
+    for (let i = 0; i < profile.computedStyles.length; i++)
+      styles[profile.computedStyles[i]] = str(strings, styleRow[i]);
+    const layout =
+      li === undefined
+        ? undefined
+        : {
+            boundsSpace: "snapshot-document-layout" as const,
+            bounds: dl?.bounds?.[li],
+            ...(profile.includeVisualFacts && dl?.clientRects?.[li]
+              ? { clientRect: dl.clientRects[li] }
+              : {}),
+            styles,
+          };
+
+    const textContent = nodeTextContent.get(n)?.join(" ");
+
+    const rawFormValueIndex = tag === "textarea" ? textValues.get(n) : inputValues.get(n);
+    const rawFormValue =
+      rawFormValueIndex !== undefined ? str(strings, rawFormValueIndex) : undefined;
+    const sensitive = isSensitiveFormControl({ tag, attrs });
+    const formDefaultValue = attrs.value ?? "";
+    const formValue = sensitive ? undefined : rawFormValue;
+    const formState = snapshotFormState(
+      rawFormValue,
+      formDefaultValue,
+      Object.prototype.hasOwnProperty.call(attrs, "value"),
+      sensitive,
+    );
+    if (sensitive) delete attrs.value;
+
+    nodes.push({
+      backendNodeId,
+      nodeType: dn.nodeType?.[n],
+      parentBackendNodeId,
+      ...(profile.includeVisualFacts &&
+      (dn.parentIndex?.[n] === undefined || (parentIdx >= 0 && parentBackendNodeId === null))
+        ? { parentMissing: true }
+        : {}),
+
+      tag,
+      attrs,
+      layout,
+      paintOrder: li === undefined ? 0 : (dl?.paintOrders?.[li] ?? 0),
+      position: styles.position || "static",
+      pointerEvents: styles["pointer-events"] || "auto",
+      cursor: styles.cursor || "auto",
+
+      textContent,
+      ...(formValue !== undefined ? { formValue } : {}),
+      ...(tag === "input" || tag === "textarea"
+        ? {
+            formPlaceholder: attrs.placeholder ?? "",
+            ...(!sensitive ? { formDefaultValue } : {}),
+            ...(formState ? { formState } : {}),
+          }
+        : {}),
+      ...(checkedInputs.has(n) ? { formValue: "true", formState: "filled" } : {}),
+      ...(selectedOptions.has(n) ? { formValue: attrs.value ?? textContent ?? "" } : {}),
+    });
+  }
+  return { nodes };
+}
+
+/** Snapshot membership and same-target edges are current response evidence.
+ * The earlier graph only supplies compatible metadata and cross-target edges. */
+export function describeSnapshotFrames(
+  snapshot: SnapshotReply,
+  target: CdpTarget,
+  hintById: ReadonlyMap<string, CdpFrame>,
+  pageUrl?: string,
+): { frames: CdpFrame[]; ids: Set<string>; rootFrameId?: string } {
+  const raw = snapshot.documents ?? [];
+  const strings = snapshot.strings ?? [];
+  const ids = new Set<string>();
+  const invalid = new Set<string>();
+  const frames = raw.map((doc) => {
+    const frameId = snapshotFrameId(doc, strings);
+    if (!frameId) return undefined;
+    if (ids.has(frameId)) invalid.add(frameId);
+    ids.add(frameId);
+    const hint = hintById.get(frameId);
+    const compatible =
+      hint && cdpTargetKey(hint.target) === cdpTargetKey(target) ? hint : undefined;
+    const url =
+      (doc.documentURL === undefined ? undefined : strings[doc.documentURL]) || compatible?.url;
+    return { frameId, target, ...(url ? { url } : {}) } as CdpFrame;
+  });
+  const root = frames[0];
+  if (root) {
+    const hint = hintById.get(root.frameId);
+    const parent = hint?.parentFrameId ? hintById.get(hint.parentFrameId) : undefined;
+    if (
+      target.sessionId &&
+      hint &&
+      cdpTargetKey(hint.target) === cdpTargetKey(target) &&
+      parent &&
+      cdpTargetKey(parent.target) !== cdpTargetKey(target)
+    ) {
+      root.parentFrameId = parent.frameId;
+      root.ownerBackendNodeId = hint.ownerBackendNodeId;
+    }
+    if (!target.sessionId && !root.url && pageUrl) root.url = pageUrl;
+  }
+  const owned = new Set<string>();
+  for (let i = 0; i < raw.length; i++) {
+    const edges = raw[i].nodes?.contentDocumentIndex;
+    const parent = frames[i];
+    if (!parent || !edges) continue;
+    for (let e = 0; e < edges.index.length; e++) {
+      const child = frames[edges.value[e]];
+      const owner = raw[i].nodes?.backendNodeId?.[edges.index[e]];
+      if (!child || owner === undefined) continue;
+      if (child === root || child === parent || owned.has(child.frameId)) {
+        invalid.add(child.frameId);
+        continue;
+      }
+      owned.add(child.frameId);
+      child.parentFrameId = parent.frameId;
+      child.ownerBackendNodeId = owner;
+    }
+  }
+  return {
+    frames: frames.filter((frame): frame is CdpFrame => !!frame && !invalid.has(frame.frameId)),
+    ids,
+    rootFrameId: root?.frameId,
+  };
+}

apps/extension/src/tools/vom/visual-dedup.ts

@@ -0,0 +1,64 @@
+import { createCaptureCheckpoint } from "./capture-abort";
+import type { VisualCandidate, VisualDiscoveryResult } from "./visual-discovery";
+
+export const MAX_VISUAL_DEDUP_KEYS = 50_000;
+
+export interface VisualDedupResult extends VisualDiscoveryResult {
+  /** Known valid candidates in this capture, not the total Canvas count on the page. */
+  readonly candidateCount: number;
+  /** Candidates actually removed by exact coverage deduplication. */
+  readonly deduplicatedCount: number;
+  readonly dedupDegraded: boolean;
+}
+
+/** Keep the first real anchor for each exact DOM/parent/crop key, in encounter order.
+ * Once the key set is full, unknown keys pass through: capacity never drops candidates. */
+export async function deduplicateVisualCandidates(
+  discovery: VisualDiscoveryResult,
+  signal?: AbortSignal,
+): Promise<VisualDedupResult> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  const keys = new Set<string>();
+  const candidates: VisualCandidate[] = [];
+  let deduplicatedCount = 0;
+  let dedupDegraded = false;
+  for (let i = 0; i < discovery.candidates.length; i++) {
+    if (i % 256 === 0) {
+      const pending = checkpoint();
+      if (pending) await pending;
+    }
+    const candidate = discovery.candidates[i];
+    const {
+      document,
+      region: { crop },
+    } = candidate;
+    const key = JSON.stringify([
+      document.attachmentId,
+      document.target.tabId,
+      document.target.sessionId ?? null,
+      document.frameId,
+      document.documentElementBackendNodeId,
+      candidate.parentBackendNodeId,
+      crop.x,
+      crop.y,
+      crop.width,
+      crop.height,
+    ]);
+    if (keys.has(key)) {
+      deduplicatedCount++;
+      continue;
+    }
+    if (keys.size < MAX_VISUAL_DEDUP_KEYS) keys.add(key);
+    else dedupDegraded = true;
+    candidates.push(candidate);
+  }
+  const pending = checkpoint();
+  if (pending) await pending;
+  return {
+    ...discovery,
+    candidates,
+    candidateCount: discovery.candidates.length,
+    deduplicatedCount,
+    dedupDegraded,
+  };
+}

apps/extension/src/tools/vom/visual-discovery.ts

@@ -0,0 +1,321 @@
+import { type CdpTarget } from "@/browser-driver/frame-graph";
+import type { ViewportRect } from "../geometry";
+import { createCaptureCheckpoint } from "./capture-abort";
+import type {
+  CaptureIssue,
+  DocumentFacts,
+  DocumentIdentity,
+  NodeFacts,
+  ObservationFacts,
+} from "./facts";
+import type { FrameOwnedAxNode } from "./frame-document";
+import {
+  EMPTY_VISUAL_CONTEXT,
+  extendVisualContext,
+  projectVisualBox,
+  resolveVisualRegion,
+  type VisualContext,
+  type VisualIssueReason,
+  type VisualRegionResult,
+  visualProjectionIssue,
+} from "./visual-region";
+
+export interface VisualCandidate {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly parentBackendNodeId: number | null;
+  readonly label?: string;
+  readonly region: Extract<VisualRegionResult, { status: "available" }>;
+}
+
+export type VisualDiscoveryIssue =
+  | {
+      readonly reason: "visual-facts-not-collected";
+      readonly target?: never;
+      readonly frameId?: never;
+      readonly backendNodeId?: never;
+    }
+  | {
+      readonly target: CdpTarget;
+      readonly frameId: string;
+      readonly backendNodeId?: number;
+      readonly reason: VisualIssueReason;
+    };
+
+export interface VisualDiscoveryResult {
+  readonly candidates: readonly VisualCandidate[];
+  readonly issues: readonly VisualDiscoveryIssue[];
+  /** Preserve upstream failures, including those that do not invalidate Canvas geometry. */
+  readonly captureIssues: readonly CaptureIssue[];
+  readonly complete: boolean;
+}
+
+type Document = DocumentFacts<FrameOwnedAxNode>;
+interface NodeContext {
+  self: VisualContext;
+  children: VisualContext;
+}
+
+function viewportRect(
+  rect: { x: number; y: number; w: number; h: number } | null | undefined,
+): ViewportRect | null {
+  return rect ? { x: rect.x, y: rect.y, width: rect.w, height: rect.h } : null;
+}
+
+/** Client offsets are unscaled local CSS units. Only ordinary, untransformed
+ * overflow chains consume this adapter; other combinations are rejected by policy. */
+function clientBox(node: NodeFacts, document: Document): ViewportRect | null {
+  const client = node.layout?.clientRect;
+  const bounds = node.layout?.bounds;
+  const border =
+    node.localRect ??
+    (bounds?.length === 4 && bounds.every(Number.isFinite) && document.geometry
+      ? {
+          x:
+            bounds[0] / document.geometry.coordinates.layoutUnitsPerCssPixel -
+            document.geometry.coordinates.scrollCss.x,
+          y:
+            bounds[1] / document.geometry.coordinates.layoutUnitsPerCssPixel -
+            document.geometry.coordinates.scrollCss.y,
+        }
+      : null);
+  if (
+    !client ||
+    client.length !== 4 ||
+    !client.every(Number.isFinite) ||
+    client[2] < 0 ||
+    client[3] < 0 ||
+    !border ||
+    !document.geometry
+  )
+    return null;
+  return projectVisualBox(
+    { x: border.x + client[0], y: border.y + client[1], width: client[2], height: client[3] },
+    document.geometry.projections,
+  );
+}
+
+/** Pure Facts consumer: no CDP, ref registration, selection, or semantic keep/drop.
+ * Both frame and node ancestry are memoized in this call, using iterative walks. */
+export async function discoverVisualCandidates(
+  facts: ObservationFacts<FrameOwnedAxNode>,
+  signal?: AbortSignal,
+): Promise<VisualDiscoveryResult> {
+  const checkpoint = createCaptureCheckpoint(signal);
+  if (!facts.visualFactsCollected)
+    return {
+      candidates: [],
+      complete: false,
+      captureIssues: facts.issues,
+      issues: [{ reason: "visual-facts-not-collected" }],
+    };
+  let work = 0;
+  const candidates: VisualCandidate[] = [];
+  const issues: VisualDiscoveryIssue[] = [];
+  const documents = new Map(facts.documents.map((document) => [document.frame.frameId, document]));
+  const contexts = new Map<string, Map<number, NodeContext>>();
+  const roots = new Map<string, VisualContext>();
+
+  async function nodeContext(document: Document, id: number): Promise<NodeContext> {
+    const cache = contexts.get(document.frame.frameId)!;
+    const path: NodeFacts[] = [];
+    let node = document.index.nodes.get(id);
+    while (node && !cache.has(node.backendNodeId)) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (
+        !document.index.ancestryComplete?.get(node.backendNodeId) ||
+        path.length >= document.index.nodes.size
+      ) {
+        const incomplete = {
+          ...roots.get(document.frame.frameId)!,
+          issue: roots.get(document.frame.frameId)!.issue ?? ("ancestry-incomplete" as const),
+        };
+        cache.set(node.backendNodeId, { self: incomplete, children: incomplete });
+        break;
+      }
+      path.push(node);
+      node =
+        node.parentBackendNodeId === null
+          ? undefined
+          : document.index.nodes.get(node.parentBackendNodeId);
+    }
+    let parent = node
+      ? cache.get(node.backendNodeId)!.children
+      : roots.get(document.frame.frameId)!;
+    for (let i = path.length - 1; i >= 0; i--) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      const current = path[i];
+      let self = parent;
+      let children = parent;
+      if (document.index.excludedBackendNodeIds.has(current.backendNodeId)) {
+        self = children = { ...parent, hidden: true };
+      } else if (current.nodeType === 1) {
+        if (!current.layout) {
+          // An element without layout is not evidence that descendants are hidden
+          // (e.g. a boxless ancestor). Keep the missing style evidence explicit.
+          self = children = { ...parent, issue: parent.issue ?? "facts-unavailable" };
+        } else if (document.identity) {
+          const ancestor = {
+            document: document.identity,
+            backendNodeId: current.backendNodeId,
+            styles: current.layout.styles,
+            clientBox: clientBox(current, document),
+          };
+          children = extendVisualContext(
+            parent,
+            ancestor,
+            current.tag !== "iframe" && current.tag !== "frame",
+          );
+          self = current.tag === "canvas" ? extendVisualContext(parent, ancestor, false) : children;
+        }
+      }
+      const result = { self, children };
+      cache.set(current.backendNodeId, result);
+      parent = children;
+    }
+    return (
+      cache.get(id) ?? {
+        self: { ...parent, issue: "ancestry-incomplete" },
+        children: { ...parent, issue: "ancestry-incomplete" },
+      }
+    );
+  }
+
+  // Process parent documents first, independent of snapshot/target completion order.
+  for (const document of facts.documents) {
+    const path: Document[] = [];
+    const visiting = new Set<string>();
+    let current: Document | undefined = document;
+    while (current && !roots.has(current.frame.frameId)) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (visiting.has(current.frame.frameId)) {
+        roots.set(current.frame.frameId, {
+          ...EMPTY_VISUAL_CONTEXT,
+          issue: "ownership-unresolved",
+        });
+        contexts.set(current.frame.frameId, new Map());
+        break;
+      }
+      visiting.add(current.frame.frameId);
+      path.push(current);
+      current = current.frame.parentFrameId
+        ? documents.get(current.frame.parentFrameId)
+        : undefined;
+    }
+    for (let i = path.length - 1; i >= 0; i--) {
+      const doc = path[i];
+      const { frame } = doc;
+      let root: VisualContext = roots.get(frame.frameId) ?? EMPTY_VISUAL_CONTEXT;
+      if (frame.parentFrameId) {
+        const parent = documents.get(frame.parentFrameId);
+        if (
+          !parent ||
+          !roots.has(parent.frame.frameId) ||
+          frame.ownerBackendNodeId === undefined ||
+          !parent.identity
+        ) {
+          root = { ...root, issue: "ownership-unresolved" };
+        } else {
+          const owner = parent.index.nodes.get(frame.ownerBackendNodeId);
+          const ownerState = await nodeContext(parent, frame.ownerBackendNodeId);
+          root = {
+            ...ownerState.children,
+            // CSS visibility inside a child document cannot override its hidden owner.
+            hidden:
+              ownerState.children.hidden ||
+              owner?.layout?.styles.visibility === "hidden" ||
+              owner?.layout?.styles.visibility === "collapse",
+            // Frame scaling is already interpreted by the shared content-quad projection.
+            transformed: false,
+            localClip: false,
+            unpositionedClip: false,
+          };
+        }
+      } else if (frame.frameId !== facts.rootFrameId)
+        root = { ...root, issue: "ownership-unresolved" };
+      root = {
+        ...root,
+        issue:
+          root.issue ??
+          (!doc.identity ? "identity-unverified" : visualProjectionIssue(doc.geometry)),
+      };
+      roots.set(frame.frameId, root);
+      contexts.set(frame.frameId, new Map());
+    }
+  }
+
+  for (const document of facts.documents) {
+    for (const node of document.index.nodes.values()) {
+      if (work++ % 256 === 0) {
+        const pending = checkpoint();
+        if (pending) await pending;
+      }
+      if (node.tag !== "canvas" || document.index.excludedBackendNodeIds.has(node.backendNodeId))
+        continue;
+      // No layout/zero size is positive evidence of no screenshot area for this node.
+      if (!node.layout) continue;
+      const bounds = node.layout.bounds;
+      if (
+        bounds?.length === 4 &&
+        bounds.every(Number.isFinite) &&
+        (bounds[2] <= 0 || bounds[3] <= 0)
+      )
+        continue;
+      const context = (await nodeContext(document, node.backendNodeId)).self;
+      const local = viewportRect(node.localRect);
+      const borderBox =
+        local && document.geometry ? projectVisualBox(local, document.geometry.projections) : null;
+      const region = resolveVisualRegion({
+        borderBox,
+        frameVisibleBox: viewportRect(node.rect),
+        context,
+        visibility: node.layout.styles.visibility,
+      });
+      if (region.status === "unavailable") {
+        issues.push({
+          target: document.frame.target,
+          frameId: document.frame.frameId,
+          backendNodeId: node.backendNodeId,
+          reason: region.reason,
+        });
+      } else if (region.status === "available" && document.identity) {
+        const label = node.attrs["aria-label"]?.trim() || node.attrs.title?.trim();
+        candidates.push({
+          document: document.identity,
+          backendNodeId: node.backendNodeId,
+          parentBackendNodeId: node.parentBackendNodeId,
+          ...(label ? { label } : {}),
+          region,
+        });
+      }
+    }
+  }
+  // AX-only/missing documents have no Canvas nodes to carry the missing evidence.
+  const reportedFrames = new Set(issues.map((issue) => issue.frameId));
+  for (const document of facts.documents) {
+    const reason = roots.get(document.frame.frameId)?.issue;
+    if (
+      reason &&
+      !reportedFrames.has(document.frame.frameId) &&
+      (!document.identity || !document.index.nodes.size)
+    )
+      issues.push({ target: document.frame.target, frameId: document.frame.frameId, reason });
+  }
+  const pending = checkpoint();
+  if (pending) await pending;
+  return {
+    candidates,
+    issues,
+    captureIssues: facts.issues,
+    complete: issues.length === 0 && facts.issues.length === 0,
+  };
+}

apps/extension/src/tools/vom/visual-region.ts

@@ -0,0 +1,318 @@
+import {
+  type GeometryProjection,
+  type Polygon,
+  projectPolygon,
+  rectPolygon,
+  regionBounds,
+  type ViewportRect,
+} from "../geometry";
+import type { DocumentGeometry, DocumentIdentity } from "./facts";
+
+export type VisualIssueReason =
+  | "ancestry-incomplete"
+  | "facts-unavailable"
+  | "geometry-unavailable"
+  | "geometry-unsupported"
+  | "identity-unverified"
+  | "ownership-unresolved";
+
+/** Top viewport CSS coordinates. Unconstrained axes have infinite bounds. */
+export interface VisualClip {
+  readonly left: number;
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+}
+
+/** Shared persistent chain: one entry per clipping ancestor, not per Canvas. */
+export interface VisualClipSource {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly x: boolean;
+  readonly y: boolean;
+  readonly overflowX: string;
+  readonly overflowY: string;
+  readonly box: ViewportRect;
+  readonly parent?: VisualClipSource;
+}
+
+export interface VisualContext {
+  readonly clip: VisualClip;
+  readonly clips?: VisualClipSource;
+  readonly hidden: boolean;
+  /** A local CSS scale/zoom makes snapshot client offsets ambiguous. */
+  readonly transformed: boolean;
+  readonly localClip?: boolean;
+  /** Overflow between an absolute target and its nearest positioned ancestor. */
+  readonly unpositionedClip?: boolean;
+  readonly issue?: VisualIssueReason;
+}
+
+export const EMPTY_VISUAL_CONTEXT: VisualContext = {
+  clip: { left: -Infinity, top: -Infinity, right: Infinity, bottom: Infinity },
+  hidden: false,
+  transformed: false,
+};
+
+function axisRect(polygon: Polygon): boolean {
+  if (polygon.length !== 4 || polygon.some((p) => !Number.isFinite(p.x) || !Number.isFinite(p.y)))
+    return false;
+  const [a, b, c, d] = polygon;
+  return a.y === b.y && b.x === c.x && c.y === d.y && d.x === a.x && b.x > a.x && d.y > a.y;
+}
+
+/** Check evidence before projectRectToViewport can reduce a polygon to its bounds. */
+export function visualProjectionIssue(
+  geometry: DocumentGeometry | undefined,
+): VisualIssueReason | undefined {
+  if (!geometry || !geometry.projections.length || geometry.pageScale === undefined)
+    return "geometry-unavailable";
+  if (!Number.isFinite(geometry.pageScale) || geometry.pageScale <= 0)
+    return "geometry-unavailable";
+  if (geometry.pageScale !== 1) return "geometry-unsupported";
+  const { layoutUnitsPerCssPixel, scrollCss } = geometry.coordinates;
+  if (
+    !Number.isFinite(layoutUnitsPerCssPixel) ||
+    layoutUnitsPerCssPixel <= 0 ||
+    ![scrollCss.x, scrollCss.y].every(Number.isFinite)
+  )
+    return "geometry-unavailable";
+  for (const projection of geometry.projections) {
+    if (
+      ![projection.topViewport.width, projection.topViewport.height].every(
+        (n) => Number.isFinite(n) && n > 0,
+      )
+    )
+      return "geometry-unavailable";
+    if (projection.sourceClips.some((clip) => !axisRect(clip))) return "geometry-unsupported";
+    for (const edge of projection.edges) {
+      if (
+        ![edge.sourceViewport.width, edge.sourceViewport.height].every(
+          (n) => Number.isFinite(n) && n > 0,
+        )
+      )
+        return "geometry-unavailable";
+      if (!axisRect(edge.destinationQuad) || edge.destinationClips?.some((clip) => !axisRect(clip)))
+        return "geometry-unsupported";
+    }
+  }
+}
+
+/** Uses the same projection math as DOM geometry, without clipping away box origins. */
+export function projectVisualBox(
+  box: ViewportRect,
+  projections: readonly GeometryProjection[],
+): ViewportRect | null {
+  let polygon: Polygon = rectPolygon({ x: box.x, y: box.y, w: box.width, h: box.height });
+  for (const projection of projections)
+    for (const edge of projection.edges) polygon = projectPolygon(polygon, edge);
+  // Preserve zero-size client boxes: they can prove a fully clipped axis.
+  if (box.width === 0 || box.height === 0) {
+    const [a, , c] = polygon;
+    return { x: a.x, y: a.y, width: c.x - a.x, height: c.y - a.y };
+  }
+  return regionBounds([polygon]);
+}
+
+function axisTransformScale(value: string): [number, number] | null {
+  if (value === "none") return [1, 1];
+  const match = /^matrix(3d)?\(([^)]+)\)$/.exec(value);
+  if (!match) return null;
+  const values = match[2].split(",").map((part) => Number(part.trim()));
+  if (!values.every(Number.isFinite)) return null;
+  if (match[1])
+    return values.length === 16 &&
+      values[0] > 0 &&
+      values[5] > 0 &&
+      values[10] === 1 &&
+      values[15] === 1 &&
+      [1, 2, 3, 4, 6, 7, 8, 9, 11, 14].every((index) => values[index] === 0)
+      ? [values[0], values[5]]
+      : null;
+  return values.length === 6 && values[0] > 0 && values[3] > 0 && values[1] === 0 && values[2] === 0
+    ? [values[0], values[3]]
+    : null;
+}
+
+export interface VisualAncestor {
+  readonly document: DocumentIdentity;
+  readonly backendNodeId: number;
+  readonly styles: Readonly<Record<string, string>>;
+  /** Already in top viewport CSS units, from a source-specific adapter. */
+  readonly clientBox?: ViewportRect | null;
+}
+
+/** One ancestor step, reusable by discovery and the future live local adapter. */
+export function extendVisualContext(
+  parent: VisualContext,
+  node: VisualAncestor,
+  clipContents = true,
+): VisualContext {
+  const styles = node.styles;
+  const opacity = styles.opacity?.trim() ? Number(styles.opacity) : NaN;
+  const zoom = styles.zoom === "normal" ? 1 : styles.zoom?.trim() ? Number(styles.zoom) : NaN;
+  const scale =
+    styles.scale === "none" ? [1] : (styles.scale ?? "").trim().split(/\s+/).map(Number);
+  const scaleSupported =
+    scale.length >= 1 &&
+    scale.length <= 3 &&
+    scale.every((n) => Number.isFinite(n) && n > 0) &&
+    (scale.length < 3 || scale[2] === 1);
+  const transformScale = axisTransformScale(styles.transform ?? "");
+  // Identity/translation changes origins, which bounds already capture, but
+  // leaves client offsets in the same units. Only scaling makes them ambiguous.
+  const transformed =
+    parent.transformed ||
+    transformScale?.some((n) => n !== 1) === true ||
+    zoom !== 1 ||
+    scale.some((n) => n !== 1);
+  const hidden = parent.hidden || opacity === 0 || styles.display === "none";
+  let issue = parent.issue;
+  if (
+    !Number.isFinite(opacity) ||
+    !Number.isFinite(zoom) ||
+    zoom <= 0 ||
+    !styles.display ||
+    !styles.visibility
+  )
+    issue ??= "facts-unavailable";
+  if (!styles.transform || !styles["clip-path"] || !styles["mask-image"])
+    issue ??= "facts-unavailable";
+  else if (!transformScale || styles["clip-path"] !== "none" || styles["mask-image"] !== "none")
+    issue ??= "geometry-unsupported";
+
+  if (
+    !["rotate", "scale", "perspective", "clip", "contain", "overflow-clip-margin"].every(
+      (key) => styles[key],
+    )
+  )
+    issue ??= "facts-unavailable";
+  else if (
+    !scaleSupported ||
+    !["none", "0deg"].includes(styles.rotate) ||
+    styles.perspective !== "none" ||
+    styles.clip !== "auto" ||
+    /(?:^|\s)(paint|strict|content)(?:$|\s)/.test(styles.contain)
+  )
+    issue ??= "geometry-unsupported";
+  // Do not pretend every DOM ancestor clips out-of-flow descendants. Support
+  // the ordinary positioned-container case; other containing-block cases stay explicit.
+  if (
+    (styles.position === "absolute" && parent.unpositionedClip) ||
+    (styles.position === "fixed" && parent.localClip)
+  )
+    issue ??= "geometry-unsupported";
+  const overflow = [styles["overflow-x"], styles["overflow-y"]];
+  if (clipContents && overflow.includes("clip") && styles["overflow-clip-margin"] !== "0px")
+    issue ??= "geometry-unsupported";
+  if (
+    overflow.some(
+      (value) => !["visible", "hidden", "clip", "scroll", "auto", "overlay"].includes(value),
+    )
+  )
+    issue ??= "facts-unavailable";
+  const [x, y] = overflow.map((value) => value !== "visible");
+  let clip = parent.clip;
+  let clips = parent.clips;
+  if (clipContents && (x || y)) {
+    if (transformed) issue ??= "geometry-unsupported";
+    const box = node.clientBox;
+    if (
+      !box ||
+      ![box.x, box.y, box.width, box.height].every(Number.isFinite) ||
+      box.width < 0 ||
+      box.height < 0
+    )
+      issue ??= "geometry-unavailable";
+    else {
+      clip = {
+        left: x ? Math.max(clip.left, box.x) : clip.left,
+        right: x ? Math.min(clip.right, box.x + box.width) : clip.right,
+        top: y ? Math.max(clip.top, box.y) : clip.top,
+        bottom: y ? Math.min(clip.bottom, box.y + box.height) : clip.bottom,
+      };
+      clips = {
+        document: node.document,
+        backendNodeId: node.backendNodeId,
+        x,
+        y,
+        overflowX: styles["overflow-x"],
+        overflowY: styles["overflow-y"],
+        box,
+        parent: clips,
+      };
+    }
+  }
+  const clipsHere = clipContents && (x || y);
+  return {
+    hidden,
+    transformed,
+    issue,
+    clip,
+    clips,
+    localClip: parent.localClip || clipsHere,
+    unpositionedClip:
+      styles.position !== "static" ||
+      styles.transform !== "none" ||
+      /(?:^|\s)layout(?:$|\s)/.test(styles.contain ?? "")
+        ? false
+        : parent.unpositionedClip || clipsHere,
+  };
+}
+
+/** A page screenshot rectangle, not an exact mask of visible Canvas pixels.
+ * Rounded corners are rendered by the browser and do not invalidate this range. */
+export type VisualRegionResult =
+  | { status: "available"; borderBox: ViewportRect; crop: ViewportRect; clips?: VisualClipSource }
+  | { status: "empty" }
+  | { status: "unavailable"; reason: VisualIssueReason };
+
+/** Box and frameVisibleBox must come from the same box kind (Canvas border-box).
+ * Frame/viewport clipping is supplied by the shared geometry adapter. */
+export function resolveVisualRegion(input: {
+  borderBox: ViewportRect | null;
+  frameVisibleBox: ViewportRect | null;
+  context: VisualContext;
+  visibility: string;
+}): VisualRegionResult {
+  const { borderBox, frameVisibleBox, context, visibility } = input;
+  if (context.hidden || visibility === "hidden" || visibility === "collapse")
+    return { status: "empty" };
+  if (context.issue) return { status: "unavailable", reason: context.issue };
+  if (visibility !== "visible") return { status: "unavailable", reason: "facts-unavailable" };
+  if (!borderBox) return { status: "unavailable", reason: "geometry-unavailable" };
+  if (!frameVisibleBox) return { status: "empty" };
+  if (
+    ![
+      borderBox.x,
+      borderBox.y,
+      borderBox.width,
+      borderBox.height,
+      frameVisibleBox.x,
+      frameVisibleBox.y,
+      frameVisibleBox.width,
+      frameVisibleBox.height,
+    ].every(Number.isFinite)
+  )
+    return { status: "unavailable", reason: "geometry-unavailable" };
+  if (
+    borderBox.width <= 0 ||
+    borderBox.height <= 0 ||
+    frameVisibleBox.width < 0 ||
+    frameVisibleBox.height < 0 ||
+    Object.values(context.clip).some(Number.isNaN)
+  )
+    return { status: "unavailable", reason: "geometry-unavailable" };
+  const x = Math.max(frameVisibleBox.x, context.clip.left);
+  const y = Math.max(frameVisibleBox.y, context.clip.top);
+  const right = Math.min(frameVisibleBox.x + frameVisibleBox.width, context.clip.right);
+  const bottom = Math.min(frameVisibleBox.y + frameVisibleBox.height, context.clip.bottom);
+  return right > x && bottom > y
+    ? {
+        status: "available",
+        borderBox,
+        crop: { x, y, width: right - x, height: bottom - y },
+        clips: context.clips,
+      }
+    : { status: "empty" };
+}

apps/extension/src/transport/types.ts

@@ -26,11 +26,17 @@ export type RpcErrorReason =
   | "ref_not_found"
   | "selector_not_found"
   | "target_not_fillable"
+  | "fill_value_invalid"
+  | "fill_target_changed"
+  | "fill_focus_lost"
+  | "fill_value_mismatch"
+  | "fill_failed"
   | "target_not_select"
   | "option_not_found"
   | "single_select_value_count"
   | "tab_not_active"
   | "restricted_tab_url"
+  | "cdp_extension_access_denied"
   | "borrow_conflict"
   | "screenshot_capture_failed"
   | "file_input_probe_failed"
@@ -464,6 +470,59 @@ export interface HoverResult {
   dialogs?: JavaScriptDialogInfo[];
 }
 
+export interface ScrollToParams {
+  session_id: string;
+  ref?: string;
+  selector?: string;
+  tab_id?: number;
+  timeout_ms?: number;
+}
+
+export interface ScrollToResult {
+  tab_id: number;
+  used_ref?: string;
+  used_selector?: string;
+  /** Clipped border-box bounds in top-level viewport CSS pixels; not an occlusion test. */
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  dialogs?: JavaScriptDialogInfo[];
+}
+
+export interface FocusParams {
+  session_id: string;
+  ref?: string;
+  selector?: string;
+  tab_id?: number;
+  timeout_ms?: number;
+}
+
+export interface FocusResult {
+  tab_id: number;
+  used_ref?: string;
+  used_selector?: string;
+  focused: boolean;
+  dialogs?: JavaScriptDialogInfo[];
+}
+
+export interface BlurParams {
+  session_id: string;
+  ref?: string;
+  selector?: string;
+  tab_id?: number;
+  timeout_ms?: number;
+}
+
+export interface BlurResult {
+  tab_id: number;
+  used_ref?: string;
+  used_selector?: string;
+  was_focused: boolean;
+  focused: boolean;
+  dialogs?: JavaScriptDialogInfo[];
+}
+
 export interface FillParams {
   session_id: string;
   value: string;

crates/bsk-cli/skill/SKILL.md

@@ -55,10 +55,20 @@ Use this default loop:
 ```text
 bsk navigate <url> --session <id>
 bsk observe --session <id>
-bsk click|hover|fill|select|press ... --session <id>
+bsk click|hover|scroll-to|focus|blur|fill|select|press ... --session <id>
 bsk observe --session <id>             # after navigation or a meaningful DOM change
 ```
 
+`bsk scroll-to <ref-or-selector> --session <id>` scrolls an element and its frame owners into view.
+Use a fresh element ref for iframe/shadow-root targets; CSS selectors search the main document.
+The result is the visible border-box portion's bounds in top-level viewport CSS pixels after
+ancestor clipping. Partial visibility is enough; hidden or fully clipped targets fail with
+`permission_denied` and `data.reason=element_not_visible`. This does not test occlusion by other elements.
+For a specific tab or deadline: `bsk scroll-to @e3 --session <id> --tab-id 42 --timeout 5s`.
+
+`bsk focus <ref>` explicitly focuses a target; `bsk blur <ref>` removes focus and reports whether
+it was focused. Use these for UI states triggered by focus changes.
+
 Prefer fresh `@eN` refs over CSS selectors. Navigation invalidates refs; large DOM changes may also
 make them stale. Observe again before the next interaction.
 
@@ -114,7 +124,7 @@ This list of names is complete. Never invent a command outside it; read
 session start|stop|list   browsers   status   doctor   update   logs
 navigate   navigate-back   navigate-forward   reload   wait-for-navigation   wait-ms
 observe   snapshot   get-html   screenshot   console   network
-click   hover   fill   select   press   evaluate
+click   hover   scroll-to   focus   blur   fill   select   press   evaluate
 tab list|create|close|select|borrow|return   window resize   emulate
 upload   download   request-help   record start|stop
 ```
@@ -172,6 +182,10 @@ intended. Read `bsk upload --help` and `bsk download --help` for all flags and e
 - Stale ref: observe again and retry the intended action once.
 - Unknown tab or session: list current tabs/sessions; never guess identifiers.
 - Timeout: inspect current page state before deciding whether one longer purposeful wait is useful.
+- Fill result unconfirmed (`fill_value_mismatch`): observe the field first; the page may have
+  formatted the value. Continue if the visible result satisfies the user's intent. Otherwise correct
+  the remaining difference; do not blindly repeat fill or immediately request human help. For other
+  fill errors, follow the returned hint and inspect current state before retrying.
 - Unsupported command: continue with available capabilities; suggest updating only when the missing
   command is necessary.
 - Unrecoverable failure: report the blocker and stop the session in a finally-style path.

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

@@ -73,6 +73,14 @@ where
     P: Serialize + Send + 'static,
     R: DeserializeOwned + Send + 'static,
 {
+    let parent_cancel = stdin_cancellation();
+    if parent_cancel.as_ref().is_some_and(|rx| *rx.borrow()) {
+        return Err(CliError::from_rpc(RpcError {
+            code: ErrorCode::Cancelled,
+            message: "parent closed the cancellation pipe".into(),
+            data: Some(serde_json::json!({"reason": "cancelled_before_dispatch"})),
+        }));
+    }
     let rpc_id: RpcId = format!("{}-{}", rpc_id_prefix, random_short_id());
     let mut client = IpcClient::connect(sock.clone()).await?;
     let rpc_id_for_call = rpc_id.clone();
@@ -88,16 +96,16 @@ where
     let outcome = tokio::select! {
         biased;
         res = &mut main_fut => res?,
-        sig = wait_for_sigint() => {
-            sig.context("install SIGINT handler").map_err(CliError::Local)?;
-            debug!(rpc_id = %rpc_id_for_cancel, "SIGINT: forwarding cancel to daemon");
+        sig = wait_for_cancel(parent_cancel) => {
+            sig.context("wait for cancellation").map_err(CliError::Local)?;
+            debug!(rpc_id = %rpc_id_for_cancel, "forwarding cancel to daemon");
             let _ = send_cancel(&sock, &rpc_id_for_cancel).await;
             match tokio::time::timeout(CANCEL_RESPONSE_GRACE, &mut main_fut).await {
                 Ok(res) => res?,
                 Err(_) => {
                     debug!(
                         rpc_id = %rpc_id_for_cancel,
-                        "SIGINT: cancel grace elapsed; synthesising cancelled error"
+                        "cancel grace elapsed; synthesising cancelled error"
                     );
                     return Err(CliError::from_rpc(RpcError {
                         code: ErrorCode::Cancelled,
@@ -112,6 +120,46 @@ where
     outcome.map_err(CliError::from_rpc)
 }
 
+/// Release caller-owned staging even after cancellation. This deliberately
+/// exposes only transfer.release, not a general bypass for business RPCs.
+/// The entire batch, including connection setup, shares one bounded budget.
+pub fn release_transfers<'a>(
+    sock: &Path,
+    transfer_ids: impl IntoIterator<Item = &'a str>,
+) -> Result<(), CliError> {
+    use bsk_protocol::tools::{TransferIdParams, TransferReleaseResult};
+    const CLEANUP_TIMEOUT: Duration = Duration::from_secs(5);
+    let ids: Vec<_> = transfer_ids.into_iter().collect();
+    if ids.is_empty() {
+        return Ok(());
+    }
+    let rt = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .context("build runtime for transfer cleanup")?;
+    rt.block_on(async {
+        tokio::time::timeout(CLEANUP_TIMEOUT, async {
+            let mut client = IpcClient::connect(sock).await?;
+            for id in ids {
+                client
+                    .call::<_, TransferReleaseResult>(
+                        "transfer-release",
+                        Method::TransferRelease,
+                        Some(TransferIdParams {
+                            transfer_id: id.to_string(),
+                        }),
+                        CLEANUP_TIMEOUT,
+                    )
+                    .await?
+                    .map_err(CliError::from_rpc)?;
+            }
+            Ok::<_, CliError>(())
+        })
+        .await
+        .context("transfer cleanup exceeded its total time budget")?
+    })
+}
+
 /// Send a `cancel { rpc_id }` frame over a fresh connection so it
 /// lands on the daemon while the original call is still parked.
 ///
@@ -146,8 +194,57 @@ fn random_short_id() -> String {
     bytes.iter().map(|b| format!("{b:02x}")).collect()
 }
 
-/// Wait for either Ctrl-C or process SIGTERM. Returning here means
-/// the user has asked us to stop.
+/// Opt-in control pipe for parent processes that cannot send Ctrl-C (Node on
+/// Windows). One reader survives the short-lived runtimes used by multi-RPC
+/// commands such as upload. Ordinary CLI stdin and terminal Ctrl-C are unchanged.
+fn stdin_cancellation() -> Option<tokio::sync::watch::Receiver<bool>> {
+    if std::env::var("BSK_CANCEL_ON_STDIN_CLOSE").as_deref() != Ok("1") {
+        return None;
+    }
+    static CANCEL: std::sync::OnceLock<tokio::sync::watch::Receiver<bool>> =
+        std::sync::OnceLock::new();
+    Some(
+        CANCEL
+            .get_or_init(|| {
+                let (tx, rx) = tokio::sync::watch::channel(false);
+                std::thread::spawn(move || {
+                    use std::io::Read;
+                    let mut stdin = std::io::stdin().lock();
+                    let mut buf = [0; 64];
+                    loop {
+                        match stdin.read(&mut buf) {
+                            Ok(0) => break,
+                            Ok(_) => {}
+                            Err(err) if err.kind() == std::io::ErrorKind::Interrupted => continue,
+                            Err(_) => break,
+                        }
+                    }
+                    let _ = tx.send(true);
+                });
+                rx
+            })
+            .clone(),
+    )
+}
+
+async fn wait_for_cancel(
+    parent_cancel: Option<tokio::sync::watch::Receiver<bool>>,
+) -> anyhow::Result<()> {
+    let parent_closed = async move {
+        match parent_cancel {
+            Some(mut rx) => {
+                let _ = rx.wait_for(|closed| *closed).await;
+            }
+            None => std::future::pending::<()>().await,
+        }
+    };
+    tokio::select! {
+        result = wait_for_sigint() => result,
+        _ = parent_closed => Ok(()),
+    }
+}
+
+/// Wait for terminal Ctrl-C.
 async fn wait_for_sigint() -> anyhow::Result<()> {
     tokio::signal::ctrl_c().await.context("listen for SIGINT")?;
     Ok(())

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

@@ -9,8 +9,7 @@ use anyhow::Context;
 use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
-    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult, TransferIdParams,
-    TransferReleaseResult,
+    DownloadParams, DownloadResult, TransferChunkParams, TransferChunkResult,
 };
 use clap::Args;
 use uuid::Uuid;
@@ -70,13 +69,7 @@ pub fn dispatch(args: DownloadArgs, format: Format) -> Result<(), CliError> {
         CliError::Local(anyhow::anyhow!("daemon returned no download transfer id"))
     })?;
     let write_result = write_transfer(&info.sock_path, &transfer_id, &args.out, args.overwrite);
-    let _: Result<TransferReleaseResult, CliError> = crate::cli::business_rpc::call(
-        info.sock_path,
-        "transfer-release",
-        Method::TransferRelease,
-        Some(TransferIdParams { transfer_id }),
-        Duration::from_secs(5),
-    );
+    let _ = crate::cli::business_rpc::release_transfers(&info.sock_path, [transfer_id.as_str()]);
     write_result?;
     match format {
         Format::Json => {

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

@@ -1,4 +1,5 @@
-//! `bsk click` / `bsk fill` / `bsk press` (M7 interaction tools).
+//! `bsk click` / `bsk focus` / `bsk blur` / `bsk fill` / `bsk press`
+//! interaction tools.
 //!
 //! The `<target>` positional accepts either a snapshot ref (`@e3`,
 //! `e3`) or a CSS selector. Use `--ref` / `--selector` explicitly when
@@ -10,8 +11,9 @@ use std::time::Duration;
 use anyhow::Context;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
-    ClickParams, ClickResult, FillParams, FillResult, HoverParams, HoverResult, KeyModifier,
-    MouseButton, PressParams, PressResult, SelectParams, SelectResult,
+    BlurParams, BlurResult, ClickParams, ClickResult, FillParams, FillResult, FocusParams,
+    FocusResult, HoverParams, HoverResult, KeyModifier, MouseButton, PressParams, PressResult,
+    SelectParams, SelectResult,
 };
 use clap::{Args, ValueEnum};
 
@@ -274,6 +276,124 @@ pub fn dispatch_hover(args: HoverArgs, format: Format) -> Result<(), CliError> {
     Ok(())
 }
 
+// ---------------------------------------------------------------------------
+// bsk focus / bsk blur
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, Args)]
+pub struct FocusArgs {
+    /// Snapshot ref (`@e3`, `e3`) or CSS selector. Optional when `--ref`/`--selector` is used.
+    pub target: Option<String>,
+
+    #[arg(long = "ref")]
+    pub ref_: Option<String>,
+
+    #[arg(long = "selector")]
+    pub selector: Option<String>,
+
+    #[arg(long)]
+    pub session: String,
+
+    #[arg(long = "tab-id")]
+    pub tab_id: Option<i64>,
+
+    #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
+    pub timeout: u32,
+}
+
+pub fn dispatch_focus(args: FocusArgs, format: Format) -> Result<(), CliError> {
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
+    let params = FocusParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        timeout_ms: Some(args.timeout),
+    };
+    let reply: FocusResult = call(
+        info.sock_path,
+        Method::ToolFocus,
+        params,
+        "focus-1",
+        args.timeout,
+    )?;
+    match format {
+        Format::Json => println!(
+            "{}",
+            serde_json::to_string_pretty(&reply)
+                .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
+        ),
+        Format::Human => {
+            let target =
+                format_used_target(reply.used_ref.as_deref(), reply.used_selector.as_deref());
+            println!(
+                "focus ok tab={} target={target} focused={}",
+                reply.tab_id, reply.focused
+            );
+            print_dialog_summaries(&reply.dialogs);
+        }
+    }
+    Ok(())
+}
+
+#[derive(Debug, Clone, Args)]
+pub struct BlurArgs {
+    /// Snapshot ref (`@e3`, `e3`) or CSS selector. Optional when `--ref`/`--selector` is used.
+    pub target: Option<String>,
+
+    #[arg(long = "ref")]
+    pub ref_: Option<String>,
+
+    #[arg(long = "selector")]
+    pub selector: Option<String>,
+
+    #[arg(long)]
+    pub session: String,
+
+    #[arg(long = "tab-id")]
+    pub tab_id: Option<i64>,
+
+    #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
+    pub timeout: u32,
+}
+
+pub fn dispatch_blur(args: BlurArgs, format: Format) -> Result<(), CliError> {
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
+    let params = BlurParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        timeout_ms: Some(args.timeout),
+    };
+    let reply: BlurResult = call(
+        info.sock_path,
+        Method::ToolBlur,
+        params,
+        "blur-1",
+        args.timeout,
+    )?;
+    match format {
+        Format::Json => println!(
+            "{}",
+            serde_json::to_string_pretty(&reply)
+                .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
+        ),
+        Format::Human => {
+            let target =
+                format_used_target(reply.used_ref.as_deref(), reply.used_selector.as_deref());
+            println!(
+                "blur ok tab={} target={target} was_focused={} focused={}",
+                reply.tab_id, reply.was_focused, reply.focused
+            );
+            print_dialog_summaries(&reply.dialogs);
+        }
+    }
+    Ok(())
+}
+
 // ---------------------------------------------------------------------------
 // bsk fill
 // ---------------------------------------------------------------------------

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

@@ -28,6 +28,7 @@ pub mod record_recovery;
 pub mod record_state;
 pub mod render_error;
 pub mod screenshot;
+pub mod scroll;
 pub mod session;
 pub mod snapshot;
 pub mod status;
@@ -47,12 +48,15 @@ use crate::cli::evaluate::EvaluateArgs;
 use crate::cli::get_html::GetHtmlArgs;
 use crate::cli::human_loop::RequestHelpArgs;
 use crate::cli::install_skill::InstallSkillArgs;
-use crate::cli::interaction::{ClickArgs, FillArgs, HoverArgs, PressArgs, SelectArgs};
+use crate::cli::interaction::{
+    BlurArgs, ClickArgs, FillArgs, FocusArgs, HoverArgs, PressArgs, SelectArgs,
+};
 use crate::cli::navigate::{NavigateCommand, NavigateHistoryArgs, ReloadArgs};
 use crate::cli::network::NetworkArgs;
 use crate::cli::observe::ObserveArgs;
 use crate::cli::record::RecordCmd;
 use crate::cli::screenshot::ScreenshotArgs;
+use crate::cli::scroll::ScrollToArgs;
 use crate::cli::session::SessionCmd;
 use crate::cli::snapshot::SnapshotArgs;
 use crate::cli::tab::TabCmd;
@@ -173,6 +177,16 @@ pub enum Command {
     /// Hover a snapshot ref or CSS selector.
     Hover(HoverArgs),
 
+    /// Scroll a snapshot ref or CSS selector into the visible viewport.
+    #[command(name = "scroll-to")]
+    ScrollTo(ScrollToArgs),
+
+    /// Focus a snapshot ref or CSS selector.
+    Focus(FocusArgs),
+
+    /// Remove focus from a snapshot ref or CSS selector.
+    Blur(BlurArgs),
+
     /// Fill an input / textarea / contenteditable.
     Fill(FillArgs),
 

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

@@ -43,10 +43,16 @@ pub mod reason {
     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";
+    pub const FILL_VALUE_INVALID: &str = "fill_value_invalid";
+    pub const FILL_TARGET_CHANGED: &str = "fill_target_changed";
+    pub const FILL_FOCUS_LOST: &str = "fill_focus_lost";
+    pub const FILL_VALUE_MISMATCH: &str = "fill_value_mismatch";
+    pub const FILL_FAILED: &str = "fill_failed";
     pub const TARGET_NOT_SELECT: &str = "target_not_select";
     pub const OPTION_NOT_FOUND: &str = "option_not_found";
     pub const SINGLE_SELECT_VALUE_COUNT: &str = "single_select_value_count";
     pub const TAB_NOT_ACTIVE: &str = "tab_not_active";
+    pub const CDP_EXTENSION_ACCESS_DENIED: &str = "cdp_extension_access_denied";
     pub const BORROW_CONFLICT: &str = "borrow_conflict";
     pub const SCREENSHOT_CAPTURE_FAILED: &str = "screenshot_capture_failed";
     pub const FILE_INPUT_PROBE_FAILED: &str = "file_input_probe_failed";
@@ -206,6 +212,13 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         return base;
     };
     match (code, reason) {
+        (ErrorCode::CdpFailed, reason::CDP_EXTENSION_ACCESS_DENIED) => RenderInfo {
+            summary: "Chrome blocked CDP access to another extension's content in this tab",
+            hint: Some(
+                "a web page can contain a restricted extension frame; disable the conflicting extension and reload, or use `bsk navigate <url>` to leave this page; reconnecting BrowserSkill alone does not remove the restriction",
+            ),
+            exit_code: base.exit_code,
+        },
         (_, reason::TRANSFER_OUTCOME_UNKNOWN) => RenderInfo {
             summary: "the file transfer outcome could not be confirmed",
             hint: Some(
@@ -247,7 +260,42 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         (ErrorCode::InvalidParams, reason::TARGET_NOT_FILLABLE) => RenderInfo {
             summary: "target element is not fillable",
             hint: Some(
-                "choose an input, textarea, or contenteditable element from the latest snapshot",
+                "observe the page and choose an enabled, editable text input, textarea, or contenteditable; use the appropriate interaction for other control types",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::InvalidParams, reason::FILL_VALUE_INVALID) => RenderInfo {
+            summary: "the requested text does not fit the field constraints",
+            hint: Some(
+                "check the field's input type and maxlength; use a compatible value without silently truncating or changing the user's intended data",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_TARGET_CHANGED) => RenderInfo {
+            summary: "the fill target changed during the action",
+            hint: Some(
+                "observe the current page and field value; if the intended result is missing, use a fresh editable target before retrying",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_FOCUS_LOST) => RenderInfo {
+            summary: "the page moved focus away from the fill target",
+            hint: Some(
+                "observe the page for a dialog or rerender and resolve it before retrying; fill manages field focus and does not require bringing the browser to the foreground",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_VALUE_MISMATCH) => RenderInfo {
+            summary: "the fill result could not be confirmed",
+            hint: Some(
+                "observe the field before retrying; the page may have formatted the value. Continue if the visible result satisfies the user's intent; otherwise correct the remaining difference. Do not blindly repeat fill or immediately request human help",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::CdpFailed, reason::FILL_FAILED) => RenderInfo {
+            summary: "fill encountered a browser or page-script error",
+            hint: Some(
+                "observe the page before retrying because the field may already have changed; retry only if the intended result is missing and the target is still available",
             ),
             exit_code: base.exit_code,
         },
@@ -442,6 +490,56 @@ mod tests {
         ErrorCode::NoBrowserConnected,
     ];
 
+    #[test]
+    fn fill_reasons_provide_recovery_without_changing_exit_codes() {
+        for (code, reason, hint_fragment) in [
+            (
+                ErrorCode::InvalidParams,
+                reason::TARGET_NOT_FILLABLE,
+                "enabled, editable",
+            ),
+            (
+                ErrorCode::InvalidParams,
+                reason::FILL_VALUE_INVALID,
+                "maxlength",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_TARGET_CHANGED,
+                "fresh editable target",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_FOCUS_LOST,
+                "does not require bringing the browser",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_VALUE_MISMATCH,
+                "Continue if the visible result satisfies",
+            ),
+            (
+                ErrorCode::CdpFailed,
+                reason::FILL_FAILED,
+                "may already have changed",
+            ),
+        ] {
+            let data = serde_json::json!({ "reason": reason });
+            let info = info_for_error(code, Some(&data));
+            assert!(info.hint.unwrap().contains(hint_fragment), "{reason}");
+            assert_eq!(info.exit_code, info_for(code).exit_code);
+        }
+        let mismatch = serde_json::json!({ "reason": reason::FILL_VALUE_MISMATCH });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&mismatch));
+        assert_eq!(info.summary, "the fill result could not be confirmed");
+        assert!(info.hint.unwrap().contains("Do not blindly repeat fill"));
+        let unknown = serde_json::json!({ "reason": "future_fill_reason" });
+        assert_eq!(
+            info_for_error(ErrorCode::CdpFailed, Some(&unknown)),
+            info_for(ErrorCode::CdpFailed)
+        );
+    }
+
     #[test]
     fn element_not_visible_overrides_permission_denied_copy() {
         let data = serde_json::json!({ "reason": reason::ELEMENT_NOT_VISIBLE });
@@ -454,6 +552,18 @@ mod tests {
         assert!(!info.summary.contains("sandbox"));
     }
 
+    #[test]
+    fn extension_access_denied_explains_the_frame_restriction_and_navigation_recovery() {
+        let data = serde_json::json!({ "reason": reason::CDP_EXTENSION_ACCESS_DENIED });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
+        assert!(info.summary.contains("another extension"));
+        let hint = info.hint.unwrap();
+        assert!(hint.contains("restricted extension frame"));
+        assert!(hint.contains("bsk navigate <url>"));
+        assert!(hint.contains("disable the conflicting extension"));
+        assert_eq!(info.exit_code, 3);
+    }
+
     #[test]
     fn session_busy_overrides_timeout_copy() {
         let data = serde_json::json!({ "reason": reason::SESSION_BUSY });

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

@@ -0,0 +1,100 @@
+//! `bsk scroll-to` — bring a target element into the visible viewport.
+
+use std::time::Duration;
+
+use anyhow::Context;
+use bsk_protocol::Method;
+use bsk_protocol::tools::{ScrollToParams, ScrollToResult};
+use clap::Args;
+
+use crate::cli::dialogs::print_dialog_summaries;
+use crate::cli::ensure_daemon::ensure_daemon;
+use crate::cli::error::{CliError, Format};
+use crate::cli::interaction::split_target;
+use crate::cli::navigate::parse_timeout_ms;
+
+#[derive(Debug, Clone, Args)]
+pub struct ScrollToArgs {
+    /// Snapshot ref (`@e3`, `e3`) or CSS selector. Optional when `--ref`/`--selector` is used.
+    pub target: Option<String>,
+
+    #[arg(long = "ref")]
+    pub ref_: Option<String>,
+
+    #[arg(long = "selector")]
+    pub selector: Option<String>,
+
+    #[arg(long)]
+    pub session: String,
+
+    #[arg(long = "tab-id")]
+    pub tab_id: Option<i64>,
+
+    #[arg(long, default_value = "30s", value_parser = parse_timeout_ms)]
+    pub timeout: u32,
+}
+
+pub fn dispatch(args: ScrollToArgs, format: Format) -> Result<(), CliError> {
+    let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
+    let info = ensure_daemon().context("ensure daemon is running")?;
+    let params = ScrollToParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        timeout_ms: Some(args.timeout),
+    };
+    let reply: ScrollToResult = crate::cli::business_rpc::call(
+        info.sock_path,
+        "scroll-to-1",
+        Method::ToolScrollTo,
+        Some(params),
+        ipc_timeout(args.timeout),
+    )?;
+    match format {
+        Format::Json => println!(
+            "{}",
+            serde_json::to_string_pretty(&reply)
+                .map_err(|e| CliError::Local(anyhow::anyhow!(e)))?
+        ),
+        Format::Human => {
+            let target =
+                format_used_target(reply.used_ref.as_deref(), reply.used_selector.as_deref());
+            println!(
+                "scroll-to ok tab={} target={target} bounds=({}, {}, {}, {})",
+                reply.tab_id, reply.x, reply.y, reply.width, reply.height
+            );
+            print_dialog_summaries(&reply.dialogs);
+        }
+    }
+    Ok(())
+}
+
+fn format_used_target(used_ref: Option<&str>, used_selector: Option<&str>) -> String {
+    used_ref
+        .map(|r| format!("@{r}"))
+        .or_else(|| used_selector.map(str::to_string))
+        .unwrap_or_else(|| "?".into())
+}
+
+fn ipc_timeout(timeout_ms: u32) -> Duration {
+    Duration::from_millis(u64::from(timeout_ms))
+        .checked_add(Duration::from_secs(15))
+        .unwrap_or(Duration::from_secs(u64::from(timeout_ms / 1_000) + 15))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn split_target_detects_refs_and_selectors() {
+        let (ref_, selector) = split_target(Some("@e3".into()), None, None).unwrap();
+        assert_eq!(ref_.as_deref(), Some("@e3"));
+        assert!(selector.is_none());
+
+        let (ref_, selector) = split_target(Some("#target".into()), None, None).unwrap();
+        assert!(ref_.is_none());
+        assert_eq!(selector.as_deref(), Some("#target"));
+    }
+}

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

@@ -6,9 +6,7 @@ use std::path::{Path, PathBuf};
 use std::time::{Duration, SystemTime};
 
 #[cfg(windows)]
-use std::os::windows::process::CommandExt;
-#[cfg(windows)]
-use std::process::{Command, Stdio};
+mod windows;
 
 use anyhow::{Context, Result, bail};
 use clap::Args;
@@ -363,7 +361,8 @@ fn install_candidate_with_client(
         crate::daemon::start::run_stop().context("stop bsk daemon before update")?;
     }
 
-    let action = replace_binary_for_update(&target, &binary, daemon_was_running)?;
+    let restart_args = daemon_was_running.then(StartArgs::default);
+    let action = replace_binary_for_update(&target, &binary, restart_args.as_ref())?;
 
     if daemon_was_running && matches!(action, InstallAction::Replaced) {
         crate::daemon::start::run_start(StartArgs::default())
@@ -394,8 +393,8 @@ pub(crate) fn download_candidate_binary(
 
 /// Daemon-side install: download, verify, and replace the executable at
 /// `target` (on Windows: stage the replacement next to it). Unlike the
-/// CLI path this never stops or starts the daemon — the daemon drives
-/// its own restart once the binary is replaced.
+/// CLI path this never stops the daemon. On Windows the helper starts
+/// its replacement after exit; elsewhere the daemon drives its own restart.
 ///
 /// `target` must be captured *before* any replacement happens: on Linux
 /// `std::env::current_exe` starts returning a ` (deleted)`-suffixed
@@ -403,10 +402,11 @@ pub(crate) fn download_candidate_binary(
 pub(crate) fn self_install_candidate(
     candidate: &UpdateCandidate,
     target: &Path,
+    restart_args: &StartArgs,
 ) -> Result<InstallAction> {
     let client = update_http_client(ARCHIVE_FETCH_TIMEOUT)?;
     let binary = download_candidate_binary(candidate, &client)?;
-    replace_binary_at_path(target, &binary)
+    replace_binary_for_update(target, &binary, Some(restart_args))
 }
 
 /// Outcome of one daemon auto-update step (see [`auto_update_step`]).
@@ -423,8 +423,8 @@ pub(crate) enum AutoUpdateOutcome {
     /// The new binary replaced the old one; the daemon should now
     /// restart into it.
     Replaced { latest: String },
-    /// Windows staged the replacement next to the running binary; a
-    /// daemon/terminal restart finishes it.
+    /// Windows started a helper that will replace the executable and
+    /// restart the daemon once the current process exits.
     Staged { latest: String },
 }
 
@@ -668,6 +668,7 @@ fn render_report(format: Format, report: &UpdateReport) -> Result<()> {
             }
             if matches!(report.install_action, Some("staged")) {
                 println!("the detached update helper will apply the replacement after exit");
+                println!("if it fails, see the *.update-*.log file next to the executable");
             }
         }
         Format::Json => {
@@ -688,22 +689,22 @@ pub fn extract_bsk_binary(archive_bytes: &[u8], kind: ArchiveKind) -> Result<Vec
 }
 
 pub fn replace_binary_at_path(target: &Path, binary: &[u8]) -> Result<InstallAction> {
-    replace_binary_for_update(target, binary, false)
+    replace_binary_for_update(target, binary, None)
 }
 
 fn replace_binary_for_update(
     target: &Path,
     binary: &[u8],
-    restart_daemon: bool,
+    restart_args: Option<&StartArgs>,
 ) -> Result<InstallAction> {
     #[cfg(windows)]
     {
-        stage_windows_replacement(target, binary, restart_daemon)
+        stage_windows_replacement(target, binary, restart_args)
     }
 
     #[cfg(not(windows))]
     {
-        let _ = restart_daemon;
+        let _ = restart_args;
         replace_binary_atomically(target, binary)
     }
 }
@@ -749,34 +750,69 @@ fn replace_binary_atomically(target: &Path, binary: &[u8]) -> Result<InstallActi
 fn stage_windows_replacement(
     target: &Path,
     binary: &[u8],
-    restart_daemon: bool,
+    restart_args: Option<&StartArgs>,
 ) -> Result<InstallAction> {
-    let paths = staged_replacement_paths(target, std::process::id())?;
-    std::fs::write(&paths.binary_path, binary)
-        .with_context(|| format!("write {}", paths.binary_path.display()))?;
-    std::fs::write(
-        &paths.script_path,
-        windows_replacement_script(target, &paths.binary_path, restart_daemon),
-    )
-    .with_context(|| format!("write {}", paths.script_path.display()))?;
+    // The helper owns replacement/restart after this process exits. Do not
+    // report Staged until it has actually begun executing the script.
+    let _child = spawn_windows_replacement(target, binary, restart_args, 120)?;
+    Ok(InstallAction::Staged)
+}
 
-    const CREATE_NO_WINDOW: u32 = 0x0800_0000;
-    const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
-    let command = format!("\"{}\"", paths.script_path.display());
-    if let Err(err) = Command::new("cmd.exe")
-        .args(["/D", "/S", "/C"])
-        .arg(command)
-        .stdin(Stdio::null())
-        .stdout(Stdio::null())
-        .stderr(Stdio::null())
-        .creation_flags(CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP)
-        .spawn()
-    {
+#[cfg(windows)]
+fn spawn_windows_replacement(
+    target: &Path,
+    binary: &[u8],
+    restart_args: Option<&StartArgs>,
+    attempts: u32,
+) -> Result<windows::Helper> {
+    let paths = staged_replacement_paths(target, std::process::id())?;
+    let ready_path = paths.script_path.with_extension("ready");
+    let log_path = paths.script_path.with_extension("log");
+    let result = (|| {
+        // A previous failed attempt by this process must not acknowledge a
+        // new helper. All paths are private to this target and process id.
+        match std::fs::remove_file(&ready_path) {
+            Ok(()) => {}
+            Err(err) if err.kind() == std::io::ErrorKind::NotFound => {}
+            Err(err) => return Err(err.into()),
+        }
+        std::fs::write(&paths.binary_path, binary)
+            .with_context(|| format!("write {}", paths.binary_path.display()))?;
+        std::fs::write(
+            &paths.script_path,
+            windows_replacement_script(restart_args, attempts),
+        )
+        .with_context(|| format!("write {}", paths.script_path.display()))?;
+        let mut child = windows::spawn(
+            &paths.script_path,
+            &paths.binary_path,
+            target,
+            &ready_path,
+            &log_path,
+        )
+        .context("launch detached Windows update helper")?;
+        let deadline = std::time::Instant::now() + Duration::from_secs(5);
+        loop {
+            if std::fs::remove_file(&ready_path).is_ok() {
+                return Ok(child);
+            }
+            if let Some(status) = child.try_wait()? {
+                bail!("Windows update helper exited before becoming ready: {status}");
+            }
+            if std::time::Instant::now() >= deadline {
+                let _ = child.kill();
+                let _ = child.wait();
+                bail!("Windows update helper did not become ready within 5 seconds");
+            }
+            std::thread::sleep(Duration::from_millis(20));
+        }
+    })();
+    if result.is_err() {
         let _ = std::fs::remove_file(&paths.binary_path);
         let _ = std::fs::remove_file(&paths.script_path);
-        return Err(err).context("launch detached Windows update helper");
+        let _ = std::fs::remove_file(&ready_path);
     }
-    Ok(InstallAction::Staged)
+    result.with_context(|| format!("Windows update helper failed; see {}", log_path.display()))
 }
 
 pub fn staged_replacement_paths(target: &Path, pid: u32) -> Result<StagedReplacementPaths> {
@@ -793,25 +829,43 @@ pub fn staged_replacement_paths(target: &Path, pid: u32) -> Result<StagedReplace
 }
 
 #[cfg(any(windows, test))]
-fn windows_replacement_script(target: &Path, staged_binary: &Path, restart_daemon: bool) -> String {
-    let target = target.display().to_string().replace('%', "%%");
-    let staged_binary = staged_binary.display().to_string().replace('%', "%%");
-    let restart = if restart_daemon {
-        format!("start \"\" /B \"{target}\" daemon start >nul 2>nul\r\n")
-    } else {
-        String::new()
-    };
+fn windows_replacement_script(restart_args: Option<&StartArgs>, attempts: u32) -> String {
+    // Only fixed switches and numeric values go into the ASCII script. Paths
+    // stay in Unicode environment variables, including %, ! and shell symbols.
+    let restart = restart_args.map_or_else(String::new, |args| {
+        format!(
+            "\"%BSK_UPDATE_TARGET%\" daemon start --port {} --session-idle {}ms --daemon-idle {}ms\r\nif errorlevel 1 goto failed_restart\r\n",
+            args.resolved_port(),
+            args.resolved_session_idle().as_millis(),
+            args.resolved_daemon_idle().as_millis(),
+        )
+    });
     format!(
         "@echo off\r\n\
-         setlocal\r\n\
+         setlocal DisableDelayedExpansion\r\n\
+         > \"%BSK_UPDATE_READY%\" echo ready\r\n\
+         if errorlevel 1 exit /b 1\r\n\
+         set /a attempts=0\r\n\
          :retry\r\n\
-         move /Y \"{staged_binary}\" \"{target}\" >nul 2>nul\r\n\
-         if errorlevel 1 (\r\n\
-           ping -n 2 127.0.0.1 >nul\r\n\
-           goto retry\r\n\
-         )\r\n\
+         move /Y \"%BSK_UPDATE_SOURCE%\" \"%BSK_UPDATE_TARGET%\" >nul\r\n\
+         if not errorlevel 1 goto replaced\r\n\
+         set /a attempts+=1\r\n\
+         if %attempts% geq {attempts} goto failed_replace\r\n\
+         if not exist \"%BSK_UPDATE_SOURCE%\" goto failed_replace\r\n\
+         ping -n 2 127.0.0.1 >nul\r\n\
+         goto retry\r\n\
+         :failed_replace\r\n\
+         echo Failed to replace the executable after %attempts% attempts.\r\n\
+         goto failed\r\n\
+         :replaced\r\n\
          {restart}\
-         del /F /Q \"%~f0\" >nul 2>nul\r\n"
+         del /F /Q \"%BSK_UPDATE_LOG%\" >nul 2>nul\r\n\
+         (del /F /Q \"%BSK_UPDATE_SCRIPT%\" >nul 2>nul & exit 0)\r\n\
+         :failed_restart\r\n\
+         echo Replaced the executable but failed to restart the daemon.\r\n\
+         :failed\r\n\
+         del /F /Q \"%BSK_UPDATE_SOURCE%\" >nul 2>nul\r\n\
+         (del /F /Q \"%BSK_UPDATE_SCRIPT%\" >nul 2>nul & exit 1)\r\n"
     )
 }
 
@@ -965,6 +1019,7 @@ mod tests {
         assert_eq!(extracted, b"windows binary");
     }
 
+    #[cfg(not(windows))]
     #[test]
     fn replaces_binary_at_path() {
         let tmp = tempfile::TempDir::new().unwrap();
@@ -999,31 +1054,139 @@ mod tests {
     }
 
     #[test]
-    fn windows_replacement_script_retries_restarts_and_cleans_itself() {
-        let script = windows_replacement_script(
-            Path::new(r"C:\Program Files\bsk.exe"),
-            Path::new(r"C:\Program Files\bsk.exe.update-42"),
-            true,
+    fn windows_replacement_script_preserves_restart_config() {
+        let args = StartArgs {
+            port: Some(54321),
+            session_idle: Some(Duration::from_millis(1234)),
+            daemon_idle: Some(Duration::from_secs(75)),
+            ..Default::default()
+        };
+        let script = windows_replacement_script(Some(&args), 120);
+        assert!(script.is_ascii());
+        assert!(
+            script
+                .contains("daemon start --port 54321 --session-idle 1234ms --daemon-idle 75000ms")
         );
-
-        assert!(script.contains(":retry"));
-        assert!(script.contains("move /Y"));
-        assert!(script.contains("ping -n 2 127.0.0.1"));
-        assert!(!script.contains("timeout"));
-        assert!(script.contains(r#"start "" /B "C:\Program Files\bsk.exe" daemon start"#));
-        assert!(script.contains(r#"del /F /Q "%~f0""#));
+        assert!(!windows_replacement_script(None, 120).contains("daemon start"));
     }
 
-    #[test]
-    fn windows_replacement_script_omits_restart_when_daemon_was_not_running() {
-        let script = windows_replacement_script(
-            Path::new(r"C:\bsk.exe"),
-            Path::new(r"C:\bsk.exe.update-42"),
-            false,
-        );
+    #[cfg(windows)]
+    fn wait_for_helper(mut child: windows::Helper) -> std::process::ExitStatus {
+        let deadline = std::time::Instant::now() + Duration::from_secs(10);
+        loop {
+            if let Some(status) = child.try_wait().unwrap() {
+                return status;
+            }
+            if std::time::Instant::now() >= deadline {
+                let _ = child.kill();
+                let _ = child.wait();
+                panic!("Windows update helper did not exit");
+            }
+            std::thread::sleep(Duration::from_millis(20));
+        }
+    }
 
-        assert!(!script.contains("daemon start"));
-        assert!(script.contains(r#"del /F /Q "%~f0""#));
+    #[cfg(windows)]
+    #[test]
+    fn windows_helper_replaces_in_unicode_spaces_and_shell_symbol_paths() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        for name in [
+            "ascii",
+            "with space",
+            "中文目录",
+            "literal %PATH% ! & (folder)",
+        ] {
+            let dir = tmp.path().join(name);
+            std::fs::create_dir(&dir).unwrap();
+            let target = dir.join("bsk.exe");
+            std::fs::write(&target, b"old binary").unwrap();
+            let child = spawn_windows_replacement(&target, b"new binary", None, 5).unwrap();
+            let paths = staged_replacement_paths(&target, std::process::id()).unwrap();
+            let status = wait_for_helper(child);
+            assert!(
+                status.success(),
+                "{name}: {:?}",
+                std::fs::read_to_string(paths.script_path.with_extension("log"))
+            );
+            assert_eq!(std::fs::read(&target).unwrap(), b"new binary", "{name}");
+            // Successful updates leave no helper, staged binary, ready file or log.
+            assert_eq!(std::fs::read_dir(&dir).unwrap().count(), 1, "{name}");
+        }
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_helper_waits_for_unlock_then_replaces() {
+        use std::os::windows::fs::OpenOptionsExt;
+        let tmp = tempfile::TempDir::new().unwrap();
+        let target = tmp.path().join("bsk.exe");
+        std::fs::write(&target, b"old binary").unwrap();
+        // Deny delete sharing, like a running Windows executable.
+        let lock = std::fs::OpenOptions::new()
+            .read(true)
+            .share_mode(1)
+            .open(&target)
+            .unwrap();
+        let mut child = spawn_windows_replacement(&target, b"new binary", None, 5).unwrap();
+        std::thread::sleep(Duration::from_millis(150));
+        assert!(child.try_wait().unwrap().is_none());
+        assert_eq!(std::fs::read(&target).unwrap(), b"old binary");
+        drop(lock);
+        assert!(wait_for_helper(child).success());
+        assert_eq!(std::fs::read(&target).unwrap(), b"new binary");
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_helper_bounds_retries_and_preserves_old_binary_on_failure() {
+        use std::os::windows::fs::OpenOptionsExt;
+        let tmp = tempfile::TempDir::new().unwrap();
+        let target = tmp.path().join("bsk.exe");
+        std::fs::write(&target, b"old binary").unwrap();
+        let _lock = std::fs::OpenOptions::new()
+            .read(true)
+            .share_mode(1)
+            .open(&target)
+            .unwrap();
+        let child = spawn_windows_replacement(&target, b"new binary", None, 2).unwrap();
+        assert!(!wait_for_helper(child).success());
+        let paths = staged_replacement_paths(&target, std::process::id()).unwrap();
+        assert_eq!(std::fs::read(&target).unwrap(), b"old binary");
+        assert!(!paths.binary_path.exists());
+        assert!(!paths.script_path.exists());
+        let log_bytes = std::fs::read(paths.script_path.with_extension("log")).unwrap();
+        let log = String::from_utf8_lossy(&log_bytes);
+        assert!(
+            log.contains("Failed to replace the executable after 2 attempts."),
+            "{log}"
+        );
+    }
+
+    #[cfg(windows)]
+    #[test]
+    fn windows_helper_reports_restart_failure_without_losing_replacement() {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let target = tmp.path().join("bsk.exe");
+        std::fs::write(&target, b"old binary").unwrap();
+        // Not a valid PE executable: replacement succeeds but restart fails.
+        let child = spawn_windows_replacement(
+            &target,
+            b"invalid executable",
+            Some(&StartArgs::default()),
+            2,
+        )
+        .unwrap();
+        assert!(!wait_for_helper(child).success());
+        let paths = staged_replacement_paths(&target, std::process::id()).unwrap();
+        let bytes = std::fs::read(paths.script_path.with_extension("log")).unwrap();
+        let log = String::from_utf8_lossy(&bytes);
+        assert!(
+            log.contains("Replaced the executable but failed to restart the daemon."),
+            "{log}"
+        );
+        assert_eq!(std::fs::read(&target).unwrap(), b"invalid executable");
+        assert!(!paths.script_path.exists());
+        assert!(!paths.binary_path.exists());
     }
 
     #[test]
@@ -1282,10 +1445,9 @@ mod tests {
     }
 
     #[test]
-    fn auto_update_step_staged_outcome_requests_no_restart() {
-        // The Windows shape: the replacement is staged next to the
-        // running binary, so the outcome must not ask for the immediate
-        // self-restart that `Replaced` triggers.
+    fn auto_update_step_reports_staged_handoff() {
+        // The helper, rather than this process, starts the new executable.
+        // The daemon must exit to let that staged handoff finish.
         let candidate = test_candidate();
         let outcome =
             auto_update_step(Some(&candidate), true, 0, |_| Ok(InstallAction::Staged)).unwrap();

crates/bsk-cli/src/cli/update/windows.rs

@@ -0,0 +1,203 @@
+//! Launch the update helper with only its stdio handles inherited.
+//!
+//! std::process::Command on Windows also inherits other inheritable handles.
+//! A daemon's listening socket must not survive in the helper: it would keep
+//! the port occupied after the daemon exits and prevent its replacement starting.
+
+use std::ffi::OsStr;
+use std::fs::File;
+use std::io;
+use std::os::windows::ffi::OsStrExt;
+use std::os::windows::io::{AsRawHandle, FromRawHandle, OwnedHandle};
+use std::os::windows::process::ExitStatusExt;
+use std::path::Path;
+use std::process::ExitStatus;
+
+use windows_sys::Win32::Foundation::{
+    HANDLE, HANDLE_FLAG_INHERIT, SetHandleInformation, WAIT_OBJECT_0, WAIT_TIMEOUT,
+};
+use windows_sys::Win32::System::Threading::{
+    CREATE_NEW_PROCESS_GROUP, CREATE_NO_WINDOW, CREATE_UNICODE_ENVIRONMENT, CreateProcessW,
+    DeleteProcThreadAttributeList, EXTENDED_STARTUPINFO_PRESENT, GetExitCodeProcess,
+    InitializeProcThreadAttributeList, PROC_THREAD_ATTRIBUTE_HANDLE_LIST, PROCESS_INFORMATION,
+    STARTF_USESTDHANDLES, STARTUPINFOEXW, TerminateProcess, UpdateProcThreadAttribute,
+    WaitForSingleObject,
+};
+
+pub(super) struct Helper(OwnedHandle);
+
+impl Helper {
+    pub(super) fn try_wait(&mut self) -> io::Result<Option<ExitStatus>> {
+        // SAFETY: the owned process handle remains valid for both calls.
+        match unsafe { WaitForSingleObject(self.0.as_raw_handle(), 0) } {
+            WAIT_OBJECT_0 => {
+                let mut code = 0;
+                if unsafe { GetExitCodeProcess(self.0.as_raw_handle(), &mut code) } == 0 {
+                    return Err(io::Error::last_os_error());
+                }
+                Ok(Some(ExitStatus::from_raw(code)))
+            }
+            WAIT_TIMEOUT => Ok(None),
+            _ => Err(io::Error::last_os_error()),
+        }
+    }
+
+    pub(super) fn kill(&mut self) -> io::Result<()> {
+        // SAFETY: this handle belongs to the helper we created.
+        if unsafe { TerminateProcess(self.0.as_raw_handle(), 1) } == 0 {
+            return Err(io::Error::last_os_error());
+        }
+        Ok(())
+    }
+
+    pub(super) fn wait(&mut self) -> io::Result<()> {
+        // Only used after kill(); do not leave a live helper on startup failure.
+        if unsafe { WaitForSingleObject(self.0.as_raw_handle(), 5000) } != WAIT_OBJECT_0 {
+            return Err(io::Error::new(
+                io::ErrorKind::TimedOut,
+                "update helper did not exit",
+            ));
+        }
+        Ok(())
+    }
+}
+
+// The opaque attribute list needs pointer-aligned storage and explicit teardown.
+struct AttributeList(Vec<usize>);
+
+impl Drop for AttributeList {
+    fn drop(&mut self) {
+        // SAFETY: this wrapper is constructed only after successful initialization.
+        unsafe { DeleteProcThreadAttributeList(self.0.as_mut_ptr().cast()) };
+    }
+}
+
+pub(super) fn spawn(
+    script: &Path,
+    source: &Path,
+    target: &Path,
+    ready: &Path,
+    log_path: &Path,
+) -> io::Result<Helper> {
+    let root = std::env::var_os("SystemRoot")
+        .ok_or_else(|| io::Error::new(io::ErrorKind::NotFound, "SystemRoot is not set"))?;
+    let application = wide(Path::new(&root).join("System32/cmd.exe").as_os_str());
+    // /S /C strips one outer pair of quotes. Environment expansion keeps paths
+    // Unicode and avoids CRT escaping, batch-file encoding, and CALL expansion.
+    let mut command = wide(OsStr::new(
+        "cmd.exe /D /V:OFF /S /C \"\"%BSK_UPDATE_SCRIPT%\"\"",
+    ));
+    let overrides = [
+        ("BSK_UPDATE_SCRIPT", script.as_os_str()),
+        ("BSK_UPDATE_SOURCE", source.as_os_str()),
+        ("BSK_UPDATE_TARGET", target.as_os_str()),
+        ("BSK_UPDATE_READY", ready.as_os_str()),
+        ("BSK_UPDATE_LOG", log_path.as_os_str()),
+    ];
+    let mut env: Vec<_> = std::env::vars_os()
+        .filter(|(key, _)| {
+            let key = key.to_string_lossy();
+            !overrides
+                .iter()
+                .any(|(name, _)| key.eq_ignore_ascii_case(name))
+                && !key.eq_ignore_ascii_case(crate::daemon::start::DAEMONIZED_ENV)
+                && !key.eq_ignore_ascii_case(crate::daemon::start::DAEMON_REPLACEMENT_WAIT_ENV)
+        })
+        .collect();
+    env.extend(
+        overrides
+            .into_iter()
+            .map(|(key, value)| (key.into(), value.to_owned())),
+    );
+    env.sort_by_key(|(key, _)| key.to_string_lossy().to_uppercase());
+    let mut environment = Vec::new();
+    for (key, value) in env {
+        environment.extend(key.encode_wide());
+        environment.push(b'=' as u16);
+        environment.extend(value.encode_wide());
+        environment.push(0);
+    }
+    environment.push(0);
+
+    let input = File::open("NUL")?;
+    let log = File::create(log_path)?;
+    let handles: [HANDLE; 2] = [input.as_raw_handle(), log.as_raw_handle()];
+    for &handle in &handles {
+        // SAFETY: these are dedicated helper stdio handles, held until spawn
+        // finishes. The explicit handle list excludes every other parent handle.
+        if unsafe { SetHandleInformation(handle, HANDLE_FLAG_INHERIT, HANDLE_FLAG_INHERIT) } == 0 {
+            return Err(io::Error::last_os_error());
+        }
+    }
+
+    let mut size = 0;
+    // SAFETY: the first call queries the allocation size, as required by Win32.
+    unsafe { InitializeProcThreadAttributeList(std::ptr::null_mut(), 1, 0, &mut size) };
+    if size == 0 {
+        return Err(io::Error::last_os_error());
+    }
+    let mut storage = vec![0usize; size.div_ceil(std::mem::size_of::<usize>())];
+    // SAFETY: storage has the requested size and pointer alignment.
+    if unsafe { InitializeProcThreadAttributeList(storage.as_mut_ptr().cast(), 1, 0, &mut size) }
+        == 0
+    {
+        return Err(io::Error::last_os_error());
+    }
+    let mut attributes = AttributeList(storage);
+    // SAFETY: the handle array and attribute storage outlive CreateProcessW.
+    if unsafe {
+        UpdateProcThreadAttribute(
+            attributes.0.as_mut_ptr().cast(),
+            0,
+            PROC_THREAD_ATTRIBUTE_HANDLE_LIST as usize,
+            handles.as_ptr().cast(),
+            std::mem::size_of_val(&handles),
+            std::ptr::null_mut(),
+            std::ptr::null(),
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error());
+    }
+    // SAFETY: these Win32 structs permit zero initialization; required fields
+    // are populated below before the process is created.
+    let mut startup: STARTUPINFOEXW = unsafe { std::mem::zeroed() };
+    startup.StartupInfo.cb = std::mem::size_of::<STARTUPINFOEXW>() as u32;
+    startup.StartupInfo.dwFlags = STARTF_USESTDHANDLES;
+    startup.StartupInfo.hStdInput = handles[0];
+    startup.StartupInfo.hStdOutput = handles[1];
+    startup.StartupInfo.hStdError = handles[1];
+    startup.lpAttributeList = attributes.0.as_mut_ptr().cast();
+    let mut process: PROCESS_INFORMATION = unsafe { std::mem::zeroed() };
+    // SAFETY: strings are NUL-terminated UTF-16, the environment is double-NUL
+    // terminated, and all buffers/handles remain alive for the duration of spawn.
+    if unsafe {
+        CreateProcessW(
+            application.as_ptr(),
+            command.as_mut_ptr(),
+            std::ptr::null(),
+            std::ptr::null(),
+            1,
+            CREATE_NO_WINDOW
+                | CREATE_NEW_PROCESS_GROUP
+                | CREATE_UNICODE_ENVIRONMENT
+                | EXTENDED_STARTUPINFO_PRESENT,
+            environment.as_ptr().cast(),
+            std::ptr::null(),
+            &startup.StartupInfo,
+            &mut process,
+        )
+    } == 0
+    {
+        return Err(io::Error::last_os_error());
+    }
+    // SAFETY: successful CreateProcessW transfers these two handles to us.
+    let _thread = unsafe { OwnedHandle::from_raw_handle(process.hThread) };
+    Ok(Helper(unsafe {
+        OwnedHandle::from_raw_handle(process.hProcess)
+    }))
+}
+
+fn wide(value: &OsStr) -> Vec<u16> {
+    value.encode_wide().chain(Some(0)).collect()
+}

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

@@ -10,8 +10,7 @@ use base64::Engine;
 use bsk_protocol::Method;
 use bsk_protocol::tools::{
     TransferBeginParams, TransferBeginResult, TransferChunkParams, TransferChunkResult,
-    TransferIdParams, TransferReadyResult, TransferReleaseResult, UploadFile, UploadMode,
-    UploadParams, UploadResult,
+    TransferIdParams, TransferReadyResult, UploadFile, UploadMode, UploadParams, UploadResult,
 };
 use clap::{Args, ValueEnum};
 
@@ -69,14 +68,12 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
     let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
     let mut staged = Vec::new();
     for path in &args.files {
-        match stage_file(&info.sock_path, &args.session, path) {
-            Ok(file) => staged.push(file),
-            Err(err) => {
-                for (id, _) in &staged {
-                    let _ = release(&info.sock_path, id);
-                }
-                return Err(err);
-            }
+        if let Err(err) = stage_file(&info.sock_path, &args.session, path, &mut staged) {
+            let _ = crate::cli::business_rpc::release_transfers(
+                &info.sock_path,
+                staged.iter().map(|(id, _)| id.as_str()),
+            );
+            return Err(err);
         }
     }
     let params = UploadParams {
@@ -102,6 +99,17 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
         Some(params),
         ipc_timeout(args.timeout),
     );
+    // The helper can reject cancellation before handing any request to the
+    // daemon. In that case staging still belongs to this CLI.
+    if result.as_ref().is_err_and(|err| {
+        err.data()
+            .is_some_and(|data| data["reason"] == "cancelled_before_dispatch")
+    }) {
+        let _ = crate::cli::business_rpc::release_transfers(
+            &info.sock_path,
+            staged.iter().map(|(id, _)| id.as_str()),
+        );
+    }
     // Once tool.upload is dispatched, staging ownership belongs to the
     // session. A transport timeout cannot prove that Chrome did not attach
     // the file, so releasing here could invalidate a late successful attach.
@@ -118,7 +126,12 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
     Ok(())
 }
 
-fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, String), CliError> {
+fn stage_file(
+    sock: &Path,
+    session: &str,
+    path: &PathBuf,
+    staged: &mut Vec<(String, String)>,
+) -> Result<(), CliError> {
     let mut file = File::open(path)
         .with_context(|| format!("open upload file {}", path.display()))
         .map_err(CliError::Local)?;
@@ -149,55 +162,39 @@ fn stage_file(sock: &Path, session: &str, path: &PathBuf) -> Result<(String, Str
         }),
         Duration::from_secs(10),
     )?;
-    let staged = (|| {
-        let mut offset = 0u64;
-        let mut buf = vec![0u8; begin.chunk_size as usize];
-        loop {
-            let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
-            if n == 0 {
-                break;
-            }
-            let reply: TransferChunkResult = crate::cli::business_rpc::call(
-                sock.to_path_buf(),
-                "transfer-chunk",
-                Method::TransferChunk,
-                Some(TransferChunkParams {
-                    transfer_id: begin.transfer_id.clone(),
-                    offset,
-                    data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
-                }),
-                Duration::from_secs(30),
-            )?;
-            offset = reply.next_offset;
+    // Record ownership immediately so one error path releases both completed
+    // files and the current partially staged file.
+    staged.push((begin.transfer_id.clone(), name));
+    let mut offset = 0u64;
+    let mut buf = vec![0u8; begin.chunk_size as usize];
+    loop {
+        let n = file.read(&mut buf).map_err(|e| CliError::Local(e.into()))?;
+        if n == 0 {
+            break;
         }
-        let _: TransferReadyResult = crate::cli::business_rpc::call(
+        let reply: TransferChunkResult = crate::cli::business_rpc::call(
             sock.to_path_buf(),
-            "transfer-finish",
-            Method::TransferFinish,
-            Some(TransferIdParams {
+            "transfer-chunk",
+            Method::TransferChunk,
+            Some(TransferChunkParams {
                 transfer_id: begin.transfer_id.clone(),
+                offset,
+                data_base64: base64::engine::general_purpose::STANDARD.encode(&buf[..n]),
             }),
-            Duration::from_secs(10),
+            Duration::from_secs(30),
         )?;
-        Ok::<_, CliError>(())
-    })();
-    if let Err(err) = staged {
-        let _ = release(sock, &begin.transfer_id);
-        return Err(err);
+        offset = reply.next_offset;
     }
-    Ok((begin.transfer_id, name))
-}
-
-fn release(sock: &Path, id: &str) -> Result<TransferReleaseResult, CliError> {
-    crate::cli::business_rpc::call(
+    let _: TransferReadyResult = crate::cli::business_rpc::call(
         sock.to_path_buf(),
-        "transfer-release",
-        Method::TransferRelease,
+        "transfer-finish",
+        Method::TransferFinish,
         Some(TransferIdParams {
-            transfer_id: id.to_string(),
+            transfer_id: begin.transfer_id.clone(),
         }),
-        Duration::from_secs(5),
-    )
+        Duration::from_secs(10),
+    )?;
+    Ok(())
 }
 
 fn ipc_timeout(timeout_ms: u32) -> Duration {

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

@@ -253,6 +253,9 @@ pub fn full_handler(status: DaemonStatus, state: Arc<DaemonState>) -> RpcHandler
                 | Method::ToolReload
                 | Method::ToolClick
                 | Method::ToolHover
+                | Method::ToolScrollTo
+                | Method::ToolFocus
+                | Method::ToolBlur
                 | Method::ToolFill
                 | Method::ToolPress
                 | Method::ToolSelect
@@ -1399,6 +1402,28 @@ mod windows {
                 connected = pipe.connect() => {
                     match connected {
                         Ok(()) => {
+                            // Keep the connected instance alive until its replacement
+                            // exists. Otherwise a fast handler can close the last
+                            // instance and make new clients fail with NotFound.
+                            loop {
+                                match ServerOptions::new()
+                                    .access_inbound(true)
+                                    .access_outbound(true)
+                                    .create(&listener.pipe_name)
+                                {
+                                    Ok(next) => {
+                                        listener.first = Some(next);
+                                        break;
+                                    }
+                                    Err(err) => {
+                                        warn!(?err, "create next named-pipe instance failed");
+                                        tokio::select! {
+                                            _ = &mut shutdown => return,
+                                            _ = tokio::time::sleep(std::time::Duration::from_millis(50)) => {}
+                                        }
+                                    }
+                                }
+                            }
                             on_open();
                             let handler = handler.clone();
                             let on_act = on_activity.clone();
@@ -1467,6 +1492,118 @@ mod windows {
         }
         Ok(())
     }
+    #[cfg(test)]
+    mod tests {
+        use super::*;
+        use std::sync::Mutex;
+        use std::time::Duration;
+        use tokio::net::windows::named_pipe::ClientOptions;
+        use tokio::sync::oneshot;
+
+        fn isolated_listener() -> NamedPipeListener {
+            let pipe_name = format!(r"\\.\pipe\bsk-test-{}", uuid::Uuid::new_v4());
+            let first = ServerOptions::new()
+                .first_pipe_instance(true)
+                .create(&pipe_name)
+                .unwrap();
+            NamedPipeListener {
+                pipe_name,
+                first: Some(first),
+            }
+        }
+
+        #[tokio::test]
+        async fn next_instance_exists_before_connection_is_handed_off() {
+            let listener = isolated_listener();
+            let name = listener.pipe_name.clone();
+            let probe_name = name.clone();
+            let (probe_tx, probe_rx) = oneshot::channel();
+            let probe_tx = Mutex::new(Some(probe_tx));
+            let (stop_tx, stop_rx) = oneshot::channel();
+            let server = tokio::spawn(serve(
+                listener,
+                crate::daemon::ipc::default_ping_handler(),
+                move || {
+                    if let Some(tx) = probe_tx.lock().unwrap().take() {
+                        // This callback runs before the connection task can finish.
+                        // A second client must already have an instance to open.
+                        let result = ClientOptions::new().open(&probe_name).map(drop);
+                        let _ = tx.send(result);
+                    }
+                },
+                || {},
+                || {},
+                async {
+                    let _ = stop_rx.await;
+                },
+            ));
+            let client = ClientOptions::new().open(&name).unwrap();
+            let result = tokio::time::timeout(Duration::from_secs(5), probe_rx).await;
+            drop(client);
+            let _ = stop_tx.send(());
+            server.await.unwrap();
+            result
+                .expect("accept callback ran")
+                .unwrap()
+                .expect("next pipe instance is ready");
+        }
+
+        #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+        async fn rapid_disconnects_and_concurrent_rpc_connections() {
+            let listener = isolated_listener();
+            let name = listener.pipe_name.clone();
+            let (stop_tx, stop_rx) = oneshot::channel();
+            let server = tokio::spawn(serve(
+                listener,
+                crate::daemon::ipc::default_ping_handler(),
+                || {},
+                || {},
+                || {},
+                async {
+                    let _ = stop_rx.await;
+                },
+            ));
+            let exercise = async {
+                // Include clients that close without sending any request.
+                for _ in 0..64 {
+                    drop(
+                        crate::ipc_client::Client::connect_path(name.clone().into())
+                            .await
+                            .unwrap(),
+                    );
+                }
+                let mut clients = tokio::task::JoinSet::new();
+                for _ in 0..8 {
+                    let name = name.clone();
+                    clients.spawn(async move {
+                        for _ in 0..32 {
+                            let mut client =
+                                crate::ipc_client::Client::connect_path(name.clone().into())
+                                    .await
+                                    .unwrap();
+                            let reply: bsk_protocol::PingResult = client
+                                .call(
+                                    bsk_protocol::Method::SystemPing,
+                                    &serde_json::json!({}),
+                                    Duration::from_secs(5),
+                                )
+                                .await
+                                .unwrap()
+                                .unwrap();
+                            assert!(reply.pong);
+                        }
+                    });
+                }
+                while let Some(result) = clients.join_next().await {
+                    result.unwrap();
+                }
+            };
+            let result = tokio::time::timeout(Duration::from_secs(30), exercise).await;
+            let _ = stop_tx.send(());
+            server.await.unwrap();
+            result.expect("connection exercise completed");
+        }
+    }
 }
 
 #[cfg(windows)]

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

@@ -90,17 +90,21 @@ pub fn pid_alive(pid: u32) -> bool {
 
     #[cfg(windows)]
     {
-        use windows_sys::Win32::Foundation::CloseHandle;
+        use windows_sys::Win32::Foundation::{CloseHandle, WAIT_TIMEOUT};
         use windows_sys::Win32::System::Threading::{
-            OpenProcess, PROCESS_QUERY_LIMITED_INFORMATION,
+            OpenProcess, PROCESS_SYNCHRONIZE, WaitForSingleObject,
         };
         unsafe {
-            let handle = OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, 0, pid);
+            let handle = OpenProcess(PROCESS_SYNCHRONIZE, 0, pid);
             if handle.is_null() {
                 return false;
             }
+            // An exited process can still be opened while another handle
+            // keeps its kernel object alive. Poll its termination signal;
+            // unlike checking STILL_ACTIVE, this also handles exit code 259.
+            let alive = WaitForSingleObject(handle, 0) == WAIT_TIMEOUT;
             CloseHandle(handle);
-            true
+            alive
         }
     }
 
@@ -110,3 +114,39 @@ pub fn pid_alive(pid: u32) -> bool {
         false
     }
 }
+
+#[cfg(all(test, windows))]
+mod tests {
+    use super::pid_alive;
+    use std::os::windows::process::CommandExt;
+    use std::process::Command;
+
+    #[test]
+    fn current_process_is_alive() {
+        assert!(pid_alive(std::process::id()));
+    }
+
+    #[test]
+    fn invalid_process_is_not_alive() {
+        assert!(!pid_alive(0));
+        assert!(!pid_alive(u32::MAX));
+    }
+
+    #[test]
+    fn exited_process_with_retained_handle_is_not_alive() {
+        for exit_code in [0, 259] {
+            let mut child = Command::new("cmd.exe")
+                .args(["/D", "/C", &format!("exit {exit_code}")])
+                .creation_flags(0x0800_0000) // CREATE_NO_WINDOW
+                .spawn()
+                .expect("spawn short-lived process");
+            assert_eq!(child.wait().unwrap().code(), Some(exit_code));
+            // Keep Child (and its process handle) alive during the probe.
+            assert!(
+                !pid_alive(child.id()),
+                "exited process with code {exit_code}"
+            );
+            drop(child);
+        }
+    }
+}

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

@@ -232,8 +232,8 @@ pub fn run_foreground(cfg: DaemonConfig) -> Result<()> {
         let session_idle_task = spawn_session_idle_reaper(Arc::clone(&state));
         let browser_liveness_task = spawn_browser_liveness_reaper(Arc::clone(&state));
         // Fired by the update check task after a successful auto-update:
-        // the replacement daemon has already been spawned, so this
-        // process should shut down and let it take over.
+        // the replacement daemon (or Windows update helper) is ready, so
+        // this process should shut down and let it take over.
         let restart_notify = Arc::new(tokio::sync::Notify::new());
         let update_check_task =
             spawn_update_check_task(Arc::clone(&state), Arc::clone(&restart_notify));
@@ -539,8 +539,8 @@ pub(crate) fn spawn_session_idle_reaper(state: Arc<DaemonState>) -> tokio::task:
 /// task spawns the replacement daemon (see
 /// [`DAEMON_REPLACEMENT_WAIT_ENV`]) and fires `restart` so this process
 /// shuts down and the new version takes over; on Windows the
-/// replacement can only be staged, so it just logs that a restart is
-/// needed.
+/// helper waits for this process to exit, replaces the binary, and starts
+/// the new daemon with the same configuration.
 pub(crate) fn spawn_update_check_task(
     state: Arc<DaemonState>,
     restart: Arc<tokio::sync::Notify>,
@@ -605,7 +605,11 @@ pub(crate) fn spawn_update_check_task(
                         |candidate| {
                             let target =
                                 exe_path.as_deref().context("current executable unknown")?;
-                            update::self_install_candidate(candidate, target)
+                            update::self_install_candidate(
+                                candidate,
+                                target,
+                                &restart_start_args(&state.config),
+                            )
                         },
                     )
                 })
@@ -635,10 +639,11 @@ pub(crate) fn spawn_update_check_task(
                     sessions,
                     "auto-update postponed: agent session(s) active; will retry on the next tick"
                 ),
-                update::AutoUpdateOutcome::Staged { latest } => warn!(
-                    %latest,
-                    "auto-update staged the new binary but cannot replace the running daemon in place; restart the daemon (or terminal) to finish the upgrade"
-                ),
+                update::AutoUpdateOutcome::Staged { latest } => {
+                    info!(%latest, "update helper ready; exiting so it can replace and restart the daemon");
+                    restart.notify_one();
+                    return;
+                }
                 update::AutoUpdateOutcome::Replaced { latest } => {
                     info!(
                         current = env!("CARGO_PKG_VERSION"),

crates/bsk-cli/src/main.rs

@@ -94,6 +94,9 @@ fn dispatch(cli: Cli, format: Format) -> Result<(), CliError> {
         Command::Reload(args) => cli::navigate::dispatch_reload(args, format),
         Command::Click(args) => cli::interaction::dispatch_click(args, format),
         Command::Hover(args) => cli::interaction::dispatch_hover(args, format),
+        Command::ScrollTo(args) => cli::scroll::dispatch(args, format),
+        Command::Focus(args) => cli::interaction::dispatch_focus(args, format),
+        Command::Blur(args) => cli::interaction::dispatch_blur(args, format),
         Command::Fill(args) => cli::interaction::dispatch_fill(args, format),
         Command::Press(args) => cli::interaction::dispatch_press(args, format),
         Command::Select(args) => cli::interaction::dispatch_select(args, format),

crates/bsk-cli/tests/cli_parse.rs

@@ -255,6 +255,65 @@ fn parses_hover_with_settle() {
     assert_eq!(args.settle, 300);
 }
 
+#[test]
+fn parses_scroll_to_target() {
+    let cli = parse(&["bsk", "scroll-to", "@e2", "--session", "s1"]);
+    let Command::ScrollTo(args) = cli.command else {
+        panic!("expected scroll-to command");
+    };
+    assert_eq!(args.target.as_deref(), Some("@e2"));
+}
+
+#[test]
+fn parses_scroll_to_explicit_target_tab_and_timeout() {
+    for flag in ["--ref", "--selector"] {
+        let cli = parse(&[
+            "bsk",
+            "scroll-to",
+            flag,
+            "e3",
+            "--session",
+            "s1",
+            "--tab-id",
+            "42",
+            "--timeout",
+            "5s",
+        ]);
+        let Command::ScrollTo(args) = cli.command else {
+            panic!("expected scroll-to command");
+        };
+        assert_eq!(args.tab_id, Some(42));
+        assert_eq!(args.timeout, 5_000);
+        assert_eq!(
+            if flag == "--ref" {
+                args.ref_
+            } else {
+                args.selector
+            }
+            .as_deref(),
+            Some("e3")
+        );
+    }
+}
+
+#[test]
+fn parses_focus_target() {
+    let cli = parse(&["bsk", "focus", "@e2", "--session", "s1"]);
+    let Command::Focus(args) = cli.command else {
+        panic!("expected focus command");
+    };
+    assert_eq!(args.target.as_deref(), Some("@e2"));
+}
+
+#[test]
+fn parses_blur_selector() {
+    let cli = parse(&["bsk", "blur", "--selector", "#search", "--session", "s1"]);
+    let Command::Blur(args) = cli.command else {
+        panic!("expected blur command");
+    };
+    assert_eq!(args.selector.as_deref(), Some("#search"));
+}
+
 #[test]
 fn rejects_zero_click_count() {
     assert!(

crates/bsk-cli/tests/session_user_interrupt.rs

@@ -293,6 +293,15 @@ async fn session_user_interrupt_event_cancels_inflight_with_user_aborted() {
 /// catch a tool dispatched arbitrarily later.
 #[tokio::test(flavor = "multi_thread", worker_threads = 4)]
 async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle() {
+    assert_idle_interrupt_rejects(Method::ToolClick).await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
+async fn user_interrupt_rejects_scroll_to_before_forwarding() {
+    assert_idle_interrupt_rejects(Method::ToolScrollTo).await;
+}
+
+async fn assert_idle_interrupt_rejects(method: Method) {
     let (handle, sock) = spawn_daemon().await;
     let mut ws = connect_ext(handle.ws_addr()).await;
     let _ = handshake_as_ext(&mut ws).await;
@@ -301,10 +310,11 @@ async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle()
 
     // Fake extension: answer tool.session_start, observe other
     // requests but never reply. We expect the daemon to reject the
-    // tool call BEFORE it ever forwards a tool.click frame.
+    // tool call BEFORE it ever forwards a browser-input frame.
     let ws_sink_for_responder = Arc::clone(&ws_sink);
-    let observed_click_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
-    let observed_click_count_clone = Arc::clone(&observed_click_count);
+    let observed_call_count = Arc::new(std::sync::atomic::AtomicUsize::new(0));
+    let observed_call_count_clone = Arc::clone(&observed_call_count);
+    let forwarded_method = method.clone();
     let responder = tokio::spawn(async move {
         let mut ws_stream = ws_stream;
         while let Some(Ok(msg)) = ws_stream.next().await {
@@ -329,8 +339,8 @@ async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle()
                     g.send(Message::Text(serde_json::to_string(&reply).unwrap()))
                         .await
                         .unwrap();
-                } else if req.method == Method::ToolClick {
-                    observed_click_count_clone.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                } else if req.method == forwarded_method {
+                    observed_call_count_clone.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                     // Deliberately do NOT reply — daemon should reject before
                     // ever forwarding to us.
                     let _ = req;
@@ -377,12 +387,12 @@ async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle()
     let state = handle.state();
     wait_for_session_interrupt_pending(&state, &start.session_id).await;
 
-    // The CLI now issues a tool.click (mutating). The daemon must
+    // The CLI now issues a browser-input (mutating). The daemon must
     // reject it WITHOUT forwarding to the extension.
-    let click_outcome = ipc
+    let outcome = ipc
         .call::<_, serde_json::Value>(
-            "click-after-interrupt",
-            Method::ToolClick,
+            "input-after-interrupt",
+            method,
             Some(json!({
                 "session_id": start.session_id,
                 "ref": "fake-ref-1",
@@ -391,7 +401,7 @@ async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle()
         )
         .await
         .unwrap();
-    let err = click_outcome.expect_err("tool.click must be rejected");
+    let err = outcome.expect_err("browser-input must be rejected");
     assert_eq!(
         err.code,
         ErrorCode::UserAborted,
@@ -399,11 +409,11 @@ async fn user_interrupt_rejects_next_mutating_tool_call_when_session_was_idle()
         err
     );
 
-    // Crucially: the extension never saw a tool.click frame.
+    // Crucially: the extension never saw a browser-input frame.
     assert_eq!(
-        observed_click_count.load(std::sync::atomic::Ordering::SeqCst),
+        observed_call_count.load(std::sync::atomic::Ordering::SeqCst),
         0,
-        "tool.click must NOT have been forwarded to the extension"
+        "browser-input must NOT have been forwarded to the extension"
     );
 
     responder.abort();

crates/bsk-cli/tests/tools_m7_ipc.rs

@@ -1,5 +1,4 @@
-//! M7 integration: drive the 7 new tool RPCs (navigate /
-//! navigate_back / navigate_forward / reload / click / fill / press)
+//! M7 integration: drive interaction and navigation tool RPCs
 //! through the IPC + per-session queue + fake extension and assert
 //! the wire shapes line up. The extension stub mirrors each method's
 //! `*Result` so we exercise the daemon's serialise → forward →
@@ -13,11 +12,13 @@ use bsk::daemon::{self, DaemonConfig};
 use bsk::ipc_client::IpcClient;
 use bsk_protocol::system::{HandshakeParams, HandshakeResult};
 use bsk_protocol::tools::{
-    ClickParams, ClickResult, FillParams, FillResult, KeyModifier, MouseButton, NavigateBackParams,
-    NavigateBackResult, NavigateForwardParams, NavigateForwardResult, NavigateParams,
-    NavigateResult, PressParams, PressResult, ReloadParams, ReloadResult, SelectParams,
-    SelectResult, SessionStartParams, SessionStartResult, WaitUntil,
+    BlurParams, BlurResult, ClickParams, ClickResult, FillParams, FillResult, FocusParams,
+    FocusResult, KeyModifier, MouseButton, NavigateBackParams, NavigateBackResult,
+    NavigateForwardParams, NavigateForwardResult, NavigateParams, NavigateResult, PressParams,
+    PressResult, ReloadParams, ReloadResult, SelectParams, SelectResult, SessionStartParams,
+    SessionStartResult, WaitUntil,
 };
+use bsk_protocol::tools::{ScrollToParams, ScrollToResult};
 use bsk_protocol::{
     BrowserPeerInfo, ErrorCode, Frame, Method, RequestFrame, ResponseBody, ResponseFrame, RpcError,
 };
@@ -382,6 +383,137 @@ async fn click_round_trips_ref_and_modifiers() {
     handle.shutdown().await;
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn focus_round_trips_verified_state() {
+    let (handle, sock) = spawn_daemon().await;
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = do_handshake(&mut ws).await;
+
+    run_extension(ws, |req| {
+        assert_eq!(req.method, Method::ToolFocus);
+        let params = req.params.clone().unwrap();
+        let p: FocusParams = serde_json::from_value(params).unwrap();
+        assert_eq!(p.ref_.as_deref(), Some("@e3"));
+        ResponseBody::Ok(
+            serde_json::to_value(FocusResult {
+                tab_id: 9,
+                used_ref: Some("e3".into()),
+                used_selector: None,
+                focused: true,
+                dialogs: vec![],
+            })
+            .unwrap(),
+        )
+    });
+
+    let session_id = ipc_session_start(&sock).await;
+    let result: FocusResult = ipc_tool_call(
+        &sock,
+        Method::ToolFocus,
+        FocusParams {
+            session_id,
+            ref_: Some("@e3".into()),
+            selector: None,
+            tab_id: None,
+            timeout_ms: Some(5_000),
+        },
+    )
+    .await
+    .expect("focus ok");
+    assert!(result.focused);
+    assert_eq!(result.used_ref.as_deref(), Some("e3"));
+    handle.shutdown().await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn blur_round_trips_previous_focus_state() {
+    let (handle, sock) = spawn_daemon().await;
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = do_handshake(&mut ws).await;
+
+    run_extension(ws, |req| {
+        assert_eq!(req.method, Method::ToolBlur);
+        let params = req.params.clone().unwrap();
+        let p: BlurParams = serde_json::from_value(params).unwrap();
+        assert_eq!(p.selector.as_deref(), Some("#search"));
+        ResponseBody::Ok(
+            serde_json::to_value(BlurResult {
+                tab_id: 9,
+                used_ref: None,
+                used_selector: Some("#search".into()),
+                was_focused: true,
+                focused: false,
+                dialogs: vec![],
+            })
+            .unwrap(),
+        )
+    });
+
+    let session_id = ipc_session_start(&sock).await;
+    let result: BlurResult = ipc_tool_call(
+        &sock,
+        Method::ToolBlur,
+        BlurParams {
+            session_id,
+            ref_: None,
+            selector: Some("#search".into()),
+            tab_id: None,
+            timeout_ms: Some(5_000),
+        },
+    )
+    .await
+    .expect("blur ok");
+    assert!(result.was_focused);
+    assert!(!result.focused);
+    assert_eq!(result.used_selector.as_deref(), Some("#search"));
+    handle.shutdown().await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn scroll_to_round_trips_visible_bounds() {
+    let (handle, sock) = spawn_daemon().await;
+    let mut ws = connect_ext(handle.ws_addr()).await;
+    let _ = do_handshake(&mut ws).await;
+
+    run_extension(ws, |req| {
+        assert_eq!(req.method, Method::ToolScrollTo);
+        let params = req.params.clone().unwrap();
+        let parsed: ScrollToParams = serde_json::from_value(params).unwrap();
+        assert_eq!(parsed.ref_.as_deref(), Some("@e3"));
+        ResponseBody::Ok(
+            serde_json::to_value(ScrollToResult {
+                tab_id: 9,
+                used_ref: Some("e3".into()),
+                used_selector: None,
+                x: 10.0,
+                y: 20.0,
+                width: 100.0,
+                height: 40.0,
+                dialogs: vec![],
+            })
+            .unwrap(),
+        )
+    });
+
+    let session_id = ipc_session_start(&sock).await;
+    let result: ScrollToResult = ipc_tool_call(
+        &sock,
+        Method::ToolScrollTo,
+        ScrollToParams {
+            session_id,
+            ref_: Some("@e3".into()),
+            selector: None,
+            tab_id: None,
+            timeout_ms: Some(5_000),
+        },
+    )
+    .await
+    .expect("scroll-to ok");
+    assert_eq!(result.used_ref.as_deref(), Some("e3"));
+    assert_eq!(result.width, 100.0);
+    handle.shutdown().await;
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn fill_round_trips_clear_before_default() {
     let (handle, sock) = spawn_daemon().await;

crates/bsk-cli/tests/windows_parent_cancel.rs

@@ -0,0 +1,342 @@
+//! Real Windows CLI cancellation, including caller-owned transfer cleanup.
+#![cfg(windows)]
+
+use std::path::Path;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
+
+use bsk::daemon::{file_transfer::TransferRegistry, info::DaemonInfo};
+use bsk_protocol::tools::{TransferBeginParams, TransferIdParams};
+use bsk_protocol::{ErrorCode, Frame, Method, ResponseBody, ResponseFrame, RpcError};
+use serde_json::json;
+use tokio::io::{AsyncBufReadExt, AsyncWriteExt, BufReader};
+use tokio::net::windows::named_pipe::ServerOptions;
+use tokio::process::Command;
+use tokio::sync::{Notify, watch};
+
+fn response<T: serde::Serialize>(result: Result<T, RpcError>) -> ResponseBody {
+    match result {
+        Ok(value) => ResponseBody::Ok(serde_json::to_value(value).unwrap()),
+        Err(err) => ResponseBody::Err(err),
+    }
+}
+
+#[test]
+fn stdin_close_cancels_business_but_releases_resources_with_a_bounded_budget() {
+    // Resolve the production registry's root before starting any runtime threads.
+    let registry_home = tempfile::tempdir().unwrap();
+    let original_home = std::env::var_os("BSK_HOME");
+    unsafe {
+        std::env::set_var("BSK_HOME", registry_home.path());
+    }
+    let transfers = Arc::new(TransferRegistry::new().unwrap());
+    unsafe {
+        match original_home {
+            Some(value) => std::env::set_var("BSK_HOME", value),
+            None => std::env::remove_var("BSK_HOME"),
+        }
+    }
+    transfers.initialize().unwrap();
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .unwrap()
+        .block_on(exercise(
+            transfers,
+            &registry_home.path().join("run/transfers"),
+        ));
+}
+
+async fn exercise(transfers: Arc<TransferRegistry>, staging_root: &Path) {
+    for mode in [
+        "wait",
+        "upload",
+        "upload-multi",
+        "upload-before-dispatch",
+        "download",
+        "upload-multi-stall",
+        "ordinary",
+    ] {
+        let home = tempfile::tempdir().unwrap();
+        let pipe_name = format!(r"\\.\pipe\bsk-parent-cancel-{}", uuid::Uuid::new_v4());
+        let info = DaemonInfo::now(std::process::id(), (&pipe_name).into(), 0, "0.2.0");
+        std::fs::write(
+            home.path().join("daemon.json"),
+            serde_json::to_vec(&info).unwrap(),
+        )
+        .unwrap();
+        let mut pipe = ServerOptions::new()
+            .first_pipe_instance(true)
+            .create(&pipe_name)
+            .unwrap();
+        let registered = Arc::new(Notify::new());
+        let pending = Arc::new(Mutex::new(None::<String>));
+        let ids = Arc::new(Mutex::new(Vec::<String>::new()));
+        let released = Arc::new(Mutex::new(Vec::<String>::new()));
+        let received = Arc::new(Mutex::new(Vec::<Method>::new()));
+        let download_id = if mode == "download" {
+            let staging = transfers.begin_download("fixture").unwrap();
+            let browser_dir = home.path().join("BrowserSkill").join(&staging.transfer_id);
+            std::fs::create_dir_all(&browser_dir).unwrap();
+            let file = browser_dir.join("download.txt");
+            std::fs::write(&file, b"download fixture").unwrap();
+            transfers
+                .import_download(&staging.transfer_id, &file)
+                .unwrap();
+            ids.lock().unwrap().push(staging.transfer_id.clone());
+            Some(staging.transfer_id)
+        } else {
+            None
+        };
+        let (cancel, cancelled) = watch::channel(false);
+        let ready = Arc::clone(&registered);
+        let name = pipe_name.clone();
+        let registry = Arc::clone(&transfers);
+        let server_ids = Arc::clone(&ids);
+        let server_released = Arc::clone(&released);
+        let server_received = Arc::clone(&received);
+        let server = tokio::spawn(async move {
+            let mut connections = tokio::task::JoinSet::new();
+            loop {
+                pipe.connect().await.unwrap();
+                let next = ServerOptions::new().create(&name).unwrap();
+                let connection = std::mem::replace(&mut pipe, next);
+                let ready = Arc::clone(&ready);
+                let pending = Arc::clone(&pending);
+                let cancel = cancel.clone();
+                let mut cancelled = cancelled.clone();
+                let name = name.clone();
+                let registry = Arc::clone(&registry);
+                let ids = Arc::clone(&server_ids);
+                let released = Arc::clone(&server_released);
+                let received = Arc::clone(&server_received);
+                let download_id = download_id.clone();
+                connections.spawn(async move {
+                    let (read, mut write) = tokio::io::split(connection);
+                    let mut reader = BufReader::new(read);
+                    let mut line = String::new();
+                    while reader.read_line(&mut line).await.unwrap_or(0) > 0 {
+                        let Frame::Request(req) = serde_json::from_str::<Frame>(&line).unwrap()
+                        else {
+                            panic!("expected request");
+                        };
+                        line.clear();
+                        received.lock().unwrap().push(req.method.clone());
+                        let params = req.params.clone().unwrap_or_default();
+                        let body = match req.method {
+                            Method::SystemStatus => ResponseBody::Ok(json!({
+                                "daemon_version": "0.2.0", "protocol_version": "1.1",
+                                "pid": std::process::id(), "uptime_secs": 0,
+                                "ws_port": 0, "sock_path": name,
+                                "browsers": [], "sessions": [], "version_skew_browsers": []
+                            })),
+                            Method::TransferBegin => {
+                                let begin = registry
+                                    .begin_upload(serde_json::from_value(params).unwrap())
+                                    .unwrap();
+                                ids.lock().unwrap().push(begin.transfer_id.clone());
+                                response(Ok(begin))
+                            }
+                            Method::ToolDownload => ResponseBody::Ok(json!({
+                                "tab_id": 1, "suggested_filename": "download.txt",
+                                "byte_size": 16, "transfer_id": download_id,
+                            })),
+                            Method::ToolWaitMs if mode == "ordinary" => {
+                                ResponseBody::Ok(json!({"waited_ms": 1}))
+                            }
+                            Method::TransferChunk
+                                if mode == "upload-before-dispatch"
+                                    || (mode.contains("multi")
+                                        && ids.lock().unwrap().len() == 1) =>
+                            {
+                                response(
+                                    registry.write_chunk(serde_json::from_value(params).unwrap()),
+                                )
+                            }
+                            Method::TransferFinish if mode != "upload-before-dispatch" => response(
+                                registry.finish_upload(serde_json::from_value(params).unwrap()),
+                            ),
+                            Method::ToolWaitMs
+                            | Method::TransferChunk
+                            | Method::TransferRead
+                            | Method::TransferFinish => {
+                                *pending.lock().unwrap() = Some(req.id.clone());
+                                ready.notify_one();
+                                cancelled.wait_for(|value| *value).await.unwrap();
+                                if mode == "upload-before-dispatch" {
+                                    // Finish won the race with cancellation, but tool.upload must
+                                    // not be dispatched and the CLI still owns the staging.
+                                    response(
+                                        registry
+                                            .finish_upload(serde_json::from_value(params).unwrap()),
+                                    )
+                                } else {
+                                    ResponseBody::Err(RpcError {
+                                        code: ErrorCode::Cancelled,
+                                        message: "parent cancellation reached daemon".into(),
+                                        data: None,
+                                    })
+                                }
+                            }
+                            Method::Cancel => {
+                                let target = params["rpc_id"].as_str().unwrap();
+                                assert_eq!(pending.lock().unwrap().as_deref(), Some(target));
+                                cancel.send(true).unwrap();
+                                ResponseBody::Ok(json!({"cancelled": true}))
+                            }
+                            Method::TransferRelease => {
+                                let params: TransferIdParams =
+                                    serde_json::from_value(params).unwrap();
+                                released.lock().unwrap().push(params.transfer_id.clone());
+                                if mode.contains("stall") {
+                                    std::future::pending::<()>().await;
+                                }
+                                response(Ok(registry.release(params)))
+                            }
+                            other => panic!("unexpected request after cancellation: {other:?}"),
+                        };
+                        let response = Frame::Response(ResponseFrame { id: req.id, body });
+                        let mut bytes = serde_json::to_vec(&response).unwrap();
+                        bytes.push(b'\n');
+                        if write.write_all(&bytes).await.is_err() {
+                            break;
+                        }
+                    }
+                });
+            }
+        });
+
+        let mut cmd = Command::new(env!("CARGO_BIN_EXE_bsk"));
+        cmd.env("BSK_HOME", home.path())
+            .env("BSK_AUTO_UPDATE", "off")
+            .env_remove("BSK_CANCEL_ON_STDIN_CLOSE")
+            .stdout(std::process::Stdio::piped())
+            .stderr(std::process::Stdio::piped())
+            .creation_flags(0x0800_0000)
+            .kill_on_drop(true);
+        if mode.starts_with("upload") {
+            let source = home.path().join("upload.txt");
+            // Declare 300 MiB without allocating or transferring that much data.
+            std::fs::File::create(&source)
+                .unwrap()
+                .set_len(if mode == "upload-before-dispatch" {
+                    16
+                } else {
+                    300 * 1024 * 1024
+                })
+                .unwrap();
+            cmd.args(["upload", "--session", "fixture", "--selector", "input"]);
+            if mode.contains("multi") {
+                let first = home.path().join("first.txt");
+                std::fs::write(&first, b"first file").unwrap();
+                cmd.arg("--file").arg(first);
+            }
+            cmd.arg("--file").arg(source);
+        } else if mode == "download" {
+            let out = home.path().join("out.txt");
+            std::fs::write(&out, b"existing output").unwrap();
+            cmd.args([
+                "download",
+                "--session",
+                "fixture",
+                "--selector",
+                "a",
+                "--overwrite",
+                "--out",
+            ])
+            .arg(out);
+        } else {
+            cmd.args(["wait-ms", if mode == "ordinary" { "1ms" } else { "60s" }]);
+        }
+        cmd.arg("--json");
+        if mode == "ordinary" {
+            cmd.stdin(std::process::Stdio::null());
+        } else {
+            cmd.env("BSK_CANCEL_ON_STDIN_CLOSE", "1")
+                .stdin(std::process::Stdio::piped());
+        }
+        let mut child = cmd.spawn().unwrap();
+        if mode != "ordinary" {
+            tokio::time::timeout(Duration::from_secs(10), registered.notified())
+                .await
+                .expect("CLI registered business RPC");
+            child
+                .stdin
+                .as_mut()
+                .unwrap()
+                .write_all(b"still connected")
+                .await
+                .unwrap();
+            drop(child.stdin.take());
+        }
+        let start = Instant::now();
+        let output = tokio::time::timeout(Duration::from_secs(8), child.wait_with_output())
+            .await
+            .expect("CLI must settle promptly, including cleanup")
+            .unwrap();
+        server.abort();
+        let _ = server.await;
+        assert_eq!(
+            output.status.code(),
+            Some(if mode == "ordinary" { 0 } else { 2 }),
+            "{mode}: stdout={} stderr={}",
+            String::from_utf8_lossy(&output.stdout),
+            String::from_utf8_lossy(&output.stderr)
+        );
+        if mode != "ordinary" {
+            let body: serde_json::Value = serde_json::from_slice(&output.stdout).unwrap();
+            assert_eq!(body["code"], "cancelled");
+            if mode != "upload-before-dispatch" {
+                assert_eq!(body["message"], "parent cancellation reached daemon");
+            }
+            let received = received.lock().unwrap();
+            let cancel = received.iter().position(|m| *m == Method::Cancel).unwrap();
+            assert!(
+                received[cancel + 1..]
+                    .iter()
+                    .all(|m| *m == Method::TransferRelease),
+                "only cleanup may follow cancellation: {received:?}"
+            );
+        }
+        let ids = ids.lock().unwrap();
+        if mode.contains("stall") {
+            assert_eq!(released.lock().unwrap().len(), 1);
+            assert!(start.elapsed() >= Duration::from_secs(4));
+            // The CLI cannot force an unresponsive daemon to clean up.
+            transfers.release_session("fixture");
+        } else {
+            assert_eq!(
+                *released.lock().unwrap(),
+                *ids,
+                "{mode}: every allocation must be released"
+            );
+            for id in ids.iter() {
+                assert!(!staging_root.join(id).exists(), "staging leaked: {id}");
+            }
+            if mode.starts_with("upload") {
+                let retry = transfers
+                    .begin_upload(TransferBeginParams {
+                        session_id: "fixture".into(),
+                        name: "retry.txt".into(),
+                        byte_size: 300 * 1024 * 1024,
+                    })
+                    .expect("same session must have room for another 300 MiB upload");
+                transfers.release(TransferIdParams {
+                    transfer_id: retry.transfer_id,
+                });
+            }
+        }
+        if mode == "download" {
+            assert_eq!(
+                std::fs::read(home.path().join("out.txt")).unwrap(),
+                b"existing output"
+            );
+            assert!(
+                !std::fs::read_dir(home.path())
+                    .unwrap()
+                    .flatten()
+                    .any(|entry| entry.file_name().to_string_lossy().ends_with(".part"))
+            );
+        }
+    }
+}

crates/bsk-cli/tests/windows_update.rs

@@ -0,0 +1,343 @@
+//! Exercise self-update with a real executable and a local release server.
+#![cfg(windows)]
+
+use std::fs;
+use std::io::{Cursor, Read, Write};
+use std::net::{TcpListener, TcpStream};
+use std::os::windows::process::CommandExt;
+use std::path::PathBuf;
+use std::process::{Child, Command, Stdio};
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
+use std::thread;
+use std::time::{Duration, Instant};
+
+use bsk::daemon::info::DaemonInfo;
+use sha2::{Digest, Sha256};
+
+const MARKER: &[u8] = b"windows-update-regression-fixture";
+
+struct ReleaseServer {
+    url: String,
+    requests: Arc<AtomicUsize>,
+    stop: Arc<AtomicBool>,
+    worker: Option<thread::JoinHandle<()>>,
+}
+
+impl ReleaseServer {
+    fn new(binary: &[u8]) -> Self {
+        let mut archive = zip::ZipWriter::new(Cursor::new(Vec::new()));
+        archive
+            .start_file(
+                "bsk.exe",
+                zip::write::SimpleFileOptions::default()
+                    .compression_method(zip::CompressionMethod::Stored),
+            )
+            .unwrap();
+        archive.write_all(binary).unwrap();
+        let archive = archive.finish().unwrap().into_inner();
+        let listener = TcpListener::bind("127.0.0.1:0").unwrap();
+        listener.set_nonblocking(true).unwrap();
+        let url = format!("http://{}", listener.local_addr().unwrap());
+        let manifest = serde_json::to_vec(&serde_json::json!({
+            "version": "999.0.0",
+            "assets": {"windows-x64": {
+                "url": format!("{url}/bsk.zip"),
+                "sha256": Sha256::digest(&archive).iter().map(|byte| format!("{byte:02x}")).collect::<String>(),
+            }},
+        }))
+        .unwrap();
+        let stop = Arc::new(AtomicBool::new(false));
+        let worker_stop = Arc::clone(&stop);
+        let requests = Arc::new(AtomicUsize::new(0));
+        let worker_requests = Arc::clone(&requests);
+        let worker = thread::spawn(move || {
+            while !worker_stop.load(Ordering::SeqCst) {
+                let (mut stream, _) = match listener.accept() {
+                    Ok(connection) => connection,
+                    Err(err) if err.kind() == std::io::ErrorKind::WouldBlock => {
+                        thread::sleep(Duration::from_millis(10));
+                        continue;
+                    }
+                    Err(err) => panic!("accept release request: {err}"),
+                };
+                // Windows accept() inherits the listener's nonblocking mode.
+                // Keep accept polling for shutdown, but read/write each request
+                // in blocking mode with the bounded timeouts below.
+                stream.set_nonblocking(false).unwrap();
+                stream
+                    .set_read_timeout(Some(Duration::from_secs(5)))
+                    .unwrap();
+                stream
+                    .set_write_timeout(Some(Duration::from_secs(5)))
+                    .unwrap();
+                let mut request = Vec::new();
+                let mut chunk = [0; 1024];
+                while !request.windows(4).any(|window| window == b"\r\n\r\n") {
+                    let len = stream.read(&mut chunk).unwrap();
+                    if len == 0 {
+                        break;
+                    }
+                    request.extend_from_slice(&chunk[..len]);
+                }
+                let body = if request.starts_with(b"GET /bsk.zip ") {
+                    worker_requests.fetch_add(1, Ordering::SeqCst);
+                    &archive
+                } else {
+                    &manifest
+                };
+                write!(
+                    stream,
+                    "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n",
+                    body.len()
+                )
+                .unwrap();
+                stream.write_all(body).unwrap();
+            }
+        });
+        Self {
+            url: format!("{url}/version.json"),
+            requests,
+            stop,
+            worker: Some(worker),
+        }
+    }
+}
+
+impl Drop for ReleaseServer {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::SeqCst);
+        let _ = self.worker.take().unwrap().join();
+    }
+}
+
+#[test]
+fn release_server_waits_for_delayed_and_fragmented_request_headers() {
+    let server = ReleaseServer::new(b"test binary");
+    let address = server
+        .url
+        .strip_prefix("http://")
+        .unwrap()
+        .strip_suffix("/version.json")
+        .unwrap();
+    let mut stream = TcpStream::connect(address).unwrap();
+    stream
+        .set_read_timeout(Some(Duration::from_secs(5)))
+        .unwrap();
+    stream
+        .set_write_timeout(Some(Duration::from_secs(5)))
+        .unwrap();
+    // Give accept() time to run before any bytes arrive, then split the
+    // headers across writes. Both reads must wait rather than return WouldBlock.
+    thread::sleep(Duration::from_millis(100));
+    stream.write_all(b"GET /version.json HTTP/1.1\r\n").unwrap();
+    thread::sleep(Duration::from_millis(100));
+    stream.write_all(b"Host: localhost\r\n\r\n").unwrap();
+    let mut response = String::new();
+    stream.read_to_string(&mut response).unwrap();
+    assert!(response.starts_with("HTTP/1.1 200 OK\r\n"), "{response}");
+    let (_, body) = response.split_once("\r\n\r\n").unwrap();
+    let manifest: serde_json::Value = serde_json::from_str(body).unwrap();
+    assert_eq!(manifest["version"], "999.0.0");
+}
+
+struct Fixture {
+    _tmp: tempfile::TempDir,
+    exe: PathBuf,
+    home: PathBuf,
+    binary: Vec<u8>,
+    server: ReleaseServer,
+    daemon: Option<Child>,
+}
+
+impl Fixture {
+    fn new() -> Self {
+        let tmp = tempfile::TempDir::new().unwrap();
+        let dir = tmp.path().join("中文 space %PATH% ! & (update)");
+        fs::create_dir(&dir).unwrap();
+        let exe = dir.join("bsk.exe");
+        let home = tmp.path().join("home");
+        fs::create_dir(&home).unwrap();
+        fs::copy(env!("CARGO_BIN_EXE_bsk"), &exe).unwrap();
+        // A PE overlay distinguishes the replacement without requiring a
+        // second build or changing the executable's behavior/version.
+        let mut binary = fs::read(&exe).unwrap();
+        binary.extend_from_slice(MARKER);
+        let server = ReleaseServer::new(&binary);
+        Self {
+            _tmp: tmp,
+            exe,
+            home,
+            binary,
+            server,
+            daemon: None,
+        }
+    }
+
+    fn command(&self) -> Command {
+        let mut cmd = Command::new(&self.exe);
+        cmd.env("BSK_HOME", &self.home)
+            .env("BSK_UPDATE_MANIFEST_URL", &self.server.url)
+            .env("BSK_AUTO_UPDATE", "off")
+            .env("RUST_LOG", "info")
+            .env("NO_PROXY", "127.0.0.1,localhost")
+            .env_remove("BSK_DAEMONIZED")
+            .env_remove("BSK_DAEMON_REPLACES_PID")
+            .stdin(Stdio::null())
+            .creation_flags(0x0800_0000);
+        cmd
+    }
+
+    fn wait_for(&self, description: &str, mut check: impl FnMut() -> bool) {
+        let deadline = Instant::now() + Duration::from_secs(30);
+        while Instant::now() < deadline {
+            if check() {
+                return;
+            }
+            thread::sleep(Duration::from_millis(50));
+        }
+        let diagnostics: Vec<_> = fs::read_dir(self.exe.parent().unwrap())
+            .unwrap()
+            .flatten()
+            .filter(|entry| entry.path().extension().is_some_and(|ext| ext == "log"))
+            .map(|entry| {
+                (
+                    entry.path(),
+                    String::from_utf8_lossy(&fs::read(entry.path()).unwrap_or_default())
+                        .into_owned(),
+                )
+            })
+            .collect();
+        let home_logs: Vec<_> = fs::read_dir(&self.home)
+            .unwrap()
+            .flatten()
+            .filter(|entry| entry.file_name().to_string_lossy().contains("log"))
+            .map(|entry| {
+                (
+                    entry.path(),
+                    String::from_utf8_lossy(&fs::read(entry.path()).unwrap_or_default())
+                        .into_owned(),
+                )
+            })
+            .collect();
+        panic!(
+            "timed out waiting for {description}; helper logs: {diagnostics:?}; daemon logs: {home_logs:?}"
+        );
+    }
+
+    fn info(&self) -> Option<DaemonInfo> {
+        serde_json::from_slice(&fs::read(self.home.join("daemon.json")).ok()?).ok()
+    }
+
+    fn updated(&self) -> bool {
+        // A locked executable may briefly reject reads during replacement.
+        fs::read(&self.exe).is_ok_and(|binary| binary == self.binary)
+    }
+}
+
+impl Drop for Fixture {
+    fn drop(&mut self) {
+        // Stop only the daemon belonging to this isolated BSK_HOME. Also reap
+        // the foreground process on assertion failures to avoid leaking locks.
+        let _ = self.command().args(["daemon", "stop"]).output();
+        if let Some(child) = self.daemon.as_mut() {
+            let _ = child.kill();
+            let _ = child.wait();
+        }
+    }
+}
+
+#[test]
+fn manual_update_replaces_the_running_executable_after_cli_exit() {
+    let fixture = Fixture::new();
+    let out = fixture
+        .command()
+        .args(["--json", "update", "--yes"])
+        .output()
+        .unwrap();
+    assert!(
+        out.status.success(),
+        "{}",
+        String::from_utf8_lossy(&out.stderr)
+    );
+    let report: serde_json::Value = serde_json::from_slice(&out.stdout).unwrap();
+    assert_eq!(report["status"], "staged");
+    fixture.wait_for("CLI replacement and helper cleanup", || {
+        fixture.updated() && fs::read_dir(fixture.exe.parent().unwrap()).unwrap().count() == 1
+    });
+    assert!(
+        fixture.info().is_none(),
+        "an update must not start a previously absent daemon"
+    );
+    assert_eq!(fixture.server.requests.load(Ordering::SeqCst), 1);
+}
+
+#[test]
+fn automatic_update_exits_old_daemon_and_restarts_on_the_same_port() {
+    let mut fixture = Fixture::new();
+    let port = unused_port();
+    let log = fs::File::create(fixture.home.join("foreground.log")).unwrap();
+    let child = fixture
+        .command()
+        .env("BSK_AUTO_UPDATE", "on")
+        // Exercise the environment inherited by a normally detached daemon.
+        .env("BSK_DAEMONIZED", "1")
+        .args([
+            "daemon",
+            "start",
+            "--port",
+            &port.to_string(),
+            "--session-idle",
+            "1234ms",
+            "--daemon-idle",
+            "30s",
+        ])
+        .stdout(Stdio::from(log.try_clone().unwrap()))
+        .stderr(Stdio::from(log))
+        .spawn()
+        .unwrap();
+    let old_pid = child.id();
+    fixture.daemon = Some(child);
+    fixture.wait_for("replacement daemon", || {
+        fixture.updated()
+            && fixture
+                .info()
+                .is_some_and(|info| info.pid != old_pid && info.ws_port == port)
+    });
+    assert!(
+        fixture
+            .daemon
+            .as_mut()
+            .unwrap()
+            .try_wait()
+            .unwrap()
+            .is_some(),
+        "old daemon must exit"
+    );
+    fixture.wait_for("helper cleanup", || {
+        fs::read_dir(fixture.exe.parent().unwrap()).unwrap().count() == 1
+    });
+    let status = fixture
+        .command()
+        .args(["--json", "status"])
+        .output()
+        .unwrap();
+    assert!(
+        status.status.success(),
+        "{}",
+        String::from_utf8_lossy(&status.stderr)
+    );
+    assert_eq!(
+        fixture.server.requests.load(Ordering::SeqCst),
+        1,
+        "the replacement must not stage another update immediately"
+    );
+}
+
+fn unused_port() -> u16 {
+    TcpListener::bind("127.0.0.1:0")
+        .unwrap()
+        .local_addr()
+        .unwrap()
+        .port()
+}

crates/bsk-protocol/schema/tool_blur_params.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BlurParams",
+  "type": "object",
+  "required": [
+    "session_id"
+  ],
+  "properties": {
+    "ref": {
+      "description": "Optional `@e<N>` ref allocated by the last observation. Mutually exclusive with `selector`.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tab_id": {
+      "description": "Target tab. Defaults to the Agent Window's active tab.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    },
+    "timeout_ms": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 1.0
+    }
+  }
+}

crates/bsk-protocol/schema/tool_blur_result.json

@@ -0,0 +1,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "BlurResult",
+  "type": "object",
+  "required": [
+    "focused",
+    "tab_id",
+    "was_focused"
+  ],
+  "properties": {
+    "dialogs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/JavaScriptDialogInfo"
+      }
+    },
+    "focused": {
+      "description": "Always false for a successful blur; included for machine verification.",
+      "type": "boolean"
+    },
+    "tab_id": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "used_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "was_focused": {
+      "description": "Whether the target held focus before the call.",
+      "type": "boolean"
+    }
+  },
+  "definitions": {
+    "JavaScriptDialogHandledAction": {
+      "description": "How the extension resolved the dialog so CDP could continue.",
+      "type": "string",
+      "enum": [
+        "accepted",
+        "dismissed"
+      ]
+    },
+    "JavaScriptDialogInfo": {
+      "description": "One observed + handled JavaScript dialog during a tool call.",
+      "type": "object",
+      "required": [
+        "handled",
+        "message",
+        "sequence",
+        "tab_id",
+        "type"
+      ],
+      "properties": {
+        "default_prompt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "handled": {
+          "$ref": "#/definitions/JavaScriptDialogHandledAction"
+        },
+        "has_browser_handler": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "sequence": {
+          "description": "Monotonic per-tab sequence for ordering within a session.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "tab_id": {
+          "type": "integer",
+          "format": "int64"
+        },
+        "type": {
+          "$ref": "#/definitions/JavaScriptDialogType"
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "JavaScriptDialogType": {
+      "description": "Native JS dialog kind reported by CDP.",
+      "type": "string",
+      "enum": [
+        "alert",
+        "confirm",
+        "prompt",
+        "beforeunload"
+      ]
+    }
+  }
+}

crates/bsk-protocol/schema/tool_focus_params.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FocusParams",
+  "type": "object",
+  "required": [
+    "session_id"
+  ],
+  "properties": {
+    "ref": {
+      "description": "Optional `@e<N>` ref allocated by the last observation. Mutually exclusive with `selector`.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tab_id": {
+      "description": "Target tab. Defaults to the Agent Window's active tab.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    },
+    "timeout_ms": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 1.0
+    }
+  }
+}

crates/bsk-protocol/schema/tool_focus_result.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FocusResult",
+  "type": "object",
+  "required": [
+    "focused",
+    "tab_id"
+  ],
+  "properties": {
+    "dialogs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/JavaScriptDialogInfo"
+      }
+    },
+    "focused": {
+      "description": "Whether the target holds DOM focus in its document or shadow root after the call.",
+      "type": "boolean"
+    },
+    "tab_id": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "used_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "definitions": {
+    "JavaScriptDialogHandledAction": {
+      "description": "How the extension resolved the dialog so CDP could continue.",
+      "type": "string",
+      "enum": [
+        "accepted",
+        "dismissed"
+      ]
+    },
+    "JavaScriptDialogInfo": {
+      "description": "One observed + handled JavaScript dialog during a tool call.",
+      "type": "object",
+      "required": [
+        "handled",
+        "message",
+        "sequence",
+        "tab_id",
+        "type"
+      ],
+      "properties": {
+        "default_prompt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "handled": {
+          "$ref": "#/definitions/JavaScriptDialogHandledAction"
+        },
+        "has_browser_handler": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "sequence": {
+          "description": "Monotonic per-tab sequence for ordering within a session.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "tab_id": {
+          "type": "integer",
+          "format": "int64"
+        },
+        "type": {
+          "$ref": "#/definitions/JavaScriptDialogType"
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "JavaScriptDialogType": {
+      "description": "Native JS dialog kind reported by CDP.",
+      "type": "string",
+      "enum": [
+        "alert",
+        "confirm",
+        "prompt",
+        "beforeunload"
+      ]
+    }
+  }
+}

crates/bsk-protocol/schema/tool_scroll_to_params.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ScrollToParams",
+  "type": "object",
+  "required": [
+    "session_id"
+  ],
+  "properties": {
+    "ref": {
+      "description": "Optional `@e<N>` ref allocated by the last observation. Mutually exclusive with `selector`.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "tab_id": {
+      "description": "Target tab. Defaults to the Agent Window's active tab.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "int64"
+    },
+    "timeout_ms": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 1.0
+    }
+  }
+}

crates/bsk-protocol/schema/tool_scroll_to_result.json

@@ -0,0 +1,123 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "ScrollToResult",
+  "type": "object",
+  "required": [
+    "height",
+    "tab_id",
+    "width",
+    "x",
+    "y"
+  ],
+  "properties": {
+    "dialogs": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/JavaScriptDialogInfo"
+      }
+    },
+    "height": {
+      "type": "number",
+      "format": "double"
+    },
+    "tab_id": {
+      "type": "integer",
+      "format": "int64"
+    },
+    "used_ref": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "used_selector": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "width": {
+      "type": "number",
+      "format": "double"
+    },
+    "x": {
+      "description": "Bounding rectangle of the element's visible border-box portion, in top-level viewport CSS pixels, after ancestor and viewport clipping. Partial visibility is sufficient. This is not an occlusion or hit test.",
+      "type": "number",
+      "format": "double"
+    },
+    "y": {
+      "type": "number",
+      "format": "double"
+    }
+  },
+  "definitions": {
+    "JavaScriptDialogHandledAction": {
+      "description": "How the extension resolved the dialog so CDP could continue.",
+      "type": "string",
+      "enum": [
+        "accepted",
+        "dismissed"
+      ]
+    },
+    "JavaScriptDialogInfo": {
+      "description": "One observed + handled JavaScript dialog during a tool call.",
+      "type": "object",
+      "required": [
+        "handled",
+        "message",
+        "sequence",
+        "tab_id",
+        "type"
+      ],
+      "properties": {
+        "default_prompt": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "handled": {
+          "$ref": "#/definitions/JavaScriptDialogHandledAction"
+        },
+        "has_browser_handler": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "message": {
+          "type": "string"
+        },
+        "sequence": {
+          "description": "Monotonic per-tab sequence for ordering within a session.",
+          "type": "integer",
+          "format": "uint64",
+          "minimum": 0.0
+        },
+        "tab_id": {
+          "type": "integer",
+          "format": "int64"
+        },
+        "type": {
+          "$ref": "#/definitions/JavaScriptDialogType"
+        },
+        "url": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "JavaScriptDialogType": {
+      "description": "Native JS dialog kind reported by CDP.",
+      "type": "string",
+      "enum": [
+        "alert",
+        "confirm",
+        "prompt",
+        "beforeunload"
+      ]
+    }
+  }
+}

crates/bsk-protocol/src/bin/dump-schema.rs

@@ -79,6 +79,12 @@ fn main() {
     dump!(ClickResult, "tool_click_result");
     dump!(HoverParams, "tool_hover_params");
     dump!(HoverResult, "tool_hover_result");
+    dump!(ScrollToParams, "tool_scroll_to_params");
+    dump!(ScrollToResult, "tool_scroll_to_result");
+    dump!(FocusParams, "tool_focus_params");
+    dump!(FocusResult, "tool_focus_result");
+    dump!(BlurParams, "tool_blur_params");
+    dump!(BlurResult, "tool_blur_result");
     dump!(FillParams, "tool_fill_params");
     dump!(FillResult, "tool_fill_result");
     dump!(PressParams, "tool_press_params");

crates/bsk-protocol/src/method.rs

@@ -72,6 +72,12 @@ pub enum Method {
     ToolClick,
     #[serde(rename = "tool.hover")]
     ToolHover,
+    #[serde(rename = "tool.scroll_to")]
+    ToolScrollTo,
+    #[serde(rename = "tool.focus")]
+    ToolFocus,
+    #[serde(rename = "tool.blur")]
+    ToolBlur,
     #[serde(rename = "tool.fill")]
     ToolFill,
     #[serde(rename = "tool.press")]
@@ -168,6 +174,9 @@ impl Method {
             | Method::ToolNavigateForward
             | Method::ToolReload
             | Method::ToolClick
+            | Method::ToolScrollTo
+            | Method::ToolFocus
+            | Method::ToolBlur
             | Method::ToolFill
             | Method::ToolPress
             | Method::ToolSelect
@@ -305,6 +314,9 @@ mod tests {
         assert!(Method::ToolNavigateForward.is_mutating());
         assert!(Method::ToolReload.is_mutating());
         assert!(Method::ToolClick.is_mutating());
+        assert!(Method::ToolScrollTo.is_mutating());
+        assert!(Method::ToolFocus.is_mutating());
+        assert!(Method::ToolBlur.is_mutating());
         assert!(Method::ToolFill.is_mutating());
         assert!(Method::ToolPress.is_mutating());
         assert!(Method::ToolSelect.is_mutating());
@@ -349,6 +361,9 @@ mod tests {
         assert_eq!(Method::ToolHover.effect(), MethodEffect::TransientInput);
         assert_eq!(Method::ToolObserve.effect(), MethodEffect::TransientInput);
         assert_eq!(Method::ToolClick.effect(), MethodEffect::BrowserMutation);
+        assert_eq!(Method::ToolScrollTo.effect(), MethodEffect::BrowserMutation);
+        assert_eq!(Method::ToolFocus.effect(), MethodEffect::BrowserMutation);
+        assert_eq!(Method::ToolBlur.effect(), MethodEffect::BrowserMutation);
         assert_eq!(Method::Cancel.effect(), MethodEffect::ControlPlane);
     }
 
@@ -358,6 +373,9 @@ mod tests {
         assert!(Method::ToolHover.requires_interrupt_gate());
         assert!(Method::ToolObserve.requires_interrupt_gate());
         assert!(Method::ToolClick.requires_interrupt_gate());
+        assert!(Method::ToolScrollTo.requires_interrupt_gate());
+        assert!(Method::ToolFocus.requires_interrupt_gate());
+        assert!(Method::ToolBlur.requires_interrupt_gate());
         assert!(!Method::Cancel.requires_interrupt_gate());
     }
 }

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

@@ -1,5 +1,5 @@
-//! DOM interaction tools (`tool.click`, `tool.fill`, `tool.press`,
-//! `tool.select`).
+//! DOM interaction tools (`tool.click`, `tool.hover`, `tool.focus`,
+//! `tool.blur`, `tool.fill`, `tool.press`, `tool.select`).
 //!
 //! Element-targeted tools accept either a snapshot `ref` (`@e<N>` form,
 //! normalised against the session's RefStore) **or** a CSS selector
@@ -131,6 +131,82 @@ pub struct HoverResult {
     pub dialogs: Vec<JavaScriptDialogInfo>,
 }
 
+// ---------------------------------------------------------------------------
+// focus / blur
+// ---------------------------------------------------------------------------
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct FocusParams {
+    pub session_id: String,
+    /// Optional `@e<N>` ref allocated by the last observation.
+    /// Mutually exclusive with `selector`.
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    /// Target tab. Defaults to the Agent Window's active tab.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(range(min = 1))]
+    pub timeout_ms: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct FocusResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    /// Whether the target holds DOM focus in its document or shadow root after the call.
+    pub focused: bool,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub dialogs: Vec<JavaScriptDialogInfo>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct BlurParams {
+    pub session_id: String,
+    /// Optional `@e<N>` ref allocated by the last observation.
+    /// Mutually exclusive with `selector`.
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    /// Target tab. Defaults to the Agent Window's active tab.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(range(min = 1))]
+    pub timeout_ms: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct BlurResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    /// Whether the target held focus before the call.
+    pub was_focused: bool,
+    /// Always false for a successful blur; included for machine verification.
+    pub focused: bool,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub dialogs: Vec<JavaScriptDialogInfo>,
+}
+
 // ---------------------------------------------------------------------------
 // fill
 // ---------------------------------------------------------------------------
@@ -325,6 +401,37 @@ mod tests {
         assert_eq!(round, p);
     }
 
+    #[test]
+    fn focus_params_serialise_ref_field_name() {
+        let p = FocusParams {
+            session_id: "abcd".into(),
+            ref_: Some("@e4".into()),
+            selector: None,
+            tab_id: Some(42),
+            timeout_ms: Some(5_000),
+        };
+        let v = serde_json::to_value(&p).unwrap();
+        assert_eq!(v.get("ref").and_then(|v| v.as_str()), Some("@e4"));
+        assert!(v.get("ref_").is_none());
+        let round: FocusParams = serde_json::from_value(v).unwrap();
+        assert_eq!(round, p);
+    }
+
+    #[test]
+    fn blur_result_round_trips_focus_state() {
+        let result = BlurResult {
+            tab_id: 42,
+            used_ref: Some("e4".into()),
+            used_selector: None,
+            was_focused: true,
+            focused: false,
+            dialogs: vec![],
+        };
+        let value = serde_json::to_value(&result).unwrap();
+        let round: BlurResult = serde_json::from_value(value).unwrap();
+        assert_eq!(round, result);
+    }
+
     #[test]
     fn modifiers_render_as_lowercase_strings() {
         let v = serde_json::to_value(KeyModifier::Ctrl).unwrap();

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

@@ -14,6 +14,7 @@ mod record_common;
 mod record_v2;
 mod record_v3;
 pub mod script;
+pub mod scroll;
 pub mod session;
 pub mod tabs;
 pub mod waits;
@@ -30,6 +31,7 @@ pub use network::*;
 pub use observation::*;
 pub use record::*;
 pub use script::*;
+pub use scroll::*;
 pub use session::*;
 pub use tabs::*;
 pub use waits::*;

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

@@ -0,0 +1,67 @@
+//! Element scrolling primitive (`tool.scroll_to`).
+
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+
+use super::JavaScriptDialogInfo;
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct ScrollToParams {
+    pub session_id: String,
+    /// Optional `@e<N>` ref allocated by the last observation.
+    /// Mutually exclusive with `selector`.
+    #[serde(
+        rename = "ref",
+        alias = "ref_",
+        default,
+        skip_serializing_if = "Option::is_none"
+    )]
+    pub ref_: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub selector: Option<String>,
+    /// Target tab. Defaults to the Agent Window's active tab.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub tab_id: Option<i64>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(range(min = 1))]
+    pub timeout_ms: Option<u32>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct ScrollToResult {
+    pub tab_id: i64,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_ref: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub used_selector: Option<String>,
+    /// Bounding rectangle of the element's visible border-box portion, in
+    /// top-level viewport CSS pixels, after ancestor and viewport clipping.
+    /// Partial visibility is sufficient. This is not an occlusion or hit test.
+    pub x: f64,
+    pub y: f64,
+    pub width: f64,
+    pub height: f64,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub dialogs: Vec<JavaScriptDialogInfo>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn params_serialise_ref_field_name() {
+        let params = ScrollToParams {
+            session_id: "abcd".into(),
+            ref_: Some("@e3".into()),
+            selector: None,
+            tab_id: Some(42),
+            timeout_ms: Some(5_000),
+        };
+        let value = serde_json::to_value(&params).unwrap();
+        assert_eq!(value.get("ref").and_then(|v| v.as_str()), Some("@e3"));
+        assert!(value.get("ref_").is_none());
+        let round: ScrollToParams = serde_json::from_value(value).unwrap();
+        assert_eq!(round, params);
+    }
+}

docs/architecture.md

@@ -84,6 +84,11 @@ Shared Rust types + JSON Schema generation. TypeScript mirrors frame shapes in
 4. Extension dispatcher validates sandbox rules, invokes CDP via `BrowserDriver`.
 5. Response travels CLI ← daemon ← extension; CLI prints result and exits.
 
+The [scroll-to primitive reference](scroll-to.md) documents `tool.scroll_to`,
+including its CLI/plugin mappings, visible-bounds contract and cancellation
+behavior. It follows the same routing path and is classified as a browser
+mutation for session queueing and user-interruption gating.
+
 ## Session and sandbox model
 
 - **Session** = opaque ID (4 lowercase letters in v0.1) + dedicated **Agent Window**