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
'use client';
// React wrapper around @three-ws/avatar.
//
// Exports:
// <Avatar src alt /> — wraps <three-ws-viewer> (light viewer)
// <AgentAvatar avatarId src /> — wraps the heavy <agent-3d> element
// <AvatarCreator open onExport onClose /> — declarative wrapper around
// the imperative AvatarCreator class
// useAvatar(id) — fetch /api/avatars/:id metadata
//
// Peer dep: react >= 18. No other runtime deps.
// Plain .js on purpose: every component builds its tree with createElement, so
// there is no JSX syntax to compile. A .jsx extension would only make the
// entry unloadable in Node and in bundlers that do not transpile node_modules.
// React 19 server components: the file is marked `'use client'` and every
// component touches the DOM, so this module is only valid in client trees.
import {
useEffect,
useRef,
useState,
useCallback,
createElement,
forwardRef,
} from 'react';
// ── <Avatar> ────────────────────────────────────────────────────────────────
/**
* Pure-visual avatar viewer. Mounts a <three-ws-viewer> web component and
* keeps its attributes in sync with React props.
*
* @param {object} props
* @param {string} props.src — GLB URL.
* @param {string} [props.alt] — accessibility label / caption.
* @param {string} [props.background] — CSS color or 'transparent'.
* @param {React.CSSProperties} [props.style]
* @param {string} [props.className]
* @param {(detail: { url: string }) => void} [props.onLoad]
* @param {(detail: { url: string, error: Error }) => void} [props.onError]
*/
export const Avatar = forwardRef(function Avatar(props, forwardedRef) {
const { src, alt, background, style, className, onLoad, onError, ...rest } = props;
const localRef = useRef(null);
// Side-effect: register <three-ws-viewer> on first mount.
useEffect(() => {
import('./viewer.js').catch((err) => {
console.error('[@three-ws/avatar/react] failed to load viewer:', err);
});
}, []);
// Sync `src` attribute.
useEffect(() => {
const el = localRef.current;
if (!el) return;
if (src) el.setAttribute('src', src);
else el.removeAttribute('src');
}, [src]);
// Sync `alt` attribute.
useEffect(() => {
const el = localRef.current;
if (!el) return;
if (alt) el.setAttribute('alt', alt);
else el.removeAttribute('alt');
}, [alt]);
// Sync `background` attribute.
useEffect(() => {
const el = localRef.current;
if (!el) return;
if (background) el.setAttribute('background', background);
else el.removeAttribute('background');
}, [background]);
// Bridge custom events → React props.
useEffect(() => {
const el = localRef.current;
if (!el) return;
const handleLoad = (e) => onLoad?.(e.detail || {});
const handleError = (e) => onError?.(e.detail || {});
el.addEventListener('load', handleLoad);
el.addEventListener('error', handleError);
return () => {
el.removeEventListener('load', handleLoad);
el.removeEventListener('error', handleError);
};
}, [onLoad, onError]);
const setRef = useCallback(
(node) => {
localRef.current = node;
if (typeof forwardedRef === 'function') forwardedRef(node);
else if (forwardedRef) forwardedRef.current = node;
},
[forwardedRef],
);
return createElement('three-ws-viewer', {
ref: setRef,
style,
class: className,
...rest,
});
});
// ── <AgentAvatar> ───────────────────────────────────────────────────────────
/**
* Wraps the heavy <agent-3d> element. The SDK monolith is lazy-loaded the
* first time this component mounts so callers that only use <Avatar> never
* pay the 3 MB cost.
*
* @param {object} props
* @param {string} [props.avatarId] — three.ws avatar UUID.
* @param {string} [props.src] — direct GLB URL (alternative to avatarId).
* @param {string} [props.iosSrc] — USDZ URL for iOS AR Quick Look.
* @param {boolean} [props.kiosk] — hide the debug GUI.
* @param {React.CSSProperties} [props.style]
* @param {string} [props.className]
*/
export const AgentAvatar = forwardRef(function AgentAvatar(props, forwardedRef) {
const { avatarId, src, iosSrc, kiosk, style, className, ...rest } = props;
const localRef = useRef(null);
const [ready, setReady] = useState(
typeof customElements !== 'undefined' && !!customElements.get('agent-3d'),
);
useEffect(() => {
let cancelled = false;
import('./agent.js')
.then((mod) => mod.ensureAgent3D())
.then(() => {
if (!cancelled) setReady(true);
})
.catch((err) => {
console.error('[@three-ws/avatar/react] failed to load <agent-3d>:', err);
});
return () => {
cancelled = true;
};
}, []);
useEffect(() => {
const el = localRef.current;
if (!el || !ready) return;
if (avatarId) el.setAttribute('avatar-id', avatarId);
else el.removeAttribute('avatar-id');
}, [avatarId, ready]);
useEffect(() => {
const el = localRef.current;
if (!el || !ready) return;
if (src) el.setAttribute('src', src);
else el.removeAttribute('src');
}, [src, ready]);
useEffect(() => {
const el = localRef.current;
if (!el || !ready) return;
if (iosSrc) el.setAttribute('ios-src', iosSrc);
else el.removeAttribute('ios-src');
}, [iosSrc, ready]);
useEffect(() => {
const el = localRef.current;
if (!el || !ready) return;
if (kiosk) el.setAttribute('kiosk', '');
else el.removeAttribute('kiosk');
}, [kiosk, ready]);
const setRef = useCallback(
(node) => {
localRef.current = node;
if (typeof forwardedRef === 'function') forwardedRef(node);
else if (forwardedRef) forwardedRef.current = node;
},
[forwardedRef],
);
if (!ready) {
return createElement('div', {
ref: setRef,
style: { ...style, display: 'flex', alignItems: 'center', justifyContent: 'center' },
className,
'data-three-ws-agent-loading': '',
...rest,
}, 'Loading three.ws avatar…');
}
return createElement('agent-3d', {
ref: setRef,
style,
class: className,
...rest,
});
});
// ── <AvatarCreator> ─────────────────────────────────────────────────────────
/**
* Declarative wrapper around the imperative AvatarCreator class. The modal
* is opened / closed based on the `open` prop. Exports are bridged through
* `onExport`; the user dismissing the modal fires `onClose`.
*
* @param {object} props
* @param {boolean} props.open — controls modal visibility.
* @param {(blob: Blob) => void | Promise<void>} [props.onExport]
* @param {() => void} [props.onClose]
* @param {string} [props.studioUrl]
* @param {string} [props.sessionUrl] — edit-mode session URL for an existing avatar.
*/
export function AvatarCreator(props) {
const { open, onExport, onClose, studioUrl, sessionUrl } = props;
const instanceRef = useRef(null);
// Keep latest callbacks in refs so we don't need to dispose/recreate
// the modal every time the parent re-renders with a fresh handler.
const onExportRef = useRef(onExport);
const onCloseRef = useRef(onClose);
useEffect(() => {
onExportRef.current = onExport;
}, [onExport]);
useEffect(() => {
onCloseRef.current = onClose;
}, [onClose]);
useEffect(() => {
let cancelled = false;
if (!open) return undefined;
import('./creator.js')
.then((mod) => {
if (cancelled) return;
const creator = new mod.AvatarCreator({
studioUrl,
avaturnSessionUrl: sessionUrl,
onExport: (blob) => onExportRef.current?.(blob),
onClose: () => onCloseRef.current?.(),
});
instanceRef.current = creator;
return creator.open();
})
.catch((err) => {
console.error('[@three-ws/avatar/react] AvatarCreator open failed:', err);
});
return () => {
cancelled = true;
if (instanceRef.current) {
instanceRef.current.dispose();
instanceRef.current = null;
}
};
}, [open, studioUrl, sessionUrl]);
return null;
}
// ── useAvatar(id) ───────────────────────────────────────────────────────────
/**
* Fetch a three.ws avatar record by id. Returns `{ avatar, loading, error }`.
* Re-fetches when `id` changes; aborts in-flight requests on unmount.
*
* @param {string | null | undefined} id
* @param {object} [opts]
* @param {string} [opts.apiOrigin] — override the API origin. Defaults to same-origin.
* @returns {{ avatar: any | null, loading: boolean, error: Error | null }}
*/
export function useAvatar(id, opts) {
const apiOrigin = opts?.apiOrigin;
const [state, setState] = useState({ avatar: null, loading: !!id, error: null });
useEffect(() => {
if (!id) {
setState({ avatar: null, loading: false, error: null });
return undefined;
}
const controller = new AbortController();
setState({ avatar: null, loading: true, error: null });
const base = apiOrigin ? apiOrigin.replace(/\/$/, '') : '';
fetch(`${base}/api/avatars/${encodeURIComponent(id)}`, {
signal: controller.signal,
headers: { accept: 'application/json' },
})
.then(async (res) => {
if (!res.ok) throw new Error(`avatar fetch failed: ${res.status}`);
const body = await res.json();
// API may return { avatar: {...} } or the record directly.
const avatar = body?.avatar || body;
setState({ avatar, loading: false, error: null });
})
.catch((err) => {
if (err?.name === 'AbortError') return;
setState({ avatar: null, loading: false, error: err });
});
return () => controller.abort();
}, [id, apiOrigin]);
return state;
}