Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(avatars): render every avatar thumbnail in a natural rest pose instead of a T-pose
nirholasfdc6a8d107f1
diff --git a/api/_lib/pose-runtime.js b/api/_lib/pose-runtime.jsindex c20c1cf1b..347ba986d 100644--- a/api/_lib/pose-runtime.js+++ b/api/_lib/pose-runtime.js@@ -45,3 +45,73 @@ export function poseRuntimeModules() {};return _poseRuntimeModules;}++// ── Thumbnail rest pose ──────────────────────────────────────────────────────+//+// src/thumbnail-pose.js poses an avatar through AnimationManager, which pulls in+// the whole retargeting stack. Rather than hand-list a rewrite per file (the+// pattern above, fine for three modules), walk the module graph from the entry+// and give every src/ file one bare specifier, `tws/<path relative to src>`, so+// a new import in any of them ships automatically instead of 404ing the page.++const THUMBNAIL_POSE_ENTRY = 'thumbnail-pose.js';+export const THUMBNAIL_POSE_SPECIFIER = `tws/${THUMBNAIL_POSE_ENTRY}`;++// Static `import … from './x.js'`, `export … from '../y.js'` and bare+// `import './z.js'`. Only relative specifiers: 'three' and its addons resolve+// through the page's own import map.+const RELATIVE_IMPORT_RE = /(\bfrom\s*|\bimport\s*)(['"])(\.{1,2}\/[^'"]+)\2/g;++function srcPath(fromFile, spec) {+ const url = new URL(spec, new URL(fromFile, SRC_DIR));+ return url.href.slice(SRC_DIR.href.length);+}++let _thumbnailPoseModules = null;++/**+ * Import-map entries for src/thumbnail-pose.js and everything it imports, as+ * data: URL modules. Built once per container.+ *+ * @returns {Record<string,string>} specifier → data: URL+ */+export function thumbnailPoseModules() {+ if (_thumbnailPoseModules) return _thumbnailPoseModules;+ const modules = {};+ const pending = [THUMBNAIL_POSE_ENTRY];+ const seen = new Set();+ while (pending.length) {+ const file = pending.shift();+ if (seen.has(file)) continue;+ seen.add(file);+ const source = readFileSync(new URL(file, SRC_DIR), 'utf8');+ const code = source.replace(RELATIVE_IMPORT_RE, (_m, lead, quote, spec) => {+ const target = srcPath(file, spec);+ pending.push(target);+ return `${lead}${quote}tws/${target}${quote}`;+ });+ if (/\bimport\s*\(\s*['"]\.{1,2}\//.test(code)) {+ throw new Error(`pose-runtime: ${file} has a relative dynamic import a render page cannot resolve`);+ }+ modules[`tws/${file}`] = 'data:text/javascript;base64,' + Buffer.from(code, 'utf8').toString('base64');+ }+ _thumbnailPoseModules = modules;+ return modules;+}++let _thumbnailPoseClip = null;++/**+ * The frozen rest pose every server-rendered thumbnail is posed with: the+ * library clip named by THUMBNAIL_POSE_CLIP, read from the motion library baked+ * into the image (public/animations/clips/) and sampled once per container.+ *+ * @returns {Promise<object>} AnimationClip JSON (see sampleClipPose)+ */+export async function thumbnailPoseClip() {+ if (_thumbnailPoseClip) return _thumbnailPoseClip;+ const { sampleClipPose, THUMBNAIL_POSE_CLIP, THUMBNAIL_POSE_TIME } = await import('../../src/thumbnail-pose.js');+ const file = new URL(`../../public/animations/clips/${THUMBNAIL_POSE_CLIP}.json`, import.meta.url);+ _thumbnailPoseClip = sampleClipPose(JSON.parse(readFileSync(file, 'utf8')), THUMBNAIL_POSE_TIME);+ return _thumbnailPoseClip;+}diff --git a/api/_lib/render-cpu.js b/api/_lib/render-cpu.jsindex 9bdc28bb2..d48743e36 100644--- a/api/_lib/render-cpu.js+++ b/api/_lib/render-cpu.js@@ -16,6 +16,7 @@import { AvatarModel, renderFrame, renderFrames, encodePng, encodeApng, parseClipJson } from '@three-ws/render';import { fetchModel } from './fetch-model.js';+import { thumbnailPoseClip } from './pose-runtime.js';// Framing constants shared with the chromium lane so a CPU render and a// browser render of the same avatar compose identically.@@ -53,6 +54,41 @@ function cachePut(key, model) {}}+// A cached model is shared by every request for the same GLB, and posing it is+// a mutation: a still poses the skeleton, renders, then puts it back, while an+// animated render plays a clip across a frame loop. Interleaving two of those on+// one model would render one request's pose in the other's frame, so each+// render takes the model for its whole duration.+const _modelQueues = new WeakMap();++function withModel(model, work) {+ const previous = _modelQueues.get(model) || Promise.resolve();+ const run = previous.then(work);+ _modelQueues.set(model, run.catch(() => {}));+ return run;+}++/**+ * Stand a cached model in the thumbnail rest pose (src/thumbnail-pose.js) and+ * frame it around that pose. Returns the undo, which puts both the skeleton and+ * the bind-pose framing back, since the model outlives this render in the cache.+ */+async function standInRestPose(model) {+ const { applyThumbnailPose } = await import('../../src/thumbnail-pose.js');+ const bindBounds = model.bounds;+ const result = await applyThumbnailPose(model.scene, await thumbnailPoseClip());+ if (result.posed) model.updateBounds();+ return {+ posed: result.posed,+ mode: result.mode,+ restore() {+ result.restore();+ model.scene.updateMatrixWorld(true);+ model.bounds = bindBounds;+ },+ };+}+/** Drop every cached model. Exported for tests and for memory-pressure handlers. */export function clearModelCache() {_models.clear();@@ -144,6 +180,11 @@ async function ensureClip(model, clipJson) {* @param {string} [opts.animationUrl] GLB of clips to retarget onto the rig* @param {string|number} [opts.clip] clip to pose, by name or index* @param {number} [opts.time=0] seconds into the clip+ * @param {'rest'|'bind'} [opts.pose='rest'] with no clip, 'rest' stands a+ * humanoid in the thumbnail rest pose (never a T-pose); 'bind' renders the+ * skeleton exactly as authored. Non-humanoid models render as authored either way.+ * @param {(r:{posed:boolean,mode:string}) => void} [opts.onPose] told how the+ * still was posed, so a caller can tell a posed humanoid from a prop* @returns {Promise<Buffer>} PNG buffer*/export async function renderGlbToPngCpu({@@ -162,17 +203,14 @@ export async function renderGlbToPngCpu({clip = null,clipJson = null,time = 0,+ pose = 'rest',+ onPose = null,} = {}) {if (!glbUrl || typeof glbUrl !== 'string') {throw Object.assign(new Error('glbUrl required'), { status: 400, code: 'invalid_args' });}const model = await loadCached(glbUrl, { maxBytes, animationUrl });- const posed = clipJson ? await ensureClip(model, clipJson) : clip;- if (posed !== null && posed !== undefined) {- model.play(posed);- model.setTime(time);- }- const frame = renderFrame(model, {+ const frameOptions = {width,height,supersample,@@ -182,8 +220,26 @@ export async function renderGlbToPngCpu({pitch,margin: FRAME_MARGIN,background: backdropToBackground(background, backdrop),+ };+ return withModel(model, async () => {+ const posed = clipJson ? await ensureClip(model, clipJson) : clip;+ if (posed !== null && posed !== undefined) {+ model.play(posed);+ model.setTime(time);+ return encodePng(renderFrame(model, frameOptions));+ }+ // No clip asked for: this is a poster. Drop whatever clip an earlier+ // animated render left on the cached model, then stand it at rest.+ model.play(null);+ model.setTime(0);+ const rest = pose === 'bind' ? null : await standInRestPose(model);+ try {+ onPose?.({ posed: Boolean(rest?.posed), mode: rest ? rest.mode : 'bind' });+ return encodePng(renderFrame(model, frameOptions));+ } finally {+ rest?.restore();+ }});- return encodePng(frame);}/**@@ -217,24 +273,26 @@ export async function renderGlbToApngCpu({throw Object.assign(new Error('glbUrl required'), { status: 400, code: 'invalid_args' });}const model = await loadCached(glbUrl, { maxBytes, animationUrl });- const playable = clipJson ? await ensureClip(model, clipJson) : clip;- const rendered = await renderFrames(model, {- width,- height,- supersample,- preset,- focus,- yaw,- pitch,- margin: FRAME_MARGIN,- background: backdropToBackground(background, backdrop),- frames,- fps,- startTime,- // A rig that cannot take the clip still animates: the turntable carries- // the loop, so the answer is a moving avatar rather than an error.- spin: playable ? spin : Math.max(spin, 360),- clip: playable,+ return withModel(model, async () => {+ const playable = clipJson ? await ensureClip(model, clipJson) : clip;+ const rendered = await renderFrames(model, {+ width,+ height,+ supersample,+ preset,+ focus,+ yaw,+ pitch,+ margin: FRAME_MARGIN,+ background: backdropToBackground(background, backdrop),+ frames,+ fps,+ startTime,+ // A rig that cannot take the clip still animates: the turntable carries+ // the loop, so the answer is a moving avatar rather than an error.+ spin: playable ? spin : Math.max(spin, 360),+ clip: playable,+ });+ return encodeApng(rendered, { fps });});- return encodeApng(rendered, { fps });}diff --git a/api/_lib/render-glb.js b/api/_lib/render-glb.jsindex 6955577f1..b478c9a19 100644--- a/api/_lib/render-glb.js+++ b/api/_lib/render-glb.js@@ -16,6 +16,7 @@ import { env } from './env.js';import { fetchModel } from './fetch-model.js';import { scriptJson, safeCssColor } from './render-safe.js';import { DEFAULT_THREE_BASE, resolveThreeCdn, THREE_VERSION, threeImportMap } from './three-cdn.js';+import { thumbnailPoseClip, thumbnailPoseModules, THUMBNAIL_POSE_SPECIFIER } from './pose-runtime.js';// Cap on GLB bytes pulled into the renderer. Anything larger risks OOM /// blowing the render budget; callers may tighten this via `maxBytes`.@@ -33,8 +34,10 @@ const DEFAULT_CHROMIUM_PACK =const CHROMIUM_PACK = env.CHROMIUM_PACK_URL || DEFAULT_CHROMIUM_PACK;// Poster composition. A 26° yaw reads as a natural 3/4 portrait without hiding-// the front of the model; 1.22 leaves enough margin that a T-pose's fingertips-// stay inside even after the yaw shrinks the projected width.+// the front of the model; 1.22 leaves enough margin that a wide silhouette (a+// prop, or a rig that keeps its authored stance) stays inside even after the+// yaw shrinks the projected width. Humanoids are stood in the thumbnail rest+// pose first (src/thumbnail-pose.js), so their arms are down when framed.const CAMERA_YAW_DEG = 26;const FRAME_MARGIN = 1.22;@@ -64,6 +67,24 @@ async function getBrowser() {_browserPromise = null; // dead or failed — relaunch below}_browserPromise = (async () => {+ // A workstation already has a chromium (the one Playwright installs for+ // the test suite). Same env var and contract as render-clip.js: unset in+ // production, where the serverless pack below stays the deployed path, and+ // set locally to exercise this lane without downloading that pack.+ const local = process.env.CHROMIUM_EXECUTABLE_PATH;+ if (local) {+ const { default: puppeteer } = await import('puppeteer-core');+ const browser = await puppeteer.launch({+ args: ['--no-sandbox', '--enable-unsafe-swiftshader', '--disable-dev-shm-usage'],+ defaultViewport: { width: 1200, height: 630, deviceScaleFactor: 1 },+ executablePath: local,+ headless: true,+ });+ browser.on('disconnected', () => {+ if (_browserPromise) _browserPromise = null;+ });+ return browser;+ }const [{ default: puppeteer }, { default: chromium }] = await Promise.all([import('puppeteer-core'),import('@sparticuz/chromium-min'),@@ -142,7 +163,7 @@ function releaseRenderSlot() {// extra static assets. three.js + GLTFLoader load from whichever CDN// resolveThreeCdn() found alive, pinned to THREE_VERSION.// window.__renderDone signals readiness to puppeteer.-function viewerHtml({ glbBase64, width, height, background, backdrop, threeBase = DEFAULT_THREE_BASE }) {+function viewerHtml({ glbBase64, width, height, background, backdrop, poseClip = null, threeBase = DEFAULT_THREE_BASE }) {// A gradient backdrop renders as page CSS behind a transparent canvas: the// screenshot composites the two, so the scene itself stays background-free.// `background` reaches here straight from a public handler, and both slots@@ -157,13 +178,19 @@ function viewerHtml({ glbBase64, width, height, background, backdrop, threeBaseconst bodyBg = useGradient? `radial-gradient(ellipse 90% 70% at 50% 38%, ${inner}, ${outer})`: 'transparent';+ // The posing stack (src/thumbnail-pose.js and the AnimationManager it drives)+ // rides into the page as data: URL modules beside three.js, so the browser+ // lane poses with exactly the code the CPU lane and the live viewer run.+ const importMap = poseClip+ ? { ...threeImportMap(threeBase), ...thumbnailPoseModules() }+ : threeImportMap(threeBase);return `<!doctype html><html><head><meta charset="utf-8" /><style>html,body{margin:0;padding:0;background:${bodyBg};overflow:hidden}</style></head><body><canvas id="c" width="${width}" height="${height}" style="display:block;width:${width}px;height:${height}px"></canvas><script>window.__GLB_B64=${scriptJson(glbBase64)};</script>-<script type="importmap">{ "imports": ${scriptJson(threeImportMap(threeBase))} }</script>+<script type="importmap">{ "imports": ${scriptJson(importMap)} }</script><script type="module">import * as THREE from 'three';import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';@@ -174,6 +201,8 @@ import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';window.__renderDone = false;window.__renderError = null;+window.__poseResult = null;+const POSE_CLIP = ${poseClip ? scriptJson(poseClip) : 'null'};const canvas = document.getElementById('c');const renderer = new THREE.WebGLRenderer({ canvas, antialias: true, alpha: true, preserveDrawingBuffer: true });@@ -220,18 +249,37 @@ loader.setDRACOLoader(dracoLoader);loader.setKTX2Loader(ktx2Loader);loader.setMeshoptDecoder(MeshoptDecoder);+// Stand a humanoid in the thumbnail rest pose before framing it. Loaded on+// demand so a posing fault costs the pose, never the poster: the model then+// renders as authored and the fault is reported back with the result.+async function standAtRest(root) {+ if (!POSE_CLIP) return { posed: false, mode: 'bind' };+ try {+ const { applyThumbnailPose } = await import(${scriptJson(THUMBNAIL_POSE_SPECIFIER)});+ const { posed, mode } = await applyThumbnailPose(root, POSE_CLIP);+ return { posed, mode };+ } catch (err) {+ return { posed: false, mode: 'pose-error', error: String(err?.message || err) };+ }+}+// The GLB bytes are fetched server-side through the SSRF-pinned fetchModel// path and embedded here as base64, so chromium never makes a network// request for the user-supplied URL (no DNS-rebinding / redirect SSRF).-function onLoaded(gltf) {+async function onLoaded(gltf) {try {const root = gltf.scene;scene.add(root);+ window.__poseResult = await standAtRest(root);+ // Box3 measures a SkinnedMesh through its bone matrices, so bring them up+ // to the pose being rendered before framing.+ root.updateMatrixWorld(true);+ root.traverse((o) => { if (o.isSkinnedMesh && o.skeleton) o.skeleton.update(); });// Frame the model: compute bounds, center it, position camera so it// fills the frame with a small margin. The camera sits at a gentle 3/4- // yaw instead of dead-on: a straight frontal shot flattens T-posed- // avatars into identical paper cutouts, while the quarter turn shows- // depth and silhouette. Distance honors both fov axes so tight margins+ // yaw instead of dead-on: a straight frontal shot flattens avatars into+ // identical paper cutouts, while the quarter turn shows depth and+ // silhouette. Distance honors both fov axes so tight margins// never crop on non-square frames.const box = new THREE.Box3().setFromObject(root);const size = new THREE.Vector3(); box.getSize(size);@@ -284,6 +332,11 @@ function onLoaded(gltf) {* Callers see one function and one PNG either way. Set RENDER_CPU_LANE=off to* pin every render back onto chromium without a deploy.*+ * Both lanes stand a humanoid in the thumbnail rest pose before framing it+ * (src/thumbnail-pose.js), so a poster never shows a bind-pose T-pose. Pass+ * `pose: 'bind'` for the skeleton exactly as authored, and `onPose` to learn+ * whether the model was posed or rendered as authored (a prop, a creature).+ ** @param {object} opts same shape as renderGlbToPngBrowser* @returns {Promise<Buffer>} PNG buffer*/@@ -321,9 +374,14 @@ export async function renderGlbToPng(opts = {}) {* @param {{inner: string, outer: string}} [opts.backdrop] - radial-gradient* backdrop (center → edge). Takes precedence over `background`; used by the* thumbnail pipeline to give every avatar its own tinted stage.+ * @param {'rest'|'bind'} [opts.pose='rest'] - 'rest' stands a humanoid in the+ * thumbnail rest pose (src/thumbnail-pose.js); 'bind' renders the skeleton as+ * authored. Non-humanoid models render as authored either way.+ * @param {(r:{posed:boolean,mode:string}) => void} [opts.onPose] - told how the+ * model was posed* @returns {Promise<Buffer>} PNG buffer*/-export async function renderGlbToPngBrowser({ glbUrl, width = 1200, height = 630, background = '#0a0a0a', backdrop = null, maxBytes = DEFAULT_MAX_GLB_BYTES } = {}) {+export async function renderGlbToPngBrowser({ glbUrl, width = 1200, height = 630, background = '#0a0a0a', backdrop = null, maxBytes = DEFAULT_MAX_GLB_BYTES, pose = 'rest', onPose = null } = {}) {if (!glbUrl || typeof glbUrl !== 'string') {throw Object.assign(new Error('glbUrl required'), { status: 400, code: 'invalid_args' });}@@ -341,10 +399,11 @@ export async function renderGlbToPngBrowser({ glbUrl, width = 1200, height = 630code: err?.code || 'glb_fetch_failed',});}+ const poseClip = pose === 'bind' ? null : await thumbnailPoseClip();await acquireRenderSlot();try {try {- return await renderOnce({ glbBase64, width, height, background, backdrop });+ return await renderOnce({ glbBase64, width, height, background, backdrop, poseClip, onPose });} catch (err) {// The shared browser can die mid-render (an OOM-reaped chromium takes// every in-flight page with it). That says nothing about this GLB: the@@ -352,7 +411,7 @@ export async function renderGlbToPngBrowser({ glbUrl, width = 1200, height = 630// a freshly launched browser instead of surfacing an infra blip as a// render failure.if (!isBrowserInfrastructureError(err)) throw err;- return await renderOnce({ glbBase64, width, height, background, backdrop });+ return await renderOnce({ glbBase64, width, height, background, backdrop, poseClip, onPose });}} finally {releaseRenderSlot();@@ -361,7 +420,7 @@ export async function renderGlbToPngBrowser({ glbUrl, width = 1200, height = 630// One page lifecycle on the shared browser: boot page, load the inline viewer,// wait for the first clean frame, screenshot.-async function renderOnce({ glbBase64, width, height, background, backdrop }) {+async function renderOnce({ glbBase64, width, height, background, backdrop, poseClip, onPose }) {const browser = await getBrowser();const page = await browser.newPage();try {@@ -370,7 +429,7 @@ async function renderOnce({ glbBase64, width, height, background, backdrop }) {// unpkg outage would otherwise hang the module import until the// watchdog below fires and every poster comes back blank.const { base: threeBase } = await resolveThreeCdn(THREE_VERSION);- const html = viewerHtml({ glbBase64, width, height, background, backdrop, threeBase });+ const html = viewerHtml({ glbBase64, width, height, background, backdrop, poseClip, threeBase });// data: URL avoids needing a network fetch for the bootstrap page itself.// importmap dependencies (three, GLTFLoader) still come from the CDN.await page.setContent(html, { waitUntil: 'domcontentloaded' });@@ -382,6 +441,9 @@ async function renderOnce({ glbBase64, width, height, background, backdrop }) {if (err) {throw Object.assign(new Error(`render failed: ${err}`), { status: 502, code: 'render_failed' });}+ const poseResult = (await page.evaluate(() => window.__poseResult)) || { posed: false, mode: 'bind' };+ if (poseResult.mode === 'pose-error') console.warn('[render] chromium lane could not pose the model:', poseResult.error);+ onPose?.({ posed: Boolean(poseResult.posed), mode: poseResult.mode });return await page.screenshot({type: 'png',omitBackground: background === 'transparent',diff --git a/api/render/glb.js b/api/render/glb.jsindex 9128f8886..7b1202255 100644--- a/api/render/glb.js+++ b/api/render/glb.js@@ -7,9 +7,15 @@// glbUrl: "https://example.com/model.glb", // required, http(s)// width: 1024, // default 1024, max 2048// height: 1024, // default 1024, max 2048-// background: "#0a0a0a" | "transparent" // default #0a0a0a+// background: "#0a0a0a" | "transparent", // default #0a0a0a+// pose: "rest" | "bind" // default rest// }//+// `pose: "rest"` stands a humanoid in the thumbnail rest pose (arms down,+// src/thumbnail-pose.js) instead of its raw bind pose; `"bind"` renders the+// skeleton exactly as authored. Non-humanoid models render as authored either+// way. The x-render-pose response header says which one the PNG shows.+//// GET /api/render/glb?glbUrl=…&width=…&height=…&background=… — the same// render addressable by URL, for consumers that can only follow a link:// og:image / twitter:image unfurls (the AR launch page points its share@@ -60,6 +66,7 @@ export default wrap(async function handler(req, res) {width: q.get('width'),height: q.get('height'),background: q.get('background') || undefined,+ pose: q.get('pose') || undefined,};} else {try {@@ -97,9 +104,25 @@ export default wrap(async function handler(req, res) {}}+ const pose = body.pose === undefined || body.pose === null || body.pose === '' ? 'rest' : body.pose;+ if (pose !== 'rest' && pose !== 'bind') {+ return error(res, 400, 'bad_request', 'pose must be "rest" or "bind"');+ }+let png;+ let posed = { posed: false, mode: pose };try {- png = await renderGlbToPng({ glbUrl, width, height, background, maxBytes: MAX_GLB_BYTES });+ png = await renderGlbToPng({+ glbUrl,+ width,+ height,+ background,+ pose,+ maxBytes: MAX_GLB_BYTES,+ onPose: (r) => {+ posed = r;+ },+ });} catch (err) {const status = err?.status || 502;return error(res, status, err?.code || 'render_failed', err?.message || 'render failed');@@ -112,5 +135,6 @@ export default wrap(async function handler(req, res) {res.setHeader('x-render-width', String(width));res.setHeader('x-render-height', String(height));res.setHeader('x-render-background', background);+ res.setHeader('x-render-pose', posed.posed ? 'rest' : posed.mode === 'bind' ? 'bind' : 'authored');res.end(png);});diff --git a/data/changelog.json b/data/changelog.jsonindex 74d5c65c0..383d04958 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,13 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-01",+ "title": "Avatar pictures show a natural standing pose instead of a T-pose",+ "summary": "The small pictures of avatars around the site, on Spotlight cards, in the Monitor fleet list, on Characters and on the Rankings board, were drawn with every avatar standing arms out in a stiff T. Avatar pictures are now drawn with the avatar standing naturally, arms relaxed at its sides, using the same posing the live 3D viewer uses, and that works for every skeleton style the viewer already understands. Props, vehicles and creatures are drawn exactly as they were made. Avatar pictures also keep their colored backdrop and their real textures again, where some had come out on plain black with bare white materials. Every avatar picture drawn from now on uses the new pose, and the older pictures can now be redrawn in place.",+ "tags": ["fix"],+ "link": "/spotlight"+ },{"date": "2026-10-01","title": "Avatars no longer open in a T-pose, and Spotlight shows one avatar instead of two",diff --git a/docs/api-reference.md b/docs/api-reference.mdindex 0fbfe4b93..04a3abeba 100644--- a/docs/api-reference.md+++ b/docs/api-reference.md@@ -1900,8 +1900,8 @@ below).### Model renderer — `GET|POST /api/render/glb````-GET /api/render/glb?glbUrl=<url>&width=1200&height=630&background=%230a0a0a-POST /api/render/glb { "glbUrl": "...", "width": 1024, "height": 1024, "background": "#0a0a0a" }+GET /api/render/glb?glbUrl=<url>&width=1200&height=630&background=%230a0a0a&pose=rest+POST /api/render/glb { "glbUrl": "...", "width": 1024, "height": 1024, "background": "#0a0a0a", "pose": "rest" }```Public renderer: any public GLB URL in, a PNG out, the same pipeline the OG@@ -1919,6 +1919,15 @@ browser boots; only public http(s) sources are fetched (SSRF-guarded);Anything else is `400 bad_request`: the value is composited into the renderpage, so it is validated rather than escaped.+`pose` is `rest` (the default) or `bind`. With `rest`, a humanoid the platform's+bone canonicalizer recognises (Mixamo, VRoid, Unreal, Blender and the rest of+the naming conventions in `src/glb-canonicalize.js`) is stood in a natural standing+pose with its arms at its sides before the render, instead of its raw T-pose or+A-pose; a rig authored with its arms already down, and any non-humanoid model,+renders as authored. `bind` skips posing. The `x-render-pose` response header+reports what the image shows: `rest`, `authored` or `bind`. See+[Avatar thumbnails](./avatar-thumbnails.md#the-rest-pose).+### Posed avatar renderer: `GET|POST /api/render/avatar-clip````diff --git a/docs/avatar-thumbnails.md b/docs/avatar-thumbnails.mdindex ec5fb85e3..114e5364a 100644--- a/docs/avatar-thumbnails.md+++ b/docs/avatar-thumbnails.md@@ -87,8 +87,12 @@ via `adoptForgePreviews()` in the backfill.### 2. Client capture (`POST /api/avatars/thumbnail`)-The browser captures the live viewer's canvas and uploads a PNG. Stored at-`thumb/<avatarId>.png` with `Content-Type: image/png`. Owner or admin only.+The browser renders a PNG and uploads it. Stored at `thumb/<avatarId>.png` with+`Content-Type: image/png`. Owner or admin only. The account save flow+(`src/account.js`) and the `/app` agent editor (`src/app.js`) render that poster+offscreen with `glbFileToThumbnail()` in+[`src/erc8004/thumbnail.js`](../src/erc8004/thumbnail.js), which poses the+avatar exactly like the server does (see [The rest pose](#the-rest-pose)).### 3. Server render (CPU rasterizer, chromium failover)@@ -109,6 +113,84 @@ always runs in bounded batches.All of this lives in [`api/_lib/avatar-thumbs.js`](../api/_lib/avatar-thumbs.js),the single owner of the invariant above.+## The rest pose++A thumbnail never shows an avatar in its raw bind pose (a T-pose or A-pose with+the arms straight out). Every renderer that turns a GLB into a picture runs+[`src/thumbnail-pose.js`](../src/thumbnail-pose.js) before framing the model:+the CPU rasterizer (`api/_lib/render-cpu.js`), the chromium failover+(`api/_lib/render-glb.js`, which ships the module into its render page as+`data:` URL modules built by `thumbnailPoseModules()` in+[`api/_lib/pose-runtime.js`](../api/_lib/pose-runtime.js)), and the browser's+offscreen capture. That covers the OG card (`/api/avatar/:id/og`), the backfill+and x402 regeneration crons, forge previews, and `/api/render/glb`.++How it poses, in order:++1. **Not a humanoid** (no skin, or fewer canonical bones than+ `AnimationManager.supportsCanonicalClips()` accepts): left as authored. Props,+ vehicles and creatures render exactly as before.+2. **Arms already hanging** in the bind pose (`armsAlreadyHanging()`): left as+ authored. Reposing a stylized rig that already stands naturally only risks+ folding its arms.+3. **Otherwise** the avatar takes one held frame of the motion library's+ standing idle (`av-idle-male`, sampled once by `sampleClipPose()`) through+ `AnimationManager`, the same retargeting path the live viewer animates with:+ canonical bone names from `src/glb-canonicalize.js`, rest-frame correction from+ `src/animation-retarget.js`, and the fallen-pose guard. Only joint rotations+ are applied; the avatar keeps its own hip height.+4. **The clip cannot drive the rig** (too few bones map, for example a rig with+ no finger bones): the arms are swung down geometrically by+ `relaxUndrivenArms()`, so the result is at worst an arms-down stance.++Renderers report the outcome through an `onPose({ posed, mode })` callback, and+`/api/render/glb` through its `x-render-pose` header. Pass `pose: 'bind'` to any+of them to render the skeleton exactly as authored.++A skeleton convention the canonicalizer does not recognise renders as authored.+Add its bone names to `src/glb-canonicalize.js` (with a case in+`tests/glb-canonicalize.test.js`) and every renderer picks it up; never add a+bone table to a renderer.++## Regenerating thumbnails after a pose change++Posters rendered before the rest pose existed stay in the bucket until something+re-renders them.+[`scripts/regenerate-avatar-thumbnails.mjs`](../scripts/regenerate-avatar-thumbnails.mjs)+does that for the keys the platform writes itself (`thumb/<uuid>.png`,+`og/avatar/<uuid>.png`, `<storage key>_og.png`, `forge/thumb/<uuid>.png`); a+creator's uploaded cover or an adopted forge reference image is never touched.+Work is planned per distinct key, most-visible first, so an agent body cloned+from a gallery avatar is fixed by the same single render as its source.++It is a dry run unless `--apply` is passed. `--apply` overwrites each object in+place under the same key, stamped `x-amz-meta-thumbnail-pose:+<THUMBNAIL_POSE_VERSION>`, and changes no database row. A model that comes back+unposed (a prop, or a rig already standing at rest) is skipped, and an object+already carrying the current stamp is skipped, so a run can be stopped and+resumed.++```bash+eval "$(node scripts/read-service-env.mjs '^S3_')"++# What would be visited, in order. Renders nothing.+node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --plan-only --limit=50++# Render 25 locally and save <avatar>-before.png / <avatar>-after.png to review.+node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --limit=25 --out=/tmp/thumbs++# Overwrite the stale posters, 500 keys at a time, resuming with --offset.+node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --apply --limit=500 --concurrency=3+node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --apply --limit=500 --offset=500 --concurrency=3+```++Every surface derives the image URL from `thumbnail_key` at read time, so no+URL changes. The public bucket domain sends no `Cache-Control` header for these+objects, so a fresh request sees the new bytes as soon as the overwrite lands,+and a browser holding a heuristically cached copy revalidates against the ETag,+which the overwrite changes. When the pose itself changes, bump+`THUMBNAIL_POSE_VERSION` in `src/thumbnail-pose.js` and run the script again.+## The three crons| Cron | Schedule | Job |diff --git a/packages/render/README.md b/packages/render/README.mdindex 01fcf5b82..eef69a6eb 100644--- a/packages/render/README.md+++ b/packages/render/README.md@@ -177,6 +177,7 @@ one with gaps:| `AvatarModel.load(source, options)` | Load a GLB into a posable model. || `model.addClips(clips)` | Retarget clips onto this skeleton by bone name. || `model.play(nameOrIndex)` / `model.setTime(s)` | Pose the model. |+| `model.updateBounds()` | Re-measure the framing bounds after posing the skeleton yourself (bounds are otherwise taken once, in the bind pose). || `renderFrame(model, options)` | One RGBA frame. || `renderFrames(model, options)` | A frame list, with animation and turntable spin. || `frameCamera(bounds, options)` | The camera used for a given focus mode. |diff --git a/packages/render/src/glb.js b/packages/render/src/glb.jsindex 45caae745..0b9ab4177 100644--- a/packages/render/src/glb.js+++ b/packages/render/src/glb.js@@ -134,9 +134,17 @@ function textureBinding(json, ref) {if (!ref || typeof ref.index !== 'number') return null;const tex = json.textures?.[ref.index];if (!tex) return null;+ // EXT_texture_webp / EXT_texture_avif move the image index into the+ // extension and leave `source` unset (or pointing at a PNG fallback). The+ // image decoder reads WebP and AVIF through sharp, so prefer those payloads;+ // without this every WebP-textured avatar rendered as bare white material.// KHR_texture_basisu points at a KTX2 payload we do not decode; the caller// falls back to the material factor, which is a real colour, not a stand-in.- const source = tex.source ?? tex.extensions?.KHR_texture_basisu?.source;+ const source =+ tex.extensions?.EXT_texture_webp?.source ??+ tex.extensions?.EXT_texture_avif?.source ??+ tex.source ??+ tex.extensions?.KHR_texture_basisu?.source;if (typeof source !== 'number') return null;const sampler = typeof tex.sampler === 'number' ? json.samplers?.[tex.sampler] : null;return {diff --git a/packages/render/src/model.js b/packages/render/src/model.jsindex 699113268..09ad2adf3 100644--- a/packages/render/src/model.js+++ b/packages/render/src/model.js@@ -129,6 +129,19 @@ export class AvatarModel {return this.action?.getClip()?.duration || 0;}+ /**+ * Re-measure the framing bounds from the skeleton's current pose. Bounds are+ * taken once at load, in the bind pose, so a T-posed rig's outstretched arms+ * set the frame. Call this after posing the skeleton by hand (anything other+ * than play/setTime) when a still should be framed around the pose it shows.+ * @returns {{min:number[],max:number[],center:number[],size:number[]}}+ */+ updateBounds() {+ this.scene.updateMatrixWorld(true);+ this.bounds = this._computeBounds();+ return this.bounds;+ }+_collect() {this.scene.updateMatrixWorld(true);this.scene.traverse((object) => {diff --git a/packages/render/src/render.js b/packages/render/src/render.jsindex 783d6026d..23864ec16 100644--- a/packages/render/src/render.js+++ b/packages/render/src/render.js@@ -62,13 +62,36 @@ function normalize(v) {return [v[0] / len, v[1] / len, v[2] / len];}-function parseColor(value) {- if (typeof value !== 'string') return [0, 0, 0];- const hex = value.replace('#', '').trim();+// sRGB 0..1 from hsl(): h in degrees, s and l in 0..1 (CSS Color 4 formula).+function hslToSrgb(h, s, l) {+ const k = (n) => (n + h / 30) % 12;+ const a = s * Math.min(l, 1 - l);+ return [0, 8, 4].map((n) => l - a * Math.max(-1, Math.min(k(n) - 3, 9 - k(n), 1)));+}++// Read a CSS colour as sRGB 0..1: #rgb, #rrggbb, rgb()/rgba() and hsl()/hsla(),+// the forms the platform's stage backdrops are written in. Anything else is black.+function parseSrgb(value) {+ const text = value.trim().toLowerCase();+ const fn = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);+ if (fn) {+ const parts = fn[2].split(/[\s,/]+/).filter(Boolean).map((p) => Number.parseFloat(p));+ if (parts.length < 3 || parts.slice(0, 3).some((p) => !Number.isFinite(p))) return null;+ if (fn[1].startsWith('rgb')) return parts.slice(0, 3).map((c) => Math.max(0, Math.min(255, c)) / 255);+ const [h, s, l] = parts;+ return hslToSrgb(((h % 360) + 360) % 360, Math.max(0, Math.min(100, s)) / 100, Math.max(0, Math.min(100, l)) / 100);+ }+ const hex = text.replace('#', '');const full = hex.length === 3 ? hex.split('').map((c) => c + c).join('') : hex;+ if (!/^[0-9a-f]{6}/.test(full)) return null;const n = Number.parseInt(full.slice(0, 6), 16);- if (!Number.isFinite(n)) return [0, 0, 0];- const srgb = [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];+ return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255];+}++function parseColor(value) {+ if (typeof value !== 'string') return [0, 0, 0];+ const srgb = parseSrgb(value);+ if (!srgb) return [0, 0, 0];return srgb.map((c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));}diff --git a/packages/render/tests/glb.test.js b/packages/render/tests/glb.test.jsindex 6c7f1f697..c8b55ce9e 100644--- a/packages/render/tests/glb.test.js+++ b/packages/render/tests/glb.test.js@@ -129,3 +129,23 @@ describe('stripImages', () => {expect(stripped.extensionsUsed).toEqual(['EXT_meshopt_compression']);});});++describe('stripImages with EXT_texture_webp', () => {+ it('binds the WebP payload a texture declares in its extension', () => {+ // The texture names its image only inside EXT_texture_webp, as every+ // gltf-transform WebP export does; reading `source` alone left the+ // material untextured (bare white) on the CPU lane.+ const json = {+ asset: { version: '2.0' },+ images: [{ mimeType: 'image/png' }, { mimeType: 'image/webp' }],+ textures: [{ source: 0, extensions: { EXT_texture_webp: { source: 1 } } }, { extensions: { EXT_texture_webp: { source: 1 } } }],+ materials: [+ { pbrMetallicRoughness: { baseColorTexture: { index: 0 } } },+ { pbrMetallicRoughness: { baseColorTexture: { index: 1 } } },+ ],+ };+ const { bindings } = stripImages(json);+ expect(bindings.get(0).baseColor.image).toBe(1);+ expect(bindings.get(1).baseColor.image).toBe(1);+ });+});diff --git a/packages/render/tests/render.test.js b/packages/render/tests/render.test.jsindex c70879d99..b35004250 100644--- a/packages/render/tests/render.test.js+++ b/packages/render/tests/render.test.js@@ -120,6 +120,19 @@ describe('renderFrame', () => {expect(frame.data[corner]).toBeLessThan(frame.data[centre]);});+ it('reads hsl() and rgb() backdrop colours, not just hex', () => {+ // The platform's per-avatar stages are written as hsl(); parsed as hex+ // they collapsed to black and every poster lost its tinted backdrop.+ const options = { width: 32, height: 32, supersample: 1 };+ const hsl = renderFrame(model, { ...options, background: { inner: 'hsl(120, 60%, 40%)', outer: 'hsl(120, 60%, 40%)' } });+ const rgb = renderFrame(model, { ...options, background: 'rgb(41, 163, 41)' });+ const hex = renderFrame(model, { ...options, background: '#29a329' });+ for (const frame of [hsl, rgb]) {+ for (let c = 0; c < 3; c++) expect(Math.abs(frame.data[c] - hex.data[c])).toBeLessThanOrEqual(2);+ }+ expect(hex.data[1]).toBeGreaterThan(100);+ });+it('exposes named lighting presets', () => {expect(Object.keys(PRESETS)).toContain('studio');for (const preset of Object.values(PRESETS)) {diff --git a/scripts/regenerate-avatar-thumbnails.mjs b/scripts/regenerate-avatar-thumbnails.mjsnew file mode 100644index 000000000..d6023eed4--- /dev/null+++ b/scripts/regenerate-avatar-thumbnails.mjs@@ -0,0 +1,302 @@+#!/usr/bin/env node+/**+ * Re-render stored avatar thumbnails in the thumbnail rest pose.+ *+ * Posters baked before src/thumbnail-pose.js existed show a humanoid in its raw+ * bind pose, arms straight out in a T. Every thumbnail the server renders from+ * now on is posed, but the ones already in the bucket stay as they were until+ * something re-renders them. This script is that something.+ *+ * What it touches: only thumbnail objects the platform renders or auto-captures+ * itself, never a creator's own artwork.+ *+ * thumb/<uuid>.png backfill renders and the /create auto-capture+ * og/avatar/<uuid>.png OG renders of first-party avatars+ * <storage key>_og.png OG renders of bucket avatars+ * forge/thumb/<uuid>.png server renders of forge models+ *+ * Many avatars share one thumbnail (an agent's cloned body keeps its source's+ * key), so work is planned per distinct key: one render rewrites the picture+ * for every avatar that points at it. Keys are visited most-visible first+ * (featured, then public, then views).+ *+ * How it writes: --apply re-renders the GLB and overwrites the object IN PLACE+ * under the same key, stamped with x-amz-meta-thumbnail-pose. No database row+ * changes, so the avatars table is never written. A model that is not a+ * humanoid (a prop, a vehicle, a creature) comes back from the renderer+ * unposed, and its stored thumbnail is left alone. An object already stamped+ * with the current THUMBNAIL_POSE_VERSION is skipped, so a run can be stopped+ * and restarted (use --offset to jump ahead) without paying for work twice.+ *+ * Usage (DATABASE_URL is in .env.local; the S3_* set lives on the Cloud Run+ * service):+ *+ * eval "$(node scripts/read-service-env.mjs '^S3_')"+ *+ * # Plan only (the default). Renders nothing, writes nothing.+ * node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --limit=20 --plan-only+ *+ * # Dry run: render each candidate locally and save before/after PNGs to a+ * # folder for review. Reads production, writes nothing to it.+ * node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --limit=12 --out=/tmp/thumbs+ *+ * # Apply: overwrite the stale posters in the bucket.+ * node --env-file=.env.local scripts/regenerate-avatar-thumbnails.mjs --apply --limit=500 --concurrency=3+ *+ * Flags:+ * --apply overwrite objects in the bucket (default: dry run)+ * --limit=N distinct thumbnail keys to visit (default 25)+ * --offset=N skip the first N keys in priority order (default 0)+ * --concurrency=N renders in flight at once (default 2)+ * --ids=a,b,c only the thumbnails of these avatar ids+ * --out=DIR dry run: write <avatar>-before.png and <avatar>-after.png here+ * --plan-only list the keys that would be visited, render nothing+ *+ * Cache: the public bucket domain serves these objects with no Cache-Control+ * header, so a fresh request gets the new bytes the moment the overwrite+ * lands, and a browser holding a heuristically cached copy revalidates on its+ * ETag, which the overwrite changes. Nothing on our side caches the image URL:+ * every surface derives it from thumbnail_key at read time.+ */++import { mkdir, writeFile } from 'node:fs/promises';+import path from 'node:path';+import { sql } from '../api/_lib/db.js';+import { headObject, presignGet, publicUrl, putObject, isStorageInfrastructureError } from '../api/_lib/r2.js';+import { renderGlbToPng, isBrowserInfrastructureError } from '../api/_lib/render-glb.js';+import { thumbBackdropFor, THUMB_SIZE, THUMB_BACKGROUND } from '../api/_lib/avatar-thumbs.js';+import { THUMBNAIL_POSE_VERSION } from '../src/thumbnail-pose.js';++const argv = process.argv.slice(2);+const flag = (name) => argv.includes(`--${name}`);+const opt = (name, fallback) => {+ const hit = argv.find((a) => a.startsWith(`--${name}=`));+ return hit ? hit.slice(name.length + 3) : fallback;+};+const int = (name, fallback, min) => {+ const n = Number.parseInt(opt(name, ''), 10);+ return Number.isFinite(n) ? Math.max(min, n) : fallback;+};++const APPLY = flag('apply');+const PLAN_ONLY = flag('plan-only');+const LIMIT = int('limit', 25, 1);+const OFFSET = int('offset', 0, 0);+const CONCURRENCY = int('concurrency', 2, 1);+const OUT = opt('out', '');+const IDS = opt('ids', '')+ .split(',')+ .map((s) => s.trim())+ .filter(Boolean);++const META_KEY = 'thumbnail-pose';+const UUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';++// The four key shapes the platform writes itself. Anything else (an adopted+// forge reference image, a creator's uploaded cover) is not ours to repaint.+const KEY_SHAPES = {+ thumb: new RegExp(`^thumb/${UUID}\\.png$`),+ ogAvatar: new RegExp(`^og/avatar/${UUID}\\.png$`),+ forgeThumb: new RegExp(`^forge/thumb/${UUID}\\.png$`),+ ogBucket: /^(?!https?:\/\/).+_og\.png$/i,+};++function shapeOf(key) {+ for (const [shape, re] of Object.entries(KEY_SHAPES)) if (re.test(key)) return shape;+ return null;+}++// Same canvas each writer used, so a regenerated poster is interchangeable with+// a fresh one: OG cards are 1200x630, gallery thumbnails square.+function canvasFor(shape) {+ if (shape === 'ogAvatar' || shape === 'ogBucket') return { width: 1200, height: 630 };+ return { width: THUMB_SIZE, height: THUMB_SIZE };+}++// The stage tint is seeded the way the original writer seeded it: by avatar id,+// or by the forge creation id embedded in a forge key.+function backdropSeed(key, shape, avatarId) {+ if (shape === 'forgeThumb') return key.slice('forge/thumb/'.length, -'.png'.length);+ return avatarId;+}++function requireEnv() {+ const missing = ['DATABASE_URL'];+ if (!PLAN_ONLY) missing.push('S3_PUBLIC_DOMAIN');+ if (APPLY) missing.push('S3_BUCKET', 'S3_ACCESS_KEY_ID', 'S3_SECRET_ACCESS_KEY');+ for (const name of missing) {+ if (process.env[name]) continue;+ const where = name.startsWith('S3_')+ ? `export the S3_* set first: eval "$(node scripts/read-service-env.mjs '^S3_')"`+ : `run with: node --env-file=.env.local ${path.relative(process.cwd(), process.argv[1])}`;+ console.error(`[regen] ${name} is unset. ${where}`);+ process.exit(1);+ }+}++const SHAPE_SQL = `^(thumb/${UUID}\\.png|og/avatar/${UUID}\\.png|forge/thumb/${UUID}\\.png)$`;++/**+ * Distinct server-written thumbnail keys, each with the GLB to re-render it+ * from. A key named after an avatar (thumb/<id>.png) renders from that avatar+ * when it still exists; otherwise from the oldest avatar sharing the key.+ */+async function planKeys() {+ const ids = IDS.length ? IDS : null;+ return sql`+ WITH refs AS (+ SELECT a.id, a.storage_key, a.thumbnail_key AS key, a.featured, a.visibility,+ a.view_count, a.created_at+ FROM avatars a+ WHERE a.deleted_at IS NULL+ AND a.storage_key IS NOT NULL+ AND a.thumbnail_key IS NOT NULL+ AND (a.thumbnail_key ~ ${SHAPE_SQL}+ OR (a.thumbnail_key ~* '_og[.]png$' AND a.thumbnail_key !~* '^https?://'))+ AND (${ids}::uuid[] IS NULL OR a.id = ANY(${ids}::uuid[]))+ )+ SELECT key,+ (array_agg(id ORDER BY (key LIKE '%' || id::text || '%') DESC, created_at ASC))[1] AS avatar_id,+ (array_agg(storage_key ORDER BY (key LIKE '%' || id::text || '%') DESC, created_at ASC))[1] AS storage_key,+ count(*)::int AS refs,+ bool_or(featured) AS featured,+ bool_or(visibility = 'public') AS public,+ max(view_count) AS views+ FROM refs+ GROUP BY key+ ORDER BY featured DESC, public DESC, views DESC NULLS LAST, key+ LIMIT ${LIMIT} OFFSET ${OFFSET}+ `;+}++// GLB the renderer reads. A signed URL when we hold storage credentials (works+// for private avatars too), otherwise the public bucket URL, which is all a dry+// run needs. Absolute first-party URLs pass through either way.+async function glbUrlFor(storageKey) {+ if (process.env.S3_ACCESS_KEY_ID && process.env.S3_BUCKET) {+ return presignGet({ key: storageKey, expiresIn: 300 });+ }+ return publicUrl(storageKey);+}++// Pose stamp of the stored object, or null when we cannot tell (no storage+// credentials in a dry run) or the object predates the stamp.+async function storedPoseVersion(key) {+ if (!process.env.S3_ACCESS_KEY_ID) return null;+ const head = await headObject(key);+ return head?.Metadata?.[META_KEY] || null;+}++async function saveCurrent(key, file) {+ const res = await fetch(publicUrl(key), { signal: AbortSignal.timeout(20_000) });+ if (!res.ok) return false;+ await writeFile(file, Buffer.from(await res.arrayBuffer()));+ return true;+}++async function processKey(row) {+ const shape = shapeOf(row.key);+ if (!shape) return { status: 'skipped', reason: 'unrecognised key shape' };++ if ((await storedPoseVersion(row.key)) === THUMBNAIL_POSE_VERSION) {+ return { status: 'current' };+ }++ let pose = { posed: false, mode: 'unknown' };+ const t0 = Date.now();+ const png = await renderGlbToPng({+ glbUrl: await glbUrlFor(row.storage_key),+ ...canvasFor(shape),+ background: THUMB_BACKGROUND,+ backdrop: thumbBackdropFor(backdropSeed(row.key, shape, row.avatar_id)),+ onPose: (result) => {+ pose = result;+ },+ });+ const ms = Date.now() - t0;+ if (!png?.length) throw new Error('renderer returned no bytes');++ // Not a humanoid: the render is the model as authored, which is what the+ // stored poster already shows. Leave it.+ if (!pose.posed) return { status: 'skipped', reason: `not posable (${pose.mode})`, ms };++ if (!APPLY) {+ if (OUT) {+ await saveCurrent(row.key, path.join(OUT, `${row.avatar_id}-before.png`)).catch(() => false);+ await writeFile(path.join(OUT, `${row.avatar_id}-after.png`), png);+ }+ return { status: 'would-write', mode: pose.mode, bytes: png.length, ms };+ }++ await putObject({+ key: row.key,+ body: png,+ contentType: 'image/png',+ metadata: { 'avatar-id': String(row.avatar_id), [META_KEY]: THUMBNAIL_POSE_VERSION },+ });+ return { status: 'written', mode: pose.mode, bytes: png.length, ms };+}++async function main() {+ requireEnv();+ if (OUT) await mkdir(OUT, { recursive: true });++ const rows = await planKeys();+ const mode = APPLY ? 'APPLY' : PLAN_ONLY ? 'plan only' : 'dry run';+ console.log(+ `[regen] ${mode}: ${rows.length} thumbnail key(s), offset ${OFFSET}, pose ${THUMBNAIL_POSE_VERSION}` ++ (OUT && !APPLY ? `, saving PNGs to ${OUT}` : ''),+ );+ if (PLAN_ONLY) {+ for (const [i, r] of rows.entries()) {+ console.log(` ${OFFSET + i + 1}. ${r.key} avatars=${r.refs} views=${r.views ?? 0} glb=${r.storage_key}`);+ }+ return;+ }++ const tally = { written: 0, 'would-write': 0, current: 0, skipped: 0, failed: 0 };+ const queue = rows.map((row, i) => ({ row, n: OFFSET + i + 1 }));+ const total = OFFSET + rows.length;+ let aborted = null;++ const worker = async () => {+ for (let job = queue.shift(); job && !aborted; job = queue.shift()) {+ const { row, n } = job;+ const label = `[${n}/${total}] ${row.key} (avatars=${row.refs})`;+ try {+ const r = await processKey(row);+ tally[r.status] += 1;+ const detail = [r.mode, r.reason, r.bytes && `${r.bytes}B`, r.ms && `${r.ms}ms`].filter(Boolean).join(' ');+ console.log(`${label} ${r.status}${detail ? ` ${detail}` : ''}`);+ } catch (err) {+ const msg = err?.message || String(err);+ // A dead browser or unreachable bucket fails every job after it for a+ // reason that has nothing to do with the models. Stop instead.+ if (isBrowserInfrastructureError(err) || isStorageInfrastructureError(err)) {+ aborted = msg;+ console.error(`${label} aborting the run: ${msg}`);+ return;+ }+ tally.failed += 1;+ console.warn(`${label} failed ${msg}`);+ }+ }+ };+ await Promise.all(Array.from({ length: Math.min(CONCURRENCY, rows.length || 1) }, worker));++ console.log(`[regen] done: ${JSON.stringify(tally)}${aborted ? ` (aborted: ${aborted})` : ''}`);+ if (rows.length === LIMIT) {+ console.log(`[regen] more may remain: rerun with --offset=${OFFSET + rows.length}`);+ }+ if (aborted) process.exitCode = 2;+}++main()+ .catch((err) => {+ console.error('[regen] fatal:', err?.stack || err);+ process.exitCode = 1;+ })+ .finally(() => {+ // The shared chromium (failover lane) keeps the event loop alive.+ setTimeout(() => process.exit(), 100).unref();+ });diff --git a/src/account.js b/src/account.jsindex 8344b8c45..cdc36ccac 100644--- a/src/account.js+++ b/src/account.js@@ -245,7 +245,7 @@ export async function saveRemoteGlbToAccount(source, meta = {}, opts = {}) {const avatar = created.avatar;// Fire-and-forget thumbnail + auto-tag pipeline. Doesn't block the caller.- // Uses a hidden off-screen model-viewer to render the GLB, captures a JPEG+ // Renders the GLB offscreen in the thumbnail rest pose, captures a JPEG// poster, uploads to R2, and calls Claude Haiku for tags + description.captureAndTagAvatar(avatar.id, storageKey).catch((err) => {log.warn('[account] thumbnail/auto-tag pipeline failed silently', err?.message);@@ -386,33 +386,19 @@ async function captureAndTagAvatar(avatarId, storageKey) {if (!publicGlb) return;} catch { return; }- // Render in a tiny off-screen model-viewer element.- const mv = document.createElement('model-viewer');- mv.setAttribute('src', publicGlb);- mv.setAttribute('camera-orbit', '0deg 75deg 105%');- mv.setAttribute('exposure', '1');- mv.setAttribute('shadow-intensity', '0.6');- mv.setAttribute('tone-mapping', 'aces');- mv.style.cssText = 'position:fixed;left:-9999px;top:-9999px;width:512px;height:512px;opacity:0;pointer-events:none;';- document.body.appendChild(mv);-- await new Promise((resolve, reject) => {- const timeout = setTimeout(() => reject(new Error('model-viewer load timeout')), 25_000);- mv.addEventListener('load', () => { clearTimeout(timeout); resolve(); }, { once: true });- mv.addEventListener('error', () => { clearTimeout(timeout); reject(new Error('model-viewer load error')); }, { once: true });+ // Render the poster offscreen with the shared three.js renderer, which stands+ // a humanoid in the thumbnail rest pose first. The hidden <model-viewer> this+ // replaced captured the raw bind pose, so every saved avatar's gallery card+ // showed a T-pose, and being the slower of the two /create captures it usually+ // landed last and overwrote the posed one.+ const glbRes = await fetch(publicGlb);+ if (!glbRes.ok) throw new Error(`thumbnail source fetch failed: ${glbRes.status}`);+ const { glbFileToThumbnail } = await import('./erc8004/thumbnail.js');+ const thumbBlob = await glbFileToThumbnail(await glbRes.blob(), {+ size: 512,+ mimeType: 'image/jpeg',+ quality: 0.82,});-- // Give the renderer one frame to paint.- await new Promise((r) => requestAnimationFrame(r));- await new Promise((r) => requestAnimationFrame(r));-- // Capture poster as JPEG blob.- let thumbBlob;- try {- thumbBlob = await mv.toBlob({ mimeType: 'image/jpeg', qualityArgument: 0.82 });- } finally {- document.body.removeChild(mv);- }if (!thumbBlob || thumbBlob.size < 500) return;// Get a presigned upload URL for the thumbnail.diff --git a/src/app.js b/src/app.jsindex 274ae94e1..2c85c50ea 100644--- a/src/app.js+++ b/src/app.js@@ -1130,6 +1130,7 @@ class App {this._currentUsdzUrl = null;this._currentHalfbodyUrl = null;this._currentAvatarId = null;+ this._currentAvatarGlbUrl = null;this._avatarNeedsThumbnail = false;try {const resp = await fetch(`/api/agents/${agentId}`, { credentials: 'include' });@@ -1145,6 +1146,7 @@ class App {this._currentUsdzUrl = avatar?.usdz_url || null;this._currentHalfbodyUrl = avatar?.halfbody_url || null;this._currentAvatarId = avatar?.id || null;+ this._currentAvatarGlbUrl = avatar?.url || null;thumbnailUrl = avatar?.thumbnail_url || null;// Flag for the LOAD_END(success) listener to capture// and upload a thumbnail once the avatar is rendered.@@ -2357,35 +2359,22 @@ class App {}// ── Auto-thumbnail capture ──────────────────────────────────────────────- // Reads the WebGL canvas pixels, downsamples to a 512² PNG, and POSTs- // to /api/avatars/thumbnail. Fire-and-forget — the only consequence of- // failure is that the next page load runs through this path again.+ // Renders the avatar's GLB offscreen to a 512² PNG in the thumbnail rest+ // pose and POSTs it to /api/avatars/thumbnail. Reading the live viewer's+ // canvas instead raced the idle clip (a capture before it started showed the+ // bind-pose T-pose) and could read back a blank buffer, since the viewer's+ // renderer does not preserve its drawing buffer. Fire-and-forget: the only+ // consequence of failure is that the next page load runs through this again.async _captureAndUploadThumbnail() {const avatarId = this._currentAvatarId;- if (!avatarId || !this.viewer?.renderer) return;-- // Give the renderer one extra frame so the first idle pose is on- // screen, not the canonical T-pose / default expression.- await new Promise((r) => setTimeout(r, 800));-- const src = this.viewer.renderer.domElement;- const out = document.createElement('canvas');- const size = 512;- out.width = out.height = size;- const ctx = out.getContext('2d');- if (!ctx) return;- // Fit-to-canvas, preserving aspect with letterboxing on a- // transparent background.- const ar = src.width / src.height || 1;- let dw = size,- dh = size;- if (ar > 1) dh = Math.round(size / ar);- else dw = Math.round(size * ar);- ctx.drawImage(src, (size - dw) / 2, (size - dh) / 2, dw, dh);-- const blob = await new Promise((resolve) => out.toBlob(resolve, 'image/png'));- if (!blob) return;+ const glbUrl = this._currentAvatarGlbUrl;+ if (!avatarId || !glbUrl) return;++ const glbRes = await fetch(glbUrl);+ if (!glbRes.ok) throw new Error(`thumbnail source fetch failed: ${glbRes.status}`);+ const { glbFileToThumbnail } = await import('./erc8004/thumbnail.js');+ const blob = await glbFileToThumbnail(await glbRes.blob(), { size: 512 });const dataUrl = await _blobToBase64(blob);const resp = await fetch('/api/avatars/thumbnail', {diff --git a/src/erc8004/thumbnail.js b/src/erc8004/thumbnail.jsindex f55917026..459e6d019 100644--- a/src/erc8004/thumbnail.js+++ b/src/erc8004/thumbnail.js@@ -1,10 +1,15 @@/**- * Client-side GLB → PNG thumbnail renderer.+ * Client-side GLB → image thumbnail renderer.** ERC-8004's `image` field is for 2D ERC-721 marketplace compatibility* (OpenSea, wallets) which can't render GLB. When a user deploys a three.ws* without supplying a 2D poster, we render one from the GLB in an offscreen- * canvas and pin it alongside the body.+ * canvas and pin it alongside the body. The account save flow (src/account.js)+ * uses the same renderer for the gallery thumbnail of every saved avatar.+ *+ * A humanoid is stood in the thumbnail rest pose first (src/thumbnail-pose.js,+ * the same posing the server renderers use), so a poster never shows the raw+ * bind pose with the arms straight out.*/import {@@ -20,71 +25,82 @@ import {ACESFilmicToneMapping,} from 'three';import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';-import { getMeshoptDecoder } from '../viewer/internal.js';+import { getDecoders } from '../viewer/internal.js';+import { applyThumbnailPose, sampleClipPose, THUMBNAIL_POSE_TIME, THUMBNAIL_POSE_URL } from '../thumbnail-pose.js';++let _poseClipPromise = null;++// The rest pose, fetched once per page from the motion library. A failed fetch+// is not cached, so the next thumbnail retries instead of rendering unposed for+// the rest of the session.+function loadPoseClip() {+ if (!_poseClipPromise) {+ _poseClipPromise = fetch(THUMBNAIL_POSE_URL)+ .then((res) => {+ if (!res.ok) throw new Error(`pose clip ${res.status}`);+ return res.json();+ })+ .then((json) => sampleClipPose(json, THUMBNAIL_POSE_TIME))+ .catch((err) => {+ _poseClipPromise = null;+ throw err;+ });+ }+ return _poseClipPromise;+}/**- * Render a GLB/GLTF file to a PNG blob.+ * Render a GLB/GLTF file to an image blob.** @param {File|Blob} file GLB/GLTF file* @param {object} [opts]* @param {number} [opts.size=512]* @param {string} [opts.background='#1a1a1a']- * @returns {Promise<Blob>} PNG blob (has `.name = 'thumbnail.png'`)+ * @param {string} [opts.mimeType='image/png'] 'image/png' or 'image/jpeg'+ * @param {number} [opts.quality=0.85] JPEG quality+ * @param {boolean} [opts.pose=true] stand a humanoid in the rest pose+ * @returns {Promise<Blob>} image blob (has `.name = 'thumbnail.png'` or `.jpg`)*/-export async function glbFileToThumbnail(file, { size = 512, background = '#1a1a1a' } = {}) {- const buffer = await file.arrayBuffer();- const loader = new GLTFLoader();- loader.setMeshoptDecoder(await getMeshoptDecoder());- const gltf = await new Promise((resolve, reject) => {- loader.parse(buffer, '', resolve, reject);- });-- const scene = new Scene();- scene.background = new Color(background);- scene.add(gltf.scene);-- const box = new Box3().setFromObject(gltf.scene);- const center = box.getCenter(new Vector3());- const boxSize = box.getSize(new Vector3());- const maxDim = Math.max(boxSize.x, boxSize.y, boxSize.z) || 1;-- const fov = 35;- const camera = new PerspectiveCamera(fov, 1, 0.01, 1000);- const dist = maxDim / (2 * Math.tan((Math.PI * fov) / 360));- // Mixamo-style framing: eye-level, slightly above center, pulled back.- camera.position.set(center.x, center.y + boxSize.y * 0.05, center.z + dist * 1.8);- camera.lookAt(center.x, center.y, center.z);-- scene.add(new HemisphereLight(0xffffff, 0x444444, 2.0));- const dir = new DirectionalLight(0xffffff, 2.5);- dir.position.set(3, 10, 7);- scene.add(dir);-+export async function glbFileToThumbnail(+ file,+ { size = 512, background = '#1a1a1a', mimeType = 'image/png', quality = 0.85, pose = true } = {},+) {const canvas = document.createElement('canvas');canvas.width = size;canvas.height = size;- const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: false });+ const renderer = new WebGLRenderer({ canvas, antialias: true, alpha: false, preserveDrawingBuffer: true });renderer.setPixelRatio(1);renderer.setSize(size, size, false);renderer.outputColorSpace = SRGBColorSpace;renderer.toneMapping = ACESFilmicToneMapping;renderer.toneMappingExposure = 1.0;+ const scene = new Scene();+ scene.background = new Color(background);try {- renderer.render(scene, camera);- const blob = await new Promise((resolve, reject) => {- canvas.toBlob(- (b) => (b ? resolve(b) : reject(new Error('toBlob returned null'))),- 'image/png',- );+ const [buffer, { dracoLoader, ktx2Loader, meshoptDecoder }] = await Promise.all([+ file.arrayBuffer(),+ getDecoders(),+ ]);+ // Saved avatars arrive Draco-, Meshopt- or KTX2-compressed depending on+ // which pipeline produced them, so register every decoder the viewer does.+ const loader = new GLTFLoader();+ loader.setDRACOLoader(dracoLoader);+ loader.setKTX2Loader(ktx2Loader.detectSupport(renderer));+ loader.setMeshoptDecoder(meshoptDecoder);+ const gltf = await new Promise((resolve, reject) => {+ loader.parse(buffer, '', resolve, reject);});- // File-like name so pinFile can label the upload.- try {- Object.defineProperty(blob, 'name', { value: 'thumbnail.png' });- } catch {- /* Blob is usually writable; ignore if not */+ scene.add(gltf.scene);++ // Posing is an improvement, never a requirement: if the clip cannot be+ // fetched the poster still renders, as authored.+ if (pose) {+ const clip = await loadPoseClip().catch(() => null);+ if (clip) await applyThumbnailPose(gltf.scene, clip);}- return blob;++ return await renderPoster({ scene, root: gltf.scene, renderer, canvas, mimeType, quality });} finally {renderer.dispose();scene.traverse((obj) => {@@ -96,3 +112,40 @@ export async function glbFileToThumbnail(file, { size = 512, background = '#1a1a});}}++async function renderPoster({ scene, root, renderer, canvas, mimeType, quality }) {+ const box = new Box3().setFromObject(root);+ const center = box.getCenter(new Vector3());+ const boxSize = box.getSize(new Vector3());+ const maxDim = Math.max(boxSize.x, boxSize.y, boxSize.z) || 1;++ const fov = 35;+ const camera = new PerspectiveCamera(fov, 1, 0.01, 1000);+ const dist = maxDim / (2 * Math.tan((Math.PI * fov) / 360));+ // Eye-level framing, slightly above center. The margin used to be 1.8x,+ // sized for a T-pose's arm span; a posed avatar stands well inside its own+ // height, so a tighter pull-back fills the card instead of floating in it.+ camera.position.set(center.x, center.y + boxSize.y * 0.05, center.z + boxSize.z / 2 + dist * 1.15);+ camera.lookAt(center.x, center.y, center.z);++ scene.add(new HemisphereLight(0xffffff, 0x444444, 2.0));+ const dir = new DirectionalLight(0xffffff, 2.5);+ dir.position.set(3, 10, 7);+ scene.add(dir);++ renderer.render(scene, camera);+ const blob = await new Promise((resolve, reject) => {+ canvas.toBlob(+ (b) => (b ? resolve(b) : reject(new Error('toBlob returned null'))),+ mimeType,+ quality,+ );+ });+ // File-like name so pinFile can label the upload.+ try {+ Object.defineProperty(blob, 'name', { value: mimeType === 'image/jpeg' ? 'thumbnail.jpg' : 'thumbnail.png' });+ } catch {+ /* Blob is usually writable; ignore if not */+ }+ return blob;+}diff --git a/src/thumbnail-pose.js b/src/thumbnail-pose.jsnew file mode 100644index 000000000..f4f2d1b08--- /dev/null+++ b/src/thumbnail-pose.js@@ -0,0 +1,226 @@+// Thumbnail rest pose: put a loaded avatar into a natural standing pose before a+// still render, so a poster never shows the raw bind pose (a T-pose or A-pose+// with the arms straight out).+//+// Every renderer that turns a GLB into a picture runs this one module: the+// server's software rasterizer (api/_lib/render-cpu.js), the server's headless+// chromium failover (api/_lib/render-glb.js, which ships this file into its+// render page), and the browser's offscreen poster capture+// (src/erc8004/thumbnail.js). It adds no bone-name table of its own. Posing goes+// through AnimationManager, the same object the live viewer animates avatars+// with, so a thumbnail lands in exactly the pose the viewer's idle shows:+// canonical bone mapping (glb-canonicalize.js), rest-frame correction and hip+// scaling (animation-retarget.js), the fallen-pose guard, and the un-driven-arm+// relaxation (animation-arm-relax.js).+//+// The pose comes from the motion library's standing idle, `av-idle-male`: a+// static, symmetric, weight-centred stance with the arms relaxed at the sides+// and the head level. The looping `idle` clip was the other candidate and was+// rejected after rendering both across Mixamo, Avaturn/RPM and the clips' own+// authoring rig: every frame of it leans the torso back with the chin raised,+// which reads well in motion and badly frozen. Whatever the source, the pose is+// sampled into a constant two-key clip by sampleClipPose(), so a render page+// carries a few kilobytes and every thumbnail of one avatar is deterministic.+//+// Rigs that cannot take canonical clips (no skin, or too few humanoid bones:+// props, vehicles, creatures) are left exactly as authored, the same gate+// AnimationManager.supportsCanonicalClips() applies in the viewer.+//+// Pure module (three + the animation stack), so it runs unchanged in Node,+// in a browser and in vitest.++import { AnimationClip, Vector3 } from 'three';+import { AnimationManager } from './animation-manager.js';+import { relaxUndrivenArms } from './animation-arm-relax.js';+import { canonicalBoneNodesFromObject } from './animation-retarget.js';++/** Library clip a thumbnail pose is sampled from (public/animations/clips/). */+export const THUMBNAIL_POSE_CLIP = 'av-idle-male';++/** Seconds into THUMBNAIL_POSE_CLIP. The clip is a single held frame. */+export const THUMBNAIL_POSE_TIME = 0;++/** Where the browser fetches the source clip. */+export const THUMBNAIL_POSE_URL = `/animations/clips/${THUMBNAIL_POSE_CLIP}.json`;++/**+ * Version stamp for posters rendered with this pose. Bump it when the pose+ * changes so scripts/regenerate-avatar-thumbnails.mjs knows which stored+ * posters are stale.+ */+export const THUMBNAIL_POSE_VERSION = 'rest-v1';++const POSE_CLIP_NAME = 'thumbnail-rest';++// An upper arm whose direction to the elbow points further down than this+// (y of the unit vector; -0.87 is 60 degrees below horizontal) already hangs at+// the side. A T-pose reads about 0 and an A-pose about -0.7, so both get posed.+const ARM_HANGING_Y = -0.87;++const _shoulder = new Vector3();+const _elbow = new Vector3();++// The mixer fades a freshly played action in over 0.01 s (AnimationManager.play).+// One tick past that leaves the pose at full weight. The clip is constant, so+// the tick length never changes the pose itself.+const SETTLE_SECONDS = 0.05;++/**+ * Freeze one instant of a clip into a constant two-key clip.+ *+ * Joint rotations are slerped exactly the way the mixer would at that time (the+ * track's own interpolant), so the frozen pose is the frame the viewer would+ * show. Translation and scale tracks are dropped: a held pose has no root+ * motion, and the clip's hip translation is authored in metres, which launches+ * a rig whose hips rest at its armature origin under a centimetre-scale parent+ * (Robot Expressive, among others) a hundred units into the air. The avatar+ * keeps its own rest hip height and the renderer frames whatever it shows. Two+ * identical keys at 0 s and 1 s give the clip a real duration, which the+ * mixer's looping math needs.+ *+ * @param {object} clipJson three.js AnimationClip JSON (the on-disk clip format)+ * @param {number} [time=THUMBNAIL_POSE_TIME] seconds into the clip; wraps by its duration+ * @returns {object} AnimationClip JSON for the frozen pose+ */+export function sampleClipPose(clipJson, time = THUMBNAIL_POSE_TIME) {+ const clip = AnimationClip.parse(clipJson);+ const duration = clip.duration > 0 ? clip.duration : 0;+ const t = duration > 0 ? ((Number(time) || 0) % duration + duration) % duration : 0;+ const tracks = [];+ for (const track of clip.tracks) {+ if (!track.times?.length || !track.name.endsWith('.quaternion')) continue;+ const value = Array.from(track.createInterpolant().evaluate(t));+ const Track = track.constructor;+ tracks.push(new Track(track.name, [0, 1], [...value, ...value]));+ }+ return AnimationClip.toJSON(new AnimationClip(POSE_CLIP_NAME, 1, tracks));+}++// Every node's local transform, so a pose can be undone exactly. Undoing it+// matters wherever the posed object outlives the render: the CPU lane keeps+// decoded models in a cache, and a later retarget against a still-posed rig+// would read the idle frame as its rest pose.+function snapshotTransforms(root) {+ const saved = [];+ root.traverse((node) => {+ saved.push([node, node.position.clone(), node.quaternion.clone(), node.scale.clone()]);+ });+ return saved;+}++function restoreTransforms(root, saved) {+ for (const [node, position, quaternion, scale] of saved) {+ node.position.copy(position);+ node.quaternion.copy(quaternion);+ node.scale.copy(scale);+ }+ refreshSkinning(root);+}++/**+ * Bring world matrices and skeleton bone matrices up to date, so a bounds+ * measurement or a render that follows reads the current pose. Box3 reads a+ * SkinnedMesh through its bone matrices, which go stale until updated.+ *+ * @param {import('three').Object3D} root+ */+export function refreshSkinning(root) {+ root.updateMatrixWorld(true);+ root.traverse((node) => {+ if (!node.isSkinnedMesh) return;+ node.skeleton?.update();+ // A SkinnedMesh caches its skinned bounds on first use; drop the cache so+ // framing measures this pose rather than whichever one was measured first.+ node.boundingBox = null;+ node.boundingSphere = null;+ });+}++/**+ * Whether a rig was authored with both arms already hanging at its sides, a+ * stance that needs no posing. Reposing such a rig gains nothing and can lose:+ * a stylized body with short, thick limbs (Robot Expressive) retargets into+ * folded arms where its own stance was natural.+ *+ * @param {import('three').Object3D} root the rig in its bind pose+ * @returns {boolean}+ */+export function armsAlreadyHanging(root) {+ const nodes = canonicalBoneNodesFromObject(root);+ for (const [arm, forearm] of [['LeftArm', 'LeftForeArm'], ['RightArm', 'RightForeArm']]) {+ const a = nodes.get(arm);+ const b = nodes.get(forearm);+ if (!a || !b) return false;+ a.getWorldPosition(_shoulder);+ b.getWorldPosition(_elbow);+ const dir = _elbow.sub(_shoulder);+ const length = dir.length();+ if (length < 1e-6 || dir.y / length > ARM_HANGING_Y) return false;+ }+ return true;+}++/**+ * @typedef {Object} ThumbnailPoseResult+ * @property {boolean} posed true when the avatar was moved into the rest pose+ * @property {'rest'|'arms-relaxed'|'authored-rest'|'not-humanoid'|'no-pose'} mode+ * how it was posed, or why it was left as authored ('authored-rest': a+ * humanoid whose own bind pose already has its arms down)+ * @property {() => void} restore undo every change; safe to call more than once+ */++/**+ * Pose a loaded avatar for a still render, in place.+ *+ * A humanoid in a T-pose or A-pose takes the frozen standing frame through the+ * viewer's own retargeting path. One already authored with its arms down keeps+ * its own stance. A humanoid the clip cannot drive (coverage too low, or the fallen-pose+ * guard rejected it) still gets its arms swung down geometrically, so the result+ * is at worst an arms-down stance, never a T-pose. Anything else is untouched.+ *+ * @param {import('three').Object3D} root the loaded scene (gltf.scene)+ * @param {object|null} poseClipJson output of sampleClipPose()+ * @returns {Promise<ThumbnailPoseResult>}+ */+export async function applyThumbnailPose(root, poseClipJson) {+ if (!root || !poseClipJson) return { posed: false, mode: 'no-pose', restore: () => {} };++ const saved = snapshotTransforms(root);+ const manager = new AnimationManager();+ let restored = false;+ const restore = () => {+ if (restored) return;+ restored = true;+ manager.detach();+ restoreTransforms(root, saved);+ };++ // attach() measures the rest frames, so the rig must read its bind pose here.+ refreshSkinning(root);+ manager.attach(root);+ if (!manager.supportsCanonicalClips()) {+ restore();+ return { posed: false, mode: 'not-humanoid', restore };+ }+ if (armsAlreadyHanging(root)) {+ restore();+ return { posed: false, mode: 'authored-rest', restore };+ }++ // Same order the viewer uses: relax arms the clip cannot reach, then play.+ manager.relaxUndrivenArms();+ manager.injectClip(POSE_CLIP_NAME, poseClipJson);+ const playing = await manager.play(POSE_CLIP_NAME);+ if (playing) {+ manager.update(SETTLE_SECONDS);+ refreshSkinning(root);+ return { posed: true, mode: 'rest', restore };+ }++ // The rig is humanoid but the clip could not drive it. Swing the arms down+ // with no name-mapping gate, which is what a T-pose needs most.+ manager.detach();+ const relaxed = relaxUndrivenArms(root, new Map());+ refreshSkinning(root);+ return { posed: relaxed > 0, mode: relaxed > 0 ? 'arms-relaxed' : 'not-humanoid', restore };+}diff --git a/tests/thumbnail-pose.test.js b/tests/thumbnail-pose.test.jsnew file mode 100644index 000000000..2046a72e1--- /dev/null+++ b/tests/thumbnail-pose.test.js@@ -0,0 +1,259 @@+/**+ * Thumbnail rest pose (src/thumbnail-pose.js): unit tests.+ *+ * Every avatar poster the platform renders (the server's CPU rasterizer, its+ * chromium failover, the browser's offscreen capture) is posed by this module.+ * These tests pin the contract at that seam, against the real pose clip from+ * the motion library rather than a hand-built stand-in:+ * - a T-posed humanoid comes out with its arms hanging, under Mixamo and+ * VRoid bone naming alike, and restore() puts every bone back exactly;+ * - a rig already authored with its arms down, and a non-humanoid rig, are+ * left exactly as authored;+ * - the frozen pose carries joint rotations only (a translation track once+ * launched a centimetre-scale rig a hundred units into the air);+ * - a real Mixamo GLB renders narrower once posed (the arms are no longer+ * spreading the frame), and the CPU lane's cached model is left at bind;+ * - the chromium lane's module map resolves every import the stack makes.+ */++import { describe, it, expect, beforeAll } from 'vitest';+import { readFileSync } from 'node:fs';+import { Bone, BufferGeometry, Float32BufferAttribute, Uint16BufferAttribute, MeshBasicMaterial, Object3D, Skeleton, SkinnedMesh, Vector3 } from 'three';+import { AvatarModel } from '@three-ws/render';+import {+ applyThumbnailPose,+ armsAlreadyHanging,+ sampleClipPose,+ THUMBNAIL_POSE_CLIP,+} from '../src/thumbnail-pose.js';+import { thumbnailPoseClip, thumbnailPoseModules, THUMBNAIL_POSE_SPECIFIER } from '../api/_lib/pose-runtime.js';++const MIXAMO = (n) => `mixamorig${n}`;+const VROID = {+ Hips: 'J_Bip_C_Hips',+ Spine: 'J_Bip_C_Spine',+ Spine1: 'J_Bip_C_Chest',+ Spine2: 'J_Bip_C_UpperChest',+ Neck: 'J_Bip_C_Neck',+ Head: 'J_Bip_C_Head',+ LeftShoulder: 'J_Bip_L_Shoulder',+ LeftArm: 'J_Bip_L_UpperArm',+ LeftForeArm: 'J_Bip_L_LowerArm',+ LeftHand: 'J_Bip_L_Hand',+ RightShoulder: 'J_Bip_R_Shoulder',+ RightArm: 'J_Bip_R_UpperArm',+ RightForeArm: 'J_Bip_R_LowerArm',+ RightHand: 'J_Bip_R_Hand',+ LeftUpLeg: 'J_Bip_L_UpperLeg',+ LeftLeg: 'J_Bip_L_LowerLeg',+ LeftFoot: 'J_Bip_L_Foot',+ RightUpLeg: 'J_Bip_R_UpperLeg',+ RightLeg: 'J_Bip_R_LowerLeg',+ RightFoot: 'J_Bip_R_Foot',+};++const FINGERS = ['Thumb', 'Index', 'Middle', 'Ring', 'Pinky'];+const VROID_FINGER = { Thumb: 'Thumb', Index: 'Index', Middle: 'Middle', Ring: 'Ring', Pinky: 'Little' };+for (const side of ['Left', 'Right']) {+ for (const f of FINGERS) {+ for (const j of [1, 2, 3]) {+ VROID[`${side}Hand${f}${j}`] = `J_Bip_${side[0]}_${VROID_FINGER[f]}${j}`;+ }+ }+}++// A metre-scale humanoid skeleton bound to a skinned mesh, facing +Z with its+// left arm along +X. `armsDown` authors the arms hanging instead of in a T;+// `fingers` gives each hand three-joint fingers, as production rigs carry.+function makeHumanoid(name = MIXAMO, { armsDown = false, fingers = true } = {}) {+ const root = new Object3D();+ const bones = [];+ const bone = (key, parent, x, y, z) => {+ const b = new Bone();+ b.name = typeof name === 'function' ? name(key) : name[key];+ b.position.set(x, y, z);+ if (parent) parent.add(b);+ bones.push(b);+ return b;+ };+ const hips = bone('Hips', null, 0, 1, 0);+ const spine = bone('Spine', hips, 0, 0.1, 0);+ const spine1 = bone('Spine1', spine, 0, 0.12, 0);+ const spine2 = bone('Spine2', spine1, 0, 0.12, 0);+ const neck = bone('Neck', spine2, 0, 0.15, 0);+ bone('Head', neck, 0, 0.1, 0);+ for (const [side, sx] of [['Left', 1], ['Right', -1]]) {+ const shoulder = bone(`${side}Shoulder`, spine2, 0.05 * sx, 0.1, 0);+ const arm = bone(`${side}Arm`, shoulder, 0.1 * sx, 0, 0);+ const fore = armsDown ? bone(`${side}ForeArm`, arm, 0, -0.26, 0) : bone(`${side}ForeArm`, arm, 0.26 * sx, 0, 0);+ const hand = armsDown ? bone(`${side}Hand`, fore, 0, -0.24, 0) : bone(`${side}Hand`, fore, 0.24 * sx, 0, 0);+ if (fingers) {+ FINGERS.forEach((f, k) => {+ let parent = hand;+ for (const j of [1, 2, 3]) {+ parent = armsDown+ ? bone(`${side}Hand${f}${j}`, parent, (k - 2) * 0.01 * sx, -0.03, 0)+ : bone(`${side}Hand${f}${j}`, parent, 0.03 * sx, 0, (k - 2) * 0.01);+ }+ });+ }+ const upLeg = bone(`${side}UpLeg`, hips, 0.09 * sx, -0.05, 0);+ const leg = bone(`${side}Leg`, upLeg, 0, -0.42, 0);+ bone(`${side}Foot`, leg, 0, -0.42, 0);+ }+ root.add(hips);++ // One weighted vertex per bone is enough for a real SkinnedMesh + Skeleton.+ const geometry = new BufferGeometry();+ const positions = [];+ const indices = [];+ const weights = [];+ root.updateMatrixWorld(true);+ bones.forEach((b, i) => {+ const p = b.getWorldPosition(new Vector3());+ positions.push(p.x, p.y, p.z);+ indices.push(i, 0, 0, 0);+ weights.push(1, 0, 0, 0);+ });+ geometry.setAttribute('position', new Float32BufferAttribute(positions, 3));+ geometry.setAttribute('skinIndex', new Uint16BufferAttribute(indices, 4));+ geometry.setAttribute('skinWeight', new Float32BufferAttribute(weights, 4));+ const mesh = new SkinnedMesh(geometry, new MeshBasicMaterial());+ root.add(mesh);+ mesh.bind(new Skeleton(bones));+ root.updateMatrixWorld(true);+ return root;+}++// Unit vector y of shoulder→elbow: about 0 in a T-pose, near -1 hanging.+function armDropY(root, armName, foreArmName) {+ const a = root.getObjectByName(armName).getWorldPosition(new Vector3());+ const b = root.getObjectByName(foreArmName).getWorldPosition(new Vector3());+ return b.sub(a).normalize().y;+}++function snapshot(root) {+ const out = [];+ root.traverse((n) => out.push([n.name, ...n.quaternion.toArray(), ...n.position.toArray()]));+ return out;+}++let poseClip;+beforeAll(async () => {+ poseClip = await thumbnailPoseClip();+});++describe('sampleClipPose', () => {+ it('freezes one instant of the library clip as joint rotations only', () => {+ const source = JSON.parse(readFileSync(`public/animations/clips/${THUMBNAIL_POSE_CLIP}.json`, 'utf8'));+ const frozen = sampleClipPose(source, 0);+ expect(frozen.duration).toBe(1);+ expect(frozen.tracks.length).toBeGreaterThan(20);+ for (const track of frozen.tracks) {+ expect(track.name.endsWith('.quaternion')).toBe(true);+ expect(track.times).toEqual([0, 1]);+ // Two identical keys: the pose holds whatever time the mixer lands on.+ expect(track.values.slice(0, 4)).toEqual(track.values.slice(4, 8));+ }+ // No translation track survives, the hip one included.+ expect(source.tracks.some((t) => t.name.endsWith('.position'))).toBe(true);+ });++ it('wraps the sample time by the clip duration', () => {+ const source = JSON.parse(readFileSync('public/animations/clips/idle.json', 'utf8'));+ const a = sampleClipPose(source, 1);+ const b = sampleClipPose(source, 1 + source.duration);+ expect(b.tracks[0].values).toEqual(a.tracks[0].values);+ });+});++describe('applyThumbnailPose', () => {+ it('drops a T-posed Mixamo rig\'s arms to its sides, and restore() undoes it exactly', async () => {+ const root = makeHumanoid(MIXAMO);+ const before = snapshot(root);+ expect(armDropY(root, 'mixamorigLeftArm', 'mixamorigLeftForeArm')).toBeCloseTo(0, 5);++ const result = await applyThumbnailPose(root, poseClip);+ expect(result).toMatchObject({ posed: true, mode: 'rest' });+ expect(armDropY(root, 'mixamorigLeftArm', 'mixamorigLeftForeArm')).toBeLessThan(-0.8);+ expect(armDropY(root, 'mixamorigRightArm', 'mixamorigRightForeArm')).toBeLessThan(-0.8);+ // Rotations only: the hips stay at the rig's own height.+ expect(root.getObjectByName('mixamorigHips').position.y).toBe(1);++ result.restore();+ expect(snapshot(root)).toEqual(before);+ });++ it('poses a VRoid-named rig through the same canonical mapping', async () => {+ const root = makeHumanoid(VROID);+ const result = await applyThumbnailPose(root, poseClip);+ expect(result).toMatchObject({ posed: true, mode: 'rest' });+ expect(armDropY(root, 'J_Bip_L_UpperArm', 'J_Bip_L_LowerArm')).toBeLessThan(-0.8);+ expect(armDropY(root, 'J_Bip_R_UpperArm', 'J_Bip_R_LowerArm')).toBeLessThan(-0.8);+ });++ it('still lowers the arms of a rig too sparse for the clip (no finger bones)', async () => {+ // Without fingers fewer than half the clip's joints map, so the retarget+ // declines; the geometric fallback must still take the arms out of the T.+ const root = makeHumanoid(MIXAMO, { fingers: false });+ const result = await applyThumbnailPose(root, poseClip);+ expect(result).toMatchObject({ posed: true, mode: 'arms-relaxed' });+ expect(armDropY(root, 'mixamorigLeftArm', 'mixamorigLeftForeArm')).toBeLessThan(-0.8);+ expect(armDropY(root, 'mixamorigRightArm', 'mixamorigRightForeArm')).toBeLessThan(-0.8);+ });++ it('keeps the stance of a rig authored with its arms already down', async () => {+ const root = makeHumanoid(MIXAMO, { armsDown: true });+ expect(armsAlreadyHanging(root)).toBe(true);+ const before = snapshot(root);+ const result = await applyThumbnailPose(root, poseClip);+ expect(result).toMatchObject({ posed: false, mode: 'authored-rest' });+ expect(snapshot(root)).toEqual(before);+ });++ it('leaves a non-humanoid rig exactly as authored', async () => {+ const root = makeHumanoid((key) => `tentacle_${key.length}_${key}`.replace(/(Left|Right|Arm|Leg|Hand|Foot|Hips|Spine|Neck|Head|Shoulder)/g, 'seg'));+ const before = snapshot(root);+ const result = await applyThumbnailPose(root, poseClip);+ expect(result).toMatchObject({ posed: false, mode: 'not-humanoid' });+ expect(snapshot(root)).toEqual(before);+ });++ it('is a no-op without a pose clip', async () => {+ const root = makeHumanoid(MIXAMO);+ const result = await applyThumbnailPose(root, null);+ expect(result).toMatchObject({ posed: false, mode: 'no-pose' });+ });+});++describe('the CPU render lane on a real GLB', () => {+ it('frames a posed Mixamo avatar narrower than its T-pose, then returns it to bind', async () => {+ const bytes = readFileSync('public/avatars/xbot.glb');+ const model = await AvatarModel.load(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));+ const bindWidth = model.bounds.size[0];++ const result = await applyThumbnailPose(model.scene, poseClip);+ expect(result.posed).toBe(true);+ const posedWidth = model.updateBounds().size[0];+ // Arms spread a T-pose to roughly its height; hanging, they span the shoulders.+ expect(posedWidth).toBeLessThan(bindWidth * 0.5);++ result.restore();+ expect(model.updateBounds().size[0]).toBeCloseTo(bindWidth, 4);+ });+});++describe('the chromium lane module map', () => {+ it('ships the whole posing stack with every relative import rewritten to a mapped specifier', () => {+ const modules = thumbnailPoseModules();+ expect(Object.keys(modules)).toContain(THUMBNAIL_POSE_SPECIFIER);+ expect(Object.keys(modules)).toContain('tws/animation-manager.js');+ for (const [specifier, url] of Object.entries(modules)) {+ const code = Buffer.from(url.slice(url.indexOf(',') + 1), 'base64').toString('utf8');+ expect(code, specifier).not.toMatch(/from\s*['"]\.{1,2}\//);+ for (const [, dep] of code.matchAll(/from\s*['"](tws\/[^'"]+)['"]/g)) {+ expect(modules, `${specifier} imports ${dep}`).toHaveProperty([dep]);+ }+ }+ });+});