CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

motion-compare.mjsskills/replica/scripts/

#!/usr/bin/env node
/**
 * skills/replica/scripts/motion-compare.mjs
 *
 * Interaction-parity ADVISORY for the stardust:replica motion pass: compares
 * two motion-observe.mjs outputs — one taken on the live source page, one on
 * the rebuilt page — and prints one greppable verdict line per observed
 * behavior plus a summary, in the same short vocabulary as gate.sh /
 * pixel-compare. It is a finding generator, NOT a gate: it exits 0 whenever
 * both inputs parsed, whatever the verdicts say.
 *
 * Policy (recreation-procedure.md § Interaction parity): motion is OBSERVED,
 * never inferred. A behavior that measurably fired on live should fire on the
 * build (else MISSING); a behavior that fired on the build but not on live is
 * probably invented motion (EXTRA); a behavior that was DEAD on live — the
 * probe ran but nothing changed — is NOT required on the build. For behaviors
 * present on both sides the timing (transition/animation time) and magnitude
 * (px) deltas are held to the tolerances.
 *
 * What a MISSING / EXTRA line IS: a finding the agent CONFIRMS on the `class`
 * lines (the trigger classes the live runtime added — the mechanism channel)
 * and on the element, then records in progress.json under
 * `motion: { observed, implemented, dead[] }` — observed = the live behaviors
 * that fired, implemented = the ones the build reproduces, dead[] = the ones
 * the sampler saw nothing for. It is never, by itself, a gate that blocks
 * approval: a hard fail here produced false blocks on class-toggled and
 * pseudo-element mechanics the sampler cannot see (a live carousel that fades
 * by toggling a class reads as "dead" to the frame sampler; a hover that moves
 * a ::after underline reads as "no diff" to the hover probe), and a build that
 * reproduced the live page faithfully was refused for it. A hover sample the
 * observer could not take (`hovered: false`, or an `.error` field) counts as
 * NOT OBSERVED — never as "dead on live" and never as evidence about the build.
 *
 * Where the instrument is blind, the verdict is advisory, never a hard EXTRA.
 * The widget frame sampler reads track/box transforms, scrollLeft and
 * indicator classes only, and the hover probe reads transform / color /
 * background / box-shadow / opacity / transition only — a live carousel that
 * fades by toggling a class, or a live hover that moves a pseudo-element
 * underline, reads as "dead" there while its class mutations show in the class
 * channel (recorded on a real page: a class-toggled carousel, four identical
 * frames, its --active classes in events.classMutations). So "dead on live,
 * fires on build" for a widget or hover, and a transitioned CSS property seen
 * on the build only, print as `extra on build — advisory`; the hard EXTRAs are
 * the complete channels: an entrance animation never fired on live, a header
 * scroll-morph the live header never made, a second header element. The class
 * channel assumes the replica prototype keeps the captured class names (it is
 * authored from the verbatim DOM); on a re-authored build read a class MISSING
 * as "missing or renamed" and confirm on the element.
 *
 * Behavior classes, keyed the way the observer records them:
 *   header      the chrome scroll-morph state machine from headerTimeline —
 *               height/transform/position change between the top and the
 *               scrolled state, the restore threshold on the way back up,
 *               main/body padding compensation, transition time, and the
 *               header count (a build that renders two headers at once is a
 *               state that cannot exist on live — always a finding).
 *   widget      one per --click poke (widgetSamples[]): change across the
 *               sampled frames in track transform / scrollLeft / box
 *               transform / indicator classes, its settle time and transition
 *               time (ms), and its travel (px).
 *   hover       one per --hover probe (hoverSamples[]): the changed-property
 *               set (sub-element keys normalised to tag.prop so re-authored
 *               class names cannot break the match) and transition time.
 *   entrance    one per animation name (events.animations): fired-element
 *               count must match (verification protocol: tagged-element count
 *               == live fired count).
 *   media       one per live <video> (media.videos[], paired by order) plus
 *               `auto-advance`: a video playing (or carrying autoplay) on live
 *               must play on the build — a paused/poster build is MISSING; class
 *               mutations that fired unpoked on live (timer rotation) must fire
 *               on the build. The gate's freeze stops both; the freeze is capture
 *               state, never the spec. Older observations without `media` compare
 *               as no media.
 *   transition  one per transitioned property (events.transitions): presence
 *               and the longest recorded duration.
 *   class       one per added trigger class (events.classMutations): a class
 *               the live runtime added but the build never adds is a missing
 *               mechanism; an extra class on the build is advisory only
 *               (class names are bookkeeping, not motion).
 *
 * Pairing widgets and hovers across the two runs: by identical selector first;
 * leftover probes are then paired in order (the i-th unpaired live poke with
 * the i-th unpaired build poke), so a build observed with re-authored
 * selectors still compares as long as the pokes were issued in the same order.
 *
 * Usage:
 *   node skills/replica/scripts/motion-compare.mjs <live.json> <build.json> [options]
 *     --tolerance-ms <n>   timing tolerance in ms                 (default 150)
 *     --tolerance-px <n>   magnitude tolerance in px              (default 8)
 *     --json <out>         also write the machine-readable summary
 *     --help               this text
 *
 * Verdict lines (stdout), one per behavior:
 *   motion <class> <name>: parity (…)
 *   motion <class> <name>: MISSING on build (…)
 *   motion <class> <name>: EXTRA on build (…)
 *   motion <class> <name>: timing delta 420ms > 150ms (…)
 *   motion <class> <name>: magnitude delta 24px > 8px (…)
 *   motion <class> <name>: dead on live — not required (…)
 *   motion <class> <name>: unobserved on live — not required (…)   probe failed / not hovered
 *   motion <class> <name>: extra on build — advisory (…)
 * then the final line
 *   motion summary: <n> parity, <n> missing, <n> extra, <n> advisory (<n> out of tolerance,
 *                   <n> dead or unobserved on live — not required; tolerance <ms>ms / <px>px)
 *
 * Writes: nothing — unless --json <out>, which receives { live, build, toleranceMs,
 * tolerancePx, advisory: true, counts, verdicts[] } (directories created).
 *
 * Exit codes: 0 both inputs parsed — ALWAYS, whatever the verdicts (advisory,
 * not a gate); 1 an input is unreadable or not a motion-observe object;
 * 2 usage error.
 * Resolution note: widget settle time is read from the observer's ~200 ms
 * frame grid, so a one-frame settle difference exceeds the default tolerance —
 * that is the instrument's resolution, not noise; raise --tolerance-ms to
 * 250 when a coarser bar is intended.
 */

