@voqalize/avatar 0.2.1 → 0.3.0

package/src/canvas/src/render2d.js

@@ -0,0 +1,218 @@
+// Canvas2D renderer for the blended display list.
+//
+// Rive's own canvas runtime paints vector art with Path2D and warps textured
+// meshes separately; this does the same. Path2D objects are cached per draw and
+// only rebuilt when that draw's geometry actually moved this frame, which keeps
+// a viseme change to ~30 rebuilds out of 813 paths.
+
+const mul = (A, B) => [
+  A[0] * B[0] + A[2] * B[1],
+  A[1] * B[0] + A[3] * B[1],
+  A[0] * B[2] + A[2] * B[3],
+  A[1] * B[2] + A[3] * B[3],
+  A[0] * B[4] + A[2] * B[5] + A[4],
+  A[1] * B[4] + A[3] * B[5] + A[5],
+];
+
+const invSimilarity = ([s, , , , tx, ty]) => [1 / s, 0, 0, 1 / s, -tx / s, -ty / s];
+
+export function buildPath(cmds) {
+  const p = new Path2D();
+  for (let i = 0; i < cmds.length;) {
+    const c = cmds[i];
+    if (c === 0) { p.moveTo(cmds[i + 1], cmds[i + 2]); i += 3; }
+    else if (c === 1) { p.lineTo(cmds[i + 1], cmds[i + 2]); i += 3; }
+    else if (c === 2) { p.bezierCurveTo(cmds[i + 1], cmds[i + 2], cmds[i + 3], cmds[i + 4], cmds[i + 5], cmds[i + 6]); i += 7; }
+    else if (c === 3) { p.closePath(); i += 1; }
+    else if (c === -1) {
+      // A sub-path placed under its own matrix; Rive emits these for shapes
+      // whose contours live in a different space than the shape itself.
+      const n = cmds[i + 7];
+      const sub = buildPath(cmds.subarray(i + 8, i + 8 + n));
+      p.addPath(sub, new DOMMatrix([cmds[i + 1], cmds[i + 2], cmds[i + 3], cmds[i + 4], cmds[i + 5], cmds[i + 6]]));
+      i += 8 + n;
+    } else break;
+  }
+  return p;
+}
+
+const cssOf = (c) => `rgba(${c[0]},${c[1]},${c[2]},${c[3]})`;
+
+export class Renderer2D {
+  constructor(canvas, rig) {
+    this.canvas = canvas;
+    this.rig = rig;
+    this.ctx = canvas.getContext('2d', { alpha: true, desynchronized: true });
+    this.unalign = invSimilarity(rig.meta.align || [1, 0, 0, 1, 0, 0]);
+    this.cache = rig.out.map(() => ({ gen: -1, path: null }));
+    this.clipCache = new Map();
+    this.gradCache = new Map();
+    this.global = [1, 0, 0, 1, 0, 0];
+    // Only 11 of the 824 draws are image-backed -- the hair, brows, suit,
+    // glasses and a freckle texture. 'off' drops them so what is left is the
+    // pure vector rig; 'ghost' leaves a flat silhouette in their place so you
+    // can see the holes they would fill.
+    this.bitmaps = 'on';           // on | off | ghost
+    this.stats = { paths: 0, rebuilt: 0, tris: 0, images: 0 };
+    this.resize();
+  }
+
+  resize(dpr = window.devicePixelRatio || 1) {
+    const { clientWidth: w, clientHeight: h } = this.canvas;
+    this.canvas.width = Math.max(1, Math.round(w * dpr));
+    this.canvas.height = Math.max(1, Math.round(h * dpr));
+    const { w: aw, h: ah } = this.rig.meta.artboard;
+    const s = Math.min(this.canvas.width / aw, this.canvas.height / ah);
+    // contain + centre, then divide out the fit transform the extractor baked in
+    this.global = mul([s, 0, 0, s, (this.canvas.width - aw * s) / 2, (this.canvas.height - ah * s) / 2], this.unalign);
+    this.scale = s;
+  }
+
+  _path(d) {
+    const c = this.cache[d.i];
+    if (c.gen !== d.gen || !c.path) { c.path = buildPath(d.cmds); c.gen = d.gen; this.stats.rebuilt++; }
+    return c.path;
+  }
+
+  // Masks deform along with the body, so their Path2D is cached on the same
+  // gen counter the draws use rather than built once and kept forever.
+  _clipPath(c) {
+    let e = this.clipCache.get(c.i);
+    if (!e || e.gen !== c.gen) { e = { gen: c.gen, path: buildPath(c.c) }; this.clipCache.set(c.i, e); }
+    return e.path;
+  }
+
+  _paint(d) {
+    if (d.colour) return d.colour;
+    const p = this.rig.paints[d.paint];
+    if (p.t === 'solid') return cssOf(p.c);
+    let g = this.gradCache.get(d.paint);
+    if (!g) {
+      const ctx = this.ctx;
+      const [x0, y0, x1, y1] = p.p;
+      g = p.t === 'linear'
+        ? ctx.createLinearGradient(x0, y0, x1, y1)
+        : ctx.createRadialGradient(x0, y0, 0, x0, y0, Math.hypot(x1 - x0, y1 - y0));
+      for (const [o, c] of p.stops) g.addColorStop(Math.min(1, Math.max(0, o)), cssOf(c));
+      this.gradCache.set(d.paint, g);
+    }
+    return g;
+  }
+
+  draw() {
+    const ctx = this.ctx, rig = this.rig, G = this.global;
+    this.stats.paths = 0; this.stats.rebuilt = 0; this.stats.tris = 0; this.stats.images = 0;
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
+
+    for (const d of rig.out) {
+      if (!(d.a > 0.003)) continue;
+      const set = rig.clipsets[d.clip];
+      const clipped = set && set.length;
+      if (clipped) {
+        ctx.save();
+        for (const id of set) {
+          const c = rig.clipOut[id];
+          const m = mul(G, c.m);
+          ctx.setTransform(m[0], m[1], m[2], m[3], m[4], m[5]);
+          ctx.clip(this._clipPath(c), c.r || 'nonzero');
+        }
+      }
+      const m = mul(G, d.m);
+      ctx.setTransform(m[0], m[1], m[2], m[3], m[4], m[5]);
+      ctx.globalAlpha = d.a > 1 ? 1 : d.a;
+      ctx.globalCompositeOperation = d.blend || 'source-over';
+
+      if (d.k === 'path') {
+        this.stats.paths++;
+        const path = this._path(d);
+        if (d.stroke) {
+          ctx.strokeStyle = this._paint(d);
+          ctx.lineWidth = d.stroke.w;
+          ctx.lineCap = d.stroke.cap;
+          ctx.lineJoin = d.stroke.join;
+          ctx.stroke(path);
+        } else {
+          ctx.fillStyle = this._paint(d);
+          ctx.fill(path, d.rule || 'nonzero');
+        }
+      } else if (this.bitmaps === 'off') {
+        // nothing to draw: the image is what this slot is made of
+      } else if (this.bitmaps === 'ghost') {
+        this.stats.images++;
+        this._ghost(ctx, d);
+      } else if (d.k === 'bitmap') {
+        this.stats.images++;
+        ctx.drawImage(rig.images[d.src], 0, 0);
+      } else if (d.k === 'mesh') {
+        this.stats.images++;
+        this._mesh(ctx, d, m);
+      }
+
+      if (clipped) ctx.restore();
+    }
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.globalAlpha = 1;
+    ctx.globalCompositeOperation = 'source-over';
+  }
+
+  // The footprint an image-backed draw occupies, as a flat fill: the mesh's own
+  // triangles, or the image's rect for a plain blit. Useful for seeing exactly
+  // which parts of the character a new persona would have to supply art for.
+  _ghost(ctx, d) {
+    ctx.globalAlpha = 0.4;
+    ctx.fillStyle = '#7c5cff';
+    ctx.beginPath();
+    if (d.k === 'mesh') {
+      const V = d.verts, I = d.idx;
+      for (let t = 0; t < I.length; t += 3) {
+        const a = I[t] * 2, b = I[t + 1] * 2, c = I[t + 2] * 2;
+        ctx.moveTo(V[a], V[a + 1]); ctx.lineTo(V[b], V[b + 1]); ctx.lineTo(V[c], V[c + 1]);
+        ctx.closePath();
+      }
+    } else ctx.rect(0, 0, d.w, d.h);
+    ctx.fill();
+  }
+
+  // Deformable image mesh: for each triangle, solve the affine that carries its
+  // UV triangle onto its deformed vertex triangle, clip to the triangle, and
+  // blit the whole texture through it. Triangles are nudged outward from their
+  // centroid by half a device pixel so shared edges do not show seams.
+  _mesh(ctx, d, m) {
+    const img = this.rig.images[d.src];
+    if (!img) return;
+    const V = d.verts, U = d.uvs, I = d.idx, W = img.width, H = img.height;
+    const grow = 0.5 / (Math.hypot(m[0], m[1]) || 1);
+    for (let t = 0; t < I.length; t += 3) {
+      const i0 = I[t] * 2, i1 = I[t + 1] * 2, i2 = I[t + 2] * 2;
+      let x0 = V[i0], y0 = V[i0 + 1], x1 = V[i1], y1 = V[i1 + 1], x2 = V[i2], y2 = V[i2 + 1];
+      const s0x = U[i0] * W, s0y = U[i0 + 1] * H;
+      const s1x = U[i1] * W, s1y = U[i1 + 1] * H;
+      const s2x = U[i2] * W, s2y = U[i2 + 1] * H;
+      const det = (s1x - s0x) * (s2y - s0y) - (s2x - s0x) * (s1y - s0y);
+      if (!det) continue;
+      const a = ((x1 - x0) * (s2y - s0y) - (x2 - x0) * (s1y - s0y)) / det;
+      const c = ((x2 - x0) * (s1x - s0x) - (x1 - x0) * (s2x - s0x)) / det;
+      const b = ((y1 - y0) * (s2y - s0y) - (y2 - y0) * (s1y - s0y)) / det;
+      const dd = ((y2 - y0) * (s1x - s0x) - (y1 - y0) * (s2x - s0x)) / det;
+      const e = x0 - a * s0x - c * s0y;
+      const f = y0 - b * s0x - dd * s0y;
+
+      const cx = (x0 + x1 + x2) / 3, cy = (y0 + y1 + y2) / 3;
+      const push = (x, y) => {
+        const dx = x - cx, dy = y - cy, l = Math.hypot(dx, dy) || 1;
+        return [x + (dx / l) * grow, y + (dy / l) * grow];
+      };
+      [x0, y0] = push(x0, y0); [x1, y1] = push(x1, y1); [x2, y2] = push(x2, y2);
+
+      ctx.save();
+      ctx.beginPath();
+      ctx.moveTo(x0, y0); ctx.lineTo(x1, y1); ctx.lineTo(x2, y2); ctx.closePath();
+      ctx.clip();
+      ctx.transform(a, b, c, dd, e, f);
+      ctx.drawImage(img, 0, 0);
+      ctx.restore();
+      this.stats.tris++;
+    }
+  }
+}

