use-scroll-animate 9.0.0 → 9.1.0

package/docs/ROADMAP.md

@@ -2,7 +2,7 @@
 
 9.0 已发布：声明式动效 DSL（`motionary/dsl` —— 用 `data-motion="enter: fade-up 600ms stagger 80ms; hover: pop"` 一行文本描述完整动效，或用 `<usa-motion>`）、插件市场正式版（`motionary/marketplace` —— 目录、搜索、一键安装，`<usa-plugin-store>`）、移除 8.9 弃用的 `applyTheme()` / `THEMES` / `THEME_NAMES` / `<usa-theme>`（改名为 Motion 前缀）；`motionary` 与 `use-scroll-animate` 同时成为 npm `latest`。下面是 9.1 → 10.0 的计划，每个版本一个主题 + 一组新组件，9.9 负责 10.0 的弃用与迁移工具。
 
-- **v9.1** — 电影化叙事 2.0：镜头语言（推拉摇移、景深切换、转场）；新组件 章节导航。
+- ✅ **v9.1** — 电影化叙事 2.0：镜头语言（推拉摇移、景深切换、转场）；新组件 章节导航。
 - **v9.2** — Lottie / Rive 导入（JSON → 动效时间线）；新组件 动画图标集。
 - **v9.3** — 生成艺术 2.0：风格化着色器；新组件 背景生成器。
 - **v9.4** — 视频动效：滚动驱动视频、帧序列；新组件 视频卡片、英雄视频。

package/docs/components.md

@@ -1167,6 +1167,29 @@ await installPlugin(searchPlugins('retro')[0], { load: () => import('motionary/f
 - `<usa-motion rules>`: `parsed`, `errors`; `usa:motion-error` { message }.
 - `<usa-plugin-store query label>`: `plugins`, `loader`, `search(q)`, `install(name)`; `usa:install` { name, effects }, `usa:install-error`.
 
+### v9.1 Storytelling 2.0: chapter nav, cinematic scene (`components/widgets`) + cinema pack (`motionary/fx/cinema`)
+
+```html
+<usa-chapter-nav for="#story"></usa-chapter-nav>
+<article id="story">
+  <section data-chapter="Prologue">…</section>
+  <usa-scene camera="dolly-in" data-chapter="The harbor">
+    <img src="harbor.jpg" alt="Harbor at dawn"><p data-caption data-at="0.4">Dawn, 1912.</p>
+  </usa-scene>
+</article>
+
+<usa-fx effect="letterbox" trigger="enter"><img src="scene.jpg" alt=""></usa-fx>
+```
+```js
+import { defineWidgets } from 'motionary/components/widgets';
+import { registerCinemaPack, cameraFrame } from 'motionary/fx/cinema';
+defineWidgets(); registerCinemaPack();
+nav.addEventListener('usa:chapter', (e) => console.log(e.detail.title));
+```
+- `<usa-chapter-nav for orientation label>`: `current`, `goTo(i)`; `usa:chapter` { index, title }.
+- `<usa-scene camera strength>`: `progress`, `setProgress(p)`; `usa:shot` { progress }.
+- Cinema: `dolly-in` · `pan-reveal` (`from`) · `letterbox` (`hold`) · `rack-focus`; `cameraFrame(move, p, strength?)`, `CAMERA_MOVES`.
+
 ## 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": "9.0.0",
+  "version": "9.1.0",
   "description": "Compatibility alias of motionary (same build). The project was renamed to Motionary — install `motionary` instead. Motionary (formerly use-scroll-animate): dependency-free scroll animations + 94 animated Web Components — 214 scroll-reveal presets, card/click/button morphs, physics, page transitions, generative & sound-reactive backgrounds, cursor/gesture effects, themes, micro-interactions, <usa-player>, WebGL. React, Vue, Svelte, Solid, Angular or plain HTML.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -388,6 +388,16 @@
         "default": "./dist/components/fx-spatial.cjs"
       }
     },
+    "./fx/cinema": {
+      "import": {
+        "types": "./dist/components/fx-cinema.d.ts",
+        "default": "./dist/components/fx-cinema.js"
+      },
+      "require": {
+        "types": "./dist/components/fx-cinema.d.cts",
+        "default": "./dist/components/fx-cinema.cjs"
+      }
+    },
     "./components/reveal": {
       "import": {
         "types": "./dist/components/reveal.d.ts",
@@ -998,6 +1008,16 @@
         "default": "./dist/components/dsl.cjs"
       }
     },
+    "./components/fx-cinema": {
+      "import": {
+        "types": "./dist/components/fx-cinema.d.ts",
+        "default": "./dist/components/fx-cinema.js"
+      },
+      "require": {
+        "types": "./dist/components/fx-cinema.d.cts",
+        "default": "./dist/components/fx-cinema.cjs"
+      }
+    },
     "./components/lite": {
       "import": {
         "types": "./dist/components/lite.d.ts",