@mehshekari/gsap-motion 4.3.0 → 4.4.2

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(

package/skill/template/useScrollScene.ts

@@ -1,126 +1,126 @@
-"use client";
-
-import { useGSAP } from "@gsap/react";
-import gsap from "gsap";
-import { ScrollTrigger } from "gsap/ScrollTrigger";
-import { useRef } from "react";
-
-/**
- * Starting point for a scroll-driven scene.
- *
- * The shape here is the lesson: one trigger owning one timeline, a genuinely
- * different strategy on mobile rather than a smaller one, and `ease: "none"`
- * throughout because the scrollbar — not an ease curve — is the playhead.
- *
- * Copy it, rename it, replace the beats. Typechecked for the same reason as
- * the sibling template.
- */
-gsap.registerPlugin(useGSAP, ScrollTrigger);
-
-/** Scroll distance the pinned sequence is spread across, in pixels. */
-const SCROLL_LENGTH = 2400;
-
-export function useScrollScene() {
-  const rootRef = useRef<HTMLDivElement>(null);
-
-  useGSAP(
-    () => {
-      const root = rootRef.current;
-      if (!root) return;
-
-      const mm = gsap.matchMedia();
-
-      mm.add(
-        {
-          desktop: "(min-width: 768px) and (prefers-reduced-motion: no-preference)",
-          mobile: "(max-width: 767px) and (prefers-reduced-motion: no-preference)",
-          reduced: "(prefers-reduced-motion: reduce)",
-        },
-        (context) => {
-          const { desktop, reduced } = context.conditions as Record<
-            string,
-            boolean
-          >;
-
-          /**
-           * Scroll-scrubbed pinning is a textbook vestibular trigger: the
-           * content moves while the page does not. Under `reduce` the beats
-           * simply exist, composed, with no pin and no scrub.
-           */
-          if (reduced) {
-            gsap.set("[data-beat]", { autoAlpha: 1, y: 0 });
-            return;
-          }
-
-          /**
-           * Not the desktop sequence scaled down. A 2400px pin on a phone is a
-           * long time to be stuck, and pinning fights the address bar
-           * collapsing — so each beat becomes an ordinary in-view reveal
-           * instead. Same content, different strategy.
-           */
-          if (!desktop) {
-            gsap.utils.toArray<HTMLElement>("[data-beat]").forEach((beat) => {
-              gsap.from(beat, {
-                autoAlpha: 0,
-                y: 24,
-                duration: 0.6,
-                ease: "power3.out",
-                scrollTrigger: { trigger: beat, start: "top 78%" },
-              });
-            });
-            return;
-          }
-
-          gsap
-            .timeline({
-              /**
-               * `ease: "none"` on every child. Easing inside a scrubbed
-               * timeline fights the visitor's own scrolling and reads as lag —
-               * `scrub` is where the smoothing belongs.
-               */
-              defaults: { ease: "none" },
-              scrollTrigger: {
-                trigger: root,
-                start: "top top",
-                end: `+=${SCROLL_LENGTH}`,
-                pin: true,
-                scrub: 1,
-                /** Reduces the flicker when the pin engages at speed. */
-                anticipatePin: 1,
-                /** Recomputes measured start values after a resize. */
-                invalidateOnRefresh: true,
-                markers: process.env.NODE_ENV === "development",
-              },
-            })
-            /**
-             * Labels rather than offsets. A scrubbed sequence gets retimed
-             * many times, and two children sharing a label stay together when
-             * the beat before them changes length.
-             */
-            .addLabel("open")
-            .from("[data-beat='1']", { autoAlpha: 0, y: 24, duration: 0.4 }, "open")
-
-            .addLabel("detail")
-            .to("[data-beat='1']", { autoAlpha: 0, duration: 0.3 }, "detail")
-            .from("[data-beat='2']", { autoAlpha: 0, y: 24, duration: 0.4 }, "detail+=0.3")
-
-            /**
-             * Placed at position 0 with the timeline's full span, so it tracks
-             * overall progress regardless of what else is happening.
-             */
-            .to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
-        },
-      );
-
-      /**
-       * ScrollTriggers and the `matchMedia` above are both reverted with the
-       * context — each registers itself when constructed inside one. Only
-       * things GSAP never sees (timers, raw listeners, observers) need a
-       * cleanup returned from here.
-       */
-    },
-    { scope: rootRef },
-  );
-
-  return rootRef;
-}
+"use client";
+
+import { useGSAP } from "@gsap/react";
+import gsap from "gsap";
+import { ScrollTrigger } from "gsap/ScrollTrigger";
+import { useRef } from "react";
+
+/**
+ * Starting point for a scroll-driven scene.
+ *
+ * The shape here is the lesson: one trigger owning one timeline, a genuinely
+ * different strategy on mobile rather than a smaller one, and `ease: "none"`
+ * throughout because the scrollbar — not an ease curve — is the playhead.
+ *
+ * Copy it, rename it, replace the beats. Typechecked for the same reason as
+ * the sibling template.
+ */
+gsap.registerPlugin(useGSAP, ScrollTrigger);
+
+/** Scroll distance the pinned sequence is spread across, in pixels. */
+const SCROLL_LENGTH = 2400;
+
+export function useScrollScene() {
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  useGSAP(
+    () => {
+      const root = rootRef.current;
+      if (!root) return;
+
+      const mm = gsap.matchMedia();
+
+      mm.add(
+        {
+          desktop: "(min-width: 768px) and (prefers-reduced-motion: no-preference)",
+          mobile: "(max-width: 767px) and (prefers-reduced-motion: no-preference)",
+          reduced: "(prefers-reduced-motion: reduce)",
+        },
+        (context) => {
+          const { desktop, reduced } = context.conditions as Record<
+            string,
+            boolean
+          >;
+
+          /**
+           * Scroll-scrubbed pinning is a textbook vestibular trigger: the
+           * content moves while the page does not. Under `reduce` the beats
+           * simply exist, composed, with no pin and no scrub.
+           */
+          if (reduced) {
+            gsap.set("[data-beat]", { autoAlpha: 1, y: 0 });
+            return;
+          }
+
+          /**
+           * Not the desktop sequence scaled down. A 2400px pin on a phone is a
+           * long time to be stuck, and pinning fights the address bar
+           * collapsing — so each beat becomes an ordinary in-view reveal
+           * instead. Same content, different strategy.
+           */
+          if (!desktop) {
+            gsap.utils.toArray<HTMLElement>("[data-beat]").forEach((beat) => {
+              gsap.from(beat, {
+                autoAlpha: 0,
+                y: 24,
+                duration: 0.6,
+                ease: "power3.out",
+                scrollTrigger: { trigger: beat, start: "top 78%" },
+              });
+            });
+            return;
+          }
+
+          gsap
+            .timeline({
+              /**
+               * `ease: "none"` on every child. Easing inside a scrubbed
+               * timeline fights the visitor's own scrolling and reads as lag —
+               * `scrub` is where the smoothing belongs.
+               */
+              defaults: { ease: "none" },
+              scrollTrigger: {
+                trigger: root,
+                start: "top top",
+                end: `+=${SCROLL_LENGTH}`,
+                pin: true,
+                scrub: 1,
+                /** Reduces the flicker when the pin engages at speed. */
+                anticipatePin: 1,
+                /** Recomputes measured start values after a resize. */
+                invalidateOnRefresh: true,
+                markers: process.env.NODE_ENV === "development",
+              },
+            })
+            /**
+             * Labels rather than offsets. A scrubbed sequence gets retimed
+             * many times, and two children sharing a label stay together when
+             * the beat before them changes length.
+             */
+            .addLabel("open")
+            .from("[data-beat='1']", { autoAlpha: 0, y: 24, duration: 0.4 }, "open")
+
+            .addLabel("detail")
+            .to("[data-beat='1']", { autoAlpha: 0, duration: 0.3 }, "detail")
+            .from("[data-beat='2']", { autoAlpha: 0, y: 24, duration: 0.4 }, "detail+=0.3")
+
+            /**
+             * Placed at position 0 with the timeline's full span, so it tracks
+             * overall progress regardless of what else is happening.
+             */
+            .to("[data-progress]", { scaleX: 1, transformOrigin: "0% 50%" }, 0);
+        },
+      );
+
+      /**
+       * ScrollTriggers and the `matchMedia` above are both reverted with the
+       * context — each registers itself when constructed inside one. Only
+       * things GSAP never sees (timers, raw listeners, observers) need a
+       * cleanup returned from here.
+       */
+    },
+    { scope: rootRef },
+  );
+
+  return rootRef;
+}