use-scroll-animate 6.1.0 → 6.2.0

package/docs/ROADMAP.md

@@ -1,15 +1,14 @@
 # 路线图（6.0 之后）
 
-> 6.0.0：移除 5.9 弃用的 API（`burst()` / `confetti()` / `shake()`、`<usa-cursor mode="trail">`），所有效果统一通过注册表（`registerEffect()` / `playEffect()` / `<usa-fx>`）提供。以下为 6.x → 7.0 的规划，每个版本一个 PR（6.1 插入“滚动预设 2.0”后，原 6.1–6.9 依次顺延为 6.2–6.10）；新效果继续集中在 `use-scroll-animate/components/effects`（`components/lite` 维持 70 KB 预算），全部兼容“减少动态效果”。
+> 6.0.0：移除 5.9 弃用的 API（`burst()` / `confetti()` / `shake()`、`<usa-cursor mode="trail">`），所有效果统一通过注册表（`registerEffect()` / `playEffect()` / `<usa-fx>`）提供。以下为 6.x → 7.0 的规划，每个版本一个 PR（6.1 插入“滚动预设 2.0”后顺延；6.2 起每个版本同时新增 3–6 个动画 UI 组件，天气与交互物理合并为 6.8）；6.x 新效果包各自独立入口（`motionary/components/fx-*`），新组件在 `motionary/components/widgets`（`components/lite` 维持 70 KB 预算），全部兼容“减少动态效果”。
 
-- **v6.1** ✅ — 滚动预设 2.0（Scroll presets 2.0，已发布）：新增 181 个滚动入场预设（总计 214 个），独立入口 `use-scroll-animate/presets/extended`（导入即注册，UMD `dist/presets-extended.umd.js`），核心包体积不变；预设支持中间关键帧 `frames`，新增 `registerPresets()` / `reversePreset()`；动画商店扩展到 227 个条目、14 个预设分类（含随滚动 `scrub-*` 与错峰 `stagger-*`）。
-- **v6.2** — 粒子与流体 2.0：GPU 流体模拟背景、烟雾与火焰、墨滴扩散、萤火虫群、樱花与落叶飘散、点击溅起水花 —— WebGL2 实现，自动降级到 Canvas 2D。
-- **v6.3** — 文字特效 3.0：液态文字、霓虹描边书写、文字粒子化聚散、故障（glitch）字、打字机光标拖影、可变字体呼吸、逐字 3D 翻转。
-- **v6.4** — 光影与材质：动态光源投影、玻璃折射、金属拉丝反光、珠光 / 镭射材质、体积光（god rays）、跟随指针的实时阴影。
-- **v6.5** — 3D 场景卡片：视差层叠景深卡、可旋转 3D 商品展示、立方体翻转画廊、折纸展开、轨道相机滚动叙事 —— CSS 3D 为主，可选 WebGL。
-- **v6.6** — 形变与 SVG 2.0：路径自动补间形变、液态 blob 按钮、描边绘制动画、SVG 滤镜（湍流、置换）扭曲转场、图标一键变形。
-- **v6.7** — 转场大全：涟漪溶解、碎片爆裂、马赛克翻牌、液体擦除、卷页、镜头推拉 —— View Transitions 优先，多页（MPA）同样可用。
-- **v6.8** — 天气与氛围：雨滴打在玻璃上、雪花堆积、雷电闪光（限频的安全闪烁）、雾气、极光、随时间变化的昼夜光照。
-- **v6.9** — 交互物理 2.0：可拖拽的软体与布料、绳索与链条、磁力吸附排列、碰撞弹球、重力翻转页面 —— 轻量 Verlet 求解器。
-- **v6.10** — 7.0 预备：动画编辑器 2.0（曲线编辑、`<usa-player>` 关键帧录制）、效果市场清单格式；标记 7.0 将移除的 API 并输出一次性警告，发布 `upgrading-7.md` 与 `usa-codemod-7`。
-- **v7.0** — 破坏性清理：移除 6.10 弃用的 API，效果包按需拆分入口，WebGPU 渲染后端（WebGL2 回退），迁移指南与自动迁移脚本，npm `latest`。
+- **v6.1** ✅ — 滚动预设 2.0（Scroll presets 2.0，已发布）：新增 181 个滚动入场预设（总计 214 个），独立入口 `motionary/presets/extended`（导入即注册，UMD `dist/presets-extended.umd.js`），核心包体积不变；预设支持中间关键帧 `frames`，新增 `registerPresets()` / `reversePreset()`；动画商店扩展到 227 个条目、14 个预设分类（含随滚动 `scrub-*` 与错峰 `stagger-*`）。
+- ✅ **v6.2** — 粒子与流体 2.0 + 组件：GPU 流体、烟雾、火焰、墨滴扩散、萤火虫、樱花与落叶、点击水花（WebGL2，自动降级 Canvas 2D）；新组件 轮播 / 滑块、动画指示器标签页、手风琴 2.0、快拍浏览器（独立入口 `motionary/components/widgets`）。
+- **v6.3** — 文字特效 3.0 + 组件：液态文字、霓虹书写、文字粒子聚散、故障字、光标拖影、可变字体呼吸、逐字 3D 翻转；新组件 通知 / Toast 堆叠、模态对话框、抽屉 / 底部面板。
+- **v6.4** — 光影与材质 + 组件：动态光源、玻璃折射、金属拉丝、珠光 / 镭射、体积光、指针实时阴影；新组件 进度条 / 进度环、计数器 / 里程表、骨架屏闪光、评分星。
+- **v6.5** — 3D 场景卡片 + 组件：景深层叠卡、可旋转商品展示、立方体画廊、折纸展开、轨道相机叙事；新组件 时间轴、瀑布流（布局动画）、图片对比滑块。
+- **v6.6** — 形变与 SVG 2.0 + 组件：路径补间、液态 blob 按钮、描边绘制、SVG 滤镜转场、图标变形；新组件 Dock 栏（macOS 放大）、形变下划线导航、汉堡 → 关闭图标、提示 / 气泡。
+- **v6.7** — 转场大全 + 组件：涟漪溶解、碎片爆裂、马赛克翻牌、液体擦除、卷页、镜头推拉（View Transitions 优先，MPA 可用）；新组件 步骤条 / 向导、分页、分段控件、开关变体。
+- **v6.8** — 天气与氛围 + 交互物理 2.0 + 组件：玻璃雨滴、积雪、安全闪电、雾、极光、昼夜光照；软体、布料、绳索、磁吸、弹球、重力翻转（Verlet）；新组件 看板 / 拖拽排序、滑动卡片、下拉刷新。
+- **v6.9** — 7.0 预备 + 组件：动画编辑器 2.0、效果市场清单格式、7.0 弃用警告、`upgrading-7.md` 与 `usa-codemod-7`；新组件 日期选择器、取色器、文件拖放区动画。
+- **v7.0** — 破坏性清理：移除 6.9 弃用的 API，效果包与组件按需拆分入口，WebGPU 渲染后端（WebGL2 回退），npm `latest`。

