Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// /choreograph: compose agent gestures into a timed routine.
//
// The page owns editing and presentation only. Everything about what a routine
// *is* — validation, timing, the URL wire format, playback order — comes from
// src/runtime/choreography.js, the same module the agents API validates with
// and the avatar runtime performs with. That is what makes the preview here
// honest: the timeline is not an approximation of what the agent will do, it is
// driven by the identical player.
//
// The 3D stage reuses the gallery's shared engine (one renderer, one avatar,
// moved into the stage on demand) and nothing 3D loads until the first play.
import { SLOTS, DEFAULT_ANIMATION_MAP } from './runtime/animation-slots.js';
import {
DEFAULT_HOLD,
MAX_HOLD,
MAX_STEPS,
MIN_HOLD,
PRESET_ROUTINES,
RoutinePlayer,
decodeRoutine,
encodeRoutine,
normalizeRoutine,
resolveStepClip,
routineDuration,
slugify,
stepOffsets,
} from './runtime/choreography.js';
import { curate, CATEGORIES } from './animation-presets.js';
const MANIFEST_URL = '/animations/manifest.json';
const THUMB_BASE = '/animations/thumbs';
/** Blend between steps. Long enough to read as a transition, short enough that
* a 1s beat is still mostly the gesture itself. */
const CROSSFADE = 0.28;
/** One line per slot: what this beat reads as inside a performance. */
const SLOT_ICONS = {
idle: '🧍',
wave: '👋',
nod: '🙂',
shake: '🙅',
think: '🤔',
celebrate: '🎉',
concern: '😟',
bow: '🙇',
point: '👉',
shrug: '🤷',
fidget: '😌',
dance: '💃',
inspect: '🔍',
present: '🖐️',
sign: '✍️',
curiosity: '👀',
patience: '⏳',
manipulate: '📦',
conjure: '✨',
};
const $ = (sel, root = document) => root.querySelector(sel);
const el = (role, root = document) => root.querySelector(`[data-role="${role}"]`);
const state = {
manifest: [],
byName: new Map(),
/** Working routine: always normalized, always the source of truth. */
name: 'Welcome',
steps: [],
loop: false,
player: null,
preview: null,
raf: 0,
lastT: 0,
stagedClip: null, // clip currently mounted on the stage
/** True while a play is still binding its clips and nothing is on stage yet. */
starting: false,
/** Bumped by every start and every stop, so work that was already in flight
* when the user changed their mind can tell that it no longer owns the
* stage. Binding a cold routine takes seconds; a lot can happen in them. */
startGen: 0,
agents: null, // null = not fetched, [] = signed out or none
dragIndex: -1,
loadedFromLink: false,
boundClips: [],
};
/* ── helpers ───────────────────────────────────────────────────────────── */
function escapeHtml(s) {
return String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
}
/** The working routine as the rest of the platform sees it, or null if empty. */
function currentRoutine() {
if (!state.steps.length) return null;
try {
return normalizeRoutine({ name: state.name, steps: state.steps, loop: state.loop });
} catch {
return null;
}
}
function clipLabel(clipName) {
return state.byName.get(clipName)?.label || clipName;
}
function stepClip(step) {
return resolveStepClip(step, null);
}
/* ── data ──────────────────────────────────────────────────────────────── */
async function loadManifest() {
try {
const res = await fetch(MANIFEST_URL, { headers: { accept: 'application/json' } });
if (!res.ok) throw new Error(`${MANIFEST_URL} responded ${res.status}`);
const manifest = await res.json();
state.manifest = Array.isArray(manifest) ? manifest : [];
state.byName = new Map(state.manifest.map((c) => [c.name, c]));
} catch (err) {
// The clip library only supplies labels, posters and the per-step clip
// picker. Composing, previewing and saving all work without it, so this
// degrades to slot names rather than taking the page down.
setStatus(`Clip labels unavailable (${err.message}). Slot names still work.`);
}
renderPalette();
renderSteps();
}
/**
* The signed-in user's agents. Being signed out is the ordinary case here, not
* an error: the whole page works without an account, and only the save panel
* needs to know. `/api/auth/me` answers 200 either way, so asking it first keeps
* an anonymous visitor's console clean instead of printing a red 401 from
* `/api/agents` on every first paint.
*/
async function loadAgents() {
try {
const { apiFetch, noteSession } = await import('./api.js');
const who = await apiFetch('/api/auth/me', {
allowAnonymous: true,
headers: { accept: 'application/json' },
});
const user = who.ok ? (await who.json()).user : null;
noteSession(!!user);
if (!user) {
state.agents = [];
renderSave();
return;
}
// allowAnonymous keeps a session that expired mid-edit from bouncing the
// composer to /login: the save panel simply falls back to its signed-out
// state and the routine on screen survives.
const res = await apiFetch('/api/agents', {
allowAnonymous: true,
headers: { accept: 'application/json' },
});
state.agents = res.ok ? ((await res.json()).agents ?? []) : [];
} catch {
state.agents = [];
}
renderSave();
}
/* ── render: presets ───────────────────────────────────────────────────── */
function renderPresets() {
el('presets').innerHTML = PRESET_ROUTINES.map((preset) => {
const seconds = routineDuration(normalizeRoutine(preset));
const beats = preset.steps
.map((s) => `<span class="ch-preset-beat">${SLOT_ICONS[s.slot] || '🎞️'} ${escapeHtml(s.slot)}</span>`)
.join('<span class="ch-preset-arrow" aria-hidden="true">→</span>');
return `
<button type="button" class="ch-preset" role="listitem" data-preset="${escapeHtml(preset.id)}">
<span class="ch-preset-head">
<span class="ch-preset-name">${escapeHtml(preset.name)}</span>
<span class="ch-preset-time">${seconds}s${preset.loop ? ' · loops' : ''}</span>
</span>
<span class="ch-preset-blurb">${escapeHtml(preset.blurb)}</span>
<span class="ch-preset-beats">${beats}</span>
</button>`;
}).join('');
}
/* ── render: palette ───────────────────────────────────────────────────── */
function renderPalette() {
el('palette').innerHTML = SLOTS.map((slot) => {
const clip = DEFAULT_ANIMATION_MAP[slot];
return `
<button type="button" class="ch-chip" role="listitem" data-slot="${escapeHtml(slot)}"
title="Add ${escapeHtml(slot)} (${escapeHtml(clipLabel(clip))})">
<span class="ch-chip-thumb">
<span class="ch-chip-icon" aria-hidden="true">${SLOT_ICONS[slot] || '🎞️'}</span>
<img src="${THUMB_BASE}/${encodeURIComponent(clip)}.webp" alt="" loading="lazy"
decoding="async" width="160" height="160" />
</span>
<span class="ch-chip-label">${escapeHtml(slot)}</span>
<span class="ch-chip-add" aria-hidden="true">+</span>
</button>`;
}).join('');
// The emoji stands in until the poster paints, then gets out of the way.
for (const img of el('palette').querySelectorAll('img')) {
const icon = img.previousElementSibling;
if (img.complete && img.naturalWidth > 0) icon?.remove();
else {
img.addEventListener('load', () => icon?.remove(), { once: true });
img.addEventListener('error', () => img.remove(), { once: true });
}
}
}
/* ── render: steps ─────────────────────────────────────────────────────── */
let clipOptionsHtml = '';
function buildClipOptions() {
if (clipOptionsHtml) return clipOptionsHtml;
const { groups } = curate(state.manifest);
const order = new Map(CATEGORIES.map((c, i) => [c.key, i]));
const sorted = [...groups].sort((a, b) => (order.get(a.key) ?? 99) - (order.get(b.key) ?? 99));
clipOptionsHtml = sorted
.map(
(g) =>
`<optgroup label="${escapeHtml(`${g.icon} ${g.label}`)}">${g.items
.map(
(item) =>
`<option value="${escapeHtml(item.name)}">${escapeHtml(item.label || item.name)}</option>`,
)
.join('')}</optgroup>`,
)
.join('');
return clipOptionsHtml;
}
function stepRowHtml(step, i) {
const clip = stepClip(step);
const isDefault = !step.clip;
return `
<li class="ch-step" data-index="${i}" draggable="true">
<span class="ch-step-grip" aria-hidden="true" title="Drag to reorder">⠿</span>
<span class="ch-step-num">${i + 1}</span>
<span class="ch-step-icon" aria-hidden="true">${SLOT_ICONS[step.slot] || '🎞️'}</span>
<span class="ch-step-body">
<span class="ch-step-slot">${escapeHtml(step.slot)}</span>
<label class="ch-step-clip">
<span class="ch-sr-only">Clip for step ${i + 1}</span>
<select class="ch-select ch-select--sm" data-act="clip" data-index="${i}">
${buildClipOptions()}
</select>
</label>
${isDefault ? '' : '<span class="ch-step-pin" title="This step pins a clip instead of following the agent\'s own mapping">pinned</span>'}
</span>
<span class="ch-step-timing">
<label class="ch-step-hold">
<span class="ch-sr-only">Hold for step ${i + 1}, in seconds</span>
<input type="range" class="ch-range" data-act="hold" data-index="${i}"
min="${MIN_HOLD}" max="${MAX_HOLD}" step="0.1" value="${step.hold}" />
<output class="ch-step-secs">${step.hold.toFixed(1)}s</output>
</label>
<label class="ch-step-speed">
<span class="ch-sr-only">Speed for step ${i + 1}</span>
<select class="ch-select ch-select--xs" data-act="speed" data-index="${i}">
${[0.5, 0.75, 1, 1.25, 1.5, 2]
.map(
(s) =>
`<option value="${s}"${s === step.speed ? ' selected' : ''}>${s}×</option>`,
)
.join('')}
</select>
</label>
</span>
<span class="ch-step-actions">
<button type="button" class="ch-icon-btn ch-icon-btn--xs" data-act="up" data-index="${i}"
title="Move up" aria-label="Move step ${i + 1} up"${i === 0 ? ' disabled' : ''}>↑</button>
<button type="button" class="ch-icon-btn ch-icon-btn--xs" data-act="down" data-index="${i}"
title="Move down" aria-label="Move step ${i + 1} down">↓</button>
<button type="button" class="ch-icon-btn ch-icon-btn--xs ch-icon-btn--danger" data-act="remove"
data-index="${i}" title="Remove" aria-label="Remove step ${i + 1}">✕</button>
</span>
<span class="ch-sr-only" data-role="step-clip-name">${escapeHtml(clipLabel(clip))}</span>
</li>`;
}
function renderSteps() {
const host = el('steps');
const empty = el('steps-empty');
host.innerHTML = state.steps.map(stepRowHtml).join('');
host.hidden = !state.steps.length;
empty.hidden = state.steps.length > 0;
// Selects cannot carry their value through innerHTML, so set them after.
for (const [i, step] of state.steps.entries()) {
const select = host.querySelector(`select[data-act="clip"][data-index="${i}"]`);
if (select) select.value = stepClip(step);
}
const last = host.querySelector('.ch-step:last-child [data-act="down"]');
if (last) last.disabled = true;
renderMeta();
renderTimeline();
renderExports();
}
function renderMeta() {
const routine = currentRoutine();
el('step-count').textContent = String(state.steps.length);
const seconds = routine ? routineDuration(routine) : 0;
el('meta-duration').textContent = seconds.toFixed(1);
el('duration').textContent = seconds.toFixed(1);
el('routine-id').textContent = slugify(state.name || 'routine');
const hasSteps = state.steps.length > 0;
for (const role of ['play', 'restart', 'loop']) el(role).disabled = !hasSteps;
el('timeline-empty').hidden = hasSteps;
}
/* ── render: timeline ──────────────────────────────────────────────────── */
function renderTimeline() {
const routine = currentRoutine();
const track = el('timeline-track');
const timeline = el('timeline');
if (!routine) {
track.innerHTML = '';
el('playhead').hidden = true;
timeline.setAttribute('aria-valuemax', '0');
timeline.setAttribute('aria-valuenow', '0');
timeline.setAttribute('aria-valuetext', 'Empty routine');
return;
}
const total = routineDuration(routine) || 1;
const active = state.player?.index ?? -1;
track.innerHTML = routine.steps
.map((step, i) => {
const span = step.hold / (step.speed || 1);
const pct = (span / total) * 100;
return `
<button type="button" class="ch-seg${i === active ? ' is-active' : ''}" style="width:${pct}%"
data-seg="${i}" title="${escapeHtml(step.slot)} · ${span.toFixed(1)}s"
aria-label="Jump to step ${i + 1}, ${escapeHtml(step.slot)}">
<span class="ch-seg-icon" aria-hidden="true">${SLOT_ICONS[step.slot] || '🎞️'}</span>
<span class="ch-seg-label">${escapeHtml(step.slot)}</span>
</button>`;
})
.join('');
timeline.setAttribute('aria-valuemax', String(total));
renderPlayhead();
}
function renderPlayhead() {
const head = el('playhead');
const routine = currentRoutine();
if (!routine || !state.player) {
head.hidden = true;
return;
}
const total = routineDuration(routine) || 1;
const t = state.player.time;
head.hidden = false;
head.style.left = `${Math.min(100, (t / total) * 100)}%`;
el('time').textContent = t.toFixed(1);
const timeline = el('timeline');
timeline.setAttribute('aria-valuenow', String(t));
const step = routine.steps[state.player.index];
timeline.setAttribute(
'aria-valuetext',
step ? `${t.toFixed(1)} seconds, ${step.slot}` : `${t.toFixed(1)} seconds`,
);
}
function highlightActive() {
const active = state.player?.index ?? -1;
for (const seg of el('timeline-track').querySelectorAll('.ch-seg')) {
seg.classList.toggle('is-active', Number(seg.dataset.seg) === active);
}
for (const row of el('steps').querySelectorAll('.ch-step')) {
row.classList.toggle('is-active', Number(row.dataset.index) === active);
}
}
/* ── render: exports ───────────────────────────────────────────────────── */
function renderExports() {
const routine = currentRoutine();
const json = routine
? JSON.stringify({ choreographies: [routine] }, null, 2)
: '// Add a step to see the payload.';
$('code', el('json-code')).textContent = json;
const id = routine?.id || 'routine';
const snippet = routine
? `<agent-3d agent="YOUR_AGENT_ID"></agent-3d>\n\n<script type="module">\n const el = document.querySelector('agent-3d');\n // Saved on the agent, so it plays by name:\n el.playRoutine(${JSON.stringify(id)});\n<\/script>`
: '// Add a step to see the snippet.';
$('code', el('embed-code')).textContent = snippet;
syncUrl();
}
function renderSave() {
const panel = el('save-panel');
const signedOut = el('save-signedout');
const agents = state.agents;
if (agents === null) {
// Still loading: show neither rather than flashing "sign in" at someone
// who is in fact signed in.
panel.hidden = true;
signedOut.hidden = true;
return;
}
if (!agents.length) {
panel.hidden = true;
signedOut.hidden = false;
return;
}
signedOut.hidden = true;
panel.hidden = false;
const select = el('agent-select');
if (select.dataset.filled !== String(agents.length)) {
select.dataset.filled = String(agents.length);
select.innerHTML = agents
.map((a) => `<option value="${escapeHtml(a.id)}">${escapeHtml(a.name || a.id)}</option>`)
.join('');
}
renderSavedRoutines();
}
/** Routines already stored on the selected agent, each loadable in one click. */
function renderSavedRoutines() {
const box = el('saved');
const agent = (state.agents || []).find((a) => a.id === el('agent-select')?.value);
const list = Array.isArray(agent?.meta?.choreographies) ? agent.meta.choreographies : [];
if (!list.length) {
box.hidden = true;
return;
}
box.hidden = false;
el('saved-list').innerHTML = list
.map((r, i) => {
let seconds = 0;
try {
seconds = routineDuration(normalizeRoutine(r));
} catch {
return '';
}
return `
<button type="button" class="ch-saved-chip" data-saved="${i}">
<span class="ch-saved-name">${escapeHtml(r.name || r.id)}</span>
<span class="ch-saved-meta">${r.steps?.length || 0} steps · ${seconds}s</span>
</button>`;
})
.join('');
}
/* ── editing ───────────────────────────────────────────────────────────── */
/** Every mutation funnels through here so the URL, exports and stage agree. */
function commit({ restage = true } = {}) {
// Any edit answers the "your link was broken" notice: the routine on screen
// is now the user's own, so the warning about the one they arrived with is
// stale.
setNotice('');
renderSteps();
if (restage) restageIfPlaying();
highlightActive();
}
function addStep(slot) {
if (state.steps.length >= MAX_STEPS) {
setStatus(`A routine holds at most ${MAX_STEPS} steps.`);
return;
}
state.steps.push({ slot, clip: null, hold: DEFAULT_HOLD, speed: 1 });
commit({ restage: false });
// Adding a step should show you the step you just added, not restart the
// routine from the top.
playFrom(state.steps.length - 1);
setStatus(`Added ${slot}. ${state.steps.length} steps.`);
}
function removeStep(i) {
const [removed] = state.steps.splice(i, 1);
if (!state.steps.length) stopPlayback();
commit();
setStatus(`Removed ${removed?.slot ?? 'step'}.`);
}
function moveStep(from, to) {
if (to < 0 || to >= state.steps.length) return;
const [step] = state.steps.splice(from, 1);
state.steps.splice(to, 0, step);
commit();
setStatus(`Moved ${step.slot} to position ${to + 1}.`);
// Keep the keyboard on the button the user just pressed.
el('steps')
.querySelector(`.ch-step[data-index="${to}"] [data-act="${to > from ? 'down' : 'up'}"]`)
?.focus();
}
/* ── playback ──────────────────────────────────────────────────────────── */
function setStatus(text) {
el('stage-status').textContent = text;
}
/**
* The one message that gets its own visible slot. `setStatus` writes to a
* screen-reader live region, which is right for play/pause chatter and wrong
* for "your link was broken": a sighted user arriving on a bad share link would
* otherwise see a routine they did not ask for and no explanation.
* @param {string} text (empty to clear)
*/
function setNotice(text) {
const box = el('notice');
box.textContent = text;
box.hidden = !text;
}
function setStageState(name, detail = '') {
el('stage-empty').hidden = name !== 'empty';
el('stage-loading').hidden = name !== 'loading';
el('stage-error').hidden = name !== 'error';
if (name === 'error' && detail) el('stage-error-title').textContent = detail;
}
async function getPreview() {
if (!state.preview) {
const mod = await import('./animations-live-preview.js');
state.preview = mod.getLivePreview();
}
return state.preview;
}
/** Manifest def for a step's clip, or null when the clip is not in the library. */
function defFor(step) {
const clip = stepClip(step);
const def = state.byName.get(clip);
return def ? { id: clip, source: 'curated', url: def.url, loop: def.loop !== false } : null;
}
/**
* Mount a step on the stage. Steps after the first crossfade into place, and
* the camera is framed once for the whole routine so it does not jog at cuts.
*/
async function stageStep(step, { crossfade = true } = {}) {
const def = defFor(step);
if (!def) {
setStageState('error', `"${stepClip(step)}" is not in the clip manifest.`);
return;
}
const gen = state.startGen;
const preview = await getPreview();
const bounds = state.boundClips || [];
try {
await preview.play(el('stage'), def, {
speed: step.speed,
crossfade: crossfade && state.stagedClip ? CROSSFADE : 0,
frameWith: bounds.filter(Boolean),
});
// Stopped or restarted while this clip was binding: whatever is on the
// stage now is the routine the user asked for, so leave it alone.
if (gen !== state.startGen) return;
state.stagedClip = def.id;
setStageState('none');
el('stage-badge').hidden = false;
el('stage-badge').textContent = `${step.slot} · ${clipLabel(def.id)}`;
} catch (err) {
if (gen !== state.startGen) return;
setStageState('error', err?.message ? `Preview failed: ${err.message}` : undefined);
}
}
/** Bind every clip in the routine up front so no cut waits on a fetch. */
async function prepareClips(routine) {
const preview = await getPreview();
const defs = routine.steps.map(defFor).filter(Boolean);
state.boundClips = await preview.prepare(defs);
}
/**
* Cue the routine and start it.
* @param {number} [fromIndex] step to open on
* @returns {Promise<boolean>} false when a newer start or a stop took the stage
* before this one finished binding, so callers can skip their follow-up.
*/
async function startPlayback(fromIndex = 0) {
const routine = currentRoutine();
if (!routine) return false;
stopRaf();
el('stage-loading-text').textContent =
state.stagedClip ? 'Cueing the routine…' : 'Retargeting the routine…';
if (!state.stagedClip) setStageState('loading');
// Flip the transport before the await. Binding every clip in the routine can
// take seconds on a cold first play, and a play button that still reads "▶"
// while the stage spins reads as a click that did not register.
setPlayButton(true);
state.starting = true;
const gen = ++state.startGen;
await prepareClips(routine);
if (gen !== state.startGen) return false;
state.starting = false;
state.player = new RoutinePlayer(routine, {
loop: state.loop,
onStep: (step) => {
stageStep(step);
highlightActive();
renderTimeline();
},
onTick: () => renderPlayhead(),
onEnd: () => {
setPlayButton(false);
setStatus('Routine finished.');
renderPlayhead();
},
});
state.player.start();
if (fromIndex > 0) state.player.seek(stepOffsets(routine)[fromIndex] ?? 0);
setPlayButton(true);
startRaf();
setStatus(`Playing ${routine.name}, ${routine.steps.length} steps.`);
return true;
}
function playFrom(index) {
startPlayback(index);
}
function stopPlayback() {
stopRaf();
state.startGen++;
state.starting = false;
state.player = null;
state.stagedClip = null;
state.preview?.stop();
setPlayButton(false);
setStageState('empty');
el('stage-badge').hidden = true;
el('playhead').hidden = true;
el('time').textContent = '0.0';
highlightActive();
}
/** Re-cue the stage after an edit, but only if something was already playing. */
function restageIfPlaying() {
if (!state.player) return;
const wasPlaying = state.player.playing;
const at = state.player.time;
const routine = currentRoutine();
if (!routine) {
stopPlayback();
return;
}
startPlayback(0).then((ok) => {
if (!ok || !state.player) return;
state.player.seek(Math.min(at, routineDuration(routine)));
if (!wasPlaying) {
state.player.pause();
setPlayButton(false);
}
renderPlayhead();
});
}
function setPlayButton(playing) {
const btn = el('play');
btn.textContent = playing ? '❙❙' : '▶';
btn.setAttribute('aria-label', playing ? 'Pause routine' : 'Play routine');
btn.title = playing ? 'Pause (Space)' : 'Play (Space)';
}
function startRaf() {
stopRaf();
state.lastT = performance.now();
const tick = () => {
state.raf = requestAnimationFrame(tick);
const now = performance.now();
const dt = Math.min(0.1, (now - state.lastT) / 1000);
state.lastT = now;
state.player?.update(dt);
};
state.raf = requestAnimationFrame(tick);
}
function stopRaf() {
cancelAnimationFrame(state.raf);
state.raf = 0;
}
function togglePlay() {
if (!state.steps.length) return;
if (state.starting) {
// The transport already reads "pause" while the clips bind, so pressing it
// has to call that load off. Without this it would queue a second copy of
// the same load behind the first and leave the user watching the spinner
// they were trying to dismiss.
stopPlayback();
setStatus('Stopped before the routine started.');
return;
}
if (!state.player) {
startPlayback(0);
return;
}
if (state.player.playing) {
state.player.pause();
state.preview?.setPaused(true);
setPlayButton(false);
setStatus('Paused.');
} else {
// A player parked at the very end restarts rather than sitting still.
if (state.player.time >= state.player.duration) state.player.start();
else state.player.resume();
state.preview?.setPaused(false);
setPlayButton(true);
setStatus('Playing.');
}
}
function scrubTo(seconds) {
const routine = currentRoutine();
if (!routine) return;
if (!state.player) {
startPlayback(0).then((ok) => {
if (!ok) return;
state.player?.seek(seconds);
state.player?.pause();
setPlayButton(false);
renderPlayhead();
});
return;
}
state.player.seek(seconds);
renderPlayhead();
highlightActive();
}
/* ── url state ─────────────────────────────────────────────────────────── */
/** The query key a routine travels in. */
const ROUTINE_PARAM = 'r';
/**
* The raw `?r=` value, read without decoding it.
*
* `encodeRoutine` already escapes the routine name, and the `|` `,` `:` `*` `@`
* it separates steps with are all legal in a query string, so the encoded
* routine belongs in the URL verbatim. Handing it to `URLSearchParams` instead
* would escape its percent signs a second time, so the share link for a routine
* called "The pitch" read `?r=The%2520pitch|…`, and reading it back through
* `URLSearchParams.get` would strip exactly one layer, turning a name that
* legitimately contains an escaped `|` into a raw bar that splits the routine on
* the wrong character.
*
* @returns {string|null}
*/
function readEncodedRoutine() {
for (const pair of window.location.search.replace(/^\?/, '').split('&')) {
if (pair.startsWith(`${ROUTINE_PARAM}=`)) return pair.slice(ROUTINE_PARAM.length + 1);
}
return null;
}
function syncUrl() {
const routine = currentRoutine();
const url = new URL(window.location.href);
url.searchParams.delete(ROUTINE_PARAM);
const others = url.searchParams.toString();
const mine = routine ? `${ROUTINE_PARAM}=${encodeRoutine(routine)}` : '';
url.search = [others, mine].filter(Boolean).join('&');
window.history.replaceState(null, '', url);
}
function loadRoutine(routine, { announce = true } = {}) {
const normalized = normalizeRoutine(routine);
state.name = normalized.name;
state.steps = normalized.steps.map((s) => ({ ...s }));
state.loop = normalized.loop;
el('name').value = state.name;
el('loop').setAttribute('aria-pressed', String(state.loop));
el('loop').classList.toggle('is-on', state.loop);
commit({ restage: false });
if (announce) setStatus(`Loaded ${normalized.name}: ${normalized.steps.length} steps.`);
}
/**
* Load the routine in `?r=`, if there is one.
* @returns {string|null} an error to show the user, or null when there was
* nothing to load or it loaded cleanly. Returning the message rather than
* announcing it lets the caller decide the final wording: a bad link falls
* back to a preset, and "could not read your link" plus "here is a starting
* point instead" belong in one sentence, not two that overwrite each other.
*/
function applyDeepLink() {
const encoded = readEncodedRoutine();
if (!encoded) return null;
// Links shared before the studio wrote its own query carry one extra layer of
// escaping. A value that does not parse as-is gets one decode and a second
// chance, so every link that used to work still does.
const candidates = [encoded];
try {
const once = decodeURIComponent(encoded);
if (once !== encoded) candidates.push(once);
} catch {
// A lone percent sign means it was never double-escaped: nothing to retry.
}
let firstError = null;
for (const candidate of candidates) {
try {
loadRoutine(decodeRoutine(candidate), { announce: false });
setStatus(`Loaded a shared routine: ${state.name}.`);
state.loadedFromLink = true;
return null;
} catch (err) {
firstError ??= err.message;
}
}
return firstError;
}
/* ── saving ────────────────────────────────────────────────────────────── */
async function copy(text, btn, label = 'Copy') {
try {
await navigator.clipboard.writeText(text);
btn.textContent = 'Copied';
} catch {
btn.textContent = 'Copy blocked, select it by hand';
}
setTimeout(() => {
btn.textContent = label;
}, 1800);
}
async function saveToAgent() {
const routine = currentRoutine();
if (!routine) return;
const btn = el('save');
const status = el('save-status');
const agentId = el('agent-select').value;
const agent = (state.agents || []).find((a) => a.id === agentId);
if (!agentId) return;
// Merge by id: saving "welcome" twice replaces it rather than stacking a
// second copy the owner would have to hunt down and delete.
const existing = Array.isArray(agent?.meta?.choreographies) ? agent.meta.choreographies : [];
const merged = existing.filter((r) => slugify(r?.id || r?.name || '') !== routine.id);
merged.push(routine);
btn.disabled = true;
status.textContent = 'Saving…';
status.className = 'ch-save-status';
try {
const { apiFetch } = await import('./api.js');
const res = await apiFetch(`/api/agents/${agentId}/animations`, {
method: 'PUT',
headers: { 'content-type': 'application/json' },
credentials: 'include',
body: JSON.stringify({ choreographies: merged }),
});
if (!res.ok) {
const body = await res.json().catch(() => ({}));
throw new Error(body.error_description || body.error || `HTTP ${res.status}`);
}
const saved = await res.json();
// Keep the local copy in step so a second save merges against the truth.
if (agent) {
agent.meta = { ...(agent.meta || {}), choreographies: saved.choreographies || [] };
}
const count = (saved.choreographies || []).length;
status.innerHTML = `Saved as <code>${escapeHtml(routine.id)}</code>. <a href="/a/${escapeHtml(
agentId,
)}">Open ${escapeHtml(agent?.name || 'the agent')}</a> · ${count} routine${
count === 1 ? '' : 's'
} in total.`;
status.className = 'ch-save-status is-ok';
renderSavedRoutines();
} catch (err) {
status.textContent = `Could not save: ${err.message}`;
status.className = 'ch-save-status is-err';
} finally {
btn.disabled = false;
}
}
/* ── events ────────────────────────────────────────────────────────────── */
function wire() {
el('presets').addEventListener('click', (e) => {
const btn = e.target.closest('[data-preset]');
if (!btn) return;
const preset = PRESET_ROUTINES.find((p) => p.id === btn.dataset.preset);
if (!preset) return;
loadRoutine(preset);
startPlayback(0);
});
el('palette').addEventListener('click', (e) => {
const chip = e.target.closest('[data-slot]');
if (chip) addStep(chip.dataset.slot);
});
el('name').addEventListener('input', (e) => {
state.name = e.target.value.slice(0, 40);
renderMeta();
renderExports();
});
// Step edits. One delegated listener for the whole list: rows are re-rendered
// on every change, so per-row listeners would leak with each edit.
const steps = el('steps');
steps.addEventListener('click', (e) => {
const btn = e.target.closest('[data-act]');
if (!btn) return;
const i = Number(btn.dataset.index);
if (btn.dataset.act === 'remove') removeStep(i);
else if (btn.dataset.act === 'up') moveStep(i, i - 1);
else if (btn.dataset.act === 'down') moveStep(i, i + 1);
});
steps.addEventListener('input', (e) => {
const input = e.target.closest('[data-act="hold"]');
if (!input) return;
const i = Number(input.dataset.index);
state.steps[i].hold = Number(input.value);
// Live feedback while dragging, without re-rendering the row under the
// pointer (which would drop the drag).
input.parentElement.querySelector('.ch-step-secs').textContent =
`${state.steps[i].hold.toFixed(1)}s`;
renderMeta();
renderTimeline();
renderExports();
});
steps.addEventListener('change', (e) => {
const control = e.target.closest('[data-act]');
if (!control) return;
const i = Number(control.dataset.index);
if (control.dataset.act === 'clip') {
const picked = control.value;
state.steps[i].clip = picked === DEFAULT_ANIMATION_MAP[state.steps[i].slot] ? null : picked;
commit();
playFrom(i);
} else if (control.dataset.act === 'speed') {
state.steps[i].speed = Number(control.value);
commit();
} else if (control.dataset.act === 'hold') {
commit();
}
});
// Drag to reorder. The keyboard equivalent is the ↑/↓ buttons on every row,
// so reordering never requires a pointer.
steps.addEventListener('dragstart', (e) => {
const row = e.target.closest('.ch-step');
if (!row) return;
state.dragIndex = Number(row.dataset.index);
row.classList.add('is-dragging');
e.dataTransfer.effectAllowed = 'move';
// Firefox refuses to start a drag without payload.
e.dataTransfer.setData('text/plain', String(state.dragIndex));
});
steps.addEventListener('dragover', (e) => {
const row = e.target.closest('.ch-step');
if (!row || state.dragIndex < 0) return;
e.preventDefault();
e.dataTransfer.dropEffect = 'move';
for (const r of steps.querySelectorAll('.ch-step')) r.classList.remove('is-drop-target');
row.classList.add('is-drop-target');
});
steps.addEventListener('drop', (e) => {
const row = e.target.closest('.ch-step');
if (!row || state.dragIndex < 0) return;
e.preventDefault();
const to = Number(row.dataset.index);
if (to !== state.dragIndex) moveStep(state.dragIndex, to);
state.dragIndex = -1;
});
steps.addEventListener('dragend', () => {
state.dragIndex = -1;
for (const r of steps.querySelectorAll('.ch-step')) {
r.classList.remove('is-dragging', 'is-drop-target');
}
});
el('play').addEventListener('click', togglePlay);
el('restart').addEventListener('click', () => startPlayback(0));
el('loop').addEventListener('click', (e) => {
state.loop = !state.loop;
e.currentTarget.setAttribute('aria-pressed', String(state.loop));
e.currentTarget.classList.toggle('is-on', state.loop);
if (state.player) state.player.loop = state.loop;
renderExports();
setStatus(state.loop ? 'Looping.' : 'Playing once.');
});
el('stage-retry').addEventListener('click', () => startPlayback(0));
// The timeline is both a scrubber and a step picker: clicking a segment jumps
// to that beat, dragging anywhere scrubs.
const timeline = el('timeline');
const seek = (clientX) => {
const routine = currentRoutine();
if (!routine) return;
const rect = timeline.getBoundingClientRect();
const ratio = Math.min(1, Math.max(0, (clientX - rect.left) / rect.width));
scrubTo(ratio * routineDuration(routine));
};
timeline.addEventListener('pointerdown', (e) => {
timeline.setPointerCapture(e.pointerId);
timeline.dataset.scrubbing = '1';
seek(e.clientX);
});
timeline.addEventListener('pointermove', (e) => {
if (timeline.dataset.scrubbing) seek(e.clientX);
});
const endScrub = (e) => {
delete timeline.dataset.scrubbing;
if (e.pointerId != null && timeline.hasPointerCapture?.(e.pointerId)) {
timeline.releasePointerCapture(e.pointerId);
}
};
timeline.addEventListener('pointerup', endScrub);
timeline.addEventListener('pointercancel', endScrub);
timeline.addEventListener('keydown', (e) => {
const routine = currentRoutine();
if (!routine) return;
const total = routineDuration(routine);
const at = state.player?.time ?? 0;
const moves = { ArrowLeft: -0.25, ArrowRight: 0.25, Home: -total, End: total };
if (!(e.key in moves)) return;
e.preventDefault();
scrubTo(Math.min(total, Math.max(0, e.key === 'Home' ? 0 : e.key === 'End' ? total : at + moves[e.key])));
});
el('save').addEventListener('click', saveToAgent);
el('agent-select').addEventListener('change', renderSavedRoutines);
el('saved-list').addEventListener('click', (e) => {
const chip = e.target.closest('[data-saved]');
if (!chip) return;
const agent = (state.agents || []).find((a) => a.id === el('agent-select').value);
const routine = agent?.meta?.choreographies?.[Number(chip.dataset.saved)];
if (!routine) return;
try {
loadRoutine(routine);
startPlayback(0);
} catch (err) {
setStatus(`That saved routine could not be loaded (${err.message}).`);
}
});
const shareLink = (e) => {
syncUrl();
copy(window.location.href, e.currentTarget, 'Copy share link');
};
el('share').addEventListener('click', shareLink);
el('share-2').addEventListener('click', shareLink);
el('copy-json').addEventListener('click', (e) =>
copy($('code', el('json-code')).textContent, e.currentTarget, 'Copy JSON'),
);
el('copy-embed').addEventListener('click', (e) =>
copy($('code', el('embed-code')).textContent, e.currentTarget, 'Copy snippet'),
);
document.addEventListener('keydown', (e) => {
// Never steal a key from a field the user is typing in.
const tag = e.target.tagName;
if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') return;
if (e.key === ' ' && state.steps.length) {
e.preventDefault();
togglePlay();
} else if (e.key === 'r' || e.key === 'R') {
if (state.steps.length) startPlayback(0);
} else if (e.key === 'Escape' && state.player) {
stopPlayback();
setStatus('Stopped.');
}
});
// Stop burning frames on a hidden tab without stomping a deliberate pause.
document.addEventListener('visibilitychange', () => {
if (document.hidden) {
stopRaf();
state.preview?.setPaused(true);
} else if (state.player?.playing) {
state.preview?.setPaused(false);
startRaf();
}
});
}
/* ── boot ──────────────────────────────────────────────────────────────── */
renderPresets();
wire();
loadManifest();
loadAgents();
const linkError = applyDeepLink();
if (!state.loadedFromLink) {
// An empty timeline is the hardest screen to start on, so the page opens on a
// real routine. Nothing 3D loads until the user presses play.
loadRoutine(PRESET_ROUTINES[0], { announce: false });
const opening = linkError
? `That shared routine could not be read (${linkError}). Loaded the Welcome routine instead.`
: 'Loaded the Welcome routine. Press play, or change any step.';
setStatus(opening);
if (linkError) setNotice(opening);
}