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.

16.1 KB
Raw Blame
/**
 * Diorama — speak a little world into being.
 *
 *   POST /api/diorama  { action:'compose', prompt }     → a diorama PLAN
 *       Decomposes one sentence into a placed set of single-object forge prompts
 *       plus a mood/palette/ground, using the platform's free-first LLM chain.
 *       Returns objects with status:'pending' and no meshes — the browser then
 *       forges each one on /api/forge and watches the world assemble.
 *
 *   POST /api/diorama  { action:'save', diorama, clientKey? } → { id, url }
 *       Persists a fully-forged world so it gets a permalink + gallery slot.
 *
 *   POST /api/diorama  { action:'export', diorama }       → { glbUrl, sceneStudioUrl, … }
 *       Merges an already-forged diorama's objects + ground + lights into ONE
 *       GLB (api/_lib/scene-graph-compose.js) and uploads it — a single file
 *       with named, selectable nodes that opens cleanly in Scene Studio
 *       (/scene) or any glTF viewer. 503 when object storage isn't configured.
 *
 *   POST /api/diorama  { action:'build', prompt }         → { diorama, glbUrl?, … }
 *       Headless one-shot: compose the plan, forge every object on the free
 *       lane, then export the merged GLB — all server-side, for callers with
 *       no browser to drive the progressive client flow (MCP tools, agents).
 *
 *   GET  /api/diorama?id=<uuid>                          → { diorama }
 *   GET  /api/diorama?list=recent|featured&limit=<n>     → { dioramas:[card] }
 *
 * No mocks: when the LLM chain is unreachable the compose route returns a clean
 * 503 and the page renders a designed retry state — it never fabricates a world.
 */

import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { llmComplete, llmConfigured } from './_lib/llm.js';
import { saveDiorama, getDiorama, listDioramas, bumpViews, dioramaStoreEnabled } from './_lib/diorama-store.js';
import { getSessionUser } from './_lib/auth.js';
import {
	exportDioramaGlb,
	dioramaExportStoreEnabled,
	composePlanFromPrompt,
	forgeDioramaObjects,
} from './_lib/diorama-build.js';
import {
	normalizeDiorama,
	MIN_OBJECTS,
	MAX_OBJECTS,
	MAX_PROMPT_LEN,
	ISLAND_RADIUS,
} from '../src/diorama/schema.js';

const SITE = process.env.PUBLIC_BASE_URL || 'https://three.ws';

const COMPOSE_SYSTEM = `You are a 3D set designer. You turn ONE short sentence into a tiny diorama — a miniature scene that sits on a small floating island a viewer can orbit.

Return ONLY a JSON object (no prose, no markdown fence) with exactly this shape:
{
  "title": "2-4 word evocative title",
  "mood": one of "dawn" | "day" | "dusk" | "night",
  "ground": one of "grass" | "sand" | "snow" | "stone" | "water" | "meadow" | "void",
  "island": one of "round" | "craggy" | "plateau",
  "palette": { "sky": ["#RRGGBB","#RRGGBB"], "ground": "#RRGGBB", "fog": "#RRGGBB", "accent": "#RRGGBB" },
  "objects": [ { "label": "short", "prompt": "ONE physical object: subject + key material + color", "position": [x, 0, z], "scale": 0.5-2.5, "rotationY": radians } ]
}

Rules:
- ${MIN_OBJECTS} to ${MAX_OBJECTS} objects. Each "prompt" describes exactly ONE isolated physical object (a single tree, a single tent) — never a scene, never "and", never people unless one figure is the whole subject. Lead with the subject, then its dominant material and color, ≤ 12 words.
- Spread objects across the island: x and z each between -${ISLAND_RADIUS - 1} and ${ISLAND_RADIUS - 1}, keep at least 1.5 between any two, never stack them. y is always 0. One object may sit near the center as a focal point.
- "palette" sky is a 2-stop vertical gradient (top, horizon). Pick colors that match the mood and the scene. "accent" is the warm/cool glow color.
- Choose mood + ground that fit the sentence (a beach → sand/day, a haunted forest → night/grass).
- Output MUST be valid JSON. No trailing commas. No comments.`;

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
	// `method()` returns TRUE when the verb is allowed (and answers 405 itself
	// otherwise), so the guard must be negated. Gate before the GET dispatch so a
	// HEAD probe is normalized to GET in here rather than falling through to a 405.
	if (!method(req, res, ['GET', 'POST'])) return;

	if (req.method === 'GET') return handleGet(req, res);

	const body = await readJson(req).catch(() => null);
	if (!body || typeof body !== 'object') {
		return json(res, 400, { error: 'invalid_body', message: 'Send a JSON body.' });
	}

	if (body.action === 'compose') return handleCompose(req, res, body);
	if (body.action === 'save') return handleSave(req, res, body);
	if (body.action === 'export') return handleExport(req, res, body);
	if (body.action === 'build') return handleBuild(req, res, body);
	return json(res, 400, {
		error: 'unknown_action',
		message: 'action must be "compose", "save", "export", or "build".',
	});
});

