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
refactor(forge): describe a waking GPU from one shared helper on every surface
nirholas240878e88626
diff --git a/src/forge-studio/forge.js b/src/forge-studio/forge.jsindex 1c8a1b185..c1eef61be 100644--- a/src/forge-studio/forge.js+++ b/src/forge-studio/forge.js@@ -17,6 +17,7 @@ import { openSketchCanvas } from './sketch-canvas.js';import { mountPromptDictation } from '../voice/prompt-dictation.js';import { showToast } from '../ui-helpers.js';import { resolveDevR2Url } from '../shared/dev-r2-proxy.js';+import { coldStartLabel } from '../shared/forge-frames.js';ensureStateKitStyles();//// Drives /api/forge. Three paths share one polling loop:@@ -1467,24 +1468,6 @@ async function startJob({ prompt, imageUrls, skipValidation, payment }) {return data;}-// A queued job on a scale-to-zero GPU worker is a container boot, not a queue,-// and the two deserve different words: "In line for a GPU" tells someone their-// job is behind other work, which is wrong and unfixable-sounding, when in fact-// nothing is ahead of them and the wait has a known end. Returns null when the-// API does not report a cold start, so the caller keeps its queue wording.-// Every number comes off the poll payload; nothing is timed locally.-function coldStartLabel(job) {- if (!job?.cold_start) return null;- const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);- const budget = num(job.cold_start_seconds);- const elapsed = num(job.elapsed_seconds);- const bootLeft = budget != null && elapsed != null ? budget - elapsed : null;- if (bootLeft != null && bootLeft > 0) return `Waking up a GPU: about ${bootLeft}s of boot left`;- // Past the stated budget: say so rather than counting into negatives.- if (bootLeft != null) return 'Still waking the GPU: it starts the moment the worker answers';- return budget ? `Waking up a GPU (about ${budget}s)` : 'Waking up a GPU';-}-async function pollUntilDone(jobId) {let deadline = performance.now() + MAX_POLL_MS;// Queue-state tracking: a job waiting for a GPU is alive, so say so (after adiff --git a/src/game/forge-prop.js b/src/game/forge-prop.jsindex 21795584c..2e653b235 100644--- a/src/game/forge-prop.js+++ b/src/game/forge-prop.js@@ -8,6 +8,7 @@// the uploaded-prop pipeline (world-objects.js registerUploadedProp).import { log } from '../shared/log.js';+import { coldStartLabel } from '../shared/forge-frames.js';const SUBMIT_URL = '/api/forge';const UPLOAD_URL = '/api/forge-upload';@@ -115,11 +116,14 @@ async function uploadReferenceImage(file, { onStatus, signal } = {}) {//// Two states this used to flatten into "waiting for a slot":// • A scale-to-zero GPU worker booting. That is a nameable wait with a stated-// budget (`cold_start` + `cold_start_seconds`), not an anonymous queue.+// budget, not an anonymous queue (coldStartLabel owns that wording, shared+// with the homepage chamber and the Studio so the three cannot drift).// • The countdown. It printed `eta_seconds`, the lane's static TOTAL, on every// frame, so a two-minute wait read as a bar stuck at the same "~60s" the// whole time. `eta_remaining_seconds` is the live figure and leads now.function statusLine(job = {}) {+ const cold = coldStartLabel(job);+ if (cold) return `${cold}, then forging…`;const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);const remaining = num(job.eta_remaining_seconds) ?? num(job.eta_seconds);const elapsed = num(job.elapsed_seconds);@@ -129,18 +133,6 @@ function statusLine(job = {}) {Boolean,);const suffix = notes.length ? ` (${notes.join(', ')})` : '';- if (job.cold_start) {- const budget = num(job.cold_start_seconds);- const bootLeft = budget != null && elapsed != null ? budget - elapsed : null;- if (bootLeft != null && bootLeft > 0) {- return `Waking up a GPU: about ${bootLeft}s of boot left${elapsed >= 5 ? ` (${elapsed}s in)` : ''}…`;- }- // Past the stated budget: say so rather than counting into negatives.- if (bootLeft != null) {- return `Still waking the GPU${elapsed >= 5 ? ` (${elapsed}s in)` : ''}. Forging starts the moment it answers…`;- }- return budget ? `Waking up a GPU (about ${budget}s), then forging…` : 'Waking up a GPU, then forging…';- }return job.status === 'queued'? `Forging: waiting for a slot${suffix}…`: `Forging your model${suffix}…`;diff --git a/src/home-forge.js b/src/home-forge.jsindex be7b42316..898b5fe6c 100644--- a/src/home-forge.js+++ b/src/home-forge.js@@ -40,6 +40,7 @@ import {fetchJobStatus,nextBackoff,} from './shared/resilient-poll.js';+import { coldStartLabel } from './shared/forge-frames.js';const POLL_INTERVAL_MS = 2500;// Max-tier texture bakes legitimately run past 10 minutes at full quality; the@@ -212,34 +213,19 @@ function setStep(name, state) {// Cold-start line, written from a real /api/forge poll frame and nothing else.// A queued job on a scale-to-zero worker is a container boot: the one wait the// page can name instead of showing a step that spins with no explanation. The-// API states both the flag and the lane's boot budget (`cold_start`,-// `cold_start_seconds`), and `elapsed_seconds` is the JOB's age, so a page-// resumed mid-generation counts from the submit, not from the reload.+// wording lives in the shared forge-frames helper, so this chamber, the Studio,+// the in-world prop forge and the MCP tools all describe a boot identically.// Passing a frame that is not cold clears the line: it is dismissed by the// first real "running" poll, never by a timer.function setWarming(job) {if (!els.warming) return;- if (!job?.cold_start) {+ const label = coldStartLabel(job || {});+ if (!label) {els.warming.hidden = true;els.warming.textContent = '';return;}- const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);- const budget = num(job.cold_start_seconds);- const elapsed = num(job.elapsed_seconds);- const bootLeft = budget != null && elapsed != null ? budget - elapsed : null;- let text;- if (bootLeft != null && bootLeft > 0) {- text = `Waking up a GPU: about ${bootLeft}s of boot left. Sculpting starts the moment it answers.`;- } else if (bootLeft != null) {- // Past the stated budget: say so rather than counting into negatives.- text = `Still waking the GPU (${elapsed}s in). Your job is accepted and starts the moment it answers.`;- } else if (budget != null) {- text = `Waking up a GPU (about ${budget}s), then sculpting starts.`;- } else {- text = 'Waking up a GPU, then sculpting starts.';- }- els.warming.textContent = text;+ els.warming.textContent = `${label}. Sculpting starts the moment the worker answers.`;els.warming.hidden = false;}diff --git a/src/shared/forge-frames.js b/src/shared/forge-frames.jsindex 91f28d9f8..a13c3e377 100644--- a/src/shared/forge-frames.js+++ b/src/shared/forge-frames.js@@ -143,6 +143,57 @@ export function forgeStageNarration(state = {}) {}}+// Cold-start state for one real /api/forge frame, or null when the API is not+// reporting a boot.+//+// A queued job on a scale-to-zero GPU worker is waiting on a container start,+// not on a queue of other people's work, and the two need different words: "in+// line for a GPU" says something is ahead of you, which is both wrong and+// unfixable-sounding, when in fact nothing is ahead and the wait has a known+// end. The API states the flag and the lane's spin-up budget (`cold_start`,+// `cold_start_seconds`) and reports the JOB's age (`elapsed_seconds`), so every+// number below is read off the payload. Nothing is timed locally, which is what+// keeps a page resumed mid-generation from restarting the countdown at zero.+//+// Shared because four surfaces render this state (the homepage chamber, the+// Studio step list, the in-world prop forge, and the MCP tool responses) and+// three of them had grown their own copy of the arithmetic.+//+// @returns {null | { budgetSeconds: number|null, elapsedSeconds: number|null,+// remainingSeconds: number|null, pastBudget: boolean }}+export function coldStartState(job = {}) {+ if (!job || !job.cold_start) return null;+ const num = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : null);+ // Guard null BEFORE the numeric compare: Number(null) is 0, which would report+ // a job of unknown age as "0s in".+ const elapsedSeconds =+ job.elapsed_seconds == null || !Number.isFinite(Number(job.elapsed_seconds)) || Number(job.elapsed_seconds) < 0+ ? null+ : Math.round(Number(job.elapsed_seconds));+ const budgetSeconds = num(job.cold_start_seconds);+ const left = budgetSeconds != null && elapsedSeconds != null ? budgetSeconds - elapsedSeconds : null;+ return {+ budgetSeconds,+ elapsedSeconds,+ remainingSeconds: left != null && left > 0 ? left : null,+ // A boot that has run past its stated budget says so rather than counting+ // into negatives.+ pastBudget: left != null && left <= 0,+ };+}++// The short phrase every surface leads with, from coldStartState(). Returns null+// when the frame reports no boot, so a caller keeps its own queued/running copy.+// Callers append their own tail ("then sculpting starts", an ellipsis, nothing).+export function coldStartLabel(job = {}) {+ const c = coldStartState(job);+ if (!c) return null;+ const inNote = c.elapsedSeconds != null && c.elapsedSeconds >= 5 ? ` (${c.elapsedSeconds}s in)` : '';+ if (c.remainingSeconds != null) return `Waking up a GPU: about ${c.remainingSeconds}s of boot left${inNote}`;+ if (c.pastBudget) return `Still waking the GPU${inNote}`;+ return c.budgetSeconds != null ? `Waking up a GPU (about ${c.budgetSeconds}s)` : 'Waking up a GPU';+}+// A forge progress frame for screenPush — the live narration other viewers see.// `type: 'analysis'` matches the activity-log "analysis" lane. The optional// `meta` rides in the frame sidecar (used only on the final frame).diff --git a/tests/forge-frame.test.js b/tests/forge-frame.test.jsindex 2b7b0bf39..b445c02a0 100644--- a/tests/forge-frame.test.js+++ b/tests/forge-frame.test.js@@ -8,8 +8,7 @@*/import { describe, it, expect } from 'vitest';-import {- clampPrompt,+import {clampPrompt,validatePrompt,forgeStageNarration,buildForgeFrame,@@ -17,8 +16,7 @@ import {parseForgeFrame,viewerLinkFor,sanitizeFrameMeta,- TRELLIS_PROMPT_LIMIT,-} from '../src/shared/forge-frames.js';+ TRELLIS_PROMPT_LIMIT, coldStartState, coldStartLabel } from '../src/shared/forge-frames.js';describe('clampPrompt', () => {it('passes a short prompt through untouched', () => {@@ -163,3 +161,67 @@ describe('sanitizeFrameMeta', () => {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',+ );+ });+});