@civitai/blocks-react 0.64.0 → 0.65.1

package/dist/internal/liveHost.d.ts

@@ -47,7 +47,7 @@
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
  * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 45, of which 8 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 47, of which 10 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -101,6 +101,12 @@
  *     host-chrome consent. Replies `collection-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
+ *   • PREPARE_TRAINING_DATASET — the server refuses every `kind: 'training'`
+ *     request from a dev token, so there is nothing to forward. Replies with a
+ *     refusal.
+ *   • RUN_TRAINING — the same dev-token refusal, plus the host-chrome consent
+ *     dialog a run is confirmed in, which this harness does not have. Replies
+ *     with a refusal.
  *   • PUBLISH_GENERATION_OUTPUTS — publishing requires the viewer's signed-in
  *     civitai.com session, which the local harness does not have; test
  *     publishing against the mock host — `createMockHost` or `Harness` from
@@ -181,6 +187,11 @@ export interface LiveHostOptions {
      */
     onPickerReady?: (handle: PickerOverlayHandle) => void;
 }
+/**
+ * The reply both training bridges get in dev:live — see their handlers. One
+ * string so the two cannot drift.
+ */
+export declare const TRAINING_UNSUPPORTED_ERROR = "training is not supported in dev:live \u2014 use dev:mock";
 /**
  * Decoded payload of a block-token JWT (the claims `BlockTokenService.sign`
  * stamps — see civitai `block-token.service.ts`). Everything is optional/unknown

package/dist/internal/liveHost.js

@@ -47,7 +47,7 @@
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
  * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 45, of which 8 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 47, of which 10 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -101,6 +101,12 @@
  *     host-chrome consent. Replies `collection-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
+ *   • PREPARE_TRAINING_DATASET — the server refuses every `kind: 'training'`
+ *     request from a dev token, so there is nothing to forward. Replies with a
+ *     refusal.
+ *   • RUN_TRAINING — the same dev-token refusal, plus the host-chrome consent
+ *     dialog a run is confirmed in, which this harness does not have. Replies
+ *     with a refusal.
  *   • PUBLISH_GENERATION_OUTPUTS — publishing requires the viewer's signed-in
  *     civitai.com session, which the local harness does not have; test
  *     publishing against the mock host — `createMockHost` or `Harness` from
@@ -130,6 +136,15 @@ const DEFAULT_BACKEND_BASE_URL = 'https://civitai.com';
 const PAGE_SLOT_ID = 'app.page';
 /** The budgeted-spend scope the workflow procedures require. */
 const BUDGETED_SCOPE = 'ai:write:budgeted';
