motionary 0.0.0-stage → 6.2.0

package/docs/presets.md

@@ -0,0 +1,310 @@
+# Presets
+
+`motionary` ships **214 scroll-reveal presets**: 33 in the core (always available) and **181 extended presets** added in 6.1 ("Scroll presets 2.0").
+
+```js
+import ScrollAnimate from 'motionary';
+import 'motionary/presets/extended'; // registers the extended set (≈ 4 kB gzip, separate entry)
+
+ScrollAnimate.observe('.card', { animation: 'bounce-in-up', duration: 900 });
+```
+
+```html
+<!-- No build: the UMD core, then the extended set (registers itself) -->
+<script src="https://unpkg.com/motionary@6/dist/index.umd.js"></script>
+<script src="https://unpkg.com/motionary@6/dist/presets-extended.umd.js"></script>
+<div data-sa data-sa-animation="clip-diamond">…</div>
+<script>ScrollAnimate.default.init();</script>
+```
+
+Every preset works everywhere a preset name is accepted: `animation` / `exit` options, `data-sa-animation`, the framework hooks (`useScrollAnimate`, `use:scrollAnimate`, …), `<scroll-animate animation="…">`, and `<usa-reveal effect="…">` / `<usa-stagger effect="…">` (any registered preset name that is not one of their own effects).
+
+All presets animate only `transform`, `opacity`, `filter` and `clip-path` (plus a constant `transform-origin`), and are skipped entirely under `prefers-reduced-motion: reduce` (the element is simply shown). Presets marked **keyframes** use intermediate `frames` (overshoot, bounce, glitch); they play as written and are ignored when presets are combined in an array.
+
+**Scroll-linked (`scrub-*`)** presets are designed for the native engine across the whole crossing: `{ engine: 'css', viewRange: ['cover 0%', 'cover 100%'] }` (`data-sa-engine="css" data-sa-view-range="cover 0%, cover 100%"`). Played as a one-shot reveal they end on their last frame (e.g. `scrub-fade-through` ends transparent).
+
+**Stagger-ready (`stagger-*`)** presets use small distances that stay calm across long lists: `staggerChildren(list, { animation: 'stagger-pop', stagger: 60 })`.
+
+## Fade (19)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `fade-in` | core | The quiet classic: content simply fades into view. |
+| `fade-in-up` | core | Rises 40px while fading in. The library default. |
+| `fade-in-down` | core | Drops in from above while fading in. |
+| `fade-in-left` | core | Glides in from the left. |
+| `fade-in-right` | core | Glides in from the right. |
+| `fade-in-up-sm` | extended | Rises a subtle 16px — calm body copy. |
+| `fade-in-down-sm` | extended | Settles down 16px. |
+| `fade-in-left-sm` | extended | Nudges in 16px from the left. |
+| `fade-in-right-sm` | extended | Nudges in 16px from the right. |
+| `fade-in-up-lg` | extended | A long 120px rise for hero blocks. |
+| `fade-in-down-lg` | extended | Drops 120px from above. |
+| `fade-in-left-lg` | extended | Travels 120px in from the left. |
+| `fade-in-right-lg` | extended | Travels 120px in from the right. |
+| `fade-in-up-left` | extended | Glides in diagonally (-40px, +40px). |
+| `fade-in-up-right` | extended | Glides in diagonally (+40px, +40px). |
+| `fade-in-down-left` | extended | Glides in diagonally (-40px, -40px). |
+| `fade-in-down-right` | extended | Glides in diagonally (+40px, -40px). |
+| `fade-in-scale` | extended | Rises 20px from 95% — the "card appears" default. |
+| `fade-in-half` | extended | Starts half visible — for content that should never vanish. |
+
+## Zoom & scale (23)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `zoom-in` | core | Grows from 80% to full size. |
+| `zoom-out` | core | Settles down from 120%. |
+| `scale-up` | core | Pops up from half size — great with spring easing. |
+| `scale-x` | core | Unrolls horizontally — ideal for dividers and bars. |
+| `scale-y` | core | Unrolls vertically. |
+| `zoom-in-up` | extended | Grows from 60% while rising 60px. |
+| `zoom-in-down` | extended | Grows from 60% while dropping in. |
+| `zoom-in-left` | extended | Grows in from the left. |
+| `zoom-in-right` | extended | Grows in from the right. |
+| `zoom-out-up` | extended | Shrinks from 140% while rising. |
+| `zoom-out-down` | extended | Shrinks from 140% while dropping in. |
+| `zoom-out-left` | extended | Shrinks in from the left. |
+| `zoom-out-right` | extended | Shrinks in from the right. |
+| `zoom-in-big` | extended | Grows all the way from nothing. |
+| `zoom-out-big` | extended | Lands from double size, like a stamp. |
+| `zoom-bounce` | extended · keyframes | Overshoots to 110%, dips, settles. |
+| `zoom-in-rotate` | extended | Grows from 50% while untwisting 30°. |
+| `scale-x-left` | extended | Unrolls left → right — underlines, bars. |
+| `scale-x-right` | extended | Unrolls right → left. |
+| `scale-y-top` | extended | Unrolls downwards like a blind. |
+| `scale-y-bottom` | extended | Grows upwards — chart bars. |
+| `stretch-x` | extended | Snaps back from a wide, flat stretch. |
+| `stretch-y` | extended | Snaps back from a tall, thin stretch. |
+
+## Flip 3D (22)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `flip-x` | core | Flips in around the X axis. |
+| `flip-y` | core | Flips in around the Y axis, like a card. |
+| `flip-up` | core | Tilts up into place with perspective. |
+| `flip-down` | core | Tilts down into place with perspective. |
+| `flip-x-reverse` | extended | Flips in around X from the other side. |
+| `flip-y-reverse` | extended | Flips in around Y from the other side. |
+| `flip-y-full` | extended | A full 180° card turn into place. |
+| `flip-diagonal` | extended | Turns in around the ↘ diagonal. |
+| `flip-diagonal-reverse` | extended | Turns in around the ↗ diagonal. |
+| `flip-left` | extended | Hinged on the left edge, swings open toward you. |
+| `flip-right` | extended | Hinged on the right edge. |
+| `unfold-down` | extended | Unfolds from the top edge like a letter. |
+| `unfold-up` | extended | Unfolds upwards from the bottom edge. |
+| `door-open-left` | extended | A door swinging open on left hinges — no fade. |
+| `door-open-right` | extended | A door swinging open on right hinges. |
+| `fold-in` | extended | Unfolds from a flat, tilted strip. |
+| `flip-x-bounce` | extended · keyframes | Flips in around X, overshoots and rocks to rest. |
+| `flip-y-bounce` | extended · keyframes | Flips in around Y, overshoots and rocks to rest. |
+| `swing-in-top` | extended · keyframes | Swings down from the top edge, then sways. |
+| `swing-in-bottom` | extended · keyframes | Swings up from the bottom edge. |
+| `swing-in-left` | extended · keyframes | Swings in on the left edge. |
+| `swing-in-right` | extended · keyframes | Swings in on the right edge. |
+
+## Slide (20)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `slide-up` | core | Slides a full height up, no fade — pair with overflow: hidden. |
+| `slide-down` | core | Slides a full height down. |
+| `slide-left` | core | Slides a full width in from the left. |
+| `slide-right` | core | Slides a full width in from the right. |
+| `slide-up-spring` | extended · keyframes | Slides a full height up, overshoots 8%, settles. |
+| `slide-down-spring` | extended · keyframes | Slides down with a small overshoot. |
+| `slide-left-spring` | extended · keyframes | Slides in from the left and springs back. |
+| `slide-right-spring` | extended · keyframes | Slides in from the right and springs back. |
+| `slide-up-sm` | extended | Slides 30% of its height — no fade. |
+| `slide-down-sm` | extended | Slides 30% of its height — no fade. |
+| `back-in-up` | extended · keyframes | Arrives small from below, then scales to full size. |
+| `back-in-down` | extended · keyframes | Arrives small from above, then scales up. |
+| `back-in-left` | extended · keyframes | Arrives small from the left, then scales up. |
+| `back-in-right` | extended · keyframes | Arrives small from the right, then scales up. |
+| `light-speed-in-left` | extended · keyframes | Streaks in skewed, brakes hard and straightens. |
+| `light-speed-in-right` | extended · keyframes | Streaks in skewed, brakes hard and straightens. |
+| `rise-in` | extended | Rises 80px from slightly smaller — weightless. |
+| `sink-in` | extended | Sinks 80px into place from slightly larger. |
+| `float-in-up` | extended · keyframes | Drifts up with a slight tilt, like a leaf in reverse. |
+| `float-in-down` | extended · keyframes | Drifts down and rocks gently to rest. |
+
+## Rotate & skew (20)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `rotate-in` | core | Spins half a turn while growing in. |
+| `rotate-left` | core | Swings in from the left with a slight tilt. |
+| `rotate-right` | core | Swings in from the right with a slight tilt. |
+| `skew-in` | core | Straightens out of a 20° skew. |
+| `roll-in-left` | extended | Rolls in from the left like a wheel. |
+| `roll-in-right` | extended | Rolls in from the right. |
+| `spiral-in` | extended | One and a half turns while growing from a point. |
+| `spiral-in-reverse` | extended | Spirals in clockwise. |
+| `spin-in` | extended | A full turn while fading in — no scaling. |
+| `rotate-in-up-left` | extended | Pivots 45° around its left-bottom corner. |
+| `rotate-in-up-right` | extended | Pivots 45° around its right-bottom corner. |
+| `rotate-in-down-left` | extended | Pivots 45° around its left-bottom corner. |
+| `rotate-in-down-right` | extended | Pivots 45° around its right-bottom corner. |
+| `skew-in-left` | extended | Straightens out of a 30° skew from the left. |
+| `skew-in-y` | extended | Rises out of a vertical 12° shear. |
+| `shear-in` | extended | Untwists from a two-axis shear. |
+| `shear-in-reverse` | extended | The mirror-image shear. |
+| `twist-in` | extended | Rotates, skews and grows at once. |
+| `tilt-in-left` | extended | Rises 30px out of an 8° tilt. |
+| `tilt-in-right` | extended | Rises out of a clockwise tilt. |
+
+## Blur & mask (14)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `blur-in` | core | Comes into focus from a 12px blur. |
+| `blur-in-up` | core | Focus pull plus a gentle rise. |
+| `blur-in-down` | extended | Focus pull while travelling 40px. |
+| `blur-in-left` | extended | Focus pull while travelling 40px. |
+| `blur-in-right` | extended | Focus pull while travelling 40px. |
+| `blur-in-strong` | extended | A heavy 24px defocus resolving. |
+| `blur-in-zoom` | extended | Settles from 120% while focusing — cinematic. |
+| `blur-in-scale` | extended | Grows from 80% while focusing. |
+| `blur-in-x` | extended | Horizontal smear that snaps into focus. |
+| `mask-up` | extended | Rises inside its own box — the classic headline reveal. |
+| `mask-down` | extended | Drops in, clipped to its own box. |
+| `mask-left` | extended | Slides left, clipped to its own box. |
+| `mask-right` | extended | Slides right, clipped to its own box. |
+| `blur-mask-up` | extended | Masked rise with a focus pull. |
+
+## Clip reveal (22)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `clip-up` | core | Uncovered from the bottom edge — nothing moves. |
+| `clip-down` | core | Uncovered from the top edge. |
+| `clip-left` | core | Uncovered from the right edge. |
+| `clip-right` | core | Uncovered from the left edge. |
+| `clip-circle` | core | An iris opening from the centre. |
+| `clip-circle-top` | extended | A circle grows from 50% 0%. |
+| `clip-circle-bottom` | extended | A circle grows from 50% 100%. |
+| `clip-circle-left` | extended | A circle grows from 0% 50%. |
+| `clip-circle-right` | extended | A circle grows from 100% 50%. |
+| `clip-circle-corner` | extended | A circle grows from 0% 0%. |
+| `clip-ellipse` | extended | An elliptical iris that follows the box shape. |
+| `clip-diamond` | extended | A diamond opening from the centre. |
+| `clip-split-x` | extended | Opens from a vertical centre line, like curtains. |
+| `clip-split-y` | extended | Opens from a horizontal centre line. |
+| `clip-box` | extended | A rectangle grows from the centre. |
+| `clip-pill` | extended | A rounded pill that squares off as it opens. |
+| `clip-blinds` | extended | Four horizontal slats open together. |
+| `clip-blinds-x` | extended | Four vertical slats open together. |
+| `clip-diagonal` | extended | Wipes in from the top-left corner. |
+| `clip-diagonal-reverse` | extended | Wipes in from the bottom-right corner. |
+| `clip-slant-right` | extended | A slanted edge sweeps left → right. |
+| `clip-slant-left` | extended | A slanted edge sweeps right → left. |
+
+## Bounce & elastic (17)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `bounce-in` | extended · keyframes | Pops from 30% with a springy wobble. |
+| `bounce-in-up` | extended · keyframes | Arrives 120px away, overshoots and bounces to rest. |
+| `bounce-in-down` | extended · keyframes | Arrives 120px away, overshoots and bounces to rest. |
+| `bounce-in-left` | extended · keyframes | Arrives 120px away, overshoots and bounces to rest. |
+| `bounce-in-right` | extended · keyframes | Arrives 120px away, overshoots and bounces to rest. |
+| `elastic-in` | extended · keyframes | Springs from zero to 120% and rings out. |
+| `elastic-in-x` | extended · keyframes | Stretches out horizontally and twangs to rest. |
+| `rubber-in` | extended · keyframes | Squashes and stretches like a rubber band. |
+| `jello-in` | extended · keyframes | Wobbles in like jelly on a plate. |
+| `wobble-in` | extended · keyframes | Wobbles side to side before standing still. |
+| `tada-in` | extended · keyframes | Grows with a celebratory shimmy. |
+| `heartbeat-in` | extended · keyframes | Two beats, then rest — great for likes and badges. |
+| `drop-in` | extended · keyframes | Falls 150px and bounces on the floor. |
+| `pop-in` | extended · keyframes | A quick pop past 112% — snappy UI feedback. |
+| `squash-in` | extended · keyframes | Lands with cartoon squash and stretch. |
+| `shake-in` | extended · keyframes | Arrives with a damped horizontal shake. |
+| `swing-in` | extended · keyframes | Hangs from the top and swings to rest. |
+
+## Color & light (14)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `brightness-in` | extended | Fades in from an overexposed flash. |
+| `darken-in` | extended | Lights up out of black — no fade. |
+| `color-in` | extended | Black & white blooms into colour. |
+| `saturate-in` | extended | Oversaturated colour settles to normal. |
+| `hue-in` | extended | Colours spin half the wheel into place. |
+| `sepia-in` | extended | An old photo developing into the present. |
+| `invert-in` | extended | A negative that develops into the positive. |
+| `contrast-in` | extended | Emerges from flat grey. |
+| `exposure-in` | extended | Blown-out highlights pulled back. |
+| `vintage-in` | extended | Soft, warm film look sharpening up. |
+| `blur-bright-in` | extended | A glowing blur resolving. |
+| `shadow-lift` | extended | Lifts off the page and casts a soft shadow. |
+| `neon-glow-in` | extended · keyframes | Flares up in violet neon and keeps a soft glow. |
+| `glow-in` | extended | Arrives wrapped in white light that fades away. |
+
+## Depth & perspective (10)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `perspective-in-up` | extended | Tilts up out of the floor plane. |
+| `perspective-in-down` | extended | Tilts down from the ceiling plane. |
+| `perspective-in-left` | extended | Swings in from a left-hand wall. |
+| `perspective-in-right` | extended | Swings in from a right-hand wall. |
+| `depth-push` | extended | Flies back from in front of the screen. |
+| `depth-pull` | extended | Approaches from deep in the scene. |
+| `depth-in-up` | extended | Rises up out of the depths. |
+| `swoop-in-left` | extended | Swoops around from behind on the left. |
+| `swoop-in-right` | extended | Swoops around from behind on the right. |
+| `card-tilt-in` | extended | A product card turning to face you. |
+
+## Glitch & special (9)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `glitch-in` | extended · keyframes | Tears in with jittering slices, then locks. |
+| `glitch-in-color` | extended · keyframes | Jitters through hue shifts before settling. |
+| `typewriter` | extended | Uncovered left → right in 16 hard steps — one line of text. |
+| `typewriter-lines` | extended | Uncovered top → bottom in 5 steps — a paragraph line by line. |
+| `hinge-in` | extended · keyframes | Swings up on a top-left hinge and wobbles shut. |
+| `flicker-in` | extended · keyframes | Two soft flickers, like a neon tube warming up. |
+| `scan-in` | extended · keyframes | A bright scan line passes top → bottom. |
+| `materialize` | extended | Condenses out of glowing haze. |
+| `teleport-in` | extended · keyframes | Beams in as a bright sliver, then snaps to shape. |
+
+## Attention (4)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `bounce` | core | Drops 60px — try it with heavy-bounce easing. |
+| `pulse` | core | A subtle 5% swell to draw the eye. |
+| `swing` | core | Swings from -10° to 10°. |
+| `shimmer` | core | Brightens up — good for badges and CTAs. |
+
+## Stagger-ready (8)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `stagger-fade-up` | extended | A tiny 12px rise that reads well 20 items deep. |
+| `stagger-pop` | extended | Each item pops from 85% — icon grids. |
+| `stagger-rise` | extended | Soft rise for card lists. |
+| `stagger-slide` | extended | Rows slide in from the right — menus, tables. |
+| `stagger-flip` | extended | Items flip down one after another like a departures board. |
+| `stagger-blur` | extended | Light focus pull per item. |
+| `stagger-zoom` | extended | Items settle down from 115%. |
+| `stagger-drop` | extended | Tags and chips tumble in. |
+
+## Scroll-linked (12)
+
+| Preset | Set | What it does |
+|---|---|---|
+| `scrub-parallax-up` | extended | Drifts upward faster than the page as you scroll. |
+| `scrub-parallax-down` | extended | Lags behind the page — a background layer. |
+| `scrub-rotate` | extended | Tilts from -25° to 25° as it crosses the viewport. |
+| `scrub-spin` | extended | One full turn per viewport crossing — badges, logos. |
+| `scrub-scale` | extended | Grows from 70% to 110% with scroll. |
+| `scrub-shrink` | extended | Shrinks as it scrolls past — hero images. |
+| `scrub-pan-left` | extended | Pans right → left with vertical scroll. |
+| `scrub-pan-right` | extended | Pans left → right with vertical scroll. |
+| `scrub-tilt` | extended | Pitches forward as it passes — 3D cards. |
+| `scrub-fade-through` | extended · keyframes | Fades in, holds through the middle, fades out. |
+| `scrub-blur-through` | extended · keyframes | Sharp only while centred — depth-of-field. |
+| `scrub-reveal-x` | extended | Uncovered left → right in step with scroll. |

