use-scroll-animate 5.8.0 → 6.0.0

package/docs/ROADMAP.md

@@ -1,14 +1,14 @@
-# 路线图（5.0 之后）
+# 路线图（6.0 之后）
 
-> 5.0.0：现代浏览器基线（Custom Elements、WAAPI、IntersectionObserver、ResizeObserver、adoptedStyleSheets），移除 4.9 弃用的 API，新增统一的插件式效果注册（`registerEffect()` / `playEffect()` / `<usa-fx>`）。以下为 5.x → 6.0 的规划，每个版本一个 PR；新效果全部通过注册表提供，集中在新入口 `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；新效果继续集中在 `use-scroll-animate/components/effects`（`components/lite` 维持 70 KB 预算），全部兼容“减少动态效果”。
 
-- ✅ **v5.1** — 卡片与点击特效 2.0：全息镭射卡、扫光、3D 翻书、磁吸卡组、卡片倾倒；点击冲击波环、墨水飞溅、星星爆裂、果冻按压、涟漪环 —— 全部可用 `<usa-fx>` 触发。
-- ✅ **v5.2** — 弹跳与物理微交互：弹入、橡皮筋、弹性悬停、掉落回弹、重力文字、弹簧跟随指针、摇摆铃铛。
-- ✅ **v5.3** — 全页特效：幕布、光圈擦除、像素溶解、百叶窗转场、滚动速度倾斜、全页聚光灯、页面边缘光晕。
-- ✅ **v5.4** — 滚动叙事模板：`<usa-story>` —— 固定章节、横向长廊、缩放穿越、前后对比滑块、数据故事计数器、逐段高亮。
-- ✅ **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`。
-- **v6.0** — 破坏性清理：移除 5.9 弃用的 API，效果统一走注册表，迁移指南与自动迁移脚本，npm `latest`。
+- **v6.1** — 粒子与流体 2.0：GPU 流体模拟背景、烟雾与火焰、墨滴扩散、萤火虫群、樱花与落叶飘散、点击溅起水花 —— WebGL2 实现，自动降级到 Canvas 2D。
+- **v6.2** — 文字特效 3.0：液态文字、霓虹描边书写、文字粒子化聚散、故障（glitch）字、打字机光标拖影、可变字体呼吸、逐字 3D 翻转。
+- **v6.3** — 光影与材质：动态光源投影、玻璃折射、金属拉丝反光、珠光 / 镭射材质、体积光（god rays）、跟随指针的实时阴影。
+- **v6.4** — 3D 场景卡片：视差层叠景深卡、可旋转 3D 商品展示、立方体翻转画廊、折纸展开、轨道相机滚动叙事 —— CSS 3D 为主，可选 WebGL。
+- **v6.5** — 形变与 SVG 2.0：路径自动补间形变、液态 blob 按钮、描边绘制动画、SVG 滤镜（湍流、置换）扭曲转场、图标一键变形。
+- **v6.6** — 转场大全：涟漪溶解、碎片爆裂、马赛克翻牌、液体擦除、卷页、镜头推拉 —— View Transitions 优先，多页（MPA）同样可用。
+- **v6.7** — 天气与氛围：雨滴打在玻璃上、雪花堆积、雷电闪光（限频的安全闪烁）、雾气、极光、随时间变化的昼夜光照。
+- **v6.8** — 交互物理 2.0：可拖拽的软体与布料、绳索与链条、磁力吸附排列、碰撞弹球、重力翻转页面 —— 轻量 Verlet 求解器。
+- **v6.9** — 7.0 预备：动画编辑器 2.0（曲线编辑、`<usa-player>` 关键帧录制）、效果市场清单格式；标记 7.0 将移除的 API 并输出一次性警告，发布 `upgrading-7.md` 与 `usa-codemod-7`。
+- **v7.0** — 破坏性清理：移除 6.9 弃用的 API，效果包按需拆分入口，WebGPU 渲染后端（WebGL2 回退），迁移指南与自动迁移脚本，npm `latest`。

package/docs/components.md