/* eslint-disable no-restricted-syntax, brace-style, object-curly-newline, max-len */
import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';

const HELP = `motion-compare — interaction-parity findings from two motion-observe JSONs (advisory, not a gate)

Usage: node motion-compare.mjs <live.json> <build.json> [options]
  --tolerance-ms <n>  timing tolerance in ms (default 150)
  --tolerance-px <n>  magnitude tolerance in px (default 8)
  --json <out>        also write the machine-readable summary
  --help              this text

Convention: <live.json> = observation of the live source page, <build.json> =
observation of the rebuilt page (same observer, same pokes in the same order).
A MISSING / EXTRA line is a finding to confirm on the class lines and record in
progress.json (motion: {observed, implemented, dead[]}) — never a block by itself.
Exit codes: 0 both inputs parsed (always, whatever the verdicts), 1 unreadable
input, 2 usage.`;

const USAGE_EXIT = 2;
const INPUT_EXIT = 1;

function usage(msg) { console.error(`motion-compare error: ${msg}\n\n${HELP}`); process.exit(USAGE_EXIT); }
function inputError(msg) { console.error(`motion-compare error: ${msg}`); process.exit(INPUT_EXIT); }

function parseArgs(argv) {
  const rest = argv.slice(2);
  if (rest.includes('--help') || rest.includes('-h')) { console.log(HELP); process.exit(0); }
  const pos = [];
  const opts = { toleranceMs: 150, tolerancePx: 8, json: null };
  // A value flag followed by nothing or by another --flag is a usage error naming the flag.
  const need = (i, flag) => { if (i + 1 >= rest.length || rest[i + 1].startsWith('--')) usage(`${flag} needs a value`); return rest[i + 1]; };
  for (let i = 0; i < rest.length; i += 1) {
    const a = rest[i];
    if (a === '--tolerance-ms') { opts.toleranceMs = Number(need(i, a)); i += 1; }
    else if (a === '--tolerance-px') { opts.tolerancePx = Number(need(i, a)); i += 1; }
    else if (a === '--json') { opts.json = need(i, a); i += 1; }
    else if (a.startsWith('--')) usage(`unknown flag ${a}`);
    else pos.push(a);
  }
  if (pos.length !== 2) usage('need <live.json> and <build.json>');
  if (!Number.isFinite(opts.toleranceMs) || opts.toleranceMs < 0) usage('--tolerance-ms must be a non-negative number');
  if (!Number.isFinite(opts.tolerancePx) || opts.tolerancePx < 0) usage('--tolerance-px must be a non-negative number');
  return { livePath: pos[0], buildPath: pos[1], opts };
}

// ---- input ------------------------------------------------------------------------------------

// An unreadable or non-motion-observe input is exit 1 (the file is wrong), distinct from exit 2
// (the command line is wrong) — so a caller can tell "re-run the observer" from "fix the flags".
function loadObservation(path, label) {
  let doc;
  try { doc = JSON.parse(readFileSync(path, 'utf8')); } catch (e) { inputError(`cannot read ${label} ${path}: ${e.message}`); }
  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) inputError(`${label} ${path} is not a motion-observe object`);
  const missing = ['headerTimeline', 'widgetSamples', 'hoverSamples', 'events'].filter((k) => !(k in doc));
  if (missing.length) inputError(`${label} ${path} lacks motion-observe keys: ${missing.join(', ')}`);
  const arr = (v) => (Array.isArray(v) ? v : []);
  const ev = doc.events && typeof doc.events === 'object' ? doc.events : {};
  const md = doc.media && typeof doc.media === 'object' ? doc.media : {};
  return {
    url: doc.url, width: doc.width,
    headerTimeline: arr(doc.headerTimeline), widgetSamples: arr(doc.widgetSamples), hoverSamples: arr(doc.hoverSamples),
    media: { videos: arr(md.videos), idleClassMutationCount: Number(md.idleClassMutationCount) || 0 },
    events: { animations: arr(ev.animations), transitions: arr(ev.transitions), classMutations: arr(ev.classMutations) },
  };
}

