use-scroll-animate 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.7.0] - 2026-10-08
+
+### Added
+- **Native shell bridges** — new entry `use-scroll-animate/components/bridge` (also on `UsaComponents` in the UMD build): `connectNativeShell()` syncs the host app's **reduce motion**, **light / dark / high-contrast theme** and **accent color** (and optional motion-sensitivity level) into every `<usa-*>` component. JSON protocol `usa:ready` / `usa:request-settings` / `usa:settings` over WebView2 web messages, `window.postMessage` or `window.usaNative.apply()`; incoming values validated. Helpers `detectNativeHost()`, `postToNative()`, `parseNativeSettings()`, `applyNativeSettings()`; event `usa:native-settings`.
+- **Official samples** in [examples/native](./examples/native/): **WinUI 3** (`UISettings.AnimationsEnabled`, accent, high contrast → `PostWebMessageAsJson`), **.NET MAUI** (Android animator scale, iOS Reduce Motion, Windows `UISettings`, `RequestedThemeChanged` → `EvaluateJavaScriptAsync`), **Flutter** (`MediaQuery.disableAnimations`, brightness, high contrast via a `UsaBridge` JavaScriptChannel), sharing one web page.
+- Showcase: **connectNativeShell()** card (Page & app-wide) — simulate host messages on a demo tile.
+- Docs: "Native shell bridge" in [docs/hybrid-apps.md](./docs/hybrid-apps.md).
+
 ## [4.6.0] - 2026-10-08
 
 ### Added

package/dist/components/angular.cjs

@@ -29,6 +29,7 @@ require('./packs.cjs');
 require('./a11y.cjs');
 require('../chunks/index-tags-BQh_uGqH.cjs');
 require('./perf.cjs');
+require('./bridge.cjs');
 
 /**
  * use-scroll-animate/components/angular — Angular integration (v3.8).

package/dist/components/angular.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"angular.cjs","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":["defineComponents"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;;;;;"}
+{"version":3,"file":"angular.cjs","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":["defineComponents"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAEA,2BAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;;;;;"}

package/dist/components/angular.js

@@ -27,6 +27,7 @@ import './packs.js';
 import './a11y.js';
 import '../chunks/index-tags-43Xtd01A.js';
 import './perf.js';
+import './bridge.js';
 
 /**
  * use-scroll-animate/components/angular — Angular integration (v3.8).

package/dist/components/angular.js.map

@@ -1 +1 @@
-{"version":3,"file":"angular.js","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;"}
+{"version":3,"file":"angular.js","sources":["../../src/components/frameworks/angular.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/angular — Angular integration (v3.8).\n * Angular renders `<usa-*>` tags once the component (or NgModule) allows\n * custom elements with `CUSTOM_ELEMENTS_SCHEMA`; property binding\n * `[checked]=\"on\"` and event binding `(usa:change)=\"…\"` then work as is.\n * This entry is framework-free (no `@angular/*` import):\n *\n * ```ts\n * import { CUSTOM_ELEMENTS_SCHEMA, Component, APP_INITIALIZER } from '@angular/core';\n * import { usaInitializer } from 'use-scroll-animate/components/angular';\n *\n * // app.config.ts\n * providers: [{ provide: APP_INITIALIZER, multi: true, useFactory: usaInitializer(['click', 'ui']) }]\n *\n * @Component({ standalone: true, schemas: [CUSTOM_ELEMENTS_SCHEMA],\n *   template: `<usa-toggle [checked]=\"on\" (usa:change)=\"on = $any($event).detail.checked\"></usa-toggle>` })\n * ```\n * `bindUsa(el, { props, on })` is available for directives that bind imperatively.\n */\nimport { defineComponents, type ComponentCategory } from '../index';\n\nexport { bindUsa, usaEventName } from './bind';\nexport type { UsaBinding } from './bind';\n\n/** `APP_INITIALIZER` factory: registers the elements in the browser (no-op during SSR). */\nexport function usaInitializer(categories?: ComponentCategory[]): () => () => void {\n  return () => () => {\n    if (typeof window !== 'undefined') defineComponents(categories);\n  };\n}\n\n/** Register the elements directly (e.g. in `main.ts` before `bootstrapApplication`). */\nexport function defineUsa(categories?: ComponentCategory[]): void {\n  if (typeof window !== 'undefined') defineComponents(categories);\n}\n\n/** Read `event.detail` from a `usa:*` event in a template handler: `(usa:change)=\"on = usaDetail($event).checked\"`. */\nexport const usaDetail = <T = any>(e: Event): T => (e as CustomEvent<T>).detail;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;;;;;;;;;;;;;;;;;;AAkBG;AAMH;AACM,SAAU,cAAc,CAAC,UAAgC,EAAA;AAC7D,IAAA,OAAO,MAAM,MAAK;QAChB,IAAI,OAAO,MAAM,KAAK,WAAW;YAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE,IAAA,CAAC;AACH;AAEA;AACM,SAAU,SAAS,CAAC,UAAgC,EAAA;IACxD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,gBAAgB,CAAC,UAAU,CAAC;AACjE;AAEA;AACO,MAAM,SAAS,GAAG,CAAU,CAAQ,KAAS,CAAoB,CAAC;;;;"}

