Skip to content

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.

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.png
new file mode 100644
index 000000000..bc2b9f98a
Binary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-1440.png differ
diff --git a/docs/assets/avatar-realism/avatar-realism-320.png b/docs/assets/avatar-realism/avatar-realism-320.png
new file mode 100644
index 000000000..b2e6778d4
Binary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-320.png differ
diff --git a/docs/assets/avatar-realism/avatar-realism-768.png b/docs/assets/avatar-realism/avatar-realism-768.png
new file mode 100644
index 000000000..e3e25cc73
Binary files /dev/null and b/docs/assets/avatar-realism/avatar-realism-768.png differ
diff --git a/docs/assets/avatar-realism/avatar-realism-readback.json b/docs/assets/avatar-realism/avatar-realism-readback.json
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.html
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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;