@civitai/blocks-react 0.70.0 → 0.72.0

package/dist/internal/mockHost.js

@@ -39,11 +39,14 @@
  */
 import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED, APP_STORAGE_ERROR_USER_ROW_LIMIT, APP_STORAGE_ERROR_VALUE_TOO_LARGE, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, APP_STORAGE_MAX_VALUE_BYTES, BrowsingLevel, SFW_LEVELS, } from '@civitai/app-sdk/blocks';
 import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
+import { PAGE_CHECKPOINT_PERSIST_ERROR, emulatesPageHost } from './hostSurface.js';
 import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, storageScopeDeniedPayload, } from './mockHostScopes.js';
 import { governsIdempotencyKey, idempotencyKeyDeniedMessage, idempotencyKeyRefusal, } from './mockHostIdempotency.js';
 import { SAVE_IMAGE_INVALID_REQUEST_ERROR, prepareSaveBytes, saveImageRequestKind, } from './saveBytes.js';
 import { UPLOAD_BYTES_INVALID_ERROR, admitUploadBytes, resolveUploadBytesRequest, } from './uploadBytes.js';
+import { mockUnpricedWorkflowRefusal, mockUnquotedWorkflowEstimateRefusal, mockWorkflowBodyRefusal, mockWorkflowStepGenerations, mockWorkflowStepName, } from './mockWorkflowGraph.js';
 import { BATCH_ESTIMATE_CELL_TIMEOUT_ERROR } from '../hooks/useBatchEstimate.js';
