motionary 0.0.0-stage → 6.2.0

package/docs/deprecations.md

@@ -0,0 +1,30 @@
+# Deprecations
+
+## Deprecated in 5.9, removed in 6.0
+
+See [upgrading-6.md](./upgrading-6.md) — `burst()`, `confetti()`, `shake()` (use `playEffect(el, 'burst' | 'confetti' | 'shake', …)`), `<usa-cursor mode="trail">` (use the `comet-trail` effect). Run `npx usa-codemod-6 --write src`.
+
+## Deprecated in 4.9, removed in 5.0
+
+See [upgrading-5.md](./upgrading-5.md) — `motionIntensity: 'off'` / `setMotionIntensity('off')`, `reducedMotion: 'no-preference'`, `<usa-timeline scrub="js">`, shared names re-exported from category entries. Run `npx usa-codemod-5 --write src`.
+
+# Upgrading to 2.0 (removed APIs)
+
+Everything below was deprecated in 1.9 and is **removed in 2.0.0**. The full step-by-step list is the MIGRATION section of the [CHANGELOG](../CHANGELOG.md).
+
+| Removed in 2.0 | Use instead |
+|---|---|
+| `import { createReactHooks } from 'use-scroll-animate'` | `import { createReactHooks } from 'use-scroll-animate/react'` |
+| `import { createVueComposables } from 'use-scroll-animate'` | `import { createVueComposables } from 'use-scroll-animate/vue'` |
+| `module` field, `dist/index.esm.js`, `dist/index.mjs` | the `exports` map: `import` → `dist/index.js` (ESM) |
+| `dist/index.js` as CommonJS | `require('use-scroll-animate')` → `dist/index.cjs` (`main`) |
+| per-file declarations in `dist/types/*`, `dist/*.d.mts` | bundled `dist/*.d.ts` (ESM) / `dist/*.d.cts` (CJS), resolved through `exports` |
+| `use-scroll-animate/dist/*` deep imports | the named entry points (`use-scroll-animate`, `/react`, `/vue`, `/svelte`, `/solid`, `/element`) |
+
+Unchanged: the browser bundles at `dist/index.umd.js` (global `ScrollAnimate`) and `dist/element.umd.js` keep their CDN URLs (`https://unpkg.com/use-scroll-animate/dist/index.umd.js`).
+
+Behaviour changes in 2.0 (no API removed):
+
+- `engine` defaults to `'auto'`: the native scroll-driven timeline is used where `animation-timeline: view()` is supported, unless the element sets `duration`, `delay`, `offset` or `stagger` itself. `createScrollAnimate({ defaultEngine: 'js' })` (or `ScrollAnimate.configure({ defaultEngine: 'js' })`) restores the 1.x behaviour.
+- Output targets ES2020 (optional chaining / nullish coalescing are no longer down-levelled). Every browser with `Animation.commitStyles()` — which the library already relied on — supports ES2020.
+- Node ≥ 18 is declared in `engines` (only relevant for SSR imports).

package/docs/frameworks-ssr.md

