talking-head-studio 0.2.7 → 0.2.9

package/dist/TalkingHead.d.ts

@@ -1,6 +1,11 @@
 import React from 'react';
 import { type StyleProp, type ViewStyle } from 'react-native';
 export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'excited' | 'thinking' | 'concerned' | 'surprised';
+export type TalkingHeadLoadingStage = 'booting' | 'fetching_model' | 'loading_avatar' | 'loading_fallback' | 'ready';
+export interface TalkingHeadLoadingState {
+    stage: TalkingHeadLoadingStage;
+    progress?: number | null;
+}
 /**
  * Standard viseme keys supported by the avatar.
  * Use with sendViseme() from your TTS viseme callbacks.
@@ -46,9 +51,12 @@ export interface TalkingHeadProps {
     skinColor?: string;
     eyeColor?: string;
     accessories?: TalkingHeadAccessory[];
+    onLoadingChange?: (state: TalkingHeadLoadingState) => void;
     onReady?: () => void;
     onError?: (message: string) => void;
     style?: StyleProp<ViewStyle>;
+    /** Base URL for vendored assets. When set, replaces all cdn.jsdelivr.net references. */
+    vendorBaseUrl?: string | null;
 }
 export interface TalkingHeadRef {
     sendAmplitude: (amplitude: number) => void;

package/dist/TalkingHead.js

@@ -6,10 +6,23 @@ const react_1 = require("react");
 const react_native_1 = require("react-native");
 const react_native_webview_1 = require("react-native-webview");
 const html_1 = require("./html");
-exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onReady, onError, style, }, ref) => {
+exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onLoadingChange, onReady, onError, style, vendorBaseUrl, }, ref) => {
     const webViewRef = (0, react_1.useRef)(null);
     const readyRef = (0, react_1.useRef)(false);
+    const firstMessageSeenRef = (0, react_1.useRef)(false);
+    const bootTimerRef = (0, react_1.useRef)(null);
+    const pendingMoodRef = (0, react_1.useRef)(mood);
+    const pendingHairColorRef = (0, react_1.useRef)(hairColor);
+    const pendingSkinColorRef = (0, react_1.useRef)(skinColor);
+    const pendingEyeColorRef = (0, react_1.useRef)(eyeColor);
     const accessoriesRef = (0, react_1.useRef)(accessories);
+    // Stable refs for callbacks so they never retrigger the boot effect.
+    const onLoadingChangeRef = (0, react_1.useRef)(onLoadingChange);
+    onLoadingChangeRef.current = onLoadingChange;
+    const onReadyRef = (0, react_1.useRef)(onReady);
+    onReadyRef.current = onReady;
+    const onErrorRef = (0, react_1.useRef)(onError);
+    onErrorRef.current = onError;
     // The WebView HTML is built once from stable initial values.
     // avatarUrl + authToken changing causes a controlled key-based remount.
     // All other prop changes (mood, colors, accessories) go via postMessage.
@@ -23,22 +36,70 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             setWebViewKey(`${avatarUrl}__${authToken ?? ''}`);
         }
     }, [avatarUrl, authToken]);
+    (0, react_1.useEffect)(() => {
+        if (!avatarUrl)
+            return;
+        firstMessageSeenRef.current = false;
+        onLoadingChangeRef.current?.({ stage: 'booting', progress: null });
+        if (bootTimerRef.current)
+            clearTimeout(bootTimerRef.current);
+        bootTimerRef.current = setTimeout(() => {
+            if (readyRef.current || firstMessageSeenRef.current)
+                return;
+            const vendorLabel = vendorBaseUrl ? ` vendor=${vendorBaseUrl}` : ' vendor=<cdn>';
+            const avatarLabel = avatarUrl && avatarUrl.length > 80 ? avatarUrl.slice(0, 80) + '…' : avatarUrl;
+            onErrorRef.current?.(`[boot timeout] No WebView messages received after 8s.${vendorLabel} avatar=${avatarLabel}`);
+        }, 8000);
+        return () => {
+            if (bootTimerRef.current) {
+                clearTimeout(bootTimerRef.current);
+                bootTimerRef.current = null;
+            }
+        };
+    }, [avatarUrl, authToken, vendorBaseUrl]);
     const post = (0, react_1.useCallback)((msg) => {
-        webViewRef.current?.postMessage(JSON.stringify(msg));
+        try {
+            webViewRef.current?.postMessage(JSON.stringify(msg));
+        }
+        catch {
+            // WebView ref frozen/invalidated during unmount — ignore
+        }
     }, []);
     (0, react_1.useImperativeHandle)(ref, () => ({
         sendAmplitude: (amplitude) => post({ type: 'amplitude', value: amplitude }),
         sendViseme: (viseme, weight = 1.0) => post({ type: 'viseme', viseme, weight }),
         scheduleVisemes: (schedule) => post({ type: 'schedule_visemes', schedule }),
         clearVisemes: () => post({ type: 'clear_visemes' }),
-        setMood: (nextMood) => post({ type: 'mood', value: nextMood }),
-        setHairColor: (color) => post({ type: 'hair_color', value: color }),
-        setSkinColor: (color) => post({ type: 'skin_color', value: color }),
-        setEyeColor: (color) => post({ type: 'eye_color', value: color }),
-        setAccessories: (newAccessories) => post({ type: 'set_accessories', accessories: newAccessories }),
+        setMood: (nextMood) => {
+            pendingMoodRef.current = nextMood;
+            if (readyRef.current)
+                post({ type: 'mood', value: nextMood });
+        },
+        setHairColor: (color) => {
+            pendingHairColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'hair_color', value: color });
+        },
+        setSkinColor: (color) => {
+            pendingSkinColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'skin_color', value: color });
+        },
+        setEyeColor: (color) => {
+            pendingEyeColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'eye_color', value: color });
+        },
+        setAccessories: (newAccessories) => {
+            accessoriesRef.current = newAccessories;
+            if (readyRef.current) {
+                post({ type: 'set_accessories', accessories: newAccessories });
+            }
+        },
     }), [post]);
     // Sync mood via postMessage only — never causes a WebView reload
     (0, react_1.useEffect)(() => {
+        pendingMoodRef.current = mood;
         if (readyRef.current)
             post({ type: 'mood', value: mood });
     }, [mood, post]);
