cdp-toolkit 1.7.0 → 1.8.0

package/dist/cli.js

@@ -486,6 +486,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",
@@ -709,11 +844,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 +915,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 +954,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 +1130,11 @@ var CDP_CAPABILITIES = new Set([
   "input.insertTextAtomic",
   "locate.text",
   "locate.xpath",
-  "capture.screencast"
+  "capture.screencast",
+  "input.raw",
+  "input.html5Drag",
+  "browser.downloads",
+  "browser.permissions"
 ]);
 
 class CdpPageDriver {
@@ -983,6 +1154,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 +1165,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 +1198,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 +1210,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 +1303,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 +1407,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 +1624,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 +1692,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 };
     });
   }
@@ -1412,7 +1706,83 @@ class CdpBrowserDriver {
     const { conn, target } = await openPage(selector).catch(noSuchTarget);
     return new CdpPageDriver(conn, target, this);
   }
-  async dispose() {}
+  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);
+    }
+    const wsUrl = await targetWsUrl(targetId).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;
+  }
+  async readActivityBeacon(targetId) {
+    const held = beaconSessions.get(targetId);
+    if (held) {
+      const value = await readBeaconOver(held);
+      if (value !== undefined)
+        return value;
+      beaconSessions.drop(targetId);
+    }
+    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 {
+      return await readBeaconOver(conn) ?? null;
+    } finally {
+      conn.close();
+    }
+  }
+  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();
+    }
+  }
+  async dispose() {
+    beaconSessions.clear();
+  }
 }
 function createCdpDriver() {
   return new CdpBrowserDriver;
@@ -1534,6 +1904,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 +1915,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 }));
@@ -1641,18 +2019,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 +2055,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 +2087,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)
     };
   });
@@ -1853,22 +2262,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 +2489,7 @@ var SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,
@@ -2038,12 +2539,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 +2555,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 +2592,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 +3763,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 +4050,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 +4075,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 +4838,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 +4861,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 });
@@ -4132,9 +4925,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 +4959,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 +5052,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 +5073,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 +5085,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 +5501,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 +5571,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 +5645,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");
@@ -5146,14 +6063,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();
     }
   });
 }