cdp-toolkit 3.2.0 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -29,6 +29,7 @@
29
29
  * function through script.callFunction and PARSE its text back into SnapshotNode[], which is
30
30
  * genuinely new integration work, not a reimplementation of the walker itself.
31
31
  */
32
+ import { keepFrontApp } from "../frontApp.ts";
32
33
  import { spawn } from "node:child_process";
33
34
  import { fileURLToPath } from "node:url";
34
35
  import { existsSync } from "node:fs";
@@ -39,7 +40,7 @@ import {
39
40
  type DragDestination, type DragOptions,
40
41
  type SetCookieParams,
41
42
  type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel,
42
- type MouseButtonOptions, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
43
+ type MouseButtonOptions, type RawMouseEvent, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
43
44
  type ScreenshotOptions, type ScreenshotResult, type ScrollOptions, type SnapshotNode, type UidStability,
44
45
  type BandConsumer, type CaptureDelivery,
45
46
  } from "../driver.ts";
@@ -59,7 +60,7 @@ import { takeStampedSnapshot } from "./snapshot.ts";
59
60
  import { selectRule, buildFulfillParams, effectiveAction } from "../tools/network_mock.ts";
60
61
  import type {
61
62
  BrowsingContextId, BrowsingContextInfo, BrowsingContextLocator, BrowsingContextReadinessState,
62
- BrowsingContextCaptureScreenshotParameters, ScriptSharedReference, ScriptRemoteValue, ScriptLocalValue,
63
+ BrowsingContextCaptureScreenshotParameters, BrowsingContextCreateParameters, ScriptSharedReference, ScriptRemoteValue, ScriptLocalValue,
63
64
  ScriptNodeRemoteValue, ScriptExceptionDetails, InputSourceActions, InputPointerSourceAction, InputKeySourceAction,
64
65
  InputWheelSourceAction, NetworkCookie,
65
66
  } from "./protocol.ts";
