@mehshekari/gsap-motion 3.1.0 → 3.2.0

package/skill/reference/frameworks.md

@@ -1,153 +0,0 @@
-# Frameworks other than React
-
-GSAP has no framework. What changes between frameworks is only **where an
-animation is created and where it is torn down** — the lifecycle. Everything
-else in this skill applies unchanged: motion design, timelines, ScrollTrigger,
-SVG, text, Flip, performance and accessibility.
-
-One pattern sits under every framework below:
-
-1. Create animations inside `gsap.context(fn, root)`, so selector strings
-   resolve inside the component's own root element.
-2. Build the reduced-motion branch with `gsap.matchMedia()` inside that context,
-   so it goes with it.
-3. Call `ctx.revert()` when the component goes away. That undoes every tween,
-   ScrollTrigger, SplitText and matchMedia created inside, and restores inline
-   styles.
-
-Timers, raw `addEventListener` calls and observers are not GSAP's — clear them
-yourself in the same cleanup.
-
-## Vanilla JavaScript
-
-```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(); // call when root is removed
-}
-```
-
-A static page that never removes the element can skip the cleanup. Anything that
-swaps content — a client-side router, HTMX, Turbo, a modal — cannot.
-
-## Vue 3 and Nuxt
-
-```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>
-```
-
-- `onMounted` never runs during server rendering, so this is safe under Nuxt as
-  written.
-- 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.
-
-## Svelte
-
-```svelte
-<script>
-  import gsap from "gsap";
-  import { onMount } from "svelte";
-
-  let root;
-
-  onMount(() => {
-    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>
-```
-
-A function returned from `onMount` runs when the component is destroyed.
-`onMount` does not run during server rendering. The markup uses Svelte's
-classic syntax; check how your Svelte version declares a `bind:this` variable
-before copying it.
-
-## Astro
-
-An Astro `<script>` runs once. With view transitions enabled, the page is
-swapped without a reload, so build on each page load and revert before each
-swap:
-
-```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>
-```
-
-Inside a React, Vue or Svelte island, use that framework's section instead.
-
-## Mounting twice
-
-Selector strings are scoped to the context's root, but `motionPath.path` and
-`morphSVG.shape` are resolved by the plugins against the whole document. A
-component rendered twice with a hardcoded id drives the first instance's
-geometry. Generate an id per instance in every framework, not only React.
-
-## What the audit covers here
-
-- `audit-gsap.mjs` reads `.js`, `.ts`, `.jsx`, `.tsx` and `.mjs` files only.
-  Logic inside `.vue`, `.svelte` or `.astro` files is not scanned — keep the
-  animation in a sibling module, like `mountReveal` above, if you want it
-  checked.
-- Its React-specific rules — `orphan-tween`, `state-per-event` and
-  `shared-plugin-id` — apply only to React files. The rest apply to every file
-  it reads: cost, loops, scrub, listeners, unmanaged instances, plugin
-  registration, reduced motion and shipped dev tooling.

package/skill/reference/react-nextjs.md

