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

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

package/skill/scripts/audit-gsap.mjs

@@ -32,12 +32,12 @@
  *
  * Exit code is 1 when any error-level finding is reported, 0 otherwise.
  */
-import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { dirname, 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,14 @@ for (const path of paths) {
 
 const findings = [];
 const sources = [];
+/** Every file read, GSAP or not: the import graph needs callers that never animate. */
+const loaded = [];
+/**
+ * A file named on the command line that the audit cannot read — a stylesheet,
+ * say. It used to be skipped in silence and the run printed "clean", which
+ * 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,8 +86,13 @@ 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);
+    loaded.push(source);
     if (!mentionsGsap(source)) continue;
 
     if (source.parseError) {
@@ -100,6 +113,22 @@ for (const path of paths) {
  */
 const registered = new Set(sources.flatMap((source) => [...pluginRegistrations(source)]));
 
+/**
+ * Who imports each file, among everything read — a caller need not use GSAP
+ * itself. Relative imports only: an alias such as `@/…` is not resolved, and a
+ * file whose importers are unknown is judged on its own, as before.
+ */
+const byPath = new Map(loaded.map((source) => [resolve(source.path), source]));
+const EXTENSIONS = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", "/index.ts", "/index.tsx", "/index.js"];
+for (const source of loaded) source.importers = [];
+for (const source of loaded) {
+  for (const [, specifier] of source.code.matchAll(/\bimport\s+(?!type\b)[^;]*?\bfrom\s*["'](\.{1,2}\/[^"']+)["']/g)) {
+    const base = resolve(dirname(source.path), specifier);
+    const target = EXTENSIONS.map((ext) => byPath.get(base + ext)).find(Boolean);
+    if (target && target !== source) target.importers.push(source);
+  }
+}
+
 for (const source of sources) {
   source.registeredElsewhere = registered;
 
@@ -124,8 +153,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 +192,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,106 @@ 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));
+  /** Where the other matches a pointer could reach are, so the reader can narrow the selector. */
+  const others = all
+    .filter((other, i) => i !== index && shown(other))
+    .slice(0, 4)
+    .map((other) => {
+      const b = other.getBoundingClientRect();
+      return [Math.round(b.x + b.width / 2), Math.round(b.y + b.height / 2)];
+    });
+  return {
+    matches: all.length,
+    index,
+    others,
+    scrolled: !inView,
+    x: clamp(box.x + box.width / 2, innerWidth),
+    y: clamp(box.y + box.height / 2, innerHeight),
+    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 +589,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 +601,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 +643,14 @@ async function capture(options) {
             });
           }
         }
