@mehshekari/gsap-motion 2.1.0 → 3.0.0

package/README.md

@@ -28,7 +28,7 @@ The audit needs no install. Pin the version, so a new rule cannot fail your
 build without warning:
 
 ```json
-"lint": "eslint && npx @mehshekari/gsap-motion@2.1.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.0.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Install the gsap-creative-animation Agent Skill, and audit GSAP animation for leaks, jank and accessibility failures — with npx.",
   "keywords": [
     "gsap",

package/skill/SKILL.md

@@ -4,7 +4,7 @@ description: Senior motion engineer for GSAP. Turns a visual or interaction idea
 license: MIT. See LICENSE; GSAP itself is licensed separately, see NOTICE.md
 compatibility: Any Agent Skills client; written for Claude Code. GSAP 3.13+, where every plugin is free. React guidance targets @gsap/react 2.x, React 18/19 and the Next.js App Router. The audit scripts need Node.js 18+ and nothing else.
 metadata:
-  version: "2.1.0"
+  version: "3.0.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -160,8 +160,9 @@ Both scripts catch failures that are **silent**. Run them from the project
 root; `<skill-dir>` is where this skill is installed.
 
 ```bash
-# Leaks, per-event tweens, layout properties, eased loops, shared plugin ids,
-# unregistered plugins, dev tooling left in. Exit 1 on an error.
+# Leaks, per-event tweens, layout properties, eased loops, an onComplete that
+# never fires, shared plugin ids, unregistered plugins, dev tooling left in.
+# Exit 1 on an error.
 node <skill-dir>/scripts/audit-gsap.mjs [path...]     # default: src
 node <skill-dir>/scripts/audit-gsap.mjs src --quiet   # errors only
 node <skill-dir>/scripts/audit-gsap.mjs src --json    # machine-readable

package/skill/example/cinematic-intro.md

@@ -119,10 +119,15 @@ tl.addLabel("hold")
 ```
 
 Get this wrong and nothing visibly breaks: the ceiling still lifts the curtain,
-just late, on every visit. That is exactly why it is worth checking.
-
-**The page renders underneath the whole time.** The curtain only covers. A
-JavaScript failure leaves the visitor on the site, not behind a curtain.
+just late, on every visit. That is exactly why it is worth checking, and why
+`audit-gsap` reports it as an error, `never-completes`.
+
+**The page renders underneath, and the curtain has a CSS exit.** The curtain
+only covers. But it is in the server-rendered HTML, so a visitor whose
+JavaScript never runs would get the curtain and nothing able to remove it — the
+ceiling is JavaScript too. A CSS animation that hides it a little after the
+ceiling is the exit that needs no script; see
+[cinematic.md](../preset/cinematic.md#without-javascript).
 
 **Session gating in the layout effect, behind storage's real failures.**
 Storage cannot be read during render without the server and client

package/skill/preset/cinematic.md

@@ -108,7 +108,39 @@ return () => window.clearTimeout(ceiling);
 
 Keep the total under ~3s. Play it once per session, not once per route — an
 intro on every navigation is an obstacle. Render the page underneath the whole
-time so a JavaScript failure cannot trap the visitor behind a curtain.
+time, so the curtain only ever covers.
+
+## Without JavaScript
+
+Rendering the page underneath is necessary, and not enough. A curtain rendered
+on the server — which a client component is, too — is in the HTML, so a visitor
+whose JavaScript never runs gets the curtain and nothing able to remove it: a
+blocked script, a chunk that fails to load after a deploy, a hydration error.
+The ceiling above is JavaScript as well.
+
+Give the curtain an exit that needs no script — a CSS animation that hides it a
+little after the JavaScript ceiling:
+
+```css
+@keyframes curtain-exit {
+  to { opacity: 0; visibility: hidden; }
+}
+
+[data-curtain] {
+  animation: curtain-exit 0.3s ease-out 5s forwards;
+}
+```
+
+- **It outranks GSAP.** Animations beat inline styles in the cascade, so once it
+  has run, an `autoAlpha` tween cannot bring the curtain back — verified in
+  Chrome. On the normal path the curtain is gone long before the delay ends.
+- **The delay counts from the HTML, not from hydration.** Set it beyond the
+  JavaScript ceiling plus a slow hydration. At worst, a page that took that
+  long to become interactive plays its intro under an invisible curtain.
+- **`visibility: hidden` is the part that matters.** It removes the curtain from
+  hit-testing, so the page is clickable, not just visible.
+- A `<noscript>` style only covers JavaScript that is switched off, not
+  JavaScript that loaded and failed. Use the animation.
 
 ## Reduced motion
 

package/skill/preset/loader.md

@@ -116,10 +116,13 @@ return () => window.clearTimeout(ceiling);
 
 A timeline containing an infinitely repeating child **never completes**, so its
 `onComplete` never fires. Give the timeline a finite beat of its own to end on,
-or drive the handover from elsewhere.
+or drive the handover from elsewhere. `audit-gsap` reports it as
+`never-completes`.
 
-Render the real page underneath the whole time, so a visitor whose JavaScript
-fails gets the site rather than a permanent curtain.
+Render the real page underneath the whole time. That alone does not save a
+visitor whose JavaScript never runs: a server-rendered curtain is then all they
+get, and the ceiling is JavaScript too. Give the curtain a CSS exit as well —
+see [cinematic.md](cinematic.md#without-javascript).
 
 ## Exit
 

package/skill/reference/core-gsap.md

@@ -69,6 +69,11 @@ rather than fighting over `transform`:
   transformOrigin: "50% 100%" }
 ```
 