+/**
+ * The reply both training bridges get in dev:live — see their handlers. One
+ * string so the two cannot drift.
+ */
+export const TRAINING_UNSUPPORTED_ERROR = 'training is not supported in dev:live — use dev:mock';
+/** The once-per-session console line for a refused training bridge. */
+const trainingUnsupportedLog = (type) => `${type} is not supported in dev:live (the server refuses every training request from a ` +
+    'dev token, and a run needs the host-chrome consent dialog). Replying with a refusal. ' +
+    'Use dev:mock to exercise the training flow.';
 /**
  * Decode the middle (payload) segment of a JWT (base64url) WITHOUT verifying
  * the signature — client-side we only need the claims to build BLOCK_INIT; the
@@ -967,6 +982,44 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'PREPARE_TRAINING_DATASET': {
+                        // UNSUPPORTED in live, and here the SERVER decides it, not this
+                        // harness: every `kind: 'training'` procedure refuses a dev token
+                        // ("training is not available from a development or review session"
+                        // — `assertTrainingRequestAllowed` in civitai/civitai), because there
+                        // is no host page whose chrome can show the viewer a price. A
+                        // training ESTIMATE is still forwarded (ESTIMATE_WORKFLOW above) and
+                        // comes back carrying that same server refusal.
+                        //
+                        // FREE TEXT on the message's own reply channel; no host code is
+                        // honest about "this harness cannot do it". Use dev:mock — its
+                        // `trainingDatasetError` / `trainingDatasetRejected` knobs cover the
+                        // refusal set.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('training-dataset', trainingUnsupportedLog('PREPARE_TRAINING_DATASET'));
+                        dispatchToBlock({
+                            type: 'TRAINING_DATASET_RESULT',
+                            payload: { requestId, error: TRAINING_UNSUPPORTED_ERROR },
+                        });
+                        return;
+                    }
+                    case 'RUN_TRAINING': {
+                        // UNSUPPORTED in live for the same server-side reason as
+                        // PREPARE_TRAINING_DATASET directly above — and doubly so: a run is
+                        // CHARGED and confirmed in host chrome this harness does not have, so
+                        // faking either half would let dev prove out a flow production does
+                        // not have. Use dev:mock — its `runTrainingError` knob covers
+                        // `declined`, `submission-unconfirmed` and the rest.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('training-run', trainingUnsupportedLog('RUN_TRAINING'));
+                        dispatchToBlock({
+                            type: 'TRAINING_RESULT',
+                            payload: { requestId, error: TRAINING_UNSUPPORTED_ERROR },
+                        });
+                        return;
+                    }
                     case 'GET_WILDCARD_PACK': {
                         // UNSUPPORTED in live v1 (honest-by-design, like OPEN_BUZZ_PURCHASE):
                         // the real host resolves the pack via a SESSION-authed proc and does

package/dist/internal/mockHost.d.ts

@@ -37,7 +37,7 @@
  * called). Only the postMessage bridge round-trips are exercised. Never import
  * this from production code.
  */
-import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockPublishedModel, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
+import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockPublishedModel, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockPrepareTrainingDatasetHostError, type BlockRunTrainingHostError, type BlockTrainingRejectionReason, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
  * = every submit RESOLVES an insufficient-Buzz `failed` snapshot, priced
@@ -179,10 +179,13 @@ export interface MockGenerationScenario {
      */
     images?: string[] | ((req: WorkflowBody) => string[]);
     /**
-     * How many trained epochs a succeeded PASS-THROUGH training step reports on
+     * How many trained epochs a succeeded training run reports on
      * {@link BlockWorkflowSnapshot.trainedEpochs} — epochs `1…n`, each tagged with
-     * the submitted `$type`. Applies only to a `{ kind: 'step', $type: 'training' }`
-     * or `'imageResourceTraining'` body; every other body is unaffected.
+     * the run's `$type`. Applies only to a PASS-THROUGH `{ kind: 'step', $type:
+     * 'training' }` / `'imageResourceTraining'` body (tagged with that `$type`) and
+     * to a `kind: 'training'` run started through `RUN_TRAINING` (tagged
+     * `'training'`, the step the host builds for it); every other body is
+     * unaffected.
      *
      * Default `0`: the field is omitted, as the host omits it for a run that
      * produced no checkpoint. Opt in with `n > 0` to simulate a finished run —
@@ -200,6 +203,11 @@ export interface MockGenerationScenario {
      * NOT simulated: the mock neither quotes nor times out, so a success here
      * says nothing about whether your run is quoted, what it costs, or whether
      * it finishes.
+     *
+     * Snapshot-only: the app-queue read (`QUERY_APP_WORKFLOWS`) replies with the
+     * canned {@link MockHostOptions.appWorkflows} rows verbatim — they carry no
+     * body, so the mock cannot tell a training row from any other. To exercise
+     * {@link AppWorkflow.trainedEpochs}, put it on the rows you pass there.
      */
     trainedEpochs?: number;
     /**
@@ -207,10 +215,38 @@ export interface MockGenerationScenario {
      * {@link BlockWorkflowSnapshot.publishedModel} — simulating a run the viewer
      * has started (`published: false`) or finished (`published: true`) publishing
      * through the model wizard. Default: unset (field omitted). For the app-queue
-     * read, put `publishedModel` on the rows you pass as `appWorkflows`.
+     * read, put `publishedModel` (and `trainedEpochs`) on the rows you pass as
+     * `appWorkflows`.
      */
     trainingPublishedModel?: BlockPublishedModel;
 }
