@civitai/blocks-react 0.69.1 → 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
@@ -704,7 +862,10 @@ Any other `'timeout'` is a slow host.
 
 **Mock host:** `createMockHost` and `Harness` price each cell exactly as they
 price one `estimate()` of that body (`costPerGen` and `failEstimate` apply per
-cell). Set `generation.batchEstimate` to `'unsupported'` to test the fallback,
+cell). Like the host, they refuse the **whole call** while the token lacks
+`ai:write:budgeted` — `'failed'`, with `hostError` `block lacks
+ai:write:budgeted scope` — so pass `consentGranted: true`, or drive
+`requestConsent()` and estimate again once the scope lands. Set `generation.batchEstimate` to `'unsupported'` to test the fallback,
 or to `'silent'` to test a call that never gets a reply (pass a short
 `timeoutMs` in a test). Set `generation.batchEstimateTimedOutCells` to a list
 of cell indices to answer those cells the way the host does when its time
@@ -2071,6 +2232,46 @@ on every parameter change. Prompting there would open a consent dialog with no
 user gesture behind it, once per edit. A failed `estimate()` rejects exactly as
 it always has; show no price and let `submit()` do the asking.
 
+The same goes for `useBatchEstimate()`. Until the viewer grants
+`ai:write:budgeted` the host refuses **every** estimate, single and batch, with
+`block lacks ai:write:budgeted scope` (`WorkflowEstimateError` / `BatchEstimateError`,
+code `'failed'`). To show a price before the first Generate, ask on a user
+gesture and estimate again once the grant lands:
+
+```tsx
+import { useEffect, useState } from 'react';
+import { useBlockToken, useBuzzWorkflow, useRequestConsent } from '@civitai/blocks-react';
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+
+function Price({ body }: { body: WorkflowBody }) {
+  const token = useBlockToken();
+  const { requestConsent } = useRequestConsent();
+  const { estimate } = useBuzzWorkflow();
+  const [price, setPrice] = useState<number | null>(null);
+  const canPrice = token.scopes.includes('ai:write:budgeted');
+
+  // Keyed on `canPrice`, so the quote is fetched again when the grant lands.
+  useEffect(() => {
+    if (!canPrice) return;
+    estimate(body).then((s) => setPrice(s.cost?.total ?? null), () => setPrice(null));
+  }, [canPrice, body, estimate]);
+
+  if (!canPrice) {
+    return (
+      <button onClick={() => requestConsent({ scopes: ['ai:write:budgeted'] })}>
+        Allow generations
+      </button>
+    );
+  }
+  return <span>{price === null ? '…' : `${price} Buzz`}</span>;
+}
+```
+
+The mock host enforces this too (since `@civitai/blocks-react` 0.70.0, #608): with
+the default `consentGranted: false` its estimate, batch estimate and submit
+refuse exactly as the host does, `REQUEST_CONSENT` grants and pushes the
+refreshed token, and `consentGrantable: false` keeps the refusal in place.
+
 ```tsx
 // This is the whole thing. No try/catch around a consent prompt, no watching
 // useBlockToken().scopes, no manual retry.
@@ -2622,6 +2823,7 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+MockWorkflowStepInfo
 PopoverShimHandle
 PopoverShimOptions
 ```
@@ -2653,6 +2855,29 @@ host.setScenario({ failMode: 'none' });   // live-tune mid-test
 uninstall();
 ```
 
+🔴 **The mock enforces the spend scope, as the host does** (since `0.70.0`,
+[#608](https://github.com/civitai/civitai-app-starters/issues/608)).
+`consentGranted` defaults to `false` — production's first token does not carry
+`ai:write:budgeted` — and while it is `false`, an estimate, a batch estimate and
+a submit are refused with `block lacks ai:write:budgeted scope`, each in the
+shape the host sends:
+
+| Call | What your code sees before consent |
+|---|---|
+| `estimate()` | rejects `WorkflowEstimateError`, code `'failed'`, reason on `err.snapshot.error` |
+| `estimateBatch()` | rejects `BatchEstimateError`, code `'failed'`, reason on `err.hostError` |
+| `submit()` | prompts for consent, the mock grants it and pushes a refreshed token, and the call is retried once with the **same** idempotency key — it resolves, and is charged once |
+
+`consentGrantable: false` (or `?consent=ungrantable`) keeps the refusal: the
+prompt is answered with `CONSENT_UNAVAILABLE` and `submit()` rejects with code
+`'exception'`.
+
+**Migrating a test:** one that estimates or submits and is not *about* consent
+passes `consentGranted: true` (or uses `?consent=granted` in a harness). One that
+is about consent drives it: estimate, see the refusal, call
+`requestConsent({ scopes: ['ai:write:budgeted'] })`, wait for
+`useBlockToken().scopes` to include it, estimate again.
+
 ### Testing overlay elements
 
 `<civitai-menu>`, and anything else that opens a panel, live in an environment

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
@@ -327,8 +385,14 @@ export declare const MOCK_TRAINING_BOUNDS: {
     readonly captionMaxChars: 1000;
     readonly maxBuzzPerRun: 5000;
 };
-/** The real server's refusal for a training request from a token without the spend scope. */
-export declare const MOCK_TRAINING_SCOPE_ERROR = "block lacks ai:write:budgeted scope";
+/**
+ * The real server's refusal for ANY money call from a token without the spend
+ * scope: civitai's `estimateWorkflow`, `estimateWorkflowBatch`, `submitWorkflow`
+ * and the training procedures all throw `FORBIDDEN` with exactly this message
+ * BEFORE any pricing, rate-limit or budget work. ONE constant for every mock
+ * path that refuses on `consentGranted === false`, so the copies cannot drift.
+ */
+export declare const MOCK_SPEND_SCOPE_ERROR = "block lacks ai:write:budgeted scope";
 /** The real server's refusal for an unknown, expired or spent quote on `RUN_TRAINING`. */
 export declare const MOCK_TRAINING_QUOTE_GONE_ERROR = "training quote not found, expired or already used \u2014 estimate again";
 /** The real server's refusal for a training estimate naming a dataset it does not hold. */
@@ -535,6 +599,16 @@ export interface MockHostOptions {
      * real mint WITHHOLDS it until the viewer consents, so this defaults to
      * `false` — the first token carries NO budgeted scope, and `REQUEST_CONSENT`
      * grants it + pushes a `TOKEN_REFRESH` (the lazy-consent round-trip).
+     *
+     * 🔴 WHILE IT IS `false` THE MOCK ENFORCES THE SCOPE, as the real server does:
+     * `ESTIMATE_WORKFLOW`, `ESTIMATE_WORKFLOW_BATCH` and `SUBMIT_WORKFLOW` (and the
+     * training paths) refuse the whole call with `block lacks ai:write:budgeted
+     * scope`, in the shape the page host sends for each. `submit()` recovers on
+     * its own (its consent prompt-and-retry grants and re-sends with the same
+     * idempotency key); `estimate()` and the batch estimate do NOT retry, so a
+     * block must call `requestConsent({ scopes: ['ai:write:budgeted'] })` and
+     * estimate again once the grant lands. A test that is not ABOUT consent sets
+     * this to `true`.
      */
     consentGranted?: boolean;
     /**