@civitai/app-sdk 0.65.0 → 0.66.0

package/README.md

@@ -140,7 +140,7 @@ interface BlockInitPayload {
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
 | `fetchNestedDocument(opts)` | Embed one of your OWN bundled documents as an iframe `srcdoc`, because a nested `<iframe src>` of your own content **cannot load** — see [Nested documents](#nested-documents) below. `NestedDocumentError` carries a `.code` of `'invalid-url' \| 'http-error' \| 'network-error'`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |
-| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `WorkflowBodyTraining` (+ `AiToolkitTrainingParams`, `BlockTrainingQuote`, `BlockTrainingDatasetItem`, `BlockTrainingDatasetResult` and the `BLOCK_TRAINING_*` bounds), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
+| types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `WorkflowBodyTraining` (+ `AiToolkitTrainingParams`, `BlockTrainingQuote`, `BlockTrainingDatasetItem`, `BlockTrainingDatasetResult` and the `BLOCK_TRAINING_*` bounds), `WorkflowBodyWorkflow` (+ `WorkflowBodyWorkflowStep`, `WorkflowStepRef`, `WithWorkflowStepRefs`, `BlockWorkflowStepSnapshot` and `BLOCK_WORKFLOW_MAX_STEPS`), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
 
 `WorkflowBody`'s `customComfy` member is a discriminated union on `mode`, mirroring
 the host's `blockCustomComfyMemberSchema`. Narrow on the VALUE (`body.mode === 'inline'`),
@@ -221,6 +221,66 @@ and review sessions. The dataset is prepared over `PREPARE_TRAINING_DATASET`
 (civitai/civitai#5438). Use it through `@civitai/blocks-react`'s `usePrepareTrainingDataset()`
 and `useRunTraining()`.
 
+`WorkflowBodyWorkflow` (`kind: 'workflow'`) submits **several orchestrator steps as one
+workflow**, 1 to `BLOCK_WORKFLOW_MAX_STEPS` (8), through the same messages as every other kind.
+A value anywhere in a step's `input` may be a `WorkflowStepRef`
+(`{ $ref, path, default?, format? }`) naming `'$arguments'`, an **earlier** step's `name`, or an
+earlier **unnamed** step by position (`'$0'`). A `name` starts with a lowercase
+letter, uses only lowercase letters, digits, `_` and `-`, and is unique (the exact rule is on
+`WorkflowBodyWorkflowStep.name`). `suppressOutput: true` marks an intermediate step whose
+blobs are not surfaced. There is no `maxBuzz`: the ceiling is the app's per-generation budget × the
+number of steps.
+
+```ts
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+
+const body: WorkflowBody = {
+  kind: 'workflow',
+  arguments: { prompt: 'a lighthouse at dusk' },
+  steps: [
+    {
+      name: 'draw',
+      $type: 'imageGen',
+      input: {
+        engine: 'google',
+        model: 'nano-banana-2',
+        prompt: { $ref: '$arguments', path: 'prompt' },
+      },
+      suppressOutput: true,
+    },
+    {
+      name: 'cutout',
+      $type: 'imageBackgroundRemoval',
+      input: { image: { $ref: 'draw', path: 'output.images[0].url' } },
+    },
+  ],
+};
+```
+
+- 🔴 **The estimate is not a maximum.** The orchestrator re-prices a step once the values it
+  references are known and charges the difference.
+- **A workflow the host cannot price still proceeds**, reserved at the ceiling above — unless it
+  contains a training step (refused without a quote, as on the single-step arm) or a `repeat`
+  step at any depth (also refused without a quote, before any reservation, as
+  `workflow_repeat_unbounded`).
+- **One author fee per workflow**, on the quoted base, itemised as `cost.authorFee` on the
+  estimate. If the workflow bills more, the fee charged is held to the fee shown; a workflow that
+  does not succeed has its whole fee reversed, even if earlier steps delivered output.
+- **`repeat` over `arguments` only, at most 16 iterations** (`BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS`,
+  nested repeats multiplied): `for.$ref` must be `'$arguments'` and `path` must name an array
+  there. A `merge` step's `fields` entries each need a string `$ref` (an earlier step or
+  `$arguments`) and a `reduce`. Repeat children appear in `snapshot.steps` as `<name>.<n>`. The
+  velocity limit counts one unit per step, and a `repeat` one per iteration.
+- `snapshot.steps` reports each step's `status`, `imageUrls`, `output` and `error`. A `failed`
+  workflow can still carry `cost.total > 0` and usable `imageUrls`: steps that succeeded before
+  the failing one stay charged.
+- A refused body carries `snapshot.errorCode`: `workflow_step_denied` (a platform-internal
+  `$type`), `workflow_ref_invalid` (a reference to the step itself, a later step, or nothing, or a
+  step name that breaks the naming rules, or a malformed `repeat`/`merge`),
+  `workflow_repeat_unbounded` (a `repeat` not over an array in `arguments`, or over 16 iterations)
+  or `workflow_too_many_steps`. The single-step pass-through arm refuses `repeat` outright.
+- Requires a host that knows the kind; an older host refuses the body.
+
 ### `defineBlock` validator rules
 
 **There is no rule list here, and that is the point.** `defineBlock` does not

package/dist/blocks/index.d.ts

@@ -109,7 +109,9 @@ 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, 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, BlockEstimateBatchAggregate, BlockModelSubstitution, ModelSubstitutionReason, KnownBlockWorkflowErrorCode, BlockStepToolCall, BlockTrainedEpoch, BlockPublishedModel, 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, WorkflowBodyTraining, AiToolkitTrainingParams, AiToolkitTrainingParamsBase, AiToolkitPlainEcosystem, AiToolkitLrScheduler, AiToolkitOptimizerType, BlockTrainingQuote, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, BlockPrepareTrainingDatasetHostError, BlockRunTrainingHostError, } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockAnalyticsDeclaration, BlockAnalyticsEventDeclaration, BlockAnalyticsPropertyDeclaration, 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, 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, } 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';
 /**
  * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
  * civitai/civitai's zod — see `WorkflowBodyTraining`.

package/dist/blocks/index.js

@@ -108,6 +108,8 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
  * in `types.ts` for which of the two it uses and why.
  */
 export { isSignedIn } 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';
 /**
  * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
  * civitai/civitai's zod — see `WorkflowBodyTraining`.

package/dist/blocks/types.d.ts

@@ -1168,6 +1168,9 @@ export type WorkflowBodyStep = {
  *    checkpoint itself.
  *  - `$type` is bounded to **1…64 characters** and `input` to **262144 bytes**
  *    (256 KB) serialized. Both REJECT; neither truncates.
+ *  - **`repeat` is refused on this arm**, outright: a `repeat` may only
+ *    iterate an array in a body's own `arguments`, and this arm has none. Use
+ *    a `kind: 'workflow'` body ({@link WorkflowBodyWorkflow}) to repeat a step.
  *  - `maxBuzz` is the app's spend knob, and the host's quote can raise the
  *    reservation above it — see its own note below.
  *
@@ -1249,6 +1252,196 @@ export type WorkflowBodyPassThroughStep = {
      */
     maxBuzz: number;
 };
