@convai/embody 0.1.0

package/dist/motion/breathe.js

@@ -0,0 +1,93 @@
+import * as THREE from 'three';
+function freshAnchor() {
+    return { base: new THREE.Quaternion(), lastWritten: new THREE.Quaternion(), has: false };
+}
+/**
+ * Subtle additive chest/spine motion so the body never reads frozen.
+ *
+ * RULING (2026-09-07 fix wave, C3, superseding an earlier fix in this same
+ * wave — see the coordinator correction in final-fix-report.md): the
+ * ORIGINAL version of this class post-multiplied the breath delta directly
+ * onto `chest.quaternion`/`waist.quaternion`, on the claim that "the mixer
+ * rewrites every frame, so multiplying in never accumulates." That's only
+ * true while an active AnimationMixer action is bound to those bones, and
+ * `createCharacter` registers clips without ever calling `.play()` — on
+ * that (default) path nothing resets the bone between frames, so the
+ * original code compounded without bound (measured ±30°+ at 30fps).
+ *
+ * A FIRST fix composed `rest * breath` absolutely every frame, using the
+ * bone's bind pose captured once at `resolveRig` time. That bounded the
+ * no-clip case but silently broke the WITH-clip case: every clip in
+ * `demo/fixtures/japanese-f-animations.glb` (Idle included, which the demo
+ * actually plays) animates `spine_02`/`spine_04` — the exact two bones this
+ * system drives — so composing onto a STATIC captured rest pose discarded
+ * the clip's own spine motion outright, every frame, on the normal
+ * (with-clip) path. That is worse than the bug it fixed: a spinning torso
+ * with no clip is unmissable on day one; silently-dropped clip spine
+ * animation on the normal path is not.
+ *
+ * Fixed properly here by having each bone remember what THIS system itself
+ * last wrote to it (`BoneAnchor.lastWritten`). Each frame:
+ *   - if the bone's LIVE quaternion differs from `lastWritten`, something
+ *     else (the mixer) rewrote it since — adopt the bone's current value as
+ *     this frame's `base` and remember it.
+ *   - if it is identical, this system's own previous write is still
+ *     standing (nothing else touched the bone) — reuse the stored `base`
+ *     rather than compounding on top of what was already composed.
+ * Then write `base * breath`. With an active clip continuously rewriting
+ * the bone (the normal path), `base` re-adopts the clip's live pose every
+ * frame and breath composes on top of it, exactly as the pipeline's stage-3
+ * "additive, after the mixer" contract intends. With no clip at all (the
+ * path the original bug was about), nothing ever differs from
+ * `lastWritten`, so `base` stays anchored to whatever the bone held on the
+ * first frame this system ever touched it (its bind pose, in practice) —
+ * bounded, exactly as the earlier fix intended, without needing a
+ * separately-captured rest pose at all.
+ *
+ * The comparison is EXACT (`Quaternion.equals`, not an epsilon): a
+ * `.copy()` followed by a later read of that SAME untouched object is
+ * bit-identical, so exact equality has no false-negative risk from float
+ * drift on the "nothing touched it" path. An epsilon would also risk a
+ * false negative on the "something touched it" path — a real clip whose
+ * frame-to-frame delta happens to be smaller than some chosen tolerance
+ * (e.g. a slow sway lingering near an extremum) would be missed and
+ * wrongly treated as "unchanged."
+ */
+export class BreathingSystem {
+    constructor(config = {}) {
+        this.stage = 3;
+        this.clock = Math.random() * 10; // random phase per instance
+        this.q = new THREE.Quaternion(); // pre-allocated
+        this.chestAnchor = freshAnchor();
+        this.waistAnchor = freshAnchor();
+        this.rate = config.rate ?? 0.22;
+        this.amount = config.amount ?? 0.012;
+        this.enabled = config.enabled ?? true;
+    }
+    update(dt, ctx) {
+        if (!this.enabled || ctx.reducedMotion)
+            return;
+        const chest = ctx.rig.bones.spineChest;
+        const waist = ctx.rig.bones.spineWaist;
+        if (!chest && !waist)
+            return;
+        this.clock += dt;
+        const phase = this.clock * this.rate * Math.PI * 2;
+        // Asymmetric breath: sharper rise (inhale), longer fall (exhale).
+        const breath = Math.sin(phase) + 0.3 * Math.sin(phase * 2 + 1.2);
+        const basis = ctx.rig.profile.basis;
+        if (chest)
+            this.applyBreath(chest, this.chestAnchor, -breath * this.amount, basis.right);
+        if (waist)
+            this.applyBreath(waist, this.waistAnchor, -breath * this.amount * 0.5, basis.right);
+    }
+    applyBreath(bone, anchor, angle, axis) {
+        if (!anchor.has || !bone.quaternion.equals(anchor.lastWritten)) {
+            anchor.base.copy(bone.quaternion);
+            anchor.has = true;
+        }
+        this.q.setFromAxisAngle(axis, angle);
+        bone.quaternion.copy(anchor.base).multiply(this.q);
+        anchor.lastWritten.copy(bone.quaternion);
+    }
+}

