@convai/embody 1.0.1-beta.0 → 1.1.0-beta.0

package/dist/motion/footLock.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Foot locking: a planted foot stays where it was put while the body sways
+ * above it.
+ *
+ * Idle and talking clips sway the hips, and with the body held in place the
+ * planted feet skate along the floor (~19 cm/s measured with jointQA on a
+ * convai-mha-1 body). Each planted foot is held at its lock point horizontally
+ * by a two-bone leg IK (thigh, calf); the clip keeps the foot's height and
+ * orientation. A foot that lifts or moves on purpose — a step — is released
+ * and blended back to the clip. Engaging and releasing run on minimum-jerk
+ * curves, so neither is a pop.
+ *
+ * A straight leg cannot reach a lock the hips have swayed away from; the hips
+ * are lowered by the shortfall (a few millimetres, capped) so the knee takes
+ * it instead of the foot dragging.
+ *
+ * Stage 4, after gaze and breathing. Units are world metres (the body has been
+ * scaled to metres by then). The values are the coffee-shop studio's, tuned
+ * with its joint QA.
+ */
+import * as THREE from 'three';
+import type { FrameContext, System } from '../character/pipeline.js';
+export interface FootLockConfig {
+    /** Static gate. Default `true`. */
+    enabled?: boolean;
+    /** A foot this far (m) above its resting height counts as lifted. Default 0.03. */
+    liftHeight?: number;
+    /** A foot the clip moves faster than this (m/s) is stepping. Default 0.3. */
+    stepSpeed?: number;
+    /** Seconds to engage or release a lock. Default 0.4. */
+    blendTime?: number;
+    /** Most the hips are lowered to let a straight leg reach its lock, m. Default 0.015. */
+    maxDrop?: number;
+}
+export declare class FootLockSystem implements System {
+    private readonly cfg;
+    readonly stage: 4;
+    private legs;
+    private drop;
+    private readonly clipPose;
+    private readonly written;
+    private readonly a;
+    private readonly b;
+    private readonly c;
+    private readonly p;
+    private readonly q;
+    private readonly q2;
+    constructor(cfg?: FootLockConfig);
+    /** Planted legs, for tests and debugging. */
+    get locks(): {
+        lock: THREE.Vector3 | null;
+        weight: number;
+    }[];
+    /**
+     * Put back the clip pose on leg bones this system wrote and the mixer is not
+     * about to rewrite (three's mixer skips a bone whose blended value did not
+     * change, and the IK would then be solved again on top of itself).
+     */
+    beforeMixer(): void;
+    update(dt: number, ctx: FrameContext): void;
+    private findLegs;
+    private copyInto;
+    /** Two-bone IK: thigh and calf turn so the foot reaches `goal`, the knee bending forward. */
+    private solve;
+    /** Apply a world-space rotation to a bone, expressed in its parent's frame. */
+    private rotateWorld;
+}

package/dist/motion/footLock.js

