@developerz.ai/ts23d 0.0.0-stage → 0.2.0

package/src/kinds/head-layout.ts

@@ -0,0 +1,63 @@
+// Head landmarks from params: where the cranium, eyes, brow, nose base, mouth, chin, jaw hinge and
+// jaw angle sit, in head units (x front, y left, z up; z 0 = chin of an undropped jaw, x 0 ≈ ear
+// canal). Every edit list reads this one table, so moving the eye line moves lids, brow and nose.
+
+import type { Vec3 } from '../core/index.ts';
+import type { HeadParams } from './head-params.ts';
+
+export interface HeadLayout {
+  /** Cranium ellipsoid centre and radii. */
+  readonly cranium: { readonly at: Vec3; readonly r: Vec3 };
+  /** Forehead front at the eye line. */
+  readonly faceX: number;
+  /** Left eye centre (mirror for the right) and eyeball radius. */
+  readonly eye: Vec3;
+  readonly eyeR: number;
+  readonly browZ: number;
+  readonly noseZ: number;
+  readonly mouthZ: number;
+  /** Front of the lips. */
+  readonly mouthX: number;
+  readonly chin: Vec3;
+  /** Jaw hinge (x, z) — the jaw part's pivot. */
+  readonly hinge: readonly [number, number];
+  /** Left jaw angle (gonion). */
+  readonly angle: Vec3;
+  /** Top of the head, units. */
+  readonly crown: number;
+  /** Bottom of the bust (the asset's z = 0), units. */
+  readonly base: number;
+}
+
+export function headLayout(p: HeadParams): HeadLayout {
+  const L = p.eyes.line;
+  const crH = p.cranium.height;
+  const rx = p.cranium.depth / 2;
+  const ry = p.cranium.width / 2;
+  const rz = crH * 0.8;
+  const cx = -0.02 - p.jaw.muzzle * 0.4;
+  const cz = L + crH * 0.2;
+  const faceX = cx + rx * 0.97;
+  const jut = p.jaw.muzzle;
+  const eyeR = p.eyes.radius;
+  const eye: Vec3 = [faceX - eyeR - p.brow.overhang, p.eyes.spacing, L];
+  const noseZ = L - p.nose.length;
+  const mouthZ = noseZ - 0.1 - p.jaw.drop * 0.3;
+  const chinZ = -p.jaw.drop;
+  const mouthX = faceX - 0.01 + jut + p.jaw.underbite * 0.3;
+  return {
+    cranium: { at: [cx, 0, cz], r: [rx, ry, rz] },
+    faceX,
+    eye,
+    eyeR,
+    browZ: L + eyeR * 0.9 + p.brow.ridge * 0.6,
+    noseZ,
+    mouthZ,
+    mouthX,
+    chin: [faceX - 0.07 + jut + p.jaw.underbite, 0, chinZ + 0.07 * p.jaw.chin],
+    hinge: [cx + 0.04, L - 0.09],
+    angle: [cx - 0.02, p.jaw.width, 0.15 - p.jaw.drop * 0.6],
+    crown: cz + rz,
+    base: -0.85 - p.jaw.drop * 0.5,
+  };
+}

package/src/kinds/head-mesh.ts

