humanforge 0.3.0 → 0.5.0

package/src/human/runtime.ts

@@ -63,6 +63,8 @@ export interface ProxyMeta {
   roughness?: number;
   /** Texture coordinates are in tiles (repeat wrapping). */
   tileable?: boolean;
+  /** Transparent WebP thumbnail, relative to the package root (tools/build-previews.mts). */
+  preview?: string;
 }
 export interface HumanManifest {
   vertexCount: number;
@@ -74,9 +76,23 @@ export interface HumanManifest {
   };
   bones: { name: string; parent: number; head: number[]; tail: number[] }[];
   proxies: ProxyMeta[];
-  skins: { id: string; tags: string[] }[];
+  /** `swatch`: the skin tone as rendered (hex), from tools/build-previews.mts. */
+  skins: { id: string; tags: string[]; swatch?: string }[];
   eyes: string[];
+  /** Iris color and round iris thumbnail per eye color (tools/build-previews.mts). */
+  eyeOptions?: Record<string, { swatch: string; preview: string }>;
   textureSizes: { skin1k: number; skin2k: number; eyes: number };
+  /**
+   * JPEG/PNG copies of every WebP texture for decoders without WebP (expo-gl's stb_image),
+   * from tools/build-mobile-textures.mts. Files: `<baseUrl or dir>/<key>_<tier>.<ext>`.
+   */
+  mobileTextures?: {
+    dir: string;
+    /** Absolute URL of the pack when it is hosted apart from the manifest (e.g. a separate CDN tag). */
+    baseUrl?: string;
+    tiers: Record<TextureTier, number>;
+    files: Record<string, { ext: 'jpg' | 'png'; max: number }>;
+  };
   expressions: Record<string, string>;
 }
 interface Morph { idx: Uint16Array; d: Int16Array; scale: number }
@@ -84,6 +100,13 @@ interface Morph { idx: Uint16Array; d: Int16Array; scale: number }
 /** Loads a texture from a URL. `size` is the known square size (React Native needs it up front). */
 export type HumanTextureLoader = (url: string, size: number) => Promise<Texture>;
 
+/** Texture quality tier: max texture edge 512 / 1024 / 2048 px (smaller sources are never upscaled). */
+export type TextureTier = '512' | '1k' | '2k';
+/** 'webp': the web files. 'mobile': the JPEG/PNG pack (needed by expo-gl, which can't decode WebP). */
+export type TextureFormat = 'webp' | 'mobile';
+const TIER_PX: Record<TextureTier, number> = { '512': 512, '1k': 1024, '2k': 2048 };
+const tierFor = (px: number): TextureTier => (px >= 2048 ? '2k' : px >= 1024 ? '1k' : '512');
+
 export const webTextureLoader: HumanTextureLoader = async (url) => new TextureLoader().loadAsync(url);
 
 export interface HumanPackage {
@@ -96,12 +119,21 @@ export interface HumanPackage {
   fetchBinary: (url: string) => Promise<ArrayBuffer>;
   proxyCache: Map<string, Promise<GlbPrimitive>>;
   textureCache: Map<string, Promise<Texture>>;
+  textureFormat: TextureFormat;
+  /** URL and pixel size of a texture key ('skins/<id>', 'eyes/<id>', 'textures/<name>') at a tier. */
+  resolveTexture(key: string, tier: TextureTier, nativeSize: number): { url: string; size: number };
+  /** Load (once per URL) a texture by key and tier. */
+  getTexture(key: string, tier: TextureTier, nativeSize: number): Promise<Texture>;
 }
 
 export interface LoadOptions {
   loadTexture?: HumanTextureLoader;
   /** Override fetching (e.g. for an offline cache). Must return the raw (still gzipped) bytes. */
   fetch?: (url: string) => Promise<ArrayBuffer>;
+  /** Texture files to use. Default 'webp'; the Expo loaders use 'mobile' (falls back to WebP if the pack is missing). */
+  textureFormat?: TextureFormat;
+  /** Where the mobile pack lives. Default: manifest.mobileTextures.baseUrl, else `<baseUrl>/mobile`. */
+  mobileBaseUrl?: string;
 }
 
 /** Undo build-human's wrapping delta coding + byte planes. */
@@ -152,12 +184,109 @@ export async function loadHumanPackage(baseUrl: string, opts: LoadOptions = {}):
     }
     morphs.set(m.name, { idx, d, scale: m.scale });
   }