// ---- small parsers ----------------------------------------------------------------------------

// Longest time token in a CSS time list / transition shorthand ("0.5s, 0.5s", "all 0.3s ease 0s",
// "300ms"). Null when no explicit time appears (a bare "all" or "none").
export function maxTimeMs(str) {
  if (typeof str !== 'string') return null;
  let best = null;
  for (const m of str.matchAll(/(-?\d*\.?\d+)(ms|s)\b/g)) {
    const v = Number(m[1]) * (m[2] === 's' ? 1000 : 1);
    if (best === null || v > best) best = v;
  }
  return best;
}

export const px = (v) => { const n = parseFloat(v); return Number.isFinite(n) ? n : null; };

// Translation vector of a computed transform ("matrix(a,b,c,d,tx,ty)" / "matrix3d(…)" / "none").
export function translateOf(t) {
  if (typeof t !== 'string' || t === 'none') return { x: 0, y: 0 };
  const args = t.slice(t.indexOf('(') + 1); // skip the function name ("matrix3d" carries a digit)
  const nums = args.match(/-?\d*\.?\d+(?:e[-+]?\d+)?/g)?.map(Number) || [];
  if (t.startsWith('matrix3d') && nums.length >= 14) return { x: nums[12], y: nums[13] };
  if (t.startsWith('matrix') && nums.length >= 6) return { x: nums[4], y: nums[5] };
  return { x: 0, y: 0 };
}

const fmtMs = (v) => (v === null || v === undefined ? 'n/a' : `${Math.round(v)}ms`);
const fmtPx = (v) => (v === null || v === undefined ? 'n/a' : `${Math.round(v * 10) / 10}px`);
const near = (a, b, tol) => Math.abs(a - b) <= tol;

// ---- verdict assembly ---------------------------------------------------------------------------

// A verdict is { cls, name, state, note, deltas } where state ∈ parity | missing | extra |
// tolerance | dead | unobserved | advisory. missing/extra/tolerance are FINDINGS (the agent confirms
// them on the class lines and the element); none of them changes the exit code — advisory, not a gate.
const FINDING = new Set(['missing', 'extra', 'tolerance']);

function verdictLine(v) {
  const head = `motion ${v.cls} ${v.name}:`;
  const tail = v.note ? ` (${v.note})` : '';
  switch (v.state) {
    case 'parity': return `${head} parity${tail}`;
    case 'missing': return `${head} MISSING on build${tail}`;
    case 'extra': return `${head} EXTRA on build${tail}`;
    case 'tolerance': return `${head} ${v.deltas.join('; ')}${tail}`;
    case 'dead': return `${head} dead on live — not required${tail}`;
    case 'unobserved': return `${head} unobserved on live — not required${tail}`;
    case 'advisory': return `${head} extra on build — advisory${tail}`;
    default: return `${head} ${v.state}${tail}`;
  }
}

// Compare a list of measured deltas: each { kind: 'timing'|'magnitude', label, live, build }.
// Returns the out-of-tolerance descriptions (empty = within tolerance). Null on either side
// (not measurable there) is compared only when both sides have a value.
function outOfTolerance(measures, { toleranceMs, tolerancePx }) {
  const out = [];
  for (const m of measures) {
    if (m.live === null || m.live === undefined || m.build === null || m.build === undefined) continue;
    const tol = m.kind === 'timing' ? toleranceMs : tolerancePx;
    const d = Math.abs(m.live - m.build);
    if (d > tol) {
      const f = m.kind === 'timing' ? fmtMs : fmtPx;
      out.push(`${m.kind} delta ${f(d)} > ${f(tol)}${m.label ? ` [${m.label}: live ${f(m.live)}, build ${f(m.build)}]` : ''}`);
    }
  }
  return out;
}

// ---- header -----------------------------------------------------------------------------------

