humanforge 0.3.0 → 0.5.0

package/src/native/humanExpo.ts

@@ -1,5 +1,9 @@
 // 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).
+// expo-gl texture loader. Pass expoLoadOptions to loadHumanPackage / preloadHumanPackage
+// (useHumanPackage does it for you).
+//
+// expo-gl decodes images with stb_image, which has no WebP support, so these options select the
+// JPEG/PNG mobile texture pack (manifest.mobileTextures, built by `npm run build:mobile`).
 import * as FileSystem from 'expo-file-system/legacy';
 import { Texture } from 'three';
 import type { HumanTextureLoader, LoadOptions } from '../human/runtime';
@@ -7,20 +11,34 @@ 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}`);
-    }
+const inflight = new Map<string, Promise<string>>();
+
+/**
+ * Download once into the cache directory; later sessions load offline. Concurrent requests for
+ * the same URL share one download, and files are written to a temp name and moved into place, so
+ * an interrupted download never leaves a broken file in the cache.
+ */
+export function cached(url: string): Promise<string> {
+  let p = inflight.get(url);
+  if (!p) {
+    p = (async () => {
+      dirReady ??= FileSystem.makeDirectoryAsync(DIR, { intermediates: true }).catch(() => {});
+      await dirReady;
+      const file = DIR + url.replace(/^https?:\/\//, '').replace(/[^a-zA-Z0-9._-]/g, '_');
+      if ((await FileSystem.getInfoAsync(file)).exists) return file;
+      const tmp = `${file}.${Date.now()}.part`;
+      const res = await FileSystem.downloadAsync(url, tmp);
+      if (res.status !== 200) {
+        await FileSystem.deleteAsync(tmp, { idempotent: true });
+        throw new Error(`humanforge: ${res.status} for ${url}`);
+      }
+      await FileSystem.moveAsync({ from: tmp, to: file });
+      return file;
+    })();
+    inflight.set(url, p);
+    p.catch(() => {}).finally(() => inflight.delete(url));
   }
-  return file;
+  return p;
 }
 
 const B64 = new Uint8Array(128);
@@ -43,16 +61,20 @@ export const expoFetch = async (url: string): Promise<ArrayBuffer> =>
 
 /**
  * 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).
+ * a "data texture" whose data is the cached file (same trick expo-three uses). The file must be
+ * JPEG or PNG (stb_image); WebP uploads silently fail and the mesh renders black.
  */
 export const expoTextureLoader: HumanTextureLoader = async (url, size) => {
+  if (/\.webp$/i.test(url)) console.warn(`humanforge: expo-gl can't decode WebP (${url}); build/host the mobile texture pack`);
   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;
+  // all pack textures are power-of-two squares, so mipmaps work and avoid shimmer at bust framing
+  tex.generateMipmaps = true;
   tex.needsUpdate = true;
   return tex;
 };
 
-export const expoLoadOptions: LoadOptions = { fetch: expoFetch, loadTexture: expoTextureLoader };
+/** Options for loadHumanPackage / preloadHumanPackage on Expo: disk cache + JPEG/PNG textures. */
+export const expoLoadOptions: LoadOptions = { fetch: expoFetch, loadTexture: expoTextureLoader, textureFormat: 'mobile' };

package/src/native/index.ts

@@ -2,8 +2,8 @@ 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';
+export { HumanView, preloadHumanPackage, useHumanPackage } from './HumanView';
+export type { HumanViewHandle, HumanViewProps, UseHumanPackageOptions } from './HumanView';
+export { cached as cachedFile, expoFetch, expoLoadOptions, expoTextureLoader } from './humanExpo';
 export { HumanEditor } from './HumanEditor';
 export type { HumanEditorProps } from './HumanEditor';

package/src/web/HumanCanvas.tsx

@@ -5,7 +5,7 @@ import {
   Vector3, WebGLRenderer,
 } from 'three';
 import { RoomEnvironment } from 'three/examples/jsm/environments/RoomEnvironment.js';