@@ -0,0 +1,100 @@
+# Next.js, Astro, React, Vue — using `<usa-*>` components (v2.9)
+
+All entry points are **SSR-safe**: importing never touches `window`/`document`; `define*()` is a no-op on the server. Register on the client only.
+
+## Next.js (App Router)
+```tsx
+// app/usa-provider.tsx
+'use client';
+import { useEffect } from 'react';
+export function UsaProvider() {
+  useEffect(() => { import('motionary/components/lazy').then((m) => m.lazyDefine()); }, []);
+  return null;
+}
+// app/layout.tsx → <body><UsaProvider />{children}</body>
+```
+The raw tags render on the server as plain HTML and upgrade on hydration. Type them with `motionary/components/jsx`:
+```ts
+// usa-jsx.d.ts
+import type { UsaIntrinsicElements } from 'motionary/components/jsx';
+declare module 'react' { namespace JSX { interface IntrinsicElements extends UsaIntrinsicElements {} } }
+```
+Prefer typed wrappers (React 18 sets properties & `usa:*` events for you):
+```tsx
+'use client';
+import * as React from 'react';
+import { createUsaComponents } from 'motionary/components/react';
+export const { UsaButton, UsaToggle, UsaCard } = createUsaComponents(React);
+// <UsaToggle checked={on} onUsaChange={(e) => setOn(e.detail.checked)} />
+```
+Page transitions in the App Router: wrap `router.push` in `pageTransition(() => router.push(href), { effect: 'slide' })`.
+
+## Astro
+```astro
+---
+// src/layouts/Base.astro
+---
+<html><body>
+  <slot />
+  <script>
+    import { lazyDefine } from 'motionary/components/lazy';
+    import { enableMpaTransitions } from 'motionary/components/page';
+    lazyDefine();
+    enableMpaTransitions('fade'); // cross-page View Transitions (or use Astro's <ClientRouter />)
+  </script>
+</body></html>
+```
+Use the tags directly in `.astro`, `.md` and island components. With `<ClientRouter />` call `lazyDefine()` again on `astro:page-load`.
+
+## Vue / Nuxt
+```js
+// vite.config.js
+import { isUsaElement } from 'motionary/components/vue';
+vue({ template: { compilerOptions: { isCustomElement: isUsaElement } } });
+// main.js (or a Nuxt client plugin: plugins/usa.client.ts)
+import { UsaPlugin } from 'motionary/components/vue';
+app.use(UsaPlugin);            // or app.use(UsaPlugin, { categories: ['click', 'ui'] })
+```
+`<usa-toggle :checked.prop="on" @usa:change="on = $event.detail.checked" />`
+
+## Svelte / Solid / Angular
+Custom elements work as-is: Svelte (`on:usa:change`), Solid (`on:usa:change`, `prop:checked`), Angular (`schemas: [CUSTOM_ELEMENTS_SCHEMA]`). Call `defineComponents()` or `lazyDefine()` in the client entry.
+
+## Lazy registration
+`lazyDefine()` (from `motionary/components/lazy`) watches the DOM and dynamically imports only the categories whose tags appear — a page with just `<usa-button>` loads the click chunk only.
+
+## Svelte / SvelteKit (v3.8)
+
+```svelte
+<script>
+  import { onMount } from 'svelte';
+  import { usa, defineUsa } from 'motionary/components/svelte';
+  onMount(() => defineUsa());
+  let on = false;
+</script>
+<usa-toggle use:usa={{ props: { checked: on }, on: { change: (e) => (on = e.detail.checked) } }}></usa-toggle>
+```
+
+## Solid / SolidStart (v3.8)
+
+```tsx
+import { onMount } from 'solid-js';
+import { defineUsa } from 'motionary/components/solid';
+onMount(() => defineUsa());
+<usa-toggle prop:checked={on()} on:usa:change={(e) => setOn(e.detail.checked)} />;
+```
+
+## Angular (v3.8)
+
+```ts
+import { APP_INITIALIZER, CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
+import { usaInitializer, usaDetail } from 'motionary/components/angular';
+// app.config.ts
+providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer() }];
+// component
+@Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `<usa-toggle [checked]="on" (usa:change)="on = detail($event).checked"></usa-toggle>` })
+export class Settings { on = false; detail = usaDetail; }
+```
+
+MAUI, Flutter WebView, Electron and Tauri: see [hybrid-apps.md](./hybrid-apps.md).

package/docs/hybrid-apps.md

