humanforge 0.3.0 → 0.5.0

package/README.md

@@ -32,6 +32,8 @@ 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)
+npm run build:mobile -- --skin-2k                          # JPEG/PNG texture pack for Expo (no WebP in expo-gl)
 ```
 
 Leave out the `--extra` packs for the system set only (~14 MB). Every item loads on demand, so
@@ -62,24 +64,83 @@ npx expo install expo-gl expo-file-system three fflate
 ```tsx
 import { HumanView, useHumanPackage } from 'humanforge';
 
-const { pkg } = useHumanPackage('https://cdn.example.com/human');
-if (!pkg) return <Loading />;
+const ASSETS = 'https://cdn.jsdelivr.net/gh/abdulrehman043/humanforge@v0.5.0/assets/human';
+
+function Avatar({ config }) {
+  // ready = the first textured frame can be painted (manifest, body, and this look's
+  // hair/clothes/skin/eyes are on disk), not just "manifest loaded"
+  const { pkg, ready, progress } = useHumanPackage(ASSETS, { config, textureSize: '1k' });
+  if (!pkg || !ready) return <Loading progress={progress} />;
+  return (
+    <HumanView
+      pkg={pkg}
+      config={config}
+      framing="face"                 // or "body"
+      textureSize="1k"               // see the table below
+      expressions={{ mouthSmile: 0.6 }}
+      onReady={() => SplashScreen.hideAsync()}   // fires once, after the first textured frame
+      style={{ width: 240, height: 240, borderRadius: 120 }}
+    />
+  );
+}
+```
 
-<HumanView
-  pkg={pkg}
-  framing="face"                     // or "body"
-  textureSize="1k"                   // "2k" for the editor screen
-  config={{ gender: 0.1, age: 0.2, african: 1, asian: 0, caucasian: 0,
-            skin: 'young_african_female', hair: 'afro01', hairColor: '#1a120c',
-            detail: { noseWidth: 0.3, eyeSize: 0.2 },
-            clothes: ['female_casualsuit01', 'shoes01'] }}
-  expressions={{ mouthSmile: 0.6 }}
-  style={{ width: 240, height: 240, borderRadius: 120 }}
-/>
+A ref gives you `avatar` (bones, `setExpression`), `render()` and `snapshot()` (PNG file URI).
+
+#### Textures on Expo: the mobile pack
+
+expo-gl uploads images through stb_image, which **can't decode WebP**: a WebP texture leaves the
+mesh black with only the lights showing. The asset package therefore ships a **mobile texture
+pack** with the same textures as baseline JPEG (opaque) and paletted PNG (hair, lashes, lace),
+in three tiers. `useHumanPackage`, `preloadHumanPackage` and `expoLoadOptions` select it
+automatically (`textureFormat: 'mobile'`); the web keeps using WebP. Nothing is converted on the
+device, and nothing large goes into your app or the npm package: files download from the CDN
+on demand and stay in the app's cache directory (offline on later launches).
+
+| `textureSize` | Max edge | Use for | First-look download* |
+| --- | --- | --- | --- |
+| `'512'` | 512 px | lists, chat bubbles, avatars under ~120 pt | ~0.8 MB |
+| `'1k'` (default) | 1024 px | profile, bust/face framing; at phone sizes this matches web 2k | ~1.2 MB |
+| `'2k'` | 2048 px (skins) | full-screen face close-ups, tablets | ~1.3 MB |
+
+\* meshes + textures of a default look (hair, outfit, shoes, skin, eyes, brows, lashes); the
+shared body and shape data add ~1.45 MB once. Brows, lashes and eye textures are small at every
+tier; textures are never upscaled.
+
+On the jsDelivr setup the pack lives on its own git tag (`mobile-v0.5.0`), because jsDelivr serves
+GitHub versions only up to 50 MB; `manifest.mobileTextures.baseUrl` points there, so you only pass
+the main URL. Self-hosting: run `npm run build:mobile` and upload `assets/human/mobile/` next to
+`manifest.json` (or pass `mobileBaseUrl`).
+
+#### Preload during the splash screen
+
+```tsx
+import { preloadHumanPackage } from 'humanforge';
+
+// resolves when the files are on disk, so the first <HumanView> paints textured at once
+await preloadHumanPackage(ASSETS, { config: savedAvatar, textureSize: '1k', onProgress: (done, total) => {} });
 ```
 
-Files are cached in the app's cache directory, so later launches work offline. A ref gives you
-`avatar` (bones, `setExpression`), `render()` and `snapshot()` (PNG file URI).
+It shares its cache with `useHumanPackage` (same URL = same package, no second download).
+
+#### Performance knobs
+
+| `HumanView` prop | Default | Notes |
+| --- | --- | --- |
+| `textureSize` | `'1k'` | tiers above |
+| `pixelRatio` | device (max 3) | `2` on 3x phones renders ~55% fewer pixels and still looks sharp |
+| `antialias` | `true` | MSAA (expo-gl `msaaSamples` on iOS) |
+| `maxTextureAnisotropy` | `2` | `1` turns it off |
+| `normalMaps` | `true` | `false` skips clothing normal maps (lighter, slightly flatter fabric) |
+
+Slider, color and expression changes reuse the textures already on the GPU: only a new item
+(hair, outfit, skin tone) or a new tier loads files. `onReady` fires once per avatar, after the
+first frame with all textures; it does not fire again on later edits.
+
+Recommended: editor screen `textureSize="1k"` (or `'2k'` on tablets), lists and thumbnails
+`'512'` with `pixelRatio={2}`. For option pickers, use the static preview images and swatches
+(`getHumanCatalog`, below) rather than live 3D views: they are small WebP files shown with
+`<Image>`, which uses the platform decoder (WebP is fine there).
 
 ### 3. React / web
 
@@ -110,7 +171,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.5.0/assets/human';
 const { pkg } = useHumanPackage(ASSETS);
 
 <HumanEditor
@@ -135,7 +196,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 +208,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 +369,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.5.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,9 @@
     "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",
+    "build:mobile": "tsx tools/build-mobile-textures.mts"
   },
   "peerDependencies": {
     "@gltf-transform/core": ">=4",
@@ -103,6 +105,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;
+}