Skip to content

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.

8.7 KB
Raw Blame
/**
 * Multi-view conditioning for single-photo image→3D on the self-host TRELLIS
 * fusing lane: api/forge.js.
 *
 * A single uploaded photo used to go to the fusing worker alone, so TRELLIS
 * hallucinated the subject's unseen sides (smeared textures, hollowed-out
 * backs). The handler now rotates the photo into side + back turnaround views
 * (Vertex Gemini edit lane) before submitting, exactly like the text→3D path
 * always did. These tests pin the gate: standard-tier single photos gain the
 * synthesized views; draft keeps single-view speed; caller-supplied multi-view
 * inputs are forwarded untouched; and a failed synthesis degrades to the
 * single view instead of failing the generation.
 */

import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';

beforeAll(() => {
	Object.assign(process.env, {
		APP_ORIGIN: 'https://three.ws',
		// Self-hosted TRELLIS worker wired → photos route to the fusing lane.
		MODEL_TRELLIS_URL: 'https://trellis.example.run.app',
		GCP_RECONSTRUCTION_KEY: 'test-gcp-key',
		// Satisfies the handler's global text-to-3D configured guard; photo
		// uploads still prefer the self-host TRELLIS lane over NVIDIA (text-only).
		NVIDIA_API_KEY: 'nvapi-test',
		// The lane wraps its job id in a signed forge token (encodeJobToken).
		JWT_SECRET: 'test-jwt-secret-at-least-32-characters-long',
	});
});

// Self-hosted GCP worker accepts the job and returns a poll handle, echoing
// back how many views it was given: the wire contract under test.
const gcpSubmit = vi.fn(async ({ params }) => ({
	extJobId: 'gcpjob-multiview-01',
	viewsUsed: params.images.length,
	multiview: params.images.length > 1,
}));
vi.mock('../../api/_providers/gcp.js', () => ({
	createRegenProvider: () => ({ submit: gcpSubmit }),
}));

// Turnaround synthesis (Vertex Gemini edit lane) yields a side + back view of
// the uploaded photo. Individual tests override it to simulate an outage.
const synthesizeTurnaroundViews = vi.fn(async () => [
	'https://cdn.example/photo-side.png',
	'https://cdn.example/photo-back.png',
]);
vi.mock('../../api/_mcp3d/text-to-image.js', () => ({
	textToImage: vi.fn(async () => ({ imageUrl: 'https://cdn.example/ref.png', model: 'flux' })),
	synthesizeTurnaroundViews,
}));

// Store: no real DB. createCreation returns an id; failures are recorded.
vi.mock('../../api/_lib/forge-store.js', () => ({
	hashClient: (v) => `client:${v || 'anon'}`,
	hashIp: (v) => `ip:${v}`,
	createCreation: vi.fn(async () => 'creation-1'),
	materializeCreation: vi.fn(async ({ glbUrl }) => ({ id: 'creation-1', glbUrl })),
	markFailed: vi.fn(async () => {}),
	findByJob: vi.fn(async () => null),
	runWithCreationContext: (_facts, fn) => fn(),
}));

// Lane health: the real snapshot probes the worker URL over the network, which
// is unreachable here and would mark the lane down. Report everything unknown
// (fail-open, treated as usable), matching a deployment with no telemetry.
vi.mock('../../api/_lib/forge-lane-health.js', () => ({
	laneHealthSnapshot: vi.fn(async () => ({ statusMap: {}, byId: {} })),
	markLaneUnhealthy: vi.fn(async () => {}),
	laneCooldownKey: (id) => `forge-lane:${id}`,
}));

// Vision pre-check is a no-op pass: the routing, not the input, is under test.
vi.mock('../../api/_lib/forge-image-validate.js', () => ({
	validateForgeImage: vi.fn(async () => ({ ok: true })),
}));

// Rate limiter: deterministic success so the lane logic is what runs.
vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
	const actual = await importActual();
	return {
		...actual,
		limits: {
			...actual.limits,
			mcp3dGenerate: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
			mcp3dGenerateFree: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
		},
		clientIp: () => '203.0.113.9',
	};
});

const { default: handler } = await import('../../api/forge.js');
const { validateForgeImage } = await import('../../api/_lib/forge-image-validate.js');

function makeReq(body) {
	return {
		method: 'POST',
		url: '/api/forge',
		headers: { 'content-type': 'application/json', 'x-forge-client': 'tester' },
		on(event, cb) {
			if (event === 'data') cb(Buffer.from(JSON.stringify(body)));
			if (event === 'end') cb();
		},
	};
}

function makeRes() {
	return {
		statusCode: 200,
		headers: {},
		body: null,
		setHeader(name, value) {
			this.headers[String(name).toLowerCase()] = value;
		},
		end(body) {
			this.body = body ? JSON.parse(body) : null;
		},
	};
}