+import { RUN_CONFIRMED_STEP_ERROR_CODES, STEP_QUOTE_ID_PATTERN, } from '../hooks/useRunConfirmedStep.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
@@ -87,6 +90,9 @@ const preferredAccountType = (body) => {
         // is `.strict()` with no `accountType`.
         case 'training':
             return undefined;
+        // Nor does a multi-step body: the kind has no `accountType` field.
+        case 'workflow':
+            return undefined;
         default: {
             // Exhaustiveness check: a new `WorkflowBody` member makes this assignment
             // fail to compile, right here, rather than defaulting somewhere.
@@ -215,6 +221,152 @@ const MOCK_TRAINING_IN_BATCH_ERROR = 'a training estimate cannot be part of a ba
 const DEFAULT_TRAINING_QUOTE_TOTAL = 500;
 /** The real quote lifetime (`BLOCK_TRAINING_QUOTE_TTL_SECONDS`, 15 min). */
 const TRAINING_QUOTE_TTL_MS = 15 * 60_000;
+/**
+ * The per-job ceiling of a confirmed step — a COPY of `@civitai/app-sdk/blocks`'s
+ * `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`, not value-imported for the reason
+ * given on {@link MOCK_TRAINING_BOUNDS}. Pinned to the SDK's value by
+ * `test/confirmedStepFlow.test.tsx`, which imports both.
+ */
+export const MOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB = 5000;
+/** The real quote lifetime (`BLOCK_QUOTE_GRANT_TTL_SECONDS`, 15 min) — the training quote's, shared. */
+const STEP_QUOTE_TTL_MS = TRAINING_QUOTE_TTL_MS;
+/**
+ * The real server's refusal when the host reads back a step quote it does not
+ * hold — unknown, expired, or already used by an earlier run. This is the
+ * PREVIEW's message, which is the one `RUN_CONFIRMED_STEP` reaches first.
+ */
+export const MOCK_STEP_QUOTE_GONE_ERROR = 'step quote not found or expired';
+/** The real server's refusal for a confirmed run whose body is not the quoted one. */
+export const MOCK_STEP_BODY_MISMATCH_ERROR = 'the step body differs from the one that was quoted — estimate again';
+/**
+ * The real server's refusal for a `quoteId` body sent as a plain
+ * `SUBMIT_WORKFLOW`: nothing but `RUN_CONFIRMED_STEP`'s dialog records the
+ * viewer's confirmation.
+ */
+export const MOCK_STEP_NOT_CONFIRMED_ERROR = 'this step has not been confirmed by the viewer in this session';
+/**
+ * The forced `RUN_CONFIRMED_STEP` errors that settle BEFORE the server claims
+ * (and so consumes) the quote: the host's own gate, dialog and daily-limit
+ * codes. Derived from the host-code list — every code except
+ * `submission-unconfirmed`, which the host emits only after a submit was sent.
+ */
+const PRE_CLAIM_RUN_CONFIRMED_STEP_ERRORS = new Set(RUN_CONFIRMED_STEP_ERROR_CODES.filter((c) => c !== 'submission-unconfirmed'));
+/**
+ * The orchestrator's training `$type`s, which never run as a confirmed step —
+ * matched CASE-INSENSITIVELY, as the server refuses a caller-supplied `$type`
+ * (`isTrainingStepTypeIgnoringCase`): `Training` or `IMAGERESOURCETRAINING` is
+ * refused like the canonical spelling. Only for refusing a submitted `$type`;
+ * the trained-epochs simulation keys on the exact spelling, as the host does.
+ */
+const TRAINING_STEP_TYPES_FOLDED = new Set([
+    'training',
+    'imageresourcetraining',
+]);
+const isTrainingStepTypeName = (stepType) => TRAINING_STEP_TYPES_FOLDED.has(stepType.toLowerCase());
+/**
+ * The orchestrator `$type` of a PASS-THROUGH step body, else `undefined`. Keyed
+ * on the VALUE of `step`, as the host keys it — a registered step names a
+ * `step` id and is a different arm.
+ */
+const passThroughStepType = (body) => {
+    const b = body;
+    return b.kind === 'step' && b.step === undefined && typeof b.$type === 'string'
+        ? b.$type
+        : undefined;
+};
+/**
+ * The real server's refusal for a TRAINING `$type` (`training`,
+ * `imageResourceTraining`) on the confirmed-step path — at the estimate, where a
+ * quote would otherwise be granted, and at the confirmed submit. Training runs
+ * have their own kind.
+ */
+export const MOCK_STEP_TRAINING_TYPE_ERROR = "a training step type cannot run as a confirmed step — use kind:'training'";
+/**
+ * The fixed PREFIX of the real server's refusal for a confirmed-step body whose
+ * `input` is not plain JSON. The full message continues with the offending path
+ * and what was found there (`body.input.when is a Date`), which varies — match on
+ * this prefix.
+ */
+export const MOCK_STEP_NON_JSON_INPUT_ERROR_PREFIX = 'a confirmed step needs plain JSON input (objects, arrays, strings, finite numbers, booleans, null) — ';
+/** Thrown by {@link canonicalStepJson} for a value that is not plain JSON. */
+class NonJsonStepBodyError extends Error {
+}
+/** How the server names a non-JSON value in its refusal. */
+const describeNonJson = (value) => {
+    if (value === undefined)
+        return 'undefined';
+    if (typeof value === 'number')
+        return `the non-finite number ${String(value)}`;
+    if (typeof value === 'object' && value !== null) {
+        const name = Object.getPrototypeOf(value)
+            ?.constructor?.name;
+        return name ? `a ${name}` : 'a non-plain object';
+    }
+    return `a ${typeof value}`;
+};
+/**
+ * The canonical form the server hashes a quoted body in, mirrored: JSON with
+ * object keys sorted at EVERY depth, so two bodies with the same values compare
+ * equal however they were written. EXACT, OR IT THROWS — only plain objects,
+ * arrays, strings, finite numbers, booleans and `null` are accepted. A `Date`,
+ * `Map`, `Set`, class instance, `BigInt`, `NaN`/`Infinity`, an `undefined`
+ * array element or an empty slot in a sparse array throws {@link NonJsonStepBodyError} naming the path, because a
+ * looser form would give two different such values the same bytes. An object
+ * key whose value is `undefined` is skipped, as JSON drops it.
+ */
+const canonicalStepJson = (value, path) => {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string' || typeof value === 'boolean')
+        return JSON.stringify(value);
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new NonJsonStepBodyError(`${path} is ${describeNonJson(value)}`);
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        // BY INDEX, not `map`: `map` and `join` skip a hole, so a sparse array would
+        // bind as if its empty slots were not there. The server refuses a hole.
+        const entries = [];
+        for (let i = 0; i < value.length; i += 1) {
+            if (!(i in value))
+                throw new NonJsonStepBodyError(`${path}[${i}] is an empty array slot`);
+            entries.push(canonicalStepJson(value[i], `${path}[${i}]`));
+        }
+        return `[${entries.join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null) {
+            throw new NonJsonStepBodyError(`${path} is ${describeNonJson(value)}`);
+        }
+        const record = value;
+        const entries = Object.keys(record)
+            .filter((k) => record[k] !== undefined)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonicalStepJson(record[k], `${path}.${k}`)}`);
+        return `{${entries.join(',')}}`;
+    }
+    throw new NonJsonStepBodyError(`${path} is ${describeNonJson(value)}`);
+};
+/**
+ * What the server binds a step quote to: the body WITHOUT its `quoteId` (the one
+ * field the run adds), in canonical form. Returns the fingerprint, or the
+ * server's refusal message when the body is not plain JSON.
+ */
+const stepBodyFingerprint = (body) => {
+    const { quoteId: _quoteId, ...rest } = body;
+    try {
+        return { fingerprint: canonicalStepJson(rest, 'body') };
+    }
+    catch (e) {
+        if (e instanceof NonJsonStepBodyError) {
+            return { refusal: `${MOCK_STEP_NON_JSON_INPUT_ERROR_PREFIX}${e.message}` };
+        }
+        throw e;
+    }
+};
 // The canned picks carry the WIDENED BlockResourceInfo projection (PR-C) — the
 // public recommended settings a real host now returns — so dev:mock mirrors prod
 // (a picked resource seeds a weight slider + trigger words). Defaults match the