@@ -0,0 +1,195 @@
+// Head edit lists → meshes. One skull field is split by the jaw cutter into `head` (skull − cut,
+// smooth-unioned with the ears) and `jaw` (skull ∩ cut, with the tusks), so the two parts share
+// the exact same outer surface; their cut faces are painted mouth-dark for when the jaw opens.
+// Eyeballs are their own spheres: sclera, iris, pupil by angle from the +X gaze.
+
+import type { Mesh, Vec3 } from '../core/index.ts';
+import { type Field, type SculptEdit, sculptField, sd, sdf } from '../primitives/index.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+import { creaseNormals, sharpenRim } from './head-rim.ts';
+import { toned } from './head-tone.ts';
+
+/** Cavity probe of the painted tone, head units: about one fold. */
+const REACH = 0.05;
+/** Default plinth colour (dark slate). */
+export const PLINTH: Vec3 = [0.16, 0.15, 0.15];
+
+/** The jaw region (head units): an ellipsoid around chin and lower lip, cut flat at the mouth
+ *  line. Its skin seam runs along the lips, down the marionette lines and under the chin — creases
+ *  a face already has — instead of across the cheek. */
+export function jawRegion(
+  p: HeadParams,
+  l: HeadLayout,
+): { field: Field; centre: Vec3; radii: Vec3 } {
+  const chin = l.chin;
+  const reach = Math.max(p.mouth.width * 1.08, (p.tusks?.spread ?? 0) + p.mouth.width * 0.5);
+  const centre: Vec3 = [l.mouthX - 0.15, 0, l.mouthZ];
+  const radii: Vec3 = [Math.max(0.27, l.mouthX - chin[0] + 0.2), reach, l.mouthZ - chin[2] + 0.1];
+  const e = sd.ellipsoid(centre, radii);
+  return { field: (q) => Math.max(q[2] - l.mouthZ, e(q)), centre, radii };
+}
+
+const unionBounds = (a: readonly [Vec3, Vec3], b?: readonly [Vec3, Vec3]): [Vec3, Vec3] =>
+  b
+    ? [
+        [Math.min(a[0][0], b[0][0]), Math.min(a[0][1], b[0][1]), Math.min(a[0][2], b[0][2])],
+        [Math.max(a[1][0], b[1][0]), Math.max(a[1][1], b[1][1]), Math.max(a[1][2], b[1][2])],
+      ]
+    : [a[0], a[1]];
+
+/** The jaw region as a sculpt group (ellipsoid ∩ below the mouth line), grown by `grow`. */
+function regionGroup(l: HeadLayout, r: { centre: Vec3; radii: Vec3 }, grow: number): SculptEdit {
+  const cx = r.centre[0];
+  const [rx, ry, rz] = r.radii;
+  return {
+    group: [
+      { shape: 'ellipsoid', at: r.centre, size: [rx + grow, ry + grow, rz + grow] },
+      {
+        shape: 'roundBox',
+        at: [cx, 0, l.mouthZ + grow - 1],
+        size: [4, 4, 2],
+        op: 'intersect',
+      },
+    ],
+    mirror: false,
+    blend: 0,
+  };
+}
+
+export interface HeadEditSet {
+  readonly skull: readonly SculptEdit[];
+  readonly ears: readonly SculptEdit[];
+  readonly tusks: readonly SculptEdit[];
+  readonly bust: readonly SculptEdit[];
+  /** The bust-cut region (≈ 0 on the cut faces), painted as bare plinth material. */
+  readonly bustCut?: Field;
+}
+
+/** `head` and `jaw` meshes in head units at cell size `res` (units). Each is ONE sculpt (skull +
+ *  ears − region, skull ∩ region + tusks), so the sculpt's range skipping covers every edit. */
+export function headAndJaw(
+  p: HeadParams,
+  l: HeadLayout,
+  set: HeadEditSet,
+  res: number,
+): { head: Mesh; jaw: Mesh } {
+  const opts = { color: p.colors.skin, mirror: 'y' as const };
+  const region = jawRegion(p, l);
+  const cut = region.field;
+  // The jaw reaches a little past the cut and sits a hair proud of the skin, so it laps over the
+  // head like a lip: no gap opens along the seam where meshing leaves the two rims a cell apart.
+  const lap = res * 0.75;
+  const proud = res * 0.03;
+  const ears: SculptEdit[] = set.ears.length > 0 ? [{ group: set.ears, blend: 0.02 }] : [];
+  const tusks: SculptEdit[] = set.tusks.length > 0 ? [{ group: set.tusks, blend: 0.01 }] : [];
+  const h = sculptField(
+    [...set.skull, ...ears, { ...regionGroup(l, region, 0), op: 'subtract' }],
+    opts,
+  );
+  const jRaw = sculptField(
+    [...set.skull, { ...regionGroup(l, region, lap), op: 'intersect' }, ...tusks],
+    opts,
+  );
+  const jField: Field = (q) => jRaw.field(q) - proud;
+  const mouth = p.colors.mouth;
+  // Only the skin-only skull is needed near the cut (paint + rim snapping): evaluated lazily.
+  const skull = sculptField(set.skull, opts).field;
+  // The painted tone reads the uncut surface (skin + ears, skin + tusks): the cut faces' normals
+  // would light the jaw rim up as a pale outline.
+  const extra = (e: readonly SculptEdit[]): Field =>
+    e.length > 0
+      ? (
+          (f: Field): Field =>
+          (q) =>
+            Math.min(skull(q), f(q))
+        )(sculptField(e, opts).field)
+      : skull;
+  const headTone = extra(set.ears);
+  const jawTone = extra(set.tusks);
+  const deep = -Math.max(res * 4, 0.03);
+  const paint =
+    (colorAt: (q: Vec3) => Vec3) =>
+    (q: Vec3): Vec3 =>
+      Math.abs(cut(q)) < res * 1.5 && skull(q) < deep ? mouth : colorAt(q);
+  const [ec, er] = [region.centre, region.radii];
+  const jb: [Vec3, Vec3] = [
+    [ec[0] - er[0] - lap, -er[1] - lap, ec[2] - er[2] - lap],
+    [ec[0] + er[0] + lap, er[1] + lap, ec[2] + lap + 0.01],
+  ];
+  const tb = set.tusks.length > 0 ? sculptField(set.tusks, opts).bounds : undefined;
+  const head = sdf({
+    field: h.field,
+    bounds: h.bounds,
+    resolution: res,
+    color: toned(headTone, paint(h.colorAt), { reach: REACH }),
+    symmetry: 'y',
+  });
+  const jaw = sdf({
+    field: jField,
+    bounds: unionBounds(jb, tb),
+    resolution: res,
+    color: toned(jawTone, paint(jRaw.colorAt), { reach: REACH }),
+    symmetry: 'y',
+  });
+  // Coarse cells: snapping folds triangles over, and nobody sees a seam at that distance.
+  if (res > 0.03) return { head: creaseNormals(head), jaw: creaseNormals(jaw) };
+  const jawSkull: Field = (q) => skull(q) - proud;
+  return {
+    // The head's rim lies under the jaw's lap, so only the jaw rim (the visible one) is snapped.
+    head: creaseNormals(head),
+    jaw: creaseNormals(sharpenRim(jaw, jawSkull, (q) => cut(q) - lap, jField, res)),
+  };
+}
+
+/** A surface point lies on a cut face: on the cut boundary, facing out of the cut region. */
+function onCut(cut: Field, q: Vec3, n: Vec3, res: number): boolean {
+  if (Math.abs(cut(q)) > res * 0.8) return false;
+  const e = res * 0.5;
+  const g: Vec3 = [
+    cut([q[0] + e, q[1], q[2]]) - cut([q[0] - e, q[1], q[2]]),
+    cut([q[0], q[1] + e, q[2]]) - cut([q[0], q[1] - e, q[2]]),
+    cut([q[0], q[1], q[2] + e]) - cut([q[0], q[1], q[2] - e]),
+  ];
+  const l = Math.hypot(g[0], g[1], g[2]) || 1;
+  return (g[0] * n[0] + g[1] * n[1] + g[2] * n[2]) / l > 0.85;
+}
+
+export function bustMesh(p: HeadParams, set: HeadEditSet, res: number): Mesh {
+  const s = sculptField(set.bust, { color: p.colors.skin, mirror: 'y' });
+  const tone = toned(s.field, s.colorAt, { reach: REACH * 1.4 });
+  const cut = set.bustCut;
+  const base = p.colors.plinth ?? PLINTH;
+  const face: Vec3 = [base[0] * 1.3, base[1] * 1.3, base[2] * 1.3];
+  return sdf({
+    field: s.field,
+    bounds: s.bounds,
+    resolution: res,
+    // Cut faces read as the bare material of a sculpted bust, not as sliced layers.
+    color: cut ? (q, n) => (onCut(cut, q, n, res) ? face : tone(q)) : tone,
+    symmetry: 'y',
+  });
+}
+
+/** Eyeball of radius `r` centred on the origin, gazing +X. */
+export function eyeMesh(p: HeadParams, r: number, res: number): Mesh {
+  const c = p.colors;
+  const iris = Math.cos(0.62);
+  const limbus = Math.cos(0.7);
+  const pupil = Math.cos(0.3);
+  return sdf({
+    field: (q) => Math.hypot(q[0], q[1], q[2]) - r,
+    bounds: [
+      [-r * 1.3, -r * 1.3, -r * 1.3],
+      [r * 1.3, r * 1.3, r * 1.3],
+    ],
+    resolution: res,
+    color: (q) => {
+      const cos = q[0] / (Math.hypot(q[0], q[1], q[2]) || 1);
+      if (cos > pupil) return c.pupil;
+      if (cos > iris) return c.iris;
+      if (cos > limbus) return [c.iris[0] * 0.45, c.iris[1] * 0.45, c.iris[2] * 0.45];
+      return c.sclera;
+    },
+  });
+}

