@voqalize/avatar 0.0.1

package/src/face-wren.js

@@ -0,0 +1,470 @@
+/**
+ * Avatar: "wren".
+ *
+ * The second line-art character, and the proof run for the recipe in
+ * docs/contract-avatar.md: static art + a POSE spec + feature blocks + META,
+ * with the stroke engine imported from line-art.js rather than carried along.
+ * Character: female, thirties, a big natural-curl mass, round glasses, a
+ * crew-neck tee. Same idiom as peep — no strokes anywhere, ink and paper and
+ * one accent — different person.
+ *
+ * What is deliberately different from peep, and why it is cheap:
+ * - THE HAIR IS THE SILHOUETTE. A scalloped cloud four times peep's hair mass,
+ *   drawn as one closed loop (outer lobes out, hairline lobes back), covering
+ *   the ears entirely — which is why this file has no ear geometry at all.
+ * - THE GLASSES ARE THE ACCENT. peep spends its one colour on the collar; wren
+ *   wears it on the frames, which makes the two instantly tellable apart at
+ *   any size where a face reads at all.
+ * - CREW NECK, NOT POLO. One band arc instead of blades + placket.
+ *
+ * What the glasses cost the rig: the eye beans live inside the lens rings, so
+ * pupil travel is capped by the frame (9/7 against peep's 11/8) — past that
+ * the bean collides with the ring and reads as the eye hitting glass. In
+ * exchange the ring is a fixed reference the bean moves against, which makes
+ * small gaze shifts MORE legible than on peep, whose beans move against
+ * nothing.
+ */
+
+import { clamp, lerp } from './params.js';
+import {
+  f, createFaceShell, faceApi, poseTransforms, pairedTeeth,
+} from './face-core.js';
+import { taper, taperRing, region } from './line-art.js';
+
+export const THEME = {
+  bg0: '#f6f3ee',
+  bg1: '#e8e2d8',
+  ink: '#1b1b1b',
+  paper: '#ffffff',
+  accent: '#f97415',
+  mouthIn: '#1b1b1b',
+  teeth: '#ffffff',
+  tongue: '#8d7f79',
+};
+
+// Frame: same native 760x950 art space as peep — not a requirement, just no
+// reason to differ — with the window shifted up because the hair cloud crowns
+// ~40 units higher than peep's fade.
+const VB = { x: 92, y: 50, w: 576, h: 800 };
+
+export const META = {
+  viewBox: { x: VB.x, y: VB.y, w: VB.w, h: VB.h },
+  mouthCrop: { x: 298, y: 432, w: 164, h: 96 },
+};
+
+// --- landmarks --------------------------------------------------------------
+const CX = 380;
+const HEAD_TOP = 148;
+const CHIN_Y = 572;
+
+const EYE = { y: 386, dx: 55, rx: 15, ry: 17.5 };
+const NOSE_TOP = 408;
+const MOUTH = { cx: CX, cy: 486 };
+const MOUTH_APERTURE = 36;
+
+// Brows: shorter and rounder than peep's, sitting clear above the lens rings
+// (lens top is y=355; a full browRaise lifts these 15 units and they still
+// never touch the frames). Drawn control points, per the peep correction —
+// the arch is not recoverable from endpoints.
+const BROW_L = [[CX - 22, 342], [CX - 40, 334], [CX - 58, 330], [CX - 72, 331],
+                [CX - 82, 334], [CX - 89, 338], [CX - 93, 343]];
+const BROW_R = [[CX + 24, 340], [CX + 42, 332], [CX + 60, 329], [CX + 73, 330],
+                [CX + 82, 333], [CX + 88, 337], [CX + 92, 342]];
+
+// ---------------------------------------------------------------------------
+// Static art: head.
+//
+// Same three-segment jaw rule as every head in this project (an unbroken
+// ear-to-ear curve is an egg), but the runs are softer: the gonion corner is
+// rounded off and the chin pad is narrower — that softness, not any single
+// feature, is most of what makes this face read as a different person before
+// the hair even loads. Chin a touch left of midline; symmetric heads read
+// as machine output.
+// ---------------------------------------------------------------------------
+const HEAD = [
+  [CX, HEAD_TOP],
+  [452, 147], [520, 204], [524, 288],
+  [527, 340], [523, 390], [520, 428],
+  [518, 462], [513, 486], [502, 510],
+  [488, 532], [456, 558], [426, 568],
+  [408, 575], [352, 574], [334, 566],
+  [308, 554], [282, 534], [264, 508],
+  [250, 482], [244, 458], [248, 426],
+  [242, 390], [237, 340], [240, 288],
+  [244, 202], [308, 145], [CX, HEAD_TOP],
+];
+const HEAD_W = [3.5, 7, 11, 14, 15, 13.5, 10, 7, 4.5, 3.5];
+
+// Neck: peep's truncated-cone construction, narrower. Fused into the head
+// layer and run long past the neckline for the same layer-parallax reasons.
+const NECK_FILL =
+  'M336 514C326 575 318 630 316 700L316 790L444 790L444 700C442 630 434 575 424 514Z';
+const NECK_L = [[336, 532], [329, 588], [323, 656], [320, 750]];
+const NECK_R = [[424, 528], [431, 584], [437, 654], [440, 750]];
+const JAW_UNDER = [[336, 560], [354, 586], [408, 588], [428, 558]];
+
+// ---------------------------------------------------------------------------
+// Static art: hair — the curl cloud.
+//
+// One closed loop: outer silhouette left-to-right over the crown as a chain of
+// LOBES (each segment's controls pushed outward, so consecutive lobes meet at
+// soft cusps — that cusp rhythm is what says "curls" with zero interior
+// marks), then the hairline right-to-left back across the forehead as smaller
+// lobes pointing down. What the loop encloses is the hair band itself: the
+// sides run 40 units wide down to y≈470, which is why wren needs no ears.
+// ---------------------------------------------------------------------------
+const HAIR = [
+  [252, 468],
+  // up the left side, three outer lobes
+  [214, 442], [206, 408], [218, 382],
+  [188, 352], [190, 306], [218, 284],
+  [196, 240], [222, 196], [262, 186],
+  // over the crown
+  [286, 138], [330, 116], [366, 124],
+  [398, 102], [446, 106], [462, 130],
+  [508, 138], [534, 170], [526, 196],
+  // down the right side
+  [560, 226], [562, 268], [546, 290],
+  [568, 322], [566, 362], [538, 388],
+  [552, 424], [540, 456], [508, 466],
+  // transition onto the hairline
+  [500, 462], [498, 458], [496, 452],
+  // back across the forehead, right to left: smaller lobes, pointing down
+  [500, 396], [498, 352], [486, 330],
+  [482, 296], [468, 278], [452, 272],
+  [430, 252], [396, 246], [380, 256],
+  [362, 242], [326, 252], [306, 270],
+  [288, 282], [278, 306], [272, 330],
+  [262, 352], [258, 400], [258, 452],
+  // close the loop at the bottom-left
+  [256, 460], [254, 464], [252, 468],
+];
+const HAIR_D = region(HAIR);
+
+// ---------------------------------------------------------------------------
+// Static art: glasses.
+//
+// Round frames in the ACCENT colour — wren's version of peep's collar trim.
+// Rings are taperRings with a gently uneven profile (first and last width
+// equal, or the ring seams at the 3 o'clock point). The temples run outward
+// and vanish under the hair band, which is what lets them be four points long.
+// ---------------------------------------------------------------------------
+const LENS_R = 29;
+const K = 0.5523; // circle-as-four-cubics constant
+
+function circlePts(cx, cy, r) {
+  const k = r * K;
+  return [
+    [cx + r, cy], [cx + r, cy + k], [cx + k, cy + r], [cx, cy + r],
+    [cx - k, cy + r], [cx - r, cy + k], [cx - r, cy], [cx - r, cy - k],
+    [cx - k, cy - r], [cx, cy - r], [cx + k, cy - r], [cx + r, cy - k],
+    [cx + r, cy],
+  ];
+}
+const LENS_L = circlePts(CX - EYE.dx, EYE.y, LENS_R);
+const LENS_R_ = circlePts(CX + EYE.dx, EYE.y, LENS_R);
+const RING_W = [5, 6, 5, 6.5, 5];
+const BRIDGE = [[CX - 26, 378], [CX - 10, 366], [CX + 10, 366], [CX + 26, 378]];
+const TEMPLE_L = [[CX - 86, 384], [CX - 100, 380], [CX - 112, 378], [CX - 121, 378]];
+const TEMPLE_R = [[CX + 86, 384], [CX + 100, 380], [CX + 112, 378], [CX + 121, 378]];
+
+/** The nose: one mark, a shorter hook than peep's — the bridge work is done
+ *  by the glasses, so the nose only has to land the tip. */
+const NOSE_D = taper(
+  [[CX - 3, NOSE_TOP], [CX - 10, 424], [CX - 15, 438], [CX - 9, 448],
+   [CX - 3, 455], [CX + 9, 453], [CX + 15, 444]],
+  [2, 8, 3]
+);
+
+// ---------------------------------------------------------------------------
+// Static art: torso — a crew-neck tee.
+//
+// Same two-run shoulder construction as peep (outer arm edge, hard turn at
+// the acromion, near-horizontal trapezius shelf), set slightly narrower. The
+// neckline is one band arc with an ink underline — no blades, no placket.
+// ---------------------------------------------------------------------------
+const TORSO = [
+  [60, 950],
+  [62, 864], [104, 750], [184, 720],
+  [240, 710], [286, 676], [322, 632],
+  [334, 662], [426, 664], [440, 628],
+  [474, 672], [518, 706], [570, 716],
+  [648, 746], [694, 860], [696, 950],
+];
+const TORSO_W = [9, 10, 8, 7.5, 10, 9];
+
+const SEAM_L = [[186, 722], [168, 782], [172, 862], [186, 950]];
+const SEAM_R = [[568, 718], [587, 778], [583, 858], [572, 950]];
+
+const NECKBAND = [[322, 630], [340, 645], [360, 655], [380, 658],
+                  [400, 654], [422, 644], [438, 627]];
+
+// Two creases, on the right this time — cloth folds where the body pulls it,
+// and mirroring peep's left-side set would make the two shirts read as the
+// same drawing recoloured.
+const CREASES = [
+  { p: [[452, 738], [447, 764], [446, 788], [450, 806]], w: [2, 6, 2] },
+  { p: [[478, 742], [474, 766], [473, 790], [476, 808]], w: [2, 5, 2] },
+];
+
+// ---------------------------------------------------------------------------
+// Layers: the same four as peep, same order, same parallax.
+// ---------------------------------------------------------------------------
+const PARALLAX = { head: 1.0, body: 0.1, features: 1.22, hair: 1.12 };
+const LAYERS = ['head', 'body', 'features', 'hair'];
+const PIVOT = { x: CX, y: 700 };
+
+// yawPx a touch under peep's 28: the hair cloud is a much larger mass and at
+// 28 its parallax slide against the head read as a wig shifting.
+const POSE = {
+  leanTravel: 23, leanPivot: { x: PIVOT.x, y: 560 },
+  shrugLift: 30, shrugTiltDeg: 1.8, shrugPivot: { x: PIVOT.x, y: 800 },
+  yawPx: 26, pitchPx: 16,
+  pivot: PIVOT,
+  // peep's breath and trunk numbers; same construction, same art units, and
+  // the two characters should breathe alike. See face-peep.js for the
+  // derivation.
+  breathSwell: 0.012, swellPivot: { x: CX, y: 950 },
+  turnPx: 16,
+  layers: LAYERS, parallax: PARALLAX,
+  torsoLayers: ['body'],
+  units: 1,
+};
+
+// ---------------------------------------------------------------------------
+// Generators: mouth. peep's contour model with wren's landmarks — the model
+// carried over intact; only the sizing constants are this face's own. See
+// face-peep.js for the full derivation commentary (aperture-not-centreline,
+// the 0.18 compensation ramp, 3:1 downward opening, the cubic 0.75 solve).
+// ---------------------------------------------------------------------------
+function mouthGeometry(p) {
+  const cx = MOUTH.cx;
+  const cy = MOUTH.cy;
+  const open = clamp(p.mouthOpen);
+  const round = clamp(p.mouthRound);
+  const tuck = clamp(p.mouthTuck);
+
+  const w = (24 + clamp(p.mouthWidth) * 30) * (1 - 0.36 * round);
+
+  const t = 1 - 0.4 * clamp(p.mouthPress);
+  const profile = [2.5 * t, 9.5 * t, 3 * t, 10.5 * t * (1 + 0.35 * tuck), 2.5 * t];
+  const halfUp = profile[1] / 2;
+  const halfLo = profile[3] / 2;
+
+  const h = open * MOUTH_APERTURE;
+  const k = clamp(open / 0.18);
+
+  const yL = cy - 6 - p.mouthCornerL * 22;
+  const yR = cy - 6 - p.mouthCornerR * 22;
+
+  const apTop = cy - h * 0.25;
+  let apBot = cy + h * 0.75;
+  if (tuck > 0) apBot = Math.max(apTop + 6, apBot - tuck * (h * 0.6 + 4));
+
+  const cornerMid = (yL + yR) / 8;
+  const topY = (apTop - k * halfUp - cornerMid) / 0.75;
+  const botY = (apBot + k * halfLo - cornerMid) / 0.75;
+
+  const contour = [
+    [cx - w, yL],
+    [cx - w * 0.55, topY], [cx + w * 0.55, topY], [cx + w, yR],
+    [cx + w * 0.55, botY], [cx - w * 0.55, botY], [cx - w, yL],
+  ];
+
+  const innerTop = cornerMid + 0.75 * topY + halfUp;
+  const innerBot = cornerMid + 0.75 * botY - halfLo;
+
+  return { contour, profile, cx, cy, w, h, topY, botY, innerTop, innerBot, open, tuck };
+}
+
+/** peep's dental-arch teeth, verbatim but for the width factors. */
+function teethPath(m, amt, lower) {
+  if (amt < 0.01) return '';
+  const gap = m.innerBot - m.innerTop;
+  if (gap < 2) return '';
+  const tw = m.w * (lower ? 0.6 : 0.76);
+  const cap = lower ? 0.5 : 0.5 + 0.35 * m.tuck;
+  const th = Math.min(amt * (lower ? 13 : 20), gap * cap);
+
+  if (lower) {
+    const base = m.innerBot + 8;
+    const edge = m.innerBot - th;
+    const end = m.innerBot - th * 0.35;
+    return (
+      `M${f(m.cx - tw)} ${f(base)}L${f(m.cx + tw)} ${f(base)}` +
+      `L${f(m.cx + tw * 0.92)} ${f(end)}` +
+      `Q${f(m.cx)} ${f(2 * edge - end)} ${f(m.cx - tw * 0.92)} ${f(end)}Z`
+    );
+  }
+  const top = m.innerTop - 8;
+  const edge = m.innerTop + th;
+  const end = m.innerTop + th * 0.35;
+  return (
+    `M${f(m.cx - tw)} ${f(top)}L${f(m.cx + tw)} ${f(top)}` +
+    `L${f(m.cx + tw * 0.92)} ${f(end)}` +
+    `Q${f(m.cx)} ${f(2 * edge - end)} ${f(m.cx - tw * 0.92)} ${f(end)}Z`
+  );
+}
+
+// Eyes: peep's bean model, verbatim but for the tilt values (wren's beans sit
+// nearly level — the glasses rings already give the face its geometry, and a
+// strong bean tilt inside a perfect circle reads as misaligned lenses).
+function eyePath(cx, cy, lid, squint, tiltDeg) {
+  const L = clamp(lid);
+  const topY = lerp(cy - EYE.ry * 1.05, cy - EYE.ry * 0.42, L);
+  const botY = lerp(cy + EYE.ry * 1.05, cy - EYE.ry * 0.05, L) - clamp(squint) * EYE.ry * 0.7;
+  const rx = EYE.rx;
+  const a = (tiltDeg * Math.PI) / 180;
+  const ca = Math.cos(a), sa = Math.sin(a);
+  const R = (x, y) => {
+    const dx = x - cx, dy = y - cy;
+    return `${f(cx + dx * ca - dy * sa)} ${f(cy + dx * sa + dy * ca)}`;
+  };
+  return (
+    `M${R(cx - rx, cy)}` +
+    `C${R(cx - rx * 0.5, topY)} ${R(cx + rx * 0.5, topY)} ${R(cx + rx, cy)}` +
+    `C${R(cx + rx * 0.5, botY)} ${R(cx - rx * 0.5, botY)} ${R(cx - rx, cy)}Z`
+  );
+}
+
+// Brows: peep's point-list deformation, wren's points and a lighter profile.
+function browPath(pts, raise, angle, inner) {
+  const n = pts.length - 1;
+  const out = pts.map(([x, y], i) => {
+    const u = i / n;
+    return [x, y - raise * 15 - inner * 11 * (1 - u) - angle * 12 * u];
+  });
+  return taper(out, [3, 12, 6], 6);
+}
+
+// ---------------------------------------------------------------------------
+// Static markup
+// ---------------------------------------------------------------------------
+const HEAD_FILL = region(HEAD);
+const HEAD_RING = taperRing(HEAD, HEAD_W, 10);
+
+function markup(id, t) {
+  const ink = (d) => `<path d="${d}" fill="${t.ink}"/>`;
+  return `
+<svg id="${id}" viewBox="${VB.x} ${VB.y} ${VB.w} ${VB.h}" xmlns="http://www.w3.org/2000/svg"
+     preserveAspectRatio="xMidYMid meet" style="display:block;width:100%;height:100%">
+  <defs>
+    <radialGradient id="${id}-gBg" cx="50%" cy="36%" r="76%">
+      <stop offset="0%" stop-color="${t.bg0}"/><stop offset="100%" stop-color="${t.bg1}"/>
+    </radialGradient>
+    <clipPath id="${id}-clipMouth"><path id="${id}-clipMouthP" d=""/></clipPath>
+  </defs>
+
+  <rect x="${VB.x}" y="${VB.y}" width="${VB.w}" height="${VB.h}" fill="url(#${id}-gBg)"/>
+
+  <!-- head and neck. No ears: the hair band covers them (see the hair note).
+       Hair underlay at head parallax, same insurance as peep's — the cloud
+       abuts the skull with no margin, and the hair layer slides against the
+       head under yaw. -->
+  <g id="${id}-head">
+    <path d="${NECK_FILL}" fill="${t.paper}"/>
+    ${ink(taper(NECK_L, [3, 8, 6]))}
+    ${ink(taper(NECK_R, [3, 8, 6]))}
+    <path d="${HEAD_FILL}" fill="${t.paper}"/>
+    ${ink(HEAD_RING)}
+    ${ink(taper(JAW_UNDER, [2, 5.5, 2]))}
+    <path d="${HAIR_D}" fill="${t.ink}"/>
+  </g>
+
+  <!-- tee: silhouette, sleeve seams, neckband, creases -->
+  <g id="${id}-body">
+    <path d="${region(TORSO)}" fill="${t.paper}"/>
+    ${ink(taper(TORSO, TORSO_W))}
+    ${ink(taper(SEAM_L, [6, 7, 5]))}
+    ${ink(taper(SEAM_R, [6, 7, 5]))}
+    ${ink(taper(NECKBAND, [5, 8, 5]))}
+    ${CREASES.map((c) => ink(taper(c.p, c.w))).join('\n    ')}
+  </g>
+
+  <!-- features: brows, eyes, nose, glasses, mouth -->
+  <g id="${id}-features">
+    <path id="${id}-browL" fill="${t.ink}"/>
+    <path id="${id}-browR" fill="${t.ink}"/>
+    <g id="${id}-eyes">
+      <path id="${id}-eyeL" fill="${t.ink}"/>
+      <path id="${id}-eyeR" fill="${t.ink}"/>
+    </g>
+    <path d="${NOSE_D}" fill="${t.ink}"/>
+    <path d="${taperRing(LENS_L, RING_W)}" fill="${t.accent}"/>
+    <path d="${taperRing(LENS_R_, RING_W)}" fill="${t.accent}"/>
+    <path d="${taper(BRIDGE, [4, 5.5, 4])}" fill="${t.accent}"/>
+    <path d="${taper(TEMPLE_L, [4, 4.5, 5])}" fill="${t.accent}"/>
+    <path d="${taper(TEMPLE_R, [4, 4.5, 5])}" fill="${t.accent}"/>
+    <g id="${id}-mouth">
+      <path id="${id}-mouthIn" fill="${t.mouthIn}"/>
+      <g clip-path="url(#${id}-clipMouth)">
+        <ellipse id="${id}-tongue" fill="${t.tongue}"/>
+        <path id="${id}-teeth" fill="${t.teeth}"/>
+        <path id="${id}-teethLo" fill="${t.teeth}" opacity=".85"/>
+      </g>
+      <path id="${id}-lips" fill="${t.ink}"/>
+    </g>
+  </g>
+
+  <!-- hair -->
+  <g id="${id}-hair">
+    <path d="${HAIR_D}" fill="${t.ink}"/>
+  </g>
+</svg>`;
+}
+
+// ---------------------------------------------------------------------------
+// Renderer — peep's apply() shape exactly; only the travels differ.
+// ---------------------------------------------------------------------------
+let uid = 0;
+
+export function createFace(mount, theme = {}) {
+  const t = Object.assign({}, THEME, theme);
+  const id = `wren${++uid}`;
+  const { svg, $, set } = createFaceShell(mount, id, markup(id, t));
+
+  const el = {
+    head: $('head'), body: $('body'), features: $('features'), hair: $('hair'),
+    browL: $('browL'), browR: $('browR'),
+    eyes: $('eyes'), eyeL: $('eyeL'), eyeR: $('eyeR'),
+    mouthIn: $('mouthIn'), lips: $('lips'), clipMouth: $('clipMouthP'),
+    teeth: $('teeth'), teethLo: $('teethLo'), tongue: $('tongue'),
+  };
+
+  function apply(p) {
+    poseTransforms(p, set, el, POSE);
+
+    // Eyes: bean travel capped by the lens rings — see the header. 10 is the
+    // most x the frame allows (bean edge 25 against an inner radius of 26);
+    // DISTRACTED is the state that needs every unit of it, same lesson as
+    // peep's 7→11 raise, hit from the other side.
+    set(el.eyes, 'transform', `translate(${f(p.pupilX * 10)} ${f(p.pupilY * 7)})`);
+
+    const lidFollow = Math.max(0, p.pupilY) * 0.22;
+    set(el.eyeL, 'd', eyePath(CX - EYE.dx, EYE.y + 1, p.lidL + lidFollow, p.squintL, -3));
+    set(el.eyeR, 'd', eyePath(CX + EYE.dx, EYE.y - 1, p.lidR + lidFollow, p.squintR, 3));
+
+    set(el.browL, 'd', browPath(BROW_L, p.browRaiseL, p.browAngleL, p.browInnerL));
+    set(el.browR, 'd', browPath(BROW_R, p.browRaiseR, p.browAngleR, p.browInnerR));
+
+    const m = mouthGeometry(p);
+    const contour = region(m.contour);
+    set(el.mouthIn, 'd', contour);
+    set(el.clipMouth, 'd', contour);
+    set(el.lips, 'd', taperRing(m.contour, m.profile, 12));
+    // Keyed off the drawn gap, not mouthOpen — a half-opaque interior is GREY,
+    // and grey on a two-value face reads as a rendering fault (peep's F bug).
+    set(el.mouthIn, 'opacity', f(clamp((m.innerBot - m.innerTop) / 3)));
+
+    pairedTeeth(p, set, el, teethPath, m);
+
+    const tg = clamp(p.tongue);
+    set(el.tongue, 'cx', f(m.cx));
+    set(el.tongue, 'cy', f(m.innerBot + 6 - tg * ((m.innerBot - m.innerTop) * 0.8 + 6)));
+    set(el.tongue, 'rx', f(m.w * 0.58));
+    set(el.tongue, 'ry', '8');
+    set(el.tongue, 'opacity', tg > 0.02 ? '1' : '0');
+  }
+
+  return faceApi(mount, svg, apply, t);
+}

