motion-audit 0.0.0-stage → 1.0.0

package/skills/motion-audit/scripts/lib/compare.mjs

@@ -0,0 +1,70 @@
+// Report-to-report comparison: `compare <ref.json> <mine.json>` and the `--baseline` filter.
+import { readFileSync } from 'node:fs';
+
+const SIGNIFICANT_MS = 50;
+const SIGNIFICANT_RATIO = 1.25;
+const SIGNIFICANT_OVERSHOOT = 5;
+
+export const readReport = (file) => {
+  let report;
+  try { report = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new Error(`cannot read report ${file}: ${e instanceof SyntaxError ? 'not valid JSON (content not shown)' : e.code ?? 'unreadable'}`); }
+  if (report.schemaVersion !== 1) throw new Error(`${file}: unsupported schemaVersion ${report.schemaVersion} (expected 1)`);
+  return report;
+};
+
+// Strongest measured move of an element at a gesture, or null.
+const primary = (el, moment) => {
+  const moves = (el.moments?.[moment]?.motion ?? []).flatMap((e) => e.moves.map((m) => ({ ...m, label: e.label })));
+  return moves.sort((a, b) => b.durationMs - a.durationMs)[0] ?? null;
+};
+
+const declared = (el, moment) => {
+  const tr = el.moments?.[moment]?.transition ?? el.transition;
+  const changed = el.moments?.[moment]?.changed ?? [];
+  if (!changed.length) return null;
+  const i = tr?.properties?.findIndex((p) => p === 'all' || changed.some((c) => c === p || c.startsWith(`${p}-`)));
+  return i >= 0 ? { duration: tr.durations[i % tr.durations.length], easing: tr.easings[i % tr.easings.length] } : null;
+};
+
+const describe = (m, d) => {
+  if (m) return `${m.durationMs} ms ${m.shape}${m.overshootPct > 3 ? ` (+${m.overshootPct} % overshoot)` : ''}`;
+  if (d) return `${d.duration} ms declared (${d.easing})`;
+  return 'no motion';
+};
+
+const differences = (am, ad, bm, bd) => {
+  if (!am && !ad && !bm && !bd) return null;
+  const out = [];
+  const da = am?.durationMs ?? ad?.duration ?? 0;
+  const db = bm?.durationMs ?? bd?.duration ?? 0;
+  if (Math.abs(db - da) >= SIGNIFICANT_MS || Math.max(da, db) / Math.max(1, Math.min(da, db)) > SIGNIFICANT_RATIO) out.push(`duration ${db - da > 0 ? '+' : ''}${db - da} ms`);
+  if (am && bm && am.shape !== bm.shape) out.push(`curve ${am.shape} -> ${bm.shape}`);
+  if (am && bm && Math.abs(am.overshootPct - bm.overshootPct) >= SIGNIFICANT_OVERSHOOT) out.push(`overshoot ${am.overshootPct} -> ${bm.overshootPct} %`);
+  return out;
+};
+
+// One line per control present in both reports and gesture; controls are paired by label.
+export const compareReports = (ref, mine) => {
+  const lines = [];
+  let differ = 0;
+  const byLabel = new Map(mine.elements.map((e) => [e.label, e]));
+  for (const a of ref.elements) {
+    const b = byLabel.get(a.label);
+    if (!b) continue;
+    for (const moment of ['hover', 'press', 'focus']) {
+      const am = primary(a, moment);
+      const bm = primary(b, moment);
+      const diff = differences(am, declared(a, moment), bm, declared(b, moment));
+      if (!diff) continue;
+      if (diff.length) differ++;
+      lines.push(`${a.label} ${moment}: ref ${describe(am, declared(a, moment))} · mine ${describe(bm, declared(b, moment))} · ${diff.length ? `diff: ${diff.join(', ')}` : 'matches'}`);
+    }
+  }
+  const refIds = new Set(ref.findings.map((f) => f.id));
+  const mineIds = new Set(mine.findings.map((f) => f.id));
+  const added = mine.findings.filter((f) => !refIds.has(f.id));
+  const gone = ref.findings.filter((f) => !mineIds.has(f.id));
+  return { lines, differ, total: lines.length, added, gone };
+};
+
+export const baselineIds = (report) => new Set([...report.findings.map((f) => f.id), ...(report.baselined ?? []).map((f) => f.id)]);

package/skills/motion-audit/scripts/lib/config.mjs

