humanforge 0.1.0 → 0.2.0

package/README.md

@@ -76,6 +76,55 @@ const glb = await exportHumanGLB(avatar);   // Mixamo-rigged, ARKit blendshapes
 
 `demo/human.html` is a complete web editor (`npm run demo`, then open `/human.html`).
 
+### 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
+same `options` object decides what your users may change on both platforms:
+
+```tsx
+// React web
+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 { pkg } = useHumanPackage(ASSETS);
+
+<HumanEditor
+  pkg={pkg}
+  defaultValue={savedAvatar}                 // the JSON you stored last time (optional)
+  options={{
+    gender: 'female',                        // 'female' | 'male' | 'any'
+    sections: ['face', 'eyes', 'nose', 'mouth', 'hair', 'outfit'],
+    exclude: ['ears', 'nose.noseHump', 'body.cupSize'],
+    items: { hair: ['long01', 'ponytail01', 'bob02'] },
+    colors: { hair: ['#1a1412', '#3d2618', '#6b4428', '#e6c88a'] },
+    detailRange: 0.7,                        // keep faces natural
+    locked: { eyes: 'brownlight' },          // never editable
+  }}
+  onSave={(config, snapshot) => api.saveAvatar(config)}
+/>
+```
+
+| Option | What it does |
+| --- | --- |
+| `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`). |
+| `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). |
+
+The config is plain JSON; store it as-is. On load, `editor.normalize(saved)` (done for you by
+`<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.
+
 ### 4. Selfie to avatar
 
 `fitSelfie` turns a front-facing photo into a `HumanConfig` patch. It sets the ethnicity mix, about
@@ -208,13 +257,15 @@ npm run demo      # http://localhost:5173 (stylized) and /human.html (realistic)
 
 - **Verified:** the asset build, the decoder and smoke tests, and the web runtime (shape sliders,
   skins, hair, clothes, rig posing, expressions, GLB export), visually in Chrome.