package/docs/accessibility.md

@@ -1,4 +1,4 @@
-# Accessibility (`use-scroll-animate/components`)
+# Accessibility (`motionary/components`)
 
 Audited in v2.9 (automated sweep in `test/components-a11y-frameworks.test.ts` + per-component tests).
 
@@ -33,7 +33,7 @@ Glass, acrylic and Fluent materials fall back to solid surfaces under `prefers-r
 
 ## Motion-sensitivity levels (4.4)
 
-`import { setMotionSensitivity, restoreMotionSensitivity } from 'use-scroll-animate/components/a11y'`
+`import { setMotionSensitivity, restoreMotionSensitivity } from 'motionary/components/a11y'`
 
 | Level | What moves | Use for |
 |---|---|---|

package/docs/components.md

@@ -1,55 +1,55 @@
-# Animated components (`use-scroll-animate/components`)
+# Animated components (`motionary/components`)
 
 Since **v2.2** (now **v3**) the package ships **30 animated UI components** as standard Web Components (`<usa-*>` custom elements) plus three transition helpers. They are built only on Custom Elements, CSS and the Web Animations API, so the same code runs:
 
 - in any modern browser (Chrome, Edge, Firefox, Safari), and with React, Vue, Svelte, Solid, Angular or no framework;
 - in **Windows desktop software** that renders its UI with a web view — Electron, Tauri (WebView2), WinUI 3 / WPF / WinForms with WebView2, and installed PWAs. See **[Windows apps guide](./windows-apps.md)**.
 
-Live gallery: <https://harrisoncn.github.io/use-scroll-animate/showcase/components.html>
+Live gallery: <https://harrisoncn.github.io/motionary/showcase/components.html>
 
 ## Principles
 
-- **Zero dependencies, tree-shakable.** Import one category (`use-scroll-animate/components/text`) or one component (`import { defineTypewriter } …`) and only that ships.
+- **Zero dependencies, tree-shakable.** Import one category (`motionary/components/text`) or one component (`import { defineTypewriter } …`) and only that ships.
 - **SSR-safe.** Importing never touches `window`/`document`; every `define*()` is a no-op on the server.
 - **Opt-in registration.** Nothing is registered until you call `define*()` (or load the IIFE bundle). Every `define*()` accepts a custom tag name: `defineSpinner('my-loader')`.
 - **`prefers-reduced-motion` everywhere.** Each component has a calm variant (instant reveal, fade instead of slide, static background…). Override globally with `configureComponents({ reducedMotion: 'reduce' | 'no-preference' | 'user' })`.
 - **GPU-friendly.** Animations use `transform` / `opacity` (plus `filter` for blur effects); layout is read and written in separate phases, at most once per frame, and loops pause when off-screen or the tab is hidden.
 - **Accessible.** Animated text keeps a visually-hidden plain copy for screen readers; switches, progress bars, toasts and dialogs carry the right roles and ARIA states.
-- **Styles included.** Each component injects its own small stylesheet once (as a constructable stylesheet, which a `style-src 'self'` CSP allows). Prefer a file? `import 'use-scroll-animate/components.css'` (or `/components/<category>.css`) and call `configureComponents({ injectStyles: false })`.
+- **Styles included.** Each component injects its own small stylesheet once (as a constructable stylesheet, which a `style-src 'self'` CSP allows). Prefer a file? `import 'motionary/components.css'` (or `/components/<category>.css`) and call `configureComponents({ injectStyles: false })`.
 
 ## Install & register
 
 ```bash