package/src/canvas/src/rig.js

@@ -0,0 +1,297 @@
+// The rig: a base display list plus a library of poses stored as differences
+// from it. Blending is additive — v = base + Σ wᵢ·(poseᵢ − base) — so two
+// weights of 0.5 give a true half-way blend regardless of the order they are
+// listed in. That is the one place we deliberately differ from Rive, which
+// lerps sequentially and is therefore order-dependent.
+
+const EPS = 1e-4;
+
+// Deltas arrive keyed by draw index. Flatten them into tuple lists once, and
+// record the union of touched indices so a frame only rebuilds what moved.
+function prepare(delta) {
+  const touch = new Set();
+  const pairs = (src, cast) => {
+    if (!src) return null;
+    const out = [];
+    for (const k of Object.keys(src)) { const i = +k; touch.add(i); out.push([i, cast(src[k])]); }
+    return out.length ? out : null;
+  };
+  const F = (a) => Float32Array.from(a);
+  const id = (v) => v;
+  const p = {
+    mat: pairs(delta.mat, F),
+    geo: pairs(delta.geo, F),
+    verts: pairs(delta.verts, F),
+    alpha: pairs(delta.alpha, id),
+    paint: pairs(delta.paint, id),
+    clip: pairs(delta.clip, id),
+    src: pairs(delta.src, id),
+    hide: null,
+  };
+  if (delta.hide && delta.hide.length) {
+    p.hide = delta.hide.slice();
+    for (const i of p.hide) touch.add(i);
+  }
+  p.touch = Int32Array.from(touch);
+
+  // Masks are indexed by clip slot rather than draw index, so they need their
+  // own dirty set. A mask moving is the common case -- it rides the body -- and
+  // it must interpolate, not snap, or its edge pops while the art glides.
+  const ctouch = new Set();
+  const cpairs = (src, cast) => {
+    if (!src) return null;
+    const out = [];
+    for (const k of Object.keys(src)) { const i = +k; ctouch.add(i); out.push([i, cast(src[k])]); }
+    return out.length ? out : null;
+  };
+  p.cmat = cpairs(delta.cmat, F);
+  p.cgeo = cpairs(delta.cgeo, F);
+  p.ctouch = Int32Array.from(ctouch);
+  return p;
+}
+
+export class Rig {
+  constructor(data, images) {
+    this.data = data;
+    this.images = images;
+    this.meta = data.meta;
+    this.paints = data.paints;
+    this.clipsets = data.clipsets;   // arrays of clip-slot ids
+
+    // Live mask state, mirroring the draw list: base kept for restore, an out
+    // buffer that poses blend into, and a gen counter the renderer caches on.
+    this.clipBase = data.clipSlots.map((c) => ({
+      m: Float32Array.from(c.m), c: Float32Array.from(c.c), r: c.r,
+    }));
+    this.clipOut = this.clipBase.map((b, i) => ({
+      i, r: b.r, m: Float32Array.from(b.m), c: Float32Array.from(b.c), gen: 0,
+    }));
+    this.clipOut.forEach((o) => { o._c = o.c; });
+
+    this.base = data.draws.map((d) => ({
+      k: d.k, m: Float32Array.from(d.m), a: d.a, blend: d.blend, clip: d.clip,
+      rule: d.rule, stroke: d.stroke, paint: d.paint, src: d.src, w: d.w, h: d.h,
+      cmds: d.cmds ? Float32Array.from(d.cmds) : null,
+      verts: d.verts ? Float32Array.from(d.verts) : null,
+      uvs: d.uvs ? Float32Array.from(d.uvs) : null,
+      idx: d.idx ? Uint16Array.from(d.idx) : null,
+    }));
+
+    // Live display list. cmds/verts get their own scratch buffers so a pose
+    // that has to snap (topology change) can swap its array in and back out.
+    this.out = this.base.map((b, i) => {
+      const o = {
+        i, k: b.k, blend: b.blend, rule: b.rule, stroke: b.stroke,
+        src: b.src, w: b.w, h: b.h, uvs: b.uvs, idx: b.idx,
+        m: Float32Array.from(b.m), a: b.a, clip: b.clip, paint: b.paint,
+        colour: null,   // set when paint blending produced a plain colour
+        gen: 0,
+      };
+      o._cmds = b.cmds ? Float32Array.from(b.cmds) : null;
+      o._verts = b.verts ? Float32Array.from(b.verts) : null;
+      o.cmds = o._cmds;
+      o.verts = o._verts;
+      o._geoDirty = false;
+      return o;
+    });
+
+    this.poses = {};
+    for (const [name, d] of Object.entries(data.poses)) this.poses[name] = prepare(d);
+
+    // A sampled timeline is just an ordered set of poses; playing it is a
+    // two-weight blend between the frames either side of the cursor. Reusing
+    // the pose machinery means ambient motion costs nothing extra.
+    this.tracks = {};
+    for (const [name, t] of Object.entries(data.tracks || {})) {
+      const keys = t.frames.map((f, j) => {
+        const key = `@${name}/${j}`;
+        this.poses[key] = prepare(f);
+        return key;
+      });
+      // `at` holds each key's normalised position in the clip. Keys are placed
+      // where the motion is, so they are not evenly spaced and playback has to
+      // search rather than divide.
+      this.tracks[name] = { period: t.period, loop: t.loop, at: t.at, keys };
+    }
+
+    this.dirty = new Set();
+    this.cdirty = new Set();
+    this.frame = 0;
+    this._acc = new Map();   // draw index -> paint accumulator, reused each frame
+  }
+
+  restore(i) {
+    const o = this.out[i], b = this.base[i];
+    o.m.set(b.m);
+    o.a = b.a;
+    o.clip = b.clip;
+    o.paint = b.paint;
+    o.src = b.src;
+    o.colour = null;
+    // Only touch geometry if a pose actually moved it last frame. Ambient
+    // motion is almost pure matrix work, so this keeps the renderer's Path2D
+    // cache warm for ~800 of the 813 paths.
+    if (o._geoDirty) {
+      if (b.cmds) { o.cmds = o._cmds; o.cmds.set(b.cmds); }
+      if (b.verts) { o.verts = o._verts; o.verts.set(b.verts); }
+      o.gen = this.frame;
+      o._geoDirty = false;
+    }
+  }
+
+  restoreClip(i) {
+    const o = this.clipOut[i], b = this.clipBase[i];
+    o.m.set(b.m);
+    o.c = o._c;
+    o.c.set(b.c);
+    o.gen = this.frame;
+  }
+
+  // weights: { poseName: 0..1 }. Anything absent is zero.
+  evaluate(weights) {
+    this.frame++;
+    const out = this.out, base = this.base;
+
+    for (const i of this.dirty) this.restore(i);
+    this.dirty.clear();
+    for (const i of this.cdirty) this.restoreClip(i);
+    this.cdirty.clear();
+
+    const act = [];
+    for (const name of Object.keys(weights)) {
+      const w = weights[name];
+      if (!(w > EPS || w < -EPS)) continue;   // spline weights may go negative
+      const p = this.poses[name];
+      if (!p) continue;
+      act.push(p, w);
+      const t = p.touch;
+      for (let j = 0; j < t.length; j++) this.dirty.add(t[j]);
+      const ct = p.ctouch;
+      for (let j = 0; j < ct.length; j++) this.cdirty.add(ct[j]);
+    }
+
+    const acc = this._acc;
+    acc.clear();
+    const slot = (i) => {
+      let s = acc.get(i);
+      if (!s) { s = { paint: -1, pw: 0, clip: -1, cw: 0, geoSnap: null, gw: 0, src: -1, sw: 0 }; acc.set(i, s); }
+      return s;
+    };
+    const cacc = new Map();
+    const cslot = (i) => {
+      let s = cacc.get(i);
+      if (!s) { s = { snap: null, gw: 0 }; cacc.set(i, s); }
+      return s;
+    };
+
+    for (let a = 0; a < act.length; a += 2) {
+      const p = act[a], w = act[a + 1];
+
+      if (p.mat) for (const [i, v] of p.mat) {
+        const o = out[i].m, b = base[i].m;
+        for (let j = 0; j < 6; j++) o[j] += w * (v[j] - b[j]);
+      }
+
+      if (p.geo) for (const [i, v] of p.geo) {
+        const d = out[i], b = base[i].cmds;
+        d.gen = this.frame; d._geoDirty = true;
+        if (v.length !== b.length) {
+          // Topology changed, so there is nothing to interpolate between.
+          // Snap to whichever competing pose is pulling hardest.
+          const s = slot(i);
+          if (w > s.gw) { s.gw = w; s.geoSnap = v; }
+        } else {
+          const o = d.cmds === d._cmds ? d.cmds : d._cmds;
+          for (let j = 0; j < v.length; j++) o[j] += w * (v[j] - b[j]);
+        }
+      }
+
+      if (p.verts) for (const [i, v] of p.verts) {
+        const d = out[i], b = base[i].verts, o = d.verts;
+        d.gen = this.frame; d._geoDirty = true;
+        for (let j = 0; j < v.length; j++) o[j] += w * (v[j] - b[j]);
+      }
+
+      if (p.alpha) for (const [i, v] of p.alpha) out[i].a += w * (v - base[i].a);
+      if (p.hide) for (const i of p.hide) out[i].a += w * (0 - base[i].a);
+
+      if (p.paint) for (const [i, v] of p.paint) {
+        const s = slot(i);
+        s.list = s.list || [];
+        s.list.push(v, w);
+      }
+      if (p.clip) for (const [i, v] of p.clip) {
+        const s = slot(i);
+        if (w > s.cw) { s.cw = w; s.clip = v; }
+      }
+      if (p.cmat) for (const [i, v] of p.cmat) {
+        const o = this.clipOut[i].m, b = this.clipBase[i].m;
+        for (let j = 0; j < 6; j++) o[j] += w * (v[j] - b[j]);
+        this.clipOut[i].gen = this.frame;
+      }
+
+      if (p.cgeo) for (const [i, v] of p.cgeo) {
+        const d = this.clipOut[i], b = this.clipBase[i].c;
+        d.gen = this.frame;
+        if (v.length !== b.length) {
+          const s = cslot(i);
+          if (w > s.gw) { s.gw = w; s.snap = v; }
+        } else {
+          const o = d.c === d._c ? d.c : d._c;
+          for (let j = 0; j < v.length; j++) o[j] += w * (v[j] - b[j]);
+        }
+      }
+
+      // A texture swap has no midpoint, so it flips with the dominant pose.
+      if (p.src) for (const [i, v] of p.src) {
+        const s = slot(i);
+        if (w > s.sw) { s.sw = w; s.src = v; }
+      }
+    }
+
+    for (const [i, s] of cacc) if (s.snap && s.gw > 0.5) this.clipOut[i].c = s.snap;
+
+    for (const [i, s] of acc) {
+      const d = out[i];
+      if (s.geoSnap && s.gw > 0.5) d.cmds = s.geoSnap;
+      if (s.clip >= 0 && s.cw > 0.5) d.clip = s.clip;
+      if (s.src >= 0 && s.sw > 0.5) d.src = s.src;
+      if (s.list) this._resolvePaint(d, base[i].paint, s.list);
+    }
+
+    return out;
+  }
+
+  // Solid-to-solid paint changes blend in RGBA, which is what the eye-hue
+  // ladder and the viseme lip tints need. Anything involving a gradient has no
+  // meaningful midpoint, so it snaps at the halfway mark instead.
+  _resolvePaint(d, basePaint, list) {
+    const P = this.paints;
+    const b = P[basePaint];
+    let allSolid = b.t === 'solid';
+    let best = -1, bw = 0;
+    for (let j = 0; j < list.length; j += 2) {
+      if (P[list[j]].t !== 'solid') allSolid = false;
+      if (list[j + 1] > bw) { bw = list[j + 1]; best = list[j]; }
+    }
+    if (!allSolid) { if (bw > 0.5) { d.paint = best; d.colour = null; } return; }
+    const c = [b.c[0], b.c[1], b.c[2], b.c[3]];
+    for (let j = 0; j < list.length; j += 2) {
+      const v = P[list[j]].c, w = list[j + 1];
+      for (let k = 0; k < 4; k++) c[k] += w * (v[k] - b.c[k]);
+    }
+    const q = (v) => (v < 0 ? 0 : v > 255 ? 255 : Math.round(v));
+    d.paint = basePaint;
+    d.colour = `rgba(${q(c[0])},${q(c[1])},${q(c[2])},${Math.min(1, Math.max(0, c[3])).toFixed(3)})`;
+  }
+}
+
+export async function loadRig(url) {
+  const base = new URL(url, location.href);
+  const data = await (await fetch(base)).json();
+  const images = await Promise.all(data.images.map(async (im) => {
+    const r = await fetch(new URL('img/' + im.file, base));
+    return createImageBitmap(await r.blob());
+  }));
+  return new Rig(data, images);
+}

