@civitai/blocks-react 0.67.1 → 0.69.0

package/dist/hooks/useResourcePicker.d.ts

@@ -1,43 +1,87 @@
 import type { BlockResourceInfo, BlockResourcePickerType } from '@civitai/app-sdk/blocks';
+/**
+ * The most resources ONE multi-select `open({ multiple })` can return — the
+ * same cap the generation body puts on `additionalResources`, so a full batch
+ * is always one a submit accepts. A larger `multiple.max` is CLAMPED to this.
+ */
+export declare const RESOURCE_PICKER_MULTIPLE_MAX = 5;
+/** The options every {@link UseResourcePicker} `open` call takes. */
+export interface ResourcePickerOpenOptions {
+    /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
+     * host rejects any other type (the modal never opens). */
+    resourceType: BlockResourcePickerType;
+    /**
+     * 🔴 OMIT THIS BY DEFAULT. It is an optional base-model family FILTER, not a
+     * label: whatever you pass, the host HIDES every resource outside that
+     * ecosystem, so the viewer's own perfectly valid LoRAs simply do not appear
+     * and the picker looks empty or broken. Omitting it is an unconstrained pick
+     * of the type — every resource the viewer can reach.
+     *
+     * Pass it ONLY when the block already holds a chosen checkpoint the pick has
+     * to match, and then DERIVE it from that checkpoint. Never a hardcoded
+     * ecosystem string: a literal pins every viewer of the app to whichever
+     * family the author happened to be testing with. Nor a literal reached
+     * through a fallback — `checkpoint?.baseModel ?? 'SDXL'` re-pins every viewer
+     * who has not picked yet, which is the same defect wearing a default.
+     *
+     * 🔴 WHERE THE FAMILY COMES FROM ON THIS HOOK'S ONLY SURFACE. This hook is
+     * PAGE-ONLY (`OPEN_RESOURCE_PICKER` is a page affordance; the model slot has
+     * the narrower `useCheckpointPicker` instead), and a page slot carries no
+     * checkpoint: `checkpoint` exists on `ModelSlotContext` alone, and
+     * `BlockContext` is a union with no index signature, so
+     * `useBlockContext().context.checkpoint` does not even typecheck. The source
+     * is {@link BlockResourceInfo}`.baseModel` — the `baseModel` of a Checkpoint
+     * THIS picker returned earlier:
+     *
+     *     const checkpoint = await open({ resourceType: 'Checkpoint' });
+     *     if (checkpoint) await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+     *
+     * Accepts an ecosystem key (e.g. 'Flux1', 'SDXL') OR a baseModel name (e.g.
+     * 'Flux.1 D'); the host collapses either to the ecosystem family. `''` is not
+     * a way to widen: the page host drops a zero-length value, so it is only ever
+     * a confusing spelling of omitting the key.
+     */
+    baseModelGroup?: string;
+}
+/**
+ * Multi-select: let the viewer pick up to `max` resources in ONE picker session.
+ *
+ * - **LoRA only.** `open({ resourceType: 'Checkpoint', multiple })` is a type
+ *   error, and at runtime it REJECTS — it is never quietly treated as a single
+ *   pick. A generation takes one checkpoint and a list of LoRAs.
+ * - **`max` is a whole number ≥ 1.** Anything above
+ *   {@link RESOURCE_PICKER_MULTIPLE_MAX} (5) is CLAMPED to it; anything that is
+ *   not a whole number ≥ 1 rejects.
+ * - `baseModelGroup` works exactly as it does for a single pick.
+ */
+export interface ResourcePickerMultiple {
+    max: number;
+}
 /** What {@link useResourcePicker} returns. */
 export interface UseResourcePicker {
-    open: (opts: {
-        /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
-         * host rejects any other type (the modal never opens). */
-        resourceType: BlockResourcePickerType;
+    open: {
         /**
-         * 🔴 OMIT THIS BY DEFAULT. It is an optional base-model family FILTER, not a
-         * label: whatever you pass, the host HIDES every resource outside that
-         * ecosystem, so the viewer's own perfectly valid LoRAs simply do not appear
-         * and the picker looks empty or broken. Omitting it is an unconstrained pick
-         * of the type — every resource the viewer can reach.
-         *
-         * Pass it ONLY when the block already holds a chosen checkpoint the pick has
-         * to match, and then DERIVE it from that checkpoint. Never a hardcoded
-         * ecosystem string: a literal pins every viewer of the app to whichever
-         * family the author happened to be testing with. Nor a literal reached
-         * through a fallback — `checkpoint?.baseModel ?? 'SDXL'` re-pins every viewer
-         * who has not picked yet, which is the same defect wearing a default.
-         *
-         * 🔴 WHERE THE FAMILY COMES FROM ON THIS HOOK'S ONLY SURFACE. This hook is
-         * PAGE-ONLY (`OPEN_RESOURCE_PICKER` is a page affordance; the model slot has
-         * the narrower `useCheckpointPicker` instead), and a page slot carries no
-         * checkpoint: `checkpoint` exists on `ModelSlotContext` alone, and
-         * `BlockContext` is a union with no index signature, so
-         * `useBlockContext().context.checkpoint` does not even typecheck. The source
-         * is {@link BlockResourceInfo}`.baseModel` — the `baseModel` of a Checkpoint
-         * THIS picker returned earlier:
-         *
-         *     const checkpoint = await open({ resourceType: 'Checkpoint' });
-         *     if (checkpoint) await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+         * Single pick. Resolves with the chosen resource, or `null` when the viewer
+         * dismissed the picker.
+         */
+        (opts: ResourcePickerOpenOptions & {
+            multiple?: undefined;
+        }): Promise<BlockResourceInfo | null>;
+        /**
+         * Multi-select (see {@link ResourcePickerMultiple}). Resolves with the
+         * picked resources IN THE ORDER THE VIEWER PICKED THEM — never more than
+         * `max` — or `[]` when the viewer dismissed. Each entry is the same
+         * {@link BlockResourceInfo} a single pick returns.
          *
-         * Accepts an ecosystem key (e.g. 'Flux1', 'SDXL') OR a baseModel name (e.g.
-         * 'Flux.1 D'); the host collapses either to the ecosystem family. `''` is not
-         * a way to widen: the page host drops a zero-length value, so it is only ever
-         * a confusing spelling of omitting the key.
+         * Against a host that predates multi-select the viewer gets the single-pick
+         * picker, and this still resolves with a list: of the one resource they
+         * picked, or `[]`.
          */
-        baseModelGroup?: string;
-    }) => Promise<BlockResourceInfo | null>;
+        (opts: ResourcePickerOpenOptions & {
+            resourceType: 'LORA';
+            multiple: ResourcePickerMultiple;
+        }): Promise<BlockResourceInfo[]>;
+    };
 }
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
@@ -51,6 +95,13 @@ export interface UseResourcePicker {
  * pick. Resolves with the chosen {@link BlockResourceInfo}, or `null` when the
  * user dismissed without picking.
  *
+ * MULTI-SELECT: pass `multiple: { max }` with `resourceType: 'LORA'` and the
+ * viewer picks up to `max` LoRAs (at most {@link RESOURCE_PICKER_MULTIPLE_MAX})
+ * in ONE picker session. `open` then resolves with a LIST — the picks in the
+ * order the viewer made them, `[]` on dismiss — instead of a single resource.
+ * See {@link ResourcePickerMultiple}. Without `multiple`, nothing about a
+ * single pick changes.
+ *
  * DISCOVERY ONLY: the returned `versionId` is a hint, never an entitlement.
  * Feed it into `body.modelVersionId` (Checkpoint) or
  * `body.additionalResources` (LoRA) and submit — the host re-validates every id
@@ -61,14 +112,14 @@ export interface UseResourcePicker {
  * Host-mediated, same trust model as `useCheckpointPicker` / `useBuzzWorkflow`:
  * the block never touches the picker UI directly.
  *
- * 🔴 THE ORDER OF THE TWO `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT SWAP
- * THEM. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
+ * 🔴 THE ORDER OF THE `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT MOVE
+ * THE LAST ONE. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
  * `jsdocExample` inside its tag loop, so on a hook with several `@example` tags
  * the LAST one wins and becomes the single published example whenever the README
  * fence is unavailable (renamed heading, dropped fence). The unconstrained call
  * is what every agent should copy, so it is last. The constrained variant is
  * first, where a human reading top-down still meets the exception before the
- * default it excepts.
+ * default it excepts; the multi-select variant sits between them.
  *
  * @example
  * // CONSTRAINED — only when the pick has to match a checkpoint the block
@@ -83,6 +134,16 @@ export interface UseResourcePicker {
  * }
  *
  * @example
+ * // MULTI-SELECT — several LoRAs in one picker session, in pick order.
+ * const { open } = useResourcePicker();
+ * const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
+ * // [] when dismissed; otherwise up to 3 picks, in the order the viewer chose
+ * const additionalResources = loras.map((lora) => ({
+ *   modelVersionId: lora.versionId,
+ *   strength: lora.strength ?? 1,
+ * }));
+ *
+ * @example
  * // THE DEFAULT — no ecosystem filter at all. The viewer sees every LoRA they
  * // can reach, which is almost always what you want.
  * const { open } = useResourcePicker();

package/dist/hooks/useResourcePicker.js

@@ -1,7 +1,21 @@
 import { useCallback } from 'react';
+import { throwOnReplyError } from '../internal/replyError.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+/**
+ * The most resources ONE multi-select `open({ multiple })` can return — the
+ * same cap the generation body puts on `additionalResources`, so a full batch
+ * is always one a submit accepts. A larger `multiple.max` is CLAMPED to this.
+ */
+export const RESOURCE_PICKER_MULTIPLE_MAX = 5;
+/**
+ * The LoRA family, lower-cased. The host's picker accepts `LoCon` and `DoRA`
+ * beside `LORA` and matches case-insensitively, so the runtime check here does
+ * too — a caller reaching those through a cast is not refused by the SDK for
+ * something the host allows.
+ */
+const MULTIPLE_RESOURCE_TYPES = new Set(['lora', 'locon', 'dora']);
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
  * host-chrome). Generalizes {@link useCheckpointPicker} from Checkpoint-only to
@@ -14,6 +28,13 @@ import { sendTypedRequest } from '../transport/transport.js';
  * pick. Resolves with the chosen {@link BlockResourceInfo}, or `null` when the
  * user dismissed without picking.
  *
+ * MULTI-SELECT: pass `multiple: { max }` with `resourceType: 'LORA'` and the
+ * viewer picks up to `max` LoRAs (at most {@link RESOURCE_PICKER_MULTIPLE_MAX})
+ * in ONE picker session. `open` then resolves with a LIST — the picks in the
+ * order the viewer made them, `[]` on dismiss — instead of a single resource.
+ * See {@link ResourcePickerMultiple}. Without `multiple`, nothing about a
+ * single pick changes.
+ *
  * DISCOVERY ONLY: the returned `versionId` is a hint, never an entitlement.
  * Feed it into `body.modelVersionId` (Checkpoint) or
  * `body.additionalResources` (LoRA) and submit — the host re-validates every id
@@ -24,14 +45,14 @@ import { sendTypedRequest } from '../transport/transport.js';
  * Host-mediated, same trust model as `useCheckpointPicker` / `useBuzzWorkflow`:
  * the block never touches the picker UI directly.
  *
- * 🔴 THE ORDER OF THE TWO `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT SWAP
- * THEM. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
+ * 🔴 THE ORDER OF THE `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT MOVE
+ * THE LAST ONE. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
  * `jsdocExample` inside its tag loop, so on a hook with several `@example` tags
  * the LAST one wins and becomes the single published example whenever the README
  * fence is unavailable (renamed heading, dropped fence). The unconstrained call
  * is what every agent should copy, so it is last. The constrained variant is
  * first, where a human reading top-down still meets the exception before the
- * default it excepts.
+ * default it excepts; the multi-select variant sits between them.
  *
  * @example
  * // CONSTRAINED — only when the pick has to match a checkpoint the block
@@ -46,6 +67,16 @@ import { sendTypedRequest } from '../transport/transport.js';
  * }
  *
  * @example
