@voqalize/avatar 0.3.0 → 0.4.1

package/src/head.js

@@ -0,0 +1,134 @@
+/**
+ * Hold-and-move: how a head spends a conversation.
+ *
+ * Watch a person on a video call with the sound off and the head is almost
+ * never *moving*. It is held, and every second or two it goes somewhere else
+ * — a quick, decided move of a few degrees, a short settle, and then still
+ * again. Speech adds strokes on top: a nod on a stressed word, down and back,
+ * over in a third of a second. What it never does is glide, and gliding is
+ * the one thing a stack of smoothed envelopes can do. That stack is what this
+ * replaced: beats, a phrase drift and a lead-in, each a linear keyframe curve,
+ * summed and then low-passed at the head's 160 ms, drew a head in continuous
+ * motion from the first word to the last. A video reviewer called it a
+ * screensaver (a recorded call, reviewed 2026-09-12), and that is
+ * the right word: every part was a movement the literature measured, and the
+ * sum was a movement nobody makes.
+ *
+ * So this keeps the *events* the research found — a head that moves before the
+ * voice, beats on stressed vowels, the settle as a phrase ends — and changes
+ * what an event is:
+ *
+ *  - A **move** takes the held pose somewhere new along a minimum-jerk path,
+ *    the profile a practised human reach follows (Flash & Hogan 1985): it
+ *    starts and stops at zero velocity and acceleration, and nearly all of its
+ *    travel is in the middle. It arrives, and then the pose is exactly still.
+ *  - A **stroke** is a pulse on top of the held pose: out fast, back a little
+ *    slower, and nothing left over when it is done.
+ *
+ * Between those the output does not change at all, and that stillness is the
+ * point: it is what makes the moves read as decisions.
+ *
+ * Times are ms on whatever clock the owner keeps; this only needs it to be
+ * monotonic.
+ */
+
+/** Minimum-jerk position for a normalised time in [0, 1]. */
+export const minJerk = (x) => (x <= 0 ? 0 : x >= 1 ? 1 : x * x * x * (10 + x * (-15 + 6 * x)));
+
+/**
+ * Fold `x` into ±`limit` without a corner: identity up to `KNEE` of the way
+ * there, then an exponential approach that reaches the limit only in the
+ * limit. It is memoryless — the same input gives the same output whenever it
+ * arrives — so nothing it touches is re-timed, which is what lets it sit in a
+ * chain whose curves are all authored against a known smoothing.
+ *
+ * A hard clamp was the obvious thing and is wrong here: what wants limiting is
+ * a sum of layers that each stay small and occasionally point the same way, so
+ * a clamp would be invisible for a minute and then hold the head perfectly
+ * still at the stop for half a second — the one thing a held pose must not do,
+ * because stillness is how this file says "decided". The knee sits at 0.7
+ * because below it the pose passes through untouched, and a recorded minute of
+ * either conversational state spends its median there.
+ */
+const KNEE = 0.7;
+export const soften = (x, limit) => {
+  const a = KNEE * limit;
+  const m = Math.abs(x);
+  if (!(limit > 0) || m <= a) return x;
+  return Math.sign(x) * (a + (limit - a) * (1 - Math.exp(-(m - a) / (limit - a))));
+};
+
+export const HEAD_AXES = ['headYaw', 'headPitch', 'headRoll'];
+const ZERO = Object.freeze({ headYaw: 0, headPitch: 0, headRoll: 0 });
+
+export class HeadPose {
+  constructor() {
+    // The held pose as a list of moves, each starting where the one before it
+    // had got to. A move may be booked ahead of time (a head moves before the
+    // voice it anticipates), so the next one can be waiting while this one
+    // plays.
+    this._moves = [{ at: -Infinity, dur: 0, from: ZERO, to: ZERO }];
+    this._strokes = [];
+  }
+
+  /** The pose the head will hold once every booked move has landed. */
+  get aim() {
+    return this._moves[this._moves.length - 1].to;
+  }
+
+  /**
+   * Go to `pose` (missing axes keep where they are), starting at `at` and
+   * arriving `dur` ms later. A move booked to start before one already
+   * booked replaces it: the later plan wins, from wherever the head will be.
+   */
+  moveTo(pose, at, dur) {
+    while (this._moves.length > 1 && this._moves[this._moves.length - 1].at > at) this._moves.pop();
+    const from = this._held(at);
+    this._moves.push({ at, dur: Math.max(1, dur), from, to: { ...from, ...pose } });
+  }
+
+  /** A pulse of `add` (per axis) that peaks `attack` ms after `at` and is gone `release` ms later. */
+  stroke(add, at, attack, release) {
+    this._strokes.push({ add, at, attack, release });
+  }
+
+  /** Drop every stroke that has not begun by `now`; the ones under way finish. */
+  cancelStrokes(now) {
+    this._strokes = this._strokes.filter((s) => s.at <= now);
+  }
+
+  /** True when nothing is booked or playing after `now`: the head is holding. */
+  still(now) {
+    const m = this._moves[this._moves.length - 1];
+    return now >= m.at + m.dur && this._strokes.every((s) => now >= s.at + s.attack + s.release);
+  }
+
+  /** The head's offset at `now`, per axis. */
+  sample(now) {
+    // A move whose successor has started can no longer be seen.
+    while (this._moves.length > 1 && this._moves[1].at <= now) this._moves.shift();
+    this._strokes = this._strokes.filter((s) => now < s.at + s.attack + s.release);
+    const out = this._held(now);
+    for (const s of this._strokes) {
+      const t = now - s.at;
+      if (t <= 0) continue;
+      const e = t < s.attack ? minJerk(t / s.attack) : 1 - minJerk((t - s.attack) / s.release);
+      for (const k in s.add) out[k] += e * s.add[k];
+    }
+    return out;
+  }
+
+  /** The held pose at `t`, strokes left out: where the head *is*, not what it is doing. */
+  held(t) {
+    return this._held(t);
+  }
+
+  _held(t) {
+    let m = this._moves[0];
+    for (const n of this._moves) if (n.at <= t) m = n;
+    const k = minJerk((t - m.at) / m.dur);
+    const out = {};
+    for (const c of HEAD_AXES) out[c] = m.from[c] + (m.to[c] - m.from[c]) * k;
+    return out;
+  }
+}

