cdp-toolkit 1.9.1 → 1.9.5

package/dist/cli.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 };
 }
@@ -4522,10 +5378,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;
 }
@@ -5101,21 +5962,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;
@@ -5464,7 +6331,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,
@@ -5489,12 +6404,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) {
@@ -5702,19 +6623,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);
@@ -5725,7 +6646,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);
@@ -5740,7 +6661,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);
@@ -5751,7 +6672,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);
@@ -5763,7 +6684,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);
@@ -5775,13 +6696,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,
@@ -5802,7 +6723,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)
@@ -5825,18 +6746,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
@@ -5844,7 +6771,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,
@@ -5918,7 +6845,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");
@@ -5956,10 +6883,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)`);
   }
@@ -5976,7 +6903,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;
@@ -5994,9 +6993,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() {
@@ -6196,13 +7195,1688 @@ var FIREFOX_TOOLS = {
   ...LEASE_TOOLS
 };
 
+// src/manifest.ts
+var MANIFEST = [
+  {
+    name: "list_pages",
+    description: "Enumerate browser page targets via the CDP browser endpoint (GET /json/list). By default returns only page-type tabs; set 'all' to also include workers and background pages. Each entry carries the targetId used as a target selector elsewhere, plus an 'origin' field recording where the tab came from: 'agent' means this toolkit created it (the entry then also carries the creating 'label' and 'createdAt'), and this stays true after the creating agent releases its lease or dies, which is what makes a stray agent tab findable later. 'unknown' means there is no creation record. It never says 'human': the toolkit cannot prove a person opened a tab, so 'unknown' is the honest word for a tab it did not create, one opened before the toolkit ran, or one whose record could not be written. A tab whose record exists but could not be read reports origin 'unknown' plus 'originUnreadable', so a broken record is never mistaken for no record. Under CDP_REQUIRE_LEASE this call also reaps abandoned agent tabs, but reap-CLOSE and lease-RECLAIMABLE (list_leases' 'stale') now fire at different times: a lease reads reclaimable the moment its TTL elapses, cheap and reversible since another agent may simply take it, while this call only CLOSES the tab, destructively, after an ADDITIONAL grace period past that TTL (CDP_REAP_GRACE_MS, default 2700000ms/45 minutes, so 60 minutes total after last use) — a tab an agent is mid-build between calls on is not destroyed out from under it. A dead-pid lease is reaped immediately regardless of grace: that process is never coming back. Closed tabs are reported in an additive 'reaped' array ({targetId,label,reason}) present only when something was actually closed; a tab with no lease is never reaped. Every entry under an active, readable lease of this backend also carries 'lease': {label, pid, idleMs, expiresAt, stale} — idleMs and expiresAt are computed fresh on every call (now-lastUsedAt and lastUsedAt+ttlMs), never read off disk, and this is unconditional on 'probe'. Set 'probe' to true to also ping each page-type target's renderer: one bounded (500ms) check per target, never more, so a single wedged tab cannot stall the listing beyond its own budget. This adds 'responsive' (true iff the ping answered in time; false on a timeout, a page-side exception, or an unreachable target — never an error for the whole call) and, where that same round trip found human-attributed input, 'humanActiveMs' (see claim_page and list_leases for what that field means and cannot prove). 'responsive' and 'humanActiveMs' are both ABSENT — never false/null — when 'probe' is not set, and 'responsive' is likewise absent on a backend that cannot answer this ping at all.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        all: {
+          type: "boolean",
+          description: "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
+        },
+        probe: {
+          type: "boolean",
+          description: "Ping each page-type target's renderer before returning: one bounded (500ms) Runtime.evaluate per target, never more. Adds 'responsive' to every page-type entry and, where the same round trip finds human-attributed input, 'humanActiveMs'. A wedged or unreachable tab reports responsive:false rather than failing the call. Defaults to false, which is byte-identical to the pre-1.8.0 shape."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "new_page",
+    description: "Open a new browser tab via Target.createTarget and return {targetId,url}. Defaults to about:blank; navigation is not awaited here (use navigate_page to load and wait).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        url: {
+          type: "string",
+          description: "URL to open in the new tab; defaults to about:blank."
+        },
+        claim: {
+          type: "boolean",
+          description: "Claim the new tab atomically as part of creating it and return a lease token alongside {targetId,url}. Default false, which is byte-identical to the pre-1.2 behavior. Under CDP_REQUIRE_LEASE the new tab is claimed and a lease returned even without claim:true, because a tab nobody holds is a tab nobody may drive; passing claim:true additionally makes the lease an explicit one, which requires its token on every later call even from this same process."
+        },
+        label: {
+          type: "string",
+          description: "Agent label recorded on the lease when claim:true, surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        ttlMs: {
+          type: "number",
+          description: "How long the lease taken by claim:true survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires. Ignored without claim:true."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "close_page",
+    description: "Close a page target via Target.closeTarget. Requires an explicit, resolvable target; refuses to guess and errors if the selector matches no target.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        }
+      },
+      required: [
+        "target"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "select_page",
+    description: "Activate/focus a page target via Target.activateTarget and persist its bare targetId to the selected-state file (CDP_STATE_DIR/selected). Requires an explicit, resolvable target.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        }
+      },
+      required: [
+        "target"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "navigate_page",
+    description: "Navigate a target page to a URL (Page.navigate), reload it (reload:true), OR go back/forward in its session history (history:'back'|'forward'), then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Exactly one of url / reload / history per call. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload, traversed:'back'|'forward' on a history move); waitUntil supports 'load'|'domcontentloaded' only (no 'networkidle'), and there is no auto-snapshot of the new page. Pass reload:true with ignoreCache:true for a hard reload that refetches every subresource (e.g. to pick up a freshly-deployed, non-content-hashed bundle the HTTP cache would serve stale).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        url: {
+          type: "string",
+          description: "Destination URL to navigate to. Required unless reload:true."
+        },
+        reload: {
+          type: "boolean",
+          description: "Reload the current page (Page.reload) instead of navigating to url. Default false."
+        },
+        history: {
+          type: "string",
+          enum: [
+            "back",
+            "forward"
+          ],
+          description: "Traverse this tab's session history instead of loading a url: 'back' and 'forward' are the browser's Back and Forward buttons. Mutually exclusive with 'url' and 'reload' — passing two of the three is refused by name rather than resolved by precedence. Works on BOTH backends (Chrome: Page.getNavigationHistory + Page.navigateToHistoryEntry; Firefox: browsingContext.traverseHistory) and waits for the same load milestone as an ordinary navigation. Going back from the first entry, or forward from the last, is an ERROR naming the direction — never a silent success that navigated nowhere. The result carries traversed:'back'|'forward' alongside the resulting url."
+        },
+        ignoreCache: {
+          type: "boolean",
+          description: "On reload, bypass the HTTP cache (hard reload) so subresources are refetched. Ignored unless reload:true. Default false."
+        },
+        waitUntil: {
+          type: "string",
+          enum: [
+            "load",
+            "domcontentloaded"
+          ],
+          description: "Which load milestone to wait for. Defaults to 'load'. No 'networkidle' support."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Override the navigation timeout in milliseconds."
+        }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "wait_for",
+    description: "Poll a target page until the given substring appears in document.body.innerText (Runtime.evaluate on a fixed interval), or throw on timeout. Text-substring waiting only: no aria/role/selector or event variants; throws rather than returning {found:false}.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        text: {
+          type: "string",
+          description: "Substring to wait for in document.body.innerText. Required."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Total time budget in milliseconds. Defaults to 15000."
+        },
+        pollMs: {
+          type: "number",
+          description: "Poll interval in milliseconds. Defaults to 250."
+        }
+      },
+      required: [
+        "text"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "evaluate_script",
+    description: "Run arbitrary JavaScript in the target page's main-world context over raw CDP and return the evaluated value (returnByValue). With no 'args' the 'expression' is evaluated as a raw expression; when 'args' is provided 'expression' must be a function literal (arrow or classic) invoked on globalThis with the args passed positionally. A thrown exception surfaces as an error; non-serializable returns (DOM nodes, functions) come back as their CDP description string. Pass 'savePath' to write the evaluated value to a JSON file instead: the response then carries only {path,bytes,type,target} and the value itself never appears in it, in any form. That is the way to read a credential (a JWT or session token out of localStorage, for example) without putting the secret into the caller's transcript. This is the one tool that can EVALUATE inside an MV3 extension's background SERVICE WORKER rather than a page (list_network_requests/get_network_request/list_console_messages OBSERVE one): pass target 'worker:<extension-id>' (Chrome only) and read chrome.storage.local, chrome.runtime and the worker's own globals directly, with an idle-evicted worker started for you first (see 'wake').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Page selector: 'active' (or omit) -> first page-type target | '<32-hex targetId>' -> exact target by id | 'index:N' -> Nth page-type target (0-based) | 'url:<substring>' -> first page whose url contains substring | 'title:<substring>' -> first page whose title contains substring | 'label:<name>' -> the page-type target with exactly this label (checked against the origin ledger and live leases) | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js) and read chrome.storage.local from it. The worker: arm is CHROME-ONLY (Capability 'worker.targets') and is accepted by four tools only — evaluate_script, list_network_requests, get_network_request and list_console_messages — never as universal grammar; an MV3 worker that has been idle-evicted is started automatically first, see 'wake'."
+        },
+        wake: {
+          type: "boolean",
+          description: "Only valid with a 'worker:<substring>' target, and rejected on a page target rather than ignored. Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so a wake asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything; the error then says the worker may simply be asleep."
+        },
+        expression: {
+          type: "string",
+          description: "JavaScript to run. Evaluated as an expression when 'args' is omitted; must be a function literal (arrow or classic) whose parameters receive 'args' when 'args' is provided. REQUIRED — the code always goes in this key, never in 'function', 'code', 'js', 'script', 'fn' or 'body'; a call using one of those instead is rejected with an error naming the wrong key."
+        },
+        awaitPromise: {
+          type: "boolean",
+          description: "Await the result if it is a Promise (default true)."
+        },
+        args: {
+          type: "array",
+          description: "Positional JSON-serializable arguments to pass to the expression, treating it as a function. No live element/page handle is bound."
+        },
+        savePath: {
+          type: "string",
+          description: "Write the evaluated value to this file as JSON and KEEP IT OUT OF THE RESPONSE: with savePath set the result is {path,bytes,type,target} only, with no copy, preview or truncation of the value. Use it to read credentials without putting them in a transcript. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the value back inline, exactly as before."
+        }
+      },
+      required: [
+        "expression"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_cookies",
+    description: "Read the cookie store for the target page, INCLUDING httpOnly cookies, which document.cookie cannot see and an evaluate_script call therefore cannot reach. Each cookie carries name, value, domain, path, expires (Unix seconds, -1 for a session cookie), size, httpOnly, secure, sameSite ('strict'|'lax'|'none'|'default') and session. The read is page-scoped, not browser-wide: it returns the cookies of the resolved tab (Chrome: Network.getCookies; Firefox: storage.getCookies partitioned by that browsing context), so point at a page on the site whose cookies you want. Filter with 'domain' and/or 'name'. Pass 'savePath' to write the cookie array to a JSON file instead: the response is then {path,bytes,count,target} only, with no cookie value in it in any form, which is how to capture a session cookie without putting the credential in the caller's transcript.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+        },
+        domain: {
+          type: "string",
+          description: "Keep only cookies for this domain. A leading dot is ignored on both sides and subdomains of the given domain match too, so 'example.test' matches '.example.test' and 'app.example.test'. No wildcards."
+        },
+        name: {
+          type: "string",
+          description: "Keep only the cookie with exactly this name. Exact match, not a substring."
+        },
+        savePath: {
+          type: "string",
+          description: "Write the cookie array to this file as JSON and KEEP THE VALUES OUT OF THE RESPONSE: with savePath set the result is {path,bytes,count,target} only, with no copy, preview or truncation of any cookie value. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Missing parent directories are created. Omit it to get the cookies back inline."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "set_cookie",
+    description: "Write one cookie into the target page's cookie store, INCLUDING an httpOnly or secure cookie, which document.cookie cannot create and an evaluate_script call therefore cannot either. Chrome uses Network.setCookie, Firefox uses storage.setCookie partitioned by the resolved browsing context. Either 'url' or 'domain' is REQUIRED: a cookie has to be attributed to a site and the call is refused with an error when neither is given, rather than guessing the current page's origin. The response is {set:true,target} and never echoes the value back, so a credential you just supplied does not land in the transcript twice. A 'set:true' is earned, not assumed: Chrome answers Network.setCookie with success:false when it declines a cookie (a domain the url does not belong to, a secure cookie on an insecure origin, an oversized value) and that refusal is raised as an error. On Firefox, 'domain' is derived from 'url' when only the url was given, because BiDi has no url parameter; a url with no host, such as about:blank or a data URL, is an error rather than a silent no-op. Read the result back with list_cookies when you need proof.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+        },
+        name: {
+          type: "string",
+          description: "Cookie name. Required and non-empty."
+        },
+        value: {
+          type: "string",
+          description: "Cookie value. Required. It is not echoed back in the response."
+        },
+        url: {
+          type: "string",
+          description: "The URL the cookie is set for, for example 'https://example.com/'. Chrome derives domain, path and secure from it. Firefox derives only the domain from its host. Give this or 'domain'."
+        },
+        domain: {
+          type: "string",
+          description: "Cookie domain, for example 'example.com' or '.example.com' for subdomains. Give this or 'url'. When both are given, this wins on Firefox and Chrome applies its own url plus domain consistency rule."
+        },
+        path: {
+          type: "string",
+          description: "Cookie path. Passed through exactly as given and NOT defaulted to '/': with a 'url' Chrome derives the path from it, so an invented default here would widen a cookie you meant to scope narrowly."
+        },
+        expires: {
+          type: "number",
+          description: "Expiry as Unix time in SECONDS, matching what list_cookies reports. Omit it for a session cookie, which is what both backends do when no expiry is supplied."
+        },
+        httpOnly: {
+          type: "boolean",
+          description: "Set the httpOnly flag, making the cookie invisible to document.cookie. Only a protocol write like this one can create such a cookie."
+        },
+        secure: {
+          type: "boolean",
+          description: "Set the secure flag. Chrome declines a secure cookie on an insecure origin, and that refusal surfaces as an error."
+        },
+        sameSite: {
+          type: "string",
+          enum: ["strict", "lax", "none", "default"],
+          description: "SameSite attribute, lowercase, matching what list_cookies reports. 'default' means the attribute is not set at all."
+        }
+      },
+      required: ["name", "value"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "delete_cookies",
+    description: "Delete the named cookie from the target page's cookie store, httpOnly cookies included. Chrome uses Network.deleteCookies, Firefox uses storage.deleteCookies with a filter, partitioned by the resolved browsing context. Both 'name' and one of 'url' or 'domain' are REQUIRED: without a site constraint the call would delete by name across the whole partition, so it is refused with an error instead. Narrow further with 'path'. The response is {deleted:true,target} and carries NO count, because neither protocol reports how many cookies it removed and a number here would be invented; call list_cookies before and after when you need a real count. 'deleted:true' means the backend accepted and performed the deletion, not that a matching cookie existed, since deleting an absent cookie is a success on both backends.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+        },
+        name: {
+          type: "string",
+          description: "Exact cookie name to delete. Required and non-empty. No wildcards: this removes a named cookie, not a swathe of them."
+        },
+        url: {
+          type: "string",
+          description: "Delete cookies matching this URL, for example 'https://example.com/'. Give this or 'domain'. On Firefox only the host is used, because BiDi's filter has no url field."
+        },
+        domain: {
+          type: "string",
+          description: "Delete cookies with this exact domain. Give this or 'url'."
+        },
+        path: {
+          type: "string",
+          description: "Narrow the deletion to cookies with this exact path. Omit to match any path allowed by the other constraints."
+        }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "take_snapshot",
+    description: "Capture the page's accessibility tree (Accessibility.getFullAXTree) as a compact indented text tree where each line is prefixed with [uid], the node's CDP backendDOMNodeId. These uids are the stateless element references that every interaction tool (click/hover/fill/etc.) feeds back to resolve a live DOM node (via DOM.resolveNode({ backendNodeId: uid })), so run this first to discover uids.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default, = first page-type target) | 'index:N' (Nth page-type target, 0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | '<32-hex targetId>' (exact target by id)."
+        },
+        interactiveOnly: {
+          type: "boolean",
+          description: "When true, emit only interactive/meaningful nodes flattened into a readable list; default false returns the full hierarchical a11y tree."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "click",
+    description: "Click an element via a synthetic mouse press/release at the element's scrolled-into-view bounding-rect center. Target the element with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector). clickCount:3 triple-clicks (selects a paragraph/line in most editors). 'modifiers' holds Alt/Control/Meta/Shift for the press and release, like a real modifier-click; on the Firefox backend a non-empty 'modifiers' throws (not yet supported over BiDi), so a modifier click there needs --browser chrome.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the element to click, obtained from take_snapshot. Provide exactly one of uid or selector."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the element to click (resolved via document.querySelector). Provide exactly one of uid or selector."
+        },
+        button: {
+          type: "string",
+          enum: [
+            "left",
+            "right",
+            "middle"
+          ],
+          description: "Mouse button: 'left' (default), 'right', or 'middle'."
+        },
+        clickCount: {
+          type: "number",
+          description: "Number of clicks: 1 = single (default), 2 = double-click, 3 = triple-click."
+        },
+        modifiers: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          description: "Modifier keys held for the click's press and release, e.g. ['Shift'] for a shift-click. Not supported on the Firefox backend: passing a non-empty array there throws."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "hover",
+    description: "Hover the mouse over an element by dispatching a mouseMoved event at its scrolled-into-view center, firing framework hover handlers. Target with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the element to hover, obtained from take_snapshot. Provide exactly one of uid or selector."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the element to hover (resolved via document.querySelector). Provide exactly one of uid or selector."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "drag",
+    description: `Drag from a source element to a destination. 'from' takes exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector. The destination is exactly one of 'to' (an element via uid/selector, or an absolute viewport point via x+y) or 'by' ({dx,dy} offset from the source point — sliders, map panning, resize handles). mode:'mouse' (default) dispatches synthetic mouse press/move/release: right for widgets built on raw pointer events, and Chrome does turn it into a real drag, but WHICH drag events reach the page depends on where the interpolated pointer path happens to land — measured on Chrome 151, the default steps:2 delivers ZERO dragover events, so an HTML5 drop zone written the standard way (preventDefault inside dragover) refuses the drop entirely. mode:'html5' performs the drag deterministically instead: Chrome's drag interception hands back the DragData the page's own dragstart built, and the toolkit replays it as dragEnter/dragOver/drop exactly at the destination, so a draggable="true" / dataTransfer drop zone works regardless of the pointer path. mode:'html5' is CHROME-ONLY: it requires capability 'input.html5Drag' and is rejected with a clear error under the Firefox backend, where the tool itself remains available for mouse-mode drags. 'steps' (default 2) sets how many interpolated mouse-move events are dispatched between source and destination; raise it for DnD libraries with a movement threshold or per-frame sampling.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        from: {
+          type: "object",
+          description: "Source element to drag from. Provide exactly one of uid or selector.",
+          properties: {
+            uid: {
+              type: "number",
+              description: "CDP backendDOMNodeId of the source element, obtained from take_snapshot."
+            },
+            selector: {
+              type: "string",
+              description: "CSS selector for the source element (resolved via document.querySelector)."
+            }
+          },
+          additionalProperties: false
+        },
+        to: {
+          type: "object",
+          description: "Where the drag ends: exactly one of uid, selector, or x+y. Mutually exclusive with 'by'; exactly one of to/by is required.",
+          properties: {
+            uid: {
+              type: "number",
+              description: "CDP backendDOMNodeId of the destination element, obtained from take_snapshot."
+            },
+            selector: {
+              type: "string",
+              description: "CSS selector for the destination element (resolved via document.querySelector)."
+            },
+            x: {
+              type: "number",
+              description: "Absolute viewport x-coordinate to drop at. Must be given together with 'y'. Use this when there is no droppable element to name (a canvas, a slider track)."
+            },
+            y: {
+              type: "number",
+              description: "Absolute viewport y-coordinate to drop at. Must be given together with 'x'."
+            }
+          },
+          additionalProperties: false
+        },
+        by: {
+          type: "object",
+          description: "Drag by an offset from the source element's center instead of to a destination: at least one of dx/dy, the other defaults to 0. Mutually exclusive with 'to'; exactly one of to/by is required. Use for sliders (by:{dx:40}), map panning, and resize handles.",
+          properties: {
+            dx: {
+              type: "number",
+              description: "Horizontal offset in CSS pixels; positive drags RIGHT."
+            },
+            dy: {
+              type: "number",
+              description: "Vertical offset in CSS pixels; positive drags DOWN."
+            }
+          },
+          additionalProperties: false
+        },
+        mode: {
+          type: "string",
+          enum: [
+            "mouse",
+            "html5"
+          ],
+          description: "'mouse' (default): synthetic mouse press/move/release, right for widgets built on raw pointer events. Chrome does turn this into a real HTML5 drag too, but WHICH drag events reach the page depends on the interpolated pointer path: at the default steps:2, an HTML5 drop zone written the standard way (preventDefault inside dragover) sees zero dragover events and refuses the drop. 'html5': real HTML5 drag-and-drop (dragstart/dragEnter/dragOver/drop with the page's own dataTransfer), deterministic regardless of pointer path. 'html5' is CHROME-ONLY and is rejected with a clear error under the Firefox backend."
+        },
+        steps: {
+          type: "number",
+          description: "Number of interpolated mouse-move events dispatched between the source and destination points, evenly spaced, the last landing exactly on the destination. Integer 1-500, default 2 (midpoint then destination). Raise it for DnD libraries with a movement threshold or per-frame sampling."
+        }
+      },
+      required: [
+        "from"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "scroll",
+    description: "Dispatch a wheel/scroll event at an anchor point: provide at most one of 'uid', 'selector', or 'x'+'y'; omit all three to scroll at the viewport center. An element anchor ('uid' or 'selector') is scrolled into view first, the same as click/hover. At least one of 'deltaX'/'deltaY' is required; positive 'deltaY' scrolls DOWN and positive 'deltaX' scrolls RIGHT (wheel-event convention). Chrome dispatches Input.dispatchMouseEvent{type:'mouseWheel'}; Firefox dispatches WebDriver BiDi's 'wheel' input source. Returns the resolved anchor point ({x,y}) plus the delta actually dispatched.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the element to scroll into view and anchor at, obtained from take_snapshot. Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the element to scroll into view and anchor at (resolved via document.querySelector). Provide at most one of uid, selector, or x+y; omit all three to scroll at the viewport center."
+        },
+        x: {
+          type: "number",
+          description: "Absolute viewport x-coordinate to anchor the scroll at. Must be given together with 'y'. Provide at most one of uid, selector, or x+y."
+        },
+        y: {
+          type: "number",
+          description: "Absolute viewport y-coordinate to anchor the scroll at. Must be given together with 'x'. Provide at most one of uid, selector, or x+y."
+        },
+        deltaX: {
+          type: "number",
+          description: "Horizontal scroll delta; positive scrolls RIGHT. At least one of deltaX/deltaY is required."
+        },
+        deltaY: {
+          type: "number",
+          description: "Vertical scroll delta; positive scrolls DOWN. At least one of deltaX/deltaY is required."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "dispatch_mouse",
+    description: "Dispatch exactly one raw mouse event ('move', 'down', or 'up') at absolute viewport coordinates: the toolkit's lowest-level input primitive. Compose move/down/move/up calls yourself to reach anything a physical mouse can do that click/drag's fixed sequences cannot — canvas drag-painting, marquee/rubber-band selection, a custom widget with its own hit-testing. Chrome-only (capability 'input.raw'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        action: {
+          type: "string",
+          enum: [
+            "move",
+            "down",
+            "up"
+          ],
+          description: "Which raw event to dispatch: 'move' (mouseMoved), 'down' (mousePressed), or 'up' (mouseReleased)."
+        },
+        x: {
+          type: "number",
+          description: "Viewport x-coordinate. Required on every call: CDP has no notion of a 'current pointer position' to default from."
+        },
+        y: {
+          type: "number",
+          description: "Viewport y-coordinate. Required on every call."
+        },
+        button: {
+          type: "string",
+          enum: [
+            "left",
+            "right",
+            "middle"
+          ],
+          description: "Mouse button: 'left' (default), 'right', or 'middle'."
+        },
+        clickCount: {
+          type: "number",
+          description: "Click-run length for a 'down' or 'up' event (2 = the second half of a double-click, 3 = triple-click). Ignored for 'move'; defaults to 1."
+        },
+        modifiers: {
+          type: "array",
+          items: {
+            type: "string",
+            enum: [
+              "Alt",
+              "Control",
+              "Meta",
+              "Shift"
+            ]
+          },
+          description: "Modifier keys held for this one event, e.g. ['Shift']."
+        }
+      },
+      required: [
+        "action",
+        "x",
+        "y"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "wait_for_download",
+    description: "Wait for a file download to finish and return it as a real file on disk: {path,suggestedFilename,bytes,url,target}. The file is written under the artifact dir's downloads/ folder and renamed from Chrome's internal guid to the page's own filename, collision-suffixed (report.csv, report-1.csv, ...). ORDERING RULE, and it is not optional: download capture must be ARMED BEFORE the click that starts the download — call wait_for_download{arm:true} first (it arms and returns immediately, reporting {armed:true,downloadPath,pending}), then click, then call wait_for_download to collect the finished file. This is Chrome's behavior, not a preference: the download-behavior override is per-connection state that Chrome REVERTS the moment the arming client disconnects, and an unarmed headless Chrome denies the download outright, so a download triggered before anything armed is lost with no file anywhere. SIDE EFFECT, browser-global: arming redirects EVERY download in this browser (all tabs, all origins) into the toolkit's downloads directory for as long as this server runs, and downloads no longer land in the user's normal Downloads folder. Because the arm lives on a connection this server process holds open, this is an MCP-server capability: under the one-shot CLI the connection dies with the process and nothing is captured. Chrome-only (capability 'browser.downloads'): absent from tools/list under the Firefox backend, never present-and-throwing, because WebDriver BiDi has no command to redirect a download to a chosen directory.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'. A download is browser-scoped, so this names the tab for the lease check and for the echoed target, not which download is returned."
+        },
+        arm: {
+          type: "boolean",
+          description: "Arm download capture and return immediately instead of waiting: {armed:true,downloadPath,pending}. Call this BEFORE the click that triggers the download. 'pending' counts downloads that already completed and have not been collected yet, so an arm call doubles as a peek."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "How long to wait for a download to complete, in milliseconds. Default 30000. Ignored with arm:true. A download that already completed and was not yet collected is returned immediately, so this only bounds the wait for a download still in flight."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "grant_permissions",
+    description: "Grant browser permissions for an origin up front, so a page asking for geolocation / notifications / clipboard gets an answer instead of showing a prompt no agent can click. 'permissions' takes CDP PermissionType values ('geolocation', 'notifications', 'clipboardReadWrite', 'camera', 'microphone', 'midi', ...); an unknown name is refused by Chrome with the bad value in the message. Returns {granted,origin,target}, or {reset:true,target} for a reset-only call. Grants are keyed by ORIGIN, not by tab: every tab on that origin is affected, including ones opened later. reset:true clears this server's previous grants first (or instead, when no permissions are given) — note CDP's reset is not origin-scoped, so it clears them for every origin at once. The grant lives on a connection this server process holds open and Chrome DISCARDS IT when that connection closes, so this is an MCP-server capability: under the one-shot CLI the grant dies with the process. Chrome-only (capability 'browser.permissions'): absent from tools/list under the Firefox backend, never present-and-throwing.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'. Used for the lease check and, when 'origin' is omitted, as the source of the origin to grant for."
+        },
+        permissions: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "CDP PermissionType values to grant, e.g. ['geolocation'] or ['clipboardReadWrite','clipboardSanitizedWrite']. Required unless reset:true. An empty array is refused rather than treated as a successful no-op."
+        },
+        origin: {
+          type: "string",
+          description: "Origin the grant applies to, e.g. 'https://example.com'. Defaults to the target tab's own origin. Required explicitly when that tab has no grantable origin (data:, blob:, about:blank all serialize to the opaque origin 'null'), which is refused with a message naming the tab's url."
+        },
+        reset: {
+          type: "boolean",
+          description: "Clear this server's previous permission grants (Browser.resetPermissions). With 'permissions' it resets FIRST and then grants, so the result is exactly the listed permissions; on its own it is a reset-only call answering {reset:true}. Not scoped to 'origin': CDP resets every origin at once."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "fill",
+    description: "Fill an element by focusing it, clearing existing content, then inserting 'value' via Input.insertText (atomic paste-like commit, not per-character keystrokes). Target with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the field to fill, obtained from take_snapshot. Provide exactly one of uid or selector."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the field to fill (resolved via document.querySelector). Provide exactly one of uid or selector."
+        },
+        value: {
+          type: "string",
+          description: "The text value to set; the field is cleared first so this overwrites existing content."
+        }
+      },
+      required: [
+        "value"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "fill_form",
+    description: "Fill multiple form fields in one call; each field is focused, cleared, then set via Input.insertText. Each field in the non-empty 'fields' array takes exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector, plus its string value.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        fields: {
+          type: "array",
+          description: "Non-empty array of fields to fill, each with exactly one of uid or selector plus a string value.",
+          items: {
+            type: "object",
+            properties: {
+              uid: {
+                type: "number",
+                description: "CDP backendDOMNodeId of the field, obtained from take_snapshot. Provide exactly one of uid or selector."
+              },
+              selector: {
+                type: "string",
+                description: "CSS selector for the field (resolved via document.querySelector). Provide exactly one of uid or selector."
+              },
+              value: {
+                type: "string",
+                description: "The text value to set; the field is cleared first so this overwrites existing content."
+              }
+            },
+            required: [
+              "value"
+            ],
+            additionalProperties: false
+          }
+        }
+      },
+      required: [
+        "fields"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "type_text",
+    description: "Focus an element and append 'text' via Input.insertText without clearing first (closest to typing). Target with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector' (a CSS selector).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the element to type into, obtained from take_snapshot. Provide exactly one of uid or selector."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the element to type into (resolved via document.querySelector). Provide exactly one of uid or selector."
+        },
+        text: {
+          type: "string",
+          description: "The text to insert; appended to existing content rather than overwriting it."
+        }
+      },
+      required: [
+        "text"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "press_key",
+    description: "Dispatch a keyDown/keyUp pair for a single key with optional modifiers. 'key' is a named key (Enter, Tab, Escape, ArrowDown, Backspace, etc.) or a single printable character; the named-key table is curated (no F-keys/numpad/IME).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        key: {
+          type: "string",
+          description: "Key to press: a named key like 'Enter', 'Tab', 'Escape', 'ArrowDown', 'Backspace', or a single printable character. Required."
+        },
+        modifiers: {
+          type: "array",
+          description: "Optional modifier names held during the press: 'Control'/'Ctrl', 'Shift', 'Alt', 'Meta'/'Cmd'.",
+          items: {
+            type: "string"
+          }
+        }
+      },
+      required: [
+        "key"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "upload_file",
+    description: "Attach one or more files to an <input type=file> element via DOM.setFileInputFiles. Target the input with exactly one of 'uid' (a CDP backendDOMNodeId from take_snapshot) or 'selector'; 'files' is an absolute path or array of absolute paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        uid: {
+          type: "number",
+          description: "CDP backendDOMNodeId of the file input element, obtained from take_snapshot. Provide exactly one of uid or selector."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector for the file input element (resolved via document.querySelector). Provide exactly one of uid or selector."
+        },
+        files: {
+          type: [
+            "string",
+            "array"
+          ],
+          items: {
+            type: "string"
+          },
+          description: "Absolute path, or array of absolute paths, to the file(s) to attach to the <input type=file>. Accepts a single string or an array of strings."
+        }
+      },
+      required: [
+        "files"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    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 — 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: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector. undefined or 'active' -> first page target; '<32-hex targetId>' -> exact target by id; 'index:N' -> Nth page target (0-based); 'url:<substring>' -> first page whose url contains substring; 'title:<substring>' -> first page whose title contains substring; 'label:<name>' -> the page with exactly this label (origin ledger or live lease)."
+        },
+        format: {
+          type: "string",
+          enum: [
+            "png",
+            "jpeg"
+          ],
+          description: "Image format. Defaults to png. quality applies only to jpeg."
+        },
+        quality: {
+          type: "number",
+          description: "JPEG quality 0-100 (default 80). Ignored for png."
+        },
+        fullPage: {
+          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."
+        },
+        selector: {
+          type: "string",
+          description: "CSS selector to clip the capture to. Mutually exclusive with uid."
+        },
+        savePath: {
+          type: "string",
+          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. 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: [],
+      additionalProperties: false
+    }
+  },
+  {
+    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); 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: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        width: {
+          type: "number",
+          description: "Device-metrics viewport width in CSS pixels. Must be supplied together with height."
+        },
+        height: {
+          type: "number",
+          description: "Device-metrics viewport height in CSS pixels. Must be supplied together with width."
+        },
+        deviceScaleFactor: {
+          type: "number",
+          description: "Device pixel ratio (DPR) for the device-metrics override; 0 uses the platform default."
+        },
+        mobile: {
+          type: "boolean",
+          description: "Whether to emulate a mobile device (affects viewport meta handling, scrollbars, etc.) for the device-metrics override."
+        },
+        userAgent: {
+          type: "string",
+          description: "User-Agent string to override via Emulation.setUserAgentOverride."
+        },
+        cpuThrottlingRate: {
+          type: "number",
+          description: "CPU throttling multiplier: 1 = no throttle, 2 = 2x slower, etc. Must be >= 1."
+        },
+        media: {
+          type: "string",
+          description: "Emulated CSS media type: 'screen' | 'print' | '' (clear)."
+        },
+        mediaFeatures: {
+          type: "array",
+          description: "Emulated media features, e.g. [{ name: 'prefers-color-scheme', value: 'dark' }].",
+          items: {
+            type: "object",
+            properties: {
+              name: {
+                type: "string",
+                description: "Media feature name, e.g. 'prefers-color-scheme'."
+              },
+              value: {
+                type: "string",
+                description: "Media feature value, e.g. 'dark'."
+              }
+            },
+            required: [
+              "name",
+              "value"
+            ],
+            additionalProperties: false
+          }
+        },
+        networkConditions: {
+          type: "object",
+          description: "Network condition overrides applied via Network.emulateNetworkConditions.",
+          properties: {
+            offline: {
+              type: "boolean",
+              description: "True to simulate offline."
+            },
+            latency: {
+              type: "number",
+              description: "Additional round-trip latency in milliseconds."
+            },
+            downloadThroughput: {
+              type: "number",
+              description: "Max download throughput in bytes/sec (-1 = no limit)."
+            },
+            uploadThroughput: {
+              type: "number",
+              description: "Max upload throughput in bytes/sec (-1 = no limit)."
+            },
+            connectionType: {
+              type: "string",
+              description: "Connection type: 'none' | 'cellular2g' | 'cellular3g' | 'cellular4g' | 'bluetooth' | 'ethernet' | 'wifi' | 'wimax' | 'other'."
+            }
+          },
+          additionalProperties: false
+        },
+        clearOverrides: {
+          type: "boolean",
+          description: "Reset every override (device metrics, UA, CPU, media, network) to the browser default; ignores all other fields when true."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "resize_page",
+    description: "Set the page's device-metrics width/height (the narrow case of emulate), optionally with deviceScaleFactor and mobile, then verify by reading back window.innerWidth/innerHeight after the override is applied. Requires positive numeric width and height. The device-metrics override persists on the target until cleared or the renderer navigates/reloads.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        width: {
+          type: "number",
+          description: "Viewport width in CSS pixels (must be positive)."
+        },
+        height: {
+          type: "number",
+          description: "Viewport height in CSS pixels (must be positive)."
+        },
+        deviceScaleFactor: {
+          type: "number",
+          description: "Device pixel ratio (DPR); 0 uses the platform default."
+        },
+        mobile: {
+          type: "boolean",
+          description: "Whether to emulate a mobile device for the device-metrics override."
+        }
+      },
+      required: [
+        "width",
+        "height"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "handle_dialog",
+    description: "Wait for the next JavaScript dialog (alert/confirm/prompt/beforeunload) on a page and respond via Page.handleJavaScriptDialog, accepting or dismissing it. Default mode resolves with the first handled dialog or throws on timeout; set autoMs to handle every dialog opening during a fixed window and resolve with the list. The dialog must be triggered out-of-band (e.g. by clicking a button), since a blocking dialog freezes the renderer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | 'label:<name>' (exact label match, origin ledger or live lease) | a 32-hex <targetId>."
+        },
+        accept: {
+          type: "boolean",
+          description: "Whether to accept (OK) or dismiss (Cancel) the dialog."
+        },
+        promptText: {
+          type: "string",
+          description: "Text to enter for a prompt() dialog when accepting."
+        },
+        timeoutMs: {
+          type: "number",
+          description: "How long to wait for the next dialog in milliseconds (default 15000)."
+        },
+        autoMs: {
+          type: "number",
+          description: "Auto-handle mode: keep handling every dialog that opens for this many milliseconds, then resolve with the list of handled dialogs (an empty list is valid; never throws on 'no dialog')."
+        }
+      },
+      required: [
+        "accept"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_console_messages",
+    description: "Read console output (logs, warnings, exceptions) captured for the target page. By default reads the target's existing shared buffer and returns parsed console entries (empty if no capture has run); with reload:true it reloads the page and records a fresh capture window (both console+network) so a network reload never wipes console history. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker's console.log arrives as Runtime.consoleAPICalled on its own session. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
+        },
+        reload: {
+          type: "boolean",
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
+        },
+        durationMs: {
+          type: "number",
+          description: "Capture window for reload mode, in milliseconds. Default 2500."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "get_console_message",
+    description: "Return a single console entry by zero-based index from the target's existing console buffer. Throws if the index is out of range; run list_console_messages (optionally with reload:true) first to populate the buffer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>'."
+        },
+        index: {
+          type: "number",
+          description: "Zero-based index into the parsed console entries. Default 0."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_network_requests",
+    description: "Return correlated network request rows (one per requestId, with status/headers/state) for the target page. By default reads the target's existing buffer; with reload:true it reloads and records a fresh both-domains capture window. Use filterUrl to keep only requests whose URL contains a substring. SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
+        },
+        reload: {
+          type: "boolean",
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer). With a worker: target there is nothing to reload: the window records for durationMs while the worker runs, and the session it holds keeps that worker from being idle-evicted until the capture stops."
+        },
+        durationMs: {
+          type: "number",
+          description: "Capture window for reload mode, in milliseconds. Default 2500."
+        },
+        filterUrl: {
+          type: "string",
+          description: "Only return requests whose URL contains this substring."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (reload:true). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "get_network_request",
+    description: "Return one network request (matched by exact requestId, else by url substring) including status/headers. Requires at least one of requestId or url (throws otherwise). With includeBody:true the body fetch drives a fresh capture (a reload for a page, a listen window for a worker) and is matched by url ONLY (a fresh capture re-mints requestIds, so a carried-over requestId cannot fetch a body, so it returns metadata plus bodyUnavailableReason). SERVICE WORKERS (Chrome only, Capability 'worker.targets'): pass target 'worker:<extension-id>' to watch an MV3 extension's BACKGROUND SERVICE WORKER. The outbound request that worker makes to your backend is recorded from CDP's Network domain on the worker's own session, which observes what the code ACTUALLY SENT and so needs neither of the two tricks a caller reaches for first. Both of those fail for ordinary JavaScript reasons rather than service-worker ones: a value bound at module top level is not visible from evaluate_script's global scope (plain lexical scoping, exactly the same in a page), and assigning self.fetch cannot rebind a fetch reference the module already captured. A worker capture has no reload to drive it: reload:true means 'listen for durationMs while the worker runs', so trigger the worker's work (another tool call, an extension message, an alarm) during the window; a worker woken by the call has already run its top-level code by the time the recorder attaches, so a request it makes at startup can be missed. SIDE EFFECT, deliberate and documented: the recording holds a CDP session on the worker, and that KEEPS THE WORKER ALIVE for as long as the capture runs — an MV3 worker is otherwise idle-evicted within seconds — and Chrome resumes evicting it once the capture stops.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>' | 'label:<name>' | 'worker:<substring>' -> a service/shared worker whose url contains the substring, which is how you reach an MV3 extension's background service worker (worker:<extension-id> or worker:background.js). The worker: arm is CHROME-ONLY (Capability 'worker.targets'), is refused on Firefox, and a bare worker target id works too."
+        },
+        requestId: {
+          type: "string",
+          description: "Match by exact requestId (metadata only, cannot fetch a body, since reload re-mints requestIds)."
+        },
+        url: {
+          type: "string",
+          description: "Match by URL substring (first match). Required for body fetch (includeBody), since url is stable across reload."
+        },
+        includeBody: {
+          type: "boolean",
+          description: "Also fetch the response body; drives a fresh reload capture and must be used with the `url` selector."
+        },
+        durationMs: {
+          type: "number",
+          description: "Capture window for the reload-driven body fetch, in milliseconds. Default 2500."
+        },
+        wake: {
+          type: "boolean",
+          description: "Worker targets only, and only when a capture is being started (includeBody together with url). Default true: an MV3 extension service worker is idle-evicted after seconds of inactivity and then exists in NO target listing, so the capture asks Chrome to start it (ServiceWorker.startWorker over a page session) and then re-reads the target list to confirm it actually came up. Pass false to fail fast instead of starting anything. Rejected rather than ignored on a page target, on a bare target id (Chrome re-mints a worker's target id when it restarts, so only the url-substring form can name a worker that is not running), and on a read-only call (the buffer is keyed by target id, so a woken worker's buffer would be empty)."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "performance_start_trace",
+    description: "Start a performance trace on the target page over raw CDP (Tracing.start) and park the recording connection in-process. Must be paired with performance_stop_trace WITHIN THE SAME PROCESS; for a robust cross-call trace use performance_trace instead. Throws if a trace is already in progress for the target.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        categories: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Trace categories to include. Defaults to the timeline + user-timing + loading + disabled-by-default timeline tracks that carry LCP/LayoutShift/RunTask."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "performance_stop_trace",
+    description: "Stop the in-process trace started by performance_start_trace, drain buffered Tracing.dataCollected events, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics}. Throws if no live trace exists in this process (e.g. start ran in a different process); use performance_trace instead. The 'target' arg is accepted only for API symmetry; at most one trace is ever live per process.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "performance_analyze_insight",
+    description: "CDP-native approximation of the DevTools insight analyzer: read a trace JSON file (bare array or {traceEvents:[...]}) at the given tracePath and return headline metrics (FCP/LCP/CLS/TBT, long tasks, layout shifts). Requires an explicit tracePath returned by performance_trace/performance_stop_trace; there is no implicit 'latest trace'. Numbers approximate DevTools (no main-thread attribution or frame-scoped LCP).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        tracePath: {
+          type: "string",
+          description: "Filesystem path to a trace JSON file written by performance_trace or performance_stop_trace (bare array OR {traceEvents:[...]}). Required."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "performance_trace",
+    description: "PRIMARY one-shot trace: start tracing, optionally reload or navigate the page, wait durationMs (default 3000), end the trace, write the trace JSON under /tmp/cdp-toolkit, and return {path,bytes,events,metrics,target}. Holds one connection open for the whole window, so it is immune to the cross-process limitation of start/stop, and it is the recommended entry point.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        durationMs: {
+          type: "number",
+          description: "How long to record after the optional reload/navigate, in milliseconds. Default 3000."
+        },
+        reload: {
+          type: "boolean",
+          description: "Reload the page after starting the trace to capture full navigation timing."
+        },
+        navigateTo: {
+          type: "string",
+          description: "Navigate to this URL after starting the trace (alternative to reload)."
+        },
+        categories: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: "Trace categories to include. Defaults to the timeline + user-timing + loading + disabled-by-default timeline tracks that carry LCP/LayoutShift/RunTask."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "start_screen_recording",
+    description: "Start recording the target tab to video over raw CDP (Page.startScreencast), holding one persistent connection open and spooling every Page.screencastFrame to disk. Chrome emits a frame ON REPAINT, not on a clock, so the stream is variable-rate: each frame is timestamped into a ledger and stop_screen_recording turns those timestamps into per-frame display durations, which is what makes a still page hold one long frame instead of the video racing or freezing. Every frame is acked immediately (an unacked frame stalls the stream). ffmpeg is probed here, not at stop, so a missing encoder fails before a recording is captured and thrown away. Must be paired with stop_screen_recording WITHIN THE SAME PROCESS (the frames are events on this connection and cannot be re-attached from another process, so the pair works under the MCP server, not the one-process-per-call CLI). Throws if a recording is already in progress for the target; recordings on DIFFERENT targets run concurrently. Chrome only: WebDriver BiDi has no screencast primitive, so both tools are absent under --browser firefox.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        format: {
+          type: "string",
+          enum: [
+            "jpeg",
+            "png"
+          ],
+          description: "Frame image format. Defaults to jpeg (far smaller per repaint); png is lossless. quality applies to jpeg only."
+        },
+        quality: {
+          type: "number",
+          description: "JPEG frame quality 0-100. Ignored for png. Omitted by default, which leaves Chrome's own default in place."
+        },
+        maxWidth: {
+          type: "number",
+          description: "Cap the streamed frame width in pixels. Also the way to pin frame size if the viewport might change mid-recording."
+        },
+        maxHeight: {
+          type: "number",
+          description: "Cap the streamed frame height in pixels."
+        },
+        everyNthFrame: {
+          type: "number",
+          description: "Capture only every Nth repaint (1 = every frame). Reduces spool size on a busy page; per-frame durations keep playback at wallclock speed either way."
+        },
+        bringToFront: {
+          type: "boolean",
+          description: "Activate the tab (Page.bringToFront) before recording. Default false. A fully backgrounded or occluded tab may never repaint, and a recording of one captures 0 frames."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "stop_screen_recording",
+    description: "Stop the recording started by start_screen_recording, assemble the spooled frames into an MP4 with ffmpeg using PER-FRAME durations from the ledger (frame N is held until frame N+1 painted; the last frame is held until this call), and return {path,bytes,durationMs,frameCount,encodedFrames,codec,encoder,width,height,droppedFrames,target}. Encoder ladder, probed once at start: hevc_videotoolbox then h264_videotoolbox then libx265 then libx264, with -tag:v hvc1 on HEVC so QuickTime plays it, +faststart, yuv420p, and even dimensions forced. With one recording in flight 'target' may be omitted; with several it is required, because guessing which to stop can lose another agent's recording. Throws if nothing is recording in this process, and throws rather than writing a silent empty video when 0 frames arrived. On an ffmpeg failure the spooled frames are KEPT and the spool path plus the exact command are named in the error. Encoded video tops out at 25 fps: ffmpeg's concat demuxer represents image timestamps on a 1/25s grid, so frames captured less than 40ms apart are coalesced deliberately (frameCount reports what was captured, encodedFrames what reached the video) instead of being dropped silently by ffmpeg. durationMs is the sum of the encoded durations; the file itself runs one 40ms step longer, because the concat demuxer needs the final frame repeated for its hold to count.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Which recording to stop: 'active' (default, valid only when exactly one recording is in flight) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        savePath: {
+          type: "string",
+          description: "Override the output file path. Default: /tmp/cdp-toolkit/screen-recording-<targetIdShort>-<stamp>.mp4."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "take_heapsnapshot",
+    description: "Capture a V8 heap snapshot of the selected page target over raw CDP (HeapProfiler.takeHeapSnapshot, accumulating addHeapSnapshotChunk events) and write it as a .heapsnapshot JSON file loadable by the DevTools Memory panel; returns {path,bytes,chunks,target} only and does not parse/summarize the snapshot. Writes under /tmp/cdp-toolkit (CDP_ARTIFACT_DIR) unless savePath is given.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | 'label:<name>' | '<targetId>'."
+        },
+        savePath: {
+          type: "string",
+          description: "Override the output path. An absolute path (starting with /) is used as-is; a relative path is resolved under the artifact dir (/tmp/cdp-toolkit). Defaults to an auto-named take_heapsnapshot-<targetId>-<timestamp>.heapsnapshot file."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "lighthouse_audit",
+    description: "Run a Lighthouse audit against a URL by shelling out to `npx --yes lighthouse` (the toolkit's sole non-CDP tool); Lighthouse attaches to the already-running Chrome on the remote-debugging port and audits its own about:blank tab rather than any live user tab. Writes a JSON report under /tmp/cdp-toolkit and returns {path, bytes} plus per-category scores (0..1 or null).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        url: {
+          type: "string",
+          description: "The URL to audit. Required, and never points at a user tab implicitly."
+        },
+        categories: {
+          type: "array",
+          items: {
+            type: "string"
+          },
+          description: 'Lighthouse categories to run (passed as --only-categories). Defaults to the full set, e.g. ["performance"] or ["performance","accessibility","seo"].'
+        },
+        savePath: {
+          type: "string",
+          description: "Override the report output path; defaults to a timestamped file under /tmp/cdp-toolkit."
+        },
+        formFactor: {
+          type: "string",
+          enum: [
+            "desktop",
+            "mobile"
+          ],
+          description: 'Form factor: "desktop" (default, uses --preset=desktop to avoid heavy mobile throttling) or "mobile".'
+        },
+        timeoutMs: {
+          type: "number",
+          description: "Overall budget for the lighthouse process in milliseconds. Default 120000."
+        }
+      },
+      required: [
+        "url"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "mock_request",
+    description: "Register a mock rule on a target's persistent fake-backend session (CDP Fetch domain): intercept requests whose URL matches urlPattern and fulfill them with a canned response, fail (abort) them, or continue them, optionally with fault injection (delayMs/failRate). The session survives reloads and navigations and lives until clear_mocks. Call repeatedly to mock several endpoints on the same target. Pass reload:true to apply immediately. Persistent across calls only via the MCP server (not the one-shot CLI).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target selector: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Defaults to the active page."
+        },
+        urlPattern: {
+          type: "string",
+          description: `CDP Fetch urlPattern glob: '*' matches any run of characters, '?' exactly one, '\\' escapes. Only matching request URLs are paused. e.g. "*/api/users*".`
+        },
+        action: {
+          type: "string",
+          enum: [
+            "fulfill",
+            "fail",
+            "continue"
+          ],
+          description: 'What to do with a matched request. Default "fulfill".'
+        },
+        status: {
+          type: "number",
+          description: "fulfill: HTTP status code for the canned response. Default 200."
+        },
+        body: {
+          type: "string",
+          description: "fulfill: response body string (base64-encoded for CDP internally)."
+        },
+        contentType: {
+          type: "string",
+          description: 'fulfill: Content-Type header. Default "application/json".'
+        },
+        headers: {
+          type: "object",
+          description: 'fulfill: extra response headers (name->value); override Content-Type case-insensitively. Add "Access-Control-Allow-Origin" for cross-origin fetches.'
+        },
+        errorReason: {
+          type: "string",
+          description: 'fail: CDP Network.ErrorReason, e.g. "Failed" (default), "BlockedByClient", "ConnectionRefused", "TimedOut".'
+        },
+        method: {
+          type: "string",
+          description: 'Only mock requests with this HTTP method (e.g. "POST"); other methods pass through.'
+        },
+        delayMs: {
+          type: "number",
+          description: "Fault injection: artificial latency in ms before responding."
+        },
+        failRate: {
+          type: "number",
+          description: "Fault injection: probability 0..1 of failing a matched request regardless of action (resilience testing)."
+        },
+        reload: {
+          type: "boolean",
+          description: "Reload the target after arming so the mock immediately catches traffic."
+        }
+      },
+      required: [
+        "urlPattern"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_mocks",
+    description: "List active fake-backend sessions (one per target) with their rules and hit counts. Prunes sessions whose tab has closed. Use to see what is currently being mocked.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Unused filter placeholder; list_mocks returns all active sessions."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clear_mocks",
+    description: "Tear down fake-backend sessions (Fetch.disable + close the connection). Clears the resolved target's session by default, or every active session with all:true.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "Opaque lease token from claim_page. Omit it for a tab this process already holds: under CDP_REQUIRE_LEASE the gate acquires a lease automatically and one acquired that way passes for any later call from the same process. Required when the tab is held by ANOTHER process, and required for a tab claimed explicitly via claim_page or new_page{claim:true}, which always demands its own token. Without CDP_REQUIRE_LEASE an unleased tab needs no token at all."
+        },
+        target: {
+          type: "string",
+          description: "Target selector whose mock session to clear. Defaults to the active page. Ignored when all:true."
+        },
+        all: {
+          type: "boolean",
+          description: "Clear every active mock session instead of just the resolved target's."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "claim_page",
+    description: "Take exclusive ownership of a browser tab and return an opaque lease token. Two modes. FRESH TAB: with no target and no targetId, opens a new tab (optionally at url) and claims it, so 'give me my own tab' is one call. TAKEOVER: with target, claims a tab that is already open — this is how you work in a tab the human already has open when they ask you to, instead of opening your own — resolving any target selector against the live page list and never creating anything. The answer's 'opened' flag says which happened (true only when this call created the tab), and that same creation record is what release_page consults, so a tab you took over is left open when you release it. Any later tool call against a leased tab must carry the matching token in its 'lease' argument or it is refused, naming the holder. The lease is reclaimable once its owning process dies, its ttlMs elapses without use, or its tab is closed. Refused from the CLI: a CLI invocation is one process per call, so its lease would be reclaimable immediately. IS SOMEBODY ELSE IN THIS TAB: the answer also carries 'humanActiveMs', milliseconds since input that this server did not dispatch — i.e. since a person last clicked, typed, or scrolled here. null means NO DATA (the tab carries no activity beacon, which is normal the first time anyone claims a person's tab, or every input on it was this server's own); it never means 'no human'. The field is absent entirely on a backend that cannot answer. On a takeover of a tab a human used within the last 30 seconds the answer additionally carries 'contention', a warning string. THE CLAIM IS NEVER REFUSED FOR THIS: taking over a person's tab is what takeover mode is for, so by the time you read the warning you already hold the lease and the tab is yours to drive. It tells you that driving it now means fighting a live person for the keyboard and mouse, so you can open your own tab instead or ask first. Known limits: input inside a cross-origin iframe is invisible to it, and a second MCP server's clicks read as human to this one.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Take over an already-open tab, e.g. one the human has open, when asked to: pass any target selector — active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Resolved against the live page list only, so it NEVER opens a tab: a selector that matches nothing is an error, not a new blank tab. The tab is left open on release because the toolkit did not create it. Refused if another live process holds it, including a lease the gate acquired for that process automatically under CDP_REQUIRE_LEASE: this takes over unleased (human) tabs and never steals one from a live agent. Mutually exclusive with targetId."
+        },
+        targetId: {
+          type: "string",
+          description: "Claim this already-open page target instead of opening a new tab. Must be an exact target id, not a selector. Kept for back-compat: prefer 'target', which accepts an exact id too plus every other selector form. Mutually exclusive with target."
+        },
+        url: {
+          type: "string",
+          description: "When opening a fresh tab, navigate it here. Ignored when target or targetId is given, since both of those claim a tab that is already open."
+        },
+        label: {
+          type: "string",
+          description: "Agent label recorded on the lease and surfaced in conflict errors and list_leases. Defaults to pid-<pid>."
+        },
+        ttlMs: {
+          type: "number",
+          description: "How long the lease survives without use before it is reclaimable. Defaults to CDP_LEASE_TTL_MS, else 900000 (15 minutes). Every checked call refreshes it, so an active agent never expires."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "release_page",
+    description: "Give a lease back, and close the tab if this toolkit opened it. Takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds, which is how you release a lease the gate acquired for you automatically, since that path never hands you a token). A tab with a creation record from this toolkit is closed; a tab that was already open and merely claimed is released and left alone. Override either way with 'close'. Idempotent: an already-released, reclaimed, or expired lease reports released:false, and a release that did not happen never closes anything, because by then the tab may belong to another agent. Answers {released, closed, targetId}.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease: {
+          type: "string",
+          description: "The opaque token claim_page (or new_page with claim:true) returned. Mutually exclusive with 'target'. Under CDP_REQUIRE_LEASE a lease the gate acquired for you automatically never produced a token in the first place, so give 'target' instead."
+        },
+        target: {
+          type: "string",
+          description: "Target selector for a tab this process holds: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>. Mutually exclusive with 'lease'. Refused if another process holds the tab."
+        },
+        close: {
+          type: "boolean",
+          description: "Force the close decision instead of letting the creation ledger decide. true closes even a tab this toolkit did not open; false keeps an agent-created tab open. Omit for the default, which closes only tabs this toolkit created."
+        }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "list_leases",
+    description: "Enumerate every active lease for diagnosis: backend, target id, agent label, pid, createdAt, lastUsedAt, ttlMs, whether the owning process is still alive, and whether the lease is reclaimable and why. Requires no token. Never returns the lease nonce, so this cannot be used to forge a token. A row for a lease file that could not be read or parsed instead carries `unreadable` (the errno, or \"unparseable\"), with label, pid, and the timestamp fields as zero placeholders and stale always false, since stale is what marks a lease free to take and an unreadable one must never read that way. Under CDP_REQUIRE_LEASE this call reaps abandoned agent tabs exactly as list_pages does (see that tool's description for the grace period between a lease reading reclaimable and its tab actually being closed), reporting them in an additive 'reaped' array and omitting their rows from the listing. A row also carries 'humanActiveMs' — milliseconds since input this server did not dispatch, i.e. since a person last used that tab — WHERE THE TAB CAN ANSWER. The field is ABSENT rather than null when it cannot: no activity beacon on that tab, every input on it accounted for by this server, a row belonging to the other backend, a tab no longer open, or a page that would not evaluate. Absence therefore means 'no answer', never 'nobody is there'. Note that lastUsedAt measures TOOLKIT calls only, so a tab a person has been typing in for ten minutes looks perfectly idle by that field and is exactly the case humanActiveMs exists to expose. Two further fields are computed fresh on every call, never read off disk: 'idleMs' (now minus lastUsedAt) and 'expiresAt' (lastUsedAt plus ttlMs — the same value claim_page already returns under that name). Both are omitted on an 'unreadable' row, whose lastUsedAt and ttlMs are the zeroed placeholders described above.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false
+    }
+  }
+];
+
 // src/cli.ts
 var USAGE = `cdp-toolkit: raw single-target CDP, 29-tool chrome-devtools-mcp parity, plus a Firefox backend over WebDriver BiDi.
 
 Usage:
-  bun run src/cli.ts <tool> [--browser chrome|firefox] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
+  bun run src/cli.ts <tool> [--browser chrome|firefox] [--connect <port|host:port|ws-url>] [--target <sel>] [--json '<obj>'] [--<key> <value> ...]
   bun run src/cli.ts --list [--browser chrome|firefox]
   bun run src/cli.ts --capabilities [--browser chrome|firefox]
+  bun run src/cli.ts --help | -h                 # this message
+  bun run src/cli.ts <tool> --help | -h           # that tool's arguments, sourced from its schema
 
 Examples:
   bun run src/cli.ts list_pages
@@ -6212,10 +8886,24 @@ Examples:
   bun run src/cli.ts take_screenshot --target url:example --fullPage true
   bun run src/cli.ts --browser firefox take_snapshot
   bun run src/cli.ts --capabilities --browser firefox
+  bun run src/cli.ts take_screenshot --help
+  bun run src/cli.ts --connect 9223 take_snapshot     # attach to your own logged-in Firefox (implies --browser firefox)
+
+--help/-h is recognised ANYWHERE in argv, before any tool dispatch: it never touches the
+browser (no CDP connection, no lease, no file written) and is never passed through as a tool
+argument, even when it appears after a tool name.
 
 Backend selection: --browser chrome|firefox, else the CDP_BROWSER env var, else "chrome" (default,
-zero behavior change for existing users). Firefox is LAUNCHED per invocation (it cannot be attached
-to), used for exactly one tool call, then disposed before the process exits.
+zero behavior change for existing users). Firefox runs in one of two modes:
+  - LAUNCH (default): a fresh throwaway-profile Firefox is spawned for this one invocation, used
+    for exactly one tool call, then disposed (session ended, process killed) before the process
+    exits. This is a login wall for anything that needs your real session.
+  - ATTACH (--connect <port|host:port|ws-url>, or the CDP_FIREFOX_ENDPOINT env var): connects to a
+    Firefox YOU already started with --remote-debugging-port, so tools see your real logged-in
+    profile. This process never launches or kills that Firefox; dispose only ends the BiDi session.
+    --connect implies --browser firefox and conflicts with an explicit --browser chrome. Firefox
+    allows only one active BiDi session at a time, so a client that dies without disposing cleanly
+    (e.g. SIGKILL) can leave the slot occupied until Firefox restarts.
 
 Target selector grammar: active | index:N | url:<substr> | title:<substr> | label:<name> | <targetId>
   plus worker:<substr> (Chrome only) for evaluate_script, list_network_requests, get_network_request
@@ -6238,7 +8926,7 @@ function coerce(raw) {
   return raw;
 }
 function parseArgv(argv) {
-  const out = { list: false, capabilities: false, args: {} };
+  const out = { list: false, capabilities: false, help: false, args: {} };
   let jsonObj;
   const flagPairs = [];
   for (let i = 0;i < argv.length; i++) {
@@ -6251,6 +8939,10 @@ function parseArgv(argv) {
       out.capabilities = true;
       continue;
     }
+    if (token === "--help" || token === "-h") {
+      out.help = true;
+      continue;
+    }
     if (token.startsWith("--")) {
       const key = token.slice(2);
       const next = argv[i + 1];
@@ -6285,10 +8977,61 @@ function parseArgv(argv) {
 function isToolName(name) {
   return Object.prototype.hasOwnProperty.call(TOOLS, name);
 }
+function formatType(prop) {
+  if (!prop)
+    return "any";
+  if (Array.isArray(prop.enum) && prop.enum.length > 0)
+    return prop.enum.map(String).join("|");
+  if (Array.isArray(prop.type))
+    return prop.type.join("|");
+  return prop.type ?? "any";
+}
+function printToolHelp(name) {
+  const spec = MANIFEST.find((t) => t.name === name);
+  if (!spec) {
+    process.stdout.write(`${name}
+`);
+    return;
+  }
+  const required = new Set(spec.inputSchema.required ?? []);
+  const props = spec.inputSchema.properties ?? {};
+  const keys = Object.keys(props);
+  const lines = [spec.name, "", spec.description, ""];
+  if (keys.length === 0) {
+    lines.push("Arguments: none.");
+  } else {
+    lines.push("Arguments:");
+    for (const key of keys) {
+      const prop = props[key];
+      const reqTag = required.has(key) ? "required" : "optional";
+      lines.push(`  --${key} <${formatType(prop)}> (${reqTag})`);
+      if (prop?.description)
+        lines.push(`      ${prop.description}`);
+    }
+  }
+  lines.push("", `Usage: cdp ${spec.name} [--target <sel>] [--json '<obj>'] [--<key> <value> ...]`);
+  process.stdout.write(`${lines.join(`
+`)}
+`);
+}
 async function main() {
   const rawArgv = process.argv.slice(2);
-  const browser = resolveBrowserKind(rawArgv);
-  const parsed = parseArgv(stripBrowserFlag(rawArgv));
+  const { kind: browser, endpoint } = resolveBackend(rawArgv);
+  const parsed = parseArgv(stripConnectFlag(stripBrowserFlag(rawArgv)));
+  if (parsed.help) {
+    if (!parsed.tool) {
+      process.stdout.write(`${USAGE}
+`);
+      return 0;
+    }
+    if (!isToolName(parsed.tool)) {
+      process.stderr.write(`${JSON.stringify({ error: `unknown tool '${parsed.tool}'. Run --list to see all ${TOOL_NAMES.length} tools.` })}
+`);
+      return 1;
+    }
+    printToolHelp(parsed.tool);
+    return 0;
+  }
   const availability = toolAvailability(browser);
   const availableSet = new Set(availability.available);
   if (parsed.capabilities) {
@@ -6349,7 +9092,7 @@ async function main() {
 `);
       return 1;
     }
-    const session2 = await startFirefoxSession();
+    const session2 = await startFirefoxSession({ endpoint });
     try {
       const result = await neutralFn(session2.driver, parsed.args);
       process.stdout.write(`${JSON.stringify(result, null, 2)}