+  const loadTexture = opts.loadTexture ?? webTextureLoader;
+  const mobile = manifest.mobileTextures;
+  const textureFormat: TextureFormat = opts.textureFormat === 'mobile' && mobile ? 'mobile' : 'webp';
+  if (opts.textureFormat === 'mobile' && !mobile) console.warn('humanforge: this asset package has no mobile texture pack (npm run build:mobile); using WebP');
+  const mobileBase = (opts.mobileBaseUrl ?? mobile?.baseUrl ?? `${root}/${mobile?.dir ?? 'mobile'}`).replace(/\/$/, '');
+  const textureCache = new Map<string, Promise<Texture>>();
+  const resolveTexture = (key: string, tier: TextureTier, nativeSize: number) => {
+    const entry = textureFormat === 'mobile' ? mobile!.files[key] : undefined;
+    if (entry) {
+      const px = Math.min(TIER_PX[tier], entry.max, nativeSize);
+      return { url: `${mobileBase}/${key}_${tierFor(px)}.${entry.ext}`, size: px };
+    }
+    // WebP: skins come in 1k and 2k; everything else at its native size
+    if (key.startsWith('skins/')) return tier === '2k' ? { url: `${root}/${key}_2k.webp`, size: manifest.textureSizes.skin2k } : { url: `${root}/${key}_1k.webp`, size: manifest.textureSizes.skin1k };
+    return { url: `${root}/${key}.webp`, size: nativeSize };
+  };
+  const getTexture = (key: string, tier: TextureTier, nativeSize: number) => {
+    const { url, size } = resolveTexture(key, tier, nativeSize);
+    let t = textureCache.get(url);
+    if (!t) {
+      t = loadTexture(url, size).then((tex) => {
+        tex.colorSpace = key.endsWith('_n') ? '' : SRGBColorSpace;
+        tex.flipY = false;
+        tex.needsUpdate = true;
+        return tex;
+      });
+      textureCache.set(url, t);
+      t.catch(() => textureCache.delete(url));
+    }
+    return t;
+  };
+  return {
+    baseUrl: root, manifest, base, morphs, body: readGlb(bodyBuf), loadTexture,
+    fetchBinary, proxyCache: new Map(), textureCache, textureFormat, resolveTexture, getTexture,
+  };
+}
+
+/** Texture key of a proxy texture path ('textures/hair-bob02.webp' -> 'textures/hair-bob02'). */
+const keyOf = (file: string) => file.replace(/\.(webp|png|jpe?g)$/, '');
+
+/**
+ * Every file a config needs for its first textured frame (proxy meshes + textures), so apps can
+ * download them ahead of time. Used by preloadHumanPackage.
+ */
+export function humanAssetsFor(pkg: HumanPackage, config: Partial<HumanConfig>, opts: { textureSize?: TextureTier; normalMaps?: boolean } = {}) {
+  const c = { ...DEFAULT_HUMAN, ...config } as HumanConfig;
+  const tier = opts.textureSize ?? '1k';
+  const ids = ['eyes-high-poly', 'teeth-teeth_base', 'tongue-tongue01'];
+  if (c.eyebrows) ids.push(`eyebrows-${c.eyebrows}`);
+  if (c.eyelashes) ids.push(`eyelashes-${c.eyelashes}`);
+  const metaOf = (id: string) => pkg.manifest.proxies.find((p) => `${p.kind}-${p.id}` === id);
+  const hidden = c.clothes.some((id) => metaOf(`clothes-${id}`)?.hidesHair);
+  if (c.hair && !hidden) ids.push(`hair-${c.hair}`);
+  for (const id of c.clothes) ids.push(`clothes-${id}`);
+  const proxies = ids.map(metaOf).filter((p): p is ProxyMeta => !!p);
+  const textures: { key: string; nativeSize: number }[] = [
+    { key: `skins/${c.skin}`, nativeSize: pkg.manifest.textureSizes.skin2k },
+    { key: `eyes/${c.eyes}`, nativeSize: pkg.manifest.textureSizes.eyes },
+  ];
+  for (const p of proxies) {
+    if (p.texture) textures.push({ key: keyOf(p.texture), nativeSize: p.textureSize });
+    if (p.normalTexture && opts.normalMaps !== false) textures.push({ key: keyOf(p.normalTexture), nativeSize: 1024 });
+  }
   return {
-    baseUrl: root, manifest, base, morphs, body: readGlb(bodyBuf), loadTexture: opts.loadTexture ?? webTextureLoader,
-    fetchBinary, proxyCache: new Map(), textureCache: new Map(),
+    meshes: proxies.map((p) => ({ id: `${p.kind}-${p.id}`, url: `${pkg.baseUrl}/${p.file}` })),
+    textures: textures.map((t) => ({ ...t, ...pkg.resolveTexture(t.key, tier, t.nativeSize) })),
   };
 }
 
