@voqalize/avatar 0.4.4 → 0.5.1

package/dist/three/tara.js

@@ -1,30 +0,0 @@
-/**
- * tara — the first 3-D character, as a complete `createAvatar` module.
- *
- * 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 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 { character } from "./createCharacter.js";
-import { BLENDER_SUPPORTS } from "./sequences.js";
-import { TARA_GLB } from "./tara-asset.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("tara", TARA_GLB);
-//# sourceMappingURL=tara.js.map

package/dist/three/tara.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tara.js","sourceRoot":"","sources":["../../client/three/tara.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAK3C;kDACkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}

package/dist/three/tess-asset.d.ts

@@ -1,7 +0,0 @@
-/**
- * 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 declare const TESS_GLB: string;
-//# sourceMappingURL=tess-asset.d.ts.map

package/dist/three/tess-asset.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tess-asset.d.ts","sourceRoot":"","sources":["../../client/three/tess-asset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,QAAyD,CAAC"}

package/dist/three/tess-asset.js

@@ -1,7 +0,0 @@
-/**
- * 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;
-//# sourceMappingURL=tess-asset.js.map

package/dist/three/tess-asset.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tess-asset.js","sourceRoot":"","sources":["../../client/three/tess-asset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,uBAAuB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC"}

package/dist/three/tess.d.ts

@@ -1,24 +0,0 @@
-/**
- * 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 type { CharacterAvatarOptions } from "./createCharacter.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 declare const supports: import("../createAvatar.js").AvatarSupport;
-export declare const createAvatar: import("../createAvatar.js").AvatarFactory<CharacterAvatarOptions>;
-//# sourceMappingURL=tess.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"tess.d.ts","sourceRoot":"","sources":["../../client/three/tess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAInE,YAAY,EAAE,sBAAsB,IAAI,aAAa,EAAE,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;kDACkD;AAClD,eAAO,MAAM,QAAQ,4CAAmB,CAAC;AAEzC,eAAO,MAAM,YAAY,oEAA8B,CAAC"}

package/dist/three/tess.js

@@ -1,24 +0,0 @@
-/**
- * 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 { BLENDER_SUPPORTS } from "./sequences.js";
-import { TESS_GLB } from "./tess-asset.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);
-//# sourceMappingURL=tess.js.map

package/dist/three/tess.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tess.js","sourceRoot":"","sources":["../../client/three/tess.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAK3C;kDACkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC"}

package/dist/three/tushar-asset.d.ts

@@ -1,7 +0,0 @@
-/**
- * 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 declare const TUSHAR_GLB: string;
-//# sourceMappingURL=tushar-asset.d.ts.map

package/dist/three/tushar-asset.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tushar-asset.d.ts","sourceRoot":"","sources":["../../client/three/tushar-asset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,UAAU,QAA2D,CAAC"}

package/dist/three/tushar-asset.js

@@ -1,7 +0,0 @@
-/**
- * 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;
-//# sourceMappingURL=tushar-asset.js.map

package/dist/three/tushar-asset.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tushar-asset.js","sourceRoot":"","sources":["../../client/three/tushar-asset.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,yBAAyB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC"}

package/dist/three/tushar.d.ts

@@ -1,22 +0,0 @@
-/**
- * tushar — the second 3-D character, and the one who proved the factory.
- *
- * 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 { CharacterAvatarOptions } from "./createCharacter.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 declare const supports: import("../createAvatar.js").AvatarSupport;
-export declare const createAvatar: import("../createAvatar.js").AvatarFactory<CharacterAvatarOptions>;
-//# sourceMappingURL=tushar.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"tushar.d.ts","sourceRoot":"","sources":["../../client/three/tushar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAInE,YAAY,EAAE,sBAAsB,IAAI,aAAa,EAAE,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;kDACkD;AAClD,eAAO,MAAM,QAAQ,4CAAmB,CAAC;AAEzC,eAAO,MAAM,YAAY,oEAAkC,CAAC"}

package/dist/three/tushar.js

@@ -1,22 +0,0 @@
-/**
- * tushar — the second 3-D character, and the one who proved the factory.
- *
- * 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 { character } from "./createCharacter.js";
-import { BLENDER_SUPPORTS } from "./sequences.js";
-import { TUSHAR_GLB } from "./tushar-asset.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("tushar", TUSHAR_GLB);
-//# sourceMappingURL=tushar.js.map

package/dist/three/tushar.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tushar.js","sourceRoot":"","sources":["../../client/three/tushar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAK/C;kDACkD;AAClD,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC"}

package/dist/types.d.ts

@@ -1,149 +0,0 @@
-/**
- * types.ts — the avatar wire vocabulary, client side.
- *
- * The binding definition is `docs/contract-wire.md`; this file is its
- * TypeScript restatement and must not drift from it. The Python half of the
- * same vocabulary is `packages/avatar-py/src/voqalize_avatar/messages.py` — the three are
- * maintained together, and a command added to one without the others is
- * incomplete.
- *
- * A server pushes these as RTVI `server-message`s under the envelope
- * `{ type: "avatar", ...cmd-specific fields }`. {@link AvatarCommand} describes
- * what rides inside that envelope; {@link isAvatarMessage} is the envelope
- * itself, and is the only definition of "this message is for the avatar" the
- * client has. There is no protocol version field — an unknown `cmd` is simply
- * ignored, which is the whole forward-compatibility rule.
- */
-import type { VisemeLetter } from "../src/avatar.js";
-/** A viseme cue: `t` is a ms offset into the utterance's clock, `v` is a Rhubarb A–H (or X) letter. */
-export interface AvatarCue {
-    t: number;
-    v: VisemeLetter;
-    /** 0..1 loudness. Absent means full. */
-    i?: number;
-    /**
-     * The phone being articulated under `v`, absent during silence.
-     *
-     * `v` is a nine-way projection of the recogniser's ~40 phones and the loss is
-     * concentrated — `B` alone absorbs IY, IH, T, D, CH, JH, TH, DH, S, Z, SH,
-     * ZH, N and Y — so a renderer with a mouth for "tongue between the teeth"
-     * cannot ask for it from `v` and can from here. **Not a closed set**: it is
-     * whatever the engine labels its own segments with, which today is Arpabet
-     * plus `Schwa` and four non-speech labels, and a later engine may say
-     * something else. Validated as an identifier and passed through unread —
-     * the letter stays the thing every face must handle, and a face that wants
-     * the finer signal opts in.
-     */
-    p?: string;
-}
-/**
- * A durable, lower-priority server state. `null` explicitly clears it.
- *
- * Three values, and the server can send no others: the remaining six of the
- * nine are Pipecat facts the browser already holds, and a server spelling of a
- * fact would be a second, lower-authority copy of it. It was `cmd: "claim"`
- * until the wire redesign, when the concept and the command were given the one
- * name the rest of the system already used for it.
- */
-export interface AvatarStateCmd {
-    cmd: "state";
-    state: "CANT_HEAR" | "THINKING" | "WORKING" | null;
-}
-/**
- * One self-completing motion, by name: face, body, and optionally a hand.
- *
- * **The id is open.** Two of them — {@link CORE_ACTION_IDS} — are intents every
- * renderer owes a server and are the only ones a server may send without
- * knowing what is mounted. Everything else is a name from the mounted avatar's
- * own catalogue, and **an unknown one is ignored, not an error**: that is the
- * same forward-compatibility rule an unknown `cmd` gets, arrived at from the
- * other direction. There, a newer server meets an older widget; here, any
- * server meets a face that cannot do the thing. Neither is worth breaking a
- * call over, and there is deliberately no fallback — an action sits on top of a
- * state, so nothing is missing when one is dropped.
- *
- * This replaced a closed seven-id vocabulary plus a second command,
- * `sequence`, for a renderer's own motions. The split cost a promotion ritual
- * for every new portable intent and still could not say what the closed set was
- * for: the listening research separates a continuer nod from an assessment nod
- * from a realisation, and all three were the one id `ACK_NOD` spelled. Now the
- * server says *when* to acknowledge and the avatar owns the variety.
- */
-export interface AvatarActionCmd {
-    cmd: "action";
-    id: string;
-}
-/**
- * The two actions every renderer must answer to.
- *
- * `ACKNOWLEDGE` is the whole backchannel family in one word — receipt, nod,
- * realisation, empathy — because which of those a face does is a rendering
- * decision and the server is not the one holding the drawing.
- * `RESPONSE_INTERRUPTED` is the one transition a server can explain and the
- * browser cannot infer.
- *
- * A renderer may draw either in its own shape; it may never redefine one, and
- * a name in its own catalogue never shadows one of these.
- */
-export declare const CORE_ACTION_IDS: readonly ["ACKNOWLEDGE", "RESPONSE_INTERRUPTED"];
-export type CoreActionId = (typeof CORE_ACTION_IDS)[number];
-export interface AvatarCuesCmd {
-    cmd: "cues";
-    ctx: string;
-    /** Discard queued cues at or after this offset (ms), then append `cues`. */
-    from_ms: number;
-    cues: AvatarCue[];
-    /**
-     * True on the one chunk that completes this turn's track: the TTS context is
-     * closed, so no further chunk will splice into `ctx`. What a client may
-     * assume, exactly — nothing about playout. The audio it describes is still
-     * ahead, and Pipecat's `botStoppedSpeaking` remains the end of the turn. It
-     * is safe to stop expecting more cue chunks after `final`.
-     *
-     * Absent on an interrupted turn, deliberately: a turn that was cut never
-     * claims to have completed. Absent chunks are the normal case — the widget's
-     * own track already completes on the trailing `X`, so ignoring `final`
-     * entirely is a correct implementation.
-     */
-    final?: boolean;
-}
-export type AvatarCommand = AvatarStateCmd | AvatarActionCmd | AvatarCuesCmd;
-/** The full server-message payload: the envelope plus its command. */
-export type AvatarServerMessage = AvatarCommand & {
-    type: "avatar";
-};
-/** An envelope addressed to the avatar, before its payload has been read. */
-export type AvatarEnvelope = {
-    type: "avatar";
-    cmd: string;
-} & Record<string, unknown>;
-/**
- * Is this server-message payload the avatar's? The envelope is the whole
- * answer: `{type:"avatar"}` with a string `cmd`. It used to be a per-deployment
- * `accept` predicate on the client, which meant the library could not state
- * what an avatar message *is*.
- *
- * Addressed to us is not the same as understood by us: {@link parseAvatarCommand}
- * is the second half.
- */
-export declare function isAvatarMessage(msg: unknown): msg is AvatarEnvelope;
-/**
- * Read an envelope's payload into the wire vocabulary, or `null` if this build
- * cannot act on it — an unknown `cmd`, a state outside the three, an action id
- * that is not a name, a malformed `cues` chunk.
- *
- * `null` is the forward-compat rule with a type attached: a newer server
- * talking to an older widget is *expected*, and the older widget ignores what
- * it does not know rather than guessing. Doing the check here rather than at
- * each use site is what lets the wire types be closed unions instead of
- * `string` — the boundary is one function, so it can be the only place that
- * has to be honest about untrusted input.
- *
- * Cues survive individually: one unrecognised letter in a chunk drops that cue,
- * not the utterance around it. Losing a frame of articulation is a far smaller
- * regression than losing a sentence of it.
- */
-export declare function parseAvatarCommand(msg: AvatarEnvelope): AvatarCommand | null;
-/** The envelope `type` the protocol reserves for avatar traffic. */
-export declare const AVATAR_MESSAGE_TYPE = "avatar";
-//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../client/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,uGAAuG;AACvG,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,YAAY,CAAC;IAChB,wCAAwC;IACxC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX;;;;;;;;;;;;OAYG;IACH,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,IAAI,CAAC;CACpD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,QAAQ,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,kDAAkE,CAAC;AAE/F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,eAAe,GACf,aAAa,CAAC;AAElB,sEAAsE;AACtE,MAAM,MAAM,mBAAmB,GAAG,aAAa,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAErE,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,cAAc,CAInE;AAiBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI,CAwD5E;AAED,oEAAoE;AACpE,eAAO,MAAM,mBAAmB,WAAW,CAAC"}

