cdp-toolkit 1.7.0 → 1.9.0

package/src/shared-tools.ts

@@ -36,11 +36,16 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type {
-  BrowserCookie, BrowserDriver, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+  BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
 import type { TargetSelector } from "./types.ts";
-import { assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, releaseLeaseFor, requireLease, type LeaseBackend, type LeaseToken } from "./leases.ts";
-import { newTrackedPage, originIndex, type PageOrigin } from "./origins.ts";
+import {
+  assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
+  type LeaseBackend, type LeaseStaleReason, type LeaseToken,
+} from "./leases.ts";
+import { installBeacon, probeRendererActivity, rendererProbeSupported } from "./activity.ts";
+import { newTrackedPage, originIndex, resolveLiveLabel, type PageOrigin } from "./origins.ts";
+import { isWorkerSelector, WORKER_SELECTOR_PAGE_ONLY_MESSAGE, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "./workers.ts";
 import { reapStaleAgentTabs, type ReapedTab } from "./reap.ts";
 
 const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
@@ -128,6 +133,21 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
     if (!p) throw new SharedToolError(`no page title containing '${needle}'`);
     return p;
   }
+  if (selector.startsWith("label:")) return pickByLabel(driver, pages, selector.slice(6));
+  if (isWorkerSelector(selector)) {
+    // THE PAGE-ONLY CONTRACT, STATED OUT LOUD. Every caller of pickPage
+    // (resolvePage -> close_page / select_page / release_page, claim_page's
+    // takeover) acts on a TAB, and the 1.9.0 "worker:" arm is deliberately NOT
+    // implemented here: it resolves against the page-only listing these callers
+    // pass, which by construction never contains a worker, so the arm could
+    // only ever miss. Refusing with the reason beats falling through to the
+    // bare-id lookup, whose "no target with id 'worker:foo'" reads as a typo.
+    // The arm lives in client.ts's pickTarget (Chrome's all-targets resolver),
+    // and only evaluate_script routes to it.
+    throw new SharedToolError(
+      backendOf(driver) === "firefox" ? WORKER_SELECTOR_UNSUPPORTED_MESSAGE : WORKER_SELECTOR_PAGE_ONLY_MESSAGE,
+    );
+  }
   const exactPage = pages.find((x) => x.id === selector);
   if (exactPage) return exactPage;
   const all = await driver.listPages({ all: true });
@@ -136,6 +156,35 @@ export async function pickPage(driver: BrowserDriver, pages: PageInfo[], selecto
   throw new SharedToolError(`no target with id '${selector}'`);
 }
 
+/**
+ * "label:<name>" resolution for pickPage. The lookup itself (both stores,
+ * live-scoped) is shared with client.ts's pickTarget and bidi/driver.ts's
+ * pickContext via origins.ts's resolveLiveLabel, so the three copies of the
+ * selector grammar cannot drift on what counts as a hit, a miss or an
+ * ambiguity. Only the error wording is local, matching this file's
+ * SharedToolError idiom.
+ *
+ * Nothing is reaped here: this is a read, not a maintenance pass, and pickPage
+ * stays gate-free and side-effect-free over its inputs.
+ */
+async function pickByLabel(driver: BrowserDriver, pages: PageInfo[], label: string): Promise<PageInfo> {
+  const { matchIds, knownLabels } = await resolveLiveLabel(backendOf(driver), label, pages.map((x) => x.id));
+  if (matchIds.length > 1) {
+    throw new SharedToolError(
+      `label 'label:${label}' matches more than one live target: ${matchIds.join(", ")}. Resolve by target id instead.`,
+    );
+  }
+  if (matchIds.length === 1) {
+    const p = pages.find((x) => x.id === matchIds[0]);
+    if (p) return p;
+  }
+  throw new SharedToolError(
+    knownLabels.length
+      ? `no live target with label '${label}' (labels currently in use: ${knownLabels.join(", ")})`
+      : `no live target with label '${label}' (no labels are currently assigned to any open target)`,
+  );
+}
+
 /* -------------------------------- element locators -------------------------------- */
 
 function locatorOf(args: { uid?: DriverUid; selector?: string }): ElementLocator {
@@ -166,6 +215,31 @@ export interface ListedPage extends PageInfo {
    *  genuinely unknown, but this field is what keeps an unreadable record from
    *  being reported as a clean "nothing was ever recorded". */
   originUnreadable?: string;
+  /**
+   * Present only for a tab under an active, READABLE lease of THIS backend.
+   * idleMs and expiresAt are computed fresh on every call (now-lastUsedAt and
+   * lastUsedAt+ttlMs), never read off disk — same rule as list_leases' own
+   * LeaseRow, and unconditional on `probe`: a lease can exist whether or not a
+   * caller ever passes probe:true, and this costs nothing beyond a lease-dir
+   * read this call already pays for under strict mode.
+   */
+  lease?: { label: string; pid: number; idleMs: number; expiresAt: number; stale: LeaseStaleReason | false };
+  /**
+   * Present only when { probe: true } was passed AND this backend can answer
+   * it (see rendererProbeSupported in src/activity.ts) AND this entry is a
+   * page-type target — a worker or iframe has no `window` to carry the beacon
+   * global, so probing one would be a guaranteed false negative rather than a
+   * genuine liveness answer. true when a bounded Runtime.evaluate answered
+   * within budget; false on a timeout, a thrown page-side exception, or a
+   * target the driver could not reach at all — the wedged-tab case this field
+   * exists to surface, reported as data rather than failing the whole call.
+   */
+  responsive?: boolean;
+  /** Ms since a human last touched this tab, present only where probe:true
+   *  answered AND the same round trip found human-attributed beacon data.
+   *  Same rule as claim_page/list_leases: absence is "no answer", never "no
+   *  human". */
+  humanActiveMs?: number;
 }
 
 /**
@@ -190,23 +264,52 @@ async function reapSet(driver: BrowserDriver, pages: PageInfo[], all?: boolean):
 
 export async function listPages(
   driver: BrowserDriver,
-  args: { all?: boolean } = {},
+  args: { all?: boolean; probe?: boolean } = {},
 ): Promise<{ pages: ListedPage[]; count: number; reaped?: ReapedTab[] }> {
   // Reap FIRST, so a tab this call is about to close never appears in the
-  // listing it returns. Under strict mode only: see requireLease.
-  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  // listing it returns, and so the lease read just below never reports a lease
+  // this same call is in the middle of deleting. Under strict mode only: see
+  // requireLease.
+  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));
   // Never let provenance break the listing: originIndex does not throw, and a
   // missing or unreadable ledger yields an empty map, so every page falls back
   // to origin "unknown" exactly as a pre-ledger consumer always saw.
-  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
-  const annotated: ListedPage[] = pages.map((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 ledger = await originIndex(backend, await reapSet(driver, pages, args.all));
+  const now = Date.now();
+  // Observability (1.8.0): every READABLE lease of this backend, keyed by
+  // target. Read unconditionally, not gated on `probe`, because a lease can
+  // exist whether or not a caller ever asks for a renderer ping.
+  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] as const),
+  );
+  const doProbe = args.probe === true && rendererProbeSupported(driver);
+  const annotated: ListedPage[] = await Promise.all(
+    pages.map(async (p) => {
+      const rec = ledger.get(p.id);
+      const base: ListedPage =
+        !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 };
+      }
+      // Page-type only: see ListedPage.responsive. Concurrent across pages
+      // (this whole map runs inside Promise.all), so one wedged tab's 500ms
+      // budget never serializes onto the next tab's.
+      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;
+    }),
+  );
   // `reaped` is present only when it has something to say, so the common-case
   // shape is byte-identical to 1.4.0. Silently closing a tab is not acceptable:
   // if a read closed something, the read says so.
@@ -238,6 +341,12 @@ export async function newPage(
     // silently WEAKEN every existing claim:true call site to pid-only.
     auto: !explicit,
   });
+  // Install the activity beacon on the same terms claim_page does: at claim
+  // time, after the claim, best effort (installBeacon never throws). A tab
+  // beaconed now is a tab that can ANSWER later — when this agent has released
+  // it and a person has picked it up, which is the case the beacon exists for.
+  // Nothing here is read back: a tab created a moment ago has no human history.
+  await installBeacon(driver, p.id);
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
 
@@ -286,23 +395,65 @@ export interface LegacyNavigateResult {
   url: string;
   frameId: string;
   reloaded?: boolean;
+  /** Present only on a history traversal, mirroring how `reloaded` is present only on a reload. */
+  traversed?: "back" | "forward";
   waitedFor: "load" | "domcontentloaded" | "frameStoppedLoading" | "navigate-only";
 }
 
+/** What a navigate_page call is actually asking for. Exactly one of the three. */
+export type NavigateMode =
+  | { mode: "url"; url: string }
+  | { mode: "reload" }
+  | { mode: "history"; history: "back" | "forward" };
+
+/**
+ * The three-way exclusivity check for navigate_page's url / reload / history, split out and
+ * exported so every refusal is pinned by a unit test without a browser (the same reason
+ * resolveScrollAnchor and resolveDragDestination live at this layer).
+ *
+ * EXCLUSIVE, NOT PRECEDENCE-ORDERED. `{url, history:"back"}` is a caller who does not know what
+ * they want; silently honoring one of them would navigate somewhere the caller did not ask for and
+ * report success. Refusing names both, so the mistake is visible in the error rather than in the
+ * page that comes back.
+ */
+export function resolveNavigateMode(args: { url?: string; reload?: boolean; history?: unknown }): NavigateMode {
+  const reload = args.reload === true;
+  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 as string };
+}
+
 export async function navigatePage(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; url?: string; reload?: boolean; ignoreCache?: boolean; waitUntil?: "load" | "domcontentloaded"; timeoutMs?: number },
