@voqalize/avatar 0.4.0 → 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,23 +1,23 @@
 /**
- * Where the three compiled characters are, resolved against this module's own
- * location.
+ * Every compiled character as one table — for a page that enumerates them.
  *
- * `new URL(…, import.meta.url)` and not a bundler's asset import: these files
- * are fetched at runtime by a consumer's app, and the spelling has to survive
- * Vite, webpack, Rollup, esbuild, a plain `tsc` output and a browser loading
- * the module directly. The query-suffix form this used to carry is Vite syntax —
- * every other toolchain, including the compiler that now builds this directory,
- * passes it through verbatim and produces an import of a file that is not there.
- *
- * The depth is the same from the source tree and from the compiled one
- * (`client/three/` and `dist/three/` are siblings), so one literal is correct in
- * both — and literal is load-bearing, because a bundler can only follow this
- * pattern when it can read the path without running anything.
+ * 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 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: new URL("../../assets/tara.glb", import.meta.url).href,
-  tushar: new URL("../../assets/tushar.glb", import.meta.url).href,
-  tanya: new URL("../../assets/tanya.glb", import.meta.url).href,
+  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/tanya-asset.ts

@@ -0,0 +1,6 @@
+/**
+ * Where tanya'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 TANYA_GLB = new URL("../../assets/tanya.glb", import.meta.url).href;

package/client/three/tanya.ts

@@ -15,7 +15,7 @@
 
 import type { PipecatClient } from "@pipecat-ai/client-js";
 import { AvatarClient, createSvgAvatar } from "../internal.js";
-import { ASSETS } from "./assets.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";
@@ -45,7 +45,7 @@ export function createAvatar(options: AvatarOptions): AvatarInstance {
   if (!mount) throw new TypeError("createAvatar: `mount` is required");
   if (!client) throw new TypeError("createAvatar: `client` is required");
 
-  const rigOptions: TaraRigOptions = { onReady, url: ASSETS.tanya };
+  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({

package/client/three/tara-asset.ts

@@ -0,0 +1,25 @@
+/**
+ * Where tara's compiled GLB is — one character, one module, on purpose.
+ *
+ * `new URL(…, import.meta.url)` and not a bundler's asset import: these files
+ * are fetched at runtime by a consumer's app, and the spelling has to survive
+ * Vite, webpack, Rollup, esbuild, a plain `tsc` output and a browser loading the
+ * module directly. The query-suffix form this used to carry is Vite syntax —
+ * every other toolchain, including the compiler that now builds this directory,
+ * passes it through verbatim and produces an import of a file that is not there.
+ *
+ * The depth is the same from the source tree and from the compiled one
+ * (`client/three/` and `dist/three/` are siblings), so one literal is correct in
+ * both — and literal is load-bearing, because a bundler can only follow this
+ * pattern when it can read the path without running anything.
+ *
+ * **One module per character is the whole point, and it is a bundling fact, not
+ * tidiness.** A bundler that can follow `new URL` emits the file it names, and
+ * it decides what to emit per *module*: three literals in one object meant a
+ * consumer who imported one character shipped all three GLBs — ~1.3 MB of a
+ * character they never mount, in every build we checked. Splitting them is what
+ * makes `@voqalize/avatar/avatars/tara` cost tara. Nothing that a character
+ * module loads may reach for another character's URL, which is also why the rig
+ * takes its `url` from its caller instead of defaulting to tara's.
+ */
+export const TARA_GLB = new URL("../../assets/tara.glb", import.meta.url).href;

package/client/three/tara-rig.ts

@@ -31,7 +31,6 @@ import { REST } from "../internal.js";
 import type { AvatarFrame, AvatarRig, RigPose } from "../internal.js";
 import * as THREE from "three";
 import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
-import { ASSETS } from "./assets.js";
 import { HARD_BUDGET, pixelRatioFor } from "./budgets.js";
 
 /**
@@ -70,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
@@ -918,14 +918,33 @@ const MIN_FRAME_MS = 1000 / RENDER_FPS;
 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;
+  /** The character's GLB. 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.
+   *
+   *  Required, and it used to default to tara's. A default meant this module
+   *  imported one character's URL, and a bundler emits assets per module — so
+   *  every consumer of *any* character shipped tara's GLB whether or not they
+   *  mounted her. The caller knows which character it is building; this file
+   *  must not ([tara-asset.ts](./tara-asset.ts)). */
+  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;
+  /** 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;
@@ -935,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;
   }
@@ -1148,14 +1167,18 @@ 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 = ASSETS.tara, 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
+  // otherwise be a 404 on a path spelled `undefined`.
+  if (!url) throw new TypeError("createTaraRig: `url` is required");
   const scene = new THREE.Scene();
   const camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0.1, 100);
   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/tara.ts

@@ -16,6 +16,7 @@
 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 { 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";
@@ -44,7 +45,7 @@ export function createAvatar(options: AvatarOptions): AvatarInstance {
   if (!mount) throw new TypeError("createAvatar: `mount` is required");
   if (!client) throw new TypeError("createAvatar: `client` is required");
 
-  const rigOptions: TaraRigOptions = { onReady };
+  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.

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/client/three/tushar-asset.ts

@@ -0,0 +1,6 @@
+/**
+ * Where tushar'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 TUSHAR_GLB = new URL("../../assets/tushar.glb", import.meta.url).href;