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
/**
* <page-agent> custom element — @three-ws/page-agent
* ==================================================
*
* Declarative wrapper around PageAgent. The element itself is invisible (the
* agent docks itself to the page corner); it exists so a site can drop the
* companion in with pure HTML and no script:
*
* <page-agent avatar="nova" position="bottom-right" auto-narrate controls></page-agent>
*
* Attributes (all optional):
* avatar initial rigged agent id (default: visitor's saved choice / "sol")
* agents comma-separated allow-list of agent ids for the picker
* position bottom-right | bottom-left | top-right | top-left
* asset-base override GLB host
* greeting line spoken on load (ignored when auto-narrate is set)
* auto-narrate present → tour the page; value → CSS selector of segments
* muted present → start muted (visual lipsync only)
* collapsed present → start as the launcher pill
* no-picker present → hide the "change agent" affordance
* no-controls present → hide the control bar
* preset persona id — resolves greeting/systemRole/suggestedPrompts/tools
* defaults (see src/presets.js). Explicit attributes above
* still win over the preset's values.
* context JSON object of host-page state, folded (sanitized) into
* `.systemPrompt` alongside the preset's systemRole —
* e.g. context='{"page":"pricing","user":"free-tier"}'
*
* Methods mirror PageAgent: narrate, narratePage, stop, setAgent, mute,
* collapse, openPicker. Events re-dispatched as DOM CustomEvents:
* page-agent:ready | :agentchange | :state | :caption | :segment | :error
*/
import { PageAgent } from './page-agent.js';
const bool = (el, name) => el.hasAttribute(name);
/** Parse the `context` JSON attribute defensively — malformed JSON → `{}`, never throws. */
function parseContextAttr(raw) {
if (!raw) return undefined;
try {
const parsed = JSON.parse(raw);
return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
} catch {
return undefined;
}
}
// The class body is evaluated the moment the package entry is imported, and
// SSR frameworks (Next, Nuxt, SvelteKit, Astro) import it on the server, where
// `HTMLElement` does not exist. Extending a plain class there keeps the import
// itself side effect free instead of throwing at module evaluation; the element
// is only ever attached in a browser, because `registerElement()` no-ops
// without `customElements`.
const ElementBase = typeof HTMLElement === 'undefined' ? class {} : HTMLElement;
export class PageAgentElement extends ElementBase {
connectedCallback() {
if (this._agent) return;
this.style.display = 'none';
const autoAttr = this.getAttribute('auto-narrate');
const autoNarrate = this.hasAttribute('auto-narrate') ? (autoAttr || true) : false;
this._agent = new PageAgent({
agent: this.getAttribute('avatar') || undefined,
agents: this.getAttribute('agents')?.split(',').map((s) => s.trim()).filter(Boolean),
position: this.getAttribute('position') || undefined,
assetBase: this.getAttribute('asset-base') || undefined,
greeting: this.getAttribute('greeting') || undefined,
autoNarrate,
muted: bool(this, 'muted'),
collapsed: bool(this, 'collapsed'),
picker: !bool(this, 'no-picker'),
controls: !bool(this, 'no-controls'),
preset: this.getAttribute('preset') || undefined,
context: parseContextAttr(this.getAttribute('context')),
});
for (const ev of ['ready', 'agentchange', 'state', 'caption', 'segment', 'error']) {
this._agent.on(ev, (detail) => {
this.dispatchEvent(new CustomEvent(`page-agent:${ev}`, { detail, bubbles: true, composed: true }));
});
}
}
disconnectedCallback() {
this._agent?.dispose();
this._agent = null;
}
// ── Imperative API proxy ──────────────────────────────────────────────────
narrate(text, opts) { return this._agent?.narrate(text, opts); }
narratePage(opts) { return this._agent?.narratePage(opts); }
stop() { this._agent?.stop(); }
setAgent(id) { return this._agent?.setAgent(id); }
mute(on = true) { this._agent?.mute(on); }
collapse(on = true) { this._agent?.collapse(on); }
openPicker() { this._agent?.openPicker(); }
setContext(context) { this._agent?.setContext(context); }
get controller() { return this._agent; }
get currentAgent() { return this._agent?.currentAgent; }
get currentPreset() { return this._agent?.currentPreset; }
get systemPrompt() { return this._agent?.systemPrompt; }
get tools() { return this._agent?.tools; }
}
export function registerElement(tag = 'page-agent') {
if (typeof customElements !== 'undefined' && !customElements.get(tag)) {
customElements.define(tag, PageAgentElement);
}
return tag;
}