cdp-toolkit 1.0.0

package/src/tools/emulation.ts

@@ -0,0 +1,212 @@
+/**
+ * emulation tools — `emulate` and `resize_page` over raw CDP.
+ *
+ * `emulate` is a one-call switchboard over Chrome's emulation overrides:
+ * device metrics (size / DPR / mobile), user-agent, CPU throttling, emulated
+ * media (type + features like prefers-color-scheme), and network conditions.
+ * `resize_page` is the narrow case of setting just the device-metrics size.
+ * A `clearOverrides` path resets every override back to the browser default.
+ *
+ * NOTE on persistence: these overrides live on the DevTools *session*. The
+ * toolkit's stateless one-shot model (withPage opens then closes the
+ * connection) means an override applied in one call is gone once that
+ * connection closes — except device metrics, which Chrome keeps applied to the
+ * target until explicitly cleared or the renderer navigates/reloads. We
+ * therefore re-assert metrics in resize_page and document this in the footer.
+ */
+import type { CdpConnection } from "../client.ts";
+import { CdpError, withPage } from "../client.ts";
+import type { Target, TargetSelector } from "../types.ts";
+
+export interface NetworkConditions {
+  /** true = simulate offline. */
+  offline?: boolean;
+  /** additional round-trip latency, ms. */
+  latency?: number;
+  /** max download throughput, bytes/sec (-1 = no limit). */
+  downloadThroughput?: number;
+  /** max upload throughput, bytes/sec (-1 = no limit). */
+  uploadThroughput?: number;
+  /** "none" | "cellular2g" | "cellular3g" | "cellular4g" | "bluetooth" | "ethernet" | "wifi" | "wimax" | "other" */
+  connectionType?: string;
+}
+
+export interface EmulateArgs {
+  target?: TargetSelector;
+  width?: number;
+  height?: number;
+  deviceScaleFactor?: number;
+  mobile?: boolean;
+  userAgent?: string;
+  /** 1 = no throttle; 2 = 2x slower; etc. */
+  cpuThrottlingRate?: number;
+  /** Emulated CSS media type: "screen" | "print" | "" (clear). */
+  media?: string;
+  /** Emulated media features, e.g. [{ name:"prefers-color-scheme", value:"dark" }]. */
+  mediaFeatures?: Array<{ name: string; value: string }>;
+  networkConditions?: NetworkConditions;
+  /** Reset every override to the browser default; ignores all other fields. */
+  clearOverrides?: boolean;
+}
+
+export interface EmulateResult {
+  target: { id: string; url: string; title: string };
+  applied: string[];
+  cleared?: boolean;
+}
+
+export interface ResizeArgs {
+  target?: TargetSelector;
+  width: number;
+  height: number;
+  deviceScaleFactor?: number;
+  mobile?: boolean;
+}
+
+export interface ResizeResult {
+  target: { id: string; url: string; title: string };
+  width: number;
+  height: number;
+  /** window.innerWidth/innerHeight observed after the override is applied. */
+  innerWidth: number;
+  innerHeight: number;
+}
+
+async function clearAll(conn: CdpConnection): Promise<void> {
+  // Order doesn't matter; each is independent. Tolerate per-domain absence.
+  await conn.send("Emulation.clearDeviceMetricsOverride").catch(() => undefined);
+  await conn.send("Emulation.setUserAgentOverride", { userAgent: "" }).catch(() => undefined);
+  await conn.send("Emulation.setCPUThrottlingRate", { rate: 1 }).catch(() => undefined);
+  await conn.send("Emulation.setEmulatedMedia", { media: "", features: [] }).catch(() => undefined);
+  await conn.send("Network.enable").catch(() => undefined);
+  await conn
+    .send("Network.emulateNetworkConditions", {
+      offline: false,
+      latency: 0,
+      downloadThroughput: -1,
+      uploadThroughput: -1,
+    })
+    .catch(() => undefined);
+}
+
+/**
+ * emulate — apply any subset of device-metrics / UA / CPU / media / network
+ * overrides in a single call, or clear them all with { clearOverrides:true }.
+ */
+export async function emulate(args: EmulateArgs = {}): Promise<EmulateResult> {
+  const { target } = args;
+  return withPage(target, async (conn: CdpConnection, t: Target) => {
+    if (args.clearOverrides) {
+      await clearAll(conn);
+      return {
+        target: { id: t.id, url: t.url, title: t.title },
+        applied: [],
+        cleared: true,
+      };
+    }
+
+    const applied: string[] = [];
+
+    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(() => undefined);
+      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 };
+  });
+}
+
+/**
+ * resize_page — set the page's device-metrics width/height. Verifies by reading
+ * back window.innerWidth/innerHeight after the override is applied.
+ */
+export async function resizePage(args: ResizeArgs): Promise<ResizeResult> {
+  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: CdpConnection, t: Target) => {
+    await conn.send("Emulation.setDeviceMetricsOverride", {
+      width,
+      height,
+      deviceScaleFactor: args.deviceScaleFactor ?? 0,
+      mobile: args.mobile ?? false,
+    });
+    await conn.send("Runtime.enable").catch(() => undefined);
+    const { result } = await conn.send<{ result: { value?: { w: number; h: number } } }>("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,
+    };
+  });
+}
+
+/*
+ * CDP methods/domains used:
+ *   - Emulation.setDeviceMetricsOverride   (resize + emulate metrics)
+ *   - Emulation.clearDeviceMetricsOverride (clearOverrides)
+ *   - Emulation.setUserAgentOverride
+ *   - Emulation.setCPUThrottlingRate
+ *   - Emulation.setEmulatedMedia           (media type + features)
+ *   - Network.enable / Network.emulateNetworkConditions
+ *   - Runtime.enable / Runtime.evaluate    (resize_page read-back verification)
+ * Parity gaps vs chrome-devtools-mcp emulate/resize_page:
+ *   - Override lifetime: toolkit is stateless (connection closes after each call). Device-metrics
+ *     overrides persist on the target until cleared/navigated; UA/CPU/media/network overrides are
+ *     session-scoped and reset when the per-call connection closes. The MCP keeps one long-lived
+ *     session so its non-metrics overrides persist across subsequent MCP calls; ours do not.
+ *   - No named device-descriptor presets (e.g. "iPhone 15"); caller passes raw metrics + UA.
+ *   - No touch-emulation / screen-orientation override (Emulation.setTouchEmulationEnabled,
+ *     setDeviceMetricsOverride.screenOrientation) — out of the assigned arg surface.
+ */

