@voqalize/avatar 0.2.2 → 0.4.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';