@convai/embody 1.0.1 → 1.1.0-beta.0

package/dist/motion/gaze.js

@@ -1,34 +1,14 @@
 import * as THREE from 'three';
-import { setLookQuat } from '../rig/profile.js';
-/**
- * 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.
- */
+import { EyeAim } from './eyeAim.js';
+/** Minimum-jerk ease: 0→1 with zero velocity and acceleration at both ends. */
+export const minJerk = (s) => {
+    const t = THREE.MathUtils.clamp(s, 0, 1);
+    return t * t * t * (10 - 15 * t + 6 * t * t);
+};
+const settled = (v) => ({ from: v, to: v, t: 1, dur: 1, delay: 0 });
+const valueOf = (m) => m.from + (m.to - m.from) * minJerk((m.t - m.delay) / m.dur);
+const done = (m) => m.t >= m.delay + m.dur;
+const DEG = Math.PI / 180;
 export class GazeSystem {
     constructor(cfg = {}) {
         this.cfg = cfg;
@@ -38,493 +18,279 @@ export class GazeSystem {
             right: { horizontal: 0, vertical: 0 },
             horizontal: 0, vertical: 0,
         };
-        /** World-space angle still between the head's forward and the target. */
         this.residual = { horizontal: 0, vertical: 0 };
-        this.yaw = 0;
-        this.pitch = 0;
-        /** Idle-roll + turn-bank, written by the aliveness layer below. */
-        this.roll = 0;
-        // --- Aliveness layer (Task 7) state -------------------------------
-        /** Idle-drift clock, advanced by `dt * idleSpeed`. Randomly seeded so
-         *  multiple GazeSystem instances on stage together don't drift in
-         *  lockstep. */
-        this.driftClock = Math.random() * 100;
-        /** Current eased gaze-shift offsets (the "look-away" the head is
-         *  easing toward / holding). */
-        this.shiftYaw = 0;
-        this.shiftPitch = 0;
-        this.shiftRoll = 0;
-        /** The look-away target `shift*` is easing toward, re-picked every
-         *  dwell period. */
-        this.shiftTargetYaw = 0;
-        this.shiftTargetPitch = 0;
-        this.shiftTargetRoll = 0;
-        /** Seconds remaining before the next gaze-shift target is re-picked. */
-        this.dwell = 0;
-        // Pre-allocated scratch — zero allocations on the steady-state path.
-        this.vTarget = new THREE.Vector3();
-        this.vHead = new THREE.Vector3();
-        this.vLocal = new THREE.Vector3();
-        this.mInv = new THREE.Matrix4();
-        // Scratch for the world-space residual published to EyeGazeSystem.
-        this.vAim = new THREE.Vector3();
-        this.vFwdW = new THREE.Vector3();
-        this.vRightW = new THREE.Vector3();
-        this.vUpW = new THREE.Vector3();
-        this.qHeadW = new THREE.Quaternion();
-        this.qRestInv = new THREE.Quaternion();
-        /** What the mixer wrote to the head this frame, before we touch it. */
-        this.qClip = new THREE.Quaternion();
-        /** The camera-locked look pose computed this frame. */
-        this.qLook = new THREE.Quaternion();
-        /** 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. */
-        this.animHead = new THREE.Quaternion();
-        this.animHeadHas = false;
-        /** The blended pose, before the output velocity cap below is applied. */
-        this.qOut = new THREE.Quaternion();
-        /** 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. */
-        this.lastOutHead = new THREE.Quaternion();
-        this.lastOutHas = false;
-        /** 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). */
-        this.animNeck1 = new THREE.Quaternion();
-        this.animNeck1Has = false;
-        this.animNeck2 = new THREE.Quaternion();
-        this.animNeck2Has = false;
-        this.qOutNeck = new THREE.Quaternion();
-        this.lastOutNeck1 = new THREE.Quaternion();
-        this.lastOutNeck1Has = false;
-        this.lastOutNeck2 = new THREE.Quaternion();
-        this.lastOutNeck2Has = false;
+        /** See `GazeSource.attending`. */
+        this.attending = false;
+        /** The world point the character is looking at this frame; see `GazeSource.focus`. */
+        this.focus = new THREE.Vector3();
+        this.headYaw = settled(0);
+        this.headPitch = settled(0);
+        this.torsoYaw = settled(0);
+        this.outside = 0;
+        this.twisted = 0;
+        this.sway = { yaw: 0, pitch: 0, has: false };
+        this.glance = { yaw: 0, pitch: 0, left: 0, next: 3 + Math.random() * 4 };
+        this.base = new Map();
+        this.out = new Map();
+        this.q = new THREE.Quaternion();
+        this.pq = new THREE.Quaternion();
+        this.up = new THREE.Vector3();
+        /** The body's lateral axis turned with the head: pitch nods about it. */
+        this.lateral = new THREE.Vector3();
+        this.fwd = new THREE.Vector3();
+        this.v = new THREE.Vector3();
+        this.w = new THREE.Vector3();
+        this.headPos = new THREE.Vector3();
+        this.m = new THREE.Matrix4();
+        this.qHead = new THREE.Quaternion();
         this.gate = cfg.enabled ?? true;
-        this.lock = cfg.idleLock ?? 0.9;
     }
-    /**
-     * 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) { this.gate = on; }
     /**
-     * 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.
-     */
-    approach(cur, tgt, k, maxStep) {
-        return cur + THREE.MathUtils.clamp((tgt - cur) * k, -maxStep, maxStep);
-    }
-    /**
-     * 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.
+     * Put back the clip pose on bones this system wrote and the mixer is not
+     * about to rewrite. Registered before the mixer (stage 0): at a loop seam
+     * or crossfade the mixer can blend from a bone's current value, which
+     * would otherwise still hold last frame's turn.
      */
-    drift(t, seed) {
-        return (Math.sin(t * 0.47 + seed) * 0.55 +
-            Math.sin(t * 0.83 + seed * 2.13) * 0.3 +
-            Math.sin(t * 1.71 + seed * 4.7) * 0.15);
+    beforeMixer() {
+        for (const [bone, was] of this.out)
+            if (was.equals(bone.quaternion))
+                bone.quaternion.copy(this.base.get(bone));
     }
     update(dt, ctx) {
         const head = ctx.rig.bones.head;
-        const neck1 = ctx.rig.bones.neck1;
-        const neck2 = ctx.rig.bones.neck2;
-        if (!head || !ctx.camera)
+        this.attending = false;
+        if (!head)
             return;
-        const lerpRate = this.cfg.lerpSpeed ?? 0.08;
-        const k = 1 - Math.exp(-lerpRate * 60 * dt);
-        const maxStep = 1.4 * dt; // rad — ~80 deg/s retarget speed limit
+        if (this.eyes === undefined)
+            this.eyes = EyeAim.calibrate(ctx.rig);
+        this.restoreClipPose(ctx);
         if (!this.gate) {
-            // Ease internal state toward neutral; write NOTHING to the rig.
-            this.yaw = this.approach(this.yaw, 0, k, maxStep);
-            this.pitch = this.approach(this.pitch, 0, k, maxStep);
-            this.roll = this.approach(this.roll, 0, k, maxStep);
-            // The clip owns the bone while gated — restart the clip low-pass and
-            // the output-cap anchor from the live pose on re-enable, rather than
-            // fighting a stale reference (same rationale as
-            // useHeadTracking.ts:322-324's gate<0.02 branch).
-            this.animHeadHas = false;
-            this.lastOutHas = false;
-            this.animNeck1Has = false;
-            this.animNeck2Has = false;
-            this.lastOutNeck1Has = false;
-            this.lastOutNeck2Has = false;
+            // Ease internal state home; the clip owns the bones while gated.
+            this.headYaw = settled(0);
+            this.headPitch = settled(0);
+            this.torsoYaw = settled(0);
+            this.out.clear();
             return;
         }
-        // Target direction in the head's PARENT space, so the solve reads off
-        // the rig's own rest-pose axes and is independent of where the body
-        // faces in the world. Using the head's actual world position (not its
-        // parent's origin) matters on a real rig, where the head bone sits
-        // offset up from neck_02 — see report for why this differs from the
-        // brief's reference snippet.
-        ctx.camera.getWorldPosition(this.vTarget);
-        head.getWorldPosition(this.vHead);
-        const parent = head.parent ?? ctx.root;
-        this.mInv.copy(parent.matrixWorld).invert();
-        this.vLocal.subVectors(this.vTarget, this.vHead).transformDirection(this.mInv);
-        // Into the head's REST frame. The yaw/pitch solved below are applied as
-        // `restHead * qLook` (the premultiply further down), i.e. RELATIVE to the
-        // head's rest orientation — so they must be MEASURED relative to it too.
-        //
-        //   want:  P · restHead · qLook · fwd = aim        (P = parent world quat)
-        //   so:    qLook solves against restHead⁻¹ · P⁻¹ · aim
-        //
-        // `transformDirection(mInv)` above supplies only P⁻¹ · aim. Without the
-        // restHead⁻¹ the solve measures in one frame and applies in another, and
-        // the head lands mis-aimed by exactly the rest tilt.
-        //
-        // Invisible on a rig whose bones rest at identity — which is every older
-        // fixture in this file. On the japanese-f fixture the head rests 11.42°
-        // tilted; measured on the live convai-mha-1 body, a level camera left the
-        // head aiming 17-20° ABOVE it, chin up, while the solve reported itself on
-        // target. That is the "it never looks at me directly" symptom.
-        const headRestFrame = ctx.rig.restPose.head;
-        if (headRestFrame)
-            this.vLocal.applyQuaternion(this.qRestInv.copy(headRestFrame).invert());
-        const basis = ctx.rig.profile.basis;
-        // Yaw/pitch of the target about the rig's own bone-local axes.
-        const right = this.vLocal.dot(basis.right);
-        const up = this.vLocal.dot(basis.up);
-        const fwd = this.vLocal.dot(basis.fwd);
-        let targetYaw = Math.atan2(right, fwd);
-        let targetPitch = -Math.atan2(up, Math.hypot(right, fwd));
-        const maxTrack = this.cfg.maxTrackAngle ?? Math.PI / 2;
-        const maxPitch = this.cfg.maxPitchAngle ?? Math.PI / 4;
-        if (Math.abs(targetYaw) > maxTrack) {
-            targetYaw = 0;
-            targetPitch = 0;
-        }
-        targetPitch = THREE.MathUtils.clamp(targetPitch, -maxPitch, maxPitch);
-        this.yaw = this.approach(this.yaw, targetYaw, k, maxStep);
-        this.pitch = this.approach(this.pitch, targetPitch, k, maxStep);
-        // --- Clip-blending layer (Task 8): smoothed camera lock ------------
-        // `ctx.speaking` selects the TARGET lock strength; the lock itself
-        // eases toward it over ~0.4s (RULING R39) rather than switching
-        // instantly, using the same time-based exponential form as `approach`
-        // above (RULING R40, same grounds as R22) — NOT the brief's bare
-        // `const lock = ctx.speaking ? talkLock : idleLock`, which would pop
-        // the lock (and therefore the head pose) in a single frame whenever
-        // speech starts or stops.
-        const idleLockCfg = this.cfg.idleLock ?? 0.9;
-        const talkLockCfg = this.cfg.talkLock ?? 0.95;
-        const lockTarget = ctx.speaking ? talkLockCfg : idleLockCfg;
-        const lockK = 1 - Math.exp(-0.04 * 60 * dt);
-        this.lock = this.approach(this.lock, lockTarget, lockK, Infinity);
-        // `calm`: a focused (highly locked) speaker stops glancing around —
-        // ported from useHeadTracking.ts:527-533. Derived from the SMOOTHED
-        // lock (not raw `ctx.speaking`) so it fades in/out with the lock
-        // transition above rather than popping with it. Applied below to the
-        // idle-drift and gaze-shift amplitudes (RULING R41) — Task 7 deferred
-        // this because it depends on this smoothed lock.
-        const speakBlend = THREE.MathUtils.clamp((this.lock - idleLockCfg) / Math.max(0.001, talkLockCfg - idleLockCfg), 0, 1);
-        const calm = 1 - 0.65 * speakBlend;
-        // --- Aliveness layer (Task 7): idle micro-drift + occasional
-        // look-away gaze shifts. Both are computed here, AFTER the tracking
-        // ease above and BEFORE the head/neck split below, and folded into
-        // local `yaw`/`pitch`/`this.roll` — `this.yaw`/`this.pitch` themselves
-        // stay pure-tracking (Task 6) values, because `direction` below is
-        // published from them and downstream consumers (blink, eye-gaze) want
-        // the deliberate look target, not idle jitter.
-        let driftYaw = 0, driftPitch = 0, driftRoll = 0;
-        if (!ctx.reducedMotion) {
-            this.driftClock += dt * (this.cfg.idleSpeed ?? 1.0);
-            const t = this.driftClock;
-            // `drift()` ported verbatim from useHeadTracking.ts:144-150; the
-            // per-axis seeds (1.0 / 7.3 / 13.1) match lines 556, 558 and 559.
-            driftYaw = this.drift(t, 1.0) * (this.cfg.idleYawAmp ?? 0.03);
-            driftPitch = this.drift(t, 7.3) * (this.cfg.idlePitchAmp ?? 0.02);
-            driftRoll = this.drift(t, 13.1) * (this.cfg.idleRollAmp ?? 0.035);
-            // Occasional look-away, held for a random dwell then re-picked —
-            // ported from useHeadTracking.ts:507-522 (the "gaze" ref). The
-            // countdown-timer bookkeeping here (`this.dwell -= dt`) is
-            // equivalent to the prior art's absolute `nextAt` comparison; the
-            // pick and dwell-duration formulas themselves are verbatim.
-            this.dwell -= dt;
-            if (this.dwell <= 0) {
-                const min = this.cfg.gazeDwellMin ?? 1.4;
-                const max = this.cfg.gazeDwellMax ?? 4.0;
-                this.dwell = min + Math.random() * (max - min);
-                this.shiftTargetYaw = (Math.random() * 2 - 1) * (this.cfg.gazeYawRange ?? 0.15);
-                this.shiftTargetPitch = (Math.random() * 2 - 1) * (this.cfg.gazePitchRange ?? 0.09);
-                this.shiftTargetRoll = (Math.random() * 2 - 1) * (this.cfg.gazeRollRange ?? 0.09);
-            }
-            // Time-based exponential ease toward the gaze-shift target — the
-            // SAME `1 - exp(-rate * 60 * dt)` form as `approach()`'s `k` above
-            // (RULING R22), ported verbatim from useHeadTracking.ts:519-522.
-            // NOT the brief's bare `+= (target - cur) * gazeEase`, which is
-            // frame-rate dependent by construction, same defect R22 already
-            // ruled out for the main tracking ease.
-            const gk = 1 - Math.exp(-(this.cfg.gazeEase ?? 0.035) * 60 * dt);
-            this.shiftYaw += (this.shiftTargetYaw - this.shiftYaw) * gk;
-            this.shiftPitch += (this.shiftTargetPitch - this.shiftPitch) * gk;
-            this.shiftRoll += (this.shiftTargetRoll - this.shiftRoll) * gk;
-        }
-        else {
-            // Reduced motion engaged mid-shift: ease any in-flight look-away back
-            // to centre rather than freezing it there (RULING R34). A hard reset
-            // would snap the offset to zero in a single frame — itself a motion
-            // artifact, and exactly what a reduced-motion user should not get.
-            // Velocity-capped via `approach()` (same k/maxStep as the tracking
-            // ease above) so the decay is smooth and frame-rate independent.
-            this.shiftYaw = this.approach(this.shiftYaw, 0, k, maxStep);
-            this.shiftPitch = this.approach(this.shiftPitch, 0, k, maxStep);
-            this.shiftRoll = this.approach(this.shiftRoll, 0, k, maxStep);
-            this.dwell = 0; // re-enabling picks a fresh target, not a stale one
+        for (const m of [this.headYaw, this.headPitch, this.torsoYaw])
+            m.t += dt;
+        const root = ctx.root;
+        root.updateMatrixWorld(true);
+        this.up.set(0, 1, 0).transformDirection(root.matrixWorld);
+        this.fwd.set(0, 0, 1).transformDirection(root.matrixWorld);
+        head.getWorldPosition(this.headPos);
+        // Steady the head against the clip's fast sway: where a point straight
+        // ahead of the body sits from the clip's head pose, minus its slow (4 s)
+        // average. The idle clips alone swing the face 15–18°.
+        const ahead = this.v.copy(this.headPos).addScaledVector(this.fwd, 10);
+        const sway = this.angleTo(ahead, ctx);
+        if (!this.sway.has)
+            Object.assign(this.sway, { yaw: sway.yaw, pitch: sway.pitch, has: true });
+        const ks = 1 - Math.exp(-dt / 4);
+        this.sway.yaw += (sway.yaw - this.sway.yaw) * ks;
+        this.sway.pitch += (sway.pitch - this.sway.pitch) * ks;
+        const steady = this.cfg.steady ?? 0.8;
+        const steadyYaw = steady * (sway.yaw - this.sway.yaw);
+        const steadyPitch = steady * (sway.pitch - this.sway.pitch);
+        // The pose: torso, then the neck unwinding it, then pitch about the
+        // head's own turned right axis.
+        const torso = valueOf(this.torsoYaw);
+        const headYaw = valueOf(this.headYaw);
+        const headPitch = valueOf(this.headPitch);
+        this.lateral.set(1, 0, 0).transformDirection(root.matrixWorld).applyAxisAngle(this.up, headYaw * DEG);
+        const bones = ctx.rig.bones;
+        this.turn([[bones.spineWaist, 0.4], [bones.spineChest, 0.6]], this.up, torso);
+        this.turn([[bones.neck1, 0.25], [bones.neck2, 0.25], [head, 0.5]], this.up, headYaw - torso + steadyYaw);
+        this.turn([[bones.neck1, 0.2], [bones.neck2, 0.3], [head, 0.5]], this.lateral, -(headPitch + steadyPitch));
+        root.updateMatrixWorld(true);
+        this.rememberOutput();
+        // What to look at: the camera while it is within reach of the body,
+        // otherwise straight ahead (the character turns home).
+        const camera = ctx.camera;
+        let attending = false;
+        if (camera) {
+            camera.getWorldPosition(this.w);
+            this.v.subVectors(this.w, this.headPos).projectOnPlane(this.up);
+            const offBody = this.v.lengthSq() > 1e-12 ? this.v.angleTo(this.fwd) : 0;
+            attending = offBody <= (this.cfg.maxTrackAngle ?? Math.PI / 2);
         }
-        // `calm` (Task 8) scales only the idle-drift and gaze-shift
-        // contributions, never the deliberate tracking (`this.yaw`/`this.pitch`
-        // themselves) — a focused speaker still looks at the viewer, she just
-        // stops the micro-life around it.
-        const yaw = this.yaw + (driftYaw + this.shiftYaw) * calm;
-        const pitch = this.pitch + (driftPitch + this.shiftPitch) * calm;
-        // Head CAPS at the head-only zone; the neck takes a share of the excess.
-        // Ported verbatim from useHeadTracking.ts:450-460 (per RULING R21) — NOT
-        // `headYaw = yaw - neckYaw`, which lets the head keep rotating past
-        // `headOnlyAngle` (scaled down by the neck's share) instead of capping
-        // there outright. That's the exact near-joint-limit pose the 0.44 retune
-        // (see `headOnlyAngle` doc above) was fixing.
-        const headOnly = this.cfg.headOnlyAngle ?? 0.44;
-        const absYaw = Math.abs(yaw);
-        const yawSign = Math.sign(yaw);
-        let headYaw;
-        let neckYaw;
-        if (absYaw <= headOnly) {
-            headYaw = yaw;
-            neckYaw = 0;
+        this.attending = attending;
+        if (attending) {
+            this.planGlances(dt, ctx);
+            this.focus.copy(this.w);
+            if (this.glance.yaw || this.glance.pitch)
+                this.offsetFocus(this.glance.yaw, this.glance.pitch);
         }
         else {
-            const extraAngle = absYaw - headOnly;
-            headYaw = headOnly * yawSign;
-            neckYaw = extraAngle * yawSign * (this.cfg.neckYawFactor ?? 0.75);
+            this.glance.yaw = this.glance.pitch = 0;
+            this.focus.copy(this.headPos).addScaledVector(this.fwd, 10);
         }
-        const headPitch = pitch * (this.cfg.headPitchFactor ?? 0.7);
-        const neckPitch = pitch * (this.cfg.neckPitchFactor ?? 0.3);
-        // Bank the head into the turn: roll proportional to the (capped) head
-        // yaw. Ported from useHeadTracking.ts:560-562
-        // (`bankRoll = -(headYaw + gaze.curYaw * calm) * turnBank`) — NOT a
-        // positive-sign `yaw * turnBank` off the raw, uncapped yaw, which
-        // would keep banking further as the neck (not the head) absorbs
-        // excess yaw beyond `headOnlyAngle`. Per RULING R31, the negative
-        // sign / capped-`headYaw` base above is confirmed. `calm` (Task 8) is
-        // already folded into `headYaw` here (it scaled `driftYaw`/`shiftYaw`
-        // above, before the head/neck split), so `bank` inherits the calming
-        // for free — no separate `* calm` needed on this line.
-        //
-        // Per RULING R30, banking is suppressed under `ctx.reducedMotion`:
-        // it's decorative roll carrying no information, and head tilt is a
-        // recognised vestibular trigger — precisely what reduced-motion
-        // exists to avoid. Tracking yaw/pitch themselves stay (the character
-        // still looks at you; that's functional), only this stylistic roll
-        // is gated. The prior art has no reduced-motion concept, so there is
-        // no upstream formula to defer to here — this gate is judgement, not
-        // a port.
-        const bank = ctx.reducedMotion ? 0 : headYaw * (this.cfg.turnBank ?? 0.2);
-        this.roll = (driftRoll + this.shiftRoll) * calm - bank;
-        // --- Clip-blending layer (Task 8): camera lock + deviation pull-back
-        //
-        // RULING R43: this is a FOUR-part mechanism ported from
-        // useHeadTracking.ts:594-633, not the two-line `max(lock, linear-pull)`
-        // form. Each part exists to stabilise the one after it — the low-pass
-        // stops the boost jittering frame to frame, the boost+lock combination
-        // is what actually blends, and the output cap catches whatever burst
-        // still gets through (e.g. a hitch, or a large one-frame clip jump).
-        //
-        // What the mixer wrote to the head THIS frame, before we touch it —
-        // captured now, since nothing above has written to `head.quaternion`
-        // yet this frame.
-        this.qClip.copy(head.quaternion);
-        setLookQuat(this.qLook, basis, headYaw, headPitch, this.roll);
-        // RULING (2026-09-07 fix wave, C1): compose the look pose ONTO the
-        // bone's own bind-time local rotation, never treat it as absolute — a
-        // real rig's head/neck bones are not identity-oriented in their
-        // parent's frame. Ported from useHeadTracking.ts:590-592
-        // (`lockedHead = copy(restPose.head).multiply(headLook)`). `premultiply`
-        // computes exactly `rest * qLook` in place, no extra scratch quaternion.
-        // Absent rest (a rig this system never resolved) leaves qLook untouched
-        // — falls back to the pre-fix, identity-relative behaviour rather than
-        // throwing.
-        const restHead = ctx.rig.restPose.head;
-        if (restHead)
-            this.qLook.premultiply(restHead);
-        // Part 2 — low-pass the clip pose (tau ~0.2s) BEFORE measuring
-        // deviation from it. Ported from useHeadTracking.ts:594-606; the prior
-        // art's own comment gives the reason verbatim: "Deviation is computed
-        // against the SMOOTHED pose so the boost itself cannot jump within a
-        // frame." First frame: seed directly from the raw clip (no
-        // artificial 0.2s ramp-up from an arbitrary identity start).
-        const kAnim = 1 - Math.exp(-dt / 0.2);
-        if (!this.animHeadHas) {
-            this.animHead.copy(this.qClip);
-            this.animHeadHas = true;
-        }
-        else {
-            this.animHead.slerp(this.qClip, kAnim);
-        }
-        // Part 1 — deviation pull-back as a SMOOTHSTEP boost applied ON TOP OF
-        // the (already time-eased, RULING R39/R40) lock — `lock += (1 - lock)
-        // * boost` — NOT `max(lock, linear-pull)`. Ported verbatim from
-        // useHeadTracking.ts:611-618. `deviationHi` is 0.35 (RULING R38:
-        // verified against `HeadTrackingConfig.DEFAULT_CONFIG.deviationHi`,
-        // useHeadTracking.ts:135 — NOT the stale interface JSDoc's 0.5,
-        // useHeadTracking.ts:67, which the implementation itself does not use).
-        const deviation = this.animHead.angleTo(this.qLook);
-        const lo = this.cfg.deviationLo ?? 0.12;
-        const hi = this.cfg.deviationHi ?? 0.35;
-        const boost = THREE.MathUtils.smoothstep(deviation, lo, hi);
-        const blend = this.lock + (1 - this.lock) * boost;
-        // Blend the LOW-PASSED clip pose (never the raw one) toward the look
-        // pose. Still a `.copy()` onto the bone (never `.multiply()`), per
-        // this class's contract — `.slerp()` interpolates, it doesn't compose
-        // with the bone's existing rotation the way `.multiply()` would.
-        this.qOut.copy(this.animHead).slerp(this.qLook, blend);
-        // Part 3 — output velocity cap, applied AFTER the blend. Ported from
-        // useHeadTracking.ts:625-631. The `Math.min(dt, 0.02)` is load-bearing,
-        // not incidental: the prior art's own comment records the exact bug it
-        // fixes — "on a hitched frame the window would otherwise expand and
-        // admit the whole burst as one visible jump (measured 1.6°-in-one-frame
-        // spikes exactly on dt≈21ms frames)." 55°/s sits above this class's own
-        // normal motion but compresses a fast clip burst across several
-        // frames. Skipped on the very first written frame (no prior output to
-        // rotate from).
-        const outCap = (55 * Math.PI / 180) * Math.min(dt, 0.02);
-        if (this.lastOutHas) {
-            head.quaternion.copy(this.lastOutHead).rotateTowards(this.qOut, outCap);
-        }
-        else {
-            head.quaternion.copy(this.qOut);
+        const off = this.angleTo(this.focus, ctx);
+        this.pursue(dt, off);
+        this.turnTorso(dt, off);
+        this.publish(ctx);
+    }
+    /** Smooth pursuit beyond the eyes' zone, and a quick shift on a large jump. */
+    pursue(dt, now) {
+        // Against where the head is already going, not where it is mid-move: a
+        // shift in flight has already claimed part of the gap, and pursuing that
+        // part again overshot the target (35 deg for a camera at 30, which then
+        // held the neck past the torso trigger).
+        const off = {
+            yaw: now.yaw - (this.headYaw.to - valueOf(this.headYaw)),
+            pitch: now.pitch - (this.headPitch.to - valueOf(this.headPitch)),
+        };
+        const zone = this.cfg.eyeZone ?? { yaw: 5, pitch: 4 };
+        const shiftZone = this.cfg.shiftZone ?? { yaw: 18, pitch: 12 };
+        const limit = this.cfg.headLimit ?? { yaw: 45, pitch: 25 };
+        const kf = 1 - Math.exp(-dt / (this.cfg.followTime ?? 0.45));
+        const beyond = (v, z) => v - THREE.MathUtils.clamp(v, -z, z);
+        const torsoGoal = this.torsoYaw.to;
+        const fy = THREE.MathUtils.clamp(beyond(off.yaw, zone.yaw) * kf, torsoGoal - limit.yaw - this.headYaw.to, torsoGoal + limit.yaw - this.headYaw.to);
+        const fp = THREE.MathUtils.clamp(beyond(off.pitch, zone.pitch) * kf, -limit.pitch - this.headPitch.to, limit.pitch - this.headPitch.to);
+        this.headYaw.from += fy;
+        this.headYaw.to += fy;
+        this.headPitch.from += fp;
+        this.headPitch.to += fp;
+        const outside = Math.abs(off.yaw) > shiftZone.yaw || Math.abs(off.pitch) > shiftZone.pitch;
+        this.outside = outside ? this.outside + dt : 0;
+        if (this.outside > 0.06 && done(this.headYaw) && done(this.headPitch)) {
+            const yawNow = valueOf(this.headYaw);
+            const pitchNow = valueOf(this.headPitch);
+            const torsoNow = this.torsoYaw.to;
+            // `off` was measured before this frame's pursuit step, which yawNow
+            // already includes; count that step once (counted twice, where the head
+            // settled depended on the frame rate: 23.3 deg at 30 fps, 22.3 at 120).
+            const remainingYaw = off.yaw - fy;
+            const remainingPitch = off.pitch - fp;
+            const yaw = THREE.MathUtils.clamp(yawNow + remainingYaw - Math.sign(remainingYaw) * 3, torsoNow - limit.yaw, torsoNow + limit.yaw);
+            const pitch = THREE.MathUtils.clamp(pitchNow + remainingPitch - Math.sign(remainingPitch) * 2, -limit.pitch, limit.pitch);
+            const dur = 0.22 + Math.hypot(yaw - yawNow, pitch - pitchNow) / 140;
+            this.headYaw = { from: yawNow, to: yaw, t: 0, dur, delay: 0.08 };
+            this.headPitch = { from: pitchNow, to: pitch, t: 0, dur, delay: 0.08 };
+            this.outside = 0;
         }
-        this.lastOutHead.copy(head.quaternion);
-        this.lastOutHas = true;
-        // RULING R61: the neck bones blend with their own clip pose too — the
-        // brief (and the first cut of this class) applied the clip-blend
-        // mechanism to the HEAD only, which meant an authored clip's neck
-        // motion was discarded outright every frame (a hard `.copy()`
-        // override, never blended). The prior art low-passes `anim.neck1`/
-        // `anim.neck2` alongside `anim.head` for exactly this reason
-        // (useHeadTracking.ts:598-606) and blends both necks with the SAME
-        // head-derived blend fraction (`blend`, computed above from `lock` and
-        // the head's own deviation boost) — NOT a separately computed per-neck
-        // deviation (useHeadTracking.ts:644,
-        // 663). `this.qClip`/`this.qLook` are reused as scratch here (the
-        // head's use of them above is finished for this frame) — neck1 is
-        // fully written before neck2 starts, so this sequential reuse is
-        // safe and allocation-free.
-        if (neck1) {
-            this.qClip.copy(neck1.quaternion);
-            if (!this.animNeck1Has) {
-                this.animNeck1.copy(this.qClip);
-                this.animNeck1Has = true;
-            }
-            else {
-                this.animNeck1.slerp(this.qClip, kAnim);
-            }
-            setLookQuat(this.qLook, basis, neckYaw * 0.5, neckPitch * 0.5, 0);
-            // C1: compose onto neck_01's own rest pose — see the head's identical
-            // comment above.
-            const restNeck1 = ctx.rig.restPose.neck1;
-            if (restNeck1)
-                this.qLook.premultiply(restNeck1);
-            this.qOutNeck.copy(this.animNeck1).slerp(this.qLook, blend);
-            if (this.lastOutNeck1Has) {
-                neck1.quaternion.copy(this.lastOutNeck1).rotateTowards(this.qOutNeck, outCap);
-            }
-            else {
-                neck1.quaternion.copy(this.qOutNeck);
-            }
-            this.lastOutNeck1.copy(neck1.quaternion);
-            this.lastOutNeck1Has = true;
+    }
+    /** The torso comes round after the neck has been twisted far for a while, and drifts home. */
+    turnTorso(dt, off) {
+        if (this.cfg.torso === false)
+            return;
+        const trigger = this.cfg.torso?.trigger ?? 32;
+        const hold = this.cfg.torso?.hold ?? 0.6;
+        const limit = this.cfg.torso?.limit ?? 30;
+        const twist = valueOf(this.headYaw) - valueOf(this.torsoYaw);
+        this.twisted = Math.abs(twist) > trigger ? this.twisted + dt : 0;
+        if (!done(this.torsoYaw))
+            return;
+        let goal = null;
+        if (this.twisted > hold)
+            goal = valueOf(this.headYaw) - Math.sign(twist) * 12;
+        else if (Math.abs(valueOf(this.headYaw) + off.yaw) < 15 && Math.abs(valueOf(this.torsoYaw)) > 2)
+            goal = 0;
+        if (goal === null)
+            return;
+        goal = THREE.MathUtils.clamp(goal, -limit, limit);
+        const size = Math.abs(goal - valueOf(this.torsoYaw));
+        if (size > 1)
+            this.torsoYaw = { from: valueOf(this.torsoYaw), to: goal, t: 0, dur: 0.8 + size / 45, delay: 0.25 };
+        this.twisted = 0;
+    }
+    /** Occasional short glances away while listening. */
+    planGlances(dt, ctx) {
+        const g = this.glance;
+        if (this.cfg.lookAways === false || ctx.reducedMotion || ctx.speaking) {
+            g.yaw = g.pitch = 0;
+            g.left = 0;
+            return;
         }
-        if (neck2) {
-            this.qClip.copy(neck2.quaternion);
-            if (!this.animNeck2Has) {
-                this.animNeck2.copy(this.qClip);
-                this.animNeck2Has = true;
-            }
-            else {
-                this.animNeck2.slerp(this.qClip, kAnim);
-            }
-            setLookQuat(this.qLook, basis, neckYaw * 0.5, neckPitch * 0.5, 0);
-            // C1: compose onto neck_02's own rest pose — see the head's identical
-            // comment above.
-            const restNeck2 = ctx.rig.restPose.neck2;
-            if (restNeck2)
-                this.qLook.premultiply(restNeck2);
-            this.qOutNeck.copy(this.animNeck2).slerp(this.qLook, blend);
-            if (this.lastOutNeck2Has) {
-                neck2.quaternion.copy(this.lastOutNeck2).rotateTowards(this.qOutNeck, outCap);
-            }
-            else {
-                neck2.quaternion.copy(this.qOutNeck);
-            }
-            this.lastOutNeck2.copy(neck2.quaternion);
-            this.lastOutNeck2Has = true;
+        if (g.left > 0) {
+            g.left -= dt;
+            if (g.left <= 0)
+                g.yaw = g.pitch = 0;
+            return;
         }
-        // Publish normalised direction for blink (Task 5) and eye-gaze (Task 9).
-        const h = THREE.MathUtils.clamp(this.yaw / maxTrack, -1, 1);
-        const v = THREE.MathUtils.clamp(-this.pitch / maxPitch, -1, 1);
+        g.next -= dt;
+        if (g.next > 0)
+            return;
+        const s = Math.random() < 0.5 ? -1 : 1;
+        g.yaw = s * (6 + Math.random() * 6);
+        g.pitch = (Math.random() * 2 - 1) * 4;
+        g.left = 0.6 + Math.random() * 0.6;
+        g.next = 3 + Math.random() * 4;
+    }
+    /** Rotate `focus` about the head by yaw (about up) and pitch (about right), degrees. */
+    offsetFocus(yaw, pitch) {
+        const d = this.v.subVectors(this.focus, this.headPos);
+        d.applyAxisAngle(this.up, yaw * DEG);
+        const side = this.w.crossVectors(d, this.up).normalize();
+        if (side.lengthSq() > 0)
+            d.applyAxisAngle(side, pitch * DEG);
+        this.focus.copy(this.headPos).add(d);
+    }
+    /**
+     * Where `target` (world) sits from the face now: yaw (+ toward the
+     * character's left) and pitch (+ up), degrees.
+     */
+    angleTo(target, ctx) {
+        if (this.eyes)
+            return this.eyes.angleTo(target);
+        // Without measurable eyes: the rig basis, whose axes are the head bone's
+        // own (so they turn with it). On convai-mha-1 `right` is the character's
+        // left; see the profile.
+        const head = ctx.rig.bones.head;
+        head.updateWorldMatrix(true, false);
+        const local = this.v.copy(target).applyMatrix4(this.m.copy(head.matrixWorld).invert());
+        const basis = ctx.rig.profile.basis;
+        const x = local.dot(basis.right);
+        const y = local.dot(basis.up);
+        const z = local.dot(basis.fwd);
+        return { yaw: Math.atan2(x, z) / DEG, pitch: Math.atan2(y, Math.hypot(x, z)) / DEG };
+    }
+    publish(ctx) {
+        const maxTrack = this.cfg.maxTrackAngle ?? Math.PI / 2;
+        const limit = this.cfg.headLimit ?? { yaw: 45, pitch: 25 };
+        const h = THREE.MathUtils.clamp((valueOf(this.headYaw) * DEG) / maxTrack, -1, 1);
+        const v = THREE.MathUtils.clamp(valueOf(this.headPitch) / limit.pitch, -1, 1);
         this.direction.horizontal = h;
         this.direction.vertical = v;
         this.direction.left.horizontal = h;
         this.direction.left.vertical = v;
         this.direction.right.horizontal = h;
         this.direction.right.vertical = v;
-        // The EYES need a different quantity, measured in WORLD space from the
-        // head's ACTUAL orientation after the writes above — not from
-        // `this.yaw`/`this.pitch`, which are bone-space CORRECTION angles.
-        //
-        // Those correction angles also carry the head's own rest tilt and the
-        // neck chain's orientation. On a rig whose bones rest at identity the
-        // two coincide, which is why this was invisible in every test here. On a
-        // real MetaHuman it is badly wrong: measured in a browser on the live
-        // convai-mha-1 body, a camera 3cm above the head (true angle 0.48°)
-        // published vertical = 0.456, 42x too large, because the head bone rests
-        // ~11.5° tilted and the solve must undo that before it aims anywhere.
-        // EyeGazeSystem read that as "looking up at 46% of maximum" and pinned
-        // eyeLookUp at 0.20 — the eyes never tracked, they were stuck up, and a
-        // character looking straight at you appeared to stare over your shoulder.
-        //
-        // `direction` above is deliberately NOT changed: BlinkSystem wants the
-        // head's deflection from neutral (lids follow the head), and two tests
-        // pin that meaning. One field cannot serve both, so the eyes get their
-        // own. `getWorldQuaternion` refreshes the matrix chain, so this reads
-        // this frame's pose rather than last frame's.
-        head.getWorldQuaternion(this.qHeadW);
-        head.getWorldPosition(this.vHead);
-        ctx.camera.getWorldPosition(this.vTarget);
-        this.vAim.subVectors(this.vTarget, this.vHead);
-        if (this.vAim.lengthSq() > 1e-12) {
-            this.vAim.normalize();
-            this.vFwdW.copy(basis.fwd).applyQuaternion(this.qHeadW);
-            this.vRightW.copy(basis.right).applyQuaternion(this.qHeadW);
-            this.vUpW.copy(basis.up).applyQuaternion(this.qHeadW);
-            const aimR = this.vAim.dot(this.vRightW);
-            const aimU = this.vAim.dot(this.vUpW);
-            const aimF = this.vAim.dot(this.vFwdW);
-            this.residual.horizontal = THREE.MathUtils.clamp(Math.atan2(aimR, aimF) / maxTrack, -1, 1);
-            this.residual.vertical = THREE.MathUtils.clamp(Math.atan2(aimU, Math.hypot(aimR, aimF)) / maxPitch, -1, 1);
+        // What the eyes still have to cover, normalised: for the fallback eye path.
+        const off = this.angleTo(this.focus, ctx);
+        this.residual.horizontal = THREE.MathUtils.clamp((off.yaw * DEG) / maxTrack, -1, 1);
+        this.residual.vertical = THREE.MathUtils.clamp((off.pitch * DEG) / (Math.PI / 4), -1, 1);
+    }
+    /** Bones the clip did not rewrite this frame still hold our output: put the clip pose back. */
+    restoreClipPose(ctx) {
+        const b = ctx.rig.bones;
+        for (const bone of [b.spineWaist, b.spineChest, b.neck1, b.neck2, b.head]) {
+            if (!bone)
+                continue;
+            const was = this.out.get(bone);
+            if (was && was.equals(bone.quaternion))
+                bone.quaternion.copy(this.base.get(bone));
+            else
+                this.base.set(bone, (this.base.get(bone) ?? new THREE.Quaternion()).copy(bone.quaternion));
+        }
+    }
+    rememberOutput() {
+        for (const bone of this.base.keys())
+            this.out.set(bone, (this.out.get(bone) ?? new THREE.Quaternion()).copy(bone.quaternion));
+    }
+    /** Rotate a chain of bones by `deg` about a world axis, shared by weight. */
+    turn(chain, worldAxis, deg) {
+        if (Math.abs(deg) < 1e-4)
+            return;
+        for (const [bone, weight] of chain) {
+            if (!bone?.parent)
+                continue;
+            bone.parent.getWorldQuaternion(this.pq);
+            const local = this.w.copy(worldAxis).applyQuaternion(this.pq.invert()).normalize();
+            bone.quaternion.premultiply(this.q.setFromAxisAngle(local, deg * weight * DEG));
+            bone.updateMatrixWorld(true);
         }
     }
 }