package/docs/upgrading-3.md

@@ -0,0 +1,21 @@
+# Upgrading to 3.0
+
+3.0 removes the APIs deprecated in 2.9. Every change has a drop-in replacement; 2.9 logs a one-time console warning wherever old usage is found, so run your app on 2.9 first and fix the warnings.
+
+| Removed in 3.0 | Use instead |
+|---|---|
+| `<usa-spinner variant="windows">`, `<usa-check variant="error">`, `<usa-dialog variant="drawer-end">`, `<usa-acrylic variant="mica">` (variant = kind) | `kind="windows"`, `kind="error"`, `kind="drawer-end"`, `kind="mica"`. `variant` now only selects a style variant (`minimal`, `neon`, `glass`, `brutalist`, `fluent`, `material`). |
+| `spinner.variant` property | `spinner.kind` |
+| `observe(el, { parallax: { y: 80 } })`, `data-sa-parallax-x/-y/-rotate/-scale/-speed` | `parallax(el, { speed: 0.3 })` (writes `--sa-parallax`, use it in CSS: `transform: translateY(calc(var(--sa-parallax) * -80px))`) or `progressVar: '--p'` |
+| `ParallaxOptions` type | `ParallaxHelperOptions` |
+| `data-variant` on spinner / check / dialog (internal styling hook) | `data-kind` |
+| Node 18 for SSR imports | Node ≥ 20 (`engines`) |
+
+Search & replace:
+
+```bash
+# kinds
+grep -rlE '<usa-(spinner|check|dialog|acrylic)[^>]*variant=' src | xargs sed -i -E 's/(<usa-(spinner|check|dialog|acrylic)[^>]*)variant=/\1kind=/g'
+# legacy parallax
+grep -rn 'data-sa-parallax\|parallax:' src
+```

