@mehshekari/gsap-motion 2.1.0 → 3.1.0

package/NOTICE.md

@@ -3,6 +3,65 @@
 This skill — its instructions, references, presets, examples, templates and
 scripts — is released under the MIT License. See [LICENSE](LICENSE).
 
+## Third-party code in the audit
+
+`scripts/lib/vendor/parser.mjs` bundles two MIT-licensed packages, so the audit
+can read JavaScript and TypeScript without installing anything. It is generated
+from the versions its first lines name.
+
+### acorn
+
+```text
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+### @sveltejs/acorn-typescript
+
+```text
+MIT License
+
+Copyright (c) 2022 Tyreal Hu
+Copyright (c) 2025 The Svelte Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## GSAP is licensed separately
 
 **GSAP is not part of this skill, and it is not MIT-licensed.** The code this

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.1.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.1.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/NOTICE.md

@@ -3,6 +3,65 @@
 This skill — its instructions, references, presets, examples, templates and
 scripts — is released under the MIT License. See [LICENSE](LICENSE).
 
+## Third-party code in the audit
+
+`scripts/lib/vendor/parser.mjs` bundles two MIT-licensed packages, so the audit
+can read JavaScript and TypeScript without installing anything. It is generated
+from the versions its first lines name.
+
+### acorn
+
+```text
+MIT License
+
+Copyright (C) 2012-2022 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+### @sveltejs/acorn-typescript
+
+```text
+MIT License
+
+Copyright (c) 2022 Tyreal Hu
+Copyright (c) 2025 The Svelte Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
 ## GSAP is licensed separately
 
 **GSAP is not part of this skill, and it is not MIT-licensed.** The code this

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.1.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/audit-gsap.mjs

@@ -13,10 +13,12 @@
  * 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.
+ * It reads each file's syntax tree — with a vendored parser, so nothing is
+ * installed — and follows what can be followed inside one file: aliases, a
+ * helper called only from a context, a timeline kept under a name. It does not
+ * follow calls into other files. A file it cannot parse is reported as
+ * `not-parsed`, never passed as clean. 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:
@@ -29,7 +31,7 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { RULES } from "./lib/rules.mjs";
+import { pluginRegistrations, RULES } from "./lib/rules.mjs";
 import { collect, lineAt, load } from "./lib/source.mjs";
 
 /**
@@ -82,6 +84,7 @@ function waived(source, line, ruleId) {
 // --- Run ---------------------------------------------------------------------
 
 const findings = [];
+const sources = [];
 
 for (const path of paths) {
   for (const file of collect(path)) {
@@ -93,20 +96,54 @@ for (const path of paths) {
      */
     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;
-
+    /**
+     * What was not checked is reported as not checked. A file that uses GSAP
+     * and does not parse gets no rule's verdict — a silent skip would read as
+     * clean.
+     */
+    if (source.parseError) {
+      const { line, message } = source.parseError;
+      if (!waived(source.raw, line, "not-parsed")) {
         findings.push({
-          rule: rule.id,
-          level: rule.level,
+          rule: "not-parsed",
+          level: "info",
           file: source.display,
           line,
-          message: hit.message,
-          hint: hit.hint,
+          message: `Not checked: the file could not be parsed (${message}).`,
+          hint: "No rule ran on this file. If it is valid JavaScript or TypeScript, the audit's parser is wrong — report it with this line.",
         });
       }
+      continue;
+    }
+
+    sources.push(source);
+  }
+}
+
+/**
+ * Plugin registration is global: `gsap.registerPlugin(ScrollTrigger)` in one
+ * module registers it for every other. What the audited files register between
+ * them is collected before any rule runs, so a section that imports a plugin
+ * the app's entry registers is not reported as unregistered.
+ */
+const registered = new Set(sources.flatMap((source) => [...pluginRegistrations(source)]));
+
+for (const source of sources) {
+  source.registeredElsewhere = registered;
+
+  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,
+      });
     }
   }
 }