cdp-toolkit 2.1.0 → 2.3.0

package/src/bidi/session-lease.ts

@@ -35,8 +35,34 @@
  * ATOMICITY. Claims are exclusive creates (writeFile flag "wx"), exactly like
  * ../leases.ts claimLease, so "is the slot free, and if so take it" is atomic
  * against a racing process for free, with no registry lock.
+ *
+ * THE MUX: WHY A LIVE HOLDER IS NO LONGER A DEAD END. Everything above still
+ * holds — one process owns Firefox's single BiDi session — but the holder now
+ * also hosts a loopback BiDi multiplexer (./mux.ts) over that one real session
+ * and ADVERTISES its ws endpoint in this record (`muxEndpoint`). Two consequences
+ * for this module, and nothing else changes:
+ *
+ *  - THE HOLDER advertises via advertiseMux() once its mux is listening. That is
+ *    a rewrite of its OWN record, guarded by the same (pid, createdAt) ownership
+ *    test release uses, and written atomically (tmp + rename) so a concurrent
+ *    reader never sees a half-written record. Advertising is best-effort: a
+ *    refusal (`advertised:false`) means the record is no longer ours and the
+ *    holder simply runs alone.
+ *  - A JOINER DOES NOT WAIT. When acquire finds a LIVE holder that carries a
+ *    muxEndpoint, there is nothing to wait FOR: the slot will not free up (the
+ *    holder is healthy) and it does not need to, because the mux serves that one
+ *    session to as many processes as ask. So acquire returns { joinMux }
+ *    immediately, with NO handle and nothing written to disk — the joiner holds
+ *    no slot and must never release one. The record is re-read on every poll
+ *    iteration, so a holder that took the slot a moment ago and advertises a beat
+ *    later is joined as soon as it does, inside the existing wait window.
+ *
+ * A live holder with NO muxEndpoint (a foreign client, an older cdp-toolkit, or
+ * one running with CDP_FIREFOX_MUX=off) is still plain BUSY and still throws
+ * SessionSlotBusyError at the deadline — exactly today's behavior. CDP_FIREFOX_MUX=off
+ * makes acquire ignore muxEndpoint entirely, which is the opt-out.
  */
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { isPidAlive, leaseDir } from "../leases.ts";
 
@@ -55,6 +81,12 @@ export interface SessionSlotRecord {
   createdAt: number;
   /** Optional Marionette control port bound to this Firefox, when known. */
   marionettePort?: number;
+  /**
+   * Loopback ws endpoint of the BiDi multiplexer this holder hosts over the one
+   * real session (see ./mux.ts and the header). Absent means "this holder serves
+   * nobody but itself", which is what every pre-mux client's record looks like.
+   */
+  muxEndpoint?: string;
 }
 
 /**
@@ -68,7 +100,11 @@ export interface SessionSlotHandle {
 }
 
 export interface AcquireResult {
-  handle: SessionSlotHandle;
+  /**
+   * Present iff WE took the slot. Absent on the joinMux path: a joiner owns no
+   * slot, wrote no record, and must never release one.
+   */
+  handle?: SessionSlotHandle;
   /**
    * Set only when we STOLE a dead holder's slot. Its presence tells the caller
    * that Firefox may still believe an orphaned BiDi session is active, so the
@@ -77,6 +113,12 @@ export interface AcquireResult {
    * sessions". Absent on a clean first acquire.
    */
   staleHolder?: SessionSlotRecord;
