@mehshekari/gsap-motion 3.1.1 → 3.2.0

package/skill/scripts/lib/ast.mjs

@@ -21,10 +21,16 @@ const OPTIONS = {
  * `.ts` is read without JSX, because there `<T>(x) => x` is a generic and
  * `<Type>value` a cast; every other extension is read with it. A `.js` file
  * with JSX is common enough, and JSX never changes how plain JavaScript parses.
+ *
+ * A single-file component's `<script>` is read without JSX too: it is
+ * TypeScript as often as not, and the template where the angle brackets live is
+ * blanked out before it reaches here.
  */
 const TYPESCRIPT = Parser.extend(tsPlugin());
 const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
 
+const WITHOUT_JSX = /\.(?:[mc]?ts|vue|svelte|astro)$/;
+
 /**
  * Parses `source` as the grammar its `path` implies.
  *
@@ -34,7 +40,7 @@ const TYPESCRIPT_JSX = Parser.extend(tsPlugin({ jsx: true }));
  */
 export function parse(source, path) {
   const comments = [];
-  const parser = /\.[mc]?ts$/.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
+  const parser = WITHOUT_JSX.test(path) ? TYPESCRIPT : TYPESCRIPT_JSX;
   const ast = parser.parse(source, { ...OPTIONS, onComment: comments });
   return { ast, comments };
 }

package/skill/scripts/lib/rules.mjs

@@ -51,6 +51,8 @@ const HINT = {
     "Nothing reverts it on unmount, and React StrictMode runs it twice in development. Move it into the useGSAP body, or wrap the handler in contextSafe. A helper counts as inside only when every use of it is a call from inside a context.",
   unmanagedInstance:
     "Inside a context these register themselves and are reverted with it. Out here nothing is watching: move it into the useGSAP body, or keep the instance and revert/kill it from the cleanup.",
+  unrevertedContext:
+    "Keep it under a name and revert it when the component goes: `onUnmounted` in Vue, the function returned from `onMount` or `$effect` in Svelte, the `useEffect` cleanup in React, `astro:before-swap` in Astro. Everything created inside the context goes with it.",
   danglingListener:
     "A listener that survives unmount keeps the component's closure — and its DOM nodes — alive. Name the handler and remove it in the cleanup, or pass `{ signal }` from an AbortController and abort it there.",
   tweenPerEvent:
@@ -212,7 +214,7 @@ function listenerMethod(node) {
  * `followNames`, a handler passed by name is followed to its declaration when
  * the file declares exactly one function of that name.
  */
-function handlersFor(ast, events, { followNames = true } = {}) {
+function handlersFor(ast, events, { followNames = true, perFrame = false } = {}) {
   const handler = (expression) => {
     const node = unwrap(expression);
     if (node?.type === "CallExpression") return node;
@@ -242,6 +244,17 @@ function handlersFor(ast, events, { followNames = true } = {}) {
     if (node) handlers.push({ name: `on${prop[1]}`, node });
   }
 
+  /**
+   * R3F's `useFrame(callback)` is a per-frame scope of its own: what is inside
+   * runs on every rendered frame, whatever the pointer is doing.
+   */
+  if (perFrame) {
+    for (const call of findAll(ast, (node) => calleeName(node) === "useFrame")) {
+      const node = handler(call.arguments[0]);
+      if (node) handlers.push({ name: "useFrame", node });
+    }
+  }
+
   return handlers;
 }
 
@@ -493,6 +506,47 @@ export function pluginRegistrations(file) {
   return names;
 }
 
+/**
+ * The mount hooks each adapter uses. A context created in one of them lives as
+ * long as the component does, so something has to revert it when the component
+ * goes.
+ */
+const MOUNT_HOOKS = new Set([
+  "onMounted",
+  "onMount",
+  "onActivated",
+  "useEffect",
+  "useLayoutEffect",
+  "$effect",
+]);
+
+/**
+ * Which mount hook `node` was created in, or null. Astro has no hook: its
+ * equivalent is a listener for `astro:page-load`, which fires on the first load
+ * and after every view transition.
+ */
+function mountHook(ast, node) {
+  /** Nearest first, so a function's own parent is the entry after it. */
+  const ancestors = ancestorsOf(ast, node);
+
+  for (let i = 0; i < ancestors.length; i += 1) {
+    if (!isFunction(ancestors[i])) continue;
+    const parent = ancestors[i + 1];
+    if (parent?.type !== "CallExpression") continue;
+
+    const name = calleeName(parent);
+    if (MOUNT_HOOKS.has(name)) return `\`${name}\``;
+    if (
+      name?.endsWith("addEventListener") &&
+      staticString(parent.arguments[0]) === "astro:page-load"
+    ) {
+      return "the `astro:page-load` handler";
+    }
+  }
+
+  return null;
+}
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -575,6 +629,40 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "unreverted-context",
+    level: "warn",
+    description:
+      "A `gsap.context` created on mount — `onMounted`, `onMount`, `useEffect`, `astro:page-load` — that nothing reverts",
+    /**
+     * Every adapter's teardown rule, in one shape: a context built when the
+     * component mounts holds every tween, ScrollTrigger and matchMedia made
+     * inside it, and reverting it is the whole cleanup. Nothing reverts it here.
+     *
+     * Only contexts created in a mount hook are read. A context built in a
+     * function the module exports — the vanilla `mountReveal(root)` shape — hands
+     * its teardown to the caller, and this file cannot see whether the caller
+     * calls it.
+     */
+    test(file) {
+      const contexts = findAll(
+        file.ast,
+        (node) => calleeName(node) === "gsap.context",
+      );
+
+      return contexts.flatMap((call) => {
+        const hook = mountHook(file.ast, call);
+        if (!hook || tornDown(file.ast, call)) return [];
+        return [
+          {
+            index: call.start,
+            message: `The \`gsap.context\` created in ${hook} is never reverted.`,
+            hint: HINT.unrevertedContext,
+          },
+        ];
+      });
+    },
+  },
   {
     id: "dangling-listener",
     level: "warn",
@@ -699,14 +787,20 @@ export const RULES = [
         );
       });
 
-      return handlersFor(file.ast, STATE_HOT_EVENTS, { followNames: false }).flatMap(
+      return handlersFor(file.ast, STATE_HOT_EVENTS, {
+        followNames: false,
+        perFrame: true,
+      }).flatMap(
         (handler) =>
           setters
             .filter((setter) => contains(handler.node, setter))
             .filter((setter) => !debounced(handler, setter))
             .map((setter) => ({
               index: setter.start,
-              message: `React state setter inside a ${handler.name} handler.`,
+              message:
+                handler.name === "useFrame"
+                  ? "React state setter inside a `useFrame` callback, which runs every frame."
+                  : `React state setter inside a ${handler.name} handler.`,
               hint: HINT.statePerEvent,
             })),
       );

package/skill/scripts/lib/source.mjs

@@ -12,7 +12,19 @@ import { extname, join, relative } from "node:path";
 
 import { parse } from "./ast.mjs";
 
-const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs"]);
+const SOURCE_EXTENSIONS = new Set([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+]);
+
+/** A single-file component: only its `<script>` blocks are code. */
+const SINGLE_FILE = /\.(?:vue|svelte|astro)$/;
 const SKIP_DIRECTORIES = new Set([
   "node_modules",
   ".next",
@@ -131,6 +143,41 @@ export function lineAt(source, index) {
   return line;
 }
 
+/**
+ * A single-file component with everything outside its `<script>` blocks blanked
+ * out, keeping every newline and every offset — so what reaches the parser is
+ * JavaScript, and a finding still points at the right line of the `.vue`,
+ * `.svelte` or `.astro` file.
+ *
+ * A `<script>` whose `type` is not JavaScript — JSON-LD, an import map, a
+ * template — is blanked with the markup. Astro's `---` frontmatter runs on the
+ * server and animates nothing, so it is left out too; the client `<script>` is
+ * what this reads.
+ */
+export function scriptsOnly(raw) {
+  const blank = (text) => text.replace(/[^\n]/g, " ");
+  const JAVASCRIPT = /^(?:module|text\/javascript|application\/javascript|ts|tsx)$/i;
+  const open = /<script\b([^>]*)>/gi;
+
+  let out = "";
+  let index = 0;
+
+  for (let tag = open.exec(raw); tag; tag = open.exec(raw)) {
+    const start = tag.index + tag[0].length;
+    const close = raw.indexOf("</script", start);
+    const end = close === -1 ? raw.length : close;
+    const type = tag[1].match(/\btype\s*=\s*["']([^"']*)["']/i)?.[1];
+    const code = !type || JAVASCRIPT.test(type.trim());
+
+    out += blank(raw.slice(index, start));
+    out += code ? raw.slice(start, end) : blank(raw.slice(start, end));
+    index = end;
+    open.lastIndex = end;
+  }
+
+  return out + blank(raw.slice(index));
+}
+
 /**
  * A file plus everything the rules need, from its text.
  *
@@ -139,7 +186,8 @@ export function lineAt(source, index) {
  * points run the rules on the same parse of the same characters.
  */
 export function fromText(raw, path, display = path) {
-  const code = stripComments(raw);
+  const source = SINGLE_FILE.test(path) ? scriptsOnly(raw) : raw;
+  const code = stripComments(source);
 
   /**
    * Parsed on first use, and once. Most files in a project never mention GSAP,
@@ -151,7 +199,7 @@ export function fromText(raw, path, display = path) {
   const tree = () => {
     if (parsed === undefined) {
       try {
-        parsed = { ...parse(raw, path), error: null };
+        parsed = { ...parse(source, path), error: null };
       } catch (error) {
         parsed = {
           ast: null,

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 |