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

package/src/avatar/art/hair.ts

@@ -0,0 +1,254 @@
+/** Hair styles (catalog `hair.*`), keyed by the part name. */
+import type { Path} from '../geom';
+import { arc, blob, scallop, type Pt } from '../geom';
+import type { HairPart, Shape, Slot } from './shape';
+
+// ---- helpers -------------------------------------------------------------
+
+/** The skull arc (centre 0,−4) from the left temple over the top to the right. */
+const skull = (vol: number, a0 = 183, a1 = 357, steps = 8): Pt[] => arc(0, -4, 46 + vol, 46 + vol, a0, a1, steps);
+
+/** A cap: the skull arc outset by `vol`, closed by a hairline (right → left). */
+const cap = (vol: number, hairline: readonly Pt[], a0 = 183, a1 = 357): Path => blob([...skull(vol, a0, a1), ...hairline]);
+
+const shine = (r = 40, a0 = 212, a1 = 244): Shape => ({
+  d: blob(arc(0, -4, r, r, a0, a1, 3), false), fill: 'hairLight', line: true, sw: 3.4, stroke: 'hairLight', opacity: 0.85,
+});
+
+/** A smooth back-view cap: down to the nape at `nape`. */
+const rearCap = (vol: number, nape: number, napeW = 40): Path =>
+  blob([...arc(0, -4, 46 + vol, 46 + vol, 162, 378, 10), [napeW + vol * 0.4, nape], [0, nape + 4], [-napeW - vol * 0.4, nape]]);
+
+/** A round, scalloped cloud (afro, puffs, buns). */
+const cloud = (cx: number, cy: number, rx: number, ry: number, count: number, bump: number, phase = 0): Path =>
+  scallop(arc(cx, cy, rx, ry, phase, phase + 360 - 360 / count, count - 1), bump, true);
+
+/** A hanging strand (locs, braids): an outlined thick round line. */
+const strand = (pts: readonly Pt[], w: number, slot: Slot = 'hair'): Shape[] => {
+  const d = blob(pts, false);
+  return [
+    { d, fill: 'none', line: true, stroke: 'hairInk', sw: w + 3 },
+    { d, fill: 'none', line: true, stroke: slot, sw: w },
+  ];
+};
+
+const smoothHairline: Pt[] = [[45, -8], [38, -24], [22, -33], [0, -36], [-22, -33], [-38, -24], [-45, -8]];
+
+// ---- hair ----------------------------------------------------------------
+
+/** Every hair style by name. */
+export const HAIR_ART: Readonly<Record<string, HairPart>> = {
+  bald: {
+    front: [{ d: blob(arc(0, -4, 38, 38, 218, 240, 2), false), fill: 'none', line: true, stroke: 'white', sw: 3.2, opacity: 0.35 }],
+    rear: [],
+    top: 0,
+  },
+
+  buzz: {
+    front: [{
+      d: cap(3, [[46, -10], [40, -22], [26, -29], [0, -32], [-26, -29], [-40, -22], [-46, -10]]),
+      fill: 'hairBuzz', clip: 'head', stroke: 'none',
+    }],
+    rear: [{ d: rearCap(2, 22), fill: 'hairBuzz', clip: 'head', stroke: 'none' }],
+    top: 0,
+  },
+
+  crop: {
+    front: [
+      { d: cap(5, [[45, -8], [41, -21], [29, -29], [15, -27], [2, -33], [-12, -27], [-26, -31], [-39, -22], [-46, -8]]), fill: 'hair' },
+      shine(42),
+    ],
+    rear: [{ d: rearCap(5, 18), fill: 'hair' }],
+    top: 5,
+  },
+
+  swoop: {
+    front: [
+      {
+        d: blob([[-48, -4], [-52, -28], [-42, -50], [-18, -63], [10, -64], [34, -55], [49, -35], [51, -8],
+          [45, -6], [41, -20], [30, -26], [16, -25], [0, -29], [-16, -36], [-30, -40], [-41, -34], [-46, -18]]),
+        fill: 'hair',
+      },
+      { d: blob([[24, -60], [14, -46], [6, -30]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 2.4 },
+      shine(46, 222, 250),
+    ],
+    rear: [{ d: rearCap(7, 16), fill: 'hair' }],
+    top: 14,
+  },
+
+  spiky: {
+    front: [{
+      d: blob([
+        [-48, -4], [-58, -22, 'c'], [-47, -30], [-54, -48, 'c'], [-36, -48], [-30, -66, 'c'], [-16, -55], [-2, -72, 'c'],
+        [8, -56], [26, -68, 'c'], [30, -50], [50, -54, 'c'], [46, -36], [60, -24, 'c'], [48, -4],
+        [44, -10], [38, -26, 'c'], [30, -21], [22, -34, 'c'], [12, -25], [2, -36, 'c'], [-8, -25], [-18, -34, 'c'], [-28, -22], [-38, -29, 'c'], [-45, -10],
+      ]),
+      fill: 'hair',
+    }, shine(40)],
+    rear: [{
+      d: blob([[-48, 14], [-58, -6, 'c'], [-50, -20], [-56, -40, 'c'], [-38, -44], [-30, -64, 'c'], [-14, -54], [0, -70, 'c'], [14, -54], [30, -64, 'c'],
+        [38, -44], [56, -40, 'c'], [50, -20], [58, -6, 'c'], [48, 14], [24, 18, 'c'], [12, 26, 'c'], [0, 20, 'c'], [-12, 26, 'c'], [-24, 18, 'c']]),
+      fill: 'hair',
+    }],
+    top: 20,
+  },
+
+  curly: {
+    back: [{ d: cloud(0, -8, 58, 54, 13, 6, 135), fill: 'hairShade' }],
+    front: [{
+      d: scallop([...skull(9, 180, 360, 9), [48, -6], [40, -20], [28, -28], [14, -30], [0, -29], [-14, -30], [-28, -28], [-40, -20], [-48, -6]], 4.5, true),
+      fill: 'hair',
+    }, shine(44, 214, 238)],
+    rear: [{ d: cloud(0, -6, 58, 58, 15, 6, 0), fill: 'hair' }],
+    top: 16,
+  },
+
+  coily: {
+    front: [{
+      d: scallop([...skull(7, 178, 362, 14), [46, -10], [40, -22], [30, -29], [20, -31], [10, -32], [0, -32], [-10, -32], [-20, -31], [-30, -29], [-40, -22], [-46, -10]], 2.6, true),
+      fill: 'hair',
+    }, shine(42, 218, 240)],
+    rear: [{ d: scallop([...arc(0, -4, 53, 53, 160, 380, 18), [44, 20], [30, 24], [15, 26], [0, 27], [-15, 26], [-30, 24], [-44, 20]], 2.6, true), fill: 'hair' }],
+    top: 10,
+  },
+
+  afro: {
+    back: [{ d: cloud(0, -16, 72, 64, 16, 6.5, 90), fill: 'hair' }],
+    front: [
+      { d: scallop([...skull(4, 186, 354, 6), [44, -12], [36, -24], [24, -30], [12, -31], [0, -31], [-12, -31], [-24, -30], [-36, -24], [-44, -12]], 3.5, true), fill: 'hair', stroke: 'none' },
+      { d: scallop([[44, -12], [36, -24], [24, -30], [12, -31], [0, -31], [-12, -31], [-24, -30], [-36, -24], [-44, -12]], 3.5, false, -1), fill: 'none', line: true, stroke: 'hairInk', sw: 3 },
+      shine(62, 214, 236),
+    ],
+    rear: [{ d: cloud(0, -16, 72, 64, 16, 6.5, 90), fill: 'hair' }],
+    top: 30,
+    coversEars: true,
+  },
+
+  bob: {
+    back: [{ d: blob([[-52, 40, 'c'], [-56, 6], [-56, -28], [-42, -52], [0, -60], [42, -52], [56, -28], [56, 6], [52, 40, 'c']]), fill: 'hairShade' }],
+    front: [{
+      d: blob([[-54, 38, 'c'], [-56, 4], [-53, -28], [-38, -51], [0, -58], [38, -51], [53, -28], [56, 4], [54, 38, 'c'],
+        [43, 36], [41, 10], [42, -14, 'c'], [30, -20], [15, -19], [0, -21], [-15, -19], [-30, -20], [-42, -14, 'c'], [-41, 10], [-43, 36]]),
+      fill: 'hair',
+    }, shine(46, 220, 246)],
+    rear: [{ d: blob([[-54, 40, 'c'], [-57, 4], [-54, -28], [-40, -52], [0, -60], [40, -52], [54, -28], [57, 4], [54, 40, 'c'], [27, 44], [0, 42], [-27, 44]]), fill: 'hair' }],
+    top: 10,
+    coversEars: true,
+  },
+
+  long: {
+    back: [{
+      d: blob([[-50, -10], [-54, -36], [-36, -52], [0, -56], [36, -52], [54, -36], [50, -10], [56, 34], [60, 74, 'c'], [30, 78], [0, 72], [-30, 78], [-60, 74, 'c'], [-56, 34]]),
+      fill: 'hairShade',
+    }],
+    front: [{
+      d: blob([[0, -58, 'c'], [26, -55], [46, -40], [53, -12], [53, 30], [52, 70, 'c'], [43, 62], [41, 30], [41, 0], [35, -20], [20, -31], [7, -38], [0, -46, 'c'],
+        [-7, -38], [-20, -31], [-35, -20], [-41, 0], [-41, 30], [-43, 62], [-52, 70, 'c'], [-53, 30], [-53, -12], [-46, -40], [-26, -55]]),
+      fill: 'hair',
+    }, shine(44, 220, 248)],
+    rear: [{
+      d: blob([[-52, -10], [-58, -40], [-40, -60], [0, -64], [40, -60], [58, -40], [52, -10], [56, 34], [60, 74, 'c'], [30, 78], [0, 74], [-30, 78], [-60, 74, 'c'], [-56, 34]]),
+      fill: 'hair',
+    }, { d: blob([[0, -58], [0, -30], [2, 10]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 2.4 }],
+    top: 14,
+    coversEars: true,
+  },
+
+  ponytail: {
+    back: [
+      { d: blob([[18, -48], [44, -64], [66, -52], [72, -22], [66, 14], [58, 44, 'c'], [52, 12], [48, -18], [34, -40]]), fill: 'hairShade' },
+    ],
+    front: [
+      { d: cap(4, smoothHairline), fill: 'hair' },
+      { d: blob([[34, -52], [40, -44]], false), fill: 'none', line: true, stroke: 'acc', sw: 7, cap: 'round' },
+      shine(42),
+    ],
+    rear: [
+      { d: rearCap(4, 14), fill: 'hair' },
+      { d: blob([[0, -30], [14, -10], [12, 30], [0, 62, 'c'], [-12, 30], [-14, -10]]), fill: 'hair' },
+      { d: blob([[-7, -28], [7, -28]], false), fill: 'none', line: true, stroke: 'acc', sw: 7 },
+    ],
+    top: 14,
+  },
+
+  bun: {
+    back: [{ d: blob(arc(0, -60, 20, 18, 0, 345, 11)), fill: 'hair' }, { d: blob(arc(0, -60, 12, 10, 200, 250, 2), false), fill: 'none', line: true, stroke: 'hairLight', sw: 3 }],
+    front: [
+      { d: cap(4, smoothHairline), fill: 'hair' },
+      { d: blob([[0, -36], [-2, -48]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 2.2 },
+      shine(42, 222, 246),
+    ],
+    rear: [{ d: rearCap(4, 14), fill: 'hair' }, { d: blob(arc(0, -52, 20, 18, 0, 345, 11)), fill: 'hair' }],
+    top: 30,
+  },
+
+  puffs: {
+    back: [{ d: cloud(-46, -40, 20, 20, 9, 4, 20), fill: 'hair' }, { d: cloud(46, -40, 20, 20, 9, 4, 0), fill: 'hair' }],
+    front: [
+      { d: cap(4, smoothHairline), fill: 'hair' },
+      { d: blob([[0, -36], [0, -50]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 2.2 },
+      { d: blob([[-36, -44], [-30, -52]], false), fill: 'none', line: true, stroke: 'acc', sw: 6 },
+      { d: blob([[36, -44], [30, -52]], false), fill: 'none', line: true, stroke: 'acc', sw: 6 },
+    ],
+    rear: [{ d: rearCap(4, 14), fill: 'hair' }, { d: cloud(-46, -40, 20, 20, 9, 4, 20), fill: 'hair' }, { d: cloud(46, -40, 20, 20, 9, 4, 0), fill: 'hair' }],
+    top: 14,
+  },
+
+  mohawk: {
+    front: [
+      { d: cap(2, [[46, -10], [40, -22], [26, -29], [0, -32], [-26, -29], [-40, -22], [-46, -10]]), fill: 'hairBuzz', clip: 'head', stroke: 'none', opacity: 0.55 },
+      {
+        d: blob([[-13, -28], [-18, -50], [-24, -72, 'c'], [-8, -62], [0, -86, 'c'], [8, -62], [24, -72, 'c'], [18, -50], [13, -28], [0, -32]]),
+        fill: 'hair',
+      },
+    ],
+    rear: [
+      { d: rearCap(2, 22), fill: 'hairBuzz', clip: 'head', stroke: 'none', opacity: 0.55 },
+      { d: blob([[-11, 18], [-13, -40], [-14, -60, 'c'], [-6, -54], [0, -72, 'c'], [6, -54], [14, -60, 'c'], [13, -40], [11, 18]]), fill: 'hair' },
+    ],
+    top: 30,
+  },
+
+  locs: {
+    back: [
+      { d: blob([[-50, -10], [-54, -36], [-36, -50], [0, -52], [36, -50], [54, -36], [50, -10], [56, 30], [58, 62, 'c'], [0, 58], [-58, 62, 'c'], [-56, 30]]), fill: 'hairShade' },
+      ...[-44, -30, 30, 44].flatMap((at) => strand([[at, 0], [at * 1.12, 30], [at * 1.12, 60]], 7, 'hairShade')),
+    ],
+    front: [
+      { d: cap(6, [[46, -2], [42, -20], [28, -30], [14, -26], [0, -32], [-14, -26], [-28, -30], [-42, -20], [-46, -2]]), fill: 'hair' },
+      ...strand([[-46, -10], [-50, 14], [-50, 40]], 8),
+      ...strand([[46, -10], [50, 14], [50, 40]], 8),
+      ...strand([[-38, -14], [-41, 8], [-41, 24]], 7),
+      ...strand([[38, -14], [41, 8], [41, 24]], 7),
+      shine(44),
+    ],
+    rear: [
+      { d: rearCap(6, 10), fill: 'hair' },
+      ...[-40, -27, -14, 0, 14, 27, 40].flatMap((at) => strand([[at * 1.05, -6], [at * 1.12, 26], [at * 1.12, 60]], 9)),
+    ],
+    top: 8,
+    coversEars: true,
+  },
+
+  braids: {
+    back: [
+      { d: blob([[-50, -10], [-54, -36], [-36, -50], [0, -52], [36, -50], [54, -36], [50, -10], [54, 30], [54, 70, 'c'], [0, 64], [-54, 70, 'c'], [-54, 30]]), fill: 'hairShade' },
+      ...[-46, -34, 34, 46].flatMap((at) => strand([[at, 0], [at * 1.08, 70]], 6, 'hairShade')),
+    ],
+    front: [
+      { d: cap(4, [[45, -6], [36, -24], [22, -30], [0, -34], [-22, -30], [-36, -24], [-45, -6]]), fill: 'hair' },
+      { d: blob([[0, -34], [0, -52]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 2.2 },
+      ...[-20, -10, 10, 20].map((at): Shape => ({ d: blob([[at, -32], [at * 1.5, -52]], false), fill: 'none', line: true, stroke: 'hairShade', sw: 1.8 })),
+      ...strand([[-46, -8], [-50, 30], [-50, 66]], 6),
+      ...strand([[46, -8], [50, 30], [50, 66]], 6),
+      { d: blob([[-54, 60], [-46, 60]], false), fill: 'none', line: true, stroke: 'acc', sw: 4, cap: 'butt' },
+      { d: blob([[46, 60], [54, 60]], false), fill: 'none', line: true, stroke: 'acc', sw: 4, cap: 'butt' },
+    ],
+    rear: [
+      { d: rearCap(4, 10), fill: 'hair' },
+      ...[-36, -24, -12, 0, 12, 24, 36].flatMap((at) => strand([[at * 1.05, -10], [at * 1.08, 30], [at * 1.08, 66]], 6.5)),
+    ],
+    top: 6,
+    coversEars: true,
+  },
+};

package/src/avatar/art/headwear.ts

@@ -0,0 +1,75 @@
+/** Headwear (catalog `headwear.*`). Head coverings are drawn with care and hide hair and ears (§14.2). */
+import { arc, blob, roundedRect } from '../geom';
+import type { HeadwearPart, Shape } from './shape';
+
+/** Every headwear part by name. */
+export const HEADWEAR_ART: Readonly<Record<string, HeadwearPart>> = {
+  hijab: {
+    // The drape sits over the body; the front frames the face (even-odd hole).
+    back: [{
+      d: blob([[-54, -10], [-56, -40], [-36, -60], [0, -64], [36, -60], [56, -40], [54, -10], [58, 30], [62, 66, 'c'], [30, 74], [0, 72], [-30, 74], [-62, 66, 'c'], [-58, 30]]),
+      fill: 'accShade',
+    }],
+    front: [{
+      d: blob([[-55, -8], [-55, -38], [-36, -58], [0, -62], [36, -58], [55, -38], [55, -8], [54, 28], [44, 56], [20, 66], [0, 66], [-20, 66], [-44, 56], [-54, 28]])
+        .add(blob([[0, -38], [24, -34], [37, -14], [38, 14], [30, 38], [14, 52], [0, 54], [-14, 52], [-30, 38], [-38, 14], [-37, -14], [-24, -34]])),
+      fill: 'acc', evenOdd: true,
+    }, { d: blob([[-30, 60], [-12, 52], [8, 58]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.4 },
+    { d: blob([[-49, -6], [-46, -30], [-30, -48]], false), fill: 'none', line: true, stroke: 'accLight', sw: 3, opacity: 0.8 }],
+    rear: [{
+      d: blob([[-54, -10], [-56, -40], [-36, -60], [0, -64], [36, -60], [56, -40], [54, -10], [58, 30], [62, 66, 'c'], [30, 74], [0, 72], [-30, 74], [-62, 66, 'c'], [-58, 30]]),
+      fill: 'acc',
+    }, { d: blob([[-20, 20], [0, 30], [22, 22]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.4 }],
+    hides: 'all',
+    hidesEars: true,
+    top: 14,
+  },
+  headwrap: {
+    back: [
+      { d: blob([[-12, -56], [-34, -80], [-14, -88], [0, -64]]), fill: 'accShade' },
+      { d: blob([[12, -56], [34, -82], [14, -90], [0, -64]]), fill: 'accShade' },
+    ],
+    front: [
+      { d: blob([[-49, -12], [-54, -38], [-38, -62], [0, -70], [38, -62], [54, -38], [49, -12], [36, -24], [18, -30], [0, -31], [-18, -30], [-36, -24]]), fill: 'acc' },
+      { d: blob([[-44, -22], [-14, -48], [10, -64]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.4 },
+      { d: blob([[44, -22], [20, -44], [2, -50]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.4 },
+      { d: blob(arc(0, -64, 9, 7, 0, 330, 11)), fill: 'acc' },
+    ],
+    rear: [
+      { d: blob([[-49, 4], [-56, -30], [-40, -60], [0, -70], [40, -60], [56, -30], [49, 4], [24, 0], [0, -2], [-24, 0]]), fill: 'acc' },
+      { d: blob([[-40, -8], [-6, -44], [16, -64]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.4 },
+      { d: blob(arc(0, -64, 9, 7, 0, 330, 11)), fill: 'acc' },
+    ],
+    hides: 'all',
+    top: 36,
+  },
+  beanie: {
+    front: [
+      { d: blob([[-50, -22, 'c'], [-50, -40], [-34, -60], [0, -66], [34, -60], [50, -40], [50, -22, 'c']]), fill: 'acc' },
+      { d: roundedRect(-52, -30, 104, 15, 6), fill: 'accShade' },
+      ...[-36, -18, 0, 18, 36].map((at): Shape => ({ d: blob([[at, -27], [at, -18]], false), fill: 'none', line: true, stroke: 'acc', sw: 2.4 })),
+      { d: blob(arc(0, -70, 10, 9, 0, 330, 11)), fill: 'accLight' },
+    ],
+    rear: [
+      { d: blob([[-50, -22, 'c'], [-50, -40], [-34, -60], [0, -66], [34, -60], [50, -40], [50, -22, 'c']]), fill: 'acc' },
+      { d: roundedRect(-52, -30, 104, 15, 6), fill: 'accShade' },
+      { d: blob(arc(0, -70, 10, 9, 0, 330, 11)), fill: 'accLight' },
+    ],
+    hides: -24,
+    top: 28,
+  },
+  cap: {
+    front: [
+      { d: blob([[-49, -22, 'c'], [-48, -42], [-30, -60], [0, -64], [30, -60], [48, -42], [49, -22, 'c'], [0, -26]]), fill: 'acc' },
+      { d: blob([[-6, -63], [-4, -40], [0, -27]], false), fill: 'none', line: true, stroke: 'accShade', sw: 2.2 },
+      { d: blob([[-46, -24, 'c'], [-24, -21], [0, -20], [24, -21], [46, -24, 'c'], [40, -14], [20, -6], [0, -4], [-20, -6], [-40, -14]]), fill: 'accShade' },
+      { d: blob(arc(0, -63, 4, 3, 0, 330, 7)), fill: 'accShade' },
+    ],
+    rear: [
+      { d: blob([[-49, -18, 'c'], [-48, -42], [-30, -60], [0, -64], [30, -60], [48, -42], [49, -18, 'c'], [12, -20], [12, -30, 'c'], [-12, -30, 'c'], [-12, -20]]), fill: 'acc' },
+      { d: roundedRect(-12, -26, 24, 5, 2), fill: 'accShade' },
+    ],
+    hides: -22,
+    top: 18,
+  },
+};

package/src/avatar/art/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The art chunk: every part's path data, keyed by catalog name. Loaded
+ * lazily by `ready()` so `encode`, `decode` and `defaultLook` never pull it
+ * in (avatars.md §3.1).
+ */
+import { BEARD_ART } from './beard';
+import { GLASSES_ART } from './glasses';
+import { HAIR_ART } from './hair';
+import { HEADWEAR_ART } from './headwear';
+import type { FacialHairPart, GlassesPart, HairPart, HeadwearPart } from './shape';
+
+/** Every category's art. */
+export interface ArtSet {
+  readonly hair: Readonly<Record<string, HairPart>>;
+  readonly beard: Readonly<Record<string, FacialHairPart>>;
+  readonly glasses: Readonly<Record<string, GlassesPart>>;
+  readonly headwear: Readonly<Record<string, HeadwearPart>>;
+}
+
+/** The launch art. */
+export const ART: ArtSet = { hair: HAIR_ART, beard: BEARD_ART, glasses: GLASSES_ART, headwear: HEADWEAR_ART };

package/src/avatar/art/shape.ts

@@ -0,0 +1,68 @@
+/**
+ * Part art is authored as point lists on the 100-unit rig (head centre at
+ * 0,0; skull circle centre 0,−4, r 46; eye line y 4; mouth y 27). Every
+ * shape fills a tint slot, never a colour, so any colour works with no new
+ * art. Hair and headwear parts ship a `rear` layer (the back of the head),
+ * used by the back and side facings (avatars.md §3.3, §14.2).
+ */
+import type { Path } from '../geom';
+
+/** A tint slot: the renderer resolves it from the look. */
+export type Slot =
+  | 'hair' | 'hairShade' | 'hairLight' | 'hairBuzz' | 'hairInk'
+  | 'beard' | 'beardShade' | 'beardInk' | 'stubble'
+  | 'acc' | 'accShade' | 'accLight' | 'accInk'
+  | 'skin' | 'skinShade' | 'skinInk' | 'ink' | 'white' | 'none';
+
+/** One painted shape of a part. */
+export interface Shape {
+  readonly d: Path;
+  readonly fill: Slot;
+  /** Outline slot; defaults to the fill's tonal outline. `'none'` for no outline. */
+  readonly stroke?: Slot;
+  readonly sw?: number;
+  /** Clip to the head silhouette (buzz cuts, stubble). */
+  readonly clip?: 'head';
+  readonly opacity?: number;
+  /** A stroke-only line (the fill is ignored). */
+  readonly line?: boolean;
+  readonly cap?: 'round' | 'butt';
+  /** Fill with the even-odd rule (shapes with holes: the hijab's face opening). */
+  readonly evenOdd?: boolean;
+}
+
+/** A hair style: `back` (behind the head), `front` (over the face), `rear` (the back view). */
+export interface HairPart {
+  readonly back?: readonly Shape[];
+  readonly front?: readonly Shape[];
+  readonly rear: readonly Shape[];
+  /** How far the style rises above the skull top (the name-tag anchor). */
+  readonly top: number;
+  /** The style covers the ears. */
+  readonly coversEars?: boolean;
+}
+
+/** Facial hair, as two layers (§14.2): `beard` below the mouth, `moustache` above it. */
+export interface FacialHairPart {
+  readonly beard?: readonly Shape[];
+  readonly moustache?: readonly Shape[];
+}
+
+/** Glasses, drawn per lens so they follow the eyes through a head turn. */
+export interface GlassesPart {
+  readonly lens: Path;
+  readonly bridge: Path;
+}
+
+/**
+ * Headwear. `hides`: `'all'` hides the hair (hijab, headwrap); a number
+ * cuts the hair above that y (hats, §14.2).
+ */
+export interface HeadwearPart {
+  readonly back?: readonly Shape[];
+  readonly front: readonly Shape[];
+  readonly rear: readonly Shape[];
+  readonly hides: 'all' | number;
+  readonly hidesEars?: boolean;
+  readonly top: number;
+}

package/src/avatar/art-store.ts

@@ -0,0 +1,36 @@
+/**
+ * The art chunk is loaded lazily (avatars.md §3.1): `ready()` imports it
+ * once, and every render is synchronous after that. Before it lands, renders
+ * draw the silhouette and `<dg-avatar>` upgrades itself when it arrives.
+ */
+import type { ArtSet } from './art';
+
+let art: ArtSet | null = null;
+let loading: Promise<void> | null = null;
+const waiters = new Set<() => void>();
+
+/** The loaded art, or `null` before {@link ready} resolves. */
+export function currentArt(): ArtSet | null {
+  return art;
+}
+
+/** Loads the art chunk (once). Resolves when rendering is synchronous. */
+export function ready(): Promise<void> {
+  loading ??= import('./art').then((mod) => {
+    art = mod.ART;
+    for (const waiter of waiters) {
+      waiter();
+    }
+    waiters.clear();
+  });
+  return loading;
+}
+
+/** Calls `fn` once the art has loaded (now, when it already has). */
+export function onArtReady(fn: () => void): void {
+  if (art) {
+    fn();
+    return;
+  }
+  waiters.add(fn);
+}