package/docs/upgrading-4.md

@@ -0,0 +1,65 @@
+# Upgrading to 4.0
+
+4.0 removes the three APIs that 3.9 deprecated, each replaced by a more capable one added during 3.x. **Run your app on 3.9 first**: it logs one console warning (`[use-scroll-animate] … deprecated …`) for every removed API you still use.
+
+| Removed in 4.0 | Use instead | Since |
+|---|---|---|
+| `sequence(steps, opts)` (`use-scroll-animate`) | `timeline()` — `use-scroll-animate` (re-exported in 4.0) or `use-scroll-animate/components/timeline` | 3.1 |
+| `connectedAnimation(from, to)` (`components/transitions`) | `sharedTransition(update)` with `data-shared="id"` (`components/layout`) | 3.6 |
+| `<usa-flip-list>` / `defineFlipList()` (`components/transitions`) | `<usa-auto-animate>` / `autoAnimate(el)` (`components/layout`) | 3.6 |
+
+## `sequence()` → `timeline()`
+
+```js
+// 3.x
+sequence([
+  { target: '.title', animation: 'fade-in-up' },
+  { target: '.subtitle', animation: 'blur-in', gap: -300 },
+  { target: '.card', animation: 'scale-up', stagger: 80 },
+], { trigger: '.hero' });
+
+// 4.0
+import { timeline } from 'use-scroll-animate';
+const tl = timeline({ defaults: { duration: 600 } })
+  .to('.title', 'fade-up')
+  .to('.subtitle', 'blur', { at: '-=300' })   // gap: -300  →  at: '-=300'
+  .to('.card', 'scale', { stagger: 80 });
+// trigger: '.hero'  →  play when it enters the view (or scrub it with scroll)
+new IntersectionObserver(([e], io) => e.isIntersecting && (io.disconnect(), tl.play())).observe(document.querySelector('.hero'));
+```
+
+Declaratively: wrap the section in `<usa-timeline>` and mark steps with `data-tl="fade-up"`, `data-at="-=300"`.
+
+`gap: n` → `at: '+=n'` (negative → `'-=n'`), `at: ms` stays `at: ms`. Engine presets map to timeline presets: `fade-in-up` → `fade-up`, `blur-in` → `blur`, `scale-up` → `scale`, or pass keyframes.
+
+## `connectedAnimation()` → `sharedTransition()`
+
+```js
+// 3.x
+detail.hidden = false;
+connectedAnimation(thumbnail, detail);
+
+// 4.0 — give both ends the same data-shared id
+// <img data-shared="photo-7"> in the grid and in the detail view
+import { sharedTransition } from 'use-scroll-animate/components/layout';
+await sharedTransition(() => { grid.hidden = true; detail.hidden = false; });
+```
+
+Uses the View Transitions API where available (FLIP fallback elsewhere) and morphs any number of shared elements at once.
+
+## `<usa-flip-list>` → `<usa-auto-animate>`
+
+```html
+<!-- 3.x -->
+<usa-flip-list><li>…</li></usa-flip-list>
+<!-- 4.0 -->
+<usa-auto-animate><li>…</li></usa-auto-animate>
+```
+
+`<usa-auto-animate>` also animates additions and removals, and size changes. Imperatively: `autoAnimate(ul)`.
+
+## Other changes in 4.0
+
+- `timeline` is exported from the root entry (`import { timeline } from 'use-scroll-animate'`) in addition to `components/timeline`.
+- CDN snippets in docs and the showcase use `use-scroll-animate@4`.
+- npm `latest` moves to 4.0.0. 3.x stays available as `use-scroll-animate@3`.

