motion-audit 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,342 @@
+// audit(pageOrUrl, options): the whole run. Returns the report (schemaVersion 1).
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  CONFIRM_MAJORITY, CONFIRM_RUNS, DEFAULT_MAX_ELEMENTS, FRAME_NOISE_FACTOR, INTERACTIVE, LONG_FRAME_MS, MIN_PLAYWRIGHT, MAX_TOGGLES, NOISY_UNATTRIBUTED_MS, ENV_NOISE_MIN_ELEMENTS, RECOUNT_AFTER_MS, SCHEMA_VERSION,
+  SCROLL_STEP_MS, SCROLL_STEP_PX, SCROLL_TAIL_MS, TOGGLE, VIEWPORT,
+} from './constants.mjs';
+import { UsageError } from './args.mjs';
+import { AuditError, TRACER_CONFIG, createPixelComparer, calibrateFrames, idleFrameNoise, createPseudoStates, describeLong, load, longFramesBetween, sameLocation, setUnattributedLimit, unattributedLimit } from './browser.mjs';
+import { baselineIds, readReport } from './compare.mjs';
+import { finalize, loadConfig, validateConfig } from './config.mjs';
+import { inconsistencies, judgeElement } from './judge.mjs';
+import { devSignals, cssPath, describeElement, hasReducedMotionRule, invisibleContent, reachability, scrollPass, ungatedHoverMotion } from './page-scripts.mjs';
+import { tracer } from './page-tracer.mjs';
+import { clickRerun, clickRows, confirmToggle, toggleRow, undecidedOf } from './undecided.mjs';
+import { loadPlaywright } from './playwright.mjs';
+import { auditElement, clickMeasurer, contactSheet, eligibleToggles, probeToggle, reducedPass } from './probes.mjs';
+
+const SCROLL_OPTIONS = { step: SCROLL_STEP_PX, stepMs: SCROLL_STEP_MS, tail: SCROLL_TAIL_MS, maxScrollers: 5 };
+const MAX_SKIP_EXAMPLES = 3;
+
+// Flaky aspects of a measurement are kept only when most of CONFIRM_RUNS runs agree.
+const confirm = async (first, aspects, rerun) => {
+  const flagged = Object.entries(aspects).filter(([, has]) => has(first));
+  if (!flagged.length) return [];
+  const later = [];
+  for (let i = 1; i < CONFIRM_RUNS; i++) later.push(await rerun());
+  for (const [name, has] of flagged) {
+    const hits = 1 + later.filter((r) => r && has(r)).length;
+    if (hits < CONFIRM_MAJORITY) first.unconfirmed = [...(first.unconfirmed ?? []), name];
+  }
+  return later;
+};
+
+const unresolvedMoves = (el) => Object.entries(el.moments).flatMap(([moment, d]) => d.motion.flatMap((e) => e.moves.filter((m) => m.unresolved > 0 && !m.jumps.length).map((m) => ({ moment, label: e.label, prop: m.prop, cadence: m.cadence }))));
+const jumpKeys = (el) => Object.entries(el.moments).flatMap(([m, d]) => d.motion.flatMap((e) => e.moves.flatMap((mv) => mv.jumps.map(() => `${m}|${e.label}|${mv.prop}`))));
+// Long frames are confirmed per gesture: a frame that shows up in the press of one run and in the
+// focus of the next is two borderline frames, not one confirmed long frame.
+const elementAspects = (first) => ({
+  ...Object.fromEntries([...new Set(first.long.map((l) => l.moment))].map((m) => [`long:${m}`, (e) => e.long.some((l) => l.moment === m)])),
+  interrupt: (e) => (e.interrupt?.length ?? 0) > 0,
+  jump: (e) => jumpKeys(e).length > 0,
+  // A step the frames could not judge: the re-measures decide whether it is ruled out or stays undecided.
+  unresolved: (e) => unresolvedMoves(e).length > 0,
+});
+const dropUnconfirmed = (el) => {
+  for (const name of el.unconfirmed ?? []) {
+    if (name.startsWith('long:')) el.long = el.long.filter((l) => l.moment !== name.slice(5));
+    if (name === 'interrupt') el.interrupt = [];
+    if (name === 'jump') for (const d of Object.values(el.moments)) for (const e of d.motion) for (const m of e.moves) m.jumps = [];
+  }
+  delete el.unconfirmed;
+};
+
+const resolveConfig = (c) => (c && typeof c === 'object' ? validateConfig(c, 'config option') : loadConfig(c));
+
+const describeLongFrames = (long) => {
+  const { frames, culprit } = describeLong(long);
+  return `${frames.length} frame${frames.length > 1 ? 's' : ''} over ${LONG_FRAME_MS} ms (${frames.slice(0, 5).join(', ')} ms), ${culprit}`;
+};
+
+export const audit = async (pageOrUrl, o = {}) => {
+  const isPage = typeof pageOrUrl === 'object' && pageOrUrl !== null && typeof pageOrUrl.goto === 'function';
+  const config = resolveConfig(o.config);
+  const baseline = o.baseline ? (typeof o.baseline === 'string' ? baselineIds(readReport(o.baseline)) : new Set(o.baseline)) : new Set();
+  const out = resolve(o.out ?? mkdtempSync(join(tmpdir(), 'motion-audit-')));
+  mkdirSync(out, { recursive: true });
+  const max = o.max ?? DEFAULT_MAX_ELEMENTS;
+
+  let browser = null;
+  let context;
+  let page;
+  let url;
+  let initScript = null;
+  let throttle = null;
+  let pixels = null;
+  let pseudo = null;
+  if (isPage) {
+    page = pageOrUrl;
+    context = page.context();
+    url = o.url ?? page.url();
+    if (!url || url === 'about:blank') throw new AuditError('the page has not been navigated: pass options.url or call page.goto() first');
+    // Before Playwright 1.59 addInitScript returns nothing and a script cannot be removed: find out with an empty
+    // one (harmless if left behind) before the tracer is added.
+    const probe = await page.addInitScript(() => {});
+    if (typeof probe?.dispose !== 'function') throw new AuditError(`audit(page) needs Playwright ${MIN_PLAYWRIGHT.join('.')} or later: the page's Playwright cannot remove the tracer it installs (addInitScript returned no Disposable). Upgrade it, or pass a URL`);
+    await probe.dispose();
+    initScript = await page.addInitScript(tracer, TRACER_CONFIG);
+  } else {
+    url = pageOrUrl;
+    const { chromium } = loadPlaywright();
+    browser = await chromium.launch();
+    context = await browser.newContext({ viewport: VIEWPORT, deviceScaleFactor: 1, ...(o.storageState ? { storageState: o.storageState } : {}) });
+    await context.addInitScript(tracer, TRACER_CONFIG);
+    page = await context.newPage();
+  }
+  const notes = [];
+  try {
+    if (o.cpu > 1) {
+      throttle = await context.newCDPSession(page);
+      await throttle.send('Emulation.setCPUThrottlingRate', { rate: o.cpu });
+    }
+    const loadOptions = { waitFor: o.waitFor, allowRedirect: Boolean(o.allowRedirect) };
+    const first = await load(page, url, loadOptions);
+    const landed = first.landed;
+    if (first.redirected) notes.push(`${url} redirected to ${landed}`);
+    pseudo = await createPseudoStates(context, page);
+    pixels = await createPixelComparer(context);
+    const noise = Math.max(await calibrateFrames(context), await idleFrameNoise(page));
+    const unattributedMs = Math.max(noise >= LONG_FRAME_MS ? NOISY_UNATTRIBUTED_MS : LONG_FRAME_MS, Math.ceil(noise * FRAME_NOISE_FACTOR));
+    setUnattributedLimit(page, unattributedMs);
+    if (unattributedMs > LONG_FRAME_MS) notes.push(`this machine or page is noisy (frames of ${Math.round(noise)} ms with nothing happening): frames with no application script count only above ${unattributedMs} ms`);
+    const ctx = { page, context, pseudo, pixels, url, interact: Boolean(o.interact), loadOptions, notes };
+    const devServer = await page.evaluate(devSignals);
+    if (devServer.length) notes.push(`development build detected (${devServer.join(', ')}): long frames are reported as warnings; audit a production build (next start, vite preview) for them to count`);
+    const loafSupported = await page.evaluate(() => window.__mt.loafSupported);
+    const raw = [];
+    const add = (kind, element, detail, key) => raw.push({ kind, element, detail, key });
+    const coverage = { candidates: 0, audited: 0, errored: 0, skipped: {}, max, toggles: { candidates: 0, probed: 0, skipped: {} } };
+    const skip = (reason, example) => {
+      const s = (coverage.skipped[reason] ??= { count: 0, examples: [] });
+      s.count++;
+      if (example && s.examples.length < MAX_SKIP_EXAMPLES) s.examples.push(example);
+    };
+
+    // Scroll the page end to end: entrances, long frames, content that stays invisible.
+    const scrollOnce = async () => { const r = await page.evaluate(scrollPass, SCROLL_OPTIONS); return { ...r, long: longFramesBetween(r.loaf, 0, Infinity, unattributedLimit(page)) }; };
+    let scroll = await scrollOnce();
+    if (scroll.long.length) {
+      const later = [];
+      for (let i = 1; i < CONFIRM_RUNS; i++) later.push(await scrollOnce());
+      if (1 + later.filter((r) => r.long.length).length < CONFIRM_MAJORITY) scroll = { ...scroll, long: [] };
+    }
+    const hiddenNormally = new Set(await page.evaluate(invisibleContent));
+
+    // Controls.
+    const controlsLoad = await load(page, url, loadOptions);
+    const findHandles = async () => (o.only?.length ? (await Promise.all(o.only.map(async (s) => {
+      try { return await page.$$(s); } catch (e) { throw new UsageError(`--only "${s}" is not a valid selector: ${e.message.split('\n')[0]}`); }
+    }))).flat() : page.$$(INTERACTIVE));
+    const handles = await findHandles();
+    coverage.candidates = handles.length;
+    const elements = [];
+    const targets = [];
+    const labels = new Map();
+    const seenPaths = new Set();
+    let navigated = false;
+    for (const h of handles) {
+      if (navigated) { skip('page navigated during the audit'); continue; }
+      if (elements.length >= max) { skip(`beyond --max ${max}`); continue; }
+      let label;
+      try {
+        const reach = await h.evaluate(reachability);
+        label = await h.evaluate(describeElement);
+        if (reach.state === 'skip') { skip(reach.reason, label); continue; }
+        const path = await h.evaluate(cssPath);
+        if (seenPaths.has(path)) { coverage.candidates--; continue; }
+        seenPaths.add(path);
+        const n = (labels.get(label) ?? 0) + 1;
+        labels.set(label, n);
+        const unique = n > 1 ? `${label} (${n})` : label;
+        const result = await auditElement(ctx, h, unique, { hoverOnly: reach.state === 'hover-only' });
+        if (result.skipped) { skip(result.skipped, label); continue; }
+        const { el } = result;
+        const later = await confirm(el, elementAspects(el), async () => {
+          const again = await auditElement(ctx, h, unique, { hoverOnly: reach.state === 'hover-only' });
+          return again.el ?? null;
+        });
+        el.undecided = undecidedOf(el, later);
+        dropUnconfirmed(el);
+        el.path = path;
+        el.real = el.pressMode === 'real';
+        elements.push(el);
+        targets.push({ path, real: el.real, label });
+        if (o.interact && !sameLocation(page.url(), landed)) {
+          navigated = true;
+          notes.push(`interacting with ${label} navigated to ${page.url()}: audit stopped there; the controls after it were not audited`);
+          await load(page, url, loadOptions);
+        }
+      } catch (e) {
+        if (o.interact && /context was destroyed|navigat/i.test(e.message)) await page.waitForTimeout(400);
+        if (o.interact && !sameLocation(page.url(), landed)) {
+          // A gesture navigated (a link that routes on mousedown): not an error of the control.
+          navigated = true;
+          notes.push(`interacting with ${label ?? 'a control'} navigated to ${page.url()}: audit stopped there; the controls after it were not audited`);
+          skip('page navigated during the audit');
+          await load(page, url, loadOptions);
+          continue;
+        }
+        coverage.errored++;
+        skip('error', `${label ?? 'element'}: ${e.message.split('\n')[0].slice(0, 90)}`);
+      }
+    }
+    coverage.audited = elements.length;
+
+    // Controls that arrive later than the first count are not covered: say so instead of reporting "N of N".
+    {
+      const age = Date.now() - controlsLoad.loadedAt;
+      if (!navigated && age < RECOUNT_AFTER_MS) await page.waitForTimeout(RECOUNT_AFTER_MS - age);
+      const now = navigated ? handles.length : (await findHandles()).length;
+      coverage.late = Math.max(0, now - handles.length);
+      if (coverage.late) notes.push(`${coverage.late} controls appeared after the audit counted ${handles.length}: the page renders late, so the audit is incomplete. Re-run with --wait-for <selector of a late control>`);
+    }
+
+    const css = await page.evaluate(ungatedHoverMotion);
+    const reducedRule = await page.evaluate(hasReducedMotionRule);
+
+    // Toggles are clicked for real, so only with --interact.
+    const toggles = [];
+    if (o.interact && !navigated) {
+      await load(page, url, loadOptions);
+      const { eligible, skipped } = await eligibleToggles(page);
+      coverage.toggles.candidates = eligible.length + skipped.length;
+      for (const s of skipped) coverage.toggles.skipped[s.reason] = (coverage.toggles.skipped[s.reason] ?? 0) + 1;
+      for (const index of eligible.slice(0, MAX_TOGGLES)) {
+        let r = await probeToggle(ctx, index);
+        if (!r.label) continue;
+        if (r.jumps.length) {
+          const again = [await probeToggle(ctx, index), await probeToggle(ctx, index)];
+          r = confirmToggle(r, again);
+        }
+        coverage.toggles.probed++;
+        toggles.push(r);
+        if (r.jumps.length) {
+          const top = [...new Map(r.jumps.map((j) => [j.label, j])).values()].slice(0, 3).map((j) => `${j.label} ${j.prop} ${j.from} -> ${j.to} in one frame (${j.direction}, ${j.delta})`).join('; ');
+          add('not-interruptible', r.label, `reversed part-way through its ${r.dur} ms motion the animation restarts instead of continuing: ${top}`, 'toggle');
+        }
+        const undecided = toggleRow(r);
+        if (undecided) raw.push(undecided);
+        if (!sameLocation(page.url(), landed)) { notes.push(`toggling ${r.label} navigated to ${page.url()}: toggle probing stopped`); break; }
+      }
+      if (eligible.length > MAX_TOGGLES) coverage.toggles.skipped[`beyond ${MAX_TOGGLES} toggles`] = eligible.length - MAX_TOGGLES;
+    } else coverage.toggles.skipped['observe-only (use --interact)'] = (coverage.toggles.candidates = (await page.$$(TOGGLE)).length);
+
+    // --click <selector>
+    let click = null;
+    if (o.click) {
+      const measure = clickMeasurer(ctx, o.click, o.interrupt);
+      let r = await measure();
+      if (r.missing) { add('click-target', o.click, `${o.click} ${r.missing}`, 'target'); await measure.restore(); }
+      else {
+        const label = `click ${o.click}`;
+        const holder = { long: r.long, jumps: r.jumps, interrupt: r.interrupt };
+        const reruns = [];
+        const later = await confirm(holder, { long: (x) => x.long.length > 0, jump: (x) => x.jumps.length > 0, interrupt: (x) => x.interrupt.length > 0 }, clickRerun(measure, reruns));
+        const undecidedRows = clickRows(label, r, holder.unconfirmed ?? [], reruns);
+        for (const name of holder.unconfirmed ?? []) r = { ...r, [name === 'jump' ? 'jumps' : name]: [] };
+        // Back to the state the target started in when the presses ended odd (a retry is one press).
+        const restored = await measure.restore();
+        click = { selector: o.click, moved: r.moved.length, mounted: r.mounted, cadence: r.cadence, long: r.long, interrupt: r.interrupt, presses: measure.presses(), remeasures: later.length, restored };
+        raw.push(...undecidedRows);
+        if (r.jumps.length) add('jump', label, `${r.jumps.slice(0, 4).map((j) => `${j.label} ${j.prop} jumps ${j.size} at ${j.atMs} ms`).join('; ')}${r.jumps.length > 4 ? ` (+${r.jumps.length - 4} more)` : ''}`, 'click');
+        for (const l of r.layout) add('layout-animated', label, `${l.label} animates its ${l.prop === 'layoutWidth' ? 'width' : 'height'} over ${l.durationMs} ms`, `${l.label} ${l.prop}`);
+        if (r.long.length) add('long-frame', label, `during the transition: ${describeLongFrames(r.long)}`, 'click');
+        if (r.interrupt.length) add('interrupt-jump', label, `second click: ${r.interrupt.slice(0, 4).map((j) => `${j.label} ${j.prop}`).join(', ')} jump`, 'click');
+      }
+    }
+
+    const sheets = [];
+    for (const s of o.frames ?? []) sheets.push(await contactSheet(ctx, s, out));
+    const reduced = await reducedPass(ctx, targets);
+    for (const el of elements) el.reduced = reduced.per.get(el.path);
+
+    // Frames no application script explains, in many unrelated controls, are the machine's: a page that janks does
+    // so in its own scripts and in the controls that run them. The calibration at the start cannot see a noisy
+    // phase that comes later.
+    const unattributed = (l) => !l.scripts?.length;
+    const noisy = elements.filter((e) => e.long.some(unattributed)).length;
+    if (noisy >= ENV_NOISE_MIN_ELEMENTS) {
+      const environmental = (l) => unattributed(l) && l.duration < NOISY_UNATTRIBUTED_MS;
+      for (const el of elements) el.long = el.long.filter((l) => !environmental(l));
+      scroll = { ...scroll, long: scroll.long.filter((l) => !environmental(l)) };
+      notes.push(`frames over ${LONG_FRAME_MS} ms with no script behind them showed up in ${noisy} unrelated controls: the machine drops frames, so those are not reported as long frames`);
+    }
+    for (const el of elements) raw.push(...judgeElement(el, config));
+    raw.push(...inconsistencies(elements, config));
+    for (const el of elements) {
+      for (const moment of [...new Set(el.long.map((l) => l.moment))]) add('long-frame', el.label, `during ${moment}: ${describeLongFrames(el.long.filter((l) => l.moment === moment))}`, moment);
+    }
+    if (scroll.long.length) add('long-frame', 'page scroll', `while scrolling${o.cpu > 1 ? ` (CPU ${o.cpu}x)` : ''}: ${describeLongFrames(scroll.long)}`, 'scroll');
+    if (scroll.keyframeLayout.length) add('layout-animated', 'keyframes', `CSS/WAAPI animations animate ${scroll.keyframeLayout.join(', ')}`, 'keyframes');
+    if (o.entrances) for (const s of scroll.sections.filter((x) => !x.animated)) add('no-entrance', `section "${s.section}"`, 'appears without an entrance the first time it is scrolled to', 'entrance');
+    for (const sel of css.found) add('ungated-hover', sel, 'moves on :hover outside @media (hover: hover): sticks after a tap on touch screens', 'ungated');
+    if (reduced.infinite.length) add('reduced-motion-loop', reduced.infinite.slice(0, 4).join(', '), 'infinite moving animation keeps running with prefers-reduced-motion', 'loop');
+    const stranded = reduced.hidden.filter((h) => !hiddenNormally.has(h)).slice(0, 6);
+    if (stranded.length) add('reduced-motion-hidden', stranded.join(', '), 'content stays at opacity 0 with prefers-reduced-motion: the entrance it waits for never runs', 'hidden');
+    const anyMotion = elements.some((e) => Object.values(e.moments).some((d) => d?.motion.some((m) => m.moves.some((x) => x.prop !== 'opacity'))));
+    const unreadable = Math.max(css.unreadable, reducedRule.unreadable);
+    if (anyMotion && !reducedRule.found) {
+      raw.push({ kind: 'reduced-motion-missing', element: 'stylesheets', key: 'rules', level: unreadable ? 'info' : undefined, detail: unreadable ? `unknown: ${unreadable} stylesheet(s) could not be read (cross-origin or file://), so a reduced-motion rule may exist there` : 'elements move but no stylesheet has a prefers-reduced-motion rule (JS-driven handling is not seen here)' });
+    }
+
+    const done = finalize(raw, config, { devServer: devServer.length > 0 });
+    coverage.inconclusive = done.findings.filter((f) => f.kind === 'inconclusive').length;
+    const baselined = done.findings.filter((f) => baseline.has(f.id));
+    const findings = done.findings.filter((f) => !baseline.has(f.id));
+    const report = {
+      schemaVersion: SCHEMA_VERSION,
+      url,
+      finalUrl: landed,
+      cpu: o.cpu ?? 1,
+      mode: o.interact ? 'interact' : 'observe-only',
+      loafSupported,
+      devServer,
+      cssUnreadable: unreadable,
+      coverage,
+      notes,
+      elements: elements.map(({ label, kind, transition, moments, interrupt, reduced: red, pressMode, hoverOnly }) => ({ label, kind, pressMode, hoverOnly, transition, moments: Object.fromEntries(Object.entries(moments).map(([k, d]) => [k, { changed: d.changed, pixels: d.pixels, transition: d.transition, cadence: d.cadence, motion: d.motion }])), interrupt, reduced: red })),
+      sections: scroll.sections,
+      toggles,
+      click,
+      sheets: sheets.filter(Boolean),
+      findings,
+      baselined,
+      suppressed: done.suppressed,
+    };
+    writeFileSync(join(out, 'report.json'), JSON.stringify(report, null, 1));
+    return { ...report, out };
+  } finally {
+    await pixels?.close();
+    if (browser) await browser.close();
+    else {
+      await pseudo?.detach();
+      // The page belongs to the caller: leave it as it was found.
+      if (throttle) {
+        await throttle.send('Emulation.setCPUThrottlingRate', { rate: 1 }).catch(() => {});
+        await throttle.detach().catch(() => {});
+      }
+      await initScript?.dispose().catch(() => {});
+      await page.evaluate(() => window.__mt?.dispose?.()).catch(() => {});
+    }
+  }
+};
+
+// 0 clean, 1 findings that fail, 2 the audit did not cover enough to mean anything.
+export const exitCode = (report, { strict = false, minCoverage } = {}) => {
+  const { candidates, audited } = report.coverage;
+  if (audited === 0 || report.coverage.late > 0) return 2;
+  if (minCoverage !== undefined && audited / candidates < minCoverage) return 2;
+  return report.findings.some((f) => f.kind !== 'inconclusive' && (f.level === 'error' || (strict && f.level === 'warning'))) ? 1 : 0;
+};

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

