@diffenderfer-games/hub 2.0.0-next.5 → 2.0.0-next.7

package/src/avatar/render/body.ts

@@ -0,0 +1,116 @@
+/**
+ * The body blob and its poses (§3.11). Each pose is a transform of the same
+ * gumdrop plus where the head sits; a future limbed body re-implements the
+ * same names. The cycle poses (`walk`, `run`, `dance`, `jump`, `cheer`) read
+ * `phase` (0 … 1).
+ */
+import { blob } from '../geom';
+import { ellipse, g, line, path, rect, rot, sc, skewX, tr, type SceneNode, type TfOp } from '../scene';
+import { LINE } from './context';
+import type { Colours } from './colours';
+import type { BodyPose } from './types';
+
+const BODY = blob([[-35, -2], [-40, -24], [-30, -50], [0, -60], [30, -50], [40, -24], [35, -2], [0, 2]]).d();
+
+/** The body's drawing plus where the head goes. */
+export interface BodyLayout {
+  readonly behind: readonly SceneNode[];
+  readonly body: readonly SceneNode[];
+  readonly front: readonly SceneNode[];
+  readonly headDx: number;
+  readonly headDy: number;
+  readonly tilt: number;
+  /** How far the whole character is lifted off the ground (jumps). */
+  readonly lift: number;
+  /** The `prop` anchor in rig space. */
+  readonly prop: { readonly x: number; readonly y: number };
+}
+
+const STOOL: readonly SceneNode[] = [
+  rect(-27, -12, 6, 12, { fill: '#2a3142', stroke: '#0d0f14', sw: 2 }),
+  rect(21, -12, 6, 12, { fill: '#2a3142', stroke: '#0d0f14', sw: 2 }),
+  rect(-38, -22, 76, 11, { fill: '#4a5470', stroke: '#0d0f14', sw: 3 }, 5.5),
+];
+
+const hand = (c: Colours, cx: number, cy: number): SceneNode => ellipse(cx, cy, 8, 8, { fill: c.body, stroke: c.bodyInk, sw: LINE });
+
+/** Lays out the body for a pose; `phi` is the body turn (shading shifts with it). */
+export function bodyLayout(c: Colours, pose: BodyPose, phi: number, phase: number, hasStool: boolean): BodyLayout {
+  const wave = Math.sin(phase * Math.PI * 2);
+  const hop = Math.abs(Math.sin(phase * Math.PI));
+  let tf: TfOp[] = [];
+  let headDx = 0;
+  let headDy = 0;
+  let tilt = 0;
+  let lift = 0;
+  const behind: SceneNode[] = [];
+  const front: SceneNode[] = [];
+  switch (pose) {
+    case 'sit':
+    case 'play': {
+      const up = hasStool ? -18 : 0;
+      tf = [tr(0, up), sc(1.12, 0.8)];
+      headDy = 12 + up;
+      if (hasStool) {
+        behind.push(...STOOL);
+      }
+      break;
+    }
+    case 'walk':
+    case 'run': {
+      const k = pose === 'run' ? 1.6 : 1;
+      tf = [tr(0, -10 * k), skewX(-10 * k), sc(1 - wave * 0.04, 1 + wave * 0.06)];
+      headDy = -14 * k + wave * 3;
+      headDx = 7 * k;
+      tilt = 6 * k;
+      behind.push(path('M-52 -30h-14M-50 -18h-20M-54 -6h-10', line('#6f7787', 3, 'round', 0.8)));
+      break;
+    }
+    case 'wave':
+      tf = [rot(-6)];
+      headDx = -5;
+      tilt = -7;
+      front.push(hand(c, 44, -58), path('M56 -70Q61 -64 58 -56M62 -76Q69 -66 64 -54', line('#e8e6df', 2.2, 'round', 0.8)));
+      break;
+    case 'cheer':
+      lift = hop * 10;
+      tf = [sc(1 - hop * 0.04, 1 + hop * 0.05)];
+      headDy = -4 * hop;
+      front.push(hand(c, -42, -66 - hop * 4), hand(c, 42, -66 - hop * 4));
+      break;
+    case 'jump':
+      lift = hop * 18;
+      tf = [sc(1 - hop * 0.06, 1 + hop * 0.08)];
+      headDy = -6 * hop;
+      break;
+    case 'dance':
+      tf = [rot(wave * 8), sc(1 + hop * 0.03, 1 - hop * 0.03)];
+      headDx = wave * 5;
+      tilt = wave * 7;
+      break;
+    case 'away':
+      tf = [sc(1.04, 0.95)];
+      headDy = 3;
+      tilt = 5;
+      break;
+    case 'idle':
+      break;
+  }
+  const hl = -16 - Math.sin(phi) * 8;
+  const body: SceneNode[] = [g([
+    path(BODY, { fill: c.bodyShade }),
+    path(BODY, { fill: c.body }, [tr(-3 - Math.sin(phi) * 2, -3), sc(0.9)]),
+    ellipse(0, -54, 20, 6, { fill: c.bodyShade }),
+    ellipse(0, 0, 6, 4, { fill: c.bodyLight }, [tr(hl, -36), rot(-30)]),
+    path(BODY, { fill: 'none', stroke: c.bodyInk, sw: LINE }),
+  ], { tf })];
+  const isSitting = pose === 'sit' || pose === 'play';
+  return { behind, body, front, headDx, headDy, tilt, lift, prop: { x: headDx * 0.5, y: isSitting ? -34 + (hasStool ? -18 : 0) * 0.8 : -30 } };
+}
+
+/** The soft ground shadow at the feet (shrinks while lifted). */
+export function groundShadow(lift: number): SceneNode {
+  const k = Math.max(0.5, 1 - lift / 40);
+  return ellipse(0, 0, 36 * k, 8 * k, { fill: '#000000', opacity: 0.3 });
+}
+

