humanforge 0.2.1 → 0.4.0

package/LICENSE.ASSETS.md

@@ -0,0 +1,53 @@
+# Asset licenses
+
+All human assets in `assets/human` are CC0 1.0 (public domain dedication). Credit is appreciated but not required.
+
+- Base mesh, targets, rig, weights, expression units: [MPFB2](https://github.com/makehumancommunity/mpfb2) (`src/mpfb/data`), CC0.
+- System skins, eyes, brows, lashes, teeth, 10 hairstyles, 12 outfits, shoes, hats: [MakeHuman system assets](https://files2.makehumancommunity.org/asset_packs/makehuman_system_assets/makehuman_system_assets_cc0.zip), CC0.
+
+## Community assets
+
+Baked by `tools/build-human.ts --extra <pack>`. The list and provenance live in `tools/extra-assets.json`. Each item's license was checked against the pack's `packs/<pack>.json` and its source page (all marked "Creative Commons Zero", checked 2026-10-18). Only the CC0 variants of the MakeHuman community packs are used; the CC-BY packs (`hair02`, `hair03`, `dress02`, ...) are not.
+
+| Pack | Download |
+|---|---|
+| hair01 | https://files2.makehumancommunity.org/asset_packs/hair01/hair01_cc0.zip |
+| dress01 | https://files2.makehumancommunity.org/asset_packs/dress01/dress01_cc0.zip |
+| suits01 | https://files2.makehumancommunity.org/asset_packs/suits01/suits01_cc0.zip |
+
+### Hair
+
+| Id | Label | Author | License | Source |
+|---|---|---|---|---|
+| `toigo_blunt_bob` | Blunt bob | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1669 |
+| `toigo_blunt_bob_with_bangs` | Blunt bob with bangs | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1681 |
+| `toigo_curled_under_bob` | Curled bob | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1677 |
+| `toigo_inverted_bob_with_bangs` | Inverted bob with bangs | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1685 |
+| `cortu_straight_bangs` | Straight with bangs | Cortu | CC0-1.0 | http://www.makehumancommunity.org/node/2810 |
+| `rehmanpolanski_hair_bun_brown` | Bun | RehmanPolanski | CC0-1.0 | http://www.makehumancommunity.org/node/2477 |
+| `culturalibre_hair_01` | Long sleek | culturalibre | CC0-1.0 | http://www.makehumancommunity.org/node/2893 |
+| `sonntag78_junglebook_hair` | Shoulder layers | sonntag78 | CC0-1.0 | http://www.makehumancommunity.org/node/174 |
+| `culturalibre_hair_02` | Short side part | culturalibre | CC0-1.0 | http://www.makehumancommunity.org/node/2892 |
+
+### Clothes
+
+| Id | Label | Author | License | Source |
+|---|---|---|---|---|
+| `toigo_camisole_dress_with_full_skirt` | Camisole dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1730 |
+| `toigo_halter_dress_knee_length` | Halter dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1853 |
+| `toigo_halter_dress_midi` | Halter midi | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1854 |
+| `toigo_halter_dress_with_fluted_skirt` | Halter gown | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1855 |
+| `toigo_shift_dress` | Shift dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1724 |
+| `toigo_keyhole_neck_dress` | Keyhole dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1613 |
+| `toigo_dress_with_tiered_skirt` | Tiered dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1640 |
+| `toigo_bodice_dress_with_lace_ruffle_skirt` | Lace ruffle dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1706 |
+| `toigo_strapless_ruffle_top_dress` | Strapless dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1705 |
+| `toigo_cut_out_dress` | Cut-out dress | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1704 |
+| `toigo_female_suit` | Skirt suit | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1324 |
+| `toigo_female_double-breasted_suit` | Double-breasted suit | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1742 |
+| `toigo_female_suit_2` | Trouser suit | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1739 |
+| `toigo_male_suit_3` | Suit and tie | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1733 |
+| `toigo_male_double-breasted_suit` | Double-breasted suit | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1740 |
+| `toigo_suit_with_dinner_jacket` | Dinner jacket | MargaretToigo | CC0-1.0 | http://www.makehumancommunity.org/node/1746 |
+
+Notes from the asset pages: `culturalibre_hair_01` and `culturalibre_hair_02` are re-uploads of 2015 MakeHuman community hair, and `rehmanpolanski_hair_bun_brown` is adapted from the system `ponytail01`. All of them are published as CC0.

package/README.md

@@ -7,7 +7,7 @@ avatar builders such as MetaPerson Creator. It has two modes:
 | --- | --- | --- |
 | Look | Photoreal skin, eyes, hair cards, clothes | Flat-colored, procedural |
 | Base | MakeHuman / MPFB2 human (CC0), 26.7k-triangle body | three.js primitives, 7–11k triangles |
-| Customization | 11 macro + 57 detail morph sliders, 20 skins, 9 eye colors, 12 brows, 4 lashes, 10 hairstyles, 18 outfits and shoes | 30+ options |
+| Customization | 11 macro + 57 detail morph sliders, 20 skins, 9 eye colors, 12 brows, 4 lashes, 19 hairstyles, 28 outfits, 6 shoes | 30+ options |
 | Rig | 52-bone **Mixamo** skeleton with skin weights (clothes and hair follow) | none |
 | Face animation | 34 FACS blendshapes with **ARKit names** (`jawOpen`, `mouthSmile`, `eyeBlinkLeft`, …) | none |
 | Download | ~1.4 MB one-time core + ~0.3–0.8 MB per look (gzipped, cached on device) | 0 (code only) |
@@ -25,9 +25,32 @@ git clone --depth 1 --filter=blob:none --sparse https://github.com/makehumancomm
 cd mpfb2 && git sparse-checkout set src/mpfb/data && cd ..
 curl -LO https://files2.makehumancommunity.org/asset_packs/makehuman_system_assets/makehuman_system_assets_cc0.zip
 unzip makehuman_system_assets_cc0.zip -d mh_assets
-npm run build:human -- mpfb2/src/mpfb/data mh_assets      # -> assets/human (~14 MB, all options)
+# CC0 community packs: extra hairstyles, dresses and suits (the items listed in tools/extra-assets.json)
+for p in hair01 dress01 suits01; do
+  curl -LO https://files2.makehumancommunity.org/asset_packs/$p/${p}_cc0.zip && unzip -q ${p}_cc0.zip -d mh_$p
+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
+the size is what you host, not what each user downloads. To add other community items, put
+their ids in `tools/extra-assets.json` (with author, license and source) and their labels in
+`src/human/catalog.ts`. `demo/wardrobe.html` renders a contact sheet of hairstyles or outfits
+for comparing them.
+
+
+`build:garments` (`tools/build-garments.mts`) adds garments the MakeHuman packs don't have, generated
+in code from the human package itself (no third-party assets): **hijab**, **al-amira**, **abaya**,
+**jalabiya**, a **day dress**, a **maxi dress** and an **evening gown**. They are regular proxies, so
+they follow every body and face slider; they are tintable (`garmentColors`, palette in
+`GARMENT_COLORS`), and headwear hides the hair while worn. Run it again after `build:human`.
+`demo/garments.html` renders a contact sheet (`?variants=1` adds extreme body shapes).
+
+![Generated garments](demo/garments-preview.png)
+
 Host `assets/human/` on any static host or CDN (S3, Cloudflare R2, GitHub Pages…). No server
 compression is needed: binaries are pre-gzipped and decoded in JS by `fflate`.
 
@@ -79,7 +102,7 @@ const glb = await exportHumanGLB(avatar);   // Mixamo-rigged, ARKit blendshapes
 ### Avatar editor: one config, web and React Native
 
 `<HumanEditor>` is a drop-in customization screen with live 3D preview, section tabs (face,
-skin, eyes, brows, nose, mouth, ears, hair, body, outfit, shoes, hat), randomize and save. The
+skin, eyes, brows, nose, mouth, ears, hair, headwear, body, outfit, shoes, hat), randomize and save. The
 same `options` object decides what your users may change on both platforms:
 
 ```tsx
@@ -88,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
@@ -112,9 +135,11 @@ const { pkg } = useHumanPackage(ASSETS);
 | `gender` | `'female'` or `'male'` locks the gender, hides the gender slider, and filters hair, clothes and skins to ones that suit it. `'any'` shows everything. |
 | `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`, `outfit`, `shoes`, `hat`, `skin`, `eyes`, `eyebrows`, `eyelashes`. |
-| `colors` | Palettes for `hair`, `eyebrows` and `skinTint`. |
-| `optional` | Slots that offer "None" (`hair`, `hat`, `eyebrows`, `shoes`). |
+| `items` | Allowed ids per slot: `hair`, `headwear`, `outfit`, `shoes`, `hat`, `skin`, `eyes`, `eyebrows`, `eyelashes`. |
+| `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. |
 | `labels` | Rename any section, control or item (for translation). |
@@ -123,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
 
@@ -210,7 +270,8 @@ avatar picks up the same bias, such as a wider mouth.
 - **Detail:** `detail: { [id]: -1..1 }`, with the ids listed in `DETAIL_SLIDERS` (head shape, jaw,
   chin, cheeks, eyes, brows, nose ×9, mouth ×8, ears, neck, shoulders, chest, waist, hips…).
 - **Style:** `skin`, `skinTint`, `eyes`, `eyebrows`, `eyebrowColor`, `eyelashes`, `hair`,
-  `hairColor`, and `clothes: string[]`. The available ids are listed in `pkg.manifest`.
+  `hairColor`, `clothes: string[]` and `garmentColors: { outfit?, headwear? }` (fabric colors of
+  tintable garments). The available ids are listed in `pkg.manifest`.
 
 ### How it works
 
@@ -248,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)
@@ -263,11 +325,15 @@ npm run demo      # http://localhost:5173 (stylized) and /human.html (realistic)
   shipping.
 - **Selfie fit:** verified in Chrome with public-domain portraits (web path). The React Native
   landmark path is documented but not implemented. See "Selfie to avatar" for its limits.
