@mehshekari/gsap-motion 4.3.0 → 4.5.0

package/skill/reference/devices.md

@@ -71,6 +71,16 @@ Device memory and core count (`navigator.deviceMemory`, `hardwareConcurrency`)
 are hints, not facts: they are absent on some browsers and rounded on others.
 Use them to pick a tier, never to decide whether a thing works.
 
+**Data saving is about bytes, not motion.** `navigator.connection?.saveData` is
+true when the visitor has turned data saving on — read it where it exists, and
+treat its absence as false, since only Chromium has it. Skip what motion costs
+to download — a video background, large textures, a 3D scene's models — and
+ship the poster frame. Keep transforms and fades: they cost nothing to fetch.
+
+A weak device lowers cost before it loses content: a capped pixel ratio, fewer
+particles, no post-processing or blur, then a poster in place of the scene. Cut
+a beat of the story last, and the same beat on every device.
+
 ## Where to read each axis
 
 `prefers-reduced-motion`, `hover` and `pointer` are media queries, so

package/skill/reference/flip.md

@@ -1,220 +1,220 @@
-# Flip
-
-Animates between two layouts you did not have to compute. You change the DOM or
-the CSS however you like, and Flip works out the transform that makes the old
-state look like the new one, then animates it away.
-
-Use it when the animation's meaning is **continuity** — this thing is still that
-thing. A thumbnail becoming a hero image, a card expanding into a panel, an item
-moving between lists, a grid reflowing on filter.
-
-```ts
-import { Flip } from "gsap/Flip";
-gsap.registerPlugin(Flip);
-```
-
-## The pattern
-
-Three steps, always in this order:
-
-```ts
-const state = Flip.getState("[data-card]");   // 1. record
-
-container.classList.toggle("expanded");        // 2. change — anything at all
-
-Flip.from(state, {                             // 3. animate the difference
-  duration: 0.6,
-  ease: "power3.inOut",
-  absolute: true,
-});
-```
-
-Step 2 can be a class toggle, a React re-render, a reparent, a sort — Flip does
-not care how the layout changed, only what it was and what it is.
-
-## Options that matter
-
-```ts
-Flip.from(state, {
-  duration: 0.6,
-  ease: "power3.inOut",
-  absolute: true,          // position: absolute during the flip
-  nested: true,            // children also move — compensates their transforms
-  scale: true,             // scale instead of animating width/height
-  stagger: 0.05,
-  spin: true,
-  simple: true,            // skip rotation/skew maths when there is none
-  onEnter: (els) => gsap.fromTo(els, { opacity: 0 }, { opacity: 1 }),
-  onLeave: (els) => gsap.to(els, { opacity: 0 }),
-});
-```
-
-- **`absolute: true`** takes the moving elements out of flow for the duration.
-  Without it, siblings reflow during the animation and the whole grid jitters.
-  Reach for it whenever more than one element moves.
-- **`scale: true`** animates a transform instead of `width`/`height`. That is a
-  GPU-friendly property against a layout-triggering one — almost always the
-  right choice. The cost is that borders and text scale too; for a card with a
-  1px border, animating size may look better.
-- **`nested: true`** when the flipped elements contain their own flipped
-  children, so the child transform is compensated rather than compounded.
-- **`onEnter` / `onLeave`** handle elements that did not exist in one of the two
-  states. Flip cannot interpolate something that has no "before" — these are
-  where you fade them.
-
-## Shared element between routes or views
-
-The element must be identifiable in both states. `data-flip-id` is how Flip
-matches a node in the old state to a *different* node in the new one:
-
-```tsx
-<img data-flip-id="hero" … />   // in the grid
-<img data-flip-id="hero" … />   // in the detail view
-```
-
-```ts
-const state = Flip.getState("[data-flip-id]");
-setOpen(true);                                   // React swaps the tree
-Flip.from(state, { duration: 0.6, absolute: true });
-```
-
-In React, run `Flip.from` **after** the DOM has updated — in a layout effect
-keyed on the state that changed, so it measures the new layout before paint:
-
-```ts
-useGSAP(() => {
-  if (!state.current) return;
-  Flip.from(state.current, { duration: 0.6, absolute: true });
-}, { dependencies: [open] });
-```
-
-## Filtering a grid
-
-The case Flip is best at, and where hand-rolling is worst:
-
-```ts
-const state = Flip.getState(items);
-items.forEach((el) => {
-  el.style.display = el.dataset.tag === filter || filter === "all" ? "" : "none";
-});
-Flip.from(state, {
-  duration: 0.5,
-  scale: true,
-  absolute: true,
-  ease: "power2.inOut",
-  onEnter: (els) => gsap.fromTo(els, { opacity: 0, scale: 0.9 }, { opacity: 1, scale: 1 }),
-  onLeave: (els) => gsap.to(els, { opacity: 0, scale: 0.9 }),
-});
-```
-
-## Holding the container's height
-
-`absolute: true` lifts every target out of flow, so a container that took its
-height from them collapses to nothing and the whole page below jumps up. Flip's
-own docs prescribe holding the height and tweening it alongside:
-
-```ts
-tl.fromTo(grid, { height: fromHeight }, { height: toHeight, duration: D }, 0);
-```
-
-**Release it on Flip's completion, never on the parent timeline's.** Flip
-restores the targets to flow as the last child of its own timeline
-(`_setFinalStates`, added with `animation.call()` at its end — internals,
-verified against gsap 3.15), and its
-`onComplete` fires immediately after that:
-
-```ts
-tl.add(
-  Flip.from(state, {
-    targets: shells,
-    absolute: true,
-    onComplete: () => gsap.set(grid, { clearProps: "height" }),
-  }),
-  0,
-);
-```
-
-Hanging it on the parent's `onComplete` only looks equivalent. The parent ends
-when its **longest** child ends, so the gap between "Flip put things back in
-flow" and "the height was released" becomes whatever else happens to be on that
-timeline. Add a long sibling and it works; take that sibling away — a branch
-that skipped, an async tween that never got added — and the release lands on the
-same frame as the restore, for a one-frame collapse that only reproduces on the
-path where the sibling is missing. A card-to-panel Flip had exactly this:
-correct on every click but the first, where an image had not decoded and a
-sibling image pass was never added.
-
-The general rule: **tie the release of a held layout property to the event that
-actually restores the layout, not to a timeline whose length is incidental.**
-
-### The held height distorts the layout Flip is about to measure
-
-This one is worse, because it produces a wrong animation rather than a flicker.
-
-`gsap.fromTo(grid, { height: from }, { height: to })` renders its start value
-immediately, so by the time `Flip.from` measures where the targets should land,
-the container is already pinned to the **old** height. A grid or flex container
-that is taller than its content **stretches its auto rows to fill it** —
-`align-content` defaults to `normal`, which behaves as `stretch`. Flip therefore
-measures a stretched layout, animates everything to those positions, and the
-elements snap when it releases them into the real one.
-
-```
-held 744, natural 632, two rows  →  each row +56px
-  Flip's target:  138 + 476 + 24 = 638
-  where they go:  138 + 420 + 24 = 582     ← a 56px snap on release
-```
-
-The fix is on the container, not the animation:
-
-```tsx
-<ul className="grid content-start gap-6">   {/* align-content: start */}
-```
-
-The held height then sits as space at the foot instead of inflating every row,
-and it is inert whenever the height is not being held.
-
-It reproduces only when the held height **exceeds** the natural one — opening a
-panel that makes the grid shorter. Close it again, or switch between two open
-states, and the container is shorter than its content, nothing stretches, and
-the bug hides. That asymmetry is why it reads as "only on the first click".
-
-## `Flip.fit`
-
-Makes one element match another's position and size without changing the DOM —
-useful for an overlay that must land exactly on a card:
-
-```ts
-Flip.fit(overlay, card, { duration: 0.5, scale: true, ease: "power3.inOut" });
-```
-
-## When not to use it
-
-- **A simple show/hide.** Flip measures every target twice; a fade does not need
-  that.
-- **Something that is not the same object.** If the visitor would not say "that
-  became this", continuity is the wrong story and Flip is just an expensive
-  transition.
-- **Very large sets.** Two full layout reads plus a transform per element. A
-  hundred items is fine; a thousand is not.
-
-## Accessibility
-
-Flip moves things across the screen, which is exactly the motion
-`prefers-reduced-motion` exists for. Under `reduce`, apply the layout change
-with `duration: 0` — the state still changes, the travel does not. Never skip
-the change itself.
-
-Focus stays on the element being flipped, which is correct. Just make sure the
-focus ring is not clipped by an `overflow: hidden` ancestor during the flip.
-
-## Failures
-
-| Symptom | Cause |
-|---|---|
-| Siblings jitter during the flip | missing `absolute: true` |
-| Nothing animates | state captured after the change, not before |
-| New items pop in | no `onEnter` |
-| Children double-transform | missing `nested: true` |
-| Blurry text mid-flight | `scale: true` on text-heavy elements — animate size |
-| Wrong in React | `Flip.from` ran before the DOM updated |
+# Flip
+
+Animates between two layouts you did not have to compute. You change the DOM or
+the CSS however you like, and Flip works out the transform that makes the old
+state look like the new one, then animates it away.
+
+Use it when the animation's meaning is **continuity** — this thing is still that
+thing. A thumbnail becoming a hero image, a card expanding into a panel, an item
+moving between lists, a grid reflowing on filter.
+
+```ts
+import { Flip } from "gsap/Flip";
+gsap.registerPlugin(Flip);
+```
+
+## The pattern
+
+Three steps, always in this order:
+
+```ts
+const state = Flip.getState("[data-card]");   // 1. record
+
+container.classList.toggle("expanded");        // 2. change — anything at all
+
+Flip.from(state, {                             // 3. animate the difference
+  duration: 0.6,
+  ease: "power3.inOut",
+  absolute: true,
+});
+```
+
+Step 2 can be a class toggle, a React re-render, a reparent, a sort — Flip does
+not care how the layout changed, only what it was and what it is.
+
+## Options that matter
+
+```ts
+Flip.from(state, {
+  duration: 0.6,
+  ease: "power3.inOut",
+  absolute: true,          // position: absolute during the flip
+  nested: true,            // children also move — compensates their transforms
+  scale: true,             // scale instead of animating width/height
+  stagger: 0.05,
+  spin: true,
+  simple: true,            // skip rotation/skew maths when there is none
+  onEnter: (els) => gsap.fromTo(els, { opacity: 0 }, { opacity: 1 }),
+  onLeave: (els) => gsap.to(els, { opacity: 0 }),
+});
+```
+
+- **`absolute: true`** takes the moving elements out of flow for the duration.
+  Without it, siblings reflow during the animation and the whole grid jitters.
+  Reach for it whenever more than one element moves.
+- **`scale: true`** animates a transform instead of `width`/`height`. That is a
+  GPU-friendly property against a layout-triggering one — almost always the
+  right choice. The cost is that borders and text scale too; for a card with a
+  1px border, animating size may look better.
+- **`nested: true`** when the flipped elements contain their own flipped
+  children, so the child transform is compensated rather than compounded.
+- **`onEnter` / `onLeave`** handle elements that did not exist in one of the two
+  states. Flip cannot interpolate something that has no "before" — these are
+  where you fade them.
+
+## Shared element between routes or views
+
+The element must be identifiable in both states. `data-flip-id` is how Flip
+matches a node in the old state to a *different* node in the new one:
+
+```tsx
+<img data-flip-id="hero" … />   // in the grid
+<img data-flip-id="hero" … />   // in the detail view
+```
+
+```ts
+const state = Flip.getState("[data-flip-id]");
+setOpen(true);                                   // React swaps the tree
+Flip.from(state, { duration: 0.6, absolute: true });
+```
+
+In React, run `Flip.from` **after** the DOM has updated — in a layout effect
+keyed on the state that changed, so it measures the new layout before paint:
+
+```ts
+useGSAP(() => {
+  if (!state.current) return;
+  Flip.from(state.current, { duration: 0.6, absolute: true });
+}, { dependencies: [open] });
+```
+
+## Filtering a grid
+
+The case Flip is best at, and where hand-rolling is worst:
+
+```ts
+const state = Flip.getState(items);
+items.forEach((el) => {
+  el.style.display = el.dataset.tag === filter || filter === "all" ? "" : "none";
+});
+Flip.from(state, {
+  duration: 0.5,
+  scale: true,
+  absolute: true,
+  ease: "power2.inOut",
+  onEnter: (els) => gsap.fromTo(els, { opacity: 0, scale: 0.9 }, { opacity: 1, scale: 1 }),
+  onLeave: (els) => gsap.to(els, { opacity: 0, scale: 0.9 }),
+});
+```
+
+## Holding the container's height
+
+`absolute: true` lifts every target out of flow, so a container that took its
+height from them collapses to nothing and the whole page below jumps up. Flip's
+own docs prescribe holding the height and tweening it alongside:
+
+```ts
+tl.fromTo(grid, { height: fromHeight }, { height: toHeight, duration: D }, 0);
+```
+
+**Release it on Flip's completion, never on the parent timeline's.** Flip
+restores the targets to flow as the last child of its own timeline
+(`_setFinalStates`, added with `animation.call()` at its end — internals,
+verified against gsap 3.15), and its
+`onComplete` fires immediately after that:
+
+```ts
+tl.add(
+  Flip.from(state, {
+    targets: shells,
+    absolute: true,
+    onComplete: () => gsap.set(grid, { clearProps: "height" }),
+  }),
+  0,
+);
+```
+
+Hanging it on the parent's `onComplete` only looks equivalent. The parent ends
+when its **longest** child ends, so the gap between "Flip put things back in
+flow" and "the height was released" becomes whatever else happens to be on that
+timeline. Add a long sibling and it works; take that sibling away — a branch
+that skipped, an async tween that never got added — and the release lands on the
+same frame as the restore, for a one-frame collapse that only reproduces on the
+path where the sibling is missing. A card-to-panel Flip had exactly this:
+correct on every click but the first, where an image had not decoded and a
+sibling image pass was never added.
+
+The general rule: **tie the release of a held layout property to the event that
+actually restores the layout, not to a timeline whose length is incidental.**
+
+### The held height distorts the layout Flip is about to measure
+
+This one is worse, because it produces a wrong animation rather than a flicker.
+
+`gsap.fromTo(grid, { height: from }, { height: to })` renders its start value
+immediately, so by the time `Flip.from` measures where the targets should land,
+the container is already pinned to the **old** height. A grid or flex container
+that is taller than its content **stretches its auto rows to fill it** —
+`align-content` defaults to `normal`, which behaves as `stretch`. Flip therefore
+measures a stretched layout, animates everything to those positions, and the
+elements snap when it releases them into the real one.
+
+```
+held 744, natural 632, two rows  →  each row +56px
+  Flip's target:  138 + 476 + 24 = 638
+  where they go:  138 + 420 + 24 = 582     ← a 56px snap on release
+```
+
+The fix is on the container, not the animation:
+
+```tsx
+<ul className="grid content-start gap-6">   {/* align-content: start */}
+```
+
+The held height then sits as space at the foot instead of inflating every row,
+and it is inert whenever the height is not being held.
+
+It reproduces only when the held height **exceeds** the natural one — opening a
+panel that makes the grid shorter. Close it again, or switch between two open
+states, and the container is shorter than its content, nothing stretches, and
+the bug hides. That asymmetry is why it reads as "only on the first click".
+
+## `Flip.fit`
+
+Makes one element match another's position and size without changing the DOM —
+useful for an overlay that must land exactly on a card:
+
+```ts
+Flip.fit(overlay, card, { duration: 0.5, scale: true, ease: "power3.inOut" });
+```
+
+## When not to use it
+
+- **A simple show/hide.** Flip measures every target twice; a fade does not need
+  that.
+- **Something that is not the same object.** If the visitor would not say "that
+  became this", continuity is the wrong story and Flip is just an expensive
+  transition.
+- **Very large sets.** Two full layout reads plus a transform per element. A
+  hundred items is fine; a thousand is not.
+
+## Accessibility
+
+Flip moves things across the screen, which is exactly the motion
+`prefers-reduced-motion` exists for. Under `reduce`, apply the layout change
+with `duration: 0` — the state still changes, the travel does not. Never skip
+the change itself.
+
+Focus stays on the element being flipped, which is correct. Just make sure the
+focus ring is not clipped by an `overflow: hidden` ancestor during the flip.
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Siblings jitter during the flip | missing `absolute: true` |
+| Nothing animates | state captured after the change, not before |
+| New items pop in | no `onEnter` |
+| Children double-transform | missing `nested: true` |
+| Blurry text mid-flight | `scale: true` on text-heavy elements — animate size |
+| Wrong in React | `Flip.from` ran before the DOM updated |

