use-scroll-animate 5.7.0 → 5.9.0

package/docs/ROADMAP.md

@@ -9,6 +9,6 @@
 - ✅ **v5.5** — 生成式背景：流场、Voronoi 细胞、网格渐变（mesh gradient）、星空、metaballs、等高线 —— Canvas 2D 实现，可见时才渲染，自适应质量。
 - ✅ **v5.6** — 声音响应特效：Web Audio 分析器驱动频谱柱、脉冲光环、波形环，节拍检测可触发任意已注册效果（需用户手势开启，减少动态效果时停用）。
 - ✅ **v5.7** — 光标与手势包：彗星拖尾、星光、丝带、磁吸点、聚光光标；甩动、双指旋转、长按蓄力手势 → 触发效果。
-- **v5.8** — 主题包与微交互库：霓虹、纸张、玻璃、复古、粗野主义主题包（令牌 + 效果预设）；复制成功、开关变形、输入抖动、密码显隐、收藏星星、下载进度等 20+ 微交互。
-- **v5.9** — JSON 动画播放器 + 6.0 预备：`<usa-player>` 播放 JSON 动画（关键帧轨道 + 已注册效果，可由实验室导出）；标记 6.0 将移除的 API 并输出一次性警告，发布 `upgrading-6.md` 与 `usa-codemod-6`。
+- ✅ **v5.8** — 主题包与微交互库：霓虹、纸张、玻璃、复古、粗野主义主题包（令牌 + 效果预设）；复制成功、开关变形、输入抖动、密码显隐、收藏星星、下载进度等 20+ 微交互。
+- ✅ **v5.9** — JSON 动画播放器 + 6.0 预备：`<usa-player>` 播放 JSON 动画（关键帧轨道 + 已注册效果，可由实验室导出）；标记 6.0 将移除的 API 并输出一次性警告，发布 `upgrading-6.md` 与 `usa-codemod-6`。
 - **v6.0** — 破坏性清理：移除 5.9 弃用的 API，效果统一走注册表，迁移指南与自动迁移脚本，npm `latest`。

package/docs/components.md

@@ -453,6 +453,52 @@ bindGesture(dial, 'twist', ({ direction }) => step(direction === 'cw' ? 1 : -1))
 ```
 `--usa-charge` (0–1) lets CSS show long-press progress. Reduced motion: cursor effects off.
 
+### v5.8 Theme packs & micro-interactions (`components/effects`)
+
+```html
+<usa-theme name="glass">
+  <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>
+  </div>
+</usa-theme>
+```
+```js
+import { applyTheme, themeCss, playEffect, registerAllEffects } from 'use-scroll-animate/components/effects';
+registerAllEffects();
+const undo = applyTheme('neon');          // whole page: design + motion tokens + data-usa-theme
+const css = themeCss('paper', ':root');   // static CSS for SSR
+playEffect(passwordToggle, 'password-reveal');
+```
+Themes: `neon` · `paper` · `glass` · `retro` · `brutalist`. Micro effects keep working (state, labels, counts) under reduced motion.
+
+### v5.9 `<usa-player>`
+
+Plays JSON animations made of timeline presets, keyframes and registered effects on one clock.
+
+```html
+<usa-player trigger="view" controls>
+  <h1>Title</h1>
+  <a class="cta">Start</a>
+  <script type="application/json">
+  { "format": "use-scroll-animate/animation", "version": 1,
+    "tracks": [
+      { "target": "h1", "start": 0, "duration": 600, "preset": "fade-up" },
+      { "target": ".cta", "start": 400, "duration": 500, "keyframes": [{ "opacity": 0, "transform": "scale(.8)" }, { "opacity": 1, "transform": "none" }] },
+      { "target": ".cta", "start": 1000, "effect": "jelly" }
+    ] }
+  </script>
+</usa-player>
+```
+```js
+import { createPlayer, registerAllEffects } from 'use-scroll-animate/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).
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/docs/deprecations.md

@@ -1,5 +1,9 @@
 # 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`.

package/docs/upgrading-6.md

@@ -0,0 +1,32 @@
+# Upgrading to 6.0
+
+5.9 **warns 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "5.7.0",
+  "version": "5.9.0",
   "description": "A lightweight, high-performance, dependency-free scroll animation library and animated UI components (Web Components) for the web and Windows web-view apps.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -514,6 +514,7 @@
     "node": ">=20"
   },
   "bin": {
-    "usa-codemod-5": "./bin/usa-codemod-5.mjs"
+    "usa-codemod-5": "./bin/usa-codemod-5.mjs",
+    "usa-codemod-6": "./bin/usa-codemod-6.mjs"
   }
 }