@@ -49,14 +110,17 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         }
     }, [accessories, post]);
     (0, react_1.useEffect)(() => {
+        pendingHairColorRef.current = hairColor;
         if (hairColor && readyRef.current)
             post({ type: 'hair_color', value: hairColor });
     }, [hairColor, post]);
     (0, react_1.useEffect)(() => {
+        pendingSkinColorRef.current = skinColor;
         if (skinColor && readyRef.current)
             post({ type: 'skin_color', value: skinColor });
     }, [skinColor, post]);
     (0, react_1.useEffect)(() => {
+        pendingEyeColorRef.current = eyeColor;
         if (eyeColor && readyRef.current)
             post({ type: 'eye_color', value: eyeColor });
     }, [eyeColor, post]);
@@ -65,6 +129,18 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
     const [initialHairColor] = (0, react_1.useState)(hairColor);
     const [initialSkinColor] = (0, react_1.useState)(skinColor);
     const [initialEyeColor] = (0, react_1.useState)(eyeColor);
+    // Use the vendor origin as baseUrl so dynamic module imports are same-origin
+    // and don't get blocked by the WebView's security model.
+    const webViewBaseUrl = (0, react_1.useMemo)(() => {
+        if (!vendorBaseUrl)
+            return 'https://localhost/';
+        try {
+            return new URL(vendorBaseUrl).origin + '/';
+        }
+        catch {
+            return 'https://localhost/';
+        }
+    }, [vendorBaseUrl]);
     // html is stable — only rebuilds when webViewKey changes (avatarUrl/authToken)
     const html = (0, react_1.useMemo)(() => (0, html_1.buildAvatarHtml)({
         avatarUrl,
@@ -75,22 +151,46 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         initialHairColor,
         initialSkinColor,
         initialEyeColor,
+        vendorBaseUrl,
     }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [webViewKey]);
     const onMessage = (0, react_1.useCallback)((event) => {
         try {
+            firstMessageSeenRef.current = true;
             const msg = JSON.parse(event.nativeEvent.data);
+            if (msg.type === 'loading' && typeof msg.stage === 'string') {
+                onLoadingChangeRef.current?.({
+                    stage: msg.stage,
+                    progress: typeof msg.progress === 'number' && Number.isFinite(msg.progress)
+                        ? msg.progress
+                        : null,
+                });
+                return;
+            }
             if (msg.type === 'ready') {
                 readyRef.current = true;
-                // Flush pending props that may have arrived before WebView was ready
+                onLoadingChangeRef.current?.({ stage: 'ready', progress: 100 });
+                // Flush pending appearance updates that arrived before the WebView was ready.
+                if (pendingMoodRef.current) {
+                    post({ type: 'mood', value: pendingMoodRef.current });
+                }
+                if (pendingHairColorRef.current) {
+                    post({ type: 'hair_color', value: pendingHairColorRef.current });
+                }
+                if (pendingSkinColorRef.current) {
+                    post({ type: 'skin_color', value: pendingSkinColorRef.current });
+                }
+                if (pendingEyeColorRef.current) {
+                    post({ type: 'eye_color', value: pendingEyeColorRef.current });
+                }
                 if (accessoriesRef.current?.length) {
                     post({ type: 'set_accessories', accessories: accessoriesRef.current });
                 }
-                onReady?.();
+                onReadyRef.current?.();
             }
             else if (msg.type === 'error') {
-                onError?.(msg.message);
+                onErrorRef.current?.(msg.message);
             }
             else if (msg.type === 'log') {
                 console.log('[TalkingHead]', msg.message);
@@ -99,8 +199,18 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         catch (err) {
             console.warn('[TalkingHead] Invalid message from WebView:', err);
         }
-    }, [onReady, onError, post]);
-    return ((0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.container, style], children: (0, jsx_runtime_1.jsx)(react_native_webview_1.WebView, { ref: webViewRef, source: { html }, style: styles.webview, javaScriptEnabled: true, domStorageEnabled: true, allowsInlineMediaPlayback: true, mediaPlaybackRequiresUserAction: false, onMessage: onMessage, originWhitelist: ['*'], mixedContentMode: "always" }, webViewKey) }));
+    }, [post]);
+    const handleWebViewError = (0, react_1.useCallback)((event) => {
+        firstMessageSeenRef.current = true;
+        const description = event.nativeEvent.description || 'WebView failed to load avatar';
+        onErrorRef.current?.(`[webview] ${description}`);
+    }, []);
+    const handleWebViewHttpError = (0, react_1.useCallback)((event) => {
+        firstMessageSeenRef.current = true;
+        const { statusCode, description, url } = event.nativeEvent;
+        onErrorRef.current?.(`[http ${statusCode}] ${description || url || 'Avatar request failed'}`);
+    }, []);
+    return ((0, jsx_runtime_1.jsx)(react_native_1.View, { style: [styles.container, style], children: (0, jsx_runtime_1.jsx)(react_native_webview_1.WebView, { ref: webViewRef, source: { html, baseUrl: webViewBaseUrl }, style: styles.webview, javaScriptEnabled: true, domStorageEnabled: true, allowsInlineMediaPlayback: true, mediaPlaybackRequiresUserAction: false, onMessage: onMessage, onError: handleWebViewError, onHttpError: handleWebViewHttpError, onLoadStart: () => console.log('[TalkingHead] WebView load start'), onLoadEnd: () => console.log('[TalkingHead] WebView load end'), onLoadProgress: (event) => console.log('[TalkingHead] WebView progress', event.nativeEvent.progress), originWhitelist: ['*'], allowFileAccess: true, allowFileAccessFromFileURLs: true, allowUniversalAccessFromFileURLs: true, mixedContentMode: "always" }, webViewKey) }));
 });
 exports.TalkingHead.displayName = 'TalkingHead';
 const styles = react_native_1.StyleSheet.create({

package/dist/TalkingHead.web.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
-import type { TalkingHeadVisemeCue, TalkingHeadVisemeSchedule } from './TalkingHead';
-export type { TalkingHeadVisemeCue, TalkingHeadVisemeSchedule };
+import type { TalkingHeadLoadingState, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule } from './TalkingHead';
+export type { TalkingHeadLoadingState, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule };
 export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'excited' | 'thinking' | 'concerned' | 'surprised';
 export interface TalkingHeadAccessory {
     id: string;
@@ -20,6 +20,7 @@ export interface TalkingHeadProps {
     skinColor?: string;
     eyeColor?: string;
     accessories?: TalkingHeadAccessory[];
+    onLoadingChange?: (state: TalkingHeadLoadingState) => void;
     onReady?: () => void;
     onError?: (message: string) => void;
     style?: React.CSSProperties;

package/dist/TalkingHead.web.js

@@ -48,13 +48,22 @@ const iframeStyle = {
     border: 'none',
     backgroundColor: 'transparent',
 };
-exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onReady, onError, style, }, ref) => {
+exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onLoadingChange, onReady, onError, style, }, ref) => {
     const iframeRef = (0, react_1.useRef)(null);
     const readyRef = (0, react_1.useRef)(false);
+    const pendingMoodRef = (0, react_1.useRef)(mood);
+    const pendingHairColorRef = (0, react_1.useRef)(hairColor);
+    const pendingSkinColorRef = (0, react_1.useRef)(skinColor);
+    const pendingEyeColorRef = (0, react_1.useRef)(eyeColor);
     const accessoriesRef = (0, react_1.useRef)(accessories);
     (0, react_1.useEffect)(() => {
         accessoriesRef.current = accessories;
     }, [accessories]);
+    (0, react_1.useEffect)(() => {
+        if (!avatarUrl)
+            return;
+        onLoadingChange?.({ stage: 'booting', progress: null });
+    }, [avatarUrl, authToken, onLoadingChange]);
     const post = (0, react_1.useCallback)((msg) => {
         iframeRef.current?.contentWindow?.postMessage(JSON.stringify(msg), '*');
     }, []);
@@ -62,13 +71,35 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         sendAmplitude: (amplitude) => post({ type: 'amplitude', value: amplitude }),
         scheduleVisemes: (schedule) => post({ type: 'schedule_visemes', schedule }),
         clearVisemes: () => post({ type: 'clear_visemes' }),
-        setMood: (nextMood) => post({ type: 'mood', value: nextMood }),
-        setHairColor: (color) => post({ type: 'hair_color', value: color }),
-        setSkinColor: (color) => post({ type: 'skin_color', value: color }),
-        setEyeColor: (color) => post({ type: 'eye_color', value: color }),
-        setAccessories: (newAccessories) => post({ type: 'set_accessories', accessories: newAccessories }),
+        setMood: (nextMood) => {
+            pendingMoodRef.current = nextMood;
+            if (readyRef.current)
+                post({ type: 'mood', value: nextMood });
+        },
+        setHairColor: (color) => {
+            pendingHairColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'hair_color', value: color });
+        },
+        setSkinColor: (color) => {
+            pendingSkinColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'skin_color', value: color });
+        },
+        setEyeColor: (color) => {
+            pendingEyeColorRef.current = color;
+            if (readyRef.current)
+                post({ type: 'eye_color', value: color });
+        },
+        setAccessories: (newAccessories) => {
+            accessoriesRef.current = newAccessories;
+            if (readyRef.current) {
+                post({ type: 'set_accessories', accessories: newAccessories });
+            }
+        },
     }), [post]);
     (0, react_1.useEffect)(() => {
+        pendingMoodRef.current = mood;
         if (readyRef.current)
             post({ type: 'mood', value: mood });
     }, [mood, post]);