const PHOTO = 'https://cdn.example/photo.png';

beforeEach(() => {
	gcpSubmit.mockClear();
	synthesizeTurnaroundViews.mockClear();
	validateForgeImage.mockReset();
	validateForgeImage.mockResolvedValue({ ok: true });
});

describe('single-photo image→3D gains synthesized turnaround views on the fusing lane', () => {
	it('submits the photo plus side + back views to the self-host TRELLIS worker', async () => {
		const req = makeReq({ image_urls: [PHOTO], tier: 'standard', path: 'image', skip_validation: true });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(200);
		expect(res.body.backend).toBe('trellis_selfhost');
		expect(res.body.status).toBe('queued');
		expect(synthesizeTurnaroundViews).toHaveBeenCalledWith(PHOTO);
		expect(gcpSubmit).toHaveBeenCalledTimes(1);
		expect(gcpSubmit.mock.calls[0][0].params.images).toEqual([
			PHOTO,
			'https://cdn.example/photo-side.png',
			'https://cdn.example/photo-back.png',
		]);
		// Provenance reports every view the worker fuses, primary first.
		expect(res.body.reference_image_urls).toHaveLength(3);
		expect(res.body.reference_image_urls[0]).toBe(PHOTO);
		expect(res.body.preview_image_url).toBe(PHOTO);
		// Background pre-matting is requested for a real photo on the fusing lane.
		expect(gcpSubmit.mock.calls[0][0].params.matte).toBe(true);
	});

	it('keeps draft single-view for speed (no synthesis, no matte)', async () => {
		const req = makeReq({ image_urls: [PHOTO], tier: 'draft', path: 'image', skip_validation: true });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(200);
		expect(res.body.backend).toBe('trellis_selfhost');
		expect(synthesizeTurnaroundViews).not.toHaveBeenCalled();
		expect(gcpSubmit.mock.calls[0][0].params.images).toEqual([PHOTO]);
		// Matte is a standard/high quality step; draft stays fast.
		expect(gcpSubmit.mock.calls[0][0].params.matte).toBe(false);
	});

	it('prunes an unusable secondary view before fusion, keeping the primary', async () => {
		const supplied = [PHOTO, 'https://cdn.example/photo-bad.png', 'https://cdn.example/photo-ok.png'];
		// Primary usable, second unusable, third usable: the bad one must be dropped.
		validateForgeImage
			.mockResolvedValueOnce({ ok: true })
			.mockResolvedValueOnce({ ok: false, issue: 'blurry', message: 'too blurry' })
			.mockResolvedValueOnce({ ok: true });
		const req = makeReq({ image_urls: supplied, tier: 'standard', path: 'image' });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(200);
		expect(validateForgeImage).toHaveBeenCalledTimes(3);
		// Caller supplied multiple views, so no synthesis; the fused set is the two
		// usable views with the corrupting one removed.
		expect(gcpSubmit.mock.calls[0][0].params.images).toEqual([
			PHOTO,
			'https://cdn.example/photo-ok.png',
		]);
	});

	it('rejects when the PRIMARY view is unusable, offering the override', async () => {
		validateForgeImage.mockResolvedValueOnce({ ok: false, issue: 'no_subject', message: 'no clear subject' });
		const req = makeReq({ image_urls: [PHOTO], tier: 'standard', path: 'image' });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(422);
		expect(res.body.error).toBe('image_not_usable');
		expect(res.body.override).toEqual({ field: 'skip_validation', value: true });
		expect(gcpSubmit).not.toHaveBeenCalled();
	});

	it('forwards caller-supplied multi-view inputs untouched (their views win)', async () => {
		const supplied = [PHOTO, 'https://cdn.example/photo-left.png'];
		const req = makeReq({ image_urls: supplied, tier: 'standard', path: 'image', skip_validation: true });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(200);
		expect(synthesizeTurnaroundViews).not.toHaveBeenCalled();
		expect(gcpSubmit.mock.calls[0][0].params.images).toEqual(supplied);
	});

	it('degrades to the single photo when synthesis fails: never a failed generation', async () => {
		synthesizeTurnaroundViews.mockRejectedValueOnce(new Error('vertex edit lane down'));
		const req = makeReq({ image_urls: [PHOTO], tier: 'standard', path: 'image', skip_validation: true });
		const res = makeRes();
		await handler(req, res);

		expect(res.statusCode).toBe(200);
		expect(res.body.backend).toBe('trellis_selfhost');
		expect(res.body.status).toBe('queued');
		expect(gcpSubmit.mock.calls[0][0].params.images).toEqual([PHOTO]);
	});
});