cdp-toolkit 1.7.0 → 1.9.0

package/dist/cli.js

@@ -278,6 +278,169 @@ async function listLeases(opts = {}) {
   return out;
 }
 
+// src/origins.ts
+import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
+import { join as join2 } from "node:path";
+function safeId2(id) {
+  return id.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+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,
+    targetId,
+    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
+    pid: process.pid,
+    createdAt: opts.now ?? Date.now()
+  };
+  const file = originFile(backend, targetId);
+  try {
+    await mkdir2(leaseDir(), { recursive: true });
+    try {
+      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+      return;
+    } catch (err) {
+      if (err.code !== "EEXIST")
+        throw err;
+    }
+    await unlink2(file).catch(() => {
+      return;
+    });
+    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
+  } catch {}
+}
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
+async function listOrigins(opts = {}) {
+  let names = [];
+  try {
+    names = await readdir2(leaseDir());
+  } catch {
+    return [];
+  }
+  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
+  const out = [];
+  for (const name of names) {
+    const parts = ORIGIN_FILE_RE.exec(name);
+    if (!parts)
+      continue;
+    const backend = parts[1];
+    const nameId = parts[2];
+    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
+    if (scoped && !live.has(nameId)) {
+      await unlink2(join2(leaseDir(), name)).catch(() => {
+        return;
+      });
+      continue;
+    }
+    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
+    let rec;
+    try {
+      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT")
+        continue;
+      out.push({ ...fromName, unreadable: code ?? "unparseable" });
+      continue;
+    }
+    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
+      out.push({ ...fromName, unreadable: "unparseable" });
+      continue;
+    }
+    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
+  }
+  return out;
+}
+async function originIndex(backend, liveIds) {
+  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
+  const index = new Map;
+  for (const row of rows) {
+    if (row.backend !== backend)
+      continue;
+    index.set(row.targetId, row);
+  }
+  return index;
+}
+async function newTrackedPage(driver, backend, opts = {}) {
+  const page = await driver.newPage(opts.url);
+  await recordOrigin(backend, page.id, { label: opts.label });
+  return page;
+}
+async function resolveLiveLabel(backend, label, liveIds) {
+  const live = new Set(liveIds);
+  const [origins, leases] = await Promise.all([originIndex(backend), listLeases({ liveBackend: backend })]);
+  const knownLabels = new Set;
+  const matchIds = new Set;
+  for (const rec of origins.values()) {
+    if (rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  for (const rec of leases) {
+    if (rec.backend !== backend || rec.unreadable !== undefined || !live.has(rec.targetId))
+      continue;
+    knownLabels.add(rec.label);
+    if (rec.label === label)
+      matchIds.add(rec.targetId);
+  }
+  return { matchIds: [...matchIds], knownLabels: [...knownLabels].sort() };
+}
+
+// src/workers.ts
+var WORKER_SELECTOR_PREFIX = "worker:";
+var WORKER_TARGET_TYPES = new Set(["service_worker", "shared_worker"]);
+function isWorkerSelector(selector) {
+  return typeof selector === "string" && selector.startsWith(WORKER_SELECTOR_PREFIX);
+}
+function workerNeedle(selector) {
+  return selector.slice(WORKER_SELECTOR_PREFIX.length);
+}
+function isWorkerTargetType(type) {
+  return type !== undefined && WORKER_TARGET_TYPES.has(type);
+}
+function resolveWorkerTargets(targets, needle) {
+  const liveWorkers = targets.filter((t) => isWorkerTargetType(t.type));
+  return {
+    matches: needle === "" ? [] : liveWorkers.filter((t) => t.url.includes(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 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). evaluate_script is the one tool that " + "accepts a worker: target.";
+function urlList(workers) {
+  return workers.map((w) => w.url).join(", ");
+}
+function workerAmbiguityMessage(needle, matches) {
+  return `'worker:${needle}' matches more than one running worker: ` + matches.map((m) => `${m.url} (${m.id})`).join(", ") + ". Narrow the substring, or pass the worker's target id directly.";
+}
+function workerMissMessage(needle, opts) {
+  const running = opts.liveWorkers?.length ? ` (running workers: ${urlList(opts.liveWorkers)})` : " (no workers are running)";
+  if (!opts.wakeAttempted) {
+    return `no running worker whose url contains '${needle}'${running}. ` + "An MV3 extension service worker is idle-evicted after seconds of inactivity and then appears in NO target " + "listing, so this is usually a sleeping worker rather than a wrong substring. You passed wake:false; " + "wake:true (the default) asks Chrome to start it first.";
+  }
+  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.";
+}
+
 // 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);
@@ -433,11 +596,13 @@ async function browserWsUrl() {
 }
 async function resolveTarget(selector, opts = {}) {
   const targets = await listTargets();
-  const hit = pickTarget(targets, selector);
+  const hit = await pickTarget(targets, selector);
+  if (isWorkerTargetType(hit.type))
+    return hit;
   await assertLeaseOk("chrome", hit.id, { lease: opts.lease, url: hit.url, title: hit.title });
   return hit;
 }
-function pickTarget(targets, selector) {
+async function pickTarget(targets, selector) {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length)
@@ -464,6 +629,30 @@ function pickTarget(targets, selector) {
       throw new CdpError(`no page title containing '${needle}'`);
     return hit;
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("chrome", label, pages.map((t) => t.id));
+    if (matchIds.length > 1) {
+      throw new CdpError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = pages.find((t) => t.id === matchIds[0]);
+      if (hit)
+        return hit;
+    }
+    throw new CdpError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+  }
+  if (isWorkerSelector(selector)) {
+    const needle = workerNeedle(selector);
+    if (needle === "")
+      throw new CdpError(WORKER_EMPTY_NEEDLE_MESSAGE);
+    const { matches, liveWorkers } = resolveWorkerTargets(targets, needle);
+    if (matches.length > 1)
+      throw new CdpError(workerAmbiguityMessage(needle, matches));
+    if (matches.length === 1)
+      return matches[0];
+    throw new CdpError(workerMissMessage(needle, { wakeAttempted: false, liveWorkers }));
+  }
   const byId = targets.find((t) => t.id === selector);
   if (!byId)
     throw new CdpError(`no target with id '${selector}'`);
@@ -486,6 +675,141 @@ async function withPage(selector, fn, opts = {}) {
   }
 }
 
+// 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);
+  dispatchLog.set(key, now);
+  while (dispatchLog.size > DISPATCH_LOG_LIMIT) {
+    const oldest = dispatchLog.keys().next();
+    if (oldest.done)
+      break;
+    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);
+  return conn.send(method, params);
+}
+function lastDispatchAt(backend, targetId) {
+  return dispatchLog.get(dispatchKey(backend, targetId));
+}
+function isHumanAttributed(beaconTs, dispatchAt, windowMs = DISPATCH_ATTRIBUTION_WINDOW_MS) {
+  if (typeof beaconTs !== "number" || !Number.isFinite(beaconTs))
+    return false;
+  return beaconTs > (dispatchAt ?? 0) + windowMs;
+}
+function humanActiveMs(beaconTs, dispatchAt, now = Date.now(), windowMs = DISPATCH_ATTRIBUTION_WINDOW_MS) {
+  if (!isHumanAttributed(beaconTs, dispatchAt, windowMs))
+    return null;
+  return Math.max(0, now - beaconTs);
+}
+var CONTENTION_WINDOW_MS = 30000;
+function contentionWarning(ms, opts) {
+  if (!opts.takeover)
+    return;
+  if (ms === null || ms >= CONTENTION_WINDOW_MS)
+    return;
+  return `a person appears to be using this tab right now: input not dispatched by this server landed ${ms}ms ago. ` + `The claim SUCCEEDED and you hold the lease — this is a warning, not a refusal. ` + `Driving the tab now will fight them for the keyboard and mouse. ` + `Consider claim_page with no target to work in your own tab instead, or ask before continuing.`;
+}
+function beaconSupported(driver) {
+  return typeof driver.installActivityBeacon === "function" && typeof driver.readActivityBeacon === "function";
+}
+async function installBeacon(driver, targetId) {
+  if (typeof driver.installActivityBeacon !== "function")
+    return false;
+  return driver.installActivityBeacon(targetId).catch(() => false);
+}
+async function readHumanActiveMs(driver, backend, targetId, now = Date.now()) {
+  if (typeof driver.readActivityBeacon !== "function")
+    return null;
+  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";
+}
+async function probeRendererActivity(driver, backend, targetId, now = Date.now()) {
+  if (typeof driver.probeRenderer !== "function")
+    return { responsive: false };
+  const { responsive, beaconTs } = await driver.probeRenderer(targetId, RENDERER_PROBE_TIMEOUT_MS).catch(() => ({ responsive: false, beaconTs: null }));
+  const ms = humanActiveMs(beaconTs, lastDispatchAt(backend, targetId), now);
+  return ms === null ? { responsive } : { responsive, humanActiveMs: ms };
+}
+
+class BeaconSessions {
+  close;
+  limit;
+  live = new Map;
+  constructor(close, limit = 32) {
+    this.close = close;
+    this.limit = limit;
+  }
+  get(key) {
+    return this.live.get(key);
+  }
+  set(key, value) {
+    const previous = this.live.get(key);
+    if (previous !== undefined) {
+      this.live.delete(key);
+      this.safeClose(previous);
+    }
+    this.live.set(key, value);
+    while (this.live.size > this.limit) {
+      const oldest = this.live.keys().next();
+      if (oldest.done)
+        break;
+      this.drop(oldest.value);
+    }
+  }
+  drop(key) {
+    const value = this.live.get(key);
+    if (value === undefined)
+      return;
+    this.live.delete(key);
+    this.safeClose(value);
+  }
+  clear() {
+    for (const key of [...this.live.keys()])
+      this.drop(key);
+  }
+  get size() {
+    return this.live.size;
+  }
+  safeClose(value) {
+    try {
+      this.close(value);
+    } catch {}
+  }
+}
+
 // src/tools/snapshot.ts
 var INTERACTIVE_ROLES = new Set([
   "button",
@@ -518,6 +842,91 @@ async function resolveUid(conn, 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];
+    }
+  }
+  const final = resolveWorkerTargets(await listTargets(), needle);
+  throw new CdpError(workerMissMessage(needle, { wakeAttempted: true, liveWorkers: final.liveWorkers, registeredScopes: scopes }));
+}
+
 // src/tools/network_mock.ts
 function escapeRegExpChar(ch) {
   return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
@@ -709,11 +1118,22 @@ var REQUIRED_CAPABILITIES = {
   stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
-  clear_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";
 }
+function interpolatePoints(from, to, steps) {
+  const out = [];
+  for (let i = 1;i < steps; i++) {
+    out.push({ x: from.x + (to.x - from.x) * i / steps, y: from.y + (to.y - from.y) * i / steps });
+  }
+  out.push({ x: to.x, y: to.y });
+  return out;
+}
 
 // src/cdp/driver.ts
 function driverError(code, message, data) {
@@ -769,12 +1189,21 @@ async function centerOf(conn, objectId) {
 async function focusElement(conn, objectId) {
   await conn.send("Runtime.callFunctionOn", { objectId, functionDeclaration: "function(){this.focus&&this.focus();}", returnByValue: true });
 }
-async function setValueOnObject(conn, objectId, value) {
+var ARM_SCROLL_SETTLE_WATCH = "(function(){window.__cdpScrollSettle=new Promise((resolve)=>{let t;const done=()=>{window.removeEventListener('scroll',on,true);resolve(true);};" + "const on=()=>{clearTimeout(t);t=setTimeout(done,60);};window.addEventListener('scroll',on,true);t=setTimeout(done,60);setTimeout(done,500);});})()";
+async function armScrollSettleWatch(conn) {
+  await conn.send("Runtime.evaluate", { expression: ARM_SCROLL_SETTLE_WATCH, returnByValue: true });
+}
+async function awaitScrollSettle(conn) {
+  await conn.send("Runtime.evaluate", { expression: "window.__cdpScrollSettle", awaitPromise: true, returnByValue: true }).catch(() => {
+    return;
+  });
+}
+async function setValueOnObject(conn, objectId, value, sendInput2) {
   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 conn.send("Input.insertText", { text: value });
+    await sendInput2("Input.insertText", { text: value });
 }
 var NAMED_KEYS = {
   enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
@@ -799,6 +1228,18 @@ var NAMED_KEYS = {
   pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 }
 };
 var MODIFIER_BITS = { alt: 1, control: 2, ctrl: 2, meta: 4, cmd: 4, command: 4, shift: 8 };
+var CLICK_MODIFIER_BITS = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+function inputModifierBits(mods) {
+  let bits = 0;
+  for (const m of mods ?? []) {
+    const bit = CLICK_MODIFIER_BITS[m];
+    if (bit === undefined)
+      throw driverError("page-error", `unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
+    bits |= bit;
+  }
+  return bits;
+}
+var HTML5_DRAG_INTERCEPT_TIMEOUT_MS = 5000;
 function resolveKey(key) {
   const named = NAMED_KEYS[key.toLowerCase()];
   if (named)
@@ -963,7 +1404,12 @@ var CDP_CAPABILITIES = new Set([
   "input.insertTextAtomic",
   "locate.text",
   "locate.xpath",
-  "capture.screencast"
+  "capture.screencast",
+  "input.raw",
+  "input.html5Drag",
+  "browser.downloads",
+  "browser.permissions",
+  "worker.targets"
 ]);
 
 class CdpPageDriver {
@@ -983,6 +1429,9 @@ class CdpPageDriver {
     this.enabledDomains.add(name);
     await this.conn.send(`${name}.enable`);
   }
+  async dispatchInput(method, params = {}) {
+    return sendInput(this.conn, "chrome", this.info.id, method, params);
+  }
   async ensureDomainSoft(name) {
     if (this.enabledDomains.has(name))
       return;
@@ -991,11 +1440,22 @@ class CdpPageDriver {
       return;
     });
   }
+  async historyEntry(direction) {
+    const h = await this.conn.send("Page.getNavigationHistory");
+    const entries = h.entries ?? [];
+    const entry = entries[h.currentIndex + (direction === "back" ? -1 : 1)];
+    if (!entry) {
+      throw driverError("page-error", `navigate: no history entry to go ${direction} to (at entry ${h.currentIndex + 1} of ${entries.length})`);
+    }
+    return entry;
+  }
   async navigate(opts) {
     await this.ensureDomain("Page");
     const reload = opts.reload === true;
-    if (!reload && !opts.url)
+    const history = opts.history;
+    if (!reload && !history && !opts.url)
       throw driverError("page-error", "navigate: 'url' is required unless reload:true");
+    const entry = history ? await this.historyEntry(history) : undefined;
     const waitUntil = opts.waitUntil ?? "load";
     const milestoneMethod = waitUntil === "load" ? "Page.loadEventFired" : "Page.domContentEventFired";
     const milestone = this.conn.waitFor(milestoneMethod, undefined, opts.timeoutMs).then(() => waitUntil).catch(() => {
@@ -1013,6 +1473,10 @@ class CdpPageDriver {
       contextId = tree?.frameTree?.frame?.id ?? "";
       url = tree?.frameTree?.frame?.url ?? opts.url ?? "";
       reloaded = true;
+    } else if (entry) {
+      await this.conn.send("Page.navigateToHistoryEntry", { entryId: entry.id }, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {});
+      contextId = "";
+      url = entry.url;
     } else {
       const nav = await this.conn.send("Page.navigate", { url: opts.url }, opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {});
       if (nav.errorText)
@@ -1021,7 +1485,20 @@ class CdpPageDriver {
       url = opts.url;
     }
     const settled = await Promise.race([milestone, stopped]);
-    return { url, contextId, ...reloaded ? { reloaded } : {}, waitedFor: settled ?? "timeout" };
+    if (entry) {
+      const tree = await this.conn.send("Page.getFrameTree").catch(() => {
+        return;
+      });
+      contextId = tree?.frameTree?.frame?.id ?? contextId;
+      url = tree?.frameTree?.frame?.url ?? url;
+    }
+    return {
+      url,
+      contextId,
+      ...reloaded ? { reloaded } : {},
+      ...history ? { traversed: history } : {},
+      waitedFor: settled ?? "timeout"
+    };
   }
   async waitForText(text, timeoutMs = 15000, pollMs = 250) {
     await this.ensureDomain("Runtime");
@@ -1101,36 +1578,96 @@ class CdpPageDriver {
   async hover(loc) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     const { x, y } = await centerOf(this.conn, objectId);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
     return { x, y };
   }
   async click(loc, opts) {
     const button = opts?.button ?? "left";
     const clickCount = opts?.clickCount ?? 1;
+    const modifiers = inputModifierBits(opts?.modifiers);
     const { x, y } = await this.hover(loc);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount, modifiers });
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount, modifiers });
     return { x, y };
   }
-  async drag(from, to) {
+  async scroll(anchor, opts) {
+    await this.ensureDomain("Runtime");
+    const { x, y } = await this.resolveScrollPoint(anchor);
+    await armScrollSettleWatch(this.conn);
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseWheel", x, y, deltaX: opts.deltaX ?? 0, deltaY: opts.deltaY ?? 0 });
+    await awaitScrollSettle(this.conn);
+    return { x, y };
+  }
+  async resolveScrollPoint(anchor) {
+    if (anchor === undefined) {
+      await this.ensureDomain("Runtime");
+      const { result, exceptionDetails } = await this.conn.send("Runtime.evaluate", { expression: "({x: window.innerWidth / 2, y: window.innerHeight / 2})", returnByValue: true });
+      if (exceptionDetails || !result.value)
+        throw driverError("page-error", `could not measure viewport for scroll center: ${exceptionDetails?.text ?? "no value"}`);
+      return result.value;
+    }
+    if ("x" in anchor)
+      return anchor;
+    const { objectId } = await resolveElementLocator(this.conn, anchor);
+    return centerOf(this.conn, objectId);
+  }
+  async drag(from, to, opts) {
     const fromPt = await this.hover(from);
-    const { objectId: dstId } = await resolveElementLocator(this.conn, to);
-    const toPt = await centerOf(this.conn, dstId);
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: (fromPt.x + toPt.x) / 2, y: (fromPt.y + toPt.y) / 2, button: "left" });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: toPt.x, y: toPt.y, button: "left" });
-    await this.conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
+    const toPt = await this.resolveDragDestination(to, fromPt);
+    const steps = Math.max(1, Math.trunc(opts?.steps ?? 2));
+    if ((opts?.mode ?? "mouse") === "html5") {
+      await this.html5Drag(fromPt, toPt, steps);
+      return { from: fromPt, to: toPt };
+    }
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
+    for (const pt of interpolatePoints(fromPt, toPt, steps)) {
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x: pt.x, y: pt.y, button: "left" });
+    }
+    await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
     return { from: fromPt, to: toPt };
   }
+  async resolveDragDestination(to, fromPt) {
+    if ("dx" in to)
+      return { x: fromPt.x + to.dx, y: fromPt.y + to.dy };
+    if ("x" in to)
+      return to;
+    const { objectId } = await resolveElementLocator(this.conn, to);
+    return centerOf(this.conn, objectId);
+  }
+  async html5Drag(fromPt, toPt, steps) {
+    await this.dispatchInput("Input.setInterceptDrags", { enabled: true });
+    try {
+      const intercepted = this.conn.waitFor("Input.dragIntercepted", undefined, HTML5_DRAG_INTERCEPT_TIMEOUT_MS).catch(() => {
+        return;
+      });
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mousePressed", x: fromPt.x, y: fromPt.y, button: "left", clickCount: 1 });
+      for (const pt of interpolatePoints(fromPt, toPt, steps)) {
+        await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseMoved", x: pt.x, y: pt.y, button: "left" });
+      }
+      const event = await intercepted;
+      if (!event?.data) {
+        throw driverError("page-error", `drag mode:"html5": the page never started a drag (no Input.dragIntercepted within ${HTML5_DRAG_INTERCEPT_TIMEOUT_MS}ms). ` + 'The source element is probably not draggable — HTML5 drag-and-drop needs draggable="true" (or a native draggable element) ' + 'plus a dragstart handler. Use the default mode:"mouse" for widgets built on raw pointer events.');
+      }
+      const data = event.data;
+      for (const type of ["dragEnter", "dragOver", "drop"]) {
+        await this.dispatchInput("Input.dispatchDragEvent", { type, x: toPt.x, y: toPt.y, data });
+      }
+      await this.dispatchInput("Input.dispatchMouseEvent", { type: "mouseReleased", x: toPt.x, y: toPt.y, button: "left", clickCount: 1 });
+    } finally {
+      await this.dispatchInput("Input.setInterceptDrags", { enabled: false }).catch(() => {
+        return;
+      });
+    }
+  }
   async setValue(loc, value) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
-    await setValueOnObject(this.conn, objectId, value);
+    await setValueOnObject(this.conn, objectId, value, (method, params) => this.dispatchInput(method, params));
   }
   async typeText(loc, text) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     await focusElement(this.conn, objectId);
     if (text.length)
-      await this.conn.send("Input.insertText", { text });
+      await this.dispatchInput("Input.insertText", { text });
   }
   async pressKey(press) {
     const spec = resolveKey(press.key);
@@ -1145,8 +1682,8 @@ class CdpPageDriver {
     const down = { type: "keyDown", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits };
     if (spec.text && !suppressText)
       down.text = spec.text;
-    await this.conn.send("Input.dispatchKeyEvent", down);
-    await this.conn.send("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
+    await this.dispatchInput("Input.dispatchKeyEvent", down);
+    await this.dispatchInput("Input.dispatchKeyEvent", { type: "keyUp", key: spec.key, code: spec.code, windowsVirtualKeyCode: spec.keyCode, nativeVirtualKeyCode: spec.keyCode, modifiers: modBits });
   }
   async setFiles(loc, files) {
     const { objectId } = await resolveElementLocator(this.conn, loc);
@@ -1362,6 +1899,36 @@ class CdpPageDriver {
     this.conn.close();
   }
 }
+var beaconSessions = new BeaconSessions((conn) => conn.close());
+async function targetWsUrl(targetId) {
+  const hit = (await listTargets()).find((t) => t.id === targetId);
+  return hit?.webSocketDebuggerUrl;
+}
+async function readBeaconOver(conn) {
+  try {
+    const res = await conn.send("Runtime.evaluate", {
+      expression: BEACON_READ_EXPRESSION,
+      returnByValue: true
+    });
+    const value = res.result?.value;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+  } catch {
+    return;
+  }
+}
+async function probeOver(conn, timeoutMs) {
+  try {
+    const res = await conn.send("Runtime.evaluate", { expression: RENDERER_PROBE_EXPRESSION, returnByValue: true }, { timeoutMs });
+    const value = res.result?.value;
+    if (Array.isArray(value) && value[0] === 1) {
+      const ts = value[1];
+      return { responsive: true, beaconTs: typeof ts === "number" && Number.isFinite(ts) ? ts : null };
+    }
+    return { responsive: false, beaconTs: null };
+  } catch {
+    return { responsive: false, beaconTs: null };
+  }
+}
 async function withBrowserConn(fn) {
   const conn = await openBrowser();
   try {
@@ -1400,6 +1967,8 @@ class CdpBrowserDriver {
   async closePage(id) {
     return withBrowserConn(async (conn) => {
       const res = await conn.send("Target.closeTarget", { targetId: id });
+      if (res.success !== false)
+        beaconSessions.drop(id);
       return { success: res.success ?? true };
     });
   }
@@ -1408,119 +1977,94 @@ class CdpBrowserDriver {
     await withBrowserConn((conn) => conn.send("Target.activateTarget", { targetId: target.id }));
     return { id: target.id, url: target.url, title: target.title };
   }
+  async resolveWorkerTarget(selector, opts) {
+    const target = await resolveWorkerSelector(selector, opts).catch(noSuchTarget);
+    return { id: target.id, url: target.url, title: target.title, type: target.type };
+  }
   async page(selector) {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     return new CdpPageDriver(conn, target, this);
   }
-  async dispose() {}
-}
-function createCdpDriver() {
-  return new CdpBrowserDriver;
-}
-
-// src/origins.ts
-import { mkdir as mkdir2, readFile as readFile2, readdir as readdir2, unlink as unlink2, writeFile as writeFile2 } from "node:fs/promises";
-import { join as join2 } from "node:path";
-function safeId2(id) {
-  return id.replace(/[^A-Za-z0-9._-]/g, "_");
-}
-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,
-    targetId,
-    label: typeof opts.label === "string" && opts.label.length ? opts.label : defaultLabel(),
-    pid: process.pid,
-    createdAt: opts.now ?? Date.now()
-  };
-  const file = originFile(backend, targetId);
-  try {
-    await mkdir2(leaseDir(), { recursive: true });
-    try {
-      await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-      return;
-    } catch (err) {
-      if (err.code !== "EEXIST")
-        throw err;
+  async installActivityBeacon(targetId) {
+    const held = beaconSessions.get(targetId);
+    if (held) {
+      const rearmed = await held.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true }).then(() => true).catch(() => false);
+      if (rearmed)
+        return true;
+      beaconSessions.drop(targetId);
     }
-    await unlink2(file).catch(() => {
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
       return;
     });
-    await writeFile2(file, JSON.stringify(record), { flag: "wx" });
-  } catch {}
-}
-async function readOrigin(backend, targetId) {
-  let raw;
-  try {
-    raw = await readFile2(originFile(backend, targetId), "utf8");
-  } catch {
-    return;
-  }
-  try {
-    const rec = JSON.parse(raw);
-    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
-      return rec;
-  } catch {}
-  return;
-}
-async function listOrigins(opts = {}) {
-  let names = [];
-  try {
-    names = await readdir2(leaseDir());
-  } catch {
-    return [];
+    if (!wsUrl)
+      return false;
+    const conn = await new CdpConnection(wsUrl).connect().catch(() => {
+      return;
+    });
+    if (!conn)
+      return false;
+    try {
+      await conn.send("Page.enable");
+      await conn.send("Page.addScriptToEvaluateOnNewDocument", { source: BEACON_SOURCE });
+      await conn.send("Runtime.evaluate", { expression: BEACON_SOURCE, returnByValue: true });
+    } catch {
+      conn.close();
+      return false;
+    }
+    beaconSessions.set(targetId, conn);
+    return true;
   }
-  const live = opts.liveIds === undefined ? undefined : new Set(opts.liveIds.map((id) => safeId2(id)));
-  const out = [];
-  for (const name of names) {
-    const parts = ORIGIN_FILE_RE.exec(name);
-    if (!parts)
-      continue;
-    const backend = parts[1];
-    const nameId = parts[2];
-    const scoped = live !== undefined && (opts.liveBackend === undefined || opts.liveBackend === backend);
-    if (scoped && !live.has(nameId)) {
-      await unlink2(join2(leaseDir(), name)).catch(() => {
-        return;
-      });
-      continue;
+  async readActivityBeacon(targetId) {
+    const held = beaconSessions.get(targetId);
+    if (held) {
+      const value = await readBeaconOver(held);
+      if (value !== undefined)
+        return value;
+      beaconSessions.drop(targetId);
     }
-    const fromName = { backend, targetId: nameId, label: "", pid: 0, createdAt: 0 };
-    let rec;
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
+      return;
+    });
+    if (!wsUrl)
+      return null;
+    const conn = await new CdpConnection(wsUrl).connect().catch(() => {
+      return;
+    });
+    if (!conn)
+      return null;
     try {
-      rec = JSON.parse(await readFile2(join2(leaseDir(), name), "utf8"));
-    } catch (err) {
-      const code = err.code;
-      if (code === "ENOENT")
-        continue;
-      out.push({ ...fromName, unreadable: code ?? "unparseable" });
-      continue;
+      return await readBeaconOver(conn) ?? null;
+    } finally {
+      conn.close();
     }
-    if (typeof rec?.targetId !== "string" || typeof rec?.label !== "string" || typeof rec?.createdAt !== "number") {
-      out.push({ ...fromName, unreadable: "unparseable" });
-      continue;
+  }
+  async probeRenderer(targetId, timeoutMs = RENDERER_PROBE_TIMEOUT_MS) {
+    const held = beaconSessions.get(targetId);
+    if (held)
+      return probeOver(held, timeoutMs);
+    const wsUrl = await targetWsUrl(targetId).catch(() => {
+      return;
+    });
+    if (!wsUrl)
+      return { responsive: false, beaconTs: null };
+    const conn = new CdpConnection(wsUrl, { timeoutMs });
+    try {
+      await conn.connect();
+    } catch {
+      return { responsive: false, beaconTs: null };
+    }
+    try {
+      return await probeOver(conn, timeoutMs);
+    } finally {
+      conn.close();
     }
-    out.push({ backend: rec.backend, targetId: rec.targetId, label: rec.label, pid: rec.pid, createdAt: rec.createdAt });
   }
-  return out;
-}
-async function originIndex(backend, liveIds) {
-  const rows = await listOrigins({ liveIds, liveBackend: backend }).catch(() => []);
-  const index = new Map;
-  for (const row of rows) {
-    if (row.backend !== backend)
-      continue;
-    index.set(row.targetId, row);
+  async dispose() {
+    beaconSessions.clear();
   }
-  return index;
 }
-async function newTrackedPage(driver, backend, opts = {}) {
-  const page = await driver.newPage(opts.url);
-  await recordOrigin(backend, page.id, { label: opts.label });
-  return page;
+function createCdpDriver() {
+  return new CdpBrowserDriver;
 }
 
 // src/reap.ts
@@ -1534,6 +2078,8 @@ function staleAgentTabs(input) {
       continue;
     if (row.stale !== "dead-pid" && row.stale !== "expired")
       continue;
+    if (row.stale === "expired" && input.now - row.lastUsedAt <= row.ttlMs + input.reapGraceMs)
+      continue;
     if (!live.has(row.targetId))
       continue;
     const origin = input.origins.get(row.targetId);
@@ -1543,13 +2089,19 @@ function staleAgentTabs(input) {
   }
   return out;
 }
+var DEFAULT_REAP_GRACE_MS = 2700000;
+function reapGraceMs() {
+  const raw = Number(process.env.CDP_REAP_GRACE_MS);
+  return Number.isFinite(raw) && raw >= 0 ? raw : DEFAULT_REAP_GRACE_MS;
+}
 async function reapStaleAgentTabs(driver, backend) {
+  const now = Date.now();
   const livePageIds = (await driver.listPages()).map((p) => p.id);
   const [origins, leases] = await Promise.all([
     originIndex(backend, undefined),
-    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [])
+    listLeases({ now, liveIds: livePageIds, liveBackend: backend }).catch(() => [])
   ]);
-  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases, now, reapGraceMs: reapGraceMs() });
   const closed = [];
   for (const c of candidates) {
     const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
@@ -1615,6 +2167,11 @@ async function pickPage(driver, pages, selector) {
       throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:"))
+    return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    throw new SharedToolError(backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE);
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage)
     return exactPage;
@@ -1624,6 +2181,18 @@ async function pickPage(driver, pages, selector) {
     return exact;
   throw new SharedToolError(`no target with id '${selector}'`);
 }
+async function pickByLabel(driver, pages, label) {
+  const { matchIds, knownLabels } = await resolveLiveLabel(backendOf(driver), label, pages.map((x) => x.id));
+  if (matchIds.length > 1) {
+    throw new SharedToolError(`label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+  }
+  if (matchIds.length === 1) {
+    const p = pages.find((x) => x.id === matchIds[0]);
+    if (p)
+      return p;
+  }
+  throw new SharedToolError(knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+}
 function locatorOf(args) {
   const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== "";
   const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
@@ -1641,18 +2210,29 @@ async function reapSet(driver, pages, all) {
   }
 }
 async function listPages(driver, args = {}) {
-  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  const backend = backendOf(driver);
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
   const reapedIds = new Set(reaped.map((r) => r.targetId));
   const pages = (await driver.listPages({ all: args.all })).filter((p) => !reapedIds.has(p.id));
-  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
-  const annotated = pages.map((p) => {
+  const ledger = await originIndex(backend, await reapSet(driver, pages, args.all));
+  const now = Date.now();
+  const leaseByTarget = new Map((await listLeases({ now, liveIds: pages.map((p) => p.id), liveBackend: backend })).filter((l) => l.backend === backend && l.unreadable === undefined).map((l) => [l.targetId, l]));
+  const doProbe = args.probe === true && rendererProbeSupported(driver);
+  const annotated = await Promise.all(pages.map(async (p) => {
     const rec = ledger.get(p.id);
-    if (!rec)
-      return { ...p, origin: "unknown" };
-    if (rec.unreadable !== undefined)
-      return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
-    return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
-  });
+    const base = !rec ? { ...p, origin: "unknown" } : rec.unreadable !== undefined ? { ...p, origin: "unknown", originUnreadable: rec.unreadable } : { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
+    const leaseRow = leaseByTarget.get(p.id);
+    if (leaseRow) {
+      base.lease = { label: leaseRow.label, pid: leaseRow.pid, idleMs: now - leaseRow.lastUsedAt, expiresAt: leaseRow.lastUsedAt + leaseRow.ttlMs, stale: leaseRow.stale };
+    }
+    if (doProbe && (p.type === undefined || p.type === "page")) {
+      const probe = await probeRendererActivity(driver, backend, p.id, now);
+      base.responsive = probe.responsive;
+      if (probe.humanActiveMs !== undefined)
+        base.humanActiveMs = probe.humanActiveMs;
+    }
+    return base;
+  }));
   return { pages: annotated, count: annotated.length, ...reaped.length ? { reaped } : {} };
 }
 async function newPage(driver, args = {}) {
@@ -1666,6 +2246,7 @@ async function newPage(driver, args = {}) {
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
     auto: !explicit
   });
+  await installBeacon(driver, p.id);
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 async function closePage(driver, args) {
@@ -1697,17 +2278,36 @@ function toLegacyWaitedFor(w) {
     return "navigate-only";
   return w;
 }
-async function navigatePage(driver, args) {
+function resolveNavigateMode(args) {
   const reload = args.reload === true;
-  if (!reload && (!args.url || typeof args.url !== "string")) {
-    throw new SharedToolError("navigate_page: 'url' is required (or pass reload:true to reload the current page)");
+  const hasUrl = typeof args.url === "string" && args.url.length > 0;
+  const hasHistory = args.history !== undefined && args.history !== null;
+  const given = [hasUrl ? "url" : "", reload ? "reload" : "", hasHistory ? "history" : ""].filter(Boolean);
+  if (given.length > 1) {
+    throw new SharedToolError(`navigate_page: 'url', 'reload' and 'history' are mutually exclusive (got ${given.join(" + ")})`);
+  }
+  if (hasHistory) {
+    if (args.history !== "back" && args.history !== "forward") {
+      throw new SharedToolError(`navigate_page: 'history' must be 'back' or 'forward' (got ${JSON.stringify(args.history)})`);
+    }
+    return { mode: "history", history: args.history };
+  }
+  if (reload)
+    return { mode: "reload" };
+  if (!hasUrl) {
+    throw new SharedToolError("navigate_page: 'url' is required (or pass reload:true to reload the current page, or history:'back'|'forward' to go back/forward in this tab's session history)");
   }
+  return { mode: "url", url: args.url };
+}
+async function navigatePage(driver, args) {
+  const mode = resolveNavigateMode(args);
   return withPage2(driver, args.target, async (page) => {
-    const r = await page.navigate(args);
+    const r = await page.navigate(mode.mode === "history" ? { ...args, history: mode.history } : args);
     return {
       url: r.url,
       frameId: r.contextId,
       ...r.reloaded ? { reloaded: r.reloaded } : {},
+      ...r.traversed ? { traversed: r.traversed } : {},
       waitedFor: toLegacyWaitedFor(r.waitedFor)
     };
   });
@@ -1734,11 +2334,29 @@ async function writeJsonSink(savePath, value) {
 function sinkRequested(savePath) {
   return savePath !== undefined && savePath !== "";
 }
+var EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"];
+async function resolveWorkerSelectorFor(driver, selector, wake) {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
 async function evaluateScript(driver, args) {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => args[k] !== undefined);
+    if (wrongKey !== undefined) {
+      throw new SharedToolError(`evaluateScript: you passed '${wrongKey}'; the key is 'expression' — function literals go in 'expression', invoked with 'args'.`);
+    }
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage2(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  if (args.wake !== undefined && !isWorkerSelector(args.target)) {
+    throw new SharedToolError("evaluateScript: 'wake' only applies to a target of the form 'worker:<substring>'; a page target is never asleep.");
+  }
+  const target = isWorkerSelector(args.target) ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id : args.target;
+  return withPage2(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     if (!sinkRequested(args.savePath))
       return value;
@@ -1853,22 +2471,113 @@ async function takeSnapshot(driver, args = {}) {
 }
 async function click(driver, args) {
   return withPage2(driver, args.target, async (page) => {
-    const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1 });
+    const { x, y } = await page.click(locatorOf(args), { button: args.button ?? "left", clickCount: args.clickCount ?? 1, modifiers: args.modifiers });
     return { clicked: true, x, y };
   });
 }
+function resolveScrollAnchor(args) {
+  const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== "";
+  const hasSelector = typeof args.selector === "string" && args.selector.length > 0;
+  const hasX = args.x !== undefined;
+  const hasY = args.y !== undefined;
+  if (hasX !== hasY)
+    throw new SharedToolError("scroll: 'x' and 'y' must be provided together");
+  const hasXY = hasX && hasY;
+  const anchorCount = [hasUid, hasSelector, hasXY].filter(Boolean).length;
+  if (anchorCount > 1)
+    throw new SharedToolError("scroll: provide at most one of { uid }, { selector }, or { x, y } (omit all three to scroll at the viewport center)");
+  if (hasUid || hasSelector)
+    return locatorOf({ uid: args.uid, selector: args.selector });
+  if (hasXY)
+    return { x: args.x, y: args.y };
+  return;
+}
+function resolveScrollDelta(args) {
+  const deltaX = args.deltaX ?? 0;
+  const deltaY = args.deltaY ?? 0;
+  if (deltaX === 0 && deltaY === 0)
+    throw new SharedToolError("scroll requires at least one of { deltaX } or { deltaY }");
+  return { deltaX, deltaY };
+}
+async function scroll(driver, args) {
+  const anchor = resolveScrollAnchor(args);
+  const { deltaX, deltaY } = resolveScrollDelta(args);
+  return withPage2(driver, args.target, async (page) => {
+    const { x, y } = await page.scroll(anchor, { deltaX, deltaY });
+    return { x, y, deltaX, deltaY, target: target3(page.info) };
+  });
+}
 async function hover(driver, args) {
   return withPage2(driver, args.target, async (page) => {
     const { x, y } = await page.hover(locatorOf(args));
     return { hovered: true, x, y };
   });
 }
+function resolveDragTo(to) {
+  const hasUid = to.uid !== undefined && to.uid !== null && to.uid !== "";
+  const hasSelector = typeof to.selector === "string" && to.selector.length > 0;
+  const hasX = to.x !== undefined;
+  const hasY = to.y !== undefined;
+  if (hasX !== hasY)
+    throw new SharedToolError("drag: 'to.x' and 'to.y' must be provided together");
+  const hasXY = hasX && hasY;
+  const count = [hasUid, hasSelector, hasXY].filter(Boolean).length;
+  if (count !== 1)
+    throw new SharedToolError("drag: 'to' takes exactly one of { uid }, { selector }, or { x, y }");
+  if (hasXY) {
+    if (!Number.isFinite(to.x) || !Number.isFinite(to.y))
+      throw new SharedToolError("drag: 'to.x' and 'to.y' must be finite numbers");
+    return { x: to.x, y: to.y };
+  }
+  return locatorOf({ uid: to.uid, selector: to.selector });
+}
+function resolveDragDestination(args) {
+  const hasTo = args.to !== undefined && args.to !== null;
+  const hasBy = args.by !== undefined && args.by !== null;
+  if (hasTo === hasBy)
+    throw new SharedToolError("drag requires exactly one of { to } or { by }");
+  if (hasBy) {
+    const by = args.by;
+    const hasDx = by.dx !== undefined;
+    const hasDy = by.dy !== undefined;
+    if (!hasDx && !hasDy)
+      throw new SharedToolError("drag: 'by' requires at least one of { dx } or { dy }");
+    const dx = by.dx ?? 0;
+    const dy = by.dy ?? 0;
+    if (!Number.isFinite(dx) || !Number.isFinite(dy))
+      throw new SharedToolError("drag: 'by.dx' and 'by.dy' must be finite numbers");
+    return { dx, dy };
+  }
+  return resolveDragTo(args.to);
+}
+var MAX_DRAG_STEPS = 500;
+function resolveDragSteps(steps) {
+  if (steps === undefined)
+    return 2;
+  if (typeof steps !== "number" || !Number.isInteger(steps) || steps < 1 || steps > MAX_DRAG_STEPS) {
+    throw new SharedToolError(`drag: 'steps' must be an integer between 1 and ${MAX_DRAG_STEPS} (default 2)`);
+  }
+  return steps;
+}
+function resolveDragMode(mode, capabilities) {
+  if (mode === undefined || mode === "mouse")
+    return "mouse";
+  if (mode !== "html5")
+    throw new SharedToolError(`drag: unknown mode '${mode}' (use 'mouse' or 'html5')`);
+  if (!capabilities.has("input.html5Drag")) {
+    throw new SharedToolError("drag: mode:'html5' is not supported by this backend (WebDriver BiDi has no drag-interception primitive). " + "Omit 'mode' for the synthetic-mouse drag, or use --browser chrome for real HTML5 drag events.");
+  }
+  return "html5";
+}
 async function drag(driver, args) {
-  if (!args.from || !args.to)
-    throw new SharedToolError("drag requires { from } and { to }");
+  if (!args.from)
+    throw new SharedToolError("drag requires { from }");
+  const destination = resolveDragDestination(args);
+  const steps = resolveDragSteps(args.steps);
+  const mode = resolveDragMode(args.mode, driver.capabilities);
   return withPage2(driver, args.target, async (page) => {
-    const { from, to } = await page.drag(locatorOf(args.from), locatorOf(args.to));
-    return { dragged: true, from, to };
+    const { from, to } = await page.drag(locatorOf(args.from), destination, { mode, steps });
+    return { dragged: true, mode, steps, from, to };
   });
 }
 async function fill(driver, args) {
@@ -1989,6 +2698,7 @@ var SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,
@@ -2010,7 +2720,7 @@ async function claimPage(driver, args = {}) {
   const hasTarget = typeof args.target === "string" && args.target.length > 0;
   const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
   if (hasTarget && hasTargetId) {
-    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
   }
   const backend = backendOf2(driver);
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
@@ -2038,12 +2748,15 @@ async function claimPage(driver, args = {}) {
     url = page.url;
     opened = true;
   }
+  const humanMs = opened ? null : await readHumanActiveMs(driver, backend, targetId);
   const liveIds = [...pages.map((p) => p.id), targetId];
   const { record, token } = await claimLease(backend, targetId, {
     label,
     ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
     liveIds
   });
+  await installBeacon(driver, targetId);
+  const contention = contentionWarning(humanMs, { takeover: !opened });
   return {
     lease: token,
     targetId,
@@ -2051,7 +2764,9 @@ async function claimPage(driver, args = {}) {
     label: record.label,
     ttlMs: record.ttlMs,
     expiresAt: record.lastUsedAt + record.ttlMs,
-    opened
+    opened,
+    ...beaconSupported(driver) ? { humanActiveMs: humanMs } : {},
+    ...contention !== undefined ? { contention } : {}
   };
 }
 async function releasePage(driver, args = {}) {
@@ -2086,9 +2801,22 @@ async function listLeasesTool(driver, _args = {}) {
   const backend = backendOf2(driver);
   const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
   const reapedIds = new Set(reaped.map((r) => r.targetId));
-  const liveIds = (await driver.listPages()).map((p) => p.id);
+  const livePages = await driver.listPages();
+  const liveIds = livePages.map((p) => p.id);
   const all = await listLeases({ liveIds, liveBackend: backend });
-  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  const kept = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  const liveSet = new Set(liveIds);
+  const now = Date.now();
+  const leases = [];
+  for (const row of kept) {
+    const computed = row.unreadable !== undefined ? row : { ...row, idleMs: now - row.lastUsedAt, expiresAt: row.lastUsedAt + row.ttlMs };
+    if (row.backend !== backend || row.unreadable !== undefined || !liveSet.has(row.targetId)) {
+      leases.push(computed);
+      continue;
+    }
+    const humanMs = await readHumanActiveMs(driver, backend, row.targetId, now).catch(() => null);
+    leases.push(humanMs === null ? computed : { ...computed, humanActiveMs: humanMs });
+  }
   return { leases, count: leases.length, ...reaped.length ? { reaped } : {} };
 }
 var LEASE_TOOLS = {
@@ -3244,6 +3972,273 @@ function truncate(s, max = 600) {
   return t.length > max ? `${t.slice(0, max)}…` : t;
 }
 
+// src/tools/dispatch-mouse.ts
+var CLICK_MODIFIER_BITS2 = { Alt: 1, Control: 2, Meta: 4, Shift: 8 };
+var BUTTONS = new Set(["left", "right", "middle"]);
+var CDP_EVENT_TYPE = {
+  move: "mouseMoved",
+  down: "mousePressed",
+  up: "mouseReleased"
+};
+function modifierBits(mods) {
+  let bits = 0;
+  for (const m of mods ?? []) {
+    const bit = CLICK_MODIFIER_BITS2[m];
+    if (bit === undefined)
+      throw new Error(`dispatch_mouse: unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
+    bits |= bit;
+  }
+  return bits;
+}
+function validateDispatchMouseArgs(args) {
+  if (args.action !== "move" && args.action !== "down" && args.action !== "up") {
+    throw new Error("dispatch_mouse requires { action } of 'move', 'down', or 'up'");
+  }
+  if (typeof args.x !== "number" || typeof args.y !== "number" || !Number.isFinite(args.x) || !Number.isFinite(args.y)) {
+    throw new Error("dispatch_mouse requires numeric { x } and { y } on every call");
+  }
+  const button = args.button ?? "left";
+  if (!BUTTONS.has(button))
+    throw new Error(`dispatch_mouse: unknown button '${button}' (use left, right, or middle)`);
+}
+async function dispatchMouse(args) {
+  validateDispatchMouseArgs(args);
+  const button = args.button ?? "left";
+  const modifiers = modifierBits(args.modifiers);
+  return withPage(args.target, async (conn, target) => {
+    const params = { type: CDP_EVENT_TYPE[args.action], x: args.x, y: args.y, button, modifiers };
+    if (args.action !== "move")
+      params.clickCount = args.clickCount ?? 1;
+    await sendInput(conn, "chrome", target.id, "Input.dispatchMouseEvent", params);
+    return { dispatched: args.action, x: args.x, y: args.y };
+  });
+}
+
+// src/tools/downloads.ts
+import { readdir as readdir3, rename, stat as stat4 } from "node:fs/promises";
+import { basename, extname, join as join8 } from "node:path";
+
+// src/tools/browser-session.ts
+import { mkdir as mkdir9 } from "node:fs/promises";
+import { join as join7 } from "node:path";
+var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+var DOWNLOADS_DIR = join7(ARTIFACT_DIR7, "downloads");
+var DOWNLOAD_BUFFER_LIMIT = 50;
+var session;
+function isDisconnect(e) {
+  const m = e instanceof Error ? e.message : String(e);
+  return /connection (not open|closed)|closed by caller|websocket|ECONNREFUSED|socket/i.test(m);
+}
+function record(s, guid) {
+  let r = s.downloads.find((d) => d.guid === guid);
+  if (!r) {
+    r = { guid, state: "inProgress", consumed: false };
+    s.downloads.push(r);
+    while (s.downloads.length > DOWNLOAD_BUFFER_LIMIT) {
+      const i = s.downloads.findIndex((d) => d.consumed);
+      s.downloads.splice(i >= 0 ? i : 0, 1);
+    }
+  }
+  return r;
+}
+function subscribe(s) {
+  s.conn.on("Browser.downloadWillBegin", (p) => {
+    const r = record(s, String(p.guid));
+    if (typeof p.url === "string")
+      r.url = p.url;
+    if (typeof p.suggestedFilename === "string")
+      r.suggestedFilename = p.suggestedFilename;
+  });
+  s.conn.on("Browser.downloadProgress", (p) => {
+    const r = record(s, String(p.guid));
+    if (typeof p.receivedBytes === "number")
+      r.bytes = p.receivedBytes;
+    if (typeof p.filePath === "string")
+      r.filePath = p.filePath;
+    const state = String(p.state);
+    if (state === "completed" || state === "canceled") {
+      r.state = state;
+      if (state === "completed") {
+        const waiter = s.waiters.shift();
+        if (waiter) {
+          r.consumed = true;
+          waiter(r);
+        }
+      }
+    }
+  });
+}
+async function getBrowserSession() {
+  if (session && !session.dead)
+    return session;
+  const previousPath = session?.armedPath;
+  const conn = await openBrowser();
+  const s = { conn, downloads: [], waiters: [], dead: false };
+  subscribe(s);
+  session = s;
+  if (previousPath)
+    await armDownloadsAt(previousPath);
+  return s;
+}
+async function browserSend(method, params = {}) {
+  const s = await getBrowserSession();
+  try {
+    return await s.conn.send(method, params);
+  } catch (e) {
+    if (isDisconnect(e)) {
+      s.dead = true;
+      const fresh = await getBrowserSession();
+      return await fresh.conn.send(method, params);
+    }
+    throw e;
+  }
+}
+async function armDownloadsAt(path) {
+  await mkdir9(path, { recursive: true });
+  const s = await getBrowserSession();
+  await s.conn.send("Browser.setDownloadBehavior", { behavior: "allowAndName", downloadPath: path, eventsEnabled: true });
+  s.armedPath = path;
+}
+async function armDownloads() {
+  const s = await getBrowserSession();
+  if (s.armedPath !== DOWNLOADS_DIR)
+    await armDownloadsAt(DOWNLOADS_DIR);
+  return { downloadPath: DOWNLOADS_DIR };
+}
+function pendingDownloads() {
+  return (session?.downloads ?? []).filter((d) => d.state === "completed" && !d.consumed);
+}
+async function nextCompletedDownload(timeoutMs) {
+  const s = await getBrowserSession();
+  const buffered = s.downloads.find((d) => d.state === "completed" && !d.consumed);
+  if (buffered) {
+    buffered.consumed = true;
+    return buffered;
+  }
+  return new Promise((resolve, reject) => {
+    const waiter = (r) => {
+      clearTimeout(timer);
+      resolve(r);
+    };
+    const timer = setTimeout(() => {
+      const i = s.waiters.indexOf(waiter);
+      if (i >= 0)
+        s.waiters.splice(i, 1);
+      reject(new Error(`wait_for_download: no download completed within ${timeoutMs}ms. Downloads are only captured while this server holds the arming connection, so the triggering click must come AFTER a wait_for_download call (use arm:true to arm without waiting).`));
+    }, timeoutMs);
+    s.waiters.push(waiter);
+  });
+}
+async function disposeBrowserSession() {
+  const s = session;
+  session = undefined;
+  if (!s)
+    return;
+  s.dead = true;
+  try {
+    s.conn.close();
+  } catch {}
+}
+
+// src/tools/downloads.ts
+function safeFilename(suggested) {
+  const raw = (suggested ?? "").replace(/[\u0000-\u001f]/g, "");
+  const name = basename(raw.split("\\").pop() ?? "").trim();
+  if (!name || name === "." || name === "..")
+    return "download";
+  return name;
+}
+function nextFreeName(name, taken) {
+  if (!taken.has(name))
+    return name;
+  const ext = extname(name);
+  const stem = ext ? name.slice(0, -ext.length) : name;
+  for (let i = 1;; i++) {
+    const candidate = `${stem}-${i}${ext}`;
+    if (!taken.has(candidate))
+      return candidate;
+  }
+}
+function validateWaitForDownloadArgs(args) {
+  if (args.timeoutMs !== undefined) {
+    if (typeof args.timeoutMs !== "number" || !Number.isFinite(args.timeoutMs) || args.timeoutMs <= 0) {
+      throw new Error(`wait_for_download: 'timeoutMs' must be a positive number (got ${JSON.stringify(args.timeoutMs)})`);
+    }
+  }
+  if (args.arm !== undefined && typeof args.arm !== "boolean") {
+    throw new Error(`wait_for_download: 'arm' must be a boolean (got ${JSON.stringify(args.arm)})`);
+  }
+}
+async function waitForDownload(args = {}) {
+  validateWaitForDownloadArgs(args);
+  const t = await resolveTarget(args.target);
+  const target = { id: t.id, url: t.url, title: t.title };
+  const { downloadPath } = await armDownloads();
+  if (args.arm === true)
+    return { armed: true, downloadPath, pending: pendingDownloads().length, target };
+  const rec = await nextCompletedDownload(args.timeoutMs ?? 30000);
+  if (!rec.filePath) {
+    throw new Error(`wait_for_download: download ${rec.guid} completed without a file path (nothing to return)`);
+  }
+  const suggestedFilename = safeFilename(rec.suggestedFilename);
+  const taken = new Set(await readdir3(DOWNLOADS_DIR).catch(() => []));
+  taken.delete(basename(rec.filePath));
+  const finalName = nextFreeName(suggestedFilename, taken);
+  const path = join8(DOWNLOADS_DIR, finalName);
+  await rename(rec.filePath, path);
+  const bytes = (await stat4(path)).size;
+  return { path, suggestedFilename, bytes, ...rec.url ? { url: rec.url } : {}, target };
+}
+
+// src/tools/permissions.ts
+function originOf(url) {
+  try {
+    const o = new URL(url).origin;
+    return o && o !== "null" ? o : undefined;
+  } catch {
+    return;
+  }
+}
+function validateGrantPermissionsArgs(args) {
+  const reset = args.reset === true;
+  if (args.reset !== undefined && typeof args.reset !== "boolean") {
+    throw new Error(`grant_permissions: 'reset' must be a boolean (got ${JSON.stringify(args.reset)})`);
+  }
+  if (args.permissions === undefined) {
+    if (!reset)
+      throw new Error("grant_permissions: 'permissions' is required (or pass reset:true to clear previous grants)");
+    return;
+  }
+  if (!Array.isArray(args.permissions)) {
+    throw new Error(`grant_permissions: 'permissions' must be an array of CDP PermissionType strings (got ${JSON.stringify(args.permissions)})`);
+  }
+  if (args.permissions.length === 0 && !reset) {
+    throw new Error("grant_permissions: 'permissions' must not be empty (pass reset:true if the intent is to clear grants)");
+  }
+  for (const p of args.permissions) {
+    if (typeof p !== "string" || p.length === 0) {
+      throw new Error(`grant_permissions: every entry of 'permissions' must be a non-empty string (got ${JSON.stringify(p)})`);
+    }
+  }
+}
+async function grantPermissions(args = {}) {
+  validateGrantPermissionsArgs(args);
+  const t = await resolveTarget(args.target);
+  const target = { id: t.id, url: t.url, title: t.title };
+  const reset = args.reset === true;
+  const permissions = args.permissions ?? [];
+  if (reset)
+    await browserSend("Browser.resetPermissions", {});
+  if (permissions.length === 0)
+    return { reset: true, target };
+  const origin = args.origin ?? originOf(t.url);
+  if (!origin) {
+    throw new Error(`grant_permissions: cannot derive an origin from the target tab's url (${JSON.stringify(t.url)}); pass 'origin' explicitly, e.g. origin:"https://example.com"`);
+  }
+  await browserSend("Browser.grantPermissions", { origin, permissions });
+  return { granted: [...permissions], origin, ...reset ? { reset: true } : {}, target };
+}
+
 // src/index.ts
 var cdpDriver = createCdpDriver();
 function onCdp(fn) {
@@ -3264,6 +4259,7 @@ var TOOLS = {
   click: onCdp(SHARED_TOOLS.click),
   hover: onCdp(SHARED_TOOLS.hover),
   drag: onCdp(SHARED_TOOLS.drag),
+  scroll: onCdp(SHARED_TOOLS.scroll),
   fill: onCdp(SHARED_TOOLS.fill),
   fill_form: onCdp(SHARED_TOOLS.fill_form),
   type_text: onCdp(SHARED_TOOLS.type_text),
@@ -3288,6 +4284,9 @@ var TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  dispatch_mouse: dispatchMouse,
+  wait_for_download: waitForDownload,
+  grant_permissions: grantPermissions,
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),
   list_leases: onCdp(LEASE_TOOLS.list_leases)
@@ -4048,6 +5047,8 @@ var KEY_VALUES = {
 };
 var MODIFIER_VALUES = { shift: "", control: "", ctrl: "", alt: "", meta: "", cmd: "", command: "" };
 var BUTTON_CODES = { left: 0, middle: 1, right: 2 };
+var ARM_SCROLL_SETTLE_WATCH_SOURCE = "function(){window.__cdpScrollSettle=new Promise((resolve)=>{let t;const done=()=>{window.removeEventListener('scroll',on,true);resolve(true);};" + "const on=()=>{clearTimeout(t);t=setTimeout(done,60);};window.addEventListener('scroll',on,true);t=setTimeout(done,60);setTimeout(done,500);});}";
+var AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}";
 var BIDI_CAPABILITIES = new Set([
   "emulate.deviceMetrics",
   "screenshot.fullPage",
@@ -4069,6 +5070,7 @@ async function getConnection(port, timeoutMs) {
   connections.set(port, conn);
   return conn;
 }
+var bidiBeaconScripts = new Map;
 async function safeTitle(conn, contextId) {
   try {
     const res = await conn.send("script.evaluate", { expression: "document.title", target: { context: contextId }, awaitPromise: false });
@@ -4113,6 +5115,22 @@ async function pickContext(conn, contexts, selector) {
         return c;
     throw driverError2("no-such-target", `no context with title containing '${needle}'`);
   }
+  if (selector.startsWith("label:")) {
+    const label = selector.slice(6);
+    const { matchIds, knownLabels } = await resolveLiveLabel("firefox", label, contexts.map((c) => c.context));
+    if (matchIds.length > 1) {
+      throw driverError2("no-such-target", `label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`);
+    }
+    if (matchIds.length === 1) {
+      const hit = contexts.find((c) => c.context === matchIds[0]);
+      if (hit)
+        return hit;
+    }
+    throw driverError2("no-such-target", knownLabels.length ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})` : `no live target with label '${label}' (no labels are currently assigned to any open target)`);
+  }
+  if (isWorkerSelector(selector)) {
+    throw driverError2("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact)
     return exact;
@@ -4132,9 +5150,31 @@ class BidiPageDriver {
     this.info = info;
     this.browser = browser;
   }
+  async urlAndReadyState() {
+    const raw = await this.conn.send("script.evaluate", {
+      expression: "location.href + '\\u0000' + document.readyState",
+      target: { context: this.contextId },
+      awaitPromise: false
+    }).then((r) => r.type === "success" ? String(deserializeRemote(r.result) ?? "") : "").catch(() => "");
+    const [url = "", ready = ""] = raw.split("\x00");
+    return [url, ready];
+  }
+  async settleAfterTraversal(beforeUrl, waitUntil, timeoutMs) {
+    const ready = waitUntil === "domcontentloaded" ? ["interactive", "complete"] : ["complete"];
+    const deadline = Date.now() + timeoutMs;
+    for (;; ) {
+      const [url, state] = await this.urlAndReadyState();
+      if (url && url !== beforeUrl && ready.includes(state))
+        return { waitedFor: waitUntil, url };
+      if (Date.now() >= deadline)
+        return { waitedFor: "timeout", url: url || beforeUrl };
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
   async navigate(opts) {
     const reload = opts.reload === true;
-    if (!reload && !opts.url)
+    const history = opts.history;
+    if (!reload && !history && !opts.url)
       throw driverError2("page-error", "navigate: 'url' is required unless reload:true");
     const waitUntil = opts.waitUntil ?? "load";
     const wait = waitUntil === "domcontentloaded" ? "interactive" : "complete";
@@ -4144,6 +5184,17 @@ class BidiPageDriver {
         const r2 = await this.conn.send("browsingContext.reload", { context: this.contextId, ignoreCache: opts.ignoreCache === true, wait }, sendOpts);
         return { url: r2.url, contextId: this.contextId, reloaded: true, waitedFor: waitUntil };
       }
+      if (history) {
+        const [beforeUrl] = await this.urlAndReadyState();
+        await this.conn.send("browsingContext.traverseHistory", { context: this.contextId, delta: history === "back" ? -1 : 1 }, sendOpts).catch((e) => {
+          const msg = e instanceof Error ? e.message : String(e);
+          if (/no such history entry|history/i.test(msg))
+            throw driverError2("page-error", `navigate: no history entry to go ${history} to (${msg})`);
+          throw e;
+        });
+        const settled = await this.settleAfterTraversal(beforeUrl, waitUntil, opts.timeoutMs ?? 15000);
+        return { url: settled.url, contextId: this.contextId, traversed: history, waitedFor: settled.waitedFor };
+      }
       const r = await this.conn.send("browsingContext.navigate", { context: this.contextId, url: opts.url, wait }, sendOpts);
       return { url: r.url, contextId: this.contextId, waitedFor: waitUntil };
     } catch (e) {
@@ -4226,6 +5277,7 @@ class BidiPageDriver {
       throw driverError2("stale-uid", `uid does not resolve: ${uid}`);
   }
   async performActions(actions) {
+    recordDispatch("firefox", this.contextId);
     try {
       await this.conn.send("input.performActions", { context: this.contextId, actions });
     } catch (e) {
@@ -4246,6 +5298,9 @@ class BidiPageDriver {
     return { x, y };
   }
   async click(loc, opts) {
+    if (opts?.modifiers && opts.modifiers.length > 0) {
+      throw driverError2("unsupported", "click: 'modifiers' is not supported by the Firefox/BiDi driver; omit 'modifiers' or use --browser chrome for a modifier click.");
+    }
     const ref = await resolveElementLocator2(this.conn, this.contextId, loc);
     const { x, y } = await this.centerOf(ref);
     const button = BUTTON_CODES[opts?.button ?? "left"];
@@ -4255,19 +5310,53 @@ class BidiPageDriver {
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
     return { x, y };
   }
-  async drag(from, to) {
+  async scroll(anchor, opts) {
+    const { x, y } = await this.resolveScrollPoint(anchor);
+    const deltaX = Math.round(opts.deltaX ?? 0);
+    const deltaY = Math.round(opts.deltaY ?? 0);
+    await this.callFunctionValue(ARM_SCROLL_SETTLE_WATCH_SOURCE, []);
+    const actions = [{ type: "scroll", x: Math.round(x), y: Math.round(y), deltaX, deltaY }];
+    await this.performActions([{ type: "wheel", id: "cdp-wheel", actions }]);
+    await this.callFunctionValue(AWAIT_SCROLL_SETTLE_SOURCE, []).catch(() => {
+      return;
+    });
+    return { x, y };
+  }
+  async resolveScrollPoint(anchor) {
+    if (anchor === undefined) {
+      const v = await this.callFunctionValue("function(){return {x: window.innerWidth / 2, y: window.innerHeight / 2};}", []);
+      if (!v || typeof v !== "object")
+        throw driverError2("page-error", "could not measure viewport for scroll center");
+      return v;
+    }
+    if ("x" in anchor)
+      return anchor;
+    return this.centerOf(await resolveElementLocator2(this.conn, this.contextId, anchor));
+  }
+  async drag(from, to, opts) {
+    if (opts?.mode === "html5") {
+      throw driverError2("unsupported", "drag: mode:'html5' is not supported by the Firefox/BiDi driver (WebDriver BiDi has no drag-interception primitive); " + "omit 'mode' for the synthetic-mouse drag, or use --browser chrome for real HTML5 drag events.");
+    }
     const fromPt = await this.centerOf(await resolveElementLocator2(this.conn, this.contextId, from));
-    const toPt = await this.centerOf(await resolveElementLocator2(this.conn, this.contextId, to));
+    const toPt = await this.resolveDragDestination(to, fromPt);
+    const steps = Math.max(1, Math.trunc(opts?.steps ?? 2));
     const actions = [
       { type: "pointerMove", x: fromPt.x, y: fromPt.y, duration: 0 },
-      { type: "pointerDown", button: 0 },
-      { type: "pointerMove", x: (fromPt.x + toPt.x) / 2, y: (fromPt.y + toPt.y) / 2, duration: 50 },
-      { type: "pointerMove", x: toPt.x, y: toPt.y, duration: 50 },
-      { type: "pointerUp", button: 0 }
+      { type: "pointerDown", button: 0 }
     ];
+    for (const pt of interpolatePoints(fromPt, toPt, steps))
+      actions.push({ type: "pointerMove", x: pt.x, y: pt.y, duration: 50 });
+    actions.push({ type: "pointerUp", button: 0 });
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
     return { from: fromPt, to: toPt };
   }
+  async resolveDragDestination(to, fromPt) {
+    if ("dx" in to)
+      return { x: fromPt.x + to.dx, y: fromPt.y + to.dy };
+    if ("x" in to)
+      return to;
+    return this.centerOf(await resolveElementLocator2(this.conn, this.contextId, to));
+  }
   async sendKeys(text) {
     if (!text.length)
       return;
@@ -4637,7 +5726,60 @@ class BidiBrowserDriver {
     const info = await pageInfoOf(conn, ctx);
     return new BidiPageDriver(conn, ctx.context, info, this);
   }
+  async installActivityBeacon(contextId) {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+      return;
+    });
+    if (!conn)
+      return false;
+    try {
+      const key = `${this.port}:${contextId}`;
+      if (!bidiBeaconScripts.has(key)) {
+        const registered = await conn.send("script.addPreloadScript", {
+          functionDeclaration: BEACON_FUNCTION_DECLARATION,
+          contexts: [contextId]
+        });
+        bidiBeaconScripts.set(key, registered.script);
+      }
+      await conn.send("script.evaluate", {
+        expression: BEACON_SOURCE,
+        target: { context: contextId },
+        awaitPromise: false
+      });
+      return true;
+    } catch {
+      return false;
+    } finally {
+      conn.release();
+    }
+  }
+  async readActivityBeacon(contextId) {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+      return;
+    });
+    if (!conn)
+      return null;
+    try {
+      const res = await conn.send("script.evaluate", {
+        expression: BEACON_READ_EXPRESSION,
+        target: { context: contextId },
+        awaitPromise: false
+      });
+      if (res.type !== "success")
+        return null;
+      const value = deserializeRemote(res.result);
+      return typeof value === "number" && Number.isFinite(value) ? value : null;
+    } catch {
+      return null;
+    } finally {
+      conn.release();
+    }
+  }
   async dispose() {
+    for (const key of [...bidiBeaconScripts.keys()]) {
+      if (key.startsWith(`${this.port}:`))
+        bidiBeaconScripts.delete(key);
+    }
     const conn = connections.get(this.port);
     if (!conn)
       return;
@@ -4654,7 +5796,7 @@ import { spawn as spawn3 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join7 } from "node:path";
+import { join as join9 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -4728,7 +5870,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join7(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join9(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -5018,7 +6160,9 @@ Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else
 zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
 to), used for exactly one tool call, then disposed before the process exits.
 
-Target selector grammar: active | index:N | url:<substr> | title:<substr> | <targetId>
+Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
+  plus worker:<substr> for evaluate_script ONLY (Chrome only): an MV3 extension's background service
+  worker, e.g. worker:<extension-id>. An idle-evicted worker is started first unless wake:false.
 Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
 Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.
@@ -5146,14 +6290,14 @@ async function main() {
 `);
       return 1;
     }
-    const session = await startFirefoxSession();
+    const session2 = await startFirefoxSession();
     try {
-      const result = await neutralFn(session.driver, parsed.args);
+      const result = await neutralFn(session2.driver, parsed.args);
       process.stdout.write(`${JSON.stringify(result, null, 2)}
 `);
       return 0;
     } finally {
-      await session.dispose();
+      await session2.dispose();
     }
   });
 }