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
// Live Docs — the pure half.
//
// Every runnable code sample on three.ws docs is decided here: what kind of
// runner a fenced block deserves, how a `curl` line becomes a real request,
// which requests a reader is allowed to fire from a documentation page, and how
// a snippet is wrapped into a sandboxed preview document.
//
// Nothing in this file touches the DOM, the network, or `window`. That is
// deliberate: the interesting logic (shell tokenizing, placeholder detection,
// the money-path guard) is exactly the logic that must be unit-tested in Node,
// and the runner in docs-live.js is then a thin, boring shell around it.
// tests/docs-live-core.test.js imports this module directly.
//
// Design rule that shapes the whole file: a documentation page is READ by
// people who are evaluating the platform, often signed in. A "Run" button on
// such a page is a loaded gun unless it is narrow by construction. So:
// - only three.ws origins are reachable (no arbitrary host from a snippet),
// - GET/HEAD run on one click,
// - other verbs demand an explicit second confirmation,
// - anything whose path can move money or mint is never runnable at all.
// The guard lives here, in the tested layer, not in a click handler.
/** Fence languages that can carry an inline HTML/web-component preview. */
export const PREVIEW_LANGS = Object.freeze(['html', 'xml', 'svg']);
/** Fence languages that can carry a shell request. */
export const SHELL_LANGS = Object.freeze(['bash', 'sh', 'shell', 'zsh', 'console', 'curl']);
/** Fence languages that can carry a runnable browser script. */
export const SCRIPT_LANGS = Object.freeze(['js', 'javascript', 'mjs']);
/** Origins a docs sample is allowed to call. Anything else is not runnable. */
export const ALLOWED_HOSTS = Object.freeze(['three.ws', 'www.three.ws', 'localhost', '127.0.0.1']);
// Paths that move value or create something irreversible. A reader clicking
// "Run" in a doc must never be able to reach these, confirmation or not: the
// blast radius of a mis-click is someone else's money. Matched against the
// pathname, case-insensitively, as a substring.
const IRREVERSIBLE_PATH_PARTS = Object.freeze([
'/pay',
'/send',
'/transfer',
'/withdraw',
'/fund',
'/swap',
'/trade',
'/buy',
'/sell',
'/wallet',
'/mint',
'/launch',
'/autopilot',
'/x402',
'/checkout',
'/billing',
'/subscribe',
'/sniper',
'/vault',
]);
const SAFE_METHODS = Object.freeze(['GET', 'HEAD']);
const KNOWN_METHODS = Object.freeze(['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS']);
// ── Fence classification ─────────────────────────────────────────────────────
/**
* Decide what a fenced code block can do.
*
* @param {{ lang?: string, code?: string }} block
* @returns {null | { kind: 'preview'|'request'|'script', reason?: string, request?: object }}
* null when the block is ordinary prose-adjacent code with nothing to run.
*/
export function classifyBlock(block = {}) {
const lang = String(block.lang || '').toLowerCase().trim();
const code = String(block.code || '');
if (!code.trim()) return null;
if (PREVIEW_LANGS.includes(lang) && hasRenderableMarkup(code)) {
return { kind: 'preview' };
}
if (SHELL_LANGS.includes(lang)) {
const request = parseCurl(code);
if (request) return { kind: 'request', request };
return null;
}
if (SCRIPT_LANGS.includes(lang) && isRunnableScript(code)) {
return { kind: 'script' };
}
return null;
}
// A preview is only worth offering when the snippet actually renders something.
// A block of `<meta>` tags or a bare `<div>` produces an empty box, which reads
// as a broken feature; the three.ws embed elements and plain visible markup do
// not. `<script>`-only snippets are excluded for the same reason.
function hasRenderableMarkup(code) {
if (/<(agent-3d|model-viewer|three-ws-[a-z-]+)\b/i.test(code)) return true;
if (/^\s*<(!doctype|html)\b/i.test(code)) return true;
// Visible structural markup with text or an element inside it.
return /<(div|section|main|button|p|h[1-6]|ul|ol|table|img|canvas|iframe|form|a)\b[^>]*>/i.test(code);
}
// Scripts are only offered a runner when they visibly do something observable:
// a network call or console output. Running a snippet whose whole body is a
// type definition produces an empty result panel and teaches the reader that
// the feature is broken.
function isRunnableScript(code) {
if (/\bimport\s+[^;]*from\s+['"][^./'"]/.test(code)) return false; // bare specifier, needs a bundler
if (/\brequire\s*\(/.test(code)) return false; // Node sample
if (/\bprocess\.env\b/.test(code)) return false; // Node sample
return /\bfetch\s*\(|\bconsole\.(log|info|warn|error|table)\s*\(/.test(code);
}
// ── Shell parsing ────────────────────────────────────────────────────────────
/**
* Split a shell command into argv, honouring single/double quotes, backslash
* line continuations, and `$'...'`-free simple escaping. Comment lines and a
* leading `$ ` prompt are dropped so a copy-pasted console transcript parses.
*
* @param {string} input
* @returns {string[]}
*/
export function tokenizeShell(input) {
const text = String(input || '')
.split('\n')
.map((line) => line.replace(/^\s*\$\s+/, ''))
.filter((line) => !/^\s*#/.test(line))
.join('\n')
.replace(/\\\r?\n/g, ' ');
const out = [];
let cur = '';
let quote = null;
let started = false;
for (let i = 0; i < text.length; i += 1) {
const ch = text[i];
if (quote) {
if (ch === '\\' && quote === '"' && i + 1 < text.length) {
i += 1;
cur += text[i];
continue;
}
if (ch === quote) {
quote = null;
continue;
}
cur += ch;
continue;
}
if (ch === '"' || ch === "'") {
quote = ch;
started = true;
continue;
}
if (ch === '\\' && i + 1 < text.length) {
i += 1;
cur += text[i];
started = true;
continue;
}
if (/\s/.test(ch)) {
if (started) out.push(cur);
cur = '';
started = false;
continue;
}
cur += ch;
started = true;
}
if (started) out.push(cur);
return out;
}
/**
* Turn a `curl` invocation into a request description.
*
* Returns null for anything that is not a single, self-contained curl call:
* pipelines, multiple commands, `curl | sh`, and non-curl shell lines all fall
* through to "not runnable" rather than being guessed at.
*
* @param {string} command
* @returns {null | { method: string, url: string, headers: Record<string,string>, body: string|null }}
*/
export function parseCurl(command) {
const raw = String(command || '');
// One command only. A pipeline or a chained command means the sample is a
// recipe, not a request, and running just the curl half would mislead.
if (/[|;]|&&/.test(raw.replace(/\\\r?\n/g, ' '))) return null;
const argv = tokenizeShell(raw);
if (!argv.length || argv[0] !== 'curl') return null;
const headers = {};
let method = null;
let url = null;
let body = null;
for (let i = 1; i < argv.length; i += 1) {
const arg = argv[i];
const next = () => argv[++i];
if (arg === '-X' || arg === '--request') {
method = String(next() || '').toUpperCase();
} else if (arg === '-H' || arg === '--header') {
const h = String(next() || '');
const idx = h.indexOf(':');
if (idx > 0) headers[h.slice(0, idx).trim()] = h.slice(idx + 1).trim();
} else if (arg === '-d' || arg === '--data' || arg === '--data-raw' || arg === '--data-binary') {
const chunk = String(next() || '');
body = body == null ? chunk : `${body}&${chunk}`;
} else if (arg === '--url') {
url = String(next() || '');
} else if (arg === '-o' || arg === '--output' || arg === '-A' || arg === '--user-agent' || arg === '-u' || arg === '--user') {
next(); // consumes its value; irrelevant to an in-page fetch
} else if (arg.startsWith('-')) {
// Bare flags (-s, -L, -i, --compressed, …) carry no value.
continue;
} else if (!url) {
url = arg;
}
}
if (!url) return null;
if (!method) method = body != null ? 'POST' : 'GET';
if (!KNOWN_METHODS.includes(method)) return null;
return { method, url, headers, body };
}
// ── Safety ───────────────────────────────────────────────────────────────────
/**
* Resolve a sample URL against three.ws and say whether it may be run.
*
* @param {{ method?: string, url?: string }} request
* @param {{ origin?: string }} [opts] the origin a relative URL resolves against
* @returns {{ ok: boolean, confirm: boolean, url: string|null, reason: string|null }}
*/
export function assessRequest(request = {}, opts = {}) {
const origin = normalizeOrigin(opts.origin) || 'https://three.ws';
const method = String(request.method || 'GET').toUpperCase();
const deny = (reason) => ({ ok: false, confirm: false, url: null, reason });
let parsed;
try {
parsed = new URL(String(request.url || ''), origin);
} catch {
return deny('That URL could not be parsed.');
}
if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
return deny('Only http(s) requests can run from the docs.');
}
if (!ALLOWED_HOSTS.includes(parsed.hostname)) {
return deny(`Only three.ws endpoints run here. This sample calls ${parsed.hostname}.`);
}
const path = parsed.pathname.toLowerCase();
if (IRREVERSIBLE_PATH_PARTS.some((part) => path.includes(part))) {
return deny('This endpoint can move funds or mint. Copy it and run it yourself.');
}
if (!KNOWN_METHODS.includes(method)) {
return deny(`${method} is not a method the docs runner sends.`);
}
return {
ok: true,
confirm: !SAFE_METHODS.includes(method),
url: parsed.toString(),
reason: null,
};
}
function normalizeOrigin(origin) {
if (!origin) return null;
try {
return new URL(String(origin)).origin;
} catch {
return null;
}
}
// ── Placeholders ─────────────────────────────────────────────────────────────
// Two characters is the floor, not three: `<id>` and `$ID` are both real slot
// names in the API reference, and a three-character minimum silently skipped
// them, leaving the reader with a request that called /api/agents/<id>.
const PLACEHOLDER_PATTERNS = Object.freeze([
/\$\{([A-Z][A-Z0-9_]+)\}/g,
/\$([A-Z][A-Z0-9_]+)\b/g,
/<([A-Za-z][A-Za-z0-9_-]+)>/g,
/\b(YOUR_[A-Z0-9_]+)\b/g,
]);
/**
* Every `$API_KEY` / `<agent-id>` / `YOUR_TOKEN` slot in a request, in the order
* a reader would fill them in. The runner renders one field per name, so a doc
* sample stops being a thing you copy, edit elsewhere and paste back.
*
* @param {{ url?: string, headers?: object, body?: string|null }} request
* @returns {Array<{ name: string, secret: boolean }>}
*/
export function findPlaceholders(request = {}) {
const haystack = [
String(request.url || ''),
...Object.entries(request.headers || {}).map(([k, v]) => `${k}: ${v}`),
String(request.body || ''),
].join('\n');
const names = [];
const seen = new Set();
for (const pattern of PLACEHOLDER_PATTERNS) {
pattern.lastIndex = 0;
let match = pattern.exec(haystack);
while (match) {
const name = match[1];
if (!seen.has(name) && !isHtmlishTag(name)) {
seen.add(name);
names.push({ name, secret: isSecretName(name) });
}
match = pattern.exec(haystack);
}
}
return names;
}
// `<html>`-shaped captures come from prose in a header value, not from a slot
// the reader is meant to fill.
const HTMLISH = new Set(['html', 'body', 'head', 'div', 'span', 'br', 'p', 'a', 'pre', 'code', 'em', 'strong']);
function isHtmlishTag(name) {
return HTMLISH.has(String(name).toLowerCase());
}
/** Names whose value must never be written to storage. */
export function isSecretName(name) {
return /(KEY|TOKEN|SECRET|PASSWORD|PASS|AUTH|CREDENTIAL|PRIVATE)/i.test(String(name));
}
/**
* Substitute placeholder values into a parsed request. Unfilled slots are left
* exactly as they are so the reader sees which field they skipped rather than a
* request that silently calls `/api/agents/undefined`.
*
* @param {object} request
* @param {Record<string,string>} values
* @returns {object} a new request; the input is not mutated
*/
export function applyPlaceholders(request = {}, values = {}) {
const fill = (text) => {
let out = String(text == null ? '' : text);
for (const [name, value] of Object.entries(values)) {
if (value === '' || value == null) continue;
const v = String(value);
// `${NAME}` first: replacing `$NAME` first would leave a stray `}`.
out = out.split(`\${${name}}`).join(v).split(`$${name}`).join(v).split(`<${name}>`).join(v);
// A bare, unsigilled name is only substituted for the YOUR_* convention.
// Replacing any bare name would rewrite unrelated prose that happens to
// contain the same word (a header called `API_KEY`, say).
if (/^YOUR_/.test(name)) out = out.split(name).join(v);
}
return out;
};
const headers = {};
for (const [k, v] of Object.entries(request.headers || {})) headers[fill(k)] = fill(v);
return {
method: request.method,
url: fill(request.url),
headers,
body: request.body == null ? null : fill(request.body),
};
}
// ── Preview documents ────────────────────────────────────────────────────────
/**
* The `<base>` a sandboxed frame needs so relative URLs in a snippet resolve.
*
* A frame built from `srcdoc` with no `allow-same-origin` has an opaque origin
* and a document URL of `about:srcdoc`, so `body="/avatars/michelle.glb"`
* resolves to nothing at all. A base pointing at the reader's own origin makes
* relative URLs mean what they mean on the page they were read on.
*
* Absolute `https://three.ws/…` URLs are deliberately left alone. Rewriting
* them to the current origin (an earlier version of this did) breaks the frame
* on any origin that does not itself serve `/agent-3d/…`, and it is also the
* wrong preview: a sample hardcodes the production URL precisely because that is
* what the reader will paste into their own site.
*
* @param {string} [origin]
* @returns {string} a `<base>` tag, or '' when no usable origin was supplied
*/
export function baseTag(origin) {
const target = normalizeOrigin(origin);
return target ? `<base href="${target}/">` : '';
}
/**
* Wrap a snippet into a complete document for a sandboxed iframe.
*
* The frame runs with `allow-scripts` and WITHOUT `allow-same-origin`, so it is
* a unique opaque origin: it can load the three.ws web component over the
* network but cannot read cookies, storage, or the parent document. That is why
* the preview is safe to offer on a page a signed-in reader is looking at.
*
* @param {string} snippet
* @param {{ origin?: string, theme?: 'dark'|'light' }} [opts]
* @returns {string} a full HTML document
*/
export function buildPreviewDoc(snippet, opts = {}) {
const theme = opts.theme === 'light' ? 'light' : 'dark';
const body = String(snippet == null ? '' : snippet);
const bg = theme === 'light' ? '#f6f7f9' : '#0e0f13';
const fg = theme === 'light' ? '#16181d' : '#e8eaf0';
// A snippet that already declares a full document is used verbatim: wrapping
// it again would nest <html> inside <body>.
if (/^\s*<(!doctype|html)\b/i.test(body)) return body;
return `<!doctype html>
<html lang="en" data-theme="${theme}">
<head>
<meta charset="utf-8">
${baseTag(opts.origin)}
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
:root { color-scheme: ${theme}; }
html, body { margin: 0; height: 100%; }
body {
background: ${bg};
color: ${fg};
font: 15px/1.5 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
display: flex;
align-items: center;
justify-content: center;
padding: 16px;
box-sizing: border-box;
}
agent-3d, model-viewer { max-width: 100%; }
img, canvas, iframe { max-width: 100%; }
</style>
</head>
<body>
${body}
</body>
</html>`;
}
/**
* Wrap a JS snippet into a document that reports its console output and any
* throw back to the parent via postMessage. Same opaque-origin sandbox as the
* preview, so a sample's `fetch` runs without the reader's three.ws cookies.
*
* @param {string} snippet
* @param {{ origin?: string }} [opts]
* @returns {string}
*/
export function buildScriptDoc(snippet, opts = {}) {
const code = String(snippet == null ? '' : snippet);
// The snippet is injected as a module body. `</script>` inside a string
// literal would otherwise close the tag early and break the document.
const safe = code.replace(/<\/script/gi, '<\\/script');
return `<!doctype html>
<html lang="en"><head><meta charset="utf-8">${baseTag(opts.origin)}</head><body>
<script type="module">
const send = (level, args) => {
const parts = args.map((a) => {
if (typeof a === 'string') return a;
try { return JSON.stringify(a, null, 2); } catch { return String(a); }
});
parent.postMessage({ __docsLive: true, level, text: parts.join(' ') }, '*');
};
for (const level of ['log', 'info', 'warn', 'error']) {
const original = console[level].bind(console);
console[level] = (...args) => { send(level, args); original(...args); };
}
window.addEventListener('unhandledrejection', (e) => send('error', [String(e.reason)]));
window.addEventListener('error', (e) => send('error', [String(e.message)]));
try {
${safe}
parent.postMessage({ __docsLive: true, level: 'done' }, '*');
} catch (err) {
send('error', [String(err && err.stack ? err.stack : err)]);
parent.postMessage({ __docsLive: true, level: 'done' }, '*');
}
<\/script>
</body></html>`;
}
// ── Result formatting ────────────────────────────────────────────────────────
/** "1.2 kB" / "840 B" / "3.4 MB" — never a bare byte count in the UI. */
export function formatBytes(n) {
// `Number(null)` is 0, so a missing value would otherwise render as "0 B" —
// an unknown size dressed up as a measured one.
if (n == null || n === '') return '—';
const v = Number(n);
if (!Number.isFinite(v) || v < 0) return '—';
if (v < 1000) return `${Math.round(v)} B`;
if (v < 1_000_000) return `${(v / 1000).toFixed(1)} kB`;
return `${(v / 1_000_000).toFixed(2)} MB`;
}
/** "142 ms" under a second, "1.42 s" above it. */
export function formatDuration(ms) {
if (ms == null || ms === '') return '—'; // see formatBytes: 0 is a measurement, null is not
const v = Number(ms);
if (!Number.isFinite(v) || v < 0) return '—';
return v < 1000 ? `${Math.round(v)} ms` : `${(v / 1000).toFixed(2)} s`;
}
/** Colour band for an HTTP status chip. */
export function statusTone(status) {
const s = Number(status);
if (!Number.isFinite(s)) return 'err';
if (s >= 200 && s < 300) return 'ok';
if (s >= 300 && s < 400) return 'redirect';
if (s === 402) return 'paid';
if (s >= 400 && s < 500) return 'warn';
return 'err';
}
/**
* Pretty-print a response body, truncating anything a docs panel should not try
* to render. JSON is re-indented; everything else is passed through.
*
* @param {string} text
* @param {{ contentType?: string, limit?: number }} [opts]
* @returns {{ text: string, language: string, truncated: boolean }}
*/
export function formatResponseBody(text, opts = {}) {
const limit = Number.isFinite(opts.limit) ? opts.limit : 20_000;
const raw = String(text == null ? '' : text);
const type = String(opts.contentType || '').toLowerCase();
let out = raw;
let language = 'text';
if (type.includes('json') || looksLikeJson(raw)) {
try {
out = JSON.stringify(JSON.parse(raw), null, 2);
language = 'json';
} catch {
language = 'text';
}
} else if (type.includes('html')) {
language = 'html';
}
if (out.length > limit) {
return { text: `${out.slice(0, limit)}\n…truncated at ${formatBytes(limit)}`, language, truncated: true };
}
return { text: out, language, truncated: false };
}
function looksLikeJson(text) {
const t = String(text || '').trim();
return (t.startsWith('{') && t.endsWith('}')) || (t.startsWith('[') && t.endsWith(']'));
}
/** A one-line label for the Run button, so the verb always matches the action. */
export function runLabel(kind, request) {
if (kind === 'preview') return 'Run preview';
if (kind === 'script') return 'Run script';
const method = String(request?.method || 'GET').toUpperCase();
return SAFE_METHODS.includes(method) ? 'Send request' : `Send ${method}`;
}