package/dist/motion/eyeGaze.d.ts

@@ -0,0 +1,65 @@
+import type { FrameContext, System } from '../character/pipeline.js';
+import type { GazeSource } from './types.js';
+export interface EyeGazeConfig {
+    /**
+     * Per-frame ease rate toward the gaze target. Verbatim from
+     * `useEyeTracking.ts`'s `DEFAULT_CONFIG.lerpSpeed` (useEyeTracking.ts:108)
+     * — NOT this plan's originally-invented `ease: 0.25` (RULING R47).
+     */
+    lerpSpeed?: number;
+    /**
+     * Constant downward bias folded into the vertical target before
+     * clamping — "pupils look slightly lower by default"
+     * (`DEFAULT_CONFIG.verticalOffset`, useEyeTracking.ts:109, doc at :31).
+     * The original brief omitted this field entirely (RULING R47).
+     */
+    verticalOffset?: number;
+    /**
+     * Scale on the eye-look MORPH values at full deflection. RULING
+     * (2026-09-07 fix wave): default is the rig-tuned value from the actual
+     * convai-mha-1 call site (SofiaV4.tsx:323, `morphGain: 0.65`), not the
+     * generic `useEyeTracking.ts` DEFAULT_CONFIG value of 1 — that call site's
+     * rig shares this exact CTRL_expressions_eyeLook* morph set (same names
+     * `CONVAI_MHA_1` resolves against) and its own comment gives the reason:
+     * "the v4 eye-look shapes encode ~40°+ of eyeball rotation at 1.0; scale
+     * down so a 30° gaze angle maps to a ~30° eyeball turn." That is a
+     * rig-mesh property, independent of C4's `DOWN_LID_SCALE` (which damps
+     * only the down-gaze lid-travel channel) — the two compound only on the
+     * down direction, by design (down gaze is the one direction stacked with
+     * BlinkSystem's resting droop too).
+     */
+    morphGain?: number;
+}
+/**
+ * Eye gaze on convai-mha-1 is MORPH-ONLY — the mandated rig has no eye bones
+ * (character spec 2.2). This system ports only the morph-output half of
+ * `useEyeTracking`'s dual bone+morph mechanism
+ * (useEyeTracking.ts:538-562) — the bone-rotation path is CC4-only and out
+ * of scope here.
+ *
+ * The channel names are cross-named: driving `eyeLookLeft*` rotates the eyes
+ * toward the character's RIGHT (useEyeTracking.ts:156-159, verified live on
+ * the UE rig by driving each morph in isolation). `CONVAI_MHA_1` encodes
+ * that as in/out morph roles (`eyeLookInL`/`eyeLookOutL`/`eyeLookInR`/
+ * `eyeLookOutR`); this system only ever speaks in in/out terms and never
+ * references a literal left/right channel name.
+ *
+ * DEFERRED (RULING R48 — logged for final review, deliberately NOT built
+ * here):
+ *   - saccades: dart-to-a-new-point-and-hold idle micro-movement
+ *     (useEyeTracking.ts:254-262, 458-485).
+ *   - the speech lock that suppresses saccades for full eye contact while
+ *     speaking, and the `isListening` lerp-to-1.0 override
+ *     (useEyeTracking.ts:264-265, 401, 485).
+ *
+ * Registered at stage 6 (morph), between lipsync and blink.
+ */
+export declare class EyeGazeSystem implements System {
+    private readonly gaze;
+    private readonly cfg;
+    readonly stage: 6;
+    private h;
+    private v;
+    constructor(gaze: GazeSource, cfg?: EyeGazeConfig);
+    update(_dt: number, ctx: FrameContext): void;
+}

