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.

24.1 KB
Raw Blame
// Forge generation timeline: the named, evidence-driven stage list shown while
// a model is being made (#state-generating on /forge).
//
// The rule this module exists to enforce: EVERY stage transition is caused by a
// real signal from /api/forge, never by a timer. The pipeline reports exactly
// these things and nothing more:
//
//   POST /api/forge          → { status, backend, tier, path, mode, prompt,
//                                directed_prompt?, preview_image_url?,
//                                reference_image_urls?, text_to_image_model?,
//                                cold_start?, eta_seconds?, coalesced? }
//   GET  /api/forge?job=…    → { status: queued|running|done|failed, backend,
//                                tier, path, preview_image_url?, failover_from? }
//
// So the honest mapping is:
//   • "Art-directing your prompt": the server runs the Granite director before
//     the POST resolves; proof of completion is `directed_prompt` on the response
//     (or its absence, which means the model got the prompt verbatim).
//   • "Painting the reference view": proof is `preview_image_url`. It can arrive
//     on the POST, or later on a poll (coalesced job, resumed job, failover
//     successor), and is revealed the moment it exists.
//   • "Sculpting the mesh": `status: queued` vs `running`. The GPU
//     workers report no sub-steps, so this stays ONE stage: no invented
//     "texturing" phase, just the queue/running distinction plus the honest
//     elapsed meter that forge.js drives.
//   • "Finalizing": the done payload landed and the viewer is
//     loading the GLB. Completed when the model is on screen.
//
// A lane that skips a stage never shows it: the free NVIDIA NIM lane emits the
// mesh straight from the prompt (no director, no reference view), so its
// timeline has three rows, not five.
//
// Cold starts get their own designed state instead of a silent stall: `cold_start`
// on the submit response means the chosen self-host worker was reached but
// answered slowly (scale-to-zero container booting). The warm-up budget shown is
// the real difference between the response's cold ETA and the catalog's warm ETA
// and it ends on a real signal (the first `running` poll), never on the clock.

const STAGE_ORDER = ['direct', 'reference', 'input', 'mesh', 'finish'];

// A tiny inline "open in a new tab" affordance is overkill for a 30px thumb; the
// anchor itself is the affordance and carries its own aria-label.
function thumbHTML(url, alt) {
	return `<img src="${url}" alt="${alt}" loading="lazy" decoding="async" />`;
}

function plural(n, one, many) {
	return n === 1 ? one : many;
}

