@voqalize/avatar 0.0.1

package/src/line-art.js

@@ -0,0 +1,111 @@
+/**
+ * line-art — the variable-width stroke engine peep was built with.
+ *
+ * The construction idiom of the Open Peeps style is that NOTHING IS A STROKE:
+ * every line is a filled outline whose width varies along its length, which is
+ * what lets a mark swell in the middle and come to a point at the ends. A
+ * uniform `stroke-width` with round caps is a rope with a blob at each end,
+ * and it is the whole difference between "vector illustration" and "someone
+ * drew this". Extracted from face-peep.js verbatim so the next line-art
+ * character starts from the kit, not from a copy of peep.
+ *
+ * A curve is a flat list of points in polybezier form — [p0, c1, c2, p1, c3,
+ * c4, p2, ...]. `widths` is a PROFILE across the whole mark, sampled at even
+ * intervals: [3, 11, 3] means thin-fat-thin whether the curve has one Bézier
+ * segment or six. Indexing per node instead is a trap — a one-segment curve
+ * has only two nodes, so a third entry is never read and the mark comes out
+ * blunt at one end.
+ */
+
+import { f } from './face-core.js';
+
+export function toSegs(flat) {
+  // Loud, because the failure is otherwise silent: a point count that is not
+  // 3n+1 simply drops the trailing points and the mark comes out short with no
+  // error anywhere.
+  if (flat.length < 4 || (flat.length - 1) % 3 !== 0) {
+    throw new Error(`curve needs 3n+1 points, got ${flat.length}`);
+  }
+  const out = [];
+  for (let i = 0; i + 3 < flat.length; i += 3) out.push(flat.slice(i, i + 4));
+  return out;
+}
+
+export const bezPt = (P, t) => {
+  const u = 1 - t;
+  return [0, 1].map(
+    (i) => u * u * u * P[0][i] + 3 * u * u * t * P[1][i] + 3 * u * t * t * P[2][i] + t * t * t * P[3][i]
+  );
+};
+export const bezTan = (P, t) => {
+  const u = 1 - t;
+  return [0, 1].map(
+    (i) => 3 * (u * u * (P[1][i] - P[0][i]) + 2 * u * t * (P[2][i] - P[1][i]) + t * t * (P[3][i] - P[2][i]))
+  );
+};
+
+export function widthAt(ws, s) {
+  const u = s * (ws.length - 1);
+  const i = Math.min(Math.floor(u), ws.length - 2);
+  return ws[i] + (ws[i + 1] - ws[i]) * (u - i);
+}
+
+/** Sample a polybezier: point, unit normal, and normalized position along it. */
+export function walk(segs, per) {
+  const out = [];
+  segs.forEach((P, i) => {
+    for (let k = i === 0 ? 0 : 1; k <= per; k++) {
+      const t = k / per;
+      const d = bezTan(P, t);
+      const L = Math.hypot(d[0], d[1]) || 1;
+      out.push({ p: bezPt(P, t), n: [-d[1] / L, d[0] / L], s: (i + t) / segs.length });
+    }
+  });
+  return out;
+}
+
+export const polyD = (pts, cmd) =>
+  pts.map(([x, y], i) => `${i ? 'L' : cmd}${f(x)} ${f(y)}`).join('');
+
+/** An open tapered mark: offset ±w/2 along the normal and close the polygon. */
+export function taper(flat, widths, per = 8) {
+  const s = walk(toSegs(flat), per);
+  const a = [], b = [];
+  for (const { p, n, s: u } of s) {
+    const h = widthAt(widths, u) / 2;
+    a.push([p[0] + n[0] * h, p[1] + n[1] * h]);
+    b.push([p[0] - n[0] * h, p[1] - n[1] * h]);
+  }
+  return polyD(a, 'M') + polyD(b.reverse(), 'L') + 'Z';
+}
+
+/**
+ * A closed tapered outline — an annulus of varying width around a contour.
+ * Two subpaths of opposite winding, so the inside is a hole under nonzero fill.
+ */
+export function taperRing(flat, widths, per = 8) {
+  const s = walk(toSegs(flat), per);
+  const a = [], b = [];
+  for (const { p, n, s: u } of s) {
+    const h = widthAt(widths, u) / 2;
+    a.push([p[0] + n[0] * h, p[1] + n[1] * h]);
+    b.push([p[0] - n[0] * h, p[1] - n[1] * h]);
+  }
+  return polyD(a, 'M') + 'Z' + polyD(b.reverse(), 'M') + 'Z';
+}
+
+/** The plain region a curve encloses — the white "background" path of a part. */
+export function region(flat) {
+  const segs = toSegs(flat);
+  let d = `M${f(segs[0][0][0])} ${f(segs[0][0][1])}`;
+  for (const P of segs) {
+    d += `C${f(P[1][0])} ${f(P[1][1])} ${f(P[2][0])} ${f(P[2][1])} ${f(P[3][0])} ${f(P[3][1])}`;
+  }
+  return d + 'Z';
+}
+
+/** Deterministic jitter, so a drawing is the same every load. */
+export function rng(seed) {
+  let s = seed >>> 0;
+  return () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
+}

