@civitai/blocks-react 0.70.0 → 0.72.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 |
 
@@ -535,12 +535,197 @@ try {
 | `'training-quote-rejected'` | the orchestrator refused the request itself; resending the same body will not help. `error` reads `Training could not be priced: <reason>` when the reason is safe to show |
 | `'training-quote-unavailable'` | no usable answer (an outage, a timeout, a rate limit, insufficient funds, …); a retry may succeed |
 | `'training-quote-unpriced'` | the orchestrator answered without a price |
+| `'daily-limit-exceeded'` | a viewer-confirmed job (a training run or a [confirmed step](#userunconfirmedstep--one-job-above-the-per-call-budget)) would exceed what remains today of the daily Buzz limit **the viewer** set for this app. Nothing was charged, no job started, and only the viewer can raise the limit. Arrives on a confirmed submit's failed snapshot, never on an estimate; `useRunConfirmedStep()` surfaces it as `err.dailyLimitExceeded` |
 | absent | any other reply, and every reply from a host that predates the field |
 
 - **Treat an unknown value as possible.** The field is typed as an open string
   (`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 `kind: 'training'` **estimate** does not set it; the three `training-quote-*`
+  codes belong to the pass-through arm.
+- A refused `kind: 'workflow'` body sets its own 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 has no estimate, but its submit still
+   proceeds.** `estimate()` rejects with a `workflow_quote_*` `errorCode` and
+   no `cost` (see the second table under Refusals), and a batch estimate
+   returns that as the cell. `submit()` of the same body is **not** refused: it
+   reserves the ceiling above instead of a quote. So a failed estimate does not
+   predict a refused submit. Two exceptions are refused on both, 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`). Their `error` states why there
+   is no quote, and only `none could be obtained; try again` is a cause a retry
+   of the same body can clear; for the others the body has to change.
+   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, 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 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>`; a retry of the same body can work only when `<cause>` is `none could be obtained; try again` |
+
+A body the host WOULD run, but has no price quote for, fails on `estimate()`
+and as a batch-estimate cell only, with no `cost`. `submit()` of the same body
+still proceeds (point 2 above):
+
+| `errorCode` | Means | `error` | Retry the same body? |
+|---|---|---|---|
+| `'workflow_quote_rejected'` | the orchestrator refused the body | `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)` | no — change the body |
+| `'workflow_quote_unavailable'` | no usable answer (an outage, a timeout, a rate limit, …) | `No price quote for this workflow: none could be obtained; try again` | yes |
+| `'workflow_quote_unpriced'` | the orchestrator answered without a price | `No price quote for this workflow: the orchestrator answered without one` | not expected to help |
+
+An older host has none of the three: it resolves the estimate with the ceiling
+as `cost.total`.
+
+- **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 of the first table,
+  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` to
+  `'rejected'`, `'unavailable'` or `'unpriced'` (`true` means `'unavailable'`),
+  which simulates no quote for that cause: a workflow with a training step or a
+  `repeat` is refused on both `estimate()` and `submit()`; any other fails its
+  `estimate()` with `workflow_quote_<cause>` and no `cost`, while its
+  `submit()` is reserved at `buzzBudget` × steps with no fee. The mock has no
+  orchestrator reason to pass on, so `'rejected'` always gives the reason-less
+  message, never the `…rejected the request: <reason>` form.
 
 > **Estimate must mirror submit** (gotcha #59): build the params for `estimate`
 > with the *exact* same logic as `submit` — same seed decision especially. The
@@ -575,6 +760,11 @@ resolves with one cell per body, in order, plus the run total. Returns
   `WorkflowEstimateError`, and the other cells still price.
 - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
   with `useBuzzWorkflow().estimate()`.
+- **A cell never carries a `stepQuote`.** A batch stores nothing, so a
+  pass-through step priced above the per-call budget comes back with its cost and
+  no confirmable quote. To run it with
+  [`useRunConfirmedStep()`](#userunconfirmedstep--one-job-above-the-per-call-budget),
+  estimate that one body with `useBuzzWorkflow().estimate()`.
 - **Estimate only.** Nothing is submitted and no Buzz is held or spent. There is
   no batch submit. Submit each cell with
   `useBuzzWorkflow().submit()`, which asks the viewer and checks the budget per
@@ -1222,6 +1412,191 @@ server compares the whole body.
 **`dev:live` refuses both bridges**, because the server refuses every training
 request from a dev token.
 
+### `useRunConfirmedStep()` — one job above the per-call budget
+
+A pass-through `step` job (`{ kind: 'step', $type, input, maxBuzz }`) that costs
+more than the app may spend without asking is refused by `submit()` — unless the
+**viewer confirms that exact price** in Civitai's own dialog. This hook is that
+path. It is the training run's confirm applied to any pass-through `$type`
+(`polyGen`, a long video job, …). Three steps, two hooks:
+
+1. **Quote** — `useBuzzWorkflow().estimate(body)`, the body you would submit. When
+   the job qualifies the reply carries `stepQuote: { quoteId, total, stepType,
+   expiresAt }`. `total` is the price the viewer will confirm and be charged.
+2. **Run** — `useRunConfirmedStep().runConfirmedStep({ ...body, quoteId })`
+   (`RUN_CONFIRMED_STEP`). Civitai reads the quote back from the server, shows
+   the viewer the price in **its** chrome and submits on their click. Resolves
+   with the submitted workflow's snapshot.
+3. **Watch** — `useBuzzWorkflow().watch(snapshot.workflowId)`, as for any job.
+
+No `stepQuote` on the estimate means the ordinary rules apply: submit it if it
+fits the budget, and otherwise it cannot run from an app. Change nothing in the
+body between the estimate and the run — the server checks it against the quoted
+one.
+
+🔴 **Only a fixed price is confirmable.** `stepQuote` is present when the
+orchestrator quoted a **fixed** price (positive, not variable or metered) that is
+above the token's per-call `buzzBudget` and at most
+`BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB` (5,000 Buzz). The viewer confirms what
+they are charged, so a price that may move, or no price at all, gets no quote.
+`stepQuote.total` can differ from `cost.total` on the same snapshot (which stays
+what an unconfirmed submit would reserve) — put `stepQuote.total` on your button.
+
+🔴 **Estimate it on its own.** Only a single `estimate()` returns a `stepQuote`.
+A batch estimate (`useBatchEstimate()`) stores nothing, so its cells never carry
+one: price the grid in a batch, then estimate the one body you want to run.
+
+🔴 **Two bodies make the estimate reject instead of returning a price.** Only
+where a quote would otherwise be granted, so not below the budget and not in a
+batch. `estimate()` rejects with a `WorkflowEstimateError` whose
+`snapshot.error` is the server's message; the same text is the
+`RunConfirmedStepError`'s `message` if such a body is run. Neither has a code or
+a flag — they are server messages, so match on the text:
+
+| `snapshot.error` / `err.message` | cause | fix |
+|---|---|---|
+| `a training step type cannot run as a confirmed step — use kind:'training'` | `$type` is `training` or `imageResourceTraining`, in any casing | train with [`kind: 'training'`](#usepreparetrainingdataset-and-useruntraining--lora-training), which has its own dataset and checks |
+| starts with `a confirmed step needs plain JSON input (objects, arrays, strings, finite numbers, booleans, null) — ` and ends with the offending path, e.g. `body.input.when is a Date` | `input` holds something that is not plain JSON: a `Date`, `Map`, `Set`, class instance, `BigInt`, `NaN`/`Infinity`, an `undefined` array element, or an empty slot in a sparse array (`… is an empty array slot`). The quote is bound to the exact body, so the body must be exactly representable | send plain JSON (an ISO string for a date, an array for a set). The suffix varies, so match on the part **before the dash** |
+
+🔴 **Single-use, and it expires.** A quote is good for one run and for **15
+minutes** (`stepQuote.expiresAt`). The server prices the job again at submit and
+refuses a higher price. Estimate again to get a new one.
+
+🔴 **Availability.** Behind the host flag **`app-blocks-confirmed-step`**, which
+ships **off** and is evaluated per viewer; requires a civitai.com host carrying
+civitai/civitai#5786. **Page apps only** — the model slot answers with an error.
+The manifest must declare **`ai:write:budgeted`** and the viewer must be signed
+in and have granted it. **Refused for development, dev-tunnel and review
+tokens**, so **`dev:live` cannot exercise it**: the estimate there never carries
+a `stepQuote` and the bridge replies with a refusal. Build the flow against the
+mock host (below). Where the feature is unavailable nothing errors — the estimate
+simply has no `stepQuote`, which is also what an older host sends.
+
+🔴 **No retry, ever.** Every confirmation is its own job: there is no idempotency
+key, and confirming the same body twice starts and charges two jobs. The hook
+never re-sends and never prompts for consent, and `useBuzzWorkflow().submit()`
+**refuses** a step body that carries a `quoteId` before sending anything — only
+`RUN_CONFIRMED_STEP`'s dialog can confirm a quote. `runConfirmedStep` also
+refuses, before sending, a body whose `quoteId` is missing or is not an
+`sq_`-shaped id (a training `tq_…` quote, or `undefined` from an estimate that
+returned no `stepQuote`).
+
+`runConfirmedStep` **rejects** with a `RunConfirmedStepError`; read the flags
+before saying anything about money:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the confirm — **no job was submitted**; the quote is still good until it expires | revert, say nothing |
+| `err.dailyLimitExceeded` | the job would exceed what remains today of the daily Buzz limit **the viewer** set for this app — **no job, nothing charged**. Civitai has already told the viewer and linked to where the limit is raised | say nothing more; do **not** retry and do **not** offer a Buzz purchase (more Buzz does not lift a limit) |
+| `err.unconfirmed` | `submission-unconfirmed`, or no reply within the 10-min bound (`err.timedOut`) — the job **may be running and charged** | 🔴 **never retry automatically**: check the viewer's generations first (`useAppWorkflows()` lists this app's runs). A retry needs a new estimate and a new confirmation, and is a **second, separately charged job** if the first one started |
+| `err.refused` (`code: 'refused'`) | the server refused the submit after the viewer confirmed — a **spend cap** (their daily or private-run Buzz cap, the app's daily spend or rate limit). Refunded: **no job, nothing charged**; the quote is used up | show `err.message` (the server's reason); a retry needs a new estimate and usually a later time |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `invalid confirmed step request` / `no block token`) | show or ignore per case |
+| `err.code === undefined`, no flag | a server refusal with no job started (expired or used quote, changed body, changed price, a training `$type`, non-plain-JSON `input`, the flag is off) | fix the body if the message names it, estimate again, then retry |
+
+```tsx
+const { estimate, submit, watch } = useBuzzWorkflow();
+const { runConfirmedStep } = useRunConfirmedStep();
+const { requestSignIn } = useRequestSignIn();
+
+async function generate3d(prompt: string) {
+  const body: WorkflowBodyPassThroughStep = {
+    kind: 'step',
+    $type: 'polyGen',
+    input: { prompt },
+    maxBuzz: 250,
+  };
+  const quote = (await estimate(body)).stepQuote;
+
+  try {
+    const started = quote
+      ? // Over the per-call budget: the viewer confirms `quote.total` in Civitai's dialog.
+        await runConfirmedStep({ ...body, quoteId: quote.quoteId })
+      : // Within it (or not confirmable): the ordinary path.
+        await submit(body);
+    return await watch(started.workflowId);
+  } catch (err) {
+    if (!(err instanceof RunConfirmedStepError)) throw err;
+    if (err.declined) return; // no job — say nothing
+    if (err.dailyLimitExceeded) return; // no job — Civitai already told the viewer
+    if (err.signInRequired) return requestSignIn();
+    if (err.unconfirmed) return showCheckYourGenerations(); // may be running — never auto-retry
+    if (err.refused) return showError(err.message); // a cap refusal; no job, nothing charged
+    showError('Could not start this job. Get a new price and try again.');
+  }
+}
+```
+
+**With the mock host** — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — this is the only place the flow can be
+exercised before a production host has it. A pass-through `step` estimate carries
+a `stepQuote` whenever the mock's price for it (`generation.costPerGen`, or
+`cost`) is above the token's per-call budget (`buzzBudget`, default 200) and at
+most 5,000, for a signed-in viewer; there is no separate switch. As on the
+server, a batch-estimate cell never carries one, and where a quote would be
+granted the estimate fails instead, with the server's message, for a training
+`$type` and for non-plain-JSON `input`. The mock holds the quotes it stored and
+refuses an unknown, expired or already-run one, a body that differs from the
+quoted one, and a plain `SUBMIT_WORKFLOW` carrying a `quoteId`. How the run
+settles is `runConfirmedStepError`:
+
+| `runConfirmedStepError` | URL | outcome |
+|---|---|---|
+| unset | — | the viewer confirms; the job starts, charged `stepQuote.total` |
+| `'declined'` | `?confirmedStep=declined` | `err.declined`; the quote survives |
+| `'daily-limit-exceeded'` | `?confirmedStep=daily-limit` | `err.dailyLimitExceeded`; the quote survives |
+| `'submission-unconfirmed'` | `?confirmedStep=unconfirmed` | `err.unconfirmed`; the quote is used up |
+| any other string | — | a server message; the quote is used up |
+
+`runConfirmedStepCapRefusal` resolves the server's refunded cap refusal
+(`err.refused`), and both knobs are live-tunable with `host.setScenario(...)`.
+
+```tsx
+import { createMockHost } from '@civitai/blocks-react/testing';
+
+const host = createMockHost({
+  consentGranted: true,
+  generation: { costPerGen: 800 }, // above the default 200 per-call budget → quoted
+  runConfirmedStepError: 'declined',
+});
+const uninstall = host.install();
+// …later: the viewer confirms this time.
+host.setScenario({ runConfirmedStepError: undefined });
+```
+
+What the mock does **not** model: it has no dialog, so the run settles at once
+where the real host waits on a click; it prices every estimate as fixed, where
+the real host gives a variable or metered price no `stepQuote`; and the flag, the
+page-only rule and the submit-time re-price are server-side.
+
+#### 3D outputs: `model3dOutputs`
+
+A step that produces 3D models (`polyGen`) lists every model url in
+`snapshot.imageUrls`, as before. `snapshot.model3dOutputs` says which is which:
+one `{ url, format, variant }` per model, where `format` is the model's own file
+format (`'glb'`, `'fbx'`, …) and `variant` is the output it came from (`'model'`,
+`'riggedFbxModel'`, `'basicAnimations.walkingModel'`, …). Both are open sets
+named by the orchestrator. The field is **omitted** when the workflow produced no
+3D model and on hosts that predate it, and the same field is on each
+`useAppWorkflows()` row.
+
+```tsx
+function modelsOf(snapshot: BlockWorkflowSnapshot) {
+  const models = snapshot.model3dOutputs ?? [];
+  return {
+    // The plain mesh, in the format a web viewer loads.
+    glb: models.find((m) => m.format === 'glb' && m.variant === 'model')?.url,
+    // The rigged export, for a download button.
+    riggedFbx: models.find((m) => m.variant === 'riggedFbxModel')?.url,
+    // Every animation clip, whatever the host named them.
+    animations: models.filter((m) => m.variant.startsWith('basicAnimations.')),
+  };
+}
+```
+
+In the mock host, `generation.model3dOutputs` puts labels (and their urls in
+`imageUrls`) on a succeeded pass-through step.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -1560,6 +1935,20 @@ if (isModelSlotContext(context) && context.checkpoint) {
 }
 ```
 
+🔴 **`persist()` works on a model slot only. On a page it always rejects.** A
+full-page app (`app.page`) is bound to no model, so the host has nowhere to write
+the override: it answers every `persist()`, including `persist(null)`, with
+`ok: false`, and the promise rejects with `page blocks cannot persist a
+checkpoint override (no model binding)`. A page app keeps the checkpoint `open()`
+returned in its own state (or in `useAppStorage()`).
+
+Both dev hosts (`createMockHost` / `Harness` and `dev:live`) refuse it the same
+way, and both default to a page context. Pass a complete `ModelSlotContext` as
+`context` to exercise a block that persists. A test that expected `persist()` to
+resolve under the default mock context was asserting something a page app never
+gets: give it the model slot the block really runs in, or, for a page app, drop
+the `persist()` call.
+
 ### `useResourcePicker()`
 
 Drive the platform resource picker for page blocks — `'Checkpoint' | 'LORA'`.
@@ -2665,6 +3054,8 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+MockWorkflowQuoteFailure
+MockWorkflowStepInfo
 PopoverShimHandle
 PopoverShimOptions
 ```
@@ -2863,6 +3254,21 @@ const host = createLiveHost(options);
 const uninstall = host.install();
 ```
 
+What `dev:live` forwards, and how it answers the one call it does not:
+
+- **`useCheckpointPicker().persist()` on a page** is refused with no backend
+  call, as the page host refuses it (see
+  [`useCheckpointPicker()`](#usecheckpointpicker)). The default `context` is a
+  page, because a dev token is a page token.
+- **`submit()`'s `idempotencyKey` reaches the server**, as it does from the
+  production hosts. A retry with the same key is deduplicated there, and a key in
+  a format the server refuses fails the submit with the server's message.
+- **`watch()`'s `waitSeconds` reaches the server**, so a poll is held open
+  instead of answered at once, and the server decides the actual hold. This
+  matches the production hosts as of
+  [civitai/civitai#5798](https://github.com/civitai/civitai/pull/5798); a
+  production host without that change drops the field and answers at once.
+
 ### Stability of `/live`
 
 The same terms as `./testing`: a normal subpath of a `0.x` package where a minor

package/dist/hooks/useBatchEstimate.d.ts

@@ -162,6 +162,10 @@ export interface UseBatchEstimate {
  * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
  * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
  *   with `useBuzzWorkflow().estimate()`.
+ * - **A cell never carries a `stepQuote`.** A batch stores nothing, so a
+ *   pass-through step priced above the per-call budget comes back with its cost
+ *   and no confirmable quote. To run it with `useRunConfirmedStep()`, estimate
+ *   that one body with `useBuzzWorkflow().estimate()`.
  *
  * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
  * list. To watch and cancel the submitted cells together, use

package/dist/hooks/useBatchEstimate.js

@@ -104,6 +104,10 @@ function toBatchEstimateError(err) {
  * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
  * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
  *   with `useBuzzWorkflow().estimate()`.
+ * - **A cell never carries a `stepQuote`.** A batch stores nothing, so a
+ *   pass-through step priced above the per-call budget comes back with its cost
+ *   and no confirmable quote. To run it with `useRunConfirmedStep()`, estimate
+ *   that one body with `useBuzzWorkflow().estimate()`.
  *
  * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
  * list. To watch and cancel the submitted cells together, use

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -13,6 +13,22 @@ import type { ConsentRetryOptions } from './consentRetryOptions.js';
  * on that class is money-ambiguous by design).
  */
 export declare const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body \u2014 estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a pass-through `step` body that
+ * carries a `quoteId`.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, for the same reason as
+ * {@link TRAINING_BODY_SUBMIT_REFUSAL}. A `quoteId` on a pass-through body means
+ * "charge this job against the price the viewer confirmed", and only
+ * `RUN_CONFIRMED_STEP`'s host-chrome dialog can record that confirmation — so a
+ * `SUBMIT_WORKFLOW` carrying one can never start the job; the server refuses it
+ * as unconfirmed. Nothing is sent and nothing is spent, which is why this too is
+ * a plain `Error` and not a {@link WorkflowSubmitError}.
+ *
+ * The same body WITHOUT `quoteId` is an ordinary pass-through submit and is not
+ * affected.
+ */
+export declare const CONFIRMED_STEP_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a step body that carries a quoteId \u2014 run it with useRunConfirmedStep().runConfirmedStep(body), or drop quoteId to submit it as an ordinary job. Nothing was sent.";
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -486,6 +502,17 @@ export interface UseBuzzWorkflow {
      * A `kind: 'training'` body's reply also carries
      * {@link BlockWorkflowSnapshot.trainingQuote} — the `quoteId` to run it with
      * through `useRunTraining()`.
+     *
+     * A pass-through `step` body's reply carries
+     * {@link BlockWorkflowSnapshot.stepQuote} when its FIXED price is above the
+     * token's per-call budget (and within the per-job ceiling). That job cannot
+     * run through {@link UseBuzzWorkflow.submit}; run it with
+     * `useRunConfirmedStep().runConfirmedStep({ ...body, quoteId:
+     * stepQuote.quoteId })`, which has the viewer confirm `stepQuote.total`. No
+     * `stepQuote` means the ordinary rules apply — it is also what a host without
+     * the feature sends. Where a quote would be granted, this REJECTS instead for
+     * a training `$type` or an `input` that is not plain JSON (see
+     * {@link BlockWorkflowSnapshot.stepQuote} for the two messages).
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -589,6 +616,9 @@ export interface UseBuzzWorkflow {
      *
      * 🔴 A `kind: 'training'` BODY IS REFUSED before anything is sent — it runs
      * only through `useRunTraining()`. See {@link TRAINING_BODY_SUBMIT_REFUSAL}.
+     * So is a pass-through `step` body that carries a `quoteId` — it runs only
+     * through `useRunConfirmedStep()`. See
+     * {@link CONFIRMED_STEP_BODY_SUBMIT_REFUSAL}.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -698,6 +728,24 @@ 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 FAILS `estimate()` with a
+ *    `workflow_quote_*` `errorCode` and no `cost`, yet 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 on both); an older host returns that ceiling as the estimate;
+ *  - 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

@@ -30,6 +30,22 @@ const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
  * on that class is money-ambiguous by design).
  */
 export const TRAINING_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a kind:'training' body — estimate it here, then run it with useRunTraining().runTraining({ ...body, quoteId }). Nothing was sent.";
+/**
+ * Why {@link UseBuzzWorkflow.submit} refuses a pass-through `step` body that
+ * carries a `quoteId`.
+ *
+ * 🔴 REFUSED BEFORE THE SEND, for the same reason as
+ * {@link TRAINING_BODY_SUBMIT_REFUSAL}. A `quoteId` on a pass-through body means
+ * "charge this job against the price the viewer confirmed", and only
+ * `RUN_CONFIRMED_STEP`'s host-chrome dialog can record that confirmation — so a
+ * `SUBMIT_WORKFLOW` carrying one can never start the job; the server refuses it
+ * as unconfirmed. Nothing is sent and nothing is spent, which is why this too is
+ * a plain `Error` and not a {@link WorkflowSubmitError}.
+ *
+ * The same body WITHOUT `quoteId` is an ordinary pass-through submit and is not
+ * affected.
+ */
+export const CONFIRMED_STEP_BODY_SUBMIT_REFUSAL = "useBuzzWorkflow.submit() does not run a step body that carries a quoteId — run it with useRunConfirmedStep().runConfirmedStep(body), or drop quoteId to submit it as an ordinary job. Nothing was sent.";
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -523,6 +539,24 @@ 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 FAILS `estimate()` with a
+ *    `workflow_quote_*` `errorCode` and no `cost`, yet 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 on both); an older host returns that ceiling as the estimate;
+ *  - 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
@@ -749,6 +783,15 @@ export function useBuzzWorkflow() {
             setStatus('error');
             throw refused;
         }
+        // See `CONFIRMED_STEP_BODY_SUBMIT_REFUSAL`. Keyed on the PRESENCE of a
+        // `quoteId`, whatever its shape: a malformed one is no more submittable
+        // than a well-formed one, and the server would refuse both.
+        if (body.kind === 'step' && body.quoteId !== undefined) {
+            const refused = new Error(CONFIRMED_STEP_BODY_SUBMIT_REFUSAL);
+            setError(refused);
+            setStatus('error');
+            throw refused;
+        }
         setError(null);
         setStatus('submitting');
         // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz

package/dist/hooks/useCheckpointPicker.d.ts

@@ -54,6 +54,8 @@ export interface UseCheckpointPicker {
  * host. Pass `null` to clear the override and fall back to the publisher
  * default at next mount. Throws on host-side validation failure (e.g.
  * "wrong-ecosystem") — surface the message to the user; don't retry blindly.
+ * MODEL SLOTS ONLY: on a page (`app.page`) the host refuses every `persist`,
+ * so it always throws there; a page app keeps the pick in its own state.
  *
  * Both flows are host-mediated: the block never touches the picker UI or
  * the user-settings table directly. Same trust model as useBuzzPurchase /

package/dist/hooks/useCheckpointPicker.js

@@ -15,6 +15,8 @@ import { sendTypedRequest } from '../transport/transport.js';
  * host. Pass `null` to clear the override and fall back to the publisher
  * default at next mount. Throws on host-side validation failure (e.g.
  * "wrong-ecosystem") — surface the message to the user; don't retry blindly.
+ * MODEL SLOTS ONLY: on a page (`app.page`) the host refuses every `persist`,
+ * so it always throws there; a page app keeps the pick in its own state.
  *
  * Both flows are host-mediated: the block never touches the picker UI or
  * the user-settings table directly. Same trust model as useBuzzPurchase /