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
// Language support for <agent-3d> embeds. Pure: no vscode, so every rule is
// unit tested against strings and character offsets; extension.js maps the
// offsets to editor positions and wires the providers.
//
// Covers the two tags an embed is made of: the element itself, and the
// <script> that loads the library. The rules encode what docs/embedding.md says
// goes wrong in practice: an element with no source shows nothing, an element
// with no size collapses to zero, a "latest" script changes under a production
// page, and a pinned script whose integrity hash has drifted is refused by the
// browser outright.
/** Every attribute the element reads, with the docs a hover or completion shows. */
export const ATTRIBUTES = Object.freeze([
attr('src', 'On-chain agent URI, the canonical source: `agent://base/42`. Also accepts a bare GLB URL.', { source: true }),
attr('agent-id', 'Agent id: numeric token id (with `chain-id`), CAIP-10 (`eip155:8453:0xReg…:42`), or a backend id (`a_abc123`).', { source: true }),
attr('chain-id', 'Chain id that a numeric `agent-id` lives on, e.g. `8453` for Base.'),
attr('avatar-id', 'A three.ws avatar id. Loads the avatar without an agent persona.', { source: true }),
attr('manifest', 'IPFS or HTTPS URL of an agent manifest.', { source: true }),
attr('body', 'HTTPS URL of a bare GLB for an ad-hoc agent. Viewer-only unless `brain` is set.', { source: true }),
attr('brain', '`free` gives an ad-hoc `body` embed a real conversation with no API key, routed through the host-paid free tier.', { values: ['free'] }),
attr('instructions', 'System prompt for the `brain`: who the agent is and how it should behave.'),
attr('mode', 'Layout: `inline` (default, flows with the document), `floating` (fixed bubble), `section` (fills its parent), `fullscreen`.', { values: ['inline', 'floating', 'section', 'fullscreen'] }),
attr('position', 'Corner for `mode="floating"`.', { values: ['bottom-right', 'bottom-left', 'top-right', 'top-left', 'bottom-center'] }),
attr('offset', 'Distance from the edges for `mode="floating"`, e.g. `24px 24px`.'),
attr('width', 'CSS width for `mode="floating"`, e.g. `320px`. Inline embeds size through CSS instead.'),
attr('height', 'CSS height for `mode="floating"`, e.g. `420px`.'),
attr('responsive', 'Scale the layout with the container width.'),
attr('framing', 'Camera framing of the avatar: `full`, `bust`, or `face`.', { values: ['full', 'bust', 'face'] }),
attr('clip', 'Animation clip to play on load, by name.'),
attr('background', 'Background colour or `transparent`.'),
attr('poster', 'Image shown while the model loads (also available as the `poster` slot).'),
attr('name-plate', 'Show the agent name over the avatar.'),
attr('voice', 'Enable voice: the agent speaks its replies and listens to the mic.'),
attr('voice-server', 'URL of a self-hosted voice server.'),
attr('chat', 'Show the built-in chat panel.'),
attr('avatar-chat', 'Chat through the avatar (speech bubbles) instead of a panel.'),
attr('avatar-walk', 'Let the avatar walk around the page.'),
attr('sign-language', 'Sign replies in ASL alongside speech.'),
attr('wallet', 'Enable the agent wallet affordance.'),
attr('tracked-mint', 'Token mint the agent reacts to (price, holders).'),
attr('skills', 'Comma-separated skill URIs to install on load.'),
attr('skill-trust', 'Trust policy for installed skills.'),
attr('memory', 'Enable persistent conversation memory.'),
attr('memory-key', 'Storage key that scopes the memory, e.g. per user.'),
attr('api-base', 'Origin of a self-hosted three.ws API, for private deployments.'),
attr('api-key', 'API key for a self-hosted brain. Prefer `key-proxy` on public pages.'),
attr('key-proxy', 'URL of your own proxy that adds the API key server-side so it never ships in HTML.'),
attr('rpc-url', 'Custom RPC endpoint for on-chain lookups.'),
attr('registry', 'Agent registry contract to resolve `agent-id` against.'),
attr('name', 'Display name override.'),
attr('eager', 'Boot immediately instead of waiting to scroll into view.', { flag: true }),
attr('keep-alive', 'Keep the GL context running while off-screen.', { flag: true }),
attr('kiosk', 'Hide all chrome for a public display.', { flag: true }),
attr('viewer', 'Viewer-only: no chat, no voice, no brain.', { flag: true }),
]);
function attr(name, doc, extra = {}) {
return Object.freeze({ name, doc, values: extra.values || null, flag: Boolean(extra.flag), source: Boolean(extra.source) });
}
export const SOURCE_ATTRIBUTES = Object.freeze(ATTRIBUTES.filter((a) => a.source).map((a) => a.name));
/** Attributes any HTML element takes, never flagged as unknown. */
const GLOBAL_ATTRIBUTE = /^(id|class|style|slot|title|hidden|lang|dir|tabindex|role|part|is|data-[\w-]+|aria-[\w-]+|on[a-z]+)$/i;
const ELEMENT_RE = /<agent-3d\b([^>]*?)(\/?)>/gi;
const SCRIPT_RE = /<script\b([^>]*)>/gi;
const ATTR_RE = /([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|(\{[^}]*\})|([^\s"'<>`]+)))?/g;
const LIBRARY_SRC_RE = /^(https?:)?\/\/([^/]+)\/agent-3d\/([^/]+)\/agent-3d(\.umd\.cjs|\.js)$/;
const EXACT_VERSION_RE = /^\d+\.\d+\.\d+$/;
/**
* @typedef {object} Attr
* @property {string} name
* @property {string|null} value null for a bare flag
* @property {number} start offset of the name
* @property {number} end offset after the whole attribute
* @property {number} nameEnd
* @property {boolean} expression true for a JSX `{…}` value
*/
/**
* Every <agent-3d> tag in the text.
* @param {string} text
* @returns {Array<{ start: number, end: number, tagEnd: number, attrsStart: number, attrs: Attr[] }>}
*/
export function findEmbeds(text) {
const out = [];
ELEMENT_RE.lastIndex = 0;
let m;
while ((m = ELEMENT_RE.exec(text))) {
const start = m.index;
const tagEnd = start + '<agent-3d'.length;
const attrsStart = tagEnd;
out.push({ start, end: start + m[0].length, tagEnd, attrsStart, attrs: parseAttrs(m[1], attrsStart) });
}
return out;
}
/**
* Every <script> that loads the agent-3d library.
* @param {string} text
* @returns {Array<{ start: number, end: number, src: Attr, channel: string, host: string, integrity: Attr|null, exact: boolean }>}
*/
export function findLibraryScripts(text) {
const out = [];
SCRIPT_RE.lastIndex = 0;
let m;
while ((m = SCRIPT_RE.exec(text))) {
const attrs = parseAttrs(m[1], m.index + '<script'.length);
const src = attrs.find((a) => a.name.toLowerCase() === 'src' && a.value);
const lib = src && LIBRARY_SRC_RE.exec(src.value.trim());
if (!lib) continue;
const channel = lib[3];
out.push({
start: m.index,
end: m.index + m[0].length,
src,
host: lib[2],
channel,
exact: EXACT_VERSION_RE.test(channel),
integrity: attrs.find((a) => a.name.toLowerCase() === 'integrity') || null,
});
}
return out;
}
/** @param {string} chunk @param {number} base offset of chunk[0] in the document */
export function parseAttrs(chunk, base) {
const attrs = [];
ATTR_RE.lastIndex = 0;
let m;
while ((m = ATTR_RE.exec(chunk))) {
if (!m[0].trim()) continue;
const name = m[1];
const expression = m[4] !== undefined;
const value = m[2] ?? m[3] ?? m[4] ?? m[5] ?? null;
attrs.push({
name,
value,
expression,
start: base + m.index,
nameEnd: base + m.index + name.length,
end: base + m.index + m[0].length,
});
}
return attrs;
}
/** Which attribute of an embed the cursor is on, if any. */
export function attributeAt(embed, offset) {
return embed.attrs.find((a) => offset >= a.start && offset <= a.end) || null;
}
/**
* Where in an embed the cursor sits: naming an attribute, inside an
* attribute's value, or nowhere relevant. Works on a tag the user is still
* typing (no closing `>` yet), which is when completion matters most.
*
* @returns {{ kind: 'name', embed: { attrs: Attr[] } } | { kind: 'value', attr: { name: string }, def: object|null } | null}
*/
export function completionContext(text, offset) {
const open = text.lastIndexOf('<agent-3d', offset);
if (open === -1) return null;
const attrsStart = open + '<agent-3d'.length;
if (offset < attrsStart) return null;
// A `>` between the tag and the cursor means the cursor is past this tag.
const close = text.indexOf('>', attrsStart);
if (close !== -1 && close < offset) return null;
const chunk = text.slice(attrsStart, offset);
// Inside an open quote: `mode="fl` or `mode='`.
const inValue = /([^\s"'<>\/=]+)\s*=\s*(["'])([^"']*)$/.exec(chunk);
if (inValue) {
const name = inValue[1].toLowerCase();
return { kind: 'value', attr: { name }, def: ATTRIBUTES.find((d) => d.name === name) || null };
}
// After whitespace (or a partial attribute name after whitespace): naming.
if (/\s$/.test(chunk) || /\s[^\s="'<>]*$/.test(chunk)) {
return { kind: 'name', embed: { start: open, tagEnd: attrsStart, attrsStart, end: offset, attrs: parseAttrs(chunk, attrsStart) } };
}
return null;
}
/**
* @typedef {object} Finding
* @property {string} code
* @property {'error'|'warning'|'information'|'hint'} severity
* @property {string} message
* @property {number} start
* @property {number} end
* @property {{ title: string, start: number, end: number, text: string }|null} fix a single text replacement
*/
/**
* Run every rule.
*
* @param {string} text
* @param {{ release?: { channel: string, integrity: string|null } | null, origin?: string }} [ctx]
* release is the current library release from /agent-3d/versions.json; when
* absent (offline) the pinning rules that need it are skipped.
* @returns {Finding[]}
*/
export function diagnose(text, ctx = {}) {
const findings = [];
const release = ctx.release && EXACT_VERSION_RE.test(ctx.release.channel) ? ctx.release : null;
for (const embed of findEmbeds(text)) {
const names = embed.attrs.map((a) => a.name.toLowerCase());
const hasSource = names.some((n) => SOURCE_ATTRIBUTES.includes(n));
const hasSpread = embed.attrs.some((a) => a.expression && /^\{\s*\.\.\./.test(a.name) || /^\{\.\.\./.test(a.name));
if (!hasSource && !hasSpread) {
findings.push({
code: 'no-source',
severity: 'error',
message: `<agent-3d> has nothing to show. Set one of ${SOURCE_ATTRIBUTES.map((n) => `\`${n}\``).join(', ')}.`,
start: embed.start,
end: embed.tagEnd,
fix: null,
});
}
const mode = valueOf(embed, 'mode');
const style = valueOf(embed, 'style') || '';
const sized =
(/\bwidth\s*:/.test(style) && /\bheight\s*:/.test(style)) ||
(names.includes('width') && names.includes('height')) ||
names.includes('responsive') ||
(mode && mode !== 'inline') ||
hasSpread ||
embed.attrs.some((a) => a.name.toLowerCase() === 'style' && a.expression) ||
names.includes('class') || names.includes('classname');
if (!sized) {
findings.push({
code: 'no-size',
severity: 'warning',
message: 'The element has no intrinsic size and will collapse to 0×0. Give it a width and height (inline style, a class, or the width/height attributes).',
start: embed.start,
end: embed.tagEnd,
fix: {
title: 'Add an inline size (400×500)',
start: embed.tagEnd,
end: embed.tagEnd,
text: ' style="width: 400px; height: 500px; display: block;"',
},
});
}
for (const a of embed.attrs) {
const lower = a.name.toLowerCase();
if (a.expression && /^\{/.test(a.name)) continue;
const def = ATTRIBUTES.find((d) => d.name === lower);
if (!def) {
if (GLOBAL_ATTRIBUTE.test(lower) || lower === 'classname' || lower === 'key' || lower === 'ref') continue;
const guess = closest(lower);
findings.push({
code: 'unknown-attribute',
severity: 'information',
message: `\`${a.name}\` is not an attribute <agent-3d> reads.${guess ? ` Did you mean \`${guess}\`?` : ''}`,
start: a.start,
end: a.nameEnd,
fix: guess ? { title: `Rename to ${guess}`, start: a.start, end: a.nameEnd, text: guess } : null,
});
continue;
}
if (def.values && a.value !== null && !a.expression && !def.values.includes(a.value.trim())) {
findings.push({
code: 'bad-value',
severity: 'warning',
message: `\`${a.name}\` takes ${def.values.map((v) => `\`${v}\``).join(', ')}; \`${a.value}\` will be ignored.`,
start: a.nameEnd,
end: a.end,
fix: null,
});
}
if (lower === 'api-key' && a.value && !a.expression) {
findings.push({
code: 'key-in-html',
severity: 'warning',
message: 'An API key in HTML ships to every visitor. Use `key-proxy` to add it server-side, or `brain="free"`.',
start: a.start,
end: a.end,
fix: null,
});
}
}
}
for (const script of findLibraryScripts(text)) {
const target = release ? release.channel : null;
if (!script.exact) {
const moving = script.channel === 'latest';
findings.push({
code: 'unpinned-library',
severity: moving ? 'warning' : 'hint',
message: moving
? 'The `latest` channel is for demos: a release can change this page under you. Pin an exact version for production.'
: `Channel \`${script.channel}\` follows new releases automatically. Pin an exact version if this page must not change on its own.`,
start: script.src.start,
end: script.src.end,
fix: target
? pinFix(text, script, release)
: null,
});
continue;
}
if (!script.integrity) {
const known = release && release.channel === script.channel && release.integrity;
findings.push({
code: 'missing-integrity',
severity: 'hint',
message: 'Pinned, but without an `integrity` hash the browser cannot verify the bytes. Add the release hash.',
start: script.src.start,
end: script.src.end,
fix: known
? { title: `Add integrity for ${release.channel}`, start: script.src.end, end: script.src.end, text: `\n integrity="${release.integrity}"\n crossorigin="anonymous"` }
: null,
});
} else if (release && release.channel === script.channel && release.integrity && script.integrity.value?.trim() !== release.integrity) {
findings.push({
code: 'stale-integrity',
severity: 'error',
message: `The integrity hash does not match release ${release.channel}. The browser will refuse to run the library.`,
start: script.integrity.start,
end: script.integrity.end,
fix: { title: `Use the published hash for ${release.channel}`, start: script.integrity.start, end: script.integrity.end, text: `integrity="${release.integrity}"` },
});
} else if (release && release.channel !== script.channel && newer(release.channel, script.channel)) {
findings.push({
code: 'newer-release',
severity: 'hint',
message: `Release ${release.channel} is available (this page pins ${script.channel}).`,
start: script.src.start,
end: script.src.end,
fix: pinFix(text, script, release),
});
}
}
return findings;
}
function pinFix(text, script, release) {
if (!release?.integrity) return null;
// Replace the whole tag so channel and hash change together.
const tag = text.slice(script.start, script.end);
const type = /\btype\s*=\s*["']module["']/i.test(tag) ? 'module' : null;
const src = script.src.value.replace(/\/agent-3d\/[^/]+\/agent-3d/, `/agent-3d/${release.channel}/agent-3d`);
const lines = ['<script', ...(type ? [` type="${type}"`] : []), ` src="${src}"`, ` integrity="${release.integrity}"`, ' crossorigin="anonymous"', '>'];
return { title: `Pin to ${release.channel} with its integrity hash`, start: script.start, end: script.end, text: lines.join('\n') };
}
function valueOf(embed, name) {
const a = embed.attrs.find((x) => x.name.toLowerCase() === name);
return a && a.value !== null && !a.expression ? a.value : null;
}
function newer(a, b) {
const pa = a.split('.').map(Number);
const pb = b.split('.').map(Number);
for (let i = 0; i < 3; i++) {
if (pa[i] !== pb[i]) return pa[i] > pb[i];
}
return false;
}
/** Nearest known attribute by edit distance, for "did you mean". */
export function closest(name) {
let best = null;
let bestScore = Infinity;
for (const a of ATTRIBUTES) {
const d = levenshtein(name, a.name);
if (d < bestScore) {
bestScore = d;
best = a.name;
}
}
return bestScore <= Math.max(2, Math.floor(name.length / 4)) ? best : null;
}
function levenshtein(a, b) {
const m = a.length;
const n = b.length;
const row = Array.from({ length: n + 1 }, (_, i) => i);
for (let i = 1; i <= m; i++) {
let prev = row[0];
row[0] = i;
for (let j = 1; j <= n; j++) {
const tmp = row[j];
row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
prev = tmp;
}
}
return row[n];
}
/** Hover text for the tag itself. */
export function tagHover(origin = 'https://three.ws') {
return [
'**`<agent-3d>`**: a live three.ws agent (3D avatar that can talk, gesture, and run skills).',
'',
`Point it at an agent with \`src\`, \`agent-id\`, \`avatar-id\`, \`manifest\`, or a bare GLB with \`body\`. Give it a width and height.`,
'',
`[Embedding guide](${origin}/docs/embedding) · [Widget Studio](${origin}/studio)`,
].join('\n');
}