@mehshekari/gsap-motion 2.1.0

package/skill/reference/performance.md

@@ -0,0 +1,216 @@
+# Performance
+
+A frame is 16.7ms at 60Hz, 8.3ms at 120Hz, and **6.2ms at 165Hz** — a rate
+ordinary gaming and creator monitors ship with now. GSAP drives tweens at
+whatever rate the display reports, so the budget you actually have is often less
+than half the figure people quote. Everything below is about staying inside it.
+
+That also makes 60Hz the wrong thing to design against in both directions: a
+high-refresh display hides jank a 60Hz laptop shows, and a mid-range phone
+throttling to 30Hz shows jank neither reveals.
+
+## What animating a property costs
+
+| Property | Browser does | Cost |
+|---|---|---|
+| `transform`, `opacity` | composite only | cheap — animate freely |
+| `filter`, `backdrop-filter` | paint, often per frame | expensive over large areas |
+| `background-position`, `box-shadow`, `border-radius` | repaint | moderate |
+| `width`, `height`, `top`, `left`, `margin`, `padding` | **layout** | expensive — avoid |
+
+The substitutions that matter:
+
+```ts
+{ left: 100 }      →  { x: 100 }
+{ width: "50%" }   →  { scaleX: 0.5, transformOrigin: "0% 50%" }
+{ top: 0 }         →  { y: 0 }
+{ display }        →  { autoAlpha }
+```
+
+`autoAlpha` is `opacity` plus `visibility`, so a hidden element stops taking
+pointer events without a layout-triggering `display` change.
+
+Animating `height: auto` is the classic trap. Use a `scaleY` on a wrapper, a
+`grid-template-rows: 0fr → 1fr` transition, or Flip with `scale: true`.
+
+### The swap is not always one for one
+
+`top: 50%` is half the **containing block**. `y: "50%"` and `yPercent: 50` are
+half the **element itself**. Swap them on a 1px rule and its full-height travel
+becomes half a pixel — silently, and worse than the layout cost it replaced.
+
+Two ways out:
+
+1. **Give the moving element its container's height** and translate that, with
+   the visible mark pinned inside it. The percentages then agree and nothing has
+   to be measured. A scanner line is the usual case: a full-height box
+   carrying a 1px line at its top, moved with `yPercent`.
+2. **Measure the container once** and translate in pixels — then keep the
+   measurement fresh across resizes yourself.
+
+The same asymmetry applies to `left`/`x` and to any percentage `width` or
+`height` swapped for a scale.
+
+## The pointer rule
+
+One tween per pointer event allocates an object per frame and creates tweens
+that fight each other. Create the retargeting function once:
+
+```ts
+const xTo = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
+```
+
+See [interaction.md](interaction.md).
+
+## The React rule
+
+State that changes every frame is a re-render every frame — the whole subtree
+reconciles so one element can move 3px.
+
+```ts
+// Wrong
+const [x, setX] = useState(0);
+
+// Right
+const xTo = gsap.quickTo(ref.current, "x", { duration: 0.4 });
+```
+
+State owns *what exists*. GSAP owns *how it moves*.
+
+## ScrollTrigger cost
+
+- **One trigger for one visual moment.** Forty cards revealing together is one
+  trigger with a stagger, not forty triggers. Each carries its own start/end
+  maths on every scroll.
+- Anything measuring layout inside `onUpdate` runs on every scroll frame. Cache
+  it, or move it to `onRefresh`.
+- `scrub: 1` is smoother *and* cheaper than `scrub: true` — it batches into the
+  ticker instead of tracking exactly.
+- Pinning adds wrapper elements. Pinning many sections adds many.
+
+## `will-change`
+
+Promotes an element to its own compositor layer. Useful in small doses,
+counterproductive in large ones — every layer costs memory, and dozens can be
+slower than none.
+
+GSAP sets it automatically during a tween when it helps. Add it by hand only for
+something that animates continuously, and never on a long list.
+
+## Filters and blur
+
+`filter: blur()` is repainted every frame and scales with area. A blurred
+full-screen backdrop animating is one of the most reliable ways to drop frames
+on a mid-range phone.
+
+Alternatives: a pre-blurred image, a `radial-gradient`, a lower-resolution
+layer scaled up, or animating `opacity` between two static states — one sharp,
+one blurred.
+
+## SVG cost
+
+Large or complex SVG animation is CPU work, not GPU work. Watch for:
+
+- Paths with thousands of nodes — simplify in the design tool first.
+- Filters (`feGaussianBlur`, `feTurbulence`) animating — very expensive.
+- `MorphSVGPlugin.convertToPath()` at runtime on every mount — convert in the
+  source file.
+- Many elements on motion paths — each is a per-frame path calculation.
+
+## Measuring
+
+Do not optimise from intuition — and time your instrumentation in
+**milliseconds, never frames**. A fixed frame count is a different duration on
+every display: 90 frames is 1.5s at 60Hz and 0.56s at 165Hz, which is the
+difference between capturing the end of an animation and stopping just before
+the part that was going wrong.
+
+```js
+const t0 = performance.now();
+const tick = () => {
+  const ms = performance.now() - t0;
+  /* record */
+  if (ms < 4000) requestAnimationFrame(tick);
+};
+```
+
+Counting frames to infer a refresh rate does not work either: an eased tween
+rounds to its end value long before it mathematically finishes, so "frames until
+it stopped changing" undercounts badly.
+
+### Timing in milliseconds, settling in frames
+
+The rule above is about *how long* something takes. *Has it finished?* is a
+different question, and a timer answers it wrongly.
+
+GSAP's ticker runs on `requestAnimationFrame`. A page driven by automation, or a
+tab in the background, throttles or pauses rAF while `setTimeout` keeps firing
+on schedule. So a harness that waits with `setTimeout(done, 800)` and then reads
+computed styles sees every `gsap.set` exactly where it belongs and every
+`gsap.to` frozen part-way — a pill holding the last target's width, an opacity
+still at its class value. That reads precisely like a lifecycle bug, and it is
+not one.
+
+It is an expensive misdiagnosis. A sliding nav pill checked this way was
+blamed on a `useGSAP` revert under StrictMode, refactored onto a plain effect,
+and given a lint waiver — and all three were undone once the same test waited
+in frames. The original code had been right throughout.
+
+Wait for a duration, but only let the wait end on a rendered frame:
+
+```js
+const settle = (ms) =>
+  new Promise((resolve) => {
+    const t0 = performance.now();
+    const tick = () =>
+      performance.now() - t0 >= ms ? resolve() : requestAnimationFrame(tick);
+    requestAnimationFrame(tick);
+  });
+```
+
+That keeps the duration independent of the display, and guarantees the ticker
+had frames to run in. If it never resolves, the page is not rendering at all —
+bring it to the front. A hang is a loud failure; a timer's stale reading is a
+silent one.
+
+**If `gsap.set` lands and `gsap.to` does not, suspect the harness before the
+code.** Read the value twice a few frames apart: unchanged and short of its
+target means the ticker is not running.
+
+1. **Performance panel, 4× or 6× CPU throttling.** Record the interaction. Long
+   tasks and "Recalculate Style" / "Layout" bars are the signal.
+2. **Rendering panel → Paint flashing** shows what is repainting.
+3. **Layers panel** shows how many compositor layers exist.
+4. Test on a real mid-range phone. A desktop hides almost every problem here.
+
+If the trace shows time in Layout, you are animating a layout property. If it
+shows Paint, something is repainting — usually a filter or a shadow. If it shows
+Scripting, it is your handler, and usually React.
+
+## Budget
+
+- A frame means everything in it — your handler, style, layout, paint,
+  composite — inside the display's interval: 16.7ms at 60Hz, 6.2ms at 165Hz.
+- A handful of transform/opacity tweens costs almost nothing.
+- One full-screen blur can cost the whole budget on a phone.
+- Dozens of simultaneous timelines are fine; dozens of simultaneous *layouts*
+  are not.
+
+## Loading
+
+GSAP core is roughly 23KB min+gzip. Plugins are extra, so import from subpaths —
+`gsap/ScrollTrigger`, never `gsap/all` — and only in the component that needs
+them. A component that is below the fold can be dynamically imported with its
+animation code.
+
+## Checklist
+
+- Only `transform` and `opacity` in anything continuous or scroll-driven?
+- One tween retargeted for pointer, not one per event?
+- No React state changing per frame?
+- One ScrollTrigger per visual moment?
+- No layout measurement inside `onUpdate`?
+- Filters limited in area, or avoided?
+- Everything reverted on unmount — no orphaned triggers or listeners?
+- Verified on a throttled CPU and a real phone?
+- End states read after waiting in rendered frames, not on a timer?

