@voqalize/avatar 0.4.1 → 0.4.2

package/README.md

@@ -5,10 +5,11 @@ avatars are lip-synced to the audio and they are state aware: they know when
 they have been interrupted, when the user is talking versus idle, when a tool
 call has started and stopped.
 
-No video track, no per-minute avatar vendor, no second media path. Twelve
-avatars ship with it — three SVG faces, six professional Canvas2D identities and
-three 2.5-D characters — one per entry point, so you pay for the one you import,
-and you can author your own.
+No video track, no per-minute avatar vendor, no second media path. SVG faces
+and 2.5-D characters ship with it, one per entry point, so you pay for the one
+you import, and you can author your own. Canvas2D identities also ship and are
+frozen: they still work, they get no further work,
+and they come out in 0.5.0 (below).
 
 This is the browser half. The pipeline half is
 [`voqalize-avatar`](https://pypi.org/project/voqalize-avatar/) on PyPI; they are
@@ -16,10 +17,10 @@ two ends of one wire format and release independently, kept compatible by the
 wire contract rather than a shared version number
 ([RELEASING.md § Compatibility](https://github.com/voqalize/avatar/blob/main/RELEASING.md#compatibility)).
 
-**Licence: MIT for the code, CC-BY 4.0 for the three 2.5-D character binaries**
-(`assets/*.glb`, the artwork — see `assets/README.md` for the credit line). The
-code is usable anywhere, including in closed-source products; the characters ask
-for attribution and nothing else. The manifest declares the pair as
+**Licence: MIT for the code and the SVG and Canvas2D avatars, CC-BY 4.0 for the
+2.5-D character binaries** (`assets/*.glb` — see `assets/README.md` for the
+credit line). Which applies is decided by the kind of avatar, so adding a
+character never moves the line. The manifest declares the pair as
 `MIT AND CC-BY-4.0`.
 
 ## Install
@@ -85,14 +86,14 @@ always the renderer's.
 
 What is left over is small, specific, and each item is a case the library
 refuses to guess at — a deliberate nod or greeting, a tool whose calls never
-enter your pipeline, a pose richer than the nine states, a backend that is not
+enter your pipeline, a pose richer than the core states, a backend that is not
 ours. [The architecture
 page](https://github.com/voqalize/avatar/blob/main/docs/architecture.md) is the
 canonical reference for all of it.
 
 ## The wire protocol
 
-Three commands, one envelope
+`state`, `action` and `cues`, one envelope
 ([contract-wire.md](https://github.com/voqalize/avatar/blob/main/docs/contract-wire.md)):
 
 ```json
@@ -113,16 +114,16 @@ Emission is overwrite, never merge: a `cues` message says "discard everything
 queued at or after `from_ms`, then append these". The server decides; the client
 has no say and no way to refuse.
 
-**Not using our backend?** Any server can produce cues, three ways, best first.
+**Not using our backend?** Any server can produce cues; the ways, best first:
 If your TTS emits native viseme events, map the integer ids through
 `AZURE_VISEME_TO_LETTER` and ship `{t, v}` as they stream. Otherwise force-align
 the text against the audio and map ARPAbet through `ARPABET_TO_VISEME`. With no
 server work at all, `textToCues(text)` is a crude grapheme guesser, fit for
-previews only. All three are exported from `@voqalize/avatar/internal`.
+previews only. Each is exported from `@voqalize/avatar/internal`.
 
 ## The faces
 
-Three ship today, all hand-authored line art: **`peep`** (the default),
+All hand-authored line art: **`peep`** (the default),
 **`wren`**, **`myna`**. Each is its own entry point, and you pass the value
 rather than a name:
 
@@ -133,11 +134,18 @@ createAvatar({ mount, client, face: myna });
 ```
 
 A name would need a table, and a table is a dynamic index no bundler can shake —
-three drawings in every consumer's bundle to render one.
+every drawing in every consumer's bundle to render one.
 
-## Professional avatars
+## Professional avatars — frozen, removed in 0.5.0
 
-Six complete, code-authored avatars ship as their own `createAvatar` modules:
+**Do not start here.** These are a Canvas2D renderer that ended up in the
+wrong place: more expensive to author than an SVG drawing and less expressive
+than the 2.5-D characters, which is the whole range it was meant to sit between.
+They still work and they are still tested, but they get no further work, and
+their entry points come out in 0.5.0. Pick an SVG face or a 2.5-D character
+instead; both are below.
+
+Complete, code-authored avatars, each its own `createAvatar` module:
 
 ```js
 import { createAvatar } from '@voqalize/avatar/avatars/arjun';
@@ -151,15 +159,15 @@ const avatar = createAvatar({ mount, client: pipecatClient });
 ```
 
 `arjun`/`meera` are the original interviewer pair; `vikram`/`ishita` and
-`kabir`/`naina` are two further wardrobe/hair directions on the same rig. The
+`kabir`/`naina` are further wardrobe/hair directions on the same rig. The
 entry points `interviewer-male`, `interviewer-female`, `professional-male-a`,
 `professional-female-a`, `professional-male-b` and `professional-female-b`
 still work — they are `@deprecated` aliases for the names above, kept so
 existing imports do not break, and should not be used in new code.
 
-All six depict Indian professionals in their late twenties, without caricature
+They depict Indian professionals in their late twenties, without caricature
 or regional costume cues. They are calibrated at call-tile size and preserve
-all six expression targets, continuous visemes, gaze, blink, head motion, and
+every expression target, continuous visemes, gaze, blink, head motion, and
 the frame-edge gesture hand. Each module is a complete identity, not a face
 value: import one instead of the default module and do not pass a `face`
 option.
@@ -171,23 +179,25 @@ only in low-motion upper-cheek areas; none are used as demographic cues.
 They use the same public contract and the same Pipecat lifecycle/viseme driver
 as the SVG avatars. Their private renderer is Canvas2D; its rig data and bitmap
 wardrobe assets are implementation details and no Canvas or pose API is added
-to the package surface.
+to the package surface. Like the SVG faces they are code, MIT, and ask for no
+attribution.
 
 ## The 2.5-D characters
 
-Three characters ship as compiled binaries, each its own `createAvatar` module:
+The characters ship as compiled binaries, each its own `createAvatar` module:
 
 ```js
 import { createAvatar } from '@voqalize/avatar/avatars/tara';
 // or: @voqalize/avatar/avatars/tushar
 //     @voqalize/avatar/avatars/tanya
+//     @voqalize/avatar/avatars/tess
 
 const avatar = createAvatar({ mount, client: pipecatClient });
 ```
 
 A photograph of a face projected onto shallow geometry, with the parts that have
 to move — eyes, teeth, the lip line — built as geometry rather than painted.
-Three.js is an *optional* peer (`three`, `>=0.180 <0.187`) behind these three
+Three.js is an *optional* peer (`three`, `>=0.180 <0.187`) behind those
 entry points only, so an SVG or Canvas consumer never downloads it, and the `.glb`
 is fetched when the avatar mounts.
 
@@ -196,7 +206,7 @@ cue-synced mouth, and a server that has never heard of these characters drives o
 correctly. The head turns 15° of yaw and 24° of pitch, which is a measured limit
 rather than an option.
 
-**The three binaries are artwork under CC-BY 4.0**, separately from the MIT code
+**The binaries are artwork under CC-BY 4.0**, separately from the MIT code
 around them; the credit line is in `assets/README.md`. Mounting, sizing, the asset
 budget and what the characters can be asked to do:
 [characters.md](https://github.com/voqalize/avatar/blob/main/docs/characters.md).
@@ -234,7 +244,7 @@ React binding. `src/` is the widget itself: the mixer, the SVG rig and drawings,
 plus the private Canvas2D interviewer rigs and their assets, as dependency-free
 ES modules with no build step, imported by `dist/` through ordinary relative
 paths. `client/` is the TypeScript those `dist/` files were compiled from, so
-the source maps resolve. `assets/` is the three compiled characters and their
+the source maps resolve. `assets/` is the compiled characters and their
 licence note — the only non-JavaScript thing here, fetched at runtime by URL.
 
 The contract documents do not ship here. They live in the repository, which is
@@ -244,10 +254,18 @@ where they are kept current:
 ## License
 
 **MIT for the code, CC-BY 4.0 for the artwork**, and Voqalize holds the
-copyright on all of it. The manifest declares the pair as `MIT AND CC-BY-4.0`;
-the artwork is `assets/*.glb`, the three 2.5-D characters, and `assets/README.md`
-carries the credit line. Everything else in the tarball is MIT, usable anywhere
-including in closed-source products.
+copyright on all of it. The licence follows the kind of avatar, not the roster:
+
+- **SVG faces and Canvas2D identities are code** — MIT, no attribution. Each is
+  drawn by the function that ships it; a Canvas2D identity's rig data and
+  wardrobe bitmaps are implementation details of that function, not artwork you
+  are licensing.
+- **2.5-D characters are artwork** — `assets/*.glb`, and nothing else in the
+  tarball, under CC-BY 4.0. `assets/README.md` carries the credit line.
+
+MIT is usable anywhere, including in closed-source products. The manifest
+declares the package as `MIT AND CC-BY-4.0`, which is what a licence scanner
+reports whether or not you import a 2.5-D character.
 
 The drawing idiom `peep` is authored in is
 [Open Peeps](https://www.openpeeps.com/) (CC0) — no artwork is copied. The

package/assets/README.md

@@ -1,12 +1,13 @@
 # The character binaries
 
-Three 2.5-D characters, one compiled file each:
+The 2.5-D characters, one compiled file each:
 
 | file | character | what it is |
 |---|---|---|
 | `tara.glb` | tara | the first; shallow geometry under a projected portrait |
 | `tushar.glb` | tushar | the second, her scripts with his landmarks |
 | `tanya.glb` | tanya | the third, built from supplied reference images |
+| `tess.glb` | tess | the fourth, from a single supplied reference sheet |
 
 They are loaded for you. `@voqalize/avatar/avatars/tara` resolves the file beside
 itself and hands it to a loader; you never name a path, and the only reason to
@@ -20,7 +21,7 @@ in this directory to regenerate it from, and the next release overwrites it.
 
 ## Licence: CC-BY 4.0
 
-The rest of this package is MIT. These three files are artwork, not code, so they
+The rest of this package is MIT. These files are artwork, not code, so they
 carry an artwork licence: **Creative Commons Attribution 4.0 International**, the
 full text in `LICENSE-CC-BY-4.0` at the package root. Use them in a product,
 commercially, modified or retextured, and credit us:
@@ -41,7 +42,7 @@ file is the only way terms travel with it.
 Every character began as an image from a generative model — OpenAI's and
 Google's — and **none of them depicts a real person**. Any resemblance to one is
 coincidence, not a likeness, and there are no personality rights attached to any
-of these three. What we did with that image is ours: the geometry, the measured
+of them. What we did with that image is ours: the geometry, the measured
 landmarks, the projection, the relighting and the authored morph targets are all
 human work, and they are the substance of what is licensed here.
 

package/client/internal.ts

@@ -47,6 +47,24 @@ export {
   LEAD_MS,
   // The body's share of a held tilt, for a page driving a rig by hand.
   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,
   normalizeCues,
   textToCues,
@@ -55,6 +73,8 @@ export {
 } from "../src/avatar.js";
 
 export type {
+  Clip,
+  ClipSample,
   AvatarApi,
   AvatarStateName,
   AvatarActionId,

package/client/three/assets.ts

@@ -1,14 +1,15 @@
 /**
- * The three compiled characters as one table — for a page that enumerates them.
+ * Every compiled character as one table — for a page that enumerates them.
  *
  * Each URL lives in its own module (`tara-asset.ts` and its siblings) and this
  * file only gathers them, because a bundler emits assets per module: anything
- * importing *this* ships all three GLBs, which is right for a rig instrument
- * that switches between characters and wrong for a consumer who mounted one.
+ * importing *this* ships every GLB, which is right for a rig instrument that
+ * switches between characters and wrong for a consumer who mounted one.
  * So the character modules never import this — they import their own — and the
  * only reader is `/internal/three`, a separate entry point that ships nothing.
  */
 import { TANYA_GLB } from "./tanya-asset.js";
+import { TESS_GLB } from "./tess-asset.js";
 import { TARA_GLB } from "./tara-asset.js";
 import { TUSHAR_GLB } from "./tushar-asset.js";
 
@@ -16,6 +17,7 @@ export const ASSETS = Object.freeze({
   tara: TARA_GLB,
   tushar: TUSHAR_GLB,
   tanya: TANYA_GLB,
+  tess: TESS_GLB,
 });
 
 /** Every compiled character, in build order. */

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
@@ -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` — 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,

package/client/three/motion-limits.json

@@ -110,7 +110,11 @@
      "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": []
   }
  },
- "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/tara-rig.ts

@@ -69,10 +69,11 @@ const FRAME_CENTRE = (FRAME.top + FRAME.bottom) / 2;
  * 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.
+ * crop on the characters that existed then 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 under the 18° the
+ * tightest of them read.
  *
  * 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
@@ -931,6 +932,19 @@ export interface TaraRigOptions {
   /** `false` leaves an asset's expression maps unread, for a capture tool
    *  comparing the face with and without them. */
   readonly expression?: boolean;
+  /** Keeps the drawing buffer readable after the browser has composited it, so
+   *  a caller can copy the canvas out at any moment rather than only from
+   *  inside the frame that drew it.
+   *
+   *  A pose sheet needs this and a consumer must not have it. WebGL contexts are
+   *  a handful per page, so a sheet of thirty poses cannot be thirty canvases —
+   *  it holds one pose still, copies the canvas into a tile, and moves on. Copy
+   *  outside the drawing frame and the buffer has already been cleared, which is
+   *  a blank tile and not an error. The cost is that the buffer cannot be
+   *  discarded, which on some drivers means a second copy of every frame; the
+   *  consumer renders thirty frames a second forever and pays nothing for a
+   *  readback it never performs. */
+  readonly readback?: boolean;
 }
 
 const radians = (deg: number) => (deg * Math.PI) / 180;
@@ -940,9 +954,9 @@ const radians = (deg: number) => (deg * Math.PI) / 180;
  * Three.js throws out of the constructor rather than returning anything, and it
  * has already written its own line to the console by then; that line is kept
  * because it names the underlying reason, which this one does not. */
-function webglRenderer(): THREE.WebGLRenderer | null {
+function webglRenderer(readback = false): THREE.WebGLRenderer | null {
   try {
-    return new THREE.WebGLRenderer({ antialias: true, alpha: true });
+    return new THREE.WebGLRenderer({ antialias: true, alpha: true, preserveDrawingBuffer: readback });
   } catch {
     return null;
   }
@@ -1153,7 +1167,7 @@ const expressionWeights = (pose: RigPose, side: "L" | "R", expression: Expressio
 // `options` is `unknown` in the contract, and stays `unknown` here: the mixer
 // passes `rigOptions` through verbatim and has no way to know any rig's shape.
 export function createTaraRig(mount: HTMLElement, options?: unknown): AvatarRig {
-  const { onReady, url, expression: readExpression = true } =
+  const { onReady, url, expression: readExpression = true, readback = false } =
     (options ?? {}) as TaraRigOptions;
   // A missing `url` is a caller's defect, not a browser condition — the WebGL
   // path below degrades because a driver is nobody's fault, whereas this would
@@ -1164,7 +1178,7 @@ export function createTaraRig(mount: HTMLElement, options?: unknown): AvatarRig
   camera.position.set(0, FRAME_CENTRE, 6);
   camera.lookAt(0, FRAME_CENTRE, 0);
 
-  const renderer = webglRenderer();
+  const renderer = webglRenderer(readback);
   // No context, no face — and that has to be the whole of it. `createAvatar` is
   // synchronous and returns `{ destroy }`, so a consumer has nothing to catch:
   // anything thrown here lands in *their* window and takes the call page with

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,72 @@
+/**
+ * tess — American, and like `tushar.ts` and `tanya.ts` a copy of `tara.ts`.
+ *
+ * Her GLB is tara's scripts run with her landmarks in place of tara's
+ * (`characters/tess/`, 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 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.
+ *
+ * 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 type { PipecatClient } from "@pipecat-ai/client-js";
+import { AvatarClient, createSvgAvatar } from "../internal.js";
+import { TESS_GLB } from "./tess-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; }
+
+/** The optional driving-UI declaration; one list for every character built on
+ *  this rig (`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: TESS_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("tess"), ...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/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, 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,EACR,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,18 @@ 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, 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,EACR,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"}

package/dist/three/assets.d.ts

@@ -2,6 +2,7 @@ export declare const ASSETS: Readonly<{
     tara: string;
     tushar: string;
     tanya: string;
+    tess: string;
 }>;
 /** Every compiled character, in build order. */
 export type CharacterName = keyof typeof ASSETS;

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

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../client/three/assets.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,MAAM;;;;EAIjB,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,MAAM,CAAC"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../../client/three/assets.ts"],"names":[],"mappings":"AAeA,eAAO,MAAM,MAAM;;;;;EAKjB,CAAC;AAEH,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,MAAM,CAAC"}

package/dist/three/assets.js

@@ -1,19 +1,21 @@
 /**
- * The three compiled characters as one table — for a page that enumerates them.
+ * Every compiled character as one table — for a page that enumerates them.
  *
  * Each URL lives in its own module (`tara-asset.ts` and its siblings) and this
  * file only gathers them, because a bundler emits assets per module: anything
- * importing *this* ships all three GLBs, which is right for a rig instrument
- * that switches between characters and wrong for a consumer who mounted one.
+ * importing *this* ships every GLB, which is right for a rig instrument that
+ * switches between characters and wrong for a consumer who mounted one.
  * So the character modules never import this — they import their own — and the
  * only reader is `/internal/three`, a separate entry point that ships nothing.
  */
 import { TANYA_GLB } from "./tanya-asset.js";
+import { TESS_GLB } from "./tess-asset.js";
 import { TARA_GLB } from "./tara-asset.js";
 import { TUSHAR_GLB } from "./tushar-asset.js";
 export const ASSETS = Object.freeze({
     tara: TARA_GLB,
     tushar: TUSHAR_GLB,
     tanya: TANYA_GLB,
+    tess: TESS_GLB,
 });
 //# sourceMappingURL=assets.js.map

package/dist/three/assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../client/three/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,SAAS;CACjB,CAAC,CAAC"}
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../../client/three/assets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,UAAU;IAClB,KAAK,EAAE,SAAS;IAChB,IAAI,EAAE,QAAQ;CACf,CAAC,CAAC"}