@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/avatar/render/eyes.ts

@@ -0,0 +1,78 @@
+/**
+ * Eyes and brows in style C (§14.1): whites 7% larger than style A's with a
+ * 1.6-unit rim in a darker shade of the skin, an iris with a darker ring, a
+ * pupil, two glints, and a soft dark-brown lid line. No dark outline.
+ */
+import { n } from '../geom';
+import { ellipse, g, line, path, sc, tr, type SceneNode } from '../scene';
+import { FIXED, SOFT_INK } from './colours';
+import { feat, LINE, type Ctx } from './context';
+
+/** Eye-white radii: style A's 9.6 × 11.8, 7% larger. */
+const RX = 9.6 * 1.07;
+const RY = 11.8 * 1.07;
+
+/** One eye; `side` −1 is the viewer's left. */
+export function eye(ctx: Ctx, side: -1 | 1): SceneNode[] {
+  const f = feat(ctx, 17 * side);
+  if (!f.vis) {
+    return [];
+  }
+  const fp = ctx.face;
+  const lidBase = side < 0 ? fp.lidL : fp.lidR;
+  const lid = lidBase + (1 - lidBase) * ctx.blink;
+  const low = side < 0 ? fp.lowL : fp.lowR;
+  const curve = side < 0 ? fp.closedCurveL : fp.closedCurveR;
+  const place = [tr(f.x, 4 + ctx.dy), sc(f.sx, 1)];
+  if (lid >= 0.9) {
+    return [g([path(`M-8 1.5Q0 ${n(1.5 - 9 * curve)} 8 1.5`, line(SOFT_INK, LINE * 1.05))], { tf: place })];
+  }
+  const top = -RY + lid * 2 * RY;
+  const edgeY = (px: number): number => top + (fp.lidTilt * (px * -side)) / 9;
+  const bot = RY - low * 2 * RY;
+  const gx = ctx.gaze.x * 2.8;
+  const gy = ctx.gaze.y * 3.4;
+  const clip = { shapes: [ellipse(0, 0, RX, RY, {})] };
+  const inner: SceneNode[] = [
+    g([
+      ellipse(0, 0, 7, 7, { fill: ctx.c.eye }),
+      ellipse(0, 0, 6.4, 6.4, line(ctx.c.eyeDark, 1.2)),
+      ellipse(0, 0, 3.6 * fp.pupil, 3.6 * fp.pupil, { fill: FIXED.pupil }),
+      ellipse(-2.4, -2.8, 2.2, 2.2, { fill: '#ffffff' }),
+      ellipse(2.1, 2, 0.9, 0.9, { fill: '#ffffff' }),
+    ], { tf: [tr(gx, gy)] }),
+  ];
+  if (lid > 0.02) {
+    inner.push(path(`M-12 -14L12 -14L12 ${n(edgeY(12))}Q0 ${n(top + 1.5)} -12 ${n(edgeY(-12))}Z`, { fill: ctx.c.skin }));
+  }
+  if (low > 0.02) {
+    inner.push(path(`M-12 14L12 14L12 ${n(bot)}Q0 ${n(bot - 3)} -12 ${n(bot)}Z`, { fill: ctx.c.skin }));
+  }
+  const out: SceneNode[] = [ellipse(0, 0, RX, RY, { fill: FIXED.white }), g(inner, { clip })];
+  if (lid > 0.06) {
+    out.push(g([path(`M${n(-RX + 0.5)} ${n(edgeY(-RX + 0.5))}Q0 ${n(top + 1.5)} ${n(RX - 0.5)} ${n(edgeY(RX - 0.5))}`, line(SOFT_INK, 1.9))], { clip }));
+  }
+  out.push(ellipse(0, 0, RX, RY, line(ctx.c.eyeRim, 1.6)));
+  return [g(out, { tf: place })];
+}
+
+const BROW_W: Readonly<Record<string, number>> = { soft: 3.8, thin: 2.4, thick: 5.6, arched: 3.6, straight: 4.2 };
+const BROW_ARCH: Readonly<Record<string, number>> = { soft: 1, thin: 1, thick: 0.8, arched: 1.9, straight: 0.2 };
+
+/** One brow in a style (`soft`, `thin`, …). */
+export function brow(ctx: Ctx, side: -1 | 1, style: string): SceneNode[] {
+  const f = feat(ctx, 17 * side);
+  if (!f.vis) {
+    return [];
+  }
+  const p = side < 0 ? ctx.face.browL : ctx.face.browR;
+  const by = -14 + p.dy + ctx.dy * 1.1;
+  const xi = -7.5 * side;
+  const xo = 7.5 * side;
+  const yi = by + p.tilt * 0.8;
+  const yo = by - p.tilt * 0.35;
+  const arch = p.arch * (BROW_ARCH[style] ?? 1);
+  const width = (BROW_W[style] ?? 3.8) * 1.15;
+  const d = `M${n(xi)} ${n(yi)}Q0 ${n(Math.min(yi, yo) - arch * 2)} ${n(xo)} ${n(yo)}`;
+  return [g([path(d, line(ctx.c.brow, width))], { tf: [tr(f.x, 0), sc(f.sx, 1)] })];
+}