package/skill/reference/project-rules.md

@@ -0,0 +1,178 @@
+# Project rules
+
+This skill is project-agnostic. The project it is working in is not: it has a
+linter, colour tokens, a folder layout, a text direction, and usually a motion
+language already on the page. Those outrank anything in this skill.
+
+## Finding them
+
+Before writing code, look for the project's animation rules, in this order:
+
+1. **`ANIMATION.md` at the repository root.**
+2. **A file an agent-instructions file points to** — `AGENTS.md`, `CLAUDE.md`,
+   `.cursor/rules`, or similar — for animation or motion.
+3. **Nothing.** Derive them (below), and say in your answer which ones you
+   assumed.
+
+Read the whole file. Where it disagrees with this skill, the project wins. If a
+project rule looks wrong, say so — do not quietly follow the skill instead.
+
+## Deriving them when there is no file
+
+A few minutes here is cheaper than a page with two motion languages.
+
+- **What fails the build.** Read the `lint`, `check` and `test` scripts in
+  `package.json` and whatever they run. A rule that fails CI is a constraint,
+  not a preference.
+- **Colour.** CSS variables, a Tailwind theme, a design-token file? An
+  animation that tweens to a literal the theme cannot reach breaks dark mode.
+- **Direction.** Is `dir="rtl"` ever set? If so, the RTL rules below apply.
+- **Where code goes.** Where do existing hooks and client components live, and
+  where does copy come from?
+- **The house motion language.** Grep for `gsap.`, `ScrollTrigger` and
+  `useGSAP`. The trigger point, ease, durations and stagger shape already on the
+  page are the precedent — step 2 of the pipeline in SKILL.md.
+
+## Writing an `ANIMATION.md`
+
+If the project will be animated more than once, suggest creating one. A useful
+one is short, and each section is an instruction rather than an essay:
+
+````markdown
+# Animation rules
+
+## What fails the build
+<!-- Lint rules that catch animation or SVG code, and their escape hatches. -->
+
+## Colour
+<!-- Where colours come from; what an SVG paint may be. -->
+
+## Direction
+<!-- LTR, RTL or both; how the layout mirrors (logical CSS, `rtl:` variants). -->
+
+## Where animation code lives
+<!-- Hook and component folders; the client/server boundary; where copy comes from. -->
+
+## House motion language
+| | |
+|---|---|
+| Trigger | e.g. `start: "top 75%"`, plays once |
+| Ease | e.g. `power3.out` |
+| Durations | heading / body / groups |
+| Stagger | `amount` (a total) or `each` (per item) |
+| Reduced motion | what the reduced branch shows |
+
+## Verify with
+<!-- The commands to run before calling it done. -->
+
+## Precedents
+<!-- Files that already do this well, by path, and what each one taught. -->
+````
+
+---
+
+## Rules worth knowing without a file
+
+Each of these fails silently in any project that has the condition.
+
+### RTL: everything with a handedness is decided, not inherited
+
+GSAP transforms are physical — `x` means left-to-right on every page. That is
+fine; leaving them unmirrored on a right-to-left page is not.
+
+| Has a direction | Mirror by |
+|---|---|
+| `x` / `xPercent` travel | negating the value |
+| `stagger` reading order | `from: "end"` |
+| MotionPath | `start: 1, end: 0` — no second path needed |
+| Horizontal ScrollTrigger | `+100 *` instead of `-100 *` |
+| Marquee | negating the target `x` |
+| `clipPath` wipe | `inset(0 100% 0 0)` becomes `inset(0 0 0 100%)` |
+| Flip | nothing — it measures both real layouts |
+
+```ts
+const isRtl = document.documentElement.dir === "rtl";
+gsap.from("[data-item]", { x: isRtl ? 40 : -40, stagger: 0.06 });
+```
+
+Read `dir` off the document rather than importing a locale: the layout sets it,
+and the hook stays independent of the i18n library. Vertical motion needs no
+mirroring at all, which is a good reason to prefer it.
+
+### A CSS transform is not a base GSAP adds to
+
+Projects that mirror with CSS often put the whole arrangement in a transform:
+
+```tsx
+<div className="translate-x-3.5 rotate-3 rtl:-translate-x-3.5 rtl:-rotate-3" />
+```
+
+A GSAP transform **replaces that matrix rather than composing with it**, and
+takes the `rtl:` variant with it, because an inline style outranks the class.
+Animate `x` or `rotation` on that element and the mirroring is gone — in one
+direction only, with nothing failing in the other.
+
+Three ways out, in order:
+
+1. **Animate a property CSS is not using.** `autoAlpha` on an element whose
+   transform CSS owns costs nothing and breaks nothing. Usually enough.
+2. **Animate a wrapper.** The wrapper carries the GSAP transform; the child
+   keeps its CSS one.
+3. **Move the arrangement into GSAP entirely**, mirroring it yourself from
+   `document.documentElement.dir`. Only worth it when the offset itself is what
+   animates, and it costs the no-JavaScript rendering.
+
+`gsap.from(el, { x: 0 })` looks like it solves this. It animates to the right
+place and then leaves an inline transform behind that no longer mirrors.
+
+### Positioned from a measurement, anchored physically
+
+A marker that slides to what it points at — a nav pill, a tab underline — is
+best placed from the target's own geometry: `x: link.offsetLeft`,
+`width: link.offsetWidth`. Measuring needs no `isRtl` branch, because the layout
+is already mirrored by the time you read it.
+
+But `offsetLeft` is physical, and so is `x`, so the marker's CSS anchor must be
+physical too: `left: 0`. A lint rule that enforces logical CSS will suggest
+`inset-inline-start: 0` instead, which resolves to `right: 0` on an RTL page
+while the measurement still counts from the left — and the marker lands
+off-screen in one direction only. Keep the physical anchor and use the
+project's waiver, with this reason.
+
+### Hue literals in SVGs
+
+If the project requires colours to come from tokens, an inline SVG is the
+easiest place to break that: it arrives as one paste with the literal in forty
+attributes, sometimes hidden in an export tool's `<style>` block. Run
+`audit-svg.mjs --hues` on the file first, and repaint with `currentColor` or
+the project's CSS variables.
+
+### Waivers carry reasons
+
+The skill's `audit-gsap.mjs` waives a rule with its id plus `-ok` — for
+example `shared-plugin-id-ok` — on the flagged line or in the eight above, and
+every waiver carries a sentence saying why:
+
+```ts
+/* shared-plugin-id-ok — one instance only: this is the page-level backdrop,
+   mounted once by the root layout and never by a component. */
+gsap.to("#dot", { motionPath: { path: "#track" } });
+```
+
+A bare token with no reason is a rule someone switched off rather than
+answered. If the project has its own waiver convention, follow that one.
+
+### Templates under a dot-directory are not typechecked
+
+TypeScript's default globs skip dot-directories such as `.claude/`, so the
+skill's `template/*.ts` files are invisible to `tsc` unless the project's
+`tsconfig.json` names them in `include`. Snippets inside Markdown are never
+checked — treat them as starting points, and let the project's own checks be
+the authority once the code is in its source tree.
+
+## Before you call it done
+
+Run the project's checks and `audit-gsap.mjs` on what you changed. Then watch
+it run: both themes if there are two, with reduced motion emulated, at phone
+width. A green build says the code compiles, not that the animation is right.
+If you have not seen it move, say so rather than implying you have.

package/skill/reference/react-nextjs.md

@@ -0,0 +1,234 @@
+# 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 |