-npm i use-scroll-animate
+npm i motionary
 ```
 
 ```js
 // everything
-import { defineComponents } from 'use-scroll-animate/components';
+import { defineComponents } from 'motionary/components';
 defineComponents();                       // or defineComponents(['text', 'feedback'])
 
 // one category
-import { defineTextComponents } from 'use-scroll-animate/components/text';
+import { defineTextComponents } from 'motionary/components/text';
 defineTextComponents();
 
 // one component
-import { defineTypewriter } from 'use-scroll-animate/components/text';
+import { defineTypewriter } from 'motionary/components/text';
 defineTypewriter();
 ```
 
 No build step (registers every `<usa-*>` and exposes the API as `window.UsaComponents`):
 
 ```html
-<script src="https://unpkg.com/use-scroll-animate@6/dist/components.umd.js"></script>
+<script src="https://unpkg.com/motionary@6/dist/components.umd.js"></script>
 <usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
 <script>UsaComponents.toast('Ready', { type: 'success' });</script>
 ```
 
 | Entry | Contents |
 |---|---|
-| `use-scroll-animate/components` | everything + `defineComponents()`, `COMPONENT_CATEGORIES`, `configureComponents()` |
-| `use-scroll-animate/components/reveal` · `/text` · `/interaction` · `/feedback` · `/background` · `/transitions` | one category + `define<Category>Components()` |
-| `use-scroll-animate/components.css`, `/components/<category>.css` | the same styles as files |
+| `motionary/components` | everything + `defineComponents()`, `COMPONENT_CATEGORIES`, `configureComponents()` |
+| `motionary/components/reveal` · `/text` · `/interaction` · `/feedback` · `/background` · `/transitions` | one category + `define<Category>Components()` |
+| `motionary/components.css`, `/components/<category>.css` | the same styles as files |
 | `dist/components.umd.js` | IIFE/UMD bundle for `<script>` tags, auto-registers |
 
 ## Components by category
@@ -60,7 +60,7 @@ All attributes are optional unless noted. Events are `CustomEvent`s that bubble,
 
 | Element | What it does | Key attributes | JS API / events |
 |---|---|---|---|
-| `<usa-reveal>` | Reveals content when it enters the viewport | `effect` (`fade`, `fade-up`*, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-out`, `blur`, `blur-up`, `flip-up`, `flip-left`, `rise`, or since 6.1 any registered scroll preset name such as `bounce-in-up` / `clip-diamond` once `use-scroll-animate` or `use-scroll-animate/presets/extended` is loaded — see [presets.md](./presets.md)), `duration` (700), `delay`, `distance` (32), `easing`, `threshold` (0.15), `root-margin`, `repeat` | `reveal()`, `reset()`, `revealed`; `usa:enter`, `usa:leave`, `usa:complete` |
+| `<usa-reveal>` | Reveals content when it enters the viewport | `effect` (`fade`, `fade-up`*, `fade-down`, `fade-left`, `fade-right`, `zoom-in`, `zoom-out`, `blur`, `blur-up`, `flip-up`, `flip-left`, `rise`, or since 6.1 any registered scroll preset name such as `bounce-in-up` / `clip-diamond` once `motionary` or `motionary/presets/extended` is loaded — see [presets.md](./presets.md)), `duration` (700), `delay`, `distance` (32), `easing`, `threshold` (0.15), `root-margin`, `repeat` | `reveal()`, `reset()`, `revealed`; `usa:enter`, `usa:leave`, `usa:complete` |
 | `<usa-stagger>` | Reveals its children one after another | `effect`, `interval` (70 ms), `duration`, `delay`, `distance`, `threshold`, `repeat` | `reveal()`, `reset()`; `usa:enter`, `usa:complete` |
 | `<usa-scroll-progress>` | Reading-progress bar for the page or one article | `target` (selector), `position` (`top`*, `bottom`, `inline`), `label`; CSS `--usa-progress-color/-height/-track` | `progress`, `update()`; `usa:progress` (`detail.progress`); `--usa-progress` on the element |
 | `<usa-scrolly>` | Sticky scrollytelling: `[data-sticky]` stays pinned while `[data-step]` children scroll by | `offset` (trigger line, 0.5) | `active`, `steps`; `usa:step` (`detail.index/step/name`); `data-step-name` + `--usa-step` on the host, `data-active` on the step |
