perf(observation): validate document identity against snapshot roots

fix(observation): validate document consistency with bounded identity checks
perf(observation): collect frame AX trees with bounded concurrency
2026-09-10 13:01:23 +08:00 · 2026-09-09 13:20:23 +08:00 · 2026-09-09 13:20:23 +08:00 · 2026-09-09 13:20:23 +08:00 · 2026-09-09 13:20:23 +08:00 · 2026-09-09 13:20:23 +08:00
211 changed files with 18181 additions and 9059 deletions
@@ -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
@@ -7,6 +7,10 @@ dist/
 .output/
 .wxt/
 .web-extension-id
+.pnpm-store/
+
+# Git worktrees
+.worktrees/

 # Logs
 *.log
@@ -0,0 +1,109 @@
+# Changelog
+
+All notable changes to BrowserSkill will be documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+Starting from 0.2.0, CLI / Extension / DSH Plugin share the same version number.
+
+## [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
+- File transfer: upload and download support across CLI, Extension, and DSH Plugin
+- File transfer: drag-and-drop upload (`drop-to-upload`)
+- VOM semantic graph, name enrichment, and hover perception modules
+- VOM hover probing (opt-in via `observe` parameter)
+- DSH Plugin: browser tool parity with CLI commands
+- Edge Add-ons automated publishing in CI
+- Protocol upgrade reminder when CLI / Extension protocol versions differ
+- Browser evaluation harness (`evals/browser/`)
+- Unified release script (`scripts/release.mjs`)
+
+### Changed
+- **Version scheme**: all three components now share the same semver
+- VOM rendering algorithm optimizations
+- Leaner SKILL.md agent instructions
+- DSH Plugin: simplified browser commands
+- Borrow confirmation UX — proactive focus and longer timeout
+- PiP window now has a close button
+
+### Fixed
+- Screenshot media type detection (was hard-coded to `image/png`)
+- DSH Plugin session lifecycle stability
+- DSH Plugin Cordis package ID mismatch
+- Observation thumbnail media type sniffing
+- Upload/download race conditions and layout bypass issues
+- VOM repeated name and safety policy issues
+
+---
+
+*Previous releases used independent version numbers per component.*
+
+## CLI 0.1.11 / Extension 0.1.7 / DSH Plugin 0.1.2 — 2026-08-26 ~ 2026-08-29
+
+### Added
+- DSH Plugin sidebar integration, session lifecycle, and archive cleanup
+- Recorder iframe and OOPIF support
+
+### Changed
+- VOM functional refactor
+
+### Fixed
+- Recorder safety policy and bug fixes
+
+## CLI 0.1.10 / Extension 0.1.6 — 2026-08-08
+
+### Added
+- VOM observation recording and settled-state detection
+- Record overlay timer
+
+### Fixed
+- Browser keepalive disconnect handling
+
+## CLI 0.1.9 / Extension 0.1.5 — 2026-07-29
+
+### Added
+- CLI auto-update mechanism
+- Trace v3 protocol and recorder
+
+### Fixed
+- MV3 keepalive disconnect
+
+## CLI 0.1.8 / Extension 0.1.4 — 2026-07-22
+
+### Added
+- More browser interaction actions
+
+### Fixed
+- Windows named-pipe hash-only path issue
+
+## CLI 0.1.7 / Extension 0.1.3 — 2026-07-07
+
+Initial public release pair.
+
+## CLI 0.1.6 — 2026-06-30
+
+### Fixed
+- Minor CLI fixes
+
+## CLI 0.1.5 / Extension 0.1.2 — 2026-06-22
+
+First tagged releases.
@@ -134,9 +134,10 @@ dependencies = [

 [[package]]
 name = "bsk"
-version = "0.1.11"
+version = "0.2.1"
 dependencies = [
 "anyhow",
+ "base64",
 "bsk-protocol",
 "clap",
 "console",
@@ -168,7 +169,7 @@ dependencies = [

 [[package]]
 name = "bsk-protocol"
-version = "0.1.11"
+version = "0.2.1"
 dependencies = [
 "schemars",
 "semver",
@@ -7,7 +7,7 @@ members = [
 default-members = ["crates/bsk-cli"]

 [workspace.package]
-version = "0.1.11"
+version = "0.2.1"
 edition = "2024"
 rust-version = "1.85"
 license = "MIT"
@@ -36,13 +36,14 @@ flate2 = "1.1.9"
 tar = "0.4.46"
 zip = { version = "7.2.0", default-features = false, features = ["deflate"] }
 sha2 = "0.11.0"
+base64 = "0.22"
 tempfile = "3"
 nix = { version = "0.29", features = ["signal", "process"] }
 rand = "0.8"
 uuid = { version = "1", features = ["v4", "serde"] }

 # Workspace crates (version required for `cargo publish` of dependents)
-bsk-protocol = { version = "0.1.9", path = "crates/bsk-protocol" }
+bsk-protocol = { version = "0.2.1", path = "crates/bsk-protocol" }

 [profile.release]
 strip = "symbols"
@@ -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

@@ -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)。

 ## 工作原理

@@ -1,6 +1,6 @@
 # BrowserSkill — Privacy Policy

-**Last updated:** May 25, 2026
+**Last updated:** August 20, 2026

 This Privacy Policy describes how the **BrowserSkill** browser extension (the "Extension") handles information when you install and use it. BrowserSkill is published as part of the open-source [BrowserSkill](https://github.com/Tencent/BrowserSkill) project. The source code is publicly auditable.

@@ -14,7 +14,7 @@ BrowserSkill is a local automation bridge that lets AI coding agents (such as Cu

 ## 2. Single Purpose

-The Extension's single purpose is to expose browser automation primitives (navigation, DOM observation, screenshots, clicks, form filling, tab management) to a locally running BrowserSkill daemon over a WebSocket connection on `127.0.0.1`, so that an AI agent invoked by the user can interact with web pages on the user's behalf.
+The Extension's single purpose is to expose browser automation primitives (navigation, DOM observation, screenshots, clicks, form filling, task-scoped file transfer, and tab management) to a locally running BrowserSkill daemon over a WebSocket connection on `127.0.0.1`, so that an AI agent invoked by the user can interact with web pages on the user's behalf.

 ## 3. Data the Extension Accesses

@@ -26,6 +26,7 @@ Depending on the commands the user (via their AI agent) sends to the local daemo
 | **User input simulated by the agent** | Mouse clicks, keystrokes, and form values that the AI agent dispatches through the Chrome DevTools Protocol (CDP). | Required to perform automation actions the user has asked the agent to do. |
 | **Tab and window metadata** | Tab IDs, URLs, titles, window IDs of the Agent Window and any tabs the user explicitly authorizes. | Required to target automation commands at the correct tab/window. |
 | **Local extension storage** | A randomly generated 8-character instance ID and an optional user-supplied label. | Used so the local daemon can recognize this browser instance across reconnects. No personal data is stored. |
+| **File transfers requested by the agent** | Local files explicitly supplied to `bsk upload`, and the file created by a single `bsk download` action. | Required to attach a task file to a web page or return a browser-generated download to the invoking local agent. |
 | **OS notifications** | Permission to display a system notification when the agent requests to "borrow" one of the user's existing tabs. | Required to obtain explicit, per-tab user consent before the agent touches any pre-existing tab. |

 ## 4. Data the Extension Does **Not** Collect
@@ -34,7 +35,7 @@ BrowserSkill does **not**:

 - Send any data to remote servers, the Extension's authors, or any third party.
 - Call any LLM, AI, or cloud API. The Extension contains no API keys, model identifiers, or remote endpoints.
- Read or transmit cookies, browsing history, bookmarks, downloads, saved passwords, or autofill data.
+- Read or transmit cookies, browsing history, bookmarks, saved passwords, or autofill data. It observes only the download initiated by an active `bsk download` call, not download history generally.
 - Use webcam, microphone, geolocation, or any device sensor.
 - Include analytics, telemetry, crash reporting, advertising SDKs, or fingerprinting code.
 - Track users across websites or across sessions.
@@ -50,6 +51,7 @@ The Extension requests the following Chrome permissions. Each is used solely for
 - **`alarms`** — Periodically wake the service worker to keep the local WebSocket connection alive.
 - **`idle`** — Detect when the device returns from idle/locked so the Extension can promptly re-establish the local WebSocket connection after the machine wakes. No idle data is stored or transmitted.
 - **`notifications`** — Show a system notification to obtain user approval before the agent borrows a user-owned tab.
+- **`downloads`** — Correlate and route the one browser download initiated by an active `bsk download` command. If that claimed transaction fails, BrowserSkill cancels an in-progress file or removes its completed temporary browser file. It is not used to enumerate download history or alter unclaimed downloads.
 - **`storage`** — Persist a random instance ID and optional label in `chrome.storage.local`.
 - **Host permission `<all_urls>`** — Inject a small status overlay (showing "Agent Active") on pages controlled by the agent, and enable automation across whatever sites the user directs the agent to. The Extension does **not** read or transmit page content from sites the agent is not actively driving.

@@ -61,6 +63,7 @@ All Extension activity stays on the user's local device. The only network traffi

 - The instance ID and optional label persist in `chrome.storage.local` until the user uninstalls the Extension or clears extension storage.
 - Page content, screenshots, DOM snapshots, and other observed data are returned to the local daemon in response to commands and are **not retained by the Extension**. They live only as long as the agent's tool call.
+- Upload and download bytes are staged by the local daemon in a private, session-scoped directory. Download staging is removed after it is copied to the requested destination. Upload staging is retained until the session ends so a later form submission can still read the attached file. Remaining staging is removed when the session ends or disconnects, or when the daemon next starts after a crash.

 ## 8. User Control

@@ -0,0 +1,81 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>BrowserSkill file-transfer fixture</title>
+    <style>
+      body { font: 16px system-ui; max-width: 760px; margin: 48px auto; }
+      .actions { display: flex; gap: 12px; align-items: center; margin: 24px 0; }
+      button, a { padding: 10px 16px; border: 1px solid #777; border-radius: 8px; }
+      a[aria-disabled="true"] { opacity: .45; pointer-events: none; }
+      #drop { padding: 36px; border: 3px dashed #777; border-radius: 12px; text-align: center; }
+      #drop.dragging { border-color: #2563eb; background: #eff6ff; }
+      img { display: block; max-width: 480px; max-height: 360px; margin-top: 20px; }
+    </style>
+  </head>
+  <body>
+    <h1>Upload then download the same image</h1>
+    <p id="status">No image selected</p>
+    <div class="actions">
+      <button id="upload" type="button">Upload through file input</button>
+      <input id="file" type="file" accept="image/png" hidden />
+      <a id="download" aria-disabled="true">Download uploaded image</a>
+    </div>
+    <div id="drop" role="button" tabindex="0">Drop an image here</div>
+    <img id="preview" alt="Uploaded image preview" hidden />
+    <script>
+      const input = document.querySelector('#file');
+      const upload = document.querySelector('#upload');
+      const drop = document.querySelector('#drop');
+      const download = document.querySelector('#download');
+      const preview = document.querySelector('#preview');
+      const status = document.querySelector('#status');
+      let objectUrl;
+
+      window.__bskTransferFixture = { events: [], result: null };
+
+      function accept(file, mechanism) {
+        if (!file) return;
+        if (objectUrl) URL.revokeObjectURL(objectUrl);
+        objectUrl = URL.createObjectURL(file);
+        preview.src = objectUrl;
+        preview.hidden = false;
+        download.href = objectUrl;
+        download.download = file.name;
+        download.removeAttribute('aria-disabled');
+        status.textContent = `Ready via ${mechanism}: ${file.name} (${file.size} bytes)`;
+        window.__bskTransferFixture.result = {
+          mechanism,
+          name: file.name,
+          size: file.size,
+          type: file.type,
+          hasPathProperty: 'path' in file,
+        };
+      }
+
+      upload.addEventListener('click', () => input.click());
+      input.addEventListener('change', () => accept(input.files[0], 'input'));
+
+      for (const type of ['dragenter', 'dragover']) {
+        drop.addEventListener(type, event => {
+          const types = [...event.dataTransfer.types];
+          window.__bskTransferFixture.events.push({ type, types });
+          if (!types.includes('Files')) return;
+          event.preventDefault();
+          drop.classList.add('dragging');
+        });
+      }
+      drop.addEventListener('dragleave', () => drop.classList.remove('dragging'));
+      drop.addEventListener('drop', event => {
+        window.__bskTransferFixture.events.push({
+          type: 'drop',
+          types: [...event.dataTransfer.types],
+          fileCount: event.dataTransfer.files.length,
+        });
+        event.preventDefault();
+        drop.classList.remove('dragging');
+        accept(event.dataTransfer.files[0], 'drop');
+      });
+    </script>
+  </body>
+</html>
@@ -1,6 +1,6 @@
 {
  "name": "@browser-skill/extension",
-  "version": "0.1.7",
+  "version": "0.2.1",
  "private": true,
  "type": "module",
  "scripts": {
@@ -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);
@@ -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)),
+    );
  }
 }

@@ -23,7 +23,7 @@ describe("BorrowConfirmationOverlay", () => {
            id: "req-1",
            isActiveTab: true,
            tabTitle: "Example",
-            timeoutMs: 5000,
+            timeoutMs: 60_000,
            onAllow,
            onDeny,
          },
@@ -32,7 +32,7 @@ describe("BorrowConfirmationOverlay", () => {
    );

    expect(screen.getByText("允许借用标签页？")).toBeTruthy();
-    for (let i = 0; i < 5; i++) {
+    for (let i = 0; i < 60; i++) {
      await act(async () => {
        await vi.advanceTimersByTimeAsync(1000);
      });
@@ -66,7 +66,7 @@ describe("BorrowConfirmationOverlay", () => {
            id: "req-fallback",
            isActiveTab: true,
            tabTitle: "Example",
-            timeoutMs: 5000,
+            timeoutMs: 60_000,
            onAllow,
            onDeny,
          },
@@ -74,7 +74,7 @@ describe("BorrowConfirmationOverlay", () => {
      />,
    );

-    for (let i = 0; i < 5; i++) {
+    for (let i = 0; i < 60; i++) {
      await act(async () => {
        await vi.advanceTimersByTimeAsync(1000);
      });
@@ -45,10 +45,32 @@ function portHarness() {

 describe("RecordFrameAgent", () => {
  afterEach(() => {
+    vi.unstubAllGlobals();
    document.documentElement.removeAttribute(RECORD_DOCUMENT_ATTRIBUTE);
    document.body.replaceChildren();
  });

+  it("starts when crypto.randomUUID is unavailable", async () => {
+    const harness = portHarness();
+    const getRandomValues = vi.fn((bytes: Uint8Array) => {
+      bytes.fill(0x11);
+      return bytes;
+    });
+    vi.stubGlobal("crypto", { getRandomValues });
+    vi.stubGlobal("chrome", {
+      runtime: {
+        connect: vi.fn(() => harness.port),
+        sendMessage: vi.fn(),
+      },
+    });
+    const agent = new RecordFrameAgent();
+
+    await expect(
+      agent.start({ type: RECORD_FRAME_START, requestId: "rec-http", startedAtMs: 10 }),
+    ).resolves.toEqual({ ok: true });
+    expect(getRandomValues).toHaveBeenCalled();
+  });
+
  it("keeps a failed stop retryable and flushes the final dirty fill", async () => {
    const harness = portHarness();
    const sendMessage = vi
@@ -1,3 +1,4 @@
+import { createRandomUuid } from "@/lib/random-uuid";
 import {
  isAcceptedRecordStepAck,
  RECORD_STEP,
@@ -18,7 +19,7 @@ export class RecordStepDelivery {
  constructor(
    requestId: string,
    send: SendRecordStepMessage = (message) => chrome.runtime.sendMessage(message),
-    producerId: string = crypto.randomUUID(),
+    producerId: string = createRandomUuid(),
  ) {
    this.#requestId = requestId;
    this.#producerId = producerId;
@@ -1,3 +1,4 @@
+import { createRandomUuid } from "@/lib/random-uuid";
 import {
  markRecordingDocument,
  type RecordingDocumentMarker,
@@ -67,7 +68,7 @@ export class RecordFrameAgent {
  async #start(
    message: RecordFrameStartMessage,
  ): Promise<{ ok: true } | { ok: false; error: string }> {
-    const producerId = crypto.randomUUID();
+    const producerId = createRandomUuid();
    const root = await waitForDocumentElement();
    if (this.#disposed) return { ok: false, error: "recording document is disposed" };
    const marker = markRecordingDocument(producerId, root);
@@ -25,7 +25,7 @@ import { recordFrameCoordinator } from "@/lib/recording/frame-coordinator";
 import { attachSessionsLiveFlag } from "@/lib/sessions-live-flag";
 import { createDisconnectCleanup } from "@/session-manager/disconnect-cleanup";
 import { attachSessionEventHandler } from "@/session-manager/event-handler";
-import { SessionManager } from "@/session-manager/manager";
+import { isAgentControlledTab, SessionManager } from "@/session-manager/manager";
 import {
  attachBorrowNotificationButtonHandler,
  attachBorrowNotificationClickHandler,
@@ -41,6 +41,8 @@ import {
  attachRecordStepListener,
  type RecordRuntimeDeps,
 } from "@/tools/record";
+import { chromeTabsApi } from "@/tools/shared";
+import { chromeTabMutationApi } from "@/tools/tabs";
 import { detectBrowserMeta } from "@/transport/handshake";
 import type { Transport } from "@/transport/transport";
 import { WSTransport } from "@/transport/ws-transport";
@@ -49,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>();
@@ -80,6 +87,24 @@ export default defineBackground(() => {
    };
  }

+  /**
+   * Authoritative overlay state for a specific tab. Agent Window tabs are
+   * free by default; only tabs explicitly claimed through session startup,
+   * `tab_create`, or `tab_borrow` receive the control overlay.
+   */
+  function overlayStateForTab(tabId?: number, windowId?: number): OverlayAgentStateMessage {
+    if (typeof tabId === "number" && typeof windowId === "number") {
+      const ctx = sessions.findByWindowId(windowId);
+      if (ctx && isAgentControlledTab(ctx, tabId)) return overlayStateForWindow(windowId);
+    }
+    return {
+      type: OVERLAY_AGENT_STATE,
+      sessionId: null,
+      mode: "hidden",
+      generation: overlayGeneration,
+    };
+  }
+
  async function pushOverlayStateToTab(
    tabId: number,
    state: OverlayAgentStateMessage,
@@ -91,13 +116,18 @@ export default defineBackground(() => {
    }
  }

+  async function pushOverlayStateForTab(tabId: number, windowId?: number): Promise<void> {
+    const state = overlayStateForTab(tabId, windowId);
+    await pushOverlayStateToTab(tabId, state);
+  }
+
  async function pushOverlayStateForWindow(windowId: number): Promise<void> {
-    const state = overlayStateForWindow(windowId);
    const tabs = await chrome.tabs.query({ windowId });
    await Promise.all(
-      tabs.map((tab) =>
-        typeof tab.id === "number" ? pushOverlayStateToTab(tab.id, state) : Promise.resolve(),
-      ),
+      tabs.map((tab) => {
+        if (typeof tab.id !== "number") return Promise.resolve();
+        return pushOverlayStateForTab(tab.id, windowId);
+      }),
    );
  }

@@ -136,13 +166,30 @@ export default defineBackground(() => {
    if (typeof tab.windowId !== "number") return;
    pushOverlayStateForAgentWindow(tab.windowId);
  });
+  // Newly observed tabs are free unless the agent's own creation path has
+  // already claimed their concrete id. This listener only renders that
+  // state; it never infers or mutates ownership from event ordering.
+  chrome.tabs.onCreated.addListener((tab) => {
+    if (typeof tab.windowId !== "number" || typeof tab.id !== "number") return;
+    if (!sessions.findByWindowId(tab.windowId)) return;
+    void pushOverlayStateForTab(tab.id, tab.windowId);
+  });
+  chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
+    sessions.forgetClosedTab(tabId, { isWindowClosing: removeInfo.isWindowClosing });
+  });
  // Re-sync the storage.session flag on SW startup so a previous SW's
  // stale `true` does not keep waking us on every page load until the
  // first mutation (review M4/M5 round 3 m-R3-1).
  void sessionsLive.refresh();
  const cleanupAfterDisconnect = createDisconnectCleanup({
    manager: sessions,
-    sessionStopDeps: { cdp },
+    // Same contract as the dispatcher's `tool.session_stop`: without these
+    // deps the agent-tab cleanup and the window-release path are dead code.
+    sessionStopDeps: {
+      cdp,
+      tabManagement: { tabs: chromeTabMutationApi },
+      tabsQuery: chromeTabsApi,
+    },
    onSessionsChanged: () => {
      void sessionsLive.syncFromManager();
    },
@@ -176,6 +223,9 @@ export default defineBackground(() => {
    recording: recordDeps,
    onSessionsChanged: onOverlaySessionStateChanged,
    onBrowserControlResumed,
+    onAgentTabClaimed: (tabId, windowId) => {
+      void pushOverlayStateForTab(tabId, windowId);
+    },
    approveBorrow: (ctx) =>
      requestBorrowConfirmation(ctx.tabId, {
        ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
@@ -309,7 +359,11 @@ export default defineBackground(() => {
    }

    if (msg.kind === OVERLAY_MSG_READY) {
-      sendResponse(overlayStateForWindow(sender.tab?.windowId));
+      // Resolve from explicit tab ownership before sending so free tabs never
+      // flash the control mask.
+      if (typeof sender.tab?.id === "number") {
+        void pushOverlayStateForTab(sender.tab.id, sender.tab.windowId);
+      }
      return false;
    }

@@ -122,8 +122,8 @@ describe("App", () => {

    expect(screen.queryByText(/^扩展 v/)).toBeNull();
    expect(screen.queryByText(/^daemon v/)).toBeNull();
-    expect(screen.getByTitle("扩展版本").textContent).toBe(EXTENSION_VERSION);
-    expect(screen.getByTitle("bsk 版本").textContent).toBe(mockDaemonVersion);
+    expect(screen.getByTitle("扩展版本").textContent).toBe(`Ext ${EXTENSION_VERSION}`);
+    expect(screen.getByTitle("bsk 版本").textContent).toBe(`CLI ${mockDaemonVersion}`);
    expect(screen.getByText("03c3e47f")).toBeTruthy();

    const copyButton = screen.getByRole("button", { name: "复制实例 ID" });
@@ -267,9 +267,9 @@ export function App() {
            data-slot="popup-meta"
          >
            <div className="flex shrink-0 items-center gap-1">
-              <span title={t("popup.extensionVersionHint")}>{extensionVersion}</span>
+              <span title={t("popup.daemonVersionHint")}>CLI {daemonVersion}</span>
              <span aria-hidden>/</span>
-              <span title={t("popup.daemonVersionHint")}>{daemonVersion}</span>
+              <span title={t("popup.extensionVersionHint")}>Ext {extensionVersion}</span>
            </div>
            <div className="flex min-w-0 items-center justify-end gap-1">
              <span className="shrink-0">{t("popup.instanceTitle")}</span>
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 import {
  CAPTURE_SUPPRESS,
  type CaptureSuppressMessage,
-  withOverlaysHiddenForCapture,
+  withExtensionOverlayHidden,
 } from "../capture-suppress-bridge";

 function recordingSendToTab(events: string[]) {
@@ -12,12 +12,12 @@ function recordingSendToTab(events: string[]) {
  });
 }

-describe("withOverlaysHiddenForCapture", () => {
+describe("withExtensionOverlayHidden", () => {
  it("sends begin → fn → end and returns fn's result", async () => {
    const events: string[] = [];
    const sendToTab = recordingSendToTab(events);

-    const result = await withOverlaysHiddenForCapture(
+    const result = await withExtensionOverlayHidden(
      7,
      async () => {
        events.push("capture");
@@ -37,7 +37,7 @@ describe("withOverlaysHiddenForCapture", () => {
    const sendToTab = recordingSendToTab(events);

    await expect(
-      withOverlaysHiddenForCapture(
+      withExtensionOverlayHidden(
        7,
        async () => {
          events.push("capture");
@@ -55,7 +55,7 @@ describe("withOverlaysHiddenForCapture", () => {
    });
    const fn = vi.fn(async () => "shot");

-    const result = await withOverlaysHiddenForCapture(7, fn, sendToTab);
+    const result = await withExtensionOverlayHidden(7, fn, sendToTab);

    expect(result).toBe("shot");
    expect(fn).toHaveBeenCalledTimes(1);
@@ -69,7 +69,7 @@ describe("withOverlaysHiddenForCapture", () => {
      return { type: CAPTURE_SUPPRESS, ok: true };
    });

-    const result = await withOverlaysHiddenForCapture(7, async () => "shot", sendToTab);
+    const result = await withExtensionOverlayHidden(7, async () => "shot", sendToTab);

    expect(result).toBe("shot");
    expect(sendToTab).toHaveBeenCalledTimes(2);
@@ -0,0 +1,30 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createRandomUuid } from "../random-uuid";
+
+describe("createRandomUuid", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("uses crypto.randomUUID when it is available", () => {
+    const randomUUID = vi.fn(() => "00000000-0000-4000-8000-000000000000");
+    vi.stubGlobal("crypto", { randomUUID, getRandomValues: vi.fn() });
+
+    expect(createRandomUuid()).toBe("00000000-0000-4000-8000-000000000000");
+    expect(randomUUID).toHaveBeenCalledOnce();
+  });
+
+  it("falls back to getRandomValues and sets UUID v4 bits", () => {
+    const bytes = new Uint8Array(16).fill(0xff);
+    const getRandomValues = vi.fn((target: Uint8Array) => {
+      target.set(bytes);
+      return target;
+    });
+    vi.stubGlobal("crypto", { getRandomValues });
+
+    const uuid = createRandomUuid();
+
+    expect(uuid).toBe("ffffffff-ffff-4fff-bfff-ffffffffffff");
+    expect(getRandomValues).toHaveBeenCalledOnce();
+  });
+});
@@ -1,9 +1,9 @@
 /**
- * Wire protocol and background-side helper for hiding the extension's
- * in-page overlay while a screenshot is captured, so captured frames only
- * contain the page itself.
+ * Wire protocol and background-side helper for temporarily excluding the
+ * extension's in-page overlay. Screenshots use it to avoid captured chrome;
+ * coordinate-driven native input uses it so Chrome hit-tests the page.
 *
- * The background wraps every capture in `withOverlaysHiddenForCapture`,
+ * The background wraps each bounded operation in `withExtensionOverlayHidden`,
 * which sends `begin` (the content script hides the overlay host and only
 * acks once the compositor has produced an overlay-free frame) and always
 * follows up with `end`, even when the capture throws. Tabs without the
@@ -46,7 +46,7 @@ const defaultSendToTab: CaptureSuppressSendToTab = (tabId, message) =>
 * (or any other `begin` failure) simply skips suppression — there is no
 * overlay to hide in that tab.
 */
-export async function withOverlaysHiddenForCapture<T>(
+export async function withExtensionOverlayHidden<T>(
  tabId: number,
  fn: () => Promise<T>,
  sendToTab: CaptureSuppressSendToTab = defaultSendToTab,
@@ -3,8 +3,10 @@
 * between the content-script control overlay and the background SW.
 *
 * Content script → background:
- *  - `{ kind: "overlay.ready" }` → background replies with the authoritative
- *      overlay state for the sender's window.
+ *  - `{ kind: "overlay.ready" }` → background decides the per-tab state first
+ *      (see overlayStateForTab) and pushes the authoritative overlay state for
+ *      that tab. It also proactively pushes on tab create and control-mode
+ *      change, so a tab usually receives state before it ever sends ready.
 *  - `{ kind: "overlay.interrupt", sessionId }` → background asks the
 *      daemon (via a `session.user_interrupt` WS event) to cancel
 *      every inflight + queued tool call for that session with
@@ -0,0 +1,26 @@
+/**
+ * Generate a UUID v4 in browser contexts where randomUUID() is unavailable.
+ *
+ * Crypto.randomUUID() is restricted to secure contexts, while
+ * crypto.getRandomValues() is available to content scripts on ordinary HTTP
+ * origins. BrowserSkill records many intranet pages served over HTTP, so the
+ * fallback is required for recording to work on those pages.
+ */
+export function createRandomUuid(): string {
+  const cryptoApi = globalThis.crypto;
+  if (typeof cryptoApi.randomUUID === "function") return cryptoApi.randomUUID();
+
+  const bytes = new Uint8Array(16);
+  cryptoApi.getRandomValues(bytes);
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20),
+  ].join("-");
+}
@@ -1,3 +1,4 @@
+import { createRandomUuid } from "../random-uuid";
 import {
  isRecordFrameQueryMessage,
  RECORD_FRAME_PORT,
@@ -188,7 +189,7 @@ export class RecordFrameCoordinator {
    const recording = this.#recordings.get(requestId);
    if (!recording) return true;
    recording.finishing = true;
-    const commandId = crypto.randomUUID();
+    const commandId = createRandomUuid();
    const results = await Promise.all(
      [...recording.agents.values()].map((agent) => this.#stopAgent(agent, requestId, commandId)),
    );
@@ -9,7 +9,7 @@ describe("disconnect session cleanup", () => {
    const manager = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => nextWindowId++),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
        remove,
      },
    });
@@ -41,7 +41,7 @@ describe("disconnect session cleanup", () => {
    const manager = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 100),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
        remove: vi.fn(() => removeGate),
      },
    });
@@ -39,7 +39,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await manager.start("aa11");
@@ -73,7 +73,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const ctx = await manager.start("aa11");
@@ -87,6 +87,7 @@ describe("attachSessionEventHandler", () => {
      windowEvents: events.api,
    });

+    manager.forgetClosedTab(7, { isWindowClosing: true });
    events.emit(4242);
    for (let i = 0; i < 4; i += 1) await Promise.resolve();

@@ -113,7 +114,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const transport = fakeTransport();
@@ -129,7 +130,7 @@ describe("attachSessionEventHandler", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const transport = fakeTransport();
@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AgentWindowApi, AgentWindowCreateOptions } from "../agent-window";
-import { SessionManager } from "../manager";
+import { isAgentControlledTab, SessionManager } from "../manager";

 function fakeAgentWindow(): AgentWindowApi & {
  createMock: ReturnType<typeof vi.fn>;
@@ -13,7 +13,7 @@ function fakeAgentWindow(): AgentWindowApi & {
    return id;
  });
  const removeMock = vi.fn(async (_id: number) => {});
-  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => {});
+  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => 0);
  return {
    create: createMock,
    remove: removeMock,
@@ -151,6 +151,76 @@ describe("SessionManager", () => {
    expect(sm.list()).toEqual([]);
  });

+  describe("explicit tab claims", () => {
+    it("claims the exact home tab returned by AgentWindowApi", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const ctx = await sm.start("aa11");
+      expect(ctx.agentCreatedTabs).toEqual(new Set([0]));
+      expect(isAgentControlledTab(ctx, 0)).toBe(true);
+    });
+
+    it("keeps every other tab free without classification state", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const ctx = await sm.start("aa11");
+      expect(isAgentControlledTab(ctx, 99)).toBe(false);
+      expect(ctx).not.toHaveProperty("userTabs");
+      expect(ctx).not.toHaveProperty("pendingAgentTabCount");
+    });
+
+    it("treats a committed borrow as an explicit claim", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const ctx = await sm.start("aa11");
+      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
+      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
+      reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 3 });
+      expect(isAgentControlledTab(ctx, 42)).toBe(true);
+    });
+
+    it("forgets an agent-created tab after Chrome removes it", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const ctx = await sm.start("aa11");
+      ctx.agentCreatedTabs.add(42);
+      sm.forgetClosedTab(42);
+      expect(ctx.agentCreatedTabs.has(42)).toBe(false);
+      expect(isAgentControlledTab(ctx, 0)).toBe(true);
+    });
+
+    it("forgets closed borrows idempotently without affecting other tabs or sessions", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const a = await sm.start("aa11");
+      const b = await sm.start("bb22");
+      a.borrowedTabs.set(42, { tabId: 42, originalWindowId: 7, originalIndex: 0 });
+      a.borrowedTabs.set(43, { tabId: 43, originalWindowId: 7, originalIndex: 1 });
+      b.borrowedTabs.set(44, { tabId: 44, originalWindowId: 8, originalIndex: 0 });
+
+      sm.forgetClosedTab(42);
+      sm.forgetClosedTab(42);
+      sm.forgetClosedTab(999);
+
+      expect(isAgentControlledTab(a, 42)).toBe(false);
+      expect(sm.findBorrowingSession(42, null)).toBeNull();
+      expect([...a.borrowedTabs.keys()]).toEqual([43]);
+      expect([...b.borrowedTabs.keys()]).toEqual([44]);
+      expect(sm.list()).toHaveLength(2);
+    });
+
+    it("prevents an in-flight borrow from reclaiming a closed tab", async () => {
+      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
+      const ctx = await sm.start("aa11");
+      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
+      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
+
+      sm.forgetClosedTab(42);
+
+      expect(() =>
+        reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 0 }),
+      ).toThrow(/reservation disappeared/);
+      reservation.release();
+      expect(sm.findBorrowingSession(42, null)).toBeNull();
+      expect(ctx.borrowedTabs.has(42)).toBe(false);
+    });
+  });
+
  describe("findBorrowingSession", () => {
    it("returns null when no session has borrowed the tab", async () => {
      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
@@ -13,8 +13,6 @@ describe("RefStore", () => {
      backendNodeId: 42,
      tabId: 7,
      generation: 0,
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
    });
    expect(s.size()).toBe(1);
    expect(s.isEmpty()).toBe(false);
@@ -50,31 +48,4 @@ describe("RefStore", () => {
      cdpSessionId: "child-session",
    });
  });
-
-  it("preserves explicit capabilities for visual surface refs", () => {
-    const s = new RefStore();
-    s.set("e1", 42, {
-      tabId: 7,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-
-    expect(s.resolveEntry("e1")).toMatchObject({
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-  });
-
-  it("never grants ordinary interaction to a surface through defaults or caller input", () => {
-    const s = new RefStore();
-    s.set("e1", 42, { tabId: 7, kind: "surface" });
-    s.set("e2", 43, {
-      tabId: 7,
-      kind: "surface",
-      capabilities: ["interact", "screenshot"],
-    });
-
-    expect(s.resolveEntry("e1")?.capabilities).toEqual(["screenshot"]);
-    expect(s.resolveEntry("e2")?.capabilities).toEqual(["screenshot"]);
-  });
 });
@@ -1,67 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { type SurfaceCaptureInput, SurfaceCaptureStore } from "../surface-capture-store";
-
-function input(): SurfaceCaptureInput {
-  return {
-    sessionId: "aa11",
-    tabId: 7,
-    navigationIdentity: "navigation",
-    surface: {
-      ref: "e3",
-      frameId: "main",
-      backendNodeId: 99,
-      observationGeneration: 2,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 50 },
-    imageWidth: 200,
-    imageHeight: 100,
-    viewportSignature: "viewport",
-    frameProjectionSignature: "frame",
-  };
-}
-
-describe("SurfaceCaptureStore", () => {
-  it("creates metadata-only, short-lived captures and consumes them once", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 500,
-      createId: () => "sc_test",
-    });
-    const capture = store.create(input());
-
-    expect(capture).toMatchObject({
-      id: "sc_test",
-      createdAt: 1_000,
-      expiresAt: 1_500,
-      consumed: false,
-    });
-    expect(capture).not.toHaveProperty("imageBase64");
-    expect(store.consume("sc_test")).toMatchObject({ ok: true });
-    expect(store.consume("sc_test")).toEqual({ ok: false, reason: "consumed" });
-
-    now = 1_600;
-    expect(store.size()).toBe(0);
-  });
-
-  it("rejects expired and unknown captures", () => {
-    let now = 1_000;
-    const store = new SurfaceCaptureStore({
-      now: () => now,
-      ttlMs: 10,
-      createId: () => "sc_expired",
-    });
-    store.create(input());
-    now = 1_010;
-
-    expect(store.consume("sc_expired")).toEqual({ ok: false, reason: "expired" });
-    expect(store.consume("sc_missing")).toEqual({ ok: false, reason: "not_found" });
-  });
-
-  it("clears every capture on session cleanup", () => {
-    const store = new SurfaceCaptureStore({ createId: () => "sc_clear" });
-    store.create(input());
-    store.clear();
-    expect(store.size()).toBe(0);
-  });
-});
@@ -14,8 +14,11 @@ export interface AgentWindowApi {
   * Guarantee the Agent Window has an active, CDP-navigable tab.
   * `chrome://` pages (including the New Tab page) reject `Page.navigate`,
   * so sessions bootstrap with `about:blank` instead.
+   *
+   * Resolves with the id of the activated (or newly created) tab, so callers
+   * can track the session's home tab without re-querying Chrome.
   */
-  ensureActiveTab(windowId: number, url: string): Promise<void>;
+  ensureActiveTab(windowId: number, url: string): Promise<number>;
 }

 /** Creation hints for a new Agent Window. */
@@ -49,15 +52,19 @@ export const chromeAgentWindowApi: AgentWindowApi = {
    // cancellation success while the Agent Window remains open.
    await chrome.windows.remove(windowId);
  },
-  async ensureActiveTab(windowId: number, url: string): Promise<void> {
+  async ensureActiveTab(windowId: number, url: string): Promise<number> {
    const tabs = await chrome.tabs.query({ windowId });
    const first = tabs.find((t) => typeof t.id === "number");
-    if (first?.id) {
+    if (first?.id !== undefined) {
      if (!first.active) {
        await chrome.tabs.update(first.id, { active: true });
      }
-      return;
+      return first.id;
    }
-    await chrome.tabs.create({ windowId, url, active: true });
+    const created = await chrome.tabs.create({ windowId, url, active: true });
+    if (typeof created?.id !== "number") {
+      throw new Error("[bh] chrome.tabs.create returned no tab id");
+    }
+    return created.id;
  },
 };
@@ -1,16 +1,25 @@
 import { AGENT_WINDOW_HOME, type AgentWindowApi, chromeAgentWindowApi } from "./agent-window";
 import { RefStore } from "./ref-store";
-import { SurfaceCaptureStore } from "./surface-capture-store";

 export interface SessionContext {
  sessionId: string;
  agentWindowId: number;
  refStore: RefStore;
-  surfaceCaptures: SurfaceCaptureStore;
  borrowedTabs: Map<number, BorrowedTab>;
+  /**
+   * Tabs explicitly claimed by the agent because it created them. This
+   * includes the Agent Window's home tab and tabs created by `tool.tab_create`.
+   * Tabs opened through Chrome UI never enter this set.
+   */
+  agentCreatedTabs: Set<number>;
  createdAtMs: number;
 }

+/** Whether this session has explicitly claimed control of `tabId`. */
+export function isAgentControlledTab(ctx: SessionContext, tabId: number): boolean {
+  return ctx.agentCreatedTabs.has(tabId) || ctx.borrowedTabs.has(tabId);
+}
+
 export interface BorrowedTab {
  tabId: number;
  originalWindowId: number;
@@ -108,6 +117,19 @@ export class SessionManager {
    return Array.from(this.sessions.values());
  }

+  /**
+   * Forget a tab Chrome has removed, including any uncommitted borrow.
+   * Whole-window closures keep committed borrows until the window-removed
+   * handler reports which user tabs could not be returned.
+   */
+  forgetClosedTab(tabId: number, { isWindowClosing = false } = {}): void {
+    this.borrowReservations.delete(tabId);
+    for (const ctx of this.sessions.values()) {
+      ctx.agentCreatedTabs.delete(tabId);
+      if (!isWindowClosing) ctx.borrowedTabs.delete(tabId);
+    }
+  }
+
  /**
   * Look up whether `tabId` is currently borrowed by some *other*
   * session than the one calling. Used by M8 `tab_borrow` to refuse
@@ -181,15 +203,18 @@ export class SessionManager {
      const { signal: _signal, ...createOptions } = opts;
      windowId = await this.agentWindow.create(AGENT_WINDOW_HOME, createOptions);
      throwIfSessionStartAborted(opts.signal);
-      await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
+      const homeTabId = await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
      throwIfSessionStartAborted(opts.signal);

      const ctx: SessionContext = {
        sessionId,
        agentWindowId: windowId,
        refStore: new RefStore(),
-        surfaceCaptures: new SurfaceCaptureStore({ now: this.now }),
        borrowedTabs: new Map(),
+        // The home tab is the session's first explicit claim. Every other
+        // tab remains free until `tab_create` or `tab_borrow` identifies it
+        // by its concrete Chrome tab id.
+        agentCreatedTabs: new Set([homeTabId]),
        createdAtMs: this.now(),
      };
      this.sessions.set(sessionId, ctx);
@@ -1,5 +1,3 @@
-import type { Rect } from "@browser-skill/vom";
-
 /**
 * Per-session map from `@e<N>` snapshot refs to a CDP node address.
 *
@@ -14,17 +12,12 @@ import type { Rect } from "@browser-skill/vom";
 * inside the `SessionContext`.
 */
 export type BackendNodeId = number;
-export type RefCapability = "interact" | "screenshot";
-export type RefTargetKind = "dom" | "surface";

 export interface RefEntry {
  backendNodeId: BackendNodeId;
  tabId: number | null;
  frameId?: string;
  cdpSessionId?: string;
-  visibleRect?: Rect;
-  kind: RefTargetKind;
-  capabilities: RefCapability[];
  generation: number;
 }

@@ -35,19 +28,8 @@ export type RefInput =
      tabId: number;
      frameId?: string;
      cdpSessionId?: string;
-      visibleRect?: Rect;
-      kind?: RefTargetKind;
-      capabilities?: RefCapability[];
    };

-function capabilitiesFor(
-  kind: RefTargetKind,
-  capabilities: RefCapability[] | undefined,
-): RefCapability[] {
-  if (kind === "surface") return ["screenshot"];
-  return capabilities ?? ["interact", "screenshot"];
-}
-
 export class RefStore {
  private readonly map = new Map<string, RefEntry>();
  private generation = 0;
@@ -88,20 +70,13 @@ export class RefStore {
      tabId?: number;
      frameId?: string;
      cdpSessionId?: string;
-      visibleRect?: Rect;
-      kind?: RefTargetKind;
-      capabilities?: RefCapability[];
    } = {},
  ): void {
-    const kind = opts.kind ?? "dom";
    this.map.set(normaliseRef(ref), {
      backendNodeId: id,
      tabId: opts.tabId ?? null,
      ...(opts.frameId ? { frameId: opts.frameId } : {}),
      ...(opts.cdpSessionId ? { cdpSessionId: opts.cdpSessionId } : {}),
-      ...(opts.visibleRect ? { visibleRect: opts.visibleRect } : {}),
-      kind,
-      capabilities: capabilitiesFor(kind, opts.capabilities),
      generation: this.generation,
    });
  }
@@ -119,20 +94,14 @@ export class RefStore {
      return {
        backendNodeId: input,
        tabId: null,
-        kind: "dom",
-        capabilities: ["interact", "screenshot"],
        generation: this.generation,
      };
    }
-    const kind = input.kind ?? "dom";
    return {
      backendNodeId: input.backendNodeId,
      tabId: input.tabId,
      ...(input.frameId ? { frameId: input.frameId } : {}),
      ...(input.cdpSessionId ? { cdpSessionId: input.cdpSessionId } : {}),
-      ...(input.visibleRect ? { visibleRect: input.visibleRect } : {}),
-      kind,
-      capabilities: capabilitiesFor(kind, input.capabilities),
      generation: this.generation,
    };
  }
@@ -1,100 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-
-export const SURFACE_CAPTURE_TTL_MS = 30_000;
-
-export interface SurfaceCapture {
-  id: string;
-  sessionId: string;
-  tabId: number;
-  navigationIdentity: string;
-  surface: {
-    ref: string;
-    frameId?: string;
-    backendNodeId: number;
-    observationGeneration: number;
-  };
-  topViewportRect: Rect;
-  imageWidth: number;
-  imageHeight: number;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-  createdAt: number;
-  expiresAt: number;
-  consumed: boolean;
-}
-
-export type SurfaceCaptureInput = Omit<
-  SurfaceCapture,
-  "id" | "createdAt" | "expiresAt" | "consumed"
->;
-
-export type SurfaceCaptureConsumeResult =
-  | { ok: true; capture: SurfaceCapture }
-  | { ok: false; reason: "not_found" | "expired" | "consumed" };
-
-export interface SurfaceCaptureStoreOptions {
-  now?: () => number;
-  ttlMs?: number;
-  createId?: () => string;
-}
-
-function randomCaptureId(): string {
-  const bytes = crypto.getRandomValues(new Uint8Array(12));
-  return `sc_${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
-}
-
-/** Per-session, metadata-only store for short-lived screenshot coordinate transactions. */
-export class SurfaceCaptureStore {
-  private readonly captures = new Map<string, SurfaceCapture>();
-  private readonly now: () => number;
-  private readonly ttlMs: number;
-  private readonly createId: () => string;
-
-  constructor(options: SurfaceCaptureStoreOptions = {}) {
-    this.now = options.now ?? Date.now;
-    this.ttlMs = options.ttlMs ?? SURFACE_CAPTURE_TTL_MS;
-    this.createId = options.createId ?? randomCaptureId;
-  }
-
-  create(input: SurfaceCaptureInput): SurfaceCapture {
-    this.purgeExpired();
-    const createdAt = this.now();
-    const capture: SurfaceCapture = {
-      ...input,
-      id: this.createId(),
-      createdAt,
-      expiresAt: createdAt + this.ttlMs,
-      consumed: false,
-    };
-    this.captures.set(capture.id, capture);
-    return capture;
-  }
-
-  consume(id: string): SurfaceCaptureConsumeResult {
-    const capture = this.captures.get(id);
-    if (!capture) return { ok: false, reason: "not_found" };
-    if (capture.expiresAt <= this.now()) {
-      this.captures.delete(id);
-      return { ok: false, reason: "expired" };
-    }
-    if (capture.consumed) return { ok: false, reason: "consumed" };
-    capture.consumed = true;
-    return { ok: true, capture };
-  }
-
-  clear(): void {
-    this.captures.clear();
-  }
-
-  size(): number {
-    this.purgeExpired();
-    return this.captures.size;
-  }
-
-  private purgeExpired(): void {
-    const now = this.now();
-    for (const [id, capture] of this.captures) {
-      if (capture.expiresAt <= now) this.captures.delete(id);
-    }
-  }
-}
@@ -127,6 +127,38 @@ describe("requestBorrowConfirmation", () => {
    expect(message.requestId.length).toBeGreaterThan(0);
  });

+  it("proactively focuses the user window before sending the overlay message", async () => {
+    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
+    windows.getLastFocused.mockResolvedValueOnce(
+      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
+    );
+    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
+
+    const pending = requestBorrowConfirmation(42, {
+      deps: { tabs, windows, notifications },
+    });
+    await vi.runAllTimersAsync();
+    await pending;
+
+    expect(windows.update).toHaveBeenCalledWith(77, { focused: true });
+  });
+
+  it("still proceeds when proactive window focus fails", async () => {
+    tabs.get.mockResolvedValueOnce({ id: 42, title: "Tab" });
+    windows.getLastFocused.mockResolvedValueOnce(
+      userWindowWithActiveTab({ windowId: 77, tabId: 7, url: "https://app.example/" }),
+    );
+    windows.update.mockRejectedValueOnce(new Error("window gone"));
+    tabs.sendMessage.mockResolvedValueOnce({ type: "borrow-response", allowed: true });
+
+    const pending = requestBorrowConfirmation(42, {
+      deps: { tabs, windows, notifications },
+    });
+    await vi.runAllTimersAsync();
+
+    expect(await pending).toBe(true);
+  });
+
  it("sends confirmation to the borrow target when it is the active tab", async () => {
    tabs.get.mockResolvedValueOnce({ id: 42, title: "Active Tab" });
    windows.getLastFocused.mockResolvedValueOnce(
@@ -13,7 +13,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -49,13 +49,54 @@ 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({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -117,7 +158,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -140,7 +181,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create,
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -158,7 +199,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -172,6 +213,47 @@ describe("ToolDispatcher", () => {
    expect(sent[0]).toEqual({ id: "r-1", result: {} });
  });

+  it("wires the production tab APIs into tool.session_stop so a surviving user tab releases the window", async () => {
+    // Regression guard for the deps that session_stop reads directly: when
+    // `tabManagement.tabs` / `tabsQuery` are not injected by the dispatcher,
+    // the agent-tab cleanup and the release decision silently no-op and the
+    // Agent Window is closed even though a user tab is still open (issue #57).
+    const removeTab = vi.fn(async () => {});
+    const closeWindow = vi.fn(async () => {});
+    // After cleanup the window still holds one tab (id 99) that is neither
+    // the home tab nor an agent-created tab — i.e. a genuine user tab.
+    vi.stubGlobal("chrome", {
+      tabs: {
+        remove: removeTab,
+        query: vi.fn(async () => [{ id: 99, windowId: 4242, active: true }]),
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: closeWindow,
+        ensureActiveTab: vi.fn(async () => 1),
+      },
+    });
+    await sessions.start("aa11");
+    // Register the exact tab id returned by the agent's creation path.
+    sessions.get("aa11")?.agentCreatedTabs.add(7);
+
+    const dispatcher = new ToolDispatcher({ transport, sessions });
+    dispatcher.start();
+
+    deliver(makeRequest("tool.session_stop", { session_id: "aa11" }));
+    await flushMicrotasks();
+
+    // The agent tab is closed through the real chrome.tabs surface...
+    expect(removeTab).toHaveBeenCalledWith(7);
+    // ...and the window is released rather than closed, so the user's tab survives.
+    expect(closeWindow).not.toHaveBeenCalled();
+    expect(sessions.has("aa11")).toBe(false);
+    expect(sent[0]).toEqual({ id: "r-1", result: { window_released: true } });
+  });
+
  it("routes tool.console through the CDP console buffer", async () => {
    vi.stubGlobal("chrome", {
      tabs: {
@@ -183,7 +265,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -232,13 +314,114 @@ describe("ToolDispatcher", () => {
    });
  });

+  it("bypasses and restores the control overlay for an upload trigger click", async () => {
+    const sendMessage = vi.fn(async () => undefined);
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => ({ id: 7, windowId: 4242, active: true })),
+        query: vi.fn(async () => [{ id: 7, windowId: 4242, active: true }]),
+        sendMessage,
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
+      },
+    });
+    const ctx = await sessions.start("aa11");
+    ctx.refStore.set("e1", 123, { tabId: 7 });
+    const send = vi.fn(async <T>(_tabId: number, method: string, params?: object) => {
+      if (method === "Page.getLayoutMetrics") {
+        return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } } as T;
+      }
+      if (method === "DOM.getContentQuads") {
+        return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] } as T;
+      }
+      if (method === "DOM.resolveNode") {
+        return { object: { objectId: "trigger-object" } } as T;
+      }
+      if (method === "DOM.describeNode") return { node: { backendNodeId: 456 } } as T;
+      if (method === "Runtime.callFunctionOn") {
+        const declaration = (params as { functionDeclaration?: string }).functionDeclaration ?? "";
+        if (declaration.includes("count: state.inputs.length")) {
+          return { result: { value: { count: 1, multiple: false } } } as T;
+        }
+        if (declaration.includes("inputs[0]")) {
+          return { result: { objectId: "input-object" } } as T;
+        }
+        return { result: { value: true } } as T;
+      }
+      if (method === "Runtime.evaluate") {
+        const expression = (params as { expression?: string }).expression ?? "";
+        if (expression.includes("overlayDetails")) {
+          return { result: { value: { hitIndex: 0 } } } as T;
+        }
+        if (expression.includes("overlayHostPresent")) {
+          return {
+            result: {
+              value: { overlayHostPresent: true, overlayHostConnected: true },
+            },
+          } as T;
+        }
+        if (expression.includes("count:")) {
+          return { result: { value: { count: 1, multiple: false } } } as T;
+        }
+        if (expression.includes("?.inputs[0]")) {
+          return { result: { objectId: "input-object" } } as T;
+        }
+        return { result: { value: true } } as T;
+      }
+      return {} as T;
+    });
+    const cdp = {
+      send,
+      detachSession: vi.fn(async () => {}),
+      ensureNetworkCapture: vi.fn(async () => {}),
+      networkEntriesSince: vi.fn(() => ({
+        tab_id: 7,
+        entries: [],
+        next_since: 0,
+        truncated: false,
+      })),
+      setDeviceMetricsOverride: vi.fn(async () => {}),
+      clearDeviceMetricsOverride: vi.fn(async () => {}),
+      setUserAgentOverride: vi.fn(async () => {}),
+      setTouchEmulationEnabled: vi.fn(async () => {}),
+    };
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp: cdp as TestDispatcherCdp });
+    dispatcher.start();
+
+    deliver(
+      makeRequest("tool.upload", {
+        session_id: "aa11",
+        ref: "@e1",
+        files: [{ transfer_id: "tr_1", name: "test.png", staged_path: "/stage/test.png" }],
+      }),
+    );
+    await flushMicrotasks();
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+
+    expect(sent[0]).toMatchObject({ result: { tab_id: 7, file_names: ["test.png"] } });
+    expect(sendMessage).toHaveBeenNthCalledWith(1, 7, {
+      type: "bh-automation-bypass",
+      enabled: true,
+    });
+    expect(sendMessage).toHaveBeenNthCalledWith(2, 7, {
+      type: "bh-automation-bypass",
+      enabled: false,
+    });
+  });
+
  it("detaches CDP state before stopping a session", async () => {
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -274,7 +457,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove,
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -322,7 +505,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -342,7 +525,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -366,7 +549,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -383,7 +566,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -400,7 +583,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const onSessionsChanged = vi.fn();
@@ -417,16 +600,32 @@ describe("ToolDispatcher", () => {
  });

  it("invokes onBrowserControlResumed for browser-control tools but not passive reads", async () => {
+    vi.stubGlobal("chrome", {
+      tabs: {
+        create: vi.fn(async (props: chrome.tabs.CreateProperties) => ({
+          id: 7,
+          windowId: props.windowId,
+          url: props.url,
+          active: props.active,
+        })),
+      },
+    });
    const { transport, sent, deliver } = fakeTransport();
    const sessions = new SessionManager({
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const onBrowserControlResumed = vi.fn();
-    const dispatcher = new ToolDispatcher({ transport, sessions, onBrowserControlResumed });
+    const onAgentTabClaimed = vi.fn();
+    const dispatcher = new ToolDispatcher({
+      transport,
+      sessions,
+      onBrowserControlResumed,
+      onAgentTabClaimed,
+    });
    dispatcher.start();

    deliver(makeRequest("tool.session_start", { session_id: "aa11" }));
@@ -443,6 +642,7 @@ describe("ToolDispatcher", () => {
    });
    await flushMicrotasks();
    expect(onBrowserControlResumed).toHaveBeenCalledWith("aa11");
+    expect(onAgentTabClaimed).toHaveBeenCalledWith(7, 1);
  });

  it("reasserts remembered hover before follow-up work and releases only after actions", async () => {
@@ -456,7 +656,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const order: string[] = [];
@@ -538,7 +738,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const cdp = {
@@ -588,6 +788,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: {
@@ -599,7 +928,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -636,7 +965,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    await sessions.start("aa11");
@@ -688,7 +1017,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -722,7 +1051,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 4242),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    transport.send = () => {
@@ -744,7 +1073,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 5555),
        remove,
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    transport.send = () => {
@@ -772,7 +1101,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(() => createPromise),
        remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -823,7 +1152,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(async () => 1),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -844,7 +1173,7 @@ describe("ToolDispatcher", () => {
      agentWindow: {
        create: vi.fn(() => createPromise),
        remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => {}),
+        ensureActiveTab: vi.fn(async () => 1),
      },
    });
    const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -1,104 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { fillEditable } from "../editable-input";
-import type { CdpRunner } from "../shared";
-
-interface FakeOptions {
-  initialValue?: string;
-  finalValue: string;
-  remount?: boolean;
-}
-
-function editableState(value: string, connected = true, focused = true) {
-  return {
-    result: {
-      value: { supported: true, connected, focused, value, kind: "input" },
-    },
-  };
-}
-
-function makeEditableCdp(options: FakeOptions) {
-  const sent: Array<{ method: string; params?: object }> = [];
-  let inserted = false;
-  const send = vi.fn(async <T>(_tabId: number, method: string, params?: object): Promise<T> => {
-    sent.push({ method, params });
-    if (method === "Input.insertText") {
-      inserted = true;
-      return {} as T;
-    }
-    if (method === "Input.dispatchKeyEvent") {
-      if ((params as { type?: string }).type === "rawKeyDown") inserted = true;
-      return {} as T;
-    }
-    if (method !== "Runtime.callFunctionOn") throw new Error(`unexpected ${method}`);
-
-    const call = params as { objectId?: string; functionDeclaration?: string };
-    const fn = call.functionDeclaration ?? "";
-    if (fn.includes("bsk-editable-selection")) {
-      return { result: { value: { selected: true } } } as T;
-    }
-    if (fn.includes("bsk-editable-sync")) return { result: { value: undefined } } as T;
-    if (fn.includes("bsk-editable-live")) {
-      return {
-        result: options.remount && inserted ? { objectId: "replacement" } : { objectId: "anchor" },
-      } as T;
-    }
-    if (fn.includes("bsk-editable-state")) {
-      if (call.objectId === "replacement") return editableState(options.finalValue) as T;
-      if (options.remount && inserted) {
-        return editableState(options.finalValue, false, false) as T;
-      }
-      return editableState(inserted ? options.finalValue : (options.initialValue ?? "")) as T;
-    }
-    throw new Error("unexpected Runtime.callFunctionOn function");
-  });
-  return { cdp: { send } as CdpRunner, sent };
-}
-
-describe("fillEditable", () => {
-  it("replaces text through the browser input path without synthetic events or value setters", async () => {
-    const fake = makeEditableCdp({ initialValue: "old", finalValue: "新值" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "新值", true);
-
-    expect(result).toMatchObject({ value: "新值", replacedNode: false });
-    expect(fake.sent).toContainEqual({ method: "Input.insertText", params: { text: "新值" } });
-    const declarations = fake.sent
-      .map((call) => (call.params as { functionDeclaration?: string })?.functionDeclaration ?? "")
-      .join("\n");
-    expect(declarations).not.toMatch(/dispatchEvent|\.value\s*=/);
-  });
-
-  it("reacquires the focused editable after a framework remount", async () => {
-    const fake = makeEditableCdp({ finalValue: "persisted", remount: true });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "persisted", true);
-
-    expect(result).toMatchObject({ value: "persisted", replacedNode: true });
-  });
-
-  it("reports a page rollback after the bounded settlement", async () => {
-    const fake = makeEditableCdp({ finalValue: "" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "rejected", true);
-
-    expect(result).toMatchObject({
-      code: "cdp_failed",
-      data: {
-        reason: "input_not_applied",
-        expected_value_length: 8,
-        actual_value_length: 0,
-        phase: "readback",
-      },
-    });
-  });
-
-  it("clears to an empty value with a browser Backspace edit", async () => {
-    const fake = makeEditableCdp({ initialValue: "old", finalValue: "" });
-
-    const result = await fillEditable(fake.cdp, 4, "anchor", "", true);
-
-    expect(result).toMatchObject({ value: "" });
-    expect(fake.sent.some((call) => call.method === "Input.insertText")).toBe(false);
-    expect(fake.sent.filter((call) => call.method === "Input.dispatchKeyEvent")).toHaveLength(2);
-  });
-});
@@ -20,7 +20,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -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);
+    }
+  });
+});
@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -0,0 +1,988 @@
+import { describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import { type DownloadsApi, handleDownload } from "../download";
+import { captureBrowserDownload } from "../download-capture";
+import { uploadThroughFileDrop } from "../file-drop-transaction";
+import { uploadThroughActivatedFileInput } from "../file-input-transaction";
+import type { ResolvedActionTarget } from "../interaction";
+import type { CdpRunner } from "../shared";
+import { handleUpload } from "../upload";
+
+function sessions() {
+  return new SessionManager({
+    agentWindow: {
+      create: vi.fn(async () => 100),
+      remove: vi.fn(async () => {}),
+      ensureActiveTab: vi.fn(async () => 1),
+    },
+  });
+}
+
+function tabsApi() {
+  return {
+    get: vi.fn(
+      async (tabId: number) => ({ id: tabId, windowId: 100, active: true }) as chrome.tabs.Tab,
+    ),
+    query: vi.fn(async () => [{ id: 4, windowId: 100, active: true } as chrome.tabs.Tab]),
+  };
+}
+
+function fakeEvent<T extends (...args: never[]) => unknown>() {
+  const listeners = new Set<T>();
+  return {
+    addListener: (listener: T) => listeners.add(listener),
+    removeListener: (listener: T) => listeners.delete(listener),
+    emit: (...args: Parameters<T>) => {
+      for (const listener of listeners) listener(...args);
+    },
+  };
+}
+
+function actionTarget(frameId?: string, sessionId?: string): ResolvedActionTarget {
+  return {
+    tab: { tabId: 4, windowId: 100, active: true },
+    backendNodeId: 123,
+    cdpTarget: { tabId: 4, ...(sessionId ? { sessionId } : {}) },
+    ...(frameId ? { frameId } : {}),
+    usedRef: "e3",
+  };
+}
+
+function withoutOverlay<T>(operation: () => Promise<T>): Promise<T> {
+  return operation();
+}
+
+function uploadCdp(
+  options: {
+    inputCount?: number;
+    multiple?: boolean;
+    chooser?: { frameId?: string; backendNodeId?: number; mode?: string };
+    pendingResolve?: boolean;
+  } = {},
+) {
+  const calls: Array<{ method: string; params?: object }> = [];
+  let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    calls.push({ method, params });
+    if (method === "DOM.scrollIntoViewIfNeeded") return {};
+    if (method === "Page.setInterceptFileChooserDialog") return {};
+    if (method === "Page.getLayoutMetrics")
+      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
+    if (method === "DOM.getContentQuads") return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] };
+    if (method === "DOM.resolveNode") {
+      if (options.pendingResolve) return new Promise<never>(() => {});
+      return { object: { objectId: "trigger-object" } };
+    }
+    if (method === "Runtime.callFunctionOn") {
+      const declaration = (params as { functionDeclaration?: string }).functionDeclaration ?? "";
+      if (declaration.includes("Object.defineProperty")) return { result: { value: true } };
+      if (declaration.includes("count: state.inputs.length")) {
+        return {
+          result: {
+            value: {
+              count: options.inputCount ?? 1,
+              multiple: options.multiple ?? true,
+            },
+          },
+        };
+      }
+      if (declaration.includes("inputs[0]")) {
+        return { result: { objectId: "input-object" } };
+      }
+      return { result: { value: true } };
+    }
+    if (method === "DOM.describeNode") return { node: { backendNodeId: 456 } };
+    if (
+      method === "Input.dispatchMouseEvent" &&
+      (params as { type?: string }).type === "mousePressed" &&
+      options.chooser
+    ) {
+      cdpEvent?.({ tabId: 4 }, "Page.fileChooserOpened", options.chooser);
+    }
+    return {};
+  });
+  const cdp: CdpRunner = {
+    send: send as unknown as CdpRunner["send"],
+    onEvent: (handler) => {
+      cdpEvent = handler;
+      return { dispose: vi.fn() };
+    },
+  };
+  return {
+    calls,
+    emitChooser: (event: { frameId?: string; backendNodeId?: number; mode?: string }) =>
+      cdpEvent?.({ tabId: 4 }, "Page.fileChooserOpened", event),
+    cdp,
+  };
+}
+
+function dropCdp(
+  options: {
+    targetContainsPoint?: boolean;
+    dispatchError?: (type: string) => Error | Promise<never> | undefined;
+    onCall?: (method: string) => void;
+  } = {},
+) {
+  const calls: Array<{ method: string; params?: object }> = [];
+  const detach = vi.fn(async () => {});
+  const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+    calls.push({ method, params });
+    options.onCall?.(method);
+    if (method === "DOM.scrollIntoViewIfNeeded") return {};
+    if (method === "Page.getLayoutMetrics") {
+      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
+    }
+    if (method === "DOM.getContentQuads") {
+      return { quads: [[10, 20, 210, 20, 210, 120, 10, 120]] };
+    }
+    if (method === "DOM.getNodeForLocation") return { backendNodeId: 124 };
+    if (method === "DOM.resolveNode") {
+      const id = (params as { backendNodeId?: number }).backendNodeId;
+      return { object: { objectId: id === 123 ? "drop-target" : "hit-target" } };
+    }
+    if (method === "Runtime.callFunctionOn") {
+      return { result: { value: options.targetContainsPoint ?? true } };
+    }
+    if (method === "Input.dispatchDragEvent") {
+      const type = (params as { type?: string }).type ?? "";
+      const error = options.dispatchError?.(type);
+      if (error instanceof Promise) return error;
+      if (error) throw error;
+      return {};
+    }
+    if (method === "Runtime.releaseObjectGroup") return {};
+    throw new Error(`unexpected drop CDP command ${method}`);
+  });
+  const cdp: CdpRunner = {
+    send: send as unknown as CdpRunner["send"],
+    detach,
+  };
+  return { calls, cdp, detach };
+}
+
+describe("file transfer tools", () => {
+  it("captures the file input activated by the requested click and injects only staged paths", async () => {
+    const manager = sessions();
+    const ctx = await manager.start("s1");
+    ctx.refStore.set("e3", 123, { tabId: 4 });
+    const { cdp, calls } = uploadCdp();
+
+    const result = await handleUpload(
+      manager,
+      {
+        session_id: "s1",
+        ref: "@e3",
+        files: [
+          { transfer_id: "tr_1", name: "one.png", staged_path: "/private/stage/one" },
+          { transfer_id: "tr_2", name: "two.png", staged_path: "/private/stage/two" },
+        ],
+      },
+      { cdp, tabsApi: tabsApi() },
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, file_names: ["one.png", "two.png"] });
+    expect(calls[0]).toEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: true },
+    });
+    expect(calls).toContainEqual({
+      method: "Page.setInterceptFileChooserDialog",
+      params: { enabled: false, cancel: true },
+    });
+    expect(calls).toContainEqual({
+      method: "DOM.setFileInputFiles",
+      params: { files: ["/private/stage/one", "/private/stage/two"], backendNodeId: 456 },
+    });
+  });
+
+  it("fails immediately when the trigger does not activate a file input", async () => {
+    const { cdp } = uploadCdp({ inputCount: 0 });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => ({ tab_id: 4, x: 10, y: 10 }),
+    });
+
+    expect(result).toMatchObject({
+      code: "unsupported",
+      data: { reason: "file_input_not_activated", phase: "resolve_input" },
+    });
+  });
+
+  it("fails before clicking when chooser interception is unavailable", async () => {
+    const trigger = vi.fn(async () => ({ tab_id: 4, x: 10, y: 10 }));
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId: number, method: string) => {
+        if (method === "Page.setInterceptFileChooserDialog") {
+          throw new Error("method unavailable");
+        }
+        return {};
+      }) as CdpRunner["send"],
+    };
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger,
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { effect_state: "none", phase: "arm_interception" },
+    });
+    expect(trigger).not.toHaveBeenCalled();
+  });
+
+  it("uses an exact chooser event as an independent input-location signal", async () => {
+    const { cdp, calls, emitChooser } = uploadCdp({ inputCount: 0 });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget("f1"),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => {
+        emitChooser({ frameId: "f1", backendNodeId: 789, mode: "selectSingle" });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({ multiple: false });
+    expect(calls).toContainEqual({
+      method: "DOM.setFileInputFiles",
+      params: { files: ["/private/stage/one"], backendNodeId: 789 },
+    });
+  });
+
+  it("reports a File System Access picker without waiting for a timeout", async () => {
+    const { cdp, emitChooser } = uploadCdp({
+      inputCount: 0,
+    });
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget("f1"),
+      files: ["/private/stage/one"],
+      timeoutMs: 100,
+      trigger: async () => {
+        emitChooser({ frameId: "f1", mode: "selectSingle" });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "unsupported",
+      message: "upload trigger invoked a non-input file picker",
+      data: { reason: "file_input_not_activated", phase: "resolve_input" },
+    });
+  });
+
+  it("bounds a stuck file-input probe", async () => {
+    const { cdp } = uploadCdp({ pendingResolve: true });
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 5,
+      trigger: vi.fn(),
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { reason: "file_input_probe_failed", phase: "arm_input_probe" },
+    });
+  });
+
+  it("marks a timed-out file assignment unknown and detaches browser state", async () => {
+    const fixture = uploadCdp();
+    const originalSend = fixture.cdp.send;
+    const detach = vi.fn(async () => {});
+    fixture.cdp.detach = detach;
+    fixture.cdp.send = vi.fn((tabId: number, method: string, params?: object) => {
+      if (method === "DOM.setFileInputFiles") return new Promise<never>(() => {});
+      return originalSend(tabId, method, params);
+    }) as CdpRunner["send"];
+
+    const result = await uploadThroughActivatedFileInput({
+      cdp: fixture.cdp,
+      actionTarget: actionTarget(),
+      files: ["/private/stage/one"],
+      timeoutMs: 10,
+      trigger: async () => ({ tab_id: 4, x: 10, y: 10 }),
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { effect_state: "unknown", phase: "set_files" },
+    });
+    expect(detach).toHaveBeenCalledWith(4);
+  });
+
+  it("delivers staged files through one explicit native drop without clicking", async () => {
+    const manager = sessions();
+    const ctx = await manager.start("s1");
+    ctx.refStore.set("e3", 123, { tabId: 4 });
+    const lifecycle: string[] = [];
+    const { cdp, calls } = dropCdp({ onCall: (method) => lifecycle.push(method) });
+    const overlayPhases: string[] = [];
+
+    const result = await handleUpload(
+      manager,
+      {
+        session_id: "s1",
+        ref: "@e3",
+        mode: "drop",
+        files: [{ transfer_id: "tr_1", name: "one.png", staged_path: "/stage/one.png" }],
+      },
+      {
+        cdp,
+        tabsApi: tabsApi(),
+        sendToTab: vi.fn(async (_tabId, message) => {
+          overlayPhases.push(message.phase);
+          lifecycle.push(`overlay:${message.phase}`);
+        }),
+      },
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, used_ref: "e3", file_names: ["one.png"] });
+    expect(calls.filter((call) => call.method === "Input.dispatchDragEvent")).toEqual([
+      {
+        method: "Input.dispatchDragEvent",
+        params: {
+          type: "dragEnter",
+          x: 110,
+          y: 70,
+          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
+        },
+      },
+      {
+        method: "Input.dispatchDragEvent",
+        params: {
+          type: "dragOver",
+          x: 110,
+          y: 70,
+          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
+        },
+      },
+      {
+        method: "Input.dispatchDragEvent",
+        params: {
+          type: "drop",
+          x: 110,
+          y: 70,
+          data: { items: [], files: ["/stage/one.png"], dragOperationsMask: 1 },
+        },
+      },
+    ]);
+    expect(calls.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
+    expect(overlayPhases).toEqual(["begin", "end"]);
+    expect(lifecycle.indexOf("DOM.getContentQuads")).toBeLessThan(
+      lifecycle.indexOf("overlay:begin"),
+    );
+    expect(lifecycle.indexOf("overlay:begin")).toBeLessThan(
+      lifecycle.indexOf("DOM.getNodeForLocation"),
+    );
+    expect(lifecycle.lastIndexOf("Input.dispatchDragEvent")).toBeLessThan(
+      lifecycle.indexOf("overlay:end"),
+    );
+    expect(lifecycle.indexOf("overlay:end")).toBeLessThan(
+      lifecycle.indexOf("Runtime.releaseObjectGroup"),
+    );
+  });
+
+  it("fails closed before dragging when another element owns the action point", async () => {
+    const { cdp, calls } = dropCdp({ targetContainsPoint: false });
+    const result = await uploadThroughFileDrop({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/stage/one.png"],
+      timeoutMs: 100,
+      withOverlayHidden: withoutOverlay,
+    });
+
+    expect(result).toMatchObject({
+      code: "permission_denied",
+      data: {
+        reason: "file_drop_target_unavailable",
+        mechanism: "drop",
+        effect_state: "none",
+        phase: "resolve_target",
+      },
+    });
+    expect(calls.some((call) => call.method === "Input.dispatchDragEvent")).toBe(false);
+  });
+
+  it("dispatches an OOPIF file drop in the child target's local coordinates", async () => {
+    const rootCalls: Array<{ method: string; params?: object }> = [];
+    const childCalls: Array<{ method: string; params?: object }> = [];
+    const cdp: CdpRunner = {
+      send: vi.fn(async (_tabId, method, params) => {
+        rootCalls.push({ method, params });
+        if (method === "DOM.scrollIntoViewIfNeeded") return {};
+        if (method === "DOM.getBoxModel") {
+          return { model: { content: [100, 100, 300, 100, 300, 200, 100, 200] } };
+        }
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 800, clientHeight: 600 } };
+        }
+        throw new Error(`unexpected root command ${method}`);
+      }) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method, params) => {
+        childCalls.push({ method, params });
+        if (method === "DOM.scrollIntoViewIfNeeded") return {};
+        if (method === "DOM.getContentQuads") {
+          return { quads: [[10, 20, 210, 20, 210, 120, 10, 120]] };
+        }
+        if (method === "Page.getLayoutMetrics") {
+          return { cssLayoutViewport: { clientWidth: 400, clientHeight: 300 } };
+        }
+        if (method === "DOM.getNodeForLocation") {
+          return { backendNodeId: 124, frameId: "child" };
+        }
+        if (method === "DOM.resolveNode") {
+          const id = (params as { backendNodeId?: number }).backendNodeId;
+          return { object: { objectId: id === 123 ? "drop-target" : "hit-target" } };
+        }
+        if (method === "Runtime.callFunctionOn") return { result: { value: true } };
+        if (method === "Input.dispatchDragEvent" || method === "Runtime.releaseObjectGroup") {
+          return {};
+        }
+        throw new Error(`unexpected child command ${method}`);
+      }) as 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 result = await uploadThroughFileDrop({
+      cdp,
+      actionTarget: actionTarget("child", "child-session"),
+      files: ["/stage/one.png"],
+      timeoutMs: 100,
+      withOverlayHidden: withoutOverlay,
+    });
+
+    expect(result).toMatchObject({ x: 110, y: 70 });
+    expect(
+      childCalls
+        .filter((call) => call.method === "Input.dispatchDragEvent")
+        .map((call) => call.params),
+    ).toEqual([
+      expect.objectContaining({ type: "dragEnter", x: 110, y: 70 }),
+      expect.objectContaining({ type: "dragOver", x: 110, y: 70 }),
+      expect.objectContaining({ type: "drop", x: 110, y: 70 }),
+    ]);
+    expect(rootCalls.some((call) => call.method === "Input.dispatchDragEvent")).toBe(false);
+  });
+
+  it("reports a missing native drag command as unsupported before commit", async () => {
+    const { cdp } = dropCdp({
+      dispatchError: (type) =>
+        type === "dragEnter" ? new Error("'Input.dispatchDragEvent' wasn't found") : undefined,
+    });
+    const result = await uploadThroughFileDrop({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/stage/one.png"],
+      timeoutMs: 100,
+      withOverlayHidden: withoutOverlay,
+    });
+
+    expect(result).toMatchObject({
+      code: "unsupported",
+      data: {
+        reason: "upload_mechanism_unsupported",
+        effect_state: "none",
+        phase: "drag_enter",
+      },
+    });
+  });
+
+  it("cancels an unresolved drag before returning a pre-commit timeout", async () => {
+    const { cdp, calls } = dropCdp({
+      dispatchError: (type) => (type === "dragEnter" ? new Promise<never>(() => {}) : undefined),
+    });
+    const result = await uploadThroughFileDrop({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/stage/one.png"],
+      timeoutMs: 10,
+      withOverlayHidden: withoutOverlay,
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { reason: "file_drop_failed", effect_state: "none", phase: "drag_enter" },
+    });
+    expect(calls).toContainEqual({
+      method: "Input.dispatchDragEvent",
+      params: expect.objectContaining({ type: "dragCancel" }),
+    });
+  });
+
+  it("marks an unresolved drop unknown and detaches browser state", async () => {
+    const { cdp, detach } = dropCdp({
+      dispatchError: (type) => (type === "drop" ? new Promise<never>(() => {}) : undefined),
+    });
+    const result = await uploadThroughFileDrop({
+      cdp,
+      actionTarget: actionTarget(),
+      files: ["/stage/one.png"],
+      timeoutMs: 10,
+      withOverlayHidden: withoutOverlay,
+    });
+
+    expect(result).toMatchObject({
+      code: "timeout",
+      data: { reason: "file_drop_failed", effect_state: "unknown", phase: "drop" },
+    });
+    expect(detach).toHaveBeenCalledWith(4);
+  });
+
+  it("routes one exact-target download through a browser-relative capability", async () => {
+    const manager = sessions();
+    const ctx = await manager.start("s1");
+    ctx.refStore.set("e3", 123, { tabId: 4 });
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 9,
+      url: "https://example.test/result.zip",
+      finalUrl: "https://example.test/result.zip",
+      filename: "result.zip",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: 12,
+      mime: "application/zip",
+      danger: "safe",
+    } as chrome.downloads.DownloadItem;
+    const completed = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_1/result.zip",
+      state: "complete",
+      fileSize: 12,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [completed]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    let suggested: chrome.downloads.DownloadFilenameSuggestion | undefined;
+    const send = vi.fn(async (_tabId: number, method: string, params?: object) => {
+      if (method === "Page.getLayoutMetrics")
+        return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
+      if (method === "DOM.getContentQuads") return { quads: [[0, 0, 20, 0, 20, 20, 0, 20]] };
+      if (
+        method === "Input.dispatchMouseEvent" &&
+        (params as { type?: string }).type === "mousePressed"
+      ) {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: "result.zip",
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, (value) => {
+            suggested = value;
+            resolve();
+          });
+        });
+        onCreated.emit(completed);
+      }
+      return {};
+    });
+    const cdp: CdpRunner = {
+      send: send as unknown as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await handleDownload(
+      manager,
+      { session_id: "s1", ref: "@e3", browser_relative_dir: "BrowserSkill/tr_1" },
+      { cdp, tabsApi: tabsApi(), downloads },
+    );
+
+    expect(suggested).toEqual({
+      filename: "BrowserSkill/tr_1/result.zip",
+      conflictAction: "overwrite",
+    });
+    expect(result).toMatchObject({
+      tab_id: 4,
+      suggested_filename: "result.zip",
+      byte_size: 12,
+      browser_path: completed.filename,
+    });
+  });
+
+  it("does not claim a download without an intent from the exact target", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => []),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as unknown as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    const unrelated = {
+      id: 17,
+      url: "https://example.test/unrelated.zip",
+      finalUrl: "https://example.test/unrelated.zip",
+      filename: "unrelated.zip",
+      state: "in_progress",
+    } as chrome.downloads.DownloadItem;
+    let defaultSuggestionCalled = false;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4, sessionId: "expected-child" },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_1",
+      timeoutMs: 5,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4, sessionId: "other-child" }, "Page.downloadWillBegin", {
+          url: unrelated.url,
+          suggestedFilename: unrelated.filename,
+        });
+        onDeterminingFilename.emit(unrelated, (suggestion) => {
+          defaultSuggestionCalled = suggestion === undefined;
+        });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(defaultSuggestionCalled).toBe(true);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed" },
+    });
+  });
+
+  it("correlates a filename candidate that arrives before the CDP intent", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 21,
+      url: "https://example.test/candidate-first.bin",
+      finalUrl: "https://example.test/candidate-first.bin",
+      filename: "candidate-first.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: 4,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      state: "complete",
+      fileSize: 4,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [complete]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    let suggestion: chrome.downloads.DownloadFilenameSuggestion | undefined;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_21",
+      timeoutMs: 1_000,
+      trigger: async () => {
+        const suggested = new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, (value) => {
+            suggestion = value;
+            resolve();
+          });
+        });
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await suggested;
+        onCreated.emit(complete);
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(suggestion).toEqual({
+      filename: "BrowserSkill/tr_21/candidate-first.bin",
+      conflictAction: "overwrite",
+    });
+    expect(result).toMatchObject({ item: { id: 21, state: "complete" } });
+  });
+
+  it("removes a completed download when the final size exceeds the limit", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 22,
+      url: "https://example.test/oversized.bin",
+      finalUrl: "https://example.test/oversized.bin",
+      filename: "oversized.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: -1,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_22/oversized.bin",
+      state: "complete",
+      fileSize: 8,
+      totalBytes: 8,
+      bytesReceived: 8,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => [complete]),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_22",
+      maxByteSize: 4,
+      timeoutMs: 1_000,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, () => resolve());
+        });
+        onCreated.emit(initial);
+        onChanged.emit({ id: initial.id, state: { current: "complete" } });
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed", effect_state: "committed" },
+    });
+    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+  });
+
+  it("reconciles a download that completes while cancellation is being requested", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const initial = {
+      id: 23,
+      url: "https://example.test/racing.bin",
+      finalUrl: "https://example.test/racing.bin",
+      filename: "racing.bin",
+      state: "in_progress",
+      fileSize: -1,
+      totalBytes: -1,
+      bytesReceived: 0,
+    } as chrome.downloads.DownloadItem;
+    const complete = {
+      ...initial,
+      filename: "/profile/Downloads/BrowserSkill/tr_23/racing.bin",
+      state: "complete",
+      fileSize: 4,
+      totalBytes: 4,
+      bytesReceived: 4,
+    } as chrome.downloads.DownloadItem;
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn().mockResolvedValueOnce([initial]).mockResolvedValueOnce([complete]),
+      cancel: vi.fn(async () => {
+        throw new Error("download already complete");
+      }),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_23",
+      timeoutMs: 80,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: initial.url,
+          suggestedFilename: initial.filename,
+        });
+        await new Promise<void>((resolve) => {
+          onDeterminingFilename.emit(initial, () => resolve());
+        });
+        onCreated.emit(initial);
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "download_capture_failed", effect_state: "committed" },
+    });
+    expect(downloads.cancel).toHaveBeenCalledWith(initial.id);
+    expect(downloads.removeFile).toHaveBeenCalledWith(initial.id);
+    expect(result).not.toMatchObject({ data: { cleanup_state: "failed" } });
+  });
+
+  it("rejects ambiguous attribution without cancelling either unclaimed download", async () => {
+    const onCreated = fakeEvent<(item: chrome.downloads.DownloadItem) => void>();
+    const onChanged = fakeEvent<(delta: chrome.downloads.DownloadDelta) => void>();
+    const onDeterminingFilename =
+      fakeEvent<
+        (
+          item: chrome.downloads.DownloadItem,
+          suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+        ) => void | true
+      >();
+    const downloads: DownloadsApi = {
+      onCreated,
+      onChanged,
+      onDeterminingFilename,
+      search: vi.fn(async () => []),
+      cancel: vi.fn(async () => {}),
+      removeFile: vi.fn(async () => {}),
+    };
+    let cdpEvent: Parameters<NonNullable<CdpRunner["onEvent"]>>[0] | undefined;
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      onEvent: (handler) => {
+        cdpEvent = handler;
+        return { dispose: vi.fn() };
+      },
+    };
+    const defaults: number[] = [];
+    const candidate = (id: number) =>
+      ({
+        id,
+        url: "https://example.test/same.bin",
+        finalUrl: "https://example.test/same.bin",
+        filename: "same.bin",
+        state: "in_progress",
+      }) as chrome.downloads.DownloadItem;
+
+    const result = await captureBrowserDownload({
+      cdp,
+      target: { tabId: 4 },
+      downloads,
+      browserRelativeDir: "BrowserSkill/tr_ambiguous",
+      timeoutMs: 100,
+      trigger: async () => {
+        cdpEvent?.({ tabId: 4 }, "Page.downloadWillBegin", {
+          url: "https://example.test/same.bin",
+          suggestedFilename: "same.bin",
+        });
+        for (const id of [31, 32]) {
+          onDeterminingFilename.emit(candidate(id), (value) => {
+            if (value === undefined) defaults.push(id);
+          });
+        }
+        return { tab_id: 4, x: 10, y: 10 };
+      },
+    });
+
+    expect(defaults.sort()).toEqual([31, 32]);
+    expect(downloads.cancel).not.toHaveBeenCalled();
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { effect_state: "unknown", phase: "attribution" },
+    });
+  });
+});
@@ -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 });
+  });
+});
@@ -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,6 +10,7 @@ import {
  rectPolygon,
  regionBounds,
 } from "../geometry";
+import { GeometryContext } from "../geometry/frame-context";
 import type { CdpRunner } from "../shared";

 describe("frame geometry projection", () => {
@@ -82,28 +83,24 @@ describe("frame geometry projection", () => {
        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([
      {
@@ -169,6 +166,7 @@ describe("frame geometry projection", () => {
    expect(geometry).toMatchObject({
      topBounds: { x: 100, y: 100, width: 200, height: 100 },
      actionPoint: { x: 200, y: 150 },
+      targetActionPoint: { x: 100, y: 50 },
    });
  });

@@ -261,6 +259,7 @@ describe("frame geometry projection", () => {
    expect(geometry).toMatchObject({
      topBounds: { x: 100, y: 100, width: 200, height: 100 },
      actionPoint: { x: 200, y: 150 },
+      targetActionPoint: { x: 200, y: 150 },
    });
  });

@@ -0,0 +1,380 @@
+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,
+  snapshotViewportRect,
+} from "../geometry/coordinate-types";
+import { GeometryContext } 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 { 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("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, { 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, { 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" },
+      { 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 }, { x: 0, y: 0 })).toBeNull();
+    expect(snapshotViewportRect([0, 0, 10, 40], { target }, { 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" },
+      { 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 { 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,
+    });
+  });
+});
@@ -7,12 +7,10 @@ import {
  handleHover,
  handlePress,
  handleSelect,
-  handleType,
  modifiersBitfield,
  parseKeySpec,
  resolveKeyDescriptor,
 } from "../interaction";
-import { captureSurfaceEnvironment } from "../surface-target";

 function fakeAgentWindow(ids: number[]) {
  let i = 0;
@@ -23,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -35,15 +33,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
    if (!h && method === "Page.getLayoutMetrics") {
      return { cssLayoutViewport: { clientWidth: 1280, clientHeight: 720 } };
    }
-    if (
-      !h &&
-      method === "Runtime.evaluate" &&
-      String((params as { expression?: string })?.expression ?? "").includes(
-        "bsk-focus-target-probe",
-      )
-    ) {
-      return { result: { value: { hasFocus: true, activeTag: "input" } } };
-    }
    if (!h) throw new Error(`unexpected CDP call ${method}`);
    return h(params);
  };
@@ -55,10 +44,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
      params?: object,
    ) => Promise<T>,
    trackSessionTab: vi.fn(),
-    getFrameGraph: vi.fn(async (tabId) => ({
-      rootFrameId: "main",
-      frames: [{ frameId: "main", target: { tabId } }],
-    })),
  };
  const tabsApi = {
    get: vi.fn(
@@ -69,84 +54,6 @@ function makeFakeCdp(handlers: Record<string, (params: unknown) => unknown>) {
  return { cdp, tabsApi, sent };
 }

-function fillRuntimeReadback(value: string) {
-  return (params: unknown) => {
-    const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-    if (fn.includes("bsk-editable-state")) {
-      return {
-        result: {
-          value: {
-            supported: true,
-            connected: true,
-            focused: true,
-            value,
-            kind: "input",
-          },
-        },
-      };
-    }
-    if (fn.includes("bsk-editable-selection")) {
-      return { result: { value: { selected: true } } };
-    }
-    return { result: { type: "undefined" } };
-  };
-}
-
-async function makeSurfaceClickFixture(onMouse?: (params: Record<string, unknown>) => void) {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const fake = makeFakeCdp({
-    "Page.getFrameTree": () => ({
-      frameTree: {
-        frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-      },
-    }),
-    "Page.getLayoutMetrics": () => ({
-      cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-      cssVisualViewport: {
-        clientWidth: 800,
-        clientHeight: 600,
-        pageX: 0,
-        pageY: 0,
-        scale: 1,
-      },
-    }),
-    "DOM.getContentQuads": () => ({ quads: [[10, 20, 110, 20, 110, 60, 10, 60]] }),
-    "Runtime.evaluate": () => ({
-      result: { value: { overlayHostPresent: false, overlayHostConnected: false } },
-    }),
-    "Input.dispatchMouseEvent": (params) => {
-      onMouse?.(params as Record<string, unknown>);
-      return {};
-    },
-  });
-  const environment = await captureSurfaceEnvironment(fake.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing Surface ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, fake, capture };
-}
-
 describe("modifiersBitfield", () => {
  it("matches CDP's expected bit layout", () => {
    expect(modifiersBitfield([])).toBe(0);
@@ -216,29 +123,6 @@ describe("handleClick", () => {
    expect(fake.cdp.send).not.toHaveBeenCalled();
  });

-  it("rejects screenshot-only visual surface refs before issuing CDP calls", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e3", 1234, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-    const fake = makeFakeCdp({});
-
-    const res = await handleClick(
-      sm,
-      { session_id: "aa11", ref: "@e3" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "ref_capability_denied", required_capability: "interact" },
-    });
-    expect(fake.cdp.send).not.toHaveBeenCalled();
-  });
-
  it("clicks by ref, computes the quad centre, dispatches three mouse events", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
@@ -283,74 +167,6 @@ describe("handleClick", () => {
    });
  });

-  it.each([
-    "left",
-    "middle",
-    "right",
-  ] as const)("uses the common click executor for a %s-button Surface click", async (button) => {
-    const { manager, fake, capture } = await makeSurfaceClickFixture();
-    const result = await handleClick(
-      manager,
-      {
-        session_id: "aa11",
-        ref: "@e3",
-        capture_id: capture.id,
-        image_x: 50,
-        image_y: 20,
-        button,
-        click_count: 2,
-        modifiers: ["ctrl", "shift"],
-      },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      used_ref: "e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-      x: 35,
-      y: 30,
-    });
-    const mouse = fake.sent.filter((call) => call.method === "Input.dispatchMouseEvent");
-    expect(mouse).toHaveLength(3);
-    expect(mouse[1].params).toMatchObject({
-      type: "mousePressed",
-      button,
-      clickCount: 2,
-      modifiers: 2 | 8,
-    });
-    expect(mouse[2].params).toMatchObject({
-      type: "mouseReleased",
-      button,
-      clickCount: 2,
-    });
-  });
-
-  it("consumes a Surface capture when the common click executor fails", async () => {
-    let mouseCalls = 0;
-    const { manager, fake, capture } = await makeSurfaceClickFixture((params) => {
-      mouseCalls += 1;
-      if (params.type === "mousePressed") throw new Error("input failed");
-    });
-    const params = {
-      session_id: "aa11",
-      ref: "@e3",
-      capture_id: capture.id,
-      image_x: 50,
-      image_y: 20,
-    };
-
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ code: "cdp_failed" });
-    expect(mouseCalls).toBe(2);
-    expect(
-      await handleClick(manager, params, { cdp: fake.cdp, tabsApi: fake.tabsApi }),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
  it("resolves frame refs in their CDP session and dispatches input in top coordinates", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
@@ -724,6 +540,21 @@ describe("handleHover", () => {
  });
 });

+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]) });
@@ -770,7 +601,8 @@ describe("handleFill", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": fillRuntimeReadback("hello"),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
      "Input.insertText": () => ({}),
    });
    const res = await handleFill(
@@ -784,13 +616,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, so the edit transaction prepares a
-    // replacement selection and performs a settled live-value readback.
+    // 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 replacement selection", 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 });
@@ -802,23 +633,12 @@ describe("handleFill", () => {
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-2" } }),
      "Runtime.callFunctionOn": (p) => {
-        const fn = (p as { functionDeclaration?: string }).functionDeclaration ?? "";
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "existingx",
-                kind: "textarea",
-              },
-            },
-          };
-        }
-        expect(fn).not.toMatch(/dispatchEvent|\.value\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(
@@ -827,7 +647,7 @@ describe("handleFill", () => {
      { cdp: fake.cdp, tabsApi: fake.tabsApi },
    );
    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.value_length).toBe(9);
+    expect(res.value_length).toBe(1);
  });

  it("treats contenteditable=true as fillable", async () => {
@@ -845,7 +665,8 @@ describe("handleFill", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-3" } }),
-      "Runtime.callFunctionOn": fillRuntimeReadback("rich"),
+      "Runtime.callFunctionOn": successfulFillScript,
+      "Runtime.releaseObject": () => ({}),
      "Input.insertText": () => ({}),
    });
    const res = await handleFill(
@@ -856,103 +677,7 @@ describe("handleFill", () => {
    expect("code" in res).toBe(false);
  });

-  it("routes OOPIF focus, text, DOM events, and readback through the node target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      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: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (target, method, params) => {
-      expect(target).toEqual({ tabId: 4, sessionId: "child-session" });
-      childCalls.push(method);
-      if (method === "DOM.describeNode") {
-        return { node: { backendNodeId: 77, nodeName: "INPUT", attributes: [] } };
-      }
-      if (method === "DOM.scrollIntoViewIfNeeded" || method === "DOM.focus") return {};
-      if (method === "DOM.resolveNode") return { object: { objectId: "child-input" } };
-      if (method === "Input.insertText") {
-        expect(params).toEqual({ text: "中文输入" });
-        return {};
-      }
-      if (method === "Runtime.callFunctionOn") {
-        const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "中文输入",
-                kind: "input",
-              },
-            },
-          };
-        }
-        if (fn.includes("bsk-editable-selection")) {
-          return { result: { value: { selected: true } } };
-        }
-        return { result: { type: "undefined" } };
-      }
-      throw new Error(`unexpected child call ${method}`);
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handleFill(
-      sm,
-      { session_id: "aa11", ref: "@e1", value: "中文输入" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in res) throw new Error(JSON.stringify(res));
-    expect(res.value_length).toBe(4);
-    expect(childCalls).toContain("DOM.focus");
-    expect(childCalls).toContain("Input.insertText");
-    expect(childCalls.filter((method) => method === "Runtime.callFunctionOn")).toHaveLength(4);
-    expect(fake.sent.some((call) => call.method === "Input.insertText")).toBe(false);
-  });
-
-  it("returns input_not_applied when a controlled input resets the value", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 8, { tabId: 4 });
-    const fake = makeFakeCdp({
-      "DOM.describeNode": () => ({ node: { backendNodeId: 8, nodeName: "INPUT" } }),
-      "DOM.scrollIntoViewIfNeeded": () => ({}),
-      "DOM.focus": () => ({}),
-      "DOM.resolveNode": () => ({ object: { objectId: "controlled" } }),
-      "Input.insertText": () => ({}),
-      "Runtime.callFunctionOn": fillRuntimeReadback(""),
-    });
-
-    const res = await handleFill(
-      sm,
-      { session_id: "aa11", ref: "@e1", value: "rejected" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "input_not_applied", expected_value_length: 8, actual_value_length: 0 },
-    });
-  });
-
-  it("stops before Input.insertText when abort fires after preparing replacement", async () => {
+  it("stops before Input.insertText when abort fires after clearing", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
    ctx.refStore.set("e1", 555, { tabId: 4 });
@@ -964,25 +689,8 @@ describe("handleFill", () => {
      "DOM.scrollIntoViewIfNeeded": () => ({}),
      "DOM.focus": () => ({}),
      "DOM.resolveNode": () => ({ object: { objectId: "obj-1" } }),
-      "Runtime.callFunctionOn": (params) => {
-        const fn = String((params as { functionDeclaration?: string }).functionDeclaration ?? "");
-        if (fn.includes("bsk-editable-state")) {
-          return {
-            result: {
-              value: {
-                supported: true,
-                connected: true,
-                focused: true,
-                value: "",
-                kind: "input",
-              },
-            },
-          };
-        }
-        if (fn.includes("bsk-editable-selection")) {
-          abort.abort();
-          return { result: { value: { selected: true } } };
-        }
+      "Runtime.callFunctionOn": () => {
+        abort.abort();
        return { result: { type: "undefined" } };
      },
      "Input.insertText": () => ({}),
@@ -1025,204 +733,6 @@ describe("handleFill", () => {
  });
 });

-describe("handleType", () => {
-  it("requires an explicit target mode instead of silently using focus", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({});
-
-    const missing = await handleType(
-      sm,
-      { session_id: "aa11", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-    expect(missing).toMatchObject({
-      code: "invalid_params",
-      message: expect.stringContaining("focused=true"),
-    });
-
-    const mixed = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", focused: true, text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-    expect(mixed).toMatchObject({
-      code: "invalid_params",
-      message: expect.stringContaining("not both"),
-    });
-    expect(fake.sent).toHaveLength(0);
-  });
-
-  it("routes committed IME text through the explicit OOPIF target without DOM readback", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      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: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: Array<{ method: string; params?: object }> = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method, params) => {
-      childCalls.push({ method, params });
-      if (method === "DOM.describeNode") {
-        return { node: { backendNodeId: 77, nodeName: "TEXTAREA", attributes: [] } };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "测试" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      tab_id: 4,
-      used_ref: "e1",
-      text_length: 2,
-      verification: "dispatched",
-    });
-    expect(childCalls.map((call) => call.method)).toEqual([
-      "DOM.describeNode",
-      "DOM.scrollIntoViewIfNeeded",
-      "DOM.focus",
-      "Input.dispatchKeyEvent",
-      "Input.insertText",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-    expect(childCalls.some((call) => call.method === "Runtime.callFunctionOn")).toBe(false);
-  });
-
-  it("uses the focused OOPIF only when focused mode resolves a text-entry target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "iframe", textEntry: false } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      if (method === "Runtime.evaluate") {
-        return {
-          result: { value: { hasFocus: true, activeTag: "textarea", textEntry: true } },
-        };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", focused: true, text: "A" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({ text_length: 1, verification: "dispatched" });
-    expect(childCalls).toEqual([
-      "Runtime.evaluate",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("refuses focused mode when focus is not owned by a text-entry target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "button", textEntry: false } },
-      }),
-    });
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", focused: true, text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "focus_target_unresolved", candidate_count: 0 },
-    });
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("rejects explicit non-text input controls", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, { tabId: 4 });
-    const fake = makeFakeCdp({
-      "DOM.describeNode": () => ({
-        node: { backendNodeId: 77, nodeName: "INPUT", attributes: ["type", "checkbox"] },
-      }),
-    });
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "invalid_params",
-      data: { reason: "target_not_fillable" },
-    });
-    expect(fake.sent.some((call) => call.method.startsWith("Input."))).toBe(false);
-  });
-
-  it("rejects a Surface ref instead of treating it as a text target", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 77, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-    const fake = makeFakeCdp({});
-
-    const result = await handleType(
-      sm,
-      { session_id: "aa11", ref: "@e1", text: "x" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(result).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "ref_capability_denied", required_capability: "interact" },
-    });
-  });
-});
-
 describe("parseKeySpec", () => {
  it("splits compound expressions into modifiers + base key", () => {
    expect(parseKeySpec("Ctrl+A")).toEqual({ key: "A", modifiers: ["ctrl"] });
@@ -1361,125 +871,6 @@ describe("handlePress", () => {
    expect(res.key).toBe("Enter");
  });

-  it("routes ref-targeted key events through the OOPIF session", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e1", 555, {
-      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: 12,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "Enter", ref: "@e1" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expectPressOk(res);
-    expect(childCalls).toEqual([
-      "DOM.scrollIntoViewIfNeeded",
-      "DOM.focus",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.some((call) => call.method === "Input.dispatchKeyEvent")).toBe(false);
-  });
-
-  it("routes an untargeted press to the uniquely focused OOPIF session", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "iframe" } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child-frame",
-          parentFrameId: "main",
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    }));
-    const childCalls: string[] = [];
-    fake.cdp.sendToTarget = vi.fn(async (_target, method) => {
-      childCalls.push(method);
-      if (method === "Runtime.evaluate") {
-        return { result: { value: { hasFocus: true, activeTag: "textarea" } } };
-      }
-      return {};
-    }) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "a" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expectPressOk(res);
-    expect(childCalls).toEqual([
-      "Runtime.evaluate",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-  });
-
-  it("refuses an untargeted press when focus ownership is ambiguous", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const fake = makeFakeCdp({
-      "Runtime.evaluate": () => ({
-        result: { value: { hasFocus: true, activeTag: "input" } },
-      }),
-    });
-    fake.cdp.getFrameGraph = vi.fn(async () => ({
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        { frameId: "child", target: { tabId: 4, sessionId: "child-session" } },
-      ],
-    }));
-    fake.cdp.sendToTarget = vi.fn(async () => ({
-      result: { value: { hasFocus: true, activeTag: "textarea" } },
-    })) as CdpRunner["sendToTarget"];
-
-    const res = await handlePress(
-      sm,
-      { session_id: "aa11", key: "Enter" },
-      { cdp: fake.cdp, tabsApi: fake.tabsApi },
-    );
-
-    expect(res).toMatchObject({
-      code: "cdp_failed",
-      data: { reason: "focus_target_unresolved", candidate_count: 2 },
-    });
-    expect(fake.sent.some((call) => call.method === "Input.dispatchKeyEvent")).toBe(false);
-  });
-
  it("stops before focus when abort fires after press scroll", async () => {
    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
    const ctx = await sm.start("aa11");
@@ -1,119 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { dispatchMouseClick } from "../mouse-input";
-import type { CdpRunner } from "../shared";
-
-function fakeCdp(onSend?: (method: string, params: Record<string, unknown>) => void): {
-  cdp: CdpRunner;
-  events: Record<string, unknown>[];
-} {
-  const events: Record<string, unknown>[] = [];
-  return {
-    events,
-    cdp: {
-      send: vi.fn(async (_tabId, method, params) => {
-        const event = params as Record<string, unknown>;
-        events.push(event);
-        onSend?.(method, event);
-        return {} as never;
-      }),
-    },
-  };
-}
-
-describe("dispatchMouseClick", () => {
-  it("emits one move, press, and release sequence", async () => {
-    const { cdp, events } = fakeCdp();
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 12, y: 34 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("completed");
-
-    expect(events).toEqual([
-      {
-        type: "mouseMoved",
-        x: 12,
-        y: 34,
-        modifiers: 0,
-      },
-      {
-        type: "mousePressed",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-      {
-        type: "mouseReleased",
-        x: 12,
-        y: 34,
-        button: "left",
-        clickCount: 1,
-        modifiers: 0,
-      },
-    ]);
-  });
-
-  it("releases a pressed button when cancellation arrives", async () => {
-    const controller = new AbortController();
-    const { cdp, events } = fakeCdp((_method, event) => {
-      if (event.type === "mousePressed") controller.abort();
-    });
-
-    expect(
-      await dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          signal: controller.signal,
-          moveSettleMs: 0,
-        },
-      ),
-    ).toBe("cancelled");
-    expect(events.at(-1)).toMatchObject({ type: "mouseReleased" });
-  });
-
-  it("settles pointer-move hit testing before pressing", async () => {
-    vi.useFakeTimers();
-    try {
-      const { cdp, events } = fakeCdp();
-      const click = dispatchMouseClick(
-        cdp,
-        4,
-        { x: 1, y: 2 },
-        {
-          button: "left",
-          clickCount: 1,
-          modifiers: 0,
-          moveSettleMs: 32,
-        },
-      );
-
-      await vi.advanceTimersByTimeAsync(31);
-      expect(events.map((event) => event.type)).toEqual(["mouseMoved"]);
-      await vi.advanceTimersByTimeAsync(1);
-      await click;
-      expect(events.map((event) => event.type)).toEqual([
-        "mouseMoved",
-        "mousePressed",
-        "mouseReleased",
-      ]);
-    } finally {
-      vi.useRealTimers();
-    }
-  });
-});
@@ -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();
+  });
+});
@@ -21,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -1,8 +1,26 @@
 import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import { handleSessionStop } from "../session";
+import type { ChromeTabsApi } from "../shared";
 import { type AgentOverlayResetApi, type ChromeWindowsApi, type TabMutationApi } from "../tabs";

+/** Build a read-only query api over a FakeState. */
+function makeQuery(state: FakeState): ChromeTabsApi {
+  return {
+    get: vi.fn(async (id) => {
+      const t = state.tabs.get(id);
+      if (!t) throw new Error(`tab ${id} not found`);
+      return t;
+    }),
+    query: vi.fn(async (q: chrome.tabs.QueryInfo) => {
+      const w = q.windowId;
+      return Array.from(state.tabs.values()).filter(
+        (t) => typeof w !== "number" || t.windowId === w,
+      );
+    }),
+  };
+}
+
 function fakeAgentWindow(ids: number[]) {
  let i = 0;
  const create = vi.fn(async () => {
@@ -11,7 +29,7 @@ function fakeAgentWindow(ids: number[]) {
    return id;
  });
  const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => {});
+  const ensureActiveTab = vi.fn(async () => 0);
  return { create, remove, ensureActiveTab };
 }

@@ -30,7 +48,9 @@ function makeApis(
 } {
  const tabs: TabMutationApi = {
    create: vi.fn(),
-    remove: vi.fn(async () => {}),
+    remove: vi.fn(async (id: number) => {
+      state.tabs.delete(id);
+    }),
    update: vi.fn(async (_id, _p) => undefined),
    get: vi.fn(async (id) => {
      const t = state.tabs.get(id);
@@ -237,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]);
@@ -249,26 +273,17 @@ 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();
  });

-  it("clears refs and Surface captures before window teardown", async () => {
+  it("clears the RefStore before window teardown", async () => {
    const aw = fakeAgentWindow([100]);
    const sm = new SessionManager({ agentWindow: aw });
    const ctx = await sm.start("aa11");
    // Insert a fake ref so we can verify clear() ran.
    ctx.refStore.set("e1", 123, { tabId: 7 });
-    ctx.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 7,
-      navigationIdentity: "navigation",
-      surface: { ref: "e1", backendNodeId: 123, observationGeneration: 0 },
-      topViewportRect: { x: 0, y: 0, w: 100, h: 50 },
-      imageWidth: 100,
-      imageHeight: 50,
-      viewportSignature: "viewport",
-      frameProjectionSignature: "frame",
-    });
    const state: FakeState = {
      tabs: new Map(),
      windowsClosed: new Set(),
@@ -277,6 +292,276 @@ describe("handleSessionStop with auto-return", () => {
    const { tabs, windows } = makeApis(state);
    await handleSessionStop(sm, { session_id: "aa11" }, { tabManagement: { tabs, windows } });
    expect(ctx.refStore.isEmpty()).toBe(true);
-    expect(ctx.surfaceCaptures.size()).toBe(0);
+  });
+
+  it.each([
+    "before teardown",
+    "during its return",
+    "after its return failed",
+    "before its turn in the return loop",
+  ])("finishes stopping when a borrowed tab closes %s", async (timing) => {
+    const aw = fakeAgentWindow([100]);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.borrowedTabs.set(1, { tabId: 1, originalWindowId: 200, originalIndex: 0 });
+    ctx.borrowedTabs.set(2, { tabId: 2, originalWindowId: 200, originalIndex: 1 });
+    const state: FakeState = {
+      tabs: new Map([
+        [1, { id: 1, windowId: 100 } as chrome.tabs.Tab],
+        [2, { id: 2, windowId: 100 } as chrome.tabs.Tab],
+      ]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    const cdp = { detachSession: vi.fn(async () => {}) };
+    const closeTab = (tabId: number) => {
+      state.tabs.delete(tabId);
+      sm.forgetClosedTab(tabId);
+    };
+    const baseMove = tabs.move;
+    tabs.move = vi.fn(async (tabId, props) => {
+      if (tabId === 1 && timing === "during its return") closeTab(1);
+      if (tabId === 1 && timing === "after its return failed") {
+        throw new Error("simulated move failure");
+      }
+      if (tabId === 2 && timing === "after its return failed") closeTab(1);
+      if (tabId === 1 && timing === "before its turn in the return loop") closeTab(2);
+      if (!state.tabs.has(tabId)) throw new Error(`tab ${tabId} not found`);
+      return baseMove(tabId, props);
+    });
+    if (timing === "before teardown") closeTab(1);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      {
+        cdp,
+        tabManagement: {
+          tabs,
+          windows,
+          agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
+        },
+        tabsQuery: makeQuery(state),
+      },
+    );
+
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    const closedTabId = timing === "before its turn in the return loop" ? 2 : 1;
+    expect(res.returned_tab_ids).toEqual([closedTabId === 1 ? 2 : 1]);
+    expect(res.return_failures).toBeUndefined();
+    expect(ctx.borrowedTabs.size).toBe(0);
+    expect(sm.has("aa11")).toBe(false);
+    expect(cdp.detachSession).toHaveBeenCalledWith("aa11");
+    expect(aw.remove).toHaveBeenCalledWith(100);
+    if (timing === "before teardown" || timing === "before its turn in the return loop") {
+      expect(tabs.move).not.toHaveBeenCalledWith(closedTabId, expect.anything());
+    }
+  });
+});
+
+describe("handleSessionStop window release (issue #57)", () => {
+  const agentWindowId = 100;
+
+  it("releases the window when user-created tabs remain", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    // ensureActiveTab returns the home tab id (10). We override the fake to
+    // return a known id.
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11);
+    ctx.agentCreatedTabs.add(12);
+    // user tab 99 (created via Chrome UI, NOT in agentCreatedTabs)
+    const state: FakeState = {
+      tabs: new Map([
+        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
+        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
+        [12, { id: 12, windowId: agentWindowId } as chrome.tabs.Tab],
+        [99, { id: 99, windowId: agentWindowId } as chrome.tabs.Tab],
+      ]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    const query = makeQuery(state);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows }, tabsQuery: query },
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res.window_released).toBe(true);
+    // agent tabs + home removed, user tab 99 kept
+    expect((tabs.remove as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]).sort()).toEqual([
+      10, 11, 12,
+    ]);
+    expect(state.tabs.has(99)).toBe(true);
+    // window released (dropOnly), not closed
+    expect(aw.remove).not.toHaveBeenCalled();
+    expect(sm.has("aa11")).toBe(false);
+  });
+
+  it("closes the window (not release) when no user tabs remain", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11);
+    const state: FakeState = {
+      tabs: new Map([
+        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
+        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
+      ]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    const query = makeQuery(state);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows }, tabsQuery: query },
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res.window_released).toBeFalsy();
+    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
+    expect(sm.has("aa11")).toBe(false);
+  });
+
+  it("is non-fatal when an agent tab is already gone", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11); // no longer in state → remove throws
+    const state: FakeState = {
+      tabs: new Map([[10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab]]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
+      if (id === 11) throw new Error("tab 11 already closed");
+      state.tabs.delete(id); // home (10) removed normally
+    });
+    const query = makeQuery(state);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows }, tabsQuery: query },
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    // user tab 10? no — 10 is home, removed. window would be empty → close.
+    expect(res.window_released).toBeFalsy();
+    expect(aw.remove).toHaveBeenCalled();
+  });
+
+  it("degrades to close-window when tabsQuery is missing", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11);
+    const state: FakeState = {
+      tabs: new Map([
+        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
+        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
+      ]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows } }, // no tabsQuery
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    // No query available → conservatively close the window.
+    expect(res.window_released).toBeFalsy();
+    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
+  });
+
+  it("degrades to close-window when tabsQuery.query throws", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11);
+    const state: FakeState = {
+      tabs: new Map([[11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab]]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    const query = makeQuery(state);
+    (query.query as ReturnType<typeof vi.fn>).mockImplementation(async () => {
+      throw new Error("query failed");
+    });
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows }, tabsQuery: query },
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    expect(res.window_released).toBeFalsy();
+    expect(aw.remove).toHaveBeenCalled();
+  });
+
+  it("tracks agentCreatedTabs across tab_create / tab_close", async () => {
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    // Simulate handleTabCreate adding, then handleTabClose removing.
+    ctx.agentCreatedTabs.add(11);
+    expect(ctx.agentCreatedTabs.has(11)).toBe(true);
+    ctx.agentCreatedTabs.delete(11); // as handleTabClose does on success
+    expect(ctx.agentCreatedTabs.has(11)).toBe(false);
+    // Unknown id delete is a safe no-op (user-closed tab).
+    expect(() => ctx.agentCreatedTabs.delete(999)).not.toThrow();
+  });
+
+  it("closes the window (not release) when an agent tab fails to close", async () => {
+    // Regression: a leaked agent tab (still in agentCreatedTabs, but
+    // still present because Step 4 remove() threw) must NOT be mistaken
+    // for a user tab. Otherwise the window would be released (dropOnly)
+    // and the agent tab would leak (issue #57 regression).
+    const aw = fakeAgentWindow([agentWindowId]);
+    aw.ensureActiveTab = vi.fn(async () => 10);
+    const sm = new SessionManager({ agentWindow: aw });
+    const ctx = await sm.start("aa11");
+    ctx.agentCreatedTabs.add(11); // Step 4 remove() will throw for this tab
+    const state: FakeState = {
+      tabs: new Map([
+        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
+        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
+      ]),
+      windowsClosed: new Set(),
+      moves: [],
+    };
+    const { tabs, windows } = makeApis(state);
+    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
+      if (id === 11) throw new Error("tab 11 failed to close");
+      state.tabs.delete(id); // home (10) removed normally; 11 lingers
+    });
+    const query = makeQuery(state);
+
+    const res = await handleSessionStop(
+      sm,
+      { session_id: "aa11" },
+      { tabManagement: { tabs, windows }, tabsQuery: query },
+    );
+    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
+    // The leaked agent tab must NOT keep the window open.
+    expect(res.window_released).toBeFalsy();
+    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
+    expect(sm.has("aa11")).toBe(false);
  });
 });
@@ -12,7 +12,7 @@ function fakeAgentWindow() {
  return {
    create: vi.fn(async () => 100),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    },
    remove: async () => {},
-    ensureActiveTab: async () => {},
+    ensureActiveTab: async () => 1,
  };
 }

@@ -24,16 +24,10 @@ describe("lookupSnapshotRef", () => {
    expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual({
      backendNodeId: 1234,
      refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
    });
    expect(lookupSnapshotRef(ctx, "e3", 4)).toEqual({
      backendNodeId: 1234,
      refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
    });
  });

@@ -59,8 +53,6 @@ describe("resolveSnapshotRef", () => {
      tabId: 4,
      frameId: "child-frame",
      cdpSessionId: "child-session",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
    });

    const expected = {
@@ -68,9 +60,6 @@ describe("resolveSnapshotRef", () => {
      refKey: "e3",
      frameId: "child-frame",
      cdpSessionId: "child-session",
-      kind: "dom" as const,
-      capabilities: ["interact", "screenshot"] as const,
-      generation: 0,
    };
    expect(lookupSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
    expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual(expected);
@@ -116,29 +105,6 @@ describe("resolveSnapshotRef", () => {
    expect(resolveSnapshotRef(ctx, "@e3", 4)).toEqual({
      backendNodeId: 1234,
      refKey: "e3",
-      kind: "dom",
-      capabilities: ["interact", "screenshot"],
-      generation: 0,
-    });
-  });
-
-  it("rejects an operation outside the ref's declared capabilities", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    ctx.refStore.set("e3", 1234, {
-      tabId: 4,
-      kind: "surface",
-      capabilities: ["screenshot"],
-    });
-
-    expect(resolveSnapshotRef(ctx, "@e3", 4, "interact")).toMatchObject({
-      code: "permission_denied",
-      message: "ref @e3 does not support interact",
-      data: {
-        reason: "ref_capability_denied",
-        required_capability: "interact",
-        kind: "surface",
-      },
    });
  });
 });
@@ -1,52 +0,0 @@
-import { describe, expect, it } from "vitest";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "../surface-coordinate";
-
-describe("surface coordinate mapping", () => {
-  it("maps capture image pixels through the actual screenshot dimensions", () => {
-    expect(mapImagePointToViewport({ x: 100, y: 50, w: 400, h: 200 }, 800, 400, 200, 100)).toEqual({
-      x: 200,
-      y: 100,
-    });
-  });
-
-  it("rejects invalid image coordinates and dimensions", () => {
-    const rect = { x: 0, y: 0, w: 100, h: 50 };
-    expect(mapImagePointToViewport(rect, 100, 50, -1, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 100, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, 0, 50)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.NaN, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 100, 50, Number.POSITIVE_INFINITY, 0)).toBeNull();
-    expect(mapImagePointToViewport(rect, 0, 50, 0, 0)).toBeNull();
-  });
-
-  it("intersects live and observed visible regions and compares them strictly", () => {
-    const clipped = surfaceVisibleRect(
-      { x: 0, y: 0, width: 200, height: 100 },
-      { x: 25, y: 30, w: 50, h: 40 },
-    );
-    expect(clipped).toEqual({ x: 25, y: 30, w: 50, h: 40 });
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 25, y: 30, w: 50, h: 40 })).toBe(
-      true,
-    );
-    expect(sameRect(clipped as NonNullable<typeof clipped>, { x: 26, y: 30, w: 50, h: 40 })).toBe(
-      false,
-    );
-  });
-
-  it("checks the projected visible region rather than only its bounding box", () => {
-    const triangle = [
-      [
-        { x: 0, y: 0 },
-        { x: 100, y: 0 },
-        { x: 0, y: 100 },
-      ],
-    ];
-    expect(pointInRegion({ x: 20, y: 20 }, triangle)).toBe(true);
-    expect(pointInRegion({ x: 90, y: 90 }, triangle)).toBe(false);
-  });
-});
@@ -1,306 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { SessionManager } from "@/session-manager/manager";
-import type { CdpRunner } from "../shared";
-import {
-  captureSurfaceEnvironment,
-  resolveSurfacePointerTarget,
-  SURFACE_POINTER_MOVE_SETTLE_MS,
-} from "../surface-target";
-
-function fakeAgentWindow() {
-  return {
-    create: vi.fn(async () => 100),
-    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
-  };
-}
-
-function fakeBrowser() {
-  let loaderId = "loader-1";
-  let pageY = 0;
-  let quad = [10, 20, 110, 20, 110, 60, 10, 60];
-  const sent: Array<{ method: string; params?: object }> = [];
-  const cdp: CdpRunner = {
-    send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-      sent.push({ method, params });
-      if (method === "Page.getFrameTree") {
-        return {
-          frameTree: { frame: { id: "main", loaderId, url: "https://fixture.test/" } },
-        } as never;
-      }
-      if (method === "Page.getLayoutMetrics") {
-        return {
-          cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY },
-          cssVisualViewport: {
-            clientWidth: 800,
-            clientHeight: 600,
-            pageX: 0,
-            pageY,
-            scale: 1,
-          },
-        } as never;
-      }
-      if (method === "DOM.getContentQuads") return { quads: [quad] } as never;
-      throw new Error(`unexpected CDP call ${method}`);
-    }) as CdpRunner["send"],
-    trackSessionTab: vi.fn(),
-  };
-  return {
-    cdp,
-    sent,
-    setLoaderId: (value: string) => {
-      loaderId = value;
-    },
-    setPageY: (value: number) => {
-      pageY = value;
-    },
-    setQuad: (value: number[]) => {
-      quad = value;
-    },
-  };
-}
-
-async function setupCapture() {
-  const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-  const context = await manager.start("aa11");
-  context.refStore.set("e3", 99, {
-    tabId: 4,
-    kind: "surface",
-    visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-  });
-  const browser = fakeBrowser();
-  const environment = await captureSurfaceEnvironment(browser.cdp, 4, undefined);
-  if ("code" in environment) throw new Error(environment.message);
-  const entry = context.refStore.resolveEntry("e3");
-  if (!entry) throw new Error("missing ref");
-  const capture = context.surfaceCaptures.create({
-    sessionId: "aa11",
-    tabId: 4,
-    navigationIdentity: environment.navigationIdentity,
-    surface: {
-      ref: "e3",
-      backendNodeId: 99,
-      observationGeneration: entry.generation,
-    },
-    topViewportRect: { x: 10, y: 20, w: 100, h: 40 },
-    imageWidth: 200,
-    imageHeight: 80,
-    viewportSignature: environment.viewportSignature,
-    frameProjectionSignature: environment.frameProjectionSignature,
-  });
-  return { manager, context, browser, capture };
-}
-
-function pointParams(captureId: string) {
-  return {
-    ref: "@e3",
-    captureId,
-    imageX: 50,
-    imageY: 20,
-  };
-}
-
-describe("Surface screenshot-bound pointer target", () => {
-  it("maps one fresh capture coordinate without executing an action", async () => {
-    const { context, browser, capture } = await setupCapture();
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({
-      usedRef: "e3",
-      point: { x: 35, y: 30 },
-      moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-      capture: { id: capture.id, imageX: 50, imageY: 20 },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-
-    const repeated = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(repeated).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_consumed" },
-    });
-  });
-
-  it("rejects a new observation generation before sending input", async () => {
-    const { context, browser, capture } = await setupCapture();
-    context.refStore.replace([
-      [
-        "e3",
-        {
-          backendNodeId: 99,
-          tabId: 4,
-          kind: "surface" as const,
-          visibleRect: { x: 10, y: 20, w: 100, h: 40 },
-        },
-      ],
-    ]);
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      pointParams(capture.id),
-      { cdp: browser.cdp },
-    );
-    expect(result).toMatchObject({
-      code: "permission_denied",
-      data: { reason: "surface_capture_stale" },
-    });
-    expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-
-  it("rejects navigation, scroll, and visible geometry changes", async () => {
-    for (const mutate of [
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setLoaderId("loader-2"),
-      (browser: ReturnType<typeof fakeBrowser>) => browser.setPageY(20),
-      (browser: ReturnType<typeof fakeBrowser>) =>
-        browser.setQuad([11, 20, 111, 20, 111, 60, 11, 60]),
-    ]) {
-      const { context, browser, capture } = await setupCapture();
-      mutate(browser);
-      const result = await resolveSurfacePointerTarget(
-        context,
-        { tabId: 4 },
-        pointParams(capture.id),
-        { cdp: browser.cdp },
-      );
-      expect(result).toMatchObject({
-        code: "permission_denied",
-        data: { reason: "surface_capture_stale" },
-      });
-      expect(browser.sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-    }
-  });
-
-  it("consumes the capture when coordinate validation fails", async () => {
-    const invalid = await setupCapture();
-    const outside = await resolveSurfacePointerTarget(
-      invalid.context,
-      { tabId: 4 },
-      { ...pointParams(invalid.capture.id), imageX: 200 },
-      { cdp: invalid.browser.cdp },
-    );
-    expect(outside).toMatchObject({
-      code: "invalid_params",
-      data: { reason: "surface_coordinate_invalid" },
-    });
-    expect(
-      await resolveSurfacePointerTarget(
-        invalid.context,
-        { tabId: 4 },
-        pointParams(invalid.capture.id),
-        { cdp: invalid.browser.cdp },
-      ),
-    ).toMatchObject({ data: { reason: "surface_capture_consumed" } });
-  });
-
-  it("maps image coordinates through an OOPIF frame projection", async () => {
-    const manager = new SessionManager({ agentWindow: fakeAgentWindow() });
-    const context = await manager.start("aa11");
-    context.refStore.set("e3", 99, {
-      tabId: 4,
-      frameId: "child",
-      cdpSessionId: "child-session",
-      kind: "surface",
-      visibleRect: { x: 120, y: 110, w: 100, h: 40 },
-    });
-    const graph = {
-      rootFrameId: "main",
-      frames: [
-        { frameId: "main", target: { tabId: 4 } },
-        {
-          frameId: "child",
-          parentFrameId: "main",
-          ownerBackendNodeId: 77,
-          target: { tabId: 4, sessionId: "child-session" },
-        },
-      ],
-    };
-    const sent: Array<{ method: string; params?: object }> = [];
-    const cdp: CdpRunner = {
-      send: vi.fn(async (_tabId: number, method: string, params?: object) => {
-        sent.push({ method, params });
-        if (method === "Page.getFrameTree") {
-          return {
-            frameTree: {
-              frame: { id: "main", loaderId: "loader-1", url: "https://fixture.test/" },
-            },
-          } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return {
-            cssLayoutViewport: { clientWidth: 800, clientHeight: 600, pageX: 0, pageY: 0 },
-            cssVisualViewport: {
-              clientWidth: 800,
-              clientHeight: 600,
-              pageX: 0,
-              pageY: 0,
-              scale: 1,
-            },
-          } as never;
-        }
-        if (method === "DOM.getBoxModel") {
-          return { model: { content: [100, 100, 300, 100, 300, 200, 100, 200] } } as never;
-        }
-        if (method === "Input.dispatchMouseEvent") return {} as never;
-        throw new Error(`unexpected root CDP call ${method}`);
-      }) as CdpRunner["send"],
-      sendToTarget: vi.fn(async (_target, method) => {
-        if (method === "DOM.getContentQuads") {
-          return { quads: [[20, 10, 120, 10, 120, 50, 20, 50]] } as never;
-        }
-        if (method === "Page.getLayoutMetrics") {
-          return { cssLayoutViewport: { clientWidth: 200, clientHeight: 100 } } as never;
-        }
-        throw new Error(`unexpected child CDP call ${method}`);
-      }) as CdpRunner["sendToTarget"],
-      getFrameGraph: vi.fn(async () => graph),
-      trackSessionTab: vi.fn(),
-    };
-    const environment = await captureSurfaceEnvironment(cdp, 4, "child");
-    if ("code" in environment) throw new Error(environment.message);
-    const entry = context.refStore.resolveEntry("e3");
-    if (!entry) throw new Error("missing ref");
-    const capture = context.surfaceCaptures.create({
-      sessionId: "aa11",
-      tabId: 4,
-      navigationIdentity: environment.navigationIdentity,
-      surface: {
-        ref: "e3",
-        frameId: "child",
-        backendNodeId: 99,
-        observationGeneration: entry.generation,
-      },
-      topViewportRect: { x: 120, y: 110, w: 100, h: 40 },
-      imageWidth: 200,
-      imageHeight: 80,
-      viewportSignature: environment.viewportSignature,
-      frameProjectionSignature: environment.frameProjectionSignature,
-    });
-
-    const result = await resolveSurfacePointerTarget(
-      context,
-      { tabId: 4 },
-      {
-        ref: "@e3",
-        captureId: capture.id,
-        imageX: 100,
-        imageY: 40,
-      },
-      { cdp },
-    );
-
-    if ("code" in result) throw new Error(JSON.stringify(result));
-    expect(result).toMatchObject({ point: { x: 170, y: 130 } });
-    expect(sent.some((call) => call.method === "Input.dispatchMouseEvent")).toBe(false);
-  });
-});
@@ -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,
@@ -23,7 +25,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -221,6 +223,7 @@ describe("handleTabCreate", () => {
      active: true,
    });
    expect(res).toMatchObject({ tab_id: 10, window_id: 100 });
+    expect(sm.get("aa11")?.agentCreatedTabs.has(10)).toBe(true);
  });

  it("forwards explicit url + index + active=false", async () => {
@@ -256,6 +259,41 @@ describe("handleTabCreate", () => {
    const res = await handleTabCreate(sm, { session_id: "aa11", index: -1 }, { tabs: api });
    expect(res).toMatchObject({ code: "invalid_params" });
  });
+
+  it("does not claim any tab when chrome.tabs.create fails", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    await sm.start("aa11");
+    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
+    const { api, spies } = makeTabMutationApi(state);
+    spies.create.mockRejectedValueOnce(new Error("chrome.tabs.create failed"));
+
+    const res = await handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
+    expect(res).toMatchObject({ code: "protocol_error" });
+
+    expect(sm.get("aa11")?.agentCreatedTabs).toEqual(new Set([1]));
+  });
+
+  it("claims the returned id even when a user tab appears during tab creation", async () => {
+    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
+    const ctx = await sm.start("aa11");
+    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
+    const { api, spies } = makeTabMutationApi(state);
+    let resolveCreate!: (tab: chrome.tabs.Tab) => void;
+    const createResult = new Promise<chrome.tabs.Tab>((resolve) => {
+      resolveCreate = resolve;
+    });
+    spies.create.mockImplementationOnce(() => createResult);
+
+    const pending = handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
+    // A user can create an unrelated same-window tab while Chrome is still
+    // resolving the agent request. There is no pending slot for it to steal.
+    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
+    resolveCreate({ id: 10, windowId: 100, active: true } as chrome.tabs.Tab);
+
+    await expect(pending).resolves.toMatchObject({ tab_id: 10 });
+    expect(ctx.agentCreatedTabs.has(10)).toBe(true);
+    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
+  });
 });

 describe("handleTabClose", () => {
@@ -511,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");
@@ -1,128 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import type { CdpRunner } from "../shared";
-import { dispatchTextInput } from "../text-input";
-
-function makeCdp(onSend?: (method: string, params?: object) => void) {
-  const sent: Array<{ method: string; params?: object }> = [];
-  const send = vi.fn(async <T>(_tabId: number, method: string, params?: object): Promise<T> => {
-    sent.push({ method, params });
-    onSend?.(method, params);
-    return {} as T;
-  });
-  return { cdp: { send } as CdpRunner, sent };
-}
-
-describe("dispatchTextInput", () => {
-  it("types ASCII through complete keydown, char, and keyup sequences", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "Ab");
-
-    expect(result).toBeNull();
-    expect(
-      fake.sent.map((call) => `${call.method}:${(call.params as { type?: string }).type}`),
-    ).toEqual([
-      "Input.dispatchKeyEvent:rawKeyDown",
-      "Input.dispatchKeyEvent:char",
-      "Input.dispatchKeyEvent:keyUp",
-      "Input.dispatchKeyEvent:rawKeyDown",
-      "Input.dispatchKeyEvent:char",
-      "Input.dispatchKeyEvent:keyUp",
-    ]);
-    expect(fake.sent[0].params).toMatchObject({ key: "A", code: "KeyA", modifiers: 8 });
-    expect(fake.sent[1].params).toMatchObject({ text: "A" });
-  });
-
-  it("types non-ASCII through the committed IME insertion path", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试");
-
-    expect(result).toBeNull();
-    expect(fake.sent).toEqual([
-      {
-        method: "Input.dispatchKeyEvent",
-        params: {
-          type: "rawKeyDown",
-          key: "Process",
-          code: "",
-          windowsVirtualKeyCode: 229,
-          nativeVirtualKeyCode: 229,
-          modifiers: 0,
-        },
-      },
-      { method: "Input.insertText", params: { text: "测试" } },
-      {
-        method: "Input.dispatchKeyEvent",
-        params: {
-          type: "keyUp",
-          key: "Process",
-          code: "",
-          windowsVirtualKeyCode: 229,
-          nativeVirtualKeyCode: 229,
-          modifiers: 0,
-        },
-      },
-    ]);
-  });
-
-  it("preserves text order across keyboard and IME segments", async () => {
-    const fake = makeCdp();
-
-    const result = await dispatchTextInput(fake.cdp, 4, "A测试1");
-
-    expect(result).toBeNull();
-    const meaningful = fake.sent.flatMap((call) => {
-      if (call.method === "Input.insertText") {
-        return [`ime:${(call.params as { text: string }).text}`];
-      }
-      if (
-        call.method === "Input.dispatchKeyEvent" &&
-        (call.params as { type?: string }).type === "char"
-      ) {
-        return [`key:${(call.params as { text: string }).text}`];
-      }
-      return [];
-    });
-    expect(meaningful).toEqual(["key:A", "ime:测试", "key:1"]);
-  });
-
-  it("reports cancellation observed after an accepted IME insertion", async () => {
-    const abort = new AbortController();
-    const fake = makeCdp((method) => {
-      if (method === "Input.insertText") abort.abort();
-    });
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试", abort.signal);
-
-    expect(result).toMatchObject({ code: "cancelled" });
-    expect(fake.sent.map((call) => call.method)).toEqual([
-      "Input.dispatchKeyEvent",
-      "Input.insertText",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent.at(-1)?.params).toMatchObject({ type: "keyUp", key: "Process" });
-  });
-
-  it("releases the IME process key without committing when cancellation follows keydown", async () => {
-    const abort = new AbortController();
-    const fake = makeCdp((method, params) => {
-      if (
-        method === "Input.dispatchKeyEvent" &&
-        (params as { type?: string }).type === "rawKeyDown"
-      ) {
-        abort.abort();
-      }
-    });
-
-    const result = await dispatchTextInput(fake.cdp, 4, "测试", abort.signal);
-
-    expect(result).toMatchObject({ code: "cancelled" });
-    expect(fake.sent.map((call) => call.method)).toEqual([
-      "Input.dispatchKeyEvent",
-      "Input.dispatchKeyEvent",
-    ]);
-    expect(fake.sent[0].params).toMatchObject({ type: "rawKeyDown", key: "Process" });
-    expect(fake.sent[1].params).toMatchObject({ type: "keyUp", key: "Process" });
-  });
-});
@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
      return id;
    }),
    remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => {}),
+    ensureActiveTab: vi.fn(async () => 1),
  };
 }

@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
    return id;
  });
  const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => {});
+  const ensureActiveTab = vi.fn(async () => 1);
  return { create, remove, ensureActiveTab };
 }

@@ -24,7 +24,7 @@ export interface BorrowResponseMessage {
  allowed: boolean;
 }

-export const CONFIRMATION_TIMEOUT_MS = 5000;
+export const CONFIRMATION_TIMEOUT_MS = 60_000;
 const EXIT_ANIMATION_MS = 150;
 /** Matches BorrowConfirmationOverlay progress ring/bar transition (duration-1000). */
 export const PROGRESS_TRANSITION_MS = 1000;
@@ -480,6 +480,13 @@ export async function requestBorrowConfirmation(
      settle(false);
    }, BACKGROUND_TIMEOUT_MS);

+    // Bring the user window to the front so the overlay is visible even
+    // when the Agent Window has stolen focus. This is fire-and-forget: if
+    // it fails the overlay / OS notification still give the user a path.
+    void windowsApi.update(notificationAnchor.windowId, { focused: true }).catch((err) => {
+      console.debug("[bsk borrow] proactive focus of user window failed", err);
+    });
+
    // Surface the OS notification *before* messaging any candidate so the
    // user has a parallel signal even if every content script is missing.
    // The Allow / Deny buttons let the user authorize explicitly when the
@@ -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);
+  }
+}
@@ -4,6 +4,7 @@ import type { Transport } from "@/transport/transport";
 import type {
  ClickParams,
  ConsoleParams,
+  DownloadParams,
  EmulateParams,
  EvaluateParams,
  FillParams,
@@ -28,22 +29,17 @@ import type {
  ScreenshotParams,
  SelectParams,
  SnapshotParams,
-  TypeParams,
+  UploadParams,
  WaitForNavigationParams,
 } from "@/transport/types";
 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,
-  handleType,
-} from "./interaction";
+import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
 import {
  handleNavigate,
  handleNavigateBack,
@@ -74,6 +70,7 @@ import {
 import { chromeTabsApi, lookupSession, resolveTargetTab } from "./shared";
 import {
  type BorrowConfirmationApprover,
+  chromeTabMutationApi,
  handleTabBorrow,
  handleTabClose,
  handleTabCreate,
@@ -87,6 +84,7 @@ import {
  type TabReturnParams,
  type TabSelectParams,
 } from "./tabs";
+import { handleUpload } from "./upload";
 import { handleWaitForNavigation } from "./waits";
 import { handleWindowResize, type WindowResizeParams } from "./window";

@@ -122,6 +120,8 @@ export interface DispatcherDeps {
  onSessionsChanged?: () => void;
  /** Invoked before a tool that dispatches page input or mutates browser state is forwarded. */
  onBrowserControlResumed?: (sessionId: string) => void;
+  /** Invoked after a tab is explicitly claimed so its overlay can be refreshed immediately. */
+  onAgentTabClaimed?: (tabId: number, windowId: number) => void;
  /** User approval for `tool.tab_borrow` (overlay in content script). */
  approveBorrow?: BorrowConfirmationApprover;
  /** i18n notification copy for `tool.request_help` (resolved per-call). */
@@ -151,6 +151,7 @@ export class ToolDispatcher {
  private readonly recording?: RecordRuntimeDeps;
  private readonly onSessionsChanged?: () => void;
  private readonly onBrowserControlResumed?: (sessionId: string) => void;
+  private readonly onAgentTabClaimed?: (tabId: number, windowId: number) => void;
  private readonly approveBorrow?: BorrowConfirmationApprover;
  private readonly helpNotificationCopy?: () => { title: string; body: string };
  private subscription: { dispose(): void } | null = null;
@@ -171,6 +172,7 @@ export class ToolDispatcher {
    this.recording = deps.recording;
    this.onSessionsChanged = deps.onSessionsChanged;
    this.onBrowserControlResumed = deps.onBrowserControlResumed;
+    this.onAgentTabClaimed = deps.onAgentTabClaimed;
    this.approveBorrow = deps.approveBorrow;
    this.helpNotificationCopy = deps.helpNotificationCopy;
  }
@@ -238,7 +240,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") {
@@ -306,13 +308,25 @@ export class ToolDispatcher {
        await this.releaseHoverLatch((req.params as SessionStopParams).session_id);
        return handleSessionStop(this.sessions, req.params as SessionStopParams, {
          cdp: this.cdp,
+          // Must be wired in production: the agent-tab cleanup and the
+          // window-release decision (issue #57) read these deps directly
+          // and silently no-op when they are absent.
+          tabManagement: { tabs: chromeTabMutationApi },
+          tabsQuery: chromeTabsApi,
          signal,
        });
      }
      case "tool.tab_list":
        return handleTabList(this.sessions, req.params as TabListParams, chromeTabsApi, signal);
-      case "tool.tab_create":
-        return handleTabCreate(this.sessions, req.params as TabCreateParams, { signal });
+      case "tool.tab_create": {
+        const result = await handleTabCreate(this.sessions, req.params as TabCreateParams, {
+          signal,
+        });
+        if (!isRpcError(result)) {
+          this.onAgentTabClaimed?.(result.tab_id, result.window_id);
+        }
+        return result;
+      }
      case "tool.tab_close":
        return this.withHoverReleaseForRequest(
          req.params as TabCloseParams,
@@ -321,13 +335,22 @@ export class ToolDispatcher {
        );
      case "tool.tab_select":
        return handleTabSelect(this.sessions, req.params as TabSelectParams, { signal });
-      case "tool.tab_borrow":
-        return handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
+      case "tool.tab_borrow": {
+        const result = await handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
          signal,
          approveBorrow: this.approveBorrow,
        });
+        if (!isRpcError(result)) {
+          this.onAgentTabClaimed?.(result.tab_id, result.agent_window_id);
+        }
+        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,
@@ -391,7 +414,11 @@ export class ToolDispatcher {
                ? {
                    cdp: this.cdp,
                    tabsApi: chromeTabsCaptureApi,
-                    conditionalSurfaceProbe: !this.hasHoverLatchForScope(hoverScope),
+                    // Active hover probing is opt-in. A held hover latch still
+                    // suppresses it, because probing would move the cursor off
+                    // the element the caller is deliberately holding.
+                    conditionalSurfaceProbe:
+                      params.probe_hover === true && !this.hasHoverLatchForScope(hoverScope),
                    hoverProbeBypassOverlay: bypassOverlay,
                  }
                : undefined,
@@ -499,17 +526,6 @@ export class ToolDispatcher {
            ),
          signal,
        );
-      case "tool.type":
-        return this.withHoverReleaseForRequest(
-          req.params as TypeParams,
-          () =>
-            handleType(
-              this.sessions,
-              req.params as TypeParams,
-              this.cdp ? { cdp: this.cdp, tabsApi: chromeTabsApi, signal } : undefined,
-            ),
-          signal,
-        );
      case "tool.press":
        return this.withHoverReleaseForRequest(
          req.params as PressParams,
@@ -532,6 +548,40 @@ export class ToolDispatcher {
            ),
          signal,
        );
+      case "tool.upload":
+        return this.withHoverReleaseForRequest(
+          req.params as UploadParams,
+          () =>
+            this.cdp
+              ? handleUpload(this.sessions, req.params as UploadParams, {
+                  cdp: this.cdp,
+                  tabsApi: chromeTabsApi,
+                  signal,
+                  bypassOverlay,
+                })
+              : Promise.resolve({
+                  code: "unsupported",
+                  message: "upload requires CDP",
+                } satisfies RpcError),
+          signal,
+        );
+      case "tool.download":
+        return this.withHoverReleaseForRequest(
+          req.params as DownloadParams,
+          () =>
+            this.cdp
+              ? handleDownload(this.sessions, req.params as DownloadParams, {
+                  cdp: this.cdp,
+                  tabsApi: chromeTabsApi,
+                  signal,
+                  bypassOverlay,
+                })
+              : Promise.resolve({
+                  code: "unsupported",
+                  message: "download requires CDP",
+                } satisfies RpcError),
+          signal,
+        );
      case "tool.evaluate":
        return handleEvaluate(
          this.sessions,
@@ -736,9 +786,10 @@ function sessionIdForBrowserControlMethod(req: RequestFrame): string | null {
    case "tool.click":
    case "tool.hover":
    case "tool.fill":
-    case "tool.type":
    case "tool.press":
    case "tool.select":
+    case "tool.upload":
+    case "tool.download":
    case "tool.evaluate":
    case "tool.observe":
    case "tool.request_help":
@@ -0,0 +1,364 @@
+// Order-independent coordinator for one browser download. CDP supplies the
+// exact target/frame intent while chrome.downloads supplies the download id
+// and filename routing hook; neither event is assumed to arrive first.
+
+import type { CdpTarget } from "@/browser-driver/frame-graph";
+import type { ClickResult, RpcError, TransferEffectState } from "@/transport/types";
+import { transferError } from "./errors";
+import { type CdpRunner, isRpcError } from "./shared";
+
+const CORRELATION_GRACE_MS = 750;
+const UNIQUE_SETTLE_MS = 50;
+const SIZE_POLL_MS = 250;
+
+type DeterminingFilenameListener = (
+  item: chrome.downloads.DownloadItem,
+  suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void,
+) => void | true;
+
+interface ListenerEvent<T> {
+  addListener(listener: T): void;
+  removeListener(listener: T): void;
+}
+
+export interface DownloadsApi {
+  onCreated: ListenerEvent<(item: chrome.downloads.DownloadItem) => void>;
+  onChanged: ListenerEvent<(delta: chrome.downloads.DownloadDelta) => void>;
+  onDeterminingFilename: ListenerEvent<DeterminingFilenameListener>;
+  search(query: chrome.downloads.DownloadQuery): Promise<chrome.downloads.DownloadItem[]>;
+  cancel(downloadId: number): Promise<void>;
+  removeFile(downloadId: number): Promise<void>;
+}
+
+export const chromeDownloadsApi: DownloadsApi = {
+  get onCreated() {
+    return chrome.downloads.onCreated;
+  },
+  get onChanged() {
+    return chrome.downloads.onChanged;
+  },
+  get onDeterminingFilename() {
+    return chrome.downloads.onDeterminingFilename;
+  },
+  search: (query) => chrome.downloads.search(query),
+  cancel: (id) => chrome.downloads.cancel(id),
+  removeFile: (id) => chrome.downloads.removeFile(id),
+};
+
+export interface DownloadCaptureOptions {
+  cdp: CdpRunner;
+  target: CdpTarget;
+  expectedFrameId?: string;
+  downloads: DownloadsApi;
+  browserRelativeDir: string;
+  maxByteSize?: number;
+  timeoutMs: number;
+  signal?: AbortSignal;
+  trigger(): Promise<ClickResult | RpcError>;
+}
+
+export interface DownloadCaptureResult {
+  click: ClickResult;
+  item: chrome.downloads.DownloadItem;
+}
+
+interface DownloadIntent {
+  url: string;
+  suggestedFilename: string;
+  frameId?: string;
+}
+
+interface DownloadCandidate {
+  item: chrome.downloads.DownloadItem;
+  suggest: (suggestion?: chrome.downloads.DownloadFilenameSuggestion) => void;
+  suggested: boolean;
+  graceTimer: ReturnType<typeof setTimeout>;
+}
+
+function safeBasename(filename: string): string {
+  const basename = filename.split(/[\\/]/).pop()?.trim();
+  return basename && basename !== "." && basename !== ".." ? basename : "download";
+}
+
+function sameTarget(source: { tabId?: number; sessionId?: string }, target: CdpTarget): boolean {
+  return source.tabId === target.tabId && source.sessionId === target.sessionId;
+}
+
+function matchesIntent(item: chrome.downloads.DownloadItem, intent: DownloadIntent): boolean {
+  const urlMatches = item.url === intent.url || item.finalUrl === intent.url;
+  return urlMatches && safeBasename(item.filename) === safeBasename(intent.suggestedFilename);
+}
+
+function knownSize(item: chrome.downloads.DownloadItem): number | undefined {
+  if (item.fileSize >= 0) return item.fileSize;
+  if (item.totalBytes >= 0) return item.totalBytes;
+  return undefined;
+}
+
+function captureError(
+  message: string,
+  effectState: TransferEffectState,
+  phase: string,
+  cleanupFailed = false,
+): RpcError {
+  return transferError("cdp_failed", "download_capture_failed", message, {
+    effectState,
+    phase,
+    ...(cleanupFailed ? { cleanupState: "failed" } : {}),
+  });
+}
+
+async function cleanupClaimedDownload(downloads: DownloadsApi, downloadId: number): Promise<void> {
+  const lookup = async () => (await downloads.search({ id: downloadId }))[0];
+  const item = await lookup();
+  if (!item || item.state === "interrupted") return;
+  if (item.state === "complete") {
+    await downloads.removeFile(downloadId);
+    return;
+  }
+
+  try {
+    await downloads.cancel(downloadId);
+  } catch (cancelError) {
+    // Completion can win the race after the lookup but before cancellation.
+    // Reconcile against Chrome's authoritative state before declaring cleanup
+    // failed so every terminal state has one explicit cleanup path.
+    const reconciled = await lookup();
+    if (!reconciled || reconciled.state === "interrupted") return;
+    if (reconciled.state === "complete") {
+      await downloads.removeFile(downloadId);
+      return;
+    }
+    throw cancelError;
+  }
+}
+
+export async function captureBrowserDownload(
+  options: DownloadCaptureOptions,
+): Promise<DownloadCaptureResult | RpcError> {
+  let click: ClickResult | undefined;
+  let intent: DownloadIntent | undefined;
+  let capturedId: number | undefined;
+  let settled = false;
+  let succeeded = false;
+  let failureResult: RpcError | undefined;
+  let uniquenessTimer: ReturnType<typeof setTimeout> | undefined;
+  let operationTimer: ReturnType<typeof setTimeout> | undefined;
+  let sizePoll: ReturnType<typeof setInterval> | undefined;
+  const candidates = new Map<number, DownloadCandidate>();
+  const createdItems = new Map<number, chrome.downloads.DownloadItem>();
+
+  let resolveCompletion!: (item: chrome.downloads.DownloadItem) => void;
+  let rejectCompletion!: (error: Error) => void;
+  const completion = new Promise<chrome.downloads.DownloadItem>((resolve, reject) => {
+    resolveCompletion = resolve;
+    rejectCompletion = reject;
+  });
+  const fail = (error: Error) => {
+    if (settled) return;
+    settled = true;
+    rejectCompletion(error);
+  };
+  const complete = (item: chrome.downloads.DownloadItem) => {
+    if (settled) return;
+    const size = knownSize(item);
+    if (size !== undefined && options.maxByteSize !== undefined && size > options.maxByteSize) {
+      fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+      return;
+    }
+    settled = true;
+    resolveCompletion(item);
+  };
+  const suggestDefault = (candidate: DownloadCandidate) => {
+    if (candidate.suggested) return;
+    candidate.suggested = true;
+    candidate.suggest();
+  };
+  const matchingCandidates = (): DownloadCandidate[] => {
+    const currentIntent = intent;
+    return currentIntent
+      ? [...candidates.values()].filter(
+          (candidate) => !candidate.suggested && matchesIntent(candidate.item, currentIntent),
+        )
+      : [];
+  };
+
+  const claimUnique = () => {
+    uniquenessTimer = undefined;
+    if (settled || capturedId !== undefined || !intent) return;
+    const matches = matchingCandidates();
+    if (matches.length !== 1) {
+      if (matches.length > 1) {
+        for (const candidate of matches) suggestDefault(candidate);
+        fail(new Error("download attribution is ambiguous"));
+      }
+      return;
+    }
+    const candidate = matches[0];
+    candidate.suggested = true;
+    clearTimeout(candidate.graceTimer);
+    capturedId = candidate.item.id;
+    candidate.suggest({
+      filename: `${options.browserRelativeDir}/${safeBasename(intent.suggestedFilename)}`,
+      conflictAction: "overwrite",
+    });
+    const size = knownSize(candidate.item);
+    if (size !== undefined && options.maxByteSize !== undefined && size > options.maxByteSize) {
+      fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+      return;
+    }
+    const created = createdItems.get(candidate.item.id);
+    if (created?.state === "interrupted") {
+      fail(new Error(created.error ?? "download interrupted"));
+    } else if (created?.state === "complete") {
+      complete(created);
+    }
+  };
+  const reconcile = () => {
+    if (settled || capturedId !== undefined || !intent) return;
+    const matches = matchingCandidates();
+    if (matches.length > 1) {
+      for (const candidate of matches) suggestDefault(candidate);
+      fail(new Error("download attribution is ambiguous"));
+      return;
+    }
+    if (matches.length === 1 && !uniquenessTimer) {
+      uniquenessTimer = setTimeout(claimUnique, UNIQUE_SETTLE_MS);
+    }
+  };
+
+  const determiningListener: DeterminingFilenameListener = (item, suggest) => {
+    const candidate: DownloadCandidate = {
+      item,
+      suggest,
+      suggested: false,
+      graceTimer: setTimeout(() => {
+        suggestDefault(candidate);
+        candidates.delete(item.id);
+        if (intent && matchesIntent(item, intent) && capturedId === undefined) {
+          fail(new Error("download correlation grace elapsed before unique attribution"));
+        }
+      }, CORRELATION_GRACE_MS),
+    };
+    candidates.set(item.id, candidate);
+    reconcile();
+    return true;
+  };
+  const createdListener = (item: chrome.downloads.DownloadItem) => {
+    createdItems.set(item.id, item);
+    if (capturedId !== item.id) return;
+    if (item.state === "interrupted") {
+      fail(new Error(item.error ?? "download interrupted"));
+    } else if (item.state === "complete") {
+      complete(item);
+    }
+  };
+  const changedListener = async (delta: chrome.downloads.DownloadDelta) => {
+    if (capturedId === undefined || delta.id !== capturedId || settled) return;
+    if (delta.state?.current === "interrupted" || delta.error?.current) {
+      fail(new Error(delta.error?.current ?? "download interrupted"));
+      return;
+    }
+    if (delta.state?.current === "complete") {
+      try {
+        const [item] = await options.downloads.search({ id: delta.id });
+        if (item) complete(item);
+        else fail(new Error("completed download disappeared"));
+      } catch (err) {
+        fail(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+  };
+  const onAbort = () => fail(new DOMException("aborted", "AbortError"));
+  const cdpSubscription = options.cdp.onEvent?.((source, method, raw) => {
+    if (method !== "Page.downloadWillBegin" || !sameTarget(source, options.target)) return;
+    const event = raw as { url?: unknown; suggestedFilename?: unknown; frameId?: unknown };
+    if (typeof event.url !== "string" || typeof event.suggestedFilename !== "string") return;
+    if (options.expectedFrameId && event.frameId !== options.expectedFrameId) {
+      fail(new Error("download originated from a different frame"));
+      return;
+    }
+    if (intent) {
+      fail(new Error("download trigger produced more than one browser download intent"));
+      return;
+    }
+    intent = {
+      url: event.url,
+      suggestedFilename: event.suggestedFilename,
+      ...(typeof event.frameId === "string" ? { frameId: event.frameId } : {}),
+    };
+    reconcile();
+  });
+  if (!cdpSubscription) {
+    return captureError("CDP download intent subscription unavailable", "none", "arm");
+  }
+
+  options.downloads.onDeterminingFilename.addListener(determiningListener);
+  options.downloads.onCreated.addListener(createdListener);
+  options.downloads.onChanged.addListener(changedListener);
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  operationTimer = setTimeout(
+    () => fail(new Error("download did not complete before timeout")),
+    options.timeoutMs,
+  );
+  sizePoll = setInterval(() => {
+    if (capturedId === undefined || settled || options.maxByteSize === undefined) return;
+    void options.downloads
+      .search({ id: capturedId })
+      .then(([item]) => {
+        if (!item || settled) return;
+        if (item.bytesReceived > (options.maxByteSize as number)) {
+          fail(new Error(`download exceeds transfer limit ${options.maxByteSize}`));
+        }
+      })
+      .catch((err) => fail(err instanceof Error ? err : new Error(String(err))));
+  }, SIZE_POLL_MS);
+
+  try {
+    const triggered = await options.trigger();
+    if (isRpcError(triggered)) {
+      void completion.catch(() => undefined);
+      const effect: TransferEffectState =
+        capturedId !== undefined ? "committed" : intent ? "unknown" : "none";
+      failureResult = {
+        ...triggered,
+        data: { ...triggered.data, effect_state: effect, phase: "trigger" },
+      };
+      return failureResult;
+    }
+    click = triggered;
+    const item = await completion;
+    succeeded = true;
+    return { click, item };
+  } catch (err) {
+    const effect: TransferEffectState =
+      capturedId !== undefined ? "committed" : click ? "unknown" : "none";
+    failureResult = captureError(
+      err instanceof Error ? err.message : String(err),
+      effect,
+      capturedId !== undefined ? "download" : "attribution",
+    );
+    return failureResult;
+  } finally {
+    settled = true;
+    if (operationTimer) clearTimeout(operationTimer);
+    if (uniquenessTimer) clearTimeout(uniquenessTimer);
+    if (sizePoll) clearInterval(sizePoll);
+    options.signal?.removeEventListener("abort", onAbort);
+    options.downloads.onDeterminingFilename.removeListener(determiningListener);
+    options.downloads.onCreated.removeListener(createdListener);
+    options.downloads.onChanged.removeListener(changedListener);
+    cdpSubscription.dispose();
+    for (const candidate of candidates.values()) {
+      clearTimeout(candidate.graceTimer);
+      if (candidate.item.id !== capturedId) suggestDefault(candidate);
+    }
+    if (!succeeded && capturedId !== undefined) {
+      try {
+        await cleanupClaimedDownload(options.downloads, capturedId);
+      } catch {
+        if (failureResult?.data) failureResult.data.cleanup_state = "failed";
+      }
+    }
+  }
+}
@@ -0,0 +1,64 @@
+// Download orchestration: validate session/tab ownership, then delegate one
+// browser-global chrome.downloads transaction to download-capture.ts.
+
+import type { SessionManager } from "@/session-manager/manager";
+import type { DownloadParams, DownloadResult, RpcError } from "@/transport/types";
+import { captureBrowserDownload, chromeDownloadsApi, type DownloadsApi } from "./download-capture";
+import { clickResolvedTarget, type InteractionDeps, resolveActionTarget } from "./interaction";
+import { enforceAgentWindow, isRpcError, lookupSession, resolveTargetTab } from "./shared";
+
+let downloadActive = false;
+
+export type { DownloadsApi } from "./download-capture";
+
+export interface DownloadDeps extends InteractionDeps {
+  downloads?: DownloadsApi;
+}
+
+export async function handleDownload(
+  manager: SessionManager,
+  params: DownloadParams,
+  deps: DownloadDeps,
+): Promise<DownloadResult | RpcError> {
+  if (downloadActive) return { code: "invalid_params", message: "another bsk download is active" };
+  downloadActive = true;
+  try {
+    const ctx = lookupSession(manager, params, "download");
+    if (isRpcError(ctx)) return ctx;
+    const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+    if (isRpcError(target)) return target;
+    const denied = enforceAgentWindow(ctx, target, "download");
+    if (denied) return denied;
+    if (!params.browser_relative_dir) {
+      return { code: "invalid_params", message: "download requires a daemon capability directory" };
+    }
+    const address = await resolveActionTarget(deps.cdp, ctx, target, params, "download");
+    if (isRpcError(address)) return address;
+
+    const capture = await captureBrowserDownload({
+      cdp: deps.cdp,
+      target: address.cdpTarget,
+      downloads: deps.downloads ?? chromeDownloadsApi,
+      browserRelativeDir: params.browser_relative_dir,
+      maxByteSize: params.max_byte_size,
+      timeoutMs: params.timeout_ms ?? 120_000,
+      signal: deps.signal,
+      expectedFrameId: address.frameId,
+      trigger: () => clickResolvedTarget(ctx, address, {}, deps),
+    });
+    if (isRpcError(capture)) return capture;
+    const { click, item } = capture;
+    return {
+      tab_id: target.tabId,
+      used_ref: click.used_ref,
+      used_selector: click.used_selector,
+      suggested_filename: item.filename.split(/[\\/]/).pop() ?? "download",
+      byte_size: item.fileSize >= 0 ? item.fileSize : item.totalBytes,
+      mime: item.mime || undefined,
+      danger: item.danger,
+      browser_path: item.filename,
+    };
+  } finally {
+    downloadActive = false;
+  }
+}
@@ -1,282 +0,0 @@
-// Browser-native editing transaction for input, textarea, and contenteditable
-// targets. The CDP target/session is selected by interaction.ts; this module
-// owns the shorter-lived editable identity inside that target.
-
-import type { RpcError } from "@/transport/types";
-import { rpcError } from "./errors";
-import type { CdpRunner } from "./shared";
-
-interface EditableState {
-  supported: boolean;
-  connected: boolean;
-  focused: boolean;
-  value: string;
-  kind: "input" | "textarea" | "contenteditable" | "unsupported";
-}
-
-export interface EditableFillResult {
-  value: string;
-  replacedNode: boolean;
-}
-
-function cancelled(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted ? { code: "cancelled", message: "fill aborted" } : null;
-}
-
-async function inspectEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  objectId: string,
-): Promise<EditableState> {
-  const reply = await cdp.send<{
-    result?: { value?: EditableState };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-state */
-      const doc = this.ownerDocument;
-      const focused = !!doc && doc.activeElement === this;
-      if (this instanceof HTMLInputElement) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.value, kind: 'input' };
-      }
-      if (this instanceof HTMLTextAreaElement) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.value, kind: 'textarea' };
-      }
-      if (this.isContentEditable) {
-        return { supported: true, connected: this.isConnected, focused,
-          value: this.innerText ?? this.textContent ?? '', kind: 'contenteditable' };
-      }
-      return { supported: false, connected: this.isConnected === true, focused,
-        value: '', kind: 'unsupported' };
-    }`,
-    returnByValue: true,
-  });
-  const state = reply.result?.value;
-  if (!state || typeof state.value !== "string") {
-    throw new Error("editable state probe returned no value");
-  }
-  return state;
-}
-
-/**
- * Return the active editable from the anchor's own document. Using the
- * anchor's execution context also works for same-process nested frames, where
- * a target-level Runtime.evaluate would otherwise see the top document.
- */
-async function focusedEditableFromAnchor(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<string | null> {
-  const reply = await cdp.send<{
-    result?: { objectId?: string; subtype?: string };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId: anchorObjectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-live */
-      const active = this.ownerDocument?.activeElement;
-      if (!active) return null;
-      const editable = active instanceof HTMLInputElement ||
-        active instanceof HTMLTextAreaElement || active.isContentEditable;
-      return editable ? active : null;
-    }`,
-    returnByValue: false,
-  });
-  if (reply.result?.subtype === "null") return null;
-  return typeof reply.result?.objectId === "string" ? reply.result.objectId : null;
-}
-
-async function resolveLiveEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<{ objectId: string; state: EditableState; replaced: boolean } | RpcError> {
-  const anchor = await inspectEditable(cdp, tabId, anchorObjectId);
-  if (anchor.supported && anchor.connected && anchor.focused) {
-    return { objectId: anchorObjectId, state: anchor, replaced: false };
-  }
-
-  const focusedObjectId = await focusedEditableFromAnchor(cdp, tabId, anchorObjectId);
-  if (!focusedObjectId) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      "the target editable lost focus or detached before input",
-      { phase: "resolve_live_editable" },
-    );
-  }
-  const focused = await inspectEditable(cdp, tabId, focusedObjectId);
-  if (!focused.supported || !focused.connected || !focused.focused) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      "the replacement editable was not live and focused",
-      { phase: "resolve_live_editable" },
-    );
-  }
-  return { objectId: focusedObjectId, state: focused, replaced: true };
-}
-
-async function selectEditableContents(
-  cdp: CdpRunner,
-  tabId: number,
-  objectId: string,
-): Promise<void> {
-  const reply = await cdp.send<{
-    result?: { value?: { selected?: boolean } };
-  }>(tabId, "Runtime.callFunctionOn", {
-    objectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-selection */
-      if (!this.isConnected || this.ownerDocument?.activeElement !== this) {
-        return { selected: false };
-      }
-      if (this instanceof HTMLInputElement || this instanceof HTMLTextAreaElement) {
-        try {
-          this.setSelectionRange(0, this.value.length);
-        } catch {
-          if (typeof this.select !== 'function') return { selected: false };
-          this.select();
-        }
-        return { selected: true };
-      }
-      if (this.isContentEditable) {
-        const selection = this.ownerDocument.getSelection();
-        if (!selection) return { selected: false };
-        const range = this.ownerDocument.createRange();
-        range.selectNodeContents(this);
-        selection.removeAllRanges();
-        selection.addRange(range);
-        return { selected: true };
-      }
-      return { selected: false };
-    }`,
-    returnByValue: true,
-  });
-  if (reply.result?.value?.selected !== true) {
-    throw new Error("could not select the live editable contents");
-  }
-}
-
-async function waitForEditableSettlement(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-): Promise<void> {
-  await cdp.send(tabId, "Runtime.callFunctionOn", {
-    objectId: anchorObjectId,
-    functionDeclaration: `function() {
-      /* bsk-editable-sync */
-      return new Promise((resolve) => {
-        let settled = false;
-        const finish = () => {
-          if (settled) return;
-          settled = true;
-          clearTimeout(timer);
-          resolve();
-        };
-        const timer = setTimeout(finish, 100);
-        const view = this.ownerDocument?.defaultView;
-        if (!view || typeof view.requestAnimationFrame !== 'function') { finish(); return; }
-        view.requestAnimationFrame(() => view.requestAnimationFrame(finish));
-      });
-    }`,
-    awaitPromise: true,
-    returnByValue: true,
-  });
-}
-
-async function deleteSelection(cdp: CdpRunner, tabId: number): Promise<void> {
-  await cdp.send(tabId, "Input.dispatchKeyEvent", {
-    type: "rawKeyDown",
-    key: "Backspace",
-    code: "Backspace",
-    windowsVirtualKeyCode: 8,
-  });
-  await cdp.send(tabId, "Input.dispatchKeyEvent", {
-    type: "keyUp",
-    key: "Backspace",
-    code: "Backspace",
-    windowsVirtualKeyCode: 8,
-  });
-}
-
-/**
- * Replace or append text through Chromium's editing pipeline. No value setter
- * or synthetic DOM events are used: controlled components observe the same
- * beforeinput/input path as a real browser edit. The live editable is resolved
- * again after settlement so a framework may remount it without producing a
- * false failure or a stale-object success.
- */
-export async function fillEditable(
-  cdp: CdpRunner,
-  tabId: number,
-  anchorObjectId: string,
-  value: string,
-  clearBefore: boolean,
-  signal?: AbortSignal,
-): Promise<EditableFillResult | RpcError> {
-  try {
-    const abortedBefore = cancelled(signal);
-    if (abortedBefore) return abortedBefore;
-
-    const initial = await resolveLiveEditable(cdp, tabId, anchorObjectId);
-    if ("code" in initial) return initial;
-    let replacedNode = initial.replaced;
-
-    if (clearBefore) await selectEditableContents(cdp, tabId, initial.objectId);
-    const abortedAfterSelection = cancelled(signal);
-    if (abortedAfterSelection) return abortedAfterSelection;
-
-    if (value.length > 0) {
-      await cdp.send(tabId, "Input.insertText", { text: value });
-    } else if (clearBefore) {
-      await deleteSelection(cdp, tabId);
-    }
-
-    const abortedAfterInput = cancelled(signal);
-    if (abortedAfterInput) return abortedAfterInput;
-    await waitForEditableSettlement(cdp, tabId, initial.objectId);
-
-    const abortedAfterSettlement = cancelled(signal);
-    if (abortedAfterSettlement) return abortedAfterSettlement;
-
-    let finalObjectId = initial.objectId;
-    let finalState = await inspectEditable(cdp, tabId, finalObjectId);
-    if (!finalState.connected || !finalState.focused) {
-      const live = await resolveLiveEditable(cdp, tabId, initial.objectId);
-      if ("code" in live) return live;
-      finalObjectId = live.objectId;
-      finalState = live.state;
-      replacedNode ||= live.replaced || finalObjectId !== initial.objectId;
-    }
-
-    const applied = clearBefore
-      ? finalState.value === value
-      : value.length === 0 || finalState.value.includes(value);
-    if (!finalState.supported || !applied) {
-      return rpcError(
-        "cdp_failed",
-        "input_not_applied",
-        "the page did not retain the requested input value",
-        {
-          expected_value_length: value.length,
-          actual_value_length: finalState.value.length,
-          phase: "readback",
-          editable_replaced: replacedNode,
-        },
-      );
-    }
-
-    return { value: finalState.value, replacedNode };
-  } catch (err) {
-    return rpcError(
-      "cdp_failed",
-      "input_not_applied",
-      err instanceof Error ? err.message : String(err),
-      { phase: "edit_transaction" },
-    );
-  }
-}
@@ -2,10 +2,51 @@
 // rendering. Extension handlers attach reasons here; human-facing copy
 // lives in bsk-cli `render_error.rs`.

-import type { ErrorCode, RpcError, RpcErrorData, RpcErrorReason } from "@/transport/types";
+import type {
+  ErrorCode,
+  RpcError,
+  RpcErrorData,
+  RpcErrorReason,
+  TransferCleanupState,
+  TransferEffectState,
+} from "@/transport/types";

 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;
+  cleanupState?: TransferCleanupState;
+}
+
 export function rpcError(
  code: ErrorCode,
  reason: RpcErrorReason,
@@ -15,3 +56,16 @@ export function rpcError(
  const data: RpcErrorData = { reason, ...extra };
  return { code, message, data };
 }
+
+export function transferError(
+  code: ErrorCode,
+  reason: RpcErrorReason,
+  message: string,
+  options: TransferErrorOptions,
+): RpcError {
+  return rpcError(code, reason, message, {
+    effect_state: options.effectState,
+    phase: options.phase,
+    ...(options.cleanupState ? { cleanup_state: options.cleanupState } : {}),
+  });
+}
@@ -0,0 +1,319 @@
+// One native file-drop transaction bound to an explicit page target. CDP drag
+// events are sent to the target that owns the node: root targets use top-level
+// coordinates, while OOPIF targets require coordinates local to their session.
+
+import type { RpcError, TransferEffectState } from "@/transport/types";
+import { transferError } from "./errors";
+import { resolveNodeGeometry } from "./frame-geometry";
+import type { ResolvedActionTarget } from "./interaction";
+import { type CdpRunner, isRpcError, sendToCdpTarget } from "./shared";
+import { BoundedWaitError, waitBounded } from "./transfer-transaction";
+
+const CLEANUP_TIMEOUT_MS = 1_000;
+
+type FileDropPhase = "resolve_target" | "drag_enter" | "drag_over" | "drop" | "cleanup";
+
+interface RuntimeReply {
+  result?: { value?: unknown; objectId?: string };
+  exceptionDetails?: { text?: string; exception?: { description?: string } };
+}
+
+interface DragData {
+  items: [];
+  files: string[];
+  dragOperationsMask: number;
+}
+
+export interface FileDropTransactionOptions {
+  cdp: CdpRunner;
+  actionTarget: ResolvedActionTarget;
+  files: string[];
+  timeoutMs: number;
+  signal?: AbortSignal;
+  withOverlayHidden: <T>(operation: () => Promise<T>) => Promise<T>;
+}
+
+export interface FileDropTransactionResult {
+  x: number;
+  y: number;
+}
+
+function failure(
+  code: RpcError["code"],
+  reason: "upload_mechanism_unsupported" | "file_drop_target_unavailable" | "file_drop_failed",
+  message: string,
+  effectState: TransferEffectState,
+  phase: FileDropPhase,
+): RpcError {
+  const error = transferError(code, reason, message, { effectState, phase });
+  error.data = { ...error.data, mechanism: "drop" };
+  return error;
+}
+
+function enrichFailure(
+  error: RpcError,
+  effectState: TransferEffectState,
+  phase: FileDropPhase,
+): RpcError {
+  return {
+    ...error,
+    data: {
+      ...error.data,
+      mechanism: "drop",
+      effect_state: effectState,
+      phase,
+    },
+  };
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function methodUnavailable(error: unknown): boolean {
+  return /(?:method|command).*(?:not found|wasn't found|unsupported)|wasn't found|-32601/i.test(
+    messageOf(error),
+  );
+}
+
+function runtimeError(reply: RuntimeReply, fallback: string): Error | null {
+  if (!reply.exceptionDetails) return null;
+  return new Error(
+    reply.exceptionDetails.exception?.description ?? reply.exceptionDetails.text ?? fallback,
+  );
+}
+
+async function pointBelongsToTarget(
+  options: FileDropTransactionOptions,
+  x: number,
+  y: number,
+  objectGroup: string,
+): Promise<boolean> {
+  const target = options.actionTarget.cdpTarget;
+  const hit = await sendToCdpTarget<{ backendNodeId?: number; frameId?: string }>(
+    options.cdp,
+    target,
+    "DOM.getNodeForLocation",
+    { x: Math.round(x), y: Math.round(y), includeUserAgentShadowDOM: true },
+  );
+  if (typeof hit.backendNodeId !== "number") return false;
+  if (options.actionTarget.frameId && hit.frameId !== options.actionTarget.frameId) return false;
+
+  const [resolvedTarget, resolvedHit] = await Promise.all([
+    sendToCdpTarget<{ object?: { objectId?: string } }>(options.cdp, target, "DOM.resolveNode", {
+      backendNodeId: options.actionTarget.backendNodeId,
+      objectGroup,
+    }),
+    sendToCdpTarget<{ object?: { objectId?: string } }>(options.cdp, target, "DOM.resolveNode", {
+      backendNodeId: hit.backendNodeId,
+      objectGroup,
+    }),
+  ]);
+  const targetObjectId = resolvedTarget.object?.objectId;
+  const hitObjectId = resolvedHit.object?.objectId;
+  if (!targetObjectId || !hitObjectId) return false;
+
+  const reply = await sendToCdpTarget<RuntimeReply>(options.cdp, target, "Runtime.callFunctionOn", {
+    objectId: targetObjectId,
+    functionDeclaration: `function(hit) {
+        for (let node = hit; node; ) {
+          if (node === this) return true;
+          if (this.contains?.(node)) return true;
+          const root = node.getRootNode?.();
+          node = node.parentNode || (root && root !== node ? root.host : null);
+        }
+        return false;
+      }`,
+    arguments: [{ objectId: hitObjectId }],
+    returnByValue: true,
+  });
+  const error = runtimeError(reply, "failed to verify file-drop target");
+  if (error) throw error;
+  return reply.result?.value === true;
+}
+
+export async function uploadThroughFileDrop(
+  options: FileDropTransactionOptions,
+): Promise<FileDropTransactionResult | RpcError> {
+  const deadline = Date.now() + options.timeoutMs;
+  const target = options.actionTarget.cdpTarget;
+  const objectGroup = `bsk-file-drop-${crypto.randomUUID()}`;
+  const dragData: DragData = {
+    items: [],
+    files: options.files,
+    dragOperationsMask: 1,
+  };
+  let dragStarted = false;
+  let dropSent = false;
+  let dragPoint = { x: 0, y: 0 };
+  let cleanupFailed = false;
+  let outcome: FileDropTransactionResult | RpcError = failure(
+    "protocol_error",
+    "file_drop_failed",
+    "file-drop transaction ended without an outcome",
+    "none",
+    "cleanup",
+  );
+
+  try {
+    const geometry = await waitBounded(
+      resolveNodeGeometry(
+        options.cdp,
+        options.actionTarget.tab.tabId,
+        {
+          target,
+          backendNodeId: options.actionTarget.backendNodeId,
+          ...(options.actionTarget.frameId ? { frameId: options.actionTarget.frameId } : {}),
+        },
+        { scrollIntoView: true },
+      ),
+      deadline,
+      options.signal,
+      "resolving file-drop target timed out",
+    );
+    if (isRpcError(geometry)) {
+      outcome = enrichFailure(geometry, "none", "resolve_target");
+      return outcome;
+    }
+    const point = geometry.targetActionPoint;
+    dragPoint = point;
+
+    outcome = await options.withOverlayHidden(async () => {
+      try {
+        try {
+          const belongs = await waitBounded(
+            pointBelongsToTarget(options, point.x, point.y, objectGroup),
+            deadline,
+            options.signal,
+            "verifying file-drop target timed out",
+          );
+          if (!belongs) {
+            return failure(
+              "permission_denied",
+              "file_drop_target_unavailable",
+              "file-drop target is not the topmost element at its action point",
+              "none",
+              "resolve_target",
+            );
+          }
+        } catch (error) {
+          return failure(
+            error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+            "file_drop_target_unavailable",
+            messageOf(error),
+            "none",
+            "resolve_target",
+          );
+        }
+
+        for (const [type, phase] of [
+          ["dragEnter", "drag_enter"],
+          ["dragOver", "drag_over"],
+        ] as const) {
+          try {
+            if (type === "dragEnter") dragStarted = true;
+            await waitBounded(
+              sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
+                type,
+                x: point.x,
+                y: point.y,
+                data: dragData,
+              }),
+              deadline,
+              options.signal,
+              `${type} timed out`,
+            );
+          } catch (error) {
+            const unsupported = methodUnavailable(error);
+            if (type === "dragEnter" && unsupported) dragStarted = false;
+            return failure(
+              unsupported
+                ? "unsupported"
+                : error instanceof BoundedWaitError
+                  ? "timeout"
+                  : "cdp_failed",
+              unsupported ? "upload_mechanism_unsupported" : "file_drop_failed",
+              messageOf(error),
+              "none",
+              phase,
+            );
+          }
+        }
+
+        try {
+          dropSent = true;
+          await waitBounded(
+            sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
+              type: "drop",
+              x: point.x,
+              y: point.y,
+              data: dragData,
+            }),
+            deadline,
+            options.signal,
+            "file drop timed out",
+          );
+          return { x: point.x, y: point.y };
+        } catch (error) {
+          outcome = failure(
+            error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+            "file_drop_failed",
+            messageOf(error),
+            "unknown",
+            "drop",
+          );
+          return outcome;
+        }
+      } finally {
+        if (dragStarted && !dropSent) {
+          try {
+            await waitBounded(
+              sendToCdpTarget(options.cdp, target, "Input.dispatchDragEvent", {
+                type: "dragCancel",
+                x: dragPoint.x,
+                y: dragPoint.y,
+                data: dragData,
+              }),
+              Date.now() + CLEANUP_TIMEOUT_MS,
+              undefined,
+              "cancelling file drag timed out",
+            );
+          } catch {
+            cleanupFailed = true;
+          }
+        }
+      }
+    });
+    return outcome;
+  } catch (error) {
+    outcome = failure(
+      error instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+      "file_drop_target_unavailable",
+      messageOf(error),
+      "none",
+      "resolve_target",
+    );
+    return outcome;
+  } finally {
+    try {
+      await waitBounded(
+        sendToCdpTarget(options.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }),
+        Date.now() + CLEANUP_TIMEOUT_MS,
+        undefined,
+        "releasing file-drop object group timed out",
+      );
+    } catch {
+      cleanupFailed = true;
+    }
+
+    const effect = isRpcError(outcome)
+      ? (outcome.data?.effect_state as TransferEffectState | undefined)
+      : "committed";
+    if (effect === "unknown" || cleanupFailed) {
+      await options.cdp.detach?.(target.tabId);
+    }
+    if (cleanupFailed && isRpcError(outcome)) {
+      outcome.data = { ...outcome.data, cleanup_state: "failed" };
+    }
+  }
+}
@@ -0,0 +1,445 @@
+// One upload transaction with an explicit browser-side commit boundary.
+// Chrome interception prevents a native chooser from escaping automation;
+// chooser events and a frame-scoped DOM probe are independent input-location
+// signals, so event delivery is not required for standard file inputs.
+
+import type { ClickResult, RpcError, TransferEffectState } from "@/transport/types";
+import { transferError } from "./errors";
+import type { ResolvedActionTarget } from "./interaction";
+import { type CdpRunner, isRpcError, sendToCdpTarget } from "./shared";
+import { BoundedWaitError, remainingMs, waitBounded } from "./transfer-transaction";
+
+const CLEANUP_TIMEOUT_MS = 1_000;
+const ACTIVATION_GRACE_MS = 1_000;
+const PROBE_INTERVAL_MS = 20;
+
+type UploadPhase =
+  | "arm_interception"
+  | "arm_input_probe"
+  | "trigger"
+  | "resolve_input"
+  | "set_files"
+  | "cleanup";
+
+interface RuntimeReply {
+  result?: { value?: unknown; objectId?: string };
+  exceptionDetails?: { text?: string; exception?: { description?: string } };
+}
+
+interface ChooserEvent {
+  frameId?: string;
+  backendNodeId?: number;
+  mode?: "selectSingle" | "selectMultiple";
+}
+
+export interface FileInputTransactionOptions {
+  cdp: CdpRunner;
+  actionTarget: ResolvedActionTarget;
+  files: string[];
+  timeoutMs: number;
+  signal?: AbortSignal;
+  trigger(): Promise<ClickResult | RpcError>;
+}
+
+export interface FileInputTransactionResult {
+  click: ClickResult;
+  multiple: boolean;
+}
+
+function runtimeError(reply: RuntimeReply, fallback: string): Error | null {
+  if (!reply.exceptionDetails) return null;
+  return new Error(
+    reply.exceptionDetails.exception?.description ?? reply.exceptionDetails.text ?? fallback,
+  );
+}
+
+function transferFailure(
+  code: RpcError["code"],
+  reason: "file_input_probe_failed" | "file_input_not_activated" | "set_file_input_failed",
+  message: string,
+  effectState: TransferEffectState,
+  phase: UploadPhase,
+): RpcError {
+  return transferError(code, reason, message, { effectState, phase });
+}
+
+function enrichFailure(
+  error: RpcError,
+  effectState: TransferEffectState,
+  phase: UploadPhase,
+): RpcError {
+  return {
+    ...error,
+    data: { ...error.data, effect_state: effectState, phase },
+  };
+}
+
+function sameTarget(
+  source: { tabId?: number; sessionId?: string },
+  target: { tabId: number; sessionId?: string },
+): boolean {
+  return source.tabId === target.tabId && source.sessionId === target.sessionId;
+}
+
+async function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  await waitBounded(
+    new Promise((resolve) => setTimeout(resolve, ms)),
+    Date.now() + ms + 1,
+    signal,
+    "upload activation probe timed out",
+  );
+}
+
+async function callOnTrigger<T = RuntimeReply>(
+  options: FileInputTransactionOptions,
+  objectId: string,
+  functionDeclaration: string,
+  args: unknown[],
+  returnByValue: boolean,
+): Promise<T> {
+  return sendToCdpTarget<T>(options.cdp, options.actionTarget.cdpTarget, "Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration,
+    arguments: args.map((value) => ({ value })),
+    returnByValue,
+    awaitPromise: false,
+  });
+}
+
+export async function uploadThroughActivatedFileInput(
+  options: FileInputTransactionOptions,
+): Promise<FileInputTransactionResult | RpcError> {
+  const deadline = Date.now() + options.timeoutMs;
+  const target = options.actionTarget.cdpTarget;
+  const objectGroup = `bsk-upload-${crypto.randomUUID()}`;
+  const stateKey = `__bskUpload_${crypto.randomUUID().replaceAll("-", "")}`;
+  const chooserEvents: ChooserEvent[] = [];
+  let interceptionArmed = false;
+  let probeArmed = false;
+  let triggerObjectId: string | undefined;
+  let outcome: FileInputTransactionResult | RpcError = transferFailure(
+    "protocol_error",
+    "file_input_probe_failed",
+    "upload transaction ended without an outcome",
+    "none",
+    "cleanup",
+  );
+
+  const chooserSubscription = options.cdp.onEvent?.((source, method, raw) => {
+    if (method !== "Page.fileChooserOpened" || !sameTarget(source, target)) return;
+    const event = raw as ChooserEvent;
+    chooserEvents.push(event);
+  });
+
+  try {
+    try {
+      await waitBounded(
+        sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+          enabled: true,
+        }),
+        deadline,
+        options.signal,
+        "arming native file chooser interception timed out",
+      );
+      interceptionArmed = true;
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "arm_interception",
+      );
+      return outcome;
+    }
+
+    try {
+      const resolved = await waitBounded(
+        sendToCdpTarget<{ object?: { objectId?: string } }>(
+          options.cdp,
+          target,
+          "DOM.resolveNode",
+          {
+            backendNodeId: options.actionTarget.backendNodeId,
+            objectGroup,
+          },
+        ),
+        deadline,
+        options.signal,
+        "resolving upload trigger timed out",
+      );
+      triggerObjectId = resolved.object?.objectId;
+      if (!triggerObjectId) throw new Error("DOM.resolveNode returned no trigger objectId");
+
+      const armed = await waitBounded(
+        callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `function(key) {
+            const doc = this.ownerDocument;
+            const owner = doc.defaultView;
+            if (!owner) return false;
+            const state = { inputs: [], listener: null };
+            Object.defineProperty(owner, key, { value: state, configurable: true });
+            state.listener = event => {
+              const path = typeof event.composedPath === "function" ? event.composedPath() : [];
+              const candidate = path[0] || event.target;
+              if (candidate && candidate.nodeType === 1 &&
+                  candidate.localName === "input" && candidate.type === "file") {
+                if (!state.inputs.includes(candidate)) state.inputs.push(candidate);
+                event.preventDefault();
+              }
+            };
+            doc.addEventListener("click", state.listener, true);
+            return true;
+          }`,
+          [stateKey],
+          true,
+        ),
+        deadline,
+        options.signal,
+        "arming frame-scoped file input probe timed out",
+      );
+      const armError = runtimeError(armed, "failed to arm file input probe");
+      if (armError || armed.result?.value !== true) {
+        throw armError ?? new Error("file input probe did not arm");
+      }
+      probeArmed = true;
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "arm_input_probe",
+      );
+      return outcome;
+    }
+
+    let click: ClickResult | RpcError;
+    try {
+      click = await waitBounded(
+        options.trigger(),
+        deadline,
+        options.signal,
+        "upload trigger timed out",
+      );
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "trigger",
+      );
+      return outcome;
+    }
+    if (isRpcError(click)) {
+      outcome = enrichFailure(click, "none", "trigger");
+      return outcome;
+    }
+
+    try {
+      const activationDeadline = Math.min(deadline, Date.now() + ACTIVATION_GRACE_MS);
+      let summary: { count: number; multiple: boolean } = { count: 0, multiple: false };
+      while (Date.now() < activationDeadline) {
+        if (chooserEvents.length > 0) break;
+        const reply = await callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `function(key) {
+            const state = this.ownerDocument.defaultView?.[key];
+            return state
+              ? { count: state.inputs.length, multiple: state.inputs[0]?.multiple === true }
+              : { count: 0, multiple: false };
+          }`,
+          [stateKey],
+          true,
+        );
+        const summaryError = runtimeError(reply, "failed to inspect activated file input");
+        if (summaryError) throw summaryError;
+        const value = reply.result?.value as { count?: unknown; multiple?: unknown } | undefined;
+        summary = {
+          count: typeof value?.count === "number" ? value.count : 0,
+          multiple: value?.multiple === true,
+        };
+        if (summary.count > 0) break;
+        await delay(Math.min(PROBE_INTERVAL_MS, remainingMs(activationDeadline)), options.signal);
+      }
+
+      if (chooserEvents.length > 1) {
+        outcome = transferFailure(
+          "unsupported",
+          "file_input_not_activated",
+          "upload trigger activated more than one file chooser",
+          "none",
+          "resolve_input",
+        );
+        return outcome;
+      }
+
+      const chooser = chooserEvents[0];
+      let backendNodeId: number | undefined;
+      let multiple = summary.multiple;
+      if (chooser) {
+        if (options.actionTarget.frameId && chooser.frameId !== options.actionTarget.frameId) {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            "upload trigger activated a file chooser in a different frame",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        if (typeof chooser.backendNodeId !== "number") {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            "upload trigger invoked a non-input file picker",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        backendNodeId = chooser.backendNodeId;
+        multiple = chooser.mode === "selectMultiple";
+      } else {
+        if (summary.count !== 1) {
+          outcome = transferFailure(
+            "unsupported",
+            "file_input_not_activated",
+            summary.count === 0
+              ? "upload trigger did not activate an input[type=file]"
+              : "upload trigger activated more than one input[type=file]",
+            "none",
+            "resolve_input",
+          );
+          return outcome;
+        }
+        const input = await callOnTrigger<RuntimeReply>(
+          options,
+          triggerObjectId,
+          `function(key) { return this.ownerDocument.defaultView?.[key]?.inputs[0]; }`,
+          [stateKey],
+          false,
+        );
+        const inputError = runtimeError(input, "failed to resolve activated file input object");
+        if (inputError) throw inputError;
+        if (!input.result?.objectId) throw new Error("activated file input returned no objectId");
+        const described = await sendToCdpTarget<{ node?: { backendNodeId?: number } }>(
+          options.cdp,
+          target,
+          "DOM.describeNode",
+          { objectId: input.result.objectId },
+        );
+        backendNodeId = described.node?.backendNodeId;
+        if (typeof backendNodeId !== "number") {
+          throw new Error("DOM.describeNode returned no file input backendNodeId");
+        }
+      }
+
+      if (!multiple && options.files.length !== 1) {
+        outcome = enrichFailure(
+          { code: "invalid_params", message: "file input accepts exactly one file" },
+          "none",
+          "resolve_input",
+        );
+        return outcome;
+      }
+
+      try {
+        await waitBounded(
+          sendToCdpTarget(options.cdp, target, "DOM.setFileInputFiles", {
+            files: options.files,
+            backendNodeId,
+          }),
+          deadline,
+          options.signal,
+          "setting file input files timed out",
+        );
+      } catch (err) {
+        outcome = transferFailure(
+          err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+          "set_file_input_failed",
+          err instanceof Error ? err.message : String(err),
+          "unknown",
+          "set_files",
+        );
+        return outcome;
+      }
+      outcome = { click, multiple };
+      return outcome;
+    } catch (err) {
+      outcome = transferFailure(
+        err instanceof BoundedWaitError ? "timeout" : "cdp_failed",
+        "file_input_probe_failed",
+        err instanceof Error ? err.message : String(err),
+        "none",
+        "resolve_input",
+      );
+      return outcome;
+    }
+  } finally {
+    chooserSubscription?.dispose();
+    let cleanupFailed = false;
+    if (probeArmed && triggerObjectId) {
+      try {
+        await waitBounded(
+          callOnTrigger(
+            options,
+            triggerObjectId,
+            `function(key) {
+              const owner = this.ownerDocument.defaultView;
+              const state = owner?.[key];
+              if (state?.listener) this.ownerDocument.removeEventListener("click", state.listener, true);
+              if (owner) delete owner[key];
+            }`,
+            [stateKey],
+            true,
+          ),
+          Date.now() + CLEANUP_TIMEOUT_MS,
+          undefined,
+          "cleaning file input probe timed out",
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    }
+    if (interceptionArmed) {
+      try {
+        await waitBounded(
+          sendToCdpTarget(options.cdp, target, "Page.setInterceptFileChooserDialog", {
+            enabled: false,
+            cancel: true,
+          }),
+          Date.now() + CLEANUP_TIMEOUT_MS,
+          undefined,
+          "disabling file chooser interception timed out",
+        );
+      } catch {
+        cleanupFailed = true;
+      }
+    }
+    try {
+      await waitBounded(
+        sendToCdpTarget(options.cdp, target, "Runtime.releaseObjectGroup", { objectGroup }),
+        Date.now() + CLEANUP_TIMEOUT_MS,
+        undefined,
+        "releasing upload object group timed out",
+      );
+    } catch {
+      cleanupFailed = true;
+    }
+
+    const effect = isRpcError(outcome)
+      ? (outcome.data?.effect_state as TransferEffectState | undefined)
+      : "committed";
+    if (effect === "unknown" || cleanupFailed) {
+      await options.cdp.detach?.(target.tabId);
+    }
+    if (cleanupFailed && isRpcError(outcome)) {
+      outcome.data = { ...outcome.data, cleanup_state: "failed" };
+    }
+  }
+}
@@ -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,154 +24,30 @@ 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. */
  actionPoint: Point;
+  /** Point in the addressed CDP target's viewport, used by OOPIF-local input events. */
+  targetActionPoint: Point;
 }

 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}`);
    }
@@ -188,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");
@@ -213,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 {
@@ -237,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,
@@ -262,13 +154,32 @@ export async function resolveNodeGeometry(
    if (isRpcError(localRegion)) return localRegion;

    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 localVisibleRegions = localRegion
+          .map((polygon) =>
+            clipPolygon(
+              polygon,
+              rectPolygon({
+                x: 0,
+                y: 0,
+                w: localViewport.width,
+                h: localViewport.height,
+              }),
+            ),
+          )
+          .filter((polygon) => polygon.length >= 3);
+        const localActionRegion = largestRegion(localVisibleRegions);
+        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) =>
@@ -283,7 +194,17 @@ export async function resolveNodeGeometry(
    if (!topBounds || !actionPoint) {
      return { code: "permission_denied", message: "element not visible" };
    }
-    return { topVisibleRegions, topBounds, actionPoint };
+    if (address.target.sessionId && !targetActionPoint) {
+      return { code: "permission_denied", message: "element not visible in its target" };
+    }
+    targetActionPoint ??= actionPoint;
+    return {
+      topVisibleRegions,
+      topBounds,
+      actionPoint,
+      targetActionPoint,
+      topViewport: cssViewport(await context.layoutMetrics({ tabId })),
+    };
  } catch (error) {
    return geometryError(error instanceof Error ? error.message : String(error));
  }
@@ -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,
-  };
-}
@@ -0,0 +1,102 @@
+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 type SnapshotProjectionResult =
+  | { status: "available"; projection: SnapshotProjection }
+  | UnavailableFrameProjection;
+
+/** Descendants inherit the failed boundary without attempting another owner read. */
+export type FrameProjectionIssue =
+  | UnavailableFrameProjection
+  | { status: "blocked"; source: CoordinateOwner; cause: UnavailableFrameProjection };
+
+export type FrameProjectionState = SnapshotProjectionResult | FrameProjectionIssue;
+
+/** DOMSnapshot bounds are document-relative CSS pixels, independent of raster DPR. */
+export function snapshotViewportRect(
+  bounds: number[],
+  owner: CoordinateOwner,
+  scroll: { x: number; y: number },
+): FrameViewportRect | null {
+  if (bounds.length < 4 || !bounds.slice(0, 4).every(Number.isFinite)) return null;
+  const [x, y, width, height] = bounds;
+  if (width <= 0 || height <= 0 || !Number.isFinite(scroll.x) || !Number.isFinite(scroll.y)) {
+    return null;
+  }
+  return {
+    space: "frame-viewport-css",
+    owner,
+    rect: { x: x - scroll.x, y: y - scroll.y, width, height },
+  };
+}
+
+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,
+    },
+  };
+}
@@ -0,0 +1,333 @@
+import {
+  type CdpFrame,
+  type CdpFrameGraph,
+  type CdpTarget,
+  cdpTargetKey,
+} from "@/browser-driver/frame-graph";
+import {
+  type GeometryProjection,
+  type Polygon,
+  type ProjectiveEdge,
+  parseCdpQuad,
+  type Quad,
+  type Size,
+} 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 };
+  visualViewport?: { zoom?: number };
+  cssLayoutViewport?: {
+    clientWidth?: number;
+    clientHeight?: number;
+    pageX?: number;
+    pageY?: number;
+  };
+  layoutViewport?: { clientWidth?: number; clientHeight?: number; pageX?: number; pageY?: number };
+}
+
+/** 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 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;
+  }
+
+  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);
+      const source = await this.viewport(root.target);
+      const parentRoot = this.targetRoot(frames, parent);
+      if (!destinationQuad || !source || !parentRoot) return null;
+      const destinationClips = await this.clips(frames, parent, parentRoot);
+      if (!destinationClips) return null;
+      edges.push({ sourceViewport: source, destinationQuad, destinationClips });
+      root = parentRoot;
+    }
+    const topViewport = await this.viewport(root.target);
+    return topViewport ? { sourceClips, edges, topViewport } : null;
+  }
+}
@@ -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;
+}
@@ -1,5 +1,5 @@
-// DOM interaction tools — `tool.click`, `tool.fill`, `tool.type`,
-// `tool.press`, and `tool.select`.
+// DOM interaction tools — `tool.click`, `tool.fill`, `tool.press`, and
+// `tool.select`.
 //
 // All interaction tools:
 // 1. Resolve target tab (sandbox: must be inside Agent Window).
@@ -11,7 +11,7 @@
 //    commands.

 import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
-import { type CdpTarget, cdpTargetKey } from "@/browser-driver/frame-graph";
+import type { CdpTarget } from "@/browser-driver/frame-graph";
 import type { SessionContext, SessionManager } from "@/session-manager/manager";
 import type {
  ClickParams,
@@ -27,15 +27,11 @@ import type {
  RpcError,
  SelectParams,
  SelectResult,
-  TypeParams,
-  TypeResult,
 } from "@/transport/types";
 import { attachDialogs, markDialogCursor } from "./dialogs";
-import { fillEditable } from "./editable-input";
 import { backendNodeToObject } from "./element-geometry";
 import { rpcError } from "./errors";
 import { resolveNodeGeometry, scrollElementAndFramesIntoView } from "./frame-geometry";
-import { dispatchMouseClick } from "./mouse-input";
 import {
  type CdpRunner,
  type ChromeTabsApi,
@@ -44,11 +40,10 @@ import {
  enforceAgentWindow,
  isRpcError,
  lookupSession,
+  type ResolvedTargetTab,
  resolveTargetTab,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { resolveSurfacePointerTarget } from "./surface-target";
-import { dispatchTextInput } from "./text-input";

 export interface InteractionDeps {
  cdp: CdpRunner;
@@ -62,6 +57,15 @@ export interface InteractionDeps {
  keepOverlayBypassAfterHover?: boolean;
 }

+export interface ResolvedActionTarget {
+  tab: ResolvedTargetTab;
+  backendNodeId: number;
+  cdpTarget: CdpTarget;
+  frameId?: string;
+  usedRef?: string;
+  usedSelector?: string;
+}
+
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_HOVER_SETTLE_MS = 200;

@@ -134,7 +138,7 @@ async function wait(ms: number, signal?: AbortSignal): Promise<void> {
 * `RpcError` if the caller supplied neither (or both), or if neither
 * lookup matched.
 */
-async function resolveBackendNode(
+export async function resolveBackendNode(
  cdp: CdpRunner,
  ctx: SessionContext,
  target: { tabId: number },
@@ -165,7 +169,7 @@ async function resolveBackendNode(
    };
  }
  if (hasRef) {
-    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId, "interact");
+    const resolved = resolveSnapshotRef(ctx, params.ref as string, target.tabId);
    if (isRpcError(resolved)) return resolved;
    return {
      backendNodeId: resolved.backendNodeId,
@@ -179,6 +183,8 @@ 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,
    });
@@ -221,146 +227,26 @@ async function resolveBackendNode(
  }
 }

-interface InputDispatchContext {
-  target: CdpTarget;
-  cdp: CdpRunner;
-  backendNodeId?: number;
-  frameId?: string;
-  usedRef?: string;
-  usedSelector?: string;
-}
-
-function inputContextForNode(
+export async function resolveActionTarget(
  cdp: CdpRunner,
-  node: Awaited<ReturnType<typeof resolveBackendNode>>,
-): (InputDispatchContext & { backendNodeId: number }) | RpcError {
-  if (isRpcError(node)) return node;
-  return {
-    target: node.cdpTarget,
-    cdp: cdpRunnerForTarget(cdp, node.cdpTarget),
-    backendNodeId: node.backendNodeId,
-    frameId: node.frameId,
-    usedRef: node.usedRef,
-    usedSelector: node.usedSelector,
-  };
-}
-
-interface FocusProbe {
-  hasFocus: boolean;
-  activeTag: string;
-  textEntry: boolean;
-}
-
-/** Resolve keyboard input to the CDP target that currently owns focus. */
-async function resolveFocusedInputContext(
-  cdp: CdpRunner,
-  tabId: number,
-  mode: "press" | "type",
-): Promise<InputDispatchContext | RpcError> {
-  if (!cdp.getFrameGraph) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      `${mode} cannot determine the focused frame target`,
-    );
-  }
-
-  let targets: CdpTarget[];
-  try {
-    const graph = await cdp.getFrameGraph(tabId);
-    const unique = new Map<string, CdpTarget>();
-    unique.set(cdpTargetKey({ tabId }), { tabId });
-    for (const frame of graph.frames) unique.set(cdpTargetKey(frame.target), frame.target);
-    targets = [...unique.values()];
-  } catch (err) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      err instanceof Error ? err.message : String(err),
-    );
-  }
-
-  const focused: Array<{ target: CdpTarget; probe: FocusProbe }> = [];
-  await Promise.all(
-    targets.map(async (candidate) => {
-      try {
-        const reply = await cdpRunnerForTarget(cdp, candidate).send<{
-          result?: { value?: FocusProbe };
-        }>(tabId, "Runtime.evaluate", {
-          expression: `(() => {
-            /* bsk-focus-target-probe */
-            const active = document.activeElement;
-            const inputType = active instanceof HTMLInputElement ? active.type.toLowerCase() : '';
-            const nonTextInputTypes = new Set([
-              'button', 'checkbox', 'color', 'date', 'datetime-local', 'file',
-              'hidden', 'image', 'month', 'radio', 'range', 'reset', 'submit',
-              'time', 'week'
-            ]);
-            const role = active instanceof Element ? active.getAttribute('role') : null;
-            return {
-              hasFocus: document.hasFocus(),
-              activeTag: active instanceof Element ? active.tagName.toLowerCase() : '',
-              textEntry:
-                (active instanceof HTMLInputElement && !nonTextInputTypes.has(inputType)) ||
-                active instanceof HTMLTextAreaElement ||
-                (active instanceof HTMLElement && active.isContentEditable) ||
-                role === 'textbox' || role === 'searchbox'
-            };
-          })()`,
-          returnByValue: true,
-        });
-        const probe = reply.result?.value;
-        if (probe?.hasFocus) focused.push({ target: candidate, probe });
-      } catch {
-        // A target may navigate or detach while the graph is being probed.
-      }
-    }),
-  );
-
-  // A top document whose active element is an iframe delegates focus to
-  // that frame. Removing those delegating targets leaves the deepest OOPIF
-  // target while same-process frames continue to use the shared root target.
-  const owners = focused.filter(({ probe }) => {
-    if (probe.activeTag === "iframe" || probe.activeTag === "frame") return false;
-    return mode !== "type" || probe.textEntry;
-  });
-  if (owners.length !== 1) {
-    return rpcError(
-      "cdp_failed",
-      "focus_target_unresolved",
-      owners.length === 0
-        ? `${mode} found no unique focused${mode === "type" ? " text-entry" : " frame"} target`
-        : `${mode} found multiple focused frame targets`,
-      { candidate_count: owners.length },
-    );
-  }
-  const target = owners[0].target;
-  return { target, cdp: cdpRunnerForTarget(cdp, target) };
+  ctx: SessionContext,
+  target: ResolvedTargetTab,
+  params: { ref?: string; selector?: string },
+  toolName: string,
+): Promise<ResolvedActionTarget | RpcError> {
+  const node = await resolveBackendNode(cdp, ctx, target, params, toolName);
+  return isRpcError(node) ? node : { tab: target, ...node };
 }

 // ---------------------------------------------------------------------------
 // tool.click
 // ---------------------------------------------------------------------------

-interface ResolvedClickPointerTarget {
-  point: { x: number; y: number };
-  usedRef?: string;
-  usedSelector?: string;
-  moveSettleMs: number;
-  capture?: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
 export async function handleClick(
  manager: SessionManager,
  params: ClickParams,
  deps: InteractionDeps = getDefaultDeps(),
 ): Promise<ClickResult | RpcError> {
-  const hasSurfacePointParams =
-    params.capture_id !== undefined || params.image_x !== undefined || params.image_y !== undefined;
  const ctxOrErr = lookupSession(manager, params, "click");
  if (isRpcError(ctxOrErr)) return ctxOrErr;
  const ctx = ctxOrErr;
@@ -370,69 +256,50 @@ export async function handleClick(
  if (isRpcError(target)) return target;
  const denied = enforceAgentWindow(ctx, target, "click");
  if (denied) return denied;
-  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
+  const resolved = await resolveActionTarget(deps.cdp, ctx, target, params, "click");
+  if (isRpcError(resolved)) return resolved;
+  return clickResolvedTarget(ctx, resolved, params, deps);
+}

-  const button: MouseButton = params.button ?? "left";
-  const clickCount = params.click_count ?? 1;
-  if (!Number.isSafeInteger(clickCount) || clickCount < 1) {
-    return { code: "invalid_params", message: "click_count must be a positive integer" };
-  }
-  const modifiers = modifiersBitfield(params.modifiers);
+export async function clickResolvedTarget(
+  ctx: SessionContext,
+  resolved: ResolvedActionTarget,
+  params: Pick<ClickParams, "button" | "click_count" | "modifiers">,
+  deps: InteractionDeps,
+): Promise<ClickResult | RpcError> {
+  const { tab: target } = resolved;
+  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "click aborted" };
  }

  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  const pointerTarget: ResolvedClickPointerTarget | RpcError = hasSurfacePointParams
-    ? await resolveSurfacePointerTarget(
-        ctx,
-        target,
-        {
-          ref: params.ref,
-          selector: params.selector,
-          captureId: params.capture_id,
-          imageX: params.image_x,
-          imageY: params.image_y,
-        },
-        {
-          cdp: deps.cdp,
-          signal: deps.signal,
-        },
-      )
-    : await (async () => {
-        const node = await resolveBackendNode(deps.cdp, ctx, target, params, "click");
-        if (isRpcError(node)) return node;
-        const geometry = await resolveNodeGeometry(
-          deps.cdp,
-          target.tabId,
-          {
-            target: node.cdpTarget,
-            backendNodeId: node.backendNodeId,
-            ...(node.frameId ? { frameId: node.frameId } : {}),
-          },
-          { scrollIntoView: true },
-        );
-        if (isRpcError(geometry)) return geometry;
-        return {
-          point: geometry.actionPoint,
-          usedRef: node.usedRef,
-          usedSelector: node.usedSelector,
-          moveSettleMs: 0,
-        };
-      })();
-  if (isRpcError(pointerTarget)) return pointerTarget;
+  const geometry = await resolveNodeGeometry(
+    deps.cdp,
+    target.tabId,
+    {
+      target: resolved.cdpTarget,
+      backendNodeId: resolved.backendNodeId,
+      ...(resolved.frameId ? { frameId: resolved.frameId } : {}),
+    },
+    { scrollIntoView: true },
+  );
+  if (isRpcError(geometry)) return geometry;
+  const centre = geometry.actionPoint;

  if (throwIfAborted(deps.signal)) {
    return { code: "cancelled", message: "click aborted" };
  }

-  const overlayBlocking = await checkOverlayAtPoint(
-    deps.cdp,
-    target.tabId,
-    pointerTarget.point.x,
-    pointerTarget.point.y,
-  );
+  const button: MouseButton = params.button ?? "left";
+  const clickCount = params.click_count ?? 1;
+  if (clickCount < 1) {
+    return { code: "invalid_params", message: "click_count must be greater than zero" };
+  }
+  const modifiers = modifiersBitfield(params.modifiers);
+
+  const overlayBlocking = await checkOverlayAtPoint(deps.cdp, target.tabId, centre.x, centre.y);
  let automationBypassEnabled = false;
  if (overlayBlocking && deps.bypassOverlay) {
    try {
@@ -444,16 +311,47 @@ export async function handleClick(
  }

  try {
-    const dispatch = await dispatchMouseClick(deps.cdp, target.tabId, pointerTarget.point, {
+    // Move first so hover state activates, then press → release.
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: centre.x,
+      y: centre.y,
+      modifiers,
+    });
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "click aborted" };
+    }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x: centre.x,
+      y: centre.y,
      button,
      clickCount,
      modifiers,
-      signal: deps.signal,
-      moveSettleMs: pointerTarget.moveSettleMs,
    });
-    if (dispatch === "cancelled") {
+    if (throwIfAborted(deps.signal)) {
+      try {
+        await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+          type: "mouseReleased",
+          x: centre.x,
+          y: centre.y,
+          button,
+          clickCount,
+          modifiers,
+        });
+      } catch (err) {
+        console.debug("[bsk interaction] best-effort mouseReleased after abort failed", err);
+      }
      return { code: "cancelled", message: "click aborted" };
    }
+    await deps.cdp.send(target.tabId, "Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x: centre.x,
+      y: centre.y,
+      button,
+      clickCount,
+      modifiers,
+    });
  } catch (err) {
    return {
      code: "cdp_failed",
@@ -471,17 +369,10 @@ export async function handleClick(

  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
    tab_id: target.tabId,
-    used_ref: pointerTarget.usedRef,
-    used_selector: pointerTarget.usedSelector,
-    x: pointerTarget.point.x,
-    y: pointerTarget.point.y,
-    ...(pointerTarget.capture
-      ? {
-          capture_id: pointerTarget.capture.id,
-          image_x: pointerTarget.capture.imageX,
-          image_y: pointerTarget.capture.imageY,
-        }
-      : {}),
+    used_ref: resolved.usedRef,
+    used_selector: resolved.usedSelector,
+    x: centre.x,
+    y: centre.y,
  });
 }

@@ -701,47 +592,6 @@ function isFillable(node: DescribedNode): boolean {
  return false;
 }

-/** `type` also supports custom text-entry widgets that expose an ARIA role. */
-function isTypeTarget(node: DescribedNode): boolean {
-  const tag = (node.nodeName ?? "").toUpperCase();
-  const attrs = node.attributes ?? [];
-  const attributes = new Map<string, string>();
-  for (let i = 0; i + 1 < attrs.length; i += 2) {
-    attributes.set(attrs[i].toLowerCase(), attrs[i + 1].toLowerCase());
-  }
-  if (tag === "TEXTAREA") return true;
-  if (tag === "INPUT") {
-    const type = attributes.get("type") ?? "text";
-    return !new Set([
-      "button",
-      "checkbox",
-      "color",
-      "date",
-      "datetime-local",
-      "file",
-      "hidden",
-      "image",
-      "month",
-      "radio",
-      "range",
-      "reset",
-      "submit",
-      "time",
-      "week",
-    ]).has(type);
-  }
-  const contentEditable = attributes.get("contenteditable");
-  if (
-    contentEditable === "" ||
-    contentEditable === "true" ||
-    contentEditable === "plaintext-only"
-  ) {
-    return true;
-  }
-  const role = attributes.get("role");
-  return role === "textbox" || role === "searchbox";
-}
-
 type SelectMutationResult =
  | {
      ok: true;
@@ -759,6 +609,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,
@@ -780,9 +677,8 @@ export async function handleFill(
  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);

  const node = await resolveBackendNode(deps.cdp, ctx, target, params, "fill");
-  const input = inputContextForNode(deps.cdp, node);
-  if (isRpcError(input)) return input;
-  const nodeCdp = input.cdp;
+  if (isRpcError(node)) return node;
+  const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);

  try {
    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
@@ -790,7 +686,7 @@ export async function handleFill(
      target.tabId,
      "DOM.describeNode",
      {
-        backendNodeId: input.backendNodeId,
+        backendNodeId: node.backendNodeId,
      },
    );
    if (!described.node || !isFillable(described.node)) {
@@ -803,139 +699,274 @@ export async function handleFill(
    const scrollErr = await scrollElementAndFramesIntoView(
      deps.cdp,
      target.tabId,
-      input.target,
-      input.backendNodeId,
-      input.frameId,
+      node.cdpTarget,
+      node.backendNodeId,
+      node.frameId,
    );
    if (scrollErr) return scrollErr;
    if (throwIfAborted(deps.signal)) {
      return { code: "cancelled", message: "fill aborted" };
    }
-    await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: input.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)) {
    return { code: "cancelled", message: "fill aborted" };
  }

-  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, input.backendNodeId);
+  const objectIdOrErr = await backendNodeToObject(nodeCdp, target.tabId, node.backendNodeId);
  if (isRpcError(objectIdOrErr)) return objectIdOrErr;
  const objectId = objectIdOrErr;
  const clearBefore = params.clear_before ?? true;
-  const fillResult = await fillEditable(
-    nodeCdp,
-    target.tabId,
-    objectId,
-    params.value,
-    clearBefore,
-    deps.signal,
-  );
-  if (isRpcError(fillResult)) return fillResult;

-  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-    tab_id: target.tabId,
-    used_ref: input.usedRef,
-    used_selector: input.usedSelector,
-    value_length: fillResult.value.length,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// tool.type
-// ---------------------------------------------------------------------------
-
-export async function handleType(
-  manager: SessionManager,
-  params: TypeParams,
-  deps: InteractionDeps = getDefaultDeps(),
-): Promise<TypeResult | RpcError> {
-  if (!params || typeof params.text !== "string") {
-    return { code: "invalid_params", message: "type requires a text string" };
-  }
-  if (params.focused !== undefined && typeof params.focused !== "boolean") {
-    return { code: "invalid_params", message: "type focused must be a boolean" };
-  }
-  const hasExplicitTarget =
-    (typeof params.ref === "string" && params.ref.length > 0) ||
-    (typeof params.selector === "string" && params.selector.length > 0);
-  if (params.focused === true && hasExplicitTarget) {
-    return {
-      code: "invalid_params",
-      message: "type: pass a ref/selector or focused=true, not both",
-    };
-  }
-  if (params.focused !== true && !hasExplicitTarget) {
-    return {
-      code: "invalid_params",
-      message: "type requires a ref/selector or focused=true",
-    };
-  }
-  const ctxOrErr = lookupSession(manager, params, "type");
-  if (isRpcError(ctxOrErr)) return ctxOrErr;
-  const ctx = ctxOrErr;
-  if (throwIfAborted(deps.signal)) return { code: "cancelled", message: "type aborted" };
-  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
-  if (isRpcError(target)) return target;
-  const denied = enforceAgentWindow(ctx, target, "type");
-  if (denied) return denied;
-  const dialogCursor = markDialogCursor(deps.cdp, target.tabId);
-
-  let input: InputDispatchContext | RpcError;
-  if (hasExplicitTarget) {
-    const node = await resolveBackendNode(deps.cdp, ctx, target, params, "type");
-    const explicitInput = inputContextForNode(deps.cdp, node);
-    if (isRpcError(explicitInput)) return explicitInput;
-    input = explicitInput;
+  try {
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
    try {
-      const described = await explicitInput.cdp.send<{ node?: DescribedNode }>(
+      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,
-        "DOM.describeNode",
-        { backendNodeId: explicitInput.backendNodeId },
+        "Runtime.callFunctionOn",
+        { objectId, functionDeclaration: FILL_EDITABLE_FUNCTION, returnByValue: true },
      );
-      if (!described.node || !isTypeTarget(described.node)) {
-        return rpcError(
-          "invalid_params",
+      if (throwIfAborted(deps.signal)) {
+        return { code: "cancelled", message: "fill aborted" };
+      }
+      if (!editable.exceptionDetails && editable.result?.value === false) {
+        return fillError(
          "target_not_fillable",
-          `element ${described.node?.nodeName ?? "?"} not text-editable`,
+          "fill target is not editable or its input type is unsupported",
        );
      }
-      deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-      const scrollErr = await scrollElementAndFramesIntoView(
-        deps.cdp,
-        target.tabId,
-        explicitInput.target,
-        explicitInput.backendNodeId,
-        explicitInput.frameId,
-      );
-      if (scrollErr) return scrollErr;
-      if (throwIfAborted(deps.signal)) return { code: "cancelled", message: "type aborted" };
-      await explicitInput.cdp.send(target.tabId, "DOM.focus", {
-        backendNodeId: explicitInput.backendNodeId,
-      });
-    } catch (err) {
-      return { code: "cdp_failed", message: err instanceof Error ? err.message : String(err) };
+      throw error;
    }
-  } else {
-    input = await resolveFocusedInputContext(deps.cdp, target.tabId, "type");
-    if (isRpcError(input)) return input;
+    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`.
+    if (params.value !== "") {
+      await deps.cdp.send(target.tabId, "Input.insertText", { text: params.value });
+    }
+    if (throwIfAborted(deps.signal)) {
+      return { code: "cancelled", message: "fill aborted" };
+    }
+    // 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(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 fillError("fill_failed", err instanceof Error ? err.message : String(err));
+  } finally {
+    await nodeCdp.send(target.tabId, "Runtime.releaseObject", { objectId }).catch(() => undefined);
  }
-
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  const dispatchError = await dispatchTextInput(input.cdp, target.tabId, params.text, deps.signal);
-  if (dispatchError) return dispatchError;
-
-  return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
-    tab_id: target.tabId,
-    used_ref: input.usedRef,
-    used_selector: input.usedSelector,
-    text_length: params.text.length,
-    verification: "dispatched",
-  });
 }

 // ---------------------------------------------------------------------------
@@ -1109,38 +1140,31 @@ export async function handlePress(
    };
  }

-  let input: InputDispatchContext | RpcError;
  // Optional focus before key dispatch.
  if (params.ref || params.selector) {
    const node = await resolveBackendNode(deps.cdp, ctx, target, params, "press");
-    const explicitInput = inputContextForNode(deps.cdp, node);
-    if (isRpcError(explicitInput)) return explicitInput;
-    input = explicitInput;
+    if (isRpcError(node)) return node;
+    const nodeCdp = cdpRunnerForTarget(deps.cdp, node.cdpTarget);
    try {
      deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
      const scrollErr = await scrollElementAndFramesIntoView(
        deps.cdp,
        target.tabId,
-        explicitInput.target,
-        explicitInput.backendNodeId,
-        explicitInput.frameId,
+        node.cdpTarget,
+        node.backendNodeId,
+        node.frameId,
      );
      if (scrollErr) return scrollErr;
      if (throwIfAborted(deps.signal)) {
        return { code: "cancelled", message: "press aborted" };
      }
-      await explicitInput.cdp.send(target.tabId, "DOM.focus", {
-        backendNodeId: explicitInput.backendNodeId,
-      });
+      await nodeCdp.send(target.tabId, "DOM.focus", { backendNodeId: node.backendNodeId });
    } catch (err) {
      return {
        code: "cdp_failed",
        message: err instanceof Error ? err.message : String(err),
      };
    }
-  } else {
-    input = await resolveFocusedInputContext(deps.cdp, target.tabId, "press");
-    if (isRpcError(input)) return input;
  }

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

@@ -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
@@ -8,7 +9,6 @@ import {
  applyVomInteractionRecovery,
  type CondSurface,
  isVomReferenceNode,
-  type Rect,
  renderVom,
  type VomNode,
  type VomOptions,
@@ -18,7 +18,7 @@ import { ChromiumCdp } from "@/browser-driver/chromium-cdp";
 import type { CdpTarget } from "@/browser-driver/frame-graph";
 import {
  type CaptureSuppressSendToTab,
-  withOverlaysHiddenForCapture,
+  withExtensionOverlayHidden,
 } from "@/lib/capture-suppress-bridge";
 import type { SessionContext, SessionManager } from "@/session-manager/manager";
 import type {
@@ -35,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,
@@ -48,25 +49,15 @@ import {
  type ToolEffect,
 } from "./shared";
 import { resolveSnapshotRef } from "./snapshot-ref";
-import { surfaceVisibleRect } from "./surface-coordinate";
-import { captureSurfaceEnvironment } from "./surface-target";
-import {
-  type CapturedNode,
-  type CapturedViewModel,
-  captureViewModel,
-  collectOverlayExcludedBackendIds,
-} 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 {
  type CaptureVomObservationResult,
  projectRecordSafeObservation,
 } from "./vom/record-safe-observation";
-import {
-  clusterRenderedSurfaces,
-  discoverRenderedSurfaces,
-  projectRenderedSurfaces,
-} from "./vom/rendered-surfaces";
 import {
  buildSemanticGraph,
  buildSemanticVomScene,
@@ -98,9 +89,6 @@ export const normaliseRef = sharedNormaliseRef;
 // screenshot — `tool.screenshot`
 // ---------------------------------------------------------------------------

-const VISUAL_SURFACE_SCREENSHOT_MAX_EDGE = 2_048;
-const VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS = 4_000_000;
-
 /**
 * Strip the `data:image/...;base64,` prefix from a Chrome
 * `captureVisibleTab` dataURL and return the raw base64 payload.
@@ -193,52 +181,27 @@ async function captureElementScreenshot(
  target: CdpTarget,
  backendNodeId: number,
  frameId?: string,
-  visualSurface = false,
-  observedVisibleRect?: Rect,
  signal?: AbortSignal,
-): Promise<
-  { image_base64: string; width: number; height: number; topViewportRect: Rect } | RpcError
-> {
+): Promise<{ image_base64: string; width: number; height: number } | RpcError> {
  if (signal?.aborted) return cancelled("screenshot");
  const geometry = await resolveNodeGeometry(
    cdp,
    tabId,
    { target, backendNodeId, ...(frameId ? { frameId } : {}) },
-    { scrollIntoView: !visualSurface },
+    { scrollIntoView: true },
  );
  if (isRpcError(geometry)) return geometry;
  if (signal?.aborted) return cancelled("screenshot");
-  const topViewportRect = surfaceVisibleRect(
-    geometry.topBounds,
-    visualSurface ? observedVisibleRect : undefined,
-  );
-  if (!topViewportRect) {
-    return { code: "permission_denied", message: "surface is no longer visible" };
-  }
-  const rect = {
-    x: topViewportRect.x,
-    y: topViewportRect.y,
-    width: topViewportRect.w,
-    height: topViewportRect.h,
-  };
-  const scale = visualSurface
-    ? Math.min(
-        1,
-        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.width,
-        VISUAL_SURFACE_SCREENSHOT_MAX_EDGE / rect.height,
-        Math.sqrt(VISUAL_SURFACE_SCREENSHOT_MAX_PIXELS / (rect.width * rect.height)),
-      )
-    : 1;
+  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,
-        scale,
+        ...clip.rect,
+        scale: 1,
      },
    });
    if (signal?.aborted) return cancelled("screenshot");
@@ -250,7 +213,7 @@ async function captureElementScreenshot(
      width: Math.round(rect.width),
      height: Math.round(rect.height),
    };
-    return { image_base64, width: dims.width, height: dims.height, topViewportRect };
+    return { image_base64, width: dims.width, height: dims.height };
  } catch (err) {
    return {
      code: "cdp_failed",
@@ -345,7 +308,7 @@ export async function handleScreenshot(
    if (!deps.cdp) {
      return { code: "cdp_failed", message: "screenshot ref capture requires CDP" };
    }
-    const node = resolveSnapshotRef(ctx, ref, target.tabId, "screenshot");
+    const node = resolveSnapshotRef(ctx, ref, target.tabId);
    if (isRpcError(node)) return node;
    if (signal?.aborted) return cancelled("screenshot");
    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
@@ -356,7 +319,7 @@ export async function handleScreenshot(
      tabId: target.tabId,
      ...(node.cdpSessionId ? { sessionId: node.cdpSessionId } : {}),
    };
-    const captured = await withOverlaysHiddenForCapture(
+    const captured = await withExtensionOverlayHidden(
      target.tabId,
      () =>
        captureElementScreenshot(
@@ -365,54 +328,18 @@ export async function handleScreenshot(
          nodeTarget,
          node.backendNodeId,
          node.frameId,
-          node.kind === "surface",
-          node.visibleRect,
          signal,
        ),
      deps.sendToTab,
    );
    if (isRpcError(captured)) return captured;
    if (signal?.aborted) return cancelled("screenshot");
-    const capture =
-      node.kind === "surface"
-        ? await (async () => {
-            const environment = await captureSurfaceEnvironment(cdp, target.tabId, node.frameId);
-            if (isRpcError(environment)) return environment;
-            return ctx.surfaceCaptures.create({
-              sessionId: ctx.sessionId,
-              tabId: target.tabId,
-              navigationIdentity: environment.navigationIdentity,
-              surface: {
-                ref: node.refKey,
-                ...(node.frameId ? { frameId: node.frameId } : {}),
-                backendNodeId: node.backendNodeId,
-                observationGeneration: node.generation,
-              },
-              topViewportRect: captured.topViewportRect,
-              imageWidth: captured.width,
-              imageHeight: captured.height,
-              viewportSignature: environment.viewportSignature,
-              frameProjectionSignature: environment.frameProjectionSignature,
-            });
-          })()
-        : null;
-    if (capture && isRpcError(capture)) return capture;
    return withShotDialogs({
      image_base64: captured.image_base64,
      width: captured.width,
      height: captured.height,
      format: "png",
      tab_id: target.tabId,
-      ...(capture
-        ? {
-            capture: {
-              id: capture.id,
-              surface_ref: `@${capture.surface.ref}`,
-              coordinate_space: "capture-image-pixel" as const,
-              expires_at: capture.expiresAt,
-            },
-          }
-        : {}),
    });
  }

@@ -424,7 +351,7 @@ export async function handleScreenshot(
    );
  }

-  const captured = await withOverlaysHiddenForCapture(
+  const captured = await withExtensionOverlayHidden(
    target.tabId,
    () => captureFullTabPng(deps, ctx, target, signal),
    deps.sendToTab,
@@ -596,8 +523,11 @@ function buildActiveScopeBlocks(nodes: VomNode[], signals: VomNodeDomSignals): A
  return blocks;
 }

-function buildConditionalSurfaces(nodes: VomNode[], captured: CapturedViewModel): CondSurface[] {
-  const probes = captured.surfaceProbes ?? [];
+function buildConditionalSurfaces(
+  nodes: VomNode[],
+  captured: CapturedSceneInput,
+  probes: CapturedSurfaceProbe[],
+): CondSurface[] {
  if (probes.length === 0) return [];

  const surfaces: CondSurface[] = [];
@@ -720,165 +650,14 @@ function findSurfaceNodeByPoint(
 export interface BuildVomSceneOptions {
  pageUrl?: string;
  supplementalNames?: ReadonlyMap<string, string>;
+  surfaceProbes?: CapturedSurfaceProbe[];
 }

 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({
@@ -888,18 +667,19 @@ export function buildFrameVomScene(
    excludedBackendNodeIds: captured.excludedBackendNodeIds,
    supplementalNames: options.supplementalNames,
  });
-  return attachCapturedSceneAnnotations(scene, documents, captured);
+  return attachCapturedSceneAnnotations(scene, documents, captured, options.surfaceProbes ?? []);
 }

 function attachCapturedSceneAnnotations(
  scene: VomScene,
  documents: VomFrameDocument[],
-  captured: CapturedViewModel,
+  captured: CapturedSceneInput,
+  surfaceProbes: CapturedSurfaceProbe[],
 ): VomScene {
  const rootDocument = documents.find((document) => document.frameId === scene.rootFrameId);
  const signals = capturedOnlySignals(rootDocument?.domNodes ?? captured.nodes);
  const activeScopeBlocks = buildActiveScopeBlocks(scene.nodes, signals);
-  const surfaces = buildConditionalSurfaces(scene.nodes, captured);
+  const surfaces = buildConditionalSurfaces(scene.nodes, captured, surfaceProbes);
  return {
    ...scene,
    ...(surfaces.length > 0 ? { surfaces } : {}),
@@ -1043,58 +823,64 @@ export async function handleGetHtml(
  }
 }

-function emptyCapturedViewModel(viewport = { width: 0, height: 0 }): CapturedViewModel {
-  return { viewport, nodes: [], iframeNodes: new Map(), excludedBackendNodeIds: new Set() };
+export interface HoverProbeOutcome {
+  /** Whether any active hover was dispatched during this observation. */
+  performed: boolean;
+  /**
+   * Whether hovering surfaced content absent from the static snapshot. Cached
+   * tooltip names count, so this may over-report on repeat observations — it
+   * errs towards telling the caller the snapshot is less fresh than it looks.
+   */
+  revealedContent: boolean;
+  surfaceProbes: CapturedSurfaceProbe[];
+  tooltipNames: Map<string, string>;
 }

-interface LayoutMetricsViewportReply {
-  cssLayoutViewport?: { clientWidth?: number; clientHeight?: number };
-  layoutViewport?: { clientWidth?: number; clientHeight?: number };
-}
+const NO_HOVER_PROBES: HoverProbeOutcome = {
+  performed: false,
+  revealedContent: false,
+  surfaceProbes: [],
+  tooltipNames: new Map(),
+};

-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(
+/**
+ * Runs both active-hover chains back to back.
+ *
+ * Ordering matters: this happens after DOM *and* accessibility capture so a
+ * hover that opens a menu cannot leave one half of the observation describing
+ * the page before the change and the other half after it. Sharing one overlay
+ * bypass span also means the agent overlay toggles once per observation
+ * instead of once per chain.
+ */
+async function runHoverProbes(
  cdp: CdpRunner,
  tabId: number,
+  captured: CapturedSceneInput,
+  documents: VomFrameDocument[],
+  staticSemantics: ReturnType<typeof resolveSemanticGraph>,
  options: CaptureVomObservationOptions,
-): Promise<CapturedViewModel> {
-  try {
-    return await captureViewModel(cdp, tabId, {
-      conditionalSurfaceProbe: options.conditionalSurfaceProbe ?? false,
-      hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
+): Promise<HoverProbeOutcome> {
+  if (!options.conditionalSurfaceProbe) return NO_HOVER_PROBES;
+
+  return withOverlayBypass(options.hoverProbeBypassOverlay, tabId, async () => {
+    const surfaceProbes = await probeHoverSurfaces(cdp, tabId, captured.nodes, {
      signal: options.signal,
    });
-  } catch (error) {
-    if (isAbortError(error)) throw error;
-    return fallbackCapturedViewModel(cdp, tabId, options.signal);
-  }
+    throwIfAborted(options.signal, "observation");
+    const tooltipNames = await probeTooltipNames(cdp, tabId, documents, staticSemantics, {
+      signal: options.signal,
+    });
+    return {
+      performed: true,
+      revealedContent: surfaceProbes.length > 0 || tooltipNames.size > 0,
+      surfaceProbes,
+      tooltipNames,
+    };
+  });
 }

 export interface CaptureVomObservationOptions extends VomOptions {
  conditionalSurfaceProbe?: boolean;
-  renderedSurfaceDiscovery?: boolean;
  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
  signal?: AbortSignal;
 }
@@ -1108,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,
@@ -1123,44 +904,73 @@ export async function captureVomObservation(
    excludedBackendNodeIds: captured.excludedBackendNodeIds,
  });
  const staticSemantics = resolveSemanticGraph(semanticGraph, { identifierFallback: false });
-  const tooltipNames = options.conditionalSurfaceProbe
-    ? await probeTooltipNames(cdp, tabId, normalizedDocuments, staticSemantics, {
-        signal: options.signal,
-        hoverProbeBypassOverlay: options.hoverProbeBypassOverlay,
-      })
-    : new Map<string, string>();
+  const hoverProbes = await runHoverProbes(
+    cdp,
+    tabId,
+    captured,
+    normalizedDocuments,
+    staticSemantics,
+    options,
+  );
  throwIfAborted(options.signal, "observation");
  const scene = projectSemanticGraph(
    normalizeSemanticStructure(
-      resolveSemanticGraph(semanticGraph, { supplementalNames: tooltipNames }),
+      resolveSemanticGraph(semanticGraph, { supplementalNames: hoverProbes.tooltipNames }),
    ),
  );
-  const decoratedScene = attachCapturedSceneAnnotations(scene, normalizedDocuments, captured);
-  const observedScene = options.renderedSurfaceDiscovery
-    ? projectRenderedSurfaces(
-        decoratedScene,
-        normalizedDocuments,
-        clusterRenderedSurfaces(
-          discoverRenderedSurfaces(
-            normalizedDocuments,
-            captured.viewport,
-            captured.excludedBackendNodeIds,
-          ),
-        ),
-      )
-    : decoratedScene;
-  const rendered = renderVom(observedScene, {
+  const decoratedScene = attachCapturedSceneAnnotations(
+    scene,
+    normalizedDocuments,
+    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 iframe geometry incomplete: some 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",
    frameDocuments: normalizedDocuments,
    rendered,
-    surfaceProbes: captured.surfaceProbes,
+    surfaceProbes: hoverProbes.surfaceProbes,
+    hoverProbe: {
+      performed: hoverProbes.performed,
+      revealedContent: hoverProbes.revealedContent,
+    },
  });
 }

@@ -1200,7 +1010,6 @@ async function handleVomObservation(
      maxTokens: params.max_tokens,
      activeRegionPolicy: true,
      conditionalSurfaceProbe: effectiveConditionalSurfaceProbe,
-      renderedSurfaceDiscovery: toolName === "observe",
      hoverProbeBypassOverlay: deps.hoverProbeBypassOverlay,
      signal,
    });
@@ -1218,9 +1027,6 @@ async function handleVomObservation(
            tabId: target.tabId,
            ...(ref.frameId ? { frameId: ref.frameId } : {}),
            ...(refTarget?.sessionId ? { cdpSessionId: refTarget.sessionId } : {}),
-            ...(ref.visibleRect ? { visibleRect: ref.visibleRect } : {}),
-            ...(ref.kind ? { kind: ref.kind } : {}),
-            ...(ref.capabilities ? { capabilities: ref.capabilities } : {}),
          },
        ] as const;
      }),
@@ -1230,6 +1036,14 @@ async function handleVomObservation(
      ref_count: observation.refs.length,
      tab_id: target.tabId,
      truncated: observation.truncated,
+      ...(toolName === "observe" && observation.hoverProbe?.performed
+        ? {
+            hover_probe: {
+              performed: true,
+              revealed_content: observation.hoverProbe.revealedContent,
+            },
+          }
+        : {}),
      ...(toolName === "observe" && (params as ObserveParams).debug_surfaces
        ? {
            debug: {
@@ -1268,5 +1082,13 @@ export async function handleObserve(
  deps: SnapshotDeps = getDefaultDeps(),
  signal?: AbortSignal,
 ): Promise<ObserveResult | RpcError> {
-  return handleVomObservation(manager, params, "observe", "transient_input", true, deps, signal);
+  return handleVomObservation(
+    manager,
+    params,
+    "observe",
+    "transient_input",
+    params.probe_hover === true,
+    deps,
+    signal,
+  );
 }
@@ -2,6 +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 { CdpRunner, ChromeTabsApi } from "./shared";
 import { isRpcError } from "./shared";
 import { returnBorrowedTab, type TabManagementDeps } from "./tabs";

@@ -73,11 +74,17 @@ export interface SessionStopResult {
  /** Tab ids whose return path failed; those entries remain borrowed so
   *  shutdown can be retried without closing the Agent Window. */
  return_failures?: Array<{ tab_id: number; code: string; message: string }>;
+  /**
+   * True when the Agent Window was *released* to the user (instead of being
+   * closed) because it still contained user-created tabs after the agent's own
+   * tabs were closed. Single-session scope.
+   */
+  window_released?: boolean;
 }

 export interface SessionStopDeps {
  signal?: AbortSignal;
-  cdp?: {
+  cdp?: Pick<CdpRunner, "releaseSessionTab"> & {
    detachSession(sessionId: string): Promise<void>;
  };
  /**
@@ -87,6 +94,13 @@ export interface SessionStopDeps {
   * without a real browser.
   */
  tabManagement?: TabManagementDeps;
+  /**
+   * Read-only Chrome tabs API used to *query* remaining tabs before deciding
+   * whether to release the window. Kept separate from `tabManagement.tabs`
+   * (a `TabMutationApi` that has no `query`) so the mutation interface stays
+   * pure. Tests can inject a fake `ChromeTabsApi` too.
+   */
+  tabsQuery?: ChromeTabsApi;
 }

 /**
@@ -152,8 +166,10 @@ export async function handleSessionStart(
 *      cleanly (review parity with M6).
 *   3. Detach CDP sessions the extension still holds for this
 *      session (no-op if M6/M7 didn't attach to any tab).
- *   4. Close the Agent Window. SessionManager.stop() removes the
- *      Chrome window and forgets the context.
+ *   4. Close the agent-created tabs and the home tab (design §3.2).
+ *   5. If any tab remains — those are user-created tabs — release the
+ *      window to the user (dropOnly) instead of closing it, so user
+ *      tabs survive. Otherwise close the window as before.
 *
 * Failures in step 1 keep the Agent Window open: a failed borrowed tab
 * may still be there, so closing the window would risk losing user
@@ -188,15 +204,19 @@ export async function handleSessionStop(
  const returnFailures: SessionStopResult["return_failures"] = [];
  const borrowedIds = Array.from(ctx.borrowedTabs.keys());
  for (const tabId of borrowedIds) {
+    // A close event may have removed this borrow while another tab returned.
+    if (!ctx.borrowedTabs.has(tabId)) continue;
    try {
      const tabManagement = {
        ...(deps.tabManagement ?? {}),
+        cdp: deps.cdp ?? deps.tabManagement?.cdp,
        signal: deps.signal,
        isAgentWindowId:
          deps.tabManagement?.isAgentWindowId ??
          ((windowId: number) => manager.findByWindowId(windowId) !== null),
      };
      const outcome = await returnBorrowedTab(ctx, tabId, tabManagement);
+      if (!ctx.borrowedTabs.has(tabId)) continue;
      if (typeof outcome === "object" && "code" in outcome) {
        console.warn(`[bsk session_stop] auto-return failed for tab ${tabId}`, outcome);
        returnFailures?.push({
@@ -209,6 +229,7 @@ export async function handleSessionStop(
        ctx.borrowedTabs.delete(tabId);
      }
    } catch (err) {
+      if (!ctx.borrowedTabs.has(tabId)) continue;
      const message = err instanceof Error ? err.message : String(err);
      console.warn(`[bsk session_stop] auto-return threw for tab ${tabId}: ${message}`);
      returnFailures?.push({
@@ -219,8 +240,15 @@ export async function handleSessionStop(
    }
  }

+  // A previously failed tab may have closed during a later return. Only
+  // confirmed close events remove borrows; ordinary move failures stay retryable.
+  const pendingReturnFailures = returnFailures.filter((failure) =>
+    ctx.borrowedTabs.has(failure.tab_id),
+  );
  if (deps.signal?.aborted) {
-    const nonCancelFailures = returnFailures?.filter((failure) => failure.code !== "cancelled");
+    const nonCancelFailures = pendingReturnFailures.filter(
+      (failure) => failure.code !== "cancelled",
+    );
    if (nonCancelFailures && nonCancelFailures.length > 0) {
      return {
        ...(returnedTabIds.length > 0 ? { returned_tab_ids: returnedTabIds } : {}),
@@ -232,8 +260,8 @@ export async function handleSessionStop(

  const result: SessionStopResult = {};
  if (returnedTabIds.length > 0) result.returned_tab_ids = returnedTabIds;
-  if (returnFailures && returnFailures.length > 0) {
-    result.return_failures = returnFailures;
+  if (pendingReturnFailures.length > 0) {
+    result.return_failures = pendingReturnFailures;
    // A failed return means at least one borrowed user tab may still be
    // inside the Agent Window. Keep the session/window alive so the user
    // can retry `bsk session stop` or explicitly `bsk tab return` after the
@@ -243,7 +271,6 @@ export async function handleSessionStop(

  // Step 2: clear the per-session RefStore (review M6/M7 parity).
  ctx.refStore.clear();
-  ctx.surfaceCaptures.clear();

  clearRecordingForSession(params.session_id);

@@ -254,8 +281,66 @@ export async function handleSessionStop(
    return { code: "cancelled", message: "session_stop aborted before window close" };
  }

-  // Step 4: close the Agent Window and drop the context.
-  await manager.stop(params.session_id);
+  // Step 4: close every tab explicitly created by the agent, including the
+  // home tab. `tabsApi` is a
+  // TabMutationApi (remove only); `queryApi` is a separate read-only
+  // ChromeTabsApi. If neither is injected, we conservatively fall back to
+  // closing the window (see Step 5).
+  const tabsApi = deps.tabManagement?.tabs;
+  const queryApi = deps.tabsQuery;
+
+  if (tabsApi) {
+    // Close each agent-created tab that still exists.
+    const agentCreatedTabIds = Array.from(ctx.agentCreatedTabs);
+    for (const tabId of agentCreatedTabIds) {
+      try {
+        await tabsApi.remove(tabId);
+        ctx.agentCreatedTabs.delete(tabId);
+      } catch (err) {
+        // Tab may already be gone (closed by the user). Non-fatal.
+        console.warn(`[bsk session_stop] failed to close agent tab ${tabId}`, err);
+      }
+    }
+  }
+
+  // Step 5: decide whether to release (keep) the window or close it.
+  let shouldRelease = false;
+  if (queryApi) {
+    try {
+      const liveWindowTabs = await queryApi.query({ windowId: ctx.agentWindowId });
+      // Only genuine *user* tabs count toward keeping the window open.
+      // An agent tab that failed to close in Step 4 may still be present
+      // here; if we counted it as a reason to release (dropOnly), the
+      // window would be kept and that agent tab would leak (issue #57
+      // regression). Exclude any id still tracked in agentCreatedTabs.
+      const userTabs = liveWindowTabs.filter((t) => {
+        if (t.id === undefined) return false;
+        return !ctx.agentCreatedTabs.has(t.id);
+      });
+      const leakedAgentTabs = liveWindowTabs.filter(
+        (t) => t.id !== undefined && ctx.agentCreatedTabs.has(t.id),
+      );
+      if (leakedAgentTabs.length > 0) {
+        console.warn(
+          `[bsk session_stop] ${leakedAgentTabs.length} agent tab(s) failed to close; forcing window close instead of release`,
+          leakedAgentTabs.map((t) => t.id),
+        );
+      }
+      shouldRelease = userTabs.length > 0;
+    } catch {
+      // Query failed (e.g. window already gone) — conservatively close it.
+      shouldRelease = false;
+    }
+  }
+
+  if (shouldRelease) {
+    // Keep the window + its user tabs; only drop the session binding.
+    await manager.stop(params.session_id, { dropOnly: true });
+    result.window_released = true;
+  } else {
+    // Window is empty (or we couldn't verify state) — close it.
+    await manager.stop(params.session_id);
+  }

  return result;
 }
@@ -53,9 +53,12 @@ export type { DialogCursor };
 export interface CdpRunner {
  send<T = unknown>(tabId: number, method: string, params?: object): Promise<T>;
  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;
  };
@@ -2,9 +2,8 @@
 // compound CDP node identity via the session RefStore, and build stable
 // `ref_not_found` errors for hard-failure tool paths.

-import type { Rect } from "@browser-skill/vom";
 import type { SessionContext } from "@/session-manager/manager";
-import { normaliseRef, type RefCapability, type RefTargetKind } from "@/session-manager/ref-store";
+import { normaliseRef } from "@/session-manager/ref-store";
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";

@@ -13,10 +12,6 @@ export interface SnapshotRefLookup {
  refKey: string;
  frameId?: string;
  cdpSessionId?: string;
-  visibleRect?: Rect;
-  kind: RefTargetKind;
-  capabilities: RefCapability[];
-  generation: number;
 }

 function refEntryForTab(ctx: SessionContext, refKey: string, tabId: number) {
@@ -42,10 +37,6 @@ export function lookupSnapshotRef(
    refKey,
    ...(entry.frameId ? { frameId: entry.frameId } : {}),
    ...(entry.cdpSessionId ? { cdpSessionId: entry.cdpSessionId } : {}),
-    ...(entry.visibleRect ? { visibleRect: entry.visibleRect } : {}),
-    kind: entry.kind,
-    capabilities: entry.capabilities,
-    generation: entry.generation,
  };
 }

@@ -58,7 +49,6 @@ export function resolveSnapshotRef(
  ctx: SessionContext,
  ref: string,
  tabId: number,
-  requiredCapability?: RefCapability,
 ): SnapshotRefLookup | RpcError {
  const looked = lookupSnapshotRef(ctx, ref, tabId);
  if (looked === null) {
@@ -68,13 +58,5 @@ export function resolveSnapshotRef(
      `ref ${ref} unknown for tab ${tabId} in session ${ctx.sessionId}`,
    );
  }
-  if (requiredCapability && !looked.capabilities.includes(requiredCapability)) {
-    return rpcError(
-      "permission_denied",
-      "ref_capability_denied",
-      `ref ${ref} does not support ${requiredCapability}`,
-      { ref: looked.refKey, required_capability: requiredCapability, kind: looked.kind },
-    );
-  }
  return looked;
 }
@@ -1,88 +0,0 @@
-import type { Rect } from "@browser-skill/vom";
-import type { Point, Region, ViewportRect } from "./geometry";
-
-const RECT_EPSILON = 0.01;
-
-export function surfaceVisibleRect(
-  liveRect: ViewportRect,
-  observedRect: Rect | undefined,
-): Rect | null {
-  const observed = observedRect ?? {
-    x: liveRect.x,
-    y: liveRect.y,
-    w: liveRect.width,
-    h: liveRect.height,
-  };
-  const x = Math.max(liveRect.x, observed.x);
-  const y = Math.max(liveRect.y, observed.y);
-  const right = Math.min(liveRect.x + liveRect.width, observed.x + observed.w);
-  const bottom = Math.min(liveRect.y + liveRect.height, observed.y + observed.h);
-  return right > x && bottom > y ? { x, y, w: right - x, h: bottom - y } : null;
-}
-
-export function sameRect(a: Rect, b: Rect): boolean {
-  return (
-    Math.abs(a.x - b.x) <= RECT_EPSILON &&
-    Math.abs(a.y - b.y) <= RECT_EPSILON &&
-    Math.abs(a.w - b.w) <= RECT_EPSILON &&
-    Math.abs(a.h - b.h) <= RECT_EPSILON
-  );
-}
-
-export function mapImagePointToViewport(
-  rect: Rect,
-  imageWidth: number,
-  imageHeight: number,
-  imageX: number,
-  imageY: number,
-): Point | null {
-  if (
-    !Number.isFinite(imageX) ||
-    !Number.isFinite(imageY) ||
-    !Number.isSafeInteger(imageWidth) ||
-    !Number.isSafeInteger(imageHeight) ||
-    imageWidth <= 0 ||
-    imageHeight <= 0 ||
-    imageX < 0 ||
-    imageY < 0 ||
-    imageX >= imageWidth ||
-    imageY >= imageHeight ||
-    !Number.isFinite(rect.x) ||
-    !Number.isFinite(rect.y) ||
-    !Number.isFinite(rect.w) ||
-    !Number.isFinite(rect.h) ||
-    rect.w <= 0 ||
-    rect.h <= 0
-  ) {
-    return null;
-  }
-  return {
-    x: rect.x + (imageX / imageWidth) * rect.w,
-    y: rect.y + (imageY / imageHeight) * rect.h,
-  };
-}
-
-function pointInPolygon(point: Point, polygon: Point[]): boolean {
-  for (let index = 0; index < polygon.length; index += 1) {
-    const a = polygon[index];
-    const b = polygon[(index + 1) % polygon.length];
-    const cross = (point.x - a.x) * (b.y - a.y) - (point.y - a.y) * (b.x - a.x);
-    const withinX = point.x >= Math.min(a.x, b.x) - 1e-9 && point.x <= Math.max(a.x, b.x) + 1e-9;
-    const withinY = point.y >= Math.min(a.y, b.y) - 1e-9 && point.y <= Math.max(a.y, b.y) + 1e-9;
-    if (Math.abs(cross) <= 1e-9 && withinX && withinY) return true;
-  }
-  let inside = false;
-  for (let index = 0, previous = polygon.length - 1; index < polygon.length; previous = index++) {
-    const a = polygon[index];
-    const b = polygon[previous];
-    const intersects =
-      a.y > point.y !== b.y > point.y &&
-      point.x < ((b.x - a.x) * (point.y - a.y)) / (b.y - a.y) + a.x;
-    if (intersects) inside = !inside;
-  }
-  return inside;
-}
-
-export function pointInRegion(point: Point, region: Region): boolean {
-  return region.some((polygon) => polygon.length >= 3 && pointInPolygon(point, polygon));
-}
@@ -1,260 +0,0 @@
-import type { CdpFrameGraph } from "@/browser-driver/frame-graph";
-import type { SessionContext } from "@/session-manager/manager";
-import type { RpcError } from "@/transport/types";
-import { rpcError } from "./errors";
-import { resolveNodeGeometry } from "./frame-geometry";
-import { type CdpRunner, isRpcError, normaliseRef } from "./shared";
-import { resolveSnapshotRef } from "./snapshot-ref";
-import {
-  mapImagePointToViewport,
-  pointInRegion,
-  sameRect,
-  surfaceVisibleRect,
-} from "./surface-coordinate";
-
-export interface SurfaceCaptureEnvironment {
-  navigationIdentity: string;
-  viewportSignature: string;
-  frameProjectionSignature: string;
-}
-
-export interface SurfaceTargetResolverDeps {
-  cdp: CdpRunner;
-  signal?: AbortSignal;
-}
-
-export interface SurfacePointerTargetInput {
-  ref?: string;
-  selector?: string;
-  captureId?: string;
-  imageX?: number;
-  imageY?: number;
-}
-
-export interface ResolvedSurfacePointerTarget {
-  point: { x: number; y: number };
-  usedRef: string;
-  moveSettleMs: number;
-  capture: {
-    id: string;
-    imageX: number;
-    imageY: number;
-  };
-}
-
-// Canvas-style controls commonly update their pointer hit-test on the next
-// animation frame. Leave a scheduling boundary after moving and before pressing.
-export const SURFACE_POINTER_MOVE_SETTLE_MS = 32;
-
-function stale(message: string): RpcError {
-  return rpcError("permission_denied", "surface_capture_stale", message);
-}
-
-function finiteObject(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(finiteObject);
-  if (typeof value !== "object" || value === null) return value;
-  return Object.fromEntries(
-    Object.entries(value)
-      .filter(
-        ([, entry]) => entry !== undefined && (typeof entry !== "number" || Number.isFinite(entry)),
-      )
-      .sort(([a], [b]) => a.localeCompare(b))
-      .map(([key, entry]) => [key, finiteObject(entry)]),
-  );
-}
-
-function framePathSignature(graph: CdpFrameGraph, frameId: string | undefined): string | null {
-  if (!frameId) return "top";
-  const frames = new Map(graph.frames.map((frame) => [frame.frameId, frame]));
-  const path: Array<{
-    frameId: string;
-    parentFrameId?: string;
-    ownerBackendNodeId?: number;
-    targetSessionId?: string;
-  }> = [];
-  const seen = new Set<string>();
-  let current = frames.get(frameId);
-  while (current) {
-    if (seen.has(current.frameId)) return null;
-    seen.add(current.frameId);
-    path.push({
-      frameId: current.frameId,
-      ...(current.parentFrameId ? { parentFrameId: current.parentFrameId } : {}),
-      ...(current.ownerBackendNodeId !== undefined
-        ? { ownerBackendNodeId: current.ownerBackendNodeId }
-        : {}),
-      ...(current.target.sessionId ? { targetSessionId: current.target.sessionId } : {}),
-    });
-    if (!current.parentFrameId) return JSON.stringify(path);
-    const parent = frames.get(current.parentFrameId);
-    if (!parent) return null;
-    current = parent;
-  }
-  return null;
-}
-
-export async function captureSurfaceEnvironment(
-  cdp: CdpRunner,
-  tabId: number,
-  frameId: string | undefined,
-): Promise<SurfaceCaptureEnvironment | RpcError> {
-  try {
-    const [tree, metrics, graph] = await Promise.all([
-      cdp.send<{
-        frameTree?: { frame?: { id?: string; loaderId?: string; url?: string } };
-      }>(tabId, "Page.getFrameTree", {}),
-      cdp.send<Record<string, unknown>>(tabId, "Page.getLayoutMetrics", {}),
-      frameId && cdp.getFrameGraph ? cdp.getFrameGraph(tabId) : Promise.resolve(null),
-    ]);
-    const root = tree.frameTree?.frame;
-    if (!root?.id || !root.loaderId) {
-      return { code: "cdp_failed", message: "could not identify the current navigation" };
-    }
-    const frameProjectionSignature = frameId
-      ? graph
-        ? framePathSignature(graph, frameId)
-        : null
-      : "top";
-    if (!frameProjectionSignature) {
-      return { code: "cdp_failed", message: `could not identify frame projection for ${frameId}` };
-    }
-    return {
-      navigationIdentity: JSON.stringify({ id: root.id, loaderId: root.loaderId, url: root.url }),
-      viewportSignature: JSON.stringify(
-        finiteObject({
-          cssLayoutViewport: metrics.cssLayoutViewport,
-          cssVisualViewport: metrics.cssVisualViewport,
-        }),
-      ),
-      frameProjectionSignature,
-    };
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-}
-
-function validatePointParams(input: SurfacePointerTargetInput): RpcError | null {
-  if (!input.captureId || typeof input.captureId !== "string") {
-    return { code: "invalid_params", message: "surface point click requires capture_id" };
-  }
-  if (typeof input.imageX !== "number" || !Number.isFinite(input.imageX)) {
-    return { code: "invalid_params", message: "image_x must be a finite number" };
-  }
-  if (typeof input.imageY !== "number" || !Number.isFinite(input.imageY)) {
-    return { code: "invalid_params", message: "image_y must be a finite number" };
-  }
-  if (!input.ref || input.selector) {
-    return {
-      code: "invalid_params",
-      message: "surface point click requires one Surface ref and does not accept a selector",
-    };
-  }
-  return null;
-}
-
-function captureConsumeError(reason: "not_found" | "expired" | "consumed"): RpcError {
-  const code = reason === "not_found" ? "not_found" : "permission_denied";
-  return rpcError(code, `surface_capture_${reason}`, `surface capture is ${reason}`);
-}
-
-function aborted(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted
-    ? { code: "cancelled", message: "surface target resolution aborted" }
-    : null;
-}
-
-/** Resolve one fresh Surface capture coordinate into a validated top-viewport pointer target. */
-export async function resolveSurfacePointerTarget(
-  ctx: SessionContext,
-  target: { tabId: number; url?: string },
-  input: SurfacePointerTargetInput,
-  deps: SurfaceTargetResolverDeps,
-): Promise<ResolvedSurfacePointerTarget | RpcError> {
-  const invalid = validatePointParams(input);
-  if (invalid) return invalid;
-  const earlyAbort = aborted(deps.signal);
-  if (earlyAbort) return earlyAbort;
-
-  const consumed = ctx.surfaceCaptures.consume(input.captureId as string);
-  if (!consumed.ok) return captureConsumeError(consumed.reason);
-  const capture = consumed.capture;
-  const postConsumeAbort = aborted(deps.signal);
-  if (postConsumeAbort) return postConsumeAbort;
-
-  if (capture.sessionId !== ctx.sessionId || capture.tabId !== target.tabId) {
-    return stale("surface capture belongs to a different session or tab");
-  }
-  if (normaliseRef(input.ref as string) !== capture.surface.ref) {
-    return stale("surface ref does not match the capture");
-  }
-  const node = resolveSnapshotRef(ctx, input.ref as string, target.tabId, "screenshot");
-  if (isRpcError(node)) return stale(node.message);
-  if (
-    node.kind !== "surface" ||
-    node.backendNodeId !== capture.surface.backendNodeId ||
-    node.frameId !== capture.surface.frameId ||
-    node.generation !== capture.surface.observationGeneration
-  ) {
-    return stale("surface observation generation or node identity changed");
-  }
-
-  deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-  try {
-    await deps.cdp.ensureAttachedToUrl?.(target.tabId, target.url);
-  } catch (error) {
-    return { code: "cdp_failed", message: error instanceof Error ? error.message : String(error) };
-  }
-  const environment = await captureSurfaceEnvironment(deps.cdp, target.tabId, node.frameId);
-  if (isRpcError(environment)) return environment;
-  if (
-    environment.navigationIdentity !== capture.navigationIdentity ||
-    environment.viewportSignature !== capture.viewportSignature ||
-    environment.frameProjectionSignature !== capture.frameProjectionSignature
-  ) {
-    return stale("navigation, viewport, zoom, scroll, or frame projection changed");
-  }
-
-  const geometry = await resolveNodeGeometry(
-    deps.cdp,
-    target.tabId,
-    {
-      target: {
-        tabId: target.tabId,
-        ...(node.cdpSessionId ? { sessionId: node.cdpSessionId } : {}),
-      },
-      backendNodeId: node.backendNodeId,
-      ...(node.frameId ? { frameId: node.frameId } : {}),
-    },
-    { scrollIntoView: false },
-  );
-  if (isRpcError(geometry)) return stale(geometry.message);
-  const currentRect = surfaceVisibleRect(geometry.topBounds, node.visibleRect);
-  if (!currentRect || !sameRect(currentRect, capture.topViewportRect)) {
-    return stale("surface visible region changed");
-  }
-  const point = mapImagePointToViewport(
-    capture.topViewportRect,
-    capture.imageWidth,
-    capture.imageHeight,
-    input.imageX as number,
-    input.imageY as number,
-  );
-  if (!point || !pointInRegion(point, geometry.topVisibleRegions)) {
-    return rpcError(
-      "invalid_params",
-      "surface_coordinate_invalid",
-      "image coordinate is outside the captured Surface",
-    );
-  }
-
-  return {
-    point,
-    usedRef: capture.surface.ref,
-    moveSettleMs: SURFACE_POINTER_MOVE_SETTLE_MS,
-    capture: {
-      id: capture.id,
-      imageX: input.imageX as number,
-      imageY: input.imageY as number,
-    },
-  };
-}
@@ -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
@@ -369,6 +373,7 @@ function buildCreateProps(
 * Returns the created tab on success, or an `RpcError` on failure.
 */
 async function createTabAndCleanup(
+  ctx: SessionContext,
  deps: TabManagementDeps,
  createProps: chrome.tabs.CreateProperties,
 ): Promise<CreatedChromeTab | RpcError> {
@@ -381,25 +386,28 @@ async function createTabAndCleanup(
      message: err instanceof Error ? err.message : String(err),
    };
  }
-  if (aborted(deps.signal, "tab_create")) {
-    // We already opened the tab; close it on abort so we don't leak.
-    if (typeof tab.id === "number") {
-      try {
-        await getTabsApi(deps).remove(tab.id);
-      } catch (cleanupErr) {
-        return rpcError(
-          "protocol_error",
-          "cleanup_failed",
-          `tab_create aborted but cleanup of tab ${tab.id} failed: ${describeError(cleanupErr)}`,
-          { resource_type: "tab", resource_id: tab.id },
-        );
-      }
-    }
-    return { code: "cancelled", message: "tab_create aborted" };
-  }
  if (typeof tab.id !== "number") {
    return { code: "protocol_error", message: "chrome.tabs.create returned no tab id" };
  }
+  // Claim the concrete id returned by Chrome. Ownership never depends on
+  // matching this request to an asynchronous onCreated event.
+  ctx.agentCreatedTabs.add(tab.id);
+  if (aborted(deps.signal, "tab_create")) {
+    try {
+      await getTabsApi(deps).remove(tab.id);
+      ctx.agentCreatedTabs.delete(tab.id);
+    } catch (cleanupErr) {
+      // Keep the claim when cleanup fails so session_stop can retry instead
+      // of releasing an agent-owned tab to the user.
+      return rpcError(
+        "protocol_error",
+        "cleanup_failed",
+        `tab_create aborted but cleanup of tab ${tab.id} failed: ${describeError(cleanupErr)}`,
+        { resource_type: "tab", resource_id: tab.id },
+      );
+    }
+    return { code: "cancelled", message: "tab_create aborted" };
+  }
  return { ...tab, id: tab.id };
 }

@@ -426,7 +434,7 @@ export async function handleTabCreate(
  const paramErr = validateTabCreateParams(params);
  if (paramErr) return paramErr;

-  const tab = await createTabAndCleanup(deps, buildCreateProps(ctx, params));
+  const tab = await createTabAndCleanup(ctx, deps, buildCreateProps(ctx, params));
  if (isRpcError(tab)) return tab;

  return {
@@ -526,6 +534,9 @@ export async function handleTabClose(
  }
  try {
    await getTabsApi(deps).remove(params.tab_id);
+    // Keep the tracking set accurate so session_stop won't try to close a
+    // tab that's already gone (design §3.1).
+    ctx.agentCreatedTabs.delete(params.tab_id);
  } catch (err) {
    return {
      code: "protocol_error",
@@ -753,13 +764,6 @@ async function executeBorrowCore(
  );
  if (moveErr) return moveErr;

-  // Best-effort activation — failure is non-fatal.
-  try {
-    await p.tabsApi.update(p.tabId, { active: true });
-  } catch (err) {
-    console.debug("[bsk tab_borrow] activate after move failed", err);
-  }
-
  return { originalWindowId, originalIndex };
 }

@@ -823,6 +827,12 @@ export async function handleTabBorrow(
        message: err instanceof Error ? err.message : String(err),
      };
    }
+    // Activate after commit so overlay/event observers see the tab as claimed.
+    try {
+      await tabsApi.update(params.tab_id, { active: true });
+    } catch (err) {
+      console.debug("[bsk tab_borrow] activate after move failed", err);
+    }
    return {
      tab_id: params.tab_id,
      original_window_id: coreResult.originalWindowId,
@@ -939,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);
+  }
 }

 /**
@@ -1022,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,
@@ -1064,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,
@@ -1110,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:
@@ -1,194 +0,0 @@
-// Browser-native text entry for live editing sessions. Unlike fill, this
-// module does not assume that the focused editable retains a DOM value: a
-// Canvas editor may use an input/textarea only as a transient keyboard/IME
-// sink and clear it after consuming each event.
-
-import type { RpcError } from "@/transport/types";
-import type { CdpRunner } from "./shared";
-
-function cancelled(signal: AbortSignal | undefined): RpcError | null {
-  return signal?.aborted ? { code: "cancelled", message: "type aborted" } : null;
-}
-
-interface KeyDescriptor {
-  key: string;
-  code: string;
-  windowsVirtualKeyCode: number;
-  nativeVirtualKeyCode?: number;
-  modifiers: number;
-}
-
-function asciiKeyDescriptor(character: string): KeyDescriptor {
-  if (/^[a-z]$/.test(character)) {
-    return {
-      key: character,
-      code: `Key${character.toUpperCase()}`,
-      windowsVirtualKeyCode: character.toUpperCase().charCodeAt(0),
-      modifiers: 0,
-    };
-  }
-  if (/^[A-Z]$/.test(character)) {
-    return {
-      key: character,
-      code: `Key${character}`,
-      windowsVirtualKeyCode: character.charCodeAt(0),
-      modifiers: 8,
-    };
-  }
-  if (/^[0-9]$/.test(character)) {
-    return {
-      key: character,
-      code: `Digit${character}`,
-      windowsVirtualKeyCode: character.charCodeAt(0),
-      modifiers: 0,
-    };
-  }
-  if (character === " ") {
-    return { key: " ", code: "Space", windowsVirtualKeyCode: 32, modifiers: 0 };
-  }
-  return {
-    key: character,
-    code: "",
-    windowsVirtualKeyCode: character.charCodeAt(0),
-    modifiers: 0,
-  };
-}
-
-/**
- * Run one complete browser key transaction and always release the key. The
- * commit callback owns the text-producing phase: a `char` event for a
- * keyboard character, or `Input.insertText` for committed IME text.
- */
-async function dispatchKeyTransaction(
-  cdp: CdpRunner,
-  tabId: number,
-  descriptor: KeyDescriptor,
-  commit: () => Promise<void>,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  let keyDown = false;
-  try {
-    await cdp.send(tabId, "Input.dispatchKeyEvent", {
-      type: "rawKeyDown",
-      ...descriptor,
-    });
-    keyDown = true;
-    const abortedAfterDown = cancelled(signal);
-    if (!abortedAfterDown) await commit();
-    await cdp.send(tabId, "Input.dispatchKeyEvent", {
-      type: "keyUp",
-      ...descriptor,
-    });
-    keyDown = false;
-    return abortedAfterDown ?? cancelled(signal);
-  } catch (err) {
-    if (keyDown) {
-      try {
-        await cdp.send(tabId, "Input.dispatchKeyEvent", {
-          type: "keyUp",
-          ...descriptor,
-        });
-      } catch {
-        // Best-effort cleanup keeps the page from observing a stuck key.
-      }
-    }
-    throw err;
-  }
-}
-
-async function typeAsciiCharacter(
-  cdp: CdpRunner,
-  tabId: number,
-  character: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const descriptor = asciiKeyDescriptor(character);
-  return dispatchKeyTransaction(
-    cdp,
-    tabId,
-    descriptor,
-    async () => {
-      await cdp.send(tabId, "Input.dispatchKeyEvent", {
-        type: "char",
-        ...descriptor,
-        text: character,
-        unmodifiedText: character,
-      });
-    },
-    signal,
-  );
-}
-
-async function typeImeSegment(
-  cdp: CdpRunner,
-  tabId: number,
-  text: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const abortedBefore = cancelled(signal);
-  if (abortedBefore) return abortedBefore;
-
-  // A committed IME value is still part of a keyboard transaction. The
-  // Process key (VK_PROCESSKEY / 229) is the platform-neutral signal that an
-  // IME owns the keystroke. It lets selection-based editors enter text mode
-  // before insertText commits the Unicode value, without inventing a visible
-  // ASCII prefix or leaving a composition transaction open.
-  const processKey: KeyDescriptor = {
-    key: "Process",
-    code: "",
-    windowsVirtualKeyCode: 229,
-    nativeVirtualKeyCode: 229,
-    modifiers: 0,
-  };
-  return dispatchKeyTransaction(
-    cdp,
-    tabId,
-    processKey,
-    () => cdp.send(tabId, "Input.insertText", { text }).then(() => undefined),
-    signal,
-  );
-}
-
-/**
- * Dispatch text through the browser's keyboard/IME pipelines. ASCII runs are
- * delivered as physical-key-shaped events; non-ASCII runs use CDP's committed
- * IME/software-keyboard insertion path. Successful return means the browser
- * accepted the input commands, not that a DOM value retained the text.
- */
-export async function dispatchTextInput(
-  cdp: CdpRunner,
-  tabId: number,
-  text: string,
-  signal?: AbortSignal,
-): Promise<RpcError | null> {
-  const abortedBefore = cancelled(signal);
-  if (abortedBefore) return abortedBefore;
-
-  const segments: Array<{ ime: boolean; text: string }> = [];
-  for (const character of text) {
-    const ime = character.codePointAt(0)! > 0x7f;
-    const previous = segments.at(-1);
-    if (previous?.ime === ime) previous.text += character;
-    else segments.push({ ime, text: character });
-  }
-
-  try {
-    for (const segment of segments) {
-      if (segment.ime) {
-        const error = await typeImeSegment(cdp, tabId, segment.text, signal);
-        if (error) return error;
-        continue;
-      }
-      for (const character of segment.text) {
-        const error = await typeAsciiCharacter(cdp, tabId, character, signal);
-        if (error) return error;
-      }
-    }
-    return null;
-  } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
@@ -0,0 +1,42 @@
+// Shared time boundary for browser-side file-transfer transactions. Concrete
+// upload/download mechanisms own their state machines and effect semantics.
+
+export class BoundedWaitError extends Error {
+  constructor(
+    readonly kind: "timeout" | "aborted",
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+export function remainingMs(deadline: number): number {
+  return Math.max(0, deadline - Date.now());
+}
+
+export async function waitBounded<T>(
+  promise: Promise<T>,
+  deadline: number,
+  signal: AbortSignal | undefined,
+  timeoutMessage: string,
+): Promise<T> {
+  const remaining = remainingMs(deadline);
+  if (signal?.aborted) throw new BoundedWaitError("aborted", "file transfer aborted");
+  if (remaining === 0) throw new BoundedWaitError("timeout", timeoutMessage);
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const boundary = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new BoundedWaitError("timeout", timeoutMessage)), remaining);
+    if (signal) {
+      onAbort = () => reject(new BoundedWaitError("aborted", "file transfer aborted"));
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+  try {
+    return await Promise.race([promise, boundary]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
@@ -0,0 +1,85 @@
+// Upload orchestration: validate the session-scoped request, resolve its click
+// target, then delegate the browser protocol transaction to the file-input
+// transaction module.
+
+import {
+  type CaptureSuppressSendToTab,
+  withExtensionOverlayHidden,
+} from "@/lib/capture-suppress-bridge";
+import type { SessionManager } from "@/session-manager/manager";
+import type { RpcError, UploadParams, UploadResult } from "@/transport/types";
+import { uploadThroughFileDrop } from "./file-drop-transaction";
+import { uploadThroughActivatedFileInput } from "./file-input-transaction";
+import { clickResolvedTarget, type InteractionDeps, resolveActionTarget } from "./interaction";
+import {
+  type CdpRunner,
+  enforceAgentWindow,
+  isRpcError,
+  lookupSession,
+  resolveTargetTab,
+} from "./shared";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface UploadDeps extends InteractionDeps {
+  cdp: CdpRunner;
+  sendToTab?: CaptureSuppressSendToTab;
+}
+
+export async function handleUpload(
+  manager: SessionManager,
+  params: UploadParams,
+  deps: UploadDeps,
+): Promise<UploadResult | RpcError> {
+  const ctx = lookupSession(manager, params, "upload");
+  if (isRpcError(ctx)) return ctx;
+  const target = await resolveTargetTab(manager, ctx, params.tab_id, deps.tabsApi);
+  if (isRpcError(target)) return target;
+  const denied = enforceAgentWindow(ctx, target, "upload");
+  if (denied) return denied;
+  if (
+    params.files.length === 0 ||
+    params.files.length > 20 ||
+    params.files.some((file) => !file.staged_path)
+  ) {
+    return { code: "invalid_params", message: "upload requires daemon-staged files" };
+  }
+  const address = await resolveActionTarget(deps.cdp, ctx, target, params, "upload");
+  if (isRpcError(address)) return address;
+  const timeoutMs = params.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const files = params.files.map((file) => file.staged_path as string);
+  const mode = params.mode ?? "input";
+  let usedRef = address.usedRef;
+  let usedSelector = address.usedSelector;
+  if (mode === "drop") {
+    deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
+    const transaction = await uploadThroughFileDrop({
+      cdp: deps.cdp,
+      actionTarget: address,
+      files,
+      timeoutMs,
+      signal: deps.signal,
+      withOverlayHidden: (operation) =>
+        withExtensionOverlayHidden(target.tabId, operation, deps.sendToTab),
+    });
+    if (isRpcError(transaction)) return transaction;
+  } else {
+    const transaction = await uploadThroughActivatedFileInput({
+      cdp: deps.cdp,
+      actionTarget: address,
+      files,
+      timeoutMs,
+      signal: deps.signal,
+      trigger: () => clickResolvedTarget(ctx, address, {}, deps),
+    });
+    if (isRpcError(transaction)) return transaction;
+    usedRef = transaction.click.used_ref;
+    usedSelector = transaction.click.used_selector;
+  }
+  return {
+    tab_id: target.tabId,
+    used_ref: usedRef,
+    used_selector: usedSelector,
+    file_names: params.files.map((file) => file.name),
+  };
+}
@@ -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 } 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],
@@ -215,33 +220,39 @@ function makeCdp(snapshot: unknown) {
      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 });
@@ -251,35 +262,13 @@ describe("captureViewModel", () => {
    expect(input?.attrs).toEqual({ type: "password" });
  });

-  it("does not run conditional surface probes by default", async () => {
+  it("never hovers the page while capturing", async () => {
    const cdp = makeCdp(fakeSnapshotReply());
-    const result = await captureViewModel(cdp, 4);
+    semanticCapture(await captureObservationFacts(cdp, 4)).captured;

-    expect(result.surfaceProbes).toEqual([]);
    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 = {
@@ -319,9 +308,10 @@ describe("captureViewModel", () => {
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };

-    const result = await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);

-    expect(result.surfaceProbes).toEqual([
+    expect(surfaceProbes).toEqual([
      {
        triggerBackendNodeId: 12,
        triggerPoint: { x: 956, y: 32 },
@@ -378,9 +368,10 @@ describe("captureViewModel", () => {
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };

-    const result = await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    const surfaceProbes = await probeHoverSurfaces(cdp, 4, captured.nodes);

-    expect(result.surfaceProbes).toEqual([
+    expect(surfaceProbes).toEqual([
      expect.objectContaining({
        triggerBackendNodeId: 12,
        subItems: ["My profile", "Sign out"],
@@ -422,7 +413,8 @@ describe("captureViewModel", () => {
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };

-    await captureViewModel(cdp, 4, { conditionalSurfaceProbe: true });
+    const captured = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    await probeHoverSurfaces(cdp, 4, captured.nodes);

    expect(hoverMoves).toBe(1);
  });
@@ -453,6 +445,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")],
@@ -483,7 +476,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);
@@ -514,6 +507,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")],
@@ -544,7 +538,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]));
  });

@@ -565,6 +561,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          nodes: {
            parentIndex: [-1, 0, 1],
            nodeName: [i("html"), i("body"), i(OVERLAY_HOST_NAME)],
@@ -587,7 +584,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]));
  });
@@ -610,6 +609,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          nodes: {
            parentIndex: [-1, 0, 1],
            nodeName: [i("html"), i("body"), i("div")],
@@ -632,7 +632,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]));
  });
@@ -655,6 +657,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          nodes: {
            parentIndex: [-1, 0, 1],
            nodeName: [i("html"), i("body"), i("div")],
@@ -677,7 +680,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");
  });
@@ -689,6 +692,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")],
@@ -715,51 +719,13 @@ 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);
    expect(nodes.find((node) => node.backendNodeId === 14)?.rendered).toBe(false);
  });

-  it("propagates fully transparent ancestor suppression to painted descendants", async () => {
-    const S = ["html", "body", "div", "canvas", "static", "auto", "visible", "1", "0"];
-    const i = (value: string) => S.indexOf(value);
-    const snapshot = {
-      strings: S,
-      documents: [
-        {
-          nodes: {
-            parentIndex: [-1, 0, 1, 2],
-            nodeName: [i("html"), i("body"), i("div"), i("canvas")],
-            backendNodeId: [10, 11, 12, 13],
-            attributes: [[], [], [], []],
-          },
-          layout: {
-            nodeIndex: [1, 2, 3],
-            styles: [
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("0")],
-              [i("static"), i("auto"), i("auto"), i("visible"), i("1")],
-            ],
-            bounds: [
-              [0, 0, 1000, 800],
-              [10, 10, 200, 100],
-              [10, 10, 200, 100],
-            ],
-            paintOrders: [0, 1, 2],
-          },
-        },
-      ],
-    };
-
-    const { nodes } = await captureViewModel(makeCdp(snapshot), 4);
-    const canvas = nodes.find((node) => node.backendNodeId === 13);
-
-    expect(canvas?.rendered).toBe(true);
-    expect(canvas?.visuallySuppressed).toBe(true);
-  });
-
  it("subtracts scroll offset to make rects viewport-relative", async () => {
    const cdp = {
      send: vi.fn(async (_t: number, method: string) => {
@@ -773,19 +739,20 @@ 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;
    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("keeps CSS snapshot bounds independent of legacy 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")],
@@ -820,13 +787,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: 2000,
+      h: 1600,
+    });
  });

  it("extracts textContent from #text child nodes via nodeValue", async () => {
@@ -850,6 +823,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          scrollOffsetX: 0,
          scrollOffsetY: 0,
          nodes: {
@@ -888,7 +862,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;
    const btn = nodes.find((n) => n.backendNodeId === 12);
    expect(btn?.textContent).toBe("登录");
    const link = nodes.find((n) => n.backendNodeId === 14);
@@ -898,7 +872,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",
@@ -975,36 +949,33 @@ describe("captureViewModel", () => {
            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",
@@ -1022,6 +993,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          scrollOffsetX: 0,
          scrollOffsetY: 0,
          nodes: {
@@ -1039,6 +1011,7 @@ describe("captureViewModel", () => {
          },
        },
        {
+          frameId: "child",
          scrollOffsetX: 0,
          scrollOffsetY: 0,
          nodes: {
@@ -1065,15 +1038,23 @@ describe("captureViewModel", () => {
            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 () => {
@@ -1094,6 +1075,7 @@ describe("captureViewModel", () => {
      strings: S,
      documents: [
        {
+          frameId: "root",
          nodes: {
            parentIndex: [-1, 0, 1],
            nodeName: [i("html"), i("body"), i("iframe")],
@@ -1115,6 +1097,7 @@ describe("captureViewModel", () => {
          },
        },
        {
+          frameId: "child",
          nodes: {
            parentIndex: [-1, 0, 1],
            nodeName: [i("html"), i("body"), i("iframe")],
@@ -1136,6 +1119,7 @@ describe("captureViewModel", () => {
          },
        },
        {
+          frameId: "nested",
          nodes: {
            parentIndex: [-1, 0],
            nodeName: [i("body"), i("input")],
@@ -1152,21 +1136,52 @@ 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 {
+              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 });
@@ -1175,13 +1190,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")],
@@ -1216,8 +1232,8 @@ describe("captureViewModel", () => {
        throw new Error(method);
      }) as unknown as <T>(tabId: number, method: string, params?: object) => Promise<T>,
    };
-    const { nodes } = await captureViewModel(cdp, 4);
-    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 / 2 - 100);
+    const { nodes } = semanticCapture(await captureObservationFacts(cdp, 4)).captured;
+    expect(nodes.find((n) => n.backendNodeId === 12)?.rect?.y).toBe(400 - 100);
  });

  it("collectOverlayExcludedBackendIds walks the pierced overlay host subtree", async () => {
@@ -0,0 +1,127 @@
+import { describe, expect, it, vi } from "vitest";
+import { OVERLAY_HOST_MARKER_ATTR } from "@/lib/overlay-bridge";
+import { createCaptureCheckpoint } from "../capture-abort";
+import { buildDocumentIndex, type DecodedNode } from "../facts";
+import { decodeDocument, REQUESTED_STYLES } from "../snapshot";
+
+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-css",
+      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);
+  });
+});
@@ -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());
+  });
+});
@@ -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 } }),
-    );
-  });
-});
@@ -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");
+  });
 });
@@ -0,0 +1,84 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ProbeBudget, resetOverlayBypassDepth, withOverlayBypass } from "../hover-perception";
+
+afterEach(() => {
+  resetOverlayBypassDepth();
+});
+
+describe("ProbeBudget", () => {
+  it("refuses a candidate that cannot finish inside the budget", () => {
+    const budget = new ProbeBudget(500);
+
+    expect(budget.canAfford(400)).toBe(true);
+    expect(budget.canAfford(600)).toBe(false);
+  });
+
+  it("stops admitting candidates once the remaining budget is smaller than one", async () => {
+    const budget = new ProbeBudget(60);
+    await new Promise((resolve) => setTimeout(resolve, 40));
+
+    // A top-of-loop `elapsed > total` check would still admit this candidate
+    // and then overshoot by its full cost.
+    expect(budget.canAfford(50)).toBe(false);
+  });
+});
+
+describe("withOverlayBypass", () => {
+  it("toggles the overlay once around nested probe phases", async () => {
+    const bypass = vi.fn(async () => {});
+
+    await withOverlayBypass(bypass, 4, async () => {
+      await withOverlayBypass(bypass, 4, async () => {
+        expect(bypass).toHaveBeenCalledTimes(1);
+      });
+      expect(bypass).toHaveBeenCalledTimes(1);
+    });
+
+    expect(bypass.mock.calls).toEqual([
+      [4, true],
+      [4, false],
+    ]);
+  });
+
+  it("restores the overlay when the probe throws", async () => {
+    const bypass = vi.fn(async () => {});
+
+    await expect(
+      withOverlayBypass(bypass, 4, async () => {
+        throw new Error("probe exploded");
+      }),
+    ).rejects.toThrow("probe exploded");
+
+    expect(bypass).toHaveBeenLastCalledWith(4, false);
+  });
+
+  it("reports a failed restore instead of swallowing it", async () => {
+    const onRestoreFailure = vi.fn();
+    const bypass = vi.fn(async (_tabId: number, enabled: boolean) => {
+      if (!enabled) throw new Error("tab is gone");
+    });
+
+    await withOverlayBypass(bypass, 4, async () => undefined, { onRestoreFailure });
+
+    expect(onRestoreFailure).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not pin the overlay off for the tab when a restore fails", async () => {
+    const failing = vi.fn(async (_tabId: number, enabled: boolean) => {
+      if (!enabled) throw new Error("tab is gone");
+    });
+    await withOverlayBypass(failing, 4, async () => undefined, { onRestoreFailure: () => {} });
+
+    const bypass = vi.fn(async () => {});
+    await withOverlayBypass(bypass, 4, async () => undefined);
+
+    expect(bypass.mock.calls).toEqual([
+      [4, true],
+      [4, false],
+    ]);
+  });
+
+  it("runs the probe untouched when no bypass is wired up", async () => {
+    await expect(withOverlayBypass(undefined, 4, async () => "done")).resolves.toBe("done");
+  });
+});
@@ -132,6 +132,37 @@ describe("tooltip name enrichment", () => {
    expect(cdp.sendToTarget).not.toHaveBeenCalled();
  });

+  it("remembers controls that revealed no tooltip so the miss is paid once", async () => {
+    const cdp: CdpRunner = {
+      send: vi.fn(async () => ({})) as CdpRunner["send"],
+      sendToTarget: vi.fn(async (_target, method) => {
+        if (method === "Page.createIsolatedWorld") return { executionContextId: 31 };
+        if (method === "DOM.resolveNode") return { object: { objectId: "button-801" } };
+        if (method === "Runtime.callFunctionOn") return { result: { value: [] } };
+        return {};
+      }) as CdpRunner["sendToTarget"],
+    };
+
+    const documents = [
+      document({ tabId: 11, sessionId: "miss-session" }, 801, undefined, "miss-frame"),
+    ];
+    const graph = semantics(documents);
+
+    const first = await probeTooltipNames(cdp, 11, documents, graph);
+    expect(first.size).toBe(0);
+    const hoversAfterFirst = vi
+      .mocked(cdp.send)
+      .mock.calls.filter(([, method]) => method === "Input.dispatchMouseEvent").length;
+    expect(hoversAfterFirst).toBeGreaterThan(0);
+
+    const second = await probeTooltipNames(cdp, 11, documents, graph);
+    expect(second.size).toBe(0);
+    expect(
+      vi.mocked(cdp.send).mock.calls.filter(([, method]) => method === "Input.dispatchMouseEvent")
+        .length,
+    ).toBe(hoversAfterFirst);
+  });
+
  it("keeps tooltip evidence isolated across sibling frame sessions", async () => {
    let hoveredX = -10;
    const cdp: CdpRunner = {
@@ -1,256 +0,0 @@
-import type { VomScene } from "@browser-skill/vom";
-import { describe, expect, it } from "vitest";
-import type { CapturedNode } from "../capture";
-import type { CapturedFrameDocument } from "../frame-capture";
-import {
-  clusterRenderedSurfaces,
-  discoverRenderedSurfaces,
-  projectRenderedSurfaces,
-} from "../rendered-surfaces";
-import type { SemanticAxNode } from "../semantic-graph";
-
-function domNode(backendNodeId: number, overrides: Partial<CapturedNode> = {}): CapturedNode {
-  return {
-    backendNodeId,
-    parentBackendNodeId: null,
-    frameId: "main",
-    ownerFrameBackendNodeId: null,
-    tag: "canvas",
-    attrs: {},
-    rect: { x: 10, y: 20, w: 800, h: 500 },
-    localRect: { x: 10, y: 20, w: 800, h: 500 },
-    paintOrder: 1,
-    position: "static",
-    pointerEvents: "auto",
-    rendered: true,
-    ...overrides,
-  };
-}
-
-function document(
-  domNodes: CapturedNode[],
-  axNodes: SemanticAxNode[] = [],
-): CapturedFrameDocument<SemanticAxNode> {
-  return {
-    frameId: domNodes[0]?.frameId ?? "main",
-    contextScopeId: domNodes[0]?.frameId ?? "main",
-    target: { tabId: 4 },
-    domNodes,
-    axNodes,
-  };
-}
-
-describe("rendered surface discovery", () => {
-  it("finds prominent rendered canvases and excludes hidden descendants", () => {
-    const visible = domNode(2, { parentBackendNodeId: 1 });
-    const hidden = domNode(3, { parentBackendNodeId: 4 });
-    const surfaces = discoverRenderedSurfaces(
-      [
-        document([
-          domNode(1, { tag: "main", rect: null, localRect: null }),
-          visible,
-          domNode(4, { tag: "section", attrs: { "aria-hidden": "true" }, rect: null }),
-          hidden,
-        ]),
-      ],
-      { width: 1280, height: 720 },
-    );
-
-    expect(surfaces).toHaveLength(1);
-    expect(surfaces[0]).toMatchObject({ backendNodeId: 2 });
-  });
-
-  it("keeps tiny canvases as individually addressable exact discoveries", () => {
-    const surfaces = discoverRenderedSurfaces(
-      [document([domNode(2, { rect: { x: 1, y: 1, w: 8, h: 8 } })])],
-      { width: 1280, height: 720 },
-    );
-    expect(surfaces).toEqual([expect.objectContaining({ backendNodeId: 2 })]);
-  });
-
-  it("keeps a surface when the canvas only has partial native accessibility content", () => {
-    const axNodes = [
-      {
-        nodeId: "canvas",
-        backendDOMNodeId: 2,
-        role: { type: "role", value: "presentation" },
-        childIds: ["button"],
-        frameId: "main",
-      },
-      {
-        nodeId: "button",
-        backendDOMNodeId: 3,
-        role: { type: "role", value: "button" },
-        frameId: "main",
-      },
-    ] as SemanticAxNode[];
-    expect(
-      discoverRenderedSurfaces([document([domNode(2)], axNodes)], { width: 1280, height: 720 }),
-    ).toEqual([expect.objectContaining({ backendNodeId: 2 })]);
-  });
-
-  it("discovers unnamed canvases without guessing labels from engineering attributes", () => {
-    const canvas = domNode(2, {
-      attrs: {
-        id: "must-not-be-a-label",
-        class: "must-not-be-a-label",
-        "data-testid": "must-not-be-a-label",
-      },
-    });
-
-    expect(discoverRenderedSurfaces([document([canvas])], { width: 1280, height: 720 })).toEqual([
-      expect.not.objectContaining({
-        label: expect.anything(),
-      }),
-    ]);
-  });
-
-  it("treats blank explicit Canvas names as unnamed", () => {
-    expect(
-      discoverRenderedSurfaces(
-        [document([domNode(2, { attrs: { "aria-label": "   ", title: "\n\t" } })])],
-        { width: 1280, height: 720 },
-      ),
-    ).toEqual([expect.not.objectContaining({ label: expect.anything() })]);
-  });
-
-  it("excludes canvases inside BrowserSkill-owned DOM subtrees", () => {
-    const owner = domNode(1, { tag: "div", rect: null, localRect: null });
-    const canvas = domNode(2, { parentBackendNodeId: 1 });
-
-    expect(
-      discoverRenderedSurfaces(
-        [document([owner, canvas])],
-        { width: 1280, height: 720 },
-        new Set([1]),
-      ),
-    ).toEqual([]);
-  });
-
-  it("excludes canvases suppressed by a fully transparent ancestor", () => {
-    const owner = domNode(1, {
-      tag: "div",
-      rect: { x: 0, y: 0, w: 900, h: 600 },
-      visuallySuppressed: true,
-    });
-    const canvas = domNode(2, { parentBackendNodeId: 1 });
-
-    expect(
-      discoverRenderedSurfaces([document([owner, canvas])], { width: 1280, height: 720 }),
-    ).toEqual([]);
-  });
-
-  it("clips canvases to overflow ancestors and drops fully clipped canvases", () => {
-    const owner = domNode(1, {
-      tag: "div",
-      rect: { x: 10, y: 20, w: 100, h: 70 },
-      overflowX: "hidden",
-      overflowY: "hidden",
-    });
-    const partial = domNode(2, {
-      parentBackendNodeId: 1,
-      rect: { x: 55, y: 30, w: 140, h: 60 },
-    });
-    const fullyClipped = domNode(3, {
-      parentBackendNodeId: 1,
-      rect: { x: 140, y: 30, w: 80, h: 50 },
-    });
-
-    expect(
-      discoverRenderedSurfaces([document([owner, partial, fullyClipped])], {
-        width: 1280,
-        height: 720,
-      }),
-    ).toEqual([
-      expect.objectContaining({
-        backendNodeId: 2,
-        visibleRect: { x: 55, y: 30, w: 55, h: 60 },
-      }),
-    ]);
-  });
-});
-
-describe("rendered surface clustering and projection", () => {
-  it("collapses overlapping canvas layers and attaches them to the nearest retained parent", () => {
-    const body = domNode(1, { tag: "body", rect: null, localRect: null });
-    const surfaces = discoverRenderedSurfaces(
-      [
-        document([
-          body,
-          domNode(2, { parentBackendNodeId: 1, paintOrder: 1 }),
-          domNode(3, { parentBackendNodeId: 1, paintOrder: 2 }),
-        ]),
-      ],
-      { width: 1280, height: 720 },
-    );
-    const groups = clusterRenderedSurfaces(surfaces);
-    const scene: VomScene = {
-      viewport: { width: 1280, height: 720 },
-      nodes: [
-        {
-          id: 10,
-          parentId: null,
-          backendNodeId: 1,
-          frameId: "main",
-          tag: "body",
-          role: "RootWebArea",
-          rect: null,
-          paintOrder: 0,
-          position: "static",
-          pointerEvents: "auto",
-        },
-      ],
-    };
-
-    expect(groups).toHaveLength(1);
-    expect(groups[0]?.members).toHaveLength(2);
-    expect(groups[0]?.label).toBeUndefined();
-    expect(
-      projectRenderedSurfaces(
-        scene,
-        [document([body, ...surfaces.map((s) => domNode(s.backendNodeId))])],
-        groups,
-      ),
-    ).toMatchObject({
-      visualSurfaces: [expect.objectContaining({ parentId: 10, backendNodeId: 3, memberCount: 2 })],
-    });
-  });
-
-  it("does not merge a contained canvas with a larger independent canvas", () => {
-    const groups = clusterRenderedSurfaces([
-      ...discoverRenderedSurfaces(
-        [
-          document([
-            domNode(1, { tag: "main", rect: null, localRect: null }),
-            domNode(2, { parentBackendNodeId: 1 }),
-            domNode(3, {
-              parentBackendNodeId: 1,
-              rect: { x: 30, y: 40, w: 200, h: 100 },
-            }),
-          ]),
-        ],
-        { width: 1280, height: 720 },
-      ),
-    ]);
-
-    expect(groups).toHaveLength(2);
-  });
-
-  it("does not merge coincident canvases owned by different containers", () => {
-    const groups = clusterRenderedSurfaces(
-      discoverRenderedSurfaces(
-        [
-          document([
-            domNode(1, { tag: "section", rect: null, localRect: null }),
-            domNode(2, { tag: "section", rect: null, localRect: null }),
-            domNode(3, { parentBackendNodeId: 1 }),
-            domNode(4, { parentBackendNodeId: 2 }),
-          ]),
-        ],
-        { width: 1280, height: 720 },
-      ),
-    );
-
-    expect(groups).toHaveLength(2);
-  });
-});
@@ -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;
+    });
+  };
+}
@@ -0,0 +1,413 @@
+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 { describeSnapshotFrames, REQUESTED_STYLES, type SnapshotReply } 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,
+): Promise<ObservationFacts<T>> {
+  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: REQUESTED_STYLES,
+          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,
+        );
+        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),
+      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 { 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(),
+    },
+  };
+}
@@ -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;
+}
@@ -1,312 +1,18 @@
-// 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 { clearHover, waitForHover } from "./hover-perception";
+import type { CapturedNode } from "./capture-types";
+import type { CapturedSurfaceProbe } from "./facts";

-const REQUESTED_STYLES = [
-  "position",
-  "pointer-events",
-  "cursor",
-  "visibility",
-  "opacity",
-  "overflow-x",
-  "overflow-y",
-] as const;
-const STYLE_COL = Object.fromEntries(
-  REQUESTED_STYLES.map((name, index) => [name, index]),
-) as Record<(typeof REQUESTED_STYLES)[number], number>;
+export type {
+  CapturedNode,
+  CapturedSurfaceProbe,
+} from "./facts";

-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;
-  overflowX?: string;
-  overflowY?: string;
-  /** True when this node or one of its DOM ancestors makes the subtree fully transparent/hidden. */
-  visuallySuppressed?: boolean;
-  /**
-   * Whether the live DOM snapshot provides a painted, non-hidden box for this
-   * node. Semantic resolution uses this only for DOM fallback nodes; AX-backed
-   * nodes remain authoritative even when they are outside the viewport.
-   */
-  rendered?: boolean;
-  textContent?: string;
-  formState?: "empty" | "filled" | "default";
-  formValue?: string;
-  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;
-  surfaceProbes?: CapturedSurfaceProbe[];
-  /** Backend node ids belonging to the agent overlay host + its shadow subtree. */
-  excludedBackendNodeIds: Set<number>;
-}
-
-export interface CaptureViewModelOptions {
-  conditionalSurfaceProbe?: boolean;
-  hoverProbeBypassOverlay?: (tabId: number, enabled: boolean) => Promise<void>;
-  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.
-  }
-}
+import { isAbortError, throwIfAborted } from "./capture-abort";
+import { clearHover, ProbeBudget, waitForHover } from "./hover-perception";

 interface RuntimeEvaluateReply {
  result?: {
@@ -329,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") {
@@ -380,7 +48,16 @@ function collectBackendIdsFromDomNode(node: CdpDomNode | undefined, out: Set<num
  }
 }

-const MAX_HOVER_PROBE_MS = 2_000;
+/**
+ * Ceiling for the whole hover-surface phase.
+ *
+ * The previous 2000 was only a floor: the loop checked elapsed time at the top,
+ * so a candidate could start with 1ms left and still run its two settle
+ * windows, pushing real cost to ~2.6s. This is that true ceiling, now actually
+ * enforced by an up-front affordability check, so the same number of candidates
+ * get probed under a bound that no longer lies.
+ */
+const MAX_HOVER_PROBE_MS = 2_600;
 const MAX_HOVER_TRIGGERS = 6;
 const MAX_HOVER_SURFACES = 3;
 const HOVER_SETTLE_MS = 300;
@@ -626,13 +303,35 @@ function confidenceForHover(
  return "low";
 }

-async function probeHoverSurfaces(
+/**
+ * One candidate costs two settle windows (baseline + post-hover) plus a few
+ * CDP round trips. Used to decide whether the next candidate still fits the
+ * budget before paying for it.
+ */
+const HOVER_CANDIDATE_COST_MS = HOVER_SETTLE_MS * 2;
+
+export interface HoverSurfaceProbeOptions {
+  signal?: AbortSignal;
+}
+
+/**
+ * Hovers a bounded set of likely menu triggers and reports the sub-items each
+ * one reveals.
+ *
+ * Runs after DOM *and* accessibility capture. Hovering can open menus and
+ * change layout, so probing between the two captures would leave the DOM half
+ * of an observation describing the page before the change and the AX half
+ * describing it after.
+ *
+ * The caller owns the overlay bypass span (see `withOverlayBypass`).
+ */
+export async function probeHoverSurfaces(
  cdp: CdpRunner,
  tabId: number,
  nodes: CapturedNode[],
-  options: CaptureViewModelOptions,
+  options: HoverSurfaceProbeOptions = {},
 ): Promise<CapturedSurfaceProbe[]> {
-  const started = Date.now();
+  const budget = new ProbeBudget(MAX_HOVER_PROBE_MS);
  try {
    throwIfAborted(options.signal);
    const cssScan = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
@@ -647,60 +346,54 @@ async function probeHoverSurfaces(
    const results: CapturedSurfaceProbe[] = [];
    const seen = new Set<number>();
    throwIfAborted(options.signal);
-    await options.hoverProbeBypassOverlay?.(tabId, true).catch(() => undefined);
-    try {
+    for (const candidate of candidates.slice(0, MAX_HOVER_TRIGGERS)) {
      throwIfAborted(options.signal);
-      for (const candidate of candidates.slice(0, MAX_HOVER_TRIGGERS)) {
+      if (!budget.canAfford(HOVER_CANDIDATE_COST_MS)) break;
+      if (results.length >= MAX_HOVER_SURFACES) break;
+      if (seen.has(candidate.backendNodeId)) continue;
+      try {
+        await clearHover(cdp, tabId);
        throwIfAborted(options.signal);
-        if (Date.now() - started > MAX_HOVER_PROBE_MS) break;
-        if (results.length >= MAX_HOVER_SURFACES) break;
-        if (seen.has(candidate.backendNodeId)) continue;
-        try {
-          await clearHover(cdp, tabId);
-          throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
-          const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-            expression: hoverStateExpression(),
-            returnByValue: true,
-          });
-          throwIfAborted(options.signal);
-          const baselineItems = runtimeValue<HoverRuntimeItem[]>(baselineReply) ?? [];
+        await waitForHover(HOVER_SETTLE_MS, options.signal);
+        const baselineReply = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+          expression: hoverStateExpression(),
+          returnByValue: true,
+        });
+        throwIfAborted(options.signal);
+        const baselineItems = runtimeValue<HoverRuntimeItem[]>(baselineReply) ?? [];

-          throwIfAborted(options.signal);
-          await cdp.send(tabId, "Input.dispatchMouseEvent", {
-            type: "mouseMoved",
-            x: candidate.x,
-            y: candidate.y,
-          });
-          throwIfAborted(options.signal);
-          await waitForHover(HOVER_SETTLE_MS, options.signal);
-          const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
-            expression: hoverStateExpression(),
-            returnByValue: true,
-          });
-          throwIfAborted(options.signal);
-          const subItems = diffHoverItems(
-            baselineItems,
-            runtimeValue<HoverRuntimeItem[]>(collected) ?? [],
-          );
-          if (subItems.length === 0) continue;
-          seen.add(candidate.backendNodeId);
-          results.push({
-            triggerBackendNodeId: candidate.backendNodeId,
-            triggerPoint: { x: candidate.x, y: candidate.y },
-            triggerAction: "hover",
-            subItems,
-            confidence: confidenceForHover(candidate, subItems),
-          });
-        } catch (error) {
-          if (isAbortError(error)) throw error;
-          continue;
-        } finally {
-          await clearHover(cdp, tabId);
-        }
+        throwIfAborted(options.signal);
+        await cdp.send(tabId, "Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: candidate.x,
+          y: candidate.y,
+        });
+        throwIfAborted(options.signal);
+        await waitForHover(HOVER_SETTLE_MS, options.signal);
+        const collected = await cdp.send<RuntimeEvaluateReply>(tabId, "Runtime.evaluate", {
+          expression: hoverStateExpression(),
+          returnByValue: true,
+        });
+        throwIfAborted(options.signal);
+        const subItems = diffHoverItems(
+          baselineItems,
+          runtimeValue<HoverRuntimeItem[]>(collected) ?? [],
+        );
+        if (subItems.length === 0) continue;
+        seen.add(candidate.backendNodeId);
+        results.push({
+          triggerBackendNodeId: candidate.backendNodeId,
+          triggerPoint: { x: candidate.x, y: candidate.y },
+          triggerAction: "hover",
+          subItems,
+          confidence: confidenceForHover(candidate, subItems),
+        });
+      } catch (error) {
+        if (isAbortError(error)) throw error;
+        continue;
+      } finally {
+        await clearHover(cdp, tabId);
      }
-    } finally {
-      await options.hoverProbeBypassOverlay?.(tabId, false).catch(() => undefined);
    }
    return results;
  } catch (err) {
@@ -750,382 +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 overflowXCol = STYLE_COL["overflow-x"];
-  const overflowYCol = STYLE_COL["overflow-y"];
-  const inputValues = sparseIndexMap(dn.inputValue);
-  const textValues = sparseIndexMap(dn.textValue);
-  const checkedInputs = new Set(dn.inputChecked?.index ?? []);
-  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[] = [];
-  const visuallySuppressedByNodeIndex = new Array<boolean>(count).fill(false);
-  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 overflowX = "visible";
-    let overflowY = "visible";
-    let rendered = false;
-    let visuallySuppressed =
-      parentIdx >= 0 ? visuallySuppressedByNodeIndex[parentIdx] === true : false;
-    const li = layoutByNode.get(n);
-    if (li !== undefined) {
-      const b = dl?.bounds?.[li];
-      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";
-      overflowX = str(strings, styleRow[overflowXCol]) || "visible";
-      overflowY = str(strings, styleRow[overflowYCol]) || "visible";
-      visuallySuppressed ||=
-        visibility === "hidden" ||
-        visibility === "collapse" ||
-        (Number.parseFloat(opacity) || 0) <= 0;
-      rendered =
-        localRect !== null &&
-        visibility !== "hidden" &&
-        visibility !== "collapse" &&
-        (Number.parseFloat(opacity) || 0) > 0;
-    }
-    visuallySuppressedByNodeIndex[n] = visuallySuppressed;
-
-    // Skip non-element nodes (#text, #cdata-section, etc.) — they carry no
-    // geometry and are never queried by callers.
-    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,
-      overflowX,
-      overflowY,
-      visuallySuppressed,
-      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(),
-      surfaceProbes: [],
-      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 surfaceProbes = options.conditionalSurfaceProbe
-    ? await probeHoverSurfaces(cdp, tabId, nodes, options)
-    : [];
-  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 } : {}),
-    surfaceProbes,
-    excludedBackendNodeIds,
-  };
-}
--- a/Show More
+++ b/Show More