motion-audit 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,278 @@
+// Pure trajectory analysis: one property sampled over time, curve classification, jump detection.
+import { LONG_FRAME_STEP_SLACK_MS, FRAME_MS, DENSE_MAX_MS, SERIES_JUMP_MAX_DT_MS, SERIES_PEAK_SLOPE, SERIES_NEIGHBOUR_RATIO, JUMP_MIN_SHARE, OVERSHOOT_SPRING_PCT, REMOUNT_GAP_FRAMES } from './constants.mjs';
+
+export const round = (x, d = 1) => Math.round(x * 10 ** d) / 10 ** d;
+export const median = (a) => {
+  const s = [...a].sort((x, y) => x - y);
+  if (!s.length) return 0;
+  return s.length % 2 ? s[(s.length - 1) / 2] : (s[s.length / 2 - 1] + s[s.length / 2]) / 2;
+};
+
+export const COLS = ['left', 'top', 'width', 'height', 'opacity', 'tx', 'ty', 'sx', 'sy', 'rot', 'ow', 'oh'];
+export const PROP_OF = { left: 'left', top: 'top', width: 'width', height: 'height', opacity: 'opacity', tx: 'translateX', ty: 'translateY', sx: 'scaleX', sy: 'scaleY', rot: 'rotate', ow: 'layoutWidth', oh: 'layoutHeight' };
+export const EPS = { left: 1, top: 1, width: 1, height: 1, translateX: 1, translateY: 1, scaleX: 0.01, scaleY: 0.01, rotate: 1, opacity: 0.02, layoutWidth: 1, layoutHeight: 1 };
+
+const SHAPES = [
+  ['linear', (u) => u],
+  ['ease-out', (u) => 1 - (1 - u) ** 2], ['ease-out', (u) => 1 - (1 - u) ** 3], ['ease-out', (u) => 1 - (1 - u) ** 5],
+  ['ease-in', (u) => u ** 2], ['ease-in', (u) => u ** 3],
+  ['ease-in-out', (u) => (u < 0.5 ? 2 * u * u : 1 - 2 * (1 - u) ** 2)], ['ease-in-out', (u) => (u < 0.5 ? 4 * u ** 3 : 1 - 4 * (1 - u) ** 3)],
+];
+
+// The curve family that fits a settled motion best. The animation began somewhere after the last unmoved
+// sample and ended somewhere before the first settled one: on a machine that drops frames those intervals
+// are long, so the start and the end are searched inside them (FIT_GRID steps each) rather than taken at the
+// sample times, which would read a late-starting or late-seen ease-in as an ease-in-out.
+const FIT_GRID = 6;
+const EASE_IN_TIE_RATIO = 1.5;
+const EASE_IN_TIE_ERROR = 0.02;
+const bestShape = (t, v, start, settle) => {
+  const v0 = v[start - 1];
+  const span = v[settle] - v0;
+  const best = new Map();
+  for (let a = 0; a < FIT_GRID; a++) {
+    const ts = t[start - 1] + ((t[start] - t[start - 1]) * a) / FIT_GRID;
+    for (let b = 1; b <= FIT_GRID; b++) {
+      const te = t[settle - 1] + ((t[settle] - t[settle - 1]) * b) / FIT_GRID;
+      for (const [name, f] of SHAPES) {
+        let err = 0;
+        for (let j = start - 1; j <= settle; j++) err += ((v[j] - v0) / span - f(Math.min(1, Math.max(0, (t[j] - ts) / (te - ts))))) ** 2;
+        if (err < (best.get(name) ?? Infinity)) best.set(name, err);
+      }
+    }
+  }
+  const [[shape, least]] = [...best.entries()].sort((x, y) => x[1] - y[1]);
+  // Sparse samples cannot always tell an ease-in from the other curves: it is a tie when the best ease-in fit
+  // is nearly as good as the winner.
+  const easeIn = best.get('ease-in');
+  return { shape, easeInTie: shape !== 'ease-in' && easeIn <= Math.max(EASE_IN_TIE_RATIO * least, least + EASE_IN_TIE_ERROR) };
+};
+
+// Angles read from a matrix wrap at +-180 degrees: unwrap so a spinning element is a smooth series.
+export const unwrap = (v) => v.reduce((out, x, i) => {
+  if (!i) return [x];
+  let y = x;
+  while (y - out[i - 1] > 180) y -= 360;
+  while (y - out[i - 1] < -180) y += 360;
+  return [...out, y];
+}, []);
+
+// Jumps of a settled motion. Velocity is taken per millisecond, so irregular sampling does not
+// change it; only intervals short enough to bound the instantaneous velocity count. A jump is a
+// step that is a sizeable share of the amplitude and moves several times faster than the average
+// speed of the whole motion (no easing curve peaks that high after its first interval) and than
+// both short neighbours. The first interval is skipped: an ease-out legitimately starts fastest.
+// `unresolved` counts steps that pass every test but the speed one, in a motion some interval of which is longer
+// than DENSE_MAX_MS (or in an interval too long to bound the velocity): the speed test cannot decide them.
+const findJumps = (t, v, start, settle, amp, t0, shape, reads = t) => {
+  const jumps = [];
+  let unresolved = 0;
+  if (settle - start < 4) return { jumps, unresolved };
+  const avgVelocity = amp / Math.max(1, t[settle] - t0);
+  const dense = t.slice(start, settle + 1).every((x, i) => x - t[start + i - 1] <= DENSE_MAX_MS);
+  const peak = SERIES_PEAK_SLOPE * (shape === 'spring' ? 2 : 1);
+  const velocity = (k) => {
+    const dt = t[k] - t[k - 1];
+    // The interval counts by the frame times and by when the values were read: a value read long after its frame started (a long
+    // task in between) says nothing about the frame-to-frame step.
+    const read = reads[k] - reads[k - 1];
+    return dt > 0 && dt <= SERIES_JUMP_MAX_DT_MS && read <= SERIES_JUMP_MAX_DT_MS ? Math.abs(v[k] - v[k - 1]) / dt : null;
+  };
+  const fast = (k) => { const x = velocity(k); return x !== null && x >= peak * avgVelocity; };
+  for (let k = start + 1; k <= settle; k++) {
+    // Chromium can sample a frame in the middle of a teleport: the step spreads over consecutive intervals that are each
+    // faster than any curve peaks. They are one jump, compared with the intervals on both sides of the run.
+    if (k < settle && fast(k) && fast(k + 1)) {
+      let end = k + 1;
+      while (end < settle && fast(end + 1)) end++;
+      const total = Math.abs(v[end] - v[k - 1]);
+      if (total >= JUMP_MIN_SHARE * amp) {
+        const before = velocity(k - 1);
+        const after = velocity(end + 1);
+        const run = total / (t[end] - t[k - 1]);
+        if (before === null || after === null) unresolved++;
+        else if (run >= SERIES_NEIGHBOUR_RATIO * before && run >= SERIES_NEIGHBOUR_RATIO * after) jumps.push({ atMs: round(t[k] - t0, 0), size: round(total, 2) });
+      }
+      k = end;
+      continue;
+    }
+    const step = Math.abs(v[k] - v[k - 1]);
+    if (step < JUMP_MIN_SHARE * amp) continue;
+    const vel = velocity(k);
+    if (vel === null) { unresolved++; continue; }
+    // Both neighbours must be judged too: a step between long intervals is not told from a steep easing.
+    const neighbours = [velocity(k - 1), velocity(k + 1)];
+    if (neighbours.includes(null)) { unresolved++; continue; }
+    if (neighbours.some((x) => vel < SERIES_NEIGHBOUR_RATIO * x)) continue;
+    // Sampled frame by frame (60 Hz) all along, a step slower than a jump is settled: it is no jump. With any longer
+    // interval in the motion (a 30 fps machine, a stall) the question stays open.
+    if (vel < peak * avgVelocity) { if (!dense) unresolved++; continue; }
+    jumps.push({ atMs: round(t[k] - t0, 0), size: round(step, 2) });
+  }
+  return { jumps, unresolved };
+};
+
+// A round trip (a toast in and out) is judged leg by leg, each against its own amplitude and speed:
+// the average speed of the whole series says nothing about any one leg. Returns jumps with `atMs`
+// relative to `t0`, the start of the whole series.
+const legJumps = (t, v, eps, t0, reads = t) => {
+  const first = v[0];
+  let peak = 0;
+  v.forEach((x, i) => { if (Math.abs(x - first) > Math.abs(v[peak] - first)) peak = i; });
+  const tol = Math.abs(v[peak] - first) * 0.005;
+  let arrive = peak;
+  while (arrive > 0 && Math.abs(v[arrive - 1] - v[peak]) <= tol) arrive--;
+  let depart = peak;
+  while (depart < v.length - 1 && Math.abs(v[depart + 1] - v[peak]) <= tol) depart++;
+  const out = [];
+  let unresolved = 0;
+  for (const [a, b] of [[0, arrive], [depart, v.length - 1]]) {
+    const leg = analyzeSeries(t.slice(a, b + 1), v.slice(a, b + 1), eps, [], [], reads.slice(a, b + 1));
+    for (const j of leg?.jumps ?? []) out.push({ atMs: round(leg.startT + j.atMs - t0, 0), size: j.size });
+    unresolved += leg?.unresolved ?? 0;
+  }
+  return { jumps: out, unresolved };
+};
+
+// Steps where one node was replaced by another (`cuts`: indices of the first sample of the new node):
+// a node removed while still moving and a new one that starts elsewhere is a teleport.
+// A join is a jump only if the interval across it and both the intervals beside it were judged: within the limit by frame time and
+// by the time the values were read. A longer interval (a motion that continues across a 300 ms gap) leaves it unresolved.
+const cutJumps = (t, v, cuts, eps, range, t0, reads = t) => {
+  const jumps = [];
+  let unresolved = 0;
+  const judged = (k) => k >= 1 && k < t.length && t[k] - t[k - 1] <= SERIES_JUMP_MAX_DT_MS && reads[k] - reads[k - 1] <= SERIES_JUMP_MAX_DT_MS;
+  for (const c of cuts) {
+    if (c < 2 || c >= v.length) continue;
+    const step = Math.abs(v[c] - v[c - 1]);
+    const moving = Math.abs(v[c - 1] - v[c - 2]) > eps;
+    if (!(moving && step >= Math.max(JUMP_MIN_SHARE * range, 3 * eps))) continue;
+    if (![c - 1, c, c + 1].every(judged)) { unresolved++; continue; }
+    jumps.push({ atMs: round(t[c] - t0, 0), size: round(step, 2) });
+  }
+  return { jumps, unresolved };
+};
+
+// One property over time (`t` ms, `v` values): duration, overshoot, curve shape and jumps.
+// Median and longest interval (ms) between samples.
+const cadenceOf = (t) => {
+  const dts = t.slice(1).map((x, i) => x - t[i]);
+  return { median: round(median(dts), 0), max: round(Math.max(0, ...dts), 0) };
+};
+
+export const analyzeSeries = (t, v, eps, cuts = [], longFrames = [], reads = t) => {
+  const n = v.length;
+  if (n < 4) return null;
+  const first = v[0];
+  const final = v[n - 1];
+  const range = Math.max(...v) - Math.min(...v);
+  if (range < eps) return null;
+  const returns = Math.abs(final - first) < eps;
+  const amp = returns ? range : Math.abs(final - first);
+  const dir = returns ? 1 : Math.sign(final - first);
+  const tol = amp * 0.005;
+  const start = v.findIndex((x) => Math.abs(x - first) > tol);
+  if (start < 1) return null;
+  const tail = v.slice(-2);
+  const settled = tail.every((x, i) => i === 0 || Math.abs(x - tail[i - 1]) <= tol);
+  let settle = n - 1;
+  if (settled) while (settle > start && Math.abs(v[settle - 1] - final) <= tol) settle--;
+  const t0 = t[start - 1];
+  let over = 0;
+  if (!returns && settled) for (let j = start; j < n; j++) over = Math.max(over, (v[j] - final) * dir);
+  const overshootPct = round((over / amp) * 100);
+  let shape;
+  let easeInTie = false;
+  if (returns) shape = 'round-trip';
+  else if (settle - start < 2) shape = 'step';
+  else if (overshootPct > OVERSHOOT_SPRING_PCT) shape = 'spring';
+  else {
+    ({ shape, easeInTie } = bestShape(t, v, start, settle));
+  }
+  let jumps;
+  let unresolved = 0;
+  if (cuts.length) {
+    // Joined nodes are separate motions: each is judged on its own, the joins by cutJumps.
+    const bounds = [0, ...cuts, n];
+    const legs = bounds.slice(1).flatMap((end, i) => {
+      const leg = analyzeSeries(t.slice(bounds[i], end), v.slice(bounds[i], end), eps, [], [], reads.slice(bounds[i], end));
+      unresolved += leg?.unresolved ?? 0;
+      return (leg?.jumps ?? []).map((j) => ({ atMs: round(leg.startT + j.atMs - t0, 0), size: j.size }));
+    });
+    const joins = cutJumps(t, v, cuts, eps, range, t0, reads);
+    unresolved += joins.unresolved;
+    jumps = legs.concat(joins.jumps);
+  } else ({ jumps, unresolved } = shape === 'round-trip' ? legJumps(t, v, eps, t0, reads) : findJumps(t, v, start, settle, amp, t0, shape, reads));
+  // A step in a frame that overlaps a long frame is that frame: the animation's clock ran on while the thread was blocked.
+  if (longFrames.length) {
+    jumps = jumps.filter((j) => {
+      const k = t.findIndex((x) => Math.abs(x - (t0 + j.atMs)) < 1.5);
+      const [from, to] = k > 0 ? [t[k - 1], t[k]] : [t0 + j.atMs, t0 + j.atMs];
+      return !longFrames.some(([s, len]) => s <= to + LONG_FRAME_STEP_SLACK_MS && s + len >= from - LONG_FRAME_STEP_SLACK_MS);
+    });
+  }
+  return { from: round(v[start - 1], 2), to: round(final, 2), startT: t0, firstT: t[start], durationMs: round(t[settle] - t0, 0), samples: settle - start + 1, easeInTie, cadence: cadenceOf(t.slice(start - 1, settle + 1)), overshootPct, shape, settled, jumps, unresolved };
+};
+
+// Whether a move is an animation: seen in more than one frame and longer than two 60 Hz frames. A change seen in a
+// single frame is a step however long that frame lasted (a machine that drops frames has 100 ms frames).
+export const animatedMove = (m) => m.samples > 1 && m.durationMs > 2 * FRAME_MS;
+
+export const analyzeElement = (el, longFrames = []) => {
+  const moves = [];
+  for (const c of COLS) {
+    const r = analyzeSeries(el.t, c === 'rot' ? unwrap(el[c]) : el[c], EPS[PROP_OF[c]], el.cuts, longFrames, el.r ?? el.t);
+    if (r) moves.push({ prop: PROP_OF[c], ...r });
+  }
+  return moves.length ? { label: el.label, root: el.root, moves } : null;
+};
+
+const kindOf = (e) => `${e.tag ?? e.label.replace(/[#.].*$/, '').toUpperCase()}|${e.role ?? ''}`;
+
+// A node removed mid-recording and a node of the same tag and role mounted in the same parent within
+// REMOUNT_GAP_FRAMES is one component re-mounted (a changed React `key`): their samples form one series,
+// with `cuts` at the joins, so the animation that starts over shows as a jump.
+export const joinRemounts = (elems) => {
+  if (elems.length < 2) return elems;
+  // Every tracked node is sampled in the same frames: gaps are counted in those frames, whatever they lasted.
+  const frames = [...new Set(elems.flatMap((e) => e.t))].sort((x, y) => x - y);
+  const frameOf = new Map(frames.map((x, i) => [x, i]));
+  const taken = new Set();
+  const next = new Map();
+  for (const a of [...elems].sort((x, y) => x.t.at(-1) - y.t.at(-1))) {
+    if (a.root || frameOf.get(a.t.at(-1)) >= frames.length - 2) continue;
+    const gap = (b) => frameOf.get(b.t[0]) - frameOf.get(a.t.at(-1));
+    const b = elems.filter((x) => x !== a && !x.root && !taken.has(x) && x.parent === a.parent && kindOf(x) === kindOf(a) && gap(x) > 0 && gap(x) <= REMOUNT_GAP_FRAMES).sort((x, y) => x.t[0] - y.t[0])[0];
+    if (b) { next.set(a, b); taken.add(b); }
+  }
+  return elems.filter((e) => !taken.has(e)).map((head) => {
+    if (!next.has(head)) return head;
+    const joined = { ...head, cuts: [] };
+    for (const c of COLS) joined[c] = [...head[c]];
+    joined.t = [...head.t];
+    joined.r = [...(head.r ?? head.t)];
+    for (let e = next.get(head); e; e = next.get(e)) {
+      joined.cuts.push(joined.t.length);
+      joined.t.push(...e.t);
+      joined.r.push(...(e.r ?? e.t));
+      for (const c of COLS) joined[c].push(...e[c]);
+    }
+    return joined;
+  });
+};
+
+// `longFrames`: [[startMs, durationMs]] of the recording's long frames: jumps they explain are not reported.
+export const analyzeRecording = (rec, { longFrames = [] } = {}) => joinRemounts(rec?.elems ?? []).map((e) => analyzeElement(e, longFrames)).filter(Boolean);
+
+// 'ease-in' when the curve starts slower than it ends; 'linear'; otherwise 'ok'.
+export const easingKind = (e) => {
+  if (e === 'linear' || /^linear\(\s*0(?:\s+0%)?\s*,\s*1(?:\s+100%)?\s*\)$/.test(e)) return 'linear';
+  if (e === 'ease-in') return 'ease-in';
+  const m = e.match(/^cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)$/);
+  if (!m) return 'ok';
+  const [x1, y1, x2, y2] = m.slice(1).map(Number);
+  if (x1 === y1 && x2 === y2) return 'linear';
+  const startSlope = x1 > 0 ? y1 / x1 : Infinity;
+  const endSlope = x2 < 1 ? (1 - y2) / (1 - x2) : Infinity;
+  return startSlope < 0.5 && endSlope > 1 ? 'ease-in' : 'ok';
+};

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

