use-scroll-animate 4.6.0 → 4.8.0

package/docs/ROADMAP.md

@@ -8,7 +8,7 @@
 - ✅ **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.8** — 3D 与 WebGL 扩展：基于 `glQuad()` 的粒子 / 后处理小型预设库，统一 WebGL 回退与电量 / 帧率自适应。
+- ✅ **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/components.md

@@ -315,6 +315,13 @@ Hybrid / desktop hosts (MAUI, Flutter WebView, Electron, Tauri): [hybrid-apps.md
 
 **Deprecated in 3.9, removed in 4.0.0:** `sequence()`, `connectedAnimation()`, `<usa-flip-list>` — see [upgrading-4.md](./upgrading-4.md).
 
+### v4.8 GPU particles, post-processing & adaptive quality (`components/webgl`)
+
+- **Particle presets** for `<usa-shader preset="…">`: `snow`, `fireflies`, `stars` (warp starfield), `bokeh`, `rain` — procedural in the fragment shader, no buffers or per-particle JS.
+- **`<usa-post-fx>`** (`definePostFx()`), e.g. `<usa-post-fx effects="vignette grain" intensity="0.6"><img …></usa-post-fx>` — chained passes `vignette` · `grain` · `chromatic` · `scanlines` · `crt` · `bloom` · `pixelate` · `duotone` · `glitch`; `postFxShader(list)` builds the same shader for your own `glQuad()`.
+- **Unified fallback** — without WebGL every preset shows a still CSS rendering (`GL_FALLBACKS`, `glFallbackCss()`); post-fx images get an approximate CSS filter.
+- **Adaptive quality** — every GL element measures its frame rate: after two slow seconds (< 40 fps) the drawing buffer drops to 50 % then 35 % resolution and climbs back after five good seconds; on battery saver (Battery Status API ≤ 20 % and not charging, or Save-Data) it renders at ≤ 30 fps and ≤ 60 % resolution. `quality="high"` opts out; `data-quality` shows the current scale. `glGovernor()` / `watchPowerSaver()` for your own loops; `glQuad().render({ extra })` sets any float uniform, `resize(scale)` scales the buffer.
+
 ## Frameworks
 
 Custom elements work in every framework. Register once (e.g. in your entry file), then use the tags.

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.6.0",
+  "version": "4.8.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",