-- **Wardrobe:** hairstyles and clothes are limited to the CC0 MakeHuman system packs (10 hairstyles,
-  12 outfits, 6 shoes). They are dated next to commercial avatar SDKs: hair is rendered with soft
-  two-pass cards, but the meshes themselves are 2014-era. More CC0
-  packs, or your own `.mhclo` assets, can be added through `tools/build-human.ts`. There's no hijab
-  or kufi in the realistic set yet.
+- **Wardrobe:** the CC0 MakeHuman system packs (10 hairstyles, 12 outfits, 6 shoes) plus CC0
+  community items: 8 women's hairstyles (bobs, bangs, a bun, long and layered cuts), 1 men's style,
+  10 dresses and 3 women's and 3 men's suits (see `LICENSE.ASSETS.md`,
+  [before/after](demo/hair-compare.jpg)). They are still behind commercial avatar SDKs: hair is
+  rendered with soft two-pass cards on 2014–2021-era community meshes. Separate tops, skirts and
+  trousers aren't offered because the editor has a single outfit slot. More CC0 packs, or your
+  own `.mhclo` assets, can be added through `tools/build-human.ts --extra`. Modest wear and
+  dresses come from `tools/build-garments.mts`: they're smooth, procedurally draped shapes (no
+  simulated folds), shaped for the rest pose; there's no kufi or niqab yet.
 - **Hair quality:** hair uses alpha-tested cards, so the edges are crisper with MSAA (`antialias: true`).
 
 ## Licenses
