cdp-toolkit 1.9.0 → 1.9.4

package/src/cli.ts

@@ -23,17 +23,20 @@
  *   - --list  -> all tool names (one per line) to stdout, exit 0.
  */
 import { TOOLS, TOOL_NAMES, type ToolName } from "./index.ts";
-import { resolveBrowserKind, stripBrowserFlag, startFirefoxSession } from "./backend.ts";
+import { resolveBackend, stripBrowserFlag, stripConnectFlag, startFirefoxSession } from "./backend.ts";
 import { toolAvailability } from "./capabilities.ts";
 import { FIREFOX_TOOLS } from "./firefox-tools.ts";
 import { leaseFromArgs, withLeaseScope } from "./leases.ts";
+import { MANIFEST } from "./manifest.ts";
 
 const USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
 Usage:
-  bun run src/cli.ts <tool> [--browser chrome|firefox] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
+  bun run src/cli.ts <tool> [--browser chrome|firefox] [--connect <port|host:port|ws-url>] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
   bun run src/cli.ts --list [--browser chrome|firefox]
   bun run src/cli.ts --capabilities [--browser chrome|firefox]
+  bun run src/cli.ts --help | -h                 # this message
+  bun run src/cli.ts <tool> --help | -h           # that tool's arguments, sourced from its schema
 
 Examples:
   bun run src/cli.ts list_pages
@@ -43,14 +46,30 @@ Examples:
   bun run src/cli.ts take_screenshot --target url:example --fullPage true
   bun run src/cli.ts --browser firefox take_snapshot
   bun run src/cli.ts --capabilities --browser firefox
+  bun run src/cli.ts take_screenshot --help
+  bun run src/cli.ts --connect 9223 take_snapshot     # attach to your own logged-in Firefox (implies --browser firefox)
+
+--help/-h is recognised ANYWHERE in argv, before any tool dispatch: it never touches the
+browser (no CDP connection, no lease, no file written) and is never passed through as a tool
+argument, even when it appears after a tool name.
 
 Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else "chrome" (default,
-zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
-to), used for exactly one tool call, then disposed before the process exits.
+zero behavior change for existing users). Firefox runs in one of two modes:
+  - LAUNCH (default): a fresh throwaway-profile Firefox is spawned for this one invocation, used
+    for exactly one tool call, then disposed (session ended, process killed) before the process
+    exits. This is a login wall for anything that needs your real session.
+  - ATTACH (--connect <port|host:port|ws-url>, or the CDP_FIREFOX_ENDPOINT env var): connects to a
+    Firefox YOU already started with --remote-debugging-port, so tools see your real logged-in
+    profile. This process never launches or kills that Firefox; dispose only ends the BiDi session.
+    --connect implies --browser firefox and conflicts with an explicit --browser chrome. Firefox
+    allows only one active BiDi session at a time, so a client that dies without disposing cleanly
+    (e.g. SIGKILL) can leave the slot occupied until Firefox restarts.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
-  plus worker:<substr> for evaluate_script ONLY (Chrome only): an MV3 extension's background service
-  worker, e.g. worker:<extension-id>. An idle-evicted worker is started first unless wake:false.
+  plus worker:<substr> (Chrome only) for evaluate_script, list_network_requests, get_network_request
+  and list_console_messages ONLY: an MV3 extension's background service worker, e.g.
+  worker:<extension-id>. An idle-evicted worker is started first unless wake:false. Recording a
+  worker keeps it alive for the length of the capture.
 Leases: pass --lease <token> to act on a tab another agent claimed with claim_page (MCP only).
 Run list_leases to see who holds what; release_page --lease <token> gives a lease back.
 Run with --list to print every tool name available under the selected backend.