@@ -78,14 +109,17 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         }
     }, [accessories, post]);
     (0, react_1.useEffect)(() => {
+        pendingHairColorRef.current = hairColor;
         if (hairColor && readyRef.current)
             post({ type: 'hair_color', value: hairColor });
     }, [hairColor, post]);
     (0, react_1.useEffect)(() => {
+        pendingSkinColorRef.current = skinColor;
         if (skinColor && readyRef.current)
             post({ type: 'skin_color', value: skinColor });
     }, [skinColor, post]);
     (0, react_1.useEffect)(() => {
+        pendingEyeColorRef.current = eyeColor;
         if (eyeColor && readyRef.current)
             post({ type: 'eye_color', value: eyeColor });
     }, [eyeColor, post]);
@@ -122,8 +156,30 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 return;
             try {
                 const msg = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+                if (msg.type === 'loading' && typeof msg.stage === 'string') {
+                    onLoadingChange?.({
+                        stage: msg.stage,
+                        progress: typeof msg.progress === 'number' && Number.isFinite(msg.progress)
+                            ? msg.progress
+                            : null,
+                    });
+                    return;
+                }
                 if (msg.type === 'ready') {
                     readyRef.current = true;
+                    onLoadingChange?.({ stage: 'ready', progress: 100 });
+                    if (pendingMoodRef.current) {
+                        post({ type: 'mood', value: pendingMoodRef.current });
+                    }
+                    if (pendingHairColorRef.current) {
+                        post({ type: 'hair_color', value: pendingHairColorRef.current });
+                    }
+                    if (pendingSkinColorRef.current) {
+                        post({ type: 'skin_color', value: pendingSkinColorRef.current });
+                    }
+                    if (pendingEyeColorRef.current) {
+                        post({ type: 'eye_color', value: pendingEyeColorRef.current });
+                    }
                     if (accessoriesRef.current?.length) {
                         post({ type: 'set_accessories', accessories: accessoriesRef.current });
                     }
@@ -142,7 +198,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         };
         window.addEventListener('message', onMessage);
         return () => window.removeEventListener('message', onMessage);
-    }, [onReady, onError, post]);
+    }, [onLoadingChange, onReady, onError, post]);
     return ((0, jsx_runtime_1.jsx)("div", { style: { ...containerStyle, ...style }, children: (0, jsx_runtime_1.jsx)("iframe", { ref: iframeRef, srcDoc: srcdoc, style: iframeStyle, sandbox: "allow-scripts allow-same-origin", title: "TalkingHead Avatar" }) }));
 });
 exports.TalkingHead.displayName = 'TalkingHead';