// Reduce a headerTimeline to its state machine: top state, scrolled state (deepest sample), restore
// threshold on the way up, padding compensation, transition time, max header count.
export function headerProfile(timeline) {
  const samples = timeline.filter((s) => s && typeof s === 'object');
  if (!samples.length) return { present: false, morphs: false, maxCount: 0 };
  const key = (s) => `${px(s.height)}|${s.transform || ''}|${s.position || ''}`;
  const top = samples[0];
  let deepIdx = 0;
  samples.forEach((s, i) => { if ((s.y || 0) > (samples[deepIdx].y || 0)) deepIdx = i; });
  const deep = samples[deepIdx];
  const morphs = samples.some((s) => key(s) !== key(top));
  // Restore threshold: first sample after the deepest one that is back in the top state. Both runs
  // sample the same y grid near the top; the two document-height-relative samples that start the
  // upward pass are collapsed to "immediately" so a different page height cannot read as a delta.
  let restoreY = null;
  let restoreImmediate = false;
  for (let i = deepIdx + 1; i < samples.length; i += 1) {
    if (key(samples[i]) === key(top)) { restoreY = samples[i].y || 0; restoreImmediate = i <= deepIdx + 2 && restoreY > 2400; break; }
  }
  const pad = (s, k) => px(s[k]);
  const comp = (k) => (pad(top, k) !== null && pad(deep, k) !== null ? Math.abs(pad(deep, k) - pad(top, k)) : null);
  let timeMs = null;
  for (const s of samples) { const t = maxTimeMs(s.transition); if (t !== null && (timeMs === null || t > timeMs)) timeMs = t; }
  return {
    present: true, morphs,
    topHeight: px(top.height), deepHeight: px(deep.height),
    heightDelta: px(top.height) !== null && px(deep.height) !== null ? Math.abs(px(top.height) - px(deep.height)) : null,
    positionChanges: top.position !== deep.position, transformChanges: (top.transform || 'none') !== (deep.transform || 'none'),
    restoreY, restoreImmediate,
    mainComp: comp('mainPadTop'), bodyComp: comp('bodyPadTop'),
    timeMs,
    maxCount: Math.max(...samples.map((s) => Number(s.headerCount) || 0)),
  };
}

// Header transition time may also live in the event log (the chrome's own transitionstart
// events name the header element in their path).
function headerEventTimeMs(events) {
  let best = null;
  for (const t of events.transitions) {
    if (!/header/i.test(String(t.el || ''))) continue;
    const v = maxTimeMs(t.dur);
    if (v !== null && (best === null || v > best)) best = v;
  }
  return best;
}

function compareHeader(live, build, opts) {
  const out = [];
  const L = headerProfile(live.headerTimeline);
  const B = headerProfile(build.headerTimeline);
  const lt = L.timeMs ?? headerEventTimeMs(live.events);
  const bt = B.timeMs ?? headerEventTimeMs(build.events);
  if (!L.present && !B.present) return out; // neither page has a header element: nothing to say
  if (!L.morphs) {
    const liveNote = L.present ? 'live header static across the scroll traversal' : 'no header element observed on live';
    out.push(B.morphs
      ? { cls: 'header', name: 'scroll-morph', state: 'extra', note: `${liveNote}, build changes ${fmtPx(B.heightDelta)}` }
      : { cls: 'header', name: 'scroll-morph', state: 'dead', note: L.present ? 'header static across the scroll traversal on both sides' : `${liveNote}; build header ${B.present ? 'static' : 'absent'}` });
  } else if (!B.morphs) {
    out.push({ cls: 'header', name: 'scroll-morph', state: 'missing', note: `live morphs ${fmtPx(L.heightDelta)} at depth${L.positionChanges ? ', position changes' : ''}${L.transformChanges ? ', transform changes' : ''}; build static` });
  } else {
    const deltas = outOfTolerance([
      { kind: 'magnitude', label: 'height change', live: L.heightDelta, build: B.heightDelta },
      { kind: 'magnitude', label: 'main padding compensation', live: L.mainComp, build: B.mainComp },
      { kind: 'magnitude', label: 'body padding compensation', live: L.bodyComp, build: B.bodyComp },
      { kind: 'timing', label: 'transition', live: lt, build: bt },
    ], opts);
    const restoreDelta = [];
    if (L.restoreY !== null && B.restoreY !== null) {
      if (!(L.restoreImmediate && B.restoreImmediate) && !near(L.restoreY, B.restoreY, opts.tolerancePx)) restoreDelta.push(`magnitude delta ${fmtPx(Math.abs(L.restoreY - B.restoreY))} > ${fmtPx(opts.tolerancePx)} [restore threshold: live y≤${L.restoreY}, build y≤${B.restoreY}]`);
    } else if ((L.restoreY === null) !== (B.restoreY === null)) {
      restoreDelta.push(`restore threshold: live ${L.restoreY === null ? 'never restores' : `y≤${L.restoreY}`}, build ${B.restoreY === null ? 'never restores' : `y≤${B.restoreY}`}`);
    }
    const mech = [];
    if (L.positionChanges !== B.positionChanges) mech.push(`position ${L.positionChanges ? 'changes' : 'stays'} on live, ${B.positionChanges ? 'changes' : 'stays'} on build`);
    if (L.transformChanges !== B.transformChanges) mech.push(`transform ${L.transformChanges ? 'changes' : 'stays'} on live, ${B.transformChanges ? 'changes' : 'stays'} on build`);
    const all = [...deltas, ...restoreDelta, ...mech];
    const summary = `Δheight ${fmtPx(L.heightDelta)}, restore ${L.restoreImmediate ? 'on first upward sample' : L.restoreY === null ? 'never' : `at y≤${L.restoreY}`}, ${fmtMs(lt)}`;
    out.push(all.length
      ? { cls: 'header', name: 'scroll-morph', state: 'tolerance', deltas: all, note: summary }
      : { cls: 'header', name: 'scroll-morph', state: 'parity', note: summary });
  }
  if (B.maxCount > Math.max(1, L.maxCount)) {
    out.push({ cls: 'header', name: 'count', state: 'extra', note: `${B.maxCount} header elements rendered on build vs ${L.maxCount} on live — a double-rendered chrome state that cannot exist on live` });
  }
  return out;
}

