talking-head-studio 0.4.11 → 0.4.12

package/dist/core/avatar/motion.js

@@ -0,0 +1,550 @@
+"use strict";
+/**
+ * Shared, framework-free motion engine data + math.
+ *
+ * This is the single source of truth for procedural body motions (groove,
+ * wave, attack, defend, …). It is consumed two ways:
+ *   1. The WebView avatar serializes MOTION_DEFS into the generated HTML
+ *      (see src/html/motion.ts) and runs the math inside the render loop.
+ *   2. The native WebGPU avatar (src/wgpu/WgpuAvatar.tsx) imports it directly
+ *      and drives bones from inside an R3F useFrame callback.
+ *
+ * Keep this module dependency-free (no three.js, no React) so both runtimes
+ * can share it. The quaternion helpers below are intentionally minimal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TALKINGHEAD_POSES = exports.TALKINGHEAD_GESTURES = exports.MOTION_KEYS = exports.MOTION_DEFS = exports.MOTION_BONE_SEARCH = void 0;
+exports.isMotionKey = isMotionKey;
+/**
+ * Bone name map: logical key -> keywords to match in an armature.
+ * Matching normalizes by lowercasing and stripping punctuation, so RPM names
+ * like LeftShoulder, RightArm, LeftForeArm all match correctly.
+ */
+exports.MOTION_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'],
+};
+exports.MOTION_DEFS = {
+    groove: {
+        bpm: 120,
+        smile: 0.55,
+        label: 'Groove',
+        bones: {
+            hips: [
+                { ax: 0, ay: 0, az: 1, amp: 0.1, 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 },
+            ],
+        },
+    },
+    attack: {
+        bpm: 160,
+        smile: 0.0,
+        label: 'Attack',
+        // Hold the lunge briefly, then return to guard so combat loops chain.
+        autoReturnMs: 450,
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: 0.2, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.25, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.15, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.14, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.65, freq: 0, phase: 0 }],
+            rightArm: [
+                { ax: 1, ay: 0, az: 0, amp: 0.85, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: -0.35, freq: 0, phase: 0 },
+            ],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.55, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.3, freq: 0, phase: 0 }],
+        },
+    },
+    defend: {
+        bpm: 80,
+        smile: 0.0,
+        label: 'Defend',
+        // A guard is a held stance; longer hold than attack but still auto-returns
+        // so the avatar relaxes if the engine forgets to clear it.
+        autoReturnMs: 1200,
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.1, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: -0.12, freq: 0, phase: 0 }],
+            head: [
+                { ax: 1, ay: 0, az: 0, amp: -0.06, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: 0.04, freq: 0, phase: 0 },
+            ],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.55, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.55, freq: 0, phase: 0 }],
+            leftArm: [
+                { ax: 1, ay: 0, az: 0, amp: 0.6, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: 0.4, freq: 0, phase: 0 },
+            ],
+            rightArm: [
+                { ax: 1, ay: 0, az: 0, amp: 0.6, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: -0.4, freq: 0, phase: 0 },
+            ],
+            leftForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.35, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.35, freq: 0, phase: 0 }],
+        },
+    },
+    cast: {
+        bpm: 120,
+        smile: 0.25,
+        label: 'Cast',
+        autoReturnMs: 700,
+        bones: {
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.08, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.04, freq: 0, phase: 0 }],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.34, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.34, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: 0.52, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.52, freq: 0, phase: 0 }],
+        },
+    },
+    hurt: {
+        bpm: 90,
+        smile: 0,
+        label: 'Hurt',
+        autoReturnMs: 520,
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.12, freq: 0, phase: 0 }],
+            spine: [
+                { ax: 1, ay: 0, az: 0, amp: -0.18, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: 0.08, freq: 0, phase: 0 },
+            ],
+            head: [
+                { ax: 1, ay: 0, az: 0, amp: -0.12, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: -0.08, freq: 0, phase: 0 },
+            ],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.2, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.2, freq: 0, phase: 0 }],
+        },
+    },
+    die: {
+        bpm: 40,
+        smile: 0,
+        label: 'Die',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.5, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.45, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.25, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.22, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.35, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.35, freq: 0, phase: 0 }],
+        },
+    },
+    windup: {
+        bpm: 110,
+        smile: 0.05,
+        label: 'Windup',
+        autoReturnMs: 800,
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.08, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: -0.18, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.08, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.62, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.9, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.4, freq: 0, phase: 0 }],
+        },
+    },
+    victory: {
+        bpm: 140,
+        smile: 0.9,
+        label: 'Victory',
+        bones: {
+            hips: [{ ax: 0, ay: 0, az: 1, amp: 0.12, freq: 1.1, phase: 0 }],
+            spine: [{ ax: 0, ay: 0, az: 1, amp: 0.08, freq: 1.1, phase: 0.3 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.08, freq: 2.2, phase: 0 }],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.52, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.52, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: 0.4, freq: 2.2, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.4, freq: 2.2, phase: Math.PI }],
+        },
+    },
+    pulled: {
+        bpm: 70,
+        smile: 0,
+        label: 'Pulled',
+        autoReturnMs: 900,
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: 0.18, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.22, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.12, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: -0.18, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: 0.18, freq: 0, phase: 0 }],
+        },
+    },
+    eaten: {
+        bpm: 45,
+        smile: 0,
+        label: 'Eaten',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.62, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.36, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.2, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.3, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: -0.32, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: -0.32, freq: 0, phase: 0 }],
+        },
+    },
+    handup: {
+        bpm: 90,
+        smile: 0.45,
+        label: 'Hand Up',
+        autoReturnMs: 1600,
+        bones: {
+            spine: [{ ax: 0, ay: 0, az: 1, amp: -0.04, freq: 0, phase: 0 }],
+            head: [{ ax: 0, ay: 1, az: 0, amp: 0.08, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.72, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.95, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.42, freq: 0, phase: 0 }],
+        },
+    },
+    index: {
+        bpm: 90,
+        smile: 0.35,
+        label: 'Index',
+        autoReturnMs: 1500,
+        bones: {
+            spine: [{ ax: 0, ay: 1, az: 0, amp: -0.08, freq: 0, phase: 0 }],
+            head: [{ ax: 0, ay: 1, az: 0, amp: -0.1, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.48, freq: 0, phase: 0 }],
+            rightArm: [
+                { ax: 1, ay: 0, az: 0, amp: 0.35, freq: 0, phase: 0 },
+                { ax: 0, ay: 1, az: 0, amp: -0.22, freq: 0, phase: 0 },
+            ],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.18, freq: 0, phase: 0 }],
+        },
+    },
+    ok: {
+        bpm: 100,
+        smile: 0.65,
+        label: 'OK',
+        autoReturnMs: 1400,
+        bones: {
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.04, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.5, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.55, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.62, freq: 0, phase: 0 }],
+        },
+    },
+    thumbup: {
+        bpm: 100,
+        smile: 0.8,
+        label: 'Thumb Up',
+        autoReturnMs: 1500,
+        bones: {
+            spine: [{ ax: 0, ay: 0, az: 1, amp: -0.03, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.42, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.28, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.75, freq: 0, phase: 0 }],
+        },
+    },
+    thumbdown: {
+        bpm: 80,
+        smile: 0.0,
+        label: 'Thumb Down',
+        autoReturnMs: 1500,
+        bones: {
+            spine: [{ ax: 0, ay: 0, az: 1, amp: 0.03, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: -0.07, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.24, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: -0.18, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: -0.72, freq: 0, phase: 0 }],
+        },
+    },
+    side: {
+        bpm: 70,
+        smile: 0.25,
+        label: 'Side',
+        bones: {
+            hips: [{ ax: 0, ay: 0, az: 1, amp: 0.16, freq: 0, phase: 0 }],
+            spine: [{ ax: 0, ay: 0, az: 1, amp: 0.18, freq: 0, phase: 0 }],
+            spine2: [{ ax: 0, ay: 0, az: 1, amp: 0.1, freq: 0, phase: 0 }],
+            head: [{ ax: 0, ay: 0, az: 1, amp: -0.09, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.25, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.25, freq: 0, phase: 0 }],
+        },
+    },
+    shrug: {
+        bpm: 100,
+        smile: 0.2,
+        label: 'Shrug',
+        autoReturnMs: 1300,
+        bones: {
+            spine: [{ ax: 1, ay: 0, az: 0, amp: -0.08, freq: 0, phase: 0 }],
+            head: [
+                { ax: 1, ay: 0, az: 0, amp: 0.08, freq: 0, phase: 0 },
+                { ax: 0, ay: 0, az: 1, amp: 0.04, freq: 0, phase: 0 },
+            ],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.38, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.38, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: -0.24, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: -0.24, freq: 0, phase: 0 }],
+            leftForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.34, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.34, freq: 0, phase: 0 }],
+        },
+    },
+    namaste: {
+        bpm: 70,
+        smile: 0.55,
+        label: 'Namaste',
+        autoReturnMs: 1800,
+        bones: {
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.07, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.1, freq: 0, phase: 0 }],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.35, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.35, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: 0.6, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: 0.6, freq: 0, phase: 0 }],
+            leftForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.65, freq: 0, phase: 0 }],
+            rightForeArm: [{ ax: 1, ay: 0, az: 0, amp: 0.65, freq: 0, phase: 0 }],
+        },
+    },
+    hip: {
+        bpm: 60,
+        smile: 0.35,
+        label: 'Hip',
+        bones: {
+            hips: [{ ax: 0, ay: 0, az: 1, amp: -0.2, freq: 0, phase: 0 }],
+            spine: [{ ax: 0, ay: 0, az: 1, amp: 0.1, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.42, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.18, freq: 0, phase: 0 }],
+        },
+    },
+    turn: {
+        bpm: 60,
+        smile: 0.2,
+        label: 'Turn',
+        bones: {
+            hips: [{ ax: 0, ay: 1, az: 0, amp: 0.24, freq: 0, phase: 0 }],
+            spine: [{ ax: 0, ay: 1, az: 0, amp: 0.18, freq: 0, phase: 0 }],
+            spine2: [{ ax: 0, ay: 1, az: 0, amp: 0.12, freq: 0, phase: 0 }],
+            head: [{ ax: 0, ay: 1, az: 0, amp: -0.1, freq: 0, phase: 0 }],
+        },
+    },
+    bend: {
+        bpm: 50,
+        smile: 0.1,
+        label: 'Bend',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: 0.2, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.38, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.22, freq: 0, phase: 0 }],
+            neck: [{ ax: 1, ay: 0, az: 0, amp: -0.08, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: -0.1, freq: 0, phase: 0 }],
+        },
+    },
+    back: {
+        bpm: 50,
+        smile: 0.1,
+        label: 'Back',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.16, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: -0.2, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: -0.12, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.1, freq: 0, phase: 0 }],
+        },
+    },
+    straight: {
+        bpm: 60,
+        smile: 0.15,
+        label: 'Straight',
+        bones: {
+            hips: [{ ax: 0, ay: 0, az: 1, amp: 0, freq: 0, phase: 0 }],
+            spine: [{ ax: 0, ay: 0, az: 1, amp: 0, freq: 0, phase: 0 }],
+            head: [{ ax: 0, ay: 0, az: 1, amp: 0, freq: 0, phase: 0 }],
+        },
+    },
+    wide: {
+        bpm: 60,
+        smile: 0.35,
+        label: 'Wide',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.05, freq: 0, phase: 0 }],
+            leftShoulder: [{ ax: 0, ay: 0, az: 1, amp: 0.38, freq: 0, phase: 0 }],
+            rightShoulder: [{ ax: 0, ay: 0, az: 1, amp: -0.38, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.55, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.55, freq: 0, phase: 0 }],
+        },
+    },
+    oneknee: {
+        bpm: 40,
+        smile: 0.05,
+        label: 'One Knee',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.42, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.2, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.08, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 0, ay: 0, az: 1, amp: 0.3, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 0, ay: 0, az: 1, amp: -0.18, freq: 0, phase: 0 }],
+        },
+    },
+    kneel: {
+        bpm: 40,
+        smile: 0.05,
+        label: 'Kneel',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.55, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.28, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.12, freq: 0, phase: 0 }],
+            head: [{ ax: 1, ay: 0, az: 0, amp: 0.1, freq: 0, phase: 0 }],
+        },
+    },
+    sitting: {
+        bpm: 40,
+        smile: 0.2,
+        label: 'Sitting',
+        bones: {
+            hips: [{ ax: 1, ay: 0, az: 0, amp: -0.7, freq: 0, phase: 0 }],
+            spine: [{ ax: 1, ay: 0, az: 0, amp: 0.16, freq: 0, phase: 0 }],
+            spine2: [{ ax: 1, ay: 0, az: 0, amp: 0.06, freq: 0, phase: 0 }],
+            leftArm: [{ ax: 1, ay: 0, az: 0, amp: -0.2, freq: 0, phase: 0 }],
+            rightArm: [{ ax: 1, ay: 0, az: 0, amp: -0.2, freq: 0, phase: 0 }],
+        },
+    },
+    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.1, 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.1, 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.3, 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.3, 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 }],
+        },
+    },
+};
+/** All available motion keys (runtime list for pickers / validation). */
+exports.MOTION_KEYS = Object.keys(exports.MOTION_DEFS);
+/** Returns true if `key` names a known motion. */
+function isMotionKey(key) {
+    return Object.prototype.hasOwnProperty.call(exports.MOTION_DEFS, key);
+}
+/**
+ * Gesture names supported by the upstream met4citizen TalkingHead (master).
+ * Passing anything outside this set to playGesture() is a silent no-op there,
+ * so consumers (and the editor) can validate against this list.
+ */
+exports.TALKINGHEAD_GESTURES = [
+    'handup',
+    'index',
+    'ok',
+    'thumbup',
+    'thumbdown',
+    'side',
+    'shrug',
+    'namaste',
+];
+/**
+ * Built-in pose template names from upstream TalkingHead (master). playPose()
+ * accepts either one of these names OR a URL to a pose animation file — so
+ * combat states like a kneeling "defeated" pose need no hosted asset.
+ */
+exports.TALKINGHEAD_POSES = [
+    'side',
+    'hip',
+    'turn',
+    'bend',
+    'back',
+    'straight',
+    'wide',
+    'oneknee',
+    'kneel',
+    'sitting',
+];

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

