@voqalize/avatar 0.0.1

package/client/src/pipecat.ts

@@ -0,0 +1,38 @@
+/**
+ * `@voqalize/avatar/pipecat` — drive the widget from a pipecat session.
+ *
+ * Framework-free: everything here is plain TypeScript over the `AvatarApi` the
+ * root export returns. `AvatarClient` is the whole surface — construct it
+ * around a mounted widget and either `attach()` it to a live `PipecatClient`
+ * or feed it messages yourself with `dispatch()`.
+ *
+ *     import { createAvatar } from "@voqalize/avatar";
+ *     import { AvatarClient } from "@voqalize/avatar/pipecat";
+ *
+ *     const avatar = createAvatar({ mount: "#tile" });
+ *     const detach = new AvatarClient(avatar).attach(pipecatClient);
+ *
+ * `@pipecat-ai/client-js` is a peer dependency of this subpath only — the root
+ * export has no dependencies at all, and a host that carries avatar commands
+ * over its own transport can import this module and never call `attach()`.
+ */
+
+export { AvatarClient, type AvatarClientOptions } from "./AvatarClient.js";
+
+export {
+  isAvatarMessage,
+  AVATAR_MESSAGE_TYPE,
+  AVATAR_PROTOCOL_VERSION,
+  type AvatarCommand,
+  type AvatarCue,
+  type AvatarCuesCmd,
+  type AvatarHintCmd,
+  type AvatarInterjectCmd,
+  type AvatarPerformAction,
+  type AvatarPerformCmd,
+  type AvatarServerMessage,
+  type AvatarSpeechCmd,
+  type AvatarStateCmd,
+  type AvatarUnknownCmd,
+  type AvatarUserCmd,
+} from "./types.js";

package/client/src/react.ts

@@ -0,0 +1,34 @@
+/**
+ * `@voqalize/avatar/react` — the React binding.
+ *
+ *     import { Avatar } from "@voqalize/avatar/react";
+ *
+ *     <Avatar client={pipecatClient} className="tile" />
+ *
+ * Peers: `react >= 18` and `@pipecat-ai/client-js`. Everything a non-React
+ * host needs is in `@voqalize/avatar/pipecat`; this module adds a mount
+ * lifecycle and nothing else.
+ */
+
+export { useAvatar, type UseAvatarHandle, type UseAvatarOptions } from "./useAvatar.js";
+export { Avatar, type AvatarProps } from "./Avatar.js";
+
+// Re-exported so a React consumer needs one import for the common case.
+export { AvatarClient, type AvatarClientOptions } from "./AvatarClient.js";
+export {
+  isAvatarMessage,
+  AVATAR_MESSAGE_TYPE,
+  AVATAR_PROTOCOL_VERSION,
+  type AvatarCommand,
+  type AvatarCue,
+  type AvatarCuesCmd,
+  type AvatarHintCmd,
+  type AvatarInterjectCmd,
+  type AvatarPerformAction,
+  type AvatarPerformCmd,
+  type AvatarServerMessage,
+  type AvatarSpeechCmd,
+  type AvatarStateCmd,
+  type AvatarUnknownCmd,
+  type AvatarUserCmd,
+} from "./types.js";

package/client/src/types.ts

