talking-head-studio 0.4.11 → 0.4.12

package/dist/TalkingHead.js

@@ -6,6 +6,7 @@ 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");
+const shouldLogDebugMessages = __DEV__;
 exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onLoadingChange, onReady, onError, onAvatarState, onVoiceMood, style, vendorBaseUrl, }, ref) => {
     const webViewRef = (0, react_1.useRef)(null);
     const readyRef = (0, react_1.useRef)(false);
@@ -129,6 +130,14 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             }
         },
         dispatchMotion: (name) => post({ type: 'motion', name }),
+        stopMotion: () => post({ type: 'stop_motion' }),
+        playGesture: (name, opts) => post({ type: 'gesture', name, dur: opts?.dur, mirror: opts?.mirror, ms: opts?.ms }),
+        stopGesture: (ms) => post({ type: 'stop_gesture', ms }),
+        playPose: (url, dur) => post({ type: 'pose', url, dur }),
+        stopPose: () => post({ type: 'stop_pose' }),
+        playAnimation: (url, opts) => post({ type: 'animation', url, dur: opts?.dur, index: opts?.index }),
+        stopAnimation: () => post({ type: 'stop_animation' }),
+        lookAt: (x, y, ms) => post({ type: 'look_at', x, y, ms }),
     }), [post]);
     // Sync mood via postMessage only — never causes a WebView reload
     (0, react_1.useEffect)(() => {
@@ -231,7 +240,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             else if (msg.type === 'voiceMood') {
                 onVoiceMoodRef.current?.(msg.mood);
             }
-            else if (msg.type === 'log') {
+            else if (msg.type === 'log' && shouldLogDebugMessages) {
                 console.log('[TalkingHead]', msg.message);
             }
         }
@@ -249,7 +258,17 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
         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) }));