package/src/params.js

@@ -0,0 +1,176 @@
+/**
+ * The rig parameter space.
+ *
+ * Everything the face can do is a point in this ~30-dimensional space. Visemes,
+ * emotions, gaze poses and gesture keyframes are all just named vectors here, so
+ * blending them is plain arithmetic rather than SVG path surgery.
+ *
+ * Sign conventions (viewer's perspective):
+ *   headYaw   +  turns toward viewer's right
+ *   headPitch +  chin down
+ *   headRoll  +  tilts toward viewer's right
+ *   pupilX    +  right,  pupilY + down
+ *   browRaise +  up,  browAngle + outer end up,  browInner + inner end up
+ *   mouthCornerL/R + up (smile)
+ */
+
+export const REST = {
+  // --- mouth -------------------------------------------------------------
+  mouthOpen: 0.02, // vertical aperture, 0..1
+  mouthWidth: 0.42, // 0 narrow .. 1 wide (0.42 is neutral)
+  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,
+  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
+
+  // --- eyes --------------------------------------------------------------
+  // A fully-open lid shows an unnatural ring of sclera; real neutral eyes sit
+  // with the upper lid already grazing the iris.
+  lidL: 0.12, // 0 wide open .. 1 fully closed
+  lidR: 0.12,
+  squintL: 0.0, // lower lid raised (smile / suspicion)
+  squintR: 0.0,
+  pupilX: 0.0,
+  pupilY: 0.05,
+
+  // --- brows -------------------------------------------------------------
+  browRaiseL: 0.0,
+  browRaiseR: 0.0,
+  browAngleL: 0.0,
+  browAngleR: 0.0,
+  browInnerL: 0.0, // inner-end lift, the "concern" muscle (AU1)
+  browInnerR: 0.0,
+
+  // --- head & body -------------------------------------------------------
+  headYaw: 0.0,
+  headPitch: 0.0,
+  headRoll: 0.0,
+  breath: 0.0, // driven by the idle layer, 0..1 through the cycle
+
+  // --- shoulders & torso -------------------------------------------------
+  // Shoulders are a floor-management channel as much as an affective one. The
+  // single most legible "I would like to come in" signal a person gives is the
+  // shoulders rising with an inbreath, and the face alone cannot say it.
+  shoulderL: 0.0, // -1 dropped .. +1 raised
+  shoulderR: 0.0,
+  // Leaning in is engagement and leaning back is withdrawal, and in a webcam
+  // frame both are read almost entirely as a change of scale.
+  torsoLean: 0.0, // -1 back .. +1 forward
+  // The trunk's own lateral axis, and the last body degree of freedom the rig
+  // was missing. Before it, everything below the collar could do was rise,
+  // fall and scale: a motion map over a 24-second listening run showed the
+  // outer edge of the body travelling exactly zero pixels. A seated person's
+  // trunk shifts sideways constantly — settling, re-settling, and lagging
+  // after a head turn — and none of that was expressible.
+  //
+  // It carries the head's turn on a much slower time constant (below), which
+  // is what buys follow-through for free: the mixer retargets it to headYaw
+  // every frame and the difference in TAU does the rest.
+  torsoTurn: 0.0, // -1 trunk toward viewer's left .. +1 right
+};
+
+// There are deliberately no arm or hand channels. The rig carried a full
+// forearm/hand chain — raise, spread, wrist rotation, splay, thumb, index — and
+// it was removed rather than fixed. Two reasons, both worth knowing before
+// anyone re-adds it. The framing is a head-and-shoulders portrait, so a hand
+// only exists at the bottom edge of the crop and every pose is a compromise
+// between "large enough to read" and "not covering the face"; and gesture is a
+// fraction of a percent of what this widget is for, against which the arm chain
+// was the single largest and most defect-prone body of geometry in the rig.
+// What the arms used to say — assent, deference, wanting the floor, apology —
+// is said by the head, brows, shoulders and torso lean instead, which is where
+// a viewer looking at a face on a video call is already looking.
+
+export const CHANNELS = Object.keys(REST);
+
+/**
+ * Channel groups. Gesture clips declare which groups they own so that, say, a
+ * nod during speech moves the head without stealing the mouth from the viseme
+ * stream.
+ */
+export const GROUPS = {
+  mouth: [
+    'mouthOpen', 'mouthWidth', 'mouthRound', 'mouthPress', 'mouthTuck',
+    'teethUpper', 'tongue', 'jaw',
+  ],
+  smile: ['mouthCornerL', 'mouthCornerR'],
+  eyes: ['lidL', 'lidR', 'squintL', 'squintR'],
+  gaze: ['pupilX', 'pupilY'],
+  brows: [
+    'browRaiseL', 'browRaiseR', 'browAngleL', 'browAngleR',
+    'browInnerL', 'browInnerR',
+  ],
+  head: ['headYaw', 'headPitch', 'headRoll'],
+  body: ['breath', 'torsoLean', 'torsoTurn'],
+  shoulders: ['shoulderL', 'shoulderR'],
+};
+
+/**
+ * Per-channel smoothing time constants, in seconds. This is where the face gets
+ * its sense of mass: the mouth snaps, the head drifts. It also does all the
+ * viseme co-articulation for free — we never blend shapes explicitly, we just
+ * retarget and let the mouth channels chase at ~40ms.
+ */
+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.smile) t[c] = 0.13;
+  t.lidL = t.lidR = 0.018; // blinks must be crisp
+  t.squintL = t.squintR = 0.12;
+  t.pupilX = t.pupilY = 0.032; // saccades are ballistic and fast
+  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
+  // 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;
+  // Nearly 3x the head's, and that ratio is the whole point rather than a
+  // taste call. The mixer feeds torsoTurn the *same* target as headYaw, so
+  // every head turn is chased by a trunk that arrives late and settles late —
+  // follow-through out of the smoothing mechanism the rig already had, with no
+  // second animation system to keep in sync. Shorten this toward the head's
+  // 0.16 and the two move as one rigid piece, which is the puppet read.
+  t.torsoTurn = 0.44;
+  return t;
+})();
+
+/**
+ * Per-channel clamp bounds, applied after the layers mix and before smoothing.
+ *
+ * The head, mouth corners and brow angles are deliberately allowed past 1: they
+ * are the channels a gesture clip adds to on top of an already-posed face, and
+ * clipping them at 1 flattens the peak of every nod fired during an emotion.
+ */
+export const RANGE = (() => {
+  const r = {};
+  for (const c of CHANNELS) r[c] = [0, 1];
+  for (const c of GROUPS.head) r[c] = [-1.4, 1.4];
+  r.mouthCornerL = r.mouthCornerR = [-1.4, 1.4];
+  r.browAngleL = r.browAngleR = [-1.4, 1.4];
+  r.browRaiseL = r.browRaiseR = [-1, 1];
+  r.browInnerL = r.browInnerR = [-1, 1];
+  r.pupilX = r.pupilY = [-1, 1];
+  r.shoulderL = r.shoulderR = [-1, 1];
+  r.torsoLean = [-1, 1];
+  r.torsoTurn = [-1, 1];
+  return r;
+})();
+
+export const clamp = (v, lo = 0, hi = 1) => (v < lo ? lo : v > hi ? hi : v);
+export const lerp = (a, b, t) => a + (b - a) * t;
+
+export function makeParams(overrides) {
+  return Object.assign({}, REST, overrides);
+}
+
+/** Frame-rate independent exponential approach toward a target. */
+export function approach(cur, target, tau, dt) {
+  if (tau <= 0) return target;
+  return cur + (target - cur) * (1 - Math.exp(-dt / tau));
+}

