@voqalize/avatar 0.2.1 → 0.3.0

package/src/face-wren.js

@@ -2,7 +2,7 @@
  * 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,
+ * docs/authoring-a-face.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
@@ -30,10 +30,9 @@ import {
   f, createFaceShell, faceApi, poseTransforms, pairedTeeth,
 } from './face-core.js';
 import { taper, taperRing, region } from './line-art.js';
+import { viewBoxForHead } from './camera.js';
 
 export const THEME = {
-  bg0: '#f6f3ee',
-  bg1: '#e8e2d8',
   ink: '#1b1b1b',
   paper: '#ffffff',
   accent: '#f97415',
@@ -42,10 +41,9 @@ export const THEME = {
   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 };
+// Wren's hair cloud is her visible crown; the skull begins well below it.
+const FRAME = { centerX: 380, crownY: 102, chinY: 575 };
+const VB = viewBoxForHead(FRAME);
 
 export const META = {
   viewBox: { x: VB.x, y: VB.y, w: VB.w, h: VB.h },
@@ -53,7 +51,7 @@ export const META = {
 };
 
 // --- landmarks --------------------------------------------------------------
-const CX = 380;
+const CX = FRAME.centerX;
 const HEAD_TOP = 148;
 const CHIN_Y = 572;
 
@@ -224,7 +222,7 @@ const POSE = {
   // 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 },
+  breathSwell: 0.008, swellPivot: { x: CX, y: 950 },
   turnPx: 16,
   layers: LAYERS, parallax: PARALLAX,
   torsoLayers: ['body'],
@@ -254,8 +252,8 @@ function mouthGeometry(p) {
   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 yL = cy - 1.5 - p.mouthCornerL * 22;
+  const yR = cy - 1.5 - p.mouthCornerR * 22;
 
   const apTop = cy - h * 0.25;
   let apBot = cy + h * 0.75;
@@ -348,14 +346,7 @@ function markup(id, t) {
   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)"/>
+  <defs><clipPath id="${id}-clipMouth"><path id="${id}-clipMouthP" d=""/></clipPath></defs>
 
   <!-- 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
@@ -468,3 +459,10 @@ export function createFace(mount, theme = {}) {
 
   return faceApi(mount, svg, apply, t);
 }
+
+/**
+ * This face as a **Face** record — `{ create, meta }`, the shape
+ * `createAvatar({ face })` takes. Importing it costs this drawing and nothing
+ * else; `src/faces.js` is the all-three table, for tooling.
+ */
+export const wren = { create: createFace, meta: META };

package/src/faces.d.ts

@@ -0,0 +1,12 @@
+import type { Face } from "./avatar.js";
+
+export const peep: Face;
+export const wren: Face;
+export const myna: Face;
+
+/** The faces we ship. Not an open vocabulary — a third face is a code change. */
+export type FaceName = "peep" | "wren" | "myna";
+
+export const FACES: Readonly<Record<FaceName, Face>>;
+export const FACE_NAMES: readonly FaceName[];
+export const DEFAULT_FACE: FaceName;

package/src/faces.js

@@ -0,0 +1,53 @@
+/**
+ * The faces we ship, as a table — for tooling that wants every one of them.
+ *
+ * **Importing this costs all three drawings** (~2k lines of path data). That is
+ * the right trade for `rig-check`, the contact sheets, the sweep and Studio,
+ * which exist to compare faces against each other. It is the wrong trade for an
+ * application, which renders one: those import a single face module and hand
+ * the record to `createAvatar` directly.
+ *
+ *     import { peep } from '@voqalize/avatar/faces/peep';
+ *     createAvatar({ mount, client, face: peep });
+ *
+ * A **Face** is `{ create, meta }` and nothing else.
+ *
+ * `create` is `createFace(mount, theme) -> { svg, apply, theme, destroy }`,
+ * callable standalone — the rig tooling drives faces with no mixer attached.
+ * That behavioural contract is the whole of what the *rig* needs: everything
+ * else — visemes, emotions, gaze, idle, clips, the mixer — works in parameter
+ * space and never learns which face it is driving.
+ *
+ * `meta` is the descriptor (viewBox, mouthCrop — see META in any face module):
+ * the things a HOST or a TOOL needs to frame a face without opening it. A face
+ * was once a bare factory, on the argument that a schema guessed from two of
+ * them would be wrong; the third settled it. Every rig needed exactly a framing
+ * rect and a mouth rect to stop the tooling hard-coding per-face tables, and
+ * nothing else — so that is all meta carries.
+ *
+ * The key is the face's name, not its rank. It used to be possible to read rank
+ * into it — the original rig was keyed `default`, which became a lie the moment
+ * it stopped being the one we ship. `DEFAULT_FACE` is the only place the choice
+ * is made, and `packages/avatar/client/createAvatar.ts` is the only place it is consulted.
+ *
+ * Two earlier rigs, `classic` and `blue-shirt`, were removed on 2026-08-06:
+ * stakeholders accepted the line-art pair and rejected both of the others, so
+ * carrying them was maintenance against art nobody wanted. What they taught the
+ * abstraction survives them — `face-core.js` exists because all three of the
+ * first rigs wrote the same apply(), and META exists because all three needed
+ * the same two rects. Their code is in git history if a lesson ever needs
+ * re-reading.
+ */
+
+import { peep } from './face-peep.js';
+import { wren } from './face-wren.js';
+import { myna } from './face-myna.js';
+
+export { peep, wren, myna };
+
+export const FACES = { peep, wren, myna };
+
+export const FACE_NAMES = Object.keys(FACES);
+
+/** The face a host gets when it does not name one. */
+export const DEFAULT_FACE = 'peep';

package/src/gaze.js

@@ -59,6 +59,52 @@ const BLINK_THRESHOLD = 0.45; // shift magnitude that triggers a gaze-evoked bli
 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
 
+/**
+ * Aversion profiles: a brief, deliberate break of eye contact that returns to
+ * whatever the gaze target already was.
+ *
+ * This exists because *holding* the user's eyes is not the attentive pose it
+ * looks like. Wang & Gratch (CHI 2010, n=133) ran the condition directly: a
+ * virtual listener that simply stares rated no better than one that visibly
+ * ignored the user (rapport 3.49 vs 3.34, n.s.), was rated the most *tense* of
+ * the three conditions, and raised the speaker's own disfluency rate to
+ * 36.75/min against 22.44 for a responsive listener. All three were rated
+ * equally natural, so it is not an animation-quality artefact. Rossano supplies
+ * the mechanism — sustained mutual gaze is a *demand for more talk*, not a
+ * signal of attention (95% of sequences expanded when both parties kept looking;
+ * 84% closed when both withdrew) — and Binetti (N=498) puts preferred mutual
+ * gaze at 3295 ± 706 ms, which is well short of forever.
+ *
+ * The other wall is just as hard: sustained *aversion* is an ostracism cue, and
+ * measured on an animated character (Chotpitayasunondh & Douglas, N=128) it
+ * costs η²ₚ = .52–.56 with post-hoc d of 1.09–2.69, with partial inattention
+ * costing most of what total inattention costs. So this is not "look away
+ * sometimes" — it is a narrow band, and the numbers below are Andrist's measured
+ * ones rather than a taste call (docs/research-biomechanics.md §4.2). The spike
+ * that arrived at this band, and what it measured on peep, is
+ * docs/research-active-listening.md.
+ *
+ * `every`/`dur` are seconds. `dirs` are unit-ish directions weighted by how
+ * often each is taken; magnitude is scaled per-fire.
+ */
+export const AVERSION = {
+  // While listening: 1.14 s (SD 0.27) every 7.21 s (SD 1.88), 57.5% sideways.
+  // Sideways dominates because down reads as submission and up reads as
+  // exasperation on a face this schematic.
+  LISTEN: {
+    every: [5.3, 9.1],
+    dur: [0.85, 1.45],
+    mag: [0.30, 0.44],
+    dirs: [[-1, 0.06], [-1, 0.06], [1, 0.02], [1, 0.02], [-0.7, -0.5], [0.5, 0.35]],
+  },
+};
+// There is deliberately no THINK profile. The *cognitive* aversion — 3.54 s
+// (SD 1.26), splitting 39.3% down / 29.4% up / 31.3% side (§4.2) — is longer
+// and deeper than the listening kind, and THINKING already renders it through
+// `wander`, which moves the whole gaze target rather than nudging off it. Two
+// mechanisms producing the same look would fight; the state that thinks looks
+// away properly, and this profile is for the state that must not.
+
 export class GazeLayer {
   constructor() {
     this.target = GAZE_TARGETS.USER;
@@ -68,8 +114,67 @@ export class GazeLayer {
     this.onLargeShift = null;
     this.jitter = { x: 0, y: 0 };
     this._nextMicro = 0;
+    this._t = 0;
+    // --- aversion scheduler
+    this.aversion = null;      // one of AVERSION, or null for none
+    /** Set true when eye contact must be held: the floor is about to change
+     *  hands. Andrist prohibits intimacy-regulating aversions near utterance
+     *  end for exactly this reason — the floor is passed with mutual gaze, and
+     *  an avatar that looks away as the user finishes has just declined it. */
+    this.hold = false;
+    this._avNext = 0;
+    this._avUntil = 0;
+    this._avVec = { x: 0, y: 0 };
+    this._avAmt = 0;           // glided 0..1 so the return is a movement, not a cut
+    this._avProfileRef = undefined;
   }
 
+  /** Adopt an aversion profile (or null). Cheap to call every frame. */
+  setAversion(p) {
+    if (p === this._avProfileRef) return;
+    this._avProfileRef = p;
+    this.aversion = p || null;
+    // Re-arm rather than inherit: a state that averts must not fire the instant
+    // it is entered off a stale timestamp from one that didn't.
+    this._avNext = this._t + (p ? p.every[0] + Math.random() * (p.every[1] - p.every[0]) : 0);
+    this._avUntil = 0;
+  }
+
+  _avert(t, dt) {
+    const p = this.aversion;
+    if (!p) {
+      // Glide home even after the profile is gone, so a state change mid-look
+      // returns the eyes instead of snapping them.
+      this._avAmt = Math.max(0, this._avAmt - dt / 0.18);
+      return;
+    }
+    if (this._avUntil && t >= this._avUntil) {
+      this._avUntil = 0;
+      this._avNext = t + p.every[0] + Math.random() * (p.every[1] - p.every[0]);
+    } else if (!this._avUntil && t >= this._avNext && !this.hold) {
+      this._avUntil = t + p.dur[0] + Math.random() * (p.dur[1] - p.dur[0]);
+      const d = p.dirs[(Math.random() * p.dirs.length) | 0];
+      const m = p.mag[0] + Math.random() * (p.mag[1] - p.mag[0]);
+      this._avVec.x = d[0] * m;
+      this._avVec.y = d[1] * m;
+    }
+    // `hold` cancels an aversion already running, it does not merely postpone
+    // the next: the turn can end mid-look, and the eyes have to be back.
+    const want = this._avUntil && !this.hold ? 1 : 0;
+    // Out fast, back slightly slower. A saccade away is ballistic; the return
+    // to a face is a fraction more deliberate, and symmetric timing here is one
+    // of the things that makes a rig read as a metronome.
+    const rate = want ? dt / 0.055 : dt / 0.11;
+    this._avAmt = want
+      ? Math.min(1, this._avAmt + rate)
+      : Math.max(0, this._avAmt - rate);
+  }
+
+  /** How far off-target the eyes currently are, 0..1. The mixer reads this to
+   *  keep the trunk out of it — an aversion is eyes and a little head, never a
+   *  body turn. */
+  get averted() { return this._avAmt; }
+
   /**
    * @param {string} name  one of GAZE_NAMES
    * @param {{x:number,y:number}} [override] normalized -1..1 escape hatch for
@@ -101,7 +206,11 @@ export class GazeLayer {
   }
 
   update(t, dt) {
+    this._t = t;
     this._micro(t, dt);
+    this._avert(t, dt);
+    const avx = this._avVec.x * this._avAmt;
+    const avy = this._avVec.y * this._avAmt;
 
     // Ballistic head follow: steer velocity toward "full speed at the target,
     // but never faster than can still brake to a stop within the distance
@@ -140,12 +249,18 @@ export class GazeLayer {
     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;
+    const pupilY = this.target.py + this.jitter.y + avy;
+    // The aversion rides *on top of* the ballistic follow rather than through
+    // it: it never touches `this.head`, so it cannot disturb the braking model
+    // and cannot trip the large-shift blink. The head takes only a fraction of
+    // what the eyes take — a brief look-away is an eye movement that the head
+    // barely joins, and a head that follows it fully reads as turning away.
+    const HEAD_SHARE = 0.22;
     return {
-      pupilX: this.target.px + this.jitter.x,
+      pupilX: this.target.px + this.jitter.x + avx,
       pupilY,
-      headYaw: this.head.x,
-      headPitch: this.head.y,
+      headYaw: this.head.x + avx * HEAD_SHARE,
+      headPitch: this.head.y + avy * HEAD_SHARE,
       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.