@crouton-kit/capture 1.3.7 → 1.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/capture",
-  "version": "1.3.7",
+  "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

@@ -73,6 +73,8 @@ async function main(): Promise<void> {
     case "network":
     case "list":
     case "cdp":
+    case "measure":
+    case "motion":
     case "__bridge-serve":
       return cdpMain();
 
@@ -118,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

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;
@@ -108,6 +117,79 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
     } 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('--')) {
@@ -118,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)) {
@@ -134,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/protocol.ts

@@ -36,3 +36,102 @@ export interface BridgeResponseErr {
 }
 
 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

@@ -14,7 +14,7 @@
 import * as fs from 'fs';
 import * as net from 'net';
 import * as path from 'path';
-import { getBrowserClient } from '../targets.js';
+import { getBrowserClient, findTabById } from '../targets.js';
 import { type CDPClient } from '../client.js';
 import { type BridgeRequest, type BridgeResponse } from './protocol.js';
 
@@ -22,12 +22,20 @@ interface EventWaiter {
   resolve: (v: unknown) => void;
 }
 
-class EventBroker {
+/**
+ * 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: CDPClient) {}
+  constructor(private client: Pick<CDPClient, 'on'>) {}
 
   private ensureListening(eventName: string): void {
     if (this.listening.has(eventName)) return;
@@ -75,7 +83,8 @@ class EventBroker {
 }
 
 export async function runBridgeServer(socketPath: string, port?: number): Promise<void> {
-  const { client } = await getBrowserClient(await resolvePort(port));
+  const resolvedPort = await resolvePort(port);
+  const { client } = await getBrowserClient(resolvedPort);
   const events = new EventBroker(client);
 
   // Cache flattened Target.attachToTarget sessions so repeated requests
@@ -85,33 +94,20 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
   async function attach(targetId: string): Promise<string> {
     const cached = targetSessions.get(targetId);
     if (cached) return cached;
-    const result = (await client.send('Target.attachToTarget', { targetId, flatten: true })) as {
+    // 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;
   }
 
-  fs.mkdirSync(path.dirname(socketPath), { recursive: true });
-  try {
-    fs.unlinkSync(socketPath);
-  } catch {
-    // No stale socket to remove.
-  }
-
-  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);
-      }
-    });
-  });
-
   async function handleLine(line: string, socket: net.Socket): Promise<void> {
     let req: BridgeRequest;
     try {
@@ -132,23 +128,97 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     socket.write(JSON.stringify(resp) + '\n');
   }
 
+  const server = await listenNdjsonSocket(socketPath, handleLine);
+
   const cleanup = (): void => {
-    try {
-      server.close();
-    } catch {
-      // Already closed.
-    }
+    closeNdjsonSocket(server, socketPath);
     try {
       client.close();
     } catch {
       // Already closed.
     }
-    try {
-      fs.unlinkSync(socketPath);
-    } catch {
-      // Already gone.
-    }
   };
+  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);
@@ -162,14 +232,6 @@ export async function runBridgeServer(socketPath: string, port?: number): Promis
     cleanup();
     process.exit(0);
   });
-
-  await new Promise<void>((resolve, reject) => {
-    server.on('error', reject);
-    server.listen(socketPath, () => resolve());
-  });
-  // 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.
 }
 
 async function resolvePort(port?: number): Promise<number> {

package/src/cdp/bridge/spawn.ts

@@ -12,6 +12,11 @@ export function bridgeSocketPath(sessionDir: string): string {
   return path.join(sessionDir, 'bridge.sock');
 }
 
+/** The recorder bridge's own socket, scoped to its recording dir so it can't collide with a session's plain `--hold` bridge. */
+export function recorderSocketPath(recDir: string): string {
+  return path.join(recDir, 'recorder.sock');
+}
+
 export async function startBridge(
   sessionDir: string,
   port: number,
@@ -63,3 +68,60 @@ export function stopBridge(pid: number | null | undefined, socketPath: string |
     }
   }
 }
+
+/**
+ * Spawns the same detached `__bridge-serve` entrypoint in recorder mode:
+ * it connects to one tab (`targetId`) instead of the browser level, and
+ * drives `capture motion rec`'s screencast/tracing/observers instead of
+ * proxying arbitrary `--browser` CDP calls. Mirrors `startBridge()`'s
+ * spawn + "wait for the socket file to appear" pattern; the caller
+ * (U14's lifecycle routing) tears it down with the same `stopBridge()`
+ * used for the plain held bridge.
+ *
+ * Recorder mode is selected via a positional (`recorder <recDir>`) rather
+ * than a new flag — `capture`'s CLI arg parser (`src/cdp/args.ts`) is not
+ * owned by this unit, but `positional` is already generic passthrough.
+ */
+export async function startRecorderBridge(
+  socketPath: string,
+  port: number,
+  targetId: string,
+  recDir: string,
+  timeoutMs = 5000,
+): Promise<{ socketPath: string; pid: number }> {
+  const scriptPath = process.argv[1];
+  const child = spawn(
+    process.execPath,
+    [
+      scriptPath,
+      '__bridge-serve',
+      '--socket',
+      socketPath,
+      '--port',
+      String(port),
+      '--target',
+      targetId,
+      'recorder',
+      recDir,
+    ],
+    { detached: true, stdio: 'ignore' },
+  );
+  child.unref();
+  const pid = child.pid;
+  if (!pid) {
+    throw new Error('Failed to spawn recorder bridge process.');
+  }
+
+  const start = Date.now();
+  while (!fs.existsSync(socketPath)) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(
+        `Recorder bridge (pid ${pid}) did not come up within ${timeoutMs}ms. ` +
+          `Check that target "${targetId}" is reachable on port ${port}.`,
+      );
+    }
+    await new Promise((r) => setTimeout(r, 50));
+  }
+
+  return { socketPath, pid };
+}

