@crouton-kit/capture 1.3.8 → 1.3.9

package/src/cdp/measure/sweep.ts

@@ -0,0 +1,330 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { CDPClient } from '../client.js';
+import { ensurePrivateDir, writeJsonPrivate } from '../../session/artifacts.js';
+import type { SnapshotMeta } from './types.js';
+
+export const SWEEP_AXES = ['width', 'dpr', 'zoom', 'color-scheme', 'reduced-motion'] as const;
+export type SweepAxis = (typeof SWEEP_AXES)[number];
+
+export interface SweepSample {
+  readonly value: number | string;
+  readonly snapId: string;
+  readonly snapDir: string;
+  readonly fingerprint: string;
+  readonly settled: boolean;
+  readonly unstableRegions: readonly { id: string; selector?: string; reason?: string }[];
+}
+
+export interface SweepTransition {
+  readonly bracket: { readonly from: number | string; readonly to: number | string };
+  readonly before: string;
+  readonly after: string;
+  readonly changes: readonly SweepChange[];
+}
+
+export interface SweepChange {
+  readonly selector: string;
+  readonly property: string;
+  readonly before: string | null;
+  readonly after: string | null;
+  readonly provenance?: {
+    readonly selector?: string;
+    readonly specificity?: string;
+    readonly source?: string;
+  };
+}
+
+/** Adjacent observed samples with matching fingerprints; this is not a claim about unobserved values between them. */
+export interface SweepRange {
+  readonly from: number | string;
+  readonly to: number | string;
+  readonly snapId: string;
+  readonly fingerprint: string;
+}
+
+export interface SweepUncertainty {
+  readonly from: number;
+  readonly to: number;
+  readonly reason: 'sampling_limit' | 'resolution_limit';
+}
+
+export interface SweepArtifact {
+  readonly axis: SweepAxis;
+  readonly from: number | string;
+  readonly to: number | string;
+  readonly capturedAt: string;
+  readonly samples: readonly SweepSample[];
+  readonly transitions: readonly SweepTransition[];
+  readonly ranges: readonly SweepRange[];
+  readonly uncertainties: readonly SweepUncertainty[];
+  readonly sampleLimit?: number;
+  /** Effective environment facts captured before sampling; CDP does not expose arbitrary pre-existing override configuration. */
+  readonly environmentRestoration?: {
+    readonly observed: readonly string[];
+    readonly unobservable: readonly string[];
+  };
+}
+
+export interface SweepRecovery {
+  readonly axis: SweepAxis;
+  readonly capturedAt: string;
+  readonly reason: 'evidence_only' | 'capture_failed';
+  /** Whether restoration was not reached, completed, or threw while handling the failed sweep. */
+  readonly environmentRestoration: 'not_attempted' | 'restored' | 'failed';
+  readonly samples: readonly {
+    value: number | string;
+    snapId: string;
+    snapDir: string;
+    /** The capture lifecycle state known by the orchestrator; failed records may contain artifacts written before the throw. */
+    status: 'pending' | 'captured' | 'evidence_only' | 'failed';
+    captured: boolean;
+    settled: boolean;
+    unstableRegions: readonly { id: string; selector?: string; reason?: string }[];
+    artifacts: readonly string[];
+    failure?: 'capture_threw';
+  }[];
+}
+
+interface StylesElement {
+  readonly id?: string;
+  readonly selector?: string;
+  readonly computed?: Record<string, string | null>;
+  readonly winningDeclarations?: readonly {
+    readonly property?: string;
+    readonly selector?: string | null;
+    readonly specificity?: string | null;
+    readonly authored?: { readonly file?: string; readonly line?: number; readonly column?: number };
+    readonly generated?: { readonly sourceURL?: string; readonly line?: number; readonly column?: number };
+  }[];
+}
+
+interface StylesReport {
+  readonly elements?: readonly StylesElement[];
+}
+
+interface GeometryReport {
+  readonly elements?: readonly { readonly id?: string; readonly selector?: string; readonly visible?: boolean; readonly display?: string }[];
+}
+
+interface TextElement {
+  readonly id?: string;
+  readonly selector?: string;
+  readonly backendNodeId?: number | null;
+  readonly lines?: readonly unknown[];
+  readonly wrapOffsets?: readonly number[];
+}
+
+interface TextReport {
+  readonly elements?: readonly TextElement[];
+  readonly nodes?: readonly TextElement[];
+}
+
+const DISCRETE_COMPUTED_PROPERTIES = new Set([
+  'display', 'visibility', 'position', 'float', 'clear', 'overflow', 'overflow-x', 'overflow-y',
+  'flex-direction', 'flex-wrap', 'grid-auto-flow', 'justify-content', 'align-items', 'align-content',
+  'white-space', 'word-break', 'overflow-wrap', 'text-overflow', 'content-visibility', 'pointer-events',
+  'writing-mode', 'direction', 'font-style', 'color', 'background-color',
+  'grid-template-areas', 'color-scheme', 'mix-blend-mode', 'isolation',
+]);
+
+function readJson<T>(filePath: string): T | undefined {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8')) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function gridTrackCount(value: string | null | undefined): number | undefined {
+  if (!value) return undefined;
+  const repeat = /^repeat\(\s*(\d+)\s*,/.exec(value);
+  if (repeat) return Number(repeat[1]);
+  const tracks = value.trim().split(/\s+/).filter(Boolean);
+  return tracks.length || undefined;
+}
+
+function colorCategory(value: string | null | undefined): string | undefined {
+  if (!value) return undefined;
+  const rgb = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)(?:\s*[,/]\s*([\d.]+))?\s*\)$/.exec(value);
+  if (!rgb) return 'other';
+  const [red, green, blue, alpha] = rgb.slice(1).map(Number);
+  if (alpha !== undefined && alpha === 0) return 'transparent';
+  const maximum = Math.max(red, green, blue);
+  const dominant = `${red === maximum ? 'r' : ''}${green === maximum ? 'g' : ''}${blue === maximum ? 'b' : ''}`;
+  return `${dominant}-${maximum + Math.min(red, green, blue) >= 255 ? 'light' : 'dark'}`;
+}
+
+function fingerprintComputed(property: string, value: string | null): string | null | undefined {
+  if (property === 'color' || property === 'background-color') return colorCategory(value);
+  return value;
+}
+
+/** A deterministic signature containing only categorical rendered-state facts. Fluid geometry, numeric styles, collector identities, and CSS provenance are deliberately excluded. Each collector's document-order records stay ordered so anonymous elements retain their structural association. */
+export function fingerprintSnapshotDir(snapDir: string): string {
+  const geometry = readJson<GeometryReport>(path.join(snapDir, 'geometry.json'));
+  const styles = readJson<StylesReport>(path.join(snapDir, 'styles.json'));
+  const text = readJson<TextReport>(path.join(snapDir, 'text.json'));
+  const substrate = {
+    geometry: geometry?.elements?.map((element) => ({ visible: element.visible, display: element.display })) ?? { missing: 'geometry.json' },
+    styles: styles?.elements?.map((element) => ({
+      computed: Object.fromEntries(Object.entries(element.computed ?? {}).filter(([property]) => DISCRETE_COMPUTED_PROPERTIES.has(property)).sort(([a], [b]) => a.localeCompare(b)).map(([property, value]) => [property, fingerprintComputed(property, value)])),
+      gridTrackCount: gridTrackCount(element.computed?.['grid-template-columns']),
+    })) ?? { missing: 'styles.json' },
+    text: (text?.elements ?? text?.nodes)?.map((element) => ({ lineCount: element.lines?.length, wrapOffsets: element.wrapOffsets })) ?? { missing: 'text.json' },
+  };
+  return crypto.createHash('sha256').update(JSON.stringify(substrate)).digest('hex');
+}
+
+interface SweepDeclaration {
+  readonly property?: string;
+  readonly selector?: string | null;
+  readonly specificity?: string | null;
+  readonly authored?: { readonly file?: string; readonly line?: number; readonly column?: number };
+  readonly generated?: { readonly sourceURL?: string; readonly line?: number; readonly column?: number };
+}
+
+function sourceFor(declaration: SweepDeclaration): SweepChange['provenance'] | undefined {
+  const authored = declaration.authored;
+  const generated = declaration.generated;
+  const source = authored?.file ? `${authored.file}${authored.line === undefined ? '' : `:${authored.line}${authored.column === undefined ? '' : `:${authored.column}`}`}` : generated?.sourceURL ? `${generated.sourceURL}${generated.line === undefined ? '' : `:${generated.line}${generated.column === undefined ? '' : `:${generated.column}`}`}` : undefined;
+  if (!declaration.selector && !declaration.specificity && !source) return undefined;
+  return { selector: declaration.selector ?? undefined, specificity: declaration.specificity ?? undefined, source };
+}
+
+/** Extracts changed computed values and the winning declaration for the new value, when captured. */
+export function changesBetweenSnapshots(beforeDir: string, afterDir: string): SweepChange[] {
+  const before = readJson<StylesReport>(path.join(beforeDir, 'styles.json'));
+  const after = readJson<StylesReport>(path.join(afterDir, 'styles.json'));
+  if (!before?.elements || !after?.elements) return [];
+  const prior = new Map(before.elements.map((element) => [element.id ?? element.selector ?? '', element]));
+  const changes: SweepChange[] = [];
+  for (const next of after.elements) {
+    const key = next.id ?? next.selector ?? '';
+    const old = prior.get(key);
+    if (!old) continue;
+    const properties = new Set([...Object.keys(old.computed ?? {}), ...Object.keys(next.computed ?? {})]);
+    for (const property of properties) {
+      const beforeValue = old.computed?.[property] ?? null;
+      const afterValue = next.computed?.[property] ?? null;
+      if (beforeValue === afterValue) continue;
+      const declaration = next.winningDeclarations?.find((candidate) => candidate.property === property);
+      changes.push({ selector: next.selector ?? key, property, before: beforeValue, after: afterValue, ...(declaration ? { provenance: sourceFor(declaration) } : {}) });
+    }
+  }
+  return changes;
+}
+
+/** Builds adjacent observed changes and matching-fingerprint spans; neither denotes unobserved values as stable. */
+export function analyzeSweepSamples(axis: SweepAxis, _from: number | string, _to: number | string, samples: readonly SweepSample[]): Pick<SweepArtifact, 'transitions' | 'ranges'> {
+  const transitions: SweepTransition[] = [];
+  const ranges: SweepRange[] = [];
+  for (let i = 1; i < samples.length; i += 1) {
+    const previous = samples[i - 1];
+    const current = samples[i];
+    if (previous.fingerprint === current.fingerprint) {
+      ranges.push({ from: previous.value, to: current.value, snapId: previous.snapId, fingerprint: previous.fingerprint });
+      continue;
+    }
+    transitions.push({ bracket: { from: previous.value, to: current.value }, before: previous.snapId, after: current.snapId, changes: changesBetweenSnapshots(previous.snapDir, current.snapDir) });
+  }
+  return { transitions, ranges };
+}
+
+export async function refineNumericSweep(samples: readonly SweepSample[], tolerance: number, capture: (value: number) => Promise<SweepSample>, sampleLimit = 96): Promise<{ samples: SweepSample[]; uncertainties: SweepUncertainty[] }> {
+  const byValue = new Map(samples.map((sample) => [Number(sample.value), sample]));
+  const uncertainties: SweepUncertainty[] = [];
+  const ordered = [...byValue.keys()].sort((a, b) => a - b);
+  const pending: Array<{ from: number; to: number }> = [];
+  for (let i = 1; i < ordered.length; i += 1) pending.push({ from: ordered[i - 1], to: ordered[i] });
+  // Breadth-first subdivision gives every coarse interval a sampled midpoint before spending the budget on finer detail in any one interval.
+  while (pending.length) {
+    const { from, to } = pending.shift()!;
+    if (to - from <= tolerance) {
+      uncertainties.push({ from, to, reason: 'resolution_limit' });
+      continue;
+    }
+    if (byValue.size >= sampleLimit) {
+      uncertainties.push({ from, to, reason: 'sampling_limit' });
+      continue;
+    }
+    const middle = tolerance >= 1 ? Math.floor((from + to) / 2) : Number(((from + to) / 2).toFixed(4));
+    if (middle <= from || middle >= to) {
+      uncertainties.push({ from, to, reason: 'resolution_limit' });
+      continue;
+    }
+    if (!byValue.has(middle)) byValue.set(middle, await capture(middle));
+    pending.push({ from, to: middle }, { from: middle, to });
+  }
+  return { samples: [...byValue.values()].sort((a, b) => Number(a.value) - Number(b.value)), uncertainties };
+}
+
+export function isSweepAxis(value: string | undefined): value is SweepAxis {
+  return value !== undefined && (SWEEP_AXES as readonly string[]).includes(value);
+}
+
+export function numericSweepValues(from: number, to: number, axis: Extract<SweepAxis, 'width' | 'dpr' | 'zoom'>): number[] {
+  if (!Number.isFinite(from) || !Number.isFinite(to) || from >= to) throw new Error(`--from must be smaller than --to for ${axis}`);
+  const step = axis === 'width' ? Math.max(1, Math.ceil((to - from) / 8)) : (to - from) / 8;
+  const values = [from];
+  for (let value = from + step; value < to; value += step) values.push(axis === 'width' ? Math.round(value) : Number(value.toFixed(4)));
+  values.push(to);
+  return [...new Set(values)].sort((a, b) => a - b);
+}
+
+export type SweepMedia = 'screen' | 'print' | 'speech';
+
+export interface SweepEnvironment {
+  readonly width: number;
+  readonly height: number;
+  readonly dpr: number;
+  readonly pageScale: number;
+  /** An effective media type observable through CSS media queries; omitted when the prior CDP type cannot be determined. */
+  readonly media?: SweepMedia;
+  readonly colorScheme: 'light' | 'dark';
+  readonly reducedMotion: 'reduce' | 'no-preference';
+}
+
+export async function readSweepEnvironment(client: CDPClient): Promise<SweepEnvironment> {
+  const response = await client.send('Runtime.evaluate', { expression: '({width: window.innerWidth, height: window.innerHeight, dpr: window.devicePixelRatio, pageScale: window.visualViewport?.scale || 1, media: matchMedia("print").matches ? "print" : matchMedia("speech").matches ? "speech" : matchMedia("screen").matches ? "screen" : null, colorScheme: matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light", reducedMotion: matchMedia("(prefers-reduced-motion: reduce)").matches ? "reduce" : "no-preference"})', returnByValue: true }) as { result?: { value?: Partial<SweepEnvironment> } };
+  const value = response.result?.value;
+  if (!value || !Number.isFinite(value.width) || !Number.isFinite(value.height) || !Number.isFinite(value.dpr) || !Number.isFinite(value.pageScale) || (value.media !== undefined && value.media !== 'screen' && value.media !== 'print' && value.media !== 'speech' && value.media !== null) || (value.colorScheme !== 'light' && value.colorScheme !== 'dark') || (value.reducedMotion !== 'reduce' && value.reducedMotion !== 'no-preference')) throw new Error('could not read the page emulation environment before sampling');
+  return { width: Math.round(value.width), height: Math.round(value.height), dpr: value.dpr, pageScale: value.pageScale, ...(value.media ? { media: value.media } : {}), colorScheme: value.colorScheme, reducedMotion: value.reducedMotion };
+}
+
+function mediaParams(baseline: SweepEnvironment): { media?: SweepMedia } {
+  return baseline.media === undefined ? {} : { media: baseline.media };
+}
+
+export async function applySweepEmulation(client: CDPClient, axis: SweepAxis, value: number | string, baseline: SweepEnvironment): Promise<void> {
+  if (axis === 'width') await client.send('Emulation.setDeviceMetricsOverride', { width: Math.round(Number(value)), height: baseline.height, deviceScaleFactor: baseline.dpr, mobile: false });
+  else if (axis === 'dpr') await client.send('Emulation.setDeviceMetricsOverride', { width: baseline.width, height: baseline.height, deviceScaleFactor: Number(value), mobile: false });
+  else if (axis === 'zoom') await client.send('Emulation.setPageScaleFactor', { pageScaleFactor: Number(value) });
+  else await client.send('Emulation.setEmulatedMedia', { ...mediaParams(baseline), features: [{ name: 'prefers-color-scheme', value: axis === 'color-scheme' ? String(value) : baseline.colorScheme }, { name: 'prefers-reduced-motion', value: axis === 'reduced-motion' ? String(value) : baseline.reducedMotion }] });
+}
+
+/** Restores the observed pre-sweep viewport, scale, and supported media settings; an unobservable media type is never replaced with an invented one. */
+export async function restoreSweepEnvironment(client: CDPClient, baseline: SweepEnvironment): Promise<void> {
+  await client.send('Emulation.setDeviceMetricsOverride', { width: baseline.width, height: baseline.height, deviceScaleFactor: baseline.dpr, mobile: false });
+  await client.send('Emulation.setPageScaleFactor', { pageScaleFactor: baseline.pageScale });
+  await client.send('Emulation.setEmulatedMedia', { ...mediaParams(baseline), features: [{ name: 'prefers-color-scheme', value: baseline.colorScheme }, { name: 'prefers-reduced-motion', value: baseline.reducedMotion }] });
+}
+
+export function readSweepSnapshot(snapId: string, snapDir: string, value: number | string, unstableRegions: SweepSample['unstableRegions'] = [], capturedSettled?: boolean): SweepSample {
+  const meta = readJson<SnapshotMeta>(path.join(snapDir, 'meta.json'));
+  return { value, snapId, snapDir, fingerprint: fingerprintSnapshotDir(snapDir), settled: capturedSettled ?? (meta?.settled === true), unstableRegions };
+}
+
+export function writeSweepArtifact(dir: string, artifact: SweepArtifact): string {
+  const artifactPath = path.join(ensurePrivateDir(dir), 'sweep.json');
+  writeJsonPrivate(artifactPath, artifact);
+  return artifactPath;
+}
+
+export function writeSweepRecoveryArtifact(dir: string, recovery: SweepRecovery): string {
+  const artifactPath = path.join(ensurePrivateDir(dir), 'sweep-recovery.json');
+  writeJsonPrivate(artifactPath, recovery);
+  return artifactPath;
+}

