@mehshekari/gsap-motion 3.1.1 → 3.3.0

package/skill/adapter/react.md

@@ -0,0 +1,133 @@
+# React
+
+Animation is a client concern, and the interesting problems are all lifecycle.
+This covers any React app — Vite, Remix, Next. With Next, read
+[next.md](next.md) too; with React Three Fiber, [r3f.md](r3f.md).
+
+## Where it is created
+
+`useGSAP`, from `@gsap/react`: `useLayoutEffect` with an SSR fallback, plus
+automatic `gsap.context()` cleanup — which is what makes it survive StrictMode's
+double invoke in development.
+
+```ts
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useRef } from "react";
+
+gsap.registerPlugin(useGSAP);          // module scope, once
+
+export function useReveal() {
+  const root = useRef<HTMLDivElement>(null);
+
+  useGSAP(() => {
+    gsap.from("[data-item]", { y: 20, stagger: 0.05 });   // scoped to root
+  }, { scope: root });
+
+  return root;
+}
+```
+
+It is a layout effect, so it runs **before paint**: a `from` or a `set` lands
+with no flash of the end state. Its options are `scope`, `dependencies` (the
+body re-runs on change) and `revertOnUpdate` (the previous run reverts first).
+
+A tween created *outside* the body — in a handler, a promise, a callback — is
+never reverted. Wrap that function in `contextSafe`, from the same hook, and the
+context owns it again. Only wrap functions that *create* animations: playing an
+existing timeline creates nothing. `contextSafe` runs during render, so reading a
+ref inside the callback trips React's "cannot access refs during render" rule —
+build the timeline in the body, keep it on a ref, and expose a `useCallback`
+that plays it.
+
+## Where it is torn down
+
+`useGSAP` reverts its context on unmount. Tweens, timelines, `ScrollTrigger`,
+`Observer`, `Draggable`, `SplitText` and `gsap.matchMedia()` register themselves
+with the context while its function runs and are reverted with it, so none needs
+a manual `kill()` inside the body.
+
+**These are yours**, because GSAP never sees them: timers, listeners on `window`
+or `document`, `ResizeObserver` and `IntersectionObserver` — and **anything
+created outside the body**, at module scope, in a plain `useEffect`, or in a
+handler that never went through `contextSafe`. That last one is the real leak,
+and the one people write cleanup for the wrong things instead of catching.
+
+## Scope
+
+`{ scope: root }` is not optional in practice: selector strings resolve inside
+the component, so two instances cannot animate each other's elements.
+
+A scope does **not** reach inside plugin config: `motionPath.path` and
+`morphSVG.shape` resolve against the whole document, so a hardcoded id in a
+component rendered twice makes both instances drive the first one's geometry,
+silently. Generate one per instance from `useId()`, stripped to word characters
+— React's id carries delimiters a CSS selector cannot hold, and unlike a counter
+it is stable across server and client.
+
+## Server rendering and hydration
+
+Reading `localStorage`, `sessionStorage` or `matchMedia` **during render** makes
+the server and the client disagree. Render the neutral state and correct it in
+the layout effect, before paint, so nothing is seen.
+
+Read direction and preferences from the DOM inside the effect, never from a prop:
+`document.documentElement.dir === "rtl"` keeps the hook independent of the i18n
+library, and the layout stamps `dir` before first paint.
+
+## Reaching the element
+
+A shared component that does not forward props has nowhere to hang a `data-*`
+attribute; widening it to take its element's remaining props is usually right,
+and often already the house pattern. A positional selector
+(`row.firstElementChild`) breaks the next time the markup moves.
+
+## Every frame
+
+React state for a value that changes every frame is a re-render per frame.
+
+```ts
+// Wrong
+const [x, setX] = useState(0);
+onMouseMove = (e) => setX(e.clientX);
+
+// Right
+const moveX = gsap.quickTo(el.current, "x", { duration: 0.5, ease: "power3" });
+onMouseMove = (e) => moveX(e.clientX);
+```
+
+State is for *what exists* — is the modal open, which tab is active. GSAP owns
+*how it moves*. Crossing that line is the most common performance bug in
+animated React.
+
+## Page and route changes
+
+A client router unmounts the outgoing tree, so an exit animation needs something
+that outlives the route — an overlay in the layout, not in the page. See
+[page-transition](../preset/page-transition.md), and [next.md](next.md) for the
+App Router. After a navigation, `ScrollTrigger.refresh()` once it settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Animation runs twice in dev | tweens created outside `useGSAP` — StrictMode |
+| Animation leaks after navigation | ScrollTrigger or listener created outside the scope |
+| Flash of the end state | `from` outside a layout effect |
+| Two components animate each other | missing `scope`, or a shared hardcoded id |
+| Hydration mismatch | storage or a media query read during render |
+| Janky pointer effect | React state in the handler |
+| Hover sticks halfway | no `overwrite: "auto"` on the retriggered tween |
+
+## What the audit covers
+
+`orphan-tween`, `state-per-event` and `shared-plugin-id` are React-specific: the
+audit applies them to `.jsx` and `.tsx` files, and to any file importing `react`
+or `@gsap/react`. Every other rule applies to every file it reads. It follows a
+helper within one file — a function only a `useGSAP` body calls counts as inside
+the context — but never into another file.
+
+## Versions
+
+Verified against `gsap@3.15` and `@gsap/react@2.1`. Written for `react@18` and
+`react@19`.