+/**
+ * The training bounds the mock enforces — COPIES of `@civitai/app-sdk/blocks`'s
+ * `BLOCK_TRAINING_DATASET_MAX_ITEMS`, `BLOCK_TRAINING_CAPTION_MAX_CHARS` and
+ * `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`, deliberately not value-imported: a value
+ * import of a symbol the newest PUBLISHED app-sdk lacks raises this package's
+ * peer floor (`tests/guards/blocks-react-peer-floor.test.mjs`). The copy is held
+ * to the SDK's value by `test/trainingKindFlow.test.tsx`, which imports both.
+ */
+export declare const MOCK_TRAINING_BOUNDS: {
+    readonly datasetMaxItems: 50;
+    readonly captionMaxChars: 1000;
+    readonly maxBuzzPerRun: 5000;
+};
+/** The real server's refusal for a training request from a token without the spend scope. */
+export declare const MOCK_TRAINING_SCOPE_ERROR = "block lacks ai:write:budgeted scope";
+/** The real server's refusal for an unknown, expired or spent quote on `RUN_TRAINING`. */
+export declare const MOCK_TRAINING_QUOTE_GONE_ERROR = "training quote not found, expired or already used \u2014 estimate again";
+/** The real server's refusal for a training estimate naming a dataset it does not hold. */
+export declare const MOCK_TRAINING_DATASET_GONE_ERROR = "training dataset not found or expired";
+/**
+ * The real server's two refusals for a dataset with NOTHING admitted
+ * (`prepareBlockTrainingDataset`): every image failed eligibility, or every
+ * eligible image failed its import. The server THROWS rather than returning
+ * `count: 0`, so a successful reply always admits at least one image.
+ */
+export declare const MOCK_TRAINING_NONE_ELIGIBLE_ERROR = "none of the requested images can be used for training";
+export declare const MOCK_TRAINING_NONE_IMPORTED_ERROR = "none of the requested images could be prepared for training";
 /**
  * BUZZ scenario controls — simulate a balance so the insufficient-Buzz / top-up
  * UX is exercisable. The mock host treats `balance` as a spendable wallet:
@@ -619,6 +655,82 @@ export interface MockHostOptions {
      * exercised by `declined`, never by the timing or the content.
      */
     createPostError?: BlockCreatePostHostError | string;
