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(studio): keep the preview status honest, copy snippets without clipboard permission, and describe the page accurately

nirholas3dbff30e657b
diff --git a/prompts/swarm-100/route-studio.md b/prompts/swarm-100/route-studio.md
deleted file mode 100644
index 7ea18b0a0..000000000
--- a/prompts/swarm-100/route-studio.md
+++ /dev/null
@@ -1,119 +0,0 @@
-# Route audit: /studio (Widget Studio)
-
-How to run: paste this file's repo path into a fresh Claude Code chat in this
-repository and say "run this work order". This file is fully self-contained:
-it depends on no other prompt file anywhere. If neighboring files in
-prompts/swarm-100/ are gone, that work is done; if present, ignore them.
-Every claim below rots; step 0 re-measures, and what you measure wins.
-
-## Operating clause (binding)
-
-- Read CLAUDE.md first. Its rules override everything, including this file.
-- Finish 100% in this session. Never end the turn with a question, an option
- list, or an unexecuted plan. A judgment call goes in one line of the final
- report; it never becomes a question that halts work.
-- The only permitted stops are the CLAUDE.md stop-and-ask gates: spending real
- funds or any irreversible on-chain write, git push or a production deploy,
- committing content that references a crypto project other than $THREE, and
- destroying unrecoverable data.
-- No mocks, no fake data, no placeholder stubs, no unfinished-work markers, no
- commented-out code. Real APIs and real integrations only.
-- The em-dash and en-dash characters are banned in everything you write.
-- Concurrent agents share this worktree: stage explicit paths only (never a
- bare add-everything), and commit finished work promptly.
-- Before committing, run: npm run check:rules -- --paths <files you touched>.
- It must exit 0.
-
-## Step 0: re-derive the current state
-
-1. This route's declared entry (path, description, added date):
-
- node -e "const p=require('./data/pages.json');for(const s of p.sections)for(const g of s.pages)if(g.path==='/studio')console.log(JSON.stringify(g,null,2))"
-
-2. Find the serving implementation: grep "/studio" in vercel.json (the live
- route table server/index.mjs boots from), then list matching files in
- pages/ and src/. STRUCTURE.md maps every surface to its directory if the
- grep is ambiguous.
-3. Production right now:
-
- curl -so /dev/null -w '%{http_code}\n' https://three.ws/studio
-
-4. Start (or reuse) the local dev server: npm run dev (vite, port 3000).
-
-## Task: audit this one route end to end, then fix everything found
-
-Route: /studio ("Widget Studio", section "build").
-Declared purpose: Pick an avatar, configure embed options, copy a one-line snippet for your site.
-
-Drive the page in a real headless browser. Playwright is already a dev
-dependency; keep your probe script in the session scratchpad, never in the
-repo.
-
-1. Load http://localhost:3000/studio. Record the HTTP status, every console
- error and warning, and every failed network request.
-2. Exercise it like a first-time user: click the primary actions, run the
- primary flow if one exists, follow the page's internal links. Every button
- must do something real; every link must resolve. If the page renders data,
- prove in the network log that it came from a live endpoint, not a baked-in
- fallback array.
-3. States: verify populated, empty, loading, and error states are designed and
- reachable. Block the page's primary fetch in Playwright and confirm an
- actionable error state appears, not a blank void or a raw exception.
-4. Responsive: render at 320, 768, and 1440 px. No horizontal page scroll, no
- overlapping or clipped controls.
-5. Accessibility basics: one h1; interactive elements are real buttons or
- links with visible focus states; images carry alt text; form fields have
- labels.
-6. Head: a specific title tag and meta description that match the declared
- purpose above.
-7. Fix every defect at its root in the page's real source files and re-run the
- probe until clean. Defects in shared modules are in scope when this route
- exercises them.
-
-## Definition of done
-
-- [ ] Local load of /studio: HTTP 200, zero console errors, zero unhandled
- failed requests (a third-party outage must land in a designed fallback,
- not a broken page).
-- [ ] No dead interactive element on the page: no stub href="#", no button
- without a handler, no link to a missing path.
-- [ ] Empty, loading, error, and populated states verified.
-- [ ] 320 / 768 / 1440 px renders verified clean.
-- [ ] Title and meta description present and specific.
-- [ ] npm test passes; npm run check:rules -- --paths <touched files> exits 0.
-- [ ] Production status from step 0 recorded in the report; if production
- needs a deploy to pick up a fix, the report says so (deploys stay
- owner-gated).
-
-## Never blocked
-
-| Blocker | Resolution (act, do not ask) |
-|---|---|
-| Missing env var or credential | Check .env and .env.local, then the Cloud Run service env, then Secret Manager (the CLAUDE.md self-unblock playbook has the exact commands). If it truly exists nowhere, wire the code fully behind the env var, prove the wiring with a dry run, and name the single missing var in the report. |
-| gcloud not on PATH | Run: export PATH="$HOME/google-cloud-sdk/bin:$PATH" |
-| Dev server port 3000 busy | Another agent may be serving this repo; probe it and reuse if so. Otherwise start your own on a free port: npx vite --port 3101 |
-| Playwright browser missing | npx playwright install chromium |
-| A surface needs a signed-in user | Register a fresh account through the real /register flow against the real API and use it. Never mock the session. |
-| A defect sits in code you did not touch | Fix it if it blocks a Definition of done line (root cause it, never mask it). Otherwise note it in the report and continue. |
-| An unrelated test is red | Same rule. Never pipe npm test through tail; it masks exit codes. |
-
-## Close out (required)
-
-1. Verify every Definition of done line with the actual command output in
- front of you. Never claim a line you did not verify.
-2. Commit with explicit paths and a subject that describes the diff (house
- style: type(scope): what changed and why a reader cares).
-3. Delete this prompt file in that same commit:
-
- git rm prompts/swarm-100/route-studio.md
-
- The shrinking directory is this campaign's only progress ledger; there is
- no progress log to update.
-4. Final report: what step 0 measured, what changed (file list), evidence per
- Definition of done line, and any one-line judgment calls. No trailing
- questions, no unexecuted plans.
-
-If a line genuinely cannot pass inside this session (an external party must
-respond, or an owner-gated action is the final step), finish everything else,
-leave this file in place, and state exactly which line remains and who owns
-it. Never delete this file on a partial.
diff --git a/public/studio/index.html b/public/studio/index.html
index fbef76694..981768663 100644
--- a/public/studio/index.html
+++ b/public/studio/index.html
@@ -7,7 +7,7 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
<meta
name="description"
- content="Turn any avatar into an embeddable 3D widget. Five types, brand controls, one-line embed."
+ content="Pick any three.ws avatar, choose a widget type, set brand colors and environment, and copy a one-line embed snippet for your site."
data-i18n-attr="content:studio_index.meta_description"/>
<meta name="theme-color" content="#0a0a0a" />
<meta name="robots" content="noindex" />
@@ -132,6 +132,8 @@
type="search"
id="public-search"
placeholder="Search public avatars…"
+ aria-label="Search public avatars"
+ data-i18n-attr="aria-label:studio_index.public_search_arialabel"
autocomplete="off"
spellcheck="false"
/>
@@ -401,7 +403,7 @@
<details>
<summary data-i18n="studio_index.script_tag_embed">Script-tag embed</summary>
<div class="copy-row">
- <textarea id="embed-script-snippet" rows="2" readonly></textarea>
+ <textarea id="embed-script-snippet" rows="2" readonly aria-label="Script-tag embed snippet" data-i18n-attr="aria-label:studio_index.script_snippet_arialabel"></textarea>
<button
type="button"
class="btn-ghost btn-sm"
diff --git a/public/studio/studio.css b/public/studio/studio.css
index 4e79c1736..0f3b2595c 100644
--- a/public/studio/studio.css
+++ b/public/studio/studio.css
@@ -819,6 +819,21 @@ a:hover {
flex-shrink: 0;
}
+.preview-status-error {
+ color: #f2a7a7;
+ font-size: 0.85em;
+}
+.preview-status-error::before {
+ content: '';
+ display: inline-block;
+ width: 7px;
+ height: 7px;
+ margin-right: 6px;
+ border-radius: 50%;
+ background: #e5484d;
+ vertical-align: middle;
+}
+
/* ── right column: tabs + form ─────────────────────────────────────────────── */
.studio-right-tabs {
display: flex;
diff --git a/public/studio/studio.js b/public/studio/studio.js
index 577c7b49e..011a1146f 100644
--- a/public/studio/studio.js
+++ b/public/studio/studio.js
@@ -202,6 +202,16 @@ formEl.addEventListener('submit', (event) => event.preventDefault());
const errEl = $('#form-error');
const previewIfr = $('#preview-iframe');
const previewSt = $('#preview-status');
+// The status line ships with a data-i18n placeholder so the pre-render copy is
+// translated, but from the first script write onwards the script owns it:
+// the catalog pass lands after an async /api/locale fetch and would otherwise
+// revert "Loading preview…" or "Live preview" back to "Pick an avatar to preview".
+previewSt.setAttribute('data-i18n-owned', '1');
+// Preview lifecycle flags. The iframe `load` event fires when the widget shell
+// has painted, not when the model has arrived; the shell reports a failed GLB
+// fetch afterwards with a `widget:load:error` message (src/app.js).
+let previewLoading = false;
+let previewFailed = false;
const captureBtn = $('#capture-camera-btn');
const saveBtn = $('#save-draft-btn');
const generateBtn = $('#generate-btn');
@@ -577,7 +587,10 @@ async function searchPublicAvatars(q) {
: 'No public avatars match that search.';
} catch (err) {
list.hidden = true;
- status.textContent = `Couldn't search: ${err.message}`;
+ const code = /^search: (\d+)$/.exec(err.message)?.[1];
+ status.textContent = code
+ ? `The avatar library answered with an error (${code}). Press Browse to try again.`
+ : "Couldn't reach the avatar library. Check your connection and press Browse to try again.";
}
}
@@ -1681,7 +1694,8 @@ const previewFrameEl = $('#preview-frame');
// Remove shimmer once iframe content has painted.
previewIfr.addEventListener('load', () => {
previewFrameEl?.classList.remove('is-loading');
- if (previewSt.textContent === 'Loading preview…') {
+ if (previewLoading) {
+ previewLoading = false;
if (state.avatarId) {
previewSt.className = 'preview-status-live';
previewSt.textContent = 'Live preview';
@@ -1740,6 +1754,8 @@ function updateWalkPreview(forceReload) {
if (forceReload || key !== previewSrcKey) {
previewSrcKey = key;
previewSt.className = 'muted';
+ previewLoading = true;
+ previewFailed = false;
previewSt.textContent = 'Loading preview…';
previewFrameEl?.classList.add('is-loading');
previewIfr.src = `/walk-embed?${query}&_=${Date.now()}`;
@@ -1798,6 +1814,8 @@ function updatePreview(forceReload) {
if (forceReload || key !== previewSrcKey) {
previewSrcKey = key;
previewSt.className = 'muted';
+ previewLoading = true;
+ previewFailed = false;
previewSt.textContent = 'Loading preview…';
previewFrameEl?.classList.add('is-loading');
// Cache-buster query forces a full reload. Without it, hash-only
@@ -1808,7 +1826,7 @@ function updatePreview(forceReload) {
// without site nav/footer/auth chrome in the DOM, so the preview
// doesn't flash the marketing site before the model renders.
previewIfr.src = `/widget?_=${Date.now()}#${hashStr}`;
- } else {
+ } else if (!previewFailed) {
previewSt.className = state.avatarId ? 'preview-status-live' : 'muted';
previewSt.textContent = state.avatarId
? 'Live preview'
@@ -1817,6 +1835,21 @@ function updatePreview(forceReload) {
postConfigToPreview();
}
+// Mirror a failed model fetch outside the iframe. The shell already renders
+// its own retry UI inside the frame; the studio status line and the camera
+// capture button would otherwise keep claiming a live preview.
+window.addEventListener('message', (event) => {
+ if (event.source !== previewIfr.contentWindow || event.origin !== location.origin) return;
+ if (event.data?.type !== 'widget:load:error') return;
+ previewLoading = false;
+ previewFailed = true;
+ previewFrameEl?.classList.remove('is-loading');
+ captureBtn.disabled = true;
+ previewSt.className = 'preview-status-error';
+ previewSt.textContent =
+ "Preview couldn't load this avatar's model. Retry inside the preview or pick another avatar.";
+});
+
function postConfigToPreview() {
if (!previewIfr.contentWindow) return;
if (state.type === 'walking-avatar') return postWalkConfigToPreview();
@@ -2061,14 +2094,30 @@ function copyFromSelector(sel, btn) {
const el = $(sel);
if (!el) return;
el.select?.();
- navigator.clipboard.writeText(el.value).then(
- () => {
- const o = btn.textContent;
- btn.textContent = 'Copied';
- setTimeout(() => (btn.textContent = o), 1200);
- },
- () => toast('Copy failed', 'error'),
- );
+ const flash = () => {
+ const o = btn.textContent;
+ btn.textContent = 'Copied';
+ setTimeout(() => (btn.textContent = o), 1200);
+ };
+ // The async clipboard API is denied without a permission grant in some
+ // embedded and in-app browsers; execCommand still copies a focused
+ // selection there, so it is the fallback rather than a failure toast.
+ const legacyCopy = () => {
+ try {
+ el.focus();
+ el.setSelectionRange?.(0, el.value.length);
+ return document.execCommand('copy');
+ } catch {
+ return false;
+ }
+ };
+ const write = navigator.clipboard?.writeText
+ ? navigator.clipboard.writeText(el.value)
+ : Promise.reject(new Error('clipboard unavailable'));
+ write.then(flash, () => {
+ if (legacyCopy()) flash();
+ else toast('Copy failed. The text is selected: press Ctrl+C or Cmd+C.', 'error');
+ });
}
function showError(msg) {
diff --git a/src/agent-avatar.js b/src/agent-avatar.js
index 12dea8cfb..828a19433 100644
--- a/src/agent-avatar.js
+++ b/src/agent-avatar.js
@@ -588,8 +588,12 @@ export class AgentAvatar {
);
return;
}
- // Clip not in library — warn once, try default slot fallback
- if (!this._warnedSlots.has(clipName)) {
+ // Clip not in library: warn once, try default slot fallback. The
+ // manifest is registered asynchronously after the viewer boots
+ // (src/app.js fetches /animations/manifest.json), so a slot fired
+ // by LOAD_START can land before any def exists. That is not a
+ // missing clip; skip the warning and take the embedded fallback.
+ if (am.getAnimationDefs().length > 0 && !this._warnedSlots.has(clipName)) {
log.warn(
`[AgentAvatar] slot "${slot}" → "${clipName}" not in animation library`,
);