+**On SVG, the origin comes with the first transform.** One that arrives after
+the element is already scaled, rotated or skewed — in a `fromTo`'s to-vars —
+leaves it offset, silently. Put it in the from-vars; see
+[svg.md](svg.md#transform-origin).
+
 `xPercent`/`yPercent` are percentages of the element's own size, which is what
 centres something without knowing its dimensions.
 
@@ -117,9 +122,6 @@ gsap.utils.selector(ref);                     // scoped selector function
 gsap.utils.shuffle(items);
 ```
 
-`mapRange` and `wrap` are the two that most often replace ten lines of
-hand-rolled maths in a scroll or marquee.
-
 ## `quickTo` and `quickSetter`
 
 For values driven by a high-frequency event — pointer move, scroll, rAF —
@@ -228,6 +230,3 @@ question — see [motion-design.md](motion-design.md).
 CustomEase.create("brand", "M0,0 C0.16,1 0.3,1 1,1");
 gsap.to(el, { y: 0, ease: "brand" });
 ```
-
-`CustomWiggle` and `CustomBounce` register named eases the same way, for shake
-and impact without hand-built keyframes.

package/skill/reference/svg.md

@@ -168,6 +168,38 @@ rendered. `ease: "none"` on anything looping.
 To author a path by eye, use `MotionPathHelper` in development only and bake the
 `d` it gives you. It is an editor — never ship it.
 
+## Transform origin
+
+Set `transformOrigin` — or `svgOrigin` — no later than the first scale, rotation
+or skew. When the origin of an SVG element that is already transformed changes,
+GSAP adds a translate that holds the element where it is (`smoothOrigin`), and
+that translate stays after the tween.
+
+A `fromTo` renders its from-vars first, so this is the shape that breaks:
+
+```ts
+// ✗ ends a whole radius up and left of where it should be
+gsap.fromTo(dot, { scale: 0 }, { scale: 1, transformOrigin: "50% 50%" });
+
+// ✓
+gsap.fromTo(dot, { scale: 0, transformOrigin: "50% 50%" }, { scale: 1 });
+```
+
+Measured in gsap 3.15 in Chrome, with the origin only in the to-vars:
+
+| From-vars | The element ends |
+|---|---|
+| `scale: 0` | offset by the origin's distance from its own top-left corner |
+| `scale: 0.94` | offset by that distance × 0.06 — a few pixels, easy to miss |
+| `rotation: 90`, `skewX: 20` | offset too |
+| `x: 20`, `scale: 1` | where it should — a translation or an identity start is safe |
+
+A `gsap.set(el, { scale: 0 })` followed by a `to` that brings the origin does the
+same. HTML elements are unaffected, and a mask or clip path makes no difference.
+Any one of these fixes it: the origin in the from-vars, a `gsap.set` of the
+origin before the tween, or `smoothOrigin: false`. `audit-gsap` reports the
+`fromTo` shape as `late-transform-origin`.
+
 ## Masks and clip paths
 
 Often better than either plugin, and cheaper. A mask reveal is a transform on a
@@ -184,8 +216,8 @@ rect inside a `<mask>`:
 gsap.from("[data-wipe]", { scaleX: 0, transformOrigin: "0% 50%", duration: 0.8 });
 ```
 
-Greyscale in a mask is an alpha stop, not a colour — the one literal this
-repo's colour rule allows.
+Greyscale in a mask is an alpha stop, not a colour — the one literal a
+token-only colour rule has no reason to refuse.
 
 ## Choosing
 

package/skill/reference/timeline.md

@@ -86,7 +86,8 @@ tl.from("[data-mark]", { ... })          // plays once
 `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.
+of its own to end on, or drive the handover from elsewhere. `audit-gsap`
+reports it as `never-completes`.
 
 ## Paused timelines as state
 

package/skill/scripts/lib/rules.mjs

@@ -126,10 +126,11 @@ function listenerCalls(code, method) {
 }
 
 /**
- * The argument spans of the `.to(` / `.from(` / `.fromTo(` calls chained on
- * from `cursor`, following the chain through labels and other calls.
+ * The argument spans of the `.to(` / `.from(` / `.fromTo(` calls — or of
+ * whichever `methods` are asked for — chained on from `cursor`, following the
+ * chain through labels and other calls.
  */
-function chainedTweens(code, cursor) {
+function chainedTweens(code, cursor, methods = ["to", "from", "fromTo"]) {
   const spans = [];
   for (;;) {
     const next = code.slice(cursor).match(/^\s*\.\s*([\w$]+)\s*\(/);
@@ -137,11 +138,83 @@ function chainedTweens(code, cursor) {
     const open = cursor + next[0].length - 1;
     const span = parenSpan(code, open);
     if (!span) return spans;
-    if (["to", "from", "fromTo"].includes(next[1])) spans.push([open, span[1]]);
+    if (methods.includes(next[1])) spans.push([open, span[1]]);
     cursor = span[1] + 1;
   }
 }
 
+/**
+ * What is added to the timeline created by the `gsap.timeline(` match `call`,
+ * whose arguments close at `close`: the argument spans of its children, and
+ * whether an `onComplete` is attached through `eventCallback`.
+ *
+ * Both are read from the chain on the call itself and from every chain on the
+ * variable it was kept in — including one that starts with a label, which is
+ * how a sequence usually opens. Those uses are read only up to the next
+ * declaration of the same name, so two functions that each keep a `tl` do not
+ * lend each other their children.
+ */
+function timelineCalls(code, call, close) {
+  const CHILDREN = ["to", "from", "fromTo", "add"];
+  const children = chainedTweens(code, close + 1, CHILDREN);
+  const callbacks = chainedTweens(code, close + 1, ["eventCallback"]);
+
+  const kept = code
+    .slice(Math.max(0, call.index - 80), call.index)
+    .match(/([\w$]+)\s*=\s*$/);
+  if (kept) {
+    const name = kept[1].replace(/\$/g, "\\$");
+    const redeclared = code
+      .slice(close)
+      .search(new RegExp(`\\b(?:const|let|var)\\s+${name}\\b`));
+    const end = redeclared === -1 ? code.length : close + redeclared;
+    const uses = new RegExp(`(?<![\\w$.])${name}(?=\\s*\\.\\s*[\\w$]+\\s*\\()`, "g");
+
+    for (const use of code.slice(close, end).matchAll(uses)) {
+      const cursor = close + use.index + use[0].length;
+      children.push(...chainedTweens(code, cursor, CHILDREN));
+      callbacks.push(...chainedTweens(code, cursor, ["eventCallback"]));
+    }
+  }
+
+  const completes = callbacks.some(([open, end]) =>
+    /^\(\s*["'`]onComplete["'`]/.test(code.slice(open, end)),
+  );
+  return { children, completes };
+}
+
+/**
+ * The top-level arguments of the call whose parentheses span `[open, close]`,
+ * as `[start, end]` pairs. A comma inside brackets, braces or a string does not
+ * separate arguments.
+ */
+function callArgs(code, open, close) {
+  const args = [];
+  let depth = 0;
+  let quote = "";
+  let start = open + 1;
+
+  for (let i = open + 1; i < close; i += 1) {
+    const c = code[i];
+
+    if (quote) {
+      if (c === "\\") i += 1;
+      else if (c === quote) quote = "";
+      continue;
+    }
+    if (c === '"' || c === "'" || c === "`") quote = c;
+    else if ("([{".includes(c)) depth += 1;
+    else if (")]}".includes(c)) depth -= 1;
+    else if (c === "," && depth === 0) {
+      args.push([start, i]);
+      start = i + 1;
+    }
+  }
+
+  if (code.slice(start, close).trim()) args.push([start, close]);
+  return args;
+}
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -431,6 +504,125 @@ export const RULES = [
       return findings.slice(0, 1);
     },
   },
+  /**
+   * An `onComplete` that can never run. A `repeat: -1` tween never completes,
+   * and a timeline holding one is given an effectively infinite duration —
+   * 1e10 seconds, measured in gsap 3.15, where neither callback fired — so its
+   * `onComplete` never fires either, and a short tween added after the loop
+   * does not change that.
+   *
+   * Nothing reports it. Whatever the callback was meant to start simply does not
+   * start: behind a ceiling timer the visitor waits for the ceiling on every
+   * visit, and without one the curtain never lifts. The guidance described this
+   * for a whole release and it still shipped, which is why it is a rule.
+   */
+  {
+    id: "never-completes",
+    level: "error",
+    test(file) {
+      /** `-1` exactly: the boundary after it rejects `-10`. */
+      const endless = /\brepeat\s*:\s*-1\b/;
+      const findings = [];
+
+      for (const call of find(
+        file.code,
+        /\bgsap\s*\.\s*(to|from|fromTo|timeline)\s*\(/g,
+      )) {
+        const open = call.index + call[0].length - 1;
+        const span = parenSpan(file.code, open);
+        if (!span) continue;
+        const args = file.code.slice(open, span[1]);
+        const waits = /\bonComplete\b/.test(args);
+
+        const own = args.search(endless);
+        if (waits && own !== -1) {
+          findings.push({
+            index: open + own,
+            message: `\`gsap.${call[1]}\` repeats forever, so its \`onComplete\` can never run.`,
+            hint: "An endless repeat never completes. Use `onRepeat` for something that should happen every cycle, or give it a finite `repeat`.",
+          });
+          continue;
+        }
+        if (call[1] !== "timeline") continue;
+
+        const { children, completes } = timelineCalls(file.code, call, span[1]);
+        if (!waits && !completes) continue;
+
+        for (const [start, end] of children) {
+          const at = file.code.slice(start, end).search(endless);
+          if (at === -1) continue;
+          findings.push({
+            index: start + at,
+            message:
+              "An endlessly repeating child in a timeline with an `onComplete`, which therefore never fires.",
+            hint: 'The child gives the timeline an effectively infinite duration, and a tween added after it does not end it. Hand over at a position instead — `.call(fn, [], "label+=0.5")` fires when the playhead passes — or run the loop as its own tween outside the timeline.',
+          });
+          break;
+        }
+      }
+
+      return findings;
+    },
+  },
+  /**
+   * A transform origin that arrives after the transform it belongs to.
+   *
+   * When the origin of an SVG element that is already scaled, rotated or
+   * skewed changes, GSAP's `smoothOrigin` adds a translate that holds the
+   * element where it is. A `fromTo` renders its from-vars first, so an origin
+   * given only in its to-vars lands on an element already at its starting
+   * transform, and the translate outlives the tween. Measured in gsap 3.15 in
+   * Chrome: a circle grown from 0 about its centre ends a whole radius up and
+   * left; rotation and skew offset it too; a translation, an identity start or
+   * an HTML element does not.
+   *
+   * `warn`, not `error`: nothing here can tell an SVG target from an HTML one.
+   */
+  {
+    id: "late-transform-origin",
+    level: "warn",
+    test(file) {
+      const ORIGIN = /\b(?:transformOrigin|svgOrigin)\s*:/;
+      const TRANSFORM = /\b(scale[XY]?|rotation|rotate|skew[XY])\s*:\s*([^,}\n]+)/g;
+      /** Whether a from-value leaves the element untransformed. */
+      const identity = (prop, value) => {
+        const v = value.trim().replace(/^["'`]|["'`]$/g, "");
+        return prop.startsWith("scale")
+          ? /^1(?:\.0+)?$/.test(v)
+          : /^-?0(?:\.0+)?(?:deg|rad)?$/.test(v);
+      };
+
+      return find(file.code, /\.\s*fromTo\s*\(/g).flatMap((call) => {
+        const open = call.index + call[0].length - 1;
+        const span = parenSpan(file.code, open);
+        if (!span) return [];
+        const [, from, to] = callArgs(file.code, open, span[1]);
+        if (!from || !to) return [];
+
+        const fromVars = file.code.slice(from[0], from[1]);
+        const toVars = file.code.slice(to[0], to[1]);
+        const origin = toVars.search(ORIGIN);
+        if (origin === -1 || ORIGIN.test(fromVars)) return [];
+        if (/\bsmoothOrigin\s*:\s*false\b/.test(toVars)) return [];
+        if (
+          [...fromVars.matchAll(TRANSFORM)].every(([, prop, value]) =>
+            identity(prop, value),
+          )
+        ) {
+          return [];
+        }
+
+        return [
+          {
+            index: to[0] + origin,
+            message:
+              "The transform origin is only in this `fromTo`'s to-vars, while its from-vars scale, rotate or skew.",
+            hint: "On an SVG element GSAP holds the element in place when its origin changes, and that correction outlives the tween: it ends offset, silently — a circle grown from 0 about its centre lands a whole radius off. Put `transformOrigin` or `svgOrigin` in the from-vars, or set it before the tween. HTML elements are unaffected.",
+          },
+        ];
+      });
+    },
+  },
   {
     id: "shared-plugin-id",
     level: "error",