@civitai/app-sdk 0.75.0 → 0.77.0

package/README.md

@@ -32,7 +32,7 @@ pnpm add @civitai/app-sdk
 | `orchestrator/steps` — `WorkflowStepTemplates`, `WorkflowStepTemplateFor`, `WorkflowStepInputFor`, `AnyWorkflowStepTemplate`, `TypedWorkflowTemplate` | **Type-only** subpath (0 runtime bytes) keying the orchestrator's generated workflow-step shapes from `@civitai/client` by wire `$type`, so apps compose real step bodies against types that track the spec instead of hand-maintained copies. Requires the optional peer `@civitai/client@beta`. Type surface only — it grants no submit permission; see "Typed step shapes" below. |
 | `blocks/*` — `BlockManifestError`, `BLOCK_SCOPES`, `BLOCK_SCOPE_PATTERN`, `isMessage`, types (`BlockManifestV1`, `BlockContext`, `BlockToken`, `BlockSettings`, `ViewerInfo`, `ThemeInfo`, `BlockWorkflowSnapshot`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`, …) | Framework-agnostic contract for [Civitai Apps](https://github.com/civitai/civitai-app-starters/blob/main/docs/build-your-first-app-block.md). Ships a byte-identical copy of the server-published canonical JSON Schema (draft 2020-12, https://civitai.com/schemas/app-block/v1.json) at the `./schemas/app-block/v1.json` subpath for offline validation; a CI drift-check keeps it in sync. Runtime-agnostic and **zero runtime dependencies** — no React, no DOM types, nothing in your install graph. Hooks and the iframe transport live in a separate package. |
 | `manifest/*` — `defineBlock`, `SCHEMA_DIVERGENCES`, `KNOWN_GAPS` (**Node only**) | Build-time manifest validation. `defineBlock(config)` compiles the vendored canonical schema with [Ajv](https://ajv.js.org) and validates a `BlockManifestV1` against it, so authoring mistakes surface in `pnpm dev` instead of at `civitai app validate`/submit. It is **derived from the schema, not a hand-written mirror of it** — that mirror is what produced [#330](https://github.com/civitai/civitai-app-starters/issues/330). Needs `node:fs` and the optional peer `ajv`, which is why it is not on the browser-facing `./blocks` surface. |
-| `vite/*` — `blockManifestPlugin` (**Node only**) | A Vite plugin wrapping `defineBlock`, firing from `configResolved` — the one hook Vite calls on both the dev-server and the build path. Every block scaffold registers it, so `pnpm dev`, `pnpm dev:harness` and `pnpm build` all fail on a bad manifest with the offending field path. Optional peers: `ajv` (runtime) and `vite` (types only). |
+| `vite/*` — `blockManifestPlugin` (**Node only**) | A Vite plugin wrapping `defineBlock`, firing from `configResolved` — the one hook Vite calls on both the dev-server and the build path. Every block scaffold registers it, so `pnpm dev`, `pnpm dev:harness` and `pnpm build` all fail on a bad manifest with the offending field path. On the dev server only, it also exposes the manifest's `scopes` + `storage` to `@civitai/sdk` for a dev-tunnel local preview. Optional peers: `ajv` (runtime) and `vite` (types only). |
 
 ## Entry points, and what the root barrel is
 
@@ -151,7 +151,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'`), `WorkflowBodyTraining` (+ `AiToolkitTrainingParams`, `BlockTrainingQuote`, `BlockTrainingDatasetItem`, `BlockTrainingDatasetResult` and the `BLOCK_TRAINING_*` bounds), `WorkflowBodyWorkflow` (+ `WorkflowBodyWorkflowStep`, `WorkflowStepRef`, `WithWorkflowStepRefs`, `BlockWorkflowStepSnapshot` and `BLOCK_WORKFLOW_MAX_STEPS`), `BlockStepQuote` / `BlockRunConfirmedStepHostError` (+ `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`, `BLOCK_STEP_QUOTE_ID_REGEX`), `BlockModel3dOutput`, `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`, `BlockTrainingDataImage`, `BlockTrainingDataUploadResult`, `BlockRunTrainingHostError` and the `BLOCK_TRAINING_*` bounds), `WorkflowBodyWorkflow` (+ `WorkflowBodyWorkflowStep`, `WorkflowStepRef`, `WithWorkflowStepRefs`, `BlockWorkflowStepSnapshot` and `BLOCK_WORKFLOW_MAX_STEPS`), `BlockStepQuote` / `BlockRunConfirmedStepHostError` (+ `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`, `BLOCK_STEP_QUOTE_ID_REGEX`), `BlockModel3dOutput`, `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'`),
@@ -267,15 +267,21 @@ const rigged = pickModel(snapshot, 'fbx', 'riggedFbxModel');
 ```
 
 `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
+run on images the viewer uploaded through the host, mirroring the host's
+`blockTrainingBodySchema` (civitai/civitai#5434, #6461). Its dataset is `items: [{ air, caption }]`
+(`BlockTrainingDatasetItem`; at most `BLOCK_TRAINING_DATASET_MAX_ITEMS` items and
+`BLOCK_TRAINING_CAPTION_MAX_CHARS` caption characters, one blob at most once). 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 review sessions. The images are uploaded over `OPEN_IMAGE_UPLOAD { purpose: 'trainingData' }`,
+which replies `IMAGE_UPLOAD_RESULT { selected: { images: [{ url, air }] } }`
+(`BlockTrainingDataUploadResult`); the host refuses a run whose quote names a blob it did not
+upload for the block, with the `BlockRunTrainingHostError` `training data not uploaded here`.
+`PREPARE_TRAINING_DATASET` (the server-prepared dataset of civitai/civitai#5438) is removed from
+the protocol. Use it through `@civitai/blocks-react`'s `useImageUpload({ purpose: 'trainingData' })`
 and `useRunTraining()`.
 
 `WorkflowBodyWorkflow` (`kind: 'workflow'`) submits **several orchestrator steps as one
@@ -407,6 +413,15 @@ import { blockManifestPlugin } from '@civitai/app-sdk/vite';
 const plugins = [blockManifestPlugin()];
 ```
 
+**On the dev server only**, the plugin also puts the manifest's `scopes` and
+`storage` on the page (a `<script>` at the end of `index.html`'s `<head>`; `vite build` never
+emits it). `@civitai/sdk` reads it in a dev-tunnel preview, where the host marks the
+frame `storageMode: 'local-preview'` and `app.storage.collection(name)` is served by
+an in-memory store that enforces these declarations — see "In a dev-tunnel preview"
+in `@civitai/sdk`'s README. Nothing else of the manifest is exposed. Without the
+plugin, a preview's document store refuses every call `local_preview_no_manifest`:
+this plugin is the only way the manifest reaches `@civitai/sdk`.
+
 ### Web storage in a block (`@civitai/app-sdk/safe-storage`)
 
 Block iframes are sandboxed **without `allow-same-origin`**, so the document has

package/dist/blocks/index.d.ts

@@ -116,7 +116,7 @@ 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, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockStorageCollectionDeclaration, BlockStorageDeclaration, BlockStorageIndexes, BlockStorageIndexType, BlockStoragePrivateCollectionDeclaration, BlockStorageSharedCollectionDeclaration, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockMediaKind, BlockMediaUploadInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, KnownBlockWorkflowErrorCode, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, WithWorkflowStepRefs, BlockWorkflowStepSnapshot, 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, BlockStepQuote, BlockModel3dOutput, BlockRunConfirmedStepHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockStorageCollectionDeclaration, BlockStorageDeclaration, BlockStorageIndexes, BlockStorageIndexType, BlockStoragePrivateCollectionDeclaration, BlockStorageSharedCollectionDeclaration, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockMediaKind, BlockMediaUploadInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, KnownBlockWorkflowErrorCode, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, WithWorkflowStepRefs, BlockWorkflowStepSnapshot, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDataImage, BlockTrainingDataUploadResult, BlockRunTrainingHostError, BlockStepQuote, BlockModel3dOutput, BlockRunConfirmedStepHostError, } from './types.js';
 /** Host bound for the App Blocks `kind: 'workflow'` body — see `WorkflowBodyWorkflow`. */
 export { BLOCK_WORKFLOW_MAX_STEPS, BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS } from './types.js';
 /**

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, BlockImagePickerSource, BlockPickedImageInfo, BlockMediaKind, BlockMediaUploadInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining, WorkflowBodyPassThroughStep } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockImagePickerSource, BlockPickedImageInfo, BlockMediaKind, BlockMediaUploadInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDataUploadResult, WorkflowBodyTraining, WorkflowBodyPassThroughStep } from './types.js';
 import type { BlockAppReaction, BlockEntityReactionErrorCode, BlockEntityReactionResult, BlockEntityReactionsResult, BlockReactionEntityType } from './reactions.js';
 /**
  * Filter params for `GET_BUZZ_TRANSACTIONS`. All optional; the host validates
@@ -218,6 +218,21 @@ export interface BlockInitPayload {
      * them — ship without React.
      */
     effectiveBrowsingLevel?: number;
+    /**
+     * `'local-preview'` when the host mounted this frame as a DEV-TUNNEL preview,
+     * which has no server-side storage namespace. The host sets it from the
+     * surface it mounted — never from the token's scopes, and never from anything
+     * the block sent. Absent on every other surface.
+     *
+     * `@civitai/sdk`'s `initialize()` reads it once and serves
+     * `app.storage.collection(name)` from an in-memory store in the tab
+     * (`app.storage.mode === 'local-preview'`). Nothing in this package or in
+     * `@civitai/blocks-react` acts on it: their storage hooks keep the real routes.
+     *
+     * ADDITIVE + OPTIONAL. A host that predates it omits the field; a value other
+     * than the exact string must be treated as absent.
+     */
+    storageMode?: 'local-preview';
 }
 /**
  * The freeform value carried by one SHARED-storage entry. Unlike the per-user
@@ -495,13 +510,6 @@ export type ParentToBlockMessage = {
         result?: BlockCreatePostResult;
         error?: string;
     };
-} | {
-    type: 'TRAINING_DATASET_RESULT';
-    payload: {
-        requestId: string;
-        result?: BlockTrainingDatasetResult;
-        error?: string;
-    };
 } | {
     type: 'TRAINING_RESULT';
     payload: {
@@ -573,7 +581,7 @@ export type ParentToBlockMessage = {
     type: 'IMAGE_UPLOAD_RESULT';
     payload: {
         requestId: string;
-        selected?: BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo;
+        selected?: BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo | BlockTrainingDataUploadResult;
         /** A `bytes` upload's refusal or failure: a host string or a forwarded server message. */
         error?: string;
     };
