@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/args.ts

@@ -1,25 +1,208 @@
-import { type ParsedArgs } from './types.js';
+import { invalidInput } from '../errors.js';
 import { getActiveSession } from '../session-context.js';
+import { type ParsedArgs } from './types.js';
+import { assertParseableUrl, assertScrollDestination, assertSweepBounds, parsePositiveNumber, parseDoAction, type SweepAxisName } from './leaf-grammar.js';
 
-// Every flag below is matched as `--flag` followed by a separate `next`
-// token (space-separated). To accept the equally-common `--flag=value` form
-// without duplicating every branch, split any `--flag=value` token into two
-// tokens up front so the rest of the parser only ever has to handle one
-// convention.
 export function expandEqualsFlags(argv: string[]): string[] {
   const out: string[] = [];
   for (const arg of argv) {
     if (arg.startsWith('--') && arg.includes('=')) {
       const eq = arg.indexOf('=');
       out.push(arg.slice(0, eq), arg.slice(eq + 1));
-    } else {
-      out.push(arg);
-    }
+    } else out.push(arg);
   }
   return out;
 }
 
-export function parseCliArgs(argv: string[]): ParsedArgs {
+const VALUE_FLAGS = new Set([
+  '--port', '--out', '--duration', '--settle', '--file', '--target', '--url', '--into', '--viewport', '--session',
+  '--filter', '--name', '--filter-url', '--filter-status', '--filter-method', '--limit', '--params', '--wait-event',
+  '--timeout', '--socket', '--settle-timeout', '--state', '--for', '--before', '--after', '--snap', '--set-file',
+  '--axis', '--from', '--to', '--viewport-height', '--rec-id', '--selector', '--do', '--element', '--prop', '--action', '--occurrence',
+]);
+
+function valueFor(flag: string, next: string | undefined): string {
+  if (next === undefined || next.startsWith('--')) throw invalidInput(`${flag} requires a value.`);
+  return next;
+}
+
+function integer(token: string, flag: string, min: number, max: number, safe = false): number {
+  // Full unsigned decimal integer grammar (leading zeros allowed); no sign,
+  // exponent, decimal point, partial token, or non-finite value.
+  if (!/^\d+$/.test(token)) throw invalidInput(`Invalid ${flag}: ${token}.`);
+  const value = Number(token);
+  if (!Number.isInteger(value) || value < min || value > max || (safe && !Number.isSafeInteger(value))) {
+    throw invalidInput(`Invalid ${flag}: ${token}.`);
+  }
+  return value;
+}
+
+function durationMs(token: string): number {
+  // Full unsigned decimal-seconds grammar (`1`, `1.`, `.5`, `00.5`); no sign,
+  // exponent, partial token, or non-finite value. Compare the decimal token
+  // before Number conversion so precision rounding cannot admit an overflow.
+  if (!/^(?:\d+\.?\d*|\.\d+)$/.test(token)) throw invalidInput(`Invalid --duration: ${token}.`);
+  const [whole = '', fraction = ''] = token.split('.');
+  const normalizedWhole = whole.replace(/^0+/, '') || '0';
+  const maxWhole = '2147483';
+  const wholeComparison = normalizedWhole.length - maxWhole.length || normalizedWhole.localeCompare(maxWhole);
+  const maxFraction = '647';
+  const fractionComparison = fraction.slice(0, maxFraction.length).padEnd(maxFraction.length, '0').localeCompare(maxFraction);
+  if (wholeComparison > 0 || (wholeComparison === 0 && (fractionComparison > 0 || (fractionComparison === 0 && /[1-9]/.test(fraction.slice(maxFraction.length)))))) {
+    throw invalidInput(`Invalid --duration: ${token}.`);
+  }
+  return Number(token) * 1000;
+}
+
+function validateKnownLeaf(command: string, positional: readonly string[]): void {
+  const leaf = positional[0];
+  if (leaf === undefined) return;
+  const branches: Record<string, readonly string[]> = {
+    session: ['start', 'stop', 'list', 'view', 'har', 'log'],
+    page: ['click', 'type', 'scroll', 'navigate', 'exec', 'shot', 'elements'],
+    tab: ['list', 'open', 'reset', 'network'],
+    measure: ['snap', 'check', 'diff', 'census', 'explain', 'sweep', 'map'],
+    motion: ['rec', 'mask', 'timeline', 'jank', 'response'],
+    lib: ['list', 'search', 'show', 'read'],
+  };
+  const known = branches[command];
+  if (known && !known.includes(leaf)) throw invalidInput(`Unknown ${command} leaf: ${leaf}.`, 'unknown_command');
+  if (command === 'measure' && leaf === 'map' && positional[1] !== undefined) {
+    const mapLeaf = positional[1];
+    if (!['focus', 'scroll', 'layers', 'ax'].includes(mapLeaf)) throw invalidInput(`Unknown measure map leaf: ${mapLeaf}.`, 'unknown_command');
+  }
+}
+
+function requireCount(values: readonly string[], min: number, max: number, command: string): void {
+  if (values.length < min || values.length > max) {
+    const expected = min === max ? `exactly ${min}` : `${min}..${max}`;
+    throw invalidInput(`${command} received ${values.length} positional argument(s); expected ${expected}.`);
+  }
+}
+
+/** Pure branch/leaf validation. It must stay before session and environment resolution. */
+export function validateCliInvocation(parsed: ParsedArgs): void {
+  validateKnownLeaf(parsed.command, parsed.positional);
+  if (parsed.help) return;
+  if (parsed.command === 'cdp') {
+    requireCount(parsed.positional, 0, 1, 'cdp');
+    if (parsed.positional.length === 0 && !parsed.waitEvent) throw invalidInput('cdp requires a method or --wait-event.');
+    if (parsed.params !== undefined) {
+      try {
+        const value = JSON.parse(parsed.params) as unknown;
+        if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('not an object');
+      } catch {
+        throw invalidInput('--params must be a JSON object.');
+      }
+    }
+    return;
+  }
+  if (parsed.positional[0] === undefined) return;
+
+  const leaf = parsed.positional[0];
+  const values = parsed.positional.slice(1);
+  if (parsed.command === 'session') {
+    const ranges: Record<string, readonly [number, number]> = {
+      start: [0, 0], stop: [1, 1], list: [0, 0], view: [1, 1], har: [0, 1], log: [1, 1],
+    };
+    const [min, max] = ranges[leaf];
+    requireCount(values, min, max, `session ${leaf}`);
+    return;
+  }
+
+  if (parsed.command === 'page') {
+    if (leaf === 'click' || leaf === 'type' || leaf === 'navigate') requireCount(values, 1, 1, `page ${leaf}`);
+    if (leaf === 'navigate') assertParseableUrl(values[0], 'URL');
+    if (leaf === 'scroll') {
+      requireCount(values, 1, 1, 'page scroll');
+      if (parsed.to === undefined) throw invalidInput('page scroll requires --to <top|bottom|px>.');
+      assertScrollDestination(parsed.to);
+    }
+    if (leaf === 'exec') requireCount(values, parsed.file === undefined ? 1 : 0, parsed.file === undefined ? 1 : 0, 'page exec');
+    if (leaf === 'shot' || leaf === 'elements') requireCount(values, 0, 0, `page ${leaf}`);
+    if (leaf === 'shot' && parsed.viewport !== undefined) {
+      const match = /^([1-9]\d*)x([1-9]\d*)$/.exec(parsed.viewport);
+      if (!match || !Number.isSafeInteger(Number(match[1])) || !Number.isSafeInteger(Number(match[2]))) {
+        throw invalidInput(`Invalid --viewport: ${parsed.viewport}.`);
+      }
+    }
+    return;
+  }
+
+  if (parsed.command === 'tab') {
+    requireCount(values, leaf === 'list' ? 0 : 1, leaf === 'list' ? 0 : 1, `tab ${leaf}`);
+    if (leaf === 'network' && values[0] !== 'offline' && values[0] !== 'online') {
+      throw invalidInput('tab network requires offline or online.');
+    }
+    return;
+  }
+
+  if (parsed.command === 'measure') {
+    if (leaf === 'snap' || leaf === 'check' || leaf === 'sweep') requireCount(values, 0, 1, `measure ${leaf}`);
+    if (leaf === 'diff' || leaf === 'census') requireCount(values, 0, 0, `measure ${leaf}`);
+    if (leaf === 'diff' && (!parsed.before || !parsed.after)) throw invalidInput('measure diff requires --before and --after.');
+    if (leaf === 'census' && !['color', 'font', 'spacing', 'radius', 'shadow', 'animation', 'geometry', 'media', 'queries'].includes(parsed.axis ?? '')) {
+      throw invalidInput('measure census requires a documented --axis value.');
+    }
+    if (leaf === 'explain') {
+      requireCount(values, 1, 1, 'measure explain');
+      if (!parsed.selector?.trim()) throw invalidInput('measure explain requires --selector.');
+    }
+    if (leaf === 'sweep') {
+      if (!['width', 'dpr', 'zoom', 'color-scheme', 'reduced-motion'].includes(parsed.axis ?? '')) {
+        throw invalidInput('measure sweep requires a documented --axis value.');
+      }
+      assertSweepBounds(parsed.axis as SweepAxisName, parsed.from, parsed.to);
+      if (parsed.viewportHeight !== undefined) parsePositiveNumber(parsed.viewportHeight, 1, '--viewport-height');
+    }
+    if (leaf === 'map') {
+      const mapLeaf = values[0];
+      if (mapLeaf === undefined) return;
+      const targets = values.slice(1);
+      requireCount(targets, mapLeaf === 'focus' || mapLeaf === 'ax' ? 1 : 0, 1, `measure map ${mapLeaf}`);
+    }
+    return;
+  }
+
+  if (parsed.command === 'motion') {
+    if (leaf === 'mask' || leaf === 'jank' || leaf === 'response') requireCount(values, 1, 1, `motion ${leaf}`);
+    if (leaf === 'timeline') {
+      requireCount(values, 1, 1, 'motion timeline');
+      if (!parsed.element?.trim()) throw invalidInput('motion timeline requires --element.');
+    }
+    if (leaf === 'rec') {
+      if (parsed.start && parsed.stop) throw invalidInput('motion rec cannot combine --start and --stop.');
+      if (!parsed.stop && parsed.recId) throw invalidInput('motion rec accepts --rec-id only with --stop.');
+      if (parsed.start || parsed.stop) {
+        requireCount(values, 0, 0, 'motion rec lifecycle');
+        if (parsed.do || parsed.duration !== undefined || (parsed.stop && parsed.viewport !== undefined)) {
+          throw invalidInput('motion rec lifecycle flags cannot be combined with one-shot flags.');
+        }
+      } else {
+        requireCount(values, 1, 1, 'motion rec');
+        if (!parsed.do) throw invalidInput('motion rec one-shot requires --do.');
+        assertParseableUrl(values[0], 'recording URL');
+        parseDoAction(parsed.do);
+      }
+      if (parsed.viewport !== undefined) {
+        const match = /^([1-9]\d*)x([1-9]\d*)$/.exec(parsed.viewport);
+        if (!match || !Number.isSafeInteger(Number(match[1])) || !Number.isSafeInteger(Number(match[2]))) {
+          throw invalidInput(`Invalid --viewport: ${parsed.viewport}.`);
+        }
+      }
+    }
+    return;
+  }
+
+  if (parsed.command === 'lib') {
+    if (leaf === 'list') requireCount(values, 0, 0, 'lib list');
+    if (leaf === 'search' || leaf === 'show') requireCount(values, 1, 1, `lib ${leaf}`);
+    if (leaf === 'read') requireCount(values, 1, Number.MAX_SAFE_INTEGER, 'lib read');
+  }
+}
+
+/** Pure syntax/provenance parsing: no session or environment reads. */
+export function parseCliSyntax(argv: string[]): ParsedArgs {
   const command = argv[0] ?? '';
   const rest = expandEqualsFlags(argv.slice(1));
   const positional: string[] = [];
@@ -28,120 +211,121 @@ export function parseCliArgs(argv: string[]): ParsedArgs {
   for (let i = 0; i < rest.length; i++) {
     const arg = rest[i];
     const next = rest[i + 1];
+    if (VALUE_FLAGS.has(arg)) valueFor(arg, next);
 
-    if (arg === '--port' && next) {
-      parsed.port = parseInt(next, 10);
-      i++;
-    } else if (arg === '--out' && next) {
-      parsed.out = next;
-      i++;
-    } else if (arg === '--json') {
-      parsed.json = true;
-    } else if (arg === '--interactive') {
-      parsed.interactive = true;
-    } else if (arg === '--har-out' && next) {
-      parsed.harOut = next;
-      i++;
-    } else if (arg === '--record') {
-      parsed.record = true;
-    } else if (arg === '--duration' && next) {
-      parsed.duration = parseInt(next, 10);
-      i++;
-    } else if (arg === '--settle' && next) {
-      parsed.settle = parseInt(next, 10);
-      i++;
-    } else if (arg === '--file' && next) {
-      parsed.file = next;
-      i++;
-    } else if (arg === '--nested') {
-      parsed.nested = true;
-    } else if (arg === '--har' && next) {
-      parsed.har = next;
-      i++;
-    } else if (arg === '--new') {
-      parsed.new = true;
-    } else if (arg === '--target' && next) {
-      parsed.target = next;
-      i++;
-    } else if (arg === '--url' && next) {
-      parsed.url = next;
-      i++;
-    } else if (arg === '--role' && next) {
-      parsed.role = next;
-      i++;
-    } else if (arg === '--into' && next) {
-      parsed.into = next;
-      i++;
-    } else if (arg === '--no-screenshot') {
-      parsed.noScreenshot = true;
-    } else if (arg === '--viewport' && next) {
-      parsed.viewport = next;
-      i++;
-    } else if (arg === '--full-page') {
-      parsed.fullPage = true;
-    } else if (arg === '--height' && next) {
-      parsed.height = parseInt(next, 10);
-      i++;
-    } else if (arg === '--filter-url' && next) {
-      parsed.filterUrl = next;
-      i++;
-    } else if (arg === '--filter-status' && next) {
-      parsed.filterStatus = next;
-      i++;
-    } else if (arg === '--filter-method' && next) {
-      parsed.filterMethod = next.toUpperCase();
-      i++;
-    } 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 === '--help' || arg === '-h') {
-      parsed.help = true;
-    } else if (arg.startsWith('--')) {
-      console.error(`Unknown flag: ${arg}`);
-      process.exit(1);
-    } else {
-      positional.push(arg);
-    }
+    if (arg === '--port') { parsed.port = integer(valueFor(arg, next), '--port', 1, 65535); i++; }
+    else if (arg === '--out') { parsed.out = valueFor(arg, next); i++; }
+    else if (arg === '--json') parsed.json = true;
+    else if (arg === '--duration') { parsed.duration = durationMs(valueFor(arg, next)); i++; }
+    else if (arg === '--settle') { parsed.settle = integer(valueFor(arg, next), '--settle', 0, 2_147_483_647); i++; }
+    else if (arg === '--file') { parsed.file = valueFor(arg, next); i++; }
+    else if (arg === '--new') parsed.new = true;
+    else if (arg === '--target') { parsed.target = valueFor(arg, next); parsed.targetSource = 'flag'; i++; }
+    else if (arg === '--url') { const value = valueFor(arg, next); parsed.url = value; (parsed.urls ??= []).push(value); i++; }
+    else if (arg === '--into') { parsed.into = valueFor(arg, next); i++; }
+    else if (arg === '--no-screenshot') parsed.noScreenshot = true;
+    else if (arg === '--viewport') { const value = valueFor(arg, next); parsed.viewport = value; (parsed.viewports ??= []).push(value); i++; }
+    else if (arg === '--full-page') parsed.fullPage = true;
+    else if (arg === '--all') parsed.all = true;
+    else if (arg === '--session') { parsed.session = valueFor(arg, next); i++; }
+    else if (arg === '--hold') parsed.hold = true;
+    else if (arg === '--filter') { parsed.filter = valueFor(arg, next); i++; }
+    else if (arg === '--name') { parsed.name = valueFor(arg, next); i++; }
+    else if (arg === '--filter-url') { parsed.filterUrl = valueFor(arg, next); i++; }
+    else if (arg === '--filter-status') { parsed.filterStatus = valueFor(arg, next); i++; }
+    else if (arg === '--filter-method') { parsed.filterMethod = valueFor(arg, next).toUpperCase(); i++; }
+    else if (arg === '--limit') { parsed.limit = integer(valueFor(arg, next), '--limit', 1, Number.MAX_SAFE_INTEGER, true); i++; }
+    else if (arg === '--browser') parsed.browser = true;
+    else if (arg === '--params') { parsed.params = valueFor(arg, next); i++; }
+    else if (arg === '--wait-event') { parsed.waitEvent = valueFor(arg, next); i++; }
+    else if (arg === '--timeout') { parsed.timeoutMs = integer(valueFor(arg, next), '--timeout', 1, 2_147_483_647); i++; }
+    else if (arg === '--socket') { parsed.socket = valueFor(arg, next); i++; }
+    else if (arg === '--freeze-animations') parsed.freezeAnimations = true;
+    else if (arg === '--settle-timeout') { parsed.settleTimeout = integer(valueFor(arg, next), '--settle-timeout', 1, 2_147_483_647); i++; }
+    else if (arg === '--capture-unsettled') parsed.captureUnsettled = true;
+    else if (arg === '--pixels') parsed.pixels = true;
+    else if (arg === '--state') { (parsed.state ??= []).push(valueFor(arg, next)); i++; }
+    else if (arg === '--for') { parsed.for = valueFor(arg, next); i++; }
+    else if (arg === '--before') { parsed.before = valueFor(arg, next); i++; }
+    else if (arg === '--after') { parsed.after = valueFor(arg, next); i++; }
+    else if (arg === '--full') parsed.full = true;
+    else if (arg === '--gate') parsed.gate = true;
+    else if (arg === '--snap') { (parsed.snap ??= []).push(valueFor(arg, next)); i++; }
+    else if (arg === '--set-file') { parsed.setFile = valueFor(arg, next); i++; }
+    else if (arg === '--axis') { parsed.axis = valueFor(arg, next); i++; }
+    else if (arg === '--from') { parsed.from = valueFor(arg, next); i++; }
+    else if (arg === '--to') { parsed.to = valueFor(arg, next); i++; }
+    else if (arg === '--viewport-height') { parsed.viewportHeight = valueFor(arg, next); i++; }
+    else if (arg === '--rec-id') { parsed.recId = valueFor(arg, next); i++; }
+    else if (arg === '--selector') { parsed.selector = valueFor(arg, 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') { parsed.do = valueFor(arg, next); i++; }
+    else if (arg === '--element') { parsed.element = valueFor(arg, next); i++; }
+    else if (arg === '--prop') { parsed.prop = valueFor(arg, next); i++; }
+    else if (arg === '--action') { parsed.action = valueFor(arg, next); i++; }
+    else if (arg === '--occurrence') { parsed.occurrence = integer(valueFor(arg, next), '--occurrence', 1, Number.MAX_SAFE_INTEGER, true); i++; }
+    else if (arg === '-h') parsed.help = true;
+    else if (arg.startsWith('--')) throw invalidInput(`Unknown flag: ${arg}.`, 'unknown_flag');
+    else positional.push(arg);
   }
 
-  // Fill gaps from environment variables (set by pipeline orchestrators)
-  if (!parsed.port && process.env.CDP_PORT) {
-    const envPort = Number.parseInt(process.env.CDP_PORT, 10);
-    if (Number.isNaN(envPort)) {
-      console.error(`Invalid CDP_PORT: ${process.env.CDP_PORT}`);
-      process.exit(1);
-    }
-    parsed.port = envPort;
-  }
-  if (!parsed.target && !parsed.url && process.env.CDP_TARGET) {
-    parsed.target = process.env.CDP_TARGET;
-  }
-  if (!parsed.har && process.env.CDP_HAR_ID) {
-    parsed.har = process.env.CDP_HAR_ID;
-  }
+  return parsed as ParsedArgs;
+}
+
+/**
+ * Decides whether an invocation needs CDP endpoint (port/target) resolution.
+ * Bare branches (`session`, `page`, ... with no leaf) and `measure map` with no
+ * sub-leaf only render help. `lib` never touches a browser. Of the `session`
+ * lifecycle leaves, only `start` connects to CDP — `stop`, `list`, `view`,
+ * `har`, and `log` finalize/read session state and must NOT parse `CDP_PORT`
+ * or read/clean the active-session index (a malformed ambient `CDP_PORT` must
+ * never block `session stop <id>` from finalizing).
+ */
+function needsEndpointResolution(parsed: ParsedArgs): boolean {
+  if (parsed.help || parsed.command === 'lib') return false;
+  const branchOnly = ['session', 'page', 'tab', 'measure', 'motion'].includes(parsed.command)
+    && (parsed.positional.length === 0 || (parsed.command === 'measure' && parsed.positional.length === 1 && parsed.positional[0] === 'map'));
+  if (branchOnly) return false;
+  if (parsed.command === 'session' && parsed.positional[0] !== 'start') return false;
+  return true;
+}
 
-  // Fill remaining gaps from active session context (explicit flags always win)
-  const session = getActiveSession();
+/**
+ * Hydrates endpoint/session defaults only after pure invocation validation
+ * succeeds. Endpoint precedence is `explicit flag > session endpoint > env`:
+ * the active session is hydrated FIRST, and the ambient `CDP_PORT` token is
+ * parsed only when neither an explicit `--port` nor a session port supplies
+ * one — so a malformed `CDP_PORT` can never reject a command whose session
+ * already holds the authoritative port.
+ */
+export function resolveCliContext(parsed: ParsedArgs): ParsedArgs {
+  if (!needsEndpointResolution(parsed)) return parsed;
+  const session = getActiveSession({ cleanStale: false });
   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;
+    if (!parsed.target && !parsed.url && session.targetId) { parsed.target = session.targetId; parsed.targetSource = 'session'; }
+    // A session target is inseparable from the endpoint that created it.
+    // Prefer that endpoint over ambient CDP_PORT, but retain an explicit
+    // --port override for deliberate multi-browser work.
+    if (parsed.port === undefined && session.port !== undefined && session.port !== null) parsed.port = session.port;
+  }
+  if (parsed.port === undefined && process.env.CDP_PORT !== undefined) {
+    parsed.port = integer(process.env.CDP_PORT, 'CDP_PORT', 1, 65535);
   }
+  // Preserve historical stale-index cleanup once endpoint validation has
+  // succeeded; only the malformed-env throw path deliberately leaves it alone.
+  if (!session) getActiveSession();
+  if (!parsed.target && !parsed.url && process.env.CDP_TARGET) { parsed.target = process.env.CDP_TARGET; parsed.targetSource = 'env'; }
+  return parsed;
+}
 
-  return parsed as ParsedArgs;
+/** Public pure parser used by command-level tests and programmatic branch callers. */
+export function parseCliArgs(argv: string[]): ParsedArgs {
+  return parseCliSyntax(argv);
 }

package/src/cdp/bridge/protocol.ts

@@ -17,7 +17,7 @@ export interface BridgeRequest {
    * domains (`Browser.*`, `Target.*`).
    */
   targetId?: string;
-  /** CDP event name to wait for (consumes the next occurrence, FIFO, buffered if it already fired). */
+  /** CDP event name to observe after this request is armed. Observation is future-only and scoped to this request's actual flattened target session (`undefined` without `targetId`); one event broadcasts to all already-armed same-key requests. */
   waitEvent?: string;
   timeoutMs?: number;
 }
@@ -36,3 +36,189 @@ 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.
+// ---------------------------------------------------------------------------
+
+/**
+ * The three-way clock baseline the design's "Recorder timing model" requires to convert
+ * screencast-frame and Tracing timestamps into the authoritative `performance.now()` domain.
+ * `performanceNowMs`/`wallClockMs` are read synchronously when the recorder arms (`rec-start`);
+ * `firstScreencastTimestampSec`/`firstTraceEventTsUs` cannot be — no frame or trace batch has
+ * necessarily arrived yet at that instant — so they are filled in opportunistically as the
+ * recorder's own screencast/tracing handlers observe the first occurrence of each, and stay
+ * `null` (with `baselinesPending: true`) until then. `rec-stop`'s response carries the same
+ * object read again at stop time — the flush path a caller uses to get the completed baselines
+ * for `markers.json` even when `rec-start`'s own response returned it still pending.
+ */
+export interface RecorderClockBaselines {
+  performanceNowMs: number;
+  wallClockMs: number;
+  /** First `Page.screencastFrame`'s `metadata.timestamp` (wall-clock seconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
+  firstScreencastTimestampSec: number | null;
+  /** First `Tracing.dataCollected` batch's earliest event `ts` (trace-clock microseconds), or `null` if none had arrived yet at the moment this snapshot was taken. */
+  firstTraceEventTsUs: number | null;
+  /** `true` while either timestamp above is still `null`. */
+  baselinesPending: boolean;
+}
+
+/**
+ * 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"`.
+ *
+ * `nonce` (here and on every other recorder request shape) is the
+ * per-recording control-socket admission token: the recorder bridge process
+ * generates it at boot (64 lowercase hex chars, 256 bits) and hands it back
+ * to its starter over a private boot file; every request line must carry it
+ * verbatim, and the server constant-time-compares it BEFORE any handler
+ * runs. There is no unauthenticated request shape and no compatibility
+ * lane — a missing or mismatched nonce is answered `ok:false error:
+ * 'unauthorized'` with no side effects.
+ */
+export interface RecStartRequest {
+  reqId: number;
+  type: 'rec-start';
+  /** Per-recording control-socket admission token — see the doc comment above. */
+  nonce: string;
+}
+
+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';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+}
+
+export interface RecStopResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'rec-stop';
+  frameCount: number;
+  eventCount: number;
+  durationMs: number;
+  /** The clock baselines re-read at stop time — the flush path for a `rec-start` response whose baselines were still pending. */
+  markers: RecorderClockBaselines;
+}
+
+/**
+ * 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). Omit `method` for a wait-event-only request;
+ * the bridge arms a future-only wait on the recorder tab websocket's
+ * unscoped event envelope and returns the matched event in one response.
+ */
+export interface RecCdpDispatchRequest {
+  reqId: number;
+  type: 'cdp';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+  method: string;
+  params?: Record<string, unknown>;
+  mark?: string;
+  waitEvent?: string;
+  timeoutMs?: number;
+}
+
+export interface RecCdpWaitEventRequest {
+  reqId: number;
+  type: 'cdp';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+  method?: undefined;
+  waitEvent: string;
+  timeoutMs?: number;
+}
+
+export type RecCdpRequest = RecCdpDispatchRequest | RecCdpWaitEventRequest;
+
+export interface RecCdpResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'cdp';
+  result?: unknown;
+  event?: unknown;
+  /**
+   * Present iff this request armed a `waitEvent` AND carried a `method`. It
+   * reports the load-wait outcome SEPARATELY from the method result: a method
+   * dispatch that succeeds is always `ok:true` with its `result` preserved,
+   * regardless of whether the paired wait observed its event
+   * (`'observed'`, with `event` set) or the wait's own bounded timer elapsed
+   * first (`'bounded-timeout'`, no `event`). A wait-event-ONLY request (no
+   * `method`) whose wait times out is still `ok:false` — that path has no
+   * method result to preserve, so its timeout is a genuine failure.
+   */
+  waitOutcome?: 'observed' | 'bounded-timeout';
+}
+
+/**
+ * The action-return HAR flush/health barrier. A recorder-routed page action
+ * (`click`, `type`, `scroll`, `exec`, `navigate`) sends this after its settle
+ * window and before claiming success, so every HAR entry/body/append the
+ * recorder's streaming collector had already completed by then is durably in
+ * the owning session's live HAR first. Deliberately NON-attributing: the
+ * response reports store health only — `ok:true` means "all work completed at
+ * request time has appended and no fatal store error is latched"; it never
+ * says which entries belong to which action and carries no counts (the
+ * collector cannot truthfully attribute concurrent traffic to one action).
+ * Once the terminal `rec-stop` latch is claimed, HAR finalization belongs to
+ * that one owner and a later `har-flush` is answered with a deterministic
+ * `ok:false` rejection instead of sharing or re-driving the drain.
+ */
+export interface RecHarFlushRequest {
+  reqId: number;
+  type: 'har-flush';
+  /** Per-recording control-socket admission token — see `RecStartRequest`. */
+  nonce: string;
+}
+
+/** Health-only: success carries no result fields beyond the envelope — see `RecHarFlushRequest`. */
+export interface RecHarFlushResponseOk {
+  reqId: number;
+  ok: true;
+  type: 'har-flush';
+}
+
+export type RecorderRequest = RecStartRequest | RecStopRequest | RecCdpRequest | RecHarFlushRequest;
+
+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 RecHarFlushResponse = RecHarFlushResponseOk | RecorderResponseErr;
+export type RecorderResponse = RecStartResponse | RecStopResponse | RecCdpResponse | RecHarFlushResponse;