cdp-toolkit 1.0.0

package/dist/mcp.js

@@ -0,0 +1,3056 @@
+#!/usr/bin/env node
+
+// src/tools/pages.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+
+// src/client.ts
+var BASE = process.env.CDP_BASE ?? "http://127.0.0.1:9222";
+var DEFAULT_TIMEOUT_MS = Number(process.env.CDP_TIMEOUT_MS ?? 15000);
+
+class CdpError extends Error {
+  code;
+  data;
+  constructor(message, code, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "CdpError";
+  }
+}
+
+class CdpConnection {
+  wsUrl;
+  opts;
+  ws;
+  nextId = 0;
+  pending = new Map;
+  listeners = new Map;
+  closed = false;
+  constructor(wsUrl, opts = {}) {
+    this.wsUrl = wsUrl;
+    this.opts = opts;
+  }
+  connect() {
+    return new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl);
+      this.ws = ws;
+      const openTimer = setTimeout(() => reject(new CdpError(`connect timeout: ${this.wsUrl}`)), this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      ws.onopen = () => {
+        clearTimeout(openTimer);
+        resolve(this);
+      };
+      ws.onerror = (e) => {
+        clearTimeout(openTimer);
+        const msg = e?.message ?? "websocket error";
+        if (this.pending.size === 0)
+          reject(new CdpError(msg));
+        this.rejectAll(new CdpError(msg));
+      };
+      ws.onclose = () => {
+        this.closed = true;
+        this.rejectAll(new CdpError("connection closed"));
+      };
+      ws.onmessage = (ev) => this.onMessage(String(ev.data));
+    });
+  }
+  onMessage(raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof msg.id === "number" && this.pending.has(msg.id)) {
+      const p = this.pending.get(msg.id);
+      clearTimeout(p.timer);
+      this.pending.delete(msg.id);
+      p.resolve(msg);
+      return;
+    }
+    if (msg.method) {
+      const set = this.listeners.get(msg.method);
+      if (set)
+        for (const h of set)
+          h(msg.params ?? {}, msg.sessionId);
+      const star = this.listeners.get("*");
+      if (star)
+        for (const h of star)
+          h({ method: msg.method, ...msg.params ?? {} }, msg.sessionId);
+    }
+  }
+  rejectAll(err) {
+    for (const [, p] of this.pending) {
+      clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pending.clear();
+  }
+  send(method, params = {}, opts = {}) {
+    if (this.closed || !this.ws)
+      return Promise.reject(new CdpError("connection not open"));
+    const id = ++this.nextId;
+    const timeoutMs = opts.timeoutMs ?? this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const payload = { id, method, params };
+    if (opts.sessionId)
+      payload.sessionId = opts.sessionId;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new CdpError(`'${method}' timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (r) => {
+          if (r.error)
+            reject(new CdpError(`${method}: ${r.error.message}`, r.error.code, r.error.data));
+          else
+            resolve(r.result ?? {});
+        },
+        reject,
+        timer
+      });
+      this.ws.send(JSON.stringify(payload));
+    });
+  }
+  on(method, handler) {
+    let set = this.listeners.get(method);
+    if (!set) {
+      set = new Set;
+      this.listeners.set(method, set);
+    }
+    set.add(handler);
+    return () => set.delete(handler);
+  }
+  waitFor(method, predicate, timeoutMs = this.opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        off();
+        reject(new CdpError(`waitFor('${method}') timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      const off = this.on(method, (params) => {
+        if (!predicate || predicate(params)) {
+          clearTimeout(timer);
+          off();
+          resolve(params);
+        }
+      });
+    });
+  }
+  close() {
+    this.closed = true;
+    this.rejectAll(new CdpError("closed by caller"));
+    try {
+      this.ws?.close();
+    } catch {}
+  }
+}
+async function httpJson(path) {
+  const res = await fetch(`${BASE}${path}`);
+  if (!res.ok)
+    throw new CdpError(`${path} -> HTTP ${res.status}`);
+  return await res.json();
+}
+function listTargets() {
+  return httpJson("/json/list");
+}
+async function browserWsUrl() {
+  const v = await httpJson("/json/version");
+  return v.webSocketDebuggerUrl;
+}
+async function resolveTarget(selector) {
+  const targets = await listTargets();
+  const pages = targets.filter((t) => t.type === "page");
+  if (!selector || selector === "active") {
+    if (!pages.length)
+      throw new CdpError("no page targets open");
+    return pages[0];
+  }
+  if (selector.startsWith("index:")) {
+    const i = Number(selector.slice(6));
+    if (!pages[i])
+      throw new CdpError(`no page target at index ${i} (have ${pages.length})`);
+    return pages[i];
+  }
+  if (selector.startsWith("url:")) {
+    const needle = selector.slice(4);
+    const hit = pages.find((t) => t.url.includes(needle));
+    if (!hit)
+      throw new CdpError(`no page url containing '${needle}'`);
+    return hit;
+  }
+  if (selector.startsWith("title:")) {
+    const needle = selector.slice(6);
+    const hit = pages.find((t) => t.title.includes(needle));
+    if (!hit)
+      throw new CdpError(`no page title containing '${needle}'`);
+    return hit;
+  }
+  const byId = targets.find((t) => t.id === selector);
+  if (!byId)
+    throw new CdpError(`no target with id '${selector}'`);
+  return byId;
+}
+async function openBrowser(opts = {}) {
+  return new CdpConnection(await browserWsUrl(), opts).connect();
+}
+async function openPage(selector, opts = {}) {
+  const target = await resolveTarget(selector);
+  const conn = await new CdpConnection(target.webSocketDebuggerUrl, opts).connect();
+  return { conn, target };
+}
+async function withPage(selector, fn, opts = {}) {
+  const { conn, target } = await openPage(selector, opts);
+  try {
+    return await fn(conn, target);
+  } finally {
+    conn.close();
+  }
+}
+
+// src/tools/pages.ts
+var STATE_DIR = process.env.CDP_STATE_DIR ?? "/tmp/cdp-toolkit";
+var SELECTED_FILE = `${STATE_DIR}/selected`;
+function toPageInfo(t) {
+  return { id: t.id, url: t.url, title: t.title, type: t.type };
+}
+async function listPages(args = {}) {
+  const targets = await listTargets();
+  const filtered = args.all ? targets : targets.filter((t) => t.type === "page");
+  const pages = filtered.map(toPageInfo);
+  return { pages, count: pages.length };
+}
+async function newPage(args = {}) {
+  const url = args.url ?? "about:blank";
+  const conn = await openBrowser();
+  try {
+    const { targetId } = await conn.send("Target.createTarget", { url });
+    if (!targetId)
+      throw new CdpError("Target.createTarget returned no targetId");
+    return { targetId, url };
+  } finally {
+    conn.close();
+  }
+}
+async function closePage(args) {
+  if (args.target === undefined || args.target === "") {
+    throw new CdpError("close_page requires an explicit target; refusing to guess which page to close");
+  }
+  const target = await resolveTarget(args.target);
+  const conn = await openBrowser();
+  try {
+    const res = await conn.send("Target.closeTarget", { targetId: target.id });
+    return { closed: target.id, success: res.success ?? true };
+  } finally {
+    conn.close();
+  }
+}
+async function selectPage(args) {
+  if (args.target === undefined || args.target === "") {
+    throw new CdpError("select_page requires an explicit target");
+  }
+  const target = await resolveTarget(args.target);
+  const conn = await openBrowser();
+  try {
+    await conn.send("Target.activateTarget", { targetId: target.id });
+  } finally {
+    conn.close();
+  }
+  await mkdir(dirname(SELECTED_FILE), { recursive: true });
+  await writeFile(SELECTED_FILE, target.id, "utf8");
+  return { selected: target.id };
+}
+
+// src/tools/navigation.ts
+async function navigatePage(args) {
+  const reload = args.reload === true;
+  if (!reload && (!args.url || typeof args.url !== "string")) {
+    throw new CdpError("navigate_page: 'url' is required (or pass reload:true to reload the current page)");
+  }
+  const waitUntil = args.waitUntil ?? "load";
+  return withPage(args.target, async (conn) => {
+    await conn.send("Page.enable");
+    const milestoneMethod = waitUntil === "load" ? "Page.loadEventFired" : "Page.domContentEventFired";
+    const milestone = conn.waitFor(milestoneMethod, undefined, args.timeoutMs).then(() => waitUntil).catch(() => {
+      return;
+    });
+    const stopped = conn.waitFor("Page.frameStoppedLoading", undefined, args.timeoutMs).then(() => "frameStoppedLoading").catch(() => {
+      return;
+    });
+    let resolvedUrl;
+    let frameId;
+    if (reload) {
+      await conn.send("Page.reload", { ignoreCache: args.ignoreCache === true }, args.timeoutMs ? { timeoutMs: args.timeoutMs } : {});
+      const tree = await conn.send("Page.getFrameTree").catch(() => {
+        return;
+      });
+      frameId = tree?.frameTree?.frame?.id ?? "";
+      resolvedUrl = tree?.frameTree?.frame?.url ?? args.url ?? "";
+    } else {
+      const nav = await conn.send("Page.navigate", { url: args.url }, args.timeoutMs ? { timeoutMs: args.timeoutMs } : {});
+      if (nav.errorText) {
+        throw new CdpError(`navigate_page: ${nav.errorText} (${args.url})`);
+      }
+      frameId = nav.frameId;
+      resolvedUrl = args.url;
+    }
+    const settled = await Promise.race([milestone, stopped]);
+    const waitedFor = settled ?? "navigate-only";
+    return reload ? { url: resolvedUrl, frameId, reloaded: true, waitedFor } : { url: resolvedUrl, frameId, waitedFor };
+  }, args.timeoutMs ? { timeoutMs: args.timeoutMs } : {});
+}
+var DEFAULT_WAIT_TIMEOUT_MS = 15000;
+var DEFAULT_POLL_MS = 250;
+async function waitForText(args) {
+  if (typeof args.text !== "string" || args.text.length === 0) {
+    throw new CdpError("wait_for: 'text' is required");
+  }
+  const timeoutMs = args.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+  const pollMs = args.pollMs ?? DEFAULT_POLL_MS;
+  const start = Date.now();
+  return withPage(args.target, async (conn, _target) => {
+    await conn.send("Runtime.enable");
+    const expr = `(() => { const b = document.body; return !!b && typeof b.innerText === 'string' && b.innerText.includes(${JSON.stringify(args.text)}); })()`;
+    for (;; ) {
+      const { result } = await conn.send("Runtime.evaluate", {
+        expression: expr,
+        returnByValue: true
+      });
+      if (result?.value === true) {
+        return { found: true, waitedMs: Date.now() - start };
+      }
+      if (Date.now() - start >= timeoutMs) {
+        throw new CdpError(`wait_for: text not found within ${timeoutMs}ms: ${JSON.stringify(args.text)}`);
+      }
+      await delay(Math.min(pollMs, Math.max(0, timeoutMs - (Date.now() - start))));
+    }
+  }, { timeoutMs: Math.max(timeoutMs, DEFAULT_WAIT_TIMEOUT_MS) });
+}
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/tools/evaluate.ts
+function exceptionMessage(details) {
+  const ex = details.exception;
+  const fromObject = ex?.description ?? (typeof ex?.value === "string" ? ex.value : ex?.value !== undefined ? JSON.stringify(ex.value) : undefined);
+  return fromObject ?? details.text ?? "evaluation threw";
+}
+function unwrap(obj) {
+  if (Object.prototype.hasOwnProperty.call(obj, "value"))
+    return obj.value;
+  if (obj.unserializableValue !== undefined)
+    return obj.unserializableValue;
+  if (obj.type === "undefined")
+    return;
+  return obj.description ?? null;
+}
+async function evaluateExpression(conn, expression, awaitPromise) {
+  const res = await conn.send("Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+    awaitPromise,
+    replMode: false,
+    silent: false
+  });
+  if (res.exceptionDetails)
+    throw new CdpError(exceptionMessage(res.exceptionDetails));
+  return unwrap(res.result);
+}
+async function evaluateFunction(conn, expression, awaitPromise, args) {
+  const globalObj = await conn.send("Runtime.evaluate", {
+    expression: "globalThis",
+    returnByValue: false
+  });
+  const objectId = globalObj.result.objectId;
+  if (!objectId)
+    throw new CdpError("could not resolve global object for function call");
+  const res = await conn.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: expression,
+    arguments: args.map((value) => ({ value })),
+    returnByValue: true,
+    awaitPromise,
+    silent: false
+  });
+  if (res.exceptionDetails)
+    throw new CdpError(exceptionMessage(res.exceptionDetails));
+  return unwrap(res.result);
+}
+async function evaluateScript(args) {
+  const { expression } = args;
+  if (typeof expression !== "string" || expression.length === 0) {
+    throw new CdpError("evaluateScript: 'expression' must be a non-empty string");
+  }
+  const awaitPromise = args.awaitPromise ?? true;
+  const callArgs = args.args;
+  return withPage(args.target, async (conn) => {
+    await conn.send("Runtime.enable");
+    if (callArgs && callArgs.length > 0) {
+      return evaluateFunction(conn, expression, awaitPromise, callArgs);
+    }
+    return evaluateExpression(conn, expression, awaitPromise);
+  });
+}
+
+// src/tools/snapshot.ts
+var INTERACTIVE_ROLES = new Set([
+  "button",
+  "link",
+  "textbox",
+  "searchbox",
+  "checkbox",
+  "radio",
+  "combobox",
+  "listbox",
+  "option",
+  "menuitem",
+  "menuitemcheckbox",
+  "menuitemradio",
+  "tab",
+  "switch",
+  "slider",
+  "spinbutton",
+  "textfield",
+  "MenuItem",
+  "Button"
+]);
+function axString(v) {
+  if (!v)
+    return;
+  const raw = v.value;
+  if (raw === undefined || raw === null)
+    return;
+  const s = String(raw).trim();
+  return s.length ? s : undefined;
+}
+function propValue(node, name) {
+  const p = node.properties?.find((x) => x.name === name);
+  return axString(p?.value);
+}
+function isInteractive(role) {
+  if (!role)
+    return false;
+  return INTERACTIVE_ROLES.has(role) || INTERACTIVE_ROLES.has(role.toLowerCase());
+}
+function formatNode(node, interactiveOnly) {
+  const role = axString(node.role);
+  const name = axString(node.name);
+  const uid = node.backendDOMNodeId;
+  if (uid === undefined)
+    return;
+  if (interactiveOnly && !isInteractive(role))
+    return;
+  if (!interactiveOnly && !role && !name)
+    return;
+  const extras = [];
+  const value = axString(node.value);
+  if (value)
+    extras.push(`value=${JSON.stringify(value)}`);
+  const checked = propValue(node, "checked");
+  if (checked && checked !== "false")
+    extras.push(`checked=${checked}`);
+  const expanded = propValue(node, "expanded");
+  if (expanded)
+    extras.push(`expanded=${expanded}`);
+  const disabled = propValue(node, "disabled");
+  if (disabled === "true")
+    extras.push("disabled");
+  const url = propValue(node, "url");
+  if (url)
+    extras.push(`url=${url}`);
+  const focused = propValue(node, "focused");
+  if (focused === "true")
+    extras.push("focused");
+  const label = name ? ` ${JSON.stringify(name)}` : "";
+  const extra = extras.length ? ` [${extras.join(" ")}]` : "";
+  return `[${uid}] ${role ?? "generic"}${label}${extra}`;
+}
+async function takeSnapshot(args = {}) {
+  const interactiveOnly = args.interactiveOnly ?? false;
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("Accessibility.enable");
+    const { nodes } = await conn.send("Accessibility.getFullAXTree");
+    const byId = new Map;
+    for (const n of nodes)
+      byId.set(n.nodeId, n);
+    const roots = nodes.filter((n) => !n.parentId || !byId.has(n.parentId));
+    const lines = [];
+    let nodeCount = 0;
+    const walk = (node, depth) => {
+      const line = node.ignored ? undefined : formatNode(node, interactiveOnly);
+      if (line !== undefined) {
+        const indent = interactiveOnly ? "" : "  ".repeat(depth);
+        lines.push(`${indent}${line}`);
+        nodeCount++;
+      }
+      const childDepth = line !== undefined && !interactiveOnly ? depth + 1 : depth;
+      for (const childId of node.childIds ?? []) {
+        const child = byId.get(childId);
+        if (child)
+          walk(child, childDepth);
+      }
+    };
+    for (const root of roots)
+      walk(root, 0);
+    return {
+      snapshot: lines.join(`
+`),
+      target: { id: target.id, url: target.url, title: target.title },
+      nodeCount
+    };
+  });
+}
+async function resolveUid(conn, uid) {
+  const { object } = await conn.send("DOM.resolveNode", {
+    backendNodeId: uid
+  });
+  if (!object?.objectId) {
+    throw new Error(`resolveUid: DOM.resolveNode returned no objectId for uid ${uid}`);
+  }
+  return { objectId: object.objectId };
+}
+
+// src/tools/input.ts
+async function resolveElement(conn, t) {
+  const hasUid = t.uid !== undefined && t.uid !== null;
+  const hasSelector = typeof t.selector === "string" && t.selector.length > 0;
+  if (hasUid === hasSelector) {
+    throw new CdpError("provide exactly one of { uid } or { selector }");
+  }
+  if (hasUid) {
+    return resolveUid(conn, t.uid);
+  }
+  const { result, exceptionDetails } = await conn.send("Runtime.evaluate", {
+    expression: `document.querySelector(${JSON.stringify(t.selector)})`,
+    returnByValue: false
+  });
+  if (exceptionDetails) {
+    throw new CdpError(`selector '${t.selector}' evaluation failed: ${exceptionDetails.text ?? "error"}`);
+  }
+  if (!result.objectId || result.subtype === "null") {
+    throw new CdpError(`selector '${t.selector}' matched no element`);
+  }
+  return { objectId: result.objectId };
+}
+async function centerOf(conn, objectId) {
+  const { result, exceptionDetails } = await conn.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: "function(){this.scrollIntoView({block:'center',inline:'center'});const r=this.getBoundingClientRect();if(r.width===0&&r.height===0)return null;return {x:r.left+r.width/2,y:r.top+r.height/2};}",
+    returnByValue: true
+  });
+  if (exceptionDetails) {
+    throw new CdpError(`could not measure element: ${exceptionDetails.text ?? "error"}`);
+  }
+  if (!result.value) {
+    throw new CdpError("element has zero size / is not visible; cannot compute a click point");
+  }
+  return result.value;
+}
+async function focusElement(conn, objectId) {
+  await conn.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: "function(){this.focus&&this.focus();}",
+    returnByValue: true
+  });
+}
+async function click(args) {
+  const button = args.button ?? "left";
+  const clickCount = args.clickCount ?? 1;
+  return withPage(args.target, async (conn) => {
+    const { objectId } = await resolveElement(conn, args);
+    const { x, y } = await centerOf(conn, objectId);
+    await conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    await conn.send("Input.dispatchMouseEvent", { type: "mousePressed", x, y, button, clickCount });
+    await conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", x, y, button, clickCount });
+    return { clicked: true, x, y };
+  });
+}
+async function hover(args) {
+  return withPage(args.target, async (conn) => {
+    const { objectId } = await resolveElement(conn, args);
+    const { x, y } = await centerOf(conn, objectId);
+    await conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y });
+    return { hovered: true, x, y };
+  });
+}
+async function drag(args) {
+  if (!args.from || !args.to)
+    throw new CdpError("drag requires { from } and { to }");
+  return withPage(args.target, async (conn) => {
+    const { objectId: srcId } = await resolveElement(conn, args.from);
+    const from = await centerOf(conn, srcId);
+    const { objectId: dstId } = await resolveElement(conn, args.to);
+    const to = await centerOf(conn, dstId);
+    await conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: from.x, y: from.y });
+    await conn.send("Input.dispatchMouseEvent", {
+      type: "mousePressed",
+      x: from.x,
+      y: from.y,
+      button: "left",
+      clickCount: 1
+    });
+    await conn.send("Input.dispatchMouseEvent", {
+      type: "mouseMoved",
+      x: (from.x + to.x) / 2,
+      y: (from.y + to.y) / 2,
+      button: "left"
+    });
+    await conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x: to.x, y: to.y, button: "left" });
+    await conn.send("Input.dispatchMouseEvent", {
+      type: "mouseReleased",
+      x: to.x,
+      y: to.y,
+      button: "left",
+      clickCount: 1
+    });
+    return { dragged: true, from, to };
+  });
+}
+async function setValue(conn, objectId, value) {
+  await focusElement(conn, objectId);
+  await conn.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: "function(){if('value'in this){this.value='';this.dispatchEvent(new Event('input',{bubbles:true}));}else if(this.isContentEditable){this.textContent='';}}",
+    returnByValue: true
+  });
+  if (value.length) {
+    await conn.send("Input.insertText", { text: value });
+  }
+}
+async function fill(args) {
+  if (typeof args.value !== "string")
+    throw new CdpError("fill requires a string { value }");
+  return withPage(args.target, async (conn) => {
+    const { objectId } = await resolveElement(conn, args);
+    await setValue(conn, objectId, args.value);
+    return { filled: true, value: args.value };
+  });
+}
+async function typeText(args) {
+  if (typeof args.text !== "string")
+    throw new CdpError("type_text requires a string { text }");
+  return withPage(args.target, async (conn) => {
+    const { objectId } = await resolveElement(conn, args);
+    await focusElement(conn, objectId);
+    if (args.text.length)
+      await conn.send("Input.insertText", { text: args.text });
+    return { typed: true, text: args.text };
+  });
+}
+async function fillForm(args) {
+  if (!Array.isArray(args.fields) || args.fields.length === 0) {
+    throw new CdpError("fill_form requires a non-empty { fields } array");
+  }
+  return withPage(args.target, async (conn) => {
+    let filled = 0;
+    for (const field of args.fields) {
+      if (typeof field.value !== "string") {
+        throw new CdpError("each fill_form field requires a string value");
+      }
+      const { objectId } = await resolveElement(conn, field);
+      await setValue(conn, objectId, field.value);
+      filled++;
+    }
+    return { filled, fields: args.fields.length };
+  });
+}
+var NAMED_KEYS = {
+  enter: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
+  return: { key: "Enter", code: "Enter", keyCode: 13, text: "\r" },
+  tab: { key: "Tab", code: "Tab", keyCode: 9 },
+  escape: { key: "Escape", code: "Escape", keyCode: 27 },
+  esc: { key: "Escape", code: "Escape", keyCode: 27 },
+  backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
+  delete: { key: "Delete", code: "Delete", keyCode: 46 },
+  space: { key: " ", code: "Space", keyCode: 32, text: " " },
+  arrowup: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
+  arrowdown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
+  arrowleft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
+  arrowright: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 },
+  up: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
+  down: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
+  left: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
+  right: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 },
+  home: { key: "Home", code: "Home", keyCode: 36 },
+  end: { key: "End", code: "End", keyCode: 35 },
+  pageup: { key: "PageUp", code: "PageUp", keyCode: 33 },
+  pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 }
+};
+var MODIFIER_BITS = {
+  alt: 1,
+  control: 2,
+  ctrl: 2,
+  meta: 4,
+  cmd: 4,
+  command: 4,
+  shift: 8
+};
+function resolveKey(key) {
+  const named = NAMED_KEYS[key.toLowerCase()];
+  if (named)
+    return named;
+  if (key.length === 1) {
+    const upper = key.toUpperCase();
+    const isLetter = upper >= "A" && upper <= "Z";
+    const isDigit = key >= "0" && key <= "9";
+    const code = isLetter ? `Key${upper}` : isDigit ? `Digit${key}` : `Key${upper}`;
+    const keyCode = upper.charCodeAt(0);
+    return { key, code, keyCode, text: key };
+  }
+  throw new CdpError(`unknown key '${key}' (use a named key like Enter/Tab/ArrowDown or a single character)`);
+}
+async function pressKey(args) {
+  if (typeof args.key !== "string" || !args.key.length) {
+    throw new CdpError("press_key requires a non-empty { key }");
+  }
+  const spec = resolveKey(args.key);
+  let modBits = 0;
+  const mods = args.modifiers ?? [];
+  for (const m of mods) {
+    const bit = MODIFIER_BITS[m.toLowerCase()];
+    if (bit === undefined)
+      throw new CdpError(`unknown modifier '${m}'`);
+    modBits |= bit;
+  }
+  const suppressText = (modBits & ~MODIFIER_BITS.shift) !== 0;
+  return withPage(args.target, async (conn) => {
+    const down = {
+      type: "keyDown",
+      key: spec.key,
+      code: spec.code,
+      windowsVirtualKeyCode: spec.keyCode,
+      nativeVirtualKeyCode: spec.keyCode,
+      modifiers: modBits
+    };
+    if (spec.text && !suppressText) {
+      down.text = spec.text;
+    }
+    await conn.send("Input.dispatchKeyEvent", down);
+    await conn.send("Input.dispatchKeyEvent", {
+      type: "keyUp",
+      key: spec.key,
+      code: spec.code,
+      windowsVirtualKeyCode: spec.keyCode,
+      nativeVirtualKeyCode: spec.keyCode,
+      modifiers: modBits
+    });
+    return { pressed: spec.key, modifiers: mods };
+  });
+}
+async function uploadFile(args) {
+  const files = Array.isArray(args.files) ? args.files : [args.files];
+  if (!files.length || files.some((f) => typeof f !== "string" || !f.length)) {
+    throw new CdpError("upload_file requires { files } as a non-empty path or array of paths");
+  }
+  return withPage(args.target, async (conn) => {
+    const { objectId } = await resolveElement(conn, args);
+    await conn.send("DOM.setFileInputFiles", { files, objectId });
+    return { uploaded: files };
+  });
+}
+
+// src/tools/screenshot.ts
+import { writeFile as writeFile2, mkdir as mkdir2 } from "node:fs/promises";
+import { join } from "node:path";
+var ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function shortId(id) {
+  return id.slice(0, 8);
+}
+function stamp() {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+async function fullPageClip(conn) {
+  const m = await conn.send("Page.getLayoutMetrics");
+  const size = m.cssContentSize ?? m.contentSize;
+  if (!size)
+    throw new CdpError("Page.getLayoutMetrics returned no content size");
+  return { x: 0, y: 0, width: Math.ceil(size.width), height: Math.ceil(size.height), scale: 1 };
+}
+async function elementClip(conn, uid, selector) {
+  let backendNodeId;
+  if (uid != null) {
+    backendNodeId = uid;
+  } else if (selector) {
+    const { root } = await conn.send("DOM.getDocument", { depth: 0 });
+    const { nodeId } = await conn.send("DOM.querySelector", {
+      nodeId: root.nodeId,
+      selector
+    });
+    if (!nodeId)
+      throw new CdpError(`selector matched no element: ${selector}`);
+    const desc = await conn.send("DOM.describeNode", { nodeId });
+    backendNodeId = desc.node.backendNodeId;
+  } else {
+    throw new CdpError("elementClip requires uid or selector");
+  }
+  try {
+    await conn.send("DOM.scrollIntoViewIfNeeded", { backendNodeId });
+  } catch {}
+  const box = await conn.send("DOM.getBoxModel", { backendNodeId });
+  const q = box.model.content;
+  const q0 = q[0];
+  const q1 = q[1];
+  if (q0 == null || q1 == null)
+    throw new CdpError("DOM.getBoxModel returned an empty content quad");
+  const xs = [q[0], q[2], q[4], q[6]].filter((n) => n != null);
+  const ys = [q[1], q[3], q[5], q[7]].filter((n) => n != null);
+  const minX = Math.min(...xs);
+  const minY = Math.min(...ys);
+  const maxX = Math.max(...xs);
+  const maxY = Math.max(...ys);
+  const width = Math.ceil(maxX - minX);
+  const height = Math.ceil(maxY - minY);
+  if (width <= 0 || height <= 0)
+    throw new CdpError("resolved element has zero area");
+  return { x: minX, y: minY, width, height, scale: 1 };
+}
+async function takeScreenshot(args = {}) {
+  const { target, fullPage, uid, selector, savePath, returnBase64 } = args;
+  if (uid != null && selector)
+    throw new CdpError("provide exactly one of uid or selector, not both");
+  const format = args.format ?? "png";
+  const quality = format === "jpeg" ? args.quality ?? 80 : undefined;
+  return withPage(target, async (conn, t) => {
+    await conn.send("Page.enable");
+    const params = { format, captureBeyondViewport: true };
+    if (quality != null)
+      params.quality = quality;
+    if (uid != null || selector) {
+      params.clip = await elementClip(conn, uid, selector);
+    } else if (fullPage) {
+      params.clip = await fullPageClip(conn);
+    }
+    const { data } = await conn.send("Page.captureScreenshot", params);
+    const buf = Buffer.from(data, "base64");
+    if (buf.byteLength === 0)
+      throw new CdpError("Page.captureScreenshot returned empty data");
+    await mkdir2(ARTIFACT_DIR, { recursive: true });
+    const ext = format === "jpeg" ? "jpg" : "png";
+    const path = savePath ?? join(ARTIFACT_DIR, `screenshot-${shortId(t.id)}-${stamp()}.${ext}`);
+    await writeFile2(path, buf);
+    const result = {
+      path,
+      bytes: buf.byteLength,
+      format,
+      target: { id: t.id, url: t.url, title: t.title }
+    };
+    if (returnBase64)
+      result.base64 = data;
+    return result;
+  });
+}
+
+// src/tools/emulation.ts
+async function clearAll(conn) {
+  await conn.send("Emulation.clearDeviceMetricsOverride").catch(() => {
+    return;
+  });
+  await conn.send("Emulation.setUserAgentOverride", { userAgent: "" }).catch(() => {
+    return;
+  });
+  await conn.send("Emulation.setCPUThrottlingRate", { rate: 1 }).catch(() => {
+    return;
+  });
+  await conn.send("Emulation.setEmulatedMedia", { media: "", features: [] }).catch(() => {
+    return;
+  });
+  await conn.send("Network.enable").catch(() => {
+    return;
+  });
+  await conn.send("Network.emulateNetworkConditions", {
+    offline: false,
+    latency: 0,
+    downloadThroughput: -1,
+    uploadThroughput: -1
+  }).catch(() => {
+    return;
+  });
+}
+async function emulate(args = {}) {
+  const { target } = args;
+  return withPage(target, async (conn, t) => {
+    if (args.clearOverrides) {
+      await clearAll(conn);
+      return {
+        target: { id: t.id, url: t.url, title: t.title },
+        applied: [],
+        cleared: true
+      };
+    }
+    const applied = [];
+    if (args.width != null || args.height != null) {
+      if (args.width == null || args.height == null) {
+        throw new CdpError("emulate device metrics require both width and height");
+      }
+      await conn.send("Emulation.setDeviceMetricsOverride", {
+        width: args.width,
+        height: args.height,
+        deviceScaleFactor: args.deviceScaleFactor ?? 0,
+        mobile: args.mobile ?? false
+      });
+      applied.push("deviceMetrics");
+    }
+    if (args.userAgent != null) {
+      await conn.send("Emulation.setUserAgentOverride", { userAgent: args.userAgent });
+      applied.push("userAgent");
+    }
+    if (args.cpuThrottlingRate != null) {
+      if (args.cpuThrottlingRate < 1)
+        throw new CdpError("cpuThrottlingRate must be >= 1");
+      await conn.send("Emulation.setCPUThrottlingRate", { rate: args.cpuThrottlingRate });
+      applied.push("cpuThrottlingRate");
+    }
+    if (args.media != null || args.mediaFeatures != null) {
+      await conn.send("Emulation.setEmulatedMedia", {
+        media: args.media ?? "",
+        features: args.mediaFeatures ?? []
+      });
+      applied.push("emulatedMedia");
+    }
+    if (args.networkConditions != null) {
+      const n = args.networkConditions;
+      await conn.send("Network.enable").catch(() => {
+        return;
+      });
+      await conn.send("Network.emulateNetworkConditions", {
+        offline: n.offline ?? false,
+        latency: n.latency ?? 0,
+        downloadThroughput: n.downloadThroughput ?? -1,
+        uploadThroughput: n.uploadThroughput ?? -1,
+        ...n.connectionType ? { connectionType: n.connectionType } : {}
+      });
+      applied.push("networkConditions");
+    }
+    if (applied.length === 0) {
+      throw new CdpError("emulate: no overrides specified (pass clearOverrides:true to reset)");
+    }
+    return { target: { id: t.id, url: t.url, title: t.title }, applied };
+  });
+}
+async function resizePage(args) {
+  const { target, width, height } = args;
+  if (!Number.isFinite(width) || !Number.isFinite(height) || width <= 0 || height <= 0) {
+    throw new CdpError("resize_page requires positive numeric width and height");
+  }
+  return withPage(target, async (conn, t) => {
+    await conn.send("Emulation.setDeviceMetricsOverride", {
+      width,
+      height,
+      deviceScaleFactor: args.deviceScaleFactor ?? 0,
+      mobile: args.mobile ?? false
+    });
+    await conn.send("Runtime.enable").catch(() => {
+      return;
+    });
+    const { result } = await conn.send("Runtime.evaluate", {
+      expression: "({ w: window.innerWidth, h: window.innerHeight })",
+      returnByValue: true
+    });
+    const v = result.value;
+    return {
+      target: { id: t.id, url: t.url, title: t.title },
+      width,
+      height,
+      innerWidth: v?.w ?? width,
+      innerHeight: v?.h ?? height
+    };
+  });
+}
+
+// src/tools/dialogs.ts
+function armDialogHandler(conn, accept, promptText, onHandled) {
+  return conn.on("Page.javascriptDialogOpening", (params) => {
+    const ev = params;
+    (async () => {
+      try {
+        await conn.send("Page.handleJavaScriptDialog", {
+          accept,
+          ...promptText !== undefined ? { promptText } : {}
+        });
+        onHandled({
+          type: ev.type,
+          message: ev.message,
+          url: ev.url,
+          ...ev.defaultPrompt !== undefined ? { defaultPrompt: ev.defaultPrompt } : {},
+          accept,
+          ...promptText !== undefined ? { promptText } : {},
+          handled: true
+        });
+      } catch {}
+    })();
+  });
+}
+async function handleDialog(args) {
+  const { target, accept, promptText, timeoutMs = 15000, autoMs } = args;
+  const { conn } = await openPage(target);
+  try {
+    await conn.send("Page.enable");
+    if (autoMs !== undefined) {
+      const handled = [];
+      const disarm = armDialogHandler(conn, accept, promptText, (d) => handled.push(d));
+      await new Promise((resolve) => setTimeout(resolve, autoMs));
+      disarm();
+      return { handled, count: handled.length };
+    }
+    return await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        disarm();
+        reject(new CdpError(`handle_dialog: no dialog opened within ${timeoutMs}ms`));
+      }, timeoutMs);
+      const disarm = armDialogHandler(conn, accept, promptText, (d) => {
+        clearTimeout(timer);
+        disarm();
+        resolve(d);
+      });
+    });
+  } finally {
+    conn.close();
+  }
+}
+
+// src/tools/console.ts
+import { readFile } from "node:fs/promises";
+
+// src/tools/recorder.ts
+import { mkdir as mkdir3, appendFile, writeFile as writeFile3, 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`;
+}
+function captureFile(targetId, captureId) {
+  return `${ARTIFACT_DIR2}/rec-${targetId}-${captureId}.jsonl`;
+}
+function delay2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+var NETWORK_EVENTS = [
+  "Network.requestWillBeSent",
+  "Network.responseReceived",
+  "Network.loadingFinished",
+  "Network.loadingFailed"
+];
+var CONSOLE_EVENTS = ["Runtime.consoleAPICalled", "Runtime.exceptionThrown", "Log.entryAdded"];
+async function startRecorder(target, opts = {}) {
+  const network = opts.network ?? true;
+  const consoleCap = opts.console ?? true;
+  await mkdir3(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 writeFile3(file, "");
+  }
+  let chain = Promise.resolve();
+  let dropped = 0;
+  const persist = (kind, method, params) => {
+    const line = { kind, method, ts: Date.now(), params };
+    const text = `${JSON.stringify(line)}
+`;
+    chain = chain.then(() => appendFile(file, text)).catch(() => {
+      dropped += 1;
+    });
+  };
+  const unsubs = [];
+  try {
+    if (network) {
+      await conn.send("Network.enable");
+      for (const ev of NETWORK_EVENTS) {
+        unsubs.push(conn.on(ev, (params) => persist("network", ev, params)));
+      }
+    }
+    if (consoleCap) {
+      await conn.send("Runtime.enable");
+      try {
+        await conn.send("Log.enable");
+      } catch {}
+      for (const ev of CONSOLE_EVENTS) {
+        unsubs.push(conn.on(ev, (params) => persist("console", ev, params)));
+      }
+    }
+  } catch (err) {
+    conn.close();
+    throw err;
+  }
+  const flush = async () => {
+    for (const off of unsubs)
+      off();
+    await chain;
+  };
+  return {
+    file,
+    target: resolved,
+    conn,
+    droppedWrites: () => dropped,
+    flush,
+    async stop() {
+      await flush();
+      conn.close();
+    }
+  };
+}
+async function captureWindow(target, durationMs, opts = {}) {
+  const resolved = await resolveTarget(target);
+  const captureId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  const file = captureFile(resolved.id, captureId);
+  const rec = await startRecorder(resolved.id, {
+    network: true,
+    console: true,
+    truncate: true,
+    file,
+    timeoutMs: opts.timeoutMs
+  });
+  await rec.conn.send("Page.enable");
+  await rec.conn.send("Page.reload", { ignoreCache: false });
+  await delay2(durationMs);
+  return {
+    file: rec.file,
+    conn: rec.conn,
+    resolved: { id: rec.target.id, url: rec.target.url, title: rec.target.title },
+    droppedWrites: rec.droppedWrites,
+    flush: () => rec.flush(),
+    async stop() {
+      await rec.stop();
+      try {
+        await copyFile(rec.file, recFile(rec.target.id));
+      } catch {}
+    }
+  };
+}
+
+// src/tools/console.ts
+var DEFAULT_CAPTURE_MS = 2500;
+function remoteObjectToText(arg) {
+  if (!arg)
+    return "";
+  if (arg.value !== undefined && arg.value !== null)
+    return String(arg.value);
+  if (typeof arg.description === "string")
+    return arg.description;
+  if (typeof arg.unserializableValue === "string")
+    return arg.unserializableValue;
+  if (arg.type === "undefined")
+    return "undefined";
+  if (arg.type === "object" && arg.subtype === "null")
+    return "null";
+  if (typeof arg.type === "string")
+    return `[${arg.type}]`;
+  return "";
+}
+function lineToEntry(line, index) {
+  const p = line.params;
+  if (line.method === "Runtime.consoleAPICalled") {
+    const args = Array.isArray(p.args) ? p.args : [];
+    return {
+      index,
+      source: "console",
+      level: typeof p.type === "string" ? p.type : "log",
+      text: args.map(remoteObjectToText).join(" "),
+      url: undefined,
+      ts: line.ts
+    };
+  }
+  if (line.method === "Runtime.exceptionThrown") {
+    const detail = p.exceptionDetails ?? {};
+    const exception = detail.exception ?? {};
+    const text = remoteObjectToText(exception) || (typeof detail.text === "string" ? detail.text : "uncaught exception");
+    return {
+      index,
+      source: "exception",
+      level: "error",
+      text,
+      url: typeof detail.url === "string" ? detail.url : undefined,
+      lineNumber: typeof detail.lineNumber === "number" ? detail.lineNumber : undefined,
+      ts: line.ts
+    };
+  }
+  if (line.method === "Log.entryAdded") {
+    const entry = p.entry ?? {};
+    return {
+      index,
+      source: "log",
+      level: typeof entry.level === "string" ? entry.level : "info",
+      text: typeof entry.text === "string" ? entry.text : "",
+      url: typeof entry.url === "string" ? entry.url : undefined,
+      lineNumber: typeof entry.lineNumber === "number" ? entry.lineNumber : undefined,
+      ts: line.ts
+    };
+  }
+  return null;
+}
+async function readConsoleEntries(file) {
+  let raw;
+  try {
+    raw = await readFile(file, "utf8");
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const rawLine of raw.split(`
+`)) {
+    const trimmed = rawLine.trim();
+    if (!trimmed)
+      continue;
+    let line;
+    try {
+      line = JSON.parse(trimmed);
+    } catch {
+      continue;
+    }
+    if (line.kind !== "console")
+      continue;
+    const entry = lineToEntry(line, out.length);
+    if (entry)
+      out.push(entry);
+  }
+  return out;
+}
+async function listConsoleMessages(args = {}) {
+  if (args.reload) {
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS);
+    await cap.stop();
+    const messages2 = await readConsoleEntries(cap.file);
+    return {
+      target: cap.resolved,
+      count: messages2.length,
+      messages: messages2,
+      droppedWrites: cap.droppedWrites()
+    };
+  }
+  const target = await resolveTarget(args.target);
+  const messages = await readConsoleEntries(recFile(target.id));
+  return {
+    target: { id: target.id, url: target.url, title: target.title },
+    count: messages.length,
+    messages
+  };
+}
+async function getConsoleMessage(args = {}) {
+  const target = await resolveTarget(args.target);
+  const messages = await readConsoleEntries(recFile(target.id));
+  const index = args.index ?? 0;
+  const entry = messages[index];
+  if (!entry) {
+    throw new CdpError(`no console message at index ${index} (have ${messages.length}); run list_console_messages or list with reload:true first`);
+  }
+  return entry;
+}
+
+// src/tools/network.ts
+import { readFile as readFile2 } from "node:fs/promises";
+var DEFAULT_CAPTURE_MS2 = 2500;
+function asHeaders(v) {
+  if (!v || typeof v !== "object")
+    return;
+  const out = {};
+  for (const [k, val] of Object.entries(v))
+    out[k] = String(val);
+  return out;
+}
+function correlate(lines) {
+  const byId = new Map;
+  const order = [];
+  for (const line of lines) {
+    if (line.kind !== "network")
+      continue;
+    const p = line.params;
+    const requestId = typeof p.requestId === "string" ? p.requestId : undefined;
+    if (!requestId)
+      continue;
+    if (line.method === "Network.requestWillBeSent") {
+      const req = p.request ?? {};
+      if (!byId.has(requestId))
+        order.push(requestId);
+      const existing = byId.get(requestId);
+      const row = existing ?? {
+        requestId,
+        url: typeof req.url === "string" ? req.url : "",
+        method: typeof req.method === "string" ? req.method : "GET",
+        resourceType: typeof p.type === "string" ? p.type : undefined,
+        requestHeaders: asHeaders(req.headers),
+        state: "pending",
+        ts: line.ts
+      };
+      byId.set(requestId, row);
+    } else if (line.method === "Network.responseReceived") {
+      const resp = p.response ?? {};
+      const row = byId.get(requestId);
+      if (row) {
+        row.status = typeof resp.status === "number" ? resp.status : row.status;
+        row.statusText = typeof resp.statusText === "string" ? resp.statusText : row.statusText;
+        row.mimeType = typeof resp.mimeType === "string" ? resp.mimeType : row.mimeType;
+        row.responseHeaders = asHeaders(resp.headers) ?? row.responseHeaders;
+        if (typeof p.type === "string")
+          row.resourceType = p.type;
+      }
+    } else if (line.method === "Network.loadingFinished") {
+      const row = byId.get(requestId);
+      if (row) {
+        row.state = "finished";
+        if (typeof p.encodedDataLength === "number")
+          row.encodedDataLength = p.encodedDataLength;
+      }
+    } else if (line.method === "Network.loadingFailed") {
+      const row = byId.get(requestId);
+      if (row) {
+        row.state = "failed";
+        if (typeof p.errorText === "string")
+          row.errorText = p.errorText;
+      }
+    }
+  }
+  return order.map((id) => byId.get(id)).filter(Boolean);
+}
+async function readNetworkRequests(file) {
+  let raw;
+  try {
+    raw = await readFile2(file, "utf8");
+  } catch {
+    return [];
+  }
+  const lines = [];
+  for (const rawLine of raw.split(`
+`)) {
+    const trimmed = rawLine.trim();
+    if (!trimmed)
+      continue;
+    try {
+      lines.push(JSON.parse(trimmed));
+    } catch {}
+  }
+  return correlate(lines);
+}
+async function listNetworkRequests(args = {}) {
+  let file;
+  let resolved;
+  let droppedWrites;
+  if (args.reload) {
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    await cap.stop();
+    file = cap.file;
+    resolved = cap.resolved;
+    droppedWrites = cap.droppedWrites();
+  } else {
+    const target = await resolveTarget(args.target);
+    file = recFile(target.id);
+    resolved = { id: target.id, url: target.url, title: target.title };
+  }
+  let requests = await readNetworkRequests(file);
+  if (args.filterUrl) {
+    const needle = args.filterUrl;
+    requests = requests.filter((r) => r.url.includes(needle));
+  }
+  return { target: resolved, count: requests.length, requests, droppedWrites };
+}
+async function getNetworkRequest(args = {}) {
+  if (!args.requestId && !args.url) {
+    throw new CdpError("get_network_request requires either requestId or url");
+  }
+  const pick = (requests) => {
+    if (args.requestId)
+      return requests.find((r) => r.requestId === args.requestId);
+    return requests.find((r) => r.url.includes(args.url));
+  };
+  const describeSelector = () => args.requestId ? `requestId ${args.requestId}` : `url ~ '${args.url}'`;
+  if (args.includeBody && args.url) {
+    const cap = await captureWindow(args.target, args.durationMs ?? DEFAULT_CAPTURE_MS2);
+    try {
+      await cap.flush();
+      const match2 = (await readNetworkRequests(cap.file)).find((r) => r.url.includes(args.url));
+      if (!match2) {
+        throw new CdpError(`no network request matched ${describeSelector()} in fresh capture`);
+      }
+      try {
+        const { body, base64Encoded } = await cap.conn.send("Network.getResponseBody", { requestId: match2.requestId });
+        return { ...match2, body, bodyBase64Encoded: base64Encoded };
+      } catch {
+        return { ...match2, body: undefined, bodyBase64Encoded: undefined };
+      }
+    } finally {
+      await cap.stop();
+    }
+  }
+  const target = await resolveTarget(args.target);
+  const match = pick(await readNetworkRequests(recFile(target.id)));
+  if (!match) {
+    throw new CdpError(`no network request matched ${describeSelector()}; run list_network_requests with reload:true first` + (args.includeBody ? `, then fetch the body with the url selector (reload re-mints requestIds)` : ``));
+  }
+  if (args.includeBody && args.requestId) {
+    return {
+      ...match,
+      body: undefined,
+      bodyUnavailableReason: "response bodies are only fetchable via a fresh reload capture, which re-mints requestIds; re-request with the `url` selector to retrieve the body"
+    };
+  }
+  return match;
+}
+
+// src/tools/performance.ts
+import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4, stat, unlink } from "node:fs/promises";
+import { join as join2 } 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 = [
+  "devtools.timeline",
+  "blink.user_timing",
+  "loading",
+  "disabled-by-default-devtools.timeline",
+  "disabled-by-default-devtools.timeline.frame"
+];
+var liveTraces = new Map;
+function stamp2() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function shortId2(id) {
+  return id.slice(0, 8);
+}
+function stateFilePath() {
+  return join2(STATE_DIR2, "trace-state.json");
+}
+function bufferTraceData(conn, sink) {
+  return conn.on("Tracing.dataCollected", (params) => {
+    const value = params.value;
+    if (Array.isArray(value))
+      sink.push(...value);
+  });
+}
+async function beginTrace(conn, categories) {
+  await conn.send("Tracing.start", {
+    traceConfig: { includedCategories: categories },
+    transferMode: "ReportEvents"
+  });
+}
+async function endTrace(conn, sink, timeoutMs = 30000) {
+  const complete = conn.waitFor("Tracing.tracingComplete", undefined, timeoutMs);
+  await conn.send("Tracing.end");
+  await complete;
+  return sink;
+}
+async function writeTrace(events, targetId) {
+  await mkdir4(ARTIFACT_DIR3, { recursive: true });
+  const path = join2(ARTIFACT_DIR3, `trace-${shortId2(targetId)}-${stamp2()}.json`);
+  const body = JSON.stringify({ traceEvents: events, metadata: { source: "cdp-toolkit" } });
+  await writeFile4(path, body, "utf8");
+  const { size } = await stat(path);
+  return { path, bytes: size };
+}
+async function performanceStartTrace(args = {}) {
+  const categories = args.categories?.length ? args.categories : DEFAULT_CATEGORIES;
+  const { conn, target } = await openPage(args.target);
+  if (liveTraces.has(target.id)) {
+    conn.close();
+    throw new CdpError(`a trace is already in progress for target ${shortId2(target.id)}; call performanceStopTrace first`);
+  }
+  const events = [];
+  bufferTraceData(conn, events);
+  try {
+    await beginTrace(conn, categories);
+  } catch (err) {
+    conn.close();
+    throw err;
+  }
+  liveTraces.set(target.id, { conn, target, events, startedAt: Date.now() });
+  await mkdir4(STATE_DIR2, { recursive: true });
+  const state = {
+    targetId: target.id,
+    url: target.url,
+    startedAt: Date.now(),
+    pid: process.pid,
+    categories
+  };
+  await writeFile4(stateFilePath(), JSON.stringify(state), "utf8");
+  return {
+    target: { id: target.id, url: target.url, title: target.title },
+    categories,
+    note: "Trace recording. Call performanceStopTrace in THIS process to finalize. Cross-process? use performanceTrace instead."
+  };
+}
+async function performanceStopTrace(args = {}) {
+  args.target;
+  const entry = liveTraces.size === 1 ? [...liveTraces.values()][0] : undefined;
+  if (!entry) {
+    let hint = "";
+    try {
+      const raw = await readFile3(stateFilePath(), "utf8");
+      const state = JSON.parse(raw);
+      hint = state.pid === process.pid ? ` (state file lists target ${shortId2(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 {}
+    throw new CdpError(`no in-process trace to stop${hint}. Use performanceTrace for a robust single-call trace.`);
+  }
+  const { conn, target, events } = entry;
+  try {
+    await endTrace(conn, events);
+  } finally {
+    conn.close();
+    liveTraces.delete(target.id);
+    await unlink(stateFilePath()).catch(() => {});
+  }
+  const written = await writeTrace(events, target.id);
+  const metrics = analyzeEvents(events);
+  return { ...written, events: events.length, metrics };
+}
+async function performanceTrace(args = {}) {
+  const durationMs = args.durationMs ?? 3000;
+  const categories = args.categories?.length ? args.categories : DEFAULT_CATEGORIES;
+  const { conn, target } = await openPage(args.target);
+  const events = [];
+  bufferTraceData(conn, events);
+  try {
+    await conn.send("Page.enable");
+    await beginTrace(conn, categories);
+    if (args.navigateTo) {
+      const loaded = conn.waitFor("Page.loadEventFired", undefined, durationMs + 5000);
+      await conn.send("Page.navigate", { url: args.navigateTo });
+      await loaded.catch(() => {});
+    } else if (args.reload) {
+      const loaded = conn.waitFor("Page.loadEventFired", undefined, durationMs + 5000);
+      await conn.send("Page.reload", { ignoreCache: false });
+      await loaded.catch(() => {});
+    }
+    await new Promise((r) => setTimeout(r, durationMs));
+    await endTrace(conn, events);
+  } finally {
+    conn.close();
+  }
+  const written = await writeTrace(events, target.id);
+  const metrics = analyzeEvents(events);
+  return { ...written, events: events.length, metrics, target: { id: target.id, url: target.url } };
+}
+function analyzeEvents(events) {
+  let navigationStartUs;
+  let fcpUs;
+  let lcpUs;
+  let dclUs;
+  let loadUs;
+  let cls = 0;
+  let layoutShifts = 0;
+  let longTasks = 0;
+  let longTasksTotalMs = 0;
+  let totalBlockingTimeMs = 0;
+  for (const e of events) {
+    const name = e.name;
+    if (!name)
+      continue;
+    if (name === "navigationStart") {
+      if (typeof e.ts === "number" && (navigationStartUs === undefined || e.ts < navigationStartUs)) {
+        navigationStartUs = e.ts;
+      }
+      continue;
+    }
+    if ((name === "firstContentfulPaint" || name === "FirstContentfulPaint") && typeof e.ts === "number") {
+      if (fcpUs === undefined || e.ts < fcpUs)
+        fcpUs = e.ts;
+      continue;
+    }
+    if (name === "largestContentfulPaint::Candidate" && typeof e.ts === "number") {
+      if (lcpUs === undefined || e.ts > lcpUs)
+        lcpUs = e.ts;
+      continue;
+    }
+    if ((name === "domContentLoadedEventEnd" || name === "DOMContentLoaded") && typeof e.ts === "number") {
+      if (dclUs === undefined || e.ts > dclUs)
+        dclUs = e.ts;
+      continue;
+    }
+    if ((name === "loadEventEnd" || name === "MarkLoad") && typeof e.ts === "number") {
+      if (loadUs === undefined || e.ts > loadUs)
+        loadUs = e.ts;
+      continue;
+    }
+    if (name === "LayoutShift") {
+      const data = e.args?.data;
+      const hadRecentInput = data?.had_recent_input === true;
+      const score = typeof data?.score === "number" ? data.score : undefined;
+      if (!hadRecentInput && typeof score === "number") {
+        cls += score;
+        layoutShifts += 1;
+      }
+      continue;
+    }
+    if (name === "RunTask" && typeof e.dur === "number") {
+      const durMs = e.dur / 1000;
+      if (durMs > 50) {
+        longTasks += 1;
+        longTasksTotalMs += durMs;
+        totalBlockingTimeMs += durMs - 50;
+      }
+      continue;
+    }
+  }
+  const relMs = (us) => us !== undefined && navigationStartUs !== undefined ? (us - navigationStartUs) / 1000 : undefined;
+  const metrics = {
+    navigationStartUs,
+    fcpMs: relMs(fcpUs),
+    lcpMs: relMs(lcpUs),
+    domContentLoadedMs: relMs(dclUs),
+    loadMs: relMs(loadUs),
+    cls: layoutShifts > 0 ? Number(cls.toFixed(4)) : 0,
+    totalBlockingTimeMs: Number(totalBlockingTimeMs.toFixed(2))
+  };
+  return {
+    metrics,
+    longTasks,
+    longTasksTotalMs: Number(longTasksTotalMs.toFixed(2)),
+    layoutShifts,
+    eventCount: events.length
+  };
+}
+async function performanceAnalyzeInsight(args = {}) {
+  if (!args.tracePath) {
+    throw new CdpError("performanceAnalyzeInsight requires { tracePath } pointing at a trace JSON file");
+  }
+  let raw;
+  try {
+    raw = await readFile3(args.tracePath, "utf8");
+  } catch (err) {
+    throw new CdpError(`cannot read trace file '${args.tracePath}': ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new CdpError(`trace file '${args.tracePath}' is not valid JSON: ${err.message}`);
+  }
+  const events = Array.isArray(parsed) ? parsed : Array.isArray(parsed.traceEvents) ? parsed.traceEvents : (() => {
+    throw new CdpError(`trace file '${args.tracePath}' has no traceEvents array`);
+  })();
+  return { ...analyzeEvents(events), tracePath: args.tracePath };
+}
+
+// src/tools/heap.ts
+import { mkdir as mkdir5, writeFile as writeFile5 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var ARTIFACT_DIR4 = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+function stamp3(targetId) {
+  const short = targetId.slice(0, 8);
+  const iso = new Date().toISOString().replace(/[:.]/g, "-");
+  return `${short}-${iso}`;
+}
+async function takeHeapsnapshot(args = {}) {
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("HeapProfiler.enable");
+    const parts = [];
+    const off = conn.on("HeapProfiler.addHeapSnapshotChunk", (params) => {
+      const chunk = params.chunk;
+      if (typeof chunk === "string")
+        parts.push(chunk);
+    });
+    try {
+      await conn.send("HeapProfiler.takeHeapSnapshot", { reportProgress: false, captureNumericValue: false }, { timeoutMs: 120000 });
+    } finally {
+      off();
+    }
+    const snapshot = parts.join("");
+    if (snapshot.length === 0) {
+      throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
+    }
+    await mkdir5(ARTIFACT_DIR4, { recursive: true });
+    const path = args.savePath ? args.savePath.startsWith("/") ? args.savePath : join3(ARTIFACT_DIR4, args.savePath) : join3(ARTIFACT_DIR4, `take_heapsnapshot-${stamp3(target.id)}.heapsnapshot`);
+    await writeFile5(path, snapshot, "utf8");
+    const bytes = Buffer.byteLength(snapshot, "utf8");
+    return {
+      path,
+      bytes,
+      chunks: parts.length,
+      target: { id: target.id, url: target.url, title: target.title }
+    };
+  });
+}
+
+// src/tools/lighthouse.ts
+import { spawn } from "node:child_process";
+import { mkdir as mkdir6, readFile as readFile4, stat as stat2 } from "node:fs/promises";
+var ARTIFACT_DIR5 = 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() {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+function shortHost(url) {
+  try {
+    const u = new URL(url);
+    const h = u.hostname || u.protocol.replace(/:$/, "");
+    return (h || "page").replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 24);
+  } catch {
+    return "page";
+  }
+}
+function runProcess(cmd, args, opts) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const timer = setTimeout(() => {
+      if (settled)
+        return;
+      try {
+        child.kill("SIGKILL");
+      } catch {}
+    }, opts.timeoutMs);
+    child.stdout.on("data", (d) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d) => {
+      stderr += d.toString();
+    });
+    child.on("error", (err) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code: null, signal: null, stdout, stderr, spawnError: err });
+    });
+    child.on("close", (code, signal) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ code, signal, stdout, stderr });
+    });
+  });
+}
+async function lighthouseAudit(args) {
+  if (!args || typeof args.url !== "string" || args.url.trim() === "") {
+    throw new CdpError("lighthouse_audit requires a non-empty 'url'");
+  }
+  const url = args.url.trim();
+  const timeoutMs = args.timeoutMs ?? 120000;
+  const port = cdpPort();
+  await mkdir6(ARTIFACT_DIR5, { recursive: true });
+  const outPath = args.savePath ?? `${ARTIFACT_DIR5}/lighthouse-${shortHost(url)}-${stamp4()}.json`;
+  const formFactor = args.formFactor ?? "desktop";
+  const lhArgs = [
+    "--yes",
+    "lighthouse",
+    url,
+    `--port=${port}`,
+    "--output=json",
+    `--output-path=${outPath}`,
+    "--quiet",
+    "--chrome-flags=--headless=new"
+  ];
+  if (formFactor === "desktop") {
+    lhArgs.push("--preset=desktop");
+  }
+  if (Array.isArray(args.categories) && args.categories.length > 0) {
+    lhArgs.push(`--only-categories=${args.categories.join(",")}`);
+  }
+  const res = await runProcess("npx", lhArgs, { timeoutMs });
+  if (res.spawnError) {
+    const code = res.spawnError.code;
+    if (code === "ENOENT") {
+      throw new CdpError("lighthouse_audit requires 'npx' (Node.js) on PATH to fetch and run the Lighthouse CLI; 'npx' was not found.");
+    }
+    throw new CdpError(`lighthouse_audit failed to spawn npx/lighthouse: ${res.spawnError.message}`);
+  }
+  let raw;
+  try {
+    raw = await readFile4(outPath, "utf8");
+  } catch {
+    raw = undefined;
+  }
+  if (raw === undefined) {
+    if (res.signal === "SIGKILL") {
+      throw new CdpError(`lighthouse_audit timed out after ${timeoutMs}ms (no report written). stderr: ${truncate(res.stderr)}`);
+    }
+    const hint = /not found|could not determine executable|npm ERR|E404|ERR_MODULE/i.test(res.stderr) ? " The Lighthouse CLI could not be fetched/installed via npx — ensure network access and that 'lighthouse' is installable." : "";
+    throw new CdpError(`lighthouse_audit produced no report (exit code ${res.code}).${hint} stderr: ${truncate(res.stderr)}`);
+  }
+  let report;
+  try {
+    report = JSON.parse(raw);
+  } catch (e) {
+    throw new CdpError(`lighthouse_audit wrote a report that is not valid JSON (${e.message})`);
+  }
+  if (report.runtimeError?.code && report.runtimeError.code !== "NO_ERROR") {
+    throw new CdpError(`lighthouse_audit runtime error [${report.runtimeError.code}]: ${report.runtimeError.message ?? "unknown"}`);
+  }
+  const categories = {};
+  for (const [key, cat] of Object.entries(report.categories ?? {})) {
+    categories[key] = cat?.score ?? null;
+  }
+  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);
+  return {
+    path: outPath,
+    bytes: size,
+    url,
+    finalUrl: report.finalDisplayedUrl ?? report.finalUrl,
+    lighthouseVersion: report.lighthouseVersion,
+    fetchTime: report.fetchTime,
+    categories,
+    warnings: Array.isArray(report.runWarnings) && report.runWarnings.length > 0 ? report.runWarnings : undefined
+  };
+}
+function truncate(s, max = 600) {
+  const t = s.trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}
+
+// src/tools/network_mock.ts
+function escapeRegExpChar(ch) {
+  return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+function globToRegExp(pattern) {
+  let re = "";
+  for (let i = 0;i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "\\") {
+      const next = pattern[i + 1];
+      if (next !== undefined) {
+        re += escapeRegExpChar(next);
+        i++;
+      } else {
+        re += "\\\\";
+      }
+    } else if (ch === "*") {
+      re += ".*";
+    } else if (ch === "?") {
+      re += ".";
+    } else {
+      re += escapeRegExpChar(ch);
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+function urlMatches(pattern, url) {
+  return globToRegExp(pattern).test(url);
+}
+function selectRule(rules, url, method) {
+  return rules.find((r) => urlMatches(r.urlPattern, url) && (!r.method || r.method.toUpperCase() === method.toUpperCase()));
+}
+function buildFulfillParams(requestId, rule) {
+  const merged = new Map;
+  merged.set("content-type", { name: "Content-Type", value: rule.contentType ?? "application/json" });
+  for (const [name, value] of Object.entries(rule.headers ?? {})) {
+    merged.set(name.toLowerCase(), { name, value });
+  }
+  return {
+    requestId,
+    responseCode: rule.status ?? 200,
+    responseHeaders: [...merged.values()],
+    body: Buffer.from(rule.body ?? "", "utf8").toString("base64")
+  };
+}
+function effectiveAction(rule, rnd) {
+  if (rule.failRate !== undefined && rule.failRate > 0 && rnd < rule.failRate)
+    return "fail";
+  return rule.action;
+}
+var sessions = new Map;
+function delay3(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function registerHandler(session) {
+  session.conn.on("Fetch.requestPaused", (params) => {
+    const p = params;
+    session.chain = session.chain.then(async () => {
+      const rule = selectRule(session.rules, p.request.url, p.request.method);
+      if (!rule) {
+        await session.conn.send("Fetch.continueRequest", { requestId: p.requestId });
+        return;
+      }
+      if (rule.delayMs)
+        await delay3(rule.delayMs);
+      const act = effectiveAction(rule, Math.random());
+      if (act === "fulfill") {
+        await session.conn.send("Fetch.fulfillRequest", { ...buildFulfillParams(p.requestId, rule) });
+      } else if (act === "fail") {
+        await session.conn.send("Fetch.failRequest", { requestId: p.requestId, errorReason: rule.errorReason ?? "Failed" });
+      } else {
+        await session.conn.send("Fetch.continueRequest", { requestId: p.requestId });
+      }
+      rule.hits++;
+      session.intercepted.push({ url: p.request.url, method: p.request.method, action: act });
+    }).catch((e) => {
+      if (/closed|connection|Target|Inspected/i.test(String(e)))
+        session.dead = true;
+    });
+  });
+}
+async function mockRequest(args) {
+  if (!args.urlPattern)
+    throw new CdpError("mock_request requires a { urlPattern }");
+  const rule = {
+    urlPattern: args.urlPattern,
+    action: args.action ?? "fulfill",
+    status: args.status,
+    body: args.body,
+    contentType: args.contentType,
+    headers: args.headers,
+    errorReason: args.errorReason,
+    method: args.method,
+    delayMs: args.delayMs,
+    failRate: args.failRate,
+    hits: 0
+  };
+  const resolved = await resolveTarget(args.target);
+  let session = sessions.get(resolved.id);
+  if (session && !session.dead) {
+    const idx = session.rules.findIndex((r) => r.urlPattern === rule.urlPattern && (r.method ?? "") === (rule.method ?? ""));
+    if (idx >= 0)
+      session.rules[idx] = rule;
+    else
+      session.rules.push(rule);
+    await session.conn.send("Fetch.enable", { patterns: session.rules.map((r) => ({ urlPattern: r.urlPattern })) });
+  } else {
+    const { conn, target } = await openPage(resolved.id);
+    session = { conn, target, rules: [rule], intercepted: [], chain: Promise.resolve(), dead: false };
+    registerHandler(session);
+    await conn.send("Fetch.enable", { patterns: [{ urlPattern: rule.urlPattern }] });
+    sessions.set(target.id, session);
+  }
+  let reloaded = false;
+  if (args.reload) {
+    await session.conn.send("Page.enable");
+    await session.conn.send("Page.reload", { ignoreCache: true });
+    await delay3(800);
+    reloaded = true;
+  }
+  return {
+    target: { id: session.target.id, url: session.target.url, title: session.target.title },
+    pattern: rule.urlPattern,
+    ruleCount: session.rules.length,
+    reloaded
+  };
+}
+async function listMocks(_args = {}) {
+  for (const [id, s] of sessions) {
+    if (s.dead) {
+      try {
+        s.conn.close();
+      } catch {}
+      sessions.delete(id);
+      continue;
+    }
+    try {
+      await s.conn.send("Runtime.evaluate", { expression: "1", returnByValue: true }, { timeoutMs: 3000 });
+    } catch {
+      try {
+        s.conn.close();
+      } catch {}
+      sessions.delete(id);
+    }
+  }
+  const mocks = [...sessions.values()].map((s) => ({
+    target: { id: s.target.id, url: s.target.url, title: s.target.title },
+    rules: s.rules.map((r) => ({ urlPattern: r.urlPattern, action: r.action, method: r.method, hits: r.hits })),
+    hits: s.intercepted.length
+  }));
+  return { count: mocks.length, mocks };
+}
+async function clearMocks(args = {}) {
+  let ids;
+  if (args.all) {
+    ids = [...sessions.keys()];
+  } else {
+    const resolved = await resolveTarget(args.target);
+    ids = sessions.has(resolved.id) ? [resolved.id] : [];
+  }
+  let cleared = 0;
+  for (const id of ids) {
+    const s = sessions.get(id);
+    if (!s)
+      continue;
+    try {
+      await s.conn.send("Fetch.disable");
+    } catch {}
+    try {
+      s.conn.close();
+    } catch {}
+    sessions.delete(id);
+    cleared++;
+  }
+  return { cleared };
+}
+
+// src/index.ts
+var TOOLS = {
+  list_pages: listPages,
+  new_page: newPage,
+  close_page: closePage,
+  select_page: selectPage,
+  navigate_page: navigatePage,
+  wait_for: waitForText,
+  evaluate_script: evaluateScript,
+  take_snapshot: takeSnapshot,
+  click,
+  hover,
+  drag,
+  fill,
+  fill_form: fillForm,
+  type_text: typeText,
+  press_key: pressKey,
+  upload_file: uploadFile,
+  take_screenshot: takeScreenshot,
+  emulate,
+  resize_page: resizePage,
+  handle_dialog: handleDialog,
+  list_console_messages: listConsoleMessages,
+  get_console_message: getConsoleMessage,
+  list_network_requests: listNetworkRequests,
+  get_network_request: getNetworkRequest,
+  performance_start_trace: performanceStartTrace,
+  performance_stop_trace: performanceStopTrace,
+  performance_analyze_insight: performanceAnalyzeInsight,
+  performance_trace: performanceTrace,
+  take_heapsnapshot: takeHeapsnapshot,
+  lighthouse_audit: lighthouseAudit,
+  mock_request: mockRequest,
+  list_mocks: listMocks,
+  clear_mocks: clearMocks
+};
+var TOOL_NAMES = Object.keys(TOOLS);
+
+// src/mcp.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+// 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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        all: {
+          type: "boolean",
+          description: "Include non-page targets (service/shared workers, background pages) when true; otherwise only page-type tabs are listed."
+        }
+      },
+      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: {
+        url: {
+          type: "string",
+          description: "URL to open in the new tab; defaults to about:blank."
+        }
+      },
+      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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<targetId>'."
+        }
+      },
+      required: [
+        "target"
+      ],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "navigate_page",
+    description: "Navigate a target page to a URL (Page.navigate) OR reload it (reload:true) over raw CDP, then wait for the load milestone with a bounded timeout so a wedged renderer can't hang. Returns {url,frameId,waitedFor} (plus reloaded:true on a reload); 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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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."
+        },
+        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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        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."
+        },
+        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."
+        },
+        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."
+        }
+      },
+      required: [
+        "expression"
+      ],
+      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: {
+        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>' | '<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).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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."
+        }
+      },
+      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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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 element via synthetic mouse press/move/release (approximates HTML5 drag-and-drop; not guaranteed for every custom DnD library). 'from' and 'to' each take exactly one of uid (a CDP backendDOMNodeId from take_snapshot) or selector.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: "Destination element to drag to. Provide exactly one of uid or selector.",
+          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)."
+            }
+          },
+          additionalProperties: false
+        }
+      },
+      required: [
+        "from",
+        "to"
+      ],
+      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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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, mutually exclusive) via raw CDP Page.captureScreenshot. Writes a PNG/JPEG under /tmp/cdp-toolkit (override with savePath) and returns {path,bytes,format,target}; raw base64 is only included when returnBase64 is set. quality applies to jpeg only.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        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."
+        },
+        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."
+        },
+        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>."
+        },
+        returnBase64: {
+          type: "boolean",
+          description: "Also return the raw base64 image bytes in the result, in addition to writing the file."
+        }
+      },
+      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). 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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (or omitted) for the first page-type target | 'index:N' (0-based) | 'url:<substring>' | 'title:<substring>' | 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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        reload: {
+          type: "boolean",
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+        },
+        durationMs: {
+          type: "number",
+          description: "Capture window for reload mode, in milliseconds. Default 2500."
+        }
+      },
+      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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        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.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        reload: {
+          type: "boolean",
+          description: "Record fresh by reloading the page and capturing for a window. Default false (read the existing buffer)."
+        },
+        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."
+        }
+      },
+      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 reload capture and is matched by url ONLY (reload re-mints requestIds, so a carried-over requestId cannot fetch a body — it returns metadata plus bodyUnavailableReason).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | '<targetId>' | 'index:N' | 'url:<substring>' | 'title:<substring>'."
+        },
+        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."
+        }
+      },
+      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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        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 — the recommended entry point.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: "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: {
+        target: {
+          type: "string",
+          description: "Target page selector: 'active' (default) | 'index:N' | 'url:<substr>' | 'title:<substr>' | '<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: {
+        url: {
+          type: "string",
+          description: "The URL to audit. Required — 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: {
+        target: {
+          type: "string",
+          description: "Target selector: active | index:N | url:<substr> | title:<substr> | <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: {
+        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: {
+        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
+    }
+  }
+];
+
+// src/mcp.ts
+var VERSION = "1.0.0";
+var dispatch = TOOLS;
+function auditCoverage() {
+  const manifestNames = new Set(MANIFEST.map((s) => s.name));
+  const registryNames = new Set(TOOL_NAMES);
+  const missingSchema = [...registryNames].filter((n) => !manifestNames.has(n));
+  const orphanSchema = [...manifestNames].filter((n) => !registryNames.has(n));
+  if (missingSchema.length)
+    console.error(`[cdp-toolkit] WARN: tools without a manifest schema: ${missingSchema.join(", ")}`);
+  if (orphanSchema.length)
+    console.error(`[cdp-toolkit] WARN: manifest schemas with no registered tool: ${orphanSchema.join(", ")}`);
+}
+var server = new Server({ name: "cdp-toolkit", version: VERSION }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: MANIFEST.map((s) => ({ name: s.name, description: s.description, inputSchema: s.inputSchema }))
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name } = request.params;
+  const args = request.params.arguments ?? {};
+  const fn = dispatch[name];
+  if (!fn) {
+    return { content: [{ type: "text", text: `unknown tool: ${name}` }], isError: true };
+  }
+  try {
+    const result = await fn(args);
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+  }
+});
+auditCoverage();
+await server.connect(new StdioServerTransport);
+console.error(`[cdp-toolkit] MCP server v${VERSION} ready — ${MANIFEST.length} tools, CDP_BASE=${BASE}`);