package/src/tools/evaluate.ts

@@ -0,0 +1,155 @@
+/**
+ * evaluate_script — run arbitrary JavaScript in a page's main context over raw
+ * CDP and return the evaluated value.
+ *
+ * Two modes, selected by whether `args` is supplied:
+ *   - No args: `Runtime.evaluate` of the raw expression (returnByValue,
+ *     awaitPromise). The natural fast path; "1+2" -> 3.
+ *   - With args: the expression is treated as a JS function (e.g. an arrow
+ *     `(a,b)=>a+b` or a `function(a,b){...}`). We resolve the page's global
+ *     object, then `Runtime.callFunctionOn` that global with the expression as
+ *     the function declaration and the supplied `args` passed positionally.
+ *     This mirrors chrome-devtools-mcp's evaluate_script(function, args) shape.
+ *
+ * Either way, a `exceptionDetails` in the response is surfaced as a thrown
+ * `CdpError` carrying the exception/description text.
+ */
+import { CdpError, withPage } from "../client.ts";
+import type { CdpConnection } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+
+/** A CDP RemoteObject as returned by Runtime.evaluate / Runtime.callFunctionOn. */
+interface RemoteObject {
+  type: string;
+  subtype?: string;
+  className?: string;
+  value?: unknown;
+  unserializableValue?: string;
+  description?: string;
+  objectId?: string;
+}
+
+/** Shape of a CDP exceptionDetails payload (subset we report on). */
+interface ExceptionDetails {
+  text?: string;
+  exception?: RemoteObject;
+  lineNumber?: number;
+  columnNumber?: number;
+}
+
+interface EvalResponse {
+  result: RemoteObject;
+  exceptionDetails?: ExceptionDetails;
+}
+
+export interface EvaluateScriptArgs {
+  /** Page selector; defaults to the active page. */
+  target?: TargetSelector;
+  /**
+   * JavaScript to run. When `args` is omitted this is evaluated as an
+   * expression. When `args` is provided this must be a function literal
+   * (arrow or classic) whose parameters receive the supplied `args`.
+   */
+  expression: string;
+  /** Await the result if it is a Promise (default true). */
+  awaitPromise?: boolean;
+  /** Positional arguments to pass to the expression (treats it as a function). */
+  args?: unknown[];
+}
+
+/** Build a readable message out of a CDP exceptionDetails block. */
+function exceptionMessage(details: ExceptionDetails): string {
+  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";
+}
+
+/**
+ * Extract the JS value from a RemoteObject. With returnByValue, `value` holds
+ * the serialized value; fall back to unserializableValue (Infinity/NaN/-0) and
+ * finally the description for non-serializable objects.
+ */
+function unwrap(obj: RemoteObject): unknown {
+  if (Object.prototype.hasOwnProperty.call(obj, "value")) return obj.value;
+  if (obj.unserializableValue !== undefined) return obj.unserializableValue;
+  if (obj.type === "undefined") return undefined;
+  return obj.description ?? null;
+}
+
+async function evaluateExpression(conn: CdpConnection, expression: string, awaitPromise: boolean): Promise<unknown> {
+  const res = await conn.send<EvalResponse>("Runtime.evaluate", {
+    expression,
+    returnByValue: true,
+    awaitPromise,
+    // Allow `await` at the top of expressions and surface a usable result.
+    replMode: false,
+    // Don't let a thrown value escape as a raw protocol error; we read
+    // exceptionDetails ourselves below.
+    silent: false,
+  });
+  if (res.exceptionDetails) throw new CdpError(exceptionMessage(res.exceptionDetails));
+  return unwrap(res.result);
+}
+
+async function evaluateFunction(
+  conn: CdpConnection,
+  expression: string,
+  awaitPromise: boolean,
+  args: unknown[],
+): Promise<unknown> {
+  // Resolve the page's global object to give callFunctionOn an `this`/context.
+  const globalObj = await conn.send<{ result: RemoteObject }>("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<EvalResponse>("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);
+}
+
+/**
+ * Evaluate `expression` in the page and return its value. When `args` is
+ * supplied, `expression` is invoked as a function with those positional args.
+ */
+export async function evaluateScript(args: EvaluateScriptArgs): Promise<unknown> {
+  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);
+  });
+}
+
+/*
+ * CDP methods/domains used:
+ *   - Runtime.enable
+ *   - Runtime.evaluate           (no-args expression path; returnByValue + awaitPromise)
+ *   - Runtime.callFunctionOn     (args path: expression treated as a function literal, called on globalThis)
+ *
+ * Parity gaps vs chrome-devtools-mcp evaluate_script:
+ *   - MCP injects a typed `page`/element handle into the evaluated function; here `args` are plain
+ *     JSON-serializable values passed positionally — no live element/page handle is bound.
+ *   - Non-serializable return values (DOM nodes, functions, circular objects) come back as their CDP
+ *     `description` string rather than a structured handle, since returnByValue is used.
+ *   - No isolated-world/contextId selection: evaluation runs in the page's default main-world context.
+ */