+export interface PreloadOptions extends LoadOptions {
+  /** The look to warm up (default DEFAULT_HUMAN): its hair, clothes, skin and eyes are downloaded too. */
+  config?: Partial<HumanConfig>;
+  textureSize?: TextureTier;
+  normalMaps?: boolean;
+  onProgress?: (done: number, total: number) => void;
+}
+
+/**
+ * Load the package and download everything the first textured frame of `config` needs. Resolves
+ * when those files are fetched (and, with the Expo loaders, on disk), not just the manifest.
+ */
+export async function preloadHumanPackage(baseUrl: string, opts: PreloadOptions = {}): Promise<HumanPackage> {
+  const pkg = await loadHumanPackage(baseUrl, opts);
+  await warmHumanPackage(pkg, opts);
+  return pkg;
+}
+
+/** Download the meshes and textures for a config into the package caches (see preloadHumanPackage). */
+export async function warmHumanPackage(pkg: HumanPackage, opts: Omit<PreloadOptions, keyof LoadOptions> = {}) {
+  const { meshes, textures } = humanAssetsFor(pkg, opts.config ?? {}, opts);
+  const total = meshes.length + textures.length;
+  let done = 0;
+  const tick = () => opts.onProgress?.(++done, total);
+  await Promise.all([
+    ...meshes.map(async (m) => {
+      let p = pkg.proxyCache.get(m.id);
+      if (!p) { p = pkg.fetchBinary(m.url).then(readGlb); pkg.proxyCache.set(m.id, p); p.catch(() => pkg.proxyCache.delete(m.id)); }
+      await p; tick();
+    }),
+    ...textures.map(async (t) => { await pkg.getTexture(t.key, opts.textureSize ?? '1k', t.nativeSize); tick(); }),
+  ]);
+}
+
 // ---------------------------------------------------------------- shape evaluation
 const clamp01 = (v: number) => Math.min(1, Math.max(0, v));
 