package/skill/adapter/svelte.md

@@ -0,0 +1,105 @@
+# Svelte and SvelteKit
+
+Svelte 5 runs effects in runes mode; `onMount` still works and reads the same in
+both versions. Either way the animation is created after mount, in a context
+that is reverted when the component is destroyed.
+
+## Where it is created
+
+```svelte
+<script>
+  import gsap from "gsap";
+
+  let root;
+
+  $effect(() => {
+    const ctx = gsap.context(() => {
+      gsap.from("[data-item]", { autoAlpha: 0, y: 24, stagger: 0.06 });
+    }, root);
+
+    return () => ctx.revert();
+  });
+</script>
+
+<section bind:this={root}>…</section>
+```
+
+`$effect` runs after the component is mounted in the browser, and the function
+it returns runs before the next run and when the component is destroyed. In
+Svelte 4, or in a codebase that has not moved to runes, the same body goes in
+`onMount` and returns the same cleanup.
+
+Check how the project declares a bound element before copying this: `let root`
+in classic syntax, `let root = $state()` in runes.
+
+## Where it is torn down
+
+The function returned from `$effect` or from `onMount`, calling `ctx.revert()`.
+That reverts every tween, ScrollTrigger, Observer, Draggable, SplitText and
+matchMedia created inside.
+
+An effect re-runs whenever a rune it read changes. If the body creates
+animations, either keep it free of reactive reads, or accept the re-run and let
+the returned cleanup revert the previous one first — which it does, before the
+body runs again.
+
+Timers, listeners and observers are yours, in the same cleanup.
+
+## Scope
+
+`gsap.context(fn, root)` scopes selector strings to the component's element.
+Plugin config is not scoped: `motionPath.path` and `morphSVG.shape` resolve
+against the whole document, so generate an id per instance — from whatever
+unique-id helper your Svelte version provides, or a module counter — rather than
+hardcoding one.
+
+## Server rendering and hydration
+
+Neither `$effect` nor `onMount` runs during server rendering, so this is safe
+under SvelteKit as written. Do not read `window`, `document` or `matchMedia` at
+the top level of `<script>`: that runs on the server. Read them inside the
+effect.
+
+Render the neutral state on the server and correct it after mount, so the
+hydrated markup matches what was sent.
+
+## Reaching the element
+
+`bind:this` for the root, `data-*` attributes for the parts. Svelte scopes CSS
+classes by compiling them, so a class selector in a tween may not match what is
+in the DOM — a `data-*` attribute is stable and says what it is for.
+
+## Every frame
+
+Refs, not `$state`. Writing a rune every frame re-renders the component;
+`gsap.quickTo` writes straight to the element. State is for what exists — is the
+drawer open, which tab is active.
+
+## Page and route changes
+
+SvelteKit destroys the outgoing component, so the context goes with it. For an
+exit animation, put the overlay in a layout, which navigation does not destroy,
+or hold the navigation while a timeline plays with the router's own hooks.
+
+After navigation, call `ScrollTrigger.refresh()` once the new page settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| `window is not defined` during a build | `window` read at the top of `<script>` instead of inside the effect |
+| Animations stack up on every state change | an effect that reads a rune, with no cleanup reverting the previous run |
+| Tween targets nothing | a class selector the compiler rewrote; use `data-*` |
+| Hydration mismatch | markup derived from storage or a media query during render |
+
+## What the audit covers
+
+From 3.2 the audit reads the `<script>` block of `.svelte` files, with offsets
+kept, so reported lines match the file. Every rule that is not React-specific
+applies; `orphan-tween`, `state-per-event` and `shared-plugin-id` do not run
+here.
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `svelte@5`, with the `onMount` form
+for `svelte@4`.

