talking-head-studio 0.3.2 → 0.3.3

package/dist/TalkingHead.d.ts

@@ -54,6 +54,7 @@ export interface TalkingHeadProps {
     onLoadingChange?: (state: TalkingHeadLoadingState) => void;
     onReady?: () => void;
     onError?: (message: string) => void;
+    onAvatarState?: (state: string) => void;
     style?: StyleProp<ViewStyle>;
     /** Base URL for vendored assets. When set, replaces all cdn.jsdelivr.net references. */
     vendorBaseUrl?: string | null;
@@ -92,5 +93,7 @@ export interface TalkingHeadRef {
     setSkinColor: (color: string) => void;
     setEyeColor: (color: string) => void;
     setAccessories: (accessories: TalkingHeadAccessory[]) => void;
+    /** Dispatch a named motion/gesture to the avatar (e.g. 'wave_right', 'dance_idle'). */
+    dispatchMotion: (name: string) => void;
 }
 export declare const TalkingHead: React.ForwardRefExoticComponent<TalkingHeadProps & React.RefAttributes<TalkingHeadRef>>;

package/dist/TalkingHead.js

@@ -6,7 +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");
-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) => {
+exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onLoadingChange, onReady, onError, onAvatarState, style, vendorBaseUrl, }, ref) => {
     const webViewRef = (0, react_1.useRef)(null);
     const readyRef = (0, react_1.useRef)(false);
     const firstMessageSeenRef = (0, react_1.useRef)(false);
@@ -23,6 +23,8 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
     onReadyRef.current = onReady;
     const onErrorRef = (0, react_1.useRef)(onError);
     onErrorRef.current = onError;
+    const onAvatarStateRef = (0, react_1.useRef)(onAvatarState);
+    onAvatarStateRef.current = onAvatarState;
     // 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.
@@ -124,6 +126,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 post({ type: 'set_accessories', accessories: newAccessories });
             }
         },
+        dispatchMotion: (name) => post({ type: 'motion', name }),
     }), [post]);
     // Sync mood via postMessage only — never causes a WebView reload
     (0, react_1.useEffect)(() => {
@@ -220,6 +223,9 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
             else if (msg.type === 'error') {
                 onErrorRef.current?.(msg.message);
             }
+            else if (msg.type === 'avatarState') {
+                onAvatarStateRef.current?.(msg.state);
+            }
             else if (msg.type === 'log') {
                 console.log('[TalkingHead]', msg.message);
             }

package/dist/TalkingHead.web.d.ts

@@ -23,6 +23,7 @@ export interface TalkingHeadProps {
     onLoadingChange?: (state: TalkingHeadLoadingState) => void;
     onReady?: () => void;
     onError?: (message: string) => void;
+    onAvatarState?: (state: string) => void;
     style?: React.CSSProperties;
 }
 export interface TalkingHeadRef {
@@ -34,5 +35,6 @@ export interface TalkingHeadRef {
     setSkinColor: (color: string) => void;
     setEyeColor: (color: string) => void;
     setAccessories: (accessories: TalkingHeadAccessory[]) => void;
+    dispatchMotion: (name: string) => void;
 }
 export declare const TalkingHead: React.ForwardRefExoticComponent<TalkingHeadProps & React.RefAttributes<TalkingHeadRef>>;

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, onLoadingChange, 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, onAvatarState, style, }, ref) => {
     const iframeRef = (0, react_1.useRef)(null);
     const readyRef = (0, react_1.useRef)(false);
     const pendingMoodRef = (0, react_1.useRef)(mood);
@@ -97,6 +97,7 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 post({ type: 'set_accessories', accessories: newAccessories });
             }
         },
