@crouton-kit/capture 1.3.6 → 1.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Browser automation and UI validation via CDP — session-based screenshots, HAR, a11y, click/type, and JS exec",
   "bin": {
     "capture": "./bin/capture"
@@ -33,6 +33,7 @@
     "access": "public"
   },
   "devDependencies": {
+    "@types/pngjs": "^6.0.5",
     "@types/ws": "^8.18.1",
     "esbuild": "^0.24.0",
     "tsx": "^4",
@@ -40,6 +41,8 @@
     "zod": "^4.3.5"
   },
   "dependencies": {
+    "pixelmatch": "7.2.0",
+    "pngjs": "7.0.0",
     "ws": "^8.19.0"
   }
 }

package/src/capture.ts

@@ -72,6 +72,10 @@ async function main(): Promise<void> {
     case "lib":
     case "network":
     case "list":
+    case "cdp":
+    case "measure":
+    case "motion":
+    case "__bridge-serve":
       return cdpMain();
 
     default:
@@ -116,6 +120,14 @@ INTERACTION COMMANDS (work inside or outside a session)
   exec <code>  |  exec --file <path>       Evaluate JS; expressions, return, and await are supported
   navigate <url> [--settle <ms>]           Navigate the current tab + record HAR
 
+MEASUREMENT & MOTION
+
+  measure snap|check|diff|census|explain|sweep|map    Enriched snapshot substrate + read-only queries
+  motion  rec|mask|timeline|jank|response             Recorder lifecycle + read-only queries over a finalized recording
+
+  capture measure --help                   Full leaf reference (input constraints per leaf)
+  capture motion --help                    Full leaf reference (input constraints per leaf)
+
 DIAGNOSTICS & ONE-OFFS (no session needed)
 
   detect                                   Find running CDP endpoints
@@ -126,6 +138,24 @@ DIAGNOSTICS & ONE-OFFS (no session needed)
   network <offline|online>                 Toggle connectivity for a tab
   har create | read [id] | delete <id>     Manage standalone HAR recordings
 
+RAW CDP ESCAPE HATCH
+
+  cdp <Domain.method> [--params json]      Send any CDP command capture doesn't wrap
+                      [--browser]          Target the browser connection (Browser.*, ServiceWorker.*)
+                      [--wait-event name]  Wait for a CDP event, e.g. after ServiceWorker.enable
+
+  Browser-level state (permission grants, ServiceWorker enablement) reverts
+  the instant its connection closes. session start --hold keeps ONE browser
+  connection open across commands so that state survives between them:
+
+    capture session start --url http://localhost:3000 --hold
+    capture cdp Browser.grantPermissions --browser --params '{"origin":"...","permissions":["notifications"]}'
+    capture cdp ServiceWorker.enable --browser --target <pageTabId>
+    capture cdp ServiceWorker.deliverPushMessage --browser --target <pageTabId> --params '{...}'
+    capture session stop <session-id>
+
+  capture cdp --help                       Full reference
+
 LIBRARY (vault libs — dev checkout only)
 
   lib list                                 List available libs

package/src/cdp/args.ts

@@ -64,7 +64,11 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
       parsed.target = next;
       i++;
     } else if (arg === '--url' && next) {
+      // Kept last-wins for every existing command's single-target semantics.
+      // Also accumulated into `urls` so census/sweep-style leaves can accept
+      // the flag repeated for a multi-page set without disturbing that.
       parsed.url = next;
+      (parsed.urls ??= []).push(next);
       i++;
     } else if (arg === '--role' && next) {
       parsed.role = next;
@@ -75,7 +79,12 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     } else if (arg === '--no-screenshot') {
       parsed.noScreenshot = true;
     } else if (arg === '--viewport' && next) {
+      // Kept last-wins for every existing command's single-value semantics.
+      // Also accumulated into `viewports` so check/snap/census-style leaves
+      // can accept the flag repeated for a multi-viewport sweep, mirroring
+      // the `--url` → { url, urls[] } pattern above.
       parsed.viewport = next;
+      (parsed.viewports ??= []).push(next);
       i++;
     } else if (arg === '--full-page') {
       parsed.fullPage = true;
@@ -94,6 +103,93 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     } else if (arg === '--limit' && next) {
       parsed.limit = parseInt(next, 10);
       i++;
+    } else if (arg === '--browser') {
+      parsed.browser = true;
+    } else if (arg === '--params' && next) {
+      parsed.params = next;
+      i++;
+    } else if (arg === '--wait-event' && next) {
+      parsed.waitEvent = next;
+      i++;
+    } else if (arg === '--timeout' && next) {
+      parsed.timeoutMs = parseInt(next, 10);
+      i++;
+    } else if (arg === '--socket' && next) {
+      parsed.socket = next;
+      i++;
+    } else if (arg === '--freeze-animations') {
+      parsed.freezeAnimations = true;
+    } else if (arg === '--settle-timeout' && next) {
+      parsed.settleTimeout = parseInt(next, 10);
+      i++;
+    } else if (arg === '--capture-unsettled') {
+      parsed.captureUnsettled = true;
+    } else if (arg === '--pixels') {
+      parsed.pixels = true;
+    } else if (arg === '--state' && next) {
+      (parsed.state ??= []).push(next);
+      i++;
+    } else if (arg === '--for' && next) {
+      parsed.for = next;
+      i++;
+    } else if (arg === '--before' && next) {
+      parsed.before = next;
+      i++;
+    } else if (arg === '--after' && next) {
+      parsed.after = next;
+      i++;
+    } else if (arg === '--full') {
+      parsed.full = true;
+    } else if (arg === '--gate') {
+      parsed.gate = true;
+    } else if (arg === '--snap' && next) {
+      (parsed.snap ??= []).push(next);
+      i++;
+    } else if (arg === '--set-file' && next) {
+      parsed.setFile = next;
+      i++;
+    } else if (arg === '--axis' && next) {
+      parsed.axis = next;
+      i++;
+    } else if (arg === '--from' && next) {
+      // Raw string — axis units vary (width px / dpr float / zoom); parseInt
+      // would lossily truncate a non-integer axis value.
+      parsed.from = next;
+      i++;
+    } else if (arg === '--to' && next) {
+      parsed.to = next;
+      i++;
+    } else if (arg === '--viewport-height' && next) {
+      parsed.viewportHeight = next;
+      i++;
+    } else if (arg === '--rec-id' && next) {
+      parsed.recId = next;
+      i++;
+    } else if (arg === '--selector' && next) {
+      parsed.selector = next;
+      i++;
+    } else if (arg === '--size') {
+      parsed.size = true;
+    } else if (arg === '--text') {
+      parsed.text = true;
+    } else if (arg === '--form') {
+      parsed.form = true;
+    } else if (arg === '--start') {
+      parsed.start = true;
+    } else if (arg === '--stop') {
+      parsed.stop = true;
+    } else if (arg === '--do' && next) {
+      parsed.do = next;
+      i++;
+    } else if (arg === '--element' && next) {
+      parsed.element = next;
+      i++;
+    } else if (arg === '--prop' && next) {
+      parsed.prop = next;
+      i++;
+    } else if (arg === '--action' && next) {
+      parsed.action = next;
+      i++;
     } else if (arg === '--help' || arg === '-h') {
       parsed.help = true;
     } else if (arg.startsWith('--')) {
@@ -104,7 +200,23 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     }
   }
 