+    /**
+     * Images `PREPARE_TRAINING_DATASET` leaves out, with their reasons — what
+     * `usePrepareTrainingDataset()` reports on `rejected`. Only entries whose
+     * `imageId` the request actually named are reported, and `count` is the rest,
+     * exactly as the server derives it. Absent → every image is admitted.
+     * Live-tunable via {@link MockHost.setScenario}.
+     *
+     * When this rejects EVERY named image the reply is an `error`, as on the real
+     * server — {@link MOCK_TRAINING_NONE_ELIGIBLE_ERROR}, or
+     * {@link MOCK_TRAINING_NONE_IMPORTED_ERROR} when every image that passed
+     * eligibility was rejected with an `import-*` reason. A success never has
+     * `count: 0`.
+     *
+     * KIND-FAITHFUL, like the rest of the training path: the mock holds the
+     * datasets it prepared, an estimate naming any other `datasetId` fails as the
+     * server's does, a quote is run at most once, and every training call needs
+     * `ai:write:budgeted` on the token ({@link MockHostOptions.consentGranted}) and
+     * a signed-in viewer. What it cannot model: image ownership and moderation (it
+     * has no images), the flag, and the page-only / dev-token refusals.
+     *
+     * ⚠️ The quote↔body check is NARROWER than the server's: the mock compares only
+     * `datasetId`, while the server hashes the whole body (minus `quoteId`) and
+     * refuses any change. A body edited between estimate and run passes here and
+     * fails in production.
+     */
+    trainingDatasetRejected?: Array<{
+        imageId: number;
+        reason: BlockTrainingRejectionReason;
+    }>;
+    /**
+     * Force `PREPARE_TRAINING_DATASET` to reply with an `error` — a
+     * {@link BlockPrepareTrainingDatasetHostError} for a host refusal, or any other
+     * string for the free-text server-message variant. Absent → it prepares.
+     * Live-tunable via {@link MockHost.setScenario}.
+     */
+    trainingDatasetError?: BlockPrepareTrainingDatasetHostError | string;
+    /**
+     * The Buzz total a `kind: 'training'` estimate quotes. Default `500`. Above
+     * `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000) the estimate fails exactly as the
+     * server's does. The run's terminal snapshot reports this as its `cost`.
+     * Live-tunable via {@link MockHost.setScenario}.
+     */
+    trainingQuoteTotal?: number;
+    /**
+     * Force `RUN_TRAINING` to reply with an `error` instead of starting a run — a
+     * {@link BlockRunTrainingHostError} (`'declined'`: the viewer dismissed the
+     * dialog, no run; `'submission-unconfirmed'`: the run MAY exist) or any other
+     * string for a server message. Absent → the run starts.
+     *
+     * Whether the QUOTE survives follows the real flow: the host's own gate and
+     * dialog codes (`declined`, `review-mode`, `block is not ready`, `sign in to
+     * train`, `invalid training request`, `no block token`) settle before the
+     * server claims the quote, so it stays runnable; `submission-unconfirmed` and
+     * any server message settle after the claim, so it is used up — re-running it
+     * gets the quote-gone error. Live-tunable via {@link MockHost.setScenario};
+     * `undefined` clears it.
+     *
+     * 🔴 Same real gap as {@link createPostError}: the consent dialog is HOST
+     * chrome, so the mock settles immediately where the real host waits on a click.
+     */
+    runTrainingError?: BlockRunTrainingHostError | string;
+    /**
+     * Make `RUN_TRAINING` resolve the server's spend-cap or temporary-availability
+     * refusal instead of a run:
+     * a snapshot `{ workflowId: 'failed', status: 'failed', cost: { total: <quote> },
+     * error: <this string> }` — the shape the real training submit returns when
+     * the viewer's daily / private-run Buzz cap, the per-app consent budget, the
+     * app's spend or rate limit (or its "temporarily unavailable" deny), or a
+     * dev-session cap stops the run (refunded, no run). `useRunTraining()` rejects
+     * it with `.refused`. Pass the server's text, e.g. `'daily Buzz cap reached: …'`.
+     * 🔴 The quote is CONSUMED, as on the server (it is claimed before the cap
+     * checks): running the same `quoteId` again gets the quote-gone error — estimate
+     * again. Absent → the run starts. Live-tunable via {@link MockHost.setScenario};
+     * `setScenario({ runTrainingCapRefusal: undefined })` clears it.
+     */
+    runTrainingCapRefusal?: string;
     /**
      * Buzz pools a `SUBMIT_WORKFLOW` must REJECT when named in `body.accountType`
      * — simulates the real backend's content-rating clamp. The real host throws a
@@ -783,7 +895,7 @@ export interface MockHostOptions {
  * {@link MockHost.setTheme}, which pushes a real `THEME_CHANGE` — the mock of
  * the viewer toggling dark mode with the block already mounted.)
  */
-export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes'>;
+export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes'>;
 /** Runtime Buzz-balance handle exposed on {@link MockHost.buzz}. */
 export interface MockBuzzHandle {
     /** Current simulated balance, or `undefined` when balance isn't simulated. */

package/dist/internal/mockHost.js

@@ -41,6 +41,7 @@ import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED
 import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
 import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, storageScopeDeniedPayload, } from './mockHostScopes.js';
 import { governsIdempotencyKey, idempotencyKeyDeniedMessage, idempotencyKeyRefusal, } from './mockHostIdempotency.js';
