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
feat(viewer): tell a visitor what to do when the model will not load
nirholas800cc4288fe1
diff --git a/src/avatar-embed.js b/src/avatar-embed.jsindex 47fb6ad3e..83b8f7f55 100644--- a/src/avatar-embed.js+++ b/src/avatar-embed.js@@ -73,6 +73,7 @@ import {} from './runtime/arkit52.js';import { log } from './shared/log.js';import { isSafeQueryModelUrl } from './shared/safe-model-url.js';+import { viewerErrorText } from './shared/viewer-error-text.js';const BRIDGE_VERSION = '1.0';const CAPABILITIES = [@@ -112,28 +113,12 @@ const DEFAULT_HOTKEYS = Object.freeze({});main().catch((err) => {+ // The visitor gets plain language; the raw rejection stays in the console so+ // a developer debugging an embed still sees which URL and status failed.+ log.warn('[avatar-embed] load failed', err);showError(viewerErrorText(err));});-// GLTFLoader rejects with the raw transport string, e.g. `fetch for-// "https://host/x.glb" responded with 502: Bad Gateway`. That names an internal-// URL and tells the viewer nothing they can act on. Map the failures a visitor-// can actually hit onto plain language; anything unrecognised keeps its own-// message, which is already written for a person (resolveAvatar throws-// "avatar <id> not found").-function viewerErrorText(err) {- const msg = String(err?.message || err || '');- if (/responded with 4\d\d/.test(msg)) {- return /40[13]/.test(msg)- ? 'This avatar is private. Sign in with the account that owns it.'- : 'This avatar is no longer available.';- }- if (/responded with 5\d\d/.test(msg)) return 'The avatar service is unavailable. Refresh to try again.';- if (/Failed to fetch|NetworkError|Load failed/i.test(msg)) return 'Connection lost. Check your network and refresh.';- if (/glTF|JSON|Unsupported|Unexpected token/i.test(msg)) return "This avatar's 3D file could not be read.";- return msg || 'Could not load avatar.';-}-async function main() {const params = new URL(location.href).searchParams;applyBackground(params.get('bg') || 'transparent');diff --git a/src/shared/viewer-error-text.js b/src/shared/viewer-error-text.jsnew file mode 100644index 000000000..084c932f5--- /dev/null+++ b/src/shared/viewer-error-text.js@@ -0,0 +1,36 @@+// GLTFLoader (and three's FileLoader under it) reject with the raw transport+// string, e.g. `fetch for "https://host/u/abc/model.glb" responded with 502:+// Bad Gateway`. Shown as-is that names an internal URL, leaks a storage key,+// and tells the viewer nothing they can act on. Map the failures a visitor can+// actually reach onto plain language with a next step.+//+// Anything unrecognised keeps its own message: the callers that throw by hand+// already write for a person (avatar-embed's `avatar <id> not found`), so+// replacing those with a generic string would lose information.++/**+ * Human, actionable text for a model-load failure.+ *+ * @param {unknown} err the rejection from a viewer load+ * @returns {string} copy safe to show a visitor+ */+export function viewerErrorText(err) {+ // An Error with an empty message must not fall through to String(err),+ // which yields the useless literal "Error".+ const msg = (typeof err?.message === 'string' ? err.message : String(err ?? '')).trim();+ if (/responded with 4\d\d/.test(msg)) {+ return /\b40[13]\b/.test(msg)+ ? 'This avatar is private. Sign in with the account that owns it.'+ : 'This avatar is no longer available.';+ }+ if (/responded with 5\d\d/.test(msg)) {+ return 'The avatar service is unavailable. Refresh to try again.';+ }+ if (/failed to fetch|networkerror|load failed|err_/i.test(msg)) {+ return 'Connection lost. Check your network and refresh.';+ }+ if (/gltf|json|unsupported|unexpected token/i.test(msg)) {+ return "This avatar's 3D file could not be read.";+ }+ return msg || 'Could not load avatar.';+}diff --git a/tests/src/viewer-error-text.test.js b/tests/src/viewer-error-text.test.jsnew file mode 100644index 000000000..abe46e213--- /dev/null+++ b/tests/src/viewer-error-text.test.js@@ -0,0 +1,50 @@+import { describe, it, expect } from 'vitest';+import { viewerErrorText } from '../../src/shared/viewer-error-text.js';++// The strings on the left are what three's FileLoader actually rejects with+// (`fetch for "<url>" responded with <status>: <statusText>`), which is what+// /embed/avatar used to paint straight into its error slot.+describe('viewerErrorText', () => {+ it('turns a 5xx transport failure into a retry instruction', () => {+ const raw = 'fetch for "https://three.ws/api/avatars/abc/glb" responded with 502: Bad Gateway';+ expect(viewerErrorText(new Error(raw))).toBe(+ 'The avatar service is unavailable. Refresh to try again.',+ );+ });++ it('tells a signed-out visitor which account they need', () => {+ for (const status of [401, 403]) {+ const raw = `fetch for "https://three.ws/api/avatars/abc/glb" responded with ${status}: Forbidden`;+ expect(viewerErrorText(new Error(raw))).toBe(+ 'This avatar is private. Sign in with the account that owns it.',+ );+ }+ });++ it('reports a missing avatar as gone, not as a permission problem', () => {+ const raw = 'fetch for "https://three.ws/api/avatars/abc/glb" responded with 404: Not Found';+ expect(viewerErrorText(new Error(raw))).toBe('This avatar is no longer available.');+ });++ it('names the network when the request never reached a server', () => {+ expect(viewerErrorText(new TypeError('Failed to fetch'))).toBe(+ 'Connection lost. Check your network and refresh.',+ );+ });++ it('reports an unreadable model file', () => {+ expect(viewerErrorText(new Error('Unexpected token < in JSON at position 0'))).toBe(+ "This avatar's 3D file could not be read.",+ );+ });++ it('keeps a message that was already written for a person', () => {+ const written = 'avatar 00000000-0000-4000-8000-000000000000 not found';+ expect(viewerErrorText(new Error(written))).toBe(written);+ });++ it('never returns an empty string', () => {+ expect(viewerErrorText(undefined)).toBe('Could not load avatar.');+ expect(viewerErrorText(new Error(''))).toBe('Could not load avatar.');+ });+});