@mehshekari/gsap-motion 4.2.0 → 4.3.0

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

package/skill/adapter/react.md

@@ -35,7 +35,8 @@ body re-runs on change) and `revertOnUpdate` (the previous run reverts first).
 A tween created *outside* the body — in a handler, a promise, a callback — is
 never reverted. Wrap that function in `contextSafe`, from the same hook, and the
 context owns it again. Only wrap functions that *create* animations: playing an
-existing timeline creates nothing. `contextSafe` runs during render, so reading a
+existing timeline creates nothing. Inside `mm.add`, use its own: the callback's
+second argument, `(context, contextSafe) =>`. `contextSafe` runs during render, so reading a
 ref inside the callback trips React's "cannot access refs during render" rule —
 build the timeline in the body, keep it on a ref, and expose a `useCallback`
 that plays it.

package/skill/reference/devices.md

@@ -23,13 +23,16 @@ mm.add(
     hoverable: "(hover: hover) and (pointer: fine)",
     motion: "(prefers-reduced-motion: no-preference)",
   },
-  (context) => {
+  (context, contextSafe) => {
     const { wide, hoverable, motion } = context.conditions;
-    // …one branch, three facts
+    // …one branch, three facts. A handler that tweens later: contextSafe(fn).
   },
 );
 ```
 
+`contextSafe` is the **second** argument. The context has none, and
+`context.add(fn)` runs `fn` at once: either one ships a blank page.
+
 `matchMedia` re-runs the body when any condition changes and reverts what the
 previous run created, so a visitor who rotates a phone, plugs in a mouse or
 turns on reduced motion gets the right version without a reload.

package/skill/reference/interaction.md

@@ -13,6 +13,11 @@ The recovery is what makes it feel physical. A button that springs toward the
 cursor and snaps back on leave feels broken; the same button easing back over
 0.6s feels alive.
 
+**A layer that answers the pointer follows it** — on both axes, toward the
+cursor. One axis, or the opposite way, reads as resistance: in blind judging, a
+card that followed beat one that drifted away every time. Depth comes from how
+*far* each layer follows, not which way.
+
 ## The rule: `quickTo`, not a tween per event
 
 ```ts
@@ -168,6 +173,8 @@ Cheap, and the styling stays in CSS where it can follow the theme.
 - Never destroy the focus ring with a transform that moves the element out from
   under it.
 - Gate hover effects on `(hover: hover)`. On touch, `:hover` sticks after a tap.
+  Input is its own axis, read in one `gsap.matchMedia` with layout and motion —
+  see [devices.md](devices.md).
 - Under `prefers-reduced-motion: reduce`, keep the state change and drop the
   travel — see [accessibility.md](accessibility.md).
 

package/skill/reference/motion-design.md

@@ -142,11 +142,10 @@ Before calling an animation done:
 - Does it say one of the five things at the top of this file?
 - Is the rhythm intentional, or are the delays arbitrary?
 - Does anything looping use `ease: "none"`?
+- Does an ambient loop move only decoration, never the copy being read?
 - Is the seam of the loop invisible?
 - Do entrances use `out` easing and exits `in`?
 - Does one element carry the emphasis, rather than all of them?
 - Does it still read at 400px wide, and on a touch device with no hover?
 - Does the reduced-motion branch still communicate the same thing?
-- Is everything reverted on unmount?
-- Is every plugin justified, and would a transform have done it?
 - Watch it five times. Does anything start to irritate?

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

@@ -49,6 +49,8 @@ import {
 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.",
+  contextSafeMisuse:
+    "The callback of `gsap.matchMedia().add`, `gsap.context` and `useGSAP` receives `(context, contextSafe)`: take the second argument, as in `mm.add(query, (context, contextSafe) => …)`, and wrap the delayed callback in it. `context.add(fn)` runs `fn` straight away instead.",
   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:
@@ -685,6 +687,45 @@ function stopped(ast, name) {
   );
 }
 
