talking-head-studio 0.4.11 → 0.4.12

package/dist/editor/boneSnap.web.d.ts

@@ -0,0 +1,27 @@
+import * as THREE from 'three';
+export declare const HUMANOID_BONES: readonly ["Hips", "Spine", "Spine1", "Spine2", "Neck", "Head", "LeftShoulder", "LeftArm", "LeftForeArm", "LeftHand", "RightShoulder", "RightArm", "RightForeArm", "RightHand", "LeftUpLeg", "LeftLeg", "LeftFoot", "LeftToeBase", "RightUpLeg", "RightLeg", "RightFoot", "RightToeBase"];
+export type HumanoidBone = (typeof HUMANOID_BONES)[number];
+export interface BoneSnapResult {
+    bone: string;
+    position: THREE.Vector3;
+    distance: number;
+}
+/**
+ * Given an avatar scene and a world-space position, finds the nearest skeleton
+ * bone whose name matches a known humanoid bone name.
+ */
+export declare function findNearestBone(avatarScene: THREE.Object3D, worldPos: THREE.Vector3, maxDistance?: number): BoneSnapResult | null;
+/**
+ * Returns the world-space position of a named bone in the avatar scene.
+ * Returns the scene origin if the bone is not found.
+ */
+export declare function getWorldPositionForBone(avatarScene: THREE.Object3D, boneName: string): THREE.Vector3;
+export declare const getWorldPositionForPlacement: typeof getWorldPositionForBone;
+/**
+ * Returns the nearest known humanoid bone to a placement point.
+ */
+export declare function snapPlacementToNearestBone(avatarScene: THREE.Object3D, worldPos: THREE.Vector3): BoneSnapResult | null;
+/**
+ * Web-safe snap hook. Native builds use the haptic version from boneSnap.ts.
+ */
+export declare function useBoneSnap(avatarScene: THREE.Object3D | null): (worldPos: THREE.Vector3) => BoneSnapResult | null;

package/dist/editor/boneSnap.web.js

@@ -0,0 +1,99 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWorldPositionForPlacement = exports.HUMANOID_BONES = void 0;
+exports.findNearestBone = findNearestBone;
+exports.getWorldPositionForBone = getWorldPositionForBone;
+exports.snapPlacementToNearestBone = snapPlacementToNearestBone;
+exports.useBoneSnap = useBoneSnap;
+const react_1 = require("react");
+const THREE = __importStar(require("three"));
+exports.HUMANOID_BONES = [
+    'Hips', 'Spine', 'Spine1', 'Spine2', 'Neck', 'Head',
+    'LeftShoulder', 'LeftArm', 'LeftForeArm', 'LeftHand',
+    'RightShoulder', 'RightArm', 'RightForeArm', 'RightHand',
+    'LeftUpLeg', 'LeftLeg', 'LeftFoot', 'LeftToeBase',
+    'RightUpLeg', 'RightLeg', 'RightFoot', 'RightToeBase',
+];
+/**
+ * Given an avatar scene and a world-space position, finds the nearest skeleton
+ * bone whose name matches a known humanoid bone name.
+ */
+function findNearestBone(avatarScene, worldPos, maxDistance = 0.35) {
+    let best = null;
+    const boneWorldPos = new THREE.Vector3();
+    avatarScene.traverse((obj) => {
+        if (!(obj instanceof THREE.Bone))
+            return;
+        if (!exports.HUMANOID_BONES.includes(obj.name))
+            return;
+        obj.getWorldPosition(boneWorldPos);
+        const dist = worldPos.distanceTo(boneWorldPos);
+        if (dist < maxDistance && (!best || dist < best.distance)) {
+            best = { bone: obj.name, position: boneWorldPos.clone(), distance: dist };
+        }
+    });
+    return best;
+}
+/**
+ * Returns the world-space position of a named bone in the avatar scene.
+ * Returns the scene origin if the bone is not found.
+ */
+function getWorldPositionForBone(avatarScene, boneName) {
+    const result = new THREE.Vector3();
+    avatarScene.traverse((obj) => {
+        if (obj instanceof THREE.Bone && obj.name === boneName) {
+            obj.getWorldPosition(result);
+        }
+    });
+    return result;
+}
+exports.getWorldPositionForPlacement = getWorldPositionForBone;
+/**
+ * Returns the nearest known humanoid bone to a placement point.
+ */
+function snapPlacementToNearestBone(avatarScene, worldPos) {
+    return findNearestBone(avatarScene, worldPos);
+}
+/**
+ * Web-safe snap hook. Native builds use the haptic version from boneSnap.ts.
+ */
+function useBoneSnap(avatarScene) {
+    return (0, react_1.useCallback)((worldPos) => {
+        if (!avatarScene)
+            return null;
+        return findNearestBone(avatarScene, worldPos);
+    }, [avatarScene]);
+}