@@ -0,0 +1,101 @@
+// motion-audit.config.json: bands, duration tokens, per-kind severity and ignores with a reason.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { BANDS } from './constants.mjs';
+import { KINDS, LEVELS } from './kinds.mjs';
+
+export const CONFIG_FILE = 'motion-audit.config.json';
+const TOP_KEYS = new Set(['bands', 'tokens', 'severity', 'ignore']);
+const GESTURES = Object.keys(BANDS);
+
+export class ConfigError extends Error {}
+
+// Fingerprint of a finding: stable across runs because it uses the element's label and the
+// moment/property that identifies the finding, never DOM indices or measured numbers.
+// An `inconclusive` row carries the `check` it could not decide and the hash of that check's own finding.
+export const fingerprint = (f) => `${f.kind}:${createHash('sha1').update(`${f.check ?? f.kind}\n${f.element}\n${f.key ?? ''}`).digest('hex').slice(0, 10)}`;
+
+const ID_PATTERN = /^([a-z-]+):[0-9a-f]{10}$/;
+const hasReason = (x) => typeof x?.reason === 'string' && x.reason.trim().length > 0;
+const rank = (level) => LEVELS.indexOf(level);
+
+// Everything that loosens the audit (bands, tokens, a lowered severity, an ignore) needs a reason.
+export const validateConfig = (raw, source = CONFIG_FILE) => {
+  const fail = (m) => { throw new ConfigError(`${source}: ${m}`); };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail('must be a JSON object');
+  for (const k of Object.keys(raw)) if (!TOP_KEYS.has(k)) fail(`unknown key "${k}" (allowed: ${[...TOP_KEYS].join(', ')})`);
+  const bands = { ...BANDS };
+  const bandEntries = Object.entries(raw.bands ?? {}).filter(([g]) => g !== 'reason');
+  if (bandEntries.length && !hasReason(raw.bands)) fail('bands needs a non-empty "reason"');
+  for (const [g, v] of bandEntries) {
+    if (!GESTURES.includes(g)) fail(`bands.${g}: unknown gesture (allowed: ${GESTURES.join(', ')})`);
+    if (!Array.isArray(v) || v.length !== 2 || v.some((x) => typeof x !== 'number' || x < 0) || v[0] > v[1]) fail(`bands.${g} must be [min, max] in ms`);
+    bands[g] = v;
+  }
+  const durations = raw.tokens?.durations ?? [];
+  if (!Array.isArray(durations) || durations.some((x) => typeof x !== 'number' || x <= 0)) fail('tokens.durations must be an array of positive numbers (ms)');
+  if (durations.length && !hasReason(raw.tokens)) fail('tokens needs a non-empty "reason"');
+  const severity = {};
+  for (const [k, v] of Object.entries(raw.severity ?? {})) {
+    if (!KINDS[k]) fail(`severity.${k}: unknown kind`);
+    const level = typeof v === 'string' ? v : v?.level;
+    if (!LEVELS.includes(level)) fail(`severity.${k}: level must be one of ${LEVELS.join(', ')}`);
+    if (rank(level) < rank(KINDS[k].level) && !(typeof v === 'object' && hasReason(v))) fail(`severity.${k}: lowering a kind needs { "level": "${level}", "reason": "..." }`);
+    severity[k] = level;
+  }
+  const ignore = [];
+  for (const [i, e] of (raw.ignore ?? []).entries()) {
+    if (!e || typeof e !== 'object') fail(`ignore[${i}] must be an object`);
+    if (!hasReason(e)) fail(`ignore[${i}] needs a non-empty "reason"`);
+    if (e.id !== undefined) {
+      const m = ID_PATTERN.exec(String(e.id));
+      if (!m || !KINDS[m[1]]) fail(`ignore[${i}].id must be a finding id: a known kind, a colon and 10 hex digits`);
+    } else {
+      if (!e.kind || !KINDS[e.kind]) fail(`ignore[${i}] needs "id" (a finding id) or a known "kind" with an "element"`);
+      if (typeof e.element !== 'string' || !/[^*\s]/.test(e.element)) fail(`ignore[${i}].element must name an element; a bare wildcard would silence the whole kind (lower its severity with a reason instead)`);
+    }
+    ignore.push({ id: e.id, kind: e.kind, element: e.element, reason: e.reason.trim() });
+  }
+  return { bands, tokens: { durations }, severity, ignore };
+};
+
+export const loadConfig = (path, cwd = process.cwd()) => {
+  const file = path ? resolve(cwd, path) : join(cwd, CONFIG_FILE);
+  if (!existsSync(file)) {
+    if (path) throw new ConfigError(`config file not found: ${file}`);
+    return validateConfig({});
+  }
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch (e) { throw new ConfigError(`${file}: not valid JSON (${e instanceof SyntaxError ? 'syntax error; content not shown' : e.code ?? 'unreadable'})`); }
+  return validateConfig(raw, file);
+};
+
+const globToRegExp = (g) => new RegExp(`^${g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`);
+const ignoreMatches = (rule, f) => (rule.id ? rule.id === f.id : rule.kind === f.kind && (!rule.element || globToRegExp(rule.element).test(f.element)));
+
+// Raw findings -> final findings: default level, config severity, ignores. Returns
+// { findings, suppressed } where suppressed carries the reason of the rule that dropped it.
+export const finalize = (raw, config, { devServer = false } = {}) => {
+  const findings = [];
+  const suppressed = [];
+  const seen = new Set();
+  // What an inconclusive row could not decide is settled when the check found something.
+  const found = new Set(raw.filter((f) => f.kind !== 'inconclusive').map((f) => fingerprint(f).split(':')[1] + f.kind));
+  for (const f of raw) {
+    if (f.kind === 'inconclusive' && found.has(fingerprint(f).split(':')[1] + f.check)) continue;
+    // One finding per fingerprint: several series can describe the same thing (two nodes of one component).
+    const id = fingerprint(f);
+    if (seen.has(id)) continue;
+    seen.add(id);
+    let level = f.level ?? KINDS[f.kind].level;
+    if (f.kind === 'long-frame' && devServer) level = 'warning';
+    level = config.severity[f.kind] ?? level;
+    if (level === 'off') continue;
+    const full = { id, level, kind: f.kind, ...(f.check ? { check: f.check } : {}), element: f.element, detail: f.detail, ...(f.cadence ? { cadence: f.cadence } : {}) };
+    const rule = config.ignore.find((r) => ignoreMatches(r, full));
+    if (rule) suppressed.push({ ...full, reason: rule.reason });
+    else findings.push(full);
+  }
+  return { findings, suppressed };
+};

package/skills/motion-audit/scripts/lib/constants.mjs

