talking-head-studio 0.2.8 → 0.3.0

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,14 +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.
@@ -27,9 +36,63 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             setWebViewKey(`${avatarUrl}__${authToken ?? ''}`);
         }
     }, [avatarUrl, authToken]);
-    const post = (0, react_1.useCallback)((msg) => {
-        webViewRef.current?.postMessage(JSON.stringify(msg));
+    (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 postQueue = (0, react_1.useRef)([]);
+    const flushTimer = (0, react_1.useRef)(null);
+    (0, react_1.useEffect)(() => () => {
+        if (flushTimer.current)
+            clearTimeout(flushTimer.current);
+    }, []);
+    const flushQueue = (0, react_1.useCallback)(() => {
+        flushTimer.current = null;
+        try {
+            const wv = webViewRef.current;
+            if (!wv)
+                return;
+            const msgs = postQueue.current.splice(0);
+            if (msgs.length === 0)
+                return;
+            // Batch all pending messages into a single injectJavaScript call
+            const js = msgs
+                .map((m) => {
+                const json = JSON.stringify(JSON.stringify(m));
+                return `window.dispatchEvent(new MessageEvent('message',{data:${json}}))`;
+            })
+                .join(';');
+            wv.injectJavaScript(js + ';true;');
+        }
+        catch {
+            // WebView ref frozen/invalidated during unmount — ignore
+            postQueue.current = [];
+        }
     }, []);
+    const post = (0, react_1.useCallback)((msg) => {
+        postQueue.current.push(msg);
+        // Coalesce into a single microtask to avoid flooding injectJavaScript
+        if (!flushTimer.current) {
+            flushTimer.current = setTimeout(flushQueue, 0);
+        }
+    }, [flushQueue]);
     (0, react_1.useImperativeHandle)(ref, () => ({
         sendAmplitude: (amplitude) => post({ type: 'amplitude', value: amplitude }),
         sendViseme: (viseme, weight = 1.0) => post({ type: 'viseme', viseme, weight }),
@@ -94,6 +157,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,
@@ -104,14 +179,26 @@ 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;
+                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 });
@@ -128,10 +215,10 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 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);
@@ -140,8 +227,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,7 +48,7 @@ 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);
@@ -59,6 +59,11 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
     (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), '*');
     }, []);
@@ -151,8 +156,18 @@ 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 });
                     }
@@ -183,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/TalkingHeadVisualization.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import { ViewStyle, StyleProp } from 'react-native';
+import { type TalkingHeadMood, type TalkingHeadAccessory, type TalkingHeadViseme, type TalkingHeadVisemeSchedule } from './TalkingHead';
+interface TalkingHeadVisualizationProps {
+    style?: StyleProp<ViewStyle>;
+    avatarUrl: string | null;
+    authToken?: string;
+    cameraView?: 'head' | 'upper' | 'full';
+    cameraDistance?: number;
+    accessories?: TalkingHeadAccessory[];
+    mood?: TalkingHeadMood;
+    aspect?: number;
+    focalLength?: number;
+    visemeSchedule?: TalkingHeadVisemeSchedule | null;
+    onVisemeScheduleApplied?: (info: {
+        requestId: string | null;
+        appliedAtMs: number;
+    }) => void;
+    vendorBaseUrl?: string | null;
+}
+export interface TalkingHeadVisualizationRef {
+    setMood: (mood: TalkingHeadMood) => void;
+    sendAmplitude: (amplitude: number) => void;
+    sendViseme: (viseme: TalkingHeadViseme, weight?: number) => void;
+    scheduleVisemes: (schedule: TalkingHeadVisemeSchedule) => void;
+    clearVisemes: () => void;
+}
+/**
+ * TalkingHeadVisualization — optimized component for rendering the 3D avatar.
+ *
+ * On native: uses FilamentAvatar (direct morph writes, no WebView bridge).
+ * On web: uses TalkingHead WebView renderer.
+ */
+export declare const TalkingHeadVisualization: React.ForwardRefExoticComponent<TalkingHeadVisualizationProps & React.RefAttributes<TalkingHeadVisualizationRef>>;
+export {};

package/dist/TalkingHeadVisualization.js