package/dist/editor/index.web.d.ts

@@ -0,0 +1,10 @@
+export { AvatarCanvas } from './AvatarCanvas';
+export { AvatarEditor } from './AvatarEditor';
+export { AvatarModel } from './AvatarModel';
+export { RigidAccessory } from './RigidAccessory';
+export { SkinnedClothing } from './SkinnedClothing';
+export { FaceSqueezeEditor, FACE_SQUEEZE_LOCAL_MODULE } from './FaceSqueezeEditor.web';
+export { studioTheme, withAlpha } from './studioTheme';
+export { useBoneSnap, findNearestBone, getWorldPositionForBone, getWorldPositionForPlacement, snapPlacementToNearestBone, HUMANOID_BONES, } from './boneSnap.web';
+export type { AvatarEditorProps, AssetPlacement, EquippedAsset, FaceSqueezeEditorProps } from './types';
+export type { BoneSnapResult, HumanoidBone } from './boneSnap.web';

package/dist/editor/index.web.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUMANOID_BONES = exports.snapPlacementToNearestBone = exports.getWorldPositionForPlacement = exports.getWorldPositionForBone = exports.findNearestBone = exports.useBoneSnap = exports.withAlpha = exports.studioTheme = exports.FACE_SQUEEZE_LOCAL_MODULE = exports.FaceSqueezeEditor = exports.SkinnedClothing = exports.RigidAccessory = exports.AvatarModel = exports.AvatarEditor = exports.AvatarCanvas = void 0;
+var AvatarCanvas_1 = require("./AvatarCanvas");
+Object.defineProperty(exports, "AvatarCanvas", { enumerable: true, get: function () { return AvatarCanvas_1.AvatarCanvas; } });
+var AvatarEditor_1 = require("./AvatarEditor");
+Object.defineProperty(exports, "AvatarEditor", { enumerable: true, get: function () { return AvatarEditor_1.AvatarEditor; } });
+var AvatarModel_1 = require("./AvatarModel");
+Object.defineProperty(exports, "AvatarModel", { enumerable: true, get: function () { return AvatarModel_1.AvatarModel; } });
+var RigidAccessory_1 = require("./RigidAccessory");
+Object.defineProperty(exports, "RigidAccessory", { enumerable: true, get: function () { return RigidAccessory_1.RigidAccessory; } });
+var SkinnedClothing_1 = require("./SkinnedClothing");
+Object.defineProperty(exports, "SkinnedClothing", { enumerable: true, get: function () { return SkinnedClothing_1.SkinnedClothing; } });
+var FaceSqueezeEditor_web_1 = require("./FaceSqueezeEditor.web");
+Object.defineProperty(exports, "FaceSqueezeEditor", { enumerable: true, get: function () { return FaceSqueezeEditor_web_1.FaceSqueezeEditor; } });
+Object.defineProperty(exports, "FACE_SQUEEZE_LOCAL_MODULE", { enumerable: true, get: function () { return FaceSqueezeEditor_web_1.FACE_SQUEEZE_LOCAL_MODULE; } });
+var studioTheme_1 = require("./studioTheme");
+Object.defineProperty(exports, "studioTheme", { enumerable: true, get: function () { return studioTheme_1.studioTheme; } });
+Object.defineProperty(exports, "withAlpha", { enumerable: true, get: function () { return studioTheme_1.withAlpha; } });
+var boneSnap_web_1 = require("./boneSnap.web");
+Object.defineProperty(exports, "useBoneSnap", { enumerable: true, get: function () { return boneSnap_web_1.useBoneSnap; } });
+Object.defineProperty(exports, "findNearestBone", { enumerable: true, get: function () { return boneSnap_web_1.findNearestBone; } });
+Object.defineProperty(exports, "getWorldPositionForBone", { enumerable: true, get: function () { return boneSnap_web_1.getWorldPositionForBone; } });
+Object.defineProperty(exports, "getWorldPositionForPlacement", { enumerable: true, get: function () { return boneSnap_web_1.getWorldPositionForPlacement; } });
+Object.defineProperty(exports, "snapPlacementToNearestBone", { enumerable: true, get: function () { return boneSnap_web_1.snapPlacementToNearestBone; } });
+Object.defineProperty(exports, "HUMANOID_BONES", { enumerable: true, get: function () { return boneSnap_web_1.HUMANOID_BONES; } });