-  // Fill gaps from environment variables (set by pipeline orchestrators)
+  // Fill gaps from the active session first. A session is an explicit,
+  // scoped choice the caller made (`capture session start`), so its
+  // target/har must win over ambient CDP_PORT/CDP_TARGET/CDP_HAR_ID env vars
+  // — those are meant for orchestrators only when NOT in a session (see
+  // `capture --help` TARGETING section). Letting a stale/inherited env var
+  // outrank an active session is how a command silently ends up on the
+  // wrong tab instead of the session's own.
+  const session = getActiveSession();
+  if (session) {
+    if (!parsed.har && session.harId) parsed.har = session.harId;
+    // An explicit --url picks a different (parallel) tab than the session's
+    // own — don't let the session's targetId clobber that choice.
+    if (!parsed.target && !parsed.url && session.targetId) parsed.target = session.targetId;
+  }
+
+  // Fill any still-empty gaps from environment variables (set by pipeline
+  // orchestrators that aren't using the session concept).
   if (!parsed.port && process.env.CDP_PORT) {
     const envPort = Number.parseInt(process.env.CDP_PORT, 10);
     if (Number.isNaN(envPort)) {
@@ -120,14 +232,5 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     parsed.har = process.env.CDP_HAR_ID;
   }
 
-  // Fill remaining gaps from active session context (explicit flags always win)
-  const session = getActiveSession();
-  if (session) {
-    if (!parsed.har && session.harId) parsed.har = session.harId;
-    // An explicit --url picks a different (parallel) tab than the session's
-    // own — don't let the session's targetId clobber that choice.
-    if (!parsed.target && !parsed.url && session.targetId) parsed.target = session.targetId;
-  }
-
   return parsed as ParsedArgs;
 }