@@ -0,0 +1,176 @@
+/**
+ * Foot locking: a planted foot stays where it was put while the body sways
+ * above it.
+ *
+ * Idle and talking clips sway the hips, and with the body held in place the
+ * planted feet skate along the floor (~19 cm/s measured with jointQA on a
+ * convai-mha-1 body). Each planted foot is held at its lock point horizontally
+ * by a two-bone leg IK (thigh, calf); the clip keeps the foot's height and
+ * orientation. A foot that lifts or moves on purpose — a step — is released
+ * and blended back to the clip. Engaging and releasing run on minimum-jerk
+ * curves, so neither is a pop.
+ *
+ * A straight leg cannot reach a lock the hips have swayed away from; the hips
+ * are lowered by the shortfall (a few millimetres, capped) so the knee takes
+ * it instead of the foot dragging.
+ *
+ * Stage 4, after gaze and breathing. Units are world metres (the body has been
+ * scaled to metres by then). The values are the coffee-shop studio's, tuned
+ * with its joint QA.
+ */
+import * as THREE from 'three';
+import { minJerk } from './gaze.js';
+/** A forward knee bends negatively about (hip→foot × body forward). */
+const KNEE = -1;
+/** A held lock follows the clip's own slow foot drift at this speed, m/s (below any visible slide). */
+const FOLLOW = 0.01;
+export class FootLockSystem {
+    constructor(cfg = {}) {
+        this.cfg = cfg;
+        this.stage = 4;
+        this.legs = null;
+        this.drop = 0;
+        this.clipPose = new Map();
+        this.written = new Map();
+        this.a = new THREE.Vector3();
+        this.b = new THREE.Vector3();
+        this.c = new THREE.Vector3();
+        this.p = new THREE.Vector3();
+        this.q = new THREE.Quaternion();
+        this.q2 = new THREE.Quaternion();
+    }
+    /** Planted legs, for tests and debugging. */
+    get locks() {
+        return (this.legs ?? []).map((l) => ({ lock: l.lock, weight: l.w }));
+    }
+    /**
+     * Put back the clip pose on leg bones this system wrote and the mixer is not
+     * about to rewrite (three's mixer skips a bone whose blended value did not
+     * change, and the IK would then be solved again on top of itself).
+     */
+    beforeMixer() {
+        for (const [bone, clip] of this.clipPose)
+            if (this.written.get(bone)?.equals(bone.quaternion))
+                bone.quaternion.copy(clip);
+    }
+    update(dt, ctx) {
+        if (this.cfg.enabled === false || dt <= 0)
+            return;
+        this.legs ??= this.findLegs(ctx.rig);
+        if (!this.legs.length)
+            return;
+        dt = Math.min(dt, 0.1);
+        const root = ctx.root;
+        const liftH = this.cfg.liftHeight ?? 0.03;
+        const stepV = this.cfg.stepSpeed ?? 0.3;
+        root.updateMatrixWorld(true);
+        // Knee slack for a leg too straight to reach its lock.
+        let need = 0;
+        for (const l of this.legs) {
+            if (!l.lock || l.w < 0.05)
+                continue;
+            const A = l.thigh.getWorldPosition(this.a), B = l.calf.getWorldPosition(this.b), C = l.foot.getWorldPosition(this.c);
+            const reach = A.distanceTo(B) + B.distanceTo(C);
+            need = Math.max(need, (A.distanceTo(this.p.set(l.lock.x, C.y, l.lock.z)) - reach * 0.995 + 0.003) * l.w);
+        }
+        const goalDrop = THREE.MathUtils.clamp(need, 0, this.cfg.maxDrop ?? 0.015);
+        this.drop += (goalDrop - this.drop) * (1 - Math.exp(-dt / 0.15));
+        if (this.drop > 1e-5) {
+            const s = root.parent ? root.parent.getWorldScale(this.p).y : 1;
+            root.position.y -= this.drop / s;
+            root.updateMatrixWorld(true);
+        }
+        const fwd = this.p.set(0, 0, 1).applyQuaternion(root.getWorldQuaternion(this.q)).clone();
+        for (const l of this.legs) {
+            for (const bone of [l.thigh, l.calf, l.foot])
+                this.copyInto(this.clipPose, bone);
+            const p = l.foot.getWorldPosition(new THREE.Vector3());
+            const raw = l.prev ? Math.hypot(p.x - l.prev.x, p.z - l.prev.z) / dt : 0;
+            l.v += (raw - l.v) * (1 - Math.exp(-dt / 0.04));
+            l.prev = p.clone();
+            // The lowest the foot has been, slowly forgiving.
+            l.restY = l.restY === null ? p.y : Math.min(l.restY + dt * 0.01, p.y);
+            // Hysteresis: plant below the thresholds, release only clearly above.
+            const planted = l.lock
+                ? p.y < l.restY + liftH * 1.6 && l.v < stepV * 1.4
+                : p.y < l.restY + liftH && l.v < stepV;
+            if (planted && !l.lock)
+                l.lock = p.clone();
+            if (l.lock) {
+                // Follow the clip's own slow drift, so the IK never holds a foot far from it.
+                const dx = p.x - l.lock.x, dz = p.z - l.lock.z, dist = Math.hypot(dx, dz);
+                if (dist > 1e-6) {
+                    const step = Math.min(dist, FOLLOW * dt);
+                    l.lock.x += (dx / dist) * step;
+                    l.lock.z += (dz / dist) * step;
+                }
+            }
+            const target = planted ? 1 : 0;
+            if (target !== l.wTo) {
+                l.wFrom = l.w;
+                l.wTo = target;
+                l.wT = 0;
+            }
+            l.wT = Math.min(1, l.wT + dt / (this.cfg.blendTime ?? 0.4));
+            l.w = l.wFrom + (l.wTo - l.wFrom) * minJerk(l.wT);
+            if (!planted && l.w < 0.01)
+                l.lock = null;
+            if (!l.lock || l.w < 0.001)
+                continue;
+            // Goal: the lock horizontally (by its weight), the clip's own height.
+            const goal = new THREE.Vector3(l.lock.x, p.y, l.lock.z).lerp(p, 1 - l.w);
+            if (goal.distanceToSquared(p) < 1e-10)
+                continue;
+            const footQ = l.foot.getWorldQuaternion(new THREE.Quaternion());
+            this.solve(l, goal, fwd);
+            // The foot keeps the world orientation the clip gave it.
+            l.foot.quaternion.copy(l.foot.parent.getWorldQuaternion(this.q).invert().multiply(footQ));
+            l.foot.updateMatrixWorld(true);
+            for (const bone of [l.thigh, l.calf, l.foot])
+                this.copyInto(this.written, bone);
+        }
+    }
+    findLegs(rig) {
+        const b = rig.bones;
+        const legs = [];
+        for (const [thigh, calf, foot] of [[b.thighL, b.calfL, b.footL], [b.thighR, b.calfR, b.footR]]) {
+            if (thigh && calf && foot)
+                legs.push({ thigh, calf, foot, lock: null, w: 0, wFrom: 0, wTo: 0, wT: 1, v: 0, restY: null, prev: null });
+        }
+        return legs;
+    }
+    copyInto(map, bone) {
+        let q = map.get(bone);
+        if (!q)
+            map.set(bone, (q = new THREE.Quaternion()));
+        q.copy(bone.quaternion);
+    }
+    /** Two-bone IK: thigh and calf turn so the foot reaches `goal`, the knee bending forward. */
+    solve(l, goal, fwd) {
+        const A = l.thigh.getWorldPosition(this.a), B = l.calf.getWorldPosition(this.b), C = l.foot.getWorldPosition(this.c);
+        const l1 = A.distanceTo(B), l2 = B.distanceTo(C);
+        const d = THREE.MathUtils.clamp(A.distanceTo(goal), Math.abs(l1 - l2) + 1e-4, l1 + l2 - 1e-4);
+        // The knee hinges across the body's forward direction: taken from the
+        // leg's own shape, a nearly straight leg's cross product was tiny and
+        // noisy, flipped sign, and the knee solved to the wrong side for a frame.
+        const n = C.clone().sub(A).normalize().cross(fwd);
+        if (n.lengthSq() < 1e-8)
+            return;
+        n.normalize();
+        const u1 = B.clone().sub(A).normalize(), u2 = C.clone().sub(B).normalize();
+        const cur = Math.atan2(u1.clone().cross(u2).dot(n), u1.dot(u2));
+        const want = KNEE * (Math.PI - Math.acos(THREE.MathUtils.clamp((l1 * l1 + l2 * l2 - d * d) / (2 * l1 * l2), -1, 1)));
+        this.rotateWorld(l.calf, this.q2.setFromAxisAngle(n, want - cur));
+        l.thigh.updateMatrixWorld(true);
+        const from = l.foot.getWorldPosition(new THREE.Vector3()).sub(A).normalize();
+        const to = goal.clone().sub(A).normalize();
+        this.rotateWorld(l.thigh, this.q2.setFromUnitVectors(from, to));
+    }
+    /** Apply a world-space rotation to a bone, expressed in its parent's frame. */
+    rotateWorld(bone, qWorld) {
+        const parentQ = bone.parent.getWorldQuaternion(new THREE.Quaternion());
+        const world = parentQ.clone().multiply(bone.quaternion);
+        bone.quaternion.copy(parentQ.invert().multiply(qWorld.clone().multiply(world)));
+        bone.updateMatrixWorld(true);
+    }
+}