package/src/gaze.js

@@ -0,0 +1,155 @@
+/**
+ * Gaze.
+ *
+ * The server sends a semantic direction; the client does the oculomotor work.
+ * Three details do almost all the perceptual heavy lifting, and skipping any
+ * one of them makes the face read as a puppet:
+ *
+ *   1. The eyes get there first. Saccades are near-instant; the head ambles
+ *      after — accelerating, cruising, braking to a stop (see HEAD_ACCEL).
+ *   2. The head only goes part of the way. Real people under-rotate the head
+ *      and let the eyes carry the remainder.
+ *   3. A blink fires on any large shift. Gaze-evoked blinks are involuntary and
+ *      their absence is uncanny even though nobody can name what's wrong.
+ */
+
+export const GAZE_TARGETS = {
+  // Straight down the barrel of the webcam — the default during conversation.
+  USER:     { px:  0.00, py:  0.06, hx:  0.00, hy:  0.00 },
+  // Still on the user, but the head is cheated aside so an ear favors the
+  // speaker — the "I'm trying to hear you" attitude. The trick is that the
+  // head-follow and the pupils point OPPOSITE ways: the head turns off-axis
+  // and the eyes counter back to the camera, which is what keeps it reading
+  // as contact rather than as looking away. CANT_HEAR sits on this target.
+  USER_EAR: { px: -0.42, py:  0.05, hx:  0.55, hy:  0.02, roll: 0.55 },
+  SCREEN_CENTER: { px:  0.00, py: -0.16, hx:  0.00, hy: -0.10 },
+  SCREEN_LEFT:   { px: -0.78, py: -0.10, hx: -0.36, hy: -0.05 },
+  SCREEN_RIGHT:  { px:  0.78, py: -0.10, hx:  0.36, hy: -0.05 },
+  SCREEN_TOP:    { px:  0.00, py: -0.72, hx:  0.00, hy: -0.30 },
+  SCREEN_BOTTOM: { px:  0.00, py:  0.62, hx:  0.00, hy:  0.24 },
+  SCREEN_WORK:     { px: -0.62, py:  0.18, hx: -0.26, hy:  0.12 },
+  NOTES:         { px:  0.18, py:  0.72, hx:  0.04, hy:  0.28 },
+  // The classic "recalling something" break of eye contact. Keep it for the
+  // stylized "let me think" beat — audiences read up-and-away regardless of
+  // whether real thinkers do it.
+  AWAY_THINKING: { px: -0.58, py: -0.58, hx: -0.20, hy: -0.18, roll: 0.08 },
+  AWAY_RIGHT:    { px:  0.58, py: -0.52, hx:  0.20, hy: -0.16, roll: -0.06 },
+  // Where measured cognitive aversion actually goes: DOWN (39%, more than up
+  // or side — docs/research-biomechanics.md §4.2). Down-left, mild enough
+  // that the lid follow shades the eyes without sealing them; the head
+  // carries a share so the pupils stay inside the aperture at tile size.
+  AWAY_DOWN:     { px: -0.45, py:  0.42, hx: -0.18, hy:  0.20, roll: 0.04 },
+};
+
+export const GAZE_NAMES = Object.keys(GAZE_TARGETS);
+
+const HEAD_FOLLOW_TAU = 0.34; // roll only — the head lags the eyes badly, on purpose
+const BLINK_THRESHOLD = 0.45; // shift magnitude that triggers a gaze-evoked blink
+
+// Head follow is ballistic, not exponential. An exponential chase has its peak
+// velocity at t=0 and then creeps forever — motion that starts instantly and
+// never quite arrives is what "drifting" looks like. A real orienting head
+// accelerates, cruises, and *brakes to a stop*; the stop is the cue that
+// attention has landed (docs/research-biomechanics.md §1.2 — the head's travel
+// is a discrete arriving move, eyes first, head after). The constants keep the
+// old τ=0.34 amble: a typical 0.3-unit shift completes in ~0.55s, USER_EAR's
+// 0.55-unit swing in ~0.85s. The mixer still low-passes headYaw/headPitch at
+// τ=0.16 downstream, which rounds the hard stop into a short settle — that
+// cascade is deliberate, so do not "help" by softening the brake here too.
+const HEAD_ACCEL = 4.0; // units/s² — sets both launch and braking firmness
+const HEAD_SPEED = 0.9; // units/s — cruise cap; only long swings ever reach it
+
+export class GazeLayer {
+  constructor() {
+    this.target = GAZE_TARGETS.USER;
+    this.name = 'USER';
+    this.head = { x: 0, y: 0, roll: 0 };
+    this.vel = { x: 0, y: 0 };
+    this.onLargeShift = null;
+    this.jitter = { x: 0, y: 0 };
+    this._nextMicro = 0;
+  }
+
+  /**
+   * @param {string} name  one of GAZE_NAMES
+   * @param {{x:number,y:number}} [override] normalized -1..1 escape hatch for
+   *        when the server knows exact screen coordinates
+   */
+  set(name, override) {
+    const next = override
+      ? { px: override.x, py: override.y, hx: override.x * 0.42, hy: override.y * 0.36 }
+      : GAZE_TARGETS[name] || GAZE_TARGETS.USER;
+    const d = Math.hypot(next.px - this.target.px, next.py - this.target.py);
+    this.target = next;
+    this.name = override ? 'CUSTOM' : name;
+    if (d > BLINK_THRESHOLD && this.onLargeShift) this.onLargeShift();
+  }
+
+  /**
+   * Micro-saccades. Eyes are never still; a perfectly fixed pupil reads as
+   * dead. Small, frequent, and irregular.
+   */
+  _micro(t, dt) {
+    if (t >= this._nextMicro) {
+      this._nextMicro = t + 0.7 + Math.random() * 1.6;
+      this.jitter.x = (Math.random() - 0.5) * 0.16;
+      this.jitter.y = (Math.random() - 0.5) * 0.11;
+    }
+    const decay = 1 - Math.exp(-dt / 0.5);
+    this.jitter.x -= this.jitter.x * decay;
+    this.jitter.y -= this.jitter.y * decay;
+  }
+
+  update(t, dt) {
+    this._micro(t, dt);
+
+    // Ballistic head follow: steer velocity toward "full speed at the target,
+    // but never faster than can still brake to a stop within the distance
+    // left". The braking bound is v² = 2·a·d solved for v, with a half-step
+    // correction for discrete time (the −maxA term) so a frame never lands
+    // past the target. As d shrinks the bound falls to zero, which *is* the
+    // deceleration — no separate easing curve.
+    const dx = this.target.hx - this.head.x;
+    const dy = this.target.hy - this.head.y;
+    const d = Math.hypot(dx, dy);
+    const maxA = HEAD_ACCEL * dt;
+    const brake = 0.5 * (Math.sqrt(maxA * maxA + 8 * HEAD_ACCEL * d) - maxA);
+    const goal = Math.min(HEAD_SPEED, brake);
+    let ax = (d ? (dx / d) * goal : 0) - this.vel.x;
+    let ay = (d ? (dy / d) * goal : 0) - this.vel.y;
+    const a = Math.hypot(ax, ay);
+    if (a > maxA) { ax *= maxA / a; ay *= maxA / a; }
+    this.vel.x += ax;
+    this.vel.y += ay;
+    // A dropped-frame dt could step past the target; land on it instead.
+    // Judged on the toward-target component so a mid-retarget frame with
+    // sideways velocity keeps flying rather than teleporting.
+    const along = d ? ((this.vel.x * dx + this.vel.y * dy) / d) * dt : 0;
+    if (along >= d && d >= 0) {
+      this.head.x = this.target.hx;
+      this.head.y = this.target.hy;
+      this.vel.x = 0;
+      this.vel.y = 0;
+    } else {
+      this.head.x += this.vel.x * dt;
+      this.head.y += this.vel.y * dt;
+    }
+
+    // Roll stays on the exponential: its travels are tiny (≤0.55 and usually
+    // ~0.08), far below where the drift tail is visible.
+    const k = 1 - Math.exp(-dt / HEAD_FOLLOW_TAU);
+    this.head.roll += ((this.target.roll || 0) - this.head.roll) * k;
+
+    const pupilY = this.target.py + this.jitter.y;
+    return {
+      pupilX: this.target.px + this.jitter.x,
+      pupilY,
+      headYaw: this.head.x,
+      headPitch: this.head.y,
+      headRoll: this.head.roll,
+      // The upper lid tracks the eye vertically. Without this, looking down
+      // exposes a band of sclera above the iris and the avatar looks startled.
+      lidBias: pupilY * 0.34,
+    };
+  }
+}