@@ -0,0 +1,161 @@
+// Named thresholds and timings shared by the analysis and the browser driver.
+export const FRAME_MS = 1000 / 60;
+export const LONG_FRAME_MS = 50;
+// A frame with no application script behind it counts above LONG_FRAME_MS, or above this multiple of the
+// longest frame a blank page shows on the same machine (a slow VM has long frames with nothing to do).
+export const FRAME_NOISE_FACTOR = 2;
+// Where a machine shows frames over LONG_FRAME_MS with nothing to do, its noise comes in bursts a short
+// calibration can miss: a frame without application work counts only above this many ms at least.
+export const NOISY_UNATTRIBUTED_MS = 250;
+// A frame whose page scripts add up to less than this is judged as one without application work: the
+// rest of it belongs to the machine.
+export const PAGE_SCRIPT_MIN_MS = 25;
+// Frames without a script behind them in this many controls of one audit are the machine's, whatever its calibration.
+export const ENV_NOISE_MIN_ELEMENTS = 3;
+// A motion of at least SPARSE_MIN_MOTION_MS sampled at fewer than SPARSE_DENSITY samples per 60 Hz
+// frame is measured again (at most SPARSE_RETRIES times), keeping the densest recording.
+export const SPARSE_MIN_MOTION_MS = 100;
+export const SPARSE_DENSITY = 0.7;
+export const SPARSE_RETRIES = 3;
+// A hover left mid-way is recorded again (at most this many times) while an animation restart was seen
+// but the value could not be followed because the frames were sparse.
+export const INTERRUPT_RETRIES = 3;
+export const CALIBRATION_CYCLES = 6;
+export const IDLE_NOISE_MS = 1000;
+export const MIN_PLAYWRIGHT = [1, 59];
+export const SCHEMA_VERSION = 1;
+
+export const DEFAULT_MAX_ELEMENTS = 40;
+export const VIEWPORT = { width: 1280, height: 900 };
+export const NAV_TIMEOUT_MS = 45000;
+export const WAIT_FOR_TIMEOUT_MS = 15000;
+// The first load of a URL waits this long for hydration and for client-side redirects; later loads
+// of the same URL (probes reload the page) wait RELOAD_WAIT_MS.
+export const HYDRATION_WAIT_MS = 800;
+export const RELOAD_WAIT_MS = 250;
+// Controls that show up later than this after a load are not "late": the audit waits this long
+// before it counts the controls again, and a larger count means the first count was incomplete.
+export const RECOUNT_AFTER_MS = 3000;
+
+// A gesture lasts until the page is still: no running CSS or WAAPI animation on the element or its
+// subtree, and no change of position, size, opacity, transform or colour for SETTLE_QUIET_MS, but at
+// least SETTLE_MIN_MS (a transition starts on the next frame) and at most SETTLE_MAX_MS.
+export const SETTLE_MIN_MS = 50;
+export const SETTLE_QUIET_MS = 80;
+export const SETTLE_MAX_MS = 2000;
+export const INTERRUPT_MIN_MOTION_MS = 80;
+export const INTERRUPT_LEAD_MS = 80;
+export const CLICK_LEAD_MS = 120;
+// After a real press is released, clicks stay cancelled this long: a library may dispatch its own click up to ~80 ms later.
+export const PRESS_GUARD_MS = 150;
+export const CLICK_RECORD_MS = 1500;
+// A click recording whose only jump candidate fell in a frame too long to judge is recorded again, at most this many times.
+export const CLICK_RESOLVE_RETRIES = 2;
+export const CLICK_INTERRUPT_MS = 160;
+export const SCROLL_STEP_PX = 160;
+export const SCROLL_STEP_MS = 90;
+export const SCROLL_TAIL_MS = 600;
+
+// Toggle probing.
+export const MAX_TOGGLES = 8;
+export const TOGGLE_MIN_MOTION_MS = 80;
+export const TOGGLE_SETTLE_MIN_MS = 100;
+export const TOGGLE_QUIET_MS = 150;
+export const TOGGLE_SHARES = [0.3, 0.55];
+
+// Tracer.
+export const TRACE_SUBTREE_CAP = 60;
+export const TRACE_PAGE_CAP = 800;
+export const TRACE_MOUNT_CAP = 400;
+export const TRACE_MIN_SIZE_PX = 4;
+
+// Findings policy.
+export const BANDS = { hover: [80, 300], press: [50, 200], focus: [0, 250] };
+export const INCONSISTENT_RATIO = 1.5;
+export const INCONSISTENT_MIN_GAP_MS = 60;
+export const OVERSHOOT_SPRING_PCT = 3;
+export const EASE_IN_MIN_MS = 60;
+
+// Jump detection. A position step is a jump only when the sampling is fine enough to bound the
+// instantaneous velocity (or an Animation object says the animation restarted).
+export const FINE_SAMPLING_MS = 1.5 * FRAME_MS;
+export const JUMP_MAX_DT_MS = 2.5 * FRAME_MS;
+// A step is a jump only if it was judged in an interval no longer than this, by frame time and by the time its value was read,
+// with both neighbouring intervals as short: a step inside a longer interval, or beside one, can only leave the motion
+// unresolved. Within the limit a settled motion is judged on its own velocities, which are bounded whatever the interval (the
+// mean slope of a smooth curve over an interval never exceeds its steepest slope), so a machine that renders 30 fps with
+// stalls up to this long still gets its teleports found.
+export const SERIES_JUMP_MAX_DT_MS = 6 * FRAME_MS;
+
+// An interval of a settled motion is a jump when it is a local speed peak (at least twice as fast as
+// both neighbours) and this many times faster than the average speed of the whole motion.
+export const SERIES_PEAK_SLOPE = 5;
+// ...and at least this many times faster than each neighbouring interval (an ease-in speeds up by less, even sampled coarsely).
+export const SERIES_NEIGHBOUR_RATIO = 3;
+export const JUMP_PEAK_SLOPE = 6;
+export const JUMP_MIN_SHARE = 0.15;
+export const RESTART_MIN_SHARE = 0.1;
+export const RESTART_WINDOW = 3;
+export const SMALL_MIN_SHARE = 0.2;
+export const SMALL_STEP_EPS_FACTOR = 2;
+export const RESTART_EVENT_SLACK_MS = 3 * FRAME_MS;
+// A node removed and a same-kind node mounted in the same parent within this many frames are one re-mounted component.
+export const REMOUNT_GAP_FRAMES = 4;
+// A step next to a long frame is that frame, not a jump (the animation clock ran ahead while the thread was blocked).
+export const LONG_FRAME_STEP_SLACK_MS = 2 * FRAME_MS;
+export const JUMP_MIN_STEP = { left: 24, top: 24, width: 24, height: 24, tx: 24, ty: 24, opacity: 0.4, sx: 0.3, sy: 0.3 };
+
+// Confirmation of flaky findings: re-measured, kept when most runs agree.
+export const CONFIRM_RUNS = 3;
+export const CONFIRM_MAJORITY = 2;
+
+// Reduced motion.
+export const REDUCED_SCALE_DELTA = 0.06;
+export const REDUCED_TRANSLATE_PX = 4;
+export const REDUCED_LOOP_SPINNER_PX = 64;
+
+export const HIT_TEST_POINTS = [[0.5, 0.5], [0.25, 0.5], [0.75, 0.5], [0.5, 0.25], [0.5, 0.75]];
+export const CLIP_MARGIN_PX = 6;
+// Screenshots differ visibly when enough PIXEL_BLOCK_PX squares change, in their average colour, by more than
+// the tolerance. Averaging squares ignores anti-aliasing (a different text rasterisation keeps the mean colour).
+export const PIXEL_BLOCK_PX = 8;
+export const PIXEL_CHANNEL_TOLERANCE = 24;
+export const PIXEL_MIN_BLOCKS = 2;
+export const CONTACT_SHEET_STEP_MS = 40;
+
+export const VISIBLE_PROPS = ['transform', 'translate', 'scale', 'rotate', 'opacity', 'background-color', 'background-image', 'color', 'box-shadow', 'border-color', 'outline-style', 'outline-width', 'outline-color', 'text-decoration-color', 'filter', 'width', 'height', 'padding-top', 'padding-left', 'margin-top', 'margin-left', 'top', 'left', 'letter-spacing', 'font-weight'];
+export const LAYOUT_PROPS = /^(width|height|top|left|right|bottom|inset|margin|padding|max-height|max-width|min-height|min-width|font-size|font-weight|letter-spacing|border-width|line-height|gap)/;
+export const INTERACTIVE = 'a[href], button, input:not([type=hidden]), select, textarea, summary, [role=button], [role=tab], [role=switch], [role=menuitem], [role=checkbox], [role=link], [tabindex]:not([tabindex="-1"])';
+export const TOGGLE = '[aria-expanded], [aria-controls], [aria-pressed], summary, [data-toggle]';
+// Controls that --interact never presses or toggles: they submit, destroy, leave, drag or resize.
+// Also denied in denyReason: any submit or reset control owned by a form (inside it or through form=),
+// links (and anything inside one) whose href is not a same-document fragment, and buttons with no accessible name.
+export const DENY_SELECTOR = '[type=submit], [type=image], [type=reset], [draggable=true], [role=slider], [role=separator], [role=scrollbar], input[type=range], input[type=file]';
+const DENY_WORDS = [
+  // English
+  'delete', 'remove', 'destroy', 'discard', 'logout', 'log out', 'sign out', 'signout', 'unsubscribe', 'pay', 'buy', 'purchase', 'checkout', 'submit', 'send', 'confirm', 'archive', 'publish', 'deploy', 'reset', 'place order', 'subscribe', 'revoke', 'block',
+  // Spanish
+  'eliminar', 'elimina', 'borrar', 'borra', 'quitar', 'descartar', 'salir', 'cerrar sesión', 'cerrar sesion', 'desconectar', 'darse de baja', 'pagar', 'paga', 'comprar', 'compra', 'enviar', 'envía', 'envia', 'confirmar', 'confirma', 'publicar', 'publica', 'archivar', 'restablecer', 'realizar pedido', 'suscribir', 'revocar', 'bloquear',
+  // Portuguese
+  'excluir', 'apagar', 'sair', 'encerrar sessão', 'encerrar sessao',
+  // French
+  'supprimer', 'effacer', 'déconnexion', 'deconnexion', 'se déconnecter', 'payer', 'acheter', 'envoyer', 'confirmer', 'publier', 'valider',
+  // German
+  'löschen', 'entfernen', 'abmelden', 'ausloggen', 'bezahlen', 'kaufen', 'senden', 'absenden', 'bestätigen', 'veröffentlichen',
+  // Italian
+  'cancella', 'rimuovi', 'esci', 'paga', 'acquista', 'invia', 'conferma', 'pubblica',
+];
+export const DENY_TEXT = new RegExp(`(?<!\\p{L})(?:${DENY_WORDS.join('|')})(?!\\p{L})`, 'iu');
+// Controls that must have an accessible name to be pressed: an unnamed one may be a trash can.
+export const NAMED_CONTROL = 'button, summary, [role=button]';
+export const LOGIN_PATH = /\/(log-?in|sign-?in|sign_in|auth|sso|session\/new)(\/|$|\?)/i;
+// A motion sampled fewer times than this is never examined for jumps (findJumps needs a start, a settle and room between).
+export const SIGHTING_MIN_SAMPLES = 5;
+
+// Frames at 60 Hz: a recording whose intervals have a median up to DENSE_MEDIAN_MS and none over DENSE_MAX_MS is dense. A step in
+// it that is slower than a jump is settled, and a row that says "too sparse" about it would be wrong. Product and tests share
+// these two numbers.
+export const DENSE_MEDIAN_MS = 20;
+export const DENSE_MAX_MS = 34;
+// A declared transition shorter than this cannot hold SIGHTING_MIN_SAMPLES frames at 60 Hz: its measured curve is not judged.
+export const MEASURE_MIN_MS = 120;

