@convai/embody 0.1.0

package/dist/character/lifecycle.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Owns the create/cancel/dispose lifecycle of a single `createCharacter(...)`
+ * call. Framework-free — no React, no R3F, nothing that needs a renderer —
+ * so it is testable with a plain deferred promise and a fake handle.
+ *
+ * This exists because "cancel a pending async creation and dispose whatever
+ * shows up late" is behaviour, not wiring (R56): `useCharacter` would
+ * otherwise have to reimplement this cancellation guard itself, which is
+ * exactly the kind of logic the spec forbids from living in `react/`.
+ *
+ * One instance is one attempt: call `start` once, `cancel` any number of
+ * times (idempotent). To retry — e.g. a new `characterId` — create a fresh
+ * instance rather than reusing this one.
+ */
+export interface CharacterLifecycle<T extends {
+    dispose(): void;
+}> {
+    /**
+     * Begin creating. `onStart` fires synchronously, before `create()` is even
+     * invoked — a caller wires it to whatever "hide the previous result" reset
+     * needs to happen the instant a new attempt begins (R57: this used to be
+     * two raw `setState(null)` calls sitting in `useCharacter`, undeclared
+     * behaviour outside the lifecycle contract; it is now owned and tested
+     * here instead). `onStart` fires exactly once, at the top of `start()` —
+     * `cancel()` never triggers it again.
+     *
+     * Resolves asynchronously into exactly one of:
+     *  - `onReady(handle)`, if still active when `create()` resolves
+     *  - a silent call to `handle.dispose()`, if `cancel()` ran first
+     *  - `onError(error)`, if `create()` rejects and `cancel()` did not run first
+     *
+     * "Disposed" above means exactly this: `T.dispose()` is invoked. Whether
+     * that actually releases every resource the handle holds is entirely
+     * `T.dispose()`'s own contract, not something this lifecycle can verify or
+     * guarantee — it does not inspect what `dispose()` does. For
+     * `CharacterHandle` specifically, see `disposeCharacter` in
+     * `createCharacter.ts`, which is what makes that promise true in
+     * practice (until 2026-09-07 it released only a media-query listener and
+     * leaked the entire loaded GLB).
+     */
+    start(create: () => Promise<T>, onStart: () => void, onReady: (handle: T) => void, onError: (error: Error) => void): void;
+    /**
+     * Idempotent — a second call is a harmless no-op (idempotency falls out of
+     * nulling `handle` after disposing it, not from a separate re-entrancy
+     * guard). If the handle already arrived, calls its `dispose()` now. If it
+     * is still in flight, marks this attempt cancelled so `dispose()` is
+     * called on it (never handed to `onReady`) the moment it arrives — see the
+     * "Disposed" note on `start()` above for what that promise does and does
+     * not cover.
+     */
+    cancel(): void;
+}
+export declare function createCharacterLifecycle<T extends {
+    dispose(): void;
+}>(): CharacterLifecycle<T>;

package/dist/character/lifecycle.js

@@ -0,0 +1,28 @@
+export function createCharacterLifecycle() {
+    let cancelled = false;
+    let handle = null;
+    return {
+        start(create, onStart, onReady, onError) {
+            onStart();
+            create()
+                .then((created) => {
+                if (cancelled) {
+                    created.dispose();
+                    return;
+                }
+                handle = created;
+                onReady(created);
+            })
+                .catch((error) => {
+                if (cancelled)
+                    return;
+                onError(error instanceof Error ? error : new Error(String(error)));
+            });
+        },
+        cancel() {
+            cancelled = true;
+            handle?.dispose();
+            handle = null;
+        },
+    };
+}

