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.

feat(spotlight): launch Agent Spotlight, a community showcase ranked by votes with entries that always read the live agent

nirholas71e73c92f4be
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index 27c741955..b213a8a3e 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -1228,6 +1228,16 @@ export const limits = {
getLimiter('bounty:create', { limit: 15, window: '1 h' }).limit(userId),
bountySubmit: (userId) =>
getLimiter('bounty:submit', { limit: 40, window: '1 h' }).limit(userId),
+ // Agent Spotlight (api/showcase/[action].js). Writing a showcase entry is a
+ // considered act (a builder does it once per agent and edits it a few times),
+ // so the create bucket is deliberately tight. Voting is a browse-time
+ // gesture down a long page, so it gets a much wider one; both are keyed on
+ // the user id, because the abuse this guards against is one account
+ // astroturfing the ranking, not one office sharing an IP.
+ showcaseWrite: (userId) =>
+ getLimiter('showcase:write', { limit: 20, window: '1 h' }).limit(userId),
+ showcaseVote: (userId) =>
+ getLimiter('showcase:vote', { limit: 120, window: '10 m' }).limit(userId),
// Direct messages between friends — its own bucket so DM spam can't starve
// world-chat posting and vice versa. Mirrors world chat's order of magnitude.
dmSend: (userId) => getLimiter('dm:send', { limit: 30, window: '1 m' }).limit(userId),
diff --git a/api/_lib/showcase-store.js b/api/_lib/showcase-store.js
new file mode 100644
index 000000000..0fe7c0246
--- /dev/null
+++ b/api/_lib/showcase-store.js
@@ -0,0 +1,453 @@
+// Agent Spotlight store: the community showcase's persistence + ranking.
+//
+// The invariant this module exists to hold: a showcase entry stores the PITCH
+// and nothing else. Every fact about the agent itself (name, description,
+// skills, avatar, on-chain identity, builder) is read live off
+// agent_identities/avatars/users on each query, so an entry can never show a
+// stale name or a deleted avatar. See the migration
+// 20260901160000_agent_showcase.sql for the same reasoning at the schema level.
+
+import { sql } from './db.js';
+import { env } from './env.js';
+import { publicUrlOrNull, thumbnailUrl } from './r2.js';
+
+export const CATEGORIES = [
+ { slug: 'trading', label: 'Trading & markets' },
+ { slug: 'research', label: 'Research & intel' },
+ { slug: 'creative', label: 'Creative' },
+ { slug: 'productivity', label: 'Productivity' },
+ { slug: 'developer', label: 'Developer tools' },
+ { slug: 'social', label: 'Social' },
+ { slug: 'gaming', label: 'Gaming & worlds' },
+ { slug: 'commerce', label: 'Commerce & payments' },
+ { slug: 'education', label: 'Education' },
+ { slug: 'other', label: 'Everything else' },
+];
+
+const CATEGORY_SLUGS = new Set(CATEGORIES.map((c) => c.slug));
+
+export const SORTS = new Set(['trending', 'new', 'top']);
+
+export function isCategory(slug) {
+ return CATEGORY_SLUGS.has(String(slug || '').toLowerCase());
+}
+
+// The showcase needs a database. Every read path checks this first so a
+// deployment without one answers 503 with a reason instead of throwing.
+export function showcaseConfigured() {
+ return Boolean(env.DATABASE_URL);
+}
+
+/* ── ranking ──────────────────────────────────────────────────────────────── */
+
+// Hacker-News-shaped decay: score = (votes + 1) / (age_hours + 2)^1.5.
+//
+// The +1 is what makes this a showcase rather than a popularity contest: a
+// just-published entry with no votes yet still outranks a week-old entry with
+// two, so the newest work is seen at all. The exponent is the knob for how fast
+// yesterday's entries fall off; 1.5 puts a 24-hour-old entry at roughly a fifth
+// of the weight of a fresh one, which keeps a full first page turning over
+// daily at the volume this surface sees.
+export const GRAVITY = 1.5;
+
+export function trendingScore({ voteCount = 0, createdAt, now = Date.now() } = {}) {
+ const ms = now - new Date(createdAt).getTime();
+ const ageHours = Number.isFinite(ms) ? Math.max(0, ms) / 3_600_000 : 0;
+ return (Number(voteCount) + 1) / Math.pow(ageHours + 2, GRAVITY);
+}
+
+/* ── shaping ──────────────────────────────────────────────────────────────── */
+
+// An avatar is renderable in a public page only when the avatar row itself is
+// public or unlisted. A private avatar yields no thumbnail and no GLB, and the
+// card falls back to its generated monogram rather than a broken image.
+function avatarUrls(row) {
+ const visible = row.avatar_visibility === 'public' || row.avatar_visibility === 'unlisted';
+ if (!visible) return { thumbnail: null, glb: null };
+ return {
+ thumbnail: row.avatar_thumbnail_key ? thumbnailUrl(row.avatar_thumbnail_key) : null,
+ glb: row.avatar_storage_key ? publicUrlOrNull(row.avatar_storage_key) : null,
+ };
+}
+
+function builderOf(row) {
+ const name = row.builder_display_name || row.builder_username || null;
+ if (!name) return null;
+ return {
+ name,
+ username: row.builder_username || null,
+ profile_url: row.builder_username ? `/u/${row.builder_username}` : null,
+ };
+}
+
+export function mapEntry(row, { now = Date.now() } = {}) {
+ const meta = row.agent_meta || {};
+ const onchain = meta.onchain || null;
+ const { thumbnail, glb } = avatarUrls(row);
+ const voteCount = Number(row.vote_count) || 0;
+
+ return {
+ id: row.id,
+ title: row.title,
+ tagline: row.tagline,
+ story: row.story || null,
+ demo_url: row.demo_url || null,
+ category: row.category,
+ tags: row.tags || [],
+ source: row.source,
+ featured: Boolean(row.featured_at),
+ vote_count: voteCount,
+ voted_by_me: Boolean(row.voted_by_me),
+ trending_score: Number(trendingScore({ voteCount, createdAt: row.created_at, now }).toFixed(6)),
+ view_count: Number(row.view_count) || 0,
+ created_at: row.created_at,
+ agent: {
+ id: row.agent_id,
+ name: row.agent_name,
+ description: row.agent_description || null,
+ skills: row.agent_skills || [],
+ url: `/agents/${row.agent_id}`,
+ profile_url: `/agents/${row.agent_id}/profile`,
+ thumbnail,
+ glb_url: glb,
+ chat_count: Number(row.chat_count) || 0,
+ action_count: Number(row.action_count) || 0,
+ is_registered: Boolean(
+ onchain || meta.sol_mint_address || row.erc8004_agent_id || meta.erc8004_agent_id,
+ ),
+ onchain: onchain ? { network: onchain.network || null, asset: onchain.sol_asset || null } : null,
+ created_at: row.agent_created_at,
+ },
+ builder: builderOf(row),
+ editable_by_me: Boolean(row.editable_by_me),
+ };
+}
+
+/* ── reads ────────────────────────────────────────────────────────────────── */
+
+// One SELECT list, used by every read, so `list` and `get` can never disagree
+// about which fields a card carries. Interpolated as a fragment via sql`` is not
+// available here (the driver has no fragment type), so the shape lives in the
+// two queries below and this comment is the contract they both honour.
+
+export async function listEntries({
+ sort = 'trending',
+ category = null,
+ tag = null,
+ q = null,
+ limit = 24,
+ offset = 0,
+ viewerId = null,
+ featuredOnly = false,
+} = {}) {
+ const rows = await sql`
+ select
+ s.id, s.title, s.tagline, s.story, s.demo_url, s.category, s.tags,
+ s.source, s.featured_at, s.view_count, s.created_at, s.submitted_by,
+ i.id as agent_id,
+ i.name as agent_name,
+ i.description as agent_description,
+ i.skills as agent_skills,
+ i.meta as agent_meta,
+ i.erc8004_agent_id,
+ i.created_at as agent_created_at,
+ a.thumbnail_key as avatar_thumbnail_key,
+ a.storage_key as avatar_storage_key,
+ a.visibility as avatar_visibility,
+ u.display_name as builder_display_name,
+ u.username as builder_username,
+ coalesce(v.n, 0) as vote_count,
+ coalesce(ch.n, 0) as chat_count,
+ coalesce(ac.n, 0) as action_count,
+ ${viewerId ? sql`(mv.user_id is not null)` : sql`false`} as voted_by_me,
+ ${viewerId ? sql`(s.submitted_by = ${viewerId} or i.user_id = ${viewerId})` : sql`false`} as editable_by_me
+ from agent_showcase s
+ join agent_identities i on i.id = s.agent_id and i.deleted_at is null and i.is_public = true
+ left join avatars a on a.id = i.avatar_id and a.deleted_at is null
+ left join users u on u.id = i.user_id and u.deleted_at is null
+ left join lateral (
+ select count(*)::int n from agent_showcase_votes sv where sv.entry_id = s.id
+ ) v on true
+ left join lateral (
+ select count(*)::int n from usage_events ue where ue.agent_id = i.id and ue.kind = 'llm'
+ ) ch on true
+ left join lateral (
+ select count(*)::int n from agent_actions aa where aa.agent_id = i.id
+ ) ac on true
+ ${
+ viewerId
+ ? sql`left join agent_showcase_votes mv on mv.entry_id = s.id and mv.user_id = ${viewerId}`
+ : sql``
+ }
+ where s.deleted_at is null
+ and s.status = 'published'
+ and (${!featuredOnly} or s.featured_at is not null)
+ and (${!category} or s.category = ${category})
+ and (${!tag} or s.tags @> array[${tag ?? ''}]::text[])
+ and (${!q} or (
+ to_tsvector('english',
+ coalesce(s.title,'') || ' ' || coalesce(s.tagline,'') || ' ' ||
+ coalesce(s.story,'') || ' ' || coalesce(i.name,'') || ' ' ||
+ coalesce(i.description,'')
+ ) @@ plainto_tsquery('english', ${q ?? ''})
+ or s.title ilike ${'%' + (q ?? '') + '%'}
+ or i.name ilike ${'%' + (q ?? '') + '%'}
+ ))
+ order by
+ case when ${sort}::text = 'top' then coalesce(v.n, 0) end desc nulls last,
+ case when ${sort}::text = 'trending'
+ then (coalesce(v.n, 0) + 1)::numeric
+ / power(extract(epoch from (now() - s.created_at))::numeric / 3600.0 + 2, ${GRAVITY}::numeric)
+ end desc nulls last,
+ s.created_at desc
+ limit ${limit} offset ${offset}
+ `;
+ const now = Date.now();
+ return rows.map((r) => mapEntry(r, { now }));
+}
+
+export async function countEntries({ category = null, tag = null, q = null } = {}) {
+ const [row] = await sql`
+ select count(*)::int as n
+ from agent_showcase s
+ join agent_identities i on i.id = s.agent_id and i.deleted_at is null and i.is_public = true
+ where s.deleted_at is null
+ and s.status = 'published'
+ and (${!category} or s.category = ${category})
+ and (${!tag} or s.tags @> array[${tag ?? ''}]::text[])
+ and (${!q} or (
+ to_tsvector('english',
+ coalesce(s.title,'') || ' ' || coalesce(s.tagline,'') || ' ' ||
+ coalesce(s.story,'') || ' ' || coalesce(i.name,'') || ' ' ||
+ coalesce(i.description,'')
+ ) @@ plainto_tsquery('english', ${q ?? ''})
+ or s.title ilike ${'%' + (q ?? '') + '%'}
+ or i.name ilike ${'%' + (q ?? '') + '%'}
+ ))
+ `;
+ return row?.n ?? 0;
+}
+
+export async function getEntry(id, { viewerId = null } = {}) {
+ const rows = await sql`
+ select
+ s.id, s.title, s.tagline, s.story, s.demo_url, s.category, s.tags,
+ s.source, s.featured_at, s.view_count, s.created_at, s.submitted_by,
+ i.id as agent_id,
+ i.name as agent_name,
+ i.description as agent_description,
+ i.skills as agent_skills,
+ i.meta as agent_meta,
+ i.erc8004_agent_id,
+ i.created_at as agent_created_at,
+ a.thumbnail_key as avatar_thumbnail_key,
+ a.storage_key as avatar_storage_key,
+ a.visibility as avatar_visibility,
+ u.display_name as builder_display_name,
+ u.username as builder_username,
+ coalesce(v.n, 0) as vote_count,
+ coalesce(ch.n, 0) as chat_count,
+ coalesce(ac.n, 0) as action_count,
+ ${viewerId ? sql`(mv.user_id is not null)` : sql`false`} as voted_by_me,
+ ${viewerId ? sql`(s.submitted_by = ${viewerId} or i.user_id = ${viewerId})` : sql`false`} as editable_by_me
+ from agent_showcase s
+ join agent_identities i on i.id = s.agent_id and i.deleted_at is null and i.is_public = true
+ left join avatars a on a.id = i.avatar_id and a.deleted_at is null
+ left join users u on u.id = i.user_id and u.deleted_at is null
+ left join lateral (
+ select count(*)::int n from agent_showcase_votes sv where sv.entry_id = s.id
+ ) v on true
+ left join lateral (
+ select count(*)::int n from usage_events ue where ue.agent_id = i.id and ue.kind = 'llm'
+ ) ch on true
+ left join lateral (
+ select count(*)::int n from agent_actions aa where aa.agent_id = i.id
+ ) ac on true
+ ${
+ viewerId
+ ? sql`left join agent_showcase_votes mv on mv.entry_id = s.id and mv.user_id = ${viewerId}`
+ : sql``
+ }
+ where s.id = ${id} and s.deleted_at is null and s.status = 'published'
+ limit 1
+ `;
+ return rows[0] ? mapEntry(rows[0]) : null;
+}
+
+// Per-category counts for the filter rail. A category with nothing in it is
+// still returned (at zero) so the rail's shape does not jump around as entries
+// land, and so an empty category can render its own "be the first" state.
+export async function categoryCounts() {
+ const rows = await sql`
+ select s.category, count(*)::int as n
+ from agent_showcase s
+ join agent_identities i on i.id = s.agent_id and i.deleted_at is null and i.is_public = true
+ where s.deleted_at is null and s.status = 'published'
+ group by s.category
+ `;
+ const counts = new Map(rows.map((r) => [r.category, r.n]));
+ return CATEGORIES.map((c) => ({ ...c, count: counts.get(c.slug) || 0 }));
+}
+
+// Headline numbers for the hero. Three separate aggregates in one round trip:
+// how much work is on the wall, how many people voted it up, and how many
+// distinct builders are represented; the last one is the number that says
+// "community" rather than "one person posted forty agents".
+export async function showcaseTotals() {
+ const [row] = await sql`
+ select
+ count(*)::int as entries,
+ count(distinct i.user_id)::int as builders,
+ coalesce(sum(v.n), 0)::int as votes
+ from agent_showcase s
+ join agent_identities i on i.id = s.agent_id and i.deleted_at is null and i.is_public = true
+ left join lateral (
+ select count(*)::int n from agent_showcase_votes sv where sv.entry_id = s.id
+ ) v on true
+ where s.deleted_at is null and s.status = 'published'
+ `;
+ return {
+ entries: row?.entries ?? 0,
+ builders: row?.builders ?? 0,
+ votes: row?.votes ?? 0,
+ };
+}
+
+// The agents this user could submit: their own, public, not already showcased.
+export async function eligibleAgents(userId) {
+ return await sql`
+ select i.id, i.name, i.description, i.skills,
+ a.thumbnail_key, a.visibility
+ from agent_identities i
+ left join avatars a on a.id = i.avatar_id and a.deleted_at is null
+ where i.user_id = ${userId}
+ and i.deleted_at is null
+ and i.is_public = true
+ and not exists (
+ select 1 from agent_showcase s
+ where s.agent_id = i.id and s.deleted_at is null
+ )
+ order by i.created_at desc
+ limit 100
+ `.then((rows) =>
+ rows.map((r) => ({
+ id: r.id,
+ name: r.name,
+ description: r.description || null,
+ skills: r.skills || [],
+ thumbnail:
+ r.thumbnail_key && (r.visibility === 'public' || r.visibility === 'unlisted')
+ ? thumbnailUrl(r.thumbnail_key)
+ : null,
+ })),
+ );
+}
+
+/* ── writes ───────────────────────────────────────────────────────────────── */
+
+// Insert, or update the caller's existing entry for that agent. Re-submitting is
+// an edit rather than a duplicate: the unique index makes that the only correct
+// outcome, and a builder polishing their pitch should not have to find a
+// separate edit screen to do it.
+export async function upsertEntry({
+ agentId,
+ userId,
+ title,
+ tagline,
+ story = null,
+ demoUrl = null,
+ category,
+ tags = [],
+}) {
+ const [row] = await sql`
+ insert into agent_showcase
+ (agent_id, submitted_by, source, title, tagline, story, demo_url, category, tags)
+ values
+ (${agentId}, ${userId}, 'community', ${title}, ${tagline}, ${story}, ${demoUrl},
+ ${category}, ${tags}::text[])
+ on conflict (agent_id) where deleted_at is null
+ do update set
+ title = excluded.title,
+ tagline = excluded.tagline,
+ story = excluded.story,
+ demo_url = excluded.demo_url,
+ category = excluded.category,
+ tags = excluded.tags,
+ -- A curated write-up that the builder later claims becomes theirs.
+ source = 'community',
+ submitted_by = excluded.submitted_by,
+ updated_at = now()
+ returning id
+ `;
+ return row?.id || null;
+}
+
+export async function ownsAgent(agentId, userId) {
+ const [row] = await sql`
+ select 1 from agent_identities
+ where id = ${agentId} and user_id = ${userId} and deleted_at is null
+ limit 1
+ `;
+ return Boolean(row);
+}
+
+export async function agentIsPublic(agentId) {
+ const [row] = await sql`
+ select is_public from agent_identities where id = ${agentId} and deleted_at is null limit 1
+ `;
+ return row ? Boolean(row.is_public) : null;
+}
+
+// Toggle. Returns the entry's post-toggle state so the button can settle on a
+// server-confirmed count instead of an optimistic guess that drifts.
+export async function toggleVote(entryId, userId) {
+ const removed = await sql`
+ delete from agent_showcase_votes
+ where entry_id = ${entryId} and user_id = ${userId}
+ returning entry_id
+ `;
+ if (!removed.length) {
+ await sql`
+ insert into agent_showcase_votes (entry_id, user_id)
+ values (${entryId}, ${userId})
+ on conflict do nothing
+ `;
+ }
+ const [row] = await sql`
+ select count(*)::int as n from agent_showcase_votes where entry_id = ${entryId}
+ `;
+ return { voted: removed.length === 0, vote_count: row?.n ?? 0 };
+}
+
+export async function entryExists(entryId) {
+ const [row] = await sql`
+ select 1 from agent_showcase
+ where id = ${entryId} and deleted_at is null and status = 'published'
+ limit 1
+ `;
+ return Boolean(row);
+}
+
+export async function softDeleteEntry(entryId, userId) {
+ const rows = await sql`
+ update agent_showcase s
+ set deleted_at = now()
+ from agent_identities i
+ where s.id = ${entryId}
+ and s.deleted_at is null
+ and i.id = s.agent_id
+ and (s.submitted_by = ${userId} or i.user_id = ${userId})
+ returning s.id
+ `;
+ return rows.length > 0;
+}
+
+// Best-effort view counter. A failure here must never break the page it counts,
+// so the caller fires it without awaiting the result.
+export async function bumpViews(entryId) {
+ try {
+ await sql`update agent_showcase set view_count = view_count + 1 where id = ${entryId}`;
+ } catch {
+ /* a lost view is not worth a 500 on a read */
+ }
+}
diff --git a/api/showcase/[action].js b/api/showcase/[action].js
new file mode 100644
index 000000000..cdabfed95
--- /dev/null
+++ b/api/showcase/[action].js
@@ -0,0 +1,336 @@
+// api/showcase/[action]: Agent Spotlight, the community showcase.
+//
+// GET /api/showcase/list?sort=trending|new|top&category=&tag=&q=&limit=&offset=&featured=1
+// GET /api/showcase/get?id=<uuid>
+// GET /api/showcase/categories (per-category counts + headline totals)
+// GET /api/showcase/eligible (auth: the caller's showcasable agents)
+// POST /api/showcase/submit { agentId, title, tagline, story?, demoUrl?, category, tags[] }
+// POST /api/showcase/vote { id } (toggle)
+// POST /api/showcase/remove { id } (submitter or agent owner)
+//
+// Reads are public and CDN-cached; writes need a session plus CSRF. The ranking
+// and every query live in api/_lib/showcase-store.js; this file is the HTTP
+// boundary and nothing else.
+
+import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';
+import { requireCsrf } from '../_lib/csrf.js';
+import { getSessionUser } from '../_lib/auth.js';
+import { limits, clientIp } from '../_lib/rate-limit.js';
+import { isUuid } from '../_lib/validate.js';
+import {
+ CATEGORIES,
+ SORTS,
+ agentIsPublic,
+ bumpViews,
+ categoryCounts,
+ countEntries,
+ eligibleAgents,
+ entryExists,
+ getEntry,
+ isCategory,
+ listEntries,
+ ownsAgent,
+ showcaseConfigured,
+ showcaseTotals,
+ softDeleteEntry,
+ toggleVote,
+ upsertEntry,
+} from '../_lib/showcase-store.js';
+
+const MAX_LIMIT = 48;
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
+ if (!method(req, res, ['GET', 'POST'])) return;
+
+ if (!showcaseConfigured()) {
+ return error(res, 503, 'not_configured', 'the showcase needs a database; none is configured here');
+ }
+
+ switch (actionOf(req)) {
+ case 'list':
+ return await handleList(req, res);
+ case 'get':
+ return await handleGet(req, res);
+ case 'categories':
+ return await handleCategories(req, res);
+ case 'eligible':
+ return await handleEligible(req, res);
+ case 'submit':
+ return await handleSubmit(req, res);
+ case 'vote':
+ return await handleVote(req, res);
+ case 'remove':
+ return await handleRemove(req, res);
+ default:
+ return error(res, 404, 'not_found', `unknown showcase action "${actionOf(req)}"`);
+ }
+});
+
+function actionOf(req) {
+ const fromQuery = req.query?.action;
+ if (fromQuery && fromQuery !== '[action]') return String(fromQuery).toLowerCase();
+ return (new URL(req.url, 'http://x').pathname.split('/').pop() || '').toLowerCase();
+}
+
+function queryOf(req) {
+ return new URL(req.url, 'http://x').searchParams;
+}
+
+// A viewer is optional on every read: signed in, their own votes come back
+// marked; signed out, the page still renders in full. A broken session cookie
+// must therefore never turn a public read into a 401.
+async function viewer(req) {
+ try {
+ const user = await getSessionUser(req);
+ return user?.id || null;
+ } catch {
+ return null;
+ }
+}
+
+/* ── reads ────────────────────────────────────────────────────────────────── */
+
+async function handleList(req, res) {
+ if (!method(req, res, ['GET'])) return;
+ const rl = await limits.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const p = queryOf(req);
+ const sort = SORTS.has(p.get('sort')) ? p.get('sort') : 'trending';
+ const rawCategory = (p.get('category') || '').toLowerCase();
+ const category = isCategory(rawCategory) ? rawCategory : null;
+ const tag = (p.get('tag') || '').trim().toLowerCase().slice(0, 40) || null;
+ const q = (p.get('q') || '').trim().slice(0, 100) || null;
+ const limit = Math.min(MAX_LIMIT, Math.max(1, Number(p.get('limit') || 24) | 0));
+ const offset = Math.max(0, Math.min(5000, Number(p.get('offset') || 0) | 0));
+ const featuredOnly = p.get('featured') === '1';
+
+ const viewerId = await viewer(req);
+ const [entries, total] = await Promise.all([
+ listEntries({ sort, category, tag, q, limit, offset, viewerId, featuredOnly }),
+ countEntries({ category, tag, q }),
+ ]);
+
+ // A signed-in read is personalised (voted_by_me), so it must never land in a
+ // shared cache. Anonymous reads are identical for everyone and cache freely.
+ const cache = viewerId
+ ? { 'Cache-Control': 'private, no-store' }
+ : { 'Cache-Control': 'public, max-age=30, stale-while-revalidate=120' };
+
+ return json(
+ res,
+ 200,
+ {
+ entries,
+ count: entries.length,
+ total,
+ has_more: offset + entries.length < total,
+ next_offset: offset + entries.length < total ? offset + entries.length : null,
+ sort,
+ category,
+ generated_at: new Date().toISOString(),
+ },
+ cache,
+ );
+}
+
+async function handleGet(req, res) {
+ if (!method(req, res, ['GET'])) return;
+ const rl = await limits.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const id = queryOf(req).get('id') || '';
+ if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
+
+ const viewerId = await viewer(req);
+ const entry = await getEntry(id, { viewerId });
+ if (!entry) return error(res, 404, 'not_found', 'no such showcase entry');
+
+ void bumpViews(id);
+ return json(res, 200, { entry }, { 'Cache-Control': 'private, no-store' });
+}
+
+async function handleCategories(req, res) {
+ if (!method(req, res, ['GET'])) return;
+ const rl = await limits.publicIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const [categories, totals] = await Promise.all([categoryCounts(), showcaseTotals()]);
+ return json(
+ res,
+ 200,
+ { categories, totals },
+ { 'Cache-Control': 'public, max-age=60, stale-while-revalidate=300' },
+ );
+}
+
+async function handleEligible(req, res) {
+ if (!method(req, res, ['GET'])) return;
+ const user = await sessionOr401(req, res, 'sign in to see which of your agents you can showcase');
+ if (!user) return;
+
+ const rl = await limits.authedReadIp(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const agents = await eligibleAgents(user.id);
+ return json(res, 200, { agents, categories: CATEGORIES }, { 'Cache-Control': 'private, no-store' });
+}
+
+/* ── writes ───────────────────────────────────────────────────────────────── */
+
+async function handleSubmit(req, res) {
+ if (!method(req, res, ['POST'])) return;
+ const user = await sessionOr401(req, res, 'sign in to submit an agent to the showcase');
+ if (!user) return;
+ if (!(await requireCsrf(req, res, user.id))) return;
+
+ const rl = await limits.showcaseWrite(user.id);
+ if (!rl.success) return rateLimited(res, rl, 'too many showcase submissions; slow down');
+
+ const body = await readJson(req, 32_000);
+ const agentId = String(body?.agentId || '').trim();
+ if (!isUuid(agentId)) return error(res, 400, 'bad_request', 'agentId must be a uuid');
+
+ if (!(await ownsAgent(agentId, user.id))) {
+ return error(res, 403, 'forbidden', 'you can only showcase an agent you own');
+ }
+ if ((await agentIsPublic(agentId)) !== true) {
+ return error(
+ res,
+ 409,
+ 'agent_not_public',
+ 'make the agent public before showcasing it: the showcase only lists agents visitors can open',
+ );
+ }
+
+ const title = trimmed(body?.title);
+ const tagline = trimmed(body?.tagline);
+ const story = trimmed(body?.story) || null;
+ const category = String(body?.category || '').toLowerCase();
+ const demoUrl = normalizeDemoUrl(body?.demoUrl);
+ if (demoUrl === false) {
+ return error(res, 400, 'bad_request', 'demoUrl must be an http(s) link');
+ }
+
+ if (!title || title.length < 3 || title.length > 90) {
+ return error(res, 400, 'bad_request', 'title must be 3 to 90 characters');
+ }
+ if (!tagline || tagline.length < 10 || tagline.length > 160) {
+ return error(res, 400, 'bad_request', 'tagline must be 10 to 160 characters');
+ }
+ if (story && story.length > 4000) {
+ return error(res, 400, 'bad_request', 'story must be 4000 characters or fewer');
+ }
+ if (!isCategory(category)) {
+ return error(res, 400, 'bad_request', `category must be one of: ${CATEGORIES.map((c) => c.slug).join(', ')}`);
+ }
+
+ const tags = normalizeTags(body?.tags);
+ if (tags === false) return error(res, 400, 'bad_request', 'tags must be up to 6 short labels');
+
+ const id = await upsertEntry({
+ agentId,
+ userId: user.id,
+ title,
+ tagline,
+ story,
+ demoUrl: demoUrl || null,
+ category,
+ tags,
+ });
+ if (!id) return error(res, 500, 'write_failed', 'the entry could not be saved');
+
+ const entry = await getEntry(id, { viewerId: user.id });
+ return json(res, 200, { entry }, { 'Cache-Control': 'private, no-store' });
+}
+
+async function handleVote(req, res) {
+ if (!method(req, res, ['POST'])) return;
+ const user = await sessionOr401(req, res, 'sign in to upvote an agent');
+ if (!user) return;
+ if (!(await requireCsrf(req, res, user.id))) return;
+
+ const rl = await limits.showcaseVote(user.id);
+ if (!rl.success) return rateLimited(res, rl, 'too many votes; slow down');
+
+ const body = await readJson(req, 2_000);
+ const id = String(body?.id || '').trim();
+ if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
+ if (!(await entryExists(id))) return error(res, 404, 'not_found', 'no such showcase entry');
+
+ const result = await toggleVote(id, user.id);
+ return json(res, 200, result, { 'Cache-Control': 'private, no-store' });
+}
+
+async function handleRemove(req, res) {
+ if (!method(req, res, ['POST'])) return;
+ const user = await sessionOr401(req, res, 'sign in to remove a showcase entry');
+ if (!user) return;
+ if (!(await requireCsrf(req, res, user.id))) return;
+
+ const body = await readJson(req, 2_000);
+ const id = String(body?.id || '').trim();
+ if (!isUuid(id)) return error(res, 400, 'bad_request', 'id must be a uuid');
+
+ const removed = await softDeleteEntry(id, user.id);
+ if (!removed) {
+ return error(res, 403, 'forbidden', 'only the submitter or the agent owner can remove an entry');
+ }
+ return json(res, 200, { removed: true }, { 'Cache-Control': 'private, no-store' });
+}
+
+/* ── input helpers ────────────────────────────────────────────────────────── */
+
+async function sessionOr401(req, res, message) {
+ let user = null;
+ try {
+ user = await getSessionUser(req);
+ } catch {
+ user = null;
+ }
+ if (!user) {
+ error(res, 401, 'unauthorized', message);
+ return null;
+ }
+ return user;
+}
+
+function trimmed(v) {
+ return typeof v === 'string' ? v.trim() : '';
+}
+
+// Returns a normalized URL string, '' for "not supplied", or false for invalid.
+// Only http(s) is accepted: the value is rendered as a link on a public page, so
+// javascript:, data: and friends have to be rejected at the boundary, not
+// escaped at the sink.
+function normalizeDemoUrl(raw) {
+ const value = trimmed(raw);
+ if (!value) return '';
+ if (value.length > 500) return false;
+ let url;
+ try {
+ url = new URL(value);
+ } catch {
+ return false;
+ }
+ if (url.protocol !== 'http:' && url.protocol !== 'https:') return false;
+ return url.toString();
+}
+
+// Up to 6 lowercase, hyphenatable labels. Returns false on anything that cannot
+// be coerced into that shape rather than silently dropping the caller's input.
+function normalizeTags(raw) {
+ if (raw == null) return [];
+ if (!Array.isArray(raw)) return false;
+ if (raw.length > 6) return false;
+ const out = [];
+ for (const t of raw) {
+ if (typeof t !== 'string') return false;
+ const tag = t.trim().toLowerCase().replace(/\s+/g, '-');
+ if (!tag) continue;
+ if (tag.length > 24 || !/^[a-z0-9][a-z0-9-]*$/.test(tag)) return false;
+ if (!out.includes(tag)) out.push(tag);
+ }
+ return out;
+}
diff --git a/pages/spotlight.html b/pages/spotlight.html
new file mode 100644
index 000000000..2504762a6
--- /dev/null
+++ b/pages/spotlight.html
@@ -0,0 +1,200 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <script>/* three.ws theme boot - no-flash; runtime in /theme-switcher.js */(function(){try{var m=localStorage.getItem('twx_theme');var l=m==='auto'?(window.matchMedia&&window.matchMedia('(prefers-color-scheme: light)').matches):m==='light';document.documentElement.setAttribute('data-theme',l?'light':'dark');}catch(e){document.documentElement.setAttribute('data-theme','dark');}})();</script>
+ <meta charset="utf-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Agent Spotlight · three.ws</title>
+ <meta
+ name="description"
+ content="The three.ws community showcase: real agents people built, written up by the people who built them, ranked by community upvotes. Browse by category, open any agent in 3D, and submit your own."
+ />
+ <meta name="theme-color" content="#0a0a0a" />
+ <link rel="canonical" href="https://three.ws/spotlight" />
+ <link rel="icon" href="/favicon.ico" sizes="any" />
+ <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+ <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+ <link rel="manifest" href="/manifest.webmanifest" />
+ <link rel="stylesheet" href="/fonts/fonts.css" />
+ <link rel="stylesheet" href="/nav.css" />
+ <link rel="stylesheet" href="/src/spotlight.css" />
+ <link rel="stylesheet" href="/footer.css" />
+ <script defer src="/footer-newsletter.js"></script>
+ </head>
+ <body>
+ <header><div id="nav-container"></div></header>
+ <script src="/nav.js"></script>
+
+ <main class="sp-shell">
+ <section class="sp-hero">
+ <p class="sp-kicker"><span class="sp-dot" aria-hidden="true"></span> Community showcase</p>
+ <h1 class="sp-title">Agent <em>Spotlight</em></h1>
+ <p class="sp-sub">
+ The agents index lists everything anyone ever registered. This is the other thing:
+ agents people actually built something with, written up by the builder, ranked by
+ what the community votes up. Open any one of them, talk to it, fork it, or put
+ your own in front of everybody.
+ </p>
+ <div class="sp-ctas">
+ <button
+ type="button"
+ class="sp-btn sp-btn-primary"
+ id="sp-submit-toggle"
+ aria-expanded="false"
+ aria-controls="sp-submit-panel"
+ >
+ Showcase your agent
+ </button>
+ <a class="sp-btn" href="/agents">Browse every agent</a>
+ <a class="sp-btn" href="/docs/spotlight">How the ranking works</a>
+ </div>
+ <dl class="sp-stats" id="sp-stats" aria-live="polite"></dl>
+ </section>
+
+ <!-- Submission. Server-validated on POST /api/showcase/submit; the client
+ mirrors the same bounds so a builder learns about a too-long tagline
+ while typing it rather than after a round trip. -->
+ <form class="sp-panel" id="sp-submit-panel" hidden>
+ <div class="sp-panel-head">
+ <h2 class="sp-h2">Put an agent in the spotlight</h2>
+ <p class="sp-panel-note">
+ Pick one of your public agents and say what it does. Everything else on the card
+ (its name, avatar, skills, on-chain identity, live chat count) is read from the
+ agent itself, so your entry never goes stale.
+ </p>
+ </div>
+
+ <div id="sp-submit-auth" class="sp-inline-state" hidden></div>
+
+ <div class="sp-field">
+ <label for="sp-agent">Agent</label>
+ <select class="sp-input" id="sp-agent" name="agentId" required></select>
+ <span class="sp-hint" id="sp-agent-hint"></span>
+ </div>
+
+ <div class="sp-row">
+ <div class="sp-field">
+ <label for="sp-title">Headline</label>
+ <input
+ class="sp-input"
+ id="sp-title"
+ name="title"
+ required
+ minlength="3"
+ maxlength="90"
+ placeholder="The rug detector that reads the chain before you ape"
+ autocomplete="off"
+ />
+ <span class="sp-hint"><span data-count-for="sp-title">0</span>/90</span>
+ </div>
+ <div class="sp-field">
+ <label for="sp-category">Category</label>
+ <select class="sp-input" id="sp-category" name="category" required></select>
+ </div>
+ </div>
+
+ <div class="sp-field">
+ <label for="sp-tagline">One-liner</label>
+ <input
+ class="sp-input"
+ id="sp-tagline"
+ name="tagline"
+ required
+ minlength="10"
+ maxlength="160"
+ placeholder="What it does, in the words you would use out loud."
+ autocomplete="off"
+ />
+ <span class="sp-hint"><span data-count-for="sp-tagline">0</span>/160</span>
+ </div>
+
+ <div class="sp-field">
+ <label for="sp-story">The write-up <span class="sp-hint">(optional)</span></label>
+ <textarea
+ class="sp-textarea"
+ id="sp-story"
+ name="story"
+ maxlength="4000"
+ placeholder="How you built it, what it is for, what surprised you. This is the part people read."
+ ></textarea>
+ <span class="sp-hint"><span data-count-for="sp-story">0</span>/4000</span>
+ </div>
+
+ <div class="sp-row">
+ <div class="sp-field">
+ <label for="sp-demo">Demo link <span class="sp-hint">(optional)</span></label>
+ <input
+ class="sp-input"
+ id="sp-demo"
+ name="demoUrl"
+ type="url"
+ maxlength="500"
+ placeholder="https://your-site.com/where-it-lives"
+ autocomplete="off"
+ />
+ </div>
+ <div class="sp-field">
+ <label for="sp-tags">Tags <span class="sp-hint">(optional, up to 6)</span></label>
+ <input
+ class="sp-input"
+ id="sp-tags"
+ name="tags"
+ maxlength="160"
+ placeholder="solana, on-chain, research"
+ autocomplete="off"
+ />
+ <span class="sp-hint">Comma separated. Lowercase letters, digits and hyphens.</span>
+ </div>
+ </div>
+
+ <div class="sp-ctas">
+ <button type="submit" class="sp-btn sp-btn-primary" id="sp-submit">Publish to the showcase</button>
+ <button type="button" class="sp-btn" id="sp-cancel">Cancel</button>
+ </div>
+ <p class="sp-form-note" id="sp-form-note" role="status" aria-live="polite"></p>
+ </form>
+
+ <!-- Editor's picks. Rendered only when at least one entry is featured, so
+ the page never shows an empty rail with a heading over it. -->
+ <section class="sp-featured" id="sp-featured" hidden aria-labelledby="sp-featured-head">
+ <h2 class="sp-h2" id="sp-featured-head">Featured</h2>
+ <div class="sp-featured-body" id="sp-featured-body"></div>
+ </section>
+
+ <section class="sp-controls" aria-label="Filter the showcase">
+ <div class="sp-sorts" role="tablist" aria-label="Sort">
+ <button type="button" class="sp-sort is-active" role="tab" aria-selected="true" data-sort="trending">Trending</button>
+ <button type="button" class="sp-sort" role="tab" aria-selected="false" data-sort="new">Newest</button>
+ <button type="button" class="sp-sort" role="tab" aria-selected="false" data-sort="top">Most upvoted</button>
+ </div>
+ <div class="sp-search">
+ <label class="sr-only" for="sp-q">Search the showcase</label>
+ <input
+ class="sp-input"
+ id="sp-q"
+ type="search"
+ placeholder="Search agents, write-ups, builders…"
+ autocomplete="off"
+ />
+ <kbd class="sp-kbd" aria-hidden="true">/</kbd>
+ </div>
+ </section>
+
+ <nav class="sp-cats" id="sp-cats" aria-label="Categories"></nav>
+
+ <section class="sp-grid" id="sp-grid" aria-label="Showcased agents" aria-busy="true"></section>
+ <div id="sp-state"></div>
+ <div class="sp-more-wrap">
+ <button type="button" class="sp-btn" id="sp-more" hidden>Load more</button>
+ </div>
+ </main>
+
+ <div id="sp-live" class="sr-only" role="status" aria-live="polite"></div>
+
+ <script type="module" src="/src/spotlight.js"></script>
+ <script src="/brand.js" defer></script>
+ <div id="footer-container"></div>
+ <script src="/footer.js"></script>
+ <script type="module" src="/i18n.js"></script>
+ </body>
+</html>
diff --git a/src/spotlight.css b/src/spotlight.css
new file mode 100644
index 000000000..65f331878
--- /dev/null
+++ b/src/spotlight.css
@@ -0,0 +1,830 @@
+/* Agent Spotlight: the community showcase (/spotlight).
+ Every value comes from public/tokens.css; nothing is hardcoded that a token
+ already expresses. The one place this sheet reaches for a literal is the
+ monogram gradient, which is derived per-agent in JS from the agent id. */
+
+.sp-shell {
+ max-width: 1180px;
+ margin: 0 auto;
+ padding: var(--space-xl, 32px) var(--space-lg, 24px) var(--space-3xl, 96px);
+}
+
+.sr-only {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ padding: 0;
+ margin: -1px;
+ overflow: hidden;
+ clip: rect(0 0 0 0);
+ white-space: nowrap;
+ border: 0;
+}
+
+/* ── hero ─────────────────────────────────────────────────────────────── */
+
+.sp-hero {
+ padding: var(--space-2xl, 56px) 0 var(--space-lg, 24px);
+ border-bottom: 1px solid var(--stroke, rgba(255, 255, 255, 0.08));
+}
+
+.sp-kicker {
+ display: inline-flex;
+ align-items: center;
+ gap: var(--space-2, 8px);
+ margin: 0 0 var(--space-sm, 12px);
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ letter-spacing: 0.12em;
+ text-transform: uppercase;
+ color: var(--ink-dim, rgba(255, 255, 255, 0.55));
+}
+
+.sp-dot {
+ width: 6px;
+ height: 6px;
+ border-radius: var(--radius-pill, 999px);
+ background: var(--success, #4ade80);
+ box-shadow: 0 0 0 3px color-mix(in srgb, var(--success, #4ade80) 22%, transparent);
+}
+
+.sp-title {
+ margin: 0 0 var(--space-md, 16px);
+ font-family: var(--font-display);
+ font-size: var(--text-2xl, 42px);
+ line-height: var(--leading-tight, 1.15);
+ letter-spacing: -0.02em;
+ font-weight: var(--weight-bold, 700);
+ color: var(--ink-bright, #fff);
+}
+
+.sp-title em {
+ font-style: normal;
+ background: linear-gradient(100deg, var(--ink-bright, #fff), var(--ink-faint, rgba(255, 255, 255, 0.45)));
+ -webkit-background-clip: text;
+ background-clip: text;
+ color: transparent;
+}
+
+.sp-sub {
+ max-width: 66ch;
+ margin: 0 0 var(--space-lg, 24px);
+ font-size: var(--text-base, 16px);
+ line-height: var(--leading-normal, 1.618);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.62));
+}
+
+.sp-ctas {
+ display: flex;
+ flex-wrap: wrap;
+ gap: var(--space-sm, 12px);
+}
+
+.sp-stats {
+ display: flex;
+ flex-wrap: wrap;
+ gap: var(--space-lg, 24px);
+ margin: var(--space-lg, 24px) 0 0;
+}
+
+.sp-stats > div {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+}
+
+.sp-stats dt {
+ order: 2;
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ letter-spacing: 0.1em;
+ text-transform: uppercase;
+ color: var(--ink-faint, rgba(255, 255, 255, 0.45));
+}
+
+.sp-stats dd {
+ order: 1;
+ margin: 0;
+ font-family: var(--font-display);
+ font-size: var(--text-xl, 28px);
+ font-weight: var(--weight-semibold, 600);
+ color: var(--ink-bright, #fff);
+ font-variant-numeric: tabular-nums;
+}
+
+/* ── buttons ──────────────────────────────────────────────────────────── */
+
+.sp-btn {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ gap: var(--space-2, 8px);
+ padding: 10px var(--space-md, 16px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.12));
+ border-radius: var(--radius-md, 10px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.04));
+ color: var(--ink, rgba(255, 255, 255, 0.86));
+ font-family: var(--font-body);
+ font-size: var(--text-ui, 14px);
+ font-weight: var(--weight-medium, 500);
+ text-decoration: none;
+ cursor: pointer;
+ transition:
+ background var(--duration-fast, 140ms) var(--ease-standard),
+ border-color var(--duration-fast, 140ms) var(--ease-standard),
+ transform var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-btn:hover {
+ background: var(--surface-2, rgba(255, 255, 255, 0.08));
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.22));
+}
+
+.sp-btn:active {
+ transform: translateY(1px);
+}
+
+.sp-btn-primary {
+ background: var(--ink-bright, #fff);
+ border-color: var(--ink-bright, #fff);
+ color: var(--bg-0, #0a0a0a);
+}
+
+.sp-btn-primary:hover {
+ background: var(--ink, rgba(255, 255, 255, 0.88));
+ border-color: var(--ink, rgba(255, 255, 255, 0.88));
+}
+
+.sp-btn-sm {
+ padding: 6px var(--space-sm, 12px);
+ font-size: var(--text-md, 13px);
+}
+
+/* ── submission panel ─────────────────────────────────────────────────── */
+
+.sp-panel {
+ margin: var(--space-lg, 24px) 0 0;
+ padding: var(--space-lg, 24px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-lg, 14px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.03));
+ display: grid;
+ gap: var(--space-md, 16px);
+}
+
+.sp-panel-head {
+ display: grid;
+ gap: var(--space-2, 8px);
+}
+
+.sp-h2 {
+ margin: 0;
+ font-family: var(--font-display);
+ font-size: var(--text-lg, 20px);
+ font-weight: var(--weight-semibold, 600);
+ color: var(--ink-bright, #fff);
+}
+
+.sp-panel-note {
+ margin: 0;
+ max-width: 70ch;
+ font-size: var(--text-md, 13px);
+ line-height: var(--leading-normal, 1.6);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.6));
+}
+
+.sp-row {
+ display: grid;
+ gap: var(--space-md, 16px);
+ grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+}
+
+.sp-field {
+ display: grid;
+ gap: 6px;
+ min-width: 0;
+}
+
+.sp-field label {
+ font-size: var(--text-md, 13px);
+ font-weight: var(--weight-medium, 500);
+ color: var(--ink, rgba(255, 255, 255, 0.84));
+}
+
+.sp-input,
+.sp-textarea {
+ width: 100%;
+ padding: 10px var(--space-sm, 12px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.12));
+ border-radius: var(--radius-md, 10px);
+ background: var(--bg-1, rgba(0, 0, 0, 0.25));
+ color: var(--ink-bright, #fff);
+ font-family: var(--font-body);
+ font-size: var(--text-ui, 14px);
+ transition: border-color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-input:hover,
+.sp-textarea:hover {
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.2));
+}
+
+.sp-textarea {
+ min-height: 120px;
+ resize: vertical;
+ line-height: var(--leading-normal, 1.6);
+}
+
+.sp-hint {
+ font-size: var(--text-2xs, 11px);
+ color: var(--ink-faint, rgba(255, 255, 255, 0.45));
+}
+
+.sp-form-note {
+ margin: 0;
+ font-size: var(--text-md, 13px);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.6));
+ min-height: 1.2em;
+}
+
+.sp-form-note[data-tone='error'] {
+ color: var(--danger, #f87171);
+}
+
+.sp-form-note[data-tone='success'] {
+ color: var(--success, #4ade80);
+}
+
+.sp-inline-state {
+ padding: var(--space-sm, 12px) var(--space-md, 16px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-md, 10px);
+ background: var(--surface-2, rgba(255, 255, 255, 0.05));
+ font-size: var(--text-md, 13px);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.68));
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: var(--space-sm, 12px);
+}
+
+/* ── featured ─────────────────────────────────────────────────────────── */
+
+.sp-featured {
+ margin: var(--space-xl, 32px) 0 0;
+ display: grid;
+ gap: var(--space-md, 16px);
+}
+
+.sp-featured-body {
+ display: grid;
+ gap: var(--space-md, 16px);
+ grid-template-columns: minmax(0, 5fr) minmax(0, 7fr);
+ align-items: stretch;
+}
+
+@media (max-width: 860px) {
+ .sp-featured-body {
+ grid-template-columns: minmax(0, 1fr);
+ }
+}
+
+.sp-stage {
+ position: relative;
+ min-height: 320px;
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-lg, 14px);
+ background:
+ radial-gradient(120% 90% at 50% 0%, var(--accent-soft, rgba(255, 255, 255, 0.08)), transparent 70%),
+ var(--surface-1, rgba(255, 255, 255, 0.03));
+ overflow: hidden;
+ display: grid;
+ place-items: center;
+}
+
+.sp-stage agent-3d {
+ width: 100%;
+ height: 100%;
+ min-height: 320px;
+ display: block;
+}
+
+.sp-stage img {
+ width: 100%;
+ height: 100%;
+ min-height: 320px;
+ object-fit: cover;
+}
+
+.sp-stage-badge {
+ position: absolute;
+ top: var(--space-sm, 12px);
+ left: var(--space-sm, 12px);
+ padding: 4px 10px;
+ border-radius: var(--radius-pill, 999px);
+ background: var(--scrim, rgba(0, 0, 0, 0.55));
+ border: 1px solid var(--on-scrim-stroke, rgba(255, 255, 255, 0.16));
+ color: var(--on-scrim-bright, #fff);
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+}
+
+.sp-featured-copy {
+ display: grid;
+ align-content: center;
+ gap: var(--space-sm, 12px);
+ padding: var(--space-lg, 24px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-lg, 14px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.03));
+}
+
+.sp-featured-copy h3 {
+ margin: 0;
+ font-family: var(--font-display);
+ font-size: var(--text-xl, 26px);
+ line-height: var(--leading-tight, 1.2);
+ font-weight: var(--weight-semibold, 600);
+ color: var(--ink-bright, #fff);
+}
+
+.sp-featured-copy p {
+ margin: 0;
+ max-width: 60ch;
+ font-size: var(--text-base, 16px);
+ line-height: var(--leading-normal, 1.6);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.66));
+}
+
+.sp-featured-story {
+ font-size: var(--text-ui, 14px) !important;
+ color: var(--ink-faint, rgba(255, 255, 255, 0.5)) !important;
+ display: -webkit-box;
+ -webkit-line-clamp: 4;
+ -webkit-box-orient: vertical;
+ overflow: hidden;
+}
+
+/* ── controls ─────────────────────────────────────────────────────────── */
+
+.sp-controls {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ justify-content: space-between;
+ gap: var(--space-md, 16px);
+ margin: var(--space-xl, 32px) 0 var(--space-md, 16px);
+}
+
+.sp-sorts {
+ display: inline-flex;
+ padding: 3px;
+ gap: 2px;
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-pill, 999px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.03));
+}
+
+.sp-sort {
+ padding: 7px var(--space-sm, 14px);
+ border: 0;
+ border-radius: var(--radius-pill, 999px);
+ background: transparent;
+ color: var(--ink-dim, rgba(255, 255, 255, 0.6));
+ font-family: var(--font-body);
+ font-size: var(--text-md, 13px);
+ font-weight: var(--weight-medium, 500);
+ cursor: pointer;
+ transition:
+ background var(--duration-fast, 140ms) var(--ease-standard),
+ color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-sort:hover {
+ color: var(--ink-bright, #fff);
+ background: var(--surface-2, rgba(255, 255, 255, 0.06));
+}
+
+.sp-sort.is-active {
+ background: var(--ink-bright, #fff);
+ color: var(--bg-0, #0a0a0a);
+}
+
+.sp-search {
+ position: relative;
+ flex: 1 1 260px;
+ max-width: 380px;
+}
+
+.sp-search .sp-input {
+ padding-right: 34px;
+}
+
+.sp-kbd {
+ position: absolute;
+ right: 10px;
+ top: 50%;
+ transform: translateY(-50%);
+ padding: 1px 6px;
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.14));
+ border-radius: var(--radius-sm, 6px);
+ background: var(--surface-2, rgba(255, 255, 255, 0.06));
+ color: var(--ink-faint, rgba(255, 255, 255, 0.45));
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ pointer-events: none;
+}
+
+.sp-cats {
+ display: flex;
+ flex-wrap: wrap;
+ gap: var(--space-2, 8px);
+ margin: 0 0 var(--space-lg, 24px);
+}
+
+.sp-cat {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+ padding: 5px var(--space-sm, 12px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-pill, 999px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.03));
+ color: var(--ink-dim, rgba(255, 255, 255, 0.62));
+ font-size: var(--text-md, 13px);
+ cursor: pointer;
+ transition:
+ border-color var(--duration-fast, 140ms) var(--ease-standard),
+ color var(--duration-fast, 140ms) var(--ease-standard),
+ background var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-cat:hover {
+ color: var(--ink-bright, #fff);
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.22));
+}
+
+.sp-cat[aria-pressed='true'] {
+ background: var(--accent-soft, rgba(255, 255, 255, 0.1));
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.28));
+ color: var(--ink-bright, #fff);
+}
+
+.sp-cat-count {
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ color: var(--ink-faint, rgba(255, 255, 255, 0.42));
+ font-variant-numeric: tabular-nums;
+}
+
+/* ── grid + cards ─────────────────────────────────────────────────────── */
+
+.sp-grid {
+ display: grid;
+ gap: var(--space-md, 16px);
+ grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
+}
+
+.sp-card {
+ position: relative;
+ display: grid;
+ grid-template-rows: auto 1fr auto;
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.1));
+ border-radius: var(--radius-lg, 14px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.03));
+ overflow: hidden;
+ transition:
+ border-color var(--duration-fast, 140ms) var(--ease-standard),
+ transform var(--duration-fast, 140ms) var(--ease-standard),
+ box-shadow var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-card:hover {
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.24));
+ transform: translateY(-2px);
+ box-shadow: var(--shadow-2, 0 8px 24px rgba(0, 0, 0, 0.35));
+}
+
+.sp-card:focus-within {
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.3));
+}
+
+.sp-card-art {
+ position: relative;
+ aspect-ratio: 16 / 10;
+ background: var(--bg-1, rgba(0, 0, 0, 0.3));
+ display: grid;
+ place-items: center;
+ overflow: hidden;
+}
+
+.sp-card-art img {
+ width: 100%;
+ height: 100%;
+ object-fit: cover;
+ transition: transform var(--duration-base, 220ms) var(--ease-standard);
+}
+
+.sp-card:hover .sp-card-art img {
+ transform: scale(1.03);
+}
+
+/* Fallback art: a deterministic monogram, so an agent with no public avatar
+ still gets a card that looks designed rather than broken. The hue comes from
+ the agent id in JS, which keeps the same agent the same colour everywhere. */
+.sp-mono {
+ width: 100%;
+ height: 100%;
+ display: grid;
+ place-items: center;
+ font-family: var(--font-display);
+ font-size: var(--text-3xl, 48px);
+ font-weight: var(--weight-bold, 700);
+ color: var(--on-scrim-bright, #fff);
+ letter-spacing: -0.03em;
+}
+
+.sp-card-badges {
+ position: absolute;
+ top: var(--space-2, 8px);
+ left: var(--space-2, 8px);
+ display: flex;
+ flex-wrap: wrap;
+ gap: 6px;
+}
+
+.sp-badge {
+ padding: 3px 8px;
+ border-radius: var(--radius-pill, 999px);
+ background: var(--scrim, rgba(0, 0, 0, 0.55));
+ border: 1px solid var(--on-scrim-stroke, rgba(255, 255, 255, 0.16));
+ color: var(--on-scrim, rgba(255, 255, 255, 0.86));
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ backdrop-filter: blur(var(--blur-sm, 8px));
+}
+
+.sp-badge-onchain {
+ color: var(--success, #4ade80);
+ border-color: color-mix(in srgb, var(--success, #4ade80) 40%, transparent);
+}
+
+.sp-badge-curated {
+ color: var(--warn, #fbbf24);
+ border-color: color-mix(in srgb, var(--warn, #fbbf24) 40%, transparent);
+}
+
+.sp-card-body {
+ display: grid;
+ gap: var(--space-2, 8px);
+ padding: var(--space-md, 16px);
+ align-content: start;
+}
+
+.sp-card-title {
+ margin: 0;
+ font-family: var(--font-display);
+ font-size: var(--text-lg, 18px);
+ font-weight: var(--weight-semibold, 600);
+ line-height: var(--leading-tight, 1.25);
+ color: var(--ink-bright, #fff);
+}
+
+.sp-card-title a {
+ color: inherit;
+ text-decoration: none;
+}
+
+/* The title link covers the card, so the whole surface is one big target while
+ the vote button and the secondary links below stay individually clickable. */
+.sp-card-title a::after {
+ content: '';
+ position: absolute;
+ inset: 0;
+ z-index: 0;
+}
+
+.sp-card-tagline {
+ margin: 0;
+ font-size: var(--text-ui, 14px);
+ line-height: var(--leading-normal, 1.55);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.64));
+ display: -webkit-box;
+ -webkit-line-clamp: 3;
+ -webkit-box-orient: vertical;
+ overflow: hidden;
+}
+
+.sp-card-meta {
+ display: flex;
+ flex-wrap: wrap;
+ align-items: center;
+ gap: 6px;
+ font-size: var(--text-md, 13px);
+ color: var(--ink-faint, rgba(255, 255, 255, 0.5));
+}
+
+.sp-card-meta strong {
+ color: var(--ink, rgba(255, 255, 255, 0.82));
+ font-weight: var(--weight-medium, 500);
+}
+
+.sp-tags {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 5px;
+}
+
+.sp-tag {
+ padding: 2px 8px;
+ border-radius: var(--radius-sm, 6px);
+ background: var(--surface-2, rgba(255, 255, 255, 0.05));
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.08));
+ color: var(--ink-faint, rgba(255, 255, 255, 0.5));
+ font-family: var(--font-mono);
+ font-size: var(--text-2xs, 11px);
+ cursor: pointer;
+ position: relative;
+ z-index: 1;
+}
+
+.sp-tag:hover {
+ color: var(--ink-bright, #fff);
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.22));
+}
+
+.sp-card-foot {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: var(--space-sm, 12px);
+ padding: var(--space-sm, 12px) var(--space-md, 16px);
+ border-top: 1px solid var(--stroke, rgba(255, 255, 255, 0.08));
+ position: relative;
+ z-index: 1;
+}
+
+.sp-card-links {
+ display: flex;
+ flex-wrap: wrap;
+ gap: var(--space-2, 8px);
+ font-size: var(--text-md, 13px);
+}
+
+.sp-card-links a {
+ color: var(--ink-dim, rgba(255, 255, 255, 0.62));
+ text-decoration: none;
+ border-bottom: 1px solid transparent;
+ transition:
+ color var(--duration-fast, 140ms) var(--ease-standard),
+ border-color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-card-links a:hover {
+ color: var(--ink-bright, #fff);
+ border-bottom-color: var(--stroke-strong, rgba(255, 255, 255, 0.35));
+}
+
+/* ── vote ─────────────────────────────────────────────────────────────── */
+
+.sp-vote {
+ display: inline-flex;
+ flex-direction: column;
+ align-items: center;
+ justify-content: center;
+ min-width: 52px;
+ padding: 5px 10px;
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.14));
+ border-radius: var(--radius-md, 10px);
+ background: var(--surface-1, rgba(255, 255, 255, 0.04));
+ color: var(--ink, rgba(255, 255, 255, 0.82));
+ font-family: var(--font-mono);
+ font-size: var(--text-md, 13px);
+ line-height: 1.1;
+ cursor: pointer;
+ transition:
+ background var(--duration-fast, 140ms) var(--ease-standard),
+ border-color var(--duration-fast, 140ms) var(--ease-standard),
+ color var(--duration-fast, 140ms) var(--ease-standard);
+}
+
+.sp-vote:hover {
+ border-color: var(--stroke-strong, rgba(255, 255, 255, 0.3));
+ background: var(--surface-2, rgba(255, 255, 255, 0.08));
+}
+
+.sp-vote[aria-pressed='true'] {
+ border-color: color-mix(in srgb, var(--success, #4ade80) 55%, transparent);
+ background: color-mix(in srgb, var(--success, #4ade80) 14%, transparent);
+ color: var(--success, #4ade80);
+}
+
+.sp-vote-caret {
+ font-size: var(--text-2xs, 11px);
+ line-height: 1;
+ opacity: 0.8;
+}
+
+.sp-vote-count {
+ font-variant-numeric: tabular-nums;
+ font-weight: var(--weight-semibold, 600);
+}
+
+.sp-vote.is-busy {
+ opacity: 0.6;
+ pointer-events: none;
+}
+
+/* ── states ───────────────────────────────────────────────────────────── */
+
+.sp-skeleton {
+ height: 340px;
+ border-radius: var(--radius-lg, 14px);
+ border: 1px solid var(--stroke, rgba(255, 255, 255, 0.06));
+ background: linear-gradient(
+ 100deg,
+ var(--surface-1, rgba(255, 255, 255, 0.03)) 30%,
+ var(--surface-2, rgba(255, 255, 255, 0.07)) 50%,
+ var(--surface-1, rgba(255, 255, 255, 0.03)) 70%
+ );
+ background-size: 220% 100%;
+ animation: sp-shimmer 1.4s var(--ease-standard) infinite;
+}
+
+@keyframes sp-shimmer {
+ from {
+ background-position: 140% 0;
+ }
+ to {
+ background-position: -40% 0;
+ }
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .sp-skeleton {
+ animation: none;
+ }
+}
+
+.sp-empty,
+.sp-error {
+ margin: var(--space-lg, 24px) 0;
+ padding: var(--space-2xl, 48px) var(--space-lg, 24px);
+ border: 1px dashed var(--stroke, rgba(255, 255, 255, 0.14));
+ border-radius: var(--radius-lg, 14px);
+ text-align: center;
+ display: grid;
+ justify-items: center;
+ gap: var(--space-sm, 12px);
+}
+
+.sp-empty h3,
+.sp-error h3 {
+ margin: 0;
+ font-family: var(--font-display);
+ font-size: var(--text-lg, 20px);
+ color: var(--ink-bright, #fff);
+}
+
+.sp-empty p,
+.sp-error p {
+ margin: 0;
+ max-width: 52ch;
+ font-size: var(--text-ui, 14px);
+ line-height: var(--leading-normal, 1.6);
+ color: var(--ink-dim, rgba(255, 255, 255, 0.6));
+}
+
+.sp-error h3 {
+ color: var(--danger, #f87171);
+}
+
+.sp-more-wrap {
+ display: flex;
+ justify-content: center;
+ margin: var(--space-xl, 32px) 0 0;
+}
+
+@media (max-width: 560px) {
+ .sp-shell {
+ padding-left: var(--space-md, 16px);
+ padding-right: var(--space-md, 16px);
+ }
+
+ .sp-title {
+ font-size: var(--text-xl, 30px);
+ }
+
+ .sp-controls {
+ flex-direction: column;
+ align-items: stretch;
+ }
+
+ .sp-search {
+ max-width: none;
+ }
+}
diff --git a/src/spotlight.js b/src/spotlight.js
new file mode 100644
index 000000000..1de7a8d61
--- /dev/null
+++ b/src/spotlight.js
@@ -0,0 +1,797 @@
+/**
+ * /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.
+ *
+ * The 3D stage on the featured entry is deliberately lazy: <agent-3d> is a
+ * WebGL component and the showcase 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';
+
+const AGENT_3D_LOADER = 'https://three.ws/agent-3d/latest/agent-3d.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'),
+ agentSelect: document.getElementById('sp-agent'),
+ agentHint: document.getElementById('sp-agent-hint'),
+ categorySelect: document.getElementById('sp-category'),
+ 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;
+
+/* ── 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) continue;
+ 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 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;
+}
+
+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;
+}
+
+function categoryLabel(slug) {
+ return categories.find((c) => c.slug === slug)?.label || slug;
+}
+
+/* ── the featured stage ───────────────────────────────────────────────── */
+
+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);
+}
+
+function stageFor(entry) {
+ const stage = el('div', { class: 'sp-stage' });
+ stage.append(el('span', { class: 'sp-stage-badge', text: "Editor's pick" }));
+
+ if (entry.agent.glb_url) {
+ // Mounted only when the stage is actually on screen. Below-the-fold WebGL
+ // on a browse page costs a visitor real frames for something they may
+ // never scroll to.
+ const mount = () => {
+ loadAgent3d();
+ stage.append(
+ el('agent-3d', {
+ body: entry.agent.glb_url,
+ autorotate: 'true',
+ 'camera-controls': 'true',
+ 'aria-label': `${entry.agent.name} in 3D`,
+ }),
+ );
+ };
+ if ('IntersectionObserver' in window) {
+ const io = new IntersectionObserver(
+ (entries, obs) => {
+ if (entries.some((e) => e.isIntersecting)) {
+ obs.disconnect();
+ mount();
+ }
+ },
+ { rootMargin: '200px' },
+ );
+ io.observe(stage);
+ } else {
+ mount();
+ }
+ } else if (entry.agent.thumbnail) {
+ stage.append(
+ el('img', {
+ src: entry.agent.thumbnail,
+ alt: `${entry.agent.name} avatar`,
+ loading: 'lazy',
+ decoding: 'async',
+ }),
+ );
+ } else {
+ stage.append(monogram(entry.agent));
+ }
+ return stage;
+}
+
+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: `/agents/${entry.agent.id}`, 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: `/agents/${entry.agent.id}`, text: `Open ${entry.agent.name}` }),
+ el('a', { class: 'sp-btn', href: `/agents/${entry.agent.id}/profile`, text: 'Read the profile' }),
+ entry.demo_url
+ ? el('a', {
+ class: 'sp-btn',
+ href: entry.demo_url,
+ target: '_blank',
+ rel: 'noopener nofollow ugc',
+ text: 'See it live',
+ })
+ : null,
+ voteButton(entry),
+ ]),
+ ]);
+
+ els.featuredBody.replaceChildren(stageFor(entry), 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: '·' }));
+ const by = entry.builder.profile_url
+ ? el('a', { href: entry.builder.profile_url, text: `by ${entry.builder.name}` })
+ : el('span', { text: `by ${entry.builder.name}` });
+ bits.push(by);
+ }
+ 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 voteButton(entry) {
+ const count = el('span', { class: 'sp-vote-count', text: String(entry.vote_count) });
+ const btn = el(
+ 'button',
+ {
+ type: 'button',
+ class: '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/showcase/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(data?.error?.message || '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.`);
+ } catch {
+ announce('the vote did not go through; check your connection');
+ } finally {
+ btn.classList.remove('is-busy');
+ }
+ });
+
+ return btn;
+}
+
+function cardFor(entry) {
+ const art = el('div', { class: 'sp-card-art' });
+ if (entry.agent.thumbnail) {
+ art.append(
+ el('img', {
+ src: entry.agent.thumbnail,
+ alt: `${entry.agent.name} avatar`,
+ loading: 'lazy',
+ decoding: 'async',
+ }),
+ );
+ } else {
+ art.append(monogram(entry.agent));
+ }
+
+ const badges = 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,
+ ]);
+ art.append(badges);
+
+ 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: `/agents/${entry.agent.id}`, 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' }),
+ el('a', { href: `/agents/${entry.agent.id}/profile`, text: 'Profile' }),
+ entry.demo_url
+ ? el('a', { href: entry.demo_url, target: '_blank', rel: 'noopener nofollow ugc', text: 'Demo' })
+ : null,
+ ]);
+
+ const foot = el('div', { class: 'sp-card-foot' }, [links, voteButton(entry)]);
+
+ return el('article', { class: 'sp-card' }, [art, body, foot]);
+}
+
+/* ── 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();
+ 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/showcase/list?${p}`, { allowAnonymous: true });
+ if (token !== loadToken) return;
+ if (res.status === 503) {
+ renderEmpty();
+ els.grid.replaceChildren();
+ return;
+ }
+ const data = await res.json().catch(() => null);
+ if (!res.ok) throw new Error(data?.error?.message || `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;
+ }
+ els.stats.replaceChildren(
+ el('div', {}, [
+ el('dd', { text: totals.entries.toLocaleString() }),
+ el('dt', { text: totals.entries === 1 ? 'agent showcased' : 'agents showcased' }),
+ ]),
+ el('div', {}, [
+ el('dd', { text: totals.builders.toLocaleString() }),
+ el('dt', { text: totals.builders === 1 ? 'builder' : 'builders' }),
+ ]),
+ el('div', {}, [
+ el('dd', { text: totals.votes.toLocaleString() }),
+ el('dt', { text: totals.votes === 1 ? 'upvote' : 'upvotes' }),
+ ]),
+ );
+}
+
+/* ── featured rail + categories ───────────────────────────────────────── */
+
+async function loadFeatured() {
+ try {
+ const res = await apiFetch('/api/showcase/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/showcase/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();
+ fillCategorySelect();
+ } catch {
+ categories = [];
+ }
+}
+
+function fillCategorySelect() {
+ if (!els.categorySelect || !categories.length) return;
+ els.categorySelect.replaceChildren(
+ ...categories.map((c) => el('option', { value: c.slug, text: c.label })),
+ );
+}
+
+/* ── 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;
+ els.agentSelect.replaceChildren(el('option', { value: '', text: 'Loading your agents…' }));
+ try {
+ const res = await apiFetch('/api/showcase/eligible', { allowAnonymous: true });
+ if (res.status === 401) {
+ eligibleLoaded = false;
+ showPanelAuth();
+ return;
+ }
+ const data = await res.json().catch(() => null);
+ if (!res.ok) throw new Error(data?.error?.message || 'could not load your agents');
+
+ if (Array.isArray(data.categories) && data.categories.length && !categories.length) {
+ categories = data.categories.map((c) => ({ ...c, count: 0 }));
+ fillCategorySelect();
+ }
+
+ const agents = Array.isArray(data.agents) ? data.agents : [];
+ if (!agents.length) {
+ els.agentSelect.replaceChildren(el('option', { value: '', text: 'No eligible agents' }));
+ els.agentSelect.disabled = true;
+ els.submit.disabled = true;
+ els.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;
+ }
+ els.agentSelect.disabled = false;
+ els.submit.disabled = false;
+ els.agentSelect.replaceChildren(
+ el('option', { value: '', text: 'Choose an agent…' }),
+ ...agents.map((a) => el('option', { value: a.id, text: a.name })),
+ );
+ els.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.
+ els.agentSelect.addEventListener('change', () => {
+ const chosen = agents.find((a) => a.id === els.agentSelect.value);
+ const tagline = document.getElementById('sp-tagline');
+ if (chosen?.description && tagline && !tagline.value.trim()) {
+ tagline.value = chosen.description.replace(/\s+/g, ' ').trim().slice(0, 160);
+ tagline.dispatchEvent(new Event('input'));
+ }
+ });
+ } catch (err) {
+ eligibleLoaded = false;
+ els.agentSelect.replaceChildren(el('option', { value: '', text: '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' }),
+ );
+ els.agentSelect.replaceChildren(el('option', { value: '', text: 'Sign in first' }));
+ els.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;
+}
+
+function parseTags(raw) {
+ return raw
+ .split(',')
+ .map((t) => t.trim().toLowerCase().replace(/\s+/g, '-'))
+ .filter(Boolean)
+ .slice(0, 6);
+}
+
+async function onSubmit(event) {
+ event.preventDefault();
+ const agentId = els.agentSelect.value;
+ if (!agentId) return setNote('pick which agent you are showcasing', 'error');
+
+ const payload = {
+ agentId,
+ title: document.getElementById('sp-title').value.trim(),
+ tagline: document.getElementById('sp-tagline').value.trim(),
+ story: document.getElementById('sp-story').value.trim() || null,
+ demoUrl: document.getElementById('sp-demo').value.trim() || null,
+ category: els.categorySelect.value,
+ tags: parseTags(document.getElementById('sp-tags').value),
+ };
+
+ if (payload.title.length < 3) return setNote('the headline needs at least 3 characters', 'error');
+ if (payload.tagline.length < 10) return setNote('the one-liner needs at least 10 characters', 'error');
+
+ els.submit.disabled = true;
+ setNote('Publishing…');
+ try {
+ const res = await apiFetch('/api/showcase/submit', {
+ method: 'POST',
+ headers: { 'content-type': 'application/json' },
+ body: JSON.stringify(payload),
+ allowAnonymous: true,
+ });
+ if (res.status === 401) {
+ showPanelAuth();
+ setNote('sign in to publish', 'error');
+ return;
+ }
+ const data = await res.json().catch(() => null);
+ if (!res.ok) throw new Error(data?.error?.message || `the submission returned ${res.status}`);
+
+ setNote('Published. Your agent is in the showcase.', 'success');
+ els.panel.reset();
+ eligibleLoaded = false;
+ view.offset = 0;
+ view.sort = 'new';
+ syncSortButtons();
+ writeUrl();
+ await Promise.all([load(), loadCategories()]);
+ announce(`${payload.title} is now in the showcase.`);
+ setTimeout(() => openPanel(false), 1200);
+ } catch (err) {
+ 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 wireCharCounters() {
+ for (const counter of document.querySelectorAll('[data-count-for]')) {
+ const field = document.getElementById(counter.dataset.countFor);
+ if (!field) continue;
+ const update = () => {
+ counter.textContent = String(field.value.length);
+ };
+ field.addEventListener('input', update);
+ update();
+ }
+}
+
+function wire() {
+ 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();
+ });
+
+ wireCharCounters();
+}
+
+readUrl();
+syncSortButtons();
+wire();
+load();
+loadCategories();
+loadFeatured();
diff --git a/vercel.json b/vercel.json
index 97e8ab7cc..90f81765c 100644
--- a/vercel.json
+++ b/vercel.json
@@ -937,6 +937,10 @@
"src": "/drops/?$",
"dest": "/drops.html"
},
+ {
+ "src": "/spotlight/?$",
+ "dest": "/spotlight.html"
+ },
{
"src": "/drops/([a-z0-9][a-z0-9-]*)/?$",
"dest": "/drop-collection.html"
diff --git a/vite.config.js b/vite.config.js
index 62a971195..39baebca3 100644
--- a/vite.config.js
+++ b/vite.config.js
@@ -541,6 +541,7 @@ const appConfig = {
i18n: resolve(__dirname, 'src/i18n.js'),
drops: resolve(__dirname, 'pages/drops.html'),
'drop-collection': resolve(__dirname, 'pages/drop-collection.html'),
+ spotlight: resolve(__dirname, 'pages/spotlight.html'),
app: resolve(__dirname, 'pages/app.html'),
proof: resolve(__dirname, 'pages/proof.html'),
stream: resolve(__dirname, 'pages/stream.html'),
@@ -1438,6 +1439,8 @@ const appConfig = {
'/portfolio/': resolve(root, 'pages/portfolio.html'),
'/drops': resolve(root, 'pages/drops.html'),
'/drops/': resolve(root, 'pages/drops.html'),
+ '/spotlight': resolve(root, 'pages/spotlight.html'),
+ '/spotlight/': resolve(root, 'pages/spotlight.html'),
'/airdrops': resolve(root, 'pages/airdrops.html'),
'/airdrops/': resolve(root, 'pages/airdrops.html'),
'/launcher': resolve(root, 'pages/launcher.html'),