@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/commands/measure/sweep.ts

@@ -0,0 +1,227 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { randomBytes } from 'crypto';
+
+import { type ParsedArgs } from '../../types.js';
+import { withConnection } from '../../connection.js';
+import { captureSnapshotSubstrate } from '../../measure/snapshot.js';
+import { createOneshotSession } from '../../../session/commands.js';
+import { getActiveSession } from '../../../session-context.js';
+import { emitResult, fact, line, lineList, renderResult, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { assertSweepBounds, parsePositiveNumber } from '../../leaf-grammar.js';
+import {
+  SWEEP_AXES,
+  analyzeSweepSamples,
+  applySweepEmulation,
+  isSweepAxis,
+  numericSweepValues,
+  readSweepEnvironment,
+  readSweepSnapshot,
+  refineNumericSweep,
+  restoreSweepEnvironment,
+  type SweepArtifact,
+  type SweepAxis,
+  type SweepRecovery,
+  type SweepSample,
+  writeSweepArtifact,
+  writeSweepRecoveryArtifact,
+} from '../../measure/sweep.js';
+
+const USAGE = `capture measure sweep [url] --axis <axis> — responsive/environment sampling with recursive bracketing of observed state changes
+
+input:
+  [url]                     page to sweep; outside a session, snapshots and sweep.json are written under one private one-shot measure directory
+  --axis <axis>             width|dpr|zoom|color-scheme|reduced-motion (required)
+  --from <val>              numeric range start, or a color-scheme/reduced-motion value
+  --to <val>                numeric range end, or a color-scheme/reduced-motion value
+  --viewport-height <val>   fixed viewport height for width/dpr sweeps
+output: <sweep axis=… samples=… transitions=…> — observed state facts per sampled point, each sampled snapshot path included; --json mirrors
+effects: drives the page repeatedly under CDP Emulation settings; writes one snapshot substrate per sampled point plus sweep.json`;
+
+const SAMPLE_LIMIT = 96;
+
+export interface SweepCommandDependencies {
+  readonly withConnection: typeof withConnection;
+  readonly captureSnapshotSubstrate: typeof captureSnapshotSubstrate;
+  readonly getActiveSession: typeof getActiveSession;
+  readonly createOneshotSession: typeof createOneshotSession;
+  readonly emitResult: typeof emitResult;
+}
+
+const defaultDependencies: SweepCommandDependencies = { withConnection, captureSnapshotSubstrate, getActiveSession, createOneshotSession, emitResult };
+
+function sweepId(): string {
+  return `sweep-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+
+/** Lists a bounded set of regular files already written to a failed snapshot directory. */
+function writtenSnapshotArtifacts(dir: string): string[] {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => entry.name).sort().slice(0, 64);
+  } catch {
+    return [];
+  }
+}
+
+// The `--from`/`--to`/`--viewport-height` numeric grammar and the enum-axis
+// domain are validated up front in `validateCliInvocation` (before any
+// artifact allocation) via the shared `parsePositiveNumber`/`assertSweepBounds`
+// predicates below; the runtime path re-runs the same pure functions so the
+// two layers can never diverge.
+const parsePositive = parsePositiveNumber;
+
+function valuesForAxis(axis: SweepAxis, parsed: ParsedArgs): Array<number | string> {
+  assertSweepBounds(axis, parsed.from, parsed.to);
+  if (axis === 'width') return numericSweepValues(parsePositive(parsed.from, 320, '--from'), parsePositive(parsed.to, 1440, '--to'), axis);
+  if (axis === 'dpr') return numericSweepValues(parsePositive(parsed.from, 1, '--from'), parsePositive(parsed.to, 3, '--to'), axis);
+  if (axis === 'zoom') return numericSweepValues(parsePositive(parsed.from, 0.5, '--from'), parsePositive(parsed.to, 2, '--to'), axis);
+  if (axis === 'color-scheme') return [parsed.from ?? 'light', parsed.to ?? 'dark'];
+  return [parsed.from ?? 'no-preference', parsed.to ?? 'reduce'];
+}
+
+export function transitionSections(artifact: SweepArtifact): FactLine[] {
+  const ranges = artifact.ranges.map((range) => line(fact`  observed matching fingerprint ${range.from}–${range.to} → ${range.snapId} (${range.snapDir})`));
+  const transitions = artifact.transitions.flatMap((transition, index) => {
+    const header = line(fact`${index + 1}. bracketed between ${transition.bracket.from} and ${transition.bracket.to} — ${transition.before} → ${transition.after}`);
+    const changes = transition.changes.slice(0, 12).map((change) => {
+      const provenance = change.provenance?.source ? fact` (${change.provenance.selector ?? 'winning declaration'}${change.provenance.specificity ? `, specificity ${change.provenance.specificity}` : ''}, ${change.provenance.source})` : change.provenance?.selector ? fact` (${change.provenance.selector}${change.provenance.specificity ? `, specificity ${change.provenance.specificity}` : ''})` : text``;
+      return line(fact`   ${change.selector} ${change.property}: ${change.before ?? 'unset'} → ${change.after ?? 'unset'}`, provenance);
+    });
+    return [header, ...changes];
+  });
+  const uncertainty = artifact.uncertainties.map((interval) => fact`  ${interval.from}–${interval.to}: ${interval.reason === 'sampling_limit' ? `not sampled after the ${artifact.sampleLimit} sample limit` : 'adjacent sampled endpoints at resolution limit'}`);
+  const settled = artifact.samples.map((sample) => {
+    const caveats = sample.unstableRegions.map((region) => fact` region ${region.id}${region.selector ? ` (${region.selector})` : ''}${region.reason ? `: ${region.reason}` : ''}`);
+    const sampleFact = fact`  ${sample.value}: ${sample.snapId} (${sample.snapDir}) settled=${String(sample.settled)}`;
+    return caveats.length ? line(sampleFact, line(text` — unstable`, lineList(caveats))) : sampleFact;
+  });
+  return [
+    lineList([text`Observed matching-fingerprint spans (no assertion about unsampled values):`, ...(ranges.length ? ranges : [text`  none`])]),
+    lineList([text`Observed state changes (bracketed by samples):`, ...(transitions.length ? transitions : [text`  none observed across sampled values`])]),
+    lineList([text`Sampling uncertainty:`, ...(uncertainty.length ? uncertainty : [text`  none`])]),
+    lineList([text`Captured sample paths and settledness:`, ...settled]),
+    artifact.environmentRestoration ? lineList([
+      text`Environment restoration provenance:`,
+      fact`  observed/restored effective settings: ${artifact.environmentRestoration.observed.join(', ')}`,
+      fact`  CDP does not expose prior override configuration for: ${artifact.environmentRestoration.unobservable.join(', ')}`,
+    ]) : text``,
+  ];
+}
+
+export function renderSweepArtifact(artifact: SweepArtifact): string {
+  return renderResult({ tag: 'sweep', attrs: { axis: artifact.axis, from: artifact.from, to: artifact.to, samples: artifact.samples.length, transitions: artifact.transitions.length }, summary: fact`Sweep samples are recorded as observed state facts.`, sections: transitionSections(artifact), followUp: artifact.samples.length > 1 ? fact`Compare two sampled substrates with \`capture measure diff --before ${artifact.samples[0].snapDir} --after ${artifact.samples[1].snapDir}\`.` : undefined });
+}
+
+export async function cmdMeasureSweep(parsed: ParsedArgs, args: string[]): Promise<void> {
+  await runMeasureSweep(parsed, args);
+}
+
+/** Runs sweep orchestration; dependency overrides keep the thrown-capture recovery path verifiable without a browser. */
+export async function runMeasureSweep(parsed: ParsedArgs, _args: string[], overrides: Partial<SweepCommandDependencies> = {}): Promise<void> {
+  const dependencies = { ...defaultDependencies, ...overrides };
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length > 1) {
+    dependencies.emitResult({ tag: 'error', attrs: { command: 'measure sweep', status: 'invalid_input' }, summary: text`Measure sweep accepts at most one positional URL.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+  if (!isSweepAxis(parsed.axis)) {
+    dependencies.emitResult({ tag: 'error', attrs: { command: 'measure sweep', status: 'invalid_axis' }, summary: fact`--axis is required and must be one of ${SWEEP_AXES.join(', ')}.` }, { json: parsed.json });
+    process.exitCode = 1;
+    return;
+  }
+
+  const axis = parsed.axis;
+  const active = dependencies.getActiveSession();
+  const oneShot = active ? undefined : dependencies.createOneshotSession('measure');
+  const snapsDir = active ? path.join(active.dir, 'measure', 'snaps') : oneShot!.artifactsDir;
+  const artifactDir = active ? path.join(active.dir, 'measure', 'sweeps', sweepId()) : path.join(oneShot!.dir, 'measure', 'sweeps', sweepId());
+  const recoverySamples: Array<SweepRecovery['samples'][number]> = [];
+  let environmentRestoration: SweepRecovery['environmentRestoration'] = 'not_attempted';
+  try {
+    const values = valuesForAxis(axis, parsed);
+    const connectionArgs: ParsedArgs = parsed.positional[0] ? { ...parsed, url: parsed.positional[0], target: undefined } : parsed;
+    const samplesByValue = new Map<string, SweepSample>();
+    let uncertainties: SweepArtifact['uncertainties'] = [];
+    let environmentFacts: SweepArtifact['environmentRestoration'];
+    await dependencies.withConnection(connectionArgs, async (client, tab) => {
+      const baseline = await readSweepEnvironment(client);
+      environmentFacts = {
+        observed: ['viewport width/height', 'device pixel ratio', 'page scale', ...(baseline.media === undefined ? [] : [`effective media type (${baseline.media})`]), 'prefers-color-scheme', 'prefers-reduced-motion'],
+        unobservable: ['arbitrary pre-existing device metrics fields', 'arbitrary media feature overrides', ...(baseline.media === undefined ? ['arbitrary pre-existing media types (not observable or restored)'] : [])],
+      };
+      const samplingEnvironment = { ...baseline, height: parsed.viewportHeight === undefined ? baseline.height : parsePositive(parsed.viewportHeight, 1, '--viewport-height') };
+      const capture = async (value: number | string): Promise<SweepSample> => {
+        const key = String(value);
+        const prior = samplesByValue.get(key);
+        if (prior) return prior;
+        await applySweepEmulation(client, axis, value, samplingEnvironment);
+        const id = `snap-${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+        const dir = path.join(snapsDir, id);
+        const recovery: SweepRecovery['samples'][number] = { value, snapId: id, snapDir: dir, status: 'pending', captured: false, settled: false, unstableRegions: [], artifacts: [] };
+        recoverySamples.push(recovery);
+        let result;
+        try {
+          result = await dependencies.captureSnapshotSubstrate({
+            target: { client, tabId: tab.id }, url: tab.url, path: dir, snapId: id,
+            settleTimeout: parsed.settleTimeout, freezeAnimations: parsed.freezeAnimations,
+            captureUnsettled: parsed.captureUnsettled, pixels: parsed.pixels, state: parsed.state ?? [],
+            viewport: `${axis === 'width' ? value : samplingEnvironment.width}x${samplingEnvironment.height}`,
+          });
+        } catch (error) {
+          Object.assign(recovery, { status: 'failed', failure: 'capture_threw', artifacts: writtenSnapshotArtifacts(dir) });
+          throw error;
+        }
+        Object.assign(recovery, { status: result.captured ? 'captured' : 'evidence_only', captured: result.captured, settled: result.settled, unstableRegions: result.unstableRegions, artifacts: result.artifacts });
+        if (!result.captured) throw new Error('evidence-only snapshot');
+        const sample = readSweepSnapshot(id, dir, value, result.unstableRegions, result.settled);
+        samplesByValue.set(key, sample);
+        return sample;
+      };
+      try {
+        for (const value of values) await capture(value);
+        if (axis === 'width' || axis === 'dpr' || axis === 'zoom') {
+          const tolerance = axis === 'width' ? 1 : 0.01;
+          const refined = await refineNumericSweep([...samplesByValue.values()], tolerance, capture, SAMPLE_LIMIT);
+          samplesByValue.clear();
+          for (const sample of refined.samples) samplesByValue.set(String(sample.value), sample);
+          uncertainties = refined.uncertainties;
+        }
+      } finally {
+        try {
+          await restoreSweepEnvironment(client, baseline);
+          environmentRestoration = 'restored';
+        } catch (error) {
+          environmentRestoration = 'failed';
+          throw error;
+        }
+      }
+    }, { settle: 0 });
+
+    const samples = (axis === 'width' || axis === 'dpr' || axis === 'zoom') ? [...samplesByValue.values()].sort((a, b) => Number(a.value) - Number(b.value)) : values.map((value) => samplesByValue.get(String(value))!).filter(Boolean);
+    const from = values[0];
+    const to = values[values.length - 1];
+    const analyzed = analyzeSweepSamples(axis, from, to, samples);
+    const artifact: SweepArtifact = { axis, from, to, capturedAt: new Date().toISOString(), samples, ...analyzed, uncertainties, sampleLimit: SAMPLE_LIMIT, environmentRestoration: environmentFacts };
+    const artifactPath = writeSweepArtifact(artifactDir, artifact);
+    const result: RenderableResult = {
+      tag: 'sweep', attrs: { axis, from, to, samples: samples.length, transitions: artifact.transitions.length, path: artifactDir },
+      summary: fact`Sweep artifact written to ${artifactPath}. It records sampled snapshot paths, discrete-state fingerprints, bracketed observed changes, and sampling uncertainty.`,
+      sections: transitionSections(artifact),
+      followUp: samples.length > 1 ? fact`Compare two sampled substrates with \`capture measure diff --before ${samples[0].snapDir} --after ${samples[1].snapDir}\`.` : undefined,
+    };
+    dependencies.emitResult(result, { json: parsed.json });
+  } catch {
+    const evidenceOnly = recoverySamples.some((sample) => sample.status === 'evidence_only');
+    const recoveryPath = writeSweepRecoveryArtifact(artifactDir, { axis, capturedAt: new Date().toISOString(), reason: evidenceOnly ? 'evidence_only' : 'capture_failed', environmentRestoration, samples: recoverySamples });
+    dependencies.emitResult({
+      tag: 'error', attrs: { command: 'measure sweep', status: evidenceOnly ? 'evidence_only' : 'sweep_failed', path: recoveryPath },
+      summary: fact`Sweep did not produce a queryable sample set. Recovery artifact: ${recoveryPath}.`,
+      sections: recoverySamples.length ? [text`Partial snapshot/recovery provenance:`, ...recoverySamples.map((sample) => fact`${sample.value}: ${sample.snapDir} status=${sample.status} captured=${sample.captured} settled=${sample.settled} artifacts=${sample.artifacts.join(', ') || 'none'} unstable=${sample.unstableRegions.map((region) => `${region.id}${region.reason ? `:${region.reason}` : ''}`).join(', ') || 'none'}`), fact`environment restoration: ${environmentRestoration}`] : undefined,
+    }, { json: parsed.json });
+    process.exitCode = 1;
+  }
+}

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

