cdp-toolkit 1.9.1 → 1.9.4

package/src/shared-tools.ts

@@ -36,8 +36,10 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type {
-  BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
+  BandedCapture, BrowserCookie, BrowserDriver, Capability, DragDestination, DriverUid, ElementLocator, NavigateResult, PageDriver, PageInfo, SnapshotNode,
 } from "./driver.ts";
+import { isTiledCapture } from "./driver.ts";
+import { stitchPngBandsToFile } from "./png.ts";
 import type { TargetSelector } from "./types.ts";
 import {
   assertLeaseOk, claimLease, defaultLabel, leaseTtlMs, listLeases, releaseLeaseFor, requireLease,
@@ -1044,31 +1046,331 @@ function stamp(): string {
   return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
 }
 
+/** Upper bound on take_screenshot's `scale`. 8 already gives ~11k px off a 1390 px viewport on a
+ *  ratio-2 display, past which the driver's own 16384 px encode guard is the binding limit anyway;
+ *  the point of a ceiling here is that a fat-fingered `scale: 800` is refused instantly instead of
+ *  wedging a real browser command for minutes. Refused, not clamped, like MAX_DRAG_STEPS. */
+const MAX_SCREENSHOT_SCALE = 8;
+
+/**
+ * take_screenshot's `scale`, plus the second backend gate in this file (resolveDragMode is the
+ * first, and this follows its shape exactly). scale needs Capability "screenshot.scale", which
+ * only the Chrome driver declares: Page.captureScreenshot takes a per-call clip.scale, while
+ * WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter at all. Per ADR-001
+ * this is a PARAM-level gap, not a whole-tool one — take_screenshot stays in tools/list on Firefox
+ * because every other argument works there, and asking for a scale on Firefox is a clear
+ * validation error, never a silent 1x capture that would return an image the caller never asked
+ * for and could not tell apart from the one they wanted. Exported for the unit tests.
+ */
+export function resolveScreenshotScale(scale: number | undefined, capabilities: ReadonlySet<Capability>): number {
+  if (scale === undefined) return 1;
+  if (typeof scale !== "number" || !Number.isFinite(scale) || scale <= 0 || scale > MAX_SCREENSHOT_SCALE) {
+    throw new SharedToolError(`take_screenshot: 'scale' must be a finite number greater than 0 and at most ${MAX_SCREENSHOT_SCALE} (default 1)`);
+  }
+  if (scale !== 1 && !capabilities.has("screenshot.scale")) {
+    throw new SharedToolError(
+      "take_screenshot: 'scale' is not supported by this backend (WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter). " +
+        `Call emulate with deviceScaleFactor:${scale} first and capture at scale 1, or use --browser chrome for a per-capture scale.`,
+    );
+  }
+  return scale;
+}
+
+/** Upper bound on a render-size side, in CSS px. Deliberately Chrome's own 16384 px per-side encode
+ *  ceiling: a viewport wider than the widest image the browser can encode cannot produce a
+ *  full-width capture of itself anyway, so anything past it is a typo rather than an intent. The
+ *  binding limit in practice is lower and is enforced where it can actually be computed — the
+ *  driver's assertClipEncodable, on the post-override numbers, since a 8192 css-px render is already
+ *  16384 device px on a ratio-2 display. Refused, not clamped, like MAX_DRAG_STEPS. */
+const MAX_RENDER_SIZE_PX = 16384;
+
+/**
+ * take_screenshot's `renderWidth`/`renderHeight`, and the third backend gate in this file
+ * (resolveDragMode is the first, resolveScreenshotScale the second, and this follows their shape).
+ *
+ * REQUIRED TOGETHER, mirroring the "device metrics require both width and height" rule emulate()
+ * has always had: a viewport is two numbers, and honouring one while inventing the other would
+ * render at a size the caller never named and never sees in the result.
+ *
+ * Unlike `scale` this is NOT a Chrome-only capability — both drivers ride their own viewport
+ * emulation for it — so on today's backends the capability arm never fires. It is written anyway
+ * because ADR-001 says availability is declared, not assumed: a future backend that cannot emulate
+ * a viewport must refuse out loud here rather than silently capture at the tab's real size, which
+ * would return a picture indistinguishable from the one the caller asked for. Exported for the tests.
+ */
+export function resolveRenderSize(
+  renderWidth: number | undefined,
+  renderHeight: number | undefined,
+  capabilities: ReadonlySet<Capability>,
+): { width: number; height: number } | undefined {
+  if (renderWidth === undefined && renderHeight === undefined) return undefined;
+  if (renderWidth === undefined || renderHeight === undefined) {
+    throw new SharedToolError(
+      "take_screenshot: 'renderWidth' and 'renderHeight' are required together (a viewport is two numbers; " +
+        `got ${renderWidth === undefined ? "only renderHeight" : "only renderWidth"})`,
+    );
+  }
+  for (const [name, value] of [["renderWidth", renderWidth], ["renderHeight", renderHeight]] as const) {
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > MAX_RENDER_SIZE_PX) {
+      throw new SharedToolError(`take_screenshot: '${name}' must be an integer between 1 and ${MAX_RENDER_SIZE_PX} css px (got ${JSON.stringify(value)})`);
+    }
+  }
+  if (!capabilities.has("screenshot.renderSize")) {
+    throw new SharedToolError(
+      "take_screenshot: 'renderWidth'/'renderHeight' are not supported by this backend (it cannot emulate a viewport for a capture). " +
+        `Call emulate with width:${renderWidth}, height:${renderHeight} first, capture, then restore the viewport yourself.`,
+    );
+  }
+  return { width: renderWidth, height: renderHeight };
+}
+
+/**
+ * take_screenshot's `tile`, and the fourth backend gate in this file (resolveDragMode,
+ * resolveScreenshotScale and resolveRenderSize are the first three, and this follows their shape).
+ *
+ * THREE-VALUED, AND THE DEFAULT IS AUTO — the one decision in this feature that is not a preference.
+ * A capture past the backend's per-image encode limit does not fail politely: measured on
+ * Chrome/151.0.7922.76, Page.captureScreenshot never answers and the tab is left resized to the
+ * clip with every later screenshot timing out. Whole-page capture is what take_screenshot is for, so
+ * the default has to be the one that returns the whole page: one shot when it fits, bands when it
+ * does not. `false` is the escape hatch back to the exact pre-tiling behaviour (refuse rather than
+ * band), `true` forces the banded path so it is directly testable.
+ *
+ * ONLY `true` COSTS A CAPABILITY. Auto asks a backend for nothing it cannot do — a driver without
+ * "screenshot.tile" simply never bands, exactly as it behaved before this feature — so gating auto
+ * would delete the default behaviour on Firefox for no gain. Exported for the unit tests.
+ */
+export function resolveTileMode(
+  tile: boolean | undefined,
+  capabilities: ReadonlySet<Capability>,
+  format: "png" | "jpeg",
+  returnBase64: boolean | undefined,
+): boolean | undefined {
+  if (tile === undefined) return undefined;
+  if (typeof tile !== "boolean") throw new SharedToolError(`take_screenshot: 'tile' must be true, false, or omitted for automatic (got ${JSON.stringify(tile)})`);
+  if (!tile) return false;
+  if (!capabilities.has("screenshot.tile")) {
+    throw new SharedToolError(
+      "take_screenshot: 'tile' is not supported by this backend (band tiling is declared only where the band arithmetic was measured against a real browser; " +
+        "Firefox was not driven for it). Capture a smaller region or a single element, or use --browser chrome for a tiled capture.",
+    );
+  }
+  // Asked for explicitly, so refuse explicitly and BEFORE a socket is opened. The same two
+  // combinations reached by AUTO are refused with the same words, one layer later — see
+  // tiledCaptureRefusal's call site inside takeScreenshot.
+  if (format !== "png") throw tiledCaptureRefusal("format");
+  if (returnBase64) throw tiledCaptureRefusal("base64");
+  return true;
+}
+
+/**
+ * The two things a tiled capture cannot also be, in one place so the explicit (`tile:true`, refused
+ * before a socket is opened) and the automatic (refused the instant the driver offers bands, before
+ * the first one is captured) paths cannot drift into two different explanations of the same wall.
+ *
+ * `banded` is present only on the automatic path, where the driver has already measured what it
+ * would take: naming the band count and the region turns "you cannot have this" into "you cannot
+ * have this because your page is this big".
+ */
+function tiledCaptureRefusal(reason: "format" | "base64", banded?: BandedCapture): SharedToolError {
+  const because = banded
+    ? ` This capture needs ${banded.bandCount} bands (${banded.clip.width}x${banded.clip.height} css px is past what one image can encode).`
+    : "";
+  if (reason === "format") {
+    return new SharedToolError(
+      "take_screenshot: a tiled capture is PNG-only — bands are stitched by concatenating PNG scanlines, and there is no lossless " +
+        `JPEG equivalent to concatenate.${because} Pass format:"png", or lower scale / narrow the region until one JPEG fits.`,
+    );
+  }
+  return new SharedToolError(
+    "take_screenshot: 'returnBase64' cannot be combined with a tiled capture — a tiled image runs to hundreds of megabytes and base64 " +
+      `inflates it by a third, into the caller's response.${because} Read the file at the returned path instead, or capture a region small enough for one shot.`,
+  );
+}
+
+/** PNG: an 8-byte signature, then an IHDR chunk whose payload opens with two big-endian uint32s. */
+function pngPixelSize(b: Uint8Array, view: DataView): { width: number; height: number } | undefined {
+  if (b.length < 24) return undefined;
+  if (view.getUint32(0) !== 0x89504e47 || view.getUint32(4) !== 0x0d0a1a0a) return undefined;
+  if (String.fromCharCode(b[12]!, b[13]!, b[14]!, b[15]!) !== "IHDR") return undefined;
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+
+/** SOF markers carrying frame dimensions. SOF4 (0xc4 DHT), SOF8 (0xc8), SOF12 (0xcc DAC) are NOT frame headers. */
+const JPEG_SOF = new Set([0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf]);
+
+/** JPEG: walk the marker segments to the first start-of-frame, which carries height then width. */
+function jpegPixelSize(b: Uint8Array, view: DataView): { width: number; height: number } | undefined {
+  if (b.length < 4 || b[0] !== 0xff || b[1] !== 0xd8) return undefined;
+  let i = 2;
+  while (i + 3 < b.length) {
+    if (b[i] !== 0xff) {
+      i += 1; // resync past fill bytes / padding
+      continue;
+    }
+    const marker = b[i + 1]!;
+    if (marker === 0xff) {
+      i += 1;
+      continue;
+    }
+    // Standalone markers: no length field follows.
+    if (marker === 0xd8 || marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) {
+      i += 2;
+      continue;
+    }
+    const segLen = view.getUint16(i + 2);
+    if (JPEG_SOF.has(marker)) {
+      if (i + 9 > b.length) return undefined;
+      return { width: view.getUint16(i + 7), height: view.getUint16(i + 5) };
+    }
+    if (segLen < 2) return undefined;
+    i += 2 + segLen;
+  }
+  return undefined;
+}
+
+/**
+ * Output dimensions read from the ENCODED BYTES, never computed from the clip and the scale the
+ * caller asked for: those two disagree the moment the device pixel ratio multiplies in (a scale-1
+ * capture of a 1390 px viewport is a 2780 px PNG on a ratio-2 display), and a computed number that
+ * quietly disagrees with the file on disk is worse than no number. `undefined` when the bytes are
+ * neither PNG nor JPEG, so take_screenshot can OMIT width/height rather than report a guess.
+ *
+ * A deliberate second implementation of tools/screencast.ts's imageSize, not a shared one: this
+ * file is the browser-NEUTRAL tool layer and imports nothing from src/tools/ (that Chrome-only
+ * layer is what it replaced), and screencast.ts's copy takes a node Buffer while a driver hands
+ * this one a Uint8Array. The two are pinned by their own tests and must stay in agreement.
+ * Exported for the unit tests.
+ */
+export function imagePixelSize(bytes: Uint8Array): { width: number; height: number } | undefined {
+  if (bytes.byteLength < 4) return undefined;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return pngPixelSize(bytes, view) ?? jpegPixelSize(bytes, view);
+}
+
+/**
+ * take_screenshot's result. Named rather than inlined now that it carries the render-size outcome:
+ * the shape appears three times in this function (signature, literal, and the widening the optional
+ * fields need) and a fourth divergent copy is how a field goes missing.
+ *
+ * `scale` is ALWAYS present; `width`/`height` only when the bytes decoded; the three render-size
+ * fields only when a render size was applied. Absent beats invented, everywhere here.
+ */
+export interface ScreenshotToolResult {
+  path: string;
+  bytes: number;
+  format: "png" | "jpeg";
+  target: { id: string; url: string; title: string };
+  scale: number;
+  width?: number;
+  height?: number;
+  /**
+   * Present, and true, ONLY when this capture was taken as bands and stitched. Auto-tiling is
+   * silent about nothing: a caller who never asked for tiling still learns their image came from
+   * `bands` separate captures, which is what makes the lazy-content caveat theirs to reason about
+   * (a page that only loads content on real scroll renders blank in bands past the first viewport —
+   * a property of the page, not of the stitch, but invisible unless the tiling is reported).
+   */
+  tiled?: true;
+  /** How many captures the image was assembled from. Present only alongside `tiled`. */
+  bands?: number;
+  /** The emulated viewport the capture ran at. */
+  renderSize?: { width: number; height: number };
+  /** False means the page is STILL emulated at renderSize: the caller has to put it back. */
+  renderRestored?: boolean;
+  renderRestoreError?: string;
+  base64?: string;
+}
+
 export async function takeScreenshot(
   driver: BrowserDriver,
   args: {
     target?: TargetSelector; format?: "png" | "jpeg"; quality?: number; fullPage?: boolean;
-    uid?: DriverUid; selector?: string; savePath?: string; returnBase64?: boolean;
+    uid?: DriverUid; selector?: string; savePath?: string; returnBase64?: boolean; scale?: number;
+    renderWidth?: number; renderHeight?: number; tile?: boolean;
   } = {},
-): Promise<{ path: string; bytes: number; format: "png" | "jpeg"; target: { id: string; url: string; title: string }; base64?: string }> {
+): Promise<ScreenshotToolResult> {
   if ((args.uid !== undefined && args.uid !== "") && args.selector) throw new SharedToolError("provide exactly one of uid or selector, not both");
   const format = args.format ?? "png";
+  // Range + capability checks BEFORE withPage: an argument this backend cannot honour must not claim
+  // a lease or open a socket (same reasoning as drag's resolveDragMode call site). For the render
+  // size that is stronger than tidiness — the refusal happens before any viewport is emulated, so a
+  // rejected call cannot be the one that leaves a page mutated.
+  const scale = resolveScreenshotScale(args.scale, driver.capabilities);
+  const renderSize = resolveRenderSize(args.renderWidth, args.renderHeight, driver.capabilities);
+  const tile = resolveTileMode(args.tile, driver.capabilities, format, args.returnBase64);
   return withPage(driver, args.target, async (page) => {
     const clip = args.uid !== undefined || args.selector ? locatorOf(args) : undefined;
-    const { data, format: outFormat } = await page.screenshot({ format, quality: args.quality, fullPage: args.fullPage, ...(clip ? { clip } : {}) });
-    if (data.byteLength === 0) throw new SharedToolError("captureScreenshot returned empty data");
-    await mkdir(ARTIFACT_DIR, { recursive: true });
-    const ext = outFormat === "jpeg" ? "jpg" : "png";
+    const ext = format === "jpeg" ? "jpg" : "png";
+    // Named BEFORE the capture, because a banded capture writes straight to its destination as the
+    // bands arrive — there is never a complete image in memory to name a file after. The one-shot
+    // path names it at the same moment for the same reason a single path is easier to trust than
+    // two; the only visible effect is that the default filename's stamp is the capture's start.
     const path = args.savePath ?? join(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
-    await writeFile(path, Buffer.from(data));
-    const result: { path: string; bytes: number; format: "png" | "jpeg"; target: { id: string; url: string; title: string }; base64?: string } = {
-      path, bytes: data.byteLength, format: outFormat, target: target3(page.info),
+    // The tool layer owns files, the driver owns the protocol: the driver decides that this capture
+    // has to be banded and produces the bands, and this callback is the only thing that knows where
+    // they go. It runs BEFORE the first band is captured, which is what lets the two combinations a
+    // stitched capture cannot serve refuse without a single wasted Page.captureScreenshot.
+    const stitch = async (banded: BandedCapture) => {
+      if (format !== "png") throw tiledCaptureRefusal("format", banded);
+      if (args.returnBase64) throw tiledCaptureRefusal("base64", banded);
+      return stitchPngBandsToFile(banded.bands, path);
     };
-    if (args.returnBase64) result.base64 = Buffer.from(data).toString("base64");
+    const shot = await page.screenshot({
+      format, quality: args.quality, fullPage: args.fullPage, scale,
+      ...(clip ? { clip } : {}),
+      ...(renderSize ? { renderWidth: renderSize.width, renderHeight: renderSize.height } : {}),
+      ...(tile !== undefined ? { tile } : {}),
+    }, stitch);
+    const result: ScreenshotToolResult = isTiledCapture(shot)
+      ? {
+          // width/height/bytes come from the STITCHER, which is the only thing that ever saw the
+          // whole image: re-reading a several-hundred-MB PNG off disk to decode an IHDR this call
+          // already computed would be slower and no more true. Still measured, never projected —
+          // the stitcher patches the IHDR with the rows it actually wrote.
+          path, bytes: shot.consumed.bytes, format: "png", target: target3(page.info), scale,
+          width: shot.consumed.width, height: shot.consumed.height,
+          tiled: true, bands: shot.consumed.bands,
+        }
+      : await writeOneShot(shot.data, shot.format, path, target3(page.info), scale, args.returnBase64);
+    // What actually happened to the page, reported from the DRIVER's answer rather than from what
+    // was asked for. renderRestored:false means the caller's tab is still emulated at renderSize
+    // and they have to fix it — the one outcome that must never be swallowed, so it rides back on
+    // the success result the same way a decoded width does.
+    if (renderSize && shot.renderSize) {
+      result.renderSize = shot.renderSize;
+      result.renderRestored = shot.renderRestored ?? false;
+      if (shot.renderRestoreError !== undefined) result.renderRestoreError = shot.renderRestoreError;
+    }
     return result;
   });
 }
 
+/** The one-shot half of takeScreenshot: bytes in hand, so the file is written here and the size is
+ *  DECODED from those bytes. Unchanged from before tiling existed, split out only so the tiled arm
+ *  above reads as the one difference it is. */
+async function writeOneShot(
+  data: Uint8Array,
+  outFormat: "png" | "jpeg",
+  path: string,
+  target: { id: string; url: string; title: string },
+  scale: number,
+  returnBase64: boolean | undefined,
+): Promise<ScreenshotToolResult> {
+  if (data.byteLength === 0) throw new SharedToolError("captureScreenshot returned empty data");
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, Buffer.from(data));
+  const size = imagePixelSize(data);
+  const result: ScreenshotToolResult = { path, bytes: data.byteLength, format: outFormat, target, scale };
+  // Absent beats invented: undecodable bytes leave width/height off the result entirely.
+  if (size) {
+    result.width = size.width;
+    result.height = size.height;
+  }
+  if (returnBase64) result.base64 = Buffer.from(data).toString("base64");
+  return result;
+}
+
 export async function emulate(
   driver: BrowserDriver,
   args: {