package/dist/character/pipeline.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The explicit frame pipeline.
+ *
+ * Order is load-bearing and each constraint below is inherited from the
+ * prior art, not invented here:
+ *   0 normalize — root scale must settle before anything reads world space
+ *   1 mixer     — clips drive the skeleton
+ *   2 gaze      — OVERRIDES the mixer's head rotation, never blends with it
+ *   3 additive  — breathe/lean/gestures, added AFTER the mixer so nothing
+ *                 accumulates (the mixer rewrites every frame)
+ *   4 ik        — foot lock (reserved; no system in this slice)
+ *   5 attach    — hair follows the final transform (reserved)
+ *   6 morph     — lipsync, eye-look, blink. Blink must run after lipsync.
+ */
+import type * as THREE from 'three';
+import type { BlendshapeQueue } from '@convai/web-sdk/core';
+import type { ResolvedRig } from '../rig/resolve.js';
+export type Stage = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export interface FrameContext {
+    root: THREE.Object3D;
+    rig: ResolvedRig;
+    camera?: THREE.Camera;
+    /** Present only while this character owns the conversational turn. */
+    queue?: BlendshapeQueue;
+    /**
+     * Produced by LipsyncSystem in stage 6, so stage-2 gaze reads the PREVIOUS
+     * frame's value. 16ms of lag on a gaze cue is imperceptible and far cheaper
+     * than a pre-pass that would exist only to remove it. Deliberate.
+     */
+    speaking: boolean;
+    energy: number;
+    reducedMotion: boolean;
+}
+export interface System {
+    readonly stage: Stage;
+    update(dt: number, ctx: FrameContext): void;
+}
+export declare class Pipeline {
+    private readonly systems;
+    private dirty;
+    add(system: System): void;
+    private sortIfDirty;
+    /** Ordered view, for tests and debugging. */
+    get ordered(): readonly System[];
+    update(dt: number, ctx: FrameContext): void;
+}

package/dist/character/pipeline.js

@@ -0,0 +1,29 @@
+export class Pipeline {
+    constructor() {
+        this.systems = [];
+        this.dirty = false;
+    }
+    add(system) {
+        this.systems.push(system);
+        this.dirty = true;
+    }
+    sortIfDirty() {
+        if (!this.dirty)
+            return;
+        // Stable sort: Array.prototype.sort is stable in every engine we target,
+        // so equal stages keep registration order — that IS the intra-stage
+        // contract, not an accident.
+        this.systems.sort((a, b) => a.stage - b.stage);
+        this.dirty = false;
+    }
+    /** Ordered view, for tests and debugging. */
+    get ordered() {
+        this.sortIfDirty();
+        return this.systems;
+    }
+    update(dt, ctx) {
+        this.sortIfDirty();
+        for (const s of this.systems)
+            s.update(dt, ctx);
+    }
+}

package/dist/clips/animations.d.ts

@@ -0,0 +1,39 @@
+/**
+ * AnimationController — generic clip playback and transitions.
+ *
+ * Deliberately NOT an idle/talk switch: the API is animation → animation.
+ * `crossfadeTo(name)` moves from whatever is playing to any named clip, and
+ * higher layers (the SDK's isSpeaking, an action event, a UI button) decide
+ * which names those are via their own mapping. Loaded clips are track-filtered
+ * against the bones this model actually has — embody's dev-time validation:
+ * the clip GLBs carry richer rigs (fingers, hair) than some models.
+ */
+import * as THREE from 'three';
+export interface ClipTransition {
+    /** Seconds for the crossfade. Default 0.35. */
+    duration?: number;
+    /** Play once and freeze on the last frame instead of looping. */
+    once?: boolean;
+    /** For `once` clips: crossfade back to this clip when finished. */
+    thenBackTo?: string;
+}
+export declare class AnimationController {
+    private readonly root;
+    readonly mixer: THREE.AnimationMixer;
+    private readonly actions;
+    private current;
+    private pendingReturn;
+    constructor(root: THREE.Object3D);
+    /** Register clips, filtering tracks to bones present on this model. */
+    register(clips: THREE.AnimationClip[]): {
+        name: string;
+        kept: number;
+        dropped: number;
+    }[];
+    get names(): string[];
+    get playing(): string | null;
+    play(name: string): void;
+    /** Generic transition: whatever is playing → `name`. Idempotent. */
+    crossfadeTo(name: string, opts?: ClipTransition): void;
+    update(delta: number): void;
+}

package/dist/clips/animations.js

