@civitai/app-sdk 0.66.0 → 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), `WorkflowBodyWorkflow` (+ `WorkflowBodyWorkflowStep`, `WorkflowStepRef`, `WithWorkflowStepRefs`, `BlockWorkflowStepSnapshot` and `BLOCK_WORKFLOW_MAX_STEPS`), `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
@@ -259,10 +299,15 @@ const body: WorkflowBody = {
 
 - 🔴 **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`).
+- **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.
@@ -277,8 +322,8 @@ const body: WorkflowBody = {
 - 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.
+  `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

package/dist/blocks/index.d.ts

@@ -109,9 +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, 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';
+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

@@ -110,6 +110,11 @@ export { isModelSlotContext, isPageSlotContext } from './types.js';
 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

@@ -1251,7 +1251,39 @@ 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
@@ -1386,12 +1418,21 @@ export type WorkflowBodyWorkflowStep = {
  *     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.
+ *  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
@@ -1700,15 +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.
+     * 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
@@ -1717,6 +1764,15 @@ 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`
@@ -1728,10 +1784,30 @@ export interface BlockWorkflowSnapshot {
      *  - `'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).
+     *    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
@@ -1939,6 +2015,84 @@ 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
@@ -2014,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}.
@@ -2040,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' | 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded';
+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. */
@@ -2696,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`
@@ -3013,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,22 @@ 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'`)
 // ============================================================
 /**

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