package/src/canvas/src/vocab.js

@@ -0,0 +1,96 @@
+// The driver's pose vocabulary, as data.
+//
+// `drivers.js` emits { poseName: weight } maps and nothing else; a name it asks
+// for that the rig does not have is silently dropped by `rig.js`, so a typo
+// shows up as a feature that simply never animates. That failure mode is why
+// this file exists: the driver builds its names from these lists, and the
+// authoring-side checker (`author/validate.mjs`) validates against the same
+// lists. One source, so the two cannot drift.
+//
+// 73 required pose names + 3 optional `wardrobe/*` + 9 optional `rhubarb/*`
+// + 4 optional `gaze/*`, and 6 track names.
+
+export const VISEMES = [
+  'viseme/100 - silence', 'viseme/101 - A,AI', 'viseme/102 - a', 'viseme/103 - ae',
+  'viseme/104 - O', 'viseme/105 - i', 'viseme/107 - p,b,m', 'viseme/108 - L',
+  'viseme/109 - v,f', 'viseme/110 - U', 'viseme/112 - o', 'viseme/113 - s,z',
+  'viseme/114 - ol', 'viseme/115 - sh,tsh,zh, dzh', 'viseme/116 - th', 'viseme/118 - kgn',
+];
+
+// The six eye states the expression x blink cross-fade can reach.
+export const eyePose = (n) => `eye/eyes-${n}`;
+export const EYE_STATES = ['idle_closed', 'idle_wide', 'happy', 'happy_closed', 'sad', 'sad_closed'];
+export const EYE_POSES = EYE_STATES.map(eyePose);
+
+// Six feature axes, each with a +100 and a -100 extreme.
+export const MORPH_AXES = ['head', 'lips', 'nose', 'brows', 'eyes', 'distance'];
+export const MORPH_POSES = MORPH_AXES.flatMap((a) => [`morph/${a}_100`, `morph/${a}_-100`]);
+
+// The iris hue ladder: 37 steps of 10 degrees, zero-padded to three digits.
+// The driver holds one or two neighbouring rungs and the runtime crossfades
+// them solid-to-solid in RGBA.
+export const hueKey = (n) => `hue/${String(n).padStart(3, '0')}`;
+export const HUE_STEP = 10;
+export const HUE_LADDER = Array.from({ length: 360 / HUE_STEP + 1 }, (_, i) => hueKey(i * HUE_STEP));
+
+// Two overlays on top of whatever hue is showing. They pull in opposite
+// directions: saturation-0 drains colour, brightness-0 lifts a black overlay.
+export const IRIS_SATURATION = 'iris/eyes-saturation-0';
+export const IRIS_BRIGHTNESS = 'iris/eyes-brightness-0';
+export const IRIS_POSES = [IRIS_SATURATION, IRIS_BRIGHTNESS];
+
+// Optional by design: these three only fire when state.hair / suit / glassesOff
+// are raised, and they exist for the bitmap-backed mascot. A hand-authored
+// vector avatar that covers 73 of 76 names is complete, not incomplete.
+export const WARDROBE_HAIR = 'wardrobe/hair-blonde';
+export const WARDROBE_SUIT = 'wardrobe/suit-black';
+export const WARDROBE_GLASSES = 'wardrobe/glasses-off';
+export const WARDROBE_POSES = [WARDROBE_HAIR, WARDROBE_SUIT, WARDROBE_GLASSES];
+
+// Optional the same way: GAZE. The four names are the extremes of the driver's
+// `pupilX`/`pupilY` channels (-1..1, + x = the viewer's right, + y = down), so
+// a mixer reaches an arbitrary gaze by holding ONE of each pair at |channel|
+// and the two axes compose. They are named for what a VIEWER sees, not for
+// whose left it is.
+//
+// Optional because an eye that cannot look anywhere but forward is still a
+// complete face — ink and facet do not implement these and are not incomplete
+// — and because a rig that does implement them costs four poses to say so.
+export const GAZE_DIRS = ['left', 'right', 'up', 'down'];
+export const GAZE_POSES = GAZE_DIRS.map((d) => `gaze/${d}`);
+
+// The driver's boot state, as data — and the only three numbers in it that any
+// AUTHORING-time code has to know. `drivers.js` sets these three on
+// `this.state` (drivers.js:34-36); it deliberately does NOT import them, so
+// this list is a mirror and has to be kept in step by hand.
+//
+// They are here because they are load-bearing on the far side of the pipeline:
+// the base iris paint in a rig file is solved backwards from where these
+// defaults should land (see `author/rig.mjs` solveIrisBase), so changing one of
+// them silently changes the colour of every avatar's eyes.
+export const DRIVER_DEFAULTS = { hue: 200, saturation: 0.15, brightness: 0.5 };
+
+// Tracks, not poses. `breathing` and `subtle` run forever under the ambient
+// amplitude; the four idle one-shots are shuffled, so every one of them must
+// start and end on the exact rest pose.
+export const AMBIENT_TRACKS = ['breathing', 'subtle'];
+export const IDLE_CLIPS = ['idle 1', 'idle 2', 'idle 3', 'idle 4'];
+export const TRACKS = [...AMBIENT_TRACKS, ...IDLE_CLIPS];
+
+// --- mouth part: the Rhubarb letters ---------------------------------------
+// The nine-letter Rhubarb alphabet (A–H plus X for silence), which is the
+// alphabet voqalize's lip-sync speaks and the condensation of the Preston Blair
+// set that every open-source aligner already targets. A rig gets these when its
+// mouth is `author/parts/mouth.mjs` — they are baked straight from that
+// contract's own `VISEME_SHAPES` (author/parts/mouth-tables.mjs) with no
+// hand-tuning, so they are a PROOF that the channel mapping lands on the right
+// nine shapes as much as they are a vocabulary.
+//
+// OPTIONAL, and they stay optional: `ink` and `facet` still hold their mouths
+// inline against the pre-channel keys and have no way to bake them, and the
+// 16-code mascot set above remains the required one for every rig.
+export const RHUBARB_LETTERS = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'X'];
+export const RHUBARB_POSES = RHUBARB_LETTERS.map((l) => 'rhubarb/' + l);
+
+export const REQUIRED_POSES = [...VISEMES, ...EYE_POSES, ...MORPH_POSES, ...HUE_LADDER, ...IRIS_POSES];
+export const OPTIONAL_POSES = [...WARDROBE_POSES, ...RHUBARB_POSES, ...GAZE_POSES];

