@mehshekari/gsap-motion 3.1.1 → 3.3.0

package/skill/reference/devices.md

@@ -0,0 +1,110 @@
+# Devices
+
+A width breakpoint is not a device. A 1024px window can be a phone in landscape,
+a tablet with a keyboard, or a desktop browser scaled to half the screen, and
+"mobile" has stood in for all three for so long that most animation ships one
+guess about which it is.
+
+Read three axes instead. They are independent, and each answers a different
+question.
+
+| Axis | Question | Read from |
+|---|---|---|
+| Layout | How much room is there? | the viewport, in `matchMedia` |
+| Input | Can the visitor hover, and how precise are they? | `(hover: hover)`, `(pointer: fine)` |
+| Motion tier | How much motion should run, and can this device run it? | `prefers-reduced-motion`, then capability |
+
+```ts
+const mm = gsap.matchMedia();
+
+mm.add(
+  {
+    wide: "(min-width: 48em)",
+    hoverable: "(hover: hover) and (pointer: fine)",
+    motion: "(prefers-reduced-motion: no-preference)",
+  },
+  (context) => {
+    const { wide, hoverable, motion } = context.conditions;
+    // …one branch, three facts
+  },
+);
+```
+
+`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.
+
+## The device changes the technique, never the story
+
+A scene says something — this section arrived, that item is now first, the page
+is loading. That does not change with the screen. What changes is how much
+motion is spent saying it.
+
+So each beat has three versions, and the beat decides which parts of itself are
+device-sensitive:
+
+- **Full** — the designed version.
+- **Light** — the same meaning, less work: a shorter travel, no blur, fewer
+  elements moving, a stagger that runs as one group.
+- **Static** — the end state, set. Still says *what* happened, with no travel.
+
+Only branch the techniques that actually depend on the device. A fade is a fade
+everywhere; a magnetic cursor is not. Writing three whole timelines where one
+beat differs is how a page ends up with two motion languages and one of them
+untested.
+
+## Start safe, then enhance
+
+Begin from the version that works everywhere — the light one — and add to it
+when an axis says there is room. The opposite order ships the expensive version
+to the device least able to run it and then tries to claw it back.
+
+If you measure capability at run time, **downgrade once**. A scene that keeps
+sampling frame rate and flipping between versions spends its budget on the
+flipping, and the visitor sees the page change its mind. Decide early, once, and
+stay there.
+
+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.
+
+## Where to read each axis
+
+`prefers-reduced-motion`, `hover` and `pointer` are media queries, so
+`gsap.matchMedia` is the one place to read them — inside the animation's own
+context, where its cleanup already is.
+
+The trap is reading them during render. A server has no viewport and no pointer,
+so anything that branches on them before mount is a hydration mismatch waiting
+to happen. Each adapter says where its own safe point is:
+
+- **React and Next** — in the `useGSAP` body, never in render. See
+  [react.md](../adapter/react.md).
+- **Vue and Nuxt** — in `onMounted`. See [vue.md](../adapter/vue.md).
+- **Svelte** — in `$effect` or `onMount`. See [svelte.md](../adapter/svelte.md).
+- **Astro** — in the component script, which is already browser-only. See
+  [astro.md](../adapter/astro.md).
+- **Vanilla** — wherever you mount. See [vanilla.md](../adapter/vanilla.md).
+
+## What each axis is allowed to change
+
+| Axis | Changes | Does not change |
+|---|---|---|
+| Layout | travel distance, stagger shape, which elements move, pinning | what the scene says |
+| Input | hover effects, cursors, magnetic pulls, drag affordances | entrance and scroll behaviour |
+| Motion tier | travel, loops, parallax, blur and shadow work | the end state the visitor is left in |
+
+A hover effect with no input branch is the common failure: a tap on a touch
+device fires `mouseenter`, nothing fires the leave, and the effect sticks. The
+audit reports that as `ungated-hover`.
+
+## Reduced motion is a tier, not an off switch
+
+The static version still communicates. It sets the end state, keeps the
+hierarchy the motion was carrying — by order, weight or a very short fade — and
+drops travel, loops and parallax. An empty branch is a page that looks broken to
+the people who asked for less motion.
+
+See [accessibility.md](accessibility.md) for what "reduced" means in practice,
+and [performance.md](performance.md) for measuring a tier rather than guessing
+it.

package/skill/reference/interaction.md

@@ -1,183 +1,183 @@
-# Interaction
-
-Pointer-driven motion. The engineering constraint is that these fire at 60–120Hz,
-so the wrong architecture costs a frame budget rather than a few milliseconds.
-
-Every interaction has three parts, and the third is the one people skip:
-
-```text
-input → response → recovery
-```
-
-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.
-
-## The rule: `quickTo`, not a tween per event
-
-```ts
-// Wrong — allocates a tween per pointer event, and they fight each other
-onMouseMove = (e) => gsap.to(el, { x: e.clientX, duration: 0.5 });
-
-// Right — one tween, retargeted
-const moveX = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
-const moveY = gsap.quickTo(el, "y", { duration: 0.5, ease: "power3" });
-onMouseMove = (e) => { moveX(e.clientX); moveY(e.clientY); };
-```
-
-Create the `quickTo` functions once, inside the `useGSAP` body. This is the
-single most important performance decision in pointer work.
-
-## Magnetic element
-
-The element leans toward the cursor while it is near, and returns when it
-leaves.
-
-```ts
-const xTo = gsap.quickTo(el, "x", { duration: 0.6, ease: "power3" });
-const yTo = gsap.quickTo(el, "y", { duration: 0.6, ease: "power3" });
-
-const onMove = (e: PointerEvent) => {
-  const r = el.getBoundingClientRect();
-  xTo((e.clientX - (r.left + r.width / 2)) * 0.35);
-  yTo((e.clientY - (r.top + r.height / 2)) * 0.35);
-};
-
-const onLeave = () => { xTo(0); yTo(0); };
-```
-
-- **Strength 0.2–0.4.** Above that the element outruns the cursor and feels
-  unmoored.
-- **Measure in the handler, not once.** Scroll and layout change the rect. If
-  that shows up as cost, cache it on enter and invalidate on scroll.
-- **The hit area should be larger than the element** — a padded wrapper listens,
-  the inner element moves. That is what makes the pull feel like a field rather
-  than a hover state.
-
-## Cursor follower
-
-```ts
-const xTo = gsap.quickTo(dot, "x", { duration: 0.35, ease: "power3" });
-const yTo = gsap.quickTo(dot, "y", { duration: 0.35, ease: "power3" });
-
-window.addEventListener("pointermove", (e) => { xTo(e.clientX); yTo(e.clientY); });
-```
-
-- Two layers at different durations (0.1 and 0.5) give the trailing-ring look
-  without a trail of elements.
-- `pointer-events: none` on the follower, always.
-- **Only on devices that have a cursor.** Gate on
-  `(hover: hover) and (pointer: fine)` — a follower on a touch device is dead
-  weight and sits in the corner.
-- Hiding the native cursor is a real accessibility cost. Do it only if the
-  replacement is at least as legible over every surface, and never over text
-  inputs.
-
-## Observer
-
-One unified handler for wheel, touch, and pointer — the right tool when you want
-a gesture rather than a scroll position.
-
-```ts
-import { Observer } from "gsap/Observer";
-gsap.registerPlugin(Observer);
-
-const obs = Observer.create({
-  target: window,
-  type: "wheel,touch,pointer",
-  onUp: () => next(),
-  onDown: () => prev(),
-  tolerance: 10,
-  preventDefault: true,
-});
-
-obs.kill();   // only needed outside a useGSAP body — see react-nextjs.md
-```
-
-This is how full-screen section-snapping and swipe carousels are built without
-ScrollTrigger. `preventDefault: true` takes over native scrolling — a large
-commitment, and it must not trap a keyboard or screen-reader user.
-
-## Draggable and Inertia
-
-```ts
-import { Draggable } from "gsap/Draggable";
-import { InertiaPlugin } from "gsap/InertiaPlugin";
-gsap.registerPlugin(Draggable, InertiaPlugin);
-
-Draggable.create(el, {
-  type: "x",
-  bounds: container,
-  inertia: true,
-  snap: { x: (v) => Math.round(v / 320) * 320 },
-  onDragEnd() { /* ... */ },
-});
-```
-
-`inertia: true` gives the flick-and-settle that makes a drag feel native.
-`Draggable.create` returns instances — `.kill()` them on unmount.
-
-Anything draggable needs a keyboard path to the same outcome. A carousel that
-only responds to drag is unusable without a pointer.
-
-## Hover with a timeline
-
-Build once, play and reverse. Better than creating tweens per event, and the
-return matches the arrival for free.
-
-```ts
-const hover = gsap.timeline({ paused: true })
-  .to(el, { scale: 1.04, duration: 0.3, ease: "power2.out" })
-  .to(label, { y: -2, duration: 0.3 }, "<");
-
-onEnter = () => hover.play();
-onLeave = () => hover.reverse();
-```
-
-In React, if the timeline is built inside `useGSAP` and only *played* from the
-handler, no `contextSafe` is needed — see [react-nextjs.md](react-nextjs.md).
-
-## `overwrite: "auto"`
-
-The classic bug: enter, leave, enter fast, and the element sits halfway.
-Whatever retriggers needs `overwrite: "auto"` so the conflicting tween is killed
-rather than blended.
-
-## Spotlight
-
-A pointer-tracked gradient. Drive CSS variables rather than re-rendering:
-
-```ts
-const setX = gsap.quickSetter(card, "--spot-x", "px");
-const setY = gsap.quickSetter(card, "--spot-y", "px");
-```
-
-```css
-background: radial-gradient(
-  240px at var(--spot-x) var(--spot-y),
-  var(--glow), transparent 70%
-);
-```
-
-Cheap, and the styling stays in CSS where it can follow the theme.
-
-## Accessibility
-
-- **Everything reachable by pointer must be reachable by keyboard.** Hover state
-  and focus state should be the same visual.
-- 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.
-- Under `prefers-reduced-motion: reduce`, keep the state change and drop the
-  travel — see [accessibility.md](accessibility.md).
-
-## Failures
-
-| Symptom | Cause |
-|---|---|
-| Janky on move | a tween per event, or React state in the handler |
-| Element sticks halfway | missing `overwrite: "auto"` |
-| 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 |
-| Effects survive navigation | `Observer`/`Draggable` not killed, listeners not removed |
+# Interaction
+
+Pointer-driven motion. The engineering constraint is that these fire at 60–120Hz,
+so the wrong architecture costs a frame budget rather than a few milliseconds.
+
+Every interaction has three parts, and the third is the one people skip:
+
+```text
+input → response → recovery
+```
+
+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.
+
+## The rule: `quickTo`, not a tween per event
+
+```ts
+// Wrong — allocates a tween per pointer event, and they fight each other
+onMouseMove = (e) => gsap.to(el, { x: e.clientX, duration: 0.5 });
+
+// Right — one tween, retargeted
+const moveX = gsap.quickTo(el, "x", { duration: 0.5, ease: "power3" });
+const moveY = gsap.quickTo(el, "y", { duration: 0.5, ease: "power3" });
+onMouseMove = (e) => { moveX(e.clientX); moveY(e.clientY); };
+```
+
+Create the `quickTo` functions once, inside the `useGSAP` body. This is the
+single most important performance decision in pointer work.
+
+## Magnetic element
+
+The element leans toward the cursor while it is near, and returns when it
+leaves.
+
+```ts
+const xTo = gsap.quickTo(el, "x", { duration: 0.6, ease: "power3" });
+const yTo = gsap.quickTo(el, "y", { duration: 0.6, ease: "power3" });
+
+const onMove = (e: PointerEvent) => {
+  const r = el.getBoundingClientRect();
+  xTo((e.clientX - (r.left + r.width / 2)) * 0.35);
+  yTo((e.clientY - (r.top + r.height / 2)) * 0.35);
+};
+
+const onLeave = () => { xTo(0); yTo(0); };
+```
+
+- **Strength 0.2–0.4.** Above that the element outruns the cursor and feels
+  unmoored.
+- **Measure in the handler, not once.** Scroll and layout change the rect. If
+  that shows up as cost, cache it on enter and invalidate on scroll.
+- **The hit area should be larger than the element** — a padded wrapper listens,
+  the inner element moves. That is what makes the pull feel like a field rather
+  than a hover state.
+
+## Cursor follower
+
+```ts
+const xTo = gsap.quickTo(dot, "x", { duration: 0.35, ease: "power3" });
+const yTo = gsap.quickTo(dot, "y", { duration: 0.35, ease: "power3" });
+
+window.addEventListener("pointermove", (e) => { xTo(e.clientX); yTo(e.clientY); });
+```
+
+- Two layers at different durations (0.1 and 0.5) give the trailing-ring look
+  without a trail of elements.
+- `pointer-events: none` on the follower, always.
+- **Only on devices that have a cursor.** Gate on
+  `(hover: hover) and (pointer: fine)` — a follower on a touch device is dead
+  weight and sits in the corner.
+- Hiding the native cursor is a real accessibility cost. Do it only if the
+  replacement is at least as legible over every surface, and never over text
+  inputs.
+
+## Observer
+
+One unified handler for wheel, touch, and pointer — the right tool when you want
+a gesture rather than a scroll position.
+
+```ts
+import { Observer } from "gsap/Observer";
+gsap.registerPlugin(Observer);
+
+const obs = Observer.create({
+  target: window,
+  type: "wheel,touch,pointer",
+  onUp: () => next(),
+  onDown: () => prev(),
+  tolerance: 10,
+  preventDefault: true,
+});
+
+obs.kill();   // only needed outside a useGSAP body — see adapter/react.md
+```
+
+This is how full-screen section-snapping and swipe carousels are built without
+ScrollTrigger. `preventDefault: true` takes over native scrolling — a large
+commitment, and it must not trap a keyboard or screen-reader user.
+
+## Draggable and Inertia
+
+```ts
+import { Draggable } from "gsap/Draggable";
+import { InertiaPlugin } from "gsap/InertiaPlugin";
+gsap.registerPlugin(Draggable, InertiaPlugin);
+
+Draggable.create(el, {
+  type: "x",
+  bounds: container,
+  inertia: true,
+  snap: { x: (v) => Math.round(v / 320) * 320 },
+  onDragEnd() { /* ... */ },
+});
+```
+
+`inertia: true` gives the flick-and-settle that makes a drag feel native.
+`Draggable.create` returns instances — `.kill()` them on unmount.
+
+Anything draggable needs a keyboard path to the same outcome. A carousel that
+only responds to drag is unusable without a pointer.
+
+## Hover with a timeline
+
+Build once, play and reverse. Better than creating tweens per event, and the
+return matches the arrival for free.
+
+```ts
+const hover = gsap.timeline({ paused: true })
+  .to(el, { scale: 1.04, duration: 0.3, ease: "power2.out" })
+  .to(label, { y: -2, duration: 0.3 }, "<");
+
+onEnter = () => hover.play();
+onLeave = () => hover.reverse();
+```
+
+In React, if the timeline is built inside `useGSAP` and only *played* from the
+handler, no `contextSafe` is needed — see [react.md](../adapter/react.md).
+
+## `overwrite: "auto"`
+
+The classic bug: enter, leave, enter fast, and the element sits halfway.
+Whatever retriggers needs `overwrite: "auto"` so the conflicting tween is killed
+rather than blended.
+
+## Spotlight
+
+A pointer-tracked gradient. Drive CSS variables rather than re-rendering:
+
+```ts
+const setX = gsap.quickSetter(card, "--spot-x", "px");
+const setY = gsap.quickSetter(card, "--spot-y", "px");
+```
+
+```css
+background: radial-gradient(
+  240px at var(--spot-x) var(--spot-y),
+  var(--glow), transparent 70%
+);
+```
+
+Cheap, and the styling stays in CSS where it can follow the theme.
+
+## Accessibility
+
+- **Everything reachable by pointer must be reachable by keyboard.** Hover state
+  and focus state should be the same visual.
+- 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.
+- Under `prefers-reduced-motion: reduce`, keep the state change and drop the
+  travel — see [accessibility.md](accessibility.md).
+
+## Failures
+
+| Symptom | Cause |
+|---|---|
+| Janky on move | a tween per event, or React state in the handler |
+| Element sticks halfway | missing `overwrite: "auto"` |
+| 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 |
+| Effects survive navigation | `Observer`/`Draggable` not killed, listeners not removed |

package/skill/reference/motion-design.md

@@ -86,8 +86,8 @@ radiating, start-to-end reads as reading order. In RTL, "reading order" is
 
 ## Overlap
 
-Sequential beats look like a slideshow. Real choreography overlaps, and the
-overlap is where an animation stops feeling like a list of steps.
+Sequential beats look like a slideshow. Overlap is where an animation stops
+feeling like a list of steps.
 
 ```ts
 tl.to(a, { ... })
