cdp-toolkit 1.9.1 → 1.9.4

package/src/bidi/driver.ts

@@ -1,9 +1,16 @@
 /**
  * BiDi implementation of the browser-neutral Driver contract in ../driver.ts (ADR-001), for
- * Firefox. lifetime is "session": a BiDi socket cannot be resumed, so createFirefoxDriver(port)
- * memoizes ONE BidiConnection per port at module scope (the connections map below), page()
+ * Firefox. THE CONNECTION IDENTITY IS A BiDi ws ENDPOINT, not a port: createFirefoxDriver(port)
+ * derives the loopback endpoint of a Firefox this toolkit launched, while
+ * createFirefoxDriverForEndpoint(wsUrl) takes a user-supplied one for ATTACH mode (a Firefox the
+ * user started with --remote-debugging-port; see ../backend.ts). Attach is a first-class path,
+ * not a workaround — what is impossible is RELAUNCHING the binary to open a port on a running
+ * instance (bidi/launch.ts's header), not connecting to a port that is already open.
+ * lifetime is "session": a BiDi socket cannot be resumed, so this file memoizes ONE
+ * BidiConnection per endpoint at module scope (the connections map below), page()
  * retains a holder, release() decrements it, and only BrowserDriver.dispose() ever closes the
- * socket. There is deliberately no reconnect-and-resume path: if the socket dies, every pending
+ * socket — after sending session.end, so an attached Firefox (which outlives us) gets its single
+ * session slot back. There is deliberately no reconnect-and-resume path: if the socket dies, every pending
  * and future call on it rejects with "disconnected" rather than silently starting a fresh
  * session underneath a caller who still thinks they hold the old one. (driver.ts's LifetimeModel
  * doc says a "session" driver "MUST re-establish itself transparently if the transport dies";
@@ -24,19 +31,20 @@
  */
 import type { TargetSelector } from "../types.ts";
 import {
-  UID_STAMP_ATTR, isDriverError, interpolatePoints,
+  UID_STAMP_ATTR, isDriverError, interpolatePoints, clearViewportRecord, readViewportRecord, renderRestoreFailureNote, writeViewportRecord,
   type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
   type DragDestination, type DragOptions,
   type SetCookieParams,
   type DriverUid, type ElementLocator, type EmulationOptions, type InterceptRule, type KeyPress, type LifetimeModel,
   type MouseButtonOptions, type NavigateOptions, type NavigateResult, type PageDriver, type PageInfo,
-  type ScreenshotOptions, type ScrollOptions, type SnapshotNode, type UidStability,
+  type ScreenshotOptions, type ScreenshotResult, type ScrollOptions, type SnapshotNode, type UidStability,
+  type BandConsumer, type CaptureDelivery,
 } from "../driver.ts";
 import { assertLeaseOk } from "../leases.ts";
 import { resolveLiveLabel } from "../origins.ts";
 import { isWorkerSelector, WORKER_SELECTOR_UNSUPPORTED_MESSAGE } from "../workers.ts";
 import { BEACON_FUNCTION_DECLARATION, BEACON_READ_EXPRESSION, BEACON_SOURCE, recordDispatch } from "../activity.ts";
-import { BidiConnection, BidiError, connectBidiSession } from "./client.ts";
+import { BidiConnection, BidiError, connectBidiSessionUrl } from "./client.ts";
 import { takeStampedSnapshot } from "./snapshot.ts";
 import { selectRule, buildFulfillParams, effectiveAction } from "../tools/network_mock.ts";
 import type {
@@ -288,37 +296,63 @@ const AWAIT_SCROLL_SETTLE_SOURCE = "function(){return window.__cdpScrollSettle;}
  * network.intercept rides network.addIntercept + network.beforeRequestSent, verified working
  * (see intercept()'s comment on why urlPatterns is never populated). screenshot.fullPage uses
  * captureScreenshot's origin:"document", screenshot.element uses its clip:{type:"element"}, both verified.
+ * screenshot.renderSize IS declared, and it is the one screenshot capability here that is not a
+ * Chrome-only gap: it rides browsingContext.setViewport, the very command emulate.deviceMetrics
+ * above already rides, applied for one capture and undone afterwards. Refusing it would be dishonest
+ * in the opposite direction — claiming a missing primitive this driver demonstrably has. Contrast
+ * screenshot.scale, absent because captureScreenshot genuinely has no scale parameter.
+ * screenshot.tile is absent for a THIRD reason, neither "has it" nor "no such parameter": the
+ * primitive plausibly exists (clip:{type:"box"}) but nothing about band tiling has been measured on
+ * this backend, and the Chrome declaration rests entirely on measurement. An undeclared capability
+ * that turns out to work is a follow-up; a declared one that silently mis-stitches is a wrong image
+ * the caller cannot tell from a right one.
  */
 const BIDI_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
-  "emulate.deviceMetrics", "screenshot.fullPage", "screenshot.element", "network.intercept", "locate.xpath",
+  "emulate.deviceMetrics", "screenshot.fullPage", "screenshot.element", "screenshot.renderSize", "network.intercept", "locate.xpath",
 ]);
 
 /* --------------------------------- module-scope session memoization --------------------------------- */