package/skill/reference/interaction.md

@@ -187,4 +187,5 @@ Cheap, and the styling stays in CSS where it can follow the theme.
 | Magnetic pull feels wrong | strength too high, or rect measured once |
 | Follower stuck in a corner | mounted on a touch device |
 | Hover sticks after tap | no `(hover: hover)` gate |
+| A hover class's scale does nothing | GSAP transformed the element and set CSS `scale` to `none` — see [performance.md](performance.md#scale-rotate-and-translate-are-not-transform) |
 | Effects survive navigation | `Observer`/`Draggable` not killed, listeners not removed |

package/skill/reference/performance.md

@@ -51,6 +51,25 @@ Two ways out:
 The same asymmetry applies to `left`/`x` and to any percentage `width` or
 `height` swapped for a scale.
 
+### `scale`, `rotate` and `translate` are not `transform`
+
+They are CSS properties of their own, and they **compose** with `transform`
+rather than being replaced by it. Tailwind v4 compiles its `scale-*`,
+`rotate-*` and `translate-*` utilities to them. GSAP accommodates them: the
+first time it reads an element's transform, it folds their computed values into
+its own and sets all three to `none` inline (verified against gsap 3.15). Two
+silent failures follow:
+
+- **Code that writes `style.transform` itself** — a rAF loop, a `useFrame`, a
+  scroll store — still composes with a class's `scale`. `scale-y-0` plus an
+  inline `scaleY(0.6)` is still zero, so the element never shows. Give the
+  initial state in the property the code writes: `gsap.set`, or an arbitrary
+  `transform` class in place of the utility.
+- **On an element GSAP has transformed, those classes stop working.** The inline
+  `none` outranks them, so a `hover:scale-105`, or a breakpoint's
+  `translate-x-*`, does nothing from then on. Animate those states with GSAP
+  too, or put them on a wrapper GSAP never touches.
+
 ## The pointer rule
 
 One tween per pointer event allocates an object per frame and creates tweens
