Skip to content

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.

8.0 KB
Raw Blame
/**
 * 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;
}