package/src/avatar/render/eyewear.ts

@@ -0,0 +1,118 @@
+/** Glasses and the `goggles` status prop, both following the head turn. */
+import type { GlassesPart } from '../art/shape';
+import { deltaE, ink, lightness, outline } from '../colour';
+import { blob, Path } from '../geom';
+import { g, line, path, rect, sc, tr, type SceneNode } from '../scene';
+import { feat, LINE, turnWarp, type Ctx } from './context';
+
+/** What fills a lens: clear glass, a tint, or a mirror finish. */
+export interface LensGlass {
+  /** The tint colour; absent for clear glass. */
+  readonly tint?: string;
+  readonly isMirror?: boolean;
+}
+
+/** The default frame colour. */
+export const FRAME_BLACK = '#1d1a1e';
+
+const SHINE = 'M-6 -4L-2 -7';
+const MIRROR_STREAKS = 'M-9 7L3 -11M-1 10L9 -4';
+
+/** The frame's colour and line width, and the dark edge a frame gets when it is light or close to the skin. */
+interface FrameInk {
+  readonly colour: string;
+  readonly sw: number;
+  readonly edge: string | undefined;
+}
+
+/** A frame stroke along a path, over its edge when it has one. */
+function frameLine(d: string, frame: FrameInk, sw = frame.sw): SceneNode[] {
+  return [...(frame.edge === undefined ? [] : [path(d, line(frame.edge, sw + 1.6))]), path(d, line(frame.colour, sw))];
+}
+
+/** One lens (or visor) in its own coordinates: the glass, then the frame. */
+function lensNodes(d: string, glass: LensGlass, frame: FrameInk, shines: readonly (readonly [number, number])[]): SceneNode[] {
+  const out: SceneNode[] = [];
+  const clip = { shapes: [path(d, {})] };
+  if (glass.tint === undefined) {
+    out.push(path(d, { fill: '#ffffff', fillOpacity: 0.16 }));
+  } else if (glass.isMirror === true) {
+    out.push(path(d, { fill: glass.tint }), g([
+      rect(-60, 2, 120, 40, { fill: outline(glass.tint), opacity: 0.75 }),
+      ...shines.map(([px, py]) => path(MIRROR_STREAKS, line('#ffffff', 2.6, 'round', 0.85), [tr(px, py)])),
+    ], { clip }));
+  } else {
+    // Dark enough to read as sunglasses, light enough that winks show through.
+    out.push(path(d, { fill: glass.tint, fillOpacity: 0.86 }), g([rect(-60, 3, 120, 40, { fill: '#ffffff', opacity: 0.12 })], { clip }));
+  }
+  out.push(...frameLine(d, frame));
+  out.push(...shines.map(([px, py]) => path(SHINE, line('#ffffff', 1.8, 'round', glass.tint === undefined ? 0.7 : 0.9), [tr(px, py)])));
+  return out;
+}
+
+/** Glasses: arms toward the ears, a lens at each eye (or one visor), and the bridge. */
+export function glasses(ctx: Ctx, part: GlassesPart, colour: string, glass: LensGlass): SceneNode[] {
+  const out: SceneNode[] = [];
+  const warp = turnWarp(ctx.phi, ctx.dy);
+  const isEdged = lightness(colour) > 0.7 || deltaE(colour, ctx.c.skin) < 24;
+  const frame: FrameInk = { colour, sw: part.frame ?? 3.2, edge: isEdged ? ink(colour) : undefined };
+  const tinted: LensGlass = part.tint === undefined ? {} : { tint: glass.tint ?? part.tint, ...(glass.isMirror === true ? { isMirror: true } : {}) };
+  if (part.isSingle !== true) {
+    for (const side of [-1, 1] as const) {
+      if (feat(ctx, 30 * side).vis) {
+        out.push(...frameLine(new Path().m(30 * side, 2).l(45 * side, 0).d(warp), frame, 2.6));
+      }
+    }
+  }
+  if (part.visor) {
+    const shines = [feat(ctx, -17), feat(ctx, 17)].filter((f) => f.vis).map((f) => [f.x, 4 + ctx.dy] as const);
+    out.push(...lensNodes(part.visor.d(warp), tinted, frame, shines));
+    return out;
+  }
+  const lens = part.lens;
+  for (const side of [-1, 1] as const) {
+    const f = feat(ctx, 17 * side);
+    if (!lens || !f.vis || (part.isSingle === true && side < 0)) {
+      continue;
+    }
+    const flip = part.isMirrored === true && side < 0 ? -1 : 1;
+    out.push(g([
+      ...lensNodes(lens.d(), tinted, frame, [[0, 0]]),
+      ...(part.bar ? frameLine(part.bar.d(), frame, 4.4) : []),
+    ], { tf: [tr(f.x, 4 + ctx.dy), sc(f.sx * flip, 1)] }));
+  }
+  if (part.chain && feat(ctx, 30).vis) {
+    out.push(path(part.chain.d(warp), line(colour, 1.6, 'round', 0.9)));
+  }
+  if (part.bridge) {
+    const fb = feat(ctx, 0);
+    out.push(g(frameLine(part.bridge.d(), frame, 2.8), { tf: [tr(fb.x, 4 + ctx.dy), sc(fb.sx, 1)] }));
+  }
+  return out;
+}
+
+const STRAP_FRONT = new Path().m(-47, -2).c(-30, -6, 30, -6, 47, -2);
+const STRAP_BACK = new Path().m(-47, -2).c(-30, 4, 30, 4, 47, -2);
+const SHELL = blob([[-31, -9], [-4, -10], [0, -6], [4, -10], [31, -9], [34, 4], [26, 16], [7, 16], [0, 11], [-7, 16], [-26, 16], [-34, 4]]);
+const GLASS_L = blob([[-27, -5], [-7, -6], [-5, 8], [-9, 12], [-24, 12], [-29, 4]]);
+const GLASS_R = blob([[27, -5], [7, -6], [5, 8], [9, 12], [24, 12], [29, 4]]);
+
+/** Play goggles over the eyes (they replace the eyes and any glasses); the strap is the body colour. */
+export function goggles(ctx: Ctx): SceneNode[] {
+  const w = turnWarp(ctx.phi, ctx.dy);
+  const band = ctx.c.body;
+  const strap = STRAP_FRONT.d(w);
+  return [
+    path(strap, line(ink(band), 9)), path(strap, line(band, 6)),
+    path(SHELL.d(w), { fill: '#2a3142', stroke: '#0d0f14', sw: LINE }),
+    path(GLASS_L.d(w), { fill: '#5fe3f2' }), path(GLASS_R.d(w), { fill: '#5fe3f2' }),
+    path(new Path().m(-22, 6).l(-14, -2).d(w), line('#e8fbff', 3)),
+    path(new Path().m(12, 6).l(20, -2).d(w), line('#e8fbff', 3)),
+  ];
+}
+
+/** The goggles strap seen from behind. */
+export function gogglesStrapBack(ctx: Ctx, phi: number): SceneNode[] {
+  const d = STRAP_BACK.d(turnWarp(phi));
+  return [path(d, line(ink(ctx.c.body), 9)), path(d, line(ctx.c.body, 6))];
+}