@@ -0,0 +1,145 @@
+# Hybrid & desktop apps: MAUI, Flutter WebView, Electron, Tauri
+
+`<usa-*>` components are plain Web Components (Custom Elements + CSS + Web Animations): anything that hosts a modern web view can run them, with **no bundler** if you want — copy `dist/components.umd.js` (and optionally `dist/components.css`) next to your HTML. For WinUI 3 / WPF / WinForms with WebView2 see [windows-apps.md](./windows-apps.md).
+
+General rules for every host:
+
+- **Load locally, not from a CDN**, so the app works offline and passes store review: ship `components.umd.js` as an asset and reference it with a relative URL.
+- **Strict CSP is fine**: styles are adopted as constructable stylesheets. If you load `components.css` yourself, call `configureComponents({ injectStyles: false })`.
+- **Reduced motion follows the OS** (`prefers-reduced-motion`) inside every web view listed here. To mirror an in-app setting, call `setMotionIntensity('off' | 'low' | 'normal' | 'high')` (or `configureComponents({ reducedMotion: 'reduce' })`) from the native side.
+- **Performance**: canvas / WebGL effects (`<usa-shader>`, `<usa-liquid>`, backgrounds) render only while visible and cap DPR at 2; they fall back to CSS where WebGL is unavailable (some Android web views).
+- **Native ↔ web**: listen to `usa:*` events in JS and forward them over the host bridge (examples below).
+
+## .NET MAUI
+
+MAUI 9+ has `HybridWebView` (raw HTML + JS bridge); `BlazorWebView` also works (Razor renders the tags; enable the elements in `wwwroot/index.html`).
+
+```text
+Resources/Raw/wwwroot/
+  index.html
+  components.umd.js     ← copied from node_modules/motionary/dist/
+```
+
+```xml
+<!-- MainPage.xaml -->
+<HybridWebView x:Name="Web" DefaultFile="index.html" RawMessageReceived="OnMessage" />
+```
+
+```html
+<!-- Resources/Raw/wwwroot/index.html -->
+<script src="components.umd.js"></script>
+<script src="_framework/hybridwebview.js"></script>
+<usa-toggle id="t"></usa-toggle>
+<script>
+  document.getElementById('t').addEventListener('usa:change', (e) =>
+    window.HybridWebView.SendRawMessage(JSON.stringify({ checked: e.detail.checked })));
+</script>
+```
+
+```csharp
+void OnMessage(object s, HybridWebViewRawMessageReceivedEventArgs e) => Debug.WriteLine(e.Message);
+// native → web
+await Web.EvaluateJavaScriptAsync("UsaComponents.setMotionIntensity('low')");
+```
+
+Notes: Android uses the system WebView (Chromium) — keep it updated; iOS / Mac Catalyst use WKWebView (Safari engine), where `linear()` spring easings fall back to cubic-bezier automatically.
+
+## Flutter (webview_flutter / flutter_inappwebview)
+
+```yaml
+# pubspec.yaml
+dependencies:
+  webview_flutter: ^4.10.0
+flutter:
+  assets:
+    - assets/web/index.html
+    - assets/web/components.umd.js
+```
+
+```dart
+final controller = WebViewController()
+  ..setJavaScriptMode(JavaScriptMode.unrestricted)
+  ..addJavaScriptChannel('Usa', onMessageReceived: (m) => debugPrint(m.message))
+  ..loadFlutterAsset('assets/web/index.html');
+
+// native → web (e.g. follow the platform's "reduce motion" setting)
+final reduce = MediaQuery.of(context).disableAnimations;
+controller.runJavaScript("UsaComponents.setMotionIntensity('${reduce ? 'off' : 'normal'}')");
+```
+
+```html
+<!-- assets/web/index.html -->
+<script src="components.umd.js"></script>
+<usa-like id="like"></usa-like>
+<script>
+  document.getElementById('like').addEventListener('usa:change', (e) => Usa.postMessage(JSON.stringify(e.detail)));
+</script>
+```
+
+`loadFlutterAsset` serves from a `file://`-like origin; ES-module builds (`components.js`) need an HTTP origin, so prefer the UMD file here. On Flutter Web you can use the components directly in `web/index.html` via `HtmlElementView`.
+
+## Electron
+
+The renderer is Chromium — use the npm package with your bundler, or the UMD file without one.
+
+```js
+// renderer.js (bundled)
+import { defineComponents, configureComponents } from 'motionary/components';
+configureComponents({ injectStyles: true });
+defineComponents();
+```
+
+```js
+// main.js — keep contextIsolation on; expose only what you need
+new BrowserWindow({ webPreferences: { preload: path.join(__dirname, 'preload.js'), contextIsolation: true, sandbox: true } });
+```
+
+```js
+// preload.js — forward component events to the main process
+const { contextBridge, ipcRenderer } = require('electron');
+contextBridge.exposeInMainWorld('usaBridge', { send: (type, detail) => ipcRenderer.send('usa', type, detail) });
+```
+
+Imports are SSR-safe (no `window` access at import time), so the same modules can be imported in preload scripts.
+
+## Tauri (v2)
+
+```js
+// src/main.js (Vite)
+import { defineComponents } from 'motionary/components';
+import { invoke } from '@tauri-apps/api/core';
+defineComponents();
+document.querySelector('usa-toggle').addEventListener('usa:change', (e) => invoke('set_setting', { on: e.detail.checked }));
+```
+
+```json
+// tauri.conf.json — a strict CSP works (constructable stylesheets)
+{ "app": { "security": { "csp": "default-src 'self'; style-src 'self'; script-src 'self'" } } }
+```
+
+Tauri uses WebView2 on Windows, WKWebView on macOS / iOS and WebKitGTK on Linux. WebKitGTK may disable WebGL on some drivers: WebGL components then set `data-fallback="webgl"` and show their CSS fallback.
+
+## Native shell bridge (4.7)
+
+`motionary/components/bridge` keeps the page in sync with the host app's **system settings** — reduce motion, light / dark / high-contrast theme, accent color — on WinUI 3 / WPF (WebView2), .NET MAUI and Flutter:
+
+```js
+import { connectNativeShell } from 'motionary/components/bridge';
+const { host } = connectNativeShell();   // 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser'
+```
+
+Protocol (JSON): the page sends `{"type":"usa:ready","version":1}` and `{"type":"usa:request-settings"}`; the host answers (and re-sends on every system change) with `{"type":"usa:settings","reducedMotion":true,"theme":"dark","accent":"#0078d4","sensitivity":"gentle"}` — via `PostWebMessageAsJson` (WebView2), `window.postMessage`, or by running `window.usaNative.apply({...})`. Incoming values are validated (unknown fields and non-color accents are dropped); settings only affect presentation.
+
+Complete samples: [examples/native](../examples/native/) — `winui3/MainWindow.xaml.cs` (`UISettings.AnimationsEnabled`, accent, high contrast), `maui/MainPage.xaml.cs` (Android animator scale, iOS Reduce Motion, Windows `UISettings`, `RequestedThemeChanged`), `flutter/lib/main.dart` (`MediaQuery.disableAnimations`, brightness, high contrast via a `UsaBridge` JavaScriptChannel).
+
+Helpers: `detectNativeHost()`, `postToNative(msg)`, `parseNativeSettings(data)`, `applyNativeSettings(settings)`; event `usa:native-settings` on `document`.
+
+## Framework wrappers
+
+| Framework | Entry | What it gives you |
+|---|---|---|
+| React | `motionary/components/react` | `createUsaComponents(React)` typed wrappers |
+| Vue | `motionary/components/vue` | `UsaPlugin`, `isUsaElement` |
+| Svelte | `motionary/components/svelte` | `use:usa={{ props, on }}` action, `defineUsa()` |
+| Solid | `motionary/components/solid` | `use:usa` directive, `defineUsa()`, JSX types |
+| Angular | `motionary/components/angular` | `usaInitializer()` for `APP_INITIALIZER`, `usaDetail()`; use `CUSTOM_ELEMENTS_SCHEMA` |

