motion-audit 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 1.0.0
+
+First release as an installable plugin and as the npm package `motion-audit`. The package ships the
+`skills/motion-audit` directory (CLI, library and skill together); `bin` and `exports` point inside it.
+
+- Skill `motion-audit` and CLI `motion-audit`: per-frame measurement of hover, press and keyboard focus,
+  click transitions, interruption, scroll, long frames and reduced motion in Chromium.
+- Observe-only by default (real hover, `:active` and `:focus-visible` forced over CDP); `--interact`
+  adds real presses and toggle probes behind a denylist, with a fresh page load between probes, an even
+  number of clicks per toggle and a stop when a gesture navigates.
+- Coverage contract: `audited N of M`, skips with reasons, exit 2 when nothing was audited,
+  `--min-coverage`.
+- The tracer follows nodes mounted during a recording (portals, conditionally rendered overlays);
+  Animation-object restart detection; interruption analysis normalised by time; flaky kinds kept only
+  when two of three runs agree.
+- Config file with bands, duration tokens, per-kind severity and ignores, all requiring a reason;
+  default profile where `no-entrance` is info and opt-in and missing press or hover on links and inputs
+  is never an error.
+- `audit(pageOrUrl, options)` accepts a Playwright `page`; `--storage-state`, `--wait-for`, redirect
+  detection, hit-testing, inner scroll containers, hidden-until-hover controls, development-build
+  detection, long-frame attribution from LoAF scripts.
+- JSON report `schemaVersion: 1` with coverage and `loafSupported`; stable `kind:hash` finding ids,
+  `--baseline`, `compare <ref.json> <mine.json>`.
+- Argument validation (`--help` exits 0, unknown options and invalid numbers exit 2); Playwright is
+  resolved from `PLAYWRIGHT_ROOT`, then the working directory, with real load errors surfaced and a 1.59
+  minimum; reports go to a temp directory unless `--out` is given.
+- Packaging: Claude Code plugin and marketplace manifests, `references/fixes.md`, trigger evals, unit and
+  fixture tests, CI on Linux, Windows and macOS.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nahuel Mosse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# motion-audit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A CLI, a library and a Claude Code skill that measure how a running web UI moves, in a real Chromium: which
+controls give no hover, press or keyboard-focus feedback, which transitions snap or jank, long frames,
+ease-in curves and off-band durations, animations that jump or restart when interrupted, and
+`prefers-reduced-motion` that is missing or broken. It records the element and its children on every
+animation frame instead of trusting what the CSS declares.
+
+It is **observe-only by default**: it hovers, forces `:active` and `:focus-visible` over the DevTools
+protocol, scrolls and reads. It never clicks unless you pass `--interact` (or name a control with
+`--click`), so it cannot toggle a Follow button or submit a form, and no focus, key or press handler
+runs. The pointer and the scroll are real, though: handlers bound to hover (`mouseenter`, `mouseover`,
+`pointerenter` that send a beacon or write storage), scroll-bound `IntersectionObserver` callbacks and
+`beforeunload` beacons run. Audit a throwaway or staging environment, never one where those events
+are billed or irreversible.
+
+## Install and run
+
+Node 22.12+ and Playwright 1.59+ with Chromium in the project you audit.
+
+```bash
+npm i -D motion-audit playwright
+npx playwright install chromium
+npx motion-audit http://localhost:3000/orders
+npx motion-audit http://localhost:3000/orders --cpu 4 --click '[aria-controls=filters]' --interrupt
+npx motion-audit compare ref.json mine.json
+```
+
+Exit `0` clean, `1` findings, `2` could not run or audited nothing. Audit a production build
+(`next start`, `vite preview`): on a dev server long frames are downgraded to warnings.
+
+| Option | Meaning |
+|---|---|
+| `--only <sel>` | audit only matching controls (repeatable) |
+| `--max <n>` | audit at most n controls, default 40; the summary says `audited N of M` |
+| `--min-coverage <0-1>` | exit 2 when audited / candidates is lower; controls beyond `--max` count as not audited, so raise `--max` too |
+| `--interact` | real press and toggle probes; a denylist skips submit and reset controls, unnamed buttons, every link that is not `#` or an `#id` on the page, destructive wording in six languages, drag and slider controls |
+| `--click <sel>` `--interrupt` | record a real click (and a second one half-way); clicks the target twice, four times with `--interrupt`, and at most eight times (sixteen) when sparse frames or a flaky finding force a re-measure (a retry adds one press, and a press's effect has to land within 1.5 s: a request still pending at the next reload is reported in the notes, but one a timer sends later cannot be seen; when the count would end odd without `--interrupt` the target is pressed once more, so the state it keeps ends as it began; with `--interrupt` every recording presses twice and the count is always even): throwaway environments only |
+| `--allow-redirect` | audit the page the URL redirects to; without it any redirect, from the server or from script, exits 2, and a login page always does |
+| `--cpu <rate>` | CPU throttle, 4 is a mid-range phone |
+| `--frames <sel>` | contact sheet of hover and press with real timestamps |
+| `--entrances` | also report sections without an entrance (info) |
+| `--storage-state <file>` | logged-in Playwright storage state; a redirect to a login page exits 2 |
+| `--wait-for <sel>` | wait for a selector before auditing |
+| `--config <file>` | config file, default `./motion-audit.config.json` |
+| `--baseline <report.json>` | ignore findings already in an earlier report |
+| `--out <dir>` | report and sheets; default a fresh temp directory |
+| `--strict` | warnings fail too |
+| `--json` | the report, `schemaVersion: 1`, with coverage, `loafSupported` and finding ids |
+
+## Config
+
+`motion-audit.config.json` in the audited project. Everything that loosens the audit needs a reason:
+
+```json
+{
+  "bands": { "reason": "Carbon micro-interactions run at 70 ms", "hover": [60, 300] },
+  "tokens": { "reason": "design-system duration tokens", "durations": [70, 120, 200] },
+  "severity": {
+    "inconsistent-duration": { "level": "info", "reason": "size-scaled durations are intended" },
+    "duration": "error"
+  },
+  "ignore": [
+    { "kind": "no-feedback", "element": "a \"Skip to content\"*", "reason": "visible only on focus" },
+    { "id": "no-feedback:3f2a9c1d07", "reason": "tracked in the design-system backlog" }
+  ]
+}
+```
+
+`bands` are `[min, max]` ms for `hover`, `press` and `focus`. `severity` levels are `error`, `warning`,
+`info` and `off`; lowering a kind needs the object form with a reason, raising does not. `ignore` takes a
+finding id (`kind:hash`, printed after each finding) or a kind plus an element glob; wildcard-only ids
+and elements are rejected. Defaults: `no-entrance` is info and opt-in, a missing press or hover on links
+and inputs is never an error, durations and consistency are warnings.
+
+## CI
+
+With Playwright Test, in a project that installed this package:
+
+```js
+import { test, expect } from '@playwright/test';
+import { audit } from 'motion-audit';
+
+test('orders: motion', async ({ page }) => {
+  test.setTimeout(240_000);
+  await page.goto('/orders');
+  const report = await audit(page, { only: ['main button', 'nav a'], max: 20 });
+  expect(report.coverage.audited).toBeGreaterThan(0);
+  expect(report.findings.filter((f) => f.level === 'error')).toEqual([]);
+});
+```
+
+`audit(pageOrUrl, options)` takes a Playwright `page` (its `baseURL` and `storageState` apply) or a URL
+(options: `only`, `max`, `cpu`, `click`, `interrupt`, `interact`, `frames`, `entrances`, `config`,
+`baseline`, `storageState`, `waitFor`, `allowRedirect`, `out`). With a `page`, the CPU throttle is
+removed, the CDP session detached and the tracer stopped and unregistered when the audit ends. Or from
+the shell, failing on new findings only:
+
+```bash
+npx motion-audit "$APP_URL/orders" --max 200 --min-coverage 0.8 --baseline motion-baseline.json
+```
+
+## Claude Code skill
+
+The same tool as a skill: Claude measures the page, reads the findings and fixes the CSS. The skill is the
+`skills/motion-audit` directory, self-contained (CLI and library included), so the plugin, `npx skills add
+NahuelMosse/motion-audit` and a copy of that directory all work. Inside the skill, `npx --no-install
+motion-audit` is preferred when the project has the devDependency; otherwise it runs the bundled script.
+
+
+```bash
+claude plugin marketplace add NahuelMosse/motion-audit
+claude plugin install motion-audit@motion-audit
+```
+
+Pin a release by adding the tag to the marketplace source, and update with the plugin commands:
+
+```bash
+claude plugin marketplace add NahuelMosse/motion-audit#v1.0.0
+claude plugin marketplace update motion-audit
+claude plugin update motion-audit@motion-audit
+```
+
+The skill needs the same Node and Playwright. Set `PLAYWRIGHT_ROOT` to a project that has
+it when the audited project does not.
+
+## Develop
+
+```bash
+npm ci
+npx playwright install chromium
+npm run test:unit                         # pure and quick, no browser
+npm run test:browser                      # fixtures, CLI and safety tests in Chromium
+npm test                                  # both
+node test/helpers/fixture-runs.mjs 3      # every fixture three times: identical findings, equal to the golden file
+MA_SHARD=2/6 npm run test:browser         # one slice of the browser tests (CI runs the slices in parallel jobs)
+```
+
+## License
+
+MIT. See [NOTICES.md](NOTICES.md) for credits.

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "motion-audit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Measures how a running web UI moves, frame by frame, in a real browser: missing hover/press/focus feedback, janky or jumping transitions, long frames and broken reduced motion.",
+  "keywords": [
+    "animation",
+    "motion",
+    "microinteractions",
+    "playwright",
+    "reduced-motion",
+    "performance",
+    "jank",
+    "qa",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Nahuel Mosse",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NahuelMosse/motion-audit.git"
+  },
+  "homepage": "https://github.com/NahuelMosse/motion-audit#readme",
+  "bugs": {
+    "url": "https://github.com/NahuelMosse/motion-audit/issues"
+  },
+  "type": "module",
+  "bin": {
+    "motion-audit": "skills/motion-audit/scripts/motion-audit.mjs"
+  },
+  "exports": {
+    ".": "./skills/motion-audit/scripts/lib/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "skills/motion-audit",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "peerDependencies": {
+    "playwright": ">=1.59"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=2 \"test/**/*.test.mjs\"",
+    "test:unit": "node --test test/args.test.mjs test/config.test.mjs test/continuity.test.mjs test/docs.test.mjs test/gates.test.mjs test/press-count.test.mjs test/residuals.test.mjs test/sightings.test.mjs test/judge.test.mjs test/long-frames.test.mjs test/package.test.mjs test/playwright-resolution.test.mjs test/release-plan.test.mjs test/reduced-and-compare.test.mjs test/segments.test.mjs test/series.test.mjs test/skill-doc.test.mjs",
+    "test:browser": "node --test --test-concurrency=1 test/cli.test.mjs test/detection.test.mjs test/fixtures.test.mjs test/package-install.test.mjs test/interact-safety.test.mjs test/readme-example.test.mjs test/redirect.test.mjs",
+    "fixtures": "node test/helpers/fixture-runs.mjs 3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.59",
+    "playwright": "^1.59"
+  }
+}

