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
// The asset-catalog MCP tools (api/_mcp/tools/library.js) and the two libraries
// under them: the manifest join (api/_lib/asset-catalog.js) and the snippet
// builder (api/_lib/asset-snippets.js).
//
// The public CDN read (r2.getPublicObjectBuffer, the export asset-catalog.js
// actually imports) is stubbed with manifests shaped exactly like the published
// ones: the field names and the "collection: x" category convention come from
// the live objects/avatars/animations manifests, so the suite exercises the real
// join, the real ranking, and the real code generation without a network call.
import { describe, it, expect, beforeEach, vi } from 'vitest';
const MANIFESTS = {
'objects/library/manifest.json': {
generated_at: '2026-09-01T00:00:00.000Z',
objects: [
{
name: 'adjustable_wrench',
label: 'Adjustable Wrench',
url: 'https://cdn.test/objects/adjustable_wrench.glb',
thumb: 'https://cdn.test/objects/adjustable_wrench.png',
bytes: 2639744,
categories: ['collection: project_lighthouse', 'props', 'tools'],
tags: ['vintage', 'garage', 'hand tool'],
license: 'CC0',
},
{
name: 'wooden_chair',
label: 'Wooden Chair',
url: 'https://cdn.test/objects/wooden_chair.glb',
thumb: 'https://cdn.test/objects/wooden_chair.png',
bytes: 1048576,
categories: ['furniture'],
tags: ['wood', 'seating'],
license: 'CC0',
},
{
name: 'IV_pole_a01',
label: 'IV Pole',
url: 'https://cdn.test/objects/simready/IV_pole_a01.glb',
thumb: 'https://cdn.test/objects/simready/IV_pole_a01.webp',
bytes: 3124000,
categories: ['simready', 'hospital'],
tags: ['iv', 'pole'],
license: 'CC-BY-4.0',
attribution: 'NVIDIA SimReady Assets, CC BY 4.0, https://huggingface.co/datasets/nvidia/simready-assets',
source: 'simready',
},
],
},
'avatars/library/manifest.json': {
avatars: [
{
name: 'abe',
label: 'Abe',
url: 'https://cdn.test/avatars/abe.glb',
thumb: 'https://cdn.test/avatars/abe.png',
bytes: 35947032,
skins: 1,
animations: 1,
source: 'mixamo',
license: 'Mixamo',
},
],
},
'animations/library/manifest.json': {
clips: [
{
name: 'mx-wave-abc123',
label: 'Wave',
url: 'https://cdn.test/animations/mx-wave-abc123.json',
thumb: 'https://cdn.test/animations/mx-wave-abc123.webp',
duration: 2.5,
loop: false,
icon: '👋',
},
],
},
// The generated catalog may not exist yet; a missing key must degrade to
// empty rather than failing the whole catalog.
'animations/library/generated/manifest.json': null,
};
const getPublicObjectBuffer = vi.fn(async (key) => {
const value = MANIFESTS[key];
if (value == null) {
const err = new Error('NoSuchKey');
err.name = 'NoSuchKey';
throw err;
}
return Buffer.from(JSON.stringify(value), 'utf8');
});
vi.mock('../../api/_lib/r2.js', () => ({ getPublicObjectBuffer }));
const { searchCatalog, getCatalogItem, relatedItems, resetCatalogCache } = await import(
'../../api/_lib/asset-catalog.js'
);
const { sourceFor, snippetFor, frameworksFor, agentElementRelease } = await import(
'../../api/_lib/asset-snippets.js'
);
const { toolDefs } = await import('../../api/_mcp/tools/library.js');
const { isPublicTool } = await import('../../api/_mcp/dispatch.js');
const tool = (name) => toolDefs.find((t) => t.name === name);
const req = { headers: { host: 'three.ws' } };
beforeEach(() => {
resetCatalogCache();
getPublicObjectBuffer.mockClear();
});
describe('catalog join', () => {
it('reads all three libraries into one normalized list', async () => {
const res = await searchCatalog({ limit: 50 });
expect(res.total).toBe(5);
expect(res.items.map((i) => i.id).sort()).toEqual([
'animation:mx-wave-abc123',
'character:abe',
'object:IV_pole_a01',
'object:adjustable_wrench',
'object:wooden_chair',
]);
});
it('lifts "collection: x" out of the browsable categories', async () => {
const item = await getCatalogItem('object:adjustable_wrench');
expect(item.categories).toEqual(['props', 'tools']);
expect(item.collection).toBe('project_lighthouse');
});
it('degrades to empty for a manifest that was never published', async () => {
// The generated animation manifest throws NoSuchKey above; the catalog
// still holds the curated clip.
const res = await searchCatalog({ kind: 'animation', limit: 50 });
expect(res.items).toHaveLength(1);
});
it('memoizes the manifests so repeat searches do not re-read storage', async () => {
await searchCatalog({ q: 'chair' });
const afterFirst = getPublicObjectBuffer.mock.calls.length;
await searchCatalog({ q: 'wrench' });
expect(getPublicObjectBuffer.mock.calls.length).toBe(afterFirst);
});
});
describe('attribution', () => {
it('carries a CC BY attribution line through to the catalog item', async () => {
const item = await getCatalogItem('object:IV_pole_a01');
expect(item.license).toBe('CC-BY-4.0');
expect(item.attribution).toMatch(/NVIDIA SimReady Assets/);
});
it('leaves attribution off CC0 items that do not need one', async () => {
expect((await getCatalogItem('object:wooden_chair')).attribution).toBeUndefined();
});
});
describe('ranking', () => {
it('ranks a title match above a tag match', async () => {
const res = await searchCatalog({ q: 'wrench' });
expect(res.items[0].id).toBe('object:adjustable_wrench');
});
it('requires every term to match, so a two-word query does not return everything', async () => {
const res = await searchCatalog({ q: 'wooden chair' });
expect(res.items.map((i) => i.id)).toEqual(['object:wooden_chair']);
expect(res.relaxed).toBe(false);
});
it('relaxes to a partial match rather than dead-ending an unmatched phrase', async () => {
const res = await searchCatalog({ q: 'wooden wrench' });
expect(res.relaxed).toBe(true);
// Both words land somewhere, and the item matching a title word outranks
// the one matching only a tag.
expect(res.items.map((i) => i.id)).toEqual([
'object:adjustable_wrench',
'object:wooden_chair',
]);
});
it('does not relax a single-word query that simply has no match', async () => {
const res = await searchCatalog({ q: 'submarine' });
expect(res.relaxed).toBe(false);
expect(res.items).toHaveLength(0);
});
it('tells a storage failure apart from a legitimately empty result and does not memoize it', async () => {
const healthy = getPublicObjectBuffer.getMockImplementation();
getPublicObjectBuffer.mockImplementation(async (key) => {
if (key === 'objects/library/manifest.json') throw new Error('R2 request failed: 500');
return healthy(key);
});
const down = await searchCatalog({ q: 'wrench' });
expect(down.items).toHaveLength(0);
expect(down.degraded).toBe(true);
getPublicObjectBuffer.mockImplementation(healthy);
const up = await searchCatalog({ q: 'wrench' });
expect(up.items[0].id).toBe('object:adjustable_wrench');
expect(up.degraded).toBe(false);
expect((await searchCatalog({ q: 'submarine' })).degraded).toBe(false);
});
it('filters by kind, category, and tag', async () => {
expect((await searchCatalog({ kind: 'character' })).items[0].id).toBe('character:abe');
expect((await searchCatalog({ category: 'FURNITURE' })).items[0].id).toBe('object:wooden_chair');
expect((await searchCatalog({ tag: 'Garage' })).items[0].id).toBe('object:adjustable_wrench');
});
it('pages with a stable order and reports next_offset', async () => {
const first = await searchCatalog({ kind: 'object', limit: 1 });
expect(first.next_offset).toBe(1);
const second = await searchCatalog({ kind: 'object', limit: 1, offset: 1 });
expect(second.items[0].id).not.toBe(first.items[0].id);
expect(second.next_offset).toBe(2);
const last = await searchCatalog({ kind: 'object', limit: 1, offset: 2 });
expect(last.next_offset).toBeNull();
});
it('resolves a bare name as well as a `<kind>:<name>` id', async () => {
expect((await getCatalogItem('abe')).id).toBe('character:abe');
expect(await getCatalogItem('nope')).toBeNull();
});
it('relates items of the same kind that share tags', async () => {
const wrench = await getCatalogItem('object:adjustable_wrench');
const related = await relatedItems(wrench);
expect(related.every((r) => r.kind === 'object')).toBe(true);
expect(related.some((r) => r.id === 'object:adjustable_wrench')).toBe(false);
});
});
describe('source snippets', () => {
it('recommends model-viewer for a prop and the avatar component for a character', async () => {
expect(frameworksFor(await getCatalogItem('object:wooden_chair'))[0]).toBe('model-viewer');
expect(frameworksFor(await getCatalogItem('character:abe'))[0]).toBe('agent-3d');
expect(frameworksFor(await getCatalogItem('animation:mx-wave-abc123'))[0]).toBe('three');
});
it('pins the agent-3d snippet to a version and never ships "latest"', async () => {
const item = await getCatalogItem('character:abe');
const snippet = snippetFor(item, 'agent-3d', 'https://three.ws');
expect(snippet.code).not.toContain('/latest/');
const release = agentElementRelease();
if (release?.version && release.integrity) {
expect(snippet.code).toContain(`/agent-3d/${release.version}/agent-3d.js`);
expect(snippet.code).toContain(release.integrity);
} else {
expect(snippet.code).toContain('/agent-3d/1/agent-3d.js');
}
});
it('emits the asset url into every model framework', async () => {
const item = await getCatalogItem('object:wooden_chair');
const { snippets } = sourceFor(item, 'https://three.ws');
for (const framework of ['agent-3d', 'model-viewer', 'three', 'react']) {
expect(snippets[framework].code).toContain(item.url);
}
});
it('builds a clip snippet that parses THREE.AnimationClip JSON with the clip loop mode', async () => {
const item = await getCatalogItem('animation:mx-wave-abc123');
const snippet = snippetFor(item, 'three', 'https://three.ws');
expect(snippet.code).toContain('THREE.AnimationClip.parse');
expect(snippet.code).toContain('THREE.LoopOnce');
expect(snippet.code).toContain(item.url);
});
it('produces a legal React identifier even for a title that starts with a digit', async () => {
const item = { ...(await getCatalogItem('animation:mx-wave-abc123')), title: '135 Degree Turn' };
const snippet = snippetFor(item, 'react', 'https://three.ws');
expect(snippet.code).toMatch(/export function use[A-Za-z]/);
});
it('links each kind to the page that actually browses it', async () => {
expect(sourceFor(await getCatalogItem('object:wooden_chair'), 'https://three.ws').links.browse)
.toBe('https://three.ws/objects');
expect(sourceFor(await getCatalogItem('character:abe'), 'https://three.ws').links.browse)
.toBe('https://three.ws/character-library');
expect(sourceFor(await getCatalogItem('animation:mx-wave-abc123'), 'https://three.ws').links.preview)
.toBe('https://three.ws/animations?clip=mx-wave-abc123');
});
});
describe('mcp tools', () => {
it('search_catalog returns readable text and structured results', async () => {
const out = await tool('search_catalog').handler({ q: 'chair' }, {}, req);
expect(out.structuredContent.ok).toBe(true);
expect(out.structuredContent.items[0].id).toBe('object:wooden_chair');
expect(out.content[0].text).toContain('object:wooden_chair');
});
it('search_catalog tells an empty result what to do next', async () => {
const out = await tool('search_catalog').handler({ q: 'submarine' }, {}, req);
expect(out.structuredContent.items).toHaveLength(0);
expect(out.content[0].text).toContain('No catalog items match');
});
it('search_catalog says so when it fell back to a partial match', async () => {
const out = await tool('search_catalog').handler({ q: 'wooden wrench' }, {}, req);
expect(out.structuredContent.relaxed).toBe(true);
expect(out.content[0].text).toContain('Nothing matches every word');
});
it('get_catalog_item rejects an unknown id with a usable hint', async () => {
await expect(tool('get_catalog_item').handler({ id: 'object:nope' }, {}, req)).rejects.toThrow(
/no catalog item/,
);
});
it('get_item_source defaults to the recommended framework', async () => {
const out = await tool('get_item_source').handler({ id: 'object:wooden_chair' }, {}, req);
expect(out.structuredContent.framework).toBe('model-viewer');
expect(out.content[0].text).toContain('<model-viewer');
});
it('get_item_source with framework "all" returns every applicable variant', async () => {
const out = await tool('get_item_source').handler(
{ id: 'character:abe', framework: 'all' },
{},
req,
);
expect(Object.keys(out.structuredContent.snippets).sort()).toEqual(
['agent-3d', 'model-viewer', 'react', 'three'].sort(),
);
});
it('get_item_source refuses a framework that does not apply to a motion clip', async () => {
await expect(
tool('get_item_source').handler(
{ id: 'animation:mx-wave-abc123', framework: 'model-viewer' },
{},
req,
),
).rejects.toThrow(/does not apply/);
});
it('every catalog tool is callable with no account and no payment', () => {
for (const def of toolDefs) {
expect(def.scope).toBeUndefined();
expect(isPublicTool(def.name)).toBe(true);
}
});
it('does not make an account-scoped tool public', () => {
expect(isPublicTool('list_my_avatars')).toBe(false);
expect(isPublicTool('recall')).toBe(false);
expect(isPublicTool('getting_started')).toBe(true);
});
});