@voqalize/avatar 0.2.1 → 0.3.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/idle.js

@@ -62,7 +62,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 (tools/motion.mjs) showed the
+ * image. A motion map of the listening state (apps/authoring/tools/motion.mjs) 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.
  *
@@ -384,91 +384,37 @@ export class IdleLayer {
 }
 
 /**
- * The listening engine: backchannels and engagement posture for LISTENING.
+ * The listening engine is now deliberately posture-only.
  *
- * An agent who sits motionless while you talk feels like a recording — but the
- * fix is not more nodding. Gratch's rapport experiments showed that nod
- * *frequency* without *contingency* creates no rapport at all, and an agent
- * that acknowledges on a metronome reads as distracting
- * (docs/research-biomechanics.md §3.5). So this engine is contingent first:
- *
- *   · The server tells it about the user's voice — a coarse speaking flag
- *     (setUserSpeaking), off its own endpointer. With no signal at all the
- *     scheduler falls back to a timer, which is the weakest mode and is meant
- *     to be: contingency is the whole point.
- *   · Acknowledgements fire at PAUSE ONSETS: when the user stops talking, a
- *     nod lands 250–600 ms later, about half the time, never more often than
- *     every 2.5 s. That timing is where a human listener's nod sits.
- *   · During a long unbroken stretch of user speech a rare mid-speech nod
- *     keeps the face alive (nods fill ~26% of human listening time — we err
- *     far quieter, per the screen-share bitrate constraint).
- *   · Engagement posture: `engage` rises while the user speaks and relaxes
- *     after long silence. The mixer spends it on torsoLean — forward lean is
- *     the highest-value listening channel the rig has (§6.3).
- *
- * If the host never supplies any user signal, the old loose random timer runs
- * instead — a worse listener, but never a dead one.
+ * `setUserSpeaking()` receives Pipecat's VAD verdict through the client
+ * adapter. It may alter the sustained engagement lean, but it never chooses or
+ * fires a clip: a nod, brow acknowledgement or any other facial claim of
+ * understanding is an explicit backend/application `action()` decision.
  */
 export class ListeningEngine {
-  constructor(fire) {
-    this.fire = fire;
+  constructor() {
     this.enabled = false;
     this.t = 0;
     this.engage = 0;
-    this.lastFireAt = -1e9;
-    // --- no-signal fallback timer (the pre-contingency behaviour, verbatim)
-    this.minGap = 3.4;
-    this.maxGap = 8.0;
-    this._next = 0;
-    // --- user-signal state
     this._hasSignal = false;
-    this._explicit = null;   // server-declared flag; null = not driven
-    this._speaking = false;  // merged VAD, after hysteresis
-    this._spokeAt = -1e9;    // start of the current speech stretch
-    this._silentAt = 0;      // end of the last one
-    this._pending = -1;      // scheduled contingent fire time, <0 = none
-    this._midNext = 0;
+    this._explicit = null;
+    this._speaking = false;
+    this._silentAt = 0;
   }
 
-  /** Push the next autonomous fire out — called on state changes and after any
-   *  manual interjection, so scheduled nods never pile onto server-driven ones. */
-  reset(delay = 2.5) {
-    this._next = this.t + delay;
-    this.lastFireAt = this.t;
-    this._pending = -1;
-  }
+  /** Compatibility no-ops retained for existing hosts that reached these
+   * internals indirectly. With no autonomous clips there is nothing to reset
+   * or cede. */
+  cede() {}
+  get ceded() { return false; }
+  reset() {}
 
-  /** Server-declared user speech, off the pipeline's own endpointer. Pass null
-   *  to hand back to the no-signal timer. */
+  /** Pipecat VAD's user-speaking truth. `null` removes the engagement signal. */
   setUserSpeaking(b) {
     if (b !== null) this._hasSignal = true;
     this._explicit = b === null ? null : !!b;
   }
 
-  /** The one seam for choosing an acknowledgement. Context-aware: what the
-   *  user just did decides the weight class of the reply
-   *  (docs/research-biomechanics.md §3.3 — continuers co-occur with ongoing
-   *  speech, assessments with completed content; corpus mix 49/40/12,
-   *  shifted quieter here per the screen-share constraint). */
-  pickAck(context) {
-    const r = Math.random();
-    // Mid-speech nods stay minimal: the user still has the floor.
-    if (context === 'midspeech') return r < 0.7 ? 'NOD_SMALL' : 'BROW_ACK';
-    // A pause after a LONG stretch earns an assessment-class nod — the user
-    // completed a thought, and answering a paragraph with a continuer reads
-    // as not having listened to it. NOD_UP is rationed: a realization every
-    // few seconds stops meaning realization.
-    const utter = this._hasSignal ? this._silentAt - this._spokeAt : 0;
-    if (utter >= 4) {
-      if (r < 0.45) return 'NOD_SLOW';
-      if (r < 0.65) return 'NOD_UP';
-      if (r < 0.85) return 'NOD_SMALL';
-      return 'BROW_ACK';
-    }
-    // Short utterance (and the no-signal fallback timer): continuer country.
-    return r < 0.55 ? 'NOD_SMALL' : r < 0.8 ? 'BROW_ACK' : 'NOD_SLOW';
-  }
-
   get speaking() { return this._explicit === true; }
 
   update(dt) {
@@ -480,39 +426,10 @@ export class ListeningEngine {
     // relaxing the moment they pause would read as relief that they stopped.
     if (speaking !== this._speaking) {
       this._speaking = speaking;
-      if (speaking) { this._spokeAt = t; this._pending = -1; }
-      else {
-        this._silentAt = t;
-        // Pause onset: the contingent backchannel moment. Half of pauses get
-        // an acknowledgement; the other half, keeping still IS the answer.
-        if (this.enabled && this._hasSignal
-            && t - this.lastFireAt >= 2.5 && Math.random() < 0.5) {
-          this._pending = t + 0.15 + Math.random() * 0.3;
-        }
-      }
+      if (!speaking) this._silentAt = t;
     }
     const engaged = speaking || t - this._silentAt < 8;
     this.engage = approach(this.engage, engaged && this._hasSignal ? 1 : 0,
       speaking ? 1.5 : 6.0, dt);
-
-    if (!this.enabled) { this._pending = -1; return; }
-
-    if (this._hasSignal) {
-      if (this._pending > 0 && t >= this._pending) {
-        this._pending = -1;
-        this.lastFireAt = t;
-        this.fire(this.pickAck('pause'));
-      }
-      // A long unbroken stretch of user speech earns a rare mid-speech nod.
-      if (speaking && t - this._spokeAt > 5.5 && t - this.lastFireAt > 3.5 && t >= this._midNext) {
-        this._midNext = t + 2.6 + Math.random() * 1.8;
-        if (Math.random() < 0.35) { this.lastFireAt = t; this.fire(this.pickAck('midspeech')); }
-      }
-    } else if (t >= this._next) {
-      // No user signal was ever supplied: the loose timer, exactly as before.
-      this._next = t + this.minGap + Math.random() * (this.maxGap - this.minGap);
-      this.lastFireAt = t;
-      this.fire(this.pickAck('pause'));
-    }
   }
 }