@voqalize/avatar 0.0.1

package/src/face-peep.js

@@ -0,0 +1,767 @@
+/**
+ * Avatar: "peep".
+ *
+ * A face for the shared rig — `createFace(mount, theme) -> { svg, apply,
+ * theme, destroy }`, consuming the same ~30-channel vector from `params.js`.
+ * Nothing above the renderer changes.
+ *
+ * Several notes below set a number against `blue-shirt`'s. That was the traced
+ * rig, retired on 2026-08-06 along with `classic` once stakeholders accepted
+ * only the line-art pair. The comparisons are kept because they are the reason
+ * these numbers are what they are — peep's were derived by converting from a
+ * rig 2.6x its size, and the conversion is where the bodies are buried. Both
+ * modules are in git history if a comparison needs checking.
+ *
+ * Where the art comes from
+ * ------------------------
+ * Hand-authored, in the manner of Open Peeps (openpeeps.com, CC0). Four
+ * concepts were drawn and this is the one that was picked: a taper fade with a
+ * spiked fringe, a polo, and the accent on the collar edge and two buttons.
+ * Character: male, urban Indian, late twenties to early thirties.
+ *
+ * The one construction fact that matters
+ * --------------------------------------
+ * OPEN PEEPS HAS NO STROKES. Taking the reference SVG apart, every part of a
+ * peep is two filled paths — a white background and a black ink — and there is
+ * not a single `stroke` attribute anywhere in it. That is why the lines swell
+ * along their length and come to a point at the ends, and it is the whole
+ * difference between "vector illustration" and "someone drew this". None of it
+ * is reachable with `stroke-width` + `stroke-linecap="round"`, which is a rope
+ * of constant thickness with a blob at each end.
+ *
+ * So this file carries a small variable-width stroke engine (`taper`,
+ * `taperRing`) and every line in the avatar is a filled outline generated by
+ * it. That is unusual for this codebase and it is deliberate: the other two
+ * avatars are painted forms with shading, this one is pure line, and the line
+ * quality IS the character.
+ *
+ * The second construction fact
+ * ----------------------------
+ * THE FACE IS SIX MARKS: two brows, two eyes, a nose, a mouth. No sclera, no
+ * iris, no lashes, no nostrils, no lower-lip line, no ear interior beyond one
+ * comma, no shading anywhere. An earlier pass had roughly five times that many
+ * marks and it read as a corporate mascot rather than a peep. Every mark added
+ * below this line has to earn its place against that.
+ *
+ * What the style costs the rig, honestly
+ * --------------------------------------
+ * 1. GAZE IS WEAKER THAN ON THE OTHER TWO AVATARS. There is no sclera, so
+ *    `pupilX/pupilY` cannot move an iris against a white field — the whole eye
+ *    bean translates instead. That is the correct reading of the style and it
+ *    is what real peeps do, but it carries less information per unit of travel.
+ *    Mitigated by giving the bean more travel than blue-shirt gives its iris
+ *    (11 units on a 25-wide eye, against blue-shirt's 19 on a 74-wide one —
+ *    as a share of frame width that is still less, and it took the DISTRACTED
+ *    state reading as eye contact to learn 7 was not enough) and by leaning on
+ *    gaze.js's head-follow, which is avatar-agnostic and does most of the work
+ *    anyway.
+ * 2. THE JAW DOES NOT DROP. The chin is part of the head's ink outline, and
+ *    translating a piece of that outline breaks the silhouette. Peeps do not
+ *    have moving jaws either. The cost is real — see MOUTH_APERTURE for how the
+ *    aperture is sized to stay off the chin without one.
+ * 3. ONE SHOULDER CANNOT RISE WITHOUT THE OTHER. The torso is a single filled
+ *    path, as it is on blue-shirt, so an asymmetric shrug is a small rotation
+ *    about the sternum. Same compromise, same reason.
+ *
+ * Arms
+ * ----
+ * There are none, and the armscye seam and sleeve hem below are GARMENT lines,
+ * not an arm. They exist because without them the bust reads as one undivided
+ * wedge of shirt. They are static geometry in the body layer and there is no
+ * parameter channel anywhere near them. See the note in params.js.
+ */
+
+import { clamp, lerp } from './params.js';
+import {
+  f, createFaceShell, faceApi, poseTransforms, pairedTeeth,
+} from './face-core.js';
+import { taper, taperRing, region, polyD, rng } from './line-art.js';
+
+export const THEME = {
+  // Paper, not white: a pure #fff field makes the ink look printed on glass,
+  // and every Open Peeps mock sits the figure on a warm off-white.
+  bg0: '#f6f3ee',
+  bg1: '#e8e2d8',
+  ink: '#1b1b1b',
+  paper: '#ffffff',
+  accent: '#f97415',
+  // The inside of an open mouth is the same ink as the outline. Anything
+  // lighter reads as a hole in the head rather than as a mouth, because in a
+  // pure line drawing there is no shading to say which is which.
+  mouthIn: '#1b1b1b',
+  teeth: '#ffffff',
+  // The only grey in the file. A warm one — a neutral grey tongue reads as a
+  // rendering artefact sitting inside the black.
+  tongue: '#8d7f79',
+};
+
+// Every colour the rig paints is a key here, and a host can override any of
+// them per instance. That is as far as theming goes on purpose. A value-swapped
+// dark variant was built and thrown away: inverting a two-value line drawing
+// turns the black hair white, which ages the character a couple of decades, and
+// fixing that means outlining the hair mass — a geometry change wearing a
+// colour change's clothes. The keys stay; the second palette does not.
+
+// ---------------------------------------------------------------------------
+// Frame.
+//
+// Native art space is 760x950; the viewBox is a portrait window onto it, by the
+// same rule blue-shirt's crop follows: about an eighth of a head of air above
+// the crown, a bit over half a head below the chin, head at ~61% of frame
+// height, mouth near the optical centre.
+//
+// The width is set by a constraint the other avatars do not have. This shirt is
+// WHITE on a near-white ground, so where blue-shirt could let background show
+// past the shoulder and lose nothing, here the shoulder line has to leave the
+// frame or the figure reads as a paper cut-out floating in the middle. 576 is
+// the widest window whose bottom corners are still inside the shirt.
+// ---------------------------------------------------------------------------
+const VB = { x: 92, y: 76, w: 576, h: 800 };
+
+/**
+ * The avatar descriptor: what a host or tool may know about this face without
+ * opening it. `viewBox` is the framing; `mouthCrop` frames the mouth for close
+ * inspection, e.g. the contact sheet's viseme-detail row.
+ */
+export const META = {
+  viewBox: { x: VB.x, y: VB.y, w: VB.w, h: VB.h },
+  mouthCrop: { x: 296, y: 434, w: 168, h: 98 },
+};
+
+// --- landmarks --------------------------------------------------------------
+// Vertical proportions are measured off the reference peep, not off anatomy.
+// The features sit LOW: with the hair mass counted, the eye line lands at 57%
+// of total height rather than the canonical 50%, and the whole cluster occupies
+// about a third of the head's width. Most of a peep's head is empty, and
+// spreading the features to fill it — which is what "correct" proportion pushes
+// you toward — is the single fastest way to lose the style.
+const CX = 380;
+const HEAD_TOP = 120;
+const CHIN_Y = 597;
+
+// Brows are given as the DRAWN control points, not as an inner/outer pair for a
+// generator to invent a curve between. That is a correction: a generator that
+// synthesised the arch from two endpoints and a peak offset produced a hard V in
+// every pose — an angry face at rest — because the shape a brow makes is not
+// recoverable from its endpoints. Poses deform these points; they never replace
+// them, so the drawing survives every channel.
+//
+// The left brow is longer and flatter and the right sits 3 units higher. Baked
+// in here, so the asymmetry survives every pose too.
+// Flatter than they were drawn, and lifted. At the concept's 19 units of arch
+// over a 79-unit span the inner ends sat low and close to the eye, and the
+// resting face read as annoyed — which is the last thing an attentive agent should
+// read as. 12 units of arch is still an arch; the difference is entirely in how
+// the neutral pose is received.
+const BROW_L = [[CX - 20, 347], [CX - 40, 340], [CX - 60, 336], [CX - 76, 337],
+                [CX - 86, 339], [CX - 94, 343], [CX - 99, 348]];
+const BROW_R = [[CX + 22, 344], [CX + 40, 337], [CX + 58, 333], [CX + 73, 335],
+                [CX + 83, 337], [CX + 90, 341], [CX + 95, 346]];
+const EYE = { y: 386, dx: 55, rx: 14, ry: 16.5 };
+const NOSE_TOP = 402;
+const MOUTH = { cx: CX, cy: 488 };
+
+// How far the aperture may open, measured as VISIBLE DARK at mouthOpen = 1 —
+// the lip band sits outside this and adds another 11 units of ink around it.
+// Bounded by the chin, not by taste: there is no jaw drop in this rig (see the
+// header), so a fully open mouth has to fit in the lower face that is already
+// there. At 38 the dark ends at y=517 and the lower lip at about y=523, leaving
+// roughly a chin's worth below it, which is what stops a wide "ah" from reading
+// as a hole in the jaw.
+const MOUTH_APERTURE = 38;
+
+// The variable-width stroke engine lives in line-art.js — `taper`, `taperRing`,
+// `region` and friends were authored here and extracted verbatim once a second
+// line-art character needed them. The width PROFILES stay per-character.
+
+// ---------------------------------------------------------------------------
+// Static art: head
+//
+// The jaw is three segments — a near-vertical RAMUS off the ear, a corner at
+// the GONION, then the BODY running forward to a narrow chin PAD. One unbroken
+// curve from ear to ear is an egg, and an egg has no age and no sex. This is
+// the same finding both other avatars' headers record, arrived at a third time;
+// treat it as a rule.
+//
+// The right side is a few units wider than the left and the chin sits slightly
+// off the midline. Not sloppiness — a mirror-symmetric head is the loudest
+// available signal that no hand was involved.
+// ---------------------------------------------------------------------------
+const HEAD = [
+  [CX, HEAD_TOP],
+  [462, 119], [536, 180], [540, 272],
+  [543, 330], [539, 384], [534, 430],
+  [531, 470], [526, 496], [509, 524],
+  [491, 552], [458, 578], [428, 590],
+  [409, 597], [352, 596], [333, 587],
+  [305, 574], [277, 552], [259, 522],
+  [242, 494], [237, 470], [240, 430],
+  [233, 384], [227, 330], [230, 272],
+  [234, 178], [300, 117], [CX, HEAD_TOP],
+];
+// Heavy along the jaw, nearly nothing at the crown. The crown is under the hair
+// mass, and ink drawn where it will be covered only ever shows up as a dark
+// fringe along the hairline.
+const HEAD_W = [4, 8, 13, 16, 17, 15, 11.5, 8, 5, 4];
+
+const EAR_L = [[236, 366], [208, 352], [186, 380], [192, 418], [198, 450], [224, 462], [239, 452]];
+const EAR_R = [[537, 372], [563, 360], [583, 388], [576, 424], [570, 452], [546, 462], [533, 452]];
+const EAR_L_IN = [[219, 386], [206, 396], [204, 418], [212, 434]];
+const EAR_R_IN = [[551, 392], [563, 402], [564, 422], [557, 437]];
+
+/**
+ * Neck.
+ *
+ * Fused into the head layer and run down to y=790 — well past the shirt's
+ * neckline — for exactly the reason blue-shirt's header gives: a neck that is
+ * its own layer at its own parallax slides out from behind the collar under
+ * yaw, and a bare block wider than the neck draws a hard-edged box across the
+ * throat. The fill's side edges are the same curve as the ink lines, so the
+ * lines sit on their own fill's edge rather than near it.
+ *
+ * Short, and that is a correction: the first pass ran the neck to 100 units and
+ * every concept on the sheet read as a giraffe. 48 units show.
+ */
+// The neck is a truncated cone, not a column. It starts about as wide as the
+// chin pad and widens into the trapezius. Drawn with parallel sides — which is
+// where it started, at 156 units against a 316-wide head — it read as a tree
+// trunk, and no amount of work on the head above it fixed that.
+const NECK_FILL =
+  'M334 536C324 590 316 640 314 700L314 790L446 790L446 700C444 640 436 590 426 536Z';
+// Both lines run to 750, well past any neckline, for the same reason the fill
+// does: the neck is in the `head` layer and the shirt is in `body`, so a shrug
+// slides the collar down 30 units while the neck stays put. Ending these where
+// the resting collar happens to be leaves two ink lines stopping in mid-air
+// above it. The shirt is painted after the head, so the overshoot costs nothing.
+const NECK_L = [[334, 552], [327, 600], [321, 662], [318, 750]];
+const NECK_R = [[426, 548], [433, 598], [439, 660], [442, 750]];
+
+/**
+ * The underside of the jaw. Drawn on the NECK, below the chin line — put on the
+ * chin itself, which is where it first went, the identical mark reads as a
+ * second chin.
+ */
+const JAW_UNDER = [[329, 584], [348, 610], [414, 612], [435, 582]];
+
+// ---------------------------------------------------------------------------
+// Static art: hair — a taper fade with a spiked fringe.
+//
+// One filled black mass, no outline, because the mass is already ink. It is a
+// single path: the silhouette left-to-right over the crown, then the hairline
+// right-to-left back, so the forehead is a hole and what is left down each side
+// is the hair on the sides of the skull.
+//
+// That continuity is the whole trick. The first version drew the sideburns as
+// their own shapes beside the mass; separate blocks abut the mass rather than
+// being continuous with it, and at any weight the join shows as two floating
+// rectangles by the ears.
+// ---------------------------------------------------------------------------
+
+/**
+ * The spiked fringe, as a zigzag polyline.
+ *
+ * Both the tooth depth AND the tooth pitch are jittered. Even pitch is a saw
+ * blade; it is the uneven pitch that reads as hair.
+ */
+function spikes(x0, x1, n, baseAt, depth, seed) {
+  const r = rng(seed);
+  const pts = [];
+  for (let i = 0; i <= n; i++) {
+    const j = i === 0 || i === n ? 0 : (r() - 0.5) * ((x1 - x0) / n) * 0.7;
+    const x = x0 + ((x1 - x0) * i) / n + j;
+    pts.push([x, baseAt(x) + (i % 2 ? depth * (0.4 + 1.0 * r()) : 0)]);
+  }
+  return polyD(pts, 'L');
+}
+
+const HAIR_D = (() => {
+  const base = (x) => 250 + 0.0009 * (x - 380) * (x - 380);
+  return (
+    'M228 398' +
+    'C220 356 218 306 226 262' +
+    'C233 178 302 118 380 121' +
+    'C460 117 532 178 538 264' +
+    'C544 308 542 354 536 398' +
+    // The sideburn ends on a diagonal: the inner boundary comes back UP past
+    // where the outer one stopped, so the strip closes to a wedge. A flat cut
+    // is the one shape a razor never leaves.
+    'L521 374' +
+    'C524 340 524 304 518 272' +
+    spikes(508, 252, 13, base, 32, 7) +
+    'C246 304 246 340 249 374Z'
+  );
+})();
+
+/** The tuft in front of the ear. Without it the fade reads as a swim cap. */
+const HAIR_TUFT = [[236, 372], [227, 388], [229, 410], [240, 414],
+                   [247, 414], [248, 396], [245, 376]];
+
+// ---------------------------------------------------------------------------
+// Static art: torso
+//
+// The armscye seam and the short-sleeve hem are what separate arm from torso.
+// Not mirrored — the left seam sits further out and the right runs straighter,
+// which is what a shirt on a real torso does.
+// ---------------------------------------------------------------------------
+// One continuous convex curve from hem to neck is a balloon, whatever its
+// radius — that was the first pass, and it read as a figure wearing a beanbag.
+// A shoulder has two distinct runs meeting at the acromion: the outer arm edge,
+// which is nearly vertical low down and turns hard, and the trapezius shelf,
+// which leaves that corner almost horizontal before rising into the neck. The
+// slope break at points 3 and 12 is the whole difference.
+const TORSO = [
+  [46, 950],
+  [48, 862], [92, 754], [176, 726],
+  [236, 720], [280, 692], [316, 650],
+  [330, 684], [430, 686], [446, 646],
+  [482, 688], [528, 716], [582, 722],
+  [664, 750], [712, 860], [714, 950],
+];
+const TORSO_W = [10, 11, 8.5, 8, 11, 10];
+
+const SEAM_L = [[178, 728], [158, 786], [164, 866], [180, 950]];
+const SEAM_R = [[580, 724], [601, 782], [597, 862], [584, 950]];
+const HEM_L = [[57, 884], [98, 918], [146, 914], [176, 878]];
+const HEM_R = [[703, 886], [664, 920], [622, 916], [596, 880]];
+
+/**
+ * Shirt creases. Three marks, all on one side.
+ *
+ * On one side deliberately: a symmetric pair of creases reads as a printed
+ * pattern rather than as fabric. Cloth folds where the body pulls it, and a
+ * body does not pull evenly.
+ */
+const CREASES = [
+  { p: [[300, 726], [305, 754], [307, 780], [303, 802]], w: [2, 7, 2] },
+  { p: [[326, 740], [331, 766], [332, 788], [329, 806]], w: [2, 5.5, 2] },
+  { p: [[336, 872], [345, 898], [352, 918], [349, 936]], w: [2, 6, 2] },
+];
+
+// Polo collar. The two blades are different shapes and set at different angles;
+// in the reference that one asymmetry does more for the hand-drawn read than
+// any amount of wobble along the lines.
+const BLADE_L = [[314, 646], [322, 678], [336, 702], [353, 718],
+                 [359, 702], [366, 686], [371, 668]];
+const BLADE_R = [[448, 644], [442, 670], [432, 690], [417, 704],
+                 [411, 692], [405, 680], [401, 666]];
+const TRIM_L = [[322, 654], [329, 680], [341, 700], [354, 712]];
+const TRIM_R = [[441, 652], [436, 674], [428, 690], [416, 700]];
+const PLACKET = [[387, 700], [390, 734], [385, 768], [389, 800]];
+
+// ---------------------------------------------------------------------------
+// Layers.
+//
+// Four, the same set blue-shirt runs. Draw order is head, body, features, hair:
+// the shirt has to be over the neck, and the fringe has to be over the brows.
+// ---------------------------------------------------------------------------
+const PARALLAX = { head: 1.0, body: 0.1, features: 1.22, hair: 1.12 };
+const LAYERS = ['head', 'body', 'features', 'hair'];
+
+// Roll pivots at the base of the neck. About the chin, the cranium swings
+// sideways and the whole thing reads as a puppet on a stick.
+const PIVOT = { x: CX, y: 700 };
+
+// Pose mechanics for face-core's poseTransforms, in this rig's own art units
+// (native 760x950 — about 2.6x smaller than blue-shirt's, hence units: 1 and
+// its own literals; see the art-unit rules in docs/contract-avatar.md).
+//
+// The shrug tilt is 1.6 degrees, not blue-shirt's 1.9. This collar is a
+// shallow polo opening over a white neck on a white shirt, so there is no
+// tonal difference to hide a mismatch: past about 1.6 the neck's ink lines
+// swing out from behind the blades and read as two stray marks on the chest.
+// The 30-unit lift is the S-conversion lesson in the flesh: carried over
+// unconverted from blue-shirt the shoulders moved 1.6% of frame height and
+// the channel that params.js calls the single most legible bid for the floor
+// did not read. Degrees carry over unconverted; travels do not.
+const POSE = {
+  leanTravel: 23, leanPivot: { x: PIVOT.x, y: 560 },
+  shrugLift: 30, shrugTiltDeg: 1.6, shrugPivot: { x: PIVOT.x, y: 800 },
+  yawPx: 28, pitchPx: 17,
+  pivot: PIVOT,
+  // 1.2% at full inhale. Chest circumference changes ~2-3% in quiet
+  // breathing, so a little over half that in linear scale is the calm end of
+  // real — and it renders as the shoulder line rising 3 units and the chest
+  // widening 4 either side, against a hem that stays where it is. The
+  // predecessor (a 4.2-unit rigid slide of the whole shirt) moved more pixels
+  // and read as less alive, which is the entire argument for the swell.
+  breathSwell: 0.012, swellPivot: { x: CX, y: 950 },
+  // Lateral trunk travel. 16 units is ~2% of the frame width — the trunk
+  // re-settling is meant to be noticed peripherally and never watched.
+  turnPx: 16,
+  layers: LAYERS, parallax: PARALLAX,
+  torsoLayers: ['body'],
+  units: 1,
+};
+
+// ---------------------------------------------------------------------------
+// Generators: mouth
+//
+// The mouth is ONE closed contour used three ways — filled with ink for the
+// interior, outlined with a tapered ring for the lips, and used as the clip for
+// teeth and tongue. That is the whole model, and it is why the closed mouth
+// needs no special case: at rest the contour is a degenerate lens, the fill
+// collapses to nothing, and what is left is the ring — a tapered line, thick in
+// the middle and pointed at the corners, which is exactly the rest mouth the
+// concept art was drawn with.
+// ---------------------------------------------------------------------------
+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 = (26 + clamp(p.mouthWidth) * 32) * (1 - 0.36 * round);
+
+  // Width profile around the ring: s=0 is the left corner, 0.25 the middle of
+  // the upper lip, 0.5 the right corner, 0.75 the middle of the lower. Pointed
+  // at the corners, heavy in the middles. `mouthPress` thins the whole thing —
+  // pressed lips are thin lips — and `mouthTuck` fattens the lower one, because
+  // a lip drawn in under the teeth is a compressed lip.
+  const t = 1 - 0.4 * clamp(p.mouthPress);
+  const profile = [2.5 * t, 10.5 * t, 3 * t, 11.5 * t * (1 + 0.35 * tuck), 2.5 * t];
+  const halfUp = profile[1] / 2;
+  const halfLo = profile[3] / 2;
+
+  // `mouthOpen` is the height of the DARK, not the separation of the two
+  // centrelines. Those are not the same thing and the difference is the whole
+  // lip band — about 11 units here — so with the naive reading the mouth stayed
+  // shut until mouthOpen passed 0.25. Two of the nine visemes live below that:
+  // B at 0.16 and G at 0.20, both of which ask for upper teeth. Neither could
+  // ever show them, and B, G and X all collapsed onto the same drawn line.
+  const h = open * MOUTH_APERTURE;
+
+  // ...but only once the lips have actually parted. Compensating at open = 0
+  // would prise the two centrelines apart by the lip thickness and the resting
+  // mouth would be a fat lens instead of the single tapered stroke the whole
+  // face is built around. The ramp buys the compensation in over the first
+  // fifth of the channel, which is also roughly where real lips separate.
+  const k = clamp(open / 0.18);
+
+  // The corners rise while the middle stays put. That is a smile; blue-shirt's
+  // mouth translates the whole aperture with the corners instead, which works
+  // there because its cupid's bow and modulated seam carry the expression. This
+  // face has no such detail to fall back on — the bow IS the expression, so it
+  // has to be geometric.
+  //
+  // The constant 6 is resting pleasantness. An attentive agent's neutral is not a
+  // flat line, and at mouthCorner's REST value of 0.1 the corner term alone
+  // gives 2.4 units of bow across an 84-wide mouth, which is nothing.
+  const yL = cy - 6 - p.mouthCornerL * 24;
+  const yR = cy - 6 - p.mouthCornerR * 24;
+
+  // The aperture opens DOWNWARD, 3:1. The upper lip is anchored to the maxilla
+  // and barely moves; the lower rides the jaw. Splitting it evenly is what makes
+  // an open mouth read as a cat's.
+  const apTop = cy - h * 0.25;
+  let apBot = cy + h * 0.75;
+  // For F/V the lower lip rides up under the upper teeth, closing the aperture
+  // from below rather than from above. The floor matters more than the lift: an
+  // F that shuts completely is an M, and the one thing that has to survive is
+  // the sliver of upper teeth resting on the lip.
+  if (tuck > 0) apBot = Math.max(apTop + 6, apBot - tuck * (h * 0.6 + 4));
+
+  // Solve back from where the aperture must be to where the control points go.
+  // A cubic reaches only 3/4 of the way from its endpoints to its controls, and
+  // both cubics here share the two corner endpoints, so the curve midpoint is
+  // cornerMid + 0.75 * ctrlY. Inverting that is the only reason this is not
+  // simply an offset.
+  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],
+  ];
+
+  // Where the DARK actually is. Below the compensation ramp these come out
+  // crossed — innerBot above innerTop — which is the correct answer for a shut
+  // mouth and is what teethPath and the tongue test against. Recomputed rather
+  // than assumed equal to apTop/apBot, because the clamp above and the ramp
+  // both mean the aperture asked for is not always the aperture drawn.
+  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 };
+}
+
+/**
+ * The upper teeth as a dental arch rather than a bar.
+ *
+ * The incisal edge follows the smile arc; a dead-straight one is most of what
+ * makes a white rect read as a strip of paper in the mouth. Deliberately no
+ * per-tooth lines: at avatar size they are sub-pixel, and a single midline tick
+ * is exactly what makes a cheap avatar look like it has a gap tooth. The top
+ * runs well above the lip and is cut off by the aperture clip, so the strip's
+ * upper boundary is always the lip's own inner contour.
+ */
+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);
+  // Normally never more than half the aperture: teeth that meet across the gap
+  // close the mouth optically no matter how far mouthOpen has driven the
+  // contour. F/V is the exception and the reason the cap is not a constant —
+  // there the upper teeth are literally resting ON the lower lip, so the dark
+  // is a rim rather than a cavity, and holding G to the same half-and-half
+  // split as B left the two letters drawing the same slit.
+  const cap = lower ? 0.5 : 0.5 + 0.35 * m.tuck;
+  const th = Math.min(amt * (lower ? 13 : 20), gap * cap);
+
+  if (lower) {
+    // The strip runs off past the lip on the far side so its outer boundary is
+    // always the clip, never an edge of its own.
+    const base = m.innerBot + 8;
+    const edge = m.innerBot - th; // deepest point, at the midline
+    const end = m.innerBot - th * 0.35; // shallowest, at the corners
+    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`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Generators: eyes
+//
+// A solid ink bean, built as two cubics meeting at pointed corners: an upper
+// lid arc and a lower lid arc. Not an <ellipse> — an ellipse cannot blink, and
+// it cannot have corners.
+//
+// Blinking is the top edge descending toward the bottom one. At full closure
+// both edges end up ABOVE the corners, so the shape is a thin crescent bowing
+// upward: the relaxed closed lid every peep is drawn with. Collapsing it to a
+// straight line instead reads as the eyes being deleted for a frame.
+// ---------------------------------------------------------------------------
+function eyePath(cx, cy, lid, squint, tiltDeg) {
+  const L = clamp(lid);
+  // 1.05 rather than 0.75 because a cubic reaches only ~0.75 of its control
+  // offset at the midpoint; this is what makes the open bean EYE.ry tall. It
+  // was 1.4, which drew a bean noticeably taller than it was wide — read as a
+  // stare rather than as a peep, whose eyes sit at or below square.
+  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`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Generators: brows
+//
+// The heaviest marks on the face, and the ones doing the most affective work,
+// so they are generated rather than transformed: `browAngle` has to pivot the
+// tail without moving the head of the brow, which a rotation about any single
+// point cannot do.
+//
+// The left brow is longer and flatter and the right sits 3 units higher. That
+// asymmetry is baked into the control points, so it survives every pose.
+// ---------------------------------------------------------------------------
+function browPath(pts, raise, angle, inner) {
+  const n = pts.length - 1;
+  const out = pts.map(([x, y], i) => {
+    // u runs 0 at the inner end to 1 at the outer, so `inner` and `angle` each
+    // pivot their own end and fade out across the brow rather than translating
+    // the whole mark. That is the only reason these are separate channels.
+    const u = i / n;
+    return [x, y - raise * 15 - inner * 11 * (1 - u) - angle * 12 * u];
+  });
+  return taper(out, [3.5, 17, 8], 6);
+}
+
+// ---------------------------------------------------------------------------
+// Static markup
+// ---------------------------------------------------------------------------
+const HEAD_FILL = region(HEAD);
+const HEAD_RING = taperRing(HEAD, HEAD_W, 10);
+const EAR_L_FILL = region(EAR_L), EAR_R_FILL = region(EAR_R);
+const EAR_L_RING = taper(EAR_L, [4, 7.5, 4]), EAR_R_RING = taper(EAR_R, [4, 7, 4]);
+
+/** The nose: one mark. Down the bridge, then a hook at the base. A straight
+ *  vertical tick is a scratch; the hook is the entire nose. */
+const NOSE_D = taper(
+  [[CX - 5, NOSE_TOP], [CX - 14, 422], [CX - 20, 441], [CX - 13, 452],
+   [CX - 5, 461], [CX + 11, 459], [CX + 18, 448]],
+  [2.5, 9.5, 3.5]
+);
+
+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, ears and neck. Ears go under the head fill so the loop's inner half
+       is covered and only the rim reads. -->
+  <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="${EAR_L_FILL}" fill="${t.paper}"/>
+    <path d="${EAR_R_FILL}" fill="${t.paper}"/>
+    ${ink(EAR_L_RING)}
+    ${ink(EAR_R_RING)}
+    <path d="${HEAD_FILL}" fill="${t.paper}"/>
+    ${ink(HEAD_RING)}
+    ${ink(taper(EAR_L_IN, [2.5, 5, 2.5]))}
+    ${ink(taper(EAR_R_IN, [2.5, 4.5, 2.5]))}
+    ${ink(taper(JAW_UNDER, [2, 5.5, 2]))}
+    <!-- Hair underlay: the same mass, locked to the skull at head parallax.
+         The hair layer runs faster, so under yaw it slides a few units across
+         the cranium; the mass abuts the head outline with no overlap margin, so
+         that slide would otherwise open a bright white sliver of scalp along the
+         leading edge. On a white-on-white avatar that sliver is far more visible
+         than blue-shirt's equivalent. Cheap insurance; do not remove it. -->
+    <path d="${HAIR_D}" fill="${t.ink}"/>
+  </g>
+
+  <!-- shirt: silhouette, arm separation, creases, collar -->
+  <g id="${id}-body">
+    <path d="${region(TORSO)}" fill="${t.paper}"/>
+    ${ink(taper(TORSO, TORSO_W))}
+    ${ink(taper(SEAM_L, [7, 8, 6]))}
+    ${ink(taper(SEAM_R, [7, 8, 6]))}
+    ${ink(taper(HEM_L, [4, 8, 4]))}
+    ${ink(taper(HEM_R, [4, 8, 4]))}
+    ${CREASES.map((c) => ink(taper(c.p, c.w))).join('\n    ')}
+    <path d="${region(BLADE_L)}" fill="${t.paper}"/>
+    <path d="${region(BLADE_R)}" fill="${t.paper}"/>
+    ${ink(taper(BLADE_L, [5, 9, 5]))}
+    ${ink(taper(BLADE_R, [5, 8, 4.5]))}
+    <path d="${taper(TRIM_L, [3, 7, 3])}" fill="${t.accent}"/>
+    <path d="${taper(TRIM_R, [3, 6, 3])}" fill="${t.accent}"/>
+    ${ink(taper(PLACKET, [4, 5, 3.5]))}
+    <circle cx="391" cy="722" r="7" fill="${t.accent}"/>
+    <circle cx="387" cy="766" r="6.5" fill="${t.accent}"/>
+  </g>
+
+  <!-- features: six marks and nothing else -->
+  <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}"/>
+    <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}"/>
+    <path d="${region(HAIR_TUFT)}" fill="${t.ink}"/>
+  </g>
+</svg>`;
+}
+
+// ---------------------------------------------------------------------------
+// Renderer
+//
+// The third data point for the finding that `apply` is not per-avatar — which
+// produced face-core.js, now the owner of the pose mechanics and the shared
+// teeth fragment. This rig keeps its own eye block (a bean, not an iris under
+// lids), its point-list brows, and its contour mouth.
+// ---------------------------------------------------------------------------
+let uid = 0;
+
+export function createFace(mount, theme = {}) {
+  const t = Object.assign({}, THEME, theme);
+  const id = `peep${++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 -------------------------------------------------------------
+    // With no sclera the whole bean travels; see the header for what that costs
+    // and why it is still the right call. 7 units on a 25-wide eye is a lot of
+    // relative travel — more than blue-shirt's iris gets — and it has to be, or
+    // a gaze target does not read at all.
+    set(el.eyes, 'transform', `translate(${f(p.pupilX * 11)} ${f(p.pupilY * 8)})`);
+
+    // The lid follows vertical gaze downward only. Looking up genuinely does
+    // widen the aperture, so there is nothing to add on that side.
+    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, -9));
+    set(el.eyeR, 'd', eyePath(CX + EYE.dx, EYE.y - 1, p.lidR + lidFollow, p.squintR, 8));
+
+    // --- brows ------------------------------------------------------------
+    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));
+
+    // --- mouth ------------------------------------------------------------
+    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));
+
+    // Fade the interior in as the lips part. At rest the contour is degenerate
+    // and fills to nothing anyway, but the first few percent of opening produce
+    // a sliver narrower than the lip ring, and drawing it makes the closed mouth
+    // flicker between two blacks as a viseme track passes through.
+    // Keyed off the gap that is actually drawn, not off mouthOpen. Ramping on
+    // the requested aperture leaves the interior part-transparent wherever the
+    // lips have parted but the channel is still low, and a half-opaque interior
+    // renders as GREY — which on a face with exactly two values reads as a
+    // rendering fault. F, at mouthOpen 0.22, was a grey hole.
+    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);
+}