@@ -0,0 +1,77 @@
+/**
+ * AnimationController — generic clip playback and transitions.
+ *
+ * Deliberately NOT an idle/talk switch: the API is animation → animation.
+ * `crossfadeTo(name)` moves from whatever is playing to any named clip, and
+ * higher layers (the SDK's isSpeaking, an action event, a UI button) decide
+ * which names those are via their own mapping. Loaded clips are track-filtered
+ * against the bones this model actually has — embody's dev-time validation:
+ * the clip GLBs carry richer rigs (fingers, hair) than some models.
+ */
+import * as THREE from 'three';
+export class AnimationController {
+    constructor(root) {
+        this.root = root;
+        this.actions = new Map();
+        this.current = null;
+        this.pendingReturn = null;
+        this.mixer = new THREE.AnimationMixer(root);
+        this.mixer.addEventListener('finished', (e) => {
+            const p = this.pendingReturn;
+            if (p && e.action === p.action) {
+                this.pendingReturn = null;
+                this.crossfadeTo(p.to);
+            }
+        });
+    }
+    /** Register clips, filtering tracks to bones present on this model. */
+    register(clips) {
+        const bones = new Set();
+        this.root.traverse((o) => bones.add(o.name));
+        const report = [];
+        for (const src of clips) {
+            const kept = src.tracks.filter((t) => bones.has(t.name.split('.')[0]));
+            const dropped = src.tracks.length - kept.length;
+            if (dropped > 0)
+                console.warn(`[embody] clip "${src.name}": ${dropped}/${src.tracks.length} tracks target absent bones — dropped`);
+            const clip = new THREE.AnimationClip(src.name, src.duration, kept);
+            this.actions.set(src.name, this.mixer.clipAction(clip));
+            report.push({ name: src.name, kept: kept.length, dropped });
+        }
+        return report;
+    }
+    get names() { return [...this.actions.keys()]; }
+    get playing() { return this.current; }
+    play(name) {
+        const a = this.actions.get(name);
+        if (!a)
+            throw new Error(`[embody] unknown clip "${name}" (have: ${this.names.join(', ')})`);
+        a.reset().setLoop(THREE.LoopRepeat, Infinity).play();
+        this.current = name;
+    }
+    /** Generic transition: whatever is playing → `name`. Idempotent. */
+    crossfadeTo(name, opts = {}) {
+        if (name === this.current)
+            return;
+        const next = this.actions.get(name);
+        if (!next)
+            throw new Error(`[embody] unknown clip "${name}" (have: ${this.names.join(', ')})`);
+        const prev = this.current ? this.actions.get(this.current) : undefined;
+        const dur = opts.duration ?? 0.35;
+        next.reset();
+        if (opts.once) {
+            next.setLoop(THREE.LoopOnce, 1);
+            next.clampWhenFinished = true;
+            if (opts.thenBackTo)
+                this.pendingReturn = { to: opts.thenBackTo, action: next };
+        }
+        else {
+            next.setLoop(THREE.LoopRepeat, Infinity);
+        }
+        next.play();
+        if (prev)
+            next.crossFadeFrom(prev, dur, false);
+        this.current = name;
+    }
+    update(delta) { this.mixer.update(delta); }
+}

package/dist/decorate/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * CharacterDecorator — the sanctioned escape hatch for per-character code.
+ *
+ * The question this answers: "what if we want to change the character the way
+ * pagoda-act did — mouth constants, material tweaks?" Three tiers, in order of
+ * preference:
+ *
+ *  1. TUNING PARAMS on built-in systems (e.g. MouthTuning on the lipsync
+ *     system): the common knobs, typed, documented, no scene-graph spelunking.
+ *  2. DECORATORS (this file): arbitrary code run once after the model loads,
+ *     with the loaded graph and the manifest in hand — material overrides,
+ *     mesh hiding, custom shaders. Client-side, versioned with the app.
+ *  3. THE PIPELINE (long-term home): fixes every consumer needs — a wrong
+ *     roughness, a broken alpha mode — belong baked into the processed GLB or
+ *     expressed as manifest metadata, not repeated in every app's decorator.
+ *
+ * A decorator that every consumer copies is a pipeline bug report.
+ */
+import type * as THREE from 'three';
+import type { CharacterBundle, Representation } from '../resolve/resolver.js';
+export interface DecoratorContext {
+    root: THREE.Object3D;
+    bundle: CharacterBundle;
+    representation: Representation;
+    /** Every unique material in the model, for tweak-by-name. */
+    materials: Map<string, THREE.Material>;
+}
+export type CharacterDecorator = (ctx: DecoratorContext) => void;
+export declare function collectMaterials(root: THREE.Object3D): Map<string, THREE.Material>;

package/dist/decorate/types.js

