@mehshekari/gsap-motion 3.4.1 → 3.6.0

package/README.md

@@ -22,6 +22,8 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `audit-svg <file...>` | Reports what DrawSVG can draw, what MorphSVG can morph, and what will fail silently. `--morph a.svg b.svg` compares a pair; `--hues` also reports hard-coded hues. |
 | `inspect <url>` | Watches a page animate over the DevTools Protocol and reports what it saw: a filmstrip, the timeline GSAP is running, and the layouts, style recalculations and frames the browser did. `--scroll`, `--hover` and `--click` reach the state first; `--reduced`, `--dark`, `--mobile` and `--cpu` change the conditions. Needs a Chrome on the machine; installs nothing. |
 | `explain <file...|url>` | Maps an animation and changes nothing: where it lives, its preference branches, its beats in order with the reasons their comments give, its scroll configuration, and what the audit says. Given a URL it reads the running page instead, where the timeline is the one GSAP actually built. |
+| `review <url>` | Measures what the motion actually did, by sampling the DOM every frame rather than by reading GSAP's timeline — which a bundled app never exposes, and which would make it work on demo pages and fail on real ones. Reports time to first motion, the share of the screen moving at its busiest, loop seams, and motion over text being read. Sampling forces layout, so it does not report layout counts; `inspect` measures those. Takes the same `--scroll`, `--reduced`, `--dark`, `--mobile` and `--cpu`. |
+| `patterns check [file]` | Validates the Patterns section of your `ANIMATION.md`: the fields each status needs, the recorded uses behind `validated`, the named reviewer behind `canonical`, and entries verified against an older GSAP than the one installed. Exits 1 on a claim the evidence does not support, so it belongs in `lint` beside `audit`. A project with no Patterns section passes. |
 | `doctor` | Checks Node.js, the installed skill's version for this project and your user, your project's `gsap` and `@gsap/react`, and whether an `ANIMATION.md` exists. |
 
 ## In CI
@@ -30,7 +32,7 @@ The audit needs no install. Pin the version, so a new rule cannot fail your
 build without warning:
 
 ```json
-"lint": "eslint && npx @mehshekari/gsap-motion@3.4.1 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.6.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -9,6 +9,8 @@
  *   npx @mehshekari/gsap-motion audit-svg <file.svg...> [--morph] [--hues]
  *   npx @mehshekari/gsap-motion inspect <url> [--at ...] [--hover ...] [--reduced]
  *   npx @mehshekari/gsap-motion explain <file...|url>
+ *   npx @mehshekari/gsap-motion review <url> [--scroll ...] [--mobile]
+ *   npx @mehshekari/gsap-motion patterns check [ANIMATION.md]
  *   npx @mehshekari/gsap-motion doctor
  *
  * Installed as a dependency, the same commands run as `gsap-motion <command>`.
@@ -84,6 +86,19 @@ Commands
   explain <file...>     Map an animation: scopes, branches, beats, triggers
                         Give it a URL instead to read the running page
     --json              Machine-readable output
+  review <url>          Measure what the motion did: time to first motion,
+                        how much moves at once, loop seams, motion over text
+    --watch <ms>        How long to watch. Default 3000
+    --scroll <px|sel>   Scroll, then watch again
+    --reduced --dark    Emulate a preference
+    --mobile            390x844 with touch input
+    --cpu 4             Throttle the CPU by this factor
+    --out <dir>         Save a frame alongside the measurements
+    --json              Machine-readable output
+  patterns check [file] Check the Patterns section of your ANIMATION.md:
+                        the fields each status needs, the uses behind
+                        validated, the reviewer behind canonical
+    --json              Machine-readable output
   doctor                Check Node, the installed skill and your project's GSAP
   --version             Print the version
 
@@ -322,6 +337,12 @@ switch (command) {
   case "explain":
     runScript("explain-motion.mjs", args);
     break;
+  case "review":
+    runScript("review-motion.mjs", args);
+    break;
+  case "patterns":
+    runScript("patterns.mjs", args);
+    break;
   case "doctor":
     doctor();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.4.1",
+  "version": "3.6.0",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "3.4.1"
+  version: "3.6.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -101,8 +101,8 @@ intent → precedent → targets → trigger → motion language → technique
 2. **Precedent** — grep for the animation this codebase already has. Its
    trigger point, easing, durations, stagger shape and attribute naming are the
    house language: match them, and differ only for a reason you can state.
-   Nothing downstream catches a skipped precedent — the code compiles, the
-   audit passes, and the page reads as two different sites.
+   Nothing downstream catches a skipped precedent: the code compiles, the audit
+   passes, and the page reads as two different sites.
 3. **Targets** — which elements move, and can they be reached without a
    positional selector that breaks when the markup moves?
 4. **Trigger** — mount, in-view, scroll position, pointer, click, route, loop.
@@ -112,8 +112,8 @@ intent → precedent → targets → trigger → motion language → technique
 8. **Implementation** — typed, cleaned up, responsive.
 9. **Performance** — transform and opacity; measure before defending anything else.
 10. **Accessibility** — the reduced-motion design, focus, keyboard.
-11. **Validate** — [refine.md](reference/refine.md): audit, fix in order,
-    re-run, then the checklist in [motion-design.md](reference/motion-design.md).
+11. **Validate** — [refine.md](reference/refine.md): audit, fix in order, re-run,
+    then the checklist in [motion-design.md](reference/motion-design.md).
 
 ## Output format
 
@@ -178,16 +178,16 @@ node <skill-dir>/scripts/audit-svg.mjs <file.svg>
 node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
 node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>
 
-# Watch a page animate: frames, timeline, browser work.
-# Needs a Chrome; observations, not verdicts.
+# Both need a Chrome. Watch a page animate; then measure what it did:
+# first motion, screen share, seams, motion over text.
 node <skill-dir>/scripts/capture-motion.mjs <url> --at 0,300,900
+node <skill-dir>/scripts/review-motion.mjs <url> --scroll 2000
 ```
 
-Run `audit-gsap` first in an `audit` and after writing animation — as a plugin,
-a hook already runs it on every edit. A false finding is a bug in the script,
-not something to work around.
+Run `audit-gsap` in an `audit` and after writing animation; as a plugin, a hook
+runs it on each edit. A false finding is a bug in the script, never something to
+work around.
 
 `MotionPathHelper`, `GSDevTools`, `markers: true` and
