@voqalize/avatar 0.2.2 → 0.3.0

package/src/conformance.js

@@ -0,0 +1,119 @@
+/**
+ * The rig conformance sweep — the assertions, with no page around them.
+ *
+ * Drives every state, emotion, gaze and semantic action through every rig you
+ * hand it, then a viseme track, and asserts the mixer keeps producing finite,
+ * in-range parameters and a still-attached drawing. A NaN anywhere in the chain
+ * shows up as a *frozen face*, which is exactly the defect the eye is worst at
+ * catching: a still avatar looks calm, not broken.
+ *
+ * This is the numeric half of judging a rig, and it is the smaller half —
+ * passing here says a change did not break the mixer, never that it looks good
+ * (CLAUDE.md § Verifying). It is also what a face author runs against a new
+ * drawing before anyone is asked to look at it.
+ *
+ * `advance` is the seam that lets one copy of the sweep serve both callers:
+ * `apps/authoring/rig-check.html` lets real time pass and watches it happen, while
+ * `packages/avatar/test/conformance.test.ts` steps `{manual: true}` avatars by a fixed
+ * dt and finishes in milliseconds. The sweep's own clock is handed to `speak`
+ * so the mouth articulates under both — a stepped avatar reading
+ * `performance.now()` would sit on the first cue for the whole track.
+ */
+import {
+  STATE_NAMES,
+  EMOTION_NAMES,
+  GAZE_NAMES,
+  ACTION_IDS,
+  checkHandFraming,
+} from './avatar.js';
+import { textToCues } from './visemes.js';
+
+/** Parameters live in −1..1 by contract; 2 is the slack a gain may legally add. */
+const PARAM_LIMIT = 2;
+
+const realTime = (s) => new Promise((r) => setTimeout(r, s * 1000));
+
+/**
+ * @param {Array<{name: string, avatar: object}>} rigs one entry per drawing
+ * @param {{advance?: (seconds: number) => void|Promise<void>}} [opts]
+ * @returns {Promise<{ok: boolean, problems: string[], summary: string}>}
+ */
+export async function conformanceSweep(rigs, { advance = realTime } = {}) {
+  const problems = [];
+  let ms = 0;
+  const clock = () => ms;
+  const tick = async (seconds) => { ms += seconds * 1000; await advance(seconds); };
+  const all = (fn) => rigs.forEach((r) => fn(r.avatar, r.name));
+
+  function check(label) {
+    for (const r of rigs) {
+      const p = r.avatar.params;
+      for (const k in p) {
+        if (!Number.isFinite(p[k])) problems.push(`${r.name} ${label}: ${k}=${p[k]}`);
+        else if (Math.abs(p[k]) > PARAM_LIMIT) {
+          problems.push(`${r.name} ${label}: ${k} out of range (${p[k].toFixed(2)})`);
+        }
+      }
+      // A renderer-neutral rig has no svg to detach; the SVG one must stay put.
+      if (r.avatar.svg && !r.avatar.svg.isConnected) problems.push(`${r.name} ${label}: svg detached`);
+    }
+  }
+
+  for (const s of STATE_NAMES)   { all((k) => k.setState(s));      await tick(0.09); check(`state ${s}`); }
+  for (const e of EMOTION_NAMES) { all((k) => k.setEmotion(e, 1)); await tick(0.09); check(`emotion ${e}`); }
+  for (const g of GAZE_NAMES)    { all((k) => k.setGaze(g));       await tick(0.09); check(`gaze ${g}`); }
+  for (const i of ACTION_IDS)    { all((k) => k.action(i));        await tick(0.18); check(`action ${i}`); }
+
+  // The hand. Two things are being proved and only one of them is the mixer's.
+  // Playing each gesture above checked the usual invariants — its face half runs
+  // through the clip layer like any other interjection. checkHandFraming is the
+  // one that matters per AVATAR: the hand places itself off META.viewBox, so a
+  // rig with a different window could push ink through the camera edge or lift
+  // the wrist into frame, and neither is visible in a resting still.
+  for (const r of rigs) {
+    if (!r.avatar.meta) continue;
+    try { checkHandFraming(r.avatar.meta); } catch (e) { problems.push(`${r.name} ${e.message}`); }
+  }
+  all((k) => k.setState('LISTENING'));
+  await tick(2);   // let the longest gesture leave frame before speech starts
+
+  const cues = textToCues('okay, and what happened next');
+  all((k) => k.speak({ cues, clock }));
+  for (let i = 0; i < 12; i++) { await tick(0.12); check('speaking'); }
+  all((k) => k.stopSpeaking().setState('LISTENING'));
+  await tick(0.2); check('after speech');
+
+  return {
+    ok: problems.length === 0,
+    problems,
+    summary: `${rigs.length} rigs x ${STATE_NAMES.length} states, ${EMOTION_NAMES.length} emotions, `
+      + `${GAZE_NAMES.length} gazes, ${ACTION_IDS.length} semantic actions `
+      + `(framing asserted per avatar), plus a viseme track`,
+  };
+}
+
+/**
+ * A deterministic `advance` for `{manual: true}` avatars: fixed-dt stepping, no
+ * wall clock, no rAF. Same rigs and same seed give the same numbers every run,
+ * which is what makes a failure here reproducible rather than anecdotal.
+ */
+export function stepper(rigs, dt = 1 / 60) {
+  return (seconds) => {
+    for (let t = 0; t < seconds; t += dt) rigs.forEach((r) => r.avatar.step(dt));
+  };
+}
+
+/**
+ * Replace `Math.random` with a seeded LCG and return the undo.
+ *
+ * The sweep's assertions are invariants — they must hold for any draw — but a
+ * failure you cannot reproduce is a failure you cannot fix, and idle, gaze
+ * aversion and blink timing are all random. Call this *before* creating the
+ * avatars: constructors draw their first phases immediately.
+ */
+export function seedRandom(seed = 1) {
+  const original = Math.random;
+  let s = seed >>> 0 || 1;
+  Math.random = () => ((s = (s * 1664525 + 1013904223) >>> 0) / 4294967296);
+  return () => { Math.random = original; };
+}

