cdp-toolkit 1.7.0 → 1.9.0

package/src/cdp/workers.ts

@@ -0,0 +1,177 @@
+/**
+ * Chrome-only: resolving a "worker:<substring>" selector, including WAKING an
+ * idle-evicted MV3 service worker so there is something to resolve.
+ *
+ * EVERY PROTOCOL CHOICE BELOW WAS MEASURED against Chrome 151.0.7922.109 for
+ * 1.9.0, because the obvious ones are wrong:
+ *
+ *  1. `ServiceWorker.enable` and `ServiceWorker.startWorker` DO NOT EXIST on the
+ *     browser endpoint — both answer `-32601 wasn't found` there. The domain is
+ *     reachable only over a session attached to a PAGE target. Any page works;
+ *     a plain `about:blank` tab hosted the wake in the probe, so no page on the
+ *     extension's own origin is needed. That is why this opens a browser
+ *     connection and then attaches a flattened session to some page, rather
+ *     than talking to the browser endpoint directly.
+ *
+ *  2. A STOPPED worker is not a target. It is absent from `/json/list` and from
+ *     `Target.getTargets` under every filter tried (including an explicit
+ *     all-types filter, and after `Target.setDiscoverTargets`). The ONLY place a
+ *     stopped worker is visible is the registration inventory that
+ *     `ServiceWorker.enable` pushes as `workerRegistrationUpdated` /
+ *     `workerVersionUpdated`. So matching a substring against a sleeping worker
+ *     means matching against those events, not against a target list.
+ *
+ *  3. `ServiceWorker.startWorker` RETURNS EMPTY SUCCESS FOR A SCOPE THAT DOES
+ *     NOT EXIST — a completely invented `chrome-extension://aaaa.../` scope
+ *     answers `{}` exactly like a real one. Its result is therefore worthless as
+ *     evidence, and nothing here reports a wake on the strength of it: the
+ *     caller re-reads the target list and only a worker that actually shows up
+ *     counts. This is the one dishonesty the feature could most easily ship.
+ *
+ * WHY THE CONNECTION IS ALWAYS CLOSED IN A `finally`. Two reasons, and the
+ * second is not obvious: a leaked socket keeps the process alive (the standing
+ * harness rule), AND an attached CDP session KEEPS A SERVICE WORKER FROM BEING
+ * EVICTED. A connection left open here would suppress the very eviction this
+ * module exists to recover from, so the leak would hide itself.
+ */
+import { CdpError, listTargets, openBrowser } from "../client.ts";
+import type { Target } from "../types.ts";
+import {
+  resolveWorkerTargets,
+  workerAmbiguityMessage,
+  workerMissMessage,
+  workerNeedle,
+  WORKER_EMPTY_NEEDLE_MESSAGE,
+} from "../workers.ts";
+
+/** Bounded wait for the first inventory event after ServiceWorker.enable. A
+ *  browser with no registrations at all never sends one, so this must time out
+ *  rather than hang; the settle that follows collects the rest of the batch. */
+const INVENTORY_FIRST_EVENT_MS = 1_500;
+const INVENTORY_SETTLE_MS = 250;
+/** Wake poll budget: 30 x 300ms = 9s. The probe saw a worker reappear in well
+ *  under 2s; the headroom is for a cold worker whose top-level code does work. */
+const WAKE_POLL_MS = 300;
+const WAKE_POLL_ATTEMPTS = 30;
+
+const 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.";
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+interface RegistrationEvent {
+  registrationId?: unknown;
+  scopeURL?: unknown;
+  isDeleted?: unknown;
+}
+interface VersionEvent {
+  registrationId?: unknown;
+  scriptURL?: unknown;
+  runningStatus?: unknown;
+}
+
+export interface WorkerStartAttempt {
+  /** True only when a matching registration was found AND a start was issued.
+   *  Says nothing about whether the worker actually came up: see fact 3. */
+  startRequested: boolean;
+  /** Every registered scope this browser reported, for the miss message. */
+  scopes: string[];
+}
+
+/**
+ * Read the service-worker registration inventory and, when exactly one
+ * registration matches `needle`, ask Chrome to start it.
+ *
+ * Matching is against the version's scriptURL OR the registration's scopeURL,
+ * so both `worker:<extension-id>` (which appears in both) and
+ * `worker:background.js` (which appears only in the scriptURL) resolve.
+ */
+export async function requestWorkerStart(needle: string): Promise<WorkerStartAttempt> {
+  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<{ sessionId?: string }>("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<string, string>();
+    const versions: Array<{ registrationId: string; scriptURL: string }> = [];
+    conn.on("ServiceWorker.workerRegistrationUpdated", (params) => {
+      for (const r of (params.registrations as RegistrationEvent[] | undefined) ?? []) {
+        if (r.isDeleted === true) continue;
+        scopeById.set(String(r.registrationId), String(r.scopeURL ?? ""));
+      }
+    });
+    conn.on("ServiceWorker.workerVersionUpdated", (params) => {
+      for (const v of (params.versions as VersionEvent[] | undefined) ?? []) {
+        versions.push({ registrationId: String(v.registrationId), scriptURL: String(v.scriptURL ?? "") });
+      }
+    });
+
+    await conn.send("ServiceWorker.enable", {}, { sessionId });
+    // The inventory arrives as events AFTER the enable response, so waiting on
+    // the response alone would read an empty map every time.
+    await conn.waitFor("ServiceWorker.workerVersionUpdated", undefined, INVENTORY_FIRST_EVENT_MS).catch(() => undefined);
+    await sleep(INVENTORY_SETTLE_MS);
+
+    const scopes = [...new Set(scopeById.values())].filter((s) => s.length > 0).sort();
+    const matched = new Set<string>();
+    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 {
+    // See the header: a held session also suppresses eviction.
+    conn.close();
+  }
+}
+
+/**
+ * Resolve a `worker:<substring>` selector to a live worker target, waking an
+ * evicted worker first when `wake` is true (the default at the tool surface).
+ *
+ * The wake path is: match running targets -> nothing -> ask for a start ->
+ * RE-READ THE TARGET LIST until the worker appears or the budget runs out.
+ * The re-read is the only evidence accepted that a wake happened.
+ */
+export async function resolveWorkerSelector(selector: string, opts: { wake: boolean }): Promise<Target> {
+  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 }),
+  );
+}