package/dist/html.d.ts

@@ -8,5 +8,12 @@ export type AvatarConfig = {
     initialHairColor?: string;
     initialSkinColor?: string;
     initialEyeColor?: string;
+    /**
+     * Base URL for vendored static assets (three.js, talkinghead.mjs, headaudio).
+     * When set, replaces all cdn.jsdelivr.net references so the WebView loads
+     * assets from your own server instead of an external CDN.
+     * Example: "https://studio.sitebay.org/vendor"
+     */
+    vendorBaseUrl?: string | null;
 };
 export declare function buildAvatarHtml(config: AvatarConfig): string;

package/dist/html.js

@@ -1,10 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAvatarHtml = buildAvatarHtml;
-const VALID_MOODS = new Set(['neutral', 'happy', 'sad', 'angry', 'excited', 'thinking', 'concerned', 'surprised']);
+const UPSTREAM_SAFE_MOOD_MAP = {
+    neutral: 'neutral',
+    happy: 'happy',
+    sad: 'sad',
+    angry: 'angry',
+    excited: 'happy',
+    thinking: 'neutral',
+    concerned: 'sad',
+    surprised: 'happy',
+};
 function buildAvatarHtml(config) {
-    // Sanitize mood at build time so the WebView never receives an invalid value
-    const safeMood = VALID_MOODS.has(config.mood) ? config.mood : 'neutral';
+    const safeMood = UPSTREAM_SAFE_MOOD_MAP[config.mood] ?? 'neutral';
+    const v = config.vendorBaseUrl ? config.vendorBaseUrl.replace(/\/$/, '') : null;
+    const threeUrl = v ? `${v}/three.module.js` : 'https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js';
+    const threeAddonsUrl = v ? `${v}/three-addons/` : 'https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/';
+    const talkingHeadUrl = v ? `${v}/talkinghead.mjs` : 'https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.7/modules/talkinghead.mjs';
+    const headAudioUrl = v ? `${v}/headaudio.min.mjs` : 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/headaudio.min.mjs';
+    const headWorkletUrl = v ? `${v}/headworklet.min.mjs` : 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/headworklet.min.mjs';
+    const headModelUrl = v ? `${v}/model-en-mixed.bin` : 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/model-en-mixed.bin';
     return `
 <!DOCTYPE html>
 <html>
@@ -18,21 +33,48 @@ function buildAvatarHtml(config) {
 <script type="importmap">
 {
   "imports": {
-    "three": "https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js",
-    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/",
-    "talkinghead": "https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.7/modules/talkinghead.mjs"
+    "three": ${JSON.stringify(threeUrl)},
+    "three/addons/": ${JSON.stringify(threeAddonsUrl)},
+    "talkinghead": ${JSON.stringify(talkingHeadUrl)}
   }
 }
 </script>
+<script>
+window.ReactNativeWebView?.postMessage(
+  JSON.stringify({ type: 'log', message: '[bootstrap] inline script start' })
+);
+function postBootstrapError(kind, message) {
+  window.ReactNativeWebView?.postMessage(
+    JSON.stringify({ type: 'error', message: '[' + kind + '] ' + String(message || 'Unknown error') })
+  );
+}
+document.addEventListener('DOMContentLoaded', function() {
+  window.ReactNativeWebView?.postMessage(
+    JSON.stringify({ type: 'log', message: '[bootstrap] DOMContentLoaded' })
+  );
+});
+window.addEventListener('error', function(event) {
+  postBootstrapError('window.error', event?.message || event?.error?.message || 'Script error');
+});
+window.addEventListener('unhandledrejection', function(event) {
+  const reason = event?.reason;
+  postBootstrapError('unhandledrejection', reason?.message || reason || 'Unhandled promise rejection');
+});
+</script>
 </head>
 <body>
 <div id="avatar"></div>
 <script type="module">
+(async function() {
+window.ReactNativeWebView?.postMessage(
+  JSON.stringify({ type: 'log', message: '[module] script start' })
+);
 const AUTH_TOKEN = ${JSON.stringify(config.authToken ?? null)};
-const TALKING_HEAD_URL = 'https://cdn.jsdelivr.net/gh/met4citizen/TalkingHead@1.7/modules/talkinghead.mjs';
-const HEAD_AUDIO_URL = 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/headaudio.min.mjs';
-const HEAD_AUDIO_WORKLET = 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/headworklet.min.mjs';
-const HEAD_AUDIO_MODEL = 'https://cdn.jsdelivr.net/gh/met4citizen/HeadAudio@v0.1.0-alpha/dist/model-en-mixed.bin';
+const TALKING_HEAD_URL = ${JSON.stringify(talkingHeadUrl)};
+const HEAD_AUDIO_URL = ${JSON.stringify(headAudioUrl)};
+const HEAD_AUDIO_WORKLET = ${JSON.stringify(headWorkletUrl)};
+const HEAD_AUDIO_MODEL = ${JSON.stringify(headModelUrl)};
+const MOOD_MAP = ${JSON.stringify(UPSTREAM_SAFE_MOOD_MAP)};
 
 let AVATAR_URL = ${JSON.stringify(config.avatarUrl)};
 const INITIAL_MOOD = ${JSON.stringify(safeMood)};
@@ -55,9 +97,16 @@ function log(msg) {
   window.ReactNativeWebView?.postMessage(JSON.stringify({ type: 'log', message: msg }));
 }
 
+function emitLoading(stage, progress = null) {
+  window.ReactNativeWebView?.postMessage(
+    JSON.stringify({ type: 'loading', stage, progress }),
+  );
+}
+
 async function loadWithAuth(url) {
   if (!url) throw new Error('Avatar URL is empty');
   if (AUTH_TOKEN && !url.startsWith('https://cdn.jsdelivr.net')) {
+    emitLoading('fetching_model');
     log('Fetching authenticated model: ' + url);
     const resp = await fetch(url, { headers: { 'Authorization': 'Bearer ' + AUTH_TOKEN } });
     if (!resp.ok) throw new Error('Failed to fetch model: ' + resp.status + ' ' + resp.statusText);
@@ -153,6 +202,7 @@ async function loadStaticFallback(loadedAvatarUrl) {
       staticModel.position.sub(scaledCenter);
 
       applyAccessories(pendingAccessoriesList);
+      emitLoading('ready', 100);
       window.ReactNativeWebView?.postMessage(JSON.stringify({ type: 'ready' }));
 
       window.addEventListener('resize', () => {
@@ -169,7 +219,11 @@ async function loadStaticFallback(loadedAvatarUrl) {
         renderer.render(scene, camera);
       });
     }, (ev) => {
-      if (ev.lengthComputable) log('Fallback Loading: ' + Math.round((ev.loaded / ev.total) * 100) + '%');
+      if (ev.lengthComputable) {
+        const progress = Math.round((ev.loaded / ev.total) * 100);
+        emitLoading('loading_fallback', progress);
+        log('Fallback Loading: ' + progress + '%');
+      }
     }, (err) => {
       log('Fallback Error: ' + err.message);
       window.ReactNativeWebView?.postMessage(JSON.stringify({ type: 'error', message: err.message }));
@@ -194,7 +248,8 @@ async function init() {
 
   try {
     log('Loading TalkingHead...');
-    const module = await import(TALKING_HEAD_URL);
+    emitLoading('booting');
+    const module = await import('talkinghead');
 
     head = new module.TalkingHead(container, {
       ttsEndpoint: null,
@@ -224,7 +279,9 @@ async function init() {
         lipsyncLang: 'en',
       }, (ev) => {
         if (ev.lengthComputable) {
-          log('Loading: ' + Math.round((ev.loaded / ev.total) * 100) + '%');
+          const progress = Math.round((ev.loaded / ev.total) * 100);
+          emitLoading('loading_avatar', progress);
+          log('Loading: ' + progress + '%');
         }
       });
       if (loadedAvatarUrl.startsWith('blob:')) URL.revokeObjectURL(loadedAvatarUrl);
@@ -262,18 +319,22 @@ async function init() {
               Object.assign(head.mtAvatar[key], { newvalue: value, needsUpdate: true });
             }
           };
-          head.opt.update = headaudio.update.bind(headaudio);
+          const headaudioUpdate = headaudio.update.bind(headaudio);
+          head.opt.update = (dt) => { headaudioUpdate(dt); tickVisemeDecay(); };
           log('HeadAudio ready (phoneme lip sync)');
         } else {
           log('HeadAudio skipped: AudioWorklet not supported in this WebView. Use sendViseme() from native TTS callbacks.');
+          head.opt.update = () => tickVisemeDecay();
         }
       } catch (err) {
         log('HeadAudio unavailable, viseme/amplitude fallback active: ' + err.message);
+        head.opt.update = () => tickVisemeDecay();
       }
 
       startAudioInterception();
       log('[ACC] init() complete, calling applyAccessories with ' + pendingAccessoriesList.length + ' pending items');
       applyAccessories(pendingAccessoriesList);
+      emitLoading('ready', 100);
       window.ReactNativeWebView?.postMessage(JSON.stringify({ type: 'ready' }));
     }
   } catch (err) {
@@ -323,34 +384,79 @@ let visemeMorphCache = null;
 const visemeState = {};
 
 const VISEME_MORPH_ALIASES = {
-  sil: ['viseme_sil', 'sil'],
-  PP:  ['viseme_PP',  'pp',  'viseme_pp'],
-  FF:  ['viseme_FF',  'ff',  'viseme_ff'],
-  TH:  ['viseme_TH',  'th',  'viseme_th'],
-  DD:  ['viseme_DD',  'dd',  'viseme_dd'],
-  kk:  ['viseme_kk',  'kk',  'viseme_k'],
-  CH:  ['viseme_CH',  'ch',  'viseme_ch'],
-  SS:  ['viseme_SS',  'ss',  'viseme_s'],
-  nn:  ['viseme_nn',  'nn',  'viseme_n'],
-  RR:  ['viseme_RR',  'rr',  'viseme_r'],
+  sil: ['viseme_sil', 'sil', 'mouthClose', 'mouth_close'],
+  PP:  ['viseme_PP',  'pp',  'viseme_pp', 'mouthPucker', 'mouth_pucker'],
+  FF:  ['viseme_FF',  'ff',  'viseme_ff', 'mouthLowerLipIn', 'mouth_lower_lip_in', 'mouthRollLower', 'mouthShrugLower'],
+  TH:  ['viseme_TH',  'th',  'viseme_th', 'tongueOut', 'tongue_out'],
+  DD:  ['viseme_DD',  'dd',  'viseme_dd', 'mouthShrugUpper', 'mouth_shrug_upper'],
+  kk:  ['viseme_kk',  'kk',  'viseme_k',  'mouthStretchLeft', 'mouth_stretch_left'],
+  CH:  ['viseme_CH',  'ch',  'viseme_ch', 'mouthSmile', 'mouth_smile', 'mouthSmileLeft', 'mouth_smile_left'],
+  SS:  ['viseme_SS',  'ss',  'viseme_ss', 'mouthStretchRight', 'mouth_stretch_right'],
+  nn:  ['viseme_nn',  'nn',  'viseme_n',  'mouthDimpleLeft', 'mouth_dimple_left'],
+  RR:  ['viseme_RR',  'rr',  'viseme_r',  'mouthDimpleRight', 'mouth_dimple_right'],
   aa:  ['viseme_aa',  'viseme_AA', 'aa', 'jawOpen', 'jaw_open', 'jawopen', 'mouthOpen', 'mouth_open', 'mouthopen'],
-  ee:  ['viseme_ee',  'viseme_E',  'ee'],
-  ih:  ['viseme_ih',  'viseme_I',  'ih'],
-  oh:  ['viseme_oh',  'viseme_O',  'oh'],
-  ou:  ['viseme_ou',  'viseme_U',  'ou'],
+  ee:  ['viseme_ee',  'viseme_E',  'ee', 'mouthSmileLeft', 'mouth_smile_left'],
+  ih:  ['viseme_ih',  'viseme_I',  'ih', 'mouthSmileRight', 'mouth_smile_right'],
+  oh:  ['viseme_oh',  'viseme_O',  'oh', 'mouthFunnel', 'mouth_funnel'],
+  ou:  ['viseme_ou',  'viseme_U',  'ou', 'mouthRollLower', 'mouth_roll_lower'],
+};
+
+// For ARKit models, each viseme may need multiple blend shapes driven together.
+// Each entry is a list of morph names to combine for that viseme.
+// The first alias list that has ANY match on the model is used.
+const VISEME_COMPOUND_ARKIT = {
+  aa:  [['jawOpen', 'mouthLowerDownLeft', 'mouthLowerDownRight'], ['jawOpen', 'mouthOpen']],
+  oh:  [['mouthFunnel', 'jawOpen'], ['mouthFunnel']],
+  ou:  [['mouthPucker', 'mouthRollLower'], ['mouthPucker']],
+  PP:  [['mouthPucker', 'mouthClose'], ['mouthPucker']],
+  FF:  [['mouthRollLower', 'mouthLowerDownLeft', 'mouthLowerDownRight'], ['mouthShrugLower']],
+  CH:  [['mouthSmileLeft', 'mouthSmileRight', 'mouthStretchLeft', 'mouthStretchRight'], ['mouthSmileLeft', 'mouthSmileRight']],
+  ee:  [['mouthSmileLeft', 'mouthSmileRight'], ['mouthSmileLeft']],
+  ih:  [['mouthSmileLeft', 'mouthSmileRight'], ['mouthSmileRight']],
 };
 
 function buildVisemeMorphCache() {
   visemeMorphCache = {};
   for (const [visemeKey, aliases] of Object.entries(VISEME_MORPH_ALIASES)) {
     const entries = [];
+    // Check if we have a compound ARKit mapping for this viseme
+    const compoundOptions = VISEME_COMPOUND_ARKIT[visemeKey];
+    if (compoundOptions) {
+      // Try each compound option; use the first one where all names exist on at least one mesh
+      let usedCompound = false;
+      for (const nameList of compoundOptions) {
+        // Collect entries for all names across all meshes
+        const compoundEntries = [];
+        for (const mesh of mouthMeshes) {
+          if (!mesh.morphTargetDictionary) continue;
+          const dict = mesh.morphTargetDictionary;
+          const dictKeysLower = Object.fromEntries(Object.keys(dict).map(k => [k.toLowerCase(), k]));
+          for (const name of nameList) {
+            const found = dictKeysLower[name.toLowerCase()];
+            if (found !== undefined) {
+              compoundEntries.push({ influences: mesh.morphTargetInfluences, idx: dict[found], morphName: found });
+            }
+          }
+        }
+        if (compoundEntries.length > 0) {
+          entries.push(...compoundEntries);
+          usedCompound = true;
+          break;
+        }
+      }
+      if (usedCompound) {
+        visemeMorphCache[visemeKey] = entries;
+        continue;
+      }
+    }
+    // Fallback: single-alias lookup
     for (const mesh of mouthMeshes) {
       if (!mesh.morphTargetDictionary) continue;
       const dictKeys = Object.keys(mesh.morphTargetDictionary);
       for (const alias of aliases) {
         const found = dictKeys.find(k => k.toLowerCase() === alias.toLowerCase());
         if (found !== undefined) {
-          entries.push({ influences: mesh.morphTargetInfluences, idx: mesh.morphTargetDictionary[found] });
+          entries.push({ influences: mesh.morphTargetInfluences, idx: mesh.morphTargetDictionary[found], morphName: found });
           break;
         }
       }
@@ -359,6 +465,12 @@ function buildVisemeMorphCache() {
   }
   const found = Object.keys(visemeMorphCache);
   log('Viseme cache: ' + (found.length > 0 ? found.join(', ') : 'none — check morph target names'));
+
+  // Always log all available morphs so we can see what the model actually has
+  if (mouthMeshes.length > 0) {
+    const allMorphs = Object.keys(mouthMeshes[0].morphTargetDictionary || {});
+    log('Available morphs: ' + (allMorphs.length > 0 ? allMorphs.join(', ') : 'none'));
+  }
 }
 
 function applyViseme(visemeKey, weight) {
@@ -368,39 +480,42 @@ function applyViseme(visemeKey, weight) {
     return;
   }
   visemeState[visemeKey] = Math.min(1, weight);
+  visemeStateLastSet.set(visemeKey, Date.now());
 }
 
-function tickVisemeDecay() {
-  if (!visemeMorphCache) return;
-  for (const [key, weight] of Object.entries(visemeState)) {
-    const decayed = weight * 0.82;
-    visemeState[key] = decayed < 0.01 ? 0 : decayed;
-    const entries = visemeMorphCache[key];
-    if (!entries) continue;
-    for (const e of entries) e.influences[e.idx] = visemeState[key];
-  }
-}
-
-// ============ RHUBARB VISEME SCHEDULER ============
-// Rhubarb mouth shapes A-H, X mapped to the closest standard viseme morph targets.
-// Amplitude fallback is gated while a schedule is active (visemeModeUntil).
+const RHUBARB_DEFAULT_VISEME_WEIGHT = 0.72;
+const RHUBARB_LABIAL_VISEME_WEIGHT = 0.85;
+const RHUBARB_AA_VISEME_WEIGHT = 0.72;
+const RHUBARB_ROUNDED_VISEME_WEIGHT = 0.62;
+const RHUBARB_FALLBACK_AMPLITUDE_CAP = 0.72;
+const RHUBARB_FALLBACK_AMPLITUDE_GAIN = 0.75;
+const RHUBARB_VISEME_WEIGHTS = {
+  PP: RHUBARB_LABIAL_VISEME_WEIGHT,
+  FF: 0.78,
+  ee: 0.72,
+  ih: 0.68,
+  oh: RHUBARB_ROUNDED_VISEME_WEIGHT,
+  ou: 0.58,
+  aa: RHUBARB_AA_VISEME_WEIGHT,
+};
 
 const RHUBARB_TO_VISEME = {
-  X: 'sil',  // silence — mouth closed
-  A: 'PP',   // m, b, p — lips together
-  B: 'kk',   // k, s, t — slightly open
-  C: 'ee',   // e as in bed — open with smile
-  D: 'aa',   // aa as in father — wide open
-  E: 'oh',   // eh/uh — rounded open
-  F: 'ou',   // oo/w — puckered
-  G: 'FF',   // f, v — teeth on lip
-  H: 'ih',   // ee as in see — wide smile
+  A: 'aa',
+  B: 'PP',
+  C: 'ih',
+  D: 'FF',
+  E: 'ee',
+  F: 'oh',
+  G: 'ou',
+  H: 'nn',
+  X: 'sil',
 };
 
 let rhubarbMorphCache = null;
 let visemeTimers = [];
 let activeVisemeScheduleId = 0;
 let visemeModeUntil = 0;
+const visemeStateLastSet = new Map();
 
 function buildRhubarbMorphCache() {
   if (!visemeMorphCache) buildVisemeMorphCache();
@@ -419,7 +534,8 @@ function applyRhubarbCue(shape) {
   if (shape === 'X' || !rhubarbMorphCache[shape]) return;
   const visemeKey = RHUBARB_TO_VISEME[shape];
   if (visemeKey && visemeKey !== 'sil') {
-    visemeState[visemeKey] = 1.0;
+    visemeState[visemeKey] = RHUBARB_VISEME_WEIGHTS[visemeKey] || RHUBARB_DEFAULT_VISEME_WEIGHT;
+    visemeStateLastSet.set(visemeKey, Date.now());
   }
 }
 
@@ -432,20 +548,98 @@ function clearScheduledVisemes() {
   for (const key of Object.keys(visemeState)) visemeState[key] = 0;
 }
 
+function tickVisemeDecay() {
+  if (!visemeMorphCache) return;
+
+  const isScheduled = Date.now() < visemeModeUntil;
+  const hasSpecificLipShape =
+    visemeState.PP > 0.05 ||
+    visemeState.FF > 0.05 ||
+    visemeState.kk > 0.05 ||
+    visemeState.ee > 0.05 ||
+    visemeState.ih > 0.05;
+
+  for (const [key, weight] of Object.entries(visemeState)) {
+    // Only decay if we aren't in the middle of a viseme schedule.
+    // Scheduled visemes are cleared manually by timeouts.
+    if (!isScheduled) {
+      const decayed = weight * 0.82;
+      visemeState[key] = decayed < 0.01 ? 0 : decayed;
+    }
+
+    const entries = visemeMorphCache[key];
+    if (!entries) continue;
+
+    let targetWeight = visemeState[key];
+    if (key === 'aa' && hasSpecificLipShape) targetWeight = Math.min(targetWeight, 0.45);
+
+    for (const e of entries) {
+      // When TalkingHead is active, write through its morph API so the internal
+      // render loop doesn't overwrite our values every frame.
+      // Use realtime (not newvalue) — newvalue is consumed and cleared after
+      // a single frame, so scheduled visemes would vanish immediately.
+      // realtime persists until explicitly set to null.
+      if (head?.mtAvatar && e.morphName && head.mtAvatar[e.morphName]) {
+        const mt = head.mtAvatar[e.morphName];
+        mt.realtime = targetWeight > 0 ? targetWeight : null;
+        mt.needsUpdate = true;
+      } else {
+        e.influences[e.idx] = targetWeight;
+      }
+    }
+  }
+}
+
 function scheduleVisemes(schedule) {
   clearScheduledVisemes();
+
+  // Prune visemeState keys that haven't been written in the last 2 seconds to
+  // prevent unbounded accumulation across many utterances.
+  const staleThreshold = Date.now() - 2000;
+  for (const key of Object.keys(visemeState)) {
+    if ((visemeStateLastSet.get(key) ?? 0) < staleThreshold) {
+      delete visemeState[key];
+      visemeStateLastSet.delete(key);
+    }
+  }
+
   if (!schedule || !Array.isArray(schedule.cues) || schedule.cues.length === 0) return;
 
   const myScheduleId = activeVisemeScheduleId;
-  const startedAt = schedule.startedAtMs || Date.now();
+  // The startedAtMs anchor is set when tts_request_start arrives on the data
+  // channel. Audio doesn't play until ~300ms later (LiveKit audio buffering).
+  // TTS generation delay is no longer included here since visemes now arrive
+  // via direct ref call before the React render cycle.
+  const AUDIO_PIPELINE_DELAY_MS = 300;
+  let startedAt = (schedule.startedAtMs || Date.now()) + AUDIO_PIPELINE_DELAY_MS;
   const durationMs = schedule.durationMs || 0;
+  const now = Date.now();
+  let elapsedMs = Math.max(0, now - startedAt);
+
+  // If the schedule still arrives late after the pipeline offset, shift further
+  if (elapsedMs > 300 && schedule.cues.length > 3) {
+    const shift = Math.min(elapsedMs - 50, 500);
+    startedAt += shift;
+    elapsedMs -= shift;
+    log('Viseme schedule arrived late, shifting anchor forward by ' + shift + 'ms');
+  }
 
-  // Gate amplitude fallback for the full duration plus a small buffer
-  visemeModeUntil = startedAt + durationMs + 200;
+  const remainingMs = Math.max(0, durationMs - elapsedMs);
+  let scheduledCueCount = 0;
+  let skippedCueCount = 0;
+
+  // Gate amplitude fallback for the locally remaining duration plus a small buffer.
+  // If the schedule arrives a bit late, keep amplitude out of the way for the rest
+  // of the utterance instead of expiring immediately from the original timestamp.
+  visemeModeUntil = now + remainingMs + 200;
 
   for (const cue of schedule.cues) {
     const delay = cue.startMs - (Date.now() - startedAt);
-    if (delay < -50) continue; // already in the past, skip
+    if (delay < -50) {
+      skippedCueCount++;
+      continue; // already in the past, skip
+    }
+    scheduledCueCount++;
 
     const applyId = setTimeout(() => {
       if (activeVisemeScheduleId !== myScheduleId) return;
@@ -461,6 +655,16 @@ function scheduleVisemes(schedule) {
     visemeTimers.push(applyId, clearId);
   }
 
+  log(
+    'Viseme schedule received: requestId=' +
+      (schedule.requestId || 'unknown') +
+      ' cues=' + schedule.cues.length +
+      ' scheduled=' + scheduledCueCount +
+      ' skipped=' + skippedCueCount +
+      ' elapsedMs=' + elapsedMs +
+      ' remainingMs=' + remainingMs,
+  );
+
   // Ensure silence at schedule end
   const endDelay = durationMs - (Date.now() - startedAt);
   if (endDelay > 0) {
@@ -630,7 +834,10 @@ function onIncomingMessage(event) {
           if (jawKey !== undefined) jawMorphCache.push({ influences: mesh.morphTargetInfluences, idx: mesh.morphTargetDictionary[jawKey] });
         }
       }
-      const val = Math.min(1, msg.value * 1.8);
+          const val = Math.min(
+            RHUBARB_FALLBACK_AMPLITUDE_CAP,
+            msg.value * RHUBARB_FALLBACK_AMPLITUDE_GAIN,
+          );
       amplitudeDecay = Math.max(amplitudeDecay * 0.7, val);
       for (let i = 0; i < jawMorphCache.length; i++) jawMorphCache[i].influences[jawMorphCache[i].idx] = amplitudeDecay;
     } else if (msg.type === 'viseme') {
@@ -640,8 +847,7 @@ function onIncomingMessage(event) {
     } else if (msg.type === 'clear_visemes') {
       clearScheduledVisemes();
     } else if (msg.type === 'mood' && head) {
-      const moodMap = { neutral:'neutral', happy:'happy', sad:'sad', angry:'angry', excited:'happy', thinking:'neutral', concerned:'sad', surprised:'happy' };
-      head.setMood(moodMap[msg.value] || 'neutral');
+      head.setMood(MOOD_MAP[msg.value] || 'neutral');
     } else if (msg.type === 'hair_color') {
       HAIR_COLOR = msg.value; applyColorOverrides();
     } else if (msg.type === 'skin_color') {
@@ -659,7 +865,8 @@ function onIncomingMessage(event) {
 window.addEventListener('message', onIncomingMessage);
 document.addEventListener('message', onIncomingMessage);
 
-init();
+await init();
+})();
 </script>
 </body>
 </html>

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export type { TalkingHeadAccessory, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, TalkingHeadViseme, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule, } from './TalkingHead';
+export type { TalkingHeadAccessory, TalkingHeadLoadingState, TalkingHeadLoadingStage, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, TalkingHeadViseme, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule, } from './TalkingHead';
 export { TalkingHead } from './TalkingHead';
 export * from './appearance';

package/dist/index.web.d.ts

@@ -1,3 +1,3 @@
-export type { TalkingHeadAccessory, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, } from './TalkingHead.web';
+export type { TalkingHeadAccessory, TalkingHeadLoadingState, TalkingHeadMood, TalkingHeadProps, TalkingHeadRef, } from './TalkingHead.web';
 export { TalkingHead } from './TalkingHead.web';
 export * from './appearance';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-head-studio",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Cross-platform 3D avatar component for React Native & web — lip-sync, gestures, accessories, and LLM integration. Powered by TalkingHead + Three.js.",
   "main": "dist/index.web.js",
   "browser": "dist/index.web.js",
@@ -79,11 +79,11 @@
   },
   "sideEffects": false,
   "peerDependencies": {
+    "@react-three/drei": ">=9",
+    "@react-three/fiber": ">=8",
     "react": ">=18",
     "react-native": ">=0.73",
     "react-native-webview": ">=13",
-    "@react-three/fiber": ">=8",
-    "@react-three/drei": ">=9",
     "three": ">=0.170"
   },
   "peerDependenciesMeta": {
@@ -126,6 +126,7 @@
     "metro-react-native-babel-preset": "^0.77.0",
     "multer": "^2.1.0",
     "prettier": "^3.8.1",
+    "react-native-webview": "^13.16.0",
     "react-test-renderer": "^19.2.4",
     "ts-jest": "^29.4.6"
   }