@@ -105,15 +105,18 @@ finishing.
 - **Weight** — a large or heavy-looking element should move slower and ease
   harder than a small one. Same duration on a hero image and a caption reads as
   a bug.
-- **Anticipation** — a small counter-move before the main one. Costs 80–120ms
-  and makes a gesture feel intentional. Use on one element, not a group.
+- **Anticipation** — a small counter-move before the main one: 80–120ms, on one
+  element, not a group.
 - **Follow-through** — elements should not all stop at once. A 0.05s offset on
-  the last beat is usually the difference between mechanical and alive.
+  the last beat is the difference between mechanical and alive.
 - **Contrast** — fast against slow is what creates emphasis. If everything moves
   at 400ms, nothing is emphasised.
 - **Restraint** — the most premium-feeling motion is usually one or two things
   moving well, not six things moving at all.
 
+Technique is chosen on a ladder — transition, tween, timeline, plugin, scroll
+takeover — in [routing.md](routing.md).
+
 ## Reading a request
 
 | They say | They usually mean |

package/skill/reference/project-rules.md

@@ -17,6 +17,18 @@ Before writing code, look for the project's animation rules, in this order:
 Read the whole file. Where it disagrees with this skill, the project wins. If a
 project rule looks wrong, say so — do not quietly follow the skill instead.
 