package/docs/migration-from-aos.md

@@ -0,0 +1,67 @@
+# Migrating from AOS (Animate On Scroll)
+
+AOS and `motionary` work the same way at the markup level — mark elements with attributes and call `init()` — so most pages migrate with a search-and-replace.
+
+## 1. Install and initialise
+
+```diff
+- import AOS from 'aos';
+- import 'aos/dist/aos.css';
+- AOS.init({ duration: 800, once: true, offset: 120 });
++ import ScrollAnimate from 'motionary';
++ ScrollAnimate.configure({ defaultDuration: 800, defaultOnce: true, defaultOffset: 120 });
++ ScrollAnimate.watch(); // like init(), and also picks up elements added later (AOS.refreshHard())
+```
+
+No stylesheet is needed: animations run through the Web Animations API (or opt into CSS classes with `useClassNames: true`).
+
+## 2. Attributes
+
+| AOS | motionary |
+|---|---|
+| `data-aos="fade-up"` | `data-sa data-sa-animation="fade-in-up"` |
+| `data-aos-duration="800"` | `data-sa-duration="800"` |
+| `data-aos-delay="200"` | `data-sa-delay="200"` |
+| `data-aos-easing="ease-in-out"` | `data-sa-easing="ease-in-out"` (also `spring`, `soft-spring`, `heavy-bounce`, `[x1,y1,x2,y2]`) |
+| `data-aos-offset="120"` | `data-sa-offset="120"` |
+| `data-aos-once="true"` | `data-sa-once` (default) |
+| `data-aos-mirror="true"` (animate out when scrolling past) | `data-sa-exit` |
+| `data-aos-anchor-placement="top-center"` | `data-sa-threshold="0.5"` or `data-sa-root-margin="0px 0px -50% 0px"` |
+| `data-aos-anchor=".other"` | `timeline()` played when `.other` enters (or `<usa-timeline>` around it) |
+
+## 3. Animation names
+
+| AOS | motionary |
+|---|---|
+| `fade` | `fade-in` |
+| `fade-up` / `fade-down` | `fade-in-up` / `fade-in-down` |
+| `fade-left` / `fade-right` | `fade-in-right` / `fade-in-left` (see the note below) |
+| `fade-up-right` etc. | `['fade-in-up', 'fade-in-left']` (combine presets) |
+| `flip-up` / `flip-down` | `flip-up` / `flip-down` |
+| `flip-left` / `flip-right` | `flip-y` |
+| `slide-up` / `slide-down` / `slide-left` / `slide-right` | `slide-up` / `slide-down` / `slide-right` / `slide-left` |
+| `zoom-in` / `zoom-out` | `zoom-in` / `zoom-out` |
+| `zoom-in-up` etc. | `['zoom-in', 'fade-in-up']` |
+
+**Left/right naming:** AOS names the direction of travel — `fade-left` moves *towards* the left, i.e. comes in from the right. Here presets name where the element comes *from*: `fade-in-right` comes in from the right. Same for `slide-*`.
+
+## 4. Global options
+
+| `AOS.init({...})` | `createScrollAnimate({...})` / `configure()` |
+|---|---|
+| `duration`, `delay`, `easing`, `offset`, `once` | `defaultDuration`, `defaultDelay`, `defaultEasing`, `defaultOffset`, `defaultOnce` |
+| `mirror: true` | per element `exit: true` (or `data-sa-exit`) |
+| `disable: 'mobile'` / function | `disabled: window.matchMedia('(max-width: 600px)').matches` |
+| `startEvent`, `initClassName`, `animatedClassName` | `useClassNames`, `hiddenClass`, `visibleClass` |
+| `throttleDelay`, `debounceDelay` | not needed (IntersectionObserver, no scroll listener) |
+
+## 5. Events and refresh
+
+| AOS | motionary |
+|---|---|
+| `document.addEventListener('aos:in', ...)` | `onEnter` / `onStart` options, or `<scroll-animate>`'s `sa:enter` / `sa:start` events |
+| `aos:out` | `onLeave` |
+| `AOS.refresh()` | `ScrollAnimate.refresh()` |
+| `AOS.refreshHard()` | `ScrollAnimate.watch()` handles DOM changes automatically |
+
+`prefers-reduced-motion` is respected out of the box (AOS needs `disable`).

