Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

8.8 KB
Raw Blame
// /herald: the playground for @three-ws/herald (herald-sdk/).
//
// Everything on this page runs the real library against the real rules engine
// in the visitor's own tab. The composer builds a message, the rules panel
// rebuilds the herald with the visitor's rules, and the verdict log prints what
// the engine actually decided, drop reasons included. Signed in, the page also
// subscribes to the delivery rail, so a `curl` from a terminal (or the CLI, or
// a CI job) is delivered here by the same avatar.
//
// The page is deliberately usable signed out: the SDK needs no account, and the
// only thing an account adds is the rail.

import { createHerald, railSource } from '../herald-sdk/src/index.js';

const AUTH_HINT_KEY = '3dagent:auth-hint';

const $ = (sel) => document.querySelector(sel);

const els = {
	text: $('#f-text'),
	from: $('#f-from'),
	url: $('#f-url'),
	tone: $('#f-tone'),
	emote: $('#f-emote'),
	presenter: $('#f-presenter'),
	importance: $('#f-importance'),
	importanceOut: $('#f-importance-out'),
	voice: $('#f-voice'),
	send: $('#f-send'),
	burst: $('#f-burst'),
	demoRun: $('#demo-run'),
	floor: $('#r-floor'),
	floorOut: $('#r-floor-out'),
	rate: $('#r-rate'),
	rateOut: $('#r-rate-out'),
	quiet: $('#r-quiet'),
	focus: $('#r-focus'),
	verdicts: $('#verdicts'),
	stats: $('#stats'),
	railDot: $('#rail-dot'),
	railLabel: $('#rail-label'),
	railKey: $('#rail-key'),
};

let herald = null;
let railStop = null;

// ── The live herald ─────────────────────────────────────────────────────────
// Rebuilt whenever the rules change, because the rules are constructor-level:
// a herald is cheap to build and this keeps the demo honest about what the
// library actually does rather than mutating private state behind the scenes.

function build() {
	herald?.stop();
	railStop = null;

	herald = createHerald({
		presenter: els.presenter.value,
		// A visitor who never switched the companion on still gets a body: the
		// site serves it at /walk-companion.js.
		avatarOptions: { walkModule: '/walk-companion.js' },
		voice: els.voice.checked ? 'always' : 'off',
		rules: {
			minImportance: Number(els.floor.value),
			maxPerWindow: Number(els.rate.value),
			quietHours: els.quiet.checked ? [22, 7] : null,
			focusOnly: els.focus.checked,
			// The playground is a place to try things: a message you send twice on
			// purpose should be visible as a duplicate within seconds, not held
			// against you for six hours.
			dedupeTtlMs: 30_000,
		},
		onDeliver: (m) => logVerdict('deliver', m.text, `importance ${m.importance}`),
		onHold: (m, reason) => logVerdict('hold', m.text, reason),
		onDrop: (m, reason) => logVerdict('drop', m?.text || '(empty)', reason),
		actionsFor: () => [
			{ label: 'Mute 1 min', title: 'Silence deliveries for a minute', onClick: () => herald.mute(60_000) },
		],
	});

	if (isAuthed()) connectRail();
	renderStats();
}

function isAuthed() {
	try {
		return JSON.parse(localStorage.getItem(AUTH_HINT_KEY) || 'null')?.authed === true;
	} catch {
		return false;
	}
}

// ── The rail ────────────────────────────────────────────────────────────────

function connectRail() {
	if (!('EventSource' in window)) return setRail('off', 'This browser has no EventSource');
	setRail('', 'Connecting…');
	// The stream itself is the status: EventSource tells us when it is open and
	// when it drops, so the label is what is actually true rather than the
	// result of a separate probe request.
	railStop = herald.source(
		railSource({
			// Same-origin: the SDK defaults to three.ws, but on a preview origin
			// (or localhost) the stream lives here, not there.
			origin: window.location.origin,
			onOpen: () => setRail('live', 'Listening on your rail'),
			// EventSource reconnects on its own, so a drop is a status change, not
			// a failure to recover from.
			onError: () => setRail('off', 'Rail disconnected, retrying…'),
		}),
	);
}

function setRail(state, label) {
	els.railDot.className = `dot${state ? ` ${state}` : ''}`;
	els.railLabel.textContent = label;
}

// ── Verdict log + stats ─────────────────────────────────────────────────────

