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.

10.4 KB
Raw Blame
// /character-library — the Mixamo character library gallery.
//
// Browses the professionally rigged humanoid characters served by
// GET /api/avatars/library (manifest on R2, mirroring the /animations gallery).
// Each card renders a live <model-viewer> off the GLB's CDN url and deep-links
// into the three viewers that accept a raw model URL:
//   Preview → /app#model=<glb>      (real three.js viewer)
//   Use     → /studio?model=<glb>   (widget studio)
//   Animate → /pose?src=<glb>       (animation studio; r2.dev is a trusted host)
//
// The library is small (a hundred or so entries) so the whole manifest is
// fetched once and filtered/sorted client-side: no pagination round-trips,
// instant search. The search, sort, card copy and deep links are pure functions
// of the manifest and live in shared/character-library-view.js, under test in
// tests/character-library-view.test.js.

import {
	cardMeta,
	characterName,
	viewerLinks,
	viewState,
	visibleCharacters,
} from './shared/character-library-view.js';

const els = {
	grid: document.querySelector('[data-role="grid"]'),
	loading: document.querySelector('[data-role="loading"]'),
	empty: document.querySelector('[data-role="empty"]'),
	emptySearch: document.querySelector('[data-role="empty-search"]'),
	error: document.querySelector('[data-role="error"]'),
	errorMsg: document.querySelector('[data-role="error-msg"]'),
	search: document.querySelector('[data-role="search"]'),
	sort: document.querySelector('[data-role="sort"]'),
	count: document.querySelector('[data-role="count"]'),
	heroStats: document.querySelector('[data-role="hero-stats"]'),
	clearSearch: document.querySelector('[data-role="clear-search"]'),
	retry: document.querySelector('[data-role="retry"]'),
};

const state = {
	all: [],
	query: '',
	sort: 'az',
};