+import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
 /**
@@ -79,6 +80,10 @@ const preferredAccountType = (body) => {
             return body.mode === 'inline' ? undefined : body.params.accountType;
         case 'step':
             return undefined;
+        // A training body names no pool either: the host's `blockTrainingBodySchema`
+        // is `.strict()` with no `accountType`.
+        case 'training':
+            return undefined;
         default: {
             // Exhaustiveness check: a new `WorkflowBody` member makes this assignment
             // fail to compile, right here, rather than defaulting somewhere.
@@ -121,6 +126,77 @@ const passThroughTrainingType = (body) => {
     const t = body.$type;
     return t === 'training' || t === 'imageResourceTraining' ? t : undefined;
 };
+/**
+ * The orchestrator `$type` a body's run trains with, if it trains at all: the
+ * pass-through training `$type`s above, and `'training'` for a
+ * `kind: 'training'` body — the host builds an ai-toolkit `training` step for it.
+ */
+const trainingStepType = (body) => body.kind === 'training' ? 'training' : passThroughTrainingType(body);
+/**
+ * The training bounds the mock enforces — COPIES of `@civitai/app-sdk/blocks`'s
+ * `BLOCK_TRAINING_DATASET_MAX_ITEMS`, `BLOCK_TRAINING_CAPTION_MAX_CHARS` and
+ * `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`, deliberately not value-imported: a value
+ * import of a symbol the newest PUBLISHED app-sdk lacks raises this package's
+ * peer floor (`tests/guards/blocks-react-peer-floor.test.mjs`). The copy is held
+ * to the SDK's value by `test/trainingKindFlow.test.tsx`, which imports both.
+ */
+export const MOCK_TRAINING_BOUNDS = {
+    datasetMaxItems: 50,
+    captionMaxChars: 1000,
+    maxBuzzPerRun: 5000,
+};
+/**
+ * The host's `PREPARE_TRAINING_DATASET` item check, mirrored: the server's
+ * `blockTrainingDatasetItemsSchema` — 1…50 items, each EXACTLY `{ imageId:
+ * positive integer, caption: string ≤ 1000 }`. The real host runs this BEFORE any
+ * server call and refuses with `invalid training dataset`, so the mock does too.
+ */
+function isValidTrainingDatasetItems(items) {
+    if (!Array.isArray(items))
+        return false;
+    if (items.length < 1 || items.length > MOCK_TRAINING_BOUNDS.datasetMaxItems)
+        return false;
+    return items.every((it) => {
+        if (typeof it !== 'object' || it === null || Array.isArray(it))
+            return false;
+        const keys = Object.keys(it);
+        if (keys.length !== 2 || !keys.includes('imageId') || !keys.includes('caption'))
+            return false;
+        const { imageId, caption } = it;
+        return (typeof imageId === 'number' &&
+            Number.isInteger(imageId) &&
+            imageId > 0 &&
+            typeof caption === 'string' &&
+            caption.length <= MOCK_TRAINING_BOUNDS.captionMaxChars);
+    });
+}
+/** The real server's refusal for a training request from a token without the spend scope. */
+export const MOCK_TRAINING_SCOPE_ERROR = 'block lacks ai:write:budgeted scope';
+/** The real server's refusal for an unknown, expired or spent quote on `RUN_TRAINING`. */
+export const MOCK_TRAINING_QUOTE_GONE_ERROR = 'training quote not found, expired or already used — estimate again';
+/** The real server's refusal for a training estimate naming a dataset it does not hold. */
+export const MOCK_TRAINING_DATASET_GONE_ERROR = 'training dataset not found or expired';
+/**
+ * The real server's two refusals for a dataset with NOTHING admitted
+ * (`prepareBlockTrainingDataset`): every image failed eligibility, or every
+ * eligible image failed its import. The server THROWS rather than returning
+ * `count: 0`, so a successful reply always admits at least one image.
+ */
+export const MOCK_TRAINING_NONE_ELIGIBLE_ERROR = 'none of the requested images can be used for training';
+export const MOCK_TRAINING_NONE_IMPORTED_ERROR = 'none of the requested images could be prepared for training';
+/**
+ * The forced `RUN_TRAINING` errors that settle BEFORE the server claims (and so
+ * consumes) the quote: the host's own gate and dialog codes. Derived from the
+ * host-code list — every code except `submission-unconfirmed`, which the host
+ * emits only after a submit was sent. Any other forced error (a server message
+ * such as "Not enough Buzz for this training run.") stands for a refusal the
+ * server made AFTER its claim, so it consumes the quote.
+ */
+const PRE_CLAIM_RUN_TRAINING_ERRORS = new Set(RUN_TRAINING_ERROR_CODES.filter((c) => c !== 'submission-unconfirmed'));
+/** Default quote total for a `kind: 'training'` estimate when {@link MockHostOptions.trainingQuoteTotal} is unset. */
+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 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
@@ -731,6 +807,13 @@ export function createMockHost(options = {}) {
     // App Blocks → Post bridge: the canned post + a forced-refusal knob.
     let createPostResult = options.createPostResult ?? DEFAULT_CREATE_POST_RESULT;
     let createPostError = options.createPostError;
+    // App Blocks training bridges: canned dataset rejections, quote total, and
+    // forced-refusal knobs. The datasets/quotes themselves live per install.
+    let trainingDatasetRejected = options.trainingDatasetRejected ?? [];
+    let trainingDatasetError = options.trainingDatasetError;
+    let trainingQuoteTotal = options.trainingQuoteTotal ?? DEFAULT_TRAINING_QUOTE_TOTAL;
+    let runTrainingError = options.runTrainingError;
+    let runTrainingCapRefusal = options.runTrainingCapRefusal;
     // 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.
@@ -882,6 +965,16 @@ export function createMockHost(options = {}) {
         let submitCount = 0;
         // body + cost remembered per workflow so the succeeded snapshot can echo them.
         const workflows = new Map();
+        // Training: datasets this install prepared (id → admitted count) and the
+        // quotes its estimates stored (id → what a run is checked against).
+        const trainingDatasets = new Map();
+        const trainingQuotes = new Map();
+        let trainingSerial = 0;
+        /** `<prefix>` + 32 hex characters — the real handles' shape. */
+        const trainingHandle = (prefix) => {
+            trainingSerial += 1;
+            return `${prefix}${trainingSerial.toString(16).padStart(32, '0')}`;
+        };
         const timers = new Set();
         const dispatchToBlock = (data) => {
             win.dispatchEvent(new MessageEvent('message', { data, origin: parentOrigin }));
@@ -911,7 +1004,7 @@ export function createMockHost(options = {}) {
          * a checkpoint. Empty for every other body, so their snapshots are unchanged.
          */
         const trainingFields = (body) => {
-            const $type = passThroughTrainingType(body);
+            const $type = trainingStepType(body);
             if (!$type)
                 return {};
             const count = Math.max(0, Math.floor(gen.trainedEpochs ?? 0));
@@ -1159,6 +1252,53 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        // TRAINING ESTIMATE — KIND-FAITHFUL, the one exception to the
+                        // kind-agnostic rule above, because the real arm is not a priced
+                        // pass-through: it needs the spend scope, names a dataset the server
+                        // must hold, refuses a price above the per-run ceiling, and STORES a
+                        // quote the run is later checked against. Each refusal is the
+                        // server's message in the host's `failureSnapshot` shape.
+                        if (body.kind === 'training') {
+                            const refuse = (error) => dispatchToBlock({
+                                type: 'ESTIMATE_RESULT',
+                                payload: { requestId, snapshot: { workflowId: 'failed', status: 'failed', error } },
+                            });
+                            if (!consentGranted)
+                                return refuse(MOCK_TRAINING_SCOPE_ERROR);
+                            const imageCount = trainingDatasets.get(body.datasetId);
+                            if (imageCount === undefined)
+                                return refuse(MOCK_TRAINING_DATASET_GONE_ERROR);
+                            const total = trainingQuoteTotal;
+                            if (total > MOCK_TRAINING_BOUNDS.maxBuzzPerRun) {
+                                return refuse(`this training run costs ${total} Buzz, above the per-run limit of ${MOCK_TRAINING_BOUNDS.maxBuzzPerRun} for apps`);
+                            }
+                            const quoteId = trainingHandle('tq_');
+                            const expiresAtMs = Date.now() + TRAINING_QUOTE_TTL_MS;
+                            trainingQuotes.set(quoteId, {
+                                datasetId: body.datasetId,
+                                total,
+                                expiresAtMs,
+                                spent: false,
+                            });
+                            dispatchToBlock({
+                                type: 'ESTIMATE_RESULT',
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        workflowId: 'wf_estimate',
+                                        status: 'pending',
+                                        cost: { total },
+                                        trainingQuote: {
+                                            quoteId,
+                                            total,
+                                            imageCount,
+                                            expiresAt: new Date(expiresAtMs).toISOString(),
+                                        },
+                                    },
+                                },
+                            });
+                            return;
+                        }
                         dispatchToBlock({
                             type: 'ESTIMATE_RESULT',
                             payload: {
@@ -1182,6 +1322,26 @@ export function createMockHost(options = {}) {
                         // the largest-wallet stamp. No recipe-registry validation.
                         submitCount += 1;
                         const body = typed.payload?.body ?? {};
+                        // A `kind: 'training'` body is never started by SUBMIT_WORKFLOW: the
+                        // server charges a training run only against a quote a signed-in
+                        // session confirmed, which only RUN_TRAINING's dialog records. The
+                        // server's own refusal, in the host's `failureSnapshot` shape.
+                        // (`useBuzzWorkflow().submit()` refuses before sending; this covers a
+                        // raw transport send.)
+                        if (body.kind === 'training') {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_SUBMITTED',
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        workflowId: 'failed',
+                                        status: 'failed',
+                                        error: 'this training run has not been confirmed by the viewer in this session',
+                                    },
+                                },
+                            });
+                            return;
+                        }
                         const cost = costFor(body);
                         // CAUGHT-SERVER-EXCEPTION simulation (`generation.failSubmitException`).
                         // Reproduces the host's `failureSnapshot(err)` byte-for-byte: the
@@ -1633,6 +1793,108 @@ export function createMockHost(options = {}) {
                         });
                         return;
                     }
+                    case 'PREPARE_TRAINING_DATASET': {
+                        // The host's gate order (`prepareTrainingDatasetGate.ts`): no
+                        // requestId → drop; signed-out → `sign in to train`; items outside
+                        // the server's schema → `invalid training dataset`, before any call.
+                        // Then the server: the spend scope, then the dataset.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        const reply = (payload) => dispatchToBlock({ type: 'TRAINING_DATASET_RESULT', payload: { requestId, ...payload } });
+                        if (viewer === null)
+                            return reply({ error: 'sign in to train' });
+                        const items = typed.payload?.items;
+                        if (!isValidTrainingDatasetItems(items)) {
+                            return reply({ error: 'invalid training dataset' });
+                        }
+                        if (!consentGranted)
+                            return reply({ error: MOCK_TRAINING_SCOPE_ERROR });
+                        if (trainingDatasetError !== undefined)
+                            return reply({ error: trainingDatasetError });
+                        const named = new Set(items.map((it) => it.imageId));
+                        const rejected = trainingDatasetRejected
+                            .filter((r) => named.has(r.imageId))
+                            .map(({ imageId, reason }) => ({ imageId, reason }));
+                        const rejectedIds = new Set(rejected.map((r) => r.imageId));
+                        const count = [...named].filter((id) => !rejectedIds.has(id)).length;
+                        if (count === 0) {
+                            // The server THROWS here, eligibility before import: an `import-*`
+                            // rejection means that image PASSED eligibility, so the server
+                            // reached the import and refuses there.
+                            const anyImported = rejected.some((r) => r.reason.startsWith('import-'));
+                            return reply({
+                                error: anyImported
+                                    ? MOCK_TRAINING_NONE_IMPORTED_ERROR
+                                    : MOCK_TRAINING_NONE_ELIGIBLE_ERROR,
+                            });
+                        }
+                        const datasetId = trainingHandle('tds_');
+                        trainingDatasets.set(datasetId, count);
+                        const result = { datasetId, count, rejected };
+                        return reply({ result });
+                    }
+                    case 'RUN_TRAINING': {
+                        // The host's gate (`runTrainingGate.ts`): no requestId → drop;
+                        // signed-out → `sign in to train`; not a `kind:'training'` body with
+                        // a `quoteId` → `invalid training request`. Then the server: the
+                        // spend scope, then the quote (unknown, expired or already spent).
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        const reply = (payload) => dispatchToBlock({ type: 'TRAINING_RESULT', payload: { requestId, ...payload } });
+                        if (viewer === null)
+                            return reply({ error: 'sign in to train' });
+                        const raw = typed.payload?.body;
+                        const b = raw && typeof raw === 'object' && !Array.isArray(raw)
+                            ? raw
+                            : null;
+                        if (!b || b.kind !== 'training' || typeof b.quoteId !== 'string' || !b.quoteId) {
+                            return reply({ error: 'invalid training request' });
+                        }
+                        if (!consentGranted)
+                            return reply({ error: MOCK_TRAINING_SCOPE_ERROR });
+                        const quote = trainingQuotes.get(b.quoteId);
+                        if (!quote || quote.spent || Date.now() >= quote.expiresAtMs) {
+                            return reply({ error: MOCK_TRAINING_QUOTE_GONE_ERROR });
+                        }
+                        // Which outcomes consume the quote, modelled on the real flow: the
+                        // host's gate and consent dialog come first (quote kept); the
+                        // server's submit then claims the quote with a GETDEL
+                        // (`claimTrainingQuote`) BEFORE any of its own checks, so every
+                        // server outcome — a refusal, a body mismatch, a cap refusal,
+                        // `submission-unconfirmed`, a run — consumes it. The mock's check
+                        // ORDER below is its own; only the spent/kept split is the server's.
+                        if (runTrainingError !== undefined) {
+                            if (!PRE_CLAIM_RUN_TRAINING_ERRORS.has(runTrainingError))
+                                quote.spent = true;
+                            return reply({ error: runTrainingError });
+                        }
+                        quote.spent = true;
+                        if (b.datasetId !== quote.datasetId) {
+                            return reply({
+                                error: 'the training body differs from the one that was quoted — estimate again',
+                            });
+                        }
+                        // The server's cap / availability refusals RESOLVE (refunded, no run
+                        // started) — after the quote was consumed above.
+                        if (runTrainingCapRefusal !== undefined) {
+                            return reply({
+                                snapshot: {
+                                    workflowId: 'failed',
+                                    status: 'failed',
+                                    cost: { total: quote.total },
+                                    error: runTrainingCapRefusal,
+                                },
+                            });
+                        }
+                        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
@@ -2347,6 +2609,19 @@ export function createMockHost(options = {}) {
             createPostResult = patch.createPostResult;
         if (patch.createPostError !== undefined)
             createPostError = patch.createPostError;
+        if (patch.trainingDatasetRejected !== undefined) {
+            trainingDatasetRejected = patch.trainingDatasetRejected;
+        }
+        // The training error knobs clear on an explicit `undefined` (key PRESENT in
+        // the patch), so a harness can turn a refusal off without re-installing.
+        if ('trainingDatasetError' in patch)
+            trainingDatasetError = patch.trainingDatasetError;
+        if (patch.trainingQuoteTotal !== undefined)
+            trainingQuoteTotal = patch.trainingQuoteTotal;
+        if ('runTrainingError' in patch)
+            runTrainingError = patch.runTrainingError;
+        if ('runTrainingCapRefusal' in patch)
+            runTrainingCapRefusal = patch.runTrainingCapRefusal;
         if (patch.appWorkflows !== undefined) {
             appWorkflows = {
                 workflows: patch.appWorkflows.workflows,