@mehshekari/gsap-motion 4.5.0 → 4.6.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.5.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.6.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.5.0",
+  "version": "4.6.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.5.0"
+  version: "4.6.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -48,9 +48,9 @@ Core principles:
      [motion-design.md](reference/motion-design.md) and the command's own
      reference. Nothing else.
    - **A component or section:** also this project's adapter, from
-     `package.json`: `next` → [react](adapter/react.md) +
-     [next](adapter/next.md); `@react-three/fiber` → react +
-     [r3f](adapter/r3f.md); `three` → [three](adapter/three.md); `nuxt` →
+     `package.json`: `react` → [react](adapter/react.md), plus
+     [next](adapter/next.md) with `next` or [r3f](adapter/r3f.md) with
+     `@react-three/fiber`; `three` → [three](adapter/three.md); `nuxt` →
      [vue](adapter/vue.md); `svelte` → [svelte](adapter/svelte.md); `astro` →
      [astro](adapter/astro.md) plus any island's own; nothing detected →
      [vanilla](adapter/vanilla.md).

package/skill/reference/refine.md

@@ -129,9 +129,9 @@ that no source rule can reach.
 | It says | Read it as |
 | --- | --- |
 | **first motion at N ms** | How long the page is still. Late enough and the visitor has scrolled past the thing you built. |
-| **N elements moved, M of them GSAP's** | The gap is motion the audit never sees. A surprise there is worth chasing. |
+| **N elements moved, M of them GSAP's** | The rest is split into CSS or Web Animations, and other script writing styles: motion the audit never sees. `--json` lists each element with its kind and box, so a surprise can be found. |
 | **X% of the screen in motion** | Everything moving at once reads as noise, not as choreography. |
-| **seams** | A step far larger than that motion's own rhythm: a loop put back by hand instead of carried. |
+| **seams** | A step far larger than that motion's own rhythm, after which the motion carries on: a loop put back by hand instead of carried. A one-time jump into place is not one. |
 | **motion over text** | Something painted over a line a reader is in the middle of. Hit-tested, so it is what is really on top. |
 | **frames over 50ms** | Long Animation Frames, with the sampler's own time taken out of each: the rest is the page's. "Not measured" means the browser has no such API, not that nothing was long. |
 | **layout shift** | The browser's own shift total, input excluded. Sampling reads layout but never moves it, so this is the page's alone — a pin swapping its position at a section edge shows here. |

package/skill/scripts/audit-gsap.mjs

@@ -32,8 +32,8 @@
  *
  * Exit code is 1 when any error-level finding is reported, 0 otherwise.
  */
-import { existsSync, statSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 
 import { check, mentionsGsap, notParsed } from "./lib/audit.mjs";
 import { pluginRegistrations, RULES } from "./lib/rules.mjs";
@@ -62,10 +62,60 @@ for (const path of paths) {
   }
 }
 
+/**
+ * `compilerOptions.paths` from the project's tsconfig.json, as
+ * `[prefix, [target prefixes]]`: `"@/*": ["./src/*"]` becomes
+ * `["@/", ["./src/"]]`, against `baseUrl` when one is set. A tsconfig is JSON
+ * with comments and trailing commas, so those are stripped first; one that
+ * still does not parse gives no aliases rather than an error.
+ */
+function tsconfigPaths(root) {
+  try {
+    const text = withoutComments(readFileSync(join(root, "tsconfig.json"), "utf8")).replace(/,(\s*[}\]])/g, "$1");
+    const { compilerOptions = {} } = JSON.parse(text);
+    const base = compilerOptions.baseUrl ?? ".";
+    return Object.entries(compilerOptions.paths ?? {}).map(([key, targets]) => [
+      key.replace(/\*$/, ""),
+      targets.map((target) => join(base, target.replace(/\*$/, ""))),
+    ]);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * JSON with its comments removed, outside strings only. A regex over the whole
+ * text took the `/*` in `"**\/*.ts"` — in every Next tsconfig's `include` — for
+ * the start of a comment, broke the JSON, and lost every alias.
+ */
+function withoutComments(text) {
+  let out = "";
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '"') {
+      const end = text.slice(i + 1).search(/(?<!\\)"/);
+      const close = end === -1 ? text.length : i + 1 + end;
+      out += text.slice(i, close + 1);
+      i = close;
+    } else if (char === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") i += 1;
+      out += "\n";
+    } else if (char === "/" && text[i + 1] === "*") {
+      const end = text.indexOf("*/", i + 2);
+      i = end === -1 ? text.length : end + 1;
+    } else {
+      out += char;
+    }
+  }
+  return out;
+}
+
 // --- Run ---------------------------------------------------------------------
 
 const findings = [];
 const sources = [];