// ---- widgets ----------------------------------------------------------------------------------

// Reduce one poke's frames to: whether anything changed, when it settled (ms after the first frame),
// travel in px (scrollLeft or track/box translate), and the longest transition time declared.
export function widgetProfile(sample) {
  if (!sample || sample.error || !Array.isArray(sample.frames) || !sample.frames.length) return { observed: false, error: sample?.error || 'no frames' };
  const frames = sample.frames;
  const sig = (f) => JSON.stringify([f.trackTransform, f.boxScrollLeft, f.boxTransform, (f.dots || []).map((d) => [d.cls, d.w, d.h, d.bg])]);
  let lastChange = -1;
  for (let i = 1; i < frames.length; i += 1) if (sig(frames[i]) !== sig(frames[i - 1])) lastChange = i;
  const fired = lastChange >= 0;
  const t0 = Number(frames[0].t) || 0;
  const settleMs = fired ? (Number(frames[lastChange].t) || 0) - t0 : null;
  const first = frames[0];
  const last = frames[frames.length - 1];
  let travel = null;
  if (typeof first.boxScrollLeft === 'number' && typeof last.boxScrollLeft === 'number' && first.boxScrollLeft !== last.boxScrollLeft) travel = Math.abs(last.boxScrollLeft - first.boxScrollLeft);
  else {
    const a = translateOf(first.trackTransform !== null && first.trackTransform !== undefined ? first.trackTransform : first.boxTransform);
    const b = translateOf(last.trackTransform !== null && last.trackTransform !== undefined ? last.trackTransform : last.boxTransform);
    const d = Math.hypot(a.x - b.x, a.y - b.y);
    if (d > 0) travel = d;
  }
  let timeMs = null;
  for (const f of frames) {
    for (const s of [f.trackTransition, ...(f.dots || []).map((d) => d.transition)]) { const v = maxTimeMs(s); if (v !== null && (timeMs === null || v > timeMs)) timeMs = v; }
  }
  const dotChange = frames.some((f, i) => i > 0 && JSON.stringify((f.dots || []).map((d) => d.cls)) !== JSON.stringify((frames[i - 1].dots || []).map((d) => d.cls)));
  return { observed: true, fired, settleMs, travel, timeMs, dotChange };
}

// Pair probes by selector, then leftovers in order.
export function pairProbes(liveList, buildList) {
  const pairs = [];
  const usedB = new Set();
  liveList.forEach((l, i) => {
    const j = buildList.findIndex((b, k) => !usedB.has(k) && b && l && b.sel === l.sel);
    if (j >= 0) { usedB.add(j); pairs.push({ live: l, build: buildList[j], liveIdx: i, buildIdx: j, by: 'selector' }); }
    else pairs.push({ live: l, build: null, liveIdx: i, buildIdx: -1, by: null });
  });
  const leftoverB = buildList.map((_, k) => k).filter((k) => !usedB.has(k));
  for (const p of pairs) {
    if (p.build === null && leftoverB.length) { p.buildIdx = leftoverB.shift(); p.build = buildList[p.buildIdx]; p.by = 'order'; }
  }
  for (const k of leftoverB) pairs.push({ live: null, build: buildList[k], liveIdx: -1, buildIdx: k, by: null });
  return pairs;
}

const probeName = (p) => {
  const ls = p.live?.sel; const bs = p.build?.sel;
  if (ls && bs && ls !== bs) return `${ls} → ${bs}`;
  return ls || bs || `#${Math.max(p.liveIdx, p.buildIdx) + 1}`;
};

// "Dead on live, fires on build" is advisory for widgets and hovers: the sampler sees only some
// mechanisms (header comment), so the class lines and the behavior-match protocol decide, not this gate.
const SAMPLER_NOTE = 'live mechanics may be invisible to the frame sampler (class-toggled fades, non-track carousels) — confirm against the class lines before treating it as invented';
const HOVER_NOTE = 'live mechanics may be invisible to the hover probe (pseudo-element underlines, text-decoration, border-color) — confirm on the element before treating it as invented';

