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 service: the operations every transport shares.
//
// api/anatomy.js (the /anatomy page) and the anatomy_* MCP tools both call
// these, so a machine written on the page and one published by an agent are
// the same record with the same permalink.
import { AnatomySpecError, extractSpecJson, normalizeSpec, specStats } from '../../../src/anatomy/spec.js';
import { scanPartialSpec } from '../../../src/anatomy/stream.js';
import { OUTPUT_RULES, SPEC_GUIDE } from './guide.js';
import { streamSpec } from './writer.js';
import { anatomyStoreEnabled, getDesign, newDesignId, saveDesign } from './store.js';
const SITE = process.env.PUBLIC_BASE_URL || 'https://three.ws';
export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
export const MAX_PROMPT_LEN = 600;
export const MAX_SPEC_BYTES = 400_000;
// A spec cut off by the token limit still carries every part that finished.
// Past this many, the salvaged machine is worth showing rather than retrying.
const SALVAGE_MIN_PARTS = 12;
export class AnatomyError extends Error {
constructor(code, message, status = 400, detail = null) {
super(message);
this.code = code;
this.status = status;
this.detail = detail;
}
}
export function designUrl(id) {
return `${SITE}/anatomy/${id}`;
}
export function publicDesign(design) {
return { ...design, url: design.id ? designUrl(design.id) : null };
}
export function cleanPrompt(raw) {
const prompt = String(raw ?? '')
.replace(/^\s*\/anatomy\s+/i, '')
.replace(/\s+/g, ' ')
.trim()
.slice(0, MAX_PROMPT_LEN);
if (prompt.length < 3) throw new AnatomyError('prompt_required', 'Describe the machine you want to see.', 400);
return prompt;
}
export function systemPrompt() {
return [
'You are Anatomy, an engineer and illustrator who explains how machines work by building them as interactive 3D cutaways.',
'Given a request, design the machine as an Anatomy spec: accurate geometry, the real moving parts in motion, the physics made visible with effects and flows, and a guided tour that teaches it step by step.',
'Write for a curious, smart reader who is not an engineer: plain words, concrete numbers, no filler. Never use the em dash or en dash characters.',
SPEC_GUIDE,
OUTPUT_RULES,
].join('\n\n');
}
function userMessage(prompt) {
return `Build this machine: ${prompt}\n\nIf the request names a specific real machine, model it on that machine. If it is vague, choose the most iconic real example and say which in the subtitle.`;
}
/**
* Turn model text into a normalized spec. Tries the whole document first,
* then salvages every complete element when the text was cut short.
* Returns { spec, warnings, salvaged } or throws AnatomySpecError.
*/
export function parseSpecText(text) {
const raw = extractSpecJson(text);
if (raw) return { ...normalizeSpec(raw), salvaged: false };
const partial = scanPartialSpec(text);
if (partial.parts.length >= SALVAGE_MIN_PARTS) {
const { spec, warnings } = normalizeSpec(partial);
return { spec, warnings: ['The model ran out of room; the machine shows every part it finished.', ...warnings], salvaged: true };
}
throw new AnatomySpecError(partial.parts.length ? `The spec was cut off after ${partial.parts.length} parts.` : 'The model did not return a JSON spec.');
}
function specSize(spec) {
return Buffer.byteLength(JSON.stringify(spec), 'utf8');
}
async function persist({ spec, prompt, source, model, user }) {
const design = {
id: newDesignId(),
title: spec.title,
subtitle: spec.subtitle,
prompt,
spec,
stats: specStats(spec),
source,
model,
userId: user?.id ?? null,
};
const saved = await saveDesign(design);
if (saved) return publicDesign(saved);
// Storage off or a failed write: the visitor still gets their machine, it
// just has no permalink. The page says so instead of showing a dead link.
const { userId: _omit, ...rest } = design;
return publicDesign({ ...rest, id: null, views: 0, creatorUsername: null, createdAt: new Date().toISOString() });
}
/**
* Write a machine with Claude, streaming it as it is written. Events:
* { type: 'stage', stage: 'writing' | 'repairing' | 'saving' }
* { type: 'delta', text } raw model text, to render progressively
* { type: 'reset' } discard the text so far (a rung died mid-way)
* Returns { design, warnings }.
*/
export async function generateDesign({ prompt, user = null, onEvent = () => {} }) {
const system = systemPrompt();
const messages = [{ role: 'user', content: userMessage(prompt) }];
const track = { userId: user?.id ?? null };
onEvent({ type: 'stage', stage: 'writing' });
let written = await streamSpec({
system,
messages,
track,
onDelta: (text) => onEvent({ type: 'delta', text }),
onReset: () => onEvent({ type: 'reset' }),
});
let parsed;
try {
parsed = parseSpecText(written.text);
} catch (err) {
// One repair round: show the model exactly what failed and ask for the
// whole object again. The client discards the first attempt.
onEvent({ type: 'stage', stage: 'repairing', reason: err.message });
onEvent({ type: 'reset' });
const truncated = written.stopReason === 'max_tokens' || written.stopReason === 'length';
const fix = truncated
? 'Your answer was cut off before the JSON closed. Write the complete spec again, more compactly: fewer, well-chosen parts (use repeat and parent hierarchies instead of listing copies) and shorter descriptions, so it fits.'
: `Your answer could not be used: ${err.message} Write the complete spec again as one valid JSON object.`;
written = await streamSpec({
system,
messages: [...messages, { role: 'assistant', content: written.text.slice(0, 60_000) || '{}' }, { role: 'user', content: `${fix}\n\n${OUTPUT_RULES}` }],
track,
onDelta: (text) => onEvent({ type: 'delta', text }),
onReset: () => onEvent({ type: 'reset' }),
});
try {
parsed = parseSpecText(written.text);
} catch (again) {
throw new AnatomyError('spec_failed', 'The model could not produce a working machine for that. Try rephrasing it, or name a specific machine.', 502, again.message);
}
}
if (specSize(parsed.spec) > MAX_SPEC_BYTES) throw new AnatomyError('spec_too_large', 'That machine came out too large to save. Try a narrower request.', 422);
onEvent({ type: 'stage', stage: 'saving' });
const design = await persist({ spec: parsed.spec, prompt, source: 'generated', model: written.model ? `${written.provider}:${written.model}` : null, user });
return { design, warnings: parsed.warnings };
}
/**
* Save a spec an agent wrote itself (the anatomy skill, MCP). No model call.
* Returns { design, warnings }.
*/
export async function publishDesign({ spec: raw, prompt = null, user = null }) {
let input = raw;
if (typeof input === 'string') {
input = extractSpecJson(input);
if (!input) throw new AnatomyError('invalid_spec', 'spec must be a JSON object (or a string holding one).', 400);
}
let normalized;
try {
normalized = normalizeSpec(input);
} catch (err) {
throw new AnatomyError('invalid_spec', err.message, 400, err.warnings || null);
}
if (specSize(normalized.spec) > MAX_SPEC_BYTES) throw new AnatomyError('spec_too_large', `The spec is over ${MAX_SPEC_BYTES / 1000} KB after normalizing.`, 413);
if (!anatomyStoreEnabled()) throw new AnatomyError('storage_unavailable', 'Publishing needs the database, which is not configured on this deployment.', 503);
const cleanedPrompt = prompt ? String(prompt).replace(/\s+/g, ' ').trim().slice(0, MAX_PROMPT_LEN) || null : null;
const design = await persist({ spec: normalized.spec, prompt: cleanedPrompt, source: 'published', model: null, user });
if (!design.id) throw new AnatomyError('storage_unavailable', 'The design could not be saved right now. Try again.', 503);
return { design, warnings: normalized.warnings };
}
export async function loadDesign(id) {
if (!UUID_RE.test(String(id || ''))) throw new AnatomyError('invalid_id', 'Malformed design id.', 400);
const design = await getDesign(String(id));
if (!design) throw new AnatomyError('not_found', 'No machine with that id.', 404);
return publicDesign(design);
}