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.

9.0 KB
Raw Blame
/**
 * Live Avatar Forge — pure frame/narration logic.
 *
 * Covers the stage→narration mapping, the prompt clamp to the TRELLIS
 * conditioning window, and the final-frame sidecar round-trip (build → parse)
 * that carries the generated GLB url from the forge driver to every viewer.
 * No network, no DOM — the real /api/forge call and GLB load live in callers.
 */

import { describe, it, expect } from 'vitest';
import {clampPrompt,
	validatePrompt,
	forgeStageNarration,
	buildForgeFrame,
	finalForgeFrame,
	parseForgeFrame,
	viewerLinkFor,
	sanitizeFrameMeta,
	TRELLIS_PROMPT_LIMIT, coldStartState, coldStartLabel } from '../src/shared/forge-frames.js';

describe('clampPrompt', () => {
	it('passes a short prompt through untouched', () => {
		const r = clampPrompt('a glossy white robot mascot');
		expect(r.trimmed).toBe(false);
		expect(r.prompt).toBe('a glossy white robot mascot');
	});

	it('collapses whitespace and trims', () => {
		const r = clampPrompt('   a   round\n robot   ');
		expect(r.prompt).toBe('a round robot');
		expect(r.trimmed).toBe(false);
	});

	it('trims an over-long prompt to the conditioning window on a word boundary', () => {
		const long = 'a friendly round robot mascot, glossy white plastic, big expressive blue eyes and tiny antennae';
		const r = clampPrompt(long);
		expect(r.trimmed).toBe(true);
		expect(r.prompt.length).toBeLessThanOrEqual(TRELLIS_PROMPT_LIMIT);
		// word boundary — no trailing partial word / space
		expect(r.prompt).not.toMatch(/\s$/);
		expect(long.startsWith(r.prompt)).toBe(true);
		expect(r.originalLength).toBe(long.length);
	});

	it('handles null / undefined safely', () => {
		expect(clampPrompt(null).prompt).toBe('');
		expect(clampPrompt(undefined).prompt).toBe('');
	});
});

describe('validatePrompt', () => {
	it('rejects too-short prompts', () => {
		expect(validatePrompt('ab').ok).toBe(false);
		expect(validatePrompt('   ').ok).toBe(false);
	});
	it('accepts a real prompt', () => {
		expect(validatePrompt('a red apple').ok).toBe(true);
	});
});

describe('forgeStageNarration', () => {
	it('narrates each real pipeline state distinctly', () => {
		const submitting = forgeStageNarration({ status: 'submitting' });
		const queued = forgeStageNarration({ status: 'queued', eta_seconds: 20 });
		const running = forgeStageNarration({ status: 'running' });
		const done = forgeStageNarration({ status: 'done' });
		const failed = forgeStageNarration({ status: 'failed' });
		for (const v of [submitting, queued, running, done, failed]) {
			expect(typeof v).toBe('string');
			expect(v.length).toBeGreaterThan(0);
		}
		expect(new Set([submitting, queued, running, done, failed]).size).toBe(5);
	});

	it('includes the ETA when the pipeline reports one', () => {
		expect(forgeStageNarration({ status: 'queued', eta_seconds: 18 })).toContain('18s');
		expect(forgeStageNarration({ status: 'queued' })).not.toContain('~');
	});

	it('falls back to a neutral line for unknown states', () => {
		expect(forgeStageNarration({ status: 'weird' })).toMatch(/forging/i);
		expect(forgeStageNarration({})).toMatch(/forging/i);
	});
});

describe('buildForgeFrame', () => {
	it('defaults to the analysis lane and omits empty meta', () => {
		const f = buildForgeFrame({ activity: 'hi' });
		expect(f).toEqual({ activity: 'hi', type: 'analysis' });
	});
	it('attaches meta when provided', () => {
		const f = buildForgeFrame({ activity: 'hi', meta: { kind: 'forge' } });
		expect(f.meta).toEqual({ kind: 'forge' });
	});
});

describe('finalForgeFrame ↔ parseForgeFrame round-trip', () => {
	it('packs the GLB url + viewer link into the sidecar and reads it back', () => {
		const frame = finalForgeFrame({
			prompt: 'a glossy white robot mascot',
			glbUrl: 'https://three.ws/cdn/forge/abc.glb',
			viewerUrl: 'https://three.ws/viewer?src=x',
			tier: 'draft',
			backend: 'nvidia',
			durable: true,
		});
		expect(frame.type).toBe('analysis');
		expect(frame.meta.kind).toBe('forge');

		const parsed = parseForgeFrame(frame);
		expect(parsed).not.toBeNull();
		expect(parsed.glbUrl).toBe('https://three.ws/cdn/forge/abc.glb');
		expect(parsed.viewerUrl).toBe('https://three.ws/viewer?src=x');
		expect(parsed.prompt).toBe('a glossy white robot mascot');
		expect(parsed.tier).toBe('draft');
		expect(parsed.backend).toBe('nvidia');
		expect(parsed.durable).toBe(true);
	});

	it('returns null for non-forge frames', () => {
		expect(parseForgeFrame({ activity: 'x', type: 'trade' })).toBeNull();
		expect(parseForgeFrame({ activity: 'x', meta: { kind: 'other' } })).toBeNull();
		expect(parseForgeFrame(null)).toBeNull();
	});

	it('rejects a sidecar whose GLB url is not http(s)', () => {
		const bad = { meta: { kind: 'forge', glbUrl: 'javascript:alert(1)', viewerUrl: '', prompt: 'x' } };
		expect(parseForgeFrame(bad)).toBeNull();
	});
});

