use-scroll-animate 5.6.0 → 5.7.0

package/docs/ROADMAP.md

@@ -8,7 +8,7 @@
 - ✅ **v5.4** — 滚动叙事模板：`<usa-story>` —— 固定章节、横向长廊、缩放穿越、前后对比滑块、数据故事计数器、逐段高亮。
 - ✅ **v5.5** — 生成式背景：流场、Voronoi 细胞、网格渐变（mesh gradient）、星空、metaballs、等高线 —— Canvas 2D 实现，可见时才渲染，自适应质量。
 - ✅ **v5.6** — 声音响应特效：Web Audio 分析器驱动频谱柱、脉冲光环、波形环，节拍检测可触发任意已注册效果（需用户手势开启，减少动态效果时停用）。
-- **v5.7** — 光标与手势包：彗星拖尾、星光、丝带、磁吸点、聚光光标；甩动、双指旋转、长按蓄力手势 → 触发效果。
+- ✅ **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`。

package/docs/components.md

@@ -437,6 +437,22 @@ button.addEventListener('click', async () => {
 ```
 Reduced motion: visuals skipped, beats trigger nothing; audio keeps playing.
 
+### v5.7 Cursor & gesture packs (`components/effects`)
+
+Cursor effects (`comet-trail` · `ribbon-trail` · `sparkle-trail` · `magnetic-dots` · `spotlight-cursor`, kind `cursor`) are persistent and scoped to the element; gestures (`fling`, `twist`, `long-press`) fire any registered effect.
+
+```html
+<usa-fx effect="comet-trail" trigger="load" self options='{"color":"#22d3ee"}'><section class="hero">…</section></usa-fx>
+<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';
+registerAllEffects();
+bindGesture(card, 'fling', 'confetti', { velocity: 1 });
+bindGesture(dial, 'twist', ({ direction }) => step(direction === 'cw' ? 1 : -1));
+```
+`--usa-charge` (0–1) lets CSS show long-press progress. Reduced motion: cursor effects off.
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

package/package.json

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