@@ -0,0 +1,46 @@
+/**
+ * Framework-free runtime for the procedural motion engine.
+ *
+ * Operates on a minimal structural bone interface (anything exposing a
+ * settable `quaternion` with x/y/z/w) so it works against three.js Object3D
+ * in the native path without importing three.js here. The generated WebView
+ * uses an inlined copy of the same math (src/html/motion.ts) for zero-dep
+ * execution inside the iframe.
+ */
+import { type MotionBoneKey, type MotionKey } from './motion';
+export interface Quat {
+    x: number;
+    y: number;
+    z: number;
+    w: number;
+}
+/** Minimal three.js-compatible bone shape. */
+export interface MotionBone {
+    name: string;
+    quaternion: {
+        x: number;
+        y: number;
+        z: number;
+        w: number;
+        set: (x: number, y: number, z: number, w: number) => void;
+    };
+}
+export declare function quatFromAxisAngle(ax: number, ay: number, az: number, angle: number): Quat;
+export declare function quatMultiply(a: Quat, b: Quat): Quat;
+/**
+ * Walks a skeleton (via a traverse callback) and maps logical bone keys to the
+ * matching bones plus their rest quaternions. Pass a `traverse` that invokes
+ * the callback for every bone node (three.js Object3D.traverse works directly).
+ */
+export declare function scanMotionBones(traverse: (visit: (bone: MotionBone) => void) => void): {
+    bones: Partial<Record<MotionBoneKey, MotionBone>>;
+    rest: Partial<Record<MotionBoneKey, Quat>>;
+};
+/**
+ * Applies one frame of a motion onto the mapped bones. `tSec` is seconds
+ * elapsed since the motion started. Static oscillators (freq === 0) contribute
+ * a constant offset (held pose); sinusoidal ones animate.
+ */
+export declare function applyMotionFrame(motionKey: MotionKey, tSec: number, bones: Partial<Record<MotionBoneKey, MotionBone>>, rest: Partial<Record<MotionBoneKey, Quat>>): void;
+/** Restores mapped bones to their captured rest quaternions. */
+export declare function restoreMotionBones(bones: Partial<Record<MotionBoneKey, MotionBone>>, rest: Partial<Record<MotionBoneKey, Quat>>): void;