package/skills/motion-audit/scripts/lib/continuity.mjs

@@ -0,0 +1,81 @@
+// Interruption analysis: after a second gesture (the mark) the motion must continue from where it
+// was. A CSS transition reverses from its live value, so a step after the mark is only a defect
+// when an Animation object says the animation restarted, or when the sampling is fine enough to
+// show the value teleporting faster than any easing curve allows.
+import { COLS, EPS, PROP_OF, median, round, unwrap } from './series.mjs';
+import { FINE_SAMPLING_MS, JUMP_MAX_DT_MS, JUMP_MIN_STEP, LONG_FRAME_STEP_SLACK_MS, JUMP_PEAK_SLOPE, RESTART_EVENT_SLACK_MS, RESTART_MIN_SHARE, RESTART_WINDOW, SMALL_MIN_SHARE, SMALL_STEP_EPS_FACTOR } from './constants.mjs';
+
+const ancestorsOf = (el, byId) => {
+  const chain = new Set([el.id]);
+  for (let p = el.parent, guard = 0; p && guard < 64; p = byId.get(p)?.parent, guard++) chain.add(p);
+  return chain;
+};
+
+// Animation events from the tracer: { t, nodeId, type: 'transition' | 'animation' | 'waapi' | 'cancel',
+// props, explicitFrom }. A restart is a new keyframe/WAAPI animation with an explicit `from`
+// keyframe, or a keyframe animation cancelled before it finished.
+const isRestart = (e) => e.type === 'cancel' || ((e.type === 'animation' || e.type === 'waapi') && e.explicitFrom);
+
+// Position steps in the window after `markT`. `durationMs` is the measured duration of the motion
+// (estimated from the series when absent). `small` is for micro-interactions (hover, a second click
+// on a trigger): steps are judged against the property's epsilon and 20 % of its range instead of
+// the absolute 24 px / 0.4 opacity of a toggle's panel.
+// `longFrames`: [[startMs, durationMs]] of the long frames of the recording. A step in a frame that
+// overlaps one is the long frame (the page's animation clock kept running while its thread was
+// blocked), reported as `long-frame`; only an Animation object that restarted is still a jump there.
+export const interruptionJumps = (rec, markT, { durationMs, small = false, longFrames = [] } = {}) => {
+  const found = [];
+  const anims = rec.anims ?? [];
+  const byId = new Map(rec.elems.map((e) => [e.id, e]));
+  for (const el of rec.elems) {
+    const scope = ancestorsOf(el, byId);
+    const own = anims.filter((a) => scope.has(a.nodeId));
+    const transitionOnly = own.some((a) => a.type === 'transition') && !own.some(isRestart);
+    for (const c of COLS) {
+      const min = small ? SMALL_STEP_EPS_FACTOR * EPS[PROP_OF[c]] : JUMP_MIN_STEP[c];
+      if (min === undefined) continue;
+      const { t } = el;
+      // When each sample was read (`t` is the start of its frame, which a slow frame leaves far behind): marks and
+      // animation events share this clock.
+      const r = el.r ?? t;
+      const v = c === 'rot' ? unwrap(el[c]) : el[c];
+      const i = r.findIndex((x) => x >= markT);
+      if (i < 3 || i >= v.length - 1) continue;
+      const range = Math.max(...v) - Math.min(...v);
+      if (range < EPS[PROP_OF[c]]) continue;
+      const before = t.slice(1, i).map((x, k) => x - t[k]);
+      const fine = median(before) <= FINE_SAMPLING_MS;
+      const dur = durationMs ?? Math.max(1, t.at(-1) - t[0]);
+      let worst = null;
+      for (let k = i; k <= Math.min(v.length - 1, i + RESTART_WINDOW); k++) {
+        const d = Math.abs(v[k] - v[k - 1]);
+        const dt = t[k] - t[k - 1];
+        // An Animation object that restarted is strong evidence, so a smaller step suffices than
+        // for a position-only teleport judged in small mode.
+        const restarted = own.some((a) => isRestart(a) && a.t >= markT - RESTART_EVENT_SLACK_MS && a.t <= r[k] + Math.max(RESTART_EVENT_SLACK_MS, 2 * dt));
+        if (d < Math.max(min, (small && !restarted ? SMALL_MIN_SHARE : RESTART_MIN_SHARE) * range)) continue;
+        if (!restarted && longFrames.some(([s, len]) => s <= t[k] + LONG_FRAME_STEP_SLACK_MS && s + len >= t[k - 1] - LONG_FRAME_STEP_SLACK_MS)) continue;
+        const teleports = !transitionOnly && fine && dt > 0 && dt <= JUMP_MAX_DT_MS && d / dt > (JUMP_PEAK_SLOPE * range) / dur;
+        if ((restarted || teleports) && (!worst || d > worst.delta)) worst = { delta: d, from: v[k - 1], to: v[k], atMs: t[k] - markT, evidence: restarted ? 'animation' : 'position' };
+      }
+      if (worst) found.push({ label: el.label, prop: PROP_OF[c], delta: round(worst.delta, 2), from: round(worst.from, 2), to: round(worst.to, 2), atMs: round(worst.atMs, 0), evidence: worst.evidence });
+    }
+  }
+  return found.sort((a, b) => b.delta - a.delta);
+};
+
+// An animation restart was seen after the mark but the samples around it are too far apart to follow the
+// value: { median, max } of the intervals there, or null when nothing restarted or the frames were fine.
+const dtsAround = (rec, markT) => rec.elems.flatMap((el) => (el.r ?? el.t).slice(1).map((x, k) => [x, x - (el.r ?? el.t)[k]]).filter(([x]) => Math.abs(x - markT) <= 300).map(([, d]) => d));
+
+// { median, max } of the intervals between the samples within 300 ms of the mark, or null without samples.
+export const markCadence = (rec, markT) => {
+  const dts = dtsAround(rec, markT);
+  return dts.length ? { median: round(median(dts), 0), max: round(Math.max(...dts), 0) } : null;
+};
+
+export const restartUnfollowed = (rec, markT) => {
+  if (!(rec.anims ?? []).some((a) => isRestart(a) && a.t >= markT - RESTART_EVENT_SLACK_MS)) return null;
+  const cadence = markCadence(rec, markT);
+  return cadence && cadence.max > JUMP_MAX_DT_MS ? cadence : null;
+};

