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
/**
* AgentPicker — reusable 3D agent browser.
*
* Opens as a modal overlay or mounts inline. Fetches public agents from
* /api/agents/public, renders a searchable/sortable/skill-filterable grid
* with a live 3D preview of each agent's avatar, and fires a callback with
* the selected agent.
*
* Unlike the avatar gallery (raw GLBs, including accessories), this picker
* surfaces deployed *agents* — identities with a name, persona, skills, an
* optional on-chain identity, and a wearable avatar.
*
* Usage:
*
* import { openAgentPicker } from './agent-picker.js';
* const agent = await openAgentPicker(); // resolves agent | null
* const agent = await openAgentPicker({ onchainOnly: true });
*
* // Or drive it directly for inline / custom flows:
* const picker = new AgentPicker({ onSelect: (a) => {...} });
* picker.openModal();
*/
import './agent-picker.css';
import './ui-juice.css';
import { enterStagger } from './ui-juice.js';
import { onchainBadgeHTML } from './shared/onchain-badge.js';
import { ensureModelViewerOrFallback } from './shared/model-viewer-loader.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);
}
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 AGENT_PH_SVG = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round"><rect x="5" y="8" width="14" height="11" rx="3"/><path d="M12 8V4"/><circle cx="12" cy="3" r="1.4"/><circle cx="9.5" cy="13" r="1.1"/><circle cx="14.5" cy="13" r="1.1"/><path d="M2.5 12v3M21.5 12v3"/></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>`;
const SORTS = [
{ key: 'popular', label: 'Popular' },
{ key: 'newest', label: 'Newest' },
{ key: 'name', label: 'A–Z' },
];
export class AgentPicker {
/**
* @param {Object} opts
* @param {string} [opts.title='Choose a 3D agent']
* @param {string} [opts.selectedId] Pre-selected agent ID
* @param {boolean} [opts.onchainOnly=false] Start filtered to on-chain agents
* @param {'popular'|'newest'|'name'} [opts.sort='popular']
* @param {string} [opts.ctaLabel='Select agent']
* @param {Function} [opts.onSelect] Callback with the selected agent object
* @param {Function} [opts.onClose] Called when the picker is closed
*/
constructor(opts = {}) {
this.opts = {
title: opts.title || 'Choose a 3D agent',
selectedId: opts.selectedId || '',
onchainOnly: !!opts.onchainOnly,
sort: SORTS.some((s) => s.key === opts.sort) ? opts.sort : 'popular',
ctaLabel: opts.ctaLabel || 'Select agent',
onSelect: opts.onSelect || (() => {}),
onClose: opts.onClose || (() => {}),
};
this._state = {
query: '',
skill: '',
sort: this.opts.sort,
onchainOnly: this.opts.onchainOnly,
cursor: null,
loading: false,
loaded: 0,
hasMore: false,
selected: null,
loadedSkills: new Set(),
cardsById: new Map(),
modelCache: new Map(), // id -> { model_url, thumbnail_url } | null (no model)
firstPageDone: false,
reqSeq: 0,
};
this._overlay = null;
this._shell = null;
this._els = {};
this._io = null;
this._searchTimer = null;
this._onKey = this._onKey.bind(this);
}
// ── Public API ──────────────────────────────────────────────────────
openModal() {
if (this._overlay) return;
ensureModelViewer();
this._overlay = document.createElement('div');
this._overlay.className = 'apk-overlay';
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(() => {
this._overlay.classList.add('apk-open');
this._els.searchInput?.focus();
});
this._loadPage();
}
mountInline(container) {
ensureModelViewer();
this._shell = this._buildShell();
this._shell.classList.add('apk-shell--inline');
this._shell.querySelector('.apk-close')?.remove();
container.appendChild(this._shell);
this._loadPage();
}
close() {
if (this._io) { this._io.disconnect(); this._io = null; }
document.removeEventListener('keydown', this._onKey);
clearTimeout(this._searchTimer);
if (this._overlay) {
this._overlay.classList.remove('apk-open');
const ov = this._overlay;
setTimeout(() => { ov.remove(); }, 200);
this._overlay = null;
} else if (this._shell) {
this._shell.remove();
}
this._shell = null;
this.opts.onClose();
}
getSelected() { return this._state.selected; }
// ── Build ───────────────────────────────────────────────────────────
_buildShell() {
const shell = document.createElement('div');
shell.className = 'apk-shell';
shell.innerHTML = `
<div class="apk-header">
<span class="apk-title">${esc(this.opts.title)}</span>
<button type="button" class="apk-close" aria-label="Close">×</button>
</div>
<div class="apk-toolbar">
<div class="apk-search">
${SEARCH_SVG}
<input type="text" placeholder="Search 3D agents..." autocomplete="off" aria-label="Search agents" />
<button type="button" class="apk-search-clear" hidden aria-label="Clear">×</button>
</div>
<div class="apk-sort" role="tablist" aria-label="Sort agents">
${SORTS.map((s) => `
<button type="button" class="apk-sort-btn${s.key === this._state.sort ? ' active' : ''}" data-sort="${s.key}" role="tab" aria-selected="${s.key === this._state.sort}">${s.label}</button>
`).join('')}
</div>
<label class="apk-onchain-toggle">
<input type="checkbox" ${this._state.onchainOnly ? 'checked' : ''} />
On-chain
</label>
<span class="apk-status" aria-live="polite">Loading...</span>
</div>
<div class="apk-skills" aria-label="Skill filters"></div>
<div class="apk-body">
<div class="apk-grid-col">
<div class="apk-grid"></div>
</div>
<div class="apk-preview-col">
<div class="apk-preview-stage">
<div class="apk-preview-empty">Select an agent to preview</div>
</div>
<div class="apk-preview-head">
<h2 class="apk-preview-name">No agent selected</h2>
</div>
<p class="apk-preview-sub">Browse and pick a 3D agent</p>
<p class="apk-preview-desc" hidden></p>
<div class="apk-preview-skills"></div>
<a class="apk-preview-profile" target="_blank" rel="noopener" hidden>View full profile →</a>
<div class="apk-spacer"></div>
<button type="button" class="apk-cta" disabled>${esc(this.opts.ctaLabel)}</button>
</div>
</div>
`;
this._els = {
searchInput: shell.querySelector('.apk-search input'),
searchClear: shell.querySelector('.apk-search-clear'),
status: shell.querySelector('.apk-status'),
skills: shell.querySelector('.apk-skills'),
grid: shell.querySelector('.apk-grid'),
gridCol: shell.querySelector('.apk-grid-col'),
previewStage: shell.querySelector('.apk-preview-stage'),
previewName: shell.querySelector('.apk-preview-name'),
previewHead: shell.querySelector('.apk-preview-head'),
previewSub: shell.querySelector('.apk-preview-sub'),
previewDesc: shell.querySelector('.apk-preview-desc'),
previewSkills: shell.querySelector('.apk-preview-skills'),
previewProfile: shell.querySelector('.apk-preview-profile'),
cta: shell.querySelector('.apk-cta'),
};
this._wireEvents(shell);
return shell;
}
_wireEvents(shell) {
shell.querySelector('.apk-close')?.addEventListener('click', () => this.close());
// Sort
shell.querySelectorAll('.apk-sort-btn').forEach((btn) => {
btn.addEventListener('click', () => {
if (btn.dataset.sort === this._state.sort) return;
this._state.sort = btn.dataset.sort;
shell.querySelectorAll('.apk-sort-btn').forEach((b) => {
const on = b === btn;
b.classList.toggle('active', on);
b.setAttribute('aria-selected', String(on));
});
this._resetAndLoad();
});
});
// On-chain toggle
shell.querySelector('.apk-onchain-toggle input')?.addEventListener('change', (e) => {
this._state.onchainOnly = e.target.checked;
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();
});
// Skill chips
this._els.skills.addEventListener('click', (e) => {
const btn = e.target.closest('.apk-skill');
if (!btn) return;
this._state.skill = btn.dataset.skill === this._state.skill ? '' : btn.dataset.skill;
this._renderSkills();
this._resetAndLoad();
});
// CTA — guarantee the avatar (GLB + id) is resolved before handing off,
// since the list endpoint only ships a thumbnail.
this._els.cta.addEventListener('click', async () => {
const a = this._state.selected;
if (!a || this._els.cta.disabled) return;
this._els.cta.disabled = true;
const prev = this._els.cta.textContent;
this._els.cta.textContent = 'Loading…';
await this._resolveAvatar(a);
this._els.cta.textContent = prev;
this.opts.onSelect(a);
this.close();
});
this._setupInfiniteScroll();
}
_setupInfiniteScroll() {
if (!('IntersectionObserver' in window)) return;
const sentinel = document.createElement('div');
sentinel.style.height = '1px';
sentinel.className = 'apk-sentinel';
this._els.grid.parentNode.appendChild(sentinel);
this._io = new IntersectionObserver((entries) => {
for (const entry of entries) {
if (entry.isIntersecting && this._state.hasMore && 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.loaded = 0;
this._state.hasMore = false;
this._state.loadedSkills = 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 seq = ++this._state.reqSeq;
const params = new URLSearchParams();
if (this._state.query) params.set('q', this._state.query);
if (this._state.skill) params.set('skill', this._state.skill);
if (this._state.sort) params.set('sort', this._state.sort);
if (this._state.onchainOnly) params.set('onchain', '1');
if (this._state.cursor) params.set('before', this._state.cursor);
params.set('limit', String(PAGE_SIZE));
try {
const res = await fetch(`/api/agents/public?${params.toString()}`, { credentials: 'include' });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
// A newer request superseded this one (filters changed mid-flight).
if (seq !== this._state.reqSeq) return;
const agents = Array.isArray(data.agents) ? data.agents : [];
if (!this._state.firstPageDone) this._els.grid.innerHTML = '';
const fresh = [];
for (const a of agents) {
this._state.cardsById.set(a.id, a);
const card = this._renderCard(a);
this._els.grid.appendChild(card);
fresh.push(card);
this._state.loaded += 1;
for (const s of a.skills || []) this._state.loadedSkills.add(s);
}
// Stagger the freshly-landed cards in (first page + each lazy-loaded page).
enterStagger(fresh);
this._state.firstPageDone = true;
this._state.hasMore = !!data.has_more;
this._state.cursor = data.next_cursor || null;
if (this._els.grid.children.length === 0) {
this._els.grid.appendChild(this._renderEmpty());
}
this._renderSkills();
this._hydratePreselection();
} catch (err) {
if (seq !== this._state.reqSeq) return;
if (this._state.loaded === 0) {
this._els.grid.innerHTML = '';
const errDiv = document.createElement('div');
errDiv.className = 'apk-error';
errDiv.textContent = `Couldn't load agents: ${err.message}. Check your connection and try again.`;
this._els.grid.appendChild(errDiv);
}
} finally {
if (seq === this._state.reqSeq) {
this._state.loading = false;
this._updateStatus();
}
}
}
_hydratePreselection() {
if (!this.opts.selectedId || this._state.selected) return;
const match = this._state.cardsById.get(this.opts.selectedId);
if (match) this._selectAgent(match);
}
// ── Rendering ───────────────────────────────────────────────────────
_renderSkeletons(n) {
for (let i = 0; i < n; i++) {
const sk = document.createElement('div');
sk.className = 'apk-skel';
sk.innerHTML = `<div class="apk-skel-thumb"></div><div class="apk-skel-bar"></div><div class="apk-skel-bar"></div>`;
this._els.grid.appendChild(sk);
}
}
_renderEmpty() {
const div = document.createElement('div');
div.className = 'apk-empty';
const filtered = this._state.query || this._state.skill || this._state.onchainOnly;
if (filtered) {
div.innerHTML = `No agents match these filters.<br>Try a different search or clear the filters.`;
} else {
div.innerHTML = `No public 3D agents yet.<a class="apk-empty-cta" href="/create">Deploy the first one →</a>`;
}
return div;
}
_renderCard(a) {
const card = document.createElement('button');
card.type = 'button';
card.className = 'apk-card';
card.dataset.id = a.id;
if (a.id === this._state.selected?.id) card.classList.add('selected');
const thumb = a.avatar_thumbnail
? `<img src="${esc(a.avatar_thumbnail)}" alt="${esc(a.name || 'Agent')}" loading="lazy" decoding="async" />`
: `<div class="apk-card-ph">${AGENT_PH_SVG}</div>`;
const badge = onchainBadgeHTML(a, { link: false, size: 'sm', showChain: false });
const skills = (a.skills || []).slice(0, 2).map((s) =>
`<span class="apk-card-chip">${esc(s)}</span>`).join('');
const chats = Number(a.chat_count) || 0;
const desc = a.description
? `<p class="apk-card-desc">${esc(a.description)}</p>`
: '';
card.innerHTML = `
<div class="apk-card-thumb">
${badge ? `<span class="apk-card-badge">${badge}</span>` : ''}
${thumb}
</div>
<div class="apk-card-body">
<div class="apk-card-name">${esc(a.name || 'Untitled agent')}</div>
${desc}
<div class="apk-card-meta">
${skills}
${chats ? `<span class="apk-card-chip">${compact.format(chats)} chats</span>` : ''}
</div>
</div>
`;
card.addEventListener('click', () => this._selectAgent(a));
return card;
}
_selectAgent(a) {
this._state.selected = a;
// Card selection visual
this._els.grid.querySelectorAll('.apk-card.selected').forEach((c) =>
c.classList.remove('selected'));
const card = this._els.grid.querySelector(`.apk-card[data-id="${CSS.escape(a.id)}"]`);
if (card) {
card.classList.add('selected');
card.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
}
// Header: name + on-chain badge
this._els.previewName.textContent = a.name || 'Untitled agent';
this._els.previewHead.querySelector('.apk-card-badge')?.remove();
const badge = onchainBadgeHTML(a, { link: false, size: 'sm', showChain: true });
if (badge) {
const span = document.createElement('span');
span.className = 'apk-card-badge';
span.innerHTML = badge;
this._els.previewHead.appendChild(span);
}
// Subtitle
const chats = Number(a.chat_count) || 0;
const bits = [];
if (chats) bits.push(`${compact.format(chats)} chats`);
bits.push(a.is_registered ? 'On-chain agent' : 'three.ws agent');
this._els.previewSub.textContent = bits.join(' · ');
// Description
if (a.description) {
this._els.previewDesc.textContent = a.description;
this._els.previewDesc.hidden = false;
} else {
this._els.previewDesc.hidden = true;
}
// Skills
this._els.previewSkills.innerHTML = (a.skills || []).slice(0, 8).map((s) =>
`<span class="apk-preview-skill">${esc(s)}</span>`).join('');
// Profile link
this._els.previewProfile.hidden = false;
this._els.previewProfile.href = a.home_url || `/agents/${a.id}`;
// CTA
this._els.cta.disabled = false;
// 3D preview (lazy — the list endpoint only ships a thumbnail).
this._renderPreviewModel(a);
}
async _renderPreviewModel(a) {
const stage = this._els.previewStage;
stage.innerHTML = '';
// Cached model resolution from a prior selection.
if (this._state.modelCache.has(a.id)) {
this._mountPreview(a, this._state.modelCache.get(a.id));
return;
}
// Show the thumbnail immediately while the GLB URL resolves.
const spinner = document.createElement('div');
spinner.className = 'apk-preview-spinner';
if (a.avatar_thumbnail) {
const img = document.createElement('img');
img.src = a.avatar_thumbnail;
img.alt = a.name || 'Agent';
img.style.cssText = 'width:100%;height:100%;object-fit:contain;opacity:.5';
stage.appendChild(img);
}
stage.appendChild(spinner);
const resolved = await this._resolveAvatar(a);
// A different agent was selected while this resolved — drop the stale render.
if (this._state.selected?.id !== a.id) return;
stage.innerHTML = '';
this._mountPreview(a, resolved);
}
/**
* Resolve an agent's wearable avatar (GLB url, thumbnail, avatar id) from
* /api/agents/:id — the public list only ships a thumbnail. Cached per id,
* and the resolved fields are stamped onto the agent object so onSelect
* callers receive a fully-hydrated record. Returns the resolved descriptor.
*/
async _resolveAvatar(a) {
if (this._state.modelCache.has(a.id)) return this._state.modelCache.get(a.id);
let resolved = {
model_url: '',
thumbnail_url: a.avatar_thumbnail || '',
avatar_id: a.avatar_id || null,
};
try {
const res = await fetch(`/api/agents/${encodeURIComponent(a.id)}`, { credentials: 'include' });
if (res.ok) {
const { agent } = await res.json();
resolved = {
model_url: agent?.avatar_model_url || '',
thumbnail_url: agent?.avatar_thumbnail_url || a.avatar_thumbnail || '',
avatar_id: agent?.avatar_id || a.avatar_id || null,
};
}
} catch {
/* fall through to thumbnail-only resolution */
}
this._state.modelCache.set(a.id, resolved);
// Hydrate the agent record so onSelect handoff carries the avatar.
a.avatar_model_url = resolved.model_url;
a.avatar_thumbnail_url = resolved.thumbnail_url;
a.avatar_id = resolved.avatar_id;
return resolved;
}
_mountPreview(a, resolved) {
const stage = this._els.previewStage;
stage.innerHTML = '';
const modelUrl = resolved?.model_url;
const thumb = resolved?.thumbnail_url || a.avatar_thumbnail;
if (modelUrl) {
const mv = document.createElement('model-viewer');
mv.setAttribute('src', modelUrl);
mv.setAttribute('alt', a.name || 'three.ws agent');
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 (thumb) mv.setAttribute('poster', thumb);
stage.appendChild(mv);
} else if (thumb) {
const img = document.createElement('img');
img.src = thumb;
img.alt = a.name || 'Agent';
img.style.cssText = 'width:100%;height:100%;object-fit:contain';
stage.appendChild(img);
} else {
const div = document.createElement('div');
div.className = 'apk-preview-empty';
div.textContent = 'This agent has no avatar yet.';
stage.appendChild(div);
}
}
_renderSkills() {
const skills = [...this._state.loadedSkills].sort((a, b) => a.localeCompare(b)).slice(0, 24);
if (!skills.length && !this._state.skill) {
this._els.skills.innerHTML = '';
return;
}
const all = this._state.skill && !skills.includes(this._state.skill)
? [this._state.skill, ...skills]
: skills;
this._els.skills.innerHTML = all.map((s) =>
`<button type="button" class="apk-skill${s === this._state.skill ? ' active' : ''}" data-skill="${esc(s)}">${esc(s)}</button>`
).join('');
}
_updateStatus() {
if (!this._els.status) return;
if (this._state.loading && this._state.loaded === 0) {
this._els.status.textContent = 'Loading...';
return;
}
const n = integer.format(this._state.loaded);
const word = this._state.loaded === 1 ? 'agent' : 'agents';
this._els.status.textContent = this._state.hasMore ? `${n}+ ${word}` : `${n} ${word}`;
}
// ── Keyboard ────────────────────────────────────────────────────────
_onKey(e) {
if (e.key === 'Escape') this.close();
}
}
// ── Convenience wrapper: opens modal, returns a promise ─────────────────
export function openAgentPicker(opts = {}) {
return new Promise((resolve) => {
const picker = new AgentPicker({
...opts,
onSelect: (agent) => resolve(agent),
onClose: () => resolve(null),
});
picker.openModal();
});
}