@@ -639,6 +791,8 @@ function jsonByteSize(value) {
  * map onto the new scenario groups so a dev can flip out-of-Buzz /
  * failures / latency without editing code. `?capRefusal=1` (or `=<text>`) sets
  * {@link MockGenerationScenario.submitCapRefusal}.
+ * `?confirmedStep=declined|daily-limit|unconfirmed` sets
+ * {@link MockHostOptions.runConfirmedStepError}.
  *
  * Returns a partial overlay applied ON TOP of explicit {@link MockHostOptions}
  * (URL wins — it's the interactive dev knob). No-op outside a browser.
@@ -751,6 +905,17 @@ export function readMockHostUrlOptions(win = globalThis
         generation.submitCapRefusal =
             capRefusal === '1' || capRefusal === 'true' ? true : capRefusal;
     }
+    // ?confirmedStep=declined|daily-limit|unconfirmed → how RUN_CONFIRMED_STEP
+    // settles (see `runConfirmedStepError`). Absent, or any other value: the viewer
+    // "confirms" and the job starts. Pair it with a `?costPerGen=` above the
+    // per-call budget, which is what makes the estimate quote a confirmed step.
+    const confirmedStep = params.get('confirmedStep');
+    if (confirmedStep === 'declined')
+        out.runConfirmedStepError = 'declined';
+    else if (confirmedStep === 'daily-limit')
+        out.runConfirmedStepError = 'daily-limit-exceeded';
+    else if (confirmedStep === 'unconfirmed')
+        out.runConfirmedStepError = 'submission-unconfirmed';
     if (Object.keys(generation).length > 0)
         out.generation = generation;
     if (Object.keys(buzz).length > 0)
@@ -903,6 +1068,9 @@ export function createMockHost(options = {}) {
     // image is never added: production leaves it unstamped, so it is not postable.
     const postableImageIds = new Set(options.postableImageIds ?? []);
     let runTrainingCapRefusal = options.runTrainingCapRefusal;
+    // Confirmed step: forced-refusal knobs. The quotes themselves live per install.
+    let runConfirmedStepError = options.runConfirmedStepError;
+    let runConfirmedStepCapRefusal = options.runConfirmedStepCapRefusal;
     // App-subqueue bridge data + forced free-text-error knob. `appWorkflows` is
     // MUTABLE — CANCEL_APP_WORKFLOW marks the matching row canceled in place so a
     // follow-up QUERY reflects it.
@@ -989,11 +1157,43 @@ export function createMockHost(options = {}) {
         // Per-viewer vote state (the mock's `mockUserId` is the "requesting viewer").
         viewerVoted: row.voters.has(mockUserId),
     });
+    /** Why a `kind: 'workflow'` body has no price quote, or `null` when it is quoted. */
+    const workflowQuoteFailure = () => {
+        const knob = gen.workflowUnpriced;
+        if (knob === true)
+            return 'unavailable';
+        return knob === 'rejected' || knob === 'unavailable' || knob === 'unpriced' ? knob : null;
+    };
     // Resolve a per-gen cost from the scenario (or legacy `cost`).
+    // A `kind: 'workflow'` body is the SUM of its steps — see `workflowStepCosts`.
     const costFor = (body) => {
+        if (body.kind === 'workflow')
+            return workflowStepCosts(body).reduce((sum, c) => sum + c, 0);
         const spec = gen.costPerGen ?? legacyCost;
         return typeof spec === 'function' ? spec(body) : (spec ?? legacyCost);
     };
+    /**
+     * `costPerGen`, called once per step of a `kind: 'workflow'` body and
+     * multiplied by that step's generations — 1, or a `repeat`'s iteration count —
+     * because the orchestrator's quote prices every child of a bounded repeat.
+     */
+    const workflowStepCosts = (body) => {
+        // Unpriced: reserved at the ceiling, one per-generation budget per step.
+        if (workflowQuoteFailure() !== null)
+            return body.steps.map(() => buzzBudget);
+        const spec = gen.costPerGen ?? legacyCost;
+        return (Array.isArray(body.steps) ? body.steps : []).map((step, index) => {
+            const each = typeof spec === 'function'
+                ? spec(body, {
+                    index,
+                    name: mockWorkflowStepName(step, index),
+                    $type: step.$type,
+                    input: step.input,
+                })
+                : spec;
+            return each * mockWorkflowStepGenerations(step.$type, step.input, body.arguments);
+        });
+    };
     // `null` = this quote is not itemised (a fee-less kind, or `authorFee: false`).
     const authorFeeFor = (body) => {
         if (gen.authorFee === false)
@@ -1001,9 +1201,16 @@ export function createMockHost(options = {}) {
         // A REGISTERED step is keyed on the VALUE of `step`, as the host keys it —
         // never `'step' in body`: `{ kind: 'step', step: undefined, ... }` is a legal
         // pass-through body, and a pass-through quote prices no fee.
-        const quotesFee = body.kind === 'textToImage' || (body.kind === 'step' && typeof body.step === 'string');
+        // A `workflow` body quotes ONE fee for the whole workflow: this function is
+        // called once per body and never per step.
+        const quotesFee = body.kind === 'textToImage' ||
+            body.kind === 'workflow' ||
+            (body.kind === 'step' && typeof body.step === 'string');
         if (!quotesFee)
             return null;
+        // An unpriced workflow has no quoted base, so no fee is priced on it.
+        if (body.kind === 'workflow' && workflowQuoteFailure() !== null)
+            return 0;
         const spec = gen.authorFee ?? 0;
         return typeof spec === 'function' ? spec(body) : spec;
     };
@@ -1098,6 +1305,10 @@ export function createMockHost(options = {}) {
         // quotes its estimates stored (id → what a run is checked against).
         const trainingDatasets = new Map();
         const trainingQuotes = new Map();
+        // Confirmed steps: the quotes this install's estimates stored (id → what a
+        // run is checked against). Same serial as the training handles, so every
+        // handle this install mints is distinct.
+        const stepQuotes = new Map();
         let trainingSerial = 0;
         /** `<prefix>` + 32 hex characters — the real handles' shape. */
         const trainingHandle = (prefix) => {
@@ -1149,16 +1360,102 @@ export function createMockHost(options = {}) {
                 ...(gen.trainingPublishedModel ? { publishedModel: { ...gen.trainingPublishedModel } } : {}),
             };
         };
+        /**
+         * The `steps` (and the top-level `imageUrls` they add up to) of a
+         * `kind: 'workflow'` run, given each step's status. A step reports images
+         * only once it has `'succeeded'` and only if it did not set
+         * `suppressOutput`; the top-level list is the union of those, in step order.
+         */
+        const workflowStepsView = (workflowId, body, statusOf, failedError) => {
+            const lastVisible = body.steps.reduce((last, s, i) => (s.suppressOutput === true ? last : i), -1);
+            const steps = body.steps.map((step, index) => {
+                const status = statusOf(index);
+                const name = mockWorkflowStepName(step, index);
+                const visible = status === 'succeeded' && step.suppressOutput !== true;
+                return {
+                    name,
+                    $type: step.$type,
+                    status,
+                    ...(visible
+                        ? {
+                            imageUrls: index === lastVisible
+                                ? imagesFor(workflowId, body)
+                                : [
+                                    `https://placehold.co/512x512/1971c2/ffffff/png?text=MOCK%0A${encodeURIComponent(name)}`,
+                                ],
+                        }
+                        : {}),
+                    ...(status === 'failed' && failedError !== undefined ? { error: failedError } : {}),
+                };
+            });
+            const imageUrls = steps.flatMap((s) => s.imageUrls ?? []);
+            return { steps, ...(imageUrls.length > 0 ? { imageUrls } : {}) };
+        };
+        /** A RUNNING `kind: 'workflow'` run after `polls` polls: steps finish in order. */
+        const workflowProgressView = (workflowId, body, polls) => {
+            const total = body.steps.length;
+            const failing = failingWorkflowStep(body);
+            const done = Math.min(Math.floor((total * polls) / Math.max(1, pollsUntilDone)), total - 1, failing === -1 ? total - 1 : failing);
+            return workflowStepsView(workflowId, body, (i) => i < done ? 'succeeded' : i === done ? 'processing' : 'pending');
+        };
+        /** Index of the step `generation.failWorkflowStep` names, or `-1`. */
+        const failingWorkflowStep = (body) => {
+            const target = gen.failWorkflowStep;
+            if (target === undefined)
+                return -1;
+            return body.steps.findIndex((s, i) => mockWorkflowStepName(s, i) === target);
+        };
+        /**
+         * The terminal snapshot of a `kind: 'workflow'` run whose step
+         * `generation.failWorkflowStep` names failed, or `null` when none does.
+         * Earlier steps stay `'succeeded'` and CHARGED, so `cost.total` is their sum
+         * and their visible images are still there.
+         */
+        const workflowPartialFailure = (workflowId) => {
+            const wf = workflows.get(workflowId);
+            const body = wf?.body;
+            if (!wf || body?.kind !== 'workflow')
+                return null;
+            const failing = failingWorkflowStep(body);
+            if (failing === -1)
+                return null;
+            const error = `mock: step "${mockWorkflowStepName(body.steps[failing], failing)}" failed`;
+            const charged = (wf.stepCosts ?? []).slice(0, failing).reduce((sum, c) => sum + c, 0);
+            return {
+                workflowId,
+                status: 'failed',
+                cost: { total: charged },
+                error,
+                ...workflowStepsView(workflowId, body, (i) => (i < failing ? 'succeeded' : i === failing ? 'failed' : 'canceled'), error),
+            };
+        };
         const succeededSnapshot = (workflowId) => {
             const wf = workflows.get(workflowId);
             const cost = wf?.cost ?? legacyCost;
             const body = wf?.body ?? {};
+            if (body.kind === 'workflow') {
+                return {
+                    workflowId,
+                    status: 'succeeded',
+                    cost: { total: cost },
+                    ...workflowStepsView(workflowId, body, () => 'succeeded'),
+                    spentAccountType: primaryFunder(buzzBalance),
+                };
+            }
+            // 3D labels: a pass-through step only (see `generation.model3dOutputs`).
+            const model3d = gen.model3dOutputs && gen.model3dOutputs.length > 0 && passThroughStepType(body)
+                ? gen.model3dOutputs.map((m) => ({ ...m }))
+                : undefined;
             return {
                 ...trainingFields(body),
+                ...(model3d ? { model3dOutputs: model3d } : {}),
                 workflowId,
                 status: 'succeeded',
                 cost: { total: cost },
-                imageUrls: imagesFor(workflowId, body),
+                // Every labelled model url is also an `imageUrls` entry on the real host.
+                imageUrls: model3d && !gen.images && !gen.image
+                    ? model3d.map((m) => m.url)
+                    : imagesFor(workflowId, body),
                 // Pick-aware APPROXIMATION of the real backend's
                 // BlockWorkflowSnapshot.spentAccountType. The real backend stamps the
                 // LARGEST realized debit (`primaryDebitedAccountType`), and its currency
@@ -1247,7 +1544,11 @@ export function createMockHost(options = {}) {
                  * ESTIMATE_WORKFLOW and ESTIMATE_WORKFLOW_BATCH so a batch cell is priced
                  * exactly as a single estimate of the same body.
                  */
-                const estimateSnapshotFor = (body) => {
+                const estimateSnapshotFor = (body, 
+                // TRUE only from the single ESTIMATE_WORKFLOW. The server's batch
+                // estimate persists nothing, so a batch cell never stores a
+                // confirmed-step quote and never carries a `stepQuote`.
+                opts) => {
                     // UNUSABLE-ESTIMATE simulation (`generation.failEstimate`). Reproduces
                     // the two real producers byte-for-byte so a block's `catch` around
                     // `estimate()` is exercisable locally — see the knob's docs for why
@@ -1328,6 +1629,68 @@ export function createMockHost(options = {}) {
                             },
                         };
                     }
+                    // CONFIRMED-STEP QUOTE — kind-faithful, like the training arm above. A
+                    // pass-through step whose (fixed) price is above the token's per-call
+                    // budget and within the per-job ceiling gets a stored, viewer-
+                    // confirmable quote beside its ordinary estimate; every other estimate
+                    // is exactly what it was. The server grants it only to a signed-in
+                    // viewer's page token, which is what `viewer !== null` stands for here.
+                    const stepType = passThroughStepType(body);
+                    const stepPrice = stepType === undefined ? 0 : costFor(body);
+                    if (opts.storeQuotes &&
+                        stepType !== undefined &&
+                        viewer !== null &&
+                        stepPrice > buzzBudget &&
+                        stepPrice <= MOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB) {
+                        // From here a quote WOULD be granted, so the two bodies that must
+                        // never get one are refused out loud, as the server refuses them: it
+                        // throws `BAD_REQUEST`, which the page host catches into
+                        // `failureSnapshot(err)` — so `estimate()` rejects instead of
+                        // returning a price. Below the budget (or in a batch) neither check
+                        // runs and the estimate is the ordinary one.
+                        if (isTrainingStepTypeName(stepType)) {
+                            return { workflowId: 'failed', status: 'failed', error: MOCK_STEP_TRAINING_TYPE_ERROR };
+                        }
+                        const bound = stepBodyFingerprint(body);
+                        if ('refusal' in bound) {
+                            return { workflowId: 'failed', status: 'failed', error: bound.refusal };
+                        }
+                        const quoteId = trainingHandle('sq_');
+                        const expiresAtMs = Date.now() + STEP_QUOTE_TTL_MS;
+                        stepQuotes.set(quoteId, {
+                            fingerprint: bound.fingerprint,
+                            total: stepPrice,
+                            expiresAtMs,
+                            spent: false,
+                        });
+                        return {
+                            workflowId: 'wf_estimate',
+                            status: 'pending',
+                            cost: quotedCost(body),
+                            stepQuote: {
+                                quoteId,
+                                total: stepPrice,
+                                stepType,
+                                expiresAt: new Date(expiresAtMs).toISOString(),
+                            },
+                        };
+                    }
+                    // MULTI-STEP — the second kind-faithful arm: the host refuses a body
+                    // it will not run BEFORE pricing it, with an `errorCode`, in the
+                    // `failureSnapshot` shape (no `cost`). A body that passes is priced
+                    // below like any other: `quotedCost` sums the steps and adds ONE fee.
+                    if (body.kind === 'workflow') {
+                        // With no quote the estimate has no price to show: it fails with the
+                        // cause, never the ceiling. (The submit of the same body proceeds.)
+                        const failure = workflowQuoteFailure();
+                        const refusal = mockWorkflowBodyRefusal(body) ??
+                            (failure === null
+                                ? null
+                                : (mockUnpricedWorkflowRefusal(body, failure) ??
+                                    mockUnquotedWorkflowEstimateRefusal(failure)));
+                        if (refusal !== null)
+                            return { workflowId: 'failed', status: 'failed', ...refusal };
+                    }
                     return {
                         workflowId: 'wf_estimate',
                         status: 'pending',
@@ -1445,7 +1808,7 @@ export function createMockHost(options = {}) {
                         const body = typed.payload?.body ?? {};
                         dispatchToBlock({
                             type: 'ESTIMATE_RESULT',
-                            payload: { requestId, snapshot: estimateSnapshotFor(body) },
+                            payload: { requestId, snapshot: estimateSnapshotFor(body, { storeQuotes: true }) },
                         });
                         return;
                     }
@@ -1518,7 +1881,7 @@ export function createMockHost(options = {}) {
                                     error: MOCK_TRAINING_IN_BATCH_ERROR,
                                 };
                             }
-                            return estimateSnapshotFor(cell ?? {});
+                            return estimateSnapshotFor(cell ?? {}, { storeQuotes: false });
                         });
                         // The server's aggregate rule: the cells that priced, i.e. not
                         // `'failed'` and carrying a numeric `cost.total`.
@@ -1611,6 +1974,45 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        // A pass-through body naming a `quoteId` asks to be charged against a
+                        // viewer-confirmed quote, and only RUN_CONFIRMED_STEP's dialog records
+                        // that confirmation — so as a plain submit the server refuses it. Its
+                        // own message, in the host's `failureSnapshot` shape.
+                        // (`useBuzzWorkflow().submit()` refuses before sending; this covers a
+                        // raw transport send.)
+                        if (body.kind === 'step' &&
+                            body.quoteId !== undefined) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_SUBMITTED',
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        workflowId: 'failed',
+                                        status: 'failed',
+                                        error: MOCK_STEP_NOT_CONFIRMED_ERROR,
+                                    },
+                                },
+                            });
+                            return;
+                        }
+                        // A `kind: 'workflow'` body the host will not run is refused here,
+                        // before any cap, balance or debit — the same refusal, with the same
+                        // `errorCode`, the estimate gives. No `cost`, so `submit()` rejects.
+                        if (body.kind === 'workflow') {
+                            const failure = workflowQuoteFailure();
+                            const refusal = mockWorkflowBodyRefusal(body) ??
+                                (failure === null ? null : mockUnpricedWorkflowRefusal(body, failure));
+                            if (refusal !== null) {
+                                dispatchToBlock({
+                                    type: 'WORKFLOW_SUBMITTED',
+                                    payload: {
+                                        requestId,
+                                        snapshot: { workflowId: 'failed', status: 'failed', ...refusal },
+                                    },
+                                });
+                                return;
+                            }
+                        }
                         const cost = costFor(body);
                         // What the viewer pays: the generation plus the app fee.
                         const charged = cost + (authorFeeFor(body) ?? 0);