@@ -40,7 +40,7 @@ defineTypewriter();
 No build step (registers every `<usa-*>` and exposes the API as `window.UsaComponents`):
 
 ```html
-<script src="https://unpkg.com/use-scroll-animate@5/dist/components.umd.js"></script>
+<script src="https://unpkg.com/use-scroll-animate@6/dist/components.umd.js"></script>
 <usa-typewriter words="Hello, Windows.|Hello, web."></usa-typewriter>
 <script>UsaComponents.toast('Ready', { type: 'success' });</script>
 ```
@@ -151,7 +151,7 @@ Presets (`SPRING_PRESETS`): `default` (170/26), `gentle` (120/14), `wobbly` (180
 | `<usa-hold>` | Hold-to-confirm ring | `duration` (1200), `label`, `color`, `haptic` | `progress`, `cancel()`; `usa:progress`, `usa:confirm`, `usa:cancel`; `--usa-hold` |
 | `<usa-double-tap>` | Double tap → heart at the point | `icon` (♥), `color`, `delay` (300), `haptic` | `pop(x?, y?)`; `usa:double-tap` |
 | `<usa-checkbox>` | Animated form-associated checkbox | `checked`, `indeterminate`, `name`, `value`, `label`, `shape` (`circle`) | `checked`, `toggle()`; `change`, `usa:change` |
-| `burst()` · `confetti()` · `shake()` · `haptic()` | The click-effect engine as functions | — | particles skip under reduced motion |
+| `haptic()` · `playEffect(el, 'burst' \| 'confetti' \| 'shake', …)` | Haptics; the click effects from code go through the effect registry (6.0 removed `burst()` / `confetti()` / `shake()`) | — | particles skip under reduced motion |
 
 ### 10. UI components & variants — `components/ui`
 
@@ -180,7 +180,7 @@ Presets (`SPRING_PRESETS`): `default` (170/26), `gentle` (120/14), `wobbly` (180
 | `pageTransition(update, opts)` | SPA page transition (View Transitions) | `effect` (`fade` · `slide` · `slide-left` · `slide-right` · `slide-up` · `circle` · `blinds` · `pixel` · `zoom`), `x`, `y`, `duration`, `fallback` | Promise |
 | `enableMpaTransitions(effect)` | Cross-document (MPA) transitions | effect, duration | — |
 | `themeTransition(apply, { x, y })` | Circle-reveal theme switch | — | Promise |
-| `<usa-cursor>` | Custom cursor | `mode` (`dot` · `trail` · `magnetic` · `glow`), `color`, `size`, `hide-native`, `targets` | `active` |
+| `<usa-cursor>` | Custom cursor | `mode` (`dot` · `magnetic` · `glow`; 6.0 removed `trail` → `comet-trail` effect), `color`, `size`, `hide-native`, `targets` | `active` |
 | `smoothScroll(opts)` · `scrollToTarget(to, opts)` | Wheel smoothing · spring scroll-to | `target`, `lerp` (0.12), `wheelMultiplier` · `offset`, `preset` | returns stop fn · Promise |
 | `<usa-fullpage>` | Full-screen snapping sections | `dots`, `axis` (`y` · `x`) | `index`, `go(i)`, `next()`, `prev()`; `usa:section` |
 | `<usa-loading-bar>` · `loadingBar` | Top loading bar | `color`, `height` (3), `position` | `start()`, `set(p)`, `done()`, `track(promise)` |
@@ -473,6 +473,32 @@ 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/performance.md

@@ -21,4 +21,4 @@ Same API as `use-scroll-animate/components`, but the light-DOM CSS is **not** in
 | `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) |
 
-Serve the CSS from somewhere else with `onDemandStyles('https://cdn.example/use-scroll-animate@5/dist/')`, or preload with `loadCategoryStyles('cards', base)`.
+Serve the CSS from somewhere else with `onDemandStyles('https://cdn.example/use-scroll-animate@6/dist/')`, or preload with `loadCategoryStyles('cards', base)`.

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "5.8.0",
+  "version": "6.0.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"
   }
 }