@voqalize/avatar 0.2.1 → 0.3.0

package/client/createAvatar.ts

@@ -0,0 +1,139 @@
+/**
+ * `createAvatar` — the entire public surface of an avatar.
+ *
+ *     const avatar = createAvatar({ mount: el, client: pipecatClient });
+ *     // …
+ *     avatar.destroy();
+ *
+ * An avatar is an embodiment of a `PipecatClient`. You hand it a mount and a
+ * live client; it subscribes and reacts. There is nothing else: no methods to
+ * drive it, no callbacks to observe it, no state to read back. Everything it
+ * needs to know is already on the wire — Pipecat's factual lifecycle events
+ * plus the avatar server-message envelope (docs/contract-wire.md).
+ *
+ * ## This is also the extension point
+ *
+ * There is no registry, no loader and no plug-in system. **You add an avatar by
+ * publishing a module that exports `createAvatar` with this signature**, and
+ * importing yours instead of ours:
+ *
+ *     import { createAvatar } from "@acme/our-mascot";
+ *
+ * That is the whole mechanism, and it is deliberate. A registry would make us
+ * own resolution, versioning and asset paths for code we have never seen; a
+ * renderer interface would make us commit to a second public contract before we
+ * know what the second renderer actually needs. An ES module export we get for
+ * free from the platform.
+ *
+ * Everything past `mount` and `client` belongs to the implementation. Ours takes
+ * `SvgAvatarOptions`; yours takes whatever it likes, and `AvatarFactory<O>` is
+ * generic so the caller still gets your options checked.
+ *
+ * ## What an implementation owes the caller
+ *
+ * Only that `destroy()` leaves the mount as it found it and unsubscribes from
+ * the client. Not returning to rest, not honouring every action, not even
+ * having a mouth — a handless, mouthless avatar that only changes colour is a
+ * conforming avatar. The obligations that *matter* are perceptual, not typed,
+ * and they live in docs/contract-behavior.md.
+ */
+
+import type { PipecatClient } from "@pipecat-ai/client-js";
+import { createAvatar as createSvgWidget } from "../src/avatar.js";
+import type { Face, FaceTheme, Gain, HandSide } from "../src/avatar.js";
+import { peep } from "../src/face-peep.js";
+import { AvatarClient } from "./AvatarClient.js";
+
+export type { Face, FaceTheme, Gain, HandSide };
+
+/**
+ * What every `createAvatar` takes. Implementations extend it with their own
+ * options; the two named here are the only ones the caller can count on.
+ */
+export interface AvatarOptions {
+  /** The element to render into. The implementation owns its contents. */
+  readonly mount: HTMLElement;
+  /**
+   * A live `PipecatClient`. Required, and not nullable: an avatar with nothing
+   * to embody has no reason to exist yet. React callers get the forgiving
+   * version — `<Avatar>` waits for a non-null client before mounting.
+   */
+  readonly client: PipecatClient;
+}
+
+/** What every `createAvatar` returns. */
+export interface AvatarInstance {
+  /** Unsubscribe from the client and remove everything from the mount. */
+  destroy(): void;
+}
+
+/**
+ * The shape a third-party avatar module exports, parameterised by its own
+ * options so a caller passing them gets them checked. `AvatarFactory` bare is
+ * the common denominator — the two options everyone shares.
+ */
+export type AvatarFactory<O extends AvatarOptions = AvatarOptions> =
+  (options: O) => AvatarInstance;
+
+/**
+ * Options for the bundled SVG avatars — ours alone; nothing outside this
+ * package reads them.
+ *
+ * `face` is a value, not a name: a name needs a table, and a table needs every
+ * face imported to answer any lookup. Import the one you want and the other two
+ * never enter your bundle.
+ *
+ *     import { createAvatar } from "@voqalize/avatar";
+ *     import { wren } from "@voqalize/avatar/faces/wren";
+ *
+ *     createAvatar({ mount, client, face: wren });
+ */
+export interface SvgAvatarOptions extends AvatarOptions {
+  /** Defaults to `peep`, the face this entry point already carries. */
+  readonly face?: Face;
+  /** Palette for that face. Its keys are the face's own; see `THEME` in its
+   * module, and CLAUDE.md on why `peep` has exactly one. */
+  readonly theme?: FaceTheme;
+  /** Viseme amplitude, 0..2. `1` is as authored. */
+  readonly mouthGain?: Gain;
+  /** Gesture-clip amplitude, 0..2. */
+  readonly gestureGain?: Gain;
+  /** Idle/liveness amplitude, 0..2. Low by design — see CLAUDE.md. */
+  readonly motionGain?: Gain;
+  /** Render the frame-edge hand at all. Default true. */
+  readonly hand?: boolean;
+  /** `1` puts it on the viewer's right, `-1` the other side. */
+  readonly handSide?: HandSide;
+}
+
+const GAINS = ["mouthGain", "gestureGain", "motionGain"] as const;
+
+export function createAvatar(options: SvgAvatarOptions): AvatarInstance {
+  const { mount, client, face = peep, ...rest } = options;
+  if (!mount) throw new TypeError("createAvatar: `mount` is required");
+  if (!client) throw new TypeError("createAvatar: `client` is required");
+  // The one range TypeScript cannot state, checked where it is cheapest to fix:
+  // at construction, by the caller who typed the number.
+  for (const key of GAINS) {
+    const g = rest[key];
+    if (g === undefined) continue;
+    if (!Number.isFinite(g) || g < 0 || g > 2) {
+      throw new RangeError(`createAvatar: \`${key}\` must be 0..2, got ${String(g)}`);
+    }
+  }
+
+  const widget = createSvgWidget({ mount, face, ...rest });
+  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/createCanvasAvatar.ts

@@ -0,0 +1,72 @@
+/** Shared private constructor for the code-authored canvas avatars. */
+
+import type { PipecatClient } from '@pipecat-ai/client-js';
+import { createAvatar as createMixer, STATES } from '../src/avatar.js';
+import type { Gain } from '../src/avatar.js';
+import { createCanvasRig } from '../src/canvas/create-rig.js';
+import { AvatarClient } from './AvatarClient.js';
+import type { AvatarInstance, AvatarOptions } from './createAvatar.js';
+
+export interface CanvasAvatarOptions extends AvatarOptions {
+  /** Viseme amplitude, 0..2. `1` is as authored. */
+  readonly mouthGain?: Gain;
+  /** Gesture-clip amplitude, 0..2. */
+  readonly gestureGain?: Gain;
+  /** Idle/liveness amplitude, 0..2. */
+  readonly motionGain?: Gain;
+}
+
+/** @deprecated Use `CanvasAvatarOptions`; kept for the original entry points. */
+export type InterviewerAvatarOptions = CanvasAvatarOptions;
+
+interface CanvasAvatarConfig {
+  readonly rigUrl: URL;
+  readonly images: Readonly<Record<string, URL>>;
+  readonly face: () => Promise<unknown>;
+  readonly label: string;
+}
+
+const GAINS = ['mouthGain', 'gestureGain', 'motionGain'] as const;
+const PRESENCE_FILTERS: Readonly<Record<string, string>> = {
+  DEGRADED: String(STATES.DEGRADED.filter ?? ''),
+  OFFLINE: String(STATES.OFFLINE.filter ?? ''),
+};
+
+export function createCanvasAvatar(
+  options: CanvasAvatarOptions,
+  config: CanvasAvatarConfig,
+): AvatarInstance {
+  const { mount, client, ...gains } = options;
+  if (!mount) throw new TypeError('createAvatar: `mount` is required');
+  if (!client) throw new TypeError('createAvatar: `client` is required');
+  for (const key of GAINS) {
+    const gain = gains[key];
+    if (gain === undefined) continue;
+    if (!Number.isFinite(gain) || gain < 0 || gain > 2) {
+      throw new RangeError(`createAvatar: \`${key}\` must be 0..2, got ${String(gain)}`);
+    }
+  }
+
+  const canvas = createCanvasRig({
+    url: config.rigUrl,
+    images: config.images,
+    face: config.face,
+    label: config.label,
+  });
+  const widget = createMixer({ mount, rig: canvas.factory, ...gains });
+  const driver = new AvatarClient(widget, {
+    onPresenceChange: (state) => canvas.setPresenceFilter(PRESENCE_FILTERS[state] ?? ''),
+  });
+  const detach = driver.attach(client as PipecatClient);
+
+  let destroyed = false;
+  return {
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      detach();
+      driver.destroy();
+      widget.destroy();
+    },
+  };
+}

