@mehshekari/gsap-motion 3.6.0 → 4.2.0

package/README.md

@@ -10,7 +10,7 @@ npx @mehshekari/gsap-motion audit src      # find silent GSAP failures; exits 1
 npx @mehshekari/gsap-motion doctor         # what is installed, and is your GSAP recent enough
 ```
 
-No dependencies, no install scripts, Node.js 18 or later.
+No dependencies, no install scripts, Node.js 22 or later.
 
 ## Commands
 
@@ -24,7 +24,7 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `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. |
+| `doctor` | `--json` for the same report a script can read. 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
 
@@ -32,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.6.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.2.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -100,6 +100,7 @@ Commands
                         validated, the reviewer behind canonical
     --json              Machine-readable output
   doctor                Check Node, the installed skill and your project's GSAP
+    --json              Machine-readable output
   --version             Print the version
 
 Docs: https://github.com/mehShekari/gsap-motion`;
@@ -217,32 +218,88 @@ function runScript(script, args) {
   process.exit(result.status ?? 1);
 }
 
-function doctor() {
+function doctor(args = []) {
+  const json = args.includes("--json");
   const bundled = skillInfo(SKILL_DIR);
   const mark = { ok: green("✓"), warn: yellow("!"), info: dim("·") };
+  /**
+   * Every check is collected, so `--json` reports the same run the text one
+   * does rather than a second, thinner version of it. A half-JSON doctor is
+   * worse than none: it invites a script to trust a field nobody filled in.
+   */
+  const checks = [];
   const report = (state, message, hint) => {
+    checks.push({ state, message, ...(hint ? { hint } : {}) });
+    if (json) return;
     console.log(`${mark[state]} ${message}`);
     if (hint && state !== "ok") console.log(`  ${dim(hint)}`);
   };
 
-  console.log(`${bold("gsap-motion")} ${pkg.version}, carrying ${SKILL_NAME} ${bundled.version}\n`);
+  if (!json) {
+    console.log(`${bold("gsap-motion")} ${pkg.version}, carrying ${SKILL_NAME} ${bundled.version}\n`);
+  }
 
   const nodeMajor = Number(process.versions.node.split(".")[0]);
   report(
-    nodeMajor >= 18 ? "ok" : "warn",
+    nodeMajor >= 22 ? "ok" : "warn",
     `Node.js ${process.versions.node}`,
-    "The audit scripts need Node.js 18 or later.",
+    "The audit scripts need Node.js 22 or later.",
   );
 
+  /**
+   * A plugin may already be providing the skill, and then a copy in
+   * `.claude/skills` is not a missing install, it is the thing that shadows the
+   * plugin and goes stale. Found in a real project: a checked-in copy three
+   * releases behind a plugin that was current, while doctor recommended the
+   * command that creates exactly that.
+   */
+  const pluginProvides = () => {
+    for (const root of [process.cwd(), homedir()]) {
+      for (const file of ["settings.json", "settings.local.json"]) {
+        try {
+          const settings = JSON.parse(readFileSync(join(root, ".claude", file), "utf8"));
+          const enabled = Object.entries(settings.enabledPlugins ?? {})
+            .filter(([, on]) => on)
+            .map(([name]) => name)
+            .filter((name) => name.startsWith("gsap-motion@"));
+          if (enabled.length) return enabled[0];
+        } catch {
+          /** No settings file, or not JSON: nothing is claimed either way. */
+        }
+      }
+    }
+    return null;
+  };
+
+  const provider = pluginProvides();
+  if (provider) {
+    report("ok", `Provided by the ${provider} plugin`);
+  }
+
   for (const [scope, root, command] of [
     ["this project", process.cwd(), `npx ${pkg.name} add`],
     ["your user", homedir(), `npx ${pkg.name} add --global`],
   ]) {
     const location = join(root, ".claude", "skills", SKILL_NAME);
     const installed = skillInfo(location);
-    if (!installed) report("info", `Not installed for ${scope}`, `${command} installs it at ${location}`);
-    else if (installed.version === bundled.version) report("ok", `Installed for ${scope}: ${installed.version}`);
-    else report("warn", `Installed for ${scope}: ${installed.version}`, `${command} updates it to ${bundled.version}.`);
+    if (!installed) {
+      /**
+       * Recommending an install on top of a plugin is how a second, ageing copy
+       * gets created, so with a plugin present this is a fact, not a suggestion.
+       */
+      if (provider) report("info", `No separate copy for ${scope}`);
+      else report("info", `Not installed for ${scope}`, `${command} installs it at ${location}`);
+    } else if (installed.version === bundled.version) {
+      report("ok", `Installed for ${scope}: ${installed.version}`);
+    } else {
+      report(
+        "warn",
+        `Installed for ${scope}: ${installed.version}`,
+        provider
+          ? `The ${provider} plugin also provides it, and a local copy shadows the plugin. Remove ${location}, or ${command} to update it to ${bundled.version}.`
+          : `${command} updates it to ${bundled.version}.`,
+      );
+    }
   }
 
   const manifest = join(process.cwd(), "package.json");
@@ -310,6 +367,26 @@ function doctor() {
     rules ? "ANIMATION.md found — the skill follows it" : "No ANIMATION.md",
     "Optional. Add one so the skill follows your project's rules; see reference/project-rules.md in the skill.",
   );
+
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          cli: pkg.version,
+          skill: bundled.version,
+          node: process.versions.node,
+          adapters: ORDER.filter((name) => picked.has(name)),
+          plugin: provider,
+          animationMd: rules,
+          /** Nothing here is a verdict on the project; `worst` is only the highest state reached. */
+          worst: checks.some((check) => check.state === "warn") ? "warn" : "ok",
+          checks,
+        },
+        null,
+        2,
+      ),
+    );
+  }
 }
 
 const [command, ...args] = process.argv.slice(2);
