@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/timing.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared timing helpers for `measure`/`motion`. See the design's "Recorder timing model":
+ * the authoritative clock for every reported timestamp is `performance.now()`, relative to
+ * the recorder-armed marker (`t=0`). Screencast frames carry a wall-clock `metadata.timestamp`
+ * and Tracing events carry a monotonic `ts` in their own domains; the recorder bridge (U13/U14)
+ * converts both into the `performance.now()` domain by baseline-offset subtraction using the
+ * baseline this module reads.
+ */
+
+import type { CDPClient } from './client.js';
+
+export interface BracketedTiming<T> {
+  result: T;
+  /** `performance.now()` immediately before `fn` ran. */
+  startPerformanceNow: number;
+  /** `performance.now()` immediately after `fn` resolved. */
+  endPerformanceNow: number;
+}
+
+/**
+ * Runs `fn`, bracketed by two `performance.now()` reads taken in the page's document execution
+ * context. Used to attribute a discrete action (e.g. an `Input.dispatch*` call) to a window in
+ * the recorder's authoritative `performance.now()` clock domain. The action's landmark label
+ * (`mark`, when the caller supplied one) is recorded host-side only — appended straight to
+ * `events.jsonl` alongside these two bracket numbers (see `../recorder-bridge.ts`'s `handleCdp`)
+ * — never written into the page's own PerformanceTimeline via `performance.mark()`: that page-
+ * visible side channel was removed (a predictable, page-observable channel the injected
+ * PerformanceObserver would otherwise re-observe as its own event, in violation of the
+ * observational-collector invariant against page-side channels).
+ */
+export async function withDocumentPerformanceNow<T>(client: CDPClient, fn: () => Promise<T>): Promise<BracketedTiming<T>> {
+  const startPerformanceNow = await readPerformanceNow(client);
+  const result = await fn();
+  const endPerformanceNow = await readPerformanceNow(client);
+  return { result, startPerformanceNow, endPerformanceNow };
+}
+
+async function readPerformanceNow(client: CDPClient): Promise<number> {
+  const evaluation = (await client.send('Runtime.evaluate', {
+    expression: 'performance.now()',
+    returnByValue: true,
+  })) as { result: { value?: unknown }; exceptionDetails?: unknown };
+
+  if (evaluation.exceptionDetails) {
+    throw new Error(`Failed to read performance.now(): ${JSON.stringify(evaluation.exceptionDetails)}`);
+  }
+  if (typeof evaluation.result.value !== 'number') {
+    throw new Error('performance.now() did not return a number');
+  }
+  return evaluation.result.value;
+}
+
+export interface TraceClockBaseline {
+  /** `performance.now()` (document-relative ms) at the moment the baseline was captured. */
+  performanceNowMs: number;
+  /** `Date.now()` (wall-clock epoch ms) at the same moment. */
+  wallClockMs: number;
+}
+
+/**
+ * Reads one synchronized (`performance.now()`, wall-clock) pair from the page in a single
+ * round trip. The recorder bridge reads this once when it arms (`rec-start`) as the anchor half
+ * of the three-way `markers.json` baseline; the other two members — the first screencast frame's
+ * `metadata.timestamp` (wall-clock seconds) and the first Tracing batch's earliest event `ts`
+ * (trace-clock microseconds) — are captured separately by the recorder bridge itself as those
+ * events arrive (not by this function, since neither exists yet at arm time). Post-processing
+ * converts frame-time and trace-time into the `performance.now()` domain by subtracting this
+ * baseline's wall-clock offset.
+ */
+export async function readTraceClockBaseline(client: CDPClient): Promise<TraceClockBaseline> {
+  const evaluation = (await client.send('Runtime.evaluate', {
+    expression: '({ performanceNowMs: performance.now(), wallClockMs: Date.now() })',
+    returnByValue: true,
+  })) as {
+    result: { value?: { performanceNowMs?: unknown; wallClockMs?: unknown } };
+    exceptionDetails?: unknown;
+  };
+
+  if (evaluation.exceptionDetails) {
+    throw new Error(`Failed to read trace clock baseline: ${JSON.stringify(evaluation.exceptionDetails)}`);
+  }
+  const value = evaluation.result.value;
+  if (!value || typeof value.performanceNowMs !== 'number' || typeof value.wallClockMs !== 'number') {
+    throw new Error('Trace clock baseline evaluation did not return the expected {performanceNowMs, wallClockMs} shape');
+  }
+  return { performanceNowMs: value.performanceNowMs, wallClockMs: value.wallClockMs };
+}

