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
// api/_lib/avatar-thumbs.js — the module that owns avatar thumbnail coverage.
//
// The invariant under test, and the reason this module exists:
//
// A `thumbnail_key` is only ever persisted AFTER the object behind it has been
// confirmed to exist in R2.
//
// Violating it is not a cosmetic bug. A key pointing at a missing object makes R2
// answer 404 with a `text/plain` body; Chrome then refuses that response for an
// <img> request and logs net::ERR_BLOCKED_BY_ORB. That is exactly what shipped on
// the homepage until 2026-07-09. These tests pin the invariant on both write
// paths (forge-preview adoption and chromium render) so it cannot regress.
import { describe, it, expect, vi, beforeEach } from 'vitest';
// `sql` is a tagged template. Route each call by the SQL text so a test can drive
// the multi-statement flows (select candidates → update → delete claim).
const sqlCalls = [];
let sqlRoutes = [];
// Records every statement, then answers from `sqlRoutes` (first match wins).
// `sqlOrder` lets a test observe write ordering across r2 + db.
const sqlOrder = [];
const defaultSqlImpl = (strings, ...vals) => {
const text = Array.isArray(strings) ? strings.join('?') : String(strings);
sqlCalls.push({ text, vals });
if (/UPDATE avatars/i.test(text)) sqlOrder.push('db');
const handler = sqlRoutes.find((r) => r.match.test(text));
return Promise.resolve(handler ? handler.rows : []);
};
const sqlMock = vi.fn(defaultSqlImpl);
vi.mock('../api/_lib/db.js', () => ({ sql: (...a) => sqlMock(...a) }));
const headObjectMock = vi.fn();
const putObjectMock = vi.fn();
const presignGetMock = vi.fn(async ({ key }) => `https://signed.example/${key}`);
// Only the IO is faked. The failure classifiers come from the real modules: they
// decide whether a failed render costs the avatar one of its three lifetime
// attempts, and a hand-copied stand-in drifts from production silently, which is
// exactly how "spawn EFAULT" ended up retiring four blameless avatars for good.
vi.mock('../api/_lib/r2.js', async (importActual) => ({
...(await importActual()),
headObject: (...a) => headObjectMock(...a),
putObject: (...a) => putObjectMock(...a),
presignGet: (...a) => presignGetMock(...a),
publicUrl: (key) => `https://cdn.example/${key}`,
isLegacyOgThumbnailKey: (k) => /^https?:\/\/.*_og\.png$/i.test(String(k || '')),
}));
const renderGlbToPngMock = vi.fn();
vi.mock('../api/_lib/render-glb.js', async (importActual) => ({
...(await importActual()),
renderGlbToPng: (...a) => renderGlbToPngMock(...a),
}));
const { adoptForgePreviews, renderThumbnail, renderBatch, thumbKeyFor, isMissingThumbnail } =
await import('../api/_lib/avatar-thumbs.js');
const updates = () => sqlCalls.filter((c) => /UPDATE avatars/i.test(c.text));
beforeEach(() => {
sqlCalls.length = 0;
sqlOrder.length = 0;
sqlRoutes = [];
// mockClear() leaves a previous test's mockImplementation in place — reset the
// behaviour, not just the call log, or one test silently starves the next.
sqlMock.mockReset().mockImplementation(defaultSqlImpl);
headObjectMock.mockReset();
putObjectMock.mockReset().mockResolvedValue(undefined);
renderGlbToPngMock.mockReset();
});
describe('isMissingThumbnail — the shared predicate', () => {
it('treats null / empty as missing', () => {
expect(isMissingThumbnail(null)).toBe(true);
expect(isMissingThumbnail('')).toBe(true);
});
it('treats an absolute URL as missing (publicUrl passes it through to an origin with no object)', () => {
expect(isMissingThumbnail('https://three.ws/avatars/michelle_og.png')).toBe(true);
expect(isMissingThumbnail('https://example.com/x.png')).toBe(true);
});
it('treats a relative bucket key as present', () => {
expect(isMissingThumbnail('thumb/abc.png')).toBe(false);
expect(isMissingThumbnail('forge/deadbeef/x-poster.webp')).toBe(false);
});
});
describe('adoptForgePreviews — zero-copy adoption', () => {
it('persists the preview key once the object is confirmed present', async () => {
sqlRoutes = [{ match: /FROM avatars a[\s\S]*JOIN forge_creations/i, rows: [{ id: 'av-1', preview_key: 'forge/aa/bb.jpg' }] }];
headObjectMock.mockResolvedValue({ ContentLength: 1234 });
const res = await adoptForgePreviews({ limit: 10 });
expect(res).toEqual({ adopted: 1, missing: 0 });
expect(headObjectMock).toHaveBeenCalledWith('forge/aa/bb.jpg');
const up = updates();
expect(up).toHaveLength(1);
expect(up[0].vals).toContain('forge/aa/bb.jpg');
});
it('NEVER persists a key when the preview object is absent from R2', async () => {
sqlRoutes = [{ match: /FROM avatars a[\s\S]*JOIN forge_creations/i, rows: [{ id: 'av-1', preview_key: 'forge/gone.jpg' }] }];
headObjectMock.mockResolvedValue(null); // object was pruned
const res = await adoptForgePreviews({ limit: 10 });
expect(res).toEqual({ adopted: 0, missing: 1 });
// This is the whole point: no UPDATE, so no 404 → no ORB.
expect(updates()).toHaveLength(0);
});
it('treats a headObject failure as absent rather than adopting optimistically', async () => {
sqlRoutes = [{ match: /FROM avatars a[\s\S]*JOIN forge_creations/i, rows: [{ id: 'av-1', preview_key: 'forge/x.jpg' }] }];
headObjectMock.mockRejectedValue(new Error('network'));
const res = await adoptForgePreviews({ limit: 10 });
expect(res.adopted).toBe(0);
expect(updates()).toHaveLength(0);
});
it('short-circuits with no candidates', async () => {
sqlRoutes = [];
const res = await adoptForgePreviews({ limit: 10 });
expect(res).toEqual({ adopted: 0, missing: 0 });
expect(headObjectMock).not.toHaveBeenCalled();
});
});
describe('renderThumbnail — render then commit', () => {
it('uploads a PNG under thumb/<id>.png with an image/png content-type', async () => {
renderGlbToPngMock.mockResolvedValue(Buffer.from('fake-png-bytes'));
const r = await renderThumbnail({ id: 'av-9', storage_key: 'u/1/model.glb' });
expect(putObjectMock).toHaveBeenCalledTimes(1);
const arg = putObjectMock.mock.calls[0][0];
expect(arg.key).toBe('thumb/av-9.png');
expect(arg.key).toBe(thumbKeyFor('av-9'));
// A wrong content-type here is the ORB failure mode the audit *thought* it saw.
expect(arg.contentType).toBe('image/png');
expect(r.key).toBe('thumb/av-9.png');
});
it('presigns the durable storage key rather than trusting a stale URL', async () => {
renderGlbToPngMock.mockResolvedValue(Buffer.from('png'));
await renderThumbnail({ id: 'av-9', storage_key: 'u/1/model.glb' });
expect(presignGetMock).toHaveBeenCalledWith(expect.objectContaining({ key: 'u/1/model.glb' }));
expect(renderGlbToPngMock.mock.calls[0][0].glbUrl).toBe('https://signed.example/u/1/model.glb');
});
it('commits thumbnail_key only after the upload resolves', async () => {
renderGlbToPngMock.mockResolvedValue(Buffer.from('png'));
putObjectMock.mockImplementation(async () => { sqlOrder.push('put'); });
await renderThumbnail({ id: 'av-9', storage_key: 'k.glb' });
// Upload first, key second. Reverse this and a failed upload leaves a
// thumbnail_key pointing at nothing — a 404 the browser blocks as ORB.
expect(sqlOrder).toEqual(['put', 'db']);
});
it('throws and writes nothing when the renderer yields no bytes', async () => {
renderGlbToPngMock.mockResolvedValue(Buffer.alloc(0));
await expect(renderThumbnail({ id: 'av-9', storage_key: 'k.glb' })).rejects.toThrow(/no bytes/i);
expect(putObjectMock).not.toHaveBeenCalled();
expect(updates()).toHaveLength(0);
});
it('does not commit a key when the upload fails', async () => {
renderGlbToPngMock.mockResolvedValue(Buffer.from('png'));
putObjectMock.mockRejectedValue(new Error('r2 down'));
await expect(renderThumbnail({ id: 'av-9', storage_key: 'k.glb' })).rejects.toThrow(/r2 down/);
expect(updates()).toHaveLength(0);
});
});
describe('renderBatch — bounded drain', () => {
it('records a failure and keeps going instead of aborting the batch', async () => {
sqlRoutes = [
{ match: /WITH candidates/i, rows: [
{ id: 'ok-1', storage_key: 'a.glb', name: 'Ok' },
{ id: 'bad-1', storage_key: 'b.glb', name: 'Bad' },
] },
];
renderGlbToPngMock.mockImplementation(async ({ glbUrl }) => {
if (glbUrl.includes('b.glb')) throw new Error('corrupt glb');
return Buffer.from('png');
});
const r = await renderBatch({ limit: 2, concurrency: 1 });
expect(r.claimed).toBe(2);
expect(r.rendered).toBe(1);
expect(r.failed).toBe(1);
// The failure is written to the ledger so retries stay bounded.
expect(sqlCalls.some((c) => /avatar_thumbnail_backfill[\s\S]*last_error/i.test(c.text))).toBe(true);
});
it('is a no-op when nothing can be claimed', async () => {
sqlRoutes = [];
const r = await renderBatch({ limit: 5 });
expect(r).toMatchObject({ claimed: 0, rendered: 0, failed: 0 });
expect(renderGlbToPngMock).not.toHaveBeenCalled();
});
// Regression: an OOM-killed chromium made every subsequent render fail in
// milliseconds with "Connection closed.". The batch ground through the whole
// queue charging a retry to each, and 1,283 perfectly renderable avatars were
// permanently retired for a crash that had nothing to do with their models.
describe('when the browser dies mid-batch', () => {
const threeJobs = [
{ match: /WITH candidates/i, rows: [
{ id: 'a-1', storage_key: 'a.glb', name: 'A' },
{ id: 'a-2', storage_key: 'b.glb', name: 'B' },
{ id: 'a-3', storage_key: 'c.glb', name: 'C' },
] },
];
it('aborts the batch instead of burning every model\'s retries', async () => {
sqlRoutes = threeJobs;
renderGlbToPngMock.mockRejectedValue(new Error('Connection closed.'));
const r = await renderBatch({ limit: 3, concurrency: 1 });
expect(r.aborted).toMatch(/connection closed/i);
expect(r.rendered).toBe(0);
// Exactly one job was attempted; the batch stopped rather than cascading.
expect(renderGlbToPngMock).toHaveBeenCalledTimes(1);
expect(r.failed).toBe(0); // an infra abort is not a model failure
});
it('gives back the attempt it charged, for the aborted AND untouched jobs', async () => {
sqlRoutes = threeJobs;
renderGlbToPngMock.mockRejectedValue(new Error('Connection closed.'));
await renderBatch({ limit: 3, concurrency: 1 });
const rollbacks = sqlCalls.filter((c) => /attempts\s*=\s*greatest\(0, attempts - 1\)/i.test(c.text));
// One for the job that hit the dead browser, two for the ones never started.
expect(rollbacks).toHaveLength(3);
// And nothing was recorded as a model-attributable failure.
expect(sqlCalls.some((c) => /SET last_error/i.test(c.text))).toBe(false);
});
it('still charges a retry for a genuinely broken model', async () => {
sqlRoutes = threeJobs;
renderGlbToPngMock.mockRejectedValue(new Error('glb fetch failed: upstream returned 404'));
const r = await renderBatch({ limit: 3, concurrency: 1 });
expect(r.aborted).toBe(false);
expect(r.failed).toBe(3); // every model tried, every one blamed
expect(sqlCalls.filter((c) => /SET last_error/i.test(c.text))).toHaveLength(3);
expect(sqlCalls.some((c) => /attempts - 1/i.test(c.text))).toBe(false);
});
});
});