package/src/cdp/commands/bridge-serve.ts

@@ -1,16 +1,41 @@
 import { runBridgeServer } from '../bridge/server.js';
+import { runRecorderBridge } from '../recorder-bridge.js';
 import { type ParsedArgs } from '../types.js';
 
 /**
  * Hidden entrypoint spawned detached by `capture session start --hold`
- * (see `bridge/spawn.ts`). Not documented in `capture --help` \u2014 nothing
- * calls this directly.
+ * (see `bridge/spawn.ts`'s `startBridge()`) or by `capture motion rec
+ * --start` in recorder mode (`startRecorderBridge()`). Not documented in
+ * `capture --help` — nothing calls this directly.
+ *
+ * Recorder mode is selected by a `recorder <recDir>` positional rather
+ * than a new flag, since `src/cdp/args.ts`'s fixed flag set isn't owned by
+ * this unit but `parsed.positional` is already generic passthrough:
+ *   capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>
  */
 export async function cmdBridgeServe(parsed: ParsedArgs, _args: string[]): Promise<void> {
   if (!parsed.socket) {
-    console.error('Usage: capture __bridge-serve --socket <path> [--port <cdpPort>]');
+    console.error(
+      'Usage: capture __bridge-serve --socket <path> [--port <cdpPort>] [--target <tabId> recorder <recDir>]',
+    );
     process.exit(1);
   }
+
+  if (parsed.positional[0] === 'recorder') {
+    const recDir = parsed.positional[1];
+    if (!parsed.target || !recDir) {
+      console.error(
+        'Usage: capture __bridge-serve --socket <path> --port <cdpPort> --target <tabId> recorder <recDir>',
+      );
+      process.exit(1);
+    }
+    await runRecorderBridge({ socketPath: parsed.socket, port: parsed.port, targetId: parsed.target, recDir });
+    // Deliberately does not exit: the open Unix socket server and the live
+    // tab websocket keep this detached process alive until the caller sends
+    // it SIGTERM (same teardown as the plain held bridge).
+    return;
+  }
+
   await runBridgeServer(parsed.socket, parsed.port);
   // Deliberately does not exit: the open Unix socket server and the live
   // browser websocket keep this detached process alive until `session stop`

package/src/cdp/commands/cdp.ts

@@ -14,7 +14,7 @@
 import * as fs from 'fs';
 import { getActiveSession } from '../../session-context.js';
 import { connectForCommand } from '../connection.js';
-import { getBrowserClient } from '../targets.js';
+import { getBrowserClient, findTabById } from '../targets.js';
 import { detectCdpPort } from '../detect.js';
 import { sendBridgeRequest } from '../bridge/client.js';
 import { type CDPClient } from '../client.js';
@@ -112,6 +112,14 @@ async function runBrowserScope(
     });
     if (!resp.ok) {
       console.error(`ERROR: ${resp.error}`);
+      if (!parsed.target) {
+        console.error(
+          '\nMany CDP domains (Storage.*, Page.*, DOM.*, Emulation.*, ...) are scoped to a specific ' +
+            'tab, not the browser connection as a whole \u2014 sent bare like this, Chrome often rejects them ' +
+            'with just "Internal error" and no further detail. Pass --target <tabId> to attach to the tab ' +
+            'the call should apply to (run "capture list" to find one).',
+        );
+      }
       process.exit(1);
     }
     console.log(JSON.stringify({ result: resp.result, event: resp.event }, null, 2));
@@ -129,8 +137,16 @@ async function runBrowserScope(
   try {
     let sessionId: string | undefined;
     if (parsed.target) {
+      // 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(port, parsed.target);
+      if (!tab) {
+        console.error(`ERROR: No target found for "${parsed.target}" on port ${port}. Run "capture list" to see available tabs.`);
+        process.exit(1);
+      }
       const attached = (await client.send('Target.attachToTarget', {
-        targetId: parsed.target,
+        targetId: tab.id,
         flatten: true,
       })) as { sessionId: string };
       sessionId = attached.sessionId;
@@ -139,6 +155,18 @@ async function runBrowserScope(
     const result = method ? await client.send(method, params ?? {}, 60000, sessionId) : undefined;
     const event = eventPromise ? await eventPromise : undefined;
     console.log(JSON.stringify({ result, event }, null, 2));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`ERROR: ${message}`);
+    if (!parsed.target) {
+      console.error(
+        '\nMany CDP domains (Storage.*, Page.*, DOM.*, Emulation.*, ...) are scoped to a specific ' +
+          'tab, not the browser connection as a whole \u2014 sent bare like this, Chrome often rejects them ' +
+          'with just "Internal error" and no further detail. Pass --target <tabId> to attach to the tab ' +
+          `the call should apply to (run "capture list" to find one${method ? `, e.g. capture cdp ${method} --browser --target <tabId> ...` : ''}).`,
+      );
+    }
+    process.exit(1);
   } finally {
     client.close();
   }