talking-head-studio 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SiteBay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,459 @@
+# talking-head-studio
+
+**Drop a talking, lip-syncing 3D avatar into any React app -- native or web -- in under five minutes.**
+
+[![npm version](https://img.shields.io/npm/v/talking-head-studio.svg)](https://www.npmjs.com/package/talking-head-studio)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://github.com/sitebay/react-native-talking-head/actions/workflows/ci.yml/badge.svg)](https://github.com/sitebay/react-native-talking-head/actions)
+
+---
+
+## Why this?
+
+- **Truly cross-platform.** One component, two renderers. React Native gets a WebView; React on web gets an iframe with `srcdoc`. Same API, same props, same ref.
+- **Bring any GLB.** Rigged models with ARKit/Oculus blend shapes get full phoneme-based lip-sync via HeadAudio. Non-rigged models still work -- they get a static viewer with amplitude-driven jaw animation as a fallback. No vendor lock-in to a single avatar format.
+- **Built for LLM voice pipelines.** Wire `sendAmplitude` to LiveKit, Web Audio, ElevenLabs, or any audio source. The avatar speaks when your AI speaks.
+- **Accessory system.** Attach hats, glasses, backpacks, or any GLB to any bone at runtime. Position, rotate, and scale each piece independently.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Subpath Exports](#subpath-exports)
+- [Props](#props)
+- [Ref API](#ref-api)
+- [Accessories](#accessories)
+- [Color Customization](#color-customization)
+- [Voice Pipeline Integration](#voice-pipeline-integration)
+- [GLB Compatibility](#glb-compatibility)
+- [Plain React / Next.js](#plain-react--nextjs)
+- [MotionEngine (Upcoming)](#motionengine-upcoming)
+- [Contributing](#contributing)
+- [Credits](#credits)
+- [License](#license)
+
+---
+
+## Installation
+
+### React Native / Expo
+
+```bash
+npm install talking-head-studio react-native-webview
+```
+
+`react-native-webview` is a peer dependency. If you are using Expo, it is available as a built-in package.
+
+### Web only (React, Next.js, Vite)
+
+```bash
+npm install talking-head-studio
+```
+
+No WebView dependency needed. The package ships a `.web.tsx` entry point that renders via `<iframe srcdoc>` automatically when bundled for web targets.
+
+---
+
+## Quick Start
+
+```tsx
+import { useRef } from 'react';
+import { TalkingHead, type TalkingHeadRef } from 'talking-head-studio';
+
+export default function Avatar() {
+  const ref = useRef<TalkingHeadRef>(null);
+
+  return (
+    <TalkingHead
+      ref={ref}
+      avatarUrl="https://models.readyplayer.me/your-model.glb"
+      mood="happy"
+      cameraView="upper"
+      hairColor="#1a1a2e"
+      skinColor="#e0a370"
+      accessories={[
+        {
+          id: 'sunglasses',
+          url: 'https://example.com/sunglasses.glb',
+          bone: 'Head',
+          position: [0, 0.08, 0.12],
+          rotation: [0, 0, 0],
+          scale: 1.0,
+        },
+      ]}
+      style={{ width: 400, height: 600 }}
+      onReady={() => console.log('Avatar loaded')}
+      onError={(msg) => console.error('Load failed:', msg)}
+    />
+  );
+}
+```
+
+---
+
+## Subpath Exports
+
+The package ships five independent entry points. Import only what you need — each subpath has its own optional peer dependencies.
+
+### `talking-head-studio` — Live talking avatar
+```tsx
+import { TalkingHead } from 'talking-head-studio';
+// Peer deps: react, react-native (optional), react-native-webview (optional)
+```
+
+### `talking-head-studio/editor` — 3D editor with gizmo (web)
+R3F-based canvas with PivotControls gizmo for placing accessories on an avatar. Web only.
+```tsx
+import { AvatarCanvas } from 'talking-head-studio/editor';
+// Peer deps: @react-three/fiber, @react-three/drei, three
+```
+
+### `talking-head-studio/appearance` — Material color system
+Apply skin/hair/eye colors to any GLB avatar. Works in both the live view and the 3D editor.
+```tsx
+import { applyAppearanceToObject3D, type AvatarAppearance } from 'talking-head-studio/appearance';
+// No extra peer deps
+```
+
+### `talking-head-studio/voice` — Audio recording hooks
+Headless hooks for recording voice samples (WebM→WAV conversion included). Backend-agnostic — send audio wherever you want (Qwen3-TTS, ElevenLabs, Groq, etc).
+```tsx
+import { useAudioRecording, useAudioPlayer } from 'talking-head-studio/voice';
+// No extra peer deps (browser APIs only)
+```
+
+### `talking-head-studio/sketchfab` — Sketchfab search & download
+Headless hooks and utilities for searching and downloading GLB models from Sketchfab. Bring your own UI and API key.
+```tsx
+import { useSketchfabSearch, ACCESSORY_CATEGORIES, downloadModel } from 'talking-head-studio/sketchfab';
+// No extra peer deps
+```
+
+---
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `avatarUrl` | `string` | **required** | URL to any `.glb` model. Rigged or non-rigged. |
+| `authToken` | `string \| null` | `null` | Bearer token sent when fetching the model URL. CDN URLs are excluded automatically. |
+| `mood` | `TalkingHeadMood` | `'neutral'` | Avatar expression. See [Moods](#moods) below. |
+| `cameraView` | `'head' \| 'upper' \| 'full'` | `'upper'` | Camera framing preset. |
+| `cameraDistance` | `number` | `-0.5` | Camera zoom offset. Negative values zoom in. |
+| `hairColor` | `string` | -- | CSS color applied to materials whose name contains `hair` or `fur`. |
+| `skinColor` | `string` | -- | CSS color applied to materials whose name contains `skin`, `body`, or `face`. |
+| `eyeColor` | `string` | -- | CSS color applied to materials whose name contains `eye` or `iris`. |
+| `accessories` | `TalkingHeadAccessory[]` | `[]` | Array of GLB items to attach to bones. See [Accessories](#accessories). |
+| `onReady` | `() => void` | -- | Fires once the avatar and scene are fully loaded. |
+| `onError` | `(message: string) => void` | -- | Fires on load failure. |
+| `style` | `ViewStyle` | -- | Container style (works on both native and web). |
+
+### Moods
+
+The `mood` prop accepts one of:
+
+```
+neutral | happy | sad | angry | excited | thinking | concerned | surprised
+```
+
+Mood can be changed at any time via props or the ref API. On rigged models, mood maps to blend shape expressions. On non-rigged models, mood is a no-op.
+
+---
+
+## Ref API
+
+Access runtime controls through a React ref. Every method is safe to call at any time -- calls made before the avatar is ready are silently dropped.
+
+```tsx
+const ref = useRef<TalkingHeadRef>(null);
+
+// Drive lip-sync from an audio amplitude value (0..1)
+ref.current?.sendAmplitude(0.7);
+
+// Change expression
+ref.current?.setMood('excited');
+
+// Change colors at runtime
+ref.current?.setHairColor('#ff0000');
+ref.current?.setSkinColor('#8d5524');
+ref.current?.setEyeColor('#2e86de');
+
+// Swap accessories without re-mounting the component
+ref.current?.setAccessories([
+  {
+    id: 'crown',
+    url: 'https://example.com/crown.glb',
+    bone: 'Head',
+    position: [0, 0.22, 0],
+    rotation: [0, 0, 0],
+    scale: 0.8,
+  },
+]);
+```
+
+### Ref Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `sendAmplitude` | `(amplitude: number) => void` | Feed audio amplitude (0 to 1) for jaw animation. |
+| `setMood` | `(mood: TalkingHeadMood) => void` | Change avatar expression at runtime. |
+| `setHairColor` | `(color: string) => void` | Update hair material color. |
+| `setSkinColor` | `(color: string) => void` | Update skin material color. |
+| `setEyeColor` | `(color: string) => void` | Update eye/iris material color. |
+| `setAccessories` | `(accessories: TalkingHeadAccessory[]) => void` | Replace the entire accessory set. Handles loading, diffing, and cleanup automatically. |
+
+---
+
+## Accessories
+
+Attach any GLB model to any bone on the avatar skeleton. The system handles loading, disposal, and transform updates.
+
+### Accessory shape
+
+```ts
+interface TalkingHeadAccessory {
+  id: string;                        // Unique identifier for diffing
+  url: string;                       // URL to a .glb file
+  bone: string;                      // Target bone name (e.g. "Head", "RightHand", "Spine")
+  position: [number, number, number]; // Offset from the bone origin
+  rotation: [number, number, number]; // Euler rotation in radians
+  scale: number;                      // Uniform scale factor
+}
+```
+
+### Example: hat + glasses + backpack
+
+```tsx
+<TalkingHead
+  avatarUrl="https://example.com/avatar.glb"
+  accessories={[
+    {
+      id: 'cowboy-hat',
+      url: '/models/cowboy-hat.glb',
+      bone: 'Head',
+      position: [0, 0.18, 0],
+      rotation: [0, 0, 0],
+      scale: 1.2,
+    },
+    {
+      id: 'aviators',
+      url: '/models/aviator-glasses.glb',
+      bone: 'Head',
+      position: [0, 0.06, 0.11],
+      rotation: [0, 0, 0],
+      scale: 1.0,
+    },
+    {
+      id: 'backpack',
+      url: '/models/backpack.glb',
+      bone: 'Spine1',
+      position: [0, 0, -0.15],
+      rotation: [0, Math.PI, 0],
+      scale: 0.9,
+    },
+  ]}
+/>
+```
+
+### Common bone names
+
+Mixamo-rigged models typically expose these bones:
+
+```
+Head, Neck, Spine, Spine1, Spine2,
+LeftShoulder, LeftArm, LeftForeArm, LeftHand,
+RightShoulder, RightArm, RightForeArm, RightHand,
+LeftUpLeg, LeftLeg, LeftFoot,
+RightUpLeg, RightLeg, RightFoot
+```
+
+Bone matching is flexible -- if an exact match is not found, the component tries a prefix match (useful for Sketchfab exports like `Head_5`). If no bone matches, the accessory falls back to the scene root.
+
+### Runtime accessory swaps
+
+```tsx
+// Remove all accessories
+ref.current?.setAccessories([]);
+
+// Swap glasses for a monocle
+ref.current?.setAccessories([
+  { id: 'monocle', url: '/models/monocle.glb', bone: 'Head', position: [0.03, 0.07, 0.11], rotation: [0, 0, 0], scale: 0.6 },
+]);
+```
+
+Accessories that were previously loaded but are absent from the new array are automatically disposed (geometry, materials, textures).
+
+---
+
+## Color Customization
+
+Colors can be set via props (applied on initial load) or via the ref API (applied at runtime without reloading the model).
+
+The system matches material names against known keywords:
+
+| Target | Material name keywords |
+|--------|----------------------|
+| Hair | `hair`, `fur` |
+| Skin | `skin`, `body`, `face` |
+| Eyes | `eye`, `iris` |
+
+```tsx
+// Via props
+<TalkingHead hairColor="#2d1b00" skinColor="#f0c8a0" eyeColor="#3d6b4f" />
+
+// Via ref (runtime)
+ref.current?.setHairColor('#ff4500');
+ref.current?.setSkinColor('#c68642');
+ref.current?.setEyeColor('#1abc9c');
+```
+
+This works on both rigged and non-rigged models -- any GLB with appropriately named materials will respond to color changes.
+
+---
+
+## Voice Pipeline Integration
+
+The component is designed to sit at the end of a voice pipeline. Feed it audio amplitude and it handles the rest.
+
+### Primary: HeadAudio phoneme lip-sync
+
+On rigged models in browser contexts with Web Audio available, [HeadAudio](https://github.com/met4citizen/HeadAudio) provides phoneme-level lip-sync automatically. Audio elements in the page are intercepted and routed through the lip-sync engine -- no wiring required on your end.
+
+### Fallback: amplitude-driven jaw
+
+When phoneme-level lip-sync is unavailable (React Native WebView, non-rigged models, or missing blend shapes), `sendAmplitude` drives jaw movement directly via morph targets.
+
+### LiveKit integration
+
+```tsx
+import { useDataChannel } from '@livekit/components-react';
+
+function AvatarWithLiveKit() {
+  const ref = useRef<TalkingHeadRef>(null);
+
+  useDataChannel('agent_speaking', (data) => {
+    if (data.amplitude !== undefined) {
+      ref.current?.sendAmplitude(data.amplitude);
+    }
+  });
+
+  return <TalkingHead ref={ref} avatarUrl="..." />;
+}
+```
+
+### Web Audio analyser
+
+```tsx
+const audioCtx = new AudioContext();
+const analyser = audioCtx.createAnalyser();
+const buf = new Uint8Array(analyser.frequencyBinCount);
+
+// Connect your audio source to the analyser
+source.connect(analyser);
+
+// Poll amplitude and feed the avatar
+const interval = setInterval(() => {
+  analyser.getByteFrequencyData(buf);
+  const amplitude = buf.reduce((a, b) => a + b, 0) / buf.length / 255;
+  ref.current?.sendAmplitude(amplitude);
+}, 50);
+```
+
+### Any audio source
+
+The only contract is a number between 0 and 1, called at roughly 20 Hz. This works with ElevenLabs, OpenAI Realtime, Deepgram, Whisper, or any other TTS/STT pipeline.
+
+---
+
+## GLB Compatibility
+
+### Rigged models (full feature set)
+
+For the complete experience -- phoneme lip-sync, expressions, moods, gestures -- your GLB should have:
+
+- A **Mixamo-compatible armature** (the component expects standard bone names)
+- **ARKit blend shapes** and/or **Oculus viseme blend shapes** for lip-sync
+- Standard Three.js-compatible GLB format
+
+Models from [Ready Player Me](https://readyplayer.me/), [Avaturn](https://avaturn.me/), or any Mixamo-rigged source work out of the box.
+
+### Non-rigged models (static fallback)
+
+Any valid GLB loads successfully. Non-rigged models get:
+
+- Auto-framing and centering in the viewport
+- Orbit controls for rotation
+- Embedded animation playback (walk cycles, idle loops, etc.)
+- Amplitude-driven jaw via morph targets (if the model has `jawOpen`, `mouthOpen`, or `viseme_aa` blend shapes)
+- Color customization (if materials are named appropriately)
+- Accessory attachment (falls back to scene root if no bones exist)
+
+### Upstream documentation
+
+For detailed model authoring guidance, see the [TalkingHead documentation](https://github.com/met4citizen/TalkingHead).
+
+---
+
+## Plain React / Next.js
+
+Despite the package name, this works on the web without React Native installed. The `react-native` and `react-native-webview` peer dependencies are both marked optional.
+
+On web, the component renders an `<iframe>` with `srcdoc` containing the full Three.js scene. No WebView, no native modules, no build plugins.
+
+```tsx
+// Works in any React 18+ web app
+import { TalkingHead } from 'talking-head-studio';
+
+export default function Page() {
+  return (
+    <TalkingHead
+      avatarUrl="/models/avatar.glb"
+      mood="happy"
+      style={{ width: 600, height: 800 }}
+    />
+  );
+}
+```
+
+Bundlers that support the `react-native` platform field (Metro, Expo) resolve `TalkingHead.tsx` (WebView). Standard web bundlers (webpack, Vite, esbuild) resolve `TalkingHead.web.tsx` (iframe). The API is identical.
+
+---
+
+## MotionEngine (Upcoming)
+
+[MotionEngine](https://github.com/lhupyn/motion-engine) integration is in development. This will add real-time body tracking and gesture replay to the avatar, driven by webcam or motion capture data.
+
+Stay tuned.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please open an issue to discuss your idea before submitting a pull request.
+
+```bash
+git clone https://github.com/sitebay/react-native-talking-head.git
+cd react-native-talking-head
+npm install
+npm run typecheck
+npm test
+```
+
+---
+
+## Credits
+
+This project builds on excellent open-source work:
+
+- [met4citizen/TalkingHead](https://github.com/met4citizen/TalkingHead) -- The 3D avatar engine powering model loading, rigging, and expression systems.
+- [met4citizen/HeadAudio](https://github.com/met4citizen/HeadAudio) -- Phoneme-based lip-sync from audio streams using AudioWorklet.
+- [lhupyn/motion-engine](https://github.com/lhupyn/motion-engine) -- Real-time body motion tracking (upcoming integration).
+- [Three.js](https://threejs.org/) -- 3D rendering, loaded via CDN at runtime.
+
+---
+
+## License
+
+MIT

package/dist/TalkingHead.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'excited' | 'thinking' | 'concerned' | 'surprised';
+export interface TalkingHeadAccessory {
+    id: string;
+    url: string;
+    bone: string;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+}
+export interface TalkingHeadProps {
+    avatarUrl: string;
+    authToken?: string | null;
+    mood?: TalkingHeadMood;
+    cameraView?: 'head' | 'upper' | 'full';
+    cameraDistance?: number;
+    hairColor?: string;
+    skinColor?: string;
+    eyeColor?: string;
+    accessories?: TalkingHeadAccessory[];
+    onReady?: () => void;
+    onError?: (message: string) => void;
+    style?: StyleProp<ViewStyle>;
+}
+export interface TalkingHeadRef {
+    sendAmplitude: (amplitude: number) => void;
+    setMood: (mood: TalkingHeadMood) => void;
+    setHairColor: (color: string) => void;
+    setSkinColor: (color: string) => void;
+    setEyeColor: (color: string) => void;
+    setAccessories: (accessories: TalkingHeadAccessory[]) => void;
+}
+export declare const TalkingHead: React.ForwardRefExoticComponent<TalkingHeadProps & React.RefAttributes<TalkingHeadRef>>;
+//# sourceMappingURL=TalkingHead.d.ts.map

package/dist/TalkingHead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TalkingHead.d.ts","sourceRoot":"","sources":["../src/TalkingHead.tsx"],"names":[],"mappings":"AAAA,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,KAAK,SAAS,EAAoB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAIhF,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,OAAO,GACP,KAAK,GACL,OAAO,GACP,SAAS,GACT,UAAU,GACV,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACzC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,cAAc,EAAE,CAAC,WAAW,EAAE,oBAAoB,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED,eAAO,MAAM,WAAW,yFAyIvB,CAAC"}

package/dist/TalkingHead.js

@@ -0,0 +1,107 @@
+import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useMemo, useRef, } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { WebView } from 'react-native-webview';
+import { buildAvatarHtml } from './html';
+export const TalkingHead = forwardRef(({ avatarUrl, authToken, mood = 'neutral', cameraView = 'upper', cameraDistance = -0.5, hairColor, skinColor, eyeColor, accessories, onReady, onError, style, }, ref) => {
+    const webViewRef = useRef(null);
+    const post = useCallback((msg) => {
+        webViewRef.current?.postMessage(JSON.stringify(msg));
+    }, []);
+    useImperativeHandle(ref, () => ({
+        sendAmplitude: (amplitude) => post({ type: 'amplitude', value: amplitude }),
+        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 }),
+    }), [post]);
+    useEffect(() => {
+        if (readyRef.current)
+            post({ type: 'mood', value: mood });
+    }, [mood, post]);
+    // Track whether the WebView JS is ready to receive messages
+    const readyRef = useRef(false);
+    // Always hold the latest accessories so the ready handler can send them
+    const accessoriesRef = useRef(accessories);
+    useEffect(() => {
+        accessoriesRef.current = accessories;
+    }, [accessories]);
+    useEffect(() => {
+        // Only post if the WebView is already ready; otherwise the ready handler sends them
+        if (accessories && readyRef.current) {
+            post({ type: 'set_accessories', accessories });
+        }
+    }, [accessories, post]);
+    useEffect(() => {
+        if (hairColor && readyRef.current)
+            post({ type: 'hair_color', value: hairColor });
+    }, [hairColor, post]);
+    useEffect(() => {
+        if (skinColor && readyRef.current)
+            post({ type: 'skin_color', value: skinColor });
+    }, [skinColor, post]);
+    useEffect(() => {
+        if (eyeColor && readyRef.current)
+            post({ type: 'eye_color', value: eyeColor });
+    }, [eyeColor, post]);
+    // Color props are intentionally excluded from deps — live updates go via postMessage.
+    // Only avatarUrl, authToken, cameraView, cameraDistance cause a full WebView reload.
+    const [initialMood] = React.useState(mood);
+    const [initialHairColor] = React.useState(hairColor);
+    const [initialSkinColor] = React.useState(skinColor);
+    const [initialEyeColor] = React.useState(eyeColor);
+    const html = useMemo(() => buildAvatarHtml({
+        avatarUrl,
+        authToken,
+        mood: initialMood,
+        cameraView,
+        cameraDistance,
+        initialHairColor: initialHairColor,
+        initialSkinColor: initialSkinColor,
+        initialEyeColor: initialEyeColor,
+    }), [
+        avatarUrl,
+        authToken,
+        cameraView,
+        cameraDistance,
+        initialMood,
+        initialHairColor,
+        initialSkinColor,
+        initialEyeColor,
+    ]);
+    const onMessage = useCallback((event) => {
+        try {
+            const msg = JSON.parse(event.nativeEvent.data);
+            if (msg.type === 'ready') {
+                readyRef.current = true;
+                // Flush any accessories that arrived before the WebView was ready
+                if (accessoriesRef.current?.length) {
+                    post({ type: 'set_accessories', accessories: accessoriesRef.current });
+                }
+                onReady?.();
+            }
+            else if (msg.type === 'error')
+                onError?.(msg.message);
+            else if (msg.type === 'log')
+                console.log('[TalkingHead]', msg.message);
+        }
+        catch (err) {
+            console.warn('[TalkingHead] Invalid message received from WebView:', err);
+        }
+    }, [onReady, onError, post]);
+    return (<View style={[styles.container, style]}>
+        <WebView ref={webViewRef} source={{ html }} style={styles.webview} javaScriptEnabled domStorageEnabled allowsInlineMediaPlayback mediaPlaybackRequiresUserAction={false} onMessage={onMessage} originWhitelist={['*']} mixedContentMode="always"/>
+      </View>);
+});
+TalkingHead.displayName = 'TalkingHead';
+const styles = StyleSheet.create({
+    container: {
+        overflow: 'hidden',
+        borderRadius: 12,
+        backgroundColor: 'transparent',
+    },
+    webview: {
+        flex: 1,
+        backgroundColor: 'transparent',
+    },
+});

package/dist/TalkingHead.web.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+export type TalkingHeadMood = 'neutral' | 'happy' | 'sad' | 'angry' | 'excited' | 'thinking' | 'concerned' | 'surprised';
+export interface TalkingHeadAccessory {
+    id: string;
+    url: string;
+    bone: string;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: number;
+}
+export interface TalkingHeadProps {
+    avatarUrl: string;
+    authToken?: string | null;
+    mood?: TalkingHeadMood;
+    cameraView?: 'head' | 'upper' | 'full';
+    cameraDistance?: number;
+    hairColor?: string;
+    skinColor?: string;
+    eyeColor?: string;
+    accessories?: TalkingHeadAccessory[];
+    onReady?: () => void;
+    onError?: (message: string) => void;
+    style?: StyleProp<ViewStyle>;
+}
+export interface TalkingHeadRef {
+    sendAmplitude: (amplitude: number) => void;
+    setMood: (mood: TalkingHeadMood) => void;
+    setHairColor: (color: string) => void;
+    setSkinColor: (color: string) => void;
+    setEyeColor: (color: string) => void;
+    setAccessories: (accessories: TalkingHeadAccessory[]) => void;
+}
+export declare const TalkingHead: React.ForwardRefExoticComponent<TalkingHeadProps & React.RefAttributes<TalkingHeadRef>>;
+//# sourceMappingURL=TalkingHead.web.d.ts.map

package/dist/TalkingHead.web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TalkingHead.web.d.ts","sourceRoot":"","sources":["../src/TalkingHead.web.tsx"],"names":[],"mappings":"AAAA,OAAO,KAON,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,KAAK,SAAS,EAAoB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAC;AAGhF,MAAM,MAAM,eAAe,GACvB,SAAS,GACT,OAAO,GACP,KAAK,GACL,OAAO,GACP,SAAS,GACT,UAAU,GACV,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,oBAAoB,EAAE,CAAC;IACrC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,OAAO,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAC;IACzC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC,cAAc,EAAE,CAAC,WAAW,EAAE,oBAAoB,EAAE,KAAK,IAAI,CAAC;CAC/D;AAED,eAAO,MAAM,WAAW,yFAiJvB,CAAC"}