@@ -0,0 +1,240 @@
+// Helpers that drive the page: tracing a gesture, snapshots, forced pseudo-states over CDP,
+// navigation with redirect checks.
+import { CALIBRATION_CYCLES, CLIP_MARGIN_PX, IDLE_NOISE_MS, VIEWPORT, HYDRATION_WAIT_MS, LOGIN_PATH, LONG_FRAME_MS, NAV_TIMEOUT_MS, PAGE_SCRIPT_MIN_MS, PIXEL_BLOCK_PX, PIXEL_CHANNEL_TOLERANCE, PIXEL_MIN_BLOCKS, RELOAD_WAIT_MS, SETTLE_MAX_MS, TRACE_MIN_SIZE_PX, TRACE_MOUNT_CAP, TRACE_PAGE_CAP, TRACE_SUBTREE_CAP, WAIT_FOR_TIMEOUT_MS } from './constants.mjs';
+import { COLS, analyzeRecording } from './series.mjs';
+
+export class AuditError extends Error {}
+
+export const TRACER_CONFIG = { cols: COLS, skip: ['SCRIPT', 'STYLE', 'LINK', 'META', 'NOSCRIPT', 'BR', 'TEMPLATE'], subtreeCap: TRACE_SUBTREE_CAP, pageCap: TRACE_PAGE_CAP, mountCap: TRACE_MOUNT_CAP, minSize: TRACE_MIN_SIZE_PX };
+
+export const snapshot = (h, props) => h.evaluate((n, p) => { const cs = getComputedStyle(n); return Object.fromEntries(p.map((x) => [x, cs.getPropertyValue(x)])); }, props);
+export const diff = (a, b) => Object.keys(a).filter((k) => a[k] !== b[k]);
+export const shot = async (page, box) => (await page.screenshot({ clip: { x: Math.max(0, box.x - CLIP_MARGIN_PX), y: Math.max(0, box.y - CLIP_MARGIN_PX), width: box.width + 2 * CLIP_MARGIN_PX, height: box.height + 2 * CLIP_MARGIN_PX } })).toString('base64');
+export const toMs = (list) => String(list).split(',').map((s) => s.trim()).map((s) => (s.endsWith('ms') ? parseFloat(s) : parseFloat(s) * 1000));
+
+// Records one gesture: the tracer follows `root` and its subtree while `action` runs.
+export const traced = async (page, root, action) => {
+  await root.evaluate((n) => window.__mt.begin('m', n));
+  const from = await page.evaluate(() => window.__mt.now());
+  await action();
+  const rec = await page.evaluate(() => window.__mt.end('m'));
+  const to = await page.evaluate(() => window.__mt.now());
+  const loaf = await page.evaluate(() => window.__mt.loaf);
+  return { rec, motion: analyzeRecording(rec, { longFrames: longWindows(loaf, from, unattributedLimit(page)) }), long: longFramesBetween(loaf, from, to, unattributedLimit(page)) };
+};
+
+// How long a frame with no application script must be to count: LONG_FRAME_MS, or more on a machine
+// whose frames are slow with nothing to do (see calibrateFrames).
+const limits = new WeakMap();
+export const setUnattributedLimit = (page, ms) => limits.set(page, ms);
+export const unattributedLimit = (page) => limits.get(page) ?? LONG_FRAME_MS;
+
+// An auxiliary page next to the audited one. A page from `browser.newPage()` owns its context, which refuses
+// further pages: the auxiliary page then lives in a context of its own (with the page's session when `session`)
+// that closes with it.
+export const auxPage = async (context, { session = false } = {}) => {
+  try {
+    return await context.newPage();
+  } catch (e) {
+    const browser = context.browser();
+    if (!browser || !/browser.newContext()/.test(String(e?.message))) throw e;
+    const own = await browser.newContext({ viewport: VIEWPORT, deviceScaleFactor: 1, ...(session ? { storageState: await context.storageState() } : {}) });
+    const page = await own.newPage();
+    const close = page.close.bind(page);
+    page.close = async (options) => { await close(options).catch(() => {}); await own.close().catch(() => {}); };
+    return page;
+  }
+};
+
+// The longest frame of the audited page while nothing touches it (ambient animations, a busy
+// machine): a frame at least that long during a gesture says nothing about the gesture.
+export const idleFrameNoise = async (page, ms = IDLE_NOISE_MS) => {
+  const from = await page.evaluate(() => window.__mt.now());
+  await page.waitForTimeout(ms);
+  const loaf = await page.evaluate(() => window.__mt.loaf);
+  return Math.max(0, ...loaf.filter(([s, d]) => s + d >= from).map(([, d]) => d));
+};
+
+// Measures the frames of a blank page doing what the audit does (hover, leave, screenshot): the
+// longest one is the noise of this machine. Returns 0 where Long Animation Frames are unsupported.
+export const calibrateFrames = async (context) => {
+  const page = await auxPage(context);
+  try {
+    await page.setViewportSize(VIEWPORT);
+    await page.setContent('<body style="margin:0"><style>button{margin:40px;padding:8px 14px;transition:background-color 140ms}button:hover{background:#ddd}</style><button id="b">Probe</button>' + '<p>text</p>'.repeat(200) + '</body>');
+    await page.evaluate(() => {
+      window.__noise = [];
+      if (PerformanceObserver.supportedEntryTypes?.includes('long-animation-frame')) new PerformanceObserver((l) => { for (const e of l.getEntries()) window.__noise.push(e.duration); }).observe({ type: 'long-animation-frame', buffered: true });
+    });
+    const box = await (await page.$('#b')).boundingBox();
+    const clip = { x: box.x - 6, y: box.y - 6, width: box.width + 12, height: box.height + 12 };
+    for (let i = 0; i < CALIBRATION_CYCLES; i++) {
+      await page.mouse.move(box.x + 5, box.y + 5);
+      await page.waitForTimeout(150);
+      await page.screenshot({ clip });
+      await page.mouse.move(1, 1);
+      await page.waitForTimeout(150);
+    }
+    return Math.max(0, ...(await page.evaluate(() => window.__noise)));
+  } catch {
+    return 0;
+  } finally {
+    await page.close().catch(() => {});
+  }
+};
+
+// The part of a frame's time that is the audit's own work: scripts with no source URL (the tracer's
+// frame callback, page.evaluate) minus the style and layout they forced, which the page's own
+// changes made necessary.
+const auditWork = (scripts) => scripts.filter((s) => !s.url).reduce((sum, s) => sum + Math.max(0, s.duration - (s.forced ?? 0)), 0);
+
+// Long frames (over LONG_FRAME_MS) in [from, to] that are the page's: what is left of a frame once
+// the audit's own script time is taken out. Frames with no script at all (style, layout, paint) count
+// when they are over `unattributedMs`, and so do frames whose page scripts are short (PAGE_SCRIPT_MIN_MS).
+const pageScripts = (scripts) => scripts.filter((x) => x.url).reduce((sum, x) => sum + x.duration, 0);
+const pageOwned = (d, scripts, unattributedMs) => d - auditWork(scripts) > (pageScripts(scripts) >= PAGE_SCRIPT_MIN_MS ? LONG_FRAME_MS : unattributedMs);
+export const longFramesBetween = (loaf, from, to = Infinity, unattributedMs = LONG_FRAME_MS) => loaf
+  .filter(([s, d, scripts]) => s + d >= from && s <= to && pageOwned(d, scripts ?? [], unattributedMs))
+  .map(([, d, scripts]) => ({ duration: Math.round(d), scripts: (scripts ?? []).filter((x) => x.url) }));
+
+// [[start, duration]] of the page's long frames (the ones longFramesBetween reports) that end after `from`:
+// a step in one of them is that frame. A frame no longer than the machine's own noise explains nothing.
+export const longWindows = (loaf, from, unattributedMs = LONG_FRAME_MS) => loaf
+  .filter(([s, d, scripts]) => s + d >= from && pageOwned(d, scripts ?? [], unattributedMs))
+  .map(([s, d]) => [s, d]);
+
+// Which scripts a long frame is attributed to, from the LoAF `scripts[]`.
+export const describeLong = (long) => {
+  const frames = long.map((l) => l.duration);
+  const byUrl = new Map();
+  for (const l of long) for (const s of l.scripts ?? []) {
+    const name = s.url ? s.url.replace(/^.*\//, '').replace(/\?.*$/, '') || s.url : '(inline or injected script)';
+    byUrl.set(name, (byUrl.get(name) ?? 0) + s.duration);
+  }
+  const top = [...byUrl.entries()].sort((a, b) => b[1] - a[1]).slice(0, 2).map(([n, d]) => `${n} ${d} ms`);
+  return { frames, culprit: top.length ? `scripts: ${top.join(', ')}` : 'no script attributed (style, layout or paint)' };
+};
+
+// Forces CSS pseudo-classes on an element through the DevTools protocol: no pointer or focus
+// event is dispatched, so nothing in the app reacts.
+export const createPseudoStates = async (context, page) => {
+  const session = await context.newCDPSession(page);
+  await session.send('DOM.enable');
+  await session.send('CSS.enable');
+  const nodeId = async (handle, up = 0) => {
+    await handle.evaluate((n, levels) => { let e = n; for (let i = 0; i < levels && e.parentElement; i++) e = e.parentElement; window.__maTarget = e; }, up);
+    const { result } = await session.send('Runtime.evaluate', { expression: 'window.__maTarget' });
+    await handle.evaluate(() => { delete window.__maTarget; });
+    return (await session.send('DOM.requestNode', { objectId: result.objectId })).nodeId;
+  };
+  return {
+    async force(handle, states, ancestors = {}) {
+      // Node ids are only valid until the next getDocument, so it is called once, before resolving any.
+      await session.send('DOM.getDocument', { depth: 0 });
+      const ids = [{ id: await nodeId(handle), states }];
+      for (const [up, st] of Object.entries(ancestors)) ids.push({ id: await nodeId(handle, Number(up)), states: st });
+      for (const { id, states: s } of ids) await session.send('CSS.forcePseudoState', { nodeId: id, forcedPseudoClasses: s });
+      return ids;
+    },
+    async clear(ids) { for (const { id } of ids) await session.send('CSS.forcePseudoState', { nodeId: id, forcedPseudoClasses: [] }); },
+    detach: () => session.detach().catch(() => {}),
+    session,
+  };
+};
+
+const sameDocument = (a, b) => {
+  const x = new URL(a);
+  const y = new URL(b);
+  return x.origin === y.origin && x.pathname.replace(/\/$/, '') === y.pathname.replace(/\/$/, '') && x.search === y.search;
+};
+export const sameLocation = sameDocument;
+
+const loadedUrls = new WeakMap();
+
+// Loads `url` fresh (never reload: a probe may have navigated) and checks where it landed: after
+// the load, after --wait-for and after the hydration wait, because a session check or a router
+// redirects from script, after the response.
+export const load = async (page, url, { waitFor, allowRedirect = false } = {}) => {
+  const response = await page.goto(url, { waitUntil: 'load', timeout: NAV_TIMEOUT_MS });
+  if (response && response.status() >= 400) throw new AuditError(`${url} answered HTTP ${response.status()}`);
+  const verify = () => {
+    const landed = page.url();
+    if (sameDocument(url, landed)) return landed;
+    const requested = new URL(url);
+    const final = new URL(landed);
+    if (LOGIN_PATH.test(final.pathname + final.search) && !LOGIN_PATH.test(requested.pathname)) {
+      throw new AuditError(`${url} redirected to ${landed}: that is a login page, not the page to audit. Pass --storage-state <file> with a logged-in session`);
+    }
+    if (!allowRedirect) throw new AuditError(`${url} redirected to ${landed}: the page audited is not the one requested. Audit that URL, or pass --allow-redirect to audit where it lands`);
+    return landed;
+  };
+  verify();
+  if (waitFor) {
+    try { await page.waitForSelector(waitFor, { state: 'visible', timeout: WAIT_FOR_TIMEOUT_MS }); } catch (e) {
+      throw new AuditError(`--wait-for "${waitFor}" did not appear within ${WAIT_FOR_TIMEOUT_MS / 1000} s on ${page.url()}: ${e.message.split('\n')[0]}`);
+    }
+  }
+  // The first load of a URL gets the full hydration wait; the probes' reloads of it a short one,
+  // then until its own entrance animations have finished.
+  const reload = loadedUrls.get(page)?.has(url);
+  await page.waitForTimeout(reload ? RELOAD_WAIT_MS : HYDRATION_WAIT_MS);
+  await page.evaluate((cap) => new Promise((resolve) => {
+    const end = performance.now() + cap;
+    const check = () => (document.getAnimations().some((a) => a.playState === 'running' && Number.isFinite(a.effect?.getComputedTiming().endTime)) && performance.now() < end ? setTimeout(check, 50) : resolve());
+    check();
+  }), SETTLE_MAX_MS).catch(() => {});
+  if (!loadedUrls.has(page)) loadedUrls.set(page, new Set());
+  loadedUrls.get(page).add(url);
+  const landed = verify();
+  return { landed, redirected: !sameDocument(url, landed), loadedAt: Date.now() };
+};
+
+// Compares two screenshots (base64 PNG) the way an eye does: the share of pixels that differ by more
+// than PIXEL_CHANNEL_TOLERANCE in some channel. Anti-aliasing and compositing noise stay below it.
+// Decoding happens in a blank page of the same context, away from the page under audit.
+export const createPixelComparer = async (context) => {
+  const page = await auxPage(context);
+  const stats = (a, b, tolerance) => page.evaluate(async ([x, y, tol, block]) => {
+    const decode = async (b64) => {
+      const bin = atob(b64);
+      const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0));
+      const bmp = await createImageBitmap(new Blob([bytes], { type: 'image/png' }));
+      const ctx = new OffscreenCanvas(bmp.width, bmp.height).getContext('2d');
+      ctx.drawImage(bmp, 0, 0);
+      return ctx.getImageData(0, 0, bmp.width, bmp.height);
+    };
+    const [p, q] = await Promise.all([decode(x), decode(y)]);
+    const bw = Math.ceil(p.width / block);
+    const bh = Math.ceil(p.height / block);
+    if (p.width !== q.width || p.height !== q.height) return { changed: bw * bh, total: bw * bh, max: 255 };
+    let changed = 0;
+    let max = 0;
+    for (let by = 0; by < bh; by++) {
+      for (let bx = 0; bx < bw; bx++) {
+        const sum = [0, 0, 0, 0, 0, 0, 0, 0];
+        let n = 0;
+        for (let y = by * block; y < Math.min(p.height, (by + 1) * block); y++) {
+          for (let x = bx * block; x < Math.min(p.width, (bx + 1) * block); x++) {
+            const i = (y * p.width + x) * 4;
+            for (let c = 0; c < 4; c++) { sum[c] += p.data[i + c]; sum[c + 4] += q.data[i + c]; }
+            n++;
+          }
+        }
+        const d = Math.max(...[0, 1, 2, 3].map((c) => Math.abs(sum[c] - sum[c + 4]) / n));
+        if (d > tol) changed++;
+        if (d > max) max = d;
+      }
+    }
+    return { changed, total: bw * bh, max: Math.round(max) };
+  }, [a, b, tolerance, PIXEL_BLOCK_PX]);
+  return {
+    stats: (a, b, tolerance = PIXEL_CHANNEL_TOLERANCE) => (a === b ? Promise.resolve({ changed: 0, total: 1, max: 0 }) : stats(a, b, tolerance)),
+    // Whether the two screenshots show a visible difference.
+    async differ(a, b) {
+      if (a === b) return false;
+      const { changed } = await stats(a, b, PIXEL_CHANNEL_TOLERANCE);
+      return changed >= PIXEL_MIN_BLOCKS;
+    },
+    close: () => page.close().catch(() => {}),
+  };
+};

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

