@civitai/blocks-react 0.71.0 → 0.72.0

package/dist/internal/mockHost.js

@@ -39,12 +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, mockWorkflowBodyRefusal, mockWorkflowStepGenerations, mockWorkflowStepName, } from './mockWorkflowGraph.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';
@@ -219,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
@@ -643,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.
@@ -755,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)
@@ -907,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.
@@ -993,6 +1157,13 @@ 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) => {
@@ -1008,7 +1179,7 @@ export function createMockHost(options = {}) {
      */
     const workflowStepCosts = (body) => {
         // Unpriced: reserved at the ceiling, one per-generation budget per step.
-        if (gen.workflowUnpriced === true)
+        if (workflowQuoteFailure() !== null)
             return body.steps.map(() => buzzBudget);
         const spec = gen.costPerGen ?? legacyCost;
         return (Array.isArray(body.steps) ? body.steps : []).map((step, index) => {
@@ -1038,7 +1209,7 @@ export function createMockHost(options = {}) {
         if (!quotesFee)
             return null;
         // An unpriced workflow has no quoted base, so no fee is priced on it.
-        if (body.kind === 'workflow' && gen.workflowUnpriced === true)
+        if (body.kind === 'workflow' && workflowQuoteFailure() !== null)
             return 0;
         const spec = gen.authorFee ?? 0;
         return typeof spec === 'function' ? spec(body) : spec;
@@ -1134,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) => {
@@ -1267,12 +1442,20 @@ export function createMockHost(options = {}) {
                     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
@@ -1361,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
@@ -1442,13 +1629,65 @@ 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) ??
-                            (gen.workflowUnpriced === true ? mockUnpricedWorkflowRefusal(body) : null);
+                            (failure === null
+                                ? null
+                                : (mockUnpricedWorkflowRefusal(body, failure) ??
+                                    mockUnquotedWorkflowEstimateRefusal(failure)));
                         if (refusal !== null)
                             return { workflowId: 'failed', status: 'failed', ...refusal };
                     }
@@ -1569,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;
                     }
@@ -1642,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`.
@@ -1735,12 +1974,34 @@ 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) ??
-                                (gen.workflowUnpriced === true ? mockUnpricedWorkflowRefusal(body) : null);
+                                (failure === null ? null : mockUnpricedWorkflowRefusal(body, failure));
                             if (refusal !== null) {
                                 dispatchToBlock({
                                     type: 'WORKFLOW_SUBMITTED',
@@ -2433,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
@@ -3112,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
@@ -3139,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;
                 }
             },
@@ -3295,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,

package/dist/internal/mockWorkflowGraph.d.ts

@@ -50,8 +50,15 @@ export declare const MOCK_WORKFLOW_DENIED_STEP_TYPES: readonly string[];
 /** A refused body: the reply's `error` and, where one is defined, its `errorCode`. */
 export interface MockWorkflowRefusal {
     error: string;
-    errorCode?: 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded' | 'training-quote-unavailable';
+    errorCode?: 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded' | `training-quote-${MockWorkflowQuoteFailure}` | `workflow_quote_${MockWorkflowQuoteFailure}`;
 }
+/**
+ * Why the host has no price quote for a workflow (its `PassThroughQuoteFailure`
+ * kinds): `'rejected'` — the orchestrator refused the body, so the same body
+ * will fail again; `'unavailable'` — no usable answer, the one cause a retry of
+ * the same body can clear; `'unpriced'` — an answer without a price.
+ */
+export type MockWorkflowQuoteFailure = 'rejected' | 'unavailable' | 'unpriced';
 /** What a step is called in a reference and on the snapshot: its `name`, or `'$<index>'`. */
 export declare const mockWorkflowStepName: (step: {
     name?: unknown;
@@ -66,22 +73,28 @@ export declare const MOCK_MERGE_SHAPE_ERROR = "a merge step needs a \"fields\" o
  * {@link mockWorkflowBodyRefusal} accepted.
  */
 export declare function mockWorkflowStepGenerations(stepType: string, input: unknown, args: unknown): number;
-/** The host's refusal text for an unquoted training step (`UNQUOTED_TRAINING_ERROR`). */
-export declare const MOCK_UNQUOTED_TRAINING_ERROR = "Training needs a price quote and none could be obtained; try again.";
+/** The host's refusal text for an unquoted training step (`unquotedTrainingRefusal`). */
+export declare const mockUnquotedTrainingError: (failure: MockWorkflowQuoteFailure) => string;
 /**
- * The refusal for a body {@link mockWorkflowBodyRefusal} ACCEPTED when the host
- * could get NO price quote for it, or `null` when it would proceed (reserved at
- * the ceiling). In the host's order: a training step anywhere (its own
- * `training-quote-*` refusal — the mock reports `'training-quote-unavailable'`,
- * the code for "no usable answer"), then a `repeat` anywhere
- * (`workflow_repeat_unbounded`, naming the first such step).
+ * The refusal, on BOTH the estimate and the submit, for a body
+ * {@link mockWorkflowBodyRefusal} ACCEPTED when the host has no price quote for
+ * it, or `null` when the submit would proceed (reserved at the ceiling). In the
+ * host's order: a training step anywhere (`training-quote-<failure>`), then a
+ * `repeat` anywhere (`workflow_repeat_unbounded`, naming the first such step).
+ * The message states the cause.
  */
 export declare function mockUnpricedWorkflowRefusal(body: {
     steps: ReadonlyArray<{
         $type: string;
         input: unknown;
     }>;
-}): MockWorkflowRefusal | null;
+}, failure: MockWorkflowQuoteFailure): MockWorkflowRefusal | null;
+/**
+ * The host's `unquotedWorkflowEstimateRefusal`: what an ESTIMATE of a workflow
+ * with no price quote fails with when {@link mockUnpricedWorkflowRefusal} did
+ * not already refuse it. Estimate only — the submit of the same body proceeds.
+ */
+export declare function mockUnquotedWorkflowEstimateRefusal(failure: MockWorkflowQuoteFailure): MockWorkflowRefusal;
 /**
  * The refusal for a `kind: 'workflow'` body, or `null` for one the mock will
  * price and run. In the host's order: