humanforge 0.3.0 → 0.4.0

package/README.md

@@ -32,6 +32,7 @@ done
 npm run build:human -- mpfb2/src/mpfb/data mh_assets \
   --extra mh_hair01 --extra mh_dress01 --extra mh_suits01  # -> assets/human (~26 MB, all options)
 npm run build:garments                                     # + modest wear and dresses (below)
+npm run build:previews                                     # thumbnails + swatches for every option (needs Chrome)
 ```
 
 Leave out the `--extra` packs for the system set only (~14 MB). Every item loads on demand, so
@@ -110,7 +111,7 @@ import { HumanEditor, useHumanPackage } from 'humanforge/web';
 // React Native (Expo)
 import { HumanEditor, useHumanPackage } from 'humanforge/native';
 
-const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.2.0/assets/human';
+const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.4.0/assets/human';
 const { pkg } = useHumanPackage(ASSETS);
 
 <HumanEditor
@@ -135,7 +136,9 @@ const { pkg } = useHumanPackage(ASSETS);
 | `sections` | Which tabs to show, in order. |
 | `exclude` / `include` | Hide (or whitelist) whole sections or single controls: `'ears'`, `'hair.color'`, `'nose.noseWidth'`, `'body.weight'`… |
 | `items` | Allowed ids per slot: `hair`, `headwear`, `outfit`, `shoes`, `hat`, `skin`, `eyes`, `eyebrows`, `eyelashes`. |
-| `colors` | Palettes for `hair`, `eyebrows`, `skinTint` and `garments` (outfit/headwear fabric). |
+| `colors` | Palettes for `hair`, `eyebrows` and `garments` (outfit/headwear fabric). |
+| `skinTones` | Skin tone ids to offer, in order (default: all of `HUMAN_SKIN_TONES`, light to deep). |
+| `featureSliders` | Also show the face-feature mix sliders (african / asian / caucasian morphs). Off by default. |
 | `optional` | Slots that offer "None" (`hair`, `hat`, `headwear`, `eyebrows`, `shoes`). |
 | `detailRange` | Caps the face/body detail sliders (0..1). |
 | `defaults` / `locked` | Starting values / values that are always enforced. |
@@ -145,7 +148,42 @@ The config is plain JSON; store it as-is. On load, `editor.normalize(saved)` (do
 `<HumanEditor>`) repairs anything the current options don't allow. For example, a male outfit in
 a female-only app gets swapped for a women's one. To display the avatar elsewhere, use
 `<HumanCanvas>` (web) or `<HumanView>` (React Native) with the saved config. To build your own UI,
-`createHumanEditor(pkg.manifest, options)` returns the same sections and controls as data.
+`createHumanEditor(pkg, options)` returns the same sections and controls as data.
+
+#### Previews and swatches (no text options)
+
+Every pickable option ships with a picture or a color, so your UI never has to print item names:
+
+| Attribute (`key`) | Shown as | Source |
+| --- | --- | --- |
+| `skin.tone` | round swatch | 11 tones, light to deep; the texture's age/gender variant follows the avatar automatically |
+| `eyes.color` | round iris image + swatch | `previews/eyes-<id>.webp` |
+| `eyes.lashes`, `brows.style` | thumbnail | close-up renders |
+| `hair.style`, `headwear.style`, `hat.style` | thumbnail | head renders (3/4 view) |
+| `outfit.style` | thumbnail | full-body renders |
+| `shoes.style` | thumbnail | shoe close-ups |
+| `hair.color`, `brows.color`, `outfit.color`, `headwear.color` | round swatch | palettes |
+
+Thumbnails are 192 px transparent WebP files in `assets/human/previews/`, so they sit on any
+background. `None` options have `id: null` and no preview (the built-in editors draw a ⌀ icon).
+
+```tsx
+import { getHumanCatalog } from 'humanforge/human';
+
+const attrs = getHumanCatalog(pkg, { gender: 'female' });   // same options as <HumanEditor>
+const hair = attrs.find((a) => a.key === 'hair.style')!;
+hair.options;        // [{ id: 'long01', label: 'Long straight', preview: 'https://…/previews/hair-long01.webp' }, …]
+hair.value(config);  // selected id
+config = hair.apply(config, 'bob02');                        // new, normalized config
+
+<Image source={{ uri: option.preview }} />                   // display 'image'
+<View style={{ backgroundColor: option.swatch }} />          // display 'swatch'
+```
+
+`label` is only an accessible name (`aria-label` / `accessibilityLabel`); translate it with the
+`labels` option if you show it. The face-feature mix (`african` / `asian` / `caucasian`) is no longer
+shown by default: picking a skin tone only changes color. The selfie fit still sets the mix, and
+`featureSliders: true` brings the sliders back.
 
 ### 4. Selfie to avatar
 
@@ -271,6 +309,7 @@ codes stay valid.
 ```bash
 npm install
 npm run build:human -- <mpfb data> <system assets>   # see above
+npm run build:previews   # option thumbnails + swatches (headless Chrome via puppeteer-core)
 npm test          # both modes: every option builds, codec round-trips, human package decodes, selfie solver
 npm run typecheck
 npm run demo      # http://localhost:5173 (stylized) and /human.html (realistic)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanforge",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Open-source avatar SDK for React and React Native: realistic MakeHuman-based humans (CC0) plus a tiny procedural low-poly mode.",
   "license": "MIT",
   "author": "abdulrehman043",
@@ -51,7 +51,8 @@
     "build:garments": "tsx tools/build-garments.mts",
     "typecheck": "tsc --noEmit",
     "test": "tsx scripts/smoke.ts && tsx scripts/human-smoke.mts && tsx scripts/fit-test.mts && tsx scripts/editor-test.mts",
-    "build:facemap": "tsx tools/build-facemap.mts"
+    "build:facemap": "tsx tools/build-facemap.mts",
+    "build:previews": "tsx tools/build-previews.mts"
   },
   "peerDependencies": {
     "@gltf-transform/core": ">=4",
@@ -103,6 +104,7 @@
     "expo-modules-core": "^3.0.30",
     "gl-matrix": "^3.4.4",
     "meshoptimizer": "^1.3.0",
+    "puppeteer-core": "^24.43.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-native": "^0.81.6",

package/src/human/catalog.ts

@@ -132,6 +132,53 @@ export const HUMAN_HAIR_COLORS: { id: string; label: string; color: string }[] =
 /** Skin tint presets (multiplied over the skin texture; white = texture as-is). */
 export const SKIN_TINTS = ['#ffffff', '#fbefe6', '#f5e3d3', '#ffe9dc', '#efe2d6', '#e8d4c4'];
 
+/**
+ * Skin tone palette shown as swatches. Each tone is a base skin texture family plus a tint
+ * (multiplied over it). The texture's age and gender variant is picked automatically from the
+ * avatar's age and gender (see skinFor), so users only ever choose a color.
+ */
+export interface SkinToneDef { id: string; base: 'caucasian' | 'caucasian2' | 'asian' | 'african'; tint: string }
+export const HUMAN_SKIN_TONES: SkinToneDef[] = [
+  { id: 'porcelain', base: 'caucasian2', tint: '#ffffff' },
+  { id: 'fair', base: 'caucasian', tint: '#ffffff' },
+  { id: 'light', base: 'caucasian', tint: '#f4e2cf' },
+  { id: 'beige', base: 'asian', tint: '#ffffff' },
+  { id: 'warm', base: 'asian', tint: '#f2dcc2' },
+  { id: 'olive', base: 'asian', tint: '#e0c4a2' },
+  { id: 'tan', base: 'caucasian', tint: '#d4ad86' },
+  { id: 'caramel', base: 'asian', tint: '#c99f78' },
+  { id: 'chestnut', base: 'asian', tint: '#ab7f5c' },
+  { id: 'mocha', base: 'asian', tint: '#8d6649' },
+  { id: 'brown', base: 'african', tint: '#ffffff' },
+  { id: 'deep', base: 'african', tint: '#d2bcaa' },
+  { id: 'ebony', base: 'african', tint: '#a99383' },
+];
+
+/** Skin texture family of a skin id, e.g. young_caucasian_female2 -> caucasian2. */
+export function skinBase(id: string): SkinToneDef['base'] {
+  // check caucasian first: 'caucasian' contains 'asian'
+  const eth = id.includes('caucasian') ? 'caucasian' : id.includes('african') ? 'african' : id.includes('asian') ? 'asian' : 'caucasian';
+  return (eth === 'caucasian' && /2$/.test(id) ? 'caucasian2' : eth) as SkinToneDef['base'];
+}
+
+/** The skin texture for a tone family that best matches an age (0..1) and gender (0..1). */
+export function skinFor(skins: string[], base: string, age: number, gender: number): string | null {
+  const eth = base.replace(/2$/, ''), variant = base.endsWith('2') ? '2' : '';
+  const g = gender < 0.5 ? 'female' : 'male';
+  const ages = age < 0.24 ? ['young', 'middleage', 'old'] : age < 0.52 ? ['middleage', 'young', 'old'] : ['old', 'middleage', 'young'];
+  for (const a of ages) for (const v of [variant, '']) {
+    const id = `${a}_${eth}_${g}${v}`;
+    if (skins.includes(id)) return id;
+  }
+  return skins.find((id) => skinBase(id) === base) ?? skins.find((id) => skinBase(id).replace(/2$/, '') === eth) ?? null;
+}
+
+const rgb = (hex: string) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
+const hex = (c: number[]) => '#' + c.map((v) => Math.round(Math.max(0, Math.min(1, v)) * 255).toString(16).padStart(2, '0')).join('');
+/** Multiply two hex colors (how a tint combines with a skin texture). */
+export const multiplyHex = (a: string, b: string) => { const x = rgb(a), y = rgb(b); return hex(x.map((v, i) => v * y[i])); };
+export const hexDistance = (a: string, b: string) => { const x = rgb(a), y = rgb(b); return Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2]); };
+
 const words = (s: string) => s.replace(/_/g, ' ').replace(/(\d+)$/, ' $1').replace(/\s+/g, ' ').trim();
 const cap = (s: string) => s.charAt(0).toUpperCase() + s.slice(1);
 

package/src/human/editor.ts

@@ -6,9 +6,11 @@
 //   editor.sections   -> [{ id: 'face', label: 'Face', controls: [...] }, ...]
 //   editor.initial    -> a valid HumanConfig that respects the options
 //   editor.normalize(savedConfig) -> clamps/repairs any config to the options (use on load)
-import { DEFAULT_HUMAN, HumanConfig, HumanManifest } from './runtime';
+import { DEFAULT_HUMAN, HumanConfig, HumanManifest, HumanPackage } from './runtime';
 import { DETAIL_SLIDERS, MACRO_SLIDERS } from './sliders';
-import { EYE_LABELS, EYE_SWATCH, GARMENT_COLORS, HUMAN_HAIR_COLORS, SKIN_TINTS, clothingInfo, fits, hairInfo, skinInfo } from './catalog';
+import {
+  EYE_LABELS, EYE_SWATCH, GARMENT_COLORS, HUMAN_HAIR_COLORS, HUMAN_SKIN_TONES, clothingInfo, fits, hairInfo, hexDistance, multiplyHex, skinBase, skinFor, skinInfo,
+} from './catalog';
 
 export type EditorGender = 'female' | 'male' | 'any';
 export type SectionId = 'body' | 'face' | 'skin' | 'eyes' | 'brows' | 'nose' | 'mouth' | 'ears' | 'hair' | 'headwear' | 'outfit' | 'shoes' | 'hat';