+/** Every file read, GSAP or not: the import graph needs callers that never animate. */
+const loaded = [];
 /**
  * A file named on the command line that the audit cannot read — a stylesheet,
  * say. It used to be skipped in silence and the run printed "clean", which
@@ -90,6 +140,7 @@ for (const path of paths) {
   }
   for (const file of collect(path)) {
     const source = load(file, ROOT);
+    loaded.push(source);
     if (!mentionsGsap(source)) continue;
 
     if (source.parseError) {
@@ -110,6 +161,50 @@ for (const path of paths) {
  */
 const registered = new Set(sources.flatMap((source) => [...pluginRegistrations(source)]));
 
+/**
+ * Who imports each file, among everything read — a caller need not use GSAP
+ * itself. Relative imports, and aliases the project's tsconfig maps in
+ * `compilerOptions.paths` (`"@/*": ["./src/*"]`).
+ *
+ * An alias that cannot be resolved may still name the file, and a verdict that
+ * rests on some of a file's callers is a guess. A real project imported one
+ * helper relatively from one caller and through `@/` from another; only the
+ * first was seen. So when an unresolved alias ends in a file's name, that
+ * file's importers are marked unknown, and it is judged alone.
+ */
+const byPath = new Map(loaded.map((source) => [resolve(source.path), source]));
+const EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", "/index.ts", "/index.tsx", "/index.js"];
+const aliases = tsconfigPaths(ROOT);
+const resolveSpecifier = (from, specifier) => {
+  const bases = specifier.startsWith(".")
+    ? [resolve(dirname(from), specifier)]
+    : aliases.flatMap(([prefix, targets]) =>
+        specifier.startsWith(prefix) ? targets.map((target) => resolve(ROOT, target + specifier.slice(prefix.length))) : [],
+      );
+  for (const base of bases) {
+    const target = EXTENSIONS.map((ext) => byPath.get(base + ext)).find(Boolean);
+    if (target) return target;
+  }
+  return null;
+};
+/** A bare package name — `gsap`, `react`, `@scope/pkg` — is not an alias. */
+const looksLikeAlias = (specifier) => /^(?:@\/|~\/|#)/.test(specifier) || aliases.some(([prefix]) => specifier.startsWith(prefix));
+const stem = (path) => path.replace(/\\/g, "/").split("/").at(-1).replace(/\.[^.]+$/, "");
+
+for (const source of loaded) source.importers = [];
+for (const source of loaded) {
+  for (const [, specifier] of source.code.matchAll(/\bimport\s+(?!type\b)[^;]*?\bfrom\s*["']([^"']+)["']/g)) {
+    if (!specifier.startsWith(".") && !looksLikeAlias(specifier)) continue;
+    const target = resolveSpecifier(source.path, specifier);
+    if (target && target !== source) {
+      target.importers.push(source);
+    } else if (!target && looksLikeAlias(specifier)) {
+      const name = specifier.split("/").at(-1);
+      for (const candidate of loaded) if (stem(candidate.path) === name) candidate.importersUnknown = true;
+    }
+  }
+}
+
 for (const source of sources) {
   source.registeredElsewhere = registered;
 

package/skill/scripts/capture-motion.mjs

@@ -427,9 +427,18 @@ export const pointAt = (selector) => `(() => {
     box = el.getBoundingClientRect();
   }
   const clamp = (v, max) => Math.min(max - 1, Math.max(0, v));
+  /** Where the other matches a pointer could reach are, so the reader can narrow the selector. */
+  const others = all
+    .filter((other, i) => i !== index && shown(other))
+    .slice(0, 4)
+    .map((other) => {
+      const b = other.getBoundingClientRect();
+      return [Math.round(b.x + b.width / 2), Math.round(b.y + b.height / 2)];
+    });
   return {
     matches: all.length,
     index,
+    others,
     scrolled: !inView,
     x: clamp(box.x + box.width / 2, innerWidth),
     y: clamp(box.y + box.height / 2, innerHeight),
@@ -635,9 +644,13 @@ async function capture(options) {
           }
         }
         const which = box.matches > 1 ? ` (match ${box.index + 1} of ${box.matches})` : "";
+        const elsewhere = box.others?.length
+          ? `; other matches a pointer could reach at ${box.others.map((p) => p.join(",")).join(" · ")} — narrow the selector to pick one`
+          : "";
         notes.push(
           `${step.type}: ${step.value}${which} at ${Math.round(box.x)},${Math.round(box.y)}` +
-            (box.scrolled ? ", scrolled into view first" : ""),
+            (box.scrolled ? ", scrolled into view first" : "") +
+            elsewhere,
         );
         await wait(120);
       }

package/skill/scripts/lib/ast.mjs

@@ -602,10 +602,56 @@ export function gsapContexts(root) {
     functions.set(name, node.type === "FunctionDeclaration" ? node : unwrap(node.init));
   }
 
+  /**
+   * Whether a function nested in a context body runs while the body runs, and
+   * so inside the context. GSAP sets the context only for the duration of the
+   * body (Context.add, gsap-core 3.15): a function the body hands to a listener,
+   * a timer, a promise or a ref runs later, outside it, and nothing it creates
+   * is reverted. A real project built a tween in `pulse.current = () => …`
+   * inside useGSAP and called it from pointermove; the audit read it as inside.
+   *
+   * In place: called right there, an array method's callback, GSAP's own
+   * callbacks (`on…` keys, `.add`, `.call`, which GSAP runs in the context),
+   * the cleanup the body returns, or a named function only ever called.
+   */
+  const ITERATORS = new Set(["forEach", "map", "filter", "flatMap", "reduce", "reduceRight", "some", "every", "find", "findIndex", "sort"]);
+  const runsInPlace = (fn) => {
+    const parent = parentOf(root, fn);
+    if (!parent) return false;
+    if (parent.type === "CallExpression") {
+      if (unwrap(parent.callee) === fn) return true;
+      const name = methodName(parent) ?? bareName(parent);
+      return ITERATORS.has(name) || name === "add" || name === "call" || isHook(parent) || safe.has(name) || calleeName(parent) === "gsap.context";
+    }
+    if (parent.type === "Property") return /^on[A-Z]/.test(keyName(parent) ?? "");
+    if (parent.type === "ReturnStatement" || (parent.type === "ArrowFunctionExpression" && parent.body === fn)) return true;
+    const bound =
+      parent.type === "VariableDeclarator" && parent.id.type === "Identifier" && unwrap(parent.init) === fn
+        ? parent.id.name
+        : fn.type === "FunctionDeclaration"
+          ? fn.id?.name
+          : null;
+    if (!bound) return false;
+    const uses = findAll(root, (n) => n.type === "Identifier" && n.name === bound && isReference(root, n));
+    return uses.every((id) => {
+      const call = parentOf(root, id);
+      return call?.type === "CallExpression" && call.callee === id;
+    });
+  };
+  /** Inside `scope`, with no function between that runs later. */
+  const runsWithin = (scope, node) => {
+    if (!contains(scope, node)) return false;
+    for (const ancestor of ancestorsOf(root, node)) {
+      if (ancestor === scope) return true;
+      if (isFunction(ancestor) && !runsInPlace(ancestor)) return false;
+    }
+    return false;
+  };
+
   const contained = new Set();
   const inside = (node) =>
-    scopes.some((argument) => contains(argument, node)) ||
-    [...contained].some((fn) => contains(fn, node));
+    scopes.some((argument) => runsWithin(argument, node)) ||
+    [...contained].some((fn) => runsWithin(fn, node));
   const identifiers = findAll(root, (node) => node.type === "Identifier");
 
   for (let changed = true; changed; ) {

package/skill/scripts/lib/rules.mjs

@@ -54,7 +54,7 @@ const HINT = {
   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. Note that contextSafe keeps every tween it creates until the context reverts: a handler that runs often should replay a timeline built once, or call a quickTo.",
+    "Nothing reverts it on unmount, and React StrictMode may run 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. Note that contextSafe keeps every tween it creates until the context reverts: a handler that runs often should replay a timeline built once, or call a quickTo.",
   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:
@@ -250,7 +250,32 @@ 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, perFrame = false } = {}) {
+function handlersFor(ast, events, options = {}) {
+  const direct = directHandlers(ast, events, options);
+  /**
+   * One hop through a ref: a handler that calls `pulse.current()`, where the
+   * file assigns `pulse.current = () => { … }`. A real project kept a tween on
+   * a ref and called it from a pointermove listener, and the rule read the
+   * listener as clean.
+   */
+  const viaRef = direct.flatMap((h) =>
+    findAll(h.node, (n) => n.type === "CallExpression" && unwrap(n.callee)?.type === "MemberExpression")
+      .map((call) => dottedName(unwrap(call.callee)))
+      .filter((name) => name?.endsWith(".current"))
+      .flatMap((name) =>
+        findAll(
+          ast,
+          (n) =>
+            n.type === "AssignmentExpression" &&
+            dottedName(unwrap(n.left)) === name &&
+            isFunction(unwrap(n.right)),
+        ).map((n) => ({ name: h.name, node: unwrap(n.right) })),
+      ),
+  );
+  return [...direct, ...viaRef];
+}
+
+function directHandlers(ast, events, { followNames = true, perFrame = false } = {}) {
   const handler = (expression) => {
     const node = unwrap(expression);
     if (node?.type === "CallExpression") return node;
@@ -397,6 +422,28 @@ const readsRef = (node) =>
       n.property.name === "current",
   ).length > 0;
 
+/**
+ * Whether a file holds a reduced-motion branch: the query written in code, or
+ * asked by name — `useReducedMotion()`, `prefersReducedMotion()`,
+ * `isReduced()`, `matchMedia(REDUCED_MOTION_QUERY)` — since it is often written
+ * once, in a shared module. "Reduced", not "reduce": an array's `.reduce()` is
+ * not one. A comment that mentions it is not a branch.
+ */
+function hasReducedBranch(file) {
+  if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) return true;
+  return (
+    findAll(file.ast, (node) => {
+      if (node.type !== "CallExpression") return false;
+      const name = calleeName(node)?.split(".").at(-1) ?? "";
+      if (/reduced/i.test(name)) return true;
+      return (
+        name === "matchMedia" &&
+        node.arguments.some((arg) => arg.type === "Identifier" && /reduced/i.test(arg.name))
+      );
+    }).length > 0
+  );
+}
+
 /** The calls that add a child to a timeline. */
 const CHILDREN = new Set(["to", "from", "fromTo", "add"]);
 
@@ -1841,25 +1888,20 @@ export const RULES = [
      */
     test(file) {
       if (!file.usesGsap) return [];
-      if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
-        return [];
-      }
+      if (hasReducedBranch(file)) return [];
       /**
-       * The query is often written once, in a shared module, and asked by name:
-       * `useReducedMotion()`, `prefersReducedMotion()`, `isReduced()`, or
-       * `matchMedia(REDUCED_MOTION_QUERY)`. That is a branch too. "Reduced",
-       * not "reduce", so an array's `.reduce()` is not one.
+       * Every caller decides instead: each file that imports this one holds a
+       * branch. Three projects reported a helper flagged while its only caller
+       * returned early under reduced motion. Only the full audit knows the
+       * importers; the editor and the write hook see one file, and report it.
        */
-      const asksByName = findAll(file.ast, (node) => {
-        if (node.type !== "CallExpression") return false;
-        const name = calleeName(node)?.split(".").at(-1) ?? "";
-        if (/reduced/i.test(name)) return true;
-        return (
-          name === "matchMedia" &&
-          node.arguments.some((arg) => arg.type === "Identifier" && /reduced/i.test(arg.name))
-        );
-      });
-      if (asksByName.length) return [];
+      if (
+        file.importers?.length &&
+        !file.importersUnknown &&
+        file.importers.every((importer) => !importer.parseError && hasReducedBranch(importer))
+      ) {
+        return [];
+      }
 
       const [first] = findAll(file.ast, (node) => {
         const method = tweenMethod(node);

package/skill/scripts/lib/source.mjs

@@ -249,7 +249,14 @@ export function fromText(raw, path, display = path) {
      */
     usesGsap:
       /\bfrom ["']gsap(?:\/|["'])/.test(code) ||
-      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code),
+      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code) ||
+      /**
+       * Loaded on demand: `loadGsap().then(({ gsap }) => …)` or
+       * `const { gsap } = await import(…)`. A real project's brand loader did
+       * this, and was the one file in eleven the lifecycle rules skipped.
+       */
+      /\(\s*\{[^}]*\bgsap\b[^}]*\}\s*\)\s*=>/.test(code) ||
+      /\{[^}]*\bgsap\b[^}]*\}\s*=\s*await\s+import\s*\(/.test(code),
   };
 }
 

package/skill/scripts/review-motion.mjs

@@ -134,8 +134,15 @@ export function seams(track, { factor = 6, minimum = 4, least = 16 } = {}) {
   /** A still element has no normal step to be unlike, so nothing is a seam. */
   if (!median) return [];
 
+  /**
+   * A loop carries on after its seam; a placement does not. A dev-only badge
+   * on a real page jumped once, 1000-1500px into a corner, and was reported as
+   * a tear. So a jump counts only when a step of ordinary size follows it.
+   */
+  const resumes = (index) => steps.slice(index + 1).some((step) => step.delta >= median / 2);
+
   return steps
-    .filter((step) => step.delta > median * factor && step.delta >= least)
+    .filter((step, index) => step.delta > median * factor && step.delta >= least && resumes(index))
     .map((step) => ({ at: step.at, jump: Math.round(step.delta * 10) / 10 }));
 }
 
@@ -274,6 +281,29 @@ export function longFrameSummary(longFrames, cost = []) {
   };
 }
 
+/**
+ * Every element that moved, once each, with what moved it and where it first
+ * was: `[{ key, kind, box }]`, at most `limit`. A count alone left a project
+ * unable to find the thirteen non-GSAP elements still moving under reduced
+ * motion. `kind` is "gsap", "css" (CSS animation, transition or Web Animation)
+ * or "script"; a recording made before kinds were read says "gsap" or "other".
+ */
+export function movingElements(log, { limit = 50 } = {}) {
+  const seen = new Map();
+  for (const frame of log) {
+    for (const moved of frame.moved) {
+      const id = moved.id ?? moved.key;
+      if (seen.has(id)) continue;
+      seen.set(id, {
+        key: moved.key,
+        kind: moved.kind ?? (moved.gsap ? "gsap" : "other"),
+        box: moved.box ?? null,
+      });
+    }
+  }
+  return [...seen.values()].slice(0, limit);
+}
+
 /** Each element and the moment it first moved, in that order. */
 export function starts(log) {
   const first = new Map();
@@ -527,6 +557,11 @@ const RECORDER = `(() => {
           id: idOf(el),
           key: keyOf(el),
           gsap: Boolean(el._gsap),
+          /**
+           * What is moving it: GSAP's cache, a running CSS animation, transition
+           * or Web Animation, or neither — a script writing styles itself.
+           */
+          kind: el._gsap ? "gsap" : el.getAnimations && el.getAnimations().length ? "css" : "script",
           box: state.screen,
           x: state.x,
           opacity: state.o,
@@ -744,6 +779,7 @@ export function conclude(result) {
     gsapMovers: new Set(
       log.flatMap((frame) => frame.moved.filter((m) => m.gsap).map((m) => m.id ?? m.key)),
     ).size,
+    movingElements: movingElements(log),
     seams: seamEvents(torn),
     overText,
     began: began.slice(0, 8),
@@ -781,6 +817,7 @@ export function probe(kind) {
     starts,
     firstMotion,
     longFrameSummary,
+    movingElements,
     conclude,
   };
   return `() => {
@@ -818,9 +855,16 @@ export function report(result, options) {
     lines.push("  or it needs a scroll or a pointer to begin");
   } else {
     lines.push(`  first motion at ${found.firstMotion}ms`);
+    const by = (kind) => found.movingElements.filter((element) => element.kind === kind).length;
+    const rest = [
+      by("css") && `${by("css")} CSS or Web Animations`,
+      by("script") && `${by("script")} written by other script`,
+      by("other") && `${by("other")} not GSAP's`,
+    ].filter(Boolean);
     lines.push(
       `  ${found.movers} elements moved, ${found.gsapMovers} of them GSAP's` +
-        `${found.movers > found.gsapMovers ? " (the rest is CSS, Web Animations or other script, which the source audit cannot see)" : ""}`,
+        `${rest.length ? `; ${rest.join(", ")}, which the source audit cannot see` : ""}` +
+        `${found.movers > found.movingElements.length ? ` (kinds read for the first ${found.movingElements.length})` : ""}`,
     );
     if (found.spread) lines.push(`  they started over a span of ${found.spread}ms`);
   }