@voqalize/avatar 0.4.1 → 0.4.3

package/client/three/createCharacter.ts

@@ -0,0 +1,109 @@
+/**
+ * `createCharacter` — the Blender characters' entry point, and the other end of
+ * the fork agreed on 2026-09-17 (*"Aligned that we fork"*).
+ *
+ * There are two `createAvatar` implementations in this package now, not one
+ * with a branch in it. `client/createAvatar.ts` mounts a drawing: a `Face`
+ * record, a theme, the frame-edge hand. This one mounts a compiled head: a GLB
+ * url, the shared rig, the house performance. They are separate because almost
+ * every option the second one passes exists to *undo* something the first one
+ * assumes — no hand, no theme, clips whose keys are degrees rather than ink —
+ * and threading one more per-avatar option through a shared entry point is the
+ * smell rather than the fix.
+ *
+ * **What is not forked is the mixer.** Both entry points resolve their options
+ * and hand them to the same `createSvgAvatar`, which still does states, layers,
+ * gaze, idle, blinks, clips and per-channel smoothing for every face in the
+ * package. Forking *that* would give two copies of the smoothing law, and the
+ * smoothing law is the thing a clip's keyframes are authored against
+ * (docs/internal-mixer.md § Smoothing) — two copies of it drift, and the drift
+ * is invisible until a nod reads wrong on one character only.
+ *
+ * A character module is therefore its GLB and its name:
+ *
+ *     export const supports = BLENDER_SUPPORTS;
+ *     export const createAvatar = character("tara", TARA_GLB);
+ *
+ * and everything else about how a Blender character is driven is here, once.
+ */
+
+import type { PipecatClient } from "@pipecat-ai/client-js";
+import { AvatarClient, createSvgAvatar } from "../internal.js";
+import type { AvatarFactory, AvatarInstance, AvatarOptions } from "../createAvatar.js";
+import { BLENDER_ACTIONS, BLENDER_SEQUENCES } from "./sequences.js";
+import { headHold } from "./holds.js";
+import { createCharacterRig, CHARACTER_TUNING } from "./character-rig.js";
+import type { CharacterRigOptions } from "./character-rig.js";
+
+/**
+ * What every Blender character takes — the two options every avatar shares,
+ * plus the three gains.
+ *
+ * There is no `face`, no `theme` and no `hand`: a compiled character is one
+ * drawing with one palette baked into its atlas, and it has no arms. There is
+ * no `url` either, because the character *is* the module you imported.
+ */
+export interface CharacterAvatarOptions extends AvatarOptions {
+  /** 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 type { AvatarInstance };
+
+/**
+ * One Blender character's `createAvatar`, bound to its name and its mesh.
+ *
+ * `name` is not a lookup key — nothing resolves a character by it and there is
+ * no table to miss. It selects this face's row in `motion-limits.json`, which
+ * is the one per-character fact that is neither in the GLB nor in the rig:
+ * the angles a person read off the face by eye, which no build can derive
+ * (`holds.ts`).
+ */
+export function character(name: Parameters<typeof headHold>[0], url: string):
+    AvatarFactory<CharacterAvatarOptions> {
+  const hold = headHold(name);
+  return function createAvatar(options: CharacterAvatarOptions): AvatarInstance {
+    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: CharacterRigOptions = { onReady, url };
+    // `hand: false` disables the bundled SVG hand renderer only; the semantic
+    // hand frame still reaches the rig, which ignores it — these characters
+    // have no arms, and that is the library's oldest standing constraint
+    // rather than an omission.
+    //
+    // `sequences` is what a server can address on a Blender character beyond
+    // the two ids every avatar owes it — the three nod types the listening
+    // research separates, and a head shake sized for a rig whose pose unit is
+    // a degree. The wire's action id is open, so nothing here needed
+    // promoting: a server that does not know which face is mounted sends
+    // `ACKNOWLEDGE` and is never wrong. `actions` is the other half, the
+    // Blender shape for an id the mixer already has, whose shared keys land
+    // outside what they mean on a head that turns in degrees.
+    const widget = createSvgAvatar({
+      mount, rig: createCharacterRig, rigOptions, hand: false,
+      sequences: BLENDER_SEQUENCES, actions: BLENDER_ACTIONS, ...CHARACTER_TUNING,
+      headHold: hold, ...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();
+      },
+    };
+  };
+}

package/client/three/holds.ts

@@ -3,12 +3,16 @@
  * pose units per axis, ready to hand to `createSvgAvatar` as `headHold`.
  *
  * The angles themselves are in `motion-limits.json` and are only
- * there. They were read off the three faces by the person who owns how they
+ * there. They were read off the faces by the person who owns how they
  * look, one axis at a time, at the surface a call actually shows — which is
  * the only way this kind of number can be got, and the reason nothing here
  * recomputes, adjusts or second-guesses one. This file is the unit change and
  * nothing else.
  *
+ * An axis the file never carried is the same case, and a character built but
+ * not yet driven by the owner has none of them: the file says so instead of
+ * carrying a number nobody read, and the fallback below is what holds her.
+ *
  * An axis the file marks for re-measurement is not enforced: it was read off an
  * asset that has since been fixed, and holding the driver to a defect that no
  * longer exists is worse than the defect. It falls back to the tightest angle
@@ -22,7 +26,7 @@
  */
 
 import LIMITS from "./motion-limits.json" with { type: "json" };
-import { HEAD_CLAMP, HEAD_DEG } from "./tara-rig.js";
+import { HEAD_CLAMP, HEAD_DEG } from "./character-rig.js";
 
 /** Degrees of each axis per pose unit, which is `HEAD_DEG` at the clamp. */
 const PER_UNIT = {
@@ -52,7 +56,8 @@ function safest(axis: string): number | undefined {
   return angles.length ? Math.min(...angles) : undefined;
 }
 
-/** `name` as the limits file spells it: tara, tushar, tanya. */
+/** `name` as the limits file spells it — a character with no live axis there
+ *  is held to the tightest budget any other is still vouched for. */
 export function headHold(name: keyof typeof LIMITS.characters): HeadHold {
   const out: HeadHold = {};
   for (const channel of Object.keys(AXIS) as (keyof typeof AXIS)[]) {

package/client/three/internal.ts

@@ -1,11 +1,11 @@
 /**
  * The 2.5-D rig, below the `createAvatar` modules — `/internal`, no semver promise.
  *
- * `tara.ts`, `tushar.ts` and `tanya.ts` are what a consumer gets: one
- * `createAvatar` each, the mixer behind it, nothing to configure. This is the
- * other door, for a page whose subject is the *rig* rather than the call — the
- * renderer with no mixer in front of it, the three compiled characters, and the
- * head envelope their channels are scaled by. Its readers are the rig instruments
+ * A character's own module — `tara.ts`, `tushar.ts`, `tanya.ts`, `tess.ts`, `tanvi.ts` — is
+ * what a consumer gets: one `createAvatar` each, the mixer behind it, nothing to
+ * configure. This is the other door, for a page whose subject is the *rig*
+ * rather than the call — the renderer with no mixer in front of it, every
+ * compiled character, and the head envelope their channels are scaled by. Its readers are the rig instruments
  * in the working tree, and nothing that ships.
  *
  * It exists because those instruments were reaching around the package instead,
@@ -18,8 +18,9 @@
 export { ASSETS as CHARACTERS } from "./assets.js";
 export type { CharacterName } from "./assets.js";
 
-export { createTaraRig, EYE_DEG, HEAD_CLAMP, HEAD_DEG, TARA_TUNING } from "./tara-rig.js";
-export type { TaraRigOptions } from "./tara-rig.js";
+export { createCharacterRig, EYE_DEG, HEAD_CLAMP, HEAD_DEG, CHARACTER_TUNING,
+  HEAD_PARTS, PIVOT, ROLL_PIVOT } from "./character-rig.js";
+export type { CharacterRigOptions } from "./character-rig.js";
 export { HARD_BUDGET, pixelRatioFor, SHIPPING_SURFACE } from "./budgets.js";
 
 /**

package/client/three/motion-limits.json

@@ -1,6 +1,6 @@
 {
  "what": "How far each character may HOLD its head off centre, in degrees, measured by eye. A sustained pose is the strict case and this is the strict number: past it a static turn stops reading as a head that turned, because the eye behind a flat projection never foreshortens. `holds.ts` converts these into the mixer's pose units and `test/three/presence.test.ts` gates LISTENING and SPEAKING against them.",
- "versus": "This is not `HEAD_DEG` and is much smaller than it. `HEAD_DEG` (tara-rig.ts) is the envelope any motion may REACH — set by where the projection itself tears, which a rendered ladder put past 21 degrees of yaw on tara. A transient that returns is forgiven what a held pose is not, so a nod may pass through an angle this file will not let the head sit at.",
+ "versus": "This is not `HEAD_DEG` and is much smaller than it. `HEAD_DEG` (character-rig.ts) is the envelope any motion may REACH — set by where the projection itself tears, which a rendered ladder put past 21 degrees of yaw on tara. A transient that returns is forgiven what a held pose is not, so a nod may pass through an angle this file will not let the head sit at.",
  "units": "degrees from rest, either side, per axis driven alone from rest",
  "surface": {
   "cssWidth": 400,
@@ -110,7 +110,15 @@
      "fixed": "2026-09-19"
     }
    ]
+  },
+  "tess": {
+   "unmeasured": "Nothing here has been read off her. She was built on 2026-09-20 and the owner has not driven her yet, so this entry carries no angle at all rather than a plausible one: `holds.ts` falls back to the tightest angle still live on each axis, which is the budget the faces nobody doubts are already held to. Drive her with the hold-and-move instrument and this becomes the same shape as the entries above.",
+   "defects": []
+  },
+  "tanvi": {
+   "unmeasured": "Nothing here has been read off her. She was built on 2026-09-23 and the owner has not driven her yet, so this entry carries no angle at all rather than a plausible one: `holds.ts` falls back to the tightest angle still live on each axis. Drive her with the hold-and-move instrument and this becomes the same shape as the entries above.",
+   "defects": []
   }
  },
- "remeasure": "An axis carrying `remeasure` was measured on an asset that has since changed. It stays as written \u2014 a measurement is not edited by someone who did not make it \u2014 and a gate skips it and says so."
+ "remeasure": "An axis carrying `remeasure` was measured on an asset that has since changed. It stays as written — a measurement is not edited by someone who did not make it — and a gate skips it and says so."
 }

package/client/three/sequences.ts

@@ -262,13 +262,13 @@ void (BLENDER_ACTIONS satisfies Partial<Record<keyof typeof ACTIONS, Sequence>>)
  * What every character in this package answers to — each one's `supports`, the
  * optional declaration a driving UI reads (`AvatarSupport`).
  *
- * Derived rather than written down, because the three parts already exist: the
- * two ids every avatar owes a server, the mixer's own clip catalogue these
- * characters inherit whole, and this file's own names. A hand-kept fourth copy
- * would only be able to disagree with them. `BLENDER_ACTIONS` adds nothing —
+ * Derived rather than written down, because every part of it already exists: the
+ * ids every avatar owes a server, the mixer's own clip catalogue these
+ * characters inherit whole, and this file's own names. A hand-kept copy beside
+ * them would only be able to disagree with them. `BLENDER_ACTIONS` adds nothing —
  * it re-shapes an id the mixer already has.
  *
- * It is one list for tara, tushar and tanya for the same reason the tables are:
+ * It is one list for every 2.5-D character for the same reason the tables are:
  * they are one rig driven through one set of channels. A character that stops
  * being able to do one of these owes its own `supports`, not an edit here.
  */

package/client/three/tanvi-asset.ts

@@ -0,0 +1,6 @@
+/**
+ * Where tanvi's compiled GLB is. One character, one module — see
+ * [tara-asset.ts](./tara-asset.ts) for why that separation is load-bearing and
+ * why the `new URL` literal is spelled exactly this way.
+ */
+export const TANVI_GLB = new URL("../../assets/tanvi.glb", import.meta.url).href;

package/client/three/tanvi.ts

@@ -0,0 +1,30 @@
+/**
+ * tanvi — Indian, and the first character whose hair is not part of her head.
+ *
+ * Her GLB is the shared scripts run with her landmarks (`characters/tanvi/`).
+ * Her long waves fall past both shoulders onto her chest, which a `Hair` shell
+ * painted into the head's atlas cannot carry: it can only be where the head is.
+ * So her photograph is split into her with the hair pulled back, which is what
+ * every other script reads, and the hair alone, which becomes a `HairLayer`
+ * mesh of its own — turning with the skull, holding back its share of a roll
+ * like tanya's hanging hair, lifting with the shoulders below the chin, and
+ * drawn over everything behind it (`character-rig.ts`).
+ *
+ * Her head angles have not been read off her yet. `motion-limits.json` says so
+ * rather than guessing, and `headHold` gives her the tightest budget any face
+ * is still vouched for until the owner drives her.
+ */
+
+import { character } from "./createCharacter.js";
+import type { CharacterAvatarOptions } from "./createCharacter.js";
+import { BLENDER_SUPPORTS } from "./sequences.js";
+import { TANVI_GLB } from "./tanvi-asset.js";
+
+export type { CharacterAvatarOptions as AvatarOptions };
+export type { AvatarInstance } from "./createCharacter.js";
+
+/** The optional driving-UI declaration; one list for every Blender character
+ *  (`sequences.ts`), because they are one rig. */
+export const supports = BLENDER_SUPPORTS;
+
+export const createAvatar = character("tanvi", TANVI_GLB);

package/client/three/tanya.ts

@@ -1,69 +1,29 @@
 /**
- * tanya — the third 3-D character, and like `tushar.ts` a copy of `tara.ts`.
+ * tanya — the third 3-D character, and the first whose atlas is not tara's
+ * window.
  *
- * 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`.
+ * Her GLB is the shared scripts run with her landmarks and atlas layout
+ * (`characters/tanya/`, whose README has the provenance and the commands).
+ * 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.
  *
- * 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.
+ * Hair that hangs is what else makes her the third rather than a fourth copy:
+ * hers is the only `Hair` mesh that carries the roll channels, because it is
+ * the only one with anything below the hold line to lag behind a tilt.
  */
 
-import type { PipecatClient } from "@pipecat-ai/client-js";
-import { AvatarClient, createSvgAvatar } from "../internal.js";
+import { character } from "./createCharacter.js";
+import type { CharacterAvatarOptions } from "./createCharacter.js";
+import { BLENDER_SUPPORTS } from "./sequences.js";
 import { TANYA_GLB } from "./tanya-asset.js";
-import { BLENDER_ACTIONS, BLENDER_SEQUENCES, BLENDER_SUPPORTS } from "./sequences.js";
-import { headHold } from "./holds.js";
-import { createTaraRig, TARA_TUNING } from "./tara-rig.js";
-import type { TaraRigOptions } from "./tara-rig.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 type { CharacterAvatarOptions as AvatarOptions };
+export type { AvatarInstance } from "./createCharacter.js";
 
-export interface AvatarInstance { destroy(): void; }
-
-/** The optional driving-UI declaration; one list for all three characters
+/** The optional driving-UI declaration; one list for every Blender character
  *  (`sequences.ts`), because they are one rig. */
 export const supports = BLENDER_SUPPORTS;
 
-export function createAvatar(options: AvatarOptions): AvatarInstance {
-  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: TaraRigOptions = { onReady, url: TANYA_GLB };
-  // 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();
-    },
-  };
-}
+export const createAvatar = character("tanya", TANYA_GLB);

package/client/three/tara.ts

@@ -4,74 +4,33 @@
  * Structurally this is the canvas avatars' shape, one layer down: the mixer
  * (`@voqalize/avatar/internal`) does states, layers, gaze, idle, blinks, clips
  * and per-channel smoothing exactly as it does for every SVG face, and the only
- * thing tara replaces is the renderer at the end of it. That is the whole
- * argument for authoring her morph targets under the library's pose-channel
- * names: nothing above this line knows there is a GPU involved, and every clip,
- * viseme and co-articulation rule the SVG faces have works here unmodified.
+ * thing a Blender character replaces is the renderer at the end of it. That is
+ * the whole argument for authoring her morph targets under the library's pose
+ * channel names: nothing above this line knows there is a GPU involved, and
+ * every clip, viseme and co-articulation rule the SVG faces have works here
+ * unmodified.
+ *
+ * How a Blender character is driven is `createCharacter.ts`, and it is the same
+ * for all of them. What is hers is the mesh — and, until 2026-09-23, rather
+ * more than that: this file was the original, the others were copies of it, and
+ * the performance every character inherits was measured on her face. It is the
+ * house performance now (`CHARACTER_TUNING`), which changes nothing about how
+ * she looks and everything about where it is decided.
  *
  * The Three.js import lives behind this module rather than in the barrel so an
  * SVG or Canvas consumer never downloads it.
  */
 
-import type { PipecatClient } from "@pipecat-ai/client-js";
-import { AvatarClient, createSvgAvatar } from "../internal.js";
-import { BLENDER_ACTIONS, BLENDER_SEQUENCES, BLENDER_SUPPORTS } from "./sequences.js";
+import { character } from "./createCharacter.js";
+import type { CharacterAvatarOptions } from "./createCharacter.js";
+import { BLENDER_SUPPORTS } from "./sequences.js";
 import { TARA_GLB } from "./tara-asset.js";
-import { headHold } from "./holds.js";
-import { createTaraRig, TARA_TUNING } from "./tara-rig.js";
-import type { TaraRigOptions } from "./tara-rig.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; }
+export type { CharacterAvatarOptions as AvatarOptions };
+export type { AvatarInstance } from "./createCharacter.js";
 
-/** The optional driving-UI declaration; one list for all three characters
+/** The optional driving-UI declaration; one list for every Blender character
  *  (`sequences.ts`), because they are one rig. */
 export const supports = BLENDER_SUPPORTS;
 
-export function createAvatar(options: AvatarOptions): AvatarInstance {
-  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: TaraRigOptions = { onReady, url: TARA_GLB };
-  // `hand: false` disables the bundled SVG hand renderer only; the semantic
-  // hand frame still reaches the rig, which ignores it — tara has no arms, and
-  // that is the library's oldest standing constraint rather than an omission.
-  // `sequences` is what a server can address on *this* avatar beyond the two
-  // ids every avatar owes it — the three nod types the listening research
-  // separates, and a head shake sized for a rig whose pose unit is a degree.
-  // The wire's action id is open, so nothing here needed promoting; a server
-  // that does not know tara is mounted sends `ACKNOWLEDGE` and is never wrong.
-  // `actions` is the other half: her own shape for an id the mixer already has,
-  // whose shared keys land outside what it means on a head that turns in degrees.
-  const widget = createSvgAvatar({
-    mount, rig: createTaraRig, rigOptions, hand: false,
-    sequences: BLENDER_SEQUENCES, actions: BLENDER_ACTIONS, ...TARA_TUNING,
-    headHold: headHold("tara"), ...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();
-    },
-  };
-}
+export const createAvatar = character("tara", TARA_GLB);

package/client/three/tess-asset.ts

@@ -0,0 +1,6 @@
+/**
+ * Where tess's compiled GLB is. One character, one module — see
+ * [tara-asset.ts](./tara-asset.ts) for why that separation is load-bearing and
+ * why the `new URL` literal is spelled exactly this way.
+ */
+export const TESS_GLB = new URL("../../assets/tess.glb", import.meta.url).href;

package/client/three/tess.ts

@@ -0,0 +1,30 @@
+/**
+ * tess — American, and the leanest character in the forge.
+ *
+ * Her GLB is the shared scripts run with her landmarks (`characters/tess/`,
+ * whose README has the provenance and the commands). She is back inside tara's
+ * atlas window — her hair is drawn into a low tail that clears both ears and
+ * reaches |u| 0.492 against a window that stops at 0.64 — so unlike tanya she
+ * needs no `face_texture.py` of her own, and her `Hair` shell gives up no roll:
+ * nothing of hers hangs past the jaw to lag. One supplied sheet, no paid edit,
+ * no module of her own; she is what a new character costs at the floor, which
+ * is why the README builds its template from her.
+ *
+ * Her head angles have not been read off her yet. `motion-limits.json` says so
+ * rather than guessing, and `headHold` gives her the tightest budget any face
+ * is still vouched for until the owner drives her.
+ */
+
+import { character } from "./createCharacter.js";
+import type { CharacterAvatarOptions } from "./createCharacter.js";
+import { BLENDER_SUPPORTS } from "./sequences.js";
+import { TESS_GLB } from "./tess-asset.js";
+
+export type { CharacterAvatarOptions as AvatarOptions };
+export type { AvatarInstance } from "./createCharacter.js";
+
+/** The optional driving-UI declaration; one list for every Blender character
+ *  (`sequences.ts`), because they are one rig. */
+export const supports = BLENDER_SUPPORTS;
+
+export const createAvatar = character("tess", TESS_GLB);

package/client/three/tushar.ts

@@ -1,65 +1,28 @@
 /**
- * tushar — the second 3-D character, and deliberately a copy of `tara.ts`.
+ * tushar — the second 3-D character, and the one who proved the factory.
  *
- * His GLB is tara's scripts run with his landmarks and atlas layout in place of
- * hers (`characters/tushar/`, 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`. What turns out to be hers rather than
- * general is marked TARA-SPECIFIC where it lives, and generalised only once a
- * third character agrees.
+ * His GLB is the shared scripts run with his landmarks and atlas layout in
+ * place of tara's (`characters/tushar/`, whose README has the provenance and
+ * the commands). He was a deliberate copy of `tara.ts` for as long as there was
+ * a `tara.ts` to copy; since 2026-09-23 there is one Blender entry point and he
+ * is its second caller rather than her second draft (`createCharacter.ts`).
+ *
+ * He is also the face that turned the ledger from a question into a decision.
+ * What was marked TARA-SPECIFIC was marked that way because one face cannot
+ * tell a convention from a coincidence; he agreed with her, and so did the two
+ * after him.
  */
 
-import type { PipecatClient } from "@pipecat-ai/client-js";
-import { AvatarClient, createSvgAvatar } from "../internal.js";
+import { character } from "./createCharacter.js";
+import type { CharacterAvatarOptions } from "./createCharacter.js";
+import { BLENDER_SUPPORTS } from "./sequences.js";
 import { TUSHAR_GLB } from "./tushar-asset.js";
-import { BLENDER_ACTIONS, BLENDER_SEQUENCES, BLENDER_SUPPORTS } from "./sequences.js";
-import { headHold } from "./holds.js";
-import { createTaraRig, TARA_TUNING } from "./tara-rig.js";
-import type { TaraRigOptions } from "./tara-rig.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; }
+export type { CharacterAvatarOptions as AvatarOptions };
+export type { AvatarInstance } from "./createCharacter.js";
 
-/** The optional driving-UI declaration; one list for all three characters
+/** The optional driving-UI declaration; one list for every Blender character
  *  (`sequences.ts`), because they are one rig. */
 export const supports = BLENDER_SUPPORTS;
 
-export function createAvatar(options: AvatarOptions): AvatarInstance {
-  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: TaraRigOptions = { onReady, url: TUSHAR_GLB };
-  // TARA-SPECIFIC, kept on purpose: `TARA_TUNING` (her mouth and motion gains)
-  // is the first thing to question if he reads wrong in a call.
-  const widget = createSvgAvatar({
-    mount, rig: createTaraRig, rigOptions, hand: false,
-    sequences: BLENDER_SEQUENCES, actions: BLENDER_ACTIONS, ...TARA_TUNING,
-    headHold: headHold("tushar"), ...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();
-    },
-  };
-}
+export const createAvatar = character("tushar", TUSHAR_GLB);

package/dist/internal.d.ts

@@ -21,8 +21,8 @@
  * renderer uses internally. It is *not* the seam to implement — see
  * docs/design-avatar-interface.md.
  */
-export { createAvatar as createSvgAvatar, REST, CHANNELS, RANGE, STATES, STATE_NAMES, ACTIONS, ACTION_IDS, GAZE_NAMES, GAZE_TARGETS, EMOTION_NAMES, VisemeTrack, VISEME_LETTERS, VISEME_SHAPES, SILENT, LEAD_MS, SHOULDER_TILT, shapeFor, normalizeCues, textToCues, ARPABET_TO_VISEME, AZURE_VISEME_TO_LETTER, } from "../src/avatar.js";
-export type { AvatarApi, AvatarStateName, AvatarActionId, AvatarGazeName, AvatarEmotionName, AvatarAction, AvatarMeta, VisemeLetter, Cue, PoseChannel, PoseOverrides, CreateAvatarOptions as CreateSvgAvatarOptions, } from "../src/avatar.js";
+export { createAvatar as createSvgAvatar, REST, CHANNELS, RANGE, STATES, STATE_NAMES, ACTIONS, ACTION_IDS, GAZE_NAMES, GAZE_TARGETS, EMOTION_NAMES, VisemeTrack, VISEME_LETTERS, VISEME_SHAPES, SILENT, LEAD_MS, SHOULDER_TILT, INTERNAL_CLIPS, ClipPlayer, TAU, clamp, approach, makeParams, emotionPose, avatarFrame, createSvgRig, shapeFor, JAW_OF_OPEN, normalizeCues, textToCues, ARPABET_TO_VISEME, AZURE_VISEME_TO_LETTER, } from "../src/avatar.js";
+export type { Clip, ClipSample, AvatarApi, AvatarStateName, AvatarActionId, AvatarGazeName, AvatarEmotionName, AvatarAction, AvatarMeta, VisemeLetter, Cue, PoseChannel, PoseOverrides, CreateAvatarOptions as CreateSvgAvatarOptions, } from "../src/avatar.js";
 export type { AvatarFrame, AvatarRig, AvatarRigFactory, HandFrame, RigPose, } from "../src/rig.js";
 export { BEHAVIOR_STATE_IDS, BEHAVIOR_ACTIONS, BEHAVIOR_ACTION_IDS, WIRE_ACTION_TO_BEHAVIOR, } from "../src/behavior.js";
 export type { BehaviorStateId, BehaviorActionId } from "../src/behavior.js";

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../client/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,YAAY,IAAI,eAAe,EAG/B,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EAEb,WAAW,EACX,cAAc,EACd,aAAa,EACb,MAAM,EACN,OAAO,EAEP,aAAa,EACb,QAAQ,EACR,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,SAAS,EACT,eAAe,EACf,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,GAAG,EACH,WAAW,EACX,aAAa,EACb,mBAAmB,IAAI,sBAAsB,GAC9C,MAAM,kBAAkB,CAAC;AAK1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,OAAO,GACR,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAM9D,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../client/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAIL,YAAY,IAAI,eAAe,EAG/B,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EAEb,WAAW,EACX,cAAc,EACd,aAAa,EACb,MAAM,EACN,OAAO,EAEP,aAAa,EAMb,cAAc,EACd,UAAU,EACV,GAAG,EACH,KAAK,EACL,QAAQ,EAKR,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EAIR,WAAW,EACX,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,YAAY,EACV,IAAI,EACJ,UAAU,EACV,SAAS,EACT,eAAe,EACf,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,GAAG,EACH,WAAW,EACX,aAAa,EACb,mBAAmB,IAAI,sBAAsB,GAC9C,MAAM,kBAAkB,CAAC;AAK1B,YAAY,EACV,WAAW,EACX,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,OAAO,GACR,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAE5B,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE5E,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAM9D,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EACV,aAAa,EACb,SAAS,EACT,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/internal.js

@@ -32,7 +32,22 @@ REST, CHANNELS, RANGE, STATES, STATE_NAMES, ACTIONS, ACTION_IDS, GAZE_NAMES, GAZ
 // The viseme clock and its tables.
 VisemeTrack, VISEME_LETTERS, VISEME_SHAPES, SILENT, LEAD_MS, 
 // The body's share of a held tilt, for a page driving a rig by hand.
-SHOULDER_TILT, shapeFor, normalizeCues, textToCues, ARPABET_TO_VISEME, AZURE_VISEME_TO_LETTER, } from "../src/avatar.js";
+SHOULDER_TILT, 
+// Stepping a gesture by hand: the catalogue, the player, and the smoothing
+// law the mixer puts between a clip's keyframes and the face. A filmstrip
+// instrument needs all three, and the one thing it must not do is fork the
+// smoothing — that is the part a keyframe is authored against
+// (docs/internal-mixer.md § Smoothing).
+INTERNAL_CLIPS, ClipPlayer, TAU, clamp, approach, 
+// Posing a face directly, with no mixer, no clock and no client above it —
+// what a pose sheet or a rig-conformance page does. `makeParams` fills the
+// rests around a handful of overrides, `emotionPose` names a familiar set of
+// them, `avatarFrame` wraps the result and `createSvgRig(face)` draws it.
+makeParams, emotionPose, avatarFrame, createSvgRig, shapeFor, 
+// The one number that says how far the mandible falls for a given aperture.
+// Anything composing a mouth pose without `shapeFor` — a retarget, a driver —
+// needs it, and the amplitudes behind the lips are calibrated at it.
+JAW_OF_OPEN, normalizeCues, textToCues, ARPABET_TO_VISEME, AZURE_VISEME_TO_LETTER, } from "../src/avatar.js";
 export { BEHAVIOR_STATE_IDS, BEHAVIOR_ACTIONS, BEHAVIOR_ACTION_IDS, WIRE_ACTION_TO_BEHAVIOR, } from "../src/behavior.js";
 export { isAvatarMessage, CORE_ACTION_IDS } from "./types.js";
 // A renderer may reuse the one lifecycle/precedence ladder without gaining a