@@ -0,0 +1,277 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TalkingHeadVisualization = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/* eslint-disable @typescript-eslint/no-unused-expressions */
+const react_1 = require("react");
+const react_native_1 = require("react-native");
+const TalkingHead_1 = require("./TalkingHead");
+const FilamentAvatar_1 = require("./filament/FilamentAvatar");
+const avatarUtils_1 = require("./utils/avatarUtils");
+const faceSqueezeAssets_1 = require("./filament/faceSqueezeAssets");
+// Cached fallback data URI — resolved once, reused across all instances
+let _fallbackDataUri = null;
+let _fallbackPromise = null;
+function getFallbackAvatarUrl() {
+    if (_fallbackDataUri)
+        return Promise.resolve(_fallbackDataUri);
+    if (!_fallbackPromise) {
+        _fallbackPromise = (0, avatarUtils_1.resolveLocalAssetUrl)(faceSqueezeAssets_1.FACE_SQUEEZE_LOCAL_MODULE).then((uri) => {
+            _fallbackDataUri = uri;
+            return uri;
+        });
+    }
+    return _fallbackPromise;
+}
+function getLoadingLabel(stage) {
+    switch (stage) {
+        case 'fetching_model':
+            return 'Fetching avatar';
+        case 'loading_avatar':
+            return 'Loading avatar';
+        case 'loading_fallback':
+            return 'Loading viewer';
+        case 'ready':
+            return 'Ready';
+        case 'booting':
+        default:
+            return 'Starting avatar';
+    }
+}
+/**
+ * TalkingHeadVisualization — optimized component for rendering the 3D avatar.
+ *
+ * On native: uses FilamentAvatar (direct morph writes, no WebView bridge).
+ * On web: uses TalkingHead WebView renderer.
+ */
+exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl, authToken, cameraView = 'head', cameraDistance = 0.2, accessories, mood: initialMood = 'neutral', aspect, focalLength, visemeSchedule, onVisemeScheduleApplied, vendorBaseUrl }, ref) => {
+    const avatarRef = (0, react_1.useRef)(null);
+    // On native, Filament ref is wired via callback ref — store it here so
+    // scheduleVisemes / sendAmplitude can route to it.
+    const filamentRef = (0, react_1.useRef)(null);
+    // Unified accessor — Filament on native, WebView on web
+    const activeAvatar = (0, react_1.useCallback)(() => (filamentRef.current ?? avatarRef.current), []);
+    // Fallback local GLB data URI — resolved once on mount
+    const [fallbackUrl, setFallbackUrl] = (0, react_1.useState)(_fallbackDataUri);
+    (0, react_1.useEffect)(() => {
+        if (_fallbackDataUri) {
+            setFallbackUrl(_fallbackDataUri);
+            return;
+        }
+        getFallbackAvatarUrl().then((u) => u && setFallbackUrl(u));
+    }, []);
+    const [mood, setMood] = (0, react_1.useState)(initialMood);
+    const [isAvatarReady, setIsAvatarReady] = (0, react_1.useState)(false);
+    const [avatarError, setAvatarError] = (0, react_1.useState)(null);
+    const [useFallback, setUseFallback] = (0, react_1.useState)(false);
+    const [loadingState, setLoadingState] = (0, react_1.useState)({
+        stage: 'booting',
+        progress: null,
+    });
+    const pendingVisemeScheduleRef = (0, react_1.useRef)(null);
+    const lastScheduledVisemeKeyRef = (0, react_1.useRef)(null);
+    const handleReady = (0, react_1.useCallback)(() => {
+        setAvatarError(null);
+        setIsAvatarReady(true);
+        setLoadingState({ stage: 'ready', progress: 100 });
+        const pendingSchedule = pendingVisemeScheduleRef.current;
+        if (!pendingSchedule)
+            return;
+        const ageMs = typeof pendingSchedule.startedAtMs === 'number'
+            ? Math.max(0, Date.now() - pendingSchedule.startedAtMs)
+            : null;
+        const durationMs = pendingSchedule.durationMs ?? 0;
+        // Drop if audio already finished playing
+        if (ageMs != null && durationMs > 0 && ageMs > durationMs + 500) {
+            __DEV__ && console.log('[TalkingHead] Dropping expired pending viseme schedule', {
+                requestId: pendingSchedule.requestId ?? null,
+                ageMs,
+                durationMs,
+            });
+            pendingVisemeScheduleRef.current = null;
+            return;
+        }
+        __DEV__ && console.log('[TalkingHead] Applying pending viseme schedule', {
+            requestId: pendingSchedule.requestId ?? null,
+            cues: pendingSchedule.cues.length,
+            ageMs,
+        });
+        activeAvatar()?.scheduleVisemes(pendingSchedule);
+        onVisemeScheduleApplied?.({
+            requestId: pendingSchedule.requestId ?? null,
+            appliedAtMs: Date.now(),
+        });
+        lastScheduledVisemeKeyRef.current = `${pendingSchedule.requestId ?? 'anonymous'}:${pendingSchedule.startedAtMs ?? 0}`;
+        pendingVisemeScheduleRef.current = null;
+    }, [onVisemeScheduleApplied, activeAvatar]);
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        setMood: (m) => setMood(m),
+        sendAmplitude: (a) => activeAvatar()?.sendAmplitude(a),
+        sendViseme: (viseme, weight) => activeAvatar()?.sendViseme(viseme, weight),
+        clearVisemes: () => activeAvatar()?.clearVisemes(),
+        scheduleVisemes: (schedule) => {
+            const scheduleKey = `${schedule.requestId ?? 'anonymous'}:${schedule.startedAtMs ?? 0}`;
+            if (lastScheduledVisemeKeyRef.current === scheduleKey)
+                return;
+            const av = activeAvatar();
+            // Filament buffers pending schedules internally — no ready gate needed.
+            // WebView (avatarRef) still needs the ready gate.
+            if (!av || (!filamentRef.current && !isAvatarReady)) {
+                pendingVisemeScheduleRef.current = schedule;
+                return;
+            }
+            av.scheduleVisemes(schedule);
+            onVisemeScheduleApplied?.({ requestId: schedule.requestId ?? null, appliedAtMs: Date.now() });
+            lastScheduledVisemeKeyRef.current = scheduleKey;
+        },
+    }), [isAvatarReady, onVisemeScheduleApplied, activeAvatar]);
+    (0, react_1.useEffect)(() => {
+        setMood(initialMood);
+    }, [initialMood]);
+    (0, react_1.useEffect)(() => {
+        setIsAvatarReady(false);
+        setAvatarError(null);
+        setUseFallback(false);
+        setLoadingState({ stage: 'booting', progress: null });
+        pendingVisemeScheduleRef.current = null;
+        lastScheduledVisemeKeyRef.current = null;
+    }, [avatarUrl]);
+    const handleError = (0, react_1.useCallback)((message) => {
+        console.warn('[TalkingHeadVisualization] Avatar load failed, switching to fallback:', message);
+        setAvatarError(message);
+        setUseFallback(true);
+    }, []);
+    // Effective avatar URL: use remote if available, fallback GLB if error or missing
+    const effectiveAvatarUrl = useFallback || !avatarUrl ? fallbackUrl : avatarUrl;
+    const handleLoadingChange = (0, react_1.useCallback)((nextState) => {
+        setLoadingState({
+            stage: nextState.stage,
+            progress: typeof nextState.progress === 'number' && Number.isFinite(nextState.progress)
+                ? Math.max(0, Math.min(100, Math.round(nextState.progress)))
+                : null,
+        });
+    }, []);
+    (0, react_1.useEffect)(() => {
+        if (!visemeSchedule || visemeSchedule.cues.length === 0)
+            return;
+        const scheduleKey = `${visemeSchedule.requestId ?? 'anonymous'}:${visemeSchedule.startedAtMs ?? 0}`;
+        if (lastScheduledVisemeKeyRef.current === scheduleKey)
+            return;
+        __DEV__ && console.log('[TalkingHead] Received viseme schedule', {
+            requestId: visemeSchedule.requestId ?? null,
+            cues: visemeSchedule.cues.length,
+            ageMs: typeof visemeSchedule.startedAtMs === 'number'
+                ? Math.max(0, Date.now() - visemeSchedule.startedAtMs)
+                : null,
+            ready: isAvatarReady,
+        });
+        const av = activeAvatar();
+        if (!av || (!filamentRef.current && !isAvatarReady)) {
+            pendingVisemeScheduleRef.current = visemeSchedule;
+            return;
+        }
+        __DEV__ && console.log('[TalkingHead] Scheduling visemes immediately', {
+            requestId: visemeSchedule.requestId ?? null,
+            cues: visemeSchedule.cues.length,
+        });
+        av.scheduleVisemes(visemeSchedule);
+        onVisemeScheduleApplied?.({
+            requestId: visemeSchedule.requestId ?? null,
+            appliedAtMs: Date.now(),
+        });
+        lastScheduledVisemeKeyRef.current = scheduleKey;
+    }, [isAvatarReady, onVisemeScheduleApplied, visemeSchedule, activeAvatar]);
+    // On native use Filament — direct morph writes, no WebView bridge.
+    if (react_native_1.Platform.OS !== 'web') {
+        return ((0, jsx_runtime_1.jsx)(FilamentAvatar_1.FilamentAvatar, { focalLength: focalLength, ref: (fr) => {
+                filamentRef.current = fr;
+                if (typeof ref === 'function')
+                    ref(fr);
+                else if (ref)
+                    ref.current = fr;
+                if (fr && pendingVisemeScheduleRef.current) {
+                    fr.scheduleVisemes(pendingVisemeScheduleRef.current);
+                    pendingVisemeScheduleRef.current = null;
+                }
+            }, style: style, avatarUrl: avatarUrl ?? null, aspect: aspect, mood: mood, accessories: accessories, onReady: handleReady, onError: handleError }));
+    }
+    if (!effectiveAvatarUrl) {
+        return ((0, jsx_runtime_1.jsx)(react_native_1.View, { style: [style, styles.placeholder] }));
+    }
+    return ((0, jsx_runtime_1.jsxs)(react_native_1.View, { style: [style, styles.container], pointerEvents: "box-none", children: [(0, jsx_runtime_1.jsx)(TalkingHead_1.TalkingHead, { ref: avatarRef, avatarUrl: effectiveAvatarUrl, authToken: authToken, cameraView: cameraView, cameraDistance: cameraDistance, accessories: accessories, mood: mood, onLoadingChange: handleLoadingChange, onReady: handleReady, onError: handleError, style: react_native_1.StyleSheet.absoluteFill, vendorBaseUrl: vendorBaseUrl }), !isAvatarReady && ((0, jsx_runtime_1.jsx)(react_native_1.View, { testID: "talking-head-loading", style: styles.loadingOverlay, pointerEvents: "none", children: (0, jsx_runtime_1.jsxs)(react_native_1.View, { style: styles.loadingCard, children: [(0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.loadingBadge, children: (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.loadingBadgeText, children: "AVATAR" }) }), (0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.loadingTitle, children: avatarError ? 'Avatar failed to load' : getLoadingLabel(loadingState.stage) }), avatarError ? ((0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.loadingHint, children: avatarError })) : typeof loadingState.progress === 'number' ? ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)(react_native_1.Text, { style: styles.loadingPercent, children: [loadingState.progress, "%"] }), (0, jsx_runtime_1.jsx)(react_native_1.View, { style: styles.progressTrack, children: (0, jsx_runtime_1.jsx)(react_native_1.View, { style: [
+                                            styles.progressFill,
+                                            { width: `${Math.max(6, loadingState.progress)}%` },
+                                        ] }) })] })) : ((0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.loadingHint, children: "Preparing the avatar scene\u2026" }))] }) }))] }));
+});
+exports.TalkingHeadVisualization.displayName = 'TalkingHeadVisualization';
+const styles = react_native_1.StyleSheet.create({
+    container: {
+        overflow: 'hidden',
+    },
+    loadingOverlay: {
+        ...react_native_1.StyleSheet.absoluteFillObject,
+        alignItems: 'center',
+        justifyContent: 'center',
+        backgroundColor: 'rgba(5, 10, 18, 0.42)',
+        padding: 20,
+    },
+    loadingCard: {
+        minWidth: 190,
+        maxWidth: 240,
+        borderRadius: 20,
+        paddingHorizontal: 18,
+        paddingVertical: 16,
+        backgroundColor: 'rgba(13, 20, 31, 0.88)',
+        borderWidth: 1,
+        borderColor: 'rgba(151, 163, 184, 0.18)',
+        alignItems: 'center',
+    },
+    loadingBadge: {
+        paddingHorizontal: 8,
+        paddingVertical: 4,
+        borderRadius: 999,
+        backgroundColor: 'rgba(83, 156, 255, 0.16)',
+        marginBottom: 10,
+    },
+    loadingBadgeText: {
+        color: '#c7dbff',
+        fontSize: 10,
+        fontWeight: '700',
+        letterSpacing: 1.1,
+    },
+    loadingTitle: {
+        color: '#f8fbff',
+        fontSize: 18,
+        fontWeight: '700',
+    },
+    loadingPercent: {
+        marginTop: 8,
+        color: '#7dd3fc',
+        fontSize: 28,
+        fontWeight: '800',
+    },
+    loadingHint: {
+        marginTop: 10,
+        color: 'rgba(226, 232, 240, 0.82)',
+        fontSize: 13,
+        textAlign: 'center',
+    },
+    progressTrack: {
+        width: '100%',
+        height: 8,
+        borderRadius: 999,
+        backgroundColor: 'rgba(148, 163, 184, 0.18)',
+        marginTop: 12,
+        overflow: 'hidden',
+    },
+    progressFill: {
+        height: '100%',
+        borderRadius: 999,
+        backgroundColor: '#5eead4',
+    },
+    placeholder: {
+        backgroundColor: 'rgba(30,34,53,0.5)',
+        alignItems: 'center',
+        justifyContent: 'center',
+    },
+});

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from './types';
+export * from './studioApi';