-- **Not yet run on a device:** the React Native components (`HumanView`, `AvatarView`,
+- **Not yet run on a device:** the React Native components (`HumanView`, `HumanEditor`, `AvatarView`,
   `AvatarCreator`). They typecheck against RN 0.81, expo-gl 16 and expo-file-system 19, and use
   the standard expo-gl texture path (`{ localUri }`). Test on one iOS and one Android device before
   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. More CC0
+- **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.
 - **Hair quality:** hair uses alpha-tested cards, so the edges are crisper with MSAA (`antialias: true`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanforge",
-  "version": "0.1.0",
+  "version": "0.2.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",
@@ -35,7 +35,9 @@
     "./core": "./src/core/index.ts",
     "./human": "./src/human/index.ts",
     "./human/export": "./src/human/export.ts",
-    "./human/selfie": "./src/human/selfie.ts"
+    "./human/selfie": "./src/human/selfie.ts",
+    "./web": "./src/web/index.ts",
+    "./native": "./src/native/index.ts"
   },
   "files": [
     "src",
@@ -47,19 +49,19 @@
     "demo": "vite",
     "build:human": "tsx tools/build-human.ts",
     "typecheck": "tsc --noEmit",
-    "test": "tsx scripts/smoke.ts && tsx scripts/human-smoke.mts && tsx scripts/fit-test.mts",
+    "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"
   },
   "peerDependencies": {
     "@gltf-transform/core": ">=4",
     "@gltf-transform/extensions": ">=4",
     "@gltf-transform/functions": ">=4",
+    "@mediapipe/tasks-vision": ">=0.10",
     "expo-file-system": ">=18",
     "expo-gl": ">=13",
     "react": ">=18",
     "react-native": ">=0.72",
-    "three": ">=0.160",
-    "@mediapipe/tasks-vision": ">=0.10"
+    "three": ">=0.160"
   },
   "peerDependenciesMeta": {
     "expo-gl": {
@@ -82,6 +84,9 @@
     },
     "@mediapipe/tasks-vision": {
       "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -90,6 +95,7 @@
     "@gltf-transform/functions": "^4.5.1",
     "@mediapipe/tasks-vision": "^1.1.1",
     "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
     "@types/three": "^0.186.0",
     "expo-file-system": "^19.0.24",
     "expo-gl": "^16.0.10",
@@ -97,6 +103,7 @@
     "gl-matrix": "^3.4.4",
     "meshoptimizer": "^1.3.0",
     "react": "^18.3.1",
+    "react-dom": "^18.3.1",
     "react-native": "^0.81.6",
     "sharp": "^0.35.5",
     "three": "^0.186.1",

package/src/human/catalog.ts

@@ -0,0 +1,95 @@
+// Item metadata for the editor: display names, which gender an item suits, and slot.
+// Ids match the asset package manifest (pkg.manifest). Items missing here still work;
+// they get a generated label and are treated as unisex.
+
+export type Fit = 'female' | 'male' | 'unisex';
+export type ClothingSlot = 'outfit' | 'shoes' | 'hat';
+
+export interface ItemInfo { label: string; fit: Fit }
+
+export const HAIR: Record<string, ItemInfo> = {
+  long01: { label: 'Long straight', fit: 'female' },
+  ponytail01: { label: 'Ponytail', fit: 'female' },
+  bob02: { label: 'Bob', fit: 'female' },
+  bob01: { label: 'Swept bob', fit: 'female' },
+  braid01: { label: 'Braid', fit: 'female' },
+  afro01: { label: 'Afro', fit: 'unisex' },
+  short01: { label: 'Short textured', fit: 'unisex' },
+  short02: { label: 'Short tousled', fit: 'male' },
+  short03: { label: 'Side fringe', fit: 'unisex' },
+  short04: { label: 'Slicked back', fit: 'male' },
+};
+
+export const CLOTHES: Record<string, ItemInfo & { slot: ClothingSlot }> = {
+  female_casualsuit01: { label: 'Casual tee', fit: 'female', slot: 'outfit' },
+  female_casualsuit02: { label: 'Casual layers', fit: 'female', slot: 'outfit' },
+  female_elegantsuit01: { label: 'Elegant', fit: 'female', slot: 'outfit' },
+  female_sportsuit01: { label: 'Sport', fit: 'female', slot: 'outfit' },
+  male_casualsuit01: { label: 'Casual 1', fit: 'male', slot: 'outfit' },
+  male_casualsuit02: { label: 'Casual 2', fit: 'male', slot: 'outfit' },
+  male_casualsuit03: { label: 'Casual 3', fit: 'male', slot: 'outfit' },
+  male_casualsuit04: { label: 'Casual 4', fit: 'male', slot: 'outfit' },
+  male_casualsuit05: { label: 'Casual 5', fit: 'male', slot: 'outfit' },
+  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' },
+  shoes01: { label: 'Shoes 1', fit: 'unisex', slot: 'shoes' },
+  shoes02: { label: 'Shoes 2', fit: 'unisex', slot: 'shoes' },
+  shoes03: { label: 'Shoes 3', fit: 'unisex', slot: 'shoes' },
+  shoes04: { label: 'Shoes 4', fit: 'unisex', slot: 'shoes' },
+  shoes05: { label: 'Shoes 5', fit: 'unisex', slot: 'shoes' },
+  shoes06: { label: 'Shoes 6', fit: 'unisex', slot: 'shoes' },
+  fedora01: { label: 'Fedora', fit: 'unisex', slot: 'hat' },
+  fedora_cocked: { label: 'Fedora (tilted)', fit: 'unisex', slot: 'hat' },
+};
+
+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',
+};
+
+/** Swatch colors for eye chips (approximate iris color). */
+export const EYE_SWATCH: Record<string, string> = {
+  brown: '#3b1d0e', brownlight: '#6b4a22', green: '#3f6a3a', blue: '#2f5f74', deepblue: '#38376a',
+  lightblue: '#6aa3b8', bluegreen: '#5f9a8a', grey: '#86928a', ice: '#9ab8a8',
+};
+
+/**
+ * Natural hair colors, as the tint multiplied over the grey hair textures (they average ~70%
+ * brightness, so tints are a bit lighter than the visible result).
+ */
+export const HUMAN_HAIR_COLORS: { id: string; label: string; color: string }[] = [
+  { id: 'black', label: 'Black', color: '#1a1412' },
+  { id: 'darkbrown', label: 'Dark brown', color: '#3d2618' },
+  { id: 'brown', label: 'Brown', color: '#6b4428' },
+  { id: 'lightbrown', label: 'Light brown', color: '#9a6a40' },
+  { id: 'auburn', label: 'Auburn', color: '#8e3b1f' },
+  { id: 'copper', label: 'Copper', color: '#c0602c' },
+  { id: 'darkblonde', label: 'Dark blonde', color: '#b88c55' },
+  { id: 'blonde', label: 'Blonde', color: '#e6c88a' },
+  { id: 'platinum', label: 'Platinum', color: '#f2ead8' },
+  { id: 'grey', label: 'Grey', color: '#a8a39c' },
+  { id: 'white', label: 'White', color: '#f4f2ee' },
+];
+
+/** Skin tint presets (multiplied over the skin texture; white = texture as-is). */
+export const SKIN_TINTS = ['#ffffff', '#fbefe6', '#f5e3d3', '#ffe9dc', '#efe2d6', '#e8d4c4'];
+
+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 fit: Fit = id.startsWith('female') ? 'female' : id.startsWith('male') ? 'male' : 'unisex';
+  return { label: cap(words(id.replace(/^(fe)?male_/, ''))), fit, slot };
+}
+export function skinInfo(id: string, tags: string[]): ItemInfo {
+  const fit: Fit = tags.some((t) => t.startsWith('female')) ? 'female' : tags.some((t) => t.startsWith('male')) ? 'male' : 'unisex';
+  const age = tags.includes('young') ? 'Young' : tags.includes('middleage') ? 'Middle-aged' : tags.includes('old') ? 'Older' : '';
+  const eth = tags.includes('african') ? 'African' : tags.includes('asian') ? 'Asian' : tags.includes('caucasian') ? 'European' : '';
+  const variant = /2$/.test(id) ? ' 2' : '';
+  return { label: [age, eth].filter(Boolean).join(' ') + variant || cap(words(id)), fit };
+}
+export const fits = (fit: Fit, gender: 'female' | 'male' | 'any') => gender === 'any' || fit === 'unisex' || fit === gender;

package/src/human/editor.ts

@@ -0,0 +1,249 @@
+// Platform-neutral avatar editor model. It turns the asset manifest plus developer options
+// (gender lock, which sections/attributes/items are editable) into a list of sections and
+// controls that the web and React Native <HumanEditor> components render.
+//
+//   const editor = createHumanEditor(pkg.manifest, { gender: 'female', exclude: ['ears', 'body.muscle'] });
+//   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 { DETAIL_SLIDERS, MACRO_SLIDERS } from './sliders';
+import { EYE_LABELS, EYE_SWATCH, 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 const ALL_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', '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'. */
+  gender?: EditorGender;
+  /** Sections to show, in order. Default ALL_SECTIONS. */
+  sections?: SectionId[];
+  /** Section ids or control ids to hide, e.g. ['ears', 'body.muscle', 'nose.noseHump', 'hair.color']. */
+  exclude?: string[];
+  /** If set, only these control ids are shown (sections without any are dropped). */
+  include?: string[];
+  /** 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>>;
+  /** 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). */
+  defaults?: Partial<HumanConfig>;
+  /** Values always enforced, whatever the user or a saved config says. */
+  locked?: Partial<HumanConfig>;
+  /** Label overrides by section or control id (e.g. for translation). */
+  labels?: Record<string, string>;
+}
+
+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 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[] }
+
+export interface HumanEditorModel {
+  options: HumanEditorOptions;
+  sections: EditorSection[];
+  /** Starting config that satisfies the options. */
+  initial: HumanConfig;
+  /** Repair any (saved or partial) config so it satisfies the options. */
+  normalize(c?: Partial<HumanConfig> | null): HumanConfig;
+  /** A random look within the allowed items and natural slider ranges. */
+  randomize(rand?: () => number): HumanConfig;
+  /** Allowed item ids per slot after gender filtering. */
+  allowed: Record<ItemSlot, string[]>;
+}
+
+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',
+};
+const FACE_SECTIONS: SectionId[] = ['face', 'skin', 'eyes', 'brows', 'nose', 'mouth', 'ears', 'hair', 'hat'];
+const BROW_SLIDERS = ['browHeight', 'browAngle', 'browDepth'];
+
+const GENDER_DEFAULTS: Record<'female' | 'male', Partial<HumanConfig>> = {
+  female: {
+    gender: 0, skin: 'young_caucasian_female', hair: 'long01', hairColor: '#6b4428', eyebrows: 'eyebrow002', eyebrowColor: '#3d2618',
+    eyelashes: 'eyelashes02', clothes: ['female_casualsuit02', 'shoes02'],
+  },
+  male: {
+    gender: 1, skin: 'young_caucasian_male', hair: 'short02', hairColor: '#3d2618', eyebrows: 'eyebrow001', eyebrowColor: '#2a1c14',
+    eyelashes: 'eyelashes01', clothes: ['male_casualsuit02', 'shoes01'],
+  },
+};
+
+const withDetail = (c: HumanConfig, id: string, v: number): HumanConfig => ({ ...c, detail: { ...c.detail, [id]: v } });
+
+export function createHumanEditor(manifest: HumanManifest, options: HumanEditorOptions = {}): HumanEditorModel {
+  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 };
+
+  // ---- allowed items
+  const restrict = (slot: ItemSlot, ids: string[]) => {
+    const only = options.items?.[slot];
+    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 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))),
+    outfit: restrict('outfit', bySlot('outfit')),
+    shoes: restrict('shoes', bySlot('shoes')),
+    hat: restrict('hat', bySlot('hat')),
+    skin: restrict('skin', manifest.skins.filter((s) => fits(skinInfo(s.id, s.tags).fit, gender)).map((s) => s.id)),
+    eyes: restrict('eyes', manifest.eyes),
+    eyebrows: restrict('eyebrows', manifest.proxies.filter((p) => p.kind === 'eyebrows').map((p) => p.id)),
+    eyelashes: restrict('eyelashes', manifest.proxies.filter((p) => p.kind === 'eyelashes').map((p) => p.id)),
+  };
+  // order hair by the catalog (best-looking first), then anything extra
+  allowed.hair.sort((a, b) => order(a) - order(b));
+
+  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;
+
+  // ---- 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));
+  const macro = (id: (typeof MACRO_SLIDERS)[number]['id'], lbl: string, min = 0, max = 1): SliderControl => ({
+    kind: 'slider', id, label: label(id, lbl), min, max, step: 0.01,
+    value: (c) => c[id], apply: (c, v) => ({ ...c, [id]: v }),
+  });
+  const detail = (id: string): SliderControl => {
+    const s = DETAIL_SLIDERS.find((d) => d.id === id)!;
+    return {
+      kind: 'slider', id, label: label(id, s.label), min: s.neg.length ? -range : 0, max: range, step: 0.01,
+      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 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 build: Record<SectionId, () => EditorControl[]> = {
+    face: () => [
+      ...(['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 })),
+    ],
+    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}` }))],
+        (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}` }))],
+        (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),
+    ],
+    nose: () => DETAIL_SLIDERS.filter((d) => d.group === 'nose').map((d) => detail(d.id)),
+    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) }))],
+        (c) => c.hair, (c, v) => ({ ...c, hair: v })),
+      color('color', 'Hair color', hairColors, (c) => c.hairColor, (c, v) => ({ ...c, hairColor: v })),
+    ],
+    body: () => [
+      ...(gender === 'any' ? [macro('gender', 'Gender')] : []),
+      macro('age', 'Age'), macro('weight', 'Weight'), macro('muscle', 'Muscle'), macro('height', 'Height'), macro('proportions', 'Proportions'),
+      ...(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)],
+    shoes: () => [clothingChoice('shoes', 'Shoes', optional.shoes)],
+    hat: () => [clothingChoice('hat', 'Hat', optional.hat)],
+  };
+
+  const sections: EditorSection[] = [];
+  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 (controls.length) sections.push({ id, label: label(id, SECTION_LABELS[id]), framing: FACE_SECTIONS.includes(id) ? 'face' : 'body', controls });
+  }
+
+  // ---- normalize: defaults <- input <- locked, then repair anything not allowed
+  const genderDefaults = gender === 'any' ? {} : GENDER_DEFAULTS[gender];
+  const base: HumanConfig = { ...DEFAULT_HUMAN, ...genderDefaults, ...options.defaults, detail: { ...DEFAULT_HUMAN.detail, ...options.defaults?.detail } } as HumanConfig;
+  const pick = (want: string | null | undefined, ids: string[], fallback: string | null | undefined) =>
+    want && ids.includes(want) ? want : fallback && ids.includes(fallback) ? fallback : ids[0] ?? null;
+
+  function normalize(input?: Partial<HumanConfig> | null): HumanConfig {
+    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;
+    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 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)];
+    return c;
+  }
+
+  function randomize(rand: () => number = Math.random): HumanConfig {
+    const any = <T,>(a: T[]) => a[Math.floor(rand() * a.length)];
+    const c = normalize();
+    const mix = [rand(), rand(), rand()];
+    const sum = mix[0] + mix[1] + mix[2];
+    const detail: Record<string, number> = {};
+    for (const d of DETAIL_SLIDERS) if (d.group !== 'body') detail[d.id] = d.neg.length ? (rand() * 2 - 1) * 0.35 * range : rand() * 0.25 * range;
+    return normalize({
+      ...c, detail,
+      african: mix[0] / sum, asian: mix[1] / sum, caucasian: mix[2] / sum,
+      age: rand() * 0.45, weight: 0.35 + rand() * 0.3, muscle: 0.35 + rand() * 0.3, height: 0.3 + rand() * 0.4,
+      skin: any(allowed.skin) ?? c.skin, eyes: any(allowed.eyes) ?? c.eyes,
+      hair: any(allowed.hair) ?? c.hair, hairColor: any(hairColors), eyebrows: any(allowed.eyebrows) ?? c.eyebrows,
+      clothes: [any(allowed.outfit), any(allowed.shoes)].filter(Boolean) as string[],
+    });
+  }
+
+  return { options, sections, initial: normalize(), normalize, randomize, allowed };
+}
+
+const HAIR_ORDER = ['long01', 'ponytail01', 'bob02', 'afro01', 'short02', '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). */
+function closestSkin(id: string, allowed: string[], manifest: HumanManifest) {
+  const tags = manifest.skins.find((s) => s.id === id)?.tags ?? [];
+  let best: string | null = null, score = -1;
+  for (const a of allowed) {
+    const t = manifest.skins.find((s) => s.id === a)?.tags ?? [];
+    const sc = t.filter((x) => tags.includes(x)).length;
+    if (sc > score) { score = sc; best = a; }
+  }
+  return best;
+}

package/src/human/export.ts

@@ -23,7 +23,10 @@ export async function exportHumanGLB(avatar: HumanAvatar): Promise<Uint8Array> {
     const alpha = mat.transparent || mat.alphaTest > 0;
     for (const t of [mat.map, mat.normalMap]) if (t) t.userData.mimeType = alpha ? 'image/png' : 'image/jpeg';
   });