package/src/cdp/types.ts

@@ -12,24 +12,37 @@ export interface ParsedArgs {
   port?: number;
   out?: string;
   json?: boolean;
-  interactive?: boolean;
-  harOut?: string;
-  record?: boolean;
   duration?: number;
   settle?: number;
   file?: string;
-  nested?: boolean;
+  /** Session-filled internal slot: NOT CLI-settable (no --har flag, no env
+   * var). Auto-filled from the active session's harId so withConnection()
+   * can auto-append recorded traffic to the session HAR. */
   har?: string;
   new?: boolean;
   target?: string;
+  /** Where `target` was assigned from: an actual `--target` flag, active-session
+   * autofill, or the ambient `CDP_TARGET` env var. Recorded at the assignment
+   * point — browser-scope CDP (`cdp --browser`) attaches a flattened target
+   * session only when this is `'flag'`; provenance is never inferred later by
+   * comparing final strings. */
+  targetSource?: 'flag' | 'session' | 'env';
   url?: string;
-  role?: string;
   into?: string;
   noScreenshot?: boolean;
   viewport?: string;
   fullPage?: boolean;
-  height?: number;
   help?: boolean;
+  /** `--all` — boolean scope-widener (per-leaf semantics). */
+  all?: boolean;
+  /** `--session <id>` — explicit session id override (per-leaf semantics). */
+  session?: string;
+  /** `session start --hold` — hold one CDP browser connection open for the session's lifetime. */
+  hold?: boolean;
+  /** `session view --filter <section>` — show only one bundle-manifest section. */
+  filter?: string;
+  /** `session log --name <label>` */
+  name?: string;
   filterUrl?: string;
   filterStatus?: string;
   filterMethod?: string;
@@ -39,4 +52,72 @@ export interface ParsedArgs {
   waitEvent?: string;
   timeoutMs?: number;
   socket?: string;
+
+  // -- measure/motion branch flags (settled in the capture measure+motion
+  // build plan's U02) -- every leaf under `capture measure`/`capture motion`
+  // parses these from the shared global parser instead of re-parsing argv
+  // itself.
+  /** `snap --freeze-animations` — pause CSS/WAAPI animation before capture. */
+  freezeAnimations?: boolean;
+  /** `snap --settle-timeout <ms>` — override the default 5000ms settle wait. */
+  settleTimeout?: number;
+  /** `snap --capture-unsettled` — write full substrate despite non-settlement. */
+  captureUnsettled?: boolean;
+  /** `snap|diff|mask --pixels` — include raster crop/diff facts. */
+  pixels?: boolean;
+  /** `snap --state <state[:selector]>` — repeatable; one entry per occurrence. */
+  state?: string[];
+  /** `check --for <list>` — comma-separated check names or categories. */
+  for?: string;
+  /** `diff --before <snap>` */
+  before?: string;
+  /** `diff --after <snap>` */
+  after?: string;
+  /** `diff --full` — expand to the complete state-matrix/per-element diff. */
+  full?: boolean;
+  /** `check|diff --gate` — exit 2 on findings/changes instead of 0. */
+  gate?: boolean;
+  /** `census --snap <id>` — repeatable; one entry per occurrence. */
+  snap?: string[];
+  /** `census --url <url>` — repeatable accumulator alongside the existing
+   * single-value `url` field above (which stays last-wins for every
+   * existing command's target-matching semantics). */
+  urls?: string[];
+  /** `census --set-file <path>` */
+  setFile?: string;
+  /** `census|sweep --axis <axis>` */
+  axis?: string;
+  /** `sweep --from <val>` — raw string; axis units vary (px/dpr/zoom). */
+  from?: string;
+  /** `sweep --to <val>` — raw string; axis units vary (px/dpr/zoom). */
+  to?: string;
+  /** `sweep --viewport-height <val>` — raw string for the viewport-height sweep axis. */
+  viewportHeight?: string;
+  /** `motion rec --stop --rec-id <id>` — explicit recording id override. */
+  recId?: string;
+  /** `check|snap|census --viewport WxH` — repeatable accumulator alongside
+   * the existing single-value `viewport` field above (last-wins, unchanged). */
+  viewports?: string[];
+  /** `explain|map focus|... --selector <sel>` */
+  selector?: string;
+  /** `explain --size` — include size/layout provenance detail. */
+  size?: boolean;
+  /** `explain --text` — include text/line-box detail. */
+  text?: boolean;
+  /** `explain --form` — include form/caret/autofill detail. */
+  form?: boolean;
+  /** `motion rec --start` — arm the composed recorder. */
+  start?: boolean;
+  /** `motion rec --stop` — finalize the composed recorder. */
+  stop?: boolean;
+  /** `motion rec --do <action>` — one-shot scripted action. */
+  do?: string;
+  /** `motion timeline --element <sel>` */
+  element?: string;
+  /** `motion timeline --prop <name>` */
+  prop?: string;
+  /** `motion response --action <action>` */
+  action?: string;
+  /** `motion response --occurrence <n>` — 1-based occurrence of a repeated action label. */
+  occurrence?: number;
 }

package/src/cdp/viewport.ts

@@ -0,0 +1,21 @@
+import { invalidInput } from '../errors.js';
+
+export interface Viewport {
+  readonly width: number;
+  readonly height: number;
+}
+
+const VIEWPORT_PATTERN = /^([1-9]\d*)x([1-9]\d*)$/;
+
+/** Parses the one viewport grammar used by every live capture command. */
+export function parseViewport(value: string): Viewport {
+  const match = VIEWPORT_PATTERN.exec(value);
+  if (match) {
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    if (Number.isSafeInteger(width) && Number.isSafeInteger(height)) {
+      return { width, height };
+    }
+  }
+  throw invalidInput(`--viewport must match <positive-safe-int>x<positive-safe-int> using lowercase x with no whitespace; received "${value}"`, 'invalid_viewport');
+}

package/src/cdp.ts

@@ -1,38 +1,16 @@
-#!/usr/bin/env tsx
 /**
- * CDP (Chrome DevTools Protocol) — browser automation via exec-first design.
+ * CDP (Chrome DevTools Protocol) — the library barrel over the CDP substrate.
  *
- * The agent writes arbitrary JS and passes it to `exec`. No training-wheel
- * commands for click/type/wait — the agent composes whatever it needs.
- *
- * Commands:
- *   capture exec <code>         Execute JS in a tab (the primary interface)
- *   capture exec --file <path>  Execute JS from file
- *   capture detect              Detect CDP port
- *   capture list                List all browser tabs
- *   capture open <url>          Open URL in browser (returns tab ID)
- *   capture reset-tab <url>    Abandon stuck tab, open fresh one
- *   capture screenshot          Capture screenshot
- *   capture a11y                Get accessibility tree
- *   capture record              Passive HAR recording
- *   capture navigate <url>      Navigate + record HAR
- *   capture har create|read|delete  Manage HAR recordings
- *
- * Options:
- *   --port <port>       Override CDP port (auto-detects if not specified)
- *   --target <tabId>    Target tab by exact ID (preferred, parallel-safe)
- *   --new               Force open a new tab (open command)
- *   --record            Enable HAR recording (exec)
- *   --har <id>          Append traffic to a HAR recording
- *   --har-out <path>    HAR output path
- *   --file <path>       Read JS from file (exec)
- *   --duration <secs>   Recording duration (record, default: 10)
- *   --settle <ms>       Settle time after navigation (navigate, default: 2000)
- *   --out <path>        Output path (screenshot)
- *   --height <px>       Override viewport height (screenshot)
- *   --full-page         Capture entire scrollable page (screenshot)
- *   --json              JSON output (a11y)
- *   --interactive       Interactive elements only (a11y)
+ * Re-exports the client, target discovery, screenshot, a11y, console-recording,
+ * and tab-lock building blocks, plus `cdpMain` (the routed command dispatch).
+ * HAR ownership is NOT exported here: the session HAR manager
+ * (`src/har-manager.ts`) fed by the internal streaming recorder
+ * (`src/cdp/har-recorder.ts`, a direct import of the recorder bridge) is the
+ * sole HAR lane.
+ * The command surface itself lives under `src/cdp/commands/` and is routed by
+ * `src/capture.ts` → `src/cdp/dispatch.ts`. This module is a pure barrel:
+ * `src/capture.ts` is the ONLY entrypoint and the ONLY error/termination
+ * boundary — nothing here executes, renders, or exits.
  */
 
 export { CDPClient } from './cdp/client.js';
@@ -42,32 +20,8 @@ export { listTargets, findTab, findTabById, openTab } from './cdp/targets.js';
 export { captureScreenshot } from './cdp/screenshot.js';
 export type { A11yNode } from './cdp/a11y.js';
 export { getAccessibilityTree } from './cdp/a11y.js';
-export { executeInBrowser } from './cdp/execute.js';
-export type { ExecuteOptions, ExecuteResult } from './cdp/execute.js';
-export { recordTraffic, navigateAndRecord, navigateAndWait } from './cdp/record.js';
-export type { RecordOptions, RecordResult, NavigateAndRecordOptions, NavigateAndRecordResult } from './cdp/record.js';
-export { HARRecorder } from './cdp/har-recorder.js';
+export { navigateAndWait } from './cdp/record.js';
 export { ConsoleRecorder } from './cdp/console-recorder.js';
 export type { ConsoleEntry } from './cdp/console-recorder.js';
 export { acquireTabLock, isTabLocked, releaseTabLock, withTabLock } from './cdp/tab-lock.js';
 export { cdpMain } from './cdp/dispatch.js';
-
-// Only run CLI when executed directly (not imported via capture.ts)
-const isMainModule =
-  process.argv[1]?.endsWith('cdp.ts') ||
-  process.argv[1]?.endsWith('cdp.mjs');
-if (isMainModule) {
-  cdpMain()
-    .then(() => {
-      // Flush stdout before exiting — process.exit() doesn't wait for stream drain
-      if (process.stdout.writableNeedDrain) {
-        process.stdout.once('drain', () => process.exit(0));
-      } else {
-        process.exit(0);
-      }
-    })
-    .catch((err) => {
-      console.error(err.message);
-      process.exit(1);
-    });
-}

package/src/command-help.ts

@@ -0,0 +1,29 @@
+/** Pure specification-help assembly from Capture's descriptor tree. */
+import { type RegistryNode } from './registry.js';
+
+const usage = (node: RegistryNode): string => `capture${node.path ? ` ${node.path}` : ''}`;
+const parameter = (name: string, grammar: string, required: boolean, variadic = false): string => `  ${required ? '<' : '['}${name}${required ? '>' : ']'}  ${grammar}${variadic ? ' (variadic)' : ''}`;
+
+/** Renders only descriptor-owned content; help never parses inputs or performs effects. */
+export function assembleHelp(node: RegistryNode): string {
+  const { help } = node;
+  const lines = [usage(node), '', help.description, '', `When to use: ${help.whenToUse}`, `Model: ${help.model ?? help.rubric}`];
+  if (help.globals) lines.push('', 'Globals:', help.globals);
+  if (help.ioContract) lines.push('', `I/O contract: ${help.ioContract}`);
+  if (node.kind === 'branch') {
+    const children = node.children.filter((child) => child.visibility === 'public');
+    if (children.length) {
+      lines.push('', 'Commands:');
+      for (const child of children) lines.push(`  ${child.path.split(' ').at(-1)}  ${child.help.description} When to use: ${child.help.whenToUse}`);
+    }
+  } else {
+    if (node.positionals.length || node.flags.length) {
+      lines.push('', 'Parameters:');
+      for (const positional of node.positionals) lines.push(parameter(positional.name, positional.grammar, positional.required, positional.variadic));
+      for (const flag of node.flags) lines.push(`  ${flag.name}${flag.grammar === 'boolean' ? '' : ` <${flag.grammar}>`}${flag.required ? ' required' : ''}${flag.repeatable ? ' repeatable' : ''}${flag.default === undefined ? '' : ` default=${flag.default}`}${flag.values ? ` values=${flag.values.join('|')}` : ''}${flag.units ? ` units=${flag.units}` : ''}`);
+    }
+    lines.push('', `Constraints: ${help.constraints}`, `Output: ${help.orderedOutput}`, `Artifact ownership: ${help.artifactOwnership}`, `Effects: browser=${node.effects.browser}, session=${node.effects.session}, artifact=${node.effects.artifact}, environment=${node.effects.environment}`, `Recovery: ${node.recovery}`);
+  }
+  lines.push('', `Next action: ${help.followUp}`);
+  return `${lines.join('\n')}\n`;
+}

package/src/command-resolution.ts

@@ -0,0 +1,22 @@
+/** Pure pre-dispatch control precedence for U15's future launcher wiring. */
+import { assembleHelp } from './command-help.js';
+import { hasHelpFlag, hasRootVersionFlag, walkCommand } from './command-walker.js';
+import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
+
+export type CommandResolution =
+  | { readonly kind: 'version' }
+  | { readonly kind: 'help'; readonly node: RegistryNode; readonly text: string }
+  | { readonly kind: 'dispatch'; readonly node: RegistryNode; readonly argv: readonly string[] }
+  | { readonly kind: 'unknown-path'; readonly received: string; readonly expected: readonly string[]; readonly path: string };
+
+/**
+ * Applies only control precedence. It deliberately does not parse leaf argv,
+ * validate `--json`, invoke a handler, or allocate any effectful dependency.
+ */
+export function resolveCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): CommandResolution {
+  if (hasRootVersionFlag(argv)) return { kind: 'version' };
+  const walked = walkCommand(argv, root);
+  if (walked.kind === 'unknown-path') return { kind: 'unknown-path', received: walked.received, expected: walked.expected, path: walked.resolved.path };
+  if (hasHelpFlag(walked.remaining)) return { kind: 'help', node: walked.node, text: assembleHelp(walked.node) };
+  return { kind: 'dispatch', node: walked.node, argv: walked.remaining };
+}

