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
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.mddeleted file mode 100644index 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.htmlindex 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" /><metaname="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><buttontype="button"class="btn-ghost btn-sm"diff --git a/public/studio/studio.css b/public/studio/studio.cssindex 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.jsindex 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.jsindex 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`,);