package/dist/api/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./studioApi"), exports);

package/dist/api/studioApi.d.ts

@@ -0,0 +1,38 @@
+import type { Avatar, AvatarUpdate, PublicAvatar, VoiceProfile, ProfileSample, WearableAsset, PlacementSuggestion } from './types';
+export declare function configureAvatarApi(opts: {
+    baseUrl?: string;
+    getToken: () => Promise<string | null>;
+}): void;
+export declare function getToken(): Promise<string | null>;
+export declare function studioFetch<T>(path: string, options?: RequestInit): Promise<T>;
+export declare function getMyAvatars(): Promise<Avatar[]>;
+export declare function getAvatar(id: string): Promise<Avatar>;
+export declare function updateAvatar(id: string, data: AvatarUpdate): Promise<Avatar>;
+export declare function deleteAvatar(id: string): Promise<void>;
+export declare function createAvatar(fileUri: string, name: string, description?: string): Promise<Avatar>;
+export declare function getPublicAvatars(): Promise<PublicAvatar[]>;
+export declare function getVoiceProfileSamples(profileId: string): Promise<ProfileSample[]>;
+export declare function getVoiceProfiles(): Promise<VoiceProfile[]>;
+export declare function setDefaultVoice(avatarId: string, profileId: string): Promise<Avatar>;
+export declare function removeDefaultVoice(avatarId: string): Promise<Avatar>;
+export declare function avatarFileUrl(avatar: Avatar): string;
+export declare function avatarThumbnailUrl(avatar: Avatar | PublicAvatar): string | null;
+export declare function avatarAnimatedThumbnailUrl(avatar: Avatar | PublicAvatar): string | null;
+export declare function thumbnailHeaders(): Promise<Record<string, string>>;
+export declare function listAssets(category?: string): Promise<WearableAsset[]>;
+export declare function getAsset(id: string): Promise<WearableAsset>;
+export declare function uploadAsset(fileUri: string, meta: {
+    name: string;
+    category: string;
+    type: 'skinned' | 'rigid';
+    slot?: string;
+    attach_bone?: string;
+    offset_position?: number[];
+    offset_rotation?: number[];
+    hides_body_parts?: string[];
+}): Promise<WearableAsset>;
+export declare function deleteAsset(id: string): Promise<void>;
+export declare function suggestPlacement(assetId: string, avatarId: string): Promise<PlacementSuggestion>;
+export declare function assetFileUrl(asset: WearableAsset): string;
+export declare function createVoiceProfile(name: string, language?: string): Promise<VoiceProfile>;
+export declare function uploadVoiceSample(profileId: string, fileUri: string, fileName: string, referenceText: string): Promise<VoiceProfile>;