package/dist/types.js

@@ -1,140 +0,0 @@
-/**
- * types.ts — the avatar wire vocabulary, client side.
- *
- * The binding definition is `docs/contract-wire.md`; this file is its
- * TypeScript restatement and must not drift from it. The Python half of the
- * same vocabulary is `packages/avatar-py/src/voqalize_avatar/messages.py` — the three are
- * maintained together, and a command added to one without the others is
- * incomplete.
- *
- * A server pushes these as RTVI `server-message`s under the envelope
- * `{ type: "avatar", ...cmd-specific fields }`. {@link AvatarCommand} describes
- * what rides inside that envelope; {@link isAvatarMessage} is the envelope
- * itself, and is the only definition of "this message is for the avatar" the
- * client has. There is no protocol version field — an unknown `cmd` is simply
- * ignored, which is the whole forward-compatibility rule.
- */
-import { VISEME_LETTERS } from "../src/avatar.js";
-/**
- * The two actions every renderer must answer to.
- *
- * `ACKNOWLEDGE` is the whole backchannel family in one word — receipt, nod,
- * realisation, empathy — because which of those a face does is a rendering
- * decision and the server is not the one holding the drawing.
- * `RESPONSE_INTERRUPTED` is the one transition a server can explain and the
- * browser cannot infer.
- *
- * A renderer may draw either in its own shape; it may never redefine one, and
- * a name in its own catalogue never shadows one of these.
- */
-export const CORE_ACTION_IDS = Object.freeze(["ACKNOWLEDGE", "RESPONSE_INTERRUPTED"]);
-/**
- * Is this server-message payload the avatar's? The envelope is the whole
- * answer: `{type:"avatar"}` with a string `cmd`. It used to be a per-deployment
- * `accept` predicate on the client, which meant the library could not state
- * what an avatar message *is*.
- *
- * Addressed to us is not the same as understood by us: {@link parseAvatarCommand}
- * is the second half.
- */
-export function isAvatarMessage(msg) {
-    if (typeof msg !== "object" || msg === null)
-        return false;
-    const m = msg;
-    return m.type === AVATAR_MESSAGE_TYPE && typeof m.cmd === "string";
-}
-/**
- * What an action id may look like. Not which ones exist — that is the mounted
- * avatar's business and this function has never met it. `CATEGORY_INTENT` in
- * upper case, bounded so a malformed or hostile message cannot smuggle
- * anything through as a name.
- */
-const ACTION_ID = /^[A-Z][A-Z0-9_]{1,63}$/;
-const LETTERS = new Set(VISEME_LETTERS);
-/**
- * What a phone label may look like. Letters only, because every label any
- * engine we have seen is one word of them — `AO`, `NG`, `Schwa`, `Breath` —
- * and the bound is what stops a name being a payload.
- */
-const PHONE_LABEL = /^[A-Za-z]{1,12}$/;
-/**
- * Read an envelope's payload into the wire vocabulary, or `null` if this build
- * cannot act on it — an unknown `cmd`, a state outside the three, an action id
- * that is not a name, a malformed `cues` chunk.
- *
- * `null` is the forward-compat rule with a type attached: a newer server
- * talking to an older widget is *expected*, and the older widget ignores what
- * it does not know rather than guessing. Doing the check here rather than at
- * each use site is what lets the wire types be closed unions instead of
- * `string` — the boundary is one function, so it can be the only place that
- * has to be honest about untrusted input.
- *
- * Cues survive individually: one unrecognised letter in a chunk drops that cue,
- * not the utterance around it. Losing a frame of articulation is a far smaller
- * regression than losing a sentence of it.
- */
-export function parseAvatarCommand(msg) {
-    switch (msg.cmd) {
-        // `claim` was this command's name, and `STRAINING` one of its values, until
-        // the wire redesign. Both are accepted and translated here, in the one
-        // place that reads untrusted input, so no layer above has ever heard of
-        // either spelling. Servers that predate the rename keep working; the old
-        // names appear nowhere else and come out when the last one has shipped.
-        case "claim":
-        case "state": {
-            const state = msg.state === "STRAINING" ? "CANT_HEAR" : msg.state;
-            if (state === null || state === "CANT_HEAR" || state === "THINKING" || state === "WORKING") {
-                return { cmd: "state", state };
-            }
-            return null;
-        }
-        // `sequence` was a second command for the same thing: a name resolved
-        // against the mounted avatar rather than against a closed list. Now that
-        // `action` is that, the two are one command and the old one is an alias.
-        case "sequence":
-        case "action":
-            // Shape only, both for a core id and for one of the avatar's own. There
-            // is nothing to check a name against here — the catalogue belongs to
-            // whatever is mounted, and this function has never met it.
-            return typeof msg.id === "string" && ACTION_ID.test(msg.id)
-                ? { cmd: "action", id: msg.id }
-                : null;
-        case "cues": {
-            if (typeof msg.ctx !== "string" || !Number.isFinite(msg.from_ms) || !Array.isArray(msg.cues)) {
-                return null;
-            }
-            const cues = [];
-            for (const c of msg.cues) {
-                if (typeof c !== "object" || c === null)
-                    continue;
-                const { t, v, i, p } = c;
-                if (typeof t !== "number" || !Number.isFinite(t))
-                    continue;
-                if (typeof v !== "string" || !LETTERS.has(v))
-                    continue;
-                const cue = { t, v: v };
-                if (typeof i === "number")
-                    cue.i = i;
-                // Bounded as a name, not checked against a list. The set belongs to
-                // whatever produced the cue, so enumerating it here would make this
-                // library the thing that has to be released before a better recogniser
-                // can say a new word.
-                if (typeof p === "string" && PHONE_LABEL.test(p))
-                    cue.p = p;
-                cues.push(cue);
-            }
-            return {
-                cmd: "cues",
-                ctx: msg.ctx,
-                from_ms: msg.from_ms,
-                cues,
-                ...(msg.final === true ? { final: true } : {}),
-            };
-        }
-        default:
-            return null;
-    }
-}
-/** The envelope `type` the protocol reserves for avatar traffic. */
-export const AVATAR_MESSAGE_TYPE = "avatar";
-//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../client/types.ts"],"names":[],"mappings":"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"}