package/docs/migration-from-gsap-scrolltrigger.md

@@ -0,0 +1,80 @@
+# Migrating from GSAP ScrollTrigger
+
+GSAP + ScrollTrigger is a full animation platform; `motionary` covers the common scroll cases — reveal on enter, staggered lists, timelines, scrubbed progress and parallax — in a few kB with no dependencies. If you rely on pinning, `snap`, morphing or arbitrary property tweens, keep GSAP for those parts.
+
+## Reveal on enter
+
+```diff
+- gsap.from('.card', { opacity: 0, y: 40, duration: 0.6, scrollTrigger: { trigger: '.card', start: 'top 90%', once: true } });
++ ScrollAnimate.observe('.card', { animation: 'fade-in-up', duration: 600 });
+```
+
+| ScrollTrigger | motionary |
+|---|---|
+| `start: 'top 90%'` | `threshold` / `rootMargin` (`'0px 0px -10% 0px'`) or `offset` (px) |
+| `once: true` | `once: true` (default) |
+| `toggleActions: 'play none none reverse'` | `exit: true` (reverse on leave, replay on enter) |
+| `toggleActions: 'restart none none reset'` | `repeat: true` |
+| `onEnter`, `onLeave`, `onEnterBack`, `onLeaveBack` | `onEnter`, `onLeave` (both directions) |
+| custom `from` vars (`{ opacity: 0, rotate: -10 }`) | `animation: { from: { opacity: 0, transform: 'rotate(-10deg)' }, to: { opacity: 1, transform: 'rotate(0deg)' } }` |
+| `ease: 'back.out(1.7)'` | `easing: 'soft-spring'`, `[0.34, 1.56, 0.64, 1]` or `(t) => …` |
+
+## Staggered lists
+
+```diff
+- gsap.from('.list li', { opacity: 0, y: 20, stagger: 0.08, scrollTrigger: '.list' });
++ staggerChildren(document.querySelector('.list'), { animation: 'fade-in-up', stagger: 80 });
+```
+
+`observeChildren: true` also animates items appended later (infinite lists).
+
+## Timelines
+
+```diff
+- const tl = gsap.timeline({ scrollTrigger: '.hero' });
+- tl.from('.title', { opacity: 0, y: 40 })
+-   .from('.subtitle', { opacity: 0 }, '-=0.2')
+-   .from('.cta', { scale: 0.8, opacity: 0 }, 1.2);
++ const tl = timeline()
++   .to('.title', 'fade-up')
++   .to('.subtitle', 'fade', { at: '-=200' })
++   .to('.cta', 'scale', { at: 1200 });
++ tl.scrub(document.querySelector('.hero')); // or tl.play() when it enters
+```
+
+`play()` / `reverse()` return Promises; `seek()`, `progress()`, labels and `scrub()` work like GSAP's timeline controls.
+
+## Scrub (progress-linked) animations
+
+```diff
+- gsap.to('.bar', { scaleX: 1, ease: 'none', scrollTrigger: { trigger: '.bar', start: 'top bottom', end: 'bottom top', scrub: true } });
++ ScrollAnimate.observe('.bar', { progressVar: '--p', progressMode: 'scroll' });
++ /* CSS */ .bar { transform: scaleX(var(--p, 0)); }
+```
+
+Or let the browser drive a preset natively where scroll-driven animations are supported:
+
+```js
+ScrollAnimate.observe('.card', { animation: 'zoom-in', engine: 'auto', viewRange: ['entry 0%', 'cover 50%'] });
+```
+
+`progressMode: 'scroll'` matches ScrollTrigger's `start: 'top bottom', end: 'bottom top'`; `onProgress(el, p)` is the equivalent of `onUpdate: self => self.progress`.
+
+## Parallax
+
+```diff
+- gsap.to('.bg', { yPercent: 20, ease: 'none', scrollTrigger: { trigger: '.hero', scrub: true } });
++ parallax('.bg', { speed: 0.2 });
+```
+
+## Cleanup
+
+| GSAP | motionary |
+|---|---|
+| `ScrollTrigger.refresh()` | `refresh()` |
+| `trigger.kill()` / `ScrollTrigger.getAll().forEach(t => t.kill())` | `unobserve(target)` / `destroy()` |
+| `gsap.matchMedia()` for reduced motion | built in: `prefers-reduced-motion` shows content without motion |
+
+## Not covered
+
+Pinning (`pin: true`), `snap`, horizontal scroll sections driven by a pinned container, and non-CSS tweening (canvas, SVG morphing, number counters) have no equivalent — combine `onProgress` with your own code, or keep GSAP for those.

