@civitai/app-sdk 0.52.0 → 0.54.0

package/README.md

@@ -87,7 +87,7 @@ over `window.postMessage({ type, payload }, targetOrigin)`, discriminated by
 - **parent → block**: `BLOCK_INIT`, `TOKEN_REFRESH`, `TOKEN_REFRESH_RESPONSE`,
   `ESTIMATE_RESULT`, `WORKFLOW_SUBMITTED`, `WORKFLOW_STATUS`,
   `BUZZ_PURCHASE_RESULT`, `CHECKPOINT_PICKER_RESULT`, `USER_CHECKPOINT_SET`,
-  `APP_STORAGE_*_RESULT`, `SUSPEND`, `RESUME`, `THEME_CHANGE`,
+  `APP_STORAGE_*_RESULT`, `SUSPEND`, `RESUME`, `THEME_CHANGE`, `ROUTE_CHANGED`,
   `CONSENT_UNAVAILABLE` (`ParentToBlockMessage`).
 - **block → parent**: `BLOCK_READY`, `BLOCK_ERROR`, `REQUEST_TOKEN`,
   `RESIZE_IFRAME`, `SUBMIT_WORKFLOW`, `ESTIMATE_WORKFLOW`, `POLL_WORKFLOW`,
@@ -446,7 +446,7 @@ The starters in `civitai/civitai-app-starters` wire this into framework-specific
 
 ## Choosing a workflow step type
 
-The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (50 in total).
+The orchestrator is a workflow API: each request submits a list of typed steps. `WORKFLOW_STEP_TYPES` is the in-code catalog of every step `$type` it accepts, with a one-line description for each — `textToImage`, `imageGen`, `videoGen`, `comfy`, `customComfy`, `textToSpeech`, `aceStepAudio`, `transcription`, `imageUpscaler` among them (51 in total).
 
 The catalog is pinned to the orchestrator's published OpenAPI spec two ways — an offline unit test against a transcribed copy of the spec's `WorkflowStepTemplate` discriminator mapping, and a CI job (`pnpm check:catalogs`) that re-fetches the live spec and diffs it. If a `$type` is listed here, the orchestrator accepts it.
 
@@ -521,15 +521,15 @@ What it exports:
 
 | Export | What |
 |---|---|
-| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 50 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
+| `WorkflowStepTemplates` | `$type` → template type, for 47 of the catalog's 51 step types. Keyed by the WIRE name, which the generated type names don't always match (`model3DPreview` → `Model3dPreviewStepTemplate`). |
 | `WorkflowStepTemplateFor<'videoGen'>` | One step's template. |
 | `WorkflowStepInputFor<'videoGen'>` | One step's `input` shape, without needing the generated `*Input` name. |
 | `AnyWorkflowStepTemplate` | Discriminated union of all 47 mapped templates — `Extract<…, { $type: 'comfy' }>` and exhaustive `switch` work. `@civitai/client`'s base `WorkflowStepTemplate` has `$type` as a bare `string`, so it narrows nothing. |
 | `TypedWorkflowTemplate` | The submit envelope with `steps` narrowed to that union. Pass it straight to `submitWorkflow` / `estimateWorkflow`. |
 
-> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
+> 🔴 **The map is not total over the catalog, and that is the expected state.** `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with no generated template in the pinned `@civitai/client` are `imageScanning`, `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile error for each of them.
 >
-> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (50, 47, 3, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
+> The two surfaces move independently on purpose: the catalog tracks the **live** orchestrator spec (a daily job syncs it), while these types track whatever `@civitai/client` was last published from. So the catalog runs ahead and the client catches up. The gap is never silent — `test/orchestrator/step-templates.test-d.ts` carries it as a `never` ledger plus one `@ts-expect-error` per gap `$type`, and `test/orchestrator/step-count-prose.test.ts` derives all four numbers (51, 47, 4, and the names) from `WORKFLOW_STEP_TYPES` and the map's own AST, then fails if this paragraph or its twin in `src/orchestrator/steps.ts` disagrees by one character.
 
 The generated `*StepTemplate` and `*Input` types are **not** re-exported individually. Using this subpath already requires `@civitai/client` installed, so if you want one by name, import it straight from there — `import type { TextToImageStepTemplate } from '@civitai/client'`.
 
@@ -566,7 +566,7 @@ A `$type` having a type here says nothing about whether you may submit it.
 
 Several of the 47 exist to serve Civitai's own pipelines rather than third-party apps — `modelPickleScan`, `xGuardModeration`, `training`, `comfyNodepackSnapshot`, `qwenImageBench`, the `model*`/`media*` hashing and classification steps. They're in the consumer spec, so they're typed here. They are not an invitation.
 
-Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 50 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
+Note that `WORKFLOW_STEP_TYPES` does **not** mark most of them: of its 51 entries exactly two — `comfyNodepackSnapshot` and `qwenImageBench` — sit under its "Platform internals" heading, and the rest are ordinary documented entries (`webScrape` even carries usage notes). The reason the platform steps are typed anyway is not that the catalog flags them as internal; it's that the catalog *documents* them, so skipping them would make `WorkflowStepTemplateFor<'training'>` a compile error for a step type the SDK documents — which is exactly what is live today for the 3 `$type`s the pinned client cannot type, and is why that gap is spelled out above rather than left to be discovered.
 
 ## Public vs. confidential clients
 

package/dist/blocks/index.d.ts

@@ -77,5 +77,5 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestGood, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/blocks/messages.d.ts

@@ -8,7 +8,7 @@
  * Wire format: `window.postMessage({ type, payload }, targetOrigin)`.
  */
 import type { ColorDomain } from './browsingLevel.js';
-import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult } from './types.js';
 /**
  * Filter params for `GET_BUZZ_TRANSACTIONS`. All optional; the host validates
  * them server-side (they are NEVER trusted for auth — the account is self-bound
@@ -345,6 +345,11 @@ export type ParentToBlockMessage = {
     payload: {
         theme: Theme;
     };
+} | {
+    type: 'ROUTE_CHANGED';
+    payload: {
+        subPath: string;
+    };
 } | {
     type: 'CONSENT_UNAVAILABLE';
     payload: ConsentUnavailablePayload;
@@ -785,7 +790,8 @@ export type BlockToParentMessage = {
     type: 'OPEN_CHECKPOINT_PICKER';
     payload: {
         requestId: string;
-        baseModelGroup: string;
+        /** Optional ecosystem-family filter. Absent ⇒ unconstrained. Never ''. */
+        baseModelGroup?: string;
         /** Currently-selected versionId so the picker can pre-highlight it. */
         currentVersionId?: number;
     };
