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
#!/usr/bin/env node
// Renders the four diagrams for the IBM Community article draft
// docs/ibm-community-defi-3d-sperax.md into docs/media/.
//
// Styled for IBM Community's light theme (IBM Plex Sans, Carbon greys, IBM
// blue) so they sit natively in the post rather than looking pasted in.
//
// Every value drawn is read from the shipped source it describes:
// - the emotion decay seconds come from SperaxOS src/components/Avatar3D/emotions.ts
// - the tool names come from public/sperax/manifest.json
// - the ported packages come from STRUCTURE.md and each package README
//
// node scripts/render-ibm-sperax-diagrams.mjs
import { chromium } from 'playwright';
import { mkdirSync } from 'node:fs';
import { resolve, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const outDir = resolve(root, 'docs/media');
mkdirSync(outDir, { recursive: true });
const BLUE = '#0f62fe';
const TEAL = '#007d79';
const PURPLE = '#8a3ffc';
const MAGENTA = '#d02670';
const GREEN = '#198038';
const INK = '#161616';
const MUTE = '#525252';
const LINE = '#e0e0e0';
const shell = (w, body, extraCss = '') => `<!doctype html><html><head><meta charset="utf-8">
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600;700&display=swap" rel="stylesheet">
<style>
*{ margin:0; padding:0; box-sizing:border-box; }
html,body{ width:${w}px; background:#fff; color:${INK};
font-family:'IBM Plex Sans', system-ui, sans-serif; }
.wrap{ width:100%; padding:56px 64px; display:flex; flex-direction:column; }
.kicker{ font-size:19px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; color:${BLUE}; margin-bottom:10px; }
h1{ font-size:42px; font-weight:600; letter-spacing:-.01em; line-height:1.15; }
.sub{ font-size:21px; color:${MUTE}; margin-top:12px; line-height:1.45; max-width:1500px; }
.mono{ font-family:'IBM Plex Mono', ui-monospace, monospace; }
.foot{ margin-top:44px; padding-top:22px; border-top:1px solid ${LINE};
display:flex; justify-content:space-between; font-size:17px; color:${MUTE}; }
${extraCss}
</style></head><body><div class="wrap">${body}</div></body></html>`;
const foot = (left) =>
`<div class="foot"><span>${left}</span><span class="mono">three.ws × SperaxOS</span></div>`;
// ── 1. Two integration paths ────────────────────────────────────────────────
const paths = () =>
shell(
2000,
`
<div class="kicker">Embedding an agent in someone else's application</div>
<h1>Two integration paths. Ship both, in this order.</h1>
<div class="sub">The choice is not how to render an avatar. It is who owns the React tree.</div>
<div class="cols">
${[
{
n: '1',
c: BLUE,
t: 'Standalone plugin',
w: 'The host will not take your code',
items: [
['One hosted manifest', 'served with CORS at a well-known URL'],
['One hosted iframe', 'the visible avatar panel'],
['Four HTTP endpoints', 'render_agent, speak, gesture, emote'],
],
pro: 'Live in a day. Nothing to vendor, review, or audit.',
con: 'No shared context. A second renderer. Cannot compose into a message.',
},
{
n: '2',
c: PURPLE,
t: 'Native component',
w: 'The host wants the dependency',
items: [
['npm install three.ws', 'the <agent-3d> custom element'],
['Same React tree', 'no iframe, no sandbox'],
['Client tool lane', 'animation calls never leave the browser'],
],
pro: 'Composes into chat messages. Finds the bugs the iframe hides.',
con: 'A dependency the host has to trust and upgrade.',
},
]
.map(
(p) => `<div class="card" style="border-top:6px solid ${p.c}">
<div class="cn" style="color:${p.c}">Path ${p.n}</div>
<div class="ct">${p.t}</div>
<div class="cw">When: ${p.w}</div>
<div class="rows">${p.items
.map(
(i) =>
`<div class="row"><div class="rt mono" style="color:${p.c}">${i[0]}</div><div class="rs">${i[1]}</div></div>`,
)
.join('')}</div>
<div class="verdict"><span class="tag good">Gets you</span>${p.pro}</div>
<div class="verdict"><span class="tag bad">Costs you</span>${p.con}</div>
</div>`,
)
.join('')}
</div>
${foot('SperaxOS is in both camps at once, so the integration has both halves')}`,
`
.cols{ display:grid; grid-template-columns:1fr 1fr; gap:34px; margin-top:36px; }
.card{ border:1px solid ${LINE}; background:#f4f4f4; padding:32px 34px 30px; display:flex; flex-direction:column; }
.cn{ font-size:17px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; }
.ct{ font-size:34px; font-weight:600; margin-top:6px; }
.cw{ font-size:20px; color:${MUTE}; margin-top:6px; }
.rows{ margin-top:24px; display:flex; flex-direction:column; gap:14px; }
.row{ background:#fff; border:1px solid ${LINE}; padding:14px 18px; }
.rt{ font-size:20px; font-weight:500; }
.rs{ font-size:18px; color:${MUTE}; margin-top:3px; }
.verdict{ font-size:19px; color:${INK}; margin-top:18px; line-height:1.45; }
.tag{ display:inline-block; font-size:15px; font-weight:600; letter-spacing:.06em; text-transform:uppercase;
padding:3px 9px; margin-right:10px; vertical-align:2px; }
.good{ background:#defbe6; color:${GREEN}; }
.bad{ background:#fff1f1; color:${MAGENTA}; }`,
);
// ── 2. Two halves per tool call ─────────────────────────────────────────────
// The connector is one SVG rather than CSS pseudo-elements: borders on the
// boxes plus 1px pseudo-element rules read as an unintended open rectangle.
const forkConnector = () => {
const W = 1872;
const H = 92;
const cx = W / 2;
const lx = W * 0.235;
const rx = W * 0.765;
const head = (x) =>
`<path d="M ${x - 8} ${H - 13} L ${x} ${H - 1} L ${x + 8} ${H - 13}" fill="none" stroke="${MUTE}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/>`;
return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}" style="display:block">
<path d="M ${cx} 0 L ${cx} ${H / 2} M ${lx} ${H / 2} L ${rx} ${H / 2} M ${lx} ${H / 2} L ${lx} ${H - 2} M ${rx} ${H / 2} L ${rx} ${H - 2}"
fill="none" stroke="${MUTE}" stroke-width="2"/>
${head(lx)}${head(rx)}
</svg>`;
};
const halves = () =>
shell(
2000,
`
<div class="kicker">The rule that keeps the body honest</div>
<h1>Every tool call runs in two halves, in parallel.</h1>
<div class="sub">The model never asserts that it waved. It receives a result saying the wave was dispatched, and the panel is what actually waved.</div>
<div class="flow">
<div class="step host">
<div class="sl">Host application</div>
<div class="sb mono">the model calls a tool<br><span style="color:${BLUE}">speak(text, sentiment)</span></div>
</div>
${forkConnector()}
<div class="fork">
<div class="branch" style="border-top:5px solid ${PURPLE}">
<div class="bl" style="color:${PURPLE}">2a the visible body</div>
<div class="sb">host frames <span class="mono">ui.url</span> and posts the call into it<br>
<span class="mono" style="color:${PURPLE}"><agent-3d></span> animates the avatar in the panel</div>
</div>
<div class="branch" style="border-top:5px solid ${TEAL}">
<div class="bl" style="color:${TEAL}">2b the model-facing result</div>
<div class="sb">gateway POSTs the arguments to <span class="mono">api[].url</span><br>
<span class="mono" style="color:${TEAL}">{ ok: true, action: "speak", spoken: "..." }</span></div>
</div>
</div>
</div>
<div class="note"><strong>The bug this prevents:</strong> the first version confirmed any agent ID. A user with a typo got a model
saying "I have bound to your agent" over an empty panel, forever. The endpoint now resolves the ID before it answers, and a
database outage degrades to an unverified binding rather than a 500, so an outage on one side never takes the host's chat panel down.</div>
${foot('Both halves run on every call')}`,
`
.flow{ margin-top:40px; display:flex; flex-direction:column; align-items:center; }
.step{ border:1px solid ${LINE}; background:#f4f4f4; padding:22px 34px; text-align:center; min-width:660px; }
.host{ border-top:5px solid ${BLUE}; }
.sl{ font-size:17px; font-weight:600; letter-spacing:.08em; text-transform:uppercase; color:${MUTE}; }
.sb{ font-size:21px; margin-top:8px; line-height:1.55; }
.fork{ display:grid; grid-template-columns:1fr 1fr; gap:56px; width:100%; }
.branch{ border:1px solid ${LINE}; background:#fff; padding:24px 30px; }
.bl{ font-size:19px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; margin-bottom:6px; }
.note{ margin-top:38px; border-left:5px solid ${BLUE}; background:#edf5ff; padding:20px 26px;
font-size:20px; line-height:1.55; color:${INK}; }`,
);
// ── 3. Empathy Layer decay curves ───────────────────────────────────────────
// intensity(t) = exp(-ln(20) * t / decaySeconds): a full spike reaches 0.05 at
// decaySeconds, matching DECAY_FLOOR in emotions.ts.
const EMOTIONS = [
{ name: 'celebration', secs: 6, color: MAGENTA, why: 'bright but brief' },
{ name: 'curiosity', secs: 8, color: BLUE, why: 'alert, engaged' },
{ name: 'concern', secs: 12, color: '#ff832b', why: 'lingers, so a risk stays on the face' },
{ name: 'empathy', secs: 13, color: PURPLE, why: 'slow to fade, like the real thing' },
{ name: 'patience', secs: 20, color: TEAL, why: 'sustained waiting state' },
];
function decayChart() {
const W = 1080;
const H = 470;
const PADL = 74;
const PADB = 62;
const PADT = 18;
const TMAX = 22;
const x = (t) => PADL + (t / TMAX) * (W - PADL - 30);
const y = (v) => PADT + (1 - v) * (H - PADT - PADB);
const ln20 = Math.log(20);
const curves = EMOTIONS.map((e) => {
const pts = [];
for (let i = 0; i <= 220; i++) {
const t = (i / 220) * TMAX;
pts.push(`${x(t).toFixed(1)},${y(Math.exp((-ln20 * t) / e.secs)).toFixed(1)}`);
}
return `<polyline points="${pts.join(' ')}" fill="none" stroke="${e.color}" stroke-width="3.5" stroke-linecap="round"/>
<circle cx="${x(e.secs).toFixed(1)}" cy="${y(0.05).toFixed(1)}" r="5" fill="${e.color}"/>`;
}).join('');
const grid = [0, 0.25, 0.5, 0.75, 1]
.map(
(v) =>
`<line x1="${PADL}" y1="${y(v)}" x2="${W - 30}" y2="${y(v)}" stroke="${LINE}" stroke-width="1"/>
<text x="${PADL - 14}" y="${y(v) + 6}" text-anchor="end" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">${v.toFixed(2)}</text>`,
)
.join('');
const ticks = [0, 5, 10, 15, 20]
.map(
(t) =>
`<text x="${x(t)}" y="${H - PADB + 30}" text-anchor="middle" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">${t}s</text>`,
)
.join('');
return `<svg width="${W}" height="${H}" viewBox="0 0 ${W} ${H}">
${grid}
<line x1="${PADL}" y1="${y(0.05)}" x2="${W - 30}" y2="${y(0.05)}" stroke="${MUTE}" stroke-width="1" stroke-dasharray="5 5"/>
<text x="${W - 32}" y="${y(0.05) - 12}" text-anchor="end" font-size="17" fill="${MUTE}" font-family="IBM Plex Mono">DECAY_FLOOR 0.02 to 0.05</text>
${curves}${ticks}
<text x="${PADL}" y="${H - 12}" font-size="18" fill="${MUTE}">time since the event spiked the emotion</text>
</svg>`;
}
const empathy = () =>
shell(
2000,
`
<div class="kicker">Section 2 · the Empathy Layer</div>
<h1>A continuous blend, not a state machine.</h1>
<div class="sub">Each emotion is a float in [0, 1]. Events spike it, and it decays exponentially at its own rate. Every active
emotion is blended into morph targets and body language on every frame, so a face can hold three feelings at once.</div>
<div class="grid">
<div class="chart">${decayChart()}</div>
<div class="legend">
<div class="lh">Decay is the personality</div>
${EMOTIONS.map(
(e) => `<div class="li">
<span class="swatch" style="background:${e.color}"></span>
<span class="ln mono">${e.name}</span>
<span class="ls mono">${e.secs}s</span>
<span class="lw">${e.why}</span>
</div>`,
).join('')}
<div class="blendbox">
<div class="lh" style="margin-bottom:14px">What a face holds at one moment</div>
${[
['concern', 40, '#ff832b'],
['curiosity', 30, BLUE],
['neutral', 30, '#8d8d8d'],
]
.map(
([n, p, c]) => `<div class="bar">
<span class="bn mono">${n}</span>
<span class="btrack"><span class="bfill" style="width:${p}%;background:${c}"></span></span>
<span class="bp mono">${p}%</span></div>`,
)
.join('')}
<div class="bnote">A state machine has to pick one of these. That snap is what reads as a cartoon.</div>
</div>
</div>
</div>
${foot('Values read from the shipped emotion table, ported between both codebases')}`,
`
.grid{ display:grid; grid-template-columns:1080px 1fr; gap:44px; margin-top:32px; align-items:start; }
.chart{ border:1px solid ${LINE}; background:#f4f4f4; padding:16px 10px 4px; }
.legend{ display:flex; flex-direction:column; }
.lh{ font-size:19px; font-weight:600; letter-spacing:.06em; text-transform:uppercase; color:${MUTE}; margin-bottom:16px; }
.li{ display:flex; align-items:baseline; gap:12px; padding:11px 0; border-bottom:1px solid ${LINE}; }
.swatch{ width:16px; height:16px; flex:0 0 16px; }
.ln{ font-size:21px; font-weight:500; width:170px; }
.ls{ font-size:21px; color:${INK}; width:64px; }
.lw{ font-size:18px; color:${MUTE}; }
.blendbox{ margin-top:34px; border:1px solid ${LINE}; background:#edf5ff; padding:24px 26px; }
.bar{ display:flex; align-items:center; gap:14px; margin-bottom:12px; }
.bn{ font-size:19px; width:140px; }
.btrack{ flex:1; height:16px; background:#fff; border:1px solid ${LINE}; }
.bfill{ display:block; height:100%; }
.bp{ font-size:19px; width:60px; text-align:right; }
.bnote{ font-size:18px; color:${MUTE}; margin-top:14px; line-height:1.5; }`,
);
// ── 4. Two-way code exchange ────────────────────────────────────────────────
const exchange = () =>
shell(
2000,
`
<div class="kicker">Section 5 · the part nobody puts in a press release</div>
<h1>Most of the code moved in the direction opposite to the marketing.</h1>
<div class="sub">If you are negotiating an integration, this is the clause to push for: a shared right to port implementation between the two codebases.</div>
<div class="ex">
<div class="side">
<div class="sh" style="color:${BLUE}">three.ws → SperaxOS</div>
${[
['Empathy Layer', 'continuous emotion blend, engine kept pure'],
['Lip-sync driver', 'RMS amplitude to a jaw morph, composed on top'],
['Inline 3D chat element', 'a live model inside a markdown message'],
['Client tool dispatcher', 'animation calls never round-trip a server'],
['Hash-chained action ledger', 'plus the reconcile job that reads it'],
]
.map(
(i) =>
`<div class="item"><div class="it">${i[0]}</div><div class="is">${i[1]}</div></div>`,
)
.join('')}
</div>
<div class="arrows"><div class="a" style="color:${BLUE}">→</div><div class="a" style="color:${TEAL}">←</div></div>
<div class="side">
<div class="sh" style="color:${TEAL}">SperaxOS → three.ws</div>
${[
['@three-ws/defi-utils', 'chain and token constants, address validation'],
['@three-ws/tool-sdk', 'defineTool, defineExecutor, toMcpTools'],
['Liquidation collector', 'three exchange streams, since hardened'],
['Rigor about sourcing', 'no figure ships that cannot be read live'],
['A second production host', 'the environment that found our real bugs'],
]
.map(
(i) =>
`<div class="item"><div class="it">${i[0]}</div><div class="is">${i[1]}</div></div>`,
)
.join('')}
</div>
</div>
${foot('A partnership measured in merged code ages better than one measured in announcements')}`,
`
.ex{ display:grid; grid-template-columns:1fr 120px 1fr; gap:0; margin-top:38px; align-items:start; }
.side{ border:1px solid ${LINE}; background:#f4f4f4; padding:28px 30px; }
.sh{ font-size:23px; font-weight:600; letter-spacing:.04em; text-transform:uppercase; margin-bottom:20px; }
.item{ background:#fff; border:1px solid ${LINE}; padding:14px 18px; margin-bottom:12px; }
.it{ font-size:22px; font-weight:500; }
.is{ font-size:18px; color:${MUTE}; margin-top:3px; }
.arrows{ display:flex; flex-direction:column; align-items:center; justify-content:center; height:100%; padding-top:90px; gap:26px; }
.a{ font-size:56px; line-height:1; }`,
);
const JOBS = [
['ibm-sperax-integration-paths.png', paths()],
['ibm-sperax-tool-call-halves.png', halves()],
['ibm-sperax-empathy-decay.png', empathy()],
['ibm-sperax-code-exchange.png', exchange()],
];
// Height is whatever the content needs: a fixed canvas leaves a band of dead
// white under every diagram, which reads as a broken image in a blog post.
const browser = await chromium.launch();
for (const [file, html] of JOBS) {
const page = await browser.newPage({ viewport: { width: 2000, height: 800 }, deviceScaleFactor: 1 });
await page.setContent(html, { waitUntil: 'networkidle' });
await page.evaluate(() => document.fonts.ready);
await page.screenshot({ path: resolve(outDir, file), fullPage: true });
const box = await page.evaluate(() => document.body.scrollHeight);
await page.close();
console.log(`wrote docs/media/${file} (2000x${box})`);
}
await browser.close();