-`MorphSVGPlugin.findShapeIndex()` are development-only, and a static import
-ships whatever `if` surrounds it. Import them dynamically behind a `NODE_ENV`
-check, and delete it once its value is baked in.
+`MorphSVGPlugin.findShapeIndex()` are development-only, and a static import ships
+whatever `if` surrounds it. Import them dynamically behind a `NODE_ENV` check.

package/skill/reference/project-rules.md

@@ -83,10 +83,76 @@ one is short, and each section is an instruction rather than an essay:
 
 ## Precedents
 <!-- Files that already do this well, by path, and what each one taught. -->
+
+## Patterns
+<!-- Shapes this project has proven. Format and statuses below; `patterns
+     check` validates this section. Omit the section until there is one. -->
 ````
 
 ---
 
+## Patterns: what the project has proven
+
+A pattern is a shape of animation this project has used and can use again. The
+section is optional, and empty is the honest state for a new project.
+
+**Nothing becomes guidance by having been written.** A pattern loaded as
+guidance repeats in every session after it, so a wrong one is not one mistake,
+it is every future mistake. That is why a status is evidence, not a claim.
+
+| Status | Reached when | Loaded as |
+|---|---|---|
+| `experimental` | Built for one request, its claims verified, the audit clean. **Offered in the answer, never written to the file.** | Nothing |
+| `candidate` | The user accepts it into ANIMATION.md. That acceptance is its first use. | An option to mention, never a default |
+| `validated` | Used again in a **different component** — two uses by default — each recorded with its file and commit, and each audit clean | The house way, unless the request gives a reason not to |
+| `canonical` | A **named person** has reviewed it | A precedent, followed like the house motion language |
+| `retired` | Disproved. Kept, with the reason, so it is not reinvented | A warning only |
+
+**Who moves an entry.** The skill offers entries and proposes promotions with
+their evidence; it never changes a status on its own. `candidate` needs your
+yes. `validated` is counted by `patterns check` from the recorded uses, never
+asserted by the entry. `canonical` needs a reviewer's name.
+
+**Moving down is evidence too.** A bug traced to a pattern returns it to
+`candidate` with the failure recorded. A GSAP release past its verified version
+marks it for re-verification — it stays loaded, marked. A use later reverted
+does not count.
+
+### The format
+
+```markdown
+### Ink behind a moving pen
+
+- **Status:** candidate
+- **Concept:** a mask shares the pen's duration and ease, so ink appears only
+  where the nib has already been.
+- **Fixed:** the mask and the path share one duration and one ease.
+- **Parameters:** duration, ease, nib radius.
+- **Not when:** the stroke crosses itself — the mask reveals the crossing early.
+- **Reduced motion:** the finished stroke is set, and no tween runs.
+- **Verified against:** gsap 3.15, DrawSVGPlugin
+- **Uses:**
+  - `src/components/Signature.tsx` — `a1b2c3d` — audit clean
+  - `src/components/Hero.tsx` — `e4f5a6b` — audit clean, review: no seams
+- **Reviewed by:** <!-- a name, for canonical only -->
+```
+
+`Concept`, `Not when`, `Reduced motion` and `Verified against` are required of
+every entry that is in the file. A `retired` entry needs only **Why**. Two uses
+in the same file count once: one component is one use.
+
+Run it with the rest of the checks:
+
+```bash
+gsap-motion patterns check          # or: patterns check path/to/ANIMATION.md
+```
+
+It exits 1 on a claim the evidence does not support, so it belongs in `lint`
+beside `audit`. Where a candidate has earned `validated`, it says so and leaves
+the promotion to you.
+
+---
+
 ## Rules worth knowing without a file
 
 Each of these fails silently in any project that has the condition.

package/skill/reference/refine.md

@@ -78,6 +78,41 @@ Reach the state first, and change the conditions that usually break things:
 
 **Without a browser, report the stage as not run.** Not "fine".
 
+## Measure it, once you have watched it
+
+`capture-motion.mjs` shows you frames. `review-motion.mjs` measures what the
+motion did, and is where the visual stage of this loop gets its evidence:
+
+```bash
+node <skill-dir>/scripts/review-motion.mjs http://localhost:3000 --scroll 2000
+```
+
+It samples the DOM every frame rather than reading `gsap.globalTimeline`,
+because a bundled app never publishes `gsap` to the page — so it works on a real
+Next, Vite, Nuxt, Astro or Svelte app, and it sees CSS and Web Animations motion
+that no source rule can reach.
+
+| It says | Read it as |
+| --- | --- |
+| **first motion at N ms** | How long the page is still. Late enough and the visitor has scrolled past the thing you built. |
+| **N elements moved, M of them GSAP's** | The gap is motion the audit never sees. A surprise there is worth chasing. |
+| **X% of the screen in motion** | Everything moving at once reads as noise, not as choreography. |
+| **seams** | A step far larger than that motion's own rhythm: a loop put back by hand instead of carried. |
+| **motion over text** | Something painted over a line a reader is in the middle of. Hit-tested, so it is what is really on top. |
+
+Three things it deliberately does not do, so you do not read them into it:
+
+- **It does not report layout cost.** Reading every box every frame is what
+  forces layout, so its numbers would be partly its own doing. `inspect`
+  measures that without sampling; use it for cost.
+- **It does not judge taste.** Composition, rhythm and whether the thing is any
+  good are yours, with the filmstrip in front of you.
+- **It does not report a seam a scroll caused.** Jumping the scrollbar is how it
+  reaches a scene, and a scrubbed animation answers instantly and correctly.
+
+A clean report is evidence, not proof: it watched one window, on one machine, at
+one size. Say which.
+
 ## When to stop
 
 Stop when every check is clean, or after **three rounds**, reporting what is