+        dispatchMotion: (name) => post({ type: 'motion', name }),
     }), [post]);
     (0, react_1.useEffect)(() => {
         pendingMoodRef.current = mood;
@@ -188,6 +189,9 @@ exports.TalkingHead = (0, react_1.forwardRef)(({ avatarUrl, authToken, mood = 'n
                 else if (msg.type === 'error') {
                     onError?.(msg.message);
                 }
+                else if (msg.type === 'avatarState') {
+                    onAvatarState?.(msg.state);
+                }
                 else if (msg.type === 'log') {
                     console.log('[TalkingHead]', msg.message);
                 }

package/dist/html.js

@@ -856,6 +856,12 @@ function onIncomingMessage(event) {
       EYE_COLOR = msg.value; applyColorOverrides();
     } else if (msg.type === 'set_accessories') {
       applyAccessories(msg.accessories || []);
+    } else if (msg.type === 'motion' && typeof msg.name === 'string') {
+      if ((window as any).motionEngine) {
+        (window as any).motionEngine.play(msg.name).catch(() => {});
+      }
+      window.ReactNativeWebView?.postMessage(JSON.stringify({ type: 'avatarState', state: 'motion:' + msg.name }));
+      log('motion dispatched: ' + msg.name);
     }
   } catch (err) {
     log('Message parse error: ' + err);

package/dist/index.d.ts

@@ -10,3 +10,4 @@ export { TalkingHeadVisualization } from './TalkingHeadVisualization';
 export type { TalkingHeadVisualizationRef } from './TalkingHeadVisualization';
 export { useDirectVisemeStream } from './tts/useDirectVisemeStream';
 export type { VisemeStreamPayload } from './tts/useDirectVisemeStream';
+export { useMotionMarkers } from './tts/useMotionMarkers';

package/dist/index.js

@@ -14,7 +14,7 @@ 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 });
-exports.useDirectVisemeStream = exports.TalkingHeadVisualization = exports.normalizeAppearance = exports.pickTargetForMaterialName = exports.applyAppearanceToObject3D = exports.TalkingHead = void 0;
+exports.useMotionMarkers = exports.useDirectVisemeStream = exports.TalkingHeadVisualization = exports.normalizeAppearance = exports.pickTargetForMaterialName = exports.applyAppearanceToObject3D = exports.TalkingHead = void 0;
 var TalkingHead_1 = require("./TalkingHead");
 Object.defineProperty(exports, "TalkingHead", { enumerable: true, get: function () { return TalkingHead_1.TalkingHead; } });
 // Export appearance utilities, but exclude AvatarAppearance — the canonical
@@ -31,3 +31,5 @@ var TalkingHeadVisualization_1 = require("./TalkingHeadVisualization");
 Object.defineProperty(exports, "TalkingHeadVisualization", { enumerable: true, get: function () { return TalkingHeadVisualization_1.TalkingHeadVisualization; } });
 var useDirectVisemeStream_1 = require("./tts/useDirectVisemeStream");
 Object.defineProperty(exports, "useDirectVisemeStream", { enumerable: true, get: function () { return useDirectVisemeStream_1.useDirectVisemeStream; } });
+var useMotionMarkers_1 = require("./tts/useMotionMarkers");
+Object.defineProperty(exports, "useMotionMarkers", { enumerable: true, get: function () { return useMotionMarkers_1.useMotionMarkers; } });

package/dist/tts/useMotionMarkers.d.ts

@@ -0,0 +1,2 @@
+import type { TalkingHeadRef } from '../TalkingHead';
+export declare function useMotionMarkers(ref: React.RefObject<TalkingHeadRef | null>): (text: string) => string;

package/dist/tts/useMotionMarkers.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMotionMarkers = useMotionMarkers;
+const react_1 = require("react");
+/**
+ * Parses ::marker_name:: tokens out of LLM transcript text, fires the
+ * corresponding motion on the avatar ref, and returns the cleaned text
+ * (markers stripped) ready to pass to TTS.
+ *
+ * Supports optional arguments: ::wave_right(slow):: — the arg string is
+ * forwarded as the second parameter of dispatchMotion for future use.
+ *
+ * @example
+ * const parseMarkers = useMotionMarkers(avatarRef);
+ * const cleanText = parseMarkers(rawLlmText); // fires motions, strips markers
+ * tts.speak(cleanText);
+ */
+const MARKER_RE = /::([a-z][a-z0-9_]*)(?:\(([^)]*)\))?::/g;
+function useMotionMarkers(ref) {
+    return (0, react_1.useCallback)((text) => text.replace(MARKER_RE, (_, name) => {
+        ref.current?.dispatchMotion(name);
+        return '';
+    }), [ref]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talking-head-studio",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "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",