package/dist/motion/eyeGaze.js

@@ -0,0 +1,66 @@
+import * as THREE from 'three';
+import { writeMorph } from '../rig/resolve.js';
+/**
+ * Eye gaze on convai-mha-1 is MORPH-ONLY — the mandated rig has no eye bones
+ * (character spec 2.2). This system ports only the morph-output half of
+ * `useEyeTracking`'s dual bone+morph mechanism
+ * (useEyeTracking.ts:538-562) — the bone-rotation path is CC4-only and out
+ * of scope here.
+ *
+ * The channel names are cross-named: driving `eyeLookLeft*` rotates the eyes
+ * toward the character's RIGHT (useEyeTracking.ts:156-159, verified live on
+ * the UE rig by driving each morph in isolation). `CONVAI_MHA_1` encodes
+ * that as in/out morph roles (`eyeLookInL`/`eyeLookOutL`/`eyeLookInR`/
+ * `eyeLookOutR`); this system only ever speaks in in/out terms and never
+ * references a literal left/right channel name.
+ *
+ * DEFERRED (RULING R48 — logged for final review, deliberately NOT built
+ * here):
+ *   - saccades: dart-to-a-new-point-and-hold idle micro-movement
+ *     (useEyeTracking.ts:254-262, 458-485).
+ *   - the speech lock that suppresses saccades for full eye contact while
+ *     speaking, and the `isListening` lerp-to-1.0 override
+ *     (useEyeTracking.ts:264-265, 401, 485).
+ *
+ * Registered at stage 6 (morph), between lipsync and blink.
+ */
+export class EyeGazeSystem {
+    constructor(gaze, cfg = {}) {
+        this.gaze = gaze;
+        this.cfg = cfg;
+        this.stage = 6;
+        this.h = 0;
+        this.v = 0;
+    }
+    update(_dt, ctx) {
+        const lerpSpeed = this.cfg.lerpSpeed ?? 0.2;
+        const verticalOffset = this.cfg.verticalOffset ?? -0.15;
+        const gain = this.cfg.morphGain ?? 0.65;
+        const d = this.gaze.direction;
+        const targetH = ctx.reducedMotion ? 0 : THREE.MathUtils.clamp(d.horizontal, -1, 1);
+        const targetV = ctx.reducedMotion
+            ? 0
+            : THREE.MathUtils.clamp(d.vertical + verticalOffset, -1, 1);
+        this.h += (targetH - this.h) * lerpSpeed;
+        this.v += (targetV - this.v) * lerpSpeed;
+        const h = this.h * gain;
+        const v = this.v * gain;
+        // Positive h = looking to the character's RIGHT. That is "in" (nose-ward)
+        // for the LEFT eye and "out" for the RIGHT eye.
+        writeMorph(ctx.rig, 'eyeLookInL', Math.max(0, h));
+        writeMorph(ctx.rig, 'eyeLookOutL', Math.max(0, -h));
+        writeMorph(ctx.rig, 'eyeLookInR', Math.max(0, -h));
+        writeMorph(ctx.rig, 'eyeLookOutR', Math.max(0, h));
+        // Positive v = looking up. Up/down are named straight (not cross-named)
+        // on both eyes. Down-gaze lid travel is damped (RULING C4, 2026-09-07 fix
+        // wave): ported from useEyeTracking.ts:545-551's `DOWN_LID_SCALE = 0.65`
+        // — at 1:1 the Look_Down morphs plus BlinkSystem's resting droop
+        // (`relax`) shut the eyes whenever the gaze drops. Only the DOWN
+        // direction is scaled; up/left/right are untouched.
+        const DOWN_LID_SCALE = 0.65;
+        writeMorph(ctx.rig, 'eyeLookUpL', Math.max(0, v));
+        writeMorph(ctx.rig, 'eyeLookDownL', DOWN_LID_SCALE * Math.max(0, -v));
+        writeMorph(ctx.rig, 'eyeLookUpR', Math.max(0, v));
+        writeMorph(ctx.rig, 'eyeLookDownR', DOWN_LID_SCALE * Math.max(0, -v));
+    }
+}

