cdp-toolkit 1.0.0 → 1.2.0

package/src/tools/network_mock.ts

@@ -1,13 +1,13 @@
 /**
- * network_mock.ts — a per-target FAKE BACKEND for the page: intercept matching
+ * network_mock.ts: a per-target FAKE BACKEND for the page: intercept matching
  * requests via the CDP Fetch domain and fulfill them with a canned response,
  * fail (abort) them, or let them continue (optionally with fault injection).
  * The rod `HijackRequests` capability the read-only console/network tools lack.
  *
  * This file is split into two layers:
  *   1. PURE logic (urlMatches / selectRule / buildFulfillParams / effectiveAction)
- *      — no browser, unit-tested in test/network_mock.test.ts.
- *   2. STATEFUL tools (mockRequest / listMocks / clearMocks) — hold a persistent
+ *      No browser needed, unit-tested in test/network_mock.test.ts.
+ *   2. STATEFUL tools (mockRequest / listMocks / clearMocks): hold a persistent
  *      CDP connection per target; integration-tested in test/mock-smoke.ts.
  */
 import { CdpError, openPage, resolveTarget } from "../client.ts";
@@ -15,7 +15,7 @@ import type { CdpConnection } from "../client.ts";
 import type { Target, TargetSelector } from "../types.ts";
 
 /* ============================================================================
- * LAYER 1 — pure logic (no I/O)
+ * LAYER 1: pure logic (no I/O)
  * ========================================================================== */
 
 export type MockAction = "fulfill" | "fail" | "continue";
@@ -111,7 +111,7 @@ export function effectiveAction(rule: { action: MockAction; failRate?: number },
 }
 
 /* ============================================================================
- * LAYER 2 — stateful tools (persistent per-target CDP connection)
+ * LAYER 2: stateful tools (persistent per-target CDP connection)
  *
  * A "fake backend" is a per-target SESSION holding ONE persistent CDP connection
  * with the Fetch domain enabled. Each session carries a list of rules; an
@@ -122,7 +122,7 @@ export function effectiveAction(rule: { action: MockAction; failRate?: number },
  * Persistence works because the MCP server process is long-lived across tool
  * calls, so this module-level `sessions` map and its open connections outlive a
  * single call. (The stateless CLI process exits after one command, so persistent
- * mocking is an MCP-server capability — like the recorder's background mode.)
+ * mocking is an MCP-server capability, like the recorder's background mode.)
  *
  * SAFETY: every paused request MUST be answered or the renderer hangs. A request
  * that pauses but matches no rule is continued untouched.
@@ -182,7 +182,7 @@ function registerHandler(session: MockSession): void {
         session.intercepted.push({ url: p.request.url, method: p.request.method, action: act });
       })
       .catch((e) => {
-        // Tab navigated away mid-flight or the connection dropped — best-effort.
+        // Tab navigated away mid-flight or the connection dropped, best-effort.
         if (/closed|connection|Target|Inspected/i.test(String(e))) session.dead = true;
       });
   });
@@ -359,7 +359,7 @@ export async function clearMocks(args: ClearMocksArgs = {}): Promise<{ cleared:
  *   Page.enable + Page.reload (reload:true), Runtime.evaluate (liveness probe).
  * Model: persistent per-target session (like recorder.ts), MCP-server-scoped state.
  * Parity gaps vs rod HijackRequests / chrome-devtools-mcp:
- *   - Request-stage only — no live Response-body rewriting (add requestStage:"Response"
+ *   - Request-stage only, no live Response-body rewriting (add requestStage:"Response"
  *     + Fetch.getResponseBody/continueResponse for that).
  *   - Persistence is in-process: works via the long-lived MCP server, not the
  *     one-shot CLI (mirrors the recorder's background mode).

package/src/tools/performance.ts

@@ -1,19 +1,19 @@
 /**
- * performance.ts — performance tracing + insight analysis over raw CDP.
+ * performance.ts: performance tracing + insight analysis over raw CDP.
  *
  * NOTE ON THE INSIGHT ANALYZER: `performanceAnalyzeInsight` is a CDP-native
  * APPROXIMATION of chrome-devtools-mcp's insight analyzer. The MCP tool runs the
  * DevTools/Lighthouse "Trace Engine" insight pipeline (a large TS engine that
  * models the full RAIL/Core-Web-Vitals heuristics). We do NOT vendor that
  * engine (zero-runtime-deps rule). Instead we parse the raw Chrome trace event
- * stream ourselves and derive the headline metrics — navigationStart, FCP, LCP,
- * long tasks (>50ms), layout shifts / CLS, and total blocking time — directly
+ * stream ourselves and derive the headline metrics (navigationStart, FCP, LCP,
+ * long tasks (>50ms), layout shifts / CLS, and total blocking time) directly
  * from the trace events. Numbers will be close to but not byte-identical with
  * the MCP/DevTools panel, which applies extra normalization (e.g. main-thread
  * attribution, frame-scoped LCP, soft-navigation handling).
  *
  * NOTE ON TRACING STATE: CDP `Tracing.start`/`Tracing.end` are bound to a single
- * live session — the recording lives on the WebSocket connection, and
+ * live session: the recording lives on the WebSocket connection, and
  * `Tracing.dataCollected` events stream back on that same connection. There is
  * no way to "re-attach" to an in-flight trace from a fresh process, because the
  * buffer is owned by the connection that started it. Cross-process persistence
@@ -213,7 +213,7 @@ export async function performanceStopTrace(
 ): Promise<{ path: string; bytes: number; events: number; metrics: TraceMetrics }> {
   // CDP tracing is browser-GLOBAL: a second Tracing.start throws "Tracing has
   // already been started", so at most one trace is ever live in this process.
-  // There is therefore nothing to disambiguate by target — take the single live
+  // There is therefore nothing to disambiguate by target; take the single live
   // trace if present. (`args.target` is accepted for API symmetry with start.)
   void args.target;
   const entry: LiveTrace | undefined = liveTraces.size === 1 ? [...liveTraces.values()][0] : undefined;
@@ -250,7 +250,7 @@ export async function performanceStopTrace(
 }
 
 /* ------------------------------------------------------------------ */