@@ -187,6 +206,74 @@ If the trace shows time in Layout, you are animating a layout property. If it
 shows Paint, something is repainting — usually a filter or a shadow. If it shows
 Scripting, it is your handler, and usually React.
 
+## WebGL: the first frame of each material
+
+Three compiles a material's shader the first time it draws it, and uploads a
+texture the first time it samples it. Both run on the main thread, inside that
+frame's render — so an object first seen mid-scroll costs one frame of hundreds
+of milliseconds, once, and never shows again in a trace recorded after it.
+
+Compile ahead, behind the loader or before scroll can reach the object:
+
+```ts
+await renderer.compileAsync(scene, camera);   // R3F: gl, scene, camera from useThree
+renderer.initTexture(texture);                 // uploads now, not on first sample
+```
+
+- **Objects with `visible: false` are compiled too** — `compile` walks every
+  mesh. Lights are not: a light that is off at compile time and turned on later
+  changes the lighting state, and every lit material recompiles then.
+- **Inside a render target it is a different program.** Drawing into one turns
+  tone mapping off and outputs the working colour space, so post-processing,
+  a portal or a render-to-texture uses a variant the screen compile never made.
+  Compile once more with any render target bound:
+
+  ```ts
+  const warm = new WebGLRenderTarget(1, 1);
+  renderer.setRenderTarget(warm);
+  await renderer.compileAsync(scene, camera);
+  renderer.setRenderTarget(null);
+  warm.dispose();
+  ```
+
+- **Fog, shadows, clipping planes, a new environment map**, and a changed light
+  count or tone mapping, each change the program. Set them before compiling.
+- `compileAsync` waits on `KHR_parallel_shader_compile` where it exists. Where it
+  does not, the work still happens on the main thread — which is why it belongs
+  before the scroll, not at the moment the object appears.
+- What cannot be warmed can be timed: mount the heavy object on ScrollTrigger's
+  `scrollEnd` event, when a dropped frame costs nothing visible.
+
+Verified against `three@0.186`.
+
+## WebGL: losing the context, and reading it back
+
+**Every canvas is a WebGL context, and the browser caps how many a page may
+hold.** Past the cap it drops the oldest — a scene mounted earlier goes black,
+with only a console warning. One canvas drawing several views (scissored
+viewports) costs one context; a canvas per section costs one each. Remounting
+canvases on scroll creates new ones, so check that unmount releases each.
+
+A context can also be lost to the GPU process — a driver reset, memory pressure.
+Three handles the event: it stops rendering on `webglcontextlost` and rebuilds
+its state on `webglcontextrestored`, re-uploading from what the CPU still holds.
+Two things it cannot bring back: an image you released after upload, and what a
+render target contained. And it only draws again if something renders — with
+R3F's `frameloop="demand"`, invalidate on restore. Test both events on purpose:
+
+```ts
+renderer.forceContextLoss();      // then
+renderer.forceContextRestore();   // the scene should come back by itself
+```
+
+**Reading pixels back stalls.** `readPixels`, `readRenderTargetPixels`, and a
+`getImageData` on a canvas WebGL drew into all make the CPU wait for every GPU
+command queued before them. Read rarely, read a small region, and prefer
+`readRenderTargetPixelsAsync`, which waits on a fence instead of blocking. A 2D
+canvas you read often takes `getContext("2d", { willReadFrequently: true })`.
+
+Verified against `three@0.186`.
+
 ## Budget
 
 - A frame means everything in it — your handler, style, layout, paint,

