@mehshekari/gsap-motion 2.1.0

package/skill/reference/three-r3f.md

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

package/skill/reference/timeline.md

@@ -0,0 +1,147 @@
+# Timeline architecture
+
+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.
+
+## Position
+
+The third argument places a child on the timeline. This is the whole API.
+
+```ts
+tl.to(a, { ... })                  // after everything before it
+  .to(b, { ... }, "<")             // with the previous tween's start
+  .to(c, { ... }, "<0.2")          // 0.2s after the previous start
+  .to(d, { ... }, "-=0.3")         // 0.3s before the timeline's current end
+  .to(e, { ... }, ">")             // at the previous tween's end (explicit)
+  .to(f, { ... }, 1.5)             // absolute time
+  .to(g, { ... }, "reveal")        // at a label
+  .to(h, { ... }, "reveal+=0.4");  // relative to a label
+```
+
+`<` is the one to reach for most. "Start with the previous thing, slightly
+after" is what overlap sounds like in code, and it survives a duration change
+upstream — `-=0.3` does not.
+
+## Labels
+
+Labels turn a timeline into something you can read and something you can seek.
+
+```ts
+const tl = gsap.timeline();
+
+tl.addLabel("mark")
+  .fromTo("[data-outline]", { drawSVG: "0%" }, { drawSVG: "100%", duration: 1 })
+  .addLabel("word")
+  .to("[data-letter]", { autoAlpha: 1, stagger: 0.05 }, "word")
+  .to(dot, { motionPath: { ... } }, "word")
+  .addLabel("hold");
+```
+
+Two children sharing a label start together and stay together when the beat
+before them changes length. That is the point — a label is a commitment about
+*structure*, where a number is a commitment about *time*.
+
+`tl.seek("word")` and `tl.tweenTo("hold")` then work without counting.
+
+## Nesting
+
+Build each beat as its own timeline and assemble them. This is what keeps a
+long sequence readable, and it lets you reuse a beat.
+
+```ts
+const enter = () =>
+  gsap.timeline().from("[data-line]", { yPercent: 110, stagger: 0.06 });
+
+const master = gsap.timeline()
+  .add(enter())
+  .add(revealImage(), "-=0.4")
+  .add(settle());
+```
+
+A nested timeline keeps its own internal timing when the parent's `timeScale`
+changes, which is how you slow a whole sequence without touching each beat.
+
+## Defaults
+
+Repeating `duration` and `ease` on every child is noise and drifts:
+
+```ts
+const tl = gsap.timeline({
+  defaults: { duration: 0.6, ease: "power3.out" },
+});
+```
+
+Children override individually. Set the house values once here.
+
+## Where `repeat` belongs
+
+On the child, not the parent, when only part of the sequence loops:
+
+```ts
+tl.from("[data-mark]", { ... })          // plays once
+  .to(dot, { rotation: 360, repeat: -1, ease: "none" });  // loops forever
+```
+
+`repeat: -1` on the timeline replays the entrance too. And a timeline containing
+an infinitely repeating child **never completes**, so its `onComplete` never
+fires — if something downstream waits on that, give the timeline a finite beat
+of its own to end on, or drive the handover from elsewhere.
+
+## Paused timelines as state
+
+Build once, play on demand. Far better than creating a tween per event.
+
+```ts
+const hover = gsap.timeline({ paused: true })
+  .to(el, { scale: 1.05, duration: 0.3 });
+
+onMouseEnter = () => hover.play();
+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).
+
+## Holds
+
+An empty tween is a pause that is visible in the structure:
+
+```ts
+tl.to(shape, { morphSVG: "#b" })
+  .to({}, { duration: 0.4 })     // hold, legible in the timeline
+  .to(shape, { morphSVG: "#c" });
+```
+
+Clearer than `delay` on the next tween, because the hold is a beat rather than a
+property of something else.
+
+## Scrubbing
+
+A paused timeline driven by an external value is the pattern behind every
+progress-bound animation:
+
+```ts
+const tl = gsap.timeline({ paused: true });
+tl.fromTo(ring, { drawSVG: "0%" }, { drawSVG: "100%", ease: "none" });
+
+gsap.to(tl, { progress, duration: 0.4, ease: "power2.out", overwrite: true });
+```
+
+Tween the progress rather than setting it — that is what smooths a value
+arriving as 0 → 40 → 100. `overwrite: true` stops two updates in flight from
+fighting. `ease: "none"` inside, because the outer tween owns the feel.
+
+ScrollTrigger's `scrub` is this same mechanism with scroll as the value.
+
+## Common failures
+
+| Symptom | Cause |
+|---|---|
+| Reads like a slideshow | no overlap — nothing uses `<` or a negative offset |
+| Retiming one beat breaks the rest | `-=` offsets instead of labels |
+| `onComplete` never fires | an infinitely repeating child |
+| Entrance replays on loop | `repeat: -1` on the timeline, not the child |
+| Flash of the end state before it runs | `from` without a `set`, outside a layout effect |
+| Two beats drift apart after an edit | both timed by number instead of sharing a label |

package/skill/scripts/audit-gsap.mjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+
+/**
+ * Audits GSAP animation code for the failures that are silent.
+ *
+ * Nothing here is a matter of taste. Every rule catches something that
+ * produces no error and often no visible symptom until much later, on a slower
+ * device, or after a navigation: a tween that outlives its component, a tween
+ * allocated per pointer event, a layout property animated every frame, an ease
+ * on a loop that makes its own seam visible, a hardcoded id that makes two
+ * instances drive one another's geometry.
+ *
+ * Rhythm, easing choice and whether an animation earns its place are not
+ * checkable and are not attempted — reference/motion-design.md owns those.
+ *
+ * This is static analysis without a parser, so it is deliberately conservative
+ * and will still be wrong sometimes. `info` findings have the loosest match.
+ * A wrong finding is a bug in this script; report it rather than working
+ * around it.
+ *
+ * Usage — paths resolve from the current directory, so run it from the project
+ * root, wherever the skill itself is installed:
+ *   node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
+ *   node <skill-dir>/scripts/audit-gsap.mjs src/components --json
+ *   node <skill-dir>/scripts/audit-gsap.mjs src --quiet   # errors only
+ *
+ * Exit code is 1 when any error-level finding is reported, 0 otherwise.
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { RULES } from "./lib/rules.mjs";
+import { collect, lineAt, load } from "./lib/source.mjs";
+
+/**
+ * The project being audited is wherever this is run from, not wherever the
+ * skill is installed. It used to be derived from this file's own location,
+ * which only worked while the skill sat exactly four levels inside the project:
+ * installed per user under `~/.claude/skills/`, it resolved `src` against the
+ * home directory and every run exited with "No such path".
+ */
+const ROOT = process.cwd();
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes("--json");
+const quiet = argv.includes("--quiet");
+const targets = argv.filter((a) => !a.startsWith("--"));
+
+const paths = (targets.length ? targets : ["src"]).map((p) => resolve(ROOT, p));
+
+for (const path of paths) {
+  if (!existsSync(path)) {
+    console.error(`No such path: ${path}`);
+    process.exit(2);
+  }
+}
+
+// --- Escape hatch ------------------------------------------------------------
+
+/**
+ * The same shape many repos already use for their own lint waivers, on
+ * purpose: one way to say "yes, and here is why", not two.
+ *
+ * A hatch is the rule's own id plus `-ok`, on the flagged line or in the eight
+ * above it, and it waives that rule and nothing else — silencing a shared id
+ * cannot also silence a layout property on the same line. The lookback is eight
+ * because a reason usually stands above a whole declaration rather than beside
+ * one line of it.
+ *
+ * Every hatch must carry its reason. A bare token with no sentence after it is
+ * a rule someone turned off rather than answered, and once this gates a build
+ * that distinction has to stay visible in review.
+ */
+const LOOKBACK = 8;
+
+function waived(source, line, ruleId) {
+  const lines = source.split("\n");
+  const from = Math.max(0, line - 1 - LOOKBACK);
+  return lines.slice(from, line).join("\n").includes(`${ruleId}-ok`);
+}
+
+// --- Run ---------------------------------------------------------------------
+
+const findings = [];
+
+for (const path of paths) {
+  for (const file of collect(path)) {
+    const source = load(file, ROOT);
+
+    /**
+     * A file that never mentions GSAP has nothing these rules can say. Checked
+     * once here rather than in every rule.
+     */
+    if (!source.usesGsap && !/\bgsap\./.test(source.code)) continue;
+
+    for (const rule of RULES) {
+      for (const hit of rule.test(source)) {
+        const line = lineAt(source.raw, hit.index);
+        if (waived(source.raw, line, rule.id)) continue;
+
+        findings.push({
+          rule: rule.id,
+          level: rule.level,
+          file: source.display,
+          line,
+          message: hit.message,
+          hint: hit.hint,
+        });
+      }
+    }
+  }
+}
+
+// --- Report ------------------------------------------------------------------
+
+const ORDER = { error: 0, warn: 1, info: 2 };
+const ICON = { error: "✗", warn: "!", info: "i" };
+
+findings.sort(
+  (a, b) =>
+    ORDER[a.level] - ORDER[b.level] ||
+    a.file.localeCompare(b.file) ||
+    a.line - b.line,
+);
+
+const shown = quiet ? findings.filter((f) => f.level === "error") : findings;
+
+if (asJson) {
+  console.log(JSON.stringify({ findings: shown }, null, 2));
+} else if (!shown.length) {
+  console.log(
+    findings.length
+      ? `gsap-audit: no errors (${findings.length} lower-severity finding(s) hidden by --quiet)`
+      : "gsap-audit: clean",
+  );
+} else {
+  let current = "";
+  for (const f of shown) {
+    if (f.file !== current) {
+      current = f.file;
+      console.log(`\n${current}`);
+    }
+    console.log(`  ${ICON[f.level]} ${f.line}:  ${f.message}  [${f.rule}]`);
+    console.log(`      ${f.hint}`);
+  }
+
+  const counts = ORDER;
+  const tally = Object.keys(counts)
+    .map((level) => [level, findings.filter((f) => f.level === level).length])
+    .filter(([, n]) => n > 0)
+    .map(([level, n]) => `${n} ${level}`)
+    .join(", ");
+
+  console.log(`\n${tally}`);
+}
+
+process.exit(findings.some((f) => f.level === "error") ? 1 : 0);