package/src/clips.js

@@ -6,12 +6,14 @@
  * is already doing, which is what makes "nod while speaking" work without any
  * special-casing.
  *
- * Two behaviours matter more here than the curves themselves:
- *   · clips are interruptible (barge-in must kill an in-flight nod), and
- *   · the queue collapses duplicates — three stacked nods reads as a fault.
+ * A server action is a physical movement, not an abstract state transition.
+ * Queued actions finish their landing before the next action begins; their
+ * underlying state may change freely while that happens. `stop()` remains for
+ * real speech taking mouth ownership.
  */
 
 import { clamp } from './params.js';
+import { INTERJECTION_TRACK_TAIL_MS } from './speech-timing.js';
 import { VisemeTrack } from './visemes.js';
 
 const smoothstep = (t) => t * t * (3 - 2 * t);
@@ -50,6 +52,7 @@ export class ClipPlayer {
     this.mouth = new VisemeTrack();
     this._blinksDone = 0;
     this.onEnd = null;
+    this.queue = [];
   }
 
   get playing() { return !!this.clip; }
@@ -60,11 +63,17 @@ export class ClipPlayer {
    * @param {HTMLAudioElement} [audio] if given, the clip's mouth track is
    *        scheduled against the audio clock instead of the local timer
    */
-  play(clip, audio) {
+  play(clip, audio, { queue = false } = {}) {
     if (!clip) return;
-    // Collapse a repeat of the clip already running.
-    if (this.clip && this.clip.id === clip.id && !this.fading) return;
+    if (this.clip && queue) {
+      if (this.clip.id === clip.id || this.queue.some((item) => item.clip.id === clip.id)) return;
+      this.queue.push({ clip, audio });
+      return;
+    }
+    this._start(clip, audio);
+  }
 
+  _start(clip, audio) {
     this.clip = clip;
     this.t = 0;
     this.fading = false;
@@ -76,7 +85,7 @@ export class ClipPlayer {
       const clock = audio
         ? () => audio.currentTime * 1000
         : () => this.t;
-      this.mouth.tailMs = 60;
+      this.mouth.tailMs = INTERJECTION_TRACK_TAIL_MS;
       this.mouth.start(clip.mouthCues, clock);
     } else {
       this.mouth.stop();
@@ -101,6 +110,8 @@ export class ClipPlayer {
     if (this.audio) { this.audio.pause(); this.audio = null; }
     if (had && had.gaze && this.hooks.onGaze) this.hooks.onGaze(null);
     if (this.onEnd) this.onEnd(had);
+    const next = this.queue.shift();
+    if (next) this._start(next.clip, next.audio);
   }
 
   /**