cdp-toolkit 1.9.1 → 1.9.5

package/dist/mcp.js

@@ -1121,6 +1121,8 @@ async function clearMocks(args = {}) {
 }
 
 // src/driver.ts
+import { mkdir as mkdir3, readFile as readFile3, unlink as unlink3, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join3 } from "node:path";
 var UID_STAMP_ATTR = "data-cdp-uid";
 var LEGACY_NUMERIC_UID = /^[0-9]+$/;
 var REQUIRED_CAPABILITIES = {
@@ -1150,6 +1152,41 @@ function interpolatePoints(from, to, steps) {
   out.push({ x: to.x, y: to.y });
   return out;
 }
+function isTiledCapture(delivery) {
+  return delivery.tiled === true;
+}
+function viewportRecordFile(scheme, targetId) {
+  return join3(leaseDir(), `viewport-${scheme}-${targetId.replace(/[^A-Za-z0-9._-]/g, "_")}.json`);
+}
+async function readViewportRecord(scheme, targetId) {
+  try {
+    const raw = JSON.parse(await readFile3(viewportRecordFile(scheme, targetId), "utf8"));
+    if (typeof raw?.width !== "number" || typeof raw?.height !== "number")
+      return;
+    return {
+      width: raw.width,
+      height: raw.height,
+      ...typeof raw.deviceScaleFactor === "number" ? { deviceScaleFactor: raw.deviceScaleFactor } : {},
+      ...typeof raw.mobile === "boolean" ? { mobile: raw.mobile } : {}
+    };
+  } catch {
+    return;
+  }
+}
+async function writeViewportRecord(scheme, targetId, rec) {
+  try {
+    await mkdir3(leaseDir(), { recursive: true });
+    await writeFile3(viewportRecordFile(scheme, targetId), JSON.stringify({ scheme, targetId, ...rec }), "utf8");
+  } catch {}
+}
+function renderRestoreFailureNote(size, why) {
+  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}.`;
+}
+async function clearViewportRecord(scheme, targetId) {
+  try {
+    await unlink3(viewportRecordFile(scheme, targetId));
+  } catch {}
+}
 
 // src/cdp/driver.ts
 function driverError(code, message, data) {
@@ -1381,14 +1418,73 @@ async function backendNodeIdOf(conn, loc) {
   }
   return searchLocate(conn, "xpath" in loc ? loc.xpath : loc.text);
 }
-async function fullPageClip(conn) {
-  const m = await conn.send("Page.getLayoutMetrics");
+async function layoutMetrics(conn) {
+  return conn.send("Page.getLayoutMetrics");
+}
+function contentClip(m) {
   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, loc) {
+function devicePixelsPerCssPx(m) {
+  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;
+}
+function scrollOffsetCssPx(m, devicePx) {
+  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 };
+}
+var MAX_ENCODED_SIDE_PX = 16384;
+function assertClipEncodable(clip, scale, devicePx, renderSize) {
+  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) {
+    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.`));
+}
+function projectedSide(cssLength, scale, devicePx) {
+  return Math.ceil(cssLength * scale * devicePx);
+}
+function planTiledCapture(clip, scale, devicePx, tile) {
+  const untiled = { 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;
+  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.`);
+  }
+  let bandHeightCss = Math.floor(MAX_ENCODED_SIDE_PX / (scale * devicePx));
+  while (bandHeightCss > 1 && projectedSide(bandHeightCss, scale, devicePx) > MAX_ENCODED_SIDE_PX)
+    bandHeightCss -= 1;
+  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.`);
+  }
+  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 };
+}
+async function elementBox(conn, loc) {
   const backendNodeId = await backendNodeIdOf(conn, loc);
   await conn.send("DOM.scrollIntoViewIfNeeded", { backendNodeId }).catch(() => {
     return;
@@ -1405,6 +1501,10 @@ async function elementClip(conn, loc) {
     throw driverError("page-error", "resolved element has zero area");
   return { x: minX, y: minY, width, height };
 }
+function documentClip(box, m, devicePx) {
+  const scroll = scrollOffsetCssPx(m, devicePx);
+  return { x: box.x + scroll.x, y: box.y + scroll.y, width: box.width, height: box.height };
+}
 var CDP_CAPABILITIES = new Set([
   "trace.performance",
   "heap.snapshot",
@@ -1415,6 +1515,9 @@ var CDP_CAPABILITIES = new Set([
   "emulate.networkConditions",
   "screenshot.fullPage",
   "screenshot.element",
+  "screenshot.scale",
+  "screenshot.renderSize",
+  "screenshot.tile",
   "network.intercept",
   "snapshot.accessibilityTree",
   "input.insertTextAtomic",
@@ -1705,31 +1808,128 @@ class CdpPageDriver {
     const { objectId } = await resolveElementLocator(this.conn, loc);
     await this.conn.send("DOM.setFileInputFiles", { files: [...files], objectId });
   }
-  async screenshot(opts) {
+  async screenshot(opts, consumeBands) {
+    const renderSize = opts?.renderWidth !== undefined && opts?.renderHeight !== undefined ? { width: opts.renderWidth, height: opts.renderHeight } : undefined;
+    if (!renderSize)
+      return this.capture(opts, consumeBands);
+    const previous = await readViewportRecord(this.browser.scheme, this.info.id);
+    await this.conn.send("Emulation.setDeviceMetricsOverride", {
+      width: renderSize.width,
+      height: renderSize.height,
+      deviceScaleFactor: previous?.deviceScaleFactor ?? 0,
+      mobile: previous?.mobile ?? false
+    });
+    let shot;
+    let captureError;
+    try {
+      shot = await this.capture(opts, consumeBands);
+    } catch (e) {
+      captureError = e;
+    }
+    let restoreError;
+    try {
+      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) {
+      if (restoreError !== undefined && captureError instanceof Error) {
+        captureError.message = `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`;
+      }
+      throw captureError;
+    }
+    const result = Object.assign(shot, { renderSize, renderRestored: restoreError === undefined });
+    if (restoreError !== undefined)
+      result.renderRestoreError = restoreError;
+    return result;
+  }
+  async capture(opts, consumeBands) {
     await this.ensureDomain("Page");
     const format = opts?.format ?? "png";
     const quality = format === "jpeg" ? opts?.quality ?? 80 : undefined;
+    const scale = opts?.scale ?? 1;
+    const renderSize = opts?.renderWidth !== undefined && opts?.renderHeight !== undefined ? { width: opts.renderWidth, height: opts.renderHeight } : undefined;
+    const box = opts?.clip ? await elementBox(this.conn, opts.clip) : undefined;
+    const metrics = await layoutMetrics(this.conn);
+    const devicePx = devicePixelsPerCssPx(metrics);
+    const clip = box ? documentClip(box, metrics, devicePx) : contentClip(metrics);
+    const sendsClip = opts?.clip !== undefined || opts?.fullPage === true || scale !== 1 || renderSize !== undefined;
+    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);
+    assertClipEncodable(clip, scale, devicePx, renderSize);
     const params = { 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("Page.captureScreenshot", params);
     return { data: new Uint8Array(Buffer.from(data, "base64")), format };
   }
+  async captureTiled(clip, plan, scale, format, consumeBands) {
+    const capture = {
+      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 };
+  }
+  async* bands(clip, plan, scale, format) {
+    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("Page.captureScreenshot", {
+        format: "png",
+        captureBeyondViewport: true,
+        clip: { x: clip.x, y, width: clip.width, height, scale }
+      });
+      yield new Uint8Array(Buffer.from(data, "base64"));
+    }
+  }
   async emulate(opts) {
     if (opts.clearOverrides) {
       const c = () => {
         return;
       };
-      await this.conn.send("Emulation.clearDeviceMetricsOverride").catch(c);
+      let metricsClearError;
+      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) {
+        throw driverError("page-error", `emulate: could not verify the device-metrics override was cleared (${metricsClearError})`);
+      }
+      await clearViewportRecord(this.browser.scheme, this.info.id);
       return { applied: [] };
     }
     const applied = [];
@@ -1743,6 +1943,12 @@ class CdpPageDriver {
         deviceScaleFactor: opts.deviceScaleFactor ?? 0,
         mobile: opts.mobile ?? false
       });
+      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) {
@@ -2130,8 +2336,522 @@ async function reapStaleAgentTabs(driver, backend) {
 }
 
 // src/shared-tools.ts
-import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname, join as join3 } from "node:path";
+import { mkdir as mkdir5, writeFile as writeFile4 } from "node:fs/promises";
+import { dirname as dirname2, join as join4 } from "node:path";
+
+// src/png.ts
+import { once } from "node:events";
+import { mkdir as mkdir4, open, rename, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createDeflate, createInflate, deflateSync } from "node:zlib";
+var PNG_SIGNATURE = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10);
+var ZLIB_CHUNK = 1 << 18;
+var BLOCK_RAW_BYTES = 1 << 22;
+var MAX_BLOCK_ROWS = 4096;
+var DECIDE_LEVEL = 6;
+var CARRIED_CHUNKS = ["gAMA", "cHRM", "sRGB", "iCCP", "pHYs"];
+var CHANNELS = { 0: 1, 2: 3, 4: 2, 6: 4 };
+var LEGAL_DEPTHS = {
+  0: [1, 2, 4, 8, 16],
+  2: [8, 16],
+  4: [8, 16],
+  6: [8, 16]
+};
+var COLOUR_TYPE_NAMES = {
+  0: "greyscale",
+  2: "truecolour RGB",
+  3: "palette",
+  4: "greyscale+alpha",
+  6: "RGBA"
+};
+
+class PngStitchError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PngStitchError";
+  }
+}
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0;n < 256; n++) {
+    let c = n;
+    for (let k = 0;k < 8; k++)
+      c = (c & 1) !== 0 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crcUpdate(crc, bytes) {
+  let c = crc;
+  for (let i = 0;i < bytes.length; i++)
+    c = CRC_TABLE[(c ^ bytes[i]) & 255] ^ c >>> 8;
+  return c >>> 0;
+}
+function crc32(bytes) {
+  return (crcUpdate(4294967295, bytes) ^ 4294967295) >>> 0;
+}
+function readU32(b, off) {
+  return (b[off] << 24 | b[off + 1] << 16 | b[off + 2] << 8 | b[off + 3]) >>> 0;
+}
+function chunkTypeAt(b, off) {
+  return String.fromCharCode(b[off], b[off + 1], b[off + 2], b[off + 3]);
+}
+function sameBytes(a, b) {
+  if (a.length !== b.length)
+    return false;
+  for (let i = 0;i < a.length; i++)
+    if (a[i] !== b[i])
+      return false;
+  return true;
+}
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = p > a ? p - a : a - p;
+  const pb = p > b ? p - b : b - p;
+  const pc = p > c ? p - c : c - p;
+  if (pa <= pb && pa <= pc)
+    return a;
+  return pb <= pc ? b : c;
+}
+function unfilterRow(type, row, prev, bpp, at) {
+  const n = row.length;
+  switch (type) {
+    case 0:
+      return;
+    case 1:
+      for (let i = bpp;i < n; i++)
+        row[i] = row[i] + row[i - bpp] & 255;
+      return;
+    case 2:
+      for (let i = 0;i < n; i++)
+        row[i] = row[i] + prev[i] & 255;
+      return;
+    case 3:
+      for (let i = 0;i < n; i++) {
+        const a = i >= bpp ? row[i - bpp] : 0;
+        row[i] = row[i] + (a + prev[i] >> 1) & 255;
+      }
+      return;
+    case 4:
+      for (let i = 0;i < n; i++) {
+        const a = i >= bpp ? row[i - bpp] : 0;
+        const c = i >= bpp ? prev[i - bpp] : 0;
+        row[i] = row[i] + paeth(a, prev[i], c) & 255;
+      }
+      return;
+    default:
+      throw new PngStitchError(`${at}: unknown row filter type ${type} (PNG defines 0-4)`);
+  }
+}
+function absSigned(v) {
+  const u = v & 255;
+  return u < 128 ? u : 256 - u;
+}
+function chooseFilter(row, prev, bpp) {
+  const n = row.length;
+  let s0 = 0, s1 = 0, s2 = 0, s3 = 0, s4 = 0;
+  for (let i = 0;i < n; i++) {
+    const x = row[i];
+    const b = prev[i];
+    const a = i >= bpp ? row[i - bpp] : 0;
+    const c = i >= bpp ? prev[i - bpp] : 0;
+    s0 += absSigned(x);
+    s1 += absSigned(x - a);
+    s2 += absSigned(x - b);
+    s3 += absSigned(x - (a + b >> 1));
+    s4 += absSigned(x - paeth(a, b, c));
+  }
+  let best = 0, bestSum = s0;
+  if (s1 < bestSum) {
+    best = 1;
+    bestSum = s1;
+  }
+  if (s2 < bestSum) {
+    best = 2;
+    bestSum = s2;
+  }
+  if (s3 < bestSum) {
+    best = 3;
+    bestSum = s3;
+  }
+  if (s4 < bestSum) {
+    best = 4;
+  }
+  return best;
+}
+function writeFilteredRow(type, row, prev, bpp, out, off) {
+  const n = row.length;
+  switch (type) {
+    case 0:
+      out.set(row, off);
+      return;
+    case 1:
+      for (let i = 0;i < n; i++)
+        out[off + i] = row[i] - (i >= bpp ? row[i - bpp] : 0) & 255;
+      return;
+    case 2:
+      for (let i = 0;i < n; i++)
+        out[off + i] = row[i] - prev[i] & 255;
+      return;
+    case 3:
+      for (let i = 0;i < n; i++) {
+        const a = i >= bpp ? row[i - bpp] : 0;
+        out[off + i] = row[i] - (a + prev[i] >> 1) & 255;
+      }
+      return;
+    default:
+      for (let i = 0;i < n; i++) {
+        const a = i >= bpp ? row[i - bpp] : 0;
+        const c = i >= bpp ? prev[i - bpp] : 0;
+        out[off + i] = row[i] - paeth(a, prev[i], c) & 255;
+      }
+      return;
+  }
+}
+function filterUnitBytes(h) {
+  return Math.max(1, Math.ceil(CHANNELS[h.colourType] * h.bitDepth / 8));
+}
+function bytesPerRow(h) {
+  return Math.ceil(h.width * CHANNELS[h.colourType] * h.bitDepth / 8);
+}
+function readIhdr(band, dataStart, at) {
+  const width = readU32(band, dataStart);
+  const height = readU32(band, dataStart + 4);
+  const bitDepth = band[dataStart + 8];
+  const colourType = band[dataStart + 9];
+  const compression = band[dataStart + 10];
+  const filterMethod = band[dataStart + 11];
+  const interlace = band[dataStart + 12];
+  if (width < 1 || height < 1)
+    throw new PngStitchError(`${at}: IHDR declares ${width}x${height}; both dimensions must be >= 1`);
+  if (compression !== 0)
+    throw new PngStitchError(`${at}: IHDR compression method ${compression}; PNG defines only 0 (deflate)`);
+  if (filterMethod !== 0)
+    throw new PngStitchError(`${at}: IHDR filter method ${filterMethod}; PNG defines only 0`);
+  if (interlace === 1) {
+    throw new PngStitchError(`${at}: interlaced (Adam7) PNG is not supported. Its seven reduced passes are not scanlines of the final image, ` + `so bands of them cannot be concatenated; re-capture without interlacing (Chrome's Page.captureScreenshot always does).`);
+  }
+  if (interlace !== 0)
+    throw new PngStitchError(`${at}: IHDR interlace method ${interlace}; PNG defines only 0 (none) and 1 (Adam7)`);
+  if (colourType === 3) {
+    throw new PngStitchError(`${at}: colour type 3 (palette) is not supported. Concatenating palettized bands requires every band's PLTE/tRNS to ` + `be identical or a full palette remap; Chrome emits colour type 2, so this path is refused rather than guessed.`);
+  }
+  if (CHANNELS[colourType] === undefined)
+    throw new PngStitchError(`${at}: IHDR colour type ${colourType}; PNG defines 0, 2, 3, 4 and 6`);
+  if (!LEGAL_DEPTHS[colourType].includes(bitDepth)) {
+    throw new PngStitchError(`${at}: bit depth ${bitDepth} is not legal for colour type ${colourType} (${COLOUR_TYPE_NAMES[colourType]}); ` + `allowed: ${LEGAL_DEPTHS[colourType].join(", ")}`);
+  }
+  return { width, height, bitDepth, colourType };
+}
+function parseBand(band, index) {
+  const at = `band ${index}`;
+  if (band.length < 8)
+    throw new PngStitchError(`${at}: ${band.length} bytes is too short to be a PNG`);
+  for (let i = 0;i < 8; i++) {
+    if (band[i] !== PNG_SIGNATURE[i])
+      throw new PngStitchError(`${at}: not a PNG (bad 8-byte signature)`);
+  }
+  let header;
+  const idat = [];
+  const carried = [];
+  let sawIend = false;
+  let off = 8;
+  while (off + 8 <= band.length) {
+    const len = readU32(band, off);
+    const type = chunkTypeAt(band, off + 4);
+    const dataStart = off + 8;
+    const dataEnd = dataStart + len;
+    if (dataEnd + 4 > band.length) {
+      throw new PngStitchError(`${at}: chunk "${type}" at byte ${off} claims ${len} payload bytes but only ${band.length - dataStart} remain (truncated PNG)`);
+    }
+    if (type === "IHDR") {
+      if (off !== 8)
+        throw new PngStitchError(`${at}: IHDR must be the first chunk, found it at byte ${off}`);
+      if (len !== 13)
+        throw new PngStitchError(`${at}: IHDR payload is ${len} bytes, must be 13`);
+      const want = readU32(band, dataEnd);
+      const got = crc32(band.subarray(off + 4, dataEnd));
+      if (want !== got)
+        throw new PngStitchError(`${at}: IHDR CRC mismatch (file says 0x${want.toString(16)}, computed 0x${got.toString(16)})`);
+      header = readIhdr(band, dataStart, at);
+    } else if (!header) {
+      throw new PngStitchError(`${at}: first chunk is "${type}", expected IHDR`);
+    } else if (type === "IDAT") {
+      idat.push([dataStart, dataEnd]);
+    } else if (type === "IEND") {
+      sawIend = true;
+      break;
+    } else if (CARRIED_CHUNKS.includes(type)) {
+      carried.push({ type, data: band.subarray(dataStart, dataEnd) });
+    }
+    off = dataEnd + 4;
+  }
+  if (!header)
+    throw new PngStitchError(`${at}: no IHDR chunk`);
+  if (idat.length === 0)
+    throw new PngStitchError(`${at}: no IDAT chunk`);
+  if (!sawIend)
+    throw new PngStitchError(`${at}: no IEND chunk (truncated PNG)`);
+  return { header, idat, carried };
+}
+function assertCompatible(first, next, firstCarried, nextCarried, index) {
+  const at = `band ${index}`;
+  if (next.width !== first.width)
+    throw new PngStitchError(`${at}: width ${next.width} does not match band 1's width ${first.width}`);
+  if (next.bitDepth !== first.bitDepth)
+    throw new PngStitchError(`${at}: bit depth ${next.bitDepth} does not match band 1's bit depth ${first.bitDepth}`);
+  if (next.colourType !== first.colourType) {
+    throw new PngStitchError(`${at}: colour type ${next.colourType} (${COLOUR_TYPE_NAMES[next.colourType] ?? "?"}) does not match band 1's ` + `colour type ${first.colourType} (${COLOUR_TYPE_NAMES[first.colourType] ?? "?"})`);
+  }
+  for (const type of CARRIED_CHUNKS) {
+    const a = firstCarried.find((c) => c.type === type);
+    const b = nextCarried.find((c) => c.type === type);
+    if (!a && !b)
+      continue;
+    if (!a || !b)
+      throw new PngStitchError(`${at}: ${b ? "has" : "is missing"} a "${type}" chunk that band 1 ${b ? "does not have" : "has"}; the bands disagree about how their samples are interpreted`);
+    if (!sameBytes(a.data, b.data))
+      throw new PngStitchError(`${at}: its "${type}" chunk differs from band 1's; the bands disagree about how their samples are interpreted`);
+  }
+}
+
+class ChunkWriter {
+  fh;
+  pos = 0;
+  constructor(fh) {
+    this.fh = fh;
+  }
+  get bytes() {
+    return this.pos;
+  }
+  async writeRaw(b) {
+    await this.fh.write(b, 0, b.length, this.pos);
+    this.pos += b.length;
+  }
+  async writeChunk(type, payload) {
+    const head = Buffer.allocUnsafe(8);
+    head.writeUInt32BE(payload.length, 0);
+    head.write(type, 4, "latin1");
+    const crc = (crcUpdate(crcUpdate(4294967295, head.subarray(4)), payload) ^ 4294967295) >>> 0;
+    const tail = Buffer.allocUnsafe(4);
+    tail.writeUInt32BE(crc, 0);
+    await this.fh.writev([head, payload, tail], this.pos);
+    this.pos += 8 + payload.length + 4;
+  }
+  async patchAt(position, b) {
+    await this.fh.write(b, 0, b.length, position);
+  }
+}
+function ihdrChunk(h, height) {
+  const buf = Buffer.allocUnsafe(25);
+  buf.writeUInt32BE(13, 0);
+  buf.write("IHDR", 4, "latin1");
+  buf.writeUInt32BE(h.width, 8);
+  buf.writeUInt32BE(height, 12);
+  buf[16] = h.bitDepth;
+  buf[17] = h.colourType;
+  buf[18] = 0;
+  buf[19] = 0;
+  buf[20] = 0;
+  buf.writeUInt32BE(crc32(buf.subarray(4, 21)), 21);
+  return buf;
+}
+
+class RowEncoder {
+  writer;
+  bpr;
+  bpp;
+  deflate = createDeflate({ chunkSize: ZLIB_CHUNK });
+  pump;
+  rowsPerBlock;
+  block;
+  blockRows = 0;
+  candNone;
+  candHeuristic;
+  prevRaw;
+  constructor(writer, bpr, bpp) {
+    this.writer = writer;
+    this.bpr = bpr;
+    this.bpp = bpp;
+    this.rowsPerBlock = Math.min(MAX_BLOCK_ROWS, Math.max(1, Math.floor(BLOCK_RAW_BYTES / bpr)));
+    this.block = Buffer.allocUnsafe(this.rowsPerBlock * bpr);
+    this.candNone = Buffer.allocUnsafe(this.rowsPerBlock * (bpr + 1));
+    this.candHeuristic = Buffer.allocUnsafe(this.rowsPerBlock * (bpr + 1));
+    this.prevRaw = new Uint8Array(bpr);
+    this.pump = (async () => {
+      for await (const chunk of this.deflate)
+        await this.writer.writeChunk("IDAT", chunk);
+    })();
+    this.pump.catch(() => {});
+  }
+  async addRow(raw) {
+    this.block.set(raw, this.blockRows * this.bpr);
+    this.blockRows += 1;
+    if (this.blockRows === this.rowsPerBlock)
+      await this.emitBlock();
+  }
+  async emitBlock() {
+    const n = this.blockRows;
+    if (n === 0)
+      return;
+    const { bpr, bpp } = this;
+    const stride = bpr + 1;
+    let prev = this.prevRaw;
+    for (let r = 0;r < n; r++) {
+      const row = this.block.subarray(r * bpr, (r + 1) * bpr);
+      const at = r * stride;
+      this.candNone[at] = 0;
+      this.candNone.set(row, at + 1);
+      const filter = chooseFilter(row, prev, bpp);
+      this.candHeuristic[at] = filter;
+      writeFilteredRow(filter, row, prev, bpp, this.candHeuristic, at + 1);
+      prev = row;
+    }
+    const used = n * stride;
+    const a = this.candNone.subarray(0, used);
+    const b = this.candHeuristic.subarray(0, used);
+    const heuristicWins = deflateSync(b, { level: DECIDE_LEVEL }).length < deflateSync(a, { level: DECIDE_LEVEL }).length;
+    this.prevRaw.set(prev);
+    this.blockRows = 0;
+    const out = Buffer.from(heuristicWins ? b : a);
+    if (!this.deflate.write(out))
+      await once(this.deflate, "drain");
+  }
+  async finish() {
+    await this.emitBlock();
+    this.deflate.end();
+    await this.pump;
+  }
+  async abort() {
+    this.deflate.destroy();
+    await this.pump.catch(() => {});
+  }
+}
+async function* inflateBandIdat(band, slices, at) {
+  const inf = createInflate({ chunkSize: ZLIB_CHUNK });
+  const feed = (async () => {
+    for (const [start, end] of slices) {
+      const view = Buffer.from(band.buffer, band.byteOffset + start, end - start);
+      if (!inf.write(view))
+        await once(inf, "drain");
+    }
+    inf.end();
+  })();
+  feed.catch(() => {});
+  try {
+    for await (const chunk of inf)
+      yield chunk;
+  } catch (err) {
+    throw new PngStitchError(`${at}: IDAT stream would not inflate (${err.message})`);
+  } finally {
+    inf.destroy();
+  }
+}
+function isAsyncIterable(x) {
+  return typeof x === "object" && x !== null && Symbol.asyncIterator in x;
+}
+async function* eachBand(bands) {
+  if (isAsyncIterable(bands)) {
+    for await (const b of bands)
+      yield b;
+  } else {
+    for (const b of bands)
+      yield b;
+  }
+}
+async function stitchPngBandsToFile(bands, outPath) {
+  await mkdir4(dirname(outPath), { recursive: true });
+  const partPath = `${outPath}.stitch-partial`;
+  const fh = await open(partPath, "w");
+  let done = false;
+  try {
+    const result = await stitchInto(fh, bands);
+    await fh.close();
+    await rename(partPath, outPath);
+    done = true;
+    return result;
+  } finally {
+    if (!done) {
+      await fh.close().catch(() => {});
+      await rm(partPath, { force: true }).catch(() => {});
+    }
+  }
+}
+async function stitchInto(fh, bands) {
+  const writer = new ChunkWriter(fh);
+  let first;
+  let firstCarried = [];
+  let encoder;
+  let prevRow = new Uint8Array(0);
+  let rowBuf = new Uint8Array(0);
+  let bpp = 0;
+  let bpr = 0;
+  let totalRows = 0;
+  let index = 0;
+  try {
+    for await (const band of eachBand(bands)) {
+      index += 1;
+      const parsed = parseBand(band, index);
+      const at = `band ${index}`;
+      if (!first) {
+        first = parsed.header;
+        firstCarried = parsed.carried;
+        bpp = filterUnitBytes(first);
+        bpr = bytesPerRow(first);
+        prevRow = new Uint8Array(bpr);
+        rowBuf = new Uint8Array(1 + bpr);
+        await writer.writeRaw(PNG_SIGNATURE);
+        await writer.writeRaw(ihdrChunk(first, 1));
+        for (const c of parsed.carried)
+          await writer.writeChunk(c.type, c.data);
+        encoder = new RowEncoder(writer, bpr, bpp);
+      } else {
+        assertCompatible(first, parsed.header, firstCarried, parsed.carried, index);
+      }
+      const enc = encoder;
+      const raw = rowBuf.subarray(1);
+      prevRow.fill(0);
+      let rows = 0;
+      let filled = 0;
+      for await (const chunk of inflateBandIdat(band, parsed.idat, at)) {
+        let off = 0;
+        while (off < chunk.length) {
+          const take = Math.min(rowBuf.length - filled, chunk.length - off);
+          rowBuf.set(chunk.subarray(off, off + take), filled);
+          filled += take;
+          off += take;
+          if (filled !== rowBuf.length)
+            continue;
+          if (rows >= parsed.header.height) {
+            throw new PngStitchError(`${at}: IDAT holds more scanlines than its IHDR height of ${parsed.header.height}`);
+          }
+          unfilterRow(rowBuf[0], raw, prevRow, bpp, at);
+          await enc.addRow(raw);
+          prevRow.set(raw);
+          rows += 1;
+          filled = 0;
+        }
+      }
+      if (filled !== 0 || rows !== parsed.header.height) {
+        throw new PngStitchError(`${at}: IDAT decoded to ${rows} complete scanlines${filled > 0 ? ` plus ${filled} trailing bytes` : ""}, but its IHDR declares ${parsed.header.height}`);
+      }
+      totalRows += parsed.header.height;
+      if (totalRows > 2147483647)
+        throw new PngStitchError(`stitched height would be ${totalRows}, past PNG's 2^31-1 limit`);
+    }
+    if (!first || !encoder)
+      throw new PngStitchError("no bands to stitch");
+    await encoder.finish();
+    await writer.writeChunk("IEND", new Uint8Array(0));
+    await writer.patchAt(8, ihdrChunk(first, totalRows));
+    return { width: first.width, height: totalRows, bytes: writer.bytes, bands: index };
+  } catch (err) {
+    await encoder?.abort();
+    throw err;
+  }
+}
+
+// src/shared-tools.ts
 var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 
@@ -2276,8 +2996,8 @@ async function closePage(driver, args) {
   return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
-  await mkdir3(STATE_DIR, { recursive: true });
-  await writeFile3(join3(STATE_DIR, "selected"), id, "utf8");
+  await mkdir5(STATE_DIR, { recursive: true });
+  await writeFile4(join4(STATE_DIR, "selected"), id, "utf8");
 }
 async function selectPage(driver, args) {
   if (args.target === undefined || args.target === "")
@@ -2341,10 +3061,10 @@ function serializeForSink(value) {
   return json ?? "null";
 }
 async function writeJsonSink(savePath, value) {
-  const path = savePath.startsWith("/") ? savePath : join3(ARTIFACT_DIR, savePath);
-  await mkdir3(dirname(path), { recursive: true });
+  const path = savePath.startsWith("/") ? savePath : join4(ARTIFACT_DIR, savePath);
+  await mkdir5(dirname2(path), { recursive: true });
   const json = serializeForSink(value);
-  await writeFile3(path, json, "utf8");
+  await writeFile4(path, json, "utf8");
   return { path, bytes: Buffer.byteLength(json, "utf8") };
 }
 function sinkRequested(savePath) {
@@ -2648,30 +3368,166 @@ async function uploadFile(driver, args) {
 function stamp() {
   return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
 }
+var MAX_SCREENSHOT_SCALE = 8;
+function resolveScreenshotScale(scale, capabilities) {
+  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;
+}
+var MAX_RENDER_SIZE_PX = 16384;
+function resolveRenderSize(renderWidth, renderHeight, capabilities) {
+  if (renderWidth === undefined && renderHeight === undefined)
+    return;
+  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]]) {
+    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 };
+}
+function resolveTileMode(tile, capabilities, format, returnBase64) {
+  if (tile === undefined)
+    return;
+  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.");
+  }
+  if (format !== "png")
+    throw tiledCaptureRefusal("format");
+  if (returnBase64)
+    throw tiledCaptureRefusal("base64");
+  return true;
+}
+function tiledCaptureRefusal(reason, banded) {
+  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.`);
+}
+function pngPixelSize(b, view) {
+  if (b.length < 24)
+    return;
+  if (view.getUint32(0) !== 2303741511 || view.getUint32(4) !== 218765834)
+    return;
+  if (String.fromCharCode(b[12], b[13], b[14], b[15]) !== "IHDR")
+    return;
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+var JPEG_SOF = new Set([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207]);
+function jpegPixelSize(b, view) {
+  if (b.length < 4 || b[0] !== 255 || b[1] !== 216)
+    return;
+  let i = 2;
+  while (i + 3 < b.length) {
+    if (b[i] !== 255) {
+      i += 1;
+      continue;
+    }
+    const marker = b[i + 1];
+    if (marker === 255) {
+      i += 1;
+      continue;
+    }
+    if (marker === 216 || marker === 1 || marker >= 208 && marker <= 215) {
+      i += 2;
+      continue;
+    }
+    const segLen = view.getUint16(i + 2);
+    if (JPEG_SOF.has(marker)) {
+      if (i + 9 > b.length)
+        return;
+      return { width: view.getUint16(i + 7), height: view.getUint16(i + 5) };
+    }
+    if (segLen < 2)
+      return;
+    i += 2 + segLen;
+  }
+  return;
+}
+function imagePixelSize(bytes) {
+  if (bytes.byteLength < 4)
+    return;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return pngPixelSize(bytes, view) ?? jpegPixelSize(bytes, view);
+}
 async function takeScreenshot(driver, args = {}) {
   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";
+  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 withPage2(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 mkdir3(ARTIFACT_DIR, { recursive: true });
-    const ext = outFormat === "jpeg" ? "jpg" : "png";
-    const path = args.savePath ?? join3(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
-    await writeFile3(path, Buffer.from(data));
-    const result = {
-      path,
-      bytes: data.byteLength,
-      format: outFormat,
-      target: target3(page.info)
+    const ext = format === "jpeg" ? "jpg" : "png";
+    const path = args.savePath ?? join4(ARTIFACT_DIR, `screenshot-${page.info.id.slice(0, 8)}-${stamp()}.${ext}`);
+    const stitch = async (banded) => {
+      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 = isTiledCapture(shot) ? {
+      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);
+    if (renderSize && shot.renderSize) {
+      result.renderSize = shot.renderSize;
+      result.renderRestored = shot.renderRestored ?? false;
+      if (shot.renderRestoreError !== undefined)
+        result.renderRestoreError = shot.renderRestoreError;
+    }
     return result;
   });
 }
+async function writeOneShot(data, outFormat, path, target, scale, returnBase64) {
+  if (data.byteLength === 0)
+    throw new SharedToolError("captureScreenshot returned empty data");
+  await mkdir5(dirname2(path), { recursive: true });
+  await writeFile4(path, Buffer.from(data));
+  const size = imagePixelSize(data);
+  const result = { path, bytes: data.byteLength, format: outFormat, target, scale };
+  if (size) {
+    result.width = size.width;
+    result.height = size.height;
+  }
+  if (returnBase64)
+    result.base64 = Buffer.from(data).toString("base64");
+  return result;
+}
 async function emulate(driver, args = {}) {
   return withPage2(driver, args.target, async (page) => {
     if (args.clearOverrides) {
@@ -2842,10 +3698,10 @@ var LEASE_TOOLS = {
 };
 
 // src/tools/console.ts
-import { readFile as readFile3 } from "node:fs/promises";
+import { readFile as readFile4 } from "node:fs/promises";
 
 // src/tools/recorder.ts
-import { mkdir as mkdir4, appendFile, writeFile as writeFile4, copyFile } from "node:fs/promises";
+import { mkdir as mkdir6, appendFile, writeFile as writeFile5, copyFile } from "node:fs/promises";
 var ARTIFACT_DIR2 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function recFile(targetId) {
   return `${ARTIFACT_DIR2}/rec-${targetId}.jsonl`;
@@ -2891,11 +3747,11 @@ var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Lo
 async function startRecorder(target, opts = {}) {
   const network = opts.network ?? true;
   const consoleCap = opts.console ?? true;
-  await mkdir4(ARTIFACT_DIR2, { recursive: true });
+  await mkdir6(ARTIFACT_DIR2, { recursive: true });
   const { conn, target: resolved } = await openPage(target, { timeoutMs: opts.timeoutMs });
   const file = opts.file ?? recFile(resolved.id);
   if (opts.truncate) {
-    await writeFile4(file, "");
+    await writeFile5(file, "");
   }
   let chain = Promise.resolve();
   let dropped = 0;
@@ -3041,7 +3897,7 @@ function lineToEntry(line, index) {
 async function readConsoleEntries(file) {
   let raw;
   try {
-    raw = await readFile3(file, "utf8");
+    raw = await readFile4(file, "utf8");
   } catch {
     return [];
   }
@@ -3098,7 +3954,7 @@ async function getConsoleMessage(args = {}) {
 }
 
 // src/tools/network.ts
-import { readFile as readFile4 } from "node:fs/promises";
+import { readFile as readFile5 } from "node:fs/promises";
 var DEFAULT_CAPTURE_MS2 = 2500;
 function asHeaders(v) {
   if (!v || typeof v !== "object")
@@ -3165,7 +4021,7 @@ function correlate(lines) {
 async function readNetworkRequests(file) {
   let raw;
   try {
-    raw = await readFile4(file, "utf8");
+    raw = await readFile5(file, "utf8");
   } catch {
     return [];
   }
@@ -3249,8 +4105,8 @@ async function getNetworkRequest(args = {}) {
 }
 
 // src/tools/performance.ts
-import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile5, stat, unlink as unlink3 } from "node:fs/promises";
-import { join as join4 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile6, writeFile as writeFile6, stat, unlink as unlink4 } from "node:fs/promises";
+import { join as join5 } from "node:path";
 var ARTIFACT_DIR3 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var STATE_DIR2 = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
 var DEFAULT_CATEGORIES = [
@@ -3268,7 +4124,7 @@ function shortId(id) {
   return id.slice(0, 8);
 }
 function stateFilePath() {
-  return join4(STATE_DIR2, "trace-state.json");
+  return join5(STATE_DIR2, "trace-state.json");
 }
 function bufferTraceData(conn, sink) {
   return conn.on("Tracing.dataCollected", (params) => {
@@ -3290,10 +4146,10 @@ async function endTrace(conn, sink, timeoutMs = 30000) {
   return sink;
 }
 async function writeTrace(events, targetId) {
-  await mkdir5(ARTIFACT_DIR3, { recursive: true });
-  const path = join4(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
+  await mkdir7(ARTIFACT_DIR3, { recursive: true });
+  const path = join5(ARTIFACT_DIR3, `trace-${shortId(targetId)}-${stamp2()}.json`);
   const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
-  await writeFile5(path, body, "utf8");
+  await writeFile6(path, body, "utf8");
   const { size } = await stat(path);
   return { path, bytes: size };
 }
@@ -3313,7 +4169,7 @@ async function performanceStartTrace(args = {}) {
     throw err;
   }
   liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
-  await mkdir5(STATE_DIR2, { recursive: true });
+  await mkdir7(STATE_DIR2, { recursive: true });
   const state = {
     targetId: target.id,
     url: target.url,
@@ -3321,7 +4177,7 @@ async function performanceStartTrace(args = {}) {
     pid: process.pid,
     categories
   };
-  await writeFile5(stateFilePath(), JSON.stringify(state), "utf8");
+  await writeFile6(stateFilePath(), JSON.stringify(state), "utf8");
   return {
     target: { id: target.id, url: target.url, title: target.title },
     categories,
@@ -3334,7 +4190,7 @@ async function performanceStopTrace(args = {}) {
   if (!entry) {
     let hint = "";
     try {
-      const raw = await readFile5(stateFilePath(), "utf8");
+      const raw = await readFile6(stateFilePath(), "utf8");
       const state = JSON.parse(raw);
       hint = state.pid === process.pid ? ` (state file lists target ${shortId(state.targetId)} but its live connection is gone)` : ` (trace was started by a DIFFERENT process pid=${state.pid}; live recordings cannot cross process boundaries)`;
     } catch {}
@@ -3346,7 +4202,7 @@ async function performanceStopTrace(args = {}) {
   } finally {
     conn.close();
     liveTraces.delete(target.id);
-    await unlink3(stateFilePath()).catch(() => {});
+    await unlink4(stateFilePath()).catch(() => {});
   }
   const written = await writeTrace(events, target.id);
   const metrics = analyzeEvents(events);
@@ -3464,7 +4320,7 @@ async function performanceAnalyzeInsight(args = {}) {
   }
   let raw;
   try {
-    raw = await readFile5(args.tracePath, "utf8");
+    raw = await readFile6(args.tracePath, "utf8");
   } catch (err) {
     throw new CdpError(`cannot read trace file '${args.tracePath}': ${err.message}`);
   }
@@ -3482,8 +4338,8 @@ async function performanceAnalyzeInsight(args = {}) {
 
 // src/tools/screencast.ts
 import { spawn } from "node:child_process";
-import { mkdir as mkdir6, rm, stat as stat2, writeFile as writeFile6 } from "node:fs/promises";
-import { join as join5 } from "node:path";
+import { mkdir as mkdir8, rm as rm2, stat as stat2, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join6 } from "node:path";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 var FFMPEG_BIN = process.env.CDP_FFMPEG ?? "ffmpeg";
 function frameDurationsMs(ledger, stopWallclockMs) {
@@ -3539,7 +4395,7 @@ function pngSize(buf) {
     return;
   return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
 }
-var JPEG_SOF = new Set([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207]);
+var JPEG_SOF2 = new Set([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207]);
 function jpegSize(buf) {
   if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216)
     return;
@@ -3561,7 +4417,7 @@ function jpegSize(buf) {
     if (i + 3 >= buf.length)
       return;
     const segLen = buf.readUInt16BE(i + 2);
-    if (JPEG_SOF.has(marker)) {
+    if (JPEG_SOF2.has(marker)) {
       if (i + 9 > buf.length)
         return;
       return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
@@ -3704,9 +4560,9 @@ async function startScreenRecording(args = {}) {
     conn.close();
     throw err;
   }
-  const spoolDir = join5(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
+  const spoolDir = join6(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
   try {
-    await mkdir6(spoolDir, { recursive: true });
+    await mkdir8(spoolDir, { recursive: true });
   } catch (err) {
     conn.close();
     throw new CdpError(`cannot create the screencast spool directory '${spoolDir}': ${err.message}`);
@@ -3747,7 +4603,7 @@ async function startScreenRecording(args = {}) {
     seq += 1;
     const file = `frame-${String(seq).padStart(6, "0")}.${ext}`;
     rec.ledger.push({ file, timestamp, width: size.width, height: size.height });
-    rec.writes = rec.writes.then(() => writeFile6(join5(spoolDir, file), buf)).catch(() => {
+    rec.writes = rec.writes.then(() => writeFile7(join6(spoolDir, file), buf)).catch(() => {
       rec.dropped += 1;
       rec.unwritten.add(file);
     });
@@ -3769,7 +4625,7 @@ async function startScreenRecording(args = {}) {
   } catch (err) {
     rec.off();
     conn.close();
-    await rm(spoolDir, { recursive: true, force: true }).catch(() => {});
+    await rm2(spoolDir, { recursive: true, force: true }).catch(() => {});
     throw err;
   }
   liveRecordings.set(target.id, rec);
@@ -3807,14 +4663,14 @@ async function stopScreenRecording(args = {}) {
   liveRecordings.delete(rec.target.id);
   const ledger = rec.unwritten.size ? rec.ledger.filter((entry) => !rec.unwritten.has(entry.file)) : rec.ledger;
   if (!ledger.length) {
-    await rm(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
+    await rm2(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
     throw new CdpError(`screen recording captured 0 frames for target ${shortId2(rec.target.id)}. Chrome emits a screencast frame only on repaint: a fully backgrounded or occluded tab may never paint. Retry with bringToFront:true, or drive the page while recording.`);
   }
-  await mkdir6(ARTIFACT_DIR4, { recursive: true });
-  const outPath = args.savePath ?? join5(ARTIFACT_DIR4, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
+  await mkdir8(ARTIFACT_DIR4, { recursive: true });
+  const outPath = args.savePath ?? join6(ARTIFACT_DIR4, `screen-recording-${shortId2(rec.target.id)}-${stamp3()}.mp4`);
   const frames = coalesceToConcatGrid(ledger, stoppedAt);
-  const manifestPath = join5(rec.spoolDir, "frames.ffconcat");
-  await writeFile6(manifestPath, buildConcatManifest(frames), "utf8");
+  const manifestPath = join6(rec.spoolDir, "frames.ffconcat");
+  await writeFile7(manifestPath, buildConcatManifest(frames), "utf8");
   const durationMs = frames.reduce((total, f) => total + f.durationMs, 0);
   const { width, height } = evenDimensions(ledger[0].width, ledger[0].height);
   let res;
@@ -3828,7 +4684,7 @@ async function stopScreenRecording(args = {}) {
 ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
   }
   const { size } = await stat2(outPath);
-  await rm(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
+  await rm2(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
   return {
     path: outPath,
     bytes: size,
@@ -3845,8 +4701,8 @@ ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
 }
 
 // src/tools/heap.ts
-import { mkdir as mkdir7, writeFile as writeFile7 } from "node:fs/promises";
-import { join as join6 } from "node:path";
+import { mkdir as mkdir9, writeFile as writeFile8 } from "node:fs/promises";
+import { join as join7 } from "node:path";
 var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function stamp4(targetId) {
   const short = targetId.slice(0, 8);
@@ -3871,9 +4727,9 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir7(ARTIFACT_DIR5, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join6(ARTIFACT_DIR5, args.savePath) : join6(ARTIFACT_DIR5, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
-    await writeFile7(path, snapshot, "utf8");
+    await mkdir9(ARTIFACT_DIR5, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join7(ARTIFACT_DIR5, args.savePath) : join7(ARTIFACT_DIR5, `take_heapsnapshot-${stamp4(target.id)}.heapsnapshot`);
+    await writeFile8(path, snapshot, "utf8");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
       path,
@@ -3886,7 +4742,7 @@ async function takeHeapsnapshot(args = {}) {
 
 // src/tools/lighthouse.ts
 import { spawn as spawn2 } from "node:child_process";
-import { mkdir as mkdir8, readFile as readFile6, stat as stat3 } from "node:fs/promises";
+import { mkdir as mkdir10, readFile as readFile7, stat as stat3 } from "node:fs/promises";
 var ARTIFACT_DIR6 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
 function cdpPort() {
   const base = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
@@ -3947,7 +4803,7 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir8(ARTIFACT_DIR6, { recursive: true });
+  await mkdir10(ARTIFACT_DIR6, { recursive: true });
   const outPath = args.savePath ?? `${ARTIFACT_DIR6}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
@@ -3976,7 +4832,7 @@ async function lighthouseAudit(args) {
   }
   let raw;
   try {
-    raw = await readFile6(outPath, "utf8");
+    raw = await readFile7(outPath, "utf8");
   } catch {
     raw = undefined;
   }
@@ -4063,14 +4919,14 @@ async function dispatchMouse(args) {
 }
 
 // src/tools/downloads.ts
-import { readdir as readdir3, rename, stat as stat4 } from "node:fs/promises";
-import { basename, extname, join as join8 } from "node:path";
+import { readdir as readdir3, rename as rename2, stat as stat4 } from "node:fs/promises";
+import { basename, extname, join as join9 } from "node:path";
 
 // src/tools/browser-session.ts
-import { mkdir as mkdir9 } from "node:fs/promises";
-import { join as join7 } from "node:path";
+import { mkdir as mkdir11 } from "node:fs/promises";
+import { join as join8 } from "node:path";
 var ARTIFACT_DIR7 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
-var DOWNLOADS_DIR = join7(ARTIFACT_DIR7, "downloads");
+var DOWNLOADS_DIR = join8(ARTIFACT_DIR7, "downloads");
 var DOWNLOAD_BUFFER_LIMIT = 50;
 var session;
 function isDisconnect(e) {
@@ -4142,7 +4998,7 @@ async function browserSend(method, params = {}) {
   }
 }
 async function armDownloadsAt(path) {
-  await mkdir9(path, { recursive: true });
+  await mkdir11(path, { recursive: true });
   const s = await getBrowserSession();
   await s.conn.send("Browser.setDownloadBehavior", { behavior: "allowAndName", downloadPath: path, eventsEnabled: true });
   s.armedPath = path;
@@ -4232,8 +5088,8 @@ async function waitForDownload(args = {}) {
   const taken = new Set(await readdir3(DOWNLOADS_DIR).catch(() => []));
   taken.delete(basename(rec.filePath));
   const finalName = nextFreeName(suggestedFilename, taken);
-  const path = join8(DOWNLOADS_DIR, finalName);
-  await rename(rec.filePath, path);
+  const path = join9(DOWNLOADS_DIR, finalName);
+  await rename2(rec.filePath, path);
   const bytes = (await stat4(path)).size;
   return { path, suggestedFilename, bytes, ...rec.url ? { url: rec.url } : {}, target };
 }
@@ -5234,7 +6090,7 @@ var MANIFEST = [
   },
   {
     name: "take_screenshot",
-    description: "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
+    description: "Capture the viewport (default), the full scrollable page (fullPage), or a single element (uid or selector, exactly one and mutually exclusive) via raw CDP Page.captureScreenshot — as one image when it fits, or as vertical bands stitched losslessly into one PNG when it does not (see tile). Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath; its directory is created for you) and returns {path,bytes,format,target,scale} plus width/height MEASURED from the encoded bytes, which are omitted rather than guessed when the bytes cannot be decoded; renderSize/renderRestored (+renderRestoreError) accompany a renderWidth/renderHeight capture, tiled/bands a banded one. Raw base64 is only included when returnBase64 is set, and is refused on a banded capture. quality applies to jpeg only. Every capture costs one Page.getLayoutMetrics round trip, because Chrome does not refuse an oversized capture politely: past 16384 device px per side Page.captureScreenshot can simply never answer, and captureBeyondViewport leaves the tab resized to the clip, so the size is checked before the capture rather than after.",
     inputSchema: {
       type: "object",
       properties: {
@@ -5262,6 +6118,22 @@ var MANIFEST = [
           type: "boolean",
           description: "Capture the full scrollable content height computed from Page.getLayoutMetrics, not just the viewport."
         },
+        scale: {
+          type: "number",
+          description: "Output-pixel multiplier for this one capture: greater than 0, at most 8, default 1. Output px = ceil(css px x scale x devicePixelRatio), so on a ratio-2 display scale 3 is 6x the CSS size; the page is never told anything changed (devicePixelRatio and innerWidth/innerHeight read identically before and after). Chrome only (capability screenshot.scale) — WebDriver BiDi's browsingContext.captureScreenshot has no scale parameter, so under Firefox call emulate with deviceScaleFactor first and capture at scale 1. A projection past Chrome's 16384 device px per side is refused before the browser is dialled, naming the largest scale that fits."
+        },
+        renderWidth: {
+          type: "number",
+          description: "Emulate this viewport width, in CSS px (integer, 1-16384), for the length of ONE capture, then put the previous viewport back. REQUIRED together with renderHeight. Not the same knob as scale: scale re-renders the same layout at more pixels, this changes what the page BELIEVES, so media queries flip and the document re-lays-out — which is how you capture a responsive page at 1920x1080 from a tab that is not that size. Declared by BOTH backends (capability screenshot.renderSize). The restore can only put back an override this toolkit itself applied: one set by the DevTools UI, another client, or a pre-1.9.2 build is invisible and gets reset to the real device. The result reports renderSize and renderRestored; renderRestored:false means the tab is STILL emulated and you have to fix it with emulate."
+        },
+        renderHeight: {
+          type: "number",
+          description: "Emulate this viewport height, in CSS px (integer, 1-16384), for the length of one capture. Required together with renderWidth — a viewport is two numbers, and honouring one while inventing the other would render at a size you never named and never see in the result. Note a narrow renderWidth reflows most documents TALLER, which is the usual way a render-size capture trips the 16384-device-px encode limit."
+        },
+        tile: {
+          type: "boolean",
+          description: "Whether this capture may be taken as vertical bands and stitched into one lossless PNG. Three-valued: omitted = AUTO (one shot when the projected output fits under Chrome's 16384 device px per side, bands when it does not — this is why a whole-page capture of a very long page now returns a file instead of hanging and wedging the tab); false = never band, refuse instead (the pre-1.9.2 behaviour); true = always band, even when one shot would have fitted. Only true costs a capability (screenshot.tile, Chrome only; Firefox was never driven for the band arithmetic). A banded capture is PNG-only and cannot also returnBase64, and only HEIGHT is tiled — a projected WIDTH past the limit is refused, not split, because bands are stitched by concatenating scanlines. Bands are a faithful crop of one document render: fixed and sticky elements do not repeat per band and seams are pixel-exact, but content the page only loads on real scroll (lazy images, virtualized lists) renders blank in bands the real viewport never reached, which is a property of the page and not of the stitch."
+        },
         uid: {
           type: "number",
           description: "Element to clip to: a CDP backendDOMNodeId obtained from take_snapshot. Mutually exclusive with selector."
@@ -5272,11 +6144,11 @@ var MANIFEST = [
         },
         savePath: {
           type: "string",
-          description: "Override the output file path. Default: /tmp/cdp-toolkit/screenshot-<id>-<stamp>.<ext>."
+          description: "Override the output file path. Default: /tmp/cdp-toolkit/screenshot-<id>-<stamp>.<ext>, where the stamp is the capture's START (a banded capture writes as it goes and has no finished image to name a file after). The destination directory is created from this path's own dirname, so a savePath outside /tmp/cdp-toolkit works."
         },
         returnBase64: {
           type: "boolean",
-          description: "Also return the raw base64 image bytes in the result, in addition to writing the file."
+          description: "Also return the raw base64 image bytes in the result, in addition to writing the file. Refused on a banded capture (see tile): a stitched image runs to hundreds of megabytes and base64 inflates it by a third, into the caller's response — read the file at the returned path instead."
         }
       },
       required: [],
@@ -5285,7 +6157,7 @@ var MANIFEST = [
   },
   {
     name: "emulate",
-    description: "Apply any subset of Chrome emulation overrides in one call: device metrics (width/height together, plus deviceScaleFactor/mobile), userAgent, cpuThrottlingRate (>=1), emulated media type + mediaFeatures, and networkConditions. Pass clearOverrides:true to reset every override to the browser default (ignores all other fields). Non-metrics overrides are session-scoped and reset when the per-call connection closes; device-metrics overrides persist on the target until cleared or the renderer navigates/reloads.",
+    description: "Apply any subset of Chrome emulation overrides in one call: device metrics (width/height together, plus deviceScaleFactor/mobile), userAgent, cpuThrottlingRate (>=1), emulated media type + mediaFeatures, and networkConditions. Pass clearOverrides:true to reset every override to the browser default (ignores all other fields); as of 1.9.2 that genuinely clears a device-metrics override set by a DIFFERENT process (Emulation.clearDeviceMetricsOverride is a no-op unless the clearing connection also set the override, so the driver re-asserts the tab's current size on its own connection first, then clears — and throws rather than answering cleared:true if it cannot verify that). Non-metrics overrides are session-scoped and reset when the per-call connection closes; device-metrics overrides persist on the target until cleared or the renderer navigates/reloads.",
     inputSchema: {
       type: "object",
       properties: {
@@ -6184,10 +7056,15 @@ class BidiConnection {
     } catch {}
   }
 }
-async function connectBidiSession(port, opts = {}) {
-  const conn = new BidiConnection(`ws://127.0.0.1:${port}/session`, { timeoutMs: opts.timeoutMs });
+async function connectBidiSessionUrl(wsUrl, opts = {}) {
+  const conn = new BidiConnection(wsUrl, { timeoutMs: opts.timeoutMs });
   await conn.connect();
-  await conn.newSession(opts.capabilities ?? {});
+  try {
+    await conn.newSession(opts.capabilities ?? {});
+  } catch (e) {
+    conn.dispose();
+    throw e;
+  }
   conn.retain();
   return conn;
 }
@@ -6763,21 +7640,27 @@ var BIDI_CAPABILITIES = new Set([
   "emulate.deviceMetrics",
   "screenshot.fullPage",
   "screenshot.element",
+  "screenshot.renderSize",
   "network.intercept",
   "locate.xpath"
 ]);
 var connections = new Map;
-async function getConnection(port, timeoutMs) {
-  const existing = connections.get(port);
+async function getConnection(endpoint, timeoutMs) {
+  const existing = connections.get(endpoint);
   if (existing) {
     existing.retain();
     return existing;
   }
-  const conn = await connectBidiSession(port, {
+  const conn = await connectBidiSessionUrl(endpoint, {
     ...timeoutMs !== undefined ? { timeoutMs } : {},
     capabilities: { alwaysMatch: { unhandledPromptBehavior: { default: "ignore" } } }
+  }).catch((e) => {
+    if (e instanceof BidiError && /maximum number of active sessions/i.test(e.message)) {
+      throw driverError2("disconnected", `Firefox already has an active WebDriver BiDi session on ${endpoint}; it allows only one. ` + `Close the other client, or restart Firefox, then retry. (A previously killed client can leave a ` + `session that Firefox does not reap.)`);
+    }
+    throw e;
   });
-  connections.set(port, conn);
+  connections.set(endpoint, conn);
   return conn;
 }
 var bidiBeaconScripts = new Map;
@@ -7126,7 +8009,55 @@ class BidiPageDriver {
       throw mapBidiError(e);
     }
   }
-  async screenshot(opts) {
+  async screenshot(opts, _consumeBands) {
+    const renderSize = opts?.renderWidth !== undefined && opts?.renderHeight !== undefined ? { width: opts.renderWidth, height: opts.renderHeight } : undefined;
+    if (!renderSize)
+      return this.capture(opts);
+    const previous = await readViewportRecord(this.browser.scheme, this.contextId);
+    try {
+      await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: renderSize.width, height: renderSize.height } });
+    } catch (e) {
+      throw mapBidiError(e);
+    }
+    let shot;
+    let captureError;
+    try {
+      shot = await this.capture(opts);
+    } catch (e) {
+      captureError = e;
+    }
+    let restoreError;
+    try {
+      if (previous) {
+        await this.conn.send("browsingContext.setViewport", {
+          context: this.contextId,
+          viewport: { width: previous.width, height: previous.height },
+          ...previous.deviceScaleFactor != null ? { devicePixelRatio: previous.deviceScaleFactor } : {}
+        });
+      } else {
+        await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null });
+      }
+    } catch (e) {
+      restoreError = e instanceof Error ? e.message : String(e);
+    }
+    if (!shot) {
+      if (restoreError !== undefined && captureError instanceof Error) {
+        captureError.message = `${captureError.message} ${renderRestoreFailureNote(renderSize, restoreError)}`;
+      }
+      throw captureError;
+    }
+    const result = { ...shot, renderSize, renderRestored: restoreError === undefined };
+    if (restoreError !== undefined)
+      result.renderRestoreError = restoreError;
+    return result;
+  }
+  async capture(opts) {
+    if (opts?.scale !== undefined && opts.scale !== 1) {
+      throw driverError2("unsupported", `screenshot scale ${opts.scale} is not supported by this backend (WebDriver BiDi's ` + "browsingContext.captureScreenshot has no scale parameter). Call emulate with " + `deviceScaleFactor:${opts.scale} first and capture at scale 1, or use --browser chrome.`);
+    }
+    if (opts?.tile === true) {
+      throw driverError2("unsupported", "screenshot tile:true is not supported by this backend: band tiling is declared only where the band " + "arithmetic has been measured against a real browser, and Firefox was not driven for it " + `(browsingContext.captureScreenshot's clip:{type:"box"} is the primitive it would ride, untested). ` + "Capture a smaller region or a single element, or use --browser chrome for a tiled capture.");
+    }
     const format = opts?.format ?? "png";
     const params = {
       context: this.contextId,
@@ -7151,12 +8082,18 @@ class BidiPageDriver {
       await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: null, devicePixelRatio: null }).catch(() => {
         return;
       });
+      await clearViewportRecord(this.browser.scheme, this.contextId);
       return { applied: [] };
     }
     const applied = [];
     try {
       if (opts.width != null && opts.height != null) {
         await this.conn.send("browsingContext.setViewport", { context: this.contextId, viewport: { width: opts.width, height: opts.height }, ...opts.deviceScaleFactor != null ? { devicePixelRatio: opts.deviceScaleFactor } : {} });
+        await writeViewportRecord(this.browser.scheme, this.contextId, {
+          width: opts.width,
+          height: opts.height,
+          ...opts.deviceScaleFactor != null ? { deviceScaleFactor: opts.deviceScaleFactor } : {}
+        });
         applied.push("deviceMetrics");
       }
       if (opts.userAgent != null) {
@@ -7364,19 +8301,19 @@ class BidiPageDriver {
 }
 
 class BidiBrowserDriver {
-  port;
+  endpoint;
   timeoutMs;
   scheme = "bidi";
   lifetime = "session";
   capabilities = BIDI_CAPABILITIES;
   uidStability = "document-stamp";
   snapshotFidelity = "dom-heuristic";
-  constructor(port, timeoutMs) {
-    this.port = port;
+  constructor(endpoint, timeoutMs) {
+    this.endpoint = endpoint;
     this.timeoutMs = timeoutMs;
   }
   async listPages() {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       const { contexts } = await conn.send("browsingContext.getTree", {}).catch((e) => {
         throw mapBidiError(e);
@@ -7387,7 +8324,7 @@ class BidiBrowserDriver {
     }
   }
   async newPage(url) {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       const { context } = await conn.send("browsingContext.create", { type: "tab" }).catch((e) => {
         throw mapBidiError(e);
@@ -7402,7 +8339,7 @@ class BidiBrowserDriver {
     }
   }
   async closePage(id) {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       await conn.send("browsingContext.close", { context: id }).catch((e) => {
         throw mapBidiError(e);
@@ -7413,7 +8350,7 @@ class BidiBrowserDriver {
     }
   }
   async activatePage(id) {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     try {
       await conn.send("browsingContext.activate", { context: id }).catch((e) => {
         throw mapBidiError(e);
@@ -7425,7 +8362,7 @@ class BidiBrowserDriver {
     }
   }
   async page(selector) {
-    const conn = await getConnection(this.port, this.timeoutMs);
+    const conn = await getConnection(this.endpoint, this.timeoutMs);
     let ctx;
     try {
       ctx = await resolveContext(conn, selector);
@@ -7437,13 +8374,13 @@ class BidiBrowserDriver {
     return new BidiPageDriver(conn, ctx.context, info, this);
   }
   async installActivityBeacon(contextId) {
-    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+    const conn = await getConnection(this.endpoint, this.timeoutMs).catch(() => {
       return;
     });
     if (!conn)
       return false;
     try {
-      const key = `${this.port}:${contextId}`;
+      const key = `${this.endpoint}:${contextId}`;
       if (!bidiBeaconScripts.has(key)) {
         const registered = await conn.send("script.addPreloadScript", {
           functionDeclaration: BEACON_FUNCTION_DECLARATION,
@@ -7464,7 +8401,7 @@ class BidiBrowserDriver {
     }
   }
   async readActivityBeacon(contextId) {
-    const conn = await getConnection(this.port, this.timeoutMs).catch(() => {
+    const conn = await getConnection(this.endpoint, this.timeoutMs).catch(() => {
       return;
     });
     if (!conn)
@@ -7487,18 +8424,24 @@ class BidiBrowserDriver {
   }
   async dispose() {
     for (const key of [...bidiBeaconScripts.keys()]) {
-      if (key.startsWith(`${this.port}:`))
+      if (key.startsWith(`${this.endpoint}:`))
         bidiBeaconScripts.delete(key);
     }
-    const conn = connections.get(this.port);
+    const conn = connections.get(this.endpoint);
     if (!conn)
       return;
-    connections.delete(this.port);
+    connections.delete(this.endpoint);
+    await conn.send("session.end", {}).catch(() => {
+      return;
+    });
     conn.dispose();
   }
 }
 function createFirefoxDriver(port, opts) {
-  return new BidiBrowserDriver(port, opts?.timeoutMs);
+  return new BidiBrowserDriver(`ws://127.0.0.1:${port}/session`, opts?.timeoutMs);
+}
+function createFirefoxDriverForEndpoint(wsUrl, opts) {
+  return new BidiBrowserDriver(wsUrl, opts?.timeoutMs);
 }
 
 // src/bidi/launch.ts
@@ -7506,7 +8449,7 @@ import { spawn as spawn3 } from "node:child_process";
 import { mkdtempSync, rmSync } from "node:fs";
 import { createConnection, createServer } from "node:net";
 import { tmpdir } from "node:os";
-import { join as join9 } from "node:path";
+import { join as join10 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -7580,7 +8523,7 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join9(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join10(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
@@ -7618,10 +8561,10 @@ async function launchFirefox(opts = {}) {
 }
 
 // src/backend.ts
-function resolveBrowserKind(argv) {
+function resolveBrowserKind(argv, env = process.env) {
   const flagIdx = argv.indexOf("--browser");
   const flagVal = flagIdx !== -1 ? argv[flagIdx + 1] : undefined;
-  const raw = flagVal ?? process.env.CDP_BROWSER ?? "chrome";
+  const raw = flagVal ?? env.CDP_BROWSER ?? "chrome";
   if (raw !== "chrome" && raw !== "firefox") {
     throw new Error(`unknown --browser '${raw}': expected 'chrome' or 'firefox' (or set CDP_BROWSER)`);
   }
@@ -7638,7 +8581,79 @@ function stripBrowserFlag(argv) {
   }
   return out;
 }
+function normalizeBidiEndpoint(raw) {
+  const value = raw.trim();
+  if (/^wss?:\/\//i.test(value)) {
+    let url;
+    try {
+      url = new URL(value);
+    } catch {
+      throw new Error(`invalid Firefox endpoint '${raw}': not a parseable ws:// URL`);
+    }
+    if (url.pathname === "" || url.pathname === "/")
+      url.pathname = "/session";
+    return url.toString();
+  }
+  if (/^\d+$/.test(value))
+    return `ws://127.0.0.1:${assertPort(value, raw)}/session`;
+  const hostPort = /^([^:/]+):(\d+)$/.exec(value);
+  if (hostPort)
+    return `ws://${hostPort[1]}:${assertPort(hostPort[2], raw)}/session`;
+  throw new Error(`invalid Firefox endpoint '${raw}': expected a port (9223), host:port, or a ws:// URL`);
+}
+function assertPort(digits, raw) {
+  const port = Number(digits);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`invalid Firefox endpoint '${raw}': port must be 1-65535`);
+  }
+  return port;
+}
+function resolveFirefoxEndpoint(argv, env = process.env) {
+  const flagIdx = argv.indexOf("--connect");
+  const raw = (flagIdx !== -1 ? argv[flagIdx + 1] : undefined) ?? env.CDP_FIREFOX_ENDPOINT;
+  if (raw === undefined || raw === "")
+    return;
+  return normalizeBidiEndpoint(raw);
+}
+function stripConnectFlag(argv) {
+  const out = [];
+  for (let i = 0;i < argv.length; i++) {
+    if (argv[i] === "--connect") {
+      i++;
+      continue;
+    }
+    out.push(argv[i]);
+  }
+  return out;
+}
+function resolveBackend(argv, env = process.env) {
+  const endpoint = resolveFirefoxEndpoint(argv, env);
+  let kind = resolveBrowserKind(argv, env);
+  const explicitBrowser = argv.includes("--browser") || env.CDP_BROWSER !== undefined;
+  if (endpoint !== undefined) {
+    if (explicitBrowser && kind === "chrome") {
+      throw new Error("--connect / CDP_FIREFOX_ENDPOINT is a Firefox attach option and is not valid with the chrome backend");
+    }
+    kind = "firefox";
+  }
+  return endpoint !== undefined ? { kind, endpoint } : { kind };
+}
 async function startFirefoxSession(opts) {
+  if (opts?.endpoint !== undefined) {
+    const driver2 = createFirefoxDriverForEndpoint(opts.endpoint);
+    let disposed2 = false;
+    return {
+      driver: driver2,
+      async dispose() {
+        if (disposed2)
+          return;
+        disposed2 = true;
+        await driver2.dispose().catch(() => {
+          return;
+        });
+      }
+    };
+  }
   const launched = await launchFirefox({ headless: opts?.headless });
   const driver = createFirefoxDriver(launched.port);
   let disposed = false;
@@ -7656,9 +8671,9 @@ async function startFirefoxSession(opts) {
   };
 }
 var sessionPromise;
-function getOrCreateFirefoxSession() {
+function getOrCreateFirefoxSession(opts) {
   if (!sessionPromise)
-    sessionPromise = startFirefoxSession();
+    sessionPromise = startFirefoxSession({ endpoint: opts?.endpoint });
   return sessionPromise;
 }
 async function disposeFirefoxSession() {
@@ -7859,8 +8874,8 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.9.1";
-var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
+var VERSION = "1.9.5";
+var { kind: BROWSER, endpoint: FIREFOX_ENDPOINT } = resolveBackend(process.argv.slice(2));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);
 var dispatch = TOOLS;
@@ -7906,7 +8921,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!neutralFn)
       return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
     try {
-      const session2 = await getOrCreateFirefoxSession();
+      const session2 = await getOrCreateFirefoxSession({ endpoint: FIREFOX_ENDPOINT });
       const result = await neutralFn(session2.driver, args);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
@@ -7918,7 +8933,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 auditCoverage();
 markLongLivedProcess();
 await server.connect(new StdioServerTransport);
-console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
+console.error(`[cdp-toolkit] MCP server v${VERSION} ready, browser=${BROWSER}${FIREFOX_ENDPOINT ? ` (attach ${FIREFOX_ENDPOINT})` : ""}, ${AVAILABILITY.available.length} tools, CDP_BASE=${BASE}`);
 var shuttingDown = false;
 async function shutdown() {
   if (shuttingDown)