@civitai/app-sdk 0.57.0 → 0.58.0

package/README.md

@@ -139,7 +139,7 @@ interface BlockInitPayload {
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
 | `fetchNestedDocument(opts)` | Embed one of your OWN bundled documents as an iframe `srcdoc`, because a nested `<iframe src>` of your own content **cannot load** — see [Nested documents](#nested-documents) below. `NestedDocumentError` carries a `.code` of `'invalid-url' \| 'http-error' \| 'network-error'`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |
-| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
+| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `WorkflowBodyTraining` (+ `AiToolkitTrainingParams`, `BlockTrainingQuote`, `BlockTrainingDatasetItem`, `BlockTrainingDatasetResult` and the `BLOCK_TRAINING_*` bounds), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
 
 `WorkflowBody`'s `customComfy` member is a discriminated union on `mode`, mirroring
 the host's `blockCustomComfyMemberSchema`. Narrow on the VALUE (`body.mode === 'inline'`),
@@ -189,10 +189,11 @@ own key:
   The trained checkpoint is not part of the block contract (an older
   host may still leak checkpoint urls into `imageUrls` / `stepOutputs` — a host defect, never
   something to build on); a host that supports it reports the trained epochs on
-  `snapshot.trainedEpochs` without the checkpoint, and the viewer publishes
+  `snapshot.trainedEpochs` (and on each `AppWorkflow` row of the app-queue read) without the
+  checkpoint, and the viewer publishes
   one by being navigated (`useCivitaiNavigate`, `scope: 'site'`) to Civitai's own model wizard at
   `models/train/from-orchestrator?workflowId=<id>&epoch=<n>`. `snapshot.publishedModel` (and
-  `AppWorkflow.publishedModel`) then reports the resulting model. Both fields are absent on hosts
+  `AppWorkflow.publishedModel`) then reports the resulting model. These fields are absent on hosts
   that predate them.
 
 ```ts
@@ -207,6 +208,18 @@ const body: WorkflowBody = {
 };
 ```
 
+`WorkflowBodyTraining` (`kind: 'training'`) is the **quoted** way to train: an ai-toolkit LoRA
+run on a dataset Civitai prepared from the viewer's own images, mirroring the host's
+`blockTrainingBodySchema` (civitai/civitai#5434). There is no `maxBuzz` and no timeout — the
+`estimate` reply carries `snapshot.trainingQuote` (`quoteId`, `total`, `imageCount`,
+`expiresAt`), and the run starts only through the `RUN_TRAINING` bridge, after the viewer
+confirms that price in Civitai's own dialog. A confirmed run may exceed the token's per-call
+budget, up to `BLOCK_TRAINING_MAX_BUZZ_PER_RUN` (5,000). Page apps only, `ai:write:budgeted`,
+behind the host flag `app-blocks-training-kind` (off by default), and refused from development
+and review sessions. The dataset is prepared over `PREPARE_TRAINING_DATASET`
+(civitai/civitai#5438). Use it through `@civitai/blocks-react`'s `usePrepareTrainingDataset()`
+and `useRunTraining()`.
+
 ### `defineBlock` validator rules
 
 **There is no rule list here, and that is the point.** `defineBlock` does not

package/dist/blocks/index.d.ts

@@ -109,5 +109,10 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockModelSubstitution, ModelSubstitutionReason, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, } from './types.js';
+/**
+ * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
+ * civitai/civitai's zod — see `WorkflowBodyTraining`.
+ */
+export { BLOCK_TRAINING_MAX_BUZZ_PER_RUN, BLOCK_TRAINING_DATASET_MAX_ITEMS, BLOCK_TRAINING_CAPTION_MAX_CHARS, BLOCK_TRAINING_SAMPLE_PROMPTS_MAX, BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS, BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS, BLOCK_TRAINING_MODEL_KEY_MAX_CHARS, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/index.js

@@ -108,4 +108,9 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
+/**
+ * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
+ * civitai/civitai's zod — see `WorkflowBodyTraining`.
+ */
+export { BLOCK_TRAINING_MAX_BUZZ_PER_RUN, BLOCK_TRAINING_DATASET_MAX_ITEMS, BLOCK_TRAINING_CAPTION_MAX_CHARS, BLOCK_TRAINING_SAMPLE_PROMPTS_MAX, BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS, BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS, BLOCK_TRAINING_MODEL_KEY_MAX_CHARS, } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/blocks/messages.d.ts

@@ -8,7 +8,7 @@
  * Wire format: `window.postMessage({ type, payload }, targetOrigin)`.
  */
 import type { ColorDomain } from './browsingLevel.js';
-import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining } from './types.js';
 /**
  * Filter params for `GET_BUZZ_TRANSACTIONS`. All optional; the host validates
  * them server-side (they are NEVER trusted for auth — the account is self-bound
@@ -464,6 +464,20 @@ export type ParentToBlockMessage = {
         result?: BlockCreatePostResult;
         error?: string;
     };
+} | {
+    type: 'TRAINING_DATASET_RESULT';
+    payload: {
+        requestId: string;
+        result?: BlockTrainingDatasetResult;
+        error?: string;
+    };
+} | {
+    type: 'TRAINING_RESULT';
+    payload: {
+        requestId: string;
+        snapshot?: BlockWorkflowSnapshot;
+        error?: string;
+    };
 } | {
     type: 'IMAGES_RESULT';
     payload: {
@@ -774,6 +788,18 @@ export type BlockToParentMessage = {
         /** Optional model-version gallery attach. Gated hard server-side. */
         modelVersionId?: number;
     };
+} | {
+    type: 'PREPARE_TRAINING_DATASET';
+    payload: {
+        requestId: string;
+        items: BlockTrainingDatasetItem[];
+    };
+} | {
+    type: 'RUN_TRAINING';
+    payload: {
+        requestId: string;
+        body: WorkflowBodyTraining;
+    };
 } | {
     type: 'GET_IMAGES_BY_IDS';
     payload: {
@@ -998,7 +1024,7 @@ export type BlockToParentMessageType = BlockToParentMessage['type'];
  * it is a measurement, not an invariant, and civitai's own compile-time gate
  * (published SDK union ⊆ `keyof INVENTORY`) is what holds one direction of it.
  */
-export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW"];
+export declare const BLOCK_TO_PARENT_MESSAGE_TYPES: readonly ["BLOCK_HELLO", "BLOCK_READY", "BLOCK_ERROR", "BLOCK_MESSAGE_REJECTED", "REQUEST_TOKEN", "RESIZE_IFRAME", "SUBMIT_WORKFLOW", "ESTIMATE_WORKFLOW", "POLL_WORKFLOW", "CANCEL_WORKFLOW", "OPEN_BUZZ_PURCHASE", "GET_BUZZ_BALANCE", "GET_VIEWER", "GET_BUZZ_TRANSACTIONS", "GET_BUZZ_ACCOUNTS", "GET_DAILY_COMPENSATION", "GET_WILDCARD_PACK", "QUERY_APP_WORKFLOWS", "PUBLISH_GENERATION_OUTPUTS", "CREATE_POST_FROM_APP", "PREPARE_TRAINING_DATASET", "RUN_TRAINING", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "SET_USER_CHECKPOINT", "NAVIGATE", "REQUEST_SIGN_IN", "REQUEST_CONSENT", "TRACK_EVENT", "APP_STORAGE_GET", "APP_STORAGE_SET", "APP_STORAGE_DELETE", "APP_STORAGE_LIST", "APP_STORAGE_QUOTA", "SHARED_LIST", "SHARED_GET_COUNT", "SHARED_GET_COUNTS", "SHARED_APPEND", "SHARED_VOTE", "SHARED_UNVOTE", "SHARED_WITHDRAW", "SHARED_UPDATE", "SHARED_GET", "SHARED_REPORT", "SAVE_IMAGE", "SET_COLLECTION_FOLLOW"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -69,6 +69,8 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'QUERY_APP_WORKFLOWS',
     'PUBLISH_GENERATION_OUTPUTS',
     'CREATE_POST_FROM_APP',
+    'PREPARE_TRAINING_DATASET',
+    'RUN_TRAINING',
     'GET_IMAGES_BY_IDS',
     'CANCEL_APP_WORKFLOW',
     'OPEN_CHECKPOINT_PICKER',

package/dist/blocks/types.d.ts

@@ -1249,6 +1249,166 @@ export type WorkflowBodyPassThroughStep = {
      */
     maxBuzz: number;
 };
+/** Ceiling on what ONE confirmed `kind: 'training'` run may cost, in Buzz. Host constant `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`. */
+export declare const BLOCK_TRAINING_MAX_BUZZ_PER_RUN = 5000;
+/** Max images in one prepared training dataset. Host constant `BLOCK_TRAINING_DATASET_MAX_ITEMS`. */
+export declare const BLOCK_TRAINING_DATASET_MAX_ITEMS = 50;
+/** Max characters of one dataset caption. Host constant `BLOCK_TRAINING_CAPTION_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_CAPTION_MAX_CHARS = 1000;
+/** Max sample prompts on a training body. Host constant `BLOCK_TRAINING_SAMPLE_PROMPTS_MAX`. */
+export declare const BLOCK_TRAINING_SAMPLE_PROMPTS_MAX = 6;
+/** Max characters of one sample prompt. Host constant `BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS = 1000;
+/** Max characters of the trigger word. Host constant `BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS = 64;
+/** Max characters of the base-model key. Host constant `BLOCK_TRAINING_MODEL_KEY_MAX_CHARS`. */
+export declare const BLOCK_TRAINING_MODEL_KEY_MAX_CHARS = 64;
+/** `lrScheduler` values the host's ai-toolkit schema accepts. */
+export type AiToolkitLrScheduler = 'constant' | 'constant_with_warmup' | 'cosine' | 'linear' | 'step';
+/** `optimizerType` values the host's ai-toolkit schema accepts. */
+export type AiToolkitOptimizerType = 'adamw' | 'adamw8bit' | 'adam8bit' | 'lion' | 'lion8bit' | 'adafactor' | 'adagrad' | 'prodigy' | 'prodigy8bit' | 'automagic';
+/** The fields every ai-toolkit ecosystem shares (`aiToolkitBaseParams` on the host). */
+export interface AiToolkitTrainingParamsBase {
+    engine: 'ai-toolkit';
+    /** Saved checkpoint count, integer 1…50. With `steps` absent it is also the length knob. */
+    epochs?: number;
+    /** Total training steps, integer ≥ 1 — the primary length (and price) knob. */
+    steps?: number;
+    /** Integer ≥ 1. Exactly `1` on the `qwen21` / `ming` / `yue2` ecosystems. */
+    batchSize?: number;
+    sampleCfgScale?: number;
+    sampleStrength?: number;
+    continueFrom?: string;
+    resolution: number | null;
+    /**
+     * Learning rate. 🔴 Must be BELOW `0.1` unless `optimizerType` is `prodigy` or
+     * `prodigy8bit` — a host refinement this type cannot express; a body that
+     * breaks it is refused at estimate.
+     */
+    lr: number;
+    textEncoderLr: number | null;
+    trainTextEncoder: boolean;
+    lrScheduler: AiToolkitLrScheduler;
+    optimizerType: AiToolkitOptimizerType;
+    networkDim: number | null;
+    networkAlpha: number | null;
+    noiseOffset: number | null;
+    minSnrGamma: number | null;
+    flipAugmentation: boolean;
+    shuffleTokens: boolean;
+    keepTokens: number;
+    numRepeats?: number;
+}
+/**
+ * The ai-toolkit ecosystems that take NO `modelVariant` — send the key absent.
+ * (`qwen21` / `ming` / `yue2` also take none; they live on their own arm of
+ * {@link AiToolkitTrainingParams} because they pin `batchSize` to `1`.)
+ */
+export type AiToolkitPlainEcosystem = 'sd1' | 'sdxl' | 'chroma' | 'qwen' | 'zimageturbo' | 'zimagebase' | 'ltx2' | 'ltx23' | 'ltx25' | 'minimaxh3' | 'ernie' | 'anima' | 'boogu' | 'krea2' | 'mageflow' | 'ideogram4' | 'ace_step_15';
+/**
+ * `params` of a {@link WorkflowBodyTraining} — the host's
+ * `aiToolkitTrainingParamsSchema`, the same schema Civitai's own training form
+ * validates against, discriminated on `ecosystem`.
+ *
+ * ⚠️ THE ECOSYSTEM LIST IS CLOSED HERE AND OPEN ON THE HOST. The host adds
+ * ecosystems over time; until this package mirrors one, a body naming it does not
+ * type-check. That is the cost of a typed copy, paid deliberately: a free
+ * `string` would let a typo through to a refused estimate.
+ */
+export type AiToolkitTrainingParams = AiToolkitTrainingParamsBase & ({
+    ecosystem: AiToolkitPlainEcosystem;
+    modelVariant?: undefined;
+} | {
+    ecosystem: 'sd3';
+    modelVariant: 'large' | 'medium';
+} | {
+    ecosystem: 'flux1';
+    modelVariant: 'dev' | 'schnell';
+} | {
+    ecosystem: 'wan';
+    modelVariant: '2.1' | '2.2';
+} | {
+    ecosystem: 'flux2klein';
+    modelVariant: '4b' | '9b';
+} | {
+    ecosystem: 'qwen21' | 'ming' | 'yue2';
+    modelVariant?: undefined;
+    batchSize?: 1;
+} | {
+    ecosystem: 'ace_step_15_xl';
+    modelVariant: 'base' | 'sft';
+});
+/**
+ * Train a LoRA with the ai-toolkit engine on a dataset Civitai prepared from the
+ * VIEWER'S OWN images — the App Blocks `kind: 'training'` workflow body.
+ *
+ * ## Availability — read before building on it
+ *
+ *  - 🔴 Behind the host flag **`app-blocks-training-kind`**, which ships OFF and is
+ *    evaluated per viewer. Where it is off, every training call is refused
+ *    (`training from apps is not enabled`).
+ *  - **Page apps only** (`/apps/run/<slug>`). The model slot answers both training
+ *    messages with an error, and the server refuses a non-page token.
+ *  - The manifest must declare **`ai:write:budgeted`** and the viewer must have
+ *    granted it; the viewer must be signed in.
+ *  - **Not from a development or review session**: dev tokens (`dev:live`, dev
+ *    tunnel) and review-sandbox tokens are refused, run-for-real included. Use the
+ *    mock host (`createMockHost` / `Harness`) to build the flow.
+ *
+ * ## The flow
+ *
+ *  1. **Dataset** — `usePrepareTrainingDataset()` (`PREPARE_TRAINING_DATASET`)
+ *     with `[{ imageId, caption }]`. Only the viewer's OWN scanned, unflagged
+ *     images within the page's maturity ceiling are admitted; the rest come back
+ *     in `rejected`. You get an opaque {@link WorkflowBodyTraining.datasetId}.
+ *  2. **Quote** — `useBuzzWorkflow().estimate(body)` with this body, `quoteId`
+ *     ABSENT. The reply's {@link BlockWorkflowSnapshot.trainingQuote} is the
+ *     orchestrator's own price for exactly this run, stored server-side.
+ *  3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })`
+ *     (`RUN_TRAINING`). Civitai shows the viewer a consent dialog in ITS chrome —
+ *     price, base model, length, dataset size, all read back from the server,
+ *     never from your body — and submits only on their click.
+ *  4. **Follow** — `useBuzzWorkflow().watch(snapshot.workflowId)`.
+ *
+ * 🔴 `useBuzzWorkflow().submit()` REFUSES THIS BODY before sending it. The server
+ * charges a training run only against a quote the viewer confirmed from a
+ * signed-in session, which only `RUN_TRAINING`'s dialog can record.
+ *
+ * ## Money
+ *
+ * There is no `maxBuzz` and no timeout knob, on purpose: the price is the quote.
+ * A run may cost more than the token's per-call `buzzBudget` (the viewer confirms
+ * the exact price), up to {@link BLOCK_TRAINING_MAX_BUZZ_PER_RUN} (5,000 Buzz);
+ * an estimate above that is refused.
+ */
+export interface WorkflowBodyTraining {
+    kind: 'training';
+    /** The handle `usePrepareTrainingDataset()` returned — `tds_` + 32 hex characters. */
+    datasetId: string;
+    /** The only engine accepted. */
+    engine: 'ai-toolkit';
+    /**
+     * A base-model key from Civitai's training catalog (1…64 characters), resolved
+     * and gated server-side. Custom AIRs are not accepted.
+     */
+    model: string;
+    params: AiToolkitTrainingParams;
+    /** At most {@link BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS} characters. Moderated like a prompt. */
+    triggerWord: string;
+    /**
+     * At most {@link BLOCK_TRAINING_SAMPLE_PROMPTS_MAX} prompts of at most
+     * {@link BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS} characters each. Moderated like
+     * prompts.
+     */
+    samplePrompts: string[];
+    /**
+     * The quote this run is charged against — {@link BlockTrainingQuote.quoteId}
+     * from the estimate (`tq_` + 32 hex characters). OMIT it on the estimate;
+     * REQUIRED on `RUN_TRAINING`. The server checks the rest of the body against
+     * the body that was quoted, so change nothing else between the two.
+     */
+    quoteId?: string;
+}
 /**
  * Body the block sends to `useBuzzWorkflow().{submit,estimate}`. A real
  * discriminated union keyed by `kind`:
@@ -1267,6 +1427,10 @@ export type WorkflowBodyPassThroughStep = {
  *    an orchestrator `$type` directly and has the host forward `input`
  *    unmodified. Bounded by a platform-internal denylist and by `maxBuzz`, not
  *    by a registry.
+ *  - {@link WorkflowBodyTraining} (`kind: 'training'`) — an ai-toolkit LoRA run
+ *    on a server-prepared dataset of the viewer's own images. ESTIMATE ONLY
+ *    through `useBuzzWorkflow`; it runs through `useRunTraining()`, whose
+ *    host-chrome consent dialog is the only way to confirm its quote.
  *
  * `kind: 'step'` is therefore itself a union, discriminated on the PRESENCE of
  * `step` — the same nesting {@link WorkflowBodyCustomComfy} has on `mode`.
@@ -1283,7 +1447,7 @@ export type WorkflowBodyPassThroughStep = {
  * over `kind`. Host code that must handle every member gets a compile error
  * pointing at the new one, which is the intended behaviour.
  */
-export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep;
+export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep | WorkflowBodyTraining;
 /**
  * The host-mediated view of an orchestrator workflow that an iframe block
  * receives over `postMessage`.
@@ -1493,6 +1657,33 @@ export interface BlockWorkflowSnapshot {
      * on any run nobody has started publishing.
      */
     publishedModel?: BlockPublishedModel;
+    /**
+     * The quote a {@link WorkflowBodyTraining} ESTIMATE produced — the orchestrator's
+     * own price for exactly that run, stored server-side. Pass
+     * `trainingQuote.quoteId` back as the body's `quoteId` on
+     * `useRunTraining().runTraining()`; the consent dialog then shows the viewer
+     * this price, read back from the server.
+     *
+     * `cost.total` on the same snapshot equals `trainingQuote.total`.
+     * `expiresAt` is an ISO-8601 timestamp: after it the run is refused and you
+     * estimate again. `imageCount` is the server-derived size of the prepared
+     * dataset, never a number the block sent.
+     *
+     * Present ONLY on the reply to a `kind: 'training'` estimate. Absent on hosts
+     * that predate civitai/civitai#5434.
+     */
+    trainingQuote?: BlockTrainingQuote;
+}
+/** {@link BlockWorkflowSnapshot.trainingQuote}. */
+export interface BlockTrainingQuote {
+    /** `tq_` + 32 hex characters. Opaque — pass it back verbatim. */
+    quoteId: string;
+    /** The quoted price, in Buzz. */
+    total: number;
+    /** How many images the prepared dataset holds. */
+    imageCount: number;
+    /** ISO-8601. The quote cannot be run after this. */
+    expiresAt: string;
 }
 /**
  * Why the host substituted a checkpoint version — see
@@ -1534,7 +1725,7 @@ export interface BlockStepToolCall {
         arguments: string;
     };
 }
-/** One entry of {@link BlockWorkflowSnapshot.trainedEpochs}. */
+/** One entry of {@link BlockWorkflowSnapshot.trainedEpochs} / {@link AppWorkflow.trainedEpochs}. */
 export interface BlockTrainedEpoch {
     /**
      * Which pass-through training `$type` produced this epoch. The SDK's inbound
@@ -2081,6 +2272,18 @@ export interface AppWorkflow {
      * every workflow nobody has published.
      */
     publishedModel?: BlockPublishedModel;
+    /**
+     * The epochs of a pass-through `training` / `imageResourceTraining` step in
+     * this workflow that produced a checkpoint. Same shape and rule as
+     * {@link BlockWorkflowSnapshot.trainedEpochs}: only runs whose training
+     * moderation status is approved are listed, the checkpoint itself is not
+     * exposed, and the field is OMITTED when there are no epochs to list. Lets a
+     * block offer "publish epoch n" from its queue without polling each run.
+     *
+     * 🔴 REQUIRES A HOST VERSION THAT EMITS IT. Absent on older hosts — treat
+     * absence as "unknown", not as "no checkpoint".
+     */
+    trainedEpochs?: BlockTrainedEpoch[];
 }
 /**
  * Per-viewer gated projection of ONE image returned by `GET_IMAGES_BY_IDS`
@@ -2297,5 +2500,102 @@ export interface BlockCreatePostResult {
  *   write, so a dismissal mid-write can never claim this code.
  */
 export type BlockCreatePostHostError = 'review-mode' | 'block is not ready' | 'sign in to post' | 'no images to post' | 'no block token' | 'declined';
+/**
+ * One image of a training dataset request — an `Image` id the VIEWER owns, and
+ * the caption to train it with.
+ *
+ * Host bounds (`blockTrainingDatasetItemsSchema`): `imageId` a positive integer,
+ * `caption` at most {@link BLOCK_TRAINING_CAPTION_MAX_CHARS} characters, no other
+ * keys; 1…{@link BLOCK_TRAINING_DATASET_MAX_ITEMS} items per request. A payload
+ * outside them is refused by the host with `invalid training dataset` before any
+ * server call. Captions are moderated like prompts.
+ */
+export interface BlockTrainingDatasetItem {
+    imageId: number;
+    caption: string;
+}
+/**
+ * Why the server left an image out of a prepared dataset. Mirrors
+ * civitai/civitai's `BlockTrainingRejectionReason`.
+ *
+ * - `unavailable` — not found, OR not the viewer's own image. One reason for
+ *   both, on purpose: the server will not tell an app whether someone else's
+ *   image id exists.
+ * - `unsupported-media` — a video or audio row.
+ * - `not-eligible` — refused by moderation state or the page's maturity ceiling.
+ * - `pending-scan` — not scanned yet; retry once the scan finishes.
+ * - `import-failed` — the orchestrator did not accept the image.
+ * - `import-unavailable` — the import timed out or the orchestrator was
+ *   unavailable; retryable.
+ *
+ * The SDK's inbound validator checks `reason` only as a STRING, so a reason the
+ * host adds later still arrives — give an exhaustive `switch` a default branch.
+ */
+export type BlockTrainingRejectionReason = 'unavailable' | 'unsupported-media' | 'not-eligible' | 'pending-scan' | 'import-failed' | 'import-unavailable';
+/**
+ * The success payload of `TRAINING_DATASET_RESULT` — what
+ * `usePrepareTrainingDataset().prepareDataset()` resolves with.
+ */
+export interface BlockTrainingDatasetResult {
+    /**
+     * Opaque handle for {@link WorkflowBodyTraining.datasetId} (`tds_` + 32 hex
+     * characters), bound to this viewer, app and install.
+     */
+    datasetId: string;
+    /**
+     * How many images were ADMITTED — always at least 1: when nothing is admitted
+     * the server refuses the request instead of returning an empty dataset. The
+     * server derives it; a run trains on exactly these.
+     */
+    count: number;
+    /** The images left out, each with its reason. Empty when every image was admitted. */
+    rejected: Array<{
+        imageId: number;
+        reason: BlockTrainingRejectionReason;
+    }>;
+}
+/**
+ * The HOST'S OWN refusal codes on a `TRAINING_DATASET_RESULT`'s `error`. Mirrors
+ * civitai/civitai's `PREPARE_TRAINING_DATASET_HOST_ERRORS`
+ * (`src/components/AppBlocks/prepareTrainingDatasetGate.ts`, civitai/civitai#5438).
+ *
+ * 🔴 THE SET A BLOCK MAY RELY ON, NOT THE SET IT MAY RECEIVE: `error` also carries
+ * any server message verbatim (`training from apps is not enabled`, a rate limit,
+ * a moderation refusal of a caption). Compare by EQUALITY against these members
+ * and treat anything else as an opaque server message.
+ *
+ * - `review-mode` — a mod-review sandbox with "run for real" off.
+ * - `block is not ready` — the host handshake has not completed.
+ * - `sign in to train` — anonymous viewer; there are no images of theirs to read.
+ * - `invalid training dataset` — `items` failed the host's item schema (shape,
+ *   count or caption length). Nothing was sent to the server.
+ * - `no block token` — the host holds no block token yet.
+ */
+export type BlockPrepareTrainingDatasetHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training dataset' | 'no block token';
+/**
+ * The HOST'S OWN refusal codes on a `TRAINING_RESULT`'s `error`. Mirrors
+ * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`
+ * (`src/components/AppBlocks/runTrainingGate.ts`).
+ *
+ * 🔴 THE SET A BLOCK MAY RELY ON, NOT THE SET IT MAY RECEIVE: server messages
+ * (an expired or already-used quote, a body that differs from the quoted one, an
+ * ineligible dataset image) arrive verbatim in the same field.
+ *
+ * - `review-mode` — a mod-review sandbox with "run for real" off.
+ * - `block is not ready` — the host handshake has not completed.
+ * - `sign in to train` — anonymous viewer; there is no account to charge.
+ * - `invalid training request` — the body is not a `kind: 'training'` body
+ *   naming a `quoteId`.
+ * - `no block token` — the host holds no block token yet.
+ * - `declined` — the viewer dismissed the consent dialog. 🔴 GUARANTEED to mean
+ *   NO RUN WAS SUBMITTED.
+ * - `submission-unconfirmed` — the submit was SENT but its outcome is unknown
+ *   (the connection dropped, or the server attempted the run and could not
+ *   confirm it). 🔴 The run MAY BE RUNNING AND CHARGED. Check the viewer's
+ *   trainings (`useAppWorkflows()`, or send them to their Training page) before
+ *   offering a retry — a retry of the same body after the server did start the
+ *   run is a SECOND, separately charged run.
+ */
+export type BlockRunTrainingHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training request' | 'no block token' | 'declined' | 'submission-unconfirmed';
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/blocks/types.js

@@ -114,4 +114,30 @@ export function isPageSlotContext(ctx) {
 export function isSignedIn(viewer) {
     return viewer !== null && viewer !== undefined;
 }
+// ============================================================
+// App Blocks TRAINING kind (`kind: 'training'`)
+// ============================================================
+//
+// 🔴 MIRRORED FROM THE HOST, NOT DESIGNED HERE. Every type in this section copies
+// civitai/civitai's zod at `a32f506516` (main, after civitai/civitai#5434):
+// `blockTrainingBodySchema` in `src/server/schema/blocks/workflow.schema.ts`, and
+// `aiToolkitTrainingParamsSchema` in `src/server/schema/orchestrator/training.schema.ts`
+// for `params`. The host's zod is the definition; this is the copy. A field the
+// host adds is invisible here until this file is updated, and the host rejects a
+// body that does not parse — so a mismatch shows up as a refused estimate, never
+// as a silently different run.
+/** Ceiling on what ONE confirmed `kind: 'training'` run may cost, in Buzz. Host constant `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`. */
+export const BLOCK_TRAINING_MAX_BUZZ_PER_RUN = 5000;
+/** Max images in one prepared training dataset. Host constant `BLOCK_TRAINING_DATASET_MAX_ITEMS`. */
+export const BLOCK_TRAINING_DATASET_MAX_ITEMS = 50;
+/** Max characters of one dataset caption. Host constant `BLOCK_TRAINING_CAPTION_MAX_CHARS`. */
+export const BLOCK_TRAINING_CAPTION_MAX_CHARS = 1000;
+/** Max sample prompts on a training body. Host constant `BLOCK_TRAINING_SAMPLE_PROMPTS_MAX`. */
+export const BLOCK_TRAINING_SAMPLE_PROMPTS_MAX = 6;
+/** Max characters of one sample prompt. Host constant `BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS`. */
+export const BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS = 1000;
+/** Max characters of the trigger word. Host constant `BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS`. */
+export const BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS = 64;
+/** Max characters of the base-model key. Host constant `BLOCK_TRAINING_MODEL_KEY_MAX_CHARS`. */
+export const BLOCK_TRAINING_MODEL_KEY_MAX_CHARS = 64;
 //# sourceMappingURL=types.js.map

package/dist/index.d.ts

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    135 symbols and that side effect into the root would make every OAuth app
+ *    154 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 135 is ASSERTED, not merely quoted — by
+ *    🔴 That 154 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/dist/index.js

@@ -25,11 +25,11 @@
  *
  *  - **`./blocks`** — importing it RUNS `./safe-storage` for its side effect
  *    (repairing `localStorage`/`sessionStorage` at an opaque origin). Folding
- *    135 symbols and that side effect into the root would make every OAuth app
+ *    154 symbols and that side effect into the root would make every OAuth app
  *    that writes `import { exchangeCode } from '@civitai/app-sdk'` pay for the
  *    Civitai-Apps contract it does not use. Blocks and OAuth apps are disjoint
  *    audiences; see this package's README.
- *    🔴 That 135 is ASSERTED, not merely quoted — by
+ *    🔴 That 154 is ASSERTED, not merely quoted — by
  *    `packages/civitai-app-sdk/test/export-surface.test.ts`, which pins
  *    `surface.get('./blocks').size`. It said 119 here against a real 125 until
  *    2026-10-04, because the existing checks pin the root as an exact union and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.57.0",
+  "version": "0.58.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",