-  const raw = (await new GLTFExporter().parseAsync(avatar.group, { binary: true, onlyVisible: true })) as ArrayBuffer;
+  // the hair's soft-tip pass is a render-time duplicate; export the mesh once
+  const tips: SkinnedMesh[] = [];
+  avatar.group.traverse((o) => { if (o.userData.softPass && o.visible) { tips.push(o as SkinnedMesh); o.visible = false; } });
+  const raw = (await new GLTFExporter().parseAsync(avatar.group, { binary: true, onlyVisible: true }).finally(() => tips.forEach((t) => (t.visible = true)))) as ArrayBuffer;
   const io = new WebIO().registerExtensions([KHRMeshQuantization]);
   const doc = await io.readBinary(new Uint8Array(raw));
   // quantize first: it rewrites accessors, which would drop the sparse flag set by sparse()

package/src/human/index.ts

@@ -1,3 +1,5 @@
 export * from './runtime';
 export * from './sliders';
 export * from './fit';
+export * from './catalog';
+export * from './editor';

package/src/human/runtime.ts

@@ -236,7 +236,19 @@ function geometryFrom(prim: GlbPrimitive, joints: string, weights: string) {
   return g;
 }
 
-interface ProxyInstance { meta: ProxyMeta; mesh: SkinnedMesh; refs: Uint16Array; refw: Float32Array; offs: Float32Array }
+/**
+ * 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.
+ */
+function hairShading(m: MeshStandardMaterial) {
+  m.onBeforeCompile = (sh) => {
+    sh.fragmentShader = sh.fragmentShader.replace('#include <map_fragment>',
+      '#include <map_fragment>\n\tdiffuseColor.rgb *= mix(0.35, 1.0, smoothstep(0.05, 0.85, diffuseColor.a));');
+  };
+  m.customProgramCacheKey = () => 'humanforge-hair';
+}
+
+interface ProxyInstance { meta: ProxyMeta; mesh: SkinnedMesh; soft?: SkinnedMesh; refs: Uint16Array; refw: Float32Array; offs: Float32Array }
 
 export class HumanAvatar {
   readonly group = new Group();
@@ -325,13 +337,14 @@ export class HumanAvatar {
       this.removeProxy(entry[0]);
       this.proxies.set(entry[0], entry[1]);
       this.group.add(entry[1].mesh);
+      if (entry[1].soft) this.group.add(entry[1].soft);
     }
     this.skinMat.map = skinTex;
     this.skinMat.color.set(c.skinTint);
     this.skinMat.needsUpdate = true;
     for (const [slot, p] of this.proxies) {
       const m = p.mesh.material as MeshStandardMaterial;
-      if (slot === 'hair') m.color.set(c.hairColor);
+      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; }
     }
