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
/**
* /spotlight: Agent Spotlight, the three.ws community showcase.
*
* One controller, three jobs: browse (sort + category + search + paging), vote,
* and submit. State is a single `view` object that the URL mirrors, so every
* filter combination is a shareable link and the back button works; the grid is
* re-fetched from that object rather than mutated in place, which keeps the
* "what am I looking at" question answerable from one value.
*
* A card's headline links to the ENTRY (/spotlight/:id), not the agent. The
* write-up is the thing a showcase exists to publish, and burying it behind a
* clamped three-line preview with no way to open it was the difference between a
* showcase and a directory. Every card still carries direct links to the agent
* itself in its footer.
*
* The 3D stage on the featured entry is deliberately lazy: <agent-3d> is a
* WebGL component and this is a browse surface, so the loader script is only
* injected once a featured entry with a public GLB actually scrolls into view.
* Everything below the fold renders from thumbnails.
*/
import { apiFetch } from './api.js';
import {
buildFields,
fillCategories,
readValues,
saveEntry,
validate,
} from './spotlight-form.js';
import { entryPath, errorMessage, monogram, relativeTime, stageFor, voteButton } from './spotlight-shared.js';
const PAGE_SIZE = 24;
const els = {
grid: document.getElementById('sp-grid'),
state: document.getElementById('sp-state'),
stats: document.getElementById('sp-stats'),
cats: document.getElementById('sp-cats'),
more: document.getElementById('sp-more'),
search: document.getElementById('sp-q'),
sorts: Array.from(document.querySelectorAll('.sp-sort')),
featured: document.getElementById('sp-featured'),
featuredBody: document.getElementById('sp-featured-body'),
panel: document.getElementById('sp-submit-panel'),
panelToggle: document.getElementById('sp-submit-toggle'),
panelAuth: document.getElementById('sp-submit-auth'),
fields: document.getElementById('sp-fields'),
cancel: document.getElementById('sp-cancel'),
submit: document.getElementById('sp-submit'),
formNote: document.getElementById('sp-form-note'),
live: document.getElementById('sp-live'),
};
const view = { sort: 'trending', category: null, tag: null, q: '', offset: 0 };
let total = 0;
let categories = [];
let totals = { entries: 0, builders: 0, votes: 0 };
let loadToken = 0;
let formRefs = null;
/* ── url state ────────────────────────────────────────────────────────── */
function readUrl() {
const p = new URLSearchParams(location.search);
const sort = p.get('sort');
if (sort === 'new' || sort === 'top' || sort === 'trending') view.sort = sort;
view.category = p.get('category') || null;
view.tag = p.get('tag') || null;
view.q = p.get('q') || '';
if (els.search) els.search.value = view.q;
}
function writeUrl({ replace = false } = {}) {
const p = new URLSearchParams();
if (view.sort !== 'trending') p.set('sort', view.sort);
if (view.category) p.set('category', view.category);
if (view.tag) p.set('tag', view.tag);
if (view.q) p.set('q', view.q);
const url = p.toString() ? `${location.pathname}?${p}` : location.pathname;
history[replace ? 'replaceState' : 'pushState']({ ...view }, '', url);
}
/* ── small helpers ────────────────────────────────────────────────────── */
function el(tag, props = {}, children = []) {
const node = document.createElement(tag);
for (const [k, v] of Object.entries(props)) {
if (v == null || v === false) continue;
if (k === 'class') node.className = v;
else if (k === 'text') node.textContent = v;
else if (k.startsWith('on') && typeof v === 'function') node.addEventListener(k.slice(2), v);
else node.setAttribute(k, v === true ? '' : String(v));
}
for (const child of [].concat(children)) {
if (child != null) node.append(child);
}
return node;
}
function announce(message) {
if (els.live) els.live.textContent = message;
}
function plural(n, one, many) {
return `${n.toLocaleString()} ${n === 1 ? one : many}`;
}
function categoryLabel(slug) {
return categories.find((c) => c.slug === slug)?.label || slug;
}
function onVoted(entry) {
totals.votes += entry.voted_by_me ? 1 : -1;
renderStats();
}
/* ── featured ─────────────────────────────────────────────────────────── */
function renderFeatured(entries) {
if (!entries.length) {
els.featured.hidden = true;
els.featuredBody.replaceChildren();
return;
}
const entry = entries[0];
const copy = el('div', { class: 'sp-featured-copy' }, [
el('h3', {}, [el('a', { href: entryPath(entry), text: entry.title })]),
el('p', { text: entry.tagline }),
entry.story ? el('p', { class: 'sp-featured-story', text: entry.story }) : null,
el('div', { class: 'sp-card-meta' }, metaBits(entry)),
el('div', { class: 'sp-ctas' }, [
el('a', { class: 'sp-btn sp-btn-primary', href: entryPath(entry), text: 'Read the write-up' }),
el('a', { class: 'sp-btn', href: `/agents/${entry.agent.id}`, text: `Open ${entry.agent.name}` }),
voteButton(entry, { announce, onVoted }),
]),
]);
els.featuredBody.replaceChildren(stageFor(entry, { badge: "Editor's pick" }), copy);
els.featured.hidden = false;
}
/* ── cards ────────────────────────────────────────────────────────────── */
function metaBits(entry) {
const bits = [el('span', {}, [el('strong', { text: entry.agent.name })])];
if (entry.builder?.name) {
bits.push(el('span', { 'aria-hidden': 'true', text: '·' }));
bits.push(
entry.builder.profile_url
? el('a', { href: entry.builder.profile_url, text: `by ${entry.builder.name}` })
: el('span', { text: `by ${entry.builder.name}` }),
);
}
if (entry.agent.chat_count > 0) {
bits.push(el('span', { 'aria-hidden': 'true', text: '·' }));
bits.push(el('span', { text: plural(entry.agent.chat_count, 'conversation', 'conversations') }));
} else if (entry.agent.action_count > 0) {
bits.push(el('span', { 'aria-hidden': 'true', text: '·' }));
bits.push(el('span', { text: plural(entry.agent.action_count, 'action', 'actions') }));
}
bits.push(el('span', { 'aria-hidden': 'true', text: '·' }));
bits.push(el('span', { text: relativeTime(entry.created_at) }));
return bits;
}
function cardFor(entry) {
const art = el('div', { class: 'sp-card-art' });
art.append(
entry.agent.thumbnail
? el('img', {
src: entry.agent.thumbnail,
alt: `${entry.agent.name} avatar`,
loading: 'lazy',
decoding: 'async',
})
: monogram(entry.agent),
);
art.append(
el('div', { class: 'sp-card-badges' }, [
el('span', { class: 'sp-badge', text: categoryLabel(entry.category) }),
entry.agent.is_registered ? el('span', { class: 'sp-badge sp-badge-onchain', text: 'On-chain' }) : null,
entry.source === 'curated' ? el('span', { class: 'sp-badge sp-badge-curated', text: 'Curated' }) : null,
]),
);
const tags = entry.tags.length
? el(
'div',
{ class: 'sp-tags' },
entry.tags.map((t) =>
el('button', {
type: 'button',
class: 'sp-tag',
text: `#${t}`,
onclick: (event) => {
event.preventDefault();
event.stopPropagation();
view.tag = view.tag === t ? null : t;
view.offset = 0;
writeUrl();
load();
},
}),
),
)
: null;
const body = el('div', { class: 'sp-card-body' }, [
el('h3', { class: 'sp-card-title' }, [el('a', { href: entryPath(entry), text: entry.title })]),
el('p', { class: 'sp-card-tagline', text: entry.tagline }),
el('div', { class: 'sp-card-meta' }, metaBits(entry)),
tags,
]);
const links = el('div', { class: 'sp-card-links' }, [
el('a', { href: `/agents/${entry.agent.id}`, text: 'Open agent' }),
entry.demo_url
? el('a', { href: entry.demo_url, target: '_blank', rel: 'noopener nofollow ugc', text: 'Demo' })
: null,
// Only an owner sees this, and it goes to the entry page where the edit
// form lives, so there is exactly one place an entry is written.
entry.editable_by_me ? el('a', { href: `${entryPath(entry)}?edit=1`, text: 'Edit' }) : null,
]);
return el('article', { class: 'sp-card' }, [
art,
body,
el('div', { class: 'sp-card-foot' }, [links, voteButton(entry, { announce, onVoted })]),
]);
}
/* ── loading ──────────────────────────────────────────────────────────── */
function skeletons(n = 6) {
els.grid.replaceChildren(...Array.from({ length: n }, () => el('div', { class: 'sp-skeleton' })));
}
function renderEmpty() {
const filtered = Boolean(view.q || view.category || view.tag);
const box = el('div', { class: 'sp-empty' }, [
el('h3', { text: filtered ? 'Nothing matches that yet' : 'The spotlight is open' }),
el('p', {
text: filtered
? 'No showcased agent matches this filter. Clear it to see everything the community has published.'
: 'No one has claimed the first slot. Build an agent, make it public, and write up what it does: the first entry gets the featured stage.',
}),
]);
box.append(
filtered
? el('button', {
type: 'button',
class: 'sp-btn sp-btn-primary',
text: 'Clear filters',
onclick: () => {
view.q = '';
view.category = null;
view.tag = null;
view.offset = 0;
if (els.search) els.search.value = '';
writeUrl();
renderCategories();
load();
},
})
: el('button', {
type: 'button',
class: 'sp-btn sp-btn-primary',
text: 'Showcase your agent',
onclick: () => openPanel(true),
}),
);
if (!filtered) box.append(el('a', { class: 'sp-btn', href: '/create-agent', text: 'Create an agent first' }));
els.state.replaceChildren(box);
}
function renderError(message) {
els.state.replaceChildren(
el('div', { class: 'sp-error' }, [
el('h3', { text: 'The showcase did not load' }),
el('p', { text: message }),
el('button', { type: 'button', class: 'sp-btn sp-btn-primary', text: 'Try again', onclick: () => load() }),
]),
);
}
async function load({ append = false } = {}) {
const token = ++loadToken;
if (!append) {
skeletons();
els.state.replaceChildren();
els.grid.setAttribute('aria-busy', 'true');
els.more.hidden = true;
} else {
els.more.disabled = true;
els.more.textContent = 'Loading…';
}
const p = new URLSearchParams({ sort: view.sort, limit: String(PAGE_SIZE), offset: String(view.offset) });
if (view.category) p.set('category', view.category);
if (view.tag) p.set('tag', view.tag);
if (view.q) p.set('q', view.q);
try {
const res = await apiFetch(`/api/spotlight/list?${p}`, { allowAnonymous: true });
if (token !== loadToken) return;
if (res.status === 503) {
els.grid.replaceChildren();
renderEmpty();
return;
}
const data = await res.json().catch(() => null);
if (!res.ok) throw new Error(errorMessage(data, `the showcase returned ${res.status}`));
const entries = Array.isArray(data.entries) ? data.entries : [];
total = Number(data.total) || 0;
if (append) {
els.grid.append(...entries.map(cardFor));
} else {
els.grid.replaceChildren(...entries.map(cardFor));
if (!entries.length) renderEmpty();
else els.state.replaceChildren();
}
els.more.hidden = !data.has_more;
els.more.disabled = false;
els.more.textContent = 'Load more';
view.offset = data.next_offset ?? view.offset;
announce(`${plural(total, 'showcased agent', 'showcased agents')}, sorted by ${view.sort}.`);
} catch (err) {
if (token !== loadToken) return;
els.grid.replaceChildren();
renderError(err?.message || 'could not reach the showcase');
} finally {
if (token === loadToken) els.grid.setAttribute('aria-busy', 'false');
}
}
function renderStats() {
if (!totals.entries) {
els.stats.replaceChildren();
return;
}
const stat = (value, label) => el('div', {}, [el('dd', { text: value.toLocaleString() }), el('dt', { text: label })]);
els.stats.replaceChildren(
stat(totals.entries, totals.entries === 1 ? 'agent showcased' : 'agents showcased'),
stat(totals.builders, totals.builders === 1 ? 'builder' : 'builders'),
stat(totals.votes, totals.votes === 1 ? 'upvote' : 'upvotes'),
);
}
/* ── featured rail + categories ───────────────────────────────────────── */
async function loadFeatured() {
try {
const res = await apiFetch('/api/spotlight/list?featured=1&limit=1&sort=trending', { allowAnonymous: true });
if (!res.ok) return;
const data = await res.json().catch(() => null);
renderFeatured(Array.isArray(data?.entries) ? data.entries : []);
} catch {
// A missing featured rail is not worth an error state: the grid below it
// is the page. Fail silently and leave the section hidden.
}
}
function renderCategories() {
els.cats.replaceChildren(
el('button', {
type: 'button',
class: 'sp-cat',
'aria-pressed': String(!view.category),
text: 'All',
onclick: () => selectCategory(null),
}),
...categories
.filter((c) => c.count > 0 || c.slug === view.category)
.map((c) =>
el(
'button',
{
type: 'button',
class: 'sp-cat',
'aria-pressed': String(view.category === c.slug),
onclick: () => selectCategory(c.slug),
},
[el('span', { text: c.label }), el('span', { class: 'sp-cat-count', text: String(c.count) })],
),
),
);
}
function selectCategory(slug) {
view.category = view.category === slug ? null : slug;
view.offset = 0;
writeUrl();
renderCategories();
load();
}
async function loadCategories() {
try {
const res = await apiFetch('/api/spotlight/categories', { allowAnonymous: true });
if (!res.ok) return;
const data = await res.json().catch(() => null);
categories = Array.isArray(data?.categories) ? data.categories : [];
if (data?.totals) totals = data.totals;
renderCategories();
renderStats();
if (formRefs) fillCategories(formRefs, categories);
} catch {
categories = [];
}
}
/* ── submission ───────────────────────────────────────────────────────── */
let eligibleLoaded = false;
function openPanel(open) {
els.panel.hidden = !open;
els.panelToggle.setAttribute('aria-expanded', String(open));
if (!open) return;
els.panel.scrollIntoView({ behavior: 'smooth', block: 'start' });
if (!eligibleLoaded) loadEligible();
}
async function loadEligible() {
eligibleLoaded = true;
formRefs.agentSelect.replaceChildren(new Option('Loading your agents…', ''));
try {
const res = await apiFetch('/api/spotlight/eligible', { allowAnonymous: true });
if (res.status === 401) {
eligibleLoaded = false;
showPanelAuth();
return;
}
const data = await res.json().catch(() => null);
if (!res.ok) throw new Error(errorMessage(data, 'could not load your agents'));
if (Array.isArray(data.categories) && data.categories.length && !categories.length) {
categories = data.categories.map((c) => ({ ...c, count: 0 }));
renderCategories();
}
fillCategories(formRefs, categories);
const agents = Array.isArray(data.agents) ? data.agents : [];
if (!agents.length) {
formRefs.agentSelect.replaceChildren(new Option('No eligible agents', ''));
formRefs.agentSelect.disabled = true;
els.submit.disabled = true;
formRefs.agentHint.replaceChildren(
document.createTextNode(
'Every public agent you own is already showcased, or you have not made one yet. ',
),
el('a', { href: '/create-agent', text: 'Create an agent' }),
document.createTextNode('.'),
);
return;
}
formRefs.agentSelect.disabled = false;
els.submit.disabled = false;
formRefs.agentSelect.replaceChildren(
new Option('Choose an agent…', ''),
...agents.map((a) => new Option(a.name, a.id)),
);
formRefs.agentHint.textContent = `${plural(agents.length, 'agent', 'agents')} you can showcase. Only public agents are listed.`;
// Pre-fill the one-liner from the agent's own description: the builder
// already wrote it once, and an empty field is the main reason a
// submission gets abandoned halfway.
formRefs.agentSelect.addEventListener('change', () => {
const chosen = agents.find((a) => a.id === formRefs.agentSelect.value);
if (chosen?.description && !formRefs.tagline.value.trim()) {
formRefs.tagline.value = chosen.description.replace(/\s+/g, ' ').trim().slice(0, 160);
formRefs.tagline.dispatchEvent(new Event('input'));
}
});
} catch (err) {
eligibleLoaded = false;
formRefs.agentSelect.replaceChildren(new Option('Could not load your agents', ''));
setNote(err?.message || 'could not load your agents', 'error');
}
}
function showPanelAuth() {
els.panelAuth.hidden = false;
els.panelAuth.replaceChildren(
el('span', { text: 'Sign in to put one of your agents in the spotlight.' }),
el('a', {
class: 'sp-btn sp-btn-sm sp-btn-primary',
href: `/login?next=${encodeURIComponent(location.pathname + location.search)}`,
text: 'Sign in',
}),
el('a', { class: 'sp-btn sp-btn-sm', href: '/register', text: 'Create an account' }),
);
formRefs.agentSelect.replaceChildren(new Option('Sign in first', ''));
formRefs.agentSelect.disabled = true;
els.submit.disabled = true;
}
function setNote(message, tone) {
els.formNote.textContent = message;
if (tone) els.formNote.dataset.tone = tone;
else delete els.formNote.dataset.tone;
}
async function onSubmit(event) {
event.preventDefault();
const payload = readValues(formRefs);
const problem = validate(payload);
if (problem) return setNote(problem, 'error');
els.submit.disabled = true;
setNote('Publishing…');
try {
const entry = await saveEntry(payload);
setNote('Published. Taking you to your entry…', 'success');
announce(`${payload.title} is now in the showcase.`);
location.href = entryPath(entry);
} catch (err) {
if (err.unauthorized) {
showPanelAuth();
setNote('sign in to publish', 'error');
return;
}
setNote(err?.message || 'the submission did not go through', 'error');
} finally {
els.submit.disabled = false;
}
}
/* ── wiring ───────────────────────────────────────────────────────────── */
function syncSortButtons() {
for (const btn of els.sorts) {
const active = btn.dataset.sort === view.sort;
btn.classList.toggle('is-active', active);
btn.setAttribute('aria-selected', String(active));
}
}
function wire() {
formRefs = buildFields(els.fields, { prefix: 'sp', withAgentPicker: true });
for (const btn of els.sorts) {
btn.addEventListener('click', () => {
if (view.sort === btn.dataset.sort) return;
view.sort = btn.dataset.sort;
view.offset = 0;
syncSortButtons();
writeUrl();
load();
});
}
let searchTimer;
els.search.addEventListener('input', () => {
clearTimeout(searchTimer);
searchTimer = setTimeout(() => {
const next = els.search.value.trim();
if (next === view.q) return;
view.q = next;
view.offset = 0;
writeUrl({ replace: true });
load();
}, 260);
});
els.more.addEventListener('click', () => load({ append: true }));
els.panelToggle.addEventListener('click', () => openPanel(els.panel.hidden));
els.cancel.addEventListener('click', () => openPanel(false));
els.panel.addEventListener('submit', onSubmit);
// `/` focuses search from anywhere on the page, the same shortcut the rest of
// the site uses; Escape closes the submission panel.
document.addEventListener('keydown', (event) => {
if (event.key === '/' && !/^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName || '')) {
event.preventDefault();
els.search.focus();
els.search.select();
} else if (event.key === 'Escape' && !els.panel.hidden) {
openPanel(false);
els.panelToggle.focus();
}
});
window.addEventListener('popstate', () => {
readUrl();
view.offset = 0;
syncSortButtons();
renderCategories();
load();
});
// Deep link from a card's "Edit" affordance or an empty state.
if (new URLSearchParams(location.search).get('submit') === '1') openPanel(true);
}
readUrl();
syncSortButtons();
wire();
load();
loadCategories();
loadFeatured();