package/dist/motion/gaze.d.ts

@@ -0,0 +1,212 @@
+import type { FrameContext, System } from '../character/pipeline.js';
+import type { GazeDirection, GazeSource } from './types.js';
+/**
+ * Config surface for `GazeSystem`. Task 6 landed the geometric core —
+ * target -> yaw/pitch -> head/neck split -> time-based, velocity-capped
+ * smoothing -> `setLookQuat`. Task 7 (this task) adds the aliveness layer:
+ * idle drift, look-away gaze shifts and turn-bank, all read by `update()`
+ * below. Task 8 (clip-blending: camera lock, deviation pull-back) extends
+ * the SAME class and will read the fields still marked "reserved" — they
+ * are declared now so the class's public config shape does not change
+ * under that task, but `update()` does not read them yet.
+ */
+export interface GazeConfig {
+    /** Half-angle (rad) the HEAD alone covers before the neck starts sharing
+     *  yaw. Verbatim from `HeadTrackingConfig.DEFAULT_CONFIG.headOnlyAngle`
+     *  (useHeadTracking.ts:107) — NOT the interface JSDoc's PI/3 (line 17),
+     *  which the implementation itself does not use. Per RULING R20: the
+     *  DEFAULTS object is ground truth, and its own comment explains 0.44 was
+     *  a deliberate retune down from a wider zone that put the head near its
+     *  joint limit for a side viewer. */
+    headOnlyAngle?: number;
+    /** Beyond this yaw (rad) tracking disengages entirely for the frame
+     *  (target clamped to zero, not clamped-in-range). */
+    maxTrackAngle?: number;
+    /** Vertical (pitch) clamp, radians. */
+    maxPitchAngle?: number;
+    /** Ease rate (per-second, before the `* 60` time-based conversion in
+     *  `update()`) toward the target yaw/pitch. Velocity-capped — see
+     *  `update()`. */
+    lerpSpeed?: number;
+    /** Share of pitch applied to the head. */
+    headPitchFactor?: number;
+    /** Share of pitch applied to each neck bone. */
+    neckPitchFactor?: number;
+    /** Share of the excess (beyond `headOnlyAngle`) yaw applied to the neck.
+     *  Verbatim from `DEFAULT_CONFIG.neckYawFactor` (useHeadTracking.ts:113),
+     *  which is 0.75, not the interface JSDoc's 0.7 (line 30). Per R20. */
+    neckYawFactor?: number;
+    /** Idle micro-drift amplitude on yaw, radians. */
+    idleYawAmp?: number;
+    /** Idle micro-drift amplitude on pitch, radians. */
+    idlePitchAmp?: number;
+    /** Idle micro-drift amplitude on roll, radians. */
+    idleRollAmp?: number;
+    /** Time multiplier for the idle-drift clock. */
+    idleSpeed?: number;
+    /** Roll added per radian of (capped) head yaw — banks the head into a
+     *  turn. */
+    turnBank?: number;
+    /** Max yaw (radians) of an occasional look-away gaze shift. */
+    gazeYawRange?: number;
+    /** Max pitch (radians) of a gaze shift. */
+    gazePitchRange?: number;
+    /** Max roll (radians) of a gaze shift. */
+    gazeRollRange?: number;
+    /** Ease rate (per-second, before the `* 60` time-based conversion) the
+     *  gaze-shift offset eases toward its target at. */
+    gazeEase?: number;
+    /** Minimum seconds a gaze-shift target is held before re-picking. */
+    gazeDwellMin?: number;
+    /** Maximum seconds a gaze-shift target is held before re-picking. */
+    gazeDwellMax?: number;
+    /** Camera-lock strength while idle (0-1): how much of the clip's local
+     *  head rotation is replaced by the look pose. High values mean
+     *  procedural drift/gaze carry the aliveness and the clip barely
+     *  reaches the output. */
+    idleLock?: number;
+    /** Camera-lock strength while `ctx.speaking` — focused on the viewer. */
+    talkLock?: number;
+    /** Clip-deviation (radians, angle between the clip's head pose and the
+     *  look pose) below which the clip flows through untouched. */
+    deviationLo?: number;
+    /** Clip-deviation (radians) by which the pull-back saturates — the head
+     *  is fully locked back to the look pose regardless of `idleLock`/
+     *  `talkLock`. */
+    deviationHi?: number;
+    /** Static construction-time gate. Live control is `setEnabled()`. */
+    enabled?: boolean;
+}
+/**
+ * Head/neck gaze pose solve, ported from `useHeadTracking`
+ * (convai-web-sdk-internal `examples/react-three-fiber/src/hooks/useHeadTracking.ts`).
+ *
+ * Stage 2 — the ONLY system permitted to OVERRIDE the mixer's head/neck
+ * rotation outright (`.copy(...)`, never `.multiply(...)`): a head that
+ * blends additively with its own animation clip fights itself every frame.
+ *
+ * Task 6 ported the geometric core: world target -> yaw/pitch about the
+ * rig's own basis -> head/neck split -> time-based, velocity-capped ease ->
+ * `setLookQuat`. Task 7 layered the aliveness on top of that same solve:
+ * always-on idle micro-drift, occasional look-away gaze shifts with dwell
+ * timing, and turn-bank roll — all suppressed under `ctx.reducedMotion`.
+ * Task 8 (this task) adds the clip-blending layer: a smoothed camera-lock
+ * strength (`idleLock`/`talkLock`, eased rather than switched — see
+ * `update()`) blended against the mixer's own clip pose, with a deviation
+ * pull-back (`deviationLo`/`deviationHi`) that guards large clip excursions
+ * regardless of lock strength; and `calm`, which de-emphasises the idle
+ * drift/gaze-shift amplitudes while the (smoothed) lock is high, i.e. while
+ * speaking — a focused speaker stops glancing around.
+ *
+ * The HEAD is the only bone that blends with the clip; the neck bones are
+ * still overridden outright (Task 6/7 behaviour, unchanged) — see
+ * `update()`.
+ *
+ * See `.superpowers/sdd/2026-09-07-convai-embody-motion-and-staging/task-6-report.md`,
+ * `task-7-report.md` and `task-8-report.md` for the line-by-line comparison
+ * against the prior art and the places this deliberately differs from it.
+ */
+export declare class GazeSystem implements System, GazeSource {
+    private readonly cfg;
+    readonly stage: 2;
+    readonly direction: GazeDirection;
+    private gate;
+    private yaw;
+    private pitch;
+    /** Idle-roll + turn-bank, written by the aliveness layer below. */
+    private roll;
+    /** Idle-drift clock, advanced by `dt * idleSpeed`. Randomly seeded so
+     *  multiple GazeSystem instances on stage together don't drift in
+     *  lockstep. */
+    private driftClock;
+    /** Current eased gaze-shift offsets (the "look-away" the head is
+     *  easing toward / holding). */
+    private shiftYaw;
+    private shiftPitch;
+    private shiftRoll;
+    /** The look-away target `shift*` is easing toward, re-picked every
+     *  dwell period. */
+    private shiftTargetYaw;
+    private shiftTargetPitch;
+    private shiftTargetRoll;
+    /** Seconds remaining before the next gaze-shift target is re-picked. */
+    private dwell;
+    /** Smoothed camera-lock strength, eased toward `idleLock`/`talkLock`
+     *  each frame (RULING R39) rather than switched instantly — ported
+     *  from `useHeadTracking.ts:581`'s `lockRef`, but time-based (R40)
+     *  instead of the prior art's bare per-frame `* 0.04`. Initialised to
+     *  `idleLock` so the very first frame doesn't jump. */
+    private lock;
+    private readonly vTarget;
+    private readonly vHead;
+    private readonly vLocal;
+    private readonly mInv;
+    /** What the mixer wrote to the head this frame, before we touch it. */
+    private readonly qClip;
+    /** The camera-locked look pose computed this frame. */
+    private readonly qLook;
+    /** Low-passed (tau ~0.2s) copy of `qClip`. RULING R43 part 2: the
+     *  deviation boost is measured against THIS, not the raw clip pose, so
+     *  one noisy/fast clip frame can't make the boost — and therefore the
+     *  blend — jump within a frame. Ported from useHeadTracking.ts:594-606. */
+    private readonly animHead;
+    private animHeadHas;
+    /** The blended pose, before the output velocity cap below is applied. */
+    private readonly qOut;
+    /** The actual pose WRITTEN to the head last frame — the anchor the
+     *  output velocity cap (RULING R43 part 3) rotates from. Ported from
+     *  useHeadTracking.ts:621-633. */
+    private readonly lastOutHead;
+    private lastOutHas;
+    /** RULING R61: the neck bones blend with their OWN clip pose too — same
+     *  low-pass, same shared head-derived `blend`, same output cap — ported
+     *  from useHeadTracking.ts:598-606 (low-pass) and :635-671 (blend +
+     *  cap). One low-pass/cap pair per neck bone, each independent (the
+     *  clip poses and, after the cap, the written poses differ per bone). */
+    private readonly animNeck1;
+    private animNeck1Has;
+    private readonly animNeck2;
+    private animNeck2Has;
+    private readonly qOutNeck;
+    private readonly lastOutNeck1;
+    private lastOutNeck1Has;
+    private readonly lastOutNeck2;
+    private lastOutNeck2Has;
+    constructor(cfg?: GazeConfig);
+    /**
+     * Live on/off gate, read every frame. While false the system writes
+     * NOTHING to the rig — the mixer's clips own the head/neck — and eases
+     * the internal yaw/pitch/roll state toward neutral so re-enabling does
+     * not snap the head back onto the camera.
+     */
+    setEnabled(on: boolean): void;
+    /**
+     * Time-based exponential ease toward `tgt`, velocity-capped so a frame
+     * hitch can't yank the head. Ported verbatim from
+     * useHeadTracking.ts:480-484 — NOT the bare `x += (target - x) * lerp`
+     * form, which is frame-rate dependent by construction (a 144Hz monitor
+     * would track visibly faster than a 60Hz one). Per RULING R22.
+     *
+     * Hoisted to a method (RULING R25) rather than a closure allocated inside
+     * `update()` — a per-frame closure is exactly the steady-state allocation
+     * this class's zero-allocation rule forbids. `useHeadTracking.ts` can
+     * afford the closure because it's a React hook body re-created rarely and
+     * garbage-collected on unmount; embody's `update()` runs every frame for
+     * the lifetime of the character.
+     */
+    private approach;
+    /**
+     * Smooth, non-repeating drift in ~[-1, 1] — three incommensurate sines
+     * (an fbm-lite). Ported VERBATIM from useHeadTracking.ts:144-150
+     * (function `drift`) — NOT the brief's single-sine placeholder
+     * (`Math.sin(t * 0.31)`), which is a different, un-sourced waveform.
+     * The three fixed frequencies/weights are shared by every axis; only
+     * the per-axis `seed` (and its own amplitude) differs, exactly as in
+     * the prior art's `drift(t, 1.0|7.3|13.1)` calls at lines 556-559.
+     *
+     * Hoisted to a method rather than a closure (RULING R25, same as
+     * `approach` above) — no steady-state allocation.
+     */
+    private drift;
+    update(dt: number, ctx: FrameContext): void;
+}