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
// The 3D stage behind /diff.
//
// A change set tells you a mesh moved. Seeing it move is what makes the change
// obvious, so this renders both models in the same scene and offers the three
// ways people actually compare things:
//
// overlay the baseline as a translucent ghost, the candidate solid on top
// wipe one screen-aligned clipping plane, dragged across the view
// split both models placed side by side, orbiting together
//
// The wipe plane is rebuilt from the camera basis every frame rather than fixed
// to world X. A plane pinned to a world axis stops being a wipe the moment you
// orbit: it slices the models diagonally and then edge-on. Deriving it from the
// camera's right vector keeps the seam vertical on screen no matter where the
// camera is, which is the only version that reads as a wipe.
//
// Loaded lazily by src/model-diff.js: three.js plus the glTF loader stack is by
// far the heaviest thing on the page, and a visitor who reads the explainer and
// leaves should not pay for it.
import {
AmbientLight,
AnimationMixer,
Box3,
Color,
DirectionalLight,
Group,
MeshStandardMaterial,
PMREMGenerator,
PerspectiveCamera,
Plane,
Scene,
Vector3,
WebGLRenderer,
} from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
import { getDecoders } from './viewer/internal.js';
// Ghost blue for the baseline, warm amber for edits, green for additions, red
// for what is gone. The same five values the page legend prints, so the picture
// and the caption can never drift apart.
const COLOR = {
before: 0x60a5fa,
changed: 0xfbbf24,
added: 0x4ade80,
removed: 0xf87171,
};
let loaderPromise = null;
function getLoader() {
if (!loaderPromise) {
loaderPromise = getDecoders().then(({ dracoLoader, ktx2Loader, meshoptDecoder }) => {
const loader = new GLTFLoader();
loader.setDRACOLoader(dracoLoader);
loader.setKTX2Loader(ktx2Loader);
loader.setMeshoptDecoder(meshoptDecoder);
return loader;
});
}
return loaderPromise;
}
// Rebuild the same node paths describe.js produces, against the loaded scene
// graph, so a row in the report can point at an object in the viewport. glTF
// node names survive on `userData.name`; `object.name` has been through three's
// PropertyBinding sanitizer and would not match a path built from the file.
function indexByPath(root) {
const byPath = new Map();
const seen = new Set();
let index = 0;
const visit = (object, parentPath) => {
const raw = object.userData?.name || object.name || `#node.${index}`;
const path = parentPath ? `${parentPath}/${raw}` : raw;
let unique = path;
let bump = 1;
while (seen.has(unique)) unique = `${path}#${bump++}`;
seen.add(unique);
byPath.set(unique, object);
index++;
for (const child of object.children) visit(child, unique);
};
for (const child of root.children) visit(child, '');
return byPath;
}
function disposeObject(object) {
object.traverse((node) => {
if (node.geometry) node.geometry.dispose();
const materials = Array.isArray(node.material) ? node.material : node.material ? [node.material] : [];
for (const material of materials) {
for (const value of Object.values(material)) {
if (value && value.isTexture) value.dispose();
}
material.dispose();
}
});
}
class Side {
constructor(role) {
this.role = role;
this.group = new Group();
this.root = null;
this.mixer = null;
this.clips = [];
this.byPath = new Map();
this.originalMaterials = new Map();
this.overrides = new Set();
this.clipPlanes = [];
}
adopt(scene, animations) {
this.clear();
this.root = scene;
this.group.add(scene);
this.byPath = indexByPath(scene);
this.clips = animations || [];
this.mixer = this.clips.length ? new AnimationMixer(scene) : null;
scene.traverse((node) => {
if (node.isMesh || node.isSkinnedMesh) this.originalMaterials.set(node, node.material);
});
}
clear() {
// Put the authored materials back before disposing, so the walk below
// disposes the originals and their textures rather than a tinted clone
// that shares those same textures with nothing left to own them.
this.restore();
if (this.root) {
this.group.remove(this.root);
disposeObject(this.root);
}
this.originalMaterials.clear();
this.byPath.clear();
this.root = null;
this.mixer = null;
this.clips = [];
}
get loaded() {
return Boolean(this.root);
}
// Swap in a generated material while remembering the authored one, so
// toggling highlight off restores exactly what the file shipped.
override(node, build) {
const original = this.originalMaterials.get(node);
if (!original) return;
const source = Array.isArray(original) ? original[0] : original;
const material = build(source);
this.overrides.add(material);
node.material = material;
}
restore() {
for (const [node, material] of this.originalMaterials) node.material = material;
for (const material of this.overrides) material.dispose();
this.overrides.clear();
}
applyClipPlanes(planes) {
this.clipPlanes = planes;
const walk = (material) => {
material.clippingPlanes = planes.length ? planes : null;
material.clipShadows = true;
material.needsUpdate = true;
};
this.group.traverse((node) => {
const materials = Array.isArray(node.material) ? node.material : node.material ? [node.material] : [];
for (const material of materials) walk(material);
});
}
}
/**
* Mount the comparison stage inside `container`.
* @param {HTMLElement} container
*/
export async function createDiffStage(container) {
const renderer = new WebGLRenderer({ antialias: true, powerPreference: 'high-performance' });
renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
renderer.localClippingEnabled = true;
container.appendChild(renderer.domElement);
const scene = new Scene();
scene.background = new Color(0x0a0a0a);
const pmrem = new PMREMGenerator(renderer);
scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture;
scene.add(new AmbientLight(0xffffff, 0.35));
const key = new DirectionalLight(0xffffff, 1.6);
key.position.set(2.5, 4, 3);
scene.add(key);
const camera = new PerspectiveCamera(45, 1, 0.01, 2000);
camera.position.set(0, 1.4, 3.4);
const controls = new OrbitControls(camera, renderer.domElement);
controls.enableDamping = true;
controls.dampingFactor = 0.08;
controls.target.set(0, 0.9, 0);
const sides = { a: new Side('a'), b: new Side('b') };
scene.add(sides.a.group, sides.b.group);
const state = {
mode: 'overlay',
wipe: 0.5,
highlight: true,
playing: false,
// Node paths, straight from the change set: `removed` exists only in the
// baseline, `added` only in the candidate, `edited` in both but different.
removed: new Set(),
added: new Set(),
edited: new Set(),
disposed: false,
visible: true,
};
// Frame delta from the loop's own timestamp. three.js deprecated Clock in
// favour of Timer, and an addon import for one subtraction is not worth the
// bytes on a page that already lazy-loads the whole renderer.
let lastFrame = 0;
const planeA = new Plane();
const planeB = new Plane();
const right = new Vector3();
const seam = new Vector3();
const center = new Vector3();
const size = new Vector3();
const box = new Box3();
// ── Framing ────────────────────────────────────────────────────────────
function unionBox() {
box.makeEmpty();
for (const side of Object.values(sides)) {
if (side.loaded) box.expandByObject(side.root);
}
return box;
}
function frameAll() {
const bounds = unionBox();
if (bounds.isEmpty()) return;
bounds.getCenter(center);
bounds.getSize(size);
const radius = Math.max(size.x, size.y, size.z) * 0.5 || 1;
const distance = (radius / Math.sin((camera.fov * Math.PI) / 360)) * 1.5;
controls.target.copy(center);
camera.position.set(center.x + distance * 0.25, center.y + radius * 0.35, center.z + distance);
camera.near = Math.max(distance / 500, 0.001);
camera.far = distance * 20;
camera.updateProjectionMatrix();
controls.update();
}
function focus(object) {
if (!object) return;
const bounds = new Box3().setFromObject(object);
if (bounds.isEmpty()) return;
const target = new Vector3();
const extent = new Vector3();
bounds.getCenter(target);
bounds.getSize(extent);
const radius = Math.max(extent.x, extent.y, extent.z, 0.05) * 0.5;
const distance = (radius / Math.sin((camera.fov * Math.PI) / 360)) * 2.4;
const direction = camera.position.clone().sub(controls.target).normalize();
controls.target.copy(target);
camera.position.copy(target).addScaledVector(direction, distance);
camera.updateProjectionMatrix();
controls.update();
}
// ── Presentation ───────────────────────────────────────────────────────
function ghostMaterial() {
return new MeshStandardMaterial({
color: COLOR.before,
transparent: true,
opacity: 0.28,
depthWrite: false,
roughness: 0.9,
metalness: 0,
});
}
// Marking a change by REPLACING the material with a flat colour destroys the
// thing you came to look at: two unrelated avatars end up as a red blob and a
// green blob. So the authored material is cloned and only its emissive is
// pushed to the marker colour. The model still looks like itself, and the
// changed parts glow. Cloning shares the source textures, and Material
// .dispose() never touches them, so the clone is free to throw away.
function tintMaterial(source, color, opacity = 1) {
const material = source && typeof source.clone === 'function' ? source.clone() : new MeshStandardMaterial();
if (material.emissive) {
material.emissive = new Color(color);
material.emissiveIntensity = 0.6;
material.emissiveMap = null;
} else {
material.color = new Color(color);
}
if (opacity < 1) {
material.transparent = true;
material.opacity = opacity;
material.depthWrite = false;
}
return material;
}
// Which objects wear which colour is decided here and nowhere else, so the
// legend, the report rows, and the viewport always agree.
function paint() {
for (const side of Object.values(sides)) side.restore();
if (!sides.a.loaded || !sides.b.loaded) return;
const ghostA = state.mode === 'overlay';
for (const [path, object] of sides.a.byPath) {
const removed = state.highlight && state.removed.has(path);
if (!ghostA && !removed) continue;
object.traverse((node) => {
if (!node.isMesh && !node.isSkinnedMesh) return;
if (removed) sides.a.override(node, (source) => tintMaterial(source, COLOR.removed, ghostA ? 0.5 : 1));
else sides.a.override(node, ghostMaterial);
});
}
if (!state.highlight) return;
for (const [path, object] of sides.b.byPath) {
const isAdded = state.added.has(path);
if (!isAdded && !state.edited.has(path)) continue;
object.traverse((node) => {
if (!node.isMesh && !node.isSkinnedMesh) return;
sides.b.override(node, (source) => tintMaterial(source, isAdded ? COLOR.added : COLOR.changed));
});
}
}
function layout() {
const bounds = unionBox();
bounds.getSize(size);
const separation = state.mode === 'split' ? Math.max(size.x, 0.5) * 0.62 : 0;
sides.a.group.position.x = -separation;
sides.b.group.position.x = separation;
if (state.mode === 'wipe') {
sides.a.applyClipPlanes([planeA]);
sides.b.applyClipPlanes([planeB]);
} else {
sides.a.applyClipPlanes([]);
sides.b.applyClipPlanes([]);
}
paint();
}
function updateWipePlanes() {
if (state.mode !== 'wipe') return;
unionBox().getCenter(center);
right.setFromMatrixColumn(camera.matrixWorld, 0).normalize();
const distance = camera.position.distanceTo(center);
const halfWidth = Math.tan((camera.fov * Math.PI) / 360) * distance * camera.aspect;
seam.copy(center).addScaledVector(right, (state.wipe - 0.5) * 2 * halfWidth);
planeA.setFromNormalAndCoplanarPoint(right.clone().negate(), seam);
planeB.setFromNormalAndCoplanarPoint(right.clone(), seam);
}
// ── Loop ───────────────────────────────────────────────────────────────
renderer.setAnimationLoop((time) => {
if (state.disposed || !state.visible) {
lastFrame = time;
return;
}
const delta = lastFrame ? Math.min((time - lastFrame) / 1000, 0.1) : 0;
lastFrame = time;
if (state.playing) {
for (const side of Object.values(sides)) side.mixer?.update(delta);
}
controls.update();
updateWipePlanes();
renderer.render(scene, camera);
});
function resize() {
const width = container.clientWidth || 1;
const height = container.clientHeight || 1;
renderer.setSize(width, height, false);
camera.aspect = width / height;
camera.updateProjectionMatrix();
}
const resizeObserver = new ResizeObserver(resize);
resizeObserver.observe(container);
resize();
// A WebGL loop running against an off-screen canvas is pure battery drain on
// a page whose report is long enough to scroll the viewer away.
const visibility = new IntersectionObserver(
(entries) => {
state.visible = entries.some((entry) => entry.isIntersecting);
},
{ threshold: 0.01 },
);
visibility.observe(container);
return {
/**
* Load one side from raw bytes.
* @param {'a'|'b'} role
* @param {ArrayBuffer} buffer
*/
async setModel(role, buffer) {
const loader = await getLoader();
const gltf = await loader.parseAsync(buffer.slice(0), '');
sides[role].adopt(gltf.scene, gltf.animations);
frameAll();
layout();
return { clips: gltf.animations.map((clip) => clip.name) };
},
/**
* Colour the viewport from a change set: which node paths were removed
* from the baseline, and which were added or edited in the candidate.
*/
applyChangeSet(changeset) {
state.removed = new Set(changeset.sections.nodes.removed.map((item) => item.name));
state.added = new Set(changeset.sections.nodes.added.map((item) => item.name));
state.edited = new Set([
...changeset.sections.nodes.modified.map((item) => item.name),
...changeset.sections.nodes.moved.map((item) => item.to),
]);
paint();
},
setMode(mode) {
state.mode = mode;
layout();
},
setWipe(fraction) {
state.wipe = Math.min(1, Math.max(0, fraction));
},
setHighlight(on) {
state.highlight = Boolean(on);
paint();
},
setPlaying(on) {
state.playing = Boolean(on);
for (const side of Object.values(sides)) {
if (!side.mixer) continue;
if (on) {
side.mixer.stopAllAction();
const clip = side.clips[0];
if (clip) side.mixer.clipAction(clip).reset().play();
} else {
side.mixer.stopAllAction();
}
}
},
hasClips() {
return sides.a.clips.length > 0 || sides.b.clips.length > 0;
},
/** Frame one node by its diff path. Falls back to the other side when only one has it. */
focusPath(path) {
focus(sides.b.byPath.get(path) || sides.a.byPath.get(path));
},
frameAll,
dispose() {
state.disposed = true;
renderer.setAnimationLoop(null);
resizeObserver.disconnect();
visibility.disconnect();
controls.dispose();
for (const side of Object.values(sides)) side.clear();
pmrem.dispose();
scene.environment?.dispose();
renderer.dispose();
renderer.domElement.remove();
},
};
}