cdp-toolkit 1.4.0 → 1.7.0

package/dist/index.js

@@ -11,6 +11,16 @@ function leaseTtlMs() {
   const raw = Number(process.env.CDP_LEASE_TTL_MS);
   return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_LEASE_TTL_MS;
 }
+var longLived = false;
+function markLongLivedProcess(value = true) {
+  longLived = value;
+}
+function requireLease() {
+  if (!longLived)
+    return false;
+  const raw = (process.env.CDP_REQUIRE_LEASE ?? "").trim().toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes" || raw === "on";
+}
 function defaultLabel() {
   return `pid-${process.pid}`;
 }
@@ -97,7 +107,8 @@ async function claimLease(backend, targetId, opts) {
       label: opts.label,
       createdAt: now,
       lastUsedAt: now,
-      ttlMs: opts.ttlMs ?? leaseTtlMs()
+      ttlMs: opts.ttlMs ?? leaseTtlMs(),
+      auto: opts.auto === true
     };
     try {
       await writeFile(leaseFile(backend, targetId), JSON.stringify(record), { flag: "wx" });
@@ -173,8 +184,16 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
   const held = rec && !staleReason(rec, { now, liveIds: ctx.liveIds }) ? rec : undefined;
   const where = describeTarget(targetId, ctx);
   if (token === undefined) {
-    if (!held)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       return;
+    }
+    if (held.auto === true && held.pid === process.pid) {
+      await touchLease(held, now);
+      return;
+    }
     throw new LeaseConflictError(`${where} is leased by '${held.label}' (pid ${held.pid}). Pass that lease's token as the 'lease' argument, or call release_page to free it. list_leases shows every active lease.`, targetId, held.label);
   }
   const parts = tokenParts(token);