package/dist/core/avatar/motionRuntime.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.quatFromAxisAngle = quatFromAxisAngle;
+exports.quatMultiply = quatMultiply;
+exports.scanMotionBones = scanMotionBones;
+exports.applyMotionFrame = applyMotionFrame;
+exports.restoreMotionBones = restoreMotionBones;
+/**
+ * Framework-free runtime for the procedural motion engine.
+ *
+ * Operates on a minimal structural bone interface (anything exposing a
+ * settable `quaternion` with x/y/z/w) so it works against three.js Object3D
+ * in the native path without importing three.js here. The generated WebView
+ * uses an inlined copy of the same math (src/html/motion.ts) for zero-dep
+ * execution inside the iframe.
+ */
+const motion_1 = require("./motion");
+function quatFromAxisAngle(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) };
+}
+function quatMultiply(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,
+    };
+}
+const norm = (s) => s.toLowerCase().replace(/[_\s\-.]/g, '');
+/**
+ * Walks a skeleton (via a traverse callback) and maps logical bone keys to the
+ * matching bones plus their rest quaternions. Pass a `traverse` that invokes
+ * the callback for every bone node (three.js Object3D.traverse works directly).
+ */
+function scanMotionBones(traverse) {
+    const bones = {};
+    const rest = {};
+    const entries = Object.entries(motion_1.MOTION_BONE_SEARCH);
+    traverse((bone) => {
+        const lk = norm(bone.name);
+        for (const [key, kws] of entries) {
+            if (bones[key])
+                continue;
+            if (kws.some((kw) => lk.includes(norm(kw)))) {
+                bones[key] = bone;
+                const q = bone.quaternion;
+                rest[key] = { x: q.x, y: q.y, z: q.z, w: q.w };
+            }
+        }
+    });
+    return { bones, rest };
+}
+/**
+ * Applies one frame of a motion onto the mapped bones. `tSec` is seconds
+ * elapsed since the motion started. Static oscillators (freq === 0) contribute
+ * a constant offset (held pose); sinusoidal ones animate.
+ */
+function applyMotionFrame(motionKey, tSec, bones, rest) {
+    const def = motion_1.MOTION_DEFS[motionKey];
+    if (!def)
+        return;
+    for (const [boneName, oscillators] of Object.entries(def.bones)) {
+        const key = boneName;
+        const bone = bones[key];
+        const restQuat = rest[key];
+        if (!bone || !restQuat || !oscillators)
+            continue;
+        let q = { ...restQuat };
+        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 = quatMultiply(q, quatFromAxisAngle(osc.ax, osc.ay, osc.az, angle));
+        }
+        bone.quaternion.set(q.x, q.y, q.z, q.w);
+    }
+}
+/** Restores mapped bones to their captured rest quaternions. */
+function restoreMotionBones(bones, rest) {
+    for (const [key, bone] of Object.entries(bones)) {
+        const restQuat = rest[key];
+        if (bone && restQuat)
+            bone.quaternion.set(restQuat.x, restQuat.y, restQuat.z, restQuat.w);
+    }
+}