@voqalize/avatar 0.4.4 → 0.5.1

package/src/face-peep.js

@@ -1,925 +0,0 @@
-/**
- * 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 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.
- *
- * The eye takes three paths to draw (lid line, aperture, iris) and is still one
- * mark: the rule counts what you see, not what renders it.
- *
- * Two changes on 2026-08-27
- * -------------------------
- * Both came from building the Canvas2D professional identities and then
- * looking at this one next to them. They were prototyped as a separate face and
- * folded back in once they held up, so `git log` for that day is the review.
- *
- * 1. THE HEAD WAS DRAWN TALL AND NARROW — a 316-unit-wide head inside a
- *    908-unit-wide 4:3 frame, filling barely a third of the tile, where the
- *    canvas avatars were calibrated at call-tile size from the start and read
- *    fuller. Rather than redraw every path, the whole head cluster (skull,
- *    ears, hair, features) is wrapped in one static anisotropic `scale()`,
- *    pivoted at the chin so the jaw stays where the neck expects it. Every
- *    landmark constant below still describes the original art space; RESHAPE is
- *    the only new geometry. The head outline was thinned to match — a line that
- *    reads at the old size is a rope at the new one.
- * 2. THE EYE WAS A SOLID INK BEAN and gaze read only as the whole bean
- *    translating. It is now that bean opened out: the bean is the lid line, a
- *    paper almond sits inside it, and an ink iris inside that carries the gaze
- *    while the lid line holds still. See the eyes section — it took two wrong
- *    passes and a wider EYE.rx, and the reasons are recorded there because they
- *    are not recoverable from the numbers.
- *
- * What the style costs the rig, honestly
- * --------------------------------------
- * 1. 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.
- * 2. 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';
-import { viewBoxForHead } from './camera.js';
-
-export const THEME = {
-  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.
-
-// --- reshape ----------------------------------------------------------------
-// One static, non-animated transform, applied to the head cluster only (skull,
-// ears, hair, features — never neck or body). Pivoted at CHIN_Y so the chin's
-// own silhouette point does not move: everything above it is pulled toward that
-// point, everything at or below it is left exactly as drawn, so the jaw-to-
-// collar join needs no rework.
-//
-// SX widens, SY shortens. Because the camera (viewBoxForHead) derives frame
-// width from frame height at a fixed 4:3, shortening the head's vertical span
-// shrinks the WHOLE frame around it — that is what "broader" means here: not a
-// wider aspect (every shipped avatar shares one 4:3 camera, on purpose; see
-// docs/authoring-a-face.md § The camera), but a head that fills more of a
-// tighter crop, further widened on top of that by SX.
-const CX = 380;
-const CHIN_Y = 597;
-const RESHAPE_SX = 1.10;
-const RESHAPE_SY = 0.88;
-const RESHAPE = `translate(${CX} ${CHIN_Y}) scale(${RESHAPE_SX} ${RESHAPE_SY}) translate(${-CX} ${-CHIN_Y})`;
-
-// The camera follows the visible hair silhouette, not the skull hidden under
-// it. Keeping these as native landmarks means reframing never touches a path.
-// crownY is the reshaped crown: CHIN_Y + (117 − CHIN_Y) × RESHAPE_SY, worked
-// out by hand because the camera reads landmarks, not the transform above it.
-const FRAME = { centerX: CX, crownY: 177, chinY: CHIN_Y };
-const VB = viewBoxForHead(FRAME);
-
-/**
- * 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 },
-  // The original crop (296, 434, 168, 98) with its corners carried through
-  // RESHAPE. A camera change does not move a path, but the reshape is geometry
-  // rather than camera, so the inspection crop has to follow it.
-  mouthCrop: { x: 288, y: 454, w: 185, h: 86 },
-};
-
-// --- 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.
-//
-// These are the NATIVE art space and RESHAPE never enters them: it is a wrapper
-// on the rendered group, so `apply()` and every number below still mean what
-// they meant before it existed.
-const HEAD_TOP = 120;
-
-// 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]];
-// rx was 14 — the bean was very nearly round — until the eye was opened out.
-// You cannot cut an almond aperture from a round bean without making the lid
-// line absurdly heavy, and a round aperture is exactly what read as a target.
-// Widening the bean was the unlock; see the eyes section.
-const EYE = { y: 386, dx: 55, rx: 16.5, 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.
-//
-// Scaled to ~0.65 of the original profile ([4, 8, 13, 16, 17, 15, 11.5, 8, 5,
-// 4]) when RESHAPE landed: the same taper shape, but a line rather than a rope
-// once the head is drawn broader and the frame tighter around it.
-const HEAD_W = [3, 5, 8.5, 10.5, 11, 10, 7.5, 5, 3.5, 3];
-
-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 = { neck: 1.0, skull: 1.0, body: 0.1, features: 1.22, hair: 1.12 };
-const LAYERS = ['neck', 'skull', '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/authoring-a-face.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,
-  // The optional pitch contract is the smallest useful upgrade for a face
-  // whose acknowledgements need to read as nods: a neck behind an independently
-  // movable skull/face/hair set, plus six calibration numbers. There are no
-  // nod-specific paths here — existing art remains the source of truth.
-  pitch: {
-    headLayers: ['skull', 'features', 'hair'], neckLayer: 'neck',
-    hinge: { x: CX, y: 620 }, neckBase: { x: CX, y: 720 },
-    headTravel: 1.0, neckTravel: 0.22,
-    foreshorten: 0.040, neckCompress: 0.034,
-  },
-  // 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.008, 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.
-  //
-  // Keep a trace of organic bow at rest, but not a social smile. Warmth is a
-  // context-driven expression layered by the behavior director, not the
-  // permanent default while the avatar is merely available.
-  const yL = cy - 1.5 - p.mouthCornerL * 24;
-  const yR = cy - 1.5 - 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 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.
-//
-// The bean used to be the whole eye — one solid mark, translated bodily for
-// gaze. It is now the LID LINE, with a paper almond cut out of it and an ink
-// iris inside that. Two passes at this were wrong, and the shape of the
-// mistakes is the reason the numbers below are so specific:
-//
-//   1. A paper disc drawn straight onto the ink bean — a light hole in a dark
-//      shape, backwards from how an eye reads.
-//   2. Paper disc, then a small ink disc on top. Right order, wrong
-//      proportions: paper visible all the way around a small central pupil is
-//      three concentric rings, which is a target, and on a face it is the
-//      classic startle cue — sclera showing above and below the iris. Every
-//      frame, both eyes, so the whole rig read as alarmed.
-//
-// So the aperture is deliberately WIDER THAN IT IS TALL while the bean is not,
-// and the iris is sized to fill its height rather than float inside it. Paper
-// then survives only at the two corners, which is what makes gaze read: a small
-// iris shift kills one corner and doubles the other — a far larger signal than
-// the same shift of a disc in open space, and the reason travel could come
-// DOWN (11 × 8 for the whole bean, against 4.5 × 2.2 for the iris) while the
-// reading got stronger.
-// ---------------------------------------------------------------------------
-
-// A cubic whose two controls share a y reaches only 3/4 of the way to it.
-// Everything below works in DRAWN extents and divides that back out, so an
-// inset of n units is n units on screen. The second pass's inset was a
-// proportional one and could not be: scaled about the eye centre it inverts the
-// moment a closing lid carries the bean's lower edge above that centre, and it
-// leaked paper out through a shut eye.
-const BULGE = 0.75;
-
-/** Two cubics between (cx±rx, cyMid), bulging to yTop and yBot; tilt about cy. */
-function lensPath(cx, cy, g, tiltDeg) {
-  if (!g) return '';
-  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)}`;
-  };
-  const ctlTop = g.cyMid + (g.yTop - g.cyMid) / BULGE;
-  const ctlBot = g.cyMid + (g.yBot - g.cyMid) / BULGE;
-  return (
-    `M${R(cx - g.rx, g.cyMid)}` +
-    `C${R(cx - g.rx * 0.5, ctlTop)} ${R(cx + g.rx * 0.5, ctlTop)} ${R(cx + g.rx, g.cyMid)}` +
-    `C${R(cx + g.rx * 0.5, ctlBot)} ${R(cx - g.rx * 0.5, ctlBot)} ${R(cx - g.rx, g.cyMid)}Z`
-  );
-}
-
-/** The lid silhouette, in drawn extents. */
-function eyeGeom(cy, lid, squint) {
-  const L = clamp(lid);
-  // 1.05 rather than 0.75 because of BULGE; 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 ctlTop = lerp(cy - EYE.ry * 1.05, cy - EYE.ry * 0.42, L);
-  const ctlBot = lerp(cy + EYE.ry * 1.05, cy - EYE.ry * 0.05, L) - clamp(squint) * EYE.ry * 0.7;
-  return {
-    cyMid: cy,
-    rx: EYE.rx,
-    yTop: cy + BULGE * (ctlTop - cy),
-    yBot: cy + BULGE * (ctlBot - cy),
-  };
-}
-
-// The lid line, as constant distances. Heavier above than below: an upper lid
-// carries the lashes and reads as the eye's weight, and a lower line as heavy
-// makes a doll. LASH_X is the corner, where the line has to stay thin or the
-// almond loses its points and rounds back into the target shape.
-const LASH_X = 3.0;
-const LASH_TOP = 5.5;
-const LASH_BOT = 4.5;
-
-/** The paper almond inside the lid line, or null once the lid has shut on it. */
-function apertureGeom(g) {
-  const yTop = g.yTop + LASH_TOP;
-  const yBot = g.yBot - LASH_BOT;
-  const rx = g.rx - LASH_X;
-  if (yBot - yTop < 0.5 || rx < 0.5) return null;
-  return { cyMid: (yTop + yBot) / 2, rx, yTop, yBot };
-}
-
-// Sized to fill the resting aperture's height (26 − 5.5 − 4.5 = 16 drawn units)
-// rather than float inside it, so both lids crop it and the paper survives only
-// as two corner slivers.
-const IRIS_R = 8.0;
-
-// Travel, native units. x is roughly one corner's worth of paper: at either
-// extreme one sliver closes and the other doubles, which is the whole gaze
-// signal.
-const IRIS_TRAVEL = { x: 4.5, y: 2.2 };
-
-// ---------------------------------------------------------------------------
-// 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>
-    <clipPath id="${id}-clipMouth"><path id="${id}-clipMouthP" d=""/></clipPath>
-    <clipPath id="${id}-clipEyeL"><path id="${id}-clipEyeLP" d=""/></clipPath>
-    <clipPath id="${id}-clipEyeR"><path id="${id}-clipEyeRP" d=""/></clipPath>
-  </defs>
-
-  <!-- The neck stays behind the skull. This explicit split is what makes a nod
-       a nod: it lets one shorten the neck and pivot the head surface instead of
-       treating the entire portrait as one vertically sliding layer. -->
-  <g id="${id}-neck">
-    <path d="${NECK_FILL}" fill="${t.paper}"/>
-    ${ink(taper(NECK_L, [3, 8, 6]))}
-    ${ink(taper(NECK_R, [3, 8, 6]))}
-  </g>
-
-  <!-- head and ears. Ears go under the head fill so the loop's inner half
-       is covered and only the rim reads.
-
-       RESHAPE wraps the art INSIDE the parallax group, never the group itself:
-       poseTransforms writes the group's own transform every frame and would
-       overwrite it. Same for features and hair below. The neck and body are
-       deliberately outside it — the reshape is pivoted on the chin so that
-       join still lands. -->
-  <g id="${id}-skull">
-    <g transform="${RESHAPE}">
-      <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>
-  </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">
-    <g transform="${RESHAPE}">
-      <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}"/>
-        <path id="${id}-apertureL" fill="${t.paper}"/>
-        <path id="${id}-apertureR" fill="${t.paper}"/>
-        <g clip-path="url(#${id}-clipEyeL)"><circle id="${id}-irisL" fill="${t.ink}"/></g>
-        <g clip-path="url(#${id}-clipEyeR)"><circle id="${id}-irisR" fill="${t.ink}"/></g>
-      </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>
-  </g>
-
-  <!-- hair -->
-  <g id="${id}-hair">
-    <g transform="${RESHAPE}">
-      <path d="${HAIR_D}" fill="${t.ink}"/>
-      <path d="${region(HAIR_TUFT)}" fill="${t.ink}"/>
-    </g>
-  </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 = {
-    neck: $('neck'), skull: $('skull'), body: $('body'), features: $('features'), hair: $('hair'),
-    browL: $('browL'), browR: $('browR'),
-    eyeL: $('eyeL'), eyeR: $('eyeR'),
-    clipEyeL: $('clipEyeLP'), clipEyeR: $('clipEyeRP'),
-    apertureL: $('apertureL'), apertureR: $('apertureR'),
-    irisL: $('irisL'), irisR: $('irisR'),
-    mouthIn: $('mouthIn'), lips: $('lips'), clipMouth: $('clipMouthP'),
-    teeth: $('teeth'), teethLo: $('teethLo'), tongue: $('tongue'),
-  };
-
-  function apply(p) {
-    poseTransforms(p, set, el, POSE);
-
-    // --- eyes -------------------------------------------------------------
-    // The lid line holds still and the iris carries the gaze. 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;
-    const eye = (cx, cy, lid, squint, tilt, aperture, iris, clip) => {
-      const g = eyeGeom(cy, lid, squint);
-      const ap = apertureGeom(g);
-      const apD = lensPath(cx, cy, ap, tilt);
-      set(el[aperture], 'd', apD);
-      // The iris is clipped to the APERTURE, not to the lid line, so it is
-      // cropped by the same edge the paper is — and a shut lid, which has no
-      // aperture at all, takes the iris with it and needs no opacity logic.
-      set(el[clip], 'd', apD);
-      set(el[iris], 'cx', f(cx + p.pupilX * IRIS_TRAVEL.x));
-      // Anchored to the aperture's midline rather than the eye's, so a
-      // half-closed eye keeps the iris centred in the slit instead of showing
-      // a band of paper above it.
-      set(el[iris], 'cy', f((ap ? ap.cyMid : cy) + p.pupilY * IRIS_TRAVEL.y));
-      set(el[iris], 'r', f(IRIS_R));
-      return lensPath(cx, cy, g, tilt);
-    };
-    set(el.eyeL, 'd', eye(CX - EYE.dx, EYE.y + 1, p.lidL + lidFollow, p.squintL, -9,
-                          'apertureL', 'irisL', 'clipEyeL'));
-    set(el.eyeR, 'd', eye(CX + EYE.dx, EYE.y - 1, p.lidR + lidFollow, p.squintR, 8,
-                          'apertureR', 'irisR', 'clipEyeR'));
-
-    // --- 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);
-}
-
-/**
- * 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 peep = { create: createFace, meta: META };