@@ -139,6 +140,10 @@ function mapBidiError(e: unknown): DriverError {
139
140
  if (code === "no such frame") return driverError("no-such-target", e.message);
140
141
  if (code === "invalid session id") return driverError("disconnected", e.message);
141
142
  if (code === "unsupported operation") return driverError("unsupported", e.message);
143
+ // A Firefox older than the one a capability was verified on answers a newer BiDi command with
144
+ // "unknown command". That is a capability gap, not a protocol fault: surface it as "unsupported"
145
+ // and name the version that has it (BIDI_CAPABILITY_MIN_FIREFOX).
146
+ if (code === "unknown command") return driverError("unsupported", `${e.message} (this Firefox predates that WebDriver BiDi command; see BIDI_CAPABILITY_MIN_FIREFOX for the version each capability needs)`);
142
147
  if (!code && /timed out/i.test(e.message)) return driverError("timeout", e.message);
143
148
  if (!code && /(disposed|not open|connection closed)/i.test(e.message)) return driverError("disconnected", e.message);
144
149
  // NS_ERROR_FILE_ACCESS_DENIED from browsingContext.navigate means the browser process was
@@ -291,6 +296,47 @@ const KEY_VALUES: Record<string, string> = {
291
296
  };
292
297
  const MODIFIER_VALUES: Record<string, string> = { shift: "\uE008", control: "\uE009", ctrl: "\uE009", alt: "\uE00A", meta: "\uE03D", cmd: "\uE03D", command: "\uE03D" };
293
298
  const BUTTON_CODES: Record<"left" | "right" | "middle", number> = { left: 0, middle: 1, right: 2 };
299
+ const RAW_MOUSE_SOURCE_ID = "cdp-raw-mouse";
300
+
301
+ /** Modifier names (Alt/Control/Meta/Shift, any case, plus the aliases pressKey takes) to WebDriver
302
+ * key values, in the order given. Unknown names are refused, never skipped. */
303
+ function modifierKeyValues(mods: readonly string[] | undefined): string[] {
304
+ const out: string[] = [];
305
+ for (const m of mods ?? []) {
306
+ const v = MODIFIER_VALUES[m.toLowerCase()];
307
+ if (v === undefined) throw driverError("page-error", `unknown modifier '${m}' (use Alt, Control, Meta, or Shift)`);
308
+ if (!out.includes(v)) out.push(v);
309
+ }
310
+ return out;
311
+ }
312
+
313
+ /**
314
+ * The input sources for pointer `actions` with `keys` held across them. With no keys it is the plain
315
+ * pointer source. With keys, a "key" source is TICK-ALIGNED with the pointer source in the same
316
+ * performActions call: [keyDown x k, pause x n, keyUp x k] against [pause x k, ...actions, pause x k],
317
+ * so every modifier is down before the first pointer action and released after the last. This is the
318
+ * shape measured on Firefox 160.0 (a lone key source or a misaligned one did not reach the click).
319
+ */
320
+ function modifierChord(pointerId: string, actions: InputPointerSourceAction[], keys: readonly string[]): InputSourceActions[] {
321
+ const pointer: InputPointerSourceAction[] = actions;
322
+ if (keys.length === 0) return [{ type: "pointer", id: pointerId, actions: pointer }];
323
+ const k = keys.length;
324
+ const pause = (): { type: "pause" } => ({ type: "pause" });
325
+ const keyActions: InputKeySourceAction[] = [
326
+ ...keys.map((v): InputKeySourceAction => ({ type: "keyDown", value: v })),
327
+ ...pointer.map(pause),
328
+ ...[...keys].reverse().map((v): InputKeySourceAction => ({ type: "keyUp", value: v })),
329
+ ];
330
+ const pointerActions: InputPointerSourceAction[] = [
331
+ ...Array.from({ length: k }, pause),
332
+ ...pointer,
333
+ ...Array.from({ length: k }, pause),
334
+ ];
335
+ return [
336
+ { type: "key", id: "cdp-keyboard", actions: keyActions },
337
+ { type: "pointer", id: pointerId, actions: pointerActions },
338
+ ];
339
+ }
294
340
 
295
341
  /** Same scroll-settle technique as cdp/driver.ts's ARM_SCROLL_SETTLE_WATCH / awaitScrollSettle,
296
342
  * see that file's doc comment for the full rationale: a capture-phase 'scroll' listener on
@@ -303,8 +349,8 @@ const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}
303
349
  /**
304
350
  * Firefox 153 capabilities. Only what was empirically verified is declared: emulate.deviceMetrics
305
351
  * (browsingContext.setViewport) and the userAgent path (universal, no capability token) both work.
306
- * emulate.mediaFeatures, emulate.cpuThrottling, emulate.networkConditions, trace.performance,
307
- * heap.snapshot, audit.lighthouse, input.insertTextAtomic and snapshot.accessibilityTree are all
352
+ * emulate.cpuThrottling, trace.performance (emulate.mediaFeatures and emulate.networkConditions were
353
+ * added later at Firefox 160, see BIDI_CAPABILITY_MIN_FIREFOX), heap.snapshot, audit.lighthouse, input.insertTextAtomic and snapshot.accessibilityTree are all
308
354
  * deliberately absent, several because Firefox 153 does not implement the underlying BiDi command
309
355
  * at all (see protocol.ts's "Firefox 153: not implemented" tags), the rest because this driver has
310
356
  * no accessibility-tree source or CPU-multiplier primitive to offer. locate.xpath rides
@@ -323,8 +369,13 @@ const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}
323
369
  * screenshot.renderSize IS declared, and it is the one screenshot capability here that is not a
324
370
  * Chrome-only gap: it rides browsingContext.setViewport, the very command emulate.deviceMetrics
325
371
  * above already rides, applied for one capture and undone afterwards. Refusing it would be dishonest
326
- * in the opposite direction — claiming a missing primitive this driver demonstrably has. Contrast
327
- * screenshot.scale, absent because captureScreenshot genuinely has no scale parameter.
372
+ * in the opposite direction — claiming a missing primitive this driver demonstrably has.
373
+ * screenshot.scale (Firefox >= 160, BIDI_CAPABILITY_MIN_FIREFOX) is the same trick one step on:
374
+ * captureScreenshot itself still has no scale parameter, but setViewport({devicePixelRatio}) with NO
375
+ * viewport key multiplies the capture and leaves the layout viewport alone (measured on 160.0:
376
+ * a 1366x683 capture became 2732x1366 at ratio 2, innerWidth/innerHeight unchanged), so scale rides
377
+ * that for one capture and undoes it, like renderSize. network.responseBodyPostHoc (Firefox >= 160)
378
+ * is armed per SESSION, see armPostHocBodies.
328
379
  * screenshot.tile stays undeclared, but no longer for an unmeasured reason: live-fired against
329
380
  * Firefox 153.0.3, a 20,000px-tall page captured with take_screenshot --fullPage true came back
330
381
  * as a single 1366x20000 PNG at scale 1, verified complete top-to-bottom — no clip, no bands.
@@ -333,8 +384,108 @@ const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}
333
384
  * no gap here to close. It stays undeclared because it would advertise a forced-tiling primitive
334
385
  * this backend has never needed, not because band-tiling behavior is untested.
335
386
  */
387
+ /**
388
+ * Capabilities verified on a Firefox NEWER than 153, keyed to the first major version they were
389
+ * measured on. They are declared in BIDI_CAPABILITIES (tool listing is static: capabilities.ts reads
390
+ * this set without opening a socket), and each method that rides one calls requireFirefox(conn,
391
+ * token) before touching browser state, so an older Firefox gets an "unsupported" DriverError that
392
+ * names the version instead of a half-applied change or a raw "unknown command".
393
+ *
394
+ * input.raw (dispatch_mouse) and input.modifierClick (click with modifiers), measured on headless
395
+ * Firefox 160.0: a pointerDown issued in one input.performActions call stays held for a pointerUp in
396
+ * a LATER call that reuses the same pointer source id (page saw mousedown, then mouseup+click), so
397
+ * one raw event per call works; and a modifier chord works when a "key" source (keyDown of the
398
+ * modifier, pauses, keyUp) is TICK-ALIGNED with the pointer source in ONE call (page saw
399
+ * shiftKey/ctrlKey/altKey/metaKey on the click). input.html5Drag is NOT declared: on 160.0 a
400
+ * pointer drag starts a real drag session (dragstart, dragenter, dragover reach the page) but the
401
+ * session never completes under BiDi input (no drop, no dragend, no mouseup, even after a pause or
402
+ * a second performActions call), so a drag cannot be delivered; see test/bidi-input-ff160.test.ts.
403
+ *
404
+ * browser.downloads (160): browser.setDownloadBehavior {type:"allowed", destinationFolder} plus the
405
+ * browsingContext.downloadWillBegin/downloadEnd events, measured on headless Firefox 160.0 — the
406
+ * file landed in the folder, downloadEnd carried status "complete" and its filepath, and
407
+ * `downloadBehavior: null` put a later download back in the profile's own download dir. Drives
408
+ * wait_for_download through ../bidi-browser-tools.ts.
409
+ * browser.permissions (160): permissions.setPermission {descriptor, state, origin}, measured on
410
+ * Firefox 160.0 — navigator.permissions.query followed granted/denied/prompt. Drives
411
+ * grant_permissions through ../bidi-browser-tools.ts, which also documents the Chrome asymmetries.
412
+ */
413
+ export const BIDI_CAPABILITY_MIN_FIREFOX: Readonly<Partial<Record<Capability, number>>> = {
414
+ "browser.downloads": 160,
415
+ "browser.permissions": 160,
416
+ "emulate.mediaFeatures": 160,
417
+ "emulate.networkConditions": 160,
418
+ "input.raw": 160,
419
+ "input.modifierClick": 160,
420
+ "network.responseBodyPostHoc": 160,
421
+ "screenshot.scale": 160,
422
+ };
423
+
424
+ /** Firefox major version from session.new's capabilities.browserVersion (e.g. "160.0" -> 160).
425
+ * undefined when the session reported none (a stub connection in tests): treated as new enough. */
426
+ export function firefoxMajor(conn: { capabilities: unknown }): number | undefined {
427
+ const v = (conn.capabilities as { browserVersion?: unknown } | undefined)?.browserVersion;
428
+ if (typeof v !== "string") return undefined;
429
+ const major = Number.parseInt(v, 10);
430
+ return Number.isFinite(major) ? major : undefined;
431
+ }
432
+
433
+ /** Throw "unsupported" when `token` needs a newer Firefox than the one this session is on. */
434
+ export function requireFirefox(conn: { capabilities: unknown }, token: Capability): void {
435
+ const min = BIDI_CAPABILITY_MIN_FIREFOX[token];
436
+ if (min === undefined) return;
437
+ const major = firefoxMajor(conn);
438
+ if (major !== undefined && major < min) {
439
+ const v = (conn.capabilities as { browserVersion?: string }).browserVersion;
440
+ throw driverError("unsupported", `${token} needs Firefox ${min} or newer; this Firefox is ${v}.`);
441
+ }
442
+ }
443
+
444
+ /**
445
+ * Largest single response body the session-wide collector keeps, in bytes. maxEncodedDataSize is a
446
+ * PER-RESPONSE cap (measured on Firefox 160.0: cap 10 dropped a 20-byte body; cap 2,000,000 kept every
447
+ * 1 MB body). A larger body is simply not retained and reads back as "no such network data". The
448
+ * TOTAL is Firefox's own and not ours to set: with a 2 MB cap or a 20 MB cap alike, 260 sequential
449
+ * 1 MB responses left the oldest ~60 answering "unavailable network data" (evicted) and the newest
450
+ * ~160 readable, so the browser's own budget is on the order of 100-200 MB regardless of this number
451
+ * (no pref for it was found; attach mode gets the browser default). This number only bounds how
452
+ * much of that budget one response can take.
453
+ */
454
+ const POST_HOC_BODY_MAX_BYTES = 2 * 1024 * 1024;
455
+
456
+ /**
457
+ * Arm the ONE session-wide response collector that makes network.responseBodyPostHoc true.
458
+ *
459
+ * WHY HERE. network.addDataCollector is scoped to the BiDi SESSION, and it only retains bodies of
460
+ * requests that start after it exists. This toolkit shares ONE real session per browser (the holder
461
+ * path of getConnection, which the mux daemon reaches through hostFirefoxMux), so the place that
462
+ * covers every client, every tab and every request since the session began is the moment that real
463
+ * session is created: no `contexts`/`userContexts`, so tabs opened later are covered too. A JOINED
464
+ * connection must NOT arm another: its commands are forwarded to the same upstream session and a
465
+ * second collector would double-retain every body. Best-effort and silent on a Firefox older than
466
+ * 160 (the capability is version-gated, see requireFirefox): a failed arm leaves reads answering
467
+ * "no such network data" rather than failing the connection the caller asked for.
468
+ */
469
+ async function armPostHocBodies(conn: BidiConnection): Promise<void> {
470
+ // Opt-out for an everyday Firefox where retaining response bodies is unwanted. With it off, a
471
+ // body is readable only after startBodyCapture, and an unarmed read is the "no such network
472
+ // data" DriverError, the same as on a Firefox older than 160.
473
+ if (process.env.CDP_FIREFOX_BODY_COLLECTOR === "off") return;
474
+ try {
475
+ requireFirefox(conn, "network.responseBodyPostHoc");
476
+ } catch {
477
+ return;
478
+ }
479
+ try {
480
+ await conn.send("network.addDataCollector", { dataTypes: ["response"], maxEncodedDataSize: POST_HOC_BODY_MAX_BYTES });
481
+ } catch (e) {
482
+ console.error(`[cdp-toolkit] firefox response-body collector not armed: ${e instanceof Error ? e.message : String(e)}`);
483
+ }
484
+ }
485
+
336
486
  const BIDI_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
337
487
  "emulate.deviceMetrics", "screenshot.fullPage", "screenshot.element", "screenshot.renderSize", "network.intercept", "locate.xpath",
488
+ ...(Object.keys(BIDI_CAPABILITY_MIN_FIREFOX) as Capability[]),
338
489
  ]);
