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
// @three-ws/walk — roster invariants.
// ====================================
// The roster is the contract the unified loader relies on: every entry must
// declare a known-good animation strategy and a resolvable asset so nothing
// ever freezes in a bind/T-pose. These tests pin those invariants and the URL
// resolution that lets one roster work from the host origin, a CDN, or the GLB
// proxy. Pure logic — no Three.js, no DOM — so they run anywhere with
// `node --test`.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
WALK_AVATARS,
DEFAULT_AVATAR_ID,
DEFAULT_SHARED_CLIPS,
getAvatar,
defaultAvatar,
listCategories,
makeApiAvatarEntry,
makeGuestAvatarEntry,
resolveAvatarUrl,
} from '../src/roster.js';
const STATES = ['idle', 'walk', 'run', 'wave', 'jump'];
test('every roster entry carries the fields the loader and picker need', () => {
for (const a of WALK_AVATARS) {
assert.equal(typeof a.id, 'string', `id on ${JSON.stringify(a)}`);
assert.ok(a.id.length, `non-empty id on ${a.id}`);
assert.equal(typeof a.name, 'string', `name on ${a.id}`);
assert.equal(typeof a.category, 'string', `category on ${a.id}`);
assert.ok(['embedded', 'shared'].includes(a.rig), `rig on ${a.id}`);
assert.ok(['static', 'api'].includes(a.source), `source on ${a.id}`);
assert.equal(typeof a.accent, 'string', `accent on ${a.id}`);
assert.ok(/^#[0-9a-f]{3,8}$/i.test(a.accent), `accent is a hex colour on ${a.id}`);
}
});
test('avatar ids are unique', () => {
const ids = WALK_AVATARS.map((a) => a.id);
assert.equal(new Set(ids).size, ids.length, 'duplicate avatar id in roster');
});
test('the default avatar exists in the roster', () => {
assert.ok(getAvatar(DEFAULT_AVATAR_ID), 'DEFAULT_AVATAR_ID not present in WALK_AVATARS');
assert.equal(defaultAvatar().id, DEFAULT_AVATAR_ID);
});
test('getAvatar resolves known ids and is null-safe', () => {
assert.equal(getAvatar('fox')?.id, 'fox');
assert.equal(getAvatar('does-not-exist'), null);
assert.equal(getAvatar(''), null);
assert.equal(getAvatar(null), null);
assert.equal(getAvatar(undefined), null);
});
test('static entries point at a local asset; api/null are handled elsewhere', () => {
for (const a of WALK_AVATARS) {
if (a.source !== 'static') continue;
assert.equal(typeof a.asset, 'string', `static ${a.id} must name an asset`);
assert.ok(a.asset.startsWith('/') || /^https?:\/\//i.test(a.asset), `asset path on ${a.id}`);
}
});
test('shared rigs only request known animation states', () => {
for (const a of WALK_AVATARS) {
if (a.rig !== 'shared' || !a.clips) continue;
for (const k of Object.keys(a.clips)) {
assert.ok(STATES.includes(k), `shared ${a.id} maps unknown state "${k}"`);
assert.equal(typeof a.clips[k], 'string', `shared ${a.id}.${k} must name a manifest clip`);
}
}
});
test('embedded clip overrides are candidate-name arrays', () => {
for (const a of WALK_AVATARS) {
if (a.rig !== 'embedded' || !a.clips) continue;
for (const k of Object.keys(a.clips)) {
assert.ok(STATES.includes(k), `embedded ${a.id} maps unknown state "${k}"`);
assert.ok(Array.isArray(a.clips[k]), `embedded ${a.id}.${k} must be a candidate array`);
}
}
});
test('DEFAULT_SHARED_CLIPS covers every animation state', () => {
for (const s of STATES) {
assert.equal(typeof DEFAULT_SHARED_CLIPS[s], 'string', `missing default clip for "${s}"`);
}
});
test('listCategories is de-duplicated and in first-seen order', () => {
const cats = listCategories();
assert.equal(new Set(cats).size, cats.length, 'duplicate category');
// first-seen order: the first roster entry seeds the first category.
assert.equal(cats[0], WALK_AVATARS[0].category);
// every roster category appears.
for (const a of WALK_AVATARS) assert.ok(cats.includes(a.category), `missing ${a.category}`);
});
test('makeApiAvatarEntry builds a shared, retargeted, user-owned entry', () => {
const e = makeApiAvatarEntry('abc123');
assert.equal(e.id, 'abc123');
assert.equal(e.source, 'api');
assert.equal(e.rig, 'shared');
assert.equal(e.asset, null);
assert.equal(e.category, 'Yours');
assert.deepEqual(e.clips, DEFAULT_SHARED_CLIPS);
const named = makeApiAvatarEntry('xyz', { name: 'Nova', accent: '#abcdef' });
assert.equal(named.name, 'Nova');
assert.equal(named.accent, '#abcdef');
});
test('resolveAvatarUrl: static paths honour assetBase', () => {
const fox = getAvatar('fox');
assert.equal(resolveAvatarUrl(fox), fox.asset);
assert.equal(resolveAvatarUrl(fox, { assetBase: 'https://cdn.example' }), `https://cdn.example${fox.asset}`);
});
test('resolveAvatarUrl: absolute asset urls pass through untouched', () => {
const entry = { source: 'static', asset: 'https://cdn.example/x.glb' };
assert.equal(resolveAvatarUrl(entry, { assetBase: 'https://other' }), 'https://cdn.example/x.glb');
});
test('resolveAvatarUrl: api entries hit the GLB proxy with apiBase + encoding', () => {
const e = makeApiAvatarEntry('user/with space');
assert.equal(resolveAvatarUrl(e), `/api/avatars/${encodeURIComponent('user/with space')}/glb`);
assert.equal(
resolveAvatarUrl(e, { apiBase: 'https://api.example' }),
`https://api.example/api/avatars/${encodeURIComponent('user/with space')}/glb`,
);
});
test('resolveAvatarUrl: null entry and asset-less static entry resolve to null', () => {
assert.equal(resolveAvatarUrl(null), null);
assert.equal(resolveAvatarUrl({ source: 'static', asset: null }), null);
});
test('makeGuestAvatarEntry: a message from a contact can be delivered by their own GLB', () => {
const entry = makeGuestAvatarEntry('https://three.ws/api/avatars/abc/glb', { name: 'Sarah' });
assert.equal(entry.name, 'Sarah');
assert.equal(entry.rig, 'shared');
assert.deepEqual(entry.clips, DEFAULT_SHARED_CLIPS);
// The URL is used verbatim: a guest body is somebody else's avatar, not one
// of ours to resolve against assetBase.
assert.equal(resolveAvatarUrl(entry, { assetBase: 'https://cdn.example' }), 'https://three.ws/api/avatars/abc/glb');
});
test('makeGuestAvatarEntry: distinct URLs get distinct ids so a swap is detectable', () => {
const a = makeGuestAvatarEntry('/avatars/one.glb');
const b = makeGuestAvatarEntry('/avatars/two.glb');
assert.notEqual(a.id, b.id);
assert.equal(makeGuestAvatarEntry('/avatars/one.glb', { id: 'pinned' }).id, 'pinned');
assert.equal(resolveAvatarUrl(a, { assetBase: 'https://cdn.example' }), 'https://cdn.example/avatars/one.glb');
});