@@ -386,9 +399,25 @@ export class HumanAvatar {
       roughness: meta.kind === 'eyes' ? 0.15 : meta.kind === 'hair' ? 0.55 : 0.8,
       side: meta.doubleSided ? DoubleSide : FrontSide,
     });
+    let soft: SkinnedMesh | undefined;
     if (meta.kind === 'hair') {
-      mat.alphaTest = 0.3;
+      // Two passes: a solid core (alpha-tested, writes depth, so strands sort correctly) and a
+      // blended pass for the soft strand tips the cutout would otherwise chop off.
+      mat.alphaTest = 0.5;
       mat.alphaToCoverage = true;
+      mat.side = DoubleSide;
+      hairShading(mat);
+      const tips = mat.clone();
+      hairShading(tips);
+      tips.alphaTest = 0.04;
+      tips.alphaToCoverage = false;
+      tips.transparent = true;
+      tips.depthWrite = false;
+      soft = new SkinnedMesh(geo, tips);
+      soft.name = `${fullId}-tips`;
+      soft.userData.softPass = true;
+      soft.frustumCulled = false;
+      soft.renderOrder = 3;
     } else if (meta.transparent) {
       mat.transparent = true;
       mat.depthWrite = false;
@@ -403,7 +432,7 @@ export class HumanAvatar {
       mesh.morphTargetDictionary = this.body.morphTargetDictionary;
       mesh.morphTargetInfluences = [...(this.body.morphTargetInfluences ?? [])];
     }
-    return { meta, mesh, refs, refw, offs };
+    return { meta, mesh, soft, refs, refw, offs };
   }
 
   private removeProxy(slot: string) {
@@ -412,6 +441,7 @@ export class HumanAvatar {
     this.group.remove(p.mesh);
     p.mesh.geometry.dispose();
     (p.mesh.material as Material).dispose();
+    if (p.soft) { this.group.remove(p.soft); (p.soft.material as Material).dispose(); }
     this.proxies.delete(slot);
   }
 
@@ -488,7 +518,10 @@ export class HumanAvatar {
     });
     this.group.updateMatrixWorld(true);
     this.body.bind(this.skeleton); // recomputes bone inverses for the new rest pose
-    for (const p of this.proxies.values()) p.mesh.bind(this.skeleton, this.body.bindMatrix);
+    for (const p of this.proxies.values()) {
+      p.mesh.bind(this.skeleton, this.body.bindMatrix);
+      p.soft?.bind(this.skeleton, this.body.bindMatrix);
+    }
   }
 
   /** Head height and total height (world space at rest), for camera framing. */

package/src/native/HumanEditor.tsx

