@mehshekari/gsap-motion 3.1.1 → 3.3.0

package/README.md

@@ -28,7 +28,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.1.1 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.3.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -257,6 +257,23 @@ function doctor() {
     );
   }
 
+  /**
+   * Which adapters the skill loads here, read the way SKILL.md's setup step 3
+   * describes. Deterministic, so the stack is looked up rather than guessed.
+   */
+  const picked = new Set();
+  if (deps.next) picked.add("react").add("next");
+  if (deps["@react-three/fiber"]) picked.add("react").add("r3f");
+  else if (deps.three) picked.add("three");
+  if (deps.react) picked.add("react");
+  if (deps.vue || deps.nuxt) picked.add("vue");
+  if (deps.svelte || deps["@sveltejs/kit"]) picked.add("svelte");
+  if (deps.astro) picked.add("astro");
+  if (picked.size === 0) picked.add("vanilla");
+
+  const ORDER = ["react", "next", "r3f", "three", "vue", "svelte", "astro", "vanilla"];
+  report("ok", `Adapters: ${ORDER.filter((name) => picked.has(name)).join(", ")}`);
+
   const rules = existsSync(join(process.cwd(), "ANIMATION.md"));
   report(
     rules ? "ok" : "info",

package/package.json

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

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "3.1.1"
+  version: "3.3.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -18,8 +18,8 @@ Core principles:
 
 - **Motion carries meaning or it goes.** Every animation answers "what does
   this tell the visitor?" Hierarchy, causality, continuity, state, or
-  personality. An animation that answers none of those is decoration with a
-  frame cost, and the right move is to delete it.
+  personality. One that answers none of those is decoration with a frame cost:
+  delete it.
 - **A timeline, not a pile of tweens.** Five independent tweens with hand-tuned
   delays is a choreography nobody can change. One timeline with labels and
   relative positions is the same animation you can actually retime.
@@ -33,23 +33,27 @@ Core principles:
 
 ## Setup
 
-1. **Everything is free.** GSAP became 100% free, every former Club plugin
-   included, with 3.13 (April 2025). Check `package.json` for what the project
-   has — `gsap`, and `@gsap/react` for React — before writing imports. Install
-   steps for a membership, a token, an `.npmrc` or `gsap-bonus.tgz` come from
-   stale training data: stop.
+1. **Everything is free.** GSAP became 100% free with 3.13 (April 2025), every
+   former Club plugin included. Check `package.json` for what the project has —
+   `gsap`, and `@gsap/react` for React — before writing imports. Install steps
+   for a membership, a token, an `.npmrc` or `gsap-bonus.tgz` are stale
+   training data: stop.
 2. **Read the project's own animation rules first. They outrank this skill.**
-   Look for `ANIMATION.md` at the repository root, then for a file that
-   `AGENTS.md`, `CLAUDE.md` or similar points to. Open
+   Look for `ANIMATION.md` at the root, then a file `AGENTS.md`, `CLAUDE.md` or
+   similar points to. Open
    [reference/project-rules.md](reference/project-rules.md) only when there is
-   no such file, or for its RTL, colour and waiver rules.
+   none, or for its RTL, colour and waiver rules.
 3. **Load by the size of the request, and nothing "for completeness".**
    - **One element, one tween or interaction** — a hover, a fade, a retime:
      [motion-design.md](reference/motion-design.md) and the command's own
      reference. Nothing else.
-   - **A component or section:** also
-     [react-nextjs.md](reference/react-nextjs.md) if `package.json` has
-     `react`, or [frameworks.md](reference/frameworks.md) if it does not.
+   - **A component or section:** also this project's adapter, from
+     `package.json`: `next` → [react](adapter/react.md) +
+     [next](adapter/next.md); `@react-three/fiber` → react +
+     [r3f](adapter/r3f.md); `three` → [three](adapter/three.md); `nuxt` →
+     [vue](adapter/vue.md); `svelte` → [svelte](adapter/svelte.md); `astro` →
+     [astro](adapter/astro.md) plus any island's own; nothing detected →
+     [vanilla](adapter/vanilla.md).
    - **A sequence, scroll scene, intro, transition or audit:** also
      [core-gsap.md](reference/core-gsap.md), and what
      [routing.md](reference/routing.md) adds for that request.
@@ -68,7 +72,7 @@ Core principles:
 | `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 | [reference/three-r3f.md](reference/three-r3f.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) |
@@ -76,12 +80,11 @@ Core principles:
 Routing:
 
 - **No argument, or no target:** read [routing.md](reference/routing.md) and
-  ask what should move. A whole page or site with nothing in it named — "add
-  some animation to my homepage" — has no target. Never invent one.
-- **An explicit or clearly implied command:** load its reference and follow it.
-- **A description rather than a command** ("make this feel like Apple", "the
-  hero is boring"): that is `animate`. Classify the intent with routing.md's
-  table, then load what that classification needs.
+  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.
 - **Two commands fit:** ask once. A scroll-driven text reveal is `scroll` and
   `text` together, not a coin toss.
 
@@ -109,7 +112,8 @@ intent → precedent → targets → trigger → motion language → technique
 8. **Implementation** — typed, cleaned up, responsive.
 9. **Performance** — transform and opacity; measure before defending anything else.
 10. **Accessibility** — the reduced-motion design, focus, keyboard.
-11. **Validate** — the checklist at the end of [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
 
@@ -122,26 +126,29 @@ For anything beyond a one-line tweak, answer in this shape, each part short:
 - **Implementation** — complete code. Not pseudocode, not an outline.
 - **Usage** — how to mount it.
 - **Notes** — responsive behaviour, reduced motion, cost, dev-only tooling.
+- **Verification** — one line per check with its evidence, and what you did not
+  check. Silence reads as "checked and fine".
 
-When a simpler technique does what the user asked for, **write only the
-simpler one**. Say in Analysis which technique you declined and why, and offer
-the requested version in one sentence; write it only if the user still wants it
-after that. Never quietly substitute, and never ship both.
+When a simpler technique does what was asked, **write only that one**. Say in
+Analysis what you declined and why, and offer the requested version in a
+sentence — write it only if they still want it. Never substitute quietly, and
+never ship both.
 
 ## Reference map
 
 - **Craft and core** — [motion-design](reference/motion-design.md) ·
-  [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md)
+  [core-gsap](reference/core-gsap.md) · [timeline](reference/timeline.md) ·
+  [devices](reference/devices.md) · [refine](reference/refine.md)
 - **Domains** — [scrolltrigger](reference/scrolltrigger.md) ·
   [svg](reference/svg.md) · [text](reference/text.md) ·
-  [interaction](reference/interaction.md) · [flip](reference/flip.md) ·
-  [three-r3f](reference/three-r3f.md)
-- **Constraints** — [react-nextjs](reference/react-nextjs.md) ·
-  [frameworks](reference/frameworks.md) ·
-  [performance](reference/performance.md) ·
+  [interaction](reference/interaction.md) · [flip](reference/flip.md)
+- **Adapters**, one per stack, chosen in setup step 3 — the same questions for
+  each: lifecycle, scope, server rendering, per-frame values, routes, failures,
+  audit.
+- **Constraints** — [performance](reference/performance.md) ·
   [accessibility](reference/accessibility.md) ·
   [project-rules](reference/project-rules.md)
-- **Presets**, starting points to adapt — [reveal](preset/reveal.md) ·
+- **Presets** to adapt — [reveal](preset/reveal.md) ·
   [magnetic](preset/magnetic.md) · [cursor](preset/cursor.md) ·
   [marquee](preset/marquee.md) · [card-stack](preset/card-stack.md) ·
   [loader](preset/loader.md) · [cinematic](preset/cinematic.md) ·
@@ -156,13 +163,12 @@ after that. Never quietly substitute, and never ship both.
 
 ## Tools
 
-Both scripts catch failures that are **silent**. Run them from the project
-root; `<skill-dir>` is where this skill is installed.
+Both scripts catch **silent** failures. Run them from the project root;
+`<skill-dir>` is where this skill is installed.
 
 ```bash
-# Leaks, per-event tweens, layout properties, eased loops, an onComplete that
-# never fires, shared plugin ids, unregistered plugins, dev tooling left in.
-# Exit 1 on an error.
+# Leaks, per-event and per-frame tweens, layout and paint properties, loops,
+# shared plugin ids, unregistered plugins, dev tooling. Exit 1 on an error.
 node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
 node <skill-dir>/scripts/audit-gsap.mjs src --quiet   # errors only
 node <skill-dir>/scripts/audit-gsap.mjs src --json    # machine-readable
@@ -173,10 +179,11 @@ node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
 node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>   # also flag hue literals
 ```
 
-Run `audit-gsap` first in an `audit` and after writing any animation. A false
-finding is a bug in the script, not something to work around.
+Run `audit-gsap` first in an `audit` and after writing any animation — as a
+Claude Code plugin, a hook already runs it on every edit and hands back what it
+finds. A false finding is a bug in the script, not something to work around.
 
 `MotionPathHelper`, `GSDevTools`, `markers: true` and
-`MorphSVGPlugin.findShapeIndex()` are development-only. A static import ships
-whatever `if` surrounds it: import them dynamically behind a `NODE_ENV` check,
-and delete the block once their value is baked in.
+`MorphSVGPlugin.findShapeIndex()` are development-only, and a static import
+ships whatever `if` surrounds it. Import them dynamically behind a `NODE_ENV`
+check, and delete the block once their value is baked in.

package/skill/adapter/astro.md

@@ -0,0 +1,111 @@
+# Astro
+
+Astro ships no JavaScript unless you ask for it, and its pages can be swapped
+without a reload. Both facts decide where an animation lives.
+
+## Where it is created
+
+In a component's `<script>`, which Astro bundles and defers. With view
+transitions enabled, a page swap does not re-run it, so build on the page-load
+event rather than at the top level:
+
+```astro
+<script>
+  import gsap from "gsap";
+
+  let ctx;
+
+  document.addEventListener("astro:page-load", () => {
+    ctx = gsap.context(() => {
+      gsap.from("[data-item]", { autoAlpha: 0, y: 24, stagger: 0.06 });
+    });
+  });
+
+  document.addEventListener("astro:before-swap", () => ctx?.revert());
+</script>
+```
+
+`astro:page-load` fires on the first load and after every swap, so this one
+shape covers both. Without view transitions the event still fires once, so the
+same code is correct either way.
+
+Inside a React, Vue or Svelte island, use that framework's adapter instead —
+the island owns its own lifecycle.
+
+## Where it is torn down
+
+`astro:before-swap`, with `ctx.revert()`. Skipping it leaves the previous page's
+ScrollTriggers and listeners bound to elements that are about to be replaced,
+and they accumulate for as long as the visit lasts.
+
+Timers, listeners and observers are yours, in the same handler.
+
+## Scope
+
+Astro's `<script>` is page-wide, not component-scoped: a component used twice on
+a page runs its script once, and selector strings match both instances. Either
+animate them as a set — which is usually what you want — or pass the root in
+with a `data-*` attribute and build one context per matching element.
+
+Plugin config is not scoped either, so generate ids per instance rather than
+hardcoding them.
+
+## Server rendering and hydration
+
+Astro components render to HTML on the server and ship no client JavaScript of
+their own, so there is no hydration to mismatch. The script runs only in the
+browser: reading `window` in it is safe, and the markup it animates is already
+painted.
+
+`client:*` directives decide when an island hydrates. An animation inside one
+does not run until it does — `client:visible` on a section that animates on
+entrance is a race worth avoiding; prefer `client:load` there, or keep the
+animation in the page's own script.
+
+## Reaching the element
+
+`data-*` attributes in the markup, queried inside the context. Astro scopes its
+component styles by adding its own attributes to elements, so a class in the
+markup is not always the class in the DOM — a `data-*` attribute you wrote is.
+
+## Every frame
+
+`gsap.quickTo` or `quickSetter`, created once inside the context. There is no
+component state here to get wrong, which removes the most common React mistake
+and leaves the ordinary one: allocating a tween per event.
+
+## Page and route changes
+
+The events are the contract:
+
+- `astro:page-load` — build, on first load and after every swap
+- `astro:before-swap` — revert, before the old page goes
+- `astro:after-swap` — for anything that must run against the new DOM before it
+  paints, such as `ScrollTrigger.refresh()`
+
+View transitions are opt-in: they come from Astro's router component in the
+layout, named `<ClientRouter />` in current versions and `<ViewTransitions />`
+in older ones. Check which one the project imports before telling anyone to add
+it.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Animation runs on the first page only | built at the top of `<script>` instead of on `astro:page-load` |
+| Triggers pile up while browsing | no `astro:before-swap` revert |
+| The script never runs | `is:inline`, which skips bundling, so the bare import fails |
+| Both instances animate as one | a page-wide script with a document-wide selector |
+| An entrance animation starts late | the island hydrates on `client:visible` |
+
+## What the audit covers
+
+From 3.2 the audit reads the `<script>` block of `.astro` files, with offsets
+kept, so reported lines match the file. It checks that a context built on
+`astro:page-load` is reverted on `astro:before-swap`, along with every rule that
+is not React-specific.
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `astro@7`; the swap events are the
+same in Astro 5 and later, though the router component was renamed.

package/skill/adapter/next.md

@@ -0,0 +1,99 @@
+# Next.js
+
+The App Router, with Server Components. Read [react.md](react.md) first: this is
+only what Next adds.
+
+## Where it is created
+
+In a `"use client"` component, in the `useGSAP` body react.md describes. Keep
+that component a **leaf**, so the page above it stays a Server Component.
+
+**Converting a Server Component is part of the cost, and it is priced before the
+design.** *Is GSAP already on this route?* If a sibling section loads `gsap` and
+`ScrollTrigger`, the marginal cost is this component's own JavaScript — a
+kilobyte or two rather than thirty-odd, which usually settles the argument. If
+nothing on the route loads GSAP, this animation buys the whole library for one
+reveal. *Does anything claim otherwise?* A comment saying the section ships no
+client JavaScript stops being true the moment you add the hook; update it in the
+same change.
+
+Say so in the Notes of your answer: "it becomes a client component" is a fact
+the reader needs.
+
+## Where it is torn down
+
+By the context, as in react.md. A navigation unmounts the page, so anything that
+must survive one belongs in the layout.
+
+## Scope
+
+As in react.md, and `useId` matters more here: the markup is rendered on the
+server and again on the client, and a counter would disagree between them.
+
+## Server rendering and hydration
+
+- **`"use client"` module scope still runs during server rendering.**
+  Registering plugins there is fine — GSAP defers anything touching `window` —
+  but reading `window` or `document` at module scope is not.
+- **Data and copy come down as props.** A client component importing a content
+  or locale module bundles every locale into the browser payload. Large
+  generated data — path tables, keyframe sets — is handed down too.
+- Storage and media queries are read after mount, never during render.
+
+## Reaching the element
+
+`next/image` renders the `<img>` itself and controls its `src`, `srcset` and
+sizing:
+
+- **Animate a wrapper you own**, not the image, when the effect needs a mask, a
+  clip or a transform that must survive the placeholder-to-loaded swap. Under
+  `fill` the image is positioned against the nearest positioned ancestor, so
+  that wrapper is already there.
+- **A reveal that depends on the image waits for load**, with a short budget
+  after which it plays anyway. A cached image can finish before the hook runs,
+  and a mask opening over an empty box reads as a bug.
+- If the animation starts by hiding a hero image, **measure what it does to
+  LCP** first. A mask over an image that is already painted usually avoids the
+  question.
+
+## Every frame
+
+Refs and `quickTo`, never React state — and it costs more here, since state held
+in a layout re-renders every page under it.
+
+## Page and route changes
+
+The App Router unmounts the old tree before the new one paints, so an exit
+animation has nowhere to play. Options, by cost:
+
+1. **Animate entrance only**, keyed off `usePathname()`. Honest, cheap, and what
+   most sites want.
+2. **An overlay that outlives the route**, mounted in the layout so the
+   navigation does not unmount it. See
+   [page-transition](../preset/page-transition.md).
+3. **`router.push` behind a played-out timeline** — intercept, play the exit,
+   navigate on complete. Breaks the back button's feel; use sparingly.
+
+Then `ScrollTrigger.refresh()` once the new layout settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| `window is not defined` during a build | `window` read at module scope in a client component |
+| Hydration mismatch | storage, a media query or a random value read during render |
+| The whole page ships as client JavaScript | `"use client"` on the page or layout instead of a leaf |
+| A reveal opens over an empty box | the tween did not wait for the image to load |
+| Positions are wrong after a navigation | no `ScrollTrigger.refresh()` once it settled |
+| The exit animation never plays | written in the page the navigation unmounts |
+
+## What the audit covers
+
+The React rules from react.md, on the same files. It reads `.ts`, `.tsx`, `.js`,
+`.jsx` and `.mjs`, so `"use client"` placement, `next.config` and route
+structure are yours to review.
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for `next@15` and
+`next@16`, App Router.

package/skill/adapter/r3f.md

@@ -0,0 +1,128 @@
+# React Three Fiber
+
+R3F is React's renderer for Three, so both lifecycles apply: read
+[react.md](react.md) for the context and cleanup rules, and
+[three.md](three.md) for what GSAP may tween on a Three object. This file is the
+part that is neither.
+
+## Where it is created
+
+In a `useGSAP` body inside the `<Canvas>` subtree, against refs to the objects:
+
+```tsx
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+import type { Mesh } from "three";
+
+export function Box() {
+  const mesh = useRef<Mesh>(null);
+
+  useGSAP(() => {
+    if (!mesh.current) return;
+    gsap.to(mesh.current.rotation, {
+      y: Math.PI * 2,
+      duration: 6,
+      ease: "none",
+      repeat: -1,
+    });
+  });
+
+  return (
+    <mesh ref={mesh}>
+      <boxGeometry />
+      <meshStandardMaterial />
+    </mesh>
+  );
+}
+```
+
+A camera move is where GSAP earns its place — easing a camera by hand is how
+scroll-driven 3D ends up feeling mechanical:
+
+```ts
+const { camera, invalidate } = useThree();
+
+gsap.timeline({ defaults: { ease: "power2.inOut", duration: 2 } })
+  .to(camera.position, { x: 0, y: 1.5, z: 4 })
+  .to(camera.rotation, { x: -0.2 }, "<");
+```
+
+## Where it is torn down
+
+The `useGSAP` context reverts the tweens, as in react.md.
+
+R3F disposes what it created for elements it rendered, when they unmount.
+Anything you built yourself — a geometry, material or texture made outside JSX,
+a loader's result you cached — is yours to dispose.
+
+## Scope
+
+There are no selector strings here: targets are refs. `{ scope: root }` still
+matters for any DOM overlay the component renders beside the canvas.
+
+## Server rendering and hydration
+
+The canvas is client-only. Import the component dynamically so Three is not in
+the initial bundle, and render a fallback while it loads — that fallback is also
+the reduced-motion and low-power design, so it is not wasted work.
+
+## Reaching the element
+
+Refs, held where the object is declared. `useThree` reaches the camera, the
+renderer and the scene without prop-drilling. Traversing by name binds to the
+exporter's names, which the next export changes.
+
+## Every frame
+
+**Never drive a 3D transform through React state.** `useState` per frame
+re-renders the React tree for a value Three reads directly. Refs and GSAP only.
+
+`useFrame` and GSAP are complementary, not competing: `useFrame` for continuous
+logic that follows the clock, GSAP for transitions between states. Inside
+`useFrame`, the rules are the ones for any per-frame scope — no allocation, no
+state, no `setState` from a callback.
+
+With `frameloop="demand"`, the canvas renders only when something asks it to, so
+a GSAP tween that changes a Three value must ask:
+
+```ts
+gsap.to(mesh.current.position, { y: 1, onUpdate: invalidate });
+```
+
+Without that, the tween runs and nothing is drawn — the most confusing failure
+in this file, because every value is correct.
+
+## Page and route changes
+
+The canvas unmounts with the route, and R3F disposes its own objects. What
+survives is anything you created outside JSX, plus any ScrollTrigger built
+against a DOM element that is now gone — which the context reverts, provided it
+was created inside the body.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Values change but nothing is drawn | `frameloop="demand"` with no `invalidate` from `onUpdate` |
+| The whole tree re-renders while animating | 3D values held in React state |
+| Nothing moves | tweened the object instead of `object.position` / `.rotation` |
+| The tween starts before the object exists | no early return on a null ref |
+| Memory grows across route changes | objects created outside JSX, never disposed |
+| Scroll-driven camera drifts out of sync | a scrub with an ease on a child, instead of `ease: "none"` |
+
+## What the audit covers
+
+The React rules from react.md, since these are `.tsx` files. From 3.2,
+`useFrame` counts as a per-frame scope, so React state set inside it is reported
+as `state-per-event`.
+
+Disposal, GPU cost and the render loop are not checkable — read for them, and
+measure with [performance.md](../reference/performance.md).
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for
+`@react-three/fiber@8` and `@react-three/fiber@9`.