package/src/kinds/head-mouth.ts

@@ -0,0 +1,111 @@
+// Lips and mouth as edit lists, part of the skull field: upper and lower lip pads (the lower one
+// pushed forward by the underbite), then the opening — a thin scowl line when `grin` is low, or a
+// crescent cut (a wide smile, corners lifted) lined with small pointed teeth along the dental arch
+// when it is high. Head units, mirrored across Y.
+
+import type { SculptEdit } from '../primitives/index.ts';
+import { alongZ } from './head-geom.ts';
+import type { HeadLayout } from './head-layout.ts';
+import type { HeadParams } from './head-params.ts';
+
+export function mouthEdits(p: HeadParams, l: HeadLayout, teeth = true): SculptEdit[] {
+  const c = p.colors;
+  const lipT = p.mouth.lips;
+  const mw = p.mouth.width;
+  const g = p.mouth.grin;
+  const out: SculptEdit[] = [
+    {
+      shape: 'ellipsoid',
+      at: [l.mouthX - 0.01, 0, l.mouthZ + lipT * 0.7],
+      size: [0.032, mw, lipT],
+      color: c.lips,
+      blend: 0.03,
+    },
+    {
+      shape: 'ellipsoid',
+      at: [l.mouthX - 0.015 + p.jaw.underbite * 0.7, 0, l.mouthZ - lipT * 0.8],
+      size: [0.034 + p.jaw.underbite * 0.3, mw * 0.85, lipT * (1.1 + p.jaw.underbite * 4)],
+      color: c.lips,
+      blend: 0.03,
+    },
+  ];
+  // Far LODs carve a grin as a plain wide line: a crescent that thin folds over at coarse cells.
+  if (g < 0.4 || !teeth) {
+    out.push({
+      shape: 'capsule',
+      at: [l.mouthX + 0.05, 0, l.mouthZ],
+      to: [l.mouthX - 0.03 - 0.02 * g, mw * 0.98, l.mouthZ + 0.012 + g * 0.05 - p.brow.scowl * 0.4],
+      size: 0.006 + g * 0.022,
+      op: 'subtract',
+      blend: 0.012,
+      color: c.mouth,
+    });
+    return out;
+  }
+  // A grin: the part of a wide ellipsoid below a higher one — a crescent whose horns rise.
+  const h = 0.035 + g * 0.05;
+  const z0 = l.mouthZ + h * 0.45;
+  const back = mw * 0.55;
+  out.push({
+    group: [
+      { shape: 'ellipsoid', at: [l.mouthX - back, 0, z0], size: [back + 0.06, mw, h] },
+      {
+        shape: 'ellipsoid',
+        at: [l.mouthX - back + 0.02, 0, z0 + h * 0.7],
+        size: [back + 0.12, mw * 1.1, h * 0.9],
+        op: 'subtract',
+      },
+    ],
+    op: 'subtract',
+    blend: 0.012,
+    color: c.mouth,
+  });
+  // A tongue fills the floor of the open mouth (so no flat jaw cut shows through the grin).
+  if (teeth)
+    out.push({
+      shape: 'ellipsoid',
+      at: [l.mouthX - back * 0.9, 0, l.mouthZ - h * 0.4],
+      size: [back * 0.9, mw * 0.62, h * 0.45],
+      color: [0.42, 0.12, 0.12],
+      blend: 0.01,
+    });
+  // The grin bunches the cheeks up and out beside the mouth corners.
+  out.push({
+    shape: 'ellipsoid',
+    at: [l.mouthX - 0.06, mw * 0.95, z0 + h * 0.6],
+    size: [0.05, 0.045, 0.04 + g * 0.01],
+    rotate: [-30, 0, 0],
+    blend: 0.035,
+  });
+  // Teeth: pointed little cones along the arch — the upper row hangs, the lower row rises.
+  const n = teeth ? 3 : 0;
+  for (let i = 0; i < n; i++) {
+    const a = (0.25 + i) * 0.36;
+    const y = Math.sin(a) * mw * 0.82;
+    const x = l.mouthX - 0.03 - (1 - Math.cos(a)) * back * 1.3;
+    // Follow the crescent: roots just inside its upper and lower edges, corners higher.
+    const lo = z0 - h * Math.sqrt(Math.max(0, 1 - (y / mw) ** 2));
+    const hi = z0 + h * 0.7 - h * 0.9 * Math.sqrt(Math.max(0, 1 - (y / (mw * 1.1)) ** 2));
+    const len = 0.03 + g * 0.008 - i * 0.004;
+    const r = 0.014 + g * 0.004 - i * 0.0015;
+    out.push(
+      {
+        shape: 'cone',
+        at: [x, y, hi + 0.008],
+        size: [r, 0.003, len],
+        rotate: alongZ([0.15, 0, -1]),
+        color: c.teeth,
+        blend: 0.004,
+      },
+      {
+        shape: 'cone',
+        at: [x - 0.006, y * 0.97, lo - 0.008],
+        size: [r * 0.85, 0.003, len * 0.6],
+        rotate: alongZ([0.1, 0, 1]),
+        color: c.teeth,
+        blend: 0.004,
+      },
+    );
+  }
+  return out;
+}