package/src/perform.js

@@ -0,0 +1,105 @@
+/**
+ * Perform — the composable action timeline.
+ *
+ * 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. 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.
+ *
+ * The clock discipline is VisemeTrack's (visemes.js): ride the audio clock
+ * whenever there is audio, because a gesture that drifts out of its own
+ * sentence is worse than no gesture at all, and a timer drifts the moment the
+ * 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.
+ *
+ * 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']);
+
+/**
+ * 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
+ * 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.
+ */
+export function normalizeActions(actions) {
+  const out = [];
+  for (const a of actions || []) {
+    if (!a || typeof a.t !== 'number' || !Number.isFinite(a.t)) {
+      console.warn('perform: dropped action without a time', a);
+      continue;
+    }
+    if (!VERBS.has(a.do)) {
+      console.warn(`perform: dropped unknown verb "${a && a.do}"`, a);
+      continue;
+    }
+    if ((a.do === 'interject' ? a.id : a.name) == null) {
+      console.warn(`perform: dropped ${a.do} with no ${a.do === 'interject' ? 'id' : 'name'}`, a);
+      continue;
+    }
+    out.push(a);
+  }
+  return out.sort((x, y) => x.t - y.t);
+}
+
+/**
+ * Schedules an action track against a clock. Sampled by the mixer once per
+ * frame, so firing granularity is one frame — gestures cannot tell.
+ */
+export class PerformTrack {
+  constructor() {
+    this.actions = [];
+    this.clock = null;
+    this.playing = false;
+    this._idx = 0;
+    /** @type {(a: object) => void} fired per action, in time order */
+    this.onAction = null;
+    /** Fired when the last action has fired — not when its effects finish. */
+    this.onEnd = null;
+  }
+
+  /** @param {() => number} clock elapsed ms of whatever the track rides on */
+  start(actions, clock) {
+    this.actions = normalizeActions(actions);
+    this.clock = clock;
+    this._idx = 0;
+    this.playing = true;
+    if (!this.actions.length) this._finish();
+  }
+
+  /** Cancels future actions. Does not fire onEnd: a stopped performance did
+   *  not complete, and nothing downstream should be told it did. */
+  stop() {
+    this.playing = false;
+    this.actions = [];
+    this.clock = null;
+    this._idx = 0;
+  }
+
+  update() {
+    if (!this.playing || !this.clock) return;
+    const now = this.clock();
+    while (this._idx < this.actions.length && this.actions[this._idx].t <= now) {
+      const a = this.actions[this._idx++];
+      if (this.onAction) this.onAction(a);
+    }
+    if (this._idx >= this.actions.length) this._finish();
+  }
+
+  _finish() {
+    this.playing = false;
+    if (this.onEnd) this.onEnd();
+  }
+}