package/dist/useAvatar.d.ts

@@ -1,39 +0,0 @@
-/**
- * useAvatar — mount an avatar into a ref'd element for as long as there is a
- * client to embody, and tear it down after.
- *
- * Internal; `<Avatar>` is the only thing the React entry exports. The whole
- * hook is one effect, because the factory takes the client at construction:
- * there is no separate attach step to keep in its own lifecycle any more.
- */
-import type { PipecatClient } from "@pipecat-ai/client-js";
-import { type AvatarFactory, type AvatarOptions, type SvgAvatarOptions } from "./createAvatar.js";
-export interface UseAvatarOptions<O extends AvatarOptions = SvgAvatarOptions> {
-    /** The live `PipecatClient`, or `null` before connect. Nothing mounts until
-     * this is non-null — an avatar with nothing to embody has nothing to do. */
-    client?: PipecatClient | null;
-    /** The avatar implementation. Defaults to the bundled SVG faces. */
-    create?: AvatarFactory<O>;
-    /** Implementation options, forwarded verbatim. Read at mount only. */
-    options?: Omit<O, keyof AvatarOptions>;
-}
-/**
- * The mount ref's type, written out rather than named as React's `RefObject`.
- *
- * React 18 and 19 declare that alias with different type arguments — 18's
- * `useRef<T>(null)` yields `RefObject<T>`, 19's yields `RefObject<T | null>` —
- * and because both are the *same alias*, TypeScript compares them by variance
- * and rejects whichever one we didn't pick. An anonymous shape forces a
- * structural comparison instead, which both versions satisfy, and which the
- * `ref` prop accepts on both. This is the only place the 18-vs-19 split shows
- * up in the binding; keep it that way.
- */
-export type AvatarMountRef = {
-    current: HTMLDivElement | null;
-};
-export interface UseAvatarHandle {
-    /** Attach to the mount element: `<div ref={containerRef} />`. */
-    containerRef: AvatarMountRef;
-}
-export declare function useAvatar<O extends AvatarOptions = SvgAvatarOptions>({ client, create, options }?: UseAvatarOptions<O>): UseAvatarHandle;
-//# sourceMappingURL=useAvatar.d.ts.map