@@ -0,0 +1,127 @@
+/**
+ * types.ts — the avatar wire vocabulary, client side.
+ *
+ * The binding definition is `docs/contract-protocol.md`; this file is its
+ * TypeScript restatement and must not drift from it. The Python half of the
+ * same vocabulary is `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", v: 1, ...cmd-specific fields }`. {@link AvatarCommand}
+ * describes the *payload*, not the envelope, because the payload is what
+ * arrives however the host chose to carry it — `AvatarClient.dispatch()`
+ * accepts anything with a string `cmd`, so an application that tunnels these
+ * through its own message type can hand them straight over.
+ */
+
+/** 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: string;
+  i?: number;
+}
+
+/** `perform()` timeline action — see docs/contract-protocol.md § Composing behavior. */
+export interface AvatarPerformAction {
+  t: number;
+  do: "state" | "emotion" | "gaze" | "interject";
+  name?: string;
+  id?: string;
+  i?: number;
+  keepGaze?: boolean;
+}
+
+export interface AvatarStateCmd {
+  cmd: "state";
+  name: string;
+  emotion?: string;
+  gaze?: string;
+}
+
+export interface AvatarInterjectCmd {
+  cmd: "interject";
+  id: string;
+}
+
+export interface AvatarPerformCmd {
+  cmd: "perform";
+  actions: AvatarPerformAction[];
+  ctx?: string;
+}
+
+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 `speech stop` remains the end of the turn. It is safe to release
+   * per-turn cue state (the splice buffer for `ctx`) once the last cue has
+   * played, and safe to stop expecting more.
+   *
+   * 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 interface AvatarSpeechCmd {
+  cmd: "speech";
+  event: "start" | "stop";
+  ctx: string;
+}
+
+export interface AvatarUserCmd {
+  cmd: "user";
+  speaking: boolean;
+}
+
+export interface AvatarHintCmd {
+  cmd: "hint";
+  kind: "eager_eot" | (string & {});
+}
+
+/** A cmd this build doesn't recognize — dispatched to nothing, ignored for forward compat. */
+export interface AvatarUnknownCmd {
+  cmd: string;
+  [key: string]: unknown;
+}
+
+export type AvatarCommand =
+  | AvatarStateCmd
+  | AvatarInterjectCmd
+  | AvatarPerformCmd
+  | AvatarCuesCmd
+  | AvatarSpeechCmd
+  | AvatarUserCmd
+  | AvatarHintCmd
+  | AvatarUnknownCmd;
+
+/** The full server-message payload: the avatar envelope plus its `cmd`. */
+export type AvatarServerMessage = AvatarCommand & {
+  type?: "avatar";
+  v?: number;
+};
+
+/** Narrows an unknown server-message payload to an avatar command. */
+export function isAvatarMessage(msg: unknown): msg is AvatarServerMessage {
+  if (typeof msg !== "object" || msg === null) return false;
+  const m = msg as Record<string, unknown>;
+  return typeof m.cmd === "string";
+}
+
+/** The envelope `type` the protocol reserves for avatar traffic. */
+export const AVATAR_MESSAGE_TYPE = "avatar";
+
+/** The protocol version this client speaks — matches `AVATAR_PROTOCOL_VERSION`
+ * in the Python package. Sent as `v` and, today, never checked: an unknown
+ * `cmd` is ignored rather than version-gated, which is the forward-compat rule
+ * the contract states. */
+export const AVATAR_PROTOCOL_VERSION = 1;

package/client/src/useAvatar.ts