package/dist/components/bridge.cjs

@@ -0,0 +1,154 @@
+'use strict';
+
+var base = require('../chunks/base-CxYU2NK_.cjs');
+
+/**
+ * use-scroll-animate/components/bridge — native shell bridges (4.7).
+ *
+ * Keeps the web UI in sync with the host app's system settings when it runs
+ * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)
+ * or **Flutter** (webview_flutter / flutter_inappwebview): the native side
+ * sends "reduce motion", light / dark / high-contrast theme and accent color;
+ * the page applies them to every `<usa-*>` component.
+ *
+ * Protocol (JSON, both directions):
+ * - native → web `{ "type": "usa:settings", "reducedMotion": true, "theme": "dark", "accent": "#0078d4", "sensitivity": "gentle" }`
+ * - web → native `{ "type": "usa:ready", "version": 1 }` on connect, `{ "type": "usa:request-settings" }`
+ *
+ * Hosts that can only run script call `window.usaNative.apply({...})`.
+ * Samples: examples/native/{winui3,maui,flutter}.
+ */
+const BRIDGE_PROTOCOL_VERSION = 1;
+const win = () => (typeof window === 'undefined' ? null : window);
+/** Which native shell (if any) hosts this page. */
+function detectNativeHost(channel = 'UsaBridge') {
+    const w = win();
+    if (!w)
+        return 'browser';
+    if (w.chrome?.webview?.postMessage)
+        return 'webview2';
+    if (w.HybridWebView?.SendRawMessage || w.HybridWebView?.SendRawMessageToDotNet || /\bMAUI\b/i.test(w.navigator?.userAgent || ''))
+        return 'maui';
+    if (w.flutter_inappwebview?.callHandler || w[channel]?.postMessage)
+        return 'flutter';
+    if (w.__TAURI__ || w.__TAURI_INTERNALS__)
+        return 'tauri';
+    if (w.process?.versions?.electron || /Electron\//.test(w.navigator?.userAgent || ''))
+        return 'electron';
+    return 'browser';
+}
+/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */
+function postToNative(message, channel = 'UsaBridge') {
+    const w = win();
+    if (!w)
+        return false;
+    const json = JSON.stringify(message);
+    try {
+        if (w.chrome?.webview?.postMessage)
+            return w.chrome.webview.postMessage(message), true;
+        if (w.HybridWebView?.SendRawMessage)
+            return w.HybridWebView.SendRawMessage(json), true;
+        if (w.HybridWebView?.SendRawMessageToDotNet)
+            return w.HybridWebView.SendRawMessageToDotNet(json), true;
+        if (w.flutter_inappwebview?.callHandler)
+            return w.flutter_inappwebview.callHandler(channel, json), true;
+        if (w[channel]?.postMessage)
+            return w[channel].postMessage(json), true;
+    }
+    catch {
+        /* host went away */
+    }
+    return false;
+}
+const THEMES = ['light', 'dark', 'high-contrast'];
+const COLOR = /^(#[0-9a-f]{3,8}|rgba?\([\d\s.,%]+\)|hsla?\([\d\s.,%deg]+\))$/i;
+/** Validate an incoming message (string or object); unknown fields are dropped. */
+function parseNativeSettings(data) {
+    let d = data;
+    if (typeof d === 'string') {
+        try {
+            d = JSON.parse(d);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!d || typeof d !== 'object' || d.type !== 'usa:settings')
+        return null;
+    const out = {};
+    if (typeof d.reducedMotion === 'boolean')
+        out.reducedMotion = d.reducedMotion;
+    if (THEMES.includes(d.theme))
+        out.theme = d.theme;
+    if (typeof d.accent === 'string' && COLOR.test(d.accent.trim()))
+        out.accent = d.accent.trim();
+    if (base.MOTION_SENSITIVITY_LEVELS.includes(d.sensitivity))
+        out.sensitivity = d.sensitivity;
+    return out;
+}
+/**
+ * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`
+ * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`
+ * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.
+ */
+function applyNativeSettings(s, root) {
+    if (s.reducedMotion !== undefined)
+        base.configureComponents({ reducedMotion: s.reducedMotion ? 'reduce' : 'user' });
+    if (s.sensitivity)
+        base.configureComponents({ motionSensitivity: s.sensitivity });
+    const el = root || (typeof document !== 'undefined' ? document.documentElement : null);
+    if (!el)
+        return;
+    if (s.theme) {
+        el.setAttribute('data-theme', s.theme === 'high-contrast' ? 'dark' : s.theme);
+        el.toggleAttribute('data-usa-contrast', s.theme === 'high-contrast');
+        el.style.colorScheme = s.theme === 'light' ? 'light' : 'dark';
+    }
+    if (s.accent)
+        el.style.setProperty('--usa-accent', s.accent);
+    if (typeof document !== 'undefined')
+        document.dispatchEvent(new CustomEvent('usa:native-settings', { detail: s }));
+}
+/**
+ * Connect to the native shell: listens for `usa:settings` messages
+ * (WebView2 `chrome.webview` messages, `window.postMessage`, or
+ * `window.usaNative.apply()`), applies them, then announces `usa:ready` and
+ * asks for the current settings. Returns `{ host, disconnect }`.
+ */
+function connectNativeShell(options = {}) {
+    const w = win();
+    const channel = options.channel || 'UsaBridge';
+    const host = detectNativeHost(channel);
+    if (!w)
+        return { host, disconnect: () => undefined };
+    const handle = (data) => {
+        const s = parseNativeSettings(data);
+        if (!s)
+            return;
+        applyNativeSettings(s, options.root);
+        options.onSettings?.(s, host);
+    };
+    const onMessage = (e) => handle(e.data);
+    w.chrome?.webview?.addEventListener?.('message', onMessage);
+    w.addEventListener?.('message', onMessage);
+    const prev = w.usaNative;
+    w.usaNative = { apply: (s) => handle({ ...s, type: 'usa:settings' }), version: BRIDGE_PROTOCOL_VERSION, host };
+    postToNative({ type: 'usa:ready', version: BRIDGE_PROTOCOL_VERSION }, channel);
+    postToNative({ type: 'usa:request-settings' }, channel);
+    return {
+        host,
+        disconnect: () => {
+            w.chrome?.webview?.removeEventListener?.('message', onMessage);
+            w.removeEventListener?.('message', onMessage);
+            w.usaNative = prev;
+        },
+    };
+}
+
+exports.BRIDGE_PROTOCOL_VERSION = BRIDGE_PROTOCOL_VERSION;
+exports.applyNativeSettings = applyNativeSettings;
+exports.connectNativeShell = connectNativeShell;
+exports.detectNativeHost = detectNativeHost;
+exports.parseNativeSettings = parseNativeSettings;
+exports.postToNative = postToNative;
+//# sourceMappingURL=bridge.cjs.map

package/dist/components/bridge.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.cjs","sources":["../../src/components/bridge/index.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/bridge — native shell bridges (4.7).\n *\n * Keeps the web UI in sync with the host app's system settings when it runs\n * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)\n * or **Flutter** (webview_flutter / flutter_inappwebview): the native side\n * sends \"reduce motion\", light / dark / high-contrast theme and accent color;\n * the page applies them to every `<usa-*>` component.\n *\n * Protocol (JSON, both directions):\n * - native → web `{ \"type\": \"usa:settings\", \"reducedMotion\": true, \"theme\": \"dark\", \"accent\": \"#0078d4\", \"sensitivity\": \"gentle\" }`\n * - web → native `{ \"type\": \"usa:ready\", \"version\": 1 }` on connect, `{ \"type\": \"usa:request-settings\" }`\n *\n * Hosts that can only run script call `window.usaNative.apply({...})`.\n * Samples: examples/native/{winui3,maui,flutter}.\n */\nimport { configureComponents, MOTION_SENSITIVITY_LEVELS, type MotionSensitivity } from '../base';\n\nexport type NativeHost = 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser';\nexport type NativeTheme = 'light' | 'dark' | 'high-contrast';\n\nexport interface NativeSettings {\n  reducedMotion?: boolean;\n  theme?: NativeTheme;\n  /** CSS color (`#0078d4`, `rgb(…)`). */\n  accent?: string;\n  /** Optional finer level (4.4). */\n  sensitivity?: MotionSensitivity;\n}\n\nexport interface NativeShellOptions {\n  /** Element that gets `data-theme` / `color-scheme` / `--usa-accent` (default `<html>`). */\n  root?: HTMLElement;\n  /** Flutter JavaScriptChannel name (default `UsaBridge`). */\n  channel?: string;\n  /** Called after settings are applied. */\n  onSettings?: (settings: NativeSettings, host: NativeHost) => void;\n}\n\nexport const BRIDGE_PROTOCOL_VERSION = 1;\n\ntype W = Record<string, any>;\nconst win = (): W | null => (typeof window === 'undefined' ? null : (window as unknown as W));\n\n/** Which native shell (if any) hosts this page. */\nexport function detectNativeHost(channel = 'UsaBridge'): NativeHost {\n  const w = win();\n  if (!w) return 'browser';\n  if (w.chrome?.webview?.postMessage) return 'webview2';\n  if (w.HybridWebView?.SendRawMessage || w.HybridWebView?.SendRawMessageToDotNet || /\\bMAUI\\b/i.test(w.navigator?.userAgent || '')) return 'maui';\n  if (w.flutter_inappwebview?.callHandler || w[channel]?.postMessage) return 'flutter';\n  if (w.__TAURI__ || w.__TAURI_INTERNALS__) return 'tauri';\n  if (w.process?.versions?.electron || /Electron\\//.test(w.navigator?.userAgent || '')) return 'electron';\n  return 'browser';\n}\n\n/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */\nexport function postToNative(message: Record<string, unknown>, channel = 'UsaBridge'): boolean {\n  const w = win();\n  if (!w) return false;\n  const json = JSON.stringify(message);\n  try {\n    if (w.chrome?.webview?.postMessage) return w.chrome.webview.postMessage(message), true;\n    if (w.HybridWebView?.SendRawMessage) return w.HybridWebView.SendRawMessage(json), true;\n    if (w.HybridWebView?.SendRawMessageToDotNet) return w.HybridWebView.SendRawMessageToDotNet(json), true;\n    if (w.flutter_inappwebview?.callHandler) return w.flutter_inappwebview.callHandler(channel, json), true;\n    if (w[channel]?.postMessage) return w[channel].postMessage(json), true;\n  } catch {\n    /* host went away */\n  }\n  return false;\n}\n\nconst THEMES: NativeTheme[] = ['light', 'dark', 'high-contrast'];\nconst COLOR = /^(#[0-9a-f]{3,8}|rgba?\\([\\d\\s.,%]+\\)|hsla?\\([\\d\\s.,%deg]+\\))$/i;\n\n/** Validate an incoming message (string or object); unknown fields are dropped. */\nexport function parseNativeSettings(data: unknown): NativeSettings | null {\n  let d: any = data;\n  if (typeof d === 'string') {\n    try {\n      d = JSON.parse(d);\n    } catch {\n      return null;\n    }\n  }\n  if (!d || typeof d !== 'object' || d.type !== 'usa:settings') return null;\n  const out: NativeSettings = {};\n  if (typeof d.reducedMotion === 'boolean') out.reducedMotion = d.reducedMotion;\n  if (THEMES.includes(d.theme)) out.theme = d.theme;\n  if (typeof d.accent === 'string' && COLOR.test(d.accent.trim())) out.accent = d.accent.trim();\n  if (MOTION_SENSITIVITY_LEVELS.includes(d.sensitivity)) out.sensitivity = d.sensitivity;\n  return out;\n}\n\n/**\n * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`\n * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`\n * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.\n */\nexport function applyNativeSettings(s: NativeSettings, root?: HTMLElement): void {\n  if (s.reducedMotion !== undefined) configureComponents({ reducedMotion: s.reducedMotion ? 'reduce' : 'user' });\n  if (s.sensitivity) configureComponents({ motionSensitivity: s.sensitivity });\n  const el = root || (typeof document !== 'undefined' ? document.documentElement : null);\n  if (!el) return;\n  if (s.theme) {\n    el.setAttribute('data-theme', s.theme === 'high-contrast' ? 'dark' : s.theme);\n    el.toggleAttribute('data-usa-contrast', s.theme === 'high-contrast');\n    el.style.colorScheme = s.theme === 'light' ? 'light' : 'dark';\n  }\n  if (s.accent) el.style.setProperty('--usa-accent', s.accent);\n  if (typeof document !== 'undefined') document.dispatchEvent(new CustomEvent('usa:native-settings', { detail: s }));\n}\n\n/**\n * Connect to the native shell: listens for `usa:settings` messages\n * (WebView2 `chrome.webview` messages, `window.postMessage`, or\n * `window.usaNative.apply()`), applies them, then announces `usa:ready` and\n * asks for the current settings. Returns `{ host, disconnect }`.\n */\nexport function connectNativeShell(options: NativeShellOptions = {}): { host: NativeHost; disconnect: () => void } {\n  const w = win();\n  const channel = options.channel || 'UsaBridge';\n  const host = detectNativeHost(channel);\n  if (!w) return { host, disconnect: () => undefined };\n  const handle = (data: unknown) => {\n    const s = parseNativeSettings(data);\n    if (!s) return;\n    applyNativeSettings(s, options.root);\n    options.onSettings?.(s, host);\n  };\n  const onMessage = (e: MessageEvent) => handle(e.data);\n  w.chrome?.webview?.addEventListener?.('message', onMessage);\n  w.addEventListener?.('message', onMessage);\n  const prev = w.usaNative;\n  w.usaNative = { apply: (s: NativeSettings) => handle({ ...s, type: 'usa:settings' }), version: BRIDGE_PROTOCOL_VERSION, host };\n  postToNative({ type: 'usa:ready', version: BRIDGE_PROTOCOL_VERSION }, channel);\n  postToNative({ type: 'usa:request-settings' }, channel);\n  return {\n    host,\n    disconnect: () => {\n      w.chrome?.webview?.removeEventListener?.('message', onMessage);\n      w.removeEventListener?.('message', onMessage);\n      w.usaNative = prev;\n    },\n  };\n}\n"],"names":["MOTION_SENSITIVITY_LEVELS","configureComponents"],"mappings":"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"}

package/dist/components/bridge.d.cts

@@ -0,0 +1,63 @@
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
+
+/**
+ * use-scroll-animate/components/bridge — native shell bridges (4.7).
+ *
+ * Keeps the web UI in sync with the host app's system settings when it runs
+ * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)
+ * or **Flutter** (webview_flutter / flutter_inappwebview): the native side
+ * sends "reduce motion", light / dark / high-contrast theme and accent color;
+ * the page applies them to every `<usa-*>` component.
+ *
+ * Protocol (JSON, both directions):
+ * - native → web `{ "type": "usa:settings", "reducedMotion": true, "theme": "dark", "accent": "#0078d4", "sensitivity": "gentle" }`
+ * - web → native `{ "type": "usa:ready", "version": 1 }` on connect, `{ "type": "usa:request-settings" }`
+ *
+ * Hosts that can only run script call `window.usaNative.apply({...})`.
+ * Samples: examples/native/{winui3,maui,flutter}.
+ */
+
+type NativeHost = 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser';
+type NativeTheme = 'light' | 'dark' | 'high-contrast';
+interface NativeSettings {
+    reducedMotion?: boolean;
+    theme?: NativeTheme;
+    /** CSS color (`#0078d4`, `rgb(…)`). */
+    accent?: string;
+    /** Optional finer level (4.4). */
+    sensitivity?: MotionSensitivity;
+}
+interface NativeShellOptions {
+    /** Element that gets `data-theme` / `color-scheme` / `--usa-accent` (default `<html>`). */
+    root?: HTMLElement;
+    /** Flutter JavaScriptChannel name (default `UsaBridge`). */
+    channel?: string;
+    /** Called after settings are applied. */
+    onSettings?: (settings: NativeSettings, host: NativeHost) => void;
+}
+declare const BRIDGE_PROTOCOL_VERSION = 1;
+/** Which native shell (if any) hosts this page. */
+declare function detectNativeHost(channel?: string): NativeHost;
+/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */
+declare function postToNative(message: Record<string, unknown>, channel?: string): boolean;
+/** Validate an incoming message (string or object); unknown fields are dropped. */
+declare function parseNativeSettings(data: unknown): NativeSettings | null;
+/**
+ * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`
+ * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`
+ * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.
+ */
+declare function applyNativeSettings(s: NativeSettings, root?: HTMLElement): void;
+/**
+ * Connect to the native shell: listens for `usa:settings` messages
+ * (WebView2 `chrome.webview` messages, `window.postMessage`, or
+ * `window.usaNative.apply()`), applies them, then announces `usa:ready` and
+ * asks for the current settings. Returns `{ host, disconnect }`.
+ */
+declare function connectNativeShell(options?: NativeShellOptions): {
+    host: NativeHost;
+    disconnect: () => void;
+};
+
+export { BRIDGE_PROTOCOL_VERSION, applyNativeSettings, connectNativeShell, detectNativeHost, parseNativeSettings, postToNative };
+export type { NativeHost, NativeSettings, NativeShellOptions, NativeTheme };

package/dist/components/bridge.d.ts

@@ -0,0 +1,63 @@
+type MotionSensitivity = 'full' | 'gentle' | 'minimal' | 'static';
+
+/**
+ * use-scroll-animate/components/bridge — native shell bridges (4.7).
+ *
+ * Keeps the web UI in sync with the host app's system settings when it runs
+ * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)
+ * or **Flutter** (webview_flutter / flutter_inappwebview): the native side
+ * sends "reduce motion", light / dark / high-contrast theme and accent color;
+ * the page applies them to every `<usa-*>` component.
+ *
+ * Protocol (JSON, both directions):
+ * - native → web `{ "type": "usa:settings", "reducedMotion": true, "theme": "dark", "accent": "#0078d4", "sensitivity": "gentle" }`
+ * - web → native `{ "type": "usa:ready", "version": 1 }` on connect, `{ "type": "usa:request-settings" }`
+ *
+ * Hosts that can only run script call `window.usaNative.apply({...})`.
+ * Samples: examples/native/{winui3,maui,flutter}.
+ */
+
+type NativeHost = 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser';
+type NativeTheme = 'light' | 'dark' | 'high-contrast';
+interface NativeSettings {
+    reducedMotion?: boolean;
+    theme?: NativeTheme;
+    /** CSS color (`#0078d4`, `rgb(…)`). */
+    accent?: string;
+    /** Optional finer level (4.4). */
+    sensitivity?: MotionSensitivity;
+}
+interface NativeShellOptions {
+    /** Element that gets `data-theme` / `color-scheme` / `--usa-accent` (default `<html>`). */
+    root?: HTMLElement;
+    /** Flutter JavaScriptChannel name (default `UsaBridge`). */
+    channel?: string;
+    /** Called after settings are applied. */
+    onSettings?: (settings: NativeSettings, host: NativeHost) => void;
+}
+declare const BRIDGE_PROTOCOL_VERSION = 1;
+/** Which native shell (if any) hosts this page. */
+declare function detectNativeHost(channel?: string): NativeHost;
+/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */
+declare function postToNative(message: Record<string, unknown>, channel?: string): boolean;
+/** Validate an incoming message (string or object); unknown fields are dropped. */
+declare function parseNativeSettings(data: unknown): NativeSettings | null;
+/**
+ * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`
+ * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`
+ * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.
+ */
+declare function applyNativeSettings(s: NativeSettings, root?: HTMLElement): void;
+/**
+ * Connect to the native shell: listens for `usa:settings` messages
+ * (WebView2 `chrome.webview` messages, `window.postMessage`, or
+ * `window.usaNative.apply()`), applies them, then announces `usa:ready` and
+ * asks for the current settings. Returns `{ host, disconnect }`.
+ */
+declare function connectNativeShell(options?: NativeShellOptions): {
+    host: NativeHost;
+    disconnect: () => void;
+};
+
+export { BRIDGE_PROTOCOL_VERSION, applyNativeSettings, connectNativeShell, detectNativeHost, parseNativeSettings, postToNative };
+export type { NativeHost, NativeSettings, NativeShellOptions, NativeTheme };

package/dist/components/bridge.js

@@ -0,0 +1,147 @@
+import { f as configureComponents, a as MOTION_SENSITIVITY_LEVELS } from '../chunks/base-CZiIAMBc.js';
+
+/**
+ * use-scroll-animate/components/bridge — native shell bridges (4.7).
+ *
+ * Keeps the web UI in sync with the host app's system settings when it runs
+ * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)
+ * or **Flutter** (webview_flutter / flutter_inappwebview): the native side
+ * sends "reduce motion", light / dark / high-contrast theme and accent color;
+ * the page applies them to every `<usa-*>` component.
+ *
+ * Protocol (JSON, both directions):
+ * - native → web `{ "type": "usa:settings", "reducedMotion": true, "theme": "dark", "accent": "#0078d4", "sensitivity": "gentle" }`
+ * - web → native `{ "type": "usa:ready", "version": 1 }` on connect, `{ "type": "usa:request-settings" }`
+ *
+ * Hosts that can only run script call `window.usaNative.apply({...})`.
+ * Samples: examples/native/{winui3,maui,flutter}.
+ */
+const BRIDGE_PROTOCOL_VERSION = 1;
+const win = () => (typeof window === 'undefined' ? null : window);
+/** Which native shell (if any) hosts this page. */
+function detectNativeHost(channel = 'UsaBridge') {
+    const w = win();
+    if (!w)
+        return 'browser';
+    if (w.chrome?.webview?.postMessage)
+        return 'webview2';
+    if (w.HybridWebView?.SendRawMessage || w.HybridWebView?.SendRawMessageToDotNet || /\bMAUI\b/i.test(w.navigator?.userAgent || ''))
+        return 'maui';
+    if (w.flutter_inappwebview?.callHandler || w[channel]?.postMessage)
+        return 'flutter';
+    if (w.__TAURI__ || w.__TAURI_INTERNALS__)
+        return 'tauri';
+    if (w.process?.versions?.electron || /Electron\//.test(w.navigator?.userAgent || ''))
+        return 'electron';
+    return 'browser';
+}
+/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */
+function postToNative(message, channel = 'UsaBridge') {
+    const w = win();
+    if (!w)
+        return false;
+    const json = JSON.stringify(message);
+    try {
+        if (w.chrome?.webview?.postMessage)
+            return w.chrome.webview.postMessage(message), true;
+        if (w.HybridWebView?.SendRawMessage)
+            return w.HybridWebView.SendRawMessage(json), true;
+        if (w.HybridWebView?.SendRawMessageToDotNet)
+            return w.HybridWebView.SendRawMessageToDotNet(json), true;
+        if (w.flutter_inappwebview?.callHandler)
+            return w.flutter_inappwebview.callHandler(channel, json), true;
+        if (w[channel]?.postMessage)
+            return w[channel].postMessage(json), true;
+    }
+    catch {
+        /* host went away */
+    }
+    return false;
+}
+const THEMES = ['light', 'dark', 'high-contrast'];
+const COLOR = /^(#[0-9a-f]{3,8}|rgba?\([\d\s.,%]+\)|hsla?\([\d\s.,%deg]+\))$/i;
+/** Validate an incoming message (string or object); unknown fields are dropped. */
+function parseNativeSettings(data) {
+    let d = data;
+    if (typeof d === 'string') {
+        try {
+            d = JSON.parse(d);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!d || typeof d !== 'object' || d.type !== 'usa:settings')
+        return null;
+    const out = {};
+    if (typeof d.reducedMotion === 'boolean')
+        out.reducedMotion = d.reducedMotion;
+    if (THEMES.includes(d.theme))
+        out.theme = d.theme;
+    if (typeof d.accent === 'string' && COLOR.test(d.accent.trim()))
+        out.accent = d.accent.trim();
+    if (MOTION_SENSITIVITY_LEVELS.includes(d.sensitivity))
+        out.sensitivity = d.sensitivity;
+    return out;
+}
+/**
+ * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`
+ * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`
+ * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.
+ */
+function applyNativeSettings(s, root) {
+    if (s.reducedMotion !== undefined)
+        configureComponents({ reducedMotion: s.reducedMotion ? 'reduce' : 'user' });
+    if (s.sensitivity)
+        configureComponents({ motionSensitivity: s.sensitivity });
+    const el = root || (typeof document !== 'undefined' ? document.documentElement : null);
+    if (!el)
+        return;
+    if (s.theme) {
+        el.setAttribute('data-theme', s.theme === 'high-contrast' ? 'dark' : s.theme);
+        el.toggleAttribute('data-usa-contrast', s.theme === 'high-contrast');
+        el.style.colorScheme = s.theme === 'light' ? 'light' : 'dark';
+    }
+    if (s.accent)
+        el.style.setProperty('--usa-accent', s.accent);
+    if (typeof document !== 'undefined')
+        document.dispatchEvent(new CustomEvent('usa:native-settings', { detail: s }));
+}
+/**
+ * Connect to the native shell: listens for `usa:settings` messages
+ * (WebView2 `chrome.webview` messages, `window.postMessage`, or
+ * `window.usaNative.apply()`), applies them, then announces `usa:ready` and
+ * asks for the current settings. Returns `{ host, disconnect }`.
+ */
+function connectNativeShell(options = {}) {
+    const w = win();
+    const channel = options.channel || 'UsaBridge';
+    const host = detectNativeHost(channel);
+    if (!w)
+        return { host, disconnect: () => undefined };
+    const handle = (data) => {
+        const s = parseNativeSettings(data);
+        if (!s)
+            return;
+        applyNativeSettings(s, options.root);
+        options.onSettings?.(s, host);
+    };
+    const onMessage = (e) => handle(e.data);
+    w.chrome?.webview?.addEventListener?.('message', onMessage);
+    w.addEventListener?.('message', onMessage);
+    const prev = w.usaNative;
+    w.usaNative = { apply: (s) => handle({ ...s, type: 'usa:settings' }), version: BRIDGE_PROTOCOL_VERSION, host };
+    postToNative({ type: 'usa:ready', version: BRIDGE_PROTOCOL_VERSION }, channel);
+    postToNative({ type: 'usa:request-settings' }, channel);
+    return {
+        host,
+        disconnect: () => {
+            w.chrome?.webview?.removeEventListener?.('message', onMessage);
+            w.removeEventListener?.('message', onMessage);
+            w.usaNative = prev;
+        },
+    };
+}
+
+export { BRIDGE_PROTOCOL_VERSION, applyNativeSettings, connectNativeShell, detectNativeHost, parseNativeSettings, postToNative };
+//# sourceMappingURL=bridge.js.map

package/dist/components/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sources":["../../src/components/bridge/index.ts"],"sourcesContent":["/**\n * use-scroll-animate/components/bridge — native shell bridges (4.7).\n *\n * Keeps the web UI in sync with the host app's system settings when it runs\n * inside **WinUI 3 / WPF (WebView2)**, **.NET MAUI** (WebView / HybridWebView)\n * or **Flutter** (webview_flutter / flutter_inappwebview): the native side\n * sends \"reduce motion\", light / dark / high-contrast theme and accent color;\n * the page applies them to every `<usa-*>` component.\n *\n * Protocol (JSON, both directions):\n * - native → web `{ \"type\": \"usa:settings\", \"reducedMotion\": true, \"theme\": \"dark\", \"accent\": \"#0078d4\", \"sensitivity\": \"gentle\" }`\n * - web → native `{ \"type\": \"usa:ready\", \"version\": 1 }` on connect, `{ \"type\": \"usa:request-settings\" }`\n *\n * Hosts that can only run script call `window.usaNative.apply({...})`.\n * Samples: examples/native/{winui3,maui,flutter}.\n */\nimport { configureComponents, MOTION_SENSITIVITY_LEVELS, type MotionSensitivity } from '../base';\n\nexport type NativeHost = 'webview2' | 'maui' | 'flutter' | 'electron' | 'tauri' | 'browser';\nexport type NativeTheme = 'light' | 'dark' | 'high-contrast';\n\nexport interface NativeSettings {\n  reducedMotion?: boolean;\n  theme?: NativeTheme;\n  /** CSS color (`#0078d4`, `rgb(…)`). */\n  accent?: string;\n  /** Optional finer level (4.4). */\n  sensitivity?: MotionSensitivity;\n}\n\nexport interface NativeShellOptions {\n  /** Element that gets `data-theme` / `color-scheme` / `--usa-accent` (default `<html>`). */\n  root?: HTMLElement;\n  /** Flutter JavaScriptChannel name (default `UsaBridge`). */\n  channel?: string;\n  /** Called after settings are applied. */\n  onSettings?: (settings: NativeSettings, host: NativeHost) => void;\n}\n\nexport const BRIDGE_PROTOCOL_VERSION = 1;\n\ntype W = Record<string, any>;\nconst win = (): W | null => (typeof window === 'undefined' ? null : (window as unknown as W));\n\n/** Which native shell (if any) hosts this page. */\nexport function detectNativeHost(channel = 'UsaBridge'): NativeHost {\n  const w = win();\n  if (!w) return 'browser';\n  if (w.chrome?.webview?.postMessage) return 'webview2';\n  if (w.HybridWebView?.SendRawMessage || w.HybridWebView?.SendRawMessageToDotNet || /\\bMAUI\\b/i.test(w.navigator?.userAgent || '')) return 'maui';\n  if (w.flutter_inappwebview?.callHandler || w[channel]?.postMessage) return 'flutter';\n  if (w.__TAURI__ || w.__TAURI_INTERNALS__) return 'tauri';\n  if (w.process?.versions?.electron || /Electron\\//.test(w.navigator?.userAgent || '')) return 'electron';\n  return 'browser';\n}\n\n/** Send a JSON message to the native host (no-op in a plain browser). Returns whether it was sent. */\nexport function postToNative(message: Record<string, unknown>, channel = 'UsaBridge'): boolean {\n  const w = win();\n  if (!w) return false;\n  const json = JSON.stringify(message);\n  try {\n    if (w.chrome?.webview?.postMessage) return w.chrome.webview.postMessage(message), true;\n    if (w.HybridWebView?.SendRawMessage) return w.HybridWebView.SendRawMessage(json), true;\n    if (w.HybridWebView?.SendRawMessageToDotNet) return w.HybridWebView.SendRawMessageToDotNet(json), true;\n    if (w.flutter_inappwebview?.callHandler) return w.flutter_inappwebview.callHandler(channel, json), true;\n    if (w[channel]?.postMessage) return w[channel].postMessage(json), true;\n  } catch {\n    /* host went away */\n  }\n  return false;\n}\n\nconst THEMES: NativeTheme[] = ['light', 'dark', 'high-contrast'];\nconst COLOR = /^(#[0-9a-f]{3,8}|rgba?\\([\\d\\s.,%]+\\)|hsla?\\([\\d\\s.,%deg]+\\))$/i;\n\n/** Validate an incoming message (string or object); unknown fields are dropped. */\nexport function parseNativeSettings(data: unknown): NativeSettings | null {\n  let d: any = data;\n  if (typeof d === 'string') {\n    try {\n      d = JSON.parse(d);\n    } catch {\n      return null;\n    }\n  }\n  if (!d || typeof d !== 'object' || d.type !== 'usa:settings') return null;\n  const out: NativeSettings = {};\n  if (typeof d.reducedMotion === 'boolean') out.reducedMotion = d.reducedMotion;\n  if (THEMES.includes(d.theme)) out.theme = d.theme;\n  if (typeof d.accent === 'string' && COLOR.test(d.accent.trim())) out.accent = d.accent.trim();\n  if (MOTION_SENSITIVITY_LEVELS.includes(d.sensitivity)) out.sensitivity = d.sensitivity;\n  return out;\n}\n\n/**\n * Apply native settings: reduce motion → `configureComponents({ reducedMotion: 'reduce' })`\n * (`false` → follow the media query again); theme → `data-theme`, `data-usa-contrast`\n * and `color-scheme`; accent → `--usa-accent`; sensitivity → `motionSensitivity`.\n */\nexport function applyNativeSettings(s: NativeSettings, root?: HTMLElement): void {\n  if (s.reducedMotion !== undefined) configureComponents({ reducedMotion: s.reducedMotion ? 'reduce' : 'user' });\n  if (s.sensitivity) configureComponents({ motionSensitivity: s.sensitivity });\n  const el = root || (typeof document !== 'undefined' ? document.documentElement : null);\n  if (!el) return;\n  if (s.theme) {\n    el.setAttribute('data-theme', s.theme === 'high-contrast' ? 'dark' : s.theme);\n    el.toggleAttribute('data-usa-contrast', s.theme === 'high-contrast');\n    el.style.colorScheme = s.theme === 'light' ? 'light' : 'dark';\n  }\n  if (s.accent) el.style.setProperty('--usa-accent', s.accent);\n  if (typeof document !== 'undefined') document.dispatchEvent(new CustomEvent('usa:native-settings', { detail: s }));\n}\n\n/**\n * Connect to the native shell: listens for `usa:settings` messages\n * (WebView2 `chrome.webview` messages, `window.postMessage`, or\n * `window.usaNative.apply()`), applies them, then announces `usa:ready` and\n * asks for the current settings. Returns `{ host, disconnect }`.\n */\nexport function connectNativeShell(options: NativeShellOptions = {}): { host: NativeHost; disconnect: () => void } {\n  const w = win();\n  const channel = options.channel || 'UsaBridge';\n  const host = detectNativeHost(channel);\n  if (!w) return { host, disconnect: () => undefined };\n  const handle = (data: unknown) => {\n    const s = parseNativeSettings(data);\n    if (!s) return;\n    applyNativeSettings(s, options.root);\n    options.onSettings?.(s, host);\n  };\n  const onMessage = (e: MessageEvent) => handle(e.data);\n  w.chrome?.webview?.addEventListener?.('message', onMessage);\n  w.addEventListener?.('message', onMessage);\n  const prev = w.usaNative;\n  w.usaNative = { apply: (s: NativeSettings) => handle({ ...s, type: 'usa:settings' }), version: BRIDGE_PROTOCOL_VERSION, host };\n  postToNative({ type: 'usa:ready', version: BRIDGE_PROTOCOL_VERSION }, channel);\n  postToNative({ type: 'usa:request-settings' }, channel);\n  return {\n    host,\n    disconnect: () => {\n      w.chrome?.webview?.removeEventListener?.('message', onMessage);\n      w.removeEventListener?.('message', onMessage);\n      w.usaNative = prev;\n    },\n  };\n}\n"],"names":[],"mappings":"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"}