package/client/index.ts

@@ -0,0 +1,39 @@
+/**
+ * `@voqalize/avatar` — a talking head that embodies a `PipecatClient`.
+ *
+ *     import { createAvatar } from "@voqalize/avatar";
+ *
+ *     const avatar = createAvatar({ mount: el, client: pipecatClient });
+ *
+ * That is the whole public surface. Put an `AvatarProcessor` in the pipecat
+ * pipeline (`pip install voqalize-avatar`), mount this in the bot's tile, and
+ * the face listens, thinks, claims the floor and lipsyncs what the TTS says.
+ *
+ * Entry points, and the split is the design rather than packaging taste:
+ *
+ * - `@voqalize/avatar` — this one. Framework-free. `@pipecat-ai/client-js` is
+ *   a type-only import, so even that peer is genuinely optional at runtime.
+ *   It carries exactly one drawing: `peep`, the default face.
+ * - `@voqalize/avatar/faces/{peep,wren,myna}` — one drawing each. Import the
+ *   one you want and pass it as `face`; the others never enter your bundle.
+ * - `@voqalize/avatar/react` — `<Avatar>`. Pulls React; nothing here does.
+ * - `@voqalize/avatar/internal` — the SVG widget, the behavior catalog and the
+ *   viseme clock. **No semver promise**: these move in any minor. They are
+ *   exported because an avatar author building on our renderer needs them, not
+ *   because they are an interface.
+ *
+ * To ship your own avatar, publish a module exporting `createAvatar` and import
+ * that instead — see `createAvatar.ts` and docs/design-avatar-interface.md.
+ */
+
+export { createAvatar } from "./createAvatar.js";
+export type {
+  AvatarOptions,
+  AvatarInstance,
+  AvatarFactory,
+  SvgAvatarOptions,
+  Face,
+  FaceTheme,
+  Gain,
+  HandSide,
+} from "./createAvatar.js";