package/skill/reference/refine.md

@@ -75,6 +75,40 @@ Reach the state first, and change the conditions that usually break things:
 - `--reduced`, `--dark`, `--mobile`, `--cpu 4`. `--mobile` makes input touch,
   so it cannot be combined with `--hover`: a coarse pointer has no hover, which
   is the thing worth knowing.
+- `--viewport 1440x900` for a desktop layout. Without it the window is whatever
+  headless Chrome opens at — about 760×480 — where many sites switch to their
+  compact layout. Every report prints the viewport it ran at.
+- `--wait` is a fixed wait after navigation; it does not detect a loader. Raise
+  it, or use `--seek`.
+- **A step that did nothing fails the run.** Nothing matched, no match on
+  screen, or an invalid selector: it is listed last, under *Not done*, and the
+  run exits 3 — 2 for an invalid selector. A hidden match is passed over for
+  the next one, and one off screen is scrolled to first.
+- **Cost on a production build, not the dev server.** In development React's
+  StrictMode mounts every effect twice — two contexts, two WebGL contexts — and
+  the bundle is unminified, so what a dev server measures is not what ships.
+  Motion and timing can be watched on either.
+- `--headed` for anything WebGL. Headless Chrome draws in software — on one
+  Windows machine, the Basic Render Driver headless and the Intel GPU headed —
+  so a 3D scene's frames, rate and long frames describe the wrong thing. A
+  report warns when the page has a canvas and the run was headless. The DOM's
+  layout and style numbers do not depend on it.
+- `--seek <name>` for a moment too short or too far into the timeline for the
+  clock to land on. `--at` then means seconds of the timeline: before each
+  capture it calls `window.<name>(t)` and waits two rendered frames. A bundle
+  never exposes `gsap`, so the page has to export the function — in
+  development only, removed with the context:
+
+```ts
+if (process.env.NODE_ENV !== "production") {
+  Object.assign(window, { __seek: (t: number) => tl.pause(t) });
+  // and in the cleanup: Reflect.deleteProperty(window, "__seek");
+}
+```
+
+  Against a production build it is missing, and the run says so rather than
+  capturing the wrong frames. Through an MCP browser, call it from
+  `evaluate_script` instead.
 
 **Without a browser, report the stage as not run.** Not "fine".
 