@@ -0,0 +1,61 @@
+/**
+ * `capture motion` branch router.
+ *
+ * Shifts the consumed leaf token out of `parsed.positional` before handing
+ * off, so every leaf command still finds its own primary target (a URL, a
+ * recording id, ...) at `positional[0]` exactly as every other capture
+ * command does.
+ */
+import { invalidInput } from '../../../errors.js';
+import { type ParsedArgs } from '../../types.js';
+import { cmdMotionRec } from './rec.js';
+import { cmdMotionMask } from './mask.js';
+import { cmdMotionTimeline } from './timeline.js';
+import { cmdMotionJank } from './jank.js';
+import { cmdMotionResponse } from './response.js';
+
+/** Root-help representation of this branch, assembled by `src/capture.ts`. */
+export const COMMAND_BLOCK = `<command name="motion">
+facts over a recording — recorder lifecycle plus read-only queries over a finalized recording
+use when recording an interaction (one-shot or composed) and reading motion facts: diffs, timelines, jank, input response
+  rec · mask · timeline · jank · response — \`capture motion -h\`
+</command>`;
+
+export const MOTION_USAGE = `capture motion — recorder lifecycle + read-only queries over a finalized recording.
+
+\`rec\` drives (and records) the browser, one-shot or composed across
+intervening commands; every other leaf below is a cheap read over the
+finalized recording artifact. Every leaf defaults to rendered prose; --json
+mirrors the same result. Findings exit 0 — a report, not a failure;
+input/precondition errors exit 1. No leaf accepts --gate.
+
+<subcommand name="rec" args="[url] --do <action> [--duration <seconds>] | --start | --stop" whenToUse="record an interaction — one-shot action, or composed across commands with --start/--stop (needs an active session)"/>
+<subcommand name="mask" args="<rec> [--limit <N>]" whenToUse="motion-diff composite image + per-region facts"/>
+<subcommand name="timeline" args="<rec> --element <sel> [--prop <prop>]" whenToUse="per-frame geometry/scroll/property timeline for one element"/>
+<subcommand name="jank" args="<rec>" whenToUse="dropped-frame/long-task/layout-shift facts"/>
+<subcommand name="response" args="<rec> [--action <action>] [--occurrence <n>]" whenToUse="input-to-settled response timeline"/>
+
+capture motion <leaf> -h    Per-leaf usage`;
+
+export async function motionMain(parsed: ParsedArgs, args: string[]): Promise<void> {
+  const leaf = parsed.positional[0];
+  const rest: ParsedArgs = { ...parsed, positional: parsed.positional.slice(1) };
+
+  switch (leaf) {
+    case 'rec':
+      return cmdMotionRec(rest, args);
+    case 'mask':
+      return cmdMotionMask(rest, args);
+    case 'timeline':
+      return cmdMotionTimeline(rest, args);
+    case 'jank':
+      return cmdMotionJank(rest, args);
+    case 'response':
+      return cmdMotionResponse(rest, args);
+    case undefined:
+      console.log(MOTION_USAGE);
+      return;
+    default:
+      throw invalidInput(`Unknown motion leaf: ${leaf}.`, 'unknown_command');
+  }
+}