339
490
 
340
491
  /* --------------------------------- module-scope session memoization --------------------------------- */
@@ -381,6 +532,9 @@ const connecting = new Map<string, Promise<BidiConnection>>();
381
532
  const sessionEpochs = new Map<string, number>();
382
533
  // Reverse lookup so resolveContext (which only has a BidiConnection) can find its endpoint's epoch.
383
534
  const connEndpoints = new WeakMap<BidiConnection, string>();
535
+ // Per-endpoint cleanup BidiBrowserDriver.dispose() runs on the live connection before session.end
536
+ // (see setDisposeHook). Keyed by endpoint, then by the registering feature.
537
+ const disposeHooks = new Map<string, Map<string, (conn: BidiConnection) => Promise<void>>>();
384
538
 
385
539
  function bumpEpoch(endpoint: string, conn: BidiConnection): void {
386
540
  sessionEpochs.set(endpoint, (sessionEpochs.get(endpoint) ?? 0) + 1);
@@ -718,6 +872,8 @@ async function getConnection(endpoint: string, timeoutMs?: number, attached = fa
718
872
  }
719
873
  connections.set(endpoint, conn);
720
874
  bumpEpoch(endpoint, conn);
875
+ // We own the real session: arm the post-hoc body collector on it (never on a joined one).
876
+ await armPostHocBodies(conn);
721
877
  // We are the HOLDER. Front our one real session with a loopback BiDi mux and advertise it in
722
878
  // the slot record, so any other process that wants this Firefox JOINS us instead of being told
723
879
  // the slot is busy. Strictly additive and strictly best-effort: any failure here leaves a
@@ -1058,26 +1214,41 @@ class BidiPageDriver implements PageDriver {
1058
1214
  await this.performActions([{ type: "pointer", id: "cdp-mouse", actions: [{ type: "pointerMove", x, y, duration: 0 }] }]);
1059
1215
  return { x, y };
1060
1216
  }
1061
- // modifiers is new in 1.8.0 (Track P1). Chrome expresses it as a bitmask on the same
1062
- // mousePressed/mouseReleased events (cdp/driver.ts's inputModifierBits); WebDriver BiDi has no
1063
- // equivalent field on a pointerDown/pointerUp action; a modifier chord instead requires a SECOND
1064
- // "key" input source ticked in lockstep with the pointer source across the same performActions
1065
- // call, which the spec explicitly permits skipping ("throw a clear error when modifiers are
1066
- // passed on firefox" — see cdp-toolkit's 1.8.0 spec, Track P1 §3) and this driver was not
1067
- // verified against real Firefox for this pass, so it throws "unsupported" rather than guess at
1068
- // untested tick-synchronization semantics.
1217
+ // modifiers (1.8.0 Track P1). Chrome expresses it as a bitmask on the same mousePressed/mouseReleased
1218
+ // events (cdp/driver.ts's inputModifierBits); BiDi has no such field on pointerDown/pointerUp, so a
1219
+ // chord is a SECOND "key" source ticked in lockstep with the pointer source inside ONE
1220
+ // performActions call (modifierChord below). Measured on Firefox 160.0 (shift+click saw
1221
+ // shiftKey=true); an older Firefox is refused by requireFirefox("input.modifierClick").
1069
1222
  async click(loc: ElementLocator, opts?: MouseButtonOptions): Promise<{ x: number; y: number }> {
1070
- if (opts?.modifiers && opts.modifiers.length > 0) {
1071
- throw driverError("unsupported", "click: 'modifiers' is not supported by the Firefox/BiDi driver; omit 'modifiers' or use --browser chrome for a modifier click.");
1072
- }
1223
+ const hasModifiers = !!opts?.modifiers && opts.modifiers.length > 0;
1224
+ if (hasModifiers) requireFirefox(this.conn, "input.modifierClick");
1225
+ const keys = modifierKeyValues(opts?.modifiers);
1073
1226
  const ref = await resolveElementLocator(this.conn, this.contextId, loc);
1074
1227
  const { x, y } = await this.centerOf(ref);
1075
1228
  const button = BUTTON_CODES[opts?.button ?? "left"];
1076
1229
  const actions: InputPointerSourceAction[] = [{ type: "pointerMove", x, y, duration: 0 }];
1077
1230
  for (let i = 0; i < (opts?.clickCount ?? 1); i++) actions.push({ type: "pointerDown", button }, { type: "pointerUp", button });
1078
- await this.performActions([{ type: "pointer", id: "cdp-mouse", actions }]);
1231
+ await this.performActions(modifierChord("cdp-mouse", actions, keys));
1079
1232
  return { x, y };
1080
1233
  }
1234
+ // dispatch_mouse on Firefox (capability "input.raw", 160+): ONE raw pointer event per call. BiDi's
1235
+ // pointer source is a virtual device with session-lifetime state, so a "down" in one call stays held
1236
+ // for an "up" in a later call as long as the source id is the same: RAW_MOUSE_SOURCE_ID is a constant
1237
+ // for that reason (and distinct from click/drag's "cdp-mouse", which always finish their own press).
1238
+ // The state lives in the shared BiDi session (bidi/mux.ts), not in this driver instance, so it
1239
+ // survives the per-tool-call driver acquisition. Unlike CDP, BiDi has no coordinate-less event: every
1240
+ // action is a pointerMove to (x,y) first, so a "down"/"up" also emits a mousemove if the pointer
1241
+ // was elsewhere. clickCount is not a BiDi field (the browser derives click counts from timing), so
1242
+ // it is ignored here.
1243
+ async dispatchMouse(event: RawMouseEvent): Promise<void> {
1244
+ requireFirefox(this.conn, "input.raw");
1245
+ const keys = modifierKeyValues(event.modifiers);
1246
+ const button = BUTTON_CODES[event.button ?? "left"];
1247
+ const actions: InputPointerSourceAction[] = [{ type: "pointerMove", x: event.x, y: event.y, duration: 0 }];
1248
+ if (event.action === "down") actions.push({ type: "pointerDown", button });
1249
+ else if (event.action === "up") actions.push({ type: "pointerUp", button });
1250
+ await this.performActions(modifierChord(RAW_MOUSE_SOURCE_ID, actions, keys));
1251
+ }
1081
1252
  // 1.8.0 Track P1: BiDi's "wheel" input source (a distinct source type from "pointer"/"key")
1082
1253
  // carries x/y/deltaX/deltaY directly on its one "scroll" action — no tick synchronization with
1083
1254
  // another source needed, unlike click's modifiers above, which is what makes this tractable.
@@ -1190,8 +1361,12 @@ class BidiPageDriver implements PageDriver {
1190
1361
  await this.callFunctionValue(BidiPageDriver.INSERT_TEXT_SOURCE, [value, false], ref);
1191
1362
  return;
1192
1363
  }
1193
- const clear = "function(){this.focus&&this.focus();if('value' in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}}";
1194
- await this.callFunctionValue(clear, [], ref);
1364
+ // Refuse a disabled or read-only field before the clear, as the Chrome driver does.
1365
+ const clear = "function(){if(this.disabled||this.readOnly)return this.disabled?'disabled':'readonly';this.focus&&this.focus();if('value' in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}return 'ok';}";
1366
+ const state = await this.callFunctionValue(clear, [], ref);
1367
+ if (state === "disabled" || state === "readonly") {
1368
+ throw driverError("page-error", `cannot fill a ${state} field: it was left unchanged`);
1369
+ }
1195
1370
  await this.sendKeys(value);
1196
1371
  }