@@ -275,7 +341,9 @@ npm run demo      # http://localhost:5173 (stylized) and /human.html (realistic)
 - Code: MIT.
 - Human assets (base mesh, targets, skins, hair, clothes, rig, weights, expression units): CC0 1.0,
   from the [MakeHuman](http://www.makehumancommunity.org) project and
-  [MPFB2](https://github.com/makehumancommunity/mpfb2). Credit is appreciated but not required.
+  [MPFB2](https://github.com/makehumancommunity/mpfb2), plus CC0 community hair and clothes listed
+  per item (author, source) in [LICENSE.ASSETS.md](LICENSE.ASSETS.md). Credit is appreciated but not required.
+- Generated garments and fabric textures (`tools/build-garments.mts` output): original, CC0 1.0.
 - Selfie fitting: MediaPipe Face Landmarker and its canonical face mesh are Apache-2.0 (Google).
   `src/human/faceMap.ts` contains vertex indices and averaged landmark positions derived from them.
   The model and WASM are downloaded at runtime and aren't bundled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanforge",
-  "version": "0.2.1",
+  "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",
@@ -48,9 +48,11 @@
   "scripts": {
     "demo": "vite",
     "build:human": "tsx tools/build-human.ts",
+    "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",
@@ -102,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

@@ -3,7 +3,7 @@
 // they get a generated label and are treated as unisex.
 
 export type Fit = 'female' | 'male' | 'unisex';
-export type ClothingSlot = 'outfit' | 'shoes' | 'hat';
+export type ClothingSlot = 'outfit' | 'shoes' | 'hat' | 'headwear';
 
 export interface ItemInfo { label: string; fit: Fit }
 
@@ -18,6 +18,16 @@ export const HAIR: Record<string, ItemInfo> = {
   short02: { label: 'Short tousled', fit: 'male' },
   short03: { label: 'Side fringe', fit: 'unisex' },
   short04: { label: 'Slicked back', fit: 'male' },
+  // MakeHuman community hair (CC0, see LICENSE.ASSETS.md)
+  toigo_blunt_bob: { label: 'Blunt bob', fit: 'female' },
+  toigo_blunt_bob_with_bangs: { label: 'Blunt bob with bangs', fit: 'female' },
+  toigo_curled_under_bob: { label: 'Curled bob', fit: 'female' },
+  toigo_inverted_bob_with_bangs: { label: 'Inverted bob with bangs', fit: 'female' },
+  cortu_straight_bangs: { label: 'Straight with bangs', fit: 'female' },
+  culturalibre_hair_01: { label: 'Long sleek', fit: 'female' },
+  sonntag78_junglebook_hair: { label: 'Shoulder layers', fit: 'female' },
+  rehmanpolanski_hair_bun_brown: { label: 'Bun', fit: 'female' },
+  culturalibre_hair_02: { label: 'Short side part', fit: 'male' },
 };
 
 export const CLOTHES: Record<string, ItemInfo & { slot: ClothingSlot }> = {
@@ -33,6 +43,23 @@ export const CLOTHES: Record<string, ItemInfo & { slot: ClothingSlot }> = {
   male_casualsuit06: { label: 'Casual 6', fit: 'male', slot: 'outfit' },
   male_elegantsuit01: { label: 'Suit', fit: 'male', slot: 'outfit' },
   male_worksuit01: { label: 'Workwear', fit: 'male', slot: 'outfit' },
+  // MakeHuman community clothes (CC0, see LICENSE.ASSETS.md)
+  toigo_camisole_dress_with_full_skirt: { label: 'Camisole dress', fit: 'female', slot: 'outfit' },
+  toigo_halter_dress_knee_length: { label: 'Halter dress', fit: 'female', slot: 'outfit' },
+  toigo_halter_dress_midi: { label: 'Halter midi', fit: 'female', slot: 'outfit' },
+  toigo_halter_dress_with_fluted_skirt: { label: 'Halter gown', fit: 'female', slot: 'outfit' },
+  toigo_shift_dress: { label: 'Shift dress', fit: 'female', slot: 'outfit' },
+  toigo_keyhole_neck_dress: { label: 'Keyhole dress', fit: 'female', slot: 'outfit' },
+  toigo_dress_with_tiered_skirt: { label: 'Tiered dress', fit: 'female', slot: 'outfit' },
+  toigo_bodice_dress_with_lace_ruffle_skirt: { label: 'Lace ruffle dress', fit: 'female', slot: 'outfit' },
+  toigo_strapless_ruffle_top_dress: { label: 'Strapless dress', fit: 'female', slot: 'outfit' },
+  toigo_cut_out_dress: { label: 'Cut-out dress', fit: 'female', slot: 'outfit' },
+  toigo_female_suit: { label: 'Skirt suit', fit: 'female', slot: 'outfit' },
+  toigo_female_suit_2: { label: 'Trouser suit', fit: 'female', slot: 'outfit' },
+  'toigo_female_double-breasted_suit': { label: 'Double-breasted suit', fit: 'female', slot: 'outfit' },
+  toigo_male_suit_3: { label: 'Suit and tie', fit: 'male', slot: 'outfit' },
+  'toigo_male_double-breasted_suit': { label: 'Double-breasted suit', fit: 'male', slot: 'outfit' },
+  toigo_suit_with_dinner_jacket: { label: 'Dinner jacket', fit: 'male', slot: 'outfit' },
   shoes01: { label: 'Shoes 1', fit: 'unisex', slot: 'shoes' },
   shoes02: { label: 'Shoes 2', fit: 'unisex', slot: 'shoes' },
   shoes03: { label: 'Shoes 3', fit: 'unisex', slot: 'shoes' },
@@ -41,8 +68,38 @@ export const CLOTHES: Record<string, ItemInfo & { slot: ClothingSlot }> = {
   shoes06: { label: 'Shoes 6', fit: 'unisex', slot: 'shoes' },
   fedora01: { label: 'Fedora', fit: 'unisex', slot: 'hat' },
   fedora_cocked: { label: 'Fedora (tilted)', fit: 'unisex', slot: 'hat' },
+  // Generated by tools/build-garments.ts (original, CC0): tintable, see GARMENT_COLORS.
+  abaya01: { label: 'Abaya', fit: 'female', slot: 'outfit' },
+  jalabiya01: { label: 'Jalabiya', fit: 'female', slot: 'outfit' },
+  dress_knee01: { label: 'Day dress', fit: 'female', slot: 'outfit' },
+  dress_maxi01: { label: 'Maxi dress', fit: 'female', slot: 'outfit' },
+  gown01: { label: 'Evening gown', fit: 'female', slot: 'outfit' },
+  hijab01: { label: 'Hijab', fit: 'female', slot: 'headwear' },
+  amira01: { label: 'Al-amira', fit: 'female', slot: 'headwear' },
 };
 
+/** Fabric colors for tintable garments (multiplied over a light fabric texture). */
+export const GARMENT_COLORS: { id: string; label: string; color: string }[] = [
+  { id: 'black', label: 'Black', color: '#1b1b1f' },
+  { id: 'charcoal', label: 'Charcoal', color: '#3a3c42' },
+  { id: 'navy', label: 'Navy', color: '#1f3a5f' },
+  { id: 'slate', label: 'Slate blue', color: '#3f5e8c' },
+  { id: 'teal', label: 'Teal', color: '#1f6f6b' },
+  { id: 'emerald', label: 'Emerald', color: '#1e6b45' },
+  { id: 'olive', label: 'Olive', color: '#6b6a3a' },
+  { id: 'mocha', label: 'Mocha', color: '#6b4f3f' },
+  { id: 'sand', label: 'Sand', color: '#cbb89a' },
+  { id: 'ivory', label: 'Ivory', color: '#e9e2d6' },
+  { id: 'white', label: 'White', color: '#f4f3ef' },
+  { id: 'blush', label: 'Blush', color: '#d9a7a0' },
+  { id: 'rose', label: 'Dusty rose', color: '#b56f7b' },
+  { id: 'terracotta', label: 'Terracotta', color: '#b85c4a' },
+  { id: 'burgundy', label: 'Burgundy', color: '#7c2945' },
+  { id: 'plum', label: 'Plum', color: '#5b3a5e' },
+  { id: 'lavender', label: 'Lavender', color: '#a79bc4' },
+  { id: 'sky', label: 'Sky', color: '#8fb3d1' },
+];
+
 export const EYE_LABELS: Record<string, string> = {
   brown: 'Dark brown', brownlight: 'Brown', green: 'Green', blue: 'Blue', deepblue: 'Deep blue',
   lightblue: 'Light blue', bluegreen: 'Blue-green', grey: 'Grey', ice: 'Ice',
@@ -75,13 +132,60 @@ 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);
 
 export function hairInfo(id: string): ItemInfo { return HAIR[id] ?? { label: cap(words(id)), fit: 'unisex' }; }
 export function clothingInfo(id: string): ItemInfo & { slot: ClothingSlot } {
   if (CLOTHES[id]) return CLOTHES[id];
-  const slot: ClothingSlot = id.startsWith('shoes') ? 'shoes' : /hat|fedora|cap|helmet/.test(id) ? 'hat' : 'outfit';
+  const slot: ClothingSlot = id.startsWith('shoes') ? 'shoes' : /hijab|amira|shayla|scarf|turban/.test(id) ? 'headwear' : /hat|fedora|cap|helmet/.test(id) ? 'hat' : 'outfit';
   const fit: Fit = id.startsWith('female') ? 'female' : id.startsWith('male') ? 'male' : 'unisex';
   return { label: cap(words(id.replace(/^(fe)?male_/, ''))), fit, slot };
 }

package/src/human/editor.ts

@@ -6,15 +6,17 @@
 //   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, 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' | 'outfit' | 'shoes' | 'hat';
-export type ItemSlot = 'hair' | 'outfit' | 'shoes' | 'hat' | 'skin' | 'eyes' | 'eyebrows' | 'eyelashes';
+export type SectionId = 'body' | 'face' | 'skin' | 'eyes' | 'brows' | 'nose' | 'mouth' | 'ears' | 'hair' | 'headwear' | 'outfit' | 'shoes' | 'hat';
+export type ItemSlot = 'hair' | 'headwear' | 'outfit' | 'shoes' | 'hat' | 'skin' | 'eyes' | 'eyebrows' | 'eyelashes';
 
-export const ALL_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', 'body', 'outfit', 'shoes', 'hat'];
+export const ALL_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', 'headwear', 'body', 'outfit', 'shoes', 'hat'];
 
 export interface HumanEditorOptions {
   /** Lock the avatar to one gender: hides the gender slider and filters hair, clothes and skins. Default 'any'. */
@@ -28,9 +30,13 @@ 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[] };
-  /** Slots that may be empty ("None" option). Default: hat and eyebrows. */
-  optional?: Partial<Record<'hair' | 'hat' | 'eyebrows' | 'shoes', boolean>>;
+  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. */
   detailRange?: number;
   /** Starting values (merged over the gender's default look). */
@@ -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[] }
@@ -64,9 +85,12 @@ export interface HumanEditorModel {
 
 const SECTION_LABELS: Record<SectionId, string> = {
   body: 'Body', face: 'Face', skin: 'Skin', eyes: 'Eyes', brows: 'Brows', nose: 'Nose', mouth: 'Mouth', ears: 'Ears',
-  hair: 'Hair', outfit: 'Outfit', shoes: 'Shoes', hat: 'Hat',
+  hair: 'Hair', headwear: 'Headwear', outfit: 'Outfit', shoes: 'Shoes', hat: 'Hat',
 };
-const FACE_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', 'hat'];
+const FACE_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', 'headwear', 'hat'];
+type WearSlot = 'outfit' | 'shoes' | 'hat' | 'headwear';
+/** Slots that can't be worn together: choosing one takes off the other. */
+const CONFLICTS: Partial<Record<WearSlot, WearSlot>> = { hat: 'headwear', headwear: 'hat' };
 const BROW_SLIDERS = ['browHeight', 'browAngle', 'browDepth'];
 
 const GENDER_DEFAULTS: Record<'female' | 'male', Partial<HumanConfig>> = {
@@ -82,13 +106,21 @@ 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;
   const range = Math.min(1, Math.max(0, options.detailRange ?? 1));
   const label = (id: string, fallback: string) => options.labels?.[id] ?? fallback;
-  const optional = { hat: true, eyebrows: true, hair: false, shoes: false, ...options.optional };
+  const optional = { hat: true, headwear: true, eyebrows: true, hair: false, shoes: false, ...options.optional };
 
   // ---- allowed items
   const restrict = (slot: ItemSlot, ids: string[]) => {
@@ -96,9 +128,10 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
     return only ? ids.filter((id) => only.includes(id)) : ids;
   };
   const clothes = manifest.proxies.filter((p) => p.kind === 'clothes').map((p) => p.id);
-  const bySlot = (slot: 'outfit' | 'shoes' | 'hat') => clothes.filter((id) => clothingInfo(id).slot === slot && fits(clothingInfo(id).fit, gender));
+  const bySlot = (slot: WearSlot) => clothes.filter((id) => clothingInfo(id).slot === slot && fits(clothingInfo(id).fit, gender));
   const allowed: Record<ItemSlot, string[]> = {
     hair: restrict('hair', manifest.proxies.filter((p) => p.kind === 'hair').map((p) => p.id).filter((id) => fits(hairInfo(id).fit, gender))),
+    headwear: restrict('headwear', bySlot('headwear')),
     outfit: restrict('outfit', bySlot('outfit')),
     shoes: restrict('shoes', bySlot('shoes')),
     hat: restrict('hat', bySlot('hat')),
@@ -112,7 +145,28 @@ 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;
 
   // ---- controls
   const shown = (section: SectionId, id: string) => !exclude.has(section) && !exclude.has(`${section}.${id}`) && !exclude.has(id) && (!include || include.has(`${section}.${id}`) || include.has(id));
@@ -127,35 +181,46 @@ 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 clothingChoice = (slot: 'outfit' | 'shoes' | 'hat', lbl: string, canBeEmpty: boolean) => choice('style', lbl,
-    [...none(canBeEmpty), ...allowed[slot].map((id) => ({ id, label: label(id, clothingInfo(id).label) }))],
-    (c) => c.clothes.find((id) => clothingInfo(id).slot === slot) ?? null,
-    (c, v) => ({ ...c, clothes: [...c.clothes.filter((id) => clothingInfo(id).slot !== slot), ...(v ? [v] : [])] }));
+  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), 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). */
+  const garmentColor = (slot: WearSlot): EditorControl[] => (allowed[slot].some(tintable)
+    ? [color('color', 'Color', garmentColors, (c) => c.garmentColors?.[slot] ?? defaultColor(worn(c, slot)) ?? garmentColors[0],
+      (c, v) => ({ ...c, garmentColors: { ...c.garmentColors, [slot]: v } }))]
+    : []);
 
   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),
@@ -164,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 })),
     ],
@@ -174,7 +239,8 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
       ...(gender !== 'male' ? [macro('cupSize', 'Bust'), macro('firmness', 'Firmness')] : []),
       ...DETAIL_SLIDERS.filter((d) => d.group === 'body').map((d) => detail(d.id)),
     ],
