@civitai/sdk 0.18.0 → 0.19.1

package/dist/app/index.d.ts

@@ -1,5 +1,5 @@
 import type { BlockContext, BlockSettings, Theme, ViewerInfo } from '../core/handshake.js';
-import type { BlockTransport } from '../core/transport.js';
+import { type BlockTransport } from '../core/transport.js';
 import { type Host } from '../host/index.js';
 import { type OrchestrationClient } from '../orchestration/index.js';
 import { type GrantOptions, type Scope, type TokenOptions, type TokenSessionOptions } from '../session/index.js';

package/dist/app/index.js

@@ -1,5 +1,6 @@
 import { BridgeError, CivitaiError } from '../core/errors.js';
 import { getTransport } from '../core/get-transport.js';
+import { isLocalPreviewStorage } from '../core/transport.js';
 import { createHost, createHostSession } from '../host/index.js';
 import { ApiError, createHttp } from '../http/index.js';
 import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orchestration/index.js';
@@ -26,13 +27,16 @@ export async function initialize(options = {}) {
     // from `token.scopes`. A published app whose manifest forgot `apps:storage`
     // holds a token that looks the same as a preview's, and must keep getting the
     // real route's `insufficient_scope` rather than a silent local store.
-    const local = snapshot().storageMode === 'local-preview'
+    const localPreview = isLocalPreviewStorage(snapshot());
+    // The same latched answer configures the session below, so `requestGrants`
+    // and the store agree on whether the document store is local.
+    const local = localPreview
         ? // The manifest arrives only from `blockManifestPlugin()`'s dev-server
             // global: there is deliberately no option to pass one.
             await createLocalPreviewStorage(readInjectedManifest(), snapshot().viewer)
         : undefined;
     return {
-        ...createAppClient(createHostSession(transport), options, holdsBlockTokenNow, holdsOAuthTokenNow, local),
+        ...createAppClient(createHostSession(transport, { localPreviewStorage: localPreview }), options, holdsBlockTokenNow, holdsOAuthTokenNow, local),
         host: createHost(transport),
         get viewer() {
             return snapshot().viewer;

package/dist/core/transport.d.ts

@@ -63,6 +63,15 @@ export interface BlockTransport {
     on(type: string, handler: (payload: unknown) => void): () => void;
 }
 export declare const EMPTY_SNAPSHOT: BlockSnapshot;
+/**
+ * Did the host mark this frame a dev-tunnel preview whose document store is
+ * served locally? THE predicate for that question. `initialize()` reads it once
+ * and the one latched answer selects the local document store AND tells the
+ * host session which scopes no grant can add (`requestGrants`), so the two
+ * cannot disagree. Never inferred from `token.scopes`: a published app whose
+ * token lacks `apps:storage` looks the same as a preview's.
+ */
+export declare function isLocalPreviewStorage(snapshot: Pick<BlockSnapshot, 'storageMode'>): boolean;
 /** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
 export declare function snapshotFromInit(payload: BlockInitPayload, hostOrigin: string): BlockSnapshot;
 /** Wire `WrappedToken` (ISO expiry) → runtime `BlockToken` (Date expiry). */

package/dist/core/transport.js

@@ -10,6 +10,17 @@ export const EMPTY_SNAPSHOT = {
     blockInstanceId: '',
     hostOrigin: null,
 };
+/**
+ * Did the host mark this frame a dev-tunnel preview whose document store is
+ * served locally? THE predicate for that question. `initialize()` reads it once
+ * and the one latched answer selects the local document store AND tells the
+ * host session which scopes no grant can add (`requestGrants`), so the two
+ * cannot disagree. Never inferred from `token.scopes`: a published app whose
+ * token lacks `apps:storage` looks the same as a preview's.
+ */
+export function isLocalPreviewStorage(snapshot) {
+    return snapshot.storageMode === LOCAL_PREVIEW_STORAGE;
+}
 /** Convert a wire `BlockInitPayload` (ISO string expiresAt) into a `BlockSnapshot`. */
 export function snapshotFromInit(payload, hostOrigin) {
     return {

package/dist/core/transports/host-replies.generated.d.ts

@@ -7,7 +7,7 @@ export interface HostReply {
     readonly keys: readonly string[] | null;
 }
 /** The civitai commit this ledger was read from. A request the host added after it is refused too. */
-export declare const HOST_SNAPSHOT = "cd79a91fe4";
+export declare const HOST_SNAPSHOT = "05f1d1fa8f";
 /**
  * Every request the host answered at {@link HOST_SNAPSHOT}. A type absent here is refused.
  * Reply names and framing are fixed at publish time: if the host renames a reply or moves a

package/dist/core/transports/host-replies.generated.js

@@ -1,7 +1,7 @@
 // Generated by scripts/gen-host-replies.mjs from snapshots/host-messages.json
-// (civitai/civitai cd79a91fe4, 2026-10-17). Do not edit.
+// (civitai/civitai 05f1d1fa8f, 2026-10-20). Do not edit.
 /** The civitai commit this ledger was read from. A request the host added after it is refused too. */
-export const HOST_SNAPSHOT = "cd79a91fe4";
+export const HOST_SNAPSHOT = "05f1d1fa8f";
 /**
  * Every request the host answered at {@link HOST_SNAPSHOT}. A type absent here is refused.
  * Reply names and framing are fixed at publish time: if the host renames a reply or moves a
@@ -33,7 +33,7 @@ export const HOST_REPLIES = {
     "OPEN_MEDIA_UPLOAD": { "reply": "MEDIA_UPLOAD_RESULT", "framing": "legacy", "keys": ["selected"] },
     "OPEN_RESOURCE_PICKER": { "reply": "RESOURCE_PICKER_RESULT", "framing": "legacy", "keys": ["selected", "selectedResources"] },
     "POLL_WORKFLOW": { "reply": "WORKFLOW_STATUS", "framing": "legacy", "keys": ["snapshot"] },
-    "PREPARE_TRAINING_DATASET": { "reply": "TRAINING_DATASET_RESULT", "framing": "legacy", "keys": ["result"] },
+    "PREPARE_TRAINING_DATASET": { "reply": "TRAINING_DATASET_RESULT", "framing": "legacy", "keys": [] },
     "PUBLISH_GENERATION_OUTPUTS": { "reply": "PUBLISH_RESULT", "framing": "legacy", "keys": ["result"] },
     "QUERY_APP_WORKFLOWS": { "reply": "APP_WORKFLOWS_RESULT", "framing": "legacy", "keys": ["result"] },
     "REQUEST_TOKEN": { "reply": "TOKEN_REFRESH_RESPONSE", "framing": "legacy", "keys": ["token"] },

package/dist/doc-store/local-preview.d.ts

@@ -1,4 +1,5 @@
 import type { ViewerInfo } from '../core/handshake.js';
+import type { Scope } from '../session/index.js';
 import { type DocumentStorage } from './index.js';
 /**
  * The document store for a DEV-TUNNEL PREVIEW: the host marked the frame
@@ -22,6 +23,15 @@ import { type DocumentStorage } from './index.js';
  * `tests/guards/local-preview-manifest-global.test.mjs`.
  */
 export declare const LOCAL_PREVIEW_MANIFEST_GLOBAL = "__CIVITAI_LOCAL_PREVIEW_MANIFEST__";
+/**
+ * The scopes the local document store serves: the two the server's document
+ * store checks (`fake.ts` enforces the same pair). A preview token never
+ * carries them and no grant can add them, so `requestGrants` treats them as
+ * held in a local preview instead of asking the host. Shared storage
+ * (`apps:storage:shared:*`) and the deprecated key/value scopes are NOT here:
+ * they keep the real routes in a preview.
+ */
+export declare const LOCAL_PREVIEW_STORAGE_SCOPES: ReadonlySet<Scope>;
 /** What a local preview reads from the manifest: the scopes it declares and its `storage` block. */
 export interface LocalPreviewManifest {
     scopes?: readonly string[];

package/dist/doc-store/local-preview.js

@@ -21,6 +21,18 @@ import { createDocumentStorage, StorageError } from './index.js';
  * `tests/guards/local-preview-manifest-global.test.mjs`.
  */
 export const LOCAL_PREVIEW_MANIFEST_GLOBAL = '__CIVITAI_LOCAL_PREVIEW_MANIFEST__';
+/**
+ * The scopes the local document store serves: the two the server's document
+ * store checks (`fake.ts` enforces the same pair). A preview token never
+ * carries them and no grant can add them, so `requestGrants` treats them as
+ * held in a local preview instead of asking the host. Shared storage
+ * (`apps:storage:shared:*`) and the deprecated key/value scopes are NOT here:
+ * they keep the real routes in a preview.
+ */
+export const LOCAL_PREVIEW_STORAGE_SCOPES = new Set([
+    'apps:storage',
+    'apps:storage:publish',
+]);
 /** The manifest the dev server injected, if any. */
 export function readInjectedManifest() {
     const value = globalThis[LOCAL_PREVIEW_MANIFEST_GLOBAL];

package/dist/host/index.d.ts

@@ -124,5 +124,13 @@ export interface Host {
     }, opts?: HostCallOptions): Promise<number[]>;
 }
 export declare function createHost(transport: BlockTransport): Host;
+export interface HostSessionOptions {
+    /**
+     * The document store is served by the in-tab local store (a dev-tunnel
+     * preview): the value `initialize()` latched from `isLocalPreviewStorage`.
+     * `requestGrants` then treats `LOCAL_PREVIEW_STORAGE_SCOPES` as held.
+     */
+    localPreviewStorage?: boolean;
+}
 /** The token the host minted for this block, kept current as the host rotates it. */
-export declare function createHostSession(transport: BlockTransport): Session;
+export declare function createHostSession(transport: BlockTransport, { localPreviewStorage }?: HostSessionOptions): Session;

package/dist/host/index.js

@@ -1,6 +1,7 @@
 import { BridgeError } from '../core/errors.js';
 import { createCaller, createListener, createNotifier } from '../core/messaging.js';
 import { tokenFromWrapped } from '../core/transport.js';
+import { LOCAL_PREVIEW_STORAGE_SCOPES } from '../doc-store/local-preview.js';
 const call = createCaller();
 const notify = createNotifier();
 const on = createListener();
@@ -254,7 +255,7 @@ function asScanResult(value) {
     return { status: 'error', ...(typeof v?.message === 'string' ? { message: v.message } : {}) };
 }
 /** The token the host minted for this block, kept current as the host rotates it. */
-export function createHostSession(transport) {
+export function createHostSession(transport, { localPreviewStorage = false } = {}) {
     return {
         async getToken({ fresh, signal } = {}) {
             if (!fresh)
@@ -263,7 +264,14 @@ export function createHostSession(transport) {
             const { token } = await call('REQUEST_TOKEN', { blockInstanceId }, { transport, signal });
             return tokenFromWrapped(token).raw;
         },
-        requestGrants: (scopes, opts = {}) => requestGrants(transport, scopes, opts),
+        requestGrants: (scopes, opts = {}) => requestGrants(transport, 
+        // A preview token never carries a document-store scope and no grant can
+        // add one, so asking the host for it could only be refused — and the
+        // refusal would take the rest of the request down with it. The local
+        // store serves them; ask only for the rest. Nothing on the token changes.
+        localPreviewStorage
+            ? scopes.filter((scope) => !LOCAL_PREVIEW_STORAGE_SCOPES.has(scope))
+            : scopes, opts),
     };
 }
 /**

package/dist/index.d.ts

@@ -17,7 +17,7 @@ export { StorageError } from './doc-store/index.js';
 export type { DocumentAuthor, DocumentCallOptions, DocumentListQuery, DocumentPage, DocumentStorage, DocumentWhereValue, StorageCollection, StorageCollectionInfo, StorageDocument, StorageErrorCode, StorageIndexType, StorageInfo, StorageLimits, StorageUsage, WriteOptions, } from './doc-store/index.js';
 export { SubmissionUnconfirmedError } from './workflows/index.js';
 export type { WorkflowCallOptions, WorkflowGetOptions, WorkflowListQuery, WorkflowListResult, WorkflowSubmitOptions, WorkflowWatchOptions, WorkflowsClient, } from './workflows/index.js';
-export type { AiToolkitLrScheduler, AiToolkitOptimizerType, AiToolkitPlainEcosystem, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AppWorkflow, AppWorkflowImage, BlockModel3dOutput, BlockModelSubstitution, BlockPublishedModel, BlockSourceImage, BlockStepQuote, BlockStepToolCall, BlockTextToImageParams, BlockTrainedEpoch, BlockTrainingQuote, BlockWorkflowSnapshot, BlockWorkflowStepSnapshot, BuzzAccountType, InlineComfyNode, KnownBlockWorkflowErrorCode, ModelSubstitutionReason, WithWorkflowStepRefs, WorkflowBody, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyInline, WorkflowBodyCustomComfyRecipe, WorkflowBodyPassThroughStep, WorkflowBodyStep, WorkflowBodyTextToImage, WorkflowBodyTraining, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, } from './workflows/types.generated.js';
+export type { AiToolkitLrScheduler, AiToolkitOptimizerType, AiToolkitPlainEcosystem, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AppWorkflow, AppWorkflowImage, BlockModel3dOutput, BlockModelSubstitution, BlockPublishedModel, BlockSourceImage, BlockStepQuote, BlockStepToolCall, BlockTextToImageParams, BlockTrainedEpoch, BlockTrainingDatasetItem, BlockTrainingQuote, BlockWorkflowSnapshot, BlockWorkflowStepSnapshot, BuzzAccountType, InlineComfyNode, KnownBlockWorkflowErrorCode, ModelSubstitutionReason, WithWorkflowStepRefs, WorkflowBody, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyInline, WorkflowBodyCustomComfyRecipe, WorkflowBodyPassThroughStep, WorkflowBodyStep, WorkflowBodyTextToImage, WorkflowBodyTraining, WorkflowBodyWorkflow, WorkflowBodyWorkflowStep, WorkflowStepRef, } from './workflows/types.generated.js';
 export { isTerminal, isTerminalStatus } from './orchestration/index.js';
 export type { OrchestrationClient, Step, StepTemplate, WaitOptions, Workflow, WorkflowPage, WorkflowQuery, WorkflowStatus, WorkflowTemplate, } from './orchestration/index.js';
 export { createHost } from './host/index.js';

package/dist/version.generated.d.ts

@@ -1,2 +1,2 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.18.0";
+export declare const VERSION = "0.19.1";

package/dist/version.generated.js

@@ -1,3 +1,3 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.18.0";
+export const VERSION = "0.19.1";

package/dist/workflows/types.generated.d.ts

@@ -938,16 +938,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
@@ -956,17 +956,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
@@ -982,8 +987,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';
     /**
@@ -992,12 +1001,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[];
     /**
@@ -1027,7 +1041,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
@@ -1395,8 +1409,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.
@@ -1529,7 +1543,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;
@@ -1710,3 +1724,20 @@ export interface AppWorkflow {
      */
     model3dOutputs?: BlockModel3dOutput[];
 }
+/**
+ * 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`, 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 {
+    air: string;
+    caption: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/sdk",
-  "version": "0.18.0",
+  "version": "0.19.1",
   "description": "The Civitai SDK: an app holds a token and calls the Civitai API and the orchestrator; a block asks its host only to show host UI.",
   "license": "MIT",
   "type": "module",