package/skill/adapter/three.md

@@ -0,0 +1,141 @@
+# Three.js
+
+GSAP is the **orchestration layer**, not the renderer. Three owns the scene, the
+camera and the draw loop. GSAP owns *when* values change and *how* they ease
+between states. With React Three Fiber, read [r3f.md](r3f.md) instead.
+
+Three does not come with GSAP, and most projects have neither. Check
+`package.json` before writing code against it, and say so if it is not there.
+
+## The division
+
+| GSAP | Three |
+|---|---|
+| timing, easing, sequencing | geometry, materials, lights |
+| camera moves between positions | camera projection, the render loop |
+| object transforms over time | the transforms themselves |
+| material property transitions | shaders |
+| tying it all to scroll | rendering the result |
+
+Do not rebuild a physics engine or a particle system in GSAP, and do not
+hand-write easing in the render loop when a tween says it in one line.
+
+## Where it is created
+
+Three objects are plain JavaScript objects, so GSAP tweens them directly. Nested
+properties are their own targets:
+
+```ts
+gsap.to(mesh.position, { x: 2, y: 1, duration: 1.2, ease: "power3.inOut" });
+gsap.to(mesh.rotation, { y: Math.PI * 2, duration: 3, ease: "none", repeat: -1 });
+gsap.to(mesh.material, { opacity: 0, duration: 0.6 });
+gsap.to(mesh.scale, { x: 1.4, y: 1.4, z: 1.4, duration: 0.5 });
+```
+
+`gsap.to(mesh, { position: { x: 2 } })` does not work. Target `mesh.position`.
+
+For a material to animate opacity, `transparent` must already be true — setting
+it mid-tween causes a shader recompile.
+
+Shader uniforms are `{ value }` objects, which tween cleanly and are the usual
+bridge between a timeline and a custom effect:
+
+```ts
+gsap.to(material.uniforms.uProgress, { value: 1, duration: 1.5, ease: "power2.inOut" });
+```
+
+Create all of it inside a `gsap.context`, as in [vanilla.md](vanilla.md): the
+lifecycle is the vanilla one, because Three has no component model of its own.
+
+## Where it is torn down
+
+Two separate jobs, and GSAP only does the first:
+
+- `ctx.revert()` for tweens, timelines and ScrollTriggers.
+- **Three's own disposal is yours**: geometries, materials, textures, render
+  targets, and the renderer itself. GSAP's cleanup does not touch them, and
+  nothing else will.
+
+Stop the render loop too. A `requestAnimationFrame` loop that outlives the
+canvas keeps the GPU busy for a page nobody is looking at.
+
+## Scope
+
+Selector strings do not apply: targets are object references. The scoping
+question becomes ownership — a module-level scene shared by two mounts animates
+twice. Build the scene per mount, or key the timeline to the instance.
+
+## Server rendering and hydration
+
+None: WebGL exists only in the browser. Import the module that creates the scene
+dynamically, after mount, so the server never evaluates it and the bundle does
+not carry Three on routes that have no canvas.
+
+## Reaching the element
+
+By reference, held from where the object was created. Traversing the scene by
+name (`scene.getObjectByName("Cube.003")`) binds the animation to whatever the
+exporter happened to call it, which the next export changes.
+
+## Every frame
+
+The render loop is already per-frame; GSAP does not need to be. Use a tween for
+transitions between states, and the loop for values that follow the clock. When
+a tween must write something the loop reads, tween a proxy object and read it in
+the loop rather than calling into Three from `onUpdate` many times per frame.
+
+The one exception is a camera with `lookAt`, which overwrites the rotation you
+tween. Tween a proxy target and call `lookAt` from `onUpdate`:
+
+```ts
+const look = { x: 0, y: 0, z: 0 };
+gsap.to(look, {
+  x: 2,
+  duration: 2,
+  onUpdate: () => camera.lookAt(look.x, look.y, look.z),
+});
+```
+
+For scroll-driven 3D, scrub a timeline rather than computing from `scrollY` in
+the loop, with `ease: "none"` on every child, as with any scrub. See
+[scrolltrigger.md](../reference/scrolltrigger.md).
+
+## Page and route changes
+
+Dispose on leaving, and rebuild on arriving. A canvas kept across a navigation
+is a live GPU context for a page that is gone.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Nothing moves | tweened `mesh` instead of `mesh.position` |
+| Opacity does nothing, or the frame stutters once | `transparent` set during the tween |
+| The GPU stays busy after leaving the page | the render loop or the renderer was never stopped |
+| Memory grows on every visit | geometries, materials or textures never disposed |
+| The camera snaps back every frame | `lookAt` overwriting a tweened rotation |
+| The page is slow on phones before anything moves | Three in the initial bundle instead of imported dynamically |
+
+## Cost and accessibility
+
+3D is the most expensive thing on a page, and the constraints are harder than
+for DOM animation:
+
+- A WebGL canvas runs the GPU continuously. On a phone that is battery and heat.
+- Give the canvas a real fallback — a static image — for low-power devices and
+  for `prefers-reduced-motion`. Stopping the animation while leaving a running
+  canvas is not a reduced-motion design.
+- Nothing essential — text, navigation, product information — should exist only
+  inside the canvas.
+
+## What the audit covers
+
+Every rule except the React-specific three, on the `.js`, `.ts` and `.mjs`
+modules that build the scene. It cannot see disposal, the render loop or GPU
+cost: those are read by hand, and measured with
+[performance.md](../reference/performance.md).
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `three@0.186`, whose disposal and
+uniform shapes it shares with earlier versions.

