@mehshekari/gsap-motion 3.1.1 → 3.3.0

package/skill/reference/routing.md

@@ -1,119 +1,136 @@
-# Routing
-
-What to load, and what to do when the request is a feeling rather than a
-command.
-
-## No argument
-
-Do not guess a target and do not invent an animation. Ask what should move, and
-offer the menu below — grouped, so the question is easy to answer.
-
-> What are we animating?
->
-> - **Entrance** — something appearing: a hero, a section, a list, an image
-> - **Scroll** — something driven by scroll position: a sequence, a pin, a
->   horizontal run
-> - **Interaction** — something answering the pointer: a button, a cursor, a
->   card
-> - **Continuous** — something always moving: a marquee, an orbit, ambient drift
-> - **Transition** — moving between two states: a route, a modal, a layout
-> - **Loading** — a loader, a progress indicator, a site intro
-> - **Existing** — something already animated that feels wrong, costs too much,
->   or should go
-
-## Classifying a description
-
-Most requests are a feeling, not a command. Classify, then route.
-
-| What they say | What they mean | 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 |
-| "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"
-
-A fade-and-scale is a failure of nerve; twelve techniques at once is a failure
-of taste. Pick **one concept** and let three techniques serve it. The concept is
-the thing you can say in a sentence — "the logo writes itself, then the dot that
-drew it runs off and writes the word" — and every technique either serves that
-sentence or is cut.
-
-## Load map
-
-The project's own rules come first, then the size tiers in SKILL.md, setup step
-3: a one-element change loads [motion-design](motion-design.md) and the
-command's own reference only. The table applies from component size up — a
-single hover takes [interaction](interaction.md) and nothing else from its row.
-
-| Request | Add |
-|---|---|
-| SVG draw / morph / path | [svg](svg.md), [timeline](timeline.md) |
-| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md) |
-| Horizontal scroll | [scrolltrigger](scrolltrigger.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
-| Text reveal, kinetic type | [text](text.md), [timeline](timeline.md) |
-| Magnetic, cursor, hover | [interaction](interaction.md), [performance](performance.md) |
-| Drag, flick, inertia | [interaction](interaction.md) |
-| Layout / shared element / modal | [flip](flip.md) |
-| Page or route transition | [flip](flip.md), [page-transition](../preset/page-transition.md), [react-nextjs](react-nextjs.md) or [frameworks](frameworks.md) |
-| Loader, splash, intro | [svg](svg.md), [timeline](timeline.md), [accessibility](accessibility.md) |
-| Marquee, orbit, ambient | [timeline](timeline.md), [performance](performance.md) |
-| Three.js / R3F | [three-r3f](three-r3f.md), [performance](performance.md) |
-| Audit an existing animation | [performance](performance.md), [accessibility](accessibility.md), [react-nextjs](react-nextjs.md) or [frameworks](frameworks.md) |
-| Retime / re-ease | [motion-design](motion-design.md) only |
-
-Do not load a domain file "for completeness". Loading `three-r3f.md` for a
-button hover is the failure this map exists to prevent.
-
-## `audit`
-
-**Run the checker first.** It is deterministic, it costs a second, and it finds
-the mechanical failures before you spend attention on them:
-
-```bash
-node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
-```
-
-**When an animation is not visible, ask whether it was ever built.** Before
-touching timings or transforms, check that the code which creates it actually
-runs. Animation is routinely built behind a condition — an image decode race, a
-`ready.then()`, a ScrollTrigger that has not fired, a `matchMedia` branch that
-does not match, an early `return` on a missing ref — and a tween that was never
-created looks exactly like one that is mis-timed. A typical case: an image wipe
-added only once the image decodes inside a short budget. On a first visit the
-image is never cached, the branch never runs, and every hypothesis about the
-wipe's geometry is wasted effort.
-
-Then read for what it cannot see. Check in this order — the first two are where
-real bugs live:
-
-1. **Lifecycle** — is every animation inside a `useGSAP`/`gsap.context` scope?
-   Are ScrollTriggers killed? Are listeners removed? Does a `matchMedia` get
-   reverted? See [react-nextjs](react-nextjs.md).
-2. **Cost** — layout-triggering properties, per-frame React state, filters on
-   large areas, one ScrollTrigger per item where one would do. See
-   [performance](performance.md).
-3. **Reduced motion** — is there a branch, and does it still communicate?
-4. **Craft** — rhythm, easing on loops, contrast. See [motion-design](motion-design.md).
-
-Report findings most-severe first, with the file and line. Do not rewrite
-unless asked.
-
-## `strip`
-
-Removing motion is a legitimate outcome and often the right one. Cut an
-animation when it answers none of hierarchy, causality, continuity, state, or
-personality; when it delays content the visitor came for; when it repeats on
-every route and stopped being noticed on the second one; or when it exists
-because a plugin was available.
-
-Say what you removed and what it was costing. Do not replace it with a smaller
-animation unless the user asks.
+# Routing
+
+What to load, and what to do when the request is a feeling rather than a
+command.
+
+## No argument
+
+Do not guess a target and do not invent an animation. Ask what should move, and
+offer the menu below — grouped, so the question is easy to answer.
+
+> What are we animating?
+>
+> - **Entrance** — something appearing: a hero, a section, a list, an image
+> - **Scroll** — something driven by scroll position: a sequence, a pin, a
+>   horizontal run
+> - **Interaction** — something answering the pointer: a button, a cursor, a
+>   card
+> - **Continuous** — something always moving: a marquee, an orbit, ambient drift
+> - **Transition** — moving between two states: a route, a modal, a layout
+> - **Loading** — a loader, a progress indicator, a site intro
+> - **Existing** — something already animated that feels wrong, costs too much,
+>   or should go
+
+## Classifying a description
+
+Most requests are a feeling, not a command. Classify, then route.
+
+| What they say | What they mean | 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 |
+| "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"
+
+A fade-and-scale is a failure of nerve; twelve techniques at once is a failure
+of taste. Pick **one concept** and let three techniques serve it. The concept is
+the thing you can say in a sentence — "the logo writes itself, then the dot that
+drew it runs off and writes the word" — and every technique either serves that
+sentence or is cut.
+
+## The technique ladder
+
+Start at the bottom, and each rung up says why the one below is not enough:
+
+1. **A CSS transition** — one property, one state change, no sequencing.
+2. **One transform tween** — it needs an ease or a duration CSS cannot say.
+3. **A timeline** — two or more things must be ordered or overlapped.
+4. **A plugin** — the shape needs it: draw, morph, path, split. Its weight ships
+   to every visitor.
+5. **A scroll takeover** — the scroll position *is* the story. It takes the
+   visitor's control of the page, so it needs the strongest reason of all.
+
+Say the rung in Analysis: "a transition would not sequence these, so this is a
+timeline". A plugin named without that sentence is one nobody justified.
+
+## Load map
+
+The project's own rules come first, then the size tiers in SKILL.md, setup step
+3: a one-element change loads [motion-design](motion-design.md) and the
+command's own reference only. The table applies from component size up — a
+single hover takes [interaction](interaction.md) and nothing else from its row.
+
+| Request | Add |
+|---|---|
+| SVG draw / morph / path | [svg](svg.md), [timeline](timeline.md) |
+| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md) |
+| Horizontal scroll | [scrolltrigger](scrolltrigger.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
+| Text reveal, kinetic type | [text](text.md), [timeline](timeline.md) |
+| Magnetic, cursor, hover | [interaction](interaction.md), [performance](performance.md) |
+| Drag, flick, inertia | [interaction](interaction.md) |
+| Layout / shared element / modal | [flip](flip.md) |
+| Page or route transition | [flip](flip.md), [page-transition](../preset/page-transition.md), this project's adapter |
+| Loader, splash, intro | [svg](svg.md), [timeline](timeline.md), [accessibility](accessibility.md) |
+| Marquee, orbit, ambient | [timeline](timeline.md), [performance](performance.md) |
+| Three.js / R3F | [three](../adapter/three.md) or [r3f](../adapter/r3f.md), [performance](performance.md) |
+| Audit an existing animation | [performance](performance.md), [accessibility](accessibility.md), this project's adapter |
+| Retime / re-ease | [motion-design](motion-design.md) only |
+| Hover, touch or reduced-motion branching | [devices](devices.md) |
+| Fixing what an audit found | [refine](refine.md) |
+
+Do not load a domain file "for completeness". Loading `adapter/three.md` for a
+button hover is the failure this map exists to prevent.
+
+## `audit`
+
+**Run the checker first.** It is deterministic, it costs a second, and it finds
+the mechanical failures before you spend attention on them:
+
+```bash
+node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
+```
+
+**When an animation is not visible, ask whether it was ever built.** Before
+touching timings or transforms, check that the code which creates it actually
+runs. Animation is routinely built behind a condition — an image decode race, a
+`ready.then()`, a ScrollTrigger that has not fired, a `matchMedia` branch that
+does not match, an early `return` on a missing ref — and a tween that was never
+created looks exactly like one that is mis-timed. A typical case: an image wipe
+added only once the image decodes inside a short budget. On a first visit the
+image is never cached, the branch never runs, and every hypothesis about the
+wipe's geometry is wasted effort.
+
+Then read for what it cannot see. Check in this order — the first two are where
+real bugs live:
+
+1. **Lifecycle** — is every animation inside a `useGSAP`/`gsap.context` scope?
+   Are ScrollTriggers killed? Are listeners removed? Does a `matchMedia` get
+   reverted? See this project's adapter.
+2. **Cost** — layout-triggering properties, per-frame React state, filters on
+   large areas, one ScrollTrigger per item where one would do. See
+   [performance](performance.md).
+3. **Reduced motion** — is there a branch, and does it still communicate?
+4. **Craft** — rhythm, easing on loops, contrast. See [motion-design](motion-design.md).
+
+Report findings most-severe first, with the file and line. Do not rewrite
+unless asked.
+
+## `strip`
+
+Removing motion is a legitimate outcome and often the right one. Cut an
+animation when it answers none of hierarchy, causality, continuity, state, or
+personality; when it delays content the visitor came for; when it repeats on
+every route and stopped being noticed on the second one; or when it exists
+because a plugin was available.
+
+Say what you removed and what it was costing. Do not replace it with a smaller
+animation unless the user asks.

package/skill/reference/scrolltrigger.md

@@ -176,7 +176,7 @@ useGSAP(() => {
 
 After a route change in the App Router, the new page's layout is measured before
 images settle. `ScrollTrigger.refresh()` on mount is usually needed. See
-[react-nextjs.md](react-nextjs.md).
+[react.md](../adapter/react.md).
 
 ## Failures
 

package/skill/reference/svg.md

@@ -24,7 +24,7 @@ as JSX.
 
 Without them you end up at `querySelectorAll("path")[3]`, which breaks on the
 next export. Prefix them, and namespace per instance — see
-[react-nextjs.md](react-nextjs.md). For a set animated together, one
+[react.md](../adapter/react.md). For a set animated together, one
 `data-*` attribute beats a run of ids:
 
 ```tsx

package/skill/reference/timeline.md

@@ -4,6 +4,46 @@ A timeline is how choreography stays editable. Five tweens with hand-tuned
 delays encode the same animation in a form nobody can retime without redoing
 the arithmetic.
 
+## Scene and beats
+
+A scene is a set of named beats, and each beat is a label in the code. Writing
+the beats down before the tweens is what stops a timeline becoming a pile of
+numbers nobody can change.
+
+Most scenes are four beats or fewer:
+
+| Beat | Says |
+|---|---|
+| Entrance | this arrived |
+| Emphasis | this is the one that matters — **at most one per scene** |
+| Pause | read this before the next thing moves |
+| Exit | this is finished, or making room |
+
+```ts
+const tl = gsap.timeline();
+
+tl.addLabel("enter")
+  .from("[data-heading]", { yPercent: 110, duration: 0.8 })
+  .from("[data-lead]", { autoAlpha: 0, y: 18, duration: 0.6 }, "-=0.5")
+  .addLabel("emphasis")
+  .add(mark())                       // a beat of its own, built elsewhere
+  .addLabel("rest");
+```
+
+Two rules follow from it:
+
+- **A beat that is more than one tween is a function returning its own
+  timeline**, added with `.add()`. The scene then reads as its beats, and the
+  beat can be retimed, reordered or dropped without touching the rest.
+- **An ambient loop is handed off after the scene, never added inside it.** An
+  infinite child makes the parent infinite, so the scene's own `onComplete`
+  never runs and anything waiting on it waits forever — the audit reports that
+  as `never-completes`. Start the loop from a `.call()` at the end, or from the
+  scene's `onComplete`.
+
+The numbered beats in an answer's Motion strategy and the labels in its code are
+the same list. If they have drifted apart, the code is not what was designed.
+
 ## Position
 
 The third argument places a child on the timeline. This is the whole API.
@@ -103,7 +143,7 @@ onMouseLeave = () => hover.reverse();
 
 `reverse()` uses the same easing backwards, so the return matches the arrival
 without a second definition. In React, anything built outside the `useGSAP`
-body must go through `contextSafe` — see [react-nextjs.md](react-nextjs.md).
+body must go through `contextSafe` — see [react.md](../adapter/react.md).
 
 ## Holds
 

package/skill/scripts/lib/ast.mjs

@@ -21,10 +21,16 @@ const OPTIONS = {
  * `.ts` is read without JSX, because there `<T>(x) => x` is a generic and
  * `<Type>value` a cast; every other extension is read with it. A `.js` file
  * with JSX is common enough, and JSX never changes how plain JavaScript parses.
+ *
+ * A single-file component's `<script>` is read without JSX too: it is
+ * TypeScript as often as not, and the template where the angle brackets live is
+ * blanked out before it reaches here.
  */
 const TYPESCRIPT = Parser.extend(tsPlugin());
 const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
 
+const WITHOUT_JSX = /\.(?:[mc]?ts|vue|svelte|astro)$/;
+
 /**
  * Parses `source` as the grammar its `path` implies.
  *
@@ -34,7 +40,7 @@ const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
  */
 export function parse(source, path) {
   const comments = [];
-  const parser = /\.[mc]?ts$/.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
+  const parser = WITHOUT_JSX.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
   const ast = parser.parse(source, { ...OPTIONS, onComment: comments });
   return { ast, comments };
 }