async function handleGet(req, res) {
	const url = new URL(req.url, 'http://x');
	const id = url.searchParams.get('id');
	const list = url.searchParams.get('list');

	if (id) {
		const diorama = await getDiorama(id);
		if (!diorama) {
			return json(res, 404, { error: 'not_found', message: 'No diorama with that id.' });
		}
		bumpViews(id); // fire and forget
		return json(res, 200, { diorama }, { 'cache-control': 'public, max-age=30, s-maxage=300' });
	}

	if (list !== null) {
		const scope = list === 'featured' ? 'featured' : 'recent';
		const limit = Number(url.searchParams.get('limit')) || 24;
		const dioramas = await listDioramas({ scope, limit });
		return json(
			res,
			200,
			{ dioramas, storage: dioramaStoreEnabled() },
			{ 'cache-control': 'public, max-age=30, s-maxage=120' },
		);
	}

	return json(res, 400, { error: 'bad_request', message: 'Pass ?id= or ?list=.' });
}

async function handleCompose(req, res, body) {
	const prompt = String(body.prompt ?? '').slice(0, MAX_PROMPT_LEN).trim();
	if (prompt.length < 3) {
		return json(res, 400, { error: 'prompt_required', message: 'Describe your world in a sentence.' });
	}
	if (!llmConfigured()) {
		return json(res, 503, {
			error: 'composer_unavailable',
			message: 'The world composer is warming up. Try again in a moment.',
		});
	}

	// Compose runs a paid LLM completion — gate per IP and behind a global hourly
	// circuit breaker so one caller (or an influx) can't drive unbounded inference
	// spend. The global bucket only trips under a genuine surge or distributed abuse.
	const ip = clientIp(req);
	const rl = await limits.dioramaComposeIp(ip);
	if (!rl.success) {
		return rateLimited(res, rl, 'World composer limit reached. Try again shortly.');
	}
	const globalRl = await limits.dioramaComposeGlobal();
	if (!globalRl.success) {
		return rateLimited(res, globalRl, 'The world composer is at capacity. Try again shortly.');
	}

	let completion;
	try {
		completion = await llmComplete({
			system: COMPOSE_SYSTEM,
			user: `Sentence: "${prompt}"\nReturn the diorama JSON.`,
			maxTokens: 900,
			timeoutMs: 30_000,
			track: { tool: 'diorama-compose' },
		});
	} catch (err) {
		console.error('[diorama] compose llm failed:', err?.message);
		return json(res, 503, {
			error: 'composer_unavailable',
			message: 'The world composer is busy. Try again in a moment.',
		});
	}

	const plan = parseJsonObject(completion?.text);
	if (!plan) {
		return json(res, 502, {
			error: 'compose_unparseable',
			message: 'The composer returned an unexpected shape. Try rephrasing your world.',
		});
	}

	plan.prompt = prompt;
	plan.objects = declump(Array.isArray(plan.objects) ? plan.objects : []);
	const { ok, diorama, errors } = normalizeDiorama(plan);
	if (!ok || diorama.objects.length < 1) {
		return json(res, 502, {
			error: 'compose_invalid',
			message: 'The composer could not place that world. Try a more concrete sentence.',
			detail: errors,
		});
	}
	// Force a clean pending plan: never trust model-supplied ids/meshes here.
	diorama.objects = diorama.objects.map((o, i) => ({
		...o,
		id: `obj-${i}`,
		status: 'pending',
		glbUrl: null,
	}));

	return json(res, 200, { diorama });
}