package/src/kinds/head-params.ts

@@ -0,0 +1,162 @@
+// Head kind parameters: the typed knobs of a stylised head, in HEAD UNITS (1 = chin to crown of a
+// human-proportioned skull; the builder scales by `height` metres at the end), plus the guard that
+// turns an unusable set into a T3D_RECIPE_INVALID with the fix.
+
+import { Ts23dError, type Vec3 } from '../core/index.ts';
+
+export type EarShape = 'round' | 'pointed';
+export type HairStyle = 'none' | 'topknot' | 'mohawk' | 'swept' | 'tufts' | 'braids';
+export type BeardStyle = 'none' | 'short' | 'braided' | 'goatee';
+export type BustStyle = 'pauldrons' | 'hood' | 'tunic' | 'vest';
+
+export interface HeadColors {
+  readonly skin: Vec3;
+  /** Darker skin: lips edge, nostrils, inner ear, wrinkles. */
+  readonly shade: Vec3;
+  readonly lips: Vec3;
+  readonly sclera: Vec3;
+  readonly iris: Vec3;
+  readonly pupil: Vec3;
+  readonly teeth: Vec3;
+  readonly mouth: Vec3;
+  readonly hair: Vec3;
+  readonly cloth: Vec3;
+  readonly leather: Vec3;
+  readonly metal: Vec3;
+  /** Cloak / mantle over the shoulders; default `leather`. */
+  readonly cape?: Vec3;
+  /** Fur trim on the bust (mantle, hood lining); default `leather`. */
+  readonly fur?: Vec3;
+  /** War paint / tattoo stripes (orc), or none. */
+  readonly paint?: Vec3;
+  /** The bust's plinth (stone/wood socle); default a dark slate. */
+  readonly plinth?: Vec3;
+  /** Scarf / sash cloth (vest style); default `cloth`. */
+  readonly scarf?: Vec3;
+}
+
+export interface HeadParams {
+  /** Chin to crown, metres (adult human ≈ 0.23). */
+  readonly height: number;
+  /** Full width / depth of the brain case; `height` = crown above the eye line. */
+  readonly cranium: { readonly width: number; readonly depth: number; readonly height: number };
+  /** Ridge radius, how far it juts past the eyes, and the scowl (inner ends lowered). */
+  /** Ridge radius, overhang past the eyes, scowl (inner ends lowered), eyebrow hair radius
+   *  (omit or 0 = no eyebrows). */
+  readonly brow: {
+    readonly ridge: number;
+    readonly overhang: number;
+    readonly scowl: number;
+    readonly hair?: number;
+  };
+  readonly cheeks: { readonly size: number; readonly width: number };
+  /** Half-width at the jaw angle, chin size, lower-jaw jut past the upper lip, chin drop,
+   *  muzzle (how far mouth and jaw push forward of the brow: prognathism). */
+  readonly jaw: {
+    readonly muzzle: number;
+    readonly width: number;
+    readonly chin: number;
+    readonly underbite: number;
+    readonly drop: number;
+  };
+  /** Eye line → nose base, nostril half-width, tip radius, hook (droop), bridge projection. */
+  readonly nose: {
+    readonly length: number;
+    readonly width: number;
+    readonly tip: number;
+    readonly hook: number;
+    readonly bridge: number;
+  };
+  /** Length (root → tip), width, sweep back (deg), tilt up (deg). */
+  readonly ears: {
+    readonly shape: EarShape;
+    readonly length: number;
+    readonly width: number;
+    readonly sweep: number;
+    readonly lift: number;
+  };
+  /** Eyeball radius, centre-to-midline, eye line (fraction of height), lid angles (deg). */
+  readonly eyes: {
+    readonly radius: number;
+    readonly spacing: number;
+    readonly line: number;
+    readonly lid: number;
+    readonly lowerLid: number;
+  };
+  /** Half-width, lip thickness, grin (0 = closed line, 1 = wide toothy smile). */
+  readonly mouth: { readonly width: number; readonly lips: number; readonly grin: number };
+  readonly tusks: {
+    readonly length: number;
+    readonly radius: number;
+    readonly spread: number;
+    readonly flare: number;
+  } | null;
+  readonly neck: { readonly radius: number };
+  /** Shoulder half-span, gear style, muscle mass (0 = bony and narrow … 1 = brute; default 0.5). */
+  readonly bust: { readonly shoulders: number; readonly style: BustStyle; readonly mass?: number };
+  readonly hair: HairStyle;
+  readonly beard: BeardStyle;
+  /** Wart / bump count scattered on the skin (seeded). */
+  readonly warts: number;
+  /** Forehead creases (0 = smooth; a goblin's worried brow has 3). */
+  readonly wrinkles?: number;
+  readonly colors: HeadColors;
+}
+
+const bad = (cause: string, fix: string): never => {
+  throw new Ts23dError('T3D_RECIPE_INVALID', { cause, fix });
+};
+
+/** Every number in a params object, with its path, for the finite/positive sweep. */
+function numbers(o: unknown, path: string, out: Array<[string, number]>): void {
+  if (typeof o === 'number') out.push([path, o]);
+  else if (o && typeof o === 'object' && !Array.isArray(o))
+    for (const [k, v] of Object.entries(o)) numbers(v, path ? `${path}.${k}` : k, out);
+}
+
+const SIGNED = new Set([
+  'brow.scowl',
+  'jaw.underbite',
+  'nose.hook',
+  'ears.lift',
+  'ears.sweep',
+  'nose.bridge',
+]);
+const ZERO_OK = new Set([
+  'mouth.grin',
+  'warts',
+  'jaw.drop',
+  'jaw.muzzle',
+  'brow.overhang',
+  'brow.hair',
+  'bust.mass',
+  'wrinkles',
+]);
+
+/** Throws T3D_RECIPE_INVALID (with a fix) when `p` cannot make a head. */
+export function checkHead(p: HeadParams): HeadParams {
+  if (!(p.height >= 0.05 && p.height <= 3))
+    bad(`head height ${p.height} m`, 'give height in metres, chin to crown: human 0.23, orc ≈ 0.3');
+  const flat: Array<[string, number]> = [];
+  numbers({ ...p, colors: undefined, height: undefined }, '', flat);
+  for (const [k, v] of flat) {
+    if (!Number.isFinite(v)) bad(`head param ${k} is ${v}`, 'use finite numbers (head units)');
+    if (SIGNED.has(k)) continue;
+    if (v < 0 || (v === 0 && !ZERO_OK.has(k)))
+      bad(`head param ${k} is ${v}`, `make ${k} > 0 (head units: 1 = chin to crown)`);
+  }
+  const e = p.eyes;
+  if (e.line < 0.3 || e.line > 0.7)
+    bad(`eyes.line ${e.line}`, 'keep the eye line between 0.3 and 0.7 of the head height');
+  if (e.spacing < e.radius * 1.1)
+    bad(
+      `eyes.spacing ${e.spacing} < eyes.radius ${e.radius} × 1.1: the eyeballs overlap`,
+      'raise eyes.spacing (centre to midline) or shrink eyes.radius',
+    );
+  if (e.lid <= e.lowerLid * -1 || e.lid > 80)
+    bad(`eye lids ${e.lid}°/${e.lowerLid}° leave no opening`, 'use lid in (−lowerLid, 80] degrees');
+  if (p.mouth.grin > 1) bad(`mouth.grin ${p.mouth.grin}`, 'grin runs 0 (closed) … 1 (wide)');
+  if (p.tusks && p.tusks.length > 0.6)
+    bad(`tusks.length ${p.tusks.length}`, 'tusks longer than 0.6 head units read as horns');
+  return p;
+}