package/skills/motion-audit/scripts/lib/index.mjs

@@ -0,0 +1,9 @@
+// Public API of the package: `import { audit } from 'motion-audit'`.
+export { audit, exitCode } from './audit.mjs';
+export { KINDS, kindNames } from './kinds.mjs';
+export { analyzeSeries, analyzeRecording, easingKind } from './series.mjs';
+export { interruptionJumps } from './continuity.mjs';
+export { judgeElement, inconsistencies } from './judge.mjs';
+export { compareReports, readReport } from './compare.mjs';
+export { fingerprint, loadConfig, validateConfig } from './config.mjs';
+export { reducedMoves, reducedResidue, transformState } from './reduced.mjs';

package/skills/motion-audit/scripts/lib/judge.mjs

@@ -0,0 +1,128 @@
+// Turns what was measured on one element into findings. Pure: no browser, no config file.
+import { BANDS, EASE_IN_MIN_MS, FRAME_MS, INCONSISTENT_MIN_GAP_MS, INCONSISTENT_RATIO, LAYOUT_PROPS, SPARSE_DENSITY } from './constants.mjs';
+import { animatedMove, easingKind } from './series.mjs';
+import { isDense, measuredFor } from './sightings.mjs';
+import { MEASURE_MIN_MS, SIGHTING_MIN_SAMPLES } from './constants.mjs';
+
+// The declared duration and easing of the transition that animates `prop`, or null if none does.
+export const transitionOf = (tr, prop) => {
+  const longhand = (p) => p === prop || prop.startsWith(`${p}-`) || p === 'all';
+  const i = tr.properties.findIndex(longhand);
+  if (i < 0) return null;
+  return { duration: tr.durations[i % tr.durations.length], easing: tr.easings[i % tr.easings.length] };
+};
+
+const isLink = (kind) => kind === 'a' || kind === 'link';
+const isInput = (kind) => kind === 'input';
+
+const closeToToken = (ms, tokens) => (tokens ?? []).some((x) => Math.abs(x - ms) <= 1);
+
+// Findings for one audited element: [{ kind, element, detail, key, level? }]. `key` identifies the
+// finding inside its element and kind (moment, property) so fingerprints survive changed numbers.
+// `policy`: { bands, tokens }.
+export const judgeElement = (el, policy = {}) => {
+  const bands = { ...BANDS, ...policy.bands };
+  const out = [];
+  const seen = new Set();
+  const add = (kind, detail, key, level, extra) => {
+    if (seen.has(`${kind}|${key}`)) return;
+    seen.add(`${kind}|${key}`);
+    out.push({ kind, element: el.label, detail, key, ...(level ? { level } : {}), ...extra });
+  };
+  // A check the frames were too sparse to decide: same fingerprint as the finding it could not confirm or rule out.
+  const unsure = (check, detail, key, cadence) => add('inconclusive', `${detail}: frames too sparse: median Δt ${cadence.median} ms, max ${cadence.max} ms`, `${check} ${key}`, undefined, { check, key, cadence });
+  for (const [moment, d] of Object.entries(el.moments)) {
+    if (!d) continue;
+    const tr = d.transition ?? el.transition;
+    if (moment === 'focus' && d.hiddenUntilHover) { add('hover-only-control', 'revealed by hover only: keyboard focus leaves it invisible', 'focus'); continue; }
+    const responds = d.changed.length > 0 || d.pixels;
+    if (!responds) {
+      if (moment === 'focus') add('no-focus-feedback', 'keyboard focus shows nothing', 'focus');
+      else if (moment === 'hover' && !el.selected && !isInput(el.kind)) add('no-feedback', 'hover: nothing visible changes', 'hover', isLink(el.kind) ? 'warning' : undefined);
+      else if (moment === 'press' && !isLink(el.kind) && !isInput(el.kind)) add('no-press-feedback', 'press: nothing visible changes', 'press');
+      continue;
+    }
+    const visual = d.changed.filter((p) => !/^outline/.test(p));
+    const animated = visual.filter((p) => transitionOf(tr, p)?.duration > 0);
+    const measured = d.motion.some((m) => m.moves.some(animatedMove));
+    if (moment !== 'focus' && visual.length && !animated.length && !measured) add('snaps', `${moment}: ${visual.join(', ')} change with no transition`, moment);
+    for (const p of animated) {
+      const { duration, easing } = transitionOf(tr, p);
+      const [lo, hi] = bands[moment] ?? [0, Infinity];
+      if ((duration < lo || duration > hi) && !closeToToken(duration, policy.tokens?.durations)) add('duration', `${moment}: ${p} ${duration} ms, outside ${lo}-${hi} ms`, `${moment} ${p}`);
+      const k = easingKind(easing);
+      if (k === 'ease-in') add('ease-in', `${moment}: ${p} eases in (${easing}): the response starts late`, `declared ${p}`);
+      if (k === 'linear' && /transform|scale|translate|opacity/.test(p)) add('linear', `${moment}: ${p} moves linearly`, p);
+    }
+    const layout = animated.filter((p) => LAYOUT_PROPS.test(p));
+    const measuredLayout = d.motion.flatMap((e) => e.moves.filter((m) => /^layout/.test(m.prop) && animatedMove(m)).map((m) => `${e.label} ${m.prop}`));
+    if (layout.length || measuredLayout.length) add('layout-animated', `${moment}: animates layout (${[...layout, ...measuredLayout].join(', ')}): moves neighbours and costs layout every frame`, moment);
+    if (!animated.length) {
+      for (const e of d.motion) for (const m of e.moves) {
+        if (m.shape === 'linear' && /^(translate|scale|opacity)/.test(m.prop) && animatedMove(m)) add('linear', `${moment}: ${e.label} ${m.prop} moves linearly (measured)`, `measured ${e.label} ${m.prop}`);
+      }
+    }
+    // The stylesheet says this gesture eases in: its own measured motion, sampled too sparsely to be fitted, cannot
+    // rule that out, so it stays visible as undecided (never nothing).
+    // The measured ease-in of the control is ruled out only by a recording that saw its own motion of a declared property
+    // with enough samples, densely enough, to fit a curve: no motion recorded, too few samples or sparse ones decide nothing.
+    // A declared duration too short to hold that many frames at 60 Hz is not judged by measurement at all (the declared curve
+    // is), and a recording that was dense is never called too sparse.
+    const wanted = new Set(animated.filter((p) => easingKind(transitionOf(tr, p).easing) === 'ease-in' && transitionOf(tr, p).duration >= MEASURE_MIN_MS).flatMap(measuredFor));
+    if (wanted.size) {
+      const root = d.motion.find((e) => e.root);
+      const label = d.rootLabel ?? root?.label;
+      const mine = (root?.moves ?? []).filter((m) => wanted.has(m.prop));
+      const fitted = (m) => m.samples >= SIGHTING_MIN_SAMPLES && m.samples / (m.durationMs / FRAME_MS) >= SPARSE_DENSITY && !m.easeInTie;
+      if (label && mine.length && isDense(d.cadence) && !mine.some((m) => (m.shape === 'ease-in' && m.durationMs > EASE_IN_MIN_MS) || fitted(m))) {
+        // Dense frames and a fit that cannot tell the curve from an ease-in: the declared curve decides, so it is the finding.
+        if (mine.some((m) => m.easeInTie && m.durationMs > EASE_IN_MIN_MS)) add('ease-in', `${moment}: ${label} measured ease-in (the fit ties with it and the stylesheet declares it)`, `measured ${label}`);
+      } else if (label && !isDense(d.cadence) && !mine.some((m) => (m.shape === 'ease-in' && m.durationMs > EASE_IN_MIN_MS) || fitted(m))) {
+        const worst = mine.map((m) => m.cadence).sort((x, y) => y.max - x.max)[0];
+        if (worst) unsure('ease-in', `${moment}: ${label} is declared to ease in, the measured curve cannot confirm it`, `measured ${label}`, worst);
+        else add('inconclusive', `${moment}: ${label} is declared to ease in and its motion was not recorded with enough samples to fit a curve`, `ease-in measured ${label}`, undefined, { check: 'ease-in', key: `measured ${label}`, cadence: d.cadence });
+      }
+    }
+    for (const e of d.motion) for (const m of e.moves) {
+      if (m.easeInTie && m.durationMs > EASE_IN_MIN_MS && m.samples / (m.durationMs / FRAME_MS) < SPARSE_DENSITY) unsure('ease-in', `${moment}: ${e.label} ${m.prop} may ease in`, `measured ${e.label}`, m.cadence);
+      if (m.shape === 'ease-in' && m.durationMs > EASE_IN_MIN_MS) add('ease-in', `${moment}: ${e.label} ${m.prop} measured ease-in over ${m.durationMs} ms`, `measured ${e.label}`);
+      for (const j of m.jumps) add('jump', `${moment}: ${e.label} ${m.prop} jumps ${j.size} at ${j.atMs} ms`, `${moment} ${e.label} ${m.prop}`);
+    }
+  }
+  for (const d of Object.values(el.moments)) {
+    const tr = d?.transition ?? el.transition;
+    if (tr.properties.includes('all') && tr.durations.some((x) => x > 0)) {
+      add('transition-all', '`transition: all` animates whatever changes, layout included', 'all');
+      break;
+    }
+  }
+  for (const u of el.undecided ?? []) add('inconclusive', u.detail, `${u.check} ${u.key}`, undefined, { check: u.check, key: u.key, cadence: u.cadence });
+  if (el.interruptUnsure && !el.interrupt?.length) unsure('interrupt-jump', 'hover left mid-way: the animation restarted but the value cannot be followed', 'hover', el.interruptUnsure);
+  if (el.interrupt?.length) add('interrupt-jump', `hover left mid-way: ${el.interrupt.map((j) => `${j.label} ${j.prop}`).join(', ')} jump instead of reversing`, 'hover');
+  if (el.reduced?.moves) add('reduced-motion-moves', `with prefers-reduced-motion it still moves (${el.reduced.moves})`, 'press');
+  if (el.reduced?.residue) add('reduced-motion-residue', `with prefers-reduced-motion a transform stays after release (${el.reduced.residue})`, 'press');
+  return out;
+};
+
+// Same kind of control, same moment, different declared durations: no single motion grammar.
+export const inconsistencies = (elements, policy = {}) => {
+  const groups = new Map();
+  for (const el of elements) for (const [moment, d] of Object.entries(el.moments)) {
+    if (!d || moment === 'focus') continue;
+    const tr = d.transition ?? el.transition;
+    const durs = d.changed.map((p) => transitionOf(tr, p)?.duration).filter((x) => x > 0);
+    if (!durs.length) continue;
+    const key = `${el.kind} ${moment}`;
+    if (!groups.has(key)) groups.set(key, new Map());
+    const top = Math.max(...durs);
+    groups.get(key).set(top, [...(groups.get(key).get(top) ?? []), el.label]);
+  }
+  const out = [];
+  for (const [key, byDur] of groups) {
+    const ds = [...byDur.keys()].sort((a, b) => a - b);
+    if (ds.length < 2 || ds.at(-1) / ds[0] < INCONSISTENT_RATIO || ds.at(-1) - ds[0] < INCONSISTENT_MIN_GAP_MS) continue;
+    if (ds.every((x) => closeToToken(x, policy.tokens?.durations))) continue;
+    out.push({ kind: 'inconsistent-duration', element: key, key, detail: ds.map((x) => `${x} ms (${byDur.get(x).slice(0, 2).join(', ')}${byDur.get(x).length > 2 ? ', ...' : ''})`).join(' vs ') });
+  }
+  return out;
+};

