cdp-toolkit 2.1.0 → 2.3.0

package/dist/index.js

@@ -1,9 +1,20 @@
+var __esm = (fn, res, err) => () => {
+  if (fn)
+    try {
+      res = fn(fn = 0);
+    } catch (e) {
+      err = [e];
+    }
+  if (err)
+    throw err[0];
+  return res;
+};
+
 // src/leases.ts
 import { AsyncLocalStorage } from "node:async_hooks";
 import { randomBytes } from "node:crypto";
 import { mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-var DEFAULT_LEASE_TTL_MS = 900000;
 function leaseDir() {
   return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 }
@@ -11,7 +22,6 @@ function leaseTtlMs() {
   const raw = Number(process.env.CDP_LEASE_TTL_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
-var longLived = false;
 function markLongLivedProcess(value = true) {
   longLived = value;
 }
@@ -49,17 +59,6 @@ function tokenParts(token) {
     return;
   return { backend, targetId, nonce };
 }
-
-class LeaseConflictError extends Error {
-  targetId;
-  holder;
-  constructor(message, targetId, holder) {
-    super(message);
-    this.targetId = targetId;
-    this.holder = holder;
-    this.name = "LeaseConflictError";
-  }
-}
 async function readLease(backend, targetId) {
   let raw;
   try {
@@ -150,7 +149,6 @@ async function releaseLeaseFor(backend, targetId) {
   });
   return { released: true };
 }
-var leaseScope = new AsyncLocalStorage;
 function withLeaseScope(lease, fn) {
   return leaseScope.run(lease, fn);
 }
@@ -217,7 +215,6 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
   }
   await touchLease(held, now);
 }
-var LEASE_FILE_RE = /^lease-(chrome|firefox)-(.+)\.json$/;
 async function listLeases(opts = {}) {
   const now = opts.now ?? Date.now();
   let names = [];
@@ -275,6 +272,21 @@ async function listLeases(opts = {}) {
   }
   return out;
 }
+var DEFAULT_LEASE_TTL_MS = 900000, longLived = false, LeaseConflictError, leaseScope, LEASE_FILE_RE;
+var init_leases = __esm(() => {
+  LeaseConflictError = class LeaseConflictError extends Error {
+    targetId;
+    holder;
+    constructor(message, targetId, holder) {
+      super(message);
+      this.targetId = targetId;
+      this.holder = holder;
+      this.name = "LeaseConflictError";
+    }
+  };
+  leaseScope = new AsyncLocalStorage;
+  LEASE_FILE_RE = /^lease-(chrome|firefox)-(.+)\.json$/;
+});
 
 // src/origins.ts
 import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
@@ -285,7 +297,6 @@ function safeId2(id) {
 function originFile(backend, targetId) {
   return join2(leaseDir(), `origin-${backend}-${safeId2(targetId)}.json`);
 }
-var ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
 async function recordOrigin(backend, targetId, opts = {}) {
   const record = {
     backend,
@@ -401,16 +412,13 @@ async function resolveLiveLabel(backend, label, liveIds) {
   }
   return { matchIds: [...matchIds], knownLabels: [...knownLabels].sort() };
 }
+var ORIGIN_FILE_RE;
+var init_origins = __esm(() => {
+  init_leases();
+  ORIGIN_FILE_RE = /^origin-(chrome|firefox)-(.+)\.json$/;
+});
 
 // src/workers.ts
-var WORKER_SELECTOR_PREFIX = "worker:";
-var WORKER_CAPABLE_TOOLS = [
-  "evaluate_script",
-  "list_network_requests",
-  "get_network_request",
-  "list_console_messages"
-];
-var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
 function isWorkerSelector(selector) {
   return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
 }
@@ -427,9 +435,6 @@ function resolveWorkerTargets(targets, needle) {
     liveWorkers
   };
 }
-var WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js";
-var WORKER_SELECTOR_UNSUPPORTED_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " + "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " + "Use --browser chrome to evaluate in, or record console/network from, an extension's background worker.";
-var WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
 function workerWakeMisuseMessage(kind) {
   if (kind === "not-a-worker-selector") {
     return "'wake' only applies to a target of the form 'worker:<substring>'. A page is never asleep, and a bare " + "worker target id cannot be woken either: Chrome destroys the target when an MV3 worker is evicted and " + "mints a NEW id when it restarts, so only the url-substring form can name a worker that is not running.";
@@ -454,22 +459,20 @@ function workerMissMessage(needle, opts) {
   const scopes = opts.registeredScopes?.length ? ` Registered service-worker scopes in this browser: ${opts.registeredScopes.join(", ")}.` : " No service-worker registrations were reported by this browser at all.";
   return `no worker whose url contains '${needle}' could be reached${running}. ` + `A start was requested (wake:true) and no matching worker appeared.${scopes} ` + "If the extension is installed but its worker never starts, check the worker script for a top-level throw.";
 }
+var WORKER_SELECTOR_PREFIX = "worker:", WORKER_CAPABLE_TOOLS, WORKER_TARGET_TYPES, WORKER_EMPTY_NEEDLE_MESSAGE = "'worker:' needs a substring of the worker's url, e.g. worker:<extension-id> or worker:background.js", WORKER_SELECTOR_UNSUPPORTED_MESSAGE, WORKER_SELECTOR_PAGE_ONLY_MESSAGE;
+var init_workers = __esm(() => {
+  WORKER_CAPABLE_TOOLS = [
+    "evaluate_script",
+    "list_network_requests",
+    "get_network_request",
+    "list_console_messages"
+  ];
+  WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
+  WORKER_SELECTOR_UNSUPPORTED_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, which this backend cannot address " + "(WebDriver BiDi has no extension service-worker target; Capability 'worker.targets' is Chrome-only). " + "Use --browser chrome to evaluate in, or record console/network from, an extension's background worker.";
+  WORKER_SELECTOR_PAGE_ONLY_MESSAGE = "target 'worker:<substring>' selects a service/shared worker, and this tool is page-only " + "(closing, selecting or releasing a worker is meaningless). The tools that accept a worker: target are " + `${WORKER_CAPABLE_TOOLS.join(", ")}.`;
+});
 
 // src/client.ts
-var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
-var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
-
-class CdpError extends Error {
-  code;
-  data;
-  constructor(message, code, data) {
-    super(message);
-    this.code = code;
-    this.data = data;
-    this.name = "CdpError";
-  }
-}
-
 class CdpConnection {
   wsUrl;
   opts;
@@ -688,31 +691,29 @@ async function withPage(selector, fn, opts = {}) {
     conn.close();
   }
 }
+var BASE, DEFAULT_TIMEOUT_MS, CdpError;
+var init_client = __esm(() => {
+  init_leases();
+  init_origins();
+  init_workers();
+  BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
+  DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
+  CdpError = class CdpError extends Error {
+    code;
+    data;
+    constructor(message, code, data) {
+      super(message);
+      this.code = code;
+      this.data = data;
+      this.name = "CdpError";
+    }
+  };
+});
 
 // src/activity.ts
-var BEACON_DATA_GLOBAL = "__cdpToolkitLastInput";
-var BEACON_INSTALLED_GLOBAL = "__cdpToolkitBeacon";
-var BEACON_EVENTS = ["pointerdown", "mousedown", "keydown", "wheel", "touchstart"];
-var BEACON_BODY = `
-  if (!window.${BEACON_INSTALLED_GLOBAL}) {
-    window.${BEACON_INSTALLED_GLOBAL} = true;
-    var mark = function () { window.${BEACON_DATA_GLOBAL} = Date.now(); };
-    var events = ${JSON.stringify([...BEACON_EVENTS])};
-    for (var i = 0; i < events.length; i++) {
-      window.addEventListener(events[i], mark, { capture: true, passive: true });
-    }
-  }`;
-var BEACON_SOURCE = `(function () {${BEACON_BODY}
-})();`;
-var BEACON_FUNCTION_DECLARATION = `function () {${BEACON_BODY}
-}`;
-var BEACON_READ_EXPRESSION = `(typeof window.${BEACON_DATA_GLOBAL} === "number" ? window.${BEACON_DATA_GLOBAL} : null)`;
-var DISPATCH_ATTRIBUTION_WINDOW_MS = 1500;
 function dispatchKey(backend, targetId) {
   return `${backend}:${targetId}`;
 }
-var dispatchLog = new Map;
-var DISPATCH_LOG_LIMIT = 512;
 function recordDispatch(backend, targetId, now = Date.now()) {
   const key = dispatchKey(backend, targetId);
   dispatchLog.delete(key);
@@ -724,7 +725,6 @@ function recordDispatch(backend, targetId, now = Date.now()) {
     dispatchLog.delete(oldest.value);
   }
 }
-var NON_SYNTHESIZING_INPUT_METHODS = new Set(["Input.setInterceptDrags", "Input.setIgnoreInputEvents"]);
 async function sendInput(conn, backend, targetId, method, params = {}) {
   if (!NON_SYNTHESIZING_INPUT_METHODS.has(method))
     recordDispatch(backend, targetId);
@@ -743,7 +743,6 @@ function humanActiveMs(beaconTs, dispatchAt, now = Date.now(), windowMs = DISPAT
     return null;
   return Math.max(0, now - beaconTs);
 }
-var CONTENTION_WINDOW_MS = 30000;
 function contentionWarning(ms, opts) {
   if (!opts.takeover)
     return;
@@ -765,8 +764,6 @@ async function readHumanActiveMs(driver, backend, targetId, now = Date.now()) {
   const beaconTs = await driver.readActivityBeacon(targetId).catch(() => null);
   return humanActiveMs(beaconTs, lastDispatchAt(backend, targetId), now);
 }
-var RENDERER_PROBE_TIMEOUT_MS = 500;
-var RENDERER_PROBE_EXPRESSION = `[1, ${BEACON_READ_EXPRESSION}]`;
 function rendererProbeSupported(driver) {
   return typeof driver.probeRenderer === "function";
 }
@@ -823,123 +820,27 @@ class BeaconSessions {
     } catch {}
   }
 }
-
-// src/tools/snapshot.ts
-var INTERACTIVE_ROLES = new Set([
-  "button",
-  "link",
-  "textbox",
-  "searchbox",
-  "checkbox",
-  "radio",
-  "combobox",
-  "listbox",
-  "option",
-  "menuitem",
-  "menuitemcheckbox",
-  "menuitemradio",
-  "tab",
-  "switch",
-  "slider",
-  "spinbutton",
-  "textfield",
-  "MenuItem",
-  "Button"
-]);
-async function resolveUid(conn, uid) {
-  const { object } = await conn.send("DOM.resolveNode", {
-    backendNodeId: uid
-  });
-  if (!object?.objectId) {
-    throw new Error(`resolveUid: DOM.resolveNode returned no objectId for uid ${uid}`);
-  }
-  return { objectId: object.objectId };
-}
-
-// src/cdp/workers.ts
-var INVENTORY_FIRST_EVENT_MS = 1500;
-var INVENTORY_SETTLE_MS = 250;
-var WAKE_POLL_MS = 300;
-var WAKE_POLL_ATTEMPTS = 30;
-var NO_HOST_PAGE_MESSAGE = "cannot start a service worker: the ServiceWorker CDP domain is only reachable over a page session, " + "and this browser has no page target open. Open any tab (new_page) and retry — the tab does not have " + "to belong to the extension.";
-var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-async function requestWorkerStart(needle) {
-  const conn = await openBrowser();
-  try {
-    const host = (await listTargets()).find((t) => t.type === "page");
-    if (!host)
-      throw new CdpError(NO_HOST_PAGE_MESSAGE);
-    const { sessionId } = await conn.send("Target.attachToTarget", {
-      targetId: host.id,
-      flatten: true
-    });
-    if (!sessionId)
-      throw new CdpError("could not attach a session to host the ServiceWorker domain");
-    const scopeById = new Map;
-    const versions = [];
-    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
-      for (const r of params.registrations ?? []) {
-        if (r.isDeleted === true)
-          continue;
-        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
-      }
-    });
-    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
-      for (const v of params.versions ?? []) {
-        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
-      }
-    });
-    await conn.send("ServiceWorker.enable", {}, { sessionId });
-    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => {
-      return;
-    });
-    await sleep(INVENTORY_SETTLE_MS);
-    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
-    const matched = new Set;
-    for (const v of versions) {
-      const scope = scopeById.get(v.registrationId);
-      if (scope === undefined)
-        continue;
-      if (v.scriptURL.includes(needle) || scope.includes(needle))
-        matched.add(scope);
-    }
-    if (matched.size === 0)
-      return { startRequested: false, scopes };
-    if (matched.size > 1) {
-      throw new CdpError(`'worker:${needle}' matches more than one registered service-worker scope: ${[...matched].sort().join(", ")}. ` + "Narrow the substring.");
-    }
-    await conn.send("ServiceWorker.startWorker", { scopeURL: [...matched][0] }, { sessionId });
-    return { startRequested: true, scopes };
-  } finally {
-    conn.close();
-  }
-}
-async function resolveWorkerSelector(selector, opts) {
-  const needle = workerNeedle(selector);
-  if (needle === "")
-    throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
-  const first = resolveWorkerTargets(await listTargets(), needle);
-  if (first.matches.length > 1)
-    throw new CdpError(workerAmbiguityMessage(needle, first.matches));
-  if (first.matches.length === 1)
-    return first.matches[0];
-  if (!opts.wake) {
-    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers: first.liveWorkers }));
-  }
-  const { startRequested, scopes } = await requestWorkerStart(needle);
-  if (startRequested) {
-    for (let i = 0;i < WAKE_POLL_ATTEMPTS; i++) {
-      await sleep(WAKE_POLL_MS);
-      const again = resolveWorkerTargets(await listTargets(), needle);
-      if (again.matches.length > 1)
-        throw new CdpError(workerAmbiguityMessage(needle, again.matches));
-      if (again.matches.length === 1)
-        return again.matches[0];
+var BEACON_DATA_GLOBAL = "__cdpToolkitLastInput", BEACON_INSTALLED_GLOBAL = "__cdpToolkitBeacon", BEACON_EVENTS, BEACON_BODY, BEACON_SOURCE, BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, DISPATCH_ATTRIBUTION_WINDOW_MS = 1500, dispatchLog, DISPATCH_LOG_LIMIT = 512, NON_SYNTHESIZING_INPUT_METHODS, CONTENTION_WINDOW_MS = 30000, RENDERER_PROBE_TIMEOUT_MS = 500, RENDERER_PROBE_EXPRESSION;
+var init_activity = __esm(() => {
+  BEACON_EVENTS = ["pointerdown", "mousedown", "keydown", "wheel", "touchstart"];
+  BEACON_BODY = `
+  if (!window.${BEACON_INSTALLED_GLOBAL}) {
+    window.${BEACON_INSTALLED_GLOBAL} = true;
+    var mark = function () { window.${BEACON_DATA_GLOBAL} = Date.now(); };
+    var events = ${JSON.stringify([...BEACON_EVENTS])};
+    for (var i = 0; i < events.length; i++) {
+      window.addEventListener(events[i], mark, { capture: true, passive: true });
     }
-  }
-  const final = resolveWorkerTargets(await listTargets(), needle);
-  throw new CdpError(workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }));
-}
+  }`;
+  BEACON_SOURCE = `(function () {${BEACON_BODY}
+})();`;
+  BEACON_FUNCTION_DECLARATION = `function () {${BEACON_BODY}
+}`;
+  BEACON_READ_EXPRESSION = `(typeof window.${BEACON_DATA_GLOBAL} === "number" ? window.${BEACON_DATA_GLOBAL} : null)`;
+  dispatchLog = new Map;
+  NON_SYNTHESIZING_INPUT_METHODS = new Set(["Input.setInterceptDrags", "Input.setIgnoreInputEvents"]);
+  RENDERER_PROBE_EXPRESSION = `[1, ${BEACON_READ_EXPRESSION}]`;
+});
 
 // src/tools/network_mock.ts
 function escapeRegExpChar(ch) {
@@ -991,7 +892,6 @@ function effectiveAction(rule, rnd) {
     return "fail";
   return rule.action;
 }
-var sessions = new Map;
 function delay(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
@@ -1117,28 +1017,15 @@ async function clearMocks(args = {}) {
   }
   return { cleared };
 }
+var sessions;
+var init_network_mock = __esm(() => {
+  init_client();
+  sessions = new Map;
+});
 
 // src/driver.ts
 import { mkdir as mkdir3, readFile as readFile3, unlink as unlink3, writeFile as writeFile3 } from "node:fs/promises";
 import { join as join3 } from "node:path";
-var UID_STAMP_ATTR = "data-cdp-uid";
-var LEGACY_NUMERIC_UID = /^[0-9]+$/;
-var REQUIRED_CAPABILITIES = {
-  performance_start_trace: ["trace.performance"],
-  performance_stop_trace: ["trace.performance"],
-  performance_analyze_insight: ["trace.performance"],
-  performance_trace: ["trace.performance"],
-  take_heapsnapshot: ["heap.snapshot"],
-  lighthouse_audit: ["audit.lighthouse"],
-  start_screen_recording: ["capture.screencast"],
-  stop_screen_recording: ["capture.screencast"],
-  mock_request: ["network.intercept"],
-  list_mocks: ["network.intercept"],
-  clear_mocks: ["network.intercept"],
-  dispatch_mouse: ["input.raw"],
-  wait_for_download: ["browser.downloads"],
-  grant_permissions: ["browser.permissions"]
-};
 function isDriverError(e) {
   return e instanceof Error && typeof e.code === "string";
 }
@@ -1185,8 +1072,158 @@ async function clearViewportRecord(scheme, targetId) {
     await unlink3(viewportRecordFile(scheme, targetId));
   } catch {}
 }
+var UID_STAMP_ATTR = "data-cdp-uid", LEGACY_NUMERIC_UID, REQUIRED_CAPABILITIES;
+var init_driver = __esm(() => {
+  init_leases();
+  LEGACY_NUMERIC_UID = /^[0-9]+$/;
+  REQUIRED_CAPABILITIES = {
+    performance_start_trace: ["trace.performance"],
+    performance_stop_trace: ["trace.performance"],
+    performance_analyze_insight: ["trace.performance"],
+    performance_trace: ["trace.performance"],
+    take_heapsnapshot: ["heap.snapshot"],
+    lighthouse_audit: ["audit.lighthouse"],
+    start_screen_recording: ["capture.screencast"],
+    stop_screen_recording: ["capture.screencast"],
+    mock_request: ["network.intercept"],
+    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"]
+  };
+});
+
+// src/cdp/driver.ts
+init_client();
+init_leases();
+init_activity();
+
+// src/tools/snapshot.ts
+init_client();
+var INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "option",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "switch",
+  "slider",
+  "spinbutton",
+  "textfield",
+  "MenuItem",
+  "Button"
+]);
+async function resolveUid(conn, uid) {
+  const { object } = await conn.send("DOM.resolveNode", {
+    backendNodeId: uid
+  });
+  if (!object?.objectId) {
+    throw new Error(`resolveUid: DOM.resolveNode returned no objectId for uid ${uid}`);
+  }
+  return { objectId: object.objectId };
+}
+
+// src/cdp/workers.ts
+init_client();
+init_workers();
+var INVENTORY_FIRST_EVENT_MS = 1500;
+var INVENTORY_SETTLE_MS = 250;
+var WAKE_POLL_MS = 300;
+var WAKE_POLL_ATTEMPTS = 30;
+var NO_HOST_PAGE_MESSAGE = "cannot start a service worker: the ServiceWorker CDP domain is only reachable over a page session, " + "and this browser has no page target open. Open any tab (new_page) and retry — the tab does not have " + "to belong to the extension.";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function requestWorkerStart(needle) {
+  const conn = await openBrowser();
+  try {
+    const host = (await listTargets()).find((t) => t.type === "page");
+    if (!host)
+      throw new CdpError(NO_HOST_PAGE_MESSAGE);
+    const { sessionId } = await conn.send("Target.attachToTarget", {
+      targetId: host.id,
+      flatten: true
+    });
+    if (!sessionId)
+      throw new CdpError("could not attach a session to host the ServiceWorker domain");
+    const scopeById = new Map;
+    const versions = [];
+    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
+      for (const r of params.registrations ?? []) {
+        if (r.isDeleted === true)
+          continue;
+        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
+      }
+    });
+    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
+      for (const v of params.versions ?? []) {
+        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
+      }
+    });
+    await conn.send("ServiceWorker.enable", {}, { sessionId });
+    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => {
+      return;
+    });
+    await sleep(INVENTORY_SETTLE_MS);
+    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
+    const matched = new Set;
+    for (const v of versions) {
+      const scope = scopeById.get(v.registrationId);
+      if (scope === undefined)
+        continue;
+      if (v.scriptURL.includes(needle) || scope.includes(needle))
+        matched.add(scope);
+    }
+    if (matched.size === 0)
+      return { startRequested: false, scopes };
+    if (matched.size > 1) {
+      throw new CdpError(`'worker:${needle}' matches more than one registered service-worker scope: ${[...matched].sort().join(", ")}. ` + "Narrow the substring.");
+    }
+    await conn.send("ServiceWorker.startWorker", { scopeURL: [...matched][0] }, { sessionId });
+    return { startRequested: true, scopes };
+  } finally {
+    conn.close();
+  }
+}
+async function resolveWorkerSelector(selector, opts) {
+  const needle = workerNeedle(selector);
+  if (needle === "")
+    throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+  const first = resolveWorkerTargets(await listTargets(), needle);
+  if (first.matches.length > 1)
+    throw new CdpError(workerAmbiguityMessage(needle, first.matches));
+  if (first.matches.length === 1)
+    return first.matches[0];
+  if (!opts.wake) {
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers: first.liveWorkers }));
+  }
+  const { startRequested, scopes } = await requestWorkerStart(needle);
+  if (startRequested) {
+    for (let i = 0;i < WAKE_POLL_ATTEMPTS; i++) {
+      await sleep(WAKE_POLL_MS);
+      const again = resolveWorkerTargets(await listTargets(), needle);
+      if (again.matches.length > 1)
+        throw new CdpError(workerAmbiguityMessage(needle, again.matches));
+      if (again.matches.length === 1)
+        return again.matches[0];
+    }
+  }
+  const final = resolveWorkerTargets(await listTargets(), needle);
+  throw new CdpError(workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }));
+}
 
 // src/cdp/driver.ts