@@ -28,7 +30,11 @@ export interface HumanEditorOptions {
   /** Allowed item ids per slot (default: everything that fits the gender). */
   items?: Partial<Record<ItemSlot, string[]>>;
   /** Color palettes. */
-  colors?: { hair?: string[]; eyebrows?: string[]; skinTint?: string[]; garments?: string[] };
+  colors?: { hair?: string[]; eyebrows?: string[]; garments?: string[] };
+  /** Skin tone ids to offer (see HUMAN_SKIN_TONES), in order. Default: all, light to deep. */
+  skinTones?: string[];
+  /** Also show the face-feature mix sliders (african / asian / caucasian morphs). Default false. */
+  featureSliders?: boolean;
   /** Slots that may be empty ("None" option). Default: hat, headwear and eyebrows. */
   optional?: Partial<Record<'hair' | 'hat' | 'headwear' | 'eyebrows' | 'shoes', boolean>>;
   /** Max magnitude of face/body detail sliders (0..1). Lower keeps faces more natural. Default 1. */
@@ -43,8 +49,23 @@ export interface HumanEditorOptions {
 
 interface Base { id: string; label: string }
 export interface SliderControl extends Base { kind: 'slider'; min: number; max: number; step: number; value(c: HumanConfig): number; apply(c: HumanConfig, v: number): HumanConfig }
-export interface ChoiceOption { id: string | null; label: string; swatch?: string }
-export interface ChoiceControl extends Base { kind: 'choice'; options: ChoiceOption[]; value(c: HumanConfig): string | null; apply(c: HumanConfig, v: string | null): HumanConfig }
+export interface ChoiceOption {
+  id: string | null;
+  /** Accessible name (the built-in editors don't print it when a preview or swatch exists). */
+  label: string;
+  /** Hex color to show as a round swatch (skin tones, eye colors). */
+  swatch?: string;
+  /** Absolute URL of a transparent WebP thumbnail (hair, brows, lashes, clothes, eyes). */
+  preview?: string;
+}
+export interface ChoiceControl extends Base {
+  kind: 'choice';
+  /** 'image': tiles with previews; 'swatch': round color swatches. */
+  display: 'image' | 'swatch';
+  options: ChoiceOption[];
+  value(c: HumanConfig): string | null;
+  apply(c: HumanConfig, v: string | null): HumanConfig;
+}
 export interface ColorControl extends Base { kind: 'color'; colors: string[]; value(c: HumanConfig): string; apply(c: HumanConfig, v: string): HumanConfig }
 export type EditorControl = SliderControl | ChoiceControl | ColorControl;
 export interface EditorSection { id: SectionId; label: string; framing: 'face' | 'body'; controls: EditorControl[] }
@@ -85,7 +106,15 @@ const GENDER_DEFAULTS: Record<'female' | 'male', Partial<HumanConfig>> = {
 
 const withDetail = (c: HumanConfig, id: string, v: number): HumanConfig => ({ ...c, detail: { ...c.detail, [id]: v } });
 
-export function createHumanEditor(manifest: HumanManifest, options: HumanEditorOptions = {}): HumanEditorModel {
+/**
+ * Build the editor model. Pass the loaded package (preferred: option previews get absolute URLs)
+ * or just its manifest.
+ */
+export function createHumanEditor(source: HumanPackage | HumanManifest, options: HumanEditorOptions = {}): HumanEditorModel {
+  const manifest: HumanManifest = 'manifest' in source ? source.manifest : source;
+  const baseUrl = 'manifest' in source ? source.baseUrl.replace(/\/$/, '') + '/' : '';
+  const url = (rel?: string) => (rel ? baseUrl + rel : undefined);
+  const proxyPreview = (kind: string, id: string) => url(manifest.proxies.find((p) => p.kind === kind && p.id === id)?.preview);
   const gender = options.gender ?? 'any';
   const exclude = new Set(options.exclude ?? []);
   const include = options.include ? new Set(options.include) : null;
@@ -116,7 +145,25 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
 
   const hairColors = options.colors?.hair ?? HUMAN_HAIR_COLORS.map((h) => h.color);
   const browColors = options.colors?.eyebrows ?? hairColors;
-  const tints = options.colors?.skinTint ?? SKIN_TINTS;
+  // skin tones: base texture family x tint, previewed as the color it renders
+  const skinIds = allowed.skin;
+  const baseColor = (base: string) => {
+    const cols = manifest.skins.filter((s) => skinBase(s.id) === base && s.swatch && skinIds.includes(s.id)).map((s) => s.swatch!);
+    if (!cols.length) return null;
+    const avg = [1, 3, 5].map((i) => cols.reduce((a, c) => a + parseInt(c.slice(i, i + 2), 16), 0) / cols.length);
+    return '#' + avg.map((v) => Math.round(v).toString(16).padStart(2, '0')).join('');
+  };
+  const lum = (h: string) => 0.299 * parseInt(h.slice(1, 3), 16) + 0.587 * parseInt(h.slice(3, 5), 16) + 0.114 * parseInt(h.slice(5, 7), 16);
+  const tones = HUMAN_SKIN_TONES
+    .filter((t) => (!options.skinTones || options.skinTones.includes(t.id)) && skinIds.some((id) => skinBase(id) === t.base))
+    .map((t) => ({ ...t, swatch: multiplyHex(baseColor(t.base) ?? '#c9a58a', t.tint) }));
+  if (!options.skinTones) tones.sort((a, b) => lum(b.swatch) - lum(a.swatch));
+  const toneOf = (c: HumanConfig) => {
+    const base = skinBase(c.skin);
+    const same = tones.filter((t) => t.base === base);
+    const pool = same.length ? same : tones;
+    return pool.reduce((best, t) => (hexDistance(t.tint, c.skinTint) < hexDistance(best.tint, c.skinTint) ? t : best), pool[0]);
+  };
   const garmentColors = options.colors?.garments ?? GARMENT_COLORS.map((g) => g.color);
   const tintable = (id: string) => !!manifest.proxies.find((p) => p.kind === 'clothes' && p.id === id)?.tintable;
   const defaultColor = (id: string | undefined) => manifest.proxies.find((p) => p.kind === 'clothes' && p.id === id)?.color;
@@ -134,14 +181,14 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
       value: (c) => c.detail[id] ?? 0, apply: (c, v) => withDetail(c, id, v),
     };
   };
-  const choice = (id: string, lbl: string, opts: ChoiceOption[], value: ChoiceControl['value'], apply: ChoiceControl['apply']): ChoiceControl =>
-    ({ kind: 'choice', id, label: label(id, lbl), options: opts, value, apply });
+  const choice = (id: string, lbl: string, opts: ChoiceOption[], value: ChoiceControl['value'], apply: ChoiceControl['apply'], display: ChoiceControl['display'] = 'image'): ChoiceControl =>
+    ({ kind: 'choice', id, label: label(id, lbl), display, options: opts, value, apply });
   const color = (id: string, lbl: string, colors: string[], value: ColorControl['value'], apply: ColorControl['apply']): ColorControl =>
     ({ kind: 'color', id, label: label(id, lbl), colors, value, apply });
   const none = (on: boolean): ChoiceOption[] => (on ? [{ id: null, label: label('none', 'None') }] : []);
   const worn = (c: HumanConfig, slot: WearSlot) => c.clothes.find((id) => clothingInfo(id).slot === slot);
   const clothingChoice = (slot: WearSlot, lbl: string, canBeEmpty: boolean) => choice('style', lbl,
-    [...none(canBeEmpty), ...allowed[slot].map((id) => ({ id, label: label(id, clothingInfo(id).label) }))],
+    [...none(canBeEmpty), ...allowed[slot].map((id) => ({ id, label: label(id, clothingInfo(id).label), preview: proxyPreview('clothes', id) }))],
     (c) => worn(c, slot) ?? null,
     (c, v) => ({ ...c, clothes: [...c.clothes.filter((id) => clothingInfo(id).slot !== slot && !(v && clothingInfo(id).slot === CONFLICTS[slot])), ...(v ? [v] : [])] }));
   /** Fabric color of the tintable garment in a slot (only shown when the slot offers one). */
@@ -152,23 +199,28 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
 
   const build: Record<SectionId, () => EditorControl[]> = {
     face: () => [
-      ...(['african', 'asian', 'caucasian'] as const).map((k) => macro(k, { african: 'African features', asian: 'Asian features', caucasian: 'European features' }[k])),
+      ...(options.featureSliders ? (['african', 'asian', 'caucasian'] as const).map((k) => macro(k, { african: 'African features', asian: 'Asian features', caucasian: 'European features' }[k])) : []),
       ...DETAIL_SLIDERS.filter((d) => d.group === 'head').map((d) => detail(d.id)),
     ],
     skin: () => [
-      choice('tone', 'Skin', allowed.skin.map((id) => ({ id, label: label(id, skinInfo(id, manifest.skins.find((s) => s.id === id)?.tags ?? []).label) })),
-        (c) => c.skin, (c, v) => ({ ...c, skin: v ?? c.skin })),
-      color('tint', 'Tint', tints, (c) => c.skinTint, (c, v) => ({ ...c, skinTint: v })),
+      choice('tone', 'Skin tone', tones.map((t) => ({ id: t.id, label: label(t.id, t.id.charAt(0).toUpperCase() + t.id.slice(1)), swatch: t.swatch })),
+        (c) => toneOf(c)?.id ?? null,
+        (c, v) => {
+          const t = tones.find((x) => x.id === v);
+          return t ? { ...c, skin: skinFor(skinIds, t.base, c.age, c.gender) ?? c.skin, skinTint: t.tint } : c;
+        }, 'swatch'),
     ],
     eyes: () => [
-      choice('color', 'Eye color', allowed.eyes.map((id) => ({ id, label: label(id, EYE_LABELS[id] ?? id), swatch: EYE_SWATCH[id] })),
-        (c) => c.eyes, (c, v) => ({ ...c, eyes: v ?? c.eyes })),
-      choice('lashes', 'Lashes', [...none(true), ...allowed.eyelashes.map((id, i) => ({ id, label: `${i + 1}` }))],
+      choice('color', 'Eye color', allowed.eyes.map((id) => ({
+        id, label: label(id, EYE_LABELS[id] ?? id),
+        swatch: manifest.eyeOptions?.[id]?.swatch ?? EYE_SWATCH[id], preview: url(manifest.eyeOptions?.[id]?.preview),
+      })), (c) => c.eyes, (c, v) => ({ ...c, eyes: v ?? c.eyes }), 'swatch'),
+      choice('lashes', 'Lashes', [...none(true), ...allowed.eyelashes.map((id, i) => ({ id, label: label(id, `Lashes ${i + 1}`), preview: proxyPreview('eyelashes', id) }))],
         (c) => c.eyelashes, (c, v) => ({ ...c, eyelashes: v })),
       ...DETAIL_SLIDERS.filter((d) => d.group === 'eyes' && !BROW_SLIDERS.includes(d.id)).map((d) => detail(d.id)),
     ],
     brows: () => [
-      choice('style', 'Brows', [...none(optional.eyebrows), ...allowed.eyebrows.map((id, i) => ({ id, label: `${i + 1}` }))],
+      choice('style', 'Brows', [...none(optional.eyebrows), ...allowed.eyebrows.map((id, i) => ({ id, label: label(id, `Brows ${i + 1}`), preview: proxyPreview('eyebrows', id) }))],
         (c) => c.eyebrows, (c, v) => ({ ...c, eyebrows: v })),
       color('color', 'Brow color', browColors, (c) => c.eyebrowColor, (c, v) => ({ ...c, eyebrowColor: v })),
       ...BROW_SLIDERS.map(detail),
@@ -177,7 +229,7 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
     mouth: () => DETAIL_SLIDERS.filter((d) => d.group === 'mouth').map((d) => detail(d.id)),
     ears: () => DETAIL_SLIDERS.filter((d) => d.group === 'ears').map((d) => detail(d.id)),
     hair: () => [
-      choice('style', 'Hairstyle', [...none(optional.hair), ...allowed.hair.map((id) => ({ id, label: label(id, hairInfo(id).label) }))],
+      choice('style', 'Hairstyle', [...none(optional.hair), ...allowed.hair.map((id) => ({ id, label: label(id, hairInfo(id).label), preview: proxyPreview('hair', id) }))],
         (c) => c.hair, (c, v) => ({ ...c, hair: v })),
       color('color', 'Hair color', hairColors, (c) => c.hairColor, (c, v) => ({ ...c, hairColor: v })),
     ],
@@ -211,7 +263,8 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
     const c: HumanConfig = { ...base, ...input, ...options.locked, detail: { ...base.detail, ...input?.detail, ...options.locked?.detail } } as HumanConfig;
     if (gender !== 'any') c.gender = options.locked?.gender ?? (gender === 'female' ? Math.min(c.gender, 0.3) : Math.max(c.gender, 0.7));
     for (const [k, v] of Object.entries(c.detail)) c.detail[k] = Math.max(-range, Math.min(range, v));
-    c.skin = pick(c.skin, allowed.skin, closestSkin(c.skin, allowed.skin, manifest) ?? base.skin) ?? c.skin;
+    // keep the chosen tone family, but follow the avatar's age and gender with the texture variant
+    c.skin = skinFor(allowed.skin, skinBase(c.skin), c.age, c.gender) ?? pick(c.skin, allowed.skin, closestSkin(c.skin, allowed.skin, manifest) ?? base.skin) ?? c.skin;
     c.eyes = pick(c.eyes, allowed.eyes, base.eyes) ?? c.eyes;
     c.hair = c.hair === null && optional.hair ? null : pick(c.hair, allowed.hair, base.hair);
     c.eyebrows = c.eyebrows === null && optional.eyebrows ? null : pick(c.eyebrows, allowed.eyebrows, base.eyebrows);
@@ -265,3 +318,59 @@ function closestSkin(id: string, allowed: string[], manifest: HumanManifest) {
   }
   return best;
 }
+
+// ---------------------------------------------------------------- catalog for custom UIs
+export interface CatalogOption {
+  /** Value to pass to `apply` (null = "none"). */
+  id: string | null;
+  /** Accessible name; not meant as visible text. */
+  label: string;
+  /** Hex color for round swatches (skin tones, eye colors, hair/brow/fabric colors). */
+  swatch?: string;
+  /** Absolute URL of a transparent WebP thumbnail (hair, brows, lashes, outfits, shoes, hats, headwear, eyes). */
+  preview?: string;
+}
+export interface CatalogAttribute {
+  /** e.g. 'hair.style', 'skin.tone', 'eyes.color', 'outfit.color' */
+  key: string;
+  section: SectionId;
+  label: string;
+  /** How to show the options: 'image' -> thumbnails, 'swatch' -> round color swatches. */
+  display: 'image' | 'swatch';
+  options: CatalogOption[];
+  /** The selected option id for a config. */
+  value(c: HumanConfig): string | null;
+  /** A new config with this option selected (already normalized). */
+  apply(c: HumanConfig, id: string | null): HumanConfig;
+}
+
+/**
+ * Every pickable (non-slider) attribute with its preview images or color swatches, for apps that
+ * build their own avatar UI. Respects the same options as the editor (gender lock, items, …).
+ *
+ *   const attrs = getHumanCatalog(pkg, { gender: 'female' });
+ *   attrs.find((a) => a.key === 'hair.style')!.options  // [{ id: 'long01', preview: 'https://…/previews/hair-long01.webp' }, …]
+ *   config = attr.apply(config, option.id);
+ */
+export function getHumanCatalog(source: HumanPackage | HumanManifest | HumanEditorModel, options?: HumanEditorOptions): CatalogAttribute[] {
+  const editor = 'sections' in source ? source : createHumanEditor(source, options);
+  const out: CatalogAttribute[] = [];
+  for (const s of editor.sections) {
+    for (const ctl of s.controls) {
+      if (ctl.kind === 'slider') continue;
+      const key = `${s.id}.${ctl.id}`;
+      if (ctl.kind === 'choice') {
+        out.push({
+          key, section: s.id, label: ctl.label, display: ctl.display, options: ctl.options,
+          value: ctl.value, apply: (c, id) => editor.normalize(ctl.apply(c, id)),
+        });
+      } else {
+        out.push({
+          key, section: s.id, label: ctl.label, display: 'swatch', options: ctl.colors.map((c) => ({ id: c, label: c, swatch: c })),
+          value: (c) => ctl.value(c), apply: (c, id) => (id ? editor.normalize(ctl.apply(c, id)) : c),
+        });
+      }
+    }
+  }
+  return out;
+}

package/src/human/runtime.ts

@@ -63,6 +63,8 @@ export interface ProxyMeta {
   roughness?: number;
   /** Texture coordinates are in tiles (repeat wrapping). */
   tileable?: boolean;
+  /** Transparent WebP thumbnail, relative to the package root (tools/build-previews.mts). */
+  preview?: string;
 }
 export interface HumanManifest {
   vertexCount: number;
@@ -74,8 +76,11 @@ export interface HumanManifest {
   };
   bones: { name: string; parent: number; head: number[]; tail: number[] }[];
   proxies: ProxyMeta[];
-  skins: { id: string; tags: string[] }[];
+  /** `swatch`: the skin tone as rendered (hex), from tools/build-previews.mts. */
+  skins: { id: string; tags: string[]; swatch?: string }[];
   eyes: string[];
+  /** Iris color and round iris thumbnail per eye color (tools/build-previews.mts). */
+  eyeOptions?: Record<string, { swatch: string; preview: string }>;
   textureSizes: { skin1k: number; skin2k: number; eyes: number };
   expressions: Record<string, string>;
 }

package/src/native/HumanEditor.tsx

@@ -3,7 +3,7 @@
 //
 //   <HumanEditor pkg={pkg} options={{ gender: 'female', exclude: ['ears'] }} onSave={(config, png) => save(config)} />
 import React, { useMemo, useRef, useState } from 'react';
-import { LayoutChangeEvent, PanResponder, Pressable, ScrollView, StyleSheet, Text, View, ViewStyle, StyleProp } from 'react-native';
+import { Image, LayoutChangeEvent, PanResponder, Pressable, ScrollView, StyleSheet, Text, View, ViewStyle, StyleProp } from 'react-native';
 import type { HumanConfig, HumanPackage } from '../human/runtime';
 import { EditorControl, HumanEditorModel as EditorModel, HumanEditorOptions, createHumanEditor } from '../human/editor';
 import { HumanView, HumanViewHandle } from './HumanView';
@@ -32,7 +32,7 @@ export function HumanEditor({
   pkg, options, editor: given, value, defaultValue, onChange, onSave, onCancel, saveLabel = 'Save', randomize = true,
   accentColor = '#1d1d1f', background = '#e9ecf1', style,
 }: HumanEditorProps) {
-  const editor = useMemo(() => given ?? createHumanEditor(pkg.manifest, options), [given, pkg, JSON.stringify(options)]);
+  const editor = useMemo(() => given ?? createHumanEditor(pkg, options), [given, pkg, JSON.stringify(options)]);
   const [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
   const config = value ? editor.normalize(value) : inner;
   const [tab, setTab] = useState(0);
@@ -110,15 +110,31 @@ function Control({ ctl, config, onChange, accent }: { ctl: EditorControl; config
     );
   }
   const v = ctl.value(config);
+  if (ctl.display === 'swatch') {
+    return (
+      <View style={s.block}>
+        <Text style={s.blockLabel}>{ctl.label}</Text>
+        <View style={s.wrap}>
+          {ctl.options.map((o) => (
+            <Pressable key={o.id ?? 'none'} accessibilityLabel={o.label} onPress={() => onChange(ctl.apply(config, o.id))}
+              style={[s.swatch, { backgroundColor: o.swatch ?? '#eee' }, o.id === v && { borderColor: accent }]}>
+              {o.preview ? <Image source={{ uri: o.preview }} style={s.swatchImg} /> : null}
+            </Pressable>
+          ))}
+        </View>
+      </View>
+    );
+  }
   return (
     <View style={s.block}>
       <Text style={s.blockLabel}>{ctl.label}</Text>
       <View style={s.wrap}>
         {ctl.options.map((o) => (
-          <Pressable key={o.id ?? 'none'} onPress={() => onChange(ctl.apply(config, o.id))}
-            style={[s.choice, o.id === v && { borderColor: accent, borderWidth: 2 }]}>
-            {o.swatch ? <View style={[s.dot, { backgroundColor: o.swatch }]} /> : null}
-            <Text style={[s.choiceText, o.id === v && { fontWeight: '700' }]}>{o.label}</Text>
+          <Pressable key={o.id ?? 'none'} accessibilityLabel={o.label} onPress={() => onChange(ctl.apply(config, o.id))}
+            style={[s.tile, o.id === v && { borderColor: accent, borderWidth: 2, backgroundColor: '#fff' }]}>
+            {o.id === null ? <View style={s.none}><View style={s.noneBar} /></View>
+              : o.preview ? <Image source={{ uri: o.preview }} style={s.tileImg} resizeMode="contain" />
+              : <Text style={s.choiceText}>{o.label}</Text>}
           </Pressable>
         ))}
       </View>
@@ -173,10 +189,13 @@ const s = StyleSheet.create({
   block: { marginVertical: 10 },
   blockLabel: { fontSize: 13, fontWeight: '600', color: '#333', marginBottom: 8 },
   wrap: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
-  choice: { flexDirection: 'row', alignItems: 'center', gap: 6, borderWidth: 1, borderColor: '#e1e3e7', borderRadius: 10, paddingHorizontal: 12, paddingVertical: 9, minWidth: 64, justifyContent: 'center' },
-  choiceText: { fontSize: 12, color: '#1d1d1f' },
-  dot: { width: 12, height: 12, borderRadius: 6 },
-  swatch: { width: 32, height: 32, borderRadius: 16, borderWidth: 3, borderColor: '#fff', shadowColor: '#000', shadowOpacity: 0.15, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+  tile: { width: 76, height: 76, borderRadius: 12, borderWidth: 1, borderColor: '#e1e3e7', backgroundColor: '#f4f5f7', alignItems: 'center', justifyContent: 'center', overflow: 'hidden', padding: 3 },
+  tileImg: { width: '100%', height: '100%' },
+  none: { width: 26, height: 26, borderRadius: 13, borderWidth: 2, borderColor: '#9aa0a8', alignItems: 'center', justifyContent: 'center' },
+  noneBar: { width: 30, height: 2, backgroundColor: '#9aa0a8', transform: [{ rotate: '-45deg' }] },
+  choiceText: { fontSize: 11, color: '#555', textAlign: 'center' },
+  swatch: { width: 36, height: 36, borderRadius: 18, borderWidth: 3, borderColor: '#fff', overflow: 'hidden', shadowColor: '#000', shadowOpacity: 0.15, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+  swatchImg: { width: '100%', height: '100%' },
   slider: { flex: 1, height: 32, justifyContent: 'center' },
   track: { height: 4, borderRadius: 2, backgroundColor: '#e3e5e8', overflow: 'hidden' },
   fill: { height: 4 },

package/src/web/HumanEditor.tsx

@@ -35,7 +35,7 @@ export function HumanEditor({
   pkg, options, editor: given, value, defaultValue, onChange, onSave, saveLabel = 'Save', selfie = false, randomize = true,
   accentColor = '#1d1d1f', background = '#e9ecf1', className, style,
 }: HumanEditorProps) {
-  const editor = useMemo(() => given ?? createHumanEditor(pkg.manifest, options), [given, pkg, JSON.stringify(options)]);
+  const editor = useMemo(() => given ?? createHumanEditor(pkg, options), [given, pkg, JSON.stringify(options)]);
   const [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
   const config = value ? editor.normalize(value) : inner;
   const [tab, setTab] = useState(0);
@@ -136,14 +136,27 @@ function Control({ ctl, config, onChange }: { ctl: EditorControl; config: HumanC
     );
   }
   const v = ctl.value(config);
+  if (ctl.display === 'swatch') {
+    return (
+      <div className="hf-block">
+        <span className="hf-label">{ctl.label}</span>
+        <div className="hf-swatches">
+          {ctl.options.map((o) => (
+            <button key={o.id ?? 'none'} aria-label={o.label} title={o.label} className={`hf-swatch ${o.id === v ? 'on' : ''}`}
+              style={{ background: o.preview ? `center/cover url("${o.preview}") ${o.swatch ?? ''}` : o.swatch ?? '#eee' }}
+              onClick={() => onChange(ctl.apply(config, o.id))} />
+          ))}
+        </div>
+      </div>
+    );
+  }
   return (
     <div className="hf-block">
       <span className="hf-label">{ctl.label}</span>
-      <div className="hf-choices">
+      <div className="hf-tiles">
         {ctl.options.map((o) => (
-          <button key={o.id ?? 'none'} className={`hf-choice ${o.id === v ? 'on' : ''}`} onClick={() => onChange(ctl.apply(config, o.id))}>
-            {o.swatch && <i style={{ background: o.swatch }} />}
-            {o.label}
+          <button key={o.id ?? 'none'} aria-label={o.label} title={o.label} className={`hf-tile ${o.id === v ? 'on' : ''}`} onClick={() => onChange(ctl.apply(config, o.id))}>
+            {o.id === null ? <NoneIcon /> : o.preview ? <img src={o.preview} alt="" loading="lazy" draggable={false} /> : <span>{o.label}</span>}
           </button>
         ))}
       </div>
@@ -151,6 +164,14 @@ function Control({ ctl, config, onChange }: { ctl: EditorControl; config: HumanC
   );
 }
 
+function NoneIcon() {
+  return (
+    <svg viewBox="0 0 24 24" width="26" height="26" aria-hidden="true" fill="none" stroke="#9aa0a8" strokeWidth="1.8">
+      <circle cx="12" cy="12" r="9" /><path d="M5.6 18.4 18.4 5.6" />
+    </svg>
+  );
+}
+
 const CSS = `
 .hf-root{--hf-accent:#1d1d1f;container-type:inline-size;height:100%;min-height:480px}
 .hf-editor{display:grid;grid-template-columns:minmax(0,1fr) 360px;height:100%;min-height:480px;font:13px/1.4 system-ui,-apple-system,sans-serif;color:#1d1d1f;background:#fff;border-radius:16px;overflow:hidden}
@@ -174,13 +195,13 @@ const CSS = `
 .hf-label{font-size:12px;color:#666}
 .hf-block{margin:12px 0}
 .hf-block>.hf-label{display:block;margin-bottom:8px;font-weight:600;color:#333}
-.hf-choices{display:grid;grid-template-columns:repeat(auto-fill,minmax(96px,1fr));gap:6px}
-.hf-choice{display:flex;align-items:center;gap:6px;justify-content:center;border:1px solid #e1e3e7;background:#fff;border-radius:10px;padding:9px 8px;font:inherit;font-size:12px;cursor:pointer;text-align:center}
-.hf-choice:hover{border-color:#c5c8ce}
-.hf-choice.on{border-color:var(--hf-accent);box-shadow:inset 0 0 0 1px var(--hf-accent);font-weight:600}
-.hf-choice i{width:12px;height:12px;border-radius:50%;flex:none}
-.hf-swatches{display:flex;flex-wrap:wrap;gap:8px}
-.hf-swatch{width:28px;height:28px;border-radius:50%;border:2px solid #fff;box-shadow:0 0 0 1px #d5d8dd;cursor:pointer;padding:0}
+.hf-tiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(72px,1fr));gap:8px}
+.hf-tile{aspect-ratio:1;display:grid;place-items:center;border:1px solid #e1e3e7;background:#f4f5f7;border-radius:12px;padding:4px;cursor:pointer;overflow:hidden;font:inherit;font-size:11px;color:#555}
+.hf-tile:hover{border-color:#c5c8ce}
+.hf-tile.on{border-color:var(--hf-accent);box-shadow:inset 0 0 0 2px var(--hf-accent);background:#fff}
+.hf-tile img{width:100%;height:100%;object-fit:contain;pointer-events:none}
+.hf-swatches{display:flex;flex-wrap:wrap;gap:10px}
+.hf-swatch{width:34px;height:34px;border-radius:50%;border:2px solid #fff;box-shadow:0 0 0 1px #d5d8dd;cursor:pointer;padding:0}
 .hf-swatch.on{box-shadow:0 0 0 2px var(--hf-accent)}
 .hf-save{margin:12px 16px 16px;border:0;border-radius:12px;padding:12px;background:var(--hf-accent);color:#fff;font:inherit;font-weight:600;cursor:pointer}
 @container (max-width:720px){.hf-editor{grid-template-columns:minmax(0,1fr);grid-template-rows:minmax(260px,52%) minmax(0,1fr)}.hf-panel{border-left:0;border-top:1px solid #eceef1}}