@@ -0,0 +1,13 @@
+export function collectMaterials(root) {
+    const out = new Map();
+    root.traverse((o) => {
+        const mesh = o;
+        if (!mesh.isMesh)
+            return;
+        const mats = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const m of mats)
+            if (m && m.name)
+                out.set(m.name, m);
+    });
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/resolver.js';
+export type { HttpResolverOptions } from './resolve/resolver.js';
+export type { CharacterResolver, CharacterBundle, Representation, ModelVariant } from './resolve/resolver.js';
+export { createCharacter } from './character/createCharacter.js';
+export type { CharacterHandle, CreateCharacterOptions } from './character/createCharacter.js';
+export { AnimationController } from './clips/animations.js';
+export type { ClipTransition } from './clips/animations.js';
+export { LipsyncSystem } from './speech/lipsync.js';
+export type { MouthTuning } from './speech/lipsync.js';
+export { createUnitNormalizer } from './rig/units.js';
+export { collectMaterials } from './decorate/types.js';
+export type { CharacterDecorator, DecoratorContext } from './decorate/types.js';
+export { Pipeline } from './character/pipeline.js';
+export type { Stage, System, FrameContext } from './character/pipeline.js';
+export { setLookQuat, CONVAI_MHA_1, CC4_LEGACY, CC4_BASIS, UE_BASIS, REGISTERED_PROFILES } from './rig/profile.js';
+export type { RigProfile, RigBasis, BoneRole, MorphRole } from './rig/profile.js';
+export { resolveRig, writeMorph, REQUIRED_BONES } from './rig/resolve.js';
+export type { ResolvedRig, MorphBinding } from './rig/resolve.js';
+export { GazeSystem } from './motion/gaze.js';
+export type { GazeConfig } from './motion/gaze.js';
+export { EyeGazeSystem } from './motion/eyeGaze.js';
+export type { EyeGazeConfig } from './motion/eyeGaze.js';
+export { BlinkSystem } from './motion/blink.js';
+export type { BlinkConfig } from './motion/blink.js';
+export { BreathingSystem } from './motion/breathe.js';
+export type { BreathingConfig } from './motion/breathe.js';
+export { createReducedMotion } from './motion/reducedMotion.js';
+export type { ReducedMotion } from './motion/reducedMotion.js';
+export type { GazeDirection, EyeGazeDirection, GazeSource } from './motion/types.js';
+export type { UnitNormalizer } from './rig/units.js';

package/dist/index.js

@@ -0,0 +1,14 @@
+export { httpResolver, pickRepresentation, DEFAULT_BASE_URL } from './resolve/resolver.js';
+export { createCharacter } from './character/createCharacter.js';
+export { AnimationController } from './clips/animations.js';
+export { LipsyncSystem } from './speech/lipsync.js';
+export { createUnitNormalizer } from './rig/units.js';
+export { collectMaterials } from './decorate/types.js';
+export { Pipeline } from './character/pipeline.js';
+export { setLookQuat, CONVAI_MHA_1, CC4_LEGACY, CC4_BASIS, UE_BASIS, REGISTERED_PROFILES } from './rig/profile.js';
+export { resolveRig, writeMorph, REQUIRED_BONES } from './rig/resolve.js';
+export { GazeSystem } from './motion/gaze.js';
+export { EyeGazeSystem } from './motion/eyeGaze.js';
+export { BlinkSystem } from './motion/blink.js';
+export { BreathingSystem } from './motion/breathe.js';
+export { createReducedMotion } from './motion/reducedMotion.js';

package/dist/motion/blink.d.ts