@@ -103,6 +138,8 @@ The answer's **Verification** section is one line per check, with its evidence:
 ```text
 Verification
 - audit-gsap: clean (3 warns waived: layout-property on the grid, with reasons)
+- review: first motion 410ms, 38% of the screen at its busiest, no seams,
+  nothing over text (1280x800, one 3s window)
 - reduced motion: emulated, the static branch sets the end state
 - StrictMode: mounted twice in dev, no doubled tweens
 - not checked: frame cost on a real phone — no device to hand

package/skill/scripts/patterns.mjs

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * patterns — what a project has proven, and what it has only tried.
+ *
+ * A skill that writes down whatever it just invented teaches itself its own
+ * mistakes: a bad pattern, once loaded as guidance, repeats in every session
+ * after it. So a pattern's standing is not something it can claim. It is
+ * counted from evidence recorded in the project's own ANIMATION.md:
+ *
+ *   experimental  built once, verified, offered in an answer. Never written.
+ *   candidate     the user put it in the file. Mentionable, never a default.
+ *   validated     used again, in another component, each use with its commit.
+ *   canonical     a named person reviewed it.
+ *   retired       disproved, kept with the reason so it is not reinvented.
+ *
+ * `validated` is computed here rather than asserted there, and `canonical`
+ * needs a name, because those are the two a keen assistant would otherwise
+ * grant itself. This command only reads and reports; it never edits the file.
+ *
+ * Node.js 18+, no dependencies.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const STATUSES = ["experimental", "candidate", "validated", "canonical", "retired"];
+
+/** How many separate components a pattern must appear in to be validated. */
+export const USES_FOR_VALIDATED = 2;
+
+const FIELDS = {
+  concept: "concept",
+  fixed: "fixed",
+  parameters: "parameters",
+  "not when": "notWhen",
+  "reduced motion": "reducedMotion",
+  "verified against": "verifiedAgainst",
+  "reviewed by": "reviewedBy",
+  why: "why",
+  status: "status",
+  uses: "uses",
+};
+
+/**
+ * Read the Patterns section of an ANIMATION.md.
+ *
+ * The format is what a person would write by hand — a heading per pattern and a
+ * bold-labelled list under it — because a format nobody will write is a format
+ * nothing will be recorded in. A field may wrap over several lines.
+ */
+export function parse(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  const entries = [];
+
+  let inSection = false;
+  let entry = null;
+  let field = null;
+
+  const closeField = () => {
+    if (entry && field && entry.fields[field] !== undefined) {
+      entry.fields[field] = entry.fields[field].trim();
+    }
+    field = null;
+  };
+
+  for (const line of lines) {
+    const heading = /^(#{2,3})\s+(.*)$/.exec(line);
+    if (heading) {
+      const [, hashes, title] = heading;
+      if (hashes === "##") {
+        closeField();
+        entry = null;
+        inSection = /^patterns\b/i.test(title.trim());
+        continue;
+      }
+      if (inSection) {
+        closeField();
+        entry = { name: title.trim(), status: null, fields: {}, uses: [] };
+        entries.push(entry);
+      }
+      continue;
+    }
+    if (!inSection || !entry) continue;
+
+    const labelled = /^\s*-\s+\*\*(.+?):\*\*\s*(.*)$/.exec(line);
+    if (labelled) {
+      closeField();
+      const key = FIELDS[labelled[1].trim().toLowerCase()];
+      if (!key) continue;
+      if (key === "status") {
+        entry.status = labelled[2].trim().toLowerCase() || null;
+        continue;
+      }
+      if (key === "uses") {
+        field = "uses";
+        continue;
+      }
+      field = key;
+      entry.fields[key] = labelled[2];
+      continue;
+    }
+
+    /** A use: a file, the commit it landed in, and what was checked. */
+    const use = /^\s+-\s+`([^`]+)`\s*[—-]\s*`([^`]+)`\s*(?:[—-]\s*(.*))?$/.exec(line);
+    if (use && field === "uses") {
+      entry.uses.push({ file: use[1].trim(), commit: use[2].trim(), note: (use[3] ?? "").trim() });
+      continue;
+    }
+
+    /** A continuation of the field above, wrapped by a person or a formatter. */
+    if (field && field !== "uses" && /^\s+\S/.test(line)) {
+      entry.fields[field] = `${entry.fields[field] ?? ""} ${line.trim()}`;
+    }
+  }
+  closeField();
+
+  return entries;
+}
+
+/** Components, not lines: two commits to one file is one pattern used once. */
+const distinctUses = (entry) => new Set(entry.uses.map((use) => use.file)).size;
+
+const REQUIRED = ["concept", "notWhen", "reducedMotion", "verifiedAgainst"];
+const LABEL = {
+  concept: "concept",
+  notWhen: "not when",
+  reducedMotion: "reduced motion",
+  verifiedAgainst: "verified against",
+};
+
+/**
+ * What the section gets wrong.
+ *
+ * Errors are claims the evidence does not support; warnings are entries that
+ * are fine but should not be in the file yet. Nothing here is a judgement about
+ * whether the pattern is any good.
+ */
+export function check(entries, { uses = USES_FOR_VALIDATED } = {}) {
+  const found = [];
+  const at = (entry, level, message) => found.push({ name: entry.name, level, message });
+
+  for (const entry of entries) {
+    if (!entry.status) {
+      at(entry, "error", `"${entry.name}" has no status. One of: ${STATUSES.join(", ")}.`);
+      continue;
+    }
+    if (!STATUSES.includes(entry.status)) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}": ${entry.status} is not a status. One of: ${STATUSES.join(", ")}.`,
+      );
+      continue;
+    }
+
+    if (entry.status === "retired") {
+      /** A retired pattern is kept only so it is not reinvented, so it owes one thing. */
+      if (!entry.fields.why) {
+        at(entry, "error", `"${entry.name}" is retired but does not say why it was retired.`);
+      }
+      continue;
+    }
+
+    if (entry.status === "experimental") {
+      at(
+        entry,
+        "warn",
+        `"${entry.name}" is experimental, which is offered, not written. ` +
+          "Make it a candidate when it is accepted, or take it out.",
+      );
+      continue;
+    }
+
+    const missing = REQUIRED.filter((key) => !entry.fields[key]);
+    if (missing.length) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}" is missing: ${missing.map((key) => LABEL[key]).join(", ")}.`,
+      );
+    }
+
+    if (entry.status === "validated" || entry.status === "canonical") {
+      const count = distinctUses(entry);
+      if (count < uses) {
+        at(
+          entry,
+          "error",
+          `"${entry.name}" claims ${entry.status} with ${count} recorded use${count === 1 ? "" : "s"}. ` +
+            `${uses} in separate components are needed, each with its file and commit.`,
+        );
+      }
+    }
+
+    if (entry.status === "canonical" && !entry.fields.reviewedBy) {
+      at(
+        entry,
+        "error",
+        `"${entry.name}" claims canonical with nobody named. Add "Reviewed by".`,
+      );
+    }
+  }
+
+  return found;
+}
+
+const asVersion = (text) => {
+  const found = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(text ?? "");
+  return found ? [Number(found[1]), Number(found[2]), Number(found[3] ?? 0)] : null;
+};
+
+/**
+ * Patterns verified against a GSAP older than the installed one.
+ *
+ * They stay loaded — a pattern does not stop working because a minor version
+ * shipped — but they are marked, because the claim behind them was checked
+ * against something else. A patch difference is not worth a word.
+ */
+export function stale(entries, { gsap } = {}) {
+  const installed = asVersion(gsap);
+  if (!installed) return [];
+
+  const found = [];
+  for (const entry of entries) {
+    if (entry.status === "retired") continue;
+    const verified = asVersion(entry.fields.verifiedAgainst);
+    if (!verified) continue;
+    const older = verified[0] < installed[0] || (verified[0] === installed[0] && verified[1] < installed[1]);
+    if (older) {
+      found.push({
+        name: entry.name,
+        level: "warn",
+        message:
+          `"${entry.name}" was verified against gsap ${verified[0]}.${verified[1]}, ` +
+          `and ${gsap} is installed. Re-verify it, or record the version you checked.`,
+      });
+    }
+  }
+  return found;
+}
+
+/**
+ * Candidates that have earned validated.
+ *
+ * Proposed, never applied: the skill offers a promotion with its evidence and a
+ * person accepts it. Canonical is absent on purpose — no amount of use earns a
+ * review.
+ */
+export function promotable(entries, { uses = USES_FOR_VALIDATED } = {}) {
+  return entries
+    .filter((entry) => entry.status === "candidate" && distinctUses(entry) >= uses)
+    .filter((entry) => REQUIRED.every((key) => entry.fields[key]))
+    .map((entry) => ({
+      name: entry.name,
+      to: "validated",
+      uses: distinctUses(entry),
+      files: [...new Set(entry.uses.map((use) => use.file))],
+    }));
+}
+
+// --- The command ---------------------------------------------------------------
+
+const installedGsap = (root) => {
+  for (const path of ["node_modules/gsap/package.json", "package.json"]) {
+    try {
+      const json = JSON.parse(readFileSync(resolve(root, path), "utf8"));
+      const version = path.endsWith("gsap/package.json")
+        ? json.version
+        : json.dependencies?.gsap ?? json.devDependencies?.gsap;
+      if (version) return String(version).replace(/^[\^~]/, "");
+    } catch {
+      /** No package.json, or no gsap in it: there is simply nothing to compare. */
+    }
+  }
+  return null;
+};
+
+export function report(entries, findings, { file, json, quiet }) {
+  if (json) {
+    return JSON.stringify({ file, patterns: entries.length, findings }, null, 2);
+  }
+
+  /**
+   * In a lint script, a check with nothing to say should say nothing. Errors
+   * still print, because they are why the run fails.
+   */
+  if (quiet) {
+    const errors = findings.filter((finding) => finding.level === "error");
+    return errors.map((finding) => `  error  ${finding.message}`).join("\n");
+  }
+
+  const lines = [];
+  if (!entries.length) {
+    lines.push(`No Patterns section in ${file}.`);
+    lines.push("Nothing to check. A pattern is written there once it has been accepted.");
+    return lines.join("\n");
+  }
+
+  const by = (status) => entries.filter((entry) => entry.status === status).length;
+  lines.push(`${entries.length} pattern${entries.length === 1 ? "" : "s"} in ${file}`);
+  lines.push(
+    "  " +
+      STATUSES.map((status) => `${by(status)} ${status}`)
+        .filter((part) => !part.startsWith("0 "))
+        .join(" · "),
+  );
+
+  if (findings.length) {
+    lines.push("");
+    for (const finding of findings) {
+      lines.push(`  ${finding.level === "error" ? "error" : " warn"}  ${finding.message}`);
+    }
+  }
+
+  const ready = promotable(entries);
+  if (ready.length) {
+    lines.push("", "Earned a promotion — yours to grant, with the evidence:");
+    for (const entry of ready) {
+      lines.push(`  ${entry.name} → validated (${entry.uses} uses: ${entry.files.join(", ")})`);
+    }
+  }
+
+  if (!findings.length) lines.push("", "patterns: clean");
+  return lines.join("\n");
+}
+
+async function main(argv) {
+  const json = argv.includes("--json");
+  const quiet = argv.includes("--quiet");
+  const rest = argv.filter(
+    (argument) => !["--json", "--quiet", "check"].includes(argument),
+  );
+  const file = rest[0] ?? "ANIMATION.md";
+  const root = process.cwd();
+
+  let markdown;
+  try {
+    markdown = readFileSync(resolve(root, file), "utf8");
+  } catch {
+    console.error(`Cannot read ${file}. Pass the path to your ANIMATION.md.`);
+    process.exit(2);
+  }
+
+  const entries = parse(markdown);
+  const findings = [...check(entries), ...stale(entries, { gsap: installedGsap(root) })];
+  const text = report(entries, findings, { file, json, quiet });
+  if (text) console.log(text);
+  process.exit(findings.some((finding) => finding.level === "error") ? 1 : 0);
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) await main(process.argv.slice(2));

