@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.11

package/src/avatar/atlas.ts

@@ -0,0 +1,246 @@
+/**
+ * `AvatarAtlas` (§3.11): bakes avatar frames into shared canvas pages for
+ * crowds (the world, leaderboards). Frames are baked on demand and
+ * time-sliced (`bake(budgetMs)` once per animation frame), shelf-packed into
+ * square pages, and whole pages are recycled least-recently-used. A frame
+ * that isn't baked yet comes back `null`, and the caller shows a silhouette.
+ * Mirrored facings (W, SW, NW) reuse the drawn ones with `mirror: true`.
+ */
+import type { Expression } from './face';
+import { toCode, toLook } from './look-like';
+import { defaultLayer } from './outputs/canvas';
+import { paintNodes, type Ctx2D } from './outputs/canvas-paint';
+import { composeAvatar } from './render/compose';
+import { WALKER_FULL } from './render/frame';
+import type { BodyPose, Facing, Figure, LookLike, StatusProp } from './render/types';
+
+/** What to bake. */
+export interface AtlasKey {
+  readonly look: LookLike;
+  readonly facing?: Facing;
+  readonly body?: BodyPose;
+  /** 0 … 1 through the pose's cycle (walk: 8 steps, idle: 4). */
+  readonly phase?: number;
+  /** One of the baked faces (default `neutral`). */
+  readonly face?: 'neutral' | 'happy' | 'surprised';
+  readonly status?: StatusProp | null;
+  /** Bake at this many px per rig unit (default the atlas scale; far avatars use half). */
+  readonly scale?: number;
+}
+
+/** A baked frame: where it is on which page, and where the feet are inside it. */
+export interface AtlasFrame {
+  readonly page: number;
+  readonly source: CanvasImageSource;
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+  /** The feet inside the frame, px from its top-left. */
+  readonly footX: number;
+  readonly footY: number;
+  /** Draw flipped horizontally (W, SW, NW). */
+  readonly mirror: boolean;
+}
+
+/** Atlas options. */
+export interface AtlasOptions {
+  /** Page edge in px (default 2048, 1024 on low-end devices). */
+  readonly pageSize?: number;
+  /** At most this many pages (default 4); the least recently used is recycled. */
+  readonly maxPages?: number;
+  /** Px per rig unit (default 0.32: a full character ≈ 64 px tall). */
+  readonly scale?: number;
+  /** The light rim for dark floors (default on). */
+  readonly rim?: boolean;
+  /** The figure every frame draws (default `blob`); worlds use `walker`. */
+  readonly figure?: Figure;
+  /** Makes page canvases (tests, workers); default an `OffscreenCanvas` or DOM canvas. */
+  readonly makeCanvas?: (size: number) => { readonly canvas: CanvasImageSource; readonly ctx: Ctx2D } | null;
+}
+
+interface Page {
+  readonly canvas: CanvasImageSource;
+  readonly ctx: Ctx2D;
+  shelfY: number;
+  shelfX: number;
+  shelfH: number;
+  used: number;
+  version: number;
+}
+
+const MIRRORED: Readonly<Partial<Record<Facing, Facing>>> = { W: 'E', SW: 'SE', NW: 'NE' };
+const STEPS: Readonly<Partial<Record<BodyPose, number>>> = { walk: 8, run: 8, idle: 4, dance: 8, jump: 6, cheer: 6 };
+/** The rig box every frame bakes: wide enough for hats, props and the rim. */
+const BOX = { x: -90, y: -210, w: 180, h: 226 };
+/** The walker's box: its full frame plus a margin for the rim. */
+const WALKER_BOX = { x: WALKER_FULL[0] + 4, y: WALKER_FULL[1] - 2, w: WALKER_FULL[2] - 8, h: WALKER_FULL[3] + 2 };
+
+/** The atlas. */
+export class AvatarAtlas {
+  readonly pageSize: number;
+  readonly scale: number;
+  private readonly maxPages: number;
+  private readonly rim: boolean;
+  private readonly figure: Figure;
+  private readonly box: typeof BOX;
+  private readonly makeCanvas: NonNullable<AtlasOptions['makeCanvas']>;
+  private readonly pages: Page[] = [];
+  private readonly frames = new Map<string, AtlasFrame & { readonly version: number }>();
+  private readonly queue = new Map<string, AtlasKey>();
+  /** The last frame baked per look code (a stand-in while new frames bake). */
+  private readonly latestByLook = new Map<string, string>();
+  private clock = 0;
+
+  constructor(opts: AtlasOptions = {}) {
+    this.pageSize = opts.pageSize ?? 2048;
+    this.maxPages = opts.maxPages ?? 4;
+    this.scale = opts.scale ?? 0.32;
+    this.rim = opts.rim ?? true;
+    this.figure = opts.figure ?? 'blob';
+    this.box = this.figure === 'walker' ? WALKER_BOX : BOX;
+    this.makeCanvas = opts.makeCanvas ?? ((size) => defaultLayer(size, size));
+  }
+
+  /** The frame for a key: the baked frame, or `null` (queued for {@link bake}). */
+  frame(key: AtlasKey): AtlasFrame | null {
+    const id = this.keyOf(key);
+    const isMirror = MIRRORED[key.facing ?? 'S'] !== undefined;
+    const hit = this.live(id);
+    if (hit) {
+      return { ...hit, mirror: isMirror };
+    }
+    this.queue.set(id, key);
+    // While this frame waits, the look's most recently baked frame stands in (no popping to a silhouette).
+    const standIn = this.live(this.latestByLook.get(toCode(key.look)) ?? '');
+    return standIn ? { ...standIn, mirror: isMirror } : null;
+  }
+
+  /** A baked frame whose page still holds it (touching the page for the LRU). */
+  private live(id: string): (AtlasFrame & { readonly version: number }) | undefined {
+    const hit = this.frames.get(id);
+    const page = hit ? this.pages[hit.page] : undefined;
+    if (!hit || page?.version !== hit.version) {
+      return undefined;
+    }
+    page.used = (this.clock += 1);
+    return hit;
+  }
+
+  /** Bakes queued frames for up to `budgetMs` (default 4 ms), oldest first. Returns how many were baked. */
+  bake(budgetMs = 4, now: () => number = () => (typeof performance === 'undefined' ? Date.now() : performance.now())): number {
+    const start = now();
+    let baked = 0;
+    for (const [id, key] of this.queue) {
+      if (baked > 0 && now() - start > budgetMs) {
+        break;
+      }
+      this.queue.delete(id);
+      if (this.bakeOne(id, key)) {
+        baked += 1;
+      }
+    }
+    return baked;
+  }
+
+  /** Frames still waiting to bake. */
+  get pending(): number {
+    return this.queue.size;
+  }
+
+  /** Every page's image (for texture uploads). */
+  get sources(): readonly CanvasImageSource[] {
+    return this.pages.map((p) => p.canvas);
+  }
+
+  private keyOf(key: AtlasKey): string {
+    const facing = MIRRORED[key.facing ?? 'S'] ?? key.facing ?? 'S';
+    const body = key.body ?? 'idle';
+    const steps = STEPS[body] ?? 1;
+    const step = Math.floor(((key.phase ?? 0) % 1) * steps);
+    return [toCode(key.look), facing, body, String(step), key.face ?? 'neutral', key.status ?? '', String(key.scale ?? this.scale)].join('~');
+  }
+
+  private place(w: number, h: number): { readonly page: number; readonly x: number; readonly y: number } | null {
+    for (let i = 0; i < this.pages.length; i += 1) {
+      const p = this.pages[i];
+      if (!p) {
+        continue;
+      }
+      if (p.shelfX + w > this.pageSize) {
+        p.shelfY += p.shelfH;
+        p.shelfX = 0;
+        p.shelfH = 0;
+      }
+      if (p.shelfY + h <= this.pageSize) {
+        const spot = { page: i, x: p.shelfX, y: p.shelfY };
+        p.shelfX += w;
+        p.shelfH = Math.max(p.shelfH, h);
+        return spot;
+      }
+    }
+    if (this.pages.length < this.maxPages) {
+      const made = this.makeCanvas(this.pageSize);
+      if (!made) {
+        return null;
+      }
+      this.pages.push({ canvas: made.canvas, ctx: made.ctx, shelfX: 0, shelfY: 0, shelfH: 0, used: 0, version: 1 });
+      return this.place(w, h);
+    }
+    // Recycle the least recently used page.
+    let oldest = 0;
+    this.pages.forEach((p, i) => { if (p.used < (this.pages[oldest]?.used ?? Infinity)) {oldest = i;} });
+    const page = this.pages[oldest];
+    if (!page) {
+      return null;
+    }
+    page.ctx.clearRect(0, 0, this.pageSize, this.pageSize);
+    page.version += 1;
+    page.shelfX = 0;
+    page.shelfY = 0;
+    page.shelfH = 0;
+    return this.place(w, h);
+  }
+
+  private bakeOne(id: string, key: AtlasKey): boolean {
+    const scale = key.scale ?? this.scale;
+    const box = this.box;
+    const w = Math.ceil(box.w * scale) + 2;
+    const h = Math.ceil(box.h * scale) + 2;
+    const spot = this.place(w, h);
+    const page = spot ? this.pages[spot.page] : undefined;
+    if (!spot || !page) {
+      return false;
+    }
+    const facing = MIRRORED[key.facing ?? 'S'] ?? key.facing ?? 'S';
+    const body = key.body ?? 'idle';
+    const steps = STEPS[body] ?? 1;
+    const phase = (Math.floor(((key.phase ?? 0) % 1) * steps) + 0.5) / steps;
+    const face: Expression = key.face ?? 'neutral';
+    const { nodes } = composeAvatar(toLook(key.look), {
+      frame: 'full', figure: this.figure, facing, rim: this.rim, shadow: false, pose: { expression: face, body, phase, status: key.status ?? null },
+    });
+    // Paint into a frame-sized scratch canvas (so the rim's layer is small too), then stamp it on the page.
+    const scratch = defaultLayer(w, h);
+    if (!scratch) {
+      return false;
+    }
+    scratch.ctx.translate(1 - box.x * scale, 1 - box.y * scale);
+    scratch.ctx.scale(scale, scale);
+    paintNodes(scratch.ctx, nodes, defaultLayer);
+    page.ctx.clearRect(spot.x, spot.y, w, h);
+    page.ctx.drawImage(scratch.canvas, spot.x, spot.y);
+    page.used = (this.clock += 1);
+    this.latestByLook.set(toCode(key.look), id);
+    this.frames.set(id, {
+      page: spot.page, source: page.canvas, x: spot.x, y: spot.y, w, h,
+      footX: 1 - box.x * scale, footY: 1 - box.y * scale, mirror: false, version: page.version,
+    });
+    return true;
+  }
+}
+
+/** A new atlas (one per scene; pages are shared by every avatar in it). */
+export function createAtlas(opts: AtlasOptions = {}): AvatarAtlas {
+  return new AvatarAtlas(opts);
+}

