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
// Contract tests for src/modly-local.js against an in-process stub of Modly's
// HTTP API. Every route, status code, and body shape the stub serves is taken
// from Modly's FastAPI routers (api/routers/{model,workflow_runs,generation,
// export,optimize}.py, https://github.com/lightningpixel/modly, MIT).
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import {
MODLY_ORIGINS,
MODLY_DEFAULT_ORIGINS,
ModlyError,
detectModly,
probeModly,
listModlyModels,
generateWithModly,
modlyMeshOp,
listModlyMeshOps,
normalizeModlyModel,
defaultModlyParams,
validateModlyWorkspacePath,
modlyRunWorkspacePath,
summarizeModlyError,
setModlyOriginOverride,
getModlyOriginOverride,
normalizeModlyOrigin,
cancelModlyRun,
} from '../src/modly-local.js';
const ORIGIN = 'http://127.0.0.1:8765';
// A minimal valid GLB header: magic "glTF", version 2, total length 12.
function glbBytes() {
const buf = new ArrayBuffer(12);
const v = new DataView(buf);
v.setUint32(0, 0x46546c67, true);
v.setUint32(4, 2, true);
v.setUint32(8, 12, true);
return new Uint8Array(buf);
}
const PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 0]);
function json(body, status = 200) {
return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
}
// In-memory Modly. `script` is the sequence of statuses a run walks through,
// one per status poll, mirroring JobStatus transitions in _run_generation.
function makeModly({
models = [
{ id: 'sf3d', name: 'Stable Fast 3D', description: 'fast', version: '1.0', vram_gb: 6, hf_repo: 'x/y', tags: ['fast'], downloaded: true, loaded: false, active: true },
{ id: 'hunyuan3d', name: 'Hunyuan3D 2', downloaded: false, loaded: false, active: false },
],
params = {
sf3d: [
{ id: 'remesh', label: 'Remesh', type: 'select', default: 'quad', options: [{ value: 'quad', label: 'Quad' }, { value: 'triangle', label: 'Triangle' }] },
{ id: 'texture_resolution', label: 'Texture size', type: 'int', default: 1024, min: 512, max: 2048, step: 512 },
],
},
script = [
{ status: 'pending', progress: 0, step: 'Waiting for the previous generation…' },
{ status: 'running', progress: 40, step: 'Generating mesh' },
{ status: 'done', progress: 100 },
],
outputPath = 'Default/sf3d_0001.glb',
workflowRuns = true,
exportBytes = glbBytes(),
} = {}) {
const calls = [];
const runs = new Map();
let seq = 0;
function statusFor(id) {
const run = runs.get(id);
if (!run) return null;
if (run.cancelled) return { status: 'cancelled', progress: run.last?.progress ?? 0, step: null, output_url: null, error: null };
const step = script[Math.min(run.polls, script.length - 1)];
run.polls += 1;
run.last = step;
const done = step.status === 'done';
return {
status: step.status,
progress: step.progress ?? 0,
step: step.step ?? null,
output_url: done ? `/workspace/${outputPath}` : null,
error: step.error ?? null,
};
}
async function handle(url, init = {}) {
const u = new URL(url);
const method = (init.method || 'GET').toUpperCase();
calls.push({ method, path: u.pathname, search: u.search, init });
const p = u.pathname;
if (method === 'GET' && p === '/health') return json({ status: 'ok' });
if (method === 'GET' && p === '/model/all') return json(models);
if (method === 'GET' && p === '/model/params') {
const id = u.searchParams.get('model_id');
if (!models.some((m) => m.id === id)) return json({ detail: `Unknown model ID: ${id}` }, 404);
return json(params[id] || []);
}
const isRunCreate = (workflowRuns && p === '/workflow-runs/from-image') || p === '/generate/from-image';
if (method === 'POST' && isRunCreate) {
const fd = init.body;
const image = fd.get('image');
if (!image || !String(image.type).startsWith('image/')) return json({ detail: 'File must be an image' }, 400);
const modelId = fd.get('model_id') || 'sf3d';
if (!models.some((m) => m.id === modelId)) return json({ detail: `Unknown model ID: ${modelId}` }, 400);
const id = `run-${++seq}`;
runs.set(id, { polls: 0, cancelled: false, modelId, params: JSON.parse(fd.get('params') || '{}'), image });
return json(p.startsWith('/workflow-runs') ? { run_id: id, status: 'pending' } : { job_id: id });
}
let m = workflowRuns && /^\/workflow-runs\/([^/]+)$/.exec(p);
if (method === 'GET' && m) {
const s = statusFor(m[1]);
if (!s) return json({ detail: `Run ${m[1]} not found` }, 404);
const sc = s.status === 'done' && s.output_url ? { workspace_path: s.output_url.replace('/workspace/', '') } : null;
return json({ run_id: m[1], ...s, scene_candidate: sc });
}
m = /^\/generate\/status\/([^/]+)$/.exec(p);
if (method === 'GET' && m) {
const s = statusFor(m[1]);
if (!s) return json({ detail: `Job ${m[1]} not found` }, 404);
return json({ job_id: m[1], ...s });
}
m = (workflowRuns && /^\/workflow-runs\/([^/]+)\/cancel$/.exec(p)) || /^\/generate\/cancel\/([^/]+)$/.exec(p);
if (method === 'POST' && m) {
const run = runs.get(m[1]);
if (!run) return json({ detail: `Job ${m[1]} not found` }, 404);
run.cancelled = true;
return json({ cancelled: true });
}
if (method === 'GET' && p === '/export/glb') {
const path = u.searchParams.get('path');
if (!path) return json({ detail: [{ loc: ['query', 'path'], msg: 'Field required', type: 'missing' }] }, 422);
return new Response(exportBytes, { status: 200, headers: { 'content-type': 'model/gltf-binary' } });
}
if (method === 'GET' && p === '/optimize/ops') {
return json([
{ id: 'decimate', label: 'Decimate', params_schema: [{ id: 'target_faces', label: 'Target faces', type: 'int', default: 10000, min: 100 }], destructive: true, undoable: true, category: 'topology' },
]);
}
m = /^\/optimize\/op\/([^/]+)$/.exec(p);
if (method === 'POST' && m) {
const body = JSON.parse(init.body);
if (m[1] !== 'decimate') return json({ detail: `Unknown mesh operation: ${m[1]}` }, 404);
const out = body.path.replace(/\.glb$/, '_dec.glb');
return json({ path: out, url: `/workspace/${out}`, face_count: body.params.target_faces ?? 10000 });
}
return json({ detail: 'Not Found' }, 404);
}
return { calls, runs, handle };
}
let modly;
function installFetch(stub, { refuse = [] } = {}) {
vi.stubGlobal(
'fetch',
vi.fn(async (url, init) => {
if (init?.signal?.aborted) throw new DOMException('Aborted', 'AbortError');
if (refuse.some((o) => String(url).startsWith(o))) throw new TypeError('Failed to fetch');
return stub.handle(String(url), init);
}),
);
}
beforeEach(() => {
modly = makeModly();
installFetch(modly);
});
afterEach(() => {
vi.unstubAllGlobals();
setModlyOriginOverride('');
});
describe('model normalization', () => {
it('defaults input/output the way Modly\'s registry does and keeps ParamSchema field names', () => {
const m = normalizeModlyModel(
{ id: 'x', downloaded: 1, vram_gb: 8, tags: ['a'] },
[{ id: 'steps', label: 'Steps', type: 'int', default: 30, min: 1, max: 100, show_if: { param: 'mode', equals: 'hq' } }, { label: 'no id' }],
);
expect(m).toMatchObject({ id: 'x', name: 'x', downloaded: true, input: 'image', output: 'mesh', vramGb: 8, tags: ['a'] });
expect(m.paramsSchema).toEqual([{ id: 'steps', label: 'Steps', type: 'int', default: 30, min: 1, max: 100, show_if: { param: 'mode', equals: 'hq' } }]);
});
it('listModlyModels reads /model/all and attaches each model\'s /model/params', async () => {
const models = await listModlyModels(ORIGIN);
expect(models.map((m) => [m.id, m.downloaded])).toEqual([
['sf3d', true],
['hunyuan3d', false],
]);
expect(models[0].paramsSchema.map((p) => p.id)).toEqual(['remesh', 'texture_resolution']);
expect(models[0].paramsSchema[0].options).toEqual([
{ value: 'quad', label: 'Quad' },
{ value: 'triangle', label: 'Triangle' },
]);
expect(models[1].paramsSchema).toEqual([]);
expect(defaultModlyParams(models[0].paramsSchema)).toEqual({ remesh: 'quad', texture_resolution: 1024 });
});
it('treats an empty Modly (no extensions installed) as zero models, not an error', async () => {
modly = makeModly({ models: [] });
installFetch(modly);
expect(await listModlyModels(ORIGIN)).toEqual([]);
});
});
describe('detection', () => {
it('resolves { origin, models } from the first origin that answers /health', async () => {
installFetch(modly, { refuse: ['http://127.0.0.1'] });
const found = await detectModly({ timeoutMs: 500 });
expect(found.origin).toBe('http://localhost:8765');
expect(found.models).toHaveLength(2);
});
it('resolves null, never throws, when nothing is listening', async () => {
installFetch(modly, { refuse: ['http://'] });
await expect(detectModly({ timeoutMs: 200 })).resolves.toBeNull();
});
it('rejects a server that answers /health but is not Modly', async () => {
vi.stubGlobal('fetch', vi.fn(async () => json({ ok: true })));
await expect(detectModly({ timeoutMs: 200 })).resolves.toBeNull();
});
it('reports blocked when Chrome\'s Local Network Access permission is denied', async () => {
installFetch(modly, { refuse: ['http://'] });
vi.stubGlobal('navigator', {
userAgent: 'Mozilla/5.0 Chrome/142.0',
permissions: {
query: vi.fn(async ({ name }) => {
if (name !== 'local-network-access') throw new TypeError('bad permission');
return { state: 'denied' };
}),
},
});
const probe = await probeModly({ timeoutMs: 200 });
expect(probe).toMatchObject({ status: 'blocked', reason: 'lna-denied', origin: null });
});
it('reports blocked mixed content for Safari on an https page', async () => {
installFetch(modly, { refuse: ['http://'] });
vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 (Macintosh) Version/18.0 Safari/605.1.15' });
vi.stubGlobal('location', { protocol: 'https:' });
const probe = await probeModly({ timeoutMs: 200 });
expect(probe).toMatchObject({ status: 'blocked', reason: 'mixed-content' });
});
it('reports not-running when nothing blocks and nothing answers', async () => {
installFetch(modly, { refuse: ['http://'] });
vi.stubGlobal('navigator', { userAgent: 'Mozilla/5.0 Firefox/140.0' });
vi.stubGlobal('location', { protocol: 'https:' });
const probe = await probeModly({ timeoutMs: 200 });
expect(probe.status).toBe('not-running');
});
});
describe('origin override', () => {
it('normalizes typed addresses and puts the override first in MODLY_ORIGINS', () => {
const store = new Map();
vi.stubGlobal('localStorage', {
getItem: (k) => store.get(k) ?? null,
setItem: (k, v) => store.set(k, String(v)),
removeItem: (k) => store.delete(k),
});
expect(normalizeModlyOrigin('localhost:9000/')).toBe('http://localhost:9000');
expect(() => normalizeModlyOrigin('ftp://x')).toThrow(ModlyError);
const ref = MODLY_ORIGINS;
setModlyOriginOverride('192.168.1.20:8765');
expect(ref).toEqual(['http://192.168.1.20:8765', ...MODLY_DEFAULT_ORIGINS]);
expect(getModlyOriginOverride()).toBe('http://192.168.1.20:8765');
setModlyOriginOverride('');
expect(ref).toEqual([...MODLY_DEFAULT_ORIGINS]);
});
});
describe('generateWithModly', () => {
it('posts the multipart contract, polls with progress, and returns a GLB blob', async () => {
const progress = [];
const res = await generateWithModly(ORIGIN, {
image: new File([PNG], 'chair.png', { type: 'image/png' }),
modelId: 'sf3d',
params: { remesh: 'triangle' },
onProgress: (pct, step) => progress.push([pct, step]),
pollIntervalMs: 1,
});
expect(res.blob.type).toBe('model/gltf-binary');
expect(res.blob.size).toBe(12);
expect(res).toMatchObject({ filename: 'sf3d_0001.glb', jobId: 'run-1', modelId: 'sf3d', workspacePath: 'Default/sf3d_0001.glb', api: 'workflow-runs' });
expect(modly.runs.get('run-1').params).toEqual({ remesh: 'triangle' });
expect(modly.runs.get('run-1').image.type).toBe('image/png');
expect(progress).toEqual([
[0, 'Sending image to Modly'],
[0, 'Waiting for the previous generation…'],
[40, 'Generating mesh'],
[100, 'Fetching the mesh from Modly'],
]);
const exportCall = modly.calls.find((c) => c.path === '/export/glb');
expect(new URLSearchParams(exportCall.search).get('path')).toBe('Default/sf3d_0001.glb');
});
it('sniffs an untyped image blob so Modly does not reject it as a non-image', async () => {
const res = await generateWithModly(ORIGIN, { image: new Blob([PNG]), modelId: 'sf3d', pollIntervalMs: 1 });
expect(res.jobId).toBe('run-1');
expect(modly.runs.get('run-1').image.type).toBe('image/png');
});
it('refuses an input that is not an image before calling Modly', async () => {
await expect(generateWithModly(ORIGIN, { image: new Blob(['hello']), modelId: 'sf3d' })).rejects.toMatchObject({ code: 'BAD_INPUT' });
expect(modly.calls).toHaveLength(0);
});
it('falls back to the legacy /generate routes on a Modly without /workflow-runs', async () => {
modly = makeModly({ workflowRuns: false });
installFetch(modly);
const res = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 });
expect(res.api).toBe('legacy');
expect(modly.calls.some((c) => c.path === '/generate/status/run-1')).toBe(true);
});
it('maps a 400 Unknown model to UNKNOWN_MODEL with Modly\'s text', async () => {
const err = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'nope' }).catch((e) => e);
expect(err).toBeInstanceOf(ModlyError);
expect(err).toMatchObject({ code: 'UNKNOWN_MODEL', status: 400, message: 'Unknown model ID: nope' });
});
it('maps a failed run to GENERATION_FAILED with the exception line and keeps the traceback', async () => {
const tb = 'Traceback (most recent call last):\n File "gen.py", line 9, in generate\n run()\ntorch.OutOfMemoryError: CUDA out of memory. Tried to allocate 2.00 GiB';
modly = makeModly({ script: [{ status: 'running', progress: 10, step: 'Loading model' }, { status: 'error', progress: 10, error: tb }] });
installFetch(modly);
const err = await generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }).catch((e) => e);
expect(err).toMatchObject({ code: 'GENERATION_FAILED', message: 'CUDA out of memory. Tried to allocate 2.00 GiB', detail: tb });
});
it('maps a run cancelled inside Modly to CANCELLED', async () => {
modly = makeModly({ script: [{ status: 'cancelled', progress: 5 }] });
installFetch(modly);
await expect(
generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
).rejects.toMatchObject({ code: 'CANCELLED' });
});
it('maps a run Modly forgot (404 mid-poll) to RUN_LOST', async () => {
installFetch(modly);
const real = globalThis.fetch;
vi.stubGlobal(
'fetch',
vi.fn(async (url, init) => (/\/workflow-runs\/run-1$/.test(String(url)) ? json({ detail: 'Run run-1 not found' }, 404) : real(url, init))),
);
await expect(
generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
).rejects.toMatchObject({ code: 'RUN_LOST' });
});
it('aborting the signal mid-run calls Modly\'s cancel endpoint and rejects CANCELLED', async () => {
modly = makeModly({ script: [{ status: 'running', progress: 20, step: 'Generating mesh' }] });
installFetch(modly);
const ctrl = new AbortController();
const promise = generateWithModly(ORIGIN, {
image: new File([PNG], 'a.png', { type: 'image/png' }),
modelId: 'sf3d',
signal: ctrl.signal,
pollIntervalMs: 50,
onProgress: (pct) => {
if (pct === 20) ctrl.abort();
},
});
await expect(promise).rejects.toMatchObject({ code: 'CANCELLED' });
await vi.waitFor(() => expect(modly.calls.some((c) => c.method === 'POST' && c.path === '/workflow-runs/run-1/cancel')).toBe(true));
expect(modly.runs.get('run-1').cancelled).toBe(true);
});
it('rejects an output that is not a binary glTF with NOT_GLB', async () => {
modly = makeModly({ exportBytes: new TextEncoder().encode('{"scene":"json, not a glb"}') });
installFetch(modly);
await expect(
generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
).rejects.toMatchObject({ code: 'NOT_GLB' });
});
it('refuses a reported output path that escapes the workspace', async () => {
modly = makeModly({ outputPath: '../../etc/passwd' });
installFetch(modly);
await expect(
generateWithModly(ORIGIN, { image: new File([PNG], 'a.png', { type: 'image/png' }), modelId: 'sf3d', pollIntervalMs: 1 }),
).rejects.toMatchObject({ code: 'BAD_PATH' });
expect(modly.calls.some((c) => c.path === '/export/glb')).toBe(false);
});
it('cancelModlyRun resolves false instead of throwing when Modly is gone', async () => {
installFetch(modly, { refuse: ['http://'] });
await expect(cancelModlyRun(ORIGIN, 'run-9')).resolves.toBe(false);
});
});
describe('workspace paths and error text', () => {
it('validates paths with the same rules as Modly\'s CLI', () => {
expect(validateModlyWorkspacePath('Default/a.glb')).toBe('Default/a.glb');
for (const bad of ['', '/etc/x.glb', '\\x.glb', 'a/../b.glb', 'C:/x.glb', 'Default/D:x.glb', 'http://evil/x.glb', 'file:x']) {
expect(() => validateModlyWorkspacePath(bad)).toThrow(ModlyError);
}
});
it('reads scene_candidate first, then strips /workspace/ from output_url', () => {
expect(modlyRunWorkspacePath({ scene_candidate: { workspace_path: 'A/b.glb' }, output_url: '/workspace/X/y.glb' })).toBe('A/b.glb');
expect(modlyRunWorkspacePath({ output_url: '/workspace/My%20Set/y.glb' })).toBe('My Set/y.glb');
expect(() => modlyRunWorkspacePath({})).toThrow(ModlyError);
});
it('summarizes a traceback to its final exception message', () => {
expect(summarizeModlyError('Traceback...\nValueError: bad image')).toBe('bad image');
expect(summarizeModlyError('')).toMatch(/without details/);
});
});
describe('modlyMeshOp', () => {
it('refuses a Blob: Modly has no mesh upload endpoint', async () => {
await expect(modlyMeshOp(ORIGIN, { glb: new Blob([glbBytes()]), op: 'decimate' })).rejects.toMatchObject({ code: 'UPLOAD_UNSUPPORTED' });
expect(modly.calls).toHaveLength(0);
});
it('runs an op on a workspace path and downloads the result', async () => {
const res = await modlyMeshOp(ORIGIN, { glb: { workspacePath: 'Default/sf3d_0001.glb' }, op: 'decimate', params: { target_faces: 5000 } });
expect(res).toMatchObject({ workspacePath: 'Default/sf3d_0001_dec.glb', filename: 'sf3d_0001_dec.glb', details: { face_count: 5000 } });
expect(res.blob.type).toBe('model/gltf-binary');
const post = modly.calls.find((c) => c.path === '/optimize/op/decimate');
expect(JSON.parse(post.init.body)).toEqual({ path: 'Default/sf3d_0001.glb', params: { target_faces: 5000 } });
});
it('maps an unknown op to NOT_FOUND with Modly\'s text', async () => {
await expect(modlyMeshOp(ORIGIN, { glb: 'Default/a.glb', op: 'explode' })).rejects.toMatchObject({ code: 'NOT_FOUND', message: 'Unknown mesh operation: explode' });
});
it('lists ops with normalized param schemas', async () => {
const ops = await listModlyMeshOps(ORIGIN);
expect(ops[0]).toMatchObject({ id: 'decimate', destructive: true, category: 'topology' });
expect(ops[0].paramsSchema[0]).toMatchObject({ id: 'target_faces', default: 10000 });
});
});