@voqalize/avatar 0.1.0 → 0.2.0

package/client/src/AvatarClient.ts

@@ -32,10 +32,10 @@
  *      it would eat into the intentional video-first safety margin rather than
  *      improve it. Left as a documented option, not built.
  *
- * `attach()` still subscribes to both pipecat events, but only to report a
- * **diagnostic** drift (`onSpeakingDrift`) between our anchor and pipecat's —
- * useful for noticing in logs if the two ever separate by more than jitter,
- * never used to move `t0` itself.
+ * `attach()` therefore subscribes to exactly one pipecat event,
+ * `serverMessage`. It used to also subscribe to both speaking events to report
+ * a diagnostic drift between our anchor and pipecat's; that hook is gone with
+ * the rest of the observability surface (`docs/removed.md` § Client callbacks).
  *
  * ## Cue splice
  *
@@ -72,18 +72,15 @@
 import type { PipecatClient, RTVIEvent } from "@pipecat-ai/client-js";
 import type { AvatarApi } from "../../src/avatar.js";
 import {
-  AVATAR_MESSAGE_TYPE,
   isAvatarMessage,
   type AvatarCommand,
   type AvatarCue,
   type AvatarCuesCmd,
-  type AvatarHintCmd,
-  type AvatarPerformCmd,
   type AvatarSpeechCmd,
   type AvatarStateCmd,
-  type AvatarUnknownCmd,
 } from "./types.js";
 
