cdp-toolkit 1.1.0 → 1.4.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.
  */