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.
Framework integration 🟡
Clean, production-ready setups for the common stacks. The golden rules:
PageAgentneeds a browser. Its constructor throws ifwindowis undefined, so never construct it during server-side rendering — build it in a client-only effect/lifecycle hook.- The ESM build leaves
threeexternal. Install it alongside:
(The CDNnpm install @three-ws/page-agent threedist/page-agent.global.jsbuild inlines three and needs no install — use that for no-code/script-tag setups.) - Always
dispose()on unmount. It tears down the WebGL context, speech queue, and DOM. One agent at a time.
React
A reusable hook that owns the lifecycle:
// usePageAgent.js
import { useEffect, useRef, useState } from 'react';
import { PageAgent } from '@three-ws/page-agent';
export function usePageAgent(config = {}) {
const ref = useRef(null);
const [agent, setAgent] = useState(null);
useEffect(() => {
const guide = new PageAgent(config);
ref.current = guide;
setAgent(guide);
return () => { guide.dispose(); ref.current = null; };
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []); // construct once; change agents via methods, not re-render
return agent;
}
// App.jsx
import { usePageAgent } from './usePageAgent';
export default function App() {
const guide = usePageAgent({ agent: 'sol', autoNarrate: true });
return (
<button onClick={() => guide?.narrate('This is the save button.', { interrupt: true })}>
Explain this
</button>
);
}
Construct once in an empty-dependency effect. To change the avatar or narration later, call
guide.setAgent(id)/guide.narrate(...)— don't tear the instance down and rebuild it on every render.
A published React wrapper also exists: @three-ws/react.
Next.js (App Router)
PageAgent is browser-only, so isolate it in a client component and construct it
in useEffect (which never runs on the server):
// components/Guide.jsx
'use client';
import { useEffect } from 'react';
export default function Guide(props) {
useEffect(() => {
let guide;
// Dynamic import keeps the 3D engine out of the server bundle entirely.
import('@three-ws/page-agent').then(({ PageAgent }) => {
guide = new PageAgent({ agent: 'vera', autoNarrate: true, ...props });
});
return () => guide?.dispose();
}, []);
return null; // the agent docks itself to <body>
}
// app/layout.jsx (or any page)
import Guide from '@/components/Guide';
export default function Layout({ children }) {
return (<>{children}<Guide /></>);
}
Pages Router is the same idea — render <Guide /> from a component and guard the
constructor behind useEffect, or next/dynamic with { ssr: false }.
Vue 3
<script setup>
import { onMounted, onBeforeUnmount } from 'vue';
import { PageAgent } from '@three-ws/page-agent';
let guide;
onMounted(() => { guide = new PageAgent({ agent: 'nova', autoNarrate: true }); });
onBeforeUnmount(() => guide?.dispose());
defineExpose({ narrate: (t) => guide?.narrate(t, { interrupt: true }) });
</script>
<template><!-- the agent docks itself; nothing to render here --></template>
The <page-agent> custom element also works in Vue templates — tell Vue it's a
custom element so it doesn't try to resolve it as a component:
// vite.config.js
export default {
plugins: [vue({ template: { compilerOptions: {
isCustomElement: (tag) => tag === 'page-agent',
}}})],
};
<script setup>import '@three-ws/page-agent';</script>
<template><page-agent avatar="nova" auto-narrate /></template>
Svelte
<script>
import { onMount } from 'svelte';
import { PageAgent } from '@three-ws/page-agent';
let guide;
onMount(() => {
guide = new PageAgent({ agent: 'atlas', autoNarrate: true });
return () => guide.dispose(); // onMount's return is the cleanup
});
</script>
Custom-element form works too — Svelte passes unknown tags straight through:
<script>import '@three-ws/page-agent';</script>
<page-agent avatar="atlas" auto-narrate></page-agent>
Astro
Astro ships zero JS by default, so opt in with a client directive. The script-tag/global build is the simplest path:
---
// src/components/Guide.astro
---
<script src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent data-avatar="echo" data-auto-narrate defer is:inline></script>
Or, in a framework island (client:only="react"), use the React setup above.
SolidJS / Qwik / Angular
The pattern is identical everywhere: construct in a client-only mount hook,
dispose() in cleanup.
// Solid
import { onMount, onCleanup } from 'solid-js';
onMount(() => { const g = new PageAgent({ agent: 'pax' }); onCleanup(() => g.dispose()); });
For Angular, build it in ngAfterViewInit and dispose in ngOnDestroy; guard
with isPlatformBrowser if you use Angular Universal (SSR).
No-code & CMS (Webflow, WordPress, Framer, Shopify, etc.)
Use the script-tag build — it needs no bundler and no three install. Paste it
into the platform's "custom code / embed / footer scripts" slot:
<script src="https://unpkg.com/@three-ws/page-agent/dist/page-agent.global.js"
data-page-agent data-avatar="nova" data-auto-narrate defer></script>
- WordPress: a "Custom HTML" block, or your theme's footer, or a headers-and- footers plugin.
- Webflow: Project Settings → Custom Code → Footer Code.
- Shopify:
theme.liquid, before</body>. For the full store treatment — a guide that walks the storefront and narrates it alongside this docked narrator — follow the step-by-step tutorial: three.ws/tutorials/shopify-store-guide.
Pin a version for stability (e.g. @three-ws/[email protected]/dist/...) so a
future release can't change behavior under you.
TypeScript
Types ship in the package — no @types/... needed. Everything is exported:
import { PageAgent, type PageAgentConfig, type RiggedAgent } from '@three-ws/page-agent';
const config: PageAgentConfig = { agent: 'sol', autoNarrate: true };
const guide = new PageAgent(config);
const current: RiggedAgent | null = guide.currentAgent;
For the <page-agent> element in JSX, declare it once:
// page-agent.d.ts
import type { PageAgentElement } from '@three-ws/page-agent';
declare global {
namespace JSX {
interface IntrinsicElements {
'page-agent': React.DetailedHTMLProps<React.HTMLAttributes<PageAgentElement>, PageAgentElement>
& { avatar?: string; position?: string; 'auto-narrate'?: boolean | string };
}
}
}
Next: API reference → · Custom avatars → · Recipes →