package/skills/motion-audit/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: motion-audit
+description: Use when the user asks to audit, test or QA the motion, animations or microinteractions of a running page or app, says it feels janky, dead, stutters or jumps, or asks whether reduced motion works. Measures in a real browser what is wrong - no hover, press or focus feedback, snapping or janky transitions, long frames, animations that jump or restart, broken prefers-reduced-motion.
+allowed-tools:
+  - Bash(node ${CLAUDE_SKILL_DIR}/scripts/*)
+  - Bash(node "${CLAUDE_SKILL_DIR}/scripts/*")
+  - Bash(npx --no-install motion-audit *)
+---
+
+# Motion audit
+
+Motion bugs are invisible in code review and in still screenshots: the CSS says `transition: transform
+200ms` and the button still snaps, because the hover rule sets a property the transition does not list.
+Run the audit against the page, then fix at the cause.
+
+**Stance.** Every interactive control owes a visible, quick response to hover, press and keyboard focus;
+frequency decides *how much* motion (a list row gets a 120 ms tint, a primary CTA gets lift and press),
+never *whether* there is feedback. A response with no transition (`snaps`) is a warning to review, not
+always a defect. Motion must never cost legibility, input latency or accessibility.
+
+## What is measured and what is read
+
+| Source | What it covers |
+|---|---|
+| `frames` | Position, size, opacity and transform of the element and its descendants sampled on every animation frame: measured duration, curve shape, overshoot, jumps, animated layout, Long Animation Frames (with the scripts that caused them) |
+| `pixels` | Computed-style and screenshot comparison at rest, hover, press and focus: whether anything visibly changes |
+| `css` | Declared `transition` duration and easing, `:hover` rules outside `@media (hover: hover)`, reduced-motion rules: read from the stylesheet, so JS-driven motion (Motion, GSAP) is only judged from `frames` |
+| `events` | Animation objects and DOM events: a keyframe animation that restarts or is cancelled mid-way, infinite animations under reduced motion, entrances |
+
+`:active` and `:focus-visible` are forced through the DevTools protocol (no pointer or focus event is
+dispatched). Hover is a real pointer move after a hit test, so a control covered by a cookie banner or
+sticky header is skipped (`NOT RUN covered`) instead of producing a false finding.
+
+## What counts as a finding
+
+Levels are the defaults; the config file can change any of them.
+
+| Kind (script output) | What the user feels | Default level | Source |
+|---|---|---|---|
+| `no-feedback` | Hover changes nothing on a button: the UI feels dead (links: warning; inputs: not reported) | error | pixels |
+| `no-press-feedback` | Press changes nothing on a button (links and inputs: not reported) | warning | pixels |
+| `no-focus-feedback` | Keyboard focus is invisible | error | pixels |
+| `hover-only-control` | A control revealed only by pointer hover stays invisible when it gets keyboard focus | warning | pixels |
+| `snaps` | Feedback exists but jumps: the changed properties have no transition | warning | css |
+| `layout-animated` | Width, height, top, margin, padding or font animate: neighbours shift and layout runs every frame | error | frames |
+| `long-frame` | A frame over 50 ms during hover, a click transition or scroll, from an application script or from style, layout and paint with no script; a warning on a development build | error | frames |
+| `ease-in` | The response starts slow: declared curve or measured trajectory | error | css |
+| `duration` | Declared duration outside the band for the gesture (hover 80-300, press 50-200, focus up to 250 ms) | warning | css |
+| `linear` | A transform or opacity transition declared linear: mechanical | warning | css |
+| `transition-all` | `transition: all` animates whatever changes, layout included | warning | css |
+| `inconsistent-duration` | Same kind of control and gesture with declared durations 1.5x and 60 ms apart | warning | css |
+| `jump` | A frame moves several times faster than a smooth curve allows: a teleporting animation | error | frames |
+| `interrupt-jump` | Leaving hover mid-way, or clicking again mid-transition, jumps instead of reversing | error | events |
+| `not-interruptible` | A toggle clicked back part-way through its motion restarts from the other end (needs `--interact`) | error | events |
+| `ungated-hover` | `:hover` moves things outside `@media (hover: hover)`: it sticks after a tap on touch screens | warning | css |
+| `reduced-motion-moves` | With prefers-reduced-motion a press still translates, rotates or scales by more than 6 % | error | css |
+| `reduced-motion-residue` | With prefers-reduced-motion a transform stays after release (needs `--interact`) | error | css |
+| `reduced-motion-loop` | An infinite moving animation keeps running under reduced motion (small rotate-only spinners excepted) | error | events |
+| `reduced-motion-hidden` | Content waits for an entrance that reduced motion skipped: it stays at opacity 0 | error | pixels |
+| `reduced-motion-missing` | Things move and no readable stylesheet has a reduced-motion rule (info when some sheets are unreadable) | warning | css |
+| `no-entrance` | A section below the fold appears without an entrance (opt-in with `--entrances`; never fails the run) | info | events |
+| `inconclusive` | The frames were too sparse to confirm or rule out a finding (its `check`, with the fingerprint of that finding): the reason gives the median and longest interval; never fails the run | warning | frames |
+| `click-target` | The `--click` selector matches nothing visible | error | pixels |
+
+`info` never fails a run. Missing `:active` or hover on links and inputs is never an error.
+
+## Method
+
+### 1. Measure on the running page
+
+Audit a **production build** (`next start`, `vite preview`, a deployed preview), not a dev server. Dev
+builds add HMR, overlays and unminified work: the audit detects them, says so, and downgrades
+`long-frame` to a warning, but only a production build gives frame timings that mean something.
+
+If the project has `motion-audit` as a devDependency, prefer `npx --no-install motion-audit <url> ...`: it runs
+the version the project pins. Otherwise run the script bundled with this skill. The same command works in Git Bash, other POSIX shells and
+PowerShell (`${CLAUDE_SKILL_DIR}` is substituted before the shell runs it; the single-quoted selectors are literal in both):
+
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/motion-audit.mjs" http://localhost:3000/orders
+node "${CLAUDE_SKILL_DIR}/scripts/motion-audit.mjs" http://localhost:3000/orders --cpu 4 --click '[aria-controls=filters]' --interrupt
+node "${CLAUDE_SKILL_DIR}/scripts/motion-audit.mjs" http://localhost:3000/orders --only 'nav a' --only '.toolbar button' --frames '.btn-primary'
+```
+
+Exit 0 clean, 1 findings, **2 could not run, audited nothing or audited incompletely** - a 2 is never a
+pass. The summary says `audited N of M controls` and lists every skip with its reason (`NOT RUN hidden`,
+`covered`, `beyond --max 40`...); when N is lower than M, say which controls were not audited.
+`--min-coverage 0.8` turns a low ratio into exit 2; controls beyond `--max` count as not audited, so
+raise it too (`--max 200 --min-coverage 0.8`). Controls that appear after the audit counted them (a late
+fetch) make the run exit 2 with `INCOMPLETE`: re-run with `--wait-for`. A URL that redirects, from the
+server or from script (a session check, a router), exits 2 instead of auditing another page; a login
+page is never audited (use `--storage-state`), another page only with `--allow-redirect`.
+
+**Observe-only by default.** The audit hovers, forces `:active` and `:focus-visible`, scrolls and reads.
+It does not click, so it cannot toggle a Follow button, open a menu that opens on `pointerdown`, submit a
+form, switch a tab that switches on `mousedown`, or run focus and keyboard handlers. It does move the
+real pointer and scroll the real page, so handlers bound to hover (`mouseenter`, `mouseover`,
+`pointerenter` that send a beacon or write storage), scroll-bound `IntersectionObserver` callbacks and
+`beforeunload` beacons run: audit a throwaway or staging environment, not one where an impression or a
+hover event is billed or irreversible. `--interact` is opt-in and adds a real press and the
+toggle probes (`not-interruptible`, `reduced-motion-residue`); a denylist skips submit and reset
+controls (inside their form or tied to it with `form=`), buttons with no accessible name, every link
+whose `href` is not `#` or the `#id` of an element of the page (hash routes included; and any control inside one), destructive or payment wording in
+English, Spanish, Portuguese, French, German and Italian (including `aria-labelledby` and image alt
+text), `[draggable]`, sliders and separators; a press is released where it was made (the pointer never
+moves while it is down, so nothing is dragged), cancelled with a `pointercancel` before the release and with clicks cancelled for a moment after it (longer than the 80 ms a library waits for the native click), so libraries that act on pointerup (React Aria) do not fire; a plain `mouseup` handler on the control still runs; the
+page is reloaded between probes, the run stops if a gesture navigates, every toggle is clicked as the
+same node an even number of times, and the denylist is checked again before each click and before the
+reduced-motion pass presses a control. Use it only
+against a disposable environment.
+
+`--click <selector>` is an explicit click on the control you name, and it clicks more than once: twice
+(a pass without the tracer for long frames, one with it for trajectories), four times with
+`--interrupt`. A step the frames were too coarse to judge adds up to two more recordings (one press each,
+two with `--interrupt`), and when a flaky aspect is found the measurement is repeated twice more, two presses
+each: at most eight clicks, sixteen with `--interrupt` (the count is always even: an odd one, after a retry without `--interrupt`, gets one more press that restores the state, provided each press's effect lands within the 1.5 s of its recording: a request still pending at the next reload is reported in the notes, one a timer sends later cannot be seen). Run
+it only against a throwaway environment: a "Save" or "Delete" target is saved or deleted several times.
+
+- `--cpu 4` throttles like a mid-range phone. Jank that only shows throttled is still jank.
+- `--click <sel>` records everything that moves for 1.5 s after a real click, including overlays mounted
+  into `<body>` on open; `--interrupt` clicks again at 160 ms. Do it for every overlay the screen opens.
+- `--frames <sel>` writes a contact sheet through hover, press and release with the real time of each
+  frame. Look at it: the numbers say *that* it moved, the sheet shows *how*.
+- `--storage-state <file>` runs logged in (a Playwright storage state); a redirect to a login page exits 2.
+- `--wait-for <sel>` waits for the selector before auditing (apps that hydrate late).
+- `--entrances` also reports sections that appear without an entrance, as info.
+- `--max 40` is the default; with more controls the summary says `audited 40 of 200`. Narrow with `--only`.
+- Inner scroll containers are scrolled and their controls audited; hidden-until-hover controls are found.
+- Flaky kinds (`long-frame`, `jump`, `interrupt-jump`, `not-interruptible`) are re-measured twice and kept
+  only when two of three runs agree.
+- `inconclusive` rows appear when a machine drops so many frames that a check (`ease-in`, `interrupt-jump`,
+  `jump`) cannot be decided even after re-recording. They are listed with the findings, counted in
+  `coverage.inconclusive` and never fail the run. Rerun on a quieter machine, or without `--cpu` throttling.
+- `report.json` (printed with `--json`, `schemaVersion: 1`) has the coverage, `loafSupported`, every
+  element's measurements, the findings with stable ids, baselined and suppressed findings.
+
+States the first load does not show (open menus, toasts, loading, error) need the page put in that state:
+run against a route or story that renders it, or use `--click` to open it.
+
+### 2. Diagnose: name the cause before editing
+
+For each finding: which element, which gesture, which property moved (or failed to), and **who drives
+it** - a CSS transition, `@keyframes`, WAAPI, a JS library, or a rAF loop writing styles. A jump during a
+click is usually a JS animation fighting a CSS transition on the same property, or an element re-mounted
+mid-animation (React `key` change). Open `references/fixes.md` for the row that matches the cause.
+
+### 3. Fix at the cause, in the component or the tokens
+
+Load `references/fixes.md` only now: it maps each root cause to the fix and to the tempting wrong fix.
+Do not add motion to silence an `info`, and do not add a scale to every control to clear a `warning`.
+
+### 4. Verify and close
+
+1. Re-run with the same flags.
+2. Re-run with `--cpu 4` on the screens that had long frames, on a production build.
+3. Look at a contact sheet (`--frames`) of the primary control and one frequent control.
+4. **Finish with 0 errors, or each remaining finding suppressed in `motion-audit.config.json` with its reason.**
+
+```json
+{
+  "bands": { "reason": "Carbon micro-interactions run at 70 ms", "hover": [60, 300] },
+  "tokens": { "reason": "design-system duration tokens", "durations": [70, 120, 200] },
+  "severity": { "inconsistent-duration": { "level": "info", "reason": "size-scaled durations are intended" } },
+  "ignore": [
+    { "kind": "no-feedback", "element": "a \"Skip to content\"*", "reason": "visible only on focus, by design" },
+    { "id": "no-feedback:3f2a9c1d07", "reason": "tracked in the design-system backlog" }
+  ]
+}
+```
+
+Anything that loosens the audit (bands, tokens, a lowered or `off` severity, an ignore) needs a
+`reason`; ids are the `kind:hash` shown after each finding, never a wildcard; a kind rule must name an
+element. Raising a severity needs no reason. `--baseline report.json` accepts the findings an earlier
+report already had, so CI fails only on new ones; `compare <ref.json> <mine.json>` lines two reports up
+control by control (measured duration, curve, overshoot) and lists new and gone findings.
+
+### Lock it in with a test
+
+From a project that installed the package (`npm i -D github:NahuelMosse/motion-audit#v1.0.0`) next to
+`@playwright/test`; the test's own `page`, `baseURL` and `storageState` are used:
+
+```js
+// motion.spec.mjs
+import { test, expect } from '@playwright/test';
+import { audit } from 'motion-audit';
+
+test('orders: motion', async ({ page }) => {
+  test.setTimeout(240_000); // each control takes a few seconds of real time
+  await page.goto('/orders');
+  const report = await audit(page, { only: ['main button', 'nav a'], max: 20, out: 'test-results/motion' });
+  expect(report.coverage.audited).toBeGreaterThan(0);
+  expect(report.findings.filter((f) => f.level === 'error')).toEqual([]);
+});
+```
+
+Or the CLI: `npx motion-audit http://localhost:3000/orders --max 200 --min-coverage 0.8 --baseline motion-baseline.json`.
+
+## Limits
+
+- Chromium only. Safari renders some transitions differently; check gesture-heavy UI there by hand.
+- Colour and shadow transitions are judged from computed styles and pixels, not traced per frame.
+- Long Animation Frames need Chromium 123+; when unsupported the report says
+  `loafSupported: false` - never read that as clean.
+- Cross-origin stylesheets (and linked ones under `file://`) cannot be read for the `:hover` and
+  reduced-motion rule checks: they are counted, and `reduced-motion-missing` becomes `info` with the count.
+- `not-interruptible` and `interrupt-jump` rely on Animation objects (keyframe restarts, cancelled
+  animations) at any sampling density; for JS-driven motion (rAF, spring libraries) a teleport is only
+  detected when frames are sampled about every 16 ms, so a slow or throttled run can miss a small one.
+- A component re-mounted mid-animation (a changed React `key`) is seen when the old node and the new one
+  have the same tag and role, share a parent and are one to four frames apart; other replacements are
+  separate series.
+- Long frames are the page's own: the time of the audit's injected scripts (the tracer, `page.evaluate`)
+  is taken out of each frame, so a heavy page under heavy machine load can still show an unattributed one.
+- On a machine that drops frames (a loaded or virtualised runner), a teleport that lands in a frame of 66 ms or
+  more is indistinguishable from a steep easing: the audit re-records the click while some steps are
+  undecidable and, if it still cannot be decided, reports an `inconclusive` row.
+- Shadow DOM and iframes are not entered; canvas and WebGL motion is not measured.
+- Durations are compared within the same element kind (`button`, `a`, `tab`...): put deliberate
+  differences in `tokens.durations` or ignore them with a reason.
+
+## Reporting back
+
+Per finding fixed: element, gesture, cause, fix, and the measured value before and after. Findings left
+in place: the suppression and its reason. The script result as exit code and its summary line; if it
+could not run or audited fewer controls than the page has, say so - never report an unrun audit as passed.

package/skills/motion-audit/references/fixes.md

@@ -0,0 +1,25 @@
+# Fix catalogue
+
+Load this when a finding is diagnosed and a fix has to be chosen. Each row maps a root cause to the
+fix that removes it and the tempting fix that does not.
+
+| Root cause | Correct fix | Wrong fix |
+|---|---|---|
+| Hover/press rule changes a property the `transition` does not list | List exactly the properties that change: `transition: background-color 140ms var(--ease-out), transform 120ms var(--ease-out)` | `transition: all` |
+| Button has no hover or press state | Tint or shadow on hover, `scale(0.97)` or a 1-2 px `translateY` on press | Leaving frequent buttons static "because they are frequent" |
+| `outline: none` with nothing in its place | `:focus-visible { outline: 2px solid ...; outline-offset: 2px }` (or a ring on the wrapper with `:focus-within`) | `:focus` ring shown on every mouse click; removing the outline |
+| A control is revealed only by `:hover` (`opacity-0 group-hover:opacity-100`) | Reveal it on `:focus-visible` and `:focus-within` too (`group-focus-within:opacity-100`, `focus-visible:opacity-100`) | Keeping it `display: none` until hover |
+| Width/height/margin/top animated (expand, grow, slide) | `transform`/`opacity`; for size, FLIP (measure, invert with `scale`, play), `grid-template-rows: 0fr -> 1fr` for accordions, or `interpolate-size: allow-keywords` with a short duration | `max-height: 9999px` hacks; `will-change` on everything |
+| Long frame when the gesture starts | Move work out of the handler: precompute, `requestIdleCallback`, `scheduler.yield()`, defer the fetch until after the first frame of the transition; animate on the compositor | Shortening the animation so the stutter is shorter |
+| Long frames while scrolling | Scroll-driven animations (`animation-timeline: view()`) or IntersectionObserver instead of scroll listeners; no layout reads in scroll handlers; fewer and lighter blurs and shadows animating | `passive: true` alone (it fixes input delay, not frame cost) |
+| `ease-in` or `linear` on a response | Strong ease-out (`cubic-bezier(0.23, 1, 0.32, 1)`) for enter and feedback; ease-in-out only for on-screen movement between two places; springs for gesture-driven motion | `ease` everywhere |
+| Durations out of band or inconsistent | Duration tokens per gesture (`--dur-hover`, `--dur-press`, `--dur-enter`, `--dur-overlay`) used by every component; list deliberate ones in `tokens.durations` of the config | Tuning each component by eye |
+| Hover driven by `@keyframes`, or a JS animation restarting from its start value | CSS transitions (they reverse from the current value) or springs that retarget from the live value | `animation-fill-mode` tricks; disabling pointer events during the animation |
+| Toggle reversed mid-motion restarts (`not-interruptible`): open and close are `@keyframes` classes, each starting at its own `from` | Transitions between two states (`.open { transform: none }` with `transition: transform ...`), which reverse from the current value; or WAAPI: keep the `Animation` and call `reverse()`, or start the new one from `getComputedStyle(el).transform`; with Motion or springs, retarget from the live value | Disabling the button or pointer events while it animates; a longer duration |
+| Dialog, menu or toast mounted on open has no exit and jumps | Keep it mounted until the exit finishes (Presence, `onAnimationEnd`, `<dialog>` with `@starting-style` and `transition-behavior: allow-discrete`) | Unmounting in the same tick as the state change |
+| JS animation and CSS transition on the same property | One owner per property: remove the CSS transition where the library animates | Adding `!important` |
+| `:hover` transform on touch | Wrap motion in `@media (hover: hover) and (pointer: fine)`; keep colour feedback outside it | Removing hover motion everywhere |
+| Reduced motion ignored | `@media (prefers-reduced-motion: reduce)`: drop translate, large scale, parallax and loops; keep opacity and colour changes and a small press scale; in JS honour `matchMedia` (Motion: `MotionConfig reducedMotion="user"`) | `* { animation: none !important; transition: none !important }`: it also kills feedback and can strand entrances at opacity 0 |
+| Entrance leaves content at opacity 0 when its animation is skipped | Put the visible state in the base style and animate *from* hidden (`@starting-style`, `animation-fill-mode: backwards`, or a class added by an observer that is a no-op under reduced motion) | Hiding content until JS runs |
+| Infinite decorative loop | Stop it or replace it with a slow opacity pulse under reduced motion; pause off-screen | Leaving it because it is "small" |
+| A section appears with no entrance (`no-entrance`, info) | Only if the design calls for it: a short opacity + 8-16 px translate on first view, 30-80 ms stagger for groups, once only | Re-animating on every scroll pass; entrances over 600 ms; adding motion just to silence an info |

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

@@ -0,0 +1,88 @@
+// Command-line parsing with validation: unknown flags and invalid numbers are usage errors.
+import { DEFAULT_MAX_ELEMENTS } from './constants.mjs';
+
+export class UsageError extends Error {}
+
+// type: 'string' | 'int' | 'number' | 'ratio' | 'bool'; repeat: collected into an array.
+const SPEC = {
+  only: { type: 'string', repeat: true },
+  max: { type: 'int', min: 1 },
+  cpu: { type: 'number', min: 1 },
+  click: { type: 'string' },
+  interrupt: { type: 'bool' },
+  interact: { type: 'bool' },
+  frames: { type: 'string', repeat: true },
+  entrances: { type: 'bool' },
+  out: { type: 'string' },
+  config: { type: 'string' },
+  baseline: { type: 'string' },
+  'storage-state': { type: 'string' },
+  'wait-for': { type: 'string' },
+  'allow-redirect': { type: 'bool' },
+  'min-coverage': { type: 'ratio' },
+  strict: { type: 'bool' },
+  json: { type: 'bool' },
+  help: { type: 'bool' },
+};
+
+export const USAGE = `motion-audit <url|file> [options]
+motion-audit compare <ref.json> <mine.json>
+
+  --only <selector>       audit only elements matching it (repeatable)
+  --max <n>               audit at most n controls (default ${DEFAULT_MAX_ELEMENTS})
+  --cpu <rate>            throttle the CPU (4 is a mid-range phone)
+  --interact              also press and toggle controls for real (denylist applies); default is observe-only
+  --click <selector>      record 1.5 s after a real click on it
+  --interrupt             with --click: click again half-way
+  --frames <selector>     write a contact sheet of its hover and press (repeatable)
+  --entrances             report sections that appear without an entrance (info)
+  --config <file>         config file (default ./motion-audit.config.json)
+  --baseline <report>     ignore findings already present in an earlier report.json
+  --storage-state <file>  Playwright storage state (logged-in session)
+  --wait-for <selector>   wait for it before auditing (hydration)
+  --allow-redirect        audit the page the URL redirects to (a login page is never audited)
+  --min-coverage <0-1>    exit 2 when audited/candidates is lower (candidates include controls beyond --max)
+  --out <dir>             report and contact sheets (default: a temp directory)
+  --strict                warnings fail too
+  --json                  print the report as JSON (schemaVersion 1)
+  --help                  this text
+
+Exit: 0 clean, 1 findings, 2 could not run or audited nothing.`;
+
+const parseValue = (flag, spec, raw) => {
+  if (raw === undefined || raw === null) throw new UsageError(`--${flag} needs a value`);
+  if (spec.type === 'string') {
+    if (raw === '' || raw.startsWith('--')) throw new UsageError(`--${flag} needs a value, got "${raw}"`);
+    return raw;
+  }
+  const n = Number(raw);
+  if (raw.trim() === '' || !Number.isFinite(n)) throw new UsageError(`--${flag} must be a number, got "${raw}"`);
+  if (spec.type === 'int' && !Number.isInteger(n)) throw new UsageError(`--${flag} must be an integer, got "${raw}"`);
+  if (spec.type === 'ratio' && (n < 0 || n > 1)) throw new UsageError(`--${flag} must be between 0 and 1, got "${raw}"`);
+  if (spec.min !== undefined && n < spec.min) throw new UsageError(`--${flag} must be at least ${spec.min}, got "${raw}"`);
+  return n;
+};
+
+export const parseArgs = (argv) => {
+  const opts = { only: [], frames: [] };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+    const eq = a.indexOf('=');
+    const flag = eq < 0 ? a.slice(2) : a.slice(2, eq);
+    const spec = SPEC[flag];
+    if (!spec) throw new UsageError(`unknown option --${flag} (see --help)`);
+    if (spec.type === 'bool') {
+      if (eq >= 0) throw new UsageError(`--${flag} takes no value`);
+      opts[flag.replace(/-(\w)/g, (_, c) => c.toUpperCase())] = true;
+      continue;
+    }
+    const raw = eq >= 0 ? a.slice(eq + 1) : argv[++i];
+    const value = parseValue(flag, spec, raw);
+    const key = flag.replace(/-(\w)/g, (_, c) => c.toUpperCase());
+    if (spec.repeat) opts[key].push(value); else opts[key] = value;
+  }
+  if (opts.interrupt && !opts.click) throw new UsageError('--interrupt needs --click <selector>');
+  return { opts, positional };
+};