package/src/kinds/head-presets.ts

@@ -0,0 +1,155 @@
+// Race presets for the head kind: plain `HeadParams` data in head units (1 = chin to crown) —
+// spread one and override (`{ ...orc, tusks: null }` is a tuskless orc). Original stylised designs
+// in the chunky hand-painted fantasy idiom, not copies of any game's characters. Proportions and
+// palettes are documented per recipe in recipes/<race>_head/README.md.
+
+import { hex } from '../material/index.ts';
+import type { HeadParams } from './head-params.ts';
+
+/** Classical proportions, slightly heroic: eye line at half height, thirds brow/nose/chin. */
+export const human: HeadParams = {
+  height: 0.23,
+  cranium: { width: 0.66, depth: 0.86, height: 0.5 },
+  brow: { ridge: 0.035, overhang: 0.03, scowl: 0.012, hair: 0.018 },
+  cheeks: { size: 1, width: 1 },
+  jaw: { muzzle: 0, width: 0.22, chin: 1.05, underbite: 0, drop: 0 },
+  nose: { length: 0.18, width: 0.06, tip: 0.036, hook: 0, bridge: 0 },
+  ears: { shape: 'round', length: 0.27, width: 0.15, sweep: 12, lift: 0 },
+  eyes: { radius: 0.052, spacing: 0.135, line: 0.5, lid: 20, lowerLid: 30 },
+  mouth: { width: 0.1, lips: 0.018, grin: 0 },
+  tusks: null,
+  neck: { radius: 0.27 },
+  bust: { shoulders: 0.95, style: 'tunic' },
+  hair: 'swept',
+  beard: 'short',
+  warts: 0,
+  colors: {
+    skin: hex('#d9a07a'),
+    shade: hex('#a8644a'),
+    lips: hex('#b86b5c'),
+    sclera: hex('#ece6dc'),
+    iris: hex('#3d6e9e'),
+    pupil: hex('#141414'),
+    teeth: hex('#ece2c8'),
+    mouth: hex('#4a1a18'),
+    hair: hex('#5a3a22'),
+    cloth: hex('#2e4f8a'),
+    cape: hex('#7a2420'),
+    leather: hex('#6b4428'),
+    metal: hex('#c9a24a'),
+  },
+};
+
+/** Massive underbitten jaw, tusks, heavy brow over small deep eyes, flat broad nose, thick neck. */
+export const orc: HeadParams = {
+  height: 0.3,
+  cranium: { width: 0.7, depth: 0.74, height: 0.31 },
+  brow: { ridge: 0.075, overhang: 0.06, scowl: 0.04 },
+  cheeks: { size: 1.3, width: 1.15 },
+  jaw: { muzzle: 0.1, width: 0.4, chin: 1.3, underbite: 0.1, drop: 0.1 },
+  nose: { length: 0.15, width: 0.1, tip: 0.042, hook: -0.01, bridge: -0.05 },
+  ears: { shape: 'pointed', length: 0.38, width: 0.19, sweep: 30, lift: 10 },
+  eyes: { radius: 0.054, spacing: 0.155, line: 0.56, lid: 10, lowerLid: 22 },
+  mouth: { width: 0.17, lips: 0.034, grin: 0 },
+  tusks: { length: 0.22, radius: 0.055, spread: 0.15, flare: 0.35 },
+  neck: { radius: 0.38 },
+  bust: { shoulders: 1.0, style: 'pauldrons', mass: 1 },
+  hair: 'topknot',
+  beard: 'none',
+  warts: 6,
+  colors: {
+    skin: hex('#5c8034'),
+    shade: hex('#33501e'),
+    lips: hex('#4f6f30'),
+    sclera: hex('#8a5a1a'),
+    iris: hex('#ffb030'),
+    pupil: hex('#140a06'),
+    teeth: hex('#e2d6b0'),
+    mouth: hex('#2a0e0c'),
+    hair: hex('#231a14'),
+    cloth: hex('#6b2a20'),
+    leather: hex('#5a3a22'),
+    metal: hex('#55524d'),
+    fur: hex('#5e4a34'),
+    paint: hex('#8a1c12'),
+  },
+};
+
+/** Small and sly: huge leaf ears, long hooked nose, wide toothy grin, big bright eyes. */
+export const goblin: HeadParams = {
+  height: 0.19,
+  cranium: { width: 0.66, depth: 0.84, height: 0.5 },
+  brow: { ridge: 0.032, overhang: 0.02, scowl: 0.03 },
+  cheeks: { size: 1.05, width: 1.05 },
+  jaw: { muzzle: 0.05, width: 0.19, chin: 0.72, underbite: 0, drop: 0 },
+  nose: { length: 0.2, width: 0.06, tip: 0.046, hook: 0.065, bridge: 0.13 },
+  ears: { shape: 'pointed', length: 0.66, width: 0.3, sweep: 24, lift: 6 },
+  eyes: { radius: 0.08, spacing: 0.155, line: 0.5, lid: 30, lowerLid: 20 },
+  mouth: { width: 0.21, lips: 0.014, grin: 0.8 },
+  tusks: null,
+  neck: { radius: 0.14 },
+  bust: { shoulders: 0.52, style: 'vest', mass: 0 },
+  hair: 'tufts',
+  beard: 'none',
+  warts: 4,
+  wrinkles: 3,
+  colors: {
+    skin: hex('#9cb84a'),
+    shade: hex('#6a8a2c'),
+    lips: hex('#7a8e36'),
+    sclera: hex('#f0e6a0'),
+    iris: hex('#e0a020'),
+    pupil: hex('#120c04'),
+    teeth: hex('#e8dcae'),
+    mouth: hex('#3a1010'),
+    hair: hex('#c8c0b0'),
+    cloth: hex('#b8a47c'),
+    cape: hex('#4e5e3a'),
+    leather: hex('#6b4428'),
+    metal: hex('#a88a4a'),
+    scarf: hex('#9a3a24'),
+  },
+};
+
+/** Broad and bearded: wide skull, big bulbous nose, braided beard, deep-set eyes. */
+export const dwarf: HeadParams = {
+  ...human,
+  height: 0.24,
+  cranium: { width: 0.74, depth: 0.86, height: 0.48 },
+  brow: { ridge: 0.05, overhang: 0.05, scowl: 0.02, hair: 0.024 },
+  cheeks: { size: 1.25, width: 1.1 },
+  jaw: { muzzle: 0.02, width: 0.27, chin: 1.2, underbite: 0, drop: 0.02 },
+  nose: { length: 0.2, width: 0.08, tip: 0.06, hook: 0.02, bridge: 0.02 },
+  eyes: { radius: 0.045, spacing: 0.14, line: 0.52, lid: 10, lowerLid: 24 },
+  neck: { radius: 0.34 },
+  bust: { shoulders: 1.1, style: 'tunic' },
+  hair: 'braids',
+  beard: 'braided',
+  colors: { ...human.colors, skin: hex('#d49470'), hair: hex('#8a3f1c'), cloth: hex('#4a5a2a') },
+};
+
+/** Slender and ageless: long swept-back ears, high cheekbones, fine nose, almond eyes. */
+export const elf: HeadParams = {
+  ...human,
+  height: 0.235,
+  cranium: { width: 0.62, depth: 0.86, height: 0.52 },
+  brow: { ridge: 0.025, overhang: 0.02, scowl: -0.01, hair: 0.012 },
+  cheeks: { size: 1.1, width: 1.05 },
+  jaw: { muzzle: 0, width: 0.19, chin: 0.85, underbite: 0, drop: 0 },
+  nose: { length: 0.18, width: 0.045, tip: 0.028, hook: 0, bridge: 0.01 },
+  ears: { shape: 'pointed', length: 0.42, width: 0.16, sweep: 40, lift: 24 },
+  eyes: { radius: 0.05, spacing: 0.13, line: 0.5, lid: 14, lowerLid: 22 },
+  bust: { shoulders: 0.85, style: 'tunic' },
+  hair: 'swept',
+  beard: 'none',
+  colors: {
+    ...human.colors,
+    skin: hex('#e8c0a0'),
+    hair: hex('#e0d090'),
+    iris: hex('#3a8a5a'),
+    cloth: hex('#2a6a4a'),
+  },
+};
+
+export const HEADS = { human, orc, goblin, dwarf, elf } as const;
+export type HeadPreset = keyof typeof HEADS;