function compareWidgets(live, build, opts) {
  const out = [];
  for (const p of pairProbes(live.widgetSamples, build.widgetSamples)) {
    const name = probeName(p);
    const L = p.live ? widgetProfile(p.live) : null;
    const B = p.build ? widgetProfile(p.build) : null;
    if (!L) { // observed on the build only
      out.push(B.observed && B.fired
        ? { cls: 'widget', name, state: 'advisory', note: 'poked on the build only; no live observation of this control' }
        : { cls: 'widget', name, state: 'unobserved', note: 'poked on the build only, no change sampled' });
      continue;
    }
    if (!L.observed) {
      out.push(B && B.observed && B.fired
        ? { cls: 'widget', name, state: 'advisory', note: `live probe ${L.error}; build changes on click — ${SAMPLER_NOTE}` }
        : { cls: 'widget', name, state: 'unobserved', note: `live probe ${L.error}` });
      continue;
    }
    if (!L.fired) {
      out.push(B && B.observed && B.fired
        ? { cls: 'widget', name, state: 'advisory', note: `no sampled change on live; build changes on click — ${SAMPLER_NOTE}` }
        : { cls: 'widget', name, state: 'dead', note: 'no sampled change across the frames (track/scroll/box/indicator)' });
      continue;
    }
    const liveNote = `travel ${fmtPx(L.travel)}, settle ${fmtMs(L.settleMs)}, transition ${fmtMs(L.timeMs)}${L.dotChange ? ', indicator changes' : ''}`;
    if (!B) { out.push({ cls: 'widget', name, state: 'missing', note: `no build poke pairs with it; live ${liveNote}` }); continue; }
    if (!B.observed) { out.push({ cls: 'widget', name, state: 'missing', note: `build probe ${B.error}; live ${liveNote}` }); continue; }
    if (!B.fired) { out.push({ cls: 'widget', name, state: 'missing', note: `no sampled change on build; live ${liveNote}` }); continue; }
    const deltas = outOfTolerance([
      { kind: 'timing', label: 'settle', live: L.settleMs, build: B.settleMs },
      { kind: 'timing', label: 'transition', live: L.timeMs, build: B.timeMs },
      { kind: 'magnitude', label: 'travel', live: L.travel, build: B.travel },
    ], opts);
    if (L.dotChange && !B.dotChange) deltas.push('indicator classes change on live, not on build');
    if (!L.dotChange && B.dotChange) deltas.push('indicator classes change on build, not on live');
    out.push(deltas.length
      ? { cls: 'widget', name, state: 'tolerance', deltas, note: `live ${liveNote}${p.by === 'order' ? '; paired by order' : ''}` }
      : { cls: 'widget', name, state: 'parity', note: `${liveNote}${p.by === 'order' ? '; paired by order' : ''}` });
  }
  return out;
}

// ---- hovers -----------------------------------------------------------------------------------

// Normalise a changed-property key: "self.color" stays; "span.icon.brand.color" → "span.color" (the
// sub-element's classes are re-authored on the build; its tag and the property are the identity).
export const normaliseHoverKey = (k) => {
  const s = String(k);
  if (s.startsWith('self.')) return s;
  const parts = s.split('.');
  return parts.length >= 2 ? `${parts[0]}.${parts[parts.length - 1]}` : s;
};

// `hovered: false` (the observer could not hover the element — off-screen, covered, detached) or an
// `.error` field is NOT OBSERVED: nothing is known about the live hover, so it is never read as "dead
// on live" (which would license the build to drop it) and never as evidence about the build.
export function hoverProfile(sample) {
  if (!sample || sample.error || sample.hovered === false) return { observed: false, error: sample?.error || (sample && sample.hovered === false ? 'not hovered' : 'no sample') };
  const changed = [...new Set((Array.isArray(sample.changed) ? sample.changed : []).map(normaliseHoverKey))].sort();
  let timeMs = null;
  const after = sample.after || {};
  for (const s of [after.self?.transition, ...((after.subs || []).map((x) => x && x.transition))]) { const v = maxTimeMs(s); if (v !== null && (timeMs === null || v > timeMs)) timeMs = v; }
  return { observed: true, fired: changed.length > 0, changed, timeMs };
}

function compareHovers(live, build, opts) {
  const out = [];
  for (const p of pairProbes(live.hoverSamples, build.hoverSamples)) {
    const name = probeName(p);
    const L = p.live ? hoverProfile(p.live) : null;
    const B = p.build ? hoverProfile(p.build) : null;
    if (!L) {
      out.push(B.observed && B.fired
        ? { cls: 'hover', name, state: 'advisory', note: `hovered on the build only; changes ${B.changed.join(', ')}` }
        : { cls: 'hover', name, state: 'unobserved', note: 'hovered on the build only, no diff' });
      continue;
    }
    if (!L.observed) {
      out.push(B && B.observed && B.fired
        ? { cls: 'hover', name, state: 'advisory', note: `live probe ${L.error}; build changes ${B.changed.join(', ')} — ${HOVER_NOTE}` }
        : { cls: 'hover', name, state: 'unobserved', note: `live probe ${L.error}` });
      continue;
    }
    if (!L.fired) {
      out.push(B && B.observed && B.fired
        ? { cls: 'hover', name, state: 'advisory', note: `no hover diff on live; build changes ${B.changed.join(', ')} — ${HOVER_NOTE}` }
        : { cls: 'hover', name, state: 'dead', note: 'no measured hover diff' });
      continue;
    }
    const liveNote = `${L.changed.join(', ')}; ${fmtMs(L.timeMs)}`;
    if (!B) { out.push({ cls: 'hover', name, state: 'missing', note: `no build probe pairs with it; live changes ${liveNote}` }); continue; }
    if (!B.observed) { out.push({ cls: 'hover', name, state: 'missing', note: `build probe ${B.error}; live changes ${liveNote}` }); continue; }
    if (!B.fired) { out.push({ cls: 'hover', name, state: 'missing', note: `no hover diff on build; live changes ${liveNote}` }); continue; }
    const lacks = L.changed.filter((k) => !B.changed.includes(k));
    const extra = B.changed.filter((k) => !L.changed.includes(k));
    const deltas = outOfTolerance([{ kind: 'timing', label: 'transition', live: L.timeMs, build: B.timeMs }], opts);
    if (lacks.length) deltas.push(`build lacks ${lacks.join(', ')}`);
    if (extra.length) deltas.push(`build adds ${extra.join(', ')}`);
    out.push(deltas.length
      ? { cls: 'hover', name, state: 'tolerance', deltas, note: `live changes ${liveNote}${p.by === 'order' ? '; paired by order' : ''}` }
      : { cls: 'hover', name, state: 'parity', note: `${liveNote}${p.by === 'order' ? '; paired by order' : ''}` });
  }
  return out;
}

