humanforge 0.2.1 → 0.3.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,31 @@ 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)
 ```
 
+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 +101,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
@@ -112,9 +134,9 @@ 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`, `skinTint` and `garments` (outfit/headwear fabric). |
+| `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). |
@@ -210,7 +232,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
 
@@ -263,11 +286,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 +302,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.3.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,6 +48,7 @@
   "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"

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',
@@ -81,7 +138,7 @@ 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

@@ -8,13 +8,13 @@
 //   editor.normalize(savedConfig) -> clamps/repairs any config to the options (use on load)
 import { DEFAULT_HUMAN, HumanConfig, HumanManifest } 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, SKIN_TINTS, clothingInfo, fits, hairInfo, 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 +28,9 @@ 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[]; skinTint?: string[]; garments?: string[] };
+  /** 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). */
@@ -64,9 +64,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>> = {
@@ -88,7 +91,7 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
   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 +99,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')),
@@ -113,6 +117,9 @@ 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;
+  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));
@@ -132,10 +139,16 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
   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,
+  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) }))],
-    (c) => c.clothes.find((id) => clothingInfo(id).slot === slot) ?? null,
-    (c, v) => ({ ...c, clothes: [...c.clothes.filter((id) => clothingInfo(id).slot !== slot), ...(v ? [v] : [])] }));
+    (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: () => [
@@ -174,7 +187,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 +197,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 });
   }
 
@@ -202,14 +216,16 @@ export function createHumanEditor(manifest: HumanManifest, options: HumanEditorO
     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 +249,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). */

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,13 @@ 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;
 }
 export interface HumanManifest {
   vertexCount: number;
@@ -233,9 +243,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 +274,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 +344,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 +374,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 +424,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 +462,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 +528,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();
     }