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(create-prompt): offer recovery that matches the failure instead of a blind retry

nirholase683d0a1790e
diff --git a/pages/create-prompt.html b/pages/create-prompt.html
index 434808805..a4dad0b19 100644
--- a/pages/create-prompt.html
+++ b/pages/create-prompt.html
@@ -198,7 +198,10 @@
outline: none;
}
textarea#prompt::placeholder {
- color: #555;
+ /* Same floor as .hint below: #555 on the #000 bg measures ~2.9:1,
+ under the 4.5:1 AA threshold, and this placeholder is the only
+ guidance in an empty composer. #8a8a8a measures ~5.8:1. */
+ color: #8a8a8a;
}
.composer-foot {
display: flex;
@@ -208,7 +211,7 @@
padding: 0 10px;
}
.counter {
- color: #555;
+ color: #8a8a8a;
font-size: 12px;
font-variant-numeric: tabular-nums;
}
@@ -415,7 +418,7 @@
transition: width 0.8s cubic-bezier(0.4, 0, 0.2, 1);
}
.elapsed {
- color: #555;
+ color: #8a8a8a;
font-size: 12px;
margin-top: 14px;
font-variant-numeric: tabular-nums;
@@ -441,11 +444,65 @@
outline: 2px solid var(--accent);
outline-offset: 2px;
}
+ /* "Try again" while a server Retry-After is still counting down. */
+ .cancel-build:disabled {
+ opacity: 0.5;
+ cursor: default;
+ font-variant-numeric: tabular-nums;
+ }
+ .cancel-build:disabled:hover {
+ color: var(--muted);
+ border-color: var(--border-strong);
+ background: transparent;
+ }
@media (prefers-reduced-motion: reduce) {
.orb::after { animation: none; }
.progress-fill { transition: none; }
}
+ /* A failed build must stop looking like a running one. The orb sweep
+ freezes, the bar and clock recede, and Cancel goes away because
+ there is nothing left to cancel: the recovery buttons inside the
+ error box are the only live controls. */
+ .build-wrap.errored .orb::after {
+ animation: none;
+ opacity: 0.2;
+ }
+ .build-wrap.errored .progress-track {
+ opacity: 0.25;
+ }
+ .build-wrap.errored .elapsed {
+ opacity: 0.5;
+ }
+ /* The phase line ("Reconstructing it into 3D...") is a claim about
+ work in flight, so it goes away entirely on failure. Hiding it
+ rather than only blanking it also survives the runtime i18n pass,
+ which re-applies the translated string from data-i18n after load.
+ The error box carries role="alert", so screen readers still get
+ the outcome. */
+ .build-wrap.errored .build-status {
+ display: none;
+ }
+ /* By id, not by class: the recovery buttons inside the error box
+ borrow .cancel-build for their styling, and hiding those would
+ strand the user on the failure with no way out. */
+ .build-wrap.errored #cancel-build {
+ display: none;
+ }
+ .error-box a {
+ color: #f3b4b4;
+ text-decoration: underline;
+ text-underline-offset: 2px;
+ }
+ .error-box a:hover {
+ color: #fff;
+ }
+ .error-box a:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 2px;
+ border-radius: 2px;
+ }
+
/* ── Done ──────────────────────────────────────────────────────────── */
.done-wrap {
align-items: center;
diff --git a/src/create-prompt.js b/src/create-prompt.js
index 529cd3a43..d6ddd72b0 100644
--- a/src/create-prompt.js
+++ b/src/create-prompt.js
@@ -34,6 +34,7 @@ const buildPrompt = $('#build-prompt');
const buildStatus = $('#build-status');
const progressFill = $('#progress-fill');
const elapsedEl = $('#elapsed');
+const buildWrap = document.querySelector('.build-wrap');
// Voice → prompt: dictate the avatar description instead of typing it. Feeds
// the exact same #prompt textarea /api/avatars/reconstruct already consumes —
@@ -151,6 +152,8 @@ async function start() {
buildPrompt.textContent = `“${prompt}”`;
setError(buildError, '');
+ buildWrap?.classList.remove('errored');
+ stopRetryCountdown();
// Seed the first progress band so the bar creeps from the very first second.
_phaseFloor = PHASE.queued.floor;
_phaseCeil = PHASE.queued.ceil;
@@ -174,7 +177,7 @@ async function start() {
}
const data = await res.json().catch(() => ({}));
if (!res.ok || !data.jobId) {
- throw new ApiError(mapSubmitError(res.status, data));
+ throw submitError(res.status, data);
}
jobId = data.jobId;
} catch (err) {
@@ -217,50 +220,106 @@ function cancelBuild() {
resetToCompose();
}
-class ApiError extends Error {}
+// `retryable` drives which recovery buttons the failure state offers. A plan
+// limit or an unconfigured deployment cannot be fixed by pressing the same
+// button again, so those failures must not show "Try again" at all.
+class ApiError extends Error {
+ constructor(message, { retryable = true, retryAfterSec = 0 } = {}) {
+ super(message);
+ this.retryable = retryable;
+ this.retryAfterSec = retryAfterSec;
+ }
+}
-/** @param {string | null | undefined} raw */
-function friendlyJobError(raw) {
- if (!raw) return 'Generation failed. Try a different prompt.';
+/**
+ * A job that ended in 'failed' carries a raw backend reason. Turn it into copy
+ * the user can act on, plus whether pressing the same button again could ever
+ * help.
+ * @param {string | null | undefined} raw
+ * @returns {ApiError}
+ */
+function jobError(raw) {
+ if (!raw) return new ApiError('Generation failed. Try a different prompt.');
const lower = raw.toLowerCase();
+ // The server refuses a full library up front, but a job can still lose the
+ // race when another avatar lands mid-build. Same dead end, same exits.
+ if (lower.includes('library is full') || lower.includes('plan limit')) return planLimitError(raw);
if (lower.includes('face') && (lower.includes('detect') || lower.includes('no face')))
- return 'Couldn\'t find a face in the generated reference image. Try rewording your prompt to describe the person more clearly.';
+ return new ApiError('Couldn\'t find a face in the generated reference image. Try rewording your prompt to describe the person more clearly.');
if (lower.includes('nsfw'))
- return 'Content safety blocked this image. Try a different prompt.';
+ return new ApiError('Content safety blocked this image. Try a different prompt.');
if (lower.includes('unreachable') || lower.includes('502') || lower.includes('503'))
- return 'The avatar engine is temporarily unavailable. Try again in a few minutes.';
+ return new ApiError('The avatar engine is temporarily unavailable. Try again in a few minutes.');
if (lower.includes('timeout') || lower.includes('timed out'))
- return 'The engine took too long. Try again in a moment.';
+ return new ApiError('The engine took too long. Try again in a moment.');
if (lower.includes('oom') || lower.includes('memory'))
- return 'The engine ran out of resources. Try a simpler prompt.';
- return 'Generation failed. Try a different prompt.';
+ return new ApiError('The engine ran out of resources. Try a simpler prompt.');
+ return new ApiError('Generation failed. Try a different prompt.');
}
-function mapSubmitError(status, data) {
+// A full avatar library is the one failure on this page that retrying can never
+// clear: the same prompt burns the same GPU minute and lands on the same
+// ceiling. Name the two places that actually clear it and drop the retry.
+function planLimitError(description) {
+ const lead = description && /\S/.test(description)
+ ? description.replace(/\s*(Delete an avatar or upgrade[^.]*\.|Delete an avatar[^.]*\.)\s*$/i, '').trim()
+ : 'Your avatar library is full on this plan.';
+ return new ApiError(
+ `${lead} <a href="/dashboard">Delete one from your dashboard</a> or ` +
+ `<a href="/pricing">upgrade your plan</a>, then build this one again.`,
+ { retryable: false },
+ );
+}
+
+/**
+ * The submit call failed. Build the ApiError the failure state renders.
+ * @returns {ApiError}
+ */
+function submitError(status, data) {
// The API error envelope is { error: <code string>, error_description: <message> }
- // (see api/_lib/http.js error()). Read those fields directly — older code that
+ // (see api/_lib/http.js error()). Read those fields directly, older code that
// reached for data.error.code / data.message never matched and collapsed every
// failure into the generic fallback, hiding the real reason from the user.
const code = typeof data?.error === 'string' ? data.error : data?.code;
const description = data?.error_description;
+ if (code === 'plan_limit' || status === 402) return planLimitError(description);
if (code === 'txt2img_rate_limited' || status === 429) {
- return 'The image engine is busy right now — wait a moment and try again.';
+ // The image ladder answers a throttle (or an exhausted budget) with a real
+ // Retry-After. Quote it instead of "wait a moment", and let failBuild hold
+ // the retry button for exactly that long: a click before then earns the
+ // same 429 and another minute of the user's time.
+ const wait = Math.min(120, Math.max(1, Math.round(Number(data?.retry_after) || 15)));
+ return new ApiError(
+ `The image engine is busy right now. It asked us to wait ${wait} seconds.`,
+ { retryAfterSec: wait },
+ );
}
if (code === 'regen_unconfigured' || code === 'txt2img_unconfigured') {
- return 'The avatar generator isn\'t configured on this deployment yet. Try the <a href="/create/selfie">selfie scanner</a> instead.';
+ return new ApiError(
+ 'The avatar generator isn\'t configured on this deployment yet. Try the <a href="/create/selfie">selfie scanner</a> instead.',
+ { retryable: false },
+ );
}
- if (code === 'txt2img_billing') return 'The image engine is temporarily unavailable (provider billing). Try again later.';
- if (code === 'txt2img_unreachable') return 'Couldn\'t reach the image engine. Check your connection and try again.';
- if (code === 'txt2img_error') return 'Couldn\'t render a reference image from that prompt. Try rewording it.';
+ if (code === 'txt2img_billing')
+ return new ApiError('The image engine is temporarily unavailable (provider billing). Try again later.');
+ if (code === 'txt2img_unreachable')
+ return new ApiError('Couldn\'t reach the image engine. Check your connection and try again.');
+ if (code === 'txt2img_error')
+ return new ApiError('Couldn\'t render a reference image from that prompt. Try rewording it.');
if (code === 'regen_needs_byok')
- return 'Avatar generation needs a 3D engine key on this deployment. Add a Meshy or Tripo key in <a href="/settings">settings</a>, or try the <a href="/create/selfie">selfie scanner</a>.';
+ return new ApiError(
+ 'Avatar generation needs a 3D engine key on this deployment. Add a Meshy or Tripo key in <a href="/settings">settings</a>, or try the <a href="/create/selfie">selfie scanner</a>.',
+ { retryable: false },
+ );
// Reached only after the server has tried every configured backend (platform
- // providers + your BYOK keys) and all of them failed — so this is a genuine
+ // providers + your BYOK keys) and all of them failed, so this is a genuine
// transient outage, not a single-provider hiccup. Offer the photo path as an
// immediate alternative rather than leaving the user to guess.
if (code === 'regen_provider_error')
- return 'The avatar engines are all busy right now. Try again in a moment, or use the <a href="/create/selfie">selfie scanner</a> instead.';
- return description || `The avatar engine returned ${status}. Try again.`;
+ return new ApiError(
+ 'The avatar engines are all busy right now. Try again in a moment, or use the <a href="/create/selfie">selfie scanner</a> instead.',
+ );
+ return new ApiError(description || `The avatar engine returned ${status}. Try again.`);
}
async function pollUntilDone(jobId, run) {
@@ -305,7 +364,7 @@ async function pollUntilDone(jobId, run) {
return data;
}
if (data.status === 'failed') {
- throw new ApiError(friendlyJobError(data.error));
+ throw jobError(data.error);
}
// Soft stall note: if it's still running well past the typical minute,
@@ -405,7 +464,7 @@ async function renderDone(avatarId, run) {
tagsEl.appendChild(s);
};
if (rigged) tag('Animation-ready', true);
- else tag('Static mesh — riggable in editor', false);
+ else tag('Static mesh, riggable in editor', false);
tag('Private to you', false);
stopElapsed();
@@ -439,6 +498,9 @@ function resetToCompose() {
_submitting = false;
stopElapsed();
setError(composeError, '');
+ setError(buildError, '');
+ buildWrap?.classList.remove('errored');
+ stopRetryCountdown();
updateCounter();
showStep('compose');
promptEl.focus();
@@ -449,21 +511,68 @@ function resetToCompose() {
function failBuild(err) {
if (err instanceof ApiError && err.message === 'redirecting') return;
stopElapsed();
+ stopRetryCountdown();
_submitting = false;
log.error('[create-prompt]', err);
+ // Everything that reaches here without being an ApiError came out of fetch
+ // itself (the JSON parses are already guarded), so name the connection rather
+ // than shrugging at the user.
const message =
- err instanceof ApiError ? err.message : 'Something went wrong. Try again.';
- // Two recovery paths: "Try again" re-submits the same prompt in place (the
- // textarea still holds it) for transient engine outages; "Edit prompt" returns
- // to compose to reword. Both keep the user moving instead of stranding them.
+ err instanceof ApiError
+ ? err.message
+ : err?.name === 'TypeError'
+ ? 'Couldn\'t reach the avatar engine. Check your connection and try again.'
+ : 'Something went wrong. Try again.';
+ // Stop the screen from claiming work is still happening: freeze the orb, mute
+ // the bar, and drop Cancel (there is nothing left to cancel). Escape still
+ // returns to compose, same as "Edit prompt".
+ buildWrap?.classList.add('errored');
+ buildStatus.textContent = '';
+ // "Try again" re-submits the same prompt in place (the textarea still holds
+ // it), which only helps a transient failure. A plan limit or an unconfigured
+ // deployment cannot clear that way, so those failures offer the exits their
+ // copy points at instead of a button guaranteed to land here again.
+ const retryable = !(err instanceof ApiError) || err.retryable !== false;
setError(
buildError,
`<span>${message}</span>` +
- ` <button type="button" id="build-retry-now" class="cancel-build" style="margin-left:10px">Try again</button>` +
+ (retryable
+ ? ` <button type="button" id="build-retry-now" class="cancel-build" style="margin-left:10px">Try again</button>`
+ : '') +
` <button type="button" id="build-edit" class="cancel-build" style="margin-left:8px">Edit prompt</button>`,
);
- document.getElementById('build-retry-now')?.addEventListener('click', () => start());
+ const retryBtn = document.getElementById('build-retry-now');
+ retryBtn?.addEventListener('click', () => start());
document.getElementById('build-edit')?.addEventListener('click', resetToCompose);
+ if (retryBtn && err instanceof ApiError && err.retryAfterSec > 0) {
+ armRetryCountdown(retryBtn, err.retryAfterSec);
+ }
+}
+
+// Hold "Try again" for the wait the server asked for and count it down in
+// place, so the button reads as a timer rather than a dead control. Clicking
+// through a Retry-After only earns the same 429, and on this page each attempt
+// can cost the user a full minute before it comes back.
+let _retryTimer = 0;
+function stopRetryCountdown() {
+ if (_retryTimer) { clearInterval(_retryTimer); _retryTimer = 0; }
+}
+function armRetryCountdown(btn, seconds) {
+ stopRetryCountdown();
+ const label = btn.textContent;
+ let left = Math.min(120, Math.max(1, Math.round(seconds)));
+ btn.disabled = true;
+ btn.textContent = `Try again in ${left}s`;
+ _retryTimer = window.setInterval(() => {
+ left -= 1;
+ if (left > 0) {
+ btn.textContent = `Try again in ${left}s`;
+ return;
+ }
+ stopRetryCountdown();
+ btn.disabled = false;
+ btn.textContent = label;
+ }, 1000);
}
// ── Elapsed clock ────────────────────────────────────────────────────────────