async function handleSave(req, res, body) {
	if (!dioramaStoreEnabled()) {
		return json(res, 503, {
			error: 'sharing_unavailable',
			message: 'Sharing is not configured on this deployment.',
		});
	}
	// Persisting a world is an anonymous public write — bound per IP so one caller
	// can't carpet the gallery table.
	const saveRl = await limits.dioramaSaveIp(clientIp(req));
	if (!saveRl.success) {
		return rateLimited(res, saveRl, 'Saving too fast. Try again in a moment.');
	}
	// Anonymous-first (no login required to save/share a world) — but when the
	// caller carries a session cookie, attach their user_id so the world
	// surfaces on their public portfolio (/u/:username → "Worlds" tab), and
	// default the in-scene author credit to their real handle if the client
	// didn't already set one.
	const sessionUser = await getSessionUser(req).catch(() => null);
	const diorama = sessionUser?.username && !body.diorama?.author?.handle
		? { ...body.diorama, author: { ...(body.diorama?.author || {}), handle: sessionUser.username } }
		: body.diorama;

	let saved;
	try {
		saved = await saveDiorama({
			diorama,
			clientKey: typeof body.clientKey === 'string' ? body.clientKey.slice(0, 128) : null,
			userId: sessionUser?.id ?? null,
		});
	} catch (err) {
		if (err?.code === 'invalid_diorama') {
			return json(res, 400, { error: 'invalid_diorama', message: err.message });
		}
		throw err;
	}
	if (!saved) {
		return json(res, 500, { error: 'save_failed', message: 'Could not save this world. Try again.' });
	}
	return json(res, 200, {
		id: saved.id,
		createdAt: saved.createdAt,
		url: `${SITE}/diorama?id=${saved.id}`,
	});
}

// Merge an already-forged diorama into one exportable GLB — the "Export +
// editability" leg of compositional scene generation: a single file with
// every object as a named, selectable node, ready for Scene Studio or any
// other glTF-aware app. Degrades cleanly (designed 503) when object storage
// isn't configured, and never fails whole-hog on a partial forge: whatever
// objects are 'ready' get merged, the rest come back in `skipped`.
async function handleExport(req, res, body) {
	if (!dioramaExportStoreEnabled()) {
		return json(res, 503, {
			error: 'export_unavailable',
			message: 'Scene export is not configured on this deployment.',
		});
	}
	const exportRl = await limits.dioramaExportIp(clientIp(req));
	if (!exportRl.success) {
		return rateLimited(res, exportRl, 'Exporting too fast. Try again in a moment.');
	}

	const { ok, diorama, errors } = normalizeDiorama(body.diorama);
	if (!ok) {
		return json(res, 400, { error: 'invalid_diorama', message: errors.join(', ') });
	}

	let result;
	try {
		result = await exportDioramaGlb(diorama);
	} catch (err) {
		if (err?.code === 'nothing_to_export') {
			return json(res, 400, { error: 'nothing_to_export', message: err.message });
		}
		console.error('[diorama] export failed:', err?.message);
		return json(res, 502, {
			error: 'export_failed',
			message: 'Could not merge this world into a scene. Try again in a moment.',
		});
	}
	// dioramaExportStoreEnabled() already gated this, but exportDioramaGlb also
	// self-checks storage config — keep the belt-and-suspenders 503 in case the
	// two checks ever diverge (e.g. a future env alias one reads and the other doesn't).
	if (!result) {
		return json(res, 503, {
			error: 'export_unavailable',
			message: 'Scene export is not configured on this deployment.',
		});
	}

	return json(res, 200, {
		glbUrl: result.glbUrl,
		sceneStudioUrl: `${SITE}/scene?model=${encodeURIComponent(result.glbUrl)}&name=${encodeURIComponent(diorama.title || 'Diorama')}`,
		title: diorama.title,
		objectCount: diorama.objects.length,
		exportedCount: result.exportedCount,
		skipped: result.skipped,
	});
}