package/src/avatar/render/frame.ts

@@ -0,0 +1,73 @@
+/**
+ * Frames (§3.4): which part of rig space an output shows, and the badge
+ * background (the site's rounded panel with a ring that lightens on dark
+ * skin, §3.9).
+ */
+import { normaliseHex, resolveColour, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import { lightness } from '../colour';
+import { g, rect, type SceneNode } from '../scene';
+import type { Frame, RenderOptions } from './types';
+
+/** A frame's box in rig units: x, y, width, height. */
+export type Box = readonly [number, number, number, number];
+
+/** The three frames' boxes. */
+export const FRAMES: Readonly<Record<Frame, Box>> = {
+  head: [-66, -164, 132, 132],
+  bust: [-84, -188, 168, 168],
+  full: [-86, -196, 172, 206],
+};
+
+/** The walker's full frame: a smaller head, and room for feet hanging below a seat. */
+export const WALKER_FULL: Box = [-60, -176, 120, 214];
+
+/** True when options draw the walker figure (full frames only). */
+export function isWalker(opts: RenderOptions): boolean {
+  return opts.figure === 'walker' && frameOf(opts) === 'full';
+}
+
+/** The box options draw, in rig units. */
+export function frameBox(opts: RenderOptions): Box {
+  return isWalker(opts) ? WALKER_FULL : FRAMES[frameOf(opts)];
+}
+
+/** The site panel colour behind badges. */
+export const PANEL = '#11141c';
+
+/** The frame an options object asks for (default `head`). */
+export function frameOf(opts: RenderOptions): Frame {
+  return opts.frame ?? 'head';
+}
+
+/** Output pixel size for a frame (the longer edge is `size`). */
+export function pixelSize(opts: RenderOptions): { readonly width: number; readonly height: number; readonly scale: number } {
+  const [, , w, h] = frameBox(opts);
+  const size = opts.size ?? 48;
+  const scale = size / Math.max(w, h);
+  return { width: w * scale, height: h * scale, scale };
+}
+
+/** The badge ring colour: lighter when the skin is darker than the panel, so every skin has an edge. */
+export function ringColour(look: AvatarLook | null): string {
+  return look && lightness(resolveColour(look.skin)) < 0.42 ? '#6f7787' : '#2a3142';
+}
+
+/** Wraps the avatar's nodes in the frame's background (a badge clips to the rounded panel). */
+export function framed(nodes: readonly SceneNode[], look: AvatarLook | null, opts: RenderOptions): SceneNode[] {
+  const [left, top, w, h] = frameBox(opts);
+  const background = opts.background ?? (frameOf(opts) === 'head' ? 'badge' : 'none');
+  if (background === 'badge') {
+    const r = w * 0.24;
+    return [
+      rect(left, top, w, h, { fill: PANEL }, r),
+      g(nodes, { clip: { shapes: [rect(left, top, w, h, {}, r)] } }),
+      rect(left + 1.5, top + 1.5, w - 3, h - 3, { fill: 'none', stroke: ringColour(look), sw: 3 }, r - 1.5),
+    ];
+  }
+  if (background === 'none') {
+    return [...nodes];
+  }
+  // A caller-supplied colour is normalised, so it can never become markup.
+  const fill = normaliseHex(background);
+  return fill ? [rect(left, top, w, h, { fill }), ...nodes] : [...nodes];
+}

package/src/avatar/render/head.ts

@@ -0,0 +1,81 @@
+/** The head, ears, cheeks and the small face and ear extras. */
+import { clamp } from '../geom';
+import { ellipse, g, line, path, sc, tr, type SceneNode } from '../scene';
+import { FIXED } from './colours';
+import { feat, HEAD_PATH, LINE, SKULL_R, type Ctx } from './context';
+
+const EAR = 'M-2 -10C6 -12 11 -6 10 1C9 8 5 11 -1 10Z';
+const EAR_FOLD = 'M1.5 -5C5.5 -5 6.5 0 5 3.5';
+
+/** Ear extras: studs or hoops, in a colour. */
+export interface EarExtra {
+  readonly kind: 'studs' | 'hoops';
+  readonly colour: string;
+}
+
+/** Ears behind the head (`behind`) or in front of it (`front`), hidden when turned away. */
+export function ears(ctx: Ctx, which: 'behind' | 'front', extra?: EarExtra): SceneNode[] {
+  const out: SceneNode[] = [];
+  for (const side of [-1, 1] as const) {
+    const t = (Math.PI / 2) * side + ctx.phi;
+    const cos = Math.cos(t);
+    if (cos < -0.15) {
+      continue;
+    }
+    const isInFront = cos > 0.3;
+    if ((which === 'front') !== isInFront) {
+      continue;
+    }
+    const earX = clamp(SKULL_R * Math.sin(t), -SKULL_R + 2, SKULL_R - 2);
+    const w = isInFront ? 0.75 + 0.25 * cos : 1;
+    const flip = isInFront ? -Math.sign(earX || side) : side;
+    const parts: SceneNode[] = [
+      path(EAR, { fill: ctx.c.skin, stroke: ctx.c.skinInk, sw: LINE }),
+      path(EAR_FOLD, line(ctx.c.skinShade, 2.2)),
+    ];
+    if (extra?.kind === 'studs') {
+      parts.push(ellipse(3, 7, 2.2, 2.2, { fill: extra.colour, stroke: '#3a2a2a', sw: 0.8 }));
+    }
+    if (extra?.kind === 'hoops') {
+      parts.push(ellipse(3, 12, 3.6, 4.4, line(extra.colour, 1.8)));
+    }
+    out.push(g(parts, { tf: [tr(earX, 6 + ctx.dy * 0.3), sc(flip * w, 1)] }));
+  }
+  return out;
+}
+
+/** The head: a shade base, the lit face, and the tonal outline. */
+export function head(ctx: Ctx): SceneNode[] {
+  const d = HEAD_PATH.d();
+  const lx = -2.5 + Math.sin(ctx.phi) * 3;
+  return [
+    path(d, { fill: ctx.c.skinShade }),
+    path(d, { fill: ctx.c.skin }, [tr(lx, -3), sc(0.95)]),
+    path(d, { fill: 'none', stroke: ctx.c.skinInk, sw: LINE }),
+  ];
+}
+
+const FRECKLES: readonly (readonly [number, number])[] = [[-3.5, -1.5], [0, 0.8], [3.5, -1.2], [1.5, -3.5]];
+
+/** Cheek blush (from the expression, plus `rosy`) and freckles. */
+export function cheeks(ctx: Ctx, hasFreckles: boolean, isRosy: boolean): SceneNode[] {
+  const out: SceneNode[] = [];
+  const blush = Math.min(1, ctx.face.cheeks + (isRosy ? 0.45 : 0));
+  for (const side of [-1, 1] as const) {
+    const f = feat(ctx, 25 * side);
+    if (!f.vis) {
+      continue;
+    }
+    const parts: SceneNode[] = [];
+    if (blush > 0.02) {
+      parts.push(ellipse(0, 0, 6.5, 3.8, { fill: FIXED.blush, opacity: Math.round(blush * 5) / 10 }));
+    }
+    if (hasFreckles) {
+      parts.push(...FRECKLES.map(([fx, fy]) => ellipse(fx, fy, 1.05, 1.05, { fill: ctx.c.skinInk, opacity: 0.45 })));
+    }
+    if (parts.length > 0) {
+      out.push(g(parts, { tf: [tr(f.x, 18 + ctx.dy), sc(f.sx, 1)] }));
+    }
+  }
+  return out;
+}

package/src/avatar/render/mouth.ts

@@ -0,0 +1,86 @@
+/**
+ * The nose, the mouth morph (one cubic structure for every shape, so any two
+ * expressions tween, §3.5) and the small FX glyphs.
+ */
+import { n } from '../geom';
+import { ellipse, g, line, path, rect, sc, tr, type SceneNode } from '../scene';
+import { FIXED, SOFT_INK } from './colours';
+import { feat, LINE, type Ctx } from './context';
+
+/** The nose: a soft shade with a highlight. */
+export function nose(ctx: Ctx): SceneNode[] {
+  const f = feat(ctx, 0);
+  return [g([
+    ellipse(0, 0, 4.4, 3, { fill: ctx.c.skinShade }),
+    ellipse(-1.5, -1, 1.2, 1.2, { fill: ctx.c.skinLight, opacity: 0.9 }),
+  ], { tf: [tr(f.x, 16 + ctx.dy), sc(Math.max(0.6, f.sx), 1)] })];
+}
+
+/** The mouth: a line when closed, a filled shape with teeth and tongue when open. Talking adds opening. */
+export function mouth(ctx: Ctx): SceneNode[] {
+  const base = ctx.face.mouth;
+  const m = { ...base, open: base.open + ctx.talk * 9 * (1 - base.round * 0.4) };
+  const f = feat(ctx, m.dx);
+  const baseY = 27;
+  const lx = -m.w / 2;
+  const ly = baseY - m.sL;
+  const rx = m.w / 2;
+  const ry = baseY - m.sR;
+  const s = (m.sL + m.sR) / 2;
+  const corner = baseY - s;
+  const ctrl = (target: number): number => (target - 0.25 * corner) / 0.75;
+  const place = [tr(f.x, ctx.dy * 0.8), sc(Math.max(0.35, f.sx), 1)];
+  if (m.open < 1) {
+    const c = ctrl(baseY + s * 0.55);
+    return [g([path(`M${n(lx)} ${n(ly)}C${n(-m.w * 0.18)} ${n(c)} ${n(m.w * 0.18)} ${n(c)} ${n(rx)} ${n(ry)}`, line(SOFT_INK, LINE * 0.95))], { tf: place })];
+  }
+  const up = baseY + s * 0.3 - m.round * m.open * 0.45;
+  const lo = baseY + s * 0.55 + m.open * (1 - m.round * 0.45);
+  const kx = (m.w / 2) * (0.55 + m.round * 0.8);
+  const d = `M${n(lx)} ${n(ly)}C${n(-kx)} ${n(ctrl(up))} ${n(kx)} ${n(ctrl(up))} ${n(rx)} ${n(ry)}C${n(kx)} ${n(ctrl(lo))} ${n(-kx)} ${n(ctrl(lo))} ${n(lx)} ${n(ly)}Z`;
+  const inside: SceneNode[] = [];
+  if (m.tongue > 0.05) {
+    inside.push(ellipse(0, lo + 1, m.w * 0.32, m.open * 0.42 * m.tongue + 1, { fill: FIXED.tongue }));
+  }
+  if (m.teeth > 0.05) {
+    inside.push(rect(-m.w / 2, up - 6, m.w, 6 + m.open * 0.22 * m.teeth, { fill: FIXED.white }));
+  }
+  return [g([
+    path(d, { fill: FIXED.mouth }),
+    g(inside, { clip: { shapes: [path(d, {})] } }),
+    path(d, line(SOFT_INK, LINE * 0.9)),
+  ], { tf: place })];
+}
+
+/** FX glyphs beside the head (sparkle, tear, sweat, anger, question, zzz). */
+export function extras(ctx: Ctx): SceneNode[] {
+  const out: SceneNode[] = [];
+  const f = feat(ctx, 0);
+  for (const e of ctx.face.extras) {
+    if (e === 'sparkle') {
+      out.push(path('M0 -9Q1.4 -1.4 9 0Q1.4 1.4 0 9Q-1.4 1.4 -9 0Q-1.4 -1.4 0 -9Z', { fill: '#ffd23f', stroke: '#0d0f14', sw: 1.6 }, [tr(48 + f.x * 0.2, -44)]));
+    }
+    if (e === 'tear') {
+      const t = feat(ctx, -16);
+      if (t.vis) {
+        out.push(path('M0 -5Q4.5 2 0 5Q-4.5 2 0 -5Z', { fill: '#7cc7ff', stroke: '#1f3b5c', sw: 1.4 }, [tr(t.x - 5, 16 + ctx.dy)]));
+      }
+    }
+    if (e === 'sweat') {
+      out.push(path('M0 -6Q5 2 0 6Q-5 2 0 -6Z', { fill: '#9fdcff', stroke: '#1f3b5c', sw: 1.4 }, [tr(40 + f.x * 0.2, -26)]));
+    }
+    if (e === 'anger') {
+      out.push(g([
+        path('M-6 -2Q-2 -2 -2 -6', line('#ff4d4d', 2.6)), path('M2 -6Q2 -2 6 -2', line('#ff4d4d', 2.6)),
+        path('M6 2Q2 2 2 6', line('#ff4d4d', 2.6)), path('M-2 6Q-2 2 -6 2', line('#ff4d4d', 2.6)),
+      ], { tf: [tr(30 + f.x * 0.3, -36)] }));
+    }
+    if (e === 'question') {
+      out.push({ k: 'text', x: 50 + f.x * 0.2, y: -40, text: '?', size: 26, font: 'pixel', fill: '#ffd23f', stroke: '#0d0f14', sw: 1.2 });
+    }
+    if (e === 'zzz') {
+      out.push({ k: 'text', x: 44 + f.x * 0.2, y: -42, text: 'z z', size: 20, font: 'pixel', fill: '#8ab4ff', stroke: '#0d0f14', sw: 1.2 });
+    }
+  }
+  return out;
+}

package/src/avatar/render/props.ts

@@ -0,0 +1,91 @@
+/**
+ * Status props (§3.11, §14.3): runtime-only parts the world (or a preview)
+ * puts on a player. `goggles` lives in eyewear.ts; the head props here sit on
+ * the head, the hand props at the `prop` anchor in front of the body.
+ */
+import { arc, blob, Path, roundedRect } from '../geom';
+import { ellipse, g, line, path, rect, rot, sc, tr, type SceneNode } from '../scene';
+import { LINE, SKULL_R, turnWarp, type Ctx } from './context';
+import type { StatusProp } from './types';
+
+const DARK = '#0d0f14';
+/** Hand props are drawn at this scale so they read at small sizes. */
+const PROP_SCALE = 1.45;
+
+/** A headset: a band over the head, ear cups and a mic (head space). */
+export function headset(ctx: Ctx, isBack: boolean): SceneNode[] {
+  const w = turnWarp(isBack ? 0 : ctx.phi);
+  const band = blob(arc(0, -4, 51, 51, 196, 344, 8), false);
+  const nodes: SceneNode[] = [path(band.d(w), line(DARK, 8)), path(band.d(w), line('#4a5470', 5))];
+  const phi = isBack ? 0 : ctx.phi;
+  for (const side of [-1, 1] as const) {
+    // The cups sit over the ears, so they follow the ears through a turn.
+    const t = (Math.PI / 2) * side + phi;
+    if (Math.cos(t) < -0.15) {
+      continue;
+    }
+    const cupX = Math.max(-SKULL_R - 1, Math.min(SKULL_R + 1, SKULL_R * Math.sin(t)));
+    const wide = 6 + 3 * Math.max(0, Math.cos(t));
+    nodes.push(path(roundedRect(cupX - wide, -6, wide * 2, 20, 5).d(), { fill: '#2a3142', stroke: DARK, sw: LINE }));
+  }
+  if (!isBack && Math.abs(phi) < 0.7) {
+    nodes.push(path(new Path().m(-46, 12).q(-40, 30, -18, 30).d(w), line('#4a5470', 3)), ellipse(-17, 30, 3, 3, { fill: '#ff5f3b', stroke: DARK, sw: 1.2 }));
+  }
+  return nodes;
+}
+
+/** A small crown on top of the head (head space; `top` is the hair or hat top). */
+export function crown(top: number): SceneNode[] {
+  const d = 'M-16 0L-18 -16L-8 -8L0 -20L8 -8L18 -16L16 0Z';
+  return [g([
+    path(d, { fill: '#ffd23f', stroke: '#8a5a00', sw: LINE }),
+    ellipse(0, -5, 2.4, 2.4, { fill: '#ff5f3b' }),
+  ], { tf: [tr(0, -50 - top + 4)] })];
+}
+
+const card = (colour: string): SceneNode =>
+  rect(-6, -9, 12, 17, { fill: colour, stroke: DARK, sw: 1.6 }, 2.5);
+
+/** Nub hands holding something at the prop anchor (body space). */
+function nubs(body: string, ink: string, spread: number, atY: number): SceneNode[] {
+  return [-1, 1].map((s) => ellipse(spread * s, atY, 7, 6, { fill: body, stroke: ink, sw: LINE }));
+}
+
+/** A hand prop drawn at the `prop` anchor (x, y) in front of the body. */
+export function handProp(prop: StatusProp, atX: number, atY: number, body: string, bodyInk: string): SceneNode[] {
+  switch (prop) {
+    case 'cards':
+      return [g([
+        g([card('#ff5f3b')], { tf: [tr(-8, 0), rot(-18)] }),
+        g([card('#ffd23f')], { tf: [tr(0, -3)] }),
+        g([card('#3d7bff')], { tf: [tr(8, 0), rot(18)] }),
+        ...nubs(body, bodyInk, 13, 8),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'controller':
+      return [g([
+        path(new Path().m(-20, -4).c(-20, -12, 20, -12, 20, -4).c(24, 10, 14, 14, 8, 6).l(-8, 6).c(-14, 14, -24, 10, -20, -4).z().d(), { fill: '#2a3142', stroke: DARK, sw: LINE }),
+        ellipse(-9, -2, 2.6, 2.6, { fill: '#8ab4ff' }), ellipse(10, -4, 2, 2, { fill: '#ff5f3b' }), ellipse(13, 0, 2, 2, { fill: '#4ade80' }),
+        ...nubs(body, bodyInk, 20, 4),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'book':
+      return [g([
+        path('M0 -2C-8 -8 -18 -8 -24 -5L-24 12C-18 9 -8 9 0 14C8 9 18 9 24 12L24 -5C18 -8 8 -8 0 -2Z', { fill: '#f4f1ea', stroke: DARK, sw: LINE }),
+        path('M0 -2L0 14', line('#c9c2b4', 1.6)),
+        path('M-19 0L-5 3M-19 5L-5 8M5 3L19 0M5 8L19 5', line('#9a9384', 1.2)),
+        path('M-24 12C-18 9 -8 9 0 14C8 9 18 9 24 12L24 15C18 12 8 12 0 17C-8 12 -18 12 -24 15Z', { fill: '#ff5f3b', stroke: DARK, sw: 1.4 }),
+        ...nubs(body, bodyInk, 25, 6),
+      ], { tf: [tr(atX, atY), sc(PROP_SCALE)] })];
+    case 'trophy':
+      return [g([
+        path('M-11 -14L11 -14L9 0C8 6 -8 6 -9 0Z', { fill: '#ffd23f', stroke: '#8a5a00', sw: LINE }),
+        path('M-11 -11C-18 -11 -18 -2 -9 -1M11 -11C18 -11 18 -2 9 -1', line('#8a5a00', 2.2)),
+        rect(-3, 4, 6, 6, { fill: '#e0a800' }), rect(-9, 10, 18, 5, { fill: '#6b4f12', stroke: DARK, sw: 1.2 }, 1.5),
+        ellipse(13, 6, 7, 6, { fill: body, stroke: bodyInk, sw: LINE }),
+      ], { tf: [tr(atX + 24, atY - 10), sc(PROP_SCALE)] })];
+    default:
+      return [];
+  }
+}
+
+/** Props worn on the head (drawn in head space). */
+export const HEAD_PROPS: ReadonlySet<StatusProp> = new Set(['goggles', 'headset', 'crown']);

package/src/avatar/render/types.ts

@@ -0,0 +1,93 @@
+/** The renderer's public option and pose types (avatars.md §3.3, §3.4, §3.11). */
+import type { AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { Expression, FaceParams } from '../face';
+
+/** Eight facings: `S` faces the viewer; `W`, `SW` and `NW` mirror `E`, `SE` and `NE`. */
+export type Facing = 'S' | 'SE' | 'E' | 'NE' | 'N' | 'NW' | 'W' | 'SW';
+
+/** The 4-direction aliases. */
+export type View = 'front' | 'back' | 'left' | 'right';
+
+/** Body poses on the blob; a future limbed body re-implements the same names. */
+export type BodyPose = 'idle' | 'walk' | 'run' | 'sit' | 'play' | 'wave' | 'cheer' | 'jump' | 'dance' | 'away';
+
+/** Runtime status props (never stored in the look). */
+export type StatusProp = 'goggles' | 'headset' | 'cards' | 'controller' | 'trophy' | 'crown' | 'book';
+
+/** How much of the character a frame shows. */
+export type Frame = 'head' | 'bust' | 'full';
+
+/**
+ * The full-body figure: `blob` (the default, a big head on a gumdrop) or
+ * `walker` (a small full-body character with legs and arms, for worlds and
+ * crowds). Head and bust frames always draw the blob.
+ */
+export type Figure = 'blob' | 'walker';
+
+/** A point in rig units. */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/** Where the eyes look: x right, y down, each in [−1, 1]. */
+export type LookDir = Point;
+
+/**
+ * Everything that moves: the face (an expression or raw parameters), gaze,
+ * blink, talk, the body pose and the status prop. The animator produces one
+ * per frame; a still render takes a partial one.
+ */
+export interface Pose {
+  readonly expression?: Expression;
+  /** Raw face parameters (wins over `expression`). */
+  readonly face?: FaceParams;
+  readonly look?: LookDir;
+  /** Extra lid closure, 0 … 1 (a blink). */
+  readonly blink?: number;
+  /** Extra mouth opening, 0 … 1 (talking). */
+  readonly talk?: number;
+  readonly body?: BodyPose;
+  /** Walk, dance or jump cycle phase, 0 … 1. */
+  readonly phase?: number;
+  readonly status?: StatusProp | null;
+  /** Reaction offset of the head, rig units. */
+  readonly bob?: Point;
+  /** Reaction tilt added to the head, degrees. */
+  readonly tilt?: number;
+  /** Reaction squash added to the head. */
+  readonly squash?: number;
+}
+
+/** Render options shared by every output. */
+export interface RenderOptions {
+  /** Output px of the frame's longer edge (default 48). */
+  readonly size?: number;
+  /** `head` badge (default), `bust` or `full` character. */
+  readonly frame?: Frame;
+  /** `badge` = the site's rounded panel and ring (the default for `head`); `none`; or a `#rrggbb`. */
+  readonly background?: 'badge' | 'none' | `#${string}`;
+  readonly facing?: Facing;
+  readonly view?: View;
+  readonly pose?: Pose;
+  /** The accessible name ("Sam's avatar"); omitted, the avatar is decorative. */
+  readonly title?: string;
+  /** A prefix for SVG ids when inlining many. */
+  readonly idPrefix?: string;
+  /** A soft light rim for dark scenes (the world; on by default in the atlas). */
+  readonly rim?: boolean;
+  /** The ground shadow (default: on for `full`). */
+  readonly shadow?: boolean;
+  /** Draws a stool under `sit` and `play` (pose sheets and previews). */
+  readonly stool?: boolean;
+  /** The full frame's figure (default `blob`). */
+  readonly figure?: Figure;
+}
+
+/** Anything a render accepts: a look, an `AV1…` code, or an object carrying a code. */
+export type LookLike = AvatarLook | string | { readonly code: string } | { readonly look: AvatarLook } | null | undefined;
+
+/** Named rig anchors (feet origin, y down), for name plates, bubbles, props and the world. */
+export type Anchor =
+  | 'feet' | 'body' | 'neck' | 'head' | 'eyeLine' | 'mouth' | 'hatTop' | 'nameplate' | 'bubble'
+  | 'seat' | 'prop' | 'shadow' | 'handL' | 'handR' | 'pod';