humanforge 0.0.0-stage → 0.1.1

package/src/human/sliders.ts

@@ -0,0 +1,145 @@
+// Slider definitions for the realistic human. Shared by the asset build
+// (tools/build-human.ts decides which MakeHuman targets to bake) and the runtime.
+//
+// Detail sliders range -1..1: negative applies `neg` targets, positive applies `pos`.
+// Targets are MakeHuman target paths relative to data/targets (without .target.gz).
+
+export interface DetailSlider {
+  id: string;
+  label: string;
+  group: 'head' | 'eyes' | 'nose' | 'mouth' | 'ears' | 'body';
+  neg: string[];
+  pos: string[];
+}
+
+const lr = (dir: string, name: string) => [`${dir}/l-${name}`, `${dir}/r-${name}`];
+const pair = (id: string, label: string, group: DetailSlider['group'], dir: string, base: string, n = 'decr', p = 'incr'): DetailSlider =>
+  ({ id, label, group, neg: [`${dir}/${base}-${n}`], pos: [`${dir}/${base}-${p}`] });
+const pairLR = (id: string, label: string, group: DetailSlider['group'], dir: string, base: string, n = 'decr', p = 'incr'): DetailSlider =>
+  ({ id, label, group, neg: lr(dir, `${base}-${n}`), pos: lr(dir, `${base}-${p}`) });
+const one = (id: string, label: string, group: DetailSlider['group'], target: string): DetailSlider =>
+  ({ id, label, group, neg: [], pos: [target] });
+
+export const DETAIL_SLIDERS: DetailSlider[] = [
+  // head & face shape
+  pair('headWidth', 'Head width', 'head', 'head', 'head-scale-horiz'),
+  pair('headHeight', 'Head height', 'head', 'head', 'head-scale-vert'),
+  pair('headDepth', 'Head depth', 'head', 'head', 'head-scale-depth'),
+  pair('faceFat', 'Face fullness', 'head', 'head', 'head-fat'),
+  one('headOval', 'Oval face', 'head', 'head/head-oval'),
+  one('headRound', 'Round face', 'head', 'head/head-round'),
+  one('headSquare', 'Square face', 'head', 'head/head-square'),
+  one('headHeart', 'Heart face', 'head', 'head/head-invertedtriangular'),
+  pair('foreheadHeight', 'Forehead height', 'head', 'forehead', 'forehead-scale-vert'),
+  pair('foreheadSlope', 'Forehead slope', 'head', 'forehead', 'forehead-trans', 'backward', 'forward'),
+  pair('jaw', 'Jaw width', 'head', 'chin', 'chin-bones'),
+  pair('chinWidth', 'Chin width', 'head', 'chin', 'chin-width'),
+  pair('chinHeight', 'Chin height', 'head', 'chin', 'chin-height'),
+  pair('chinProminence', 'Chin prominence', 'head', 'chin', 'chin-prominent'),
+  pair('chinCleft', 'Chin cleft', 'head', 'chin', 'chin-cleft'),
+  pairLR('cheekBones', 'Cheekbones', 'head', 'cheek', 'cheek-bones'),
+  pairLR('cheekVolume', 'Cheek volume', 'head', 'cheek', 'cheek-volume'),
+  // eyes & brows
+  pairLR('eyeSize', 'Eye size', 'eyes', 'eyes', 'eye-scale'),
+  pairLR('eyeOpening', 'Eye opening', 'eyes', 'eyes', 'eye-height2'),
+  pairLR('eyeSpacing', 'Eye spacing', 'eyes', 'eyes', 'eye-trans', 'in', 'out'),
+  pairLR('eyeHeight', 'Eye height', 'eyes', 'eyes', 'eye-trans', 'down', 'up'),
+  pairLR('eyeTilt', 'Eye tilt', 'eyes', 'eyes', 'eye-corner1', 'down', 'up'),
+  pairLR('eyeFold', 'Eyelid fold', 'eyes', 'eyes', 'eye-epicanthus', 'in', 'out'),
+  pairLR('eyeBags', 'Eye bags', 'eyes', 'eyes', 'eye-bag'),
+  pair('browHeight', 'Brow height', 'eyes', 'eyebrows', 'eyebrows-trans', 'down', 'up'),
+  pair('browAngle', 'Brow angle', 'eyes', 'eyebrows', 'eyebrows-angle', 'down', 'up'),
+  pair('browDepth', 'Brow ridge', 'eyes', 'eyebrows', 'eyebrows-trans', 'backward', 'forward'),
+  // nose
+  pair('noseWidth', 'Nose width', 'nose', 'nose', 'nose-scale-horiz'),
+  pair('noseLength', 'Nose length', 'nose', 'nose', 'nose-scale-vert'),
+  pair('noseDepth', 'Nose projection', 'nose', 'nose', 'nose-scale-depth'),
+  pair('noseBridge', 'Bridge width', 'nose', 'nose', 'nose-width1'),
+  pair('noseHump', 'Nose hump', 'nose', 'nose', 'nose-hump'),
+  pair('noseTip', 'Tip up/down', 'nose', 'nose', 'nose-point', 'down', 'up'),
+  pair('noseTipWidth', 'Tip width', 'nose', 'nose', 'nose-point-width'),
+  pair('nostrils', 'Nostril width', 'nose', 'nose', 'nose-nostrils-width'),
+  pair('noseFlare', 'Nostril flare', 'nose', 'nose', 'nose-flaring'),
+  // mouth
+  pair('mouthWidth', 'Mouth width', 'mouth', 'mouth', 'mouth-scale-horiz'),
+  pair('mouthHeight', 'Mouth position', 'mouth', 'mouth', 'mouth-trans', 'down', 'up'),
+  pair('upperLip', 'Upper lip', 'mouth', 'mouth', 'mouth-upperlip-volume'),
+  pair('lowerLip', 'Lower lip', 'mouth', 'mouth', 'mouth-lowerlip-volume'),
+  pair('cupidsBow', "Cupid's bow", 'mouth', 'mouth', 'mouth-cupidsbow'),
+  pair('mouthCorners', 'Mouth corners', 'mouth', 'mouth', 'mouth-angles', 'down', 'up'),
+  pair('mouthDepth', 'Mouth depth', 'mouth', 'mouth', 'mouth-scale-depth'),
+  pair('dimples', 'Dimples', 'mouth', 'mouth', 'mouth-dimples', 'in', 'out'),
+  // ears
+  pairLR('earSize', 'Ear size', 'ears', 'ears', 'ear-scale'),
+  pairLR('earAngle', 'Ear angle', 'ears', 'ears', 'ear-rot', 'backward', 'forward'),
+  pairLR('earLobe', 'Ear lobe', 'ears', 'ears', 'ear-lobe'),
+  { id: 'earPointed', label: 'Pointed ears', group: 'ears', neg: [], pos: lr('ears', 'ear-shape-pointed') },
+  // body detail
+  pair('neckWidth', 'Neck width', 'body', 'neck', 'neck-scale-horiz'),
+  pair('neckLength', 'Neck length', 'body', 'neck', 'neck-scale-vert'),
+  pair('shoulders', 'Shoulders', 'body', 'torso', 'measure-shoulder-dist'),
+  pair('chest', 'Chest', 'body', 'torso', 'measure-bust-circ'),
+  pair('waist', 'Waist', 'body', 'torso', 'measure-waist-circ'),
+  pair('hips', 'Hips', 'body', 'torso', 'measure-hips-circ'),
+  pair('vShape', 'V-shape', 'body', 'torso', 'torso-vshape'),
+  pair('belly', 'Belly', 'body', 'stomach', 'stomach-pregnant'),
+  pair('buttocks', 'Buttocks', 'body', 'buttocks', 'buttocks-volume'),
+];
+
+/** Macro sliders (0..1), mirroring MakeHuman's macro modifiers. */
+export const MACRO_SLIDERS = [
+  { id: 'gender', label: 'Gender', min: 'Female', max: 'Male' },
+  { id: 'age', label: 'Age', min: '18', max: '90' },
+  { id: 'muscle', label: 'Muscle', min: 'Soft', max: 'Muscular' },
+  { id: 'weight', label: 'Weight', min: 'Thin', max: 'Heavy' },
+  { id: 'height', label: 'Height', min: 'Short', max: 'Tall' },
+  { id: 'proportions', label: 'Proportions', min: 'Uncommon', max: 'Ideal' },
+  { id: 'cupSize', label: 'Bust', min: 'Small', max: 'Large' },
+  { id: 'firmness', label: 'Firmness', min: 'Low', max: 'High' },
+  { id: 'african', label: 'African', min: '0', max: '1' },
+  { id: 'asian', label: 'Asian', min: '0', max: '1' },
+  { id: 'caucasian', label: 'European', min: '0', max: '1' },
+] as const;
+
+export type MacroId = (typeof MACRO_SLIDERS)[number]['id'];
+
+/**
+ * FACS-style expression units shipped with MPFB, mapped to the closest ARKit
+ * blendshape names so ARKit/MediaPipe face-tracking data can drive them.
+ */
+export const EXPRESSION_UNITS: Record<string, string> = {
+  'eye-left-closure': 'eyeBlinkLeft',
+  'eye-right-closure': 'eyeBlinkRight',
+  'eye-left-opened-up': 'eyeWideLeft',
+  'eye-right-opened-up': 'eyeWideRight',
+  'eye-left-slit': 'eyeSquintLeft',
+  'eye-right-slit': 'eyeSquintRight',
+  'eyebrows-left-down': 'browDownLeft',
+  'eyebrows-right-down': 'browDownRight',
+  'eyebrows-left-extern-up': 'browOuterUpLeft',
+  'eyebrows-right-extern-up': 'browOuterUpRight',
+  'eyebrows-left-inner-up': 'browInnerUpLeft',
+  'eyebrows-right-inner-up': 'browInnerUpRight',
+  'eyebrows-left-up': 'browUpLeft',
+  'eyebrows-right-up': 'browUpRight',
+  'mouth-open': 'jawOpen',
+  'mouth-corner-puller': 'mouthSmile',
+  'mouth-depression': 'mouthFrown',
+  'mouth-depression-retraction': 'mouthLowerDown',
+  'mouth-elevation': 'mouthUpperUp',
+  'mouth-compression': 'mouthPress',
+  'mouth-pursing': 'mouthPucker',
+  'mouth-protusion': 'mouthFunnel',
+  'mouth-retraction': 'mouthStretch',
+  'mouth-upward-retraction': 'mouthDimple',
+  'mouth-eversion': 'mouthRollOut',
+  'mouth-parling': 'mouthClose',
+  'mouth-part-later': 'mouthLeft',
+  'nose-compression': 'noseCompress',
+  'nose-depression': 'noseDepress',
+  'nose-left-elevation': 'noseSneerLeft',
+  'nose-right-elevation': 'noseSneerRight',
+  'nose-left-dilatation': 'nostrilFlareLeft',
+  'nose-right-dilatation': 'nostrilFlareRight',
+  'neck-platysma': 'neckTense',
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './core';
+export * from './human';
+export * from './native';

package/src/native/AvatarCreator.tsx

@@ -0,0 +1,161 @@
+// <AvatarCreator>: full-screen editor driven by EDITOR_SCHEMA. No UI deps beyond RN.
+import React, { useRef, useState } from 'react';
+import { PanResponder, Pressable, ScrollView, StyleSheet, Text, View } from 'react-native';
+import {
+  AvatarConfig, Control, DEFAULT_AVATAR, EDITOR_SCHEMA, encodeAvatar, normalizeConfig, prettyLabel, randomAvatar,
+} from '../core';
+import { AvatarView, AvatarViewHandle } from './AvatarView';
+
+export interface AvatarCreatorProps {
+  initialConfig?: Partial<AvatarConfig> | null;
+  /** Called on Save with the config and its compact code (store either). */
+  onSave?: (config: AvatarConfig, code: string, view: AvatarViewHandle | null) => void;
+  onCancel?: () => void;
+  onChange?: (config: AvatarConfig) => void;
+  accentColor?: string;
+  saveLabel?: string;
+}
+
+export function AvatarCreator({
+  initialConfig, onSave, onCancel, onChange, accentColor = '#1d1d1f', saveLabel = 'Save',
+}: AvatarCreatorProps) {
+  const [config, setConfig] = useState<AvatarConfig>(() => normalizeConfig(initialConfig ?? DEFAULT_AVATAR));
+  const [tab, setTab] = useState(0);
+  const view = useRef<AvatarViewHandle>(null);
+  const section = EDITOR_SCHEMA[tab];
+
+  const update = (next: AvatarConfig) => {
+    setConfig(next);
+    onChange?.(next);
+  };
+  const set = (key: keyof AvatarConfig, value: string | number) => update({ ...config, [key]: value });
+
+  return (
+    <View style={s.root}>
+      <AvatarView ref={view} config={config} framing={section.focus === 'face' ? 'face' : 'body'} style={s.preview} />
+
+      <View style={s.topBar} pointerEvents="box-none">
+        {onCancel ? <Btn label="Cancel" onPress={onCancel} /> : <View />}
+        <Btn label="🎲" onPress={() => update(randomAvatar())} />
+      </View>
+
+      <ScrollView horizontal showsHorizontalScrollIndicator={false} style={s.tabs} contentContainerStyle={s.tabsInner}>
+        {EDITOR_SCHEMA.map((sec, i) => (
+          <Pressable key={sec.id} onPress={() => setTab(i)} style={[s.tab, i === tab && { borderBottomColor: accentColor }]}>
+            <Text style={[s.tabText, i === tab && { color: accentColor, fontWeight: '700' }]}>{sec.label}</Text>
+          </Pressable>
+        ))}
+      </ScrollView>
+
+      <ScrollView style={s.panel} contentContainerStyle={{ paddingBottom: 16 }}>
+        {section.controls.map((ctl) => (
+          <View key={ctl.key} style={s.row}>
+            <Text style={s.label}>{ctl.label}</Text>
+            <ControlInput ctl={ctl} value={config[ctl.key]} onChange={(v) => set(ctl.key, v)} accent={accentColor} />
+          </View>
+        ))}
+      </ScrollView>
+
+      {onSave ? (
+        <Pressable style={[s.save, { backgroundColor: accentColor }]} onPress={() => onSave(config, encodeAvatar(config), view.current)}>
+          <Text style={s.saveText}>{saveLabel}</Text>
+        </Pressable>
+      ) : null}
+    </View>
+  );
+}
+
+function ControlInput({ ctl, value, onChange, accent }: {
+  ctl: Control; value: string | number; onChange: (v: string | number) => void; accent: string;
+}) {
+  if (ctl.type === 'slider') return <Slider value={value as number} onChange={onChange} accent={accent} />;
+  if (ctl.type === 'color') {
+    return (
+      <View style={s.wrap}>
+        {ctl.palette.map((c) => (
+          <Pressable key={c} onPress={() => onChange(c)} hitSlop={4}
+            style={[s.swatch, { backgroundColor: c }, value === c && { borderColor: accent, borderWidth: 3 }]} />
+        ))}
+      </View>
+    );
+  }
+  return (
+    <View style={s.wrap}>
+      {ctl.options.map((o) => (
+        <Pressable key={o} onPress={() => onChange(o)} style={[s.chip, value === o && { backgroundColor: accent, borderColor: accent }]}>
+          <Text style={[s.chipText, value === o && { color: '#fff' }]}>{prettyLabel(o)}</Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+
+/** Dependency-free slider (0..1). Commits at most once per frame while dragging. */
+function Slider({ value, onChange, accent }: { value: number; onChange: (v: number) => void; accent: string }) {
+  const width = useRef(1);
+  const live = useRef({ value, onChange, raf: 0 as number | 0, next: value });
+  live.current.value = value;
+  live.current.onChange = onChange;
+  const emit = (v: number) => {
+    live.current.next = Math.min(1, Math.max(0, v));
+    if (live.current.raf) return;
+    live.current.raf = requestAnimationFrame(() => {
+      live.current.raf = 0;
+      live.current.onChange(live.current.next);
+    });
+  };
+  const pan = useRef((() => {
+    let startX = 0;
+    return PanResponder.create({
+      onStartShouldSetPanResponder: () => true,
+      onMoveShouldSetPanResponder: () => true,
+      onPanResponderTerminationRequest: () => false,
+      onPanResponderGrant: (e) => {
+        startX = e.nativeEvent.locationX;
+        emit(startX / width.current);
+      },
+      onPanResponderMove: (_, g) => emit((startX + g.dx) / width.current),
+    });
+  })()).current;
+  return (
+    <View style={s.sliderHit} onLayout={(e) => (width.current = Math.max(1, e.nativeEvent.layout.width))} {...pan.panHandlers}>
+      <View style={s.track} pointerEvents="none">
+        <View style={[s.fill, { width: `${value * 100}%`, backgroundColor: accent }]} />
+      </View>
+      <View pointerEvents="none" style={[s.thumb, { left: `${value * 100}%`, borderColor: accent }]} />
+    </View>
+  );
+}
+
+function Btn({ label, onPress }: { label: string; onPress: () => void }) {
+  return (
+    <Pressable onPress={onPress} style={s.btn}>
+      <Text style={s.btnText}>{label}</Text>
+    </Pressable>
+  );
+}
+
+const s = StyleSheet.create({
+  root: { flex: 1, backgroundColor: '#fff' },
+  preview: { flex: 1.1, backgroundColor: '#eef1f5' },
+  topBar: { position: 'absolute', top: 12, left: 12, right: 12, flexDirection: 'row', justifyContent: 'space-between' },
+  btn: { backgroundColor: 'rgba(255,255,255,0.9)', borderRadius: 18, paddingHorizontal: 14, paddingVertical: 8 },
+  btnText: { fontSize: 15, color: '#1d1d1f' },
+  tabs: { flexGrow: 0, borderBottomWidth: StyleSheet.hairlineWidth, borderBottomColor: '#ddd' },
+  tabsInner: { paddingHorizontal: 8 },
+  tab: { paddingHorizontal: 12, paddingVertical: 12, borderBottomWidth: 2, borderBottomColor: 'transparent' },
+  tabText: { fontSize: 14, color: '#666' },
+  panel: { flex: 1, paddingHorizontal: 16 },
+  row: { marginTop: 14 },
+  label: { fontSize: 12, color: '#666', marginBottom: 8 },
+  wrap: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
+  chip: { borderWidth: 1, borderColor: '#d5d8dd', borderRadius: 16, paddingHorizontal: 12, paddingVertical: 6 },
+  chipText: { fontSize: 13, color: '#1d1d1f' },
+  swatch: { width: 30, height: 30, borderRadius: 15, borderWidth: 1, borderColor: '#ccc' },
+  sliderHit: { 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, borderRadius: 12, paddingVertical: 14, alignItems: 'center' },
+  saveText: { color: '#fff', fontSize: 16, fontWeight: '600' },
+});

package/src/native/AvatarView.tsx

@@ -0,0 +1,135 @@
+// <AvatarView>: renders an avatar with expo-gl + three (no expo-three, no R3F).
+// Renders on demand only (on change / drag), so an idle avatar costs zero GPU.
+import React, { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from 'react';
+import { PanResponder, StyleProp, View, ViewStyle } from 'react-native';
+import { ExpoWebGLRenderingContext, GLView } from 'expo-gl';
+import { WebGLRenderer } from 'three';
+import { AvatarConfig, AvatarStage, Framing, avatarToGLB, encodeAvatar, normalizeConfig, toBase64 } from '../core';
+
+export interface AvatarViewProps {
+  config: Partial<AvatarConfig>;
+  framing?: Framing;
+  /** Hex background, or null for transparent. */
+  background?: string | null;
+  /** Faceted low-poly shading (default true). */
+  flatShading?: boolean;
+  /** Drag horizontally to spin (default true). */
+  rotatable?: boolean;
+  /** Slowly spin continuously (renders every frame while on). */
+  autoRotate?: boolean;
+  /** Initial yaw in radians. */
+  yaw?: number;
+  style?: StyleProp<ViewStyle>;
+  onReady?: () => void;
+}
+
+export interface AvatarViewHandle {
+  /** Render and save a PNG; resolves to a local file URI. */
+  snapshot(): Promise<string | null>;
+  /** Binary glTF of the current avatar, base64 encoded (write with expo-file-system). */
+  toGLBBase64(): string;
+  setYaw(yaw: number): void;
+}
+
+export const AvatarView = forwardRef<AvatarViewHandle, AvatarViewProps>(function AvatarView(
+  { config, framing = 'body', background = '#eef1f5', flatShading = true, rotatable = true, autoRotate = false, yaw = 0, style, onReady },
+  ref,
+) {
+  const stage = useMemo(() => new AvatarStage(background), []);
+  const gl = useRef<ExpoWebGLRenderingContext | null>(null);
+  const renderer = useRef<WebGLRenderer | null>(null);
+  const pending = useRef(false);
+  const live = useRef({ autoRotate, config, flatShading });
+  live.current = { autoRotate, config, flatShading };
+  const key = encodeAvatar(normalizeConfig(config));
+
+  const requestRender = () => {
+    if (pending.current || !gl.current || !renderer.current) return;
+    pending.current = true;
+    requestAnimationFrame(() => {
+      pending.current = false;
+      if (!gl.current || !renderer.current) return;
+      if (live.current.autoRotate) stage.setYaw(stage.yaw + 0.012);
+      renderer.current.render(stage.scene, stage.camera);
+      gl.current.endFrameEXP();
+      if (live.current.autoRotate) requestRender();
+    });
+  };
+
+  const onContextCreate = (ctx: ExpoWebGLRenderingContext) => {
+    const w = ctx.drawingBufferWidth, h = ctx.drawingBufferHeight;
+    // Minimal canvas shim: three only needs size + no-op listeners when given a context.
+    const canvas = {
+      width: w, height: h, style: {}, clientWidth: w, clientHeight: h,
+      addEventListener: () => {}, removeEventListener: () => {}, getContext: () => ctx,
+    };
+    const r = new WebGLRenderer({ canvas: canvas as any, context: ctx as any, antialias: true, alpha: background === null });
+    r.setPixelRatio(1);
+    r.setSize(w, h, false);
+    if (background === null) r.setClearColor(0x000000, 0);
+    gl.current = ctx;
+    renderer.current = r;
+    stage.setSize(w, h);
+    stage.setFraming(framing);
+    stage.setYaw(yaw);
+    stage.setAvatar(config, { flatShading });
+    requestRender();
+    onReady?.();
+  };
+
+  useEffect(() => {
+    if (!renderer.current) return;
+    stage.setAvatar(live.current.config, { flatShading: live.current.flatShading });
+    requestRender();
+  }, [key, flatShading]);
+
+  useEffect(() => {
+    stage.setFraming(framing);
+    requestRender();
+  }, [framing]);
+
+  useEffect(() => {
+    if (autoRotate) requestRender();
+  }, [autoRotate]);
+
+  useEffect(() => () => {
+    stage.dispose();
+    renderer.current?.dispose();
+    gl.current = null;
+    renderer.current = null;
+  }, []);
+
+  const pan = useMemo(() => {
+    let start = 0;
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 4 && Math.abs(g.dx) > Math.abs(g.dy),
+      onPanResponderGrant: () => { start = stage.yaw; },
+      onPanResponderMove: (_, g) => {
+        stage.setYaw(start + g.dx * 0.012);
+        requestRender();
+      },
+      onPanResponderTerminationRequest: () => false,
+    });
+  }, []);
+
+  useImperativeHandle(ref, () => ({
+    async snapshot() {
+      if (!gl.current || !renderer.current) return null;
+      renderer.current.render(stage.scene, stage.camera);
+      const snap = await GLView.takeSnapshotAsync(gl.current, { format: 'png' });
+      gl.current.endFrameEXP();
+      return typeof snap.uri === 'string' ? snap.uri : null;
+    },
+    toGLBBase64: () => toBase64(avatarToGLB(live.current.config, { flatShading: live.current.flatShading })),
+    setYaw(y: number) {
+      stage.setYaw(y);
+      requestRender();
+    },
+  }));
+
+  return (
+    <View style={[{ overflow: 'hidden' }, style]} {...(rotatable ? pan.panHandlers : null)}>
+      <GLView style={{ flex: 1 }} onContextCreate={onContextCreate} />
+    </View>
+  );
+});

package/src/native/HumanView.tsx

@@ -0,0 +1,149 @@
+// <HumanView>: realistic MakeHuman-based avatar for React Native (expo-gl + three).
+// Renders on demand only; a static avatar costs no GPU after the first frame.
+import React, { forwardRef, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { PanResponder, StyleProp, View, ViewStyle } from 'react-native';
+import { ExpoWebGLRenderingContext, GLView } from 'expo-gl';
+import {
+  ACESFilmicToneMapping, Color, DirectionalLight, HemisphereLight, PerspectiveCamera, Scene, SRGBColorSpace, Vector3, WebGLRenderer,
+} from 'three';
+import { HumanAvatar, HumanConfig, HumanPackage, loadHumanPackage } from '../human/runtime';
+import { expoLoadOptions } from './humanExpo';
+
+/** Load (and disk-cache) the human package once per base URL. */
+const packages = new Map<string, Promise<HumanPackage>>();
+export function useHumanPackage(baseUrl: string) {
+  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, expoLoadOptions);
+      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 };
+}
+
+export interface HumanViewProps {
+  pkg: HumanPackage;
+  config: Partial<HumanConfig>;
+  framing?: 'face' | 'body';
+  /** ARKit-style expression weights, e.g. { mouthSmile: 1 } */
+  expressions?: Record<string, number>;
+  background?: string;
+  rotatable?: boolean;
+  /** '1k' textures for lists/low-end devices, '2k' for the editor. */
+  textureSize?: '1k' | '2k';
+  style?: StyleProp<ViewStyle>;
+  onReady?: (avatar: HumanAvatar) => void;
+}
+
+export interface HumanViewHandle {
+  avatar: HumanAvatar | null;
+  render(): void;
+  snapshot(): Promise<string | null>;
+}
+
+export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function HumanView(
+  { pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '2k', style, onReady }, ref,
+) {
+  const gl = useRef<ExpoWebGLRenderingContext | null>(null);
+  const renderer = useRef<WebGLRenderer | null>(null);
+  const yaw = useRef(0);
+  const pending = useRef(false);
+  const stage = useMemo(() => {
+    const scene = new Scene();
+    scene.background = new Color(background);
+    const key = new DirectionalLight('#fff4e8', 2.2);
+    key.position.set(1.2, 2.2, 2.5);
+    const rim = new DirectionalLight('#dfe8ff', 1.0);
+    rim.position.set(-2, 2, -2);
+    scene.add(key, rim, new HemisphereLight('#ffffff', '#b9a99a', 1.1));
+    const avatar = new HumanAvatar(pkg);
+    avatar.textureSize = textureSize;
+    scene.add(avatar.group);
+    return { scene, camera: new PerspectiveCamera(24, 1, 0.05, 50), avatar };
+  }, [pkg]);
+
+  const draw = () => {
+    if (!gl.current || !renderer.current) return;
+    const { camera, avatar } = stage;
+    const m = avatar.metrics();
+    const target = framing === 'face' ? new Vector3(0, m.headY - 0.08, 0) : new Vector3(0, m.height * 0.52, 0);
+    const h = framing === 'face' ? 0.42 : m.height * 1.12;
+    const dist = h / 2 / Math.tan((camera.fov * Math.PI) / 360) / Math.min(1, camera.aspect * 1.1);
+    camera.position.set(Math.sin(yaw.current) * dist, target.y + dist * 0.03, Math.cos(yaw.current) * dist);
+    camera.lookAt(target);
+    renderer.current.render(stage.scene, camera);
+    gl.current.endFrameEXP();
+  };
+  const requestRender = () => {
+    if (pending.current) return;
+    pending.current = true;
+    requestAnimationFrame(() => { pending.current = false; draw(); });
+  };
+
+  const onContextCreate = (ctx: ExpoWebGLRenderingContext) => {
+    const w = ctx.drawingBufferWidth, h = ctx.drawingBufferHeight;
+    const canvas = { width: w, height: h, style: {}, clientWidth: w, clientHeight: h, addEventListener: () => {}, removeEventListener: () => {}, getContext: () => ctx };
+    const r = new WebGLRenderer({ canvas: canvas as any, context: ctx as any, antialias: true });
+    r.setPixelRatio(1);
+    r.setSize(w, h, false);
+    r.outputColorSpace = SRGBColorSpace;
+    r.toneMapping = ACESFilmicToneMapping;
+    stage.camera.aspect = w / h;
+    stage.camera.updateProjectionMatrix();
+    gl.current = ctx;
+    renderer.current = r;
+    requestRender();
+  };
+
+  const key = JSON.stringify(config);
+  useEffect(() => {
+    let live = true;
+    stage.avatar.setConfig(config).then(() => {
+      if (!live) return;
+      requestRender();
+      onReady?.(stage.avatar);
+    });
+    return () => { live = false; };
+  }, [key, stage]);
+
+  useEffect(() => {
+    for (const [k, v] of Object.entries(expressions ?? {})) stage.avatar.setExpression(k, v);
+    requestRender();
+  }, [JSON.stringify(expressions), framing]);
+
+  useEffect(() => () => { stage.avatar.dispose(); renderer.current?.dispose(); gl.current = null; renderer.current = null; }, [stage]);
+
+  const pan = useMemo(() => {
+    let start = 0;
+    return PanResponder.create({
+      onMoveShouldSetPanResponder: (_, g) => Math.abs(g.dx) > 4 && Math.abs(g.dx) > Math.abs(g.dy),
+      onPanResponderGrant: () => { start = yaw.current; },
+      onPanResponderMove: (_, g) => { yaw.current = start - g.dx * 0.01; requestRender(); },
+      onPanResponderTerminationRequest: () => false,
+    });
+  }, []);
+
+  useImperativeHandle(ref, () => ({
+    avatar: stage.avatar,
+    render: requestRender,
+    async snapshot() {
+      if (!gl.current) return null;
+      draw();
+      const snap = await GLView.takeSnapshotAsync(gl.current, { format: 'png' });
+      return typeof snap.uri === 'string' ? snap.uri : null;
+    },
+  }));
+
+  return (
+    <View style={[{ overflow: 'hidden' }, style]} {...(rotatable ? pan.panHandlers : null)}>
+      <GLView style={{ flex: 1 }} onContextCreate={onContextCreate} />
+    </View>
+  );
+});

package/src/native/humanExpo.ts

@@ -0,0 +1,58 @@
+// React Native (Expo) adapters for the realistic human: a disk-cached fetcher and an
+// expo-gl texture loader. Pass both to loadHumanPackage (useHumanPackage does it for you).
+import * as FileSystem from 'expo-file-system/legacy';
+import { Texture } from 'three';
+import type { HumanTextureLoader, LoadOptions } from '../human/runtime';
+
+const DIR = `${FileSystem.cacheDirectory ?? ''}humanforge/`;
+let dirReady: Promise<void> | null = null;
+
+/** Download once into the cache directory; later sessions load offline. */
+async function cached(url: string): Promise<string> {
+  dirReady ??= FileSystem.makeDirectoryAsync(DIR, { intermediates: true }).catch(() => {});
+  await dirReady;
+  const file = DIR + url.replace(/^https?:\/\//, '').replace(/[^a-zA-Z0-9._-]/g, '_');
+  const info = await FileSystem.getInfoAsync(file);
+  if (!info.exists) {
+    const res = await FileSystem.downloadAsync(url, file);
+    if (res.status !== 200) {
+      await FileSystem.deleteAsync(file, { idempotent: true });
+      throw new Error(`humanforge: ${res.status} for ${url}`);
+    }
+  }
+  return file;
+}
+
+const B64 = new Uint8Array(128);
+'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'.split('').forEach((c, i) => (B64[c.charCodeAt(0)] = i));
+function fromBase64(s: string): ArrayBuffer {
+  const clean = s.replace(/[^A-Za-z0-9+/]/g, '');
+  const out = new Uint8Array(Math.floor((clean.length * 3) / 4));
+  let o = 0;
+  for (let i = 0; i < clean.length; i += 4) {
+    const n = (B64[clean.charCodeAt(i)] << 18) | (B64[clean.charCodeAt(i + 1)] << 12) | (B64[clean.charCodeAt(i + 2)] << 6) | B64[clean.charCodeAt(i + 3)];
+    out[o++] = n >> 16;
+    if (o < out.length) out[o++] = (n >> 8) & 255;
+    if (o < out.length) out[o++] = n & 255;
+  }
+  return out.buffer;
+}
+
+export const expoFetch = async (url: string): Promise<ArrayBuffer> =>
+  fromBase64(await FileSystem.readAsStringAsync(await cached(url), { encoding: FileSystem.EncodingType.Base64 }));
+
+/**
+ * expo-gl decodes images natively when texImage2D receives `{ localUri }`, so we hand three
+ * a "data texture" whose data is the cached file (same trick expo-three uses).
+ */
+export const expoTextureLoader: HumanTextureLoader = async (url, size) => {
+  const localUri = await cached(url);
+  const tex = new Texture();
+  tex.image = { data: { localUri }, width: size, height: size };
+  (tex as any).isDataTexture = true;
+  tex.generateMipmaps = false;
+  tex.needsUpdate = true;
+  return tex;
+};
+
+export const expoLoadOptions: LoadOptions = { fetch: expoFetch, loadTexture: expoTextureLoader };

package/src/native/index.ts

@@ -0,0 +1,7 @@
+export { AvatarView } from './AvatarView';
+export type { AvatarViewHandle, AvatarViewProps } from './AvatarView';
+export { AvatarCreator } from './AvatarCreator';
+export type { AvatarCreatorProps } from './AvatarCreator';
+export { HumanView, useHumanPackage } from './HumanView';
+export type { HumanViewHandle, HumanViewProps } from './HumanView';
+export { expoFetch, expoLoadOptions, expoTextureLoader } from './humanExpo';