@mehshekari/gsap-motion 3.6.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
 
@@ -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.0.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.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.6.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
 
@@ -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/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/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

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