cdp-toolkit 1.4.0 → 1.6.0

package/dist/mcp.js

@@ -682,6 +682,8 @@ var REQUIRED_CAPABILITIES = {
   performance_trace: ["trace.performance"],
   take_heapsnapshot: ["heap.snapshot"],
   lighthouse_audit: ["audit.lighthouse"],
+  start_screen_recording: ["capture.screencast"],
+  stop_screen_recording: ["capture.screencast"],
   mock_request: ["network.intercept"],
   list_mocks: ["network.intercept"],
   clear_mocks: ["network.intercept"]
@@ -937,7 +939,8 @@ var CDP_CAPABILITIES = new Set([
   "snapshot.accessibilityTree",
   "input.insertTextAtomic",
   "locate.text",
-  "locate.xpath"
+  "locate.xpath",
+  "capture.screencast"
 ]);
 
 class CdpPageDriver {
@@ -2579,11 +2582,375 @@ async function performanceAnalyzeInsight(args = {}) {
   return { ...analyzeEvents(events), tracePath: args.tracePath };
 }
 
-// src/tools/heap.ts
-import { mkdir as mkdir6, writeFile as writeFile6 } from "node:fs/promises";
+// 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";
 var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
-function stamp3(targetId) {
+var FFMPEG_BIN = process.env.CDP_FFMPEG ?? "ffmpeg";
+function frameDurationsMs(ledger, stopWallclockMs) {
+  return ledger.map((entry, i) => {
+    const next = i + 1 < ledger.length ? ledger[i + 1].timestamp : stopWallclockMs;
+    return Math.max(1, Math.round(next - entry.timestamp));
+  });
+}
+var CONCAT_GRID_MS = 40;
+function coalesceToConcatGrid(ledger, stopWallclockMs, gridMs = CONCAT_GRID_MS) {
+  if (!ledger.length)
+    return [];
+  const raw = frameDurationsMs(ledger, stopWallclockMs);
+  let elapsed = 0;
+  const kept = [];
+  let lastSlot = -1;
+  for (let i = 0;i < ledger.length; i++) {
+    const slot = Math.round(elapsed / gridMs);
+    if (slot > lastSlot) {
+      kept.push({ file: ledger[i].file, slot });
+      lastSlot = slot;
+    }
+    elapsed += raw[i];
+  }
+  const endSlot = Math.max(lastSlot + 1, Math.round(elapsed / gridMs));
+  return kept.map((frame, i) => ({
+    file: frame.file,
+    durationMs: ((i + 1 < kept.length ? kept[i + 1].slot : endSlot) - frame.slot) * gridMs
+  }));
+}
+function buildConcatManifest(frames) {
+  if (!frames.length)
+    throw new CdpError("cannot build a concat manifest from an empty frame ledger");
+  const lines = ["ffconcat version 1.0"];
+  for (const frame of frames) {
+    lines.push(`file ${frame.file}`);
+    lines.push(`duration ${(frame.durationMs / 1000).toFixed(6)}`);
+  }
+  lines.push(`file ${frames[frames.length - 1].file}`);
+  return `${lines.join(`
+`)}
+`;
+}
+function evenDimensions(width, height) {
+  return { width: Math.max(0, Math.trunc(width / 2) * 2), height: Math.max(0, Math.trunc(height / 2) * 2) };
+}
+function pngSize(buf) {
+  if (buf.length < 24)
+    return;
+  if (buf.readUInt32BE(0) !== 2303741511 || buf.readUInt32BE(4) !== 218765834)
+    return;
+  if (buf.toString("latin1", 12, 16) !== "IHDR")
+    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]);
+function jpegSize(buf) {
+  if (buf.length < 4 || buf[0] !== 255 || buf[1] !== 216)
+    return;
+  let i = 2;
+  while (i + 3 < buf.length) {
+    if (buf[i] !== 255) {
+      i += 1;
+      continue;
+    }
+    const marker = buf[i + 1];
+    if (marker === 255) {
+      i += 1;
+      continue;
+    }
+    if (marker === 216 || marker === 1 || marker >= 208 && marker <= 215) {
+      i += 2;
+      continue;
+    }
+    if (i + 3 >= buf.length)
+      return;
+    const segLen = buf.readUInt16BE(i + 2);
+    if (JPEG_SOF.has(marker)) {
+      if (i + 9 > buf.length)
+        return;
+      return { width: buf.readUInt16BE(i + 7), height: buf.readUInt16BE(i + 5) };
+    }
+    if (segLen < 2)
+      return;
+    i += 2 + segLen;
+  }
+  return;
+}
+function imageSize(buf) {
+  return pngSize(buf) ?? jpegSize(buf);
+}
+var ENCODER_LADDER = [
+  { encoder: "hevc_videotoolbox", codec: "hevc", tag: "hvc1" },
+  { encoder: "h264_videotoolbox", codec: "h264" },
+  { encoder: "libx265", codec: "hevc", tag: "hvc1" },
+  { encoder: "libx264", codec: "h264" }
+];
+function ffmpegEncoderNames(encodersOutput) {
+  const names = new Set;
+  for (const line of encodersOutput.split(`
+`)) {
+    const m = /^\s*[VAS][A-Z.]{5}\s+(\S+)/.exec(line);
+    if (m)
+      names.add(m[1]);
+  }
+  return names;
+}
+function selectEncoder(encodersOutput) {
+  const available = ffmpegEncoderNames(encodersOutput);
+  for (const candidate of ENCODER_LADDER) {
+    if (available.has(candidate.encoder))
+      return candidate;
+  }
+  throw new CdpError(`ffmpeg reports none of the supported video encoders (${ENCODER_LADDER.map((c) => c.encoder).join(", ")}). ` + "Install a full ffmpeg build: 'brew install ffmpeg' (macOS) or 'apt install ffmpeg' (Debian/Ubuntu).");
+}
+function buildFfmpegArgs(manifestPath, outPath, choice) {
+  return [
+    "-hide_banner",
+    "-loglevel",
+    "error",
+    "-y",
+    "-f",
+    "concat",
+    "-safe",
+    "0",
+    "-i",
+    manifestPath,
+    "-vsync",
+    "vfr",
+    "-vf",
+    "scale=trunc(iw/2)*2:trunc(ih/2)*2",
+    "-c:v",
+    choice.encoder,
+    ...choice.tag ? ["-tag:v", choice.tag] : [],
+    "-pix_fmt",
+    "yuv420p",
+    "-movflags",
+    "+faststart",
+    "-an",
+    outPath
+  ];
+}
+function run(bin, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(bin, args, { stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+var encoderProbe;
+var FFMPEG_MISSING = `ffmpeg is required to encode a screen recording but '${FFMPEG_BIN}' could not be executed. ` + "Install it with 'brew install ffmpeg' (macOS) or 'apt install ffmpeg' (Debian/Ubuntu), " + "or point CDP_FFMPEG at the binary.";
+async function probeEncoder() {
+  if (!encoderProbe) {
+    encoderProbe = (async () => {
+      let res;
+      try {
+        res = await run(FFMPEG_BIN, ["-hide_banner", "-encoders"]);
+      } catch (err) {
+        throw new CdpError(`${FFMPEG_MISSING} (${err.message})`);
+      }
+      if (res.code !== 0)
+        throw new CdpError(`${FFMPEG_MISSING} ('-encoders' exited ${res.code}: ${res.stderr.trim().slice(0, 300)})`);
+      return selectEncoder(`${res.stdout}
+${res.stderr}`);
+    })();
+    encoderProbe.catch(() => {
+      encoderProbe = undefined;
+    });
+  }
+  return encoderProbe;
+}
+var liveRecordings = new Map;
+function shortId2(id) {
+  return id.slice(0, 8);
+}
+function assertNotRecording(targetId, activeIds) {
+  if (activeIds.includes(targetId)) {
+    throw new CdpError(`a screen recording is already in progress for target ${shortId2(targetId)}; call stop_screen_recording first`);
+  }
+}
+function chooseRecordingId(activeIds, selector) {
+  if (!activeIds.length) {
+    throw new CdpError("no screen recording is in progress in this process. start_screen_recording parks a live CDP connection in memory, so a recording cannot be stopped from a different process than the one that started it (the CLI is one process per call: use the MCP server for the pair).");
+  }
+  if (selector === undefined || selector === "active") {
+    if (activeIds.length === 1)
+      return activeIds[0];
+    throw new CdpError(`${activeIds.length} screen recordings are in progress (targets: ${activeIds.map(shortId2).join(", ")}); pass 'target' to say which one to stop`);
+  }
+  return activeIds.find((id) => id === selector);
+}
+function stamp3() {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+function target32(t) {
+  return { id: t.id, url: t.url, title: t.title };
+}
+async function startScreenRecording(args = {}) {
+  const format = args.format ?? "jpeg";
+  if (format !== "jpeg" && format !== "png")
+    throw new CdpError("start_screen_recording: format must be 'jpeg' or 'png'");
+  if (args.quality !== undefined && (!Number.isFinite(args.quality) || args.quality < 0 || args.quality > 100)) {
+    throw new CdpError("start_screen_recording: quality must be a number between 0 and 100 (jpeg only)");
+  }
+  const encoder = await probeEncoder();
+  const { conn, target } = await openPage(args.target);
+  try {
+    assertNotRecording(target.id, [...liveRecordings.keys()]);
+  } catch (err) {
+    conn.close();
+    throw err;
+  }
+  const spoolDir = join5(ARTIFACT_DIR4, `screencast-${shortId2(target.id)}-${stamp3()}`);
+  try {
+    await mkdir6(spoolDir, { recursive: true });
+  } catch (err) {
+    conn.close();
+    throw new CdpError(`cannot create the screencast spool directory '${spoolDir}': ${err.message}`);
+  }
+  const ext = format === "png" ? "png" : "jpg";
+  const rec = {
+    conn,
+    target,
+    spoolDir,
+    ledger: [],
+    startedAt: Date.now(),
+    format,
+    encoder,
+    writes: Promise.resolve(),
+    dropped: 0,
+    unwritten: new Set,
+    off: () => {}
+  };
+  let seq = 0;
+  rec.off = conn.on("Page.screencastFrame", (params) => {
+    const sessionId = params.sessionId;
+    if (typeof sessionId === "number") {
+      conn.send("Page.screencastFrameAck", { sessionId }).catch(() => {});
+    }
+    const data = params.data;
+    if (typeof data !== "string" || !data.length) {
+      rec.dropped += 1;
+      return;
+    }
+    const meta = params.metadata;
+    const timestamp = typeof meta?.timestamp === "number" ? Math.round(meta.timestamp * 1000) : Date.now();
+    const buf = Buffer.from(data, "base64");
+    const size = imageSize(buf);
+    if (!size || size.width <= 0 || size.height <= 0) {
+      rec.dropped += 1;
+      return;
+    }
+    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.dropped += 1;
+      rec.unwritten.add(file);
+    });
+  });
+  try {
+    await conn.send("Page.enable");
+    if (args.bringToFront)
+      await conn.send("Page.bringToFront").catch(() => {});
+    const params = { format };
+    if (format === "jpeg" && args.quality !== undefined)
+      params.quality = args.quality;
+    if (args.maxWidth !== undefined)
+      params.maxWidth = args.maxWidth;
+    if (args.maxHeight !== undefined)
+      params.maxHeight = args.maxHeight;
+    if (args.everyNthFrame !== undefined)
+      params.everyNthFrame = args.everyNthFrame;
+    await conn.send("Page.startScreencast", params);
+  } catch (err) {
+    rec.off();
+    conn.close();
+    await rm(spoolDir, { recursive: true, force: true }).catch(() => {});
+    throw err;
+  }
+  liveRecordings.set(target.id, rec);
+  return {
+    target: target32(target),
+    format,
+    spoolDir,
+    encoder: encoder.encoder,
+    codec: encoder.codec,
+    startedAt: rec.startedAt,
+    note: "Recording. Call stop_screen_recording in THIS process to encode the MP4; frames only arrive on repaint, so a still page yields one long-held frame."
+  };
+}
+async function pickRecording(selector) {
+  const chosen = chooseRecordingId([...liveRecordings.keys()], selector);
+  if (chosen)
+    return liveRecordings.get(chosen);
+  const { conn, target } = await openPage(selector);
+  conn.close();
+  const hit = liveRecordings.get(target.id);
+  if (!hit) {
+    throw new CdpError(`no screen recording is in progress for target ${shortId2(target.id)} (recording: ${[...liveRecordings.keys()].map(shortId2).join(", ") || "none"})`);
+  }
+  return hit;
+}
+async function stopScreenRecording(args = {}) {
+  const rec = await pickRecording(args.target);
+  rec.off();
+  try {
+    await rec.conn.send("Page.stopScreencast");
+  } catch {}
+  const stoppedAt = Date.now();
+  await rec.writes.catch(() => {});
+  rec.conn.close();
+  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(() => {});
+    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`);
+  const frames = coalesceToConcatGrid(ledger, stoppedAt);
+  const manifestPath = join5(rec.spoolDir, "frames.ffconcat");
+  await writeFile6(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;
+  try {
+    res = await run(FFMPEG_BIN, buildFfmpegArgs(manifestPath, outPath, rec.encoder));
+  } catch (err) {
+    throw new CdpError(`${FFMPEG_MISSING} Spooled frames kept at ${rec.spoolDir}. (${err.message})`);
+  }
+  if (res.code !== 0) {
+    throw new CdpError(`ffmpeg (${rec.encoder.encoder}) exited ${res.code} encoding ${frames.length} frames. Spooled frames kept at ${rec.spoolDir}, re-run by hand with: ` + `${FFMPEG_BIN} ${buildFfmpegArgs(manifestPath, outPath, rec.encoder).join(" ")}
+ffmpeg said: ${res.stderr.trim().slice(0, 800)}`);
+  }
+  const { size } = await stat2(outPath);
+  await rm(rec.spoolDir, { recursive: true, force: true }).catch(() => {});
+  return {
+    path: outPath,
+    bytes: size,
+    durationMs,
+    frameCount: ledger.length,
+    encodedFrames: frames.length,
+    codec: rec.encoder.codec,
+    encoder: rec.encoder.encoder,
+    width,
+    height,
+    droppedFrames: rec.dropped,
+    target: target32(rec.target)
+  };
+}
+
+// src/tools/heap.ts
+import { mkdir as mkdir7, writeFile as writeFile7 } from "node:fs/promises";
+import { join as join6 } from "node:path";
+var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function stamp4(targetId) {
   const short = targetId.slice(0, 8);
   const iso = new Date().toISOString().replace(/[:.]/g, "-");
   return `${short}-${iso}`;
@@ -2606,9 +2973,9 @@ async function takeHeapsnapshot(args = {}) {
     if (snapshot.length === 0) {
       throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
     }
-    await mkdir6(ARTIFACT_DIR4, { recursive: true });
-    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join5(ARTIFACT_DIR4, args.savePath) : join5(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
-    await writeFile6(path, snapshot, "utf8");
+    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");
     const bytes = Buffer.byteLength(snapshot, "utf8");
     return {
       path,
@@ -2620,15 +2987,15 @@ async function takeHeapsnapshot(args = {}) {
 }
 
 // src/tools/lighthouse.ts
-import { spawn } from "node:child_process";
-import { mkdir as mkdir7, readFile as readFile6, stat as stat2 } from "node:fs/promises";
-var ARTIFACT_DIR5 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+import { spawn as spawn2 } from "node:child_process";
+import { mkdir as mkdir8, readFile as readFile6, 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";
   const m = base.match(/:(\d+)/);
   return m?.[1] ? Number(m[1]) : 9222;
 }
-function stamp4() {
+function stamp5() {
   return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
 }
 function shortHost(url) {
@@ -2645,7 +3012,7 @@ function runProcess(cmd, args, opts) {
     let stdout = "";
     let stderr = "";
     let settled = false;
-    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn2(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     const timer = setTimeout(() => {
       if (settled)
         return;
@@ -2682,8 +3049,8 @@ async function lighthouseAudit(args) {
   const url = args.url.trim();
   const timeoutMs = args.timeoutMs ?? 120000;
   const port = cdpPort();
-  await mkdir7(ARTIFACT_DIR5, { recursive: true });
-  const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp4()}.json`;
+  await mkdir8(ARTIFACT_DIR6, { recursive: true });
+  const outPath = args.savePath ?? `${ARTIFACT_DIR6}/lighthouse-${shortHost(url)}-${stamp5()}.json`;
   const formFactor = args.formFactor ?? "desktop";
   const lhArgs = [
     "--yes",
@@ -2738,7 +3105,7 @@ async function lighthouseAudit(args) {
   if (Object.keys(categories).length === 0) {
     throw new CdpError(`lighthouse_audit report contained no category scores (exit code ${res.code}). stderr: ${truncate(res.stderr)}`);
   }
-  const { size } = await stat2(outPath);
+  const { size } = await stat3(outPath);
   return {
     path: outPath,
     bytes: size,
@@ -2792,6 +3159,8 @@ var TOOLS = {
   performance_stop_trace: performanceStopTrace,
   performance_analyze_insight: performanceAnalyzeInsight,
   performance_trace: performanceTrace,
+  start_screen_recording: startScreenRecording,
+  stop_screen_recording: stopScreenRecording,
   take_heapsnapshot: takeHeapsnapshot,
   lighthouse_audit: lighthouseAudit,
   mock_request: mockRequest,
@@ -3905,6 +4274,76 @@ var MANIFEST = [
       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. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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. Required only when the tab this call resolves to is leased by someone; omit it for unleased tabs, which behave exactly as before."
+        },
+        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>' | '<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.",
@@ -4678,8 +5117,8 @@ function hostFromUrl(url, toolName) {
 function driverError2(code, message, data) {
   return Object.assign(new Error(message), { code, ...data !== undefined ? { data } : {} });
 }
-function encodeUid2(stamp5) {
-  return `bidi:${stamp5}`;
+function encodeUid2(stamp6) {
+  return `bidi:${stamp6}`;
 }
 function decodeStamp(uid) {
   if (!uid.startsWith("bidi:"))
@@ -4786,7 +5225,7 @@ function parseSnapshotLine(line) {
   const m = LINE_RE.exec(line);
   if (!m)
     return;
-  const indent = m[1] ?? "", stamp5 = m[2], role = m[3], nameLit = m[4], extrasRaw = m[5];
+  const indent = m[1] ?? "", stamp6 = m[2], role = m[3], nameLit = m[4], extrasRaw = m[5];
   const depth = indent.length / 2;
   let name;
   if (nameLit) {
@@ -4814,7 +5253,7 @@ function parseSnapshotLine(line) {
       extras[key] = val;
     }
   }
-  return { uid: encodeUid2(stamp5), role, depth, ...name !== undefined ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} };
+  return { uid: encodeUid2(stamp6), role, depth, ...name !== undefined ? { name } : {}, ...Object.keys(extras).length ? { extras } : {} };
 }
 var INTERACTIVE_ROLES3 = new Set([
   "button",
@@ -4847,8 +5286,8 @@ function sharedRefOf(node, describe) {
 }
 async function resolveElementLocator2(conn, contextId, loc) {
   if ("uid" in loc) {
-    const stamp5 = decodeStamp(loc.uid);
-    const nodes2 = await locateNodes(conn, contextId, { type: "css", value: `[${UID_STAMP_ATTR}="${cssEscape(stamp5)}"]` });
+    const stamp6 = decodeStamp(loc.uid);
+    const nodes2 = await locateNodes(conn, contextId, { type: "css", value: `[${UID_STAMP_ATTR}="${cssEscape(stamp6)}"]` });
     if (!nodes2.length)
       throw driverError2("stale-uid", `uid does not resolve: ${loc.uid}`);
     return sharedRefOf(nodes2[0], loc.uid);
@@ -5060,14 +5499,14 @@ class BidiPageDriver {
       return loc.uid;
     }
     const ref = await resolveElementLocator2(this.conn, this.contextId, loc);
-    const stamp5 = await this.callFunctionValue(STAMP_ONE_SOURCE, [], ref);
-    if (typeof stamp5 !== "string")
+    const stamp6 = await this.callFunctionValue(STAMP_ONE_SOURCE, [], ref);
+    if (typeof stamp6 !== "string")
       throw driverError2("page-error", "stamping the located element did not return a string");
-    return encodeUid2(stamp5);
+    return encodeUid2(stamp6);
   }
   async resolve(uid) {
-    const stamp5 = decodeStamp(uid);
-    const nodes = await locateNodes(this.conn, this.contextId, { type: "css", value: `[${UID_STAMP_ATTR}="${cssEscape(stamp5)}"]` });
+    const stamp6 = decodeStamp(uid);
+    const nodes = await locateNodes(this.conn, this.contextId, { type: "css", value: `[${UID_STAMP_ATTR}="${cssEscape(stamp6)}"]` });
     if (!nodes.length)
       throw driverError2("stale-uid", `uid does not resolve: ${uid}`);
   }
@@ -5496,11 +5935,11 @@ function createFirefoxDriver(port, opts) {
 }
 
 // src/bidi/launch.ts
-import { spawn as spawn2 } from "node:child_process";
+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 join6 } from "node:path";
+import { join as join7 } from "node:path";
 function resolveBinary() {
   const candidates = [
     process.env.FIREFOX_BIN,
@@ -5574,11 +6013,11 @@ async function launchFirefox(opts = {}) {
   const binary = resolveBinary();
   const port = await pickPort(opts.port);
   const isThrowaway = opts.profilePath === undefined;
-  const profilePath = opts.profilePath ?? mkdtempSync(join6(tmpdir(), "cdp-toolkit-ff-profile-"));
+  const profilePath = opts.profilePath ?? mkdtempSync(join7(tmpdir(), "cdp-toolkit-ff-profile-"));
   const args = ["--profile", profilePath, "--remote-debugging-port", String(port), "--no-remote"];
   if (opts.headless)
     args.push("--headless");
-  const proc = spawn2(binary, args, { stdio: "ignore", detached: false });
+  const proc = spawn3(binary, args, { stdio: "ignore", detached: false });
   let closed = false;
   const close = async () => {
     if (closed)
@@ -5844,7 +6283,7 @@ var FIREFOX_TOOLS = {
 };
 
 // src/mcp.ts
-var VERSION = "1.4.0";
+var VERSION = "1.6.0";
 var BROWSER = resolveBrowserKind(stripBrowserFlag(process.argv.slice(2)));
 var AVAILABILITY = toolAvailability(BROWSER);
 var AVAILABLE_NAMES = new Set(AVAILABILITY.available);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "cdp-toolkit",
-  "version": "1.4.0",
-  "description": "A lightweight chrome-devtools-mcp alternative: a single-target MCP server + CLI that drives one tab over a direct WebSocket with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 39 tools including built-in network mocking and a cookie group. No Puppeteer, no all-target fan-out.",
+  "version": "1.6.0",
+  "description": "A lightweight chrome-devtools-mcp alternative: an MCP server + CLI that drives the tabs you name, one target per call over one direct WebSocket, with a bounded timeout on every call, so a stuck page can't wedge your agent or force a /mcp restart. Chrome over CDP and Firefox over WebDriver BiDi, with tools a backend can't run absent from tools/list rather than throwing mid-task. 41 tools including built-in network mocking, a cookie group, tab leases, and tab-to-video screen recording so several agents can drive one browser without stealing each other's tabs. No Puppeteer, no all-target fan-out.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -75,6 +75,7 @@
     "test": "bun test",
     "smoke": "bun run ./test/smoke.ts",
     "mock:smoke": "bun run ./test/mock-smoke.ts",
+    "screencast:smoke": "bun run ./test/screencast-smoke.ts",
     "mcp:smoke": "bun run ./test/mcp-smoke.ts",
     "firefox:smoke": "bun run ./test/firefox-smoke.ts",
     "lease:smoke": "bun run ./test/lease-smoke.ts"

package/src/bidi/driver.ts

@@ -269,6 +269,10 @@ const BUTTON_CODES: Record<"left" | "right" | "middle", number> = { left: 0, mid
  * supported yet" on real Firefox 153.0.3, contradicting the initial assumption that both text and
  * xpath locators were live; ElementLocator's `text` branch still resolves and correctly surfaces
  * "unsupported" rather than silently misbehaving, it is simply not offered as a capability.
+ * capture.screencast is absent because WebDriver BiDi has no streamed-frame primitive at all:
+ * the spec offers only the one-shot browsingContext.captureScreenshot, with no screencast
+ * start/stop command and no per-repaint frame event to subscribe to, so the screen-recording
+ * pair is honestly missing under Firefox rather than present and throwing.
  * network.intercept rides network.addIntercept + network.beforeRequestSent, verified working
  * (see intercept()'s comment on why urlPatterns is never populated). screenshot.fullPage uses
  * captureScreenshot's origin:"document", screenshot.element uses its clip:{type:"element"}, both verified.

package/src/capabilities.ts

@@ -1,5 +1,5 @@
 /**
- * Per-backend tool availability: filters the 36-tool registry down to what a
+ * Per-backend tool availability: filters the 41-tool registry down to what a
  * given DriverKind can actually run, per ADR-001's rule that tools/list
  * discovers gaps, not runtime "unsupported" throws. Pure and I/O-free: driver
  * construction reads a static readonly `capabilities` set, it does not dial a