1197
1372
  async typeText(loc: ElementLocator, text: string): Promise<void> {
@@ -1245,13 +1420,28 @@ class BidiPageDriver implements PageDriver {
1245
1420
  opts?.renderWidth !== undefined && opts?.renderHeight !== undefined
1246
1421
  ? { width: opts.renderWidth, height: opts.renderHeight }
1247
1422
  : undefined;
1248
- if (!renderSize) return this.capture(opts);
1423
+ const scale = opts?.scale !== undefined && opts.scale !== 1 ? opts.scale : undefined;
1424
+ if (!renderSize && scale === undefined) return this.capture(opts);
1425
+ if (scale !== undefined) requireFirefox(this.conn, "screenshot.scale");
1249
1426
  const previous = await readViewportRecord(this.browser.scheme, this.contextId);
1427
+ // BiDi's devicePixelRatio REPLACES the page's ratio, where Chrome's clip.scale MULTIPLIES it, so
1428
+ // a scale of 2 on a ratio-2 display must send 4 or it would be a silent no-op. The base is the
1429
+ // ratio this toolkit last emulated, else the live window.devicePixelRatio.
1430
+ let dprOverride: number | undefined;
1431
+ if (scale !== undefined) {
1432
+ const base = previous?.deviceScaleFactor ?? Number(await this.evaluate("window.devicePixelRatio").catch(() => 1));
1433
+ dprOverride = (Number.isFinite(base) && base > 0 ? base : 1) * scale;
1434
+ }
1250
1435
  try {
1251
- // devicePixelRatio is deliberately not sent: this changes the render SIZE, and omitting the
1252
- // field leaves whatever ratio an earlier emulate set in place (the CDP path inherits it the
1253
- // same way).
1254
- await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: renderSize.width, height: renderSize.height } });
1436
+ // With a render size only, devicePixelRatio is deliberately not sent: that changes the render
1437
+ // SIZE, and omitting the field leaves whatever ratio an earlier emulate set in place (the CDP
1438
+ // path inherits it the same way). With a scale, the ratio is sent and, when no render size is
1439
+ // asked for, so is no viewport at all (measured: the layout viewport is left as it was).
1440
+ await this.conn.send("browsingContext.setViewport", {
1441
+ context: this.contextId,
1442
+ ...(renderSize ? { viewport: { width: renderSize.width, height: renderSize.height } } : {}),
1443
+ ...(dprOverride !== undefined ? { devicePixelRatio: dprOverride } : {}),
1444
+ });
1255
1445
  } catch (e) {
1256
1446
  throw mapBidiError(e);
1257
1447
  }