+## A motion budget
+
+A page gets busy one reasonable addition at a time. A budget makes the cost
+visible before the tenth one lands: how many groups may move at once, how many
+loops may be visible, how many scroll-bound and pointer effects a viewport
+carries, and which plugins a route may load.
+
+Going over is allowed — with a reason stated in the answer, not by accident.
+Before adding to a route, inventory what it already animates: that is step 2 of
+the pipeline, and it is also how you find the animation this one should replace
+rather than join.
+
 ## Deriving them when there is no file
 
 A few minutes here is cheaper than a page with two motion languages.
@@ -62,6 +74,10 @@ one is short, and each section is an instruction rather than an essay:
 | Stagger | `amount` (a total) or `each` (per item) |
 | Reduced motion | what the reduced branch shows |
 
+## Motion budget
+<!-- Per viewport: groups moving at once, visible loops, scroll-bound effects,
+     pointer effects. Plugins per route. Going over is allowed, with a reason. -->
+
 ## Verify with
 <!-- The commands to run before calling it done. -->
 

package/skill/reference/refine.md

@@ -0,0 +1,84 @@
+# Refining
+
+Writing the animation is the first draft. This is what turns it into something
+worth shipping, and it is mostly checking rather than writing.
+
+```text
+generate → audit → fix → re-run every check → tune → final
+```
+
+The loop matters because the failures this skill exists to catch are silent: the
+code compiles, the page looks right in a demo, and the leak shows up three
+navigations later. Nothing downstream will tell you. So the check is part of
+writing, not something done afterwards if there is time.
+
+## Audit first, and mean it
+
+Run `audit-gsap` on the file you just wrote, before reading it yourself. It
+costs a second, it is deterministic, and it finds the mechanical failures so
+your attention goes to the ones it cannot see.
+
+With the plugin installed, a hook does this automatically after every edit and
+hands the findings back — see the Tools section of SKILL.md. Without it, run the
+script.
+
+A finding you believe is wrong is a bug in the script. Report it; do not work
+around it with a waiver.
+
+## Fix in this order
+
+The order is not taste. A fix further down the list can be undone by a fix
+further up it, so doing them in this order avoids fixing the same thing twice.
+
+1. **Lifecycle and correctness** — does it clean up, does it run once, does it
+   target what you think it targets.
+2. **Accessibility** — the reduced-motion design, focus order, anything the
+   motion hides from a keyboard.
+3. **Performance** — layout and paint properties, per-frame allocation, work
+   that scales with the number of items.
+4. **Composition** — beats, hierarchy, what happens at the same time.
+5. **Rhythm** — durations, eases, overlap. Last, because everything above
+   changes it.
+
+## Verify a claim before you fix
+
+When a fix rests on a claim about how something behaves — "`clearProps` runs
+after the plugin's last write", "this element is the one that moves under
+`fill`" — check it before writing the fix. A minimal reproduction, one variable
+at a time, and read what actually happened in the DOM.
+
+A fix built on a guess usually works by accident, and the comment above it is
+then wrong for everyone who reads it next.
+
+## When to stop
+
+Stop when every check is clean, or after **three rounds**, reporting what is
+left.
+
+Three is not a budget to spend. Most changes are right after one. Stopping on a
+number matters for the case where a fix keeps moving the problem: the third
+round is where you say what is still wrong and why, rather than trying a fourth
+shape of the same idea.
+
+**Leave what works alone.** The loop is for the animation you were asked about.
+Retiming a neighbouring section because you noticed it is churn: it costs review
+attention, it risks a regression nobody asked for, and it is exactly what the
+`outcome-no-churn` eval measures.
+
+**Depth scales with the request.** A hover retime does not need a composition
+pass. A site intro does.
+
+## Report what you checked
+
+The answer's **Verification** section is one line per check, with its evidence:
+
+```text
+Verification
+- audit-gsap: clean (3 warns waived: layout-property on the grid, with reasons)
+- reduced motion: emulated, the static branch sets the end state
+- StrictMode: mounted twice in dev, no doubled tweens
+- not checked: frame cost on a real phone — no device to hand
+```
+
+Say what you did not check, too. "Not checked" is information; silence reads as
+"checked and fine", and that is the one thing it must never mean.