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.

tools(scripts): add the GLB PBR channel inspector and the generation-suite probe

nirholas2831eb597424
diff --git a/scripts/inspect-glb-materials.mjs b/scripts/inspect-glb-materials.mjs
new file mode 100755
index 000000000..d6fd8e6d2
--- /dev/null
+++ b/scripts/inspect-glb-materials.mjs
@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+/**
+ * PBR channel inspector for GLB files.
+ *
+ * Answers one question per model: which of the five glTF PBR texture channels
+ * does this material actually carry, at what resolution, and which material
+ * extensions ride along? A mesh can be geometrically perfect and still read as
+ * plastic because the lane that produced it baked a baseColor atlas and nothing
+ * else, so every surface reflects the viewer's IBL identically. This script is
+ * how that gap is measured rather than guessed.
+ *
+ * node scripts/inspect-glb-materials.mjs model.glb
+ * node scripts/inspect-glb-materials.mjs https://.../a.glb https://.../b.glb
+ * node scripts/inspect-glb-materials.mjs --matrix --label=trellis a.glb --label=hunyuan b.glb
+ * node scripts/inspect-glb-materials.mjs --json model.glb > channels.json
+ *
+ * `--matrix` prints the markdown lane table that lives in
+ * workers/texture/README.md; `--json` prints the same data as a machine-readable
+ * document for a test or a report to consume. Exit code is 1 when any inspected
+ * model is missing a channel that its own materials imply it should have (a
+ * metal with no metallicRoughness map, a textured surface with no normal), so
+ * this doubles as a regression gate in CI.
+ *
+ * Reads with @gltf-transform and sharp, both already in the dependency tree.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import { Buffer } from 'node:buffer';
+import { NodeIO } from '@gltf-transform/core';
+import { ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import { MeshoptDecoder } from 'meshoptimizer';
+import sharp from 'sharp';
+
+// The five texture slots glTF 2.0 defines on a metallic-roughness material, in
+// the order a reader cares about them: what colour is it, what shape is the
+// surface, how does it reflect, where is it occluded, does it glow.
+const CHANNELS = Object.freeze([
+ { key: 'baseColor', label: 'baseColor', get: (m) => m.getBaseColorTexture() },
+ { key: 'normal', label: 'normal', get: (m) => m.getNormalTexture() },
+ { key: 'metallicRoughness', label: 'metallicRoughness', get: (m) => m.getMetallicRoughnessTexture() },
+ { key: 'occlusion', label: 'occlusion', get: (m) => m.getOcclusionTexture() },
+ { key: 'emissive', label: 'emissive', get: (m) => m.getEmissiveTexture() },
+]);
+
+function parseArgs(argv) {
+ const args = { inputs: [], json: false, matrix: false, strict: true };
+ let pendingLabel = null;
+ for (const raw of argv) {
+ if (raw === '--json') args.json = true;
+ else if (raw === '--matrix') args.matrix = true;
+ else if (raw === '--no-strict') args.strict = false;
+ else if (raw.startsWith('--label=')) pendingLabel = raw.slice('--label='.length);
+ else if (raw.startsWith('--')) throw new Error(`unknown flag ${raw}`);
+ else {
+ args.inputs.push({ source: raw, label: pendingLabel || defaultLabel(raw) });
+ pendingLabel = null;
+ }
+ }
+ return args;
+}
+
+function defaultLabel(source) {
+ try {
+ if (/^https?:\/\//i.test(source)) return basename(new URL(source).pathname) || source;
+ } catch {
+ return source;
+ }
+ return basename(source);
+}
+
+/** Fetch a remote GLB or read a local one. Remote failures name the status. */
+async function loadBytes(source) {
+ if (/^https?:\/\//i.test(source)) {
+ const res = await fetch(source, { redirect: 'follow' });
+ if (!res.ok) throw new Error(`${source} returned HTTP ${res.status}`);
+ return Buffer.from(await res.arrayBuffer());
+ }
+ return readFile(resolve(source));
+}
+
+/**
+ * Texture dimensions. glTF stores image bytes without a declared size, so the
+ * only honest answer comes from decoding the header; sharp does that without
+ * decompressing the pixels.
+ */
+async function textureInfo(texture) {
+ if (!texture) return null;
+ const image = texture.getImage();
+ const mimeType = texture.getMimeType() || 'unknown';
+ const bytes = image ? image.byteLength : 0;
+ if (!image) return { present: true, width: null, height: null, mimeType, bytes };
+ try {
+ const meta = await sharp(Buffer.from(image)).metadata();
+ return { present: true, width: meta.width ?? null, height: meta.height ?? null, mimeType, bytes };
+ } catch {
+ // An encoding sharp cannot parse (KTX2, a truncated buffer) still counts
+ // as a present channel; only its resolution is unknown.
+ return { present: true, width: null, height: null, mimeType, bytes };
+ }
+}
+
+function resolutionOf(info) {
+ if (!info) return null;
+ if (info.width && info.height) return `${info.width}x${info.height}`;
+ return 'unknown';
+}
+
+/**
+ * Channels a material *should* carry, given what it already declares. A flat
+ * untextured colour swatch needs nothing; the moment a material carries a
+ * baseColor atlas, the absence of a normal map is a real defect rather than a
+ * style choice, and a non-zero metalness with no metallicRoughness map means
+ * every texel reflects identically.
+ */
+function expectedGaps(material, channels) {
+ const gaps = [];
+ if (!channels.baseColor?.present) return gaps; // untextured material: nothing implied
+ if (!channels.normal?.present) gaps.push('normal');
+ if (!channels.metallicRoughness?.present) gaps.push('metallicRoughness');
+ if (!channels.occlusion?.present) gaps.push('occlusion');
+ return gaps;
+}
+
+async function inspectOne({ source, label }) {
+ const bytes = await loadBytes(source);
+ const io = new NodeIO()
+ .registerExtensions(ALL_EXTENSIONS)
+ .registerDependencies({ 'meshopt.decoder': MeshoptDecoder });
+ await MeshoptDecoder.ready;
+ const doc = await io.readBinary(new Uint8Array(bytes));
+ const root = doc.getRoot();
+ const materials = [];
+
+ for (const material of root.listMaterials()) {
+ const channels = {};
+ for (const ch of CHANNELS) channels[ch.key] = await textureInfo(ch.get(material));
+ materials.push({
+ name: material.getName() || '(unnamed)',
+ metallicFactor: material.getMetallicFactor(),
+ roughnessFactor: material.getRoughnessFactor(),
+ alphaMode: material.getAlphaMode(),
+ doubleSided: material.getDoubleSided(),
+ extensions: material.listExtensions().map((e) => e.extensionName).sort(),
+ channels,
+ gaps: expectedGaps(material, channels),
+ });
+ }
+
+ // A primitive with no material takes glTF's default material, whose
+ // metallicFactor and roughnessFactor are both 1.0 — it renders as rough bare
+ // metal. Counting these separately matters because such a model reports
+ // "0 materials" rather than "1 broken material".
+ let unmaterialed = 0;
+ for (const mesh of root.listMeshes()) {
+ for (const prim of mesh.listPrimitives()) if (!prim.getMaterial()) unmaterialed++;
+ }
+
+ return {
+ label,
+ source,
+ bytes: bytes.byteLength,
+ extensionsUsed: root.listExtensionsUsed().map((e) => e.extensionName).sort(),
+ materialCount: materials.length,
+ unmaterialedPrimitives: unmaterialed,
+ materials,
+ };
+}
+
+function tick(info) {
+ if (!info?.present) return 'no';
+ const res = resolutionOf(info);
+ return res === 'unknown' ? 'yes' : res;
+}
+
+function printReport(report) {
+ console.log(`\n${report.label}`);
+ console.log('-'.repeat(report.label.length));
+ console.log(` source ${report.source}`);
+ console.log(` size ${(report.bytes / 1024).toFixed(1)} KiB`);
+ console.log(` extensions ${report.extensionsUsed.join(', ') || '(none)'}`);
+ if (report.unmaterialedPrimitives > 0) {
+ console.log(` WARNING ${report.unmaterialedPrimitives} primitive(s) with no material (render as rough metal)`);
+ }
+ if (report.materialCount === 0) {
+ console.log(' materials (none)');
+ return;
+ }
+ for (const m of report.materials) {
+ console.log(`\n material "${m.name}"`);
+ console.log(` metallic ${m.metallicFactor.toFixed(2)} roughness ${m.roughnessFactor.toFixed(2)} alpha ${m.alphaMode} doubleSided ${m.doubleSided}`);
+ for (const ch of CHANNELS) {
+ const info = m.channels[ch.key];
+ const mime = info?.present ? ` ${info.mimeType} ${(info.bytes / 1024).toFixed(1)} KiB` : '';
+ console.log(` ${ch.label.padEnd(18)} ${tick(info).padEnd(12)}${mime}`);
+ }
+ console.log(` extensions ${m.extensions.join(', ') || '(none)'}`);
+ if (m.gaps.length) console.log(` MISSING ${m.gaps.join(', ')}`);
+ }
+}
+
+/** The markdown lane table that ships in workers/texture/README.md. */
+function printMatrix(reports) {
+ const header = ['Lane / model', ...CHANNELS.map((c) => c.label), 'Extensions'];
+ const rows = reports.map((r) => {
+ // One row per model, collapsing its materials: a channel counts as
+ // present only when EVERY material carries it, because a model whose hair
+ // has a normal map and whose skin does not still renders a flat face.
+ const cells = CHANNELS.map((ch) => {
+ if (r.materialCount === 0) return 'no materials';
+ const infos = r.materials.map((m) => m.channels[ch.key]);
+ if (infos.every((i) => i?.present)) {
+ const res = [...new Set(infos.map((i) => resolutionOf(i)))];
+ return res.length === 1 ? res[0] : res.join(' / ');
+ }
+ if (infos.some((i) => i?.present)) return 'partial';
+ return 'no';
+ });
+ const exts = [...new Set(r.materials.flatMap((m) => m.extensions))].sort();
+ return [r.label, ...cells, exts.join(', ') || '(none)'];
+ });
+ const widths = header.map((h, i) => Math.max(h.length, ...rows.map((row) => row[i].length)));
+ const line = (cells) => `| ${cells.map((c, i) => c.padEnd(widths[i])).join(' | ')} |`;
+ console.log('');
+ console.log(line(header));
+ console.log(`| ${widths.map((w) => '-'.repeat(w)).join(' | ')} |`);
+ for (const row of rows) console.log(line(row));
+}
+
+async function main() {
+ const args = parseArgs(process.argv.slice(2));
+ if (args.inputs.length === 0) {
+ console.error('usage: node scripts/inspect-glb-materials.mjs [--matrix] [--json] [--label=<name>] <glb path or url>...');
+ process.exit(2);
+ }
+
+ const reports = [];
+ let failures = 0;
+ for (const input of args.inputs) {
+ try {
+ reports.push(await inspectOne(input));
+ } catch (err) {
+ failures++;
+ reports.push({ label: input.label, source: input.source, error: String(err.message || err) });
+ }
+ }
+
+ const ok = reports.filter((r) => !r.error);
+ if (args.json) {
+ console.log(JSON.stringify({ generatedAt: new Date().toISOString(), models: reports }, null, 2));
+ } else if (args.matrix) {
+ printMatrix(ok);
+ } else {
+ for (const r of reports) {
+ if (r.error) console.error(`\n${r.label}\n ERROR ${r.error}`);
+ else printReport(r);
+ }
+ }
+
+ const gapped = ok.filter((r) => r.unmaterialedPrimitives > 0 || r.materials.some((m) => m.gaps.length));
+ if (!args.json) {
+ console.log('');
+ if (gapped.length) {
+ console.log(`${gapped.length} of ${ok.length} model(s) missing an implied PBR channel: ${gapped.map((r) => r.label).join(', ')}`);
+ } else if (ok.length) {
+ console.log(`All ${ok.length} model(s) carry a complete PBR set.`);
+ }
+ }
+ if (failures > 0) process.exit(2);
+ if (args.strict && gapped.length > 0) process.exit(1);
+}
+
+main().catch((err) => {
+ console.error(err);
+ process.exit(2);
+});
diff --git a/scripts/probe-generation-suite.mjs b/scripts/probe-generation-suite.mjs
new file mode 100644
index 000000000..b47beddb9
--- /dev/null
+++ b/scripts/probe-generation-suite.mjs
@@ -0,0 +1,419 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * scripts/probe-generation-suite.mjs — run every generation-suite flow against a
+ * live deployment and report what actually produced an artifact.
+ *
+ * A catalog entry saying `configured: true` only means an env var exists. This
+ * script is the opposite bar: it submits real work to the real endpoints, polls
+ * to completion, downloads the result, and asserts the bytes are what they claim
+ * to be (glTF magic for a mesh, PNG/WebP signature with alpha for an image,
+ * a parseable AnimationClip for a motion). Nothing here counts a green config.
+ *
+ * Usage:
+ * node scripts/probe-generation-suite.mjs # all rows
+ * node scripts/probe-generation-suite.mjs --only rig,remesh
+ * node scripts/probe-generation-suite.mjs --base https://three.ws
+ * node scripts/probe-generation-suite.mjs --json out.json
+ *
+ * Exit code 0 when every selected row passed, 1 otherwise.
+ */
+
+import { writeFileSync } from 'node:fs';
+
+const args = process.argv.slice(2);
+function flag(name, fallback = null) {
+ const i = args.indexOf(`--${name}`);
+ return i >= 0 && args[i + 1] && !args[i + 1].startsWith('--') ? args[i + 1] : fallback;
+}
+const BASE = (flag('base', process.env.PROBE_BASE || 'https://three.ws') || '').replace(/\/$/, '');
+const ONLY = (flag('only') || '').split(',').map((s) => s.trim()).filter(Boolean);
+const JSON_OUT = flag('json');
+const VERBOSE = args.includes('--verbose');
+
+// A public reference mesh and image that live on our own CDN, so a probe never
+// depends on a third party's uptime to prove our pipeline works.
+const REF_MESH = `${BASE}/avatars/mannequin.glb`;
+const REF_IMAGE = `${BASE}/og-image.png`;
+
+const UA = 'threews-generation-probe/1.0';
+const CLIENT_ID = `probe-${Date.now().toString(36)}`;
+
+function log(...a) {
+ if (VERBOSE) console.error(' ', ...a);
+}
+
+async function req(path, { method = 'GET', body = null, timeoutMs = 60_000, headers = {} } = {}) {
+ const url = path.startsWith('http') ? path : `${BASE}${path}`;
+ try {
+ const res = await fetch(url, {
+ method,
+ headers: {
+ 'user-agent': UA,
+ 'x-forge-client': CLIENT_ID,
+ ...(body ? { 'content-type': 'application/json' } : {}),
+ ...headers,
+ },
+ body: body ? JSON.stringify(body) : undefined,
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ const text = await res.text();
+ let parsed = null;
+ try {
+ parsed = JSON.parse(text);
+ } catch {
+ parsed = null;
+ }
+ return { status: res.status, json: parsed, text, headers: res.headers };
+ } catch (err) {
+ return { status: 0, json: null, text: String(err?.message || err), headers: new Headers() };
+ }
+}
+
+// Download the first bytes of an artifact and identify it by magic number, so a
+// 200 that serves an HTML error page can never be mistaken for a model.
+async function sniff(url, timeoutMs = 90_000) {
+ try {
+ const res = await fetch(url, {
+ headers: { 'user-agent': UA },
+ signal: AbortSignal.timeout(timeoutMs),
+ });
+ if (!res.ok) return { ok: false, detail: `HTTP ${res.status}` };
+ const buf = Buffer.from(await res.arrayBuffer());
+ const head = buf.subarray(0, 4).toString('binary');
+ let kind = 'unknown';
+ if (head === 'glTF') kind = 'glb';
+ else if (buf.subarray(0, 8).toString('hex') === '89504e470d0a1a0a') kind = 'png';
+ else if (head.startsWith('\xff\xd8')) kind = 'jpeg';
+ else if (buf.subarray(0, 4).toString('binary') === 'RIFF' && buf.subarray(8, 12).toString('binary') === 'WEBP') kind = 'webp';
+ else if (buf.subarray(4, 8).toString('binary') === 'ftyp') kind = 'mp4';
+ else if (head.trim().startsWith('{') || head.trim().startsWith('[')) kind = 'json';
+ else if (buf.subarray(0, 6).toString('binary').startsWith('solid') || buf.length > 84) kind = 'binary';
+ return { ok: true, kind, bytes: buf.length, buf };
+ } catch (err) {
+ return { ok: false, detail: String(err?.message || err) };
+ }
+}
+
+// Assert a GLB actually carries geometry rather than an empty scene: read the
+// JSON chunk out of the binary container and count mesh primitives.
+function inspectGlb(buf) {
+ if (buf.length < 20 || buf.subarray(0, 4).toString('binary') !== 'glTF') return null;
+ const jsonLen = buf.readUInt32LE(12);
+ if (jsonLen <= 0 || 20 + jsonLen > buf.length) return null;
+ let doc;
+ try {
+ doc = JSON.parse(buf.subarray(20, 20 + jsonLen).toString('utf8'));
+ } catch {
+ return null;
+ }
+ const primitives = (doc.meshes || []).reduce((n, m) => n + (m.primitives?.length || 0), 0);
+ return {
+ meshes: (doc.meshes || []).length,
+ primitives,
+ nodes: (doc.nodes || []).length,
+ skins: (doc.skins || []).length,
+ animations: (doc.animations || []).length,
+ materials: (doc.materials || []).length,
+ images: (doc.images || []).length,
+ joints: (doc.skins || []).reduce((n, s) => n + (s.joints?.length || 0), 0),
+ };
+}
+
+// Poll a job endpoint that answers { status: queued|running|done|failed }.
+async function pollJob(pollPath, { budgetMs = 420_000, intervalMs = 6_000, jobKey = 'job' } = {}) {
+ const deadline = Date.now() + budgetMs;
+ let last = null;
+ while (Date.now() < deadline) {
+ const r = await req(pollPath, { timeoutMs: 30_000 });
+ last = r;
+ const status = String(r.json?.status || '').toLowerCase();
+ log(`poll ${jobKey}: ${r.status} ${status || r.text.slice(0, 90)}`);
+ if (status === 'done' || status === 'succeeded' || status === 'complete') return r;
+ if (status === 'failed' || status === 'error') return r;
+ if (r.status >= 400 && r.status !== 429) return r;
+ await new Promise((r2) => setTimeout(r2, intervalMs));
+ }
+ return last || { status: 0, json: null, text: 'poll budget exhausted' };
+}
+
+const results = [];
+function record(name, endpoint, ok, detail, extra = {}) {
+ results.push({ name, endpoint, ok, detail, ...extra });
+ const mark = ok === true ? 'PASS' : ok === 'skip' ? 'SKIP' : 'FAIL';
+ console.log(`${mark.padEnd(4)} ${name.padEnd(24)} ${detail}`);
+}
+
+function selected(name) {
+ return ONLY.length === 0 || ONLY.includes(name);
+}
+
+// A generic "submit a mesh job, poll it, sniff the result" runner shared by the
+// remesh / stylize / segment / rembg lanes, which all use the same envelope.
+async function meshJob(name, path, body, resultKey = 'result_url', expectKind = 'glb') {
+ const post = await req(path, { method: 'POST', body, timeoutMs: 60_000 });
+ if (post.status === 503) return record(name, path, false, `unconfigured: ${post.json?.message || post.text.slice(0, 120)}`);
+ if (post.status !== 202 && post.status !== 200) {
+ return record(name, path, false, `submit HTTP ${post.status}: ${post.text.slice(0, 160)}`);
+ }
+ const jobId = post.json?.job_id;
+ if (!jobId) return record(name, path, false, `submit returned no job_id: ${post.text.slice(0, 160)}`);
+ const done = await pollJob(`${path}?job=${encodeURIComponent(jobId)}`, { jobKey: name });
+ const status = String(done.json?.status || '').toLowerCase();
+ if (status !== 'done') {
+ return record(name, path, false, `job ${status || done.status}: ${done.json?.error || done.text.slice(0, 160)}`);
+ }
+ const url = done.json?.[resultKey];
+ if (!url) return record(name, path, false, `done without ${resultKey}`);
+ const s = await sniff(url);
+ if (!s.ok) return record(name, path, false, `artifact fetch failed: ${s.detail}`);
+ const glb = expectKind === 'glb' ? inspectGlb(s.buf) : null;
+ if (expectKind === 'glb' && (!glb || glb.primitives === 0)) {
+ return record(name, path, false, `artifact is not a mesh with geometry (kind=${s.kind}, ${s.bytes} B)`);
+ }
+ const summary = glb
+ ? `${s.bytes} B glb, ${glb.primitives} primitives, ${glb.materials} materials`
+ : `${s.bytes} B ${s.kind}`;
+ record(name, path, true, summary, { artifact: url, glb: glb || undefined, job: done.json });
+ return done.json;
+}
+
+async function probeCatalogHealth() {
+ if (!selected('catalog')) return;
+ const cat = await req('/api/forge?catalog');
+ record(
+ 'catalog',
+ 'GET /api/forge?catalog',
+ cat.status === 200 && Array.isArray(cat.json?.backends),
+ cat.status === 200 ? `${cat.json?.backends?.length} backends, ${cat.json?.tiers?.length} tiers` : `HTTP ${cat.status}`,
+ );
+ const health = await req('/api/forge?health', { timeoutMs: 90_000 });
+ const backends = health.json?.backends || {};
+ const bad = Object.entries(backends)
+ .filter(([, v]) => v?.status !== 'ok' && v?.status !== 'byok')
+ .map(([k, v]) => `${k}=${v?.status}`);
+ record(
+ 'health',
+ 'GET /api/forge?health',
+ health.status === 200 && bad.length === 0,
+ health.status === 200 ? (bad.length ? `not ok: ${bad.join(', ')}` : `all ${Object.keys(backends).length} lanes ok`) : `HTTP ${health.status}`,
+ { llm: health.json?.llm?.overall },
+ );
+}
+
+async function probeTextTo3d() {
+ if (!selected('text-to-3d')) return;
+ const post = await req('/api/forge', {
+ method: 'POST',
+ body: {
+ prompt: 'a small wooden toy boat with a striped sail',
+ tier: 'draft',
+ force_regenerate: true,
+ },
+ timeoutMs: 300_000,
+ });
+ if (post.status !== 200 && post.status !== 202) {
+ return record('text-to-3d', 'POST /api/forge', false, `HTTP ${post.status}: ${post.text.slice(0, 200)}`);
+ }
+ let glbUrl = post.json?.glb_url || post.json?.glbUrl;
+ if (!glbUrl && post.json?.poll_url) {
+ const done = await pollJob(post.json.poll_url, { jobKey: 'text-to-3d', budgetMs: 480_000 });
+ glbUrl = done.json?.glb_url || done.json?.glbUrl;
+ if (!glbUrl) {
+ return record('text-to-3d', 'POST /api/forge', false, `job ${done.json?.status || done.status}: ${done.json?.error || done.text.slice(0, 160)}`);
+ }
+ }
+ if (!glbUrl) return record('text-to-3d', 'POST /api/forge', false, `no glb_url: ${post.text.slice(0, 200)}`);
+ const s = await sniff(glbUrl);
+ const glb = s.ok ? inspectGlb(s.buf) : null;
+ record(
+ 'text-to-3d',
+ 'POST /api/forge',
+ Boolean(glb && glb.primitives > 0),
+ glb ? `${s.bytes} B glb, ${glb.primitives} primitives, backend=${post.json?.backend || '?'}` : `not a mesh: ${s.detail || s.kind}`,
+ { artifact: glbUrl },
+ );
+ return glbUrl;
+}
+
+async function probeImageTo3d() {
+ if (!selected('image-to-3d')) return;
+ const presign = await req('/api/forge-upload', {
+ method: 'POST',
+ body: { content_type: 'image/png', size_bytes: 4096 },
+ });
+ const presignOk = presign.status === 200 && Boolean(presign.json?.upload_url);
+ if (!presignOk && presign.status !== 503) {
+ record('image-upload', 'POST /api/forge-upload', false, `HTTP ${presign.status}: ${presign.text.slice(0, 140)}`);
+ } else {
+ record('image-upload', 'POST /api/forge-upload', presignOk, presignOk ? 'presigned R2 upload issued' : 'object storage unconfigured (URL path still open)');
+ }
+ const post = await req('/api/forge', {
+ method: 'POST',
+ body: { image_urls: [REF_IMAGE], tier: 'draft', force_regenerate: true },
+ timeoutMs: 300_000,
+ });
+ if (post.status !== 200 && post.status !== 202) {
+ return record('image-to-3d', 'POST /api/forge', false, `HTTP ${post.status}: ${post.text.slice(0, 200)}`);
+ }
+ let glbUrl = post.json?.glb_url || post.json?.glbUrl;
+ if (!glbUrl && post.json?.poll_url) {
+ const done = await pollJob(post.json.poll_url, { jobKey: 'image-to-3d', budgetMs: 480_000 });
+ glbUrl = done.json?.glb_url || done.json?.glbUrl;
+ }
+ if (!glbUrl) return record('image-to-3d', 'POST /api/forge', false, `no glb_url: ${post.text.slice(0, 200)}`);
+ const s = await sniff(glbUrl);
+ const glb = s.ok ? inspectGlb(s.buf) : null;
+ record(
+ 'image-to-3d',
+ 'POST /api/forge',
+ Boolean(glb && glb.primitives > 0),
+ glb ? `${s.bytes} B glb, ${glb.primitives} primitives` : `not a mesh: ${s.detail || s.kind}`,
+ { artifact: glbUrl },
+ );
+}
+
+async function probeRig() {
+ if (!selected('rig')) return;
+ const post = await req('/api/forge?action=rig', {
+ method: 'POST',
+ body: { mesh_url: REF_MESH },
+ timeoutMs: 60_000,
+ });
+ if (post.status !== 202 && post.status !== 200) {
+ return record('auto-rig', 'POST /api/forge?action=rig', false, `HTTP ${post.status}: ${post.text.slice(0, 180)}`);
+ }
+ const jobId = post.json?.job_id || post.json?.job;
+ let done = post;
+ if (jobId && !post.json?.result_url) {
+ done = await pollJob(`/api/forge?action=rig&job=${encodeURIComponent(jobId)}`, { jobKey: 'rig' });
+ }
+ const url = done.json?.result_url || done.json?.rigged_url || done.json?.glb_url;
+ if (!url) {
+ return record('auto-rig', 'POST /api/forge?action=rig', false, `no rigged url: ${done.json?.error || done.text.slice(0, 180)}`);
+ }
+ const s = await sniff(url);
+ const glb = s.ok ? inspectGlb(s.buf) : null;
+ const rigged = Boolean(glb && glb.skins > 0 && glb.joints > 0);
+ record('auto-rig', 'POST /api/forge?action=rig', rigged, glb ? `${glb.skins} skin(s), ${glb.joints} joints, ${glb.primitives} primitives` : `not a mesh: ${s.detail}`, { artifact: url });
+}
+
+async function probeMotion() {
+ if (!selected('motion')) return;
+ const post = await req('/api/forge-motion', {
+ method: 'POST',
+ body: { prompt: 'waving confidently with the right arm', duration_seconds: 3 },
+ });
+ if (post.status === 503) return record('text-to-motion', 'POST /api/forge-motion', false, `unconfigured: ${post.json?.message || ''}`);
+ if (post.status !== 202 && post.status !== 200) {
+ return record('text-to-motion', 'POST /api/forge-motion', false, `HTTP ${post.status}: ${post.text.slice(0, 180)}`);
+ }
+ const jobId = post.json?.job_id;
+ const done = await pollJob(`/api/forge-motion?job=${encodeURIComponent(jobId)}`, { jobKey: 'motion' });
+ const url = done.json?.clip_url;
+ if (!url) return record('text-to-motion', 'POST /api/forge-motion', false, `job ${done.json?.status || done.status}: ${done.json?.error || done.text.slice(0, 160)}`);
+ const s = await sniff(url);
+ let clipOk = false;
+ let detail = s.detail || s.kind;
+ if (s.ok) {
+ try {
+ const clip = JSON.parse(s.buf.toString('utf8'));
+ const tracks = clip.tracks || clip.clip?.tracks || [];
+ clipOk = Array.isArray(tracks) && tracks.length > 0;
+ detail = `${tracks.length} tracks, ${done.json?.frames || '?'} frames @ ${done.json?.fps || '?'} fps`;
+ } catch {
+ detail = `clip is not JSON (${s.bytes} B ${s.kind})`;
+ }
+ }
+ record('text-to-motion', 'POST /api/forge-motion', clipOk, detail, { artifact: url });
+}
+
+async function probeRetexture() {
+ if (!selected('retexture')) return;
+ const probe = await req('/api/studio/retexture-region');
+ const ok = probe.status === 200 || probe.status === 405;
+ record('retexture (probe)', 'GET /api/studio/retexture-region', ok, ok ? `capability probe HTTP ${probe.status}` : `HTTP ${probe.status}: ${probe.text.slice(0, 140)}`);
+ const post = await req('/api/studio/retexture-region', {
+ method: 'POST',
+ body: { mesh_url: REF_MESH, prompt: 'weathered bronze with green patina' },
+ timeoutMs: 90_000,
+ });
+ if (post.status === 503) return record('retexture', 'POST /api/studio/retexture-region', false, `unconfigured: ${post.json?.message || post.text.slice(0, 140)}`);
+ if (post.status !== 202 && post.status !== 200) {
+ return record('retexture', 'POST /api/studio/retexture-region', false, `HTTP ${post.status}: ${post.text.slice(0, 180)}`);
+ }
+ const jobId = post.json?.job_id;
+ if (!jobId) return record('retexture', 'POST /api/studio/retexture-region', Boolean(post.json?.result_url), post.text.slice(0, 160));
+ const done = await pollJob(`/api/studio/retexture-region?job=${encodeURIComponent(jobId)}`, { jobKey: 'retexture' });
+ const url = done.json?.result_url;
+ if (!url) return record('retexture', 'POST /api/studio/retexture-region', false, `job ${done.json?.status || done.status}: ${done.json?.error || done.text.slice(0, 160)}`);
+ const s = await sniff(url);
+ const glb = s.ok ? inspectGlb(s.buf) : null;
+ record('retexture', 'POST /api/studio/retexture-region', Boolean(glb && glb.images > 0), glb ? `${glb.images} texture image(s), ${glb.materials} materials` : `not a mesh: ${s.detail}`, { artifact: url });
+}
+
+async function probeX402() {
+ if (!selected('x402')) return;
+ const r = await req('/api/x402/forge', {
+ method: 'POST',
+ body: { prompt: 'a ceramic teapot', tier: 'draft' },
+ });
+ const accepts = r.json?.accepts || [];
+ const ok = r.status === 402 && Array.isArray(accepts) && accepts.length > 0;
+ record('x402 challenge', 'POST /api/x402/forge', ok, ok ? `402 with ${accepts.length} accept(s): ${accepts.map((a) => `${a.network}/${a.maxAmountRequired}`).join(', ')}` : `HTTP ${r.status}: ${r.text.slice(0, 160)}`);
+ const wk = await req('/.well-known/x402.json');
+ const items = wk.json?.items || wk.json?.resources || [];
+ const gen = items.filter((i) => String(i.resource || i.url || '').includes('forge') || String(i.resource || i.url || '').includes('mcp-3d'));
+ record('x402 catalog', 'GET /.well-known/x402.json', wk.status === 200 && gen.length > 0, wk.status === 200 ? `${gen.length} generation surfaces of ${items.length} listed` : `HTTP ${wk.status}`);
+}
+
+async function probeMcp(path, label) {
+ if (!selected('mcp')) return;
+ const list = await req(path, {
+ method: 'POST',
+ body: { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} },
+ timeoutMs: 45_000,
+ });
+ const tools = list.json?.result?.tools || [];
+ record(`${label} tools/list`, `POST ${path}`, list.status === 200 && tools.length > 0, list.status === 200 ? `${tools.length} tools` : `HTTP ${list.status}: ${list.text.slice(0, 140)}`);
+ if (!tools.length) return;
+ // Call the cheapest read-only tool the server advertises, so a probe never
+ // bills a generation just to prove the JSON-RPC surface answers.
+ const readOnly = tools.find((t) => /catalog|list|capabilit|health|search|browse/i.test(t.name));
+ if (!readOnly) return record(`${label} tools/call`, `POST ${path}`, 'skip', 'no read-only tool advertised');
+ const call = await req(path, {
+ method: 'POST',
+ body: { jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: readOnly.name, arguments: {} } },
+ timeoutMs: 60_000,
+ });
+ const content = call.json?.result?.content || [];
+ record(`${label} tools/call`, `${readOnly.name}`, call.status === 200 && content.length > 0 && !call.json?.result?.isError, call.status === 200 ? `${readOnly.name} → ${content.length} content block(s)` : `HTTP ${call.status}: ${call.text.slice(0, 140)}`);
+}
+
+async function main() {
+ console.log(`Generation-suite probe against ${BASE}\n`);
+ await probeCatalogHealth();
+ await probeTextTo3d();
+ await probeImageTo3d();
+ await probeRig();
+ if (selected('remesh')) await meshJob('remesh', '/api/forge-remesh', { mesh_url: REF_MESH, remesh_mode: 'triangle', operation: 'simplify', target_faces: 3000 });
+ if (selected('stylize')) await meshJob('stylize', '/api/forge-stylize', { mesh_url: REF_MESH, style: 'lowpoly' });
+ if (selected('segment')) await meshJob('segment', '/api/forge-segment', { mesh_url: REF_MESH, method: 'connected', max_parts: 8 });
+ if (selected('rembg')) await meshJob('rembg', '/api/forge-rembg', { image_url: REF_IMAGE }, 'result_url', 'png');
+ await probeMotion();
+ await probeRetexture();
+ await probeX402();
+ await probeMcp('/api/mcp-3d', 'mcp-3d');
+ await probeMcp('/api/mcp-studio', 'mcp-studio');
+
+ const failed = results.filter((r) => r.ok === false);
+ console.log(`\n${results.length - failed.length}/${results.length} passed`);
+ if (failed.length) console.log(`failed: ${failed.map((f) => f.name).join(', ')}`);
+ if (JSON_OUT) writeFileSync(JSON_OUT, JSON.stringify({ base: BASE, at: new Date().toISOString(), results }, null, 2));
+ process.exit(failed.length ? 1 : 0);
+}
+
+main().catch((err) => {
+ console.error('probe crashed:', err);
+ process.exit(1);
+});