@mehshekari/gsap-motion 4.2.1 → 4.4.2

package/skill/scripts/lib/rules.mjs

@@ -49,6 +49,8 @@ import {
 const HINT = {
   matchMediaNeverRuns:
     "A matchMedia callback runs only while at least one of its named conditions matches, and a visitor with no reduced-motion preference matches none of these — so the branch for them is dead code and nothing animates. Add `motion: \"(prefers-reduced-motion: no-preference)\"` beside it, or use two separate `add` calls.",
+  contextSafeMisuse:
+    "The callback of `gsap.matchMedia().add`, `gsap.context` and `useGSAP` receives `(context, contextSafe)`: take the second argument, as in `mm.add(query, (context, contextSafe) => …)`, and wrap the delayed callback in it. `context.add(fn)` runs `fn` straight away instead.",
   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:
@@ -59,6 +61,10 @@ const HINT = {
     "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.",
+  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:
+    "If anything has changed layout since the last frame, this read makes the browser compute it now, every frame. Measure once and again only on resize — a ScrollTrigger's `onRefresh`, or a ResizeObserver — and read the cached value here.",
   paintProperty:
     "Filters and shadows repaint the layer every frame, and the cost grows with the painted area. Animate `opacity` on a pre-blurred or pre-shadowed copy, or move a transform instead, and measure before defending anything else.",
   unownedLoop:
@@ -102,6 +108,7 @@ const HINT = {
 const MESSAGE = {
   easedLoop: "An infinite repeat with an ease other than `none`.",
   tweenPerFrame: "A tween is created here on every frame.",
+  layoutReadPerFrame: "Layout is read here on every frame.",
   unownedLoop: "An infinite repeat that nothing pauses.",
   ungatedHover: "A hover animation with no `(hover: hover)` gate.",
   delayChain: "Three or more tweens in this scope are sequenced by `delay`.",
@@ -171,10 +178,19 @@ function layoutHint(property, percent) {
   const swap = TRANSFORM_FOR[property];
   return swap
     ? `Use \`${swap}\` instead — a compositor-only property.` +
+        (property === "height" ? ` ${HEIGHT_CAVEAT}` : "") +
         (percent ? ` ${PERCENT_CAVEAT}` : "")
     : "Prefer transform and opacity; they never touch layout.";
 }
 
+/**
+ * A scale squashes what is inside. An accordion's text is the usual case, and
+ * a real project kept its `height` tween for exactly that reason, which the
+ * hint above alone would have argued against.
+ */
+const HEIGHT_CAVEAT =
+  "Unless what is inside must keep its shape — an accordion's text: then transition `grid-template-rows` from `0fr` to `1fr`, or use Flip.";
+
 /** Whether a transform's from-value, as written, leaves the element untransformed. */
 function identityTransform(property, value) {
   const v = value.trim().replace(/^["'`]|["'`]$/g, "");
@@ -587,6 +603,36 @@ const PAINT_PROPERTIES = new Set([
   "boxShadow",
 ]);
 
+/** Three's math types: what a render loop allocates when it should reuse. */
+const THREE_MATH = new Set([
+  "Vector2",
+  "Vector3",
+  "Vector4",
+  "Quaternion",
+  "Euler",
+  "Matrix3",
+  "Matrix4",
+  "Color",
+  "Box3",
+  "Sphere",
+  "Ray",
+  "Plane",
+  "Spherical",
+]);
+
+/** Reads that return layout, and so make the browser compute it if it is stale. */
+const LAYOUT_READ_METHODS = new Set(["getBoundingClientRect", "getClientRects"]);
+const LAYOUT_READ_PROPERTIES = new Set([
+  "offsetWidth",
+  "offsetHeight",
+  "offsetTop",
+  "offsetLeft",
+  "clientWidth",
+  "clientHeight",
+  "scrollWidth",
+  "scrollHeight",
+]);
+
 const HOVER_EVENTS = new Set([
   "pointerenter",
   "pointerover",
@@ -685,6 +731,45 @@ function stopped(ast, name) {
   );
 }
 
+/**
+ * Every `add` call on a `gsap.matchMedia()`: made on it directly, or on a name
+ * the file binds it to, at declaration or later.
+ */
+function matchMediaAdds(file) {
+  const media = new Set(
+    findAll(
+      file.ast,
+      (node) =>
+        (node.type === "VariableDeclarator" &&
+          node.id.type === "Identifier" &&
+          /**
+           * `let tl;` has no initializer, and `calleeName` does not accept
+           * null. Every fixture initialised its declarations, so 133 passing
+           * tests missed this; the first real project threw on it and took
+           * the whole audit down with it.
+           */
+          Boolean(node.init) &&
+          calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
+        (node.type === "AssignmentExpression" &&
+          node.left.type === "Identifier" &&
+          calleeName(unwrap(node.right)) === "gsap.matchMedia"),
+    ).map((node) => (node.type === "VariableDeclarator" ? node.id.name : node.left.name)),
+  );
+
+  const onMatchMedia = (call) => {
+    const callee = unwrap(call.callee);
+    if (callee?.type !== "MemberExpression") return false;
+    const object = unwrap(callee.object);
+    if (object?.type === "Identifier") return media.has(object.name);
+    return calleeName(object) === "gsap.matchMedia";
+  };
+
+  return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node));
+}
+
+/** Nodes a value passes through unchanged on its way to whatever uses it. */
+const TRANSPARENT = new Set(["ParenthesizedExpression", "ChainExpression", "TSAsExpression", "TSNonNullExpression"]);
+
 export const RULES = [
   // --- Lifecycle ------------------------------------------------------------
   {
@@ -968,7 +1053,7 @@ export const RULES = [
       return findAll(file.ast, animates).flatMap(
         (call) => {
           const seen = new Set();
-          return varsObjects(call, tweenMethod(call))
+          return varsObjects(call, tweenMethod(call), file.ast)
             .flatMap((vars) => vars.properties)
             .filter((property) => {
               const key = keyName(property);
@@ -1046,7 +1131,7 @@ export const RULES = [
     test(file) {
       return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap(
         (call) => {
-          const vars = ownVars(call, tweenMethod(call));
+          const vars = ownVars(call, tweenMethod(call), file.ast);
           if (!vars) return [];
           const repeat = propertyOf(vars, "repeat");
           if (!repeat || numberValue(repeat.value) !== -1) return [];
@@ -1360,6 +1445,91 @@ export const RULES = [
       return findings;
     },
   },
+  {
+    id: "allocation-per-frame",
+    level: "warn",
+    description:
+      "A Three.js vector, colour, matrix or quaternion built every frame — in `useFrame`, the ticker, `onUpdate` or a `requestAnimationFrame` loop",
+    /**
+     * Only Three's math types, by name. Any `new` in a frame allocates, but a
+     * `Set` or a `Map` there is usually deliberate and rarely hot; these are
+     * the objects a render loop builds by the thousand, once per object per
+     * frame, and each has a `set` or `copy` that makes the allocation pointless.
+     */
+    test(file) {
+      const scopes = perFrameScopes(file.ast);
+      if (scopes.length === 0) return [];
+
+      const built = findAll(file.ast, (node) => {
+        if (node.type !== "NewExpression") return false;
+        const name = dottedName(unwrap(node.callee))?.split(".").at(-1);
+        return THREE_MATH.has(name);
+      });
+
+      const reported = new Set();
+      return built.flatMap((node) => {
+        if (reported.has(node.start) || !scopes.some((scope) => contains(scope, node))) {
+          return [];
+        }
+        reported.add(node.start);
+        const name = dottedName(unwrap(node.callee)).split(".").at(-1);
+        return [
+          {
+            index: node.start,
+            message: `A \`${name}\` is allocated here on every frame.`,
+            hint: HINT.allocationPerFrame,
+          },
+        ];
+      });
+    },
+  },
+  {
+    id: "layout-read-per-frame",
+    level: "info",
+    description:
+      "A layout read — `getBoundingClientRect`, `offsetWidth`, `getComputedStyle` — in a callback that runs every frame",
+    /**
+     * Info, because a read is only expensive when something has invalidated
+     * layout since the last frame, and that depends on what else runs — a
+     * transform does not, a `width` tween does. What is certain is that the
+     * value is re-measured every frame when it usually changes only on resize.
+     */
+    test(file) {
+      const scopes = perFrameScopes(file.ast);
+      if (scopes.length === 0) return [];
+
+      const reads = findAll(file.ast, (node) => {
+        if (node.type === "CallExpression") {
+          const name = calleeName(node);
+          return (
+            name === "getComputedStyle" ||
+            name === "window.getComputedStyle" ||
+            LAYOUT_READ_METHODS.has(methodName(node))
+          );
+        }
+        return (
+          node.type === "MemberExpression" &&
+          !node.computed &&
+          LAYOUT_READ_PROPERTIES.has(node.property.name)
+        );
+      });
+
+      const reported = new Set();
+      return reads.flatMap((node) => {
+        if (reported.has(node.start) || !scopes.some((scope) => contains(scope, node))) {
+          return [];
+        }
+        reported.add(node.start);
+        return [
+          {
+            index: node.start,
+            message: MESSAGE.layoutReadPerFrame,
+            hint: HINT.layoutReadPerFrame,
+          },
+        ];
+      });
+    },
+  },
   {
     id: "paint-property",
     level: "warn",
@@ -1374,7 +1544,7 @@ export const RULES = [
 
       return findAll(file.ast, animates).flatMap((call) => {
         const seen = new Set();
-        return varsObjects(call, tweenMethod(call))
+        return varsObjects(call, tweenMethod(call), file.ast)
           .flatMap((vars) => vars.properties)
           .filter((property) => {
             const key = keyName(property);
@@ -1421,7 +1591,7 @@ export const RULES = [
 
       return findAll(file.ast, (node) => tweenMethod(node) !== null).flatMap((call) => {
         if (inside(call)) return [];
-        const vars = ownVars(call, tweenMethod(call));
+        const vars = ownVars(call, tweenMethod(call), file.ast);
         if (!vars) return [];
         const repeat = propertyOf(vars, "repeat");
         if (!repeat || numberValue(repeat.value) !== -1) return [];
@@ -1477,7 +1647,7 @@ export const RULES = [
 
       for (const call of findAll(file.ast, (node) => tweenMethod(node) !== null)) {
         if (chainStart(call) !== call) continue;
-        const vars = ownVars(call, tweenMethod(call));
+        const vars = ownVars(call, tweenMethod(call), file.ast);
         const delay = vars && propertyOf(vars, "delay");
         if (!delay || !(numberValue(delay.value) > 0)) continue;
         const scope = scopeOf(file.ast, call) ?? file.ast;
@@ -1628,35 +1798,6 @@ export const RULES = [
       const REDUCE = /prefers-reduced-motion\s*:\s*reduce/i;
       const PREFERENCE = /prefers-reduced-motion/i;
 
-      /** Names bound to `gsap.matchMedia()` in this file, at declaration or later. */
-      const media = new Set(
-        findAll(
-          file.ast,
-          (node) =>
-            (node.type === "VariableDeclarator" &&
-              node.id.type === "Identifier" &&
-              /**
-               * `let tl;` has no initializer, and `calleeName` does not accept
-               * null. Every fixture initialised its declarations, so 133 passing
-               * tests missed this; the first real project threw on it and took
-               * the whole audit down with it.
-               */
-              Boolean(node.init) &&
-              calleeName(unwrap(node.init)) === "gsap.matchMedia") ||
-            (node.type === "AssignmentExpression" &&
-              node.left.type === "Identifier" &&
-              calleeName(unwrap(node.right)) === "gsap.matchMedia"),
-        ).map((node) => (node.type === "VariableDeclarator" ? node.id.name : node.left.name)),
-      );
-
-      const onMatchMedia = (call) => {
-        const callee = unwrap(call.callee);
-        if (callee?.type !== "MemberExpression") return false;
-        const object = unwrap(callee.object);
-        if (object?.type === "Identifier") return media.has(object.name);
-        return calleeName(object) === "gsap.matchMedia";
-      };
-
       /** The conditions as written: in the call, or in a `const` the file declares once. */
       const conditionsOf = (argument) => {
         const target = unwrap(argument);
@@ -1714,7 +1855,7 @@ export const RULES = [
         }).length > 0;
       };
 
-      return findAll(file.ast, (node) => methodName(node) === "add" && onMatchMedia(node))
+      return matchMediaAdds(file)
         .filter((call) => {
           if (!everyReduces(conditionsOf(call.arguments[0]))) return false;
           const callback = resolveFunction(file.ast, call.arguments[1]);
@@ -1728,6 +1869,93 @@ export const RULES = [
         }));
     },
   },
+  {
+    id: "context-safe-misuse",
+    level: "warn",
+    description:
+      "A callback made context-safe with the context itself, which runs it at once instead",
+    /**
+     * The callback of `gsap.matchMedia().add`, `gsap.context` or `useGSAP`
+     * receives `(context, contextSafe)`. Two ways of getting that wrong both
+     * ship a blank page:
+     *
+     * - `({ contextSafe }) => …` reads `contextSafe` from the context, which has
+     *   none. It is `undefined`, and the first call throws.
+     * - `context.add(fn)` handed on as a callback. `add` with a function runs it
+     *   at once, passing the context, and returns what it returned, so the
+     *   caller receives no callback and `fn` ran with the wrong argument.
+     *
+     * Found in the 4.3 creative A/B: three of 27 runs, in both arms, crashed on
+     * load this way, every one inside a matchMedia. `add` as a statement runs a
+     * block inside the context and is correct; a named `add("onClick", fn)` and
+     * `add(null, fn)` return a wrapper and are correct too. Only an `add` whose
+     * result is used, given a function, is reported.
+     */
+    test(file) {
+      const callbacks = new Set(
+        [
+          ...matchMediaAdds(file).map((call) => call.arguments[1]),
+          ...findAll(
+            file.ast,
+            (node) =>
+              node.type === "CallExpression" &&
+              ["gsap.context", "useGSAP"].includes(calleeName(node)),
+          ).map((call) => call.arguments[0]),
+        ]
+          .map((argument) => resolveFunction(file.ast, argument))
+          .filter(Boolean),
+      );
+
+      /** Is the call's result handed on, rather than thrown away as a statement? */
+      const used = (call) => {
+        let child = call;
+        let parent = parentOf(file.ast, call);
+        while (parent && TRANSPARENT.has(parent.type)) {
+          child = parent;
+          parent = parentOf(file.ast, parent);
+        }
+        if (!parent || parent.type === "ExpressionStatement" || parent.type === "SequenceExpression") {
+          return false;
+        }
+        return !(parent.type === "CallExpression" && parent.callee === child);
+      };
+
+      const findings = [];
+      for (const fn of callbacks) {
+        const [param] = fn.params;
+        if (param?.type === "ObjectPattern") {
+          const property = param.properties.find((p) => keyName(p) === "contextSafe");
+          if (property) {
+            findings.push({
+              index: property.start,
+              message:
+                "`contextSafe` is read from the callback's first argument, the context, which has none: it is undefined, and the first call throws.",
+              hint: HINT.contextSafeMisuse,
+            });
+          }
+          continue;
+        }
+        if (param?.type !== "Identifier") continue;
+        const adds = findAll(fn.body, (node) => {
+          if (methodName(node) !== "add") return false;
+          const receiver = unwrap(unwrap(node.callee).object);
+          return receiver?.type === "Identifier" && receiver.name === param.name;
+        });
+        for (const call of adds) {
+          const target = unwrap(call.arguments[0]);
+          if (!target || target.type === "Literal" || target.type === "TemplateLiteral") continue;
+          if (!isFunction(target) && target.type !== "Identifier") continue;
+          if (!used(call)) continue;
+          findings.push({
+            index: call.start,
+            message: `\`${param.name}.add(fn)\` runs fn at once and returns its result, so what is handed on here is not a callback.`,
+            hint: HINT.contextSafeMisuse,
+          });
+        }
+      }
+      return findings;
+    },
+  },
   {
     id: "stacked-from",
     level: "warn",

package/skill/scripts/review-motion.mjs

@@ -19,13 +19,15 @@
  * for a reviewer looking at the filmstrip; this reports evidence, with the time
  * and the element, and leaves the verdict to them.
  *
- * Node.js 22+, no dependencies, whatever Chrome the machine already has.
+ * Node.js 22+, no dependencies, whatever Chrome the machine already has. With
+ * `--probe install` and `--probe read` it drives no browser at all, and prints
+ * the two functions to run in one you already have.
  */
-import { mkdirSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { connect, findChrome } from "./capture-motion.mjs";
+import { connect, findChrome, gpuNote, prepareOut } from "./capture-motion.mjs";
 
 // --- What a recording means ---------------------------------------------------
 
@@ -229,6 +231,33 @@ export function seamEvents(torn, { window = 50 } = {}) {
   }));
 }
 
+/**
+ * The long frames, with the sampler's own time taken out of each.
+ *
+ * Reading every moving element's box and style is work inside every frame
+ * this records, so a long frame is partly the recorder's. `cost` is that work,
+ * per frame, as `[at, ms]`; what falls inside a long frame is subtracted, and
+ * the rest is the page's own. Null when the browser has no Long Animation
+ * Frames API, which is not the same as no long frames.
+ */
+export function longFrameSummary(longFrames, cost = []) {
+  if (!longFrames) return null;
+  const own = (frame) =>
+    cost
+      .filter(([at]) => at >= frame.at && at <= frame.at + frame.duration)
+      .reduce((sum, [, ms]) => sum + ms, 0);
+  const frames = longFrames.map((frame) => ({
+    ...frame,
+    page: Math.max(0, Math.round(frame.duration - own(frame))),
+  }));
+  const longest = frames.reduce((a, b) => (b.duration > (a?.duration ?? -1) ? b : a), null);
+  return {
+    count: frames.length,
+    longest,
+    blocking: frames.reduce((sum, frame) => sum + frame.blocking, 0),
+  };
+}
+
 /** Each element and the moment it first moved, in that order. */
 export function starts(log) {
   const first = new Map();
@@ -259,6 +288,8 @@ export function parseOptions(argv) {
     out: null,
     json: false,
     chrome: null,
+    headed: false,
+    probe: null,
     errors: [],
   };
 
@@ -300,6 +331,9 @@ export function parseOptions(argv) {
       case "--chrome":
         options.chrome = next() ?? null;
         break;
+      case "--headed":
+        options.headed = true;
+        break;
       case "--mobile":
         options.mobile = true;
         break;
@@ -312,12 +346,24 @@ export function parseOptions(argv) {
       case "--json":
         options.json = true;
         break;
+      case "--probe": {
+        const kind = next();
+        if (kind !== "install" && kind !== "read") {
+          options.errors.push("--probe takes install or read.");
+        } else {
+          options.probe = kind;
+        }
+        break;
+      }
       default:
         options.errors.push(`Unknown option: ${argument}`);
     }
   }
 
-  if (options.url === null) options.errors.push("No URL. Pass the page to review.");
+  /** A probe is printed, not run, so it needs no page. */
+  if (options.url === null && options.probe === null) {
+    options.errors.push("No URL. Pass the page to review.");
+  }
   return options;
 }
 
@@ -366,9 +412,46 @@ const RECORDER = `(() => {
     return id;
   };
 
+  /**
+   * Long frames and layout shifts, where the browser reports them. The sampler
+   * below is itself work inside every frame, so its own time is kept too, and a
+   * long frame is reported with that time taken out. A read never shifts
+   * layout, so the shifts are the page's alone.
+   */
+  const supported = (type) =>
+    typeof PerformanceObserver !== "undefined" &&
+    (PerformanceObserver.supportedEntryTypes || []).includes(type);
+  const longFrames = supported("long-animation-frame") ? [] : null;
+  const shift = supported("layout-shift") ? { total: 0, count: 0, largest: null } : null;
+  const cost = [];
+  if (longFrames) {
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        longFrames.push({
+          at: Math.round(entry.startTime - started),
+          duration: Math.round(entry.duration),
+          blocking: Math.round(entry.blockingDuration || 0),
+        });
+      }
+    }).observe({ type: "long-animation-frame" });
+  }
+  if (shift) {
+    new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.hadRecentInput) continue;
+        shift.total += entry.value;
+        shift.count += 1;
+        if (!shift.largest || entry.value > shift.largest.value) {
+          shift.largest = { at: Math.round(entry.startTime - started), value: entry.value };
+        }
+      }
+    }).observe({ type: "layout-shift" });
+  }
+
   const tick =() => {
+    const began = performance.now();
     frames += 1;
-    const at = Math.round(performance.now() - started);
+    const at = Math.round(began - started);
     const now = new Map();
     const moved = [];
     /**
@@ -428,6 +511,7 @@ const RECORDER = `(() => {
 
     previous = now;
     if (moved.length) log.push({ at, moved, scrolled });
+    cost.push([at, Math.round((performance.now() - began) * 10) / 10]);
     requestAnimationFrame(tick);
   };
   requestAnimationFrame(tick);
@@ -471,6 +555,10 @@ const RECORDER = `(() => {
     viewport: { width: innerWidth, height: innerHeight },
     text: textLines(),
     log,
+    longFrames,
+    shift,
+    cost,
+    canvases: document.querySelectorAll("canvas").length,
   });
   return true;
 })()`;
@@ -485,7 +573,7 @@ async function watch(options) {
     throw new Error("No Chrome found. Install Chrome, or pass --chrome <path>, or set CHROME_PATH.");
   }
 
-  const browser = connect(executable);
+  const browser = connect(executable, { headless: !options.headed });
   const notes = [];
 
   try {
@@ -557,9 +645,9 @@ async function watch(options) {
 
     let shot = null;
     if (options.out) {
-      mkdirSync(resolve(options.out), { recursive: true });
+      const out = prepareOut(options.out);
       const png = await call("Page.captureScreenshot", { format: "png" });
-      shot = join(resolve(options.out), "review.png");
+      shot = join(out, "review.png");
       writeFileSync(shot, Buffer.from(png.data, "base64"));
     }
 
@@ -629,7 +717,48 @@ export function conclude(result) {
     overText,
     began: began.slice(0, 8),
     spread: began.length > 1 ? began.at(-1).at - began[0].at : 0,
+    /** Both absent from a recording made before they were measured: unknown, not zero. */
+    longFrames: longFrameSummary(recorded.longFrames, recorded.cost),
+    canvases: recorded.canvases ?? null,
+    shift: recorded.shift
+      ? { ...recorded.shift, total: Math.round(recorded.shift.total * 1000) / 1000 }
+      : null,
+  };
+}
+
+// --- In a browser this does not drive -----------------------------------------
+
+/**
+ * The recorder and its conclusions, as functions for a browser something else
+ * already holds — a DevTools MCP server's `evaluate_script`, where a project
+ * allows no second Chrome.
+ *
+ * `install` records from the moment it runs, not from navigation, so first
+ * motion is measured from there. `read` concludes in the page with the same
+ * functions this file uses, and returns only the findings: the frame log never
+ * crosses the wire. Emulation is the driving tool's own to set.
+ */
+export function probe(kind) {
+  if (kind === "install") return `() => ${RECORDER}`;
+  const helpers = {
+    overlap,
+    coverage,
+    seams,
+    motionOverText,
+    afterScroll,
+    seamEvents,
+    starts,
+    firstMotion,
+    longFrameSummary,
+    conclude,
   };
+  return `() => {
+  if (!window.__gsapMotionReview) return null;
+${Object.entries(helpers)
+  .map(([name, fn]) => `  const ${name} = ${fn};`)
+  .join("\n")}
+  return conclude({ recorded: window.__gsapMotionReview() });
+}`;
 }
 
 // --- Report --------------------------------------------------------------------
@@ -643,9 +772,12 @@ export function report(result, options) {
     options.dark && "dark",
     options.mobile && "mobile 390x844",
     options.cpu > 1 && `CPU ÷${options.cpu}`,
+    options.headed && "headed, on the GPU",
   ].filter(Boolean);
   if (emulated.length) lines.push(`  as: ${emulated.join(", ")}`);
   for (const note of result.notes) lines.push(`  ${note}`);
+  const gpu = gpuNote(found.canvases, options);
+  if (gpu) lines.push(`  ${gpu}`);
 
   lines.push("", "What moved");
   if (found.firstMotion === null) {
@@ -680,6 +812,28 @@ export function report(result, options) {
    */
   lines.push("  layout work is not measured here — sampling forces it; use inspect for that");
 
+  const long = found.longFrames;
+  if (long === null) {
+    lines.push("  long frames: not measured — this browser has no Long Animation Frames API");
+  } else if (long.count === 0) {
+    lines.push("  no frame took longer than 50ms");
+  } else {
+    lines.push(
+      `  ${long.count} frame${long.count === 1 ? "" : "s"} over 50ms; the longest` +
+        ` ${long.longest.duration}ms at ${long.longest.at}ms, ${long.longest.page}ms of it` +
+        " the page's own rather than the sampler's",
+    );
+  }
+  const shift = found.shift;
+  if (shift === null) {
+    lines.push("  layout shift: not measured — this browser does not report it");
+  } else {
+    lines.push(
+      `  layout shift: ${shift.total} over ${shift.count} shift${shift.count === 1 ? "" : "s"}` +
+        `${shift.largest ? `, the largest ${Math.round(shift.largest.value * 1000) / 1000} at ${shift.largest.at}ms` : ""}`,
+    );
+  }
+
   if (found.seams.length) {
     lines.push("", "Seams — a step far larger than the motion's own rhythm");
     for (const event of found.seams.slice(0, 6)) {
@@ -714,6 +868,11 @@ async function main(argv) {
     process.exit(2);
   }
 
+  if (options.probe) {
+    console.log(probe(options.probe));
+    return;
+  }
+
   try {
     const result = await watch(options);
     console.log(