talking-head-studio 0.4.11 → 0.4.12

package/dist/html.js

@@ -1,11 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAvatarHtml = buildAvatarHtml;
+const accessories_1 = require("./html/accessories");
+const motion_1 = require("./html/motion");
+const visemes_1 = require("./html/visemes");
 const UPSTREAM_SAFE_MOOD_MAP = {
     neutral: 'neutral',
     happy: 'happy',
     sad: 'sad',
     angry: 'angry',
+    fear: 'fear',
+    disgust: 'disgust',
+    love: 'love',
+    sleep: 'sleep',
     excited: 'happy',
     thinking: 'neutral',
     concerned: 'sad',
@@ -13,6 +20,9 @@ const UPSTREAM_SAFE_MOOD_MAP = {
 };
 function buildAvatarHtml(config) {
     const safeMood = UPSTREAM_SAFE_MOOD_MAP[config.mood] ?? 'neutral';
+    const safeCameraDistance = Number.isFinite(config.cameraDistance)
+        ? config.cameraDistance
+        : -0.5;
     const v = config.vendorBaseUrl ? config.vendorBaseUrl.replace(/\/$/, '') : null;
     const threeUrl = v ? `${v}/three.module.js` : 'https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js';
     const threeAddonsUrl = v ? `${v}/three-addons/` : 'https://cdn.jsdelivr.net/npm/three@0.180.0/examples/jsm/';
@@ -82,7 +92,7 @@ const MOOD_MAP = ${JSON.stringify(UPSTREAM_SAFE_MOOD_MAP)};
 let AVATAR_URL = ${JSON.stringify(config.avatarUrl)};
 const INITIAL_MOOD = ${JSON.stringify(safeMood)};
 const CAMERA_VIEW = ${JSON.stringify(config.cameraView)};
-const CAMERA_DISTANCE = ${config.cameraDistance};
+const CAMERA_DISTANCE = ${JSON.stringify(safeCameraDistance)};
 let HAIR_COLOR = ${JSON.stringify(config.initialHairColor ?? null)};
 let SKIN_COLOR = ${JSON.stringify(config.initialSkinColor ?? null)};
 let EYE_COLOR = ${JSON.stringify(config.initialEyeColor ?? null)};
@@ -384,736 +394,19 @@ function startAudioInterception() {
   }).observe(document.body, { childList: true, subtree: true });
 }
 
