@civitai/app-sdk 0.65.1 → 0.67.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`), `BlockStepQuote` / `BlockRunConfirmedStepHostError` (+ `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`, `BLOCK_STEP_QUOTE_ID_REGEX`), `BlockModel3dOutput`, `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'`),
@@ -209,6 +209,46 @@ const body: WorkflowBody = {
 };
 ```
 
+**Above the per-call budget: a confirmed step.** A pass-through job the per-call budget refuses
+can still run when the **viewer confirms its exact price** in Civitai's own dialog
+(civitai/civitai#5786). When the orchestrator quotes a **fixed** price (positive, not variable
+or metered) above the token's per-call budget and at most `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`
+(5,000), the `estimate` reply carries `snapshot.stepQuote` (`quoteId`, `total`, `stepType`,
+`expiresAt`). Send the same body back with that `quoteId` on the `RUN_CONFIRMED_STEP` bridge
+(`CONFIRMED_STEP_RESULT`); a `quoteId` body sent as an ordinary submit is refused. A quote is
+single-use and expires after 15 minutes. Only a **single** estimate carries `stepQuote` — a
+batch estimate stores nothing, so its cells never do. Where a quote would be granted, the
+estimate **fails instead** (`{ workflowId: 'failed', status: 'failed', error }`) for a training
+`$type` in any casing (`a training step type cannot run as a confirmed step — use kind:'training'`) and for an
+`input` that is not plain JSON (`a confirmed step needs plain JSON input (objects, arrays,
+strings, finite numbers, booleans, null) — <path> is <what>`; the suffix varies, so match on
+the text before the dash). Each confirmation is its own job, so a
+`submission-unconfirmed` result — the outcome is unknown — must never be retried automatically:
+a retry is a new, separately charged job. Page apps only, `ai:write:budgeted`, behind the host
+flag `app-blocks-confirmed-step` (off by default), and refused for development, dev-tunnel and
+review tokens — so it is exercised against the mock host, not `dev:live`. Use it through
+`@civitai/blocks-react`'s `useRunConfirmedStep()`.
+
+**3D outputs.** A step that produces 3D models (`polyGen`) still lists every model url in
+`snapshot.imageUrls`; `snapshot.model3dOutputs` (and the same field on an `AppWorkflow` row)
+labels them. Omitted when there are none.
+
+```ts
+import type { BlockModel3dOutput, BlockWorkflowSnapshot } from '@civitai/app-sdk/blocks';
+
+// `format` is the model's file format; `variant` is the output it came from.
+function pickModel(
+  snapshot: BlockWorkflowSnapshot,
+  format: string,
+  variant: string,
+): BlockModel3dOutput | undefined {
+  return snapshot.model3dOutputs?.find((m) => m.format === format && m.variant === variant);
+}
+
+const mesh = pickModel(snapshot, 'glb', 'model');
+const rigged = pickModel(snapshot, 'fbx', 'riggedFbxModel');
+```
+
 `WorkflowBodyTraining` (`kind: 'training'`) is the **quoted** way to train: an ai-toolkit LoRA
 run on a dataset Civitai prepared from the viewer's own images, mirroring the host's
 `blockTrainingBodySchema` (civitai/civitai#5434). There is no `maxBuzz` and no timeout — the
@@ -221,6 +261,71 @@ 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 has no estimate, but its submit still proceeds.** The
+  estimate (and a batch-estimate cell) fails with no `cost` and `snapshot.errorCode`
+  `workflow_quote_rejected` (the orchestrator refused the body; the same body will fail again),
+  `workflow_quote_unavailable` (no usable answer; the one a retry can clear) or
+  `workflow_quote_unpriced` (an answer without a price). The submit of the same body is reserved
+  at the ceiling above — unless it contains a training step (refused without a quote on both, as
+  on the single-step arm) or a `repeat` step at any depth (also refused on both, before any
+  reservation, as `workflow_repeat_unbounded`; its `error` states the cause). An older host
+  returns the ceiling as the estimate's `cost.total` instead of failing.
+- **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 a `repeat` with no price quote) 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,14 @@ 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, 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';
+/**
+ * Host bounds for a viewer-confirmed pass-through step, mirrored from
+ * civitai/civitai — see `BlockWorkflowSnapshot.stepQuote`.
+ */
+export { BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB, BLOCK_STEP_QUOTE_ID_REGEX } 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,13 @@ 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 a viewer-confirmed pass-through step, mirrored from
+ * civitai/civitai — see `BlockWorkflowSnapshot.stepQuote`.
+ */
+export { BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB, BLOCK_STEP_QUOTE_ID_REGEX } from './types.js';
 /**
  * Host bounds for the App Blocks `kind: 'training'` flow, mirrored from
  * civitai/civitai's zod — see `WorkflowBodyTraining`.

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, BlockNavigateScope, BlockContext, BlockSettings, Theme, ViewerInfo, WorkflowBody, BlockWorkflowSnapshot, BlockEstimateBatchAggregate, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostResult, BlockTrainingDatasetItem, BlockTrainingDatasetResult, WorkflowBodyTraining } from './types.js';
+import type { BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, 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';
 /**
  * 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
@@ -508,6 +508,13 @@ export type ParentToBlockMessage = {
         snapshot?: BlockWorkflowSnapshot;
         error?: string;
     };
+} | {
+    type: 'CONFIRMED_STEP_RESULT';
+    payload: {
+        requestId: string;
+        snapshot?: BlockWorkflowSnapshot;
+        error?: string;
+    };
 } | {
     type: 'IMAGES_RESULT';
     payload: {
@@ -846,6 +853,12 @@ export type BlockToParentMessage = {
         requestId: string;
         body: WorkflowBodyTraining;
     };
+} | {
+    type: 'RUN_CONFIRMED_STEP';
+    payload: {
+        requestId: string;
+        body: WorkflowBodyPassThroughStep;
+    };
 } | {
     type: 'GET_IMAGES_BY_IDS';
     payload: {
@@ -1093,7 +1106,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", "GET_IMAGES_BY_IDS", "CANCEL_APP_WORKFLOW", "OPEN_CHECKPOINT_PICKER", "OPEN_RESOURCE_PICKER", "OPEN_IMAGE_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"];
+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", "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"];
 /**
  * The bucket a message type falls into when the protocol does not declare it.
  *

package/dist/blocks/messages.js

@@ -72,6 +72,7 @@ export const BLOCK_TO_PARENT_MESSAGE_TYPES = [
     'CREATE_POST_FROM_APP',
     'PREPARE_TRAINING_DATASET',
     'RUN_TRAINING',
+    'RUN_CONFIRMED_STEP',
     'GET_IMAGES_BY_IDS',
     'CANCEL_APP_WORKFLOW',
     'OPEN_CHECKPOINT_PICKER',

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.
  *
@@ -1248,6 +1251,237 @@ export type WorkflowBodyPassThroughStep = {
      * viewer as a maximum.
      */
     maxBuzz: number;
+    /**
+     * The viewer-confirmable quote this job is charged against —
+     * {@link BlockStepQuote.quoteId} from this body's own estimate
+     * (`sq_` + 32 lowercase hex characters, {@link BLOCK_STEP_QUOTE_ID_REGEX}).
+     *
+     * OMIT it everywhere except a CONFIRMED run: an estimate never carries it,
+     * and neither does an ordinary submit. It is REQUIRED on
+     * `RUN_CONFIRMED_STEP` (`useRunConfirmedStep()` in `@civitai/blocks-react`),
+     * the only message that can run a job priced above the token's per-call
+     * budget — see {@link BlockWorkflowSnapshot.stepQuote} for the flow.
+     *
+     * 🔴 A body carrying it is NOT runnable through `SUBMIT_WORKFLOW`. The server
+     * charges a confirmed job only against a quote the viewer confirmed in
+     * Civitai's own dialog from a signed-in session, so the same body sent as a
+     * plain submit is refused. Change nothing else in the body between the
+     * estimate and the run: the server checks it against the quoted one
+     * (`quoteId` itself is excluded from that comparison).
+     */
+    quoteId?: string;
+};
+/**
+ * Ceiling on what ONE viewer-confirmed pass-through job may cost, in Buzz. Host
+ * constant `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`. A fixed price above it gets
+ * no {@link BlockWorkflowSnapshot.stepQuote} and cannot be run from an app.
+ */
+export declare const BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB = 5000;
+/**
+ * The shape of a confirmed-step quote id ({@link BlockStepQuote.quoteId}): `sq_`
+ * followed by 32 lowercase hex characters. Host constant
+ * `BLOCK_STEP_QUOTE_ID_REGEX`. Disjoint from the training quote's `tq_` shape,
+ * so neither kind's id can name the other's quote.
+ */
+export declare const BLOCK_STEP_QUOTE_ID_REGEX: RegExp;
+/**
+ * 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 has no estimate, but its submit still
+ *     proceeds.** `estimate()` (and that body's cell in a batch estimate) FAILS
+ *     with no `cost` and `errorCode` `'workflow_quote_rejected'`,
+ *     `'workflow_quote_unavailable'` or `'workflow_quote_unpriced'` — see
+ *     {@link BlockWorkflowSnapshot.errorCode} for which of them a retry can
+ *     clear. `submit()` of the same body is NOT refused: it is reserved at the
+ *     ceiling above instead of at a quote. So a failed estimate does not predict
+ *     a refused submit. Two exceptions are refused on BOTH, before any
+ *     reservation: a workflow containing a training step, exactly as on the
+ *     single-step arm (a `training-quote-*` `errorCode`), and one with a
+ *     `repeat` step at any depth (`errorCode: 'workflow_repeat_unbounded'`).
+ *     Their `error` states the cause; only "none could be obtained; try again"
+ *     is one a retry of the same body can clear.
+ *     (An OLDER host returns the ceiling as the estimate's `cost.total` instead
+ *     of failing, so there a total equal to the ceiling may be unpriced.)
+ *  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;
@@ -1431,6 +1665,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 +1685,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 +1725,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;
     };
@@ -1500,13 +1741,21 @@ export interface BlockWorkflowSnapshot {
      *
      * WHERE IT APPEARS today: the refusal for a pass-through `step` body
      * ({@link WorkflowBodyPassThroughStep}) whose `$type` is a training type
-     * (`'training'` or `'imageResourceTraining'`) when the host could not get a
+     * (`'training'` or `'imageResourceTraining'`, in any casing — the host
+     * compares `$type` case-insensitively) when the host could not get a
      * price quote for it. That refusal is `{ workflowId: 'failed', status:
      * 'failed', error, errorCode }` with no `cost`, and it is the reply to
      * `estimate()` (which rejects with `WorkflowEstimateError`), to `submit()`
      * (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.
+     * error's `.snapshot.errorCode`. A `kind: 'training'` ESTIMATE does not set
+     * it. The confirmed SUBMIT of a training run or a confirmed step can — see
+     * `'daily-limit-exceeded'` below.
+     * A refused `kind: 'workflow'` body ({@link WorkflowBodyWorkflow}) sets it in
+     * the same shape, on the same three replies — except the three
+     * `workflow_quote_*` codes, which are ESTIMATE-ONLY (`estimate()` and a
+     * batch-estimate cell): `submit()` of the same body defines no such refusal
+     * and proceeds, reserved at the ceiling.
      *
      * The values the host sends today ({@link KnownBlockWorkflowErrorCode}):
      *  - `'training-quote-rejected'` — the orchestrator refused the request
@@ -1515,6 +1764,50 @@ 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.
+     *  - `'daily-limit-exceeded'` — a viewer-confirmed job (a `kind: 'training'`
+     *    run or a confirmed step) would exceed what remains today of the daily
+     *    Buzz limit THE VIEWER set for this app. Nothing was charged and no job
+     *    was started; the confirm cannot override it, and only the viewer can
+     *    raise the limit. This one arrives on the failed snapshot a confirmed
+     *    SUBMIT resolves (`{ workflowId: 'failed', status: 'failed', cost, error,
+     *    errorCode }`), not on an estimate. On a confirmed step the host also
+     *    reports it as the `error` code of `CONFIRMED_STEP_RESULT` — see
+     *    {@link BlockRunConfirmedStepHostError}.
+     *  - `'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 has no price
+     *    quote for it. `error` then reads `workflow step N: a workflow with a
+     *    repeat needs a price quote and <cause>`, where `<cause>` is one of the
+     *    three in the `workflow_quote_*` messages below. A retry of the same body
+     *    can succeed only when the cause is `none could be obtained; try again`;
+     *    otherwise the body is what has to change.
+     *  - `'workflow_quote_rejected'` — ESTIMATE only. The orchestrator refused
+     *    the body, so there is no price to show; resending the same body will not
+     *    help. `error` reads `No price quote for this workflow: the orchestrator
+     *    rejected the request: <reason>` when the reason is safe to show, else
+     *    `No price quote for this workflow: the orchestrator rejected the request;
+     *    check the step inputs and references (retrying the same body will not
+     *    help)`.
+     *  - `'workflow_quote_unavailable'` — ESTIMATE only. No usable answer (an
+     *    outage, a timeout, a rate limit, …). The one `workflow_quote_*` code a
+     *    retry of the same body can clear. `error` reads `No price quote for this
+     *    workflow: none could be obtained; try again`.
+     *  - `'workflow_quote_unpriced'` — ESTIMATE only. The orchestrator answered
+     *    without a price. `error` reads `No price quote for this workflow: the
+     *    orchestrator answered without one`.
+     *
+     * Each `workflow_quote_*` reply is `{ workflowId: 'failed', status: 'failed',
+     * error, errorCode }` with NO `cost`. A host that predates these codes
+     * resolves the estimate instead, with the spend ceiling as `cost.total`.
      *
      * 🔴 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 +2015,126 @@ export interface BlockWorkflowSnapshot {
      * that predate civitai/civitai#5434.
      */
     trainingQuote?: BlockTrainingQuote;
+    /**
+     * The viewer-confirmable quote a pass-through `step` ESTIMATE
+     * ({@link WorkflowBodyPassThroughStep}) produced, when the job costs more than
+     * the app may spend without asking. Its presence means: this job cannot run
+     * through `submit()`, and CAN run through `useRunConfirmedStep()` once the
+     * viewer confirms `stepQuote.total` in Civitai's own dialog.
+     *
+     * THE FLOW, mirroring a training run's:
+     *  1. `useBuzzWorkflow().estimate(body)` — the reply carries `stepQuote`.
+     *  2. `useRunConfirmedStep().runConfirmedStep({ ...body, quoteId:
+     *     stepQuote.quoteId })` — Civitai shows the viewer the price (read back
+     *     from the server, never from the body) and submits on their confirm.
+     *  3. `useBuzzWorkflow().watch(snapshot.workflowId)`.
+     *
+     * WHEN THE HOST SENDS IT — all of these, decided server-side:
+     *  - the orchestrator quoted a **FIXED** price for exactly this step:
+     *    positive, and not a variable or metered one. The viewer confirms what
+     *    they are charged, so a price that may move is never confirmable;
+     *  - that price is ABOVE the token's per-call budget and at most
+     *    {@link BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB} (5,000 Buzz);
+     *  - the block runs in a page app for a signed-in viewer on an ordinary
+     *    token. Development, dev-tunnel and review sessions never get one, and
+     *    neither does the model slot.
+     * Everywhere else the field is ABSENT and the estimate is exactly what it was.
+     * Absent is therefore not an error — it is also what every host that
+     * predates civitai/civitai#5786 sends.
+     *
+     * 🔴 ONLY A SINGLE ESTIMATE CARRIES IT. A batch estimate
+     * (`ESTIMATE_WORKFLOW_BATCH`, `useBatchEstimate()`) stores nothing, so its
+     * cells never have a `stepQuote`, whatever they cost. Price a grid in a batch,
+     * then estimate the one body you want to run on its own.
+     *
+     * 🔴 TWO BODIES MAKE THAT ESTIMATE FAIL INSTEAD OF RETURNING A PRICE — only
+     * where a quote would otherwise have been granted (so not below the budget,
+     * and not in a batch). The reply is the failure snapshot `{ workflowId:
+     * 'failed', status: 'failed', error }`, which `estimate()` rejects with; the
+     * same text arrives as `CONFIRMED_STEP_RESULT`'s `error` if such a body is
+     * run. Neither has an {@link BlockWorkflowSnapshot.errorCode}; they are
+     * server messages, so match on the text and keep a generic branch:
+     *  - `a training step type cannot run as a confirmed step — use
+     *    kind:'training'` — `$type` is `training` or `imageResourceTraining`, in
+     *    any casing.
+     *    Training has its own kind ({@link WorkflowBodyTraining}).
+     *  - `a confirmed step needs plain JSON input (objects, arrays, strings,
+     *    finite numbers, booleans, null) — <path> is <what>` — `input` holds a
+     *    `Date`, `Map`, `Set`, class instance, `BigInt`, `NaN`/`Infinity`, an
+     *    `undefined` array element or an empty slot in a sparse array
+     *    (`… — body.input.list[1] is an empty array slot`). The quote is bound to the exact body, so the
+     *    body must be exactly representable. The part after the dash names the
+     *    offending path (`body.input.when is a Date`) and varies: match on the
+     *    text BEFORE the dash.
+     *
+     * `total` is the price the viewer confirms and is charged. 🔴 It can differ
+     * from `cost.total` on the same snapshot, which stays what an UNCONFIRMED
+     * submit would reserve (`max(maxBuzz, quote)`); show `stepQuote.total` on a
+     * confirm button. `expiresAt` is an ISO-8601 timestamp 15 minutes out; after
+     * it the run is refused and you estimate again. A quote is single-use.
+     */
+    stepQuote?: BlockStepQuote;
+    /**
+     * What each 3D model in {@link BlockWorkflowSnapshot.imageUrls} IS — one label
+     * per model a pass-through step produced (e.g. `polyGen`).
+     *
+     * Every model url is still listed in `imageUrls`, unchanged and in the same
+     * order as before the field existed; this only says which entry is which.
+     * Match on `url`:
+     *
+     * ```ts
+     * const glb = snapshot.model3dOutputs?.find(
+     *   (m) => m.format === 'glb' && m.variant === 'model',
+     * );
+     * if (glb) viewer.load(glb.url);
+     * ```
+     *
+     * OMITTED when the workflow produced no 3D model, and on hosts that predate
+     * civitai/civitai#5786 — in which case `imageUrls` is all there is.
+     */
+    model3dOutputs?: BlockModel3dOutput[];
+    /**
+     * 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
@@ -1755,6 +2168,42 @@ export interface BlockTrainingQuote {
     /** ISO-8601. The quote cannot be run after this. */
     expiresAt: string;
 }