package/src/cdp/commands/motion/jank.ts

@@ -0,0 +1,132 @@
+import { type ParsedArgs } from '../../types.js';
+import { resolveRecRef } from '../../../output/artifact.js';
+import { emitResult, fact, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+import { readMotionJank, type ArtifactLossFact, type LayoutShiftFact, type LayoutShiftRectFact, type LongTaskFact } from '../../motion/jank.js';
+
+const USAGE = `capture motion jank <rec> — dropped-frame, long-task-record, and layout-shift facts over a finalized recording
+
+input:
+  <rec>   recording id in the active session or an absolute recording path (required; the recording must be finalized)
+output: <jank …> — dropped-frame, long-task-record, and layout-shift facts; observer and screencast timing is recorder-relative performance.now(), trace timing recorder-relative only when an explicit trace/performance baseline was retained; --json mirrors
+effects: read-only — reads the finalized recording artifact, never drives the browser`;
+
+export async function cmdMotionJank(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length !== 1 || !parsed.positional[0]) {
+    return emitCommandError(parsed, 'invalid_target', 'motion jank requires exactly one recording id or absolute recording path.', 'Record one with `capture motion rec <url> --do <action>` .');
+  }
+
+  try {
+    const ref = resolveRecRef(parsed.positional[0]);
+    const { analysis, meta } = readMotionJank(ref);
+    const state = typeof meta.state === 'string' ? meta.state : 'unknown';
+    const sections: FactLine[] = [fact`${analysis.timingNote}`];
+
+    if (analysis.droppedFrames.length) {
+      sections.push(lineList(analysis.droppedFrames.map((drop, index) =>
+        fact`${index + 1}. frames ${drop.beforeFrame}→${drop.afterFrame}: interval ${drop.intervalMs.toFixed(2)}ms, cadence ${analysis.cadenceMs?.toFixed(2) ?? 'unavailable'}ms, estimated dropped frames ${drop.estimatedDroppedFrames}, t=${drop.startMs.toFixed(2)}→${drop.endMs.toFixed(2)}ms (±frame)`,
+      )));
+    } else {
+      sections.push(fact`Dropped-frame intervals: 0; ${analysis.frameCount} timestamped rect sample(s), cadence ${analysis.cadenceMs?.toFixed(2) ?? 'unavailable'}ms.`);
+    }
+    if (analysis.missingFrameSampleCount > 0) sections.push(fact`${analysis.missingFrameSampleCount} screencast frame(s) have no rect timestamp sample; dropped-frame count is incomplete.`);
+    if (analysis.cadenceMs === null) sections.push(text`Fewer than two positive frame intervals were retained; nominal cadence is unavailable and the dropped-frame count is incomplete.`);
+
+    if (analysis.longTasks.length) {
+      sections.push(lineList(analysis.longTasks.map((task, index) => formatLongTask(task, index))));
+    } else {
+      sections.push(text`Long-task records: 0.`);
+    }
+
+    if (analysis.layoutShifts.length) {
+      sections.push(...analysis.layoutShifts.map((shift, index) => formatLayoutShift(shift, index)));
+    } else {
+      sections.push(text`Layout-shift records: 0.`);
+    }
+
+    if (analysis.artifactLoss.length) {
+      sections.push(lineList(analysis.artifactLoss.map(formatArtifactLoss)));
+    }
+
+    const result: RenderableResult = {
+      tag: 'jank',
+      attestation: {
+        kind: 'recording',
+        id: ref.id,
+        path: ref.dir,
+        note: fact`Recording state ${state}. ${analysis.timingNote}`,
+      },
+      attrs: {
+        state,
+        frames: analysis.frameCount,
+        'dropped-frames': analysis.droppedFrameCount,
+        'dropped-frames-incomplete': analysis.droppedFramesIncomplete,
+        'long-task-records': analysis.longTasks.length,
+        'long-task-records-incomplete': analysis.longTasksIncomplete,
+        'layout-shift-records': analysis.layoutShifts.length,
+        'layout-shift-records-incomplete': analysis.layoutShiftsIncomplete,
+        'timestamp-uncertainty': analysis.frameTimestampUncertainty,
+      },
+      summary: fact`${analysis.droppedFrameCount} estimated dropped frame(s)${analysis.droppedFramesIncomplete ? ' (incomplete)' : ''}, ${analysis.longTasks.length} long-task record(s)${analysis.longTasksIncomplete ? ' (incomplete)' : ''}, ${analysis.layoutShifts.length} layout-shift record(s)${analysis.layoutShiftsIncomplete ? ' (incomplete)' : ''}.`,
+      sections,
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    emitCommandError(parsed, 'artifact_unavailable', message, 'Pass a finalized recording id/path; `capture motion rec --stop` finalizes a composed recording.');
+  }
+}
+
+function formatLongTask(task: LongTaskFact, index: number): FactLine {
+  const timingText = task.timingDomain === 'recorder-performance'
+    ? `t=${task.startMs!.toFixed(2)}→${task.endMs!.toFixed(2)}ms`
+    : task.timingDomain === 'trace-relative-first-event'
+      ? `t=${task.startMs!.toFixed(2)}→${task.endMs!.toFixed(2)}ms relative to first trace event`
+      : 'timing unavailable after navigation gap';
+  const overlapText = task.overlapsDroppedFrames === null
+    ? task.timingDomain === 'unavailable'
+      ? '; dropped-frame overlap unavailable after navigation gap'
+      : '; dropped-frame overlap unavailable across trace-relative and recorder-relative timing domains'
+    : task.overlapsDroppedFrames.length
+      ? `, overlaps dropped-frame interval(s) ending at frame ${task.overlapsDroppedFrames.join(', ')}`
+      : '';
+  return fact`long-task record ${index + 1} (${task.source}): ${timingText}, duration ${task.durationMs.toFixed(2)}ms${overlapText}.`;
+}
+
+function formatLayoutShift(shift: LayoutShiftFact, index: number): FactLine {
+  const attribution = shift.attribution === 'observer-sources'
+    ? 'PerformanceObserver sources'
+    : shift.attribution === 'frame-diff-inferred'
+      ? `inferred from rect samples bracketing t=${shift.beforeFrameMs?.toFixed(2)}→${shift.afterFrameMs?.toFixed(2)}ms (±frame)`
+      : 'unavailable';
+  const timing = shift.tMs === null ? 'timing unavailable after navigation gap' : `t=${shift.tMs.toFixed(2)}ms`;
+  const header = fact`layout shift ${index + 1}: ${timing}, value ${shift.value}${shift.hadRecentInput === undefined ? '' : `, had-recent-input ${shift.hadRecentInput}`}; attribution ${attribution}`;
+  return shift.rects.length ? lineList([header, ...shift.rects.map(formatShiftRect)]) : lineList([header, text`no element-attributed rect record was retained for this layout-shift entry`]);
+}
+
+function formatShiftRect(item: LayoutShiftRectFact): FactLine {
+  const current = item.rect ? `x=${item.rect.x} y=${item.rect.y} w=${item.rect.w} h=${item.rect.h}` : 'unavailable';
+  const previous = item.previousRect ? `x=${item.previousRect.x} y=${item.previousRect.y} w=${item.previousRect.w} h=${item.previousRect.h}` : 'unavailable';
+  const movement = item.delta ? `x=${item.delta.x} y=${item.delta.y} w=${item.delta.w} h=${item.delta.h}` : 'unavailable';
+  return fact`   ${item.elementId === undefined ? 'element id unavailable' : `element ${item.elementId}`}: rect ${current}; previous rect ${previous}; delta ${movement}`;
+}
+
+function formatArtifactLoss(loss: ArtifactLossFact): FactLine {
+  const details = loss.message ?? loss.reason ?? 'detail unavailable';
+  const affected = loss.affectedCounts.length ? `${loss.affectedCounts.join(', ')} (incomplete)` : 'no jank count family';
+  return fact`Artifact loss/recovery: ${loss.kind}; ${loss.count ?? 'unknown'} record(s); ${details}. Affected counts: ${affected}.`;
+}
+
+function emitCommandError(parsed: ParsedArgs, status: string, message: string, recovery: string): void {
+  const result: RenderableResult = {
+    tag: 'error',
+    attrs: { command: 'motion jank', status },
+    summary: fact`${message}`,
+    followUp: fact`${recovery}`,
+  };
+  emitResult(result, { json: parsed.json });
+  process.exitCode = 1;
+}

package/src/cdp/commands/motion/mask.ts

@@ -0,0 +1,92 @@
+import { type ParsedArgs } from '../../types.js';
+import { createMotionMask } from '../../motion/mask.js';
+import { readMeta, resolveRecRef } from '../../../output/artifact.js';
+import { emitResult, fact, formatArtifactList, line, lineList, text, type FactLine, type RenderableResult } from '../../../output/render.js';
+
+const DEFAULT_REGION_LIMIT = 20;
+
+const USAGE = `capture motion mask <rec> — motion-diff composite image plus per-region facts over a finalized recording
+
+input:
+  <rec>          recording id in the active session or an absolute recording path (required; the recording must be finalized)
+  --limit <N>    render at most N size-sorted region rows (default: ${DEFAULT_REGION_LIMIT}); --json always contains every region row
+output: <motion-mask …> — the composite image path plus per-region area, distance, velocity, and element attribution where recorded rects overlap; frame-derived times carry ±1-frame uncertainty; --json mirrors
+effects: reads the finalized recording artifact, never drives the browser; writes motion-mask.png inside the recording directory`;
+
+export async function cmdMotionMask(parsed: ParsedArgs, _args: string[]): Promise<void> {
+  if (parsed.help) {
+    console.log(USAGE);
+    return;
+  }
+  if (parsed.positional.length !== 1) {
+    return emitCommandError(parsed, 'invalid_target', 'motion mask requires exactly one recording id or absolute recording path. Create one with `capture motion rec`.');
+  }
+
+  try {
+    const ref = resolveRecRef(parsed.positional[0]);
+    const meta = readMeta<{ state?: unknown }>(ref);
+    const state = typeof meta.state === 'string' ? meta.state : 'unknown';
+    if (state !== 'finalized' && state !== 'orphaned-finalized') {
+      return emitCommandError(parsed, 'recording_not_finalized', `Recording ${ref.id} has state ${state}; finalize it with \`capture motion rec --stop\` before creating a mask.`);
+    }
+    const mask = createMotionMask(ref);
+    // A recording can have many isolated changed-pixel components. Limit the
+    // human/agent prose view, while JSON keeps the complete size-sorted list.
+    const proseLimit = parsed.limit ?? DEFAULT_REGION_LIMIT;
+    const reportedRegions = parsed.json ? mask.regions : mask.regions.slice(0, proseLimit);
+    const regionLines = reportedRegions.length
+      ? reportedRegions.map((region) => formatRegion(region))
+      : [text`No changed pixels were measured across the recorded frame pairs.`];
+    const result: RenderableResult = {
+      tag: 'motion-mask',
+      attestation: {
+        kind: 'recording',
+        id: ref.id,
+        path: ref.dir,
+        note: text`Frame-derived onset, distance, and velocity times carry ±1 frame uncertainty; timestamps use screencast-frame timing when available.`,
+      },
+      attrs: {
+        state,
+        regions: mask.regions.length,
+        'prose-regions': Math.min(mask.regions.length, proseLimit),
+        image: `${ref.id}/motion-mask.png`,
+        'timestamp-uncertainty': '±1 frame',
+        ...(mask.caveat ? { window: 'partial (viewport resize)' } : {}),
+      },
+      summary: fact`Composite written: motion-mask.png (${mask.width}×${mask.height}, ${mask.comparedFramePairs} adjacent frame pair(s)); transparent pixels did not differ and hue runs blue (early) to red (late).`,
+      artifacts: formatArtifactList([{ name: 'motion-mask.png', note: 'motion-diff composite' }]),
+      sections: [
+        ...(mask.caveat ? [line(text`${mask.caveat}`)] : []),
+        ...(mask.regions.length > proseLimit && !parsed.json
+          ? [fact`Showing ${reportedRegions.length} of ${mask.regions.length} size-sorted changed-pixel regions; --json contains all region rows.`]
+          : []),
+        lineList(regionLines),
+      ],
+      followUp: mask.regions[0]?.element
+        ? line(text`Per-frame geometry for region 1: \`capture motion timeline `, fact`${ref.id}`, text` --element `, fact`${mask.regions[0].element.label}\`.`)
+        : undefined,
+    };
+    emitResult(result, { json: parsed.json });
+  } catch (err) {
+    emitCommandError(parsed, 'artifact_unavailable', err instanceof Error ? err.message : String(err));
+  }
+}
+
+function formatRegion(region: ReturnType<typeof createMotionMask>['regions'][number]): FactLine {
+  const attribution = region.element
+    ? fact` · attributed rect: \`${region.element.label}\`${region.element.backendNodeId === undefined ? '' : ` (backend ${region.element.backendNodeId})`}`
+    : text` · no recorded element rect overlapped this region`;
+  return line(
+    fact`${region.index}. x=${region.x} y=${region.y} w=${region.width} h=${region.height} — area ${region.areaPixels} changed px; distance ${region.distancePx}px; velocity ${region.velocityPxPerSecond}px/s; frame-time ${region.startMs}–${region.endMs}ms`,
+    attribution,
+  );
+}
+
+function emitCommandError(parsed: ParsedArgs, status: string, message: string): void {
+  emitResult({
+    tag: 'error',
+    attrs: { command: 'motion mask', status },
+    summary: fact`${message}`,
+  }, { json: parsed.json });
+  process.exitCode = 1;
+}