@civitai/blocks-react 0.70.0 → 0.71.0

package/README.md

@@ -482,7 +482,7 @@ if (quote.cost) showPrice(priceLine(quote.cost));
 
 | `cost.authorFee` | Means | Where |
 |---|---|---|
-| a number `> 0` | that much of `total` is the app fee | `estimate()` for a `textToImage` or registered-`step` body, and the refusal `submit()` resolves for those kinds when a budget, spend cap or rate limit refuses the quoted price |
+| a number `> 0` | that much of `total` is the app fee | `estimate()` for a `textToImage`, registered-`step` or `workflow` body (one fee for the whole workflow), and the refusal `submit()` resolves for those kinds when a budget, spend cap or rate limit refuses the quoted price |
 | `0` | a fee was looked up and none applies to this request | the same replies |
 | absent | the total is **not itemised** | a host that predates the field; every snapshot of a submitted workflow (`submit` success, `poll`, `cancel`), whose `total` is the generation's realized cost with the fee charged separately; the registered-`step` `submit()` refusal for a missing orchestrator price quote, which refuses before any fee is looked up; and `customComfy`, pass-through `step` and `training` quotes, which price no fee |
 
@@ -541,6 +541,164 @@ try {
   (`KnownBlockWorkflowErrorCode | (string & {})`), the host may add codes, and
   the inbound validator accepts any string. Keep a `default` branch.
 - The `kind: 'training'` arm does not set it.
+- A refused `kind: 'workflow'` body sets its own three codes, in the same
+  shape — see the next section.
+
+#### Several steps as one workflow: `kind: 'workflow'`
+
+A `kind: 'workflow'` body submits **several orchestrator steps as one
+workflow**, where a later step can consume an earlier step's result. It goes
+through the hooks you already use: `useBuzzWorkflow().estimate / submit /
+watch / cancel`, a `useBatchEstimate()` cell, and `useWorkflowBatch()`. There
+is no new hook and no new message.
+
+```tsx
+import { useBuzzWorkflow } from '@civitai/blocks-react';
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+
+const { estimate, submit, watch } = useBuzzWorkflow();
+
+// Step 1 draws an image; step 2 removes the background from step 1's result.
+const body: WorkflowBody = {
+  kind: 'workflow',
+  arguments: { prompt: 'a lighthouse at dusk' },
+  steps: [
+    {
+      name: 'draw',
+      $type: 'imageGen',
+      input: {
+        engine: 'google',
+        model: 'nano-banana-2',
+        // Read from `arguments` above.
+        prompt: { $ref: '$arguments', path: 'prompt' },
+      },
+      // An intermediate step: its image is not surfaced.
+      suppressOutput: true,
+    },
+    {
+      name: 'cutout',
+      $type: 'imageBackgroundRemoval',
+      // Read from the EARLIER step named `draw`.
+      input: { image: { $ref: 'draw', path: 'output.images[0].url' } },
+    },
+  ],
+};
+
+const quote = await estimate(body);
+showPrice(`About ${quote.cost?.total} Buzz`); // an estimate, not a maximum
+
+const submitted = await submit(body);
+const done = await watch(submitted.workflowId);
+
+for (const step of done.steps ?? []) {
+  if (step.status === 'failed') showError(`${step.name} failed`);
+}
+// Even when `done.status === 'failed'`, earlier steps may have left images.
+showImages(done.imageUrls ?? []);
+```
+
+**The body**
+
+- `steps`: 1 to 8 (`BLOCK_WORKFLOW_MAX_STEPS`). Each is `{ name?, $type, input,
+  suppressOutput? }`, where `$type` is an orchestrator step type and `input` is
+  that step's own input.
+- **A step `name`** is optional. It is a lowercase letter followed by up to 31
+  of `a-z`, `0-9`, `_` or `-`, unique within the body, and not `block-step`
+  (reserved). A step you do not name is named by its position: `$0`, `$1`, ….
+- **A reference** is `{ $ref, path, default?, format? }` and may stand in for
+  any value in `input`, at any depth. `$ref` is `'$arguments'`, the `name` of an
+  **earlier** step, or — for an earlier step you did not name — its position
+  (`'$0'` is the first step). A step can never reference itself or a later
+  step. An object is a reference only when it has both `$ref` and `path` and no
+  other key but `default` / `format`.
+- **Limits**: 64 references per body, inputs nested at most 32 levels, `repeat`
+  templates nested at most 4 deep, a `$type` of at most 64 characters, and 256
+  KB (262144 bytes) for every step's `input` plus `arguments` together. An
+  unknown key on the body or on a step is rejected. The app's velocity limit
+  counts one unit per step, and a `repeat` step one per iteration instead.
+- `suppressOutput: true` marks an intermediate step. Its images are left out of
+  `snapshot.imageUrls` and out of its own `steps[i].imageUrls`. It still runs
+  and is still charged.
+- There is **no `maxBuzz`**. The spend ceiling is the app's per-generation
+  budget × the number of steps, enforced by the host.
+- Any orchestrator `$type` is accepted except the platform-internal ones:
+  scanners, moderation classifiers, hashing, web scrape/search, and the retired
+  `textToImage` step type.
+- **`repeat` over `arguments` only, at most 16 iterations**
+  (`BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS`, nested repeats multiplied). Its input
+  is exactly `{ for: { $ref: '$arguments', path, as }, template: { $type,
+  name?, input? } }`, where `path` names an array in `arguments`. Inside the
+  template, `as` is a source a reference may name; it may not equal a step
+  name. The template's `$type` is held to the denylist too. A `repeat` over
+  another step's output is refused, because its length is unknown until that
+  step has run. The single-step pass-through `kind: 'step'` arm refuses
+  `repeat` outright.
+- **`merge`**: every entry of `input.fields` needs a string `$ref` (`$arguments`
+  or an earlier step, never a repeat variable) and a `reduce`; each counts
+  toward the 64-reference limit.
+- `WithWorkflowStepRefs<T>` (from `@civitai/app-sdk/blocks`) types an input you
+  already have a type for while still allowing references in it.
+
+**🔴 Three things about the price**
+
+1. **The estimate is not a maximum.** When a step reads from an earlier step,
+   the orchestrator re-prices it once those values are known and charges the
+   difference. Never show the estimate as "you will pay at most".
+2. **A workflow the host cannot price still proceeds.** `submit()` reserves the
+   ceiling above instead of a quote. Two exceptions are refused without a
+   quote, before any reservation: a workflow with a training step (a
+   `training-quote-*` `errorCode`, as on the single-step arm), and a workflow
+   with a `repeat` step at any depth (`workflow_repeat_unbounded`; a retry may
+   succeed).
+3. **One author fee per workflow**, not one per step, 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 if earlier steps delivered output.
+
+**The result**
+
+`snapshot.steps` lists every step in order, as `{ name, $type, status,
+imageUrls?, output?, error? }`. Read it from `poll()`, `watch()` and
+`cancel()`; do not rely on it being on the `submit()` reply. The steps a
+`repeat` step generates follow it, named `<repeat name>.<n>`. The top-level
+fields keep their meaning: `status` and `cost` are the whole workflow's, and
+`imageUrls` is the union of the steps that did not set `suppressOutput`.
+
+🔴 **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`. Show what did
+finish, and do not tell the viewer nothing was charged — though the app fee is
+reversed for any workflow that does not succeed.
+
+**Refusals**
+
+A body the host will not run is refused before anything is priced or reserved:
+`estimate()` rejects with `WorkflowEstimateError`, `submit()` with
+`WorkflowSubmitError`, and a batch estimate returns it as that cell. Branch on
+`err.snapshot.errorCode`:
+
+| `errorCode` | Means |
+|---|---|
+| `'workflow_too_many_steps'` | more than 8 steps |
+| `'workflow_step_denied'` | a step names a platform-internal `$type` |
+| `'workflow_ref_invalid'` | a reference points at the step itself, a later step, or nothing; a step name breaks the rules above; a `repeat` or `merge` is malformed; or a repeat `as` name is also a step name |
+| `'workflow_repeat_unbounded'` | a `repeat` iterates something other than an array in `arguments`, or more than 16 times (nested repeats multiplied); or the workflow has a `repeat` and no price quote could be had (retrying may work) |
+
+- **Requires a host that knows the kind.** An older host refuses the body.
+- **Test it locally.** The mock host prices each step with
+  `generation.costPerGen` (a function gets the step as its second argument) and
+  multiplies it by a `repeat` step's iteration count, then adds
+  `generation.authorFee` once; refuses with the four codes above, in the host's
+  order; reports
+  `steps` on every poll, finishing them in order; and
+  `generation.failWorkflowStep: '<name>'` (`'$<index>'` for an unnamed step)
+  makes one step fail, so you can render a partial failure. The mock checks
+  where a reference points, not whether its `path` exists; it never re-prices;
+  and it does not expand a `repeat` step into generated `<name>.<n>` steps. It
+  quotes every workflow unless you set `generation.workflowUnpriced: true`,
+  which simulates no quote: a workflow with a training step or a `repeat` is
+  refused, and any other is reserved at `buzzBudget` × steps with no fee.
 
 > **Estimate must mirror submit** (gotcha #59): build the params for `estimate`
 > with the *exact* same logic as `submit` — same seed decision especially. The
@@ -2665,6 +2823,7 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+MockWorkflowStepInfo
 PopoverShimHandle
 PopoverShimOptions
 ```

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -698,6 +698,22 @@ export interface UseBuzzWorkflow {
  * the paragraph above records, one member over: an incomplete description of a
  * union, trusted because it read as authoritative.
  *
+ * 🔴 A MULTI-STEP `kind: 'workflow'` BODY CHANGES WHAT THE PRICE MEANS — again a
+ * capability claim, so it is stated here. `WorkflowBodyWorkflow` submits several
+ * orchestrator steps as one workflow through these same calls, and:
+ *  - `estimate()`'s `cost.total` 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 on `submit()`, reserved at
+ *    the app's per-generation budget × the number of steps (one with a training
+ *    step, or with a `repeat` step at any depth, is refused instead);
+ *  - one author fee applies to the whole workflow, not one per step, and it is
+ *    reversed whole if the workflow does not succeed;
+ *  - `repeat` iterates only an array in the body's `arguments`, at most 16
+ *    times, nested repeats multiplied;
+ *  - a `failed` result can carry `cost.total > 0` and usable `imageUrls`, because
+ *    steps that succeeded before the failing one stay charged — read
+ *    `result.steps`.
+ *
  * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
  * @example

package/dist/hooks/useBuzzWorkflow.js

@@ -523,6 +523,22 @@ export class WorkflowSubmitError extends Error {
  * the paragraph above records, one member over: an incomplete description of a
  * union, trusted because it read as authoritative.
  *
+ * 🔴 A MULTI-STEP `kind: 'workflow'` BODY CHANGES WHAT THE PRICE MEANS — again a
+ * capability claim, so it is stated here. `WorkflowBodyWorkflow` submits several
+ * orchestrator steps as one workflow through these same calls, and:
+ *  - `estimate()`'s `cost.total` 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 on `submit()`, reserved at
+ *    the app's per-generation budget × the number of steps (one with a training
+ *    step, or with a `repeat` step at any depth, is refused instead);
+ *  - one author fee applies to the whole workflow, not one per step, and it is
+ *    reversed whole if the workflow does not succeed;
+ *  - `repeat` iterates only an array in the body's `arguments`, at most 16
+ *    times, nested repeats multiplied;
+ *  - a `failed` result can carry `cost.total > 0` and usable `imageUrls`, because
+ *    steps that succeeded before the failing one stay charged — read
+ *    `result.steps`.
+ *
  * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
  * @example

package/dist/internal/mockHost.d.ts

@@ -77,7 +77,21 @@ export type MockCannedImageScan = 'scanned' | {
  * A per-generation cost: a fixed number, or a function of the submitted
  * {@link WorkflowBody} (so a dev can vary cost by model / step count).
  */
-export type CostSpec = number | ((req: WorkflowBody) => number);
+export type CostSpec = number | ((req: WorkflowBody, step?: MockWorkflowStepInfo) => number);
+/**
+ * The step a {@link CostSpec} function is pricing, passed as its SECOND
+ * argument when the body is `kind: 'workflow'`: the mock calls
+ * {@link MockGenerationScenario.costPerGen} once per step and sums the results.
+ * `undefined` for every other kind, which is priced with one call.
+ */
+export interface MockWorkflowStepInfo {
+    /** Zero-based position in the body's `steps`. */
+    index: number;
+    /** The step's `name`, or `'$<index>'` for an unnamed step. */
+    name: string;
+    $type: string;
+    input: Record<string, unknown>;
+}
 /**
  * A result image url: a fixed string, or a function of the submitted body
  * (so a dev can echo the prompt into a placeholder).
@@ -91,6 +105,12 @@ export interface MockGenerationScenario {
     /**
      * Cost reported on `ESTIMATE_RESULT` + the succeeded snapshot. A number, or
      * a `(body) => number`. Overrides the legacy top-level `cost`. Default `8`.
+     *
+     * A `kind: 'workflow'` body is priced PER STEP: this is called once for each
+     * step (a function receives the step as its second argument, see
+     * {@link MockWorkflowStepInfo}), multiplied by that step's generations (a
+     * `repeat` counts its iterations, nested repeats multiplied), and summed, so a
+     * plain number prices an N-step workflow with no `repeat` at N times it.
      */
     costPerGen?: CostSpec;
     /**
@@ -100,9 +120,10 @@ export interface MockGenerationScenario {
      * real host does. A number, or a `(body) => number`. Default `0`, which is
      * reported as `authorFee: 0` ("no fee on this request").
      *
-     * Like the real host, only a `textToImage` or registered-`step` body is
-     * itemised; `customComfy`, pass-through `step` and `training` quotes carry no
-     * `authorFee`. The succeeded snapshot's `cost.total` stays {@link costPerGen}
+     * Like the real host, only a `textToImage`, registered-`step` or `workflow`
+     * body is itemised; `customComfy`, pass-through `step` and `training` quotes
+     * carry no `authorFee`. A `workflow` body is charged this ONCE, however many
+     * steps it has. The succeeded snapshot's `cost.total` stays {@link costPerGen}
      * (a submitted workflow reports the generation's own cost), while a simulated
      * {@link MockBuzzScenario.balance} is debited `costPerGen + authorFee`.
      *
@@ -265,7 +286,44 @@ export interface MockGenerationScenario {
      * Default: unset.
      */
     submitCapRefusal?: string | true;
-    /** A single result image url (or `(body) => url`). */
+    /**
+     * Make ONE step of a `kind: 'workflow'` run fail, so a block can exercise a
+     * PARTIAL failure. Name the step as its snapshot entry names it: its `name`,
+     * or `'$<index>'` for a step the body left unnamed. The poll that finishes
+     * the workflow then answers `status: 'failed'` with:
+     *  - `steps`: every step before it `'succeeded'`, the named step `'failed'`
+     *    with an `error`, every step after it `'canceled'`;
+     *  - `cost.total`: the sum of the steps that succeeded (they stay charged), so
+     *    it is `> 0` unless the FIRST step is the one that fails;
+     *  - `imageUrls`: the images of the succeeded steps that did not set
+     *    `suppressOutput`.
+     *
+     * What the real orchestrator reports for the steps AFTER a failed one is its
+     * own business; `'canceled'` here is the mock's stand-in for "did not run".
+     *
+     * Ignored by every other kind, and when no step matches. Takes precedence
+     * over {@link workflowOutcome} for the workflow it applies to. Live-tunable
+     * via `setScenario({ generation: { failWorkflowStep } })`. Default: unset.
+     */
+    failWorkflowStep?: string;
+    /**
+     * Simulate the host getting NO price quote for a `kind: 'workflow'` body. The
+     * host then refuses, before any reservation, a workflow with a training step
+     * (`errorCode: 'training-quote-unavailable'`) or a `repeat` step at any depth
+     * (`'workflow_repeat_unbounded'`); any other workflow proceeds reserved at the
+     * CEILING — {@link MockHostOptions.buzzBudget} × the number of steps — which
+     * the estimate reports as `cost.total`, with `authorFee: 0` (no quote, no
+     * fee base). Ignored by every other kind. Live-tunable via
+     * `setScenario({ generation: { workflowUnpriced } })`. Default: unset (every
+     * workflow is quoted at its per-step `costPerGen`).
+     */
+    workflowUnpriced?: boolean;
+    /**
+     * A single result image url (or `(body) => url`). For a `kind: 'workflow'`
+     * run this (and {@link images}) is the LAST step that did not set
+     * `suppressOutput`; each earlier visible step gets its own labelled
+     * placeholder.
+     */
     image?: ImageSpec;
     /**
      * Multiple result image urls (or `(body) => url[]`). Takes precedence over

package/dist/internal/mockHost.js

@@ -43,6 +43,7 @@ import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, sto
 import { governsIdempotencyKey, idempotencyKeyDeniedMessage, idempotencyKeyRefusal, } from './mockHostIdempotency.js';
 import { SAVE_IMAGE_INVALID_REQUEST_ERROR, prepareSaveBytes, saveImageRequestKind, } from './saveBytes.js';
 import { UPLOAD_BYTES_INVALID_ERROR, admitUploadBytes, resolveUploadBytesRequest, } from './uploadBytes.js';
+import { mockUnpricedWorkflowRefusal, mockWorkflowBodyRefusal, mockWorkflowStepGenerations, mockWorkflowStepName, } from './mockWorkflowGraph.js';
 import { BATCH_ESTIMATE_CELL_TIMEOUT_ERROR } from '../hooks/useBatchEstimate.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
@@ -87,6 +88,9 @@ const preferredAccountType = (body) => {
         // is `.strict()` with no `accountType`.
         case 'training':
             return undefined;
+        // Nor does a multi-step body: the kind has no `accountType` field.
+        case 'workflow':
+            return undefined;
         default: {
             // Exhaustiveness check: a new `WorkflowBody` member makes this assignment
             // fail to compile, right here, rather than defaulting somewhere.
@@ -990,10 +994,35 @@ export function createMockHost(options = {}) {
         viewerVoted: row.voters.has(mockUserId),
     });
     // Resolve a per-gen cost from the scenario (or legacy `cost`).
+    // A `kind: 'workflow'` body is the SUM of its steps — see `workflowStepCosts`.
     const costFor = (body) => {
+        if (body.kind === 'workflow')
+            return workflowStepCosts(body).reduce((sum, c) => sum + c, 0);
         const spec = gen.costPerGen ?? legacyCost;
         return typeof spec === 'function' ? spec(body) : (spec ?? legacyCost);
     };
+    /**
+     * `costPerGen`, called once per step of a `kind: 'workflow'` body and
+     * multiplied by that step's generations — 1, or a `repeat`'s iteration count —
+     * because the orchestrator's quote prices every child of a bounded repeat.
+     */
+    const workflowStepCosts = (body) => {
+        // Unpriced: reserved at the ceiling, one per-generation budget per step.
+        if (gen.workflowUnpriced === true)
+            return body.steps.map(() => buzzBudget);
+        const spec = gen.costPerGen ?? legacyCost;
+        return (Array.isArray(body.steps) ? body.steps : []).map((step, index) => {
+            const each = typeof spec === 'function'
+                ? spec(body, {
+                    index,
+                    name: mockWorkflowStepName(step, index),
+                    $type: step.$type,
+                    input: step.input,
+                })
+                : spec;
+            return each * mockWorkflowStepGenerations(step.$type, step.input, body.arguments);
+        });
+    };
     // `null` = this quote is not itemised (a fee-less kind, or `authorFee: false`).
     const authorFeeFor = (body) => {
         if (gen.authorFee === false)
@@ -1001,9 +1030,16 @@ export function createMockHost(options = {}) {
         // A REGISTERED step is keyed on the VALUE of `step`, as the host keys it —
         // never `'step' in body`: `{ kind: 'step', step: undefined, ... }` is a legal
         // pass-through body, and a pass-through quote prices no fee.
-        const quotesFee = body.kind === 'textToImage' || (body.kind === 'step' && typeof body.step === 'string');
+        // A `workflow` body quotes ONE fee for the whole workflow: this function is
+        // called once per body and never per step.
+        const quotesFee = body.kind === 'textToImage' ||
+            body.kind === 'workflow' ||
+            (body.kind === 'step' && typeof body.step === 'string');
         if (!quotesFee)
             return null;
+        // An unpriced workflow has no quoted base, so no fee is priced on it.
+        if (body.kind === 'workflow' && gen.workflowUnpriced === true)
+            return 0;
         const spec = gen.authorFee ?? 0;
         return typeof spec === 'function' ? spec(body) : spec;
     };
@@ -1149,10 +1185,88 @@ export function createMockHost(options = {}) {
                 ...(gen.trainingPublishedModel ? { publishedModel: { ...gen.trainingPublishedModel } } : {}),
             };
         };
+        /**
+         * The `steps` (and the top-level `imageUrls` they add up to) of a
+         * `kind: 'workflow'` run, given each step's status. A step reports images
+         * only once it has `'succeeded'` and only if it did not set
+         * `suppressOutput`; the top-level list is the union of those, in step order.
+         */
+        const workflowStepsView = (workflowId, body, statusOf, failedError) => {
+            const lastVisible = body.steps.reduce((last, s, i) => (s.suppressOutput === true ? last : i), -1);
+            const steps = body.steps.map((step, index) => {
+                const status = statusOf(index);
+                const name = mockWorkflowStepName(step, index);
+                const visible = status === 'succeeded' && step.suppressOutput !== true;
+                return {
+                    name,
+                    $type: step.$type,
+                    status,
+                    ...(visible
+                        ? {
+                            imageUrls: index === lastVisible
+                                ? imagesFor(workflowId, body)
+                                : [
+                                    `https://placehold.co/512x512/1971c2/ffffff/png?text=MOCK%0A${encodeURIComponent(name)}`,
+                                ],
+                        }
+                        : {}),
+                    ...(status === 'failed' && failedError !== undefined ? { error: failedError } : {}),
+                };
+            });
+            const imageUrls = steps.flatMap((s) => s.imageUrls ?? []);
+            return { steps, ...(imageUrls.length > 0 ? { imageUrls } : {}) };
+        };
+        /** A RUNNING `kind: 'workflow'` run after `polls` polls: steps finish in order. */
+        const workflowProgressView = (workflowId, body, polls) => {
+            const total = body.steps.length;
+            const failing = failingWorkflowStep(body);
+            const done = Math.min(Math.floor((total * polls) / Math.max(1, pollsUntilDone)), total - 1, failing === -1 ? total - 1 : failing);
+            return workflowStepsView(workflowId, body, (i) => i < done ? 'succeeded' : i === done ? 'processing' : 'pending');
+        };
+        /** Index of the step `generation.failWorkflowStep` names, or `-1`. */
+        const failingWorkflowStep = (body) => {
+            const target = gen.failWorkflowStep;
+            if (target === undefined)
+                return -1;
+            return body.steps.findIndex((s, i) => mockWorkflowStepName(s, i) === target);
+        };
+        /**
+         * The terminal snapshot of a `kind: 'workflow'` run whose step
+         * `generation.failWorkflowStep` names failed, or `null` when none does.
+         * Earlier steps stay `'succeeded'` and CHARGED, so `cost.total` is their sum
+         * and their visible images are still there.
+         */
+        const workflowPartialFailure = (workflowId) => {
+            const wf = workflows.get(workflowId);
+            const body = wf?.body;
+            if (!wf || body?.kind !== 'workflow')
+                return null;
+            const failing = failingWorkflowStep(body);
+            if (failing === -1)
+                return null;
+            const error = `mock: step "${mockWorkflowStepName(body.steps[failing], failing)}" failed`;
+            const charged = (wf.stepCosts ?? []).slice(0, failing).reduce((sum, c) => sum + c, 0);
+            return {
+                workflowId,
+                status: 'failed',
+                cost: { total: charged },
+                error,
+                ...workflowStepsView(workflowId, body, (i) => (i < failing ? 'succeeded' : i === failing ? 'failed' : 'canceled'), error),
+            };
+        };
         const succeededSnapshot = (workflowId) => {
             const wf = workflows.get(workflowId);
             const cost = wf?.cost ?? legacyCost;
             const body = wf?.body ?? {};
+            if (body.kind === 'workflow') {
+                return {
+                    workflowId,
+                    status: 'succeeded',
+                    cost: { total: cost },
+                    ...workflowStepsView(workflowId, body, () => 'succeeded'),
+                    spentAccountType: primaryFunder(buzzBalance),
+                };
+            }
             return {
                 ...trainingFields(body),
                 workflowId,
@@ -1328,6 +1442,16 @@ export function createMockHost(options = {}) {
                             },
                         };
                     }
+                    // MULTI-STEP — the second kind-faithful arm: the host refuses a body
+                    // it will not run BEFORE pricing it, with an `errorCode`, in the
+                    // `failureSnapshot` shape (no `cost`). A body that passes is priced
+                    // below like any other: `quotedCost` sums the steps and adds ONE fee.
+                    if (body.kind === 'workflow') {
+                        const refusal = mockWorkflowBodyRefusal(body) ??
+                            (gen.workflowUnpriced === true ? mockUnpricedWorkflowRefusal(body) : null);
+                        if (refusal !== null)
+                            return { workflowId: 'failed', status: 'failed', ...refusal };
+                    }
                     return {
                         workflowId: 'wf_estimate',
                         status: 'pending',
@@ -1611,6 +1735,23 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        // A `kind: 'workflow'` body the host will not run is refused here,
+                        // before any cap, balance or debit — the same refusal, with the same
+                        // `errorCode`, the estimate gives. No `cost`, so `submit()` rejects.
+                        if (body.kind === 'workflow') {
+                            const refusal = mockWorkflowBodyRefusal(body) ??
+                                (gen.workflowUnpriced === true ? mockUnpricedWorkflowRefusal(body) : null);
+                            if (refusal !== null) {
+                                dispatchToBlock({
+                                    type: 'WORKFLOW_SUBMITTED',
+                                    payload: {
+                                        requestId,
+                                        snapshot: { workflowId: 'failed', status: 'failed', ...refusal },
+                                    },
+                                });
+                                return;
+                            }
+                        }
                         const cost = costFor(body);
                         // What the viewer pays: the generation plus the app fee.
                         const charged = cost + (authorFeeFor(body) ?? 0);
@@ -1758,7 +1899,12 @@ export function createMockHost(options = {}) {
                         if (balanceSimulated)
                             buzz.balance = buzz.balance - charged;
                         const workflowId = `wf_${submitCount}_${Date.now()}`;
-                        workflows.set(workflowId, { polls: 0, cost, body });
+                        workflows.set(workflowId, {
+                            polls: 0,
+                            cost,
+                            body,
+                            ...(body.kind === 'workflow' ? { stepCosts: workflowStepCosts(body) } : {}),
+                        });
                         dispatchToBlock({
                             type: 'WORKFLOW_SUBMITTED',
                             payload: { requestId, snapshot: { workflowId, status: 'pending' } },
@@ -1784,6 +1930,16 @@ export function createMockHost(options = {}) {
                         }
                         const polls = wf.polls + 1;
                         wf.polls = polls;
+                        // A `kind: 'workflow'` run with a step told to fail ends `failed`
+                        // with its earlier steps intact (`generation.failWorkflowStep`).
+                        const partialFailure = polls >= pollsUntilDone ? workflowPartialFailure(workflowId) : null;
+                        if (partialFailure !== null) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_STATUS',
+                                payload: { requestId, snapshot: partialFailure },
+                            });
+                            return;
+                        }
                         const outcome = polls >= pollsUntilDone ? (gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded') : null;
                         if (outcome === 'failed' || outcome === 'expired') {
                             dispatchToBlock({
@@ -1814,7 +1970,17 @@ export function createMockHost(options = {}) {
                         else {
                             dispatchToBlock({
                                 type: 'WORKFLOW_STATUS',
-                                payload: { requestId, snapshot: { workflowId, status: 'processing' } },
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        workflowId,
+                                        status: 'processing',
+                                        // A multi-step run reports how far its steps have got.
+                                        ...(wf.body?.kind === 'workflow'
+                                            ? workflowProgressView(workflowId, wf.body, polls)
+                                            : {}),
+                                    },
+                                },
                             });
                         }
                         return;
@@ -1835,6 +2001,14 @@ export function createMockHost(options = {}) {
                         if (wf && !wf.canceled && wf.polls >= pollsUntilDone) {
                             // Already finished: like the real host, report the real terminal
                             // status rather than pretending the cancel took.
+                            const partialFailure = workflowPartialFailure(workflowId);
+                            if (partialFailure !== null) {
+                                dispatchToBlock({
+                                    type: 'WORKFLOW_CANCELED',
+                                    payload: { requestId, snapshot: partialFailure },
+                                });
+                                return;
+                            }
                             const outcome = gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded';
                             dispatchToBlock({
                                 type: 'WORKFLOW_CANCELED',

package/dist/internal/mockWorkflowGraph.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The mock host's checks on a multi-step `kind: 'workflow'` body: its shape,
+ * its step cap, its step names and reference graph, and the step-type denylist.
+ *
+ * A MIRROR of the host's rules, kept in its own pure module so the estimate, the
+ * batch estimate and the submit all refuse the same bodies, in the same order,
+ * with the same `errorCode`.
+ *
+ * 🔴 AN APPROXIMATION, NOT THE HOST. It checks WHERE a reference points, never
+ * whether its `path` exists, and it prices nothing. A body this accepts can
+ * still be refused by the real host or by the orchestrator.
+ */
+/**
+ * The bounds the mock enforces. `maxSteps` is a COPY of
+ * `@civitai/app-sdk/blocks`'s `BLOCK_WORKFLOW_MAX_STEPS`, deliberately not
+ * value-imported: a value import of a symbol the newest PUBLISHED app-sdk lacks
+ * raises this package's peer floor
+ * (`tests/guards/blocks-react-peer-floor.test.mjs`). It is held to the SDK's
+ * value by `test/mockHostWorkflowKind.test.tsx`, which imports both.
+ */
+export declare const MOCK_WORKFLOW_BOUNDS: {
+    /** Steps in one body. */
+    readonly maxSteps: 8;
+    /** Reference objects across every step input of one body. */
+    readonly maxRefs: 64;
+    /** Nesting depth of one step `input`. */
+    readonly maxInputDepth: 32;
+    /** How deep a `repeat` template may nest another `repeat`. */
+    readonly maxRepeatNesting: 4;
+    /** Serialized bytes of every step `input` plus `arguments`, summed. */
+    readonly maxInputBytes: 262144;
+    /** Characters of a step `$type`, and of a step `name` on the wire. */
+    readonly maxTypeChars: 64;
+    /**
+     * Iterations of one top-level `repeat` step, nested repeats MULTIPLIED. A
+     * COPY of `@civitai/app-sdk/blocks`'s `BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS`,
+     * held to it by the same test as `maxSteps`.
+     */
+    readonly maxRepeatIterations: 16;
+};
+/**
+ * Orchestrator `$type`s a `kind: 'workflow'` step may not name: the host's
+ * platform-internal list (scanners, moderation classifiers, hashing and model
+ * ingestion, the catalog's platform internals, web scrape/search and the
+ * retired `textToImage` step type) plus `promptModeration`. Matched
+ * case-insensitively, as the host matches. Anything else is accepted,
+ * including a `$type` this list has never heard of.
+ */
+export declare const MOCK_WORKFLOW_DENIED_STEP_TYPES: readonly string[];
+/** A refused body: the reply's `error` and, where one is defined, its `errorCode`. */
+export interface MockWorkflowRefusal {
+    error: string;
+    errorCode?: 'workflow_step_denied' | 'workflow_ref_invalid' | 'workflow_too_many_steps' | 'workflow_repeat_unbounded' | 'training-quote-unavailable';
+}
+/** What a step is called in a reference and on the snapshot: its `name`, or `'$<index>'`. */
+export declare const mockWorkflowStepName: (step: {
+    name?: unknown;
+}, index: number) => string;
+/** The refusal for a `repeat` whose shape or nesting the mock cannot follow. */
+export declare const MOCK_REPEAT_SHAPE_ERROR: string;
+/** The refusal for a `merge` whose sources the mock cannot read. */
+export declare const MOCK_MERGE_SHAPE_ERROR = "a merge step needs a \"fields\" object whose entries each carry a string \"$ref\" and a \"reduce\"";
+/**
+ * How many generations a step runs: 1, or a `repeat`'s iteration count with
+ * nested repeats multiplied (never less than 1). Only meaningful for a body
+ * {@link mockWorkflowBodyRefusal} accepted.
+ */
+export declare function mockWorkflowStepGenerations(stepType: string, input: unknown, args: unknown): number;
+/** The host's refusal text for an unquoted training step (`UNQUOTED_TRAINING_ERROR`). */
+export declare const MOCK_UNQUOTED_TRAINING_ERROR = "Training needs a price quote and none could be obtained; try again.";
+/**
+ * The refusal for a body {@link mockWorkflowBodyRefusal} ACCEPTED when the host
+ * could get NO price quote for it, or `null` when it would proceed (reserved at
+ * the ceiling). In the host's order: a training step anywhere (its own
+ * `training-quote-*` refusal — the mock reports `'training-quote-unavailable'`,
+ * the code for "no usable answer"), then a `repeat` anywhere
+ * (`workflow_repeat_unbounded`, naming the first such step).
+ */
+export declare function mockUnpricedWorkflowRefusal(body: {
+    steps: ReadonlyArray<{
+        $type: string;
+        input: unknown;
+    }>;
+}): MockWorkflowRefusal | null;
+/**
+ * The refusal for a `kind: 'workflow'` body, or `null` for one the mock will
+ * price and run. In the host's order:
+ *
+ *  1. the wire shape — no `errorCode`, the host's schema rejection;
+ *  2. the step cap — `workflow_too_many_steps`;
+ *  3. step by step: the name rules and a `repeat`'s exact shape and nesting
+ *     (`workflow_ref_invalid`); the repeat bound — only over an array in
+ *     `arguments`, at most 16 iterations with nested repeats multiplied
+ *     (`workflow_repeat_unbounded`); then the reference graph
+ *     (`workflow_ref_invalid`). A name is `[a-z][a-z0-9_-]{0,31}` (or the
+ *     step's own `$<index>`), unique, and not `block-step`; every source — a
+ *     reference, a `repeat`'s `for`, a `merge` field — names `$arguments` or an
+ *     EARLIER step, and a `merge` field never names a repeat variable;
+ *  4. a repeat `as` name that is also a step name — `workflow_ref_invalid`;
+ *  5. the step-type denylist on every step and on the step a `repeat` runs —
+ *     `workflow_step_denied`.
+ */
+export declare function mockWorkflowBodyRefusal(body: unknown): MockWorkflowRefusal | null;
+//# sourceMappingURL=mockWorkflowGraph.d.ts.map

package/dist/internal/mockWorkflowGraph.js

@@ -0,0 +1,424 @@
+/**
+ * The mock host's checks on a multi-step `kind: 'workflow'` body: its shape,
+ * its step cap, its step names and reference graph, and the step-type denylist.
+ *
+ * A MIRROR of the host's rules, kept in its own pure module so the estimate, the
+ * batch estimate and the submit all refuse the same bodies, in the same order,
+ * with the same `errorCode`.
+ *
+ * 🔴 AN APPROXIMATION, NOT THE HOST. It checks WHERE a reference points, never
+ * whether its `path` exists, and it prices nothing. A body this accepts can
+ * still be refused by the real host or by the orchestrator.
+ */
+/**
+ * The bounds the mock enforces. `maxSteps` is a COPY of
+ * `@civitai/app-sdk/blocks`'s `BLOCK_WORKFLOW_MAX_STEPS`, deliberately not
+ * value-imported: a value import of a symbol the newest PUBLISHED app-sdk lacks
+ * raises this package's peer floor
+ * (`tests/guards/blocks-react-peer-floor.test.mjs`). It is held to the SDK's
+ * value by `test/mockHostWorkflowKind.test.tsx`, which imports both.
+ */
+export const MOCK_WORKFLOW_BOUNDS = {
+    /** Steps in one body. */
+    maxSteps: 8,
+    /** Reference objects across every step input of one body. */
+    maxRefs: 64,
+    /** Nesting depth of one step `input`. */
+    maxInputDepth: 32,
+    /** How deep a `repeat` template may nest another `repeat`. */
+    maxRepeatNesting: 4,
+    /** Serialized bytes of every step `input` plus `arguments`, summed. */
+    maxInputBytes: 262_144,
+    /** Characters of a step `$type`, and of a step `name` on the wire. */
+    maxTypeChars: 64,
+    /**
+     * Iterations of one top-level `repeat` step, nested repeats MULTIPLIED. A
+     * COPY of `@civitai/app-sdk/blocks`'s `BLOCK_WORKFLOW_REPEAT_MAX_ITERATIONS`,
+     * held to it by the same test as `maxSteps`.
+     */
+    maxRepeatIterations: 16,
+};
+/**
+ * Orchestrator `$type`s a `kind: 'workflow'` step may not name: the host's
+ * platform-internal list (scanners, moderation classifiers, hashing and model
+ * ingestion, the catalog's platform internals, web scrape/search and the
+ * retired `textToImage` step type) plus `promptModeration`. Matched
+ * case-insensitively, as the host matches. Anything else is accepted,
+ * including a `$type` this list has never heard of.
+ */
+export const MOCK_WORKFLOW_DENIED_STEP_TYPES = Object.freeze([
+    'modelPickleScan',
+    'modelClamScan',
+    'imageScanning',
+    'xGuardModeration',
+    'shieldstralModeration',
+    'promptModeration',
+    'mediaHash',
+    'modelHash',
+    'modelParseMetadata',
+    'comfyNodepackSnapshot',
+    'qwenImageBench',
+    'webScrape',
+    'webSearch',
+    'textToImage',
+]);
+const DENIED_LOOKUP = new Set(MOCK_WORKFLOW_DENIED_STEP_TYPES.map((t) => t.toLowerCase()));
+const ARGUMENTS_REF = '$arguments';
+/** The name the single-step kinds give their one step; a workflow step may not take it. */
+const RESERVED_STEP_NAME = 'block-step';
+const STEP_NAME_PATTERN = /^[a-z][a-z0-9_-]{0,31}$/;
+/** The only keys a reference object may carry. */
+const REF_KEYS = new Set(['$ref', 'path', 'default', 'format']);
+const BODY_KEYS = new Set(['kind', 'steps', 'arguments']);
+const STEP_KEYS = new Set(['name', '$type', 'input', 'suppressOutput']);
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const isRepeat = (stepType) => typeof stepType === 'string' && stepType.toLowerCase() === 'repeat';
+/** What a step is called in a reference and on the snapshot: its `name`, or `'$<index>'`. */
+export const mockWorkflowStepName = (step, index) => typeof step.name === 'string' ? step.name : `$${index}`;
+const isMerge = (stepType) => typeof stepType === 'string' && stepType.toLowerCase() === 'merge';
+const hasOnlyKeys = (object, allowed) => Object.keys(object).every((key) => allowed.includes(key));
+/**
+ * A `repeat` step's input, or `null` unless it is EXACTLY
+ * `{ for: { $ref, path, as }, template: { $type, name?, input? } }` with string
+ * `$ref` / `path` / `as` / `$type` (and `name`, when present). Fail-closed on
+ * shape, every key spelled exactly, as the host reads it.
+ */
+function readRepeatInput(input) {
+    if (!isPlainObject(input) || !hasOnlyKeys(input, ['for', 'template']))
+        return null;
+    const { for: forClause, template } = input;
+    if (!isPlainObject(forClause) || !hasOnlyKeys(forClause, ['$ref', 'path', 'as']))
+        return null;
+    if (typeof forClause.$ref !== 'string' ||
+        typeof forClause.path !== 'string' ||
+        typeof forClause.as !== 'string') {
+        return null;
+    }
+    if (!isPlainObject(template) || !hasOnlyKeys(template, ['$type', 'name', 'input']))
+        return null;
+    if (typeof template.$type !== 'string')
+        return null;
+    if (template.name !== undefined && typeof template.name !== 'string')
+        return null;
+    return { forClause: forClause, template: template };
+}
+/** The refusal for a `repeat` whose shape or nesting the mock cannot follow. */
+export const MOCK_REPEAT_SHAPE_ERROR = 'a repeat step needs exactly { for: { $ref, path, as }, template: { $type, name?, input? } }, ' +
+    `nested at most ${MOCK_WORKFLOW_BOUNDS.maxRepeatNesting} deep`;
+/** The refusal for a `merge` whose sources the mock cannot read. */
+export const MOCK_MERGE_SHAPE_ERROR = 'a merge step needs a "fields" object whose entries each carry a string "$ref" and a "reduce"';
+/** The array a `for` path names in `arguments`, by exact own keys, or `null`. */
+function readArgumentsArray(args, path) {
+    let current = args;
+    for (const part of path.split('.')) {
+        if (!isPlainObject(current) || !Object.prototype.hasOwnProperty.call(current, part))
+            return null;
+        current = current[part];
+    }
+    return Array.isArray(current) ? current : null;
+}
+/**
+ * THE REPEAT BOUND. A refusal message, or `null` when the step is not a
+ * `repeat` or its loop is bounded: it iterates an array in the body's own
+ * `arguments` (so its length is fixed in the submitted body), and the count,
+ * nested repeats multiplied, is at most `maxRepeatIterations`.
+ */
+function repeatUnboundedProblem(stepType, input, args, outerIterations = 1) {
+    if (!isRepeat(stepType))
+        return null;
+    const repeat = readRepeatInput(input);
+    if (!repeat)
+        return MOCK_REPEAT_SHAPE_ERROR;
+    const { forClause, template } = repeat;
+    if (forClause.$ref !== ARGUMENTS_REF) {
+        return (`a repeat may only iterate over the workflow's own arguments ("$ref": "${ARGUMENTS_REF}"), ` +
+            `not ${JSON.stringify(forClause.$ref)} — pass the list in "arguments" instead`);
+    }
+    const items = readArgumentsArray(args, forClause.path);
+    if (!items)
+        return `repeat "for" path ${JSON.stringify(forClause.path)} does not name an array in "arguments"`;
+    const iterations = outerIterations * items.length;
+    if (iterations > MOCK_WORKFLOW_BOUNDS.maxRepeatIterations) {
+        return (`a repeat may run at most ${MOCK_WORKFLOW_BOUNDS.maxRepeatIterations} iterations, nested repeats ` +
+            `multiplied (got ${iterations})`);
+    }
+    return repeatUnboundedProblem(template.$type, template.input, args, iterations);
+}
+/**
+ * How many generations a step runs: 1, or a `repeat`'s iteration count with
+ * nested repeats multiplied (never less than 1). Only meaningful for a body
+ * {@link mockWorkflowBodyRefusal} accepted.
+ */
+export function mockWorkflowStepGenerations(stepType, input, args) {
+    if (!isRepeat(stepType))
+        return 1;
+    const repeat = readRepeatInput(input);
+    const items = repeat ? readArgumentsArray(args, repeat.forClause.path) : null;
+    if (!repeat || !items)
+        return 1;
+    return Math.max(1, items.length * mockWorkflowStepGenerations(repeat.template.$type, repeat.template.input, args));
+}
+/** The source each `merge` field reads, or `null` when that cannot be read for certain. */
+function readMergeSources(input) {
+    if (!isPlainObject(input))
+        return null;
+    if (Object.keys(input).some((key) => key !== 'fields' && key.toLowerCase() === 'fields'))
+        return null;
+    const { fields } = input;
+    if (!isPlainObject(fields))
+        return null;
+    const sources = [];
+    for (const field of Object.values(fields)) {
+        if (!isPlainObject(field))
+            return null;
+        if (Object.keys(field).some((key) => key !== '$ref' && key.toLowerCase() === '$ref'))
+            return null;
+        // Without `reduce` the entry is a plain reference, which the orchestrator
+        // replaces with what it points at before the merge reads it.
+        if (typeof field.$ref !== 'string' || !('reduce' in field))
+            return null;
+        sources.push(field.$ref);
+    }
+    return sources;
+}
+/**
+ * Every `$type` a step can run: its own and, for a `repeat`, its template's.
+ * `null` for a `repeat` whose shape it cannot follow, or nested past the bound.
+ */
+function collectStepTypes(stepType, input) {
+    const types = [];
+    let currentType = stepType;
+    let currentInput = input;
+    for (let depth = 0; depth <= MOCK_WORKFLOW_BOUNDS.maxRepeatNesting; depth += 1) {
+        types.push(currentType);
+        if (!isRepeat(currentType))
+            return types;
+        const repeat = readRepeatInput(currentInput);
+        if (!repeat)
+            return null;
+        currentType = repeat.template.$type;
+        currentInput = repeat.template.input;
+    }
+    return null;
+}
+/**
+ * A reference is an object with BOTH `$ref` and `path` and no key other than
+ * `default` / `format`. Anything else — including an object that has `$ref` but
+ * no `path` — is ordinary input and is walked, not judged.
+ */
+function isRefObject(value) {
+    if (!('$ref' in value) || !('path' in value))
+        return false;
+    return Object.keys(value).every((key) => REF_KEYS.has(key));
+}
+function checkSource(source, sources, state) {
+    state.refs += 1;
+    if (state.refs > MOCK_WORKFLOW_BOUNDS.maxRefs) {
+        return `a workflow may hold at most ${MOCK_WORKFLOW_BOUNDS.maxRefs} references`;
+    }
+    // THE BACKWARDS-ONLY RULE: `sources` holds `$arguments` and the names of the
+    // steps BEFORE this one, so the step itself, a later step and a name that
+    // does not exist all miss it the same way.
+    if (!sources.has(source)) {
+        return `"$ref": ${JSON.stringify(source)} does not name "${ARGUMENTS_REF}" or an earlier step`;
+    }
+    return null;
+}
+/** A refusal message, or `null` when `value` is fine. */
+function checkValue(value, depth, sources, state) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    if (depth > MOCK_WORKFLOW_BOUNDS.maxInputDepth) {
+        return `input is nested deeper than ${MOCK_WORKFLOW_BOUNDS.maxInputDepth} levels`;
+    }
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const problem = checkValue(entry, depth + 1, sources, state);
+            if (problem)
+                return problem;
+        }
+        return null;
+    }
+    const object = value;
+    if (isRefObject(object)) {
+        if (typeof object.$ref !== 'string' || typeof object.path !== 'string') {
+            return 'a reference needs a string "$ref" and a string "path"';
+        }
+        if (object.format !== undefined && object.format !== null && typeof object.format !== 'string') {
+            return 'a reference "format" must be a string';
+        }
+        return checkSource(object.$ref, sources, state);
+    }
+    for (const entry of Object.values(object)) {
+        const problem = checkValue(entry, depth + 1, sources, state);
+        if (problem)
+            return problem;
+    }
+    return null;
+}
+/**
+ * Check one step's input. Two step types name their sources outside a reference
+ * object and are read by shape: `repeat` (its `for` clause, with the `as` name a
+ * legal source inside its template) and `merge` (its fields).
+ */
+function checkStepInput(stepType, input, depth, sources, state) {
+    if (isMerge(stepType)) {
+        const mergeSources = readMergeSources(input);
+        if (!mergeSources)
+            return MOCK_MERGE_SHAPE_ERROR;
+        for (const source of mergeSources) {
+            // A merge waits on its sources as STEPS, so a loop variable is not one.
+            if (state.loopVars.has(source)) {
+                return `a merge field cannot read the repeat variable ${JSON.stringify(source)}`;
+            }
+            const problem = checkSource(source, sources, state);
+            if (problem)
+                return problem;
+        }
+        return checkValue(input, depth, sources, state);
+    }
+    if (!isRepeat(stepType))
+        return checkValue(input, depth, sources, state);
+    const repeat = readRepeatInput(input);
+    if (!repeat)
+        return MOCK_REPEAT_SHAPE_ERROR;
+    const { forClause, template } = repeat;
+    const sourceProblem = checkSource(forClause.$ref, sources, state);
+    if (sourceProblem)
+        return sourceProblem;
+    state.loopVars.add(forClause.as);
+    return checkStepInput(template.$type, template.input, depth + 2, new Set([...sources, forClause.as]), state);
+}
+/** The host's refusal text for an unquoted training step (`UNQUOTED_TRAINING_ERROR`). */
+export const MOCK_UNQUOTED_TRAINING_ERROR = 'Training needs a price quote and none could be obtained; try again.';
+/**
+ * The refusal for a body {@link mockWorkflowBodyRefusal} ACCEPTED when the host
+ * could get NO price quote for it, or `null` when it would proceed (reserved at
+ * the ceiling). In the host's order: a training step anywhere (its own
+ * `training-quote-*` refusal — the mock reports `'training-quote-unavailable'`,
+ * the code for "no usable answer"), then a `repeat` anywhere
+ * (`workflow_repeat_unbounded`, naming the first such step).
+ */
+export function mockUnpricedWorkflowRefusal(body) {
+    const types = body.steps.map((step) => collectStepTypes(step.$type, step.input) ?? [step.$type]);
+    if (types.some((ts) => ts.some((t) => t === 'training' || t === 'imageResourceTraining'))) {
+        return { error: MOCK_UNQUOTED_TRAINING_ERROR, errorCode: 'training-quote-unavailable' };
+    }
+    const index = types.findIndex((ts) => ts.some(isRepeat));
+    if (index === -1)
+        return null;
+    return {
+        error: `workflow step ${index}: a workflow with a repeat needs a price quote and none could be obtained; try again`,
+        errorCode: 'workflow_repeat_unbounded',
+    };
+}
+/** The host's wire schema, mirrored: exact keys, types and sizes. No `errorCode`. */
+function isWellFormedBody(body) {
+    if (!isPlainObject(body) || !Object.keys(body).every((key) => BODY_KEYS.has(key)))
+        return false;
+    if (!Array.isArray(body.steps) || body.steps.length === 0)
+        return false;
+    if (body.arguments !== undefined && !isPlainObject(body.arguments))
+        return false;
+    let bytes = body.arguments ? JSON.stringify(body.arguments).length : 0;
+    for (const step of body.steps) {
+        if (!isPlainObject(step) || !Object.keys(step).every((key) => STEP_KEYS.has(key)))
+            return false;
+        const { name, $type, input, suppressOutput } = step;
+        if (typeof $type !== 'string' || $type.length < 1 || $type.length > MOCK_WORKFLOW_BOUNDS.maxTypeChars) {
+            return false;
+        }
+        if (name !== undefined &&
+            (typeof name !== 'string' || name.length < 1 || name.length > MOCK_WORKFLOW_BOUNDS.maxTypeChars)) {
+            return false;
+        }
+        if (!isPlainObject(input))
+            return false;
+        if (suppressOutput !== undefined && typeof suppressOutput !== 'boolean')
+            return false;
+        bytes += JSON.stringify(input).length;
+    }
+    return bytes <= MOCK_WORKFLOW_BOUNDS.maxInputBytes;
+}
+/**
+ * The refusal for a `kind: 'workflow'` body, or `null` for one the mock will
+ * price and run. In the host's order:
+ *
+ *  1. the wire shape — no `errorCode`, the host's schema rejection;
+ *  2. the step cap — `workflow_too_many_steps`;
+ *  3. step by step: the name rules and a `repeat`'s exact shape and nesting
+ *     (`workflow_ref_invalid`); the repeat bound — only over an array in
+ *     `arguments`, at most 16 iterations with nested repeats multiplied
+ *     (`workflow_repeat_unbounded`); then the reference graph
+ *     (`workflow_ref_invalid`). A name is `[a-z][a-z0-9_-]{0,31}` (or the
+ *     step's own `$<index>`), unique, and not `block-step`; every source — a
+ *     reference, a `repeat`'s `for`, a `merge` field — names `$arguments` or an
+ *     EARLIER step, and a `merge` field never names a repeat variable;
+ *  4. a repeat `as` name that is also a step name — `workflow_ref_invalid`;
+ *  5. the step-type denylist on every step and on the step a `repeat` runs —
+ *     `workflow_step_denied`.
+ */
+export function mockWorkflowBodyRefusal(body) {
+    if (!isWellFormedBody(body))
+        return { error: 'invalid workflow body' };
+    const { steps } = body;
+    if (steps.length > MOCK_WORKFLOW_BOUNDS.maxSteps) {
+        return {
+            error: `a workflow may have at most ${MOCK_WORKFLOW_BOUNDS.maxSteps} steps (got ${steps.length})`,
+            errorCode: 'workflow_too_many_steps',
+        };
+    }
+    const invalid = (index, problem) => ({
+        error: `workflow step ${index}: ${problem}`,
+        errorCode: 'workflow_ref_invalid',
+    });
+    const earlier = new Set([ARGUMENTS_REF]);
+    const taken = new Set();
+    const state = { refs: 0, loopVars: new Set() };
+    const stepTypes = [];
+    for (const [index, step] of steps.entries()) {
+        const positional = `$${index}`;
+        const name = mockWorkflowStepName(step, index);
+        if (name !== positional && !STEP_NAME_PATTERN.test(name)) {
+            return invalid(index, `name ${JSON.stringify(name)} must match ${STEP_NAME_PATTERN.source} or be "${positional}"`);
+        }
+        if (name === RESERVED_STEP_NAME)
+            return invalid(index, `name "${RESERVED_STEP_NAME}" is reserved`);
+        if (taken.has(name))
+            return invalid(index, `name ${JSON.stringify(name)} is used twice`);
+        const types = collectStepTypes(step.$type, step.input);
+        if (types === null)
+            return invalid(index, MOCK_REPEAT_SHAPE_ERROR);
+        const unbounded = repeatUnboundedProblem(step.$type, step.input, body.arguments);
+        if (unbounded !== null) {
+            return { error: `workflow step ${index}: ${unbounded}`, errorCode: 'workflow_repeat_unbounded' };
+        }
+        const problem = checkStepInput(step.$type, step.input, 0, earlier, state);
+        if (problem)
+            return invalid(index, problem);
+        taken.add(name);
+        earlier.add(name);
+        stepTypes.push(types);
+    }
+    // A repeat variable that is also a step name (or `$arguments`) would make a
+    // template reference ambiguous between the two.
+    for (const loopVar of state.loopVars) {
+        if (earlier.has(loopVar)) {
+            return {
+                error: `a repeat "as" name ${JSON.stringify(loopVar)} is also a step name or "${ARGUMENTS_REF}"`,
+                errorCode: 'workflow_ref_invalid',
+            };
+        }
+    }
+    for (const [index, types] of stepTypes.entries()) {
+        const denied = types.find((t) => DENIED_LOOKUP.has(t.toLowerCase()));
+        if (denied !== undefined) {
+            return {
+                error: `workflow step ${index}: orchestrator step type '${denied}' is platform-internal and cannot be submitted by an app block`,
+                errorCode: 'workflow_step_denied',
+            };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=mockWorkflowGraph.js.map

package/dist/testing.d.ts

@@ -21,7 +21,7 @@ import { __resetTransport } from './transport/singleton.js';
 import { type MockHostOptions } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
 export { installPopoverShim, type PopoverShimHandle, type PopoverShimOptions, } from './internal/popoverShim.js';
-export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
+export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type MockWorkflowStepInfo, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
 /**
  * Props for the dev {@link Harness}.
  */

package/dist/transport/validate.js

@@ -334,6 +334,41 @@ export function isValidWorkflowSnapshot(s) {
         return false;
     if (s.trainingQuote !== undefined && !isValidTrainingQuote(s.trainingQuote))
         return false;
+    if (s.steps !== undefined && !isValidWorkflowSteps(s.steps))
+        return false;
+    return true;
+}
+/**
+ * Shape check for `steps` — the per-step view of a `kind: 'workflow'` run.
+ * OPTIONAL like its neighbours, and a PRESENT but malformed value rejects the
+ * snapshot: the block reads `name`, `$type`, `status` and `imageUrls` off every
+ * entry.
+ *
+ * `status` is checked against the SAME closed set as the snapshot's own
+ * `status`, unlike the open string unions above: it is typed as that closed
+ * union and a block `switch`es on it, so a snapshot carrying any other value is
+ * dropped rather than handed over. `output` is `unknown` by contract and is not
+ * inspected.
+ */
+function isValidWorkflowSteps(steps) {
+    if (!Array.isArray(steps))
+        return false;
+    for (const step of steps) {
+        if (!isObject(step))
+            return false;
+        if (typeof step.name !== 'string' || typeof step.$type !== 'string')
+            return false;
+        if (typeof step.status !== 'string' || !WORKFLOW_STATUSES.has(step.status))
+            return false;
+        if (step.imageUrls !== undefined) {
+            if (!Array.isArray(step.imageUrls))
+                return false;
+            if (!step.imageUrls.every((u) => typeof u === 'string'))
+                return false;
+        }
+        if (step.error !== undefined && typeof step.error !== 'string')
+            return false;
+    }
     return true;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -58,7 +58,7 @@
     "typescript": "^5.9.2",
     "vite": "^8.0.14",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.65.1"
+    "@civitai/app-sdk": "^0.66.0"
   },
   "publishConfig": {
     "access": "public"