@mehshekari/gsap-motion 4.3.0 → 4.5.0

package/skill/scripts/review-motion.mjs

@@ -19,13 +19,24 @@
  * 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,
+  exitFor,
+  findChrome,
+  gpuNote,
+  parseViewport,
+  prepareOut,
+  scrollExpression,
+  undone,
+} from "./capture-motion.mjs";
 
 // --- What a recording means ---------------------------------------------------
 
@@ -199,7 +210,7 @@ export function afterScroll(found, scrolledAt, { settle = 300 } = {}) {
  */
 export function seamEvents(torn, { window = 50 } = {}) {
   const flat = torn.flatMap((element) =>
-    element.seams.map((seam) => ({ key: element.key, at: seam.at, jump: seam.jump })),
+    element.seams.map((seam) => ({ key: element.key, box: element.box, at: seam.at, jump: seam.jump })),
   );
   flat.sort((a, b) => a.at - b.at);
 
@@ -215,6 +226,7 @@ export function seamEvents(torn, { window = 50 } = {}) {
     events.push({
       at: seam.at,
       elements: new Set([seam.key]),
+      box: seam.box,
       least: seam.jump,
       most: seam.jump,
     });
@@ -224,11 +236,44 @@ 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,
   }));
 }
 
+/**
+ * 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();
@@ -253,12 +298,15 @@ export function parseOptions(argv) {
     watch: 3000,
     scroll: null,
     mobile: false,
+    viewport: null,
     reduced: false,
     dark: false,
     cpu: 1,
     out: null,
     json: false,
     chrome: null,
+    headed: false,
+    probe: null,
     errors: [],
   };
 
@@ -300,9 +348,18 @@ export function parseOptions(argv) {
       case "--chrome":
         options.chrome = next() ?? null;
         break;
+      case "--headed":
+        options.headed = true;
+        break;
       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;
@@ -312,12 +369,27 @@ 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.");
+  }
+  if (options.mobile && options.viewport) {
+    options.errors.push("--mobile sets its own viewport; drop one of --mobile and --viewport.");
+  }
   return options;
 }
 
@@ -366,9 +438,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 +537,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 +581,10 @@ const RECORDER = `(() => {
     viewport: { width: innerWidth, height: innerHeight },
     text: textLines(),
     log,
+    longFrames,
+    shift,
+    cost,
+    canvases: document.querySelectorAll("canvas").length,
   });
   return true;
 })()`;
@@ -485,7 +599,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 {
@@ -518,6 +632,9 @@ async function watch(options) {
       });
       await call("Emulation.setTouchEmulationEnabled", { enabled: true, maxTouchPoints: 5 });
     }
+    if (options.viewport) {
+      await call("Emulation.setDeviceMetricsOverride", { ...options.viewport, deviceScaleFactor: 1, mobile: false });
+    }
     if (options.cpu > 1) await call("Emulation.setCPUThrottlingRate", { rate: options.cpu });
 
     await call("Page.addScriptToEvaluateOnNewDocument", { source: RECORDER });
@@ -526,19 +643,13 @@ async function watch(options) {
     await call("Page.navigate", { url: options.url });
     await wait(options.watch);
 
+    const notDone = [];
     if (options.scroll !== null) {
-      const pixels = asNumber(options.scroll);
-      const moved = await evaluate(
-        pixels === null
-          ? `(() => {
-              const element = document.querySelector(${JSON.stringify(options.scroll)});
-              if (!element) return null;
-              element.scrollIntoView({ block: "center" });
-              return Math.round(window.scrollY);
-            })()`
-          : `(window.scrollTo(0, ${pixels}), Math.round(window.scrollY))`,
-      );
-      notes.push(moved === null ? `scroll: nothing matched ${options.scroll}` : `scroll: to ${moved}px`);
+      const step = { type: "scroll", value: options.scroll };
+      const moved = await evaluate(scrollExpression(options.scroll));
+      const missed = undone(step, moved);
+      if (missed) notDone.push(missed);
+      else notes.push(`scroll: to ${moved.y}px`);
       await wait(options.watch);
     }
 
@@ -557,9 +668,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"));
     }
 
@@ -570,6 +681,7 @@ async function watch(options) {
       recalcs: delta("RecalcStyleCount"),
       shot,
       notes,
+      notDone,
     };
   } finally {
     await browser.close();
@@ -590,6 +702,7 @@ export function conclude(result) {
   /** One track per element, to find the loops that tear. */
   const tracks = new Map();
   const named = new Map();
+  const boxes = new Map();
   for (const frame of log) {
     for (const moved of frame.moved) {
       const id = moved.id ?? moved.key;
@@ -597,6 +710,7 @@ export function conclude(result) {
       track.push({ at: frame.at, x: moved.x });
       tracks.set(id, track);
       named.set(id, moved.key);
+      boxes.set(id, moved.box);
     }
   }
   const scrolledAt = log.filter((frame) => frame.scrolled).map((frame) => frame.at);
@@ -606,7 +720,12 @@ export function conclude(result) {
     if (track.length < 20) continue;
     const found = afterScroll(seams(track), scrolledAt);
     if (found.length) {
-      torn.push({ key: named.get(key) ?? key, seams: found.slice(0, 3), frames: track.length });
+      torn.push({
+        key: named.get(key) ?? key,
+        box: boxes.get(key) ?? null,
+        seams: found.slice(0, 3),
+        frames: track.length,
+      });
     }
   }
 
@@ -629,7 +748,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 +803,14 @@ 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(", ")}`);
+  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}`);
 
   lines.push("", "What moved");
   if (found.firstMotion === null) {
@@ -655,7 +820,7 @@ export function report(result, options) {
     lines.push(`  first motion at ${found.firstMotion}ms`);
     lines.push(
       `  ${found.movers} elements moved, ${found.gsapMovers} of them GSAP's` +
-        `${found.movers > found.gsapMovers ? " (the rest is CSS, which the source audit cannot see)" : ""}`,
+        `${found.movers > found.gsapMovers ? " (the rest is CSS, Web Animations or other script, which the source audit cannot see)" : ""}`,
     );
     if (found.spread) lines.push(`  they started over a span of ${found.spread}ms`);
   }
@@ -680,13 +845,36 @@ 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)) {
       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}`,
       );
     }
   }
@@ -701,6 +889,11 @@ export function report(result, options) {
   if (result.shot) lines.push("", `Frame: ${result.shot}`);
 
   lines.push("", "These are measurements. Composition, rhythm and taste are yours to judge.");
+  /** Last, so a reader who sees only the end still sees it. */
+  if (result.notDone?.length) {
+    lines.push("", "Not done — the run exits non-zero");
+    for (const line of result.notDone) lines.push(`  ${line}`);
+  }
   return lines.join("\n");
 }
 
@@ -714,13 +907,19 @@ async function main(argv) {
     process.exit(2);
   }
 
+  if (options.probe) {
+    console.log(probe(options.probe));
+    return;
+  }
+
   try {
     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);