package/dist/useAvatar.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"useAvatar.d.ts","sourceRoot":"","sources":["../client/useAvatar.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,aAAa,GAAG,gBAAgB;IAC1E;gFAC4E;IAC5E,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,oEAAoE;IACpE,MAAM,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC1B,sEAAsE;IACtE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,EAAE,MAAM,aAAa,CAAC,CAAC;CACxC;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,cAAc,GAAG;IAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAAA;CAAE,CAAC;AAEhE,MAAM,WAAW,eAAe;IAC9B,iEAAiE;IACjE,YAAY,EAAE,cAAc,CAAC;CAC9B;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS,aAAa,GAAG,gBAAgB,EAClE,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAE,gBAAgB,CAAC,CAAC,CAAM,GACpD,eAAe,CAyBjB"}

package/dist/useAvatar.js

@@ -1,35 +0,0 @@
-/**
- * useAvatar — mount an avatar into a ref'd element for as long as there is a
- * client to embody, and tear it down after.
- *
- * Internal; `<Avatar>` is the only thing the React entry exports. The whole
- * hook is one effect, because the factory takes the client at construction:
- * there is no separate attach step to keep in its own lifecycle any more.
- */
-import { useEffect, useRef } from "react";
-import { createAvatar as createSvgAvatar, } from "./createAvatar.js";
-export function useAvatar({ client, create, options } = {}) {
-    const containerRef = useRef(null);
-    // Latest-options ref, so the mount effect reads the live values without
-    // remounting the face every time a caller passes a fresh object literal.
-    const optionsRef = useRef(options);
-    optionsRef.current = options;
-    useEffect(() => {
-        const mount = containerRef.current;
-        if (!mount || !client)
-            return;
-        const factory = (create ?? createSvgAvatar);
-        // The cast is the seam between "O minus the two we supply" and O. It is
-        // sound by construction and TypeScript cannot see through the spread of a
-        // generic; the two halves are typed at the boundary the caller touches.
-        const instance = factory({ mount, client, ...optionsRef.current });
-        return () => instance.destroy();
-        // A new client identity is a new thing to embody, so the avatar is rebuilt
-        // rather than re-pointed. Hosts keep one `PipecatClient` across
-        // connect/disconnect cycles, so this does not fire on an ordinary
-        // reconnect; if yours constructs a fresh client per session, expect the
-        // face to remount with it.
-    }, [client, create]);
-    return { containerRef };
-}
-//# sourceMappingURL=useAvatar.js.map

package/dist/useAvatar.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"useAvatar.js","sourceRoot":"","sources":["../client/useAvatar.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EACL,YAAY,IAAI,eAAe,GAIhC,MAAM,mBAAmB,CAAC;AA8B3B,MAAM,UAAU,SAAS,CACvB,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAA0B,EAAE;IAErD,MAAM,YAAY,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAC;IAElD,wEAAwE;IACxE,yEAAyE;IACzE,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACnC,UAAU,CAAC,OAAO,GAAG,OAAO,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC;QACnC,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;YAAE,OAAO;QAC9B,MAAM,OAAO,GAAG,CAAC,MAAM,IAAI,eAAe,CAAqB,CAAC;QAChE,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,MAAM,QAAQ,GAAG,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,OAAO,EAAkB,CAAC,CAAC;QACnF,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QAChC,2EAA2E;QAC3E,gEAAgE;QAChE,kEAAkE;QAClE,wEAAwE;QACxE,2BAA2B;IAC7B,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAErB,OAAO,EAAE,YAAY,EAAE,CAAC;AAC1B,CAAC"}