cdp-toolkit 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to cdp-toolkit are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-09-10
+
+**Drive focus-gated pages on a background tab without stealing OS window focus.** Some sites gate a button behind `document.hasFocus()`/`visibilitychange` — the canonical case is Anthropic's Claude Code OAuth page (`claude.ai/oauth/*`), whose **Authorize** button stays disabled on a background tab, forcing an agent driving `claude -p` login to keep a human clicking. Two new Chrome-only tools port the mechanism of the [`danbuhler/claude-code-auto-authorize`](https://github.com/danbuhler/claude-code-auto-authorize) extension: `Emulation.setFocusEmulationEnabled` makes the page *believe* it is focused (hasFocus→true, visibility stays `visible`, focus events fire) while the real window stays put, and `Input.dispatchMouseEvent` delivers the **trusted** click (`isTrusted:true`) that a content script's synthesized events can never produce.
+
+### Added
+
+- **`focus_emulation { enabled }`** — the raw toggle: a tab reports focused/visible with no OS focus change. Call with `enabled:false` to restore.
+- **`click_focus_gated { selector|text, timeoutMs, pollMs, keepFocus }`** — the one-call compose: enable focus emulation, poll until the button (CSS selector or exact visible-text, e.g. `"Authorize"`) exists **and** is enabled, trusted-click it, restore emulation (always, unless `keepFocus`, even on throw). Timeout error names the failure mode ("never located" vs "found but stayed disabled").
+- New capability **`emulate.focus`** (Chrome declares it; BiDi's emulation module has no focus primitive, so both tools are absent from `tools/list` under `--browser firefox`, per ADR-001).
+- New live harness **`test/focus-emulation-smoke.ts`** (`bun run focus:smoke`): a real headless Chrome serves a focus-gated Authorize fixture (disabled until `hasFocus()`), proves the gate is closed in a background tab (control), then `click_focus_gated` opens it and lands a trusted click — page log shows `gate:unlocked` + `CLICKED trusted=true` with the tab never activated. Plus unit tests `test/focus-emulation.test.ts` (16) pinning validation, capability gating, and manifest/docs/group registration.
+
 ## [2.2.0] - 2026-09-04
 
 **Several agent PROCESSES can now drive tabs of ONE user-launched Firefox at the same time.** Firefox serves exactly one WebDriver BiDi session per browser (measured on 153.0.3: a second `session.new` gets "Maximum number of active sessions", a second WebSocket to `/session/<id>` is refused at the HTTP upgrade). Previously a second cdp-toolkit process attaching to the same Firefox was refused after the session-slot wait; now the process that wins the slot fronts the one real session with a loopback BiDi multiplexer, and every other process joins it instead of waiting. **Measured** (`bun run firefox:multi:smoke`, headless Firefox 153.0.3, 4 agents × 6 rounds): before, 4 server processes attached to one Firefox — 1 of 4 completed, the other 3 refused after the session wait; after, all 4 completed concurrently (40 calls, wall 437ms vs serial 1375ms, 4 distinct processes in flight), a killed server process left 3 survivors finishing with 0 retries, and a killed daemon was replaced within the recovery path with every survivor finishing on its original tab via the stale-id hint (`firefox:coord:smoke` 11/11, `bun test` 929 pass). See [`docs/design/2026-09-04-firefox-multi-agent-session-mux.md`](docs/design/2026-09-04-firefox-multi-agent-session-mux.md).

package/README.md

@@ -245,12 +245,12 @@ That shape is deliberate. The MCP **2026-07-28** revision puts lazy discovery on
 {"tool": "describe_tool", "arguments": {}}
 ```
 
-With no `name` it returns the grouped catalog of everything this server can run. The whole 45-tool surface costs 1,141 characters:
+With no `name` it returns the grouped catalog of everything this server can run. The whole 47-tool surface:
 
 ```
-cdp-toolkit 2.2.0 · browser=chrome · 45 tools available, 46 in tools/list (CDP_TOOL_PROFILE=full)
+cdp-toolkit 2.3.0 · browser=chrome · 47 tools available, 48 in tools/list (CDP_TOOL_PROFILE=full)
 [listed] core (12): list_pages, new_page, close_page, select_page, navigate_page, wait_for, take_snapshot, click, fill, type_text, evaluate_script, take_screenshot
-[listed] input (7): hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file
+[listed] input (9): hover, drag, scroll, dispatch_mouse, press_key, fill_form, upload_file, focus_emulation, click_focus_gated
 [listed] cookies (3): list_cookies, set_cookie, delete_cookies
 [listed] network (2): list_network_requests, get_network_request
 [listed] console (2): list_console_messages, get_console_message
@@ -271,7 +271,7 @@ Under a narrower profile the groups it leaves out read `[hidden]` instead of `[l
 
 | `CDP_TOOL_PROFILE` | entries in `tools/list` | bytes | ≈ tokens |
 |---|---|---|---|
-| unset / `full` — the default | 46 | 33,886 | ≈8,471 |
+| unset / `full` — the default | 48 | 35,556 | ≈8,889 |
 | `core` | 13 | 9,066 | ≈2,266 |
 | `core,network,console` | 17 | 11,893 | ≈2,973 |
 | `full` under `CDP_BROWSER=firefox` | 35 | 26,533 | ≈6,633 |

package/dist/bidi/mux-daemon.js

@@ -498,6 +498,8 @@ var init_driver = __esm(() => {
     list_mocks: ["network.intercept"],
     clear_mocks: ["network.intercept"],
     dispatch_mouse: ["input.raw"],
+    focus_emulation: ["emulate.focus"],
+    click_focus_gated: ["emulate.focus"],
     wait_for_download: ["browser.downloads"],
     grant_permissions: ["browser.permissions"]
   };

package/dist/cli.js

@@ -1090,6 +1090,8 @@ var init_driver = __esm(() => {
     list_mocks: ["network.intercept"],
     clear_mocks: ["network.intercept"],
     dispatch_mouse: ["input.raw"],
+    focus_emulation: ["emulate.focus"],
+    click_focus_gated: ["emulate.focus"],
     wait_for_download: ["browser.downloads"],
     grant_permissions: ["browser.permissions"]
   };
@@ -4157,6 +4159,7 @@ var CDP_CAPABILITIES = new Set([
   "capture.screencast",
   "input.raw",
   "input.html5Drag",
+  "emulate.focus",
   "browser.downloads",
   "browser.permissions",
   "worker.targets"
@@ -7577,6 +7580,99 @@ async function dispatchMouse(args) {
   });
 }
 
+// src/tools/focus-emulation.ts
+init_activity();
+init_client();
+function validateFocusEmulationArgs(args) {
+  if (typeof args.enabled !== "boolean") {
+    throw new Error("focus_emulation requires { enabled } of true or false");
+  }
+}
+function validateClickFocusGatedArgs(args) {
+  const hasSel = typeof args.selector === "string" && args.selector.length > 0;
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  if (hasSel === hasText) {
+    throw new Error("click_focus_gated requires exactly one of { selector } or { text }");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new Error("click_focus_gated: timeoutMs must be a positive number");
+  }
+  if (args.pollMs !== undefined && (!Number.isFinite(args.pollMs) || args.pollMs <= 0)) {
+    throw new Error("click_focus_gated: pollMs must be a positive number");
+  }
+}
+var FIND_BUTTON = `(() => {
+  const SEL = %SEL%;
+  const TEXT = %TEXT%;
+  let btn = null;
+  let matchedBy = null;
+  if (SEL) {
+    btn = document.querySelector(SEL);
+    if (btn) matchedBy = "selector";
+  }
+  if (!btn && TEXT) {
+    btn = Array.from(document.querySelectorAll("button,[role=button],input[type=submit]"))
+      .find((b) => (b.textContent || b.value || "").trim() === TEXT);
+    if (btn) matchedBy = "text";
+  }
+  if (!btn) return null;
+  const r = btn.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2,
+           disabled: !!btn.disabled || btn.getAttribute("aria-disabled") === "true",
+           matchedBy, hasFocus: document.hasFocus(), visibility: document.visibilityState };
+})()`;
+function findButtonExpression(selector, text) {
+  return FIND_BUTTON.replace("%SEL%", JSON.stringify(selector ?? null)).replace("%TEXT%", JSON.stringify(text ?? null));
+}
+async function focusEmulation(args) {
+  validateFocusEmulationArgs(args);
+  return withPage(args.target, async (conn) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: args.enabled });
+    return { enabled: args.enabled };
+  }, { lease: args.lease });
+}
+async function clickFocusGated(args) {
+  validateClickFocusGatedArgs(args);
+  const timeoutMs = args.timeoutMs ?? 30000;
+  const pollMs = args.pollMs ?? 500;
+  const start = Date.now();
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    try {
+      const expression = findButtonExpression(args.selector, args.text);
+      for (;; ) {
+        const { result } = await conn.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true
+        });
+        const btn = result?.value;
+        if (btn && !btn.disabled) {
+          const base = { x: btn.x, y: btn.y, button: "left", buttons: 1, clickCount: 1 };
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: btn.x, y: btn.y });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mousePressed" });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased" });
+          return {
+            clicked: true,
+            x: btn.x,
+            y: btn.y,
+            matchedBy: btn.matchedBy,
+            elapsedMs: Date.now() - start
+          };
+        }
+        if (Date.now() - start >= timeoutMs) {
+          throw new Error(`click_focus_gated: button never became clickable within ${timeoutMs}ms` + (btn ? " (found but stayed disabled — focus emulation may not satisfy this gate)" : " (never located)"));
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    } finally {
+      if (!args.keepFocus) {
+        await conn.send("Emulation.setFocusEmulationEnabled", { enabled: false }).catch(() => {});
+      }
+    }
+  }, { lease: args.lease, timeoutMs: timeoutMs + 5000 });
+}
+
 // src/tools/downloads.ts
 init_client();
 import { readdir as readdir3, rename as rename2, stat as stat4 } from "node:fs/promises";
@@ -7852,6 +7948,8 @@ var TOOLS = {
   list_mocks: listMocks,
   clear_mocks: clearMocks,
   dispatch_mouse: dispatchMouse,
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   wait_for_download: waitForDownload,
   grant_permissions: grantPermissions,
   claim_page: onCdp(LEASE_TOOLS.claim_page),
@@ -8983,6 +9081,70 @@ var MANIFEST = [
       additionalProperties: false
     }
   },
+  {
+    name: "focus_emulation",
+    description: "Toggle page focus emulation: the page reports focused/visible without the OS window moving; Chrome-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        target: {
+          type: "string",
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        enabled: {
+          type: "boolean",
+          description: "true = page reports focused; false = restore real focus state."
+        }
+      },
+      required: [
+        "enabled"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "click_focus_gated",
+    description: "Emulate page focus, wait for a focus-gated button to enable, trusted-click it, restore; Chrome-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        target: {
+          type: "string",
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector of the button; exactly one of selector or text."
+        },
+        text: {
+          type: "string",
+          description: 'Visible-text match for the button (e.g. "Authorize"); exactly one of selector or text.'
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Max ms to poll for the button to become enabled. Default 30000."
+        },
+        pollMs: {
+          type: "number",
+          description: "Poll interval ms. Default 500."
+        },
+        keepFocus: {
+          type: "boolean",
+          description: "Leave focus emulation on after the click (default false = restored)."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
   {
     name: "wait_for_download",
     description: "Arm or collect a browser download; arm capture before triggering the download.",

package/dist/index.js

@@ -1089,6 +1089,8 @@ var init_driver = __esm(() => {
     list_mocks: ["network.intercept"],
     clear_mocks: ["network.intercept"],
     dispatch_mouse: ["input.raw"],
+    focus_emulation: ["emulate.focus"],
+    click_focus_gated: ["emulate.focus"],
     wait_for_download: ["browser.downloads"],
     grant_permissions: ["browser.permissions"]
   };
@@ -1559,6 +1561,7 @@ var CDP_CAPABILITIES = new Set([
   "capture.screencast",
   "input.raw",
   "input.html5Drag",
+  "emulate.focus",
   "browser.downloads",
   "browser.permissions",
   "worker.targets"
@@ -4979,6 +4982,99 @@ async function dispatchMouse(args) {
   });
 }
 
+// src/tools/focus-emulation.ts
+init_activity();
+init_client();
+function validateFocusEmulationArgs(args) {
+  if (typeof args.enabled !== "boolean") {
+    throw new Error("focus_emulation requires { enabled } of true or false");
+  }
+}
+function validateClickFocusGatedArgs(args) {
+  const hasSel = typeof args.selector === "string" && args.selector.length > 0;
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  if (hasSel === hasText) {
+    throw new Error("click_focus_gated requires exactly one of { selector } or { text }");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new Error("click_focus_gated: timeoutMs must be a positive number");
+  }
+  if (args.pollMs !== undefined && (!Number.isFinite(args.pollMs) || args.pollMs <= 0)) {
+    throw new Error("click_focus_gated: pollMs must be a positive number");
+  }
+}
+var FIND_BUTTON = `(() => {
+  const SEL = %SEL%;
+  const TEXT = %TEXT%;
+  let btn = null;
+  let matchedBy = null;
+  if (SEL) {
+    btn = document.querySelector(SEL);
+    if (btn) matchedBy = "selector";
+  }
+  if (!btn && TEXT) {
+    btn = Array.from(document.querySelectorAll("button,[role=button],input[type=submit]"))
+      .find((b) => (b.textContent || b.value || "").trim() === TEXT);
+    if (btn) matchedBy = "text";
+  }
+  if (!btn) return null;
+  const r = btn.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2,
+           disabled: !!btn.disabled || btn.getAttribute("aria-disabled") === "true",
+           matchedBy, hasFocus: document.hasFocus(), visibility: document.visibilityState };
+})()`;
+function findButtonExpression(selector, text) {
+  return FIND_BUTTON.replace("%SEL%", JSON.stringify(selector ?? null)).replace("%TEXT%", JSON.stringify(text ?? null));
+}
+async function focusEmulation(args) {
+  validateFocusEmulationArgs(args);
+  return withPage(args.target, async (conn) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: args.enabled });
+    return { enabled: args.enabled };
+  }, { lease: args.lease });
+}
+async function clickFocusGated(args) {
+  validateClickFocusGatedArgs(args);
+  const timeoutMs = args.timeoutMs ?? 30000;
+  const pollMs = args.pollMs ?? 500;
+  const start = Date.now();
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    try {
+      const expression = findButtonExpression(args.selector, args.text);
+      for (;; ) {
+        const { result } = await conn.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true
+        });
+        const btn = result?.value;
+        if (btn && !btn.disabled) {
+          const base = { x: btn.x, y: btn.y, button: "left", buttons: 1, clickCount: 1 };
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: btn.x, y: btn.y });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mousePressed" });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased" });
+          return {
+            clicked: true,
+            x: btn.x,
+            y: btn.y,
+            matchedBy: btn.matchedBy,
+            elapsedMs: Date.now() - start
+          };
+        }
+        if (Date.now() - start >= timeoutMs) {
+          throw new Error(`click_focus_gated: button never became clickable within ${timeoutMs}ms` + (btn ? " (found but stayed disabled — focus emulation may not satisfy this gate)" : " (never located)"));
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    } finally {
+      if (!args.keepFocus) {
+        await conn.send("Emulation.setFocusEmulationEnabled", { enabled: false }).catch(() => {});
+      }
+    }
+  }, { lease: args.lease, timeoutMs: timeoutMs + 5000 });
+}
+
 // src/tools/downloads.ts
 init_client();
 import { readdir as readdir3, rename as rename2, stat as stat4 } from "node:fs/promises";
@@ -5254,6 +5350,8 @@ var TOOLS = {
   list_mocks: listMocks,
   clear_mocks: clearMocks,
   dispatch_mouse: dispatchMouse,
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   wait_for_download: waitForDownload,
   grant_permissions: grantPermissions,
   claim_page: onCdp(LEASE_TOOLS.claim_page),

package/dist/mcp.js

@@ -1090,6 +1090,8 @@ var init_driver = __esm(() => {
     list_mocks: ["network.intercept"],
     clear_mocks: ["network.intercept"],
     dispatch_mouse: ["input.raw"],
+    focus_emulation: ["emulate.focus"],
+    click_focus_gated: ["emulate.focus"],
     wait_for_download: ["browser.downloads"],
     grant_permissions: ["browser.permissions"]
   };
@@ -4161,6 +4163,7 @@ var CDP_CAPABILITIES = new Set([
   "capture.screencast",
   "input.raw",
   "input.html5Drag",
+  "emulate.focus",
   "browser.downloads",
   "browser.permissions",
   "worker.targets"
@@ -7581,6 +7584,99 @@ async function dispatchMouse(args) {
   });
 }
 
+// src/tools/focus-emulation.ts
+init_activity();
+init_client();
+function validateFocusEmulationArgs(args) {
+  if (typeof args.enabled !== "boolean") {
+    throw new Error("focus_emulation requires { enabled } of true or false");
+  }
+}
+function validateClickFocusGatedArgs(args) {
+  const hasSel = typeof args.selector === "string" && args.selector.length > 0;
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  if (hasSel === hasText) {
+    throw new Error("click_focus_gated requires exactly one of { selector } or { text }");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new Error("click_focus_gated: timeoutMs must be a positive number");
+  }
+  if (args.pollMs !== undefined && (!Number.isFinite(args.pollMs) || args.pollMs <= 0)) {
+    throw new Error("click_focus_gated: pollMs must be a positive number");
+  }
+}
+var FIND_BUTTON = `(() => {
+  const SEL = %SEL%;
+  const TEXT = %TEXT%;
+  let btn = null;
+  let matchedBy = null;
+  if (SEL) {
+    btn = document.querySelector(SEL);
+    if (btn) matchedBy = "selector";
+  }
+  if (!btn && TEXT) {
+    btn = Array.from(document.querySelectorAll("button,[role=button],input[type=submit]"))
+      .find((b) => (b.textContent || b.value || "").trim() === TEXT);
+    if (btn) matchedBy = "text";
+  }
+  if (!btn) return null;
+  const r = btn.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2,
+           disabled: !!btn.disabled || btn.getAttribute("aria-disabled") === "true",
+           matchedBy, hasFocus: document.hasFocus(), visibility: document.visibilityState };
+})()`;
+function findButtonExpression(selector, text) {
+  return FIND_BUTTON.replace("%SEL%", JSON.stringify(selector ?? null)).replace("%TEXT%", JSON.stringify(text ?? null));
+}
+async function focusEmulation(args) {
+  validateFocusEmulationArgs(args);
+  return withPage(args.target, async (conn) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: args.enabled });
+    return { enabled: args.enabled };
+  }, { lease: args.lease });
+}
+async function clickFocusGated(args) {
+  validateClickFocusGatedArgs(args);
+  const timeoutMs = args.timeoutMs ?? 30000;
+  const pollMs = args.pollMs ?? 500;
+  const start = Date.now();
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+    try {
+      const expression = findButtonExpression(args.selector, args.text);
+      for (;; ) {
+        const { result } = await conn.send("Runtime.evaluate", {
+          expression,
+          returnByValue: true
+        });
+        const btn = result?.value;
+        if (btn && !btn.disabled) {
+          const base = { x: btn.x, y: btn.y, button: "left", buttons: 1, clickCount: 1 };
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: btn.x, y: btn.y });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mousePressed" });
+          await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased" });
+          return {
+            clicked: true,
+            x: btn.x,
+            y: btn.y,
+            matchedBy: btn.matchedBy,
+            elapsedMs: Date.now() - start
+          };
+        }
+        if (Date.now() - start >= timeoutMs) {
+          throw new Error(`click_focus_gated: button never became clickable within ${timeoutMs}ms` + (btn ? " (found but stayed disabled — focus emulation may not satisfy this gate)" : " (never located)"));
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+      }
+    } finally {
+      if (!args.keepFocus) {
+        await conn.send("Emulation.setFocusEmulationEnabled", { enabled: false }).catch(() => {});
+      }
+    }
+  }, { lease: args.lease, timeoutMs: timeoutMs + 5000 });
+}
+
 // src/tools/downloads.ts
 init_client();
 import { readdir as readdir3, rename as rename2, stat as stat4 } from "node:fs/promises";
@@ -7856,6 +7952,8 @@ var TOOLS = {
   list_mocks: listMocks,
   clear_mocks: clearMocks,
   dispatch_mouse: dispatchMouse,
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   wait_for_download: waitForDownload,
   grant_permissions: grantPermissions,
   claim_page: onCdp(LEASE_TOOLS.claim_page),
@@ -8517,6 +8615,70 @@ var MANIFEST = [
       additionalProperties: false
     }
   },
+  {
+    name: "focus_emulation",
+    description: "Toggle page focus emulation: the page reports focused/visible without the OS window moving; Chrome-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        target: {
+          type: "string",
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        enabled: {
+          type: "boolean",
+          description: "true = page reports focused; false = restore real focus state."
+        }
+      },
+      required: [
+        "enabled"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "click_focus_gated",
+    description: "Emulate page focus, wait for a focus-gated button to enable, trusted-click it, restore; Chrome-only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        target: {
+          type: "string",
+          description: "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector of the button; exactly one of selector or text."
+        },
+        text: {
+          type: "string",
+          description: 'Visible-text match for the button (e.g. "Authorize"); exactly one of selector or text.'
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Max ms to poll for the button to become enabled. Default 30000."
+        },
+        pollMs: {
+          type: "number",
+          description: "Poll interval ms. Default 500."
+        },
+        keepFocus: {
+          type: "boolean",
+          description: "Leave focus emulation on after the click (default false = restored)."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
   {
     name: "wait_for_download",
     description: "Arm or collect a browser download; arm capture before triggering the download.",
@@ -10053,7 +10215,9 @@ var GROUP_TOOLS = {
     "dispatch_mouse",
     "press_key",
     "fill_form",
-    "upload_file"
+    "upload_file",
+    "focus_emulation",
+    "click_focus_gated"
   ],
   cookies: ["list_cookies", "set_cookie", "delete_cookies"],
   network: ["list_network_requests", "get_network_request"],
@@ -10278,6 +10442,26 @@ var TOOL_DOCS = {
       modifiers: "Modifier keys held for this one event, e.g. ['Shift']."
     }
   },
+  focus_emulation: {
+    description: "Toggles CDP Emulation.setFocusEmulationEnabled on a tab: the page then BELIEVES it is focused (document.hasFocus()→true, visibilitychange stays 'visible', focus events fire) while the real OS window and active tab stay put — no focus theft. This is the primitive that unlocks focus-GATED UI (a button the site disables unless its tab is focused, e.g. Anthropic's Claude Code OAuth Authorize button on claude.ai/oauth/*) on a background tab. Chrome-only: WebDriver BiDi's emulation module has no focus primitive, so this tool is absent from tools/list under --browser firefox. Ports the core mechanism of the danbuhler/claude-code-auto-authorize extension. Remember to call with enabled:false to restore, or use click_focus_gated which restores automatically.",
+    params: {
+      lease: "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
+      target: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'.",
+      enabled: "true = page reports focused/visible; false = restore the real focus state."
+    }
+  },
+  click_focus_gated: {
+    description: "One-call compose of focus emulation + trusted click for a focus-gated button: enables Emulation.setFocusEmulationEnabled, polls until the button (located by CSS selector OR exact visible-text match, e.g. 'Authorize') exists AND is enabled, dispatches a trusted move/press/release click via Input.dispatchMouseEvent (isTrusted:true — a content script's synthesized events can never satisfy a focus gate), then restores focus emulation off unless keepFocus. Built for the Claude Code OAuth Authorize button but works on any focus-gated control on a background tab. Throws with a diagnostic ('never located' vs 'found but stayed disabled') on timeout. Chrome-only; absent under --browser firefox.",
+    params: {
+      lease: "Lease token from claim_page. Omit for a tab this process holds. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease).",
+      target: "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'.",
+      selector: "CSS selector of the button. Give exactly one of selector or text.",
+      text: "Exact visible-text match of the button (trims whitespace, matches button/[role=button]/submit inputs), e.g. 'Authorize'. Give exactly one of selector or text.",
+      timeoutMs: "Max ms to poll for the button to appear and become enabled. Default 30000.",
+      pollMs: "Poll interval in ms. Default 500.",
+      keepFocus: "Leave focus emulation ON after the click (default false — restored even on throw, so a failed click never strands the page fake-focused)."
+    }
+  },
   wait_for_download: {
     description: "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under Firefox.",
     params: {
@@ -10573,7 +10757,7 @@ var TOOL_DOCS = {
 };
 
 // src/version.ts
-var VERSION = "2.2.0";
+var VERSION = "2.3.0";
 
 // src/mcp.ts
 var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-toolkit",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 45 tools including built-in network mocking, a cookie group, tab leases with human-activity detection, real HTML5 drag-and-drop, raw mouse/scroll dispatch, downloads, permission grants, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs or a human's. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
@@ -84,7 +84,8 @@
     "lease:smoke": "bun run ./test/lease-smoke.ts",
     "staleness:smoke": "bun run ./test/staleness-smoke.ts",
     "input:smoke": "bun run ./test/input-smoke.ts",
-    "extension:smoke": "bun run ./test/extension-smoke.ts"
+    "extension:smoke": "bun run ./test/extension-smoke.ts",
+    "focus:smoke": "bun run ./test/focus-emulation-smoke.ts"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",

package/src/cdp/driver.ts

@@ -651,7 +651,7 @@ const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
   "screenshot.fullPage", "screenshot.element", "screenshot.scale", "screenshot.renderSize", "screenshot.tile", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
-  "capture.screencast", "input.raw", "input.html5Drag",
+  "capture.screencast", "input.raw", "input.html5Drag", "emulate.focus",
   "browser.downloads", "browser.permissions", "worker.targets",
 ]);
 /* ---------------------------------- PageDriver ---------------------------------- */

package/src/driver.ts

@@ -150,6 +150,7 @@ export type Capability =
   | "locate.xpath" // find a node by xpath
   | "input.raw" // raw single mouse-event dispatch (dispatch_mouse's move/down/up primitive); Chrome only
   | "input.html5Drag" // real HTML5 drag events (drag's mode:"html5"); Chrome only, see PageDriver.drag
+  | "emulate.focus" // fake page focus without moving the OS window (focus_emulation / click_focus_gated); Chrome only — BiDi's emulation module has no focus primitive
   | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
   | "browser.permissions" // grant/reset browser permissions for an origin (grant_permissions); Chrome only
   | "worker.targets"; // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
@@ -172,6 +173,8 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],
   dispatch_mouse: ["input.raw"],
+  focus_emulation: ["emulate.focus"],
+  click_focus_gated: ["emulate.focus"],
   wait_for_download: ["browser.downloads"],
   grant_permissions: ["browser.permissions"],
 } as const;

package/src/index.ts

@@ -43,6 +43,8 @@ import { lighthouseAudit } from "./tools/lighthouse.ts";
 import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
 // --- raw mouse dispatch (Input.dispatchMouseEvent, one event per call) : chrome-only, capability "input.raw" ---
 import { dispatchMouse } from "./tools/dispatch-mouse.ts";
+// --- focus emulation + focus-gated click (Emulation.setFocusEmulationEnabled) : chrome-only, capability "emulate.focus" ---
+import { focusEmulation, clickFocusGated } from "./tools/focus-emulation.ts";
 // --- downloads + permissions (browser-endpoint state on a standing connection) : chrome-only, 1.8.0 Track P3 ---
 import { waitForDownload } from "./tools/downloads.ts";
 import { grantPermissions } from "./tools/permissions.ts";
@@ -145,6 +147,10 @@ export const TOOLS = {
   clear_mocks: clearMocks,
   // raw mouse dispatch (1) : 1.8.0 Track P1 toolkit addition, chrome-only (capability "input.raw")
   dispatch_mouse: dispatchMouse,
+  // focus emulation (2) : fake page focus without stealing OS focus; trusted click on a focus-gated
+  // button (e.g. Claude Code OAuth Authorize). chrome-only (capability "emulate.focus")
+  focus_emulation: focusEmulation,
+  click_focus_gated: clickFocusGated,
   // downloads + permissions (2) : 1.8.0 Track P3 toolkit additions, chrome-only (capabilities
   // "browser.downloads" / "browser.permissions"). Both drive browser-endpoint state that Chrome
   // reverts when the issuing client disconnects, so both run on tools/browser-session.ts's standing

package/src/manifest.ts

@@ -674,6 +674,70 @@ export const MANIFEST: ToolSpec[] = [
       "additionalProperties": false
     }
   },
+  {
+    "name": "focus_emulation",
+    "description": "Toggle page focus emulation: the page reports focused/visible without the OS window moving; Chrome-only.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        "target": {
+          "type": "string",
+          "description": "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        "enabled": {
+          "type": "boolean",
+          "description": "true = page reports focused; false = restore real focus state."
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "additionalProperties": false
+    }
+  },
+  {
+    "name": "click_focus_gated",
+    "description": "Emulate page focus, wait for a focus-gated button to enable, trusted-click it, restore; Chrome-only.",
+    "inputSchema": {
+      "type": "object",
+      "properties": {
+        "lease": {
+          "type": "string",
+          "description": "Lease token; omit for a tab this process already holds. See server instructions."
+        },
+        "target": {
+          "type": "string",
+          "description": "Page selector (index:/url:/title:/label:/targetId, default active); grammar in server instructions."
+        },
+        "selector": {
+          "type": "string",
+          "description": "CSS selector of the button; exactly one of selector or text."
+        },
+        "text": {
+          "type": "string",
+          "description": "Visible-text match for the button (e.g. \"Authorize\"); exactly one of selector or text."
+        },
+        "timeoutMs": {
+          "type": "number",
+          "description": "Max ms to poll for the button to become enabled. Default 30000."
+        },
+        "pollMs": {
+          "type": "number",
+          "description": "Poll interval ms. Default 500."
+        },
+        "keepFocus": {
+          "type": "boolean",
+          "description": "Leave focus emulation on after the click (default false = restored)."
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    }
+  },
   {
     "name": "wait_for_download",
     "description": "Arm or collect a browser download; arm capture before triggering the download.",

package/src/toolDocs.ts

@@ -173,6 +173,26 @@ export const TOOL_DOCS: Record<string, ToolDoc> = {
       "modifiers": "Modifier keys held for this one event, e.g. ['Shift']."
     }
   },
+  "focus_emulation": {
+    "description": "Toggles CDP Emulation.setFocusEmulationEnabled on a tab: the page then BELIEVES it is focused (document.hasFocus()→true, visibilitychange stays 'visible', focus events fire) while the real OS window and active tab stay put — no focus theft. This is the primitive that unlocks focus-GATED UI (a button the site disables unless its tab is focused, e.g. Anthropic's Claude Code OAuth Authorize button on claude.ai/oauth/*) on a background tab. Chrome-only: WebDriver BiDi's emulation module has no focus primitive, so this tool is absent from tools/list under --browser firefox. Ports the core mechanism of the danbuhler/claude-code-auto-authorize extension. Remember to call with enabled:false to restore, or use click_focus_gated which restores automatically.",
+    "params": {
+      "lease": "Lease token from claim_page. Omit for a tab this process holds; required for a tab held by another process. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease). See server instructions.",
+      "target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'.",
+      "enabled": "true = page reports focused/visible; false = restore the real focus state."
+    }
+  },
+  "click_focus_gated": {
+    "description": "One-call compose of focus emulation + trusted click for a focus-gated button: enables Emulation.setFocusEmulationEnabled, polls until the button (located by CSS selector OR exact visible-text match, e.g. 'Authorize') exists AND is enabled, dispatches a trusted move/press/release click via Input.dispatchMouseEvent (isTrusted:true — a content script's synthesized events can never satisfy a focus gate), then restores focus emulation off unless keepFocus. Built for the Claude Code OAuth Authorize button but works on any focus-gated control on a background tab. Throws with a diagnostic ('never located' vs 'found but stayed disabled') on timeout. Chrome-only; absent under --browser firefox.",
+    "params": {
+      "lease": "Lease token from claim_page. Omit for a tab this process holds. Auto-acquired under CDP_REQUIRE_LEASE (then pass target, not lease).",
+      "target": "Page selector: 'active' (default), 'index:N', 'url:<substr>', 'title:<substr>', 'label:<name>', or a 32-hex '<targetId>'.",
+      "selector": "CSS selector of the button. Give exactly one of selector or text.",
+      "text": "Exact visible-text match of the button (trims whitespace, matches button/[role=button]/submit inputs), e.g. 'Authorize'. Give exactly one of selector or text.",
+      "timeoutMs": "Max ms to poll for the button to appear and become enabled. Default 30000.",
+      "pollMs": "Poll interval in ms. Default 500.",
+      "keepFocus": "Leave focus emulation ON after the click (default false — restored even on throw, so a failed click never strands the page fake-focused)."
+    }
+  },
   "wait_for_download": {
     "description": "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}, written under the artifact dir's downloads/. ORDERING RULE, not optional: capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (returns {armed:true,downloadPath,pending}), then click, then call again to collect the file. The download-behavior override is per-connection state Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so one triggered before arming is lost. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads dir until this server exits — they no longer land in the user's normal Downloads folder. The arm lives on a connection this server holds open (an MCP-server capability): under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under Firefox.",
     "params": {

package/src/toolGroups.ts

@@ -14,7 +14,7 @@ export const GROUP_TOOLS: Record<ToolGroup, readonly string[]> = {
   ],
   input: [
     "hover", "drag", "scroll", "dispatch_mouse", "press_key", "fill_form",
-    "upload_file",
+    "upload_file", "focus_emulation", "click_focus_gated",
   ],
   cookies: ["list_cookies", "set_cookie", "delete_cookies"],
   network: ["list_network_requests", "get_network_request"],

package/src/tools/focus-emulation.ts

@@ -0,0 +1,185 @@
+/**
+ * focus-emulation.ts: `focus_emulation` + `click_focus_gated` — the Chrome CDP primitive behind
+ * driving a focus-gated page (a button the site disables unless the tab is focused) WITHOUT
+ * stealing OS window focus.
+ *
+ * WHY THIS EXISTS (the mechanism it ports)
+ * ========================================
+ * Anthropic's Claude Code OAuth page (claude.ai/oauth/*) gates its Authorize button behind
+ * document.hasFocus()/visibilitychange: a background tab reports hasFocus()===false and the
+ * button stays disabled, so an agent driving claude -p's login has to keep a human clicking.
+ * The danbuhler/claude-code-auto-authorize Chrome extension defeats it with two CDP primitives:
+ *   1. Emulation.setFocusEmulationEnabled {enabled:true} — the page BELIEVES it is focused
+ *      (hasFocus()→true, visibilitychange stays "visible", focus events fire) while the real
+ *      OS window stays put; and
+ *   2. Input.dispatchMouseEvent — a TRUSTED click (isTrusted:true) on that background tab,
+ *      which a content script's synthesized events (isTrusted:false) can never produce.
+ * This module is that pair as toolkit tools: focus_emulation is the raw toggle;
+ * click_focus_gated composes toggle → locate-button → trusted-click → restore.
+ *
+ * WHY CHROME-ONLY (capability "emulate.focus", declared in ../driver.ts /
+ * ../cdp/driver.ts): WebDriver BiDi has no focus-emulation module (the emulation module covers
+ * geolocation/timezone/locale/scripting only), so under --browser firefox BOTH tools are absent
+ * from tools/list (ADR-001: absent, never present-and-throwing) — like dispatch_mouse and
+ * start_screen_recording.
+ *
+ * Lease gate: withPage (client.ts) → resolveTarget → assertLeaseOk("chrome", ...), the same
+ * choke point as every input tool.
+ */
+import { sendInput } from "../activity.ts";
+import { withPage } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+
+export interface FocusEmulationArgs {
+  target?: TargetSelector;
+  lease?: string;
+  /** true → the page reports focused; false → restore real focus state. */
+  enabled: boolean;
+}
+
+export interface FocusEmulationResult {
+  enabled: boolean;
+}
+
+export interface ClickFocusGatedArgs {
+  target?: TargetSelector;
+  lease?: string;
+  /** CSS selector of the button to click once focus is emulated. Exactly one of selector/text. */
+  selector?: string;
+  /** Visible-text match for the button (e.g. "Authorize"); exact-trim match, case-sensitive. */
+  text?: string;
+  /** Max ms to poll for the button to exist AND become enabled. Default 30000. */
+  timeoutMs?: number;
+  /** Poll interval ms. Default 500. */
+  pollMs?: number;
+  /** Leave focus emulation ON after the click (default false — always restored). */
+  keepFocus?: boolean;
+}
+
+export interface ClickFocusGatedResult {
+  clicked: boolean;
+  x: number;
+  y: number;
+  /** How the button was located. */
+  matchedBy: "selector" | "text";
+  /** ms from call to click. */
+  elapsedMs: number;
+}
+
+export function validateFocusEmulationArgs(args: FocusEmulationArgs): void {
+  if (typeof args.enabled !== "boolean") {
+    throw new Error("focus_emulation requires { enabled } of true or false");
+  }
+}
+
+export function validateClickFocusGatedArgs(args: ClickFocusGatedArgs): void {
+  const hasSel = typeof args.selector === "string" && args.selector.length > 0;
+  const hasText = typeof args.text === "string" && args.text.length > 0;
+  if (hasSel === hasText) {
+    throw new Error("click_focus_gated requires exactly one of { selector } or { text }");
+  }
+  if (args.timeoutMs !== undefined && (!Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0)) {
+    throw new Error("click_focus_gated: timeoutMs must be a positive number");
+  }
+  if (args.pollMs !== undefined && (!Number.isFinite(args.pollMs) || args.pollMs <= 0)) {
+    throw new Error("click_focus_gated: pollMs must be a positive number");
+  }
+}
+
+const FIND_BUTTON = `(() => {
+  const SEL = %SEL%;
+  const TEXT = %TEXT%;
+  let btn = null;
+  let matchedBy = null;
+  if (SEL) {
+    btn = document.querySelector(SEL);
+    if (btn) matchedBy = "selector";
+  }
+  if (!btn && TEXT) {
+    btn = Array.from(document.querySelectorAll("button,[role=button],input[type=submit]"))
+      .find((b) => (b.textContent || b.value || "").trim() === TEXT);
+    if (btn) matchedBy = "text";
+  }
+  if (!btn) return null;
+  const r = btn.getBoundingClientRect();
+  if (r.width === 0 || r.height === 0) return null;
+  return { x: r.left + r.width / 2, y: r.top + r.height / 2,
+           disabled: !!btn.disabled || btn.getAttribute("aria-disabled") === "true",
+           matchedBy, hasFocus: document.hasFocus(), visibility: document.visibilityState };
+})()`;
+
+function findButtonExpression(selector: string | undefined, text: string | undefined): string {
+  return FIND_BUTTON.replace("%SEL%", JSON.stringify(selector ?? null)).replace(
+    "%TEXT%",
+    JSON.stringify(text ?? null),
+  );
+}
+
+/** Toggle page focus emulation. The page reports focused/visible without the OS window moving. */
+export async function focusEmulation(args: FocusEmulationArgs): Promise<FocusEmulationResult> {
+  validateFocusEmulationArgs(args);
+  return withPage(
+    args.target,
+    async (conn) => {
+      await conn.send("Emulation.setFocusEmulationEnabled", { enabled: args.enabled });
+      return { enabled: args.enabled };
+    },
+    { lease: args.lease },
+  );
+}
+
+/**
+ * Emulate focus, poll for a focus-gated button to become enabled, trusted-click it, restore.
+ * The restore runs in `finally` unless keepFocus — a thrown click never strands the page in a
+ * fake-focused state.
+ */
+export async function clickFocusGated(args: ClickFocusGatedArgs): Promise<ClickFocusGatedResult> {
+  validateClickFocusGatedArgs(args);
+  const timeoutMs = args.timeoutMs ?? 30_000;
+  const pollMs = args.pollMs ?? 500;
+  const start = Date.now();
+  return withPage(
+    args.target,
+    async (conn, target) => {
+      await conn.send("Emulation.setFocusEmulationEnabled", { enabled: true });
+      try {
+        const expression = findButtonExpression(args.selector, args.text);
+        for (;;) {
+          const { result } = await conn.send<{ result: { value?: unknown } }>("Runtime.evaluate", {
+            expression,
+            returnByValue: true,
+          });
+          const btn = (result as { value?: unknown } | undefined)?.value as
+            | { x: number; y: number; disabled: boolean; matchedBy: "selector" | "text" }
+            | null
+            | undefined;
+          if (btn && !btn.disabled) {
+            const base = { x: btn.x, y: btn.y, button: "left", buttons: 1, clickCount: 1 };
+            await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { type: "mouseMoved", x: btn.x, y: btn.y });
+            await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mousePressed" });
+            await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", { ...base, type: "mouseReleased" });
+            return {
+              clicked: true,
+              x: btn.x,
+              y: btn.y,
+              matchedBy: btn.matchedBy,
+              elapsedMs: Date.now() - start,
+            };
+          }
+          if (Date.now() - start >= timeoutMs) {
+            throw new Error(
+              `click_focus_gated: button never became clickable within ${timeoutMs}ms` +
+                (btn ? " (found but stayed disabled — focus emulation may not satisfy this gate)" : " (never located)"),
+            );
+          }
+          await new Promise((r) => setTimeout(r, pollMs));
+        }
+      } finally {
+        if (!args.keepFocus) {
+          await conn.send("Emulation.setFocusEmulationEnabled", { enabled: false }).catch(() => {});
+        }
+      }
+    },
+    { lease: args.lease, timeoutMs: timeoutMs + 5_000 },
+  );
+}

package/src/version.ts

@@ -6,4 +6,4 @@
  * ready line; keeping it in its own module means a release bump touches one
  * line here plus package.json, not a const buried in the server.
  */
-export const VERSION = "2.2.0";
+export const VERSION = "2.3.0";