-    outfit: () => [clothingChoice('outfit', 'Outfit', false)],
+    headwear: () => [clothingChoice('headwear', 'Headwear', optional.headwear), ...garmentColor('headwear')],
+    outfit: () => [clothingChoice('outfit', 'Outfit', false), ...garmentColor('outfit')],
     shoes: () => [clothingChoice('shoes', 'Shoes', optional.shoes)],
     hat: () => [clothingChoice('hat', 'Hat', optional.hat)],
   };
@@ -183,7 +249,7 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
   for (const id of options.sections ?? ALL_SECTIONS) {
     if (exclude.has(id)) continue;
     const controls = build[id]().filter((ctl) => shown(id, ctl.id)).filter((ctl) => ctl.kind !== 'choice' || ctl.options.length > 1 || ctl.options[0]?.id !== null);
-    if ((id === 'outfit' || id === 'shoes' || id === 'hat') && !allowed[id].length) continue;
+    if ((id === 'outfit' || id === 'shoes' || id === 'hat' || id === 'headwear') && !allowed[id].length) continue;
     if (controls.length) sections.push({ id, label: label(id, SECTION_LABELS[id]), framing: FACE_SECTIONS.includes(id) ? 'face' : 'body', controls });
   }
 
@@ -197,19 +263,22 @@ 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);
     c.eyelashes = c.eyelashes === null ? null : pick(c.eyelashes, allowed.eyelashes, base.eyelashes);