package/docs/motion-tokens.css

@@ -0,0 +1,31 @@
+/* motionary motion tokens (4.2) — generated from MOTION_TOKENS */
+:root {
+  --usa-duration-instant: 0ms;
+  --usa-duration-fast: 150ms;
+  --usa-duration-normal: 300ms;
+  --usa-duration-slow: 600ms;
+  --usa-duration-slower: 900ms;
+  --usa-duration-slowest: 1400ms;
+  --usa-easing-linear: linear;
+  --usa-easing-standard: cubic-bezier(0.2, 0, 0, 1);
+  --usa-easing-emphasized: cubic-bezier(0.22, 1, 0.36, 1);
+  --usa-easing-decelerate: cubic-bezier(0, 0, 0, 1);
+  --usa-easing-accelerate: cubic-bezier(0.3, 0, 1, 1);
+  --usa-easing-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --usa-easing-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
+  --usa-spring-gentle-stiffness: 120;
+  --usa-spring-gentle-damping: 14;
+  --usa-spring-gentle-mass: 1;
+  --usa-spring-snappy-stiffness: 300;
+  --usa-spring-snappy-damping: 30;
+  --usa-spring-snappy-mass: 1;
+  --usa-spring-bouncy-stiffness: 260;
+  --usa-spring-bouncy-damping: 12;
+  --usa-spring-bouncy-mass: 1;
+  --usa-spring-wobbly-stiffness: 180;
+  --usa-spring-wobbly-damping: 8;
+  --usa-spring-wobbly-mass: 1;
+  --usa-spring-stiff-stiffness: 500;
+  --usa-spring-stiff-damping: 40;
+  --usa-spring-stiff-mass: 1;
+}

