@mehshekari/gsap-motion 3.5.0 → 4.1.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
 
@@ -23,7 +23,8 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `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`. |
-| `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. |
+| `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` | `--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
 
@@ -31,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.5.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.0.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -10,6 +10,7 @@
  *   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>`.
@@ -94,7 +95,12 @@ Commands
     --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
+    --json              Machine-readable output
   --version             Print the version
 
 Docs: https://github.com/mehShekari/gsap-motion`;
@@ -212,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");
@@ -305,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);
@@ -335,8 +417,11 @@ switch (command) {
   case "review":
     runScript("review-motion.mjs", args);
     break;
+  case "patterns":
+    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.5.0",
+  "version": "4.1.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.5.0"
+  version: "4.1.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
 
@@ -101,8 +93,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,14 +104,15 @@ 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
 
 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/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

@@ -83,10 +83,95 @@ 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.
+
+### `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
 
 Each of these fails silently in any project that has the condition.

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/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/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 22+, 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

@@ -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";