+  /**
+   * Set instead of `handle` when a LIVE holder advertises a BiDi multiplexer.
+   * The caller dials `endpoint` exactly as it would dial Firefox; `holder` is the
+   * record it came from, for error reporting. Nothing was written to disk.
+   */
+  joinMux?: { endpoint: string; holder: SessionSlotRecord };
 }
 
 export interface AcquireOptions {
@@ -105,6 +147,16 @@ export function sessionSlotFile(endpoint: string): string {
   return join(leaseDir(), `ff-session-${safeEndpoint(endpoint)}.json`);
 }
 
+/**
+ * Where the detached mux DAEMON (./mux-daemon.ts) appends its one-line diagnostics for this
+ * endpoint. It is spawned with stdio:"ignore" (no console at all), so this file is the ONLY
+ * record of why a daemon refused to start; the driver names it in the error it raises when a
+ * daemon it spawned never advertised. Sibling of the slot file, same safeEndpoint key.
+ */
+export function muxDaemonLogFile(endpoint: string): string {
+  return join(leaseDir(), `ff-mux-${safeEndpoint(endpoint)}.log`);
+}
+
 /** Read per call (like leaseDir/leaseTtlMs), so a test can redirect it. A value
  *  that is not a finite number > 0 falls back to the default. */
 export function sessionWaitMs(): number {
@@ -236,7 +288,16 @@ export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions)
       }
     }
 
-    // 4. LIVE holder: legitimate contention. Poll until the deadline, then fail.
+    // 4. LIVE holder. If it advertises a mux, JOIN it instead of waiting: the slot
+    // is never going to free up, and it does not have to — the holder's mux serves
+    // the one real session to every joiner. Return immediately, writing nothing.
+    // (The re-read at step 2 happens every iteration, so a holder that advertises a
+    // beat after taking the slot is picked up on the next poll.) CDP_FIREFOX_MUX=off
+    // opts out and restores the pre-mux busy-wait exactly.
+    if (typeof holder.muxEndpoint === "string" && holder.muxEndpoint.length > 0 && process.env.CDP_FIREFOX_MUX !== "off") {
+      return { joinMux: { endpoint: holder.muxEndpoint, holder } };
+    }
+    // No mux: legitimate contention. Poll until the deadline, then fail.
     lastLiveHolder = holder;
     const remaining = deadline - Date.now();
     if (remaining <= 0) throw new SessionSlotBusyError(endpoint, holder);
@@ -244,6 +305,37 @@ export async function acquireSessionSlot(endpoint: string, opts: AcquireOptions)
   }
 }
 
+/**
+ * Publish this holder's BiDi multiplexer endpoint into its OWN slot record, so a
+ * contending process joins the mux instead of waiting out the slot.
+ *
+ * Ownership-guarded by the same (pid, createdAt) test releaseSessionSlot uses: if
+ * the record on disk is missing or belongs to someone else (we were stolen from
+ * as a dead-looking holder, or we already released), we refuse with
+ * { advertised: false } and leave the file byte-for-byte untouched rather than
+ * stamping our mux onto a stranger's claim.
+ *
+ * Atomic: the merged record is written to `<file>.tmp-<pid>` and renamed over the
+ * original, so a concurrent acquire's read sees either the old record or the new
+ * one, never a truncated one. Every other field is preserved.
+ */
+export async function advertiseMux(handle: SessionSlotHandle, muxEndpoint: string): Promise<{ advertised: boolean }> {
+  const current = await readSessionSlot(handle.endpoint);
+  if (!current) return { advertised: false };
+  if (current.pid !== process.pid || current.createdAt !== handle.createdAt) return { advertised: false };
+  const file = sessionSlotFile(handle.endpoint);
+  const tmp = `${file}.tmp-${process.pid}`;
+  const next: SessionSlotRecord = { ...current, muxEndpoint };
+  try {
+    await writeFile(tmp, JSON.stringify(next), "utf8");
+    await rename(tmp, file);
+  } catch {
+    await unlink(tmp).catch(() => undefined);
+    return { advertised: false };
+  }
+  return { advertised: true };
+}
+
 /**
  * Release the slot, but ONLY if the record on disk is still the one we wrote.
  *

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

@@ -230,6 +230,7 @@ export const MANIFEST: ToolSpec[] = [
         },
         "args": {
           "type": "array",
+          "items": {},
           "description": "Positional JSON arguments."
         },
         "savePath": {
@@ -673,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.1.0";
+export const VERSION = "2.3.0";