package/src/cdp/bridge/client.ts

@@ -0,0 +1,49 @@
+/**
+ * Client side of the bridge protocol \u2014 used by `capture cdp --browser` to
+ * relay one request to an already-running bridge server over its socket.
+ */
+
+import * as net from 'net';
+import { type BridgeRequest, type BridgeResponse } from './protocol.js';
+
+let reqCounter = 0;
+
+export function sendBridgeRequest(
+  socketPath: string,
+  req: Omit<BridgeRequest, 'reqId'>,
+): Promise<BridgeResponse> {
+  const wireTimeoutMs = (req.timeoutMs ?? 10000) + 5000;
+  return new Promise((resolve, reject) => {
+    const reqId = ++reqCounter;
+    const socket = net.createConnection(socketPath);
+    let buffer = '';
+
+    const timer = setTimeout(() => {
+      socket.destroy();
+      reject(new Error(`Bridge request timed out after ${wireTimeoutMs}ms (socket: ${socketPath})`));
+    }, wireTimeoutMs);
+
+    socket.on('connect', () => {
+      socket.write(JSON.stringify({ ...req, reqId } satisfies BridgeRequest) + '\n');
+    });
+
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf-8');
+      const idx = buffer.indexOf('\n');
+      if (idx < 0) return;
+      clearTimeout(timer);
+      const line = buffer.slice(0, idx);
+      socket.end();
+      try {
+        resolve(JSON.parse(line) as BridgeResponse);
+      } catch (err) {
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+
+    socket.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}

package/src/cdp/bridge/protocol.ts

@@ -0,0 +1,137 @@
+/**
+ * Wire protocol between `capture cdp --browser` and the held bridge process
+ * (`capture __bridge-serve`). Newline-delimited JSON over a Unix domain
+ * socket — one request per connection, one response, then the socket closes.
+ */
+
+export interface BridgeRequest {
+  reqId: number;
+  /** CDP method, e.g. "Browser.grantPermissions". Omit when only waiting for an event. */
+  method?: string;
+  params?: Record<string, unknown>;
+  /**
+   * Target (page or worker) to scope this call to, via a flattened
+   * `Target.attachToTarget` session on the SAME held browser websocket.
+   * Required for domains that live on a target rather than the browser
+   * itself (`ServiceWorker.*`, `Page.*`, ...) — omit for pure browser-level
+   * domains (`Browser.*`, `Target.*`).
+   */
+  targetId?: string;
+  /** CDP event name to wait for (consumes the next occurrence, FIFO, buffered if it already fired). */
+  waitEvent?: string;
+  timeoutMs?: number;
+}
+
+export interface BridgeResponseOk {
+  reqId: number;
+  ok: true;
+  result?: unknown;
+  event?: unknown;
+}
+
+export interface BridgeResponseErr {
+  reqId: number;
+  ok: false;
+  error: string;
+}
+
+export type BridgeResponse = BridgeResponseOk | BridgeResponseErr;
+
+// ---------------------------------------------------------------------------
+// Recorder-mode protocol — the SAME NDJSON-over-unix-socket wire format as
+// above, specialized for `capture motion rec` (see ../recorder-bridge.ts).
+// The generic `BridgeRequest`/`BridgeResponse` are unchanged and still
+// govern `capture cdp --browser` / `session start --hold`; a recorder-mode
+// bridge process (spawned in recorder mode, see ../bridge/spawn.ts) speaks
+// this union instead, one request per connection, one response, same as
+// the plain bridge.
+// ---------------------------------------------------------------------------
+
+/** One synchronized (performance.now, wall-clock) pair, captured when the recorder arms. */
+export interface RecorderClockBaselines {
+  performanceNowMs: number;
+  wallClockMs: number;
+}
+
+/**
+ * Arms the recorder on its held tab connection: enables the motion-rec CDP
+ * domains, starts `Page.startScreencast` + `Tracing`, injects the
+ * Mutation/Resize/Performance observers, and captures the clock baseline.
+ * A recorder process only accepts one `rec-start` while `state==="idle"`.
+ */
+export interface RecStartRequest {
+  reqId: number;
+  type: 'rec-start';
+}
+
+export interface RecStartResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'rec-start';
+  /** Returned for the caller to persist into `markers.json` — the recorder itself does not write that file. */
+  markers: RecorderClockBaselines;
+}
+
+/**
+ * Stops screencast + tracing, flushes the injected observers, and tears
+ * down the recorder's subscriptions (not the socket — the caller closes
+ * the bridge process once it has read the response). Returns counts for
+ * the caller's `meta.json`; the recorder itself does not write that file.
+ */
+export interface RecStopRequest {
+  reqId: number;
+  type: 'rec-stop';
+}
+
+export interface RecStopResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'rec-stop';
+  frameCount: number;
+  eventCount: number;
+  durationMs: number;
+}
+
+/**
+ * A CDP request routed through the recorder's held tab connection — the
+ * mechanism intervening session commands (`click`, `type`, `navigate`, ...)
+ * use during a composed recording. Setting `mark` brackets the dispatch
+ * with two performance.now() reads taken in the page's execution context
+ * (`../timing.ts`'s `withDocumentPerformanceNow`) and appends a labeled
+ * input-landmark record to `events.jsonl`, tying the action to the frame
+ * timeline — this is the "marked CDP request message" the protocol
+ * supports. Omit `mark` for a plain passthrough call (still observed
+ * natively by the recorder's own event subscriptions, just not logged as a
+ * distinct input landmark).
+ */
+export interface RecCdpRequest {
+  reqId: number;
+  type: 'cdp';
+  method: string;
+  params?: Record<string, unknown>;
+  mark?: string;
+  waitEvent?: string;
+  timeoutMs?: number;
+}
+
+export interface RecCdpResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'cdp';
+  result?: unknown;
+  event?: unknown;
+}
+
+export type RecorderRequest = RecStartRequest | RecStopRequest | RecCdpRequest;
+
+export interface RecorderResponseErr {
+  reqId: number;
+  ok: false;
+  type: RecorderRequest['type'];
+  error: string;
+}
+
+export type RecStartResponse = RecStartResponseOk | RecorderResponseErr;
+export type RecStopResponse = RecStopResponseOk | RecorderResponseErr;
+export type RecCdpResponse = RecCdpResponseOk | RecorderResponseErr;
+export type RecorderResponse = RecStartResponse | RecStopResponse | RecCdpResponse;