-// "session" LifetimeModel: ONE BidiConnection per port, shared by every page() acquisition on that
-// port. getConnection retains a holder on every call (fresh or reused); callers release() it.
-const connections = new Map<number, BidiConnection>();
-async function getConnection(port: number, timeoutMs?: number): Promise<BidiConnection> {
-  const existing = connections.get(port);
+// "session" LifetimeModel: ONE BidiConnection per BiDi ws endpoint, shared by every page()
+// acquisition on that endpoint. Keyed by the endpoint URL string rather than a port because attach
+// mode's endpoint may be any host/port/path (../backend.ts's normalizeBidiEndpoint), and the URL is
+// the only identity both modes share. getConnection retains a holder on every call (fresh or
+// reused); callers release() it.
+const connections = new Map<string, BidiConnection>();
+async function getConnection(endpoint: string, timeoutMs?: number): Promise<BidiConnection> {
+  const existing = connections.get(endpoint);
   if (existing) { existing.retain(); return existing; }
   // Firefox 153's default unhandledPromptBehavior is "dismiss": a page-blocking alert()/confirm()
   // gets auto-dismissed before handleDialog() ever runs, and Firefox's own userPromptOpened event
   // reports handler:"dismiss" on it (verified: a bare session.new left "no such alert" on the very
   // next handleUserPrompt call). Setting "ignore" here is what makes handleDialog() able to see
   // and answer a live prompt at all.
-  const conn = await connectBidiSession(port, {
+  const conn = await connectBidiSessionUrl(endpoint, {
     ...(timeoutMs !== undefined ? { timeoutMs } : {}),
     capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } },
+  }).catch((e: unknown) => {
+    // Firefox allows exactly ONE active BiDi session and never reaps an abandoned one (verified:
+    // still held 10s after an abrupt socket death). A client killed without session.end therefore
+    // leaves the slot occupied until Firefox restarts, and the raw wire message ("Maximum number of
+    // active sessions") tells the user nothing about how to get unstuck. Force-ending a session we
+    // do not own is not an option (there is no id to end), so this maps the error to instructions.
+    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+      throw driverError("disconnected",
+        `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` +
+        `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` +
+        `session that Firefox does not reap.)`);
+    }
+    throw e;
   }); // already retained once
-  connections.set(port, conn);
+  connections.set(endpoint, conn);
   return conn;
 }
 
 /**
- * Contexts that already carry a beacon preload script, keyed port:context ->
+ * Contexts that already carry a beacon preload script, keyed endpoint:context ->
  * the script id BiDi handed back.
  *
  * WHY FIREFOX NEEDS NO HELD CONNECTION where Chrome does. This driver's
- * LifetimeModel is "session": ONE BidiConnection is memoized per port above and
+ * LifetimeModel is "session": ONE BidiConnection is memoized per endpoint above and
  * lives until dispose(), so a preload script registered on it stays registered
  * across navigations for free. Chrome's equivalent registration is cleared when
  * the registering client disconnects, and this toolkit's CDP lifetime is
@@ -771,7 +805,101 @@ class BidiPageDriver implements PageDriver {
     }
   }
 
-  async screenshot(opts?: ScreenshotOptions): Promise<{ data: Uint8Array; format: "png" | "jpeg" }> {
+  /**
+   * A capture, optionally rendered at an emulated viewport that is put back afterwards. Same
+   * contract and the same restore-on-every-exit discipline as CdpPageDriver.screenshot — read that
+   * method's comment for the reasoning; only the commands differ (browsingContext.setViewport here,
+   * Emulation.setDeviceMetricsOverride there).
+   *
+   * NOT LIVE-FIRED. Firefox was not launched for this change, so unlike the Chrome path every claim
+   * here rests on the shape of browsingContext.setViewport plus the unit tests, not on a measured
+   * page. What IS verified is that the restore cannot be skipped: the ordering and the finally-path
+   * are shared logic exercised by test/screenshot-scale.test.ts against a stub. Two specifics to
+   * confirm when Firefox is next driven: whether setViewport's null viewport reverts to the real
+   * window (CDP's clear does not, for an override another session set), and whether it reflows
+   * synchronously the way setDeviceMetricsOverride was measured to.
+   */
+  async screenshot<T>(opts?: ScreenshotOptions, _consumeBands?: BandConsumer<T>): Promise<CaptureDelivery<T>> {
+    const renderSize =
+      opts?.renderWidth !== undefined && opts?.renderHeight !== undefined
+        ? { width: opts.renderWidth, height: opts.renderHeight }
+        : undefined;
+    if (!renderSize) return this.capture(opts);
+    const previous = await readViewportRecord(this.browser.scheme, this.contextId);
+    try {
+      // devicePixelRatio is deliberately not sent: this changes the render SIZE, and omitting the
+      // field leaves whatever ratio an earlier emulate set in place (the CDP path inherits it the
+      // same way).
+      await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: renderSize.width, height: renderSize.height } });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+    let shot: ScreenshotResult | undefined;
+    let captureError: unknown;
+    try {
+      shot = await this.capture(opts);
+    } catch (e) {
+      captureError = e;
+    }
+    let restoreError: string | undefined;
+    try {
+      // Re-apply the tracked viewport, never a bare null: a null viewport reverts to the real
+      // window and would destroy an override the caller set with emulate earlier.
+      if (previous) {
+        await this.conn.send("browsingContext.setViewport", {
+          context: this.contextId,
+          viewport: { width: previous.width, height: previous.height },
+          ...(previous.deviceScaleFactor != null ? { devicePixelRatio: previous.deviceScaleFactor } : {}),
+        });
+      } else {
+        await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null });
+      }
+    } catch (e) {
+      restoreError = e instanceof Error ? e.message : String(e);
+    }
+    if (!shot) {
+      if (restoreError !== undefined && captureError instanceof Error) {
+        captureError.message = `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`;
+      }
+      throw captureError;
+    }
+    const result: ScreenshotResult = { ...shot, renderSize, renderRestored: restoreError === undefined };
+    if (restoreError !== undefined) result.renderRestoreError = restoreError;
+    return result;
+  }
+  /** The capture itself, with no viewport emulation of its own. Split out so screenshot()'s restore
+   *  wraps EVERY way this can fail, the throwing paths included. */
+  private async capture(opts?: ScreenshotOptions): Promise<ScreenshotResult> {
+    // ADR-001 param-level gap, same shape as drag's mode:"html5" (see resolveDragMode in
+    // ../shared-tools.ts): browsingContext.captureScreenshot has NO scale parameter — its only
+    // knobs are origin, format and clip — so a scale asked for here is refused outright rather
+    // than silently captured at 1x, which would hand back an image the caller never asked for.
+    if (opts?.scale !== undefined && opts.scale !== 1) {
+      throw driverError(
+        "unsupported",
+        `screenshot scale ${opts.scale} is not supported by this backend (WebDriver BiDi's ` +
+          "browsingContext.captureScreenshot has no scale parameter). Call emulate with " +
+          `deviceScaleFactor:${opts.scale} first and capture at scale 1, or use --browser chrome.`,
+      );
+    }
+    // Same ADR-001 param-level shape, and the reason is HONESTY rather than a missing primitive.
+    // browsingContext.captureScreenshot does take clip:{type:"box",x,y,width,height}, so a banded
+    // capture is probably implementable here — but Firefox was not launched for this change, so
+    // every property band tiling depends on is unmeasured on this backend: whether a box clip
+    // renders content outside the viewport at all, whether clip.y is CSS px, whether fixed elements
+    // repeat per band, whether seams are pixel-exact. Each of those was measured on Chrome before
+    // the Chrome path was declared. Shipping an unverified twin would put a silently-wrong stitch in
+    // front of a caller, so this refuses and says why. `tile:false` and the default (auto, which
+    // never bands here) ask this backend for nothing and are untouched.
+    if (opts?.tile === true) {
+      throw driverError(
+        "unsupported",
+        "screenshot tile:true is not supported by this backend: band tiling is declared only where the band " +
+          "arithmetic has been measured against a real browser, and Firefox was not driven for it " +
+          '(browsingContext.captureScreenshot\'s clip:{type:"box"} is the primitive it would ride, untested). ' +
+          "Capture a smaller region or a single element, or use --browser chrome for a tiled capture.",
+      );
+    }
     const format = opts?.format ?? "png";
     const params: BrowsingContextCaptureScreenshotParameters = {
       context: this.contextId,
@@ -792,14 +920,37 @@ class BidiPageDriver implements PageDriver {
   // a real parity gap noted in the footer rather than smoothed over.
   async emulate(opts: EmulationOptions): Promise<{ applied: string[] }> {
     if (opts.clearOverrides) {
+      // CHECKED FOR THE SAME CROSS-PROCESS NO-OP THE CDP DRIVER HAD (see that method's comment) —
+      // by protocol semantics, since Firefox was not launched to measure this directly. The W3C
+      // WebDriver BiDi spec's "remote end steps for browsingContext.setViewport" (and the "set
+      // viewport" / "set device pixel ratio override" algorithms it calls) key EVERY step off
+      // |navigable| — the browsing context — never off which session or connection issued an
+      // earlier override: "If |viewport| is not null, set the width/height of |navigable|'s layout
+      // viewport... Otherwise, set the |navigable|'s layout viewport to the implementation-defined
+      // default", and the device-pixel-ratio twin literally does `Remove |navigable| from [device
+      // pixel ratio overrides]`. There is no per-session ownership check anywhere in that algorithm,
+      // unlike CDP's clearDeviceMetricsOverride (measured to be a no-op unless the calling
+      // connection is also the one that set the override). So a `viewport: null` from ANY BiDi
+      // connection reverts THIS navigable to its real default, regardless of which connection —
+      // this toolkit's own per-call ones included — set the override being cleared. No defect,
+      // no "set-then-clear" workaround needed; left as it was.
       await this.conn.send("emulation.setUserAgentOverride", { userAgent: null, contexts: [this.contextId] }).catch(() => undefined);
       await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null, devicePixelRatio: null }).catch(() => undefined);
+      // No override of ours left to put back: a render-size capture should restore to null.
+      await clearViewportRecord(this.browser.scheme, this.contextId);
       return { applied: [] };
     }
     const applied: string[] = [];
     try {
       if (opts.width != null && opts.height != null) {
         await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: opts.width, height: opts.height }, ...(opts.deviceScaleFactor != null ? { devicePixelRatio: opts.deviceScaleFactor } : {}) });
+        // Recorded so a later render-size capture puts THIS back rather than reverting to the real
+        // window. See ViewportRecord in ../driver.ts.
+        await writeViewportRecord(this.browser.scheme, this.contextId, {
+          width: opts.width,
+          height: opts.height,
+          ...(opts.deviceScaleFactor != null ? { deviceScaleFactor: opts.deviceScaleFactor } : {}),
+        });
         applied.push("deviceMetrics");
       }
       if (opts.userAgent != null) {
@@ -1053,10 +1204,12 @@ class BidiBrowserDriver implements BrowserDriver {
   readonly capabilities = BIDI_CAPABILITIES;
   readonly uidStability: UidStability = "document-stamp";
   readonly snapshotFidelity = "dom-heuristic" as const;
-  constructor(private readonly port: number, private readonly timeoutMs?: number) {}
+  /** `endpoint` is a BiDi ws URL (see getConnection): derived from a port for a launched
+   *  Firefox, user-supplied for an attached one. It is this driver's whole identity. */
+  constructor(private readonly endpoint: string, private readonly timeoutMs?: number) {}
 
   async listPages(): Promise<PageInfo[]> {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       const { contexts } = await conn.send("browsingContext.getTree", {}).catch((e) => { throw mapBidiError(e); });
       return Promise.all(contexts.map((c) => pageInfoOf(conn, c)));
@@ -1065,7 +1218,7 @@ class BidiBrowserDriver implements BrowserDriver {
     }
   }
   async newPage(url?: string): Promise<PageInfo> {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       const { context } = await conn.send("browsingContext.create", { type: "tab" }).catch((e) => { throw mapBidiError(e); });
       // Established fact: navigating the default about:home context to a data: URL is rejected,
@@ -1077,7 +1230,7 @@ class BidiBrowserDriver implements BrowserDriver {
     }
   }
   async closePage(id: string): Promise<{ success: boolean }> {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       await conn.send("browsingContext.close", { context: id }).catch((e) => { throw mapBidiError(e); });
       return { success: true };
@@ -1086,7 +1239,7 @@ class BidiBrowserDriver implements BrowserDriver {
     }
   }
   async activatePage(id: string): Promise<PageInfo> {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       await conn.send("browsingContext.activate", { context: id }).catch((e) => { throw mapBidiError(e); });
       const ctx = await resolveContext(conn, id);
@@ -1096,7 +1249,7 @@ class BidiBrowserDriver implements BrowserDriver {
     }
   }
   async page(selector: TargetSelector): Promise<PageDriver> {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     let ctx: BrowsingContextInfo;
     try {
       ctx = await resolveContext(conn, selector);
@@ -1124,10 +1277,10 @@ class BidiBrowserDriver implements BrowserDriver {
    * an annotation that must never fail real work.
    */
   async installActivityBeacon(contextId: string): Promise<boolean> {
-    const conn = await getConnection(this.port, this.timeoutMs).catch(() => undefined);
+    const conn = await getConnection(this.endpoint, this.timeoutMs).catch(() => undefined);
     if (!conn) return false;
     try {
-      const key = `${this.port}:${contextId}`;
+      const key = `${this.endpoint}:${contextId}`;
       if (!bidiBeaconScripts.has(key)) {
         const registered = await conn.send("script.addPreloadScript", {
           functionDeclaration: BEACON_FUNCTION_DECLARATION,
@@ -1151,7 +1304,7 @@ class BidiBrowserDriver implements BrowserDriver {
   /** Read the beacon timestamp for a context, or null when it has none. Gate-free;
    *  see the declaration in ../driver.ts for why that is required here. */
   async readActivityBeacon(contextId: string): Promise<number | null> {
-    const conn = await getConnection(this.port, this.timeoutMs).catch(() => undefined);
+    const conn = await getConnection(this.endpoint, this.timeoutMs).catch(() => undefined);
     if (!conn) return null;
     try {
       const res = await conn.send("script.evaluate", {
@@ -1171,19 +1324,35 @@ class BidiBrowserDriver implements BrowserDriver {
 
   async dispose(): Promise<void> {
     for (const key of [...bidiBeaconScripts.keys()]) {
-      if (key.startsWith(`${this.port}:`)) bidiBeaconScripts.delete(key);
+      if (key.startsWith(`${this.endpoint}:`)) bidiBeaconScripts.delete(key);
     }
-    const conn = connections.get(this.port);
+    const conn = connections.get(this.endpoint);
     if (!conn) return;
-    connections.delete(this.port);
+    connections.delete(this.endpoint);
+    // Cleanly END the BiDi session so Firefox frees its single session slot for the next
+    // attach (a launch-mode Firefox is killed anyway; this matters for attach mode where the
+    // user's browser lives on). Verified: closing the socket alone does NOT free the slot, and
+    // Firefox never reaps the orphan, so skipping this would make the SECOND attach fail.
+    // Best-effort: harmless if the socket is already gone.
+    await conn.send("session.end", {}).catch(() => undefined);
     conn.dispose();
   }
 }
 
-/** Construct the BiDi implementation of the frozen Driver contract. `port` is a Firefox debug
- *  port already listening (see ./launch.ts's launchFirefox), never 9222/CDP's convention. */
+/** Construct the BiDi implementation of the frozen Driver contract for a LAUNCHED Firefox. `port`
+ *  is a Firefox debug port already listening (see ./launch.ts's launchFirefox), never 9222/CDP's
+ *  convention; it is only ever a shorthand for the loopback endpoint below. Note port 0 is a legal
+ *  argument for capability probes (createFirefoxDriver(0)) that never open a socket. */
 export function createFirefoxDriver(port: number, opts?: { timeoutMs?: number }): BrowserDriver {
-  return new BidiBrowserDriver(port, opts?.timeoutMs);
+  return new BidiBrowserDriver(`ws://127.0.0.1:${port}/session`, opts?.timeoutMs);
+}
+
+/** Construct the same driver for ATTACH mode: `wsUrl` is the BiDi endpoint of a Firefox the user
+ *  started themselves with --remote-debugging-port, already normalized by ../backend.ts's
+ *  normalizeBidiEndpoint. This driver NEVER owns that process — dispose() ends the BiDi session and
+ *  closes the socket, and nothing anywhere in this path kills a browser it did not launch. */
+export function createFirefoxDriverForEndpoint(wsUrl: string, opts?: { timeoutMs?: number }): BrowserDriver {
+  return new BidiBrowserDriver(wsUrl, opts?.timeoutMs);
 }
 // resolveContext is exported for ONE reason: it is the Firefox lease choke
 // point, and a choke point nothing can call directly is a choke point nothing
@@ -1192,7 +1361,8 @@ export function createFirefoxDriver(port: number, opts?: { timeoutMs?: number })
 export { BidiBrowserDriver, BidiPageDriver, resolveContext };
 
 /* ------------------------------------------------------------------------------
- * BiDi modules/commands used: session (new, subscribe/unsubscribe, via client.ts); browsingContext
+ * BiDi modules/commands used: session (new, subscribe/unsubscribe, via client.ts; end, sent by
+ * dispose() so an attached Firefox gets its one session slot back); browsingContext
  * (create, close, activate, getTree, navigate, reload, locateNodes, captureScreenshot, setViewport,
  * handleUserPrompt); script (evaluate, callFunction); input (performActions, setFiles); network
  * (addDataCollector, removeDataCollector, getData, addIntercept, removeIntercept, continueRequest,
@@ -1226,6 +1396,25 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
  *     this one. Neither insertText route synthesizes a <br> or a block break.
  *   - trace.performance / heap.snapshot / audit.lighthouse: not declared, Chrome-only domains with
  *     no BiDi equivalent at all.
+ *   - screenshot.scale: not declared. browsingContext.captureScreenshot's parameters are context,
+ *     origin, format and clip — no scale anywhere, and its clip types (box/element) carry no
+ *     multiplier either. A `scale` other than 1 is a refusal in screenshot() (ADR-001 param-level
+ *     gap, like drag's html5 mode), pointing at emulate's deviceScaleFactor as the real workaround.
+ *   - screenshot.renderSize: DECLARED, and the one screenshot capability here that is not a gap. It
+ *     rides browsingContext.setViewport — the same command emulate.deviceMetrics already uses —
+ *     applied for one capture and restored to the tracked viewport (or `viewport:null`) afterwards.
+ *     NOT live-fired: Firefox was not launched for this change, so the ordering and the restore rest
+ *     on the shared logic's unit tests rather than a measured page. Two things to confirm when
+ *     Firefox is next driven: whether a null viewport reverts to the real window (CDP's clear does
+ *     NOT, for an override another session set), and whether setViewport reflows synchronously the
+ *     way Emulation.setDeviceMetricsOverride was measured to on Chrome.
+ *   - screenshot.tile: not declared, and unlike screenshot.scale this is an UNMEASURED gap rather
+ *     than a missing parameter. captureScreenshot does take clip:{type:"box"}, so bands are probably
+ *     implementable — but every property band tiling rests on (does a box clip render past the
+ *     viewport, is clip.y CSS px, do fixed elements repeat per band, are seams pixel-exact) was
+ *     measured on Chrome and on nothing else, and Firefox was not launched here. `tile:true` is a
+ *     refusal in screenshot() naming --browser chrome; the default (auto) never bands on this
+ *     backend, so it is unchanged.
  *   - emulate.mediaFeatures / emulate.cpuThrottling / emulate.networkConditions: not declared.
  *     Firefox 153 does not implement setMediaFeaturesOverride; CPU throttling and network condition
  *     emulation have no verified-working BiDi path in this environment, so emulate() never claims
@@ -1238,4 +1427,10 @@ export { BidiBrowserDriver, BidiPageDriver, resolveContext };
  *   - LifetimeModel's "MUST re-establish itself transparently if the transport dies" is NOT
  *     implemented: a dead BiDi socket surfaces as "disconnected" on every subsequent call instead
  *     of silently starting a new session underneath the caller. See the top-of-file comment.
+ *   - Concurrent clients: Chrome happily accepts many CDP sockets against one browser, Firefox
+ *     accepts exactly ONE active BiDi session. In attach mode that makes this driver mutually
+ *     exclusive with any other BiDi client (a Playwright/geckodriver run, a second cdp-toolkit)
+ *     on the same Firefox, and a client killed without session.end leaks the slot until Firefox
+ *     restarts. getConnection maps that into an actionable "disconnected" error; there is nothing
+ *     to declare as a Capability here because the constraint is per-browser, not per-tool.
  * ---------------------------------------------------------------------------- */

package/src/bidi/launch.ts

@@ -1,15 +1,22 @@
 /**
  * Firefox launcher for the WebDriver BiDi backend.
  *
- * Why this exists at all: unlike Chrome, there is no attach-to-the-user's-
- * running-browser story here. You cannot add --remote-debugging-port to an
- * already-running Firefox: relaunching the binary with that flag hands off
- * to the running instance and exits silently, opening no port. The flag
- * only takes effect on the ORIGINAL launch of a process. That means this
- * module must own full process lifetime, start it, own its pid, and reap
- * it, because there is no later point at which a debug port can be bolted
- * on. Do not "simplify" this into an attach-to-running-browser helper; that
- * shape cannot work on Firefox and was verified against Firefox 153.0.3.
+ * What THIS module does: it owns full process lifetime for the Firefox instances it starts —
+ * launches the binary, holds its pid, and reaps it. That is required because there is no live
+ * handoff for the debug port: you cannot RELAUNCH an already-running Firefox with
+ * --remote-debugging-port and have it take effect — the relaunch hands off to the running
+ * instance and exits silently, opening no port. The flag only takes effect on the ORIGINAL
+ * launch of a process, which is why this launcher must be the one to start it. Do not
+ * "simplify" this into a relaunch-to-open-a-port helper; that shape cannot work on Firefox and
+ * was verified against Firefox 153.0.3.
+ *
+ * What this does NOT mean: that Firefox "cannot be attached to" at all. A Firefox that was
+ * ORIGINALLY launched with --remote-debugging-port — by this module, or by hand by the user —
+ * exposes a plain BiDi ws endpoint that a fresh client CAN connect to later, any number of
+ * times. That attach path is real, supported, and separate from this file: see backend.ts's
+ * `startFirefoxSession({ endpoint })` and `createFirefoxDriverForEndpoint` (bidi/driver.ts),
+ * which is exactly how cdp-toolkit connects to a user-launched Firefox to see their real
+ * logged-in profile instead of a throwaway one.
  *
  * Zero runtime dependencies: only node:child_process, node:fs, node:net,
  * node:os and node:path.
@@ -185,8 +192,11 @@ export async function launchFirefox(opts: LaunchFirefoxOptions = {}): Promise<La
 /*
  * CDP methods/domains used: none, this module speaks no browser protocol,
  * it only launches the process and confirms the debug port is listening.
- * Parity gap vs the Chrome-side story: there is no equivalent of attaching
- * to an already-running browser instance the way client.ts can resolve a
- * target on an already-listening port 9222. Firefox always requires this
- * launcher to have started the process.
+ * This launcher itself has no attach story — it only ever starts fresh processes — but that is
+ * a scope limit of THIS FILE, not a Firefox limit: see backend.ts's `startFirefoxSession({
+ * endpoint })` / `createFirefoxDriverForEndpoint` (bidi/driver.ts) for the supported attach path,
+ * which connects to the ws endpoint of a Firefox that was launched (by this module or by hand)
+ * with --remote-debugging-port. Still unsupported, and unsupportable on Firefox, is relaunching
+ * the binary against an already-running instance to open a port after the fact (header above) —
+ * that is a different operation from attaching to a port that is already open.
  */