package/skill/adapter/vanilla.md

@@ -0,0 +1,115 @@
+# Vanilla JavaScript
+
+No framework: you own the mount and the unmount, so the only question is
+whether the element this animates can ever be removed.
+
+## Where it is created
+
+Inside `gsap.context(fn, root)`, in a function that runs when the element is in
+the document:
+
+```js
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+
+gsap.registerPlugin(ScrollTrigger);
+
+export function mountReveal(root) {
+  const ctx = gsap.context(() => {
+    const mm = gsap.matchMedia();
+    mm.add(
+      {
+        motion: "(prefers-reduced-motion: no-preference)",
+        reduced: "(prefers-reduced-motion: reduce)",
+      },
+      ({ conditions }) => {
+        if (conditions.reduced) {
+          gsap.set("[data-item]", { autoAlpha: 1, y: 0 });
+          return;
+        }
+        gsap.from("[data-item]", {
+          autoAlpha: 0,
+          y: 24,
+          stagger: { amount: 0.4 },
+          scrollTrigger: { trigger: root, start: "top 75%" },
+        });
+      },
+    );
+  }, root);
+
+  return () => ctx.revert();
+}
+```
+
+The returned function is the whole teardown contract. Hand it to whatever owns
+the element's life.
+
+## Where it is torn down
+
+`ctx.revert()` undoes every tween, ScrollTrigger, Observer, Draggable, SplitText
+and matchMedia created inside the context, and restores inline styles.
+
+Timers, `addEventListener` calls and observers are not GSAP's. Clear them in the
+same cleanup.
+
+A static page that never removes the element can skip teardown. Anything that
+swaps content — a client-side router, HTMX, Turbo, a modal, a web component —
+cannot: every swap would otherwise leave the previous run's triggers behind.
+
+## Scope
+
+The context's second argument is the root. Selector strings inside resolve
+within it, so the same widget mounted twice does not animate the other's
+elements.
+
+Plugin config is not scoped: `motionPath.path` and `morphSVG.shape` resolve
+against the whole document. Generate an id per instance rather than hardcoding
+one, in every framework and here too.
+
+## Server rendering and hydration
+
+There is none unless you add it. If the markup is rendered by a server template,
+the only rule that carries over is that the script runs after the element
+exists — a `defer`red module, or a `DOMContentLoaded` handler.
+
+## Reaching the element
+
+Pass the root in, and query inside it. A module that reaches for
+`document.querySelector` at import time binds to whatever happened to be on the
+first page, and silently animates nothing after a swap.
+
+## Every frame
+
+Use `gsap.quickTo` or `gsap.quickSetter` created once, outside the handler, and
+call it from the event. Creating a tween per pointer event allocates one tween
+per frame, each fighting the last.
+
+## Page and route changes
+
+If a router swaps content, mount on the new page and revert before the swap. The
+library's own events are the hooks: Turbo's `turbo:load` and
+`turbo:before-render`, HTMX's `htmx:afterSwap`, or your router's equivalent.
+Call `ScrollTrigger.refresh()` after the new content settles.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Animation stops working after a page swap | mounted once at import, never again |
+| Triggers pile up over a session | no `ctx.revert()` before the swap |
+| Selector matches another instance's element | no root passed to `gsap.context` |
+| Scroll positions drift | no `ScrollTrigger.refresh()` after content changed |
+
+## What the audit covers
+
+Every rule except the React-specific three: `orphan-tween`, `state-per-event`
+and `shared-plugin-id` apply to React files only. Cost, loops, scrub, listeners,
+unmanaged instances, plugin registration, reduced motion and shipped dev tooling
+are checked here.
+
+Keep the animation in a `.js`, `.mjs` or `.ts` module — the files the audit
+reads — rather than in an inline `<script>` in an HTML page, which it does not.
+
+## Versions
+
+Verified against `gsap@3.15`. No framework version applies.