package/src/avatar/render/colours.ts

@@ -0,0 +1,81 @@
+/**
+ * Resolves a look's colours into every tint slot the art uses (§3.2): each
+ * fill gets its shade, highlight and tonal outline (style C, §14.1), brows
+ * and beards are kept apart from the skin (§14.2), and accessories default
+ * to the body colour.
+ */
+import { resolveColour, type AvatarLook, type LookAccessory } from '@diffenderfer-games/hub-contract/avatar';
+import { adjust, keepApart, light, lightness, mix, outline, shade } from '../colour';
+
+/** The soft dark-brown ink for lids, mouths and closed eyes (§14.1). */
+export const SOFT_INK = '#3a2a2a';
+
+/** Resolved colours for one look. */
+export interface Colours {
+  readonly skin: string;
+  readonly skinShade: string;
+  readonly skinLight: string;
+  readonly skinInk: string;
+  /** The eye-white rim: a darker shade of the skin. */
+  readonly eyeRim: string;
+  readonly hair: string;
+  readonly hairShade: string;
+  readonly hairLight: string;
+  readonly hairInk: string;
+  /** A buzz cut: hair mixed into the skin. */
+  readonly hairBuzz: string;
+  readonly brow: string;
+  readonly beard: string;
+  readonly beardShade: string;
+  readonly beardInk: string;
+  readonly stubble: string;
+  readonly eye: string;
+  readonly eyeDark: string;
+  readonly body: string;
+  readonly bodyShade: string;
+  readonly bodyLight: string;
+  readonly bodyInk: string;
+}
+
+/** The fixed colours every look shares. */
+export const FIXED = {
+  ink: SOFT_INK, white: '#fbfaf6', mouth: '#5a1d2a', tongue: '#ff7d8e', blush: '#ff7b8f', pupil: '#140f0d',
+} as const;
+
+/** A colour and its derived tones. */
+export interface Tones {
+  readonly base: string;
+  readonly shade: string;
+  readonly light: string;
+  readonly ink: string;
+}
+
+/** A fill and its tones. */
+export function tones(hex: string): Tones {
+  return { base: hex, shade: shade(hex), light: light(hex), ink: outline(hex) };
+}
+
+/** The colours of a look. */
+export function lookColours(look: AvatarLook): Colours {
+  const skin = resolveColour(look.skin);
+  const hair = resolveColour(look.hair.colour);
+  const browBase = look.brows.colour === undefined
+    ? (lightness(hair) > 0.78 ? adjust(hair, -0.22) : adjust(hair, -0.05))
+    : resolveColour(look.brows.colour);
+  const beard = keepApart(look.facialHair.colour === undefined ? hair : resolveColour(look.facialHair.colour), skin);
+  const eye = resolveColour(look.eyes.colour);
+  const body = resolveColour(look.body.colour);
+  return {
+    skin, skinShade: shade(skin), skinLight: light(skin), skinInk: outline(skin), eyeRim: adjust(skin, -0.2, 1.1),
+    hair, hairShade: shade(hair), hairLight: light(hair), hairInk: outline(hair), hairBuzz: mix(hair, skin, 0.42),
+    brow: keepApart(browBase, skin),
+    beard, beardShade: shade(beard), beardInk: outline(beard), stubble: mix(beard, skin, 0.35),
+    eye, eyeDark: adjust(eye, -0.18),
+    body, bodyShade: shade(body), bodyLight: light(body), bodyInk: outline(body),
+  };
+}
+
+/** An accessory's colour: its own, else the body colour. */
+export function accessoryColour(look: AvatarLook, accessory: LookAccessory | undefined): string {
+  return accessory?.colour === undefined ? resolveColour(look.body.colour) : resolveColour(accessory.colour);
+}

package/src/avatar/render/compose.ts

@@ -0,0 +1,303 @@
+/**
+ * Composes a look and a pose into a scene in rig space: the feet at (0, 0),
+ * y down, the head centre near (0, −96) (§14.2). Layers go back to front as
+ * in §3.2, with facial hair split into beard and moustache layers.
+ */
+import { partName, resolveColour, type AvatarLook } from '@diffenderfer-games/hub-contract/avatar';
+import type { ArtSet } from '../art';
+import type { HeadwearPart, Shape } from '../art/shape';
+import { currentArt } from '../art-store';
+import { EXPRESSIONS } from '../face';
+import { n, type Warp } from '../geom';
+import { g, path, rect, rot, sc, tr, type Clip, type SceneNode } from '../scene';
+import { bodyLayout, groundShadow } from './body';
+import { accessoryColour, lookColours, tones, type Colours } from './colours';
+import { HEAD_PATH, LINE, paintShapes, SKULL_R, turnWarp, type Ctx } from './context';
+import { FRAME_BLACK, glasses, goggles, gogglesStrapBack, type LensGlass } from './eyewear';
+import { brow, eye } from './eyes';
+import { cheeks, ears, head, type EarExtra } from './head';
+import { extras, mouth, nose } from './mouth';
+import { crown, handProp, headset } from './props';
+import type { Anchor, Facing, Point, Pose, RenderOptions } from './types';
+
+/** The lens tint drawn with a mirror finish. */
+const MIRROR_TINT = 'p:lens-mirror';
+
+/** The head centre's height above the feet. */
+export const HEAD_Y = -96;
+
+const DEG = Math.PI / 180;
+type Drawn = 'S' | 'SE' | 'E' | 'NE' | 'N';
+const FACING_ANGLE: Readonly<Record<Drawn, number>> = { S: 0, SE: 34, E: 70, NE: 145, N: 180 };
+const MIRROR: Readonly<Partial<Record<Facing, Drawn>>> = { SW: 'SE', W: 'E', NW: 'NE' };
+const VIEW_FACING = { front: 'S', back: 'N', left: 'W', right: 'E' } as const;
+
+/** A composed avatar: scene nodes in rig space and its anchors. */
+export interface Composed {
+  readonly nodes: readonly SceneNode[];
+  readonly anchors: Readonly<Record<Anchor, Point>>;
+}
+
+/** The facing an options object asks for. */
+export function facingOf(opts: RenderOptions): Facing {
+  return opts.facing ?? (opts.view ? VIEW_FACING[opts.view] : 'S');
+}
+
+/** Per-look parts resolved against the art. */
+interface Parts {
+  readonly c: Colours;
+  readonly hair: ArtSet['hair'][string] | undefined;
+  readonly hat: HeadwearPart | undefined;
+  readonly hatColour: string;
+  readonly beard: ArtSet['beard'][string] | undefined;
+  readonly glasses: ArtSet['glasses'][string] | undefined;
+  readonly glassesColour: string;
+  readonly lensGlass: LensGlass;
+  readonly freckles: boolean;
+  readonly rosy: boolean;
+  readonly earExtra: EarExtra | undefined;
+  readonly browStyle: string;
+}
+
+function resolveParts(look: AvatarLook, art: ArtSet): Parts {
+  const slot = (name: string) => look.accessories.find((a) => a.slot === name);
+  const hatAcc = slot('headwear');
+  const glassAcc = slot('glasses');
+  const earAcc = slot('ears');
+  const face = slot('face');
+  return {
+    c: lookColours(look),
+    hair: art.hair[partName(look.hair.style)],
+    hat: hatAcc ? art.headwear[partName(hatAcc.id)] : undefined,
+    hatColour: accessoryColour(look, hatAcc),
+    beard: art.beard[partName(look.facialHair.style)],
+    glasses: glassAcc ? art.glasses[partName(glassAcc.id)] : undefined,
+    glassesColour: glassAcc?.colour === undefined ? FRAME_BLACK : accessoryColour(look, glassAcc),
+    lensGlass: glassAcc?.tint === undefined ? {} : { tint: resolveColour(glassAcc.tint), ...(glassAcc.tint === MIRROR_TINT ? { isMirror: true } : {}) },
+    freckles: face?.id === 'face.freckles',
+    rosy: face?.id === 'face.rosy',
+    earExtra: earAcc ? { kind: earAcc.id === 'ears.hoops' ? 'hoops' : 'studs', colour: earAcc.colour === undefined ? '#f5c542' : accessoryColour(look, earAcc) } : undefined,
+    browStyle: partName(look.brows.style),
+  };
+}
+
+/** The far-side clip for a turned head's rear art (a back-of-skull crescent). */
+function backOfHead(phi: number): { readonly crescent: Clip; readonly half: Clip } {
+  const co = Math.cos(phi);
+  const left = -SKULL_R * co - 3;
+  const cx = (left + SKULL_R + 12) / 2;
+  const rx = (SKULL_R + 12 - left) / 2;
+  const crescent = `M-200 -200H200V200H-200Z M${n(cx - rx)} 8A${n(rx)} 64 0 1 0 ${n(cx + rx)} 8A${n(rx)} 64 0 1 0 ${n(cx - rx)} 8Z`;
+  return {
+    crescent: { shapes: [path(crescent, {})], evenOdd: true },
+    half: { shapes: [rect(-200, -200, 200 + cx, 400, {})] },
+  };
+}
+
+/**
+ * The shoulder line in head space: hair below it hangs behind the body and
+ * shoulders, hair above it (or over the face) stays over the head (§14.6
+ * "Long hair"). The two halves overlap by a unit so the seam never shows.
+ */
+export const SHOULDER_Y = 36;
+const ABOVE_SHOULDERS: Clip = { shapes: [rect(-200, -200, 400, 200 + SHOULDER_Y + 1, {}), path(HEAD_PATH.d(), {})] };
+const BELOW_SHOULDERS: Clip = { shapes: [rect(-200, SHOULDER_Y - 1, 400, 300, {})] };
+
+/** True when a layer reaches below the shoulder line. */
+function hangs(shapes: readonly Shape[] | undefined): boolean {
+  return shapes?.some((s) => s.d.bottom() > SHOULDER_Y) === true;
+}
+
+/** A head's drawing: what goes behind the body (hanging hair) and the head itself. */
+interface HeadNodes {
+  readonly behindBody: SceneNode[];
+  readonly head: SceneNode[];
+}
+
+/** Splits a hair layer at the shoulders: the part above stays in `over`, the part below goes in `behind`. */
+function splitAtShoulders(nodes: readonly SceneNode[], doesHang: boolean, over: SceneNode[], behind: SceneNode[]): void {
+  if (nodes.length === 0) {
+    return;
+  }
+  if (!doesHang) {
+    over.push(...nodes);
+    return;
+  }
+  over.push(g(nodes, { clip: ABOVE_SHOULDERS }));
+  behind.push(g(nodes, { clip: BELOW_SHOULDERS }));
+}
+
+/** The front and side views of the head. */
+function frontHead(ctx: Ctx, p: Parts, isPlaying: boolean, status: Pose['status'], angle: number, gazeX: number): HeadNodes {
+  const hatCut: Clip | undefined = p.hat && typeof p.hat.hides === 'number' ? { shapes: [rect(-120, p.hat.hides, 240, 260, {})] } : undefined;
+  const isHairShown = !(p.hat && p.hat.hides === 'all');
+  const cut = (nodes: SceneNode[]): SceneNode[] => (hatCut && nodes.length > 0 ? [g(nodes, { clip: hatCut })] : nodes);
+  const hairTie = tones(ctx.c.body);
+  const hatTones = tones(p.hatColour);
+  const warpFront = turnWarp((angle + gazeX * 6) * DEG);
+  const warpBack: Warp | undefined = ctx.phi === 0 ? undefined : (px, py) => [px - Math.sin(ctx.phi) * 8, py];
+  const behindBody: SceneNode[] = [];
+  const out: SceneNode[] = [];
+  if (isHairShown) {
+    // The hair behind the head is behind the body too: it hangs down the back.
+    behindBody.push(...cut(paintShapes(ctx.c, hairTie, p.hair?.back, warpBack)));
+  }
+  if (p.hat?.back) {
+    out.push(...paintShapes(ctx.c, hatTones, p.hat.back, warpBack));
+  }
+  if (!p.hat?.hidesEars) {
+    out.push(...ears(ctx, 'behind', p.earExtra));
+  }
+  out.push(...head(ctx));
+  const turnS = Math.sin(ctx.phi);
+  if (Math.abs(turnS) > 0.3) {
+    // A turned head shows the back of the hair (the rear art) on the far side (§14.2).
+    const co = Math.cos(ctx.phi);
+    const shift: Warp = (px, py) => [px * (0.92 + 0.08 * co) - turnS * 5, py];
+    const clips = backOfHead(ctx.phi);
+    const onFarSide = (nodes: SceneNode[]): SceneNode[] => (nodes.length > 0 ? [g([g(nodes, { clip: clips.crescent })], { clip: clips.half })] : []);
+    if (isHairShown) {
+      splitAtShoulders(onFarSide(cut(paintShapes(ctx.c, hairTie, p.hair?.rear, shift))), hangs(p.hair?.rear), out, behindBody);
+    }
+    if (p.hat) {
+      out.push(...onFarSide(paintShapes(ctx.c, hatTones, p.hat.rear, shift)));
+    }
+  }
+  if (!p.hat?.hidesEars) {
+    out.push(...ears(ctx, 'front', p.earExtra));
+  }
+  out.push(...cheeks(ctx, p.freckles, p.rosy));
+  const faceWarp = turnWarp(ctx.phi, ctx.dy * 0.8);
+  out.push(...paintShapes(ctx.c, hairTie, p.beard?.beard, faceWarp));
+  if (!isPlaying) {
+    out.push(...eye(ctx, -1), ...eye(ctx, 1));
+  }
+  out.push(...brow(ctx, -1, p.browStyle), ...brow(ctx, 1, p.browStyle));
+  if (turnS > 0.8) {
+    out.push(path('M43 9C50 11 51 18 43.5 20', { fill: ctx.c.skin, stroke: ctx.c.skinInk, sw: LINE }));
+  }
+  out.push(...nose(ctx), ...mouth(ctx));
+  out.push(...paintShapes(ctx.c, hairTie, p.beard?.moustache, faceWarp));
+  if (isHairShown) {
+    splitAtShoulders(cut(paintShapes(ctx.c, hairTie, p.hair?.front, warpFront)), hangs(p.hair?.front), out, behindBody);
+    if (p.hair?.front?.some((s) => s.clip === 'head')) {
+      out.push(path(HEAD_PATH.d(), { fill: 'none', stroke: ctx.c.skinInk, sw: LINE }));
+    }
+  }
+  if (isPlaying) {
+    out.push(...goggles(ctx));
+  } else if (p.glasses) {
+    out.push(...glasses(ctx, p.glasses, p.glassesColour, p.lensGlass));
+  }
+  if (p.hat) {
+    out.push(...paintShapes(ctx.c, hatTones, p.hat.front, warpFront));
+  }
+  if (status === 'headset') {
+    out.push(...headset(ctx, false));
+  }
+  out.push(...extras(ctx));
+  return { behindBody, head: out };
+}
+
+/** The back views (N, NE): the rear art wrapped past 180°. */
+function backHead(ctx: Ctx, p: Parts, isPlaying: boolean, status: Pose['status'], angle: number): HeadNodes {
+  const phi = (angle - 180) * DEG;
+  const warp = turnWarp(phi);
+  const isHairShown = !(p.hat && p.hat.hides === 'all');
+  const hatCut: Clip | undefined = p.hat && typeof p.hat.hides === 'number' ? { shapes: [rect(-120, p.hat.hides, 240, 260, {})] } : undefined;
+  const out: SceneNode[] = [];
+  if (!p.hat?.hidesEars) {
+    out.push(...ears({ ...ctx, phi }, 'behind', p.earExtra));
+  }
+  out.push(...head({ ...ctx, phi: 0 }));
+  if (isHairShown) {
+    const rear = paintShapes(ctx.c, tones(ctx.c.body), p.hair?.rear, warp);
+    out.push(...(hatCut && rear.length > 0 ? [g(rear, { clip: hatCut })] : rear));
+    if (p.hair?.rear.some((s) => s.clip === 'head')) {
+      out.push(path(HEAD_PATH.d(), { fill: 'none', stroke: ctx.c.skinInk, sw: LINE }));
+    }
+  }
+  if (isPlaying) {
+    out.push(...gogglesStrapBack(ctx, phi));
+  }
+  if (p.hat) {
+    out.push(...paintShapes(ctx.c, tones(p.hatColour), p.hat.rear, warp));
+  }
+  if (status === 'headset') {
+    out.push(...headset(ctx, true));
+  }
+  // From behind, long hair falls down the back, over the body.
+  return { behindBody: [], head: out };
+}
+
+/** The grey silhouette: a malformed code, a hidden player, or before the art loads. */
+function silhouette(hasShadow: boolean): SceneNode[] {
+  const grey = '#6f7787';
+  return [
+    ...(hasShadow ? [groundShadow(0)] : []),
+    path('M-35 -2C-42 -20 -38 -46 -22 -56C-8 -62 8 -62 22 -56C38 -46 42 -20 35 -2C20 3 -20 3 -35 -2Z', { fill: grey }),
+    path(HEAD_PATH.d(), { fill: grey }, [tr(0, HEAD_Y), sc(0.94)]),
+  ];
+}
+
+function anchorsFor(headX: number, headY: number, top: number, prop: Point, mirror: number): Record<Anchor, Point> {
+  const at = (px: number, py: number): Point => ({ x: px * mirror, y: py });
+  return {
+    feet: at(0, 0), body: at(0, -30), neck: at(headX, headY + 46), head: at(headX, headY), eyeLine: at(headX, headY + 4),
+    mouth: at(headX, headY + 27), hatTop: at(headX, top), nameplate: at(0, top - 10), bubble: at(0, top - 14),
+    seat: at(0, 0), prop: at(prop.x, prop.y), shadow: at(0, 0), handL: at(-40, -30), handR: at(40, -30), pod: at(0, 14),
+  };
+}
+
+/** Composes a look (or `null` for the silhouette) with a pose. */
+export function composeAvatar(look: AvatarLook | null, opts: RenderOptions = {}): Composed {
+  const art = currentArt();
+  const facingIn = facingOf(opts);
+  const isMirrored = MIRROR[facingIn] !== undefined;
+  const facing: Drawn = MIRROR[facingIn] ?? (facingIn === 'S' || facingIn === 'SE' || facingIn === 'E' || facingIn === 'NE' ? facingIn : 'N');
+  const hasShadow = opts.shadow ?? opts.frame === 'full';
+  if (!look || !art) {
+    return { nodes: silhouette(hasShadow), anchors: anchorsFor(0, HEAD_Y, HEAD_Y - 60, { x: 0, y: -30 }, 1) };
+  }
+  const pose = opts.pose ?? {};
+  const bodyPose = pose.body ?? 'idle';
+  const status = pose.status ?? (bodyPose === 'play' ? 'goggles' : null);
+  const isPlaying = status === 'goggles';
+  const face = pose.face ?? EXPRESSIONS[pose.expression ?? (bodyPose === 'play' ? 'determined' : bodyPose === 'away' ? 'sleepy' : 'neutral')];
+  const gaze = pose.look ?? { x: 0, y: 0 };
+  const angle = FACING_ANGLE[facing];
+  const isBack = angle > 90;
+  const parts = resolveParts(look, art);
+  const ctx: Ctx = {
+    c: parts.c, face, gaze, phi: (angle + gaze.x * 11) * DEG, dy: gaze.y * 3,
+    blink: pose.blink ?? 0, talk: pose.talk ?? 0,
+  };
+  const b = bodyLayout(parts.c, bodyPose, ctx.phi, pose.phase ?? 0.25, opts.stool === true);
+  const headX = b.headDx + (pose.bob?.x ?? 0);
+  const headY = HEAD_Y + b.headDy + (pose.bob?.y ?? 0);
+  const tilt = face.headTilt + b.tilt + (pose.tilt ?? 0);
+  const sq = face.squash + (pose.squash ?? 0);
+  const drawn = isBack ? backHead(ctx, parts, isPlaying, status, angle) : frontHead(ctx, parts, isPlaying, status, angle, gaze.x);
+  const headNodes = drawn.head;
+  const top = headY - 50 - Math.max(parts.hair?.top ?? 0, parts.hat?.top ?? 0);
+  if (status === 'crown') {
+    headNodes.push(...crown(Math.max(parts.hair?.top ?? 0, parts.hat?.top ?? 0)));
+  }
+  const handProps = status && !isBack ? handProp(status, b.prop.x, b.prop.y, parts.c.body, parts.c.bodyInk) : [];
+  const headTf = [tr(headX, headY), rot(tilt), sc(1 + sq, 1 - sq)];
+  const character: SceneNode[] = [
+    ...b.behind,
+    ...(drawn.behindBody.length > 0 ? [g(drawn.behindBody, { tf: headTf })] : []),
+    ...b.body,
+    g(headNodes, { tf: headTf }),
+    ...b.front, ...handProps,
+  ];
+  const lifted = b.lift > 0 ? [g(character, { tf: [tr(0, -b.lift)] })] : character;
+  const rimmed = opts.rim ? [g(lifted, { rim: true })] : lifted;
+  const all: SceneNode[] = [...(hasShadow ? [groundShadow(b.lift)] : []), ...rimmed];
+  const mirror = isMirrored ? -1 : 1;
+  return {
+    nodes: isMirrored ? [g(all, { tf: [sc(-1, 1)] })] : all,
+    anchors: anchorsFor(headX, headY - b.lift, top - b.lift, { x: b.prop.x, y: b.prop.y - b.lift }, mirror),
+  };
+}