@@ -0,0 +1,56 @@
+import type { FrameContext, System } from '../character/pipeline.js';
+import type { GazeSource } from './types.js';
+export interface BlinkConfig {
+    /** Floor on the gap between blinks (seconds). */
+    minInterval?: number;
+    /** MEDIAN of the log-normal blink gap — the long right tail gives the
+     *  occasional 20-60s attentive hold seen in the reference footage. */
+    maxInterval?: number;
+    /** Phase durations (seconds), each jittered +/-15% per blink. */
+    closeDuration?: number;
+    holdDuration?: number;
+    openDuration?: number;
+    doubleBlinkChance?: number;
+    /** Reference blinks are mostly soft: 5 of 6 measured events were under 55%
+     *  amplitude, so full snaps are the exception. */
+    partialBlinkChance?: number;
+    /**
+     * Resting upper-lid droop (0 = wide stare, 1 = closed). RULING (2026-09-07
+     * fix wave): default is the rig-tuned value from the actual convai-mha-1
+     * call site (`examples/react-three-fiber/src/characters/SofiaV4.tsx:338`),
+     * not the brief's untuned 0.35 — that call site's own comment names the
+     * exact failure: "stacked on the Eye_Look_Down lid travel[,] the old 0.35
+     * default read half-asleep whenever the gaze dropped" (Sofia.tsx:238-241).
+     * Compounds with C2 (the resting droop no longer also floors the blink
+     * channel) and C4 (`DOWN_LID_SCALE` on the down-gaze morph) — all three
+     * touch this same eyelid pathway together.
+     */
+    restingLidDroop?: number;
+    restingLowerLid?: number;
+    /**
+     * Extra droop at full downward gaze. Modest, because the eyeLookDown
+     * morphs already carry most of the lid travel. Default is the same
+     * rig-tuned call site as `restingLidDroop` above (SofiaV4.tsx:339).
+     */
+    gazeFollowAmount?: number;
+    enabled?: boolean;
+}
+/**
+ * Procedural eyelid behaviour, matched frame-by-frame against Unreal
+ * MetaHuman reference footage. Owns the WHOLE lid state, not just the blink.
+ * Registered AFTER lipsync in stage 6 so it wins over NeuroSync's own damped
+ * blinks — the pipeline enforces that by registration order, not by comment.
+ */
+export declare class BlinkSystem implements System {
+    private readonly gaze?;
+    readonly stage: 6;
+    private readonly cfg;
+    private clock;
+    private nextBlink;
+    /** Current blink; phases are pre-jittered when it is scheduled. */
+    private b;
+    /** Resting droop wander: a level gliding toward a re-targeted value. */
+    private droop;
+    constructor(config?: BlinkConfig, gaze?: GazeSource | undefined);
+    update(dt: number, ctx: FrameContext): void;
+}

package/dist/motion/blink.js

