@mehshekari/gsap-motion 4.4.2 → 4.5.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.4.2 audit src --quiet"
+"lint": "eslint && npx @mehshekari/gsap-motion@4.5.0 audit src --quiet"
 ```
 
 Or install it with `npm install --save-dev --save-exact @mehshekari/gsap-motion`.

package/bin/gsap-motion.mjs

@@ -74,12 +74,14 @@ Commands
     --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
+    --at 0,300,900      When to capture, in ms after --wait
+    --wait 400          A fixed wait after navigation; it does not detect a loader
     --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
+    --viewport 1440x900 The window's size; every report prints the one used
     --cpu 4             Throttle the CPU by this factor
     --headed            A visible Chrome on the GPU, for WebGL pages
     --seek <name>       Call window.<name>(t) before each capture; --at is
@@ -96,6 +98,7 @@ Commands
     --scroll <px|sel>   Scroll, then watch again
     --reduced --dark    Emulate a preference
     --mobile            390x844 with touch input
+    --viewport 1440x900 The window's size; every report prints the one used
     --cpu 4             Throttle the CPU by this factor
     --headed            A visible Chrome on the GPU, for WebGL pages
     --out <dir>         Save a frame alongside the measurements
@@ -297,7 +300,15 @@ function doctor(args = []) {
       if (provider) report("info", `No separate copy for ${scope}`);
       else report("info", `Not installed for ${scope}`, `${command} installs it at ${location}`);
     } else if (installed.version === bundled.version) {
-      report("ok", `Installed for ${scope}: ${installed.version}`);
+      if (provider) {
+        report(
+          "warn",
+          `Installed for ${scope}: ${installed.version}`,
+          `The ${provider} plugin provides it too, so the skill is listed twice. Remove ${location}.`,
+        );
+      } else {
+        report("ok", `Installed for ${scope}: ${installed.version}`);
+      }
     } else {
       report(
         "warn",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mehshekari/gsap-motion",
-  "version": "4.4.2",
+  "version": "4.5.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.4.2"
+  version: "4.5.0"
   verified-gsap: "3.15"
   verified-gsap-react: "2.1"
 ---

package/skill/adapter/react.md

@@ -34,8 +34,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. Inside `mm.add`, use its own: the callback's
+context owns it — with every tween it makes, killed ones too, until it reverts.
+A frequent handler replays a timeline built in the body, or calls a `quickTo`. 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`
@@ -103,8 +103,7 @@ onMouseMove = (e) => moveX(e.clientX);
 ```
 
 State is for *what exists* — is the modal open, which tab is active. GSAP owns
-*how it moves*. Crossing that line is the most common performance bug in
-animated React.
+*how it moves*.
 
 ## Page and route changes
 

package/skill/reference/refine.md

@@ -75,6 +75,15 @@ Reach the state first, and change the conditions that usually break things:
 - `--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.
+- `--viewport 1440x900` for a desktop layout. Without it the window is whatever
+  headless Chrome opens at — about 760×480 — where many sites switch to their
+  compact layout. Every report prints the viewport it ran at.
+- `--wait` is a fixed wait after navigation; it does not detect a loader. Raise
+  it, or use `--seek`.
+- **A step that did nothing fails the run.** Nothing matched, no match on
+  screen, or an invalid selector: it is listed last, under *Not done*, and the
+  run exits 3 — 2 for an invalid selector. A hidden match is passed over for
+  the next one, and one off screen is scrolled to first.
 - **Cost on a production build, not the dev server.** In development React's
   StrictMode mounts every effect twice — two contexts, two WebGL contexts — and
   the bundle is unminified, so what a dev server measures is not what ships.

package/skill/scripts/audit-gsap.mjs

@@ -32,12 +32,12 @@
  *
  * Exit code is 1 when any error-level finding is reported, 0 otherwise.
  */
