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.

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.js
new file mode 100644
index 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.js
index 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.html
index 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.js
index 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.js
index 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 = null
currentResultTier = 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.js
new file mode 100644
index 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.js
index 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');
+ });
+});