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(ar): give the AR page a real error state instead of one grey line and a dead end

nirholasda2cd8e2dc22
diff --git a/pages/ar.html b/pages/ar.html
index f4700a109..a1c5ac7fe 100644
--- a/pages/ar.html
+++ b/pages/ar.html
@@ -13,6 +13,7 @@
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png" />
<link rel="apple-touch-icon" href="/apple-touch-icon.png" />
<link rel="manifest" href="/manifest.webmanifest" />
+ <link rel="stylesheet" href="/tokens.css" />
<link rel="stylesheet" href="/fonts/fonts.css" />
<meta name="description" content="Type a prompt, get a real 3D model, and place it in your room: free text-to-3D with one-tap AR on any phone (WebXR, Scene Viewer, Quick Look) and a QR handoff from desktop." data-i18n-attr="content:ar.meta_description" />
<meta name="robots" content="index, follow, max-image-preview:large, max-snippet:-1" />
@@ -40,17 +41,29 @@
<script type="module" src="/src/ar-page.js"></script>
<style>
- :root {
+ /* Dark-only theme layer (QB-07). An AR page renders a model against a
+ dark studio ground in either theme, so it pins the canonical
+ primitives to their dark values and aliases its local names to
+ them rather than forking a second palette. The doubled :root is a
+ specificity bump over the token sheet's own light block. */
+ :root,
+ :root:root[data-theme='light'] {
+ color-scheme: dark;
+ --bg-0: #0a0a0a;
+ --ink: #e8e8e8;
+ --ink-dim: #888888;
+ --accent: #ffffff;
+ --danger: #f87171;
+
--bg: #000000;
- --bg2: #0a0a0a;
- --text: #e8e8e8;
- --text-2: #888888;
+ --bg2: var(--bg-0);
+ --text: var(--ink);
+ --text-2: var(--ink-dim);
--text-3: #555555;
- --accent: #ffffff;
- --accent-2: #ffffff;
- --panel: rgba(255, 255, 255, 0.04);
- --border: rgba(255, 255, 255, 0.08);
- --radius: 14px;
+ --accent-2: var(--accent);
+ --panel: var(--surface-1);
+ --border: var(--stroke);
+ --radius: var(--radius-lg);
}
*,
@@ -406,16 +419,81 @@
.ar-footer-link:hover { color: var(--text-2); }
.ar-footer-sep { font-size: 12px; color: var(--text-3); }
- /* ── Loading / error fallback ─────────────────── */
+ /* ── Error state ──────────────────────────────────
+ The only thing a visitor sees when a link is stale, an agent has
+ no body yet, or a fetch fails. It used to be one line of grey
+ text on a black page with nowhere to go, which is a dead end
+ dressed as a message. It is a panel now: what happened, in plain
+ language, and at least one action that always works. */
.ar-error {
display: flex;
+ flex-direction: column;
align-items: center;
justify-content: center;
+ gap: var(--space-sm);
height: 100%;
- color: var(--text-2);
- font-size: 15px;
+ padding: var(--space-xl) var(--space-md);
text-align: center;
- padding: 2rem;
+ outline: none;
+ }
+ .ar-error__title {
+ margin: 0;
+ font-size: clamp(18px, 4.5vw, 22px);
+ font-weight: 600;
+ letter-spacing: -0.01em;
+ color: var(--text);
+ }
+ .ar-error__body {
+ margin: 0;
+ max-width: 42ch;
+ font-size: 15px;
+ line-height: var(--leading-normal);
+ color: var(--text-2);
+ }
+ .ar-error__actions {
+ display: flex;
+ flex-wrap: wrap;
+ justify-content: center;
+ gap: var(--space-xs);
+ margin-top: var(--space-xs);
+ }
+ .ar-error__btn {
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ min-height: 44px;
+ padding: 0 var(--space-lg);
+ border-radius: var(--radius-pill);
+ border: 1px solid var(--border);
+ background: var(--panel);
+ color: var(--text);
+ font: inherit;
+ font-size: 14px;
+ font-weight: 600;
+ text-decoration: none;
+ cursor: pointer;
+ transition:
+ background var(--duration-fast) var(--ease-standard),
+ border-color var(--duration-fast) var(--ease-standard),
+ color var(--duration-fast) var(--ease-standard),
+ transform var(--duration-fast) var(--ease-standard);
+ }
+ .ar-error__btn:hover {
+ border-color: var(--accent);
+ background: var(--surface-2);
+ color: var(--ink-bright);
+ }
+ .ar-error__btn:active {
+ transform: translateY(1px);
+ }
+ .ar-error__btn--primary {
+ background: var(--accent);
+ border-color: transparent;
+ color: var(--on-accent);
+ }
+ .ar-error__btn--primary:hover {
+ background: var(--btn-primary-bg-hover, #ffffff);
+ color: var(--on-accent);
}
</style>
<script src="/model-viewer-meshopt.js"></script>
diff --git a/src/ar-page.js b/src/ar-page.js
index a6a1d3f52..b9f6a4c08 100644
--- a/src/ar-page.js
+++ b/src/ar-page.js
@@ -32,7 +32,12 @@ let usdzObjectUrl = null;
async function init() {
if (!entityId) {
- showError(`No ${mode} specified.`);
+ showError(
+ `This link does not name a${mode === 'agent' ? 'n agent' : 'n avatar'} to show, so there is nothing to place in your room.`,
+ mode === 'agent'
+ ? { browseHref: '/agents', browseLabel: 'Browse agents' }
+ : {},
+ );
return;
}
@@ -40,7 +45,10 @@ async function init() {
const agent = await fetchAgent(entityId);
if (!agent) return;
if (!agent.avatar_id) {
- showError(`${agent.name || 'This agent'} has no 3D body yet.`);
+ showError(
+ `${agent.name || 'This agent'} has no 3D body yet, so there is nothing to place in your room. Give it one in the studio, then come back.`,
+ { browseHref: '/create', browseLabel: 'Create a body' },
+ );
return;
}
avatarId = agent.avatar_id;
@@ -51,7 +59,9 @@ async function init() {
const glbUrl = avatar.model_url || avatar.url;
if (!glbUrl) {
- showError('This avatar has no 3D model.');
+ showError(
+ 'This avatar has no 3D model attached yet, so there is nothing to place in your room.',
+ );
return;
}
@@ -72,7 +82,7 @@ async function fetchAvatar(id) {
if (!r.ok) throw new Error(`${r.status}`);
return (await r.json()).avatar;
} catch (err) {
- showError(`Couldn't load avatar (${err.message}).`);
+ showError(`We could not load this avatar (${err.message}).`, { retry: true });
return null;
}
}
@@ -83,7 +93,11 @@ async function fetchAgent(id) {
if (!r.ok) throw new Error(`${r.status}`);
return (await r.json()).agent;
} catch (err) {
- showError(`Couldn't load agent (${err.message}).`);
+ showError(`We could not load this agent (${err.message}).`, {
+ retry: true,
+ browseHref: '/agents',
+ browseLabel: 'Browse agents',
+ });
return null;
}
}
@@ -193,9 +207,56 @@ async function generateUsdz(glbUrl) {
}
}
-function showError(msg) {
+/**
+ * Replace the whole shell with a designed error state.
+ *
+ * This is the only thing a visitor sees when a link is stale, an agent has no
+ * body yet, or a fetch fails, and until now it was one unstyled line of text
+ * against a black page with nowhere to go. Every message therefore ships with
+ * a way out: a browse link that is always correct, plus a retry when the
+ * failure could be transient (a network hiccup, a cold API) rather than a
+ * statement about this particular avatar.
+ *
+ * @param {string} msg What went wrong, in plain language.
+ * @param {{ retry?: boolean, browseHref?: string, browseLabel?: string }} [opts]
+ */
+function showError(msg, opts = {}) {
const shell = $('ar-shell');
- if (shell) shell.innerHTML = `<div class="ar-error">${msg}</div>`;
+ if (!shell) return;
+ const { retry = false, browseHref = '/avatars', browseLabel = 'Browse avatars' } = opts;
+ const panel = document.createElement('div');
+ panel.className = 'ar-error';
+ panel.setAttribute('role', 'alert');
+
+ const title = document.createElement('h2');
+ title.className = 'ar-error__title';
+ title.textContent = 'This avatar cannot open in AR';
+ const body = document.createElement('p');
+ body.className = 'ar-error__body';
+ body.textContent = msg;
+ const actions = document.createElement('div');
+ actions.className = 'ar-error__actions';
+
+ if (retry) {
+ const again = document.createElement('button');
+ again.type = 'button';
+ again.className = 'ar-error__btn ar-error__btn--primary';
+ again.textContent = 'Try again';
+ again.addEventListener('click', () => location.reload());
+ actions.append(again);
+ }
+ const browse = document.createElement('a');
+ browse.className = retry ? 'ar-error__btn' : 'ar-error__btn ar-error__btn--primary';
+ browse.href = browseHref;
+ browse.textContent = browseLabel;
+ actions.append(browse);
+
+ panel.append(title, body, actions);
+ shell.replaceChildren(panel);
+ // Move focus to the alert so a screen reader and a keyboard user both land
+ // on the recovery path instead of at the top of a page that no longer exists.
+ panel.tabIndex = -1;
+ panel.focus();
}
async function shareAvatar(avatar) {
@@ -251,7 +312,7 @@ document.addEventListener('DOMContentLoaded', () => {
init().catch((err) => {
log.error('[ar-page] init error', err);
- showError('Something went wrong loading this avatar.');
+ showError('Something went wrong loading this avatar.', { retry: true });
});
window.addEventListener('beforeunload', () => {