+init_network_mock();
+init_driver();
 function driverError(code, message, data) {
   return Object.assign(new Error(message), { code, ...data !== undefined ? { data } : {} });
 }
@@ -1249,12 +1286,12 @@ async function awaitScrollSettle(conn) {
     return;
   });
 }
-async function setValueOnObject(conn, objectId, value, sendInput2) {
+async function setValueOnObject(conn, objectId, value, sendInput) {
   await focusElement(conn, objectId);
   const fn = "function(){if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}}";
   await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: fn, returnByValue: true });
   if (value.length)
-    await sendInput2("Input.insertText", { text: value });
+    await sendInput("Input.insertText", { text: value });
 }
 var NAMED_KEYS = {
   enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
@@ -1524,6 +1561,7 @@ var CDP_CAPABILITIES = new Set([
   "capture.screencast",
   "input.raw",
   "input.html5Drag",
+  "emulate.focus",
   "browser.downloads",
   "browser.permissions",
   "worker.targets"
@@ -2287,7 +2325,13 @@ function createCdpDriver() {
   return new CdpBrowserDriver;
 }
 
+// src/leases-tools.ts
+init_activity();
+init_origins();
+
 // src/reap.ts
+init_leases();
+init_origins();
 function staleAgentTabs(input) {
   const live = new Set(input.livePageIds);
   const out = [];
@@ -2334,6 +2378,7 @@ async function reapStaleAgentTabs(driver, backend) {
 }
 
 // src/shared-tools.ts
+init_driver();
 import { mkdir as mkdir5, writeFile as writeFile4 } from "node:fs/promises";
 import { dirname as dirname2, join as join4 } from "node:path";
 
@@ -2850,6 +2895,10 @@ async function stitchInto(fh, bands) {
 }
 
 // src/shared-tools.ts
+init_leases();
+init_activity();
+init_origins();
+init_workers();
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -3581,6 +3630,8 @@ var SHARED_TOOLS = {
 };
 
 // src/leases-tools.ts
+init_leases();
+
 class LeaseToolError extends Error {
 }
 function backendOf2(driver) {
@@ -3696,10 +3747,13 @@ var LEASE_TOOLS = {
 };
 
 // src/tools/console.ts
+init_client();
 import { readFile as readFile4 } from "node:fs/promises";
 
 // src/tools/recorder.ts
+init_client();
 import { mkdir as mkdir6, appendFile, writeFile as writeFile5, copyFile } from "node:fs/promises";
+init_workers();
 function artifactDir() {
   return process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 }
@@ -3926,11 +3980,11 @@ async function listConsoleMessages(args = {}) {
   if (args.reload) {
     const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS, { wake: args.wake });
     await cap.stop();
-    const messages2 = await readConsoleEntries(cap.file);
+    const messages = await readConsoleEntries(cap.file);
     return {
       target: cap.resolved,
-      count: messages2.length,
-      messages: messages2,
+      count: messages.length,
+      messages,
       droppedWrites: cap.droppedWrites()
     };
   }
@@ -3954,6 +4008,7 @@ async function getConsoleMessage(args = {}) {
 }
 
 // src/tools/network.ts
+init_client();
 import { readFile as readFile5 } from "node:fs/promises";
 var DEFAULT_CAPTURE_MS2 = 2500;
 function asHeaders(v) {
@@ -4075,15 +4130,15 @@ async function getNetworkRequest(args = {}) {
     const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2, { wake: args.wake });
     try {
       await cap.flush();
-      const match2 = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
-      if (!match2) {
+      const match = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
+      if (!match) {
         throw new CdpError(`no network request matched ${describeSelector()} in fresh capture`);
       }
       try {
-        const { body, base64Encoded } = await cap.conn.send("Network.getResponseBody", { requestId: match2.requestId });
-        return { ...match2, body, bodyBase64Encoded: base64Encoded };
+        const { body, base64Encoded } = await cap.conn.send("Network.getResponseBody", { requestId: match.requestId });
+        return { ...match, body, bodyBase64Encoded: base64Encoded };
       } catch {
-        return { ...match2, body: undefined, bodyBase64Encoded: undefined };
+        return { ...match, body: undefined, bodyBase64Encoded: undefined };
       }
     } finally {
       await cap.stop();
@@ -4105,6 +4160,7 @@ async function getNetworkRequest(args = {}) {
 }
 
 // src/tools/performance.ts
+init_client();
 import { mkdir as mkdir7, readFile as readFile6, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
 import { join as join5 } from "node:path";
 var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -4337,6 +4393,7 @@ async function performanceAnalyzeInsight(args = {}) {
 }
 
 // src/tools/screencast.ts
+init_client();
 import { spawn } from "node:child_process";
 import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join6 } from "node:path";
@@ -4701,6 +4758,7 @@ ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
 }
 
 // src/tools/heap.ts
+init_client();
 import { mkdir as mkdir9, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join7 } from "node:path";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -4741,6 +4799,7 @@ async function takeHeapsnapshot(args = {}) {
 }
 
 // src/tools/lighthouse.ts
+init_client();
 import { spawn as spawn2 } from "node:child_process";
 import { mkdir as mkdir10, readFile as readFile7, stat as stat3 } from "node:fs/promises";
 var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -4876,7 +4935,12 @@ function truncate(s, max = 600) {
   return t.length > max ? `${t.slice(0, max)}…` : t;
 }
 
+// src/index.ts
+init_network_mock();
+
 // src/tools/dispatch-mouse.ts
+init_activity();
+init_client();
 var CLICK_MODIFIER_BITS2 = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
 var BUTTONS = new Set(["left", "right", "middle"]);
 var CDP_EVENT_TYPE = {
@@ -4918,11 +4982,106 @@ 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";
 import { basename, extname, join as join9 } from "node:path";
 
 // src/tools/browser-session.ts
+init_client();
 import { mkdir as mkdir11 } from "node:fs/promises";
 import { join as join8 } from "node:path";
 var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -5095,6 +5254,7 @@ async function waitForDownload(args = {}) {
 }
 
 // src/tools/permissions.ts
+init_client();
 function originOf(url) {
   try {
     const o = new URL(url).origin;
@@ -5144,6 +5304,7 @@ async function grantPermissions(args = {}) {
 }
 
 // src/index.ts
+init_client();
 var cdpDriver = createCdpDriver();
 function onCdp(fn) {
   return (args) => fn(cdpDriver, args);
@@ -5189,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),