use-scroll-animate 5.3.0 → 5.5.0

package/docs/ROADMAP.md

@@ -5,8 +5,8 @@
 - ✅ **v5.1** — 卡片与点击特效 2.0：全息镭射卡、扫光、3D 翻书、磁吸卡组、卡片倾倒；点击冲击波环、墨水飞溅、星星爆裂、果冻按压、涟漪环 —— 全部可用 `<usa-fx>` 触发。
 - ✅ **v5.2** — 弹跳与物理微交互：弹入、橡皮筋、弹性悬停、掉落回弹、重力文字、弹簧跟随指针、摇摆铃铛。
 - ✅ **v5.3** — 全页特效：幕布、光圈擦除、像素溶解、百叶窗转场、滚动速度倾斜、全页聚光灯、页面边缘光晕。
-- **v5.4** — 滚动叙事模板：`<usa-story>` —— 固定章节、横向长廊、缩放穿越、前后对比滑块、数据故事计数器、逐段高亮。
-- **v5.5** — 生成式背景：流场、Voronoi 细胞、网格渐变（mesh gradient）、星空、metaballs、等高线 —— Canvas 2D 实现，可见时才渲染，自适应质量。
+- ✅ **v5.4** — 滚动叙事模板：`<usa-story>` —— 固定章节、横向长廊、缩放穿越、前后对比滑块、数据故事计数器、逐段高亮。
+- ✅ **v5.5** — 生成式背景：流场、Voronoi 细胞、网格渐变（mesh gradient）、星空、metaballs、等高线 —— Canvas 2D 实现，可见时才渲染，自适应质量。
 - **v5.6** — 声音响应特效：Web Audio 分析器驱动频谱柱、脉冲光环、波形环，节拍检测可触发任意已注册效果（需用户手势开启，减少动态效果时停用）。
 - **v5.7** — 光标与手势包：彗星拖尾、星光、丝带、磁吸点、聚光光标；甩动、双指旋转、长按蓄力手势 → 触发效果。
 - **v5.8** — 主题包与微交互库：霓虹、纸张、玻璃、复古、粗野主义主题包（令牌 + 效果预设）；复制成功、开关变形、输入抖动、密码显隐、收藏星星、下载进度等 20+ 微交互。

package/docs/components.md

@@ -381,6 +381,41 @@ link.addEventListener('click', (e) => {
 
 Persistent: `<usa-fx effect="velocity-skew" trigger="load">`, `spotlight` (`radius`, `dim`), `edge-glow` (`color`, `size`). Reduced motion: transitions cross-fade (150 ms), persistent effects are off.
 
+### v5.4 Scroll stories — `<usa-story>` (`components/effects`)
+
+```js
+import { defineStory } from 'use-scroll-animate/components/effects';
+defineStory();
+```
+```html
+<usa-story template="pin">
+  <figure data-stage>…</figure>
+  <section data-step>Chapter 1</section>
+  <section data-step>Chapter 2</section>
+</usa-story>
+<usa-story template="gallery"><div data-sticky><div data-track>…cards…</div></div></usa-story>
+<usa-story template="compare" label="Before / after"><div data-sticky><img data-before …><img data-after …></div></usa-story>
+<usa-story template="counter"><strong data-count="12,480">0</strong></usa-story>
+```
+
+Templates `pin` · `gallery` · `zoom` (`zoom="6"`) · `compare` · `counter` · `highlight`. Each sets `--usa-story-progress`, fires `usa-story-step`, and exposes `progress`, `step`, `update()`. Reduced motion: no sliding / zooming, final counter values. Demo: `showcase/story.html`.
+
+### v5.5 Generative backgrounds (`components/effects`)
+
+`flow-field` · `voronoi` · `mesh-gradient` · `starfield` · `metaballs` · `contours` (kind `background`) — Canvas 2D behind the element’s content, rendering only while visible, with adaptive quality; reduced motion draws one static frame.
+
+```html
+<usa-fx effect="mesh-gradient" trigger="load" self class="hero" options='{"colors":["#7c5cff","#ff5c8a","#22d3ee"],"speed":0.6}'>
+  <h1>Hello</h1>
+</usa-fx>
+```
+```js
+import { registerEffect } from 'use-scroll-animate/components/fx';
+import { canvasBackground } from 'use-scroll-animate/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) });
+```
+
 ## 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.3.0",
+  "version": "5.5.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",