@@ -1270,20 +1460,33 @@ class BidiPageDriver implements PageDriver {
1270
1460
  await this.conn.send("browsingContext.setViewport", {
1271
1461
  context: this.contextId,
1272
1462
  viewport: { width: previous.width, height: previous.height },
1273
- ...(previous.deviceScaleFactor != null ? { devicePixelRatio: previous.deviceScaleFactor } : {}),
1463
+ // A scaled capture changed the ratio, so it is always put back: to the recorded one, or to
1464
+ // null (the real display's) when no emulated ratio was ever recorded.
1465
+ ...(previous.deviceScaleFactor != null ? { devicePixelRatio: previous.deviceScaleFactor } : scale !== undefined ? { devicePixelRatio: null } : {}),
1274
1466
  });
1275
1467
  } else {
1276
- await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null });
1468
+ await this.conn.send("browsingContext.setViewport", {
1469
+ context: this.contextId,
1470
+ ...(renderSize ? { viewport: null } : {}),
1471
+ ...(scale !== undefined ? { devicePixelRatio: null } : {}),
1472
+ });
1277
1473
  }
1278
1474
  } catch (e) {
1279
1475
  restoreError = e instanceof Error ? e.message : String(e);
1280
1476
  }
1281
1477
  if (!shot) {
1282
1478
  if (restoreError !== undefined && captureError instanceof Error) {
1283
- captureError.message = `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`;
1479
+ captureError.message = renderSize
1480
+ ? `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`
1481
+ : `${captureError.message} (and restoring the device pixel ratio failed too, the tab may still be emulated at ratio ${dprOverride}: ${restoreError})`;
1284
1482
  }
1285
1483
  throw captureError;
1286
1484
  }
1485
+ if (!renderSize) {
1486
+ // Scale-only capture: no render size to report, but a failed restore is still never swallowed.
1487
+ if (restoreError !== undefined) throw driverError("page-error", `screenshot captured, but restoring the device pixel ratio failed (the tab may still be emulated at ratio ${dprOverride}): ${restoreError}`);
1488
+ return shot;
1489
+ }
1287
1490
  const result: ScreenshotResult = { ...shot, renderSize, renderRestored: restoreError === undefined };
1288
1491
  if (restoreError !== undefined) result.renderRestoreError = restoreError;
1289
1492
  return result;
