@voqalize/avatar 0.4.1 → 0.4.2

package/src/idle.js

@@ -54,7 +54,13 @@ import { HeadPose } from './head.js';
  */
 export const DEFAULT_PROFILE = {
   sway: 1.0,
-  settle: [1.8, 4.6],
+  // A head re-positions oftener than it used to (2026-09-21). On a character
+  // whose held angle is budgeted this is the half of "more movement" that
+  // actually arrives: the angle is capped by `headHold` and the *rate* is not,
+  // so a body that re-settles every couple of seconds reads as more alive than
+  // one that reaches further every five. Still an event every second or two at
+  // its fastest, which is nowhere near the 1.5 Hz line.
+  settle: [1.4, 3.4],
   blinkGap: [1.9, 5.4],
   slowBlink: 0,
   breathRate: 1.0,
@@ -62,7 +68,7 @@ export const DEFAULT_PROFILE = {
   hold: null,
   rhythm: null,
   flick: null,
-  shift: [9, 22],
+  shift: [7, 16],
 };
 
 const rand = ([a, b]) => a + Math.random() * (b - a);
@@ -120,7 +126,7 @@ function nextPosture(prev) {
   // a mechanism that is invisible half the time reads as a body that only
   // moves sometimes. Nobody shifts their weight by a millimetre. The 25% that
   // stays on the same side is what keeps it off a left-right metronome.
-  const mag = 0.16 + Math.random() * 0.26;
+  const mag = 0.20 + Math.random() * 0.32;
   const away = prev.torsoTurn > 0 ? -1 : prev.torsoTurn < 0 ? 1 : (Math.random() < 0.5 ? -1 : 1);
   const turn = mag * (Math.random() < 0.75 ? away : -away);
   const leanAway = prev.torsoLean > 0 ? -1 : 1;
@@ -158,11 +164,24 @@ function nextPosture(prev) {
  * and not a small number, is what keeps pitch off the wire's vocabulary. It was
  * held to under a degree as well, which measured as a listening head with no
  * pitch in it at all (1.05° peak over thirty seconds, against yaw's 5.5°), and
- * a head that only ever turns is a head on a turntable. The range is wider now
- * and still biased upward: a chin that drifts down and stays there is the
- * downcast read, which on a photographed face arrives long before any other.
+ * a head that only ever turns is a head on a turntable. The range is biased
+ * upward: a chin that drifts down and stays there is the downcast read, which
+ * on a photographed face arrives long before any other.
+ *
+ * **Widened again on 2026-09-21, on the owner's read that the whole figure is
+ * too restricted.** The ceiling here is not this table — it is `headHold` in
+ * the mixer (step 6b), which softens what the layers together ask the head to
+ * *hold* against the angle the owner measured on each character by eye
+ * (`motion-limits.json`). So these numbers are what the drawing gets and what a
+ * budgeted character gets is its own measured angle, which is the arrangement
+ * this file should have been sized against all along: on tara the widest settle
+ * yaw is 4.9° under a 6° hold budget, the widest pitch 2.6° under 5°, and roll
+ * stays the most conservative of the three because her roll *transition* is a
+ * recorded defect at any angle. The `dur` is untouched — a wider move over the
+ * same half second is a faster move, not a busier one, and the frequency is
+ * what the movement budget is about (CLAUDE.md).
  */
-const SETTLE = { yaw: [0.16, 0.34], pitch: [-0.11, 0.08], roll: [0.10, 0.28], dur: [0.45, 0.8], switchP: 0.7 };
+const SETTLE = { yaw: [0.22, 0.46], pitch: [-0.15, 0.11], roll: [0.14, 0.38], dur: [0.45, 0.8], switchP: 0.7 };
 const HOME = { headYaw: 0, headPitch: 0, headRoll: 0 };
 
 /**
@@ -186,7 +205,7 @@ const HOME = { headYaw: 0, headPitch: 0, headRoll: 0 };
  * same gate, so a quiet head does not sit on a torso still rocking under it.
  */
 const LIVE = {
-  yaw: 0.05, pitch: 0.02, roll: 0.05, breathPitch: 0.006,
+  yaw: 0.07, pitch: 0.028, roll: 0.07, breathPitch: 0.006,
   retarget: [0.6, 2.2], tau: 0.38,
   drift: [2.0, 5.0], still: [1.2, 3.5], stillGain: 0.12,
 };
@@ -208,7 +227,6 @@ export class IdleLayer {
     this._nextBlink = 2 + Math.random() * 3;
     this._blinkT = -1;
     this._blinkDur = 0.13;
-    this._double = false;
     this._lastBlinkAt = -Infinity;
     // Two incommensurate frequencies per axis so the sway never visibly loops.
     this._ph = [Math.random() * 9, Math.random() * 9, Math.random() * 9];
@@ -294,19 +312,18 @@ export class IdleLayer {
    * rate is a decision to revisit in that state, not something for the eyelids
    * to drop silently.
    */
-  blink(double = false, evoked = false, forced = false) {
+  blink(evoked = false, forced = false) {
     if (evoked) {
       if (this.t - this._lastBlinkAt < BLINK_REFRACTORY) return;
       const gap = this._nextBlink - this._lastBlinkAt;
       if (!forced && this.t - this._lastBlinkAt < EVOKED_EARLIEST * gap) return;
     }
-    this._startBlink(0.11 + Math.random() * 0.04, double);
+    this._startBlink(0.11 + Math.random() * 0.04);
   }
 
-  _startBlink(dur, double) {
+  _startBlink(dur) {
     if (this._blinkT >= 0) return;
     this._blinkT = 0;
-    this._double = double;
     this._blinkDur = dur;
     this._lastBlinkAt = this.t;
     this._nextBlink = this.t + rand(this.profile.blinkGap);
@@ -319,12 +336,12 @@ export class IdleLayer {
    * of speech with no pauses in it.
    */
   phraseBlink() {
-    this.blink(false, true);
+    this.blink(true);
   }
 
   /** A slow, deliberate blink — reads as thinking or fatigue. */
   slowBlink() {
-    this._startBlink(0.34, false);
+    this._startBlink(0.34);
   }
 
   _blinkValue(dt) {
@@ -333,7 +350,6 @@ export class IdleLayer {
     const d = this._blinkDur;
     const p = this._blinkT / d;
     if (p >= 1) {
-      if (this._double) { this._double = false; this._blinkT = 0; return 0; }
       this._blinkT = -1;
       return 0;
     }
@@ -351,10 +367,15 @@ export class IdleLayer {
       // Re-armed here as well as in _startBlink, for the frame the timer comes
       // due in the middle of a blink already running.
       this._nextBlink = t + rand(pr.blinkGap);
-      // A share of them slow if the state asks for it; roughly one in six of
-      // the rest comes in a pair.
+      // A share of them slow if the state asks for it. **The rest are single,
+      // and a paired blink is not a thing this layer does** — a share of them
+      // used to re-close the instant the lid reached open, which at this
+      // duration is a 7-9 Hz flutter and was read by the owner on 2026-09-21 as
+      // a dropped frame rather than as a pair. A human doublet is two blinks a
+      // few hundred ms apart, which is what the gap already produces when it
+      // draws short; nothing in research-biomechanics.md asks for the rest.
       if (Math.random() < pr.slowBlink) this.slowBlink();
-      else this.blink(Math.random() < 0.16);
+      else this.blink();
     }
     const blink = this._blinkValue(dt);
 
@@ -524,6 +545,12 @@ export class IdleLayer {
         // actually present on screen. `gain` is where a deployment that
         // really is paying for the pixels turns it back down.
         // The head is the exception: it settles rather than sways (SETTLE).
+        // The *idle* terms below went up again on 2026-09-21 — the owner read
+        // the figure as too restricted — and only the idle terms: the speech
+        // share is `prosody.js`'s business and is raised there, beside the
+        // words it is timed to. These are all far below 1.5 Hz, so the raise
+        // buys excursion and not rate; what it costs the encoder is a slightly
+        // larger slow motion, which is the cheap kind.
         headYaw: hs.headYaw + flickYaw + post.headYaw * ps,
         headPitch: hs.headPitch + workPitch,
         headRoll: hs.headRoll + post.headRoll * ps,
@@ -531,9 +558,16 @@ export class IdleLayer {
         // outbreath over the phrase (research-biomechanics.md §6.1), which the
         // prosody layer draws. Quiet breathing steps mostly back under it.
         breath: breath * this.gain * (1 - 0.6 * this.talk),
-        // The brows are never quite still either.
-        browRaiseL: s(0, 0.089) * 0.020 * a,
-        browRaiseR: s(1, 0.083) * 0.020 * a,
+        // The brows are never quite still either — and they were nearly still
+        // here, at an amplitude a beat could swallow whole. Two video
+        // reviewers named a motionless upper face as the biggest reason these
+        // read as uncanny; `prosody.POSE.brow` answered that for a face that
+        // is *talking*, and the avatar listens far more than it speaks
+        // (CLAUDE.md). The two rates are further apart than they were so the
+        // pair drifts out of phase inside one call rather than over several:
+        // a matched pair is the drawing, not the face.
+        browRaiseL: s(0, 0.089) * 0.032 * a,
+        browRaiseR: s(1, 0.071) * 0.032 * a,
         // Shoulders, and the body's share of speech emphasis — a head that
         // moves on its own above a torso that never does is the head-on-a-stick
         // read, and it was the loudest note in the first round of stakeholder
@@ -559,15 +593,15 @@ export class IdleLayer {
         // said should be the louder. What is left here is the part prosody
         // cannot supply: motion in the gaps *between* phrases, where there is
         // no accent to hang anything on.
-        shoulderL: (s(1, 0.11) * 0.5 + s(2, 0.22) * 0.5) * (0.040 * ad + 0.045 * say * this.gain)
+        shoulderL: (s(1, 0.11) * 0.5 + s(2, 0.22) * 0.5) * (0.052 * ad + 0.045 * say * this.gain)
           + workL + post.shoulderL * ps,
-        shoulderR: (s(2, 0.10) * 0.5 + s(0, 0.19) * 0.5) * (0.040 * ad + 0.045 * say * this.gain)
+        shoulderR: (s(2, 0.10) * 0.5 + s(0, 0.19) * 0.5) * (0.052 * ad + 0.045 * say * this.gain)
           + workR + post.shoulderR * ps,
-        torsoLean: s(0, 0.085) * (0.028 * ad + 0.035 * say * this.gain) + post.torsoLean * ps,
+        torsoLean: s(0, 0.085) * (0.036 * ad + 0.035 * say * this.gain) + post.torsoLean * ps,
         // The trunk's own drift, small next to the weight shift that dominates
         // this channel. It exists so the body is not perfectly still *between*
         // shifts, which would make each shift read as a discrete event.
-        torsoTurn: (s(2, 0.047) * 0.6 + s(1, 0.031) * 0.4) * 0.06 * a
+        torsoTurn: (s(2, 0.047) * 0.6 + s(1, 0.031) * 0.4) * 0.075 * a
           + post.torsoTurn * ps,
       },
     };

package/src/prosody.js

@@ -83,10 +83,36 @@ const BLINK_FRESH_MS = 150;
 // wobble about the same one. Yaw is the narrowest in degrees because it is the
 // axis a projected photograph survives least; pitch leans slightly chin-up,
 // which is where a person talking to someone holds their head.
+// **Every axis went up on 2026-09-21, and it is paying for something
+// specific.** The speaking face used to get much of its movement from a gaze
+// aversion — a look away that took the neck with it — and that is gone
+// (gaze.js): the eyes now hold the user for the whole turn. Taking it out and
+// changing nothing else left the speaking head measurably *stiller* than
+// before, which is the defect the aversion had been introduced to fix. So the
+// movement comes back as the pose the head holds per phrase, which is what a
+// speaker's head actually does and is communicative rather than evasive.
+//
+// Sized against `presence.test.ts`, which renders a turn through the real
+// mixer and prints the degrees. On tara the widest yaw here is ~4.9° and the
+// widest chin-up ~4.4°, inside the 6° and 5° she was measured at for a *held*
+// pose; what the same table showed before the raise was a speaking head
+// reaching 4.2° of yaw and 2.1° of pitch, the second of which is under half of
+// what the aversion had been supplying. `headHold` softens the sum in any
+// case, so a character measured tighter than tara gets her own angle here for
+// free.
 const POSE = {
-  headYaw: [0.12, 0.34],
-  headPitch: [-0.20, 0.14],
-  headRoll: [0.10, 0.30],
+  headYaw: [0.15, 0.44],
+  // **Pitch widens downward only, and the chin-up end is pinned where it was.**
+  // Opening it to -0.26 with the rest measured as a speaking face reading
+  // *sleepy*: the lids follow the globe, and on a rig with a reflex a chin-up
+  // head means eyes rolled down to hold the user, which narrows the aperture
+  // for real. The audit's open-lid median went 0.149 -> 0.163 against a 0.15
+  // ceiling (research-perception.md § 6) on that change alone. So the chin-up
+  // end stays at the -0.20 it was measured safe at, and the extra travel comes
+  // off the other end, where the reflex rolls the eyes *up* and the lid opens.
+  // A phrase pose returns, so this is not the chin-drift that reads downcast.
+  headPitch: [-0.20, 0.22],
+  headRoll: [0.12, 0.34],
   // The mouth corners take a small share of each pose: a speaking mouth whose
   // corners never move reads as dubbed. They ease rather than move, since a
   // corner that jumps reads as a twitch.
@@ -195,16 +221,32 @@ const BEAT = {
   // been held a while, so a phrase does not change position twice in a breath.
   // Of the rest most are a nod and some leave the head alone: a beat on every
   // accent is a metronome, and the brows still carry it.
-  swingP: 0.3,
-  swingAfterMs: 1800,
+  //
+  // **Raised on 2026-09-21, and this is where the speaking head's motion went.**
+  // Deleting the speaking aversion (gaze.js) took its head share with it, and
+  // that share had been most of what moved the head *inside* a sentence: the
+  // per-sentence deviation fell from 0.79 deg of yaw to 0.55 measured on the
+  // audit's real cue track, because a held phrase pose contributes nothing to a
+  // deviation taken about that phrase's own mean. The swing is the honest way
+  // to put it back — it is a move to a new pose rather than a look away from
+  // the user, which is the whole distinction the removal was about, and Graf
+  // has the speaker doing it. Offered more often and after a shorter hold; the
+  // hold is still long enough that a phrase does not reposition twice in a
+  // breath.
+  swingP: 0.42,
+  swingAfterMs: 1400,
   swingMs: 320,
   nodP: 0.7,
   // The nod: down and back, over by 0.4 s, and nothing after it. It peaks just
   // ahead of the vowel so that, through the head's 160 ms smoothing, it lands on
   // it. About 2.5° asked of tara, of which the smoothing renders most.
   nod: { pitch: 0.15, attack: 130, release: 240, lead: 170 },
-  // A diagonal nod's yaw, on the turn's side.
-  yawP: 0.35,
+  // A diagonal nod's yaw, on the turn's side. Raised with the swing above, and
+  // for the same reason — a diagonal beat moves the head across the sentence
+  // where a pure pitch nod only moves it down and back. The amplitude is
+  // untouched: the nod's read defect was its geometry, never its size
+  // (3d-avatar-motion-audit.md, 2026-09-14).
+  yawP: 0.45,
   yaw: 0.12,
 };
 
@@ -217,16 +259,21 @@ const BEAT = {
 // shoulders at 0.19 s and the lean at 0.24 s. Each stroke returns through
 // neutral: a trunk that only ever lifts is a standing shrug, which is what a
 // filmstrip once showed as the figure sitting larger and lower in frame.
+// Raised on 2026-09-21 with the rest of the body: the trunk has no measured
+// hold budget the way the head does — nothing about a shoulder tells a
+// projected photograph it has been turned too far — so it is the channel where
+// "a bit more movement" is free, and it is the one the head-on-a-stick read
+// comes from.
 const BEAT_BODY = {
   keys: [[-380, 0], [-60, 1], [140, 0.25], [320, -0.30], [600, 0]],
-  shoulder: 0.28, lean: 0.11, spread: 0.35,
+  shoulder: 0.36, lean: 0.15, spread: 0.35,
 };
 // The lift a phrase carries, over its own span: up on the first stressed
 // syllable and settling below where it started as the breath goes out.
 const PHRASE_BODY = {
   keys: [[-260, 0], [180, 1], [900, 0.5], [1500, -0.30], [2400, 0]],
-  shoulder: 0.22,
-  lean: 0.16,
+  shoulder: 0.28,
+  lean: 0.21,
 };
 
 // The phrase-final settle: chin down this far from the phrase's own pose,
@@ -257,16 +304,40 @@ const HOME_MS = 700;
 // to take the mouth.
 // `ack` rises with the nod and outlasts it, since a smile that ends with the
 // head's last beat reads as part of the gesture rather than as pleasure.
+//
+// `listen` is the fourth, and it is the one episode that is not about speech at
+// all: the floor has arrived and the face receives it. Every other state change
+// the avatar makes is a change of task; this one is a change of *who is
+// talking*, and a face that takes the floor back with no expression at all is
+// where the "not smiling enough" read comes from. Its shape is the owner's
+// (2026-09-21): up, then a long fade to neutral rather than a held level, which
+// is the same argument the other three are built on — a smile that stays is
+// discounted. The full height lasts 1.8 s, inside Ekman's felt-smile window,
+// and the remaining 3.8 s is the fade. **It is the warmest of the four, raised
+// on the owner's read of 2026-09-21 that it was not arriving.** It started at
+// `ack`'s height and reasoned that `close` — the face that hands the floor
+// over — should outrank the face that takes it; on screen that had it landing
+// as a politeness rather than as a welcome, and this is the one episode a user
+// is looking straight at when it fires.
 // Times in ms.
 const WARMTH = {
   onset: { keys: [[0, 0], [350, 1], [1500, 1], [2800, 0]], corner: 0.18, squint: 0.08 },
   close: { keys: [[0, 0], [300, 1], [2600, 1], [3800, 0]], corner: 0.36, squint: 0.14 },
   ack: { keys: [[0, 0], [220, 1], [1100, 1], [2000, 0]], corner: 0.30, squint: 0.12 },
+  listen: { keys: [[0, 0], [400, 1], [2200, 1], [6000, 0]], corner: 0.42, squint: 0.17 },
 };
 // A continuer can come every second or two. Each one smiling would hold the
 // smile up for as long as the user talks, which is the fixed smile again, so
 // an acknowledgement inside this long of the last smiling one nods without it.
 const ACK_SMILE_REST_MS = 4000;
+// The listening smile rests behind *any* warmth, not just its own, and this is
+// the whole of what keeps it from becoming the fixed smile. A turn normally
+// ends SPEAKING -> `close` -> LISTENING within a few hundred ms, and `close` is
+// already that handover's smile; a state that flaps back through LISTENING —
+// through THINKING and out again, or a barge-in and a resume — would otherwise
+// re-arm one every time. Longer than the episodes themselves, so two can never
+// run end to end.
+const LISTEN_SMILE_REST_MS = 7000;
 
 /**
  * What a rig renders of the head amplitudes above, unless it says otherwise.
@@ -320,6 +391,7 @@ export class SpeechProsody {
     this._moves = [];
     this._warm = [];
     this._lastAckSmile = -Infinity;
+    this._lastWarm = -Infinity;
     this._head = new HeadPose();
     this._home = true;
     this._corner = 0;
@@ -360,7 +432,23 @@ export class SpeechProsody {
 
   /** The track played out to its end: the turn's closing warmth. */
   closeTurn() {
-    this._warm.push({ at: this._ms, w: WARMTH.close });
+    this._smile(WARMTH.close);
+  }
+
+  /**
+   * The avatar has entered LISTENING: the floor is the user's. A warmth
+   * episode, unless something smiled recently — see `LISTEN_SMILE_REST_MS`,
+   * which is what stands between this and a face that is always smiling.
+   */
+  listen() {
+    if (this._ms - this._lastWarm < LISTEN_SMILE_REST_MS) return;
+    this._smile(WARMTH.listen);
+  }
+
+  /** Start a warmth episode, and remember that the face has just smiled. */
+  _smile(w) {
+    this._lastWarm = this._ms;
+    this._warm.push({ at: this._ms, w });
   }
 
   /**
@@ -371,10 +459,12 @@ export class SpeechProsody {
   acknowledge() {
     if (this._ms - this._lastAckSmile < ACK_SMILE_REST_MS) return;
     this._lastAckSmile = this._ms;
-    this._warm.push({ at: this._ms, w: WARMTH.ack });
+    this._smile(WARMTH.ack);
   }
 
-  /** Cut off: a smile that survives being interrupted has not noticed. */
+  /** Cut off: a smile that survives being interrupted has not noticed. The
+   *  rest period is deliberately *not* cleared — being interrupted is not an
+   *  occasion to smile a fresh one at the state change that follows. */
   cool() {
     this._warm = [];
   }
@@ -480,7 +570,7 @@ export class SpeechProsody {
     if (cue.v !== SILENT) {
       if (this._onsetPending) {
         this._onsetPending = false;
-        this._warm.push({ at: this._ms, w: WARMTH.onset });
+        this._smile(WARMTH.onset);
       }
       let a = i;
       while (a > 0 && !isPause(cues, a - 1)) a--;

package/src/rig.d.ts

@@ -22,3 +22,10 @@ export type AvatarRigFactory = (mount: HTMLElement, options?: unknown) => Avatar
 
 export const HAND_GESTURE_NAMES: ReadonlyArray<HandFrame["gesture"]>;
 export function avatarFrame(pose: RigPose, hand?: HandFrame): AvatarFrame;
+/** The bundled SVG renderer as a bare rig: what `createAvatar` builds when no
+ *  `rig` option is passed, and what an instrument mounts when it wants a face
+ *  it can pose directly. */
+export function createSvgRig(
+  face: ReturnType<import("./avatar.js").FaceFactory>,
+  hand?: unknown,
+): AvatarRig;