package/src/command-walker.ts

@@ -0,0 +1,35 @@
+/** Pure exact command-path resolution for the descriptor registry. */
+import { CAPTURE_REGISTRY, type RegistryBranch, type RegistryNode } from './registry.js';
+
+export type WalkResult =
+  | { readonly kind: 'resolved'; readonly node: RegistryNode; readonly remaining: readonly string[] }
+  | { readonly kind: 'unknown-path'; readonly received: string; readonly resolved: RegistryBranch; readonly expected: readonly string[]; readonly remaining: readonly string[] };
+
+/**
+ * Resolves only exact canonical path tokens. It stops before the first option,
+ * resolves the deepest known leaf/branch, and leaves all leaf argv untouched.
+ * Parsing, output compatibility, effects, and handler dispatch are intentionally
+ * outside this pure walker.
+ */
+export function walkCommand(argv: readonly string[], root: RegistryBranch = CAPTURE_REGISTRY): WalkResult {
+  let current: RegistryNode = root;
+  let index = 0;
+  while (current.kind === 'branch' && index < argv.length) {
+    const token = argv[index];
+    if (token.startsWith('-')) break;
+    const child: RegistryNode | undefined = current.children.find((candidate: RegistryNode) => candidate.path.split(' ').at(-1) === token);
+    if (!child) return { kind: 'unknown-path', received: token, resolved: current, expected: current.children.filter((candidate) => candidate.visibility === 'public').map((candidate) => candidate.path.split(' ').at(-1)!), remaining: argv.slice(index) };
+    current = child;
+    index += 1;
+  }
+  return { kind: 'resolved', node: current, remaining: argv.slice(index) };
+}
+
+export function hasHelpFlag(argv: readonly string[]): boolean {
+  return argv.includes('-h') || argv.includes('--help');
+}
+
+/** Root version is the sole accepted version spelling and wins before walking. */
+export function hasRootVersionFlag(argv: readonly string[]): boolean {
+  return argv[0] === '--version';
+}