-import { HumanAvatar, HumanConfig, HumanPackage } from '../human/runtime';
+import { HumanAvatar, HumanConfig, HumanPackage, TextureTier } from '../human/runtime';
 
 export interface HumanCanvasProps {
   pkg: HumanPackage;
@@ -16,7 +16,8 @@ export interface HumanCanvasProps {
   background?: string;
   /** Drag to turn the avatar. Default true. */
   rotatable?: boolean;
-  textureSize?: '1k' | '2k';
+  /** Texture tier: '512' | '1k' | '2k' (default '2k'). */
+  textureSize?: TextureTier;
   className?: string;
   style?: React.CSSProperties;
   onReady?: (avatar: HumanAvatar) => void;

package/src/web/HumanEditor.tsx

@@ -35,7 +35,7 @@ export function HumanEditor({
   pkg, options, editor: given, value, defaultValue, onChange, onSave, saveLabel = 'Save', selfie = false, randomize = true,
   accentColor = '#1d1d1f', background = '#e9ecf1', className, style,
 }: HumanEditorProps) {
-  const editor = useMemo(() => given ?? createHumanEditor(pkg.manifest, options), [given, pkg, JSON.stringify(options)]);
+  const editor = useMemo(() => given ?? createHumanEditor(pkg, options), [given, pkg, JSON.stringify(options)]);
   const [inner, setInner] = useState<HumanConfig>(() => editor.normalize(defaultValue ?? null));
   const config = value ? editor.normalize(value) : inner;
   const [tab, setTab] = useState(0);
@@ -136,14 +136,27 @@ function Control({ ctl, config, onChange }: { ctl: EditorControl; config: HumanC
     );
   }
   const v = ctl.value(config);
+  if (ctl.display === 'swatch') {
+    return (
+      <div className="hf-block">
+        <span className="hf-label">{ctl.label}</span>
+        <div className="hf-swatches">
+          {ctl.options.map((o) => (
+            <button key={o.id ?? 'none'} aria-label={o.label} title={o.label} className={`hf-swatch ${o.id === v ? 'on' : ''}`}
+              style={{ background: o.preview ? `center/cover url("${o.preview}") ${o.swatch ?? ''}` : o.swatch ?? '#eee' }}
+              onClick={() => onChange(ctl.apply(config, o.id))} />
+          ))}
+        </div>
+      </div>
+    );
+  }
   return (
     <div className="hf-block">
       <span className="hf-label">{ctl.label}</span>
-      <div className="hf-choices">
+      <div className="hf-tiles">
         {ctl.options.map((o) => (
-          <button key={o.id ?? 'none'} className={`hf-choice ${o.id === v ? 'on' : ''}`} onClick={() => onChange(ctl.apply(config, o.id))}>
-            {o.swatch && <i style={{ background: o.swatch }} />}
-            {o.label}
+          <button key={o.id ?? 'none'} aria-label={o.label} title={o.label} className={`hf-tile ${o.id === v ? 'on' : ''}`} onClick={() => onChange(ctl.apply(config, o.id))}>
+            {o.id === null ? <NoneIcon /> : o.preview ? <img src={o.preview} alt="" loading="lazy" draggable={false} /> : <span>{o.label}</span>}
           </button>
         ))}
       </div>
@@ -151,6 +164,14 @@ function Control({ ctl, config, onChange }: { ctl: EditorControl; config: HumanC
   );
 }
 
+function NoneIcon() {
+  return (
+    <svg viewBox="0 0 24 24" width="26" height="26" aria-hidden="true" fill="none" stroke="#9aa0a8" strokeWidth="1.8">
+      <circle cx="12" cy="12" r="9" /><path d="M5.6 18.4 18.4 5.6" />
+    </svg>
+  );
+}
+
 const CSS = `
 .hf-root{--hf-accent:#1d1d1f;container-type:inline-size;height:100%;min-height:480px}
 .hf-editor{display:grid;grid-template-columns:minmax(0,1fr) 360px;height:100%;min-height:480px;font:13px/1.4 system-ui,-apple-system,sans-serif;color:#1d1d1f;background:#fff;border-radius:16px;overflow:hidden}
@@ -174,13 +195,13 @@ const CSS = `
 .hf-label{font-size:12px;color:#666}
 .hf-block{margin:12px 0}
 .hf-block>.hf-label{display:block;margin-bottom:8px;font-weight:600;color:#333}
-.hf-choices{display:grid;grid-template-columns:repeat(auto-fill,minmax(96px,1fr));gap:6px}
-.hf-choice{display:flex;align-items:center;gap:6px;justify-content:center;border:1px solid #e1e3e7;background:#fff;border-radius:10px;padding:9px 8px;font:inherit;font-size:12px;cursor:pointer;text-align:center}
-.hf-choice:hover{border-color:#c5c8ce}
-.hf-choice.on{border-color:var(--hf-accent);box-shadow:inset 0 0 0 1px var(--hf-accent);font-weight:600}
-.hf-choice i{width:12px;height:12px;border-radius:50%;flex:none}
-.hf-swatches{display:flex;flex-wrap:wrap;gap:8px}
-.hf-swatch{width:28px;height:28px;border-radius:50%;border:2px solid #fff;box-shadow:0 0 0 1px #d5d8dd;cursor:pointer;padding:0}
+.hf-tiles{display:grid;grid-template-columns:repeat(auto-fill,minmax(72px,1fr));gap:8px}
+.hf-tile{aspect-ratio:1;display:grid;place-items:center;border:1px solid #e1e3e7;background:#f4f5f7;border-radius:12px;padding:4px;cursor:pointer;overflow:hidden;font:inherit;font-size:11px;color:#555}
+.hf-tile:hover{border-color:#c5c8ce}
+.hf-tile.on{border-color:var(--hf-accent);box-shadow:inset 0 0 0 2px var(--hf-accent);background:#fff}
+.hf-tile img{width:100%;height:100%;object-fit:contain;pointer-events:none}
+.hf-swatches{display:flex;flex-wrap:wrap;gap:10px}
+.hf-swatch{width:34px;height:34px;border-radius:50%;border:2px solid #fff;box-shadow:0 0 0 1px #d5d8dd;cursor:pointer;padding:0}
 .hf-swatch.on{box-shadow:0 0 0 2px var(--hf-accent)}
 .hf-save{margin:12px 16px 16px;border:0;border-radius:12px;padding:12px;background:var(--hf-accent);color:#fff;font:inherit;font-weight:600;cursor:pointer}
 @container (max-width:720px){.hf-editor{grid-template-columns:minmax(0,1fr);grid-template-rows:minmax(260px,52%) minmax(0,1fr)}.hf-panel{border-left:0;border-top:1px solid #eceef1}}