+
 interface Turn {
   ctx: string;
   /** The canonical, already-spliced cue track for this turn. */
@@ -91,47 +88,30 @@ interface Turn {
   /** Whether `speech start` has anchored a clock and issued the first `speak()`. */
   started: boolean;
   clock: (() => number) | null;
-  t0: number | null;
 }
 
+/**
+ * Internal. Not exported from the package — see `index.ts` for the public
+ * surface, which is `<Avatar>` and nothing else.
+ *
+ * There is deliberately no `accept` predicate here any more. Avatar commands
+ * travel in one envelope, `{type:"avatar"}`, in both directions and from every
+ * source: a `AvatarProcessor` in the pipeline and a brain driving the face
+ * out of band emit the same shape. A per-deployment predicate meant the
+ * library could not state what an avatar message *is*, which is the one thing
+ * a wire format has to be able to say. See docs/removed.md § The accept
+ * predicate.
+ */
 export interface AvatarClientOptions {
-  /** `{cmd:"hint"}` is a no-op hook today — the widget's listening engine
-   * already handles acks; a host may still want to know a hint arrived. */
-  onHint?: (kind: string, msg: AvatarHintCmd) => void;
-  /** An unrecognized `cmd` (forward compat) — the protocol says ignore
-   * silently, so this is purely an observability hook, not required. */
-  onUnknownCmd?: (msg: AvatarUnknownCmd) => void;
   /** A dispatch threw (e.g. an unknown state or interjection id, which the
    * widget throws on). Defaults to `console.warn`. */
   onError?: (err: unknown, msg: AvatarCommand) => void;
-  /** Diagnostic only (see the class doc's "Turn clock anchoring" section) —
-   * never moves the anchor, just reports how far pipecat's own
-   * botStartedSpeaking/botStoppedSpeaking landed from it. */
-  onSpeakingDrift?: (info: { event: "start" | "stop"; ctx: string | null; driftMs: number }) => void;
-  /**
-   * Which server-messages `attach()` should look inside. Defaults to the
-   * protocol's own envelope, `type === "avatar"`.
-   *
-   * The escape hatch exists because an application may tunnel avatar commands
-   * inside a message type of its own — one deployment routes them through a
-   * generic `ui_command` envelope so an LLM tool call can drive the face — and
-   * teaching this library that envelope would be teaching it one consumer's
-   * private vocabulary. Widen it here instead:
-   *
-   *     accept: (m) => m.type === "avatar" ||
-   *                    (m.type === "ui_command" && m.action === "avatar")
-   *
-   * The predicate only decides *whether to look*; the payload still has to
-   * carry a string `cmd` to dispatch at all.
-   */
-  accept?: (message: Record<string, unknown>) => boolean;
   /** Override for tests. Defaults to `performance.now`. */
   now?: () => number;
 }
 
 /**
- * The three `RTVIEvent` members `attach()` subscribes to, spelled as their
- * values.
+ * The one `RTVIEvent` member `attach()` subscribes to, spelled as its value.
  *
  * Written out rather than imported because that enum was this module's *only*
  * runtime reference to `@pipecat-ai/client-js`, and one runtime reference makes
@@ -147,8 +127,6 @@ export interface AvatarClientOptions {
  */
 export const RTVI_EVENTS = {
   serverMessage: "serverMessage",
-  botStartedSpeaking: "botStartedSpeaking",
-  botStoppedSpeaking: "botStoppedSpeaking",
 } as const satisfies Record<string, string>;
 
 /** Defensive unwrap for the `RTVIEvent.ServerMessage` `{ data }` quirk: some
@@ -163,14 +141,12 @@ export class AvatarClient {
   private readonly avatar: AvatarApi;
   private readonly opts: AvatarClientOptions;
   private readonly now: () => number;
-  private readonly accept: (message: Record<string, unknown>) => boolean;
   private turn: Turn | null = null;
 
   constructor(avatar: AvatarApi, opts: AvatarClientOptions = {}) {
     this.avatar = avatar;
     this.opts = opts;
     this.now = opts.now ?? (() => performance.now());
-    this.accept = opts.accept ?? ((m) => m.type === AVATAR_MESSAGE_TYPE);
   }
 
   /** The active turn's ctx, or `null` between turns. For tests and telemetry. */
@@ -183,41 +159,36 @@ export class AvatarClient {
     return this.turn ? [...this.turn.cues] : [];
   }
 
-  /** Dispatch one avatar command. Accepts anything with a string `cmd` — an
-   * already-unwrapped `{type:"avatar", cmd, ...}` server message, or a bare
-   * `{cmd, ...}` payload from whatever else the host is carrying them in.
-   * Unknown `cmd`s are ignored, per the wire protocol's forward-compat rule. */
+  /** Dispatch one server message. Anything that isn't in the avatar envelope
+   * is not ours and is ignored; so is an envelope carrying a `cmd` this build
+   * has never heard of, per the wire protocol's forward-compat rule. */
   dispatch(raw: unknown): void {
     if (!isAvatarMessage(raw)) return;
-    const msg = raw;
+    const msg: AvatarCommand = raw;
     try {
       switch (msg.cmd) {
         case "state":
-          this.handleState(msg as AvatarStateCmd);
+          this.handleState(msg);
           break;
         case "interject":
-          this.avatar.interject((msg as { id: string }).id);
+          this.avatar.interject(msg.id);
           break;
-        case "perform":
-          this.handlePerform(msg as AvatarPerformCmd);
+        case "gesture":
+          this.avatar.gesture(msg.id);
           break;
         case "cues":
-          this.handleCues(msg as AvatarCuesCmd);
+          this.handleCues(msg);
           break;
         case "speech":
-          this.handleSpeech(msg as AvatarSpeechCmd);
+          this.handleSpeech(msg);
           break;
         case "user":
-          this.avatar.setUserSpeaking((msg as { speaking: boolean }).speaking);
-          break;
-        case "hint": {
-          const hint = msg as AvatarHintCmd;
-          this.opts.onHint?.(hint.kind, hint);
-          break;
-        }
-        default:
-          this.opts.onUnknownCmd?.(msg as AvatarUnknownCmd);
+          this.avatar.setUserSpeaking(msg.speaking);
           break;
+        // No default: an unknown `cmd` is a newer server talking to an older
+        // widget, and the protocol's forward-compat rule says ignore it. There
+        // is no callback for it — a hook nobody could act on is observability,
+        // not an interface (`docs/removed.md` § Client callbacks).
       }
     } catch (err) {
       if (this.opts.onError) this.opts.onError(err, msg);
@@ -235,30 +206,13 @@ export class AvatarClient {
     this.avatar.setState(msg.name, { emotion: msg.emotion, gaze: msg.gaze });
   }
 
-  private handlePerform(msg: AvatarPerformCmd) {
-    this.avatar.perform(msg.actions, { clock: this.resolveClock(msg.ctx) });
-  }
-
-  /** Ride the named turn's clock if it's the one we're currently anchored to;
-   * otherwise (no active turn, or `perform` names a ctx we never saw a
-   * `speech start` for) fall back to a fresh clock anchored at this call — the
-   * same "elapsed ms since this call" default `avatar.perform()` itself uses
-   * when given no clock and no audio. */
-  private resolveClock(ctx: string | undefined): () => number {
-    if (ctx && this.turn && this.turn.ctx === ctx && this.turn.clock) {
-      return this.turn.clock;
-    }
-    const start = this.now();
-    return () => this.now() - start;
-  }
-
   private ensureTurn(ctx: string): Turn {
     if (!this.turn || this.turn.ctx !== ctx) {
       // A different ctx supersedes whatever turn we had — a stale trailing
       // message for the old ctx will find `this.turn.ctx !== ctx` in
       // handleSpeech's stop-guard and be ignored, rather than cutting off the
       // new turn.
-      this.turn = { ctx, cues: [], started: false, clock: null, t0: null };
+      this.turn = { ctx, cues: [], started: false, clock: null };
     }
     return this.turn;
   }
@@ -286,7 +240,6 @@ export class AvatarClient {
       const turn = this.ensureTurn(msg.ctx);
       const t0 = this.now();
       const clock = () => this.now() - t0;
-      turn.t0 = t0;
       turn.clock = clock;
       turn.started = true;
       this.avatar.speak({ cues: turn.cues, clock });
@@ -300,44 +253,18 @@ export class AvatarClient {
     }
   }
 
-  private reportDrift(event: "start" | "stop") {
-    if (!this.opts.onSpeakingDrift) return;
-    const t0 = this.turn?.t0;
-    if (t0 == null) return;
-    this.opts.onSpeakingDrift({ event, ctx: this.turn?.ctx ?? null, driftMs: this.now() - t0 });
-  }
-
   /**
    * Subscribe to a live `PipecatClient`'s server messages and dispatch the
-   * avatar commands among them. Which messages count is the `accept` option;
-   * by default, the protocol's own `{type:"avatar"}` envelope.
-   *
-   * Also wires the diagnostic drift cross-check described in the class doc.
+   * avatar commands among them — the ones in the protocol's own
+   * `{type:"avatar"}` envelope, which `isAvatarMessage` is the definition of.
    * Never throws on a malformed or irrelevant message.
    *
    * @returns an unsubscribe function; call it on unmount or disconnect.
    */
   attach(client: PipecatClient): () => void {
-    const onServerMessage = (raw: unknown) => {
-      const message = unwrapServerMessage(raw);
-      if (!this.accept(message)) return;
-      this.dispatch(message);
-    };
-    const onBotStartedSpeaking = () => this.reportDrift("start");
-    const onBotStoppedSpeaking = () => this.reportDrift("stop");
-
+    const onServerMessage = (raw: unknown) => this.dispatch(unwrapServerMessage(raw));
     const serverMessage = RTVI_EVENTS.serverMessage as RTVIEvent;
-    const started = RTVI_EVENTS.botStartedSpeaking as RTVIEvent;
-    const stopped = RTVI_EVENTS.botStoppedSpeaking as RTVIEvent;
-
     client.on(serverMessage, onServerMessage);
-    client.on(started, onBotStartedSpeaking);
-    client.on(stopped, onBotStoppedSpeaking);
-
-    return () => {
-      client.off(serverMessage, onServerMessage);
-      client.off(started, onBotStartedSpeaking);
-      client.off(stopped, onBotStoppedSpeaking);
-    };
+    return () => client.off(serverMessage, onServerMessage);
   }
 }

package/client/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * `@voqalize/avatar` — the avatar as one React component.
+ *
+ *     import { Avatar } from "@voqalize/avatar";
+ *
+ *     <Avatar client={pipecatClient} className="avatar-tile" />
+ *
+ * That is the whole public surface. Put an `AvatarProcessor` in the pipecat
+ * pipeline (`pip install voqalize-avatar`), drop this component into the bot's
+ * tile, and the face listens, thinks, claims the floor and lipsyncs what the
+ * TTS says.
+ *
+ * The widget underneath is framework-free, and the dispatcher between it and
+ * the RTVI data channel is plain TypeScript — but neither is exported. Two
+ * consumers wanted a call tile, both are React, and a public API is a promise
+ * we have to keep across versions. `docs/removed.md` lists what used to be
+ * here and how to get it back if a real third case argues for it.
+ *
+ * Peers: `react >= 18` and `@pipecat-ai/client-js`.
+ */
+
+export { Avatar, type AvatarProps } from "./Avatar.js";

package/client/src/types.ts

@@ -8,11 +8,11 @@
  * 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.
+ * `{ 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 — see `docs/removed.md`
+ * § The `v` field.
  */
 
 /** A viseme cue: `t` is a ms offset into the utterance's clock, `v` is a Rhubarb A–H (or X) letter. */
@@ -22,16 +22,6 @@ export interface AvatarCue {
   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;
@@ -44,10 +34,14 @@ export interface AvatarInterjectCmd {
   id: string;
 }
 
-export interface AvatarPerformCmd {
-  cmd: "perform";
-  actions: AvatarPerformAction[];
-  ctx?: string;
+/**
+ * A hand gesture — the hand at the frame edge plus its face half. Separate from
+ * `interject` on purpose: `interject("WAVE")` is the face alone and always was,
+ * so a server that upgrades gets no hand until it asks for one.
+ */
+export interface AvatarGestureCmd {
+  cmd: "gesture";
+  id: string;
 }
 
 export interface AvatarCuesCmd {
@@ -83,45 +77,28 @@ export interface AvatarUserCmd {
   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
+  | AvatarGestureCmd
   | AvatarCuesCmd
   | AvatarSpeechCmd
-  | AvatarUserCmd
-  | AvatarHintCmd
-  | AvatarUnknownCmd;
+  | AvatarUserCmd;
 
-/** The full server-message payload: the avatar envelope plus its `cmd`. */
-export type AvatarServerMessage = AvatarCommand & {
-  type?: "avatar";
-  v?: number;
-};
+/** The full server-message payload: the envelope plus its command. */
+export type AvatarServerMessage = AvatarCommand & { type: "avatar" };
 
-/** Narrows an unknown server-message payload to an avatar command. */
+/**
+ * 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* — see `docs/removed.md` § The accept predicate.
+ */
 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";
+  return m.type === AVATAR_MESSAGE_TYPE && 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

@@ -2,25 +2,21 @@
  * 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.
+ * Internal: `<Avatar>` is the only thing the package exports. It is a separate
+ * module anyway because the two lifecycles genuinely differ — mounting the
+ * widget happens once (an avatar swap remounts by design; see the note in the
+ * effect), while attaching to the pipecat client re-runs whenever the client
+ * identity changes, which a session reconnect makes it do.
  */
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { 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";
+import { createAvatar, type AvatarApi } from "../../src/avatar.js";
+import { AvatarClient } from "./AvatarClient.js";
 
-export interface UseAvatarOptions extends AvatarClientOptions {
-  /** Name from `AVATAR_NAMES`. Omit for the widget's own `DEFAULT_AVATAR`. */
+export interface UseAvatarOptions {
+  /** Which face. Omit for the widget's own default. */
   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. */
@@ -45,12 +41,6 @@ export interface UseAvatarHandle {
   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 {
@@ -58,30 +48,16 @@ export function useAvatar(options: UseAvatarOptions = {}): UseAvatarHandle {
   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.
+  // Latest-options ref, so the mount effect (which runs once) still reads the
+  // live 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;
+    const instance = createAvatar({ mount, avatar: optionsRef.current.avatar });
+    avatarClientRef.current = new AvatarClient(instance);
     setAvatar(instance);
 
     return () => {
@@ -89,10 +65,10 @@ export function useAvatar(options: UseAvatarOptions = {}): UseAvatarHandle {
       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).
+    // Mount once. `avatar` is read at mount time only — the widget has no
+    // hot-swap-avatar API (`createFace` runs once per mount), so changing it
+    // re-renders nothing here by design; a caller that needs a different face
+    // remounts with a `key` prop (see the component's doc).
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
@@ -105,9 +81,5 @@ export function useAvatar(options: UseAvatarOptions = {}): UseAvatarHandle {
     // 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 };
+  return { containerRef, avatar };
 }

package/docs/contract-avatar.md

@@ -201,6 +201,36 @@ 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.
 
+## The hand — a layer no face draws
+
+`src/hand.js` puts a hand into the bottom of the frame for `gesture(id)`
+(protocol side: [contract-protocol.md](contract-protocol.md) § Hand gestures).
+It is deliberately **not** part of this contract's parameter space: it writes a
+transform on its own `<g>` appended over the face's svg, it has no channel in
+`params.js`, and a face that never plays a gesture renders byte-for-byte what
+it rendered before. That is the whole reason it could be added at all — a hand
+channel only one avatar could draw is precisely the mistake CLAUDE.md
+constraint 9 names.
+
+**What a face owes it: a `META.viewBox`, and `theme.ink` / `theme.paper`.**
+Nothing else, and no new META field. Placement derives four numbers from the
+window itself — centre `x + w/2`, floor `y + h`, a reach scaled off `w`, and an
+outboard limit of `w/2 − 8` — and every gesture timeline is authored in wrist
+depth *below the floor* rather than absolute `y`, so the same drawing lands
+correctly on windows of different heights. peep's bottom is 876 and wren's and
+myna's is 850; all three place identically.
+
+Two framing rules are asserted, not assumed. `checkHandFraming(meta)` throws if
+any keyframe would let the wrist rise into the window (the hand must always be
+*cut* by the bottom edge, never end in a floating stump) or let the hand's
+rotated width cross the window's side (a portrait window pillarboxed in a 16:9
+tile slices anything outboard with a hard vertical line that reads as a
+rendering fault). `sweep()` runs it for every registered avatar, so a new face
+with an unusual window fails the gate rather than the eye.
+
+If a character's idiom cannot carry it, mount with `hand: false`; `gesture()`
+then plays the face half alone.
+
 ## Checklist for a new avatar
 
 1. Serve with `python3 serve.py 8777` (never `python3 -m http.server` — its
@@ -218,9 +248,12 @@ its theme keys stay overridable, but do not add a `dark` selector.
    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
+   a viseme track, plus `checkHandFraming` against your window and a pass of
+   every hand gesture. 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.
+   `[-1, 0, 1]` per channel — and look at one hand gesture at peak extension
+   (`demo/rig/body-lab.html?face=NAME&gesture=HI&at=0.4`), because figure/ground
+   between hand and shirt is a judgement the framing check cannot make.
 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.
@@ -324,7 +357,8 @@ A new face module supplies:
 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
+interjections, the frame-edge hand (§ The hand — it needs only your viewBox and
+two theme keys), 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