@crouton-kit/capture 1.3.7 → 1.3.9

package/src/cdp/motion/response.ts

@@ -0,0 +1,356 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+import { diffPngs } from '../../output/diff.js';
+import { artifactPath, readEvents, readMarkers, readMeta, readRects, resolveRecRef, type RecRef } from '../../output/artifact.js';
+import { ensurePrivateDir } from '../../session/artifacts.js';
+
+export type ResponseStage = 'input' | 'mutation' | 'layout' | 'paint' | 'network' | 'longtask' | 'settle';
+export type TimestampPrecision = 'exact' | 'frame';
+
+export interface ResponsePoint {
+  readonly stage: ResponseStage;
+  /** Milliseconds in the recording-relative performance.now() domain. */
+  readonly timestampMs: number;
+  /** Delta from the selected input's start. */
+  readonly deltaMs: number;
+  readonly precision: TimestampPrecision;
+  /** Fixed, sanitized label for the evidence source. */
+  readonly source: string;
+}
+
+export interface ResponseTimeline {
+  readonly action: string;
+  readonly inputStartMs: number;
+  readonly inputEndMs: number;
+  readonly actionWindowEndMs: number | null;
+  readonly points: readonly ResponsePoint[];
+  readonly unavailableStages: readonly string[];
+  readonly caveats: readonly string[];
+  readonly state: string;
+  readonly timingNote: string;
+}
+
+interface Markers {
+  performanceNowMs: number;
+  wallClockMs?: number;
+  firstScreencastTimestampSec?: number | null;
+  firstTraceEventTsUs?: number | null;
+  tracePerformanceNowMs?: number | null;
+  traceTimestampUs?: number | null;
+  baselinesPending?: boolean;
+}
+
+interface EventRecord {
+  kind?: unknown;
+  mark?: unknown;
+  action?: unknown;
+  startPerformanceNow?: unknown;
+  endPerformanceNow?: unknown;
+  performanceNowMs?: unknown;
+  performanceNow?: unknown;
+  startTime?: unknown;
+  duration?: unknown;
+  entryType?: unknown;
+  name?: unknown;
+  events?: unknown;
+  timestamp?: unknown;
+  reason?: unknown;
+  count?: unknown;
+}
+
+interface FrameRecord {
+  frame?: unknown;
+  file?: unknown;
+  screencastTimestamp?: unknown;
+  timestamp?: unknown;
+  diffPixelCount?: unknown;
+}
+
+interface ActionMark {
+  readonly label: string;
+  readonly occurrence: number;
+  readonly startMs: number;
+  readonly endMs: number;
+}
+
+interface CandidatePoint extends Omit<ResponsePoint, 'deltaMs'> {}
+
+function finite(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function count(value: unknown): number | null {
+  return finite(value) && value >= 0 ? value : null;
+}
+
+function relativePerformance(timestamp: number, markers: Markers): number {
+  return timestamp - markers.performanceNowMs;
+}
+
+function observerPerformance(event: EventRecord, markers: Markers): number | null {
+  const timestamp = event.kind === 'performance'
+    ? event.startTime ?? event.performanceNowMs ?? event.performanceNow
+    : event.performanceNowMs ?? event.performanceNow ?? event.startTime;
+  return finite(timestamp) ? relativePerformance(timestamp, markers) : null;
+}
+
+function tracePerformance(timestampUs: number, markers: Markers): number | null {
+  const traceAnchorUs = finite(markers.traceTimestampUs) ? markers.traceTimestampUs : null;
+  const traceAnchorPerf = finite(markers.tracePerformanceNowMs) ? markers.tracePerformanceNowMs : null;
+  if (traceAnchorUs !== null && traceAnchorPerf !== null) return (timestampUs - traceAnchorUs) / 1000 + relativePerformance(traceAnchorPerf, markers);
+  return null;
+}
+
+function framePerformance(timestampSec: number, markers: Markers): number | null {
+  if (!finite(markers.wallClockMs)) return null;
+  return timestampSec * 1000 - markers.wallClockMs;
+}
+
+function inWindow(point: CandidatePoint, startMs: number, endMs: number | null): boolean {
+  return point.timestampMs >= startMs && (endMs === null || point.timestampMs < endMs);
+}
+
+function traceEvents(events: readonly EventRecord[], markers: Markers, caveats: string[]): Array<{ name: string; timestampMs: number; durationMs?: number }> {
+  const output: Array<{ name: string; timestampMs: number; durationMs?: number }> = [];
+  for (const event of events) {
+    if (event.kind !== 'trace' || !Array.isArray(event.events)) continue;
+    for (const raw of event.events) {
+      if (!raw || typeof raw !== 'object') continue;
+      const trace = raw as { name?: unknown; ts?: unknown; dur?: unknown };
+      if (!finite(trace.ts) || typeof trace.name !== 'string') continue;
+      const timestampMs = tracePerformance(trace.ts, markers);
+      if (timestampMs === null) continue;
+      output.push({ name: trace.name, timestampMs, durationMs: finite(trace.dur) ? trace.dur / 1000 : undefined });
+    }
+  }
+  if (events.some((event) => event.kind === 'trace') && output.length === 0) {
+    caveats.push('trace timing unavailable: markers.json has no real trace timestamp/performance alignment marker; trace-derived response rows are omitted.');
+  }
+  return output;
+}
+
+function inputMarks(events: readonly EventRecord[], markers: Markers): ActionMark[] {
+  const seen = new Map<string, number>();
+  const marks: ActionMark[] = [];
+  for (const event of events) {
+    if (event.kind !== 'input' || typeof event.mark !== 'string' || !finite(event.startPerformanceNow)) continue;
+    // New artifacts retain the verbatim action separately from the internal
+    // structural mark. Legacy artifacts have only `mark`.
+    const label = typeof event.action === 'string' ? event.action : event.mark;
+    if (typeof label !== 'string') continue;
+    const occurrence = (seen.get(label) ?? 0) + 1;
+    seen.set(label, occurrence);
+    const startMs = relativePerformance(event.startPerformanceNow, markers);
+    const endMs = finite(event.endPerformanceNow) ? relativePerformance(event.endPerformanceNow, markers) : startMs;
+    marks.push({ label, occurrence, startMs, endMs });
+  }
+  return marks.sort((a, b) => a.startMs - b.startMs || a.occurrence - b.occurrence);
+}
+
+function selectAction(actions: readonly ActionMark[], action: string, occurrence?: number): ActionMark {
+  const matches = actions.filter((item) => item.label === action);
+  if (matches.length === 0) throw new Error(`No input mark exists for action ${JSON.stringify(action)}.`);
+  if (occurrence !== undefined) {
+    const match = matches.find((item) => item.occurrence === occurrence);
+    if (match) return match;
+    throw new ResponseActionSelectionError(matches, `Action ${JSON.stringify(action)} has no occurrence ${occurrence}; ${matches.length} occurrence(s) available.`);
+  }
+  if (matches.length === 1) return matches[0];
+  throw new ResponseActionSelectionError(matches, `Action ${JSON.stringify(action)} appears ${matches.length} times; pass --occurrence <n> to select one.`);
+}
+
+function eventDropCaveats(events: readonly EventRecord[]): string[] {
+  const caveats: string[] = [];
+  for (const event of events) {
+    if (event.kind !== 'trace-dropped' && event.kind !== 'binding-dropped' && event.kind !== 'rect-sample-dropped') continue;
+    const dropped = count(event.count);
+    const reason = typeof event.reason === 'string' ? event.reason : 'unknown reason';
+    caveats.push(`${event.kind}: ${dropped ?? 'unknown'} record(s) dropped (${reason}); response evidence may be truncated.`);
+  }
+  return caveats;
+}
+
+interface FrameDelta {
+  readonly timestampMs: number;
+  readonly diffPixelCount: number;
+  readonly source: string;
+}
+
+function frameRecordTime(frame: FrameRecord, markers: Markers): number | null {
+  const native = finite(frame.screencastTimestamp) ? frame.screencastTimestamp : finite(frame.timestamp) ? frame.timestamp : null;
+  return native === null ? null : framePerformance(native, markers);
+}
+
+function frameDeltasFromRecords(frames: readonly FrameRecord[], markers: Markers): FrameDelta[] {
+  return frames
+    .map((frame, index) => ({ frame, index, timestampMs: frameRecordTime(frame, markers), diffPixelCount: count(frame.diffPixelCount) }))
+    .filter((item): item is { frame: FrameRecord; index: number; timestampMs: number; diffPixelCount: number } => item.timestampMs !== null && item.diffPixelCount !== null)
+    .sort((a, b) => a.timestampMs - b.timestampMs)
+    .map((item) => ({ timestampMs: item.timestampMs, diffPixelCount: item.diffPixelCount, source: `frame delta ${item.index}` }));
+}
+
+function firstPaintDelta(frameDeltas: readonly FrameDelta[], startMs: number, endMs: number | null): CandidatePoint | null {
+  const delta = frameDeltas.find((item) => item.diffPixelCount > 0 && item.timestampMs >= startMs && (endMs === null || item.timestampMs < endMs));
+  return delta ? { stage: 'paint', timestampMs: delta.timestampMs, precision: 'frame', source: `${delta.source} (${delta.diffPixelCount} changed pixel(s))` } : null;
+}
+
+function settlePoint(frameDeltas: readonly FrameDelta[], candidates: readonly CandidatePoint[], startMs: number, endMs: number | null): CandidatePoint | null {
+  const lastSignalMs = Math.max(startMs, ...candidates.filter((point) => inWindow(point, startMs, endMs)).map((point) => point.timestampMs));
+  let consecutiveIdentical = 0;
+  for (const delta of frameDeltas) {
+    if (delta.timestampMs < lastSignalMs || (endMs !== null && delta.timestampMs >= endMs)) continue;
+    if (delta.diffPixelCount === 0) consecutiveIdentical += 1;
+    else consecutiveIdentical = 0;
+    if (consecutiveIdentical >= 2 && delta.timestampMs - lastSignalMs >= 300) {
+      return { stage: 'settle', timestampMs: delta.timestampMs, precision: 'frame', source: 'two consecutive identical frame deltas; no scoped DOM/network/layout/paint signal for ≥300ms' };
+    }
+  }
+  return null;
+}
+
+function firstStage(candidates: readonly CandidatePoint[], stage: ResponseStage, startMs: number, endMs: number | null): CandidatePoint | null {
+  return candidates.filter((point) => point.stage === stage && inWindow(point, startMs, endMs)).sort((a, b) => a.timestampMs - b.timestampMs)[0] ?? null;
+}
+
+/**
+ * Reduces recorder artifacts into response facts. It never invents a stage:
+ * absent/unusable evidence is reported as unavailable, and settle is emitted
+ * only from action-scoped identical-frame + quiet-window evidence.
+ */
+export function responseTimelineFromArtifacts(
+  action: string,
+  events: readonly EventRecord[],
+  frames: readonly FrameRecord[],
+  markers: Markers,
+  state: string,
+  occurrence?: number,
+): ResponseTimeline {
+  if (!finite(markers.performanceNowMs)) throw new Error('markers.json has no finite performanceNowMs baseline; re-record with `capture motion rec`.');
+  const caveats = eventDropCaveats(events);
+  if (markers.baselinesPending) caveats.push('markers.json still has baselinesPending=true; timing sources without anchors are omitted rather than aligned approximately.');
+  if (state === 'orphaned-finalized') caveats.push('recording state is orphaned-finalized; artifacts are a partial best-effort recording from data flushed before recorder exit.');
+  if (state === 'partial') caveats.push('recording state is partial (no_frames); retained source records are readable, while frame-derived paint and settle facts are unavailable.');
+  if (!finite(markers.wallClockMs)) caveats.push('screencast wall-clock anchor unavailable; frame-derived paint and settle timing are unavailable.');
+
+  const actions = inputMarks(events, markers);
+  const selected = selectAction(actions, action, occurrence);
+  const nextAction = actions.find((item) => item.startMs > selected.startMs);
+  const actionWindowEndMs = nextAction?.startMs ?? null;
+
+  const candidates: CandidatePoint[] = [];
+  for (const event of events) {
+    const timestampMs = observerPerformance(event, markers);
+    if (timestampMs === null) continue;
+    if (event.kind === 'mutation') candidates.push({ stage: 'mutation', timestampMs, precision: 'exact', source: 'MutationObserver' });
+    if (event.kind === 'resize' || (event.kind === 'performance' && event.entryType === 'layout')) candidates.push({ stage: 'layout', timestampMs, precision: 'exact', source: event.kind === 'resize' ? 'ResizeObserver' : 'PerformanceObserver layout entry' });
+    if (event.kind === 'performance' && event.entryType === 'paint') candidates.push({ stage: 'paint', timestampMs, precision: 'exact', source: 'PerformanceObserver paint entry' });
+    if (event.kind === 'network') candidates.push({ stage: 'network', timestampMs, precision: 'exact', source: 'network event' });
+    if (event.kind === 'performance' && event.entryType === 'longtask') candidates.push({ stage: 'longtask', timestampMs, precision: 'exact', source: 'PerformanceObserver longtask entry' });
+  }
+
+  for (const trace of traceEvents(events, markers, caveats)) {
+    if (/layout|updatelayouttree/i.test(trace.name)) candidates.push({ stage: 'layout', timestampMs: trace.timestampMs, precision: 'exact', source: `Tracing ${trace.name}` });
+    else if (/paint|composite|drawframe/i.test(trace.name)) candidates.push({ stage: 'paint', timestampMs: trace.timestampMs, precision: 'exact', source: `Tracing ${trace.name}` });
+    else if (/network|resource(send|receive|finish)|load/i.test(trace.name)) candidates.push({ stage: 'network', timestampMs: trace.timestampMs, precision: 'exact', source: `Tracing ${trace.name}` });
+    else if (/(longtask|run(task|microtasks)|task)/i.test(trace.name) && (trace.durationMs ?? 0) >= 50) candidates.push({ stage: 'longtask', timestampMs: trace.timestampMs, precision: 'exact', source: `Tracing ${trace.name}` });
+  }
+
+  const frameDeltas = frameDeltasFromRecords(frames, markers);
+  const paintFromFrames = firstPaintDelta(frameDeltas, selected.startMs, actionWindowEndMs);
+  if (paintFromFrames) candidates.push(paintFromFrames);
+
+  const points: ResponsePoint[] = [{ stage: 'input', timestampMs: selected.startMs, deltaMs: 0, precision: 'exact', source: `input dispatch mark (occurrence ${selected.occurrence})` }];
+  for (const stage of ['mutation', 'layout', 'paint', 'network', 'longtask'] as const) {
+    const point = firstStage(candidates, stage, selected.startMs, actionWindowEndMs);
+    if (point) points.push({ ...point, deltaMs: point.timestampMs - selected.startMs });
+  }
+  const settle = settlePoint(frameDeltas, candidates, selected.startMs, actionWindowEndMs);
+  if (settle) points.push({ ...settle, deltaMs: settle.timestampMs - selected.startMs });
+
+  points.sort((a, b) => a.timestampMs - b.timestampMs || a.stage.localeCompare(b.stage));
+
+  const present = new Set(points.map((point) => point.stage));
+  const unavailableStages = ['mutation', 'layout', 'paint', 'network', 'settle'].filter((stage) => !present.has(stage as ResponseStage));
+  if (unavailableStages.includes('paint') && frameDeltas.length === 0) caveats.push('paint-different frame unavailable: no readable adjacent frame deltas with wall-clock-aligned timestamps.');
+  if (unavailableStages.includes('settle')) caveats.push('settle unavailable: this action window has no two consecutive identical frame deltas after ≥300ms without scoped response signals.');
+
+  return {
+    action: selected.label,
+    inputStartMs: selected.startMs,
+    inputEndMs: selected.endMs,
+    actionWindowEndMs,
+    points,
+    unavailableStages,
+    caveats,
+    state,
+    timingNote: 'Timestamps use performance.now() relative to recorder arm; observer points use PerformanceEntry.startTime when present, trace points require a real trace alignment marker, and frame-derived points use the screencast wall-clock anchor with ±1 frame uncertainty.',
+  };
+}
+
+export interface LoadedResponseTimeline {
+  readonly ref: RecRef;
+  readonly timeline: ResponseTimeline;
+  readonly availableActions: readonly string[];
+}
+
+function withFrameDeltas(ref: RecRef, rects: readonly FrameRecord[], markers: Markers): FrameRecord[] {
+  const framesDir = artifactPath(ref, 'frames', { mustExist: false });
+  if (!fs.existsSync(framesDir) || !fs.statSync(framesDir).isDirectory()) return [...rects];
+  const files = fs.readdirSync(framesDir).filter((name) => name.endsWith('.png')).sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  if (files.length < 2) return [...rects];
+  const byFile = new Map(rects.filter((record) => typeof record.file === 'string').map((record) => [record.file as string, record]));
+  const workDir = path.join(ref.dir, '.response-diff-work');
+  ensurePrivateDir(workDir);
+  try {
+    const output: FrameRecord[] = [...rects];
+    for (let i = 0; i < files.length - 1; i++) {
+      const before = path.join(framesDir, files[i]);
+      const after = path.join(framesDir, files[i + 1]);
+      const diffPath = path.join(workDir, `pair-${String(i).padStart(6, '0')}.png`);
+      const diff = diffPngs(before, after, diffPath, { diffMask: true });
+      if (!diff.ok) continue;
+      const afterRecord = byFile.get(files[i + 1]);
+      if (afterRecord) output.push({ ...afterRecord, diffPixelCount: diff.diffPixelCount });
+      else output.push({ file: files[i + 1], screencastTimestamp: undefined, timestamp: undefined, frame: i + 1, diffPixelCount: diff.diffPixelCount });
+    }
+    return output;
+  } finally {
+    fs.rmSync(workDir, { recursive: true, force: true });
+  }
+}
+
+/** Resolves recording artifacts that contain a completed evidence inventory before reading its response facts. */
+export function loadResponseTimeline(rec: string, action?: string, occurrence?: number): LoadedResponseTimeline {
+  const ref = resolveRecRef(rec);
+  const meta = readMeta<{ state?: unknown; reason?: unknown }>(ref);
+  const state = typeof meta.state === 'string' ? meta.state : 'unknown';
+  const readablePartial = state === 'partial' && meta.reason === 'no_frames';
+  if (state !== 'finalized' && state !== 'orphaned-finalized' && !readablePartial) {
+    throw new Error(`Recording ${JSON.stringify(ref.id)} is state ${JSON.stringify(state)}; finalize it with \`capture motion rec --stop\` before querying response.`);
+  }
+  const events = readEvents<EventRecord>(ref);
+  const markers = readMarkers<Markers>(ref);
+  if (!finite(markers.performanceNowMs)) throw new Error('markers.json has no finite performanceNowMs baseline; re-record with `capture motion rec`.');
+  const actions = inputMarks(events, markers);
+  if (!action && actions.length !== 1) throw new ResponseActionSelectionError(actions);
+  const selected = action ?? actions[0]?.label;
+  if (!selected) throw new ResponseActionSelectionError(actions);
+  const rects = readRects<FrameRecord>(ref);
+  const frames = withFrameDeltas(ref, rects, markers);
+  return { ref, timeline: responseTimelineFromArtifacts(selected, events, frames, markers, state, occurrence), availableActions: actions.map((item) => actionOccurrenceLabel(item)) };
+}
+
+function actionOccurrenceLabel(action: ActionMark): string {
+  return `${action.label} (occurrence ${action.occurrence}, t=${action.startMs.toFixed(2)}ms)`;
+}
+
+export class ResponseActionSelectionError extends Error {
+  readonly actions: readonly string[];
+  constructor(actions: readonly ActionMark[] | readonly string[], message?: string) {
+    const labels = actions.map((action) => typeof action === 'string' ? action : actionOccurrenceLabel(action));
+    super(message ?? (labels.length === 0 ? 'Recording has no injected input marks.' : 'Recording has multiple input marks; pass --action <unique action>.'));
+    this.name = 'ResponseActionSelectionError';
+    this.actions = labels;
+  }
+}

package/src/cdp/motion/timeline.ts

@@ -0,0 +1,215 @@
+import {
+  readEvents,
+  readMarkers,
+  readMeta,
+  readRects,
+  type RecRef,
+} from '../../output/artifact.js';
+
+export interface TimelineRect {
+  readonly tag?: unknown;
+  readonly id?: unknown;
+  readonly classes?: unknown;
+  readonly backendNodeId?: unknown;
+  readonly identityUnresolved?: unknown;
+  readonly x?: unknown;
+  readonly y?: unknown;
+  readonly width?: unknown;
+  readonly height?: unknown;
+  readonly scrollTop?: unknown;
+  readonly scrollLeft?: unknown;
+  readonly properties?: unknown;
+  readonly computed?: unknown;
+  readonly [key: string]: unknown;
+}
+
+export interface TimelineFrameRecord {
+  readonly frame?: unknown;
+  readonly screencastTimestamp?: unknown;
+  readonly elements?: unknown;
+}
+
+interface MarkerRecord {
+  readonly firstScreencastTimestampSec?: unknown;
+  readonly performanceNowMs?: unknown;
+}
+
+export interface TimelinePoint {
+  readonly frame: number;
+  /** Milliseconds from the recording's first sampled frame, in its screencast clock. */
+  readonly timeMs: number | null;
+  readonly timestampUncertainty: '±frame';
+  readonly elementId: number | null;
+  readonly tag: string | null;
+  readonly id: string | null;
+  readonly classes: string | null;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+  readonly scrollTop?: number;
+  readonly scrollLeft?: number;
+  readonly property?: { readonly name: string; readonly value: string | number | boolean | null };
+}
+
+export interface TimelineAnalysis {
+  readonly points: readonly TimelinePoint[];
+  readonly selectedBackendNodeId: number | null;
+  readonly selectionMethod: 'backend-node-id' | 'sample-label';
+  readonly frameCount: number;
+  readonly eventsRead: number;
+  readonly propertyAvailable: boolean;
+  readonly timingDomain: 'screencast-relative' | 'frame-order-only';
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}
+
+function roundMilliseconds(value: number): number {
+  return Math.round(value * 1000) / 1000;
+}
+
+function classTokens(value: unknown): string[] {
+  return typeof value === 'string' ? value.split(/\s+/).filter(Boolean) : [];
+}
+
+/**
+ * Recorder samples preserve tag/id/class labels and, where the identity
+ * bridge resolves it, backendNodeId. They do not preserve a DOM tree, so a
+ * full CSS selector cannot be evaluated after recording. This intentionally
+ * supports the label grammar that can be measured from that artifact and
+ * refuses unsupported combinators/attributes rather than pretending an
+ * arbitrary selector was matched.
+ */
+export function matchesRecordedSelector(element: TimelineRect, selector: string): boolean {
+  const trimmed = selector.trim();
+  if (!trimmed || /[\s>+~\[\]:,*]/.test(trimmed)) return false;
+
+  const match = /^(?<tag>[A-Za-z][A-Za-z0-9-]*)?(?<id>#[A-Za-z_][A-Za-z0-9_-]*)?(?<classes>(?:\.[A-Za-z_][A-Za-z0-9_-]*)*)$/.exec(trimmed);
+  if (!match?.groups) return false;
+  const tag = match.groups.tag;
+  const requestedId = match.groups.id?.slice(1);
+  const requestedClasses = [...(match.groups.classes?.matchAll(/\.([A-Za-z_][A-Za-z0-9_-]*)/g) ?? [])].map((m) => m[1]);
+  if (!tag && !requestedId && requestedClasses.length === 0) return false;
+
+  if (tag && stringOrNull(element.tag)?.toLowerCase() !== tag.toLowerCase()) return false;
+  if (requestedId && stringOrNull(element.id) !== requestedId) return false;
+  const classes = new Set(classTokens(element.classes));
+  return requestedClasses.every((name) => classes.has(name));
+}
+
+function elementLabel(element: TimelineRect): string {
+  return [stringOrNull(element.tag) ?? '', stringOrNull(element.id) ?? '', stringOrNull(element.classes) ?? ''].join('\u0000');
+}
+
+function propertyValue(element: TimelineRect, property: string): string | number | boolean | null | undefined {
+  const geometry: Record<string, unknown> = {
+    x: element.x,
+    y: element.y,
+    width: element.width,
+    height: element.height,
+    left: element.x,
+    top: element.y,
+    right: finiteNumber(element.x) !== null && finiteNumber(element.width) !== null ? finiteNumber(element.x)! + finiteNumber(element.width)! : undefined,
+    bottom: finiteNumber(element.y) !== null && finiteNumber(element.height) !== null ? finiteNumber(element.y)! + finiteNumber(element.height)! : undefined,
+    scrollTop: element.scrollTop,
+    scrollLeft: element.scrollLeft,
+  };
+  const direct = geometry[property];
+  if (typeof direct === 'string' || typeof direct === 'number' || typeof direct === 'boolean' || direct === null) return direct;
+  for (const container of [element.properties, element.computed]) {
+    if (container && typeof container === 'object') {
+      const value = (container as Record<string, unknown>)[property];
+      if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) return value;
+    }
+  }
+  return undefined;
+}
+
+/** Reads the finalized recording's sampled bounding boxes and produces the
+ * narrow, read-only timeline substrate used by the command leaf. */
+export function analyzeMotionTimeline(ref: RecRef, selector: string, property?: string): TimelineAnalysis {
+  const records = readRects<TimelineFrameRecord>(ref);
+  // events.jsonl is a required finalized-recording artifact. Reading it here
+  // makes a missing/corrupt event stream a structured resolver error instead
+  // of silently treating a partial recording as complete.
+  const events = readEvents<Record<string, unknown>>(ref);
+  const markers = readMarkers<MarkerRecord>(ref);
+
+  const frames = records
+    .map((record, index) => ({
+      frame: finiteNumber(record.frame) ?? index,
+      timestamp: finiteNumber(record.screencastTimestamp),
+      elements: Array.isArray(record.elements) ? record.elements.filter((e): e is TimelineRect => typeof e === 'object' && e !== null) : [],
+    }))
+    .sort((a, b) => a.frame - b.frame);
+
+  let selected: TimelineRect | undefined;
+  for (const frame of frames) {
+    selected = frame.elements.find((element) => matchesRecordedSelector(element, selector));
+    if (selected) break;
+  }
+  if (!selected) {
+    throw new MotionTimelineSelectionError(selector, frames.length);
+  }
+
+  const selectedBackendNodeId = finiteNumber(selected.backendNodeId);
+  const selectionMethod: TimelineAnalysis['selectionMethod'] = selectedBackendNodeId === null ? 'sample-label' : 'backend-node-id';
+  const selectedLabel = elementLabel(selected);
+  const baseline = finiteNumber(markers.firstScreencastTimestampSec)
+    ?? frames.find((frame) => frame.timestamp !== null)?.timestamp
+    ?? null;
+  const timingDomain: TimelineAnalysis['timingDomain'] = baseline === null ? 'frame-order-only' : 'screencast-relative';
+  let propertyAvailable = property === undefined;
+
+  const points: TimelinePoint[] = [];
+  for (const frame of frames) {
+    const element = selectedBackendNodeId !== null
+      ? frame.elements.find((candidate) => finiteNumber(candidate.backendNodeId) === selectedBackendNodeId)
+      : frame.elements.find((candidate) => elementLabel(candidate) === selectedLabel);
+    if (!element) continue;
+    const x = finiteNumber(element.x);
+    const y = finiteNumber(element.y);
+    const width = finiteNumber(element.width);
+    const height = finiteNumber(element.height);
+    if (x === null || y === null || width === null || height === null) continue;
+
+    const value = property === undefined ? undefined : propertyValue(element, property);
+    if (property !== undefined && value !== undefined) propertyAvailable = true;
+    points.push({
+      frame: frame.frame,
+      timeMs: baseline !== null && frame.timestamp !== null ? roundMilliseconds((frame.timestamp - baseline) * 1000) : null,
+      timestampUncertainty: '±frame',
+      elementId: finiteNumber(element.backendNodeId),
+      tag: stringOrNull(element.tag),
+      id: stringOrNull(element.id),
+      classes: stringOrNull(element.classes),
+      x,
+      y,
+      width,
+      height,
+      ...(finiteNumber(element.scrollTop) !== null ? { scrollTop: finiteNumber(element.scrollTop)! } : {}),
+      ...(finiteNumber(element.scrollLeft) !== null ? { scrollLeft: finiteNumber(element.scrollLeft)! } : {}),
+      ...(property !== undefined && value !== undefined ? { property: { name: property, value } } : {}),
+    });
+  }
+
+  return { points, selectedBackendNodeId, selectionMethod, frameCount: frames.length, eventsRead: events.length, propertyAvailable, timingDomain };
+}
+
+export class MotionTimelineSelectionError extends Error {
+  constructor(readonly selector: string, readonly frameCount: number) {
+    super(`No sampled element matched ${JSON.stringify(selector)} across ${frameCount} frame(s). Recorder timeline matching supports a tag, #id, .class, or their simple combination because rects.jsonl does not retain a DOM tree.`);
+    this.name = 'MotionTimelineSelectionError';
+  }
+}
+
+export function readTimelineMeta(ref: RecRef): { state: string; durationMs: number | null } {
+  const meta = readMeta<{ state?: unknown; durationMs?: unknown }>(ref);
+  return { state: typeof meta.state === 'string' ? meta.state : 'unknown', durationMs: finiteNumber(meta.durationMs) };
+}