@mehshekari/gsap-motion 3.3.0 → 3.4.1

package/README.md

@@ -20,6 +20,8 @@ No dependencies, no install scripts, Node.js 18 or later.
 | `remove` | Uninstalls it. Takes the same `--global` and `--dir`. It only ever removes a directory that holds this skill. |
 | `audit [path...]` | Scans for leaks, per-frame cost, eased loops, shared plugin ids, unregistered plugins and shipped dev tooling. Default path `src`. `--quiet` for errors only, `--json` for scripts. |
 | `audit-svg <file...>` | Reports what DrawSVG can draw, what MorphSVG can morph, and what will fail silently. `--morph a.svg b.svg` compares a pair; `--hues` also reports hard-coded hues. |
+| `inspect <url>` | Watches a page animate over the DevTools Protocol and reports what it saw: a filmstrip, the timeline GSAP is running, and the layouts, style recalculations and frames the browser did. `--scroll`, `--hover` and `--click` reach the state first; `--reduced`, `--dark`, `--mobile` and `--cpu` change the conditions. Needs a Chrome on the machine; installs nothing. |
+| `explain <file...|url>` | Maps an animation and changes nothing: where it lives, its preference branches, its beats in order with the reasons their comments give, its scroll configuration, and what the audit says. Given a URL it reads the running page instead, where the timeline is the one GSAP actually built. |
 | `doctor` | Checks Node.js, the installed skill's version for this project and your user, your project's `gsap` and `@gsap/react`, and whether an `ANIMATION.md` exists. |
 
 ## In CI
@@ -28,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.3.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/bin/gsap-motion.mjs

@@ -7,6 +7,8 @@
  *   npx @mehshekari/gsap-motion remove [--global | --dir <skills-dir>]
  *   npx @mehshekari/gsap-motion audit [path...] [--quiet] [--json]
  *   npx @mehshekari/gsap-motion audit-svg <file.svg...> [--morph] [--hues]
+ *   npx @mehshekari/gsap-motion inspect <url> [--at ...] [--hover ...] [--reduced]
+ *   npx @mehshekari/gsap-motion explain <file...|url>
  *   npx @mehshekari/gsap-motion doctor
  *
  * Installed as a dependency, the same commands run as `gsap-motion <command>`.
@@ -69,6 +71,19 @@ Commands
   audit-svg <file...>   What an SVG can do before you animate it
     --morph <a> <b>     Compare a morph pair
     --hues              Also report hard-coded hues
+  inspect <url>         Watch a page animate and report what it did
+    --at 0,300,900      When to capture, in ms after the page settles
+    --scroll <px|sel>   Scroll before capturing
+    --hover <selector>  Move the pointer onto an element
+    --click <selector>  Click an element
+    --reduced --dark    Emulate a preference
+    --mobile            390x844 with touch input
+    --cpu 4             Throttle the CPU by this factor
+    --out <dir>         Where frames go. Default .gsap-motion/inspect
+    --json              Machine-readable output
+  explain <file...>     Map an animation: scopes, branches, beats, triggers
+                        Give it a URL instead to read the running page
+    --json              Machine-readable output
   doctor                Check Node, the installed skill and your project's GSAP
   --version             Print the version
 