+/** {@link BlockWorkflowSnapshot.stepQuote}. */
+export interface BlockStepQuote {
+    /**
+     * `sq_` + 32 lowercase hex characters ({@link BLOCK_STEP_QUOTE_ID_REGEX}).
+     * Opaque — pass it back verbatim as the body's `quoteId`.
+     */
+    quoteId: string;
+    /** The exact price the viewer confirms and is charged, in Buzz. */
+    total: number;
+    /** The orchestrator `$type` that was priced — the body's own `$type`. */
+    stepType: string;
+    /** ISO-8601. The quote cannot be run after this. */
+    expiresAt: string;
+}
+/**
+ * One entry of {@link BlockWorkflowSnapshot.model3dOutputs} /
+ * {@link AppWorkflow.model3dOutputs} — the label for one 3D model url.
+ */
+export interface BlockModel3dOutput {
+    /** The model's url. Also present in the snapshot's `imageUrls` (an `AppWorkflow`'s `images`). */
+    url: string;
+    /**
+     * The model's own file format as the orchestrator reports it — `'glb'`,
+     * `'fbx'`, …. An open set: compare against the formats your viewer loads and
+     * ignore the rest.
+     */
+    format: string;
+    /**
+     * Which output of the step this model is: the output field it came from,
+     * dot-joined when nested — `'model'`, `'riggedFbxModel'`,
+     * `'basicAnimations.walkingModel'`, …. An array index is a segment
+     * (`'models.0'`), and it is `''` when the step's whole output is the model.
+     * The names are the orchestrator's, per `$type`; nothing here lists them.
+     */
+    variant: string;
+}
 /**
  * Why the host substituted a checkpoint version — see
  * {@link BlockWorkflowSnapshot.modelSubstitutions}.
@@ -1781,7 +2230,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' | 'daily-limit-exceeded' | 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded' | 'workflow_quote_rejected' | 'workflow_quote_unavailable' | 'workflow_quote_unpriced';
 /** One entry of {@link BlockWorkflowSnapshot.modelSubstitutions}. */
 export interface BlockModelSubstitution {
     /** The checkpoint version id the block asked for. */
@@ -2437,6 +2886,13 @@ export interface AppWorkflow {
      * absence as "unknown", not as "no checkpoint".
      */
     trainedEpochs?: BlockTrainedEpoch[];
+    /**
+     * Labels for the 3D models among this workflow's {@link AppWorkflow.images} —
+     * same shape and rule as {@link BlockWorkflowSnapshot.model3dOutputs}: every
+     * labelled `url` is also an entry of `images`, and the field is OMITTED when
+     * there are none (and on hosts that predate it).
+     */
+    model3dOutputs?: BlockModel3dOutput[];
 }
 /**
  * Per-viewer gated projection of ONE image returned by `GET_IMAGES_BY_IDS`
@@ -2754,5 +3210,37 @@ export type BlockPrepareTrainingDatasetHostError = 'review-mode' | 'block is not
  *   run is a SECOND, separately charged run.
  */
 export type BlockRunTrainingHostError = 'review-mode' | 'block is not ready' | 'sign in to train' | 'invalid training request' | 'no block token' | 'declined' | 'submission-unconfirmed';
+/**
+ * The HOST'S OWN refusal codes on a `CONFIRMED_STEP_RESULT`'s `error`. Mirrors
+ * civitai/civitai's `RUN_CONFIRMED_STEP_HOST_ERRORS`
+ * (`src/components/AppBlocks/runConfirmedStepGate.ts`, civitai/civitai#5786).
+ *
+ * 🔴 THE SET A BLOCK MAY RELY ON, NOT THE SET IT MAY RECEIVE: server messages
+ * (an expired or already-used quote, a body that differs from the quoted one, a
+ * price that changed, `confirmed steps from apps are not enabled`) arrive
+ * verbatim in the same field.
+ *
+ * - `review-mode` — a mod-review sandbox with "run for real" off.
+ * - `block is not ready` — the host handshake has not completed.
+ * - `sign in to run` — anonymous viewer; there is no account to charge.
+ * - `invalid confirmed step request` — the body is not a pass-through
+ *   `kind: 'step'` body naming an `sq_`-shaped `quoteId`.
+ * - `no block token` — the host holds no block token yet.
+ * - `declined` — the viewer dismissed the confirm. 🔴 GUARANTEED to mean NO JOB
+ *   WAS SUBMITTED. The quote is untouched and can still be run before it
+ *   expires.
+ * - `daily-limit-exceeded` — the job would exceed what remains today of the
+ *   daily Buzz limit the VIEWER set for this app. NO job was submitted and
+ *   nothing was charged. The host has already told the viewer, in its own
+ *   chrome, and pointed them at where to raise the limit; there is no confirm
+ *   to click and nothing the app can do about it. Do not retry.
+ * - `submission-unconfirmed` — the submit was SENT but its outcome is unknown.
+ *   🔴 The job MAY BE RUNNING AND CHARGED. Every confirmation is its own job,
+ *   so a retry (which needs a new estimate and a new confirmation) starts a
+ *   SECOND, separately charged job if the first one did start. Check the
+ *   viewer's generations (`useAppWorkflows()`) before offering one, and never
+ *   retry automatically.
+ */
+export type BlockRunConfirmedStepHostError = 'review-mode' | 'block is not ready' | 'sign in to run' | 'invalid confirmed step request' | 'no block token' | 'declined' | 'daily-limit-exceeded' | 'submission-unconfirmed';
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/blocks/types.js

@@ -115,6 +115,38 @@ export function isSignedIn(viewer) {
     return viewer !== null && viewer !== undefined;
 }
 // ============================================================
+// Confirmed steps (a pass-through job above the per-call budget)
+// ============================================================
+/**
+ * Ceiling on what ONE viewer-confirmed pass-through job may cost, in Buzz. Host
+ * constant `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`. A fixed price above it gets
+ * no {@link BlockWorkflowSnapshot.stepQuote} and cannot be run from an app.
+ */
+export const BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB = 5000;
+/**
+ * The shape of a confirmed-step quote id ({@link BlockStepQuote.quoteId}): `sq_`
+ * followed by 32 lowercase hex characters. Host constant
+ * `BLOCK_STEP_QUOTE_ID_REGEX`. Disjoint from the training quote's `tq_` shape,
+ * so neither kind's id can name the other's quote.
+ */
+export const BLOCK_STEP_QUOTE_ID_REGEX = /^sq_[a-f0-9]{32}$/;
+// ============================================================
+// 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
+ *    172 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 172 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
+ *    172 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 172 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.1",
+  "version": "0.67.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",