package/docs/motion-tokens.md

@@ -0,0 +1,46 @@
+# Motion design tokens (4.2)
+
+`motionary/components/tokens` gives your product one motion scale — durations, easings and springs — as **CSS custom properties**, **W3C Design Tokens JSON**, and **JS values**, and imports the scale your designers keep in **Figma Tokens (Tokens Studio)** or **Style Dictionary**.
+
+```ts
+import { applyMotionTokens, importMotionTokens, motionToken, motionVar } from 'motionary/components/tokens';
+
+// 1. Use the defaults (writes --usa-* variables on <html>)…
+applyMotionTokens();
+// 2. …or your own scale, from a Figma Tokens / Style Dictionary / DTCG export
+applyMotionTokens(importMotionTokens(await (await fetch('/design/tokens.json')).json()));
+
+motionToken('duration', 'fast');      // 150
+motionToken('easing', 'emphasized');  // 'cubic-bezier(0.22, 1, 0.36, 1)'
+motionVar('duration', 'slow');        // 'var(--usa-duration-slow, 600ms)'
+timeline().to('.card', 'fade-up', { duration: 'slow', easing: 'spring' }); // token names work
+```
+
+```css
+.button { transition: transform var(--usa-duration-fast) var(--usa-easing-emphasized); }
+```
+
+## Default scale
+
+| Group | Tokens |
+|---|---|
+| `duration` (ms) | `instant` 0 · `fast` 150 · `normal` 300 · `slow` 600 · `slower` 900 · `slowest` 1400 |
+| `easing` | `linear` · `standard` · `emphasized` · `decelerate` · `accelerate` · `spring` · `bounce` |
+| `spring` (stiffness / damping / mass) | `gentle` 120/14/1 · `snappy` 300/30/1 · `bouncy` 260/12/1 · `wobbly` 180/8/1 · `stiff` 500/40/1 |
+
+Prebuilt files: [`docs/motion-tokens.css`](./motion-tokens.css) and [`docs/motion.tokens.json`](./motion.tokens.json) (DTCG; `$type: duration | cubicBezier | spring`).
+
+## API
+
+| Function | |
+|---|---|
+| `MOTION_TOKENS` | The default scale. |
+| `applyMotionTokens(partial?, root?, prefix?)` | Merge over the defaults, write `--usa-*` vars on `root` (default `<html>`), make it the active scale. Returns undo. |
+| `importMotionTokens(json, base?)` | DTCG (`$value`/`$type`), Tokens Studio (`value`/`type`), Style Dictionary (`value`, nested). Reads leaves under any `duration` / `easing` / `spring` group (any depth) and typed leaves (`duration`, `cubicBezier`, `transition`, `spring`). |
+| `motionTokensToCss(tokens?, selector?, prefix?)` · `motionTokensToVars()` · `motionTokensToJSON()` | Export. |
+| `motionToken(group, name)` · `motionVar(group, name, prop?)` · `getMotionTokens()` | Read. |
+| `parseDuration()` · `parseEasing()` · `mergeMotionTokens()` · `resolveDurationToken()` · `resolveEasingToken()` | Helpers. |
+
+## Style Dictionary
+
+Point Style Dictionary at `docs/motion.tokens.json` as a source, or export your own motion group and import it at runtime with `importMotionTokens()`. Tokens are plain data, so SSR is fine; `applyMotionTokens()` is a no-op without a DOM (it still sets the active scale).

package/docs/motion.tokens.json