@@ -0,0 +1,113 @@
+/**
+ * useAvatar — mount the widget, wire it to a live session, dispatch its
+ * server-messages, and clean up.
+ *
+ * Options are read through a ref so the effect doesn't re-subscribe on every
+ * render. Split in two effects: mounting the widget happens once (an avatar or
+ * theme swap remounts by design — see the note in the effect); attaching to
+ * the pipecat client re-runs whenever the client identity changes (a session
+ * reconnect mints a new one) or once the widget instance becomes available.
+ */
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { PipecatClient } from "@pipecat-ai/client-js";
+import { createAvatar, type AvatarApi, type CreateAvatarOptions } from "../../src/avatar.js";
+import { AvatarClient, type AvatarClientOptions } from "./AvatarClient.js";
+
+export interface UseAvatarOptions extends AvatarClientOptions {
+  /** Name from `AVATAR_NAMES`. Omit for the widget's own `DEFAULT_AVATAR`. */
+  avatar?: string;
+  theme?: CreateAvatarOptions["theme"];
+  /** Articulation gains — see docs/contract-protocol.md § Events, gains, introspection. */
+  mouthGain?: number;
+  gestureGain?: number;
+  /** The live `PipecatClient` to dispatch server-messages from, or `null`
+   * before connect. `useAvatar` (dis)connects the subscription as this
+   * changes; it does not create or own the client. */
+  client?: PipecatClient | null;
+}
+
+/**
+ * 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;
+  /** The live widget instance once mounted, else `null`. */
+  avatar: AvatarApi | null;
+  /** The dispatcher wrapping `avatar` — `null` until mounted. Exposed for
+   * tests and telemetry (`turnCtx`, `turnCues`) and for manual dispatch. */
+  client: AvatarClient | null;
+  /** Dispatch one avatar command by hand — e.g. from a dev-tools console, or
+   * from a transport that isn't a `PipecatClient`. No-ops before mount. */
+  dispatch: (msg: unknown) => void;
+}
+
+export function useAvatar(options: UseAvatarOptions = {}): UseAvatarHandle {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [avatar, setAvatar] = useState<AvatarApi | null>(null);
+  const avatarClientRef = useRef<AvatarClient | null>(null);
+
+  // Latest-options ref, so the mount effect (which runs once) still reads live
+  // callback props without re-subscribing.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    const mount = containerRef.current;
+    if (!mount) return;
+    const instance = createAvatar({
+      mount,
+      avatar: optionsRef.current.avatar,
+      theme: optionsRef.current.theme,
+      mouthGain: optionsRef.current.mouthGain,
+      gestureGain: optionsRef.current.gestureGain,
+    });
+    const wrapper = new AvatarClient(instance, {
+      onHint: (kind, msg) => optionsRef.current.onHint?.(kind, msg),
+      onUnknownCmd: (msg) => optionsRef.current.onUnknownCmd?.(msg),
+      onError: (err, msg) => optionsRef.current.onError?.(err, msg),
+      onSpeakingDrift: (info) => optionsRef.current.onSpeakingDrift?.(info),
+      accept: optionsRef.current.accept,
+      now: optionsRef.current.now,
+    });
+    avatarClientRef.current = wrapper;
+    setAvatar(instance);
+
+    return () => {
+      instance.destroy();
+      avatarClientRef.current = null;
+      setAvatar(null);
+    };
+    // Mount once. `avatar`/`theme`/the gains are read at mount time only — the
+    // widget has no hot-swap-avatar API (`createFace` runs once per mount), so
+    // changing them re-renders nothing here by design; a caller that needs a
+    // different avatar remounts with a `key` prop (see the component's doc).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  useEffect(() => {
+    const wrapper = avatarClientRef.current;
+    const pipecatClient = options.client;
+    if (!wrapper || !pipecatClient) return;
+    return wrapper.attach(pipecatClient);
+    // Re-subscribe when the widget mounts or the session's client changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [avatar, options.client]);
+
+  const dispatch = useCallback((msg: unknown) => {
+    avatarClientRef.current?.dispatch(msg);
+  }, []);
+
+  return { containerRef, avatar, client: avatarClientRef.current, dispatch };
+}

package/docs/contract-avatar.md

