@crouton-kit/capture 1.4.2 → 1.4.10

package/src/cdp/commands/perf/trace.ts

@@ -0,0 +1,235 @@
+import * as crypto from 'node:crypto';
+import * as path from 'node:path';
+import { type ParsedArgs } from '../../types.js';
+import { detectCdpPort } from '../../detect.js';
+import { openTab } from '../../targets.js';
+import { collectorHostSocketPath, startCollectorHost } from '../../bridge/spawn.js';
+import { sendHostRequest, type HostResponse } from '../../host/client.js';
+import { scanCollectorHost, type CollectorHostHandle } from '../../host/handle.js';
+import { stopAndReapCollectorHostAtSessionStop } from '../../host/lifecycle.js';
+import { resolveTraceRef } from '../../../output/artifact.js';
+import { emitResult, fact, formatArtifactList, type RenderableResult } from '../../../output/render.js';
+import { CAPTURE_ROOT, ensurePrivateDir, readPrivateFile, registerArtifactRoot } from '../../../session/artifacts.js';
+import { getActiveSession } from '../../../session-context.js';
+import { withSessionLifecycle } from '../../../session/coordinator.js';
+import { driveOneShotAction } from '../motion/rec.js';
+
+const HELP = `capture perf trace [url] [--do <action>] [--duration <seconds>] | --start | --stop — record a Chrome performance trace
+
+input:
+  [url]                  navigate to this URL and trace the load until it settles; without a URL the active session tab is traced in place (mutually exclusive with --start/--stop)
+  --do <action>          trace across one action on the current page (same action grammar as \`motion rec --do\`), for an interaction trace INP can be read from
+  --duration <seconds>   stop tracing this long after the action; default 3
+  --artifact-dir <path>  root for a sessionless one-shot trace bundle
+  --start                open a trace window and return; requires an active session, and the trace stays live across intervening commands until --stop
+  --stop                 close the live trace window and finalize its artifact; the session's one live trace is selected without an id. If a one-shot trace process is interrupted after it starts, the session collector host keeps this trace live; use --stop to finalize it (or session collectors to read its id/state)
+output: <trace …> — the finalized trace artifact, its recorded window, event count, and completion state; --json mirrors
+effects: drives the browser and records; a sessionless trace writes one bundle under --artifact-dir, then spawns or joins the session's collector host, which holds the tab connection until the trace is stopped. Claims \`tracing\`, which is browser-global: refused while \`motion rec\` or another trace is live anywhere in the browser, and the refusal names the claim and the collector holding it.`;
+
+interface TraceSummary { events: number; windowMs: number; navigations: number; categories: string; }
+interface TraceArtifact { id: string; dir: string; completion: string; reason?: string; summary: TraceSummary; }
+
+function commandError(parsed: ParsedArgs, status: string, message: string): void {
+  const held = /^Claim "([^"]+)" is held by (collector|reservation) (.+)\.$/.exec(message);
+  const result: RenderableResult = held
+    ? {
+      tag: 'error',
+      attrs: { command: 'perf trace', code: 'claim_held', claim: held[1], holder: `${held[2]} ${held[3]}` },
+      summary: fact`received: perf trace\nexpected: no live collector holding the ${held[1]} claim\nholder: ${held[2]} ${held[3]}`,
+      followUp: fact`Run \`capture session collectors\` to see the live roster, stop the holder, then re-issue.`,
+    }
+    : { tag: 'error', attrs: { command: 'perf trace', status }, summary: fact`${message}` };
+  emitResult(result, { json: parsed.json });
+  process.exitCode = 1;
+}
+
+function summaryFromMeta(dir: string, id: string): TraceArtifact {
+  const resolved = resolveTraceRef(dir);
+  const meta = JSON.parse(readPrivateFile(path.join(dir, 'meta.json')).toString('utf8')) as Record<string, unknown>;
+  const summary = (meta.summary && typeof meta.summary === 'object' ? meta.summary : meta) as Record<string, unknown>;
+  return {
+    id,
+    dir,
+    completion: resolved.completion,
+    ...(resolved.reason ? { reason: resolved.reason } : {}),
+    summary: {
+      events: typeof summary.events === 'number' ? summary.events : 0,
+      windowMs: typeof summary.windowMs === 'number' ? summary.windowMs : 0,
+      navigations: typeof summary.navigations === 'number' ? summary.navigations : 0,
+      categories: typeof summary.categories === 'string' ? summary.categories : 'devtools-default',
+    },
+  };
+}
+
+function emitTrace(parsed: ParsedArgs, artifact: TraceArtifact): void {
+  const result: RenderableResult = {
+    tag: 'trace',
+    attestation: { kind: 'trace', id: artifact.id, path: artifact.dir },
+    attrs: {
+      completion: artifact.completion,
+      events: artifact.summary.events,
+      'window-ms': artifact.summary.windowMs,
+      navigations: artifact.summary.navigations,
+      categories: artifact.summary.categories,
+      ...(artifact.reason ? { reason: artifact.reason } : {}),
+    },
+    summary: fact`Trace events are Chrome's own Tracing output at the DevTools default category set. The recording window is bounded by this command's start and stop and contains nothing from before it.`,
+    artifacts: formatArtifactList([{ name: 'trace.json' }]),
+    ...(artifact.reason ? { sections: [fact`Completion reason: ${artifact.reason}`] } : {}),
+  };
+  emitResult(result, { json: parsed.json });
+}
+
+async function ensureHost(sessionDir: string, port: number, targetId: string): Promise<CollectorHostHandle> {
+  let scanned = scanCollectorHost(sessionDir);
+  if (scanned.classification === 'unknown' || scanned.classification === 'malformed') throw new Error(`collector host is ${scanned.classification}`);
+  if (scanned.classification === 'dead') {
+    const reaped = await stopAndReapCollectorHostAtSessionStop(sessionDir);
+    if (reaped.status === 'terminal') throw new Error(reaped.error);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification === 'absent') {
+    await startCollectorHost(collectorHostSocketPath(sessionDir), port, targetId, sessionDir);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification !== 'live' || !scanned.handle) throw new Error('collector host did not publish a live handle');
+  if (scanned.handle.targetId !== targetId) throw new Error('collector host is bound to a different target; stop the active collector before tracing this tab');
+  return scanned.handle;
+}
+
+async function startTrace(host: CollectorHostHandle): Promise<{ id: string; dir: string }> {
+  const response = await sendHostRequest(host.socketPath, { type: 'collector-start', nonce: host.nonce, kind: 'trace', config: {} }, 30_000);
+  if (!response.ok || !response.collector || typeof response.collector !== 'object') throw new Error(response.error ?? 'collector host refused to start trace');
+  const collector = response.collector as { id?: unknown; dir?: unknown };
+  if (typeof collector.id !== 'string' || typeof collector.dir !== 'string') throw new Error('collector host returned a malformed trace collector');
+  return { id: collector.id, dir: collector.dir };
+}
+
+async function stopTrace(host: CollectorHostHandle, id: string, dir: string): Promise<TraceArtifact> {
+  const response = await sendHostRequest(host.socketPath, { type: 'collector-stop', nonce: host.nonce, id }, 45_000);
+  if (!response.ok) throw new Error(response.error ?? 'collector host refused to stop trace');
+  return summaryFromMeta(dir, id);
+}
+
+function hostCdp(host: CollectorHostHandle) {
+  return async (method: string, params: Record<string, unknown> = {}, annotation?: string): Promise<Record<string, unknown>> => {
+    const response = await sendHostRequest(host.socketPath, { type: 'cdp', nonce: host.nonce, method, params, ...(annotation ? { annotation } : {}) }, 30_000);
+    if (!response.ok) throw new Error(response.error ?? `host CDP call ${method} failed`);
+    const { reqId: _reqId, ok: _ok, type: _type, error: _error, ...result } = response;
+    return result;
+  };
+}
+
+async function waitForDocument(host: CollectorHostHandle): Promise<void> {
+  const cdp = hostCdp(host);
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    const response = await cdp('Runtime.evaluate', { expression: 'document.readyState', returnByValue: true });
+    const state = (response.result as { value?: unknown } | undefined)?.value;
+    if (state === 'complete') return;
+    await new Promise(resolve => setTimeout(resolve, 50));
+  }
+  throw new Error('timed out waiting for the traced document to finish loading');
+}
+
+async function drive(host: CollectorHostHandle, url: string | undefined, action: string | undefined, durationMs: number): Promise<void> {
+  const cdp = hostCdp(host);
+  if (url) {
+    await cdp('Page.enable');
+    await cdp('Page.navigate', { url });
+    await waitForDocument(host);
+  }
+  if (action) {
+    await driveOneShotAction({
+      async handleCdp(request: { method: string; params?: Record<string, unknown>; mark?: string }) {
+        return { result: await cdp(request.method, request.params ?? {}, request.mark) };
+      },
+    }, action);
+  }
+  await new Promise(resolve => setTimeout(resolve, durationMs));
+}
+
+function oneShotDir(artifactDir?: string): string {
+  const dir = path.join(artifactDir === undefined ? CAPTURE_ROOT : registerArtifactRoot(artifactDir), `oneshot-${Date.now().toString(36)}-${crypto.randomBytes(4).toString('hex')}`);
+  ensurePrivateDir(path.join(dir, 'perf', 'traces'));
+  return dir;
+}
+
+async function handleStart(parsed: ParsedArgs): Promise<void> {
+  const session = getActiveSession();
+  if (!session?.targetId || session.port === undefined || session.port === null) return commandError(parsed, 'no_active_session', 'perf trace --start requires an active session with a target and CDP port.');
+  try {
+    const started = await withSessionLifecycle(session.dir, async () => startTrace(await ensureHost(session.dir, session.port!, session.targetId!)));
+    emitResult({
+      tag: 'trace',
+      attestation: { kind: 'trace', id: started.id, path: started.dir },
+      attrs: { completion: 'live', categories: 'devtools-default' },
+      summary: fact`Trace window is live on the session tab. It contains events after this command until \`capture perf trace --stop\`.`,
+    }, { json: parsed.json });
+  } catch (error) { commandError(parsed, 'start_failed', error instanceof Error ? error.message : String(error)); }
+}
+
+async function handleStop(parsed: ParsedArgs): Promise<void> {
+  const session = getActiveSession();
+  if (!session) return commandError(parsed, 'no_active_session', 'perf trace --stop requires an active session.');
+  try {
+    const artifact = await withSessionLifecycle(session.dir, async () => {
+      const scanned = scanCollectorHost(session.dir);
+      if (scanned.classification !== 'live' || !scanned.handle) throw new Error(`no live collector host (${scanned.classification})`);
+      const trace = scanned.handle.collectors.find(collector => collector.kind === 'trace');
+      if (!trace) throw new Error('no live trace collector exists in this session');
+      return stopTrace(scanned.handle, trace.id, trace.dir);
+    });
+    emitTrace(parsed, artifact);
+  } catch (error) { commandError(parsed, 'stop_failed', error instanceof Error ? error.message : String(error)); }
+}
+
+async function handleOneShot(parsed: ParsedArgs): Promise<void> {
+  const active = getActiveSession();
+  const url = parsed.positional[0];
+  const durationMs = parsed.duration ?? 3_000;
+  if (!Number.isFinite(durationMs) || durationMs < 0) return commandError(parsed, 'invalid_duration', '--duration must be a non-negative number of seconds.');
+  if (!active?.targetId && !url) return commandError(parsed, 'no_session_target', 'perf trace without a URL requires an active session tab.');
+  let host: CollectorHostHandle | undefined;
+  let started: { id: string; dir: string } | undefined;
+  try {
+    const port = active?.port ?? parsed.port ?? await detectCdpPort();
+    const sessionDir = active?.dir ?? oneShotDir(parsed.artifactDir);
+    const targetId = active?.targetId ?? (await openTab(port, 'about:blank')).id;
+    const run = async (): Promise<TraceArtifact> => {
+      host = await ensureHost(sessionDir, port, targetId);
+      started = await startTrace(host);
+      await drive(host, url, parsed.do, durationMs);
+      return stopTrace(host, started.id, started.dir);
+    };
+    const artifact = active ? await withSessionLifecycle(sessionDir, run) : await run();
+    emitTrace(parsed, artifact);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    // An active session owns the host durably, so a later --stop can observe
+    // and finalize its trace. A sessionless one-shot has no such recovery
+    // surface; stop its trace before reporting the failed command.
+    if (host && started && !active) {
+      try {
+        await stopTrace(host, started.id, started.dir);
+      } catch (cleanupError) {
+        const cleanupDetail = cleanupError instanceof Error ? cleanupError.message : String(cleanupError);
+        commandError(parsed, 'trace_failed', `${detail}. Trace cleanup also failed: ${cleanupDetail}`);
+        return;
+      }
+    }
+    const recovery = host && started && active
+      ? `${detail}. Trace ${started.id} remains live at ${started.dir}; finalize it with \`capture perf trace --stop\` (or inspect \`capture session collectors\`).`
+      : detail;
+    commandError(parsed, 'trace_failed', recovery);
+  }
+}
+
+export async function cmdPerfTrace(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) { console.log(HELP); return; }
+  if (parsed.start) return handleStart(parsed);
+  if (parsed.stop) return handleStop(parsed);
+  return handleOneShot(parsed);
+}
+
+export { HELP as PERF_TRACE_HELP, resolveTraceRef };

