@mehshekari/gsap-motion 4.2.1 → 4.4.2

package/skill/reference/devices.md

@@ -23,13 +23,16 @@ mm.add(
     hoverable: "(hover: hover) and (pointer: fine)",
     motion: "(prefers-reduced-motion: no-preference)",
   },
-  (context) => {
+  (context, contextSafe) => {
     const { wide, hoverable, motion } = context.conditions;
-    // …one branch, three facts
+    // …one branch, three facts. A handler that tweens later: contextSafe(fn).
   },
 );
 ```
 
+`contextSafe` is the **second** argument. The context has none, and
+`context.add(fn)` runs `fn` at once: either one ships a blank page.
+
 `matchMedia` re-runs the body when any condition changes and reverts what the
 previous run created, so a visitor who rotates a phone, plugs in a mouse or
 turns on reduced motion gets the right version without a reload.
@@ -68,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

@@ -13,6 +13,11 @@ The recovery is what makes it feel physical. A button that springs toward the
 cursor and snaps back on leave feels broken; the same button easing back over
 0.6s feels alive.
 
+**A layer that answers the pointer follows it** — on both axes, toward the
+cursor. One axis, or the opposite way, reads as resistance: in blind judging, a
+card that followed beat one that drifted away every time. Depth comes from how
+*far* each layer follows, not which way.
+
 ## The rule: `quickTo`, not a tween per event
 
 ```ts
@@ -168,6 +173,8 @@ Cheap, and the styling stays in CSS where it can follow the theme.
 - Never destroy the focus ring with a transform that moves the element out from
   under it.
 - Gate hover effects on `(hover: hover)`. On touch, `:hover` sticks after a tap.
+  Input is its own axis, read in one `gsap.matchMedia` with layout and motion —
+  see [devices.md](devices.md).
 - Under `prefers-reduced-motion: reduce`, keep the state change and drop the
   travel — see [accessibility.md](accessibility.md).
 
@@ -180,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/motion-design.md

@@ -142,11 +142,10 @@ Before calling an animation done:
 - Does it say one of the five things at the top of this file?
 - Is the rhythm intentional, or are the delays arbitrary?
 - Does anything looping use `ease: "none"`?
+- Does an ambient loop move only decoration, never the copy being read?
 - Is the seam of the loop invisible?
 - Do entrances use `out` easing and exits `in`?
 - Does one element carry the emphasis, rather than all of them?
 - Does it still read at 400px wide, and on a touch device with no hover?
 - Does the reduced-motion branch still communicate the same thing?
-- Is everything reverted on unmount?
-- Is every plugin justified, and would a transform have done it?
 - Watch it five times. Does anything start to irritate?

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,