+    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: () => {
+                if (shouldLogDebugMessages)
+                    console.log('[TalkingHead] WebView load start');
+            }, onLoadEnd: () => {
+                if (shouldLogDebugMessages)
+                    console.log('[TalkingHead] WebView load end');
+            }, onLoadProgress: (event) => {
+                if (shouldLogDebugMessages) {
+                    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,7 +1,8 @@
 import React from 'react';
-import type { TalkingHeadLoadingState, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule } from './TalkingHead';
-export type { TalkingHeadLoadingState, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule };
-export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'excited' | 'thinking' | 'concerned' | 'surprised';
+import type { TalkingHeadLoadingState, TalkingHeadLoadingStage, TalkingHeadViseme, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule } from './TalkingHead';
+import type { MotionKey, TalkingHeadGesture, TalkingHeadPose } from './core/avatar/motion';
+export type { TalkingHeadLoadingStage, TalkingHeadLoadingState, TalkingHeadViseme, TalkingHeadVisemeCue, TalkingHeadVisemeSchedule, };
+export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'fear' | 'disgust' | 'love' | 'sleep' | 'excited' | 'thinking' | 'concerned' | 'surprised';
 export interface TalkingHeadAccessory {
     id: string;
     url: string;
@@ -31,6 +32,7 @@ export type TalkingHeadPropsAlias = TalkingHeadProps;
 export type AvatarPlayerProps = TalkingHeadProps;
 export interface TalkingHeadRef {
     sendAmplitude: (amplitude: number) => void;
+    sendViseme: (viseme: TalkingHeadViseme, weight?: number) => void;
     scheduleVisemes: (schedule: TalkingHeadVisemeSchedule) => void;
     clearVisemes: () => void;
     setMood: (mood: TalkingHeadMood) => void;
@@ -38,7 +40,32 @@ export interface TalkingHeadRef {
     setSkinColor: (color: string) => void;
     setEyeColor: (color: string) => void;
     setAccessories: (accessories: TalkingHeadAccessory[]) => void;
-    dispatchMotion: (name: string) => void;
+    /** Play a procedural motion (e.g. 'attack', 'defend', 'groove'). */
+    dispatchMotion(name: MotionKey): void;
+    dispatchMotion(name: string): void;
+    /** Stop the current procedural motion and return to rest. */
+    stopMotion: () => void;
+    /** Play an upstream TalkingHead hand gesture (e.g. 'thumbup'). */
+    playGesture: (name: TalkingHeadGesture | string, opts?: {
+        dur?: number;
+        mirror?: boolean;
+        ms?: number;
+    }) => void;
+    /** Stop the current gesture, easing out over `ms`. */
+    stopGesture: (ms?: number) => void;
+    /** Strike a pose — a built-in template name (e.g. 'oneknee') or a pose-file URL. */
+    playPose: (urlOrTemplate: TalkingHeadPose | string, dur?: number) => void;
+    /** Release the current pose and return to the default stance. */
+    stopPose: () => void;
+    /** Play a full body animation from a GLB/FBX URL (e.g. a combat move). */
+    playAnimation: (url: string, opts?: {
+        dur?: number;
+        index?: number;
+    }) => void;
+    /** Stop the current body animation. */
+    stopAnimation: () => void;
+    /** Turn head/eyes toward viewport coordinates (px), easing over `ms`. */
+    lookAt: (x: number, y: number, ms?: number) => void;
 }
 /** @deprecated Use AvatarPlayerRef */
 export type TalkingHeadRefAlias = TalkingHeadRef;

package/dist/TalkingHead.web.js

@@ -37,6 +37,7 @@ exports.TalkingHead = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = __importStar(require("react"));
 const html_1 = require("./html");
+const shouldLogDebugMessages = typeof process !== 'undefined' && process.env.NODE_ENV !== 'production';
 const containerStyle = {
     overflow: 'hidden',
     borderRadius: 12,
@@ -79,6 +80,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
     }, []);
     (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) => {
@@ -108,6 +110,14 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             }
         },
         dispatchMotion: (name) => post({ type: 'motion', name }),
+        stopMotion: () => post({ type: 'stop_motion' }),
+        playGesture: (name, opts) => post({ type: 'gesture', name, dur: opts?.dur, mirror: opts?.mirror, ms: opts?.ms }),
+        stopGesture: (ms) => post({ type: 'stop_gesture', ms }),
+        playPose: (url, dur) => post({ type: 'pose', url, dur }),
+        stopPose: () => post({ type: 'stop_pose' }),
+        playAnimation: (url, opts) => post({ type: 'animation', url, dur: opts?.dur, index: opts?.index }),
+        stopAnimation: () => post({ type: 'stop_animation' }),
+        lookAt: (x, y, ms) => post({ type: 'look_at', x, y, ms }),
     }), [post]);
     (0, react_1.useEffect)(() => {
         pendingMoodRef.current = mood;
@@ -202,7 +212,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 else if (msg.type === 'avatarState') {
                     onAvatarStateRef.current?.(msg.state);
                 }
-                else if (msg.type === 'log') {
+                else if (msg.type === 'log' && shouldLogDebugMessages) {
                     console.log('[TalkingHead]', msg.message);
                 }
             }

package/dist/TalkingHeadVisualization.d.ts

@@ -1,3 +1,4 @@
+import './wgpu/blobShim';
 import React from 'react';
 import { ViewStyle, StyleProp } from 'react-native';
 import { type TalkingHeadMood, type TalkingHeadAccessory, type TalkingHeadViseme, type TalkingHeadVisemeSchedule } from './TalkingHead';
@@ -27,6 +28,27 @@ export interface TalkingHeadVisualizationRef {
     clearVisemes: () => void;
     /** Trigger a named motion on the avatar (e.g. 'celebrate', 'groove', 'wave') */
     playMotion: (name: string) => void;
+    /** Stop the current procedural motion and return to rest. */
+    stopMotion: () => void;
+    /** Play an upstream TalkingHead gesture or native procedural fallback. */
+    playGesture: (name: string, opts?: {
+        dur?: number;
+        mirror?: boolean;
+        ms?: number;
+    }) => void;
+    /** Stop the current gesture. */
+    stopGesture: (ms?: number) => void;
+    /** Strike a pose by built-in name or pose URL. */
+    playPose: (name: string, dur?: number) => void;
+    /** Release the current pose and return to rest. */
+    stopPose: () => void;
+    /** Play a hosted animation clip on renderers that support it. */
+    playAnimation: (url: string, opts?: {
+        dur?: number;
+        index?: number;
+    }) => void;
+    /** Stop the current hosted animation clip. */
+    stopAnimation: () => void;
 }
 /**
  * TalkingHeadVisualization — optimized component for rendering the 3D avatar.

package/dist/TalkingHeadVisualization.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TalkingHeadVisualization = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
+// IMPORTANT: blobShim must be first — installs Blob+createObjectURL patch
+// before @react-three/fiber's polyfills() runs.
+require("./wgpu/blobShim");
 /* eslint-disable @typescript-eslint/no-unused-expressions */
 const react_1 = require("react");
 const react_native_1 = require("react-native");
@@ -60,7 +63,7 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
             setFallbackUrl(_fallbackDataUri);
             return;
         }
-        getFallbackAvatarUrl().then((u) => u && setFallbackUrl(u));
+        void getFallbackAvatarUrl().then((u) => u && setFallbackUrl(u));
     }, []);
     const [mood, setMood] = (0, react_1.useState)(initialMood);
     const [isAvatarReady, setIsAvatarReady] = (0, react_1.useState)(false);
