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 - the runnable API cards embedded in documentation.
*
* public/live-steps.js ships as a classic script (like tutorials-manifest.js),
* so these tests evaluate the real shipped file in a sandbox and exercise the
* exported surface. That keeps the security invariants under test in the exact
* artifact the browser loads, rather than in a parallel copy.
*/
import { describe, it, expect } from 'vitest';
import { readFileSync, readdirSync, statSync } from 'node:fs';
import { resolve, join } from 'node:path';
import vm from 'node:vm';
const ROOT = resolve(__dirname, '..');
const SOURCE = readFileSync(join(ROOT, 'public/live-steps.js'), 'utf8');
/*
* A fresh vm context has no web globals, so hand the script the same small set
* a browser would: URL and URLSearchParams for request building, and a location
* for resolving relative asset URLs. Anything beyond this (document, fetch) is
* only reached from mount(), which the browser pass in
* scripts/capture-live-steps-media.mjs exercises for real.
*/
function load() {
const sandbox = {
window: {},
URL,
URLSearchParams,
location: new URL('https://three.ws/tutorials/wallet-sign-in'),
};
vm.createContext(sandbox);
vm.runInContext(SOURCE, sandbox, { filename: 'live-steps.js' });
return sandbox.window.LiveSteps;
}
const LiveSteps = load();
describe('live-steps registry', () => {
it('loads and exposes the documented surface', () => {
expect(LiveSteps).toBeTruthy();
for (const name of ['STEPS', 'validateRegistry', 'redact', 'buildUrl', 'mount']) {
expect(typeof LiveSteps[name]).not.toBe('undefined');
}
expect(LiveSteps.STEPS.length).toBeGreaterThan(0);
});
it('every registered request is a read-only GET', () => {
for (const step of LiveSteps.STEPS) {
if (step.kind !== 'request') continue;
expect(step.method).toBe('GET');
}
});
it('every registered path is a literal same-origin /api path', () => {
for (const step of LiveSteps.STEPS) {
if (step.kind !== 'request') continue;
expect(step.path.startsWith('/api/')).toBe(true);
expect(step.path).not.toContain('..');
expect(step.path).not.toContain('//');
// A template in the path would let markdown steer the request.
expect(step.path).not.toContain('{');
expect(step.path).not.toContain(':');
}
});
it('every step carries reader-facing copy and a reference link', () => {
for (const step of LiveSteps.STEPS) {
expect(step.title.length).toBeGreaterThan(4);
expect(step.summary.length).toBeGreaterThan(20);
expect(step.docs.startsWith('/')).toBe(true);
}
});
});
describe('validateRegistry rejects unsafe entries', () => {
const base = {
id: 'x',
kind: 'request',
method: 'GET',
path: '/api/version',
title: 'x',
summary: 'x',
docs: '/docs/',
inputs: [],
exports: {},
};
it('refuses a method other than GET', () => {
expect(() => LiveSteps.validateRegistry([{ ...base, method: 'POST' }])).toThrow(/read-only/);
});
it('refuses an absolute URL as the path', () => {
expect(() => LiveSteps.validateRegistry([{ ...base, path: 'https://evil.test/api/x' }])).toThrow(
/unsafe path/,
);
});
it('refuses a traversal path', () => {
expect(() => LiveSteps.validateRegistry([{ ...base, path: '/api/../admin' }])).toThrow(
/unsafe path/,
);
});
it('refuses a protocol-relative path', () => {
expect(() => LiveSteps.validateRegistry([{ ...base, path: '//evil.test/api' }])).toThrow(
/unsafe path/,
);
});
it('refuses duplicate ids', () => {
expect(() => LiveSteps.validateRegistry([base, base])).toThrow(/duplicate/);
});
it('refuses an input name that is not a plain identifier', () => {
expect(() =>
LiveSteps.validateRegistry([{ ...base, inputs: [{ name: 'a b', label: 'x', value: '' }] }]),
).toThrow(/unsafe input name/);
});
it('refuses a step that consumes a variable nothing earlier produces', () => {
expect(() =>
LiveSteps.validateRegistry([
{ ...base, kind: 'derive', derive: 'siwsMessage', uses: ['nonce'] },
]),
).toThrow(/no earlier step exports/);
});
it('refuses a derivation that is not implemented in code', () => {
expect(() =>
LiveSteps.validateRegistry([
{ ...base, exports: { nonce: 'nonce' } },
{ ...base, id: 'y', kind: 'derive', derive: 'notAThing', uses: ['nonce'] },
]),
).toThrow(/unknown derivation/);
});
it('accepts the shipped registry', () => {
expect(LiveSteps.validateRegistry(LiveSteps.STEPS)).toBe(true);
});
});
describe('buildUrl', () => {
const step = {
path: '/api/agents/public',
inputs: [{ name: 'limit', label: 'limit', value: '3' }],
};
it('appends inputs as encoded query values', () => {
expect(LiveSteps.buildUrl(step, { limit: '5' })).toBe('/api/agents/public?limit=5');
});
it('drops blank inputs rather than sending an empty parameter', () => {
expect(LiveSteps.buildUrl(step, { limit: ' ' })).toBe('/api/agents/public');
expect(LiveSteps.buildUrl(step, {})).toBe('/api/agents/public');
});
it('cannot be steered off the path by a hostile input value', () => {
const url = LiveSteps.buildUrl(step, { limit: '../../admin?x=1#y' });
expect(url.startsWith('/api/agents/public?')).toBe(true);
expect(url).not.toContain('/admin');
expect(url).toContain('limit=..%2F..%2Fadmin%3Fx%3D1%23y');
});
it('ignores values for parameters the step does not declare', () => {
expect(LiveSteps.buildUrl(step, { limit: '2', secret: 'nope' })).toBe(
'/api/agents/public?limit=2',
);
});
});
describe('redact', () => {
it('hides session-shaped fields and counts them', () => {
const { value, count } = LiveSteps.redact({
nonce: 'keep-me',
csrf: 'hide-me',
user: { sid: 'hide-me-too', email: '[email protected]' },
});
expect(count).toBe(2);
expect(value.nonce).toBe('keep-me');
expect(value.csrf).not.toBe('hide-me');
expect(value.user.sid).not.toBe('hide-me-too');
expect(value.user.email).toBe('[email protected]');
});
it('walks arrays', () => {
const { value, count } = LiveSteps.redact({ sessions: [{ token: 'a' }, { token: 'b' }] });
expect(count).toBe(2);
expect(value.sessions.every((s) => s.token !== 'a' && s.token !== 'b')).toBe(true);
});
it('leaves an already-empty field alone rather than inventing a secret', () => {
const { value, count } = LiveSteps.redact({ token: null, csrf: '' });
expect(count).toBe(0);
expect(value.token).toBe(null);
expect(value.csrf).toBe('');
});
it('does not mutate the input, so exports still read real values', () => {
const raw = { csrf: 'real-value' };
LiveSteps.redact(raw);
expect(raw.csrf).toBe('real-value');
});
});
describe('explainFailure', () => {
it('names a cause and a next move for every branch', () => {
for (const status of [0, 401, 404, 429, 500]) {
const text = LiveSteps.explainFailure(status, null);
expect(text.length).toBeGreaterThan(30);
}
expect(LiveSteps.explainFailure(0, null)).toMatch(/offline|blocking/i);
expect(LiveSteps.explainFailure(429, null)).toMatch(/rate limited/i);
});
it('surfaces the API error description when there is one', () => {
expect(LiveSteps.explainFailure(400, { error_description: 'limit must be a number' })).toContain(
'limit must be a number',
);
});
});
describe('the SIWS message derivation', () => {
const message = LiveSteps.DERIVATIONS.siwsMessage({
domain: 'three.ws',
uri: 'https://three.ws',
nonce: 'TEST_NONCE',
address: 'YourWa11etAddress',
});
const lines = message.split('\n');
it('opens with the domain from the nonce response, not the page host', () => {
expect(lines[0]).toBe('three.ws wants you to sign in with your Solana account:');
});
it('keeps both structural blank lines the verify parser depends on', () => {
expect(lines[1]).toBe('YourWa11etAddress');
expect(lines[2]).toBe('');
expect(lines[4]).toBe('');
});
it('uses a Solana network name for Chain ID, never an EIP-155 number', () => {
expect(message).toContain('Chain ID: mainnet');
expect(message).not.toMatch(/Chain ID: \d/);
});
it('carries the nonce and a five minute expiry window', () => {
expect(message).toContain('Nonce: TEST_NONCE');
const issued = Date.parse(message.match(/Issued At: (.+)/)[1]);
const expires = Date.parse(message.match(/Expiration Time: (.+)/)[1]);
expect(expires - issued).toBe(5 * 60 * 1000);
});
it('falls back to a visible placeholder when no address is supplied', () => {
const anon = LiveSteps.DERIVATIONS.siwsMessage({
domain: 'three.ws',
uri: 'https://three.ws',
nonce: 'N',
});
expect(anon.split('\n')[1]).toBe('<your-solana-address>');
});
});
describe('the rendered-asset lane', () => {
it('parses a dotted path with indexes', () => {
expect(LiveSteps.parsePickPath('agents[0].avatar_thumbnail')).toEqual([
'agents',
0,
'avatar_thumbnail',
]);
expect(LiveSteps.parsePickPath('data.launches[2].agent.avatar_thumbnail_url')).toEqual([
'data',
'launches',
2,
'agent',
'avatar_thumbnail_url',
]);
});
it('rejects anything that is not a plain path', () => {
for (const bad of ['', 'a..b', 'a[b]', 'a[]', '.a', 'a.', 'a()', 'a[0', null, 42]) {
expect(LiveSteps.parsePickPath(bad)).toBe(null);
}
});
it('reads a value, and returns undefined rather than throwing on a miss', () => {
const body = { agents: [{ avatar_thumbnail: '/a.png' }] };
expect(LiveSteps.pickValue(body, ['agents', 0, 'avatar_thumbnail'])).toBe('/a.png');
expect(LiveSteps.pickValue(body, ['agents', 5, 'avatar_thumbnail'])).toBe(undefined);
expect(LiveSteps.pickValue(body, ['nope', 'deeper'])).toBe(undefined);
// An array where an object key is expected must not be indexed by name.
expect(LiveSteps.pickValue(body, ['agents', 'avatar_thumbnail'])).toBe(undefined);
});
it('only lets https and same-origin paths become a subresource', () => {
expect(LiveSteps.safeAssetUrl('/avatars/cz.glb')).toBe('/avatars/cz.glb');
expect(LiveSteps.safeAssetUrl('https://cdn.example/a.png')).toBe('https://cdn.example/a.png');
for (const bad of [
'javascript:alert(1)',
'data:image/svg+xml,<svg onload=alert(1)>',
'http://insecure.example/a.png',
'//evil.example/a.png',
'',
null,
{},
]) {
expect(LiveSteps.safeAssetUrl(bad)).toBe(null);
}
});
it('infers the asset kind from the extension, query string and all', () => {
expect(LiveSteps.mediaKind('/a/b.glb')).toBe('model');
expect(LiveSteps.mediaKind('/a/b.gltf?v=2')).toBe('model');
expect(LiveSteps.mediaKind('/a/b.webp#x')).toBe('image');
expect(LiveSteps.mediaKind('/a/b.JPG')).toBe('image');
expect(LiveSteps.mediaKind('/a/b.txt')).toBe(null);
expect(LiveSteps.mediaKind(null)).toBe(null);
});
it('every registered render declares a readable path, a known kind and alt text', () => {
for (const step of LiveSteps.STEPS) {
if (!step.renders) continue;
expect(LiveSteps.parsePickPath(step.renders.pick)).toBeTruthy();
expect(['image', 'model', 'auto', undefined]).toContain(step.renders.kind);
expect(String(step.renders.alt).length).toBeGreaterThan(10);
}
});
});
describe('shipped documentation only references registered steps', () => {
function walk(dir, out = []) {
for (const name of readdirSync(dir)) {
const full = join(dir, name);
if (statSync(full).isDirectory()) walk(full, out);
else if (name.endsWith('.md')) out.push(full);
}
return out;
}
const ids = new Set(LiveSteps.STEPS.map((s) => s.id));
const blocks = [];
for (const file of walk(join(ROOT, 'docs'))) {
const md = readFileSync(file, 'utf8');
const re = /```live\n([\s\S]*?)```/g;
let m;
while ((m = re.exec(md)) !== null) blocks.push({ file, body: m[1] });
}
it('finds live blocks in the docs', () => {
expect(blocks.length).toBeGreaterThan(0);
});
it('every live block is valid JSON naming a registered step', () => {
for (const block of blocks) {
const spec = JSON.parse(block.body);
expect(ids.has(spec.step), `${block.file} references unknown step "${spec.step}"`).toBe(true);
}
});
});