// Headless one-shot world build: compose → forge every object → export — the
// full pipeline in a single call, for callers with no browser to drive the
// progressive client flow (MCP tools, autonomous agents). Real LLM inference
// plus N real free-lane forges, so it carries compose's fail-closed rate-limit
// posture. A forge failure on some objects never fails the whole build — the
// diorama returned reflects exactly what forged, and `skipped` names the rest.
async function handleBuild(req, res, body) {
	const prompt = String(body.prompt ?? '').slice(0, MAX_PROMPT_LEN).trim();
	if (prompt.length < 3) {
		return json(res, 400, { error: 'prompt_required', message: 'Describe your world in a sentence.' });
	}

	const ip = clientIp(req);
	const rl = await limits.dioramaBuildIp(ip);
	if (!rl.success) {
		return rateLimited(res, rl, 'World builder limit reached. Try again shortly.');
	}
	const globalRl = await limits.dioramaBuildGlobal();
	if (!globalRl.success) {
		return rateLimited(res, globalRl, 'The world builder is at capacity. Try again shortly.');
	}

	let plan;
	try {
		plan = await composePlanFromPrompt(prompt);
	} catch (err) {
		const status = err?.code === 'composer_unavailable' ? 503 : err?.code === 'prompt_required' ? 400 : 502;
		return json(res, status, { error: err?.code || 'compose_failed', message: err.message });
	}

	const forged = await forgeDioramaObjects(plan, {
		clientKey: typeof body.clientKey === 'string' ? body.clientKey.slice(0, 128) : undefined,
	});
	const readyCount = forged.objects.filter((o) => o.status === 'ready').length;

	const response = {
		diorama: forged,
		objectCount: forged.objects.length,
		readyCount,
		viewerUrl: `${SITE}/diorama`,
	};

	if (readyCount > 0) {
		try {
			const exported = await exportDioramaGlb(forged);
			if (exported) {
				response.glbUrl = exported.glbUrl;
				response.sceneStudioUrl = `${SITE}/scene?model=${encodeURIComponent(exported.glbUrl)}&name=${encodeURIComponent(forged.title || 'Diorama')}`;
				response.exportedCount = exported.exportedCount;
				response.skipped = exported.skipped;
			} else {
				response.exportNote = 'Scene export is not configured on this deployment; the diorama objects still forged individually.';
			}
		} catch (err) {
			console.error('[diorama] build export step failed:', err?.message);
			response.exportNote = 'The world forged but could not be merged into a single scene file. Try action:"export" again.';
		}
	}

	return json(res, 200, response);
}

// Extract the first balanced top-level JSON object from a model response that
// may be wrapped in prose or a ```json fence. Returns the parsed object or null.
function parseJsonObject(text) {
	if (typeof text !== 'string') return null;
	const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
	const candidate = fence ? fence[1] : text;
	const start = candidate.indexOf('{');
	if (start < 0) return null;
	let depth = 0;
	let inStr = false;
	let esc = false;
	for (let i = start; i < candidate.length; i++) {
		const c = candidate[i];
		if (inStr) {
			if (esc) esc = false;
			else if (c === '\\') esc = true;
			else if (c === '"') inStr = false;
			continue;
		}
		if (c === '"') inStr = true;
		else if (c === '{') depth++;
		else if (c === '}') {
			depth--;
			if (depth === 0) {
				try {
					return JSON.parse(candidate.slice(start, i + 1));
				} catch {
					return null;
				}
			}
		}
	}
	return null;
}

// Guard against the model stacking objects at the origin (a common failure):
// if any two objects are closer than MIN_SPACING, re-seat everything on a tidy
// spiral so the world always reads as a composed scene, never a pile.
const MIN_SPACING = 1.4;
function declump(objects) {
	if (objects.length < 2) return objects;
	let clumped = false;
	for (let i = 0; i < objects.length && !clumped; i++) {
		for (let j = i + 1; j < objects.length; j++) {
			const a = objects[i]?.position || [0, 0, 0];
			const b = objects[j]?.position || [0, 0, 0];
			if (Math.hypot((a[0] || 0) - (b[0] || 0), (a[2] || 0) - (b[2] || 0)) < MIN_SPACING) {
				clumped = true;
				break;
			}
		}
	}
	if (!clumped) return objects;
	const n = objects.length;
	const golden = Math.PI * (3 - Math.sqrt(5));
	return objects.map((o, i) => {
		// Phyllotaxis: even, non-overlapping spread filling the island disc.
		const t = (i + 0.5) / n;
		const r = (ISLAND_RADIUS - 1.2) * Math.sqrt(t);
		const a = i * golden;
		return { ...o, position: [Math.cos(a) * r, 0, Math.sin(a) * r] };
	});
}