@civitai/app-sdk 0.74.0 → 0.76.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
 
@@ -407,6 +407,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, 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, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, 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, 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, BlockTrainingDatasetItem, BlockTrainingDatasetResult, 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
@@ -592,6 +607,13 @@ export type ParentToBlockMessage = {
         selectedImages?: BlockPickedImageInfo[];
         error?: string;
     };
+} | {
+    type: 'MEDIA_UPLOAD_RESULT';
+    payload: {
+        requestId: string;
+        selected?: BlockMediaUploadInfo;
+        error?: string;
+    };
 } | {
     type: 'USER_CHECKPOINT_SET';
     payload: {
@@ -973,6 +995,19 @@ export type BlockToParentMessage = {
          */
         publicOnly?: boolean;
     };
+} | {
+    type: 'OPEN_MEDIA_UPLOAD';
+    payload: {
+        requestId: string;
+        /** What kind of media to upload. The host refuses any other value. */
+        kind: BlockMediaKind;
+        /** Required. The only accepted value today. */
+        purpose: 'generationSource';
+        /** In-tab bytes: present = bytes mode (no picker), absent = picker mode. */
+        bytes?: ArrayBuffer;
+        /** Bytes mode only: the type the app believes it is sending; must match the content. */
+        mimeType?: string;
+    };
 } | {
     type: 'SET_USER_CHECKPOINT';
     payload: {
@@ -1194,7 +1229,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", "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", "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"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -79,6 +79,7 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'OPEN_RESOURCE_PICKER',
     'OPEN_IMAGE_UPLOAD',
     'OPEN_IMAGE_PICKER',
+    'OPEN_MEDIA_UPLOAD',
     'SET_USER_CHECKPOINT',
     'NAVIGATE',
     'REQUEST_SIGN_IN',

package/dist/blocks/types.d.ts

@@ -372,6 +372,51 @@ export interface BlockPickedImageInfo {
      */
     imageId?: number;
 }
+/**
+ * What kind of media `OPEN_MEDIA_UPLOAD` (via `useMediaUpload`) uploads. The
+ * host decides the file's real type from its MAGIC BYTES, never from a declared
+ * MIME type, and accepts per kind:
+ *  - `'image'`: PNG, JPEG or WebP;
+ *  - `'video'`: MP4 or WebM;
+ *  - `'audio'`: MP3, WAV or WebM.
+ */
+export type BlockMediaKind = 'image' | 'video' | 'audio';
+/**
+ * One media file the host uploaded for the block as a GENERATION INPUT
+ * (`MEDIA_UPLOAD_RESULT.selected`, via `useMediaUpload`).
+ *
+ * `url` is a PRIVATE generation-input URL: pass it into a workflow step input
+ * (an image, video or audio input). It is not a public Civitai image and has no
+ * `imageId`. The host refuses data URIs and inline
+ * base64 in step inputs, so this is how a block gets media it holds (a picked
+ * file, a canvas, a recording) into a step.
+ *
+ * Per kind:
+ *  - `'image'`: the host RESIZES the picture so both sides are within 64–2048
+ *    pixels and RE-ENCODES it as JPEG. `mimeType` is always `'image/jpeg'`,
+ *    and `sizeBytes`, `width` and `height` describe that JPEG.
+ *  - `'video'`: uploaded as sent. `width` / `height` are always set (the host
+ *    refuses a file with no video track); `durationMs` is set when the browser
+ *    reports a finite duration.
+ *  - `'audio'`: uploaded as sent. No `width` / `height`; `durationMs` as for
+ *    video. A `MediaRecorder` WebM can report no duration, so do not rely on it.
+ */
+export interface BlockMediaUploadInfo {
+    /** The private generation-input URL. Pass it into a step input. */
+    url: string;
+    /** The kind that was requested. */
+    kind: BlockMediaKind;
+    /** The type actually uploaded. Always `'image/jpeg'` for `'image'`. */
+    mimeType: string;
+    /** Bytes actually uploaded (for `'image'`, the re-encoded JPEG's size). */
+    sizeBytes: number;
+    /** Pixel width. Always set for `'image'` and `'video'`; absent for `'audio'`. */
+    width?: number;
+    /** Pixel height. Always set for `'image'` and `'video'`; absent for `'audio'`. */
+    height?: number;
+    /** Duration in milliseconds, for `'video'` / `'audio'` when known. Never set for `'image'`. */
+    durationMs?: number;
+}
 /**
  * One of the model version's curated preview images, with the standard
  * gen params extracted from its source meta. Block UIs use these to let
@@ -1295,8 +1340,14 @@ export type WorkflowBodyPassThroughStep = {
      *
      * Consequently the orchestrator's per-`$type` schema is the ONLY authority for
      * what a given `$type` accepts; nothing in this package or on the host mirrors
-     * it. Bounded only by size: at most **262144 bytes** (256 KB) serialized, which
-     * is a payload-DoS bound and not a shape gate.
+     * it. Its shape is not checked; its size is: at most **262144 bytes** (256 KB)
+     * serialized, which is a payload-DoS bound and not a shape gate.
+     *
+     * 🔴 **No inline media.** The host refuses a `data:image|video|audio` URI or a
+     * long raw base64 string anywhere in here: upload the image, video or audio
+     * with `useMediaUpload()` (an image also works with
+     * `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`)
+     * and pass the returned `url`.
      */
     input: Record<string, unknown>;
     /**

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

@@ -430,11 +430,14 @@ export interface BuildImageGenBodyOptions {
  *
  * @example  Nano Banana 2 with a reference image
  * ```ts
+ * // Pass a hosted image URL, not a data URI or raw base64. In an App Block, the
+ * // `url` from `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`;
+ * // the block host refuses inline media in a step input.
  * const body = buildImageGenBody({
  *   engine: 'google',
  *   model: 'nano-banana-2',
  *   prompt: 'turn this into a cartoon sticker',
- *   images: ['data:image/png;base64,...'],
+ *   images: [source.url],
  *   aspectRatio: '1:1',
  *   numImages: 1,
  *   resolution: '1K',

package/dist/orchestrator/index.js

@@ -393,11 +393,14 @@ export function buildTextToImageBody(input, opts = {}) {
  *
  * @example  Nano Banana 2 with a reference image
  * ```ts
+ * // Pass a hosted image URL, not a data URI or raw base64. In an App Block, the
+ * // `url` from `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`;
+ * // the block host refuses inline media in a step input.
  * const body = buildImageGenBody({
  *   engine: 'google',
  *   model: 'nano-banana-2',
  *   prompt: 'turn this into a cartoon sticker',
- *   images: ['data:image/png;base64,...'],
+ *   images: [source.url],
  *   aspectRatio: '1:1',
  *   numImages: 1,
  *   resolution: '1K',

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.74.0",
+  "version": "0.76.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",