// ---- event families -----------------------------------------------------------------------------

const groupBy = (list, keyOf) => {
  const m = new Map();
  for (const item of list) { const k = keyOf(item); if (k === null || k === undefined || k === '') continue; if (!m.has(k)) m.set(k, []); m.get(k).push(item); }
  return m;
};

function compareEntrances(live, build) {
  const out = [];
  const L = groupBy(live.events.animations, (a) => a.name);
  const B = groupBy(build.events.animations, (a) => a.name);
  for (const [name, items] of [...L.entries()].sort()) {
    const b = B.get(name);
    if (!b) { out.push({ cls: 'entrance', name, state: 'missing', note: `fired on ${items.length} element(s) on live` }); continue; }
    out.push(b.length === items.length
      ? { cls: 'entrance', name, state: 'parity', note: `fired on ${items.length} element(s)` }
      : { cls: 'entrance', name, state: 'tolerance', deltas: [`fired-element count live ${items.length}, build ${b.length}`] });
  }
  for (const [name, items] of [...B.entries()].sort()) if (!L.has(name)) out.push({ cls: 'entrance', name, state: 'extra', note: `fired on ${items.length} element(s) on build, never on live` });
  return out;
}

function compareTransitions(live, build, opts) {
  const out = [];
  const longest = (items) => items.reduce((m, t) => { const v = maxTimeMs(t.dur); return v !== null && (m === null || v > m) ? v : m; }, null);
  const L = groupBy(live.events.transitions, (t) => t.prop);
  const B = groupBy(build.events.transitions, (t) => t.prop);
  for (const [prop, items] of [...L.entries()].sort()) {
    const b = B.get(prop);
    if (!b) { out.push({ cls: 'transition', name: prop, state: 'missing', note: `${items.length} event(s) on live, ${fmtMs(longest(items))}` }); continue; }
    const deltas = outOfTolerance([{ kind: 'timing', label: 'longest duration', live: longest(items), build: longest(b) }], opts);
    out.push(deltas.length
      ? { cls: 'transition', name: prop, state: 'tolerance', deltas, note: `${items.length} event(s) on live, ${b.length} on build` }
      : { cls: 'transition', name: prop, state: 'parity', note: `${items.length} event(s) on live, ${b.length} on build, ${fmtMs(longest(items))}` });
  }
  // A property transitioned on the build only is advisory: the event log records whatever the
  // traversal happened to touch (a parked pointer over a button, a smooth-scroll transform), and the
  // live list depends on the same accident — a hard EXTRA here failed faithful builds.
  for (const [prop, items] of [...B.entries()].sort()) if (!L.has(prop)) out.push({ cls: 'transition', name: prop, state: 'advisory', note: `${items.length} event(s) on build, none on live — a build-only transitioned property; incidental unless a live line names the motion` });
  return out;
}

function compareClasses(live, build) {
  const out = [];
  const flat = (list) => list.flatMap((m) => (Array.isArray(m.added) ? m.added : []).map((c) => ({ c, el: m.el })));
  const L = groupBy(flat(live.events.classMutations), (x) => x.c);
  const B = groupBy(flat(build.events.classMutations), (x) => x.c);
  for (const [c, items] of [...L.entries()].sort()) {
    out.push(B.has(c)
      ? { cls: 'class', name: c, state: 'parity', note: `added ${items.length}× on live, ${B.get(c).length}× on build` }
      : { cls: 'class', name: c, state: 'missing', note: `trigger class added ${items.length}× on live, never on build` });
  }
  for (const [c, items] of [...B.entries()].sort()) if (!L.has(c)) out.push({ cls: 'class', name: c, state: 'advisory', note: `added ${items.length}× on build, never on live — check it drives no invented behavior` });
  return out;
}