package/src/cdp/measure/types.ts

@@ -0,0 +1,220 @@
+/**
+ * Snapshot substrate types — the contract every `measure snap` collector
+ * (U07–U12) and the orchestrator (`snapshot.ts`) share. This file is the
+ * spec: read it before writing or changing a collector.
+ *
+ * ## The U04 artifact contract collectors must honor
+ *  - `geometry.json` is ALWAYS `{ elements: ElementRecord[], unstableRegions?:
+ *    UnstableRegion[] }`. `unstableRegions` is present ONLY on a
+ *    `--capture-unsettled` capture of an unsettled page — never on a
+ *    settled capture, and never omitted-but-empty vs. absent inconsistently.
+ *    See `src/output/artifact.ts`'s module doc for the reader side of this.
+ *  - Every per-element record any collector writes (in `geometry.json` and
+ *    elsewhere) should carry the identifying fields in {@link ElementRecord}
+ *    — a stable `id`, and whichever of `selector`/`backendNodeId`/`axId`/
+ *    `axName`/`text` it has facts for — so `src/output/selector.ts`'s
+ *    selector-input resolution works uniformly across every collector file.
+ *  - `meta.json` MUST ALWAYS exist for any snap dir this orchestrator
+ *    touches, including an unsettled, evidence-only capture (no
+ *    `--capture-unsettled`). `session stop` reads it to build the bundle
+ *    manifest, and `src/output/artifact.ts` treats its presence as the
+ *    marker that a ref actually names something.
+ */
+
+import type { CDPClient } from '../client.js';
+import type { SnapMeta } from '../../session/artifacts.js';
+import type { UnstableRegion } from '../../output/artifact.js';
+import type { ElementRecord } from '../../output/selector.js';
+
+export type { UnstableRegion, ElementRecord };
+
+/** The already-connected CDP client + (optional) target identity a snapshot capture drives. */
+export interface CaptureSnapshotTarget {
+  readonly client: CDPClient;
+  readonly tabId?: string;
+}
+
+/** Input to {@link captureSnapshotSubstrate} — mirrors `measure snap`'s CLI options 1:1. */
+export interface CaptureSnapshotOptions {
+  readonly target: CaptureSnapshotTarget;
+  readonly url: string | null;
+  /** Absolute artifact directory for this snap, caller-resolved (session `measure/snaps/{id}` or a oneshot dir). */
+  readonly path: string;
+  /** Snapshot id; defaults to `basename(path)`. */
+  readonly snapId?: string;
+  /** `--settle-timeout <ms>`; default {@link DEFAULT_SETTLE_TIMEOUT_MS} (5000). */
+  readonly settleTimeout?: number;
+  /** `--freeze-animations`; default `false`. */
+  readonly freezeAnimations?: boolean;
+  /** `--capture-unsettled`; default `false`. */
+  readonly captureUnsettled?: boolean;
+  /** `--pixels`; default `false`. */
+  readonly pixels?: boolean;
+  /** `--state <state[:selector]>` (repeatable); default `[]`. */
+  readonly state?: readonly string[];
+  readonly viewport?: string | null;
+  /**
+   * Poll interval for the settledness loop; default {@link DEFAULT_POLL_INTERVAL_MS}
+   * (100ms). Not part of the CLI surface — a test-only override so the
+   * settledness suite doesn't need a fake-clock injection seam in
+   * production code. Omitting it reproduces the documented default.
+   */
+  readonly pollIntervalMs?: number;
+  /**
+   * Quiet-window threshold for the settledness loop; default
+   * {@link DEFAULT_QUIET_THRESHOLD_MS} (300ms). Same test-only-override
+   * rationale as `pollIntervalMs`.
+   */
+  readonly quietThresholdMs?: number;
+  /**
+   * Collector set to run, ordered by {@link CollectorPhase}. Not part of
+   * the CLI surface — a test-only override so the phase-ordering suite can
+   * inject stub collectors that record their call order. Omitting it runs
+   * the real collector set `snapshot.ts` defines.
+   */
+  readonly collectors?: readonly CollectorDescriptor[];
+}
+
+/** `meta.json`'s on-disk shape — a {@link SnapMeta} (the U03 contract) plus snapshot-specific detail. */
+export interface SnapshotMeta extends SnapMeta {
+  readonly settleMs: number;
+  readonly settleTimeoutMs: number;
+  readonly freezeAnimations: boolean;
+  readonly captureUnsettled: boolean;
+  readonly pixels: boolean;
+  readonly states: readonly string[];
+  readonly unstableRegionCount: number;
+  /** Present only when `freezeAnimations` is true — whether every animation `freezeAnimationsBeforeCapture` paused was confirmed resumed to its pre-freeze `playState` (I-6). `false` means restoration could not be guaranteed (origin capture failed, or the restore call itself threw) — never omitted to imply a clean restore. */
+  readonly animationsRestored?: boolean;
+  /** Present (and always `false`) only when the browser-wide `Animation.setPlaybackRate({playbackRate:0})` freeze override itself threw during origin capture (I-6, #8) — distinct from `animationsRestored` above, which reflects only the RESTORE step. The per-animation `.pause()` calls captured in the same evaluate as the origin capture are still real for whatever existed at freeze time, but any animation the page creates AFTER that point was never covered by the override. Absent whenever the override genuinely succeeded, freeze wasn't requested, or the origin capture itself failed (that failure is already surfaced via a pessimistic `animationsRestored:false`) — never a fabricated affirmative standing in for "unknown". */
+  readonly freezeOverrideApplied?: false;
+  /** Present (and always `true`) only when at least one animation's own `.pause()` call inside {@link FREEZE_ANIMATIONS_SCRIPT} failed (#72) — that animation was left running through the frozen baseline capture even though `rateOverrideApplied`/`freezeOverrideApplied` can both be genuinely clean. Absent whenever every enumerated animation was confirmed paused, freeze wasn't requested, or the origin capture itself failed (already surfaced via a pessimistic `animationsRestored:false`) — never a fabricated `false` standing in for "unknown". Always emitted alongside `unfrozenCount` when `true`. */
+  readonly freezeIncomplete?: true;
+  /** Count of animations whose `.pause()` call failed (#72) — only present when `freezeIncomplete` is `true`. `0` there means the pause-failure tally itself could not be read back (the count is genuinely UNKNOWN, not confirmed zero); `freezeIncomplete` is the operative gate for that case, not this count. */
+  readonly unfrozenCount?: number;
+  /** Present only when the snapshot reached the baseline boundary (`captured`) — whether `document.documentElement.outerHTML` was actually read (I-5). `false` means the CDP read threw or returned no value: `dom.html` is NOT written in that case (an absent file, never a benign empty one), and `unavailableReason` names why. */
+  readonly domHtml?: { readonly available: boolean; readonly unavailableReason?: string };
+}
+
+/** Return value of {@link captureSnapshotSubstrate}. */
+export interface CaptureSnapshotResult {
+  readonly id: string;
+  readonly dir: string;
+  readonly url: string | null;
+  readonly viewport: string | null;
+  readonly settled: boolean;
+  /** `settled || captureUnsettled` — whether the full collector substrate was written. */
+  readonly captured: boolean;
+  readonly settleMs: number;
+  readonly settleTimeoutMs: number;
+  readonly unstableRegions: readonly UnstableRegion[];
+  /** Filenames written under `dir`, relative to it. */
+  readonly artifacts: readonly string[];
+  readonly meta: SnapshotMeta;
+}
+
+/**
+ * The write surface a {@link SnapshotContext} hands to every collector.
+ * Both methods resolve `filename` against the snap `dir` and THROW if the
+ * resolved target would escape it (an absolute path, or a `path.relative`
+ * from `dir` that climbs out via `..`) — the U03 secure-fs helpers only
+ * enforce the global `CAPTURE_ROOT` boundary, so this containment check is
+ * what actually scopes a collector's writes to this snap's directory.
+ */
+export interface SnapshotWriter {
+  /** Writes `value` as pretty JSON to `filename` under the snap dir (via `writeJsonPrivate`) and records it as a written artifact. Throws if `filename` would escape the snap dir. */
+  json(filename: string, value: unknown): void;
+  /** Writes `data` as a binary file to `filename` under the snap dir (via `writeBinaryPrivate`) and records it as a written artifact. Throws if `filename` would escape the snap dir. */
+  binary(filename: string, data: Buffer): void;
+}
+
+/**
+ * Shared, read-only capture context every collector (U07–U12) receives.
+ * Collectors read from this and write only through `write` — never touch
+ * `fs` directly, never resolve their own path under `dir`.
+ */
+export interface SnapshotContext {
+  readonly client: CDPClient;
+  /** Absolute snap artifact directory. */
+  readonly dir: string;
+  readonly snapId: string;
+  readonly url: string | null;
+  readonly viewport: string | null;
+  /** Whether the page reached settledness (not merely whether a full substrate is being written — see `captureUnsettled`). */
+  readonly settled: boolean;
+  readonly freezeAnimations: boolean;
+  readonly captureUnsettled: boolean;
+  readonly pixels: boolean;
+  /** `--state` values requested for this capture. */
+  readonly state: readonly string[];
+  /** Non-empty ONLY when the page was unstable and a full substrate was still captured (`--capture-unsettled`). Collectors that key elements should stamp matching regions' ids onto affected records; `geometry.ts` spreads this directly into `geometry.json`'s `unstableRegions` field. */
+  readonly unstableRegions: readonly UnstableRegion[];
+  readonly write: SnapshotWriter;
+}
+
+/** A collector's whole contract: read from `ctx`, write via `ctx.write`, resolve. */
+export type Collector = (ctx: SnapshotContext) => Promise<void>;
+
+/**
+ * Which snapshot phase a collector belongs to — the ordering guarantee the
+ * orchestrator enforces:
+ *  - `baseline`: pure/measuring collectors that must observe the page as it
+ *    settled. They run in PARALLEL, and ALL finish before `screenshot.png`
+ *    + `dom.html` are captured at the baseline boundary.
+ *  - `mutating`: collectors that mutate DOM/focus/scroll/background
+ *    (focus, scroll, states, pixels). They run AFTER the baseline artifacts
+ *    are captured, and SERIALIZED (one at a time) so their mutations and
+ *    restorations cannot contaminate the baseline artifacts or each other.
+ */
+export type CollectorPhase = 'baseline' | 'mutating';
+
+/** A collector paired with the phase that decides when and how it runs. */
+export interface CollectorDescriptor {
+  readonly name: string;
+  readonly phase: CollectorPhase;
+  readonly fn: Collector;
+}
+
+// ============================================================================
+// Churn/evidence artifact shapes — written only on the evidence branch
+// (unsettled capture), by `settle.ts`/`snapshot.ts`.
+// ============================================================================
+
+/** One `churn.json` region — grouped mutation or animation evidence for one distinct source. */
+export interface ChurnRegionRecord {
+  readonly id: string;
+  readonly selector?: string;
+  readonly reason?: string;
+  readonly mutationCount: number;
+  readonly firstMutationAtMs?: number;
+  readonly lastMutationAtMs?: number;
+}
+
+/** `churn.json`'s on-disk shape — written only when a snap did NOT settle. */
+export interface ChurnReport {
+  readonly settled: false;
+  readonly settleTimeoutMs: number;
+  readonly elapsedMs: number;
+  /** Count of mutations actually kept (bounded by the churn observer's 200-record cap) — `regions[].mutationCount` sums to this, not to the true observed total. */
+  readonly totalMutations: number;
+  readonly resizeCount: number;
+  /** Present (with the dropped count) only when the churn observer's 200-record cap was hit — the observer counted more raw mutations than it kept, so `totalMutations`/`regions` reflect the capped set, not every mutation the page produced (I-5). Absent when nothing was dropped. */
+  readonly mutationsTruncated?: number;
+  readonly regions: readonly ChurnRegionRecord[];
+}
+
+/** One entry in `document.getAnimations()`'s inventory. */
+export interface AnimationEvidenceRecord {
+  readonly selector: string | null;
+  readonly animationName: string | null;
+  readonly durationMs: number | null;
+  readonly iterationCount: number | 'infinite' | null;
+  readonly infinite: boolean;
+  readonly playState: string;
+}
+
+/** `animation.json`'s on-disk shape when written as evidence (unsettled, not captured). */
+export interface AnimationEvidence {
+  readonly animations: readonly AnimationEvidenceRecord[];
+  readonly infiniteCount: number;
+}