-let amplitudeDecay = 0;
-let jawMorphCache = null;
-let visemeMorphCache = null;
-
-// Voice-driven mood detection
-let voiceEnergySmoothed = 0;
-let voiceMoodCurrent = 'neutral';
-let voiceMoodFramesAbove = 0;
-let voiceMoodFramesBelow = 0;
-const VOICE_ENERGY_EXCITED_THRESH = 0.45;
-const VOICE_ENERGY_NEUTRAL_THRESH = 0.15;
-const VOICE_MOOD_FRAMES_REQUIRED = 12; // ~0.2s at 60fps
-function updateVoiceMood(rawAmplitude) {
-  voiceEnergySmoothed = voiceEnergySmoothed * 0.85 + rawAmplitude * 0.15;
-  if (voiceEnergySmoothed > VOICE_ENERGY_EXCITED_THRESH) {
-    voiceMoodFramesAbove++;
-    voiceMoodFramesBelow = 0;
-    if (voiceMoodCurrent !== 'excited' && voiceMoodFramesAbove >= VOICE_MOOD_FRAMES_REQUIRED) {
-      voiceMoodCurrent = 'excited';
-      rnPost(JSON.stringify({ type: 'voiceMood', mood: 'excited' }));
-    }
-  } else if (voiceEnergySmoothed < VOICE_ENERGY_NEUTRAL_THRESH) {
-    voiceMoodFramesBelow++;
-    voiceMoodFramesAbove = 0;
-    if (voiceMoodCurrent !== 'neutral' && voiceMoodFramesBelow >= VOICE_MOOD_FRAMES_REQUIRED * 3) {
-      voiceMoodCurrent = 'neutral';
-      rnPost(JSON.stringify({ type: 'voiceMood', mood: 'neutral' }));
-    }
-  }
-}
-const visemeState = {};
-
-const VISEME_MORPH_ALIASES = {
-  sil: ['viseme_sil', 'sil', 'mouthClose', 'mouth_close'],
-  PP:  ['viseme_PP',  'pp',  'viseme_pp', 'mouthPucker', 'mouth_pucker'],
-  FF:  ['viseme_FF',  'ff',  'viseme_ff', 'mouthLowerLipIn', 'mouth_lower_lip_in', 'mouthRollLower', 'mouthShrugLower'],
-  TH:  ['viseme_TH',  'th',  'viseme_th', 'tongueOut', 'tongue_out'],
-  DD:  ['viseme_DD',  'dd',  'viseme_dd', 'mouthShrugUpper', 'mouth_shrug_upper'],
-  kk:  ['viseme_kk',  'kk',  'viseme_k',  'mouthStretchLeft', 'mouth_stretch_left'],
-  CH:  ['viseme_CH',  'ch',  'viseme_ch', 'mouthSmile', 'mouth_smile', 'mouthSmileLeft', 'mouth_smile_left'],
-  SS:  ['viseme_SS',  'ss',  'viseme_ss', 'mouthStretchRight', 'mouth_stretch_right'],
-  nn:  ['viseme_nn',  'nn',  'viseme_n',  'mouthDimpleLeft', 'mouth_dimple_left'],
-  RR:  ['viseme_RR',  'rr',  'viseme_r',  'mouthDimpleRight', 'mouth_dimple_right'],
-  aa:  ['viseme_aa',  'viseme_AA', 'aa', 'jawOpen', 'jaw_open', 'jawopen', 'mouthOpen', 'mouth_open', 'mouthopen'],
-  ee:  ['viseme_ee',  'viseme_E',  'ee', 'mouthSmileLeft', 'mouth_smile_left'],
-  ih:  ['viseme_ih',  'viseme_I',  'ih', 'mouthSmileRight', 'mouth_smile_right'],
-  oh:  ['viseme_oh',  'viseme_O',  'oh', 'mouthFunnel', 'mouth_funnel'],
-  ou:  ['viseme_ou',  'viseme_U',  'ou', 'mouthRollLower', 'mouth_roll_lower'],
-};
-
-// For ARKit models, each viseme may need multiple blend shapes driven together.
-// Each entry is a list of morph names to combine for that viseme.
-// The first alias list that has ANY match on the model is used.
-const VISEME_COMPOUND_ARKIT = {
-  aa:  [['jawOpen', 'mouthLowerDownLeft', 'mouthLowerDownRight'], ['jawOpen', 'mouthOpen']],
-  oh:  [['mouthFunnel', 'jawOpen'], ['mouthFunnel']],
-  ou:  [['mouthPucker', 'mouthRollLower'], ['mouthPucker']],
-  PP:  [['mouthPucker', 'mouthClose'], ['mouthPucker']],
-  FF:  [['mouthRollLower', 'mouthLowerDownLeft', 'mouthLowerDownRight'], ['mouthShrugLower']],
-  CH:  [['mouthSmileLeft', 'mouthSmileRight', 'mouthStretchLeft', 'mouthStretchRight'], ['mouthSmileLeft', 'mouthSmileRight']],
-  ee:  [['mouthSmileLeft', 'mouthSmileRight'], ['mouthSmileLeft']],
-  ih:  [['mouthSmileLeft', 'mouthSmileRight'], ['mouthSmileRight']],
-};
-
-function buildVisemeMorphCache() {
-  visemeMorphCache = {};
-  for (const [visemeKey, aliases] of Object.entries(VISEME_MORPH_ALIASES)) {
-    const entries = [];
-    // Check if we have a compound ARKit mapping for this viseme
-    const compoundOptions = VISEME_COMPOUND_ARKIT[visemeKey];
-    if (compoundOptions) {
-      // Try each compound option; use the first one where all names exist on at least one mesh
-      let usedCompound = false;
-      for (const nameList of compoundOptions) {
-        // Collect entries for all names across all meshes
-        const compoundEntries = [];
-        for (const mesh of mouthMeshes) {
-          if (!mesh.morphTargetDictionary) continue;
-          const dict = mesh.morphTargetDictionary;
-          const dictKeysLower = Object.fromEntries(Object.keys(dict).map(k => [k.toLowerCase(), k]));
-          for (const name of nameList) {
-            const found = dictKeysLower[name.toLowerCase()];
-            if (found !== undefined) {
-              compoundEntries.push({ influences: mesh.morphTargetInfluences, idx: dict[found], morphName: found });
-            }
-          }
-        }
-        if (compoundEntries.length > 0) {
-          entries.push(...compoundEntries);
-          usedCompound = true;
-          break;
-        }
-      }
-      if (usedCompound) {
-        visemeMorphCache[visemeKey] = entries;
-        continue;
-      }
-    }
-    // Fallback: single-alias lookup
-    for (const mesh of mouthMeshes) {
-      if (!mesh.morphTargetDictionary) continue;
-      const dictKeys = Object.keys(mesh.morphTargetDictionary);
-      for (const alias of aliases) {
-        const found = dictKeys.find(k => k.toLowerCase() === alias.toLowerCase());
-        if (found !== undefined) {
-          entries.push({ influences: mesh.morphTargetInfluences, idx: mesh.morphTargetDictionary[found], morphName: found });
-          break;
-        }
-      }
-    }
-    if (entries.length > 0) visemeMorphCache[visemeKey] = entries;
-  }
-  const found = Object.keys(visemeMorphCache);
-  log('Viseme cache: ' + (found.length > 0 ? found.join(', ') : 'none — check morph target names'));
-
-  // Always log all available morphs so we can see what the model actually has
-  if (mouthMeshes.length > 0) {
-    const allMorphs = Object.keys(mouthMeshes[0].morphTargetDictionary || {});
-    log('Available morphs: ' + (allMorphs.length > 0 ? allMorphs.join(', ') : 'none'));
-  }
-}
-
-function applyViseme(visemeKey, weight) {
-  if (!visemeMorphCache) buildVisemeMorphCache();
-  if (visemeKey === 'sil' || weight <= 0) {
-    for (const key of Object.keys(visemeState)) visemeState[key] = 0;
-    return;
-  }
-  visemeState[visemeKey] = Math.min(1, weight);
-  visemeStateLastSet.set(visemeKey, Date.now());
-}
-
-const RHUBARB_DEFAULT_VISEME_WEIGHT = 0.72;
-const RHUBARB_LABIAL_VISEME_WEIGHT = 0.85;
-const RHUBARB_AA_VISEME_WEIGHT = 0.72;
-const RHUBARB_ROUNDED_VISEME_WEIGHT = 0.62;
-const RHUBARB_FALLBACK_AMPLITUDE_CAP = 0.72;
-const RHUBARB_FALLBACK_AMPLITUDE_GAIN = 0.75;
-const RHUBARB_VISEME_WEIGHTS = {
-  PP: RHUBARB_LABIAL_VISEME_WEIGHT,
-  FF: 0.78,
-  ee: 0.72,
-  ih: 0.68,
-  oh: RHUBARB_ROUNDED_VISEME_WEIGHT,
-  ou: 0.58,
-  aa: RHUBARB_AA_VISEME_WEIGHT,
-};
-
-const RHUBARB_TO_VISEME = {
-  A: 'aa',
-  B: 'PP',
-  C: 'ih',
-  D: 'FF',
-  E: 'ee',
-  F: 'oh',
-  G: 'ou',
-  H: 'nn',
-  X: 'sil',
-};
-
-let rhubarbMorphCache = null;
-let visemeTimers = [];
-let activeVisemeScheduleId = 0;
-let visemeModeUntil = 0;
-const visemeStateLastSet = new Map();
-
-function buildRhubarbMorphCache() {
-  if (!visemeMorphCache) buildVisemeMorphCache();
-  rhubarbMorphCache = {};
-  for (const [rhubarbShape, visemeKey] of Object.entries(RHUBARB_TO_VISEME)) {
-    if (visemeKey === 'sil') { rhubarbMorphCache[rhubarbShape] = null; continue; }
-    rhubarbMorphCache[rhubarbShape] = visemeMorphCache[visemeKey] || null;
-  }
-  log('Rhubarb morph cache built');
-}
-
-function applyRhubarbCue(shape) {
-  if (!rhubarbMorphCache) buildRhubarbMorphCache();
-  // Zero all active viseme channels first
-  for (const key of Object.keys(visemeState)) visemeState[key] = 0;
-  if (shape === 'X' || !rhubarbMorphCache[shape]) return;
-  const visemeKey = RHUBARB_TO_VISEME[shape];
-  if (visemeKey && visemeKey !== 'sil') {
-    visemeState[visemeKey] = RHUBARB_VISEME_WEIGHTS[visemeKey] || RHUBARB_DEFAULT_VISEME_WEIGHT;
-    visemeStateLastSet.set(visemeKey, Date.now());
+${(0, visemes_1.buildVisemeScript)()}${(0, accessories_1.buildAccessoriesScript)()}${(0, motion_1.buildMotionScript)()}function dispatchProceduralMotion(name) {
+  const motionHandled = typeof window.playMotion === 'function'
+    ? window.playMotion(name)
+    : false;
+  if (motionHandled) {
+    rnPost(JSON.stringify({ type: 'avatarState', state: 'motion:' + name }));
+    log('motion dispatched: ' + name);
+  } else {
+    rnPost(JSON.stringify({ type: 'avatarState', state: 'motion_error:unknown:' + name }));
+    log('motion rejected: unknown key ' + name);
   }
 }
 
-function clearScheduledVisemes() {
-  activeVisemeScheduleId++;
-  for (const id of visemeTimers) clearTimeout(id);
-  visemeTimers = [];
-  visemeModeUntil = 0;
-  // Zero all mouth morphs
-  for (const key of Object.keys(visemeState)) visemeState[key] = 0;
-}
-
-function tickVisemeDecay(deltaSeconds) {
-  if (!visemeMorphCache) return;
-
-  const isScheduled = Date.now() < visemeModeUntil;
-  const hasSpecificLipShape =
-    visemeState.PP > 0.05 ||
-    visemeState.FF > 0.05 ||
-    visemeState.kk > 0.05 ||
-    visemeState.ee > 0.05 ||
-    visemeState.ih > 0.05;
-
-  for (const [key, weight] of Object.entries(visemeState)) {
-    // Only decay if we aren't in the middle of a viseme schedule.
-    // Scheduled visemes are cleared manually by timeouts.
-    if (!isScheduled) {
-      // Time-delta-aware decay: maintain consistent feel regardless of frame rate.
-      // Base rate is calibrated for 60 fps (0.82 per frame = ~12 frames to 10%).
-      // pow(0.82, delta*60) is frame-rate independent.
-      const dt = deltaSeconds ?? (1 / 60);
-      const decayFactor = Math.pow(0.82, dt * 60);
-      const decayed = weight * decayFactor;
-      visemeState[key] = decayed < 0.01 ? 0 : decayed;
-    }
-
-    const entries = visemeMorphCache[key];
-    if (!entries) continue;
-
-    let targetWeight = visemeState[key];
-    if (key === 'aa' && hasSpecificLipShape) targetWeight = Math.min(targetWeight, 0.45);
-
-    for (const e of entries) {
-      // When TalkingHead is active, write through its morph API so the internal
-      // render loop doesn't overwrite our values every frame.
-      // Use realtime (not newvalue) — newvalue is consumed and cleared after
-      // a single frame, so scheduled visemes would vanish immediately.
-      // realtime persists until explicitly set to null.
-      if (head && head.mtAvatar && e.morphName && head.mtAvatar[e.morphName]) {
-        const mt = head.mtAvatar[e.morphName];
-        mt.realtime = targetWeight > 0 ? targetWeight : null;
-        mt.needsUpdate = true;
-      } else {
-        e.influences[e.idx] = targetWeight;
-      }
-    }
-  }
-}
-
-function scheduleVisemes(schedule) {
-  clearScheduledVisemes();
-
-  // Prune visemeState keys that haven't been written in the last 2 seconds to
-  // prevent unbounded accumulation across many utterances.
-  const staleThreshold = Date.now() - 2000;
-  for (const key of Object.keys(visemeState)) {
-    if ((visemeStateLastSet.get(key) ?? 0) < staleThreshold) {
-      delete visemeState[key];
-      visemeStateLastSet.delete(key);
-    }
-  }
-
-  if (!schedule || !Array.isArray(schedule.cues) || schedule.cues.length === 0) return;
-
-  const myScheduleId = activeVisemeScheduleId;
-  // Anchor selection priority:
-  //   1. audioStartedAtMs — stamped when audio actually begins playing (most accurate)
-  //   2. startedAtMs + pipeline delay — stamped at TTS request fire time
-  //
-  // AUDIO_PIPELINE_DELAY_MS compensates for the gap between "TTS request fired"
-  // and "audio audible from speaker". Qwen3-TTS on local/tailnet is ~80–150 ms;
-  // LiveKit adds ~50–80 ms of jitter buffer on top. 150 ms is conservative but
-  // avoids the mouth running ahead of audio on fast connections.
-  const AUDIO_PIPELINE_DELAY_MS = 50;
-  let startedAt = schedule.audioStartedAtMs
-    ?? ((schedule.startedAtMs || Date.now()) + AUDIO_PIPELINE_DELAY_MS);
-  const durationMs = schedule.durationMs || 0;
-  const now = Date.now();
-  let elapsedMs = Math.max(0, now - startedAt);
-
-  // If the schedule still arrives late after the pipeline offset, shift further
-  if (elapsedMs > 300 && schedule.cues.length > 3) {
-    const shift = Math.min(elapsedMs - 50, 500);
-    startedAt += shift;
-    elapsedMs -= shift;
-    log('Viseme schedule arrived late, shifting anchor forward by ' + shift + 'ms');
-  }
-
-  const remainingMs = Math.max(0, durationMs - elapsedMs);
-  let scheduledCueCount = 0;
-  let skippedCueCount = 0;
-
-  // Gate amplitude fallback for the locally remaining duration plus a small buffer.
-  // If the schedule arrives a bit late, keep amplitude out of the way for the rest
-  // of the utterance instead of expiring immediately from the original timestamp.
-  visemeModeUntil = now + remainingMs + 200;
-
-  for (const cue of schedule.cues) {
-    const delay = cue.startMs - (Date.now() - startedAt);
-    if (delay < -50) {
-      skippedCueCount++;
-      continue; // already in the past, skip
-    }
-    scheduledCueCount++;
-
-    const applyId = setTimeout(() => {
-      if (activeVisemeScheduleId !== myScheduleId) return;
-      applyRhubarbCue(cue.viseme);
-    }, Math.max(0, delay));
-
-    const clearId = setTimeout(() => {
-      if (activeVisemeScheduleId !== myScheduleId) return;
-      // Only clear if the next cue hasn't already overwritten state
-      visemeState[RHUBARB_TO_VISEME[cue.viseme]] = 0;
-    }, Math.max(0, delay + (cue.endMs - cue.startMs)));
-
-    visemeTimers.push(applyId, clearId);
-  }
-
-  log(
-    'Viseme schedule received: requestId=' +
-      (schedule.requestId || 'unknown') +
-      ' cues=' + schedule.cues.length +
-      ' scheduled=' + scheduledCueCount +
-      ' skipped=' + skippedCueCount +
-      ' elapsedMs=' + elapsedMs +
-      ' remainingMs=' + remainingMs,
-  );
-
-  // Ensure silence at schedule end
-  const endDelay = durationMs - (Date.now() - startedAt);
-  if (endDelay > 0) {
-    visemeTimers.push(setTimeout(() => {
-      if (activeVisemeScheduleId !== myScheduleId) return;
-      for (const key of Object.keys(visemeState)) visemeState[key] = 0;
-      visemeModeUntil = 0;
-    }, endDelay + 100));
-  }
-}
-// ============ END RHUBARB VISEME SCHEDULER ============
-
-let THREE_REF = null;
-let gltfLoaderInstance = null;
-const currentAccessories = {};
-let pendingAccessoriesList = [];
-
-function disposeHierarchy(node) {
-  if (!node) return;
-  node.traverse((child) => {
-    if (child.isMesh) {
-      if (child.geometry) child.geometry.dispose();
-      if (child.material) {
-        const materials = Array.isArray(child.material) ? child.material : [child.material];
-        materials.forEach(mat => {
-          if (mat.map) mat.map.dispose();
-          if (mat.lightMap) mat.lightMap.dispose();
-          if (mat.bumpMap) mat.bumpMap.dispose();
-          if (mat.normalMap) mat.normalMap.dispose();
-          if (mat.specularMap) mat.specularMap.dispose();
-          if (mat.envMap) mat.envMap.dispose();
-          mat.dispose();
-        });
-      }
-    }
-  });
-}
-
-async function ensureThree() {
-  if (!THREE_REF) {
-    THREE_REF = await import('three');
-    const { GLTFLoader } = await import('three/addons/loaders/GLTFLoader.js');
-    const { DRACOLoader } = await import('three/addons/loaders/DRACOLoader.js');
-    gltfLoaderInstance = new GLTFLoader();
-    const dracoLoader = new DRACOLoader();
-    dracoLoader.setDecoderPath(DRACO_URL);
-    gltfLoaderInstance.setDRACOLoader(dracoLoader);
-  }
-}
-
-async function applyAccessories(accessoriesList) {
-  log('[ACC] applyAccessories called with ' + accessoriesList.length + ' items');
-  pendingAccessoriesList = accessoriesList;
-  await ensureThree();
-  const root = (head && head.armature) ? head.armature : staticModel;
-  log('[ACC] root=' + (root ? root.constructor.name + '/' + root.name : 'NULL') + ' head=' + !!head + ' head.armature=' + !!(head && head.armature) + ' staticModel=' + !!staticModel);
-  if (!root) { log('[ACC] ABORT: no root'); return; }
-
-  const boneNames = [];
-  root.traverse((child) => { if (child.isBone) boneNames.push(child.name); });
-  log('[ACC] Bones found: ' + boneNames.join(', '));
-
-  const newAccessoryIds = new Set(accessoriesList.map(a => a.id));
-  for (const id in currentAccessories) {
-    if (!newAccessoryIds.has(id)) {
-      const acc = currentAccessories[id];
-      if (acc.model) {
-        if (acc.model.parent) acc.model.parent.remove(acc.model);
-        disposeHierarchy(acc.model);
-      }
-      delete currentAccessories[id];
-      log('[ACC] Removed old accessory: ' + id);
-    }
-  }
-
-  for (const accData of accessoriesList) {
-    log('[ACC] Processing: id=' + accData.id + ' url=' + accData.url + ' bone=' + accData.bone);
-    const existing = currentAccessories[accData.id];
-
-    if (!existing || existing.url !== accData.url) {
-      if (existing && existing.model) {
-        if (existing.model.parent) existing.model.parent.remove(existing.model);
-        disposeHierarchy(existing.model);
-      }
-      currentAccessories[accData.id] = { ...accData, model: null, isLoading: true, latestData: accData };
-      log('[ACC] Starting GLB load: ' + accData.url);
-      (async () => {
-        try {
-          const loadedUrl = await loadWithAuth(accData.url);
-          gltfLoaderInstance.load(loadedUrl, (gltf) => {
-            if (loadedUrl.startsWith('blob:')) URL.revokeObjectURL(loadedUrl);
-            log('[ACC] GLB loaded OK for ' + accData.id);
-            const model = gltf.scene;
-            const latestData = (currentAccessories[accData.id] && currentAccessories[accData.id].latestData) || accData;
-            let targetBone = null;
-            let prefixCandidate = null;
-            root.traverse((child) => {
-              if (child.isBone && child.name === latestData.bone) targetBone = child;
-              else if (!prefixCandidate && child.name.replace(/_\\d+$/, '') === latestData.bone) prefixCandidate = child;
-            });
-            if (!targetBone && prefixCandidate) {
-              targetBone = prefixCandidate;
-              log('[ACC] Prefix match bone: ' + targetBone.name);
-            }
-            model.traverse((child) => { if (child.isMesh) child.frustumCulled = false; });
-            if (!targetBone) { log('[ACC] Bone not found: ' + latestData.bone + '. Using root.'); targetBone = root; }
-            else log('[ACC] Found bone: ' + targetBone.name);
-            const modelScale = latestData.scale !== undefined ? latestData.scale : 1.0;
-            model.scale.set(modelScale, modelScale, modelScale);
-            model.position.set(
-              latestData.position ? latestData.position[0] : 0,
-              latestData.position ? latestData.position[1] : 0,
-              latestData.position ? latestData.position[2] : 0
-            );
-            if (latestData.rotation) model.rotation.set(...latestData.rotation);
-            if (!currentAccessories[accData.id] || currentAccessories[accData.id].url !== accData.url) {
-              log('[ACC] Aborting: ' + accData.id + ' changed while loading.');
-              return;
-            }
-            targetBone.add(model);
-            log('[ACC] Attached to ' + targetBone.name);
-            currentAccessories[accData.id].model = model;
-            currentAccessories[accData.id].isLoading = false;
-          }, () => {}, (err) => {
-            if (loadedUrl.startsWith('blob:')) URL.revokeObjectURL(loadedUrl);
-            log('[ACC] FAILED: ' + accData.id + ': ' + err.message);
-            if (currentAccessories[accData.id]) currentAccessories[accData.id].isLoading = false;
-          });
-        } catch (authErr) {
-          log('[ACC] Auth fetch failed ' + accData.id + ': ' + authErr.message);
-          if (currentAccessories[accData.id]) currentAccessories[accData.id].isLoading = false;
-        }
-      })();
-    } else if (existing && existing.isLoading) {
-      existing.latestData = accData;
-    } else if (existing && existing.model) {
-      const model = existing.model;
-      const accScale = accData.scale !== undefined ? accData.scale : 1.0;
-      model.scale.set(accScale, accScale, accScale);
-      model.position.set(
-        accData.position ? accData.position[0] : 0,
-        accData.position ? accData.position[1] : 0,
-        accData.position ? accData.position[2] : 0
-      );
-      if (accData.rotation) model.rotation.set(...accData.rotation);
-    }
-  }
-}
-
-/* ── MotionEngine ────────────────────────────────────────────────────────── */
-/* Quaternion math helpers (no Three.js dep required) */
-const QM = {
-  fromAxisAngle(ax, ay, az, angle) {
-    const s = Math.sin(angle / 2);
-    return { x: ax*s, y: ay*s, z: az*s, w: Math.cos(angle/2) };
-  },
-  multiply(a, b) {
-    return {
-      x:  a.w*b.x + a.x*b.w + a.y*b.z - a.z*b.y,
-      y:  a.w*b.y - a.x*b.z + a.y*b.w + a.z*b.x,
-      z:  a.w*b.z + a.x*b.y - a.y*b.x + a.z*b.w,
-      w:  a.w*b.w - a.x*b.x - a.y*b.y - a.z*b.z,
-    };
-  },
-  applyTo(bone, q) {
-    bone.quaternion.set(q.x, q.y, q.z, q.w);
-  },
-  copyFrom(bone) {
-    const q = bone.quaternion;
-    return { x: q.x, y: q.y, z: q.z, w: q.w };
-  },
-};
-
-const MOTION_DEFS = {
-  groove: {
-    bpm: 120,
-    smile: 0.55,
-    label: 'Groove',
-    bones: {
-      hips:      [{ ax:0, ay:0, az:1, amp:0.10, freq:1.0, phase:0       },
-                  { ax:0, ay:1, az:0, amp:0.05, freq:0.5, phase:0       }],
-      spine:     [{ ax:0, ay:0, az:1, amp:0.08, freq:1.0, phase:0.3     },
-                  { ax:1, ay:0, az:0, amp:0.03, freq:2.0, phase:0       }],
-      spine2:    [{ ax:0, ay:0, az:1, amp:0.06, freq:1.0, phase:0.6     }],
-      neck:      [{ ax:0, ay:0, az:1, amp:0.05, freq:1.0, phase:Math.PI }],
-      head:      [{ ax:1, ay:0, az:0, amp:0.06, freq:2.0, phase:0       },
-                  { ax:0, ay:0, az:1, amp:0.04, freq:1.0, phase:Math.PI }],
-      leftArm:   [{ ax:0, ay:0, az:1, amp:0.22, freq:1.0, phase:Math.PI/2  }],
-      rightArm:  [{ ax:0, ay:0, az:1, amp:0.22, freq:1.0, phase:-Math.PI/2 }],
-    },
-  },
-  wave: {
-    bpm: 90,
-    smile: 0.75,
-    label: 'Wave',
-    bones: {
-      hips:      [{ ax:0, ay:0, az:1, amp:0.04, freq:0.5, phase:0 }],
-      spine:     [{ ax:0, ay:0, az:1, amp:0.04, freq:0.5, phase:0.2 }],
-      head:      [{ ax:0, ay:1, az:0, amp:0.12, freq:0.5, phase:0   },
-                  { ax:0, ay:0, az:1, amp:0.04, freq:0.5, phase:0.5 }],
-      rightShoulder:[{ ax:0, ay:0, az:1, amp:-0.6, freq:0,   phase:0 }],
-      rightArm:  [{ ax:0, ay:0, az:1, amp:-0.55, freq:0,  phase:0 },
-                  { ax:1, ay:0, az:0, amp:0.35,  freq:1.5, phase:0 }],
-      rightForeArm:[{ ax:1, ay:0, az:0, amp:0.4, freq:1.5, phase:Math.PI/3 }],
-    },
-  },
-  nod: {
-    bpm: 100,
-    smile: 0.4,
-    label: 'Head Bop',
-    bones: {
-      hips:   [{ ax:0, ay:0, az:1, amp:0.04, freq:0.83, phase:0 }],
-      spine:  [{ ax:1, ay:0, az:0, amp:0.04, freq:0.83, phase:0.2 },
-               { ax:0, ay:0, az:1, amp:0.03, freq:0.83, phase:0.4 }],
-      neck:   [{ ax:1, ay:0, az:0, amp:0.12, freq:1.67, phase:0 }],
-      head:   [{ ax:1, ay:0, az:0, amp:0.16, freq:1.67, phase:Math.PI/6 },
-               { ax:0, ay:1, az:0, amp:0.05, freq:0.83, phase:0 }],
-      leftArm:[{ ax:0, ay:0, az:1, amp:0.12, freq:0.83, phase:0 }],
-      rightArm:[{ ax:0, ay:0, az:1, amp:0.12, freq:0.83, phase:Math.PI }],
-    },
-  },
-  idle: {
-    bpm: 60,
-    smile: 0.15,
-    label: 'Idle Sway',
-    bones: {
-      hips:   [{ ax:0, ay:0, az:1, amp:0.035, freq:0.5, phase:0 }],
-      spine:  [{ ax:0, ay:0, az:1, amp:0.028, freq:0.5, phase:0.3 },
-               { ax:1, ay:0, az:0, amp:0.012, freq:0.25, phase:0 }],
-      spine2: [{ ax:0, ay:0, az:1, amp:0.018, freq:0.5, phase:0.5 }],
-      head:   [{ ax:1, ay:0, az:0, amp:0.025, freq:0.25, phase:0  },
-               { ax:0, ay:1, az:0, amp:0.015, freq:0.5,  phase:0.8}],
-    },
-  },
-  celebrate: {
-    bpm: 140,
-    smile: 0.95,
-    label: 'Celebrate',
-    bones: {
-      hips:    [{ ax:0, ay:0, az:1, amp:0.14, freq:1.17, phase:0       },
-                { ax:1, ay:0, az:0, amp:0.06, freq:2.33, phase:0       }],
-      spine:   [{ ax:0, ay:0, az:1, amp:0.10, freq:1.17, phase:0.4     },
-                { ax:1, ay:0, az:0, amp:0.05, freq:2.33, phase:0.2     }],
-      spine2:  [{ ax:0, ay:0, az:1, amp:0.07, freq:1.17, phase:0.7     }],
-      neck:    [{ ax:1, ay:0, az:0, amp:0.06, freq:2.33, phase:0       }],
-      head:    [{ ax:1, ay:0, az:0, amp:0.10, freq:2.33, phase:0.15    },
-                { ax:0, ay:0, az:1, amp:0.06, freq:1.17, phase:Math.PI }],
-      leftShoulder: [{ ax:0, ay:0, az:1, amp: 0.5, freq:0, phase:0    }],
-      rightShoulder:[{ ax:0, ay:0, az:1, amp:-0.5, freq:0, phase:0    }],
-      leftArm: [{ ax:0, ay:0, az:1, amp: 0.55, freq:0,    phase:0     },
-                { ax:1, ay:0, az:0, amp:0.30,  freq:2.33, phase:0     }],
-      rightArm:[{ ax:0, ay:0, az:1, amp:-0.55, freq:0,    phase:0     },
-                { ax:1, ay:0, az:0, amp:0.30,  freq:2.33, phase:Math.PI }],
-      leftForeArm: [{ ax:1, ay:0, az:0, amp:0.25, freq:2.33, phase:0.4 }],
-      rightForeArm:[{ ax:1, ay:0, az:0, amp:0.25, freq:2.33, phase:0.4 }],
-    },
-  },
-};
-
-/* Runtime state */
-let motionActive = false;
-let motionKey = null;
-let motionStartTime = null;
-let motionBones = {};
-let motionRestQuats = {};
-let motionSmileTargets = [];
-let motionBeatTimer = null;
-let motionBeatIndex = 0;
-
-/* Bone name map: logical key -> keywords to match in armature.
-   norm() strips punctuation and lowercases, so RPM names like
-   LeftShoulder, RightArm, LeftForeArm etc. all match correctly. */
-const BONE_SEARCH = {
-  hips:          ['hips','pelvis','hip','root'],
-  spine:         ['spine','spine0','spine_0','spine_01','spine1_'],
-  spine2:        ['spine2','spine_02','upperchest','chest','spine1'],
-  neck:          ['neck'],
-  head:          ['head'],
-  leftShoulder:  ['leftshoulder','l_shoulder','shoulderleft','leftclavicle','l_clavicle'],
-  rightShoulder: ['rightshoulder','r_shoulder','shoulderright','rightclavicle','r_clavicle'],
-  leftArm:       ['leftarm','l_arm','armleft','leftupperarm','l_upperarm'],
-  rightArm:      ['rightarm','r_arm','armright','rightupperarm','r_upperarm'],
-  leftForeArm:   ['leftforearm','l_forearm','forearmleft','leftlowerarm'],
-  rightForeArm:  ['rightforearm','r_forearm','forearmright','rightlowerarm'],
-};
-
-function motionScanBones(root) {
-  motionBones = {}; motionRestQuats = {};
-  if (!root) return;
-  const norm = s => s.toLowerCase().replace(/[_\\s\\-\\.]/g, '');
-  root.traverse(child => {
-    if (!child.isBone) return;
-    const lk = norm(child.name);
-    for (const [key, kws] of Object.entries(BONE_SEARCH)) {
-      if (motionBones[key]) continue;
-      if (kws.some(kw => lk.includes(norm(kw)))) {
-        motionBones[key] = child;
-        motionRestQuats[key] = QM.copyFrom(child);
-      }
-    }
-  });
-  const found = Object.keys(motionBones);
-  log('MotionEngine: ' + (found.length === 0
-    ? 'No rigged bones detected — motion engine needs a humanoid skeleton.'
-    : found.length + ' bones mapped: ' + found.join(', ') + '.'));
-}
-
-function motionScanSmile(root) {
-  motionSmileTargets = [];
-  if (!root) return;
-  root.traverse(child => {
-    if (!child.isMesh || !child.morphTargetDictionary) return;
-    Object.keys(child.morphTargetDictionary).forEach(name => {
-      const lk = name.toLowerCase();
-      if (lk.includes('smile') || lk.includes('happy') || lk.includes('joy') || lk.includes('mouthsmile')) {
-        motionSmileTargets.push({ mesh: child, index: child.morphTargetDictionary[name] });
-      }
-    });
-  });
-}
-
-function motionInitFromRoot(root) {
-  motionScanBones(root);
-  motionScanSmile(root);
-}
-
-function motionSetSmile(v) {
-  motionSmileTargets.forEach(t => { t.mesh.morphTargetInfluences[t.index] = v; });
-}
-
-/* BPM beat indicator — no-ops in WebView (no beat UI) */
-function motionStartBeat(bpm) {
-  clearInterval(motionBeatTimer);
-  motionBeatIndex = 0;
-  /* beat UI elements not present in WebView — intentional no-op */
-}
-
-function motionStopBeat() {
-  clearInterval(motionBeatTimer);
-  motionBeatTimer = null;
-}
-
-/* ── applyMotionBones ────────────────────────────────────────
-   Called every frame from inside the render loop
-   (fallback: before renderer.render; TH: inside head.opt.update).
-   Runs AFTER TH has written its own bones so our values are
-   the last thing written before the draw call.
- ─────────────────────────────────────────────────────────── */
-function applyMotionBones() {
-  if (!motionActive) return;
-  const def = MOTION_DEFS[motionKey];
-  if (!def) return;
-  const tSec = (performance.now() - motionStartTime) / 1000;
-
-  for (const [boneName, oscillators] of Object.entries(def.bones)) {
-    const bone = motionBones[boneName];
-    if (!bone) continue;
-    const rest = motionRestQuats[boneName];
-    let q = { ...rest };
-
-    for (const osc of oscillators) {
-      const angle = osc.freq === 0
-        ? osc.amp
-        : osc.amp * Math.sin(2 * Math.PI * osc.freq * tSec + osc.phase);
-      q = QM.multiply(q, QM.fromAxisAngle(osc.ax, osc.ay, osc.az, angle));
-    }
-
-    bone.quaternion.set(q.x, q.y, q.z, q.w);
-  }
-}
-
-window.playMotion = function(key) {
-  const def = MOTION_DEFS[key];
-  if (!def) { log('MotionEngine: unknown motion key: ' + key); return; }
-  const root = (head && head.armature) ? head.armature : staticModel;
-  if (!root) { log('MotionEngine: no model loaded'); return; }
-
-  if (Object.keys(motionBones).length === 0) motionInitFromRoot(root);
-
-  window.stopMotion(false);
-
-  motionKey = key;
-  motionActive = true;
-  motionStartTime = performance.now();
-
-  motionStartBeat(def.bpm);
-  motionSetSmile(def.smile);
-  log('MotionEngine: playing ' + def.label + ' @ ' + def.bpm + ' BPM');
-};
-
-window.stopMotion = function(restore) {
-  if (restore === undefined) restore = true;
-  motionActive = false;
-  motionStopBeat();
-
-  if (restore) {
-    for (const [key, bone] of Object.entries(motionBones)) {
-      const rest = motionRestQuats[key];
-      if (rest) bone.quaternion.set(rest.x, rest.y, rest.z, rest.w);
-    }
-    motionSetSmile(0);
-    log('MotionEngine: stopped');
-  }
-};
-/* ── End MotionEngine ─────────────────────────────────────── */
-
 function onIncomingMessage(event) {
   try {
     const msg = JSON.parse(event.data);
@@ -1158,11 +451,41 @@ function onIncomingMessage(event) {
     } else if (msg.type === 'set_accessories') {
       applyAccessories(msg.accessories || []);
     } else if (msg.type === 'motion' && typeof msg.name === 'string') {
-      if (typeof window.playMotion === 'function') {
-        window.playMotion(msg.name);
+      dispatchProceduralMotion(msg.name);
+    } else if (msg.type === 'stop_motion') {
+      if (typeof window.stopMotion === 'function') window.stopMotion();
+    } else if (msg.type === 'gesture' && typeof msg.name === 'string') {
+      if (head && typeof head.playGesture === 'function') {
+        // TalkingHead@1.7 playGesture(name, dur, mirror, ms) positional contract.
+        head.playGesture(msg.name, msg.dur ?? 3, msg.mirror ?? false, msg.ms ?? 1000);
+      } else {
+        dispatchProceduralMotion(msg.name);
+      }
+    } else if (msg.type === 'stop_gesture') {
+      if (head && typeof head.stopGesture === 'function') {
+        head.stopGesture(msg.ms ?? 1000);
+      } else if (typeof window.stopMotion === 'function') {
+        window.stopMotion();
+      }
+    } else if (msg.type === 'pose' && typeof msg.url === 'string') {
+      if (head && typeof head.playPose === 'function') {
+        // url may be a built-in template name (e.g. 'oneknee') or a pose file URL.
+        head.playPose(msg.url, null, msg.dur ?? 5);
+      } else {
+        dispatchProceduralMotion(msg.url);
+      }
+    } else if (msg.type === 'stop_pose') {
+      if (head && typeof head.stopPose === 'function') {
+        head.stopPose();
+      } else if (typeof window.stopMotion === 'function') {
+        window.stopMotion();
       }
-      rnPost(JSON.stringify({ type: 'avatarState', state: 'motion:' + msg.name }));
-      log('motion dispatched: ' + msg.name);
+    } else if (msg.type === 'animation' && head && typeof head.playAnimation === 'function') {
+      head.playAnimation(msg.url, null, msg.dur ?? 10, msg.index ?? 0);
+    } else if (msg.type === 'stop_animation' && head && typeof head.stopAnimation === 'function') {
+      head.stopAnimation();
+    } else if (msg.type === 'look_at' && head && typeof head.lookAt === 'function') {
+      head.lookAt(msg.x, msg.y, msg.ms ?? 500);
     }
   } catch (err) {
     log('Message parse error: ' + err);