@mehshekari/gsap-motion 3.1.0 → 3.2.0

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`