describe('viewerLinkFor', () => {
	it('builds an encoded viewer link from an origin', () => {
		expect(viewerLinkFor('https://cdn/x y.glb', 'https://three.ws/')).toBe(
			'https://three.ws/viewer?src=https%3A%2F%2Fcdn%2Fx%20y.glb',
		);
	});
});

describe('sanitizeFrameMeta', () => {
	it('keeps a valid forge sidecar and caps lengths', () => {
		const out = sanitizeFrameMeta({
			kind: 'forge',
			glbUrl: 'https://three.ws/cdn/a.glb',
			viewerUrl: 'https://three.ws/viewer?src=a',
			prompt: 'x'.repeat(1000),
			tier: 'draft',
			backend: 'nvidia',
			durable: false,
			injected: 'should be dropped',
		});
		expect(out.glbUrl).toBe('https://three.ws/cdn/a.glb');
		expect(out.prompt.length).toBe(320);
		expect(out.tier).toBe('draft');
		expect('injected' in out).toBe(false);
	});

	it('returns null for non-forge or url-less meta', () => {
		expect(sanitizeFrameMeta(null)).toBeNull();
		expect(sanitizeFrameMeta({ kind: 'other' })).toBeNull();
		expect(sanitizeFrameMeta({ kind: 'forge', glbUrl: 'not-a-url' })).toBeNull();
	});
});

// ── cold-start state ─────────────────────────────────────────────────────────
//
// A queued job on a scale-to-zero GPU worker is waiting on a container boot, not
// behind other people's work. Four surfaces render that state (the homepage
// chamber, the Studio step list, the in-world prop forge, the MCP tool
// responses) and three of them had grown their own copy of this arithmetic, so
// it lives here once. Every value is read off a real /api/forge frame; nothing
// is timed locally, which is what stops a page resumed mid-generation from
// restarting the countdown at zero.
describe('coldStartState / coldStartLabel', () => {
	it('reports nothing for a frame the API did not flag as cold', () => {
		expect(coldStartState({ status: 'queued', eta_seconds: 120 })).toBeNull();
		expect(coldStartLabel({ status: 'running' })).toBeNull();
		expect(coldStartState()).toBeNull();
	});

	it('counts the remaining boot from the stated budget and the job age', () => {
		const c = coldStartState({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 20 });
		expect(c).toEqual({ budgetSeconds: 75, elapsedSeconds: 20, remainingSeconds: 55, pastBudget: false });
		expect(coldStartLabel({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 20 })).toBe(
			'Waking up a GPU: about 55s of boot left (20s in)',
		);
	});

	it('a boot past its budget says so instead of counting into negatives', () => {
		const c = coldStartState({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 200 });
		expect(c.remainingSeconds).toBeNull();
		expect(c.pastBudget).toBe(true);
		const label = coldStartLabel({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 200 });
		expect(label).toBe('Still waking the GPU (200s in)');
		expect(label).not.toMatch(/-\d+s/);
	});

	// The exact boundary: elapsed === budget is spent, not "0s left", because a
	// "about 0s of boot left" line reads as broken.
	it('treats a boot exactly at its budget as spent', () => {
		const c = coldStartState({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 75 });
		expect(c.remainingSeconds).toBeNull();
		expect(c.pastBudget).toBe(true);
	});

	it('names the state but promises no number when the lane states no budget', () => {
		expect(coldStartLabel({ cold_start: true })).toBe('Waking up a GPU');
		expect(coldStartLabel({ cold_start: true, cold_start_seconds: 60 })).toBe('Waking up a GPU (about 60s)');
	});

	// Number(null) is 0, which passes a bare `>= 0` check: a job of unknown age
	// would otherwise be reported as "0s in" on every frame.
	it('does not invent an age for a frame that carries none', () => {
		const c = coldStartState({ cold_start: true, cold_start_seconds: 75 });
		expect(c.elapsedSeconds).toBeNull();
		expect(c.remainingSeconds).toBeNull();
		expect(c.pastBudget).toBe(false);
		expect(coldStartLabel({ cold_start: true, cold_start_seconds: 75 })).not.toContain('0s in');
	});

	// Under 5s the age just flickers as the first polls land, so it is omitted.
	it('omits an age too small to mean anything', () => {
		expect(coldStartLabel({ cold_start: true, cold_start_seconds: 75, elapsed_seconds: 2 })).toBe(
			'Waking up a GPU: about 73s of boot left',
		);
	});
});