@mehshekari/gsap-motion 4.3.0 → 4.5.0

package/skill/reference/routing.md

@@ -54,6 +54,15 @@ two is not a coin toss.
 | "it feels cheap" | linear easing, or one uniform duration | `tune` |
 | "it feels slow" | usually too sequential, not too long: try overlap | `tune` |
 
+### "Match this site, one to one"
+
+The reference is the precedent, and its motion is the spec. Measure its curves
+and durations from it — `inspect` on its URL with a dense `--at`, or a
+recording frame by frame — and copy them exactly. "Motion carries meaning or it
+goes" judged the reference when it was designed; applied to the copy, it
+simplifies what was asked for verbatim. Personalising is a second pass, after
+the copy matches.
+
 ### "Something crazy"
 
 A fade-and-scale is a failure of nerve; twelve techniques at once is a failure
@@ -87,7 +96,8 @@ single hover takes [interaction](interaction.md) and nothing else from its row.
 | Request | Add |
 |---|---|
 | SVG draw / morph / path | [svg](svg.md), [timeline](timeline.md) |
-| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md) |
+| Scroll sequence, pin, scrub | [scrolltrigger](scrolltrigger.md), [timeline](timeline.md), [performance](performance.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
+| Smooth scroll, Lenis | [scrolltrigger](scrolltrigger.md#lenis), [devices](devices.md) |
 | Horizontal scroll | [scrolltrigger](scrolltrigger.md), [scroll-storytelling](../preset/scroll-storytelling.md) |
 | Text reveal, kinetic type | [text](text.md), [timeline](timeline.md) |
 | Magnetic, cursor, hover | [interaction](interaction.md), [performance](performance.md) |

package/skill/reference/scrolltrigger.md

@@ -97,6 +97,39 @@ Things that bite:
 - `position: sticky` is cheaper and needs no plugin. Use it when you only need
   the element to stay put, not to drive a timeline.
 
+### `pinType`
+
+How the pin holds the element. On the window it defaults to `"fixed"`: at each
+enter and leave, ScrollTrigger swaps the element's whole state — `position`,
+`top`, `left`, `width`, `height`, margins, padding — and the browser lays it out
+again in that frame. `"transform"` swaps nothing, and writes a translate every
+frame while the pin is active (verified against gsap 3.15).
+
+`"fixed"` is the default because native scrolling runs off the main thread, and
+a translate written once per frame would trail it. Under Lenis that reason is
+gone for the wheel — the scroll moves in the same frame as the pin — and the
+state swap at every section edge is what remains. On one landing page it was
+measured at a CLS of 4 to 7.5 and frames of 50 to 117ms per edge, and
+`"transform"` removed both. Touch is still native under Lenis, so keep
+`"fixed"` there:
+
+```ts
+// Inside the component's context, so it reverts with it. Both conditions are
+// named: a matchMedia callback runs only while one of them matches.
+gsap.matchMedia().add({ smoothed: "(pointer: fine)", touch: "(pointer: coarse)" }, (context) => {
+  const { smoothed } = context.conditions;
+  ScrollTrigger.create({ trigger: section, pin: true, pinType: smoothed ? "transform" : "fixed" });
+});
+```
+
+A trackpad sends wheel events, so a laptop is smoothed too. A laptop with a
+touch screen still reads `(pointer: fine)`, and scrolled by finger its pin
+trails the native scroll. If that audience matters, branch on
+`(any-pointer: coarse)` instead: every device with touch gets `"fixed"`, and
+with it the cost at each edge.
+
+Without smooth scrolling, leave the default.
+
 ## Horizontal scroll
 
 A vertical scroll driving a horizontal translation. `xPercent` avoids measuring:
@@ -162,6 +195,49 @@ interferes with `position: fixed`, anchor links, and native scroll on some
 touch devices. Do not add it to make a reveal smoother — fix the reveal. Add it
 only when the whole page is designed around smoothed scrolling.
 
+## Lenis
+
+Lenis smooths wheel input and writes the result to the real scroll position, so
+ScrollTrigger needs no `scrollerProxy`. Pins need one decision, in
+[`pinType`](#pintype). What it needs above all is **one clock**, shared with
+GSAP:
+
+```ts
+const lenis = new Lenis();                         // autoRaf stays false, its default
+lenis.on("scroll", ScrollTrigger.update);          // triggers read this frame's scroll
+const raf = (time: number) => lenis.raf(time * 1000); // the ticker's time is seconds
+gsap.ticker.add(raf, false, true);                 // prioritized: before GSAP renders
+gsap.ticker.lagSmoothing(0);
+
+// Teardown. A context owns neither of these.
+gsap.ticker.remove(raf);
+lenis.destroy();
+```
+
+- **Prioritized, because GSAP renders in its own first ticker listener.** Added
+  after it, Lenis moves the scroll once GSAP has drawn the frame: a numeric
+  `scrub` — a tween — and anything tweened from the scroll position render one
+  frame late. `scrub: true` sets progress directly and is not affected.
+- **Never `autoRaf: true` as well.** Lenis steps by the difference between
+  consecutive `raf` calls, and the two loops pass clocks with different origins,
+  so the step swings and the scroll stutters.
+- **`lagSmoothing(0)`**: after a frame longer than 500ms, GSAP otherwise
+  advances its clock by 33ms, and Lenis on that clock crawls back to the
+  scroll. It applies to every tween on the page, which then jump after a long
+  frame instead of slowing.
+- **Touch is native by default.** With `syncTouch` off, Lenis smooths nothing on
+  a touch screen and only runs its loop. Leave it off — it takes over the
+  platform's momentum, and is unstable on older iOS — and consider not creating
+  Lenis at all without a fine pointer; see [devices.md](devices.md).
+- **Reduced motion is handled.** By default Lenis tracks the input 1:1 and makes
+  programmatic scrolls instant, and keeps running. Do not destroy it for reduced
+  motion: the ScrollTrigger sync above depends on it.
+- In-page links need `anchors: true`; a nested scroll container needs
+  `data-lenis-prevent`. In React, `ReactLenis` from `lenis/react` takes the same
+  options: `autoRaf: false`, and the ticker wiring in an effect.
+
+Verified against `lenis@1.3` and `gsap@3.15`.
+
 ## React
 
 The lifecycle is the hard part. `useGSAP` reverts its context on unmount, which
@@ -189,3 +265,6 @@ images settle. `ScrollTrigger.refresh()` on mount is usually needed. See
 | Janky while scrolling | layout-triggering properties — see [performance](performance.md) |
 | Works, then breaks after navigation | ScrollTriggers not killed on unmount |
 | Wrong on mobile after address-bar hide | viewport resize — `invalidateOnRefresh` |
+| Smooth scroll stutters | Lenis on two loops — `autoRaf` and the ticker |
+| A numeric scrub trails the scroll by a frame | Lenis's `raf` added to the ticker without `prioritize` |
+| A layout shift and a long frame at each pinned section's edge | a `"fixed"` pin under Lenis — `pinType: "transform"` for the wheel |

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
@@ -151,6 +167,14 @@ if (asJson) {
     .join(", ");
 
   console.log(`\n${tally}`);
+  /** Said here because a report that never mentions it reads as "there is no way". */
+  console.log(
+    "A deliberate finding is waived with `<rule-id>-ok` and a reason, on its line or in the eight above.",
+  );
+}
+
+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
@@ -29,6 +32,12 @@
  *   --cpu 4               throttle the CPU by this factor
  *   --json                machine-readable, for scripts
  *   --chrome <path>       a browser to use, overriding the search
+ *   --seek <name>         call window.<name>(t) before each capture, and read
+ *                         --at as seconds of the timeline instead of the clock
+ *   --headed              a visible Chrome, on the machine's GPU: what a WebGL
+ *                         page needs for its frames and rate to mean anything
+ *   --probe timeline      print the timeline reader as a function, for a
+ *                         browser you already drive, and open none
  *
  * `--scroll`, `--hover` and `--click` run in the order they are written, before
  * the first capture. An animation that needs a pointer or a scroll position is
@@ -40,7 +49,7 @@
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // --- The browser -------------------------------------------------------------
@@ -85,11 +94,20 @@ export function connect(executable, { headless = true } = {}) {
   const chrome = spawn(
     executable,
     [
-      ...(headless ? ["--headless=new"] : []),
+      /** Headless runs without a GPU, for a steady result; headed gets the machine's own. */
+      ...(headless ? ["--headless=new", "--disable-gpu"] : []),
       "--remote-debugging-pipe",
+      /**
+       * A window nobody can see is a page Chrome stops animating: headed and
+       * moved off-screen, as a window behind an editor is, rAF went from 122 a
+       * second to none, and the run hung. With these it ran at 166. They are
+       * Puppeteer's defaults too.
+       */
+      "--disable-backgrounding-occluded-windows",
+      "--disable-renderer-backgrounding",
+      "--disable-background-timer-throttling",
       "--no-first-run",
       "--no-default-browser-check",
-      "--disable-gpu",
       "--disable-extensions",
       `--user-data-dir=${profile}`,
       "about:blank",
@@ -173,9 +191,14 @@ export function parseOptions(argv) {
     reduced: false,
     dark: false,
     mobile: false,
+    viewport: null,
     cpu: 1,
     json: false,
     chrome: null,
+    headed: false,
+    seek: null,
+    atGiven: false,
+    probe: null,
     errors: [],
   };
 
@@ -192,6 +215,7 @@ export function parseOptions(argv) {
           options.errors.push("--at takes milliseconds, such as --at 0,300,900");
         } else {
           options.at = times.sort((a, b) => a - b);
+          options.atGiven = true;
         }
         break;
       }
@@ -222,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");
@@ -234,6 +264,20 @@ export function parseOptions(argv) {
       case "--chrome":
         options.chrome = value() ?? null;
         break;
+      case "--headed":
+        options.headed = true;
+        break;
+      case "--seek": {
+        /** A name the page exports, never an expression: it is spliced into the page's code. */
+        const name = value() ?? "";
+        if (/^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(name)) options.seek = name;
+        else options.errors.push("--seek takes the name of a function on window, such as --seek __seek");
+        break;
+      }
+      case "--probe":
+        if (value() === "timeline") options.probe = "timeline";
+        else options.errors.push("--probe takes timeline");
+        break;
       default:
         if (argument.startsWith("--")) options.errors.push(`Unknown option: ${argument}`);
         else if (options.url === null) options.url = argument;
@@ -241,7 +285,19 @@ export function parseOptions(argv) {
     }
   }
 
-  if (options.url === null) options.errors.push("No URL. Pass the page to watch.");
+  /** 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 watch.");
+  }
+
+  /** Seeking makes `--at` timeline seconds, so the millisecond default would mean minutes. */
+  if (options.seek && !options.atGiven) {
+    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")) {
@@ -325,14 +381,145 @@ const COUNT_FRAMES = `(() => {
   return true;
 })()`;
 
-/** The live box of a selector, so a pointer lands on an element that is moving. */
-const boxOf = (selector) => `(() => {
-  const element = document.querySelector(${JSON.stringify(selector)});
-  if (!element) return null;
-  const box = element.getBoundingClientRect();
-  return { x: box.x + box.width / 2, y: box.y + box.height / 2, width: box.width, height: box.height };
+/**
+ * The timeline reader as a function, for a browser something else already
+ * holds — a DevTools MCP server's `evaluate_script`. Layouts and style
+ * recalculations come from the DevTools protocol, which a page cannot reach, so
+ * they are not part of it.
+ */
+export const probe = () => `() => ${READ_TIMELINE}`;
+
+/** Two rendered frames: a seek has been applied and painted once this resolves. */
+const SETTLED = "new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(() => done(true))))";
+
+/** A frame's file name: milliseconds of the clock, or seconds of the timeline when seeking. */
+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 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 -------------------------------------------------------
+
+/**
+ * What a report says when the page has a canvas and Chrome ran without its GPU:
+ * a WebGL scene was then drawn in software, and its frames, rate and long frames
+ * describe that, not the visitor's machine. Null when there is nothing to say.
+ */
+export function gpuNote(canvases, options) {
+  if (!canvases || options.headed) return null;
+  return (
+    `${canvases} canvas${canvases === 1 ? "" : "es"} on the page, and Chrome ran without its GPU:` +
+    " a WebGL scene's frames, rate and long frames are software rendering's. Measure it with --headed."
+  );
+}
+
+/**
+ * Creates `out` and returns its absolute path. When it is inside the project's
+ * `.gsap-motion/` — the default is — that folder gets a `.gitignore` of `*`,
+ * so the frames are never committed: a real project committed four of them in
+ * its first commit, and a knowledge-graph tool indexed them after that. The
+ * project's own `.gitignore` is left alone, and so is any other `--out`.
+ */
+export function prepareOut(out, cwd = process.cwd()) {
+  const path = resolve(cwd, out);
+  mkdirSync(path, { recursive: true });
+  const own = resolve(cwd, ".gsap-motion");
+  if (path === own || path.startsWith(own + sep)) {
+    const ignore = join(own, ".gitignore");
+    if (!existsSync(ignore)) writeFileSync(ignore, "# Written by gsap-motion: frames are not source.\n*\n");
+  }
+  return path;
+}
+
 // --- The run -----------------------------------------------------------------
 
 const wait = (ms) => new Promise((done) => setTimeout(done, ms));
@@ -356,7 +543,7 @@ async function capture(options) {
     );
   }
 
-  const browser = connect(executable);
+  const browser = connect(executable, { headless: !options.headed });
   const notes = [];
 
   try {
@@ -393,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 });
 
@@ -402,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;
         }
         /**
@@ -460,25 +634,36 @@ 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);
       }
     }
 
-    mkdirSync(resolve(options.out), { recursive: true });
+    const out = prepareOut(options.out);
 
     const frames = [];
     let elapsed = 0;
+    if (options.seek && !(await evaluate(`typeof window.${options.seek} === "function"`))) {
+      throw new Error(
+        `--seek: window.${options.seek} is not a function on this page. Export it in development; see refine.md.`,
+      );
+    }
     for (const at of options.at) {
-      if (at > elapsed) {
+      if (options.seek) {
+        /** Seek, then let two frames render, so what is captured is that time drawn. */
+        await evaluate(`window.${options.seek}(${at})`);
+        await evaluate(SETTLED);
+      } else if (at > elapsed) {
         await wait(at - elapsed);
         elapsed = at;
       }
       const shot = await call("Page.captureScreenshot", { format: "png" });
       const bytes = Buffer.from(shot.data, "base64");
-      const file = join(resolve(options.out), `frame-${String(at).padStart(5, "0")}ms.png`);
+      const file = join(out, frameName(at, options));
       writeFileSync(file, bytes);
       frames.push({ at, file, bytes: bytes.length });
     }
@@ -487,6 +672,8 @@ async function capture(options) {
     const drawn = await evaluate(
       "({ 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) => {
@@ -511,7 +698,7 @@ async function capture(options) {
       overMs: span,
     };
 
-    return { url: options.url, frames, timeline, measured, notes, chrome: executable };
+    return { url: options.url, frames, timeline, measured, notes, notDone, canvases, viewport, chrome: executable };
   } finally {
     await browser.close();
   }
@@ -527,13 +714,19 @@ export function report(result, options) {
     options.dark && "dark",
     options.mobile && "mobile 390x844",
     options.cpu > 1 && `CPU ÷${options.cpu}`,
+    options.headed && "headed, on the GPU",
+    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}`);
 
   lines.push("", `Frames (${result.frames.length}), in ${options.out}`);
   for (const frame of result.frames) {
-    lines.push(`  ${String(frame.at).padStart(5)}ms  ${frame.file}`);
+    const when = options.seek ? `${frame.at}s`.padStart(8) : `${String(frame.at).padStart(5)}ms`;
+    lines.push(`  ${when}  ${frame.file}`);
   }
 
   lines.push("", "Timeline, as the page is running it");
@@ -576,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");
 }
@@ -591,9 +789,15 @@ async function main(argv) {
     process.exit(2);
   }
 
+  if (options.probe) {
+    console.log(probe());
+    return;
+  }
+
   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);