@@ -0,0 +1,337 @@
+# Contract B — mixer ↔ face (the avatar contract)
+
+*Living document. Describes the code as of `src/face*.js` on `main`; the
+[Direction](#direction) section flags what is about to change. The counterpart
+contract — what the server drives — is
+[contract-protocol.md](contract-protocol.md).*
+
+An avatar is a module exporting exactly this, and nothing more:
+
+```js
+createFace(mount, theme) -> { svg, apply(params), theme, destroy() }
+META = { viewBox: {x, y, w, h}, mouthCrop: {x, y, w, h} }
+```
+
+- `mount` — element to render into. `destroy()` empties it.
+- `theme` — optional per-key colour overrides merged over the rig's palette;
+  the merged object is returned as `theme`. Theme *keys* are per-avatar
+  (peep and wren carry 8 each; the retired rigs shared a ~25-key palette).
+  Hosts that paint *around* the widget read them off `api.theme` — see
+  Palettes below.
+- `svg` — the live `<svg>` element.
+- `apply(params)` — write one full parameter vector into the DOM. Called every
+  animation frame.
+- `META` — the **avatar descriptor**: what a host or tool may know about the
+  face without opening it. `viewBox` is the framing (hosts derive aspect from
+  it; `createAvatar` exposes it as `api.meta`); `mouthCrop` frames the mouth
+  for close inspection (the contact sheet's viseme-detail row). Deliberately
+  minimal — a landmark joins META when a second consumer needs it, not before.
+
+**A face must be callable standalone.** Three rig-tooling pages call
+`AVATARS[name].create(mount)` directly with no mixer and drive `apply()` from
+a raw vector; a face that only works under `createAvatar` is broken.
+
+Nothing above the face knows what a face looks like; nothing in the face knows
+what a call is. If a visual change needs `params.js` touched, reconsider; if
+it needs anything outside `src/face*.js`, it's a bug.
+
+## Obligations of `apply(params)`
+
+- **Consume, don't smooth.** Values arrive already clamped to `RANGE` and
+  already smoothed through per-channel time constants. Add no easing of your
+  own.
+- **Idempotent and cheap.** Same vector in, same DOM out; memoize attribute
+  writes (every rig shares a `prev`-map `set(node, attr, val)` helper) so
+  an unchanged channel costs nothing. ~60 calls/s is the budget.
+- **Never write `viewBox`.** Every pose channel is a transform or a path,
+  never the camera. Tooling relies on this to crop safely after `apply()`.
+- **Honour the channel's *semantic*, not its plumbing.** The channel value is
+  what an author of `visemes.js`/`emotions.js` — who never sees your rig —
+  thinks they are asking for. The standing example: `mouthOpen` denotes the
+  *visible aperture*. peep initially mapped it to the gap between lip
+  centrelines; the drawn lip band was ~11 units thick, so the mouth stayed
+  visibly shut until 0.25 and two of the nine visemes live below that. The fix
+  was to solve back from aperture to control points, not to re-tune the
+  visemes.
+
+## The parameter vector
+
+30 float channels (`src/params.js`). Rest is the neutral face; range is the
+post-mix clamp; τ is the smoothing time constant the mixer applies (the face
+never does). Sign conventions are from the *viewer's* perspective.
+
+| channel | rest | range | τ (s) | means |
+|---|---|---|---|---|
+| `mouthOpen` | 0.02 | 0..1 | 0.042 | visible vertical aperture |
+| `mouthWidth` | 0.42 | 0..1 | 0.042 | narrow..wide (0.42 neutral) |
+| `mouthRound` | 0.10 | 0..1 | 0.042 | pucker / protrusion |
+| `mouthPress` | 0.15 | 0..1 | 0.042 | lips thinned & pressed |
+| `mouthTuck` | 0 | 0..1 | 0.042 | lower lip under upper teeth (F/V) |
+| `mouthCornerL/R` | 0.10 | −1.4..1.4 | 0.13 | −frown..+smile |
+| `teethUpper` | 0 | 0..1 | 0.042 | upper-teeth reveal |
+| `tongue` | 0 | 0..1 | 0.042 | tongue raised into aperture (L) |
+| `jaw` | 0 | 0..1 | 0.07 | extra chin drop, lags the lips |
+| `lidL/R` | 0.12 | 0..1 | 0.018 | 0 wide open..1 closed; rest grazes the iris |
+| `squintL/R` | 0 | 0..1 | 0.12 | lower lid raised (smile/suspicion) |
+| `pupilX/Y` | 0 / 0.05 | −1..1 | 0.032 | gaze offset, +right / +down |
+| `browRaiseL/R` | 0 | −1..1 | 0.08 | whole-brow lift |
+| `browAngleL/R` | 0 | −1.4..1.4 | 0.08 | outer-end up |
+| `browInnerL/R` | 0 | −1..1 | 0.08 | inner-end lift (AU1, "concern") |
+| `headYaw` | 0 | −1.4..1.4 | 0.16 | + toward viewer's right |
+| `headPitch` | 0 | −1.4..1.4 | 0.16 | + chin down |
+| `headRoll` | 0 | −1.4..1.4 | 0.16 | + tilt toward viewer's right |
+| `breath` | 0 | 0..1 | 0.25 | idle-driven breathing cycle |
+| `shoulderL/R` | 0 | −1..1 | 0.19 | −dropped..+raised |
+| `torsoLean` | 0 | −1..1 | 0.24 | −back..+forward; reads as scale change |
+| `torsoTurn` | 0 | −1..1 | 0.44 | trunk lateral travel, + toward viewer's right |
+
+Groups (`GROUPS`): `mouth`, `smile`, `eyes`, `gaze`, `brows`, `head`, `body`
+(breath + torsoLean + torsoTurn), `shoulders` — clips declare group ownership by
+them.
+
+`torsoTurn`'s time constant is nearly 3× the head's, and that ratio is load-
+bearing rather than taste: the mixer feeds it the *same* target as `headYaw`
+(scaled by `TRUNK_FOLLOW = 0.45` in `avatar.js`), so a sustained head turn is
+chased by a trunk that leaves late and settles late. Follow-through falls out of
+the smoothing the rig already had; there is no second animation system. Shorten
+it toward 0.16 and head and trunk move as one rigid piece, which is the puppet
+read.
+
+A face should consume all 30. One sanctioned exception exists: peep ignores
+`jaw` (its construction has no drawn jaw line to drop — a documented character
+decision, not an oversight).
+
+There are deliberately **no arm or hand channels**; see the note in
+`params.js` before considering any.
+
+## Invariant vs per-avatar
+
+Three rigs were built independently and their `apply()` implementations
+converged on the same eight blocks in the same order — torso lean → shoulders
+→ parallax layer loop → eyes → brows → mouth → teeth → tongue — with the same
+memoizer and the same return shape. That convergence now lives in
+**`src/face-core.js`**, which owns:
+
+- the shell: mount, id-scoped selector, the memoized `set(node, attr, val)`;
+- `poseTransforms(p, set, el, POSE)` — lean, shoulders, parallax, driven by a
+  per-rig `POSE` spec of named scalars (below);
+- the shared feature fragments a rig opts into where its model matches:
+  `pairedTeeth` (peep, wren). Two more — `irisLidEyes` and `browPair` — were
+  removed with the rigs that used them; a future rig with sclera and
+  endpoint-pair brows should recover them from git history rather than
+  re-derive them;
+- the shared constants: lean scale `0.055`, head-roll multipliers ×5.5
+  features / ×1.5 torso, shrug/tilt derivation `shrug=(L+R)/2`, `tilt=(R−L)/2`,
+  lower-teeth reveal ramp `(open − 0.45) / 0.4`, tongue gate `> 0.02`;
+- `faceApi` — the return shape.
+
+What legitimately varies per avatar, and stays in the face module:
+
+- **The `POSE`/`EYES` spec values**: `yawPx`/`pitchPx` (parallax travel),
+  `pivot`, lean travel and pivot, shrug lift and tilt degrees, `turnPx` (lateral
+  trunk travel at `torsoTurn = 1`), the breath model, pupil travel, `lidFollow`
+  strength (0.22 on both current rigs), plus a `units` factor (see Art units).
+- **The breath model's numbers**. A rig declares `breathSwell` + `swellPivot`
+  and breathes as a *scale about the hem*:
+  the shoulder line rises and the chest widens while the bottom of the shirt
+  stays put, and the head's matching lift is derived arithmetic
+  (`swell × (swellPivot.y − pivot.y)`) rather than a second tuned constant, so
+  the two layers cannot drift and the neck cannot telescope. `breathSwell` is
+  required. It replaced a rigid vertical slide of the whole shirt, which moved
+  *more* pixels and read as *less* alive — a figure translating up and down has
+  been nudged, not filled with air.
+- **Structural choices**: layer set and parallax table (the retired rigs ran 7
+  layers and 4; peep and wren fuse to 4 — the art decides, not a standard); eye
+  model
+  (iris + 4 lid paths vs peep's single translated group + regenerated bean);
+  brow input (endpoint pair vs drawn point list); mouth output (path strings
+  vs peep's contour point list); which optional elements exist (`jaw` shade,
+  `subLip`, `seam`, split lip edges, lower teeth). A rig whose model diverges
+  keeps its own block instead of the shared fragment — peep's eyes and brows
+  are the standing example.
+
+Do not chase parity between faces: they are separate drawings, not renderings
+of one drawing. A visual improvement lands in one face and stops there.
+
+## Art units
+
+Units are per-rig (peep 760×950 cropped to `92 76 576 800`; wren and myna the
+same window at `92 50`; the retired rigs were 320×400 and a native 1024² cropped to
+`179 42 666 832` — note how little the aspect agreed). **Copying a magnitude
+between rigs is silent breakage**: one retired rig's travels were the other's
+numbers with `units: S` (S = 2.67) in its `POSE` spec; peep's torso channels
+were once ported without conversion and the shoulders stopped reading, while
+nothing threw and `sweep()` passed. The trap inside the
+trap: **translations convert, degrees don't** — a rotation is already
+unit-independent, which is why `shrugTiltDeg` never takes the `units` factor.
+
+`viewBox` is not a rig constant. Hosts derive aspect from `META.viewBox` (or
+`api.meta.viewBox`); the demos do.
+
+## Registration
+
+`src/avatar.js` holds the registry — `{ create, meta }` records:
+
+```js
+export const AVATARS = {
+  peep: { create, meta },
+  wren: { create, meta },
+  myna: { create, meta },
+};
+export const DEFAULT_AVATAR = 'peep';
+createAvatar({ avatar: 'peep' })      // by name
+createAvatar({ face: myCreateFace })  // any factory, never registered
+```
+
+A bare `face:` factory has no descriptor; `createAvatar` then derives
+`meta.viewBox` from the produced svg and `meta.mouthCrop` is absent — registry
+avatars always carry the full META.
+
+Palettes: there is no barrel `THEME` export — each face module owns its
+palette, and `api.theme` returns the mounted avatar's. A host needs it
+whenever it paints anything *around* the widget: every rig is drawn portrait,
+so a 16:9 call tile leaves a margin either side of the drawing, and the margin
+has to be filled with the rig's own backdrop or the tile reads as a portrait
+picture hung in a landscape frame. `demo/call.html` does exactly that — tile
+background from `theme.bg0/bg1`, plus a mask feathering the drawing's two
+vertical edges, because peep's white shirt is drawn to run off its own frame
+and otherwise stops in mid-air. Reshaping the art to fit a host's box is the
+wrong fix; the widget does not control the box. peep has
+no dark palette **by decision** (inverting two-value line art recolours the
+hair and ages the character; that is geometry wearing a palette's clothes) —
+its theme keys stay overridable, but do not add a `dark` selector.
+
+## Checklist for a new avatar
+
+1. Serve with `python3 serve.py 8777` (never `python3 -m http.server` — its
+   caching has burned this project three times).
+2. `demo/rig/contact-sheet.html?face=NAME` — every viseme, emotion, gaze and
+   channel extreme. Check the **mouth-detail crop row**, not just full heads:
+   two visemes can be numerically distinct and visually identical (`G` vs `B`
+   both read as a white strip until `G` was rebuilt as nearly-all-teeth). At
+   avatar size a viseme is ~40 px tall; letter collisions are invisible on the
+   full-head row. The crop row frames itself from your `META.mouthCrop`.
+3. `demo/rig/torso-check.html?face=NAME` — shoulders × lean × head pose.
+   These channels only fail *in combination*; this is where a rig leaks
+   background from behind the shirt if it is going to.
+4. `demo/rig/clip-strip.html?clip=NOD_SMALL&face=NAME` — phase relationships
+   through the mixer's own smoothing, as a filmstrip.
+5. `demo/rig/rig-check.html` → `await sweep()` — conformance: params finite,
+   `|v| ≤ 2`, svg connected, across every state/emotion/gaze/interjection and
+   a viseme track. Sweep also cannot see *looks*; it reaches shoulders/torso
+   only through clips, so drive those with a `setOverrides` loop over
+   `[-1, 0, 1]` per channel.
+6. Auto-traced art has known failure modes to budget for: zero-margin abutting
+   contours open seams under parallax; the trace stops at the source crop;
+   hard horizontal edges invisible in the source appear under motion.
+7. **The 130 px acceptance pass** — downsample the rest pose, the emotions
+   row and the X/A mouth crops to ~130 px and judge *there*. Author at
+   close-up, accept at tile size: the mouth must still read as smiling (not
+   merely present), the six emotions must be tellable apart, and X vs A must
+   differ in *shape*. Run the fixation audit on the rest tile: name the first
+   three things you see, in order — the eye/mouth band places no worse than
+   second. (Why: [research-perception.md](research-perception.md) §2, §5, §8.)
+8. **Levelness by mirror** — render rest, flip it horizontally, and compare
+   the pair; tilt and lopsidedness pop instantly. Judge on the glasses line
+   and eye line. Rest must be channel-neutral and dead level: the mixer adds
+   roll, sway and glances at runtime, and a baked-in tilt compounds with all
+   of them. Drawing asymmetry (fringe, chin off midline) is welcome; *pose*
+   asymmetry is a defect.
+9. **Worst-case composites, not rest poses, for clearances** — build the
+   extreme combination for every pair of marks that move relative to each
+   other (brows-down + squint + pitch against a glasses frame; wide-open
+   mouth against any under-lip mark) and verify a hard 3–4 unit gap.
+   Near-tangency shimmers under animation. If an accessory and a channel
+   collide, the accessory yields. Also render one **mid-blink** frame (lids
+   held ~0.5 via rig-check's `pose()`): anything that must ride the lid — a
+   lash line — is caught here, not at open or closed.
+10. **Independent design review** — before a face is called done, a fresh-eyes
+    reviewer (not the author) critiques it against the *product brief* at
+    tile size, organized around the questions in
+    [research-perception.md](research-perception.md): fixation hierarchy,
+    resting trust/warmth, neoteny calibration, caricature economy, animation
+    head-room, silhouette, long-session comfort. The output is prescriptions
+    ranked by perceptual payoff ÷ stroke cost, plus a **protect-list** of
+    marks confirmed right — which then stops future churn on them.
+
+## Adding a new avatar
+
+Both halves of the old Direction section landed (`src/face-core.js` and
+`META`), and the recipe has been run end-to-end twice: `wren` as the plumbing
+proof, and `myna` (2026-08-07) as the proof of the *staged* process below —
+which is where the time and the judgement actually went.
+
+### The staged process
+
+Identity and production quality are different problems; solving them in
+stages, with different acceptance bars, is what kept the myna run converging.
+
+- **Stage 0 — identity source.** A stakeholder-supplied reference image is
+  the identity spec. Hard lesson (koel, rejected on sight the same day it
+  passed every rig check): character identity is judged against a concrete
+  image, not against adjectives — a brief-first avatar optimizes the wrong
+  target however well it verifies. If there is no reference, get one agreed
+  before authoring.
+- **Stage 1 — distill, then match.** Extract from the reference: the
+  silhouette, the 3–5 identity marks, and the palette structure (where the
+  one accent sits). That distillate — not the pixels — is what gets matched
+  (peak shift: exaggerate the distinctive, simplify the generic —
+  research-perception.md §5). *Measure* proportions off the bitmap instead of
+  eyeballing (lens w:h, feature heights as fractions of face height — myna's
+  glasses only landed when measured). Hand-author in the idiom; never
+  auto-trace. The bar for this stage is the squint test at full size and
+  130 px: same person?
+- **Stage 2 — production calibration.** The reference *stops being the bar*;
+  the brief takes over. This is where the science does the work, all of it
+  judged on the 130 px surface: mouth ink floor so warmth survives the tile;
+  channel→geometry gains raised until shared emotion poses land (categorical
+  perception: near-extreme or invisible); resting brow/mouth set for trust,
+  not personality (the smirk composite); resting lid graze against stare;
+  interiors calmed against nod-flicker; clearance envelopes at worst-case
+  composites; shape-not-amplitude viseme separation. Guardrail: **one neoteny
+  move per round** (eye size *or* forehead *or* jaw *or* nose), then re-judge
+  — two at once is how a professional assistant becomes a mascot. Note where
+  production calibration diverges from the reference rather than silently
+  splitting the difference.
+- **Stage 3 — independent review** (checklist item 10), then the stakeholder.
+  The author does not review their own likeness; anchoring is real. Expect
+  the reviewer to find the class of error the author cannot: authored at
+  close-up, judged at close-up.
+
+### What a face module supplies
+
+A new face module supplies:
+
+1. **Static art** — the markup function: layer groups, the element table's
+   nodes, theme-keyed fills. Hand-authored or cleaned trace; budget for the
+   auto-trace failure modes in the checklist if tracing. For a line-art
+   character, build every mark with `src/line-art.js` (`taper`, `taperRing`,
+   `region` — filled variable-width marks, width profiles over normalized s);
+   the width *profiles* are per-character and stay in the face module.
+2. **A `POSE` spec** for `poseTransforms` — the named scalars (travels,
+   pivots, bob, tilt degrees), the layer list/parallax table/torso subset, and
+   `units`. Start from the rig whose construction is closest and re-derive
+   every *travel* in your own units; keep degrees as judgements about your own
+   collar/neck geometry, not conversions.
+3. **Feature blocks** — use the face-core fragments where your model matches
+   (`irisLidEyes`, `browPair`, `pairedTeeth`); write your own where the
+   character disagrees. The mouth is always yours: honour the channel
+   semantics in *Obligations* above. peep's bean-eye, point-list-brow and
+   contour-mouth generators carried into wren as copies with re-derived
+   constants — if a third line-art face repeats that, extract them into
+   parameterized factories the way the stroke engine was extracted.
+4. **`META`** — viewBox and mouthCrop.
+5. **A registry entry** — `{ create, meta }` in `src/avatar.js`.
+
+What you get for free: the mixer, visemes, emotions, gaze, idle, clips,
+interjections, the pose mechanics, the memoizer, and every host page and rig
+tool — the demos' avatar pickers, contact sheet, torso check, clip strip and
+`sweep()` all enumerate the registry. The wren run measured the split: the
+plumbing steps (2, 4, 5) are mechanical; the art (step 1) and the read of
+every state at tile size (the checklist) are where the judgement — and the
+time — actually goes. Static accessories interact with channels: wren's lens
+rings cap pupil travel, the exact channel DISTRACTED needs most — check your
+accessory against the gaze extremes early, not last.
+
+Then run the checklist above, and judge by eye — passing `sweep()` is not
+evidence a face looks right.