package/src/idle.js

@@ -17,6 +17,7 @@
  */
 
 import { approach } from './params.js';
+import { HeadPose } from './head.js';
 
 /**
  * An idle profile. Every state carries one (sparse — missing keys mean these
@@ -24,7 +25,13 @@ import { approach } from './params.js';
  * the layer, because an oscillator whose amplitude steps is a visible pop.
  *
  *   sway        0..~1.2  head-drift / brow-drift / shoulder / torso amplitude
- *   blinkGap    [min,max] seconds between spontaneous blinks
+ *   blinkGap    [min,max] seconds between blinks — ALL blinks. A blink the
+ *               face is made to do (a gaze shift, a state change, a pause in
+ *               speech) replaces the next timed one instead of adding to it,
+ *               so this is the state's rate whatever else is going on.
+ *   slowBlink   0..1 share of timed blinks drawn slow (0.34 s) — the heavy,
+ *               deliberate blink of someone thinking. A share of the budget,
+ *               not a second clock on top of it.
  *   breathRate  multiplier on the 0.23 Hz resting cycle (13.8/min)
  *   breathAmp   breath excursion scale; cognitive load = faster AND shallower
  *   hold        { every:[s,s], dur:[s,s] } — freeze the sway (breath continues).
@@ -41,10 +48,15 @@ import { approach } from './params.js';
  *               perfectly still. Amplitude rides on `sway`, which is how the
  *               cognitive states get the measured sway *suppression* under
  *               load (§6.2) without a second knob.
+ *   settle      [s,s] gap between the head's own small re-positionings, or
+ *               null for a head that only moves when something moves it.
+ *               Amplitude rides on `sway` too.
  */
 export const DEFAULT_PROFILE = {
   sway: 1.0,
+  settle: [1.8, 4.6],
   blinkGap: [1.9, 5.4],
+  slowBlink: 0,
   breathRate: 1.0,
   breathAmp: 1.0,
   hold: null,
@@ -55,6 +67,26 @@ export const DEFAULT_PROFILE = {
 
 const rand = ([a, b]) => a + Math.random() * (b - a);
 
+// No evoked blink within this long of the last blink. A glance out and back
+// is two large gaze shifts a second apart and carries one blink, not two; and
+// a state change that lands on a gaze shift is one event to the eyelids.
+const BLINK_REFRACTORY = 1.5;
+
+// How far into the current gap an odds-rolled evoked blink may land, as a
+// fraction of that gap. A state that moves its gaze oftener than it blinks —
+// SEARCHING_SCREEN hops 42 times a minute against a 10/min budget, and nearly
+// every hop clears the ramp — would otherwise blink at its gaze's rate rather
+// than its own. This lets such a blink only *move* the next one onto a shift,
+// which is the half worth keeping (research-biomechanics.md §5.4: a blink at a
+// boundary is worth several placed at random), and not add one.
+//
+// 0.80 is where the trade turns, measured on tara's targets at 30 min a state:
+// SEARCHING_SCREEN falls from 2.12x its authored rate to 1.06x and
+// REVIEWING_SCREEN from 1.36x to 1.01x, while 54% of the former's blinks still
+// land on a hop. Tighter values buy hundredths of rate and halve that
+// placement — 0.90 holds only 26%.
+const EVOKED_EARLIEST = 0.80;
+
 /**
  * Postural weight shift: the one part of this layer that is not periodic, and
  * the part that does most of the work.
@@ -62,7 +94,7 @@ const rand = ([a, b]) => a + Math.random() * (b - a);
  * Everything else here is an oscillator, and an oscillator cannot make a body
  * look alive across a thirty-second hold. Fast enough to notice and it reads
  * as rocking; slow enough not to and it is indistinguishable from a still
- * image. A motion map of the listening state (apps/authoring/tools/motion.mjs) showed the
+ * image. A headless motion map of the listening state showed the
  * outer edge of the torso travelling zero pixels over 24 seconds — the sway
  * was there in the numbers and rendered as nothing at all.
  *
@@ -107,6 +139,58 @@ function nextPosture(prev) {
   };
 }
 
+/**
+ * The head's settle: where a person's head goes while nothing is moving it.
+ *
+ * It used to be a pair of slow sines per axis, and on tara that was two
+ * failures at once. At 0.05-0.09 Hz and under a degree it was too slow to see
+ * as motion, so a listening face read as frozen — "a dead stare, only blinks",
+ * in the video review that found it — and what could be seen of it was a head
+ * that never stops gliding, which is the other failure. A listener's head does
+ * neither: it is held, and every few seconds it re-positions — one to two
+ * degrees, over about half a second — and is held again (head.js). Pose units
+ * at sway 1; on tara a unit of yaw is 10.7°, of pitch 17.1°, of roll 5.7°. The
+ * first cut asked for about a degree and a recorded call measured it at 3 px
+ * of head travel, which is the frozen listener it was meant to fix.
+ *
+ * None of these is a nod. The renderer does not acknowledge on its own
+ * (CLAUDE.md), so a settle is one move, never a down-and-back — that property,
+ * 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.
+ */
+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 HOME = { headYaw: 0, headPitch: 0, headRoll: 0 };
+
+/**
+ * The moving hold: what keeps a held head alive.
+ *
+ * Hold-and-move fixed the floating head, and the same reviewer then found the
+ * holds themselves uncanny — "absolute 0-velocity holds", a head locked while
+ * only the mouth moves. Animators met this long ago: a character that stops
+ * dead reads as a still frame, so a held pose keeps drifting by a fraction of
+ * its size: here a few tenths of a degree, small enough that a move still
+ * reads as the event. It runs in every state, speech included, and yields to
+ * a static hold, which is stillness on purpose.
+ *
+ * **It is not a sum of sines.** The first cut was, at 0.2-0.6 Hz, and the next
+ * review read it at once as floating underwater: a periodic sway is a loop,
+ * and people see loops. Human postural sway is a random walk, and it stops —
+ * a head drifts for a few seconds, then is quiet for a couple. So each axis
+ * glides to a new random offset every 0.6-2.2 s through two smoothing stages
+ * (an S-shaped approach, no overshoot, no rhythm), and a gate alternates
+ * drifting stretches with near-still ones. The body's idle drift takes the
+ * 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,
+  retarget: [0.6, 2.2], tau: 0.38,
+  drift: [2.0, 5.0], still: [1.2, 3.5], stillGain: 0.12,
+};
+
 /** Ease so the shift has no corners at either end — a weight shift accelerates
  *  and settles, and a linear ramp between two postures reads as a slide. */
 const smoothstep = (x) => x * x * (3 - 2 * x);
@@ -125,8 +209,18 @@ export class IdleLayer {
     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];
+    // The moving hold (LIVE): per axis a random target, a first stage chasing
+    // it and the output chasing that; and the drift/still gate.
+    this._liveTo = [0, 0, 0];
+    this._liveA = [0, 0, 0];
+    this._liveB = [0, 0, 0];
+    this._liveAt = 0;
+    this._liveOn = true;
+    this._liveFlip = rand(LIVE.drift);
+    this._liveGate = 1;
     // Glided amplitudes (profiles set the target, these chase it).
     this._sway = 1;
     this._breathAmp = 1;
@@ -151,6 +245,11 @@ export class IdleLayer {
     this._shiftAt = 8;
     this._shiftT0 = -1;
     this._shiftDur = 2;
+    // Settle machine: the head's held pose, and when it next moves.
+    this._head = new HeadPose();
+    this._settleAt = 1 + Math.random() * 2;
+    this._settleSide = Math.random() < 0.5 ? -1 : 1;
+    this._settled = false;
     // Speech phrasing: a slow gain the talking body's excursion rides on, so
     // it comes in waves rather than as a steady hum.
     this._phrase = 0;
@@ -179,20 +278,53 @@ export class IdleLayer {
     }
   }
 
-  /** Force a blink now — used on gaze shifts and state transitions. */
-  blink(double = false) {
+  /**
+   * Blink now. `evoked` is a blink the face is made to do by something else —
+   * a large gaze shift, a state change, a pause in speech — and it is refused
+   * inside BLINK_REFRACTORY of the last one, and again before EVOKED_EARLIEST
+   * of the way through the current gap. Every blink, evoked or not, restarts
+   * the timer: people blink at a rate, and an event moves a blink earlier
+   * rather than adding one. Without that, a state that glances or wanders
+   * blinks at its timer's rate plus its gaze's, far past the rates in
+   * docs/research-biomechanics.md §5 that the gaps are set from.
+   *
+   * `forced` is a beat the state asked for by name — `glance.blinkTo` and
+   * `blinkBack`, the re-engagement the author wanted seen. It clears the budget
+   * gate but not the refractory: a state whose authored beats overrun its own
+   * rate is a decision to revisit in that state, not something for the eyelids
+   * to drop silently.
+   */
+  blink(double = false, 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);
+  }
+
+  _startBlink(dur, double) {
     if (this._blinkT >= 0) return;
     this._blinkT = 0;
     this._double = double;
-    this._blinkDur = 0.11 + Math.random() * 0.04;
+    this._blinkDur = dur;
+    this._lastBlinkAt = this.t;
+    this._nextBlink = this.t + rand(this.profile.blinkGap);
+  }
+
+  /**
+   * A blink placed by speech, at a pause. It also restarts the timer: a speaker
+   * who blinks at a clause boundary does not blink again a moment later
+   * because a clock said so, and the timer is only there to fill a long run
+   * of speech with no pauses in it.
+   */
+  phraseBlink() {
+    this.blink(false, true);
   }
 
   /** A slow, deliberate blink — reads as thinking or fatigue. */
   slowBlink() {
-    if (this._blinkT >= 0) return;
-    this._blinkT = 0;
-    this._double = false;
-    this._blinkDur = 0.34;
+    this._startBlink(0.34, false);
   }
 
   _blinkValue(dt) {
@@ -216,9 +348,13 @@ export class IdleLayer {
     const pr = this.profile;
 
     if (t >= this._nextBlink) {
+      // 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);
-      // Roughly one blink in six comes in a pair.
-      this.blink(Math.random() < 0.16);
+      // A share of them slow if the state asks for it; roughly one in six of
+      // the rest comes in a pair.
+      if (Math.random() < pr.slowBlink) this.slowBlink();
+      else this.blink(Math.random() < 0.16);
     }
     const blink = this._blinkValue(dt);
 
@@ -327,6 +463,49 @@ export class IdleLayer {
       this._flickT = -1;
     }
 
+    // The settle. Not while talking — speech holds and moves the head itself
+    // (prosody.js), and two layers each re-positioning it is a head with two
+    // minds — and never inside a static hold, which is stillness on purpose.
+    if (pr.settle && this.talk < 0.5) {
+      if (t >= this._settleAt && t >= this._holdUntil) {
+        this._settleAt = t + rand(pr.settle);
+        if (Math.random() < SETTLE.switchP) this._settleSide = -this._settleSide;
+        const m = this._sway * this.gain;
+        this._head.moveTo({
+          headYaw: this._settleSide * rand(SETTLE.yaw) * m,
+          headPitch: rand(SETTLE.pitch) * m,
+          headRoll: (Math.random() < 0.5 ? -1 : 1) * rand(SETTLE.roll) * m,
+        }, t * 1000, rand(SETTLE.dur) * 1000);
+        this._settled = true;
+      }
+    } else if (this._settled) {
+      this._settled = false;
+      this._head.moveTo(HOME, t * 1000, 600);
+    }
+    const hs = this._head.sample(t * 1000);
+    // The moving hold (LIVE). Only half of it rides on `sway`: a state that
+    // turns its drift down still has a living head.
+    if (t >= this._liveAt) {
+      this._liveAt = t + rand(LIVE.retarget);
+      for (let i = 0; i < 3; i++) this._liveTo[i] = Math.random() * 2 - 1;
+    }
+    if (t >= this._liveFlip) {
+      this._liveOn = !this._liveOn;
+      this._liveFlip = t + rand(this._liveOn ? LIVE.drift : LIVE.still);
+    }
+    this._liveGate = approach(this._liveGate, this._liveOn ? 1 : LIVE.stillGain, 0.5, dt);
+    for (let i = 0; i < 3; i++) {
+      this._liveA[i] = approach(this._liveA[i], this._liveTo[i], LIVE.tau, dt);
+      this._liveB[i] = approach(this._liveB[i], this._liveA[i], LIVE.tau, dt);
+    }
+    const live = this.gain * this._holdAmp * (0.5 + 0.5 * this._sway) * this._liveGate;
+    const [ly, lp, lr] = this._liveB;
+    hs.headYaw += ly * LIVE.yaw * live;
+    hs.headPitch += (lp * LIVE.pitch - Math.sin(this._breathPh) * LIVE.breathPitch * this._breathAmp) * live;
+    hs.headRoll += lr * LIVE.roll * live;
+    // The body's idle drift, quieted with the head (the speech term is not).
+    const ad = a * (0.35 + 0.65 * this._liveGate);
+
     // Speech moves the body more, and in waves. `talk` says whether sound is
     // being produced, `_phrase` says how hard this stretch of it is being
     // pushed.
@@ -344,11 +523,14 @@ export class IdleLayer {
         // below the 0.04-0.6 Hz seated trunk band, still calm, but now
         // actually present on screen. `gain` is where a deployment that
         // really is paying for the pixels turns it back down.
-        headYaw: (s(0, 0.094) * 0.6 + s(0, 0.058) * 0.4) * 0.075 * a
-          + flickYaw + post.headYaw * ps,
-        headPitch: (s(1, 0.072) * 0.6 + s(1, 0.046) * 0.4) * 0.055 * a + workPitch,
-        headRoll: s(2, 0.061) * 0.048 * a + post.headRoll * ps,
-        breath: breath * this.gain,
+        // The head is the exception: it settles rather than sways (SETTLE).
+        headYaw: hs.headYaw + flickYaw + post.headYaw * ps,
+        headPitch: hs.headPitch + workPitch,
+        headRoll: hs.headRoll + post.headRoll * ps,
+        // Speech reorganises breathing: a quick inbreath at a pause and a long
+        // 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,
@@ -368,11 +550,20 @@ export class IdleLayer {
         // torso band's mean luminance range falls 28 -> 24. Sway suppression is
         // a statement about drift. Speech reorganises the body; it does not
         // park it.
-        shoulderL: (s(1, 0.11) * 0.5 + s(2, 0.22) * 0.5) * (0.040 * a + 0.10 * say * this.gain)
+        // The speech term is smaller than it was, and that is a handover rather
+        // than a reduction. `prosody.js` now puts the body's share of an accent
+        // and of a phrase's posture on the shoulders and the lean, timed off
+        // the words; this is a pair of sine waves timed off nothing. Two
+        // unrelated sources at full strength read as a body that is busy
+        // without being about anything, and the one that knows what is being
+        // 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)
           + workL + post.shoulderL * ps,
-        shoulderR: (s(2, 0.10) * 0.5 + s(0, 0.19) * 0.5) * (0.040 * a + 0.10 * say * this.gain)
+        shoulderR: (s(2, 0.10) * 0.5 + s(0, 0.19) * 0.5) * (0.040 * ad + 0.045 * say * this.gain)
           + workR + post.shoulderR * ps,
-        torsoLean: s(0, 0.085) * (0.028 * a + 0.075 * say * this.gain) + post.torsoLean * ps,
+        torsoLean: s(0, 0.085) * (0.028 * 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.

package/src/interjections.js

@@ -119,16 +119,21 @@ const CLIPS = {
     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]],
+      // Recognition is quick: everything arrives in the first ~150 ms and then
+      // holds. It used to build over the first third of the clip with the lids
+      // half-lowered and the trunk sinking, and a video reviewer read that as
+      // the head drifting down — "looks like losing consciousness". The lids
+      // are a flicker now, not a droop, and the lean is a small forward set.
+      browRaiseL: [[0, 0], [0.09, 0.17], [0.30, 0.06], [1, 0]],
+      browRaiseR: [[0, 0], [0.09, 0.14], [0.30, 0.05], [1, 0]],
+      lidL: [[0, 0], [0.10, 0.09], [0.30, 0.04], [0.70, 0.02], [1, 0]],
+      lidR: [[0, 0], [0.10, 0.09], [0.30, 0.04], [0.70, 0.02], [1, 0]],
+      mouthPress: [[0, 0], [0.13, 0.20], [0.60, 0.15], [1, 0]],
+      mouthCornerL: [[0, 0], [0.18, 0.09], [0.80, 0.055], [1, 0]],
+      mouthCornerR: [[0, 0], [0.18, 0.09], [0.80, 0.055], [1, 0]],
+      torsoLean: [[0, 0], [0.14, 0.07], [0.70, 0.05], [1, 0]],
+      shoulderL: [[0, 0], [0.16, 0.060], [0.70, 0.035], [1, 0]],
+      shoulderR: [[0, 0], [0.16, 0.060], [0.70, 0.035], [1, 0]],
     },
   },
   ACK_REALIZE: {
@@ -164,19 +169,47 @@ const CLIPS = {
   // 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.
+  // **Slower than it was, and that is what made it land.** This nod ran two
+  // down-beats 381 ms apart — 2.6 Hz, which is past the 1.5 Hz line CLAUDE.md
+  // and research-biomechanics.md § 3.4 both draw between "I'm with you" and
+  // "hurry up", and which the head's own 160 ms smoothing attenuates to about a
+  // third. Authoring it louder was the obvious fix and the wrong one: the
+  // gesture was not too small, it was too *fast* to survive the mass of the
+  // thing it was moving.
+  //
+  // At 780 ms between down-beats it is 1.28 Hz, attenuated to about 0.64
+  // instead of 0.36, and 1.5 s long — which is where the research puts this
+  // kind of nod anyway. § 3.3 separates a `short` continuer (0.83 s, small)
+  // from a `long` assessment nod (1.42 s, large range), and an acknowledgement
+  // of what someone just said is the second. § 3.4's two structural laws hold:
+  // the first cycle is the biggest, and each one decays.
+  //
+  // **No opening up-beat, and the corpus is why.** An earlier pass gave this a
+  // small preparatory lift on the theory that a nod winds up before it starts.
+  // § 3.3 separates `long` (large range, *no* swing-up) from `long_p` (large
+  // range *with* one, reading as a cognitive shift), so a lift here was quietly
+  // making agreement look like realisation. It also broke the rate: the beat
+  // sat 330 ms before the first peak, a 1.52 Hz opening half-cycle in a clip
+  // whose two down-beats are a comfortable 1.28 Hz apart.
   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]],
+    id: 'ACK_NOD', label: 'acknowledge: nod', text: '', duration: 1500,
+    keys: {
+      // Down, up through neutral, down again, settle. The trailing −0.08 flourish
+      // that used to sit at 0.94 is gone: it put two *return* beats 570 ms apart,
+      // a 1.75 Hz oscillation inside a clip whose down-beats are a comfortable
+      // 1.28 Hz. A gesture's last move should be releasing, not one more beat.
+      // Each down is the stroke and each up the recovery, so the downs are
+      // fast and the ups take their time: a symmetric ramp on both sides read
+      // as "a very slow, linear dip" on video. The downs still sit 720 ms
+      // apart (1.39 Hz), and a short hold at the bottom is what gives the
+      // stroke its weight.
+      headPitch: [[0, 0], [0.16, 1.10], [0.24, 1.00], [0.52, -0.20], [0.64, 0.66], [0.72, 0.58], [1, 0]],
+      headRoll: [[0, 0], [0.18, -0.090], [0.70, -0.070], [1, 0]],
+      torsoLean: [[0, 0], [0.32, 0.130], [0.70, 0.085], [1, 0]],
+      shoulderL: [[0, 0], [0.44, 0.062], [0.76, 0.036], [1, 0]],
+      shoulderR: [[0, 0], [0.44, 0.062], [0.76, 0.036], [1, 0]],
+      lidL: [[0, 0], [0.30, 0.070], [0.68, 0.040], [1, 0]],
+      lidR: [[0, 0], [0.30, 0.070], [0.68, 0.040], [1, 0]],
     },
   },
   // The disagree family follows the same three laws as explicit nods (§3.4): the
@@ -664,10 +697,21 @@ const CLIPS = {
 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.
+ * This renderer's own addressable actions — the bundled SVG faces' catalogue,
+ * not the wire's vocabulary, which is open and has only two required ids
+ * (`docs/contract-wire.md` § Action).
+ *
+ * Every one of these is a name a server may send *once it knows this renderer
+ * is mounted*, and nothing here is a name it may send blind. Two of them are
+ * what `ACKNOWLEDGE` resolves to on the floor — `ACK_NOD` while the user still
+ * has it, `ACK_RECEIVE` once they have stopped — and `RESPONSE_INTERRUPTED` is
+ * required of every avatar, so it appears here as this renderer's shape for it
+ * rather than as its own idea. The four `GESTURE_*` are things this body does
+ * and no protocol asks for.
+ *
+ * Naming is `CATEGORY_INTENT`, and the list doubles as the conformance sweep's
+ * roster: `ACKNOWLEDGE` is absent on purpose, because sweeping both shapes it
+ * resolves to covers strictly more.
  */
 export const ACTION_IDS = Object.freeze([
   'ACK_RECEIVE', 'ACK_NOD',