+ * // MULTI-SELECT — several LoRAs in one picker session, in pick order.
+ * const { open } = useResourcePicker();
+ * const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
+ * // [] when dismissed; otherwise up to 3 picks, in the order the viewer chose
+ * const additionalResources = loras.map((lora) => ({
+ *   modelVersionId: lora.versionId,
+ *   strength: lora.strength ?? 1,
+ * }));
+ *
+ * @example
  * // THE DEFAULT — no ecosystem filter at all. The viewer sees every LoRA they
  * // can reach, which is almost always what you want.
  * const { open } = useResourcePicker();
@@ -56,16 +87,55 @@ import { sendTypedRequest } from '../transport/transport.js';
  */
 export function useResourcePicker() {
     const open = useCallback(async (opts) => {
-        const { selected } = await sendTypedRequest(getTransport(), {
+        if (opts.multiple == null) {
+            const { selected } = await sendTypedRequest(getTransport(), {
+                type: 'OPEN_RESOURCE_PICKER',
+                payload: {
+                    resourceType: opts.resourceType,
+                    ...(opts.baseModelGroup != null ? { baseModelGroup: opts.baseModelGroup } : {}),
+                },
+            }, 'RESOURCE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+            // Normalize the "dismissed" case to an explicit null so callers can
+            // `if (!picked) return;` without an `undefined` ambiguity.
+            return selected ?? null;
+        }
+        // ── Multi-select ──────────────────────────────────────────────────────
+        // Refused HERE, before anything is sent, for two reasons: the caller gets
+        // an error naming the mistake instead of a picker that never opens, and a
+        // host that predates multi-select never sees a request it would answer
+        // with the wrong thing (it ignores `multiple` and would happily open a
+        // single CHECKPOINT pick).
+        if (!MULTIPLE_RESOURCE_TYPES.has(String(opts.resourceType).trim().toLowerCase())) {
+            throw new Error(`useResourcePicker: \`multiple\` is only supported for LoRA picks, not ` +
+                `resourceType "${String(opts.resourceType)}". Call open() without \`multiple\` for a single pick.`);
+        }
+        const requestedMax = opts.multiple.max;
+        if (typeof requestedMax !== 'number' || !Number.isInteger(requestedMax) || requestedMax < 1) {
+            throw new Error('useResourcePicker: `multiple.max` must be a whole number of at least 1 ' +
+                `(values above ${RESOURCE_PICKER_MULTIPLE_MAX} are clamped to ${RESOURCE_PICKER_MULTIPLE_MAX}).`);
+        }
+        const max = Math.min(requestedMax, RESOURCE_PICKER_MULTIPLE_MAX);
+        const result = await sendTypedRequest(getTransport(), {
             type: 'OPEN_RESOURCE_PICKER',
             payload: {
                 resourceType: opts.resourceType,
                 ...(opts.baseModelGroup != null ? { baseModelGroup: opts.baseModelGroup } : {}),
+                multiple: { max },
             },
         }, 'RESOURCE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
-        // Normalize the "dismissed" case to an explicit null so callers can
-        // `if (!picked) return;` without an `undefined` ambiguity.
-        return selected ?? null;
+        // The host answers a multi request it will not open with `{ error }`.
+        throwOnReplyError(result, 'The host refused the multi-select resource picker request.');
+        // A host that knows multi-select answers `selectedResources` (`[]` on
+        // dismiss). One that predates it ignored `multiple`, opened a single pick
+        // and answered `selected` (or nothing, on dismiss) — still a list here, of
+        // one or none, so the caller has ONE result shape to handle either way.
+        const picked = Array.isArray(result.selectedResources)
+            ? result.selectedResources
+            : result.selected
+                ? [result.selected]
+                : [];
+        // Belt: never hand back more than was asked for.
+        return picked.slice(0, max);
     }, []);
     return { open };
 }

package/dist/hooks/useSharedStorage.d.ts

@@ -1,4 +1,28 @@
 import type { SharedStorageValue } from '@civitai/app-sdk/blocks';
+/**
+ * A shared-storage write the server REFUSED because a per-(viewer, app) budget
+ * is empty — thrown by `append`, `update`, `vote`, `unvote`, `withdraw` and
+ * `report` when the host's refusal carries retry metadata.
+ *
+ * It EXTENDS `Error`, the class every other shared-storage refusal is thrown
+ * as, so existing `catch` code keeps working unchanged: `.message` is still the
+ * host's refusal text (for example `Too many submissions — retry in 312s`).
+ * Branch on `instanceof SharedStorageRateLimitError` to render the wait from
+ * {@link SharedStorageRateLimitError.retryAt} instead of parsing the message.
+ *
+ * Not thrown when the refusal carries no metadata — a host that predates it, or
+ * a refusal that is not a rate limit. Those stay a plain `Error`.
+ */
+export declare class SharedStorageRateLimitError extends Error {
+    /** Whole seconds until a retry can succeed, as of when the server refused. At least 1. */
+    readonly retryAfterSeconds: number;
+    /** ISO-8601 instant at which a retry can succeed. Prefer this for a countdown. */
+    readonly retryAt: string;
+    constructor(message: string, rateLimit: {
+        retryAfterSeconds: number;
+        retryAt: string;
+    });
+}
 /**
  * The value a viewer contributes to the SHARED store: a required `title`, an
  * optional long-form `body`, and an optional opaque app-owned `data` blob.

package/dist/hooks/useSharedStorage.js

@@ -2,6 +2,50 @@ import { useMemo } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply, throwOnReplyError } from '../internal/replyError.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { parseSharedStorageRateLimit } from '../transport/validate.js';
+/**
+ * A shared-storage write the server REFUSED because a per-(viewer, app) budget
+ * is empty — thrown by `append`, `update`, `vote`, `unvote`, `withdraw` and
+ * `report` when the host's refusal carries retry metadata.
+ *
+ * It EXTENDS `Error`, the class every other shared-storage refusal is thrown
+ * as, so existing `catch` code keeps working unchanged: `.message` is still the
+ * host's refusal text (for example `Too many submissions — retry in 312s`).
+ * Branch on `instanceof SharedStorageRateLimitError` to render the wait from
+ * {@link SharedStorageRateLimitError.retryAt} instead of parsing the message.
+ *
+ * Not thrown when the refusal carries no metadata — a host that predates it, or
+ * a refusal that is not a rate limit. Those stay a plain `Error`.
+ */
+export class SharedStorageRateLimitError extends Error {
+    /** Whole seconds until a retry can succeed, as of when the server refused. At least 1. */
+    retryAfterSeconds;
+    /** ISO-8601 instant at which a retry can succeed. Prefer this for a countdown. */
+    retryAt;
+    constructor(message, rateLimit) {
+        super(message);
+        this.name = 'SharedStorageRateLimitError';
+        this.retryAfterSeconds = rateLimit.retryAfterSeconds;
+        this.retryAt = rateLimit.retryAt;
+    }
+}
+/**
+ * Throw {@link SharedStorageRateLimitError} when a write reply is a refusal (a
+ * PRESENT `error`, the same test as `throwOnReplyError`) that carries valid
+ * `rateLimit`. Otherwise returns, and the caller's usual reply check throws the
+ * plain `Error` as before.
+ *
+ * Parses `rateLimit` rather than trusting it: the transport delivers it as the
+ * host sent it, so a malformed value is ignored here and the caller's plain
+ * `Error` is thrown instead.
+ */
+function throwOnSharedRateLimit(result, fallback) {
+    if (result.error === undefined)
+        return;
+    const rateLimit = parseSharedStorageRateLimit(result.rateLimit);
+    if (rateLimit)
+        throw new SharedStorageRateLimitError(result.error || fallback, rateLimit);
+}
 /**
  * App-scoped, append-only, community-votable SHARED datastore. Sibling of
  * {@link useAppStorage} (the per-viewer KV store) — same postMessage bridge,
@@ -15,6 +59,11 @@ import { sendTypedRequest } from '../transport/transport.js';
  * / `getCount(s)`) and a hard reject on mutations (`append`/`vote`/`unvote`/
  * `withdraw`).
  *
+ * Writes are budgeted per (viewer, app) server-side. A write refused for that
+ * reason rejects with {@link SharedStorageRateLimitError} (a subclass of the
+ * plain `Error` every other refusal is) carrying `retryAfterSeconds` and
+ * `retryAt`, whenever the host sends the metadata.
+ *
  * The hook is stable across renders — it returns the same object identity once
  * the transport singleton is created, so it's safe in `useEffect`/`useMemo`
  * dependency arrays.
@@ -71,6 +120,7 @@ export function useSharedStorage() {
             },
             async report(key, reason) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_REPORT', payload: { key, reason } }, 'SHARED_REPORT_RESULT');
+                throwOnSharedRateLimit(result, 'shared report failed');
                 throwOnFailedReply(result, 'shared report failed');
             },
             async getCount(key) {
@@ -85,25 +135,30 @@ export function useSharedStorage() {
             },
             async append(value) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_APPEND', payload: { value } }, 'SHARED_APPEND_RESULT');
+                throwOnSharedRateLimit(result, 'shared append failed');
                 throwOnReplyError(result, 'shared append failed');
                 return { key: result.key };
             },
             async update(key, value) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_UPDATE', payload: { key, value } }, 'SHARED_UPDATE_RESULT');
+                throwOnSharedRateLimit(result, 'shared update failed');
                 throwOnFailedReply(result, 'shared update failed');
             },
             async vote(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_VOTE', payload: { key } }, 'SHARED_VOTE_RESULT');
+                throwOnSharedRateLimit(result, 'shared vote failed');
                 throwOnReplyError(result, 'shared vote failed');
                 return result.count;
             },
             async unvote(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_UNVOTE', payload: { key } }, 'SHARED_UNVOTE_RESULT');
+                throwOnSharedRateLimit(result, 'shared unvote failed');
                 throwOnReplyError(result, 'shared unvote failed');
                 return result.count;
             },
             async withdraw(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_WITHDRAW', payload: { key } }, 'SHARED_WITHDRAW_RESULT');
+                throwOnSharedRateLimit(result, 'shared withdraw failed');
                 throwOnFailedReply(result, 'shared withdraw failed');
                 // `deleted` is optional on the wire type because an error reply omits
                 // it. On the success path the validator requires a boolean, so this is

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