cdp-toolkit 1.7.0 → 1.9.0

package/src/bidi/driver.ts

@@ -24,14 +24,18 @@
  */
 import type { TargetSelector } from "../types.ts";
 import {
-  UID_STAMP_ATTR, isDriverError,
+  UID_STAMP_ATTR, isDriverError, interpolatePoints,
   type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  type DragDestination, type DragOptions,
   type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel,
   type MouseButtonOptions, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
-  type ScreenshotOptions, type SnapshotNode, type UidStability,
+  type ScreenshotOptions, type ScrollOptions, type SnapshotNode, type UidStability,
 } from "../driver.ts";
 import { assertLeaseOk } from "../leases.ts";
+import { resolveLiveLabel } from "../origins.ts";
+import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
+import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
 import { BidiConnection, BidiError, connectBidiSession } from "./client.ts";
 import { takeStampedSnapshot } from "./snapshot.ts";
 import { selectRule, buildFulfillParams, effectiveAction } from "../tools/network_mock.ts";
@@ -39,7 +43,7 @@ import type {
   BrowsingContextId, BrowsingContextInfo, BrowsingContextLocator, BrowsingContextReadinessState,
   BrowsingContextCaptureScreenshotParameters, ScriptSharedReference, ScriptRemoteValue, ScriptLocalValue,
   ScriptNodeRemoteValue, ScriptExceptionDetails, InputSourceActions, InputPointerSourceAction, InputKeySourceAction,
-  NetworkCookie,
+  InputWheelSourceAction, NetworkCookie,
 } from "./protocol.ts";
 
 /* ---------------------------------- cookies ---------------------------------- */