@@ -0,0 +1,186 @@
+// <HumanEditor> for React Native (Expo): the same developer-controlled editor as the web one,
+// built only from React Native primitives (no slider/UI dependencies).
+//
+//   <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 type { HumanConfig, HumanPackage } from '../human/runtime';
+import { EditorControl, HumanEditorModel as EditorModel, HumanEditorOptions, createHumanEditor } from '../human/editor';
+import { HumanView, HumanViewHandle } from './HumanView';
+
+export interface HumanEditorProps {
+  pkg: HumanPackage;
+  /** What users may edit (gender lock, sections, items…). Ignored if `editor` is given. */
+  options?: HumanEditorOptions;
+  editor?: EditorModel;
+  /** Controlled value. */
+  value?: Partial<HumanConfig>;
+  /** Uncontrolled starting value (e.g. the user's saved avatar). */
+  defaultValue?: Partial<HumanConfig>;
+  onChange?: (config: HumanConfig) => void;
+  /** Shows a Save button; gets the config (store as JSON) and a PNG file URI of the avatar. */
+  onSave?: (config: HumanConfig, snapshotUri: string | null) => void;
+  onCancel?: () => void;
+  saveLabel?: string;
+  randomize?: boolean;
+  accentColor?: string;
+  background?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+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 [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
+  const config = value ? editor.normalize(value) : inner;
+  const [tab, setTab] = useState(0);
+  const [framing, setFraming] = useState<'face' | 'body' | null>(null);
+  const view = useRef<HumanViewHandle>(null);
+  const section = editor.sections[Math.min(tab, editor.sections.length - 1)];
+
+  const update = (next: HumanConfig) => {
+    const n = editor.normalize(next);
+    if (!value) setInner(n);
+    onChange?.(n);
+  };
+  if (!section) return <View style={style}><Text>No editable sections.</Text></View>;
+  const shot = framing ?? section.framing;
+
+  return (
+    <View style={[s.root, style]}>
+      <View style={s.preview}>
+        <HumanView ref={view} pkg={pkg} config={config} framing={shot} background={background} style={StyleSheet.absoluteFill} />
+        <View style={s.toolbar} pointerEvents="box-none">
+          {onCancel ? <Pill label="Cancel" onPress={onCancel} /> : null}
+          <View style={s.seg}>
+            {(['face', 'body'] as const).map((f) => (
+              <Pressable key={f} onPress={() => setFraming(f)} style={[s.segBtn, shot === f && { backgroundColor: accentColor }]}>
+                <Text style={[s.segText, shot === f && { color: '#fff' }]}>{f === 'face' ? 'Face' : 'Body'}</Text>
+              </Pressable>
+            ))}
+          </View>
+          {randomize ? <Pill label="🎲" onPress={() => update(editor.randomize())} /> : null}
+        </View>
+      </View>
+
+      <ScrollView horizontal showsHorizontalScrollIndicator={false} style={s.tabs} contentContainerStyle={s.tabsInner}>
+        {editor.sections.map((sec, i) => (
+          <Pressable key={sec.id} onPress={() => { setTab(i); setFraming(null); }} style={[s.tab, sec === section && { backgroundColor: accentColor }]}>
+            <Text style={[s.tabText, sec === section && { color: '#fff' }]}>{sec.label}</Text>
+          </Pressable>
+        ))}
+      </ScrollView>
+
+      <ScrollView style={s.panel} contentContainerStyle={{ padding: 16, paddingBottom: 24 }} keyboardShouldPersistTaps="handled">
+        {section.controls.map((ctl) => <Control key={`${section.id}.${ctl.id}`} ctl={ctl} config={config} onChange={update} accent={accentColor} />)}
+      </ScrollView>
+
+      {onSave ? (
+        <Pressable style={[s.save, { backgroundColor: accentColor }]} onPress={async () => onSave(config, (await view.current?.snapshot()) ?? null)}>
+          <Text style={s.saveText}>{saveLabel}</Text>
+        </Pressable>
+      ) : null}
+    </View>
+  );
+}
+
+function Control({ ctl, config, onChange, accent }: { ctl: EditorControl; config: HumanConfig; onChange: (c: HumanConfig) => void; accent: string }) {
+  if (ctl.kind === 'slider') {
+    return (
+      <View style={s.row}>
+        <Text style={s.label}>{ctl.label}</Text>
+        <Slider value={ctl.value(config)} min={ctl.min} max={ctl.max} accent={accent} onChange={(v) => onChange(ctl.apply(config, v))} />
+      </View>
+    );
+  }
+  if (ctl.kind === 'color') {
+    const v = ctl.value(config).toLowerCase();
+    return (
+      <View style={s.block}>
+        <Text style={s.blockLabel}>{ctl.label}</Text>
+        <View style={s.wrap}>
+          {ctl.colors.map((c) => (
+            <Pressable key={c} accessibilityLabel={c} onPress={() => onChange(ctl.apply(config, c))}
+              style={[s.swatch, { backgroundColor: c }, c.toLowerCase() === v && { borderColor: accent }]} />
+          ))}
+        </View>
+      </View>
+    );
+  }
+  const v = ctl.value(config);
+  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>
+        ))}
+      </View>
+    </View>
+  );
+}
+
+/** Minimal slider (no native dependency). Updates while dragging; tap to jump. */
+function Slider({ value, min, max, onChange, accent }: { value: number; min: number; max: number; onChange: (v: number) => void; accent: string }) {
+  const width = useRef(1);
+  const latest = useRef(onChange);
+  latest.current = onChange;
+  const toValue = (x: number) => Math.round((min + (Math.max(0, Math.min(width.current, x)) / width.current) * (max - min)) * 100) / 100;
+  const pan = useMemo(() => PanResponder.create({
+    onStartShouldSetPanResponder: () => true,
+    onMoveShouldSetPanResponder: () => true,
+    onPanResponderTerminationRequest: () => false,
+    onPanResponderGrant: (e) => latest.current(toValue(e.nativeEvent.locationX)),
+    onPanResponderMove: (e) => latest.current(toValue(e.nativeEvent.locationX)),
+  }), [min, max]);
+  const t = (value - min) / (max - min || 1);
+  return (
+    <View style={s.slider} onLayout={(e: LayoutChangeEvent) => (width.current = e.nativeEvent.layout.width)} {...pan.panHandlers}>
+      <View style={s.track} pointerEvents="none">
+        <View style={[s.fill, { width: `${t * 100}%`, backgroundColor: accent }]} />
+      </View>
+      <View pointerEvents="none" style={[s.thumb, { left: `${t * 100}%`, borderColor: accent }]} />
+    </View>
+  );
+}
+
+function Pill({ label, onPress }: { label: string; onPress: () => void }) {
+  return <Pressable onPress={onPress} style={s.pill}><Text style={s.pillText}>{label}</Text></Pressable>;
+}
+
+const s = StyleSheet.create({
+  root: { flex: 1, backgroundColor: '#fff' },
+  preview: { height: '48%' },
+  toolbar: { position: 'absolute', top: 12, left: 12, right: 12, flexDirection: 'row', gap: 8, alignItems: 'center' },
+  seg: { flexDirection: 'row', backgroundColor: 'rgba(255,255,255,0.92)', borderRadius: 999, padding: 3 },
+  segBtn: { paddingHorizontal: 14, paddingVertical: 6, borderRadius: 999 },
+  segText: { fontSize: 13, color: '#1d1d1f' },
+  pill: { backgroundColor: 'rgba(255,255,255,0.92)', borderRadius: 999, paddingHorizontal: 12, paddingVertical: 7 },
+  pillText: { fontSize: 13, color: '#1d1d1f' },
+  tabs: { flexGrow: 0, borderBottomWidth: StyleSheet.hairlineWidth, borderBottomColor: '#e3e5e8' },
+  tabsInner: { paddingHorizontal: 12, paddingVertical: 10, gap: 6 },
+  tab: { paddingHorizontal: 14, paddingVertical: 8, borderRadius: 999, backgroundColor: '#f2f3f5' },
+  tabText: { fontSize: 13, fontWeight: '500', color: '#444' },
+  panel: { flex: 1 },
+  row: { flexDirection: 'row', alignItems: 'center', marginVertical: 8 },
+  label: { width: 112, fontSize: 12, color: '#666' },
+  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 },
+  slider: { flex: 1, height: 32, justifyContent: 'center' },
+  track: { height: 4, borderRadius: 2, backgroundColor: '#e3e5e8', overflow: 'hidden' },
+  fill: { height: 4 },
+  thumb: { position: 'absolute', width: 22, height: 22, marginLeft: -11, borderRadius: 11, backgroundColor: '#fff', borderWidth: 2 },
+  save: { margin: 16, marginTop: 0, borderRadius: 12, paddingVertical: 14, alignItems: 'center' },
+  saveText: { color: '#fff', fontSize: 15, fontWeight: '600' },
+});