package/src/avatar/catalog-view.ts

@@ -0,0 +1,14 @@
+/** The catalog as the designer and games see it: parts per category, palettes and the revision. */
+import { CATALOG_REVISION, PALETTES, partsOf, type CatalogEntry, type PartCategory } from '@diffenderfer-games/hub-contract/avatar';
+
+/** The catalog view. */
+export const catalog = {
+  /** The parts of a category in designer order (retired parts hidden). */
+  parts(category: PartCategory): readonly CatalogEntry[] {
+    return partsOf(category);
+  },
+  /** Every colour palette. */
+  palettes: PALETTES,
+  /** The catalog revision this build knows. */
+  revision: CATALOG_REVISION,
+};

package/src/avatar/colour.ts

@@ -0,0 +1,109 @@
+/**
+ * Colour derivation in OKLab: from one fill we derive its shade, highlight
+ * and tonal outline, so any `#rrggbb` works with no new art (avatars.md §2.3,
+ * §14.1).
+ */
+
+interface Lab {
+  readonly L: number;
+  readonly a: number;
+  readonly b: number;
+}
+
+const toLin = (c: number): number => {
+  const v = c / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+};
+const fromLin = (c: number): number => {
+  const v = c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055;
+  return Math.round(Math.min(1, Math.max(0, v)) * 255);
+};
+
+/** A `#rrggbb` colour in OKLab. */
+export function hexToLab(hex: string): Lab {
+  const r = toLin(parseInt(hex.slice(1, 3), 16));
+  const g = toLin(parseInt(hex.slice(3, 5), 16));
+  const bl = toLin(parseInt(hex.slice(5, 7), 16));
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * bl);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * bl);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * bl);
+  return {
+    L: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  };
+}
+
+/** An OKLab colour as `#rrggbb` (clipped to sRGB). */
+export function labToHex(lab: Lab): string {
+  const { a, b } = lab;
+  const l = (lab.L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (lab.L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (lab.L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const r = fromLin(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s);
+  const g = fromLin(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s);
+  const bl = fromLin(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s);
+  return `#${[r, g, bl].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/** Shifts lightness by `dL` (OKLab L units) and scales chroma. */
+export function adjust(hex: string, dL: number, chroma = 1): string {
+  const c = hexToLab(hex);
+  return labToHex({ L: Math.min(0.98, Math.max(0.03, c.L + dL)), a: c.a * chroma, b: c.b * chroma });
+}
+
+/** The one shade tone of a fill. */
+export const shade = (hex: string): string => adjust(hex, -0.1, 1.08);
+
+/** The one highlight tone of a fill. */
+export const light = (hex: string): string => adjust(hex, 0.09, 0.9);
+
+/** Style C's tonal outline: a darker shade of the fill's own colour (§14.1). */
+export const outline = (hex: string): string => adjust(hex, -0.24, 1.1);
+
+/** A dark ink in the fill's own hue (status props keep a strong edge). */
+export function ink(hex: string): string {
+  const c = hexToLab(hex);
+  return labToHex({ L: Math.min(0.24, c.L * 0.42), a: c.a * 0.6, b: c.b * 0.6 });
+}
+
+/** Linear mix in OKLab. */
+export function mix(a: string, b: string, t: number): string {
+  const lhs = hexToLab(a);
+  const rhs = hexToLab(b);
+  return labToHex({ L: lhs.L + (rhs.L - lhs.L) * t, a: lhs.a + (rhs.a - lhs.a) * t, b: lhs.b + (rhs.b - lhs.b) * t });
+}
+
+/** OKLab lightness, 0 … 1. */
+export const lightness = (hex: string): number => hexToLab(hex).L;
+
+/** Perceptual distance (OKLab ΔE × 100). */
+export function deltaE(a: string, b: string): number {
+  const lhs = hexToLab(a);
+  const rhs = hexToLab(b);
+  return Math.hypot(lhs.L - rhs.L, lhs.a - rhs.a, lhs.b - rhs.b) * 100;
+}
+
+/**
+ * Keeps brows and facial hair visible on the skin (§14.2): a colour within
+ * ΔE 12 of the skin is darkened by 0.18 L.
+ */
+export function keepApart(colour: string, skin: string): string {
+  // Always darker: lightening on deep skin read as a grey mask in the review; the tonal outline does the rest.
+  return deltaE(colour, skin) >= 12 ? colour : adjust(colour, -0.18);
+}
+
+/** WCAG relative luminance of a `#rrggbb`. */
+export function luminance(hex: string): number {
+  const r = toLin(parseInt(hex.slice(1, 3), 16));
+  const g = toLin(parseInt(hex.slice(3, 5), 16));
+  const b = toLin(parseInt(hex.slice(5, 7), 16));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio between two colours. */
+export function contrast(a: string, b: string): number {
+  const lhs = luminance(a);
+  const rhs = luminance(b);
+  return (Math.max(lhs, rhs) + 0.05) / (Math.min(lhs, rhs) + 0.05);
+}

package/src/avatar/describe.ts

@@ -0,0 +1,79 @@
+/**
+ * Plain-text forms of a look: `describe()` for alt text where the avatar is
+ * the content (the designer preview), and `avatarEmoji()` for plain-text
+ * places (push titles, the console). Never gendered (§10).
+ */
+import { findPreset, partName, resolveColour, type AvatarLook, type LookColour } from '@diffenderfer-games/hub-contract/avatar';
+import { lightness } from './colour';
+import { toLook } from './look-like';
+import type { LookLike } from './render/types';
+
+/** Hair phrases; `{c}` is the colour word. */
+const HAIR_WORDS: Readonly<Record<string, string>> = {
+  bald: 'no hair', buzz: 'a {c} buzz cut', crop: 'short {c} hair', swoop: 'short swept {c} hair', spiky: 'spiky {c} hair',
+  curly: 'short curly {c} hair', coily: 'short coily {c} hair', afro: 'a {c} afro', bob: 'a {c} bob', long: 'long {c} hair',
+  ponytail: 'a {c} ponytail', bun: 'a {c} bun', puffs: 'two {c} puffs', mohawk: 'a {c} mohawk', locs: '{c} locs', braids: '{c} braids',
+};
+const BEARD_WORDS: Readonly<Record<string, string>> = {
+  stubble: 'stubble', moustache: 'a moustache', handlebar: 'a handlebar moustache', goatee: 'a goatee',
+  chinstrap: 'a chinstrap beard', short: 'a short beard', full: 'a beard', long: 'a long beard',
+};
+const EXTRA_WORDS: Readonly<Record<string, string>> = {
+  'glasses.round': 'round glasses', 'glasses.square': 'square glasses', 'glasses.owl': 'big round glasses',
+  'glasses.cat-eye': 'cat-eye glasses', 'glasses.half-rim': 'half-rim glasses', 'glasses.aviator': 'aviator glasses',
+  'glasses.sunglasses': 'sunglasses', 'glasses.sport': 'sport sunglasses', 'glasses.hearts': 'heart glasses', 'glasses.monocle': 'a monocle',
+  'headwear.hijab': 'a hijab',
+  'headwear.headwrap': 'a headwrap', 'headwear.beanie': 'a beanie', 'headwear.cap': 'a cap',
+  'face.freckles': 'freckles', 'face.rosy': 'rosy cheeks', 'ears.studs': 'earrings', 'ears.hoops': 'hoop earrings',
+};
+
+/** A colour word: the preset's name (`p:hair-dark-blond` → "dark blond"), else "light" or "dark". */
+function colourWord(colour: LookColour, prefix: 'hair' | 'eye'): string {
+  if (findPreset(colour) && colour.startsWith(`p:${prefix}-`)) {
+    return colour.slice(prefix.length + 3).replace(/-/g, ' ');
+  }
+  return lightness(resolveColour(colour)) > 0.6 ? 'light' : 'dark';
+}
+
+/** "Short curly blond hair, green eyes and freckles." */
+export function describeLook(look: AvatarLook): string {
+  const isCovered = look.accessories.some((a) => a.id === 'headwear.hijab' || a.id === 'headwear.headwrap');
+  const parts: string[] = [];
+  if (!isCovered) {
+    parts.push((HAIR_WORDS[partName(look.hair.style)] ?? '{c} hair').replace('{c}', colourWord(look.hair.colour, 'hair')));
+  }
+  parts.push(`${colourWord(look.eyes.colour, 'eye')} eyes`);
+  const beard = BEARD_WORDS[partName(look.facialHair.style)];
+  if (beard) {
+    parts.push(beard);
+  }
+  for (const accessory of look.accessories) {
+    const word = EXTRA_WORDS[accessory.id];
+    if (word) {
+      parts.push(word);
+    }
+  }
+  const text = parts.length > 1 ? `${parts.slice(0, -1).join(', ')} and ${parts.at(-1) ?? ''}` : parts.join('');
+  return `${text.charAt(0).toUpperCase()}${text.slice(1)}.`;
+}
+
+/** Alt text for any {@link LookLike} (`''` for none). */
+export function describe(like: LookLike): string {
+  const look = toLook(like);
+  return look ? describeLook(look) : '';
+}
+
+const TONES = ['\u{1F3FB}', '\u{1F3FC}', '\u{1F3FD}', '\u{1F3FE}', '\u{1F3FF}'];
+const HAIR_HINT: Readonly<Record<string, string>> = { curly: '\u{1F9B1}', coily: '\u{1F9B1}', afro: '\u{1F9B1}', bald: '\u{1F9B2}', buzz: '\u{1F9B2}' };
+
+/** A person emoji with the nearest of the five skin tones and a hair hint where Unicode has one: `🧑🏽‍🦱`. */
+export function avatarEmoji(like: LookLike): string {
+  const look = toLook(like);
+  if (!look) {
+    return '\u{1F464}';
+  }
+  const l = lightness(resolveColour(look.skin));
+  const tone = TONES[Math.max(0, Math.min(4, Math.round((0.86 - l) / 0.09)))] ?? '';
+  const hint = HAIR_HINT[partName(look.hair.style)];
+  return `\u{1F9D1}${tone}${hint ? `‍${hint}` : ''}`;
+}

package/src/avatar/face.ts

@@ -0,0 +1,187 @@
+/**
+ * Expressions are parameter sets, not drawings (avatars.md §3.5), so they
+ * mix freely with look direction, blinking and talking. Every field is a
+ * number (except the FX list), so any two expressions tween.
+ */
+
+/** One brow: vertical offset, tilt (+ lowers the inner end) and arch. */
+export interface BrowParams {
+  readonly dy: number;
+  readonly tilt: number;
+  readonly arch: number;
+}
+
+/** The mouth morph: every expression uses the same structure. */
+export interface MouthParams {
+  /** Corner-to-corner width. */
+  readonly w: number;
+  /** Left corner raise (+ up). */
+  readonly sL: number;
+  /** Right corner raise. */
+  readonly sR: number;
+  /** 0 closed … ~16 wide open. */
+  readonly open: number;
+  /** 0 … 1, pulls the lips into an "o". */
+  readonly round: number;
+  /** 0 … 1, the top-teeth band. */
+  readonly teeth: number;
+  /** 0 … 1. */
+  readonly tongue: number;
+  /** Sideways shift (a smirk). */
+  readonly dx: number;
+}
+
+/** Small FX glyphs drawn beside the head. */
+export type FaceExtra = 'sweat' | 'tear' | 'sparkle' | 'anger' | 'question' | 'zzz';
+
+/** A face: brows, lids, pupils, mouth, cheeks, head tilt and squash. */
+export interface FaceParams {
+  readonly browL: BrowParams;
+  readonly browR: BrowParams;
+  /** Upper lid, 0 open … 1 closed. */
+  readonly lidL: number;
+  readonly lidR: number;
+  /** Lower lid (a smile squint), 0 … 1. */
+  readonly lowL: number;
+  readonly lowR: number;
+  /** + lowers the inner corners (a cross look). */
+  readonly lidTilt: number;
+  /** When closed: +1 a happy ^, −1 a calm ∪. */
+  readonly closedCurveL: number;
+  readonly closedCurveR: number;
+  /** Pupil scale, 0.7 … 1.3. */
+  readonly pupil: number;
+  readonly mouth: MouthParams;
+  /** Blush, 0 … 1. */
+  readonly cheeks: number;
+  /** Degrees, −12 … 12. */
+  readonly headTilt: number;
+  /** −0.08 … 0.08 (stretch on surprise). */
+  readonly squash: number;
+  readonly extras: readonly FaceExtra[];
+}
+
+const brow = (dy = 0, tilt = 0, arch = 2.5): BrowParams => ({ dy, tilt, arch });
+const mouth = (m: Partial<MouthParams>): MouthParams => ({ w: 13, sL: 1.5, sR: 1.5, open: 0, round: 0, teeth: 0, tongue: 0, dx: 0, ...m });
+
+const BASE: FaceParams = {
+  browL: brow(), browR: brow(), lidL: 0.12, lidR: 0.12, lowL: 0, lowR: 0, lidTilt: 0,
+  closedCurveL: 1, closedCurveR: 1, pupil: 1, mouth: mouth({}), cheeks: 0.25, headTilt: 0, squash: 0, extras: [],
+};
+
+const face = (f: Partial<FaceParams>): FaceParams => ({ ...BASE, ...f });
+
+/** The launch set of 16 expressions (§3.5). Kid-friendly: angry and shocked stay cartoon-cute, cry is one tear. */
+export const EXPRESSIONS = {
+  neutral: BASE,
+  happy: face({
+    browL: brow(-2, 0, 3.5), browR: brow(-2, 0, 3.5), lowL: 0.22, lowR: 0.22,
+    mouth: mouth({ w: 19, sL: 5, sR: 5, open: 7, teeth: 0.5, tongue: 0.6 }), cheeks: 0.65,
+  }),
+  laugh: face({
+    browL: brow(-4, -1, 4), browR: brow(-4, -1, 4), lidL: 1, lidR: 1,
+    mouth: mouth({ w: 22, sL: 6, sR: 6, open: 13, teeth: 0.45, tongue: 0.9 }), cheeks: 0.9, headTilt: -6, squash: 0.03, extras: ['sparkle'],
+  }),
+  grin: face({
+    browL: brow(-2.5, 0, 3.5), browR: brow(-2.5, 0, 3.5), lowL: 0.3, lowR: 0.3,
+    mouth: mouth({ w: 21, sL: 5.5, sR: 5.5, open: 4.5, teeth: 1 }), cheeks: 0.7,
+  }),
+  sad: face({
+    browL: brow(1, -4.5, 1), browR: brow(1, -4.5, 1), lidL: 0.3, lidR: 0.3, lidTilt: -3,
+    mouth: mouth({ w: 12, sL: -4, sR: -4 }), cheeks: 0.1, headTilt: 4,
+  }),
+  cry: face({
+    browL: brow(1, -5.5, 1), browR: brow(1, -5.5, 1), lidL: 0.4, lidR: 0.4, lidTilt: -3, lowL: 0.15, lowR: 0.15,
+    mouth: mouth({ w: 13, sL: -4.5, sR: -4.5, open: 3 }), cheeks: 0.4, headTilt: 5, extras: ['tear'],
+  }),
+  surprised: face({
+    browL: brow(-7, -1, 4), browR: brow(-7, -1, 4), lidL: 0, lidR: 0, pupil: 0.8,
+    mouth: mouth({ w: 9, sL: 0, sR: 0, open: 11, round: 1, tongue: 0.3 }), cheeks: 0.2, squash: -0.05,
+  }),
+  shocked: face({
+    browL: brow(-9, -2, 4.5), browR: brow(-9, -2, 4.5), lidL: 0, lidR: 0, pupil: 0.7,
+    mouth: mouth({ w: 11, sL: -1, sR: -1, open: 14, round: 0.8, tongue: 0.4 }), cheeks: 0.15, squash: -0.07, extras: ['sweat'],
+  }),
+  angry: face({
+    browL: brow(2, 5.5, 0), browR: brow(2, 5.5, 0), lidL: 0.32, lidR: 0.32, lidTilt: 4,
+    mouth: mouth({ w: 15, sL: -2.5, sR: -2.5, open: 3.5, teeth: 0.9 }), cheeks: 0.35, extras: ['anger'],
+  }),
+  grumpy: face({
+    browL: brow(2, 3.5, 0.5), browR: brow(2, 3.5, 0.5), lidL: 0.42, lidR: 0.42, lidTilt: 2,
+    mouth: mouth({ w: 12, sL: -2, sR: -2.5, dx: -1 }), cheeks: 0.1, headTilt: -3,
+  }),
+  thinking: face({
+    browL: brow(-5, -1.5, 3.5), browR: brow(1.5, 3, 0.5), lidL: 0.1, lidR: 0.3,
+    mouth: mouth({ w: 9, sL: -0.5, sR: 1.5, dx: 4 }), cheeks: 0.15, headTilt: -5, extras: ['question'],
+  }),
+  wink: face({
+    browL: brow(-2, 0, 3.5), browR: brow(1.5, 1.5, 1.5), lidR: 1, lowL: 0.15,
+    mouth: mouth({ w: 16, sL: 2, sR: 5.5, dx: 1.5 }), cheeks: 0.6, headTilt: 3, extras: ['sparkle'],
+  }),
+  smug: face({
+    browL: brow(0, 1, 1.5), browR: brow(-4, -1, 3.5), lidL: 0.45, lidR: 0.4, lowL: 0.1, lowR: 0.1,
+    mouth: mouth({ w: 14, sL: 1, sR: 5, dx: 3 }), cheeks: 0.45, headTilt: 4,
+  }),
+  worried: face({
+    browL: brow(-2, -5, 2), browR: brow(-2, -5, 2), lidL: 0.05, lidR: 0.05, pupil: 0.9,
+    mouth: mouth({ w: 11, sL: -1.5, sR: -1, open: 1.5 }), cheeks: 0.1, extras: ['sweat'],
+  }),
+  sleepy: face({
+    browL: brow(1, -1, 1.5), browR: brow(1, -1, 1.5), lidL: 0.72, lidR: 0.72, closedCurveL: -1, closedCurveR: -1,
+    mouth: mouth({ w: 7, sL: 0, sR: 0, open: 2.5, round: 1 }), cheeks: 0.2, headTilt: 7, extras: ['zzz'],
+  }),
+  determined: face({
+    browL: brow(1, 3.5, 0.5), browR: brow(1, 3.5, 0.5), lidL: 0.22, lidR: 0.22, lidTilt: 2,
+    mouth: mouth({ w: 12, sL: 1, sR: 1 }), cheeks: 0.25,
+  }),
+} satisfies Record<string, FaceParams>;
+
+/** A named expression. */
+export type Expression = keyof typeof EXPRESSIONS;
+
+/** Every expression name, in the launch order. */
+export const EXPRESSION_NAMES: readonly Expression[] = [
+  'neutral', 'happy', 'laugh', 'grin', 'sad', 'cry', 'surprised', 'shocked',
+  'angry', 'grumpy', 'thinking', 'wink', 'smug', 'worried', 'sleepy', 'determined',
+];
+
+/** True for a known expression name. */
+export function isExpression(name: string): name is Expression {
+  return Object.prototype.hasOwnProperty.call(EXPRESSIONS, name);
+}
+
+const lerp = (a: number, b: number, t: number): number => a + (b - a) * t;
+const mixBrow = (a: BrowParams, b: BrowParams, t: number): BrowParams => ({ dy: lerp(a.dy, b.dy, t), tilt: lerp(a.tilt, b.tilt, t), arch: lerp(a.arch, b.arch, t) });
+const mixMouth = (a: MouthParams, b: MouthParams, t: number): MouthParams => ({
+  w: lerp(a.w, b.w, t), sL: lerp(a.sL, b.sL, t), sR: lerp(a.sR, b.sR, t), open: lerp(a.open, b.open, t),
+  round: lerp(a.round, b.round, t), teeth: lerp(a.teeth, b.teeth, t), tongue: lerp(a.tongue, b.tongue, t), dx: lerp(a.dx, b.dx, t),
+});
+
+/** An expression's parameters (a name or parameters pass through). */
+export function faceOf(e: Expression | FaceParams): FaceParams {
+  return typeof e === 'string' ? EXPRESSIONS[e] : e;
+}
+
+/** Blends two expressions: `mix('happy', 'surprised', 0.4)`. */
+export function mix(a: Expression | FaceParams, b: Expression | FaceParams, t: number): FaceParams {
+  const from = faceOf(a);
+  const to = faceOf(b);
+  return {
+    browL: mixBrow(from.browL, to.browL, t), browR: mixBrow(from.browR, to.browR, t),
+    lidL: lerp(from.lidL, to.lidL, t), lidR: lerp(from.lidR, to.lidR, t), lowL: lerp(from.lowL, to.lowL, t), lowR: lerp(from.lowR, to.lowR, t),
+    lidTilt: lerp(from.lidTilt, to.lidTilt, t), closedCurveL: lerp(from.closedCurveL, to.closedCurveL, t), closedCurveR: lerp(from.closedCurveR, to.closedCurveR, t),
+    pupil: lerp(from.pupil, to.pupil, t), mouth: mixMouth(from.mouth, to.mouth, t), cheeks: lerp(from.cheeks, to.cheeks, t),
+    headTilt: lerp(from.headTilt, to.headTilt, t), squash: lerp(from.squash, to.squash, t), extras: t < 0.5 ? from.extras : to.extras,
+  };
+}
+
+/** The hub's quick-chat emotes (`e:<emoji>`, the safety package's EMOTES) mapped to faces (§3.7), so an emote can also play on the sender's face. */
+const EMOTE_FACES: Readonly<Record<string, Expression>> = {
+  '😀': 'happy', '😂': 'laugh', '😮': 'surprised', '😢': 'sad', '😎': 'smug', '🤔': 'thinking',
+  '👍': 'grin', '👏': 'happy', '🎉': 'laugh', '❤️': 'happy', '🔥': 'determined', '⭐': 'grin',
+};
+
+/** The face for a quick-chat emote (`e:😂` or the bare emoji), or `null`. */
+export function expressionFromEmote(emoteId: string): Expression | null {
+  return EMOTE_FACES[emoteId.startsWith('e:') ? emoteId.slice(2) : emoteId] ?? null;
+}