@@ -814,6 +820,7 @@ export type BlockToParentMessage = {
     type: 'NAVIGATE';
     payload: {
         path: string;
+        scope?: BlockNavigateScope;
         target: 'current' | 'new_tab';
     };
 } | {

package/dist/blocks/types.d.ts

@@ -258,6 +258,28 @@ export type BlockImageScanResult = {
  *    `imageId`/`nsfwLevel`/`contentRating` crosses back into the block.
  */
 export type BlockUploadPurpose = 'display' | 'generationSource';
+/**
+ * Which SPACE a `NAVIGATE` path is resolved in. Mirrors the host's
+ * `NavigateScope` in civitai/civitai's `pageBlockHostLogic.ts`. Keep in lockstep.
+ *
+ *  - `'app'` (DEFAULT): the path is resolved under the block's OWN route
+ *    (`<base>/<slug>/<path>`) and pushed shallowly, so the page stays mounted.
+ *  - `'site'`: the path is resolved at the SITE root, non-shallow, and the viewer
+ *    leaves the app. Granted per-surface — the host refuses it outright on a
+ *    surface that does not hold the capability — and `/api/*` is refused in this
+ *    scope regardless.
+ *
+ * 🔴 ABSENT IS `'app'`, and the host compares against the literal `'site'` rather
+ * than validating against this union, so an UNKNOWN value fails CLOSED onto
+ * `'app'` too. That is what makes the field additive: a block built against an
+ * SDK that predates `scope` sends nothing and keeps the behaviour it always had.
+ *
+ * 🔴 A LEADING SLASH CARRIES NO MEANING. `scope` selects the space and `path` is a
+ * path WITHIN it, so the host normalises leading slashes away:
+ * `{ scope: 'app', path: '/settings' }` and `{ scope: 'app', path: 'settings' }`
+ * are one request. Do not reintroduce punctuation semantics.
+ */
+export type BlockNavigateScope = 'app' | 'site';
 /**
  * The source-image result the host returns from `OPEN_IMAGE_UPLOAD` when the
  * block requested `purpose: 'generationSource'` (`IMAGE_UPLOAD_RESULT.selected`)

package/dist/manifest/defineBlock.js

@@ -90,8 +90,9 @@ export const SCHEMA_DIVERGENCES = {
             'REVIEW IN THE OTHER DIRECTION: `allow-popups`, `allow-modals`, `allow-downloads` and any ' +
             'other token outside {allow-scripts, allow-forms} PASS HERE and may be refused at review. ' +
             'They are not rejected because the tier is assigned server-side during review and is ' +
-            'unknowable locally — `starters/civitai-block-starter` itself ships ' +
-            '"allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox". See ' +
+            'unknowable locally. Every shipped starter and example now declares exactly ' +
+            '"allow-scripts allow-forms", so none of them illustrates this gap any more — the looser ' +
+            'arm is pinned by the synthetic cases in test/manifest/divergences.test.ts instead. See ' +
             'KNOWN_GAPS["tier-dependent-sandbox-allowlist"].',
     },
     scopeJustifications: {

package/dist/orchestrator/index.d.ts

@@ -130,6 +130,8 @@ export declare const WORKFLOW_STEP_TYPES: {
      * `maxDuration` is an upper bound; generation can stop earlier.
      */
     readonly yuE2: "Generate a song from style and lyrics with YuE2";
+    /** Music or a standalone sound effect from a text prompt. */
+    readonly soniloAudioGen: "Music or a sound effect from a text prompt (Sonilo)";
     /** Speech-to-text transcription. */
     readonly transcription: "Speech-to-text transcription";
     /** Generate captions from audio. */

package/dist/orchestrator/index.js

@@ -134,6 +134,8 @@ export const WORKFLOW_STEP_TYPES = {
      * `maxDuration` is an upper bound; generation can stop earlier.
      */
     yuE2: 'Generate a song from style and lyrics with YuE2',
+    /** Music or a standalone sound effect from a text prompt. */
+    soniloAudioGen: 'Music or a sound effect from a text prompt (Sonilo)',
     /** Speech-to-text transcription. */
     transcription: 'Speech-to-text transcription',
     /** Generate captions from audio. */

package/dist/orchestrator/steps.d.ts

@@ -3,7 +3,7 @@
  * own generated client (`@civitai/client`).
  *
  * The sibling `@civitai/app-sdk/orchestrator` module gives you the *catalog*
- * (`WORKFLOW_STEP_TYPES` — 50 `$type` names and what each one does) and the
+ * (`WORKFLOW_STEP_TYPES` — 51 `$type` names and what each one does) and the
  * fetch helpers (`submitWorkflow`, `estimateWorkflow`, …), but its body
  * builders take `input: unknown`. This module is the missing half: the actual
  * per-step input shapes, tracked against the orchestrator's OpenAPI spec by
@@ -70,7 +70,7 @@
  * consumer spec, so they are typed here. They are not an invitation.
  *
  * ⚠️ `WORKFLOW_STEP_TYPES` does NOT mark most of them. Counted at this commit:
- * of its 50 entries, exactly TWO sit under its "Platform internals" heading —
+ * of its 51 entries, exactly TWO sit under its "Platform internals" heading —
  * `comfyNodepackSnapshot` and `qwenImageBench`. `training`, `webScrape`,
  * `xGuardModeration`, `modelPickleScan` and the `model*` / `media*` steps are
  * ordinary documented entries under ordinary headings, and `webScrape` carries
@@ -89,9 +89,9 @@
  * (#315) without anything going red. The measured state, derived rather than
  * typed:
  *
- * `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with
+ * `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with
  * no generated template in the pinned `@civitai/client` are `imageScanning`,
- * `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
+ * `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
  * error for each of them.
  *
  * That gap is EXPECTED and is not a defect in either surface. The catalog
@@ -300,7 +300,7 @@ interface StepTemplateMap {
     xGuardModeration: XGuardModerationStepTemplate;
 }
 /**
- * `$type` → its step-template type, for 47 of the catalog's 50 step types.
+ * `$type` → its step-template type, for 47 of the catalog's 51 step types.
  *
  * Keyed by the WIRE name rather than the generated type name, because the wire
  * name is what you actually have in hand and the generator does not always

package/dist/orchestrator/steps.js

@@ -3,7 +3,7 @@
  * own generated client (`@civitai/client`).
  *
  * The sibling `@civitai/app-sdk/orchestrator` module gives you the *catalog*
- * (`WORKFLOW_STEP_TYPES` — 50 `$type` names and what each one does) and the
+ * (`WORKFLOW_STEP_TYPES` — 51 `$type` names and what each one does) and the
  * fetch helpers (`submitWorkflow`, `estimateWorkflow`, …), but its body
  * builders take `input: unknown`. This module is the missing half: the actual
  * per-step input shapes, tracked against the orchestrator's OpenAPI spec by
@@ -70,7 +70,7 @@
  * consumer spec, so they are typed here. They are not an invitation.
  *
  * ⚠️ `WORKFLOW_STEP_TYPES` does NOT mark most of them. Counted at this commit:
- * of its 50 entries, exactly TWO sit under its "Platform internals" heading —
+ * of its 51 entries, exactly TWO sit under its "Platform internals" heading —
  * `comfyNodepackSnapshot` and `qwenImageBench`. `training`, `webScrape`,
  * `xGuardModeration`, `modelPickleScan` and the `model*` / `media*` steps are
  * ordinary documented entries under ordinary headings, and `webScrape` carries
@@ -89,9 +89,9 @@
  * (#315) without anything going red. The measured state, derived rather than
  * typed:
  *
- * `WORKFLOW_STEP_TYPES` documents 50 `$type`s; this map covers 47. The 3 with
+ * `WORKFLOW_STEP_TYPES` documents 51 `$type`s; this map covers 47. The 4 with
  * no generated template in the pinned `@civitai/client` are `imageScanning`,
- * `preprocessVideo`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
+ * `preprocessVideo`, `soniloAudioGen`, `yuE2`, and `WorkflowStepTemplateFor<…>` is a compile
  * error for each of them.
  *
  * That gap is EXPECTED and is not a defect in either surface. The catalog

package/package.json

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