package/src/tools/heap.ts

@@ -0,0 +1,109 @@
+/**
+ * heap.ts — `take_heapsnapshot` over raw CDP.
+ *
+ * Captures a V8 heap snapshot of a page target and writes it as a
+ * `.heapsnapshot` file (the JSON format DevTools' Memory panel loads).
+ *
+ * CDP semantics this module relies on:
+ *   - `HeapProfiler.takeHeapSnapshot` streams the snapshot back as a sequence
+ *     of `HeapProfiler.addHeapSnapshotChunk` events. The command's own result
+ *     does NOT carry the data — it resolves only after the final chunk has been
+ *     emitted. So we subscribe to the chunk event first, accumulate every
+ *     chunk's string, then `await` the command; once it resolves we have the
+ *     complete snapshot and join the chunks into one JSON document.
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { withPage } from "../client.ts";
+import type { TargetSelector } from "../types.ts";
+
+const ARTIFACT_DIR = process.env.CDP_ARTIFACT_DIR ?? "/tmp/cdp-toolkit";
+
+export interface TakeHeapsnapshotArgs {
+  /** Page selector (defaults to the active page). */
+  target?: TargetSelector;
+  /** Override the output path. When relative, resolved under ARTIFACT_DIR. */
+  savePath?: string;
+}
+
+export interface TakeHeapsnapshotResult {
+  path: string;
+  bytes: number;
+  /** Number of `addHeapSnapshotChunk` events accumulated. */
+  chunks: number;
+  target: { id: string; url: string; title: string };
+}
+
+/** A short, fs-safe stamp derived from the target id and the current time. */
+function stamp(targetId: string): string {
+  const short = targetId.slice(0, 8);
+  const iso = new Date().toISOString().replace(/[:.]/g, "-");
+  return `${short}-${iso}`;
+}
+
+/**
+ * Take a V8 heap snapshot of the selected page and persist it as a
+ * `.heapsnapshot` file under ARTIFACT_DIR (or `savePath`).
+ */
+export async function takeHeapsnapshot(
+  args: TakeHeapsnapshotArgs = {},
+): Promise<TakeHeapsnapshotResult> {
+  return withPage(args.target, async (conn, target) => {
+    await conn.send("HeapProfiler.enable");
+
+    // Subscribe BEFORE issuing the command so we don't miss early chunks.
+    const parts: string[] = [];
+    const off = conn.on("HeapProfiler.addHeapSnapshotChunk", (params) => {
+      const chunk = (params as { chunk?: unknown }).chunk;
+      if (typeof chunk === "string") parts.push(chunk);
+    });
+
+    try {
+      // Resolves only after the final addHeapSnapshotChunk has fired. We grant
+      // it a generous timeout: heap snapshots of large pages can take a while.
+      await conn.send(
+        "HeapProfiler.takeHeapSnapshot",
+        { reportProgress: false, captureNumericValue: false },
+        { timeoutMs: 120_000 },
+      );
+    } finally {
+      off();
+    }
+
+    const snapshot = parts.join("");
+    if (snapshot.length === 0) {
+      throw new Error("HeapProfiler.takeHeapSnapshot produced no chunks");
+    }
+
+    await mkdir(ARTIFACT_DIR, { recursive: true });
+    const path = args.savePath
+      ? args.savePath.startsWith("/")
+        ? args.savePath
+        : join(ARTIFACT_DIR, args.savePath)
+      : join(ARTIFACT_DIR, `take_heapsnapshot-${stamp(target.id)}.heapsnapshot`);
+
+    await writeFile(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 },
+    };
+  });
+}
+
+/* ----------------------------------------------------------------------------
+ * CDP methods/domains used:
+ *   - HeapProfiler.enable
+ *   - HeapProfiler.takeHeapSnapshot           (command; resolves after last chunk)
+ *   - HeapProfiler.addHeapSnapshotChunk        (event; accumulated into the file)
+ *
+ * Parity gaps vs chrome-devtools-mcp `take_heapsnapshot`:
+ *   - reportProgress is forced false; no incremental progress callbacks surfaced.
+ *   - Returns {path,bytes,chunks,target} only — does not parse/summarize the
+ *     snapshot (node counts, retained sizes); the .heapsnapshot file is for the
+ *     DevTools Memory panel to load, matching the MCP tool's artifact behavior.
+ * --------------------------------------------------------------------------*/