@@ -1291,18 +1494,8 @@ class BidiPageDriver implements PageDriver {
1291
1494
  /** The capture itself, with no viewport emulation of its own. Split out so screenshot()'s restore
1292
1495
  * wraps EVERY way this can fail, the throwing paths included. */
1293
1496
  private async capture(opts?: ScreenshotOptions): Promise<ScreenshotResult> {
1294
- // ADR-001 param-level gap, same shape as drag's mode:"html5" (see resolveDragMode in
1295
- // ../shared-tools.ts): browsingContext.captureScreenshot has NO scale parameter — its only
1296
- // knobs are origin, format and clip — so a scale asked for here is refused outright rather
1297
- // than silently captured at 1x, which would hand back an image the caller never asked for.
1298
- if (opts?.scale !== undefined && opts.scale !== 1) {
1299
- throw driverError(
1300
- "unsupported",
1301
- `screenshot scale ${opts.scale} is not supported by this backend (WebDriver BiDi's ` +
1302
- "browsingContext.captureScreenshot has no scale parameter). Call emulate with " +
1303
- `deviceScaleFactor:${opts.scale} first and capture at scale 1, or use --browser chrome.`,
1304
- );
1305
- }
1497
+ // `scale` never reaches here: screenshot() applies it as a one-capture devicePixelRatio
1498
+ // override (captureScreenshot itself still has no scale parameter) and puts it back.
1306
1499
  // Same ADR-001 param-level shape, but now a measured non-gap rather than an unmeasured one.
1307
1500
  // Live-fired against Firefox 153.0.3: a 20,000px-tall page captured with take_screenshot
1308
1501
  // --fullPage true came back as one 1366x20000 PNG at scale 1, verified complete top-to-bottom,
@@ -1334,9 +1527,10 @@ class BidiPageDriver implements PageDriver {
1334
1527
  throw mapBidiError(e);
1335
1528
  }
1336
1529
  }
1337
- // Only userAgent and width/height/deviceScaleFactor are applied: mediaFeatures, cpuThrottling
1338
- // and networkConditions are not in BIDI_CAPABILITIES (see its comment) and this method never
1339
- // claims them. `mobile` has no BiDi viewport-emulation equivalent and is silently ignored,
1530
+ // Applied: userAgent, width/height/deviceScaleFactor, and (Firefox 160+, BIDI_CAPABILITY_MIN_FIREFOX)
1531
+ // mediaFeatures and offline-only networkConditions. cpuThrottling is not in BIDI_CAPABILITIES and
1532
+ // this method never claims it; a media TYPE and a throttled network are refused as "unsupported".
1533
+ // `mobile` has no BiDi viewport-emulation equivalent and is silently ignored,
1340
1534
  // a real parity gap noted in the footer rather than smoothed over.
1341
1535
  async emulate(opts: EmulationOptions): Promise<{ applied: string[] }> {
1342
1536
  if (opts.clearOverrides) {
@@ -1356,11 +1550,29 @@ class BidiPageDriver implements PageDriver {
1356
1550
  // no "set-then-clear" workaround needed; left as it was.
1357
1551
  await this.conn.send("emulation.setUserAgentOverride", { userAgent: null, contexts: [this.contextId] }).catch(() => undefined);
1358
1552
  await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null, devicePixelRatio: null }).catch(() => undefined);
1553
+ // Best-effort like the two above: a Firefox older than 160 has neither command, and then
1554
+ // there is nothing of ours to clear. The overrides are session-scoped (one shared BiDi
1555
+ // session per browser, see mux.ts), so this clears what ANY driver instance on this browser set.
1556
+ await this.conn.send("emulation.setMediaFeaturesOverride", { features: null, contexts: [this.contextId] }).catch(() => undefined);
1557
+ await this.conn.send("emulation.setNetworkConditions", { networkConditions: null, contexts: [this.contextId] }).catch(() => undefined);
1359
1558
  // No override of ours left to put back: a render-size capture should restore to null.
1360
1559
  await clearViewportRecord(this.browser.scheme, this.contextId);
1361
1560
  return { applied: [] };
1362
1561
  }
1363
1562
  const applied: string[] = [];
1563
+ // Refusals first, before ANY browser state changes, so a refused call never half-applies.
1564
+ if (opts.media != null && opts.media !== "") {
1565
+ throw driverError("unsupported", `emulate media "${opts.media}": WebDriver BiDi's emulation.setMediaFeaturesOverride takes media features (prefers-color-scheme, ...) but has no print/screen media-type override. Use mediaFeatures, or --browser chrome for media type emulation.`);
1566
+ }
1567
+ const net = opts.networkConditions;
1568
+ if (net != null) {
1569
+ const throttled = (net.latency ?? 0) > 0 || (net.downloadThroughput ?? -1) >= 0 || (net.uploadThroughput ?? -1) >= 0;
1570
+ if (throttled) {
1571
+ throw driverError("unsupported", "emulate networkConditions: Firefox only emulates offline (emulation.setNetworkConditions has the single type \"offline\"); latency and download/upload throughput throttling are not available. Pass only {offline:true|false}, or use --browser chrome.");
1572
+ }
1573
+ requireFirefox(this.conn, "emulate.networkConditions");
1574
+ }
1575
+ if (opts.mediaFeatures != null) requireFirefox(this.conn, "emulate.mediaFeatures");
1364
1576
  try {
1365
1577
  if (opts.width != null && opts.height != null) {
1366
1578
  await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: opts.width, height: opts.height }, ...(opts.deviceScaleFactor != null ? { devicePixelRatio: opts.deviceScaleFactor } : {}) });
@@ -1377,6 +1589,22 @@ class BidiPageDriver implements PageDriver {
1377
1589
  await this.conn.send("emulation.setUserAgentOverride", { userAgent: opts.userAgent, contexts: [this.contextId] });
1378
1590
  applied.push("userAgent");
1379
1591
  }
1592
+ if (opts.mediaFeatures != null) {
1593
+ // BiDi takes an OBJECT {name: value}; null resets (an empty list mirrors Chrome's "clear").
1594
+ const features = Object.fromEntries(opts.mediaFeatures.map((f) => [f.name, f.value]));
1595
+ await this.conn.send("emulation.setMediaFeaturesOverride", {
1596
+ features: opts.mediaFeatures.length > 0 ? features : null,
1597
+ contexts: [this.contextId],
1598
+ });
1599
+ applied.push("mediaFeatures");
1600
+ }
1601
+ if (net != null) {
1602
+ await this.conn.send("emulation.setNetworkConditions", {
1603
+ networkConditions: net.offline ? { type: "offline" } : null,
1604
+ contexts: [this.contextId],
1605
+ });
1606
+ applied.push("networkConditions");
1607
+ }
1380
1608
  } catch (e) {
1381
1609
  throw mapBidiError(e);
1382
1610
  }
@@ -1559,11 +1787,29 @@ class BidiPageDriver implements PageDriver {
1559
1787
  };
1560
1788
  }
