@voqalize/avatar 0.2.2 → 0.3.0

package/src/interjections.js

@@ -26,9 +26,13 @@ const nod = (peak, at = 0.24, rebound = 0.56) => [
   [0, 0], [at, peak], [rebound, -peak * 0.24], [1, 0],
 ];
 
-export const INTERJECTIONS = {
+// This is the authoring library. It intentionally contains exploratory clips
+// as well as production ones; only the small `ACTIONS` export below is
+// part of the public action contract.
+const CLIPS = {
   // ---------------------------------------------------------------------
-  // Pure backchannel — no words, fired automatically while LISTENING.
+  // Wordless acknowledgement clips. Every one is an explicit backend or
+  // application decision; the client never fires them from VAD or a timer.
   // ---------------------------------------------------------------------
   // The nod peaks below are pre-compensated for the head's 160ms time constant.
   // Authored at their perceptual value (~0.3) they rendered at ~0.6x and read as
@@ -44,26 +48,27 @@ export const INTERJECTIONS = {
   // drops further than the trend — and everything stays under the 1.5 Hz line
   // where sustained attention turns into impatience.
   NOD_SMALL: {
-    id: 'NOD_SMALL', label: 'nod (continuer)', text: '', duration: 800,
+    id: 'NOD_SMALL', label: 'nod (continuer)', text: '', duration: 900,
     keys: {
-      // One cycle: single-cycle nods are 42% of the corpus, and the continuer
-      // is the quietest citizen of the family — "go on", not "I agree".
-      headPitch: nod(0.55, 0.22, 0.52),
-      browRaiseL: [[0, 0], [0.3, 0.14], [1, 0]],
-      browRaiseR: [[0, 0], [0.3, 0.14], [1, 0]],
+      // One readable stroke, not an ambient bob. The peak is deliberately
+      // authored above its desired rendered travel because the common head
+      // smoothing absorbs a fast impulse before it reaches the SVG.
+      headPitch: [[0, 0], [0.25, 0.74], [0.38, 0.70], [0.68, -0.12], [1, 0]],
+      browRaiseL: [[0, 0], [0.34, 0.16], [1, 0]],
+      browRaiseR: [[0, 0], [0.34, 0.16], [1, 0]],
     },
   },
   NOD_SLOW: {
-    id: 'NOD_SLOW', label: 'nod (assessment, two-beat)', text: '', duration: 1420,
+    id: 'NOD_SLOW', label: 'nod (assessment / receipt)', text: '', duration: 1200,
     keys: {
-      // Two cycles at ~1.4 Hz. The first beat is the deepest thing any nod
-      // does (anticipatory rising) and the second sits well below it —
-      // declination plus final lowering, which is what makes the gesture
-      // resolve instead of merely stopping. The lift between beats crosses
-      // slightly above rest so the cycles read as separate strokes.
-      headPitch: [[0, 0], [0.16, 0.85], [0.38, -0.10], [0.60, 0.55], [0.85, -0.06], [1, 0]],
-      mouthCornerL: [[0, 0], [0.45, 0.12], [1, 0]],
-      mouthCornerR: [[0, 0], [0.45, 0.12], [1, 0]],
+      // A receipt needs an arrival. The former two fast peaks registered as
+      // idle bobbing at call-tile size, so this is one deep downstroke with a
+      // short dwell and a slower recovery. The tiny torso commitment keeps the
+      // head from looking like it is sliding independently of the body.
+      headPitch: [[0, 0], [0.18, 0.18], [0.39, 1.06], [0.52, 1.02], [0.78, -0.16], [1, 0]],
+      torsoLean: [[0, 0], [0.40, 0.09], [0.58, 0.07], [1, 0]],
+      browRaiseL: [[0, 0], [0.23, 0.12], [0.62, 0.08], [1, 0]],
+      browRaiseR: [[0, 0], [0.23, 0.10], [0.62, 0.07], [1, 0]],
     },
   },
   // The "ah — I see" nod. What separates it from agreement is the upswing:
@@ -88,13 +93,93 @@ export const INTERJECTIONS = {
     keys: {
       browRaiseL: [[0, 0], [0.24, 0.30], [0.7, 0.06], [1, 0]],
       browRaiseR: [[0, 0], [0.24, 0.26], [0.7, 0.06], [1, 0]],
-      headPitch: [[0, 0], [0.3, 0.08], [1, 0]],
       mouthCornerL: [[0, 0], [0.35, 0.14], [1, 0]],
       mouthCornerR: [[0, 0], [0.35, 0.14], [1, 0]],
     },
     blinkAt: [0.22],
   },
-  // The disagree family follows the same three laws as the nods (§3.4): the
+  // ---------------------------------------------------------------------
+  // Understanding beats — eye/face/body composites, deliberately separate
+  // from nods. They are the shared low-authoring-cost alternative when a
+  // portrait's pitch geometry is too limited to carry acknowledgement alone.
+  // ---------------------------------------------------------------------
+  ACK_CONTINUE: {
+    id: 'ACK_CONTINUE', label: 'acknowledge: continue', text: '', duration: 620,
+    keys: {
+      // Eyes acknowledge first; nothing here claims agreement or closes the
+      // conversational floor while the user is still talking.
+      browRaiseL: [[0, 0], [0.18, 0.14], [0.48, 0.06], [1, 0]],
+      browRaiseR: [[0, 0], [0.18, 0.12], [0.48, 0.05], [1, 0]],
+      lidL: [[0, 0], [0.20, 0.035], [0.58, 0.01], [1, 0]],
+      lidR: [[0, 0], [0.20, 0.035], [0.58, 0.01], [1, 0]],
+    },
+  },
+  ACK_RECEIVE: {
+    id: 'ACK_RECEIVE', label: 'acknowledge: received', text: '', duration: 1120,
+    keys: {
+      // Recognition → take it in → settle. The face does not nod; it lands in
+      // a quiet, held receipt, leaving room for the user to see the response.
+      browRaiseL: [[0, 0], [0.12, 0.16], [0.34, 0.055], [1, 0]],
+      browRaiseR: [[0, 0], [0.12, 0.13], [0.34, 0.045], [1, 0]],
+      lidL: [[0, 0], [0.16, 0.15], [0.49, 0.14], [0.82, 0.035], [1, 0]],
+      lidR: [[0, 0], [0.16, 0.15], [0.49, 0.14], [0.82, 0.035], [1, 0]],
+      mouthPress: [[0, 0], [0.23, 0.20], [0.60, 0.17], [1, 0]],
+      mouthCornerL: [[0, 0], [0.34, 0.08], [0.80, 0.055], [1, 0]],
+      mouthCornerR: [[0, 0], [0.34, 0.08], [0.80, 0.055], [1, 0]],
+      torsoLean: [[0, 0], [0.34, 0.13], [0.70, 0.10], [1, 0]],
+      shoulderL: [[0, 0], [0.50, 0.070], [0.76, 0.045], [1, 0]],
+      shoulderR: [[0, 0], [0.50, 0.070], [0.76, 0.045], [1, 0]],
+    },
+  },
+  ACK_REALIZE: {
+    id: 'ACK_REALIZE', label: 'acknowledge: realization', text: '', duration: 980,
+    keys: {
+      // The brows and widened lid lead: this means "the point connected", not
+      // the generic social smile which looks like agreement in a small tile.
+      browRaiseL: [[0, 0], [0.15, 0.36], [0.42, 0.20], [1, 0]],
+      browRaiseR: [[0, 0], [0.15, 0.32], [0.42, 0.18], [1, 0]],
+      lidL: [[0, 0], [0.16, -0.07], [0.48, -0.025], [1, 0]],
+      lidR: [[0, 0], [0.16, -0.07], [0.48, -0.025], [1, 0]],
+      mouthCornerL: [[0, 0], [0.35, 0.12], [0.80, 0.09], [1, 0]],
+      mouthCornerR: [[0, 0], [0.35, 0.12], [0.80, 0.09], [1, 0]],
+      torsoLean: [[0, 0], [0.38, 0.07], [0.72, 0.05], [1, 0]],
+    },
+  },
+  ACK_EMPATHIZE: {
+    id: 'ACK_EMPATHIZE', label: 'acknowledge: empathy', text: '', duration: 1180,
+    keys: {
+      // Inner brows and softened lids acknowledge the affect without signalling
+      // agreement. Keep the mouth nearly neutral for professional contexts.
+      browInnerL: [[0, 0], [0.22, 0.24], [0.68, 0.16], [1, 0]],
+      browInnerR: [[0, 0], [0.22, 0.20], [0.68, 0.13], [1, 0]],
+      browRaiseL: [[0, 0], [0.22, 0.07], [0.68, 0.05], [1, 0]],
+      browRaiseR: [[0, 0], [0.22, 0.06], [0.68, 0.04], [1, 0]],
+      lidL: [[0, 0], [0.25, 0.06], [0.72, 0.04], [1, 0]],
+      lidR: [[0, 0], [0.25, 0.06], [0.72, 0.04], [1, 0]],
+      mouthPress: [[0, 0], [0.34, 0.06], [0.72, 0.045], [1, 0]],
+      torsoLean: [[0, 0], [0.40, 0.065], [0.76, 0.045], [1, 0]],
+    },
+  },
+  // A comparison nod, not the director's default. Two quick decaying strokes
+  // with a barely-there listening tilt reflect the common conversational form
+  // the current single deep receipt does not show. It stays comparison-only:
+  // the host can decide whether this faster cadence fits its conversation.
+  ACK_NOD: {
+    id: 'ACK_NOD', label: 'acknowledge: nod', text: '', duration: 1120,
+    keys: {
+      // Values are intentionally a little theatrical at close range: at a
+      // video-call tile the head's 160 ms smoothing otherwise eats the second
+      // beat and the slight listening tilt entirely.
+      headPitch: [[0, 0], [0.12, -0.15], [0.30, 0.98], [0.46, -0.13], [0.64, 0.68], [0.82, -0.09], [1, 0]],
+      headRoll: [[0, 0], [0.18, -0.090], [0.68, -0.070], [1, 0]],
+      torsoLean: [[0, 0], [0.31, 0.115], [0.68, 0.075], [1, 0]],
+      shoulderL: [[0, 0], [0.43, 0.055], [0.73, 0.032], [1, 0]],
+      shoulderR: [[0, 0], [0.43, 0.055], [0.73, 0.032], [1, 0]],
+      lidL: [[0, 0], [0.30, 0.065], [0.64, 0.038], [1, 0]],
+      lidR: [[0, 0], [0.30, 0.065], [0.64, 0.038], [1, 0]],
+    },
+  },
+  // The disagree family follows the same three laws as explicit nods (§3.4): the
   // first swing is the biggest, every cycle decays, and the whole gesture
   // stays at or under ~1.5 Hz. Both are SERVER-SENT ONLY — an agent must
   // never disagree autonomously, so neither is in the listening engine's
@@ -211,6 +296,24 @@ export const INTERJECTIONS = {
     blinkAt: [0.1],
   },
 
+  /** Server-confirmed cut-off after playout stopped. This is not a state: the
+   * clip explains the abrupt transition, then lands in whatever factual pose
+   * Pipecat has resolved underneath it. */
+  RESPONSE_INTERRUPTED: {
+    id: 'RESPONSE_INTERRUPTED', label: 'response: interrupted', text: '', duration: 1550,
+    keys: {
+      mouthOpen: [[0, 0], [0.06, 0.36], [0.80, 0.36], [1, 0]],
+      jaw: [[0, 0], [0.08, 0.20], [0.80, 0.20], [1, 0]],
+      browRaiseL: [[0, 0], [0.12, 0.46], [0.72, 0.34], [1, 0]],
+      browRaiseR: [[0, 0], [0.12, 0.40], [0.72, 0.30], [1, 0]],
+      lidL: [[0, 0], [0.12, -0.18], [0.72, -0.12], [1, 0]],
+      lidR: [[0, 0], [0.12, -0.16], [0.72, -0.10], [1, 0]],
+      torsoLean: [[0, 0], [0.18, -0.16], [0.72, -0.10], [1, 0]],
+      shoulderL: [[0, 0], [0.18, -0.12], [0.72, -0.08], [1, 0]],
+      shoulderR: [[0, 0], [0.18, -0.12], [0.72, -0.08], [1, 0]],
+    },
+  },
+
   /**
    * "May I come in." This used to be a raised palm, and it is now the same
    * signal without one: the body claims a little space and the face asks. The
@@ -273,8 +376,8 @@ export const INTERJECTIONS = {
    * oscillation left to fill the time; a held smile past about a second stops
    * being a greeting and becomes an expression.
    */
-  WAVE: {
-    id: 'WAVE', label: 'greet (brow flash)', text: '', duration: 1300,
+  GESTURE_GREET: {
+    id: 'GESTURE_GREET', label: 'gesture: greet', text: '', duration: 1300,
     keys: {
       browRaiseL: [[0, 0], [0.11, 0.85], [0.4, 0.22], [0.75, 0.12], [1, 0]],
       browRaiseR: [[0, 0], [0.11, 0.80], [0.4, 0.20], [0.75, 0.10], [1, 0]],
@@ -304,8 +407,8 @@ export const INTERJECTIONS = {
    * Deep enough to be unmistakable: peak 0.62 against NOD_SMALL's 0.52, over
    * nearly three times the duration.
    */
-  THUMBS_UP: {
-    id: 'THUMBS_UP', label: 'approve', text: '', duration: 1500,
+  GESTURE_APPROVE: {
+    id: 'GESTURE_APPROVE', label: 'gesture: approve', text: '', duration: 1500,
     keys: {
       headPitch: [[0, 0], [0.3, 0.62], [0.58, 0.20], [0.78, 0.34], [1, 0]],
       mouthCornerL: [[0, 0], [0.36, 0.58], [0.8, 0.48], [1, 0]],
@@ -473,8 +576,8 @@ export const INTERJECTIONS = {
       torsoLean: [[0, 0], [0.25, 0.10], [0.7, 0.08], [1, 0]],
     },
   },
-  ONE_MOMENT: {
-    id: 'ONE_MOMENT', label: 'one moment', text: 'one moment', duration: 1350,
+  GESTURE_WAIT: {
+    id: 'GESTURE_WAIT', label: 'gesture: wait', text: 'one moment', duration: 1350,
     // w · ʌ · n  ·  m · oʊ · m · ə · n · t
     mouthCues: [
       { t: 0, v: 'F' }, { t: 110, v: 'C' }, { t: 210, v: 'A' }, { t: 320, v: 'F' },
@@ -557,19 +660,41 @@ export const INTERJECTIONS = {
   },
 };
 
-export const INTERJECTION_IDS = Object.keys(INTERJECTIONS);
+/** Full local authoring library. Not a server action vocabulary. */
+export const INTERNAL_CLIPS = CLIPS;
+
+/**
+ * Public, server-addressable actions. Naming is `CATEGORY_INTENT`:
+ * acknowledgements are `ACK_*`, the special transition is `RESPONSE_*`, and
+ * visible hand/body movements are `GESTURE_*`. This is deliberately an intent
+ * vocabulary — `ACK_NOD` is one implementation, not a promise about anatomy.
+ */
+export const ACTION_IDS = Object.freeze([
+  'ACK_RECEIVE', 'ACK_NOD',
+  'RESPONSE_INTERRUPTED',
+  'GESTURE_GREET', 'GESTURE_GOODBYE', 'GESTURE_APPROVE', 'GESTURE_WAIT',
+]);
 
-/** Clips that carry words, vs. wordless backchannel. */
-export const SPOKEN_IDS = INTERJECTION_IDS.filter((k) => INTERJECTIONS[k].text);
+/** Face-capable subset of the action contract. */
+export const ACTIONS = Object.freeze({
+  ...Object.fromEntries(ACTION_IDS.filter((id) => CLIPS[id]).map((id) => [id, CLIPS[id]])),
+  // The goodbye face intentionally reuses the greeting brow-flash while its
+  // hand owns the distinct, longer farewell motion. It still needs metadata so
+  // a client can enumerate every public action without knowing that detail.
+  GESTURE_GOODBYE: {
+    ...CLIPS.GESTURE_GREET,
+    id: 'GESTURE_GOODBYE', label: 'gesture: goodbye', duration: 1550,
+  },
+});
 
 /**
- * Attach audio to a clip. Call once at boot with your own TTS renders:
- *   attachAudio('OKAY', '/audio/agent-okay.mp3')
+ * Attach audio to an internal authoring clip. Production actions are silent
+ * sequences; response speech always belongs to Pipecat's audio/viseme track.
  * The baked viseme track is then scheduled against that file's clock instead of
  * the local timer, so any timing drift resolves in the audio's favour.
  */
 export function attachAudio(id, url) {
-  const clip = INTERJECTIONS[id];
+  const clip = CLIPS[id];
   if (!clip) throw new Error(`unknown interjection: ${id}`);
   const el = new Audio(url);
   el.preload = 'auto';

package/src/params.js

@@ -14,6 +14,8 @@
  *   mouthCornerL/R + up (smile)
  */
 
+import { JAW_RESPONSE_TAU_S, MOUTH_RESPONSE_TAU_S } from './speech-timing.js';
+
 export const REST = {
   // --- mouth -------------------------------------------------------------
   mouthOpen: 0.02, // vertical aperture, 0..1
@@ -21,8 +23,10 @@ export const REST = {
   mouthRound: 0.1, // pucker / lip protrusion
   mouthPress: 0.15, // lips thinned & pressed together
   mouthTuck: 0.0, // lower lip drawn under upper teeth (F/V)
-  mouthCornerL: 0.1, // -1 frown .. +1 smile
-  mouthCornerR: 0.1,
+  // Availability is not a permanent smile. Warmth and encouragement are
+  // explicit behavioral choices layered above this neutral resting shape.
+  mouthCornerL: 0.0, // -1 frown .. +1 smile
+  mouthCornerR: 0.0,
   teethUpper: 0.0, // how far the upper teeth show, 0..1
   tongue: 0.0, // tongue raised into the aperture, 0..1
   jaw: 0.0, // extra chin drop, follows mouthOpen but slower
@@ -118,7 +122,7 @@ export const GROUPS = {
 export const TAU = (() => {
   const t = {};
   for (const c of CHANNELS) t[c] = 0.09;
-  for (const c of GROUPS.mouth) t[c] = 0.042;
+  for (const c of GROUPS.mouth) t[c] = MOUTH_RESPONSE_TAU_S;
   for (const c of GROUPS.smile) t[c] = 0.13;
   t.lidL = t.lidR = 0.018; // blinks must be crisp
   t.squintL = t.squintR = 0.12;
@@ -126,7 +130,7 @@ export const TAU = (() => {
   for (const c of GROUPS.brows) t[c] = 0.08;
   for (const c of GROUPS.head) t[c] = 0.16; // the head has real mass
   t.breath = 0.25;
-  t.jaw = 0.07; // the jaw lags the lips slightly
+  t.jaw = JAW_RESPONSE_TAU_S; // the jaw lags the lips slightly
   // The torso has more mass than the head and reads wrong when it hasn't.
   t.shoulderL = t.shoulderR = 0.19;
   t.torsoLean = 0.24;

package/src/perform.js

@@ -3,7 +3,7 @@
  *
  * A performance is the server's choreography: timed verbs `{t, do, ...}` fired
  * against a clock, where every verb resolves to one of the widget's own enums —
- * states, emotions, gaze targets, interjections, hand gestures. The vocabulary is deliberately
+ * states, emotions, gaze targets, and semantic actions. The vocabulary is deliberately
  * closed: the backend sequences what the rig already does well, it cannot
  * invent motion. That constraint is what makes the wire format assemblable by
  * a dialogue manager and reviewable by a human.
@@ -14,25 +14,23 @@
  * tab is backgrounded. One deliberate difference: beat times fire *verbatim*,
  * with no LEAD_MS. Visemes lead the sound because phoneme sync is
  * frame-critical; a gesture arrives through its channels' own smoothing lag,
- * and any deliberate lead (CLAIM_FLOOR starts ~350ms before the first sample)
- * is authored into the times by the composer, not imposed here.
+ * and any deliberate lead is authored into the times by the composer, not
+ * imposed here.
  *
  * Seeking the audio backward does not re-fire earlier actions: verbs have side
  * effects, and replaying a nod is worse than missing one.
  */
 
-const VERBS = new Set(['state', 'emotion', 'gaze', 'interject', 'gesture']);
-// The verbs addressed by `id` rather than `name`. Both id verbs name a clip the
-// widget already owns; both name-verbs name an enum value.
-const ID_VERBS = new Set(['interject', 'gesture']);
+const VERBS = new Set(['state', 'emotion', 'gaze', 'action']);
+// `action` is addressed by id; the remaining verbs name an enum value.
+const ID_VERBS = new Set(['action']);
 
 /**
  * Shape hygiene for action arrays, in the spirit of normalizeCues: sort by
  * time, drop what cannot possibly fire — no finite `t`, an unknown verb, a
  * missing `name`/`id` — each with a console warning, never a throw.
  *
- * This checks *shape* only. Enum values (is "THINKING" a state? is "NOD_UP"
- * an interjection?) are checked when the verb fires, by the dispatcher in
+ * This checks *shape* only. Enum values are checked when the verb fires, by the dispatcher in
  * avatar.js — deliberately, and not just because importing the enums here
  * would be a dependency cycle: a track half-composed against a newer widget
  * should lose the verbs the widget doesn't know, not the whole performance.

package/src/rig.d.ts

@@ -0,0 +1,24 @@
+/** The mixer→rig pose model, internal to the SVG renderer; see docs/internal-rig.md. */
+export type RigChannel = string;
+export type RigPose = Readonly<Record<RigChannel, number>>;
+
+export interface HandFrame {
+  gesture: "greet" | "farewell" | "approve" | "wait";
+  progress: number;
+  side: "left" | "right";
+}
+
+export interface AvatarFrame {
+  pose: RigPose;
+  hand?: HandFrame;
+}
+
+export interface AvatarRig {
+  apply(frame: AvatarFrame): void;
+  destroy(): void;
+}
+
+export type AvatarRigFactory = (mount: HTMLElement, options?: unknown) => AvatarRig;
+
+export const HAND_GESTURE_NAMES: ReadonlyArray<HandFrame["gesture"]>;
+export function avatarFrame(pose: RigPose, hand?: HandFrame): AvatarFrame;

package/src/rig.js

@@ -0,0 +1,32 @@
+/**
+ * Renderer-agnostic frame types expressed as runtime helpers.
+ *
+ * `createSvgRig()` is a migration adapter for the existing SVG faces. It lets
+ * the mixer submit one AvatarFrame per tick today while new renderers can
+ * implement the same small `{ apply(frame), destroy() }` contract directly.
+ */
+
+export const HAND_GESTURE_NAMES = Object.freeze(['greet', 'farewell', 'approve', 'wait']);
+
+/** @param {Record<string, number>} pose @param {object|undefined} hand */
+export function avatarFrame(pose, hand) {
+  return hand ? { pose, hand } : { pose };
+}
+
+/**
+ * Adapt an existing SVG face plus its first-class hand renderer to AvatarRig.
+ * `face` and `hand` retain their own SVG-private geometry; callers only submit
+ * semantic frames.
+ */
+export function createSvgRig(face, hand = null) {
+  return {
+    apply(frame) {
+      face.apply(frame.pose);
+      if (hand && typeof hand.applyFrame === 'function') hand.applyFrame(frame.hand);
+    },
+    destroy() {
+      if (hand) hand.destroy();
+      face.destroy();
+    },
+  };
+}

package/src/speech-timing.js

@@ -0,0 +1,23 @@
+/**
+ * Timing policy for the mouth track.
+ *
+ * Keep perceptual cleanup, cue presentation, and mouth response constants
+ * named by their job. Network delivery is deliberately absent: it cannot be
+ * corrected by shifting every cue on the utterance clock.
+ */
+
+/** Cues shorter than this do not survive visual normalization. */
+export const MIN_VISIBLE_CUE_MS = 30;
+
+/** Cue timestamps render verbatim; the clock's epoch is supplied by the caller. */
+export const CUE_TRACK_LEAD_MS = 0;
+
+/** Extra time after a final silence cue before a general speech track ends. */
+export const SPEECH_TRACK_TAIL_MS = 120;
+
+/** Shorter completion tail for self-contained spoken interjection clips. */
+export const INTERJECTION_TRACK_TAIL_MS = 60;
+
+/** First-order response constants: lips settle before the jaw does. */
+export const MOUTH_RESPONSE_TAU_S = 0.042;
+export const JAW_RESPONSE_TAU_S = 0.07;

package/src/visemes.js

@@ -23,6 +23,12 @@
  * the same viseme shouted and murmured should not look identical.
  */
 
+import {
+  CUE_TRACK_LEAD_MS,
+  MIN_VISIBLE_CUE_MS,
+  SPEECH_TRACK_TAIL_MS,
+} from './speech-timing.js';
+
 export const VISEME_SHAPES = {
   X: { mouthOpen: 0.02, mouthWidth: 0.42, mouthRound: 0.10, mouthPress: 0.15, mouthTuck: 0, teethUpper: 0.00, tongue: 0.0 },
   A: { mouthOpen: 0.00, mouthWidth: 0.40, mouthRound: 0.18, mouthPress: 0.55, mouthTuck: 0, teethUpper: 0.00, tongue: 0.0 },
@@ -63,7 +69,6 @@ export function shapeFor(letter, intensity = 1) {
 // ---------------------------------------------------------------------------
 // Cue track hygiene
 // ---------------------------------------------------------------------------
-const MIN_CUE_MS = 30; // shorter than this and the mouth just flutters
 
 /**
  * Sort, merge consecutive duplicates, and drop sub-perceptual cues. Servers
@@ -76,10 +81,20 @@ export function normalizeCues(cues) {
     const v = VISEME_SHAPES[c.v] ? c.v : SILENT;
     const prev = out[out.length - 1];
     if (prev && prev.v === v) continue; // merge repeats
-    if (prev && c.t - prev.t < MIN_CUE_MS) {
+    if (prev && c.t - prev.t < MIN_VISIBLE_CUE_MS) {
       // Too short to read. Keep whichever is more visually salient: a closure
       // (A/G) carries more lip-reading information than a mid-open vowel.
-      if (v === 'A' || v === 'G') out[out.length - 1] = { ...c, v };
+      if (v === 'A' || v === 'G') {
+        // The short cue can sit between two identical closures (G → F → G).
+        // Its replacement would otherwise create a duplicate visible shape;
+        // preserving the first G is both the stable wire form and the face the
+        // viewer actually saw.
+        if (out.length > 1 && out[out.length - 2].v === v) out.pop();
+        // A winning closure replaces the preceding shape for the entire
+        // sub-perceptual interval. Preserve that cue's timestamp while taking
+        // the closure's intensity, matching the server-side wire normalizer.
+        else out[out.length - 1] = { ...c, t: prev.t, v };
+      }
       continue;
     }
     out.push({ t: c.t, v, i: c.i == null ? 1 : c.i });
@@ -88,17 +103,18 @@ export function normalizeCues(cues) {
 }
 
 /**
- * Schedules a cue track against an audio clock.
+ * Schedules a cue track against an utterance clock.
  *
- * The clock must come from the audio itself (`audioEl.currentTime * 1000` or
- * `AudioContext.currentTime`), never from wall time — wall time drifts against
- * playback and you will spend the rest of your life chasing it.
+ * An audio-owned clock (`audioEl.currentTime * 1000` or
+ * `AudioContext.currentTime`) is the strongest source when the caller owns
+ * playback. The Pipecat adapter cannot see browser device playout; it supplies
+ * elapsed time from `botStartedSpeaking`, Pipecat's output-lifecycle epoch.
  *
- * LEAD_MS biases the mouth slightly ahead of the sound. Perceptually the
- * tolerance is asymmetric: roughly -45ms (audio first) to +125ms (video first),
- * so leading is the safe side to err on.
+ * There is deliberately no renderer-wide lead. Network/media skew cannot be
+ * corrected by moving every cue, and the predicted backend leg owns its own
+ * explicit prediction cushion.
  */
-export const LEAD_MS = 40;
+export const LEAD_MS = CUE_TRACK_LEAD_MS;
 
 export class VisemeTrack {
   constructor() {
@@ -107,7 +123,7 @@ export class VisemeTrack {
     this.playing = false;
     this._idx = 0;
     this.onEnd = null;
-    this.tailMs = 120; // how long past the last cue before we call it done
+    this.tailMs = SPEECH_TRACK_TAIL_MS;
   }
 
   /** @param {() => number} clock returns elapsed ms of the audio being played */

package/client/dist/Avatar.d.ts

@@ -1,27 +0,0 @@
-/**
- * Avatar — a call-tile-ready wrapper around the widget, and the package's
- * whole public surface.
- *
- *     <Avatar client={session.client} className="avatar-tile" />
- *
- * Two props of its own; everything else is forwarded to the mount `<div>`, so
- * it sizes and styles like the tile it lives in. There is nothing to configure
- * because there is nothing the server does not already say: the
- * `AvatarProcessor` in the pipeline drives the state, the gaze and the mouth.
- *
- * The widget has no hot-swap-avatar API — `createFace` runs once per mount —
- * so `avatar` is read once, at mount. To switch faces at runtime, remount with
- * a `key` prop:
- *
- *     <Avatar key={name} avatar={name} client={session.client} />
- */
-import type { HTMLAttributes } from "react";
-import type { PipecatClient } from "@pipecat-ai/client-js";
-export interface AvatarProps extends HTMLAttributes<HTMLDivElement> {
-    /** The live `PipecatClient`, or `null` before connect. */
-    client?: PipecatClient | null;
-    /** Which face. Omit for the default. Read at mount only — see above. */
-    avatar?: string;
-}
-export declare function Avatar({ client, avatar, ...rest }: AvatarProps): import("react").JSX.Element;
-//# sourceMappingURL=Avatar.d.ts.map

package/client/dist/Avatar.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../src/Avatar.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAG3D,MAAM,WAAW,WAAY,SAAQ,cAAc,CAAC,cAAc,CAAC;IACjE,0DAA0D;IAC1D,MAAM,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;IAC9B,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,EAAE,WAAW,+BAG9D"}

package/client/dist/Avatar.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"Avatar.js","sourceRoot":"","sources":["../src/Avatar.tsx"],"names":[],"mappings":";AAoBA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAS3C,MAAM,UAAU,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,EAAe;IAC7D,MAAM,EAAE,YAAY,EAAE,GAAG,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACvD,OAAO,cAAK,IAAI,EAAC,KAAK,gBAAY,QAAQ,KAAK,IAAI,EAAE,GAAG,EAAE,YAAY,GAAI,CAAC;AAC7E,CAAC"}