@@ -0,0 +1,127 @@
+import * as THREE from 'three';
+import { writeMorph } from '../rig/resolve.js';
+const rand = (a, b) => a + Math.random() * (b - a);
+/** +/-15% multiplicative jitter. */
+const jitter = (v) => v * rand(0.85, 1.15);
+/**
+ * Log-normal-ish blink gap matched to the reference footage: median ~=
+ * `median` seconds, long right tail, never below `min`. Uniform intervals are
+ * what read robotic. Sigma 0.55 in log space — 0.7 produced long dead
+ * stretches that read as "barely blinks".
+ */
+function blinkGap(median, min) {
+    const u = Math.random() || 1e-6;
+    const v = Math.random();
+    const g = Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+    return Math.max(min, median * Math.exp(0.55 * g));
+}
+/**
+ * Procedural eyelid behaviour, matched frame-by-frame against Unreal
+ * MetaHuman reference footage. Owns the WHOLE lid state, not just the blink.
+ * Registered AFTER lipsync in stage 6 so it wins over NeuroSync's own damped
+ * blinks — the pipeline enforces that by registration order, not by comment.
+ */
+export class BlinkSystem {
+    constructor(config = {}, gaze) {
+        this.gaze = gaze;
+        this.stage = 6;
+        this.clock = 0;
+        /** Current blink; phases are pre-jittered when it is scheduled. */
+        this.b = { start: -1, peak: 1, close: 0.09, hold: 0.055, open: 0.3 };
+        /** Resting droop wander: a level gliding toward a re-targeted value. */
+        this.droop = { level: 0, target: 0, next: 0 };
+        this.cfg = {
+            minInterval: 1.2, maxInterval: 3.5,
+            closeDuration: 0.09, holdDuration: 0.055, openDuration: 0.3,
+            doubleBlinkChance: 0.12, partialBlinkChance: 0.3,
+            restingLidDroop: 0.22, restingLowerLid: 0.12,
+            gazeFollowAmount: 0.08, enabled: true,
+            ...config,
+        };
+        this.nextBlink = rand(1.5, this.cfg.maxInterval);
+        this.droop.level = this.cfg.restingLidDroop;
+        this.droop.target = this.cfg.restingLidDroop;
+    }
+    update(dt, ctx) {
+        if (!this.cfg.enabled)
+            return;
+        this.clock += dt;
+        const t = this.clock;
+        const b = this.b;
+        // --- blink envelope -----------------------------------------------
+        let v = 0;
+        if (!ctx.reducedMotion) {
+            // Kick off a blink when the timer elapses; roll its character. Partials
+            // are soft AND slow-opening; full blinks snap shut but still reopen
+            // lazily. Every phase is re-rolled so no two blinks match.
+            if (b.start < 0 && t >= this.nextBlink) {
+                b.start = t;
+                const partial = Math.random() < this.cfg.partialBlinkChance;
+                b.peak = partial ? rand(0.5, 0.85) : rand(0.92, 1);
+                b.close = jitter(this.cfg.closeDuration) * (partial ? rand(1.1, 1.6) : 1);
+                b.hold = jitter(this.cfg.holdDuration);
+                b.open = rand(0.8, 1.5) * this.cfg.openDuration;
+            }
+            if (b.start >= 0) {
+                const el = t - b.start;
+                if (el < b.close) {
+                    // Fast close, decelerating into contact.
+                    v = Math.sin((el / b.close) * (Math.PI / 2));
+                }
+                else if (el < b.close + b.hold) {
+                    v = 1;
+                }
+                else if (el < b.close + b.hold + b.open) {
+                    // Slow reopen with a long ease-out tail.
+                    const u = (el - b.close - b.hold) / b.open;
+                    v = 0.5 * (1 + Math.cos(Math.PI * u));
+                }
+                else {
+                    b.start = -1;
+                    this.nextBlink = t + (Math.random() < this.cfg.doubleBlinkChance
+                        ? rand(0.35, 0.9) // quick second blink
+                        : Math.min(blinkGap(this.cfg.maxInterval, this.cfg.minInterval), this.cfg.maxInterval * 2.2));
+                }
+                v *= b.peak;
+            }
+        }
+        else {
+            b.start = -1;
+        }
+        // --- resting droop -------------------------------------------------
+        // A slow random WANDER, not a sine: a loop, however slow, eventually
+        // reads repetitive. Every few seconds the lid tension re-targets within
+        // +/-35% of the configured droop and glides there.
+        const d = this.droop;
+        if (t >= d.next) {
+            d.target = this.cfg.restingLidDroop * rand(0.65, 1.35);
+            d.next = t + rand(3, 9);
+        }
+        d.level += (d.target - d.level) * (1 - Math.exp(-1.2 * dt));
+        // The lid follows the eye vertically: extra droop as the gaze drops, and
+        // the relaxed hood lifts away as it rises. The lift is MULTIPLICATIVE
+        // (damping the resting droop toward zero as gazeUp -> 1), not a flat
+        // subtraction — a constant offset diverges from the droop level itself
+        // and can flip sign or floor incorrectly across the resting band.
+        const gazeV = this.gaze?.direction.vertical ?? 0;
+        const gazeDown = Math.max(0, -gazeV);
+        const gazeUp = Math.max(0, gazeV);
+        const relax = THREE.MathUtils.clamp(d.level * (1 - 0.6 * gazeUp) + gazeDown * this.cfg.gazeFollowAmount, 0, 1);
+        // RULING (2026-09-07 fix wave, C2): `blink`/`blinkCorrective` get the
+        // PURE blink envelope (`v`, zero between blinks); `relax` is its own
+        // channel. Folding them together with `Math.max(relax, v)` (the old
+        // behaviour) stacked two independent morphs onto one another
+        // anatomically — the resting droop kept the lids permanently ~1/3
+        // closed AND clipped the bottom third of every blink's envelope (30% of
+        // blinks are partial, per `partialBlinkChance`, and peak there is
+        // already below 0.85). See useBlink.ts:247-250: the prior art writes
+        // `v` to `blink`/`blinkCorr` and `relax`/`restingLowerLid` to their own
+        // slots — never combined.
+        writeMorph(ctx.rig, 'blinkL', v);
+        writeMorph(ctx.rig, 'blinkR', v);
+        writeMorph(ctx.rig, 'blinkCorrectiveL', v); // CC4 only; absent = no-op
+        writeMorph(ctx.rig, 'blinkCorrectiveR', v);
+        writeMorph(ctx.rig, 'relax', relax);
+        writeMorph(ctx.rig, 'lowerLidUp', this.cfg.restingLowerLid);
+    }
+}

package/dist/motion/breathe.d.ts

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