package/dist/motion/gaze.d.ts

@@ -1,220 +1,175 @@
+import * as THREE from 'three';
 import type { FrameContext, System } from '../character/pipeline.js';
 import type { EyeGazeDirection, 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.
+ * Gaze the way people do it: eyes, then neck, then body.
+ *
+ *  · The eyes take every small change on their own (EyeGazeSystem aims each
+ *    one at `focus`), so the head is not moved by a few degrees of camera.
+ *  · Beyond that the head follows smoothly, lagging the eyes (smooth pursuit),
+ *    so a gliding camera is tracked without the head holding and then
+ *    snapping. A sudden large jump gets a quick eye-led head shift on a
+ *    minimum-jerk curve, ~80 ms after the eyes, stopping a few degrees short
+ *    for the eyes to finish.
+ *  · The torso turns only once the head has had to twist far off the body for
+ *    a moment; it turns slowly while the neck unwinds by the same amount, so
+ *    the head stays on target. When the target comes back toward the front,
+ *    the torso drifts home the same way.
+ *  · While fixating, most of the clip's fast head sway is cancelled (people
+ *    hold the head still while looking at something); the slow part of it,
+ *    and everything below the neck, plays as authored.
+ *
+ * Every turn is ADDED to the clip's pose, so idle sway and talking gestures
+ * stay alive. A bone the clip did not key this frame still holds last
+ * frame's output; that is detected and the clip pose restored before adding,
+ * so nothing accumulates.
+ *
+ * Angles are measured from the eyes' own neutral frame (EyeAim, from the
+ * body's eye geometry) where the body allows, otherwise from the rig basis.
+ * The values are the coffee-shop studio's, tuned on camera.
  */
 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). */