+/**
+ * The most steps one `kind: 'workflow'` body may carry. The host refuses a
+ * longer list with `errorCode: 'workflow_too_many_steps'`; an empty list is
+ * refused too.
+ */
+export declare const BLOCK_WORKFLOW_MAX_STEPS = 8;
+/**
+ * The most times one top-level `repeat` step of a `kind: 'workflow'` body may
+ * run its template, NESTED REPEATS MULTIPLIED (a 4-item repeat inside a 4-item
+ * repeat is 16). The host refuses more with
+ * `errorCode: 'workflow_repeat_unbounded'`.
+ */
+export declare const BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS = 16;
+/**
+ * A REFERENCE inside a `kind: 'workflow'` step's `input` — the orchestrator's
+ * own mechanism for feeding one step's result into a later step. Put it
+ * anywhere a value would go, at any depth.
+ *
+ * `$ref` names where the value comes from:
+ *  - `'$arguments'` — the body's own {@link WorkflowBodyWorkflow.arguments};
+ *  - the `name` of an EARLIER step in the same body;
+ *  - `'$<index>'` — an EARLIER step you did NOT name, by its zero-based
+ *    position (`'$0'` is the first step). A step that has a `name` is
+ *    referenced by that name only.
+ *
+ * An object counts as a reference only when it has BOTH `$ref` and `path` and
+ * no key other than `default` / `format`; anything else is ordinary input.
+ *
+ * `path` selects the value inside that source, e.g. `'output.images[0].url'`
+ * for a step, or `'prompt'` for `$arguments`. The orchestrator resolves it; the
+ * path is not checked by this package or by the host.
+ *
+ * 🔴 A reference may only point BACKWARDS. A step that names itself, a later
+ * step, or a step that does not exist is refused by the host with
+ * `errorCode: 'workflow_ref_invalid'` before anything is priced or reserved.
+ * A body may hold at most 64 references, in inputs nested at most 32 levels.
+ *
+ * `default` is the value used when the path resolves to nothing; `format` is a
+ * template applied to the resolved value. Both are passed to the orchestrator
+ * unmodified.
+ */
+export type WorkflowStepRef = {
+    $ref: '$arguments' | `$${number}` | (string & {});
+    path: string;
+    default?: unknown;
+    format?: string;
+};
+/**
+ * `T` with a {@link WorkflowStepRef} allowed in place of any value, at any
+ * depth. Use it to keep a step input typed while still wiring references in:
+ *
+ * ```ts
+ * type CutoutInput = { image: string; format?: 'png' | 'webp' };
+ * const input: WithWorkflowStepRefs<CutoutInput> = {
+ *   image: { $ref: 'draw', path: 'output.images[0].url' },
+ *   format: 'png',
+ * };
+ * ```
+ */
+export type WithWorkflowStepRefs<T> = WorkflowStepRef | (T extends ReadonlyArray<infer U> ? Array<WithWorkflowStepRefs<U>> : T extends object ? {
+    [K in keyof T]: WithWorkflowStepRefs<T[K]>;
+} : T);
+/** One step of a {@link WorkflowBodyWorkflow}. */
+export type WorkflowBodyWorkflowStep = {
+    /**
+     * What later steps call this one in a {@link WorkflowStepRef}, and the `name`
+     * it reports under on {@link BlockWorkflowSnapshot.steps}. Optional: an
+     * unnamed step is named by its position (`'$0'`, `'$1'`, …).
+     *
+     * A lowercase letter followed by up to 31 of `a-z`, `0-9`, `_` or `-`
+     * (`/^[a-z][a-z0-9_-]{0,31}$/`), unique within the body, and not
+     * `'block-step'`, which is reserved. A name that breaks a rule is refused
+     * with `errorCode: 'workflow_ref_invalid'`.
+     */
+    name?: string;
+    /**
+     * The ORCHESTRATOR step type to run, verbatim — e.g. `'imageGen'`. Not
+     * resolved against any allowlist: it is refused only when it names a
+     * platform-internal type (scanners, moderation classifiers, hashing, web
+     * scrape/search, and the retired `textToImage` step type), with
+     * `errorCode: 'workflow_step_denied'`. 1…64 characters.
+     *
+     * Two step types are read by shape, because they name their sources outside
+     * a {@link WorkflowStepRef}:
+     *  - **`repeat` — over `arguments` only, at most
+     *    {@link BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS} iterations.** Its input must
+     *    be exactly `{ for: { $ref, path, as }, template: { $type, name?, input? } }`
+     *    with `for.$ref === '$arguments'` and `path` naming an ARRAY in the body's
+     *    `arguments`; its length is the iteration count, nested repeats
+     *    multiplied. A repeat over another step's output, a missing or non-array
+     *    path, or too many iterations is refused with
+     *    `errorCode: 'workflow_repeat_unbounded'`; a wrong shape, or repeats nested
+     *    more than 4 deep, with `workflow_ref_invalid`. Inside the template the
+     *    `as` name is a source a reference may name; it may not equal a step name.
+     *    The template's `$type` is held to the denylist too.
+     *  - **`merge`** — every entry of `input.fields` needs a string `$ref` and a
+     *    `reduce`, and each `$ref` must name `$arguments` or an EARLIER step,
+     *    never a repeat variable. Each counts toward the 64-reference cap.
+     *    Otherwise `workflow_ref_invalid`.
+     */
+    $type: string;
+    /**
+     * The step's own input object. Any value in it, at any depth, may be a
+     * {@link WorkflowStepRef}. The orchestrator's per-`$type` schema is the only
+     * authority for what a given `$type` accepts. Every step's `input` plus the
+     * body's `arguments` may total at most 262144 bytes (256 KB) serialized.
+     */
+    input: Record<string, unknown>;
+    /**
+     * `true` marks an INTERMEDIATE step: its blobs are not surfaced, neither on
+     * its own {@link BlockWorkflowStepSnapshot.imageUrls} nor in the top-level
+     * {@link BlockWorkflowSnapshot.imageUrls}. The step still runs and is still
+     * charged.
+     */
+    suppressOutput?: boolean;
+};
+/**
+ * The `workflow` member of {@link WorkflowBody} — SEVERAL orchestrator steps
+ * submitted as ONE workflow, where a later step can consume an earlier step's
+ * result through a {@link WorkflowStepRef}. It travels through the same
+ * messages and hooks as every other kind (`estimate`, `submit`, `watch`,
+ * `cancel`, a batch-estimate cell, `useWorkflowBatch`).
+ *
+ * Between 1 and {@link BLOCK_WORKFLOW_MAX_STEPS} steps. There is no `maxBuzz`:
+ * the spend ceiling is the app's per-generation budget × the number of steps,
+ * enforced by the host. The host's schema is strict: an unknown key on the
+ * body or on a step is rejected, not dropped.
+ *
+ * 🔴 THREE THINGS ABOUT THE PRICE, all of them different from a single-step
+ * body:
+ *  1. **The estimate is NOT a maximum.** When a step's input references an
+ *     earlier step, the orchestrator re-prices that step once the referenced
+ *     values are known and charges the difference. Show the estimate as an
+ *     estimate; never as "you will pay at most".
+ *  2. **A workflow the host cannot price still proceeds.** It is reserved at
+ *     the ceiling above instead of at a quote — unless it contains a training
+ *     step, which is refused without a quote exactly as on the single-step arm
+ *     (a `training-quote-*` `errorCode`), or a `repeat` step at any depth,
+ *     which is refused without a quote too, before any reservation, with
+ *     `errorCode: 'workflow_repeat_unbounded'` — retrying later may succeed.
+ *  3. **One author fee per workflow**, not one per step, computed on the
+ *     QUOTED base. The estimate's `cost.authorFee` is that single fee, already
+ *     inside `cost.total`. If the workflow bills more than the quote, the fee
+ *     charged is held to the fee shown. A workflow that does not succeed has
+ *     its WHOLE fee reversed, even when earlier steps delivered output.
+ *
+ * The app's velocity limit counts one unit per step, and a `repeat` step one
+ * per iteration (nested repeats multiplied) instead of one.
+ *
+ * 🔴 A FAILED WORKFLOW CAN STILL HAVE COST AND IMAGES. Steps that succeeded
+ * before the failing one stay charged, so a `failed` snapshot can carry
+ * `cost.total > 0` and usable `imageUrls`. See {@link BlockWorkflowSnapshot.steps}.
+ *
+ * 🔴 REQUIRES A HOST THAT KNOWS THIS KIND. An older host refuses the body.
+ *
+ * @example An image step whose output a second step consumes.
+ * ```ts
+ * const body: WorkflowBody = {
+ *   kind: 'workflow',
+ *   arguments: { prompt: 'a lighthouse at dusk' },
+ *   steps: [
+ *     {
+ *       name: 'draw',
+ *       $type: 'imageGen',
+ *       input: {
+ *         engine: 'google',
+ *         model: 'nano-banana-2',
+ *         prompt: { $ref: '$arguments', path: 'prompt' },
+ *       },
+ *       suppressOutput: true,
+ *     },
+ *     {
+ *       name: 'cutout',
+ *       $type: 'imageBackgroundRemoval',
+ *       input: { image: { $ref: 'draw', path: 'output.images[0].url' } },
+ *     },
+ *   ],
+ * };
+ * ```
+ */
+export type WorkflowBodyWorkflow = {
+    kind: 'workflow';
+    /** The steps, in order. 1…{@link BLOCK_WORKFLOW_MAX_STEPS}. */
+    steps: WorkflowBodyWorkflowStep[];
+    /**
+     * Values the steps can read through `{ $ref: '$arguments', path }` — one
+     * place to put a prompt or a seed that several steps share.
+     */
+    arguments?: Record<string, unknown>;
+};
 /** Ceiling on what ONE confirmed `kind: 'training'` run may cost, in Buzz. Host constant `BLOCK_TRAINING_MAX_BUZZ_PER_RUN`. */
 export declare const BLOCK_TRAINING_MAX_BUZZ_PER_RUN = 5000;
 /** Max images in one prepared training dataset. Host constant `BLOCK_TRAINING_DATASET_MAX_ITEMS`. */
