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
// Model Diff page controller (/diff).
//
// Three jobs, in the order the visitor experiences them:
// 1. Get two models. Drag-drop, file picker, a pasted URL, or an example pair.
// 2. Compare them. The whole engine (@three-ws/glb-diff) runs here in the tab.
// 3. Show the result twice over: as a change set you can read and copy, and as
// a 3D scene where clicking a row frames the object it names.
//
// The privacy claim in the copy constrains the code, as it does on /rig-doctor:
// a dropped file is read with the File API and compared in this tab. It is never
// posted anywhere. A model given as a URL is a different matter and the page
// says so: it is fetched through the same-origin proxy at /api/glb, because an
// arbitrary CDN will not send an Access-Control-Allow-Origin header and the
// browser would refuse the read outright.
//
// The 3D stage is imported lazily. three.js plus the glTF loader stack is the
// heaviest thing on this page and the report is useful without it, so the
// import starts only once a model is actually in hand.
import { describeModel, diffDescriptions, formatBytes, formatMarkdown, SEVERITY_MEANING } from '@three-ws/glb-diff';
import { proxiedModelURL } from './ipfs.js';
const $ = (id) => document.getElementById(id);
// Real models this site already serves, chosen so the four states a visitor can
// land in are each one click away: a rig that lost its skeleton, two unrelated
// characters, two close siblings, and a pair with nothing between them.
const EXAMPLE_PAIRS = [
{
label: 'A rig, then the same pose unrigged',
a: '/avatars/default.glb',
b: '/avatars/mannequin.glb',
title: 'Every skeleton and clip gone: the breaking case',
},
{
label: 'Two different characters',
a: '/avatars/xbot.glb',
b: '/avatars/michelle.glb',
title: 'Different meshes, different clips, overlapping joint names',
},
{
label: 'Sibling avatars',
a: '/avatars/realistic-male.glb',
b: '/avatars/realistic-female.glb',
title: 'Same rig family, different geometry and textures',
},
{
label: 'Nothing changed',
a: '/avatars/cesium-man.glb',
b: '/avatars/cesium-man.glb',
title: 'What a clean comparison looks like',
},
];
const SECTION_ORDER = [
['skins', 'Skeletons'],
['animations', 'Animations'],
['meshes', 'Meshes'],
['nodes', 'Nodes'],
['materials', 'Materials'],
['textures', 'Textures'],
];
const TOTAL_LABEL = {
vertices: 'Vertices',
triangles: 'Triangles',
nodes: 'Nodes',
meshes: 'Meshes',
materials: 'Materials',
textures: 'Textures',
animations: 'Animations',
skins: 'Skeletons',
joints: 'Joints',
scenes: 'Scenes',
textureBytes: 'Texture bytes',
sizeBytes: 'File size',
};
const state = {
a: null,
b: null,
changeset: null,
stage: null,
stagePromise: null,
mode: 'overlay',
focused: null,
};
// ── Small helpers ────────────────────────────────────────────────────────────
function esc(value) {
return String(value ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' })[c]);
}
function num(value) {
return Number(value || 0).toLocaleString();
}
function signed(value, isBytes) {
if (value === 0) return '0';
const body = isBytes ? formatBytes(Math.abs(value)) : num(Math.abs(value));
return `${value > 0 ? '+' : '-'}${body}`;
}
function fieldText(change) {
const opaque = {
geometry: 'vertex data changed',
pixels: 'image data changed',
inverseBindMatrices: 'bind pose changed',
topology: 'vertex positions or index buffer changed',
uv: 'UV coordinates changed',
skinWeights: 'vertex joint/weight bindings changed',
};
if (opaque[change.field]) return `${opaque[change.field]}${change.note ? ` (${change.note})` : ''}`;
const show = (value) => {
if (value === null || value === undefined) return 'none';
if (Array.isArray(value)) return value.length > 4 ? `[${value.slice(0, 4).join(', ')}, +${value.length - 4}]` : `[${value.join(', ')}]`;
if (typeof value === 'object') return JSON.stringify(value);
return String(value);
};
return `${show(change.a)} to ${show(change.b)}${change.note ? ` (${change.note})` : ''}`;
}
// ── Loading a side ───────────────────────────────────────────────────────────
// Same-origin models are fetched directly. Anything else goes through the
// site's own GLB proxy, which exists precisely because a third-party CDN's CORS
// policy would otherwise make the model unreadable from a browser. The rule
// itself lives in src/ipfs.js beside the image-proxy rule, so a surface that
// paints a model and a surface that paints token art cannot drift apart.
function proxied(url) {
return proxiedModelURL(url) || null;
}
function setSlotState(role, slotState) {
$(`dx-slot-${role}`).dataset.state = slotState;
}
function showSlotError(role, message) {
const el = $(`dx-error-${role}`);
el.textContent = message;
el.hidden = !message;
setSlotState(role, message ? 'error' : 'idle');
}
async function loadSide(role, bytes, name, sourceUrl) {
showSlotError(role, '');
setSlotState(role, 'loading');
$(`dx-name-${role}`).textContent = name;
$(`dx-meta-${role}`).textContent = formatBytes(bytes.byteLength);
let description;
try {
description = await describeModel(new Uint8Array(bytes), { name });
} catch (err) {
showSlotError(role, `Not a readable glTF/GLB: ${err?.message || 'could not parse the file'}`);
state[role] = null;
renderReport();
return;
}
state[role] = { description, bytes, name, url: sourceUrl || null };
setSlotState(role, 'loaded');
$(`dx-meta-${role}`).textContent =
`${formatBytes(bytes.byteLength)} - ${num(description.totals.triangles)} tris - ${num(description.totals.joints)} joints`;
const stage = await ensureStage();
if (stage) {
try {
await stage.setModel(role, bytes);
} catch (err) {
// The report is the product; a viewport that refuses one exotic model
// must not take the comparison down with it.
showSlotError(role, `Compared fine, but the 3D view could not load it: ${err?.message || 'renderer error'}`);
}
}
compare();
syncShareUrl();
}
async function loadFromFile(role, file) {
if (!file) return;
try {
const bytes = await file.arrayBuffer();
await loadSide(role, bytes, file.name);
} catch (err) {
showSlotError(role, `Could not read the file: ${err?.message || 'unknown error'}`);
}
}
async function loadFromUrl(role, rawUrl) {
const url = String(rawUrl || '').trim();
if (!url) return;
const target = proxied(url);
if (!target) {
showSlotError(role, 'That does not look like a URL.');
return;
}
setSlotState(role, 'loading');
$(`dx-name-${role}`).textContent = 'Fetching...';
try {
const res = await fetch(target, { signal: AbortSignal.timeout(30_000) });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const bytes = await res.arrayBuffer();
const name = url.split('/').filter(Boolean).pop() || url;
await loadSide(role, bytes, name, url);
} catch (err) {
$(`dx-name-${role}`).textContent = role === 'a' ? 'Drop the baseline .glb' : 'Drop the candidate .glb';
showSlotError(role, `Could not fetch that model: ${err?.message || 'network error'}`);
}
}
// ── The comparison ───────────────────────────────────────────────────────────
function compare() {
if (!state.a || !state.b) {
renderReport();
return;
}
renderSkeleton();
// Yield one frame so the skeleton actually paints before the comparison
// takes the main thread. Without it the placeholder never appears and a
// heavy pair looks like a frozen page.
requestAnimationFrame(() => {
state.changeset = diffDescriptions(state.a.description, state.b.description);
renderReport();
if (state.stage) {
state.stage.applyChangeSet(state.changeset);
$('dx-stage-bar').hidden = false;
$('dx-legend').hidden = false;
$('dx-play-wrap').hidden = !state.stage.hasClips();
}
});
}
function renderSkeleton() {
$('dx-report').innerHTML =
'<div class="dx-card"><div class="dx-skeleton"><i></i><i></i><i></i><i></i></div></div>';
}
function renderReport() {
const host = $('dx-report');
if (!state.a || !state.b) {
const waiting = state.a || state.b ? 'One more to go.' : 'Drop a file on each side, paste two URLs, or pick an example pair.';
host.innerHTML = `<div class="dx-card"><div class="dx-empty"><strong>Load two models</strong>${esc(waiting)} The comparison runs on your machine.</div></div>`;
return;
}
const changes = state.changeset;
if (!changes) return;
host.innerHTML = [
verdictHtml(changes),
totalsHtml(changes),
sectionsHtml(changes),
actionsHtml(changes),
].join('');
wireReport();
}
function verdictHtml(changes) {
const s = changes.summary;
const counts = changes.identical
? 'no differences'
: `+${s.added} / -${s.removed} / ~${s.modified} / renamed ${s.renamed} / moved ${s.moved}`;
const highlights = changes.highlights
.map((h) => `<li class="dx-highlight dx-sev-${esc(h.severity)}">${esc(h.text)}</li>`)
.join('');
return `
<div class="dx-verdict dx-sev-${esc(changes.severity)}">
<div class="dx-verdict-top">
<span class="dx-verdict-level">${esc(changes.severity)}</span>
<span class="dx-verdict-counts">${esc(counts)}</span>
</div>
<p class="dx-verdict-why">${esc(SEVERITY_MEANING[changes.severity])}</p>
${highlights ? `<ul class="dx-highlights">${highlights}</ul>` : ''}
</div>`;
}
function totalsHtml(changes) {
const rows = Object.entries(changes.totals).filter(([, v]) => v.delta !== 0);
if (!rows.length) return '';
const body = rows
.map(([key, v]) => {
const isBytes = key.endsWith('Bytes');
const fmt = isBytes ? formatBytes : num;
const cls = v.delta > 0 ? 'dx-up' : 'dx-down';
const pct = v.pct === null || v.pct === 0 ? '' : ` (${v.pct > 0 ? '+' : ''}${v.pct}%)`;
return `<tr><td>${esc(TOTAL_LABEL[key] || key)}</td><td class="dx-num">${esc(fmt(v.a))}</td><td class="dx-num">${esc(fmt(v.b))}</td><td class="dx-num ${cls}">${esc(signed(v.delta, isBytes) + pct)}</td></tr>`;
})
.join('');
return `
<div class="dx-card">
<div class="dx-card-head"><span>Totals</span></div>
<table class="dx-totals">
<thead><tr><th>metric</th><th class="dx-num">before</th><th class="dx-num">after</th><th class="dx-num">delta</th></tr></thead>
<tbody>${body}</tbody>
</table>
</div>`;
}
function rowHtml({ mark, markClass, name, detail, fields, path }) {
const inner = `
<span class="dx-mark ${markClass}" aria-hidden="true">${mark}</span>
<span>
<span class="dx-row-name">${esc(name)}</span>
${detail ? ` <span class="dx-row-detail">${esc(detail)}</span>` : ''}
${fields && fields.length ? `<ul class="dx-fields">${fields.map((f) => `<li class="dx-field"><b>${esc(f.field)}</b> ${esc(fieldText(f))}</li>`).join('')}</ul>` : ''}
</span>`;
if (path) {
return `<li><button type="button" class="dx-row" data-path="${esc(path)}" aria-pressed="false" title="Frame this node in the viewer">${inner}</button></li>`;
}
return `<li class="dx-row">${inner}</li>`;
}
function sectionsHtml(changes) {
const blocks = SECTION_ORDER.map(([key, label]) => {
const section = changes.sections[key];
if (!section || !section.changed) return '';
const isNodes = key === 'nodes';
const rows = [
...section.removed.map((item) =>
rowHtml({ mark: '-', markClass: 'dx-mark-del', name: item.name, detail: item.detail, path: isNodes ? item.name : null }),
),
...section.added.map((item) =>
rowHtml({ mark: '+', markClass: 'dx-mark-add', name: item.name, detail: item.detail, path: isNodes ? item.name : null }),
),
...section.renamed.map((item) =>
rowHtml({ mark: 'R', markClass: 'dx-mark-ren', name: `${item.from} to ${item.to}`, path: isNodes ? item.to : null }),
),
...(section.moved || []).map((item) =>
rowHtml({ mark: 'M', markClass: 'dx-mark-mov', name: `${item.from} to ${item.to}`, detail: 'reparented', path: item.to }),
),
...section.modified.map((item) =>
rowHtml({
mark: '~',
markClass: 'dx-mark-mod',
name: item.name,
detail: item.from && item.from !== item.name ? `was ${item.from}` : '',
fields: item.changes,
path: isNodes ? item.name : null,
}),
),
].join('');
const open = section.severity === 'breaking' || section.severity === 'major' ? ' open' : '';
return `
<details class="dx-section"${open}>
<summary>
<svg class="dx-caret" width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m9 6 6 6-6 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>
<span class="dx-section-name dx-sev-${esc(section.severity)}" style="color: var(--dx-sev)">${esc(label)}</span>
<span class="dx-section-count">${section.changed} changed, ${section.unchanged} same</span>
</summary>
<ul class="dx-rows">${rows}</ul>
</details>`;
}).join('');
const extras = extensionsHtml(changes);
if (!blocks && !extras) {
return `<div class="dx-card"><div class="dx-empty"><strong>No differences</strong>Every scene, mesh, material, texture, skeleton and clip matches.</div></div>`;
}
return `<div class="dx-card">${blocks}${extras}</div>`;
}
function extensionsHtml(changes) {
const ext = changes.extensions;
const rows = [
...ext.required.added.map((n) => rowHtml({ mark: '+', markClass: 'dx-mark-add', name: n, detail: 'now required' })),
...ext.required.removed.map((n) => rowHtml({ mark: '-', markClass: 'dx-mark-del', name: n, detail: 'no longer required' })),
...ext.used.added.filter((n) => !ext.required.added.includes(n)).map((n) => rowHtml({ mark: '+', markClass: 'dx-mark-add', name: n })),
...ext.used.removed.filter((n) => !ext.required.removed.includes(n)).map((n) => rowHtml({ mark: '-', markClass: 'dx-mark-del', name: n })),
...changes.asset.map((c) => rowHtml({ mark: '~', markClass: 'dx-mark-mod', name: c.field, detail: fieldText(c) })),
];
if (!rows.length) return '';
return `
<details class="dx-section">
<summary>
<svg class="dx-caret" width="12" height="12" viewBox="0 0 24 24" fill="none" aria-hidden="true"><path d="m9 6 6 6-6 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>
<span class="dx-section-name">Extensions and metadata</span>
<span class="dx-section-count">${rows.length} changed</span>
</summary>
<ul class="dx-rows">${rows.join('')}</ul>
</details>`;
}
function cliCommand() {
const a = state.a?.url || state.a?.name || 'before.glb';
const b = state.b?.url || state.b?.name || 'after.glb';
return `npx @three-ws/glb-diff ${a} ${b} --fail-on breaking`;
}
function actionsHtml() {
return `
<div class="dx-card">
<div class="dx-card-head"><span>Take it with you</span></div>
<div style="padding: var(--space-md); display: flex; flex-direction: column; gap: var(--space-sm)">
<div class="dx-actions">
<button type="button" class="dx-btn" data-copy="markdown">Copy Markdown</button>
<button type="button" class="dx-btn" data-copy="json">Copy JSON</button>
<button type="button" class="dx-btn" data-download="json">Download change set</button>
<button type="button" class="dx-btn" data-copy="link">Copy link</button>
</div>
<pre class="dx-cli">${esc(cliCommand())}</pre>
<div class="dx-actions">
<button type="button" class="dx-btn" data-copy="cli">Copy the CLI command</button>
</div>
</div>
</div>`;
}
// ── Wiring ───────────────────────────────────────────────────────────────────
async function flash(button, message) {
const original = button.textContent;
button.textContent = message;
button.disabled = true;
setTimeout(() => {
button.textContent = original;
button.disabled = false;
}, 1400);
}
async function copy(text, button, label) {
try {
await navigator.clipboard.writeText(text);
flash(button, label);
} catch {
flash(button, 'Clipboard blocked');
}
}
function wireReport() {
for (const button of document.querySelectorAll('[data-path]')) {
button.addEventListener('click', () => {
const path = button.dataset.path;
for (const other of document.querySelectorAll('[data-path]')) other.setAttribute('aria-pressed', 'false');
button.setAttribute('aria-pressed', 'true');
state.focused = path;
state.stage?.focusPath(path);
});
}
for (const button of document.querySelectorAll('[data-copy]')) {
button.addEventListener('click', () => {
const kind = button.dataset.copy;
if (kind === 'markdown') return copy(formatMarkdown(state.changeset), button, 'Copied');
if (kind === 'json') return copy(JSON.stringify(state.changeset, null, 2), button, 'Copied');
if (kind === 'cli') return copy(cliCommand(), button, 'Copied');
return copy(location.href, button, 'Copied');
});
}
const download = document.querySelector('[data-download]');
if (download) {
download.addEventListener('click', () => {
const blob = new Blob([JSON.stringify(state.changeset, null, 2)], { type: 'application/json' });
const url = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = url;
link.download = `${state.a.name.replace(/\.[^.]+$/, '')}-to-${state.b.name.replace(/\.[^.]+$/, '')}.diff.json`;
link.click();
URL.revokeObjectURL(url);
flash(download, 'Saved');
});
}
}
async function ensureStage() {
if (state.stage) return state.stage;
if (!state.stagePromise) {
state.stagePromise = import('./model-diff-stage.js')
.then((mod) => mod.createDiffStage($('dx-stage')))
.then((stage) => {
state.stage = stage;
$('dx-stage-empty').hidden = true;
return stage;
})
.catch((err) => {
// WebGL can be unavailable (headless, blocked, software-blacklisted).
// The report still works, so say what happened and carry on.
$('dx-stage-empty').innerHTML =
`<strong>3D view unavailable</strong><span>${esc(err?.message || 'this browser refused a WebGL context')}. The comparison below still works.</span>`;
state.stagePromise = null;
return null;
});
}
return state.stagePromise;
}
function wireSlot(role) {
const slot = $(`dx-slot-${role}`);
const input = $(`dx-file-${role}`);
input.addEventListener('change', () => loadFromFile(role, input.files?.[0]));
for (const type of ['dragenter', 'dragover']) {
slot.addEventListener(type, (event) => {
event.preventDefault();
slot.dataset.state = 'dragging';
});
}
for (const type of ['dragleave', 'drop']) {
slot.addEventListener(type, (event) => {
event.preventDefault();
if (slot.dataset.state === 'dragging') slot.dataset.state = state[role] ? 'loaded' : 'idle';
});
}
slot.addEventListener('drop', (event) => loadFromFile(role, event.dataTransfer?.files?.[0]));
$(`dx-load-${role}`).addEventListener('click', () => loadFromUrl(role, $(`dx-url-${role}`).value));
$(`dx-url-${role}`).addEventListener('keydown', (event) => {
if (event.key === 'Enter') loadFromUrl(role, event.currentTarget.value);
});
}
function wireExamples() {
const host = $('dx-examples');
for (const pair of EXAMPLE_PAIRS) {
const button = document.createElement('button');
button.type = 'button';
button.className = 'dx-example';
button.textContent = pair.label;
button.title = pair.title;
button.addEventListener('click', async () => {
$('dx-url-a').value = pair.a;
$('dx-url-b').value = pair.b;
await loadFromUrl('a', pair.a);
await loadFromUrl('b', pair.b);
});
host.appendChild(button);
}
}
function wireStageControls() {
for (const button of document.querySelectorAll('[data-mode]')) {
button.addEventListener('click', () => {
state.mode = button.dataset.mode;
for (const other of document.querySelectorAll('[data-mode]')) {
other.setAttribute('aria-pressed', String(other === button));
}
$('dx-wipe').hidden = state.mode !== 'wipe';
state.stage?.setMode(state.mode);
});
}
$('dx-wipe').addEventListener('input', (event) => state.stage?.setWipe(Number(event.target.value) / 100));
$('dx-highlight').addEventListener('change', (event) => state.stage?.setHighlight(event.target.checked));
$('dx-play').addEventListener('change', (event) => state.stage?.setPlaying(event.target.checked));
$('dx-swap').addEventListener('click', async () => {
const [a, b] = [state.a, state.b];
if (!a && !b) return;
state.a = b;
state.b = a;
const urlA = $('dx-url-a').value;
$('dx-url-a').value = $('dx-url-b').value;
$('dx-url-b').value = urlA;
for (const role of ['a', 'b']) {
const side = state[role];
$(`dx-name-${role}`).textContent = side ? side.name : role === 'a' ? 'Drop the baseline .glb' : 'Drop the candidate .glb';
$(`dx-meta-${role}`).textContent = side
? `${formatBytes(side.bytes.byteLength)} - ${num(side.description.totals.triangles)} tris - ${num(side.description.totals.joints)} joints`
: '';
setSlotState(role, side ? 'loaded' : 'idle');
if (side && state.stage) await state.stage.setModel(role, side.bytes);
}
compare();
syncShareUrl();
});
}
// Keyboard shortcuts, so the comparison modes are reachable without hunting for
// the control strip. Skipped while a text field has focus.
function wireShortcuts() {
document.addEventListener('keydown', (event) => {
const tag = document.activeElement?.tagName;
if (tag === 'INPUT' || tag === 'TEXTAREA' || event.metaKey || event.ctrlKey || event.altKey) return;
const modes = { o: 'overlay', w: 'wipe', s: 'split' };
const mode = modes[event.key.toLowerCase()];
if (mode) {
document.querySelector(`[data-mode="${mode}"]`)?.click();
return;
}
if (event.key.toLowerCase() === 'h') $('dx-highlight').click();
if (event.key.toLowerCase() === 'f') state.stage?.frameAll();
});
}
// A pair given as URLs is shareable, so it goes in the address bar. A pair of
// dropped files is not, and pretending otherwise would produce a link that
// silently opens an empty page for whoever received it.
function syncShareUrl() {
const params = new URLSearchParams();
if (state.a?.url) params.set('a', state.a.url);
if (state.b?.url) params.set('b', state.b.url);
const query = params.toString();
history.replaceState(null, '', query ? `${location.pathname}?${query}` : location.pathname);
}
async function restoreFromUrl() {
const params = new URLSearchParams(location.search);
const a = params.get('a');
const b = params.get('b');
if (a) {
$('dx-url-a').value = a;
await loadFromUrl('a', a);
}
if (b) {
$('dx-url-b').value = b;
await loadFromUrl('b', b);
}
}
function init() {
wireSlot('a');
wireSlot('b');
wireExamples();
wireStageControls();
wireShortcuts();
restoreFromUrl();
}
if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', init);
else init();