cdp-toolkit 1.9.1 → 1.9.5

package/src/cdp/driver.ts

@@ -13,11 +13,13 @@ import { resolveUid } from "../tools/snapshot.ts";
 import { resolveWorkerSelector } from "./workers.ts";
 import { buildFulfillParams, effectiveAction, selectRule } from "../tools/network_mock.ts";
 import {
-  LEGACY_NUMERIC_UID, interpolatePoints, type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
+  LEGACY_NUMERIC_UID, interpolatePoints, clearViewportRecord, readViewportRecord, renderRestoreFailureNote, writeViewportRecord,
+  type BrowserCookie, type BrowserDriver, type Capability, type DeleteCookiesFilter, type HandledDialogInfo, type DriverError, type DriverErrorCode, type DriverEvent,
   type SetCookieParams,
   type DragDestination, type DragOptions,
   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 BandConsumer, type BandedCapture, type CaptureDelivery, type TiledScreenshotResult,
 } from "../driver.ts";
 /* ------------------------------ error + uid codec ------------------------------ */
 function driverError(code: DriverErrorCode, message: string, data?: unknown): DriverError {
@@ -292,13 +294,267 @@ async function backendNodeIdOf(conn: CdpConnection, loc: ElementLocator): Promis
   }
   return searchLocate(conn, "xpath" in loc ? loc.xpath : loc.text);
 }