package/src/contracts/a11y.ts

@@ -0,0 +1,33 @@
+/** Frozen retained accessibility tree contract (U1), with pure validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+export interface AxRectCoverage { readonly eligible: number; readonly attempted: number; readonly succeeded: number; readonly failed: number; readonly skipped: number; }
+/** Every retained AX node is source ordered, including ignored/unnamed nodes, and preserves evidence verbatim. */
+export interface AxTreeNode { readonly axId: string; readonly sourceOrdinal: number; readonly role?: string; readonly name?: string; readonly description?: string; readonly value?: unknown; readonly ignored: boolean; readonly cdpNodeId?: number; readonly backendNodeId?: number; readonly parentAxId?: string; readonly childAxIds: readonly string[]; readonly rect: Availability<unknown>; readonly raw: Record<string, unknown>; }
+/** Exhaustive retained store: first <=5000 source-array nodes, no semantic filtering. */
+export interface AxTreeManifest { readonly schemaVersion: 1; readonly treeId: string; readonly source: 'live' | 'snapshot'; readonly snapshotId?: string; readonly nodes: readonly AxTreeNode[]; readonly sourceTotal?: number; readonly retained: number; readonly dropped?: number; readonly droppedUnknown?: boolean; readonly rectCoverage: AxRectCoverage; readonly iframeExclusion: Availability<null>; }
+/** Sidecar meta at `<owner>/a11y/trees/<tree-id>/meta.json`; tree lifetime equals file lifetime. */
+export interface AxTreeReference { readonly schemaVersion: 1; readonly treeId: string; readonly treePath: string; readonly metaPath: string; readonly owner: string; readonly retained: number; readonly coverage: Pick<AxTreeManifest, 'sourceTotal' | 'dropped' | 'droppedUnknown' | 'rectCoverage'>; }
+export function validateAxTreeManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('a11y tree must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('a11y tree schemaVersion must be 1'));
+  if (typeof value.treeId !== 'string' || !value.treeId) errs.push(fail('a11y tree missing treeId'));
+  if (value.source !== 'live' && value.source !== 'snapshot') errs.push(fail('a11y tree source must be live or snapshot'));
+  if (!isObject(value.rectCoverage)) errs.push(fail('a11y tree missing rectCoverage'));
+  if (!isObject(value.iframeExclusion)) errs.push(fail('a11y tree missing iframeExclusion'));
+  if (!Array.isArray(value.nodes)) errs.push(fail('a11y tree requires nodes array'));
+  else {
+    if (value.nodes.length > 5000) errs.push(fail('a11y tree retains more than 5000 nodes'));
+    const ids = new Set<string>();
+    for (const node of value.nodes) {
+      if (!isObject(node) || typeof node.axId !== 'string') { errs.push(fail('a11y tree has malformed node')); continue; }
+      if (ids.has(node.axId)) errs.push(fail(`a11y tree duplicate retained AX ID: ${node.axId}`));
+      ids.add(node.axId);
+    }
+  }
+  if (typeof value.retained !== 'number') errs.push(fail('a11y tree missing retained count'));
+  else if (Array.isArray(value.nodes) && value.retained !== value.nodes.length) errs.push(fail('a11y tree retained count must equal node count'));
+  if (typeof value.sourceTotal === 'number' && typeof value.dropped === 'number' && typeof value.retained === 'number' && value.sourceTotal !== value.retained + value.dropped) errs.push(fail('a11y tree sourceTotal must equal retained + dropped'));
+  return combine(...errs);
+}