function escapeHtml(s) {
	return String(s ?? '').replace(/[&<>"']/g, (c) =>
		({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]),
	);
}
function escapeAttr(s) {
	return escapeHtml(s);
}

function show(el, on) {
	if (el) el.hidden = !on;
}

// Exactly one of the page's five states is on screen at a time; showing the next
// one is always "hide the other four".
const PANELS = {
	loading: () => els.loading,
	grid: () => els.grid,
	empty: () => els.empty,
	'empty-search': () => els.emptySearch,
	error: () => els.error,
};

function showOnly(name) {
	for (const [key, el] of Object.entries(PANELS)) show(el(), key === name);
}

// A card's <model-viewer> is deliberately control-free. model-viewer reads
// `camera-controls` as a boolean attribute, so the old `camera-controls="false"`
// switched controls ON: it made every thumbnail drag-orbit under the link that
// wraps it, and it gave each of the hundred-plus cards a keyboard tab stop with
// nothing to operate. Dropping the attribute leaves auto-rotate (which does not
// need controls) and hands the click straight to the viewer link. The `disable-*`
// attributes went with it; they only ever qualified camera-controls.
//
// The thumbnail is slotted in as a real <img> rather than passed as `poster=`.
// model-viewer's built-in poster is a <button> in its shadow DOM, so the default
// gave every card a second tab stop announcing the same character name as the
// link that wraps it. A slotted poster replaces that button, and the image gets
// native lazy loading and off-thread decoding on the way.
function renderCard(a) {
	const glbUrl = a.url || '';
	const links = viewerLinks(a);
	const thumb = a.thumb || '';
	const alt = characterName(a) || 'Character';

	// A row with no GLB gets a plain, unlinked tile rather than an anchor to "#":
	// the three viewers all take the model URL, so with none there is nothing for
	// them to open.
	const openTag = links
		? `<a class="ch-card-thumb" href="${escapeAttr(links.preview)}" aria-label="Preview ${escapeAttr(alt)} in 3D">`
		: '<div class="ch-card-thumb">';
	const closeTag = links ? '</a>' : '</div>';
	const actions = links
		? `<div class="ch-card-actions">
				<a class="ch-btn ch-btn--primary" href="${escapeAttr(links.use)}" title="Use in Widget Studio">Use</a>
				<a class="ch-btn ch-btn--ghost" href="${escapeAttr(links.animate)}" title="Animate in the Animation Studio">Animate</a>
				<a class="ch-btn ch-btn--ghost" href="${escapeAttr(links.preview)}" title="Open in the 3D viewer">Preview</a>
			</div>`
		: '';

	const card = document.createElement('article');
	card.className = 'ch-card';
	card.innerHTML = `
		${openTag}
			<model-viewer
				src="${escapeAttr(glbUrl)}"
				alt="${escapeAttr(alt)}"
				class="ch-card-mv"
				reveal="manual"
				loading="lazy"
				interaction-prompt="none"
				auto-rotate
				rotation-per-second="20deg"
				environment-image="neutral"
				shadow-intensity="0"
				exposure="1"
			>${thumb ? `<img slot="poster" class="ch-card-poster" src="${escapeAttr(thumb)}" alt="" loading="lazy" decoding="async" />` : ''}</model-viewer>
			<span class="ch-card-pill">Rigged</span>
			<span class="ch-card-play" aria-hidden="true">▶</span>
		${closeTag}
		<div class="ch-card-body">
			<h3 class="ch-card-name">${escapeHtml(alt)}</h3>
			<div class="ch-card-meta">
				<span title="Skinned mesh, ready to animate">${escapeHtml(cardMeta(a))}</span>
			</div>
			${actions}
		</div>
	`;
	return card;
}

// ── Intent-driven model loading ──────────────────────────────────────────────
// A library character is a 4-76 MB GLB, so letting every card auto-load streamed
// hundreds of megabytes nobody had asked for, and any model still in flight when
// the visitor navigated away logged an aborted fetch in the console. Cards mount
// with `reveal="manual"`, which paints the poster and downloads nothing; the
// model streams on real intent only: a hover that settles, or keyboard focus
// that settles. Tabbing or sweeping the pointer across the grid therefore costs
// nothing, and a touch visitor taps straight through to the full viewer instead
// of paying for a preview on cellular.
const REVEAL_DWELL_MS = 180;
let pendingReveal = null;

function revealModel(thumb) {
	if (!thumb || thumb.dataset.revealed) return;
	const mv = thumb.querySelector('model-viewer');
	if (!mv) return;
	thumb.dataset.revealed = '1';
	thumb.classList.add('is-live');
	// A slotted poster is ours to clear: dismissPoster only fades model-viewer's
	// own built-in poster, so without this the thumbnail would sit on top of the
	// model it just finished downloading.
	if (mv.loaded) mv.dataset.loaded = '1';
	else mv.addEventListener('load', () => { mv.dataset.loaded = '1'; }, { once: true });
	// whenDefined resolves synchronously once the CDN module has upgraded the
	// element, and waits for it on a slow connection instead of no-opping.
	customElements.whenDefined('model-viewer').then(() => mv.dismissPoster?.());
}

function scheduleReveal(thumb) {
	if (!thumb || thumb.dataset.revealed) return;
	cancelReveal();
	pendingReveal = { thumb, timer: setTimeout(() => revealModel(thumb), REVEAL_DWELL_MS) };
}

function cancelReveal(thumb) {
	if (!pendingReveal) return;
	if (thumb && pendingReveal.thumb !== thumb) return;
	clearTimeout(pendingReveal.timer);
	pendingReveal = null;
}

function wireReveal() {
	if (!els.grid) return;
	els.grid.addEventListener('pointerover', (e) => {
		// Touch fires pointerover just before the tap navigates to the viewer, so
		// starting a download there would be pure waste. Honour Data Saver too.
		if (e.pointerType === 'touch' || navigator.connection?.saveData) return;
		scheduleReveal(e.target.closest?.('.ch-card-thumb'));
	});
	els.grid.addEventListener('pointerout', (e) => {
		const thumb = e.target.closest?.('.ch-card-thumb');
		// pointerout also fires moving between a card's own children; only a
		// pointer that actually left the card cancels the pending reveal.
		if (thumb && !thumb.contains(e.relatedTarget)) cancelReveal(thumb);
	});
	els.grid.addEventListener('focusin', (e) => scheduleReveal(e.target.closest?.('.ch-card-thumb')));
	els.grid.addEventListener('focusout', (e) => cancelReveal(e.target.closest?.('.ch-card-thumb')));
}

function applyView() {
	const list = visibleCharacters(state.all, { query: state.query, sort: state.sort });
	const panel = viewState({ loaded: true, failed: false, total: state.all.length, visible: list.length });

	if (panel !== 'grid') {
		showOnly(panel);
		if (els.count) els.count.textContent = panel === 'empty-search' ? '0 characters' : '';
		return;
	}

	const frag = document.createDocumentFragment();
	for (const a of list) frag.appendChild(renderCard(a));
	// A reveal armed against a card this render is about to drop would fire on a
	// detached element.
	cancelReveal();
	els.grid.replaceChildren(frag);

	showOnly('grid');
	if (els.count) els.count.textContent = `${list.length} of ${state.all.length}`;
}

async function load() {
	showOnly('loading');

	try {
		const res = await fetch('/api/avatars/library');
		if (!res.ok) throw new Error(`HTTP ${res.status}`);
		const data = await res.json();
		state.all = Array.isArray(data.avatars) ? data.avatars : [];
		// The hero used to hard-code "106" in its headline, which went stale the
		// moment the 107th character landed on R2. The manifest is now the only
		// place the number lives, and it renders here.
		if (els.heroStats) {
			els.heroStats.textContent = state.all.length
				? `${state.all.length} rigged characters · free to use`
				: '';
		}
		applyView();
	} catch (err) {
		showOnly('error');
		if (els.errorMsg) {
			// The catalog pass lands after /api/locale resolves and would otherwise
			// revert this concrete reason back to the generic placeholder shipped in
			// the HTML. data-i18n-owned hands the element to this script for good.
			els.errorMsg.dataset.i18nOwned = '1';
			els.errorMsg.textContent = `Failed to load characters: ${err?.message || 'network error'}`;
		}
	}
}

function wire() {
	let t;
	els.search?.addEventListener('input', (e) => {
		clearTimeout(t);
		const v = e.target.value;
		t = setTimeout(() => {
			state.query = v;
			applyView();
		}, 120);
	});
	els.sort?.addEventListener('change', (e) => {
		state.sort = e.target.value;
		applyView();
	});
	els.clearSearch?.addEventListener('click', () => {
		state.query = '';
		if (els.search) els.search.value = '';
		applyView();
	});
	els.retry?.addEventListener('click', load);

	// "/" focuses search, matching the /animations gallery affordance.
	document.addEventListener('keydown', (e) => {
		if (e.key === '/' && document.activeElement !== els.search) {
			e.preventDefault();
			els.search?.focus();
		}
	});
}

wire();
wireReveal();
load();