package/dist/internal.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal.js","sourceRoot":"","sources":["../client/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO;AACL,2EAA2E;AAC3E,0DAA0D;AAC1D,8DAA8D;AAC9D,YAAY,IAAI,eAAe;AAC/B,8EAA8E;AAC9E,oBAAoB;AACpB,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa;AACb,mCAAmC;AACnC,WAAW,EACX,cAAc,EACd,aAAa,EACb,MAAM,EACN,OAAO;AACP,qEAAqE;AACrE,aAAa,EACb,QAAQ,EACR,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AA4B1B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAO9D,6EAA6E;AAC7E,kCAAkC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../client/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO;AACL,2EAA2E;AAC3E,0DAA0D;AAC1D,8DAA8D;AAC9D,YAAY,IAAI,eAAe;AAC/B,8EAA8E;AAC9E,oBAAoB;AACpB,IAAI,EACJ,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,YAAY,EACZ,aAAa;AACb,mCAAmC;AACnC,WAAW,EACX,cAAc,EACd,aAAa,EACb,MAAM,EACN,OAAO;AACP,qEAAqE;AACrE,aAAa;AACb,2EAA2E;AAC3E,0EAA0E;AAC1E,2EAA2E;AAC3E,8DAA8D;AAC9D,wCAAwC;AACxC,cAAc,EACd,UAAU,EACV,GAAG,EACH,KAAK,EACL,QAAQ;AACR,2EAA2E;AAC3E,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,UAAU,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ;AACR,4EAA4E;AAC5E,8EAA8E;AAC9E,qEAAqE;AACrE,WAAW,EACX,aAAa,EACb,UAAU,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AA8B1B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAO9D,6EAA6E;AAC7E,kCAAkC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}