-    const wear = (slot: 'outfit' | 'shoes' | 'hat', canBeEmpty: boolean) => {
+    const wear = (slot: WearSlot, canBeEmpty: boolean) => {
       const cur = c.clothes.find((id) => clothingInfo(id).slot === slot);
       const fallback = base.clothes.find((id) => clothingInfo(id).slot === slot);
       if (!cur && canBeEmpty) return [];
       const v = pick(cur, allowed[slot], fallback);
       return v ? [v] : [];
     };
-    c.clothes = [...wear('outfit', false), ...wear('shoes', optional.shoes), ...wear('hat', true)];
+    const headwear = wear('headwear', true);
+    c.clothes = [...wear('outfit', false), ...wear('shoes', optional.shoes), ...headwear, ...(headwear.length ? [] : wear('hat', true))];
+    if (c.garmentColors) c.garmentColors = Object.fromEntries(Object.entries(c.garmentColors).filter(([, v]) => typeof v === 'string'));
     return c;
   }
 
@@ -233,7 +302,9 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
   return { options, sections, initial: normalize(), normalize, randomize, allowed };
 }
 
-const HAIR_ORDER = ['long01', 'ponytail01', 'bob02', 'afro01', 'short02', 'short01', 'short04', 'bob01', 'braid01', 'short03'];
+const HAIR_ORDER = ['long01', 'culturalibre_hair_01', 'cortu_straight_bangs', 'sonntag78_junglebook_hair', 'ponytail01', 'rehmanpolanski_hair_bun_brown',
+  'toigo_blunt_bob', 'toigo_blunt_bob_with_bangs', 'toigo_curled_under_bob', 'toigo_inverted_bob_with_bangs', 'bob02', 'afro01',
+  'short02', 'culturalibre_hair_02', 'short01', 'short04', 'bob01', 'braid01', 'short03'];
 const order = (id: string) => { const i = HAIR_ORDER.indexOf(id); return i < 0 ? 100 : i; };
 
 /** Same age/ethnicity skin among the allowed ones (used when gender filtering removes the current skin). */
