@mehshekari/gsap-motion 4.3.0 → 4.4.2

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

@@ -151,6 +151,10 @@ 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.",
+  );
 }
 
 process.exit(findings.some((f) => f.level === "error") ? 1 : 0);

package/skill/scripts/capture-motion.mjs

@@ -29,6 +29,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 +46,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 +91,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",
@@ -176,6 +191,10 @@ export function parseOptions(argv) {
     cpu: 1,
     json: false,
     chrome: null,
+    headed: false,
+    seek: null,
+    atGiven: false,
+    probe: null,
     errors: [],
   };
 
@@ -192,6 +211,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;
       }
@@ -234,6 +254,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 +275,15 @@ 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");
+  }
 
   /** 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,6 +367,21 @@ const COUNT_FRAMES = `(() => {
   return true;
 })()`;
 
+/**
+ * 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 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)});
@@ -333,6 +390,39 @@ const boxOf = (selector) => `(() => {
   return { x: box.x + box.width / 2, y: box.y + box.height / 2, width: box.width, height: box.height };
 })()`;
 
+// --- 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 +446,7 @@ async function capture(options) {
     );
   }
 
-  const browser = connect(executable);
+  const browser = connect(executable, { headless: !options.headed });
   const notes = [];
 
   try {
@@ -467,18 +557,27 @@ async function capture(options) {
       }
     }
 
-    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 +586,7 @@ 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 after = await call("Performance.getMetrics");
 
     const delta = (name) => {
@@ -511,7 +611,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, canvases, chrome: executable };
   } finally {
     await browser.close();
   }
@@ -527,13 +627,18 @@ 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(", ")}`);
   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");
@@ -591,6 +696,11 @@ 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));

package/skill/scripts/lib/ast.mjs

@@ -214,26 +214,75 @@ export function tweenMethod(node) {
   return allowed.has(method) ? method : null;
 }
 
-const argumentObject = (call, index) => {
-  const node = unwrap(call.arguments[index]);
-  return node?.type === "ObjectExpression" ? node : null;
-};
+/**
+ * The object literal bound to `name` by a `const`, when the file binds that
+ * name exactly once. Two bindings of one name, in different functions, would
+ * need scope to tell apart; a wrong guess is a false finding, so neither is
+ * read.
+ */
+function constObject(root, name) {
+  const bound = findAll(
+    root,
+    (node) => node.type === "VariableDeclarator" && node.id.type === "Identifier" && node.id.name === name,
+  );
+  if (bound.length !== 1 || !bound[0].init) return null;
+  const declaration = parentOf(root, bound[0]);
+  if (declaration?.kind !== "const") return null;
+  const init = unwrap(bound[0].init);
+  return init.type === "ObjectExpression" ? init : null;
+}
+
+/** `node`'s properties, re-anchored at `site`: a finding lands where the tween uses them. */
+const anchoredAt = (properties, site) =>
+  properties.map((property) => ({ ...property, start: site.start, end: site.end }));
+
+/**
+ * The object a vars argument stands for: a literal, or a `const` bound to one,
+ * with any spread of such a `const` unfolded in place. Vars written once and
+ * shared between a `fromTo`'s ends are how a real film's credits hid two of
+ * seven filter tweens from the audit.
+ */
+function resolveObject(root, node, seen = new Set()) {
+  let target = unwrap(node);
+  let site = null;
+  if (target?.type === "Identifier" && root) {
+    site = target;
+    target = constObject(root, target.name);
+  }
+  if (target?.type !== "ObjectExpression" || seen.has(target)) return null;
+  seen.add(target);
+
+  let unfolded = false;
+  const properties = target.properties.flatMap((property) => {
+    if (property.type !== "SpreadElement") return [property];
+    const spread = resolveObject(root, property.argument, seen);
+    if (!spread) return [property];
+    unfolded = true;
+    return anchoredAt(spread.properties, property);
+  });
+  /** A literal with nothing to unfold is returned as it is, not as a copy. */
+  if (site) return { ...target, start: site.start, end: site.end, properties: anchoredAt(properties, site) };
+  return unfolded ? { ...target, properties } : target;
+}
+
+const argumentObject = (call, index, root) => resolveObject(root, call.arguments[index]);
 
 /**
  * The vars object that holds a tween's own settings — `repeat`, `ease`,
  * `yoyo`: the second argument, a `fromTo`'s third, a timeline's first. `null`
- * when it is not an object literal.
+ * when it is neither an object literal nor a `const` bound to one. Pass the
+ * file's `root` to follow a `const`; without it, only literals are read.
  */
-export const ownVars = (call, method) =>
-  argumentObject(call, method === "fromTo" ? 2 : method === "timeline" ? 0 : 1);
+export const ownVars = (call, method, root) =>
+  argumentObject(call, method === "fromTo" ? 2 : method === "timeline" ? 0 : 1, root);
 
 /**
  * Every vars object a tween call carries, as object literals: both of a
  * `fromTo`'s, a timeline's own, or the tween's.
  */
-export function varsObjects(call, method) {
+export function varsObjects(call, method, root) {
   const indexes = method === "fromTo" ? [1, 2] : method === "timeline" ? [0] : [1];
-  return indexes.map((index) => argumentObject(call, index)).filter(Boolean);
+  return indexes.map((index) => argumentObject(call, index, root)).filter(Boolean);
 }
 
 const FUNCTIONS = new Set([

package/skill/scripts/lib/rules.mjs

@@ -61,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:
@@ -104,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`.",
@@ -173,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, "");
@@ -589,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",
@@ -1009,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);
@@ -1087,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 [];
@@ -1401,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",
@@ -1415,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);
@@ -1462,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 [];
@@ -1518,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;