@@ -290,7 +419,12 @@ export class HumanAvatar {
   private exprDeltas: Float32Array[];
   private skinMat: MeshStandardMaterial;
   private version = 0;
-  textureSize: '1k' | '2k' = '2k';
+  /** Texture tier; set before the first setConfig (changing it later reloads textures). */
+  textureSize: TextureTier = '2k';
+  /** Anisotropic filtering for textures (1 = off). Lower is cheaper on phones. */
+  anisotropy = 4;
+  /** Load clothing normal maps. Turn off for lighter mobile materials. */
+  normalMaps = true;
 
   constructor(pkg: HumanPackage) {
     this.pkg = pkg;
@@ -353,8 +487,8 @@ export class HumanAvatar {
       return [slot, await this.loadProxy(id)] as const;
     });
     const sizes = this.pkg.manifest.textureSizes;
-    const skin = this.texture(`skins/${c.skin}_${this.textureSize}.webp`, this.textureSize === '2k' ? sizes.skin2k : sizes.skin1k);
-    const eyes = this.texture(`eyes/${c.eyes}.webp`, sizes.eyes);
+    const skin = this.texture(`skins/${c.skin}`, sizes.skin2k);
+    const eyes = this.texture(`eyes/${c.eyes}`, sizes.eyes);
     const loaded = await Promise.all(loads);
     const [skinTex, eyeTex] = await Promise.all([skin, eyes]);
     if (v !== this.version) return; // a newer setConfig superseded this one
@@ -366,14 +500,17 @@ export class HumanAvatar {
       this.group.add(entry[1].mesh);
       if (entry[1].soft) this.group.add(entry[1].soft);
     }
-    this.skinMat.map = skinTex;
+    // only touch the material when the texture really changed (slider edits keep the same one)
+    if (this.skinMat.map !== skinTex) {
+      if (!this.skinMat.map) this.skinMat.needsUpdate = true; // null -> texture changes the shader
+      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); (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 (slot === 'eyes' && m.map !== eyeTex) { if (!m.map) m.needsUpdate = true; m.map = eyeTex; }
       if (p.meta.kind === 'clothes' && p.meta.tintable) m.color.set(c.garmentColors?.[clothingInfo(p.meta.id).slot] ?? p.meta.color ?? '#ffffff');
     }
     this.reshape();
@@ -381,6 +518,30 @@ export class HumanAvatar {
 
   getConfig(): HumanConfig { return this.config; }
 
+  /**
+   * Re-apply textures after changing textureSize, anisotropy or normalMaps (meshes stay as they
+   * are; already-loaded files come from the cache).
+   */
+  async reloadTextures() {
+    const c = this.config, sizes = this.pkg.manifest.textureSizes;
+    const v = this.version;
+    const [skin, eyes] = await Promise.all([this.texture(`skins/${c.skin}`, sizes.skin2k), this.texture(`eyes/${c.eyes}`, sizes.eyes)]);
+    const maps = await Promise.all([...this.proxies.values()].map(async (p) => [p,
+      p.meta.texture ? await this.texture(keyOf(p.meta.texture), p.meta.textureSize) : null,
+      p.meta.normalTexture && this.normalMaps ? await this.texture(keyOf(p.meta.normalTexture), 1024) : null] as const));
+    if (v !== this.version) return; // a setConfig happened meanwhile and used the new settings
+    this.skinMat.map = skin;
+    for (const [p, map, normal] of maps) {
+      for (const m of [p.mesh.material, p.soft?.material].filter(Boolean) as MeshStandardMaterial[]) {
+        const shaderChange = !!m.normalMap !== !!normal;
+        if (p.meta.tileable) for (const t of [map, normal]) if (t && t.wrapS !== RepeatWrapping) { t.wrapS = t.wrapT = RepeatWrapping; t.needsUpdate = true; }
+        if (p.meta.kind === 'eyes') m.map = eyes; else if (map) m.map = map;
+        m.normalMap = normal;
+        if (shaderChange) m.needsUpdate = true;
+      }
+    }
+  }
+
   /** Expression by ARKit-style name (e.g. 'jawOpen', 'mouthSmile') or MPFB unit name, weight 0..1. */
   setExpression(name: string, weight: number) {
     const unit = this.exprNames.findIndex((u) => u === name || this.alias(u) === name);
@@ -391,20 +552,11 @@ export class HumanAvatar {
   }
   get expressionNames() { return this.exprNames.map((u) => this.alias(u)); }
 
-  private texture(file: string, size: number): Promise<Texture> {
-    const url = `${this.pkg.baseUrl}/${file}`;
-    let t = this.pkg.textureCache.get(url);
-    if (!t) {
-      t = this.pkg.loadTexture(url, size).then((tex) => {
-        tex.colorSpace = file.endsWith('_n.webp') ? '' : SRGBColorSpace;
-        tex.flipY = false;
-        tex.anisotropy = 4;
-        tex.needsUpdate = true;
-        return tex;
-      });
-      this.pkg.textureCache.set(url, t);
-    }
-    return t;
+  private texture(key: string, nativeSize: number): Promise<Texture> {
+    return this.pkg.getTexture(key, this.textureSize, nativeSize).then((tex) => {
+      if (tex.anisotropy !== this.anisotropy) { tex.anisotropy = this.anisotropy; tex.needsUpdate = true; }
+      return tex;
+    });
   }
 
   private async loadProxy(fullId: string): Promise<ProxyInstance | null> {
@@ -417,8 +569,8 @@ export class HumanAvatar {
     }
     const [prim, map, normalMap] = await Promise.all([
       p,
-      meta.texture ? this.texture(meta.texture, meta.textureSize) : null,
-      meta.normalTexture ? this.texture(meta.normalTexture, 1024) : null,
+      meta.texture ? this.texture(keyOf(meta.texture), meta.textureSize) : null,
+      meta.normalTexture && this.normalMaps ? this.texture(keyOf(meta.normalTexture), 1024) : null,
     ]);
     const geo = geometryFrom(prim, '_JOINTS', '_WEIGHTS');
     const refs = asU16(prim.attributes._REFS), refw = toFloat(prim.attributes._REFW), offs = toFloat(prim.attributes._OFFS);

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from './core';
 export * from './human';
 export * from './native';
+// the root entry targets React Native: its preload uses the Expo disk cache and mobile textures
+export { preloadHumanPackage } from './native';

package/src/native/HumanEditor.tsx

@@ -3,7 +3,7 @@
 //
 //   <HumanEditor pkg={pkg} options={{ gender: 'female', exclude: ['ears'] }} onSave={(config, png) => save(config)} />
 import React, { useMemo, useRef, useState } from 'react';
-import { LayoutChangeEvent, PanResponder, Pressable, ScrollView, StyleSheet, Text, View, ViewStyle, StyleProp } from 'react-native';
+import { Image, LayoutChangeEvent, PanResponder, Pressable, ScrollView, StyleSheet, Text, View, ViewStyle, StyleProp } from 'react-native';
 import type { HumanConfig, HumanPackage } from '../human/runtime';
 import { EditorControl, HumanEditorModel as EditorModel, HumanEditorOptions, createHumanEditor } from '../human/editor';
 import { HumanView, HumanViewHandle } from './HumanView';
@@ -32,7 +32,7 @@ export function HumanEditor({
   pkg, options, editor: given, value, defaultValue, onChange, onSave, onCancel, saveLabel = 'Save', randomize = true,
   accentColor = '#1d1d1f', background = '#e9ecf1', style,
 }: HumanEditorProps) {
-  const editor = useMemo(() => given ?? createHumanEditor(pkg.manifest, options), [given, pkg, JSON.stringify(options)]);
+  const editor = useMemo(() => given ?? createHumanEditor(pkg, options), [given, pkg, JSON.stringify(options)]);
   const [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
   const config = value ? editor.normalize(value) : inner;
   const [tab, setTab] = useState(0);
@@ -110,15 +110,31 @@ function Control({ ctl, config, onChange, accent }: { ctl: EditorControl; config
     );
   }
   const v = ctl.value(config);
+  if (ctl.display === 'swatch') {
+    return (
+      <View style={s.block}>
+        <Text style={s.blockLabel}>{ctl.label}</Text>
+        <View style={s.wrap}>
+          {ctl.options.map((o) => (
+            <Pressable key={o.id ?? 'none'} accessibilityLabel={o.label} onPress={() => onChange(ctl.apply(config, o.id))}
+              style={[s.swatch, { backgroundColor: o.swatch ?? '#eee' }, o.id === v && { borderColor: accent }]}>
+              {o.preview ? <Image source={{ uri: o.preview }} style={s.swatchImg} /> : null}
+            </Pressable>
+          ))}
+        </View>
+      </View>
+    );
+  }
   return (
     <View style={s.block}>
       <Text style={s.blockLabel}>{ctl.label}</Text>
       <View style={s.wrap}>
         {ctl.options.map((o) => (
-          <Pressable key={o.id ?? 'none'} onPress={() => onChange(ctl.apply(config, o.id))}
-            style={[s.choice, o.id === v && { borderColor: accent, borderWidth: 2 }]}>
-            {o.swatch ? <View style={[s.dot, { backgroundColor: o.swatch }]} /> : null}
-            <Text style={[s.choiceText, o.id === v && { fontWeight: '700' }]}>{o.label}</Text>
+          <Pressable key={o.id ?? 'none'} accessibilityLabel={o.label} onPress={() => onChange(ctl.apply(config, o.id))}
+            style={[s.tile, o.id === v && { borderColor: accent, borderWidth: 2, backgroundColor: '#fff' }]}>
+            {o.id === null ? <View style={s.none}><View style={s.noneBar} /></View>
+              : o.preview ? <Image source={{ uri: o.preview }} style={s.tileImg} resizeMode="contain" />
+              : <Text style={s.choiceText}>{o.label}</Text>}
           </Pressable>
         ))}
       </View>
@@ -173,10 +189,13 @@ const s = StyleSheet.create({
   block: { marginVertical: 10 },
   blockLabel: { fontSize: 13, fontWeight: '600', color: '#333', marginBottom: 8 },
   wrap: { flexDirection: 'row', flexWrap: 'wrap', gap: 8 },
-  choice: { flexDirection: 'row', alignItems: 'center', gap: 6, borderWidth: 1, borderColor: '#e1e3e7', borderRadius: 10, paddingHorizontal: 12, paddingVertical: 9, minWidth: 64, justifyContent: 'center' },
-  choiceText: { fontSize: 12, color: '#1d1d1f' },
-  dot: { width: 12, height: 12, borderRadius: 6 },
-  swatch: { width: 32, height: 32, borderRadius: 16, borderWidth: 3, borderColor: '#fff', shadowColor: '#000', shadowOpacity: 0.15, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+  tile: { width: 76, height: 76, borderRadius: 12, borderWidth: 1, borderColor: '#e1e3e7', backgroundColor: '#f4f5f7', alignItems: 'center', justifyContent: 'center', overflow: 'hidden', padding: 3 },
+  tileImg: { width: '100%', height: '100%' },
+  none: { width: 26, height: 26, borderRadius: 13, borderWidth: 2, borderColor: '#9aa0a8', alignItems: 'center', justifyContent: 'center' },
+  noneBar: { width: 30, height: 2, backgroundColor: '#9aa0a8', transform: [{ rotate: '-45deg' }] },
+  choiceText: { fontSize: 11, color: '#555', textAlign: 'center' },
+  swatch: { width: 36, height: 36, borderRadius: 18, borderWidth: 3, borderColor: '#fff', overflow: 'hidden', shadowColor: '#000', shadowOpacity: 0.15, shadowRadius: 2, shadowOffset: { width: 0, height: 1 }, elevation: 1 },
+  swatchImg: { width: '100%', height: '100%' },
   slider: { flex: 1, height: 32, justifyContent: 'center' },
   track: { height: 4, borderRadius: 2, backgroundColor: '#e3e5e8', overflow: 'hidden' },
   fill: { height: 4 },

package/src/native/HumanView.tsx

@@ -1,31 +1,71 @@
 // <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 { LayoutChangeEvent, PanResponder, PixelRatio, 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 {
+  HumanAvatar, HumanConfig, HumanPackage, LoadOptions, PreloadOptions, TextureTier, loadHumanPackage, warmHumanPackage,
+} from '../human/runtime';
 import { expoLoadOptions } from './humanExpo';
 
-/** Load (and disk-cache) the human package once per base URL. */
+export interface UseHumanPackageOptions extends Omit<PreloadOptions, keyof LoadOptions | 'onProgress'> {
+  /** Host of the mobile texture pack, if not next to the manifest or in manifest.mobileTextures.baseUrl. */
+  mobileBaseUrl?: string;
+  /** Also download this look's meshes and textures before `ready` (default: true, with DEFAULT_HUMAN). */
+  preload?: boolean;
+}
+
+/**
+ * Preload on Expo: loads the package with the disk cache and JPEG/PNG textures, then downloads
+ * everything `config` needs for its first textured frame. Resolves when those files are on disk.
+ *
+ *   await preloadHumanPackage(ASSETS, { config: savedAvatar, textureSize: '1k' });  // e.g. during splash
+ */
+export function preloadHumanPackage(baseUrl: string, opts: Omit<PreloadOptions, keyof LoadOptions> & { mobileBaseUrl?: string } = {}) {
+  return getPackage(baseUrl, opts.mobileBaseUrl).then(async (pkg) => { await warmHumanPackage(pkg, opts); return pkg; });
+}
+
 const packages = new Map<string, Promise<HumanPackage>>();
-export function useHumanPackage(baseUrl: string) {
+function getPackage(baseUrl: string, mobileBaseUrl?: string) {
+  let p = packages.get(baseUrl);
+  if (!p) {
+    p = loadHumanPackage(baseUrl, { ...expoLoadOptions, mobileBaseUrl });
+    packages.set(baseUrl, p);
+    p.catch(() => packages.delete(baseUrl));
+  }
+  return p;
+}
+
+/**
+ * Load (and disk-cache) the human package once per base URL. `ready` turns true when the first
+ * textured frame can be painted: manifest, base mesh, and (unless `preload: false`) the meshes and
+ * textures of `config`, all on disk. `progress` is 0..1 while preloading.
+ */
+export function useHumanPackage(baseUrl: string, opts: UseHumanPackageOptions = {}) {
   const [pkg, setPkg] = useState<HumanPackage | null>(null);
+  const [ready, setReady] = useState(false);
+  const [progress, setProgress] = useState(0);
   const [error, setError] = useState<Error | null>(null);
+  const key = JSON.stringify([opts.config ?? null, opts.textureSize ?? '1k', opts.normalMaps ?? true, opts.preload ?? true]);
   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));
+    setReady(false);
+    getPackage(baseUrl, opts.mobileBaseUrl)
+      .then(async (p) => {
+        if (!live) return;
+        setPkg(p);
+        if (opts.preload !== false) {
+          await warmHumanPackage(p, { ...opts, onProgress: (d, t) => live && setProgress(d / t) });
+        }
+        if (live) { setProgress(1); setReady(true); }
+      })
+      .catch((e) => live && setError(e));
     return () => { live = false; };
-  }, [baseUrl]);
-  return { pkg, error };
+  }, [baseUrl, key]);
+  return { pkg, ready, progress, error };
 }
 
 export interface HumanViewProps {
@@ -36,9 +76,21 @@ export interface HumanViewProps {
   expressions?: Record<string, number>;
   background?: string;
   rotatable?: boolean;
-  /** '1k' textures for lists/low-end devices, '2k' for the editor. */
-  textureSize?: '1k' | '2k';
+  /**
+   * Texture tier. Default '1k': at face/bust framing on a phone it looks like web '2k'.
+   * '512' for lists and avatars under ~120 pt; '2k' only for full-screen close-ups.
+   */
+  textureSize?: TextureTier;
+  /** Render resolution in pixels per point. Default: the device's (max 3). 2 is a good speed/quality balance. */
+  pixelRatio?: number;
+  /** MSAA. Default true (expo-gl multisampling on iOS, three's antialias elsewhere). */
+  antialias?: boolean;
+  /** Anisotropic texture filtering. Default 2; 1 turns it off. */
+  maxTextureAnisotropy?: number;
+  /** Clothing normal maps. Default true; false for lighter materials on low-end phones. */
+  normalMaps?: boolean;
   style?: StyleProp<ViewStyle>;
+  /** Called once, after the first frame with all textures has been drawn. */
   onReady?: (avatar: HumanAvatar) => void;
 }
 
@@ -49,12 +101,21 @@ export interface HumanViewHandle {
 }
 
 export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function HumanView(
-  { pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '2k', style, onReady }, ref,
+  {
+    pkg, config, framing = 'face', expressions, background = '#e9ecf1', rotatable = true, textureSize = '1k',
+    pixelRatio, antialias = true, maxTextureAnisotropy = 2, normalMaps = true, style, onReady,
+  }, ref,
 ) {
   const gl = useRef<ExpoWebGLRenderingContext | null>(null);
   const renderer = useRef<WebGLRenderer | null>(null);
   const yaw = useRef(0);
   const pending = useRef(false);
+  const textured = useRef(false); // config applied with all textures loaded
+  const readyFired = useRef(false);
+  const readyCb = useRef(onReady);
+  readyCb.current = onReady;
+  const [layout, setLayout] = useState<{ w: number; h: number } | null>(null);
+
   const stage = useMemo(() => {
     const scene = new Scene();
     scene.background = new Color(background);
@@ -65,21 +126,39 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     scene.add(key, rim, new HemisphereLight('#ffffff', '#b9a99a', 1.1));
     const avatar = new HumanAvatar(pkg);
     avatar.textureSize = textureSize;
+    avatar.anisotropy = maxTextureAnisotropy;
+    avatar.normalMaps = normalMaps;
     scene.add(avatar.group);
+    textured.current = false;
+    readyFired.current = false;
     return { scene, camera: new PerspectiveCamera(24, 1, 0.05, 50), avatar };
   }, [pkg]);
 
+  useEffect(() => { (stage.scene.background as Color).set(background); requestRender(); }, [background]);
+
   const draw = () => {
-    if (!gl.current || !renderer.current) return;
+    const ctx = gl.current, r = renderer.current;
+    if (!ctx || !r) return;
     const { camera, avatar } = stage;
+    const w = ctx.drawingBufferWidth, h = ctx.drawingBufferHeight;
+    if (r.domElement.width !== w || r.domElement.height !== h) {
+      r.domElement.width = w; r.domElement.height = h;
+      r.setSize(w, h, false);
+      camera.aspect = w / h;
+      camera.updateProjectionMatrix();
+    }
     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);
+    const vh = framing === 'face' ? 0.42 : m.height * 1.12;
+    const dist = vh / 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();
+    r.render(stage.scene, camera);
+    ctx.endFrameEXP();
+    if (textured.current && !readyFired.current) {
+      readyFired.current = true;
+      readyCb.current?.(avatar);
+    }
   };
   const requestRender = () => {
     if (pending.current) return;
@@ -90,7 +169,7 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
   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 });
+    const r = new WebGLRenderer({ canvas: canvas as any, context: ctx as any, antialias });
     r.setPixelRatio(1);
     r.setSize(w, h, false);
     r.outputColorSpace = SRGBColorSpace;
@@ -102,17 +181,28 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     requestRender();
   };
 
+  // Shape/color changes reuse the cached textures; only a new item or tier loads files.
   const key = JSON.stringify(config);
   useEffect(() => {
     let live = true;
     stage.avatar.setConfig(config).then(() => {
       if (!live) return;
+      textured.current = true;
       requestRender();
-      onReady?.(stage.avatar);
     });
     return () => { live = false; };
   }, [key, stage]);
 
+  // quality knobs that need the textures reapplied
+  useEffect(() => {
+    const a = stage.avatar;
+    if (a.textureSize === textureSize && a.anisotropy === maxTextureAnisotropy && a.normalMaps === normalMaps) return;
+    a.textureSize = textureSize;
+    a.anisotropy = maxTextureAnisotropy;
+    a.normalMaps = normalMaps;
+    a.reloadTextures().then(requestRender);
+  }, [textureSize, maxTextureAnisotropy, normalMaps, stage]);
+
   useEffect(() => {
     for (const [k, v] of Object.entries(expressions ?? {})) stage.avatar.setExpression(k, v);
     requestRender();
@@ -141,9 +231,23 @@ export const HumanView = forwardRef<HumanViewHandle, HumanViewProps>(function Hu
     },
   }));
 
+  // expo-gl sizes its buffer to (view size x device scale). For a lower pixelRatio, render a
+  // smaller GLView and scale it up to fill the box.
+  const device = Math.min(3, PixelRatio.get());
+  const k = pixelRatio && pixelRatio < device ? pixelRatio / device : 1;
+  const onLayout = (e: LayoutChangeEvent) => setLayout({ w: e.nativeEvent.layout.width, h: e.nativeEvent.layout.height });
+  const glStyle: StyleProp<ViewStyle> = k === 1 || !layout
+    ? { flex: 1 }
+    : {
+      position: 'absolute', width: layout.w * k, height: layout.h * k,
+      left: (layout.w - layout.w * k) / 2, top: (layout.h - layout.h * k) / 2, transform: [{ scale: 1 / k }],
+    };
+
   return (
-    <View style={[{ overflow: 'hidden' }, style]} {...(rotatable ? pan.panHandlers : null)}>
-      <GLView style={{ flex: 1 }} onContextCreate={onContextCreate} />
+    <View style={[{ overflow: 'hidden' }, style]} onLayout={onLayout} {...(rotatable ? pan.panHandlers : null)}>
+      {k === 1 || layout ? (
+        <GLView style={glStyle} msaaSamples={antialias ? 4 : 0} onContextCreate={onContextCreate} />
+      ) : null}
     </View>
   );
 });