package/docs/upgrading-5.md

@@ -0,0 +1,31 @@
+# Upgrading to 5.0
+
+5.0.0 is released. 4.9 **warned once in the console** for everything below, and a codemod rewrites most of it:
+
+```sh
+npx usa-codemod-5 src            # dry run: lists every change
+npx usa-codemod-5 --write src    # apply
+```
+
+## Removed in 5.0 (deprecated in 4.9)
+
+| 4.x | 5.0 | Codemod |
+|---|---|---|
+| `configureComponents({ motionIntensity: 'off' })`, `setMotionIntensity('off')` | `motionSensitivity: 'minimal'` / `setMotionSensitivity('minimal')` (4.4) — intensity is `'low' \| 'normal' \| 'high'` | ✅ |
+| `configureComponents({ reducedMotion: 'no-preference' })` | removed — the OS "reduce motion" setting is always honoured; `'user'` (default) or `'reduce'` | ✅ (→ `'user'`) |
+| `<usa-timeline scrub="js">` | `scrub` — the JS engine is picked automatically where native scroll timelines are missing; `smooth="…"` opts into smoothing | ✅ (→ `scrub smooth="0.1"`) |
+| `configureComponents`, `prefersReducedMotion`, `ComponentsConfig`, `UsaElement` re-exported from every category entry (`use-scroll-animate/components/<category>`) | import them from `use-scroll-animate/components` | ✅ |
+
+`<usa-motion-switch>` keeps its **Off** button; in 5.0 it maps to sensitivity `minimal`.
+
+## Modern-browser baseline
+
+5.0 requires **Custom Elements, Web Animations, IntersectionObserver, ResizeObserver and constructable stylesheets** (`adoptedStyleSheets`) — every evergreen browser since 2023 (Chrome / Edge ≥ 111, Safari ≥ 16.4, Firefox ≥ 115, WebView2, Electron ≥ 24). The legacy `experimental-webgl` context is no longer requested, and browsers without the required features are no longer tested or supported (the remaining no-WAAPI guards only keep SSR / test environments from throwing). View Transitions and scroll-driven animations stay **progressive** (used when present, JS fallback otherwise).
+
+Check a browser with `baselineReport()` / `warnBaseline()` from `use-scroll-animate/components/a11y` (4.9).
+
+## New in 5.0
+
+- **Unified plugin-style effect registration**: `registerEffect({ name, kind, run })`, `playEffect(el, name, options)`, `<usa-fx effect="…" trigger="…">` — every built-in click / card / hover effect is registered the same way, and so are yours.
+
+See the [CHANGELOG](../CHANGELOG.md) for the full list.

