@mehshekari/gsap-motion 2.1.0

package/skill/scripts/lib/source.mjs

@@ -0,0 +1,238 @@
+/**
+ * Source reading for the GSAP audit.
+ *
+ * Every helper here exists because naive matching produces false findings, and
+ * a checker that cries wolf is one people switch off. Comments are stripped
+ * before any rule runs — well-commented animation code explains itself at length, and
+ * a docblock saying "do not use `gsap.to` in a pointermove handler" would
+ * otherwise be reported as doing exactly that.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join, relative } from "node:path";
+
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+const SKIP_DIRECTORIES = new Set([
+  "node_modules",
+  ".next",
+  ".git",
+  "dist",
+  "build",
+  "coverage",
+]);
+
+/** Every source file under `root`, or `root` itself when it is a file. */
+export function collect(root) {
+  if (statSync(root).isFile()) return [root];
+
+  const files = [];
+  const walk = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.startsWith(".") || SKIP_DIRECTORIES.has(entry.name)) {
+        continue;
+      }
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (SOURCE_EXTENSIONS.has(extname(entry.name))) files.push(full);
+    }
+  };
+
+  walk(root);
+  return files.sort();
+}
+
+/**
+ * Replaces comment bodies with spaces, keeping every newline and every offset.
+ *
+ * Offsets are preserved rather than the text being cut out, so an index into
+ * the returned string is still an index into the original and `lineAt` stays
+ * correct. Blanking also means a rule cannot accidentally join two tokens that
+ * a comment sat between.
+ */
+export function stripComments(source) {
+  const out = source.split("");
+  let mode = "code";
+  let quote = "";
+
+  for (let i = 0; i < source.length; i += 1) {
+    const c = source[i];
+    const next = source[i + 1];
+
+    if (mode === "code") {
+      if (c === "/" && next === "/") {
+        mode = "line";
+        out[i] = " ";
+        out[i + 1] = " ";
+        i += 1;
+      } else if (c === "/" && next === "*") {
+        mode = "block";
+        out[i] = " ";
+        out[i + 1] = " ";
+        i += 1;
+      } else if (c === '"' || c === "'" || c === "`") {
+        mode = "string";
+        quote = c;
+      }
+      continue;
+    }
+
+    if (mode === "line") {
+      if (c === "\n") mode = "code";
+      else out[i] = " ";
+      continue;
+    }
+
+    if (mode === "block") {
+      if (c === "*" && next === "/") {
+        out[i] = " ";
+        out[i + 1] = " ";
+        i += 1;
+        mode = "code";
+      } else if (c !== "\n") {
+        out[i] = " ";
+      }
+      continue;
+    }
+
+    // Inside a string literal: left intact, but escapes must not end it early.
+    if (c === "\\") {
+      i += 1;
+      continue;
+    }
+    if (c === quote) mode = "code";
+  }
+
+  return out.join("");
+}
+
+/** 1-indexed line number for a character offset. */
+export function lineAt(source, index) {
+  let line = 1;
+  for (let i = 0; i < index && i < source.length; i += 1) {
+    if (source[i] === "\n") line += 1;
+  }
+  return line;
+}
+
+/**
+ * The `{ … }` block that opens at or after `from`, as a `[start, end]` pair.
+ *
+ * Used to ask "is this call inside that handler?" without a parser. Quotes are
+ * tracked so a brace inside a string cannot close the block early; comments are
+ * already gone by the time this runs.
+ */
+export function blockAfter(source, from) {
+  const start = source.indexOf("{", from);
+  if (start === -1) return null;
+
+  let depth = 0;
+  let quote = "";
+
+  for (let i = start; i < source.length; i += 1) {
+    const c = source[i];
+
+    if (quote) {
+      if (c === "\\") i += 1;
+      else if (c === quote) quote = "";
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      continue;
+    }
+    if (c === "{") depth += 1;
+    else if (c === "}") {
+      depth -= 1;
+      if (depth === 0) return [start, i];
+    }
+  }
+
+  return null;
+}
+
+/** Whether `index` falls inside any of the given `[start, end]` spans. */
+export const within = (spans, index) =>
+  spans.some(([start, end]) => index > start && index < end);
+
+/**
+ * The `( … )` of a call, as a `[start, end]` pair, given the index of its
+ * opening paren. Quotes are tracked the same way `blockAfter` tracks them.
+ */
+export function parenSpan(source, open) {
+  let depth = 0;
+  let quote = "";
+
+  for (let i = open; i < source.length; i += 1) {
+    const c = source[i];
+
+    if (quote) {
+      if (c === "\\") i += 1;
+      else if (c === quote) quote = "";
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") {
+      quote = c;
+      continue;
+    }
+    if (c === "(") depth += 1;
+    else if (c === ")") {
+      depth -= 1;
+      if (depth === 0) return [open, i];
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Spans of every `useGSAP(…)`, `gsap.context(…)` and `contextSafe(…)` call.
+ *
+ * Anything created outside these is outside the context that reverts it, which
+ * is the single most common way an animation outlives its component.
+ *
+ * The span is the call's parentheses, not the first `{` after its name. The
+ * first brace failed silently twice over: a bodiless `useGSAP()` — the usual
+ * way to get `contextSafe` — claimed whatever block came next in the file, so an
+ * orphaned tween in the handler below it read as owned; and an expression-bodied
+ * `contextSafe(() => gsap.to(el, { … }))` measured as the tween's own vars
+ * object, which the call itself sits in front of.
+ *
+ * `contextSafe` counts because it is a context: a wrapped function's tweens are
+ * added to the one `useGSAP` created.
+ */
+export function contextSpans(code) {
+  const spans = [];
+  for (const match of code.matchAll(
+    /\b(?:useGSAP|gsap\.context|contextSafe)\s*\(/g,
+  )) {
+    const span = parenSpan(code, match.index + match[0].length - 1);
+    if (span) spans.push(span);
+  }
+  return spans;
+}
+
+/** A file plus everything the rules need, read once. */
+export function load(path, root) {
+  const raw = readFileSync(path, "utf8");
+  const code = stripComments(raw);
+
+  return {
+    path,
+    display: relative(root, path).replace(/\\/g, "/"),
+    raw,
+    code,
+    /**
+     * "Can this mount more than once?" rather than literally "is this JSX".
+     *
+     * A hook lives in a `.ts` file and often imports only `@gsap/react`, never
+     * `react` itself — so matching on the extension or a React import alone
+     * misses exactly the files where the component-instance rules matter most.
+     */
+    isReact:
+      /\.(tsx|jsx)$/.test(path) ||
+      /\bfrom ["']react["']/.test(code) ||
+      /\bfrom ["']@gsap\/react["']/.test(code),
+    isClient: /^\s*["']use client["']/m.test(code),
+    usesGsap: /\bfrom ["']gsap(?:\/|["'])/.test(code),
+    contexts: contextSpans(code),
+  };
+}

package/skill/template/useScrollScene.ts

@@ -0,0 +1,126 @@
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useRef } from "react";
+
+/**
+ * Starting point for a scroll-driven scene.
+ *
+ * The shape here is the lesson: one trigger owning one timeline, a genuinely
+ * different strategy on mobile rather than a smaller one, and `ease: "none"`
+ * throughout because the scrollbar — not an ease curve — is the playhead.
+ *
+ * Copy it, rename it, replace the beats. Typechecked for the same reason as
+ * the sibling template.
+ */
+gsap.registerPlugin(useGSAP, ScrollTrigger);
+
+/** Scroll distance the pinned sequence is spread across, in pixels. */
+const SCROLL_LENGTH = 2400;
+
+export function useScrollScene() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const root = rootRef.current;
+      if (!root) return;
+
+      const mm = gsap.matchMedia();
+
+      mm.add(
+        {
+          desktop: "(min-width: 768px) and (prefers-reduced-motion: no-preference)",
+          mobile: "(max-width: 767px) and (prefers-reduced-motion: no-preference)",
+          reduced: "(prefers-reduced-motion: reduce)",
+        },
+        (context) => {
+          const { desktop, reduced } = context.conditions as Record<
+            string,
+            boolean
+          >;
+
+          /**
+           * Scroll-scrubbed pinning is a textbook vestibular trigger: the
+           * content moves while the page does not. Under `reduce` the beats
+           * simply exist, composed, with no pin and no scrub.
+           */
+          if (reduced) {
+            gsap.set("[data-beat]", { autoAlpha: 1, y: 0 });
+            return;
+          }
+
+          /**
+           * Not the desktop sequence scaled down. A 2400px pin on a phone is a
+           * long time to be stuck, and pinning fights the address bar
+           * collapsing — so each beat becomes an ordinary in-view reveal
+           * instead. Same content, different strategy.
+           */
+          if (!desktop) {
+            gsap.utils.toArray<HTMLElement>("[data-beat]").forEach((beat) => {
+              gsap.from(beat, {
+                autoAlpha: 0,
+                y: 24,
+                duration: 0.6,
+                ease: "power3.out",
+                scrollTrigger: { trigger: beat, start: "top 78%" },
+              });
+            });
+            return;
+          }
+
+          gsap
+            .timeline({
+              /**
+               * `ease: "none"` on every child. Easing inside a scrubbed
+               * timeline fights the visitor's own scrolling and reads as lag —
+               * `scrub` is where the smoothing belongs.
+               */
+              defaults: { ease: "none" },
+              scrollTrigger: {
+                trigger: root,
+                start: "top top",
+                end: `+=${SCROLL_LENGTH}`,
+                pin: true,
+                scrub: 1,
+                /** Reduces the flicker when the pin engages at speed. */
+                anticipatePin: 1,
+                /** Recomputes measured start values after a resize. */
+                invalidateOnRefresh: true,
+                markers: process.env.NODE_ENV === "development",
+              },
+            })
+            /**
+             * Labels rather than offsets. A scrubbed sequence gets retimed
+             * many times, and two children sharing a label stay together when
+             * the beat before them changes length.
+             */
+            .addLabel("open")
+            .from("[data-beat='1']", { autoAlpha: 0, y: 24, duration: 0.4 }, "open")
+
+            .addLabel("detail")
+            .to("[data-beat='1']", { autoAlpha: 0, duration: 0.3 }, "detail")
+            .from("[data-beat='2']", { autoAlpha: 0, y: 24, duration: 0.4 }, "detail+=0.3")
+
+            /**
+             * Placed at position 0 with the timeline's full span, so it tracks
+             * overall progress regardless of what else is happening.
+             */
+            .to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
+        },
+      );
+
+      /**
+       * ScrollTriggers and the `matchMedia` above are both reverted with the
+       * context — each registers itself when constructed inside one. Only
+       * things GSAP never sees (timers, raw listeners, observers) need a
+       * cleanup returned from here.
+       */
+    },
+    { scope: rootRef },
+  );
+
+  return rootRef;
+}

package/skill/template/useTimeline.ts

@@ -0,0 +1,110 @@
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { useCallback, useRef } from "react";
+
+/**
+ * Starting point for a component-scoped GSAP timeline.
+ *
+ * Copy it into the project's hooks folder or next to the component that owns
+ * it, rename it, and replace the timeline body. The structure is the part worth
+ * keeping: plugin registration at module scope, a scoped `useGSAP`, a
+ * `matchMedia` branch that treats reduced motion as a design rather than an off
+ * switch, and an explicit teardown for the things the GSAP context does not
+ * own.
+ *
+ * Worth typechecking where the skill is installed: add the skill's `template/`
+ * folder to `tsconfig.json`'s `include`. TypeScript's globs skip dot-directories
+ * such as `.claude/`, and an example that has quietly stopped compiling is worse
+ * than none.
+ */
+gsap.registerPlugin(useGSAP);
+
+/** One place for the numbers, so retiming is not a hunt through the body. */
+const TIMING = {
+  enter: 0.8,
+  stagger: 0.08,
+  hold: 0.4,
+} as const;
+
+export function useTimeline() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  /**
+   * Kept on a ref rather than returned directly: the timeline is built inside
+   * the effect, and a caller that wants to replay it needs a stable handle that
+   * does not exist until then.
+   */
+  const timelineRef = useRef<gsap.core.Timeline | null>(null);
+
+  useGSAP(
+    () => {
+      /**
+       * `matchMedia` rather than a one-off query, because a visitor can change
+       * the preference or the viewport while the component is mounted. GSAP
+       * reverts the losing branch and builds the other one; a plain `if` leaves
+       * the first animation running forever.
+       */
+      const mm = gsap.matchMedia();
+
+      mm.add(
+        {
+          motion: "(prefers-reduced-motion: no-preference)",
+          reduced: "(prefers-reduced-motion: reduce)",
+        },
+        (context) => {
+          const { reduced } = context.conditions as Record<string, boolean>;
+
+          /**
+           * The reduced branch must set the END state, not merely skip the
+           * tween. A `from` that never runs leaves its target at the authored
+           * start — which hides the content rather than calming it. This is the
+           * most common reduced-motion bug there is.
+           */
+          if (reduced) {
+            gsap.set("[data-item]", { autoAlpha: 1, y: 0 });
+            return;
+          }
+
+          timelineRef.current = gsap
+            .timeline({ defaults: { ease: "power3.out" } })
+            .from("[data-item]", {
+              y: 32,
+              autoAlpha: 0,
+              duration: TIMING.enter,
+              stagger: TIMING.stagger,
+            })
+            /**
+             * Positions, not delays. `<` starts a child with the previous one
+             * and survives a duration change upstream, where `-=0.3` silently
+             * drifts.
+             */
+            .to("[data-accent]", { scaleX: 1, duration: 0.5 }, "<0.2");
+        },
+      );
+
+      /**
+       * Nothing is returned, and that is deliberate. `matchMedia` registers
+       * itself with whatever GSAP context is active when it is constructed, so
+       * this one is reverted along with every tween above — as are Observer,
+       * Draggable, SplitText and ScrollTrigger when built in here.
+       *
+       * What a context never sees is the rest: timers, raw `addEventListener`,
+       * ResizeObserver, Three.js disposal. Return a cleanup for those.
+       */
+    },
+    { scope: rootRef },
+  );
+
+  /**
+   * Playing a timeline that already exists creates nothing, so this needs no
+   * `contextSafe` — the context already owns it. Wrapping it would also be a
+   * lint error, because `contextSafe` runs during render and reading a ref
+   * there is what React forbids. Reserve `contextSafe` for a handler that
+   * *creates* a tween.
+   */
+  const replay = useCallback(() => timelineRef.current?.restart(), []);
+
+  return { rootRef, replay };
+}