package/src/native/index.ts

@@ -5,3 +5,5 @@ export type { AvatarCreatorProps } from './AvatarCreator';
 export { HumanView, useHumanPackage } from './HumanView';
 export type { HumanViewHandle, HumanViewProps } from './HumanView';
 export { expoFetch, expoLoadOptions, expoTextureLoader } from './humanExpo';
+export { HumanEditor } from './HumanEditor';
+export type { HumanEditorProps } from './HumanEditor';

package/src/web/HumanCanvas.tsx

@@ -0,0 +1,146 @@
+// <HumanCanvas>: the realistic avatar in a React (web) app. Renders on demand only.
+import React, { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import {
+  ACESFilmicToneMapping, Color, DirectionalLight, HemisphereLight, PMREMGenerator, PerspectiveCamera, Scene, SRGBColorSpace,
+  Vector3, WebGLRenderer,
+} from 'three';
+import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
+import { HumanAvatar, HumanConfig, HumanPackage } from '../human/runtime';
+
+export interface HumanCanvasProps {
+  pkg: HumanPackage;
+  config: Partial<HumanConfig>;
+  framing?: 'face' | 'body';
+  /** ARKit-style expression weights, e.g. { mouthSmile: 0.6 } */
+  expressions?: Record<string, number>;
+  background?: string;
+  /** Drag to turn the avatar. Default true. */
+  rotatable?: boolean;
+  textureSize?: '1k' | '2k';
+  className?: string;
+  style?: React.CSSProperties;
+  onReady?: (avatar: HumanAvatar) => void;
+}
+
+export interface HumanCanvasHandle {
+  avatar: HumanAvatar | null;
+  render(): void;
+  /** PNG data URL of the current view. */
+  snapshot(): string | null;
+}
+
+interface Stage { renderer: WebGLRenderer; scene: Scene; camera: PerspectiveCamera; avatar: HumanAvatar; yaw: number; framing: 'face' | 'body'; frame?: number; ready: boolean }
+
+export const HumanCanvas = forwardRef<HumanCanvasHandle, HumanCanvasProps>(function HumanCanvas(
+  { pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '2k', className, style, onReady }, ref,
+) {
+  const host = useRef<HTMLDivElement>(null);
+  const stage = useRef<Stage | null>(null);
+  const ready = useRef(onReady);
+  ready.current = onReady;
+
+  const draw = () => {
+    const s = stage.current;
+    // the skeleton is only bound after the first setConfig
+    if (!s || !s.ready || s.frame) return;
+    s.frame = requestAnimationFrame(() => {
+      s.frame = 0;
+      const m = s.avatar.metrics();
+      const face = s.framing === 'face';
+      const target = face ? new Vector3(0, m.headY - 0.08, 0) : new Vector3(0, m.height * 0.52, 0);
+      const h = face ? 0.42 : m.height * 1.12;
+      const dist = h / 2 / Math.tan((s.camera.fov * Math.PI) / 360) / Math.min(1, s.camera.aspect * 1.1);
+      s.camera.position.set(Math.sin(s.yaw) * dist, target.y + dist * 0.03, Math.cos(s.yaw) * dist);
+      s.camera.lookAt(target);
+      s.renderer.render(s.scene, s.camera);
+    });
+  };
+
+  useEffect(() => {
+    const el = host.current!;
+    const renderer = new WebGLRenderer({ antialias: true, preserveDrawingBuffer: true, alpha: false });
+    renderer.setPixelRatio(Math.min(2, devicePixelRatio));
+    renderer.outputColorSpace = SRGBColorSpace;
+    renderer.toneMapping = ACESFilmicToneMapping;
+    Object.assign(renderer.domElement.style, { width: '100%', height: '100%', display: 'block', touchAction: 'none', cursor: rotatable ? 'grab' : 'default' });
+    el.appendChild(renderer.domElement);
+    const scene = new Scene();
+    scene.background = new Color(background);
+    const pmrem = new PMREMGenerator(renderer);
+    scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
+    scene.environmentIntensity = 0.55;
+    const key = new DirectionalLight('#fff4e8', 1.6);
+    key.position.set(1.2, 2.2, 2.5);
+    const rim = new DirectionalLight('#dfe8ff', 0.9);
+    rim.position.set(-2, 2, -2);
+    scene.add(key, rim, new HemisphereLight('#ffffff', '#b9a99a', 0.4));
+    const avatar = new HumanAvatar(pkg);
+    avatar.textureSize = textureSize;
+    scene.add(avatar.group);
+    const s: Stage = { renderer, scene, camera: new PerspectiveCamera(24, 1, 0.05, 50), avatar, yaw: 0, framing, ready: false };
+    stage.current = s;
+
+    const resize = () => {
+      const w = Math.max(1, el.clientWidth), h = Math.max(1, el.clientHeight);
+      renderer.setSize(w, h, false);
+      s.camera.aspect = w / h;
+      s.camera.updateProjectionMatrix();
+      draw();
+    };
+    const ro = new ResizeObserver(resize);
+    ro.observe(el);
+    resize();
+
+    let drag: number | null = null;
+    const canvas = renderer.domElement;
+    canvas.onpointerdown = (e) => { if (!rotatable) return; drag = e.clientX; canvas.setPointerCapture(e.pointerId); canvas.style.cursor = 'grabbing'; };
+    canvas.onpointermove = (e) => { if (drag === null) return; s.yaw -= (e.clientX - drag) * 0.01; drag = e.clientX; draw(); };
+    canvas.onpointerup = canvas.onpointercancel = () => { drag = null; canvas.style.cursor = rotatable ? 'grab' : 'default'; };
+
+    return () => {
+      ro.disconnect();
+      if (s.frame) cancelAnimationFrame(s.frame);
+      avatar.dispose();
+      pmrem.dispose();
+      renderer.dispose();
+      canvas.remove();
+      stage.current = null;
+    };
+  }, [pkg]);
+
+  const key = JSON.stringify(config);
+  useEffect(() => {
+    const s = stage.current;
+    if (!s) return;
+    let live = true;
+    s.avatar.setConfig(config).then(() => {
+      if (!live) return;
+      s.ready = true;
+      draw();
+      ready.current?.(s.avatar);
+    });
+    return () => { live = false; };
+  }, [key, pkg]);
+
+  useEffect(() => {
+    const s = stage.current;
+    if (!s) return;
+    s.framing = framing;
+    (s.scene.background as Color).set(background);
+    for (const name of s.avatar.expressionNames) s.avatar.setExpression(name, expressions?.[name] ?? 0);
+    draw();
+  }, [framing, background, JSON.stringify(expressions)]);
+
+  useImperativeHandle(ref, () => ({
+    get avatar() { return stage.current?.avatar ?? null; },
+    render: draw,
+    snapshot() {
+      const s = stage.current;
+      if (!s) return null;
+      s.renderer.render(s.scene, s.camera);
+      return s.renderer.domElement.toDataURL('image/png');
+    },
+  }));
+
+  return <div ref={host} className={className} style={{ position: 'relative', overflow: 'hidden', ...style }} />;
+});

package/src/web/HumanEditor.tsx

@@ -0,0 +1,198 @@
+// <HumanEditor>: drop-in avatar customization UI for React (web). The developer decides what
+// users may edit through `options` (see HumanEditorOptions in ../human/editor).
+//
+//   <HumanEditor pkg={pkg} options={{ gender: 'female', exclude: ['ears'] }} onSave={(config) => api.save(config)} />
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import type { HumanConfig, HumanPackage } from '../human/runtime';
+import { EditorControl, HumanEditorModel as EditorModel, HumanEditorOptions, createHumanEditor } from '../human/editor';
+import { HumanCanvas, HumanCanvasHandle } from './HumanCanvas';
+
+export interface HumanEditorProps {
+  pkg: HumanPackage;
+  /** What users may edit. Ignored if `editor` is given. */
+  options?: HumanEditorOptions;
+  /** A prebuilt editor model (createHumanEditor), to share it with your own code. */
+  editor?: EditorModel;
+  /** Controlled value. */
+  value?: Partial<HumanConfig>;
+  /** Uncontrolled starting value (e.g. the user's saved avatar). */
+  defaultValue?: Partial<HumanConfig>;
+  onChange?: (config: HumanConfig) => void;
+  /** Shows a Save button. Gets the config (store it as JSON) and a PNG snapshot. */
+  onSave?: (config: HumanConfig, snapshot: string | null) => void;
+  saveLabel?: string;
+  /** Show a "From selfie" button (needs @mediapipe/tasks-vision). */
+  selfie?: boolean;
+  /** Show a randomize button. Default true. */
+  randomize?: boolean;
+  accentColor?: string;
+  background?: string;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+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 [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
+  const config = value ? editor.normalize(value) : inner;
+  const [tab, setTab] = useState(0);
+  const [framing, setFraming] = useState<'face' | 'body' | null>(null);
+  const [busy, setBusy] = useState<string | null>(null);
+  const canvas = useRef<HumanCanvasHandle>(null);
+  const file = useRef<HTMLInputElement>(null);
+  const section = editor.sections[Math.min(tab, editor.sections.length - 1)];
+
+  useEffect(() => { if (!value) setInner((c) => editor.normalize(c)); }, [editor]);
+  useStyles();
+
+  const update = (next: HumanConfig) => {
+    const n = editor.normalize(next);
+    if (!value) setInner(n);
+    onChange?.(n);
+  };
+
+  const fromSelfie = async (f: File) => {
+    setBusy('Reading your photo…');
+    try {
+      const { createSelfieFitter } = await import('../human/selfie');
+      const fitter = await (fitterCache ??= createSelfieFitter());
+      const g = editor.options.gender;
+      const res = await fitter.fit(pkg, f, {
+        base: { ...config, detail: {} },
+        hints: g === 'female' ? { gender: 0 } : g === 'male' ? { gender: 1 } : { gender: config.gender },
+      });
+      const c = res.config;
+      update({ ...config, african: c.african, asian: c.asian, caucasian: c.caucasian, skin: c.skin, skinTint: c.skinTint, eyes: c.eyes, detail: { ...config.detail, ...c.detail } });
+      setBusy(null);
+    } catch (e) {
+      setBusy(`Couldn't read a face: ${(e as Error).message}`);
+      setTimeout(() => setBusy(null), 3000);
+    }
+  };
+
+  if (!section) return <div className="hf-editor">No editable sections.</div>;
+  const view = framing ?? section.framing;
+
+  return (
+    <div className={`hf-root ${className ?? ''}`} style={{ ['--hf-accent' as any]: accentColor, ...style }}>
+    <div className="hf-editor">
+      <div className="hf-stage">
+        <HumanCanvas ref={canvas} pkg={pkg} config={config} framing={view} background={background} style={{ position: 'absolute', inset: 0 }} />
+        <div className="hf-toolbar">
+          <div className="hf-seg">
+            <button className={view === 'face' ? 'on' : ''} onClick={() => setFraming('face')}>Face</button>
+            <button className={view === 'body' ? 'on' : ''} onClick={() => setFraming('body')}>Body</button>
+          </div>
+          {randomize && <button className="hf-btn" title="Random look" onClick={() => update(editor.randomize())}>🎲</button>}
+          {selfie && <button className="hf-btn" onClick={() => file.current?.click()}>📷 Selfie</button>}
+          <input ref={file} type="file" accept="image/*" hidden onChange={(e) => { const f = e.target.files?.[0]; if (f) fromSelfie(f); e.target.value = ''; }} />
+        </div>
+        {busy && <div className="hf-toast">{busy}</div>}
+      </div>
+      <div className="hf-panel">
+        <div className="hf-tabs" role="tablist">
+          {editor.sections.map((s, i) => (
+            <button key={s.id} role="tab" aria-selected={s === section} className={s === section ? 'on' : ''} onClick={() => { setTab(i); setFraming(null); }}>
+              {s.label}
+            </button>
+          ))}
+        </div>
+        <div className="hf-controls">
+          {section.controls.map((ctl) => <Control key={`${section.id}.${ctl.id}`} ctl={ctl} config={config} onChange={update} />)}
+        </div>
+        {onSave && <button className="hf-save" onClick={() => onSave(config, canvas.current?.snapshot() ?? null)}>{saveLabel}</button>}
+      </div>
+    </div>
+    </div>
+  );
+}
+let fitterCache: Promise<any> | undefined;
+
+function Control({ ctl, config, onChange }: { ctl: EditorControl; config: HumanConfig; onChange: (c: HumanConfig) => void }) {
+  if (ctl.kind === 'slider') {
+    const v = ctl.value(config);
+    return (
+      <label className="hf-row">
+        <span className="hf-label">{ctl.label}</span>
+        <input type="range" min={ctl.min} max={ctl.max} step={ctl.step} value={v} onChange={(e) => onChange(ctl.apply(config, Number(e.target.value)))}
+          onDoubleClick={() => onChange(ctl.apply(config, ctl.min < 0 ? 0 : (ctl.min + ctl.max) / 2))} />
+      </label>
+    );
+  }
+  if (ctl.kind === 'color') {
+    const v = ctl.value(config).toLowerCase();
+    return (
+      <div className="hf-block">
+        <span className="hf-label">{ctl.label}</span>
+        <div className="hf-swatches">
+          {ctl.colors.map((c) => (
+            <button key={c} aria-label={c} className={`hf-swatch ${c.toLowerCase() === v ? 'on' : ''}`} style={{ background: c }} onClick={() => onChange(ctl.apply(config, c))} />
+          ))}
+        </div>
+      </div>
+    );
+  }
+  const v = ctl.value(config);
+  return (
+    <div className="hf-block">
+      <span className="hf-label">{ctl.label}</span>
+      <div className="hf-choices">
+        {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>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+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}
+.hf-stage{position:relative;min-height:260px;min-width:0}
+.hf-toolbar{position:absolute;top:12px;left:12px;right:12px;display:flex;gap:8px;flex-wrap:wrap;pointer-events:none}
+.hf-toolbar>*{pointer-events:auto}
+.hf-seg{display:flex;background:rgba(255,255,255,.9);border-radius:999px;padding:3px;box-shadow:0 1px 4px rgba(0,0,0,.08)}
+.hf-seg button,.hf-btn{border:0;background:transparent;border-radius:999px;padding:6px 12px;font:inherit;cursor:pointer;color:inherit}
+.hf-seg button.on{background:var(--hf-accent);color:#fff}
+.hf-btn{background:rgba(255,255,255,.9);box-shadow:0 1px 4px rgba(0,0,0,.08)}
+.hf-btn:hover{background:#fff}
+.hf-toast{position:absolute;left:50%;bottom:16px;transform:translateX(-50%);background:rgba(29,29,31,.85);color:#fff;padding:8px 14px;border-radius:999px}
+.hf-panel{display:flex;flex-direction:column;border-left:1px solid #eceef1;min-height:0;min-width:0}
+.hf-tabs{display:flex;gap:4px;overflow-x:auto;padding:12px 12px 8px;border-bottom:1px solid #eceef1;scrollbar-width:none}
+.hf-tabs::-webkit-scrollbar{display:none}
+.hf-tabs button{flex:none;border:0;background:#f2f3f5;border-radius:999px;padding:7px 13px;font:inherit;font-weight:500;cursor:pointer;color:#444}
+.hf-tabs button.on{background:var(--hf-accent);color:#fff}
+.hf-controls{flex:1;overflow-y:auto;padding:8px 16px 16px}
+.hf-row{display:grid;grid-template-columns:118px 1fr;align-items:center;gap:10px;margin:9px 0}
+.hf-row input{width:100%;accent-color:var(--hf-accent)}
+.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-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}}
+`;
+let injected = false;
+function useStyles() {
+  useEffect(() => {
+    if (injected || typeof document === 'undefined') return;
+    injected = true;
+    const el = document.createElement('style');
+    el.dataset.humanforge = '';
+    el.textContent = CSS;
+    document.head.appendChild(el);
+  }, []);
+}

package/src/web/index.ts

@@ -0,0 +1,29 @@
+// React (web) components. Import from 'humanforge/web'.
+import { useEffect, useState } from 'react';
+import { HumanPackage, LoadOptions, loadHumanPackage } from '../human/runtime';
+
+export { HumanCanvas } from './HumanCanvas';
+export type { HumanCanvasHandle, HumanCanvasProps } from './HumanCanvas';
+export { HumanEditor } from './HumanEditor';
+export type { HumanEditorProps } from './HumanEditor';
+export * from '../human/editor';
+export * from '../human/catalog';
+
+const packages = new Map<string, Promise<HumanPackage>>();
+/** Load the human asset package once per URL (shared by every component on the page). */
+export function useHumanPackage(baseUrl: string, opts?: LoadOptions) {
+  const [pkg, setPkg] = useState<HumanPackage | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  useEffect(() => {
+    let p = packages.get(baseUrl);
+    if (!p) {
+      p = loadHumanPackage(baseUrl, opts);
+      packages.set(baseUrl, p);
+      p.catch(() => packages.delete(baseUrl));
+    }
+    let live = true;
+    p.then((v) => live && setPkg(v), (e) => live && setError(e));
+    return () => { live = false; };
+  }, [baseUrl]);
+  return { pkg, error };
+}