@@ -98,7 +101,7 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
             cues: pendingSchedule.cues.length,
             ageMs,
         });
-        activeAvatar()?.scheduleVisemes(pendingSchedule);
+        activeAvatar()?.scheduleVisemes?.(pendingSchedule);
         onVisemeScheduleApplied?.({
             requestId: pendingSchedule.requestId ?? null,
             appliedAtMs: Date.now(),
@@ -108,10 +111,24 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
     }, [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(),
-        playMotion: (name) => avatarRef.current?.dispatchMotion(name),
+        sendAmplitude: (a) => activeAvatar()?.sendAmplitude?.(a),
+        sendViseme: (viseme, weight) => activeAvatar()?.sendViseme?.(viseme, weight),
+        clearVisemes: () => activeAvatar()?.clearVisemes?.(),
+        playMotion: (name) => {
+            const avatar = activeAvatar();
+            if (avatar?.playMotion) {
+                avatar.playMotion(name);
+                return;
+            }
+            avatar?.dispatchMotion?.(name);
+        },
+        stopMotion: () => activeAvatar()?.stopMotion?.(),
+        playGesture: (name, opts) => activeAvatar()?.playGesture?.(name, opts),
+        stopGesture: (ms) => activeAvatar()?.stopGesture?.(ms),
+        playPose: (name, dur) => activeAvatar()?.playPose?.(name, dur),
+        stopPose: () => activeAvatar()?.stopPose?.(),
+        playAnimation: (url, opts) => activeAvatar()?.playAnimation?.(url, opts),
+        stopAnimation: () => activeAvatar()?.stopAnimation?.(),
         scheduleVisemes: (schedule) => {
             const scheduleKey = `${schedule.requestId ?? 'anonymous'}:${schedule.startedAtMs ?? 0}`;
             if (lastScheduledVisemeKeyRef.current === scheduleKey)
@@ -119,7 +136,7 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
             const av = activeAvatar();
             // WgpuAvatar buffers pending schedules internally — no ready gate needed.
             // WebView (avatarRef) still needs the ready gate.
-            if (!av || (!wgpuRef.current && !isAvatarReady)) {
+            if (!av?.scheduleVisemes || (!wgpuRef.current && !isAvatarReady)) {
                 pendingVisemeScheduleRef.current = schedule;
                 return;
             }
@@ -140,8 +157,11 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
         lastScheduledVisemeKeyRef.current = null;
     }, [avatarUrl]);
     const handleError = (0, react_1.useCallback)((message) => {
-        console.warn('[TalkingHeadVisualization] Avatar load failed, switching to fallback:', message);
+        console.warn('[TalkingHeadVisualization] Avatar error:', message);
         setAvatarError(message);
+        // Only fall back to local GLB for hard load failures, not morph-target warnings
+        if (message.includes('morph') || message.includes('No mesh'))
+            return;
         setUseFallback(true);
     }, []);
     // Effective avatar URL: use remote if available, fallback GLB if error or missing
@@ -169,7 +189,7 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
             ready: isAvatarReady,
         });
         const av = activeAvatar();