package/src/visemes.js

@@ -0,0 +1,230 @@
+/**
+ * Visemes — the wire protocol between the server and the mouth.
+ *
+ * We use the Rhubarb Lip Sync alphabet (A–H, plus X for silence), which is a
+ * condensation of the Preston Blair mouth set. Nine shapes is plenty for a
+ * stylized 2D face, and it gives the server side an obvious open-source
+ * reference implementation to target.
+ *
+ *   A  closed lips          P B M   (also the resting closure)
+ *   B  slightly open,       K S T D, and consonantal EE
+ *      teeth together
+ *   C  open                 EH AE
+ *   D  wide open            AA
+ *   E  slightly rounded     AO ER
+ *   F  puckered             UW OW W
+ *   G  lip to upper teeth   F V
+ *   H  tongue up            L
+ *   X  idle / silence
+ *
+ * A cue is `{ t, v, i? }` — millisecond offset into the utterance, the letter,
+ * and an optional 0..1 intensity (loudness). Intensity is cheap for the server
+ * to derive from TTS energy and is the single biggest realism win available:
+ * the same viseme shouted and murmured should not look identical.
+ */
+
+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 },
+  B: { mouthOpen: 0.16, mouthWidth: 0.54, mouthRound: 0.05, mouthPress: 0.10, mouthTuck: 0, teethUpper: 0.75, tongue: 0.0 },
+  C: { mouthOpen: 0.45, mouthWidth: 0.58, mouthRound: 0.05, mouthPress: 0.00, mouthTuck: 0, teethUpper: 0.45, tongue: 0.0 },
+  D: { mouthOpen: 0.85, mouthWidth: 0.52, mouthRound: 0.02, mouthPress: 0.00, mouthTuck: 0, teethUpper: 0.25, tongue: 0.15 },
+  E: { mouthOpen: 0.34, mouthWidth: 0.28, mouthRound: 0.55, mouthPress: 0.00, mouthTuck: 0, teethUpper: 0.15, tongue: 0.0 },
+  F: { mouthOpen: 0.22, mouthWidth: 0.10, mouthRound: 0.95, mouthPress: 0.10, mouthTuck: 0, teethUpper: 0.00, tongue: 0.0 },
+  G: { mouthOpen: 0.20, mouthWidth: 0.46, mouthRound: 0.10, mouthPress: 0.40, mouthTuck: 1.00, teethUpper: 1.00, tongue: 0.0 },
+  H: { mouthOpen: 0.40, mouthWidth: 0.48, mouthRound: 0.05, mouthPress: 0.00, mouthTuck: 0, teethUpper: 0.35, tongue: 0.90 },
+};
+
+export const VISEME_LETTERS = Object.keys(VISEME_SHAPES);
+
+/** Resting mouth used when nothing is speaking. */
+export const SILENT = 'X';
+
+/**
+ * Scale a shape by loudness. Only the "effortful" channels scale — a quiet 'D'
+ * is a small D, not a different shape.
+ */
+export function shapeFor(letter, intensity = 1) {
+  const base = VISEME_SHAPES[letter] || VISEME_SHAPES[SILENT];
+  const rest = VISEME_SHAPES.X;
+  const k = 0.45 + 0.55 * Math.max(0, Math.min(1, intensity));
+  return {
+    mouthOpen: rest.mouthOpen + (base.mouthOpen - rest.mouthOpen) * k,
+    mouthWidth: rest.mouthWidth + (base.mouthWidth - rest.mouthWidth) * k,
+    mouthRound: base.mouthRound,
+    mouthPress: base.mouthPress,
+    mouthTuck: base.mouthTuck,
+    teethUpper: base.teethUpper * k,
+    tongue: base.tongue,
+    jaw: (rest.mouthOpen + (base.mouthOpen - rest.mouthOpen) * k) * 0.7,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 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
+ * emit noisy tracks; this makes them watchable.
+ */
+export function normalizeCues(cues) {
+  const out = [];
+  const sorted = [...cues].sort((a, b) => a.t - b.t);
+  for (const c of sorted) {
+    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) {
+      // 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 };
+      continue;
+    }
+    out.push({ t: c.t, v, i: c.i == null ? 1 : c.i });
+  }
+  return out;
+}
+
+/**
+ * Schedules a cue track against an audio 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.
+ *
+ * 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.
+ */
+export const LEAD_MS = 40;
+
+export class VisemeTrack {
+  constructor() {
+    this.cues = [];
+    this.clock = null;
+    this.playing = false;
+    this._idx = 0;
+    this.onEnd = null;
+    this.tailMs = 120; // how long past the last cue before we call it done
+  }
+
+  /** @param {() => number} clock returns elapsed ms of the audio being played */
+  start(cues, clock) {
+    this.cues = normalizeCues(cues);
+    this.clock = clock;
+    this._idx = 0;
+    this.playing = true;
+  }
+
+  /** Streaming top-up: append cues that arrive mid-utterance. */
+  push(cues) {
+    const merged = normalizeCues([...this.cues, ...cues]);
+    this.cues = merged;
+    // Re-seek rather than trusting the old index against a re-normalized array.
+    this._idx = 0;
+  }
+
+  stop() {
+    this.playing = false;
+    this.cues = [];
+    this.clock = null;
+    this._idx = 0;
+  }
+
+  /** @returns {{letter: string, intensity: number} | null} */
+  sample() {
+    if (!this.playing || !this.cues.length || !this.clock) return null;
+    const now = this.clock() + LEAD_MS;
+
+    // Cues are time-ordered and `now` is mostly monotonic, so this walk is O(1)
+    // amortized. Reset on seek-backward.
+    if (this._idx > 0 && this.cues[this._idx] && this.cues[this._idx].t > now) this._idx = 0;
+    while (this._idx + 1 < this.cues.length && this.cues[this._idx + 1].t <= now) this._idx++;
+
+    const last = this.cues[this.cues.length - 1];
+    if (now > last.t + this.tailMs && last.v === SILENT) {
+      this.playing = false;
+      if (this.onEnd) this.onEnd();
+      return null;
+    }
+
+    const cue = this.cues[this._idx];
+    if (cue.t > now) return { letter: SILENT, intensity: 1 };
+    return { letter: cue.v, intensity: cue.i == null ? 1 : cue.i };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Reference mappings for the server side
+// ---------------------------------------------------------------------------
+
+/**
+ * ARPAbet phoneme -> Rhubarb letter. This is the table to port server-side if
+ * you go the forced-alignment / G2P route (CMUdict, phonemizer, MFA).
+ */
+export const ARPABET_TO_VISEME = {
+  // closures
+  P: 'A', B: 'A', M: 'A',
+  // labiodental
+  F: 'G', V: 'G',
+  // rounded
+  W: 'F', UW: 'F', UH: 'F', OW: 'F', OY: 'F',
+  AO: 'E', ER: 'E', AXR: 'E', R: 'E',
+  // tongue-up
+  L: 'H',
+  // wide-open vowels
+  AA: 'D', AY: 'D', AW: 'D',
+  AE: 'C', AH: 'C', EH: 'C', EY: 'C', HH: 'C',
+  IH: 'B', IY: 'B', Y: 'B',
+  // alveolars / sibilants / the rest
+  T: 'B', D: 'B', S: 'B', Z: 'B', N: 'B', K: 'B', G: 'B', NG: 'B',
+  SH: 'B', ZH: 'B', CH: 'B', JH: 'B', TH: 'B', DH: 'B',
+  SIL: 'X', SP: 'X',
+};
+
+/**
+ * Azure Speech emits integer viseme IDs (0-21) on its `visemeReceived` event.
+ * This maps them straight onto our letters — the cheapest possible path to
+ * production-quality lipsync if you're already on Azure TTS.
+ */
+export const AZURE_VISEME_TO_LETTER = [
+  'X', 'C', 'D', 'E', 'C', 'E', 'B', 'F', 'F', 'D',
+  'E', 'D', 'C', 'E', 'H', 'B', 'B', 'B', 'G', 'B',
+  'B', 'A',
+];
+
+/**
+ * A crude grapheme-level guesser. NOT for production — it exists so the demo
+ * can preview arbitrary text without a TTS round-trip, and to make the shape of
+ * the mapping concrete. Real timing must come from the server.
+ */
+export function textToCues(text, { wpm = 165 } = {}) {
+  const msPerChar = 60000 / (wpm * 5.1);
+  const cues = [];
+  let t = 0;
+  const s = text.toLowerCase();
+  const push = (v, dur) => { cues.push({ t: Math.round(t), v }); t += dur; };
+
+  for (let i = 0; i < s.length; i++) {
+    const two = s.slice(i, i + 2);
+    const c = s[i];
+    if (two === 'th' || two === 'sh' || two === 'ch') { push('B', msPerChar * 1.6); i++; continue; }
+    if (two === 'oo' || two === 'ou' || two === 'ow') { push('F', msPerChar * 1.8); i++; continue; }
+    if (two === 'ee' || two === 'ea') { push('B', msPerChar * 1.7); i++; continue; }
+    if (/[pbm]/.test(c)) push('A', msPerChar * 1.1);
+    else if (/[fv]/.test(c)) push('G', msPerChar * 1.2);
+    else if (/[wu]/.test(c)) push('F', msPerChar * 1.4);
+    else if (/[or]/.test(c)) push('E', msPerChar * 1.4);
+    else if (c === 'l') push('H', msPerChar * 1.2);
+    else if (/[ai]/.test(c)) push('D', msPerChar * 1.5);
+    else if (/[e]/.test(c)) push('C', msPerChar * 1.4);
+    else if (/[a-z]/.test(c)) push('B', msPerChar);
+    else if (/[\s]/.test(c)) push('X', msPerChar * 0.9);
+    else if (/[,;:]/.test(c)) push('X', 180);
+    else if (/[.!?]/.test(c)) push('X', 320);
+  }
+  push('X', 0);
+  return cues;
+}