use-scroll-animate 4.5.0 → 4.7.0

package/docs/ROADMAP.md

@@ -7,8 +7,8 @@
 - ✅ **v4.3** — 文本进阶：按字 / 词 / 行拆分的 `splitText()`，支持中日韩文字与 RTL，配合 `timeline()` 逐字编排。
 - ✅ **v4.4** — 无障碍增强：每个组件提供“静态替代”与 `aria-live` 规范，新增运动敏感度分级与自动化 a11y 回归测试。
 - ✅ **v4.5** — 性能与体积：按需加载 CSS、共享 rAF 调度器、动画数量自动降级，组件整体 gzip 目标 ≤ 70KB。
-- **v4.6** — 实验室 2.0：时间线可视化编辑（关键帧轨道）、保存 / 分享预设，并可导出为 `<usa-timeline>` 标记。
-- **v4.7** — 原生壳集成：WinUI 3、.NET MAUI、Flutter 的官方桥接示例包，支持系统“减少动态效果”与主题自动同步。
+- ✅ **v4.6** — 实验室 2.0：时间线可视化编辑（关键帧轨道）、保存 / 分享预设，并可导出为 `<usa-timeline>` 标记。
+- ✅ **v4.7** — 原生壳集成：WinUI 3、.NET MAUI、Flutter 的官方桥接示例包，支持系统“减少动态效果”与主题自动同步。
 - **v4.8** — 3D 与 WebGL 扩展：基于 `glQuad()` 的粒子 / 后处理小型预设库，统一 WebGL 回退与电量 / 帧率自适应。
 - **v4.9** — 5.0 预备：标记计划移除或重命名的 API 并输出一次性弃用警告，发布 `upgrading-5.md` 与自动迁移脚本（codemod）。
 - **v5.0** — 下一代主版本：仅支持现代浏览器（原生 View Transitions / Scroll Timeline 基线），移除 4.9 弃用的 API，统一的插件式效果注册机制。

package/docs/hybrid-apps.md

@@ -119,6 +119,21 @@ document.querySelector('usa-toggle').addEventListener('usa:change', (e) => invok
 
 Tauri uses WebView2 on Windows, WKWebView on macOS / iOS and WebKitGTK on Linux. WebKitGTK may disable WebGL on some drivers: WebGL components then set `data-fallback="webgl"` and show their CSS fallback.
 
+## Native shell bridge (4.7)
+
+`use-scroll-animate/components/bridge` keeps the page in sync with the host app's **system settings** — reduce motion, light / dark / high-contrast theme, accent color — on WinUI 3 / WPF (WebView2), .NET MAUI and Flutter:
+
+```js
+import { connectNativeShell } from 'use-scroll-animate/components/bridge';
+const { host } = connectNativeShell();   // 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser'
+```
+
+Protocol (JSON): the page sends `{"type":"usa:ready","version":1}` and `{"type":"usa:request-settings"}`; the host answers (and re-sends on every system change) with `{"type":"usa:settings","reducedMotion":true,"theme":"dark","accent":"#0078d4","sensitivity":"gentle"}` — via `PostWebMessageAsJson` (WebView2), `window.postMessage`, or by running `window.usaNative.apply({...})`. Incoming values are validated (unknown fields and non-color accents are dropped); settings only affect presentation.
+
+Complete samples: [examples/native](../examples/native/) — `winui3/MainWindow.xaml.cs` (`UISettings.AnimationsEnabled`, accent, high contrast), `maui/MainPage.xaml.cs` (Android animator scale, iOS Reduce Motion, Windows `UISettings`, `RequestedThemeChanged`), `flutter/lib/main.dart` (`MediaQuery.disableAnimations`, brightness, high contrast via a `UsaBridge` JavaScriptChannel).
+
+Helpers: `detectNativeHost()`, `postToNative(msg)`, `parseNativeSettings(data)`, `applyNativeSettings(settings)`; event `usa:native-settings` on `document`.
+
 ## Framework wrappers
 
 | Framework | Entry | What it gives you |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-scroll-animate",
-  "version": "4.5.0",
+  "version": "4.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",
@@ -358,6 +358,16 @@
         "default": "./dist/components/perf.cjs"
       }
     },
+    "./components/bridge": {
+      "import": {
+        "types": "./dist/components/bridge.d.ts",
+        "default": "./dist/components/bridge.js"
+      },
+      "require": {
+        "types": "./dist/components/bridge.d.cts",
+        "default": "./dist/components/bridge.cjs"
+      }
+    },
     "./components/lite": {
       "import": {
         "types": "./dist/components/lite.d.ts",