package/skill/adapter/vue.md

@@ -0,0 +1,120 @@
+# Vue and Nuxt
+
+Composition API with `<script setup>`. Nuxt renders on the server, so everything
+here is written to run only in the browser.
+
+## Where it is created
+
+In `onMounted`, inside a `gsap.context` rooted at the component's element:
+
+```vue
+<script setup>
+import gsap from "gsap";
+import { onMounted, onUnmounted, ref } from "vue";
+
+const root = ref(null);
+let ctx;
+
+onMounted(() => {
+  ctx = gsap.context(() => {
+    gsap.from("[data-item]", { autoAlpha: 0, y: 24, stagger: 0.06 });
+  }, root.value);
+});
+
+onUnmounted(() => ctx?.revert());
+</script>
+
+<template>
+  <section ref="root">…</section>
+</template>
+```
+
+Animation that reacts to state belongs in a `watch` that adds its tweens to the
+same context with `ctx.add(() => { /* … */ })`, so they are reverted with it
+rather than outliving it.
+
+## Where it is torn down
+
+`onUnmounted`, with `ctx.revert()`. That covers every tween, ScrollTrigger,
+Observer, Draggable, SplitText and matchMedia created inside the context.
+
+Timers, listeners and observers are yours, in the same hook. A `watch` stopper
+is yours too if you created it outside `setup`'s own scope.
+
+`<KeepAlive>` does not unmount: it deactivates. Use `onActivated` and
+`onDeactivated` to pause and resume, or the animation keeps running in a
+component the visitor cannot see.
+
+## Scope
+
+`gsap.context(fn, root.value)` scopes selector strings to the component's root,
+so a component used twice on a page does not animate the other's elements.
+
+Plugin config is not scoped. `motionPath.path` and `morphSVG.shape` resolve
+against the whole document, so generate an id per instance —
+`useId()` in Vue 3.5 and later, or a module counter — rather than hardcoding
+one.
+
+## Server rendering and hydration
+
+`onMounted` never runs on the server, so this is safe under Nuxt as written. Two
+rules follow:
+
+- Do not read `window`, `document` or `matchMedia` in `setup`'s body — it runs
+  on the server. Read them inside `onMounted`.
+- Render the neutral state on the server and correct it after mount, or the
+  hydrated markup disagrees with what was sent.
+
+In Nuxt, `<ClientOnly>` is a way to skip server rendering for a widget entirely,
+at the cost of rendering nothing until hydration — a poor trade for a section
+that carries content, a reasonable one for a canvas.
+
+## Reaching the element
+
+A template ref for the root, and `data-*` attributes inside it for the parts.
+Querying by tag or position (`root.value.children[2]`) breaks the next time the
+template changes.
+
+A child component's root element is reachable with a ref only when it is a
+single-root component; otherwise pass a class or a `data-*` attribute down and
+query it inside the context.
+
+## Every frame
+
+Refs, not reactive state. A `ref()` written every frame triggers Vue's
+reactivity and re-renders the component; `gsap.quickTo` writes straight to the
+element. Reactive state is for what exists — is the panel open, which tab is
+active.
+
+## Page and route changes
+
+Vue Router replaces the view, and `onUnmounted` runs, so the context goes with
+it. For an exit animation, either put the overlay in the layout, which the
+navigation does not unmount, or use the router's own guards to hold the
+navigation while a timeline plays.
+
+Call `ScrollTrigger.refresh()` after the new view settles — in Nuxt, after
+`nextTick()` on the route change.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| `window is not defined` during a Nuxt build | `window` read in `setup` instead of `onMounted` |
+| Hydration mismatch warning | state derived from storage or a media query during render |
+| The animation keeps running after leaving the page | `<KeepAlive>` deactivation treated as unmount |
+| Tweens from a `watch` are never reverted | created outside the context instead of through `ctx.add` |
+| Two instances animate each other | no root passed to `gsap.context` |
+
+## What the audit covers
+
+From 3.2 the audit reads the `<script>` block of `.vue` files, with offsets
+kept, so reported lines match the file. It checks that a context created in
+`onMounted` is reverted, along with every rule that is not React-specific.
+
+`orphan-tween`, `state-per-event` and `shared-plugin-id` are React-only and do
+not run here.
+
+## Versions
+
+Verified against `gsap@3.15`. Written for `vue@3.5` and `nuxt@4`.

package/skill/example/svg-loader.md

@@ -177,4 +177,4 @@ project's messages itself could bundle every locale.
 ## Related
 
 [preset/loader.md](../preset/loader.md) · [reference/svg.md](../reference/svg.md)
-· [reference/react-nextjs.md](../reference/react-nextjs.md)
+· [adapter/react.md](../adapter/react.md)

package/skill/reference/core-gsap.md

@@ -180,7 +180,7 @@ that context** — `MatchMedia`'s constructor registers with whatever context is
 active (verified against gsap 3.15), and `Context.add` makes itself active while your
 function runs. An explicit `mm.revert()` there is redundant, not wrong. Created
 outside one — module scope, a plain `useEffect` — it is yours to revert. See
-[react-nextjs.md](react-nextjs.md).
+[react.md](../adapter/react.md).
 
 ## `context`