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/:id renders one Agent Spotlight entry.
*
* The reason this page exists: an entry's write-up runs to 4,000 characters and
* the index could only ever show three clamped lines of it. A showcase whose
* write-ups cannot be read is a directory with extra steps.
*
* It is also the only place an entry is WRITTEN after it is created. The index
* creates; this page edits and removes, using the same field module
* (src/spotlight-form.js), so there is exactly one implementation of the form
* and one place a builder has to find to fix a typo.
*
* The page title, meta description and canonical are set from the entry once it
* loads. Social crawlers never execute this: vercel.json rewrites them to
* api/spotlight-og.js, which renders the same facts server-side.
*/
import { apiFetch } from './api.js';
import {
buildFields,
fillCategories,
fillEntry,
readValues,
removeEntry,
saveEntry,
validate,
} from './spotlight-form.js';
import { el, entryPath, errorMessage, monogram, relativeTime, stageFor, voteButton } from './spotlight-shared.js';
import { verifiedBlock } from './spotlight-verified.js';
const root = document.getElementById('sp-entry');
const live = document.getElementById('sp-live');
let entry = null;
let categories = [];
function announce(message) {
if (live) live.textContent = message;
}
function plural(n, one, many) {
return `${n.toLocaleString()} ${n === 1 ? one : many}`;
}
function entryIdFromPath() {
const m = location.pathname.match(/^\/spotlight\/([0-9a-f-]{36})\/?$/i);
return m ? m[1] : null;
}
function categoryLabel(slug) {
return categories.find((c) => c.slug === slug)?.label || slug;
}
/* ── head ─────────────────────────────────────────────────────────────── */
// A client-rendered page still owes a correct title and canonical: the browser
// tab, a bookmark, and the history entry all read them, and so does any crawler
// that does execute JS.
function applyHead(e) {
const title = `${e.title} · Agent Spotlight · three.ws`;
document.title = title;
setMeta('name', 'description', e.tagline);
setLink('canonical', `https://three.ws/spotlight/${e.id}`);
}
function setMeta(attr, key, value) {
let node = document.head.querySelector(`meta[${attr}="${key}"]`);
if (!node) {
node = document.createElement('meta');
node.setAttribute(attr, key);
document.head.appendChild(node);
}
node.setAttribute('content', value);
}
function setLink(rel, href) {
let node = document.head.querySelector(`link[rel="${rel}"]`);
if (!node) {
node = document.createElement('link');
node.rel = rel;
document.head.appendChild(node);
}
node.href = href;
}
/* ── render ───────────────────────────────────────────────────────────── */
function breadcrumb(e) {
return el('nav', { class: 'sp-crumbs', 'aria-label': 'Breadcrumb' }, [
el('a', { href: '/spotlight', text: 'Agent Spotlight' }),
el('span', { 'aria-hidden': 'true', text: '/' }),
el('a', {
href: `/spotlight?category=${encodeURIComponent(e.category)}`,
text: categoryLabel(e.category),
}),
]);
}
function badges(e) {
// No category chip here: the breadcrumb directly above already names it, and
// printing it twice in two styles reads as a rendering bug.
const chips = [
e.agent.is_registered ? el('span', { class: 'sp-badge sp-badge-onchain', text: 'On-chain' }) : null,
e.featured ? el('span', { class: 'sp-badge', text: "Editor's pick" }) : null,
e.source === 'curated' ? el('span', { class: 'sp-badge sp-badge-curated', text: 'Curated' }) : null,
].filter(Boolean);
return chips.length ? el('div', { class: 'sp-detail-badges' }, chips) : null;
}
// A curated entry says so in words, not just a badge. The badge tells you the
// category of thing you are reading; this tells you who wrote it, which is the
// part that would otherwise put words in a builder's mouth.
function provenance(e) {
if (e.source !== 'curated') return null;
return el('p', { class: 'sp-provenance' }, [
el('strong', { text: 'Written by three.ws. ' }),
document.createTextNode(
`${e.agent.name} is ${e.builder?.name ? `${e.builder.name}'s` : 'a community'} agent; this write-up is ours, not theirs. `,
),
e.editable_by_me
? el('span', { text: 'It is your agent, so you can replace this with your own words below.' })
: document.createTextNode('Its builder can replace it with their own write-up at any time.'),
]);
}
function storyBlock(e) {
if (!e.story) return null;
// Stored as plain text with blank-line paragraph breaks. Rendered as real
// paragraphs via textContent, never innerHTML: this is user-submitted copy on
// a public page.
const paragraphs = e.story
.split(/\n{2,}/)
.map((p) => p.trim())
.filter(Boolean);
return el(
'div',
{ class: 'sp-story' },
paragraphs.map((p) => el('p', { text: p })),
);
}
function skillChips(e) {
const skills = e.agent.skills || [];
if (!skills.length) return null;
return el('div', { class: 'sp-facts-block' }, [
el('h3', { class: 'sp-facts-head', text: 'Skills' }),
el(
'div',
{ class: 'sp-tags' },
skills.slice(0, 14).map((s) => el('span', { class: 'sp-tag sp-tag-static', text: s })),
),
]);
}
// Everything in this panel is read live off the agent on each request, which is
// exactly why it belongs beside the write-up: the prose is a claim from a
// moment in time, these are facts as of now.
function factsPanel(e) {
const rows = [
['Agent', e.agent.name],
['Builder', e.builder?.name || 'Not public'],
['Published', relativeTime(e.created_at)],
['Upvotes', String(e.vote_count)],
];
if (e.agent.chat_count > 0) rows.push(['Conversations', e.agent.chat_count.toLocaleString()]);
if (e.agent.action_count > 0) rows.push(['On-chain actions', e.agent.action_count.toLocaleString()]);
if (e.view_count > 0) rows.push(['Views', e.view_count.toLocaleString()]);
if (e.agent.onchain?.network) rows.push(['Network', e.agent.onchain.network]);
return el('aside', { class: 'sp-facts', 'aria-label': 'Agent facts' }, [
el(
'dl',
{ class: 'sp-facts-list' },
rows.flatMap(([k, v]) => [el('dt', { text: k }), el('dd', { text: v })]),
),
skillChips(e),
el('div', { class: 'sp-facts-block' }, [
el('h3', { class: 'sp-facts-head', text: 'Go to the agent' }),
el('div', { class: 'sp-facts-links' }, [
el('a', { class: 'sp-btn sp-btn-sm', href: `/agents/${e.agent.id}`, text: 'Open in 3D' }),
el('a', { class: 'sp-btn sp-btn-sm', href: `/agents/${e.agent.id}/profile`, text: 'Full profile' }),
el('a', { class: 'sp-btn sp-btn-sm', href: `/agents/${e.agent.id}/ar`, text: 'View in AR' }),
]),
]),
]);
}
function shareRow(e) {
const url = `https://three.ws/spotlight/${e.id}`;
const shareText = `${e.title} (${e.agent.name} on three.ws)`;
const copy = el('button', { type: 'button', class: 'sp-btn sp-btn-sm', text: 'Copy link' });
copy.addEventListener('click', async () => {
try {
await navigator.clipboard.writeText(url);
copy.textContent = 'Copied';
announce('Link copied.');
setTimeout(() => {
copy.textContent = 'Copy link';
}, 1600);
} catch {
// Clipboard is permission-gated and can simply refuse. Select the URL
// so the visitor can copy it themselves rather than getting nothing.
const field = el('input', { class: 'sp-input', value: url, readonly: true });
copy.replaceWith(field);
field.select();
}
});
return el('div', { class: 'sp-share' }, [
copy,
el('a', {
class: 'sp-btn sp-btn-sm',
href: `https://x.com/intent/post?text=${encodeURIComponent(shareText)}&url=${encodeURIComponent(url)}`,
target: '_blank',
rel: 'noopener',
text: 'Share on X',
}),
e.demo_url
? el('a', {
class: 'sp-btn sp-btn-sm',
href: e.demo_url,
target: '_blank',
rel: 'noopener nofollow ugc',
text: 'See it live',
})
: null,
]);
}
function ownerControls(e) {
if (!e.editable_by_me) return null;
const edit = el('button', { type: 'button', class: 'sp-btn sp-btn-sm', text: 'Edit entry' });
const remove = el('button', { type: 'button', class: 'sp-btn sp-btn-sm sp-btn-danger', text: 'Remove' });
edit.addEventListener('click', () => openEditor(true));
remove.addEventListener('click', () => confirmRemove(remove));
return el('div', { class: 'sp-owner-bar' }, [
el('span', { class: 'sp-owner-label', text: 'You can edit this entry' }),
edit,
storyToggle(e),
remove,
]);
}
// Story consent is the owner's alone. A curated entry never becomes a success
// story until this button is pressed by the agent's owner; pressing it again
// withdraws, and the entry leaves /stories on the next read.
function storyToggle(e) {
if (!e.owned_by_me) return null;
const label = () => (entry.story_consent ? 'Withdraw from stories' : 'Feature as a success story');
const button = el('button', {
type: 'button',
class: `sp-btn sp-btn-sm${e.story_consent ? '' : ' sp-btn-primary'}`,
'aria-pressed': e.story_consent ? 'true' : 'false',
title: 'Show this entry and its verified results on /stories',
text: label(),
});
button.addEventListener('click', async () => {
const next = !entry.story_consent;
button.disabled = true;
button.textContent = next ? 'Featuring…' : 'Withdrawing…';
try {
const res = await apiFetch('/api/spotlight/consent', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ id: entry.id, consent: next }),
allowAnonymous: true,
});
const data = await res.json().catch(() => null);
if (res.status === 401) throw new Error('your session expired; sign in and try again');
if (!res.ok) throw new Error(errorMessage(data, `the change returned ${res.status}`));
entry.story_consent = Boolean(data.story_consent);
entry.story_consented_at = data.story_consented_at || null;
const qualifies = Boolean(entry.verified?.qualifies);
renderNote(
entry.story_consent
? qualifies
? 'Featured. This entry now appears on /stories with its verified results.'
: 'Consent saved. It appears on /stories as soon as the agent has a verified result: a coin launched, creator fees, or service income.'
: 'Withdrawn. This entry no longer appears on /stories.',
);
announce(entry.story_consent ? 'Featured as a success story.' : 'Withdrawn from stories.');
} catch (err) {
renderNote(err?.message || 'the change did not save', 'error');
} finally {
button.disabled = false;
button.textContent = label();
button.setAttribute('aria-pressed', entry.story_consent ? 'true' : 'false');
button.classList.toggle('sp-btn-primary', !entry.story_consent);
}
});
return button;
}
// Two-step, in place: a destructive action gets a real confirmation, and the
// second click is a different button than the first so a double click cannot
// delete an entry by accident.
function confirmRemove(button) {
const bar = button.parentElement;
const cancel = el('button', { type: 'button', class: 'sp-btn sp-btn-sm', text: 'Keep it' });
const confirm = el('button', {
type: 'button',
class: 'sp-btn sp-btn-sm sp-btn-danger',
text: 'Yes, remove it',
});
const prompt = el('span', { class: 'sp-owner-label', text: 'Remove this entry from the showcase?' });
const original = Array.from(bar.childNodes);
bar.replaceChildren(prompt, confirm, cancel);
cancel.addEventListener('click', () => bar.replaceChildren(...original));
confirm.addEventListener('click', async () => {
confirm.disabled = true;
confirm.textContent = 'Removing…';
try {
await removeEntry(entry.id);
announce('Entry removed.');
location.href = '/spotlight';
} catch (err) {
bar.replaceChildren(...original);
renderNote(err?.message || 'the entry could not be removed', 'error');
}
});
}
function renderNote(message, tone) {
const note = document.getElementById('sp-detail-note');
if (!note) return;
note.textContent = message;
if (tone) note.dataset.tone = tone;
else delete note.dataset.tone;
}
/* ── edit ─────────────────────────────────────────────────────────────── */
let editRefs = null;
function editorPanel() {
const fields = el('div', { id: 'sp-edit-fields' });
const note = el('p', { class: 'sp-form-note', id: 'sp-edit-note', role: 'status', 'aria-live': 'polite' });
const save = el('button', { type: 'submit', class: 'sp-btn sp-btn-primary', text: 'Save changes' });
const cancel = el('button', { type: 'button', class: 'sp-btn', text: 'Cancel' });
cancel.addEventListener('click', () => openEditor(false));
const form = el('form', { class: 'sp-panel', id: 'sp-edit-panel', hidden: true }, [
el('div', { class: 'sp-panel-head' }, [
el('h2', { class: 'sp-h2', text: 'Edit this entry' }),
el('p', {
class: 'sp-panel-note',
text: `You are editing the write-up, not ${entry.agent.name} itself. The agent's name, avatar, skills and identity always come from the agent record.`,
}),
]),
fields,
el('div', { class: 'sp-ctas' }, [save, cancel]),
note,
]);
form.addEventListener('submit', async (event) => {
event.preventDefault();
const payload = readValues(editRefs, entry.agent.id);
const problem = validate(payload);
if (problem) {
note.textContent = problem;
note.dataset.tone = 'error';
return;
}
save.disabled = true;
note.textContent = 'Saving…';
delete note.dataset.tone;
try {
entry = await saveEntry(payload);
announce('Entry updated.');
render();
} catch (err) {
note.textContent = err.unauthorized
? 'your session expired; sign in and try again'
: err?.message || 'the change did not save';
note.dataset.tone = 'error';
} finally {
save.disabled = false;
}
});
return form;
}
function openEditor(open) {
const panel = document.getElementById('sp-edit-panel');
if (!panel) return;
panel.hidden = !open;
if (!open) return;
if (!editRefs) {
editRefs = buildFields(document.getElementById('sp-edit-fields'), {
prefix: 'spe',
withAgentPicker: false,
});
}
fillCategories(editRefs, categories, entry.category);
fillEntry(editRefs, entry);
panel.scrollIntoView({ behavior: 'smooth', block: 'start' });
editRefs.title.focus();
}
/* ── related ──────────────────────────────────────────────────────────── */
async function loadRelated(e) {
const rail = document.getElementById('sp-related');
if (!rail) return;
try {
const res = await apiFetch(
`/api/spotlight/list?category=${encodeURIComponent(e.category)}&limit=4&sort=trending`,
{ allowAnonymous: true },
);
if (!res.ok) return;
const data = await res.json().catch(() => null);
const others = (data?.entries || []).filter((x) => x.id !== e.id).slice(0, 3);
if (!others.length) return;
rail.replaceChildren(
el('h2', { class: 'sp-h2', text: `More in ${categoryLabel(e.category)}` }),
el(
'div',
{ class: 'sp-related-grid' },
others.map((o) =>
el('a', { class: 'sp-related-card', href: entryPath(o) }, [
o.agent.thumbnail
? el('img', { src: o.agent.thumbnail, alt: '', loading: 'lazy', decoding: 'async' })
: monogram(o.agent),
el('div', { class: 'sp-related-copy' }, [
el('strong', { text: o.title }),
el('span', { text: o.agent.name }),
]),
]),
),
),
);
rail.hidden = false;
} catch {
// A missing related rail is not worth an error state on a page whose
// content has already rendered.
}
}
/* ── page ─────────────────────────────────────────────────────────────── */
function render() {
applyHead(entry);
const header = el('div', { class: 'sp-detail-copy' }, [
breadcrumb(entry),
badges(entry),
el('h1', { class: 'sp-detail-title', text: entry.title }),
el('p', { class: 'sp-detail-tagline', text: entry.tagline }),
el('div', { class: 'sp-card-meta' }, [
el('span', {}, [el('strong', { text: entry.agent.name })]),
entry.builder?.name
? el('span', { 'aria-hidden': 'true', text: '·' })
: null,
entry.builder?.name
? entry.builder.profile_url
? el('a', { href: entry.builder.profile_url, text: `built by ${entry.builder.name}` })
: el('span', { text: `built by ${entry.builder.name}` })
: null,
el('span', { 'aria-hidden': 'true', text: '·' }),
el('span', { text: relativeTime(entry.created_at) }),
]),
el('div', { class: 'sp-detail-actions' }, [
voteButton(entry, { announce, large: true }),
el('a', {
class: 'sp-btn sp-btn-primary',
href: `/agents/${entry.agent.id}`,
text: `Talk to ${entry.agent.name}`,
}),
]),
shareRow(entry),
]);
const main = el('div', { class: 'sp-detail-main' }, [
provenance(entry),
storyBlock(entry) ||
el('p', { class: 'sp-detail-nostory', text: 'No write-up yet, just the one-liner above.' }),
]);
// Filtered, because replaceChildren() coerces a null argument to the literal
// string "null" and prints it on the page. Only el() filters its children;
// this call is the one place a section can legitimately be absent.
const sections = [
el('div', { class: 'sp-detail-hero' }, [stageFor(entry, { eager: true }), header]),
ownerControls(entry),
verifiedBlock(entry),
entry.editable_by_me ? editorPanel() : null,
el('p', { class: 'sp-form-note', id: 'sp-detail-note', role: 'status', 'aria-live': 'polite' }),
el('div', { class: 'sp-detail-body' }, [main, factsPanel(entry)]),
el('section', { class: 'sp-related', id: 'sp-related', hidden: true }),
el('div', { class: 'sp-detail-foot' }, [
el('a', { class: 'sp-btn', href: '/spotlight', text: 'Back to the showcase' }),
el('a', { class: 'sp-btn', href: '/spotlight?submit=1', text: 'Showcase your own agent' }),
]),
].filter(Boolean);
root.replaceChildren(...sections);
root.setAttribute('aria-busy', 'false');
editRefs = null;
}
function renderMissing(message, { notFound = false } = {}) {
root.setAttribute('aria-busy', 'false');
root.replaceChildren(
el('div', { class: notFound ? 'sp-empty' : 'sp-error' }, [
el('h3', { text: notFound ? 'That entry is not here' : 'This entry did not load' }),
el('p', { text: message }),
el('a', { class: 'sp-btn sp-btn-primary', href: '/spotlight', text: 'Open the showcase' }),
]),
);
document.title = notFound ? 'Entry not found · Agent Spotlight · three.ws' : document.title;
}
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 : [];
} catch {
categories = [];
}
}
async function boot() {
const id = entryIdFromPath();
if (!id) {
renderMissing('That link does not point at a showcase entry.', { notFound: true });
return;
}
// Categories only supply human labels, so the entry never waits on them.
loadCategories();
try {
const res = await apiFetch(`/api/spotlight/get?id=${encodeURIComponent(id)}`, { allowAnonymous: true });
const data = await res.json().catch(() => null);
if (res.status === 404) {
renderMissing(
'This entry was removed, or the agent behind it is no longer public. The rest of the showcase is still here.',
{ notFound: true },
);
return;
}
if (!res.ok) throw new Error(errorMessage(data, `the entry returned ${res.status}`));
entry = data.entry;
render();
loadRelated(entry);
announce(`${entry.title}. ${plural(entry.vote_count, 'upvote', 'upvotes')}.`);
if (new URLSearchParams(location.search).get('edit') === '1' && entry.editable_by_me) {
openEditor(true);
}
} catch (err) {
renderMissing(err?.message || 'could not reach the showcase');
}
}
boot();