@@ -72,12 +91,13 @@ interface ParsedArgs {
   tool?: string;
   list: boolean;
   capabilities: boolean;
+  help: boolean;
   args: Record<string, unknown>;
 }
 
 /** Parse process argv (already sliced to drop the runtime + script, and with --browser already stripped). */
 function parseArgv(argv: string[]): ParsedArgs {
-  const out: ParsedArgs = { list: false, capabilities: false, args: {} };
+  const out: ParsedArgs = { list: false, capabilities: false, help: false, args: {} };
   // Collect flag pairs separately so --json can be merged BEFORE individual
   // flags override it, regardless of token order.
   let jsonObj: Record<string, unknown> | undefined;
@@ -93,6 +113,16 @@ function parseArgv(argv: string[]): ParsedArgs {
       out.capabilities = true;
       continue;
     }
+    // Recognised ANYWHERE in argv (not just as the first token), and BEFORE the
+    // generic "--key value" branch below, so --help/-h can never be swallowed as
+    // a tool argument (the bug: `take_screenshot --help` used to run the tool
+    // with args.help=true; `-h` doesn't even start with "--", so without this
+    // explicit check it fell through to the positional branch and, if a tool
+    // name was already set, was silently dropped and the tool ran anyway).
+    if (token === "--help" || token === "-h") {
+      out.help = true;
+      continue;
+    }
     if (token.startsWith("--")) {
       const key = token.slice(2);
       const next = argv[i + 1];
@@ -130,10 +160,78 @@ function isToolName(name: string): name is ToolName {
   return Object.prototype.hasOwnProperty.call(TOOLS, name);
 }
 
+/** A JSON-Schema property shape narrow enough for the fields --help prints. */
+interface HelpProp {
+  type?: string | string[];
+  enum?: unknown[];
+  description?: string;
+}
+
+/** "string", "string|array" (a union type array), or an enum rendered as "png|jpeg". */
+function formatType(prop: HelpProp | undefined): string {
+  if (!prop) return "any";
+  if (Array.isArray(prop.enum) && prop.enum.length > 0) return prop.enum.map(String).join("|");
+  if (Array.isArray(prop.type)) return prop.type.join("|");
+  return prop.type ?? "any";
+}
+
+/**
+ * Print one tool's usage sourced ENTIRELY from MANIFEST's inputSchema (src/manifest.ts) — the
+ * same JSON Schema the MCP server advertises via tools/list. This is a read of that single
+ * source of truth, not a second hand-maintained argument list that could drift from it.
+ */
+function printToolHelp(name: ToolName): void {
+  const spec = MANIFEST.find((t) => t.name === name);
+  if (!spec) {
+    // Every TOOLS entry has a MANIFEST entry (auditCoverage() in mcp.ts warns otherwise); this
+    // is a defensive fallback, not an expected path.
+    process.stdout.write(`${name}\n`);
+    return;
+  }
+  const required = new Set(spec.inputSchema.required ?? []);
+  const props = (spec.inputSchema.properties ?? {}) as Record<string, HelpProp>;
+  const keys = Object.keys(props);
+
+  const lines = [spec.name, "", spec.description, ""];
+  if (keys.length === 0) {
+    lines.push("Arguments: none.");
+  } else {
+    lines.push("Arguments:");
+    for (const key of keys) {
+      const prop = props[key];
+      const reqTag = required.has(key) ? "required" : "optional";
+      lines.push(`  --${key} <${formatType(prop)}> (${reqTag})`);
+      if (prop?.description) lines.push(`      ${prop.description}`);
+    }
+  }
+  lines.push("", `Usage: cdp ${spec.name} [--target <sel>] [--json '<obj>'] [--<key> <value> ...]`);
+  process.stdout.write(`${lines.join("\n")}\n`);
+}
+
 async function main(): Promise<number> {
   const rawArgv = process.argv.slice(2);
-  const browser = resolveBrowserKind(rawArgv);
-  const parsed = parseArgv(stripBrowserFlag(rawArgv));
+  const { kind: browser, endpoint } = resolveBackend(rawArgv);
+  const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
+
+  // --help/-h short-circuits BEFORE any availability lookup or backend touch — no CDP
+  // connection, no lease, no file written. This must be the very first thing checked in
+  // main(), ahead of --list/--capabilities, so a --help gesture can never be downgraded
+  // into a real dispatch by any branch below it.
+  if (parsed.help) {
+    if (!parsed.tool) {
+      process.stdout.write(`${USAGE}\n`);
+      return 0;
+    }
+    if (!isToolName(parsed.tool)) {
+      process.stderr.write(
+        `${JSON.stringify({ error: `unknown tool '${parsed.tool}'. Run --list to see all ${TOOL_NAMES.length} tools.` })}\n`,
+      );
+      return 1;
+    }
+    printToolHelp(parsed.tool);
+    return 0;
+  }
+
   const availability = toolAvailability(browser);
   const availableSet = new Set(availability.available);
 
@@ -203,14 +301,15 @@ async function main(): Promise<number> {
       return 0;
     }
 
-    // Firefox: one process per invocation. Launch, run exactly one tool call, always dispose,
-    // even if the tool call itself throws, so the spawned Firefox process never leaks.
+    // Firefox: one process per invocation. Launch (or, with --connect/CDP_FIREFOX_ENDPOINT,
+    // attach), run exactly one tool call, always dispose, even if the tool call itself throws —
+    // in launch mode that reaps the spawned process; in attach mode it only ends the BiDi session.
     const neutralFn = FIREFOX_TOOLS[tool];
     if (!neutralFn) {
       process.stderr.write(`${JSON.stringify({ error: `tool '${tool}' has no Firefox implementation wired` })}\n`);
       return 1;
     }
-    const session = await startFirefoxSession();
+    const session = await startFirefoxSession({ endpoint });
     try {
       const result = await neutralFn(session.driver, parsed.args as never);
       process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/src/driver.ts

@@ -56,7 +56,13 @@
  * breaks the CLI.
  */
 
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { ToolName } from "./index.ts";
+// leaseDir only, for the viewport-override record below. leases.ts imports nothing from this file
+// (node builtins only), so this is not a cycle; the record deliberately shares the lease directory
+// rather than minting a second state location.
+import { leaseDir } from "./leases.ts";
 import type { TargetSelector } from "./types.ts";
 
 /* ---------------------------------- uids ---------------------------------- */
@@ -133,6 +139,9 @@ export type Capability =
   | "emulate.networkConditions" // throttled or offline conditions
   | "screenshot.fullPage" // one-shot full scrollable page, not just the viewport
   | "screenshot.element" // capture clipped to a single element
+  | "screenshot.scale" // per-capture output-pixel multiplier; no permanent emulation change
+  | "screenshot.renderSize" // emulate a viewport for the duration of ONE capture, then put the old one back
+  | "screenshot.tile" // capture past the backend's one-image encode limit as vertical bands, stitched losslessly
   | "network.intercept" // fulfill, fail, or continue a matched request
   | "network.responseBodyPostHoc" // read a body for a request not armed in advance
   | "snapshot.accessibilityTree" // native a11y dump, not a DOM-walk approximation
@@ -344,6 +353,236 @@ export interface ScreenshotOptions {
   quality?: number;
   fullPage?: boolean; // requires "screenshot.fullPage"
   clip?: ElementLocator; // requires "screenshot.element"
+  scale?: number; // requires "screenshot.scale"; absent or 1 leaves the capture byte-for-byte as it was
+  /**
+   * Render this capture at an emulated viewport, then put the previous one back. Both fields are
+   * required TOGETHER (the tool layer enforces it; a driver trusts its caller) and both require
+   * Capability "screenshot.renderSize". Absent, the capture is byte-for-byte what it was.
+   *
+   * NOT the same knob as `scale`, and the difference is measured, not asserted. `scale` multiplies
+   * output pixels while the page keeps believing it is its old size: window.devicePixelRatio read 2
+   * both before and after a --scale 3 capture, and innerWidth/innerHeight stayed 1390x1064. This
+   * pair changes what the page BELIEVES for the length of one capture, so media queries flip and
+   * the document re-lays-out — which is the point (capture a responsive page at desktop 1920x1080
+   * from a tab that is not that size) and also why it must be undone afterwards.
+   *
+   * `deviceScaleFactor` and `mobile` are deliberately INHERITED from whatever override was already
+   * in place rather than reset: the caller asked to change the render SIZE, and silently dropping
+   * a device pixel ratio they set earlier would be a second, unrequested change.
+   */
+  renderWidth?: number; // requires "screenshot.renderSize"
+  renderHeight?: number; // requires "screenshot.renderSize"
+  /**
+   * Whether this capture may be taken as vertical BANDS and stitched, instead of as one image.
+   * Three-valued, and the middle value is the default:
+   *
+   *   undefined  AUTO. One shot when the projected output fits under the backend's per-image encode
+   *              limit, banded when it does not. A capture that fits is byte-for-byte the call it
+   *              always was — the same params on the wire, no clip synthesized that was not there
+   *              before — so auto costs the common path nothing but the layout-metrics round trip
+   *              the decision itself needs.
+   *   false      NEVER band. A capture past the limit is REFUSED by the encode guard instead. This
+   *              is the escape hatch back to the exact pre-tiling behaviour.
+   *   true       ALWAYS band, even when one shot would have fitted. Mainly so the banded path is
+   *              directly testable on an ordinary page; see the driver for why "always" is made to
+   *              mean at least two bands rather than a one-band no-op.
+   *
+   * AUTO IS THE DEFAULT BECAUSE THE ALTERNATIVE IS A WEDGED TAB, not because banding is free.
+   * Measured (see MAX_ENCODED_SIDE_PX in ../cdp/driver.ts): a plain capture of a document past the
+   * limit does not fail fast — Page.captureScreenshot never answers, and because captureBeyondViewport
+   * resizes the page to the clip for the length of the capture, the tab is left stuck at that size
+   * with every later screenshot timing out too.
+   *
+   * Requires Capability "screenshot.tile" only for `true`. `undefined` and `false` ask a backend for
+   * nothing it cannot already do.
+   */
+  tile?: boolean; // `true` requires "screenshot.tile"
+}
+
+/**
+ * A capture too big for one image, handed to the tool layer band by band.
+ *
+ * LAZY BY CONTRACT, not by convenience: the Nth band's Page.captureScreenshot runs only when the
+ * consumer pulls the Nth band, so a driver never holds two bands at once and a whole 1.4 GB image
+ * never exists in memory. Accumulating the bands into an array first would typecheck, work on a
+ * small page, and defeat the entire point of the streaming stitcher on a large one.
+ *
+ * VERTICAL ONLY, AND THAT IS A SCOPE DECISION RATHER THAN AN OVERSIGHT. Bands stack top to bottom
+ * because that is the one direction a PNG can be concatenated without decoding it whole: scanlines
+ * are the unit, so appending rows is cheap and appending columns is not. A region whose projected
+ * WIDTH alone is past the limit is therefore refused, naming the width, rather than silently
+ * truncated or split into a grid this stitcher cannot reassemble.
+ */
+export interface BandedCapture {
+  /** The bands, top to bottom, produced one at a time. */
+  bands: AsyncIterable<Uint8Array>;
+  /** How many bands the sequence will yield. Known before the first one is captured. */
+  bandCount: number;
+  /** Height of every band but the last, in CSS px. The last is the remainder. */
+  bandHeightCss: number;
+  /** The whole region being tiled, CSS px, in document coordinates. */
+  clip: { x: number; y: number; width: number; height: number };
+  /** Always "png": the stitch is a PNG-scanline concatenation, and there is no lossless JPEG one. */
+  format: "png";
+}
+
+/**
+ * The tool layer's half of a banded capture: consume the bands and return whatever was made of
+ * them. Called at most once per capture, BEFORE the first band is taken, so a consumer that cannot
+ * accept a banded capture at all (it was asked for JPEG, or for base64 of a 300 MB image) refuses
+ * by throwing here and no band is ever captured.
+ *
+ * This is why the driver takes a callback rather than returning the iterable: a banded capture may
+ * hold a viewport override for its whole duration, and the driver can only put that back once it
+ * knows the consumer is finished. Handing the iterable out would end the driver's call while the
+ * page was still emulated.
+ */
+export type BandConsumer<T> = (capture: BandedCapture) => Promise<T>;
+
+/** What a banded capture returns in place of bytes: the consumer's own answer, plus how it was split. */
+export interface TiledScreenshotResult<T> {
+  tiled: true;
+  format: "png";
+  bandCount: number;
+  bandHeightCss: number;
+  /** Whatever the BandConsumer returned — for take_screenshot, the stitcher's measured report. */
+  consumed: T;
+  /** Same three render-size fields a one-shot capture carries, same meaning. */
+  renderSize?: { width: number; height: number };
+  renderRestored?: boolean;
+  renderRestoreError?: string;
+}
+
+/** One capture, delivered whole or in bands. Discriminate with isTiledCapture. */
+export type CaptureDelivery<T> = ScreenshotResult | TiledScreenshotResult<T>;
+
+export function isTiledCapture<T>(delivery: CaptureDelivery<T>): delivery is TiledScreenshotResult<T> {
+  return (delivery as { tiled?: unknown }).tiled === true;
+}
+
+/**
+ * What a capture returns. `data`/`format` are the whole answer for an ordinary capture; the three
+ * render-size fields are present only when renderWidth/renderHeight were applied.
+ *
+ * `renderRestored:false` IS THE LOUD PART, and it is why this is a result shape rather than a bare
+ * byte buffer. A failed restore means the caller's page is still emulated at the render size after
+ * this call returns — a mutation they did not ask to keep — so it has to travel back with the image
+ * instead of being swallowed. On the THROWING path there is no result to carry it, so a driver
+ * appends the same fact to the error message instead (see CdpPageDriver.screenshot).
+ */
+export interface ScreenshotResult {
+  data: Uint8Array;
+  format: "png" | "jpeg";
+  /** The emulated viewport this capture ran at. Present only when renderWidth/renderHeight were given. */
+  renderSize?: { width: number; height: number };
+  /** Whether the previous viewport was put back. Present only when a render size was applied. */
+  renderRestored?: boolean;
+  /** Why the restore failed. Present only when renderRestored is false. */
+  renderRestoreError?: string;
+}
+
+/* --------------------- the viewport-override record (both drivers) --------------------- */
+
+/**
+ * The device-metrics override this toolkit last applied to a target, as a file under the lease
+ * directory. Written by PageDriver.emulate, removed by emulate{clearOverrides}, read by
+ * PageDriver.screenshot so a render-size capture can put back what it displaced.
+ *
+ * WHY A FILE AND NOT A FIELD ON THE DRIVER. The spec for this feature called for a private field on
+ * the page driver, and that is provably not enough here — MEASURED against Chrome/151.0.7922.76:
+ *
+ *   $ cli emulate --target T --width 800 --height 600     # one process, socket closes on exit
+ *   $ cli evaluate_script --target T ...innerWidth...     # a DIFFERENT process
+ *   "[800,600,2]"                                         # the override OUTLIVED the connection
+ *
+ * The CDP driver's LifetimeModel is "per-call": a PageDriver instance lives for exactly one tool
+ * call, so a field on it is empty by construction at the start of the screenshot call that needs
+ * it, and the override it must not destroy was set by a process that has already exited. Same
+ * reasoning leases.ts and origins.ts give for their own files, arrived at the same way.
+ *
+ * WHY THE RECORD IS LOAD-BEARING AND NOT A CONVENIENCE. Emulation.clearDeviceMetricsOverride does
+ * NOT mean "undo the override" — measured, twice, on the same tab:
+ *
+ *   fresh connection, never set an override, clear it   -> returns {}, page STAYS 800x600
+ *   fresh connection, set 1920x1080, then clear         -> page becomes 1390x1064, the REAL device
+ *
+ * So clearing is a no-op for an override this session did not set, and once a session DOES set one,
+ * clearing reverts to the physical device and takes any earlier override down with it. A
+ * render-size capture always sets one, so its clear always lands — which is exactly why restoring
+ * by clearing would silently destroy a caller's earlier `emulate` and why this record exists.
+ *
+ * WHAT IT CANNOT SEE, and this is a real limit rather than a caveat: an override applied by
+ * something that is not this toolkit — the DevTools UI, Puppeteer, another automation client, or a
+ * toolkit build older than this record — leaves no file, so a render-size capture restores by
+ * clearing and that foreign override is reset to the real device. There is no CDP or BiDi command
+ * that reads a device-metrics override back, so a driver genuinely cannot know it was there.
+ */
+export interface ViewportRecord {
+  width: number;
+  height: number;
+  /** CDP's Emulation.setDeviceMetricsOverride sense: 0 means "the real device's". */
+  deviceScaleFactor?: number;
+  mobile?: boolean;
+}
+
+/** Sibling of leases.ts's lease-<backend>-<targetId>.json, in the same directory and with the same
+ *  filename-safety policy. Keyed by the driver's uid SCHEME ("cdp" / "bidi") because a CDP targetId
+ *  and a BiDi context id are not disjoint by construction — the same reason lease files carry a
+ *  backend in the name. */
+export function viewportRecordFile(scheme: string, targetId: string): string {
+  return join(leaseDir(), `viewport-${scheme}-${targetId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+}
+
+/** The override this toolkit last applied to `targetId`, or undefined when it has applied none.
+ *  A missing, unreadable, or malformed file all read as undefined: "we do not know" is the honest
+ *  answer, and it is the one that makes the caller restore by clearing rather than by guessing. */
+export async function readViewportRecord(scheme: string, targetId: string): Promise<ViewportRecord | undefined> {
+  try {
+    const raw = JSON.parse(await readFile(viewportRecordFile(scheme, targetId), "utf8")) as Partial<ViewportRecord>;
+    if (typeof raw?.width !== "number" || typeof raw?.height !== "number") return undefined;
+    return {
+      width: raw.width,
+      height: raw.height,
+      ...(typeof raw.deviceScaleFactor === "number" ? { deviceScaleFactor: raw.deviceScaleFactor } : {}),
+      ...(typeof raw.mobile === "boolean" ? { mobile: raw.mobile } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Record an override this toolkit just applied. Deliberately best-effort: emulate's job is to
+ *  emulate, and a full disk must not turn a working override into a thrown error. The cost of a
+ *  lost write is stated above — a later render-size capture restores by clearing instead. */
+export async function writeViewportRecord(scheme: string, targetId: string, rec: ViewportRecord): Promise<void> {
+  try {
+    await mkdir(leaseDir(), { recursive: true });
+    await writeFile(viewportRecordFile(scheme, targetId), JSON.stringify({ scheme, targetId, ...rec }), "utf8");
+  } catch {
+    /* best-effort, see above */
+  }
+}
+
+/**
+ * What a driver appends to a capture's error when the render-size restore ALSO failed. Shared by
+ * both drivers because the sentence is the caller's only warning that their page is still emulated,
+ * and it must not read differently depending on which browser stranded it. Says what is wrong AND
+ * how to undo it by hand, because at this point the toolkit has already failed to.
+ */
+export function renderRestoreFailureNote(size: { width: number; height: number }, why: string): string {
+  return (
+    `— AND the ${size.width}x${size.height} render-size override could NOT be restored (${why}), so this page is STILL ` +
+    `emulated at ${size.width}x${size.height}: put it back with emulate{width,height} or emulate{clearOverrides:true}.`
+  );
+}
+
+/** Forget the recorded override. Best-effort for the same reason, and a missing file is success. */
+export async function clearViewportRecord(scheme: string, targetId: string): Promise<void> {
+  try {
+    await unlink(viewportRecordFile(scheme, targetId));
+  } catch {
+    /* best-effort, see above */
+  }
 }
 
 /** Each optional field names the Capability it requires, if any. */
@@ -642,9 +881,21 @@ export interface PageDriver {
   setFiles(loc: ElementLocator, files: readonly string[]): Promise<void>;
 
   /* rendering */
-  /** Returns raw image bytes. Artifact naming and writing stay in the tool. */
-  screenshot(opts?: ScreenshotOptions): Promise<{ data: Uint8Array; format: "png" | "jpeg" }>;
-  /** Apply overrides. Returns the field names actually applied. */
+  /** Returns raw image bytes. Artifact naming and writing stay in the tool. Under
+   *  renderWidth/renderHeight it also reports the emulated size it ran at and whether the previous
+   *  viewport was put back — see ScreenshotResult.
+   *
+   *  `consumeBands` is how a caller says it can accept a capture too big to encode as one image
+   *  (see BandedCapture). Omitting it is a real and honest state, not a shortcut: a caller with
+   *  nowhere to put a band sequence gets the encode guard's refusal instead of a wedged tab, which
+   *  is exactly the pre-tiling behaviour. Supplying it lets the driver band the capture when the
+   *  projection demands it (the default) or when `tile:true` asks for it. The driver calls it at
+   *  most once and awaits it, so the whole capture — every band — is finished before this method
+   *  resolves and before any viewport override is put back. */
+  screenshot<T>(opts?: ScreenshotOptions, consumeBands?: BandConsumer<T>): Promise<CaptureDelivery<T>>;
+  /** Apply overrides. Returns the field names actually applied. An implementation that applies
+   *  device metrics MUST record them with writeViewportRecord (and clear the record under
+   *  clearOverrides), or a later render-size capture will restore by clearing and destroy them. */
   emulate(opts: EmulationOptions): Promise<{ applied: string[] }>;
 
   /* events */