-import { existsSync } from "node:fs";
+import { existsSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
 import { check, mentionsGsap, notParsed } from "./lib/audit.mjs";
 import { pluginRegistrations, RULES } from "./lib/rules.mjs";
-import { collect, load } from "./lib/source.mjs";
+import { collect, hasSourceExtension, load } from "./lib/source.mjs";
 
 /**
  * The project being audited is wherever this is run from, not wherever the
@@ -66,6 +66,12 @@ for (const path of paths) {
 
 const findings = [];
 const sources = [];
+/**
+ * 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
+ * reads as "checked and fine" about a file nothing looked at.
+ */
+const notScanned = [];
 
 /** A finding as the report shows it: under the file's display path, no column. */
 const reported = (source, finding) => ({
@@ -78,6 +84,10 @@ const reported = (source, finding) => ({
 });
 
 for (const path of paths) {
+  if (statSync(path).isFile() && !hasSourceExtension(path)) {
+    notScanned.push(path);
+    continue;
+  }
   for (const file of collect(path)) {
     const source = load(file, ROOT);
     if (!mentionsGsap(source)) continue;
@@ -124,8 +134,14 @@ findings.sort(
 
 const shown = quiet ? findings.filter((f) => f.level === "error") : findings;
 
+const READS = "the audit reads .ts, .tsx, .js, .jsx and .mjs, and the scripts of .vue, .svelte and .astro files";
+if (notScanned.length === paths.length) {
+  for (const path of notScanned) console.error(`Not scanned: ${path} — ${READS}.`);
+  process.exit(2);
+}
+
 if (asJson) {
-  console.log(JSON.stringify({ findings: shown }, null, 2));
+  console.log(JSON.stringify({ findings: shown, notScanned }, null, 2));
 } else if (!shown.length) {
   console.log(
     findings.length
@@ -157,4 +173,8 @@ if (asJson) {
   );
 }
 
+if (!asJson) {
+  for (const path of notScanned) console.log(`Not scanned: ${path} — ${READS}.`);
+}
+
 process.exit(findings.some((f) => f.level === "error") ? 1 : 0);

package/skill/scripts/capture-motion.mjs

@@ -17,8 +17,11 @@
  * 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)
+ *   --at 0,300,900        when to capture, in ms after --wait
+ *   --wait 400            a fixed wait after navigation, before any step or
+ *                         capture (default 400). It does not detect a loader.
+ *   --viewport 1440x900   the window's size; the default is whatever headless
+ *                         Chrome opens at, and every report prints it
  *   --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
@@ -188,6 +191,7 @@ export function parseOptions(argv) {
     reduced: false,
     dark: false,
     mobile: false,
+    viewport: null,
     cpu: 1,
     json: false,
     chrome: null,
@@ -242,6 +246,12 @@ export function parseOptions(argv) {
       case "--mobile":
         options.mobile = true;
         break;
+      case "--viewport": {
+        const size = parseViewport(value());
+        if (size) options.viewport = size;
+        else options.errors.push("--viewport takes a width and height, such as --viewport 1440x900");
+        break;
+      }
       case "--cpu": {
         const rate = asNumber(value());
         if (rate === null || rate < 1) options.errors.push("--cpu takes a factor of 1 or more");
@@ -285,6 +295,10 @@ export function parseOptions(argv) {
     options.errors.push("--seek needs --at, in seconds of the timeline, such as --at 3,3.3,3.6");
   }
 
+  if (options.mobile && options.viewport) {
+    options.errors.push("--mobile sets its own viewport; drop one of --mobile and --viewport.");
+  }
+
   /** 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(
@@ -382,14 +396,97 @@ const SETTLED = "new Promise((done) => requestAnimationFrame(() => requestAnimat
 export const frameName = (at, options) =>
   options.seek ? `frame-${at.toFixed(3).padStart(8, "0")}s.png` : `frame-${String(at).padStart(5, "0")}ms.png`;
 
-/** 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 first match a pointer can reach, read live so it lands on an element that
+ * is moving. Three real pages defeated "the first match": a header holding two
+ * copies of a button with the first in a collapsed container, five links of
+ * which only the last was on screen, and a match scrolled out of the viewport,
+ * where the pointer landed at a negative y and the run still said it clicked.
+ * So every match is tried in order, one with no box or hidden is passed over,
+ * and one outside the viewport is scrolled into it first. An invalid selector
+ * is said to be one, rather than matching nothing.
+ */
+export const pointAt = (selector) => `(() => {
+  let all;
+  try {
+    all = [...document.querySelectorAll(${JSON.stringify(selector)})];
+  } catch {
+    return { invalid: true };
+  }
+  const shown = (el) => {
+    const box = el.getBoundingClientRect();
+    return box.width > 0 && box.height > 0 && getComputedStyle(el).visibility !== "hidden";
+  };
+  const index = all.findIndex(shown);
+  if (index === -1) return { matches: all.length, index };
+  const el = all[index];
+  let box = el.getBoundingClientRect();
+  const inView = box.bottom > 0 && box.right > 0 && box.top < innerHeight && box.left < innerWidth;
+  if (!inView) {
+    el.scrollIntoView({ block: "center", behavior: "instant" });
+    box = el.getBoundingClientRect();
+  }
+  const clamp = (v, max) => Math.min(max - 1, Math.max(0, v));
+  return {
+    matches: all.length,
+    index,
+    scrolled: !inView,
+    x: clamp(box.x + box.width / 2, innerWidth),
+    y: clamp(box.y + box.height / 2, innerHeight),
+    width: box.width,
+    height: box.height,
+  };
 })()`;
 
+/**
+ * Scrolls instantly, then reports where the page is once two frames have drawn.
+ * A page with `scroll-behavior: smooth` used to animate the jump, so the
+ * position was read as 0 while it travelled, and frames were captured mid-way.
+ */
+export function scrollExpression(value) {
+  const pixels = /^\d+$/.test(String(value)) ? Number(value) : null;
+  const move =
+    pixels === null
+      ? `let el;
+    try { el = document.querySelector(${JSON.stringify(value)}); } catch { done({ invalid: true }); return; }
+    if (!el) { done({ matches: 0 }); return; }
+    el.scrollIntoView({ block: "center", behavior: "instant" });`
+      : `window.scrollTo({ top: ${pixels}, behavior: "instant" });`;
+  return `new Promise((done) => {
+    ${move}
+    requestAnimationFrame(() => requestAnimationFrame(() => done({ y: Math.round(window.scrollY) })));
+  })`;
+}
+
+/** What a step that did nothing says, or null when it did something. */
+export function undone(step, result) {
+  if (result?.invalid) return `${step.type}: ${step.value} is not a valid selector`;
+  if (!result || result.matches === 0) return `${step.type}: nothing matched ${step.value}`;
+  if (result.index === -1) {
+    const n = result.matches;
+    return `${step.type}: ${step.value} matched ${n} element${n === 1 ? "" : "s"}, none with a box on screen`;
+  }
+  return null;
+}
+
+/**
+ * The exit code a run earns: 2 for an invalid selector, 3 when a step asked for
+ * did nothing, 0 otherwise. A step that did nothing used to leave a note in the
+ * middle of the report and exit 0, which a script — or a reader with `| tail` —
+ * took as done.
+ */
+export const exitFor = (notDone) =>
+  notDone.some((line) => line.endsWith("is not a valid selector")) ? 2 : notDone.length ? 3 : 0;
+
+/** `--viewport 1440x900`, as numbers, or null. */
+export function parseViewport(text) {
+  const match = /^(\d{2,5})x(\d{2,5})$/.exec(String(text ?? ""));
+  return match ? { width: Number(match[1]), height: Number(match[2]) } : null;
+}
+
+/** What the page measured itself at, for every report: a default nobody chose is still a size. */
+export const VIEWPORT = "({ width: innerWidth, height: innerHeight })";
+
 // --- Where output goes -------------------------------------------------------
 
 /**
@@ -483,6 +580,9 @@ async function capture(options) {
       });
       await call("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
     }
+    if (options.viewport) {
+      await call("Emulation.setDeviceMetricsOverride", { ...options.viewport, deviceScaleFactor: 1, mobile: false });
+    }
 
     if (options.cpu > 1) await call("Emulation.setCPUThrottlingRate", { rate: options.cpu });
 
@@ -492,36 +592,20 @@ async function capture(options) {
     await call("Page.navigate", { url: options.url });
     await wait(options.wait);
 
+    const notDone = [];
     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`,
-        );
+        const moved = await evaluate(scrollExpression(step.value));
+        const missed = undone(step, moved);
+        if (missed) notDone.push(missed);
+        else notes.push(`scroll: to ${moved.y}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`,
-          );
+        const box = await evaluate(pointAt(step.value));
+        const missed = undone(step, box) ?? (pointable(box) ? null : undone(step, { ...box, index: -1 }));
+        if (missed) {
+          notDone.push(missed);
           continue;
         }
         /**
@@ -550,8 +634,10 @@ async function capture(options) {
             });
           }
         }
+        const which = box.matches > 1 ? ` (match ${box.index + 1} of ${box.matches})` : "";
         notes.push(
-          `${step.type}: ${step.value} at ${Math.round(box.x)},${Math.round(box.y)}`,
+          `${step.type}: ${step.value}${which} at ${Math.round(box.x)},${Math.round(box.y)}` +
+            (box.scrolled ? ", scrolled into view first" : ""),
         );
         await wait(120);
       }
@@ -587,6 +673,7 @@ async function capture(options) {
       "({ frames: window.__gsapMotionFrames ?? null, since: window.__gsapMotionStart ?? null })",
     );
     const canvases = await evaluate("document.querySelectorAll(\"canvas\").length");
+    const viewport = await evaluate(VIEWPORT);
     const after = await call("Performance.getMetrics");
 
     const delta = (name) => {
@@ -611,7 +698,7 @@ async function capture(options) {
       overMs: span,
     };
 
-    return { url: options.url, frames, timeline, measured, notes, canvases, chrome: executable };
+    return { url: options.url, frames, timeline, measured, notes, notDone, canvases, viewport, chrome: executable };
   } finally {
     await browser.close();
   }
@@ -631,6 +718,7 @@ export function report(result, options) {
     options.seek && `seeking with window.${options.seek}`,
   ].filter(Boolean);
   if (emulated.length) lines.push(`  as: ${emulated.join(", ")}`);
+  if (result.viewport) lines.push(`  viewport: ${result.viewport.width}x${result.viewport.height}`);
   for (const note of result.notes) lines.push(`  ${note}`);
   const gpu = gpuNote(result.canvases, options);
   if (gpu) lines.push(`  ${gpu}`);
@@ -681,6 +769,11 @@ export function report(result, options) {
       ` · ${measured.recalcs} style recalculations (${measured.recalcSeconds}s)`,
   );
   lines.push("", "These are observations. What they mean is yours to judge.");
+  /** Last, so a reader who sees only the end still sees it. */
+  if (result.notDone?.length) {
+    lines.push("", "Not done — the run exits non-zero");
+    for (const line of result.notDone) lines.push(`  ${line}`);
+  }
 
   return lines.join("\n");
 }
@@ -704,6 +797,7 @@ async function main(argv) {
   try {
     const result = await capture(options);
     console.log(options.json ? JSON.stringify(result, null, 2) : report(result, options));
+    process.exitCode = exitFor(result.notDone);
   } catch (error) {
     console.error(error.message);
     process.exit(1);

package/skill/scripts/lib/ast.mjs

@@ -307,7 +307,7 @@ export const contains = (outer, inner) =>
  * returns `null`: an ambiguous handler is left unread rather than guessed at.
  */
 export function resolveFunction(root, node) {
-  const target = unwrap(node);
+  const target = wrappedFunction(unwrap(node));
   if (isFunction(target)) return target;
   if (target?.type !== "Identifier") return null;
 
@@ -318,13 +318,34 @@ export function resolveFunction(root, node) {
       (n.type === "VariableDeclarator" &&
         n.id.type === "Identifier" &&
         n.id.name === target.name &&
-        isFunction(unwrap(n.init))),
+        isFunction(wrappedFunction(unwrap(n.init)))),
   );
   if (declarations.length !== 1) return null;
   const [declaration] = declarations;
   return declaration.type === "FunctionDeclaration"
     ? declaration
-    : unwrap(declaration.init);
+    : wrappedFunction(unwrap(declaration.init));
+}
+
+/**
+ * The function inside a call that hands it back to run later, unchanged in
+ * what it does: `contextSafe(fn)`, `ctx.add(null, fn)` and `useCallback(fn, deps)`.
+ * The handler the skill recommends is wrapped in contextSafe, and following
+ * names stopped at the wrapper, so a tween per pointer event went unreported.
+ * Anything else is returned as it was.
+ */
+function wrappedFunction(node) {
+  if (node?.type !== "CallExpression") return node;
+  const name = calleeName(node)?.split(".").at(-1);
+  if (name === "contextSafe" || name === "useCallback") return unwrap(node.arguments[0]);
+  if (
+    name === "add" &&
+    unwrap(node.arguments[0])?.type === "Literal" &&
+    unwrap(node.arguments[0]).value === null
+  ) {
+    return unwrap(node.arguments[1]);
+  }
+  return node;
 }
 
 const PARENTS = new WeakMap();

package/skill/scripts/lib/rules.mjs

@@ -54,13 +54,15 @@ 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.",
+    "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.",
   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:
     "Keep it under a name and revert it when the component goes: `onUnmounted` in Vue, the function returned from `onMount` or `$effect` in Svelte, the `useEffect` cleanup in React, `astro:before-swap` in Astro. Everything created inside the context goes with it.",
   tweenPerFrame:
     "A tween per frame allocates an object per frame, and each one fights the last. Create a `gsap.quickTo()` or `quickSetter()` once outside the callback and call it inside — or, for scroll, scrub a timeline instead of writing values by hand.",
+  refReadInCleanup:
+    "So nothing is killed, and the tweens outlive the component. Capture the element in the effect body — `const el = ref.current` — and kill through that in the cleanup, or build the tweens in a useGSAP or gsap.context body, whose revert needs no ref.",
   allocationPerFrame:
     "Every frame's object is garbage by the next, and the collector reclaims it in a pause that lands as a dropped frame. Build it once, outside the callback — at module scope, or in a ref or useMemo — and reuse it with `.set()` or `.copy()`.",
   layoutReadPerFrame:
@@ -96,7 +98,7 @@ const HINT = {
   unregisteredPlugin:
     "An unregistered plugin's properties are ignored without an error — the animation simply does nothing.",
   missingReducedMotion:
-    "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible.",
+    "Reduced motion is a design, not an off switch: decide what the motion was saying and say it without the travel. Note that the reduced branch must set the END state — a `from` that never runs leaves its target invisible. If the branch lives in the module that calls this one, waive it here and name that caller.",
   devToolImport:
     "A static import ships regardless of any `if` around the call. Load it with a dynamic `import()` behind a NODE_ENV check, or bake its output in and delete it.",
   markers: 'Gate it: `markers: process.env.NODE_ENV === "development"`.',
@@ -310,6 +312,91 @@ function debounced(handler, node) {
   );
 }
 
+/**
+ * Whether a tween's target is a local the enclosing effect captured, and that
+ * effect's code kills that local's tweens: `const el = ref.current` in the body,
+ * `gsap.killTweensOf(el)` in the cleanup. Found on the corpus, where it was
+ * reported as an orphan.
+ *
+ * Only a captured local counts. `killTweensOf(ref.current)` in a passive
+ * cleanup kills nothing at unmount — React has already cleared the ref — and
+ * that is `ref-read-in-cleanup`'s to say.
+ */
+function killedThroughCapture(ast, node) {
+  if (!isGsapCall(node)) return false;
+  const target = unwrap(node.arguments[0]);
+  if (target?.type !== "Identifier") return false;
+
+  const effect = ancestorsOf(ast, node).find((fn) => {
+    if (!isFunction(fn)) return false;
+    const call = parentOf(ast, fn);
+    return (
+      call?.type === "CallExpression" &&
+      call.arguments[0] === fn &&
+      EFFECTS.has(calleeName(call)?.split(".").at(-1))
+    );
+  });
+  if (!effect) return false;
+
+  const captured = findAll(
+    effect,
+    (n) => n.type === "VariableDeclarator" && n.id.type === "Identifier" && n.id.name === target.name,
+  ).length > 0;
+  if (!captured) return false;
+
+  /**
+   * In the cleanup — the function the effect returns — and nowhere else. A
+   * kill at the top of the body stops the previous run's tweens before
+   * starting new ones; it does nothing at unmount. Nine true corpus findings
+   * did exactly that, and the first version of this check let them go.
+   */
+  const cleanups = cleanupsOf(ast, effect);
+
+  const names = (arg) => {
+    const value = unwrap(arg);
+    if (value?.type === "Identifier") return [value.name];
+    if (value?.type === "ArrayExpression") return value.elements.flatMap((e) => (e ? names(e) : []));
+    return [];
+  };
+  return cleanups.some(
+    (cleanup) =>
+      findAll(
+        cleanup,
+        (n) =>
+          n.type === "CallExpression" &&
+          calleeName(n)?.endsWith("killTweensOf") &&
+          n.arguments.some((arg) => names(arg).includes(target.name)),
+      ).length > 0,
+  );
+}
+
+const EFFECTS = new Set(["useEffect", "useLayoutEffect"]);
+
+/** The functions an effect callback returns: its cleanups. */
+function cleanupsOf(ast, effect) {
+  const cleanups = findAll(
+    effect,
+    (n) => n.type === "ReturnStatement" && n.argument && scopeOf(ast, n) === effect,
+  )
+    .map((n) => unwrap(n.argument))
+    .filter(isFunction);
+  if (effect.type === "ArrowFunctionExpression" && effect.expression && isFunction(unwrap(effect.body))) {
+    cleanups.push(unwrap(effect.body));
+  }
+  return cleanups;
+}
+
+/** Whether `node` reads a ref: a `.current` anywhere inside it. */
+const readsRef = (node) =>
+  findAll(
+    node,
+    (n) =>
+      n.type === "MemberExpression" &&
+      !n.computed &&
+      n.property.type === "Identifier" &&
+      n.property.name === "current",
+  ).length > 0;
+
 /** The calls that add a child to a timeline. */
 const CHILDREN = new Set(["to", "from", "fromTo", "add"]);
 
@@ -341,6 +428,22 @@ function tornDown(ast, node) {
   const kept = keptUnder(ast, node);
   if (endsUnder(kept?.name)) return true;
 
+  /**
+   * A second name for it: `active = timeline`, then `active?.kill()` in the
+   * cleanup. Found on the corpus, in a preview whose timeline was built in a
+   * helper and handed to a variable the effect owns.
+   */
+  if (kept?.name) {
+    const aliases = findAll(ast, (n) => {
+      const from = n.type === "AssignmentExpression" ? n.right : n.type === "VariableDeclarator" ? n.init : null;
+      const to = n.type === "AssignmentExpression" ? n.left : n.type === "VariableDeclarator" ? n.id : null;
+      return unwrap(from)?.type === "Identifier" && unwrap(from).name === kept.name && to?.type === "Identifier";
+    }).map((n) => (n.type === "AssignmentExpression" ? n.left.name : n.id.name));
+    if (aliases.some(endsUnder)) return true;
+  }
+
+  if (killedThroughCapture(ast, node)) return true;
+
   const fn = scopeOf(ast, node);
   if (!isFunction(fn)) return false;
 
@@ -886,6 +989,62 @@ export const RULES = [
       });
     },
   },
+  {
+    id: "ref-read-in-cleanup",
+    level: "warn",
+    description:
+      "`killTweensOf` given a ref's `.current` in a `useEffect` cleanup, where React has already cleared it at unmount",
+    /**
+     * At unmount React detaches a DOM ref before it runs passive cleanups, so
+     * `ref.current` is null there and the kill finds nothing. A corpus project
+     * did this in three cleanups, and fifteen tweens outlived their component.
+     *
+     * Narrow on purpose. Only `useEffect`: when a layout cleanup runs relative
+     * to ref detachment is not something this rule is sure of. Only
+     * `killTweensOf`, whose argument is the element: a ref that holds a timeline
+     * — `tlRef.current?.kill()` — is not cleared by React, and is correct.
+     */
+    test(file) {
+      if (!file.isReact) return [];
+      const effects = findAll(
+        file.ast,
+        (n) => n.type === "CallExpression" && calleeName(n)?.split(".").at(-1) === "useEffect",
+      )
+        .map((call) => unwrap(call.arguments[0]))
+        .filter(isFunction);
+
+      return effects.flatMap((effect) =>
+        cleanupsOf(file.ast, effect).flatMap((cleanup) => {
+          /** A local the cleanup itself reads from a ref: `const root = rootRef.current`. */
+          const fromRef = new Set(
+            findAll(
+              cleanup,
+              (n) =>
+                n.type === "VariableDeclarator" &&
+                n.id.type === "Identifier" &&
+                n.init &&
+                readsRef(n.init),
+            ).map((n) => n.id.name),
+          );
+          const viaRef = (arg) =>
+            readsRef(arg) ||
+            findAll(arg, (n) => n.type === "Identifier" && fromRef.has(n.name)).length > 0;
+
+          return findAll(
+            cleanup,
+            (n) =>
+              n.type === "CallExpression" &&
+              calleeName(n)?.endsWith("killTweensOf") &&
+              n.arguments.some(viaRef),
+          ).map((call) => ({
+            index: call.start,
+            message: "`killTweensOf` reads a ref in a useEffect cleanup, which React has already cleared at unmount.",
+            hint: HINT.refReadInCleanup,
+          }));
+        }),
+      );
+    },
+  },
   {
     id: "dangling-listener",
     level: "warn",
@@ -1685,6 +1844,22 @@ export const RULES = [
       if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
         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.
+       */
+      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 [];
 
       const [first] = findAll(file.ast, (node) => {
         const method = tweenMethod(node);

package/skill/scripts/lib/source.mjs

@@ -241,7 +241,15 @@ export function fromText(raw, path, display = path) {
       /\bfrom ["']react["']/.test(code) ||
       /\bfrom ["']@gsap\/react["']/.test(code),
     isClient: /^\s*["']use client["']/m.test(code),
-    usesGsap: /\bfrom ["']gsap(?:\/|["'])/.test(code),
+    /**
+     * GSAP itself, or a binding named `gsap` from anywhere: a project's own
+     * wrapper (`import { gsap } from "@/core/motion/gsap"`) is common, and
+     * reading only the package left orphan-tween and missing-reduced-motion
+     * blind to every file in a real project that used one.
+     */
+    usesGsap:
+      /\bfrom ["']gsap(?:\/|["'])/.test(code) ||
+      /\bimport\s+(?!type\b)(?:gsap\b|\{[^}]*\bgsap\b[^}]*\})[^;]*?\bfrom\s*["']/.test(code),
   };
 }
 

package/skill/scripts/review-motion.mjs

@@ -27,7 +27,16 @@ import { writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { connect, findChrome, gpuNote, prepareOut } from "./capture-motion.mjs";
+import {
+  connect,
+  exitFor,
+  findChrome,
+  gpuNote,
+  parseViewport,
+  prepareOut,
+  scrollExpression,
+  undone,
+} from "./capture-motion.mjs";
 
 // --- What a recording means ---------------------------------------------------
 
@@ -201,7 +210,7 @@ export function afterScroll(found, scrolledAt, { settle = 300 } = {}) {
  */
 export function seamEvents(torn, { window = 50 } = {}) {
   const flat = torn.flatMap((element) =>
-    element.seams.map((seam) => ({ key: element.key, at: seam.at, jump: seam.jump })),
+    element.seams.map((seam) => ({ key: element.key, box: element.box, at: seam.at, jump: seam.jump })),
   );
   flat.sort((a, b) => a.at - b.at);
 
@@ -217,6 +226,7 @@ export function seamEvents(torn, { window = 50 } = {}) {
     events.push({
       at: seam.at,
       elements: new Set([seam.key]),
+      box: seam.box,
       least: seam.jump,
       most: seam.jump,
     });
@@ -226,6 +236,12 @@ export function seamEvents(torn, { window = 50 } = {}) {
     at: event.at,
     count: event.elements.size,
     example: [...event.elements][0],
+    /**
+     * Where the example was on screen, as [x, y, width, height]. A key like
+     * `div.absolute` names hundreds of elements in a Tailwind project; a real
+     * report could not find the one that tore.
+     */
+    box: event.box ?? null,
     least: event.least,
     most: event.most,
   }));
@@ -282,6 +298,7 @@ export function parseOptions(argv) {
     watch: 3000,
     scroll: null,
     mobile: false,
+    viewport: null,
     reduced: false,
     dark: false,
     cpu: 1,
@@ -337,6 +354,12 @@ export function parseOptions(argv) {
       case "--mobile":
         options.mobile = true;
         break;
+      case "--viewport": {
+        const size = parseViewport(next());
+        if (size) options.viewport = size;
+        else options.errors.push("--viewport takes a width and height, such as --viewport 1440x900.");
+        break;
+      }
       case "--reduced":
         options.reduced = true;
         break;
@@ -364,6 +387,9 @@ export function parseOptions(argv) {
   if (options.url === null && options.probe === null) {
     options.errors.push("No URL. Pass the page to review.");
   }
+  if (options.mobile && options.viewport) {
+    options.errors.push("--mobile sets its own viewport; drop one of --mobile and --viewport.");
+  }
   return options;
 }
 
@@ -606,6 +632,9 @@ async function watch(options) {
       });
       await call("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
     }
+    if (options.viewport) {
+      await call("Emulation.setDeviceMetricsOverride", { ...options.viewport, deviceScaleFactor: 1, mobile: false });
+    }
     if (options.cpu > 1) await call("Emulation.setCPUThrottlingRate", { rate: options.cpu });
 
     await call("Page.addScriptToEvaluateOnNewDocument", { source: RECORDER });
@@ -614,19 +643,13 @@ async function watch(options) {
     await call("Page.navigate", { url: options.url });
     await wait(options.watch);
 
+    const notDone = [];
     if (options.scroll !== null) {
-      const pixels = asNumber(options.scroll);
-      const moved = await evaluate(
-        pixels === null
-          ? `(() => {
-              const element = document.querySelector(${JSON.stringify(options.scroll)});
-              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 ${options.scroll}` : `scroll: to ${moved}px`);
+      const step = { type: "scroll", value: options.scroll };
+      const moved = await evaluate(scrollExpression(options.scroll));
+      const missed = undone(step, moved);
+      if (missed) notDone.push(missed);
+      else notes.push(`scroll: to ${moved.y}px`);
       await wait(options.watch);
     }
 
@@ -658,6 +681,7 @@ async function watch(options) {
       recalcs: delta("RecalcStyleCount"),
       shot,
       notes,
+      notDone,
     };
   } finally {
     await browser.close();
@@ -678,6 +702,7 @@ export function conclude(result) {
   /** One track per element, to find the loops that tear. */
   const tracks = new Map();
   const named = new Map();
+  const boxes = new Map();
   for (const frame of log) {
     for (const moved of frame.moved) {
       const id = moved.id ?? moved.key;
@@ -685,6 +710,7 @@ export function conclude(result) {
       track.push({ at: frame.at, x: moved.x });
       tracks.set(id, track);
       named.set(id, moved.key);
+      boxes.set(id, moved.box);
     }
   }
   const scrolledAt = log.filter((frame) => frame.scrolled).map((frame) => frame.at);
@@ -694,7 +720,12 @@ export function conclude(result) {
     if (track.length < 20) continue;
     const found = afterScroll(seams(track), scrolledAt);
     if (found.length) {
-      torn.push({ key: named.get(key) ?? key, seams: found.slice(0, 3), frames: track.length });
+      torn.push({
+        key: named.get(key) ?? key,
+        box: boxes.get(key) ?? null,
+        seams: found.slice(0, 3),
+        frames: track.length,
+      });
     }
   }
 
@@ -775,6 +806,8 @@ export function report(result, options) {
     options.headed && "headed, on the GPU",
   ].filter(Boolean);
   if (emulated.length) lines.push(`  as: ${emulated.join(", ")}`);
+  const { viewport } = result.recorded;
+  if (viewport) lines.push(`  viewport: ${viewport.width}x${viewport.height}`);
   for (const note of result.notes) lines.push(`  ${note}`);
   const gpu = gpuNote(found.canvases, options);
   if (gpu) lines.push(`  ${gpu}`);
@@ -787,7 +820,7 @@ export function report(result, options) {
     lines.push(`  first motion at ${found.firstMotion}ms`);
     lines.push(
       `  ${found.movers} elements moved, ${found.gsapMovers} of them GSAP's` +
-        `${found.movers > found.gsapMovers ? " (the rest is CSS, which the source audit cannot see)" : ""}`,
+        `${found.movers > found.gsapMovers ? " (the rest is CSS, Web Animations or other script, which the source audit cannot see)" : ""}`,
     );
     if (found.spread) lines.push(`  they started over a span of ${found.spread}ms`);
   }
@@ -838,9 +871,10 @@ export function report(result, options) {
     lines.push("", "Seams — a step far larger than the motion's own rhythm");
     for (const event of found.seams.slice(0, 6)) {
       const size = event.least === event.most ? `${event.most}px` : `${event.least}-${event.most}px`;
+      const where = event.box ? ` at ${event.box.map(Math.round).join(",")}` : "";
       lines.push(
         `  ${event.at}ms  ${event.count === 1 ? event.example : `${event.count} elements (${event.example})`}` +
-          ` jumps ${size}`,
+          `${where} jumps ${size}`,
       );
     }
   }
@@ -855,6 +889,11 @@ export function report(result, options) {
   if (result.shot) lines.push("", `Frame: ${result.shot}`);
 
   lines.push("", "These are measurements. Composition, rhythm and taste are yours to judge.");
+  /** Last, so a reader who sees only the end still sees it. */
+  if (result.notDone?.length) {
+    lines.push("", "Not done — the run exits non-zero");
+    for (const line of result.notDone) lines.push(`  ${line}`);
+  }
   return lines.join("\n");
 }
 
@@ -877,9 +916,10 @@ async function main(argv) {
     const result = await watch(options);
     console.log(
       options.json
-        ? JSON.stringify({ url: result.url, ...conclude(result) }, null, 2)
+        ? JSON.stringify({ url: result.url, ...conclude(result), notDone: result.notDone }, null, 2)
         : report(result, options),
     );
+    process.exitCode = exitFor(result.notDone);
   } catch (error) {
     console.error(error.message);
     process.exit(1);