@convai/embody 0.1.0

package/dist/motion/gaze.js

@@ -0,0 +1,467 @@
+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.
+ */
+export class GazeSystem {
+    constructor(cfg = {}) {
+        this.cfg = cfg;
+        this.stage = 2;
+        this.direction = {
+            left: { horizontal: 0, vertical: 0 },
+            right: { horizontal: 0, vertical: 0 },
+            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();
+        /** 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;
+        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.
+     */
+    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);
+    }
+    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)
+            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.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;
+            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);
+        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
+        }
+        // `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;
+        }
+        else {
+            const extraAngle = absYaw - headOnly;
+            headYaw = headOnly * yawSign;
+            neckYaw = extraAngle * yawSign * (this.cfg.neckYawFactor ?? 0.75);
+        }
+        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);
+        }
+        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;
+        }
+        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;
+        }
+        // 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);
+        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;
+    }
+}

package/dist/motion/reducedMotion.d.ts

@@ -0,0 +1,13 @@
+/**
+ * prefers-reduced-motion watcher.
+ *
+ * Continuous breathing, drifting, swaying and blinking is a genuine
+ * vestibular problem for some users, and this media query is exactly what it
+ * is for. Damping costs almost nothing, so it ships in v1 rather than the
+ * roadmap. Lipsync and clip playback are NOT damped — they carry meaning.
+ */
+export interface ReducedMotion {
+    readonly value: boolean;
+    dispose(): void;
+}
+export declare function createReducedMotion(): ReducedMotion;

package/dist/motion/reducedMotion.js

@@ -0,0 +1,13 @@
+export function createReducedMotion() {
+    if (typeof globalThis.matchMedia !== 'function') {
+        return { value: false, dispose() { } };
+    }
+    const mq = globalThis.matchMedia('(prefers-reduced-motion: reduce)');
+    let current = mq.matches;
+    const onChange = (e) => { current = e.matches; };
+    mq.addEventListener('change', onChange);
+    return {
+        get value() { return current; },
+        dispose() { mq.removeEventListener('change', onChange); },
+    };
+}

package/dist/motion/types.d.ts

@@ -0,0 +1,16 @@
+/** Per-eye gaze. horizontal: -1 (left) to 1 (right). vertical: -1 (down) to 1 (up). */
+export interface EyeGazeDirection {
+    horizontal: number;
+    vertical: number;
+}
+export interface GazeDirection {
+    left: EyeGazeDirection;
+    right: EyeGazeDirection;
+    /** Averages, for consumers that do not care about vergence. */
+    horizontal: number;
+    vertical: number;
+}
+/** Anything that can tell a downstream system where the character is looking. */
+export interface GazeSource {
+    readonly direction: GazeDirection;
+}

package/dist/motion/types.js

@@ -0,0 +1 @@
+export {};

package/dist/react/ConvaiCharacter.d.ts

@@ -0,0 +1,7 @@
+import { type UseCharacterOptions } from './useCharacter.js';
+import type { CharacterHandle } from '../character/createCharacter.js';
+export interface ConvaiCharacterProps extends UseCharacterOptions {
+    onReady?: (character: CharacterHandle) => void;
+    onError?: (error: Error) => void;
+}
+export declare function ConvaiCharacter({ onReady, onError, ...opts }: ConvaiCharacterProps): import("react").JSX.Element | null;

package/dist/react/ConvaiCharacter.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Thin wiring only. All lifecycle/tick behaviour lives in `useCharacter`
+ * (which itself delegates cancellation to `../character/lifecycle`) — this
+ * component adds nothing but the `<primitive>` render and the
+ * onReady/onError callback plumbing.
+ */
+import { useEffect } from 'react';
+import { useCharacter } from './useCharacter.js';
+export function ConvaiCharacter({ onReady, onError, ...opts }) {
+    const { character, error } = useCharacter(opts);
+    useEffect(() => {
+        if (character && onReady)
+            onReady(character);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [character, onReady]);
+    useEffect(() => {
+        if (error && onError)
+            onError(error);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [error, onError]);
+    if (!character)
+        return null;
+    return _jsx("primitive", { object: character.root });
+}

package/dist/react/index.d.ts

@@ -0,0 +1,4 @@
+export { useCharacter } from './useCharacter.js';
+export type { UseCharacterOptions, UseCharacterResult } from './useCharacter.js';
+export { ConvaiCharacter } from './ConvaiCharacter.js';
+export type { ConvaiCharacterProps } from './ConvaiCharacter.js';

package/dist/react/index.js

@@ -0,0 +1,2 @@
+export { useCharacter } from './useCharacter.js';
+export { ConvaiCharacter } from './ConvaiCharacter.js';

package/dist/react/useCharacter.d.ts

@@ -0,0 +1,11 @@
+import type { BlendshapeQueue } from '@convai/web-sdk/core';
+import { type CharacterHandle, type CreateCharacterOptions } from '../character/createCharacter.js';
+export interface UseCharacterOptions extends CreateCharacterOptions {
+    /** Pass the queue only while this character owns the conversational turn. */
+    queue?: BlendshapeQueue;
+}
+export interface UseCharacterResult {
+    character: CharacterHandle | null;
+    error: Error | null;
+}
+export declare function useCharacter(opts: UseCharacterOptions): UseCharacterResult;

package/dist/react/useCharacter.js

@@ -0,0 +1,45 @@
+/**
+ * Thin wiring only — see the module doc on `../character/lifecycle` for why
+ * the cancel/dispose behaviour lives there and not here. This hook does
+ * nothing `createCharacterLifecycle` doesn't already own: it creates a
+ * lifecycle per `characterId`, feeds it `createCharacter`, cancels it on
+ * unmount/re-run, and forwards the two pieces of state React needs
+ * (`character`, `error`). Ticking and camera assignment are similarly
+ * one-line pass-throughs to `CharacterHandle.update`/`.camera`.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { useFrame, useThree } from '@react-three/fiber';
+import { createCharacter } from '../character/createCharacter.js';
+import { createCharacterLifecycle } from '../character/lifecycle.js';
+export function useCharacter(opts) {
+    const [character, setCharacter] = useState(null);
+    const [error, setError] = useState(null);
+    const camera = useThree((s) => s.camera);
+    const queueRef = useRef(opts.queue);
+    queueRef.current = opts.queue;
+    // Re-created options each render, but only read inside the effect below at
+    // the instant it (re-)runs — see the exhaustive-deps note on that effect.
+    const optsRef = useRef(opts);
+    optsRef.current = opts;
+    useEffect(() => {
+        const lifecycle = createCharacterLifecycle();
+        lifecycle.start(() => createCharacter(optsRef.current), 
+        // Hide the previous attempt's result the instant a new one begins —
+        // owned by the lifecycle contract (R57), not a bare effect-body
+        // setState pair.
+        () => {
+            setCharacter(null);
+            setError(null);
+        }, (c) => setCharacter(c), (e) => setError(e));
+        return () => lifecycle.cancel();
+        // Re-create only when the identity of the character changes — matching
+        // the lifecycle contract of one `start` per instance.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [opts.characterId]);
+    useEffect(() => {
+        if (character)
+            character.camera = camera;
+    }, [character, camera]);
+    useFrame((_, delta) => character?.update(delta, queueRef.current));
+    return { character, error };
+}