package/docs/upgrading-6.md

@@ -0,0 +1,32 @@
+# Upgrading to 6.0
+
+6.0.0 is released. 5.9 **warned once in the console** for everything below, and a codemod rewrites most of it:
+
+```sh
+npx usa-codemod-6 src            # dry run: lists every change (and what needs a manual edit)
+npx usa-codemod-6 --write src    # apply
+```
+
+## Removed in 6.0 (deprecated in 5.9)
+
+6.0 finishes the move to the 5.0 effect registry: every effect is registered once and played the same way (`playEffect()`, `bindEffect()`, `<usa-fx>`). The ad-hoc helpers that bypassed it go away.
+
+| 5.x | 6.0 | Codemod |
+|---|---|---|
+| `burst(x, y, options)` from `use-scroll-animate/components` / `/components/click` | `playEffect(document.body, 'burst', { x, y, ...options })` from `use-scroll-animate/components/fx` | ✅ |
+| `confetti(options)` | `playEffect(document.body, 'confetti', options)` (`x` / `y` in the options, or play it on the element to fire from its centre) | ✅ |
+| `shake(el, intensity, duration)` | `playEffect(el, 'shake', { intensity, duration })` | ✅ |
+| `UsaComponents.burst / confetti / shake` (UMD global) | `UsaComponents.playEffect(…)` | ✅ |
+| `<usa-cursor mode="trail">` | wrap the content: `<usa-fx effect="comet-trail" trigger="load" self>…</usa-fx>` (5.7; scoped, touch-aware, overlay canvas). `mode="dot" \| "magnetic" \| "glow"` stay. | ⚠️ reported, manual |
+
+`haptic()` stays. The registered `burst` effect accepts `x` / `y` since 5.9, so the rewrite keeps the exact origin.
+
+## Behaviour
+
+- Nothing else changes in 6.0: the modern-browser baseline is the 5.0 one, every 5.1–5.9 pack keeps its API, and `<usa-player>` JSON (`format: "use-scroll-animate/animation"`, `version: 1`) stays readable.
+
+## New in 5.9 (before the break)
+
+- `<usa-player>` plays JSON animations (keyframe tracks, timeline presets, registered effects) — exported from the playground's **`<usa-player> JSON`** tab. See [components.md](./components.md#v59-usa-player).
+
+See the [CHANGELOG](../CHANGELOG.md) for the full list.