package/src/cdp/measure/v2/collectors.ts

@@ -0,0 +1,19 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { CollectorCoverage, SNAPSHOT_FACET_NAMES, SnapshotFacetName } from '../../../contracts/snapshot.js';
+import { SnapAcquisitionRequest } from './snap-selection.js';
+export type CollectorPhase = 'baseline' | 'mutating';
+export interface DeclaredArtifact { readonly key: string; readonly path: string; readonly media_type: string; readonly retained_arrays?: readonly { readonly key: string; readonly json_pointer: string; readonly retained_count: number }[]; }
+export interface NamedCoverage { readonly name: string; readonly coverage: CollectorCoverage; }
+export interface SnapshotCollectorContext { readonly request: SnapAcquisitionRequest; readonly root: string; write(artifact: DeclaredArtifact, bytes: Uint8Array): void; restore(name: string, restore: () => Promise<{ readonly restored: boolean; readonly reason?: string }>): void; }
+export interface CollectorResult<N extends SnapshotFacetName> { readonly primary: NamedCoverage; readonly subpopulations: Record<string, CollectorCoverage>; readonly artifacts: readonly DeclaredArtifact[]; }
+export interface RegisteredSnapshotCollector<N extends SnapshotFacetName = SnapshotFacetName> { readonly facet: N; readonly phase: CollectorPhase; readonly requested: (request: SnapAcquisitionRequest) => boolean; readonly collect: (ctx: SnapshotCollectorContext) => Promise<CollectorResult<N>>; }
+export class SnapshotCollectorRegistry { constructor(readonly entries: readonly RegisteredSnapshotCollector[]) {} }
+export function defineSnapshotCollectors(entries: readonly RegisteredSnapshotCollector[]): SnapshotCollectorRegistry { const seen = new Set(entries.map(entry => entry.facet)); if (entries.length !== SNAPSHOT_FACET_NAMES.length || seen.size !== entries.length || SNAPSHOT_FACET_NAMES.some(facet => !seen.has(facet)) || entries.some(entry => entry.phase !== 'baseline' && entry.phase !== 'mutating')) throw new Error('snapshot collector registration must contain each fixed facet exactly once'); return new SnapshotCollectorRegistry([...entries].sort((a, b) => SNAPSHOT_FACET_NAMES.indexOf(a.facet) - SNAPSHOT_FACET_NAMES.indexOf(b.facet))); }
+const unavailable = (reason: string): CollectorCoverage => ({ retained_count: 0, availability: { state: 'unavailable', reason }, truncation: { state: 'unknown' }, source_total: { state: 'unavailable', reason } });
+/** U7 replaces registrations, not orchestration. Placeholder collectors intentionally acquire no browser evidence. */
+const placeholderSubpopulations = (facet: SnapshotFacetName): Record<string, CollectorCoverage> => facet === 'queries' ? { 'media-queries': unavailable('collector-unavailable'), 'container-queries': unavailable('collector-unavailable') } : facet === 'focus' ? { forward: unavailable('collector-unavailable'), reverse: unavailable('collector-unavailable') } : facet === 'scroll' ? { 'snap-descendants': unavailable('collector-unavailable'), 'sticky-fixed-descendants': unavailable('collector-unavailable'), 'sampled-visible-children': unavailable('collector-unavailable') } : {};
+export const defaultSnapshotCollectors = defineSnapshotCollectors(SNAPSHOT_FACET_NAMES.map(facet => ({ facet, phase: 'baseline' as const, requested: request => facet !== 'pixels' || request.pixels ? facet !== 'states' || request.states.length > 0 : false, collect: async () => ({ primary: { name: facet, coverage: unavailable('collector-unavailable') }, subpopulations: placeholderSubpopulations(facet), artifacts: [] }) })));
+export function createArtifactWriter(root: string, restorers: Array<{ name: string; restore: () => Promise<{ restored: boolean; reason?: string }> }>): Pick<SnapshotCollectorContext, 'write' | 'restore'> { const paths = new Set<string>(); return { write(artifact, bytes) { if (!artifact.path || path.isAbsolute(artifact.path) || artifact.path.includes('\\') || artifact.path.split('/').some(item => !item || item === '.' || item === '..') || paths.has(artifact.path)) throw new Error('invalid or duplicate collector artifact path'); paths.add(artifact.path); const output = path.join(root, artifact.path); fs.mkdirSync(path.dirname(output), { recursive: true, mode: 0o700 }); fs.writeFileSync(output, bytes); }, restore(name, restore) { restorers.push({ name, restore }); } }; }
+export function sourceArtifactDeclaration(root: string, artifact: DeclaredArtifact) { const data = fs.readFileSync(path.join(root, artifact.path)); return { key: artifact.key, path: artifact.path, bytes: data.length, sha256: crypto.createHash('sha256').update(data).digest('hex'), media_type: artifact.media_type, retained_arrays: artifact.retained_arrays ?? [] }; }