@@ -0,0 +1,76 @@
+// What becomes of a sighting (a jump seen in one recording) that the re-measures do not reproduce: it is dropped only
+// when a re-measure that could see that very motion did not see it; otherwise it stays visible as undecided. Pure.
+import { FINE_SAMPLING_MS, JUMP_MAX_DT_MS, DENSE_MAX_MS, DENSE_MEDIAN_MS, SERIES_JUMP_MAX_DT_MS, SIGHTING_MIN_SAMPLES } from './constants.mjs';
+
+// The sampling a recording gave each motion in it. `moved`: [{ label, moves: [{ prop, samples, unresolved, cadence }] }].
+// `mark`: { median, max } of the intervals around the second gesture, for the checks that depend on one; null when
+// there was none. `ran` is false when the probe did not run (it threw, the control left the page).
+export const coverageOf = (moved, { ran = true, mark = null, moment = '' } = {}) => ({
+  ran,
+  mark,
+  moves: moved.flatMap((e) => e.moves.map((m) => ({ moment, label: e.label, prop: m.prop, samples: m.samples, unresolved: m.unresolved, maxDt: m.cadence.max }))),
+});
+export const NO_COVERAGE = { ran: false, mark: null, moves: [] };
+
+// The worst of two coverages of the same motion (fewest samples, any unresolved step, longest interval).
+export const mergeCoverage = (a, b) => {
+  const moves = [...a.moves];
+  for (const m of b.moves) {
+    const i = moves.findIndex((x) => sameMotion(x, m));
+    if (i < 0) moves.push(m);
+    else moves[i] = { ...moves[i], samples: Math.min(moves[i].samples, m.samples), unresolved: moves[i].unresolved || m.unresolved, maxDt: Math.max(moves[i].maxDt, m.maxDt) };
+  }
+  const mark = a.mark && b.mark ? { median: Math.max(a.mark.median, b.mark.median), max: Math.max(a.mark.max, b.mark.max) } : a.mark ?? b.mark;
+  return { ran: a.ran && b.ran, mark, moves };
+};
+
+export const sameMotion = (a, b) => a.label === b.label && a.prop === b.prop && (a.moment ?? '') === (b.moment ?? '');
+
+// Whether a recording could have shown the sighting's jump: the very motion is in it (same element label, property and
+// gesture), judged on enough samples, with no step left unresolved and no interval too long to bound a velocity.
+// For a check that depends on a second gesture (`mark`) the probe must have run, and the frames around that gesture
+// must follow a value frame by frame.
+export const canSee = (coverage, sighting, { mark = false } = {}) => {
+  if (!coverage?.ran) return false;
+  const m = coverage.moves.find((x) => sameMotion(x, sighting));
+  if (!m || m.samples < SIGHTING_MIN_SAMPLES || m.unresolved || m.maxDt > SERIES_JUMP_MAX_DT_MS) return false;
+  if (!mark) return true;
+  return Boolean(coverage.mark) && coverage.mark.median <= FINE_SAMPLING_MS && coverage.mark.max <= JUMP_MAX_DT_MS;
+};
+
+export const isDense = (cadence) => Boolean(cadence) && cadence.median <= DENSE_MEDIAN_MS && cadence.max <= DENSE_MAX_MS;
+
+// The sightings a re-measure did not rule out, each with why: 'flake' (a clear step in frame-by-frame sampling that the
+// re-measures did not reproduce) or 'unseen' (no re-measure could judge that motion). `sightings`: [{ label, prop, moment?, dense,
+// cadence? }] (the cadence is that of the intervals around the sighting); `reruns`: [{ saw: [{ label, prop, moment? }], coverage }].
+export const undecidedSightings = (sightings, reruns, opts = {}) => sightings.flatMap((s) => {
+  if (s.dense) return [{ sighting: s, cause: 'flake' }];
+  const ruledOut = reruns.some((r) => !(r.saw ?? []).some((x) => sameMotion(x, s)) && canSee(r.coverage, s, opts));
+  return ruledOut ? [] : [{ sighting: s, cause: 'unseen' }];
+});
+
+// 'drop' when every sighting was ruled out; otherwise the cause of the first that was not ('flake' before 'unseen').
+export const unconfirmedVerdict = (sightings, reruns, opts = {}) => {
+  const left = undecidedSightings(sightings, reruns, opts);
+  return left.find((x) => x.cause === 'flake')?.cause ?? left[0]?.cause ?? 'drop';
+};
+
+// The reason an undecided row gives, by cause.
+export const undecidedReason = (cause, runs) => (cause === 'flake'
+  ? `seen in 1 of ${runs} recordings, not reproduced`
+  : `seen in 1 of ${runs} recordings; the others could not judge that motion (frames too sparse, or it was not there)`);
+
+// The CSS properties whose declared transition shows up as a measured property (a transform moves the box, so it also
+// moves the measured position and size).
+const TRANSFORM = ['transform', 'translate', 'scale', 'rotate'];
+const MEASURED_BY = {
+  translateX: TRANSFORM, translateY: TRANSFORM, scaleX: TRANSFORM, scaleY: TRANSFORM, rotate: TRANSFORM, opacity: ['opacity'],
+  left: [...TRANSFORM, 'left', 'right', 'inset', 'marginLeft', 'marginRight'], top: [...TRANSFORM, 'top', 'bottom', 'inset', 'marginTop', 'marginBottom'],
+  width: [...TRANSFORM, 'width', 'minWidth', 'maxWidth', 'flex', 'padding', 'paddingLeft', 'paddingRight'], height: [...TRANSFORM, 'height', 'minHeight', 'maxHeight', 'flex', 'padding', 'paddingTop', 'paddingBottom'],
+  layoutWidth: ['width', 'minWidth', 'maxWidth', 'flex', 'padding', 'paddingLeft', 'paddingRight'], layoutHeight: ['height', 'minHeight', 'maxHeight', 'flex', 'padding', 'paddingTop', 'paddingBottom'],
+};
+
+
+// The measured properties a CSS property moves (a declared `width` shows as width and layoutWidth; a `transform` as its parts).
+const camel = (name) => name.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+export const measuredFor = (cssProp) => Object.keys(MEASURED_BY).filter((m) => MEASURED_BY[m].includes(camel(cssProp)));

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