package/docs/windows-apps.md

@@ -0,0 +1,119 @@
+# Using the components in Windows desktop apps
+
+The `<usa-*>` components are plain web platform code (Custom Elements v1, CSS, Web Animations API). Any Windows app whose UI is rendered by a modern web engine can use them unchanged:
+
+| Stack | Engine on Windows | Works | Notes |
+|---|---|---|---|
+| **Electron** | Chromium (bundled) | ✅ | All features, incl. View Transitions. |
+| **Tauri 1/2** | Microsoft Edge **WebView2** (Chromium) | ✅ | Same as Edge. |
+| **WinUI 3 / WPF / WinForms + WebView2** | WebView2 | ✅ | Host a local HTML page (see below). |
+| **.NET MAUI / Blazor Hybrid** | `BlazorWebView` → WebView2 | ✅ | Register in `wwwroot/index.html`. |
+| **Installed PWA** (Edge / Chrome "Install app") | Edge / Chrome | ✅ | Runs in its own window with taskbar icon. |
+| Neutralino, Wails, Flutter `webview_windows` | WebView2 | ✅ | Any WebView2-based shell. |
+| Legacy MSHTML (`WebBrowser` control, IE11) | Trident | ❌ | No Custom Elements / WAAPI — migrate to WebView2. |
+
+Requirements: Custom Elements, `IntersectionObserver` and `Element.animate()` — every Chromium ≥ 84 (all supported Electron/WebView2 versions). `viewTransition()` uses the View Transitions API (Chromium ≥ 111) and falls back to a cross-fade.
+
+Every component respects the Windows setting **Settings → Accessibility → Visual effects → Animation effects** (exposed to web views as `prefers-reduced-motion`), and `<usa-acrylic>` turns solid when **Transparency effects** are off or a high-contrast theme is active (`prefers-reduced-transparency`, `forced-colors`).
+
+## Electron
+
+Bundle the renderer as usual (Vite, webpack, esbuild…):
+
+```js
+// renderer/main.js
+import { defineComponents, toast } from 'motionary/components';
+defineComponents();
+
+window.api?.onSaved?.(() => toast('Saved', { type: 'success' }));
+```
+
+```html
+<!-- renderer/index.html -->
+<usa-acrylic kind="mica" style="min-height:100vh">
+  <usa-view-switch active="home">
+    <section data-view="home"><usa-typewriter words="Welcome back"></usa-typewriter></section>
+    <section data-view="settings"><usa-toggle checked>Start with Windows</usa-toggle></section>
+  </usa-view-switch>
+</usa-acrylic>
+```
+
+Without a bundler, copy `node_modules/motionary/dist/components.umd.js` next to your HTML and use `<script src="components.umd.js"></script>` — no `nodeIntegration` needed, it works with `contextIsolation: true` and `sandbox: true`.
+
+**Content-Security-Policy.** Components inject styles via constructable stylesheets (`document.adoptedStyleSheets`), which are allowed by `style-src 'self'` without `'unsafe-inline'`. If you prefer files:
+
+```js
+import 'motionary/components.css';
+import { configureComponents, defineComponents } from 'motionary/components';
+configureComponents({ injectStyles: false });
+defineComponents();
+```
+
+`<usa-grain>` and `<usa-acrylic>` use `data:` SVG noise images — allow `img-src 'self' data:`.
+
+**Real Windows materials.** Electron ≥ 24 can draw real Mica / Acrylic behind a transparent window (`new BrowserWindow({ backgroundMaterial: 'mica' })`). Set the page background to transparent and use `<usa-acrylic tint-opacity="0.2">` for in-page panels on top of it.
+
+## Tauri
+
+```ts
+// src/main.ts (Vite template)
+import { defineFeedbackComponents } from 'motionary/components/feedback';
+import { defineTransitionComponents } from 'motionary/components/transitions';
+defineFeedbackComponents();
+defineTransitionComponents();
+```
+
+Nothing to configure in `tauri.conf.json`. For window-level Mica/Acrylic use Tauri's `windowEffects` (`"effects": ["mica"]`) with `"transparent": true`.
+
+## WinUI 3 / WPF / WinForms with WebView2
+
+1. Put your page and the bundle in a folder that is copied to the output, e.g. `wwwroot/index.html` and `wwwroot/components.umd.js` (from `node_modules/motionary/dist/`, or download it from unpkg).
+2. Map the folder to a virtual host and navigate to it:
+
+```csharp
+// WinUI 3 (C#)
+await MyWebView.EnsureCoreWebView2Async();
+MyWebView.CoreWebView2.SetVirtualHostNameToFolderMapping(
+    "app.local", Path.Combine(AppContext.BaseDirectory, "wwwroot"),
+    CoreWebView2HostResourceAccessKind.Allow);
+MyWebView.Source = new Uri("https://app.local/index.html");
+```
+
+```html
+<!-- wwwroot/index.html -->
+<!doctype html>
+<meta name="color-scheme" content="light dark">
+<script src="components.umd.js"></script>
+<usa-progress id="p" value="0" label="Installing"></usa-progress>
+<usa-spinner kind="fluent"></usa-spinner>
+<script>
+  // messages from C#: CoreWebView2.PostWebMessageAsJson("{\"progress\":42}")
+  chrome.webview.addEventListener('message', (e) => (p.value = e.data.progress));
+</script>
+```
+
+Talk back to the host with `chrome.webview.postMessage(...)` from component events, e.g.
+`dialog.addEventListener('usa:close', (e) => chrome.webview.postMessage({ closed: e.detail.returnValue }))`.
+
+For a transparent WebView2 over a Mica window, set `DefaultBackgroundColor` to `Transparent` and keep the page background transparent.
+
+## PWA
+
+Link the bundle (or import it in your module graph) and install the site from Edge/Chrome. Add `"display": "standalone"` (or `"window-controls-overlay"` for a custom title bar) to the manifest; the components behave exactly as on the web.
+
+## Performance checklist for desktop UIs
+
+- Register only what you use (`define<Category>Components()` or single `define*()` calls) to keep start-up light.
+- Background effects (`<usa-aurora>`, `<usa-particles>`, `<usa-marquee>`) stop animating when off-screen and when the window is hidden/minimised (`document.hidden`).
+- All motion runs on the compositor (`transform` / `opacity`), so it stays smooth on integrated GPUs and in battery-saver mode; call `configureComponents({ reducedMotion: 'reduce' })` to force the calm variants (e.g. for a "Reduce animations" toggle in your app settings).
+
+## WinUI 3 sample app + Fluent preset (v2.8)
+
+[`examples/webview2-winui/`](../examples/webview2-winui/) is a complete WinUI 3 app (Windows App SDK, native **Mica** backdrop, full-window WebView2 with `SetVirtualHostNameToFolderMapping`) whose UI is a plain `index.html` using `components.umd.js`.
+
+```js
+import { fluentPreset } from 'motionary/components/background';
+const off = fluentPreset({ reveal: true, mica: true }); // Fluent variant + Mica-style bg + Acrylic + Reveal highlight
+```
+
+`fluentPreset()` sets `variant="fluent"` page-wide (Segoe UI Variable, Windows 11 accent `#0067c0` / `#4cc2ff` dark, 8 px radii), tints the body like Mica (skip with `mica: false` when the host window already uses `MicaBackdrop`), turns `.usa-acrylic` / `[data-acrylic]` into Acrylic surfaces and adds Reveal highlight to buttons and `[data-fluent-reveal]` items. Reduced motion / reduced transparency / high contrast fall back to solid materials without Reveal tracking.