+  args: {
+    target?: TargetSelector; url?: string; reload?: boolean; ignoreCache?: boolean;
+    history?: "back" | "forward"; waitUntil?: "load" | "domcontentloaded"; timeoutMs?: number;
+  },
 ): Promise<LegacyNavigateResult> {
-  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 mode = resolveNavigateMode(args);
   return withPage(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),
     };
   });
@@ -370,14 +521,70 @@ function sinkRequested(savePath?: string): savePath is string {
   return savePath !== undefined && savePath !== "";
 }
 
+/** Keys a caller reaches for out of habit from other automation APIs, none of
+ *  which this tool reads: the code always goes in 'expression'. Checked in
+ *  this order so the error names one wrong key, deterministically, when a
+ *  caller happens to pass more than one. */
+const EXPRESSION_ALIAS_KEYS = ["function", "code", "js", "script", "fn", "body"] as const;
+
+/**
+ * Turn a `worker:<substring>` target into a concrete target id, waking an
+ * idle-evicted MV3 service worker on the way when `wake` is not false.
+ *
+ * WHY THIS RETURNS AN ID RATHER THAN DRIVING THE WORKER ITSELF. Once resolved,
+ * a worker is just a target with its own webSocketDebuggerUrl, and a DIRECT
+ * connection to it evaluates exactly like a page does — `Runtime.evaluate` with
+ * `awaitPromise` returns real awaited values there (measured on Chrome 151;
+ * `chrome.storage.local.get(null)` comes back as an object, not undefined). So
+ * the worker rides the ordinary page() acquisition path from here, and every
+ * behavior around it — the args/function form, exception reporting, and above
+ * all savePath's no-value-in-the-response secret hygiene — is the SAME CODE,
+ * not a parallel copy that could quietly diverge on the leak-shaped edge.
+ *
+ * Exported for the unit tests, which need to reach the capability refusal
+ * without a browser.
+ */
+export async function resolveWorkerSelectorFor(
+  driver: BrowserDriver,
+  selector: string,
+  wake: boolean,
+): Promise<PageInfo> {
+  if (!driver.capabilities.has("worker.targets") || typeof driver.resolveWorkerTarget !== "function") {
+    throw new SharedToolError(`evaluateScript: ${WORKER_SELECTOR_UNSUPPORTED_MESSAGE}`);
+  }
+  return driver.resolveWorkerTarget(selector, { wake });
+}
+
 export async function evaluateScript(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string },