@@ -1,234 +0,0 @@
-# React and Next.js
-
-Written for the Next.js App Router with React 19 and Server Components, and
-verified against `@gsap/react` 2.1. Most of it applies to any React app; the
-RSC sections apply only where Server Components exist. Animation is always a
-client concern, and the interesting problems are all lifecycle. Not using
-React? Read [frameworks.md](frameworks.md) instead.
-
-## `useGSAP`
-
-`useGSAP`, from `@gsap/react`, is `useLayoutEffect` with an SSR fallback
-plus automatic `gsap.context()` cleanup — which is what makes it survive React
-19 StrictMode's double invoke.
-
-```ts
-"use client";
-
-import { useGSAP } from "@gsap/react";
-import gsap from "gsap";
-import { useRef } from "react";
-
-gsap.registerPlugin(useGSAP);          // module scope, once
-
-export function useThing() {
-  const root = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      gsap.from("[data-item]", { y: 20, stagger: 0.05 });  // scoped to root
-      return () => { /* anything the context does not own */ };
-    },
-    { scope: root },
-  );
-
-  return root;
-}
-```
-
-`{ scope: root }` is not optional in practice: it makes selector strings resolve
-inside the component, so two instances on a page do not animate each other's
-elements.
-
-Options: `scope`, `dependencies`, `revertOnUpdate`. With `dependencies`, the
-body re-runs when they change; `revertOnUpdate: true` also reverts the previous
-run first.
-
-Being a layout effect matters: it runs **before paint**, so a `from` or a `set`
-lands without a flash of the end state.
-
-## `contextSafe`
-
-Anything that creates a tween *outside* the hook body — an event handler, a
-promise, a callback — is created outside the context and never reverted.
-
-```ts
-const { contextSafe } = useGSAP(() => { ... }, { scope: root });
-
-const onEnter = contextSafe(() => {
-  gsap.to(el.current, { scale: 1.05 });   // now owned by the context
-});
-```
-
-Two things to get right:
-
-- **Only wrap functions that create animations.** Playing a timeline that
-  already exists creates nothing and needs no wrapper.
-- **`contextSafe` runs during render.** Reading a ref inside the callback you
-  pass it trips React's "cannot access refs during render" lint rule. Build the
-  timeline inside the hook body, keep it on a ref, and expose a plain
-  `useCallback` that plays it.
-
-## Refs, never state
-
-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.
-
-## The RSC boundary
-
-A component that animates is `"use client"`. Keep it a leaf so the page above it
-stays a Server Component.
-
-**If the target is currently a Server Component, converting it is part of the
-cost, and you have to price it before you design.** Two questions:
-
-1. *Is the library already on this route?* Grep for existing GSAP use in the
-   sections the page renders. If a sibling already loads `gsap` and
-   `ScrollTrigger`, the marginal cost is this component's own JS — a kilobyte or
-   two — rather than thirty-odd. That usually settles the argument. If nothing
-   on the route loads GSAP yet, this animation is buying the whole library for
-   one reveal, and it had better be worth it.
-2. *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 — a stale claim in a docblock is worse than none, because the
-   next person believes it.
-
-State both in the Notes section of your answer. "It becomes a client component"
-is a fact the reader needs, not a detail.
-
-### Reaching the element
-
-A shared component that does not forward props has nowhere to hang a `data-*`
-attribute. Widening it to take the rest of its element's props is usually right
-and is often already the house pattern — check a sibling before inventing one.
-Finding the element positionally instead (`row.firstElementChild`,
-`querySelectorAll("path")[3]`) is a selector that breaks silently the next time
-the markup moves.
-
-Two consequences worth planning for:
-
-- **Data and copy come down as props.** A client component importing a content
-  or locale module bundles every locale into the browser payload. Resolve on the
-  server, pass what the visitor needs. The same applies to large generated data
-  — path tables, keyframe sets: hand them down rather than importing them
-  client-side.
-- **`"use client"` module scope still runs during SSR.** Registering plugins
-  there is fine — GSAP defers anything touching `window` — but reading `window`
-  or `document` at module scope is not.
-
-## Reading the environment
-
-Read direction and preferences from the DOM inside the effect, not from a
-prop or a locale constant:
-
-```ts
-const isRtl = document.documentElement.dir === "rtl";
-```
-
-The layout stamps `dir` before first paint, and reading it there keeps the hook
-independent of the i18n library.
-
-## Cleanup: what the context already owns
-
-Wider than it is usually given credit for, and worth knowing precisely —
-otherwise you write cleanup that does nothing and still miss the real leaks.
-
-While a context's function runs, GSAP points `_context` at that context, and
-these register themselves with it on construction. `context.revert()` then
-reverts them:
-
-- tweens and timelines
-- `ScrollTrigger`
-- `Observer`
-- `Draggable`
-- `SplitText`
-- `gsap.matchMedia()`
-
-So inside a `useGSAP` body, none of those need a manual `.kill()` or
-`.revert()`. An explicit one is redundant rather than wrong.
-
-**These are genuinely yours**, because GSAP never sees them:
-
-- `setTimeout` / `setInterval` — clear them
-- `addEventListener` on `window` or `document` — remove them
-- `ResizeObserver` / `IntersectionObserver` — `.disconnect()`
-- Three.js geometries, materials, textures — dispose them
-- **anything created outside the context body** — module scope, a plain
-  `useEffect`, or 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.
-
-```ts
-useGSAP(() => {
-  const mm = gsap.matchMedia();        // reverted with the context
-  const io = new ResizeObserver(onResize);   // not — disconnect it
-  mm.add({ ... }, () => { ... });
-  io.observe(root.current!);
-  return () => io.disconnect();
-}, { scope: root });
-```
-
-`node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>`
-checks this distinction, among others.
-
-## Unique ids
-
-A scope does **not** reach inside plugin config. `motionPath.path` and
-`morphSVG.shape` are resolved by the plugin against the whole document, so a
-hardcoded id in a component rendered twice makes both instances drive the first
-one's geometry — silently.
-
-```ts
-const uid = `rs${useId().replace(/[^a-zA-Z0-9]/g, "")}`;
-```
-
-React's generated id carries delimiters a CSS selector cannot hold, so strip it
-to word characters. It is stable across server and client, which a counter is
-not. Then `id={`${uid}-track`}` in the markup and `#${uid}-track` in the config.
-
-## Route transitions
-
-The App Router unmounts the old tree before the new one paints, so an exit
-animation has nowhere to play. Options, in order of how much they cost:
-
-1. **Animate entrance only.** Keyed off `usePathname()`. Honest, cheap, and what
-   most sites actually want.
-2. **An overlay that outlives the route.** Mounted in the layout, so it is not
-   unmounted by the navigation. 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.
-
-After any navigation, call `ScrollTrigger.refresh()` once the new layout has
-settled.
-
-## Hydration
-
-Anything read from `localStorage`, `sessionStorage`, or `matchMedia` during
-render makes the server and client disagree. Render the neutral state, then
-correct it in the layout effect — before paint, so nothing is seen.
-
-## 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 media query read during render |
-| Janky pointer effect | React state in the handler |
-| Hover sticks halfway | no `overwrite: "auto"` on the retriggered tween |
-| `gsap.set` lands but `gsap.to` sits mid-flight — only under test | the harness waited on a timer while rAF was throttled, so the ticker never ran. Not a lifecycle bug: wait in frames — see "Timing in milliseconds, settling in frames" in performance.md |

