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
/**
* Rendering pieces shared by /spotlight and /spotlight/:id.
*
* Both surfaces draw the same entry: the same 3D stage, the same upvote button
* with the same optimistic-free settle, the same monogram fallback for an agent
* with no public avatar. Keeping them here means a card and a detail page can
* never disagree about what an entry looks like or what a vote does.
*/
import { apiFetch } from './api.js';
const AGENT_3D_LOADER = 'https://three.ws/agent-3d/latest/agent-3d.js';
export 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;
}
// The API answers errors as { error, error_description } (api/_lib/http.js).
// Reading `error.message` instead, which is the shape most JSON APIs use, threw
// away every server-side validation message and replaced it with a bare status
// code, so a builder was told "the submission returned 400" instead of "the
// headline needs at least 3 characters". One reader, used everywhere.
export function errorMessage(payload, fallback) {
return payload?.error_description || payload?.error?.message || fallback;
}
export function entryPath(entry) {
return `/spotlight/${entry.id}`;
}
export function relativeTime(iso) {
const then = new Date(iso).getTime();
if (!Number.isFinite(then)) return '';
const mins = Math.round((Date.now() - then) / 60000);
if (mins < 1) return 'just now';
if (mins < 60) return `${mins}m ago`;
const hours = Math.round(mins / 60);
if (hours < 24) return `${hours}h ago`;
const days = Math.round(hours / 24);
if (days < 30) return `${days}d ago`;
return new Date(then).toLocaleDateString(undefined, { month: 'short', year: 'numeric' });
}
// Deterministic hue from the agent id: the same agent keeps the same monogram
// colour on every card, in every session, without storing anything.
function hueOf(id) {
let h = 0;
for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) % 360;
return h;
}
export function monogram(agent) {
const hue = hueOf(agent.id || agent.name || 'agent');
const initials = (agent.name || '?')
.split(/\s+/)
.slice(0, 2)
.map((w) => w[0])
.join('')
.toUpperCase();
const node = el('div', { class: 'sp-mono', 'aria-hidden': 'true', text: initials });
node.style.background = `linear-gradient(140deg, hsl(${hue} 62% 26%), hsl(${(hue + 48) % 360} 55% 14%))`;
return node;
}
let agent3dRequested = false;
function loadAgent3d() {
if (agent3dRequested) return;
agent3dRequested = true;
const s = document.createElement('script');
s.type = 'module';
s.src = AGENT_3D_LOADER;
document.head.appendChild(s);
}
// Swap the still for the viewer only when <agent-3d> reports `agent:ready`, the
// component's one success signal: the GLB is loaded, framed and holding its
// idle. Until then the viewer stays transparent (spotlight.css), and at that
// moment the still goes and the viewer fades in, in the same frame. The still
// is a bind-pose render and the viewer's canvas is transparent, so any moment
// both are visible reads as a second, T-posed copy of the avatar standing
// behind the live one. Watching for a canvas used to be the signal here, but the
// component draws into its shadow root, which a MutationObserver on the host
// never sees, so the still stayed up for the life of the page.
//
// On `agent:error` the viewer is removed instead, leaving the still as the only
// thing on the stage: an image of the avatar beats an empty, draggable void.
// When neither event fires (the loader script never arrived) the still simply
// stays, which is also the right outcome.
export function revealWhenReady(viewer, still) {
viewer.addEventListener(
'agent:ready',
() => {
still.classList.add('is-hidden');
still.setAttribute('aria-hidden', 'true');
viewer.classList.add('is-ready');
},
{ once: true },
);
viewer.addEventListener(
'agent:error',
() => {
if (!still.classList.contains('is-hidden')) viewer.remove();
},
{ once: true },
);
}
/**
* The 3D stage. `eager: true` mounts the viewer immediately (the detail page,
* where the stage IS the page); the default waits for the stage to scroll into
* view, because below-the-fold WebGL on a browse page costs a visitor real
* frames for something they may never reach.
*/
export function stageFor(entry, { badge = null, eager = false } = {}) {
const stage = el('div', { class: 'sp-stage' });
if (badge) stage.append(el('span', { class: 'sp-stage-badge', text: badge }));
// The still goes in first and stays until the 3D viewer has actually painted.
// A GLB can fail for reasons this page does not control (a cold CDN, a blocked
// origin, no WebGL on the device), and a silently empty hero is the worst
// version of that failure.
const still = entry.agent.thumbnail
? el('img', {
class: 'sp-stage-still',
src: entry.agent.thumbnail,
alt: `${entry.agent.name} avatar`,
loading: eager ? 'eager' : 'lazy',
decoding: 'async',
})
: monogram(entry.agent);
stage.append(still);
if (!entry.agent.glb_url) return stage;
const mount = () => {
loadAgent3d();
const viewer = el('agent-3d', {
body: entry.agent.glb_url,
autorotate: 'true',
'camera-controls': 'true',
'aria-label': `${entry.agent.name} in 3D`,
});
// Listeners go on before the element is attached, so a model that is
// already cached cannot report ready before anyone is listening.
revealWhenReady(viewer, still);
stage.append(viewer);
};
if (eager || !('IntersectionObserver' in window)) {
mount();
} else {
const io = new IntersectionObserver(
(entries, obs) => {
if (entries.some((e) => e.isIntersecting)) {
obs.disconnect();
mount();
}
},
{ rootMargin: '200px' },
);
io.observe(stage);
}
return stage;
}
/**
* The upvote toggle. Never optimistic: the count and pressed state settle on
* what the server returns, so two tabs, a double click and a lost request all
* converge on the same truth instead of drifting apart.
*
* `onVoted` is called with the mutated entry after a successful toggle, which is
* how the page's headline totals stay in step without a refetch.
*/
export function voteButton(entry, { announce = () => {}, onVoted = () => {}, large = false } = {}) {
const count = el('span', { class: 'sp-vote-count', text: String(entry.vote_count) });
const btn = el(
'button',
{
type: 'button',
class: large ? 'sp-vote sp-vote-lg' : 'sp-vote',
'aria-pressed': String(Boolean(entry.voted_by_me)),
'aria-label': `Upvote ${entry.title}`,
title: 'Upvote',
},
[el('span', { class: 'sp-vote-caret', 'aria-hidden': 'true', text: '▲' }), count],
);
btn.addEventListener('click', async (event) => {
event.preventDefault();
event.stopPropagation();
btn.classList.add('is-busy');
try {
const res = await apiFetch('/api/spotlight/vote', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ id: entry.id }),
allowAnonymous: true,
});
if (res.status === 401) {
location.href = `/login?next=${encodeURIComponent(location.pathname + location.search)}`;
return;
}
const data = await res.json().catch(() => null);
if (!res.ok) {
announce(errorMessage(data, 'the vote did not go through'));
return;
}
entry.vote_count = data.vote_count;
entry.voted_by_me = data.voted;
count.textContent = String(data.vote_count);
btn.setAttribute('aria-pressed', String(data.voted));
announce(
`${data.voted ? 'Upvoted' : 'Removed your upvote from'} ${entry.title}. ${data.vote_count} total.`,
);
onVoted(entry);
} catch {
announce('the vote did not go through; check your connection');
} finally {
btn.classList.remove('is-busy');
}
});
return btn;
}