@mehshekari/gsap-motion 3.4.0 → 3.4.1

package/README.md

@@ -30,7 +30,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@3.4.0 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@3.4.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": "3.4.0",
+  "version": "3.4.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 18+ and nothing else.
 metadata:
-  version: "3.4.0"
+  version: "3.4.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

package/skill/scripts/capture-motion.mjs

@@ -257,14 +257,35 @@ export function parseOptions(argv) {
 
 /**
  * The timeline GSAP is running, read from the page itself rather than guessed
- * from the source. Without GSAP on the page this returns null, which is a
- * finding of its own: the animation never started.
+ * from the source.
+ *
+ * A bundled app never gives the page a gsap global. GSAP installs its exports
+ * into a private object, and the branch of its installer that would reach
+ * window cannot be taken, because that object is truthy from the start. So a
+ * page can be full of GSAP with nothing to ask. Presence is read instead from
+ * the traces it leaves — the version it announces, and the cache it hangs on
+ * every element it touches — and a timeline that cannot be read is reported as
+ * unreadable, never as an animation that never ran.
  */
 const READ_TIMELINE = `(() => {
-  if (typeof gsap === "undefined") return null;
-  const children = gsap.globalTimeline.getChildren(true, true, true);
+  const handle =
+    typeof gsap !== "undefined"
+      ? gsap
+      : window.GreenSockGlobals && window.GreenSockGlobals.gsap
+        ? window.GreenSockGlobals.gsap
+        : null;
+  const version = (window.gsapVersions || [])[0] || null;
+  const controlled = [...document.querySelectorAll("*")].filter((el) => el._gsap).length;
+  if (!handle) {
+    if (!version && !controlled) return null;
+    return { readable: false, version, controlled };
+  }
+  const children = handle.globalTimeline.getChildren(true, true, true);
   return {
-    time: gsap.globalTimeline.time(),
+    readable: true,
+    version,
+    controlled,
+    time: handle.globalTimeline.time(),
     children: children.map((child) => ({
       targets: (child.targets?.() ?? []).map((target) =>
         target?.id ? "#" + target.id :
@@ -283,6 +304,27 @@ const READ_TIMELINE = `(() => {
   };
 })()`;
 
+/**
+ * Frames the page actually drove.
+ *
+ * Chrome's own Frames metric reads 0 in headless even while a tween runs at a
+ * steady 60fps, so it cannot be reported as a frame count. A requestAnimationFrame
+ * counter, installed before the page's own scripts, counts the frames the page
+ * was given — which is the number a reader wants when asking whether motion
+ * was smooth.
+ */
+const COUNT_FRAMES = `(() => {
+  if (window.__gsapMotionFrames !== undefined) return true;
+  window.__gsapMotionFrames = 0;
+  window.__gsapMotionStart = performance.now();
+  const step = () => {
+    window.__gsapMotionFrames += 1;
+    requestAnimationFrame(step);
+  };
+  requestAnimationFrame(step);
+  return true;
+})()`;
+
 /** The live box of a selector, so a pointer lands on an element that is moving. */
 const boxOf = (selector) => `(() => {
   const element = document.querySelector(${JSON.stringify(selector)});
@@ -295,6 +337,17 @@ const boxOf = (selector) => `(() => {
 
 const wait = (ms) => new Promise((done) => setTimeout(done, ms));
 
+/**
+ * Whether a box can be pointed at.
+ *
+ * A selector can match an element that styles say is visible and that layout
+ * gives no box at all — a duplicate inside a collapsed container, say. Its
+ * rect is every zero, so a pointer aimed at its centre lands in the corner of
+ * the viewport and hits whatever is there. Found on a real site, where a
+ * header held two copies of the same button and the first had no box.
+ */
+export const pointable = (box) => Boolean(box && box.width > 0 && box.height > 0);
+
 async function capture(options) {
   const executable = findChrome(options.chrome);
   if (!executable) {
@@ -343,6 +396,8 @@ async function capture(options) {
 
     if (options.cpu > 1) await call("Emulation.setCPUThrottlingRate", { rate: options.cpu });
 
+    await call("Page.addScriptToEvaluateOnNewDocument", { source: COUNT_FRAMES });
+
     const before = await call("Performance.getMetrics");
     await call("Page.navigate", { url: options.url });
     await wait(options.wait);
@@ -373,6 +428,12 @@ async function capture(options) {
           notes.push(`${step.type}: nothing matched ${step.value}`);
           continue;
         }
+        if (!pointable(box)) {
+          notes.push(
+            `${step.type}: ${step.value} matched an element with no box on screen, so nothing was done`,
+          );
+          continue;
+        }
         /**
          * Two moves, because a pointer that is already there never enters; and
          * the box is read now, since whatever is animating has moved since the
@@ -423,6 +484,9 @@ async function capture(options) {
     }
 
     const timeline = await evaluate(READ_TIMELINE);
+    const drawn = await evaluate(
+      "({ frames: window.__gsapMotionFrames ?? null, since: window.__gsapMotionStart ?? null })",
+    );
     const after = await call("Performance.getMetrics");
 
     const delta = (name) => {
@@ -431,11 +495,17 @@ async function capture(options) {
       return end - start;
     };
 
-    const span = (options.at.at(-1) ?? 0) + options.wait;
+    /** The window the page was actually watched for, not the one that was asked for. */
+    const span = Math.round(
+      drawn.since === null
+        ? (options.at.at(-1) ?? 0) + options.wait
+        : await evaluate(`performance.now() - ${drawn.since}`),
+    );
     const measured = {
       layouts: delta("LayoutCount"),
       recalcs: delta("RecalcStyleCount"),
-      frames: delta("Frames"),
+      frames: drawn.frames,
+      fps: drawn.frames && span ? Number(((drawn.frames / span) * 1000).toFixed(1)) : null,
       layoutSeconds: Number(delta("LayoutDuration").toFixed(3)),
       recalcSeconds: Number(delta("RecalcStyleDuration").toFixed(3)),
       overMs: span,
@@ -449,7 +519,7 @@ async function capture(options) {
 
 // --- Reporting ---------------------------------------------------------------
 
-function report(result, options) {
+export function report(result, options) {
   const lines = [`Watched ${result.url}`];
 
   const emulated = [
@@ -469,6 +539,17 @@ function report(result, options) {
   lines.push("", "Timeline, as the page is running it");
   if (result.timeline === null) {
     lines.push("  no GSAP on the page — nothing was animating, or it never loaded");
+  } else if (result.timeline.readable === false) {
+    const { version, controlled } = result.timeline;
+    lines.push(
+      `  GSAP${version ? ` ${version}` : ""} is running, but this page keeps it to itself,` +
+        " so its timeline cannot be read from outside.",
+    );
+    lines.push(
+      `  ${controlled} element${controlled === 1 ? " carries" : "s carry"} GSAP's cache,` +
+        " so it has touched the page.",
+    );
+    lines.push("  To read the timeline here, call gsap.install(window) in development.");
   } else if (result.timeline.children.length === 0) {
     lines.push("  GSAP is loaded, and its global timeline has no children right now");
   } else {
@@ -486,8 +567,12 @@ function report(result, options) {
 
   const { measured } = result;
   lines.push("", `Browser work over ${measured.overMs}ms`);
+  /** A rate only means something when frames were counted at all. */
+  const rate = measured.fps === null ? "" : ` (${measured.fps}/s)`;
+  const drew =
+    measured.frames === null ? "frames not counted" : `${measured.frames} frames${rate}`;
   lines.push(
-    `  ${measured.frames} frames · ${measured.layouts} layouts (${measured.layoutSeconds}s)` +
+    `  ${drew} · ${measured.layouts} layouts (${measured.layoutSeconds}s)` +
       ` · ${measured.recalcs} style recalculations (${measured.recalcSeconds}s)`,
   );
   lines.push("", "These are observations. What they mean is yours to judge.");

package/skill/scripts/explain-motion.mjs

@@ -29,10 +29,12 @@ import { connect, findChrome } from "./capture-motion.mjs";
 import { check, mentionsGsap } from "./lib/audit.mjs";
 import {
   calleeName,
+  contains,
   dottedName,
   findAll,
   keptUnder,
   methodName,
+  scopeOf,
   propertyOf,
   staticString,
   timelineLinks,
@@ -185,6 +187,8 @@ function readFile(file) {
   // Scenes: a timeline, and the beats on it in order.
   const timelines = findAll(file.ast, (node) => calleeName(node) === "gsap.timeline");
   const claimed = new Set();
+  /** Which function holds each scene, since a file often has two called `tl`. */
+  const owners = new Map();
 
   for (const timeline of timelines) {
     const beats = [];
@@ -192,7 +196,9 @@ function readFile(file) {
       claimed.add(link);
       const method = methodName(link);
       if (method === "addLabel") {
-        beats.push({ label: staticString(link.arguments[0]) ?? "(label)" });
+        beats.push({
+          label: staticString(link.arguments[0]) ?? textOf(file, link.arguments[0], 24) ?? "(label)",
+        });
         continue;
       }
       if (!["to", "from", "fromTo", "set", "call", "add"].includes(method)) continue;
@@ -209,19 +215,31 @@ function readFile(file) {
       });
     }
 
-    map.scenes.push({
+    const scene = {
       line: lineAt(file.raw, timeline.start),
       name: keptUnder(file.ast, timeline)?.name ?? null,
       repeat: valueOf(varsOf(timeline), "repeat"),
       why: reasonFor(file, timeline),
       beats,
-    });
+    };
+    map.scenes.push(scene);
+    owners.set(scene, scopeOf(file.ast, timeline));
   }
 
-  /** The name each scene is kept under, so its own beats find their way home. */
-  const byName = new Map(
-    map.scenes.filter((scene) => scene.name).map((scene) => [scene.name, scene]),
-  );
+  /**
+   * The scene a beat belongs to. A name alone is not enough: two timelines in
+   * one file are often both `tl`, and handing one scene's beats to the other is
+   * the kind of wrong a map must not be. The owner is the enclosing function.
+   */
+  const sceneFor = (name, node) => {
+    const holding = map.scenes.filter((scene) => {
+      if (scene.name !== name) return false;
+      const owner = owners.get(scene);
+      /** A timeline at module scope owns the whole file; otherwise its function must hold the beat. */
+      return !owner || contains(owner, node);
+    });
+    return holding.at(-1) ?? null;
+  };
 
   // Beats added to a timeline this file was handed: the helper shape, where the
   // caller owns the timeline and this file only fills it.
@@ -232,14 +250,17 @@ function readFile(file) {
     if (claimed.has(call) || timelines.includes(call)) continue;
     const owner = dottedName(unwrap(call.callee).object);
     if (!owner || owner === "gsap" || owner.startsWith("gsap.")) continue;
-    const own = byName.get(owner);
+    const own = sceneFor(owner, call);
     if (!own && !handed.has(owner)) handed.set(owner, []);
 
     const method = methodName(call);
     const vars = varsOf(call);
     (own ? own.beats : handed.get(owner)).push(
       method === "addLabel"
-        ? { label: staticString(call.arguments[0]) ?? "(label)" }
+        ? {
+            label:
+              staticString(call.arguments[0]) ?? textOf(file, call.arguments[0], 24) ?? "(label)",
+          }
         : {
             line: lineAt(file.raw, startOf(call)),
             method,