function logVerdict(action, text, why) {
	const row = document.createElement('div');
	row.className = `verdict ${action}`;
	const tag = document.createElement('span');
	tag.className = 'tag';
	tag.textContent = action.toUpperCase();
	const body = document.createElement('span');
	body.textContent = text;
	const reason = document.createElement('span');
	reason.className = 'why';
	reason.textContent = why ? `· ${why}` : '';
	row.append(tag, body, reason);

	if (els.verdicts.firstElementChild?.querySelector('.why')?.textContent?.startsWith('Nothing yet')) {
		els.verdicts.textContent = '';
	}
	els.verdicts.prepend(row);
	while (els.verdicts.children.length > 40) els.verdicts.lastElementChild.remove();
	renderStats();
}

function renderStats() {
	const s = herald.stats();
	const cells = [
		['delivered', s.delivered],
		['held', s.holding],
		['dropped', s.dropped],
		['spoken', s.spoken],
	];
	els.stats.innerHTML = '';
	for (const [label, value] of cells) {
		const cell = document.createElement('div');
		cell.className = 'stat';
		const b = document.createElement('b');
		b.textContent = String(value);
		const span = document.createElement('span');
		span.textContent = label;
		cell.append(b, span);
		els.stats.appendChild(cell);
	}
}

// ── Composer ────────────────────────────────────────────────────────────────

function compose(over = {}) {
	return {
		// A fresh id per send: the playground is for trying the same line twice
		// and watching the dedupe window catch the second one.
		id: `play-${Date.now()}-${Math.round(Math.random() * 1e6)}`,
		text: els.text.value.trim() || 'Deploy is green',
		from: els.from.value.trim() || undefined,
		url: els.url.value.trim() || undefined,
		tone: els.tone.value,
		emote: els.emote.value,
		importance: Number(els.importance.value),
		...over,
	};
}

function send() {
	herald.announce(compose());
}

function burst() {
	const lines = [
		'Build queued',
		'Tests passed',
		'Container pushed',
		'Migration applied',
		'Deploy is green',
	];
	lines.forEach((text, i) => {
		herald.announce(compose({ text, importance: 60 + i * 8, id: `burst-${Date.now()}-${i}` }));
	});
}

// ── Wiring ──────────────────────────────────────────────────────────────────

els.importance.addEventListener('input', () => {
	els.importanceOut.textContent = els.importance.value;
});
els.floor.addEventListener('input', () => {
	els.floorOut.textContent = els.floor.value;
});
els.rate.addEventListener('input', () => {
	els.rateOut.textContent = els.rate.value;
});

for (const control of [els.floor, els.rate, els.quiet, els.focus, els.presenter, els.voice]) {
	control.addEventListener('change', build);
}

els.send.addEventListener('click', send);
els.burst.addEventListener('click', burst);
els.demoRun.addEventListener('click', () => {
	document.getElementById('playground')?.scrollIntoView({ behavior: 'smooth', block: 'start' });
	herald.announce({
		id: `hero-${Date.now()}`,
		text: 'This is what an important message looks like',
		from: 'herald',
		importance: 90,
		tone: 'celebrate',
		emote: 'dance',
		url: '/docs/herald',
	});
});

// Enter in the message field sends, because a demo you have to reach for the
// mouse to run is a demo people bounce off.
els.text.addEventListener('keydown', (e) => {
	if (e.key === 'Enter') {
		e.preventDefault();
		send();
	}
});

for (const btn of document.querySelectorAll('.copy')) {
	btn.addEventListener('click', async () => {
		const target = document.querySelector(btn.dataset.copy);
		if (!target) return;
		const text = target.textContent.replace(/^Copy/, '').trim();
		try {
			await navigator.clipboard.writeText(text);
			const original = btn.textContent;
			btn.textContent = 'Copied';
			setTimeout(() => {
				btn.textContent = original;
			}, 1400);
		} catch {
			// Clipboard blocked (permissions, insecure context): select the block
			// so the visitor can copy it themselves rather than being told nothing.
			const range = document.createRange();
			range.selectNodeContents(target);
			const sel = window.getSelection();
			sel.removeAllRanges();
			sel.addRange(range);
			btn.textContent = 'Select + copy';
		}
	});
}

if (!isAuthed()) {
	setRail('off', 'Sign in to use your rail');
	els.railKey.textContent = 'Sign in';
	els.railKey.href = '/login?next=/herald';
}

build();