@@ -0,0 +1,132 @@
+{
+  "motion": {
+    "duration": {
+      "instant": {
+        "$type": "duration",
+        "$value": "0ms"
+      },
+      "fast": {
+        "$type": "duration",
+        "$value": "150ms"
+      },
+      "normal": {
+        "$type": "duration",
+        "$value": "300ms"
+      },
+      "slow": {
+        "$type": "duration",
+        "$value": "600ms"
+      },
+      "slower": {
+        "$type": "duration",
+        "$value": "900ms"
+      },
+      "slowest": {
+        "$type": "duration",
+        "$value": "1400ms"
+      }
+    },
+    "easing": {
+      "linear": {
+        "$type": "string",
+        "$value": "linear"
+      },
+      "standard": {
+        "$type": "cubicBezier",
+        "$value": [
+          0.2,
+          0,
+          0,
+          1
+        ]
+      },
+      "emphasized": {
+        "$type": "cubicBezier",
+        "$value": [
+          0.22,
+          1,
+          0.36,
+          1
+        ]
+      },
+      "decelerate": {
+        "$type": "cubicBezier",
+        "$value": [
+          0,
+          0,
+          0,
+          1
+        ]
+      },
+      "accelerate": {
+        "$type": "cubicBezier",
+        "$value": [
+          0.3,
+          0,
+          1,
+          1
+        ]
+      },
+      "spring": {
+        "$type": "cubicBezier",
+        "$value": [
+          0.34,
+          1.56,
+          0.64,
+          1
+        ]
+      },
+      "bounce": {
+        "$type": "cubicBezier",
+        "$value": [
+          0.68,
+          -0.55,
+          0.265,
+          1.55
+        ]
+      }
+    },
+    "spring": {
+      "gentle": {
+        "$type": "spring",
+        "$value": {
+          "stiffness": 120,
+          "damping": 14,
+          "mass": 1
+        }
+      },
+      "snappy": {
+        "$type": "spring",
+        "$value": {
+          "stiffness": 300,
+          "damping": 30,
+          "mass": 1
+        }
+      },
+      "bouncy": {
+        "$type": "spring",
+        "$value": {
+          "stiffness": 260,
+          "damping": 12,
+          "mass": 1
+        }
+      },
+      "wobbly": {
+        "$type": "spring",
+        "$value": {
+          "stiffness": 180,
+          "damping": 8,
+          "mass": 1
+        }
+      },
+      "stiff": {
+        "$type": "spring",
+        "$value": {
+          "stiffness": 500,
+          "damping": 40,
+          "mass": 1
+        }
+      }
+    }
+  }
+}

package/docs/performance.md

@@ -0,0 +1,24 @@
+# Performance (4.5)
+
+## One frame loop
+Every `<usa-*>` loop (cursors, particles, springs, marquees, WebGL, scroll effects…) schedules work through **one shared `requestAnimationFrame`**: callbacks registered during a frame run together, in order, and a throwing callback no longer starves the rest. Use it for your own loops:
+
+```ts
+import { onFrame, schedulerStats } from 'motionary/components/perf';
+const stop = onFrame((time, dt) => { /* … */ });
+schedulerStats(); // { frames, callbacks, peak, pending, loops }
+```
+
+## Animation budget & auto-degrade
+- `setAnimationBudget(n)` caps concurrent component animations; extra ones land on their final frame instantly. `activeAnimations()` reports the current count.
+- `autoDegrade({ minFps = 45, maxActive = 40, sample = 1000, patience = 2, recovery = 3 })` samples the frame rate and animation count. After `patience` bad samples it sets motion intensity to `low` and the budget to `maxActive / 2`; after `recovery` good samples it restores both. Dispatches `usa:degrade` (`{ degraded, fps, active, reason }`).
+
+## On-demand CSS — `motionary/components/lite`
+Same API as `motionary/components`, but the light-DOM CSS is **not** inlined: the first time an element of a category connects, `dist/components/<category>.css` is added as a `<link>` (custom tag names fall back to `components.css`). Shadow-DOM styles stay inlined.
+
+| Import | gzip |
+|---|---|
+| `motionary/components` (everything, CSS inlined) | ≈ 79 KB |
+| `motionary/components/lite` (everything, CSS on demand) | **≈ 62 KB** (budget 70 KB, checked in CI) |
+
+Serve the CSS from somewhere else with `onDemandStyles('https://cdn.example/motionary@6/dist/')`, or preload with `loadCategoryStyles('cards', base)`.