@voqalize/avatar 0.2.2 → 0.4.0

package/src/hand.js

@@ -4,9 +4,9 @@
  * The avatar has no arms (CLAUDE.md, constraint 9): two earlier rigs carried a
  * full forearm/hand chain, nine parameter channels and several hundred lines of
  * geometry each, and it was removed on sight. This is the other design. It
- * survived a stakeholder trial in `experiments/arm-gesture/` and was promoted
- * on 2026-08-07; what makes it a different proposition from the thing that was
- * cut is that **it is not part of the rig**. No parameter channel, no per-face
+ * survived a stakeholder trial and was promoted on 2026-08-07; what makes it a
+ * different proposition from the thing that was cut is that **it is not part of
+ * the rig**. No parameter channel, no per-face
  * geometry, no forearm — one drawing, placed by four numbers derived from the
  * mounted avatar's own `META.viewBox`, painted in its own theme, appended over
  * its SVG. A face that never plays a gesture is byte-for-byte what it was.
@@ -39,37 +39,37 @@
  *    the waves sit LOWER and further back instead (`sc`), and the face stays
  *    entirely clear.
  *
- * 4. THE ONLY EDGE THAT CUTS THE HAND IS THE BOTTOM ONE. Every shipped avatar's
- *    viewBox is a portrait window pillarboxed inside a 16:9 tile, so anything
- *    past the window's right edge is sliced by a hard vertical line that reads
- *    as a rendering fault. Outboard travel is budgeted against the hand's own
+ * 4. THE ONLY EDGE THAT CUTS THE HAND IS THE BOTTOM ONE. Anything past the
+ *    camera's side edge is sliced by a hard vertical line that reads as a
+ *    rendering fault. Outboard travel is budgeted against the hand's own
  *    width AND its rotation — a hand 440 units tall swings ~110 units sideways
  *    at 14 degrees, which is what silently blew the budget the first time.
  *    `checkHandFraming()` asserts both rules against the real timelines.
  *
- * See docs/contract-protocol.md § Hand gestures for the wire surface and
- * docs/contract-avatar.md § The hand for what a face module owes this module
+ * See docs/internal-mixer.md § Hand gestures for the wire surface and
+ * docs/authoring-a-face.md § The hand for what a face module owes this module
  * (the answer is: a viewBox and two theme keys).
  */
 
 import { taper, taperRing, region, smooth } from './line-art.js';
 import { f } from './face-core.js';
+import { CALL_CAMERA } from './camera.js';
 
 // --- the frame --------------------------------------------------------------
 // Everything the hand needs to place itself comes out of `META.viewBox`, and
-// that is the whole reason this module needed no new META field. The three
-// shipped avatars draw a 576x800 portrait window; the numbers below are ratios
-// and offsets against that window, not against any one character's anatomy.
+// that is the whole reason this module needed no new META field. The shared
+// camera makes 70% of its height a head, so size follows the person rather
+// than growing merely because the new 4:3 camera is wider.
 //
 // The wrist sits below the frame edge by a clear margin, never at it: a wrist
 // exactly on the line renders as a rounded end kissing the border, which reads
 // as a hand stuck to the frame rather than one coming from off-camera.
 const WRIST_DROP = 24;   // minimum units the wrist stays below the frame bottom
 const HIDE = 574;        // fully off-camera; must clear the tallest shape
-// How far the outermost ink may sit from the frame centre before the portrait
-// window slices it (rule 4): half the window, less a hair of margin.
+// How far the outermost ink may sit from the frame centre before the camera
+// slices it (rule 4): half the window, less a hair of margin.
 const SIDE_MARGIN = 8;
-// Author scale at a 576-unit-wide window. The number this design changed most,
+// Author scale at a 480-unit-tall head. The number this design changed most,
 // and both directions were rendered and judged. Earlier cuts drew the hand at
 // FACE depth: a 19 cm hand against a 23 cm head is 0.83 of it, peep's head is
 // 477 art units, so ~394 — which came out looking like a pale tube rising past
@@ -85,7 +85,8 @@ const SIDE_MARGIN = 8;
 // becomes ground, and the tile reads as broken before it reads as a gesture.
 // Optically correct, perceptually wrong. 2.95 puts the palm at ~0.82
 // head-widths — still clearly nearer the lens, still clearly not the subject.