package/src/cdp/commands/perf/vitals.ts

@@ -0,0 +1,76 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { type ParsedArgs } from '../../types.js';
+import { analyzeChromeTrace, type MetricProvenance, type TraceInsightSet } from '../../trace-analysis.js';
+import { resolveTraceRef } from '../../../output/artifact.js';
+import { emitResult, fact, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+
+const HELP = `capture perf vitals <trace> — Core Web Vitals measured from a recorded trace
+
+input:
+  <trace>   trace id in the active session or an absolute trace path (required; the trace must be finalized)
+output: <vitals …> — LCP with its ttfb/load-delay/load-duration/render-delay subparts and element attribution, INP with its input-delay/main-thread-handling/presentation breakdown, and CLS with its session-window clusters and per-cluster culprits, one set per navigation in the trace; a metric with no occurrence in the recording reports not-observed, never 0, and a subpart the engine did not attribute is omitted rather than shown as 0; --json mirrors
+effects: read-only — reads the finalized trace artifact, never drives the browser`;
+
+function error(parsed: ParsedArgs, status: string, message: string): void {
+  emitResult({ tag: 'error', attrs: { command: 'perf vitals', status }, summary: fact`${message}` }, { json: parsed.json });
+  process.exitCode = 1;
+}
+
+function provenanceLines(provenance: MetricProvenance): FactLine[] {
+  return provenance.limitations.map(limit => fact`${limit}`);
+}
+
+function lcpLine(set: TraceInsightSet): FactLine[] {
+  const value = set.metrics.lcp;
+  const scope = fact`LCP is the largest contentful paint observed in this recording window, not a real-user field percentile.`;
+  if (value.status === 'not-observed') return [fact`LCP: not-observed (${value.reason}).`, scope, ...provenanceLines(value.provenance)];
+  const parts = Object.entries(value.value.subpartsMs).map(([name, duration]) => `${name}=${duration}ms`).join(', ');
+  const attribution = value.attribution ? `; attribution ${[value.attribution.element, value.attribution.nodeId === undefined ? undefined : `node ${value.attribution.nodeId}`, value.attribution.resourceUrl].filter(Boolean).join(', ')}` : '';
+  return [fact`LCP: ${value.value.durationMs}ms${parts ? `; subparts ${parts}` : ''}${attribution}.`, scope, ...provenanceLines(value.provenance)];
+}
+
+function inpLine(set: TraceInsightSet): FactLine[] {
+  const value = set.metrics.inp;
+  const scope = fact`INP is the single longest interaction in this window, not a distribution across interactions.`;
+  if (value.status === 'not-observed') return [fact`INP: not-observed (${value.reason}).`, scope, ...provenanceLines(value.provenance)];
+  const attribution = value.attribution?.targetNodeId === undefined ? '' : `; target node ${value.attribution.targetNodeId}`;
+  return [fact`INP: ${value.value.durationMs}ms; input-delay=${value.value.inputDelayMs}ms, main-thread-handling=${value.value.mainThreadHandlingMs}ms, presentation=${value.value.presentationDelayMs}ms; interaction ${value.value.interactionType} id ${value.value.interactionId}${attribution}.`, scope, ...provenanceLines(value.provenance)];
+}
+
+function clsLine(set: TraceInsightSet): FactLine[] {
+  const value = set.metrics.cls;
+  const scope = fact`CLS is the largest session-window cluster inside this window; a shorter recording measures less shift than a longer one.`;
+  if (value.status === 'not-observed') return [fact`CLS: not-observed (${value.reason}).`, scope, ...provenanceLines(value.provenance)];
+  const clusters = value.value.clusters.map((cluster, index) => `cluster ${index + 1}: value=${cluster.value}, shifts=${cluster.shiftCount}${cluster.culprits.length ? `, culprits=${JSON.stringify(cluster.culprits)}` : ''}`);
+  return [fact`CLS: ${value.value.value}; ${clusters.join('; ')}.`, scope, ...provenanceLines(value.provenance)];
+}
+
+function section(set: TraceInsightSet): FactLine {
+  return lineList([fact`Insight set ${set.id} for ${set.url}`, ...lcpLine(set), ...inpLine(set), ...clsLine(set)]);
+}
+
+function jsonSet(set: TraceInsightSet): Record<string, unknown> {
+  return { set: set.id, url: set.url, lcp: set.metrics.lcp, inp: set.metrics.inp, cls: set.metrics.cls };
+}
+
+export async function cmdPerfVitals(parsed: ParsedArgs): Promise<void> {
+  if (parsed.help) { console.log(HELP); return; }
+  const input = parsed.positional[0];
+  if (!input) return error(parsed, 'invalid_target', 'perf vitals requires one finalized trace id or absolute trace path.');
+  try {
+    const trace = resolveTraceRef(input);
+    const raw = JSON.parse(fs.readFileSync(path.join(trace.dir, 'trace.json'), 'utf8')) as { traceEvents?: object[] };
+    if (!Array.isArray(raw.traceEvents)) throw new Error('trace.json is not a Chrome trace with a traceEvents array');
+    const analysis = await analyzeChromeTrace({ traceEvents: raw.traceEvents });
+    const result: RenderableResult = {
+      tag: 'vitals',
+      attestation: { kind: 'trace', id: trace.id, path: trace.dir },
+      attrs: { completion: trace.completion, ...(trace.reason ? { reason: trace.reason } : {}), 'insight-sets': analysis.insightSets.length, engine: analysis.source.engine, origin: 'lab' },
+      summary: fact`Core Web Vitals are trace-derived lab measurements.`,
+      sections: analysis.insightSets.length ? analysis.insightSets.map(section) : [text`No DevTools insight set was produced for this trace.`],
+      jsonSections: analysis.insightSets.map(jsonSet),
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (cause) { error(parsed, 'artifact_unavailable', cause instanceof Error ? cause.message : String(cause)); }
+}

package/src/cdp/commands/session/collectors.ts

@@ -0,0 +1,54 @@
+import * as path from 'node:path';
+import { type ParsedArgs } from '../../types.js';
+import { getActiveSession, readSessionState } from '../../../session-context.js';
+import { CAPTURE_ROOT } from '../../../session/artifacts.js';
+import { scanCollectorHost } from '../../host/handle.js';
+import { emitResult, fact, lineList, type FactLine } from '../../../output/render.js';
+
+const HELP = `capture session collectors — what is collecting in the active session right now
+
+input:
+  (none)   reads the active session's collector host; pass --session <id> to read a named live session
+output: <collectors …> — one row per live collector with its kind, id, artifact directory, held claims, and start time, plus the host's process state; an absent host is a completed no-collector observation; --json mirrors
+effects: read-only — reads the session's collector-host handle, never drives the browser`;
+
+function error(parsed: ParsedArgs, code: string, message: string): void {
+  emitResult({ tag: 'error', attrs: { command: 'session collectors', code }, summary: fact`${message}` }, { json: parsed.json });
+  process.exitCode = 1;
+}
+
+export function cmdSessionCollectors(parsed: ParsedArgs): void {
+  if (parsed.help) { console.log(HELP); return; }
+  const session = parsed.session
+    ? (() => {
+      try { return readSessionState(path.join(CAPTURE_ROOT, parsed.session!)); }
+      catch { return null; }
+    })()
+    : getActiveSession();
+  if (!session) return error(parsed, 'no_session', parsed.session ? `No readable live session named "${parsed.session}".` : 'No active capture session.');
+
+  const scanned = scanCollectorHost(session.dir);
+  const rows: FactLine[] = [];
+  if (scanned.classification === 'live' && scanned.handle) {
+    for (const collector of scanned.handle.collectors) {
+      rows.push(fact`${collector.kind} ${collector.id}: ${collector.dir}; claims ${collector.claims.join(', ') || 'none'}; started ${collector.startedAt}`);
+    }
+  }
+  if (rows.length === 0) rows.push(fact`no live collector; host state ${scanned.classification}.`);
+
+  emitResult({
+    tag: 'collectors',
+    attrs: {
+      session: session.sessionId,
+      host: scanned.classification,
+      collectors: scanned.handle?.collectors.length ?? 0,
+    },
+    summary: lineList(rows),
+    jsonSections: [{
+      session: session.sessionId,
+      host: scanned.classification,
+      collectors: scanned.handle?.collectors ?? [],
+      reservations: scanned.handle?.reservations ?? [],
+    }],
+  }, { json: parsed.json });
+}

package/src/cdp/commands/stub.ts

@@ -0,0 +1,10 @@
+import { captureError } from '../../errors.js';
+import { type ParsedArgs } from '../types.js';
+
+export function runStub(parsed: ParsedArgs, help: string, command: string): void {
+  if (parsed.help) {
+    console.log(help);
+    return;
+  }
+  throw captureError('precondition', 'not_implemented', `capture ${command} is not yet implemented.`);
+}

package/src/cdp/commands/tab/close.ts

@@ -20,7 +20,7 @@ input:
   --port <port>   CDP endpoint (default: the auto-discovered preferred endpoint)
 
 output: <tab-closed port=… target=…> — the closed tab's full target id and last observed URL.
-effects: closes exactly one page tab. Refuses unless any active session's background-tab ownership is known, and never closes that session's tab; reset or stop the session first.`;
+effects: closes exactly one page tab. Refuses unless any active session's background-tab ownership is known, and never closes that session's tab; stop the session first.`;
 
 export function buildTabClosedResult(tab: CDPTarget, port: number): RenderableResult {
   return {
@@ -82,7 +82,7 @@ export async function cmdTabClose(parsed: ParsedArgs, _args: string[]): Promise<
       throw captureError(
         'precondition',
         'active_session_target',
-        `target ${resolved.id} is the active session ${active.sessionId}'s tab; capture tab close never leaves an active session pointing at a closed target. Use capture tab reset <url> to replace it or capture session stop ${active.sessionId} first.`,
+        `target ${resolved.id} is the active session ${active.sessionId}'s tab; capture tab close never leaves an active session pointing at a closed target. Stop the session first: capture session stop ${active.sessionId}.`,
       );
     }
 

package/src/cdp/commands/tab/index.ts

@@ -17,34 +17,25 @@ import { cmdTabOpen } from './open.js';
 import { cmdTabClose } from './close.js';
 import { cmdTabReset } from './reset.js';
 import { cmdTabNetwork } from './network.js';
+import { tabMockMain } from './mock/index.js';
 
 /** Root-help representation of this branch, assembled by `src/capture.ts`. */
 export const COMMAND_BLOCK = `<command name="tab">
-browser and tab plumbing — starting/stopping a browser capture owns, endpoint/tab discovery, tab lifecycle, connection-level network emulation
-use when nothing is running yet (\`tab launch\` starts a browser capture owns and reaps), when finding a CDP endpoint or tab, opening/closing/replacing a tab, or toggling connectivity; \`tab list\` is the probe for a running browser
-  launch · quit · list · open · close · reset · network — \`capture tab -h\`
+browser and tab plumbing — the existence of a browser capture owns, endpoint/tab discovery, tab lifecycle, and the conditions the tab's network runs under (connectivity, mocked responses)
+use when starting, finding, opening, closing, or resetting a browser tab, or changing its network conditions
 </command>`;
 
-export const TAB_USAGE = `capture tab — browser and tab plumbing: browser lifecycle, discovery, tab lifecycle, network emulation.
-
-\`tab list\` with no --port performs full endpoint discovery and is the probe
-for whether a CDP-enabled browser is running at all; when nothing is running,
-\`tab launch\` starts one capture owns — never hand-roll a detached browser,
-since nothing reaps that. Capture signals only browsers it launched itself
-(verified by process-birth identity): an endpoint you reach with --port stays
-untouched. \`tab reset\` replaces a stuck tab with a fresh one; under an active
-session it refuses while a recording is active (stop it first), reaps dead
-recorder handles, and updates the session's {target, port} pair together.
-
-<subcommand name="launch" args="[--url <url>] [--port <port>] [--headed]" whenToUse="start a browser capture owns (and reaps) when none is running"/>
-<subcommand name="quit" args="[<port>] [--all]" whenToUse="stop a browser capture launched; never touches a browser capture did not start"/>
-<subcommand name="list" args="[--port <port>]" whenToUse="discover CDP endpoints and the tabs open on them"/>
-<subcommand name="open" args="<url> [--new] [--port <port>]" whenToUse="open a URL and get its tab id"/>
-<subcommand name="close" args="<target> [--port <port>]" whenToUse="close one explicitly identified background tab"/>
-<subcommand name="reset" args="<url> [--port <port>]" whenToUse="abandon a stuck tab and open a fresh one (refuses while a recording is active; reaps dead recorder handles; updates the active session's {target, port} together)"/>
-<subcommand name="network" args="<offline|online>" whenToUse="toggle connection-level network emulation for a tab"/>
-
-capture tab <leaf> -h    Per-leaf usage`;
+export const TAB_USAGE = `<command name="tab" description="browser and tab lifecycle">
+<model>Browser discovery and lifecycle, tab lifecycle, and network conditions divide these children. Capture owns and reaps only browsers it started itself; endpoints selected with --port stay untouched.</model>
+<subcommand name="launch" description="start a Capture-owned browser" whenToUse="Use when no CDP-enabled browser is running."/>
+<subcommand name="quit" description="stop a Capture-owned browser" whenToUse="Use to stop a browser that Capture launched."/>
+<subcommand name="list" description="CDP endpoints and open tabs" whenToUse="Use to find a browser endpoint or tab before targeting it."/>
+<subcommand name="open" description="open a URL in a tab" whenToUse="Use to navigate the current tab or create a tab for a URL."/>
+<subcommand name="close" description="close one tab" whenToUse="Use to close an explicitly identified background tab."/>
+<subcommand name="reset" description="replace a tab" whenToUse="Use to discard a stuck tab and update the active session to a fresh one."/>
+<subcommand name="network" description="tab network emulation" whenToUse="Use to change online connectivity for a tab held by an active session."/>
+<subcommand name="mock" description="network response mocking" whenToUse="Use to intercept the tab's requests and answer them from an ordered rule document."/>
+</command>`;
 
 export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void> {
   const leaf = parsed.positional[0];
@@ -65,6 +56,8 @@ export async function tabMain(parsed: ParsedArgs, args: string[]): Promise<void>
       return cmdTabReset(rest, args);
     case 'network':
       return cmdTabNetwork(rest, args);
+    case 'mock':
+      return tabMockMain(rest, args);
     case undefined:
       console.log(TAB_USAGE);
       return;

package/src/cdp/commands/tab/launch.ts

@@ -44,7 +44,7 @@ export function buildBrowserLaunchedResult(
       fact` (pid ${browser.pid}) is answering CDP.`,
     ),
     sections,
-    followUp: line(text`capture tab quit `, data(browser.port)),
+    followUp: line(text`capture session start --port `, data(browser.port)),
   };
 }
 

package/src/cdp/commands/tab/mock/index.ts

@@ -0,0 +1,24 @@
+import { invalidInput } from '../../../../errors.js';
+import { type ParsedArgs } from '../../../types.js';
+import { cmdTabMockStart } from './start.js';
+import { cmdTabMockStop } from './stop.js';
+
+export const MOCK_USAGE = `<command name="mock" description="network response mocking">
+<model>Mocking changes what the tab's requests do and records what it did; it is not a measurement. Rules are an ordered document, first match wins, replaced only by stopping and starting again.</model>
+<subcommand name="start" description="install a mock rule document on the tab" whenToUse="Use before the navigation or interaction whose requests you want answered from rules."/>
+<subcommand name="stop" description="remove the mock rules and finalize their record" whenToUse="Use to return the tab to real network behavior and get the record of what was mocked."/>
+</command>`;
+
+export async function tabMockMain(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+  switch (leaf) {
+    case 'start': return cmdTabMockStart(rest);
+    case 'stop': return cmdTabMockStop(rest);
+    case undefined:
+      console.log(MOCK_USAGE);
+      return;
+    default:
+      throw invalidInput(`Unknown tab mock leaf: ${leaf}.`, 'unknown_command');
+  }
+}

package/src/cdp/commands/tab/mock/lifecycle.ts

@@ -0,0 +1,88 @@
+import { captureError } from '../../../../errors.js';
+import { admitSessionOperation, withSessionLifecycle } from '../../../../session/coordinator.js';
+import { getActiveSession } from '../../../../session-context.js';
+import { collectorHostSocketPath, startCollectorHost } from '../../../bridge/spawn.js';
+import { sendHostRequest } from '../../../host/client.js';
+import { scanCollectorHost, type CollectorHostHandle } from '../../../host/handle.js';
+import { stopAndReapCollectorHostAtSessionStop } from '../../../host/lifecycle.js';
+
+interface LiveMock { id: string; dir: string; startedAt: string; }
+export interface StartedMock extends LiveMock { rules: number; targetId: string; }
+export interface StoppedMock extends LiveMock { completion: string; rules: number; paused: number; matched: number; releasedUnmatched: number; ruleMatches: number[]; }
+
+function activeSession(): NonNullable<ReturnType<typeof getActiveSession>> {
+  const session = getActiveSession();
+  if (!session) throw captureError('precondition', 'no_active_session', 'capture tab mock requires an active session with a target; start one with `capture session start --url <url>`.');
+  if (!session.targetId) throw captureError('precondition', 'session_target_missing', `session ${session.sessionId} has no target to mock; start it with a URL or reset its tab first.`);
+  return session;
+}
+
+function claimHeld(handle: CollectorHostHandle): never {
+  const holder = handle.collectors.find(collector => collector.claims.includes('fetch-interception'));
+  if (holder) throw captureError('precondition', 'claim_held', `received: capture tab mock start\nexpected: no live collector holding the \`fetch-interception\` claim\nholder: ${holder.kind} collector ${holder.id}, started ${holder.startedAt}\nNext: Run \`capture session collectors\` to see the live roster, stop the holder, then re-issue.`);
+  throw captureError('precondition', 'claim_held', 'received: capture tab mock start\nexpected: no live collector holding the `fetch-interception` claim\nNext: Run `capture session collectors` to see the live roster, stop the holder, then re-issue.');
+}
+
+async function hostForStart(sessionDir: string, targetId: string, port: number): Promise<CollectorHostHandle> {
+  let scanned = scanCollectorHost(sessionDir);
+  if (scanned.classification === 'unknown' || scanned.classification === 'malformed') throw captureError('precondition', 'collector_host_unavailable', `session collector host is ${scanned.classification}.`);
+  if (scanned.classification === 'dead') {
+    const reaped = await stopAndReapCollectorHostAtSessionStop(sessionDir);
+    if (reaped.status === 'terminal') throw captureError('cleanup', 'collector_host_reap_failed', reaped.error);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification === 'absent') {
+    await startCollectorHost(collectorHostSocketPath(sessionDir), port, targetId, sessionDir);
+    scanned = scanCollectorHost(sessionDir);
+  }
+  if (scanned.classification !== 'live' || !scanned.handle) throw captureError('world', 'collector_host_unavailable', 'collector host did not publish a live handle.');
+  if (scanned.handle.targetId !== targetId) throw captureError('precondition', 'target_mismatch', 'collector host is bound to a different session target; stop the session before changing tabs.');
+  return scanned.handle;
+}
+
+export async function startMock(rulesPath: string, rules: number): Promise<StartedMock> {
+  const session = activeSession();
+  const operation = await admitSessionOperation(session.dir);
+  try {
+    return await withSessionLifecycle(session.dir, async () => {
+      const current = activeSession();
+      if (current.dir !== session.dir) throw captureError('precondition', 'session_changed', 'the active session changed while mock startup was waiting for its lifecycle lock.');
+      if (!current.port) throw captureError('precondition', 'session_port_missing', 'active session has no CDP port for its target.');
+      const host = await hostForStart(current.dir, current.targetId!, current.port);
+      if (host.collectors.some(collector => collector.claims.includes('fetch-interception'))) claimHeld(host);
+      const response = await sendHostRequest(host.socketPath, { type: 'collector-start', nonce: host.nonce, kind: 'intercept', config: { rulesPath } }, 30_000);
+      if (!response.ok || !response.collector || typeof response.collector !== 'object') {
+        if ((response.error ?? '').includes('fetch-interception')) claimHeld(host);
+        throw captureError('world', 'mock_start_failed', response.error ?? 'collector host refused to start mock');
+      }
+      const collector = response.collector as { id?: unknown; dir?: unknown };
+      if (typeof collector.id !== 'string' || typeof collector.dir !== 'string') throw captureError('internal', 'malformed_collector_response', 'collector host returned a malformed mock collector.');
+      return { id: collector.id, dir: collector.dir, startedAt: new Date().toISOString(), rules, targetId: current.targetId! };
+    });
+  } finally {
+    await operation.release();
+  }
+}
+
+export async function stopMock(): Promise<StoppedMock> {
+  const session = activeSession();
+  const operation = await admitSessionOperation(session.dir);
+  try {
+    return await withSessionLifecycle(session.dir, async () => {
+      const current = activeSession();
+      if (current.dir !== session.dir) throw captureError('precondition', 'session_changed', 'the active session changed while mock shutdown was waiting for its lifecycle lock.');
+      const scanned = scanCollectorHost(current.dir);
+      if (scanned.classification !== 'live' || !scanned.handle) throw captureError('precondition', 'no_live_mock', `no live mock exists in this session (${scanned.classification}). Start one with \`capture tab mock start --rules <path>\`.`);
+      const row = scanned.handle.collectors.find(collector => collector.kind === 'intercept');
+      if (!row) throw captureError('precondition', 'no_live_mock', 'no live mock exists in this session. Start one with `capture tab mock start --rules <path>`.');
+      const response = await sendHostRequest(scanned.handle.socketPath, { type: 'collector-stop', nonce: scanned.handle.nonce, id: row.id }, 30_000);
+      if (!response.ok) throw captureError('world', 'mock_stop_failed', response.error ?? 'collector host refused to stop mock');
+      const summary = response.summary && typeof response.summary === 'object' && !Array.isArray(response.summary) ? response.summary as Record<string, unknown> : {};
+      const number = (name: string): number => typeof summary[name] === 'number' ? summary[name] as number : 0;
+      const ruleMatches = Array.isArray(summary.ruleMatches) && summary.ruleMatches.every(value => typeof value === 'number') ? summary.ruleMatches as number[] : [];
+      return { id: row.id, dir: row.dir, startedAt: row.startedAt, completion: typeof response.completion === 'string' ? response.completion : 'partial', rules: number('rules'), paused: number('paused'), matched: number('matched'), releasedUnmatched: number('releasedUnmatched'), ruleMatches };
+    });
+  } finally {
+    await operation.release();
+  }
+}