@@ -182,8 +201,12 @@ async function assertLeaseOk(backend, targetId, ctx = {}) {
     throw new LeaseConflictError(`malformed lease token for ${where}. Pass back the token claim_page returned, never a constructed one.`, targetId);
   }
   if (parts.backend !== backend || parts.targetId !== targetId) {
-    if (!held)
+    if (!held) {
+      if (requireLease()) {
+        await claimLease(backend, targetId, { label: defaultLabel(), ttlMs: leaseTtlMs(), auto: true, now });
+      }
       return;
+    }
     throw new LeaseConflictError(`the lease token you passed is for ${parts.backend} target '${parts.targetId}', not ${where}, which is leased by '${held.label}'. Resolve the tab you actually hold, or claim this one.`, targetId, held.label);
   }
   if (!held) {
@@ -680,6 +703,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"]
@@ -935,7 +960,8 @@ var CDP_CAPABILITIES = new Set([
   "snapshot.accessibilityTree",
   "input.insertTextAtomic",
   "locate.text",
-  "locate.xpath"
+  "locate.xpath",
+  "capture.screencast"
 ]);
 
 class CdpPageDriver {
@@ -1424,6 +1450,20 @@ async function recordOrigin(backend, targetId, opts = {}) {
     await writeFile2(file, JSON.stringify(record), { flag: "wx" });
   } catch {}
 }
+async function readOrigin(backend, targetId) {
+  let raw;
+  try {
+    raw = await readFile2(originFile(backend, targetId), "utf8");
+  } catch {
+    return;
+  }
+  try {
+    const rec = JSON.parse(raw);
+    if (typeof rec?.targetId === "string" && typeof rec?.label === "string" && typeof rec?.createdAt === "number")
+      return rec;
+  } catch {}
+  return;
+}
 async function listOrigins(opts = {}) {
   let names = [];
   try {
@@ -1481,59 +1521,43 @@ async function newTrackedPage(driver, backend, opts = {}) {
   return page;
 }
 
-// src/leases-tools.ts
-class LeaseToolError extends Error {
-}
-function backendOf(driver) {
-  return driver.scheme === "bidi" ? "firefox" : "chrome";
-}
-async function claimPage(driver, args = {}) {
-  const backend = backendOf(driver);
-  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
-  const pages = await driver.listPages();
-  let targetId = args.targetId;
-  let url = args.url ?? "about:blank";
-  if (targetId === undefined || targetId === "") {
-    const page = await newTrackedPage(driver, backend, { url: args.url, label });
-    targetId = page.id;
-    url = page.url;
-  } else {
-    const existing = pages.find((p) => p.id === targetId);
-    if (!existing)
-      throw new LeaseToolError(`claim_page: no page target with id '${targetId}'`);
-    url = existing.url;
+// src/reap.ts
+function staleAgentTabs(input) {
+  const live = new Set(input.livePageIds);
+  const out = [];
+  for (const row of input.leases) {
+    if (row.backend !== input.backend)
+      continue;
+    if (row.unreadable !== undefined)
+      continue;
+    if (row.stale !== "dead-pid" && row.stale !== "expired")
+      continue;
+    if (!live.has(row.targetId))
+      continue;
+    const origin = input.origins.get(row.targetId);
+    if (origin === undefined || origin.unreadable !== undefined)
+      continue;
+    out.push({ targetId: row.targetId, label: row.label, reason: row.stale });
   }
-  const liveIds = [...pages.map((p) => p.id), targetId];
-  const { record, token } = await claimLease(backend, targetId, {
-    label,
-    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
-    liveIds
-  });
-  return {
-    lease: token,
-    targetId,
-    url,
-    label: record.label,
-    ttlMs: record.ttlMs,
-    expiresAt: record.lastUsedAt + record.ttlMs
-  };
+  return out;
 }
-async function releasePage(_driver, args) {
-  if (typeof args.lease !== "string" || !args.lease.length) {
-    throw new LeaseToolError("release_page requires the 'lease' token returned by claim_page");
+async function reapStaleAgentTabs(driver, backend) {
+  const livePageIds = (await driver.listPages()).map((p) => p.id);
+  const [origins, leases] = await Promise.all([
+    originIndex(backend, undefined),
+    listLeases({ liveIds: livePageIds, liveBackend: backend }).catch(() => [])
+  ]);
+  const candidates = staleAgentTabs({ backend, livePageIds, origins, leases });
+  const closed = [];
+  for (const c of candidates) {
+    const res = await driver.closePage(c.targetId).catch(() => ({ success: false }));
+    if (res.success !== true)
+      continue;
+    await releaseLeaseFor(backend, c.targetId);
+    closed.push(c);
   }
-  return releaseLease(args.lease);
+  return closed;
 }
-async function listLeasesTool(driver, _args = {}) {
-  const liveIds = (await driver.listPages()).map((p) => p.id);
-  const leases = await listLeases({ liveIds, liveBackend: backendOf(driver) });
-  return { leases, count: leases.length };
-}
-var LEASE_TOOLS = {
-  claim_page: claimPage,
-  release_page: releasePage,
-  list_leases: listLeasesTool
-};
 
 // src/shared-tools.ts
 import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
@@ -1546,7 +1570,7 @@ class SharedToolError extends Error {
 function target3(p) {
   return { id: p.id, url: p.url, title: p.title };
 }
-function backendOf2(driver) {
+function backendOf(driver) {
   return driver.scheme === "bidi" ? "firefox" : "chrome";
 }
 async function withPage2(driver, target, fn) {
@@ -1560,7 +1584,7 @@ async function withPage2(driver, target, fn) {
 async function resolvePage(driver, selector) {
   const pages = await driver.listPages();
   const hit = await pickPage(driver, pages, selector);
-  await assertLeaseOk(backendOf2(driver), hit.id, { url: hit.url, title: hit.title });
+  await assertLeaseOk(backendOf(driver), hit.id, { url: hit.url, title: hit.title });
   return hit;
 }
 async function pickPage(driver, pages, selector) {
@@ -1615,8 +1639,10 @@ async function reapSet(driver, pages, all) {
   }
 }
 async function listPages(driver, args = {}) {
-  const pages = await driver.listPages({ all: args.all });
-  const ledger = await originIndex(backendOf2(driver), await reapSet(driver, pages, args.all));
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backendOf(driver)) : [];
+  const reapedIds = new Set(reaped.map((r) => r.targetId));
+  const pages = (await driver.listPages({ all: args.all })).filter((p) => !reapedIds.has(p.id));
+  const ledger = await originIndex(backendOf(driver), await reapSet(driver, pages, args.all));
   const annotated = pages.map((p) => {
     const rec = ledger.get(p.id);
     if (!rec)
@@ -1625,16 +1651,18 @@ async function listPages(driver, args = {}) {
       return { ...p, origin: "unknown", originUnreadable: rec.unreadable };
     return { ...p, origin: "agent", label: rec.label, createdAt: rec.createdAt };
   });
-  return { pages: annotated, count: annotated.length };
+  return { pages: annotated, count: annotated.length, ...reaped.length ? { reaped } : {} };
 }
 async function newPage(driver, args = {}) {
   const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
-  const p = await newTrackedPage(driver, backendOf2(driver), { url: args.url, label });
-  if (args.claim !== true)
+  const p = await newTrackedPage(driver, backendOf(driver), { url: args.url, label });
+  const explicit = args.claim === true;
+  if (!explicit && !requireLease())
     return { targetId: p.id, url: p.url };
-  const { record, token } = await claimLease(backendOf2(driver), p.id, {
+  const { record, token } = await claimLease(backendOf(driver), p.id, {
     label,
-    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs()
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    auto: !explicit
   });
   return { targetId: p.id, url: p.url, lease: token, label: record.label, expiresAt: record.lastUsedAt + record.ttlMs };
 }
@@ -1645,7 +1673,7 @@ async function closePage(driver, args) {
   const res = await driver.closePage(p.id);
   if (!res.success)
     return { closed: p.id, success: false, leaseReleased: false };
-  const released = await releaseLeaseFor(backendOf2(driver), p.id);
+  const released = await releaseLeaseFor(backendOf(driver), p.id);
   return { closed: p.id, success: true, ...released.released ? { leaseReleased: true } : {} };
 }
 async function writeSelectedFile(id) {
@@ -1970,6 +1998,103 @@ var SHARED_TOOLS = {
   handle_dialog: handleDialog
 };
 
+// src/leases-tools.ts
+class LeaseToolError extends Error {
+}
+function backendOf2(driver) {
+  return driver.scheme === "bidi" ? "firefox" : "chrome";
+}
+async function claimPage(driver, args = {}) {
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  const hasTargetId = typeof args.targetId === "string" && args.targetId.length > 0;
+  if (hasTarget && hasTargetId) {
+    throw new LeaseToolError("claim_page takes at most one of 'target' (any selector: active | index:N | url:<substr> | title:<substr> | <targetId>) or 'targetId' (an exact target id, kept for back-compat). Pass 'target' alone to claim an open tab, or neither to open a fresh one.");
+  }
+  const backend = backendOf2(driver);
+  const label = typeof args.label === "string" && args.label.length ? args.label : defaultLabel();
+  const pages = await driver.listPages();
+  let targetId;
+  let url;
+  let opened;
+  if (hasTarget) {
+    const hit = await pickPage(driver, pages, args.target).catch((err) => {
+      throw new LeaseToolError(`claim_page: no open tab matches target '${args.target}' (${err.message}). No tab was opened: claim_page never creates one when 'target' is given.`);
+    });
+    targetId = hit.id;
+    url = hit.url;
+    opened = false;
+  } else if (hasTargetId) {
+    const existing = pages.find((p) => p.id === args.targetId);
+    if (!existing)
+      throw new LeaseToolError(`claim_page: no page target with id '${args.targetId}'`);
+    targetId = existing.id;
+    url = existing.url;
+    opened = false;
+  } else {
+    const page = await newTrackedPage(driver, backend, { url: args.url, label });
+    targetId = page.id;
+    url = page.url;
+    opened = true;
+  }
+  const liveIds = [...pages.map((p) => p.id), targetId];
+  const { record, token } = await claimLease(backend, targetId, {
+    label,
+    ttlMs: typeof args.ttlMs === "number" && args.ttlMs > 0 ? args.ttlMs : leaseTtlMs(),
+    liveIds
+  });
+  return {
+    lease: token,
+    targetId,
+    url,
+    label: record.label,
+    ttlMs: record.ttlMs,
+    expiresAt: record.lastUsedAt + record.ttlMs,
+    opened
+  };
+}
+async function releasePage(driver, args = {}) {
+  const hasLease = typeof args.lease === "string" && args.lease.length > 0;
+  const hasTarget = typeof args.target === "string" && args.target.length > 0;
+  if (hasLease === hasTarget) {
+    throw new LeaseToolError("release_page takes exactly one of 'lease' (the token claim_page returned) or 'target' (a selector for a tab this process holds)");
+  }
+  const backend = backendOf2(driver);
+  let targetId;
+  let released;
+  if (hasLease) {
+    const parts = tokenParts(args.lease);
+    if (!parts)
+      return { released: false, closed: false };
+    targetId = parts.targetId;
+    released = (await releaseLease(args.lease)).released;
+  } else {
+    const page = await resolvePage(driver, args.target);
+    targetId = page.id;
+    released = (await releaseLeaseFor(backend, targetId)).released;
+  }
+  if (!released)
+    return { released: false, closed: false, ...hasTarget ? { targetId } : {} };
+  const shouldClose = args.close === false ? false : args.close === true ? true : await readOrigin(backend, targetId) !== undefined;
+  if (!shouldClose)
+    return { released: true, closed: false, targetId };
+  const res = await driver.closePage(targetId).catch(() => ({ success: false }));
+  return { released: true, closed: res.success === true, targetId };
+}
+async function listLeasesTool(driver, _args = {}) {
+  const backend = backendOf2(driver);
+  const reaped = requireLease() ? await reapStaleAgentTabs(driver, backend) : [];
+  const reapedIds = new Set(reaped.map((r) => r.targetId));
+  const liveIds = (await driver.listPages()).map((p) => p.id);
+  const all = await listLeases({ liveIds, liveBackend: backend });
+  const leases = all.filter((l) => !(l.backend === backend && reapedIds.has(l.targetId)));
+  return { leases, count: leases.length, ...reaped.length ? { reaped } : {} };
+}
+var LEASE_TOOLS = {
+  claim_page: claimPage,
+  release_page: releasePage,
+  list_leases: listLeasesTool
+};
+
 // src/tools/console.ts
 import { readFile as readFile3 } from "node:fs/promises";
 
@@ -2577,11 +2702,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}`;
@@ -2604,9 +3093,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,
@@ -2618,15 +3107,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) {
@@ -2643,7 +3132,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;
@@ -2680,8 +3169,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",
@@ -2736,7 +3225,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,
@@ -2790,6 +3279,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,