@voqalize/avatar 0.2.2 → 0.4.0

package/dist/three/tanya.d.ts

@@ -0,0 +1,35 @@
+/**
+ * tanya — the third 3-D character, and like `tushar.ts` a copy of `tara.ts`.
+ *
+ * Her GLB is tara's scripts run with her landmarks and atlas layout in place of
+ * hers (`characters/tanya/`, whose README has the provenance and the commands),
+ * so the rig, the mixer, the sequences and her tuning are all hers, unmodified;
+ * the one seam is `TaraRigOptions.url`.
+ *
+ * She is the first character whose atlas is not tara's window. Her hair is the
+ * silhouette down past the jaw, out to |u| 0.761 where tara's window stops at
+ * 0.64, so `characters/tanya/face_texture.py` widens it to 1408x1568 at the same
+ * 800 pixels per face height. That is a fact about the asset and costs this file
+ * nothing — the rig reads the window from the GLB.
+ */
+import type { PipecatClient } from "@pipecat-ai/client-js";
+export interface AvatarOptions {
+    readonly mount: HTMLElement;
+    readonly client: PipecatClient;
+    /** Viseme amplitude, 0..2. `1` is as authored. */
+    readonly mouthGain?: number;
+    /** Gesture-clip amplitude, 0..2. */
+    readonly gestureGain?: number;
+    /** Idle/liveness amplitude, 0..2. */
+    readonly motionGain?: number;
+    /** Fires when the GLB is in the scene — for a capture tool, not a consumer. */
+    readonly onReady?: () => void;
+}
+export interface AvatarInstance {
+    destroy(): void;
+}
+/** The optional driving-UI declaration; one list for all three characters
+ *  (`sequences.ts`), because they are one rig. */
+export declare const supports: import("../createAvatar.js").AvatarSupport;
+export declare function createAvatar(options: AvatarOptions): AvatarInstance;
+//# sourceMappingURL=tanya.d.ts.map

package/dist/three/tanya.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanya.d.ts","sourceRoot":"","sources":["../../client/three/tanya.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAQ3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,kDAAkD;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qCAAqC;IACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAAG,OAAO,IAAI,IAAI,CAAC;CAAE;AAEpD;kDACkD;AAClD,eAAO,MAAM,QAAQ,4CAAmB,CAAC;AAEzC,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,CA0BnE"}

package/dist/three/tanya.js

@@ -0,0 +1,51 @@
+/**
+ * tanya — the third 3-D character, and like `tushar.ts` a copy of `tara.ts`.
+ *
+ * Her GLB is tara's scripts run with her landmarks and atlas layout in place of
+ * hers (`characters/tanya/`, whose README has the provenance and the commands),
+ * so the rig, the mixer, the sequences and her tuning are all hers, unmodified;
+ * the one seam is `TaraRigOptions.url`.
+ *
+ * She is the first character whose atlas is not tara's window. Her hair is the
+ * silhouette down past the jaw, out to |u| 0.761 where tara's window stops at
+ * 0.64, so `characters/tanya/face_texture.py` widens it to 1408x1568 at the same
+ * 800 pixels per face height. That is a fact about the asset and costs this file
+ * nothing — the rig reads the window from the GLB.
+ */
+import { AvatarClient, createSvgAvatar } from "../internal.js";
+import { ASSETS } from "./assets.js";
+import { BLENDER_ACTIONS, BLENDER_SEQUENCES, BLENDER_SUPPORTS } from "./sequences.js";
+import { headHold } from "./holds.js";
+import { createTaraRig, TARA_TUNING } from "./tara-rig.js";
+/** The optional driving-UI declaration; one list for all three characters
+ *  (`sequences.ts`), because they are one rig. */
+export const supports = BLENDER_SUPPORTS;
+export function createAvatar(options) {
+    const { mount, client, onReady, ...gains } = options;
+    if (!mount)
+        throw new TypeError("createAvatar: `mount` is required");
+    if (!client)
+        throw new TypeError("createAvatar: `client` is required");
+    const rigOptions = { onReady, url: ASSETS.tanya };
+    // TARA-SPECIFIC, kept on purpose: `TARA_TUNING` (her mouth and motion gains)
+    // is the first thing to question if she reads wrong in a call.
+    const widget = createSvgAvatar({
+        mount, rig: createTaraRig, rigOptions, hand: false,
+        sequences: BLENDER_SEQUENCES, actions: BLENDER_ACTIONS, ...TARA_TUNING,
+        headHold: headHold("tanya"), ...gains,
+    });
+    const driver = new AvatarClient(widget);
+    const detach = driver.attach(client);
+    let destroyed = false;
+    return {
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            detach();
+            driver.destroy();
+            widget.destroy();
+        },
+    };
+}
+//# sourceMappingURL=tanya.js.map