export function createForgeTimeline({ list, preview, warming, engineLabel = (id) => id }) {
	// Facts accumulated from real responses. Nothing here is ever guessed.
	let f = blankFacts();
	// Rendered rows keyed by stage id, so a re-render updates text in place
	// instead of rebuilding the list (no flicker, no re-announcing every row to
	// a screen reader, and CSS transitions survive).
	const rows = new Map();
	let previewUrlShown = null;

	function blankFacts() {
		return {
			mode: 'text', // text | image | sketch
			viewCount: 0,
			localPreviewUrl: null, // user's own photo/sketch, known before submit
			plannedBackend: null,
			backend: null,
			plannedReference: true, // does this lane paint a reference view?
			hasReference: false,
			referenceUrl: null,
			directedPrompt: null,
			// Did the response carry a `directed_prompt` KEY at all? Absent (an older
			// deployment) is not the same claim as present-and-null (the director
			// genuinely left the prompt alone), and the label must not conflate them.
			directedReported: false,
			directorRan: false, // the submit response came back, so the pass is over
			// Extra reference views the fusing lane painted around the primary one.
			// 0 means the lane painted a single view, which is not a missing stage.
			referenceViews: 0,
			// The generation finished every image step and is handing the job to a
			// GPU lane. Reported by a pre-submit progress crumb, so the mesh row can
			// start before the POST that carries the job id has resolved.
			handedOff: false,
			submitted: false,
			resumed: false,
			status: 'submitting', // submitting | queued | running | finalizing | done | failed
			coldStart: false,
			coldSeconds: null,
			etaSeconds: null,
			queuedSeconds: 0,
			failoverFrom: null,
			elapsedS: 0,
			// A lane running on the user's own machine (Modly). It reports its own
			// step text, and its result is not one of the server's saved creations.
			local: false,
			stepText: '',
		};
	}

	// ── Stage model ──────────────────────────────────────────────────────────
	function stages() {
		const out = [];
		const meshStarted = f.submitted || f.resumed || f.handedOff;
		const terminal = f.status === 'done' || f.status === 'finalizing';
		// A failed job stops spinning: the row keeps its label and detail but drops
		// back to the idle marker, so nothing on screen still implies live work.
		const meshState = terminal ? 'done' : f.status === 'failed' ? 'pending' : meshStarted ? 'active' : 'pending';

		if (f.mode === 'sketch') {
			out.push({
				id: 'input',
				label: 'Your drawing',
				detail: 'Uploaded and used as the reference, no image is synthesized',
				state: 'done',
				thumb: f.localPreviewUrl,
				thumbAlt: 'Your uploaded drawing',
			});
		} else if (f.mode === 'image') {
			const n = Math.max(1, f.viewCount);
			out.push({
				id: 'input',
				label: `Conditioning on ${n} reference ${plural(n, 'view', 'views')}`,
				detail: n > 1 ? 'The engine fuses every view into one mesh' : 'Reconstructing straight from your photo',
				state: 'done',
				thumb: f.localPreviewUrl || f.referenceUrl,
				thumbAlt: 'Your uploaded reference view',
			});
		} else if (f.plannedReference || f.hasReference) {
			// Text → 3D through a reference view: the director rewrites the prompt,
			// then a text-to-image model paints the view the mesh is built from.
			out.push({
				id: 'direct',
				label: directLabel(),
				detail: directDetail(),
				state: f.directorRan ? 'done' : 'active',
			});
			out.push({
				id: 'reference',
				label: f.hasReference ? 'Reference view painted' : 'Painting the reference view',
				detail: f.hasReference
					? f.referenceViews > 1
						? `Plus ${f.referenceViews - 1} turnaround ${plural(f.referenceViews - 1, 'view', 'views')}, so the engine fuses real coverage instead of guessing the back`
						: 'This is the image the mesh is reconstructed from'
					: 'A photoreal single view the reconstructor can read cleanly',
				state: f.hasReference ? 'done' : f.directorRan ? 'active' : 'pending',
				thumb: f.hasReference ? f.referenceUrl : null,
				thumbAlt: 'The reference view painted from your prompt',
			});
		} else {
			out.push({
				id: 'input',
				label: f.submitted ? 'Prompt accepted' : 'Sending your prompt',
				detail: `${engineLabel(f.backend || f.plannedBackend)} builds the mesh straight from text, with no reference image in this lane`,
				state: f.submitted ? 'done' : 'active',
			});
		}

		out.push({
			id: 'mesh',
			label: meshLabel(),
			detail: meshDetail(),
			state: meshState,
		});

		out.push({
			id: 'finish',
			label: f.status === 'done' ? 'Model ready' : 'Finalizing the GLB',
			detail: f.local
				? f.status === 'done'
					? 'Loaded in the viewer'
					: f.status === 'finalizing'
						? 'Fetching the GLB from your computer and loading it into the viewer'
						: 'Fetched from your computer, then straight into the viewer'
				: f.status === 'done'
					? 'Saved to your creations and loaded in the viewer'
					: f.status === 'finalizing'
						? 'Compressing, scoring quality and loading it into the viewer'
						: 'Durable copy, quality score, then straight into the viewer',
			state: f.status === 'done' ? 'done' : f.status === 'finalizing' ? 'active' : 'pending',
		});

		return out.sort((a, b) => STAGE_ORDER.indexOf(a.id) - STAGE_ORDER.indexOf(b.id));
	}

	function directLabel() {
		if (!f.directorRan) return 'Art-directing your prompt';
		if (f.directedPrompt) return 'Prompt art-directed';
		// The lane reported no rewrite. Only claim the prompt went through
		// untouched when the response actually said so.
		return f.directedReported ? 'Prompt used as you wrote it' : 'Prompt handed to the painter';
	}

	function directDetail() {
		if (!f.directorRan) return 'Rewriting it into a single-subject brief with material and lighting cues';
		if (f.directedPrompt) return 'Expanded with materials, lighting and composition cues. See it with your model';
		return f.directedReported
			? 'The director left it unchanged, so the model saw your exact words'
			: 'This lane does not report the director’s rewrite back';
	}

	function meshLabel() {
		const engine = engineLabel(f.backend || f.plannedBackend);
		if (f.mode === 'sketch') return `Sculpting geometry from your drawing on ${engine}`;
		if (f.local) return `Building the mesh on ${engine}`;
		return `Sculpting the textured mesh on ${engine}`;
	}

	function meshDetail() {
		if (f.status === 'failed') return 'The lane reported a failure';
		// Handed off but the POST has not answered yet: the reference work is
		// provably finished (the crumb said so) and the job id is still in flight.
		if (f.handedOff && !f.submitted && !f.resumed) {
			return `Handing the reference views to ${engineLabel(f.backend || f.plannedBackend)}`;
		}
		if (f.failoverFrom) {
			return `${engineLabel(f.failoverFrom)} hit a snag, so ${engineLabel(f.backend)} picked the job up`;
		}
		// A local engine names the step it is on; that beats any generic copy.
		if (f.stepText && (f.status === 'queued' || f.status === 'running')) return f.stepText;
		if (f.status === 'queued') {
			if (f.coldStart) return 'Waiting on a GPU worker that is still booting';
			return f.queuedSeconds >= 8
				? 'In line for a GPU. Earlier jobs finish first, nothing is downgraded'
				: 'Accepted, waiting for a GPU slot';
		}
		if (f.status === 'running') {
			// The workers expose queued/running only (no per-step progress), so this
			// says what the stage covers rather than pretending to track it.
			return 'Geometry and textures in one pass. The engine reports no sub-steps, so the elapsed meter below is the real signal.';
		}
		if (f.status === 'done' || f.status === 'finalizing') return 'Mesh delivered';
		return 'Starts as soon as the job is accepted';
	}

	// ── Rendering ────────────────────────────────────────────────────────────
	function render() {
		if (!list) return;
		const wanted = stages();
		const seen = new Set();
		for (const st of wanted) {
			seen.add(st.id);
			let row = rows.get(st.id);
			if (!row) {
				row = buildRow(st.id);
				rows.set(st.id, row);
				list.appendChild(row.el);
			}
			if (row.el.dataset.state !== st.state) row.el.dataset.state = st.state;
			if (row.label.textContent !== st.label) row.label.textContent = st.label;
			const detail = st.detail || '';
			if (row.detail.textContent !== detail) row.detail.textContent = detail;
			row.detail.hidden = !detail;
			renderThumb(row, st);
		}
		for (const [id, row] of rows) {
			if (seen.has(id)) continue;
			row.el.remove();
			rows.delete(id);
		}
		// Keep DOM order in sync with the stage order after an insert.
		for (const st of wanted) {
			const row = rows.get(st.id);
			if (row) list.appendChild(row.el);
		}
	}

	function buildRow(id) {
		const el = document.createElement('li');
		el.className = 'step';
		el.dataset.stage = id;
		el.dataset.state = 'pending';
		el.innerHTML =
			'<span class="dot" aria-hidden="true"></span>' +
			'<span class="step-body"><span class="step-label"></span><span class="step-detail"></span></span>';
		return {
			el,
			label: el.querySelector('.step-label'),
			detail: el.querySelector('.step-detail'),
			thumb: null,
		};
	}

	function renderThumb(row, st) {
		if (!st.thumb) {
			if (row.thumb) {
				row.thumb.remove();
				row.thumb = null;
			}
			return;
		}
		if (!row.thumb) {
			const a = document.createElement('a');
			a.className = 'step-thumb';
			a.target = '_blank';
			a.rel = 'noopener noreferrer';
			row.thumb = a;
			row.el.appendChild(a);
		}
		if (row.thumb.dataset.src !== st.thumb) {
			row.thumb.dataset.src = st.thumb;
			row.thumb.href = st.thumb;
			row.thumb.setAttribute('aria-label', `${st.thumbAlt || 'Reference view'}. Opens the full image in a new tab`);
			row.thumb.title = 'Open the full reference view';
			row.thumb.innerHTML = thumbHTML(st.thumb, st.thumbAlt || 'Reference view');
		}
	}

	// The big square preview above the stage list. Shows the shimmer skeleton
	// until a real image exists, then paints it in (CSS handles the motion-safe
	// reveal) and runs the reconstruction scanline while the mesh stage is live.
	function renderPreview() {
		if (!preview) return;
		const url = f.referenceUrl || f.localPreviewUrl || null;
		const meshLive = (f.status === 'queued' || f.status === 'running') && (f.submitted || f.resumed);
		preview.classList.toggle('is-reconstructing', Boolean(meshLive));
		if (!url) {
			if (previewUrlShown !== null) {
				previewUrlShown = null;
				preview.innerHTML = '<div class="shimmer" aria-hidden="true"></div>';
			} else if (!preview.firstChild) {
				preview.innerHTML = '<div class="shimmer" aria-hidden="true"></div>';
			}
			return;
		}
		if (previewUrlShown === url) return;
		previewUrlShown = url;
		const img = new Image();
		img.alt = f.mode === 'sketch' ? 'Your drawing' : f.hasReference ? 'Reference view painted from your prompt' : 'Your reference photo';
		img.src = url;
		img.onload = () => {
			if (previewUrlShown !== url) return;
			preview.replaceChildren(img);
		};
		img.onerror = () => {
			// A broken reference URL must not leave a half-state: fall back to the
			// skeleton and let the stage row keep the honest label.
			if (previewUrlShown !== url) return;
			previewUrlShown = null;
			preview.innerHTML = '<div class="shimmer" aria-hidden="true"></div>';
		};
	}

	// ── Cold-start warming state ─────────────────────────────────────────────
	function renderWarming() {
		if (!warming) return;
		const active = f.coldStart && (f.status === 'queued' || f.status === 'submitting');
		warming.classList.toggle('is-hidden', !active);
		if (!active) {
			warming.dataset.phase = 'off';
			return;
		}
		const title = warming.querySelector('.gen-warming-title');
		const body = warming.querySelector('.gen-warming-body');
		const count = warming.querySelector('.gen-warming-count');
		const budget = f.coldSeconds;
		const left = budget ? Math.round(budget - f.elapsedS) : null;
		const over = left != null && left <= 0;
		warming.dataset.phase = over ? 'over' : 'warming';
		const engine = engineLabel(f.backend || f.plannedBackend);
		const nextTitle = over ? 'Still waking the GPU' : 'Waking up a GPU';
		if (title.textContent !== nextTitle) title.textContent = nextTitle;
		const nextBody = over
			? `${engine} is taking longer than its usual boot. Your job is accepted and queued: it starts the moment the worker answers, and nothing is lost in the meantime.`
			: `${engine} scales to zero when nobody is using it, so this request is booting a container. Your job is already accepted and starts the second the worker is up.`;
		if (body.textContent !== nextBody) body.textContent = nextBody;
		const nextCount = over
			? 'Past the usual boot time. Still waiting on the worker'
			: left != null
				? `~${left}s of warm-up left, then sculpting starts`
				: 'First request after an idle spell, so the worker is booting';
		if (count.textContent !== nextCount) count.textContent = nextCount;
	}

	function paint() {
		render();
		renderPreview();
		renderWarming();
	}

	// ── Public API ───────────────────────────────────────────────────────────
	return {
		/**
		 * Start a fresh timeline for a submission. Everything passed here is known
		 * client-side before the request goes out; the server's answer refines it.
		 */
		begin({ mode, backend, viewCount = 0, localPreviewUrl = null, usesReference = true, local = false }) {
			f = blankFacts();
			f.mode = mode;
			f.local = Boolean(local);
			f.plannedBackend = backend;
			f.backend = backend;
			f.viewCount = viewCount;
			f.localPreviewUrl = localPreviewUrl;
			f.plannedReference = mode === 'text' ? usesReference : false;
			previewUrlShown = null;
			rows.forEach((row) => row.el.remove());
			rows.clear();
			if (preview) preview.innerHTML = '<div class="shimmer" aria-hidden="true"></div>';
			paint();
		},

		/** Restore the timeline for a job that survived a reload (resumeInflight). */
		resume({ backend, referenceUrl = null, mode = 'text', elapsedS = 0 }) {
			f = blankFacts();
			f.mode = mode;
			f.plannedBackend = backend;
			f.backend = backend;
			f.resumed = true;
			f.submitted = true;
			f.directorRan = true;
			f.status = 'running';
			f.elapsedS = elapsedS;
			f.plannedReference = Boolean(referenceUrl);
			if (referenceUrl) {
				f.hasReference = true;
				f.referenceUrl = referenceUrl;
			}
			previewUrlShown = null;
			rows.forEach((row) => row.el.remove());
			rows.clear();
			paint();
			return f.etaSeconds;
		},

		/**
		 * Apply the POST /api/forge response. `warmEtaSeconds` is the catalog's
		 * warm estimate for the lane that actually ran, so the cold-start budget is
		 * a real difference of two real numbers rather than a made-up countdown.
		 */
		applySubmit(job, { warmEtaSeconds = null } = {}) {
			f.submitted = true;
			f.directorRan = true;
			if (job?.backend) f.backend = job.backend;
			f.directedReported = Boolean(job) && Object.prototype.hasOwnProperty.call(job, 'directed_prompt');
			if (typeof job?.directed_prompt === 'string' && job.directed_prompt.trim()) {
				f.directedPrompt = job.directed_prompt.trim();
			}
			const ref =
				(typeof job?.preview_image_url === 'string' && job.preview_image_url) ||
				(Array.isArray(job?.reference_image_urls) && job.reference_image_urls[0]) ||
				null;
			if (ref && f.mode === 'text') {
				f.hasReference = true;
				f.referenceUrl = ref;
				f.plannedReference = true;
				const views = Array.isArray(job?.reference_image_urls) ? job.reference_image_urls.length : 0;
				if (views > f.referenceViews) f.referenceViews = views;
			} else if (f.mode === 'text' && !f.hasReference && job?.status && !ref && !job?.coalesced) {
				// The lane answered without a reference view: it generates the mesh
				// straight from the prompt. Drop the reference stages rather than
				// leaving a row that will never complete.
				f.plannedReference = false;
			}
			if (Number(job?.eta_seconds) > 0) f.etaSeconds = Math.round(Number(job.eta_seconds));
			f.coldStart = Boolean(job?.cold_start);
			if (f.coldStart) {
				// The lane's real spin-up budget when the API states it
				// (`cold_start_seconds`, returned alongside `cold_start` on both the
				// submit and the poll frame). The subtraction below is the older,
				// weaker estimate: it infers the boot from how much the ETA widened,
				// which is only as good as the catalog's warm figure and reads as
				// "no estimate" whenever the two happen to match. Prefer the stated
				// number; keep the derivation for a lane that reports the flag
				// without a budget, so a boot is still measurable rather than silent.
				const stated = Number(job?.cold_start_seconds);
				if (stated > 0) {
					f.coldSeconds = Math.round(stated);
				} else {
					const warm = Number(warmEtaSeconds) > 0 ? Number(warmEtaSeconds) : null;
					const gap = warm && f.etaSeconds ? f.etaSeconds - warm : null;
					f.coldSeconds = gap && gap > 0 ? Math.round(gap) : null;
				}
			}
			f.status = job?.status === 'done' ? 'finalizing' : job?.status === 'running' ? 'running' : 'queued';
			paint();
			return { etaSeconds: f.etaSeconds, directedPrompt: f.directedPrompt, referenceUrl: f.referenceUrl };
		},

		/**
		 * Apply the pre-submit progress crumbs read from GET /api/forge?progress=…
		 * while the POST is still open. Each crumb is written by the server AFTER
		 * the work it names finished, so this advances the same stages the submit
		 * response would have advanced, only minutes earlier in wall-clock terms.
		 * Crumbs never move a stage backwards: a fact the POST already delivered
		 * stands.
		 */
		applyProgress(crumbs) {
			if (!Array.isArray(crumbs) || !crumbs.length) return false;
			if (f.submitted || f.resumed) return false;
			let changed = false;
			for (const crumb of crumbs) {
				if (crumb?.stage === 'directed' && !f.directorRan) {
					f.directorRan = true;
					f.directedReported = Object.prototype.hasOwnProperty.call(crumb, 'directed_prompt');
					if (typeof crumb.directed_prompt === 'string' && crumb.directed_prompt.trim()) {
						f.directedPrompt = crumb.directed_prompt.trim();
					}
					changed = true;
				} else if (crumb?.stage === 'reference') {
					if (typeof crumb.preview_image_url === 'string' && crumb.preview_image_url && !f.hasReference) {
						f.hasReference = true;
						f.referenceUrl = crumb.preview_image_url;
						f.plannedReference = true;
						// A reference view can only exist because the director already
						// handed a brief to the painter, so this crumb proves both.
						f.directorRan = true;
						changed = true;
					}
				} else if (crumb?.stage === 'views') {
					const n = Number(crumb.view_count);
					if (n > f.referenceViews) {
						f.referenceViews = Math.round(n);
						changed = true;
					}
				} else if (crumb?.stage === 'submitting' && !f.handedOff) {
					f.handedOff = true;
					changed = true;
				}
			}
			if (changed) paint();
			return changed;
		},

		/** The art-directed prompt a crumb reported, before the POST resolves. */
		hasDirectedPrompt() {
			return Boolean(f.directedPrompt);
		},

		/** Apply one GET /api/forge?job=… poll payload. */
		applyPoll(data) {
			if (!data) return;
			if (data.backend) f.backend = data.backend;
			if (data.failover_from && data.backend && data.failover_from !== data.backend) {
				f.failoverFrom = data.failover_from;
			}
			// The reference view can first become visible here: a coalesced job, a
			// resumed session, or a failover successor never saw the submit payload.
			if (typeof data.preview_image_url === 'string' && data.preview_image_url && !f.hasReference) {
				f.hasReference = true;
				f.referenceUrl = data.preview_image_url;
				if (f.mode === 'text') f.plannedReference = true;
			}
			if (data.status === 'queued') {
				f.status = 'queued';
				f.queuedSeconds += 1;
			} else if (data.status === 'running') {
				f.status = 'running';
				f.queuedSeconds = 0;
				// A worker that answers "running" is up: the cold start is over, and
				// that is a real signal, not a timer expiring.
				f.coldStart = false;
			} else if (data.status === 'done') {
				f.status = 'finalizing';
			} else if (data.status === 'failed') {
				f.status = 'failed';
			}
			paint();
		},

		/**
		 * The step a local engine says it is on (Modly's own `step` text). Empty
		 * text falls back to the generic stage copy. No state changes.
		 */
		setStepText(text) {
			const next = String(text || '').trim().slice(0, 140);
			if (next === f.stepText) return;
			f.stepText = next;
			paint();
		},

		/** The GLB landed; the client is loading it into the viewer. */
		finalizing() {
			f.status = 'finalizing';
			paint();
		},

		/** The model is on screen. */
		complete() {
			f.status = 'done';
			f.coldStart = false;
			paint();
		},

		/** Terminal failure: freeze the rows where they are, drop the warming card. */
		fail() {
			f.status = 'failed';
			f.coldStart = false;
			paint();
		},

		/** Called once a second by the elapsed timer in forge.js. No state changes. */
		tick(elapsedS) {
			f.elapsedS = elapsedS;
			renderWarming();
		},

		/** The honest ETA the server reported for this job, or null. */
		etaSeconds() {
			return f.etaSeconds;
		},

		/** The art-directed prompt for the current job, or null. */
		directedPrompt() {
			return f.directedPrompt;
		},

		/** Is the current job on a cold (booting) worker? */
		isCold() {
			return f.coldStart;
		},
	};
}