@@ -0,0 +1,86 @@
+// The rows a sighting leaves when the re-measures do not reproduce it (see sightings.mjs): a jump seen in one recording is
+// dropped only when a re-measure that could see that motion did not see it. Pure: no browser.
+import { CONFIRM_MAJORITY, CONFIRM_RUNS } from './constants.mjs';
+import { NO_COVERAGE, coverageOf, isDense, undecidedReason, undecidedSightings, unconfirmedVerdict } from './sightings.mjs';
+
+const sparseText = (c) => `frames too sparse: median Δt ${c.median} ms, max ${c.max} ms`;
+
+// What a gesture's recording could see of each of its motions, and the jumps seen in it.
+const elementCoverage = (el) => ({ ran: true, mark: null, moves: Object.entries(el.moments ?? {}).flatMap(([moment, d]) => coverageOf(d.motion, { moment }).moves) });
+const elementSaw = (el) => Object.entries(el.moments ?? {}).flatMap(([moment, d]) => d.motion.flatMap((e) => e.moves.filter((m) => m.jumps.length).map((m) => ({ moment, label: e.label, prop: m.prop }))));
+
+// Undecided rows of a gesture's flaky aspects (`el.unconfirmed`): [{ check, key, detail }], one per sighting. `later`: the
+// re-measures of the element (null where the probe did not run).
+export const undecidedOf = (el, later) => {
+  const out = [];
+  const unconfirmed = el.unconfirmed ?? [];
+  if (unconfirmed.includes('interrupt')) {
+    const verdict = unconfirmedVerdict(el.interruptSightings ?? [], later.map((x) => ({ saw: x?.interrupt ?? [], coverage: x?.interruptCoverage ?? NO_COVERAGE })), { mark: true });
+    if (verdict !== 'drop') out.push({ check: 'interrupt-jump', key: 'hover', detail: `hover left mid-way: ${undecidedReason(verdict, CONFIRM_RUNS)}`, cadence: el.interruptCadence });
+  }
+  if (unconfirmed.includes('jump')) {
+    const reruns = later.map((x) => ({ saw: x ? elementSaw(x) : [], coverage: x ? elementCoverage(x) : NO_COVERAGE }));
+    for (const [moment, d] of Object.entries(el.moments)) for (const e of d.motion) for (const m of e.moves) {
+      if (!m.jumps.length) continue;
+      const verdict = unconfirmedVerdict([{ moment, label: e.label, prop: m.prop, dense: isDense(m.cadence) }], reruns);
+      if (verdict !== 'drop') out.push({ check: 'jump', key: `${moment} ${e.label} ${m.prop}`, detail: `${moment}: ${e.label} ${m.prop} ${undecidedReason(verdict, CONFIRM_RUNS)}`, cadence: m.cadence });
+    }
+  }
+  // A step too coarse to judge (unresolved) in a gesture: ruled out only by a re-measure that could see that motion and saw no jump.
+  const reruns = later.map((x) => ({ saw: x ? elementSaw(x) : [], coverage: x ? elementCoverage(x) : NO_COVERAGE }));
+  for (const [moment, d] of Object.entries(el.moments)) for (const e of d.motion) for (const m of e.moves) {
+    if (!(m.unresolved > 0) || m.jumps.length) continue;
+    const verdict = unconfirmedVerdict([{ moment, label: e.label, prop: m.prop, dense: false }], reruns);
+    const key = `${moment} ${e.label} ${m.prop}`;
+    if (verdict !== 'drop' && !out.some((o) => o.key === key)) out.push({ check: 'jump', key, detail: `${moment}: ${e.label} ${m.prop} has a step the frames were too coarse to judge: ${undecidedReason(verdict, CONFIRM_RUNS)}`, cadence: m.cadence });
+  }
+  return out;
+};
+
+// Inconclusive rows of the --click check. `first`: the first measurement (before any flaky aspect was dropped);
+// `unconfirmed`: the aspects the majority vote dropped; `reruns`: the re-measures (a missing target counts as none).
+export const clickRows = (label, first, unconfirmed, reruns) => {
+  const rows = [];
+  const row = (check, detail, cadence) => rows.push({ kind: 'inconclusive', check, element: label, key: 'click', detail, cadence });
+  const asReruns = (pick) => reruns.map((x) => ({ saw: x[pick] ?? [], coverage: x.coverage ?? NO_COVERAGE }));
+  const dropped = (name, list) => list.length > 0 && unconfirmed.includes(name);
+  if (!(first.jumps.length > 0 && !dropped('jump', first.jumps))) {
+    if (first.unsure) row('jump', `a step in the transition could be a jump: ${sparseText(first.unsure)}`, first.unsure);
+    else if (dropped('jump', first.jumps) && first.jumpSightings.length) {
+      const left = undecidedSightings(first.jumpSightings, asReruns('jumps'));
+      const cause = left.find((x) => x.cause === 'flake') ?? left[0];
+      if (cause) row('jump', `a step in the transition could be a jump: ${undecidedReason(cause.cause, CONFIRM_RUNS)}`, cause.sighting.cadence);
+    }
+  }
+  if (!(first.interrupt.length > 0 && !dropped('interrupt', first.interrupt))) {
+    if (first.interruptUnsure) row('interrupt-jump', `second click: the animation restarted but the value cannot be followed: ${sparseText(first.interruptUnsure)}`, first.interruptUnsure);
+    else if (dropped('interrupt', first.interrupt)) {
+      const left = undecidedSightings(first.interruptSightings, asReruns('interrupt'), { mark: true });
+      const cause = left.find((x) => x.cause === 'flake') ?? left[0];
+      if (cause) row('interrupt-jump', `second click: ${undecidedReason(cause.cause, CONFIRM_RUNS)}`, cause.sighting.cadence);
+    }
+  }
+  return rows;
+};
+
+// The re-measure the majority vote asks of the --click check: the measurement again with its retries off (two presses, four with
+// --interrupt), recorded in `reruns` as what the sighting rules read.
+export const clickRerun = (measure, reruns) => async () => {
+  const again = await measure(0);
+  reruns.push(again.missing ? { jumps: [], interrupt: [] } : again);
+  return again.missing ? null : again;
+};
+
+// A toggle whose reversal showed a restart in one probe: kept when most probes agree, otherwise dropped (`undecided` is
+// null) or left undecided ('flake' | 'unseen'). `again`: the other probes; one that did not run has no jumps and no coverage.
+export const confirmToggle = (r, again) => {
+  if (1 + again.filter((x) => x.jumps?.length).length >= CONFIRM_MAJORITY) return r;
+  const verdict = unconfirmedVerdict(r.sightings ?? [], again.map((x) => ({ saw: x.jumps ?? [], coverage: x.coverage ?? NO_COVERAGE })), { mark: true });
+  return { ...r, jumps: [], undecided: verdict === 'drop' ? null : verdict };
+};
+
+export const toggleRow = (r) => {
+  if (r.jumps.length || !(r.undecided || r.unsure)) return null;
+  const why = r.unsure ? `an animation restart cannot be followed: ${sparseText(r.unsure)}` : undecidedReason(r.undecided, CONFIRM_RUNS);
+  return { kind: 'inconclusive', check: 'not-interruptible', element: r.label, key: 'toggle', detail: `reversed part-way through its motion: ${why}`, cadence: r.unsure ?? r.sightings?.[0]?.cadence ?? r.cadence };
+};

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

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// motion-audit <url|file> [options]   (see --help)
+// Thin entry point: everything lives in ./lib. It always runs when executed, so it also works
+// through a symlink or junction (no main-module guard to defeat).
+import { main } from './lib/cli.mjs';
+
+process.exitCode = await main(process.argv.slice(2));