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.

fix(sign-language): gate every control on the stage load state so a click during the download queues

nirholas529fb46b033a
diff --git a/pages/sign-language.html b/pages/sign-language.html
index dd32b5649..ee44cfac6 100644
--- a/pages/sign-language.html
+++ b/pages/sign-language.html
@@ -59,6 +59,28 @@
.sl-stage-wrap { position: relative; border: 1px solid var(--stroke); border-radius: 20px; overflow: hidden; background: radial-gradient(120% 120% at 50% 0%, rgba(167,139,250,.10), transparent 60%), var(--surface-1); aspect-ratio: 4 / 5; min-height: 380px; }
#sl-stage { position: absolute; inset: 0; width: 100%; height: 100%; }
+
+ /* Loading: the GLB is several MB, so the stage is empty for a beat.
+ A silhouette that breathes says "an avatar is coming" where an empty
+ gradient box says "this is broken". Both children are removed from
+ the a11y tree; #sl-status carries the same news to a screen reader. */
+ .sl-stage-skeleton { position: absolute; inset: 0; display: none; flex-direction: column; align-items: center; justify-content: center; gap: 14px; pointer-events: none; }
+ .sl-stage-wrap[data-state='loading'] .sl-stage-skeleton { display: flex; }
+ .sl-stage-skeleton-head, .sl-stage-skeleton-body { background: rgba(167,139,250,.14); border-radius: 999px; animation: sl-stage-breathe 1.6s ease-in-out infinite; }
+ .sl-stage-skeleton-head { width: 78px; height: 78px; }
+ .sl-stage-skeleton-body { width: 128px; height: 176px; border-radius: 64px 64px 28px 28px; animation-delay: .18s; }
+ @keyframes sl-stage-breathe { 0%, 100% { opacity: .35; } 50% { opacity: .85; } }
+
+ /* Error: a failed mount used to be a permanent dead stage. It is a
+ network failure like any other, so it gets a real way back. */
+ .sl-stage-fallback[hidden] { display: none; }
+ .sl-stage-fallback { position: absolute; inset: 0; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 14px; padding: 24px; text-align: center; }
+ .sl-stage-fallback-msg { margin: 0; max-width: 34ch; color: var(--ink-dim); font-size: 14px; line-height: 1.6; }
+ .sl-stage-fallback a { color: var(--ink); }
+
+ @media (prefers-reduced-motion: reduce) {
+ .sl-stage-skeleton-head, .sl-stage-skeleton-body { animation: none; opacity: .6; }
+ }
.sl-status { position: absolute; left: 0; right: 0; bottom: 0; padding: 12px 16px; font-family: var(--font-mono); font-size: 13px; color: var(--ink); background: linear-gradient(to top, rgba(0,0,0,.55), transparent); pointer-events: none; min-height: 20px; }
:root[data-theme='light'] .sl-status { color: #fff; }
@@ -265,8 +287,17 @@
<main class="sl-main">
<section class="sl-hero">
- <div class="sl-stage-wrap">
+ <div class="sl-stage-wrap" id="sl-stage-wrap" data-state="loading">
<div id="sl-stage"></div>
+ <div class="sl-stage-skeleton" aria-hidden="true">
+ <span class="sl-stage-skeleton-head"></span>
+ <span class="sl-stage-skeleton-body"></span>
+ </div>
+ <div class="sl-stage-fallback" id="sl-stage-fallback" hidden>
+ <p class="sl-stage-fallback-msg" id="sl-stage-msg" role="status"></p>
+ <button id="sl-stage-retry" class="sl-btn" type="button" data-i18n="sign_language.retry_the_avatar">Retry the avatar</button>
+ <a class="sl-cap-link" href="#sl-api" data-i18n="sign_language.compile_signing_over_http_instead">Compile signing over HTTP instead ↓</a>
+ </div>
<div class="sl-status" id="sl-status" aria-live="polite"></div>
</div>
diff --git a/src/sign-language-page.js b/src/sign-language-page.js
index 9d3edaba7..d41194978 100644
--- a/src/sign-language-page.js
+++ b/src/sign-language-page.js
@@ -50,6 +50,24 @@ async function boot() {
if (status) status.textContent = msg || '';
};
+ // The stage is a several-MB GLB over the network, so it has the same states
+ // as any other fetch. Every control reads `signingState` before it tries to
+ // sign, which is what keeps a click during the download from being a dead
+ // one: it queues instead.
+ const stageWrap = $('#sl-stage-wrap');
+ const stageFallback = $('#sl-stage-fallback');
+ const stageMsg = $('#sl-stage-msg');
+ /** @type {'loading'|'ready'|'mute'|'error'} */
+ let signingState = 'loading';
+ const setStageState = (state, message = '') => {
+ signingState = state;
+ if (stageWrap) stageWrap.dataset.state = state;
+ if (stageFallback) stageFallback.hidden = state !== 'error';
+ if (stageMsg) stageMsg.textContent = message;
+ };
+ /** A phrase asked for before the avatar was ready, performed on arrival. */
+ let pending = null;
+
// Speed and dominant hand are baked into the compiled clips, so changing
// either rebuilds the speaker (cheap: the vocabulary is compiled lazily and
// cached per setting).
@@ -100,6 +118,8 @@ async function boot() {
speaker?.cancel();
speaker = null;
stage?.dispose();
+ setStageState('loading');
+ setStatus(`Loading ${avatar.label}…`);
// Full-body framing: the whole avatar stays in frame, and the orbit
// controls let anyone zoom into the signing space when they want detail.
stage = new PoseStage(stageHost, {
@@ -110,18 +130,25 @@ async function boot() {
const { supported } = await stage.mount();
stage.start();
if (!supported) {
- setStatus('This avatar can’t sign, but the tools below still work.');
+ setStageState('mute');
+ setStatus(`${avatar.label} can’t sign: it has no usable skeleton. Pick another avatar, or compile the signing over HTTP below.`);
return false;
}
rebuildSpeaker();
+ setStageState('ready');
return true;
} catch (err) {
log.warn('[sign-language] stage mount failed', err?.message);
- setStatus('Live preview unavailable: the spelling tools below still work.');
+ // A failed mount is a network failure like any other, so it gets a
+ // way back rather than a permanently dead box.
+ setStageState(
+ 'error',
+ 'The 3D preview did not load. That is usually the network, so a retry fixes it; the sign API below runs on the server and works either way.',
+ );
+ setStatus('');
return false;
}
};
- await mountStage();
// ── Hero auto-signing loop ────────────────────────────────────────────────
// Signing is content, so it is never disabled: but auto-PLAYING on arrival
@@ -146,33 +173,69 @@ async function boot() {
clearTimeout(heroTimer);
speaker?.cancel();
};
- if (speaker && !reducedMotion) heroTick();
- else if (speaker) setStatus('Type anything and watch the avatar sign it.');
// ── Spell-anything input ──────────────────────────────────────────────────
const spellInput = $('#sl-spell-input');
const spellBtn = $('#sl-spell-btn');
- const spellIt = async () => {
- if (!speaker) return;
- const raw = spellInput.value.trim();
- const norm = normalizeWord(raw);
- if (!norm) {
- setStatus('Type letters or numbers to sign.');
- return;
- }
- stopHero();
- heroActive = false;
- lastPhrase = raw;
+ // Why the avatar cannot sign right now, phrased as something to do about it.
+ const unavailableReason = () =>
+ signingState === 'mute'
+ ? `${avatar.label} has no signing skeleton. Pick another avatar above, or compile this over HTTP in the sign API below.`
+ : 'The 3D preview did not load. Retry it above, or compile this over HTTP in the sign API below.';
+
+ /**
+ * Sign a phrase in whatever state the stage is in: queue it while the GLB
+ * is still downloading, and say why when it cannot be performed at all.
+ * @param {string} phrase
+ * @param {{ label?: string, onSettled?: () => void }} [opts] `label` replaces
+ * the default "Signing: …" line; `onSettled` runs once the clip is over.
+ * @returns {Promise<boolean>} whether it was performed now.
+ */
+ const requestSign = async (phrase, opts = {}) => {
+ lastPhrase = phrase;
syncShare();
- setStatus(`Signing: “${norm.toLowerCase()}”`);
+ if (signingState === 'loading') {
+ pending = { phrase, opts };
+ setStatus(`Loading the avatar: it signs “${phrase.trim().toLowerCase()}” as soon as it arrives.`);
+ return false;
+ }
+ if (!speaker) {
+ setStatus(unavailableReason());
+ opts.onSettled?.();
+ return false;
+ }
+ setStatus(opts.label || `Signing: “${phrase.trim().toLowerCase()}”`);
try {
- const result = await speaker.speak(raw);
+ const result = await speaker.speak(phrase);
if (!result.superseded) setStatus(describeResult(result));
+ opts.onSettled?.();
+ return true;
} catch (e) {
setStatus(e?.message || 'Could not sign that.');
+ opts.onSettled?.();
+ return false;
}
};
+
+ /** Perform whatever was asked for while the avatar was still loading. */
+ const flushPending = async () => {
+ if (!pending) return false;
+ const { phrase, opts } = pending;
+ pending = null;
+ await requestSign(phrase, opts);
+ return true;
+ };
+
+ const spellIt = async () => {
+ const raw = spellInput.value.trim();
+ if (!normalizeWord(raw)) {
+ setStatus('Type letters or numbers to sign.');
+ return;
+ }
+ stopHero();
+ await requestSign(raw);
+ };
spellBtn?.addEventListener('click', spellIt);
spellInput?.addEventListener('keydown', (e) => {
if (e.key === 'Enter') {
@@ -311,23 +374,15 @@ async function boot() {
chip.textContent = word.toLowerCase();
const gloss = signGloss(word);
if (gloss) chip.title = gloss;
- chip.addEventListener('click', async () => {
- if (!speaker) return;
+ chip.addEventListener('click', () => {
stopHero();
- heroActive = false;
active?.setAttribute('aria-pressed', 'false');
active = chip;
chip.setAttribute('aria-pressed', 'true');
- lastPhrase = word;
- syncShare();
- setStatus(gloss ? `${word.toLowerCase()}: ${gloss}` : `Signing “${word.toLowerCase()}”`);
- try {
- const result = await speaker.speak(word);
- if (!result.superseded) chip.setAttribute('aria-pressed', 'false');
- } catch {
- chip.setAttribute('aria-pressed', 'false');
- setStatus('Could not sign that.');
- }
+ requestSign(word, {
+ label: gloss ? `${word.toLowerCase()}: ${gloss}` : `Signing “${word.toLowerCase()}”`,
+ onSettled: () => chip.setAttribute('aria-pressed', 'false'),
+ });
});
vocabHost.appendChild(chip);
}
@@ -344,9 +399,9 @@ async function boot() {
initSignApiConsole({
defaults: { hand: dominant === 'Left' ? 'left' : 'right', speed: rate },
sign: async ({ text, hand, speed }) => {
- if (!speaker) throw new Error('the avatar has not finished loading');
+ if (signingState === 'loading') throw new Error('the avatar has not finished loading');
+ if (!speaker) throw new Error(unavailableReason());
stopHero();
- heroActive = false;
const wanted = hand === 'left' ? 'Left' : 'Right';
if (wanted !== dominant || speed !== rate) {
dominant = wanted;
@@ -356,13 +411,9 @@ async function boot() {
syncPills('#sl-speed', (btn) => btn.textContent === `${speed}×`);
rebuildSpeaker();
}
- lastPhrase = text;
- syncShare();
- setStatus(`Signing: “${text.toLowerCase()}”`);
// Move to the avatar before it starts, not after it finishes.
stageHost.scrollIntoView({ behavior: reducedMotion ? 'auto' : 'smooth', block: 'center' });
- const result = await speaker.speak(text);
- if (!result.superseded) setStatus(describeResult(result));
+ await requestSign(text);
},
});
@@ -370,19 +421,25 @@ async function boot() {
// A shareable signing link, mirroring the studio's ?spell=: /sign-language
// ?say=hello+world signs the phrase on arrival (dictionary + spelling).
const say = new URLSearchParams(location.search).get('say');
- if (say && speaker && normalizeWord(say)) {
+ if (say && normalizeWord(say)) {
stopHero();
- heroActive = false;
if (spellInput) spellInput.value = say.slice(0, 48);
- lastPhrase = say;
- syncShare();
- speaker
- .speak(say)
- .then((result) => {
- if (!result.superseded) setStatus(describeResult(result));
- })
- .catch((e) => setStatus(e?.message || 'Could not sign that.'));
+ requestSign(say);
+ }
+
+ // ── Mount the stage last ──────────────────────────────────────────────────
+ // Everything above is wired before the several-MB GLB starts downloading, so
+ // a visitor who types during the load gets a queued phrase rather than a
+ // button with no listener on it.
+ $('#sl-stage-retry')?.addEventListener('click', () => startStage());
+ async function startStage() {
+ if (!(await mountStage())) return;
+ if (await flushPending()) return;
+ if (heroActive && !reducedMotion) heroTick();
+ else if (lastPhrase) replay();
+ else setStatus('Type anything and watch the avatar sign it.');
}
+ await startStage();
}
function wireWebcamDemo(setStatus) {