@@ -256,6 +260,14 @@ const KEY_VALUES: Record<string, string> = {
 const MODIFIER_VALUES: Record<string, string> = { shift: "\uE008", control: "\uE009", ctrl: "\uE009", alt: "\uE00A", meta: "\uE03D", cmd: "\uE03D", command: "\uE03D" };
 const BUTTON_CODES: Record<"left" | "right" | "middle", number> = { left: 0, middle: 1, right: 2 };
 
+/** Same scroll-settle technique as cdp/driver.ts's ARM_SCROLL_SETTLE_WATCH / awaitScrollSettle,
+ *  see that file's doc comment for the full rationale: a capture-phase 'scroll' listener on
+ *  window, debounced 60ms with a 500ms cap, so scroll()'s caller observes the settled position. */
+const 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);});}";
+const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}";
+
 /**
  * Firefox 153 capabilities. Only what was empirically verified is declared: emulate.deviceMetrics
  * (browsingContext.setViewport) and the userAgent path (universal, no capability token) both work.
@@ -301,6 +313,22 @@ async function getConnection(port: number, timeoutMs?: number): Promise<BidiConn
   return conn;
 }
 
+/**
+ * Contexts that already carry a beacon preload script, keyed port:context ->
+ * the script id BiDi handed back.
+ *
+ * WHY FIREFOX NEEDS NO HELD CONNECTION where Chrome does. This driver's
+ * LifetimeModel is "session": ONE BidiConnection is memoized per port above and
+ * lives until dispose(), so a preload script registered on it stays registered
+ * across navigations for free. Chrome's equivalent registration is cleared when
+ * the registering client disconnects, and this toolkit's CDP lifetime is
+ * "per-call", which is why cdp/driver.ts has to hold a socket per beaconed tab
+ * and this file does not. The map exists only to avoid stacking a second
+ * registration on a context that already has one; the in-page script is
+ * idempotent, so a duplicate would be harmless but pointless.
+ */
+const bidiBeaconScripts = new Map<string, string>();
+
 /* ----------------------------------- context/page lookup ----------------------------------- */
 async function safeTitle(conn: BidiConnection, contextId: BrowsingContextId): Promise<string> {
   try {
@@ -358,6 +386,32 @@ async function pickContext(
     for (const c of contexts) if ((await safeTitle(conn, c.context)).includes(needle)) return c;
     throw driverError("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 driverError("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 driverError(
+      "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)) {
+    // Capability-gated, not unimplemented: "unsupported" is the DriverErrorCode
+    // that tells a caller to check the capability rather than retry. The tool
+    // itself stays available on Firefox — only this arm of the grammar is
+    // refused, exactly as drag's mode:'html5' is. Refusing loudly beats the
+    // alternative the bare-id fall-through would produce, which is a confusing
+    // "no context matching 'worker:abc'" that reads like a typo.
+    throw driverError("unsupported", WORKER_SELECTOR_UNSUPPORTED_MESSAGE);
+  }
   const exact = contexts.find((c) => c.context === selector);
   if (exact) return exact;
   throw driverError("no-such-target", `no context matching '${selector}'`);
@@ -369,9 +423,51 @@ class BidiPageDriver implements PageDriver {
   private bodyCollector?: string;
   constructor(private readonly conn: BidiConnection, private readonly contextId: BrowsingContextId, readonly info: PageInfo, readonly browser: BrowserDriver) {}
 
+  /** `location.href` and `document.readyState` in one round trip, NUL-joined so the result comes
+   *  back as one plain string (deserializeRemote's simplest shape). Empty strings on any failure —
+   *  a transient evaluate error during a navigation is normal and must not abort a poll. */
+  private async urlAndReadyState(): Promise<[string, string]> {
+    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("\u0000");
+    return [url, ready];
+  }
+
+  /**
+   * Bounded readiness wait after a history traversal.
+   *
+   * WHY THIS EXISTS AT ALL. browsingContext.navigate and .reload both take a `wait` readiness state
+   * and block server-side until it is reached, which is why the two branches below simply return
+   * `waitedFor: waitUntil`. browsingContext.traverseHistory takes NO `wait` parameter and returns
+   * as soon as the traversal is dispatched, so this driver owns the wait for that one path — the
+   * same position cdp/driver.ts is in for every navigation.
+   *
+   * Polling rather than a `browsingContext.load` subscription, matching waitForText's in-file
+   * pattern: a bfcache restore does not necessarily re-fire a load event, so an event wait could
+   * hang on a perfectly successful traversal while a poll observes the settled document directly.
+   *
+   * KNOWN LIMIT, stated rather than hidden: "we moved" is inferred from the url changing. A
+   * traversal between two history entries with the IDENTICAL url therefore cannot be confirmed and
+   * burns the whole budget before returning "timeout" — with the correct url, and after the
+   * traversal really did happen. That is the honest reading of the only signal available here.
+   */
+  private async settleAfterTraversal(beforeUrl: string, waitUntil: "load" | "domcontentloaded", timeoutMs: number): Promise<{ waitedFor: NavigateResult["waitedFor"]; url: string }> {
+    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: NavigateOptions): Promise<NavigateResult> {
     const reload = opts.reload === true;
-    if (!reload && !opts.url) throw driverError("page-error", "navigate: 'url' is required unless reload:true");
+    const history = opts.history;
+    if (!reload && !history && !opts.url) throw driverError("page-error", "navigate: 'url' is required unless reload:true");
     const waitUntil = opts.waitUntil ?? "load";
     const wait: BrowsingContextReadinessState = waitUntil === "domcontentloaded" ? "interactive" : "complete";
     const sendOpts = opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {};
@@ -380,6 +476,21 @@ class BidiPageDriver implements PageDriver {
         const r = await this.conn.send("browsingContext.reload", { context: this.contextId, ignoreCache: opts.ignoreCache === true, wait }, sendOpts);
         return { url: r.url, contextId: this.contextId, reloaded: true, waitedFor: waitUntil };
       }
+      if (history) {
+        const [beforeUrl] = await this.urlAndReadyState();
+        // NavigateOptions.history forbids a silent no-op. Firefox answers a traversal past either
+        // end of the session history with a "no such history entry" error, which mapBidiError would
+        // relay verbatim — a message that never names the direction the caller asked for. Rewrapped
+        // here so back-at-the-start and forward-at-the-end read the same on both backends.
+        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 driverError("page-error", `navigate: no history entry to go ${history} to (${msg})`);
+            throw e;
+          });
+        const settled = await this.settleAfterTraversal(beforeUrl, waitUntil, opts.timeoutMs ?? 15_000);
+        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 as string, wait }, sendOpts);
       return { url: r.url, contextId: this.contextId, waitedFor: waitUntil };
     } catch (e) {
@@ -454,7 +565,25 @@ class BidiPageDriver implements PageDriver {
     if (!nodes.length) throw driverError("stale-uid", `uid does not resolve: ${uid}`);
   }
 
+  /**
+   * THE INPUT DISPATCH CHOKE POINT for Firefox, and the direct counterpart of
+   * cdp/driver.ts's dispatchInput. Every synthesized input this driver produces
+   * is already funnelled through this one method (hover, click, scroll, drag,
+   * setValue, typeText, pressKey all build actions and call it), so the
+   * dispatch-log write that keeps the toolkit's own input from reading as a
+   * human's needs exactly one line, here. See ../activity.ts.
+   *
+   * scroll and the generalised drag arrived on the OTHER 1.8.0 branch (Track P)
+   * and inherited the log for free by building on this method — which is the
+   * whole argument for a choke point, and the reason this list is worth keeping
+   * accurate rather than deleting.
+   *
+   * NOT routed through here: input.setFiles (upload_file). Same reasoning as the
+   * CDP side — it fires none of the beacon's events, so logging it could only
+   * suppress a real human input, never prevent a false one.
+   */
   private async performActions(actions: InputSourceActions[]): Promise<void> {
+    recordDispatch("firefox", this.contextId);
     try {
       await this.conn.send("input.performActions", { context: this.contextId, actions });
     } catch (e) {
@@ -474,7 +603,18 @@ class BidiPageDriver implements PageDriver {
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions: [{ type: "pointerMove", x, y, duration: 0 }] }]);
     return { x, y };
   }
+  // modifiers is new in 1.8.0 (Track P1). Chrome expresses it as a bitmask on the same
+  // mousePressed/mouseReleased events (cdp/driver.ts's inputModifierBits); WebDriver BiDi has no
+  // equivalent field on a pointerDown/pointerUp action; a modifier chord instead requires a SECOND
+  // "key" input source ticked in lockstep with the pointer source across the same performActions
+  // call, which the spec explicitly permits skipping ("throw a clear error when modifiers are
+  // passed on firefox" — see cdp-toolkit's 1.8.0 spec, Track P1 §3) and this driver was not
+  // verified against real Firefox for this pass, so it throws "unsupported" rather than guess at
+  // untested tick-synchronization semantics.
   async click(loc: ElementLocator, opts?: MouseButtonOptions): Promise<{ x: number; y: number }> {
+    if (opts?.modifiers && opts.modifiers.length > 0) {
+      throw driverError("unsupported", "click: 'modifiers' is not supported by the Firefox/BiDi driver; omit 'modifiers' or use --browser chrome for a modifier click.");
+    }
     const ref = await resolveElementLocator(this.conn, this.contextId, loc);
     const { x, y } = await this.centerOf(ref);
     const button = BUTTON_CODES[opts?.button ?? "left"];
@@ -483,17 +623,63 @@ class BidiPageDriver implements PageDriver {
     await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
     return { x, y };
   }
-  async drag(from: ElementLocator, to: ElementLocator): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }> {
+  // 1.8.0 Track P1: BiDi's "wheel" input source (a distinct source type from "pointer"/"key")
+  // carries x/y/deltaX/deltaY directly on its one "scroll" action — no tick synchronization with
+  // another source needed, unlike click's modifiers above, which is what makes this tractable.
+  // Same settle-wait rationale as cdp/driver.ts's armScrollSettleWatch: a wheel-triggered scroll
+  // is a browser-animated effect, not a synchronous DOM mutation, so a caller reading scroll
+  // position immediately after performActions resolves risks the pre-scroll value. Not empirically
+  // verified against real Firefox this pass (no Firefox available in this environment), but applied
+  // for consistency with the verified Chrome behavior rather than left as a known, unfixed gap.
+  async scroll(anchor: ElementLocator | { x: number; y: number } | undefined, opts: ScrollOptions): Promise<{ x: number; y: number }> {
+    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: InputWheelSourceAction[] = [{ 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(() => undefined);
+    return { x, y };
+  }
+  private async resolveScrollPoint(anchor: ElementLocator | { x: number; y: number } | undefined): Promise<{ x: number; y: number }> {
+    if (anchor === undefined) {
+      const v = await this.callFunctionValue("function(){return {x: window.innerWidth / 2, y: window.innerHeight / 2};}", []);
+      if (!v || typeof v !== "object") throw driverError("page-error", "could not measure viewport for scroll center");
+      return v as { x: number; y: number };
+    }
+    if ("x" in anchor) return anchor;
+    return this.centerOf(await resolveElementLocator(this.conn, this.contextId, anchor));
+  }
+  // 1.8.0 Track P2. mode:"html5" is REFUSED here, never silently downgraded to mouse mode: WebDriver
+  // BiDi has no drag-interception primitive at all (no setInterceptDrags equivalent, no drag event
+  // to subscribe to, no dispatchDragEvent), so there is nothing to port. The param-level refusal
+  // mirrors click's modifiers-on-Firefox above — `drag` itself stays in tools/list because mouse
+  // mode is fully supported here. `to` accepting a point or an offset, and `steps`, are both
+  // backend-neutral and DO work on this driver.
+  async drag(from: ElementLocator, to: DragDestination, opts?: DragOptions): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }> {
+    if (opts?.mode === "html5") {
+      throw driverError(
+        "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 resolveElementLocator(this.conn, this.contextId, from));
-    const toPt = await this.centerOf(await resolveElementLocator(this.conn, this.contextId, to));
+    const toPt = await this.resolveDragDestination(to, fromPt);
+    const steps = Math.max(1, Math.trunc(opts?.steps ?? 2));
     const actions: InputPointerSourceAction[] = [
       { 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 },
     ];
+    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 };
   }
+  private async resolveDragDestination(to: DragDestination, fromPt: { x: number; y: number }): Promise<{ x: number; y: number }> {
+    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 resolveElementLocator(this.conn, this.contextId, to));
+  }
   // No atomic value-commit primitive over BiDi (established fact): every key goes through
   // input.performActions, batched into ONE call regardless of string length, so setValue/typeText
   // cost exactly 2 round trips (one evaluate to focus/clear, one performActions for the keys).
@@ -921,7 +1107,72 @@ class BidiBrowserDriver implements BrowserDriver {
     const info = await pageInfoOf(conn, ctx);
     return new BidiPageDriver(conn, ctx.context, info, this);
   }
+
+  /**
+   * Install the activity beacon (../activity.ts) into a context and every
+   * document it navigates to afterwards.
+   *
+   * Both legs matter: script.addPreloadScript arms every FUTURE document (and
+   * survives navigation for free here, see bidiBeaconScripts above), while the
+   * script.evaluate arms the document already loaded, which a preload script
+   * never retroactively reaches.
+   *
+   * DELIBERATELY GATE-FREE (no resolveContext), like its CDP twin and for the
+   * same reason: the claim_page{target} path reads and installs around a claim
+   * that the lease gate would otherwise take on its own behalf. Returning false
+   * rather than throwing is the contract — installBeacon's caller treats this as
+   * an annotation that must never fail real work.
+   */
+  async installActivityBeacon(contextId: string): Promise<boolean> {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => undefined);
+    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();
+    }
+  }
+
+  /** Read the beacon timestamp for a context, or null when it has none. Gate-free;
+   *  see the declaration in ../driver.ts for why that is required here. */
+  async readActivityBeacon(contextId: string): Promise<number | null> {
+    const conn = await getConnection(this.port, this.timeoutMs).catch(() => undefined);
+    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(): Promise<void> {
+    for (const key of [...bidiBeaconScripts.keys()]) {
+      if (key.startsWith(`${this.port}:`)) bidiBeaconScripts.delete(key);
+    }
     const conn = connections.get(this.port);
     if (!conn) return;
     connections.delete(this.port);

package/src/capabilities.ts

@@ -1,5 +1,5 @@
 /**
- * Per-backend tool availability: filters the 41-tool registry down to what a
+ * Per-backend tool availability: filters the 45-tool registry down to what a
  * given DriverKind can actually run, per ADR-001's rule that tools/list
  * discovers gaps, not runtime "unsupported" throws. Pure and I/O-free: driver
  * construction reads a static readonly `capabilities` set, it does not dial a