package/dist/three/tanya.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tanya.js","sourceRoot":"","sources":["../../client/three/tanya.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtF,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAkB3D;kDACkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAEzC,MAAM,UAAU,YAAY,CAAC,OAAsB;IACjD,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,GAAG,OAAO,CAAC;IACrD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,SAAS,CAAC,mCAAmC,CAAC,CAAC;IACrE,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;IAEvE,MAAM,UAAU,GAAmB,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;IAClE,6EAA6E;IAC7E,+DAA+D;IAC/D,MAAM,MAAM,GAAG,eAAe,CAAC;QAC7B,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK;QAClD,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,WAAW;QACtE,QAAQ,EAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK;KACtC,CAAC,CAAC;IACH,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAErC,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,OAAO;QACL,OAAO;YACL,IAAI,SAAS;gBAAE,OAAO;YACtB,SAAS,GAAG,IAAI,CAAC;YACjB,MAAM,EAAE,CAAC;YACT,MAAM,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/three/tara-rig.d.ts

@@ -0,0 +1,403 @@
+/**
+ * tara's renderer: the `AvatarRig` contract (`apply(frame)` / `destroy()`)
+ * over the Blender-authored GLB.
+ *
+ * The whole file is one idea — **the pose channel is the interface, and every
+ * mapping here is a translation of one channel into the one control that
+ * renders it.** `scripts/morphs.py` authored the shape keys under the library's
+ * own channel names precisely so this file never has to interpret a viseme, a
+ * state or an emotion; it receives a fully mixed pose and moves geometry.
+ *
+ * Three kinds of control, in the order they appear below:
+ *
+ *   morph targets  the face itself — lips, jaw, lids, brows, and the mouth
+ *                  interior that has to choreograph with them
+ *   head group     `headYaw` / `headPitch` / `headRoll`, as a rotation of the
+ *                  parts that ride the skull about the jaw-angle pivot
+ *   eye globes     `pupilX` / `pupilY`, as a rotation of the eyeball, because
+ *                  the iris is painted onto a sphere and cannot slide
+ *
+ * and a fourth, for the body: `shoulderL/R` are morph targets on the torso
+ * shell like any face channel, and `breath`, `torsoLean` and `torsoTurn` are
+ * each one transform of a group — a swell, a scale, a sway (see `BODY`).
+ *
+ * An asset may add a fifth: expression maps, which change the face's *light*
+ * where a smile or a raised brow would, because moving the geometry cannot
+ * (see `expressive`).
+ */
+import type { AvatarRig } from "../internal.js";
+/**
+ * Head motion, in degrees at the channel's own clamp of ±1.4.
+ *
+ * These are the program's *working* envelope, mapped so that a channel pinned to
+ * its limit lands exactly on it. That is the point of scaling by the clamp
+ * rather than by 1: the mixer cannot ask for more than the envelope allows, and
+ * the hard ceiling stays unreachable by construction instead of by a second
+ * clamp nobody runs.
+ *
+ * **It opened on 2026-09-12, from yaw ±6°, pitch ±5°, roll ±3°.** That
+ * envelope made Busso's neutral-speech numbers unreachable: his mean
+ * per-sentence pitch *range* is 9.5°, which is 95 % of everything ±5° could
+ * ever produce, so speaking alone would have swung the channel corner to corner
+ * and a deliberate nod on top of it would have had nowhere left to go. What had
+ * held it there was the asset, not anatomy — the neck's follow was linear and
+ * drew a second jawline past a few degrees — and once that follow became exact
+ * (`NECK_QUAD` below) pitch could open to 24 and roll to 8.
+ *
+ * Yaw is still the smallest because it is the one axis this rig is genuinely
+ * constrained on: the albedo is a front-orthographic projection of a 0.34-deep
+ * shell, and a large turn is where that reads as a cardboard cutout rather than
+ * a head. **It opened from 9° to 15° on 2026-09-18.** The cutout was measured
+ * rather than assumed — a ladder rendered at 9/12/15/18/21/25/30 and read at
+ * crop on all three characters is clean to 21° on tara and to 18° on tanya and
+ * tushar. 9° was therefore set at half of where the artefact actually begins,
+ * and the stiffness the owner reported on tanya's turns was that margin, not
+ * her asset. 15° keeps 3° of headroom on the tightest of the three.
+ *
+ * This is not for speech: Busso wants ±1.15° of yaw in neutral conversation and
+ * always did. It is for a head that turns to *look* at something, which is what
+ * mocap drives and what pegged the channel — a real 25° turn still saturates at
+ * 15°, so this widens the envelope without making it generous.
+ *
+ * And it is not the angle a pose may be *held* at, which is a stricter question
+ * with its own measurement per character (`motion-limits.json`, applied through
+ * `holds.ts`): a turn that returns is forgiven what a sustained one is not. The
+ * two numbers differ by about 3x on yaw and neither is a correction of the
+ * other.
+ *
+ * **Editing these needs no rebuild, but it is not free.** The neck's fields
+ * carry no angle, so `tara.glb` cannot go stale against them. What a number
+ * here does move:
+ *
+ * - Every clip is authored in channel units, so a degree here re-sizes every
+ *   clip driving that axis. `test/nods.test.ts` bands *pitch* only — `down`,
+ *   `up`, `upFirst` — and computes `yawPP` without ever asserting it. A yaw
+ *   change moves nothing there; a pitch change moves four tests.
+ * - `head_parallax.py` and `validate_morphs.py` quote their gates at this
+ *   envelope. `validate_morphs` reads `morphs.head_envelope()`, but
+ *   `head_parallax.POSES` hardcoded `yaw 9` until 2026-09-18 and would have
+ *   gone on grading 9° while the rig shipped 15° — a gate defending a number
+ *   nothing used. It derives both angles from here now.
+ * - The yaw twist's two fields are an expansion in the angle, so their error
+ *   grows as θ²/6. Against the exact rotation at the maximum ramp
+ *   (`NECK_TWIST` = 0.5) that is 0.31 % at 9°, 0.85 % at 15°, 1.23 % at 18°
+ *   (`morphs.neck_twist`). The note here used to read as a wall at 9°; it is
+ *   not one — 15° costs under a percent of a displacement that is itself a
+ *   fraction of the neck's radius.
+ *
+ * TARA-SPECIFIC: each number is her reach before an artefact shows — yaw by
+ * the cutout, pitch by the neck fold that starts to crease at 24° chin-up.
+ * Both were measured on the shipping surface, one axis at a time. This is still
+ * one shared pair of
+ * constants for all three characters, which holds only because 15° is inside
+ * every one of them; the first character that wants more than its neighbours
+ * forces the envelope onto `TaraRigOptions` as a per-character fact. A second
+ * avatar measures its own with the audit.
+ */
+export declare const HEAD_CLAMP = 1.4;
+export declare const HEAD_DEG: {
+    yaw: number;
+    pitch: number;
+    roll: number;
+};
+/** Degrees per pose unit: the globe turns `pupil * GAZE_TRAVEL / GLOBE_RADIUS`
+ *  radians, and the head reaches `HEAD_DEG` at the clamp.
+ *
+ *  Exported through `internal.ts` for the same reason as the head envelope: an
+ *  instrument that asks for "eyes on the camera through a head turn" is running
+ *  this conversion backwards, and a second copy of it would be a second thing to
+ *  update when the eye tile or the globe changes. */
+export declare const EYE_DEG: {
+    x: number;
+    y: number;
+};
+/**
+ * The mixer's per-rig calibration for tara, passed by `tara.ts` and the motion
+ * audit so both measure the same face. A pose unit is an angle here and a
+ * pixel count on an SVG face, so the speech layer's amplitudes are tuned per
+ * rig rather than in the library: `prosodyHeadGain` sizes speech-rhythm head
+ * motion against this face's own motion envelope.
+ *
+ * `oculomotor` is the eye-head system sized for this face (`gaze.js`). Her eye
+ * turns 10° a pupil unit and her head 6.4° of yaw a head unit, and the shared
+ * look table — drawn for a line face, whose pupils cross most of an eye — put
+ * every look in the eyes: a thinking look away was the iris parked in the
+ * corner of the socket for two thirds of the state, which is side-eye, not
+ * thought. Here the head carries about 60 % of a look and the eyes land a third
+ * of the way off centre, where a real eye-head shift leaves them (Freedman &
+ * Sparks; Pejsa & Andrist). The comment on each target is its world angle,
+ * x right and y down.
+ *
+ *   vor        Real gain in the light is close to 1. A little under leaves the
+ *              head some say, so a nod carries the eyes a touch with it rather
+ *              than pinning them to the lens. Vertically it is well under
+ *              (2026-09-15): her pitch is a shell tipping on a photograph and
+ *              reads as a fraction of what it is, so the eyes' full answer to
+ *              it read as the eyes moving on their own — at 0.8, THINKING's
+ *              up-look rolled the iris to the lid with white beneath it, and
+ *              the reply that followed dropped it into a downcast look with the
+ *              lid riding down, while the head was still coming back. At 0.35
+ *              the eyes mostly go where the head takes them.
+ *   range      How far the reflex may carry the eye in the socket. Unlimited,
+ *              an up-look's onset put the whole 8° in the eye before the neck
+ *              moved — the iris pinned under the lid, white beneath it, which
+ *              on this photograph reads as an eye-roll. Up 0.45 is 2.8° and
+ *              down 0.5 is 3.1°; the head covers the rest, as it does once the
+ *              eye nears its effective range. Both were looser (0.55, 0.85)
+ *              and a gap between turns hit both ends of them every time.
+ *   lidFollow  Down 0.38 keeps the upper lid on the iris: the lid travels
+ *              0.068 face units per lid unit and the iris 0.026 per pupil unit.
+ *              Up a little less, so an upward look opens the eye a hair instead
+ *              of dragging the lid along with it.
+ *   avert      A conversational look away keeps under half its size in the
+ *              eyes and gives the neck 0.6 of it — on this face the eyes alone
+ *              could only make it a glance sideways.
+ *   head       The follow's launch and cruise, in head units. A real head
+ *              reaches a 7-8° shift in about 0.4 s, its speed scaling with the
+ *              size of the shift; the shared amble took a thinking look 1.2 s,
+ *              and the reflex, doing its job, held the eyes in the corner of
+ *              the socket the whole way.
+ *
+ * `trunkFollow` is 0.3, under the line faces' 0.45. Live2D's face-tracking
+ * sample gives the body a third of the head's yaw (BodyAngleX 10 against
+ * AngleX 30; docs/research-head-rotation.md § 5 item 6), and that is the
+ * benchmark to sit at, not above. Here it matters for a reason a line face
+ * does not have: the neck's outline holds under a twist by construction
+ * (`morphs.neck_twist`), so the trunk's sway is what is left moving it — a
+ * quarter to a third of it at the yaw peak in the recorded call, read as the
+ * neck sliding. TARA-SPECIFIC in its evidence only: a second Blender avatar
+ * starts from 0.3 and checks its own outline at crop.
+ */
+export declare const TARA_TUNING: {
+    readonly prosodyHeadGain: 1;
+    readonly prosodyFaceGain: 1;
+    readonly saccadeGain: 2.4;
+    readonly aversionGain: 1.8;
+    readonly trunkFollow: 0.3;
+    readonly brows: {
+        readonly range: readonly [-0.28, 0.24];
+        readonly floor: 0.11;
+        readonly forms: readonly [{
+            readonly p: 0.38;
+            readonly inner: 0;
+            readonly angle: 0;
+        }, {
+            readonly p: 0.34;
+            readonly inner: 0.26;
+            readonly angle: 0;
+        }, {
+            readonly p: 0.28;
+            readonly inner: 0;
+            readonly angle: 0.3;
+        }];
+    };
+    readonly states: {
+        readonly WORKING: {
+            readonly pose: {
+                readonly headPitch: 0.04;
+                readonly lidL: -0.08;
+                readonly lidR: -0.08;
+                readonly shoulderL: 0.06;
+                readonly shoulderR: 0.06;
+            };
+        };
+        readonly CANT_HEAR: {
+            readonly pose: {
+                readonly torsoLean: 0.22;
+                readonly headPitch: 0.1;
+                readonly browRaiseL: -0.14;
+                readonly browRaiseR: -0.14;
+                readonly browInnerL: 0.22;
+                readonly browInnerR: 0.18;
+                readonly mouthPress: 0.4;
+                readonly mouthCornerL: -0.1;
+                readonly mouthCornerR: -0.1;
+            };
+        };
+        readonly SEARCHING_SCREEN: {
+            readonly pose: {
+                readonly mouthPress: 0.4;
+                readonly mouthCornerL: -0.08;
+                readonly mouthCornerR: -0.08;
+                readonly browRaiseL: -0.1;
+                readonly browRaiseR: -0.06;
+            };
+        };
+    };
+    readonly oculomotor: {
+        readonly angles: {
+            readonly eye: {
+                x: number;
+                y: number;
+            };
+            readonly head: {
+                x: number;
+                y: number;
+            };
+        };
+        readonly vor: {
+            readonly x: 0.8;
+            readonly y: 0.35;
+        };
+        readonly range: {
+            readonly x: 0.8;
+            readonly up: 0.45;
+            readonly down: 0.5;
+        };
+        readonly lidFollow: {
+            readonly down: 0.38;
+            readonly up: 0.3;
+        };
+        readonly avert: {
+            readonly eye: 0.45;
+            readonly head: 0.6;
+        };
+        readonly head: {
+            readonly accel: 16;
+            readonly speed: 3.5;
+        };
+        readonly targets: {
+            readonly OWN_SCREEN: {
+                readonly px: 0.14;
+                readonly py: 0.24;
+                readonly hx: 0.1;
+                readonly hy: 0.06;
+            };
+            readonly USER_EAR: {
+                readonly px: -0.2;
+                readonly py: 0.05;
+                readonly hx: 0.4;
+                readonly hy: 0.02;
+                readonly roll: 0.55;
+            };
+            readonly SCREEN_CENTER: {
+                readonly px: 0;
+                readonly py: -0.06;
+                readonly hx: 0;
+                readonly hy: -0.14;
+            };
+            readonly SCREEN_LEFT: {
+                readonly px: -0.42;
+                readonly py: -0.1;
+                readonly hx: -0.8;
+                readonly hy: -0.05;
+            };
+            readonly SCREEN_RIGHT: {
+                readonly px: 0.42;
+                readonly py: -0.1;
+                readonly hx: 0.8;
+                readonly hy: -0.05;
+            };
+            readonly SCREEN_TOP: {
+                readonly px: 0;
+                readonly py: -0.26;
+                readonly hx: 0;
+                readonly hy: -0.28;
+            };
+            readonly SCREEN_WORK: {
+                readonly px: -0.35;
+                readonly py: 0.18;
+                readonly hx: -0.55;
+                readonly hy: 0.12;
+            };
+            readonly AWAY_THINKING: {
+                readonly px: -0.3;
+                readonly py: -0.4;
+                readonly hx: -0.75;
+                readonly hy: -0.33;
+                readonly roll: 0.08;
+            };
+            readonly AWAY_RIGHT: {
+                readonly px: 0.3;
+                readonly py: -0.36;
+                readonly hx: 0.72;
+                readonly hy: -0.3;
+                readonly roll: -0.06;
+            };
+            readonly AWAY_DOWN: {
+                readonly px: -0.28;
+                readonly py: 0.45;
+                readonly hx: -0.62;
+                readonly hy: 0.16;
+                readonly roll: 0.04;
+            };
+            readonly AWAY_SIDE: {
+                readonly px: 0.32;
+                readonly py: 0.08;
+                readonly hx: 0.72;
+                readonly hy: 0.02;
+                readonly roll: -0.03;
+            };
+        };
+    };
+};
+export interface TaraRigOptions {
+    /** Called once the GLB is in the scene, for a capture tool that must wait. */
+    readonly onReady?: () => void;
+    /** The character's GLB, when it is not tara. The second-character seam: every
+     *  build fact the rig reads (jaw-shadow tile, rim depth, morph names) travels
+     *  in the GLB's own extras, so a character built by the same scripts needs
+     *  nothing else. Tara's tuning is still applied, which is the experiment. */
+    readonly url?: string;
+    /** `false` leaves an asset's expression maps unread, for a capture tool
+     *  comparing the face with and without them. */
+    readonly expression?: boolean;
+}
+/**
+ * The hair's roll, which is the one thing in this rig that is not a function of
+ * the pose alone.
+ *
+ * A hank that hangs past the jaw is lying on a shoulder, and a shoulder does not
+ * tilt when the head does. Rolled rigidly with the skull it lifts off the collar
+ * and the page shows through behind it, so the shell gives up `hold` of the
+ * roll at its lowest rows and none at the crown, graded by `morphs.hair_hold`.
+ * That is the static half and it is what fixes the gap.
+ *
+ * The other half is why roll read as a hinge at all. A rigid rotation about a
+ * fixed point is a hinge — there is nothing else in it — and what a real head
+ * tilt has that this lacked is hair that arrives late and settles. Live2D gives
+ * every hank a spring for exactly this (`docs/research-head-rotation.md` § 3.1:
+ * mobility ~0.95, delay 0.8-0.9, one clear overshoot), so this is a spring on
+ * the hair's own angle chasing the share of the roll it agrees to take.
+ *
+ * It is on the hair and not on the head's channels on purpose. The mixer's
+ * per-channel time constants are shared with the SVG faces and every clip in the
+ * library is authored pre-compensated for them, so a spring on `headRoll` would
+ * silently re-time every nod ever authored. Secondary motion on a shell that
+ * only this renderer has costs nothing outside it.
+ *
+ * 1.5 Hz is the band the library already keeps gesture under, and a hank of hair
+ * on a real head swings near it (a 7 cm pendulum is 1.9 Hz); the damping is a
+ * single visible overshoot, settling inside 0.8 s. Faster reads as a flick and
+ * slower as wet hair.
+ */
+/**
+ * `hold` is the share of the head's roll the hanging hair declines to take, and
+ * `hz`/`damping` are how it gets there. 1.5 Hz is the ceiling the repo's idle
+ * constraint sets on *driven* oscillation; a settle is a one-shot and could
+ * defensibly go faster, but there is no reason to spend the exemption: what
+ * unhinges the roll is the hair arriving late, not the ring. At 0.65 it trails
+ * by 93% of its travel a frame in, overshoots 5% and is inside 5% of the hold in
+ * 450 ms — well within a phrase's hold.
+ */
+export declare const HAIR_ROLL: {
+    hold: number;
+    hz: number;
+    damping: number;
+};
+/**
+ * One step of `HAIR_ROLL`'s spring: semi-implicit, the rate taking the frame's
+ * acceleration before the angle takes the rate. Explicit Euler rings at this
+ * stiffness and 30 fps; this does not, which is the only reason the order of
+ * those two lines is worth a sentence.
+ *
+ * Exported for `test/nods.test.ts`, because settle time and overshoot are
+ * numbers and not something a still frame can show. It is not part of the
+ * package's surface — `packages/avatar/client/tara.ts` is.
+ */
+export declare const hairRollStep: (angle: number, rate: number, target: number, dt: number) => {
+    angle: number;
+    rate: number;
+};
+export declare function createTaraRig(mount: HTMLElement, options?: unknown): AvatarRig;
+//# sourceMappingURL=tara-rig.d.ts.map

package/dist/three/tara-rig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tara-rig.d.ts","sourceRoot":"","sources":["../../client/three/tara-rig.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAe,SAAS,EAAW,MAAM,gBAAgB,CAAC;AAmBtE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAKH,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,QAAQ;;;;CAAkC,CAAC;AAyIxD;;;;;;qDAMqD;AACrD,eAAO,MAAM,OAAO;;;CAA2G,CAAC;AAGhI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiJd,CAAC;AA8bX,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B;;;iFAG6E;IAC7E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;oDACgD;IAChD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;CAC/B;AAsID;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS;;;;CAAyC,CAAC;AAEhE;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,EAAE,QAAQ,MAAM,EAAE,IAAI,MAAM;;;CAInF,CAAC;AAkCF,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CA4Z9E"}