package/skills/motion-audit/scripts/lib/kinds.mjs

@@ -0,0 +1,33 @@
+// The single registry of finding kinds. SKILL.md's table is checked against it by the tests.
+// source: 'frames' = measured from the per-frame trace, 'pixels' = screenshot or computed-style
+// comparison, 'css' = read from declared CSS, 'events' = Animation objects and DOM events.
+export const LEVELS = ['off', 'info', 'warning', 'error'];
+
+export const KINDS = {
+  'no-feedback': { level: 'error', source: 'pixels', user: 'Hover changes nothing on a button: the UI feels dead (links: warning; inputs: not reported)' },
+  'no-press-feedback': { level: 'warning', source: 'pixels', user: 'Press changes nothing on a button (links and inputs: not reported)' },
+  'no-focus-feedback': { level: 'error', source: 'pixels', user: 'Keyboard focus is invisible' },
+  'hover-only-control': { level: 'warning', source: 'pixels', user: 'A control revealed only by pointer hover stays invisible when it gets keyboard focus' },
+  snaps: { level: 'warning', source: 'css', user: 'Feedback exists but jumps: the changed properties have no transition' },
+  'layout-animated': { level: 'error', source: 'frames', user: 'Width, height, top, margin, padding or font animate: neighbours shift and layout runs every frame' },
+  'long-frame': { level: 'error', source: 'frames', user: 'A frame over 50 ms during hover, a click transition or scroll (warning on a dev build)' },
+  'ease-in': { level: 'error', source: 'css', user: 'The response starts slow: declared curve or measured trajectory' },
+  duration: { level: 'warning', source: 'css', user: 'Declared duration outside the band for the gesture (hover 80-300, press 50-200, focus up to 250 ms)' },
+  linear: { level: 'warning', source: 'css', user: 'A transform or opacity transition declared linear: mechanical' },
+  'transition-all': { level: 'warning', source: 'css', user: '`transition: all` animates whatever changes, layout included' },
+  'inconsistent-duration': { level: 'warning', source: 'css', user: 'Same kind of control and gesture with declared durations 1.5x and 60 ms apart' },
+  jump: { level: 'error', source: 'frames', user: 'A frame moves several times faster than a smooth curve allows: a teleporting animation' },
+  'interrupt-jump': { level: 'error', source: 'events', user: 'Leaving hover mid-way, or clicking again mid-transition, jumps instead of reversing' },
+  'not-interruptible': { level: 'error', source: 'events', user: 'A toggle clicked back part-way through its motion restarts from the other end (needs --interact)' },
+  'ungated-hover': { level: 'warning', source: 'css', user: '`:hover` moves things outside `@media (hover: hover)`: it sticks after a tap on touch screens' },
+  'reduced-motion-moves': { level: 'error', source: 'css', user: 'With prefers-reduced-motion a press still translates, rotates or scales by more than 6 %' },
+  'reduced-motion-residue': { level: 'error', source: 'css', user: 'With prefers-reduced-motion a transform stays after release' },
+  'reduced-motion-loop': { level: 'error', source: 'events', user: 'An infinite moving animation keeps running under reduced motion (small rotate-only spinners excepted)' },
+  'reduced-motion-hidden': { level: 'error', source: 'pixels', user: 'Content waits for an entrance that reduced motion skipped: it stays at opacity 0' },
+  'reduced-motion-missing': { level: 'warning', source: 'css', user: 'Things move and no readable stylesheet has a reduced-motion rule (info when some sheets are unreadable)' },
+  'no-entrance': { level: 'info', source: 'events', user: 'A section below the fold appears without an entrance (opt-in with --entrances; never fails the run)' },
+  inconclusive: { level: 'warning', source: 'frames', user: 'The frames were too sparse to confirm or rule out a finding (its `check`): rerun on a quieter machine, without --cpu; never fails the run' },
+  'click-target': { level: 'error', source: 'pixels', user: 'The --click selector matches nothing visible' },
+};
+
+export const kindNames = () => Object.keys(KINDS);