package/src/contracts/cursor.ts

@@ -0,0 +1,35 @@
+/** Frozen immutable index/cursor contract (U1), pure types/validators only. */
+import { MAX_CURSOR_BYTES, OK, ValidationResult, combine, fail, isAscii, isObject, isSha256Hex } from './primitives.js';
+
+/** Exactly the five public leaves permitted to materialize immutable cursor indexes. */
+export type CursorLeaf = 'browser detect' | 'browser list' | 'library list' | 'library search' | 'library show';
+export interface ImmutableIndex<Row = unknown> { readonly schemaVersion: 1; readonly leaf: CursorLeaf; readonly path: string; readonly digest: string; readonly createdAt: string; readonly expiresAt: string; readonly filter: Record<string, unknown>; readonly pageSize: number; readonly order: string; readonly coverage: unknown; readonly rows: readonly Row[]; }
+/** Authenticated opaque cursor claims. The serialized token itself is <=2048 ASCII bytes. */
+export interface CursorClaims { readonly schemaVersion: 1; readonly indexDigest: string; readonly leaf: CursorLeaf; readonly filter: Record<string, unknown>; readonly nextExclusiveOrdinal: number; readonly pageSize: number; readonly expiresAt: string; readonly mac: string; }
+export function validateImmutableIndex(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('immutable index must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('index schemaVersion must be 1'));
+  if (typeof value.digest !== 'string' || !isSha256Hex(value.digest)) errs.push(fail('index digest must be lowercase SHA-256 hex'));
+  if (!Array.isArray(value.rows)) errs.push(fail('index requires rows array'));
+  if (!(typeof value.pageSize === 'number' && value.pageSize >= 1 && value.pageSize <= 20)) errs.push(fail('index pageSize must be 1..20'));
+  return combine(...errs);
+}
+export function validateCursorToken(token: string): ValidationResult {
+  if (!isAscii(token)) return fail('cursor must be ASCII');
+  if (Buffer.byteLength(token, 'ascii') > MAX_CURSOR_BYTES) return fail(`cursor exceeds ${MAX_CURSOR_BYTES} ASCII bytes`);
+  return OK;
+}
+export function validateCursorClaims(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('cursor claims must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('cursor schemaVersion must be 1'));
+  if (typeof value.indexDigest !== 'string' || !isSha256Hex(value.indexDigest)) errs.push(fail('cursor missing valid indexDigest'));
+  if (!['browser detect', 'browser list', 'library list', 'library search', 'library show'].includes(value.leaf as string)) errs.push(fail('cursor has invalid leaf'));
+  if (!isObject(value.filter)) errs.push(fail('cursor missing filter object'));
+  if (typeof value.expiresAt !== 'string' || Number.isNaN(Date.parse(value.expiresAt))) errs.push(fail('cursor missing valid expiresAt'));
+  if (!(typeof value.nextExclusiveOrdinal === 'number' && Number.isSafeInteger(value.nextExclusiveOrdinal) && value.nextExclusiveOrdinal >= 0)) errs.push(fail('cursor nextExclusiveOrdinal must be nonnegative safe integer'));
+  if (!(typeof value.pageSize === 'number' && value.pageSize >= 1 && value.pageSize <= 20)) errs.push(fail('cursor pageSize must be 1..20'));
+  if (typeof value.mac !== 'string' || !value.mac) errs.push(fail('cursor missing MAC'));
+  return combine(...errs);
+}

package/src/contracts/index.ts

@@ -0,0 +1,15 @@
+/**
+ * U1 frozen Capture hard-cut contract surface. Import from this module for
+ * descriptor/result/schema types; it has no browser, CLI, output, or process
+ * side effects and remains intentionally unreachable from `src/capture.ts`
+ * until the atomic U15 public cutover.
+ */
+export * from './primitives.js';
+export * from './results.js';
+export * from './routes.js';
+export * from './snapshot.js';
+export * from './neutral.js';
+export * from './a11y.js';
+export * from './cursor.js';
+export * from './motion.js';
+export * from './release.js';

package/src/contracts/motion.ts

@@ -0,0 +1,19 @@
+/** Frozen motion observations schema-2 contract (U1), pure types/validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+export const MOTION_OBSERVATION_FAMILIES = ['source-record', 'trace-event', 'frame-interval', 'frame-pixel-delta', 'element-rect-delta', 'observer-rect-delta'] as const;
+export type MotionObservationFamily = (typeof MOTION_OBSERVATION_FAMILIES)[number];
+/** Source ordinals are contiguous across the entire recording before final write. */
+export interface MotionObservation { readonly id: string; readonly family: MotionObservationFamily; readonly sourceOrdinal: number; readonly kindRank: number; readonly childRank: number; readonly values: Record<string, unknown>; readonly availability: Availability<null>; readonly provenance: { readonly recordingId: string; readonly artifactPath: string; readonly jsonPointer: string }; }
+export interface MotionObservationsManifest { readonly schemaVersion: 2; readonly recordingId: string; readonly sourceSchemaVersion: 2; readonly observations: readonly MotionObservation[]; readonly completeWithinRetainedCoverage: true; readonly ordering: '(sourceOrdinal,kind-rank,child-rank)'; }
+export function validateMotionObservationsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('motion observations must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 2 || value.sourceSchemaVersion !== 2) errs.push(fail('motion observations requires recording/source schemaVersion 2'));
+  if (typeof value.recordingId !== 'string' || !value.recordingId) errs.push(fail('motion observations missing recordingId'));
+  if (value.ordering !== '(sourceOrdinal,kind-rank,child-rank)') errs.push(fail('motion observations has wrong ordering declaration'));
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('motion observations must attest retained coverage completeness'));
+  if (!Array.isArray(value.observations)) errs.push(fail('motion observations requires array'));
+  else for (const observation of value.observations) if (!isObject(observation) || typeof observation.id !== 'string' || !MOTION_OBSERVATION_FAMILIES.includes(observation.family as MotionObservationFamily) || !Number.isSafeInteger(observation.sourceOrdinal)) errs.push(fail('motion observations contains malformed observation'));
+  return combine(...errs);
+}

package/src/contracts/neutral.ts

@@ -0,0 +1,56 @@
+/** Frozen neutral measurement derived-read contracts (U1), pure types/validators only. */
+import { Availability, OK, ValidationResult, combine, fail, isObject } from './primitives.js';
+
+/** The eleven canonical family order is semantic and deterministic. */
+export const NEUTRAL_FAMILIES = [
+  'viewport-box-position', 'element-scroll-extent', 'native-interactive-box-size',
+  'computed-color-pair-contrast', 'sampled-hit-reception', 'text-inline-extent',
+  'form-control-state', 'media-state', 'animation-state',
+  'opaque-background-sibling-box-intersection',
+  'css-overflow-visible-descendant-peer-box-intersection',
+] as const;
+export type NeutralFamily = (typeof NEUTRAL_FAMILIES)[number];
+
+export interface NumericSummary { readonly count: number; readonly unavailableCount: number; readonly min: number | null; readonly p25: number | null; readonly p50: number | null; readonly p75: number | null; readonly max: number | null; }
+export interface FactProvenance { readonly snapshotId: string; readonly sources: readonly string[]; readonly artifactPath: string; readonly jsonPointer: string; }
+export interface NeutralFact { readonly id: string; readonly family: NeutralFamily; readonly schemaVersion: 1; readonly subjects: readonly string[]; readonly values: Record<string, unknown>; readonly units: Record<string, string>; readonly availability: Availability<null>; readonly provenance: FactProvenance; }
+export interface FamilyCoverage { readonly populationDefinition: string; readonly schemaVersion: 1; readonly sources: readonly string[]; readonly availability: Availability<null>; readonly populationCount: number; readonly measuredCount: number; readonly unavailableCount: number; readonly sourceTotal?: number; readonly kept: number; readonly dropped?: number; readonly droppedUnknown?: boolean; readonly caps: readonly string[]; readonly exclusions: readonly string[]; readonly unavailableReasons: Readonly<Record<string, number>>; }
+export interface NeutralFamilyStore { readonly family: NeutralFamily; readonly coverage: FamilyCoverage; readonly numericSummaries: Readonly<Record<string, NumericSummary>>; readonly categoricalMaps: Readonly<Record<string, Readonly<Record<string, number>>>>; readonly relationCandidateAccounting?: Record<string, number>; readonly facts: readonly NeutralFact[]; }
+/** Exhaustive retained measurement evidence, never a bounded display projection. */
+export interface FactsManifest { readonly schemaVersion: 1; readonly snapshotIds: readonly string[]; readonly familyOrder: readonly NeutralFamily[]; readonly families: readonly NeutralFamilyStore[]; readonly completeWithinRetainedCoverage: true; }
+
+/** One merged snapshot-local subject; collisions never merge subjects. */
+export interface SelectorSubject { readonly subjectId: string; readonly snapshotId: string; readonly geometryOrdinal?: number; readonly axSourceOrdinal?: number; readonly textSourceOrdinal?: number; readonly backendNodeId?: number; readonly css?: readonly string[]; readonly axIds?: readonly string[]; readonly axNames?: readonly string[]; readonly text?: readonly string[]; }
+export interface SelectorsManifest { readonly schemaVersion: 1; readonly snapshotIds: readonly string[]; readonly order: 'geometry-ordinal-then-ax-document-order-then-text-capture-order'; readonly subjects: readonly SelectorSubject[]; }
+
+/** Source occurrence attested by a derived read. SHA-256 is over source `meta.json` bytes. */
+export interface ReadSourceOccurrence { readonly snapshotId: string; readonly canonicalPath: string; readonly metaSchemaVersion: 1 | 2; readonly metaSha256: string; }
+export interface DerivedReadManifest { readonly schemaVersion: 1; readonly readId: string; readonly owner: string; readonly operation: string; readonly sources: readonly ReadSourceOccurrence[]; readonly factsPath: string; readonly selectorsPath: string; readonly familyCounts: Readonly<Record<string, number>>; readonly factOrderVersion: 1; readonly selectorOrderVersion: 1; readonly completeWithinRetainedCoverage: true; readonly cropsPath?: string; }
+
+export function validateFactsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('facts manifest must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('facts schemaVersion must be 1'));
+  if (!Array.isArray(value.snapshotIds) || !value.snapshotIds.every((x) => typeof x === 'string')) errs.push(fail('facts requires snapshotIds string array'));
+  if (!Array.isArray(value.familyOrder) || !Array.isArray(value.families)) errs.push(fail('facts requires familyOrder and families arrays'));
+  else for (const family of value.families) {
+    if (!isObject(family) || typeof family.family !== 'string' || !isObject(family.coverage) || !Array.isArray(family.facts)) errs.push(fail('facts contains malformed family store'));
+  }
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('facts must attest completeWithinRetainedCoverage=true'));
+  return combine(...errs);
+}
+export function validateSelectorsManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('selectors manifest must be an object');
+  if (value.schemaVersion !== 1) return fail('selectors schemaVersion must be 1');
+  if (!Array.isArray(value.snapshotIds) || !Array.isArray(value.subjects) || typeof value.order !== 'string') return fail('selectors requires snapshotIds, order, and subjects');
+  return OK;
+}
+export function validateDerivedReadManifest(value: unknown): ValidationResult {
+  if (!isObject(value)) return fail('derived read manifest must be an object');
+  const errs: ValidationResult[] = [];
+  if (value.schemaVersion !== 1) errs.push(fail('derived read manifest schemaVersion must be 1'));
+  for (const f of ['readId', 'owner', 'operation', 'factsPath', 'selectorsPath']) if (typeof value[f] !== 'string' || !value[f]) errs.push(fail(`missing ${f}`));
+  if (!Array.isArray(value.sources)) errs.push(fail('derived read manifest requires sources array'));
+  if (value.completeWithinRetainedCoverage !== true) errs.push(fail('derived read must attest completeWithinRetainedCoverage=true'));
+  return combine(...errs);
+}