+        const which = box.matches > 1 ? ` (match ${box.index + 1} of ${box.matches})` : "";
+        const elsewhere = box.others?.length
+          ? `; other matches a pointer could reach at ${box.others.map((p) => p.join(",")).join(" · ")} — narrow the selector to pick one`
+          : "";
         notes.push(
-          `${step.type}: ${step.value} 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" : "") +
+            elsewhere,
         );
         await wait(120);
       }
@@ -587,6 +686,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 +711,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 +731,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 +782,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 +810,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();
@@ -581,10 +602,56 @@ export function gsapContexts(root) {
     functions.set(name, node.type === "FunctionDeclaration" ? node : unwrap(node.init));
   }
 
+  /**
+   * Whether a function nested in a context body runs while the body runs, and
+   * so inside the context. GSAP sets the context only for the duration of the
+   * body (Context.add, gsap-core 3.15): a function the body hands to a listener,
+   * a timer, a promise or a ref runs later, outside it, and nothing it creates
+   * is reverted. A real project built a tween in `pulse.current = () => …`
+   * inside useGSAP and called it from pointermove; the audit read it as inside.
+   *
+   * In place: called right there, an array method's callback, GSAP's own
+   * callbacks (`on…` keys, `.add`, `.call`, which GSAP runs in the context),
+   * the cleanup the body returns, or a named function only ever called.
+   */
+  const ITERATORS = new Set(["forEach", "map", "filter", "flatMap", "reduce", "reduceRight", "some", "every", "find", "findIndex", "sort"]);
+  const runsInPlace = (fn) => {
+    const parent = parentOf(root, fn);
+    if (!parent) return false;
+    if (parent.type === "CallExpression") {
+      if (unwrap(parent.callee) === fn) return true;
+      const name = methodName(parent) ?? bareName(parent);
+      return ITERATORS.has(name) || name === "add" || name === "call" || isHook(parent) || safe.has(name) || calleeName(parent) === "gsap.context";
+    }
+    if (parent.type === "Property") return /^on[A-Z]/.test(keyName(parent) ?? "");
+    if (parent.type === "ReturnStatement" || (parent.type === "ArrowFunctionExpression" && parent.body === fn)) return true;
+    const bound =
+      parent.type === "VariableDeclarator" && parent.id.type === "Identifier" && unwrap(parent.init) === fn
+        ? parent.id.name
+        : fn.type === "FunctionDeclaration"
+          ? fn.id?.name
+          : null;
+    if (!bound) return false;
+    const uses = findAll(root, (n) => n.type === "Identifier" && n.name === bound && isReference(root, n));
+    return uses.every((id) => {
+      const call = parentOf(root, id);
+      return call?.type === "CallExpression" && call.callee === id;
+    });
+  };
+  /** Inside `scope`, with no function between that runs later. */
+  const runsWithin = (scope, node) => {
+    if (!contains(scope, node)) return false;
+    for (const ancestor of ancestorsOf(root, node)) {
+      if (ancestor === scope) return true;
+      if (isFunction(ancestor) && !runsInPlace(ancestor)) return false;
+    }
+    return false;
+  };
+
   const contained = new Set();
   const inside = (node) =>
-    scopes.some((argument) => contains(argument, node)) ||
-    [...contained].some((fn) => contains(fn, node));
+    scopes.some((argument) => runsWithin(argument, node)) ||
+    [...contained].some((fn) => runsWithin(fn, node));
   const identifiers = findAll(root, (node) => node.type === "Identifier");
 
   for (let changed = true; changed; ) {

package/skill/scripts/lib/rules.mjs

@@ -54,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 may run it twice in development. Move it into the useGSAP body, or wrap the handler in contextSafe. A helper counts as inside only when every use of it is a call from inside a context. Note that contextSafe keeps every tween it creates until the context reverts: a handler that runs often should replay a timeline built once, or call a quickTo.",
   unmanagedInstance:
     "Inside a context these register themselves and are reverted with it. Out here nothing is watching: move it into the useGSAP body, or keep the instance and revert/kill it from the cleanup.",
   unrevertedContext:
     "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"`.',
@@ -248,7 +250,32 @@ function listenerMethod(node) {
  * `followNames`, a handler passed by name is followed to its declaration when
  * the file declares exactly one function of that name.
  */
-function handlersFor(ast, events, { followNames = true, perFrame = false } = {}) {
+function handlersFor(ast, events, options = {}) {
+  const direct = directHandlers(ast, events, options);
+  /**
+   * One hop through a ref: a handler that calls `pulse.current()`, where the
+   * file assigns `pulse.current = () => { … }`. A real project kept a tween on
+   * a ref and called it from a pointermove listener, and the rule read the
+   * listener as clean.
+   */
+  const viaRef = direct.flatMap((h) =>
+    findAll(h.node, (n) => n.type === "CallExpression" && unwrap(n.callee)?.type === "MemberExpression")
+      .map((call) => dottedName(unwrap(call.callee)))
+      .filter((name) => name?.endsWith(".current"))
+      .flatMap((name) =>
+        findAll(
+          ast,
+          (n) =>
+            n.type === "AssignmentExpression" &&
+            dottedName(unwrap(n.left)) === name &&
+            isFunction(unwrap(n.right)),
+        ).map((n) => ({ name: h.name, node: unwrap(n.right) })),
+      ),
+  );
+  return [...direct, ...viaRef];
+}
+
+function directHandlers(ast, events, { followNames = true, perFrame = false } = {}) {
   const handler = (expression) => {
     const node = unwrap(expression);
     if (node?.type === "CallExpression") return node;
@@ -310,6 +337,113 @@ 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;
+
+/**
+ * Whether a file holds a reduced-motion branch: the query written in code, or
+ * asked by name — `useReducedMotion()`, `prefersReducedMotion()`,
+ * `isReduced()`, `matchMedia(REDUCED_MOTION_QUERY)` — since it is often written
+ * once, in a shared module. "Reduced", not "reduce": an array's `.reduce()` is
+ * not one. A comment that mentions it is not a branch.
+ */
+function hasReducedBranch(file) {
+  if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) return true;
+  return (
+    findAll(file.ast, (node) => {
+      if (node.type !== "CallExpression") return false;
+      const name = calleeName(node)?.split(".").at(-1) ?? "";
+      if (/reduced/i.test(name)) return true;
+      return (
+        name === "matchMedia" &&
+        node.arguments.some((arg) => arg.type === "Identifier" && /reduced/i.test(arg.name))
+      );
+    }).length > 0
+  );
+}
+
 /** The calls that add a child to a timeline. */
 const CHILDREN = new Set(["to", "from", "fromTo", "add"]);
 
@@ -341,6 +475,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 +1036,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",
@@ -1682,7 +1888,14 @@ export const RULES = [
      */
     test(file) {
       if (!file.usesGsap) return [];
-      if (findAll(file.ast, (node) => spells(node, "prefers-reduced-motion")).length) {
+      if (hasReducedBranch(file)) return [];
+      /**
+       * Every caller decides instead: each file that imports this one holds a
+       * branch. Three projects reported a helper flagged while its only caller
+       * returned early under reduced motion. Only the full audit knows the
+       * importers; the editor and the write hook see one file, and report it.
+       */
+      if (file.importers?.length && file.importers.every((importer) => !importer.parseError && hasReducedBranch(importer))) {
         return [];
       }
 

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