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 steps - runnable API calls embedded directly in three.ws documentation.
* ============================================================================
*
* WHAT IT IS
* A tutorial author writes a fenced ```live block naming a step id. The viewer
* replaces that block with an interactive card that performs the REAL request
* against the live three.ws API, in the reader's browser, and renders the real
* response. No mocked payloads, no recorded fixtures: the reader sees what the
* platform is actually returning right now, and can copy it.
*
* THE SECURITY MODEL (the reason this design, and not "let markdown name a URL")
* Markdown is content. Content must never be able to choose what request the
* page makes. So:
*
* 1. Markdown SELECTS, code DECIDES. A ```live block may only reference a
* step id from the STEPS registry below. An unknown id renders a visible
* "unknown step" card and issues no request at all.
* 2. GET only. validateRegistry() throws at load if any entry declares
* another method, so no live step can ever mutate platform state.
* 3. Paths are literal constants. Reader input and chained values only ever
* land in query-string values, URL-encoded. Nothing interpolates into the
* path or the origin, so no live step can be pointed at another host.
* 4. Responses render through the DOM (textContent + built spans), never
* innerHTML, so a hostile payload cannot inject markup.
* 5. Session-shaped fields (sid, csrf, tokens) are redacted from the DISPLAY
* before painting. Chained exports read the raw body, so a redacted field
* still works as an input to the next step without ever being on screen.
*
* WIRING
* Loaded as a classic script (like /tutorials-manifest.js) and used as:
*
* LiveSteps.mount(articleElement);
*
* called after the markdown has been parsed into the article. Styles live in
* /live-steps.css. Authoring guide: /docs/live-steps.md.
*/
(function () {
'use strict';
/* ══════════════════════════════════════════════════════════════════════
* Derivations - pure client-side transforms, referenced by name from the
* registry. A derive step performs no network call; it turns values that
* earlier steps exported into the exact artifact the reader needs to see.
* ══════════════════════════════════════════════════════════════════════ */
const SIWS_STATEMENT =
'Sign in to three.ws. This request will not trigger any blockchain transaction or cost ' +
'any fees. By signing, you agree to the Terms of Service (https://three.ws/legal/tos) and ' +
'Privacy Policy (https://three.ws/legal/privacy).';
const DERIVATIONS = {
/*
* Assemble the CAIP-122 message a Solana wallet signs. This is the step
* integrations get wrong most often: the blank lines are structural, the
* chain id is a network name rather than an EIP-155 number, and domain
* and uri must come from the nonce response rather than from location.
*/
siwsMessage(vars) {
const address = vars.address || '<your-solana-address>';
const issuedAt = new Date();
const expiration = new Date(issuedAt.getTime() + 5 * 60 * 1000);
return [
`${vars.domain} wants you to sign in with your Solana account:`,
address,
'',
SIWS_STATEMENT,
'',
`URI: ${vars.uri}`,
'Version: 1',
'Chain ID: mainnet',
`Nonce: ${vars.nonce}`,
`Issued At: ${issuedAt.toISOString()}`,
`Expiration Time: ${expiration.toISOString()}`,
].join('\n');
},
};
/* ══════════════════════════════════════════════════════════════════════
* The registry - the complete set of calls documentation is allowed to
* make. Adding a row here is a code change, reviewed like any other.
*
* id referenced from markdown
* kind 'request' (network) or 'derive' (pure, local)
* title card heading
* summary one line explaining what the reader is about to observe
* docs deep link to the reference entry for this endpoint
* inputs reader-editable query parameters
* uses variable names this step consumes from earlier steps
* exports variable name -> key in the response body
* ══════════════════════════════════════════════════════════════════════ */
const STEPS = [
{
id: 'version',
kind: 'request',
method: 'GET',
path: '/api/version',
title: 'Ask the platform what it is running',
summary:
'Returns the exact commit and Cloud Run revision serving this page. Useful as a first call when a fix you expect is not showing up.',
docs: '/docs/#api-reference',
credentials: 'omit',
inputs: [],
exports: { commit: 'commitShort' },
},
{
id: 'platform-stats',
kind: 'request',
method: 'GET',
path: '/api/platform/stats',
title: 'Read the live platform counters',
summary:
'Agents, avatars, widgets and chains, counted at request time. These are the numbers behind the homepage.',
docs: '/docs/#api-reference',
credentials: 'omit',
inputs: [],
exports: {},
},
{
id: 'agents-public',
kind: 'request',
method: 'GET',
path: '/api/agents/public',
title: 'List public agents',
summary:
'The public agent directory, cursor-paginated. No key and no session: this is the same data the discover page renders.',
docs: '/docs/#api-reference',
credentials: 'omit',
inputs: [
{
name: 'limit',
label: 'limit',
value: '3',
placeholder: '3',
hint: 'How many agents to return (1-50).',
},
],
exports: {},
renders: {
pick: 'agents[0].avatar_thumbnail',
kind: 'image',
alt: 'The portrait of the first agent in the live public directory',
},
},
{
id: 'pump-launches',
kind: 'request',
method: 'GET',
path: '/api/pump/launches',
title: 'List coins launched through three.ws',
summary:
'Every mint launched from the platform, newest first, each joined to the agent that launched it. Public: this is what the launches feed renders from.',
docs: '/launches',
credentials: 'omit',
inputs: [
{
name: 'limit',
label: 'limit',
value: '3',
placeholder: '3',
hint: 'How many launches to return.',
},
],
exports: {},
renders: {
pick: 'data.launches[0].agent.avatar_thumbnail_url',
kind: 'image',
alt: 'The portrait of the agent behind the most recent launch',
},
},
{
id: 'pump-trending',
kind: 'request',
method: 'GET',
path: '/api/pump/trending',
title: 'Read the trending coin feed',
summary:
'Trending mints from the live Pump.fun feed, the same source the market surfaces score against. Values move between one run and the next, which is the point.',
docs: '/pumpfun',
credentials: 'omit',
inputs: [
{
name: 'limit',
label: 'limit',
value: '3',
placeholder: '3',
hint: 'How many coins to return.',
},
],
exports: {},
},
{
id: 'skills-catalog',
kind: 'request',
method: 'GET',
path: '/api/skills',
title: 'Browse the skill catalog',
summary:
'Every published skill with its category, install count, rating and per-call price. This is what an agent shops from.',
docs: '/docs/#api-reference',
credentials: 'omit',
inputs: [
{
name: 'limit',
label: 'limit',
value: '3',
placeholder: '3',
hint: 'How many skills to return.',
},
],
exports: {},
},
{
id: 'three-leaderboard',
kind: 'request',
method: 'GET',
path: '/api/leaderboard',
title: 'Read the $THREE holder leaderboard',
summary:
'Live holder ranks, tiers and supply share for $THREE, read straight from chain state. Holder tier is what gates the premium surfaces.',
docs: '/docs/#api-reference',
credentials: 'omit',
inputs: [
{
name: 'limit',
label: 'limit',
value: '3',
placeholder: '3',
hint: 'How many ranked holders to return.',
},
],
exports: {},
},
{
id: 'auth-me',
kind: 'request',
method: 'GET',
path: '/api/auth/me',
title: 'Ask who you are signed in as',
summary:
'Sent with your cookies. If you are signed in on this browser you will see your own account; if not, you will see the signed-out shape that trips most integrations.',
docs: '/docs/#authentication',
credentials: 'include',
inputs: [],
exports: {},
},
{
id: 'siws-nonce',
kind: 'request',
method: 'GET',
path: '/api/auth/siws/nonce',
title: 'Mint a Solana sign-in nonce',
summary:
'A single-use nonce with a five minute life, plus the canonical domain and uri your signed message must carry. Reading it here costs nothing and signs you into nothing.',
docs: '/docs/#authentication',
credentials: 'include',
inputs: [],
exports: {
nonce: 'nonce',
domain: 'domain',
uri: 'uri',
expiresAt: 'expiresAt',
},
},
{
id: 'siws-message',
kind: 'derive',
derive: 'siwsMessage',
title: 'Build the exact bytes to sign',
summary:
'Composed locally from the nonce response. This is the string your wallet signs, byte for byte, and the one place integrations most often go wrong.',
docs: '/tutorials/wallet-sign-in',
uses: ['nonce', 'domain', 'uri'],
inputs: [
{
name: 'address',
label: 'address',
value: '',
placeholder: 'Your Solana address (optional)',
hint: 'Left blank, the message shows a placeholder in the address line.',
},
],
},
];
/* ══════════════════════════════════════════════════════════════════════
* Registry validation. These are the invariants the security model rests
* on, so they are checked at load and throw rather than degrade.
* ══════════════════════════════════════════════════════════════════════ */
const SAFE_PATH = /^\/api\/[A-Za-z0-9][A-Za-z0-9/_-]*$/;
const SAFE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
function validateRegistry(steps) {
const seen = new Set();
const produced = new Set();
for (const step of steps) {
if (!step.id || seen.has(step.id)) {
throw new Error(`live-steps: duplicate or missing step id "${step.id}"`);
}
seen.add(step.id);
if (step.kind !== 'request' && step.kind !== 'derive') {
throw new Error(`live-steps: ${step.id} has unknown kind "${step.kind}"`);
}
for (const input of step.inputs || []) {
if (!SAFE_NAME.test(input.name)) {
throw new Error(`live-steps: ${step.id} has unsafe input name "${input.name}"`);
}
}
for (const name of step.uses || []) {
if (!produced.has(name)) {
throw new Error(
`live-steps: ${step.id} uses "${name}", which no earlier step exports`,
);
}
}
if (step.kind === 'request') {
if (step.method !== 'GET') {
throw new Error(
`live-steps: ${step.id} declares ${step.method}; live steps are read-only`,
);
}
if (!SAFE_PATH.test(step.path) || step.path.includes('..')) {
throw new Error(`live-steps: ${step.id} has an unsafe path "${step.path}"`);
}
for (const name of Object.keys(step.exports || {})) {
if (!SAFE_NAME.test(name)) {
throw new Error(`live-steps: ${step.id} exports unsafe name "${name}"`);
}
produced.add(name);
}
if (step.renders) {
if (!parsePickPath(step.renders.pick)) {
throw new Error(
`live-steps: ${step.id} renders an unreadable path "${step.renders.pick}"`,
);
}
const kind = step.renders.kind || 'auto';
if (kind !== 'auto' && kind !== 'model' && kind !== 'image') {
throw new Error(`live-steps: ${step.id} renders unknown kind "${kind}"`);
}
if (!step.renders.alt) {
throw new Error(`live-steps: ${step.id} renders without alt text`);
}
}
} else {
if (typeof DERIVATIONS[step.derive] !== 'function') {
throw new Error(`live-steps: ${step.id} names unknown derivation "${step.derive}"`);
}
if (!(step.uses || []).length) {
throw new Error(`live-steps: ${step.id} is a derive step with no inputs to derive from`);
}
}
}
return true;
}
validateRegistry(STEPS);
const BY_ID = new Map(STEPS.map((s) => [s.id, s]));
/* variable name -> id of the step that produces it, for prerequisite chasing. */
const PRODUCER = new Map();
for (const step of STEPS) {
for (const name of Object.keys(step.exports || {})) {
if (!PRODUCER.has(name)) PRODUCER.set(name, step.id);
}
}
/* ══════════════════════════════════════════════════════════════════════
* Redaction. Session-shaped fields are stripped from the rendered copy so
* that a reader screenshotting the docs, or a page recorded by a session
* replay tool, never carries a usable credential. Exports read the raw
* body, so redaction costs the reader nothing.
* ══════════════════════════════════════════════════════════════════════ */
const SECRET_KEY =
/^(sid|csrf|csrf_token|token|access_token|refresh_token|id_token|secret|authorization|cookie|session|password|private_key|privatekey|api_key|apikey)$/i;
const REDACTED = '[redacted in this view]';
function redact(value) {
let count = 0;
const walk = (node) => {
if (Array.isArray(node)) return node.map(walk);
if (node && typeof node === 'object') {
const out = {};
for (const [key, val] of Object.entries(node)) {
if (SECRET_KEY.test(key) && val !== null && val !== '') {
out[key] = REDACTED;
count += 1;
} else {
out[key] = walk(val);
}
}
return out;
}
return node;
};
return { value: walk(value), count };
}
/* ══════════════════════════════════════════════════════════════════════
* URL building. Query values are the only place reader input reaches the
* request, and they go through URLSearchParams, so they are encoded.
* ══════════════════════════════════════════════════════════════════════ */
function buildUrl(step, values) {
/*
* encodeURIComponent rather than URLSearchParams, for two reasons. It
* percent-encodes the delimiters that matter here (/, ?, #, &) where
* URLSearchParams leaves some of them raw and turns spaces into '+', and
* it is a language built-in, so this stays pure and testable outside a
* browser. Only declared inputs are read, so an undeclared key a caller
* passes in can never reach the URL.
*/
const pairs = [];
for (const input of step.inputs || []) {
const raw = values[input.name];
if (raw === undefined || raw === null || String(raw).trim() === '') continue;
pairs.push(`${encodeURIComponent(input.name)}=${encodeURIComponent(String(raw).trim())}`);
}
return pairs.length ? `${step.path}?${pairs.join('&')}` : step.path;
}
/* ══════════════════════════════════════════════════════════════════════
* Rendering helpers.
* ══════════════════════════════════════════════════════════════════════ */
const SVG = 'http://www.w3.org/2000/svg';
function icon(paths, extra) {
const svg = document.createElementNS(SVG, 'svg');
svg.setAttribute('viewBox', '0 0 24 24');
svg.setAttribute('fill', 'none');
svg.setAttribute('stroke', 'currentColor');
svg.setAttribute('stroke-width', extra || '2');
svg.setAttribute('stroke-linecap', 'round');
svg.setAttribute('stroke-linejoin', 'round');
svg.setAttribute('aria-hidden', 'true');
for (const d of paths) {
const p = document.createElementNS(SVG, 'path');
p.setAttribute('d', d);
svg.appendChild(p);
}
return svg;
}
const ICONS = {
play: () => icon(['M7 4.5v15l12-7.5z'], '1.6'),
check: () => icon(['M20 6 9 17l-5-5'], '2.4'),
copy: () => icon(['M9 9h9a2 2 0 0 1 2 2v9H9z', 'M5 15V5a2 2 0 0 1 2-2h10']),
alert: () => icon(['M12 8v5', 'M12 17h.01', 'M12 3 2 20h20z']),
link: () => icon(['M10 13a5 5 0 0 0 7.07 0l3-3a5 5 0 1 0-7.07-7.07l-1.72 1.71', 'M14 11a5 5 0 0 0-7.07 0l-3 3a5 5 0 1 0 7.07 7.07l1.71-1.71']),
chain: () => icon(['M4 12h6', 'M14 12h6', 'M11 8l3 8'], '1.8'),
};
function el(tag, className, text) {
const node = document.createElement(tag);
if (className) node.className = className;
if (text !== undefined) node.textContent = text;
return node;
}
/*
* Paint JSON without innerHTML: tokens become spans, everything else stays
* a text node, so no response body can inject markup into the page.
*/
const JSON_TOKEN =
/("(?:\\.|[^"\\])*"\s*:)|("(?:\\.|[^"\\])*")|(-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?)|(true|false|null)/g;
function paintJson(text) {
const frag = document.createDocumentFragment();
let last = 0;
let match;
JSON_TOKEN.lastIndex = 0;
while ((match = JSON_TOKEN.exec(text)) !== null) {
if (match.index > last) {
frag.appendChild(document.createTextNode(text.slice(last, match.index)));
}
const cls = match[1] ? 'ls-key' : match[2] ? 'ls-str' : match[3] ? 'ls-num' : 'ls-lit';
frag.appendChild(el('span', cls, match[0]));
last = match.index + match[0].length;
}
if (last < text.length) frag.appendChild(document.createTextNode(text.slice(last)));
return frag;
}
function copyButton(getText) {
const btn = el('button', 'ls-copy');
btn.type = 'button';
const label = el('span', null, 'Copy');
btn.append(ICONS.copy(), label);
btn.setAttribute('aria-label', 'Copy this response to the clipboard');
let timer = null;
btn.addEventListener('click', async () => {
try {
await navigator.clipboard.writeText(getText());
btn.replaceChildren(ICONS.check(), el('span', null, 'Copied'));
btn.classList.add('is-copied');
} catch {
btn.replaceChildren(ICONS.copy(), el('span', null, 'Press Ctrl+C'));
}
clearTimeout(timer);
timer = setTimeout(() => {
btn.classList.remove('is-copied');
btn.replaceChildren(ICONS.copy(), el('span', null, 'Copy'));
}, 1800);
});
return btn;
}
function formatBytes(n) {
if (n < 1024) return `${n} B`;
if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
return `${(n / 1024 / 1024).toFixed(1)} MB`;
}
/*
* Turn a failed request into something the reader can act on. A live step
* that says "something went wrong" teaches nothing, so every branch here
* names the cause and the next move.
*/
function explainFailure(status, body) {
if (status === 0) {
return 'The request never reached the API. You are probably offline, or an extension is blocking requests from this page.';
}
if (status === 401 || status === 403) {
return 'The API answered, and told us this call needs a signed-in session. That is the correct answer for a signed-out browser.';
}
if (status === 404) {
return 'The API answered, but no route matched. If you are reading a cached copy of this page, reload it.';
}
if (status === 429) {
return 'Rate limited. The live steps share your IP allowance with the rest of the site, so wait a few seconds and run it again.';
}
if (status >= 500) {
return 'The API failed on its side. This is a real production response, not a mock, so it is worth reporting if it persists.';
}
const described = body && (body.error_description || body.error);
return described
? `The API rejected the request: ${described}`
: 'The API answered with an unexpected status.';
}
/* ══════════════════════════════════════════════════════════════════════
* The render lane - the part only a 3D platform can do.
*
* Printing JSON proves the API answered. It does not show what the answer
* IS. When a response carries the URL of an avatar, a thumbnail or a GLB,
* a step can declare `renders` and the card mounts that asset live under
* the body: "call the endpoint" and "look at the thing it returned" become
* one card instead of a call, a copy, and a trip to another tab.
*
* The URL comes off the network, so it is treated as untrusted:
* - it is read from the RAW body by a path the registry declares, never
* by anything markdown supplies,
* - it must be https: or a same-origin absolute path, so a redirected or
* poisoned field can never produce a javascript: or data: subresource,
* - it is set through setAttribute on a fresh element, never innerHTML.
* ══════════════════════════════════════════════════════════════════════ */
const MODEL_EXT = /\.(glb|gltf)(\?|#|$)/i;
const IMAGE_EXT = /\.(png|jpe?g|webp|avif|gif)(\?|#|$)/i;
/* `agents[0].avatar_thumbnail` -> ['agents', 0, 'avatar_thumbnail']. */
function parsePickPath(expr) {
if (typeof expr !== 'string' || !expr) return null;
/* A trailing separator would otherwise consume cleanly and yield a path
* one segment shorter than the author wrote. */
if (expr.endsWith('.')) return null;
const out = [];
const re = /([A-Za-z_$][\w$]*)|\[(\d+)\]/g;
let consumed = 0;
/* A separator promises another segment; "a." must not parse as ['a']. */
let expectSegment = true;
let match;
while ((match = re.exec(expr)) !== null) {
if (match.index !== consumed) return null;
consumed = re.lastIndex;
out.push(match[1] !== undefined ? match[1] : Number(match[2]));
expectSegment = false;
if (expr.charAt(consumed) === '.') {
consumed += 1;
expectSegment = true;
}
re.lastIndex = consumed;
}
if (expectSegment || consumed !== expr.length || !out.length) return null;
return out;
}
function pickValue(body, path) {
let cursor = body;
for (const segment of path) {
if (cursor === null || cursor === undefined) return undefined;
if (typeof segment === 'number') {
if (!Array.isArray(cursor)) return undefined;
} else if (typeof cursor !== 'object' || Array.isArray(cursor)) {
return undefined;
}
cursor = cursor[segment];
}
return cursor;
}
function mediaKind(url) {
if (typeof url !== 'string') return null;
if (MODEL_EXT.test(url)) return 'model';
if (IMAGE_EXT.test(url)) return 'image';
return null;
}
/*
* Only https and same-origin absolute paths may become a subresource. A
* scheme-relative or bare-relative value is rejected rather than resolved:
* the origin it would pick up depends on the page, and a URL whose host
* depends on where the docs are hosted is not a URL worth rendering.
*/
function safeAssetUrl(url) {
if (typeof url !== 'string' || !url) return null;
if (url.startsWith('//')) return null;
if (url.startsWith('/')) return url;
return /^https:\/\/[^\s/?#]+/i.test(url) ? url : null;
}
function renderAsset(url, kind, alt) {
const wrap = el('div', 'ls-asset');
const head = el('div', 'ls-asset-head');
head.append(el('span', 'ls-asset-label', 'Rendered from this response'), el('code', 'ls-asset-src', url));
wrap.appendChild(head);
const frame = el('div', 'ls-asset-frame');
/*
* model-viewer is loaded by the pages that host live steps. If a host
* page has not registered it, mounting the element would paint an empty
* box, so the reader gets a real link to the file instead.
*/
if (kind === 'model' && !(window.customElements && customElements.get('model-viewer'))) {
const link = el('a', 'ls-asset-fallback', 'Open the model file');
link.href = url;
link.target = '_blank';
link.rel = 'noopener noreferrer';
frame.appendChild(link);
wrap.appendChild(frame);
return wrap;
}
if (kind === 'model') {
const viewer = document.createElement('model-viewer');
viewer.className = 'ls-asset-model';
viewer.setAttribute('src', url);
viewer.setAttribute('camera-controls', '');
viewer.setAttribute('touch-action', 'pan-y');
viewer.setAttribute('interaction-prompt', 'none');
viewer.setAttribute('shadow-intensity', '0');
viewer.setAttribute('exposure', '0.95');
viewer.setAttribute('environment-image', 'neutral');
viewer.setAttribute('field-of-view', '32deg');
viewer.setAttribute('tabindex', '0');
viewer.setAttribute('alt', alt || 'The model this response points at');
const reduce = window.matchMedia && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!reduce) {
viewer.setAttribute('auto-rotate', '');
viewer.setAttribute('auto-rotate-delay', '600');
viewer.setAttribute('rotation-per-second', '16deg');
}
frame.append(viewer, el('span', 'ls-asset-hint', 'Drag to orbit'));
} else {
const img = new Image();
img.className = 'ls-asset-img';
img.src = url;
img.alt = alt || 'The image this response points at';
img.loading = 'lazy';
img.decoding = 'async';
img.addEventListener('error', () => {
frame.replaceChildren(el('p', 'ls-asset-fail', 'That URL did not load as an image.'));
});
frame.appendChild(img);
}
wrap.appendChild(frame);
return wrap;
}
/* ══════════════════════════════════════════════════════════════════════
* The card.
* ══════════════════════════════════════════════════════════════════════ */
function createCard(step, block, ctx) {
const card = el('section', 'ls-card');
card.dataset.step = step.id;
card.dataset.state = 'idle';
card.setAttribute('role', 'group');
card.setAttribute('aria-label', `Live step: ${step.title}`);
/* Header: what this call is, and where the reference for it lives. */
const head = el('header', 'ls-head');
const badge = el('span', 'ls-badge');
badge.append(
el('span', 'ls-badge-dot'),
el('span', null, step.kind === 'derive' ? 'LOCAL' : 'LIVE'),
);
head.appendChild(badge);
const titles = el('div', 'ls-titles');
titles.appendChild(el('h4', 'ls-title', block.title || step.title));
const target = el('p', 'ls-target');
if (step.kind === 'request') {
target.append(el('span', 'ls-method', step.method), el('code', 'ls-path', step.path));
} else {
target.append(el('span', 'ls-method ls-method-local', 'DERIVE'), el('code', 'ls-path', 'runs in this page, no request'));
}
titles.appendChild(target);
head.appendChild(titles);
if (step.docs) {
const ref = el('a', 'ls-ref');
ref.href = step.docs;
ref.append(ICONS.link(), el('span', null, 'Reference'));
head.appendChild(ref);
}
card.appendChild(head);
card.appendChild(el('p', 'ls-summary', block.note || step.summary));
/* Chained variables: name what this step needs and where it comes from. */
if ((step.uses || []).length) {
const chain = el('p', 'ls-chain');
chain.appendChild(ICONS.chain());
chain.appendChild(
el(
'span',
null,
`Uses ${step.uses.join(', ')} from the ${BY_ID.get(PRODUCER.get(step.uses[0])).title.toLowerCase()} step above.`,
),
);
card.appendChild(chain);
}
/* Reader-editable query parameters. */
const values = {};
if ((step.inputs || []).length) {
const form = el('div', 'ls-inputs');
for (const input of step.inputs) {
values[input.name] = input.value;
const field = el('label', 'ls-field');
field.appendChild(el('span', 'ls-field-label', input.label));
const box = el('input', 'ls-input');
box.type = 'text';
box.value = input.value;
box.placeholder = input.placeholder || '';
box.spellcheck = false;
box.autocomplete = 'off';
if (input.hint) box.title = input.hint;
box.addEventListener('input', () => {
values[input.name] = box.value;
if (step.kind === 'request') urlPreview.textContent = buildUrl(step, values);
});
field.appendChild(box);
if (input.hint) field.appendChild(el('span', 'ls-field-hint', input.hint));
form.appendChild(field);
}
card.appendChild(form);
}
/* Action row: the button, the resolved URL, and the result meta. */
const actions = el('div', 'ls-actions');
const run = el('button', 'ls-run');
run.type = 'button';
run.append(ICONS.play(), el('span', 'ls-run-label', step.kind === 'derive' ? 'Build it' : 'Run it'));
actions.appendChild(run);
const urlPreview = el('code', 'ls-url');
urlPreview.textContent = step.kind === 'request' ? buildUrl(step, values) : '';
if (step.kind === 'request') actions.appendChild(urlPreview);
const meta = el('span', 'ls-meta');
actions.appendChild(meta);
card.appendChild(actions);
/* Result region. Announced politely so a screen reader hears the outcome. */
const result = el('div', 'ls-result');
result.setAttribute('aria-live', 'polite');
card.appendChild(result);
function setState(state) {
card.dataset.state = state;
}
function showBody(text, isJson) {
result.replaceChildren();
const shell = el('div', 'ls-body');
const pre = el('pre', 'ls-pre');
const code = el('code');
if (isJson) code.appendChild(paintJson(text));
else code.textContent = text;
pre.appendChild(code);
shell.append(pre, copyButton(() => text));
result.appendChild(shell);
return shell;
}
function showNote(className, text) {
const note = el('p', `ls-note ${className}`);
if (className === 'is-error') note.appendChild(ICONS.alert());
note.appendChild(el('span', null, text));
result.appendChild(note);
}
async function execute() {
if (card.dataset.state === 'running') return;
/* A derive step needs its inputs; offer to produce them rather than fail. */
if (step.kind === 'derive') {
const missing = (step.uses || []).filter((name) => !(name in ctx.vars));
if (missing.length) {
const producerId = PRODUCER.get(missing[0]);
setState('idle');
result.replaceChildren();
showNote(
'is-hint',
`This step needs ${missing.join(', ')}. Running the ${BY_ID.get(producerId).title.toLowerCase()} step first.`,
);
const ok = await ctx.runStep(producerId);
if (!ok) return;
}
const vars = Object.assign({}, ctx.vars, values);
const text = DERIVATIONS[step.derive](vars);
setState('ok');
meta.replaceChildren(el('span', 'ls-pill ls-pill-ok', 'built'), el('span', 'ls-dim', `${text.length} chars`));
showBody(text, false);
showNote('is-hint', 'Every line matters: the two blank lines are structural, and Chain ID is a network name rather than a number.');
return true;
}
setState('running');
run.disabled = true;
meta.replaceChildren(el('span', 'ls-spinner'), el('span', 'ls-dim', 'calling the live API'));
result.replaceChildren();
const url = buildUrl(step, values);
urlPreview.textContent = url;
const started = performance.now();
let status = 0;
let text = '';
let parsed = null;
try {
const res = await fetch(url, {
method: step.method,
credentials: step.credentials === 'include' ? 'include' : 'omit',
headers: { accept: 'application/json' },
});
status = res.status;
text = await res.text();
} catch {
status = 0;
}
const ms = Math.round(performance.now() - started);
run.disabled = false;
try {
parsed = JSON.parse(text);
} catch {
parsed = null;
}
const ok = status >= 200 && status < 300;
setState(ok ? 'ok' : 'error');
meta.replaceChildren(
el('span', `ls-pill ${ok ? 'ls-pill-ok' : 'ls-pill-bad'}`, status ? String(status) : 'no response'),
el('span', 'ls-dim', `${ms} ms`),
el('span', 'ls-dim', formatBytes(new Blob([text]).size)),
);
if (parsed !== null) {
const { value, count } = redact(parsed);
showBody(JSON.stringify(value, null, 2), true);
if (count) {
showNote(
'is-hint',
`${count} session-shaped ${count === 1 ? 'field is' : 'fields are'} hidden in this view so the page never carries a usable credential. Your own call receives the real values.`,
);
}
} else if (text) {
showBody(text, false);
}
if (!ok) {
showNote('is-error', explainFailure(status, parsed));
return false;
}
/* Publish exports for later steps, from the RAW body. */
const exported = [];
for (const [name, key] of Object.entries(step.exports || {})) {
if (parsed && parsed[key] !== undefined && parsed[key] !== null) {
ctx.vars[name] = parsed[key];
exported.push(name);
}
}
if (exported.length) {
showNote('is-ok', `Later steps on this page can now use ${exported.join(', ')}.`);
ctx.onExport();
}
/*
* The render lane. Read from the raw body (redaction never hides an
* asset URL, but reading raw keeps the two concerns independent), and
* stay quiet when the field is absent: a directory whose first entry
* has no portrait is a normal response, not an error to shout about.
*/
if (step.renders && parsed) {
const raw = pickValue(parsed, parsePickPath(step.renders.pick));
const url = safeAssetUrl(raw);
const kind = step.renders.kind === 'auto' || !step.renders.kind ? mediaKind(url) : step.renders.kind;
if (url && kind) result.appendChild(renderAsset(url, kind, step.renders.alt));
}
return true;
}
run.addEventListener('click', () => {
execute();
});
return { card, execute, step };
}
/* ══════════════════════════════════════════════════════════════════════
* Unknown-step placeholder. A typo in markdown must be visible to the
* author and inert for the reader, never a silent no-op.
* ══════════════════════════════════════════════════════════════════════ */
function unknownCard(id) {
const card = el('section', 'ls-card');
card.dataset.state = 'error';
const head = el('header', 'ls-head');
head.appendChild(el('span', 'ls-badge ls-badge-bad', 'UNKNOWN'));
const titles = el('div', 'ls-titles');
titles.appendChild(el('h4', 'ls-title', 'This live step is not registered'));
titles.appendChild(el('p', 'ls-target', `No step with id "${id}" exists.`));
head.appendChild(titles);
card.appendChild(head);
card.appendChild(
el(
'p',
'ls-summary',
'Documentation may only run calls that are registered in public/live-steps.js, so nothing was requested. Add the step to the registry, or fix the id in the markdown.',
),
);
return card;
}
/* ══════════════════════════════════════════════════════════════════════
* Toolbar. Appears once a page carries more than one live step, so a
* reader can watch the whole flow run in order without hunting buttons.
* ══════════════════════════════════════════════════════════════════════ */
function createToolbar(cards, ctx) {
const bar = el('div', 'ls-toolbar');
const label = el('div', 'ls-toolbar-text');
label.appendChild(el('strong', null, 'This page runs.'));
label.appendChild(
el(
'span',
null,
` ${cards.length} steps below call the live three.ws API from your browser and show the real response.`,
),
);
bar.appendChild(label);
const runAll = el('button', 'ls-run ls-run-all');
runAll.type = 'button';
runAll.append(ICONS.play(), el('span', null, 'Run every step'));
runAll.addEventListener('click', async () => {
runAll.disabled = true;
runAll.replaceChildren(el('span', 'ls-spinner'), el('span', null, 'Running'));
for (const entry of cards) {
entry.card.scrollIntoView({ block: 'center', behavior: ctx.reduceMotion ? 'auto' : 'smooth' });
await entry.execute();
}
runAll.disabled = false;
runAll.replaceChildren(ICONS.check(), el('span', null, 'Ran every step'));
});
bar.appendChild(runAll);
return bar;
}
/* ══════════════════════════════════════════════════════════════════════
* mount(root) - swap every ```live block in `root` for a card.
* ══════════════════════════════════════════════════════════════════════ */
function mount(root) {
if (!root) return [];
const blocks = root.querySelectorAll('pre > code.language-live');
if (!blocks.length) return [];
const ctx = {
vars: Object.create(null),
reduceMotion:
typeof window.matchMedia === 'function' &&
window.matchMedia('(prefers-reduced-motion: reduce)').matches,
onExport() {},
async runStep(id) {
const entry = mounted.find((m) => m.step.id === id);
return entry ? entry.execute() : false;
},
};
const mounted = [];
for (const code of blocks) {
const pre = code.parentElement;
let spec;
try {
spec = JSON.parse(code.textContent);
} catch {
spec = null;
}
const step = spec && BY_ID.get(spec.step);
if (!step) {
pre.replaceWith(unknownCard(spec ? spec.step : 'malformed block'));
continue;
}
const entry = createCard(step, spec, ctx);
pre.replaceWith(entry.card);
mounted.push(entry);
}
if (mounted.length > 1) {
mounted[0].card.parentNode.insertBefore(createToolbar(mounted, ctx), mounted[0].card);
}
return mounted;
}
window.LiveSteps = {
STEPS,
DERIVATIONS,
validateRegistry,
redact,
buildUrl,
explainFailure,
parsePickPath,
pickValue,
safeAssetUrl,
mediaKind,
mount,
};
})();