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
// Anatomy spec: the declarative description of a machine that Claude writes
// and the viewer renders.
//
// One contract for every producer and consumer: the server writer (api/anatomy)
// validates what the model streams, the browser runtime renders it, and the
// `anatomy` agent skill authors it directly. Nothing here imports three.js, so
// the same normalizer runs in Node and the browser.
//
// normalizeSpec() is deliberately forgiving: a model that writes 160 good parts
// and one bad one gets 160 parts and a warning, not an error. Every number is
// clamped to a sane range and every string is length-capped, so a stored spec
// can never make the viewer allocate unbounded geometry. A spec is only
// rejected when nothing renderable survives.
export const SPEC_VERSION = 1;
export const LIMITS = Object.freeze({
parts: 220,
effects: 40,
flows: 24,
steps: 14,
pathPoints: 64,
profilePoints: 64,
repeat: 96,
motions: 3,
gearTeeth: 160,
rotorBlades: 64,
springTurns: 60,
particles: 600,
title: 80,
subtitle: 140,
summary: 600,
name: 60,
description: 420,
stepBody: 520,
group: 40,
id: 48,
});
export const AXES = Object.freeze(['x', 'y', 'z']);
export const SHAPE_TYPES = Object.freeze([
'box',
'cylinder',
'tube',
'cone',
'sphere',
'capsule',
'torus',
'gear',
'rotor',
'lathe',
'extrude',
'spring',
'pipe',
]);
export const PART_STYLES = Object.freeze(['solid', 'wire', 'glass', 'ghost']);
export const MOTION_TYPES = Object.freeze(['spin', 'oscillate', 'crank', 'pulse']);
export const EFFECT_TYPES = Object.freeze(['flame', 'exhaust', 'plasma', 'water', 'smoke', 'steam', 'sparks', 'electric', 'glow']);
// The largest coordinate a spec may use. Machines are authored at roughly
// 1 to 20 units across; the viewer frames whatever it gets, this only stops a
// stray 1e9 from destroying the bounding box.
const MAX_COORD = 500;
export class AnatomySpecError extends Error {
constructor(message, warnings = []) {
super(message);
this.code = 'invalid_spec';
this.warnings = warnings;
}
}
const isObj = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
function num(v, def, min, max) {
const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v;
if (typeof n !== 'number' || !Number.isFinite(n)) return def;
return Math.min(max, Math.max(min, n));
}
function int(v, def, min, max) {
return Math.round(num(v, def, min, max));
}
function text(v, max, def = '') {
if (typeof v !== 'string') return def;
const s = v.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '').replace(/\s+/g, ' ').trim();
return s.length > max ? `${s.slice(0, max - 1).trimEnd()}…` : s;
}
// Step bodies and descriptions keep paragraph breaks.
function prose(v, max) {
if (typeof v !== 'string') return '';
const s = v
.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, '')
.split(/\n{2,}/)
.map((p) => p.replace(/\s+/g, ' ').trim())
.filter(Boolean)
.join('\n\n');
return s.length > max ? `${s.slice(0, max - 1).trimEnd()}…` : s;
}
const HEX_RE = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i;
export function color(v, def = null) {
if (typeof v !== 'string') return def;
const m = HEX_RE.exec(v.trim());
if (!m) return def;
const h = m[1].length === 3 ? m[1].replace(/./g, (c) => c + c) : m[1];
return `#${h.toLowerCase()}`;
}
function vec3(v, def = [0, 0, 0], lim = MAX_COORD) {
if (!Array.isArray(v) || v.length < 3) return def;
const out = v.slice(0, 3).map((x) => num(x, NaN, -lim, lim));
return out.some(Number.isNaN) ? def : out;
}
function axis(v, def = 'y') {
const a = typeof v === 'string' ? v.trim().toLowerCase().replace(/^[-+]/, '') : '';
return AXES.includes(a) ? a : def;
}
// Ids are referenced by parent links, step focus lists and URLs in the
// viewer, so they are normalized to a safe slug.
export function slugId(v) {
if (typeof v !== 'string' && typeof v !== 'number') return '';
return String(v)
.toLowerCase()
.replace(/[^a-z0-9_-]+/g, '-')
.replace(/^-+|-+$/g, '')
.slice(0, LIMITS.id);
}
function points2(v, max, lim = MAX_COORD) {
if (!Array.isArray(v)) return [];
const out = [];
for (const p of v.slice(0, max)) {
if (!Array.isArray(p) || p.length < 2) continue;
const a = num(p[0], NaN, -lim, lim);
const b = num(p[1], NaN, -lim, lim);
if (Number.isNaN(a) || Number.isNaN(b)) continue;
out.push([a, b]);
}
return out;
}
function points3(v, max) {
if (!Array.isArray(v)) return [];
const out = [];
for (const p of v.slice(0, max)) {
const q = vec3(p, null);
if (q) out.push(q);
}
return out;
}
const pos = (v, def) => num(v, def, 0.001, MAX_COORD);
function normalizeShape(raw, warn, where) {
if (!isObj(raw)) {
warn(`${where}: missing shape, used a box`);
return { type: 'box', size: [1, 1, 1], radius: 0 };
}
const type = String(raw.type || '').toLowerCase();
const ax = axis(raw.axis);
switch (type) {
case 'box': {
const size = Array.isArray(raw.size) ? vec3(raw.size, [1, 1, 1]).map((s) => Math.max(0.001, Math.abs(s))) : [pos(raw.width, 1), pos(raw.height, 1), pos(raw.depth, 1)];
return { type, size, radius: num(raw.radius, 0, 0, Math.min(...size) / 2) };
}
case 'cylinder': {
const r = pos(raw.radius, 0.5);
return {
type,
axis: ax,
radiusTop: pos(raw.radiusTop, r),
radiusBottom: pos(raw.radiusBottom, r),
length: pos(raw.length ?? raw.height, 1),
open: raw.open === true,
};
}
case 'tube': {
const outer = pos(raw.outerRadius ?? raw.radius, 0.5);
return { type, axis: ax, outerRadius: outer, innerRadius: num(raw.innerRadius, outer * 0.8, 0.001, outer * 0.995), length: pos(raw.length ?? raw.height, 1) };
}
case 'cone':
return { type, axis: ax, radius: pos(raw.radius, 0.5), length: pos(raw.length ?? raw.height, 1) };
case 'sphere':
return { type, radius: pos(raw.radius, 0.5), hemisphere: raw.hemisphere === true, axis: ax };
case 'capsule':
return { type, axis: ax, radius: pos(raw.radius, 0.3), length: pos(raw.length ?? raw.height, 1) };
case 'torus': {
const r = pos(raw.radius, 1);
return { type, axis: ax, radius: r, tube: num(raw.tube, r * 0.2, 0.001, r), arc: num(raw.arc, 360, 1, 360) };
}
case 'gear': {
const r = pos(raw.radius, 1);
return {
type,
axis: ax,
teeth: int(raw.teeth, 18, 4, LIMITS.gearTeeth),
radius: r,
toothDepth: num(raw.toothDepth, r * 0.12, 0.001, r * 0.6),
thickness: pos(raw.thickness, r * 0.25),
bore: num(raw.bore, r * 0.2, 0, r * 0.85),
};
}
case 'rotor': {
const r = pos(raw.radius, 1);
return {
type,
axis: ax,
blades: int(raw.blades, 12, 1, LIMITS.rotorBlades),
radius: r,
hubRadius: num(raw.hubRadius, r * 0.25, 0.001, r * 0.95),
chord: pos(raw.chord, r * 0.3),
thickness: pos(raw.thickness, r * 0.03),
twist: num(raw.twist, 25, -89, 89),
pitch: num(raw.pitch, 30, -89, 89),
hubLength: pos(raw.hubLength, r * 0.3),
};
}
case 'lathe': {
const profile = points2(raw.profile, LIMITS.profilePoints).map(([r, a]) => [Math.abs(r), a]);
if (profile.length < 2) {
warn(`${where}: lathe needs 2+ profile points, used a cylinder`);
return { type: 'cylinder', axis: ax, radiusTop: 0.5, radiusBottom: 0.5, length: 1, open: false };
}
return { type, axis: ax, profile };
}
case 'extrude': {
const points = points2(raw.points, LIMITS.profilePoints);
if (points.length < 3) {
warn(`${where}: extrude needs 3+ points, used a box`);
return { type: 'box', size: [1, 1, 0.2], radius: 0 };
}
return { type, axis: axis(raw.axis, 'z'), points, depth: pos(raw.depth, 0.2) };
}
case 'spring': {
const r = pos(raw.radius, 0.4);
return { type, axis: ax, radius: r, wire: num(raw.wire, r * 0.12, 0.001, r), turns: num(raw.turns, 6, 0.5, LIMITS.springTurns), length: pos(raw.length ?? raw.height, 1) };
}
case 'pipe': {
const path = points3(raw.path, LIMITS.pathPoints);
if (path.length < 2) {
warn(`${where}: pipe needs 2+ path points, used a cylinder`);
return { type: 'cylinder', axis: ax, radiusTop: 0.1, radiusBottom: 0.1, length: 1, open: false };
}
return { type, path, radius: pos(raw.radius, 0.08), closed: raw.closed === true };
}
default:
warn(`${where}: unknown shape "${type}", used a box`);
return { type: 'box', size: vec3(raw.size, [1, 1, 1]).map((s) => Math.max(0.001, Math.abs(s))), radius: 0 };
}
}
function normalizeMotion(raw, warn, where) {
const list = Array.isArray(raw) ? raw : isObj(raw) ? [raw] : [];
const out = [];
for (const m of list.slice(0, LIMITS.motions)) {
if (!isObj(m)) continue;
const type = String(m.type || '').toLowerCase();
const phase = num(m.phase, 0, -36000, 36000);
if (type === 'spin') out.push({ type, axis: axis(m.axis), speed: num(m.speed, 0.5, -60, 60), phase });
else if (type === 'oscillate')
out.push({
type,
axis: axis(m.axis),
kind: m.kind === 'rotate' ? 'rotate' : 'translate',
amplitude: num(m.amplitude, m.kind === 'rotate' ? 20 : 0.2, -MAX_COORD, MAX_COORD),
frequency: num(m.frequency, 1, 0, 60),
phase,
});
else if (type === 'crank') {
const radius = pos(m.radius, 0.3);
out.push({ type, axis: axis(m.axis), radius, rod: num(m.rod, radius * 3, radius * 1.05, MAX_COORD), speed: num(m.speed, 1, -60, 60), phase });
} else if (type === 'pulse') out.push({ type, amplitude: num(m.amplitude, 0.06, 0, 2), frequency: num(m.frequency, 1, 0, 60), phase });
else warn(`${where}: unknown motion "${type}" dropped`);
}
return out;
}
function normalizeRepeat(raw) {
if (!isObj(raw)) return null;
const count = int(raw.count, 1, 1, LIMITS.repeat);
if (count < 2) return null;
if (Array.isArray(raw.offset)) return { count, mode: 'linear', offset: vec3(raw.offset, [1, 0, 0]) };
return { count, mode: 'radial', axis: axis(raw.axis), angle: num(raw.angle, 360, 1, 360) };
}
function uniqueId(base, used, fallback) {
let id = slugId(base) || fallback;
if (!used.has(id)) {
used.add(id);
return id;
}
let n = 2;
while (used.has(`${id}-${n}`)) n++;
id = `${id}-${n}`;
used.add(id);
return id;
}
function normalizePart(raw, i, used, warn) {
const where = `part ${raw?.id || i + 1}`;
const id = uniqueId(raw.id ?? raw.name, used, `part-${i + 1}`);
const style = PART_STYLES.includes(raw.style) ? raw.style : 'solid';
return {
id,
name: text(raw.name, LIMITS.name) || id,
description: prose(raw.description, LIMITS.description),
group: text(raw.group, LIMITS.group),
parent: raw.parent == null || raw.parent === '' ? null : slugId(raw.parent),
shape: normalizeShape(raw.shape, warn, where),
position: vec3(raw.position),
rotation: vec3(raw.rotation, [0, 0, 0], 36000),
scale: Array.isArray(raw.scale) ? vec3(raw.scale, [1, 1, 1]).map((s) => (Math.abs(s) < 0.001 ? 1 : s)) : [1, 1, 1],
color: color(raw.color, null),
style,
glow: num(raw.glow, 0, 0, 1),
repeat: normalizeRepeat(raw.repeat),
motion: normalizeMotion(raw.motion, warn, where),
explode: Array.isArray(raw.explode) ? vec3(raw.explode) : null,
label: raw.label === false ? false : raw.label === true ? true : null,
};
}
const EFFECT_DEFAULTS = Object.freeze({
flame: ['#ffd27a', '#ff4d1a'],
exhaust: ['#e8f4ff', '#4f8dff'],
plasma: ['#f3d9ff', '#9b4dff'],
water: ['#bfe6ff', '#1f7ae0'],
smoke: ['#9a9a9a', '#5c5c5c'],
steam: ['#ffffff', '#cfd8e0'],
sparks: ['#fff3b0', '#ff9a1f'],
electric: ['#e6f4ff', '#55aaff'],
glow: ['#ffe8a8', '#ff8a1f'],
});
function normalizeEffect(raw, i, used, warn) {
const type = String(raw.type || '').toLowerCase();
if (!EFFECT_TYPES.includes(type)) {
warn(`effect ${raw.id || i + 1}: unknown type "${type}" dropped`);
return null;
}
const [c1, c2] = EFFECT_DEFAULTS[type];
const radius = pos(raw.radius, 0.3);
const eff = {
id: uniqueId(raw.id ?? `${type}-${i + 1}`, used, `${type}-${i + 1}`),
type,
name: text(raw.name, LIMITS.name) || type[0].toUpperCase() + type.slice(1),
description: prose(raw.description, LIMITS.description),
parent: raw.parent == null || raw.parent === '' ? null : slugId(raw.parent),
position: vec3(raw.position),
axis: axis(raw.axis),
direction: num(raw.direction, 1, -1, 1) < 0 ? -1 : 1,
radius,
radiusEnd: num(raw.radiusEnd, type === 'flame' ? radius * 0.15 : radius, 0, MAX_COORD),
length: pos(raw.length, 1),
size: Array.isArray(raw.size) ? vec3(raw.size, null)?.map((s) => Math.max(0.001, Math.abs(s))) || null : null,
color: color(raw.color, c1),
color2: color(raw.color2, c2),
intensity: num(raw.intensity, 1, 0, 3),
speed: num(raw.speed, 1, 0, 10),
count: int(raw.count, type === 'sparks' ? 120 : 160, 8, LIMITS.particles),
};
if (type === 'electric') {
eff.from = vec3(raw.from, [0, 0, 0]);
eff.to = vec3(raw.to, [0, eff.length, 0]);
}
return eff;
}
function normalizeFlow(raw, i, used, warn) {
const path = points3(raw.path, LIMITS.pathPoints);
if (path.length < 2) {
warn(`flow ${raw.id || i + 1}: needs 2+ path points, dropped`);
return null;
}
return {
id: uniqueId(raw.id ?? raw.name ?? `flow-${i + 1}`, used, `flow-${i + 1}`),
name: text(raw.name, LIMITS.name) || `Flow ${i + 1}`,
description: prose(raw.description, LIMITS.description),
path,
color: color(raw.color, '#3fa9ff'),
speed: num(raw.speed, 0.4, 0.01, 10),
count: int(raw.count, 40, 4, 240),
size: num(raw.size, 1, 0.2, 5),
closed: raw.closed === true,
};
}
/**
* Validate and normalize a raw spec. Returns { spec, warnings }.
* Throws AnatomySpecError only when nothing renderable is left.
*/
export function normalizeSpec(raw, { strict = true } = {}) {
const warnings = [];
const warn = (m) => {
if (warnings.length < 60) warnings.push(m);
};
if (!isObj(raw)) throw new AnatomySpecError('The spec must be a JSON object.');
const used = new Set();
const parts = [];
for (const [i, p] of (Array.isArray(raw.parts) ? raw.parts : []).entries()) {
if (parts.length >= LIMITS.parts) {
warn(`more than ${LIMITS.parts} parts; the rest were dropped`);
break;
}
if (isObj(p)) parts.push(normalizePart(p, i, used, warn));
}
// Parent links must point at an earlier-or-later real part and must not
// form a cycle; anything else is re-rooted so the part still renders.
const byId = new Map(parts.map((p) => [p.id, p]));
for (const p of parts) {
if (p.parent && (!byId.has(p.parent) || p.parent === p.id)) {
warn(`part ${p.id}: parent "${p.parent}" not found, attached to the root`);
p.parent = null;
}
}
for (const p of parts) {
const seen = new Set([p.id]);
let cur = p.parent;
while (cur) {
if (seen.has(cur)) {
warn(`part ${p.id}: parent cycle broken`);
p.parent = null;
break;
}
seen.add(cur);
cur = byId.get(cur)?.parent || null;
}
}
const effects = [];
for (const [i, e] of (Array.isArray(raw.effects) ? raw.effects : []).slice(0, LIMITS.effects).entries()) {
if (!isObj(e)) continue;
const eff = normalizeEffect(e, i, used, warn);
if (!eff) continue;
if (eff.parent && !byId.has(eff.parent)) {
warn(`effect ${eff.id}: parent "${eff.parent}" not found, attached to the root`);
eff.parent = null;
}
effects.push(eff);
}
const flows = [];
for (const [i, f] of (Array.isArray(raw.flows) ? raw.flows : []).slice(0, LIMITS.flows).entries()) {
if (!isObj(f)) continue;
const flow = normalizeFlow(f, i, used, warn);
if (flow) flows.push(flow);
}
if (strict && !parts.length) throw new AnatomySpecError('The spec has no renderable parts.', warnings);
const known = new Set([...parts.map((p) => p.id), ...effects.map((e) => e.id), ...flows.map((f) => f.id)]);
const steps = [];
for (const s of (Array.isArray(raw.steps) ? raw.steps : []).slice(0, LIMITS.steps)) {
if (!isObj(s)) continue;
const title = text(s.title, LIMITS.name);
const body = prose(s.body ?? s.text, LIMITS.stepBody);
if (!title && !body) continue;
const focus = (Array.isArray(s.focus) ? s.focus : [])
.map(slugId)
.filter((id) => {
if (known.has(id)) return true;
if (id) warn(`step "${title}": unknown focus id "${id}" ignored`);
return false;
});
steps.push({ title: title || `Step ${steps.length + 1}`, body, focus: [...new Set(focus)] });
}
const view = isObj(raw.view) ? raw.view : {};
const spec = {
version: SPEC_VERSION,
title: text(raw.title, LIMITS.title) || 'Untitled machine',
subtitle: text(raw.subtitle, LIMITS.subtitle),
summary: prose(raw.summary, LIMITS.summary),
parts,
effects,
flows,
steps,
view: {
speed: num(view.speed, 1, 0, 4),
explode: num(view.explode, 0, 0, 1),
section: view.section === 'x' || view.section === 'y' || view.section === 'z' ? view.section : null,
},
};
return { spec, warnings };
}
/** Counts that describe a spec in one line (gallery cards, MCP results). */
export function specStats(spec) {
let moving = 0;
let instances = 0;
for (const p of spec.parts || []) {
const n = p.repeat?.count || 1;
instances += n;
if (p.motion?.length) moving += n;
}
return {
parts: spec.parts?.length || 0,
instances,
moving,
effects: spec.effects?.length || 0,
flows: spec.flows?.length || 0,
steps: spec.steps?.length || 0,
};
}
/**
* Pull a JSON object out of a model completion: a ```json fence if there is
* one, otherwise the outermost {...}. Returns the parsed value or null.
*/
export function extractSpecJson(textIn) {
const source = String(textIn || '');
const fenced = /```(?:json)?[ \t]*\n([\s\S]*?)```/i.exec(source);
const candidates = [];
if (fenced) candidates.push(fenced[1]);
const first = source.indexOf('{');
const last = source.lastIndexOf('}');
if (first !== -1 && last > first) candidates.push(source.slice(first, last + 1));
for (const c of candidates) {
try {
return JSON.parse(c);
} catch {
/* try the next candidate */
}
}
return null;
}