@@ -873,12 +881,6 @@ 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: {
@@ -1214,7 +1216,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", "ESTIMATE_WORKFLOW_BATCH", "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", "RUN_CONFIRMED_STEP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "OPEN_IMAGE_PICKER", "OPEN_MEDIA_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", "SET_ENTITY_REACTION", "GET_ENTITY_REACTIONS"];
+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", "ESTIMATE_WORKFLOW_BATCH", "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", "RUN_TRAINING", "RUN_CONFIRMED_STEP", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_UPLOAD", "OPEN_IMAGE_PICKER", "OPEN_MEDIA_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", "SET_ENTITY_REACTION", "GET_ENTITY_REACTIONS"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -70,7 +70,6 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'QUERY_APP_WORKFLOWS',
     'PUBLISH_GENERATION_OUTPUTS',
     'CREATE_POST_FROM_APP',
-    'PREPARE_TRAINING_DATASET',
     'RUN_TRAINING',
     'RUN_CONFIRMED_STEP',
     'GET_IMAGES_BY_IDS',

package/dist/blocks/types.d.ts

@@ -256,8 +256,17 @@ export type BlockImageScanResult = {
  *    UNSCANNED — the orchestrator scans it at generation time — so the host
  *    returns ONLY the source shape ({@link BlockGenerationSourceImageInfo}); no
  *    `imageId`/`nsfwLevel`/`contentRating` crosses back into the block.
- */
-export type BlockUploadPurpose = 'display' | 'generationSource';
+ *  - `'trainingData'`: PRIVATE training images for a `kind: 'training'` run
+ *    (civitai/civitai#6461). The viewer picks up to
+ *    {@link BLOCK_TRAINING_DATASET_MAX_ITEMS} PNG, JPEG or WebP files in a host
+ *    modal; each is uploaded as a consumer blob, as Civitai's own training form
+ *    does. ONE reply carries every image that uploaded
+ *    ({@link BlockTrainingDataUploadResult}), and the host remembers each key it
+ *    uploaded for this block — `RUN_TRAINING` refuses a quote naming any other.
+ *    Page apps only. A host that predates the purpose normalises it to
+ *    `'display'` and answers with ONE moderated image instead.
+ */
+export type BlockUploadPurpose = 'display' | 'generationSource' | 'trainingData';
 /**
  * Which SPACE a `NAVIGATE` path is resolved in. Mirrors the host's
  * `NavigateScope` in civitai/civitai's `pageBlockHostLogic.ts`. Keep in lockstep.
@@ -296,6 +305,32 @@ export type BlockNavigateScope = 'app' | 'site';
  * lockstep.
  */
 export type BlockGenerationSourceImageInfo = BlockSourceImage;
+/**
+ * One image an `OPEN_IMAGE_UPLOAD { purpose: 'trainingData' }` uploaded — an
+ * element of {@link BlockTrainingDataUploadResult.images}. Mirrors the host's
+ * `TrainingDataUpload` in civitai/civitai's
+ * `src/components/AppBlocks/trainingDataUpload.ts` (civitai/civitai#6461).
+ *
+ * The image is PRIVATE training data: it is not published, scanned or given an
+ * `Image` row, so there is no `imageId`.
+ */
+export interface BlockTrainingDataImage {
+    /** The uploaded blob's url. Show it as the thumbnail; it is also accepted as an item's `air`. */
+    url: string;
+    /**
+     * The consumer-blob key — pass it as {@link BlockTrainingDatasetItem.air}.
+     * Opaque. The host compares keys case-insensitively.
+     */
+    air: string;
+}
+/**
+ * `IMAGE_UPLOAD_RESULT.selected` for `purpose: 'trainingData'`: every image that
+ * uploaded, in one reply. The viewer may finish with fewer than they picked when
+ * some failed to upload; a cancel is a reply with NO `selected`.
+ */
+export interface BlockTrainingDataUploadResult {
+    images: BlockTrainingDataImage[];
+}
 /**
  * Which of the viewer's own image libraries `OPEN_IMAGE_PICKER` (via
  * `useImagePicker`) offers:
@@ -1618,10 +1653,13 @@ export type WorkflowBodyWorkflow = {
 };
 /** 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`. */
+/**
+ * Max images in one training dataset ({@link WorkflowBodyTraining.items}), and in
+ * one `trainingData` upload. 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;
+export declare const BLOCK_TRAINING_CAPTION_MAX_CHARS = 8192;
 /** 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`. */
@@ -1706,16 +1744,16 @@ export type AiToolkitTrainingParams = AiToolkitTrainingParamsBase & ({
     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.
+ * Train a LoRA with the ai-toolkit engine on images the VIEWER uploaded through
+ * the host — 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.
+ *  - **Page apps only** (`/apps/run/<slug>`). The model slot answers
+ *    `RUN_TRAINING` 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
@@ -1724,17 +1762,22 @@ export type AiToolkitTrainingParams = AiToolkitTrainingParamsBase & ({
  *
  * ## 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}.
+ *  1. **Upload** — `useImageUpload({ purpose: 'trainingData' }).open()`
+ *     (`OPEN_IMAGE_UPLOAD { purpose: 'trainingData' }`). The viewer picks up to
+ *     {@link BLOCK_TRAINING_DATASET_MAX_ITEMS} images in a host modal; you get
+ *     `[{ url, air }]` ({@link BlockTrainingDataImage}), or `null` on cancel.
+ *     Pair each `air` with your caption to build {@link WorkflowBodyTraining.items}.
  *  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.
+ *     never from your body, with the host's own copies of the uploads as
+ *     thumbnails — and submits only on their click. A quote naming an image this
+ *     host did not upload for the block is refused with no dialog
+ *     (`training data not uploaded here`) — upload in the same page session as the
+ *     run; a reload forgets the uploads.
  *  4. **Follow** — `useBuzzWorkflow().watch(snapshot.workflowId)`.
  *
  * 🔴 `useBuzzWorkflow().submit()` REFUSES THIS BODY before sending it. The server
@@ -1750,8 +1793,12 @@ export type AiToolkitTrainingParams = AiToolkitTrainingParamsBase & ({
  */
 export interface WorkflowBodyTraining {
     kind: 'training';
-    /** The handle `usePrepareTrainingDataset()` returned — `tds_` + 32 hex characters. */
-    datasetId: string;
+    /**
+     * The dataset: 1…{@link BLOCK_TRAINING_DATASET_MAX_ITEMS} images this host
+     * uploaded for the viewer, each with its caption — see
+     * {@link BlockTrainingDatasetItem}. One blob may appear once.
+     */
+    items: BlockTrainingDatasetItem[];
     /** The only engine accepted. */
     engine: 'ai-toolkit';
     /**
@@ -1760,12 +1807,17 @@ export interface WorkflowBodyTraining {
      */
     model: string;
     params: AiToolkitTrainingParams;
-    /** At most {@link BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS} characters. Moderated like a prompt. */
+    /**
+     * At most {@link BLOCK_TRAINING_TRIGGER_WORD_MAX_CHARS} characters. The host runs
+     * it through the same trigger-word check Civitai's trainer and Training Studio
+     * use, at the estimate and again at the submit, before anything is reserved; a
+     * refused trigger word fails the estimate.
+     */
     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.
+     * {@link BLOCK_TRAINING_SAMPLE_PROMPT_MAX_CHARS} characters each. Checked for
+     * those bounds only, as in the Training Studio.
      */
     samplePrompts: string[];
     /**
@@ -1795,7 +1847,7 @@ export interface WorkflowBodyTraining {
  *    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
+ *    on images the viewer uploaded through the host. ESTIMATE ONLY
  *    through `useBuzzWorkflow`; it runs through `useRunTraining()`, whose
  *    host-chrome consent dialog is the only way to confirm its quote.
  *  - {@link WorkflowBodyWorkflow} (`kind: 'workflow'`) — up to
@@ -2163,8 +2215,8 @@ export interface BlockWorkflowSnapshot {
      *
      * `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.
+     * estimate again. `imageCount` is the size of the dataset the server quoted
+     * (`items.length`).
      *
      * Present ONLY on the reply to a `kind: 'training'` estimate. Absent on hosts
      * that predate civitai/civitai#5434.
@@ -2318,7 +2370,7 @@ export interface BlockTrainingQuote {
     quoteId: string;
     /** The quoted price, in Buzz. */
     total: number;
-    /** How many images the prepared dataset holds. */
+    /** How many images the quoted dataset holds. */
     imageCount: number;
     /** ISO-8601. The quote cannot be run after this. */
     expiresAt: string;
@@ -3451,85 +3503,30 @@ export interface BlockCreatePostResult {
  */
 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.
+ * One image of a training dataset ({@link WorkflowBodyTraining.items}) — a blob
+ * this host uploaded for the viewer, and the caption to train it with. The
+ * Training Studio's own `{ air, caption }` shape.
  *
- * 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.
+ * Host bounds (`blockTrainingDatasetItemsSchema`, civitai/civitai#6461): `air`
+ * is the blob's key ({@link BlockTrainingDataImage.air}) or its Civitai-hosted
+ * blob url — the server keeps only the key; `caption` at most
+ * {@link BLOCK_TRAINING_CAPTION_MAX_CHARS} characters; no other keys;
+ * 1…{@link BLOCK_TRAINING_DATASET_MAX_ITEMS} items per body, and one blob at
+ * most once (keys compare case-insensitively). A body outside them is refused at
+ * the estimate.
  */
 export interface BlockTrainingDatasetItem {
-    imageId: number;
+    air: string;
     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.
+ * (an expired or already-used quote, a body that differs from the quoted one)
+ * 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.
@@ -3537,6 +3534,11 @@ export type BlockPrepareTrainingDatasetHostError = 'review-mode' | 'block is not
  * - `invalid training request` — the body is not a `kind: 'training'` body
  *   naming a `quoteId`.
  * - `no block token` — the host holds no block token yet.
+ * - `training data not uploaded here` — the quote names an image this host did
+ *   not upload for this block (civitai/civitai#6461): the host remembers only the
+ *   blobs its own `OPEN_IMAGE_UPLOAD { purpose: 'trainingData' }` uploaded, and
+ *   forgets them on a reload. Refused BEFORE any dialog: NO RUN, nothing
+ *   charged. Upload the images again, estimate again, run that quote.
  * - `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
@@ -3546,7 +3548,7 @@ export type BlockPrepareTrainingDatasetHostError = 'review-mode' | 'block is not
  *   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 type BlockRunTrainingHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training request' | 'no block token' | 'training data not uploaded here' | 'declined' | 'submission-unconfirmed';
 /**
  * The HOST'S OWN refusal codes on a `CONFIRMED_STEP_RESULT`'s `error`. Mirrors
  * civitai/civitai's `RUN_CONFIRMED_STEP_HOST_ERRORS`

package/dist/blocks/types.js

@@ -151,8 +151,10 @@ export const BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS = 16;
 // ============================================================
 //
 // 🔴 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
+// civitai/civitai's zod as of civitai/civitai#6461 (head `05f1d1fa8f`):
+// `blockTrainingBodySchema` in `src/server/schema/blocks/workflow.schema.ts`,
+// `blockTrainingDatasetItemsSchema` in
+// `src/server/schema/blocks/training-dataset.schema.ts` for `items`, 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
@@ -160,10 +162,13 @@ export const BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS = 16;
 // 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`. */
+/**
+ * Max images in one training dataset ({@link WorkflowBodyTraining.items}), and in
+ * one `trainingData` upload. 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;
+export const BLOCK_TRAINING_CAPTION_MAX_CHARS = 8192;
 /** 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`. */

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
- *    198 symbols and that side effect into the root would make every OAuth app
+ *    197 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 198 is ASSERTED, not merely quoted — by
+ *    🔴 That 197 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
- *    198 symbols and that side effect into the root would make every OAuth app
+ *    197 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 198 is ASSERTED, not merely quoted — by
+ *    🔴 That 197 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/vite/index.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from 'vite';
+import type { BlockManifest } from '../blocks/types.js';
 export interface BlockManifestPluginOptions {
     /**
      * Path to the manifest. Relative paths resolve against `root`, which defaults
@@ -9,6 +10,34 @@ export interface BlockManifestPluginOptions {
     /** Overrides the Vite project root used to resolve a relative `manifestPath`. */
     root?: string;
 }
+/**
+ * The global the dev server's HTML sets for `@civitai/sdk` to read. Spelled again
+ * in `packages/civitai-sdk/src/doc-store/local-preview.ts` (the two packages share
+ * no code); `tests/guards/local-preview-manifest-global.test.mjs` pins the two equal.
+ *
+ * WHY A GLOBAL, set by a `<script>` the plugin adds to `index.html`, rather than
+ * the alternatives:
+ * - a VIRTUAL MODULE needs `@civitai/sdk` to import it, which fails to resolve in
+ *   every bundle not built by this plugin — production included;
+ * - a `define` substitution has to reach `@civitai/sdk` inside `node_modules`,
+ *   where it depends on how the dependency optimizer pre-bundles it, and it would
+ *   rewrite production builds too;
+ * - an `initialize()` option needs every app to import its manifest and pass it,
+ *   and would be public API.
+ * The `<script>` is added on the DEV SERVER only (`vite build` never emits it),
+ * needs no change in an app that registers this plugin, and the SDK reads it only
+ * when the host marks the frame a local preview. It is the ONLY way the manifest
+ * reaches the SDK, so an app that does NOT register the plugin gets the SDK's
+ * `local_preview_no_manifest` error. Every scaffold in this repo that ships a
+ * manifest registers it; not every scaffold elsewhere does (the CLI's
+ * `page-money` template, for one, does not), and those apps must add it.
+ */
+export declare const LOCAL_PREVIEW_MANIFEST_GLOBAL = "__CIVITAI_LOCAL_PREVIEW_MANIFEST__";
+/**
+ * The classic `<script>` body: only `scopes` and `storage`, as JSON with `<`
+ * escaped so no value can close the element.
+ */
+export declare function localPreviewManifestScript(manifest: Pick<BlockManifest, 'scopes' | 'storage'>): string;
 export declare function blockManifestPlugin(options?: BlockManifestPluginOptions): Plugin;
 export { BlockManifestError } from '../blocks/manifestError.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/vite/index.js

@@ -18,6 +18,13 @@
  * pre-check against the same canonical). It exists so a manifest mistake
  * surfaces in the dev loop rather than at submit time.
  *
+ * DEV SERVER ONLY, it also hands the manifest's `scopes` and `storage` to
+ * `@civitai/sdk`, for a dev-tunnel preview. A preview has no server-side storage,
+ * so when the host marks the frame `storageMode: 'local-preview'` the SDK serves
+ * `app.storage.collection(name)` from an in-memory store that enforces THESE
+ * declarations — the ones of the code being previewed, which the server has
+ * never seen. See {@link LOCAL_PREVIEW_MANIFEST_GLOBAL} for why it is a global.
+ *
  * PEERS: `ajv` (used at runtime by `@civitai/app-sdk/manifest`) and `vite`
  * (types only). Both are optional peers of `@civitai/app-sdk`; a scaffold using
  * this plugin needs both in its devDependencies.
@@ -25,7 +32,60 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { BlockManifestError, defineBlock } from '../manifest/index.js';
+/**
+ * The global the dev server's HTML sets for `@civitai/sdk` to read. Spelled again
+ * in `packages/civitai-sdk/src/doc-store/local-preview.ts` (the two packages share
+ * no code); `tests/guards/local-preview-manifest-global.test.mjs` pins the two equal.
+ *
+ * WHY A GLOBAL, set by a `<script>` the plugin adds to `index.html`, rather than
+ * the alternatives:
+ * - a VIRTUAL MODULE needs `@civitai/sdk` to import it, which fails to resolve in
+ *   every bundle not built by this plugin — production included;
+ * - a `define` substitution has to reach `@civitai/sdk` inside `node_modules`,
+ *   where it depends on how the dependency optimizer pre-bundles it, and it would
+ *   rewrite production builds too;
+ * - an `initialize()` option needs every app to import its manifest and pass it,
+ *   and would be public API.
+ * The `<script>` is added on the DEV SERVER only (`vite build` never emits it),
+ * needs no change in an app that registers this plugin, and the SDK reads it only
+ * when the host marks the frame a local preview. It is the ONLY way the manifest
+ * reaches the SDK, so an app that does NOT register the plugin gets the SDK's
+ * `local_preview_no_manifest` error. Every scaffold in this repo that ships a
+ * manifest registers it; not every scaffold elsewhere does (the CLI's
+ * `page-money` template, for one, does not), and those apps must add it.
+ */
+export const LOCAL_PREVIEW_MANIFEST_GLOBAL = '__CIVITAI_LOCAL_PREVIEW_MANIFEST__';
+/** Reads and validates the manifest, throwing the message Vite should print. */
+function loadManifest(manifestPath) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`block.manifest.json could not be read or parsed (${manifestPath}): ${err.message}`);
+    }
+    try {
+        defineBlock({ manifest });
+    }
+    catch (err) {
+        // Re-thrown with the field path up front: Vite prints the message, not
+        // the error's own properties, so `.field` would otherwise be invisible.
+        const field = err instanceof BlockManifestError && err.field ? ` [${err.field}]` : '';
+        throw new Error(`block.manifest.json is invalid${field}: ${err.message}`);
+    }
+    return manifest;
+}
+/**
+ * The classic `<script>` body: only `scopes` and `storage`, as JSON with `<`
+ * escaped so no value can close the element.
+ */
+export function localPreviewManifestScript(manifest) {
+    const exposed = JSON.stringify({ scopes: manifest.scopes, storage: manifest.storage }).replace(/</g, '\\u003c');
+    return `globalThis[${JSON.stringify(LOCAL_PREVIEW_MANIFEST_GLOBAL)}] = ${exposed};`;
+}
 export function blockManifestPlugin(options = {}) {
+    let manifestPath = '';
+    let serving = false;
     return {
         name: 'civitai-block-manifest',
         // `enforce: 'pre'` so the manifest error is the FIRST thing reported rather
@@ -36,23 +96,27 @@ export function blockManifestPlugin(options = {}) {
             // this module's own location — this file now lives inside the installed
             // package, not next to the consumer's manifest.
             const root = options.root ?? config?.root ?? process.cwd();
-            const manifestPath = resolve(root, options.manifestPath ?? './block.manifest.json');
-            let manifest;
-            try {
-                manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-            }
-            catch (err) {
-                throw new Error(`block.manifest.json could not be read or parsed (${manifestPath}): ${err.message}`);
-            }
-            try {
-                defineBlock({ manifest });
-            }
-            catch (err) {
-                // Re-thrown with the field path up front: Vite prints the message, not
-                // the error's own properties, so `.field` would otherwise be invisible.
-                const field = err instanceof BlockManifestError && err.field ? ` [${err.field}]` : '';
-                throw new Error(`block.manifest.json is invalid${field}: ${err.message}`);
-            }
+            manifestPath = resolve(root, options.manifestPath ?? './block.manifest.json');
+            serving = config?.command === 'serve';
+            loadManifest(manifestPath);
+        },
+        transformIndexHtml() {
+            // Dev server only: a build never carries the manifest into the page.
+            if (!serving)
+                return undefined;
+            // Re-read per page load, so an edited manifest takes effect on reload.
+            const manifest = loadManifest(manifestPath);
+            return [
+                {
+                    tag: 'script',
+                    // End of <head>, NOT `head-prepend`: prepended, a large `storage` block
+                    // could push `<meta charset>` past the 1024-byte prescan. Nothing needs
+                    // it earlier: the SDK reads the global inside `initialize()`, after
+                    // BLOCK_INIT, and a classic script still runs before any module script.
+                    injectTo: 'head',
+                    children: localPreviewManifestScript(manifest),
+                },
+            ];
         },
     };
 }

package/package.json

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