@mehshekari/gsap-motion 4.1.0 → 4.2.1

package/README.md

@@ -32,7 +32,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@4.0.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.2.1 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": "4.1.0",
+  "version": "4.2.1",
   "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 22+ and nothing else.
 metadata:
-  version: "4.1.0"
+  version: "4.2.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

package/skill/reference/accessibility.md

@@ -54,6 +54,21 @@ mm.add(
 
 ```
 
+**Both conditions are required, and dropping `motion` breaks everything.** The
+callback runs only while at least one named condition matches. With `reduced`
+alone, a visitor who has no preference — nearly all of them — matches nothing,
+so the callback never runs and **the page ships with no animation at all**,
+silently: no error, and every test with reduced motion on still passes. The
+audit reports it as `matchmedia-never-runs`.
+
+A reduced-only `add` is still correct when it does not branch — the shape below
+is GSAP's own, and each callback is meant to run only for its own visitors:
+
+```ts
+mm.add("(prefers-reduced-motion: no-preference)", () => { /* the animation */ });
+mm.add("(prefers-reduced-motion: reduce)", () => { /* the end states */ });
+```
+
 Built inside a `useGSAP` body this needs no explicit teardown — `matchMedia`
 registers with the active context and is reverted with it.
 

package/skill/reference/refine.md

@@ -147,3 +147,30 @@ Verification
 
 Say what you did not check, too. "Not checked" is information; silence reads as
 "checked and fine", and that is the one thing it must never mean.
+
+### "Verified" names what you saw
+
+**A check is a measurement, not a verb.** "Verified live", "tested at 390px" and
+"works as expected" say that something was run; they do not say what came back,
+so nobody can tell whether it would have caught the failure.
+
+A head-to-head test made the cost concrete. An answer written with this skill
+reported *"verified live, no horizontal overflow at 390px"* — and shipped two
+bugs that a 390px browser shows at a glance: the visual pushed below the fold,
+and a label invisible through its whole first state. Overflow was the one thing
+checked, and it was not what was broken.
+
+So a line states the value observed, at a time and a size:
+
+| Not this | This |
+|---|---|
+| verified live | badge label opacity 1 at t=0 and at every state label, 1280x800 |
+| works on mobile | 390x844: the visual's top edge at 96px, above the fold; no overflow |
+| reduced motion handled | reduced emulated: heading and lead at end state, no tween ran |
+| animation runs | `review`: first motion at 410ms; 0 elements invisible for the whole window |
+
+**Check the failure, not the feature.** A reveal that works is easy to observe;
+the failures that ship are an element that never appears, one that appears too
+late, and one that is off screen at the size you did not look at. Look for those
+by name. And a claim you did not observe is worse than "not checked": it tells
+the reader to stop looking.

package/skill/reference/timeline.md

@@ -186,3 +186,35 @@ ScrollTrigger's `scrub` is this same mechanism with scroll as the value.
 | 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 |
+| An element is invisible until much later than it should be | several `from`/`fromTo` on it, each applying its start state when built |
+
+### `from` renders when it is built, not when it plays
+
+`from` and `fromTo` default to `immediateRender: true`: the start state is
+written to the element **the moment the tween is created**, not when the
+playhead reaches it. With one tween per element that is exactly what you want —
+nothing flashes before the entrance.
+
+Build several against the same element and they all write at once, in order, so
+**the last one wins and holds the element there until the playhead arrives.**
+A helper that adds a beat per state is the usual way in: one call site, run in
+a loop, and a label that stays hidden through every state before the last.
+
+```ts
+const addBeat = (state: string) => {
+  tl.addLabel(state).fromTo(
+    badge,
+    { autoAlpha: 0, y: 6 },
+    { autoAlpha: 1, y: 0, immediateRender: false }, // written when it plays
+    state,
+  );
+};
+
+gsap.set(badge, { autoAlpha: 1, y: 0 }); // the first state, set once, on purpose
+STATES.forEach(addBeat);
+```
+
+The conflict is per property. Two tweens on one element that set **different**
+properties — one fading in on `opacity`, another turning on `rotationY` — hide
+nothing, and need no change. The audit reports the shape that does hide:
+`stacked-from`.

package/skill/scripts/lib/ast.mjs

@@ -478,12 +478,43 @@ export function gsapContexts(root) {
     }
   }
 
-  const scopes = findAll(
-    root,
-    (node) =>
-      node.type === "CallExpression" &&
-      (isHook(node) || calleeName(node) === "gsap.context" || safe.has(bareName(node))),
-  ).flatMap((call) => call.arguments);
+  /**
+   * A matchMedia is a context too: `mm.revert()` reverts what its `add`
+   * callbacks made. Its callback is recognised on `gsap.matchMedia().add` and on
+   * any name the file assigns `gsap.matchMedia()` to, followed when it is handed
+   * over by name. Whether the matchMedia itself is ever reverted is
+   * `unmanaged-instance`'s to report, not a reason to distrust its callbacks.
+   */
+  const matchMedias = new Set(
+    findAll(
+      root,
+      (node) =>
+        (node.type === "VariableDeclarator" &&
+          Boolean(node.init) &&
+          calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
+        (node.type === "AssignmentExpression" &&
+          calleeName(unwrap(node.right)) === "gsap.matchMedia"),
+    )
+      .map((node) => dottedName(node.type === "VariableDeclarator" ? node.id : node.left))
+      .filter(Boolean),
+  );
+  const isMatchMediaAdd = (node) => {
+    if (methodName(node) !== "add") return false;
+    const object = unwrap(unwrap(node.callee).object);
+    return calleeName(object) === "gsap.matchMedia" || matchMedias.has(dottedName(object));
+  };
+
+  const scopes = [
+    ...findAll(
+      root,
+      (node) =>
+        node.type === "CallExpression" &&
+        (isHook(node) || calleeName(node) === "gsap.context" || safe.has(bareName(node))),
+    ).flatMap((call) => call.arguments),
+    ...findAll(root, isMatchMediaAdd).flatMap((call) =>
+      call.arguments.map((argument) => resolveFunction(root, argument)).filter(Boolean),
+    ),
+  ];
 
   const counts = new Map();
   const functions = new Map();

package/skill/scripts/lib/rules.mjs

@@ -47,6 +47,10 @@ import {
 
 /** What each rule says, in one place. */
 const HINT = {
+  matchMediaNeverRuns:
+    "A matchMedia callback runs only while at least one of its named conditions matches, and a visitor with no reduced-motion preference matches none of these — so the branch for them is dead code and nothing animates. Add `motion: \"(prefers-reduced-motion: no-preference)\"` beside it, or use two separate `add` calls.",
+  stackedFrom:
+    "A `from` or `fromTo` applies its start state the moment it is built. Built more than once against the same element, the last one wins, and holds that element at its start state until the playhead reaches it — invisible, if the start state hides it. Pass `immediateRender: false`, and set the element's first state yourself with `gsap.set`.",
   orphanTween:
     "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:
@@ -1598,4 +1602,355 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "matchmedia-never-runs",
+    level: "warn",
+    description:
+      "A matchMedia callback that branches on reduced motion, when every condition needs it",
+    /**
+     * `mm.add({ reduced: "(prefers-reduced-motion: reduce)" }, (context) => …)`
+     * whose callback branches on the preference. The callback runs only while a
+     * named condition matches, and a visitor with no preference matches none —
+     * so the branch written for them never runs, and neither does the
+     * animation in it. Found in a head-to-head test on a real hero, where the
+     * whole page shipped without motion, and again in phase 8's first round.
+     *
+     * Branching is the whole signal: reading `conditions`, or asking
+     * `window.matchMedia` about reduced motion inside the callback. A
+     * reduced-only `add` that does not branch is GSAP's documented pattern for
+     * setting end states, meant to run for those visitors only, and is correct.
+     *
+     * The conditions are read when they are written in the call, or kept in a
+     * `const` the file declares once. An imported object, or a `let` that may be
+     * reassigned, cannot be judged here and is left alone.
+     */
+    test(file) {
+      const REDUCE = /prefers-reduced-motion\s*:\s*reduce/i;
+      const PREFERENCE = /prefers-reduced-motion/i;
+
+      /** Names bound to `gsap.matchMedia()` in this file, at declaration or later. */
+      const media = new Set(
+        findAll(
+          file.ast,
+          (node) =>
+            (node.type === "VariableDeclarator" &&
+              node.id.type === "Identifier" &&
+              /**
+               * `let tl;` has no initializer, and `calleeName` does not accept
+               * null. Every fixture initialised its declarations, so 133 passing
+               * tests missed this; the first real project threw on it and took
+               * the whole audit down with it.
+               */
+              Boolean(node.init) &&
+              calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
+            (node.type === "AssignmentExpression" &&
+              node.left.type === "Identifier" &&
+              calleeName(unwrap(node.right)) === "gsap.matchMedia"),
+        ).map((node) => (node.type === "VariableDeclarator" ? node.id.name : node.left.name)),
+      );
+
+      const onMatchMedia = (call) => {
+        const callee = unwrap(call.callee);
+        if (callee?.type !== "MemberExpression") return false;
+        const object = unwrap(callee.object);
+        if (object?.type === "Identifier") return media.has(object.name);
+        return calleeName(object) === "gsap.matchMedia";
+      };
+
+      /** The conditions as written: in the call, or in a `const` the file declares once. */
+      const conditionsOf = (argument) => {
+        const target = unwrap(argument);
+        if (target?.type !== "Identifier") return target;
+        const declarators = findAll(
+          file.ast,
+          (node) =>
+            node.type === "VariableDeclarator" &&
+            node.id.type === "Identifier" &&
+            node.id.name === target.name,
+        );
+        if (declarators.length !== 1) return null;
+        const [declarator] = declarators;
+        return parentOf(file.ast, declarator)?.kind === "const" ? unwrap(declarator.init) : null;
+      };
+
+      /** Every condition needs reduced motion: one query string, or an object of them. */
+      const everyReduces = (conditions) => {
+        const query = staticString(conditions);
+        if (typeof query === "string") return REDUCE.test(query);
+        if (conditions?.type !== "ObjectExpression" || !conditions.properties.length) return false;
+        return conditions.properties.every((property) => {
+          const value = staticString(property.value);
+          return typeof value === "string" && REDUCE.test(value);
+        });
+      };
+
+      /** Does the callback read its conditions, or ask the browser about reduced motion? */
+      const branches = (fn) => {
+        const asksTheBrowser =
+          findAll(fn.body, (node) => {
+            if (node.type !== "CallExpression") return false;
+            const name = calleeName(node);
+            if (name !== "window.matchMedia" && name !== "matchMedia") return false;
+            const query = staticString(node.arguments[0]);
+            return typeof query === "string" && PREFERENCE.test(query);
+          }).length > 0;
+        if (asksTheBrowser) return true;
+
+        const [param] = fn.params;
+        if (!param) return false;
+        if (param.type === "ObjectPattern") {
+          return param.properties.some((p) => keyName(p) === "conditions");
+        }
+        if (param.type !== "Identifier") return false;
+        return findAll(fn.body, (node) => {
+          const member = unwrap(node);
+          return (
+            member?.type === "MemberExpression" &&
+            !member.computed &&
+            unwrap(member.object)?.type === "Identifier" &&
+            unwrap(member.object).name === param.name &&
+            member.property.name === "conditions"
+          );
+        }).length > 0;
+      };
+
+      return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node))
+        .filter((call) => {
+          if (!everyReduces(conditionsOf(call.arguments[0]))) return false;
+          const callback = resolveFunction(file.ast, call.arguments[1]);
+          return Boolean(callback) && branches(callback);
+        })
+        .map((call) => ({
+          index: call.start,
+          message:
+            "This matchMedia callback branches on reduced motion, but every condition needs reduced motion — so it never runs for a visitor without that preference.",
+          hint: HINT.matchMediaNeverRuns,
+        }));
+    },
+  },
+  {
+    id: "stacked-from",
+    level: "warn",
+    description:
+      "A timeline's `from` or `fromTo` built more than once against the same target",
+    /**
+     * A `from` or `fromTo` on a timeline, without `immediateRender: false`,
+     * that is built more than once against the same element: written out
+     * twice, or inside a loop, or inside a helper a loop calls. Each applies
+     * its start state the moment it is built, so the last one wins and holds
+     * the element hidden until the playhead arrives. Found in a real hero,
+     * where one call site in a helper ran six times and a badge stayed
+     * invisible through the whole first state.
+     *
+     * Two shapes must stay quiet, and both sat in that same file. A target that
+     * varies with the loop — `forEach((card) => tl.from(card, …))` — is a new
+     * element each pass. And a tween inside a callback that is only passed
+     * along is not known to run each pass, so it is not reported.
+     */
+    test(file) {
+      const LOOPS = ["ForStatement", "ForOfStatement", "ForInStatement", "WhileStatement", "DoWhileStatement"];
+      const isLoopCallback = (fn) => {
+        const parent = parentOf(file.ast, fn);
+        return (
+          parent?.type === "CallExpression" &&
+          unwrap(parent.arguments[0]) === fn &&
+          ["forEach", "map", "flatMap"].includes(methodName(parent))
+        );
+      };
+      const renders = (call) =>
+        !call.arguments.some((arg) => {
+          const object = unwrap(arg);
+          return (
+            object?.type === "ObjectExpression" &&
+            object.properties.some((p) => {
+              const value = unwrap(p.value);
+              return keyName(p) === "immediateRender" && value?.type === "Literal" && value.value === false;
+            })
+          );
+        });
+
+      const paramNames = (fn) =>
+        fn.params.flatMap((param) =>
+          findAll(param, (n) => n.type === "Identifier").map((n) => n.name),
+        );
+      const loopNames = (loop) => {
+        const left = loop.left ?? loop.init;
+        return left ? findAll(left, (n) => n.type === "Identifier").map((n) => n.name) : [];
+      };
+
+      /** Is this node inside a loop body or a loop callback? */
+      const inLoop = (node) =>
+        ancestorsOf(file.ast, node).some((a) => LOOPS.includes(a.type) || (isFunction(a) && isLoopCallback(a)));
+
+      /**
+       * Walk out from the tween. The names that change each pass are gathered on
+       * the way; the walk stops at the first function that is neither a loop's
+       * own callback nor a named helper some loop calls, because nothing then
+       * says it runs more than once.
+       */
+      /**
+       * Does a guard on the way out pick exactly one pass? `key === "money"`
+       * does; `key !== "brand"` runs on most passes and still stacks. Only an
+       * equality against a literal, on a name that changes each pass, counts —
+       * the version of a real hero built without the skill guarded its one
+       * per-state tween that way, and a first version of this rule credited it
+       * with a bug it did not have.
+       */
+      const selectsOnePass = (guards, varying) =>
+        guards.some((test) =>
+          findAll(test, (node) => {
+            if (node.type !== "BinaryExpression" || !["===", "=="].includes(node.operator)) return false;
+            const sides = [unwrap(node.left), unwrap(node.right)];
+            const name = sides.find((side) => side?.type === "Identifier" && varying.has(side.name));
+            const literal = sides.find((side) => side?.type === "Literal");
+            return Boolean(name && literal);
+          }).length > 0,
+        );
+
+      /** Names that change each pass: its variable, and whatever its body declares. */
+      const declaredIn = (body) =>
+        body
+          ? findAll(body, (n) => n.type === "VariableDeclarator" && n.id.type === "Identifier").map((n) => n.id.name)
+          : [];
+
+      const repetition = (tween, timeline) => {
+        const varying = new Set();
+        const guards = [];
+        const settle = (loopBody) => {
+          declaredIn(loopBody).forEach((n) => varying.add(n));
+          return selectsOnePass(guards, varying) ? null : varying;
+        };
+        let inner = tween;
+        for (const ancestor of ancestorsOf(file.ast, tween)) {
+          if (contains(ancestor, timeline)) return null;
+          if ((ancestor.type === "IfStatement" || ancestor.type === "ConditionalExpression") && contains(ancestor.consequent, inner)) {
+            guards.push(ancestor.test);
+          }
+          inner = ancestor;
+          if (LOOPS.includes(ancestor.type)) {
+            loopNames(ancestor).forEach((n) => varying.add(n));
+            return settle(ancestor.body);
+          }
+          if (!isFunction(ancestor)) continue;
+          paramNames(ancestor).forEach((n) => varying.add(n));
+          if (isLoopCallback(ancestor)) return settle(ancestor.body);
+
+          const holder = parentOf(file.ast, ancestor);
+          const name =
+            holder?.type === "VariableDeclarator" && holder.id.type === "Identifier"
+              ? holder.id.name
+              : ancestor.type === "FunctionDeclaration"
+                ? ancestor.id?.name
+                : null;
+          if (!name) return null;
+          const calledInLoop = findAll(
+            file.ast,
+            (n) =>
+              n.type === "CallExpression" &&
+              unwrap(n.callee)?.type === "Identifier" &&
+              unwrap(n.callee).name === name &&
+              inLoop(n),
+          ).length > 0;
+          return calledInLoop ? varying : null;
+        }
+        return null;
+      };
+
+      /**
+       * The properties a tween's start state sets, or null when they cannot be
+       * read. "Last one wins" is per property: two from-tweens on one element
+       * that set different properties hide nothing, and a real project relied on
+       * exactly that — a line flying in on `opacity` and `y` while a second tween
+       * turned it on `rotationY`. `autoAlpha` sets opacity, so they count as one.
+       */
+      const CONFIG = new Set([
+        "duration", "delay", "ease", "stagger", "repeat", "yoyo", "repeatDelay",
+        "immediateRender", "overwrite", "paused", "id", "data", "callbackScope",
+        "onStart", "onUpdate", "onComplete", "onRepeat", "onReverseComplete", "scrollTrigger",
+      ]);
+      const startKeys = (tween) => {
+        const vars = unwrap(tween.arguments[1]);
+        if (vars?.type !== "ObjectExpression") return null;
+        if (vars.properties.some((p) => p.type !== "Property" || p.computed)) return null;
+        return new Set(
+          vars.properties
+            .map((p) => keyName(p))
+            .filter((key) => key && !CONFIG.has(key))
+            .map((key) => (key === "autoAlpha" ? "opacity" : key)),
+        );
+      };
+      const overlap = (a, b) => {
+        if (!a || !b) return false;
+        for (const key of a) if (b.has(key)) return true;
+        return false;
+      };
+
+      /**
+       * Two calls that cannot both run: opposite branches of one `if` or one
+       * ternary, or two cases of one `switch`. A real project built a fade-in in
+       * the `if` and a fade-out in the `else` against the same element, and only
+       * ever ran one of them.
+       */
+      const exclusive = (a, b) => {
+        const upB = new Set(ancestorsOf(file.ast, b));
+        for (const node of ancestorsOf(file.ast, a)) {
+          if (!upB.has(node)) continue;
+          if ((node.type === "IfStatement" || node.type === "ConditionalExpression") && node.alternate) {
+            if (contains(node.alternate, a) !== contains(node.alternate, b)) return true;
+          }
+          if (node.type === "SwitchStatement") {
+            const caseOf = (n) => node.cases.find((c) => contains(c, n));
+            if (caseOf(a) && caseOf(a) !== caseOf(b)) return true;
+          }
+        }
+        return false;
+      };
+
+      const mentions = (text, names) =>
+        [...names].some((name) => new RegExp(`(^|[^\\w$])${name.replace(/\$/g, "\\$")}([^\\w$]|$)`).test(text));
+
+      const findings = [];
+      const timelines = findAll(file.ast, (node) => calleeName(node) === "gsap.timeline");
+      for (const timeline of timelines) {
+        const tweens = timelineLinks(file.ast, timeline).filter(
+          (call) => ["from", "fromTo"].includes(methodName(call)) && call.arguments[0] && renders(call),
+        );
+        const reported = new Set();
+        /** Earlier from-tweens on each target, to compare a later one against. */
+        const earlier = new Map();
+
+        for (const tween of tweens) {
+          const target = unwrap(tween.arguments[0]);
+          const text = file.raw.slice(target.start, target.end).replace(/\s+/g, "");
+          if (reported.has(text)) continue;
+
+          /** One call site built repeatedly always shares its own properties. */
+          const varying = repetition(tween, timeline);
+          const repeatedInPlace = varying !== null && !mentions(text, varying);
+
+          const keys = startKeys(tween);
+          const before = earlier.get(text) ?? [];
+          const writtenTwice = before.some(
+            (other) => !exclusive(other.tween, tween) && overlap(other.keys, keys),
+          );
+          earlier.set(text, [...before, { tween, keys }]);
+
+          if (repeatedInPlace || writtenTwice) {
+            reported.add(text);
+            findings.push({
+              /**
+               * The method's own position, not the call's. A chained call starts
+               * where its chain starts, so `tween.start` pointed a real report 25
+               * lines above the `fromTo` it was about.
+               */
+              index: unwrap(tween.callee)?.property?.start ?? tween.start,
+              message: `\`${text}\` gets a \`${methodName(tween)}\` more than once on this timeline, and each applies its start state as soon as it is built.`,
+              hint: HINT.stackedFrom,
+            });
+          }
+        }
+      }
+      return findings;
+    },
+  },
 ];