@civitai/blocks-react 0.68.0 → 0.69.0

package/README.md

@@ -495,6 +495,53 @@ if (quote.cost) showPrice(priceLine(quote.cost));
   reports `authorFee: 0`, and `authorFee: false` (`?authorFee=off`) leaves it
   out, as an older host does.
 
+#### Why a training step could not be priced: `snapshot.errorCode`
+
+A pass-through `step` body whose `$type` is a training type (`'training'` or
+`'imageResourceTraining'`) needs a price quote; when the host cannot get one it
+refuses with `{ workflowId: 'failed', status: 'failed', error, errorCode }` and
+no `cost`. `estimate()` rejects with a `WorkflowEstimateError` and `submit()`
+with a `WorkflowSubmitError` (before anything is reserved), and a batch
+estimate returns it as that body's cell. `errorCode` is the stable value to
+branch on; `error` stays the diagnostic read.
+
+```tsx
+import { useBuzzWorkflow, WorkflowEstimateError } from '@civitai/blocks-react';
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+
+const { estimate } = useBuzzWorkflow();
+declare const body: WorkflowBody;
+
+try {
+  await estimate(body);
+} catch (err) {
+  if (!(err instanceof WorkflowEstimateError)) throw err;
+  switch (err.snapshot.errorCode) {
+    case 'training-quote-rejected': // the request itself was refused — change it
+      showError('These training settings were refused. Check them and try again.');
+      break;
+    case 'training-quote-unavailable': // no answer right now — retrying may work
+    case 'training-quote-unpriced': // answered without a price
+      showError('Training cannot be priced right now. Try again shortly.');
+      break;
+    default: // no code, or one a later host added
+      showError('Could not get a price.');
+  }
+}
+```
+
+| `errorCode` | Means |
+|---|---|
+| `'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 |
+| 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.
+
 > **Estimate must mirror submit** (gotcha #59): build the params for `estimate`
 > with the *exact* same logic as `submit` — same seed decision especially. The
 > orchestrator whatif prices a cache hit (identical workflow) at 0 and a fresh
@@ -529,10 +576,11 @@ resolves with one cell per body, in order, plus the run total. Returns
 - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
   with `useBuzzWorkflow().estimate()`.
 - **Estimate only.** Nothing is submitted and no Buzz is held or spent. There is
-  no batch submit, watch or cancel. Submit each cell with
+  no batch submit. Submit each cell with
   `useBuzzWorkflow().submit()`, which asks the viewer and checks the budget per
   cell. `aggregate.total` is a quote, not a lock: each cell is priced again when
-  it is submitted.
+  it is submitted. To follow the submitted cells and cancel them together, see
+  [`useWorkflowBatch()`](#useworkflowbatch).
 
 `aggregate.total` sums the cells that priced. It covers the whole grid only when
 `aggregate.pricedCells === aggregate.cellCount`; otherwise show it as a partial
@@ -664,6 +712,121 @@ budget runs out (`ok: false`, `timedOut: true`). **`dev:live`** forwards the cal
 a civitai.com that predates the batch procedure it rejects with `'failed'`
 rather than `'unsupported'`.
 
+### `useWorkflowBatch()`
+
+Watch a set of already-submitted workflows as one batch: per-cell status, a
+summary, and cancel-all. Built for grid apps that submit each cell with
+`useBuzzWorkflow().submit()` (each with its own confirmation, unchanged) and
+then have to follow all of them. `useWorkflowBatch(workflowIds, options?)`
+returns `{ cells, summary, cancelAll, rewatch }`.
+
+- **The array of ids is the batch.** There is no server-side batch id. Append
+  each id as its `submit()` resolves, and persist the same array (plain
+  strings) to re-attach after a reload by passing it back. Skip a submit that
+  resolved with the `'failed'` placeholder id: nothing was created.
+- **Every cell is one ordinary `watch()`**, so each workflow has exactly one
+  poll in flight. When a cell's loop restarts (the list changes, `rewatch()`,
+  a StrictMode remount) the new loop waits for the old loop's poll to return.
+  `options` (`intervalMs`, `waitSeconds`, `timeoutMs`, `maxRetries`) are passed
+  to every cell's `watch()`.
+- **At most 30 ids** (`WORKFLOW_BATCH_MAX_CELLS`): the poll allowance (1,200 per
+  60 s per block instance and viewer) divided by one watch's 40 polls a minute.
+  A longer list, a duplicate, an empty id or a `'failed'`/`'whatif'`
+  placeholder throws.
+- **`summary`** counts `succeeded`, `failed`, `canceled`, `expired` and `running`
+  (not terminal, including cells with no snapshot yet) from each cell's latest
+  snapshot, plus `realisedCost`: the sum of `cost.total` on the terminal
+  snapshots that carry one. That is the generation cost the host reported, not a
+  ledger read; the author fee is charged separately and is not included.
+  `settled` is `running === 0`.
+- **A host failure placeholder is not a workflow outcome.** When the host fails
+  a poll it answers `{ workflowId: 'failed', status: 'failed' }`. That says
+  nothing about the workflow, so the cell is not counted as failed: its `phase`
+  becomes `'stopped'` with `error` set, and `summary.stopped` counts it. A
+  stopped cell (also a watch that timed out or ran out of retries) is not
+  polled again until you call `rewatch()`.
+- **`cancelAll()` cancels every cell not known to be finished** and resolves
+  (never rejects) with `{ canceled, alreadySettled, refused, notAttempted,
+  failed, complete }`, each a list of ids. Cancels charge the estimate allowance
+  (150 per 10 s per block instance; on a page app every viewer shares it), so at
+  most four are in flight. A refused cancel resolves `status: 'processing'`: it
+  was not sent and the workflow is still running. After the first refusal the
+  rest of the call is not sent (`notAttempted`). A cancel answered with the
+  host's failure placeholder is `failed`, not a failed workflow. Nothing is
+  retried automatically. When `complete` is `false`, wait a few seconds and call
+  `cancelAll()` again; it targets only cells that are still not finished.
+- **Unmounting stops every poll.** A `cancelAll()` already running keeps sending.
+
+```tsx
+import { useEffect, useState } from 'react';
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+import { useBuzzWorkflow, useWorkflowBatch } from '@civitai/blocks-react';
+
+const SAVED = 'grid-run-ids';
+
+function GridRun({ bodies }: { bodies: WorkflowBody[] }) {
+  const { submit } = useBuzzWorkflow();
+  const [ids, setIds] = useState<string[]>(() => {
+    try {
+      return JSON.parse(localStorage.getItem(SAVED) ?? '[]') as string[];
+    } catch {
+      return [];
+    }
+  });
+  useEffect(() => {
+    try {
+      localStorage.setItem(SAVED, JSON.stringify(ids));
+    } catch {
+      // Storage can be unavailable; the run still works, it just won't re-attach.
+    }
+  }, [ids]);
+
+  const { cells, summary, cancelAll, rewatch } = useWorkflowBatch(ids);
+  const [cancelNote, setCancelNote] = useState<string | null>(null);
+
+  async function runCell(body: WorkflowBody, key: string) {
+    const snap = await submit(body, { idempotencyKey: key });
+    if (snap.workflowId !== 'failed') setIds((prev) => [...prev, snap.workflowId]);
+  }
+
+  async function onCancelAll() {
+    const result = await cancelAll();
+    setCancelNote(
+      result.complete
+        ? null
+        : `${result.refused.length + result.notAttempted.length + result.failed.length} cells are still running. Try again in a few seconds.`,
+    );
+  }
+
+  return (
+    <div>
+      <button onClick={() => bodies.forEach((b, i) => void runCell(b, `cell-${i}`))}>Run grid</button>
+      <p>
+        {summary.succeeded} done, {summary.failed} failed, {summary.canceled} cancelled,{' '}
+        {summary.running} running. Spent {summary.realisedCost} Buzz.
+      </p>
+      {!summary.settled && <button onClick={onCancelAll}>Cancel all</button>}
+      {summary.stopped > 0 && <button onClick={rewatch}>Refresh stalled cells</button>}
+      {cancelNote && <p>{cancelNote}</p>}
+      <ul>
+        {cells.map((cell) => (
+          <li key={cell.workflowId}>{cell.snapshot?.status ?? 'queued'}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+**Mock host:** `createMockHost` and `Harness` keep a cancelled workflow
+cancelled on later polls, report a finished workflow's real status when it is
+cancelled, and count down an id they did not submit (one restored after a
+reload) like any other. Set `generation.cancelRefused` to `true` (or a list of
+workflow ids) to answer cancels the way the host does when the allowance is used
+up, and `generation.workflowOutcome` to a `(workflowId, body) => 'succeeded' |
+'failed' | 'expired'` function to give a grid a mix of outcomes. The mock does
+not model the rate limits themselves.
+
 ### `useBuzzPurchase()`
 
 Open the Buzz purchase modal. It raises the viewer's WALLET, never a spend cap:

package/dist/hooks/useBatchEstimate.d.ts

@@ -163,9 +163,10 @@ export interface UseBatchEstimate {
  * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
  *   with `useBuzzWorkflow().estimate()`.
  *
- * 🔴 ESTIMATE ONLY. There is no batch submit, watch or cancel and no id for the
- * list. The total is a quote: nothing reserves it and each cell is priced again
- * at `submit()`.
+ * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
+ * list. To watch and cancel the submitted cells together, use
+ * `useWorkflowBatch()`. The total is a quote: nothing reserves it and each cell
+ * is priced again at `submit()`.
  *
  * Like `estimate()`, this does NOT prompt for consent. It needs the
  * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.

package/dist/hooks/useBatchEstimate.js

@@ -105,9 +105,10 @@ function toBatchEstimateError(err) {
  * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
  *   with `useBuzzWorkflow().estimate()`.
  *
- * 🔴 ESTIMATE ONLY. There is no batch submit, watch or cancel and no id for the
- * list. The total is a quote: nothing reserves it and each cell is priced again
- * at `submit()`.
+ * 🔴 ESTIMATE ONLY. There is no batch submit and no server-side id for the
+ * list. To watch and cancel the submitted cells together, use
+ * `useWorkflowBatch()`. The total is a quote: nothing reserves it and each cell
+ * is priced again at `submit()`.
  *
  * Like `estimate()`, this does NOT prompt for consent. It needs the
  * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.

package/dist/hooks/useWorkflowBatch.d.ts

@@ -0,0 +1,196 @@
+import type { BlockWorkflowSnapshot } from '@civitai/app-sdk/blocks';
+import type { WatchWorkflowOptions } from './useBuzzWorkflow.js';
+/**
+ * The most workflows one {@link useWorkflowBatch} may watch.
+ *
+ * Derived from the host's poll allowance, not picked: one watched workflow makes
+ * at most 60 / 1.5 = 40 polls a minute (one poll in flight, `intervalMs` 1,500
+ * between polls), and the viewer's poll allowance is 1,200 per 60 s per block
+ * instance, so 1,200 / 40 = 30 workflows is the most one viewer can watch before
+ * polls start coming back as placeholders. The developer docs' limits table
+ * gives the same figure. A list longer than this throws, because an app that
+ * needs more cells needs a different plan than "watch them all at once".
+ */
+export declare const WORKFLOW_BATCH_MAX_CELLS = 30;
+/**
+ * Where a cell's watch stands.
+ *
+ * - `'watching'` — a `watch()` loop is running for it.
+ * - `'settled'` — its latest snapshot is terminal. Nothing is polling it.
+ * - `'stopped'` — nothing is polling it and it is NOT known to be finished: the
+ *   watch timed out (`timeoutMs`), gave up after `maxRetries` failed polls, or the
+ *   host answered a poll with its failure placeholder instead of this workflow's
+ *   status. The workflow may still be running. `error` says why when there was an
+ *   error. Call {@link UseWorkflowBatch.rewatch} to start watching it again.
+ */
+export type WorkflowBatchCellPhase = 'watching' | 'settled' | 'stopped';
+/**
+ * Where a cell's most recent cancel request stands.
+ *
+ * - `'idle'` — no cancel was asked for.
+ * - `'pending'` — a cancel request is in flight.
+ * - `'done'` — the host answered with a terminal snapshot. Usually `canceled`,
+ *   but a workflow that finished before the cancel landed reports its real
+ *   status (`succeeded`, `failed`, `expired`).
+ * - `'refused'` — not cancelled. The host answered with a NON-terminal snapshot
+ *   (its answer when the estimate allowance is used up: the cancel was not sent),
+ *   or this cell was not attempted because an earlier cancel in the same
+ *   `cancelAll()` was refused. The workflow is still running. Call `cancelAll()`
+ *   again after a few seconds.
+ * - `'failed'` — the cancel request itself failed: it rejected, or the host
+ *   answered with its failure placeholder (`workflowId: 'failed'`) rather than
+ *   this workflow's snapshot. The workflow's state is unknown and it may still be
+ *   running. Calling `cancelAll()` again retries it.
+ */
+export type WorkflowBatchCancelState = 'idle' | 'pending' | 'done' | 'refused' | 'failed';
+/** One watched workflow. */
+export interface WorkflowBatchCell {
+    workflowId: string;
+    /**
+     * The latest snapshot the host returned FOR THIS WORKFLOW, or `null` before the
+     * first one. A host failure placeholder (whose `workflowId` is `'failed'`) is
+     * never stored here, because it is not this workflow's status.
+     */
+    snapshot: BlockWorkflowSnapshot | null;
+    phase: WorkflowBatchCellPhase;
+    /** Why the watch stopped, when it stopped on an error. `null` otherwise. */
+    error: Error | null;
+    cancel: WorkflowBatchCancelState;
+}
+/**
+ * Counts over every cell, from each cell's latest snapshot.
+ *
+ * `succeeded + failed + canceled + expired + running === total`.
+ */
+export interface WorkflowBatchSummary {
+    total: number;
+    /** Cells whose latest snapshot is not terminal, including cells with no snapshot yet. */
+    running: number;
+    succeeded: number;
+    failed: number;
+    canceled: number;
+    expired: number;
+    /**
+     * The part of `running` that nothing is polling (phase `'stopped'`). A batch
+     * with `stopped > 0` will not settle on its own: call `rewatch()`.
+     */
+    stopped: number;
+    /**
+     * The sum of `cost.total` on the terminal snapshots that carry one: the
+     * generation cost the host reported for each finished workflow (a cancelled
+     * workflow reports its cost after the cancel). It is what the snapshots say,
+     * not a read of the viewer's Buzz ledger. The app author's fee is charged
+     * separately and is not included.
+     */
+    realisedCost: number;
+    /** How many terminal cells contributed to `realisedCost`. */
+    costedCells: number;
+    /** `true` when every cell is terminal (`running === 0`). `true` for an empty list. */
+    settled: boolean;
+}
+/**
+ * What one {@link UseWorkflowBatch.cancelAll} call did. Each array holds workflow
+ * ids, in list order.
+ */
+export interface WorkflowBatchCancelResult {
+    /** The host answered `canceled`. */
+    canceled: string[];
+    /**
+     * The workflow had already finished: either its latest snapshot was already
+     * terminal (no request was sent), or the host answered the cancel with the
+     * workflow's real terminal status because it finished first.
+     */
+    alreadySettled: string[];
+    /** The host answered with a non-terminal snapshot: the cancel was not sent. */
+    refused: string[];
+    /**
+     * Not attempted, because an earlier cancel in this call was refused. The
+     * allowance is used up, so sending more would only be refused too.
+     */
+    notAttempted: string[];
+    /** The cancel request failed. The workflow's state is unknown. */
+    failed: string[];
+    /** `true` when `refused`, `notAttempted` and `failed` are all empty. */
+    complete: boolean;
+}
+/** Options for {@link useWorkflowBatch}. Passed to every cell's `watch()`. */
+export type WorkflowBatchOptions = Pick<WatchWorkflowOptions, 'intervalMs' | 'waitSeconds' | 'timeoutMs' | 'maxRetries'>;
+/** What {@link useWorkflowBatch} returns. */
+export interface UseWorkflowBatch {
+    /** One cell per id passed in, in the same order. */
+    cells: readonly WorkflowBatchCell[];
+    summary: WorkflowBatchSummary;
+    /**
+     * Cancel every cell that is not known to be finished. Resolves (never rejects)
+     * with what happened to each one; see {@link WorkflowBatchCancelResult}.
+     *
+     * Calling it while a previous call is still running returns that call's
+     * promise. Calling it again after a call that was not `complete` retries the
+     * cells that are still not finished.
+     */
+    cancelAll: () => Promise<WorkflowBatchCancelResult>;
+    /** Start watching every `'stopped'` cell again. */
+    rewatch: () => void;
+}
+/**
+ * Watch a set of already-submitted workflows as one batch, with per-cell status,
+ * a summary, and cancel-all. For grid apps that submit N workflows one by one
+ * with `useBuzzWorkflow().submit()` (each with its own confirmation) and then
+ * have to follow all N.
+ *
+ * 🔴 THE APP OWNS THE LIST, AND THE LIST IS THE BATCH. Pass the workflow ids as
+ * an array: append each id as its `submit()` resolves, and persist the same
+ * array (it is plain strings) to re-attach after a reload by passing it back.
+ * There is no server-side batch id. The host knows nothing about the grouping,
+ * so nothing here changes what the host allows: every cell is one ordinary
+ * `watch()` and every cancel is one ordinary `cancel()`.
+ *
+ * What it guarantees, and the host limits behind each:
+ *
+ * - **One poll in flight per workflow.** Each cell is one `watch()` loop. When a
+ *   loop is restarted (the list changes, `rewatch()`, a React StrictMode
+ *   remount), the new loop waits for the old loop's in-flight poll to return
+ *   first, so two polls for one workflow never overlap.
+ * - **At most {@link WORKFLOW_BATCH_MAX_CELLS} workflows.** That is the poll
+ *   allowance (1,200 per 60 s, per block instance and viewer) divided by one
+ *   watch's 40 polls a minute. A longer list throws.
+ * - **Cancel-all is paced and stops on refusal.** Cancels charge the estimate
+ *   allowance (150 per 10 s per block instance, shared by every viewer of a page
+ *   app). At most four are in flight. When the host answers one with a
+ *   non-terminal snapshot (its answer when that allowance is used up), the rest
+ *   of the call is not sent and comes back as `notAttempted`. Nothing is retried
+ *   automatically. Call `cancelAll()` again after a few seconds.
+ * - **A host failure placeholder is not a workflow outcome.** When the host
+ *   fails a poll or a cancel it answers with `{ workflowId: 'failed', status:
+ *   'failed' }`. `watch()` and `cancel()` resolve with that, but it says nothing
+ *   about the workflow, which may still be running. This hook never counts it as
+ *   a failed cell: a poll placeholder stops the cell (phase `'stopped'`, with
+ *   `error` set), and a cancel placeholder is a `'failed'` cancel.
+ * - **Unmounting stops every poll.** No state updates happen after unmount. A
+ *   `cancelAll()` already running keeps sending, because the viewer asked for it.
+ *
+ * Throws (at render) when the list is longer than
+ * {@link WORKFLOW_BATCH_MAX_CELLS}, has a duplicate, has an empty id, or has the
+ * `'failed'` / `'whatif'` placeholder a refused `submit()` resolves with.
+ *
+ * Needs the same `ai:write:budgeted` scope as `submit()`. A viewer who submitted
+ * already has it.
+ *
+ * @example
+ * const { submit } = useBuzzWorkflow();
+ * const [ids, setIds] = useState<string[]>(() => loadSavedIds());
+ * const batch = useWorkflowBatch(ids);
+ *
+ * async function runCell(body: WorkflowBody, key: string) {
+ *   const snap = await submit(body, { idempotencyKey: key });
+ *   if (snap.workflowId !== 'failed') setIds((prev) => [...prev, snap.workflowId]);
+ * }
+ *
+ * useEffect(() => saveIds(ids), [ids]);
+ *
+ * // batch.summary.running, batch.summary.realisedCost, batch.cells[i].snapshot …
+ * const result = await batch.cancelAll();
+ * if (!result.complete) showRetryCancel(result);
+ */
+export declare function useWorkflowBatch(workflowIds: readonly string[], options?: WorkflowBatchOptions): UseWorkflowBatch;
+//# sourceMappingURL=useWorkflowBatch.d.ts.map

package/dist/hooks/useWorkflowBatch.js

@@ -0,0 +1,352 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useBuzzWorkflow } from './useBuzzWorkflow.js';
+/**
+ * The most workflows one {@link useWorkflowBatch} may watch.
+ *
+ * Derived from the host's poll allowance, not picked: one watched workflow makes
+ * at most 60 / 1.5 = 40 polls a minute (one poll in flight, `intervalMs` 1,500
+ * between polls), and the viewer's poll allowance is 1,200 per 60 s per block
+ * instance, so 1,200 / 40 = 30 workflows is the most one viewer can watch before
+ * polls start coming back as placeholders. The developer docs' limits table
+ * gives the same figure. A list longer than this throws, because an app that
+ * needs more cells needs a different plan than "watch them all at once".
+ */
+export const WORKFLOW_BATCH_MAX_CELLS = 30;
+/**
+ * How many `cancel()` requests {@link UseWorkflowBatch.cancelAll} keeps in flight.
+ *
+ * Cancels charge the ESTIMATE allowance (150 per 10 s per block instance). On a
+ * page app every viewer of the app shares that allowance, along with the host's
+ * other reads for the app (viewer, balance, image and model lookups). Four at a
+ * time keeps a 16-cell cancel-all from landing as one burst on an allowance other
+ * people are using. Not exported: it is a pacing detail, not a contract.
+ */
+const CANCEL_CONCURRENCY = 4;
+/** Statuses after which a workflow will not change again. */
+const TERMINAL = new Set([
+    'succeeded',
+    'failed',
+    'canceled',
+    'expired',
+]);
+/**
+ * Placeholder ids a resolved `submit()` can carry when no workflow was created
+ * (see `useBuzzWorkflow().submit`). There is nothing behind them to watch.
+ */
+const NON_WORKFLOW_IDS = new Set(['failed', 'whatif']);
+const FRESH = { snapshot: null, phase: 'watching', error: null, cancel: 'idle' };
+function validateIds(ids) {
+    if (ids.length > WORKFLOW_BATCH_MAX_CELLS) {
+        throw new RangeError(`useWorkflowBatch: ${ids.length} workflow ids, but at most ${WORKFLOW_BATCH_MAX_CELLS} can be watched at once`);
+    }
+    const seen = new Set();
+    for (const id of ids) {
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new TypeError('useWorkflowBatch: every workflow id must be a non-empty string');
+        }
+        if (NON_WORKFLOW_IDS.has(id)) {
+            throw new TypeError(`useWorkflowBatch: '${id}' is not a workflow id. A submit that resolved with it created nothing to watch`);
+        }
+        if (seen.has(id)) {
+            throw new TypeError(`useWorkflowBatch: workflow id '${id}' appears more than once`);
+        }
+        seen.add(id);
+    }
+}
+function summarise(cells) {
+    const summary = {
+        total: cells.length,
+        running: 0,
+        succeeded: 0,
+        failed: 0,
+        canceled: 0,
+        expired: 0,
+        stopped: 0,
+        realisedCost: 0,
+        costedCells: 0,
+        settled: true,
+    };
+    for (const cell of cells) {
+        const status = cell.snapshot?.status;
+        if (status === undefined || !TERMINAL.has(status)) {
+            summary.running += 1;
+            if (cell.phase === 'stopped')
+                summary.stopped += 1;
+            continue;
+        }
+        summary[status] += 1;
+        const total = cell.snapshot?.cost?.total;
+        if (typeof total === 'number' && Number.isFinite(total)) {
+            summary.realisedCost += total;
+            summary.costedCells += 1;
+        }
+    }
+    summary.settled = summary.running === 0;
+    return summary;
+}
+/**
+ * Watch a set of already-submitted workflows as one batch, with per-cell status,
+ * a summary, and cancel-all. For grid apps that submit N workflows one by one
+ * with `useBuzzWorkflow().submit()` (each with its own confirmation) and then
+ * have to follow all N.
+ *
+ * 🔴 THE APP OWNS THE LIST, AND THE LIST IS THE BATCH. Pass the workflow ids as
+ * an array: append each id as its `submit()` resolves, and persist the same
+ * array (it is plain strings) to re-attach after a reload by passing it back.
+ * There is no server-side batch id. The host knows nothing about the grouping,
+ * so nothing here changes what the host allows: every cell is one ordinary
+ * `watch()` and every cancel is one ordinary `cancel()`.
+ *
+ * What it guarantees, and the host limits behind each:
+ *
+ * - **One poll in flight per workflow.** Each cell is one `watch()` loop. When a
+ *   loop is restarted (the list changes, `rewatch()`, a React StrictMode
+ *   remount), the new loop waits for the old loop's in-flight poll to return
+ *   first, so two polls for one workflow never overlap.
+ * - **At most {@link WORKFLOW_BATCH_MAX_CELLS} workflows.** That is the poll
+ *   allowance (1,200 per 60 s, per block instance and viewer) divided by one
+ *   watch's 40 polls a minute. A longer list throws.
+ * - **Cancel-all is paced and stops on refusal.** Cancels charge the estimate
+ *   allowance (150 per 10 s per block instance, shared by every viewer of a page
+ *   app). At most four are in flight. When the host answers one with a
+ *   non-terminal snapshot (its answer when that allowance is used up), the rest
+ *   of the call is not sent and comes back as `notAttempted`. Nothing is retried
+ *   automatically. Call `cancelAll()` again after a few seconds.
+ * - **A host failure placeholder is not a workflow outcome.** When the host
+ *   fails a poll or a cancel it answers with `{ workflowId: 'failed', status:
+ *   'failed' }`. `watch()` and `cancel()` resolve with that, but it says nothing
+ *   about the workflow, which may still be running. This hook never counts it as
+ *   a failed cell: a poll placeholder stops the cell (phase `'stopped'`, with
+ *   `error` set), and a cancel placeholder is a `'failed'` cancel.
+ * - **Unmounting stops every poll.** No state updates happen after unmount. A
+ *   `cancelAll()` already running keeps sending, because the viewer asked for it.
+ *
+ * Throws (at render) when the list is longer than
+ * {@link WORKFLOW_BATCH_MAX_CELLS}, has a duplicate, has an empty id, or has the
+ * `'failed'` / `'whatif'` placeholder a refused `submit()` resolves with.
+ *
+ * Needs the same `ai:write:budgeted` scope as `submit()`. A viewer who submitted
+ * already has it.
+ *
+ * @example
+ * const { submit } = useBuzzWorkflow();
+ * const [ids, setIds] = useState<string[]>(() => loadSavedIds());
+ * const batch = useWorkflowBatch(ids);
+ *
+ * async function runCell(body: WorkflowBody, key: string) {
+ *   const snap = await submit(body, { idempotencyKey: key });
+ *   if (snap.workflowId !== 'failed') setIds((prev) => [...prev, snap.workflowId]);
+ * }
+ *
+ * useEffect(() => saveIds(ids), [ids]);
+ *
+ * // batch.summary.running, batch.summary.realisedCost, batch.cells[i].snapshot …
+ * const result = await batch.cancelAll();
+ * if (!result.complete) showRetryCancel(result);
+ */
+export function useWorkflowBatch(workflowIds, options) {
+    validateIds(workflowIds);
+    // A private `useBuzzWorkflow()` instance, so the app's own instance's
+    // `result`/`status` are not overwritten by 16 cells' updates.
+    const { watch, cancel } = useBuzzWorkflow();
+    const [states, setStates] = useState(() => new Map());
+    // Mirror of `states` for async code, which must not read a stale closure.
+    const statesRef = useRef(states);
+    statesRef.current = states;
+    const idsKey = workflowIds.join('\u0000');
+    const idsRef = useRef(workflowIds);
+    idsRef.current = workflowIds;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const mountedRef = useRef(false);
+    /** Per workflow: the running loop's controller and a promise that settles when it ends. */
+    const loopsRef = useRef(new Map());
+    const cancelAllRef = useRef(null);
+    const patch = useCallback((workflowId, change) => {
+        if (!mountedRef.current)
+            return;
+        setStates((prev) => {
+            const next = new Map(prev);
+            next.set(workflowId, { ...(prev.get(workflowId) ?? FRESH), ...change });
+            return next;
+        });
+    }, []);
+    const startLoop = useCallback((workflowId) => {
+        const loops = loopsRef.current;
+        const previous = loops.get(workflowId);
+        previous?.controller.abort();
+        const controller = new AbortController();
+        // 🔴 CHAIN ON THE PREVIOUS LOOP. Aborting a `watch()` does not withdraw a
+        // poll already in flight (the host can hold it up to 15 s); the loop only
+        // sees the abort when that poll returns. Starting the new loop at once would
+        // put two polls for one workflow in flight.
+        const done = (previous?.done ?? Promise.resolve()).then(async () => {
+            if (controller.signal.aborted)
+                return;
+            try {
+                const final = await watch(workflowId, {
+                    ...optionsRef.current,
+                    signal: controller.signal,
+                    onUpdate: (snapshot) => {
+                        if (controller.signal.aborted || snapshot.workflowId !== workflowId)
+                            return;
+                        patch(workflowId, { snapshot });
+                    },
+                });
+                if (controller.signal.aborted)
+                    return;
+                if (final.workflowId !== workflowId) {
+                    patch(workflowId, {
+                        phase: 'stopped',
+                        error: new Error(`useWorkflowBatch: the host answered a poll for ${workflowId} with a failure placeholder, not the workflow's status`),
+                    });
+                    return;
+                }
+                patch(workflowId, {
+                    snapshot: final,
+                    phase: TERMINAL.has(final.status) ? 'settled' : 'stopped',
+                    error: null,
+                });
+            }
+            catch (err) {
+                if (controller.signal.aborted)
+                    return;
+                patch(workflowId, { phase: 'stopped', error: err instanceof Error ? err : new Error(String(err)) });
+            }
+        });
+        loops.set(workflowId, { controller, done });
+    }, [watch, patch]);
+    useEffect(() => {
+        mountedRef.current = true;
+        const loops = loopsRef.current;
+        return () => {
+            mountedRef.current = false;
+            for (const loop of loops.values())
+                loop.controller.abort();
+        };
+    }, []);
+    // Diff the list against the running loops: start new ids, stop removed ones.
+    useEffect(() => {
+        const loops = loopsRef.current;
+        const wanted = new Set(idsRef.current);
+        for (const [id, loop] of loops) {
+            // Abort, but KEEP the entry: its `done` is what a re-added id's new loop
+            // must wait on, because the aborted loop's poll may still be in flight.
+            if (!wanted.has(id))
+                loop.controller.abort();
+        }
+        for (const id of idsRef.current) {
+            const loop = loops.get(id);
+            if (loop && !loop.controller.signal.aborted)
+                continue;
+            const state = statesRef.current.get(id);
+            // A settled or stopped cell stays as it is until `rewatch()`.
+            if (state && state.phase !== 'watching')
+                continue;
+            startLoop(id);
+        }
+        setStates((prev) => {
+            let changed = false;
+            const next = new Map(prev);
+            for (const id of prev.keys()) {
+                if (!wanted.has(id)) {
+                    next.delete(id);
+                    changed = true;
+                }
+            }
+            return changed ? next : prev;
+        });
+        // `idsKey` stands for the list's contents; the list itself is read from the ref.
+    }, [idsKey, startLoop]);
+    const rewatch = useCallback(() => {
+        for (const id of idsRef.current) {
+            if (statesRef.current.get(id)?.phase !== 'stopped')
+                continue;
+            patch(id, { phase: 'watching', error: null });
+            startLoop(id);
+        }
+    }, [patch, startLoop]);
+    const cancelAll = useCallback(() => {
+        if (cancelAllRef.current)
+            return cancelAllRef.current;
+        const run = async () => {
+            const ids = [...idsRef.current];
+            const outcome = new Map();
+            const targets = [];
+            for (const id of ids) {
+                const status = statesRef.current.get(id)?.snapshot?.status;
+                if (status !== undefined && TERMINAL.has(status))
+                    outcome.set(id, 'alreadySettled');
+                else
+                    targets.push(id);
+            }
+            let refusedSeen = false;
+            let next = 0;
+            const worker = async () => {
+                for (let id = targets[next]; id !== undefined; id = targets[next]) {
+                    next += 1;
+                    if (refusedSeen) {
+                        outcome.set(id, 'notAttempted');
+                        patch(id, { cancel: 'refused' });
+                        continue;
+                    }
+                    patch(id, { cancel: 'pending' });
+                    let snapshot;
+                    try {
+                        snapshot = await cancel(id);
+                    }
+                    catch {
+                        outcome.set(id, 'failed');
+                        patch(id, { cancel: 'failed' });
+                        continue;
+                    }
+                    if (snapshot.workflowId !== id) {
+                        // The host's failure placeholder: the request failed, the workflow's
+                        // state is unknown.
+                        outcome.set(id, 'failed');
+                        patch(id, { cancel: 'failed' });
+                    }
+                    else if (TERMINAL.has(snapshot.status)) {
+                        outcome.set(id, snapshot.status === 'canceled' ? 'canceled' : 'alreadySettled');
+                        loopsRef.current.get(id)?.controller.abort();
+                        patch(id, { cancel: 'done', snapshot, phase: 'settled', error: null });
+                    }
+                    else {
+                        refusedSeen = true;
+                        outcome.set(id, 'refused');
+                        patch(id, { cancel: 'refused' });
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(CANCEL_CONCURRENCY, targets.length) }, () => worker()));
+            const result = {
+                canceled: [],
+                alreadySettled: [],
+                refused: [],
+                notAttempted: [],
+                failed: [],
+                complete: true,
+            };
+            for (const id of ids) {
+                const bucket = outcome.get(id);
+                if (bucket)
+                    result[bucket].push(id);
+            }
+            result.complete =
+                result.refused.length === 0 && result.notAttempted.length === 0 && result.failed.length === 0;
+            return result;
+        };
+        const promise = run().finally(() => {
+            cancelAllRef.current = null;
+        });
+        cancelAllRef.current = promise;
+        return promise;
+    }, [cancel, patch]);
+    const cells = useMemo(() => workflowIds.map((workflowId) => ({ workflowId, ...(states.get(workflowId) ?? FRESH) })), 
+    // `idsKey` stands for the list's contents, so a new array with the same ids
+    // does not rebuild the cells.
+    [idsKey, states]);
+    const summary = useMemo(() => summarise(cells), [cells]);
+    return { cells, summary, cancelAll, rewatch };
+}
+//# sourceMappingURL=useWorkflowBatch.js.map

package/dist/index.d.ts

@@ -29,6 +29,8 @@ export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, Wor
 export type { SubmitWorkflowOptions, UseBuzzWorkflow, WatchWorkflowOptions, WorkflowSubmitErrorCode, } from './hooks/useBuzzWorkflow.js';
 export { BATCH_ESTIMATE_MAX_CELLS, BatchEstimateError, useBatchEstimate, } from './hooks/useBatchEstimate.js';
 export type { BatchEstimateCell, BatchEstimateErrorCode, BatchEstimateResult, BlockEstimateBatchAggregate, EstimateBatchOptions, UseBatchEstimate, } from './hooks/useBatchEstimate.js';
+export { WORKFLOW_BATCH_MAX_CELLS, useWorkflowBatch } from './hooks/useWorkflowBatch.js';
+export type { UseWorkflowBatch, WorkflowBatchCancelResult, WorkflowBatchCancelState, WorkflowBatchCell, WorkflowBatchCellPhase, WorkflowBatchOptions, WorkflowBatchSummary, } from './hooks/useWorkflowBatch.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export type { UseEntitlements, Entitlement } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';

package/dist/index.js

@@ -32,6 +32,7 @@ export { useBlockToken } from './hooks/useBlockToken.js';
 export { useHostOrigin } from './hooks/useHostOrigin.js';
 export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, WorkflowSubmitError, } from './hooks/useBuzzWorkflow.js';
 export { BATCH_ESTIMATE_MAX_CELLS, BatchEstimateError, useBatchEstimate, } from './hooks/useBatchEstimate.js';
+export { WORKFLOW_BATCH_MAX_CELLS, useWorkflowBatch } from './hooks/useWorkflowBatch.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
 export { useTip } from './hooks/useTip.js';

package/dist/internal/mockHost.d.ts

@@ -195,6 +195,29 @@ export interface MockGenerationScenario {
      * `batchEstimate: 'supported'`. Default: unset (no cell times out).
      */
     batchEstimateTimedOutCells?: number[];
+    /**
+     * Make `CANCEL_WORKFLOW` answer the way the real host answers a cancel it
+     * REFUSED because the estimate allowance is used up: `{ workflowId, status:
+     * 'processing' }`. The cancel is not applied, so later polls keep reporting
+     * the workflow as running. `true` refuses every cancel; an array refuses only
+     * those workflow ids. Use it to test a cancel button's "not cancelled, try
+     * again" path, including `useWorkflowBatch().cancelAll()`'s `refused` and
+     * `notAttempted` lists.
+     *
+     * Live-tunable via `setScenario({ generation: { cancelRefused } })`. Default:
+     * unset (every cancel applies).
+     */
+    cancelRefused?: boolean | readonly string[];
+    /**
+     * The terminal status each polled workflow ends with, so a grid can be tested
+     * with a mix of outcomes. Called once per workflow, on the poll that finishes
+     * it, with the workflow id and the body it was submitted with (`undefined`
+     * for an id this mock did not submit, such as one restored after a reload).
+     *
+     * `'failed'` and `'expired'` reply `{ workflowId, status, error }` with no
+     * `cost` and no images. Default: every workflow `'succeeded'`.
+     */
+    workflowOutcome?: (workflowId: string, body: WorkflowBody | undefined) => 'succeeded' | 'failed' | 'expired';
     /**
      * Force every SUBMIT to come back as a caught server EXCEPTION — the host's
      * real `failureSnapshot(err)` shape: `{ workflowId:'failed', status:'failed',

package/dist/internal/mockHost.js

@@ -1084,6 +1084,9 @@ export function createMockHost(options = {}) {
         let tokenSerial = 0;
         let submitCount = 0;
         // body + cost remembered per workflow so the succeeded snapshot can echo them.
+        // `body` is absent for an id this mock never submitted (a workflow id an app
+        // restored after a reload). `canceled` is set by `CANCEL_WORKFLOW`, so later
+        // polls keep answering `canceled` instead of resuming the countdown.
         const workflows = new Map();
         // Training: datasets this install prepared (id → admitted count) and the
         // quotes its estimates stored (id → what a run is checked against).
@@ -1703,11 +1706,35 @@ export function createMockHost(options = {}) {
                     }
                     case 'POLL_WORKFLOW': {
                         const workflowId = typed.payload?.workflowId ?? '';
-                        const wf = workflows.get(workflowId);
-                        const polls = (wf?.polls ?? 0) + 1;
-                        if (wf)
-                            wf.polls = polls;
-                        if (polls >= pollsUntilDone) {
+                        // An id this mock did not submit (e.g. restored from storage after a
+                        // reload) gets a record on its first poll, so it counts down to done
+                        // like any other instead of answering `processing` forever.
+                        let wf = workflows.get(workflowId);
+                        if (!wf) {
+                            wf = { polls: 0, cost: legacyCost };
+                            workflows.set(workflowId, wf);
+                        }
+                        if (wf.canceled) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_STATUS',
+                                payload: { requestId, snapshot: { workflowId, status: 'canceled' } },
+                            });
+                            return;
+                        }
+                        const polls = wf.polls + 1;
+                        wf.polls = polls;
+                        const outcome = polls >= pollsUntilDone ? (gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded') : null;
+                        if (outcome === 'failed' || outcome === 'expired') {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_STATUS',
+                                payload: {
+                                    requestId,
+                                    snapshot: { workflowId, status: outcome, error: `mock: workflow ${outcome}` },
+                                },
+                            });
+                            return;
+                        }
+                        if (outcome === 'succeeded') {
                             // Apply synthetic latency on the terminal (succeeded) poll only.
                             const delay = latencyFor();
                             if (delay > 0) {
@@ -1733,7 +1760,35 @@ export function createMockHost(options = {}) {
                     }
                     case 'CANCEL_WORKFLOW': {
                         const workflowId = typed.payload?.workflowId ?? '';
-                        workflows.delete(workflowId);
+                        const refused = gen.cancelRefused;
+                        if (refused === true || (Array.isArray(refused) && refused.includes(workflowId))) {
+                            // The real host's answer when the estimate allowance is used up: a
+                            // NON-terminal snapshot, and the cancel is not sent.
+                            dispatchToBlock({
+                                type: 'WORKFLOW_CANCELED',
+                                payload: { requestId, snapshot: { workflowId, status: 'processing' } },
+                            });
+                            return;
+                        }
+                        const wf = workflows.get(workflowId);
+                        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 outcome = gen.workflowOutcome?.(workflowId, wf.body) ?? 'succeeded';
+                            dispatchToBlock({
+                                type: 'WORKFLOW_CANCELED',
+                                payload: {
+                                    requestId,
+                                    snapshot: outcome === 'succeeded'
+                                        ? succeededSnapshot(workflowId)
+                                        : { workflowId, status: outcome, error: `mock: workflow ${outcome}` },
+                                },
+                            });
+                            return;
+                        }
+                        // Keep the record, marked canceled, so later polls answer `canceled`
+                        // rather than counting down to `succeeded`.
+                        workflows.set(workflowId, { ...(wf ?? { polls: 0, cost: legacyCost }), canceled: true });
                         dispatchToBlock({
                             type: 'WORKFLOW_CANCELED',
                             payload: { requestId, snapshot: { workflowId, status: 'canceled' } },

package/dist/transport/validate.js

@@ -248,6 +248,12 @@ export function isValidWorkflowSnapshot(s) {
     }
     if (s.error !== undefined && typeof s.error !== 'string')
         return false;
+    // OPTIONAL: set only on the refusals that define a code (today the training
+    // price-quote refusal), absent everywhere else. Checked as a STRING, not
+    // against today's codes — the open-ended-union rule below: a host adding a
+    // code must not turn into a dropped reply in every shipped bundle.
+    if (s.errorCode !== undefined && typeof s.errorCode !== 'string')
+        return false;
     if (s.autoClaim !== undefined) {
         if (!isObject(s.autoClaim))
             return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.68.0",
+  "version": "0.69.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.64.0"
+    "@civitai/app-sdk": "^0.65.0"
   },
   "publishConfig": {
     "access": "public"