package/src/cdp/bridge/server.ts

@@ -0,0 +1,241 @@
+/**
+ * The bridge server: holds ONE browser-level CDP connection open for the
+ * lifetime of a held session and exposes it to (many, sequential) `capture
+ * cdp --browser` invocations over a Unix socket.
+ *
+ * Why this exists: `Browser.grantPermissions`, `ServiceWorker.enable`, and
+ * other browser-scoped CDP state are per-CLIENT and revert the instant the
+ * granting websocket disconnects. `capture` normally opens/closes a fresh
+ * websocket per command, so that state was gone by the next command. Running
+ * this as a long-lived detached process is what keeps ONE websocket (and
+ * therefore that state) alive across many separate `capture` invocations.
+ */
+
+import * as fs from 'fs';
+import * as net from 'net';
+import * as path from 'path';
+import { getBrowserClient, findTabById } from '../targets.js';
+import { type CDPClient } from '../client.js';
+import { type BridgeRequest, type BridgeResponse } from './protocol.js';
+
+interface EventWaiter {
+  resolve: (v: unknown) => void;
+}
+
+/**
+ * Buffers CDP events by name and resolves `wait()` callers FIFO, either
+ * immediately (from the buffer) or when the next matching event arrives.
+ * Shared by the plain browser-level bridge and the recorder bridge
+ * (`../recorder-bridge.ts`) — both hold one long-lived `CDPClient` and need
+ * the same "consume the next occurrence of this event" primitive for
+ * `waitEvent`-bearing requests.
+ */
+export class EventBroker {
+  private queues = new Map<string, unknown[]>();
+  private waiters = new Map<string, EventWaiter[]>();
+  private listening = new Set<string>();
+
+  constructor(private client: Pick<CDPClient, 'on'>) {}
+
+  private ensureListening(eventName: string): void {
+    if (this.listening.has(eventName)) return;
+    this.listening.add(eventName);
+    this.client.on(eventName, (params) => {
+      const waiters = this.waiters.get(eventName);
+      if (waiters && waiters.length > 0) {
+        waiters.shift()!.resolve(params);
+        return;
+      }
+      const q = this.queues.get(eventName) ?? [];
+      q.push(params);
+      // Cap the buffer so an event nobody ever asks for can't leak memory.
+      if (q.length > 50) q.shift();
+      this.queues.set(eventName, q);
+    });
+  }
+
+  wait(eventName: string, timeoutMs: number): Promise<unknown> {
+    this.ensureListening(eventName);
+    const q = this.queues.get(eventName);
+    if (q && q.length > 0) {
+      return Promise.resolve(q.shift());
+    }
+    return new Promise((resolve, reject) => {
+      const list = this.waiters.get(eventName) ?? [];
+      const entry: EventWaiter = {
+        resolve: (v) => {
+          clearTimeout(timer);
+          resolve(v);
+        },
+      };
+      const timer = setTimeout(() => {
+        const current = this.waiters.get(eventName);
+        if (current) {
+          const idx = current.indexOf(entry);
+          if (idx >= 0) current.splice(idx, 1);
+        }
+        reject(new Error(`Timed out after ${timeoutMs}ms waiting for event "${eventName}"`));
+      }, timeoutMs);
+      list.push(entry);
+      this.waiters.set(eventName, list);
+    });
+  }
+}
+
+export async function runBridgeServer(socketPath: string, port?: number): Promise<void> {
+  const resolvedPort = await resolvePort(port);
+  const { client } = await getBrowserClient(resolvedPort);
+  const events = new EventBroker(client);
+
+  // Cache flattened Target.attachToTarget sessions so repeated requests
+  // against the same target (e.g. ServiceWorker.enable then
+  // ServiceWorker.deliverPushMessage) reuse one attach instead of piling up.
+  const targetSessions = new Map<string, string>();
+  async function attach(targetId: string): Promise<string> {
+    const cached = targetSessions.get(targetId);
+    if (cached) return cached;
+    // Accept the same 8-char-prefix targeting every other capture command
+    // promises (see the top-level --help TARGETING section) instead of
+    // requiring the full 32-char target id here.
+    const tab = await findTabById(resolvedPort, targetId);
+    if (!tab) {
+      throw new Error(`No target found for "${targetId}" on port ${resolvedPort}. Run "capture list" to see available tabs.`);
+    }
+    const result = (await client.send('Target.attachToTarget', { targetId: tab.id, flatten: true })) as {
+      sessionId: string;
+    };
+    targetSessions.set(targetId, result.sessionId);
+    return result.sessionId;
+  }
+
+  async function handleLine(line: string, socket: net.Socket): Promise<void> {
+    let req: BridgeRequest;
+    try {
+      req = JSON.parse(line);
+    } catch {
+      return;
+    }
+    let resp: BridgeResponse;
+    try {
+      const sessionId = req.targetId ? await attach(req.targetId) : undefined;
+      const eventPromise = req.waitEvent ? events.wait(req.waitEvent, req.timeoutMs ?? 10000) : undefined;
+      const result = req.method ? await client.send(req.method, req.params ?? {}, 60000, sessionId) : undefined;
+      const event = eventPromise ? await eventPromise : undefined;
+      resp = { reqId: req.reqId, ok: true, result, event };
+    } catch (err) {
+      resp = { reqId: req.reqId, ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+    socket.write(JSON.stringify(resp) + '\n');
+  }
+
+  const server = await listenNdjsonSocket(socketPath, handleLine);
+
+  const cleanup = (): void => {
+    closeNdjsonSocket(server, socketPath);
+    try {
+      client.close();
+    } catch {
+      // Already closed.
+    }
+  };
+  installProcessCleanup(cleanup, client);
+  // Intentionally does not resolve further work here: the open server and
+  // the live websocket keep the event loop (and this detached process) alive
+  // until `stopBridge()` sends SIGTERM.
+}
+
+/**
+ * Ensures `socketPath`'s parent directory exists and removes any stale
+ * socket file left at that path (a previous bridge process that died
+ * without cleaning up). Shared preparation step before binding a new
+ * `net.Server` there.
+ */
+export function prepareSocketPath(socketPath: string): void {
+  fs.mkdirSync(path.dirname(socketPath), { recursive: true });
+  try {
+    fs.unlinkSync(socketPath);
+  } catch {
+    // No stale socket to remove.
+  }
+}
+
+/**
+ * Binds a Unix-domain `net.Server` at `socketPath` that frames each
+ * connection's input as newline-delimited JSON, invoking `handleLine` once
+ * per complete line. This is the wire framing every bridge mode (plain
+ * browser-level bridge, recorder bridge) shares — "one request per
+ * connection, one response, then the socket closes" is a convention the
+ * caller's `handleLine` implements by writing exactly one response per
+ * line and letting the client end the connection; the server itself is
+ * agnostic to that convention and would happily frame a connection that
+ * sends multiple lines.
+ */
+export async function listenNdjsonSocket(
+  socketPath: string,
+  handleLine: (line: string, socket: net.Socket) => void | Promise<void>,
+): Promise<net.Server> {
+  prepareSocketPath(socketPath);
+
+  const server = net.createServer((socket) => {
+    let buffer = '';
+    socket.on('data', (chunk) => {
+      buffer += chunk.toString('utf-8');
+      let idx: number;
+      while ((idx = buffer.indexOf('\n')) >= 0) {
+        const line = buffer.slice(0, idx);
+        buffer = buffer.slice(idx + 1);
+        if (line.trim()) void handleLine(line, socket);
+      }
+    });
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(socketPath, () => resolve());
+  });
+  return server;
+}
+
+/** Closes the socket server and best-effort unlinks the socket file. */
+export function closeNdjsonSocket(server: net.Server, socketPath: string): void {
+  try {
+    server.close();
+  } catch {
+    // Already closed.
+  }
+  try {
+    fs.unlinkSync(socketPath);
+  } catch {
+    // Already gone.
+  }
+}
+
+/**
+ * Wires SIGTERM/SIGINT and the held client's disconnect into one `cleanup`
+ * call followed by `process.exit(0)` — the shutdown sequence every
+ * detached bridge process (plain or recorder) uses.
+ */
+export function installProcessCleanup(
+  cleanup: () => void,
+  client: Pick<CDPClient, 'onDisconnect'>,
+): void {
+  process.on('SIGTERM', () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on('SIGINT', () => {
+    cleanup();
+    process.exit(0);
+  });
+  client.onDisconnect(() => {
+    // The browser (or its CDP endpoint) went away — nothing left to bridge.
+    cleanup();
+    process.exit(0);
+  });
+}
+
+async function resolvePort(port?: number): Promise<number> {
+  if (port) return port;
+  const { detectCdpPort } = await import('../detect.js');
+  return detectCdpPort();
+}