+    /** Static construction-time gate. Live control is `setEnabled()`. */
+    enabled?: boolean;
+    /** Beyond this angle (rad) off the body's front the character stops attending and turns home. Default PI/2. */
     maxTrackAngle?: number;
-    /** Vertical (pitch) clamp, radians. */
+    /** Changes inside this (degrees) are left to the eyes. Default 5 yaw, 4 pitch. */
+    eyeZone?: {
+        yaw: number;
+        pitch: number;
+    };
+    /** A target this far (degrees) outside the face gets a quick head shift. Default 18 yaw, 12 pitch. */
+    shiftZone?: {
+        yaw: number;
+        pitch: number;
+    };
+    /** Seconds the head lags the eyes in smooth pursuit. Default 0.45. */
+    followTime?: number;
+    /** How far the head and neck turn from the body, degrees. Default 45 yaw, 25 pitch. */
+    headLimit?: {
+        yaw: number;
+        pitch: number;
+    };
+    /**
+     * Torso turn: after the head has been twisted past `trigger` degrees for
+     * `hold` seconds the torso turns, at most `limit` degrees. `false` keeps the
+     * torso out of it. Default `{ trigger: 32, hold: 0.6, limit: 30 }`.
+     */
+    torso?: false | {
+        trigger?: number;
+        hold?: number;
+        limit?: number;
+    };
+    /** Share of the clip's fast head sway cancelled while fixating, 0–1. Default 0.8. */
+    steady?: number;
+    /**
+     * Occasional short glances away while listening (never while speaking or
+     * under reduced motion). Default `true`.
+     */
+    lookAways?: boolean;
+    /** @deprecated Ignored since 1.1: the head is driven by pursuit and shifts, see `eyeZone`/`followTime`. */
+    headOnlyAngle?: number;
+    /** @deprecated Ignored since 1.1; see `headLimit.pitch`. */
     maxPitchAngle?: number;
-    /** Ease rate (per-second, before the `* 60` time-based conversion in
-     *  `update()`) toward the target yaw/pitch. Velocity-capped — see
-     *  `update()`. */
+    /** @deprecated Ignored since 1.1; see `followTime`. */
     lerpSpeed?: number;
-    /** Share of pitch applied to the head. */
+    /** @deprecated Ignored since 1.1. */
     headPitchFactor?: number;
-    /** Share of pitch applied to each neck bone. */
+    /** @deprecated Ignored since 1.1. */
     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. */
+    /** @deprecated Ignored since 1.1. */
     neckYawFactor?: number;
-    /** Idle micro-drift amplitude on yaw, radians. */
+    /** @deprecated Ignored since 1.1: the clip's own motion carries the head's life. */
     idleYawAmp?: number;
-    /** Idle micro-drift amplitude on pitch, radians. */
+    /** @deprecated Ignored since 1.1. */
     idlePitchAmp?: number;
-    /** Idle micro-drift amplitude on roll, radians. */
+    /** @deprecated Ignored since 1.1. */
     idleRollAmp?: number;
