@civitai/blocks-react 0.64.0 → 0.65.0

package/dist/hooks/useRunTraining.js

@@ -0,0 +1,212 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The host's CLOSED refusal codes for `RUN_TRAINING`, as a runtime list. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`.
+ *
+ * 🔴 THE ERROR CHANNEL IS NOT AN ENUM: server messages (an expired or used quote,
+ * a body that differs from the quoted one) arrive in the same field — see
+ * {@link isRunTrainingErrorCode}.
+ */
+export const RUN_TRAINING_ERROR_CODES = [
+    'review-mode',
+    'block is not ready',
+    'sign in to train',
+    'invalid training request',
+    'no block token',
+    'declined',
+    'submission-unconfirmed',
+];
+const CODE_SET = new Set(RUN_TRAINING_ERROR_CODES);
+/**
+ * The `workflowId` the host's training submit stamps on a snapshot that is NOT a
+ * run — its cap refusals resolve `{ workflowId: 'failed', status: 'failed', cost,
+ * error }` (`submitTrainingWorkflow` in civitai/civitai `blocks.router.ts`).
+ * Compared with `===`: a real orchestrator id is a workflow that may exist.
+ */
+const HOST_REFUSAL_WORKFLOW_ID = 'failed';
+/** `true` when `error` is one of the host's closed refusal codes rather than a server message. */
+export function isRunTrainingErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A training run that did not come back with a snapshot.
+ *
+ * 🔴 READ THE FLAGS BEFORE SAYING ANYTHING ABOUT MONEY — they are the only part of
+ * this error with a money meaning, and they point in opposite directions:
+ *
+ *  - `.declined` — the viewer dismissed the consent dialog. NO RUN WAS
+ *    SUBMITTED, guaranteed by the host's consent latch. Render nothing.
+ *  - `.unconfirmed` — the run MAY BE RUNNING AND CHARGED: the host sent the
+ *    submit and could not learn its outcome (`submission-unconfirmed`), or no
+ *    reply arrived at all (`.timedOut` — the viewer may have clicked Train on a
+ *    dialog this block had stopped waiting for). Do NOT retry automatically and
+ *    do NOT tell the viewer it failed: check their trainings first
+ *    (`useAppWorkflows()` lists this app's runs), because re-running the same
+ *    body after the server did start it is a SECOND, separately charged run.
+ *  - `.refused` (`code: 'refused'`) — the server REFUSED the submit at a spend
+ *    cap after the viewer confirmed (the viewer's daily or private-run Buzz cap,
+ *    the per-app consent budget, the app's daily spend or rate limit, a dev
+ *    session cap). Its reservation was refunded: NO RUN, nothing charged.
+ *    `.message` is the server's reason (e.g. `daily Buzz cap reached: …`) and
+ *    `.snapshot` the refusal it arrived in. Retrying needs a new estimate and
+ *    usually a later time; buying Buzz does not lift these caps.
+ *  - `.signInRequired` — no session. Route into `useRequestSignIn()`.
+ *  - anything else — a refusal before any submit (an expired or used quote, a
+ *    body that no longer matches its quote, an ineligible image). Estimate again
+ *    before retrying; `.message` is the host's or server's text.
+ */
+export class RunTrainingError extends Error {
+    /**
+     * The closed host refusal code, `'refused'` for a cap refusal, or `undefined`
+     * for a server/transport error.
+     */
+    code;
+    /**
+     * The server refused the submit (a spend cap, or a temporary-availability deny)
+     * and refunded it — no run exists. The quote is used up: estimate again.
+     * See the class docs; `.message` is the server's reason.
+     */
+    refused;
+    /** The refusal snapshot the host replied with, when {@link refused}. */
+    snapshot;
+    /** The viewer dismissed the consent dialog — no run was submitted. */
+    declined;
+    /**
+     * The run may exist and may have been charged — `submission-unconfirmed`, or a
+     * transport timeout. Check the viewer's trainings before retrying.
+     */
+    unconfirmed;
+    /** No reply arrived within the 10-minute consent bound. Implies {@link unconfirmed}. */
+    timedOut;
+    /** There is no session (`sign in to train`, or a bare `UNAUTHORIZED`). */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'RunTrainingError';
+        this.timedOut = opts?.timedOut === true;
+        this.refused = opts?.refusedSnapshot !== undefined;
+        if (opts?.refusedSnapshot !== undefined) {
+            this.code = 'refused';
+            this.snapshot = opts.refusedSnapshot;
+        }
+        else if (isRunTrainingErrorCode(error)) {
+            this.code = error;
+        }
+        this.declined = error === 'declined';
+        this.unconfirmed = this.timedOut || error === 'submission-unconfirmed';
+        this.signInRequired = error === 'sign in to train' || error === 'UNAUTHORIZED';
+    }
+}
+/**
+ * Run an App Blocks `kind: 'training'` LoRA training — the only way one starts —
+ * through the host-mediated `RUN_TRAINING` → `TRAINING_RESULT` bridge.
+ *
+ * 🔴 AVAILABILITY: page apps only, behind the host flag `app-blocks-training-kind`
+ * (ships off), with `ai:write:budgeted` declared and granted by a signed-in
+ * viewer. Refused from `dev:live` and from review sessions — build the flow
+ * against the mock host. See `WorkflowBodyTraining` in `@civitai/app-sdk`.
+ *
+ * The flow: `usePrepareTrainingDataset()` → `useBuzzWorkflow().estimate(body)`
+ * (its `trainingQuote.quoteId`) → `runTraining({ ...body, quoteId })` →
+ * `useBuzzWorkflow().watch(workflowId)`. Change nothing in the body between the
+ * estimate and the run: the server checks it against the quoted one.
+ *
+ * 🔴 THE CONSENT DIALOG IS CIVITAI'S, AND IT IS THE CHARGE. Every number on it is
+ * read back from the server's stored quote — never from your body. A run may cost
+ * more than the token's per-call budget (the viewer confirms the exact price), up
+ * to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000 Buzz). Images are the viewer's own.
+ *
+ * 🔴 NO AUTOMATIC CONSENT RETRY, unlike the other consent-gated hooks — on
+ * purpose. `RUN_TRAINING` carries no idempotency key and has an outcome
+ * (`submission-unconfirmed`) where a run may exist, so this hook never re-sends.
+ * It is also unreachable in practice: a block holding a `quoteId` got it from an
+ * estimate that already required `ai:write:budgeted`.
+ *
+ * Sent under the 10-minute human-interaction bound: the host replies only when
+ * the viewer clicks or dismisses its dialog.
+ *
+ * @example
+ * const { estimate, watch } = useBuzzWorkflow();
+ * const { runTraining } = useRunTraining();
+ * const quote = (await estimate(body)).trainingQuote!;
+ * try {
+ *   const started = await runTraining({ ...body, quoteId: quote.quoteId });
+ *   await watch(started.workflowId, { onUpdate: render });
+ * } catch (e) {
+ *   if (!(e instanceof RunTrainingError)) throw e;
+ *   if (e.declined) return;                          // no run — say nothing
+ *   if (e.signInRequired) return requestSignIn();
+ *   if (e.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
+ *   if (e.refused) return showError(e.message); // a cap / availability refusal; no run, nothing charged
+ *   showError('Could not start training. Get a new price and try again.');
+ * }
+ */
+export function useRunTraining() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // This request can outlive the component by up to ten minutes (the dialog may
+    // stay open), so a `pending` toggled on an unmounted control is state nobody
+    // can clear.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const runTraining = useCallback(async (body) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            const reply = await sendTypedRequest(getTransport(), { type: 'RUN_TRAINING', payload: { body } }, 'TRAINING_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS }).catch((err) => {
+                if (err instanceof RequestTimeoutError) {
+                    throw new RunTrainingError(err.message, { timedOut: true });
+                }
+                throw err instanceof Error ? err : new Error(String(err));
+            });
+            if (reply.error || !reply.snapshot) {
+                // `||`, not `??`: `error: ''` is a shape-valid reply. Its fallback is the
+                // CAUTIOUS code — with neither a snapshot nor a reason, nothing says a
+                // run was not started, so the block must not be told it was safe to
+                // retry.
+                throw new RunTrainingError(reply.error || 'submission-unconfirmed');
+            }
+            // 🔴 A RESOLVED SNAPSHOT IS NOT ALWAYS A RUN. The host's training submit
+            // answers its spend-cap and temporary-availability refusals (refunded,
+            // nothing started) with a
+            // resolved `{ workflowId: 'failed', status: 'failed', cost, error }`.
+            // Resolving that would hand the caller a workflow id to `watch()` that
+            // names nothing, and drop the reason. Exact match on the host's
+            // sentinel: a failed snapshot with a REAL id is a workflow that may
+            // exist, and keeps resolving so it can be watched.
+            if (reply.snapshot.workflowId === HOST_REFUSAL_WORKFLOW_ID &&
+                reply.snapshot.status === 'failed') {
+                throw new RunTrainingError(reply.snapshot.error || 'training run refused', {
+                    refusedSnapshot: reply.snapshot,
+                });
+            }
+            return reply.snapshot;
+        }
+        catch (err) {
+            const wrapped = err instanceof RunTrainingError
+                ? err
+                : new RunTrainingError(err instanceof Error ? err.message : String(err));
+            if (mountedRef.current)
+                setError(wrapped);
+            // Thrown even when unmounted: the caller's `await` must still learn the
+            // outcome of a possibly-charged run.
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, []);
+    return { runTraining, pending, error };
+}
+//# sourceMappingURL=useRunTraining.js.map

package/dist/index.d.ts

@@ -67,6 +67,10 @@ export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_COD
 export type { UseCollectionFollow } from './hooks/useCollectionFollow.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
 export type { UseCreatePostFromApp, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './hooks/useCreatePostFromApp.js';
+export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
+export type { UsePrepareTrainingDataset, BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, } from './hooks/usePrepareTrainingDataset.js';
+export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
+export type { UseRunTraining, QuotedTrainingBody, RunTrainingErrorCode, BlockRunTrainingHostError, BlockTrainingQuote, WorkflowBodyTraining, } from './hooks/useRunTraining.js';
 export type { BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, AppWorkflowsParams, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, } from '@civitai/app-sdk/blocks';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export type { UseCheckpointPicker } from './hooks/useCheckpointPicker.js';

package/dist/index.js

@@ -59,6 +59,8 @@ export { RequestTimeoutError } from './transport/transport.js';
 export { InvalidIdempotencyKeyError } from './transport/transport.js';
 export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_CODES, isCollectionFollowErrorCode, } from './hooks/useCollectionFollow.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
+export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
+export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';

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. */