package/skill/scripts/review-motion.mjs

@@ -0,0 +1,731 @@
+#!/usr/bin/env node
+/**
+ * review — the visual audit: what the motion actually did, measured.
+ *
+ * `audit` reads the source and says what is likely wrong. `inspect` watches and
+ * reports what it saw. This sits between them: it watches, and then draws
+ * conclusions that can be checked — time to first motion, how much of the screen
+ * moves at once, motion over text being read, loop seams, and layout work per
+ * frame.
+ *
+ * It does not read `gsap.globalTimeline`. A bundled app never publishes `gsap`,
+ * so an audit built on the timeline would work on demo pages and fail on real
+ * ones. Everything here comes from sampling the DOM: every frame, the box,
+ * opacity and transform of each element that can move, diffed against the frame
+ * before. That sees CSS and Web Animations motion too, which the source audit
+ * cannot see at all.
+ *
+ * What it does not do is judge taste. Composition, rhythm and visual quality are
+ * for a reviewer looking at the filmstrip; this reports evidence, with the time
+ * and the element, and leaves the verdict to them.
+ *
+ * Node.js 18+, no dependencies, whatever Chrome the machine already has.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { connect, findChrome } from "./capture-motion.mjs";
+
+// --- What a recording means ---------------------------------------------------
+
+/** The first moment anything moved, or null when nothing ever did. */
+export function firstMotion(log) {
+  return log.length ? log[0].at : null;
+}
+
+/**
+ * The share of the viewport in motion.
+ *
+ * Summing the boxes is wrong and wildly so: on a real page the moving elements
+ * are nested, and the first spike reported 34 viewports in motion on a viewport
+ * that has one. This is the area of their union, clipped to the screen — the
+ * fraction a viewer would say is moving.
+ *
+ * The union is computed by sweeping the distinct x edges and, for each strip,
+ * merging the y ranges that cover it. With the handful of boxes a frame holds,
+ * that is exact and fast enough to run per frame.
+ */
+export function coverage(boxes, viewport) {
+  const clipped = [];
+  for (const [x, y, width, height] of boxes) {
+    const x0 = Math.max(0, x);
+    const y0 = Math.max(0, y);
+    const x1 = Math.min(viewport.width, x + width);
+    const y1 = Math.min(viewport.height, y + height);
+    if (x1 > x0 && y1 > y0) clipped.push([x0, y0, x1, y1]);
+  }
+  if (!clipped.length) return 0;
+
+  const edges = [...new Set(clipped.flatMap(([x0, , x1]) => [x0, x1]))].sort((a, b) => a - b);
+  let area = 0;
+  for (let i = 0; i < edges.length - 1; i += 1) {
+    const left = edges[i];
+    const right = edges[i + 1];
+    const width = right - left;
+    if (!width) continue;
+
+    const spans = clipped
+      .filter(([x0, , x1]) => x0 <= left && x1 >= right)
+      .map(([, y0, , y1]) => [y0, y1])
+      .sort((a, b) => a[0] - b[0]);
+
+    let covered = 0;
+    let openFrom = null;
+    let openTo = null;
+    for (const [y0, y1] of spans) {
+      if (openTo === null || y0 > openTo) {
+        if (openTo !== null) covered += openTo - openFrom;
+        openFrom = y0;
+        openTo = y1;
+      } else if (y1 > openTo) {
+        openTo = y1;
+      }
+    }
+    if (openTo !== null) covered += openTo - openFrom;
+    area += width * covered;
+  }
+
+  return Math.round((area / (viewport.width * viewport.height)) * 1000) / 1000;
+}
+
+/**
+ * Where a loop jumps instead of travelling.
+ *
+ * A seam is a frame whose step is unlike every other step: a marquee that
+ * restarts at zero rather than being carried back, and shows a tear. Easing is
+ * not a seam, which is why this compares against the median step rather than
+ * the mean — an eased tween's steps vary smoothly, and no single one stands out
+ * against the middle of the distribution.
+ *
+ * A ratio alone is not enough. A nearly-still element has a median step of a
+ * fraction of a pixel, so the smallest wobble is many times it: the first run
+ * against a real page reported an orbiting dot that moved 7.6px. A tear has to
+ * be big enough to see, so a seam is both unlike its neighbours and at least
+ * `least` pixels.
+ */
+export function seams(track, { factor = 6, minimum = 4, least = 16 } = {}) {
+  if (track.length < minimum) return [];
+
+  const steps = [];
+  /**
+   * From index 2: a track begins when the element first moves, so its first
+   * step is the leap out of rest that a `from` tween makes when it sets its
+   * starting offset. A real page reported every such entrance as a 633px tear.
+   */
+  for (let i = 2; i < track.length; i += 1) {
+    steps.push({ at: track[i].at, delta: Math.abs(track[i].x - track[i - 1].x) });
+  }
+  if (!steps.length) return [];
+
+  const sorted = [...steps].map((step) => step.delta).sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  /** A still element has no normal step to be unlike, so nothing is a seam. */
+  if (!median) return [];
+
+  return steps
+    .filter((step) => step.delta > median * factor && step.delta >= least)
+    .map((step) => ({ at: step.at, jump: Math.round(step.delta * 10) / 10 }));
+}
+
+/** How much of `a` lies under `b`, as a share of `a`. */
+const overlap = ([ax, ay, aw, ah], [bx, by, bw, bh]) => {
+  const width = Math.min(ax + aw, bx + bw) - Math.max(ax, bx);
+  const height = Math.min(ay + ah, by + bh) - Math.max(ay, by);
+  if (width <= 0 || height <= 0) return 0;
+  return (width * height) / (aw * ah);
+};
+
+/**
+ * Motion passing over text a reader is in the middle of.
+ *
+ * A shared edge is not a problem — a rule sliding under a heading covers a few
+ * pixels of it — so this only reports motion over a quarter of the line or
+ * more. An element moving over itself is not motion over text, or every reveal
+ * of a paragraph would be reported.
+ */
+export function motionOverText(moving, text, { least = 0.25, visible = 0.5 } = {}) {
+  const found = [];
+  for (const line of text) {
+    for (const mover of moving) {
+      if (mover.key === line.key) continue;
+      /** A sheet at two percent opacity is over the text but not in the way. */
+      if (mover.opacity !== undefined && mover.opacity < visible) continue;
+      /**
+       * Nor is a wrapper that paints nothing. Geometry cannot tell a positioning
+       * box from a sheet: on a real page a transparent full-screen div was
+       * reported as covering every line on it. The page is asked whether the
+       * element paints at all, and only then is it in the way.
+       */
+      if (mover.paints === false) continue;
+      /**
+       * When the page hit-tested the line, believe it: `covered` is the element
+       * actually painted on top of it, and null means nothing is.
+       */
+      if (line.covered !== undefined && mover.id !== line.covered) continue;
+      const share = overlap(line.box, mover.box);
+      if (share >= least) {
+        found.push({
+          text: line.key,
+          over: mover.key,
+          share: Math.round(share * 100) / 100,
+        });
+      }
+    }
+  }
+  return found;
+}
+
+/**
+ * Seams that a scroll did not cause.
+ *
+ * Jumping the scrollbar is how this tool reaches a scene, and a scrubbed
+ * animation answers an instant scroll by moving instantly — correctly. A real
+ * page reported 575px and 77px tears at the exact moment of the scroll, which
+ * says something about how it was driven, not about the animation. Anything
+ * within `settle` of a frame that scrolled is therefore not reported.
+ */
+export function afterScroll(found, scrolledAt, { settle = 300 } = {}) {
+  return found.filter((seam) => !scrolledAt.some((at) => seam.at >= at && seam.at - at <= settle));
+}
+
+/**
+ * One lurch is one finding, however many elements were in it.
+ *
+ * Elements that move together tear together: a real page reported five rects
+ * jumping 25-30px, which reads as five problems and is one. Seams within
+ * `window` of each other are the same event, and the reader is told how many
+ * elements were in it.
+ */
+export function seamEvents(torn, { window = 50 } = {}) {
+  const flat = torn.flatMap((element) =>
+    element.seams.map((seam) => ({ key: element.key, at: seam.at, jump: seam.jump })),
+  );
+  flat.sort((a, b) => a.at - b.at);
+
+  const events = [];
+  for (const seam of flat) {
+    const open = events.at(-1);
+    if (open && seam.at - open.at <= window) {
+      open.elements.add(seam.key);
+      open.least = Math.min(open.least, seam.jump);
+      open.most = Math.max(open.most, seam.jump);
+      continue;
+    }
+    events.push({
+      at: seam.at,
+      elements: new Set([seam.key]),
+      least: seam.jump,
+      most: seam.jump,
+    });
+  }
+
+  return events.map((event) => ({
+    at: event.at,
+    count: event.elements.size,
+    example: [...event.elements][0],
+    least: event.least,
+    most: event.most,
+  }));
+}
+
+/** Each element and the moment it first moved, in that order. */
+export function starts(log) {
+  const first = new Map();
+  for (const frame of log) {
+    for (const moved of frame.moved) {
+      if (!first.has(moved.key)) first.set(moved.key, frame.at);
+    }
+  }
+  return [...first].map(([key, at]) => ({ key, at }));
+}
+
+// --- Options -----------------------------------------------------------------
+
+const asNumber = (value) => {
+  if (!/^\d+$/.test(String(value ?? ""))) return null;
+  return Number(value);
+};
+
+export function parseOptions(argv) {
+  const options = {
+    url: null,
+    watch: 3000,
+    scroll: null,
+    mobile: false,
+    reduced: false,
+    dark: false,
+    cpu: 1,
+    out: null,
+    json: false,
+    chrome: null,
+    errors: [],
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const argument = argv[i];
+    const next = () => argv[(i += 1)];
+
+    if (!argument.startsWith("--")) {
+      if (options.url === null) options.url = argument;
+      else options.errors.push(`More than one URL: ${argument}`);
+      continue;
+    }
+
+    switch (argument) {
+      case "--watch": {
+        const ms = asNumber(next());
+        if (ms === null || ms < 200) {
+          options.errors.push("--watch takes milliseconds, 200 or more.");
+        } else {
+          options.watch = ms;
+        }
+        break;
+      }
+      case "--scroll":
+        options.scroll = next() ?? null;
+        break;
+      case "--out":
+        options.out = next() ?? null;
+        break;
+      case "--cpu": {
+        const rate = Number(next());
+        if (!Number.isFinite(rate) || rate < 1) {
+          options.errors.push("--cpu takes a factor of 1 or more.");
+        } else {
+          options.cpu = rate;
+        }
+        break;
+      }
+      case "--chrome":
+        options.chrome = next() ?? null;
+        break;
+      case "--mobile":
+        options.mobile = true;
+        break;
+      case "--reduced":
+        options.reduced = true;
+        break;
+      case "--dark":
+        options.dark = true;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      default:
+        options.errors.push(`Unknown option: ${argument}`);
+    }
+  }
+
+  if (options.url === null) options.errors.push("No URL. Pass the page to review.");
+  return options;
+}
+
+// --- What runs in the page ----------------------------------------------------
+
+/**
+ * The recorder, installed before the page's own scripts so it sees the first
+ * frame. It keeps its log in the page and hands the whole thing over at the end:
+ * one round trip, not one per frame, because a round trip per frame would slow
+ * the page it is measuring.
+ */
+const RECORDER = `(() => {
+  if (window.__gsapMotionReview) return true;
+  const log = [];
+  const started = performance.now();
+  let frames = 0;
+  let previous = new Map();
+  let lastScrollX = window.scrollX;
+  let lastScrollY = window.scrollY;
+
+  /** Does this element put anything on the screen, or only position things? */
+  const paints = (style) =>
+    style.backgroundImage !== "none" ||
+    style.backdropFilter !== "none" ||
+    !/^rgba\(.*,\s*0(\.0+)?\)$/.test(style.backgroundColor);
+
+  const keyOf = (el) => {
+    const cls = typeof el.className === "string" ? el.className.trim().split(/\\s+/)[0] : "";
+    return el.tagName.toLowerCase() + (el.id ? "#" + el.id : "") + (cls ? "." + cls : "");
+  };
+
+  /**
+   * A readable key is not an identity. An SVG holds many rect elements with no
+   * id and no class, and on a real page every one of them collapsed into a
+   * single track whose interleaved positions looked like a 633px tear. Each
+   * element carries its own number; the key is only what the reader is shown.
+   */
+  let counter = 0;
+  const ids = new WeakMap();
+  const idOf = (el) => {
+    let id = ids.get(el);
+    if (id === undefined) {
+      id = counter += 1;
+      ids.set(el, id);
+    }
+    return id;
+  };
+
+  const tick =() => {
+    frames += 1;
+    const at = Math.round(performance.now() - started);
+    const now = new Map();
+    const moved = [];
+    /**
+     * Scrolling moves every box on the screen at once. Measured against the
+     * viewport, a scroll reads as the whole page animating and as a jump of
+     * hundreds of pixels in every track — the first run against a real page
+     * reported exactly that. Motion is therefore measured against the document,
+     * and only coverage and motion-over-text use where a thing is on screen.
+     */
+    const sx = window.scrollX;
+    const sy = window.scrollY;
+    const scrolled = sx !== lastScrollX || sy !== lastScrollY;
+    lastScrollX = sx;
+    lastScrollY = sy;
+
+    for (const el of document.querySelectorAll("*")) {
+      const style = getComputedStyle(el);
+      const transform = style.transform === "none" ? "" : style.transform;
+      const opacity = Math.round(parseFloat(style.opacity) * 100) / 100;
+      /** Only what can move: GSAP's own, or anything transformed or faded. */
+      if (!el._gsap && !transform && opacity === 1) continue;
+
+      const box = el.getBoundingClientRect();
+      const state = {
+        x: Math.round((box.x + sx) * 10) / 10,
+        y: Math.round((box.y + sy) * 10) / 10,
+        w: Math.round(box.width * 10) / 10,
+        h: Math.round(box.height * 10) / 10,
+        o: opacity,
+        t: transform,
+        screen: [
+          Math.round(box.x * 10) / 10,
+          Math.round(box.y * 10) / 10,
+          Math.round(box.width * 10) / 10,
+          Math.round(box.height * 10) / 10,
+        ],
+      };
+      now.set(el, state);
+
+      const before = previous.get(el);
+      if (
+        before &&
+        (before.x !== state.x || before.y !== state.y || before.w !== state.w ||
+          before.h !== state.h || before.o !== state.o || before.t !== state.t)
+      ) {
+        moved.push({
+          id: idOf(el),
+          key: keyOf(el),
+          gsap: Boolean(el._gsap),
+          box: state.screen,
+          x: state.x,
+          opacity: state.o,
+          paints: paints(style),
+        });
+      }
+    }
+
+    previous = now;
+    if (moved.length) log.push({ at, moved, scrolled });
+    requestAnimationFrame(tick);
+  };
+  requestAnimationFrame(tick);
+
+  /** The text on the page, read once at the end: what a reader could be reading. */
+  const textLines = () => {
+    const lines = [];
+    for (const el of document.querySelectorAll("p, h1, h2, h3, h4, li, blockquote, figcaption")) {
+      const text = (el.textContent || "").trim();
+      if (text.length < 20) continue;
+      const box = el.getBoundingClientRect();
+      if (box.width < 40 || box.height < 10) continue;
+      if (box.y > innerHeight || box.y + box.height < 0) continue;
+      /**
+       * Boxes cannot express stacking. A full-screen backdrop sits under the
+       * text and still covers it geometrically; a real page reported one as
+       * covering every line on it. Hit testing is the browser's own answer to
+       * what is on top, so the covering element is read rather than inferred.
+       */
+      const onTop = document.elementFromPoint(
+        Math.min(innerWidth - 1, Math.max(0, box.x + box.width / 2)),
+        Math.min(innerHeight - 1, Math.max(0, box.y + box.height / 2)),
+      );
+      const covered = onTop && onTop !== el && !el.contains(onTop) ? idOf(onTop) : null;
+
+      lines.push({
+        key: el.tagName.toLowerCase() + (el.id ? "#" + el.id : ""),
+        covered,
+        box: [
+          Math.round(box.x), Math.round(box.y),
+          Math.round(box.width), Math.round(box.height),
+        ],
+      });
+    }
+    return lines;
+  };
+
+  window.__gsapMotionReview = () => ({
+    frames,
+    elapsed: Math.round(performance.now() - started),
+    viewport: { width: innerWidth, height: innerHeight },
+    text: textLines(),
+    log,
+  });
+  return true;
+})()`;
+
+// --- Watching ------------------------------------------------------------------
+
+const wait = (ms) => new Promise((done) => setTimeout(done, ms));
+
+async function watch(options) {
+  const executable = findChrome(options.chrome);
+  if (!executable) {
+    throw new Error("No Chrome found. Install Chrome, or pass --chrome <path>, or set CHROME_PATH.");
+  }
+
+  const browser = connect(executable);
+  const notes = [];
+
+  try {
+    const { targetId } = await browser.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await browser.send("Target.attachToTarget", { targetId, flatten: true });
+    const call = (method, params) => browser.send(method, params, sessionId);
+    const evaluate = async (expression) => {
+      const { result } = await call("Runtime.evaluate", {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+      });
+      return result.value;
+    };
+
+    await call("Page.enable");
+    await call("Runtime.enable");
+    await call("Performance.enable");
+
+    const features = [];
+    if (options.reduced) features.push({ name: "prefers-reduced-motion", value: "reduce" });
+    if (options.dark) features.push({ name: "prefers-color-scheme", value: "dark" });
+    if (features.length) await call("Emulation.setEmulatedMedia", { features });
+    if (options.mobile) {
+      await call("Emulation.setDeviceMetricsOverride", {
+        width: 390,
+        height: 844,
+        deviceScaleFactor: 3,
+        mobile: true,
+      });
+      await call("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
+    }
+    if (options.cpu > 1) await call("Emulation.setCPUThrottlingRate", { rate: options.cpu });
+
+    await call("Page.addScriptToEvaluateOnNewDocument", { source: RECORDER });
+
+    const before = await call("Performance.getMetrics");
+    await call("Page.navigate", { url: options.url });
+    await wait(options.watch);
+
+    if (options.scroll !== null) {
+      const pixels = asNumber(options.scroll);
+      const moved = await evaluate(
+        pixels === null
+          ? `(() => {
+              const element = document.querySelector(${JSON.stringify(options.scroll)});
+              if (!element) return null;
+              element.scrollIntoView({ block: "center" });
+              return Math.round(window.scrollY);
+            })()`
+          : `(window.scrollTo(0, ${pixels}), Math.round(window.scrollY))`,
+      );
+      notes.push(moved === null ? `scroll: nothing matched ${options.scroll}` : `scroll: to ${moved}px`);
+      await wait(options.watch);
+    }
+
+    const recorded = await evaluate(
+      "window.__gsapMotionReview ? window.__gsapMotionReview() : null",
+    );
+    const after = await call("Performance.getMetrics");
+
+    if (!recorded) throw new Error("The recorder never ran. The page may have blocked scripts.");
+
+    const delta = (name) => {
+      const start = before.metrics.find((m) => m.name === name)?.value ?? 0;
+      const end = after.metrics.find((m) => m.name === name)?.value ?? 0;
+      return end - start;
+    };
+
+    let shot = null;
+    if (options.out) {
+      mkdirSync(resolve(options.out), { recursive: true });
+      const png = await call("Page.captureScreenshot", { format: "png" });
+      shot = join(resolve(options.out), "review.png");
+      writeFileSync(shot, Buffer.from(png.data, "base64"));
+    }
+
+    return {
+      url: options.url,
+      recorded,
+      layouts: delta("LayoutCount"),
+      recalcs: delta("RecalcStyleCount"),
+      shot,
+      notes,
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+// --- Conclusions ---------------------------------------------------------------
+
+/** Turn one recording into the findings a reviewer can act on. */
+export function conclude(result) {
+  const { recorded } = result;
+  const { log, viewport, text, frames, elapsed } = recorded;
+
+  const busiest = log
+    .map((frame) => ({ at: frame.at, share: coverage(frame.moved.map((m) => m.box), viewport) }))
+    .sort((a, b) => b.share - a.share)[0] ?? null;
+
+  /** One track per element, to find the loops that tear. */
+  const tracks = new Map();
+  const named = new Map();
+  for (const frame of log) {
+    for (const moved of frame.moved) {
+      const id = moved.id ?? moved.key;
+      const track = tracks.get(id) ?? [];
+      track.push({ at: frame.at, x: moved.x });
+      tracks.set(id, track);
+      named.set(id, moved.key);
+    }
+  }
+  const scrolledAt = log.filter((frame) => frame.scrolled).map((frame) => frame.at);
+  const torn = [];
+  for (const [key, track] of tracks) {
+    /** Only long-running motion can have a seam; a reveal simply ends. */
+    if (track.length < 20) continue;
+    const found = afterScroll(seams(track), scrolledAt);
+    if (found.length) {
+      torn.push({ key: named.get(key) ?? key, seams: found.slice(0, 3), frames: track.length });
+    }
+  }
+
+  /** Motion over text, judged at the busiest moment rather than every frame. */
+  const atBusiest = busiest ? log.find((frame) => frame.at === busiest.at) : null;
+  const overText = atBusiest ? motionOverText(atBusiest.moved, text) : [];
+
+  const began = starts(log);
+  return {
+    firstMotion: firstMotion(log),
+    frames,
+    elapsed,
+    fps: elapsed ? Math.round((frames / elapsed) * 1000 * 10) / 10 : null,
+    busiest,
+    movers: tracks.size,
+    gsapMovers: new Set(
+      log.flatMap((frame) => frame.moved.filter((m) => m.gsap).map((m) => m.id ?? m.key)),
+    ).size,
+    seams: seamEvents(torn),
+    overText,
+    began: began.slice(0, 8),
+    spread: began.length > 1 ? began.at(-1).at - began[0].at : 0,
+  };
+}
+
+// --- Report --------------------------------------------------------------------
+
+export function report(result, options) {
+  const found = conclude(result);
+  const lines = [`Reviewed ${result.url}`];
+
+  const emulated = [
+    options.reduced && "reduced motion",
+    options.dark && "dark",
+    options.mobile && "mobile 390x844",
+    options.cpu > 1 && `CPU ÷${options.cpu}`,
+  ].filter(Boolean);
+  if (emulated.length) lines.push(`  as: ${emulated.join(", ")}`);
+  for (const note of result.notes) lines.push(`  ${note}`);
+
+  lines.push("", "What moved");
+  if (found.firstMotion === null) {
+    lines.push("  nothing moved in the whole window — the animation never started,");
+    lines.push("  or it needs a scroll or a pointer to begin");
+  } else {
+    lines.push(`  first motion at ${found.firstMotion}ms`);
+    lines.push(
+      `  ${found.movers} elements moved, ${found.gsapMovers} of them GSAP's` +
+        `${found.movers > found.gsapMovers ? " (the rest is CSS, which the source audit cannot see)" : ""}`,
+    );
+    if (found.spread) lines.push(`  they started over a span of ${found.spread}ms`);
+  }
+
+  if (found.busiest) {
+    lines.push("", "How much moves at once");
+    lines.push(
+      `  at its busiest, ${Math.round(found.busiest.share * 100)}% of the screen was in motion` +
+        ` (${found.busiest.at}ms)`,
+    );
+  }
+
+  lines.push("", "Cost");
+  lines.push(
+    `  ${found.frames} frames over ${found.elapsed}ms${found.fps ? ` (${found.fps}/s)` : ""}`,
+  );
+  /**
+   * Layout counts are deliberately absent. Reading every box every frame is
+   * what forces layout, so this run's counts are the sampler's own work as much
+   * as the page's — measured on a real page, sampling quadrupled them. `inspect`
+   * measures that without sampling, and is the honest place to read it.
+   */
+  lines.push("  layout work is not measured here — sampling forces it; use inspect for that");
+
+  if (found.seams.length) {
+    lines.push("", "Seams — a step far larger than the motion's own rhythm");
+    for (const event of found.seams.slice(0, 6)) {
+      const size = event.least === event.most ? `${event.most}px` : `${event.least}-${event.most}px`;
+      lines.push(
+        `  ${event.at}ms  ${event.count === 1 ? event.example : `${event.count} elements (${event.example})`}` +
+          ` jumps ${size}`,
+      );
+    }
+  }
+
+  if (found.overText.length) {
+    lines.push("", "Motion over text");
+    for (const o of found.overText.slice(0, 5)) {
+      lines.push(`  ${o.over} covers ${Math.round(o.share * 100)}% of ${o.text}`);
+    }
+  }
+
+  if (result.shot) lines.push("", `Frame: ${result.shot}`);
+
+  lines.push("", "These are measurements. Composition, rhythm and taste are yours to judge.");
+  return lines.join("\n");
+}
+
+// --- Entry ---------------------------------------------------------------------
+
+async function main(argv) {
+  const options = parseOptions(argv);
+  if (options.errors.length) {
+    for (const error of options.errors) console.error(error);
+    console.error("\nUsage: node review-motion.mjs <url> [--watch 3000] [--scroll <px|sel>] …");
+    process.exit(2);
+  }
+
+  try {
+    const result = await watch(options);
+    console.log(
+      options.json
+        ? JSON.stringify({ url: result.url, ...conclude(result) }, null, 2)
+        : report(result, options),
+    );
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) await main(process.argv.slice(2));