-    /** Time multiplier for the idle-drift clock. */
+    /** @deprecated Ignored since 1.1. */
     idleSpeed?: number;
-    /** Roll added per radian of (capped) head yaw — banks the head into a
-     *  turn. */
+    /** @deprecated Ignored since 1.1. */
     turnBank?: number;
-    /** Max yaw (radians) of an occasional look-away gaze shift. */
+    /** @deprecated Ignored since 1.1; see `lookAways`. */
     gazeYawRange?: number;
-    /** Max pitch (radians) of a gaze shift. */
+    /** @deprecated Ignored since 1.1; see `lookAways`. */
     gazePitchRange?: number;
-    /** Max roll (radians) of a gaze shift. */
+    /** @deprecated Ignored since 1.1. */
     gazeRollRange?: number;
-    /** Ease rate (per-second, before the `* 60` time-based conversion) the
-     *  gaze-shift offset eases toward its target at. */
+    /** @deprecated Ignored since 1.1. */
     gazeEase?: number;
-    /** Minimum seconds a gaze-shift target is held before re-picking. */
+    /** @deprecated Ignored since 1.1. */
     gazeDwellMin?: number;
-    /** Maximum seconds a gaze-shift target is held before re-picking. */
+    /** @deprecated Ignored since 1.1. */
     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. */
+    /** @deprecated Ignored since 1.1: turns are added to the clip, never locked over it. */
     idleLock?: number;
-    /** Camera-lock strength while `ctx.speaking` — focused on the viewer. */
+    /** @deprecated Ignored since 1.1. */
     talkLock?: number;
-    /** Clip-deviation (radians, angle between the clip's head pose and the
-     *  look pose) below which the clip flows through untouched. */
+    /** @deprecated Ignored since 1.1. */
     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`. */
+    /** @deprecated Ignored since 1.1. */
     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.
- */
+/** Minimum-jerk ease: 0→1 with zero velocity and acceleration at both ends. */
+export declare const minJerk: (s: number) => number;
 export declare class GazeSystem implements System, GazeSource {
     private readonly cfg;
     readonly stage: 2;
     readonly direction: GazeDirection;
-    /** World-space angle still between the head's forward and the target. */
     readonly residual: EyeGazeDirection;
+    /** See `GazeSource.attending`. */
+    attending: boolean;
+    /** The world point the character is looking at this frame; see `GazeSource.focus`. */
+    readonly focus: THREE.Vector3;
     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;
-    private readonly vAim;
-    private readonly vFwdW;
-    private readonly vRightW;
-    private readonly vUpW;
-    private readonly qHeadW;
-    private readonly qRestInv;
-    /** 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;
+    private eyes;
+    private headYaw;
+    private headPitch;
+    private torsoYaw;
+    private outside;
+    private twisted;
+    private readonly sway;
+    private glance;
+    private readonly base;
+    private readonly out;
+    private readonly q;
+    private readonly pq;
+    private readonly up;
+    /** The body's lateral axis turned with the head: pitch nods about it. */
+    private readonly lateral;
+    private readonly fwd;
+    private readonly v;
+    private readonly w;
+    private readonly headPos;
+    private readonly m;
+    private readonly qHead;
     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.
+     * 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.
      */
-    private approach;
+    beforeMixer(): void;
+    update(dt: number, ctx: FrameContext): void;
+    /** Smooth pursuit beyond the eyes' zone, and a quick shift on a large jump. */
+    private pursue;
+    /** The torso comes round after the neck has been twisted far for a while, and drifts home. */
+    private turnTorso;
+    /** Occasional short glances away while listening. */
+    private planGlances;
+    /** Rotate `focus` about the head by yaw (about up) and pitch (about right), degrees. */
+    private offsetFocus;
     /**
-     * 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.
+     * Where `target` (world) sits from the face now: yaw (+ toward the
+     * character's left) and pitch (+ up), degrees.
      */
-    private drift;
-    update(dt: number, ctx: FrameContext): void;
+    private angleTo;
+    private publish;
+    /** Bones the clip did not rewrite this frame still hold our output: put the clip pose back. */
+    private restoreClipPose;
+    private rememberOutput;
+    /** Rotate a chain of bones by `deg` about a world axis, shared by weight. */
+    private turn;
 }