package/src/cli.ts

@@ -48,7 +48,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.

package/src/client.ts

@@ -5,6 +5,16 @@
  */
 import type { CdpResponse, Target, TargetSelector } from "./types.ts";
 import { assertLeaseOk } from "./leases.ts";
+import { resolveLiveLabel } from "./origins.ts";
+import {
+  isWorkerSelector,
+  isWorkerTargetType,
+  resolveWorkerTargets,
+  workerAmbiguityMessage,
+  workerMissMessage,
+  workerNeedle,
+  WORKER_EMPTY_NEEDLE_MESSAGE,
+} from "./workers.ts";
 
 /** Base HTTP origin of the DevTools endpoint. Override with CDP_BASE. */
 export const BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -197,7 +207,19 @@ export async function browserWsUrl(): Promise<string> {
  *  the ambient lease scope instead (see leases.ts). */
 export async function resolveTarget(selector: TargetSelector, opts: { lease?: string } = {}): Promise<Target> {
   const targets = await listTargets();
-  const hit = pickTarget(targets, selector);
+  const hit = await pickTarget(targets, selector);
+  // WORKER TARGETS BYPASS THE LEASE GATE ENTIRELY, and that is a decision, not
+  // an omission. A lease answers "who is driving this TAB", and every
+  // consequence of holding one is a tab consequence: reap CLOSES an abandoned
+  // leased tab, and "close the stale tab" is meaningless for a service worker
+  // that Chrome starts and stops on its own schedule (see ReapInput.livePageIds,
+  // which is deliberately fed the page-only listing for exactly this reason).
+  // Letting strict mode auto-acquire here would mint a lease file per worker
+  // evaluate, keyed on an id that vanishes the moment the worker idles out —
+  // garbage that the page-only reap set can never collect. It also cannot be
+  // used to sneak past a lease: a worker is not a tab, so there is no tab
+  // someone else holds that this could reach.
+  if (isWorkerTargetType(hit.type)) return hit;
   // THE Chrome choke point. Every tool reaches a page through here, so a tool
   // added after this shipped is protected with no action from its author.
   //
@@ -211,7 +233,7 @@ export async function resolveTarget(selector: TargetSelector, opts: { lease?: st
   return hit;
 }
 
-function pickTarget(targets: Target[], selector: TargetSelector): Target {
+async function pickTarget(targets: Target[], selector: TargetSelector): Promise<Target> {
   const pages = targets.filter((t) => t.type === "page");
   if (!selector || selector === "active") {
     if (!pages.length) throw new CdpError("no page targets open");
@@ -234,6 +256,34 @@ function pickTarget(targets: Target[], selector: TargetSelector): Target {
     if (!hit) 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)) {
+    // Resolved against the UNFILTERED listing, never `pages`: a worker is not a
+    // page target and would not be in it. Waking an evicted worker is NOT done
+    // here — this stays a pure pick over what the browser already reports, and
+    // the wake path lives in cdp/workers.ts, reached only from evaluate_script.
+    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 }));
+  }
   // bare id
   const byId = targets.find((t) => t.id === selector);
   if (!byId) throw new CdpError(`no target with id '${selector}'`);

package/src/driver.ts

@@ -1,5 +1,5 @@
 /**
- * ADR-001: one browser-neutral Driver interface behind the 41 tools.
+ * ADR-001: one browser-neutral Driver interface behind the 45 tools.
  *
  * Context. Every tool in src/tools/ is a stateless one-shot on withPage():
  * open a socket, act, always close. That is only correct because a CDP `Uid`
@@ -138,7 +138,12 @@ export type Capability =
   | "snapshot.accessibilityTree" // native a11y dump, not a DOM-walk approximation
   | "input.insertTextAtomic" // atomic value commit, not synthesized keystrokes
   | "locate.text" // find a node by visible text substring
-  | "locate.xpath"; // find a node by xpath
+  | "locate.xpath" // find a node by xpath
+  | "input.raw" // raw single mouse-event dispatch (dispatch_mouse's move/down/up primitive); Chrome only
+  | "input.html5Drag" // real HTML5 drag events (drag's mode:"html5"); Chrome only, see PageDriver.drag
+  | "browser.downloads" // capture a file download to a known path (wait_for_download); Chrome only
+  | "browser.permissions" // grant/reset browser permissions for an origin (grant_permissions); Chrome only
+  | "worker.targets"; // address a service/shared worker as a target ("worker:<substr>"), incl. waking an evicted MV3 worker; Chrome only
 
 /**
  * Tools whose availability depends on a capability. A tool absent from this
@@ -157,6 +162,9 @@ export const REQUIRED_CAPABILITIES: Partial<Record<ToolName, readonly Capability
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"],
+  dispatch_mouse: ["input.raw"],
+  wait_for_download: ["browser.downloads"],
+  grant_permissions: ["browser.permissions"],
 } as const;
 
 /* --------------------------------- errors --------------------------------- */
@@ -213,6 +221,19 @@ export interface NavigateOptions {
   url?: string;
   reload?: boolean;
   ignoreCache?: boolean;
+  /**
+   * Traverse the tab's session history instead of loading a URL: the browser Back / Forward
+   * buttons. Mutually exclusive with `url` and `reload` (the tool layer enforces that; a driver
+   * trusts its caller). Chrome: Page.getNavigationHistory + Page.navigateToHistoryEntry. Firefox:
+   * browsingContext.traverseHistory{delta:-1|+1}. Universal — both drivers implement it, so this is
+   * deliberately NOT a Capability.
+   *
+   * NO SILENT NO-OP. Asking to go back from the first history entry (or forward from the last) is a
+   * caller mistake, not a legal outcome: both drivers MUST throw an error naming the direction
+   * rather than return a success that navigated nowhere, because a no-op success reads as "you are
+   * on the previous page" and the caller acts on that.
+   */
+  history?: "back" | "forward";
   waitUntil?: "load" | "domcontentloaded";
   timeoutMs?: number;
 }
@@ -222,12 +243,93 @@ export interface NavigateResult {
   /** CDP frameId or BiDi context id. Opaque. */
   contextId: string;
   reloaded?: boolean;
+  /** Which direction a `history` traversal actually moved. Present only for a history navigation,
+   *  the same way `reloaded` is present only for a reload. */
+  traversed?: "back" | "forward";
   waitedFor: "load" | "domcontentloaded" | "committed" | "timeout";
 }
 
 export interface MouseButtonOptions {
   button?: "left" | "right" | "middle";
   clickCount?: number;
+  /** "Alt" | "Control" | "Meta" | "Shift", held for the press/release. CDP bits: Alt=1,
+   *  Control=2, Meta=4, Shift=8 (cdp/driver.ts's inputModifierBits). A non-empty array is
+   *  "unsupported" on the Firefox/BiDi driver today: see click()'s implementation note. */
+  modifiers?: readonly string[];
+}
+
+/**
+ * Where a drag ends. 1.8.0 Track P2 widened this past "an element": an absolute viewport point
+ * ({x,y}) and an offset from the source point ({dx,dy}) are both real destinations for widgets
+ * that have no droppable element to name — a range slider's track, a map canvas, a resize gutter.
+ * The three branches are discriminated structurally ("dx" in / "x" in), the same way
+ * PageDriver.scroll's anchor already discriminates an ElementLocator from a viewport point; no
+ * ElementLocator variant carries an `x` or `dx` field, so the check is exact and not a heuristic.
+ */
+export type DragDestination = ElementLocator | { x: number; y: number } | { dx: number; dy: number };
+
+export interface DragOptions {
+  /**
+   * "mouse" (default): synthetic mousePressed/mouseMoved…/mouseReleased. Fine for widgets built on
+   * raw pointer events, and it is what `drag` has always done.
+   *
+   * "html5": a REAL HTML5 drag — Input.setInterceptDrags(true), the same press/move sequence, then
+   * the intercepted DragData replayed as Input.dispatchDragEvent dragEnter/dragOver/drop at the
+   * destination.
+   *
+   * WHAT THE DIFFERENCE ACTUALLY IS (measured on Chrome 151.0.7922.109, macOS, both --headless=new
+   * and headed — NOT assumed). Synthetic mouse events DO start a real drag in modern Chrome, so
+   * mouse mode is not inert on HTML5 drop zones the way the folklore says. What mouse mode does
+   * not control is WHICH drag events the page receives: that follows the interpolated pointer
+   * path, and at the default steps:2 a source-to-zone drag delivered dragstart and drop but ZERO
+   * dragover. A drop zone written the standard way — preventDefault inside dragover, which is how
+   * the HTML spec says you mark a valid drop target — therefore refused the drop outright, while
+   * steps:1 and steps:8 on the very same page happened to work. html5 mode removes the luck: the
+   * dragEnter/dragOver/drop triple is dispatched explicitly at the destination every time.
+   *
+   * Requires Capability "input.html5Drag" — Chrome only. A driver without that capability MUST
+   * throw "unsupported"; it must never silently downgrade to mouse mode, because a caller who
+   * asked for html5 asked precisely because mouse mode was not delivering the drop.
+   */
+  mode?: "mouse" | "html5";
+  /** Interpolated mouseMoved events dispatched between the source and destination points, evenly
+   *  spaced, the last one landing exactly on the destination. Default 2 (the pre-1.8.0 hardcoded
+   *  behavior: midpoint, then destination). DnD libraries with a movement threshold or per-frame
+   *  sampling need more. The tool layer validates the range; a driver trusts its caller. */
+  steps?: number;
+}
+
+/**
+ * The `steps` evenly-spaced points between `from` (exclusive) and `to` (inclusive), for a drag's
+ * interpolated move sequence. The last point is EXACTLY `to`, emitted as `to` itself rather than
+ * computed, so float error can never leave the pointer a fraction of a pixel short of the
+ * destination element. steps:1 is a single jump to the destination; steps:2 is
+ * midpoint-then-destination, the pre-1.8.0 hardcoded behavior.
+ *
+ * Lives here, in the backend-neutral module, because BOTH drivers need the identical geometry:
+ * the CDP driver turns each point into an Input.dispatchMouseEvent{mouseMoved} and the BiDi driver
+ * into a performActions pointerMove, but "where the pointer goes" must not differ by backend.
+ * Callers pass an already-validated integer >= 1 (the tool layer validates; a driver trusts it).
+ */
+export function interpolatePoints(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  steps: number,
+): Array<{ x: number; y: number }> {
+  const out: Array<{ x: number; y: number }> = [];
+  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;
+}
+
+export interface ScrollOptions {
+  /** Positive scrolls DOWN, positive scrolls RIGHT: wheel-event convention. The tool layer
+   *  (shared-tools.ts) requires at least one of deltaX/deltaY; a driver trusts its caller and
+   *  does not re-validate. */
+  deltaX?: number;
+  deltaY?: number;
 }
 
 export interface KeyPress {
@@ -414,6 +516,79 @@ export interface BrowserDriver {
   /** Acquire a page handle. The caller MUST release() it. Prefer withDriver. */
   page(selector: TargetSelector): Promise<PageDriver>;
 
+  /**
+   * Install the activity beacon into a target and, where the backend can, into
+   * every document it navigates to afterwards. Resolves true when the beacon is
+   * in place. See src/activity.ts.
+   *
+   * OPTIONAL, per ADR-001's "absent rather than present-and-throwing" rule, but
+   * NOT a `Capability`: that union gates whole tools out of tools/list, and no
+   * tool is gated here. The beacon is an additive FIELD on claim_page and
+   * list_leases, both of which work unchanged without it, so the honest
+   * expression of a backend that cannot do this is an absent method producing an
+   * absent field — not a missing tool and not a throw.
+   */
+  installActivityBeacon?(targetId: string): Promise<boolean>;
+
+  /**
+   * Read the beacon's timestamp for a target, or null when the target has no
+   * beacon. WITHOUT THE LEASE GATE, which is required rather than convenient:
+   * claim_page{target} must read this BEFORE claiming, and under
+   * CDP_REQUIRE_LEASE a gated read would auto-acquire the lease and then collide
+   * with the explicit claim behind it (the same reason pickPage is gate-free;
+   * see leases-tools.ts's header).
+   *
+   * This is not a general gate bypass and must never become one: it returns one
+   * number and takes no expression, so it cannot be made to read or change
+   * anything else about the page.
+   */
+  readActivityBeacon?(targetId: string): Promise<number | null>;
+
+  /**
+   * Bounded liveness probe behind list_pages{probe:true}: run ONE Runtime.evaluate
+   * (or backend equivalent) capped at `timeoutMs`, and report whether it
+   * answered in time plus whatever the activity beacon said in that same round
+   * trip. See src/activity.ts's RENDERER_PROBE_EXPRESSION for exactly what is
+   * evaluated and why.
+   *
+   * MUST NEVER REJECT. A timeout, a thrown page-side exception, a dead
+   * connection, or a target that no longer exists are all
+   * `{responsive:false, beaconTs:null}` — indistinguishable from each other and
+   * from a genuinely wedged renderer, which is the honest answer: none of them
+   * let the caller drive that tab any faster than this call already told it.
+   *
+   * OPTIONAL and NOT a `Capability`, for the same reason installActivityBeacon
+   * and readActivityBeacon are not: no whole tool is gated, only an additive
+   * field on list_pages, so the honest expression of a backend that cannot do
+   * this is an absent method producing an absent field.
+   */
+  probeRenderer?(targetId: string, timeoutMs?: number): Promise<{ responsive: boolean; beaconTs: number | null }>;
+
+  /**
+   * Resolve a "worker:<substring>" selector to a concrete service/shared-worker
+   * target, STARTING an idle-evicted MV3 service worker first when `wake` is
+   * true. The returned PageInfo's id is a plain target id, so the caller then
+   * acquires it through the ordinary page() path.
+   *
+   * OPTIONAL **and** gated by Capability "worker.targets", unlike
+   * installActivityBeacon / readActivityBeacon / probeRenderer, which are
+   * optional but deliberately NOT capabilities. The difference is what a caller
+   * can observe: those three produce an absent FIELD on a result that is
+   * otherwise complete, so silence is the honest answer. This one decides
+   * whether an argument the caller explicitly wrote is honoured, and silently
+   * resolving `worker:...` to something else — or to nothing — would be a wrong
+   * answer rather than a missing annotation. So it refuses out loud, exactly as
+   * drag's mode:'html5' does behind "input.html5Drag" (see resolveDragMode).
+   * No tool is gated out of tools/list: evaluate_script is universal, only this
+   * one arm of its `target` grammar is Chrome-only.
+   *
+   * MUST NOT report a wake it cannot see: an implementation is required to
+   * confirm the worker is back in the target listing rather than trusting the
+   * start command's own result. See cdp/workers.ts for why that is not
+   * paranoia.
+   */
+  resolveWorkerTarget?(selector: string, opts: { wake: boolean }): Promise<PageInfo>;
+
   /** Tear down the transport: process exit (CLI) or shutdown (MCP server).
    *  Idempotent. MUST NOT be called by a tool. */
   dispose(): Promise<void>;
@@ -446,7 +621,16 @@ export interface PageDriver {
   /* input */
   click(loc: ElementLocator, opts?: MouseButtonOptions): Promise<{ x: number; y: number }>;
   hover(loc: ElementLocator): Promise<{ x: number; y: number }>;
-  drag(from: ElementLocator, to: ElementLocator): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }>;
+  /** Press at `from`, move to `to`, release. `to` is an element, an absolute viewport point, or an
+   *  offset from the resolved source point (DragDestination). opts.mode picks synthetic-mouse vs.
+   *  real HTML5 drag events; opts.steps sets how many interpolated moves are dispatched. */
+  drag(from: ElementLocator, to: DragDestination, opts?: DragOptions): Promise<{ from: { x: number; y: number }; to: { x: number; y: number } }>;
+  /** Dispatch a wheel/scroll event at an anchor point. `anchor` is an ElementLocator (scrolled
+   *  into view first, exactly like click/hover), an absolute viewport point, or `undefined` for
+   *  the viewport center. Chrome: Input.dispatchMouseEvent{type:"mouseWheel"}. Firefox: BiDi's
+   *  "wheel" input source via input.performActions. Universal: both drivers must implement it
+   *  (absent from driver.ts's REQUIRED_CAPABILITIES, unlike dispatch_mouse). */
+  scroll(anchor: ElementLocator | { x: number; y: number } | undefined, opts: ScrollOptions): Promise<{ x: number; y: number }>;
   /** Overwrite an element's value. One atomic commit under
    *  "input.insertTextAtomic", else synthesized keystrokes, so per-key handlers
    *  on the page WILL fire. Callers must not depend on either behavior. */

package/src/index.ts

@@ -4,7 +4,7 @@
  * Two exports:
  *   1. `TOOLS` : the registry mapping every chrome-devtools-mcp tool name
  *      (snake_case string, all 29 of them) plus the toolkit's own superset
- *      tools, 41 entries in all, to its raw-CDP implementation function. The
+ *      tools, 45 entries in all, to its raw-CDP implementation function. The
  *      CLI and any embedder dispatch through this single table.
  *   2. The client primitives, re-exported so consumers can build their own
  *      flows on the same connection/timeout machinery the tools use.
@@ -41,6 +41,11 @@ import { takeHeapsnapshot } from "./tools/heap.ts";
 import { lighthouseAudit } from "./tools/lighthouse.ts";
 // --- network mocking (Fetch domain) : toolkit addition beyond the 29 parity tools ---
 import { mockRequest, listMocks, clearMocks } from "./tools/network_mock.ts";
+// --- raw mouse dispatch (Input.dispatchMouseEvent, one event per call) : chrome-only, capability "input.raw" ---
+import { dispatchMouse } from "./tools/dispatch-mouse.ts";
+// --- downloads + permissions (browser-endpoint state on a standing connection) : chrome-only, 1.8.0 Track P3 ---
+import { waitForDownload } from "./tools/downloads.ts";
+import { grantPermissions } from "./tools/permissions.ts";
 
 /** A toolkit tool: a single typed-args function returning JSON-serializable data. */
 export type ToolFn = (args: never) => Promise<unknown>;
@@ -67,8 +72,16 @@ function onCdp<A>(fn: (driver: ReturnType<typeof createCdpDriver>, args: A) => P
  * opt-in tab ownership so many agents can share one browser), plus a 2-tool
  * screen-recording pair (start_screen_recording/stop_screen_recording : a tab
  * captured to an H.265 MP4 with per-frame durations, so a variable-rate
- * repaint stream plays back at wallclock speed).
- * 29 + 1 + 3 + 3 + 3 + 2 = 41 entries total. Listed explicitly so the mapping is auditable at a glance and
+ * repaint stream plays back at wallclock speed), plus a 2-tool input-parity
+ * addition (1.8.0 Track P1: `scroll`, a wheel-event dispatch at an anchor
+ * point sharing click/hover's element-locator and lease-gate contract; and
+ * `dispatch_mouse`, the raw move/down/up mouse-event primitive composable
+ * into anything a physical mouse can do, chrome-only per capability "input.raw"), plus a 2-tool
+ * browser-state addition (1.8.0 Track P3: `wait_for_download`, which captures a file download to a
+ * named path, and `grant_permissions`, which answers permission prompts for an origin; both
+ * chrome-only and both driven from a standing browser-endpoint connection, see
+ * tools/browser-session.ts).
+ * 29 + 1 + 3 + 3 + 3 + 2 + 2 + 2 = 45 entries total. Listed explicitly so the mapping is auditable at a glance and
  * the CLI can `--list` it.
  *
  * 20 of the 29 MCP-parity tools (pages/navigation/evaluate/snapshot/interaction/
@@ -93,10 +106,11 @@ export const TOOLS = {
   delete_cookies: onCdp(SHARED_TOOLS.delete_cookies),
   // snapshot (1)
   take_snapshot: onCdp(SHARED_TOOLS.take_snapshot),
-  // interaction (8)
+  // interaction (9) : scroll is 1.8.0 Track P1, a toolkit addition beyond the 29 parity 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),
@@ -129,6 +143,14 @@ export const TOOLS = {
   mock_request: mockRequest,
   list_mocks: listMocks,
   clear_mocks: clearMocks,
+  // raw mouse dispatch (1) : 1.8.0 Track P1 toolkit addition, chrome-only (capability "input.raw")
+  dispatch_mouse: dispatchMouse,
+  // downloads + permissions (2) : 1.8.0 Track P3 toolkit additions, chrome-only (capabilities
+  // "browser.downloads" / "browser.permissions"). Both drive browser-endpoint state that Chrome
+  // reverts when the issuing client disconnects, so both run on tools/browser-session.ts's standing
+  // connection rather than a per-call socket : see that module's header for the measurements.
+  wait_for_download: waitForDownload,
+  grant_permissions: grantPermissions,
   // tab leases (3) : opt-in ownership so many agents can share one browser
   claim_page: onCdp(LEASE_TOOLS.claim_page),
   release_page: onCdp(LEASE_TOOLS.release_page),