package/src/cdp/measure/v2/orchestrator.ts

@@ -0,0 +1,46 @@
+import { SnapshotFacet, SnapshotMetaV2, SnapshotTargetAttestation } from '../../../contracts/snapshot.js';
+import { allocateSnapshotStaging, cleanupSnapshotStaging, finalizeSnapshotManifest, publishSnapshot, SnapshotIndexEntry } from '../../../output/artifact-lifecycle.js';
+import { createArtifactWriter, defaultSnapshotCollectors, DeclaredArtifact, SnapshotCollectorRegistry, sourceArtifactDeclaration } from './collectors.js';
+import { SnapAcquisitionRequest } from './snap-selection.js';
+import { ResolvedTarget } from './target.js';
+import { withTargetMutationLock } from './target-lock.js';
+export interface PinnedSession { readonly sessionId: string; readonly source: 'active' | 'explicit'; readonly generation: number | null; readonly target: ResolvedTarget; readonly directory: string; }
+export interface SessionSnapshotAuthority { withPinnedOpenSession<T>(selection: Extract<SnapAcquisitionRequest['selection'], { kind: 'named-session' | 'active-session' }>, fn: (session: PinnedSession) => Promise<T>): Promise<T>; }
+export interface SnapshotOrchestratorDeps { readonly artifactRoot?: string; readonly collectors?: SnapshotCollectorRegistry; readonly resolveTarget: (request: SnapAcquisitionRequest) => Promise<{ readonly target: ResolvedTarget; readonly attestation: SnapshotTargetAttestation; readonly association: 'one-shot' | { readonly sessionId: string }; readonly close?: () => Promise<boolean> }>; readonly sessions?: SessionSnapshotAuthority; readonly coordinateAuthority?: Record<string, unknown>; readonly contentInputs?: Record<string, unknown>; }
+export interface SnapshotAcquisitionResult { readonly snapshot: SnapshotIndexEntry; readonly attestation: SnapshotTargetAttestation; }
+const sameTarget = (a: ResolvedTarget, b: ResolvedTarget): boolean => a.identity.host === b.identity.host && a.identity.port === b.identity.port && a.identity.fullTargetId === b.identity.fullTargetId;
+const unavailable = { retained_count: 0, availability: { state: 'unavailable' as const, reason: 'collector-unavailable' }, truncation: { state: 'unknown' as const }, source_total: { state: 'unavailable' as const, reason: 'collector-unavailable' } };
+const facet = (requested: boolean, primary: { name: string; coverage: any } | undefined, subpopulations: Record<string, any> | undefined): SnapshotFacet => { const coverage = primary?.coverage ?? unavailable; const blocked = coverage.availability !== 'available'; return { status: !requested ? 'not-requested' : blocked ? 'unavailable' : 'available', primary_population: primary ?? { name: 'unavailable', coverage }, subpopulations: subpopulations ?? {}, unavailable_reason: !requested ? null : blocked ? coverage.availability.reason : null }; };
+/** Private/unreachable acquisition seam. Resolution, pinning, locking, collection, restoration, close, and publication are one lifecycle. */
+export async function acquireSnapshotV2(request: SnapAcquisitionRequest, deps: SnapshotOrchestratorDeps): Promise<SnapshotAcquisitionResult> {
+  const run = async (pinned?: PinnedSession): Promise<SnapshotAcquisitionResult> => {
+    const resolved = await deps.resolveTarget(request);
+    if (pinned && !sameTarget(pinned.target, resolved.target)) throw new Error('session target changed while pinned');
+    const target = pinned?.target ?? resolved.target;
+    return withTargetMutationLock(target.identity, async () => {
+      let staging: ReturnType<typeof allocateSnapshotStaging> | undefined; let published = false; let closeAttempted = false; let primary: unknown; let restoration: unknown; let close: unknown;
+      try {
+        staging = allocateSnapshotStaging(deps.artifactRoot);
+        const restorers: Array<{ name: string; restore: () => Promise<{ restored: boolean; reason?: string }> }> = []; const writer = createArtifactWriter(staging.directory, restorers); const results = new Map<string, { primary: any; subpopulations: Record<string, any>; artifacts: readonly DeclaredArtifact[] }>(); const registry = deps.collectors ?? defaultSnapshotCollectors;
+        const baseline = registry.entries.filter(entry => entry.phase === 'baseline' && entry.requested(request));
+        const settled = await Promise.allSettled(baseline.map(entry => entry.collect({ request, root: staging!.directory, ...writer }).then(result => results.set(entry.facet, result))));
+        primary = settled.find(item => item.status === 'rejected' && item.reason)?.reason;
+        if (!primary) for (const entry of registry.entries.filter(entry => entry.phase === 'mutating' && entry.requested(request))) { try { results.set(entry.facet, await entry.collect({ request, root: staging.directory, ...writer })); } catch (error) { primary = error; break; } }
+        for (const restorer of [...restorers].reverse()) try { const result = await restorer.restore(); if (!result.restored) restoration ??= new Error(result.reason ?? `restoration ${restorer.name} unconfirmed`); } catch (error) { restoration ??= error; }
+        if (resolved.close) try { closeAttempted = true; if (!(await resolved.close())) close = new Error('temporary_target_cleanup_unconfirmed'); } catch (error) { close = error; }
+        if (close || restoration || primary) throw close ?? restoration ?? primary;
+        const facets = {} as SnapshotMetaV2['facets']; const artifacts: DeclaredArtifact[] = [];
+        for (const entry of registry.entries) { const result = results.get(entry.facet); (facets as any)[entry.facet] = facet(entry.requested(request), result?.primary, result?.subpopulations); if (result) artifacts.push(...result.artifacts); }
+        const meta: Omit<SnapshotMetaV2, 'snapshotId'> = { schemaVersion: 2, request: { selection: request.selection }, settled: true, timing: {}, coordinateAuthority: deps.coordinateAuthority ?? {}, contentInputs: deps.contentInputs ?? {}, target: resolved.attestation, facets, source_artifact_manifest: { schemaVersion: 2, artifacts: artifacts.map(artifact => sourceArtifactDeclaration(staging!.directory, artifact)).sort((a, b) => a.path.localeCompare(b.path)) }, sourcePixelCoverage: {} };
+        finalizeSnapshotManifest(staging, meta); const snapshot = publishSnapshot(staging, resolved.association, deps.artifactRoot); published = true; return { snapshot, attestation: resolved.attestation };
+      } catch (error) {
+        primary ??= error;
+        if (resolved.close && !closeAttempted) try { closeAttempted = true; if (!(await resolved.close())) close = new Error('temporary_target_cleanup_unconfirmed'); } catch (closeError) { close = closeError; }
+        if (staging && !published) cleanupSnapshotStaging(staging, deps.artifactRoot);
+        throw close ?? restoration ?? primary;
+      }
+    });
+  };
+  if (request.selection.kind === 'named-session' || request.selection.kind === 'active-session') { if (!deps.sessions) throw new Error('session snapshot authority is required'); return deps.sessions.withPinnedOpenSession(request.selection, run); }
+  return run();
+}