@@ -222,10 +222,10 @@ Every component reads these CSS custom properties (set them on `:root`, any ance
 
 | Import | What |
 |---|---|
-| `use-scroll-animate/components/react` | `createUsaComponents(React)` typed wrappers (props, ref, `onUsa*` events) |
-| `use-scroll-animate/components/vue` | `isUsaElement`, `UsaPlugin` |
-| `use-scroll-animate/components/jsx` | `UsaIntrinsicElements` JSX types |
-| `use-scroll-animate/components/lazy` | `lazyDefine()`, `defineUsed()`, `loadCategory()` |
+| `motionary/components/react` | `createUsaComponents(React)` typed wrappers (props, ref, `onUsa*` events) |
+| `motionary/components/vue` | `isUsaElement`, `UsaPlugin` |
+| `motionary/components/jsx` | `UsaIntrinsicElements` JSX types |
+| `motionary/components/lazy` | `lazyDefine()`, `defineUsed()`, `loadCategory()` |
 
 See [frameworks-ssr.md](./frameworks-ssr.md) and [accessibility.md](./accessibility.md).
 
@@ -327,7 +327,7 @@ Hybrid / desktop hosts (MAUI, Flutter WebView, Electron, Tauri): [hybrid-apps.md
 `<usa-fx>` (`defineFx()`, `defineFxComponents()`) plays any registered effect on its first child: `<usa-fx effect="jelly" trigger="click"><button>Go</button></usa-fx>` — `trigger` `click` · `hover` · `enter` · `load` · `loop` · `manual`, `options` (JSON), `once`, `self`.
 
 ```js
-import { registerEffect, playEffect, bindEffect, listEffects } from 'use-scroll-animate/components/fx';
+import { registerEffect, playEffect, bindEffect, listEffects } from 'motionary/components/fx';
 registerEffect({ name: 'spin-pop', kind: 'attention', run: (el, o, ctx) => ctx.animate(el, frames, { duration: 700 }) });
 await playEffect(el, 'spin-pop');
 const unbind = bindEffect(card, 'fade-up', { trigger: 'enter' });
@@ -337,10 +337,10 @@ Built-ins (`BUILTIN_EFFECTS`): every timeline preset as an `enter` effect (`fade
 
 ### v5.1 Card & click effects 2.0 (`components/effects`)
 
-The 5.x effect packs live in `use-scroll-animate/components/effects` (not in `components` / `components/lite`). Register them once, then use any name with `<usa-fx>`, `playEffect()` or `bindEffect()`:
+The 5.x effect packs live in `motionary/components/effects` (not in `components` / `components/lite`). Register them once, then use any name with `<usa-fx>`, `playEffect()` or `bindEffect()`:
 
 ```js
-import { registerAllEffects } from 'use-scroll-animate/components/effects';
+import { registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
 ```
 ```html
@@ -355,7 +355,7 @@ Card: `holo` · `glare-sweep` · `book-open` · `card-fan` · `topple` · `float
 `bounce-in` · `rubber-band` · `elastic-hover` · `drop-bounce` · `gravity-text` · `spring-follow` · `bell-swing` — keyframes come from a damped-spring / gravity solver and play on WAAPI.
 
 ```js
-import { registerAllEffects, solveSpring, springKeyframes } from 'use-scroll-animate/components/effects';
+import { registerAllEffects, solveSpring, springKeyframes } from 'motionary/components/effects';
 registerAllEffects();
 const { frames, duration } = springKeyframes((p) => ({ transform: `scale(${p})` }), { stiffness: 220, damping: 11 });
 el.animate(frames, { duration });
@@ -370,8 +370,8 @@ el.animate(frames, { duration });
 Transitions `curtain` · `iris` · `pixel-dissolve` · `blinds` cover the viewport, await `onCovered()`, then reveal:
 
 ```js
-import { registerAllEffects } from 'use-scroll-animate/components/effects';
-import { playEffect } from 'use-scroll-animate/components/fx';
+import { registerAllEffects } from 'motionary/components/effects';
+import { playEffect } from 'motionary/components/fx';
 registerAllEffects();
 link.addEventListener('click', (e) => {
   e.preventDefault();
@@ -384,7 +384,7 @@ Persistent: `<usa-fx effect="velocity-skew" trigger="load">`, `spotlight` (`radi
 ### v5.4 Scroll stories — `<usa-story>` (`components/effects`)
 
 ```js
-import { defineStory } from 'use-scroll-animate/components/effects';
+import { defineStory } from 'motionary/components/effects';
 defineStory();
 ```
 ```html
@@ -410,8 +410,8 @@ Templates `pin` · `gallery` · `zoom` (`zoom="6"`) · `compare` · `counter` ·
 </usa-fx>
 ```
 ```js
-import { registerEffect } from 'use-scroll-animate/components/fx';
-import { canvasBackground } from 'use-scroll-animate/components/effects';
+import { registerEffect } from 'motionary/components/fx';
+import { canvasBackground } from 'motionary/components/effects';
 registerEffect({ name: 'pulse-bg', kind: 'background', reduced: 'run',
   run: (el, o, ctx) => canvasBackground(el, ctx, { draw: ({ ctx: g, w, h, t }) => { g.fillStyle = `hsl(${t * 40} 70% 50%)`; g.fillRect(0, 0, w, h); } }, o) });
 ```
@@ -428,7 +428,7 @@ registerEffect({ name: 'pulse-bg', kind: 'background', reduced: 'run',
 </usa-audio>
 ```
 ```js
-import { enableAudio, bindBeat, registerAllEffects } from 'use-scroll-animate/components/effects';
+import { enableAudio, bindBeat, registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
 button.addEventListener('click', async () => {
   await enableAudio('mic');            // or an <audio>/<video> element, selector or MediaStream
@@ -446,7 +446,7 @@ Cursor effects (`comet-trail` · `ribbon-trail` · `sparkle-trail` · `magnetic-
 <usa-gesture-fx gesture="long-press" effect="tada"><button>Hold me</button></usa-gesture-fx>
 ```
 ```js
-import { bindGesture, registerAllEffects } from 'use-scroll-animate/components/effects';
+import { bindGesture, registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
 bindGesture(card, 'fling', 'confetti', { velocity: 1 });
 bindGesture(dial, 'twist', ({ direction }) => step(direction === 'cw' ? 1 : -1));
@@ -460,12 +460,12 @@ bindGesture(dial, 'twist', ({ direction }) => step(direction === 'cw' ? 1 : -1))
   <div class="usa-surface">
     <button data-theme-fx="click">Tap</button>
     <usa-fx effect="like-heart" trigger="click"><button aria-pressed="false">♥ <span data-count="12">12</span></button></usa-fx>
-    <usa-fx effect="copy-success" trigger="click"><button data-copy="npm i use-scroll-animate">Copy</button></usa-fx>
+    <usa-fx effect="copy-success" trigger="click"><button data-copy="npm i motionary">Copy</button></usa-fx>
   </div>
 </usa-theme>
 ```
 ```js
-import { applyTheme, themeCss, playEffect, registerAllEffects } from 'use-scroll-animate/components/effects';
+import { applyTheme, themeCss, playEffect, registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
 const undo = applyTheme('neon');          // whole page: design + motion tokens + data-usa-theme
 const css = themeCss('paper', ':root');   // static CSS for SSR
@@ -492,20 +492,49 @@ Plays JSON animations made of timeline presets, keyframes and registered effects
 </usa-player>
 ```
 ```js
-import { createPlayer, registerAllEffects } from 'use-scroll-animate/components/effects';
+import { createPlayer, registerAllEffects } from 'motionary/components/effects';
 registerAllEffects();
 const p = createPlayer(hero, await (await fetch('/hero.json')).json());
 p.play(); p.seek(500); p.rate = 0.5;
 ```
 `trigger="scroll"` scrubs the animation with the page. Reduced motion: the final state, no effects. Export JSON from the Playground (`<usa-player> JSON` tab).
 
+### v6.2 Widgets: carousel, tab bar, accordion 2.0, stories (`components/widgets`) + GPU pack (`components/fx-gpu`)
+
+```html
+<usa-carousel effect="cards" loop autoplay="4000" label="Featured">
+  <img src="a.jpg" alt="…"><img src="b.jpg" alt="…"><img src="c.jpg" alt="…">
+</usa-carousel>
+
+<usa-tab-bar indicator="pill">
+  <button>Overview</button><button>Specs</button>
+  <div data-panel>…</div><div data-panel>…</div>
+</usa-tab-bar>
+
+<usa-disclosure variant="cards">
+  <details><summary>Shipping</summary><p>…</p></details>
+</usa-disclosure>
+
+<usa-stories duration="5000" loop><img src="1.jpg" alt="…"><img src="2.jpg" alt="…"></usa-stories>
+
+<usa-fx effect="fluid" trigger="load" self class="hero"><h1>Hello</h1></usa-fx>
+```
+```js
+import { defineWidgets } from 'motionary/components/widgets';
+import { defineFx } from 'motionary/components/fx';
+import { registerGpuEffects } from 'motionary/components/fx-gpu';
+defineWidgets(); defineFx(); registerGpuEffects();
+document.querySelector('usa-carousel').next();
+```
+No build: `components.umd.js` + `widgets.umd.js`. GPU effects: `fluid` · `smoke` · `fire` · `ink` · `fireflies` (WebGL2 → Canvas 2D) · `sakura` · `leaves` (Canvas 2D) · `splash` (click). Reduced motion: instant switches, no autoplay, one still frame.
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.
 
 ```jsx
 // React 19 passes props to custom elements as properties; React 18 passes strings — both work for attributes.
-import { defineFeedbackComponents, toast } from 'use-scroll-animate/components/feedback';
+import { defineFeedbackComponents, toast } from 'motionary/components/feedback';
 defineFeedbackComponents();
 
 export function Save() {
@@ -532,4 +561,4 @@ Gzipped, minified (budgets enforced in CI by `npm run size:check`):
 | `viewTransition` only | ≈ 0.4 kB |
 | `dist/components.css` | ≈ 5.5 kB |
 
-The scroll-animation core (`use-scroll-animate`) is unchanged and is not pulled in by the components.
+The scroll-animation core (`motionary`) is unchanged and is not pulled in by the components.

package/docs/frameworks-ssr.md

@@ -8,22 +8,22 @@ All entry points are **SSR-safe**: importing never touches `window`/`document`;
 'use client';
 import { useEffect } from 'react';
 export function UsaProvider() {
-  useEffect(() => { import('use-scroll-animate/components/lazy').then((m) => m.lazyDefine()); }, []);
+  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 `use-scroll-animate/components/jsx`:
+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 'use-scroll-animate/components/jsx';
+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 'use-scroll-animate/components/react';
+import { createUsaComponents } from 'motionary/components/react';
 export const { UsaButton, UsaToggle, UsaCard } = createUsaComponents(React);
 // <UsaToggle checked={on} onUsaChange={(e) => setOn(e.detail.checked)} />
 ```
@@ -37,8 +37,8 @@ Page transitions in the App Router: wrap `router.push` in `pageTransition(() =>
 <html><body>
   <slot />
   <script>
-    import { lazyDefine } from 'use-scroll-animate/components/lazy';
-    import { enableMpaTransitions } from 'use-scroll-animate/components/page';
+    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>
@@ -49,10 +49,10 @@ Use the tags directly in `.astro`, `.md` and island components. With `<ClientRou
 ## Vue / Nuxt
 ```js
 // vite.config.js
-import { isUsaElement } from 'use-scroll-animate/components/vue';
+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 'use-scroll-animate/components/vue';
+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" />`
@@ -61,14 +61,14 @@ app.use(UsaPlugin);            // or app.use(UsaPlugin, { categories: ['click',
 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 `use-scroll-animate/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.
+`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 'use-scroll-animate/components/svelte';
+  import { usa, defineUsa } from 'motionary/components/svelte';
   onMount(() => defineUsa());
   let on = false;
 </script>
@@ -79,7 +79,7 @@ Custom elements work as-is: Svelte (`on:usa:change`), Solid (`on:usa:change`, `p
 
 ```tsx
 import { onMount } from 'solid-js';
-import { defineUsa } from 'use-scroll-animate/components/solid';
+import { defineUsa } from 'motionary/components/solid';
 onMount(() => defineUsa());
 <usa-toggle prop:checked={on()} on:usa:change={(e) => setOn(e.detail.checked)} />;
 ```
@@ -88,7 +88,7 @@ onMount(() => defineUsa());
 
 ```ts
 import { APP_INITIALIZER, CUSTOM_ELEMENTS_SCHEMA, Component } from '@angular/core';
-import { usaInitializer, usaDetail } from 'use-scroll-animate/components/angular';
+import { usaInitializer, usaDetail } from 'motionary/components/angular';
 // app.config.ts
 providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer() }];
 // component

package/docs/hybrid-apps.md

@@ -17,7 +17,7 @@ MAUI 9+ has `HybridWebView` (raw HTML + JS bridge); `BlazorWebView` also works (
 ```text
 Resources/Raw/wwwroot/
   index.html
-  components.umd.js     ← copied from node_modules/use-scroll-animate/dist/
+  components.umd.js     ← copied from node_modules/motionary/dist/
 ```
 
 ```xml
@@ -84,7 +84,7 @@ The renderer is Chromium — use the npm package with your bundler, or the UMD f
 
 ```js
 // renderer.js (bundled)
-import { defineComponents, configureComponents } from 'use-scroll-animate/components';
+import { defineComponents, configureComponents } from 'motionary/components';
 configureComponents({ injectStyles: true });
 defineComponents();
 ```
@@ -106,7 +106,7 @@ Imports are SSR-safe (no `window` access at import time), so the same modules ca
 
 ```js
 // src/main.js (Vite)
-import { defineComponents } from 'use-scroll-animate/components';
+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 }));
@@ -121,10 +121,10 @@ Tauri uses WebView2 on Windows, WKWebView on macOS / iOS and WebKitGTK on Linux.
 
 ## Native shell bridge (4.7)
 
-`use-scroll-animate/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:
+`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 'use-scroll-animate/components/bridge';
+import { connectNativeShell } from 'motionary/components/bridge';
 const { host } = connectNativeShell();   // 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser'
 ```
 
@@ -138,8 +138,8 @@ Helpers: `detectNativeHost()`, `postToNative(msg)`, `parseNativeSettings(data)`,
 
 | Framework | Entry | What it gives you |
 |---|---|---|
-| React | `use-scroll-animate/components/react` | `createUsaComponents(React)` typed wrappers |
-| Vue | `use-scroll-animate/components/vue` | `UsaPlugin`, `isUsaElement` |
-| Svelte | `use-scroll-animate/components/svelte` | `use:usa={{ props, on }}` action, `defineUsa()` |
-| Solid | `use-scroll-animate/components/solid` | `use:usa` directive, `defineUsa()`, JSX types |
-| Angular | `use-scroll-animate/components/angular` | `usaInitializer()` for `APP_INITIALIZER`, `usaDetail()`; use `CUSTOM_ELEMENTS_SCHEMA` |
+| 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

@@ -1,6 +1,6 @@
 # Migrating from AOS (Animate On Scroll)
 
-AOS and `use-scroll-animate` work the same way at the markup level — mark elements with attributes and call `init()` — so most pages migrate with a search-and-replace.
+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
 
@@ -8,7 +8,7 @@ AOS and `use-scroll-animate` work the same way at the markup level — mark elem
 - import AOS from 'aos';
 - import 'aos/dist/aos.css';
 - AOS.init({ duration: 800, once: true, offset: 120 });
-+ import ScrollAnimate from 'use-scroll-animate';
++ 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())
 ```
@@ -17,7 +17,7 @@ No stylesheet is needed: animations run through the Web Animations API (or opt i
 
 ## 2. Attributes
 
-| AOS | use-scroll-animate |
+| AOS | motionary |
 |---|---|
 | `data-aos="fade-up"` | `data-sa data-sa-animation="fade-in-up"` |
 | `data-aos-duration="800"` | `data-sa-duration="800"` |
@@ -31,7 +31,7 @@ No stylesheet is needed: animations run through the Web Animations API (or opt i
 
 ## 3. Animation names
 
-| AOS | use-scroll-animate |
+| AOS | motionary |
 |---|---|
 | `fade` | `fade-in` |
 | `fade-up` / `fade-down` | `fade-in-up` / `fade-in-down` |
@@ -57,7 +57,7 @@ No stylesheet is needed: animations run through the Web Animations API (or opt i
 
 ## 5. Events and refresh
 
-| AOS | use-scroll-animate |
+| AOS | motionary |
 |---|---|
 | `document.addEventListener('aos:in', ...)` | `onEnter` / `onStart` options, or `<scroll-animate>`'s `sa:enter` / `sa:start` events |
 | `aos:out` | `onLeave` |

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

@@ -1,6 +1,6 @@
 # Migrating from GSAP ScrollTrigger
 
-GSAP + ScrollTrigger is a full animation platform; `use-scroll-animate` 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.
+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
 
@@ -9,7 +9,7 @@ GSAP + ScrollTrigger is a full animation platform; `use-scroll-animate` covers t
 + ScrollAnimate.observe('.card', { animation: 'fade-in-up', duration: 600 });
 ```
 
-| ScrollTrigger | use-scroll-animate |
+| ScrollTrigger | motionary |
 |---|---|
 | `start: 'top 90%'` | `threshold` / `rootMargin` (`'0px 0px -10% 0px'`) or `offset` (px) |
 | `once: true` | `once: true` (default) |
@@ -69,7 +69,7 @@ ScrollAnimate.observe('.card', { animation: 'zoom-in', engine: 'auto', viewRange
 
 ## Cleanup
 
-| GSAP | use-scroll-animate |
+| GSAP | motionary |
 |---|---|
 | `ScrollTrigger.refresh()` | `refresh()` |
 | `trigger.kill()` / `ScrollTrigger.getAll().forEach(t => t.kill())` | `unobserve(target)` / `destroy()` |

package/docs/motion-tokens.css

@@ -1,4 +1,4 @@
-/* use-scroll-animate motion tokens (4.2) — generated from MOTION_TOKENS */
+/* motionary motion tokens (4.2) — generated from MOTION_TOKENS */
 :root {
   --usa-duration-instant: 0ms;
   --usa-duration-fast: 150ms;

package/docs/motion-tokens.md

@@ -1,9 +1,9 @@
 # Motion design tokens (4.2)
 
-`use-scroll-animate/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**.
+`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 'use-scroll-animate/components/tokens';
+import { applyMotionTokens, importMotionTokens, motionToken, motionVar } from 'motionary/components/tokens';
 
 // 1. Use the defaults (writes --usa-* variables on <html>)…
 applyMotionTokens();

package/docs/performance.md

@@ -4,7 +4,7 @@
 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 'use-scroll-animate/components/perf';
+import { onFrame, schedulerStats } from 'motionary/components/perf';
 const stop = onFrame((time, dt) => { /* … */ });
 schedulerStats(); // { frames, callbacks, peak, pending, loops }
 ```
@@ -13,12 +13,12 @@ schedulerStats(); // { frames, callbacks, peak, pending, loops }
 - `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 — `use-scroll-animate/components/lite`
-Same API as `use-scroll-animate/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.
+## 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 |
 |---|---|
-| `use-scroll-animate/components` (everything, CSS inlined) | ≈ 79 KB |
-| `use-scroll-animate/components/lite` (everything, CSS on demand) | **≈ 62 KB** (budget 70 KB, checked in CI) |
+| `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/use-scroll-animate@6/dist/')`, or preload with `loadCategoryStyles('cards', base)`.
+Serve the CSS from somewhere else with `onDemandStyles('https://cdn.example/motionary@6/dist/')`, or preload with `loadCategoryStyles('cards', base)`.

package/docs/presets.md

@@ -1,18 +1,18 @@
 # Presets
 
-`use-scroll-animate` ships **214 scroll-reveal presets**: 33 in the core (always available) and **181 extended presets** added in 6.1 ("Scroll presets 2.0").
+`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 'use-scroll-animate';
-import 'use-scroll-animate/presets/extended'; // registers the extended set (≈ 4 kB gzip, separate entry)
+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/use-scroll-animate@6/dist/index.umd.js"></script>
-<script src="https://unpkg.com/use-scroll-animate@6/dist/presets-extended.umd.js"></script>
+<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>
 ```