package/src/avatar/render/context.ts

@@ -0,0 +1,117 @@
+/**
+ * What every layer needs while drawing, the 2.5D head turn, and painting
+ * catalog shapes into scene nodes.
+ */
+import type { Shape, Slot } from '../art/shape';
+import type { FaceParams } from '../face';
+import { clamp, Path, type Warp } from '../geom';
+import { g, path, type Clip, type SceneNode } from '../scene';
+import { FIXED, type Colours, type Tones } from './colours';
+import type { LookDir } from './types';
+
+/** The skull radius used by the head turn. */
+export const SKULL_R = 46;
+
+/** Style C's outline width at the 100-unit head height (§14.1). */
+export const LINE = 2.4;
+
+/** Part fills are outlined a little thinner than lines (the POC's style C). */
+const FILL_OUTLINE = 0.8;
+
+/** The head outline (centre 0,0; 100 units tall). */
+export const HEAD_PATH = new Path().m(0, -50).c(27, -50, 46, -32, 46, -4).c(46, 24, 30, 50, 0, 50).c(-30, 50, -46, 24, -46, -4).c(-46, -32, -27, -50, 0, -50).z();
+
+/** The head as a clip region. */
+export const HEAD_CLIP: Clip = { shapes: [path(HEAD_PATH.d(), {})] };
+
+/** Drawing state for one head. */
+export interface Ctx {
+  readonly c: Colours;
+  readonly face: FaceParams;
+  readonly gaze: LookDir;
+  /** Head turn, radians: the facing plus a little from the gaze. */
+  readonly phi: number;
+  /** Vertical feature shift from the gaze. */
+  readonly dy: number;
+  /** Extra lid closure (blink). */
+  readonly blink: number;
+  /** Extra mouth opening (talk). */
+  readonly talk: number;
+}
+
+/** Where a face feature centred at `x0` lands after the head turn. */
+export function feat(ctx: Ctx, x0: number): { readonly x: number; readonly sx: number; readonly vis: boolean } {
+  const t0 = Math.asin(clamp(x0 / SKULL_R, -1, 1));
+  const t = t0 + ctx.phi;
+  return { x: SKULL_R * Math.sin(t), sx: Math.max(0.05, Math.cos(t) / Math.cos(t0)), vis: Math.cos(t) > 0.22 };
+}
+
+/**
+ * A warp that wraps a part around the skull by `phi`. Unlike a strict
+ * cylinder, the far side is squeezed toward the silhouette instead of
+ * folding behind it, so outlines never collapse into wedges (§14.2).
+ */
+export function turnWarp(phi: number, dy = 0): Warp | undefined {
+  if (phi === 0 && dy === 0) {
+    return undefined;
+  }
+  const half = Math.PI / 2;
+  return (px, py) => {
+    const ax = Math.abs(px);
+    const sg = Math.sign(px) || 1;
+    const t0 = Math.asin(Math.min(ax, SKULL_R) / SKULL_R) * sg;
+    const lead = phi >= 0 ? (t0 <= 0 ? 1 : 1 - t0 / half) : (t0 >= 0 ? 1 : 1 + t0 / half);
+    const t = t0 + phi * lead;
+    const over = Math.max(0, ax - SKULL_R) * Math.max(0.25, Math.abs(Math.sin(t)));
+    return [SKULL_R * Math.sin(t) + sg * over, py + dy];
+  };
+}
+
+/** Resolves a tint slot. `acc` is the accessory (or hair-tie) colour for this part. */
+export function slotColour(c: Colours, acc: Tones, slot: Slot): string {
+  switch (slot) {
+    case 'none': return 'none';
+    case 'acc': return acc.base;
+    case 'accShade': return acc.shade;
+    case 'accLight': return acc.light;
+    case 'accInk': return acc.ink;
+    case 'ink': return FIXED.ink;
+    case 'white': return FIXED.white;
+    default: return c[slot];
+  }
+}
+
+/** The tonal outline slot for a fill slot. */
+function outlineOf(slot: Slot): Slot {
+  if (slot.startsWith('hair')) {
+    return 'hairInk';
+  }
+  if (slot === 'beard' || slot === 'beardShade' || slot === 'stubble') {
+    return 'beardInk';
+  }
+  if (slot.startsWith('acc')) {
+    return 'accInk';
+  }
+  if (slot.startsWith('skin')) {
+    return 'skinInk';
+  }
+  return 'ink';
+}
+
+/** Paints catalog shapes with an optional warp; `clip: 'head'` shapes are clipped to the head. */
+export function paintShapes(c: Colours, acc: Tones, shapes: readonly Shape[] | undefined, warp?: Warp): SceneNode[] {
+  if (!shapes) {
+    return [];
+  }
+  return shapes.map((s): SceneNode => {
+    const d = s.d.d(warp);
+    const opacity = s.opacity === undefined ? {} : { opacity: s.opacity };
+    if (s.line) {
+      return path(d, { fill: 'none', stroke: slotColour(c, acc, s.stroke ?? 'ink'), sw: s.sw ?? LINE, cap: s.cap ?? 'round', ...opacity });
+    }
+    const strokeSlot = s.stroke ?? outlineOf(s.fill);
+    const stroke = strokeSlot === 'none' ? {} : { stroke: slotColour(c, acc, strokeSlot), sw: (s.sw ?? LINE) * FILL_OUTLINE };
+    const node = path(d, { fill: slotColour(c, acc, s.fill), ...(s.evenOdd ? { evenOdd: true } : {}), ...stroke, ...opacity });
+    return s.clip === 'head' ? g([node], { clip: HEAD_CLIP }) : node;
+  });
+}