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
// Animation preset gallery for the /pose studio.
//
// Renders a curated, searchable gallery of ready-to-apply motion clips. Click a
// card and the clip retargets onto the loaded rig and plays live in the
// viewport (the shared 3D stage is the preview surface — one figure, like
// Mixamo, rather than N video thumbnails). A transport bar then lets the user
// scrub speed, toggle loop, stop, and export an animated GLB with the motion
// baked in.
//
// This controller owns only its own AnimationMixer and DOM; it borrows the rig
// and render loop from the host (pose-studio) through the callbacks passed to
// the constructor, and signals the host when a preview takes over the figure so
// the keyframe timeline can yield.
import { AnimationClip, AnimationMixer, LoopOnce, LoopRepeat } from 'three';
import { GLTFExporter } from 'three/addons/exporters/GLTFExporter.js';
import { curate } from './animation-presets.js';
import { buildFingerspellingClip, normalizeWord } from './fingerspelling.js';
import {
retargetClipToRig,
scaleClipSpeed,
parseClipJSON,
trimClip,
blendClipLoop,
MIN_COVERAGE,
} from './animation-retarget.js';
import { Modal } from './shared/modal.js';
import { log } from './shared/log.js';
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
const MANIFEST_URL = '/animations/manifest.json';
// A rig needs a real share of the canonical skeleton before presets read as
// performances rather than twitches. Mirrors AnimationManager's bar.
const MIN_RIG_BONES = 8;
// Text-to-animation job polling (POST /api/forge-motion → poll until the clip
// is ready). The motion model runs ~10–30s on a warm GPU container.
const GEN_POLL_INTERVAL_MS = 2500;
const GEN_MAX_POLL_MS = 90 * 1000;
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const el = (tag, attrs = {}, children = []) => {
const node = document.createElement(tag);
for (const [k, v] of Object.entries(attrs)) {
if (k === 'class') node.className = v;
else if (k === 'text') node.textContent = v;
else if (k === 'html') node.innerHTML = v;
else if (k.startsWith('on') && typeof v === 'function')
node.addEventListener(k.slice(2), v);
else if (v !== false && v != null) node.setAttribute(k, v);
}
for (const child of Array.isArray(children) ? children : [children]) {
if (child == null) continue;
node.appendChild(typeof child === 'string' ? document.createTextNode(child) : child);
}
return node;
};
export class AnimationLibrary {
/**
* @param {{
* host: HTMLElement,
* getRig: () => object|null,
* getAvatarId?: () => string|null,
* onPreviewStart?: () => void,
* onPreviewStop?: () => void,
* setStatus?: (msg: string, kind?: string) => void,
* }} opts
*/
constructor(opts) {
this.host = opts.host;
this.getRig = opts.getRig;
this.getAvatarId = opts.getAvatarId || (() => null);
this.onPreviewStart = opts.onPreviewStart || (() => {});
this.onPreviewStop = opts.onPreviewStop || (() => {});
this.setStatus = opts.setStatus || (() => {});
/** @type {Array} curated manifest defs (with category) */
this._defs = [];
/** @type {Map<string, import('three').AnimationClip>} canonical clips by name */
this._clipCache = new Map();
/** @type {string} '' = all categories */
this._filterCat = '';
this._query = '';
this._mixer = null;
this._mixerRoot = null;
this._action = null;
this._activeName = null;
this._activeDef = null;
this._speed = 1;
this._previewing = false;
this._paused = false;
this._scrubbing = false;
this._state = 'loading';
// Trim/blend/loop edits, applied to the active clip before preview,
// export, and save. `_baseClip` is the untrimmed canonical clip the
// active def resolved to; edits are recomputed from it, never baked in
// place, so adjusting a slider always starts from the original motion.
this._baseClip = null;
this._trimStart = 0;
this._trimEnd = null;
this._blendMs = 0;
this._loopOn = true;
this._editDebounce = null;
// Resolves once mount() has finished loading the manifest (success or
// failure) — openByName() awaits this so a ?anim=<preset> deep-link works
// even before the gallery has rendered.
this._readyResolve = null;
this._ready = new Promise((resolve) => {
this._readyResolve = resolve;
});
// Text-to-animation job state (token-based abort like the forge panels).
this._genToken = 0;
this._genTimer = null;
// Resolved DOM refs (built in _renderShell).
this._refs = {};
}
// ── Lifecycle ───────────────────────────────────────────────────────────
async mount() {
this._renderShell();
this._setState('loading');
try {
const res = await fetch(MANIFEST_URL, { cache: 'no-cache' });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const manifest = await res.json();
if (!Array.isArray(manifest) || manifest.length === 0)
throw new Error('empty manifest');
this._curated = curate(manifest);
this._defs = [
this._curated.featured,
this._curated.groups.flatMap((g) => g.items),
].flat();
this._buildCategoryChips();
this._evaluateRig();
} catch (err) {
log.warn('[AnimationLibrary] manifest load failed:', err.message);
this._setState('error-load');
} finally {
this._readyResolve?.();
}
}
/**
* Open a preset by its manifest name and play it on the current rig. This is
* the ?anim= deep-link path for built-in library clips (keyed by name, e.g.
* "idle" or "av-boxer-dance") — the counterpart to PoseLibrary.openById() for
* saved community clips, which are keyed by API UUID. Waits for the manifest
* to finish loading first. Throws if no preset carries that name; when no
* compatible rig is loaded, preview() surfaces its own "load an avatar"
* guidance rather than throwing.
* @param {string} name manifest clip name
*/
async openByName(name) {
await this._ready;
let def = this._defs.find((d) => d.name === name);
if (!def) def = await this._lookupFullLibrary(name);
if (!def) throw new Error(`No built-in animation named “${name}”`);
return this.preview(def);
}
/**
* Resolve a full-library clip def by name. The /animations gallery
* deep-links R2-hosted clips (mx-* names) that aren't in the curated
* manifest; their defs carry an absolute CDN url that preview()/_loadClip()
* fetch like any other. Returns null when the library doesn't know the
* name either (including before the library has been uploaded).
*
* Asks the endpoint for the single name rather than downloading the whole
* manifest to find one entry in it: the catalog is thousands of clips and
* growing with every seeding batch, so the unfiltered response is over a
* megabyte of JSON to resolve about three kilobytes of it.
* @param {string} name
*/
async _lookupFullLibrary(name) {
try {
const res = await fetch(`/api/animations/library?name=${encodeURIComponent(name)}`);
if (!res.ok) return null;
const data = await res.json();
return (data.clips || []).find((d) => d.name === name) || null;
} catch {
return null;
}
}
/** Called by the host when the active rig changes (avatar load / mannequin). */
onRigChanged() {
this._genToken++; // a generation in flight was for the previous rig
this._stopGenTimer();
this._setGenBusy(false);
this.stopPreview({ silent: true });
this._disposeMixer();
if (this._defs.length) this._evaluateRig();
}
/** Tick the preview mixer. Host calls this from its render loop while previewing. */
update(dt) {
this._mixer?.update(dt);
if (!this._scrubbing) this._syncProgress();
}
/** Push the active action's clock into the transport scrubber + time label. */
_syncProgress() {
const { transportScrub, transportTime } = this._refs;
if (!transportScrub || !this._action) return;
const clip = this._action.getClip?.();
const dur = clip?.duration || 0;
if (dur <= 0) return;
// action.time wraps within [0, duration) for a looping action and clamps
// for a one-shot, so it reads as clip-local position either way.
const t = Math.max(0, Math.min(dur, this._action.time));
transportScrub.value = String(Math.round((t / dur) * 1000));
if (transportTime) transportTime.textContent = `${t.toFixed(1)} / ${dur.toFixed(1)}s`;
}
/** Seek the active clip to a 0..1 fraction and reflect it immediately. */
_seek(frac) {
if (!this._action) return;
const dur = this._action.getClip?.().duration || 0;
this._action.paused = false;
this._action.time = Math.max(0, Math.min(0.999, frac)) * dur;
this._mixer?.update(0);
if (this._paused) this._action.paused = true;
}
/** Toggle play/pause on the live preview. */
_togglePlay() {
if (!this._action) return;
this._paused = !this._paused;
this._action.paused = this._paused;
this._updatePlayIcon();
}
_updatePlayIcon() {
const btn = this._refs.transportPlay;
if (!btn) return;
btn.textContent = this._paused ? '▶' : '⏸';
btn.setAttribute('aria-label', this._paused ? 'Play' : 'Pause');
btn.title = this._paused ? 'Play' : 'Pause';
}
isPreviewing() {
return this._previewing;
}
dispose() {
this._genToken++; // abort any in-flight generation poll
this._stopGenTimer();
this.stopPreview({ silent: true });
this._disposeMixer();
this._clipCache.clear();
this.host.innerHTML = '';
}
// ── Rig capability ────────────────────────────────────────────────────────
_rigBoneCount() {
const rig = this.getRig();
return rig?.getBones?.().length || 0;
}
// Presets target rigged GLB avatars. The primitive mannequin has no skinned
// skeleton to export, so we steer the user to load a real avatar.
_evaluateRig() {
const rig = this.getRig();
if (!rig || rig.kind === 'mannequin') return this._setState('no-rig');
if (this._rigBoneCount() < MIN_RIG_BONES) return this._setState('incompatible');
this._setState('ready');
this._renderGallery();
}
// ── Shell + states ──────────────────────────────────────────────────────
_renderShell() {
this.host.innerHTML = '';
// Generate-from-text: synthesize a brand-new motion from a prompt and play
// it on the rig exactly like a preset. The capability the preset library
// can't offer — motion that doesn't pre-exist.
const genInput = el('input', {
type: 'text',
class: 'al-gen-input',
placeholder: 'Generate a motion — “waving confidently”',
'aria-label': 'Generate an animation from a text description',
autocomplete: 'off',
maxlength: '200',
});
const genBtn = el(
'button',
{ class: 'al-gen-btn', type: 'button', title: 'Generate a motion from your description' },
['✨ Generate'],
);
const submitGen = () => this.generateFromText(genInput.value);
genBtn.addEventListener('click', submitGen);
genInput.addEventListener('keydown', (e) => {
if (e.key === 'Enter') {
e.preventDefault();
submitGen();
}
});
const gen = el('div', { class: 'al-gen' }, [genInput, genBtn]);
// Fingerspell: spell any word in ASL on the avatar's right hand. Built
// locally and deterministically (src/fingerspelling.js) — no network,
// instant, and the result exports like any other clip.
const spellInput = el('input', {
type: 'text',
class: 'al-gen-input',
placeholder: 'Fingerspell in ASL — try your name',
'aria-label': 'Fingerspell a word in American Sign Language',
autocomplete: 'off',
maxlength: '40',
});
const spellBtn = el(
'button',
{ class: 'al-gen-btn', type: 'button', title: 'Spell the word letter by letter in American Sign Language' },
['🤟 Spell'],
);
const submitSpell = () => this.spellWord(spellInput.value);
spellBtn.addEventListener('click', submitSpell);
spellInput.addEventListener('keydown', (e) => {
if (e.key === 'Enter') {
e.preventDefault();
submitSpell();
}
});
const spell = el('div', { class: 'al-gen al-spell' }, [spellInput, spellBtn]);
const search = el('input', {
type: 'search',
class: 'al-search',
placeholder: 'Search animations…',
'aria-label': 'Search animations',
autocomplete: 'off',
});
search.addEventListener('input', () => {
this._query = search.value.trim().toLowerCase();
if (this._state === 'ready') this._renderGallery();
});
const chips = el('div', {
class: 'al-chips',
role: 'tablist',
'aria-label': 'Animation categories',
});
const grid = el('div', { class: 'al-grid' });
const empty = el('div', { class: 'al-empty' });
// Shell refs first; _renderTransport() merges its own sub-refs (label,
// speed, export button) into this._refs, so it must run after this assign.
this._refs = { gen, genInput, genBtn, spell, spellInput, spellBtn, search, chips, grid, empty };
const transport = this._renderTransport();
this._refs.transport = transport;
this.host.appendChild(gen);
this.host.appendChild(spell);
this.host.appendChild(search);
// Now-playing transport sits directly under the search so it's visible the
// moment a clip plays (hidden until then) — not buried below the card grid.
this.host.appendChild(transport.root);
this.host.appendChild(chips);
this.host.appendChild(empty);
this.host.appendChild(grid);
}
_setState(state) {
this._state = state;
const { gen, spell, search, chips, grid, empty, transport } = this._refs;
const ready = state === 'ready';
if (gen) gen.style.display = ready ? '' : 'none';
if (spell) spell.style.display = ready ? '' : 'none';
search.style.display = ready ? '' : 'none';
chips.style.display = ready ? '' : 'none';
grid.style.display = ready ? '' : 'none';
transport.root.style.display = ready && this._activeName ? '' : 'none';
empty.style.display = ready ? 'none' : '';
if (ready) return;
empty.innerHTML = '';
const make = (icon, title, body, action) => {
empty.appendChild(el('div', { class: 'al-empty-icon' }, [icon]));
empty.appendChild(el('div', { class: 'al-empty-title' }, [title]));
empty.appendChild(el('p', { class: 'al-empty-body' }, [body]));
if (action) empty.appendChild(action);
};
if (state === 'loading') {
empty.appendChild(
el(
'div',
{ class: 'al-skeleton-grid' },
Array.from({ length: 6 }, () => el('div', { class: 'al-skeleton' })),
),
);
} else if (state === 'error-load') {
const retry = el('button', { class: 'al-cta', type: 'button' }, ['Retry']);
retry.addEventListener('click', () => this.mount());
make(
'⚠️',
'Couldn’t load the animation library',
'The clip manifest failed to load. Check your connection and try again.',
retry,
);
} else if (state === 'no-rig') {
const cta = el('button', { class: 'al-cta', type: 'button' }, ['Load a rigged avatar']);
cta.addEventListener('click', () =>
document.querySelector('#pose-load-avatar')?.click(),
);
make(
'🦴',
'Load a rigged avatar to animate',
'Animation presets apply to a rigged model. Load one of your avatars (or a public avatar) and the full gallery unlocks here.',
cta,
);
} else if (state === 'incompatible') {
make(
'🚫',
'This rig can’t be retargeted',
`The loaded model exposes only ${this._rigBoneCount()} recognizable humanoid bones — too few to drive the preset library. Try a standard humanoid avatar.`,
null,
);
}
}
// ── Category chips ──────────────────────────────────────────────────────
_buildCategoryChips() {
const { chips } = this._refs;
chips.innerHTML = '';
const mk = (key, label) => {
const b = el(
'button',
{
class: 'al-chip',
type: 'button',
role: 'tab',
'data-cat': key,
'aria-selected': String(this._filterCat === key),
},
[label],
);
b.addEventListener('click', () => {
this._filterCat = key;
chips
.querySelectorAll('.al-chip')
.forEach((c) => c.setAttribute('aria-selected', String(c.dataset.cat === key)));
this._renderGallery();
});
return b;
};
chips.appendChild(mk('', 'All'));
for (const g of this._curated.groups) chips.appendChild(mk(g.key, `${g.icon} ${g.label}`));
}
// ── Gallery ─────────────────────────────────────────────────────────────
_matches(def) {
if (this._filterCat && def.category !== this._filterCat) return false;
if (this._query) {
const hay = `${def.label || ''} ${def.name}`.toLowerCase();
if (!hay.includes(this._query)) return false;
}
return true;
}
_renderGallery() {
const { grid } = this._refs;
grid.innerHTML = '';
// Featured row only when unfiltered and unsearched.
if (!this._filterCat && !this._query && this._curated.featured.length) {
grid.appendChild(el('div', { class: 'al-section-label' }, ['Featured']));
const row = el('div', { class: 'al-cards' });
for (const def of this._curated.featured) row.appendChild(this._card(def));
grid.appendChild(row);
}
for (const group of this._curated.groups) {
const items = group.items.filter((d) => this._matches(d));
if (!items.length) continue;
grid.appendChild(
el('div', { class: 'al-section-label' }, [`${group.icon} ${group.label}`]),
);
const row = el('div', { class: 'al-cards' });
for (const def of items) row.appendChild(this._card(def));
grid.appendChild(row);
}
if (!grid.querySelector('.al-card')) {
grid.appendChild(
el('p', { class: 'al-no-match' }, [`No animations match “${this._query}”.`]),
);
}
}
_card(def) {
const isActive = def.name === this._activeName;
const card = el(
'button',
{
class: `al-card${isActive ? ' is-active' : ''}`,
type: 'button',
'data-name': def.name,
'aria-pressed': String(isActive),
title: `${def.label || def.name}${def.loop === false ? '' : ' · loops'}`,
},
[
el('span', { class: 'al-card-icon' }, [def.icon || '🎬']),
el('span', { class: 'al-card-label' }, [def.label || def.name]),
el('span', { class: 'al-card-badge' }, [def.loop === false ? 'once' : 'loop']),
el('span', { class: 'al-card-eq', 'aria-hidden': 'true' }, [
el('i'),
el('i'),
el('i'),
]),
],
);
card.addEventListener('click', () => this.preview(def));
return card;
}
_markActiveCard() {
this._refs.grid.querySelectorAll('.al-card').forEach((c) => {
const on = c.dataset.name === this._activeName;
c.classList.toggle('is-active', on);
c.setAttribute('aria-pressed', String(on));
});
}
// ── Preview ─────────────────────────────────────────────────────────────
async _loadClip(def) {
if (this._clipCache.has(def.name)) return this._clipCache.get(def.name);
const res = await fetch(def.url, { cache: 'force-cache' });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const clip = parseClipJSON(await res.json(), def.name);
this._clipCache.set(def.name, clip);
return clip;
}
_ensureMixer(rig) {
if (this._mixer && this._mixerRoot === rig.root) return this._mixer;
this._disposeMixer();
this._mixer = new AnimationMixer(rig.root);
this._mixerRoot = rig.root;
return this._mixer;
}
/** Load → retarget → play a preset on the current rig. */
async preview(def) {
const rig = this.getRig();
if (!rig || rig.kind === 'mannequin') {
this.setStatus('Load a rigged avatar to apply animations.', 'error');
return;
}
this.setStatus(`Loading ${def.label || def.name}…`);
let clip;
try {
clip = await this._loadClip(def);
} catch (err) {
this._clipCache.delete(def.name);
this.setStatus(`Couldn’t load “${def.label || def.name}”: ${err.message}`, 'error');
return;
}
this._baseClip = clip;
this._resetEdits(clip.duration, def.loop !== false);
this._playClip(this._computeEditedClip(clip), { ...def, loop: this._loopOn });
}
/**
* Retarget an already-resolved canonical clip onto the current rig and play
* it. Shared by preset preview() and text-to-animation generateFromText() —
* one apply path, so a generated motion behaves exactly like a preset
* (transport, speed, loop, export all work identically). Returns true on play.
*/
_playClip(clip, def) {
const rig = this.getRig();
if (!rig || rig.kind === 'mannequin') {
this.setStatus('Load a rigged avatar to apply animations.', 'error');
return false;
}
const {
clip: retargeted,
matched,
total,
coverage,
dropped,
} = retargetClipToRig(clip, rig);
if (!retargeted) {
this.setStatus(
`“${def.label || def.name}” can’t retarget to this rig — only ${matched}/${total} tracks mapped (need ${Math.round(MIN_COVERAGE * 100)}%).`,
'error',
);
return false;
}
const mixer = this._ensureMixer(rig);
mixer.stopAllAction();
const action = mixer.clipAction(retargeted);
action.setLoop(def.loop === false ? LoopOnce : LoopRepeat, Infinity);
action.clampWhenFinished = def.loop === false;
action.timeScale = this._speed;
action.reset().play();
this._paused = false;
this._scrubbing = false;
this._updatePlayIcon();
this._action = action;
this._activeName = def.name;
this._activeDef = def;
this._activeRetarget = { matched, total, coverage, dropped };
if (!this._previewing) {
this._previewing = true;
this.onPreviewStart();
}
this._markActiveCard();
this._updateTransport();
this._refs.transport.root.style.display = '';
const pct = Math.round(coverage * 100);
const note = dropped.length
? ` (${matched}/${total} bones · ${dropped.length} not on this rig)`
: ` (${matched}/${total} bones matched)`;
this.setStatus(`Playing “${def.label || def.name}” — ${pct}% retargeted${note}.`);
return true;
}
// ── Generate from text ──────────────────────────────────────────────────
/**
* Synthesize a brand-new motion from a prompt (workers/model-text2motion via
* /api/forge-motion), then retarget + play it through the same path as a
* preset. Token-based abort so a newer request supersedes an in-flight one.
*/
async generateFromText(prompt) {
prompt = (prompt || '').trim();
if (prompt.length < 3) {
this.setStatus('Describe the motion in a few words first.', 'error');
return;
}
const rig = this.getRig();
if (!rig || rig.kind === 'mannequin') {
this.setStatus('Load a rigged avatar before generating a motion.', 'error');
return;
}
const token = ++this._genToken;
this._setGenBusy(true);
const t0 = performance.now();
const tick = () => {
if (token !== this._genToken) return;
const s = Math.floor((performance.now() - t0) / 1000);
this.setStatus(`Generating “${prompt}” — ${s}s`, 'busy');
};
tick();
this._genTimer = setInterval(tick, 1000);
try {
const clipJSON = await this._runMotionJob(prompt, token);
if (token !== this._genToken || !clipJSON) return; // superseded / aborted
this._stopGenTimer();
const name = `gen_${Date.now().toString(36)}`;
const clip = parseClipJSON(clipJSON, name);
this._clipCache.set(name, clip);
const def = {
name,
label: prompt.length > 28 ? `${prompt.slice(0, 27)}…` : prompt,
icon: '✨',
loop: true,
generated: true,
};
this._baseClip = clip;
this._resetEdits(clip.duration, true);
this._playClip(this._computeEditedClip(clip), { ...def, loop: this._loopOn });
} catch (err) {
if (token !== this._genToken) return;
this._stopGenTimer();
const msg =
err?.kind === 'unconfigured'
? 'Text-to-animation isn’t enabled on this deployment yet.'
: err?.message || 'Generation failed.';
this.setStatus(msg, 'error');
} finally {
if (token === this._genToken) this._setGenBusy(false);
}
}
/** Submit a motion job and poll until the clip JSON is ready. */
async _runMotionJob(prompt, token) {
const submit = await fetch('/api/forge-motion', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ prompt }),
});
const sub = await submit.json().catch(() => ({}));
if (submit.status === 503 || sub.error === 'unconfigured') {
throw Object.assign(new Error(sub.message || 'unconfigured'), { kind: 'unconfigured' });
}
if (submit.status === 429) throw new Error('The motion generator is busy. Try again shortly.');
if (!submit.ok || !sub.job_id) throw new Error(sub.message || `Generator returned ${submit.status}.`);
const deadline = performance.now() + GEN_MAX_POLL_MS;
while (token === this._genToken && performance.now() < deadline) {
await sleep(GEN_POLL_INTERVAL_MS);
if (token !== this._genToken) return null;
const res = await fetch(`/api/forge-motion?job=${encodeURIComponent(sub.job_id)}`);
const data = await res.json().catch(() => ({}));
// The server hands back the clip already converted to the library's
// basis; the raw worker URL is the fallback when that step failed.
if (data.status === 'done' && data.clip) return data.clip;
if (data.status === 'done' && data.clip_url) {
const cr = await fetch(data.clip_url);
if (!cr.ok) throw new Error(`Couldn’t fetch the generated clip (HTTP ${cr.status}).`);
return cr.json();
}
if (data.status === 'failed') throw new Error(data.error || 'Generation failed.');
}
if (token !== this._genToken) return null;
throw new Error('Generation timed out. Try a shorter prompt.');
}
// ── Fingerspell ─────────────────────────────────────────────────────────
/**
* Spell a word in American Sign Language on the rig's right hand. The clip
* is built locally and deterministically (src/fingerspelling.js) and plays
* through the same retarget/transport path as a preset, so speed, scrub,
* and animated-GLB export all work on a spelled word. Returns true on play.
*/
spellWord(word) {
const letters = normalizeWord(word);
if (!letters) {
this.setStatus('Type a word to fingerspell — letters and numbers.', 'error');
return false;
}
// Reflect the (normalized) word in the input so deep links read back.
if (this._refs.spellInput) this._refs.spellInput.value = letters;
const rig = this.getRig();
if (!rig || rig.kind === 'mannequin') {
this.setStatus('Load a rigged avatar to fingerspell.', 'error');
return false;
}
let clip;
try {
const json = buildFingerspellingClip(letters);
clip = parseClipJSON(json, json.name);
this._clipCache.set(json.name, clip);
} catch (err) {
this.setStatus(`Couldn’t build the spelling: ${err.message}`, 'error');
return false;
}
const def = {
name: clip.name,
label: `Fingerspell “${letters}”`,
icon: '🤟',
loop: false,
spelled: true,
};
this._baseClip = clip;
this._resetEdits(clip.duration, false);
return this._playClip(this._computeEditedClip(clip), { ...def, loop: this._loopOn });
}
_stopGenTimer() {
if (this._genTimer) {
clearInterval(this._genTimer);
this._genTimer = null;
}
}
_setGenBusy(busy) {
const { gen, genInput, genBtn } = this._refs;
if (genInput) genInput.disabled = busy;
if (genBtn) {
genBtn.disabled = busy;
genBtn.textContent = busy ? '✨ Generating…' : '✨ Generate';
}
if (gen) gen.dataset.busy = busy ? 'true' : 'false';
}
stopPreview({ silent = false } = {}) {
if (!this._previewing && !this._activeName) return;
this._mixer?.stopAllAction();
this._action = null;
this._activeName = null;
this._activeDef = null;
this._previewing = false;
this._markActiveCard?.();
if (this._refs.transport) this._refs.transport.root.style.display = 'none';
// Hand the figure back to the host in a clean rest pose.
try {
this.getRig()?.resetPose?.();
} catch {
/* rig may be gone */
}
this.onPreviewStop();
if (!silent) this.setStatus('Preview stopped.');
}
_setSpeed(v) {
this._speed = Math.min(2.5, Math.max(0.25, v));
if (this._action) this._action.timeScale = this._speed;
this._updateTransport();
}
// ── Trim / blend / loop edits ────────────────────────────────────────────
/** Reset the trim/blend/loop controls for a newly-loaded clip. */
_resetEdits(duration, loopDefault) {
this._trimStart = 0;
this._trimEnd = duration;
this._blendMs = 0;
this._loopOn = loopDefault !== false;
const { trimStartInput, trimEndInput, blendInput, loopBtn } = this._refs;
if (trimStartInput) {
trimStartInput.max = duration.toFixed(2);
trimStartInput.value = '0';
}
if (trimEndInput) {
trimEndInput.max = duration.toFixed(2);
trimEndInput.value = duration.toFixed(2);
}
if (blendInput) blendInput.value = '0';
if (loopBtn) {
loopBtn.setAttribute('aria-pressed', String(this._loopOn));
loopBtn.classList.toggle('is-on', this._loopOn);
}
}
/** Apply the current trim range and loop-blend to `base`, never mutating it. */
_computeEditedClip(base) {
const duration = base.duration;
const start = Math.max(0, Math.min(this._trimStart, duration));
const end = Math.max(start + 1 / 60, Math.min(this._trimEnd ?? duration, duration));
const trimmed =
start > 1e-3 || end < duration - 1e-3 ? trimClip(base, start, end) : base;
const edited =
this._loopOn && this._blendMs > 0 ? blendClipLoop(trimmed, this._blendMs / 1000) : trimmed;
if (edited !== base) edited.name = base.name;
return edited;
}
/** Re-derive and replay the edited clip after a trim/blend/loop control changes. */
_onEditsChanged() {
if (!this._baseClip || !this._activeDef) return;
const wasPaused = this._paused;
const edited = this._computeEditedClip(this._baseClip);
const played = this._playClip(edited, { ...this._activeDef, loop: this._loopOn });
if (played && wasPaused) {
this._action.paused = true;
this._paused = true;
this._updatePlayIcon();
}
}
_debounceEdits() {
clearTimeout(this._editDebounce);
this._editDebounce = setTimeout(() => this._onEditsChanged(), 180);
}
_onTrimInput() {
const { trimStartInput, trimEndInput } = this._refs;
const duration = this._baseClip?.duration || 0;
let start = Math.max(0, parseFloat(trimStartInput.value) || 0);
let end = parseFloat(trimEndInput.value);
if (!Number.isFinite(end)) end = duration;
if (end <= start) end = Math.min(duration, start + 0.1);
start = Math.min(start, duration);
this._trimStart = start;
this._trimEnd = end;
this._debounceEdits();
}
// ── Save to library ──────────────────────────────────────────────────────
/**
* Save the active clip (with current trim/blend/loop edits applied) to the
* signed-in user's animation library. Saves the canonical, pre-retarget
* clip, the same basis AnimationManager plays everywhere, so it plays on
* any future rig, not just the one currently loaded.
*/
async _saveToLibrary(btn) {
if (!this._baseClip || !this._activeDef) return;
const defaultName = this._activeDef.label || this._activeDef.name || 'My animation';
const nameInput = el('input', {
type: 'text',
class: 'al-save-name',
value: defaultName,
maxlength: '120',
required: 'true',
autocomplete: 'off',
'aria-label': 'Animation name',
});
const visSelect = el('select', { class: 'al-save-vis', 'aria-label': 'Visibility' }, [
el('option', { value: 'private' }, ['Private (only you)']),
el('option', { value: 'unlisted' }, ['Unlisted (anyone with the link)']),
el('option', { value: 'public' }, ['Public (listed in the library)']),
]);
const cancelBtn = el('button', { type: 'button', class: 'al-save-cancel' }, ['Cancel']);
const submitBtn = el('button', { type: 'submit', class: 'al-save-submit' }, ['Save']);
const form = el('form', { class: 'al-save-form' }, [
el('label', { class: 'al-save-label' }, ['Name', nameInput]),
el('label', { class: 'al-save-label' }, ['Visibility', visSelect]),
el('div', { class: 'al-save-actions' }, [cancelBtn, submitBtn]),
]);
let resolved = false;
const choice = await new Promise((resolve) => {
const settle = (v) => {
if (resolved) return;
resolved = true;
resolve(v);
};
const modal = new Modal({
title: 'Save to your animation library',
body: form,
dismissible: true,
onClose: () => settle(null),
});
cancelBtn.addEventListener('click', () => modal.close());
form.addEventListener('submit', (e) => {
e.preventDefault();
settle({ name: nameInput.value.trim(), visibility: visSelect.value });
modal.close();
});
modal.open(btn);
nameInput.focus();
nameInput.select();
});
if (!choice || !choice.name) return;
const original = btn.textContent;
btn.disabled = true;
btn.textContent = 'Saving…';
try {
const clip = this._computeEditedClip(this._baseClip);
const avatarId = this.getAvatarId();
const res = await fetch('/api/animations/clips', {
method: 'POST',
credentials: 'include',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
name: choice.name,
visibility: choice.visibility,
kind: this._loopOn ? 'loop' : 'animation',
loop: this._loopOn,
avatar_id: avatarId && UUID_RE.test(avatarId) ? avatarId : undefined,
clip: AnimationClip.toJSON(clip),
}),
});
if (res.status === 401) {
btn.disabled = false;
btn.textContent = original;
this.setStatus('Sign in to save animations to your library.', 'error');
window.location.assign(
`/login?next=${encodeURIComponent(window.location.pathname + window.location.search)}`,
);
return;
}
const data = await res.json().catch(() => ({}));
if (!res.ok) throw new Error(data.message || `HTTP ${res.status}`);
btn.textContent = 'Saved ✓';
this.setStatus(`Saved “${choice.name}” to your animation library.`);
} catch (err) {
log.warn('[AnimationLibrary] save failed:', err);
btn.textContent = 'Failed';
this.setStatus(`Save failed: ${err.message}`, 'error');
} finally {
setTimeout(() => {
btn.disabled = false;
btn.textContent = original;
}, 2400);
}
}
// ── Transport bar (now-playing + speed + loop + stop + export) ────────────
_renderTransport() {
const label = el('span', { class: 'al-now-label' });
const speedVal = el('span', { class: 'al-speed-val' }, ['1.0×']);
const speed = el('input', {
type: 'range',
min: '0.25',
max: '2.5',
step: '0.05',
value: '1',
class: 'al-speed',
'aria-label': 'Playback speed',
});
speed.addEventListener('input', () => {
this._setSpeed(parseFloat(speed.value));
});
const stop = el('button', { class: 'al-tbtn', type: 'button', title: 'Stop preview' }, [
'⏹ Stop',
]);
stop.addEventListener('click', () => this.stopPreview());
// Play/pause + scrubbable progress — the clip's own timeline, so users can
// scrub to any frame, pause on a pose, and see how long the motion runs.
const play = el('button', { class: 'al-play', type: 'button', title: 'Pause', 'aria-label': 'Pause' }, ['⏸']);
play.addEventListener('click', () => this._togglePlay());
const scrub = el('input', {
type: 'range',
min: '0',
max: '1000',
step: '1',
value: '0',
class: 'al-scrub',
'aria-label': 'Scrub animation timeline',
});
const onScrub = () => {
this._scrubbing = true;
this._seek(parseInt(scrub.value, 10) / 1000);
};
scrub.addEventListener('input', onScrub);
scrub.addEventListener('change', () => {
this._scrubbing = false;
});
scrub.addEventListener('pointerup', () => {
this._scrubbing = false;
});
const timeLabel = el('span', { class: 'al-time' }, ['0.0 / 0.0s']);
const exportBtn = el(
'button',
{
class: 'al-export',
type: 'button',
title: 'Download a GLB with this animation baked in',
},
['Export animated GLB'],
);
exportBtn.addEventListener('click', () => this._exportGLB(exportBtn));
const saveBtn = el(
'button',
{
class: 'al-save',
type: 'button',
title: 'Save this clip to your animation library',
},
['💾 Save to library'],
);
saveBtn.addEventListener('click', () => this._saveToLibrary(saveBtn));
// Trim / blend / loop: cut the clip to a range and crossfade the loop seam,
// the same editing affordances a Theatre.js-style timeline offers, applied
// to the resolved clip (preset, generated, or spelled) before preview,
// export, and save all see it.
const trimStartInput = el('input', {
type: 'number',
class: 'al-trim-input',
min: '0',
step: '0.1',
value: '0',
'aria-label': 'Trim start, in seconds',
title: 'Trim start (s)',
});
const trimEndInput = el('input', {
type: 'number',
class: 'al-trim-input',
min: '0',
step: '0.1',
value: '0',
'aria-label': 'Trim end, in seconds',
title: 'Trim end (s)',
});
trimStartInput.addEventListener('input', () => this._onTrimInput());
trimEndInput.addEventListener('input', () => this._onTrimInput());
const blendInput = el('input', {
type: 'number',
class: 'al-blend-input',
min: '0',
max: '2000',
step: '50',
value: '0',
'aria-label': 'Loop blend, in milliseconds',
title: 'Crossfade the loop seam (ms)',
});
blendInput.addEventListener('input', () => {
this._blendMs = Math.max(0, Math.min(2000, parseFloat(blendInput.value) || 0));
this._debounceEdits();
});
const loopBtn = el(
'button',
{
class: 'al-loop is-on',
type: 'button',
'aria-pressed': 'true',
title: 'Toggle looping',
},
['🔁 Loop'],
);
loopBtn.addEventListener('click', () => {
this._loopOn = !this._loopOn;
loopBtn.setAttribute('aria-pressed', String(this._loopOn));
loopBtn.classList.toggle('is-on', this._loopOn);
this._onEditsChanged();
});
const editRow = el('div', { class: 'al-edit-row' }, [
el('label', { class: 'al-edit-field' }, ['Trim', trimStartInput, 'to', trimEndInput, 's']),
el('label', { class: 'al-edit-field' }, ['Blend', blendInput, 'ms']),
loopBtn,
]);
const root = el('div', { class: 'al-transport', style: 'display:none' }, [
el('div', { class: 'al-now' }, [el('span', { class: 'al-now-dot' }), label]),
el('div', { class: 'al-scrub-row' }, [play, scrub, timeLabel]),
el('div', { class: 'al-speed-row' }, [el('label', {}, ['Speed']), speed, speedVal]),
editRow,
el('div', { class: 'al-transport-actions' }, [stop, saveBtn, exportBtn]),
]);
this._refs = {
...this._refs,
transportLabel: label,
transportSpeedVal: speedVal,
transportSpeed: speed,
transportPlay: play,
transportScrub: scrub,
transportTime: timeLabel,
exportBtn,
saveBtn,
trimStartInput,
trimEndInput,
blendInput,
loopBtn,
};
return { root };
}
_updateTransport() {
const { transportLabel, transportSpeedVal, transportSpeed } = this._refs;
if (transportLabel && this._activeDef) {
transportLabel.textContent = this._activeDef.label || this._activeDef.name;
}
if (transportSpeedVal) transportSpeedVal.textContent = `${this._speed.toFixed(2)}×`;
if (transportSpeed) transportSpeed.value = String(this._speed);
}
async _exportGLB(btn) {
const rig = this.getRig();
if (!rig || !this._activeDef || !this._baseClip) return;
const original = btn.textContent;
const done = (txt, cls) => {
btn.classList.remove('is-busy', 'is-ok', 'is-err');
if (cls) btn.classList.add(cls);
btn.textContent = txt;
setTimeout(() => {
btn.classList.remove('is-ok', 'is-err');
btn.textContent = original;
}, 2400);
};
btn.classList.add('is-busy');
btn.textContent = 'Baking…';
try {
const base = this._computeEditedClip(this._baseClip);
const { clip } = retargetClipToRig(base, rig);
if (!clip) throw new Error('retarget failed');
const exportClip = scaleClipSpeed(clip, this._speed);
exportClip.name = this._activeDef.name;
// Park the figure on the clip's first frame so the exported rest pose
// is the animation's start, not wherever the live preview paused.
if (this._action) {
this._action.time = 0;
this._mixer.update(0);
}
const exporter = new GLTFExporter();
const buffer = await exporter.parseAsync(rig.root, {
binary: true,
animations: [exportClip],
embedImages: true,
});
const safeRig =
(rig.root?.name || 'avatar').replace(/[^a-z0-9._-]+/gi, '-').slice(0, 40) ||
'avatar';
this._download(buffer, `${safeRig}-${this._activeDef.name}.glb`);
done('Saved ✓', 'is-ok');
this.setStatus(
`Exported animated GLB: ${this._activeDef.label || this._activeDef.name}.`,
);
} catch (err) {
log.warn('[AnimationLibrary] export failed:', err);
done('Failed', 'is-err');
this.setStatus(`Export failed: ${err.message}`, 'error');
}
}
_download(buffer, filename) {
const blob =
buffer instanceof Blob ? buffer : new Blob([buffer], { type: 'model/gltf-binary' });
const url = URL.createObjectURL(blob);
const a = document.createElement('a');
a.href = url;
a.download = filename;
document.body.appendChild(a);
a.click();
a.remove();
setTimeout(() => URL.revokeObjectURL(url), 1500);
}
_disposeMixer() {
if (this._mixer) {
this._mixer.stopAllAction();
try {
this._mixer.uncacheRoot(this._mixerRoot);
} catch {
/* root already gone */
}
}
this._mixer = null;
this._mixerRoot = null;
this._action = null;
}
}