package/dist/editor/studioTheme.d.ts

@@ -1,20 +1,20 @@
 export declare const studioTheme: {
     readonly colors: {
-        readonly background: "#111315";
-        readonly backgroundAlt: "#191d20";
-        readonly surface: "#1c2125";
-        readonly surfaceRaised: "#252b30";
-        readonly surfaceSoft: "#2b3238";
-        readonly border: "#394249";
-        readonly borderStrong: "#53606a";
-        readonly textPrimary: "#f6efe4";
-        readonly textSecondary: "#cabfaa";
-        readonly textMuted: "#8b847a";
-        readonly accent: "#ff7a59";
-        readonly accentStrong: "#ff9c72";
-        readonly accentMuted: "rgba(255, 122, 89, 0.16)";
+        readonly background: "#0d1018";
+        readonly backgroundAlt: "#13151C";
+        readonly surface: "#1a1e29";
+        readonly surfaceRaised: "#222a3a";
+        readonly surfaceSoft: "#282B36";
+        readonly border: "#363b4a";
+        readonly borderStrong: "#424655";
+        readonly textPrimary: "#FAF7F0";
+        readonly textSecondary: "#C8CCD9";
+        readonly textMuted: "#6B7080";
+        readonly accent: "#4F5BD5";
+        readonly accentStrong: "#6673D6";
+        readonly accentMuted: "rgba(79, 91, 213, 0.16)";
         readonly success: "#69c08a";
-        readonly danger: "#f07a7a";
+        readonly danger: "#E85C48";
         readonly shadow: "rgba(0, 0, 0, 0.32)";
         readonly haze: "rgba(255, 255, 255, 0.05)";
     };

package/dist/editor/studioTheme.js

@@ -2,23 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.studioTheme = void 0;
 exports.withAlpha = withAlpha;
+// Self-contained theme. Palette is inspired by @sitebay/theme (slate dark
+// surfaces + indigo accent + parchment text) but intentionally NOT a hard
+// dependency — keeps this package standalone/publishable.
 exports.studioTheme = {
     colors: {
-        background: '#111315',
-        backgroundAlt: '#191d20',
-        surface: '#1c2125',
-        surfaceRaised: '#252b30',
-        surfaceSoft: '#2b3238',
-        border: '#394249',
-        borderStrong: '#53606a',
-        textPrimary: '#f6efe4',
-        textSecondary: '#cabfaa',
-        textMuted: '#8b847a',
-        accent: '#ff7a59',
-        accentStrong: '#ff9c72',
-        accentMuted: 'rgba(255, 122, 89, 0.16)',
+        background: '#0d1018',
+        backgroundAlt: '#13151C',
+        surface: '#1a1e29',
+        surfaceRaised: '#222a3a',
+        surfaceSoft: '#282B36',
+        border: '#363b4a',
+        borderStrong: '#424655',
+        textPrimary: '#FAF7F0',
+        textSecondary: '#C8CCD9',
+        textMuted: '#6B7080',
+        accent: '#4F5BD5',
+        accentStrong: '#6673D6',
+        accentMuted: 'rgba(79, 91, 213, 0.16)',
         success: '#69c08a',
-        danger: '#f07a7a',
+        danger: '#E85C48',
         shadow: 'rgba(0, 0, 0, 0.32)',
         haze: 'rgba(255, 255, 255, 0.05)',
     },

package/dist/editor/types.d.ts

@@ -41,4 +41,5 @@ export interface AvatarEditorProps {
 }
 export interface FaceSqueezeEditorProps {
     onClose: () => void;
+    avatarModule?: unknown;
 }

package/dist/html/accessories.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generated avatar WebView accessories script section.
+ *
+ * Kept as a string builder so html.ts can compose the final document without
+ * owning every browser-side subsystem inline.
+ */
+export declare function buildAccessoriesScript(): string;

package/dist/html/accessories.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAccessoriesScript = buildAccessoriesScript;
+/**
+ * Generated avatar WebView accessories script section.
+ *
+ * Kept as a string builder so html.ts can compose the final document without
+ * owning every browser-side subsystem inline.
+ */
+function buildAccessoriesScript() {
+    return `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);
+    }
+  }
+}
+
+`;
+}

package/dist/html/motion.d.ts

@@ -0,0 +1 @@
+export declare function buildMotionScript(): string;

package/dist/html/motion.js

@@ -0,0 +1,189 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMotionScript = buildMotionScript;
+/**
+ * Generated avatar WebView motion script section.
+ *
+ * Kept as a string builder so html.ts can compose the final document without
+ * owning every browser-side subsystem inline. The motion definitions and bone
+ * search map are serialized from the shared, framework-free source of truth in
+ * src/core/avatar/motion.ts so the WebView and the native WGPU path can never
+ * drift apart. The math below mirrors src/core/avatar/motionRuntime.ts.
+ */
+const motion_1 = require("../core/avatar/motion");
+function buildMotionScript() {
+    return `/* ── 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 };
+  },
+};
+
+/* Motion definitions + bone search map — serialized from the shared TS source
+   of truth (src/core/avatar/motion.ts) at build time. */
+const MOTION_DEFS = ${JSON.stringify(motion_1.MOTION_DEFS)};
+const BONE_SEARCH = ${JSON.stringify(motion_1.MOTION_BONE_SEARCH)};
+
+/* Runtime state */
+let motionActive = false;
+let motionKey = null;
+let motionStartTime = null;
+let motionBones = {};
+let motionRestQuats = {};
+let motionSmileTargets = [];
+let motionBeatTimer = null;
+let motionBeatIndex = 0;
+let motionAutoReturnTimer = null;
+
+/* Bone scan: norm() strips punctuation and lowercases, so RPM names like
+   LeftShoulder, RightArm, LeftForeArm etc. all match correctly. */
+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 false; }
+  const root = (head && head.armature) ? head.armature : staticModel;
+  if (!root) { log('MotionEngine: no model loaded'); return false; }
+
+  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');
+
+  /* Pose-like motions (attack/defend) auto-revert to rest so combat loops
+     return to guard without an explicit stop message. */
+  if (def.autoReturnMs > 0) {
+    motionAutoReturnTimer = setTimeout(function() {
+      if (motionKey === key) window.stopMotion(true);
+    }, def.autoReturnMs);
+  }
+  return true;
+};
+
+window.stopMotion = function(restore) {
+  if (restore === undefined) restore = true;
+  if (motionAutoReturnTimer) { clearTimeout(motionAutoReturnTimer); motionAutoReturnTimer = null; }
+  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);
+    motionKey = null;
+    log('MotionEngine: stopped');
+  }
+};
+/* ── End MotionEngine ─────────────────────────────────────── */
+
+`;
+}

package/dist/html/visemes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Generated avatar WebView visemes script section.
+ *
+ * Kept as a string builder so html.ts can compose the final document without
+ * owning every browser-side subsystem inline.
+ */
+export declare function buildVisemeScript(): string;