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
import { describe, it, expect } from 'vitest';
import {
detectArTarget,
assertArAssetUrl,
buildSceneViewerUrl,
buildViewerUrl,
buildArLaunchUrl,
buildIrlUrl,
buildArViewUrl,
planArLaunch,
} from '../api/_lib/ar-launch.js';
import { toolDefs as arDefs } from '../api/_mcp3d/tools/ar.js';
import { validateSpatialArtifact } from '../api/_lib/spatial-mcp.js';
const GLB = 'https://three.ws/cdn/creations/model.glb';
const IOS = 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15';
const ANDROID = 'Mozilla/5.0 (Linux; Android 14; Pixel 8) AppleWebKit/537.36';
const DESKTOP = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36';
describe('detectArTarget', () => {
it('classifies iOS, Android, and desktop', () => {
expect(detectArTarget(IOS)).toBe('ios');
expect(detectArTarget('… iPad …')).toBe('ios');
expect(detectArTarget(ANDROID)).toBe('android');
expect(detectArTarget(DESKTOP)).toBe('desktop');
expect(detectArTarget('')).toBe('desktop');
});
});
describe('assertArAssetUrl: boundary rejection', () => {
it('accepts an https .glb / .gltf', () => {
expect(assertArAssetUrl(GLB)).toBe(GLB);
expect(assertArAssetUrl('https://x.io/a.gltf')).toBe('https://x.io/a.gltf');
expect(assertArAssetUrl('https://x.io/a.glb?token=1')).toContain('.glb');
});
it('rejects non-https, non-glb, and garbage: a coded error, not a crash', () => {
expect(() => assertArAssetUrl('http://x.io/a.glb')).toThrow(/https/i);
expect(() => assertArAssetUrl('https://x.io/a.png')).toThrow(/\.glb/i);
expect(() => assertArAssetUrl('not a url')).toThrow(/valid https url/i);
try {
assertArAssetUrl('http://x.io/a.glb');
} catch (e) {
expect(e.code).toBe('not_https');
expect(e.arUserMessage).toBe(true);
}
});
});
describe('buildSceneViewerUrl', () => {
it('builds an ARCore intent URL with the GLB as the source and a browser fallback', () => {
const u = buildSceneViewerUrl(GLB, { title: 'Robot', fallbackUrl: 'https://three.ws/viewer?src=x' });
expect(u).toMatch(/^intent:\/\/arvr\.google\.com\/scene-viewer\/1\.2\?/);
expect(u).toContain('package=com.google.ar.core');
expect(u).toContain(encodeURIComponent(GLB));
expect(u).toContain('S.browser_fallback_url=');
});
});
describe('buildArViewUrl', () => {
it('builds the /ar/view URL with src and title', () => {
const u = buildArViewUrl('https://three.ws', GLB, 'Robot');
expect(u).toBe(`https://three.ws/ar/view?src=${encodeURIComponent(GLB)}&title=Robot`);
});
it('adds irl only when passed', () => {
expect(buildArViewUrl('https://three.ws', GLB)).not.toContain('irl=');
const u = buildArViewUrl('https://three.ws', GLB, 'Scout', { irlUrl: 'https://three.ws/irl?avatar=x' });
expect(u).toContain(`irl=${encodeURIComponent('https://three.ws/irl?avatar=x')}`);
});
});
describe('planArLaunch: device routing', () => {
it('Android → redirect to Scene Viewer', () => {
const p = planArLaunch({ glbUrl: GLB, userAgent: ANDROID, origin: 'https://three.ws' });
expect(p.target).toBe('android');
expect(p.action).toBe('redirect');
expect(p.url).toContain('scene-viewer');
});
it('iOS → redirect to /ar/view, the page that generates a real ios-src USDZ', () => {
const p = planArLaunch({ glbUrl: GLB, userAgent: IOS, origin: 'https://three.ws' });
expect(p.target).toBe('ios');
expect(p.action).toBe('redirect');
expect(p.url).toContain('/ar/view?src=');
expect(p.viewerUrl).toContain('/viewer?src=');
});
it('desktop → redirect to /ar/view too (its own WebGL fallback handles no-AR-hardware)', () => {
const p = planArLaunch({ glbUrl: GLB, userAgent: DESKTOP, origin: 'https://three.ws' });
expect(p.target).toBe('desktop');
expect(p.action).toBe('redirect');
expect(p.url).toContain('/ar/view?src=');
});
it('bad input throws at the boundary (handled by the endpoint)', () => {
expect(() => planArLaunch({ glbUrl: 'http://x/a.glb', userAgent: IOS, origin: 'https://three.ws' })).toThrow();
});
});
describe('GET /api/ar: response caching and redirect targets', () => {
function makeReq(ua) {
return {
method: 'GET',
url: `/api/ar?src=${encodeURIComponent(GLB)}&title=Robot`,
headers: { 'user-agent': ua, host: 'three.ws' },
};
}
function makeRes() {
return {
statusCode: 200,
_h: {},
writableEnded: false,
headersSent: false,
setHeader(k, v) {
this._h[k.toLowerCase()] = v;
},
getHeader(k) {
return this._h[k.toLowerCase()];
},
end(body) {
this._body = body;
this.writableEnded = true;
},
};
}
it('iOS gets a 200 interstitial that redirects to /ar/view, never cached (the content is UA-specific)', async () => {
const { default: handler } = await import('../api/ar.js');
const res = makeRes();
await handler(makeReq(IOS), res);
expect(res.statusCode).toBe(200);
expect(res._body).toContain('/ar/view?src=');
expect(res._body).toContain('title=Robot');
expect(res.getHeader('vary')).toMatch(/user-agent/i);
expect(res.getHeader('cache-control')).toBe('no-store');
});
it('the Android Scene Viewer redirect stays uncached (no-store)', async () => {
const { default: handler } = await import('../api/ar.js');
const res = makeRes();
await handler(makeReq(ANDROID), res);
expect(res.statusCode).toBe(302);
expect(res.getHeader('location')).toContain('scene-viewer');
expect(res.getHeader('cache-control')).toBe('no-store');
});
it('desktop also gets the /ar/view interstitial', async () => {
const { default: handler } = await import('../api/ar.js');
const res = makeRes();
await handler(makeReq(DESKTOP), res);
expect(res.statusCode).toBe(200);
expect(res._body).toContain('/ar/view?src=');
});
it('a missing/invalid src is rejected at the boundary with a designed 400 error page, not a crash', async () => {
const { default: handler } = await import('../api/ar.js');
// Missing src entirely.
const missing = makeRes();
await handler({ method: 'GET', url: '/api/ar', headers: { 'user-agent': IOS, host: 'three.ws' } }, missing);
expect(missing.statusCode).toBe(400);
expect(missing.getHeader('cache-control')).toBe('no-store');
expect(missing._body).toContain("Can't open this in AR");
// Non-https src.
const insecure = makeRes();
await handler(
{ method: 'GET', url: `/api/ar?src=${encodeURIComponent('http://x.io/a.glb')}`, headers: { 'user-agent': IOS, host: 'three.ws' } },
insecure,
);
expect(insecure.statusCode).toBe(400);
expect(insecure._body).toContain("Can't open this in AR");
});
it('kind=avatar sends everyone (Android included) to the /ar/view interstitial carrying the irl handoff', async () => {
const { default: handler } = await import('../api/ar.js');
const res = makeRes();
// Android would normally 302 to Scene Viewer, but an avatar always goes to /ar/view.
await handler(
{ method: 'GET', url: `/api/ar?src=${encodeURIComponent(GLB)}&title=Scout&kind=avatar`, headers: { 'user-agent': ANDROID, host: 'three.ws' } },
res,
);
expect(res.statusCode).toBe(200);
expect(res._body).toContain('/ar/view?src=');
expect(res._body).toContain(`irl=${encodeURIComponent(`https://three.ws/irl?avatar=${encodeURIComponent(GLB)}`)}`);
});
});
describe('buildViewerUrl / buildArLaunchUrl', () => {
it('build https viewer and AR launch URLs', () => {
expect(buildViewerUrl('https://three.ws', GLB)).toBe(`https://three.ws/viewer?src=${encodeURIComponent(GLB)}`);
expect(buildArLaunchUrl('https://three.ws', GLB)).toBe(`https://three.ws/api/ar?src=${encodeURIComponent(GLB)}`);
});
});
describe('export_ar MCP tool', () => {
const tool = arDefs.find((d) => d.name === 'export_ar');
const req = { headers: { host: 'three.ws', 'x-forwarded-proto': 'https' } };
it('is a free, read-only tool', () => {
expect(tool).toBeTruthy();
expect(tool.scope).toBeUndefined();
expect(tool.annotations).toMatchObject({ readOnlyHint: true, destructiveHint: false });
});
it('returns AR links and a conformant spatial artifact with the AR handoff', async () => {
const r = await tool.handler({ glb_url: GLB, title: 'Robot' }, null, req);
const sc = r.structuredContent;
expect(sc.arLaunchUrl).toContain('/api/ar?src=');
expect(sc.viewerUrl).toContain('/viewer?src=');
expect(sc.sceneViewerUrl).toContain('scene-viewer');
// The embedded spatial artifact is conformant and carries the AR block.
const v = validateSpatialArtifact(sc.spatial);
expect(v.valid).toBe(true);
expect(sc.spatial.ar.supported).toBe(true);
expect(sc.spatial.ar.launchUrl).toContain('/api/ar');
});
it('rejects bad input cleanly (isError, no crash)', async () => {
const r = await tool.handler({ glb_url: 'http://x/a.glb' }, null, req);
expect(r.isError).toBe(true);
expect(r.structuredContent.error).toBe(true);
});
it('response carries no payment/coin/internal-id surface (OpenAI-clean)', async () => {
const r = await tool.handler({ glb_url: GLB }, null, req);
const FORBIDDEN = /x402|payment|wallet|usdc|\$three|\btoken\b|\bcoin\b|price|\bpaid\b|onchain|web3|mint|session|trace|job_id|creation_id/i;
expect(FORBIDDEN.test(JSON.stringify(r))).toBe(false);
});
it('kind:"avatar" adds the IRL living-agent link and marks the launch as live', async () => {
const r = await tool.handler({ glb_url: GLB, title: 'Scout', kind: 'avatar' }, null, req);
const sc = r.structuredContent;
expect(sc.irlUrl).toBe(`https://three.ws/irl?avatar=${encodeURIComponent(GLB)}`);
expect(sc.arLaunchUrl).toContain('kind=avatar');
expect(sc.spatial.kind).toBe('avatar');
expect(validateSpatialArtifact(sc.spatial).valid).toBe(true);
// The narration leads with the living experience, not the static placement.
expect(r.content[0].text).toContain(sc.irlUrl);
});
it('plain models stay static: no irlUrl, no live flag on the launch link', async () => {
const r = await tool.handler({ glb_url: GLB }, null, req);
expect(r.structuredContent.irlUrl).toBeUndefined();
expect(r.structuredContent.arLaunchUrl).not.toContain('kind=avatar');
});
});
describe('live (avatar) AR lane: the agent-economy bridge into physical space', () => {
it('buildIrlUrl builds the /irl living handoff for a GLB', () => {
expect(buildIrlUrl('https://three.ws', GLB)).toBe(`https://three.ws/irl?avatar=${encodeURIComponent(GLB)}`);
expect(buildIrlUrl('https://three.ws/', GLB)).toBe(`https://three.ws/irl?avatar=${encodeURIComponent(GLB)}`);
});
it('buildArLaunchUrl marks live launches with kind=avatar', () => {
expect(buildArLaunchUrl('https://three.ws', GLB, '', { live: true })).toContain('&kind=avatar');
expect(buildArLaunchUrl('https://three.ws', GLB)).not.toContain('kind=avatar');
});
it('planArLaunch live: Android goes to /ar/view (never a blind Scene Viewer redirect), with irlUrl', () => {
const p = planArLaunch({ glbUrl: GLB, userAgent: ANDROID, origin: 'https://three.ws', live: true });
expect(p.action).toBe('redirect');
expect(p.url).toContain('/ar/view?src=');
expect(p.irlUrl).toContain('/irl?avatar=');
});
it('planArLaunch live: iOS and desktop carry irlUrl into the /ar/view redirect', () => {
for (const ua of [IOS, DESKTOP]) {
const p = planArLaunch({ glbUrl: GLB, userAgent: ua, origin: 'https://three.ws', live: true });
expect(p.action).toBe('redirect');
expect(p.url).toContain(`irl=${encodeURIComponent(p.irlUrl)}`);
}
});
it('planArLaunch static: Android still goes straight to Scene Viewer, no irlUrl anywhere', () => {
const android = planArLaunch({ glbUrl: GLB, userAgent: ANDROID, origin: 'https://three.ws' });
expect(android.action).toBe('redirect');
expect(android.url).toContain('scene-viewer');
expect(android.irlUrl).toBe('');
const ios = planArLaunch({ glbUrl: GLB, userAgent: IOS, origin: 'https://three.ws' });
expect(ios.irlUrl).toBe('');
});
});
describe('GET /api/render/glb: URL-addressable render (share cards)', () => {
function makeReq(url) {
return { method: 'GET', url, headers: { host: 'three.ws' } };
}
function makeRes() {
return {
statusCode: 200,
_h: {},
writableEnded: false,
headersSent: false,
setHeader(k, v) {
this._h[k.toLowerCase()] = v;
},
getHeader(k) {
return this._h[k.toLowerCase()];
},
end(body) {
this._body = body;
this.writableEnded = true;
},
};
}
it('400s a GET without glbUrl (no chromium spin-up on junk)', async () => {
const { default: handler } = await import('../api/render/glb.js');
const res = makeRes();
await handler(makeReq('/api/render/glb'), res);
expect(res.statusCode).toBe(400);
expect(JSON.parse(res._body).error).toBe('bad_request');
});
it('400s a GET pointing at a private address (SSRF guard holds on the GET path)', async () => {
const { default: handler } = await import('../api/render/glb.js');
const res = makeRes();
await handler(makeReq('/api/render/glb?glbUrl=' + encodeURIComponent('https://10.0.0.8/a.glb')), res);
expect(res.statusCode).toBe(400);
});
});