-async function fullPageClip(conn: CdpConnection): Promise<{ x: number; y: number; width: number; height: number }> {
-  const m = await conn.send<{ cssContentSize?: { width: number; height: number }; contentSize?: { width: number; height: number } }>("Page.getLayoutMetrics");
+/**
+ * The Page.getLayoutMetrics reply, read off a live browser rather than guessed. Measured shape,
+ * Chrome/151.0.7922.76 on a deviceScaleFactor-2 display (2026-08-10):
+ *   layoutViewport   {pageX:0,pageY:0,clientWidth:2780,clientHeight:2128}
+ *   visualViewport   {offsetX,offsetY,pageX,pageY,clientWidth:2780,clientHeight:2128,scale:1,zoom:1}
+ *   contentSize      {x,y,width:2780,height:2128}
+ *   cssLayoutViewport{pageX:0,pageY:0,clientWidth:1390,clientHeight:1064}
+ *   cssVisualViewport{offsetX,offsetY,pageX,pageY,clientWidth:1390,clientHeight:1064,scale:1,zoom:1}
+ *   cssContentSize   {x,y,width:1390,height:1064}
+ * The css-prefixed rects are CSS px and the legacy twins carry the SAME rect in device px, so their
+ * clientWidth ratio is the live device-pixel multiplier (2 here). Every field is optional on this
+ * type because the css-prefixed family is the newer half of the reply and an older Chrome answers
+ * with only the legacy names.
+ *
+ * THE UNIT RULE HAS ONE MEASURED EXCEPTION, and it is a live footgun rather than trivia: on a
+ * scrolled page `visualViewport.pageX`/`pageY` come back in CSS px, not device px, while
+ * `clientWidth`/`clientHeight` on that very same rect stay device px. Scrolled to 700/4593 above:
+ * cssVisualViewport 700/4593, cssLayoutViewport 700/4593, visualViewport 700/4593 (CSS!),
+ * layoutViewport 1400/9186 (device). scrollOffsetCssPx below is the one reader of those offsets and
+ * spells out which fields it trusts and why.
+ */
+interface LayoutMetrics {
+  layoutViewport?: { pageX?: number; pageY?: number; clientWidth?: number; clientHeight?: number };
+  visualViewport?: { pageX?: number; pageY?: number; clientWidth?: number; clientHeight?: number };
+  contentSize?: { width: number; height: number };
+  cssLayoutViewport?: { pageX?: number; pageY?: number; clientWidth?: number; clientHeight?: number };
+  cssVisualViewport?: { pageX?: number; pageY?: number; clientWidth?: number; clientHeight?: number };
+  cssContentSize?: { width: number; height: number };
+}
+async function layoutMetrics(conn: CdpConnection): Promise<LayoutMetrics> {
+  return conn.send<LayoutMetrics>("Page.getLayoutMetrics");
+}
+/**
+ * The rect a capture with no element clip covers — for `fullPage`, and ALSO for the plain
+ * no-clip-no-fullPage call, because on this driver those two are the same picture. Measured, not
+ * assumed: captureBeyondViewport is hardcoded true just below, so a no-clip capture of a 1390x3250
+ * css-px document at scroll y=1200 returned 2780x6500 device px from the document ORIGIN — the
+ * same 72490 bytes, sha256 ab46801c…, as the same page captured with fullPage:true.
+ *
+ * That is why a scaled plain capture synthesizes THIS clip and not cssVisualViewport (which the
+ * metrics reply also carries: pageX/pageY = the scroll offset, clientWidth/clientHeight = the
+ * VISIBLE 1390x1064). Clipping to the visual viewport would make `scale` do two things at once —
+ * multiply the resolution AND silently crop 3250 css px of document down to 1064 — so `--scale 3`
+ * would return a different picture than `--scale 1`, not a bigger one. Here scale only ever
+ * multiplies: 2780x6500 at scale 1 -> 5560x13000 at scale 2, same framing.
+ */
+function contentClip(m: LayoutMetrics): { x: number; y: number; width: number; height: number } {
   const size = m.cssContentSize ?? m.contentSize;
   if (!size) throw driverError("page-error", "Page.getLayoutMetrics returned no content size");
   return { x: 0, y: 0, width: Math.ceil(size.width), height: Math.ceil(size.height) };
 }
-async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{ x: number; y: number; width: number; height: number }> {
+/**
+ * How many output pixels one CSS px of clip becomes BEFORE `scale` is applied — the display's (or
+ * emulation override's) device-pixel multiplier, read as the ratio between the device-px and CSS-px
+ * copies of the same viewport rect rather than from window.devicePixelRatio (no extra round trip,
+ * same source of truth as the capture itself). Measured: clip {100x100, scale:1} on a ratio-2
+ * display returns a 200x200 PNG, so this factor really does multiply into the encoded size.
+ * Falls back to 1 when a metrics reply carries only one of the two rects.
+ */
+function devicePixelsPerCssPx(m: LayoutMetrics): number {
+  const css = m.cssVisualViewport?.clientWidth ?? m.cssLayoutViewport?.clientWidth;
+  const dev = m.visualViewport?.clientWidth ?? m.layoutViewport?.clientWidth;
+  if (!css || !dev) return 1;
+  const ratio = dev / css;
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : 1;
+}
+/**
+ * The page's scroll offset in CSS px — what has to be ADDED to a viewport-relative rect to make it
+ * document-absolute, which is the frame `Page.captureScreenshot` reads its clip in whenever
+ * captureBeyondViewport is true (hardcoded true below).
+ *
+ * WHICH FIELD, MEASURED rather than inferred from the "css" prefix, because that prefix is NOT a
+ * clean CSS-px/device-px split for the offsets. Same reply, same instant, page scrolled to
+ * window.scrollX/scrollY = 700/4593 on a deviceScaleFactor-2 display (Chrome/151.0.7922.76,
+ * 2026-08-10):
+ *   cssVisualViewport  pageX/pageY = 700 / 4593   <- CSS px  (what this returns)
+ *   cssLayoutViewport  pageX/pageY = 700 / 4593   <- CSS px, identical
+ *   visualViewport     pageX/pageY = 700 / 4593   <- CSS px TOO, despite clientWidth/clientHeight
+ *                                                    on that same rect reading 2780x2128 (device px)
+ *   layoutViewport     pageX/pageY = 1400 / 9186  <- device px, exactly 2x
+ * So `visualViewport` mixes units WITHIN one rect, and is the one field a "no css prefix means
+ * device px" assumption would silently double. It is never read here.
+ *
+ * The legacy fallback rides `layoutViewport` over the measured ratio (9186/2 = 4593 exactly) and is
+ * only reachable on a Chrome old enough to answer with no css-prefixed rects at all — where
+ * devicePixelsPerCssPx above has already fallen back to 1 and contentClip is already handing Chrome
+ * the DEVICE-px contentSize as a clip. The division is what keeps this offset in whatever frame the
+ * rest of the reply put the file in, rather than correcting into a frame nothing else is using.
+ */
+function scrollOffsetCssPx(m: LayoutMetrics, devicePx: number): { x: number; y: number } {
+  const css = m.cssVisualViewport ?? m.cssLayoutViewport;
+  if (css) return { x: css.pageX ?? 0, y: css.pageY ?? 0 };
+  const legacy = m.layoutViewport;
+  if (legacy) return { x: (legacy.pageX ?? 0) / devicePx, y: (legacy.pageY ?? 0) / devicePx };
+  return { x: 0, y: 0 };
+}
+/**
+ * Chrome's per-side encode limit. MEASURED against Chrome/151.0.7922.76, clip width x height in
+ * CSS px at the given scale on a device-pixel-ratio-2 display, so the encoded size is
+ * ceil(css * scale * ratio):
+ *   1024x100 @8  -> 16384x1600 encoded: OK in ~1s
+ *   1025x100 @8  -> 16400x1600 encoded: Page.captureScreenshot NEVER ANSWERS (killed at 45s, and
+ *                   again at 180s on a fresh tab) — 16 px over the cap and the command just hangs
+ *   100x1024 @8  -> 1600x16384 encoded: OK in ~1s     (same cap on the other axis)
+ *   100x1025 @8  -> 1600x16400 encoded: hangs the same way
+ *   100x1064 @16 -> 3200x34048 encoded: fails fast with the opaque CDP error
+ *                   "Page.captureScreenshot: Unable to capture screenshot"
+ * So the failure is not a silent clamp — but it is either a wedged command or an error naming no
+ * dimension, which is why this is refused BEFORE the capture, with the numbers spelled out.
+ *
+ * And the cost of just letting Chrome try is worse than a failed call: captureBeyondViewport
+ * (hardcoded true below) RESIZES the page to the clip for the duration of the capture, and a
+ * capture that never returns never puts it back. After the 1025x100 @8 hang above, that tab was
+ * left reporting window.innerWidth/innerHeight of 8200x800 — the clip's own css size — and every
+ * later screenshot on it timed out too. A refusal here is what keeps a caller's tab intact.
+ */
+const MAX_ENCODED_SIDE_PX = 16384;
+/**
+ * `renderSize` is only for the message. It is named separately because it changes what the caller
+ * should DO about the refusal: past the cap because of `scale`, the fix is a smaller scale, but past
+ * it because a narrow render size made the document reflow taller, the fix is a different render
+ * size (or dropping fullPage) and a "largest scale that fits" hint would be useless advice.
+ */
+function assertClipEncodable(
+  clip: { width: number; height: number },
+  scale: number,
+  devicePx: number,
+  renderSize?: { width: number; height: number },
+): void {
+  const outWidth = Math.ceil(clip.width * scale * devicePx);
+  const outHeight = Math.ceil(clip.height * scale * devicePx);
+  if (outWidth <= MAX_ENCODED_SIDE_PX && outHeight <= MAX_ENCODED_SIDE_PX) return;
+  const at = renderSize ? ` at render size ${renderSize.width}x${renderSize.height}` : "";
+  const projection =
+    `(clip ${clip.width}x${clip.height} css px${at} x scale ${scale} x device pixel ratio ${devicePx}), ` +
+    `past Chrome's ${MAX_ENCODED_SIDE_PX} px per-side limit; `;
+  if (scale !== 1) {
+    // Floor to 2dp: a rounded-UP suggestion would be a scale that fails the same way.
+    const fits = Math.floor((MAX_ENCODED_SIDE_PX / (Math.max(clip.width, clip.height) * devicePx)) * 100) / 100;
+    throw driverError(
+      "page-error",
+      `screenshot scale ${scale} would encode ${outWidth}x${outHeight} px ${projection}` +
+        (fits >= 0.01
+          ? `the largest scale that fits this clip is ${fits}.`
+          : `this clip is already past the limit at scale 1 — capture a smaller region.`),
+    );
+  }
+  const maxCssSide = Math.floor(MAX_ENCODED_SIDE_PX / devicePx);
+  throw driverError(
+    "page-error",
+    `this capture would encode ${outWidth}x${outHeight} px ${projection}` +
+      `at device pixel ratio ${devicePx} the clip may be at most ${maxCssSide} css px per side` +
+      (renderSize
+        ? ` — a narrow renderWidth reflows the document TALLER, so widen it, shorten the page, or drop fullPage.`
+        : ` — capture a smaller region or drop fullPage.`),
+  );
+}
+/** The encoded size a clip projects to, the one number every guard and every band decision is made
+ *  on. `scale` and the device pixel ratio BOTH multiply — measured, see devicePixelsPerCssPx. */
+function projectedSide(cssLength: number, scale: number, devicePx: number): number {
+  return Math.ceil(cssLength * scale * devicePx);
+}
+
+/**
+ * How the capture is split, decided before a single Page.captureScreenshot is sent. Pure and
+ * exported so the arithmetic is unit-testable without a browser: getting it wrong is invisible in
+ * a small test and catastrophic on a 140,000 px page.
+ *
+ * BAND HEIGHT IS IN CSS PX AND SO IS clip.y, and that is MEASURED, not assumed. A ruler page with
+ * a marker at CSS y=4000-4008, clipped {y:3980,height:40}, put the marker at the same CSS position
+ * at scale 1 and at scale 2 — the output was simply twice the resolution. So a band advances by
+ * bandHeightCss regardless of scale or device pixel ratio; multiplying the offset by either would
+ * skip or repeat that factor's worth of page on every seam.
+ *
+ * WHY `tile:true` ON A FITTING REGION STILL SPLITS IN TWO. The flag exists so the banded path can
+ * be exercised on an ordinary page. A band height derived only from the cap would return ONE band
+ * for any page small enough to be convenient to test, i.e. `tile:true` would be a no-op on exactly
+ * the pages someone would use it to check seams with. So an explicit `true` also halves a region
+ * that already fits. It stays lossless either way (the stitcher is byte-exact; a seam is not a
+ * resample), and the result reports the band count honestly.
+ */
+export interface TilePlan {
+  tiled: boolean;
+  /** How many Page.captureScreenshot calls. 1 when not tiled. */
+  bandCount: number;
+  /** CSS-px height of every band but the last; the last is the remainder. */
+  bandHeightCss: number;
+}
+export function planTiledCapture(
+  clip: { width: number; height: number },
+  scale: number,
+  devicePx: number,
+  tile: boolean | undefined,
+): TilePlan {
+  const untiled: TilePlan = { tiled: false, bandCount: 1, bandHeightCss: clip.height };
+  if (tile === false) return untiled;
+  const fits =
+    projectedSide(clip.width, scale, devicePx) <= MAX_ENCODED_SIDE_PX &&
+    projectedSide(clip.height, scale, devicePx) <= MAX_ENCODED_SIDE_PX;
+  if (fits && tile !== true) return untiled;
+  // WIDTH CANNOT BE TILED, and this refusal is the deliberate edge of the feature's scope. The
+  // stitcher concatenates PNG scanlines, so it can only grow the image downward; a too-wide
+  // capture would need a grid and a horizontal join it cannot do. Refusing names the two knobs
+  // that actually shrink a width — the alternative, silently capturing 16384 px of a wider page,
+  // would hand back a truncated picture indistinguishable from a complete one.
+  const outWidth = projectedSide(clip.width, scale, devicePx);
+  if (outWidth > MAX_ENCODED_SIDE_PX) {
+    const maxCssWidth = Math.floor(MAX_ENCODED_SIDE_PX / (scale * devicePx));
+    throw driverError(
+      "page-error",
+      `this capture is ${outWidth} px WIDE (clip ${clip.width} css px x scale ${scale} x device pixel ratio ${devicePx}), ` +
+        `past Chrome's ${MAX_ENCODED_SIDE_PX} px per-side limit, and width cannot be tiled: bands are stitched ` +
+        `vertically only. Lower scale (at most ${Math.floor((MAX_ENCODED_SIDE_PX / (clip.width * devicePx)) * 100) / 100}), ` +
+        `or set renderWidth at most ${maxCssWidth} css px, or clip to a narrower element.`,
+    );
+  }
+  // The largest band whose PROJECTION still fits: ceil(h x scale x devicePx) <= cap. The loop is a
+  // floating-point backstop — floor() alone is right for every integer ratio, but a fractional
+  // scale x ratio can land a hair above the cap after ceil(), and a band one pixel over is not an
+  // off-by-one, it is the hang this whole feature exists to avoid. Measured by mutation: dropping
+  // devicePx from the floor() alone changes NOTHING, because the loop walks the value back down to
+  // the same answer (slowly, one px at a time). The loop is the correctness; the floor is the speed.
+  let bandHeightCss = Math.floor(MAX_ENCODED_SIDE_PX / (scale * devicePx));
+  while (bandHeightCss > 1 && projectedSide(bandHeightCss, scale, devicePx) > MAX_ENCODED_SIDE_PX) bandHeightCss -= 1;
+  // UNREACHABLE AS THINGS STAND, and said so rather than presented as a live branch: a band height
+  // below 1 needs scale x devicePx past the cap, and every clip is at least 1 css px wide (both
+  // clip builders ceil, and a zero-area element is refused before this), so the width check above
+  // has already thrown. Kept because it is the invariant the loop depends on — a zero band height
+  // would make bandCount infinite — not because a caller can get here today.
+  if (bandHeightCss < 1) {
+    throw driverError(
+      "page-error",
+      `scale ${scale} at device pixel ratio ${devicePx} projects a single css pixel to ${scale * devicePx} device px, ` +
+        `past the ${MAX_ENCODED_SIDE_PX} px limit — no band height can fit. Lower scale.`,
+    );
+  }
+  // An explicit `true` on a region that already fits: split it for real (see the header).
+  if (tile === true && clip.height <= bandHeightCss) bandHeightCss = Math.max(1, Math.ceil(clip.height / 2));
+  return { tiled: true, bandCount: Math.max(1, Math.ceil(clip.height / bandHeightCss)), bandHeightCss };
+}
+
+/**
+ * The element's content box, in CSS px and VIEWPORT-RELATIVE — which is the frame
+ * `DOM.getBoxModel` answers in, measured rather than assumed: on a 10,000 css px document scrolled
+ * to y=4593, the quad for an element whose real document position is y=5000 came back at y=407,
+ * matching `getBoundingClientRect().top` to the pixel. NOT a capture clip; see documentClip below
+ * for the frame conversion that has to happen before this can be one.
+ *
+ * THE SCROLL IS DELIBERATE, AND IT IS NOT WHAT MAKES THE CLIP CORRECT. With captureBeyondViewport
+ * (hardcoded true in capture()) Chrome renders the whole document, so nothing here has to be on
+ * screen to be captured, and the REJECTED ALTERNATIVE was to drop this call entirely and read the
+ * box model where the page already sat. Measured consequence of dropping it, on a fixture whose
+ * target only fills itself from an IntersectionObserver: with the scroll, the capture reads
+ * "LAZY CONTENT LOADED"; without it, the same capture returns the element's "NOT LOADED
+ * (placeholder)" state in the right region — because captureBeyondViewport renders what the DOM
+ * currently IS (the tab still reported the placeholder text afterwards, scrollY 0), and never
+ * triggers a viewport-driven load. So the scroll buys lazy content, costs one round trip, and the
+ * document-frame correction below is what buys correctness. Keeping it also means the offset this
+ * scroll CREATES must be read after it settles — see capture()'s ordering.
+ */
+async function elementBox(conn: CdpConnection, loc: ElementLocator): Promise<{ x: number; y: number; width: number; height: number }> {
   const backendNodeId = await backendNodeIdOf(conn, loc);
   await conn.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }).catch(() => undefined);
   const box = await conn.send<{ model: { content: number[] } }>("DOM.getBoxModel", { backendNodeId });
@@ -311,6 +567,36 @@ async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{
   if (width <= 0 || height <= 0) throw driverError("page-error", "resolved element has zero area");
   return { x: minX, y: minY, width, height };
 }
+/**
+ * A viewport-relative element box -> the document-absolute clip `Page.captureScreenshot` actually
+ * wants. THE BUG THIS FIXES, measured on Chrome/151.0.7922.76: the box model's own x/y used to be
+ * handed straight to the capture, so a `--selector` clip returned the wrong region of the page
+ * whenever bringing the element into view required a scroll. On a 10,000 css px document with the
+ * target at y=5000, `DOM.scrollIntoViewIfNeeded` left the page at scrollY 4593 and the element at
+ * viewport y=407 — and the capture came back as document[407..657], a flat slab of page background,
+ * with no part of the element in it. Starting the same call from scrollY 4950 instead, where the
+ * element already sat at viewport y=50 and the scroll was a no-op, produced document[50..300]: the
+ * document's own top banner for the first 100 css px, background below, boundary on the predicted
+ * pixel. Both are the same arithmetic — a viewport-relative number read in the document frame —
+ * and the pair is also why the old behaviour depended on where the CALLER had left the page.
+ *
+ * Adding the scroll offset is the whole correction, and it is added in CSS px because `clip` is in
+ * CSS px (a clip of {1390 x 1064} on a ratio-2 display encodes 2780x2128, i.e. the multiplier is
+ * applied by Chrome AFTER the clip, not expected in it). Mixing in the device-px twin of the offset
+ * would be the same class of bug wearing different units.
+ *
+ * `scale`, `renderWidth`/`renderHeight` and `tile` all ride this same corrected rect and needed no
+ * changes of their own: scale only ever rides clip.scale, a render size reflows the document before
+ * anything here is measured, and the band walker starts from clip.y and walks in CSS px.
+ */
+function documentClip(
+  box: { x: number; y: number; width: number; height: number },
+  m: LayoutMetrics,
+  devicePx: number,
+): { x: number; y: number; width: number; height: number } {
+  const scroll = scrollOffsetCssPx(m, devicePx);
+  return { x: box.x + scroll.x, y: box.y + scroll.y, width: box.width, height: box.height };
+}
 /**
  * Chrome capabilities. network.responseBodyPostHoc is deliberately NOT declared: the Network
  * domain is enabled lazily (only by startBodyCapture/intercept), so a body is only readable for
@@ -342,11 +628,28 @@ async function elementClip(conn: CdpConnection, loc: ElementLocator): Promise<{
  * is declared for BiDi: Firefox's browsingContext.downloadWillBegin/downloadEnd exist but there is
  * no BiDi command to redirect a download to a chosen directory, and BiDi has no permission-granting
  * command at all outside the optional `permissions` module this driver does not negotiate.
+ * screenshot.scale rides Page.captureScreenshot's clip.scale, a per-CALL output multiplier that
+ * leaves page emulation untouched (the deviceScaleFactor workaround does not: it re-lays-out the
+ * page and persists until cleared). It is a PARAM-level capability like input.html5Drag, so
+ * take_screenshot stays universal and only the `scale` argument is gated; WebDriver BiDi's
+ * browsingContext.captureScreenshot has no scale parameter at all, so it is honestly Chrome-only.
+ * screenshot.renderSize rides Emulation.setDeviceMetricsOverride applied for the length of one
+ * capture and undone in a finally. Unlike screenshot.scale this is NOT a Chrome-only gap: BiDi's
+ * browsingContext.setViewport is a real equivalent and the Firefox driver declares it too. Both
+ * drivers already declare emulate.deviceMetrics on the very same primitive, so a backend that could
+ * not honour this would be a backend that cannot emulate a viewport at all.
+ * screenshot.tile rides the SAME clip.scale primitive as screenshot.scale, sent once per band with
+ * clip.y walked down the document, plus ../png.ts's stitcher. It is declared here and NOT for BiDi,
+ * for the honest reason rather than a protocol one: band tiling was measured against a real Chrome
+ * (fixed and sticky elements do not repeat per band, seams are pixel-exact, clipped bands are
+ * scroll-independent, and clip.y/clip.height stay CSS px while scale only changes resolution), and
+ * no Firefox was driven to measure the same for browsingContext.captureScreenshot's clip:{type:"box"}.
+ * Declaring an unmeasured tiling would be claiming a capability on the strength of a spec reading.
  */
 const CDP_CAPABILITIES: ReadonlySet<Capability> = new Set<Capability>([
   "trace.performance", "heap.snapshot", "audit.lighthouse", "emulate.cpuThrottling",
   "emulate.mediaFeatures", "emulate.deviceMetrics", "emulate.networkConditions",
-  "screenshot.fullPage", "screenshot.element", "network.intercept",
+  "screenshot.fullPage", "screenshot.element", "screenshot.scale", "screenshot.renderSize", "screenshot.tile", "network.intercept",
   "snapshot.accessibilityTree", "input.insertTextAtomic", "locate.text", "locate.xpath",
   "capture.screencast", "input.raw", "input.html5Drag",
   "browser.downloads", "browser.permissions", "worker.targets",
@@ -718,27 +1021,272 @@ class CdpPageDriver implements PageDriver {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     await this.conn.send("DOM.setFileInputFiles", { files: [...files], objectId });
   }
-  async screenshot(opts?: ScreenshotOptions): Promise<{ data: Uint8Array; format: "png" | "jpeg" }> {
+  /**
+   * A capture, optionally rendered at an emulated viewport that is put back afterwards.
+   *
+   * ORDERING IS THE WHOLE CORRECTNESS ARGUMENT. The override goes on FIRST, before anything is
+   * measured, because narrowing the viewport reflows the document: capture() reads
+   * Page.getLayoutMetrics for fullPage's content rect and for the device-pixel projection, and
+   * elementClip reads a box model, and all three answer differently at 1920 wide than at 390. That
+   * also puts assertClipEncodable on the POST-override numbers, so a 1920-wide render at scale 4 is
+   * refused on the size it would really encode rather than on the tab's old size.
+   *
+   * NO REFLOW WAIT, and that is measured rather than assumed. Emulation.setDeviceMetricsOverride
+   * resolves only once layout has settled: on a page with a `@media (max-width:900px)` rule, an
+   * IMMEDIATE getLayoutMetrics + captureScreenshot after the override matched one taken after a
+   * double-requestAnimationFrame round-trip on every field — content rect, computed background
+   * colour (the media query had already flipped), a grid child's height (236.47 vs 444.46 px across
+   * the breakpoint), and the PNG's own sha256. Three transitions, 1920x1080 -> 420x900 -> 1920x1080,
+   * byte-identical each time. So there is deliberately no sleep here; adding a speculative one would
+   * be untestable latency on every capture.
+   *
+   * RESTORE RUNS ON EVERY EXIT. A thrown guard (assertClipEncodable), a per-command timeout, a
+   * page-side failure — the capture's error is held, the viewport is put back, and only then does
+   * the error propagate. Leaving it unrestored is the exact failure this feature exists to avoid:
+   * an aborted capture that strands a device-metrics override poisons every later measurement on
+   * that tab (innerHeight stuck at the content height) and is expensive to even diagnose. When the
+   * restore ITSELF fails there is no result to carry the bad news, so the fact is appended to the
+   * error message instead — the caller's page really is still emulated and silence would be a lie.
+   *
+   * A BANDED CAPTURE HOLDS THE OVERRIDE FOR ITS WHOLE LENGTH, deliberately. capture() awaits the
+   * band consumer, so this method does not reach its restore until the last band has been captured
+   * AND written. That is the only correct ordering: every band has to be rendered at the same
+   * emulated viewport, and putting the viewport back halfway would reflow the document under the
+   * remaining bands and stitch two different layouts into one image.
+   */
+  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, consumeBands);
+    // Read BEFORE applying ours: our own setDeviceMetricsOverride overwrites the browser's state
+    // and there is no CDP command that reads a device-metrics override back out.
+    const previous = await readViewportRecord(this.browser.scheme, this.info.id);
+    await this.conn.send("Emulation.setDeviceMetricsOverride", {
+      width: renderSize.width,
+      height: renderSize.height,
+      // Inherited, not reset: the caller asked to change the render SIZE. Dropping a
+      // deviceScaleFactor or mobile flag they set with emulate would be a second, silent change.
+      deviceScaleFactor: previous?.deviceScaleFactor ?? 0,
+      mobile: previous?.mobile ?? false,
+    });
+    let shot: CaptureDelivery<T> | undefined;
+    let captureError: unknown;
+    try {
+      shot = await this.capture(opts, consumeBands);
+    } catch (e) {
+      captureError = e;
+    }
+    let restoreError: string | undefined;
+    try {
+      // Re-apply, never clear, when we know what was there: clearDeviceMetricsOverride resets to the
+      // REAL device (measured — see ViewportRecord's header), so clearing here would silently
+      // destroy an override the caller set with emulate earlier and believes is still in force.
+      if (previous) {
+        await this.conn.send("Emulation.setDeviceMetricsOverride", {
+          width: previous.width,
+          height: previous.height,
+          deviceScaleFactor: previous.deviceScaleFactor ?? 0,
+          mobile: previous.mobile ?? false,
+        });
+      } else {
+        await this.conn.send("Emulation.clearDeviceMetricsOverride");
+      }
+    } catch (e) {
+      restoreError = e instanceof Error ? e.message : String(e);
+    }
+    if (!shot) {
+      // Mutate rather than re-wrap: a DriverError's `code` ("timeout", "page-error", ...) is what
+      // callers branch on, and a fresh error would throw that away to add one sentence.
+      if (restoreError !== undefined && captureError instanceof Error) {
+        captureError.message = `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`;
+      }
+      throw captureError;
+    }
+    // Object.assign onto the result we just built, rather than a spread: `shot` is a union
+    // (bytes or bands) and mutating it keeps whichever arm it is, discriminant and all.
+    const result = Object.assign(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<T>(opts?: ScreenshotOptions, consumeBands?: BandConsumer<T>): Promise<CaptureDelivery<T>> {
     await this.ensureDomain("Page");
     const format = opts?.format ?? "png";
     const quality = format === "jpeg" ? (opts?.quality ?? 80) : undefined;
+    // scale absent (or exactly 1) must leave this call byte-for-byte what it was: clip.scale stays
+    // 1 on the element/fullPage paths and the plain no-clip path still sends NO clip at all.
+    const scale = opts?.scale ?? 1;
+    const renderSize =
+      opts?.renderWidth !== undefined && opts?.renderHeight !== undefined
+        ? { width: opts.renderWidth, height: opts.renderHeight }
+        : undefined;
+    // ONE Page.getLayoutMetrics, now fetched on EVERY capture, and the plain path's round trip is
+    // bought deliberately. It used to be skipped when nothing needed a clip — which meant the guard
+    // below never ran there, and that path is NOT the viewport capture it reads as:
+    // captureBeyondViewport is hardcoded true, so a plain take_screenshot already captures the whole
+    // document. MEASURED consequence of the old skip: a plain capture of any page past ~8192 css px
+    // (on a ratio-2 display) hangs Page.captureScreenshot and leaves the tab stuck at the content
+    // size, no flags required. Auto-tiling has to know the projection anyway, so one round trip now
+    // decides all three outcomes — one shot, bands, or a refusal — instead of none of them.
+    //
+    // AND THE ELEMENT BOX IS READ FIRST, BEFORE THE METRICS. That ordering is load-bearing, not
+    // style: elementBox calls DOM.scrollIntoViewIfNeeded, which MOVES the scroll offset that
+    // documentClip then has to add. Metrics read before the scroll carry the OLD offset (measured:
+    // 0 on a freshly navigated tab where the scroll then lands at 4593), and correcting by a stale
+    // offset is the same bug with a smaller error. Read after, and one round trip still serves both
+    // the projection and the correction — no second Page.getLayoutMetrics for the element path.
+    const box = opts?.clip ? await elementBox(this.conn, opts.clip) : undefined;
+    const metrics = await layoutMetrics(this.conn);
+    const devicePx = devicePixelsPerCssPx(metrics);
+    // The rect this capture covers, ALWAYS computed even when it is not sent. For the plain path
+    // this is the clip Chrome infers for itself (measured byte-identical to fullPage, see
+    // contentClip), so projecting it is projecting what Chrome is really about to encode.
+    const clip = box ? documentClip(box, metrics, devicePx) : contentClip(metrics);
+    // Which calls put a clip ON THE WIRE is unchanged, and that is what keeps a fitting capture
+    // byte-for-byte what it was: the plain no-clip call still sends no clip at all, and only the
+    // element / fullPage / scale / render-size paths synthesize one (clip.scale being the only
+    // place scale can ride).
+    const sendsClip = opts?.clip !== undefined || opts?.fullPage === true || scale !== 1 || renderSize !== undefined;
+    // A caller with nowhere to put bands cannot be given any: it gets the encode guard's refusal
+    // instead, which is the pre-tiling behaviour and still keeps the tab alive.
+    if (opts?.tile === true && !consumeBands) {
+      throw driverError("unsupported", "screenshot tile:true needs a caller that can consume bands; this one passed no band consumer");
+    }
+    const plan = planTiledCapture(clip, scale, devicePx, consumeBands ? opts?.tile : false);
+    if (plan.tiled) return this.captureTiled(clip, plan, scale, format, consumeBands!);
+    // Guarded here, not in the tool layer: the clip is only known once it has been measured.
+    //
+    // DELIBERATELY NOT CONDITIONED ON scale !== 1, NOR ON A CLIP BEING SENT, and both were live-fire
+    // bugs rather than tidy-ups. `--fullPage --renderWidth 420 --renderHeight 900` at scale 1 on a
+    // 4-column grid page reflowed the document from 2880 to 10800 css px tall, projected to
+    // 840x21600 device px, sailed past this guard because the scale was 1, and WEDGED the tab. The
+    // no-clip default path wedged it the same way for the same reason: no clip sent, so no guard.
+    // Guard the PROJECTION, never the knob that happened to motivate the guard.
+    //
+    // And the restore could not save it. Measured with CDP_TIMEOUT_MS=8000: the capture timed out
+    // client-side, the restore ran and SUCCEEDED (the error carried no restore-failure note), and
+    // the page was still 420x10800 afterwards — because the timeout is only local, Chrome's capture
+    // is still running, and it re-resizes the page after the restore lands. A finally cannot beat a
+    // command that is still executing, so this pre-flight refusal is the only real protection.
+    assertClipEncodable(clip, scale, devicePx, renderSize);
     const params: Record<string, unknown> = { format, captureBeyondViewport: true };
     if (quality != null) params.quality = quality;
-    if (opts?.clip) params.clip = { ...(await elementClip(this.conn, opts.clip)), scale: 1 };
-    else if (opts?.fullPage) params.clip = { ...(await fullPageClip(this.conn)), scale: 1 };
+    if (sendsClip) params.clip = { ...clip, scale };
     const { data } = await this.conn.send<{ data: string }>("Page.captureScreenshot", params);
     return { data: new Uint8Array(Buffer.from(data, "base64")), format };
   }
+  /** Hand the consumer a lazy band sequence and wait for it to finish with it. */
+  private async captureTiled<T>(
+    clip: { x: number; y: number; width: number; height: number },
+    plan: TilePlan,
+    scale: number,
+    format: "png" | "jpeg",
+    consumeBands: BandConsumer<T>,
+  ): Promise<TiledScreenshotResult<T>> {
+    const capture: BandedCapture = {
+      bands: this.bands(clip, plan, scale, format),
+      bandCount: plan.bandCount,
+      bandHeightCss: plan.bandHeightCss,
+      clip,
+      format: "png",
+    };
+    const consumed = await consumeBands(capture);
+    return { tiled: true, format: "png", bandCount: plan.bandCount, bandHeightCss: plan.bandHeightCss, consumed };
+  }
+  /**
+   * The bands themselves, one Page.captureScreenshot at a time and only when pulled.
+   *
+   * clip.y advances in CSS px and the last band is the REMAINDER, not a full band: asking for a
+   * full-height last band would extend the clip past the document, and the sum of the band heights
+   * has to be the region's height exactly or the stitched image is taller than the page.
+   *
+   * No scroll management, deliberately: measured on this Chrome, the identical clip captured at
+   * three different real scroll positions produced three byte-identical PNGs, so a band is a pure
+   * function of its clip. Nothing here has to move, restore, or even read the page's scroll.
+   */
+  private async *bands(
+    clip: { x: number; y: number; width: number; height: number },
+    plan: TilePlan,
+    scale: number,
+    format: "png" | "jpeg",
+  ): AsyncGenerator<Uint8Array> {
+    // Backstop, and it lives INSIDE the generator on purpose: shared-tools.ts refuses format:"jpeg"
+    // with a message naming the fix, from the band consumer, which runs before the first band is
+    // pulled. Checking earlier than this made the driver's terse message win over the tool layer's
+    // useful one (live-fired: `--format jpeg` on a 140,982 px page reported "got format jpeg" and
+    // nothing about what to do). Here it only fires for a consumer that ACCEPTED a jpeg banded
+    // capture, which no shipping caller does — it exists so a future one cannot get a sequence of
+    // JPEGs that the PNG stitcher would reject with a confusing parse error instead.
+    if (format !== "png") {
+      throw driverError("unsupported", `a tiled capture is PNG-only (bands are stitched as PNG scanlines); got format "${format}"`);
+    }
+    const bottom = clip.y + clip.height;
+    for (let i = 0; i < plan.bandCount; i++) {
+      const y = clip.y + i * plan.bandHeightCss;
+      const height = Math.min(plan.bandHeightCss, bottom - y);
+      const { data } = await this.conn.send<{ data: string }>("Page.captureScreenshot", {
+        format: "png",
+        captureBeyondViewport: true,
+        clip: { x: clip.x, y, width: clip.width, height, scale },
+      });
+      yield new Uint8Array(Buffer.from(data, "base64"));
+    }
+  }
   // Adapted from src/tools/emulation.ts `emulate`.
   async emulate(opts: EmulationOptions): Promise<{ applied: string[] }> {
     if (opts.clearOverrides) {
       const c = () => undefined;
-      await this.conn.send("Emulation.clearDeviceMetricsOverride").catch(c);
+      // MEASURED BUG, now fixed: a bare Emulation.clearDeviceMetricsOverride on a FRESH connection
+      // is a no-op — it resolves with {} (success) while a stale override some OTHER, now-
+      // disconnected process set stays fully in force (see ViewportRecord's header comment in
+      // ../driver.ts for the two-process proof). Under this toolkit's per-call driver lifetime, the
+      // connection that runs clearOverrides is essentially NEVER the connection that ran the
+      // original emulate, so this was the COMMON case, not an edge case — `emulate` was the
+      // documented wedged-tab recovery procedure, and it was silently doing nothing.
+      //
+      // Remedy, measured to work every time (../driver.ts's ViewportRecord header, the A/B/C/D/E/F
+      // trace): "set an override, then clear it" — clearDeviceMetricsOverride only reverts to the
+      // REAL device when the clearing connection is ALSO the one that set the override, so setting
+      // one first on THIS connection makes it the override's owner and turns the clear that follows
+      // into a real one. The numbers used to "set" do not matter for correctness (clearing always
+      // lands on the real device once this connection owns an override) — but they matter for being
+      // side-effect-free, so read the layout's CURRENT size first and re-apply exactly that: the
+      // page never visibly moves, only this connection's ownership of the override changes.
+      let metricsClearError: string | undefined;
+      try {
+        await this.ensureDomain("Page");
+        const metrics = await layoutMetrics(this.conn);
+        const width =
+          metrics.cssVisualViewport?.clientWidth ?? metrics.cssLayoutViewport?.clientWidth ??
+          metrics.visualViewport?.clientWidth ?? metrics.layoutViewport?.clientWidth ?? 1;
+        const height =
+          metrics.cssVisualViewport?.clientHeight ?? metrics.cssLayoutViewport?.clientHeight ??
+          metrics.visualViewport?.clientHeight ?? metrics.layoutViewport?.clientHeight ?? 1;
+        await this.conn.send("Emulation.setDeviceMetricsOverride", { width, height, deviceScaleFactor: 0, mobile: false });
+        await this.conn.send("Emulation.clearDeviceMetricsOverride");
+      } catch (e) {
+        metricsClearError = e instanceof Error ? e.message : String(e);
+      }
       await this.conn.send("Emulation.setUserAgentOverride", { userAgent: "" }).catch(c);
       await this.conn.send("Emulation.setCPUThrottlingRate", { rate: 1 }).catch(c);
       await this.conn.send("Emulation.setEmulatedMedia", { media: "", features: [] }).catch(c);
       await this.ensureDomainSoft("Network");
       await this.conn.send("Network.emulateNetworkConditions", { offline: false, latency: 0, downloadThroughput: -1, uploadThroughput: -1 }).catch(c);
+      if (metricsClearError !== undefined) {
+        // Honest failure, not a lie wearing success's shape: `cleared: true` must mean the page
+        // really is back at the real device, and CONTRACT.md #65 says throw on failure rather than
+        // return an error sentinel. The record is deliberately LEFT IN PLACE: we could not confirm
+        // the browser-side override is gone, so it remains the best available description of what
+        // the page may still be showing.
+        throw driverError("page-error", `emulate: could not verify the device-metrics override was cleared (${metricsClearError})`);
+      }
+      // Only forget the recorded override once the clear that supersedes it is confirmed to have
+      // actually run — a record dropped before that point could make a later render-size capture
+      // "restore" an override that never left.
+      await clearViewportRecord(this.browser.scheme, this.info.id);
       return { applied: [] };
     }
     const applied: string[] = [];
@@ -754,6 +1302,15 @@ class CdpPageDriver implements PageDriver {
         deviceScaleFactor: opts.deviceScaleFactor ?? 0,
         mobile: opts.mobile ?? false,
       });
+      // Recorded so a later render-size capture puts THIS back instead of clearing to the real
+      // device. Written after the command succeeds, so a rejected override leaves no record
+      // claiming an override that is not there. See ViewportRecord in ../driver.ts.
+      await writeViewportRecord(this.browser.scheme, this.info.id, {
+        width: opts.width,
+        height: opts.height,
+        deviceScaleFactor: opts.deviceScaleFactor ?? 0,
+        mobile: opts.mobile ?? false,
+      });
       applied.push("deviceMetrics");
     }
     if (opts.userAgent != null) {
@@ -1266,4 +1823,32 @@ export { CdpBrowserDriver, CdpPageDriver };
  *     startBodyCapture / emulate's networkConditions branch), never eagerly by page(), so a
  *     body is only readable for a request that occurred after something armed capture first.
  *     That is arming by another name, not "not armed in advance".
+ *   - screenshot.scale rides clip.scale, so a scaled no-clip capture has to synthesize the clip
+ *     Page.captureScreenshot otherwise infers (contentClip, off Page.getLayoutMetrics — measured
+ *     to be the same picture as fullPage, because captureBeyondViewport is always true here).
+ *     Output px is ceil(cssPx * scale * devicePixelRatio) — the ratio multiplies in, measured —
+ *     and anything past 16384 px a side is refused BEFORE the call, because Chrome's own answer
+ *     there is either a hang or an error naming no dimension (see MAX_ENCODED_SIDE_PX).
+ *   - screenshot.renderSize rides Emulation.setDeviceMetricsOverride, applied before ANYTHING is
+ *     measured (a narrower viewport reflows the document, so the content rect, the element box and
+ *     the encode guard must all be read after it) and undone on every exit path. Restore re-applies
+ *     the record ../driver.ts's writeViewportRecord kept, never a bare clear: measured,
+ *     Emulation.clearDeviceMetricsOverride is a NO-OP for an override another session set, and once
+ *     this session sets one it reverts to the REAL device — so clearing would silently destroy a
+ *     caller's earlier emulate. NOT a Chrome-only capability: the BiDi driver declares it too.
+ *   - The encode guard is deliberately NOT conditioned on scale, since 1.9.2: a scale-1 fullPage at
+ *     a narrow render size reflowed a page from 2880 to 10800 css px tall and wedged the tab. And a
+ *     wedge is not recoverable by the restore — the per-command timeout is client-side only, so
+ *     Chrome's capture is still running and re-resizes the page after the restore lands (measured
+ *     with CDP_TIMEOUT_MS=8000: the restore SUCCEEDED and the tab was still 420x10800). The
+ *     pre-flight refusal is the only real protection; an already-wedged tab is recovered by an
+ *     explicit emulate{width,height}, verified.
+ *   - screenshot.tile rides the same clip primitive, sent once per band with clip.y walked down the
+ *     document in CSS px (measured: clip.y/clip.height are CSS px at every scale), the bands piped
+ *     into ../png.ts's streaming stitcher by the tool layer. Page.getLayoutMetrics is now fetched on
+ *     EVERY capture, including the plain default one, because the projection is what decides one
+ *     shot vs bands vs refusal — and because the plain path was the one place the encode guard could
+ *     not run, which made a plain take_screenshot of a long page a tab-wedger with no flags set.
+ *     Vertical only: a projection too WIDE is refused by name, since PNG scanline concatenation
+ *     cannot join columns.
  * ---------------------------------------------------------------------------- */