package/skill/reference/three-r3f.md

@@ -1,161 +0,0 @@
-# Three.js and React Three Fiber
-
-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.
-
-Neither library comes with GSAP, and most projects have neither. Check
-`package.json` before writing code against them, and say so if they are not
-there.
-
-## The division
-
-| GSAP | Three / R3F |
-|---|---|
-| 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. Do not hand-write
-easing in `useFrame` when a tween would say it in one line.
-
-## The core pattern
-
-Three objects are plain JS objects, so GSAP tweens them directly. The only thing
-to remember is that 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 property to animate opacity, `transparent` must already be true —
-setting it mid-tween causes a shader recompile.
-
-## Uniforms
-
-Shader uniforms are `{ value }` objects, which tween cleanly:
-
-```ts
-gsap.to(material.uniforms.uProgress, { value: 1, duration: 1.5, ease: "power2.inOut" });
-```
-
-This is the usual bridge between a GSAP timeline and a custom shader effect —
-one uniform, driven by the timeline, interpreted by the shader.
-
-## R3F
-
-The renderer runs its own loop, so nothing needs invalidating on demand unless
-the canvas is set to `frameloop="demand"` — in which case call `invalidate()`
-from `onUpdate`.
-
-```tsx
-"use client";
-
-import { useGSAP } from "@gsap/react";
-import { useFrame, useThree } from "@react-three/fiber";
-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>
-  );
-}
-```
-
-**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
-per-frame logic that depends on the clock, GSAP for transitions between states.
-
-## Camera
-
-Camera moves are where GSAP earns its place — easing a camera by hand is how
-scroll-driven 3D ends up feeling mechanical.
-
-```ts
-const { camera } = 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 }, "<");
-```
-
-If the camera uses `lookAt`, tween a proxy target and call `lookAt` in
-`onUpdate` — otherwise the rotation you tween is overwritten every frame:
-
-```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),
-});
-```
-
-## Scroll-driven 3D
-
-Scrub a timeline, do not compute from `scrollY` in `useFrame`:
-
-```ts
-gsap.timeline({
-  scrollTrigger: { trigger: section, start: "top top", end: "+=2000",
-                   pin: true, scrub: 1 },
-})
-  .to(camera.position, { z: 3, ease: "none" })
-  .to(material.uniforms.uProgress, { value: 1, ease: "none" }, "<");
-```
-
-`ease: "none"` on every child, as with any scrub. See
-[scrolltrigger.md](scrolltrigger.md).
-
-## 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`. Do not merely stop the animation and leave a
-  running canvas.
-- Dynamically import the 3D component so Three is not in the initial bundle.
-- `frameloop="demand"` when the scene is static between interactions.
-- Dispose geometries, materials and textures on unmount; GSAP's cleanup does not
-  do that.
-- Nothing essential — text, navigation, product information — should exist only
-  inside the canvas.
-
-## Cleanup
-
-```ts
-useGSAP(() => {
-  const tl = gsap.timeline({ scrollTrigger: { ... } });
-  return () => { tl.scrollTrigger?.kill(); };
-});
-```
-
-Plus Three's own disposal, which is separate and yours to do.