@@ -1758,7 +2160,12 @@ export function createMockHost(options = {}) {
                         if (balanceSimulated)
                             buzz.balance = buzz.balance - charged;
                         const workflowId = `wf_${submitCount}_${Date.now()}`;
-                        workflows.set(workflowId, { polls: 0, cost, body });
+                        workflows.set(workflowId, {
+                            polls: 0,
+                            cost,
+                            body,
+                            ...(body.kind === 'workflow' ? { stepCosts: workflowStepCosts(body) } : {}),
+                        });
                         dispatchToBlock({
                             type: 'WORKFLOW_SUBMITTED',
                             payload: { requestId, snapshot: { workflowId, status: 'pending' } },
@@ -1784,6 +2191,16 @@ export function createMockHost(options = {}) {
                         }
                         const polls = wf.polls + 1;
                         wf.polls = polls;
+                        // A `kind: 'workflow'` run with a step told to fail ends `failed`
+                        // with its earlier steps intact (`generation.failWorkflowStep`).
+                        const partialFailure = polls >= pollsUntilDone ? workflowPartialFailure(workflowId) : null;
+                        if (partialFailure !== null) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_STATUS',
+                                payload: { requestId, snapshot: partialFailure },
+                            });
+                            return;
+                        }
                         const outcome = polls >= pollsUntilDone ? (gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded') : null;
                         if (outcome === 'failed' || outcome === 'expired') {
                             dispatchToBlock({
@@ -1814,7 +2231,17 @@ export function createMockHost(options = {}) {
                         else {
                             dispatchToBlock({
                                 type: 'WORKFLOW_STATUS',
-                                payload: { requestId, snapshot: { workflowId, status: 'processing' } },
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        workflowId,
+                                        status: 'processing',
+                                        // A multi-step run reports how far its steps have got.
+                                        ...(wf.body?.kind === 'workflow'
+                                            ? workflowProgressView(workflowId, wf.body, polls)
+                                            : {}),
+                                    },
+                                },
                             });
                         }
                         return;
@@ -1835,6 +2262,14 @@ export function createMockHost(options = {}) {
                         if (wf && !wf.canceled && wf.polls >= pollsUntilDone) {
                             // Already finished: like the real host, report the real terminal
                             // status rather than pretending the cancel took.
+                            const partialFailure = workflowPartialFailure(workflowId);
+                            if (partialFailure !== null) {
+                                dispatchToBlock({
+                                    type: 'WORKFLOW_CANCELED',
+                                    payload: { requestId, snapshot: partialFailure },
+                                });
+                                return;
+                            }
                             const outcome = gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded';
                             dispatchToBlock({
                                 type: 'WORKFLOW_CANCELED',
@@ -2259,6 +2694,84 @@ export function createMockHost(options = {}) {
                         });
                         return reply({ snapshot: { workflowId, status: 'pending' } });
                     }
+                    case 'RUN_CONFIRMED_STEP': {
+                        // The host's gate (`runConfirmedStepGate.ts`): no requestId → drop;
+                        // signed-out → `sign in to run`; not a pass-through `kind:'step'`
+                        // body naming an `sq_`-shaped `quoteId` → `invalid confirmed step
+                        // request`. Then the server: the spend scope, then the quote the host
+                        // reads back for its dialog (unknown, expired or already spent).
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        const reply = (payload) => dispatchToBlock({
+                            type: 'CONFIRMED_STEP_RESULT',
+                            payload: { requestId, ...payload },
+                        });
+                        if (viewer === null)
+                            return reply({ error: 'sign in to run' });
+                        const raw = typed.payload?.body;
+                        const b = raw && typeof raw === 'object' && !Array.isArray(raw)
+                            ? raw
+                            : null;
+                        if (!b ||
+                            b.kind !== 'step' ||
+                            typeof b.$type !== 'string' ||
+                            typeof b.quoteId !== 'string' ||
+                            !STEP_QUOTE_ID_PATTERN.test(b.quoteId)) {
+                            return reply({ error: 'invalid confirmed step request' });
+                        }
+                        if (!consentGranted)
+                            return reply({ error: MOCK_SPEND_SCOPE_ERROR });
+                        const quote = stepQuotes.get(b.quoteId);
+                        if (!quote || quote.spent || Date.now() >= quote.expiresAtMs) {
+                            return reply({ error: MOCK_STEP_QUOTE_GONE_ERROR });
+                        }
+                        // Which outcomes consume the quote — the same split as RUN_TRAINING
+                        // above: the host's gate, its daily-limit explanation and its confirm
+                        // come first (quote kept); the submit then claims the quote before any
+                        // of its own checks, so every server outcome consumes it.
+                        if (runConfirmedStepError !== undefined) {
+                            if (!PRE_CLAIM_RUN_CONFIRMED_STEP_ERRORS.has(runConfirmedStepError)) {
+                                quote.spent = true;
+                            }
+                            return reply({ error: runConfirmedStepError });
+                        }
+                        // The submit's preflight refuses a training `$type` BEFORE it touches
+                        // the quote, so the quote is kept.
+                        if (isTrainingStepTypeName(b.$type)) {
+                            return reply({ error: MOCK_STEP_TRAINING_TYPE_ERROR });
+                        }
+                        quote.spent = true;
+                        // The body is hashed AFTER the claim, so a body the server cannot bind
+                        // (non-plain-JSON input) and a body that differs both consume the quote.
+                        const bound = stepBodyFingerprint(b);
+                        if ('refusal' in bound)
+                            return reply({ error: bound.refusal });
+                        if (bound.fingerprint !== quote.fingerprint) {
+                            return reply({ error: MOCK_STEP_BODY_MISMATCH_ERROR });
+                        }
+                        // The server's cap refusals RESOLVE (refunded, no job started) — after
+                        // the quote was consumed above.
+                        if (runConfirmedStepCapRefusal !== undefined) {
+                            return reply({
+                                snapshot: {
+                                    workflowId: 'failed',
+                                    status: 'failed',
+                                    cost: { total: quote.total },
+                                    error: runConfirmedStepCapRefusal,
+                                },
+                            });
+                        }
+                        // Every confirmation is its own job: the charge is the confirmed
+                        // price, never `maxBuzz`.
+                        submitCount += 1;
+                        const workflowId = `wf_${submitCount}_${Date.now()}`;
+                        workflows.set(workflowId, {
+                            polls: 0,
+                            cost: quote.total,
+                            body: raw,
+                        });
+                        return reply({ snapshot: { workflowId, status: 'pending' } });
+                    }
                     case 'PUBLISH_GENERATION_OUTPUTS': {
                         // Publish selected outputs of one of the app's OWN workflows as bare,
                         // real-scanned public Image rows. Drop a request with no requestId
@@ -2938,13 +3451,27 @@ export function createMockHost(options = {}) {
                         return saveReply({ ok: true });
                     }
                     case 'SET_USER_CHECKPOINT': {
-                        // Persist the checkpoint override (mirrors the real host's
-                        // block_user_settings write). Accept a numeric versionId OR an
-                        // explicit null (clear); anything else is a bad-input NACK, same as
-                        // the real IframeHost. Without this reply `useCheckpointPicker().
-                        // persist()` hung to its 30s timeout under the mock host.
+                        // Without a reply `useCheckpointPicker().persist()` hung to its 30s
+                        // timeout under the mock host.
                         if (!isRoutableRequestId(requestId))
                             return;
+                        // 🔴 A PAGE REFUSES, ALWAYS — and the default context is a page.
+                        // The page host has nowhere to write the override (a page token is
+                        // bound to no model), so it answers every request with this exact
+                        // reply, whatever `versionId` was sent. Until this branch the mock
+                        // answered `ok: true` on a page, so a page app's `persist()` passed
+                        // here and failed in production. See ./hostSurface.ts.
+                        if (emulatesPageHost(options.context)) {
+                            dispatchToBlock({
+                                type: 'USER_CHECKPOINT_SET',
+                                payload: { requestId, ok: false, error: PAGE_CHECKPOINT_PERSIST_ERROR },
+                            });
+                            return;
+                        }
+                        // MODEL SLOT: persist the checkpoint override (mirrors the real
+                        // host's block_user_settings write). Accept a numeric versionId OR
+                        // an explicit null (clear); anything else is a bad-input NACK, same
+                        // as the real IframeHost.
                         const rawVersionId = typed.payload?.versionId;
                         const versionId = rawVersionId === null
                             ? null
@@ -2965,6 +3492,11 @@ export function createMockHost(options = {}) {
                         return;
                     }
                     default:
+                        // No reply, as in production. What reaches here is a type with no
+                        // reply channel (BLOCK_READY, NAVIGATE, TRACK_EVENT, …) or a type
+                        // this protocol does not declare. The real host's `unsupported on
+                        // this host` reply is built only for a request type it KNOWS and
+                        // has no handler for; a type it does not know gets nothing.
                         return;
                 }
             },
@@ -3121,6 +3653,11 @@ export function createMockHost(options = {}) {
             uploadImageBytesError = patch.uploadImageBytesError;
         if ('runTrainingCapRefusal' in patch)
             runTrainingCapRefusal = patch.runTrainingCapRefusal;
+        if ('runConfirmedStepError' in patch)
+            runConfirmedStepError = patch.runConfirmedStepError;
+        if ('runConfirmedStepCapRefusal' in patch) {
+            runConfirmedStepCapRefusal = patch.runConfirmedStepCapRefusal;
+        }
         if (patch.appWorkflows !== undefined) {
             appWorkflows = {
                 workflows: patch.appWorkflows.workflows,