@@ -301,6 +316,12 @@ switch (command) {
   case "audit-svg":
     runScript("audit-svg.mjs", args);
     break;
+  case "inspect":
+    runScript("capture-motion.mjs", args);
+    break;
+  case "explain":
+    runScript("explain-motion.mjs", args);
+    break;
   case "doctor":
     doctor();
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "3.3.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.3.0"
+  version: "3.4.1"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---
@@ -163,27 +163,31 @@ never ship both.
 
 ## Tools
 
-Both scripts catch **silent** failures. Run them from the project root;
-`<skill-dir>` is where this skill is installed.
+These catch what is **silent**. Run them from the project root; `<skill-dir>`
+is the skill's folder.
 
 ```bash
 # Leaks, per-event and per-frame tweens, layout and paint properties, loops,
-# shared plugin ids, unregistered plugins, dev tooling. Exit 1 on an error.
+# plugin ids, unregistered plugins, dev tooling. 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
+node <skill-dir>/scripts/audit-gsap.mjs src --json
 
-# What an SVG can actually do, before any animation is written.
+# What an SVG can do, before any animation is written.
 node <skill-dir>/scripts/audit-svg.mjs <file.svg>
 node <skill-dir>/scripts/audit-svg.mjs --morph <a.svg> <b.svg>
-node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>   # also flag hue literals
+node <skill-dir>/scripts/audit-svg.mjs --hues <file.svg>
+
+# Watch a page animate: frames, timeline, browser work.
+# Needs a Chrome; observations, not verdicts.
+node <skill-dir>/scripts/capture-motion.mjs <url> --at 0,300,900
 ```
 
-Run `audit-gsap` first in an `audit` and after writing any animation — as a
-Claude Code plugin, a hook already runs it on every edit and hands back what it
-finds. A false finding is a bug in the script, not something to work around.
+Run `audit-gsap` first in an `audit` and after writing animation — as a plugin,
+a hook already runs it on every edit. A false finding is a bug in the script,
+not something to work around.
 
 `MotionPathHelper`, `GSDevTools`, `markers: true` and
 `MorphSVGPlugin.findShapeIndex()` are development-only, and a static import
 ships whatever `if` surrounds it. Import them dynamically behind a `NODE_ENV`
-check, and delete the block once their value is baked in.
+check, and delete it once its value is baked in.

package/skill/reference/refine.md

@@ -25,6 +25,9 @@ script.
 A finding you believe is wrong is a bug in the script. Report it; do not work
 around it with a waiver.
 
+When what the code says and what the page does disagree, `explain-motion.mjs`
+reads both: the file's map, or — given a URL — the timeline GSAP actually built.
+
 ## Fix in this order
 
 The order is not taste. A fix further down the list can be undone by a fix
@@ -50,6 +53,31 @@ at a time, and read what actually happened in the DOM.
 A fix built on a guess usually works by accident, and the comment above it is
 then wrong for everyone who reads it next.
 
+## Watch it, when you can
+
+A checker reads code. It cannot see a seam, a slideshow, or a hero that starts
+so late the visitor has already scrolled past it. When a browser is on the
+machine, run the page:
+
+```bash
+node <skill-dir>/scripts/capture-motion.mjs http://localhost:3000 --at 0,300,900
+```
+
+It reports a filmstrip, the timeline GSAP is actually running — which is not
+always the one in the source — and the layouts, style recalculations and frames
+the browser did. All observations; the judgement is yours.
+
+Reach the state first, and change the conditions that usually break things:
+
+- `--scroll <px|selector>`, `--hover <selector>`, `--click <selector>` run in
+  the order written, before the first capture. A hover effect or a mid-page
+  ScrollTrigger is invisible without them.
+- `--reduced`, `--dark`, `--mobile`, `--cpu 4`. `--mobile` makes input touch,
+  so it cannot be combined with `--hover`: a coarse pointer has no hover, which
+  is the thing worth knowing.
+
+**Without a browser, report the stage as not run.** Not "fine".
+
 ## When to stop
 
 Stop when every check is clean, or after **three rounds**, reporting what is

package/skill/reference/routing.md

@@ -99,6 +99,18 @@ the mechanical failures before you spend attention on them:
 node .claude/skills/gsap-creative-animation/scripts/audit-gsap.mjs <path>
 ```
 
+**Read the map before reading the code.** `explain-motion.mjs` prints what a
+file animates — scopes, preference branches, beats in order with the reasons
+their comments give, and the scroll configuration — and cites the audit rather
+than judging. Given a URL it reads the running page instead, which is the only
+way to see the timeline GSAP actually built, after every branch and early
+return:
+
+```bash
+node <skill-dir>/scripts/explain-motion.mjs src/hooks/useHero.ts
+node <skill-dir>/scripts/explain-motion.mjs http://localhost:3000
+```
+
 **When an animation is not visible, ask whether it was ever built.** Before
 touching timings or transforms, check that the code which creates it actually
 runs. Animation is routinely built behind a condition — an image decode race, a

package/skill/scripts/capture-motion.mjs

@@ -0,0 +1,604 @@
+#!/usr/bin/env node
+
+/**
+ * Watches a page animate, and reports what it saw.
+ *
+ * Everything here is an observation, never a verdict. It captures frames at
+ * given times, reads the timeline GSAP is actually running, and counts the
+ * layouts, style recalculations and frames the browser did — and then says so,
+ * with numbers. Whether 14 layouts in a second is a problem depends on the
+ * animation, and that judgement belongs to whoever reads this.
+ *
+ * It drives Chrome over the DevTools Protocol through a pipe — `stdin` and
+ * `stdout` of two extra file descriptors — rather than a WebSocket, because
+ * Node 18 has no global WebSocket and this skill installs nothing. It uses
+ * whatever Chrome the machine already has.
+ *
+ * Usage, from the project root:
+ *   node <skill-dir>/scripts/capture-motion.mjs <url> [options]
+ *
+ *   --at 0,300,900        when to capture, in ms after the page settles
+ *   --wait 400            settle time before the first capture (default 400)
+ *   --out <dir>           where frames go (default .gsap-motion/inspect)
+ *   --scroll <px|sel>     scroll before capturing: a number, or to a selector
+ *   --hover <selector>    move the pointer onto an element, at its live box
+ *   --click <selector>    click an element
+ *   --reduced             emulate prefers-reduced-motion: reduce
+ *   --dark                emulate prefers-color-scheme: dark
+ *   --mobile              390x844 at dpr 3, with touch input
+ *   --cpu 4               throttle the CPU by this factor
+ *   --json                machine-readable, for scripts
+ *   --chrome <path>       a browser to use, overriding the search
+ *
+ * `--scroll`, `--hover` and `--click` run in the order they are written, before
+ * the first capture. An animation that needs a pointer or a scroll position is
+ * invisible without them.
+ *
+ * `--mobile` makes input touch, so it cannot be combined with `--hover`: a
+ * device with a coarse pointer has no hover, which is the point.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// --- The browser -------------------------------------------------------------
+
+/** Where a Chrome usually is, per platform. `CHROME_PATH` wins over all of it. */
+export function findChrome(override) {
+  const candidates = [
+    override,
+    process.env.GSAP_MOTION_CHROME,
+    process.env.CHROME_PATH,
+    ...(process.platform === "win32"
+      ? [
+          `${process.env.ProgramFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+          `${process.env["ProgramFiles(x86)"]}\\Google\\Chrome\\Application\\chrome.exe`,
+          `${process.env.LOCALAPPDATA}\\Google\\Chrome\\Application\\chrome.exe`,
+          `${process.env.ProgramFiles}\\Microsoft\\Edge\\Application\\msedge.exe`,
+        ]
+      : process.platform === "darwin"
+        ? [
+            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+            "/Applications/Chromium.app/Contents/MacOS/Chromium",
+            `${homedir()}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+          ]
+        : [
+            "/usr/bin/google-chrome",
+            "/usr/bin/google-chrome-stable",
+            "/usr/bin/chromium",
+            "/usr/bin/chromium-browser",
+            "/snap/bin/chromium",
+          ]),
+  ];
+
+  return candidates.find((path) => path && existsSync(path)) ?? null;
+}
+
+/**
+ * A CDP connection over Chrome's pipe transport: commands into file descriptor
+ * 3, replies and events out of 4, each message a JSON object followed by a NUL.
+ */
+export function connect(executable, { headless = true } = {}) {
+  const profile = join(tmpdir(), `gsap-motion-inspect-${process.pid}`);
+  const chrome = spawn(
+    executable,
+    [
+      ...(headless ? ["--headless=new"] : []),
+      "--remote-debugging-pipe",
+      "--no-first-run",
+      "--no-default-browser-check",
+      "--disable-gpu",
+      "--disable-extensions",
+      `--user-data-dir=${profile}`,
+      "about:blank",
+    ],
+    { stdio: ["ignore", "pipe", "pipe", "pipe", "pipe"] },
+  );
+
+  const [, , stderr, toBrowser, fromBrowser] = chrome.stdio;
+  const stderrLines = [];
+  stderr.on("data", (chunk) => stderrLines.push(chunk.toString()));
+
+  const waiting = new Map();
+  let buffer = "";
+
+  fromBrowser.on("data", (chunk) => {
+    buffer += chunk.toString("utf8");
+    let end = buffer.indexOf("\0");
+    while (end !== -1) {
+      let message;
+      try {
+        message = JSON.parse(buffer.slice(0, end));
+      } catch {
+        message = null;
+      }
+      buffer = buffer.slice(end + 1);
+      const pending = message?.id && waiting.get(message.id);
+      if (pending) {
+        waiting.delete(message.id);
+        if (message.error) pending.reject(new Error(message.error.message ?? "CDP error"));
+        else pending.resolve(message.result);
+      }
+      end = buffer.indexOf("\0");
+    }
+  });
+
+  let nextId = 0;
+  const send = (method, params = {}, sessionId) =>
+    new Promise((accept, reject) => {
+      const id = (nextId += 1);
+      waiting.set(id, { resolve: accept, reject });
+      toBrowser.write(
+        `${JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) })}\0`,
+      );
+      setTimeout(() => {
+        if (!waiting.has(id)) return;
+        waiting.delete(id);
+        reject(new Error(`${method} did not answer within 20s`));
+      }, 20000);
+    });
+
+  const close = async () => {
+    try {
+      await send("Browser.close");
+    } catch {
+      chrome.kill();
+    }
+  };
+
+  return { send, close, stderrLines };
+}
+
+// --- Options -----------------------------------------------------------------
+
+/** A number of milliseconds, or null when the text is not one. */
+const asNumber = (text) => {
+  const value = Number(text);
+  return Number.isFinite(value) ? value : null;
+};
+
+/**
+ * Reads the command line. Exported because the parsing is worth testing without
+ * a browser, and because a wrong `--at` should fail before Chrome starts.
+ */
+export function parseOptions(argv) {
+  const options = {
+    url: null,
+    at: [0, 300, 900],
+    wait: 400,
+    out: join(".gsap-motion", "inspect"),
+    steps: [],
+    reduced: false,
+    dark: false,
+    mobile: false,
+    cpu: 1,
+    json: false,
+    chrome: null,
+    errors: [],
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    const value = () => argv[(index += 1)];
+
+    switch (argument) {
+      case "--at": {
+        const times = String(value() ?? "")
+          .split(",")
+          .map((part) => asNumber(part.trim()));
+        if (times.length === 0 || times.some((time) => time === null || time < 0)) {
+          options.errors.push("--at takes milliseconds, such as --at 0,300,900");
+        } else {
+          options.at = times.sort((a, b) => a - b);
+        }
+        break;
+      }
+      case "--wait": {
+        const ms = asNumber(value());
+        if (ms === null || ms < 0) options.errors.push("--wait takes milliseconds");
+        else options.wait = ms;
+        break;
+      }
+      case "--out":
+        options.out = value() ?? options.out;
+        break;
+      case "--scroll":
+        options.steps.push({ type: "scroll", value: value() ?? "" });
+        break;
+      case "--hover":
+        options.steps.push({ type: "hover", value: value() ?? "" });
+        break;
+      case "--click":
+        options.steps.push({ type: "click", value: value() ?? "" });
+        break;
+      case "--reduced":
+        options.reduced = true;
+        break;
+      case "--dark":
+        options.dark = true;
+        break;
+      case "--mobile":
+        options.mobile = true;
+        break;
+      case "--cpu": {
+        const rate = asNumber(value());
+        if (rate === null || rate < 1) options.errors.push("--cpu takes a factor of 1 or more");
+        else options.cpu = rate;
+        break;
+      }
+      case "--json":
+        options.json = true;
+        break;
+      case "--chrome":
+        options.chrome = value() ?? null;
+        break;
+      default:
+        if (argument.startsWith("--")) options.errors.push(`Unknown option: ${argument}`);
+        else if (options.url === null) options.url = argument;
+        else options.errors.push(`Unexpected argument: ${argument}`);
+    }
+  }
+
+  if (options.url === null) options.errors.push("No URL. Pass the page to watch.");
+
+  /** A coarse pointer has no hover; emulating both would measure something no device is. */
+  if (options.mobile && options.steps.some((step) => step.type === "hover")) {
+    options.errors.push(
+      "--mobile and --hover cannot be combined: mobile emulation makes input touch, and a touch device has no hover.",
+    );
+  }
+
+  return options;
+}
+
+// --- What runs in the page ---------------------------------------------------
+
+/**
+ * The timeline GSAP is running, read from the page itself rather than guessed
+ * 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 = `(() => {
+  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 {
+    readable: true,
+    version,
+    controlled,
+    time: handle.globalTimeline.time(),
+    children: children.map((child) => ({
+      targets: (child.targets?.() ?? []).map((target) =>
+        target?.id ? "#" + target.id :
+        target?.tagName ? target.tagName.toLowerCase() :
+        String(target)
+      ),
+      duration: Number(child.duration?.().toFixed?.(3) ?? child.duration?.() ?? 0),
+      repeat: child.repeat?.() ?? 0,
+      yoyo: child.yoyo?.() ?? false,
+      paused: child.paused?.() ?? false,
+      ease: typeof child.vars?.ease === "string" ? child.vars.ease : child.vars?.ease ? "(function)" : null,
+      props: Object.keys(child.vars ?? {}).filter(
+        (key) => !["ease", "duration", "repeat", "yoyo", "scrollTrigger", "onComplete", "onUpdate", "delay", "stagger"].includes(key),
+      ),
+    })),
+  };
+})()`;
+
+/**
+ * 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)});
+  if (!element) return null;
+  const box = element.getBoundingClientRect();
+  return { x: box.x + box.width / 2, y: box.y + box.height / 2, width: box.width, height: box.height };
+})()`;
+
+// --- The run -----------------------------------------------------------------
+
+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) {
+    throw new Error(
+      "No Chrome found. Install Chrome, or pass --chrome <path>, or set CHROME_PATH.",
+    );
+  }
+
+  const browser = connect(executable);
+  const notes = [];
+
+  try {
+    const { targetId } = await browser.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await browser.send("Target.attachToTarget", {
+      targetId,
+      flatten: true,
+    });
+    const call = (method, params) => browser.send(method, params, sessionId);
+    const evaluate = async (expression) => {
+      const { result } = await call("Runtime.evaluate", {
+        expression,
+        returnByValue: true,
+        awaitPromise: true,
+      });
+      return result.value;
+    };
+
+    await call("Page.enable");
+    await call("Runtime.enable");
+    await call("Performance.enable");
+
+    const features = [];
+    if (options.reduced) features.push({ name: "prefers-reduced-motion", value: "reduce" });
+    if (options.dark) features.push({ name: "prefers-color-scheme", value: "dark" });
+    if (features.length) await call("Emulation.setEmulatedMedia", { features });
+
+    if (options.mobile) {
+      await call("Emulation.setDeviceMetricsOverride", {
+        width: 390,
+        height: 844,
+        deviceScaleFactor: 3,
+        mobile: true,
+      });
+      await call("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
+    }
+
+    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);
+
+    for (const step of options.steps) {
+      if (step.type === "scroll") {
+        const pixels = asNumber(step.value);
+        const moved = await evaluate(
+          pixels === null
+            ? `(() => {
+                const element = document.querySelector(${JSON.stringify(step.value)});
+                if (!element) return null;
+                element.scrollIntoView({ block: "center" });
+                return Math.round(window.scrollY);
+              })()`
+            : `(window.scrollTo(0, ${pixels}), Math.round(window.scrollY))`,
+        );
+        notes.push(
+          moved === null
+            ? `scroll: nothing matched ${step.value}`
+            : `scroll: to ${moved}px`,
+        );
+      }
+
+      if (step.type === "hover" || step.type === "click") {
+        const box = await evaluate(boxOf(step.value));
+        if (!box) {
+          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
+         * page loaded.
+         */
+        await call("Input.dispatchMouseEvent", { type: "mouseMoved", x: 1, y: 1, buttons: 0 });
+        await wait(60);
+        await call("Input.dispatchMouseEvent", {
+          type: "mouseMoved",
+          x: box.x,
+          y: box.y,
+          buttons: 0,
+        });
+
+        if (step.type === "click") {
+          for (const type of ["mousePressed", "mouseReleased"]) {
+            await call("Input.dispatchMouseEvent", {
+              type,
+              x: box.x,
+              y: box.y,
+              button: "left",
+              buttons: type === "mousePressed" ? 1 : 0,
+              clickCount: 1,
+            });
+          }
+        }
+        notes.push(
+          `${step.type}: ${step.value} at ${Math.round(box.x)},${Math.round(box.y)}`,
+        );
+        await wait(120);
+      }
+    }
+
+    mkdirSync(resolve(options.out), { recursive: true });
+
+    const frames = [];
+    let elapsed = 0;
+    for (const at of options.at) {
+      if (at > elapsed) {
+        await wait(at - elapsed);
+        elapsed = at;
+      }
+      const shot = await call("Page.captureScreenshot", { format: "png" });
+      const bytes = Buffer.from(shot.data, "base64");
+      const file = join(resolve(options.out), `frame-${String(at).padStart(5, "0")}ms.png`);
+      writeFileSync(file, bytes);
+      frames.push({ at, file, bytes: bytes.length });
+    }
+
+    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) => {
+      const start = before.metrics.find((metric) => metric.name === name)?.value ?? 0;
+      const end = after.metrics.find((metric) => metric.name === name)?.value ?? 0;
+      return end - start;
+    };
+
+    /** 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: 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,
+    };
+
+    return { url: options.url, frames, timeline, measured, notes, chrome: executable };
+  } finally {
+    await browser.close();
+  }
+}
+
+// --- Reporting ---------------------------------------------------------------
+
+export function report(result, options) {
+  const lines = [`Watched ${result.url}`];
+
+  const emulated = [
+    options.reduced && "reduced motion",
+    options.dark && "dark",
+    options.mobile && "mobile 390x844",
+    options.cpu > 1 && `CPU ÷${options.cpu}`,
+  ].filter(Boolean);
+  if (emulated.length) lines.push(`  as: ${emulated.join(", ")}`);
+  for (const note of result.notes) lines.push(`  ${note}`);
+
+  lines.push("", `Frames (${result.frames.length}), in ${options.out}`);
+  for (const frame of result.frames) {
+    lines.push(`  ${String(frame.at).padStart(5)}ms  ${frame.file}`);
+  }
+
+  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 {
+    for (const child of result.timeline.children) {
+      const forever = child.repeat === -1;
+      lines.push(
+        `  ${child.targets.join(", ") || "(no target)"} · ${child.duration}s` +
+          `${forever ? ", repeats forever" : child.repeat ? `, repeats ${child.repeat}` : ""}` +
+          `${child.yoyo ? ", yoyo" : ""}${child.paused ? ", paused" : ""}` +
+          `${child.ease ? `, ease ${child.ease}` : ""}` +
+          `${child.props.length ? ` · ${child.props.join(" ")}` : ""}`,
+      );
+    }
+  }
+
+  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(
+    `  ${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.");
+
+  return lines.join("\n");
+}
+
+// --- Entry -------------------------------------------------------------------
+
+async function main(argv) {
+  const options = parseOptions(argv);
+
+  if (options.errors.length) {
+    for (const error of options.errors) console.error(error);
+    console.error("\nUsage: node capture-motion.mjs <url> [--at 0,300,900] [--hover <sel>] …");
+    process.exit(2);
+  }
+
+  try {
+    const result = await capture(options);
+    console.log(options.json ? JSON.stringify(result, null, 2) : report(result, options));
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) await main(process.argv.slice(2));

package/skill/scripts/explain-motion.mjs

@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+
+/**
+ * Maps an animation: what it does, in what order, under what conditions, and
+ * what cleans it up.
+ *
+ * It changes nothing and judges nothing. Every line says where it came from,
+ * because that is the difference between a map and a guess:
+ *
+ *   (file)     read from the syntax tree — this is what the code says
+ *   (comment)  the reason the author wrote down, quoted
+ *   (audit)    a finding, with the rule that made it
+ *   (page)     read from the running page, which may differ from the source
+ *   (inferred) a reading, not a fact
+ *
+ * Given files it reads the code. Given a URL it reads the running page, where
+ * the timeline is the one GSAP actually built — after every condition, branch
+ * and early return the source has.
+ *
+ * Usage, from the project root:
+ *   node <skill-dir>/scripts/explain-motion.mjs <file...> [--json]
+ *   node <skill-dir>/scripts/explain-motion.mjs <url> [--json] [--wait 600]
+ */
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+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,
+  tweenMethod,
+  unwrap,
+} from "./lib/ast.mjs";
+import { RULES } from "./lib/rules.mjs";
+import { collect, lineAt, load } from "./lib/source.mjs";
+
+// --- Reading the code --------------------------------------------------------
+
+/** The source of a node, on one line, short enough to read in a list. */
+const textOf = (file, node, limit = 48) => {
+  if (!node) return null;
+  const text = file.raw.slice(node.start, node.end).replace(/\s+/g, " ").trim();
+  return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+};
+
+/**
+ * The comment block immediately above `node`, which is where the reason usually
+ * is. Only a block that ends within two lines counts: a comment further up
+ * belongs to something else.
+ */
+function reasonFor(file, node) {
+  const line = lineAt(file.raw, node.start);
+  const above = file.comments
+    .filter((comment) => {
+      const ends = lineAt(file.raw, comment.end);
+      return ends < line && line - ends <= 2;
+    })
+    .sort((a, b) => b.end - a.end)[0];
+  if (!above) return null;
+
+  const sentence = above.value
+    .split("\n")
+    .map((row) => row.replace(/^\s*\*?\s?/, "").trim())
+    .filter(Boolean)
+    .join(" ")
+    .trim();
+  return sentence.length > 96 ? `${sentence.slice(0, 95)}…` : sentence;
+}
+
+/** The position argument of a timeline call: `"<"`, `"-=0.2"`, a number. */
+function positionOf(file, call) {
+  const method = methodName(call);
+  const index = method === "fromTo" ? 3 : 2;
+  return textOf(file, call.arguments[index], 16);
+}
+
+/** Where a call keeps its vars: a timeline at 0, a fromTo at 2, everything else at 1. */
+const varsOf = (call) => {
+  const method = methodName(call) ?? tweenMethod(call);
+  const index = method === "timeline" ? 0 : method === "fromTo" ? 2 : 1;
+  const node = unwrap(call.arguments[index]);
+  return node?.type === "ObjectExpression" ? node : null;
+};
+
+/**
+ * Where a call reads as starting. In `tl.from(a).from(b)` both calls begin at
+ * `tl`, so the method's own name is what tells the beats apart — and what puts
+ * each one's comment above the right beat.
+ */
+const startOf = (call) => unwrap(call.callee)?.property?.start ?? call.start;
+
+const valueOf = (vars, key) => {
+  const property = vars && propertyOf(vars, key);
+  if (!property) return null;
+  const literal = unwrap(property.value);
+  if (literal?.type === "Literal") return String(literal.value);
+  return null;
+};
+
+/** The scroll configuration of a tween's vars, or of a ScrollTrigger.create. */
+function triggerOf(file, call) {
+  const vars = varsOf(call);
+  const own = vars && propertyOf(vars, "scrollTrigger");
+  const config = own ? unwrap(own.value) : null;
+  const direct =
+    calleeName(call) === "ScrollTrigger.create"
+      ? unwrap(call.arguments[0])
+      : null;
+  const object = config?.type === "ObjectExpression" ? config : direct?.type === "ObjectExpression" ? direct : null;
+  if (!object) return null;
+
+  const read = (key) => {
+    const property = propertyOf(object, key);
+    return property ? textOf(file, property.value, 24) : null;
+  };
+
+  return {
+    line: lineAt(file.raw, (own ?? call).start),
+    trigger: read("trigger"),
+    start: read("start"),
+    end: read("end"),
+    scrub: read("scrub"),
+    pin: read("pin"),
+    toggleActions: read("toggleActions"),
+  };
+}
+
+function readFile(file) {
+  const map = {
+    file: file.display,
+    scopes: [],
+    branches: [],
+    scenes: [],
+    loose: [],
+    triggers: [],
+    findings: [],
+  };
+
+  // Where animation is created, and what owns its cleanup.
+  for (const call of findAll(file.ast, (node) => {
+    const name = calleeName(node);
+    return name === "useGSAP" || name === "gsap.context";
+  })) {
+    const vars = unwrap(call.arguments[1]);
+    map.scopes.push({
+      kind: calleeName(call),
+      line: lineAt(file.raw, call.start),
+      scope:
+        vars?.type === "ObjectExpression"
+          ? textOf(file, propertyOf(vars, "scope")?.value, 24)
+          : textOf(file, call.arguments[1], 24),
+      why: reasonFor(file, call),
+    });
+  }
+
+  // Device and preference branches.
+  for (const call of findAll(file.ast, (node) => methodName(node) === "add")) {
+    const conditions = unwrap(call.arguments[0]);
+    if (conditions?.type === "ObjectExpression") {
+      const named = conditions.properties
+        .map((property) => {
+          const query = staticString(property.value);
+          return query ? `${property.key.name ?? property.key.value}: ${query}` : null;
+        })
+        .filter(Boolean);
+      if (named.length) {
+        map.branches.push({ line: lineAt(file.raw, call.start), conditions: named });
+      }
+    } else {
+      const query = staticString(call.arguments[0]);
+      if (query && /\(.*:.*\)/.test(query)) {
+        map.branches.push({ line: lineAt(file.raw, call.start), conditions: [query] });
+      }
+    }
+  }
+
+  // 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 = [];
+    for (const link of timelineLinks(file.ast, timeline)) {
+      claimed.add(link);
+      const method = methodName(link);
+      if (method === "addLabel") {
+        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;
+
+      const vars = varsOf(link);
+      beats.push({
+        line: lineAt(file.raw, startOf(link)),
+        method,
+        target: textOf(file, link.arguments[0], 32),
+        duration: valueOf(vars, "duration"),
+        ease: valueOf(vars, "ease"),
+        at: positionOf(file, link),
+        why: reasonFor(file, { start: startOf(link) }),
+      });
+    }
+
+    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 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.
+  const handed = new Map();
+  for (const call of findAll(file.ast, (node) =>
+    ["to", "from", "fromTo", "set", "addLabel", "call"].includes(methodName(node)),
+  )) {
+    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 = 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]) ?? textOf(file, call.arguments[0], 24) ?? "(label)",
+          }
+        : {
+            line: lineAt(file.raw, startOf(call)),
+            method,
+            target: textOf(file, call.arguments[0], 32),
+            duration: valueOf(vars, "duration"),
+            ease: valueOf(vars, "ease"),
+            at: positionOf(file, call),
+            why: reasonFor(file, { start: startOf(call) }),
+          },
+    );
+  }
+  map.handed = [...handed.entries()].map(([owner, beats]) => ({ owner, beats }));
+  for (const scene of map.scenes) {
+    scene.beats.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+  }
+
+  // Tweens that belong to no timeline.
+  for (const call of findAll(file.ast, (node) => tweenMethod(node) !== null)) {
+    if (claimed.has(call) || timelines.includes(call)) continue;
+    if (calleeName(call)?.startsWith("gsap.") !== true) continue;
+    const vars = varsOf(call);
+    map.loose.push({
+      line: lineAt(file.raw, call.start),
+      method: tweenMethod(call),
+      target: textOf(file, call.arguments[0], 32),
+      duration: valueOf(vars, "duration"),
+      ease: valueOf(vars, "ease"),
+      repeat: valueOf(vars, "repeat"),
+      why: reasonFor(file, call),
+    });
+  }
+
+  // Scroll configuration, wherever it is written.
+  for (const call of findAll(file.ast, (node) => node.type === "CallExpression")) {
+    const trigger = triggerOf(file, call);
+    if (trigger) map.triggers.push(trigger);
+  }
+
+  // What the audit says about this file, so a claim can cite a rule.
+  for (const rule of RULES) {
+    for (const finding of check(rule, file)) {
+      map.findings.push({ line: finding.line, rule: finding.rule, level: finding.level, message: finding.message });
+    }
+  }
+
+  return map;
+}
+
+// --- Reading the page --------------------------------------------------------
+
+const LIVE = `(() => {
+  const out = { gsap: typeof gsap !== "undefined", children: [], triggers: [], reduced: null };
+  out.reduced = matchMedia("(prefers-reduced-motion: reduce)").matches;
+  if (!out.gsap) return out;
+
+  out.children = gsap.globalTimeline.getChildren(true, true, true).map((child) => ({
+    targets: (child.targets?.() ?? []).map((target) =>
+      target?.id ? "#" + target.id : target?.tagName ? target.tagName.toLowerCase() : String(target)
+    ),
+    duration: child.duration?.() ?? 0,
+    repeat: child.repeat?.() ?? 0,
+    paused: child.paused?.() ?? false,
+    ease: typeof child.vars?.ease === "string" ? child.vars.ease : null,
+  }));
+
+  const ScrollTriggerClass = globalThis.ScrollTrigger ?? gsap.core?.globals?.().ScrollTrigger;
+  if (ScrollTriggerClass?.getAll) {
+    out.triggers = ScrollTriggerClass.getAll().map((trigger) => ({
+      element: trigger.trigger?.id ? "#" + trigger.trigger.id : trigger.trigger?.tagName?.toLowerCase() ?? null,
+      start: trigger.start,
+      end: trigger.end,
+      scrub: Boolean(trigger.vars?.scrub),
+      pin: Boolean(trigger.vars?.pin),
+      progress: Number((trigger.progress ?? 0).toFixed(3)),
+    }));
+  }
+  return out;
+})()`;
+
+async function readPage(url, { wait = 600, chrome = null } = {}) {
+  const executable = findChrome(chrome);
+  if (!executable) {
+    throw new Error("No Chrome found. Install Chrome, pass --chrome <path>, or set CHROME_PATH.");
+  }
+
+  const browser = connect(executable);
+  try {
+    const { targetId } = await browser.send("Target.createTarget", { url: "about:blank" });
+    const { sessionId } = await browser.send("Target.attachToTarget", { targetId, flatten: true });
+    const call = (method, params) => browser.send(method, params, sessionId);
+
+    await call("Page.enable");
+    await call("Runtime.enable");
+    await call("Page.navigate", { url });
+    await new Promise((done) => setTimeout(done, wait));
+
+    const { result } = await call("Runtime.evaluate", {
+      expression: LIVE,
+      returnByValue: true,
+      awaitPromise: true,
+    });
+    return { url, ...result.value };
+  } finally {
+    await browser.close();
+  }
+}
+
+// --- Reporting ---------------------------------------------------------------
+
+function reportFile(map) {
+  const lines = [`${map.file}`];
+  const say = (text) => lines.push(`  ${text}`);
+
+  if (map.scopes.length) {
+    say("");
+    say("Where it lives");
+    for (const scope of map.scopes) {
+      say(`  ${scope.line}: ${scope.kind}${scope.scope ? ` scoped to ${scope.scope}` : ""}   (file)`);
+      if (scope.why) say(`      "${scope.why}"   (comment)`);
+    }
+  }
+
+  if (map.branches.length) {
+    say("");
+    say("Branches");
+    for (const branch of map.branches) {
+      say(`  ${branch.line}: ${branch.conditions.join(" · ")}   (file)`);
+    }
+  }
+
+  for (const scene of map.scenes) {
+    say("");
+    say(`Scene at line ${scene.line}${scene.name ? ` (${scene.name})` : ""}${scene.repeat === "-1" ? ", repeats forever" : ""}   (file)`);
+    if (scene.why) say(`    "${scene.why}"   (comment)`);
+    for (const beat of scene.beats) {
+      if (beat.label) {
+        say(`    label "${beat.label}"`);
+        continue;
+      }
+      const parts = [
+        `${beat.method} ${beat.target ?? ""}`.trim(),
+        beat.duration ? `${beat.duration}s` : null,
+        beat.ease ? `ease ${beat.ease}` : null,
+        beat.at ? `at ${beat.at}` : null,
+      ].filter(Boolean);
+      say(`    ${beat.line}: ${parts.join(" · ")}`);
+      if (beat.why) say(`        "${beat.why}"   (comment)`);
+    }
+  }
+
+  for (const scene of map.handed ?? []) {
+    say("");
+    say(`Beats this file adds to ${scene.owner}, a timeline it was given   (file)`);
+    for (const beat of scene.beats) {
+      if (beat.label) {
+        say(`    label "${beat.label}"`);
+        continue;
+      }
+      const parts = [
+        `${beat.method} ${beat.target ?? ""}`.trim(),
+        beat.duration ? `${beat.duration}s` : null,
+        beat.ease ? `ease ${beat.ease}` : null,
+        beat.at ? `at ${beat.at}` : null,
+      ].filter(Boolean);
+      say(`    ${beat.line}: ${parts.join(" · ")}`);
+      if (beat.why) say(`        "${beat.why}"   (comment)`);
+    }
+  }
+
+  if (map.loose.length) {
+    say("");
+    say("Tweens on no timeline   (file)");
+    for (const tween of map.loose) {
+      const parts = [
+        `${tween.method} ${tween.target ?? ""}`.trim(),
+        tween.duration ? `${tween.duration}s` : null,
+        tween.ease ? `ease ${tween.ease}` : null,
+        tween.repeat === "-1" ? "repeats forever" : null,
+      ].filter(Boolean);
+      say(`  ${tween.line}: ${parts.join(" · ")}`);
+    }
+  }
+
+  if (map.triggers.length) {
+    say("");
+    say("Scroll   (file)");
+    for (const trigger of map.triggers) {
+      const parts = [
+        trigger.trigger ? `trigger ${trigger.trigger}` : null,
+        trigger.start ? `start ${trigger.start}` : null,
+        trigger.end ? `end ${trigger.end}` : null,
+        trigger.scrub ? `scrub ${trigger.scrub}` : null,
+        trigger.pin ? `pin ${trigger.pin}` : null,
+        trigger.toggleActions ? `toggleActions ${trigger.toggleActions}` : null,
+      ].filter(Boolean);
+      say(`  ${trigger.line}: ${parts.join(" · ") || "(no options read)"}`);
+    }
+  }
+
+  say("");
+  if (map.findings.length) {
+    say("What the audit says");
+    for (const finding of map.findings) {
+      say(`  ${finding.line}: ${finding.message} [${finding.rule}]   (audit)`);
+    }
+  } else {
+    say("The audit reports nothing on this file.   (audit)");
+  }
+
+  return lines.join("\n");
+}
+
+function reportPage(page) {
+  const lines = [`${page.url}   (page)`];
+  const say = (text) => lines.push(`  ${text}`);
+
+  say("");
+  say(`Reduced motion: ${page.reduced ? "the visitor asked for less" : "no preference"}`);
+
+  say("");
+  if (!page.gsap) {
+    say("No GSAP on the page. Either it never loaded, or nothing here animates with it.");
+    return lines.join("\n");
+  }
+
+  say(`Running now: ${page.children.length} tween(s) or timeline(s) on the global timeline`);
+  for (const child of page.children) {
+    const parts = [
+      child.targets.join(", ") || "(no target)",
+      `${Number(child.duration.toFixed(3))}s`,
+      child.repeat === -1 ? "repeats forever" : child.repeat ? `repeats ${child.repeat}` : null,
+      child.paused ? "paused" : null,
+      child.ease ? `ease ${child.ease}` : null,
+    ].filter(Boolean);
+    say(`  ${parts.join(" · ")}`);
+  }
+
+  say("");
+  say(`ScrollTriggers: ${page.triggers.length}`);
+  for (const trigger of page.triggers) {
+    const parts = [
+      trigger.element ?? "(no element)",
+      `${Math.round(trigger.start)}→${Math.round(trigger.end)}`,
+      trigger.scrub ? "scrub" : null,
+      trigger.pin ? "pin" : null,
+      `progress ${trigger.progress}`,
+    ].filter(Boolean);
+    say(`  ${parts.join(" · ")}`);
+  }
+
+  say("");
+  say("A finished tween leaves the global timeline, so what is here is what is running now.");
+  return lines.join("\n");
+}
+
+// --- Entry -------------------------------------------------------------------
+
+export function parseArguments(argv) {
+  const options = { targets: [], json: false, wait: 600, chrome: null, errors: [] };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--json") options.json = true;
+    else if (argument === "--wait") options.wait = Number(argv[(index += 1)]) || options.wait;
+    else if (argument === "--chrome") options.chrome = argv[(index += 1)] ?? null;
+    else if (argument.startsWith("--")) options.errors.push(`Unknown option: ${argument}`);
+    else options.targets.push(argument);
+  }
+
+  if (options.targets.length === 0) {
+    options.errors.push("Nothing to explain. Pass a file, a directory, or a URL.");
+  }
+
+  options.live = options.targets.some((target) => /^https?:|^file:/.test(target));
+  if (options.live && options.targets.length > 1) {
+    options.errors.push("Explain one URL at a time.");
+  }
+
+  return options;
+}
+
+async function main(argv) {
+  const options = parseArguments(argv);
+  if (options.errors.length) {
+    for (const error of options.errors) console.error(error);
+    console.error("\nUsage: node explain-motion.mjs <file...|url> [--json]");
+    process.exit(2);
+  }
+
+  if (options.live) {
+    const page = await readPage(options.targets[0], options);
+    console.log(options.json ? JSON.stringify(page, null, 2) : reportPage(page));
+    return;
+  }
+
+  const root = process.cwd();
+  const maps = [];
+
+  for (const target of options.targets) {
+    const path = resolve(root, target);
+    if (!existsSync(path)) {
+      console.error(`No such path: ${path}`);
+      process.exit(2);
+    }
+    for (const found of collect(path)) {
+      const file = load(found, root);
+      if (!mentionsGsap(file)) continue;
+      if (file.parseError) {
+        maps.push({ file: file.display, parseError: file.parseError.message });
+        continue;
+      }
+      maps.push(readFile(file));
+    }
+  }
+
+  if (maps.length === 0) {
+    console.log("Nothing here animates with GSAP.");
+    return;
+  }
+
+  console.log(
+    options.json
+      ? JSON.stringify(maps, null, 2)
+      : maps
+          .map((map) =>
+            map.parseError ? `${map.file}\n  could not be parsed: ${map.parseError}` : reportFile(map),
+          )
+          .join("\n\n"),
+  );
+}
+
+const invoked = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (invoked) await main(process.argv.slice(2));