@@ -247,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

@@ -6,11 +6,12 @@
 // (TextureLoader on the web by default; see src/native/humanTextures.ts for React Native).
 import {
   Bone, BufferAttribute, BufferGeometry, DoubleSide, FrontSide, Group, Material, Matrix4, MeshStandardMaterial,
-  Quaternion, SRGBColorSpace, Skeleton, SkinnedMesh, Texture, TextureLoader, Vector3,
+  Quaternion, RepeatWrapping, SRGBColorSpace, Skeleton, SkinnedMesh, Texture, TextureLoader, Vector3,
 } from 'three';
 import { gunzipSync } from 'fflate';
 import { DETAIL_SLIDERS } from './sliders';
 import { GlbPrimitive, readGlb, toFloat } from './glb';
+import { clothingInfo } from './catalog';
 
 // ---------------------------------------------------------------- config
 export interface HumanConfig {
@@ -39,6 +40,8 @@ export interface HumanConfig {
   hair: string | null;
   hairColor: string;
   clothes: string[];
+  /** Colors of tintable garments by clothing slot ('outfit', 'headwear'...); unset = the garment's default. */
+  garmentColors?: Record<string, string>;
 }
 
 export const DEFAULT_HUMAN: HumanConfig = {
@@ -53,6 +56,15 @@ export interface ProxyMeta {
   id: string; kind: string; file: string; triangles: number; transparent: boolean; tintable: boolean; zDepth: number;
   deleteVerts?: [number, number][]; scale: [number, number, number][];
   texture?: string; normalTexture?: string; textureSize: number; doubleSided: boolean;
+  /** Default tint for tintable garments. */
+  color?: string;
+  /** Headwear that covers the hair: the hair proxy is not shown while it is worn. */
+  hidesHair?: boolean;
+  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;
@@ -64,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>;
 }
@@ -233,9 +248,25 @@ function geometryFrom(prim: GlbPrimitive, joints: string, weights: string) {
   g.setAttribute('skinIndex', new BufferAttribute(asU16(prim.attributes[joints]), 4));
   g.setAttribute('skinWeight', new BufferAttribute(toFloat(prim.attributes[weights]), 4));
   g.setIndex(new BufferAttribute(prim.index, 1));
+  if (prim.attributes.COLOR_0) g.setAttribute('color', new BufferAttribute(toFloat(prim.attributes.COLOR_0), prim.attributes.COLOR_0.itemSize));
   return g;
 }
 
+/**
+ * Vertices split only for texture seams share refs/weights/offsets. Pairs (dup, first) so
+ * normals can be averaged across the seam after computeVertexNormals.
+ */
+function seamPairs(refs: Uint16Array, refw: Float32Array, offs: Float32Array) {
+  const first = new Map<string, number>(), pairs: number[] = [];
+  for (let i = 0; i < refs.length / 3; i++) {
+    let k = '';
+    for (let c = 0; c < 3; c++) k += `${refs[i * 3 + c]},${Math.round(refw[i * 3 + c] * 1e4)},${Math.round(offs[i * 3 + c] * 1e5)},`;
+    const f = first.get(k);
+    if (f === undefined) first.set(k, i); else pairs.push(i, f);
+  }
+  return Uint32Array.from(pairs);
+}
+
 /**
  * Hair cards: the texture's transparent texels are near-white, which shows as a light halo
  * around strands once alpha is blended. Darken texels by their coverage so tips fade naturally.
@@ -248,7 +279,7 @@ function hairShading(m: MeshStandardMaterial) {
   m.customProgramCacheKey = () => 'humanforge-hair';
 }
 
-interface ProxyInstance { meta: ProxyMeta; mesh: SkinnedMesh; soft?: SkinnedMesh; refs: Uint16Array; refw: Float32Array; offs: Float32Array }
+interface ProxyInstance { meta: ProxyMeta; mesh: SkinnedMesh; soft?: SkinnedMesh; refs: Uint16Array; refw: Float32Array; offs: Float32Array; seams?: Uint32Array }
 
 export class HumanAvatar {
   readonly group = new Group();
@@ -318,7 +349,8 @@ export class HumanAvatar {
     if (c.eyelashes) wanted.set('eyelashes', `eyelashes-${c.eyelashes}`);
     wanted.set('teeth', 'teeth-teeth_base');
     wanted.set('tongue', 'tongue-tongue01');
-    if (c.hair) wanted.set('hair', `hair-${c.hair}`);
+    const meta = (id: string) => this.pkg.manifest.proxies.find((p) => p.kind === 'clothes' && p.id === id);
+    if (c.hair && !c.clothes.some((id) => meta(id)?.hidesHair)) wanted.set('hair', `hair-${c.hair}`);
     c.clothes.forEach((id) => wanted.set(`clothes:${id}`, `clothes-${id}`));
     const loads = [...wanted.entries()].map(async ([slot, id]) => {
       const cur = this.proxies.get(slot);
@@ -347,6 +379,7 @@ export class HumanAvatar {
       if (slot === 'hair') { m.color.set(c.hairColor); (p.soft?.material as MeshStandardMaterial | undefined)?.color.set(c.hairColor); }
       if (slot === 'eyebrows') m.color.set(c.eyebrowColor);
       if (slot === 'eyes' && m.map !== eyeTex) { m.map = eyeTex; m.needsUpdate = true; }
+      if (p.meta.kind === 'clothes' && p.meta.tintable) m.color.set(c.garmentColors?.[clothingInfo(p.meta.id).slot] ?? p.meta.color ?? '#ffffff');
     }
     this.reshape();
   }
@@ -396,9 +429,11 @@ export class HumanAvatar {
     const refs = asU16(prim.attributes._REFS), refw = toFloat(prim.attributes._REFW), offs = toFloat(prim.attributes._OFFS);
     const mat = new MeshStandardMaterial({
       map, normalMap, metalness: 0,
-      roughness: meta.kind === 'eyes' ? 0.15 : meta.kind === 'hair' ? 0.55 : 0.8,
+      roughness: meta.roughness ?? (meta.kind === 'eyes' ? 0.15 : meta.kind === 'hair' ? 0.55 : 0.8),
       side: meta.doubleSided ? DoubleSide : FrontSide,
+      vertexColors: !!geo.getAttribute('color'),
     });
+    if (meta.tileable) for (const t of [map, normalMap]) if (t && t.wrapS !== RepeatWrapping) { t.wrapS = t.wrapT = RepeatWrapping; t.needsUpdate = true; }
     let soft: SkinnedMesh | undefined;
     if (meta.kind === 'hair') {
       // Two passes: a solid core (alpha-tested, writes depth, so strands sort correctly) and a
@@ -432,7 +467,8 @@ export class HumanAvatar {
       mesh.morphTargetDictionary = this.body.morphTargetDictionary;
       mesh.morphTargetInfluences = [...(this.body.morphTargetInfluences ?? [])];
     }
-    return { meta, mesh, soft, refs, refw, offs };
+    const seams = meta.kind === 'clothes' ? seamPairs(refs, refw, offs) : undefined;
+    return { meta, mesh, soft, refs, refw, offs, seams: seams?.length ? seams : undefined };
   }
 
   private removeProxy(slot: string) {
@@ -497,6 +533,11 @@ export class HumanAvatar {
       }
       pp.needsUpdate = true;
       g.computeVertexNormals();
+      if (p.seams) {
+        const nn = g.getAttribute('normal') as BufferAttribute, q = p.seams;
+        for (let i = 0; i < q.length; i += 2) { tmpA.fromBufferAttribute(nn, q[i]); tmpB.fromBufferAttribute(nn, q[i + 1]).add(tmpA); nn.setXYZ(q[i + 1], tmpB.x, tmpB.y, tmpB.z); }
+        for (let i = q.length - 2; i >= 0; i -= 2) { tmpA.fromBufferAttribute(nn, q[i + 1]).normalize(); nn.setXYZ(q[i + 1], tmpA.x, tmpA.y, tmpA.z); nn.setXYZ(q[i], tmpA.x, tmpA.y, tmpA.z); }
+      }
       g.computeBoundingSphere();
     }
 

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}}