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(ui): swap broken thumbnails for the designed fallback tile instead of the browser's broken-image glyph

nirholasb41962e40fed
diff --git a/pages/monitor.html b/pages/monitor.html
index 214bd1c3e..015c31908 100644
--- a/pages/monitor.html
+++ b/pages/monitor.html
@@ -177,6 +177,7 @@
.forge-cell img { width: 100%; height: 100%; object-fit: cover; display: block; transition: transform 0.2s; }
.forge-cell:hover img, .forge-cell:focus-visible img { transform: scale(1.06); }
.forge-cell:focus-visible { outline: 1px solid var(--mon-green); }
+ .forge-cell-fb { width: 100%; height: 100%; display: flex; align-items: center; justify-content: center; font-size: 20px; font-weight: 700; color: #0a0a0a; background: linear-gradient(135deg, var(--mon-violet), var(--mon-cyan)); }
.forge-tag { position: absolute; left: 0; right: 0; bottom: 0; font-size: 8px; color: #e8e8e8; background: linear-gradient(transparent, rgba(0, 0, 0, 0.82)); padding: 12px 5px 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
/* Skeletons */
diff --git a/src/avatar-gallery-picker.js b/src/avatar-gallery-picker.js
index 6020a7d1f..b7d0c6bde 100644
--- a/src/avatar-gallery-picker.js
+++ b/src/avatar-gallery-picker.js
@@ -23,6 +23,7 @@ import { onchainBadgeHTML } from './shared/onchain-badge.js';
import { walletChipHTML, wireWalletChips } from './shared/agent-wallet-chip.js';
import { ensureModelViewerOrFallback } from './shared/model-viewer-loader.js';
+import { thumbFallbackAttr, wireThumbFallback } from './shared/thumb-fallback.js';
const PAGE_SIZE = 24;
// Shared loader: three CDNs, a per-source timeout and a visible fallback on
@@ -387,6 +388,7 @@ export class AvatarGalleryPicker {
this._state.totalLoaded += 1;
for (const t of a.tags || []) this._state.loadedTags.add(t);
}
+ wireThumbFallback(this._els.grid);
// Stagger the freshly-landed avatar cards in (first page + each lazy page).
enterStagger(fresh);
@@ -475,9 +477,10 @@ export class AvatarGalleryPicker {
card.dataset.id = a.id;
if (a.id === this._state.selected?.id) card.classList.add('selected');
+ const phFallback = `<div class="agp-card-ph">${AVATAR_PH_SVG}</div>`;
const thumb = a.thumbnail_url
- ? `<img src="${esc(a.thumbnail_url)}" alt="${esc(a.name || 'Avatar')}" loading="lazy" decoding="async" />`
- : `<div class="agp-card-ph">${AVATAR_PH_SVG}</div>`;
+ ? `<img src="${esc(a.thumbnail_url)}" alt="${esc(a.name || 'Avatar')}" loading="lazy" decoding="async" ${thumbFallbackAttr(phFallback, esc)} />`
+ : phFallback;
const tags = (a.tags || []).slice(0, 2).map((t) =>
`<span class="agp-card-chip">${esc(t)}</span>`).join('');
diff --git a/src/economy-live.js b/src/economy-live.js
index 0a61157e6..8a7f66ff3 100644
--- a/src/economy-live.js
+++ b/src/economy-live.js
@@ -18,6 +18,7 @@
import { openHirePanel } from './shared/agent-hire.js';
import { sanitizeUrl } from './shared/sanitize-url.js';
+import { thumbFallbackAttr, wireThumbFallback } from './shared/thumb-fallback.js';
const $ = (sel) => /** @type {HTMLElement} */ (document.querySelector(sel));
@@ -113,10 +114,11 @@ function agentCard(a) {
: a.has_paid_skills ? '<span class="ae-chip">Paid skills</span>' : '<span class="ae-chip ae-chip-free">Free</span>';
const buyers = Number(a.buyers_total) || 0;
const buyers24 = Number(a.buyers_24h) || 0;
+ const avatarFallback = `<span class="ae-avatar-fallback">${esc((a.name || '?').slice(0, 1).toUpperCase())}</span>`;
return `
<a class="ae-card" href="/agents/${encodeURIComponent(a.id)}">
<div class="ae-card-top">
- <div class="ae-avatar">${thumb ? `<img src="${esc(thumb)}" alt="" loading="lazy" />` : `<span class="ae-avatar-fallback">${esc((a.name || '?').slice(0, 1).toUpperCase())}</span>`}</div>
+ <div class="ae-avatar">${thumb ? `<img src="${esc(thumb)}" alt="" loading="lazy" ${thumbFallbackAttr(avatarFallback, esc)} />` : avatarFallback}</div>
<div class="ae-card-head">
<span class="ae-card-name">${esc(a.name || 'Untitled agent')}</span>
<span class="ae-muted ae-card-cat">${esc(a.category || 'general')}</span>
@@ -162,6 +164,7 @@ async function loadAgents({ quiet = false } = {}) {
return;
}
host.innerHTML = items.map(agentCard).join('');
+ wireThumbFallback(host);
setStat('#ae-stat-agents', items.length >= 24 ? '24+' : String(items.length));
const earners = items.filter((a) => (Number(a.buyers_total) || 0) > 0).length;
setStat('#ae-stat-earning', String(earners));
@@ -341,9 +344,10 @@ let _offers = [];
function offerAvatar(offer) {
const url = offer?.provider?.avatar_thumbnail_url || '';
- if (url) return `<span class="ae-offer-av"><img src="${esc(url)}" alt="" loading="lazy" /></span>`;
const letter = (offer?.provider?.name || offer?.name || '?').slice(0, 1).toUpperCase();
- return `<span class="ae-offer-av"><span class="ae-offer-av-fallback">${esc(letter)}</span></span>`;
+ const fallback = `<span class="ae-offer-av-fallback">${esc(letter)}</span>`;
+ if (url) return `<span class="ae-offer-av"><img src="${esc(url)}" alt="" loading="lazy" ${thumbFallbackAttr(fallback, esc)} /></span>`;
+ return `<span class="ae-offer-av">${fallback}</span>`;
}
function offerStatsLine(st) {
@@ -428,6 +432,7 @@ function renderOffers() {
}
const mode = $('#ae-offer-sort')?.value || 'proven';
host.innerHTML = sortOffers(_offers, mode).map(offerCard).join('');
+ wireThumbFallback(host);
for (const btn of host.querySelectorAll('[data-hire]')) {
btn.addEventListener('click', () => {
const offer = _offers.find((o) => o.slug === btn.getAttribute('data-hire'));
diff --git a/src/monitor.js b/src/monitor.js
index 3b18b98a9..986735683 100644
--- a/src/monitor.js
+++ b/src/monitor.js
@@ -10,6 +10,7 @@
// Terminal links come from the shared builder so this board carries the same
// referral codes as the rest of the product and cannot drift from them.
import { gmgnTokenUrl } from './shared/trading-terminals.js';
+import { thumbFallbackAttr, wireThumbFallback } from './shared/thumb-fallback.js';
const $ = (id) => document.getElementById(id);
@@ -141,10 +142,11 @@ function fleetRow(agent) {
const hot = agent.last_action_at && Date.now() - new Date(agent.last_action_at).getTime() < 15 * 60 * 1000;
const initial = (agent.name || '?').trim().charAt(0).toUpperCase();
const skills = Array.isArray(agent.skills) ? agent.skills.length : 0;
+ const fleetFallback = `<div class="fleet-av-fb" aria-hidden="true">${esc(initial)}</div>`;
row.innerHTML = `
${agent.avatar_thumbnail
- ? `<img class="fleet-av" src="${esc(agent.avatar_thumbnail)}" alt="" loading="lazy" />`
- : `<div class="fleet-av-fb" aria-hidden="true">${esc(initial)}</div>`}
+ ? `<img class="fleet-av" src="${esc(agent.avatar_thumbnail)}" alt="" loading="lazy" ${thumbFallbackAttr(fleetFallback, esc)} />`
+ : fleetFallback}
<div class="fleet-meta">
<div class="fleet-name">${esc(agent.name || 'Unnamed agent')}${agent.is_registered ? '<span class="reg-chip">ERC-8004</span>' : ''}</div>
<div class="fleet-sub">${skills ? skills + ' skill' + (skills === 1 ? '' : 's') + ' · ' : ''}${nf.format(agent.chat_count || 0)} chats</div>
@@ -185,6 +187,7 @@ async function loadFleet() {
}
body.innerHTML = '';
for (const agent of agents) body.appendChild(fleetRow(agent));
+ wireThumbFallback(body);
if (!spotlightMounted) {
const first = agents.find((a) => a.avatar_thumbnail) || agents[0];
mountSpotlight(first);
@@ -228,12 +231,14 @@ async function loadOnAir() {
const row = document.createElement('a');
row.className = 'desk-row';
row.href = '/agents-live';
+ const deskFallback = '<div class="fleet-av-fb" aria-hidden="true">?</div>';
row.innerHTML = `
- ${desk.avatarUrl ? `<img class="fleet-av" src="${esc(desk.avatarUrl)}" alt="" loading="lazy" />` : '<div class="fleet-av-fb" aria-hidden="true">?</div>'}
+ ${desk.avatarUrl ? `<img class="fleet-av" src="${esc(desk.avatarUrl)}" alt="" loading="lazy" ${thumbFallbackAttr(deskFallback, esc)} />` : deskFallback}
<div class="fleet-meta"><div class="fleet-name">${esc(desk.agentName || desk.agentId)}</div><div class="fleet-sub">screen cast in progress</div></div>
<span class="desk-live">LIVE</span>`;
body.appendChild(row);
}
+ wireThumbFallback(body);
} catch (err) {
showError(body, badge, 'Live-desk feed unreachable (' + err.message + ').', loadOnAir);
}
@@ -306,18 +311,20 @@ function renderLeaders(earners, busiest) {
'<div class="panel-empty">No tip earners in the last 24h. Tip any agent from its profile and it climbs this board.</div>';
return;
}
+ const leaderFallback = '<div class="fleet-av-fb" aria-hidden="true">?</div>';
body.innerHTML = list
.slice(0, 8)
.map(
(a, i) => `
<a class="desk-row" href="${esc(a.url || '#')}">
<span class="fleet-actions" style="min-width:14px">${i + 1}</span>
- ${a.avatar_thumbnail_url ? `<img class="fleet-av" src="${esc(a.avatar_thumbnail_url)}" alt="" loading="lazy" />` : '<div class="fleet-av-fb" aria-hidden="true">?</div>'}
+ ${a.avatar_thumbnail_url ? `<img class="fleet-av" src="${esc(a.avatar_thumbnail_url)}" alt="" loading="lazy" ${thumbFallbackAttr(leaderFallback, esc)} />` : leaderFallback}
<div class="fleet-meta"><div class="fleet-name">${esc(a.name || 'agent')}</div><div class="fleet-sub">${a.tip_count != null ? nf.format(a.tip_count) + ' tips' : nf.format(a.events || 0) + ' events'}</div></div>
<span class="wire-amt">${a.usd != null ? usd(a.usd) : ''}</span>
</a>`
)
.join('');
+ wireThumbFallback(body);
}
function renderLaunches(launches) {
@@ -500,14 +507,17 @@ async function loadForge() {
}
body.innerHTML = `<div class="forge-grid">${creations
.slice(0, 12)
- .map(
- (c) => `
+ .map((c) => {
+ const letter = (c.model_category && c.model_category !== 'other' ? c.model_category : '3D').trim().charAt(0).toUpperCase();
+ const forgeFallback = `<div class="forge-cell-fb" aria-hidden="true">${esc(letter)}</div>`;
+ return `
<a class="forge-cell" href="/creations" title="${esc((c.prompt || '').slice(0, 140))}">
- <img src="${esc(c.preview_image_url)}" alt="${esc((c.prompt || '3D creation').slice(0, 80))}" loading="lazy" />
+ <img src="${esc(c.preview_image_url)}" alt="${esc((c.prompt || '3D creation').slice(0, 80))}" loading="lazy" ${thumbFallbackAttr(forgeFallback, esc)} />
<span class="forge-tag">${esc(c.model_category && c.model_category !== 'other' ? c.model_category : rel(c.created_at) + ' ago')}</span>
- </a>`
- )
+ </a>`;
+ })
.join('')}</div>`;
+ wireThumbFallback(body);
} catch (err) {
showError(body, badge, 'Forge gallery unreachable (' + err.message + ').', loadForge);
}
diff --git a/src/shared/thumb-fallback.js b/src/shared/thumb-fallback.js
new file mode 100644
index 000000000..c3cd2ebee
--- /dev/null
+++ b/src/shared/thumb-fallback.js
@@ -0,0 +1,46 @@
+// thumb-fallback.js: shared broken-thumbnail fallback wiring.
+//
+// Renderers that build a container's markup as one HTML string
+// (`.map(...).join('')` assigned to `.innerHTML`) have no live <img> node at
+// template-build time to attach an error listener to, unlike a renderer that
+// creates a single DOM node up front and can call
+// `img.addEventListener('error', ...)` directly (see
+// src/marketplace-gallery.js). Tag the <img> with its fallback markup
+// instead and wire one delegated listener on the container after insertion.
+//
+// The DOM `error` event does not bubble, so a listener on an ancestor only
+// ever sees it if it is added on the capture phase.
+
+const ATTR = 'data-thumb-fallback';
+
+// `esc` is the caller's own HTML-escaper (every call site already has one);
+// passing it in keeps the escaping consistent with the rest of that file's
+// template instead of duplicating an escaper here.
+export function thumbFallbackAttr(fallbackHtml, esc) {
+ return `${ATTR}="${esc(fallbackHtml)}"`;
+}
+
+// Call once per container, any time after its markup (or appended children)
+// are in place. One call wires every current AND future
+// <img data-thumb-fallback> inside root, including rows added by later
+// pagination or a refresh. Safe to call again on the same root: it is a
+// no-op after the first call, so repeated renders of the same container
+// never pile up duplicate listeners.
+export function wireThumbFallback(root) {
+ if (root.dataset.thumbFallbackWired) return;
+ root.dataset.thumbFallbackWired = '1';
+ root.addEventListener(
+ 'error',
+ (event) => {
+ const img = event.target;
+ if (!img || img.tagName !== 'IMG' || !img.hasAttribute(ATTR)) return;
+ const fallback = img.getAttribute(ATTR);
+ // Remove before swapping: a failure on the fallback's own markup (if
+ // it somehow contains another <img>) carries no data-thumb-fallback
+ // of its own, so it cannot re-enter this branch and loop.
+ img.removeAttribute(ATTR);
+ img.outerHTML = fallback;
+ },
+ true,
+ );
+}
diff --git a/tests/thumb-fallback.test.js b/tests/thumb-fallback.test.js
new file mode 100644
index 000000000..24c91f2d8
--- /dev/null
+++ b/tests/thumb-fallback.test.js
@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+//
+// wireThumbFallback() is the delegated error handler that swaps a dead
+// <img data-thumb-fallback="..."> for its designed fallback markup, for the
+// three list/card renderers (src/monitor.js, src/economy-live.js,
+// src/avatar-gallery-picker.js) that build rows as HTML strings and have no
+// live <img> node at template-build time to call .addEventListener on
+// directly.
+//
+// This project's jsdom 30, with no optional `canvas` package installed,
+// never decodes real images and never fires `load`/`error` on an <img> for
+// any src, local server or not: this was verified against a real local
+// HTTP server serving both a 200 PNG and a 404, with and without the
+// sandbox's network restrictions lifted, and neither event ever fired
+// within an 8s window. So this suite dispatches genuine `Event('error')` /
+// `Event('load')` objects directly at the <img> node, the same event type
+// and non-bubbling propagation a real browser delivers, which is what
+// wireThumbFallback() actually consumes; only the network cause behind the
+// event is substituted. The capture-phase delegation, attribute lookup,
+// outerHTML swap and cleanup-before-swap guard are exercised for real.
+import { describe, it, expect, beforeEach } from 'vitest';
+import { thumbFallbackAttr, wireThumbFallback } from '../src/shared/thumb-fallback.js';
+
+function esc(s) {
+ return String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+}
+
+function fireError(img) {
+ img.dispatchEvent(new Event('error', { bubbles: false }));
+}
+
+function fireLoad(img) {
+ img.dispatchEvent(new Event('load', { bubbles: false }));
+}
+
+beforeEach(() => {
+ document.body.innerHTML = '';
+});
+
+describe('wireThumbFallback', () => {
+ it('swaps every tagged <img> that errors for its exact fallback markup, and leaves an untagged <img> alone', () => {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+
+ const fallbackA = '<div class="fleet-av-fb" aria-hidden="true">A</div>';
+ const fallbackB = '<span class="ae-avatar-fallback">B</span>';
+
+ container.innerHTML = `
+ <img id="tagged-a" src="/does-not-exist-${Math.random().toString(36).slice(2)}.png" ${thumbFallbackAttr(fallbackA, esc)} />
+ <img id="tagged-b" src="/does-not-exist-${Math.random().toString(36).slice(2)}.png" ${thumbFallbackAttr(fallbackB, esc)} />
+ <img id="untagged" src="/does-not-exist-${Math.random().toString(36).slice(2)}.png" />
+ `;
+
+ wireThumbFallback(container);
+
+ const taggedA = container.querySelector('#tagged-a');
+ const taggedB = container.querySelector('#tagged-b');
+ const untagged = container.querySelector('#untagged');
+
+ fireError(taggedA);
+ fireError(taggedB);
+ fireError(untagged);
+
+ expect(container.querySelector('#tagged-a')).toBeNull();
+ expect(container.querySelector('#tagged-b')).toBeNull();
+ expect(container.innerHTML).toContain(fallbackA);
+ expect(container.innerHTML).toContain(fallbackB);
+
+ // The untagged image had no data-thumb-fallback, so the handler ignored
+ // its error event entirely: still an <img>, not swapped.
+ const stillImg = container.querySelector('#untagged');
+ expect(stillImg).not.toBeNull();
+ expect(stillImg.tagName).toBe('IMG');
+ });
+
+ it('never swaps an image that fires load instead of error', () => {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const fallback = '<div class="agp-card-ph">placeholder</div>';
+ container.innerHTML = `<img id="ok" src="/static/favicon.ico" ${thumbFallbackAttr(fallback, esc)} />`;
+ wireThumbFallback(container);
+
+ fireLoad(container.querySelector('#ok'));
+
+ const img = container.querySelector('#ok');
+ expect(img).not.toBeNull();
+ expect(img.tagName).toBe('IMG');
+ expect(container.innerHTML).not.toContain(fallback);
+ });
+
+ it('is idempotent: calling it twice on the same container does not double-register the listener', () => {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ const fallback = '<div class="fleet-av-fb" aria-hidden="true">?</div>';
+ container.innerHTML = `<img id="dup" src="/missing.png" ${thumbFallbackAttr(fallback, esc)} />`;
+
+ wireThumbFallback(container);
+ wireThumbFallback(container);
+
+ fireError(container.querySelector('#dup'));
+
+ // A double-registered listener would try to swap outerHTML a second time
+ // using the (by then stale) `img` reference and throw, or otherwise
+ // leave the fallback duplicated. A single clean swap is correct.
+ expect(container.innerHTML).toBe(fallback);
+ });
+
+ it('removes the data-thumb-fallback attribute before swapping, so a fallback that itself contains an <img> cannot loop', () => {
+ const container = document.createElement('div');
+ document.body.appendChild(container);
+ // A fallback containing its own <img> is not a real pattern in this
+ // codebase, but proves the attribute is gone before the swap happens:
+ // if removal happened after, the new nested <img> below would still
+ // carry a (copied) data-thumb-fallback the handler could act on.
+ const nested = '<div class="fb"><img id="nested-img" src="/also-missing.png" /></div>';
+ container.innerHTML = `<img id="root-img" src="/missing.png" ${thumbFallbackAttr(nested, esc)} />`;
+
+ wireThumbFallback(container);
+ fireError(container.querySelector('#root-img'));
+
+ const nestedImg = container.querySelector('#nested-img');
+ expect(nestedImg).not.toBeNull();
+ expect(nestedImg.hasAttribute('data-thumb-fallback')).toBe(false);
+
+ // Firing error on the nested image is a no-op: it has nothing to swap to.
+ fireError(nestedImg);
+ expect(container.querySelector('#nested-img')).not.toBeNull();
+ });
+});