@@ -1431,6 +1624,10 @@ export interface WorkflowBodyTraining {
  *    on a server-prepared dataset of the viewer's own images. 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
+ *    {@link BLOCK_WORKFLOW_MAX_STEPS} orchestrator steps submitted as one
+ *    workflow, a later step consuming an earlier one's result through a
+ *    {@link WorkflowStepRef}. Its estimate is not a maximum — read its doc.
  *
  * `kind: 'step'` is therefore itself a union, discriminated on the PRESENCE of
  * `step` — the same nesting {@link WorkflowBodyCustomComfy} has on `mode`.
@@ -1447,7 +1644,7 @@ export interface WorkflowBodyTraining {
  * over `kind`. Host code that must handle every member gets a compile error
  * pointing at the new one, which is the intended behaviour.
  */
-export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep | WorkflowBodyTraining;
+export type WorkflowBody = WorkflowBodyTextToImage | WorkflowBodyCustomComfy | WorkflowBodyStep | WorkflowBodyPassThroughStep | WorkflowBodyTraining | WorkflowBodyWorkflow;
 /**
  * The host-mediated view of an orchestrator workflow that an iframe block
  * receives over `postMessage`.
@@ -1487,6 +1684,9 @@ export interface BlockWorkflowSnapshot {
          *   orchestrator price quote, which refuses before any fee is looked up; and
          *   the kinds that price no fee (`customComfy`, pass-through `step`,
          *   `training`). **Do not read absent as `0`** — show `total` on its own.
+         *
+         * A `kind: 'workflow'` estimate itemises it too, and it is ONE fee for the
+         * whole workflow however many steps it has.
          */
         authorFee?: number;
     };
@@ -1507,6 +1707,8 @@ export interface BlockWorkflowSnapshot {
      * (which rejects with `WorkflowSubmitError`, before anything is reserved or
      * charged), and to that body's cell in a batch estimate. Read it from the
      * error's `.snapshot.errorCode`. The `kind: 'training'` arm does NOT set it.
+     * A refused `kind: 'workflow'` body ({@link WorkflowBodyWorkflow}) sets it in
+     * the same shape, on the same three replies.
      *
      * The values the host sends today ({@link KnownBlockWorkflowErrorCode}):
      *  - `'training-quote-rejected'` — the orchestrator refused the request
@@ -1515,6 +1717,21 @@ export interface BlockWorkflowSnapshot {
      *  - `'training-quote-unavailable'` — no usable answer (an outage, a timeout,
      *    a rate limit, insufficient funds, …). Retrying later may succeed.
      *  - `'training-quote-unpriced'` — the orchestrator answered without a price.
+     *  - `'workflow_step_denied'` — a step of a `kind: 'workflow'` body names a
+     *    platform-internal `$type`. Remove or replace that step.
+     *  - `'workflow_ref_invalid'` — a {@link WorkflowStepRef} in a step's `input`
+     *    points at the step itself, a later step, or nothing; or a step `name`
+     *    breaks the naming rules (see {@link WorkflowBodyWorkflowStep.name}).
+     *    `error` names the step by its position.
+     *  - `'workflow_too_many_steps'` — more than
+     *    {@link BLOCK_WORKFLOW_MAX_STEPS} steps.
+     *  - `'workflow_repeat_unbounded'` — a `repeat` step iterates something other
+     *    than an array in the body's `arguments`, or more than
+     *    {@link BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS} times, nested repeats
+     *    multiplied; or the workflow has a `repeat` and the host could get no
+     *    price quote for it (`error` then reads `… a workflow with a repeat needs
+     *    a price quote and none could be obtained; try again`, and a retry may
+     *    succeed).
      *
      * 🔴 AN UNKNOWN VALUE IS POSSIBLE: the host may add codes, and the SDK's
      * inbound validator accepts any string here. Handle an unrecognised code as a
@@ -1722,6 +1939,48 @@ export interface BlockWorkflowSnapshot {
      * that predate civitai/civitai#5434.
      */
     trainingQuote?: BlockTrainingQuote;
+    /**
+     * The steps of a `kind: 'workflow'` run ({@link WorkflowBodyWorkflow}), in
+     * the orchestrator's order, each with its own status and results. The steps a
+     * `repeat` step generates follow it, named `<repeat name>.<n>`, so the list
+     * can be longer than the body's.
+     *
+     * The top-level fields keep their meaning: `status` is the workflow's,
+     * `imageUrls` is the union of every step that did NOT set `suppressOutput`,
+     * and `cost` is the whole workflow's.
+     *
+     * 🔴 A `failed` WORKFLOW IS NOT AN EMPTY ONE. Steps that succeeded before the
+     * failing step stay charged and keep their results, so a snapshot with
+     * `status: 'failed'` can carry `cost.total > 0` and usable `imageUrls`. Read
+     * `steps` to see which step failed (`status: 'failed'`, with its `error`)
+     * and which finished.
+     *
+     * Read it from the poll and cancel replies of a `kind: 'workflow'` run; do
+     * not rely on it being on the submit reply. ABSENT for every other kind, on
+     * an estimate (which creates no workflow) and on a host that predates it.
+     */
+    steps?: BlockWorkflowStepSnapshot[];
+}
+/** One entry of {@link BlockWorkflowSnapshot.steps}. */
+export interface BlockWorkflowStepSnapshot {
+    /** The step's `name` from the body, or the name the host gave an unnamed step. */
+    name: string;
+    /** The orchestrator step type that ran. */
+    $type: string;
+    status: 'pending' | 'processing' | 'succeeded' | 'failed' | 'expired' | 'canceled';
+    /**
+     * This step's own image urls. Omitted when it has none, and always omitted
+     * for a step submitted with `suppressOutput: true`.
+     */
+    imageUrls?: string[];
+    /**
+     * The step's raw orchestrator output, minus its blobs — the same treatment
+     * and the same caveats as {@link BlockWorkflowSnapshot.stepOutputs}: its shape
+     * is whatever the orchestrator returns for that `$type`, and it is UNSCANNED.
+     */
+    output?: unknown;
+    /** Why this step failed. Diagnostic text; do not render it verbatim. */
+    error?: string;
 }
 /**
  * The run total a BATCH estimate reports beside its per-cell snapshots
@@ -1781,7 +2040,7 @@ export type ModelSubstitutionReason = 'wrong-workflow' | 'unrecognized' | 'gated
  * and the SDK's inbound validator accepts any string. Handle an unrecognised
  * code as a generic failure.
  */
-export type KnownBlockWorkflowErrorCode = 'training-quote-rejected' | 'training-quote-unavailable' | 'training-quote-unpriced';
+export type KnownBlockWorkflowErrorCode = 'training-quote-rejected' | 'training-quote-unavailable' | 'training-quote-unpriced' | 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded';
 /** One entry of {@link BlockWorkflowSnapshot.modelSubstitutions}. */
 export interface BlockModelSubstitution {
     /** The checkpoint version id the block asked for. */

package/dist/blocks/types.js

@@ -115,6 +115,22 @@ export function isSignedIn(viewer) {
     return viewer !== null && viewer !== undefined;
 }
 // ============================================================
+// App Blocks MULTI-STEP kind (`kind: 'workflow'`)
+// ============================================================
+/**
+ * The most steps one `kind: 'workflow'` body may carry. The host refuses a
+ * longer list with `errorCode: 'workflow_too_many_steps'`; an empty list is
+ * refused too.
+ */
+export const BLOCK_WORKFLOW_MAX_STEPS = 8;
+/**
+ * The most times one top-level `repeat` step of a `kind: 'workflow'` body may
+ * run its template, NESTED REPEATS MULTIPLIED (a 4-item repeat inside a 4-item
+ * repeat is 16). The host refuses more with
+ * `errorCode: 'workflow_repeat_unbounded'`.
+ */
+export const BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS = 16;
+// ============================================================
 // App Blocks TRAINING kind (`kind: 'training'`)
 // ============================================================
 //

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
- *    160 symbols and that side effect into the root would make every OAuth app
+ *    167 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 160 is ASSERTED, not merely quoted — by
+ *    🔴 That 167 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
- *    160 symbols and that side effect into the root would make every OAuth app
+ *    167 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 160 is ASSERTED, not merely quoted — by
+ *    🔴 That 167 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/package.json

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