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
feat(forge): show the reference image the moment it renders, not when the job returns
nirholas21ab5564b08a
diff --git a/api/_lib/forge-progress.js b/api/_lib/forge-progress.jsnew file mode 100644index 000000000..204659267--- /dev/null+++ b/api/_lib/forge-progress.js@@ -0,0 +1,97 @@+// Pre-submit progress crumbs for a forge generation.+//+// The problem this solves: POST /api/forge is ONE long request. Before it can+// answer with a job id it has to run the art-director pass, synthesize the+// photoreal reference view, and (on the fusing lane) paint the turnaround+// views. On a standard text prompt that is one LLM call plus up to four image+// generations, and every second of it used to be invisible: /forge could only+// show "art-directing your prompt" until the whole thing resolved, so the+// reference image the user is really waiting to see landed at the very END of+// the silent window instead of the moment it existed.+//+// There is no second channel on a single HTTP request, so the generation writes+// a crumb into the shared cache as it passes each REAL milestone, keyed by a+// caller-supplied trace id, and /forge reads them with a cheap poll while its+// POST is still in flight (GET /api/forge?progress=<id>).+//+// Rules this module exists to keep:+// • Every crumb is written AFTER the work it names actually finished. There is+// no "probably done by now" crumb and no timer anywhere in this file.+// • It is entirely fail-open. A write failure, an absent Redis, an instance+// that never sees the read: all of them degrade to exactly the behaviour+// before this existed (the stage list waits for the POST). Nothing in a+// generation may ever fail because a progress crumb did.+// • The trace id comes from the CLIENT and is not a job handle: it grants no+// access to anything. The crumbs it addresses hold only what the response+// would carry seconds later anyway (the directed prompt, the reference URL),+// they expire in minutes, and a caller that does not send one costs nothing.++import { cacheGetFresh, cacheSet } from './cache.js';++// Long enough to cover the slowest cold pre-submit phase with room to spare,+// short enough that an abandoned trace evaporates on its own.+const TTL_SECONDS = 300;+// A trace only ever collects the handful of milestones below; the cap is a+// belt-and-braces bound on what one id can make us store.+const MAX_CRUMBS = 8;++const STAGES = new Set(['directed', 'reference', 'views', 'submitting']);++/**+ * Accept a client-supplied trace id only in a shape we generate: url-safe, and+ * long enough not to collide across concurrent generations. Anything else is+ * treated as "no trace", never as an error, so a malformed id can only cost the+ * caller its own progress, never its generation.+ * @param {unknown} raw+ * @returns {string|null}+ */+export function normalizeTraceId(raw) {+ const id = typeof raw === 'string' ? raw.trim() : '';+ return /^[A-Za-z0-9_-]{16,64}$/.test(id) ? id : null;+}++function key(traceId) {+ return `forge:progress:${traceId}`;+}++/**+ * Record one completed milestone. Fire-and-forget by design: callers do not+ * await this on the generation's critical path.+ * @param {string|null} traceId+ * @param {'directed'|'reference'|'views'|'submitting'} stage+ * @param {Record<string, unknown>} [data]+ */+export async function recordForgeProgress(traceId, stage, data = {}) {+ const id = normalizeTraceId(traceId);+ if (!id || !STAGES.has(stage)) return;+ try {+ const existing = await cacheGetFresh(key(id));+ const crumbs = Array.isArray(existing) ? existing : [];+ // One crumb per stage: a lane that revisits a milestone (a failover that+ // re-paints the reference view) updates it rather than growing the list.+ const next = crumbs.filter((c) => c?.stage !== stage);+ next.push({ stage, at: Date.now(), ...data });+ await cacheSet(key(id), next.slice(-MAX_CRUMBS), TTL_SECONDS);+ } catch {+ // Instrumentation, never a gate.+ }+}++/**+ * Read the crumbs recorded so far for a trace, oldest first. Returns an empty+ * array for an unknown or expired trace, which is what a caller polling ahead of+ * the first milestone sees and is indistinguishable from "not there yet".+ * @param {string|null} traceId+ * @returns {Promise<Array<Record<string, unknown>>>}+ */+export async function readForgeProgress(traceId) {+ const id = normalizeTraceId(traceId);+ if (!id) return [];+ try {+ const crumbs = await cacheGetFresh(key(id));+ if (!Array.isArray(crumbs)) return [];+ return crumbs.filter((c) => c && STAGES.has(c.stage)).sort((a, b) => (a.at || 0) - (b.at || 0));+ } catch {+ return [];+ }+}diff --git a/api/forge.js b/api/forge.jsindex 997f26478..326417270 100644--- a/api/forge.js+++ b/api/forge.js@@ -77,10 +77,12 @@ import {estimateCredits,preferFreeReconstruct,backendIsConfigured,+ backendAcceptsInlineViews,buildCatalog,selfhostQualityForTier,} from './_lib/forge-tiers.js';import { laneHealthSnapshot, markLaneUnhealthy } from './_lib/forge-lane-health.js';+import { isInlineImageRef } from './_lib/image-persist.js';import { resolveProviderKey } from './_lib/forge-provider-key.js';import { validateForgeImage } from './_lib/forge-image-validate.js';import { encodeJobToken, decodeJobToken } from './_lib/forge-job-token.js';@@ -94,6 +96,7 @@ import {findByJob,} from './_lib/forge-store.js';import { isStorageInfrastructureError } from './_lib/r2.js';+import { normalizeTraceId, recordForgeProgress, readForgeProgress } from './_lib/forge-progress.js';import { getSessionUser } from './_lib/auth.js';import { constantTimeEquals } from './_lib/crypto.js';import {@@ -1078,6 +1081,12 @@ async function startJob(req, res) {// before. An explicitly-present but invalid value is a 400 with an actionable// message; an absent field is never an error.const opts = normalizeForgeOptions(body);+ // Optional client-supplied trace id for the pre-submit progress channel. The+ // director pass and the reference-view synthesis both finish long before this+ // request can answer, so each records a crumb the page reads with a cheap poll+ // (GET ?progress=<id>) while this POST is still open. Absent id: no crumbs, and+ // the generation is byte-for-byte what it was before.+ const progressId = normalizeTraceId(body?.progress_id);if (opts.errors.length) {return json(res, 400, {error: 'invalid_options',@@ -1883,6 +1892,14 @@ async function startJob(req, res) {// view synthesized from the prompt (text→3D). `referenceImageUrl` is the// primary view: the durable preview + the synthesis target.let referenceImageUrl;+ // What we ECHO and STORE for the reference view, as opposed to what we send+ // the reconstructor. They differ in exactly one case: a storage outage makes+ // referenceImageUrl an inline data URI (see _lib/image-persist.js), which the+ // worker must receive and which must never reach the response body or the+ // forge_creations row, where a multi-megabyte base64 string would bloat every+ // poll payload and the database. Null there means "no durable preview", which+ // is the truth: nothing was parked.+ let reportableRefUrl = null;let textToImageModel;let views;// The prompt the art director actually handed to the reference painter, when@@ -1894,6 +1911,7 @@ async function startJob(req, res) {if (isImageMode) {views = imageUrls;referenceImageUrl = imageUrls[0];+ reportableRefUrl = referenceImageUrl;textToImageModel = null;} else {// Granite art-director pass (on by default; pass director:false to skip):@@ -1927,6 +1945,10 @@ async function startJob(req, res) {// Report the rewrite only when it actually changed the brief, an// unchanged value means the model saw exactly what the user typed.if (promptForReference && promptForReference !== prompt) directedPrompt = promptForReference;+ // Milestone 1: the director pass is over. Crumb it before the (much+ // longer) image synthesis starts so the page can retire that stage and+ // show the real rewrite instead of holding it for the whole request.+ recordForgeProgress(progressId, 'directed', { directed_prompt: directedPrompt }).catch(() => {});// Seed the reconstruction reference from the dedicated Vertex-Gemini// photoreal module when it is live, so a text prompt reconstructs from the// most photoreal single view we can synthesize. Fail-open: an absent module@@ -1941,6 +1963,33 @@ async function startJob(req, res) {referenceImageUrl = synthesized.imageUrl;textToImageModel = synthesized.model;views = [referenceImageUrl];+ reportableRefUrl = isInlineImageRef(referenceImageUrl) ? null : referenceImageUrl;+ // The reference view came back inline because object storage refused to+ // park it (see _lib/image-persist.js). Our own GPU workers decode a data+ // URI, so those lanes carry on untouched; a third-party reconstructor+ // fetches a URL and cannot, so it is refused here with the actual cause+ // rather than being handed a data URI it will reject opaquely. Before+ // this branch existed the storage error escaped raw, and every text→3D+ // caller was told to "check your secret access key and signing method".+ if (isInlineImageRef(referenceImageUrl) && !backendAcceptsInlineViews(backendId)) {+ return json(res, 503, {+ error: 'storage_unavailable',+ message:+ 'Our image storage is not accepting writes right now, so this engine cannot be given the reference view. Try again on the free built-in engine, or retry shortly.',+ backend: backendId,+ retryable: true,+ retry_backends: retryBackendSuggestions({ attempted: [backendId], hasImage: false }).filter(+ backendAcceptsInlineViews,+ ),+ });+ }+ // Milestone 2: the reference view exists. This is the one the user is+ // really waiting to see, and it is now minutes-fresh rather than+ // arriving with the job id at the end of the request.+ recordForgeProgress(progressId, 'reference', {+ preview_image_url: reportableRefUrl,+ text_to_image_model: textToImageModel,+ }).catch(() => {});}// Multi-view conditioning: rotate the primary view (the caller's uploaded@@ -1954,10 +2003,29 @@ async function startJob(req, res) {// speed, and a caller who supplied multiple calibrated views keeps exactly// those. Best-effort: a failed view just means fewer views, never a// failed generation.- if (backendId === 'trellis_selfhost' && tier.id !== 'draft' && views.length === 1) {+ // An inline reference view (storage outage) is skipped here on purpose: the+ // turnaround lane edits an image it fetches by URL, so it can only fail, and+ // paying a Vertex round trip to learn that would just slow the one path still+ // able to deliver a mesh. Single-view reconstruction still runs.+ if (+ backendId === 'trellis_selfhost' &&+ tier.id !== 'draft' &&+ views.length === 1 &&+ !isInlineImageRef(referenceImageUrl)+ ) {const turnaround = await synthesizeTurnaroundViews(referenceImageUrl).catch(() => []);if (turnaround.length) views = [...views, ...turnaround];}+ // Milestone 3: every view the reconstructor will fuse now exists, so the+ // remaining wait is the GPU itself. Only crumbed when the lane actually+ // painted extra views, so a single-view lane never shows a stage it skipped.+ if (views.length > 1) {+ recordForgeProgress(progressId, 'views', { view_count: views.length }).catch(() => {});+ }+ // Milestone 4: every image the reconstructor needs is in the bucket and the+ // request is handing the job to a GPU lane. Everything after this point is+ // the engine's own queued/running reporting, which the page already polls.+ recordForgeProgress(progressId, 'submitting', {}).catch(() => {});// Explicitly chosen free HuggingFace lane. Unlike the trellis free-first// path below: which degrades to the paid Replicate lane when the free@@ -2047,7 +2115,7 @@ async function startJob(req, res) {ipHash: hashIp(ip),prompt: prompt || (isImageMode ? 'image-to-3d' : ''),aspect: isImageMode ? null : aspect,- previewImageUrl: referenceImageUrl,+ previewImageUrl: reportableRefUrl,replicateJobId: job.extJobId,textToImageModel: isImageMode ? null : textToImageModel,viewsRequested: views.length,@@ -2072,7 +2140,7 @@ async function startJob(req, res) {backend: backendId,prompt: prompt || null,directed_prompt: directedPrompt,- preview_image_url: referenceImageUrl,+ preview_image_url: reportableRefUrl,reference_image_urls: views,text_to_image_model: isImageMode ? null : textToImageModel,cold_start: cold,@@ -2114,7 +2182,7 @@ async function startJob(req, res) {tier,path,mode: isImageMode ? 'image_to_3d' : 'text_to_3d',- previewImageUrl: referenceImageUrl,+ previewImageUrl: reportableRefUrl,textToImageModel,directedPrompt,opts,@@ -2152,7 +2220,7 @@ async function startJob(req, res) {tier,path,mode: isImageMode ? 'image_to_3d' : 'text_to_3d',- previewImageUrl: referenceImageUrl,+ previewImageUrl: reportableRefUrl,textToImageModel,directedPrompt,opts,@@ -2316,7 +2384,7 @@ async function startJob(req, res) {tier,path,mode: isImageMode ? 'image_to_3d' : 'text_to_3d',- previewImageUrl: referenceImageUrl,+ previewImageUrl: reportableRefUrl,textToImageModel,directedPrompt,opts,@@ -2359,7 +2427,7 @@ async function startJob(req, res) {ipHash: hashIp(ip),prompt: prompt || (isImageMode ? 'image-to-3d' : ''),aspect,- previewImageUrl: referenceImageUrl,+ previewImageUrl: reportableRefUrl,replicateJobId: job.extJobId,textToImageModel,viewsRequested,@@ -2395,7 +2463,7 @@ async function startJob(req, res) {backend: backendId,prompt: prompt || null,directed_prompt: directedPrompt,- preview_image_url: referenceImageUrl,+ preview_image_url: reportableRefUrl,reference_image_urls: views,views_requested: viewsRequested,views_used: viewsUsed,@@ -3149,6 +3217,23 @@ export default wrap(async (req, res) => {});}+ // ?progress: the pre-submit crumbs for a trace id the caller passed on its own+ // still-open POST (see _lib/forge-progress.js). Answers instantly from the+ // shared cache, and an unknown trace is an empty list rather than an error:+ // polling ahead of the first milestone is the normal case, not a fault.+ if (url.searchParams.has('progress')) {+ const traceId = (url.searchParams.get('progress') || '').trim();+ if (!normalizeTraceId(traceId)) {+ return json(res, 400, {+ error: 'invalid_progress_id',+ message: 'Pass ?progress=<id> using the same id sent as progress_id on the POST.',+ });+ }+ const rl = await limits.mcp3dStatus(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);+ return json(res, 200, { progress: await readForgeProgress(traceId) });+ }+const jobId = (url.searchParams.get('job') || '').trim();if (!jobId) {return json(res, 400, { error: 'missing_job', message: 'Pass ?job=<id> to poll a job.' });diff --git a/pages/forge.html b/pages/forge.htmlindex 9fb3222bc..71ec88ff5 100644--- a/pages/forge.html+++ b/pages/forge.html@@ -3327,6 +3327,17 @@margin-top: var(--space-md);display: inline-flex;gap: var(--space-xs);+ /* A recovery row must never run off the panel: at 320px a two-button+ row (or one long label) used to clip its own text against the+ right edge, so the escape hatch was unreadable exactly where the+ user needed it most. */+ flex-wrap: wrap;+ justify-content: center;+ max-width: 100%;+ }+ .notice .actions .btn {+ max-width: 100%;+ white-space: normal;}.hint-foot {text-align: center;diff --git a/src/forge-timeline.js b/src/forge-timeline.jsindex 12a2d7f15..1659d79ff 100644--- a/src/forge-timeline.js+++ b/src/forge-timeline.js@@ -73,6 +73,13 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)// 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@@ -88,7 +95,7 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)// ── Stage model ──────────────────────────────────────────────────────────function stages() {const out = [];- const meshStarted = f.submitted || f.resumed;+ 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.@@ -126,7 +133,9 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)id: 'reference',label: f.hasReference ? 'Reference view painted' : 'Painting the reference view',detail: f.hasReference- ? 'This is the image the mesh is reconstructed from'+ ? 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,@@ -187,6 +196,11 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)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`;}@@ -415,7 +429,9 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)f.hasReference = true;f.referenceUrl = ref;f.plannedReference = true;- } else if (f.mode === 'text' && job?.status && !ref && !job?.coalesced) {+ 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.@@ -424,15 +440,78 @@ export function createForgeTimeline({ list, preview, warming, engineLabel = (id)if (Number(job?.eta_seconds) > 0) f.etaSeconds = Math.round(Number(job.eta_seconds));f.coldStart = Boolean(job?.cold_start);if (f.coldStart) {- 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;+ // 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;diff --git a/src/forge.js b/src/forge.jsindex e66b4a263..baab0105a 100644--- a/src/forge.js+++ b/src/forge.js@@ -152,6 +152,11 @@ const els = {let aspectRatio = '1:1';let elapsedTimer = null;+// Wall-clock origin of the running elapsed meter, and a handle to repaint it on+// demand. Module-level because anchorElapsed() re-points the origin at the+// server's own job age when a poll frame reports one.+let elapsedStart = 0;+let elapsedRetick = null;let pollAbort = false;let mode = 'text'; // 'text' | 'image' | 'sketch' — input mode (prompt vs photos vs drawing)let lastJob = null; // { prompt, imageUrls, seed }: for retry and refine@@ -310,7 +315,14 @@ const CLIENT_ID = (() => {}})();-const CLIENT_HEADERS = { 'x-forge-client': CLIENT_ID };+// `x-witness: handled` tells the session recorder (packages/witness) that this+// page renders a designed state for every status /api/forge can answer with: a+// rate limit, a lane failure, a storage outage. Without it the recorder counts+// each of those as an unhandled failure and the companion interrupts with+// "something just broke, want to report it?" ON TOP of the recovery buttons the+// page is already showing, which at 320px literally covered Try again. The call+// is still recorded, it just stops triggering that offer.+const CLIENT_HEADERS = { 'x-forge-client': CLIENT_ID, 'x-witness': 'handled' };// Leave-the-page continuity. The active async job persists here so a reload,// a navigation away, or a closed tab does not lose the generation: returning@@ -389,6 +401,29 @@ function showState(name) {if (name !== 'result' && cinemaOn) setCinema(false);}+// Bring the stage (the panel that holds the timeline, the viewer and the error+// states) into view when the page has just switched what it is showing there.+//+// On a wide screen the composer and the stage sit side by side and the stage is+// already on screen, so scrolling would be a pointless jolt. Below the layout's+// breakpoint they stack, and the stage starts a full viewport BELOW the Generate+// button: pressing Generate on a phone used to leave the user staring at the+// engine picker while the whole live timeline played out off-screen. So: scroll+// only when the stage genuinely is not in view, and respect a reduced-motion+// preference by jumping instead of animating.+function revealStage() {+ const el = els.stage;+ if (!el || typeof el.getBoundingClientRect !== 'function') return;+ const rect = el.getBoundingClientRect();+ const viewport = window.innerHeight || document.documentElement.clientHeight || 0;+ if (!viewport) return;+ // "In view" means its top edge is inside the upper two thirds of the window,+ // which is where a side-by-side stage always is and a stacked one never is.+ if (rect.top >= 0 && rect.top < viewport * 0.66) return;+ const reduced = window.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches;+ el.scrollIntoView({ behavior: reduced ? 'auto' : 'smooth', block: 'start' });+}+// Human label for a backend id, from the short-label map or the live catalog.function engineLabel(id) {if (!id) return 'the engine';@@ -468,7 +503,7 @@ function setProgress(pct) {function startElapsed(offsetMs = 0) {// `offsetMs` backdates the counter for a resumed job, so the elapsed line// stays honest about how long the generation has really been running.- const started = performance.now() - Math.max(0, offsetMs);+ elapsedStart = performance.now() - Math.max(0, offsetMs);stopElapsed();// Reset the meter to a clean running state for this job.if (els.genProgress) {@@ -478,7 +513,7 @@ function startElapsed(offsetMs = 0) {}setProgress(0);const tick = () => {- const s = Math.floor((performance.now() - started) / 1000);+ const s = Math.floor((performance.now() - elapsedStart) / 1000);// Re-read every tick: the accepted job replaces the catalog guess with the// server's real ETA for the lane that actually ran (cold start included).const typical = currentEtaSeconds();@@ -499,9 +534,32 @@ function startElapsed(offsetMs = 0) {}};tick();+ elapsedRetick = tick;elapsedTimer = window.setInterval(tick, 1000);}+// Re-anchor the running meter to the server's own age for this job.+//+// The meter interpolates between polls with a local 1s tick, which is what keeps+// it smooth, but the tick alone has no idea when the JOB started: only when this+// tab did. `elapsed_seconds` on every non-terminal poll frame is measured from+// the creation row, so it is the same number for every viewer of the same job.+// Snapping to it costs nothing when they already agree and is the difference+// between "3s in" and the truth on a resumed page.+//+// A drift under 2s is ignored, so an ordinary round-trip does not re-snap the+// display on every poll; past that the server wins in both directions, because+// the one case that matters (a resumed or coalesced job, where the local clock+// reads far too LOW) is a correction the meter has to make.+function anchorElapsed(serverElapsedS) {+ const s = Number(serverElapsedS);+ if (!Number.isFinite(s) || s < 0 || !elapsedTimer) return;+ const localS = (performance.now() - elapsedStart) / 1000;+ if (Math.abs(s - localS) < 2) return;+ elapsedStart = performance.now() - s * 1000;+ elapsedRetick?.();+}+// Snap the meter to a finished, successful state — the only path to 100%.function markProgressDone() {if (!els.genProgress) return;@@ -512,12 +570,84 @@ function markProgressDone() {}function stopElapsed() {+ elapsedRetick = null;if (elapsedTimer) {window.clearInterval(elapsedTimer);elapsedTimer = null;}}+// ── Pre-submit progress watch ────────────────────────────────────────────────+// POST /api/forge is ONE long request: the art-director pass, the reference-view+// synthesis and (on the fusing lane) the turnaround views all complete inside+// it. Without a second channel the stage list could only report "art-directing+// your prompt" for that whole window, and the reference image the user is really+// waiting to watch appear arrived at the very END of it, with the job id.+//+// So the server records a crumb the moment each of those milestones genuinely+// finishes (api/_lib/forge-progress.js), keyed by a trace id this browser mints,+// and this poll reads them while the POST is still open. Every transition it+// causes is still a real server signal, never a timer. It is also completely+// optional: a poll that answers with nothing (no Redis, a different instance, an+// older deployment) leaves the panel behaving exactly as it did before.+const PROGRESS_POLL_MS = 2500;+let progressWatch = null;++function mintProgressId() {+ const raw =+ typeof crypto?.randomUUID === 'function'+ ? crypto.randomUUID()+ : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}-${Math.random().toString(36).slice(2)}`;+ // The server accepts 16-64 url-safe characters; a UUID with its dashes removed+ // sits comfortably inside that and stays a single token in a query string.+ return raw.replace(/[^A-Za-z0-9_-]/g, '').slice(0, 48);+}++function stopProgressWatch() {+ if (!progressWatch) return;+ progressWatch.stopped = true;+ window.clearTimeout(progressWatch.timer);+ try {+ progressWatch.controller?.abort();+ } catch {+ // An already-settled fetch has nothing to abort.+ }+ progressWatch = null;+}++function startProgressWatch(traceId) {+ stopProgressWatch();+ if (!traceId) return;+ const watch = { stopped: false, timer: 0, controller: null };+ progressWatch = watch;+ const poll = async () => {+ if (watch.stopped) return;+ watch.controller = typeof AbortController === 'function' ? new AbortController() : null;+ try {+ const res = await fetch(`/api/forge?progress=${encodeURIComponent(traceId)}`, {+ headers: CLIENT_HEADERS,+ signal: watch.controller?.signal,+ });+ if (!watch.stopped && res.ok) {+ const data = await res.json().catch(() => null);+ if (Array.isArray(data?.progress) && data.progress.length) timeline.applyProgress(data.progress);+ } else if (!res.ok && res.status !== 429) {+ // This deployment does not serve the progress channel (or refused the+ // trace). One answer is enough to know that: keep polling and we would+ // just fill the console with the same failure for the whole request.+ stopProgressWatch();+ return;+ }+ } catch {+ // A dropped progress poll is invisible on purpose: the submit response+ // carries every one of these facts a moment later regardless.+ }+ if (watch.stopped) return;+ watch.timer = window.setTimeout(poll, PROGRESS_POLL_MS);+ };+ watch.timer = window.setTimeout(poll, PROGRESS_POLL_MS);+}+function setBusy(busy) {els.generate.dataset.busy = busy ? '1' : '0';els.generate.disabled = busy;@@ -1504,7 +1634,7 @@ function forgeHeaders(extra) {return h;}-async function startJob({ prompt, imageUrls, skipValidation, payment, seed }) {+async function startJob({ prompt, imageUrls, skipValidation, payment, seed, progressId }) {const base = { path: selectedEngine.path, tier: selectedTier, backend: selectedEngine.backend };const body =Array.isArray(imageUrls) && imageUrls.length@@ -1518,6 +1648,10 @@ async function startJob({ prompt, imageUrls, skipValidation, payment, seed }) {// Reproducibility: see mintSeed(). Absent on a job replayed from the gallery,// where the original seed was never recorded, so that path stays as it was.if (Number.isInteger(seed)) body.seed = seed;+ // Trace id for the pre-submit progress channel (see startProgressWatch). The+ // server crumbs each finished milestone against it while this request is still+ // open. Purely additive: omit it and the response is identical.+ if (progressId) body.progress_id = progressId;// Caller already saw the vision warning and chose to proceed (Consumer 1).if (skipValidation) body.skip_validation = true;// Pay-per-use proof: a non-holder who paid $THREE for this High generation@@ -1554,6 +1688,20 @@ async function startJob({ prompt, imageUrls, skipValidation, payment, seed }) {e.kind = 'unconfigured';throw e;}+ // Object storage rejected the generation (a rotated credential, an unreachable+ // endpoint). Nothing about the prompt is wrong, no engine switch routes around+ // it, and unlike a quota pause it does not clear in seconds, so it gets its+ // own designed state rather than a countdown that promises a fix it cannot+ // deliver. Models already forged are served from the public CDN and are+ // unaffected, which is the honest alternative to offer.+ if (data.error === 'storage_unavailable') {+ const e = new Error(+ data.message || '3D generation is paused while our asset storage recovers.',+ );+ e.kind = 'storage_down';+ e.retryAfter = Number(data.retry_after) > 0 ? Math.ceil(Number(data.retry_after)) : 60;+ throw e;+ }if (res.status === 503) {const e = new Error(data.message || 'The generator is temporarily unavailable. Try again shortly.',@@ -1727,6 +1875,15 @@ async function pollUntilDone(jobId) {if (data.error === 'invalid_job' || data.error === 'missing_job') {throw new Error(data.message || 'That generation is no longer available.');}+ // The server's elapsed is the JOB's age, measured from the row's+ // created_at; the local meter only knows when THIS tab started counting.+ // Those agree for a job submitted here and diverge for every other case:+ // a resumed session, a coalesced job that joined work already in flight,+ // or a failover successor. Re-anchor the meter to the server's figure so+ // the elapsed readout and the cold-start countdown describe the+ // generation rather than the tab, while the 1s tick keeps them moving+ // smoothly between polls.+ anchorElapsed(data.elapsed_seconds);// One place folds the poll into the stage timeline: queued vs running, the// lane a poll-time failover moved to, and a reference view that only// becomes visible now (coalesced job, resumed session, failover successor).@@ -2086,6 +2243,7 @@ function showResult(glbUrl, label, meta, { autoSaved = false, downloadUrl = nullcurrentResultTier = meta?.tier || selectedTier;updateRefineButton();showState('result');+ revealStage();// Manage focus across the async transition: land on the primary next action// (Download), but never steal focus from a user already working elsewhere,// e.g. a gallery card click or someone mid-typing a new prompt.@@ -2398,9 +2556,15 @@ function showError(message, { allowOverride = false, title = 'Generation failed'if (els.errorLanes) {els.errorLanes.classList.add('is-hidden');els.errorLanes.innerHTML = '';+ // showStorageDown relabels this group for its own contents; every other+ // state that reveals it fills it with engine switches, so reset the name.+ els.errorLanes.setAttribute('aria-label', 'Retry on another engine');}if (els.retry) els.retry.disabled = false;showState('error');+ // A failure the user cannot see is a hang. On a stacked layout the stage sits+ // below the fold, so bring it up before moving focus into it.+ revealStage();// The async flow just landed on an error: put keyboard focus on the primary// recovery action, unless the user is already typing somewhere else.const ax = document.activeElement;@@ -2440,6 +2604,68 @@ function showLaneFailed(message, backends) {els.errorLanes.classList.remove('is-hidden');}+// Object storage is rejecting us, so no lane can finish a generation: every one+// of them has to park a reference image or a finished mesh in the bucket. This+// is the one failure class where "try another engine" is a lie, so instead of+// offering it we tell the user plainly what broke, that it is ours and not+// theirs, and what still works right now: every model they already forged is+// served from the public CDN and opens, downloads and refines exactly as before.+// Retry stays, on the same live countdown as the quota state, because a fixed+// credential recovers within seconds without a redeploy.+function showStorageDown({ retryAfter = 60, message = '' } = {}) {+ stopElapsed();+ timeline.fail();+ stopRateLimitCountdown();+ if (els.generateAnyway) els.generateAnyway.classList.add('is-hidden');++ const canRefineLocally = Boolean(lastShownGlb && els.viewer.getAttribute('src'));+ if (els.refineLocally) els.refineLocally.classList.toggle('is-hidden', !canRefineLocally);++ if (els.errorTitle) els.errorTitle.textContent = 'Our storage is down, not your prompt';++ // The alternative that genuinely works while the bucket is unreachable. This+ // row is normally the engine-switch group, so it says what it holds now.+ if (els.errorLanes) {+ els.errorLanes.innerHTML = '';+ els.errorLanes.setAttribute('aria-label', 'What still works while storage recovers');+ const seeSaved = document.createElement('button');+ seeSaved.type = 'button';+ seeSaved.className = 'btn btn-ghost';+ seeSaved.textContent = 'Open a saved model';+ seeSaved.addEventListener('click', () => {+ els.creations?.scrollIntoView({ behavior: 'smooth', block: 'start' });+ els.creationsGrid?.querySelector('button, [tabindex]')?.focus?.({ preventScroll: true });+ });+ els.errorLanes.appendChild(seeSaved);+ els.errorLanes.classList.remove('is-hidden');+ }++ let remaining = Math.max(1, Math.ceil(retryAfter));+ const base =+ message ||+ '3D generation is paused while our asset storage recovers. Nothing you did caused this and nothing was charged.';+ const tail = canRefineLocally ? ' Your current model is still here: refine it locally, no storage needed.' : '';+ const render = () => {+ els.errorMessage.textContent =+ remaining > 0+ ? `${base} Retrying is available in ${remaining}s.${tail}`+ : `${base} You can try again now.${tail}`;+ };+ if (els.retry) els.retry.disabled = remaining > 0;+ render();+ showState('error');+ revealStage();++ rateLimitTimer = setInterval(() => {+ remaining -= 1;+ if (remaining <= 0) {+ stopRateLimitCountdown();+ if (els.retry) els.retry.disabled = false;+ }+ render();+ }, 1000);+}+// Rate-limit state: a designed, recoverable treatment for a 429. Instead of a// dead-end "busy, try again", we (1) show a live countdown to the reset and// re-enable Retry automatically when it elapses, and (2) — when a model is@@ -2493,6 +2719,7 @@ function showRateLimited({ retryAfter = 10, unavailable = false, busy = false })if (els.retry) els.retry.disabled = remaining > 0;render();showState('error');+ revealStage();rateLimitTimer = setInterval(() => {remaining -= 1;@@ -2537,11 +2764,21 @@ async function run(cfg) {pendingLaneNote = '';startElapsed();showState('generating');+ revealStage();const label = cfg.prompt || (isImage ? 'Multi-view reconstruction' : '');+ // Watch the server's pre-submit milestones for THIS submission while the POST+ // below is still open, so the director's rewrite and the reference view land+ // on the stage list the moment each one genuinely finishes, not at the end.+ const progressId = mintProgressId();+ startProgressWatch(progressId);+try {- const job = await startJob(cfg);+ const job = await startJob({ ...cfg, progressId });+ // The POST answered, so it now carries every fact the crumbs were standing+ // in for. Nothing left to watch.+ stopProgressWatch();if (job.creation_id) currentCreationId = job.creation_id;// Fold every real signal the submit response carries into the timeline: the@@ -2667,6 +2904,12 @@ async function run(cfg) {showRateLimited({ retryAfter: err.retryAfter, unavailable: err.unavailable });return;}+ // Object storage is refusing us. Designed, honest, and pointed at the thing+ // that still works, instead of a raw signing complaint from the store.+ if (err.kind === 'storage_down') {+ showStorageDown({ retryAfter: err.retryAfter, message: err.message });+ return;+ }// Free lane at capacity under load — same recoverable countdown UI, framed as// high demand. Auto-retry lands the user in line as slots free up, and the// local-refine escape hatch still applies when a model is already on screen.@@ -2735,6 +2978,9 @@ async function run(cfg) {'Something went wrong. Try a simpler, single-subject prompt or cleaner photos.',);} finally {+ // Every exit from this job (delivered, cancelled, errored, gated) ends the+ // pre-submit watch, so a poll can never outlive the run that started it.+ stopProgressWatch();setBusy(false);}}diff --git a/tests/forge-progress.test.js b/tests/forge-progress.test.jsnew file mode 100644index 000000000..2cb9b80bf--- /dev/null+++ b/tests/forge-progress.test.js@@ -0,0 +1,85 @@+// Pre-submit progress crumbs (api/_lib/forge-progress.js).+//+// The contract this pins is the one /forge depends on to stop showing "art+// directing your prompt" for the whole of a 40-second POST: a crumb is readable+// the instant the work it names finished, one crumb per stage, and every failure+// mode of the channel degrades to silence rather than to an error a generation+// could trip over.++import { describe, it, expect, vi, beforeEach } from 'vitest';++const store = new Map();+vi.mock('../api/_lib/cache.js', () => ({+ cacheGetFresh: vi.fn(async (key) => (store.has(key) ? store.get(key) : null)),+ cacheSet: vi.fn(async (key, value) => {+ store.set(key, value);+ }),+}));++const { normalizeTraceId, recordForgeProgress, readForgeProgress } = await import(+ '../api/_lib/forge-progress.js'+);+const cache = await import('../api/_lib/cache.js');++const TRACE = 'a1b2c3d4e5f60718293a4b5c6d7e8f90';++describe('forge progress trace ids', () => {+ it('accepts the url-safe ids the page mints and rejects everything else', () => {+ expect(normalizeTraceId(TRACE)).toBe(TRACE);+ expect(normalizeTraceId('short')).toBeNull();+ expect(normalizeTraceId(`${TRACE}/../../etc/passwd`)).toBeNull();+ expect(normalizeTraceId('a'.repeat(200))).toBeNull();+ expect(normalizeTraceId(null)).toBeNull();+ expect(normalizeTraceId({ id: TRACE })).toBeNull();+ });+});++describe('forge progress crumbs', () => {+ beforeEach(() => {+ store.clear();+ vi.clearAllMocks();+ });++ it('reads back the milestones in the order they finished', async () => {+ await recordForgeProgress(TRACE, 'directed', { directed_prompt: 'a brass sundial, studio light' });+ await recordForgeProgress(TRACE, 'reference', { preview_image_url: 'https://cdn.example/ref.png' });+ await recordForgeProgress(TRACE, 'submitting', {});+ const crumbs = await readForgeProgress(TRACE);+ expect(crumbs.map((c) => c.stage)).toEqual(['directed', 'reference', 'submitting']);+ expect(crumbs[0].directed_prompt).toBe('a brass sundial, studio light');+ expect(crumbs[1].preview_image_url).toBe('https://cdn.example/ref.png');+ });++ it('keeps one crumb per stage when a failover repaints a milestone', async () => {+ await recordForgeProgress(TRACE, 'reference', { preview_image_url: 'https://cdn.example/first.png' });+ await recordForgeProgress(TRACE, 'reference', { preview_image_url: 'https://cdn.example/second.png' });+ const crumbs = await readForgeProgress(TRACE);+ expect(crumbs).toHaveLength(1);+ expect(crumbs[0].preview_image_url).toBe('https://cdn.example/second.png');+ });++ it('is a no-op without a usable trace id, so an anonymous POST costs nothing', async () => {+ await recordForgeProgress(null, 'directed', { directed_prompt: 'x' });+ await recordForgeProgress('nope', 'directed', { directed_prompt: 'x' });+ expect(cache.cacheSet).not.toHaveBeenCalled();+ expect(await readForgeProgress(null)).toEqual([]);+ });++ it('refuses a stage it does not define rather than storing arbitrary keys', async () => {+ await recordForgeProgress(TRACE, 'texturing', { fake: true });+ expect(cache.cacheSet).not.toHaveBeenCalled();+ expect(await readForgeProgress(TRACE)).toEqual([]);+ });++ it('answers with silence when the shared cache is unavailable', async () => {+ cache.cacheGetFresh.mockRejectedValueOnce(new Error('redis down'));+ await expect(readForgeProgress(TRACE)).resolves.toEqual([]);+ cache.cacheSet.mockRejectedValueOnce(new Error('redis down'));+ await expect(recordForgeProgress(TRACE, 'directed', {})).resolves.toBeUndefined();+ });++ it('drops a stored value that is not a crumb list', async () => {+ store.set(`forge:progress:${TRACE}`, { stage: 'directed' });+ expect(await readForgeProgress(TRACE)).toEqual([]);+ });+});diff --git a/tests/forge-timeline.test.js b/tests/forge-timeline.test.jsindex 388531890..25cb5ed33 100644--- a/tests/forge-timeline.test.js+++ b/tests/forge-timeline.test.js@@ -190,3 +190,89 @@ describe('forge timeline completion', () => {expect(labelOf('finish')).toBe('Model ready');});});++// The pre-submit progress channel (api/_lib/forge-progress.js writes the crumbs,+// src/forge.js polls them). Its whole point is that the reference view appears+// while the POST is still open instead of arriving with the job id, so these+// pin that the crumbs advance exactly the stages the submit response would have,+// and that a later submit response can never walk that back.+describe('forge timeline pre-submit progress crumbs', () => {+ let timeline;+ beforeEach(() => {+ timeline = mount();+ });++ const detailOf = (id) =>+ document.querySelector(`#stages .step[data-stage="${id}"] .step-detail`)?.textContent;++ it('retires the director stage on the crumb, before any submit response', () => {+ timeline.begin({ mode: 'text', backend: 'trellis_selfhost', usesReference: true });+ expect(stateOf('direct')).toBe('active');+ const changed = timeline.applyProgress([+ { stage: 'directed', at: 1, directed_prompt: 'a brass sundial, weathered patina, studio light' },+ ]);+ expect(changed).toBe(true);+ expect(stateOf('direct')).toBe('done');+ expect(labelOf('direct')).toBe('Prompt art-directed');+ // The next stage is now the one genuinely running.+ expect(stateOf('reference')).toBe('active');+ expect(stateOf('mesh')).toBe('pending');+ });++ it('paints the reference view from the crumb and keeps it after the submit lands', () => {+ timeline.begin({ mode: 'text', backend: 'trellis_selfhost', usesReference: true });+ timeline.applyProgress([+ { stage: 'directed', at: 1, directed_prompt: 'a brass sundial' },+ { stage: 'reference', at: 2, preview_image_url: 'https://cdn.example/ref.png' },+ ]);+ expect(stateOf('reference')).toBe('done');+ expect(+ document.querySelector('#stages .step[data-stage="reference"] .step-thumb')?.getAttribute('href'),+ ).toBe('https://cdn.example/ref.png');+ // A submit response that omits the reference must not drop stages the+ // crumbs already proved happened.+ timeline.applySubmit({ status: 'queued', backend: 'trellis_selfhost' });+ expect(stageIds()).toEqual(['direct', 'reference', 'mesh', 'finish']);+ expect(stateOf('reference')).toBe('done');+ });++ it('starts the mesh row on the submitting crumb and names the turnaround views', () => {+ timeline.begin({ mode: 'text', backend: 'trellis_selfhost', usesReference: true });+ timeline.applyProgress([+ { stage: 'directed', at: 1, directed_prompt: null },+ { stage: 'reference', at: 2, preview_image_url: 'https://cdn.example/ref.png' },+ { stage: 'views', at: 3, view_count: 3 },+ { stage: 'submitting', at: 4 },+ ]);+ expect(detailOf('reference')).toContain('2 turnaround views');+ expect(stateOf('mesh')).toBe('active');+ expect(detailOf('mesh')).toContain('Handing the reference views to TRELLIS');+ // A director that genuinely left the prompt alone says so, and never+ // claims a rewrite that did not happen.+ expect(labelOf('direct')).toBe('Prompt used as you wrote it');+ });++ it('ignores crumbs once the submit response has landed', () => {+ timeline.begin({ mode: 'text', backend: 'trellis_selfhost', usesReference: true });+ timeline.applySubmit({+ status: 'queued',+ backend: 'trellis_selfhost',+ preview_image_url: 'https://cdn.example/real.png',+ });+ const changed = timeline.applyProgress([+ { stage: 'reference', at: 9, preview_image_url: 'https://cdn.example/stale.png' },+ ]);+ expect(changed).toBe(false);+ expect(+ document.querySelector('#stages .step[data-stage="reference"] .step-thumb')?.getAttribute('href'),+ ).toBe('https://cdn.example/real.png');+ });++ it('does nothing at all when the channel reports nothing', () => {+ timeline.begin({ mode: 'text', backend: 'trellis_selfhost', usesReference: true });+ expect(timeline.applyProgress([])).toBe(false);+ expect(timeline.applyProgress(null)).toBe(false);+ expect(stateOf('direct')).toBe('active');+ expect(stateOf('reference')).toBe('pending');+ });+});