1561
1789
  async getResponseBody(requestId: string): Promise<{ body: string; base64Encoded: boolean }> {
1562
- if (!this.bodyCollector) throw driverError("unsupported", "getResponseBody: call startBodyCapture() first (network.responseBodyPostHoc is not supported)");
1790
+ // On Firefox >= 160 the session-wide collector (armPostHocBodies) already holds the body, so no
1791
+ // collector id is passed and startBodyCapture is optional. An older Firefox has no such collector:
1792
+ // only a body armed through this page's own startBodyCapture is readable there.
1793
+ let collector: string | undefined;
1563
1794
  try {
1564
- const { bytes } = await this.conn.send("network.getData", { dataType: "response", collector: this.bodyCollector, request: requestId });
1795
+ requireFirefox(this.conn, "network.responseBodyPostHoc");
1796
+ } catch (e) {
1797
+ if (!this.bodyCollector) {
1798
+ throw driverError("unsupported", `${(e as Error).message} Call startBodyCapture() before the request to read its body on this Firefox.`);
1799
+ }
1800
+ collector = this.bodyCollector;
1801
+ }
1802
+ try {
1803
+ const { bytes } = await this.conn.send("network.getData", { dataType: "response", request: requestId, ...(collector ? { collector } : {}) });
1565
1804
  return bytes.type === "base64" ? { body: bytes.value, base64Encoded: true } : { body: bytes.value, base64Encoded: false };
1566
1805
  } catch (e) {
1806
+ // Two distinct BiDi answers, measured on Firefox 160.0. Never surface either as an empty body.
1807
+ if (e instanceof BidiError && e.code === "unavailable network data") {
1808
+ throw driverError("page-error", `getResponseBody: the body of request ${requestId} was collected but has been evicted (Firefox keeps only a bounded recent window of response bodies, on the order of 100-200 MB). Re-issue the request, then read it sooner.`);
1809
+ }
1810
+ if (e instanceof BidiError && e.code === "no such network data") {
1811
+ throw driverError("page-error", `getResponseBody: no body is held for request ${requestId}. Firefox cannot say which of these applies: the id is wrong, the request started before this Firefox session did, the response was larger than ${POST_HOC_BODY_MAX_BYTES} bytes (not retained), or it has no body.`);
1812
+ }
1567
1813
  throw mapBidiError(e);
1568
1814
  }
1569
1815
  }
@@ -1617,6 +1863,15 @@ class BidiPageDriver implements PageDriver {
1617
1863
  }
1618
1864
  }
1619
1865
 
1866
+ /**
1867
+ * browsingContext.create params for new_page / claim_page. background:true unless focus is
1868
+ * explicitly true: per the BiDi spec a context created without it becomes the active tab, which
1869
+ * switches the user's visible tab. Exported for the unit test (no fake BiDi transport exists).
1870
+ */
1871
+ export function bidiCreateTabParams(opts?: { focus?: boolean }): BrowsingContextCreateParameters {
1872
+ return { type: "tab", background: opts?.focus !== true };
1873
+ }
1874
+
1620
1875
  /* --------------------------------- BrowserDriver --------------------------------- */
1621
1876
  class BidiBrowserDriver implements BrowserDriver {
1622
1877
  readonly scheme = "bidi";
@@ -1637,10 +1892,11 @@ class BidiBrowserDriver implements BrowserDriver {
1637
1892
  conn.release();
1638
1893
  }
1639
1894
  }