+  args: { target?: TargetSelector; expression: string; awaitPromise?: boolean; args?: unknown[]; savePath?: string; wake?: boolean },
 ): Promise<unknown> {
   if (typeof args.expression !== "string" || args.expression.length === 0) {
+    const wrongKey = EXPRESSION_ALIAS_KEYS.find((k) => (args as Record<string, unknown>)[k] !== undefined);
+    if (wrongKey !== undefined) {
+      throw new SharedToolError(
+        `evaluateScript: you passed '${wrongKey}'; the key is 'expression' — function literals go in 'expression', invoked with 'args'.`,
+      );
+    }
     throw new SharedToolError("evaluateScript: 'expression' must be a non-empty string");
   }
-  return withPage(driver, args.target, async (page) => {
+  if (args.wake !== undefined && typeof args.wake !== "boolean") {
+    throw new SharedToolError("evaluateScript: 'wake' must be a boolean");
+  }
+  // `wake` is REFUSED on a page selector rather than ignored. Accepting it there
+  // would read as "this call will wake something", and the caller would never
+  // learn that the argument did nothing at all.
+  if (args.wake !== undefined && !isWorkerSelector(args.target)) {
+    throw new SharedToolError(
+      "evaluateScript: 'wake' only applies to a target of the form 'worker:<substring>'; a page target is never asleep.",
+    );
+  }
+  // Resolved to a bare target id BEFORE acquisition, so the page() call below is
+  // the same one every other selector makes.
+  const target = isWorkerSelector(args.target)
+    ? (await resolveWorkerSelectorFor(driver, args.target, args.wake ?? true)).id
+    : args.target;
+  return withPage(driver, target, async (page) => {
     const value = await page.evaluate(args.expression, { args: args.args, awaitPromise: args.awaitPromise ?? true });
     // No savePath: byte-identical to the pre-sink behavior, the value itself.
     // A thrown page-side exception never reaches here, so it still surfaces as
@@ -620,14 +827,55 @@ export async function takeSnapshot(
 
 export async function click(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number },
+  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; button?: "left" | "right" | "middle"; clickCount?: number; modifiers?: string[] },
 ): Promise<{ clicked: true; x: number; y: number }> {
   return withPage(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 };
   });
 }
 
+/**
+ * scroll's anchor rule: exactly one of `{uid}`, `{selector}`, or `{x,y}` — or none of the three,
+ * which means the viewport center. `x`/`y` must arrive together; one without the other is refused
+ * rather than silently treated as "half an anchor". Exported for the unit tests, which pin the
+ * rule without a browser.
+ */
+export function resolveScrollAnchor(args: { uid?: DriverUid; selector?: string; x?: number; y?: number }): ElementLocator | { x: number; y: number } | undefined {
+  const hasUid = args.uid !== undefined && args.uid !== null && args.uid !== ("" as unknown);
+  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 as number, y: args.y as number };
+  return undefined;
+}
+
+/** scroll's delta rule: at least one of deltaX/deltaY is required (a no-op scroll is refused
+ *  rather than silently dispatched). Exported for the unit tests. */
+export function resolveScrollDelta(args: { deltaX?: number; deltaY?: number }): { deltaX: number; deltaY: number } {
+  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 };
+}
+
+export async function scroll(
+  driver: BrowserDriver,
+  args: { target?: TargetSelector; uid?: DriverUid; selector?: string; x?: number; y?: number; deltaX?: number; deltaY?: number },
+): Promise<{ x: number; y: number; deltaX: number; deltaY: number; target: { id: string; url: string; title: string } }> {
+  const anchor = resolveScrollAnchor(args);
+  const { deltaX, deltaY } = resolveScrollDelta(args);
+  return withPage(driver, args.target, async (page) => {
+    const { x, y } = await page.scroll(anchor, { deltaX, deltaY });
+    return { x, y, deltaX, deltaY, target: target3(page.info) };
+  });
+}
+
 export async function hover(driver: BrowserDriver, args: { target?: TargetSelector; uid?: DriverUid; selector?: string }): Promise<{ hovered: true; x: number; y: number }> {
   return withPage(driver, args.target, async (page) => {
     const { x, y } = await page.hover(locatorOf(args));
@@ -635,14 +883,106 @@ export async function hover(driver: BrowserDriver, args: { target?: TargetSelect
   });
 }
 
+/** drag's `to`: exactly one of { uid } | { selector } | { x, y }, x and y together. Exported for
+ *  the unit tests, which pin the rule without a browser. */
+export function resolveDragTo(to: { uid?: DriverUid; selector?: string; x?: number; y?: number }): DragDestination {
+  const hasUid = to.uid !== undefined && to.uid !== null && to.uid !== ("" as unknown);
+  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 as number, y: to.y as number };
+  }
+  return locatorOf({ uid: to.uid, selector: to.selector });
+}
+
+/**
+ * drag's destination rule: EXACTLY one of `to` (where the drag ends) or `by` (how far it moves
+ * from the source point). Both is a contradiction and neither leaves nowhere to drag to, so both
+ * are refused rather than resolved by precedence — a caller who passed both meant one of them and
+ * silently picking is how the wrong widget gets dragged. `by` needs at least one of dx/dy; the
+ * other defaults to 0, so `by:{dx:40}` is a pure horizontal slider nudge. Exported for the tests.
+ */
+export function resolveDragDestination(args: {
+  to?: { uid?: DriverUid; selector?: string; x?: number; y?: number };
+  by?: { dx?: number; dy?: number };
+}): DragDestination {
+  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 as { dx?: number; dy?: number };
+    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 as { uid?: DriverUid; selector?: string; x?: number; y?: number });
+}
+
+/** Upper bound on drag's interpolated moves. 500 already exceeds what any per-frame-sampling DnD
+ *  library needs (a 60fps drag lasting 8s), and each step is a round-tripped CDP command, so an
+ *  accidental `steps: 100000` would otherwise wedge the call for minutes. Refused, not clamped. */
+const MAX_DRAG_STEPS = 500;
+
+/** drag's `steps`: an integer in [1, MAX_DRAG_STEPS], default 2 (the pre-1.8.0 midpoint +
+ *  destination sequence). Exported for the unit tests. */
+export function resolveDragSteps(steps?: number): number {
+  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;
+}
+
+/**
+ * drag's `mode`, plus the ONE backend gate in this file. mode:"html5" needs Capability
+ * "input.html5Drag", which only the Chrome driver declares (Chrome's Input.setInterceptDrags /
+ * dragIntercepted / dispatchDragEvent have no WebDriver BiDi equivalent). Per ADR-001 this is a
+ * PARAM-level gap, not a whole-tool one: `drag` stays in tools/list on Firefox because mouse mode
+ * works there, and asking for html5 on Firefox is a clear validation error — never a silent
+ * downgrade to mouse mode, which would report success for a drop that never happened.
+ * Exported for the unit tests.
+ */
+export function resolveDragMode(mode: string | undefined, capabilities: ReadonlySet<Capability>): "mouse" | "html5" {
+  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";
+}
+
 export async function drag(
   driver: BrowserDriver,
-  args: { target?: TargetSelector; from: { uid?: DriverUid; selector?: string }; to: { uid?: DriverUid; selector?: string } },
-): Promise<{ dragged: true; from: { x: number; y: number }; to: { x: number; y: number } }> {
-  if (!args.from || !args.to) throw new SharedToolError("drag requires { from } and { to }");
+  args: {
+    target?: TargetSelector;
+    from: { uid?: DriverUid; selector?: string };
+    to?: { uid?: DriverUid; selector?: string; x?: number; y?: number };
+    by?: { dx?: number; dy?: number };
+    mode?: "mouse" | "html5";
+    steps?: number;
+  },
+): Promise<{ dragged: true; mode: "mouse" | "html5"; steps: number; from: { x: number; y: number }; to: { x: number; y: number } }> {
+  if (!args.from) throw new SharedToolError("drag requires { from }");
+  const destination = resolveDragDestination(args);
+  const steps = resolveDragSteps(args.steps);
+  // Capability check BEFORE withPage: an unsupported mode must not claim a lease or open a socket.
+  const mode = resolveDragMode(args.mode, driver.capabilities);
   return withPage(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 };
   });
 }
 
@@ -775,8 +1115,9 @@ export async function handleDialog(
 
 /* ------------------------------------- registry ------------------------------------- */
 
-/** The 23 tools this file unifies, importable by both src/index.ts (Chrome) and
- *  src/firefox-tools.ts (Firefox). Each function is (driver, args) => Promise<result>. */
+/** The 24 tools this file unifies (23 pre-1.8.0, plus `scroll`, Track P1), importable by both
+ *  src/index.ts (Chrome) and src/firefox-tools.ts (Firefox). Each function is
+ *  (driver, args) => Promise<result>. */
 export const SHARED_TOOLS = {
   list_pages: listPages,
   new_page: newPage,
@@ -792,6 +1133,7 @@ export const SHARED_TOOLS = {
   click,
   hover,
   drag,
+  scroll,
   fill,
   fill_form: fillForm,
   type_text: typeText,