-/* performanceTrace (PRIMARY one-shot — the smoke path)               */
+/* performanceTrace (PRIMARY one-shot, the smoke path)                */
 /* ------------------------------------------------------------------ */
 
 export interface PerformanceTraceArgs {
@@ -366,7 +366,7 @@ export function analyzeEvents(events: TraceEvent[]): TraceMetrics {
       continue;
     }
 
-    // LCP candidate — the LAST candidate before user input is the real LCP.
+    // LCP candidate: the LAST candidate before user input is the real LCP.
     if (name === "largestContentfulPaint::Candidate" && typeof e.ts === "number") {
       // candidates are monotonic; keep the latest timestamp seen.
       if (lcpUs === undefined || e.ts > lcpUs) lcpUs = e.ts;
@@ -383,7 +383,7 @@ export function analyzeEvents(events: TraceEvent[]): TraceMetrics {
       continue;
     }
 
-    // Layout shifts — sum scores that did NOT follow recent user input.
+    // Layout shifts: sum scores that did NOT follow recent user input.
     if (name === "LayoutShift") {
       const data = e.args?.data;
       const hadRecentInput = data?.had_recent_input === true;
@@ -438,7 +438,7 @@ export interface PerformanceAnalyzeInsightArgs {
 /**
  * CDP-native approximation of the MCP insight analyzer. Reads a trace JSON file
  * (bare array OR { traceEvents: [...] }) and returns structured headline
- * metrics. If `tracePath` is omitted, throws — there is no implicit "latest
+ * metrics. If `tracePath` is omitted, throws; there is no implicit "latest
  * trace" magic; callers pass the path returned by a trace tool.
  */
 export async function performanceAnalyzeInsight(
@@ -473,9 +473,9 @@ export async function performanceAnalyzeInsight(
 /*
  * CDP methods/domains used:
  *   - Tracing.start (traceConfig.includedCategories, transferMode:ReportEvents)
- *   - Tracing.dataCollected   (event — buffered into the event array)
+ *   - Tracing.dataCollected   (event, buffered into the event array)
  *   - Tracing.end
- *   - Tracing.tracingComplete (event — awaited to know recording is flushed)
+ *   - Tracing.tracingComplete (event, awaited to know recording is flushed)
  *   - Page.enable / Page.navigate / Page.reload / Page.loadEventFired (one-shot reload path)
  *
  * Parity gaps vs chrome-devtools-mcp performance tools:

package/src/tools/recorder.ts

@@ -1,5 +1,5 @@
 /**
- * recorder.ts — the stateful console+network capture engine.
+ * recorder.ts: the stateful console+network capture engine.
  *
  * RECORDER MODEL
  * ==============
@@ -22,7 +22,7 @@
  *
  * CAPTURE MODEL (what the tool surface actually uses)
  * ---------------------------------------------------
- * The console/network tools drive `captureWindow()` — a one-shot reload capture
+ * The console/network tools drive `captureWindow()`, a one-shot reload capture
  * that records BOTH domains into a UNIQUE per-capture file
  * (`rec-<targetId>-<captureId>.jsonl`) and, on stop, publishes that capture as
  * the target's shared "latest" buffer (`rec-<targetId>.jsonl`). Capturing both
@@ -154,7 +154,7 @@ export async function startRecorder(target: TargetSelector, opts: RecorderOption
       try {
         await conn.send("Log.enable");
       } catch {
-        /* Log not supported on this target type — Runtime events still flow */
+        /* Log not supported on this target type; Runtime events still flow */
       }
       for (const ev of CONSOLE_EVENTS) {
         unsubs.push(conn.on(ev, (params) => persist("console", ev, params)));
@@ -165,7 +165,7 @@ export async function startRecorder(target: TargetSelector, opts: RecorderOption
     throw err;
   }
 
-  // Stop accepting new events, then let queued appends settle — without closing
+  // Stop accepting new events, then let queued appends settle, without closing
   // the connection (response bodies stay fetchable on `conn`).
   const flush = async (): Promise<void> => {
     for (const off of unsubs) off();
@@ -195,7 +195,7 @@ export async function startRecorder(target: TargetSelector, opts: RecorderOption
 export interface CaptureWindow {
   /** The unique per-capture buffer file (read this for isolated results). */
   file: string;
-  /** Live connection (open until stop) — for Network.getResponseBody etc. */
+  /** Live connection (open until stop), for Network.getResponseBody etc. */
   conn: CdpConnection;
   /** Resolved target identity. */
   resolved: { id: string; url: string; title: string };

package/src/tools/snapshot.ts

@@ -3,7 +3,7 @@
  *
  * The reference scheme (CONTRACT.md "The element-reference scheme"):
  *   A `Uid` IS a CDP `backendDOMNodeId` (a number). Refs are therefore
- *   stateless — `take_snapshot` emits them straight from the a11y tree, and
+ *   stateless: `take_snapshot` emits them straight from the a11y tree, and
  *   every interaction tool resolves them back to a live DOM node via
  *   `DOM.resolveNode({ backendNodeId: uid })`. There is no server-side ref
  *   table to drift or expire.
@@ -124,7 +124,7 @@ export interface TakeSnapshotResult {
 }
 
 /**
- * take_snapshot — Accessibility.getFullAXTree walked into a compact indented
+ * take_snapshot: Accessibility.getFullAXTree walked into a compact indented
  * text tree. Each emitted line carries the node's backendDOMNodeId as [uid],
  * which interaction tools feed straight back to resolveUid.
  */

package/src/tools/dialogs.ts

@@ -1,236 +0,0 @@
-/**
- * dialogs.ts — JavaScript dialog handling (alert / confirm / prompt / beforeunload).
- *
- * Replicates chrome-devtools-mcp's `handle_dialog`. A JS dialog opened by the
- * page (alert/confirm/prompt/beforeunload) blocks the renderer until the
- * embedder responds via Page.handleJavaScriptDialog. Over raw CDP we:
- *   1. Page.enable
- *   2. subscribe to Page.javascriptDialogOpening
- *   3. on fire, respond with Page.handleJavaScriptDialog({ accept, promptText })
- *
- * Two modes are supported per CONTRACT:
- *   - "wait for next dialog then handle" (default): arm the listener and resolve
- *     when the next dialog is handled, or time out if none appears.
- *   - "auto-handle for N ms" ({ autoMs }): handle every dialog that opens during
- *     a fixed window, then resolve with the list handled.
- *
- * Because a dialog blocks the renderer, the code that *triggers* the dialog
- * (e.g. a Runtime.evaluate of `confirm("x")`) must NOT be awaited before the
- * dialog is handled — otherwise it deadlocks. `handleDialogForExpression` arms
- * the listener, fires the expression WITHOUT awaiting, waits for the dialog to
- * be handled, then awaits the now-unblocked evaluate result.
- */
-import type { CdpConnection } from "../client.ts";
-import { CdpError, openPage } from "../client.ts";
-import type { TargetSelector } from "../types.ts";
-
-/** Raw shape of the Page.javascriptDialogOpening event params. */
-interface JavascriptDialogOpening {
-  url: string;
-  message: string;
-  type: "alert" | "confirm" | "prompt" | "beforeunload" | string;
-  hasBrowserHandler: boolean;
-  defaultPrompt?: string;
-}
-
-/** A single handled dialog. */
-export interface HandledDialog {
-  type: string;
-  message: string;
-  url: string;
-  defaultPrompt?: string;
-  accept: boolean;
-  promptText?: string;
-  handled: true;
-}
-
-export interface HandleDialogArgs {
-  target?: TargetSelector;
-  /** Whether to accept (OK) or dismiss (Cancel) the dialog. */
-  accept: boolean;
-  /** Text to enter for a prompt() dialog when accepting. */
-  promptText?: string;
-  /** How long to wait for the next dialog (default 15000ms). */
-  timeoutMs?: number;
-  /**
-   * Auto-handle mode: keep handling every dialog that opens for this many ms,
-   * then resolve. When set, the return value is a list of handled dialogs and
-   * the function never throws on "no dialog" (an empty list is a valid result).
-   */
-  autoMs?: number;
-}
-
-/**
- * Arm a dialog handler on a live page connection. Returns a disarm function and
- * a promise that resolves with each dialog as it is handled (via the onHandled
- * callback). This is the low-level primitive used by both public modes and by
- * the expression helper.
- */
-function armDialogHandler(
-  conn: CdpConnection,
-  accept: boolean,
-  promptText: string | undefined,
-  onHandled: (d: HandledDialog) => void,
-): () => void {
-  return conn.on("Page.javascriptDialogOpening", (params) => {
-    const ev = params as unknown as JavascriptDialogOpening;
-    void (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 {
-        /* connection may have raced closed; the awaiter will time out */
-      }
-    })();
-  });
-}
-
-/**
- * handle_dialog — wait for the next JS dialog on a page and respond to it.
- *
- * Default mode: opens a persistent connection, enables Page, arms the listener,
- * and resolves with the first handled dialog (or throws on timeout). Auto mode
- * ({ autoMs }): handles every dialog for the window and resolves with the list.
- *
- * The caller is expected to trigger the dialog out-of-band (e.g. by clicking a
- * button on the page). To trigger-and-handle in one call, use
- * handleDialogForExpression.
- */
-export async function handleDialog(
-  args: HandleDialogArgs,
-): Promise<HandledDialog | { handled: HandledDialog[]; count: number }> {
-  const { target, accept, promptText, timeoutMs = 15_000, autoMs } = args;
-  const { conn } = await openPage(target);
-  try {
-    await conn.send("Page.enable");
-
-    if (autoMs !== undefined) {
-      const handled: HandledDialog[] = [];
-      const disarm = armDialogHandler(conn, accept, promptText, (d) => handled.push(d));
-      await new Promise<void>((resolve) => setTimeout(resolve, autoMs));
-      disarm();
-      return { handled, count: handled.length };
-    }
-
-    return await new Promise<HandledDialog>((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();
-  }
-}
-
-export interface HandleDialogForExpressionArgs {
-  target?: TargetSelector;
-  /** A JS expression that opens a dialog, e.g. `confirm("ok?")` or `prompt("name?")`. */
-  expression: string;
-  accept: boolean;
-  promptText?: string;
-  timeoutMs?: number;
-}
-
-/**
- * Arm a dialog handler, evaluate an expression that OPENS a dialog (without
- * awaiting it — a blocking dialog would otherwise deadlock the evaluate), wait
- * for the dialog to be handled, then await the now-unblocked evaluate result.
- *
- * Returns both the handled-dialog metadata and the value the expression
- * resolved to (e.g. `true` for an accepted confirm, the entered text for an
- * accepted prompt, `false`/`null` for a dismissed one). This is the
- * trigger-and-handle helper used by the live smoke test.
- */
-export async function handleDialogForExpression(
-  args: HandleDialogForExpressionArgs,
-): Promise<{ dialog: HandledDialog; value: unknown }> {
-  const { target, expression, accept, promptText, timeoutMs = 15_000 } = args;
-  const { conn } = await openPage(target);
-  try {
-    await conn.send("Page.enable");
-    await conn.send("Runtime.enable");
-
-    let resolveDialog!: (d: HandledDialog) => void;
-    let rejectDialog!: (e: Error) => void;
-    const dialogPromise = new Promise<HandledDialog>((res, rej) => {
-      resolveDialog = res;
-      rejectDialog = rej;
-    });
-    const timer = setTimeout(
-      () => rejectDialog(new CdpError(`handle_dialog: expression opened no dialog within ${timeoutMs}ms`)),
-      timeoutMs,
-    );
-    const disarm = armDialogHandler(conn, accept, promptText, (d) => {
-      clearTimeout(timer);
-      resolveDialog(d);
-    });
-
-    // Fire the dialog-opening expression WITHOUT awaiting: a blocking dialog
-    // holds the evaluate open until we handle it. We capture the promise so we
-    // can await its (now-unblocked) value after the dialog is handled.
-    const evalPromise = conn
-      .send<{ result: { value?: unknown }; exceptionDetails?: { text?: string } }>("Runtime.evaluate", {
-        expression,
-        returnByValue: true,
-        awaitPromise: true,
-        // The evaluate itself must not time out before we handle the dialog.
-        userGesture: true,
-      })
-      .catch((e: unknown) => {
-        // Surface as an exception-shaped result so the await below can decide.
-        return { result: {}, __error: e } as { result: { value?: unknown }; __error: unknown };
-      });
-
-    const dialog = await dialogPromise;
-    disarm();
-
-    const evalResult = (await evalPromise) as {
-      result: { value?: unknown };
-      exceptionDetails?: { text?: string };
-      __error?: unknown;
-    };
-    if (evalResult.__error) throw evalResult.__error;
-    if (evalResult.exceptionDetails) {
-      throw new CdpError(`expression threw: ${evalResult.exceptionDetails.text ?? "unknown error"}`);
-    }
-
-    return { dialog, value: evalResult.result?.value };
-  } finally {
-    conn.close();
-  }
-}
-
-/* ----------------------------------------------------------------------------
- * CDP methods / domains used:
- *   - Page.enable
- *   - Page.javascriptDialogOpening   (event, subscribed)
- *   - Page.handleJavaScriptDialog    ({ accept, promptText })
- *   - Runtime.enable                 (helper only)
- *   - Runtime.evaluate               (helper only — fires the dialog-opening expr)
- *
- * Parity gaps vs chrome-devtools-mcp `handle_dialog`:
- *   - MCP auto-handles the single pending dialog tracked by its Page object;
- *     here the caller arms first and triggers out-of-band, OR uses the
- *     handleDialogForExpression helper to trigger-and-handle atomically.
- *   - MCP returns its standard page/snapshot envelope after handling; this
- *     returns just the handled-dialog metadata (type/message/url/accept/...).
- *   - beforeunload dialogs are handled the same way but are only emitted when a
- *     real navigation/close is attempted; arming alone does not provoke them.
- * -------------------------------------------------------------------------- */

package/src/tools/emulation.ts

@@ -1,212 +0,0 @@
-/**
- * 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.
- */