// Media: videos paired by document order. Live playing → build must play; live autoplay attribute
// but paused at the sample (off-viewport lazy autoplay) → build must carry autoplay or play. A build
// video where live had none, or playing where live paused, is advisory (possible invented motion).
export function compareMedia(live, build) {
  const out = [];
  const L = live.media?.videos || [];
  const B = build.media?.videos || [];
  const auto = (v) => !!(v && (v.playing || v.autoplay));
  L.forEach((lv, i) => {
    const bv = B[i];
    const file = (lv.src || '').split('/').pop().split('?')[0].slice(0, 40);
    const name = `video#${i + 1}${file ? ` ${file}` : ''}`;
    const liveState = lv.playing ? 'playing' : lv.autoplay ? 'autoplay, paused at sample' : 'paused';
    if (!auto(lv)) {
      out.push(auto(bv) ? { cls: 'media', name, state: 'advisory', note: 'live paused, build autoplays' } : { cls: 'media', name, state: 'parity', note: 'paused on both' });
      return;
    }
    if (!bv) { out.push({ cls: 'media', name, state: 'missing', note: `live ${liveState}, no <video> on build — poster only?` }); return; }
    const ok = lv.playing ? bv.playing : auto(bv);
    out.push(ok
      ? { cls: 'media', name, state: 'parity', note: `live ${liveState}, build ${bv.playing ? 'playing' : 'autoplay'}` }
      : { cls: 'media', name, state: 'missing', note: `live ${liveState}, build ${bv.paused ? 'paused' : 'not advancing'} (readyState ${bv.readyState ?? '?'}) — the capture freeze is not the spec` });
  });
  B.slice(L.length).forEach((bv, i) => { if (auto(bv)) out.push({ cls: 'media', name: `video#${L.length + i + 1}`, state: 'advisory', note: 'autoplay video on build only' }); });
  const li = live.media?.idleClassMutationCount || 0;
  const bi = build.media?.idleClassMutationCount || 0;
  if (li > 0) {
    out.push(bi > 0
      ? { cls: 'media', name: 'auto-advance', state: 'parity', note: `${li} class mutation(s) fired unpoked on live, ${bi} on build` }
      : { cls: 'media', name: 'auto-advance', state: 'missing', note: `${li} class mutation(s) fired unpoked on live (timer-driven rotation), none on build` });
  }
  return out;
}

// ---- main -------------------------------------------------------------------------------------

export function compare(live, build, opts) {
  const verdicts = [
    ...compareHeader(live, build, opts),
    ...compareWidgets(live, build, opts),
    ...compareHovers(live, build, opts),
    ...compareEntrances(live, build),
    ...compareTransitions(live, build, opts),
    ...compareClasses(live, build),
    ...compareMedia(live, build),
  ];
  const count = (s) => verdicts.filter((v) => v.state === s).length;
  const counts = { behaviors: verdicts.length, parity: count('parity'), missing: count('missing'), extra: count('extra'), tolerance: count('tolerance'), dead: count('dead') + count('unobserved'), advisory: count('advisory') };
  // findings = the lines the agent must confirm and record; informational only (exit stays 0).
  const findings = verdicts.filter((v) => FINDING.has(v.state)).length;
  return { verdicts, counts, findings };
}

// The summary line: the four headline counts first (greppable), the rest in the parenthetical.
export function summaryLine(counts, opts) {
  return `motion summary: ${counts.parity} parity, ${counts.missing} missing, ${counts.extra} extra, ${counts.advisory} advisory (${counts.tolerance} out of tolerance, ${counts.dead} dead or unobserved on live — not required; tolerance ${opts.toleranceMs}ms / ${opts.tolerancePx}px)`;
}

function main() {
  const { livePath, buildPath, opts } = parseArgs(process.argv);
  const live = loadObservation(livePath, 'live');
  const build = loadObservation(buildPath, 'build');
  if (live.width && build.width && live.width !== build.width) console.error(`motion-compare WARNING: viewport widths differ (live ${live.width}, build ${build.width}) — chrome and widget behavior are breakpoint-dependent`);
  const { verdicts, counts, findings } = compare(live, build, opts);
  for (const v of verdicts) console.log(verdictLine(v));
  console.log(summaryLine(counts, opts));
  if (opts.json) {
    mkdirSync(dirname(opts.json) || '.', { recursive: true });
    writeFileSync(opts.json, JSON.stringify({ live: livePath, build: buildPath, toleranceMs: opts.toleranceMs, tolerancePx: opts.tolerancePx, advisory: true, findings, counts, verdicts: verdicts.map((v) => ({ ...v, line: verdictLine(v) })) }, null, 2));
  }
  // Advisory: both inputs parsed → exit 0, whatever the verdicts. The MISSING/EXTRA lines are
  // findings for the agent to confirm and record (progress.json motion: {observed, implemented, dead[]}).
  process.exitCode = 0;
}

// Only run when invoked directly, so the test can import the reducers. Compare by real path: node
// resolves the entry's symlinks for import.meta.url but not for argv[1], so a symlinked checkout or
// temp dir would otherwise turn the CLI into a silent no-op (exit 0, no lines — which reads as PASS).
function isMainModule() {
  try { return realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); } catch { return false; }
}
if (process.argv[1] && isMainModule()) {
  try { main(); } catch (e) { console.error(`motion-compare error: ${e.message}`); process.exit(USAGE_EXIT); }
}

skills

README.md

tile.json