@@ -99,6 +133,8 @@ that no source rule can reach.
 | **X% of the screen in motion** | Everything moving at once reads as noise, not as choreography. |
 | **seams** | A step far larger than that motion's own rhythm: a loop put back by hand instead of carried. |
 | **motion over text** | Something painted over a line a reader is in the middle of. Hit-tested, so it is what is really on top. |
+| **frames over 50ms** | Long Animation Frames, with the sampler's own time taken out of each: the rest is the page's. "Not measured" means the browser has no such API, not that nothing was long. |
+| **layout shift** | The browser's own shift total, input excluded. Sampling reads layout but never moves it, so this is the page's alone — a pin swapping its position at a section edge shows here. |
 
 Three things it deliberately does not do, so you do not read them into it:
 
@@ -113,6 +149,33 @@ Three things it deliberately does not do, so you do not read them into it:
 A clean report is evidence, not proof: it watched one window, on one machine, at
 one size. Say which.
 
+## In a browser you already drive
+
+Both scripts open a Chrome of their own. Where a project allows only one — a
+DevTools MCP server, say — they print what they would have run instead, and
+open nothing:
+
+```bash
+node <skill-dir>/scripts/review-motion.mjs --probe install   # start recording
+node <skill-dir>/scripts/review-motion.mjs --probe read      # the findings
+node <skill-dir>/scripts/capture-motion.mjs --probe timeline # the running timeline
+```
+
+Each prints one function. Run `install` through the tool's `evaluate_script`,
+then reach the state — scroll, hover, wait — with that tool's own input, and
+then `read`. It returns what `review --json` would: the same conclusions,
+computed in the page, so the frame log never leaves it.
+
+What changes, so the report says it:
+
+- **First motion counts from `install`**, not from navigation. A reload discards
+  the recorder; install again after one.
+- **Emulation is the driving tool's**: its CPU throttling, viewport and
+  media features, set before `install`.
+- **No layout or style counts.** Those come from the DevTools protocol, which a
+  page cannot reach — read them from the tool's own performance trace. Long
+  frames and layout shifts are observed in the page, so `read` has them.
+
 ## When to stop
 
 Stop when every check is clean, or after **three rounds**, reporting what is