1640
- async newPage(url?: string): Promise<PageInfo> {
1895
+ async newPage(url?: string, opts?: { focus?: boolean }): Promise<PageInfo> {
1641
1896
  const conn = await getConnection(this.endpoint, this.timeoutMs, this.attached);
1642
1897
  try {
1643
- const { context } = await conn.send("browsingContext.create", { type: "tab" }).catch((e) => { throw mapBidiError(e); });
1898
+ const create = () => conn.send("browsingContext.create", bidiCreateTabParams(opts)).catch((e) => { throw mapBidiError(e); });
1899
+ const { context } = opts?.focus === true ? await create() : await keepFrontApp(create);
1644
1900
  // Established fact: navigating the default about:home context to a data: URL is rejected,
1645
1901
  // so a fresh context is created here FIRST and only then navigated, never reused as-is.
1646
1902
  if (url) await conn.send("browsingContext.navigate", { context, url, wait: "complete" }).catch((e) => { throw mapBidiError(e); });
@@ -1652,7 +1908,7 @@ class BidiBrowserDriver implements BrowserDriver {
1652
1908
  async closePage(id: string): Promise<{ success: boolean }> {
1653
1909
  const conn = await getConnection(this.endpoint, this.timeoutMs, this.attached);
1654
1910
  try {
1655
- await conn.send("browsingContext.close", { context: id }).catch((e) => { throw mapBidiError(e); });
1911
+ await keepFrontApp(() => conn.send("browsingContext.close", { context: id }).catch((e) => { throw mapBidiError(e); }));
1656
1912
  return { success: true };
1657
1913
  } finally {
1658
1914
  conn.release();
@@ -1742,7 +1998,43 @@ class BidiBrowserDriver implements BrowserDriver {
1742
1998
  }
1743
1999
  }
1744
2000
 
2001
+ /**
2002
+ * Run `fn` against this endpoint's live BiDi connection, for BROWSER-scoped commands that have
2003
+ * no page to hang off (browser.setDownloadBehavior, permissions.setPermission). Retains and
2004
+ * releases a holder exactly like page() does. NOT a lease gate: callers resolve their target
2005
+ * through page() first (resolveContext is the gate), then come here for the browser-wide work.
2006
+ */
2007
+ async withBrowserConnection<T>(fn: (conn: BidiConnection) => Promise<T>): Promise<T> {
2008
+ const conn = await getConnection(this.endpoint, this.timeoutMs, this.attached);
2009
+ try {
2010
+ return await fn(conn);
2011
+ } finally {
2012
+ conn.release();
2013
+ }
2014
+ }
2015
+
2016
+ /**
2017
+ * Register cleanup that must run against the LIVE connection before dispose() ends the session —
2018
+ * browser state this process changed that would otherwise outlive it (a download redirect left
2019
+ * armed, a permission grant that Firefox persists in the profile). Keyed by `key` so re-registering
2020
+ * replaces rather than stacks. Hooks are best-effort and run once.
2021
+ */
2022
+ setDisposeHook(key: string, hook: ((conn: BidiConnection) => Promise<void>) | undefined): void {
2023
+ let hooks = disposeHooks.get(this.endpoint);
2024
+ if (!hooks) { hooks = new Map(); disposeHooks.set(this.endpoint, hooks); }
2025
+ if (hook) hooks.set(key, hook);
2026
+ else hooks.delete(key);
2027
+ }
2028
+
1745
2029
  async dispose(): Promise<void> {
2030
+ // Browser-state restores first, while the connection (and, for a mux holder, every joiner's
2031
+ // shared session) is still alive.
2032
+ const hooks = disposeHooks.get(this.endpoint);
2033
+ disposeHooks.delete(this.endpoint);
2034
+ const live = connections.get(this.endpoint);
2035
+ if (hooks && live) {
2036
+ for (const hook of hooks.values()) await hook(live).catch(() => undefined);
2037
+ }
1746
2038
  for (const key of [...bidiBeaconScripts.keys()]) {
1747
2039
  if (key.startsWith(`${this.endpoint}:`)) bidiBeaconScripts.delete(key);
1748
2040
  }
@@ -1870,7 +2162,9 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
1870
2162
  * (create, close, activate, getTree, navigate, reload, locateNodes, captureScreenshot, setViewport,
1871
2163
  * handleUserPrompt); script (evaluate, callFunction); input (performActions, setFiles); network
1872
2164
  * (addDataCollector, removeDataCollector, getData, addIntercept, removeIntercept, continueRequest,
1873
- * provideResponse, failRequest, beforeRequestSent event); emulation (setUserAgentOverride). Events
2165
+ * provideResponse, failRequest, beforeRequestSent event); emulation (setUserAgentOverride);
2166
+ * browser (setDownloadBehavior) and permissions (setPermission), both via withBrowserConnection
2167
+ * from ../bidi-browser-tools.ts. Events
1874
2168
  * subscribed via BidiConnection.on/waitFor: browsingContext.navigationCommitted/userPromptOpened/
1875
2169
  * contextDestroyed, log.entryAdded, network.beforeRequestSent/responseCompleted.
1876
2170
  *
@@ -1900,10 +2194,14 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
1900
2194
  * this one. Neither insertText route synthesizes a <br> or a block break.
1901
2195
  * - trace.performance / heap.snapshot / audit.lighthouse: not declared, Chrome-only domains with
1902
2196
  * no BiDi equivalent at all.
1903
- * - screenshot.scale: not declared. browsingContext.captureScreenshot's parameters are context,
1904
- * origin, format and clip — no scale anywhere, and its clip types (box/element) carry no
1905
- * multiplier either. A `scale` other than 1 is a refusal in screenshot() (ADR-001 param-level
1906
- * gap, like drag's html5 mode), pointing at emulate's deviceScaleFactor as the real workaround.
2197
+ * - screenshot.scale: DECLARED for Firefox >= 160 (BIDI_CAPABILITY_MIN_FIREFOX; requireFirefox
2198
+ * gives an older one "unsupported"). browsingContext.captureScreenshot still has no scale
2199
+ * parameter, so screenshot() sets browsingContext.setViewport({devicePixelRatio: base * scale})
2200
+ * for the one capture (no viewport key: the layout viewport is untouched) and puts the ratio back
2201
+ * (the recorded emulate ratio, else null). base is the recorded or live window.devicePixelRatio
2202
+ * because BiDi's ratio replaces where Chrome's clip.scale multiplies. Measured on 160.0 headless:
2203
+ * 1366x683 at scale 1, 2732x1366 at ratio 2, ratio back to 1 after setViewport({devicePixelRatio:
2204
+ * null}). Limit: a ratio emulated by ANOTHER process with no viewport record is restored to null.
1907
2205
  * - screenshot.renderSize: DECLARED, and the one screenshot capability here that is not a gap. It
1908
2206
  * rides browsingContext.setViewport — the same command emulate.deviceMetrics already uses —
1909
2207
  * applied for one capture and restored to the tracked viewport (or `viewport:null`) afterwards.
@@ -1920,13 +2218,22 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
1920
2218
  * tile:true) has nothing to do here. `tile:true` is still a refusal in screenshot() naming
1921
2219
  * --browser chrome; the default (auto) still never bands on this backend — both unchanged, now
1922
2220
  * for a documented reason instead of an untested one.
1923
- * - emulate.mediaFeatures / emulate.cpuThrottling / emulate.networkConditions: not declared.
1924
- * Firefox 153 does not implement setMediaFeaturesOverride; CPU throttling and network condition
1925
- * emulation have no verified-working BiDi path in this environment, so emulate() never claims
1926
- * them and silently ignores the `mobile` flag (no BiDi mobile-viewport emulation exists either).
1927
- * - network.responseBodyPostHoc: not declared, deliberately, mirroring cdp/driver.ts's own call.
1928
- * network.addDataCollector must be armed before the request; there is no reading a body for a
1929
- * request that predates arming, so an honest capability set omits it exactly as Chrome's does.
2221
+ * - emulate.mediaFeatures / emulate.networkConditions: declared via BIDI_CAPABILITY_MIN_FIREFOX
2222
+ * at 160 (measured on 160.0: emulation.setMediaFeaturesOverride takes features as an OBJECT,
2223
+ * features:null resets; setNetworkConditions has only {type:"offline"}, null resets). A media
2224
+ * TYPE (print/screen) and any latency/throughput throttle are refused "unsupported", never
2225
+ * ignored. emulate.cpuThrottling: not declared; CPU throttling has no BiDi path, so emulate()
2226
+ * never claims it and silently ignores the `mobile` flag (no BiDi mobile-viewport emulation exists either).
2227
+ * - network.responseBodyPostHoc: DECLARED for Firefox >= 160. A collector is session-scoped and
2228
+ * retains only requests that start after it, so armPostHocBodies adds ONE (all contexts, 2 MB per
2229
+ * response) the moment the real session is created, in the holder path of getConnection (which
2230
+ * the mux daemon also runs); joined connections never arm. A body the page fetched before any
2231
+ * tool call is then readable by request id (getData, no collector id) as text or base64. Limits:
2232
+ * Firefox's own total budget evicts the oldest bodies ("unavailable network data" -> clear
2233
+ * DriverError), over-cap/unknown ids read "no such network data" (also a DriverError, never empty
2234
+ * text), and the request id must come from somewhere (a network.response event, or
2235
+ * get_network_request): a request that predates this process's own subscription has no id here.
2236
+ * Chrome still does not declare it (cdp/driver.ts).
1930
2237
  * - NavigateResult.waitedFor never returns "timeout": BiDi's navigate/reload block server-side on
1931
2238
  * `wait`, so an unreachable milestone is a thrown "timeout" DriverError, not CDP's soft return.
1932
2239
  * - LifetimeModel's "MUST re-establish itself transparently if the transport dies" is NOT