cdp-toolkit 1.0.0

package/src/tools/input.ts

@@ -0,0 +1,399 @@
+/**
+ * Interaction tools: click, hover, drag, fill, fill_form, type_text,
+ * press_key, upload_file.
+ *
+ * Every element-targeting tool accepts exactly one of `{ uid }` (a
+ * backendDOMNodeId from take_snapshot) or `{ selector }` (a CSS selector).
+ * uid resolves via resolveUid (DOM.resolveNode); selector resolves via
+ * Runtime.evaluate(document.querySelector). Both end up as a JS object handle
+ * (objectId), then Runtime.callFunctionOn scrolls it into view + reads its
+ * bounding-rect center, and we dispatch real input events via
+ * Input.dispatchMouseEvent / Input.dispatchKeyEvent. This drives the page the
+ * same way a user would, so framework event handlers fire correctly.
+ */
+import type { CdpConnection } from "../client.ts";
+import { CdpError, withPage } from "../client.ts";
+import type { TargetSelector, Uid } from "../types.ts";
+import { resolveUid } from "./snapshot.ts";
+
+/* --------------------------------- targeting --------------------------------- */
+
+interface ElementTarget {
+  uid?: Uid;
+  selector?: string;
+}
+
+/** Resolve {uid|selector} (exactly one) to a JS object handle on the page. */
+async function resolveElement(conn: CdpConnection, t: ElementTarget): Promise<{ objectId: string }> {
+  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 as Uid);
+  }
+  // selector path
+  const { result, exceptionDetails } = await conn.send<{
+    result: { objectId?: string; subtype?: string };
+    exceptionDetails?: { text?: string };
+  }>("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 };
+}
+
+interface Point {
+  x: number;
+  y: number;
+}
+
+/** Scroll the element into view and return its viewport-space center point. */
+async function centerOf(conn: CdpConnection, objectId: string): Promise<Point> {
+  const { result, exceptionDetails } = await conn.send<{
+    result: { value?: Point | null };
+    exceptionDetails?: { text?: string };
+  }>("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;
+}
+
+/** Focus an element via its object handle (used by fill / type_text). */
+async function focusElement(conn: CdpConnection, objectId: string): Promise<void> {
+  await conn.send("Runtime.callFunctionOn", {
+    objectId,
+    functionDeclaration: "function(){this.focus&&this.focus();}",
+    returnByValue: true,
+  });
+}
+
+/* ----------------------------------- click ----------------------------------- */
+
+export interface ClickArgs extends ElementTarget {
+  target?: TargetSelector;
+  /** "left" (default) | "right" | "middle". */
+  button?: "left" | "right" | "middle";
+  /** 1 = single (default), 2 = double-click. */
+  clickCount?: number;
+}
+
+export async function click(args: ClickArgs): Promise<{ clicked: true; x: number; y: number }> {
+  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 as const, x, y };
+  });
+}
+
+/* ----------------------------------- hover ----------------------------------- */
+
+export interface HoverArgs extends ElementTarget {
+  target?: TargetSelector;
+}
+
+export async function hover(args: HoverArgs): Promise<{ hovered: true; x: number; y: number }> {
+  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 as const, x, y };
+  });
+}
+
+/* ----------------------------------- drag ------------------------------------ */
+
+export interface DragArgs {
+  target?: TargetSelector;
+  /** Source element (exactly one of from.uid / from.selector). */
+  from: ElementTarget;
+  /** Destination element (exactly one of to.uid / to.selector). */
+  to: ElementTarget;
+}
+
+export async function drag(args: DragArgs): Promise<{ dragged: true; from: Point; to: Point }> {
+  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,
+    });
+    // Intermediate move so dragstart/dragover fire on the page.
+    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 as const, from, to };
+  });
+}
+
+/* ------------------------------ fill / type_text ------------------------------ */
+
+/** Set an element's value by clearing it then inserting text (focus + insertText). */
+async function setValue(conn: CdpConnection, objectId: string, value: string): Promise<void> {
+  await focusElement(conn, objectId);
+  // Clear existing content so fill is an overwrite, then insert the new text.
+  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 });
+  }
+}
+
+export interface FillArgs extends ElementTarget {
+  target?: TargetSelector;
+  value: string;
+}
+
+export async function fill(args: FillArgs): Promise<{ filled: true; value: string }> {
+  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 as const, value: args.value };
+  });
+}
+
+export interface TypeTextArgs extends ElementTarget {
+  target?: TargetSelector;
+  text: string;
+}
+
+/**
+ * type_text — focus then insert text. Unlike fill it does NOT clear first, so
+ * it appends to whatever is already focused/present (closest to "typing").
+ */
+export async function typeText(args: TypeTextArgs): Promise<{ typed: true; text: string }> {
+  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 as const, text: args.text };
+  });
+}
+
+/* ---------------------------------- fill_form --------------------------------- */
+
+export interface FillFormField extends ElementTarget {
+  value: string;
+}
+
+export interface FillFormArgs {
+  target?: TargetSelector;
+  fields: FillFormField[];
+}
+
+export async function fillForm(args: FillFormArgs): Promise<{ filled: number; fields: number }> {
+  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 };
+  });
+}
+
+/* ---------------------------------- press_key --------------------------------- */
+
+interface KeySpec {
+  key: string;
+  code: string;
+  keyCode: number;
+  /** text to commit (printable keys / Enter newline) */
+  text?: string;
+}
+
+/** Named-key table: maps friendly names to CDP dispatchKeyEvent fields. */
+const NAMED_KEYS: Record<string, KeySpec> = {
+  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 },
+};
+
+const MODIFIER_BITS: Record<string, number> = {
+  alt: 1,
+  control: 2,
+  ctrl: 2,
+  meta: 4,
+  cmd: 4,
+  command: 4,
+  shift: 8,
+};
+
+/** Resolve a key name (named or single printable char) to a KeySpec. */
+function resolveKey(key: string): KeySpec {
+  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)`);
+}
+
+export interface PressKeyArgs {
+  target?: TargetSelector;
+  /** Key name: "Enter", "Tab", "a", "ArrowDown", etc. */
+  key: string;
+  /** Modifier names: "Control"/"Ctrl", "Shift", "Alt", "Meta"/"Cmd". */
+  modifiers?: string[];
+}
+
+export async function pressKey(args: PressKeyArgs): Promise<{ pressed: string; modifiers: string[] }> {
+  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;
+  }
+  // When a modifier other than Shift is held, suppress text (it's a chord).
+  const suppressText = (modBits & ~MODIFIER_BITS.shift!) !== 0;
+
+  return withPage(args.target, async (conn) => {
+    const down: Record<string, unknown> = {
+      type: "keyDown",
+      key: spec.key,
+      code: spec.code,
+      windowsVirtualKeyCode: spec.keyCode,
+      nativeVirtualKeyCode: spec.keyCode,
+      modifiers: modBits,
+    };
+    if (spec.text && !suppressText) {
+      // A printable char dispatches as keyDown-with-text, which commits the
+      // character (verified: x/y/space produce value "xy "). `type` is already
+      // "keyDown" from construction above.
+      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 };
+  });
+}
+
+/* --------------------------------- upload_file -------------------------------- */
+
+export interface UploadFileArgs extends ElementTarget {
+  target?: TargetSelector;
+  /** Absolute path(s) to the file(s) to attach to the <input type=file>. */
+  files: string | string[];
+}
+
+export async function uploadFile(args: UploadFileArgs): Promise<{ uploaded: string[] }> {
+  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);
+    // setFileInputFiles needs a backendNodeId/objectId reference to the <input>.
+    await conn.send("DOM.setFileInputFiles", { files, objectId });
+    return { uploaded: files };
+  });
+}
+
+/* ------------------------------------------------------------------------------
+ * CDP methods used:
+ *   DOM.resolveNode (via resolveUid), Runtime.evaluate (selector resolution),
+ *   Runtime.callFunctionOn (scrollIntoView + rect center, focus, clear value),
+ *   Input.dispatchMouseEvent (click/hover/drag),
+ *   Input.insertText (fill/type_text/fill_form),
+ *   Input.dispatchKeyEvent (press_key, named keys + modifiers),
+ *   DOM.setFileInputFiles (upload_file).
+ * Parity gaps vs chrome-devtools-mcp interaction tools:
+ *   - press_key supports a curated named-key table + single chars; it is not the
+ *     full Puppeteer KeyInput enum (function keys F1-F12, numpad, IME, etc.).
+ *   - fill/type_text use Input.insertText (atomic paste-like commit) rather than
+ *     per-character keystrokes, so per-char keydown handlers / input masks that
+ *     depend on individual keystrokes won't see each character.
+ *   - drag is a synthetic mouse press/move/release; native HTML5 drag-and-drop
+ *     (DataTransfer) is approximated, matching CDP's mouse-driven model but not
+ *     guaranteed for every custom DnD library.
+ *   - no implicit auto-wait/retry: tools resolve and act once. Callers re-snapshot
+ *     between steps (MCP wraps each action in a Puppeteer locator auto-wait).
+ * ---------------------------------------------------------------------------- */

package/src/tools/lighthouse.ts

@@ -0,0 +1,285 @@
+/**
+ * lighthouse_audit — THE ONLY non-CDP tool in this toolkit.
+ *
+ * Unlike every other module, this one does NOT speak the Chrome DevTools
+ * Protocol over a WebSocket. Instead it shells out to the external Lighthouse
+ * CLI (`npx --yes lighthouse ...`) via node:child_process. Lighthouse attaches
+ * to the already-running Chrome on the remote-debugging port (9222) through its
+ * `--port` flag, drives its own audit, and writes a JSON report. We parse that
+ * report and return the per-category scores.
+ *
+ * Zero npm runtime deps are added: Lighthouse is fetched on-demand by `npx`
+ * (the contract's explicit exception for this single module). If npx or
+ * Lighthouse is unavailable, we throw a clear CdpError naming the dependency.
+ */
+import { spawn } from "node:child_process";
+import { mkdir, readFile, stat } from "node:fs/promises";
+import { CdpError } from "../client.ts";
+
+const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+
+/** Lighthouse port to attach to the already-running Chrome (matches CDP_BASE). */
+function cdpPort(): number {
+  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 stamp(): string {
+  return new Date(Date.now()).toISOString().replace(/[:.]/g, "-");
+}
+
+function shortHost(url: string): string {
+  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";
+  }
+}
+
+/** Result of running a single child process to completion. */
+interface SpawnResult {
+  code: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  spawnError?: Error;
+}
+
+function runProcess(
+  cmd: string,
+  args: string[],
+  opts: { timeoutMs: number },
+): Promise<SpawnResult> {
+  return new Promise<SpawnResult>((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 {
+        /* ignore */
+      }
+    }, opts.timeoutMs);
+
+    child.stdout.on("data", (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on("data", (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on("error", (err: Error) => {
+      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 });
+    });
+  });
+}
+
+/** The shape we read out of a Lighthouse JSON report (only the bits we need). */
+interface LighthouseReport {
+  requestedUrl?: string;
+  finalUrl?: string;
+  finalDisplayedUrl?: string;
+  lighthouseVersion?: string;
+  fetchTime?: string;
+  runtimeError?: { code?: string; message?: string };
+  runWarnings?: string[];
+  categories?: Record<
+    string,
+    { id?: string; title?: string; score?: number | null }
+  >;
+}
+
+export interface LighthouseAuditArgs {
+  /** The URL to audit. Required — never points at a user tab implicitly. */
+  url: string;
+  /**
+   * Lighthouse categories to run. Defaults to the full set.
+   * e.g. ["performance"], ["performance","accessibility","seo"].
+   */
+  categories?: string[];
+  /** Override the report output path (defaults under ARTIFACT_DIR). */
+  savePath?: string;
+  /**
+   * Form factor: "desktop" (default) or "mobile". Desktop avoids the heavy
+   * mobile throttling that makes quick smoke audits slow.
+   */
+  formFactor?: "desktop" | "mobile";
+  /** Overall budget for the lighthouse process (ms). Default 120000. */
+  timeoutMs?: number;
+}
+
+export interface LighthouseAuditResult {
+  path: string;
+  bytes: number;
+  url: string;
+  finalUrl?: string;
+  lighthouseVersion?: string;
+  fetchTime?: string;
+  categories: Record<string, number | null>;
+  warnings?: string[];
+}
+
+/**
+ * Run a Lighthouse audit against `url` using the already-running Chrome on the
+ * CDP port. Returns the report path and per-category scores (0..1, or null when
+ * a category was not run / not scored).
+ */
+export async function lighthouseAudit(
+  args: LighthouseAuditArgs,
+): Promise<LighthouseAuditResult> {
+  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 ?? 120_000;
+  const port = cdpPort();
+
+  await mkdir(ARTIFACT_DIR, { recursive: true });
+  const outPath =
+    args.savePath ?? `${ARTIFACT_DIR}/lighthouse-${shortHost(url)}-${stamp()}.json`;
+
+  const formFactor = args.formFactor ?? "desktop";
+  const lhArgs: string[] = [
+    "--yes",
+    "lighthouse",
+    url,
+    `--port=${port}`,
+    "--output=json",
+    `--output-path=${outPath}`,
+    "--quiet",
+    // Attach to the existing Chrome rather than letting Lighthouse launch its
+    // own; --headless=new keeps it off-screen. Lighthouse honors --port to
+    // reuse the running browser on that remote-debugging port.
+    '--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 as NodeJS.ErrnoException).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}`,
+    );
+  }
+
+  // Try to read the report regardless of exit code: Lighthouse can exit
+  // non-zero on audit warnings while still having written a valid report.
+  let raw: string | undefined;
+  try {
+    raw = await readFile(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: LighthouseReport;
+  try {
+    report = JSON.parse(raw) as LighthouseReport;
+  } catch (e) {
+    throw new CdpError(
+      `lighthouse_audit wrote a report that is not valid JSON (${(e as Error).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: Record<string, number | null> = {};
+  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 stat(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: string, max = 600): string {
+  const t = s.trim();
+  return t.length > max ? `${t.slice(0, max)}…` : t;
+}
+
+/*
+ * ---------------------------------------------------------------------------
+ * NON-CDP MODULE. This is the toolkit's sole tool that does not speak raw CDP.
+ *
+ * External dependency (subprocess, fetched on demand by npx — not an npm dep):
+ *   - `npx --yes lighthouse <url> --port=<cdpPort> --output=json
+ *      --output-path=<artifact> --quiet --preset=desktop
+ *      [--only-categories=...] --chrome-flags=--headless=new`
+ *   Lighthouse attaches to the already-running Chrome via its --port flag and
+ *   runs the audit; we parse the emitted JSON report.
+ *
+ * CDP methods used directly: NONE (Lighthouse drives CDP internally).
+ *
+ * Parity gaps vs the chrome-devtools-mcp `lighthouse_audit` tool:
+ *   - Defaults to the desktop preset (the MCP/Puppeteer integration may default
+ *     to mobile); pass formFactor:"mobile" to match a mobile run.
+ *   - Returns numeric category scores only; does not surface per-audit
+ *     opportunities/diagnostics (the full report is on disk at `path`).
+ *   - No programmatic Puppeteer page reuse: Lighthouse opens its own about:blank
+ *     tab in the attached Chrome for the run rather than auditing a live tab,
+ *     which is intentional (never drives a real user tab).
+ * ---------------------------------------------------------------------------
+ */