+/**
+ * Every `add` call on a `gsap.matchMedia()`: made on it directly, or on a name
+ * the file binds it to, at declaration or later.
+ */
+function matchMediaAdds(file) {
+  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";
+  };
+
+  return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node));
+}
+
+/** Nodes a value passes through unchanged on its way to whatever uses it. */
+const TRANSPARENT = new Set(["ParenthesizedExpression", "ChainExpression", "TSAsExpression", "TSNonNullExpression"]);
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -1606,50 +1647,67 @@ export const RULES = [
     id: "matchmedia-never-runs",
     level: "warn",
     description:
-      "A matchMedia callback that branches on its conditions, when every condition needs reduced motion",
+      "A matchMedia callback that branches on reduced motion, when every condition needs it",
     /**
      * `mm.add({ reduced: "(prefers-reduced-motion: reduce)" }, (context) => …)`
-     * whose callback reads `context.conditions`. The callback runs only while a
+     * 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.
+     * 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 reading of `conditions` is the whole signal. 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. */
-      const media = new Set(
-        findAll(
+      /** 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" &&
-            /**
-             * `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",
-        ).map((node) => node.id.name),
-      );
+            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;
+      };
 
-      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";
+      /** 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 the conditions it was handed? */
+      /** 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") {
@@ -1668,26 +1726,107 @@ export const RULES = [
         }).length > 0;
       };
 
-      return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node))
+      return matchMediaAdds(file)
         .filter((call) => {
-          const conditions = unwrap(call.arguments[0]);
-          if (conditions?.type !== "ObjectExpression" || !conditions.properties.length) return false;
-          const everyReduces = conditions.properties.every((property) => {
-            const value = staticString(property.value);
-            return typeof value === "string" && REDUCE.test(value);
-          });
-          if (!everyReduces) return false;
+          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 its conditions, but every condition needs reduced motion — so it never runs for a visitor without that preference.",
+            "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: "context-safe-misuse",
+    level: "warn",
+    description:
+      "A callback made context-safe with the context itself, which runs it at once instead",
+    /**
+     * The callback of `gsap.matchMedia().add`, `gsap.context` or `useGSAP`
+     * receives `(context, contextSafe)`. Two ways of getting that wrong both
+     * ship a blank page:
+     *
+     * - `({ contextSafe }) => …` reads `contextSafe` from the context, which has
+     *   none. It is `undefined`, and the first call throws.
+     * - `context.add(fn)` handed on as a callback. `add` with a function runs it
+     *   at once, passing the context, and returns what it returned, so the
+     *   caller receives no callback and `fn` ran with the wrong argument.
+     *
+     * Found in the 4.3 creative A/B: three of 27 runs, in both arms, crashed on
+     * load this way, every one inside a matchMedia. `add` as a statement runs a
+     * block inside the context and is correct; a named `add("onClick", fn)` and
+     * `add(null, fn)` return a wrapper and are correct too. Only an `add` whose
+     * result is used, given a function, is reported.
+     */
+    test(file) {
+      const callbacks = new Set(
+        [
+          ...matchMediaAdds(file).map((call) => call.arguments[1]),
+          ...findAll(
+            file.ast,
+            (node) =>
+              node.type === "CallExpression" &&
+              ["gsap.context", "useGSAP"].includes(calleeName(node)),
+          ).map((call) => call.arguments[0]),
+        ]
+          .map((argument) => resolveFunction(file.ast, argument))
+          .filter(Boolean),
+      );
+
+      /** Is the call's result handed on, rather than thrown away as a statement? */
+      const used = (call) => {
+        let child = call;
+        let parent = parentOf(file.ast, call);
+        while (parent && TRANSPARENT.has(parent.type)) {
+          child = parent;
+          parent = parentOf(file.ast, parent);
+        }
+        if (!parent || parent.type === "ExpressionStatement" || parent.type === "SequenceExpression") {
+          return false;
+        }
+        return !(parent.type === "CallExpression" && parent.callee === child);
+      };
+
+      const findings = [];
+      for (const fn of callbacks) {
+        const [param] = fn.params;
+        if (param?.type === "ObjectPattern") {
+          const property = param.properties.find((p) => keyName(p) === "contextSafe");
+          if (property) {
+            findings.push({
+              index: property.start,
+              message:
+                "`contextSafe` is read from the callback's first argument, the context, which has none: it is undefined, and the first call throws.",
+              hint: HINT.contextSafeMisuse,
+            });
+          }
+          continue;
+        }
+        if (param?.type !== "Identifier") continue;
+        const adds = findAll(fn.body, (node) => {
+          if (methodName(node) !== "add") return false;
+          const receiver = unwrap(unwrap(node.callee).object);
+          return receiver?.type === "Identifier" && receiver.name === param.name;
+        });
+        for (const call of adds) {
+          const target = unwrap(call.arguments[0]);
+          if (!target || target.type === "Literal" || target.type === "TemplateLiteral") continue;
+          if (!isFunction(target) && target.type !== "Identifier") continue;
+          if (!used(call)) continue;
+          findings.push({
+            index: call.start,
+            message: `\`${param.name}.add(fn)\` runs fn at once and returns its result, so what is handed on here is not a callback.`,
+            hint: HINT.contextSafeMisuse,
+          });
+        }
+      }
+      return findings;
+    },
+  },
   {
     id: "stacked-from",
     level: "warn",