@civitai/sdk 0.17.1 → 0.19.0

package/README.md

@@ -282,6 +282,55 @@ before moderation and before any write budget. An absent field is allowed;
 ownership is checked only when the document is written. Only phase-one operations exist: no batch writes, change feed, TTL or
 owner-written documents yet.
 
+### In a dev-tunnel preview: local to the tab
+
+A dev-tunnel preview (`civitai app dev-tunnel`, the App Assistant's live
+preview) has **no server-side storage**: an app that is not approved has no storage
+namespace, and unreviewed code must not write into a published app's data. So when
+the host marks the frame `storageMode: 'local-preview'` in `BLOCK_INIT`,
+`initialize()` serves `app.storage.collection(name)` and `app.storage.info()` from an
+**in-memory store in this tab** — [`createFakeStorage`](#a-fake-document-store), the
+real client over a seam that enforces the server's rules — and sends **no request**
+to `blocks/storage/*`. Your code does not change; show a badge so nobody mistakes the
+data for real:
+
+```ts
+if (app.storage.mode === 'local-preview') {
+  showBadge('Preview data is local to this tab');
+}
+```
+
+- **Your LOCAL manifest decides the collections**, not the server's copy:
+  `blockManifestPlugin()` from `@civitai/app-sdk/vite` hands its `scopes` and
+  `storage` to the page on the dev server (never in a build); that is the only way
+  the manifest reaches the SDK. It does so from the `@civitai/app-sdk` release that
+  includes this change (the one whose CHANGELOG entry reads "`blockManifestPlugin()`
+  exposes the manifest's `scopes` and `storage` to `@civitai/sdk` on the dev server
+  only"); a `^0.x` range never moves to a newer minor, so raise that pin by hand.
+  Not every scaffold registers the plugin (the CLI's `page-money` template does
+  not); add it there. Without it, every document-store call rejects
+  `local_preview_no_manifest` (a `StorageError`, status 404, sent nowhere); a
+  declaration the local store cannot serve rejects `local_preview_invalid_manifest`
+  (also 404), and a local store that failed to load rejects
+  `local_preview_unavailable` (also 404; reload the preview). None is a status this
+  SDK treats as retryable, and none falls back to the real routes.
+- **Model-version ownership is not checked locally.** A collection's
+  `ownedModelVersions` fields accept any well-formed model version id in a preview;
+  the server checks that the writer owns it. A malformed value is still refused.
+- **One viewer, one tab, gone on reload.** It cannot show other people's entries,
+  real vote totals, ranking across users, the minimum-trust gate on shared writes,
+  or moderation of real content.
+- **Only the document store.** The deprecated `app.storage.get/set/…`,
+  `app.sharedStorage` and `@civitai/blocks-react`'s `useAppStorage` /
+  `useSharedStorage` keep calling the real routes, which refuse a preview.
+- **Only on the host's signal.** `app.storage.mode` is latched when `initialize()`
+  resolves, and never inferred from the token: a published app whose manifest forgot
+  `apps:storage` holds a token that looks the same, and keeps getting the real
+  route's `insufficient_scope`. That refusal's message says what to do —
+  declare `apps:storage` under `scopes`; it is granted once the app is approved — and
+  that in a preview this SDK would have kept the data locally had the host marked the
+  frame.
+
 The legacy stores below keep working, unchanged, while apps move; their methods are
 `@deprecated`. Nothing is copied from them into collections.
 

package/dist/app/index.d.ts

@@ -9,6 +9,21 @@ import { type SiteClient } from '../site/index.js';
 import { type StorageClient } from '../storage/index.js';
 import { type SubListingsClient } from '../sub-listings/index.js';
 import { type WorkflowsClient } from '../workflows/index.js';
+/**
+ * Which store serves `app.storage.collection(name)` and `app.storage.info()`.
+ *
+ * - `'remote'` — the server's document store, `/api/v1/blocks/storage/…`.
+ * - `'local-preview'` — an in-memory store in this tab, because the host marked
+ *   the frame a dev-tunnel preview (which has no server-side storage). It
+ *   enforces the server's rules against the LOCAL manifest, models ONE viewer,
+ *   and is gone on reload. Show the viewer a "preview data is local to this tab"
+ *   badge.
+ *
+ * Latched when `initialize()` resolves. Only the document store switches: the
+ * deprecated key/value methods on `app.storage`, `app.sharedStorage` and the
+ * `@civitai/blocks-react` storage hooks keep calling the real routes.
+ */
+export type StorageMode = 'remote' | 'local-preview';
 export interface AppClient {
     /**
      * The public Civitai REST API (`/api/v1`), as the viewer.
@@ -36,7 +51,9 @@ export interface AppClient {
      * with an OAuth access token is refused. The legacy store refuses an anonymous
      * viewer outright; the document store lets one read SHARED collections only.
      */
-    readonly storage: StorageClient & DocumentStorage;
+    readonly storage: StorageClient & DocumentStorage & {
+        readonly mode: StorageMode;
+    };
     /**
      * @deprecated Declare a `shared` collection under `storage.collections` and use
      * `app.storage.collection(name)`. This store keeps working, unchanged, until the

package/dist/app/index.js

@@ -6,6 +6,7 @@ import { createOrchestrationClient, DEFAULT_ORCHESTRATION_URL, } from '../orches
 import { createTokenSession, } from '../session/index.js';
 import { createSharedStorageClient, } from '../shared-storage/index.js';
 import { createDocumentStorage } from '../doc-store/index.js';
+import { createLocalPreviewStorage, readInjectedManifest } from '../doc-store/local-preview.js';
 import { createSiteClient, DEFAULT_SITE_URL } from '../site/index.js';
 import { createStorageClient } from '../storage/index.js';
 import { createSubListingsClient } from '../sub-listings/index.js';
@@ -21,8 +22,17 @@ export async function initialize(options = {}) {
     const holdsBlockTokenNow = holdsBlockToken(snapshot);
     // Read live, like the predicate above: the host rotates the token.
     const holdsOAuthTokenNow = () => snapshot().token.kind === 'oauth';
+    // 🔴 Latched here, ONCE, and only on the host's exact signal — never inferred
+    // 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'
+        ? // 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),
+        ...createAppClient(createHostSession(transport), options, holdsBlockTokenNow, holdsOAuthTokenNow, local),
         host: createHost(transport),
         get viewer() {
             return snapshot().viewer;
@@ -81,7 +91,9 @@ const OAUTH_OPT_IN = 'declare `auth: "oauth"` in block.manifest.json';
  * refuses, with nothing in this repo able to notice it going stale.
  */
 const BLOCK_NAMESPACE = /^\/*blocks\//;
-function createAppClient(session, options, holdsBlockTokenNow = () => false, holdsOAuthTokenNow = () => false) {
+function createAppClient(session, options, holdsBlockTokenNow = () => false, holdsOAuthTokenNow = () => false, 
+/** A local preview's document store; when present, the site HTTP client never reaches the document store. */
+localDocuments) {
     const http = (baseUrl) => createHttp({ session, baseUrl, fetch: options.fetch });
     // One instance for every site-hosted surface: the storage, sub-listings and
     // workflows clients' routes live under the same base URL, so a `siteUrl`
@@ -100,7 +112,15 @@ function createAppClient(session, options, holdsBlockTokenNow = () => false, hol
         // One object, two stores, no shared names: the legacy five and the document
         // store's `collection`/`info`. Spread rather than chained so neither keeps a
         // reference to the other.
-        storage: { ...createStorageClient(siteHttp), ...createDocumentStorage(siteHttp) },
+        //
+        // In a local preview the document store is the in-memory one and is never
+        // handed `siteHttp`: zero `blocks/storage/*` requests by construction. The
+        // legacy key/value methods are out of scope and keep the real routes.
+        storage: {
+            ...createStorageClient(siteHttp),
+            ...(localDocuments ?? createDocumentStorage(siteHttp, { explainInsufficientScope: true })),
+            mode: localDocuments ? 'local-preview' : 'remote',
+        },
         sharedStorage: createSharedStorageClient(siteHttp),
         subListings: createSubListingsClient(siteHttp),
         workflows: createWorkflowsClient(explainWorkflowRefusal(siteHttp, holdsOAuthTokenNow)),

package/dist/core/handshake.d.ts

@@ -98,7 +98,17 @@ export interface BlockInitPayload {
     maxBrowsingLevel?: number;
     /** The domain ceiling narrowed to this viewer. Always a subset of the above. */
     effectiveBrowsingLevel?: number;
+    /**
+     * `'local-preview'` when the host mounted this frame as a dev-tunnel preview,
+     * which has no server-side storage. The host sets it from the surface it
+     * mounted, never from the token or anything the block sent. Absent everywhere
+     * else, and from a host that predates it. Typed `unknown` on the wire: only
+     * the exact string switches anything — see {@link LOCAL_PREVIEW_STORAGE}.
+     */
+    storageMode?: unknown;
 }
+/** The one value of `BLOCK_INIT.storageMode` the SDK acts on. Compared exactly. */
+export declare const LOCAL_PREVIEW_STORAGE = "local-preview";
 /**
  * Host messages the transport itself acts on. Domains own everything else.
  *

package/dist/core/handshake.js

@@ -2,6 +2,8 @@
  * The host's side of the handshake, as it arrives on the wire. The shapes are
  * the host's and must track it.
  */
+/** The one value of `BLOCK_INIT.storageMode` the SDK acts on. Compared exactly. */
+export const LOCAL_PREVIEW_STORAGE = 'local-preview';
 /** Discriminator only — the payload is still unvalidated wire data. */
 export function isHostMessage(data, type) {
     return (typeof data === 'object' &&

package/dist/core/transport.d.ts

@@ -29,6 +29,12 @@ export interface BlockSnapshot {
     maxBrowsingLevel?: number;
     /** The domain ceiling narrowed to this viewer. Always a subset of `maxBrowsingLevel`. */
     effectiveBrowsingLevel?: number;
+    /**
+     * `'local-preview'` when the host said this frame is a dev-tunnel preview with
+     * no server-side storage; absent otherwise. `initialize()` reads it ONCE, so a
+     * later change cannot move an app's storage between stores mid-session.
+     */
+    storageMode?: 'local-preview';
 }
 export interface RequestOptions {
     signal?: AbortSignal;

package/dist/core/transport.js

@@ -1,3 +1,4 @@
+import { LOCAL_PREVIEW_STORAGE } from './handshake.js';
 export const EMPTY_SNAPSHOT = {
     ready: false,
     renderMode: 'iframe',
@@ -24,6 +25,9 @@ export function snapshotFromInit(payload, hostOrigin) {
         domain: payload.domain,
         maxBrowsingLevel: payload.maxBrowsingLevel,
         effectiveBrowsingLevel: payload.effectiveBrowsingLevel,
+        // The exact string or nothing: a value this SDK does not know must read as
+        // "not a local preview", which keeps today's behaviour (the real routes).
+        ...(payload.storageMode === LOCAL_PREVIEW_STORAGE ? { storageMode: LOCAL_PREVIEW_STORAGE } : {}),
     };
 }
 /** Wire `WrappedToken` (ISO expiry) → runtime `BlockToken` (Date expiry). */

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/index.d.ts

@@ -171,7 +171,16 @@ export interface DocumentStorage {
  * Every code the server documents for these routes. The type stays open
  * (`string & {}`) so a code a later server adds still reaches the caller.
  */
-export type StorageErrorCode = 'invalid_request' | 'index_not_declared' | 'unauthenticated' | 'sign_in_required' | 'insufficient_scope' | 'consent_required' | 'not_eligible' | 'not_author' | 'write_policy' | 'resource_not_owned' | 'not_found' | 'collection_not_declared' | 'method_not_allowed' | 'version_conflict' | 'index_building' | 'cursor_expired' | 'too_large' | 'quota_exceeded' | 'content_rejected' | 'rate_limited' | 'internal_error' | 'storage_disabled' | 'moderation_unavailable' | 'consent_unavailable' | 'service_unavailable' | (string & {});
+export type StorageErrorCode = 'invalid_request' | 'index_not_declared' | 'unauthenticated' | 'sign_in_required' | 'insufficient_scope' | 'consent_required' | 'not_eligible' | 'not_author' | 'write_policy' | 'resource_not_owned' | 'not_found' | 'collection_not_declared' | 'method_not_allowed' | 'version_conflict' | 'index_building' | 'cursor_expired' | 'too_large' | 'quota_exceeded' | 'content_rejected' | 'rate_limited' | 'internal_error' | 'storage_disabled' | 'moderation_unavailable' | 'consent_unavailable' | 'service_unavailable'
+/**
+ * LOCAL, never sent by the server: the host marked this frame a dev-tunnel
+ * local preview, and no manifest reached the SDK to say which collections exist.
+ */
+ | 'local_preview_no_manifest'
+/** LOCAL, never sent by the server: the local preview's manifest declares storage the local store cannot serve. */
+ | 'local_preview_invalid_manifest'
+/** LOCAL, never sent by the server: the local preview's in-memory store could not be loaded. */
+ | 'local_preview_unavailable' | (string & {});
 /**
  * A refusal from the document store, in its one envelope `{ code, message, error, details? }`.
  * Branch on `code`; `status` and `body` are {@link ApiError}'s, as sent.
@@ -184,4 +193,16 @@ export declare class StorageError extends ApiError {
     /** Seconds to wait before retrying, when the server named one (`rate_limited`, a retryable 503). */
     get retryAfter(): number | undefined;
 }
-export declare function createDocumentStorage(http: Http): DocumentStorage;
+/**
+ * Appended to a REAL route's `insufficient_scope`, after the server's own sentence.
+ * The server cannot tell a published app whose manifest forgot the scope from a
+ * dev-tunnel preview (which is never granted it), so the message covers both —
+ * and says that, in a preview, this SDK keeps the data locally once the host
+ * marks the frame, so seeing this refusal there means the host did not.
+ */
+export declare const INSUFFICIENT_SCOPE_HINT: string;
+export interface DocumentStorageOptions {
+    /** Append {@link INSUFFICIENT_SCOPE_HINT} to an `insufficient_scope` refusal. The server's `code` is unchanged. */
+    explainInsufficientScope?: boolean;
+}
+export declare function createDocumentStorage(http: Http, options?: DocumentStorageOptions): DocumentStorage;

package/dist/doc-store/index.js

@@ -42,8 +42,19 @@ export class StorageError extends ApiError {
         return typeof value === 'number' ? value : undefined;
     }
 }
+/**
+ * Appended to a REAL route's `insufficient_scope`, after the server's own sentence.
+ * The server cannot tell a published app whose manifest forgot the scope from a
+ * dev-tunnel preview (which is never granted it), so the message covers both —
+ * and says that, in a preview, this SDK keeps the data locally once the host
+ * marks the frame, so seeing this refusal there means the host did not.
+ */
+export const INSUFFICIENT_SCOPE_HINT = 'Declare `apps:storage` under `scopes` in block.manifest.json; it is granted once the app is approved. ' +
+    'In a dev-tunnel preview, this version of @civitai/sdk keeps preview data in a local in-memory store ' +
+    "instead, when the host marks the frame `storageMode: 'local-preview'` — this refusal came from the real " +
+    'route, so this frame was not marked.';
 /** An {@link ApiError} whose body is the store's envelope becomes a {@link StorageError}; anything else passes through. */
-function toStorageError(error) {
+function toStorageError(error, options = {}) {
     if (!(error instanceof ApiError) || error instanceof StorageError)
         return error;
     const body = error.body;
@@ -52,7 +63,10 @@ function toStorageError(error) {
     const { code, message, details } = body;
     if (typeof code !== 'string')
         return error;
-    return new StorageError(error.status, code, typeof message === 'string' ? message : error.message, body, details != null && typeof details === 'object' && !Array.isArray(details)
+    const said = typeof message === 'string' ? message : error.message;
+    return new StorageError(error.status, code, 
+    // `body` stays as the server sent it; only the human-readable sentence grows.
+    options.explainInsufficientScope && code === 'insufficient_scope' ? `${said} — ${INSUFFICIENT_SCOPE_HINT}` : said, body, details != null && typeof details === 'object' && !Array.isArray(details)
         ? details
         : undefined, { cause: error });
 }
@@ -87,13 +101,13 @@ function segment(what, value) {
     }
     return encodeURIComponent(value);
 }
-export function createDocumentStorage(http) {
+export function createDocumentStorage(http, options = {}) {
     const call = async (method, path, opts = {}) => {
         try {
             return await http(method, path, opts);
         }
         catch (error) {
-            throw toStorageError(error);
+            throw toStorageError(error, options);
         }
     };
     return {

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

@@ -0,0 +1,49 @@
+import type { ViewerInfo } from '../core/handshake.js';
+import { type DocumentStorage } from './index.js';
+/**
+ * The document store for a DEV-TUNNEL PREVIEW: the host marked the frame
+ * `storageMode: 'local-preview'` (a preview has no server-side storage namespace,
+ * by design), so `app.storage.collection(name)` is served by an in-memory store
+ * in this tab instead of `/api/v1/blocks/storage/…`.
+ *
+ * That store is `createFakeStorage` — the real client over a seam that enforces
+ * the server's rules — loaded with a dynamic `import()`, so it is a separate
+ * chunk that an app outside a preview never downloads. It never receives the
+ * site HTTP client, so no request can reach a real route by construction.
+ *
+ * The collections come from the app's LOCAL manifest, the one being previewed,
+ * never from the server. With none available, every call fails with a local
+ * error instead of falling through to the real routes or to a permissive store.
+ */
+/**
+ * Where `@civitai/app-sdk/vite` puts the local manifest's `scopes` and `storage`
+ * in a DEV SERVER page (never in a build). Spelled again, on purpose, in
+ * `packages/civitai-app-sdk/src/vite/index.ts`; the two copies are pinned equal by
+ * `tests/guards/local-preview-manifest-global.test.mjs`.
+ */
+export declare const LOCAL_PREVIEW_MANIFEST_GLOBAL = "__CIVITAI_LOCAL_PREVIEW_MANIFEST__";
+/** What a local preview reads from the manifest: the scopes it declares and its `storage` block. */
+export interface LocalPreviewManifest {
+    scopes?: readonly string[];
+    storage?: unknown;
+}
+/** The manifest the dev server injected, if any. */
+export declare function readInjectedManifest(): LocalPreviewManifest | undefined;
+/**
+ * The status of every local error (`local_preview_no_manifest`,
+ * `local_preview_invalid_manifest`, `local_preview_unavailable`). A missing or
+ * unservable manifest is a SETUP mistake that no wait fixes, so it must not be a status `isTransient`
+ * (`src/http/retry.ts`) reads as retryable — that is every 5xx and 429. 404 is
+ * the status the server gives the nearest case it has, `collection_not_declared`:
+ * with no usable manifest, no collection is declared. `get` still rejects (it
+ * reads only the code `not_found` as "no document"), and the `code` tells them
+ * apart. A store that failed to load is not retried either: a reload is the fix,
+ * and the message says so.
+ */
+export declare const LOCAL_PREVIEW_ERROR_STATUS = 404;
+/**
+ * Builds the preview's document store. Never throws: a missing or unusable
+ * manifest, or a local store that fails to load, yields a store whose every call
+ * rejects, so storage cannot stop the rest of the app from starting.
+ */
+export declare function createLocalPreviewStorage(manifest: LocalPreviewManifest | undefined, viewer: ViewerInfo | null): Promise<DocumentStorage>;

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

@@ -0,0 +1,131 @@
+import { createDocumentStorage, StorageError } from './index.js';
+/**
+ * The document store for a DEV-TUNNEL PREVIEW: the host marked the frame
+ * `storageMode: 'local-preview'` (a preview has no server-side storage namespace,
+ * by design), so `app.storage.collection(name)` is served by an in-memory store
+ * in this tab instead of `/api/v1/blocks/storage/…`.
+ *
+ * That store is `createFakeStorage` — the real client over a seam that enforces
+ * the server's rules — loaded with a dynamic `import()`, so it is a separate
+ * chunk that an app outside a preview never downloads. It never receives the
+ * site HTTP client, so no request can reach a real route by construction.
+ *
+ * The collections come from the app's LOCAL manifest, the one being previewed,
+ * never from the server. With none available, every call fails with a local
+ * error instead of falling through to the real routes or to a permissive store.
+ */
+/**
+ * Where `@civitai/app-sdk/vite` puts the local manifest's `scopes` and `storage`
+ * in a DEV SERVER page (never in a build). Spelled again, on purpose, in
+ * `packages/civitai-app-sdk/src/vite/index.ts`; the two copies are pinned equal by
+ * `tests/guards/local-preview-manifest-global.test.mjs`.
+ */
+export const LOCAL_PREVIEW_MANIFEST_GLOBAL = '__CIVITAI_LOCAL_PREVIEW_MANIFEST__';
+/** The manifest the dev server injected, if any. */
+export function readInjectedManifest() {
+    const value = globalThis[LOCAL_PREVIEW_MANIFEST_GLOBAL];
+    return value != null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+const NO_MANIFEST = "local preview storage: the host marked this frame `storageMode: 'local-preview'` (a dev-tunnel preview, " +
+    'which has no server-side storage), and no block.manifest.json reached @civitai/sdk to say which ' +
+    'collections exist. Add `blockManifestPlugin()` from `@civitai/app-sdk/vite` to vite.config and run the ' +
+    'Vite dev server, with the @civitai/app-sdk release that includes the local-preview manifest injection or ' +
+    'later — the plugin does not inject it before that release, and a `^0.x` range never moves to a newer ' +
+    'minor, so raise the pin by hand. Nothing was sent to the server.';
+/**
+ * The status of every local error (`local_preview_no_manifest`,
+ * `local_preview_invalid_manifest`, `local_preview_unavailable`). A missing or
+ * unservable manifest is a SETUP mistake that no wait fixes, so it must not be a status `isTransient`
+ * (`src/http/retry.ts`) reads as retryable — that is every 5xx and 429. 404 is
+ * the status the server gives the nearest case it has, `collection_not_declared`:
+ * with no usable manifest, no collection is declared. `get` still rejects (it
+ * reads only the code `not_found` as "no document"), and the `code` tells them
+ * apart. A store that failed to load is not retried either: a reload is the fix,
+ * and the message says so.
+ */
+export const LOCAL_PREVIEW_ERROR_STATUS = 404;
+/**
+ * Builds the preview's document store. Never throws: a missing or unusable
+ * manifest, or a local store that fails to load, yields a store whose every call
+ * rejects, so storage cannot stop the rest of the app from starting.
+ */
+export async function createLocalPreviewStorage(manifest, viewer) {
+    if (manifest === undefined)
+        return refusingStorage('local_preview_no_manifest', NO_MANIFEST);
+    let createFakeStorage;
+    try {
+        ({ createFakeStorage } = await import('./fake.js'));
+    }
+    catch (error) {
+        return refusingStorage('local_preview_unavailable', `local preview storage: the local store could not be loaded — ${error?.message ?? String(error)}. ` +
+            'Reload the preview. Nothing was sent to the server.');
+    }
+    // MODEL-VERSION OWNERSHIP IS NOT CHECKED LOCALLY. The server checks a write's
+    // `ownedModelVersions` fields against the model versions the writer really
+    // owns; the local store knows of none, and would refuse every such write the
+    // server accepts. So every well-formed id a write carries is added to the
+    // viewer's `modelVersions` — the fake's own seam, read per call — before the
+    // write reaches it. Malformed values are still refused, as the server refuses them.
+    const owned = [];
+    const localViewer = viewer === null
+        ? null
+        : {
+            username: viewer.username ?? `user-${viewer.id}`,
+            get modelVersions() {
+                return owned;
+            },
+        };
+    try {
+        const fake = createFakeStorage({
+            manifest: { scopes: manifest.scopes, storage: manifest.storage },
+            // Latched at init, like the mode: a sign-in remounts the frame.
+            viewer: localViewer,
+        });
+        const http = (method, path, opts) => {
+            collectIds(opts?.body, owned);
+            return fake.http(method, path, opts);
+        };
+        return createDocumentStorage(http);
+    }
+    catch (error) {
+        return refusingStorage('local_preview_invalid_manifest', `local preview storage: block.manifest.json declares storage the local preview store cannot serve — ` +
+            `${error.message}. Nothing was sent to the server.`);
+    }
+}
+/** Every integer a write body carries that could be a model version id. */
+function collectIds(value, into) {
+    if (typeof value === 'number') {
+        if (Number.isInteger(value) && value >= 1 && !into.includes(value))
+            into.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectIds(item, into);
+    }
+    else if (value !== null && typeof value === 'object') {
+        for (const item of Object.values(value))
+            collectIds(item, into);
+    }
+}
+/** A store that refuses every call with one LOCAL, non-retryable error. */
+function refusingStorage(code, message) {
+    const refuse = () => Promise.reject(new StorageError(LOCAL_PREVIEW_ERROR_STATUS, code, message, { code, message, error: message }));
+    // Every method of `StorageCollection`, so `satisfies` fails the build if one is added.
+    const collection = {
+        get: refuse,
+        getMany: refuse,
+        put: refuse,
+        create: refuse,
+        delete: refuse,
+        list: refuse,
+        increment: refuse,
+        mark: refuse,
+        unmark: refuse,
+    };
+    return {
+        collection: () => collection,
+        info: refuse,
+    };
+}

package/dist/index.d.ts

@@ -3,7 +3,7 @@
  * inside a civitai.com page, `app.host`. Outside one, `createSignIn()` gets the token.
  */
 export { initialize } from './app/index.js';
-export type { AppClient, BlockAppClient, BlockInitializeOptions, TokenInitializeOptions, } from './app/index.js';
+export type { AppClient, BlockAppClient, BlockInitializeOptions, StorageMode, TokenInitializeOptions, } from './app/index.js';
 export { createSignIn, SignInError } from './sign-in/index.js';
 export type { SignIn, SignInOptions } from './sign-in/index.js';
 export { SCOPES } from './session/index.js';
@@ -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.17.1";
+export declare const VERSION = "0.19.0";

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.17.1";
+export const VERSION = "0.19.0";

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.17.1",
+  "version": "0.19.0",
   "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",