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.

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.js
index 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 a
diff --git a/src/game/forge-prop.js b/src/game/forge-prop.js
index 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.js
index 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.js
index 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.js
index 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',
+ );
+ });
+});