talking-head-studio 0.4.10 → 0.4.12

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

@@ -0,0 +1,1713 @@
+/**
+ * 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.
+ */
+/** A single sinusoidal (or static, when freq === 0) rotation oscillator. */
+export interface MotionOscillator {
+    /** Rotation axis x/y/z (need not be normalized for small angles). */
+    ax: number;
+    ay: number;
+    az: number;
+    /** Peak rotation in radians. */
+    amp: number;
+    /** Oscillation frequency in Hz. freq === 0 means a held static pose offset. */
+    freq: number;
+    /** Phase offset in radians. */
+    phase: number;
+}
+/** Logical bone key -> list of oscillators applied on top of its rest pose. */
+export type MotionBoneMap = Partial<Record<MotionBoneKey, MotionOscillator[]>>;
+export interface MotionDef {
+    /** Beats per minute — cosmetic metadata (drives beat UI in the full editor). */
+    bpm: number;
+    /** Smile morph weight held while this motion plays (0..1). */
+    smile: number;
+    /** Human-readable label. */
+    label: string;
+    /**
+     * When set, the motion auto-reverts to rest after this many milliseconds.
+     * Used by pose-like combat states (attack/defend) so a combat loop snaps to
+     * a pose then returns to guard without an explicit stop message. Omitted for
+     * looping motions (groove, idle, …) which run until stopped.
+     */
+    autoReturnMs?: number;
+}
+export type MotionBoneKey = 'hips' | 'spine' | 'spine2' | 'neck' | 'head' | 'leftShoulder' | 'rightShoulder' | 'leftArm' | 'rightArm' | 'leftForeArm' | 'rightForeArm';
+export interface MotionDefWithBones extends MotionDef {
+    bones: MotionBoneMap;
+}
+/**
+ * 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.
+ */
+export declare const MOTION_BONE_SEARCH: Record<MotionBoneKey, string[]>;
+export declare const MOTION_DEFS: {
+    groove: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            neck: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    wave: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    nod: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            neck: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    idle: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    attack: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    defend: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    cast: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    hurt: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    die: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    windup: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    victory: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    pulled: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    eaten: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    handup: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    index: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    ok: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    thumbup: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    thumbdown: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    side: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    shrug: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    namaste: {
+        bpm: number;
+        smile: number;
+        label: string;
+        autoReturnMs: number;
+        bones: {
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    hip: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    turn: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    bend: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            neck: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    back: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    straight: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    wide: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    oneknee: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    kneel: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    sitting: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+    celebrate: {
+        bpm: number;
+        smile: number;
+        label: string;
+        bones: {
+            hips: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            spine2: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            neck: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            head: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightShoulder: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            leftForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+            rightForeArm: {
+                ax: number;
+                ay: number;
+                az: number;
+                amp: number;
+                freq: number;
+                phase: number;
+            }[];
+        };
+    };
+};
+/** Union of valid motion keys, for typed consumer APIs. */
+export type MotionKey = keyof typeof MOTION_DEFS;
+/** All available motion keys (runtime list for pickers / validation). */
+export declare const MOTION_KEYS: MotionKey[];
+/** Returns true if `key` names a known motion. */
+export declare function isMotionKey(key: string): key is MotionKey;
+/**
+ * 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.
+ */
+export declare const TALKINGHEAD_GESTURES: readonly ["handup", "index", "ok", "thumbup", "thumbdown", "side", "shrug", "namaste"];
+export type TalkingHeadGesture = (typeof TALKINGHEAD_GESTURES)[number];
+/**
+ * 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.
+ */
+export declare const TALKINGHEAD_POSES: readonly ["side", "hip", "turn", "bend", "back", "straight", "wide", "oneknee", "kneel", "sitting"];
+export type TalkingHeadPose = (typeof TALKINGHEAD_POSES)[number];