package/client/internal.ts

@@ -0,0 +1,80 @@
+/**
+ * `@voqalize/avatar/internal` — the parts of our own implementation that
+ * another avatar can build on.
+ *
+ * **Nothing here is covered by semver.** Names, signatures and semantics move
+ * in any minor release. It is exported because an avatar author who wants the
+ * SVG mixer, the behavior catalog or — most usefully — the viseme clock should
+ * not have to vendor a copy, not because any of it is an interface. The
+ * interface is `createAvatar`, and it is one function.
+ *
+ * The one thing here worth reaching for on purpose is `VisemeTrack`: someone
+ * has to turn a cue array plus a clock into "which mouth shape is on screen
+ * right now", every renderer needs exactly that, and it is a solved problem.
+ *
+ *     const track = new VisemeTrack();
+ *     track.start(cues, () => performance.now() - t0);
+ *     // per frame:
+ *     const s = track.sample();   // { letter: "D", intensity: 1 } | null
+ *
+ * `docs/internal-rig.md` describes the pose-channel model the bundled SVG
+ * renderer uses internally. It is *not* the seam to implement — see
+ * docs/design-avatar-interface.md.
+ */
+
+export {
+  // The bundled SVG widget. Not the faces: importing one from here would put
+  // all three in every bundle that wanted the viseme clock.
+  // `@voqalize/avatar/faces/<name>` is where a face comes from.
+  createAvatar as createSvgAvatar,
+  STATES,
+  STATE_NAMES,
+  ACTIONS,
+  ACTION_IDS,
+  GAZE_NAMES,
+  GAZE_TARGETS,
+  EMOTION_NAMES,
+  // The viseme clock and its tables.
+  VisemeTrack,
+  VISEME_LETTERS,
+  VISEME_SHAPES,
+  SILENT,
+  LEAD_MS,
+  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 {
+  BEHAVIOR_STATES,
+  BEHAVIOR_STATE_IDS,
+  BEHAVIOR_ACTIONS,
+  BEHAVIOR_ACTION_IDS,
+  WIRE_ACTION_TO_BEHAVIOR,
+} from "../src/behavior.js";
+
+export type { BehaviorStateId, BehaviorActionId } from "../src/behavior.js";
+
+export { isAvatarMessage } from "./types.js";
+export type {
+  AvatarCommand,
+  AvatarCue,
+  AvatarCuesCmd,
+} from "./types.js";

package/client/interviewer-female.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `meera`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './meera.js';
+export type { CanvasAvatarOptions, CanvasAvatarOptions as InterviewerAvatarOptions } from './createCanvasAvatar.js';

package/client/interviewer-male.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `arjun`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './arjun.js';
+export type { CanvasAvatarOptions, CanvasAvatarOptions as InterviewerAvatarOptions } from './createCanvasAvatar.js';

package/client/ishita.ts

@@ -0,0 +1,24 @@
+/** Polished professional female avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-female-a.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-female-a-top-body.webp': new URL('../src/canvas/data/img/professional-female-a-top-body.webp', import.meta.url),
+  'professional-female-a-hair-back.webp': new URL('../src/canvas/data/img/professional-female-a-hair-back.webp', import.meta.url),
+  'professional-female-a-hair-front.webp': new URL('../src/canvas/data/img/professional-female-a-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Ishita — polished professional female avatar',
+  });
+}

package/client/kabir.ts

@@ -0,0 +1,24 @@
+/** Relaxed professional male avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-male-b.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-male-b-top-body.webp': new URL('../src/canvas/data/img/professional-male-b-top-body.webp', import.meta.url),
+  'professional-male-b-hair-back.webp': new URL('../src/canvas/data/img/professional-male-b-hair-back.webp', import.meta.url),
+  'professional-male-b-hair-front.webp': new URL('../src/canvas/data/img/professional-male-b-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Kabir — relaxed professional male avatar',
+  });
+}

package/client/meera.ts

@@ -0,0 +1,24 @@
+/** Professional Indian female interviewer, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/interviewer-female.rig.json', import.meta.url);
+const IMAGES = {
+  'round-w1-hair-back.webp': new URL('../src/canvas/data/img/round-w1-hair-back.webp', import.meta.url),
+  'round-w1-top-body.webp': new URL('../src/canvas/data/img/round-w1-top-body.webp', import.meta.url),
+  'round-w1-hair-front.webp': new URL('../src/canvas/data/img/round-w1-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Meera — professional female interviewer avatar',
+  });
+}

package/client/naina.ts

@@ -0,0 +1,24 @@
+/** Relaxed professional female avatar, authored to read at call-tile size. */
+
+import { createCanvasAvatar } from './createCanvasAvatar.js';
+import type { CanvasAvatarOptions } from './createCanvasAvatar.js';
+import type { AvatarInstance } from './createAvatar.js';
+
+const RIG_URL = new URL('../src/canvas/data/professional-female-b.rig.json', import.meta.url);
+const IMAGES = {
+  'professional-female-b-top-body.webp': new URL('../src/canvas/data/img/professional-female-b-top-body.webp', import.meta.url),
+  'professional-female-b-hair-back.webp': new URL('../src/canvas/data/img/professional-female-b-hair-back.webp', import.meta.url),
+  'professional-female-b-hair-front.webp': new URL('../src/canvas/data/img/professional-female-b-hair-front.webp', import.meta.url),
+} as const;
+const FACE = () => import('../src/canvas/avatars/round/face.mjs');
+
+export type { CanvasAvatarOptions };
+
+export function createAvatar(options: CanvasAvatarOptions): AvatarInstance {
+  return createCanvasAvatar(options, {
+    rigUrl: RIG_URL,
+    images: IMAGES,
+    face: FACE,
+    label: 'Naina — relaxed professional female avatar',
+  });
+}

package/client/professional-female-a.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `ishita`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './ishita.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-female-b.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `naina`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './naina.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-male-a.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `vikram`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './vikram.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/professional-male-b.ts

@@ -0,0 +1,4 @@
+/** @deprecated Renamed to `kabir`; kept as an alias so existing imports keep working. */
+
+export { createAvatar } from './kabir.js';
+export type { CanvasAvatarOptions } from './createCanvasAvatar.js';

package/client/react.ts

@@ -0,0 +1,13 @@
+/**
+ * `@voqalize/avatar/react` — the avatar as one component.
+ *
+ *     import { Avatar } from "@voqalize/avatar/react";
+ *
+ *     <Avatar client={session.client} className="avatar-tile" />
+ *
+ * Separate from the main entry so that `createAvatar` costs nothing to a
+ * caller who is not on React — React is an optional peer, and a barrel that
+ * re-exported this would make it a hard one.
+ */
+
+export { Avatar, type AvatarProps } from "./Avatar.js";

package/client/types.ts

@@ -0,0 +1,146 @@
+/**
+ * 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 { ACTION_IDS, VISEME_LETTERS } from "../src/avatar.js";
+import type { AvatarActionId, 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;
+}
+
+/** A durable, lower-priority server claim. `null` explicitly clears it. */
+export interface AvatarClaimCmd {
+  cmd: "claim";
+  state: "STRAINING" | "THINKING" | "WORKING" | null;
+}
+
+/** A self-completing authored sequence: face, body, and optionally a hand. */
+export interface AvatarActionCmd {
+  cmd: "action";
+  id: AvatarActionId;
+}
+
+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 =
+  | AvatarClaimCmd
+  | 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 function isAvatarMessage(msg: unknown): msg is AvatarEnvelope {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  return m.type === AVATAR_MESSAGE_TYPE && typeof m.cmd === "string";
+}
+
+const ACTIONS = new Set<string>(ACTION_IDS);
+const LETTERS = new Set<string>(VISEME_LETTERS);
+
+/**
+ * Read an envelope's payload into the wire vocabulary, or `null` if this build
+ * cannot act on it — an unknown `cmd`, an id or claim outside the enum, 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: AvatarEnvelope): AvatarCommand | null {
+  switch (msg.cmd) {
+    case "claim": {
+      const state = msg.state;
+      if (state === null || state === "STRAINING" || state === "THINKING" || state === "WORKING") {
+        return { cmd: "claim", state };
+      }
+      return null;
+    }
+    case "action":
+      return typeof msg.id === "string" && ACTIONS.has(msg.id)
+        ? { cmd: "action", id: msg.id as AvatarActionId }
+        : null;
+    case "cues": {
+      if (typeof msg.ctx !== "string" || !Number.isFinite(msg.from_ms) || !Array.isArray(msg.cues)) {
+        return null;
+      }
+      const cues: AvatarCue[] = [];
+      for (const c of msg.cues as unknown[]) {
+        if (typeof c !== "object" || c === null) continue;
+        const { t, v, i } = c as Record<string, unknown>;
+        if (typeof t !== "number" || !Number.isFinite(t)) continue;
+        if (typeof v !== "string" || !LETTERS.has(v)) continue;
+        cues.push(typeof i === "number" ? { t, v: v as VisemeLetter, i } : { t, v: v as VisemeLetter });
+      }
+      return {
+        cmd: "cues",
+        ctx: msg.ctx,
+        from_ms: msg.from_ms as number,
+        cues,
+        ...(msg.final === true ? { final: true as const } : {}),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+/** The envelope `type` the protocol reserves for avatar traffic. */
+export const AVATAR_MESSAGE_TYPE = "avatar";