-const REACH_AT_576 = 2.95;
+// Compact avatar tiles need a hand that reads as a gesture, not as the subject.
+const REACH_AT_480_HEAD = 2.40;
 
 /** The four placement numbers, derived. A host never sees these. */
 function frameOf(viewBox) {
@@ -93,7 +94,7 @@ function frameOf(viewBox) {
   return {
     cx: vb.x + vb.w / 2,           // frame centre; also where a resting hand starts
     bottom: vb.y + vb.h,           // the visible bottom edge — the line the hand rises past
-    reach: (REACH_AT_576 * vb.w) / 576,
+    reach: (REACH_AT_480_HEAD * vb.h * CALL_CAMERA.head) / 480,
     outboardLimit: vb.w / 2 - SIDE_MARGIN,
   };
 }
@@ -129,17 +130,10 @@ const PALM = [
   // bottom edge, which reads as a shape RESTING ON the edge (a bag, a sheet of
   // paper) rather than one continuing past it. Widest at ~a third down from the
   // fingertips, ~65% of that at the cut, and the eye infers the arm for free.
-  [26, 300], [28, 60], [31, 16],
-  [36, -20], [41, -54],                                  // the widest band
-  [40, -86], [38, -112],                                 // ring+little, splayed
-  [35, -138], [27, -150], [18, -147],                    // DOMED tip, never pointed
-  [13, -134],            // notch floor: ~15% of finger length, and a U not a V
-  [8, -146], [1, -164], [-8, -166],                      // middle, the longest
-  [-16, -156],
-  [-20, -136],           // notch floor
-  [-25, -148], [-33, -157], [-40, -150],                 // index, domed
-  [-44, -130], [-46, -110],
-  [-47, -92],            // the thumb web — shallow, so this is a hand not a fork
+  [24, 300], [26, 58], [30, 18], [38, -18], [42, -48],
+  [39, -72], [31, -86], [21, -84],
+  [17, -104], [8, -116], [-4, -114], [-13, -102], [-16, -84],
+  [-22, -102], [-34, -111], [-46, -104], [-53, -91], [-53, -76],
   // The thumb is a CONVEX WEDGE, and that is a deletion rather than an
   // addition. An earlier thumb had a re-entrant curl in its outer contour; at
   // 130 px the hook read as a detached ear sitting beside the jaw, which was the
@@ -147,11 +141,8 @@ const PALM = [
   // this contour: it leaves the palm's outer edge, swells to a rounded pad at
   // ~40 degrees off the palm axis, and comes back. A thumb is a wedge, and a
   // wedge has two edges.
-  [-56, -99], [-65, -96], [-71, -87],
-  [-72, -75], [-65, -67],                                // the pad: broad, round
-  [-56, -58], [-49, -46],
-  [-46, -26], [-42, 4],                                  // thenar, then the taper
-  [-36, 60], [-32, 300],
+  [-68, -73], [-80, -64], [-84, -52], [-80, -40],
+  [-68, -31], [-56, -22], [-47, -5], [-41, 28], [-34, 300],
 ];
 // Where the finger information moved to. An earlier cut put the interdigital
 // valleys 50-60% of the way down the fingers, which makes a SAW: at 130 px a
@@ -167,8 +158,8 @@ const PALM = [
 // size this ships at) and at full size it reads as a scratch. Economy is not a
 // style here, it is the difference between a mark and a blemish.
 const PALM_SEPS = [
-  [[13, -130], [14, -122], [15, -113]],      // little/ring from middle
-  [[-20, -132], [-21, -124], [-21, -115]],   // middle from index
+  [[10, -94], [10, -89], [11, -84]],
+  [[-20, -94], [-21, -89], [-21, -84]],
 ];
 // The one interior mark that says PALM rather than back-of-hand — and it is the
 // THENAR crease, the arc around the ball of the thumb, not a line across the
@@ -177,7 +168,7 @@ const PALM_SEPS = [
 // rounded white form, at tile size, beside a face, reads as a MOUTH. The arc
 // runs off the bottom edge instead of ending, so nothing about it says "this
 // mark stopped here".
-const PALM_CREASE = [[-46, -80], [-41, -54], [-30, -26], [-14, -2], [-8, 14]];
+const PALM_CREASE = [[-53, -65], [-46, -47], [-34, -27], [-18, -8]];
 
 // --- dorsal: the fist, for thumbs-up ----------------------------------------
 // The back of a closed hand: an undulating top edge of metacarpal heads, and a
@@ -199,13 +190,10 @@ const PALM_CREASE = [[-46, -80], [-41, -54], [-30, -26], [-14, -2], [-8, 14]];
 // that is true, but by 16 units across 60 rather than by 30; the mass is 82 wide
 // against 78 visible. The two undulations survive only as inflections in it.
 const FIST = [
-  [24, 300], [26, 60], [30, 12],            // the wrist really is ~60% of a fist
-  [36, -22], [40, -46],                     // the heel, and the widest band
-  [39, -66], [30, -74], [22, -70],          // TWO undulations, not four knuckles
-  [12, -80], [-2, -86], [-14, -82],         // the larger one, index side
-  [-26, -76], [-36, -64],
-  [-42, -42], [-41, -16],
-  [-37, 60], [-34, 300],
+  [24, 300], [26, 62], [30, 20], [39, -7], [45, -31],
+  [42, -51], [31, -64], [14, -70], [-4, -69],
+  [-21, -63], [-35, -51], [-42, -31], [-40, -6],
+  [-35, 62], [-31, 300],
 ];
 // Four small knuckle bumps were drawn at the same scale and rhythm as peep's
 // hair spikes, so at 130 px the row read as a lapel zigzag continuing the
@@ -223,7 +211,7 @@ const FIST = [
 // frame cut and left the knuckle half of the fist empty. An empty top and a
 // marked bottom is upside down: the eye goes to the crest first, and finds
 // nothing there.
-const FIST_CURL = [[24, -48], [8, -58], [-8, -60], [-24, -52]];
+const FIST_CURL = [[22, -43], [7, -50], [-10, -49], [-25, -41]];
 // The thumb is a SEPARATE CLOSED SHAPE crossing the fist, which is what keeps
 // the middle-finger read dead — the first thumbs-up drawn here was rejected on
 // sight for exactly that. A glyph has tolerances and these are them:
@@ -248,12 +236,9 @@ const FIST_CURL = [[24, -48], [8, -58], [-8, -60], [-24, -52]];
 // its tip and the entire radial column reads as ONE very long digit — the
 // middle-finger silhouette, rebuilt out of correct parts.
 const FIST_THUMB = [
-  [10, -48],                                   // base, deep inside the fist's mass
-  [2, -78], [-1, -100],                        // inner edge — SHORT, and that is the point
-  [-6, -118], [-18, -128], [-31, -122],        // domed tip, and a wide dome
-  [-38, -106], [-38, -88],
-  [-36, -70], [-32, -56], [-25, -44],          // outer edge, tucking back under the crest
-  [10, -48],
+  [17, -42], [8, -61], [2, -78], [-8, -90],
+  [-21, -90], [-31, -80], [-33, -66], [-27, -52],
+  [-16, -41], [17, -42],
 ];
 // There is no thumbnail, and that is the clearest single deletion in this
 // drawing. A short curved crease near the top of the thumb, at 130 px, on a
@@ -270,11 +255,9 @@ const FIST_THUMB = [
 // meaning lives in one unambiguous silhouette rather than in notches, and where
 // it crosses the hair, value does the separating.
 const POINT = [
-  [24, 300], [26, 60], [30, 12],
-  [36, -22], [40, -46],                      // the heel, and the widest band
-  [39, -66], [30, -74], [22, -70],           // two undulations, as on FIST
-  [12, -80], [-2, -84],
-  [-8, -90],                                 // the web — a rounded corner, barely a notch
+  [24, 300], [26, 62], [30, 20], [39, -7], [44, -29],
+  [37, -49], [17, -53], [8, -66], [6, -107],
+  [0, -128], [-11, -136], [-23, -130], [-29, -116], [-29, -72],
   // The index. It once cleared the knuckles by 75 units against a visible fist
   // of 90 — anatomically defensible, and at 0.79 of a head-width it was the
   // longest single mark in the tile. Nothing that is not the face gets to be
@@ -286,15 +269,9 @@ const POINT = [
   // It tapers toward the tip and carries no joint pinch. The pinch was drawn in
   // the OUTLINE, and a wobble that small in a contour does not read as a knuckle
   // at any size — it reads as an unsteady line.
-  [-12, -106], [-15, -122],                  // inner edge
-  [-18, -136], [-25, -146], [-32, -143],     // domed tip, never pointed
-  [-35, -129], [-34, -112],                  // outer edge
-  [-36, -94],
   // The thumb, clamped across the curled fingers and showing as a lobe on the
   // flank. An index-up fist with no thumb anywhere in it is quietly impossible.
-  [-44, -76], [-47, -62], [-44, -50],
-  [-42, -38], [-41, -16],
-  [-37, 60], [-34, 300],
+  [-39, -55], [-42, -31], [-40, -6], [-35, 62], [-31, 300],
 ];
 
 // Ink weights are in ART units, sampled off peep's own marks: the torso runs
@@ -318,22 +295,22 @@ const POINT = [
 // (compose so it doesn't cross; weight hierarchy; knockout) and it is the one
 // already native to these rigs, whose head contour outweighs the brow which
 // outweighs the ear whorl.
-const W_OUTLINE = [16, 15, 9, 6, 9, 15, 17];
+const W_OUTLINE = [12, 11, 8, 6, 8, 11, 12];
 // Device 3, the knockout: a white halo that breaks the shirt's seams where the
 // hand crosses them. It is deliberately NARROW across the middle of the mark:
 // the hand's upper half sits against the background, and a white rim there would
 // turn it into a cut-out sticker. Only the tails — the part over the shirt — get
 // the full gap. Where the halo width equals the ink width it is entirely covered
 // and costs nothing, so the profile is scaled with the ink above it.
-const W_HALO = [34, 29, 13, 6, 13, 29, 35];
+const W_HALO = [26, 22, 13, 6, 13, 22, 26];
 const W_CREASE = [2, 8, 2];
 // The palm's finger separators: thick where they leave the notch floor, gone by
 // the end. This is the ear-whorl mark language, applied to a hand.
-const W_SEP = [7, 3, 0.5];
+const W_SEP = [5, 2, 0.5];
 // The fist's one interior mark. Thick-to-thin across an S, so it reads as a form
 // turning rather than as a drawn line.
 const W_CURL = [3, 9, 7, 2];
-const W_THUMB = [12, 14, 11, 8, 11, 14, 12];
+const W_THUMB = [9, 11, 9, 7, 9, 11, 9];
 
 // The shapes, and the interior marks each one carries. Interior marks carry
 // their own width profile rather than sharing one: three of them exist, they do
@@ -354,7 +331,7 @@ const SHAPES = {
   // being an empty slab.
   POINT: {
     outline: POINT,
-    marks: [{ pts: [[22, -50], [6, -58], [-10, -58]], w: W_CURL }],
+    marks: [{ pts: [[20, -42], [5, -48], [-11, -47]], w: W_CURL }],
     rings: [],
   },
 };
@@ -435,11 +412,11 @@ export const HAND_GESTURES = {
   //
   // The swing is deliberately ASYMMETRIC, -2 out and +16 in. A wave rotating
   // about a wrist below the frame throws the fingertips ~110 units sideways,
-  // and spending that outboard is what put the thumb through the portrait
-  // window the first time. Swinging further toward the person you are waving at
+  // and spending that outboard is what put the thumb through the camera edge
+  // the first time. Swinging further toward the person you are waving at
   // is also, conveniently, what people do.
-  HI: {
-    id: 'HI', label: 'wave hello', shape: 'PALM', face: 'WAVE', dur: 1250, sc: 0.70,
+  GESTURE_GREET: {
+    id: 'GESTURE_GREET', label: 'greet', shape: 'PALM', face: 'GESTURE_GREET', dur: 1250, sc: 0.70,
     out: [[0, 0], [150, 74], [300, 114], [1000, 114], [1250, 30]],
     dy: [[0, HIDE], [150, 240], [300, 40], [390, 60], [700, 50], [1000, 58], [1120, 136], [1250, HIDE]],
     rot: [[0, -3], [150, 2], [310, 16], [475, -2], [640, 16], [805, -1], [970, 12], [1000, 8], [1250, -3]],
@@ -447,8 +424,8 @@ export const HAND_GESTURES = {
   // Goodbye: same hand, slower, one more swing, and it lingers at the top
   // before dropping. A wave that leaves as briskly as it arrived reads as a
   // dismissal rather than a farewell.
-  BYE: {
-    id: 'BYE', label: 'wave goodbye', shape: 'PALM', face: 'WAVE', dur: 1550, sc: 0.70,
+  GESTURE_GOODBYE: {
+    id: 'GESTURE_GOODBYE', label: 'goodbye', shape: 'PALM', face: 'GESTURE_GREET', dur: 1550, sc: 0.70,
     out: [[0, 0], [170, 76], [320, 116], [1300, 116], [1550, 32]],
     dy: [[0, HIDE], [160, 230], [320, 32], [410, 54], [700, 42], [1000, 52], [1300, 46], [1420, 128], [1550, HIDE]],
     rot: [[0, -3], [170, 2], [330, 16], [510, -2], [690, 16], [870, -2], [1050, 16], [1230, -1], [1300, 8], [1550, -3]],
@@ -461,8 +438,8 @@ export const HAND_GESTURES = {
   // exactly why it read the way it did. The wrist spends the entire budget (it
   // sits on the floor), so the fist rides the bottom edge and only the thumb is
   // up near the face.
-  THUMBS_UP: {
-    id: 'THUMBS_UP', label: 'thumbs up', shape: 'FIST', face: 'THUMBS_UP', dur: 1300,
+  GESTURE_APPROVE: {
+    id: 'GESTURE_APPROVE', label: 'approve', shape: 'FIST', face: 'GESTURE_APPROVE', dur: 1300, sc: 0.82,
     out: [[0, 0], [160, 54], [300, 84], [1050, 84], [1300, 32]],
     dy: [[0, HIDE], [160, 174], [300, 24], [390, 42], [700, 34], [1050, 40], [1160, 120], [1300, HIDE]],
     rot: [[0, -6], [160, -2], [300, 3], [400, 0], [700, 1.5], [1000, 0], [1050, 0], [1300, -8]],
@@ -472,8 +449,8 @@ export const HAND_GESTURES = {
   // couple of units and a degree, which reads as a held hand rather than as a
   // stopped clock. Held longest of the four, because it is the one gesture
   // whose job is to buy time (research-perception.md §1, latency masking).
-  ONE_MOMENT: {
-    id: 'ONE_MOMENT', label: 'one moment', shape: 'POINT', face: 'ONE_MOMENT', dur: 1700,
+  GESTURE_WAIT: {
+    id: 'GESTURE_WAIT', label: 'wait', shape: 'POINT', face: 'GESTURE_WAIT', dur: 1700, sc: 0.78,
     out: [[0, 0], [170, 60], [320, 96], [1400, 96], [1700, 34]],
     dy: [[0, HIDE], [170, 244], [320, 32], [410, 54], [700, 46], [1100, 53], [1400, 48], [1520, 136], [1700, HIDE]],
     rot: [[0, -7], [170, -2], [320, 2], [420, 0], [800, 1], [1200, -0.5], [1400, 0], [1700, -9]],
@@ -482,6 +459,22 @@ export const HAND_GESTURES = {
 
 export const HAND_GESTURE_IDS = Object.keys(HAND_GESTURES);
 
+/** Public renderer-frame gesture names → current SVG timelines. */
+const FRAME_GESTURES = Object.freeze({
+  greet: 'GESTURE_GREET',
+  farewell: 'GESTURE_GOODBYE',
+  approve: 'GESTURE_APPROVE',
+  wait: 'GESTURE_WAIT',
+});
+const GESTURE_TO_FRAME = Object.freeze(Object.fromEntries(
+  Object.entries(FRAME_GESTURES).map(([name, id]) => [id, name]),
+));
+
+/** Stable SVG-action names → renderer-neutral hand controls. */
+export const HAND_ACTION_TO_FRAME_GESTURE = Object.freeze({
+  ...GESTURE_TO_FRAME,
+});
+
 // GO_ON is deliberately absent, and this is the reasoning rather than an
 // oversight. It was drawn as a low splayed open palm rocking at the wrist; the
 // stakeholder's verdict was "go on doesn't work for me" and the review was
@@ -520,7 +513,7 @@ function sample(keys, t) {
 
 /**
  * Mount the hand over a face and return the player. Built by `createAvatar`;
- * a host drives it through `avatar.gesture(id)`, never directly.
+ * the public avatar composes it through a semantic `GESTURE_*` action.
  *
  * @param {SVGElement} svg    the mounted face's own root — same coordinate space
  * @param {{ink:string, paper:string}} theme  the mounted face's palette
@@ -575,6 +568,7 @@ export function createHand(svg, theme, meta, opts = {}) {
   for (const [k, s] of Object.entries(SHAPES)) shapes[k] = build(s);
 
   let current = null; // { def, start }
+  const queue = [];
   let lastT = 0;
 
   function place(x, y, rot, sc) {
@@ -588,19 +582,50 @@ export function createHand(svg, theme, meta, opts = {}) {
     for (const s of Object.values(shapes)) s.style.display = 'none';
     place(fr.cx, fr.bottom + HIDE, 0, 1);
   }
+  function show(def) {
+    for (const [k, s] of Object.entries(shapes)) s.style.display = k === def.shape ? '' : 'none';
+  }
+  function applyFrame(frame) {
+    if (!frame) { park(); return; }
+    const id = FRAME_GESTURES[frame.gesture];
+    const def = HAND_GESTURES[id];
+    if (!def) { park(); return; }
+    dir = frame.side === 'left' ? -1 : 1;
+    show(def);
+    const local = Math.max(0, Math.min(1, frame.progress)) * def.dur;
+    place(
+      fr.cx + dir * sample(def.out, local),
+      fr.bottom + sample(def.dy, local),
+      sample(def.rot, local),
+      def.sc || 1,
+    );
+  }
   park();
 
   return {
     get playing() { return !!current; },
     get id() { return current ? current.def.id : null; },
+    /** The semantic hand control for the current animation frame, or null. */
+    get frame() {
+      if (!current) return null;
+      return {
+        gesture: GESTURE_TO_FRAME[current.def.id],
+        progress: Math.max(0, Math.min(1, (lastT - current.start) / current.def.dur)),
+        side: dir === -1 ? 'left' : 'right',
+      };
+    },
+    /** Render a first-class AvatarFrame hand control. */
+    applyFrame,
     setDir(d) { dir = d === -1 ? -1 : 1; if (!current) park(); },
     /** @param {string} id  @param {number} [atMs] start time on the layer's clock */
-    play(id, atMs) {
+    play(id, atMs, { queue: shouldQueue = false } = {}) {
       const def = HAND_GESTURES[id];
       if (!def) throw new Error(`unknown hand gesture: ${id}`);
-      for (const [k, s] of Object.entries(shapes)) {
-        s.style.display = k === def.shape ? '' : 'none';
+      if (current && shouldQueue) {
+        if (current.def.id !== id && !queue.some((item) => item.id === id)) queue.push({ id, def });
+        return def;
       }
+      show(def);
       current = { def, start: atMs !== undefined ? atMs : lastT };
       return def;
     },
@@ -610,15 +635,19 @@ export function createHand(svg, theme, meta, opts = {}) {
       const local = tMs - current.start;
       if (local < 0) return;
       const def = current.def;
-      if (local >= def.dur) { current = null; park(); return def; }
-      place(
-        fr.cx + dir * sample(def.out, local),
-        fr.bottom + sample(def.dy, local),
-        sample(def.rot, local),
-        def.sc || 1
-      );
+      if (local >= def.dur) {
+        const done = def;
+        const next = queue.shift();
+        if (next) {
+          show(next.def);
+          current = { def: next.def, start: tMs };
+        } else {
+          current = null;
+        }
+        return done;
+      }
     },
-    stop() { current = null; park(); },
+    stop() { current = null; queue.length = 0; park(); },
     destroy() { if (g.parentNode) g.parentNode.removeChild(g); },
   };
 }
@@ -626,12 +655,12 @@ export function createHand(svg, theme, meta, opts = {}) {
 /**
  * Rules 1 and 4, asserted rather than eyeballed — both were violated by an
  * early cut and neither is visible in a still of the resting pose. Run by
- * `tools/sweep.mjs` against every registered avatar, because the frame numbers
+ * `pnpm test` against every registered avatar, because the frame numbers
  * are derived per avatar and a rig with a different window could break the
  * budget without anything else noticing.
  *
  *   rule 1  the wrist never rises into the frame;
- *   rule 4  no gesture pushes ink through the portrait window's side edge, at
+ *   rule 4  no gesture pushes ink through the camera window's side edge, at
  *           any point in its rotation. A hand 440 units tall throws its outer
  *           corner ~110 units sideways at 14 degrees, so the budget has to be
  *           spent against `out` AND `rot` together.

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;
+  }
+}