@@ -0,0 +1,71 @@
+// Command-line entry: argument handling, output, exit codes.
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { USAGE, UsageError, parseArgs } from './args.mjs';
+import { audit, exitCode } from './audit.mjs';
+import { compareReports, readReport } from './compare.mjs';
+import { ConfigError } from './config.mjs';
+import { AuditError } from './browser.mjs';
+import { DEFAULT_MAX_ELEMENTS } from './constants.mjs';
+
+const toUrl = (target) => (/^[a-z][a-z0-9+.-]*:\/\//i.test(target) ? target : existsSync(target) ? pathToFileURL(resolve(target)).href : target);
+
+const summary = (r) => {
+  const n = (m) => r.elements.filter((e) => e.moments[m]?.changed.length || e.moments[m]?.pixels).length;
+  const c = r.coverage;
+  const skipped = Object.entries(c.skipped).map(([reason, s]) => `${s.count} ${reason}`);
+  const lines = [`audited ${c.audited} of ${c.candidates} controls${skipped.length ? ` (not audited: ${skipped.join(', ')})` : ''} · mode ${r.mode}`];
+  lines.push(`respond on hover ${n('hover')} · press ${n('press')} · focus ${n('focus')} · sections with entrance ${r.sections.filter((s) => s.animated).length}/${r.sections.length}${r.loafSupported ? '' : ' · long frames: not supported by this browser'}${r.cssUnreadable ? ` · ${r.cssUnreadable} stylesheets not read` : ''}`);
+  if (c.inconclusive) lines.push(`inconclusive: ${c.inconclusive} check(s) could not be decided because frames were too sparse; rerun on a quieter machine, without --cpu`);
+  const t = c.toggles;
+  const togglesSkipped = Object.entries(t.skipped).filter(([, v]) => v > 0);
+  lines.push(`toggles: ${t.probed} probed of ${t.candidates}${togglesSkipped.length ? ` (not probed: ${togglesSkipped.map(([k, v]) => `${v} ${k}`).join(', ')})` : ''}`);
+  for (const [reason, s] of Object.entries(c.skipped)) if (s.examples.length) lines.push(`  NOT RUN ${reason}: ${s.examples.join('; ')}`);
+  for (const note of r.notes) lines.push(`note: ${note}`);
+  return lines;
+};
+
+const printText = (r, code, opts) => {
+  for (const line of summary(r)) console.log(line);
+  for (const f of r.findings) console.log(`${f.level.padEnd(7)} ${f.kind}${f.check ? ` (${f.check})` : ''}: ${f.element}: ${f.detail} [${f.id}]`);
+  if (r.baselined.length) console.log(`${r.baselined.length} finding(s) already in the baseline`);
+  for (const s of r.suppressed) console.log(`suppressed ${s.kind}: ${s.element} [${s.id}]: ${s.reason}`);
+  if (r.sheets.length) console.log(`contact sheets: ${r.sheets.join(', ')}`);
+  console.log(`report: ${join(r.out, 'report.json')}`);
+  const failing = r.findings.filter((f) => f.kind !== 'inconclusive' && (f.level === 'error' || (opts.strict && f.level === 'warning')));
+  if (r.coverage.audited === 0) console.log('NOT AUDITED: no control was audited, so there is no result (exit 2)');
+  else if (r.coverage.late > 0) console.log(`INCOMPLETE: ${r.coverage.late} controls appeared after the audit started, so they were not audited; re-run with --wait-for <selector> (exit 2)`);
+  else if (code === 2) console.log(`coverage ${r.coverage.audited}/${r.coverage.candidates} is below --min-coverage ${opts.minCoverage} (exit 2)`);
+  else console.log(failing.length ? `${failing.length} to fix, or suppress in the config with a reason (${r.findings.length - failing.length} others do not fail)` : `clean: ${r.findings.length} non-failing finding(s)`);
+};
+
+const runCompare = (argv) => {
+  if (argv.length !== 2) throw new UsageError('compare needs <ref.json> <mine.json>');
+  const c = compareReports(readReport(argv[0]), readReport(argv[1]));
+  for (const l of c.lines) console.log(l);
+  for (const f of c.added) console.log(`new in mine: ${f.kind}: ${f.element} [${f.id}]`);
+  for (const f of c.gone) console.log(`gone from mine: ${f.kind}: ${f.element} [${f.id}]`);
+  console.log(`${c.differ} of ${c.total} differ`);
+  return 0;
+};
+
+// Returns the exit code.
+export const main = async (argv) => {
+  try {
+    if (argv[0] === 'compare') return runCompare(argv.slice(1));
+    const { opts, positional } = parseArgs(argv);
+    if (opts.help) { console.log(USAGE); return 0; }
+    if (positional.length !== 1) throw new UsageError(positional.length ? `expected one url or file, got ${positional.length}` : 'missing <url|file> (see --help)');
+    const report = await audit(toUrl(positional[0]), { ...opts, max: opts.max ?? DEFAULT_MAX_ELEMENTS });
+    const code = exitCode(report, { strict: opts.strict, minCoverage: opts.minCoverage });
+    if (opts.json) console.log(JSON.stringify(report, null, 1));
+    else printText(report, code, opts);
+    return code;
+  } catch (e) {
+    if (e instanceof UsageError) { console.error(`${e.message}\n\n${USAGE}`); return 2; }
+    if (e instanceof ConfigError || e instanceof AuditError) { console.error(`could not run: ${e.message}`); return 2; }
+    console.error(`could not run: ${e.stack ?? e.message}`);
+    return 2;
+  }
+};