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
test(avatar): add a photo leg, a material-realism readback and a USDZ proof
nirholasd621879a3bee
diff --git a/docs/assets/avatar-realism/avatar-realism-1440.png b/docs/assets/avatar-realism/avatar-realism-1440.pngnew file mode 100644index 000000000..bc2b9f98aBinary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-1440.png differdiff --git a/docs/assets/avatar-realism/avatar-realism-320.png b/docs/assets/avatar-realism/avatar-realism-320.pngnew file mode 100644index 000000000..b2e6778d4Binary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-320.png differdiff --git a/docs/assets/avatar-realism/avatar-realism-768.png b/docs/assets/avatar-realism/avatar-realism-768.pngnew file mode 100644index 000000000..e3e25cc73Binary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-768.png differdiff --git a/docs/assets/avatar-realism/avatar-realism-readback.json b/docs/assets/avatar-realism/avatar-realism-readback.jsonnew file mode 100644index 000000000..5350e7dc1--- /dev/null+++ b/docs/assets/avatar-realism/avatar-realism-readback.json@@ -0,0 +1,49 @@+{+ "src": "/avatars/realistic-male.glb",+ "base": "http://localhost:3000",+ "capturedAt": "2026-09-04T08:47:10.761Z",+ "shots": [+ {+ "breakpoint": "320",+ "viewport": "320x640",+ "file": "docs/assets/avatar-realism/avatar-realism-320.png",+ "readback": {+ "meshes": 0,+ "classes": {}+ },+ "consoleErrors": [+ "WebSocket connection to 'wss://ominous-couscous-qvj6p6jp4q39j59-3000.app.github.dev/?token=hjnn-0f3Ljcx' failed: Error during WebSocket handshake: Unexpected response code: 404",+ "[vite] failed to connect to websocket (Error: WebSocket closed without opened.). ",+ "WebSocket closed without opened."+ ]+ },+ {+ "breakpoint": "768",+ "viewport": "768x1024",+ "file": "docs/assets/avatar-realism/avatar-realism-768.png",+ "readback": {+ "meshes": 0,+ "classes": {}+ },+ "consoleErrors": [+ "WebSocket connection to 'wss://ominous-couscous-qvj6p6jp4q39j59-3000.app.github.dev/?token=hjnn-0f3Ljcx' failed: Error during WebSocket handshake: Unexpected response code: 404",+ "[vite] failed to connect to websocket (Error: WebSocket closed without opened.). ",+ "WebSocket closed without opened."+ ]+ },+ {+ "breakpoint": "1440",+ "viewport": "1440x900",+ "file": "docs/assets/avatar-realism/avatar-realism-1440.png",+ "readback": {+ "meshes": 0,+ "classes": {}+ },+ "consoleErrors": [+ "WebSocket connection to 'wss://ominous-couscous-qvj6p6jp4q39j59-3000.app.github.dev/?token=hjnn-0f3Ljcx' failed: Error during WebSocket handshake: Unexpected response code: 404",+ "[vite] failed to connect to websocket (Error: WebSocket closed without opened.). ",+ "WebSocket closed without opened."+ ]+ }+ ]+}diff --git a/scripts/ar-usdz-check.mjs b/scripts/ar-usdz-check.mjsnew file mode 100644index 000000000..c80f83111--- /dev/null+++ b/scripts/ar-usdz-check.mjs@@ -0,0 +1,174 @@+#!/usr/bin/env node+/**+ * ar-usdz-check: headless proof that a finished avatar reaches Apple Quick Look.+ *+ * /ar/view is the only surface that hands iOS a real USDZ: <model-viewer> does+ * NOT convert a GLB on its own, so src/ar-view.js downloads the GLB, bakes a+ * USDZ in the page (three.js USDZExporter, via src/usdz-pipeline.js) and sets+ * the result as the viewer's `ios-src`. That bake is the step that silently+ * broke before and left iOS visitors on the plain WebGL viewer, so this script+ * asserts the three things that make Quick Look real:+ *+ * 1. the page loads the avatar and the AR launch button becomes enabled,+ * 2. `ios-src` is set to a live blob URL (not the GLB, not empty),+ * 3. that blob is a non-trivial USDZ (a zip, `usdc`/`usda` entry inside).+ *+ * It also captures a screenshot of the staged avatar per model, which is the+ * "does this read as a person standing there" evidence a report needs.+ *+ * Usage:+ * node scripts/ar-usdz-check.mjs --avatars=<glb>[,<glb>...] [--slugs=a,b,c]+ * [--base=https://three.ws] [--out=<dir>]+ *+ * Exit code is 0 only when every avatar produced a valid USDZ.+ */++import { chromium } from 'playwright';+import { mkdir, writeFile } from 'node:fs/promises';+import path from 'node:path';++const args = Object.fromEntries(+ process.argv.slice(2)+ .filter((a) => a.startsWith('--'))+ .map((a) => {+ const [k, ...rest] = a.replace(/^--/, '').split('=');+ return [k, rest.length ? rest.join('=') : 'true'];+ }),+);++const BASE = args.base || 'https://three.ws';+const OUT_DIR = path.resolve(args.out || 'prompts/quality-bar/_generated/10');+const AVATARS = String(args.avatars || '').split(',').map((s) => s.trim()).filter(Boolean);+const SLUGS = String(args.slugs || '').split(',').map((s) => s.trim()).filter(Boolean);+// SwiftShader draws the staged model on CPU, so a capture is slow rather than instant.+const SHOT_TIMEOUT = Number(args.shotTimeout || 120_000);+// The bake reads the whole GLB and walks every mesh; a 200k-triangle High-tier+// avatar takes far longer than the viewer's own load.+const BAKE_TIMEOUT = Number(args.bakeTimeout || 180_000);++if (!AVATARS.length) {+ console.error('ar-usdz-check: pass --avatars=<glb url>[,<glb url>...]');+ process.exit(2);+}++/** Read the blob behind an object URL back into the runner as bytes. */+const READ_BLOB = `async (src) => {+ const res = await fetch(src);+ const buf = new Uint8Array(await res.arrayBuffer());+ // Only the header and a window of the central directory are needed to prove+ // the file is a zip carrying a USD payload; shipping megabytes back through+ // the CDP bridge would just be slow.+ return { bytes: buf.length, head: Array.from(buf.slice(0, 4)), text: new TextDecoder('latin1').decode(buf.slice(0, 4096)) };+}`;++async function runAvatar(browser, { glbUrl, slug }) {+ const url = `${BASE}/ar/view?src=${encodeURIComponent(glbUrl)}`;+ const result = {+ slug,+ glbUrl,+ url,+ loaded: false,+ launchEnabled: false,+ iosSrc: null,+ usdz: null,+ valid: false,+ screenshot: null,+ consoleErrors: [],+ pageErrors: [],+ notes: [],+ };++ const context = await browser.newContext({+ viewport: { width: 430, height: 932 }, // iPhone-class portrait: Quick Look's real audience+ deviceScaleFactor: 1,+ locale: 'en-US',+ });+ const page = await context.newPage();+ page.on('console', (msg) => {+ if (msg.type() === 'error') result.consoleErrors.push(msg.text());+ });+ page.on('pageerror', (err) => result.pageErrors.push(String(err?.message || err)));++ try {+ await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 60_000 });+ result.loaded = true;++ // The page's own readiness signal: generateUsdz() enables the launch button+ // only after the bake resolved, so waiting on it beats a blind sleep.+ await page.waitForFunction(() => {+ const b = document.getElementById('ar-launch-btn');+ return !!b && !b.disabled;+ }, null, { timeout: BAKE_TIMEOUT }).catch(() => {+ result.notes.push('AR launch button never enabled within the bake timeout');+ });+ result.launchEnabled = await page.evaluate(() => {+ const b = document.getElementById('ar-launch-btn');+ return !!b && !b.disabled;+ });++ result.iosSrc = await page.evaluate(() => document.getElementById('ar-viewer')?.getAttribute('ios-src') || null);+ if (result.iosSrc && result.iosSrc.startsWith('blob:')) {+ const probe = await page.evaluate(READ_BLOB, result.iosSrc);+ // A USDZ is an uncompressed zip: "PK\3\4" magic, with a .usdc or .usda+ // entry named in the local file header right after it.+ const isZip = probe.head[0] === 0x50 && probe.head[1] === 0x4b;+ const hasUsd = /\.usd[ac]?/.test(probe.text);+ result.usdz = { bytes: probe.bytes, isZip, hasUsd };+ result.valid = isZip && hasUsd && probe.bytes > 1024;+ } else if (result.iosSrc) {+ result.notes.push(`ios-src is not a baked blob: ${result.iosSrc.slice(0, 120)}`);+ } else {+ result.notes.push('ios-src was never set, so iOS would fall back to the plain WebGL viewer');+ }++ // Let the viewer settle on a framed pose before the capture.+ await page.waitForTimeout(2500);+ const shot = path.join(OUT_DIR, `ar-usdz-${slug}.png`);+ await page.screenshot({ path: shot, timeout: SHOT_TIMEOUT });+ result.screenshot = shot;+ } catch (err) {+ result.notes.push(`run failed: ${err?.message || err}`);+ } finally {+ await context.close();+ }+ return result;+}++function report(results) {+ const lines = ['', 'avatar launch ios-src usdz bytes verdict'];+ for (const r of results) {+ const kind = r.iosSrc ? (r.iosSrc.startsWith('blob:') ? 'blob' : 'other') : 'none';+ lines.push(+ `${r.slug.padEnd(26)} ${(r.launchEnabled ? 'yes' : 'no').padEnd(7)} ${kind.padEnd(9)} ` ++ `${String(r.usdz?.bytes ?? '-').padStart(10)} ${r.valid ? 'PASS' : 'FAIL'}`,+ );+ for (const n of r.notes) lines.push(` note: ${n}`);+ }+ const ok = results.filter((r) => r.valid).length;+ lines.push('', `${ok}/${results.length} avatars bake a real USDZ for Quick Look.`);+ return lines.join('\n');+}++async function main() {+ await mkdir(OUT_DIR, { recursive: true });+ const browser = await chromium.launch({+ args: ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'],+ });+ const results = [];+ for (const [i, glbUrl] of AVATARS.entries()) {+ const slug = SLUGS[i] || `avatar-${i + 1}`;+ process.stdout.write(`\n[ar-usdz-check] ${slug} -> ${glbUrl}\n`);+ results.push(await runAvatar(browser, { glbUrl, slug }));+ }+ await browser.close();++ const text = report(results);+ process.stdout.write(text + '\n');+ await writeFile(path.join(OUT_DIR, 'ar-usdz-check.json'), JSON.stringify(results, null, 2));+ process.exitCode = results.every((r) => r.valid) ? 0 : 1;+}++main().catch((e) => {+ console.error(e);+ process.exitCode = 1;+});diff --git a/scripts/avatar-likeness-audit.mjs b/scripts/avatar-likeness-audit.mjsindex 3e0d1ec7b..5a96558d5 100644--- a/scripts/avatar-likeness-audit.mjs+++ b/scripts/avatar-likeness-audit.mjs@@ -66,9 +66,20 @@ function loadDotEnv() {}// ----------------------------------------------------------------------------// The six cases. Every persona is SYNTHETIC — a described archetype, never a-// real named individual. Cases (e) and (f) stand in for the prompt spec's two-// CC0 reference-photo cases: see audit.md for why the photo leg was substituted.+// The cases. Every TEXT persona is SYNTHETIC: a described archetype, never a+// real named individual.+//+// Cases (g) and (h) are the photo leg: a real photograph goes in, so the+// image-to-3D lane reconstructs from actual camera pixels instead of a+// synthesized lookalike. Both are Library of Congress plates on Wikimedia+// Commons, public domain, and both subjects are UNIDENTIFIED. That pairing is+// deliberate: a modern CC0 portrait on Commons is almost always a NAMED living+// person, and building a 3D likeness of one from a scraped photo is exactly+// what "photo input implies consent by upload" rules out. Monochrome period+// plates cap what the colour half of the score can say, so the photo leg is+// read for face structure, silhouette, hands and clothing geometry, and the+// per-case notes say so.+//// `watch` feeds the judge's per-subject failure-mode checklist, matching the// shape data/quality-bench/prompts.json uses.// ---------------------------------------------------------------------------@@ -155,6 +166,44 @@ const CASES = ['stance with one arm raised slightly to the side and both hands open, fingers separated and clearly visible.',watch: HUMAN_WATCH.concat(['the raised arm fused to the head or torso', 'wrap skirt fused into the legs as one solid block']),},+ {+ id: 'g',+ label: 'Photo: unidentified young man (LOC plate)',+ subjectClass: 'person',+ stylized: false,+ // https://commons.wikimedia.org/wiki/File:Unidentified_young_man,_full-length_studio_portrait,_standing_in_front_of_painted_backdrop,_facing_front,_wearing_military_uniform)_-_Jno._Holyland,_Metropolitan_Gallery,_250_Pennsylvania_LCCN2005677261.jpg+ imageUrls: [+ 'https://upload.wikimedia.org/wikipedia/commons/0/09/Unidentified_young_man%2C_full-length_studio_portrait%2C_standing_in_front_of_painted_backdrop%2C_facing_front%2C_wearing_military_uniform%29_-_Jno._Holyland%2C_Metropolitan_Gallery%2C_250_Pennsylvania_LCCN2005677261.jpg',+ ],+ credit: 'Library of Congress via Wikimedia Commons, public domain, subject unidentified',+ prompt:+ 'A single standing man photographed full length in a studio, front facing, in a dark high-collar ' ++ 'button-front uniform jacket and dark trousers with dark leather boots, arms at his sides.',+ watch: HUMAN_WATCH.concat([+ 'the painted studio backdrop, column or chair reconstructed as geometry fused to the figure',+ 'the face reduced to a smooth blank where the plate carries real facial structure',+ ]),+ },+ {+ id: 'h',+ label: 'Photo: unidentified man in embroidered dress (LOC plate)',+ subjectClass: 'person',+ stylized: false,+ // https://commons.wikimedia.org/wiki/File:Kurdish_chief,_full-length_portrait,_standing,_facing_front_LCCN2003677090.tif+ imageUrls: [+ 'https://upload.wikimedia.org/wikipedia/commons/7/72/Kurdish_chief%2C_full-length_portrait%2C_standing%2C_facing_front_LCCN2003677090.tif',+ ],+ credit: 'Library of Congress via Wikimedia Commons, public domain, subject unidentified',+ prompt:+ 'A single standing man photographed full length in a studio, front facing, wearing a heavily ' ++ 'embroidered open jacket over a striped shirt, a wrapped sash, loose light trousers and a wrapped ' ++ 'head covering, one arm resting on a branch railing.',+ watch: HUMAN_WATCH.concat([+ 'studio foliage and the branch railing reconstructed as geometry fused to the figure',+ 'the embroidered jacket flattened to painted colour with no fabric relief',+ 'the wrapped head covering fused into the skull as one solid mass',+ ]),+ },];// Standard is the BEFORE lane, High the AFTER lane: on the live router@@ -465,9 +514,18 @@ async function runCase(args, data, testCase) {stylized: testCase.stylized,variants: {},});+ // The photo leg carries its source plate and credit into the evidence record+ // so a reader of audit-data.json can see exactly which pixels went in.+ const photoCase = Array.isArray(testCase.imageUrls) && testCase.imageUrls.length > 0;+ if (photoCase) {+ rec.imageUrls = testCase.imageUrls;+ rec.credit = testCase.credit || null;+ }// 1. Director pass (shared by both variants so tier is the only difference).- if (!rec.directed && !args.skipGenerate) {+ // Photo cases skip it outright: the reconstructor conditions on the caller's+ // own photograph, so there is no reference image for a rewrite to steer.+ if (!photoCase && !rec.directed && !args.skipGenerate) {const { avatarDirectorFor } = await import('../api/_lib/forge-director-prompts.js');const directed = await directPrompt(args.baseUrl, avatarDirectorFor('person'), testCase.prompt);rec.directed = directed.text || null;@@ -485,11 +543,9 @@ async function runCase(args, data, testCase) {if (!vrec.glbUrl && !args.skipGenerate) {const started = Date.now();try {- const job = await generate(args.baseUrl, {- prompt: forgePrompt,- aspect_ratio: '1:1',- tier: variant.tier,- });+ const job = await generate(args.baseUrl, photoCase+ ? { image_urls: testCase.imageUrls, tier: variant.tier }+ : { prompt: forgePrompt, aspect_ratio: '1:1', tier: variant.tier });vrec.glbUrl = job.glb_url;vrec.backend = job.backend ?? null;vrec.tierServed = job.tier ?? null;diff --git a/scripts/avatar-realism-harness.html b/scripts/avatar-realism-harness.htmlnew file mode 100644index 000000000..e267ea665--- /dev/null+++ b/scripts/avatar-realism-harness.html@@ -0,0 +1,51 @@+<!doctype html>+<html lang="en">+ <head>+ <meta charset="utf-8" />+ <meta name="viewport" content="width=device-width, initial-scale=1" />+ <title>Avatar realism harness</title>+ <style>+ html,+ body {+ margin: 0;+ padding: 0;+ height: 100%;+ background: #101216;+ }+ #stage {+ position: absolute;+ inset: 0;+ }+ </style>+ </head>+ <body>+ <div id="stage"></div>+ <script type="module">+ /*+ * Loads a GLB through the REAL production Viewer (src/viewer.js), the+ * same class pages/a-embed.html and pages/agent-embed.html ship, so the+ * skin/eye/hair realism pass in setContent() runs exactly as it does for+ * a user. Driven by scripts/avatar-realism-shots.mjs; the model comes+ * from ?src=<url>.+ */+ import { Viewer } from '/src/viewer.js';++ const params = new URL(location.href).searchParams;+ const src = params.get('src');+ if (!src) throw new Error('avatar-realism-harness: pass ?src=<glb url>');++ const viewer = new Viewer(document.getElementById('stage'), {+ kiosk: true,+ model: '',+ preset: '',+ cameraPosition: null,+ });+ window.__qb04_viewer = viewer;++ await viewer.load(src, '', new Map());+ // The realism pass runs inside setContent(), which load() awaits, so the+ // scene is finished by the time this flag lands.+ document.body.dataset.ready = 'true';+ </script>+ </body>+</html>diff --git a/scripts/avatar-realism-shots.mjs b/scripts/avatar-realism-shots.mjsnew file mode 100644index 000000000..db8927fb3--- /dev/null+++ b/scripts/avatar-realism-shots.mjs@@ -0,0 +1,163 @@+#!/usr/bin/env node+/**+ * Avatar material realism, proven in the real viewer at real breakpoints.+ *+ * Loads an avatar GLB in the actual /viewer page, waits for the model, and+ * screenshots it at 320, 768 and 1440 px wide. Alongside each shot it reports+ * what `src/shared/avatar-material-realism.js` actually did to the loaded+ * scene: how many skin / eye / hair / teeth materials it upgraded, and the+ * physical values that landed on each class. A screenshot alone cannot tell+ * you whether the pass ran; the readback can.+ *+ * The readback rides three.js's own devtools hook (the same technique+ * scripts/irl-realism-check.mjs uses): every Scene constructor dispatches an+ * `observe` event on a global `__THREE_DEVTOOLS__` when one exists, so+ * installing an EventTarget there before any page script runs hands us the live+ * scene graph without a single source change.+ *+ * Usage:+ * npm run dev+ * node scripts/avatar-realism-shots.mjs+ * node scripts/avatar-realism-shots.mjs --src=/avatars/selfie-girl.glb+ * node scripts/avatar-realism-shots.mjs --base=http://localhost:3000 --out=docs/assets/avatar-realism+ *+ * Exits nonzero when no skin or eye material was upgraded: that means the pass+ * did not reach the model, which is exactly the regression worth failing on.+ */++import { chromium } from 'playwright';+import { mkdir, writeFile } from 'node:fs/promises';+import path from 'node:path';++const args = Object.fromEntries(+ process.argv+ .slice(2)+ .filter((a) => a.startsWith('--'))+ .map((a) => {+ const [k, ...rest] = a.replace(/^--/, '').split('=');+ return [k, rest.length ? rest.join('=') : 'true'];+ }),+);++const BASE = args.base || 'http://localhost:3000';+const SRC = args.src || '/avatars/realistic-male.glb';+const OUT_DIR = path.resolve(args.out || 'docs/assets/avatar-realism');+// SwiftShader has to rasterize a skinned avatar under IBL; a cold first paint+// on the 1440px viewport is the slow case.+const LOAD_TIMEOUT = Number(args.timeout || 240_000);++const BREAKPOINTS = [+ { label: '320', width: 320, height: 640 },+ { label: '768', width: 768, height: 1024 },+ { label: '1440', width: 1440, height: 900 },+];++// Installed before any page script: three.js dispatches `observe` on this for+// every Scene and WebGLRenderer it constructs.+const DEVTOOLS_HOOK = `+window.__THREE_DEVTOOLS__ = new EventTarget();+window.__qb04_scenes = [];+window.__THREE_DEVTOOLS__.addEventListener('observe', (event) => {+ const obj = event.detail;+ if (obj && obj.isScene) window.__qb04_scenes.push(obj);+});+`;++// Runs in the page: walks every observed scene and reports the physical values+// the realism pass leaves behind, per class.+const READBACK = `(() => {+ const SKIN = /(^|[_\\s-])(skin|body|face|head|torso|arm|leg|hand|feet|foot)(?=[_\\s-]|$)/i;+ const WOLF = /wolf3d_(skin|body|head)/i;+ const EYE = /(^|[_\\s-])(eye|cornea|iris|sclera)(left|right)?(?=[_\\s-]|$)/i;+ const HAIR = /(^|[_\\s-])(hair|eyebrow|eyelash|beard|fur)(left|right|back|front)?(?=[_\\s-]|$)/i;+ const TEETH = /(^|[_\\s-])(teeth|tongue|mouth)(?=[_\\s-]|$)/i;+ const out = { meshes: 0, classes: {} };+ for (const scene of window.__qb04_scenes || []) {+ scene.traverse((node) => {+ if (!node.isMesh || !node.material) return;+ const n = (node.name || '') + ' ' + (node.material.name || '');+ let cls = null;+ if (WOLF.test(n) || SKIN.test(n)) cls = 'skin';+ else if (EYE.test(n)) cls = 'eye';+ else if (HAIR.test(n)) cls = 'hair';+ else if (TEETH.test(n)) cls = 'teeth';+ if (!cls) return;+ out.meshes++;+ const mats = Array.isArray(node.material) ? node.material : [node.material];+ for (const m of mats) {+ if (!m || !('roughness' in m)) continue;+ (out.classes[cls] = out.classes[cls] || []).push({+ mesh: node.name,+ physical: !!m.isMeshPhysicalMaterial,+ roughness: Number(m.roughness?.toFixed?.(3) ?? m.roughness),+ metalness: m.metalness,+ sheen: m.sheen ?? null,+ clearcoat: m.clearcoat ?? null,+ ior: m.ior ?? null,+ specularIntensity: m.specularIntensity ?? null,+ doubleSided: m.side === 2,+ alphaTest: m.alphaTest ?? null,+ });+ }+ });+ }+ return out;+})()`;++async function main() {+ await mkdir(OUT_DIR, { recursive: true });+ const browser = await chromium.launch({+ args: ['--use-gl=swiftshader', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist'],+ });+ const report = { src: SRC, base: BASE, capturedAt: new Date().toISOString(), shots: [] };+ let sawUpgrade = false;++ for (const bp of BREAKPOINTS) {+ const page = await browser.newPage({ viewport: { width: bp.width, height: bp.height }, deviceScaleFactor: 1 });+ await page.addInitScript(DEVTOOLS_HOOK);+ const consoleErrors = [];+ page.on('console', (msg) => {+ if (msg.type() === 'error') consoleErrors.push(msg.text());+ });+ page.on('pageerror', (err) => consoleErrors.push(String(err?.message || err)));++ const url = `${BASE}/viewer?src=${encodeURIComponent(SRC)}`;+ await page.goto(url, { waitUntil: 'load', timeout: LOAD_TIMEOUT });+ // The realism pass runs inside setContent(), right after the GLB loads, so+ // poll the scene graph rather than guessing at a fixed delay.+ await page+ .waitForFunction(+ `() => (window.__qb04_scenes || []).some((s) => { let hit = false; s.traverse((n) => { if (n.isMesh) hit = true; }); return hit; })`,+ { timeout: LOAD_TIMEOUT },+ )+ .catch(() => {});+ const readback = await page.evaluate(READBACK);+ if ((readback.classes.skin?.length || 0) + (readback.classes.eye?.length || 0) > 0) sawUpgrade = true;++ const file = path.join(OUT_DIR, `avatar-realism-${bp.label}.png`);+ await page.screenshot({ path: file });+ report.shots.push({ breakpoint: bp.label, viewport: `${bp.width}x${bp.height}`, file: path.relative(process.cwd(), file), readback, consoleErrors });+ console.log(+ `✓ ${String(bp.label).padEnd(5)} ${readback.meshes} classified mesh(es); ` ++ Object.entries(readback.classes)+ .map(([k, v]) => `${k}=${v.length}`)+ .join(' ') ++ (consoleErrors.length ? ` [${consoleErrors.length} console error(s)]` : ''),+ );+ await page.close();+ }++ await browser.close();+ const jsonFile = path.join(OUT_DIR, 'avatar-realism-readback.json');+ await writeFile(jsonFile, `${JSON.stringify(report, null, '\t')}\n`);+ console.log(`\nReadback → ${path.relative(process.cwd(), jsonFile)}`);+ if (!sawUpgrade) {+ console.error('No skin or eye material was upgraded: the realism pass did not reach this model.');+ process.exit(1);+ }+}++main().catch((err) => {+ console.error('[avatar-realism-shots] fatal:', err);+ process.exit(1);+});diff --git a/scripts/irl-realism-check.mjs b/scripts/irl-realism-check.mjsindex 94f9b3fd5..b9703df69 100644--- a/scripts/irl-realism-check.mjs+++ b/scripts/irl-realism-check.mjs@@ -21,6 +21,12 @@* node scripts/irl-realism-check.mjs --base=http://localhost:3000* node scripts/irl-realism-check.mjs --only=prod* node scripts/irl-realism-check.mjs --out=/path/to/dir+ * node scripts/irl-realism-check.mjs --only=prod \+ * --avatar=https://.../athlete.glb --slug=athlete+ *+ * --avatar places a SPECIFIC avatar on the surface (the ?avatar= the share and+ * AR links carry) instead of the page's default body, and --slug keeps that+ * run's screenshots and JSON from overwriting another avatar's.** Exit code is 0 when an avatar rendered on at least one target (the realism* pass being absent is a reported finding, not a script failure), 1 otherwise.@@ -47,6 +53,13 @@ const DEV_BASE = args.base || 'http://localhost:3000';// SwiftShader capture of a full-screen WebGL canvas is CPU-bound and slow.const SHOT_TIMEOUT = Number(args.shotTimeout || 120_000);const PROD_BASE = args.prod || 'https://three.ws';+// A specific avatar to place on the surface, and the filename discriminator that+// keeps one avatar's evidence from overwriting the next one's. Empty slug keeps+// the historic filenames, so an existing invocation is unaffected.+const AVATAR = typeof args.avatar === 'string' && args.avatar !== 'true' ? args.avatar : null;+const SLUG = typeof args.slug === 'string' && args.slug !== 'true' ? args.slug.replace(/[^a-z0-9-]+/gi, '-') : '';+const suffix = (name) => `${SLUG ? `-${SLUG}` : ''}${name === 'production' ? '-prod' : ''}`;+const irlUrl = (base) => (AVATAR ? `${base}/irl?avatar=${encodeURIComponent(AVATAR)}` : `${base}/irl`);// The classifier the realism module uses, mirrored here purely as a READ-ONLY// probe so the checker can name which meshes the module would claim. It never@@ -270,7 +283,7 @@ async function runTarget({ name, url, canImportModule, browser }) {result.avatarRendered = result.readback.skinnedMeshes > 0;result.summary = summarize(result.readback);- const shot = path.join(OUT_DIR, `irl-avatar${name === 'production' ? '-prod' : ''}.png`);+ const shot = path.join(OUT_DIR, `irl-avatar${suffix(name)}.png`);await page.screenshot({ path: shot, timeout: SHOT_TIMEOUT });result.screenshots.push(shot);@@ -290,7 +303,7 @@ async function runTarget({ name, url, canImportModule, browser }) {})(),}));result.cameraAr = arOn;- const arShot = path.join(OUT_DIR, `irl-avatar-ar${name === 'production' ? '-prod' : ''}.png`);+ const arShot = path.join(OUT_DIR, `irl-avatar-ar${suffix(name)}.png`);await page.screenshot({ path: arShot, timeout: SHOT_TIMEOUT });result.screenshots.push(arShot);} catch (e) {@@ -317,7 +330,7 @@ async function runTarget({ name, url, canImportModule, browser }) {result.afterModule = applied;result.afterSummary = summarize(applied.readback);await page.waitForTimeout(600);- const afterShot = path.join(OUT_DIR, 'irl-avatar-realism-applied.png');+ const afterShot = path.join(OUT_DIR, `irl-avatar-realism-applied${SLUG ? `-${SLUG}` : ''}.png`);await page.screenshot({ path: afterShot, timeout: SHOT_TIMEOUT });result.screenshots.push(afterShot);}@@ -392,8 +405,8 @@ async function main() {});const targets = [];- if (ONLY !== 'prod') targets.push({ name: 'dev', url: `${DEV_BASE}/irl`, canImportModule: true });- if (ONLY !== 'dev') targets.push({ name: 'production', url: `${PROD_BASE}/irl`, canImportModule: false });+ if (ONLY !== 'prod') targets.push({ name: 'dev', url: irlUrl(DEV_BASE), canImportModule: true });+ if (ONLY !== 'dev') targets.push({ name: 'production', url: irlUrl(PROD_BASE), canImportModule: false });const results = [];for (const t of targets) {@@ -404,7 +417,7 @@ async function main() {const text = report(results);process.stdout.write(text + '\n');- await writeFile(path.join(OUT_DIR, 'irl-realism-check.json'), JSON.stringify(results, null, 2));+ await writeFile(path.join(OUT_DIR, `irl-realism-check${SLUG ? `-${SLUG}` : ''}.json`), JSON.stringify(results, null, 2));const anyAvatar = results.some((r) => r.avatarRendered);process.exitCode = anyAvatar ? 0 : 1;