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
/**
* AvatarGalleryPicker — reusable avatar browser component.
*
* Opens as a modal overlay or mounts inline. Fetches avatars from
* /api/avatars/public (browse mode) or /api/avatars (user's own),
* renders a searchable/filterable grid with live 3D preview, and
* fires a callback with the selected avatar.
*
* Usage:
*
* // Modal mode — resolves with selected avatar or null
* import { openAvatarPicker } from './avatar-gallery-picker.js';
* const avatar = await openAvatarPicker({ source: 'public' });
*
* // With pre-selected avatar
* const avatar = await openAvatarPicker({ source: 'mine', selectedId: 'abc' });
*/
import './avatar-gallery-picker.css';
import './ui-juice.css';
import { enterStagger } from './ui-juice.js';
import { onchainBadgeHTML } from './shared/onchain-badge.js';
import { walletChipHTML, wireWalletChips } from './shared/agent-wallet-chip.js';
import { ensureModelViewerOrFallback } from './shared/model-viewer-loader.js';
import { thumbFallbackAttr, wireThumbFallback } from './shared/thumb-fallback.js';
const PAGE_SIZE = 24;
// Shared loader: three CDNs, a per-source timeout and a visible fallback on
// every <model-viewer> in this picker when none of them can be reached.
function ensureModelViewer() {
ensureModelViewerOrFallback(document);
}
let _aaLoaded = false;
// Load the self-contained <avatar-actions> web component from /public on demand.
// Loading via a runtime <script type=module> (rather than a static import) keeps
// the one component definition shared by both bundled modules and plain HTML
// pages without a build-time public-dir resolution.
function ensureAvatarActions() {
if (_aaLoaded || customElements.get('avatar-actions')) return;
_aaLoaded = true;
const s = document.createElement('script');
s.type = 'module';
s.src = '/avatar-actions.js';
document.head.appendChild(s);
}
function esc(s) {
return String(s ?? '')
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"');
}
const compact = new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 });
const integer = new Intl.NumberFormat('en');
const AVATAR_PH_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="8" r="4"/><path d="M4 21c1.5-4.5 4.5-7 8-7s6.5 2.5 8 7"/></svg>`;
const SEARCH_SVG = `<svg viewBox="0 0 16 16" width="14" height="14" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><circle cx="7" cy="7" r="4.5"/><path d="m10.5 10.5 3 3"/></svg>`;
export class AvatarGalleryPicker {
/**
* @param {Object} opts
* @param {'public'|'mine'|'both'} [opts.source='both'] Which API to fetch from
* @param {string} [opts.title='Choose an avatar']
* @param {string} [opts.selectedId] Pre-selected avatar ID
* @param {boolean} [opts.showModes=true] Show share/glb/embed handoff modes
* @param {string} [opts.ctaLabel='Select avatar'] Label for the CTA button
* @param {Function} [opts.onSelect] Callback with the selected avatar object
* @param {Function} [opts.onClose] Called when the picker is closed
*/
constructor(opts = {}) {
this.opts = {
source: opts.source || 'both',
title: opts.title || 'Choose an avatar',
selectedId: opts.selectedId || '',
showModes: opts.showModes !== false,
ctaLabel: opts.ctaLabel || 'Select avatar',
onSelect: opts.onSelect || (() => {}),
onClose: opts.onClose || (() => {}),
};
this._state = {
query: '',
tag: '',
cursor: null,
loading: false,
total: null,
totalLoaded: 0,
selected: null,
mode: 'share',
loadedTags: new Set(),
cardsById: new Map(),
firstPageDone: false,
activeSource: this.opts.source === 'both' ? 'public' : this.opts.source,
};
this._overlay = null;
this._shell = null;
this._els = {};
this._io = null;
this._searchTimer = null;
this._copyTimer = null;
this._onKey = this._onKey.bind(this);
}
// ── Public API ──────────────────────────────────────────────────────
openModal() {
if (this._overlay) return;
this._closed = false;
ensureModelViewer();
this._overlay = document.createElement('div');
this._overlay.className = 'agp-overlay';
// Modal semantics, so a screen reader announces the picker as a dialog with
// a name instead of an unlabelled div, and treats the page behind it as
// inert. Only the modal path gets these: mountInline() renders the same
// shell as ordinary in-page content, where a dialog role would be a lie.
this._overlay.setAttribute('role', 'dialog');
this._overlay.setAttribute('aria-modal', 'true');
this._overlay.setAttribute('aria-label', this.opts.title);
this._overlay.addEventListener('click', (e) => {
if (e.target === this._overlay) this.close();
});
this._shell = this._buildShell();
this._overlay.appendChild(this._shell);
document.body.appendChild(this._overlay);
document.addEventListener('keydown', this._onKey);
requestAnimationFrame(() => {
// close() nulls _overlay, and a picker dismissed inside the one frame
// between mounting and this callback (Escape on a slow first paint, or a
// backdrop click landing early) left this dereferencing null and throwing
// on the player's console. Nothing to animate in if it is already gone.
if (!this._overlay) return;
this._overlay.classList.add('agp-open');
this._els.searchInput?.focus();
});
this._loadPage();
}
mountInline(container) {
this._closed = false;
ensureModelViewer();
this._shell = this._buildShell();
this._shell.classList.add('agp-shell--inline');
const close = this._shell.querySelector('.agp-close');
if (close) close.remove();
container.appendChild(this._shell);
this._loadPage();
}
close() {
// Idempotent: a fast close→navigate (e.g. the /pose page tears the picker
// down while a backdrop-dismiss is mid-flight) can call close() twice. We
// null the instance fields synchronously and operate on captured locals so
// the deferred overlay removal never dereferences a node a prior call
// already detached (TypeError: ... reading 'remove' on null).
if (this._closed) return;
this._closed = true;
if (this._io) { this._io.disconnect(); this._io = null; }
document.removeEventListener('keydown', this._onKey);
const overlay = this._overlay;
const shell = this._shell;
this._overlay = null;
this._shell = null;
if (overlay) {
overlay.classList.remove('agp-open');
setTimeout(() => overlay.remove(), 200);
} else if (shell) {
shell.remove();
}
this.opts.onClose();
}
getSelected() { return this._state.selected; }
// ── Build ───────────────────────────────────────────────────────────
_buildShell() {
const shell = document.createElement('div');
shell.className = 'agp-shell';
const showSourceToggle = this.opts.source === 'both';
const showModes = this.opts.showModes;
shell.innerHTML = `
<div class="agp-header">
<span class="agp-title">${esc(this.opts.title)}</span>
<button type="button" class="agp-close" aria-label="Close">×</button>
</div>
<div class="agp-toolbar">
${showSourceToggle ? `
<div class="agp-source-toggle" role="tablist" aria-label="Avatar source">
<button type="button" class="agp-source-btn${this._state.activeSource === 'public' ? ' active' : ''}" data-source="public">Public gallery</button>
<button type="button" class="agp-source-btn${this._state.activeSource === 'mine' ? ' active' : ''}" data-source="mine">My avatars</button>
</div>
` : ''}
<div class="agp-search">
${SEARCH_SVG}
<input type="text" placeholder="Search avatars..." autocomplete="off" aria-label="Search avatars" />
<button type="button" class="agp-search-clear" hidden aria-label="Clear">×</button>
</div>
<span class="agp-status" aria-live="polite">Loading...</span>
</div>
<div class="agp-tags" aria-label="Tag filters"></div>
<div class="agp-body">
<div class="agp-grid-col">
<div class="agp-grid"></div>
</div>
<div class="agp-preview-col">
<div class="agp-preview-stage">
<div class="agp-preview-empty">Select an avatar to preview</div>
</div>
<h2 class="agp-preview-name">No avatar selected</h2>
<p class="agp-preview-sub">Browse and pick an avatar</p>
<div class="agp-preview-tags"></div>
<avatar-actions class="agp-actions" style="display:none;margin:10px 0"></avatar-actions>
${showModes ? `
<div class="agp-modes" role="radiogroup" aria-label="Output mode">
<label><input type="radio" name="agp-mode" value="share" checked /><span>Share link</span></label>
<label><input type="radio" name="agp-mode" value="glb" /><span>GLB URL</span></label>
<label><input type="radio" name="agp-mode" value="embed" /><span>Embed</span></label>
</div>
<div class="agp-payload">Selected payload appears here</div>
` : ''}
<button type="button" class="agp-cta" disabled>${esc(this.opts.ctaLabel)}</button>
</div>
</div>
`;
this._els = {
searchInput: shell.querySelector('.agp-search input'),
searchClear: shell.querySelector('.agp-search-clear'),
status: shell.querySelector('.agp-status'),
tags: shell.querySelector('.agp-tags'),
grid: shell.querySelector('.agp-grid'),
gridCol: shell.querySelector('.agp-grid-col'),
previewStage: shell.querySelector('.agp-preview-stage'),
previewName: shell.querySelector('.agp-preview-name'),
previewSub: shell.querySelector('.agp-preview-sub'),
previewTags: shell.querySelector('.agp-preview-tags'),
actions: shell.querySelector('.agp-actions'),
payload: shell.querySelector('.agp-payload'),
cta: shell.querySelector('.agp-cta'),
};
this._wireEvents(shell);
return shell;
}
_wireEvents(shell) {
shell.querySelector('.agp-close')?.addEventListener('click', () => this.close());
// Source toggle
shell.querySelectorAll('.agp-source-btn').forEach((btn) => {
btn.addEventListener('click', () => {
const src = btn.dataset.source;
if (src === this._state.activeSource) return;
this._state.activeSource = src;
shell.querySelectorAll('.agp-source-btn').forEach((b) =>
b.classList.toggle('active', b === btn));
this._resetAndLoad();
});
});
// Search
this._els.searchInput.addEventListener('input', () => {
this._els.searchClear.hidden = !this._els.searchInput.value;
clearTimeout(this._searchTimer);
this._searchTimer = setTimeout(() => {
this._state.query = this._els.searchInput.value.trim();
this._resetAndLoad();
}, 250);
});
this._els.searchClear.addEventListener('click', () => {
this._els.searchInput.value = '';
this._els.searchClear.hidden = true;
this._state.query = '';
this._resetAndLoad();
this._els.searchInput.focus();
});
// Tags
this._els.tags.addEventListener('click', (e) => {
const btn = e.target.closest('.agp-tag');
if (!btn) return;
this._state.tag = btn.dataset.tag === this._state.tag ? '' : btn.dataset.tag;
this._renderTags();
this._resetAndLoad();
});
// Mode radio
shell.querySelectorAll('input[name="agp-mode"]').forEach((input) => {
input.addEventListener('change', () => {
if (!input.checked) return;
this._state.mode = input.value;
this._updatePayload();
});
});
// CTA
this._els.cta.addEventListener('click', () => {
if (!this._state.selected) return;
if (this.opts.showModes) {
this._copyPayload();
} else {
this.opts.onSelect(this._state.selected);
this.close();
}
});
// Infinite scroll
this._setupInfiniteScroll();
}
_setupInfiniteScroll() {
if (!('IntersectionObserver' in window)) return;
const sentinel = document.createElement('div');
sentinel.style.height = '1px';
sentinel.className = 'agp-sentinel';
this._els.grid.parentNode.appendChild(sentinel);
this._io = new IntersectionObserver((entries) => {
for (const entry of entries) {
if (entry.isIntersecting && this._state.cursor && !this._state.loading) {
this._loadPage();
}
}
}, { root: this._els.gridCol, rootMargin: '300px 0px' });
this._io.observe(sentinel);
}
// ── Data ────────────────────────────────────────────────────────────
_resetAndLoad() {
this._state.cursor = null;
this._state.totalLoaded = 0;
this._state.total = null;
this._state.loadedTags = new Set();
this._state.firstPageDone = false;
this._state.cardsById = new Map();
this._els.grid.innerHTML = '';
this._renderSkeletons(6);
this._loadPage();
}
async _loadPage() {
if (this._state.loading) return;
this._state.loading = true;
this._updateStatus();
const isPublic = this._state.activeSource === 'public';
const baseUrl = isPublic ? '/api/avatars/public' : '/api/avatars';
const params = new URLSearchParams();
if (this._state.query) params.set('q', this._state.query);
if (this._state.tag) params.set('tag', this._state.tag);
if (this._state.cursor) params.set('cursor', this._state.cursor);
params.set('limit', String(PAGE_SIZE));
if (!this._state.firstPageDone) params.set('totals', '1');
try {
const res = await fetch(`${baseUrl}?${params.toString()}`, { credentials: 'include' });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
const avatars = Array.isArray(data.avatars) ? data.avatars : [];
// Clear skeletons on first page
if (!this._state.firstPageDone) {
this._els.grid.innerHTML = '';
}
const fresh = [];
for (const a of avatars) {
this._state.cardsById.set(a.id, a);
const card = this._renderCard(a);
this._els.grid.appendChild(card);
fresh.push(card);
this._state.totalLoaded += 1;
for (const t of a.tags || []) this._state.loadedTags.add(t);
}
wireThumbFallback(this._els.grid);
// Stagger the freshly-landed avatar cards in (first page + each lazy page).
enterStagger(fresh);
if (!this._state.firstPageDone) {
if (typeof data.total === 'number') this._state.total = data.total;
this._state.firstPageDone = true;
}
this._state.cursor = data.next_cursor || null;
if (this._els.grid.children.length === 0) {
const empty = document.createElement('div');
empty.className = 'agp-empty';
empty.textContent = this._state.query || this._state.tag
? 'No avatars match these filters.'
: isPublic ? 'No public avatars yet.' : 'You don\'t have any avatars yet.';
this._els.grid.appendChild(empty);
}
this._renderTags();
this._hydratePreselection();
} catch (err) {
if (this._state.totalLoaded === 0) {
this._els.grid.innerHTML = '';
this._els.grid.appendChild(this._errorState(err));
}
} finally {
this._state.loading = false;
this._updateStatus();
}
}
// A dead "Failed to load: Failed to fetch" left the only path out of the
// picker as closing it. Say what happened in plain words and offer the retry.
_errorState(err) {
const box = document.createElement('div');
box.className = 'agp-error';
box.setAttribute('role', 'alert');
const title = document.createElement('p');
title.className = 'agp-error-title';
title.textContent = 'Could not load avatars';
box.appendChild(title);
const detail = document.createElement('p');
detail.className = 'agp-error-detail';
detail.textContent = /failed to fetch|networkerror|load failed/i.test(err?.message || '')
? 'The request did not reach three.ws. Check your connection, then try again.'
: `The avatar service answered with ${err?.message || 'an unexpected error'}.`;
box.appendChild(detail);
const retry = document.createElement('button');
retry.type = 'button';
retry.className = 'agp-error-retry';
retry.textContent = 'Try again';
retry.addEventListener('click', () => {
this._els.grid.innerHTML = '';
this._renderSkeletons(6);
this._loadPage();
});
box.appendChild(retry);
return box;
}
_hydratePreselection() {
if (!this.opts.selectedId || this._state.selected) return;
const match = this._state.cardsById.get(this.opts.selectedId);
if (match) this._selectAvatar(match);
}
// ── Rendering ───────────────────────────────────────────────────────
_renderSkeletons(n) {
for (let i = 0; i < n; i++) {
const sk = document.createElement('div');
sk.className = 'agp-skel';
sk.innerHTML = `<div class="agp-skel-thumb"></div><div class="agp-skel-bar"></div><div class="agp-skel-bar"></div>`;
this._els.grid.appendChild(sk);
}
}
_renderCard(a) {
const card = document.createElement('button');
card.type = 'button';
card.className = 'agp-card';
card.dataset.id = a.id;
if (a.id === this._state.selected?.id) card.classList.add('selected');
const phFallback = `<div class="agp-card-ph">${AVATAR_PH_SVG}</div>`;
const thumb = a.thumbnail_url
? `<img src="${esc(a.thumbnail_url)}" alt="${esc(a.name || 'Avatar')}" loading="lazy" decoding="async" ${thumbFallbackAttr(phFallback, esc)} />`
: phFallback;
const tags = (a.tags || []).slice(0, 2).map((t) =>
`<span class="agp-card-chip">${esc(t)}</span>`).join('');
const views = Number(a.view_count) || 0;
// The card is a <button>, so render a non-link badge (no nested anchor /
// click conflict). The explorer link lives on the agent's own pages.
const onchain = onchainBadgeHTML(a, { link: false, size: 'sm', showChain: false });
// The card is a <button>; render the wallet chip as a non-interactive,
// vanity-aware badge (link:false → no nested copy/explorer controls). It
// no-ops until the avatar record carries a custodial solana_address.
const wallet = walletChipHTML(a, { isOwner: false, showPending: false, link: false });
card.innerHTML = `
<div class="agp-card-thumb">${thumb}</div>
<div class="agp-card-body">
<div class="agp-card-name">${esc(a.name || 'Untitled')}</div>
<div class="agp-card-meta">
${onchain}
${wallet}
${tags}
${views ? `<span class="agp-card-chip">${compact.format(views)} views</span>` : ''}
</div>
</div>
`;
wireWalletChips(card);
card.addEventListener('click', () => this._selectAvatar(a));
return card;
}
_selectAvatar(a) {
this._state.selected = a;
// Update card selection visual
this._els.grid.querySelectorAll('.agp-card.selected').forEach((c) =>
c.classList.remove('selected'));
const card = this._els.grid.querySelector(`.agp-card[data-id="${CSS.escape(a.id)}"]`);
if (card) {
card.classList.add('selected');
card.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
}
// Preview info
this._els.previewName.textContent = a.name || 'Untitled';
const tagBits = (a.tags || []).join(' · ') || 'three.ws avatar';
const views = Number(a.view_count) || 0;
this._els.previewSub.textContent = views
? `${tagBits} · ${compact.format(views)} views`
: tagBits;
// Preview tags
if (this._els.previewTags) {
this._els.previewTags.innerHTML = (a.tags || []).slice(0, 6).map((t) =>
`<span class="agp-preview-tag">${esc(t)}</span>`).join('');
}
// Ownership + wallet surface: a previewed avatar you don't own gets
// "Save to my avatars" (fork); your own gets its agent-wallet panel.
if (this._els.actions) {
ensureAvatarActions();
const el = this._els.actions;
el.style.display = 'block';
if (customElements.get('avatar-actions')) el.avatar = a;
else el.setAttribute('avatar-id', a.id);
}
// 3D preview
this._els.previewStage.innerHTML = '';
if (a.model_url) {
const mv = document.createElement('model-viewer');
mv.setAttribute('src', a.model_url);
mv.setAttribute('alt', a.name || 'three.ws avatar');
mv.setAttribute('camera-controls', '');
mv.setAttribute('auto-rotate', '');
mv.setAttribute('rotation-per-second', '16deg');
mv.setAttribute('interaction-prompt', 'none');
mv.setAttribute('exposure', '1.05');
mv.setAttribute('shadow-intensity', '0.8');
mv.setAttribute('environment-image', 'neutral');
if (a.thumbnail_url) mv.setAttribute('poster', a.thumbnail_url);
this._els.previewStage.appendChild(mv);
} else if (a.thumbnail_url) {
const img = document.createElement('img');
img.src = a.thumbnail_url;
img.alt = a.name || 'Avatar';
img.style.cssText = 'width:100%;height:100%;object-fit:contain';
this._els.previewStage.appendChild(img);
} else {
const div = document.createElement('div');
div.className = 'agp-preview-empty';
div.textContent = 'No preview available for this avatar.';
this._els.previewStage.appendChild(div);
}
this._els.cta.disabled = false;
this._updatePayload();
}
_renderTags() {
const tags = [...this._state.loadedTags].sort((a, b) => a.localeCompare(b)).slice(0, 20);
if (!tags.length && !this._state.tag) {
this._els.tags.innerHTML = '';
return;
}
const all = this._state.tag && !tags.includes(this._state.tag)
? [this._state.tag, ...tags]
: tags;
this._els.tags.innerHTML = all.map((t) =>
`<button type="button" class="agp-tag${t === this._state.tag ? ' active' : ''}" data-tag="${esc(t)}">${esc(t)}</button>`
).join('');
}
_updateStatus() {
if (!this._els.status) return;
if (this._state.loading && this._state.totalLoaded === 0) {
this._els.status.textContent = 'Loading...';
return;
}
if (this._state.total != null) {
this._els.status.textContent = `${integer.format(this._state.totalLoaded)} of ${integer.format(this._state.total)}`;
} else {
this._els.status.textContent = `${integer.format(this._state.totalLoaded)} avatars`;
}
}
// ── Payload / copy ──────────────────────────────────────────────────
_buildPayload() {
const a = this._state.selected;
if (!a) return '';
if (this._state.mode === 'share') return `https://three.ws/avatars/${a.id}`;
if (this._state.mode === 'glb') return a.model_url || '';
return `<script type="module" src="https://three.ws/avatar-sdk/dist/index.mjs"><\/script>\n<agent-3d avatar-id="${a.id}" style="width:100%;height:480px"></agent-3d>`;
}
_updatePayload() {
if (!this._els.payload) return;
if (!this._state.selected) {
this._els.payload.textContent = 'Selected payload appears here';
return;
}
const payload = this._buildPayload();
this._els.payload.textContent = payload || '(not available for this mode)';
}
async _copyPayload() {
const payload = this._buildPayload();
if (!payload) return;
try {
await navigator.clipboard.writeText(payload);
const prev = this._els.cta.textContent;
this._els.cta.classList.add('copied');
this._els.cta.textContent = 'Copied!';
if (this._copyTimer) clearTimeout(this._copyTimer);
this._copyTimer = setTimeout(() => {
this._els.cta.classList.remove('copied');
this._els.cta.textContent = prev;
}, 1400);
} catch (err) {
if (this._els.payload) {
this._els.payload.textContent = `Clipboard blocked: ${err.message}\n\n${payload}`;
}
}
}
// ── Keyboard ────────────────────────────────────────────────────────
_onKey(e) {
if (e.key === 'Escape') this.close();
}
}
// ── Convenience wrapper: opens modal, returns a promise ─────────────────
export function openAvatarPicker(opts = {}) {
return new Promise((resolve) => {
const picker = new AvatarGalleryPicker({
...opts,
onSelect: (avatar) => resolve(avatar),
onClose: () => resolve(null),
});
picker.openModal();
});
}