@@ -344,7 +421,7 @@ switch (command) {
     runScript("patterns.mjs", args);
     break;
   case "doctor":
-    doctor();
+    doctor(args);
     break;
   case "--version":
   case "-v":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.6.0",
+  "version": "4.2.0",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",
@@ -35,7 +35,7 @@
     "NOTICE.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
     "bundle": "node scripts/bundle-skill.mjs",

package/skill/SKILL.md

@@ -2,9 +2,9 @@
 name: gsap-creative-animation
 description: Senior motion engineer for GSAP. Turns a visual or interaction idea into production-ready animation across DOM, SVG, text, images, scroll, pointer, layout and 3D — entrance reveals, scroll-driven sequences, pinned and horizontal scroll, magnetic cursors, kinetic typography, marquees, card stacks, page and modal transitions, loaders and site intros, SVG draw/morph/path, Flip layout transitions, and GSAP orchestration of Three.js/R3F. React and Next.js first; also vanilla JS, Vue, Svelte and Astro. Use whenever the user wants something animated, wants motion to feel cinematic/premium/alive/futuristic, wants an existing animation retimed, audited, or made cheaper, or mentions gsap, ScrollTrigger, DrawSVG, MorphSVG, MotionPath, SplitText, Flip, Observer, انیمیشن, موشن, اسکرول, لودینگ, مورفینگ.
 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.
+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 22+ and nothing else.
 metadata:
-  version: "3.6.0"
+  version: "4.2.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -60,33 +60,25 @@ Core principles:
 
 ## Commands
 
-| Command | Category | Description | Reference |
-|---|---|---|---|
-| `animate [target]` | Build | General entry — analyse the intent, then route | [reference/routing.md](reference/routing.md) |
-| `reveal [target]` | Build | Entrance and in-view reveals, staggers, masks | [preset/reveal.md](preset/reveal.md) |
-| `scroll [target]` | Build | Scroll-driven sequences, pin, scrub, horizontal | [reference/scrolltrigger.md](reference/scrolltrigger.md) |
-| `text [target]` | Build | Kinetic typography, split reveals, scramble | [reference/text.md](reference/text.md) |
-| `svg [file]` | Build | Draw, morph, path-follow, SVG timelines | [reference/svg.md](reference/svg.md) |
-| `interact [target]` | Build | Pointer, magnetic, cursor, drag, inertia | [reference/interaction.md](reference/interaction.md) |
-| `ambient [target]` | Build | Marquees, orbits, floating, breathing loops | [preset/marquee.md](preset/marquee.md) |
-| `transition [target]` | Build | Page, route, modal and layout transitions | [reference/flip.md](reference/flip.md) |
-| `loader` | Build | Loading and progress animation | [preset/loader.md](preset/loader.md) |
-| `intro` | Build | Site or section entry sequence | [preset/cinematic.md](preset/cinematic.md) |
-| `three [target]` | Build | GSAP orchestrating Three.js / R3F | [adapter/three.md](adapter/three.md) |
-| `audit [target]` | Evaluate | Check an existing animation: leaks, cost, a11y | [reference/performance.md](reference/performance.md) |
-| `tune [target]` | Refine | Retime, re-ease, fix rhythm — no new motion | [reference/motion-design.md](reference/motion-design.md) |
-| `strip [target]` | Fix | Remove motion that is not earning its place | [reference/motion-design.md](reference/motion-design.md) |
-
-Routing:
+| Group | Commands |
+|---|---|
+| **Build** | `create` — the front door: classify the request, then route · `design` — plan only, no code · `build` — implement an approved plan · and the ten domain commands, unchanged: `reveal` `scroll` `text` `svg` `interact` `ambient` `transition` `loader` `intro` `three` |
+| **Evaluate** | `audit` — a verdict, from the source · `inspect` — what a browser saw · `explain` — the architecture · `review` — what the motion measured |
+| **Refine** | `tune` — timing and easing only · `strip` — remove motion that is not earning its place · `evolve` — audit, fix, tune, then offer patterns |
+| **Knowledge** | `patterns` — what this project has proven, by status · `learn` — offer a verified finding as a candidate |
+
+`animate` is an alias of `create`. Routing:
 
 - **No argument, or no target:** read [routing.md](reference/routing.md) and
   ask what should move. "Add some animation to my homepage" names no target:
   never invent one.
 - **A command, explicit or implied:** load its reference and follow it.
 - **A description** ("make this feel like Apple", "the hero is boring"): that is
-  `animate`. Classify with routing.md's table, then load what that needs.
+  `create`. Classify with routing.md's table, then load what that needs.
 - **Two commands fit:** ask once. A scroll-driven text reveal is `scroll` and
   `text` together, not a coin toss.
+- **`design` stops at the plan.** `build` implements one that was approved, and
+  needs it in hand. `evolve` improves what is there and never adds motion.
 
 ## The pipeline
 
@@ -119,7 +111,8 @@ intent → precedent → targets → trigger → motion language → technique
 
 For anything beyond a one-line tweak, answer in this shape, each part short:
 
-- **Analysis** — what moves, why, in what style, on what trigger.
+- **Analysis** — what moves, why, on what trigger, and the intent you read it
+  as, with the values that follow.
 - **Motion strategy** — the sequence, as numbered beats.
 - **Architecture** — timeline shape, plugins and why each is needed, refs,
   handlers, what cleans up.

package/skill/reference/accessibility.md

@@ -54,6 +54,21 @@ mm.add(
 
 ```
 
+**Both conditions are required, and dropping `motion` breaks everything.** The
+callback runs only while at least one named condition matches. With `reduced`
+alone, a visitor who has no preference — nearly all of them — matches nothing,
+so the callback never runs and **the page ships with no animation at all**,
+silently: no error, and every test with reduced motion on still passes. The
+audit reports it as `matchmedia-never-runs`.
+
+A reduced-only `add` is still correct when it does not branch — the shape below
+is GSAP's own, and each callback is meant to run only for its own visitors:
+
+```ts
+mm.add("(prefers-reduced-motion: no-preference)", () => { /* the animation */ });
+mm.add("(prefers-reduced-motion: reduce)", () => { /* the end states */ });
+```
+
 Built inside a `useGSAP` body this needs no explicit teardown — `matchMedia`
 registers with the active context and is reverted with it.
 

package/skill/reference/motion-design.md

@@ -43,14 +43,14 @@ default.
 | Ease | Feel | Use |
 |---|---|---|
 | `power2.out` | quick start, soft landing | the default for entrances |
-| `power3.out` / `power4.out` | sharper, more expensive-feeling | premium, cinematic |
+| `power3.out` / `power4.out` | sharper, more expensive-feeling | see intents |
 | `power2.in` | gathers then leaves | exits |
 | `power2.inOut` | symmetric | moves between two resting states |
 | `none` | mechanical, constant | **anything looping**, scrub, marquee |
-| `back.out(1.4)` | overshoot | playful — never on more than one thing at a time |
+| `back.out(1.4)` | overshoot | playful — never two at once |
 | `elastic.out(1, 0.4)` | wobble | rarely; reads as a toy |
-| `sine.inOut` | gentle breath | ambient loops, pulses |
-| `expo.out` | dramatic arrival | one hero moment, not a list |
+| `sine.inOut` | gentle breath | ambient loops |
+| `expo.out` | dramatic arrival | one hero moment |
 
 Two failures worth naming. **An ease other than `none` on a repeating tween**
 puts a visible stutter at the seam — the loop decelerates into its own restart.
@@ -119,16 +119,21 @@ takeover — in [routing.md](routing.md).
 
 ## Reading a request
 
-| They say | They usually mean |
-|---|---|
-| "smoother" | longer duration, softer ease — or a cost problem; check which |
-| "snappier" | shorter duration, `power3.out`, less stagger |
-| "more premium" | fewer elements moving, longer eases, no overshoot |
-| "more playful" | overshoot on one element, tighter stagger |
-| "cinematic" | slower, sequential, one thing at a time, generous holds |
-| "subtle" | reduce distance before reducing duration |
-| "it feels cheap" | usually linear easing or uniform duration |
-| "it feels slow" | usually too sequential, not too long — try overlap first |
+A feeling resolves to values from the tables above. **Say them in Analysis**: a
+reviewer can argue with a reading, not with code.
+
+| Intent | Duration | Ease | Competing | Deliberately still |
+|---|---|---|---|---|
+| cinematic | 600–900ms, 1s+ for one hero beat | `power3.out`, `expo.out` once | one | the background |
+| premium | 350–500ms | `power3.out`, no overshoot | few | anything that would bounce |
+| playful | 200–350ms | `back.out(1.4)`, one element | few | every second overshoot |
+| alive | 1s+, looping | `sine.inOut`, `none` | ambient only | the content itself |
+| technical | 200–500ms | `none`, `power2.out`, stepped | a grid, together | curves |
+| organic | 600–900ms, overlapping | `sine.inOut`, soft | several | straight lines |
+
+**They compose, one column at a time.** "Cinematic but fast" keeps the ease and
+the focus, and moves down a duration band. [routing.md](routing.md) reads the
+common adjustments.
 
 ## Validation
 

package/skill/reference/project-rules.md

@@ -151,6 +151,25 @@ 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.
 
+### `patterns` and `learn`
+
+- **`patterns`** lists what the project has proven, by status, and what has
+  earned a promotion. Asked to apply one, it uses `validated` and `canonical`
+  entries by default and a `candidate` only when you name it — a candidate is an
+  option to mention, not a default to reach for.
+- **`learn`** offers a finding as a `candidate`, once you agree, and writes
+  nothing before that. It offers only what it has verified: the claim tested
+  with a minimal repro, the audit clean, and the entry carrying its concept,
+  what is fixed, when not to use it, its reduced-motion branch, and what it was
+  verified against. **An unverified finding is not offered at all**, and neither
+  command ever changes a status — `validated` is counted by `patterns check`,
+  and `canonical` is a person's signature.
+
+A new shape is composed from what exists before anything is invented, and a
+behaviour claim is verified one variable at a time before it is written down.
+Something that turns out to be general is worth an upstream issue; something
+mechanically detectable is worth an audit rule, with its fires and quiet cases.
+
 ---
 
 ## Rules worth knowing without a file

package/skill/reference/refine.md

@@ -147,3 +147,30 @@ Verification
 
 Say what you did not check, too. "Not checked" is information; silence reads as
 "checked and fine", and that is the one thing it must never mean.
+
+### "Verified" names what you saw
+
+**A check is a measurement, not a verb.** "Verified live", "tested at 390px" and
+"works as expected" say that something was run; they do not say what came back,
+so nobody can tell whether it would have caught the failure.
+
+A head-to-head test made the cost concrete. An answer written with this skill
+reported *"verified live, no horizontal overflow at 390px"* — and shipped two
+bugs that a 390px browser shows at a glance: the visual pushed below the fold,
+and a label invisible through its whole first state. Overflow was the one thing
+checked, and it was not what was broken.
+
+So a line states the value observed, at a time and a size:
+
+| Not this | This |
+|---|---|
+| verified live | badge label opacity 1 at t=0 and at every state label, 1280x800 |
+| works on mobile | 390x844: the visual's top edge at 96px, above the fold; no overflow |
+| reduced motion handled | reduced emulated: heading and lead at end state, no tween ran |
+| animation runs | `review`: first motion at 410ms; 0 elements invisible for the whole window |
+
+**Check the failure, not the feature.** A reveal that works is easy to observe;
+the failures that ship are an element that never appears, one that appears too
+late, and one that is off screen at the size you did not look at. Look for those
+by name. And a claim you did not observe is worse than "not checked": it tells
+the reader to stop looking.

package/skill/reference/routing.md

@@ -25,19 +25,34 @@ offer the menu below — grouped, so the question is easy to answer.
 
 Most requests are a feeling, not a command. Classify, then route.
 
-| What they say | What they mean | Route to |
+**A named feeling routes here, and resolves to values** in
+[motion-design](motion-design.md)'s *Reading a request* — duration, ease, how
+many move at once, and what stays still. They compose, so a request that names
+two is not a coin toss.
+
+| What they say | Route to |
+|---|---|
+| "make it cinematic" | `intro` · [cinematic](../preset/cinematic.md) |
+| "make it feel premium" | `tune` · [motion-design](motion-design.md) |
+| "make it feel alive" | `ambient` · [marquee](../preset/marquee.md) |
+| "futuristic / technical" | `text` + `svg` |
+| "liquid / organic" | `svg` · [loader](../preset/loader.md) |
+| "like Apple" | `scroll` · [scroll-storytelling](../preset/scroll-storytelling.md) |
+
+**A diagnosis is not a feeling**, and routes on what is actually wrong:
+
+| What they say | What it usually is | Route to |
 |---|---|---|
-| "make it cinematic" | slow, weighted, sequenced, one thing at a time | `intro` · [cinematic](../preset/cinematic.md) |
-| "make it feel premium" | fewer moving parts, longer eases, no bounce | `tune` · [motion-design](motion-design.md) |
-| "make it feel alive" | ambient continuous motion under static content | `ambient` · [marquee](../preset/marquee.md) |
-| "make it pop / bolder" | more contrast in timing, not more elements moving | `tune` · [motion-design](motion-design.md) |
-| "like Apple" | scroll-scrubbed, pinned, one idea per screen | `scroll` · [scroll-storytelling](../preset/scroll-storytelling.md) |
-| "futuristic / technical" | scramble, draw-on, mechanical easing, grid reveals | `text` + `svg` |
-| "liquid / organic" | morph, path motion, overlapping soft easing | `svg` · [loader](../preset/loader.md) |
-| "something crazy" | layered techniques with one clear concept | see below |
+| "make it pop / bolder" | contrast in timing, not more elements moving | `tune` |
+| "the hero is boring" | a hierarchy problem before a motion problem | `tune`, then `reveal` |
+| "it feels janky" | cost or trigger | `audit` · [performance](performance.md) |
 | "smooth image reveal" | clip-path or mask, not opacity | [reveal](../preset/reveal.md) |
-| "the hero is boring" | hierarchy problem before a motion problem | `tune`, then `reveal` |
-| "it feels janky" | cost or trigger problem | `audit` · [performance](performance.md) |
+| "something crazy" | layered techniques, one clear concept | see below |
+| "smoother" | longer and softer — or a cost problem, so check which | `tune`, or `audit` |
+| "snappier" | shorter, less stagger | `tune` |
+| "subtle" | less distance, before less duration | `tune` |
+| "it feels cheap" | linear easing, or one uniform duration | `tune` |
+| "it feels slow" | usually too sequential, not too long: try overlap | `tune` |
 
 ### "Something crazy"
 
@@ -90,6 +105,47 @@ single hover takes [interaction](interaction.md) and nothing else from its row.
 Do not load a domain file "for completeness". Loading `adapter/three.md` for a
 button hover is the failure this map exists to prevent.
 
+## `create`, `design` and `build`
+
+Three commands for one piece of work, separated so that the expensive part —
+writing code — is not where a disagreement about the idea surfaces.
+
+- **`create`** is the front door, and the alias `animate` still reaches it. It
+  classifies the request and routes: a domain command if one fits, `design`
+  first if the request is large or vague, straight to the work if it is small
+  and clear. A one-element hover does not need a plan; a site intro does.
+- **`design`** produces a plan and **no code**: what moves and why, the beats in
+  order, the device and reduced-motion strategy, the techniques with the reason
+  each is needed, and what it will cost against the project's motion budget.
+  It ends by asking whether to build it. Writing code here defeats the point —
+  the plan is cheap to argue with, and an implementation is not.
+- **`build`** implements a plan that was approved, and needs one in hand. Given
+  no plan it asks for one rather than inventing something to build; given a plan
+  it follows it through the pipeline, and says plainly where it departed and
+  why. A departure is not a failure — a plan meets the real markup for the first
+  time during `build` — but a silent one is.
+
+## `evolve`
+
+Improve motion that already exists: `audit`, fix what it found, `tune` the
+timing, then offer what was learned. It adds no new motion; that is `create`.
+
+Its guards, all four of which exist because an improvement loop is the easiest
+place for an assistant to do damage while feeling useful:
+
+- **It needs a target, and keeps to one component or scene.** "Evolve the site"
+  is not a request, it is an invitation to churn.
+- **It shows its plan before a large change.** A retime is not a large change;
+  restructuring a timeline is.
+- **It stops after three rounds** and reports what is left, rather than trying a
+  fourth shape of the same idea.
+- **It leaves approved motion alone.** Something the project accepted is not a
+  defect because this run would have done it differently.
+- **It offers at most an `experimental` pattern, and never changes a status.**
+  See [project-rules.md](project-rules.md): standing comes from evidence, and a
+  loop that promotes its own output is the failure the maturity model exists to
+  prevent.
+
 ## `audit`
 
 **Run the checker first.** It is deterministic, it costs a second, and it finds

package/skill/reference/timeline.md

@@ -186,3 +186,35 @@ ScrollTrigger's `scrub` is this same mechanism with scroll as the value.
 | Entrance replays on loop | `repeat: -1` on the timeline, not the child |
 | Flash of the end state before it runs | `from` without a `set`, outside a layout effect |
 | Two beats drift apart after an edit | both timed by number instead of sharing a label |
+| An element is invisible until much later than it should be | several `from`/`fromTo` on it, each applying its start state when built |
+
+### `from` renders when it is built, not when it plays
+
+`from` and `fromTo` default to `immediateRender: true`: the start state is
+written to the element **the moment the tween is created**, not when the
+playhead reaches it. With one tween per element that is exactly what you want —
+nothing flashes before the entrance.
+
+Build several against the same element and they all write at once, in order, so
+**the last one wins and holds the element there until the playhead arrives.**
+A helper that adds a beat per state is the usual way in: one call site, run in
+a loop, and a label that stays hidden through every state before the last.
+
+```ts
+const addBeat = (state: string) => {
+  tl.addLabel(state).fromTo(
+    badge,
+    { autoAlpha: 0, y: 6 },
+    { autoAlpha: 1, y: 0, immediateRender: false }, // written when it plays
+    state,
+  );
+};
+
+gsap.set(badge, { autoAlpha: 1, y: 0 }); // the first state, set once, on purpose
+STATES.forEach(addBeat);
+```
+
+The conflict is per property. Two tweens on one element that set **different**
+properties — one fading in on `opacity`, another turning on `rotationY` — hide
+nothing, and need no change. The audit reports the shape that does hide:
+`stacked-from`.

package/skill/scripts/capture-motion.mjs

@@ -11,7 +11,7 @@
  *
  * It drives Chrome over the DevTools Protocol through a pipe — `stdin` and
  * `stdout` of two extra file descriptors — rather than a WebSocket, because
- * Node 18 has no global WebSocket and this skill installs nothing. It uses
+ * Node 22 has no global WebSocket and this skill installs nothing. It uses
  * whatever Chrome the machine already has.
  *
  * Usage, from the project root:

package/skill/scripts/lib/rules.mjs

@@ -47,6 +47,10 @@ import {
 
 /** What each rule says, in one place. */
 const HINT = {
+  matchMediaNeverRuns:
+    "A matchMedia callback runs only while at least one of its named conditions matches, and a visitor with no reduced-motion preference matches none of these — so the branch for them is dead code and nothing animates. Add `motion: \"(prefers-reduced-motion: no-preference)\"` beside it, or use two separate `add` calls.",
+  stackedFrom:
+    "A `from` or `fromTo` applies its start state the moment it is built. Built more than once against the same element, the last one wins, and holds that element at its start state until the playhead reaches it — invisible, if the start state hides it. Pass `immediateRender: false`, and set the element's first state yourself with `gsap.set`.",
   orphanTween:
     "Nothing reverts it on unmount, and React StrictMode runs it twice in development. Move it into the useGSAP body, or wrap the handler in contextSafe. A helper counts as inside only when every use of it is a call from inside a context.",
   unmanagedInstance:
@@ -1598,4 +1602,315 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "matchmedia-never-runs",
+    level: "warn",
+    description:
+      "A matchMedia callback that branches on its conditions, when every condition needs reduced motion",
+    /**
+     * `mm.add({ reduced: "(prefers-reduced-motion: reduce)" }, (context) => …)`
+     * whose callback reads `context.conditions`. The callback runs only while a
+     * named condition matches, and a visitor with no preference matches none —
+     * so the branch written for them never runs, and neither does the
+     * animation in it. Found in a head-to-head test on a real hero, where the
+     * whole page shipped without motion.
+     *
+     * The reading of `conditions` is the whole signal. A reduced-only `add`
+     * that does not branch is GSAP's documented pattern for setting end states,
+     * meant to run for those visitors only, and is correct.
+     */
+    test(file) {
+      const REDUCE = /prefers-reduced-motion\s*:\s*reduce/i;
+
+      /** Names bound to `gsap.matchMedia()` in this file. */
+      const media = new Set(
+        findAll(
+          file.ast,
+          (node) =>
+            node.type === "VariableDeclarator" &&
+            node.id.type === "Identifier" &&
+            /**
+             * `let tl;` has no initializer, and `calleeName` does not accept
+             * null. Every fixture initialised its declarations, so 133 passing
+             * tests missed this; the first real project threw on it and took
+             * the whole audit down with it.
+             */
+            Boolean(node.init) &&
+            calleeName(unwrap(node.init)) === "gsap.matchMedia",
+        ).map((node) => node.id.name),
+      );
+
+      const onMatchMedia = (call) => {
+        const callee = unwrap(call.callee);
+        if (callee?.type !== "MemberExpression") return false;
+        const object = unwrap(callee.object);
+        if (object?.type === "Identifier") return media.has(object.name);
+        return calleeName(object) === "gsap.matchMedia";
+      };
+
+      /** Does the callback read the conditions it was handed? */
+      const branches = (fn) => {
+        const [param] = fn.params;
+        if (!param) return false;
+        if (param.type === "ObjectPattern") {
+          return param.properties.some((p) => keyName(p) === "conditions");
+        }
+        if (param.type !== "Identifier") return false;
+        return findAll(fn.body, (node) => {
+          const member = unwrap(node);
+          return (
+            member?.type === "MemberExpression" &&
+            !member.computed &&
+            unwrap(member.object)?.type === "Identifier" &&
+            unwrap(member.object).name === param.name &&
+            member.property.name === "conditions"
+          );
+        }).length > 0;
+      };
+
+      return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node))
+        .filter((call) => {
+          const conditions = unwrap(call.arguments[0]);
+          if (conditions?.type !== "ObjectExpression" || !conditions.properties.length) return false;
+          const everyReduces = conditions.properties.every((property) => {
+            const value = staticString(property.value);
+            return typeof value === "string" && REDUCE.test(value);
+          });
+          if (!everyReduces) return false;
+          const callback = resolveFunction(file.ast, call.arguments[1]);
+          return Boolean(callback) && branches(callback);
+        })
+        .map((call) => ({
+          index: call.start,
+          message:
+            "This matchMedia callback branches on its conditions, but every condition needs reduced motion — so it never runs for a visitor without that preference.",
+          hint: HINT.matchMediaNeverRuns,
+        }));
+    },
+  },
+  {
+    id: "stacked-from",
+    level: "warn",
+    description:
+      "A timeline's `from` or `fromTo` built more than once against the same target",
+    /**
+     * A `from` or `fromTo` on a timeline, without `immediateRender: false`,
+     * that is built more than once against the same element: written out
+     * twice, or inside a loop, or inside a helper a loop calls. Each applies
+     * its start state the moment it is built, so the last one wins and holds
+     * the element hidden until the playhead arrives. Found in a real hero,
+     * where one call site in a helper ran six times and a badge stayed
+     * invisible through the whole first state.
+     *
+     * Two shapes must stay quiet, and both sat in that same file. A target that
+     * varies with the loop — `forEach((card) => tl.from(card, …))` — is a new
+     * element each pass. And a tween inside a callback that is only passed
+     * along is not known to run each pass, so it is not reported.
+     */
+    test(file) {
+      const LOOPS = ["ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"];
+      const isLoopCallback = (fn) => {
+        const parent = parentOf(file.ast, fn);
+        return (
+          parent?.type === "CallExpression" &&
+          unwrap(parent.arguments[0]) === fn &&
+          ["forEach", "map", "flatMap"].includes(methodName(parent))
+        );
+      };
+      const renders = (call) =>
+        !call.arguments.some((arg) => {
+          const object = unwrap(arg);
+          return (
+            object?.type === "ObjectExpression" &&
+            object.properties.some((p) => {
+              const value = unwrap(p.value);
+              return keyName(p) === "immediateRender" && value?.type === "Literal" && value.value === false;
+            })
+          );
+        });
+
+      const paramNames = (fn) =>
+        fn.params.flatMap((param) =>
+          findAll(param, (n) => n.type === "Identifier").map((n) => n.name),
+        );
+      const loopNames = (loop) => {
+        const left = loop.left ?? loop.init;
+        return left ? findAll(left, (n) => n.type === "Identifier").map((n) => n.name) : [];
+      };
+
+      /** Is this node inside a loop body or a loop callback? */
+      const inLoop = (node) =>
+        ancestorsOf(file.ast, node).some((a) => LOOPS.includes(a.type) || (isFunction(a) && isLoopCallback(a)));
+
+      /**
+       * Walk out from the tween. The names that change each pass are gathered on
+       * the way; the walk stops at the first function that is neither a loop's
+       * own callback nor a named helper some loop calls, because nothing then
+       * says it runs more than once.
+       */
+      /**
+       * Does a guard on the way out pick exactly one pass? `key === "money"`
+       * does; `key !== "brand"` runs on most passes and still stacks. Only an
+       * equality against a literal, on a name that changes each pass, counts —
+       * the version of a real hero built without the skill guarded its one
+       * per-state tween that way, and a first version of this rule credited it
+       * with a bug it did not have.
+       */
+      const selectsOnePass = (guards, varying) =>
+        guards.some((test) =>
+          findAll(test, (node) => {
+            if (node.type !== "BinaryExpression" || !["===", "=="].includes(node.operator)) return false;
+            const sides = [unwrap(node.left), unwrap(node.right)];
+            const name = sides.find((side) => side?.type === "Identifier" && varying.has(side.name));
+            const literal = sides.find((side) => side?.type === "Literal");
+            return Boolean(name && literal);
+          }).length > 0,
+        );
+
+      /** Names that change each pass: its variable, and whatever its body declares. */
+      const declaredIn = (body) =>
+        body
+          ? findAll(body, (n) => n.type === "VariableDeclarator" && n.id.type === "Identifier").map((n) => n.id.name)
+          : [];
+
+      const repetition = (tween, timeline) => {
+        const varying = new Set();
+        const guards = [];
+        const settle = (loopBody) => {
+          declaredIn(loopBody).forEach((n) => varying.add(n));
+          return selectsOnePass(guards, varying) ? null : varying;
+        };
+        let inner = tween;
+        for (const ancestor of ancestorsOf(file.ast, tween)) {
+          if (contains(ancestor, timeline)) return null;
+          if ((ancestor.type === "IfStatement" || ancestor.type === "ConditionalExpression") && contains(ancestor.consequent, inner)) {
+            guards.push(ancestor.test);
+          }
+          inner = ancestor;
+          if (LOOPS.includes(ancestor.type)) {
+            loopNames(ancestor).forEach((n) => varying.add(n));
+            return settle(ancestor.body);
+          }
+          if (!isFunction(ancestor)) continue;
+          paramNames(ancestor).forEach((n) => varying.add(n));
+          if (isLoopCallback(ancestor)) return settle(ancestor.body);
+
+          const holder = parentOf(file.ast, ancestor);
+          const name =
+            holder?.type === "VariableDeclarator" && holder.id.type === "Identifier"
+              ? holder.id.name
+              : ancestor.type === "FunctionDeclaration"
+                ? ancestor.id?.name
+                : null;
+          if (!name) return null;
+          const calledInLoop = findAll(
+            file.ast,
+            (n) =>
+              n.type === "CallExpression" &&
+              unwrap(n.callee)?.type === "Identifier" &&
+              unwrap(n.callee).name === name &&
+              inLoop(n),
+          ).length > 0;
+          return calledInLoop ? varying : null;
+        }
+        return null;
+      };
+
+      /**
+       * The properties a tween's start state sets, or null when they cannot be
+       * read. "Last one wins" is per property: two from-tweens on one element
+       * that set different properties hide nothing, and a real project relied on
+       * exactly that — a line flying in on `opacity` and `y` while a second tween
+       * turned it on `rotationY`. `autoAlpha` sets opacity, so they count as one.
+       */
+      const CONFIG = new Set([
+        "duration", "delay", "ease", "stagger", "repeat", "yoyo", "repeatDelay",
+        "immediateRender", "overwrite", "paused", "id", "data", "callbackScope",
+        "onStart", "onUpdate", "onComplete", "onRepeat", "onReverseComplete", "scrollTrigger",
+      ]);
+      const startKeys = (tween) => {
+        const vars = unwrap(tween.arguments[1]);
+        if (vars?.type !== "ObjectExpression") return null;
+        if (vars.properties.some((p) => p.type !== "Property" || p.computed)) return null;
+        return new Set(
+          vars.properties
+            .map((p) => keyName(p))
+            .filter((key) => key && !CONFIG.has(key))
+            .map((key) => (key === "autoAlpha" ? "opacity" : key)),
+        );
+      };
+      const overlap = (a, b) => {
+        if (!a || !b) return false;
+        for (const key of a) if (b.has(key)) return true;
+        return false;
+      };
+
+      /**
+       * Two calls that cannot both run: opposite branches of one `if` or one
+       * ternary, or two cases of one `switch`. A real project built a fade-in in
+       * the `if` and a fade-out in the `else` against the same element, and only
+       * ever ran one of them.
+       */
+      const exclusive = (a, b) => {
+        const upB = new Set(ancestorsOf(file.ast, b));
+        for (const node of ancestorsOf(file.ast, a)) {
+          if (!upB.has(node)) continue;
+          if ((node.type === "IfStatement" || node.type === "ConditionalExpression") && node.alternate) {
+            if (contains(node.alternate, a) !== contains(node.alternate, b)) return true;
+          }
+          if (node.type === "SwitchStatement") {
+            const caseOf = (n) => node.cases.find((c) => contains(c, n));
+            if (caseOf(a) && caseOf(a) !== caseOf(b)) return true;
+          }
+        }
+        return false;
+      };
+
+      const mentions = (text, names) =>
+        [...names].some((name) => new RegExp(`(^|[^\\w$])${name.replace(/\$/g, "\\$")}([^\\w$]|$)`).test(text));
+
+      const findings = [];
+      const timelines = findAll(file.ast, (node) => calleeName(node) === "gsap.timeline");
+      for (const timeline of timelines) {
+        const tweens = timelineLinks(file.ast, timeline).filter(
+          (call) => ["from", "fromTo"].includes(methodName(call)) && call.arguments[0] && renders(call),
+        );
+        const reported = new Set();
+        /** Earlier from-tweens on each target, to compare a later one against. */
+        const earlier = new Map();
+
+        for (const tween of tweens) {
+          const target = unwrap(tween.arguments[0]);
+          const text = file.raw.slice(target.start, target.end).replace(/\s+/g, "");
+          if (reported.has(text)) continue;
+
+          /** One call site built repeatedly always shares its own properties. */
+          const varying = repetition(tween, timeline);
+          const repeatedInPlace = varying !== null && !mentions(text, varying);
+
+          const keys = startKeys(tween);
+          const before = earlier.get(text) ?? [];
+          const writtenTwice = before.some(
+            (other) => !exclusive(other.tween, tween) && overlap(other.keys, keys),
+          );
+          earlier.set(text, [...before, { tween, keys }]);
+
+          if (repeatedInPlace || writtenTwice) {
+            reported.add(text);
+            findings.push({
+              /**
+               * The method's own position, not the call's. A chained call starts
+               * where its chain starts, so `tween.start` pointed a real report 25
+               * lines above the `fromTo` it was about.
+               */
+              index: unwrap(tween.callee)?.property?.start ?? tween.start,
+              message: `\`${text}\` gets a \`${methodName(tween)}\` more than once on this timeline, and each applies its start state as soon as it is built.`,
+              hint: HINT.stackedFrom,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
 ];

package/skill/scripts/patterns.mjs

@@ -17,7 +17,7 @@
  * 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.
+ * Node.js 22+, no dependencies.
  */
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";

package/skill/scripts/review-motion.mjs

@@ -19,7 +19,7 @@
  * 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.
+ * Node.js 22+, no dependencies, whatever Chrome the machine already has.
  */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";