package/src/emotions.js

@@ -8,9 +8,10 @@
  */
 
 export const EMOTIONS = {
-  neutral: {
-    mouthCornerL: 0.10, mouthCornerR: 0.10,
-  },
+  // Deliberately empty: REST is genuine availability, rather than a social
+  // smile baked into every state. Positive affect belongs to a response,
+  // greeting, success beat, or explicit warm/encouraging emotion.
+  neutral: {},
   warm: {
     mouthCornerL: 0.48, mouthCornerR: 0.48,
     // A real smile squints. Without this it reads as a mask.

package/src/face-core.js

@@ -65,6 +65,13 @@ export function faceApi(mount, svg, apply, theme) {
  *   shrugPivot   {x, y} the sternum
  *   yawPx        px of head travel at headYaw = 1
  *   pitchPx      px at headPitch = 1
+ *   pitch        optional corrective-pose contract for rigs that can nod:
+ *                `{ headLayers, neckLayer, hinge, headTravel, neckTravel,
+ *                   foreshorten, neckCompress, neckBase }`.
+ *                `headLayers` must be separate SVG groups for the skull and
+ *                its attached surface layers; `neckLayer` must be behind it.
+ *                This is intentionally a small group-level contract, not a
+ *                second set of authored paths per expression.
  *   pivot        {x, y} roll pivot — the base of the neck, not the chin:
  *                rotating about the chin swings the whole cranium sideways
  *                and reads as a puppet on a stick
@@ -128,17 +135,36 @@ export function poseTransforms(p, set, el, spec) {
 
   const yx = p.headYaw * spec.yawPx;
   const py = p.headPitch * spec.pitchPx;
+  const pitch = spec.pitch;
   for (const key of spec.layers) {
     const k = spec.parallax[key];
     const torso = spec.torsoLayers.includes(key);
     const roll = torso ? p.headRoll * ROLL_TORSO : p.headRoll * ROLL_HEAD;
+    const isPitchHead = !!pitch && pitch.headLayers.includes(key);
+    const isPitchNeck = !!pitch && pitch.neckLayer === key;
+    // A pitch-capable rig makes its skull, features and hair move together:
+    // their old parallax values still apply to yaw, but not to the vertical
+    // nod. That coherence is the point of separating them from the neck.
+    const pitchTravel = isPitchHead ? pitch.headTravel
+      : isPitchNeck ? pitch.neckTravel : k;
+    const pitchScale = isPitchHead
+      ? 1 - Math.max(0, p.headPitch) * pitch.foreshorten : 1;
+    const neckScale = isPitchNeck
+      ? 1 - Math.max(0, p.headPitch) * pitch.neckCompress : 1;
+    const pitchT = pitchScale !== 1
+      ? `translate(${f(pitch.hinge.x)} ${f(pitch.hinge.y)}) scale(1 ${f(pitchScale)}) translate(${f(-pitch.hinge.x)} ${f(-pitch.hinge.y)}) `
+      : '';
+    const neckT = neckScale !== 1
+      ? `translate(${f(pitch.neckBase.x)} ${f(pitch.neckBase.y)}) scale(1 ${f(neckScale)}) translate(${f(-pitch.neckBase.x)} ${f(-pitch.neckBase.y)}) `
+      : '';
     // Torso layers get their breath from the swell inside torsoT; head layers
     // get the matching lift, which is derived from the swell rather than tuned
     // separately — the neck rides on the chest it sits on.
     const bob = torso ? 0 : -neckLift;
     set(el[key], 'transform',
       leanT + (torso ? torsoT : '')
-      + `translate(${f(yx * k)} ${f(py * k + bob)}) rotate(${f(roll)} ${f(spec.pivot.x)} ${f(spec.pivot.y)})`);
+      + pitchT + neckT
+      + `translate(${f(yx * k)} ${f(py * pitchTravel + bob)}) rotate(${f(roll)} ${f(spec.pivot.x)} ${f(spec.pivot.y)})`);
   }
 }
 

package/src/face-myna.d.ts

@@ -0,0 +1,7 @@
+import type { AvatarMeta, Face, FaceFactory } from "./avatar.js";
+
+export const createFace: FaceFactory;
+export const META: AvatarMeta;
+/** Default palette. Passed as `createAvatar({ theme })`; see authoring-a-face.md. */
+export const THEME: Readonly<Record<string, string>>;
+export const myna: Face;