-        if (!av || (!wgpuRef.current && !isAvatarReady)) {
+        if (!av?.scheduleVisemes || (!wgpuRef.current && !isAvatarReady)) {
             pendingVisemeScheduleRef.current = visemeSchedule;
             return;
         }
@@ -193,7 +213,7 @@ exports.TalkingHeadVisualization = (0, react_1.forwardRef)(({ style, avatarUrl,
     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, onVoiceMood: onVoiceMood, 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.jsxs)(react_native_1.View, { style: styles.progressTrack, children: [(0, jsx_runtime_1.jsx)(react_native_1.View, { style: { flex: Math.max(6, loadingState.progress ?? 0), height: '100%', borderRadius: 999, backgroundColor: '#5eead4' } }), (0, jsx_runtime_1.jsx)(react_native_1.View, { style: { flex: 100 - Math.max(6, loadingState.progress ?? 0) } })] })] })) : ((0, jsx_runtime_1.jsx)(react_native_1.Text, { style: styles.loadingHint, children: "Preparing the avatar scene\u2026" }))] }) }))] }));
+    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, onVoiceMood: onVoiceMood, style: react_native_1.StyleSheet.absoluteFillObject, 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.jsxs)(react_native_1.View, { style: styles.progressTrack, children: [(0, jsx_runtime_1.jsx)(react_native_1.View, { style: { flex: Math.max(6, loadingState.progress ?? 0), height: '100%', borderRadius: 999, backgroundColor: '#5eead4' } }), (0, jsx_runtime_1.jsx)(react_native_1.View, { style: { flex: 100 - Math.max(6, loadingState.progress ?? 0) } })] })] })) : ((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({

package/dist/api/studioApi.d.ts

@@ -9,7 +9,18 @@ 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 interface CreateAvatarOptions {
+    /** Sketchfab model uid this avatar was imported from. */
+    sketchfabUid?: string;
+    /** Whether the GLB has morph targets (enables real lipsync). */
+    sketchfabHasMorphs?: boolean;
+}
+export declare function createAvatar(fileUri: string, name: string, description?: string, options?: CreateAvatarOptions): Promise<Avatar>;
+/**
+ * Sketchfab uids that previously imported with working morph targets.
+ * Used to pin "verified" models to the top of search results.
+ */
+export declare function getVerifiedSketchfabUids(): Promise<string[]>;
 export declare function getPublicAvatars(): Promise<PublicAvatar[]>;
 export declare function getVoiceProfileSamples(profileId: string): Promise<ProfileSample[]>;
 export declare function getVoiceProfiles(): Promise<VoiceProfile[]>;

package/dist/api/studioApi.js

@@ -8,6 +8,7 @@ exports.getAvatar = getAvatar;
 exports.updateAvatar = updateAvatar;
 exports.deleteAvatar = deleteAvatar;
 exports.createAvatar = createAvatar;
+exports.getVerifiedSketchfabUids = getVerifiedSketchfabUids;
 exports.getPublicAvatars = getPublicAvatars;
 exports.getVoiceProfileSamples = getVoiceProfileSamples;
 exports.getVoiceProfiles = getVoiceProfiles;
@@ -28,7 +29,9 @@ exports.uploadVoiceSample = uploadVoiceSample;
 // ---------------------------------------------------------------------------
 // Injectable configuration
 // ---------------------------------------------------------------------------
-let _baseUrl = process.env.EXPO_PUBLIC_BACKEND_URL ?? '';
+let _baseUrl = typeof process !== 'undefined'
+    ? process.env.EXPO_PUBLIC_BACKEND_URL ?? ''
+    : '';
 let _getToken = null;
 function configureAvatarApi(opts) {
     if (opts.baseUrl !== undefined)
@@ -110,7 +113,7 @@ function updateAvatar(id, data) {
 function deleteAvatar(id) {
     return studioFetch(`/v1/avatars/${id}`, { method: 'DELETE' });
 }
-async function createAvatar(fileUri, name, description) {
+async function createAvatar(fileUri, name, description, options) {
     const formData = new FormData();
     formData.append('file', {
         uri: fileUri,
@@ -121,8 +124,19 @@ async function createAvatar(fileUri, name, description) {
     if (description) {
         formData.append('description', description);
     }
+    if (options?.sketchfabUid) {
+        formData.append('sketchfab_uid', options.sketchfabUid);
+        formData.append('sketchfab_has_morphs', options.sketchfabHasMorphs ? 'true' : 'false');
+    }
     return studioFetchForm('/v1/avatars', 'POST', formData);
 }
+/**
+ * Sketchfab uids that previously imported with working morph targets.
+ * Used to pin "verified" models to the top of search results.
+ */
+function getVerifiedSketchfabUids() {
+    return studioFetch('/v1/sketchfab/verified').then((r) => r.uids);
+}
 function getPublicAvatars() {
     return studioFetch('/v1/avatars/public');
 }

package/dist/contract.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable avatar contract entrypoint for SiteBay clients.
+ *
+ * Runtime packages should import avatar control, viseme, and backend surface
+ * types from `talking-head-studio/contract` instead of reaching into internal
+ * `src/core/avatar/*` paths.
+ */
+export type { AgentVisemePayload, ArkitBlendShape, EngineVisemeMappingArtifact, OculusViseme, OculusVisemeWeights, RhubarbViseme, VisemeCue, } from './core/avatar/visemes';
+export { ARKIT_TO_OCULUS, ENGINE_VISEME_MAPPING, OCULUS_MORPH_TARGET_NAMES, OCULUS_VISEMES, RHUBARB_TO_OCULUS, RHUBARB_VISEMES, getArkitWeightsForViseme, oculusWeightsForRhubarbCue, remapArkitToOculus, } from './core/avatar/visemes';
+export type { EyeGaze, ExpressionState, FaceControl, HeadPose, Viseme, } from './core/avatar/faceControls';
+export { applyVisemeToExpression, createNeutralExpression, visemeToExpression, } from './core/avatar/faceControls';
+export type { AvatarBackend, AvatarRenderTarget, CalibrationProfile, } from './core/avatar/backend';
+export { MOTION_DEFS, MOTION_KEYS, isMotionKey, TALKINGHEAD_GESTURES, TALKINGHEAD_POSES, } from './core/avatar/motion';
+export type { MotionKey, MotionDef, MotionDefWithBones, MotionBoneKey, MotionOscillator, TalkingHeadGesture, TalkingHeadPose, } from './core/avatar/motion';

package/dist/contract.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Stable avatar contract entrypoint for SiteBay clients.
+ *
+ * Runtime packages should import avatar control, viseme, and backend surface
+ * types from `talking-head-studio/contract` instead of reaching into internal
+ * `src/core/avatar/*` paths.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TALKINGHEAD_POSES = exports.TALKINGHEAD_GESTURES = exports.isMotionKey = exports.MOTION_KEYS = exports.MOTION_DEFS = exports.visemeToExpression = exports.createNeutralExpression = exports.applyVisemeToExpression = exports.remapArkitToOculus = exports.oculusWeightsForRhubarbCue = exports.getArkitWeightsForViseme = exports.RHUBARB_VISEMES = exports.RHUBARB_TO_OCULUS = exports.OCULUS_VISEMES = exports.OCULUS_MORPH_TARGET_NAMES = exports.ENGINE_VISEME_MAPPING = exports.ARKIT_TO_OCULUS = void 0;
+var visemes_1 = require("./core/avatar/visemes");
+Object.defineProperty(exports, "ARKIT_TO_OCULUS", { enumerable: true, get: function () { return visemes_1.ARKIT_TO_OCULUS; } });
+Object.defineProperty(exports, "ENGINE_VISEME_MAPPING", { enumerable: true, get: function () { return visemes_1.ENGINE_VISEME_MAPPING; } });
+Object.defineProperty(exports, "OCULUS_MORPH_TARGET_NAMES", { enumerable: true, get: function () { return visemes_1.OCULUS_MORPH_TARGET_NAMES; } });
+Object.defineProperty(exports, "OCULUS_VISEMES", { enumerable: true, get: function () { return visemes_1.OCULUS_VISEMES; } });
+Object.defineProperty(exports, "RHUBARB_TO_OCULUS", { enumerable: true, get: function () { return visemes_1.RHUBARB_TO_OCULUS; } });
+Object.defineProperty(exports, "RHUBARB_VISEMES", { enumerable: true, get: function () { return visemes_1.RHUBARB_VISEMES; } });
+Object.defineProperty(exports, "getArkitWeightsForViseme", { enumerable: true, get: function () { return visemes_1.getArkitWeightsForViseme; } });
+Object.defineProperty(exports, "oculusWeightsForRhubarbCue", { enumerable: true, get: function () { return visemes_1.oculusWeightsForRhubarbCue; } });
+Object.defineProperty(exports, "remapArkitToOculus", { enumerable: true, get: function () { return visemes_1.remapArkitToOculus; } });
+var faceControls_1 = require("./core/avatar/faceControls");
+Object.defineProperty(exports, "applyVisemeToExpression", { enumerable: true, get: function () { return faceControls_1.applyVisemeToExpression; } });
+Object.defineProperty(exports, "createNeutralExpression", { enumerable: true, get: function () { return faceControls_1.createNeutralExpression; } });
+Object.defineProperty(exports, "visemeToExpression", { enumerable: true, get: function () { return faceControls_1.visemeToExpression; } });
+var motion_1 = require("./core/avatar/motion");
+Object.defineProperty(exports, "MOTION_DEFS", { enumerable: true, get: function () { return motion_1.MOTION_DEFS; } });
+Object.defineProperty(exports, "MOTION_KEYS", { enumerable: true, get: function () { return motion_1.MOTION_KEYS; } });
+Object.defineProperty(exports, "isMotionKey", { enumerable: true, get: function () { return motion_1.isMotionKey; } });
+Object.defineProperty(exports, "TALKINGHEAD_GESTURES", { enumerable: true, get: function () { return motion_1.TALKINGHEAD_GESTURES; } });
+Object.defineProperty(exports, "TALKINGHEAD_POSES", { enumerable: true, get: function () { return motion_1.TALKINGHEAD_POSES; } });

package/dist/core/avatar/avatarCapabilities.d.ts

@@ -0,0 +1,60 @@
+import { type AvatarSchemaReport, type VisemeTier } from './schema';
+import { type MotionBoneKey } from './motion';
+export interface MotionCoverage {
+    /** Motion-engine bone keys this rig can drive (head, spine, arms, …). */
+    matched: MotionBoneKey[];
+    /** Motion-engine bone keys with no matching bone. */
+    missing: MotionBoneKey[];
+    /** Enough of the body is rigged for the procedural motion engine to read as
+     *  "moving" (spine + head + at least one arm). */
+    ready: boolean;
+}
+export interface AvatarCapabilities {
+    /** Full schema report (visemes, skeleton, mesh) from walkAvatarSchema. */
+    schema: AvatarSchemaReport;
+    /** Best lip-sync strategy: oculus / arkit / minimal / none. */
+    lipSyncTier: VisemeTier;
+    /** Can this avatar lip-sync from a viseme schedule (morph-driven)? */
+    canLipSync: boolean;
+    /** Can the talking-head motion engine give this avatar body motion/gestures? */
+    canMove: boolean;
+    /** Procedural-motion bone coverage detail. */
+    motion: MotionCoverage;
+    /** Baked animation clip count (informational; the motion engine is procedural). */
+    animations: number;
+}
+type GltfJson = {
+    nodes?: {
+        name?: string;
+    }[];
+    meshes?: {
+        primitives?: {
+            indices?: number;
+            attributes?: Record<string, number>;
+            targets?: unknown[];
+        }[];
+        extras?: {
+            targetNames?: string[];
+        };
+    }[];
+    skins?: {
+        joints?: number[];
+    }[];
+    accessors?: {
+        count?: number;
+    }[];
+    animations?: unknown[];
+};
+/** Decode a .glb (binary) or .gltf (JSON) ArrayBuffer/Uint8Array into its glTF JSON. */
+export declare function parseGlbJson(data: ArrayBuffer | Uint8Array): GltfJson;
+/** Capability report from glTF JSON (the unit-testable core). */
+export declare function inspectAvatarGltf(json: GltfJson): AvatarCapabilities;
+/** Capability report from raw GLB/glTF bytes (browser: fetch(url).arrayBuffer()). */
+export declare function inspectAvatarCapabilities(data: ArrayBuffer | Uint8Array): AvatarCapabilities;
+/**
+ * Capability report from a GLB's raw JSON-chunk bytes — for the streaming
+ * import path that reads only the header + JSON chunk off disk (mirrors
+ * sketchfab's inspectGlbJsonChunk, but for full avatar capabilities).
+ */
+export declare function inspectAvatarJsonChunk(jsonBytes: Uint8Array): AvatarCapabilities;
+export {};

package/dist/core/avatar/avatarCapabilities.js

@@ -0,0 +1,100 @@
+"use strict";
+// src/core/avatar/glbInspect.ts
+// Pre-flight avatar capability check from raw GLB/glTF bytes — no Three.js, no
+// WebGL load required. Reuses walkAvatarSchema() (the single source of truth for
+// viseme tier + humanoid rig) by adapting the glTF JSON into the minimal scene
+// that walker expects, then layers on motion-engine bone coverage.
+//
+// The avatar creator runs this when a user picks/uploads/URLs an avatar, so it
+// can soft-warn ("this model can't lip-sync / won't gesture") before committing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseGlbJson = parseGlbJson;
+exports.inspectAvatarGltf = inspectAvatarGltf;
+exports.inspectAvatarCapabilities = inspectAvatarCapabilities;
+exports.inspectAvatarJsonChunk = inspectAvatarJsonChunk;
+const schema_1 = require("./schema");
+const motion_1 = require("./motion");
+/** Decode a .glb (binary) or .gltf (JSON) ArrayBuffer/Uint8Array into its glTF JSON. */
+function parseGlbJson(data) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    // GLB: 'glTF' magic (0x46546C67), then 12-byte header + JSON chunk.
+    if (bytes.length >= 12 && bytes[0] === 0x67 && bytes[1] === 0x6c && bytes[2] === 0x54 && bytes[3] === 0x46) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        const jsonLen = view.getUint32(12, true); // first chunk length (JSON)
+        const jsonBytes = bytes.subarray(20, 20 + jsonLen);
+        return JSON.parse(new TextDecoder().decode(jsonBytes));
+    }
+    // Otherwise assume .gltf JSON text.
+    return JSON.parse(new TextDecoder().decode(bytes));
+}
+const norm = (s) => s.toLowerCase().replace(/[_\s\-.]/g, '');
+/** Capability report from glTF JSON (the unit-testable core). */
+function inspectAvatarGltf(json) {
+    const nodes = json.nodes ?? [];
+    const meshes = json.meshes ?? [];
+    const skins = json.skins ?? [];
+    const accessors = json.accessors ?? [];
+    // Adapt the glTF JSON into the minimal { traverse } scene walkAvatarSchema wants.
+    const objects = [];
+    for (const skin of skins) {
+        const bones = (skin.joints ?? []).map((j) => ({ name: nodes[j]?.name }));
+        objects.push({ isSkinnedMesh: true, skeleton: { bones } });
+        for (const j of skin.joints ?? []) {
+            const nm = nodes[j]?.name;
+            if (nm)
+                objects.push({ isBone: true, name: nm });
+        }
+    }
+    for (const mesh of meshes) {
+        const targetNames = mesh.extras?.targetNames ?? [];
+        const dict = targetNames.length ? Object.fromEntries(targetNames.map((n, i) => [String(n), i])) : undefined;
+        let idxCount = 0;
+        let posCount = 0;
+        let hasIdx = false;
+        for (const prim of mesh.primitives ?? []) {
+            if (prim.indices != null && accessors[prim.indices]) {
+                idxCount += accessors[prim.indices].count ?? 0;
+                hasIdx = true;
+            }
+            const posIdx = prim.attributes?.POSITION;
+            if (posIdx != null && accessors[posIdx])
+                posCount += accessors[posIdx].count ?? 0;
+        }
+        objects.push({
+            isMesh: true,
+            ...(dict ? { morphTargetDictionary: dict } : {}),
+            geometry: hasIdx ? { index: { count: idxCount } } : { attributes: { position: { count: posCount } } },
+        });
+    }
+    const schema = (0, schema_1.walkAvatarSchema)({ traverse: (cb) => objects.forEach((o) => cb(o)) });
+    // Motion-engine coverage: which logical bones the procedural engine can drive.
+    const bonesNorm = schema.skeleton.bones.map(norm);
+    const matched = [];
+    const missing = [];
+    for (const [key, kws] of Object.entries(motion_1.MOTION_BONE_SEARCH)) {
+        const hit = kws.some((kw) => bonesNorm.some((b) => b.includes(norm(kw))));
+        (hit ? matched : missing).push(key);
+    }
+    const has = (k) => matched.includes(k);
+    const ready = schema.skeleton.hasRig && has('spine') && has('head') && (has('leftArm') || has('rightArm'));
+    return {
+        schema,
+        lipSyncTier: schema.morphs.visemeTier,
+        canLipSync: schema.morphs.visemeTier !== 'none',
+        canMove: ready,
+        motion: { matched, missing, ready },
+        animations: (json.animations ?? []).length,
+    };
+}
+/** Capability report from raw GLB/glTF bytes (browser: fetch(url).arrayBuffer()). */
+function inspectAvatarCapabilities(data) {
+    return inspectAvatarGltf(parseGlbJson(data));
+}
+/**
+ * Capability report from a GLB's raw JSON-chunk bytes — for the streaming
+ * import path that reads only the header + JSON chunk off disk (mirrors
+ * sketchfab's inspectGlbJsonChunk, but for full avatar capabilities).
+ */
+function inspectAvatarJsonChunk(jsonBytes) {
+    return inspectAvatarGltf(JSON.parse(new TextDecoder().decode(jsonBytes)));
+}

package/dist/core/avatar/backends/gaussian.js

@@ -142,10 +142,12 @@ class GaussianBackend {
         this.boneMap.clear();
         const allBones = new Map();
         this.scene.traverse((obj) => {
-            if (obj.isBone)
-                allBones.set(obj.name, obj);
-            if (obj.isSkinnedMesh && obj.skeleton?.bones) {
-                for (const b of obj.skeleton.bones) {
+            const bone = obj;
+            if (bone.isBone)
+                allBones.set(bone.name, bone);
+            const skinned = obj;
+            if (skinned.isSkinnedMesh && skinned.skeleton?.bones) {
+                for (const b of skinned.skeleton.bones) {
                     allBones.set(b.name, b);
                 }
             }