@civitai/blocks-react 0.67.0 → 0.68.0

package/README.md

@@ -455,6 +455,46 @@ if (priced) {
   prices a cache hit at 0). `estimate` resolves it; only a non-numeric
   `cost.total` rejects.
 
+#### Showing the app fee: `cost.authorFee`
+
+`cost.total` is what the viewer pays and **already includes the app author's
+per-generation fee**. `cost.authorFee` is that fee on its own, in whole Buzz, so
+`total - authorFee` is the generation's price. It is display only.
+
+```tsx
+import type { BlockWorkflowSnapshot, WorkflowBody } from '@civitai/app-sdk/blocks';
+
+const { estimate } = useBuzzWorkflow();
+declare const body: WorkflowBody;
+
+function priceLine(cost: NonNullable<BlockWorkflowSnapshot['cost']>): string {
+  // Absent = not itemised. Show the total alone; do NOT treat it as a 0 fee.
+  if (cost.authorFee === undefined) return `${cost.total} Buzz`;
+  // 0 = a fee was looked up and none applies to this request.
+  if (cost.authorFee === 0) return `${cost.total} Buzz (no app fee)`;
+  const generation = cost.total - cost.authorFee;
+  return `${cost.total} Buzz (generation ${generation} + app fee ${cost.authorFee})`;
+}
+
+const quote = await estimate(body); // rejects without a usable price — see above
+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 |
+| `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 |
+
+- **Against an older host the field is simply absent.** Nothing else changes:
+  `total` has the same value with or without it, so an app that never reads
+  `authorFee` is unaffected.
+- **Test all three locally** with the mock host's `generation.authorFee`
+  (`createMockHost({ generation: { costPerGen: 40, authorFee: 5 } })`, or
+  `?authorFee=5` in the dev harness): a number itemises it, the default `0`
+  reports `authorFee: 0`, and `authorFee: false` (`?authorFee=off`) leaves it
+  out, as an older host does.
+
 > **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
@@ -467,6 +507,163 @@ if (priced) {
 > your installed version predates 0.5.0, do the client-side half and add the
 > `cancel(...)` call after upgrading.
 
+### `useBatchEstimate()`
+
+Price a grid of generations in one request. `estimateBatch(bodies)` takes a list
+of workflow bodies, each exactly what `useBuzzWorkflow().estimate()` takes, and
+resolves with one cell per body, in order, plus the run total. Returns
+`{ estimateBatch, pending, result, error }`.
+
+- **One request against the estimate allowance** however many cells it carries.
+  On a page app that allowance is shared by every viewer of the app and by the
+  host's other reads for it, so a 16-cell grid priced cell by cell used 16 of it.
+- **At most 16 bodies per call** (`BATCH_ESTIMATE_MAX_CELLS`). Price a larger grid
+  in several calls.
+- **Cells are metered too**, against an allowance of their own that is shared
+  the same way (on a page app, by every viewer of the app), so a batch is not a
+  way around the estimate allowance. A call over either limit is refused whole:
+  it rejects with `BatchEstimateError` code `'failed'`. Retry in a few seconds.
+- **Every rule of a single estimate applies to each cell.** A cell that one
+  `estimate()` would reject comes back as `ok: false` with the same
+  `WorkflowEstimateError`, and the other cells still price.
+- **`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
+  `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.
+
+`aggregate.total` sums the cells that priced. It covers the whole grid only when
+`aggregate.pricedCells === aggregate.cellCount`; otherwise show it as a partial
+total.
+
+**The host bounds the time one call takes.** If its budget runs out, the call
+still resolves: the cells that priced are returned, and every other cell is
+`ok: false` with `timedOut: true`. Show those cells as unavailable and let the
+viewer retry later. Branch on `timedOut`, not on `snapshot.error`: the host's
+wording is not a contract.
+
+`estimateBatch` rejects with `BatchEstimateError` only when the whole call
+failed. Branch on `err.code`:
+
+| `code` | Meaning | What to do |
+|---|---|---|
+| `'unsupported'` | The host answered `unsupported on this host`. | Price each cell with `estimate()`. |
+| `'timeout'` | No reply in time. A host that supports the batch replies within its own time budget, well inside the default wait, so this usually means a slow host, not an old one. | Show the estimate as unavailable and retry later. **Do not** fall back to one `estimate()` per cell: that sends up to 16 more estimates at a host that is already slow. |
+| `'invalid-request'` | Empty list, or more than 16 bodies. Refused before sending. | Fix the list. |
+| `'failed'` | Any other whole-call refusal: the scope, a rate limit, review preview. The reason is on `err.hostError`; log it, don't render it. | Show your own copy and retry later. |
+
+A 2 × 2 grid (two prompts × two checkpoints), falling back to per-cell estimates
+only on a host that answers `'unsupported'`:
+
+```tsx
+import { useState } from 'react';
+import type { WorkflowBody } from '@civitai/app-sdk/blocks';
+import {
+  BatchEstimateError,
+  useBatchEstimate,
+  useBuzzWorkflow,
+  WorkflowEstimateError,
+} from '@civitai/blocks-react';
+
+const PROMPTS = ['a lighthouse at dusk', 'a lighthouse in fog'];
+const CHECKPOINTS = [
+  { modelId: 101, modelVersionId: 1001 },
+  { modelId: 202, modelVersionId: 2002 },
+];
+
+/** One cell's quote: a price, or why it has none. */
+type CellQuote = { total: number } | { unavailable: string };
+
+export function GridQuote() {
+  const { estimateBatch } = useBatchEstimate();
+  const { estimate } = useBuzzWorkflow();
+  const [quotes, setQuotes] = useState<CellQuote[]>([]);
+  const [runTotal, setRunTotal] = useState<number | null>(null);
+
+  const bodies: WorkflowBody[] = PROMPTS.flatMap((prompt) =>
+    CHECKPOINTS.map((cp) => ({ kind: 'textToImage' as const, ...cp, params: { prompt } })),
+  );
+
+  // Your copy, chosen by `code` (and, for a batch cell, `timedOut`). Never
+  // render or match `err.message` or `snapshot.error`.
+  const why = (err: WorkflowEstimateError, timedOut = false) =>
+    timedOut
+      ? 'Price not ready, try again shortly'
+      : err.code === 'no-cost'
+        ? 'No price for this cell'
+        : 'This cell cannot run';
+
+  async function priceGrid() {
+    try {
+      const { cells, aggregate } = await estimateBatch(bodies);
+      setQuotes(
+        cells.map((c) => (c.ok ? { total: c.cost.total } : { unavailable: why(c.error, c.timedOut) })),
+      );
+      setRunTotal(aggregate.pricedCells === aggregate.cellCount ? aggregate.total : null);
+      return;
+    } catch (err) {
+      if (!(err instanceof BatchEstimateError)) throw err;
+      if (err.code !== 'unsupported') {
+        // 'timeout' is a slow host, not an old one: never fan out per cell here.
+        setQuotes([]);
+        setRunTotal(null);
+        return; // show "pricing unavailable, try again" in your UI
+      }
+    }
+    // This host has no batch estimate: one estimate() per cell, as before.
+    const fallback: CellQuote[] = [];
+    for (const body of bodies) {
+      try {
+        const snapshot = await estimate(body);
+        fallback.push({ total: snapshot.cost!.total });
+      } catch (err) {
+        if (!(err instanceof WorkflowEstimateError)) throw err;
+        fallback.push({ unavailable: why(err) });
+      }
+    }
+    setQuotes(fallback);
+    const priced = fallback.filter((q): q is { total: number } => 'total' in q);
+    setRunTotal(
+      priced.length === fallback.length ? priced.reduce((sum, q) => sum + q.total, 0) : null,
+    );
+  }
+
+  return (
+    <div>
+      <button onClick={() => void priceGrid()}>Price grid</button>
+      <ul>
+        {quotes.map((q, i) => (
+          <li key={i}>{'total' in q ? `${q.total} Buzz` : q.unavailable}</li>
+        ))}
+      </ul>
+      {runTotal !== null && <p>Run total: {runTotal} Buzz</p>}
+    </div>
+  );
+}
+```
+
+The fallback spends one request of the shared allowance per cell, which is why
+the batch exists. Each submit stays per cell: call `submit(bodies[i])` for each
+cell the viewer confirms.
+
+A host that predates the batch message never replies, so the call ends in
+`'timeout'` after the full wait. Only if your app must support such a host,
+detect it with a deliberate probe: send a one-body batch once with a short
+`{ timeoutMs }`, and treat only that probe's `'timeout'` as "no batch support".
+Any other `'timeout'` is a slow host.
+
+**Mock host:** `createMockHost` and `Harness` price each cell exactly as they
+price one `estimate()` of that body (`costPerGen` and `failEstimate` apply per
+cell). Set `generation.batchEstimate` to `'unsupported'` to test the fallback,
+or to `'silent'` to test a call that never gets a reply (pass a short
+`timeoutMs` in a test). Set `generation.batchEstimateTimedOutCells` to a list
+of cell indices to answer those cells the way the host does when its time
+budget runs out (`ok: false`, `timedOut: true`). **`dev:live`** forwards the call to civitai.com, so against
+a civitai.com that predates the batch procedure it rejects with `'failed'`
+rather than `'unsupported'`.
+
 ### `useBuzzPurchase()`
 
 Open the Buzz purchase modal. It raises the viewer's WALLET, never a spend cap:
@@ -1088,6 +1285,66 @@ await shared.unvote(key);
 await shared.withdraw(key);                            // remove my own entry
 ```
 
+#### Shared-storage write limits
+
+Every write is budgeted per **(viewer, app)** on the server. One viewer
+exhausting their budget in your app costs them nothing in another app, and
+re-minting the block token does not reset it.
+
+| Writes | Budget |
+|---|---|
+| `append` + `update` (one shared budget) | a **burst of 10**, refilling **1 every 6 minutes**, and a **daily bucket of 50**, refilling continuously (one every ~29 minutes). A write needs a token from both. |
+| — writes the server **refused** (moderation block, the 50-entry cap, quota, not found, …) | also charged to a **rejection bucket of 10**, refilling **1 every 30 minutes**. No `append`/`update` is accepted while it is empty. Concurrent refused writes can drive it into debt, down to −10, which has to refill first. |
+| `vote` + `unvote` | 30 a minute, shared |
+| `withdraw` | 30 a minute |
+| `report` | 20 a day |
+
+Only writes that **land** spend the `append`/`update` budget: a write that fails
+without landing gets its token back. The few failures the platform marks as its
+own fault are refunded without a rejection charge too.
+
+> The `append`/`update` budget above goes live with the next civitai.com
+> release. Until then the live limit is a fixed window of **20 posts + edits a
+> day** per (viewer, app). The vote, withdraw and report limits, and the retry
+> metadata below, are already live.
+
+A write refused for budget arrives with retry metadata, and the hook rejects with
+**`SharedStorageRateLimitError`**. It extends the plain `Error` every other
+refusal is thrown as, so existing `catch` code keeps working, and `.message` is
+still the server's text (`Too many submissions — retry in 312s`, or `votes`,
+`withdrawals`, `reports`). Branch on the class to render the wait instead of
+parsing the message:
+
+```tsx
+import { SharedStorageRateLimitError, useSharedStorage } from '@civitai/blocks-react';
+
+const shared = useSharedStorage();
+try {
+  await shared.append({ title: 'Add dark mode' });
+} catch (err) {
+  if (err instanceof SharedStorageRateLimitError) {
+    // err.retryAt: ISO-8601 instant a retry can succeed; err.retryAfterSeconds: whole seconds, ≥ 1.
+    const at = new Date(err.retryAt).toLocaleTimeString();
+    showNotice(`You're posting fast. Try again at ${at}.`);
+  } else {
+    throw err;
+  }
+}
+```
+
+- **Don't retry before `retryAt`.** A refused retry gets nothing, and once the
+  budget is empty every attempt is refused until it refills.
+- **Absent metadata is not "retry now".** A host that predates it, or a refusal
+  that is not a rate limit, throws the plain `Error`. The hook also ignores a
+  malformed `rateLimit` and throws the plain `Error`, rather than hand you
+  something you would render.
+- On the wire the refusal reply is `{ requestId, error, rateLimit?: { retryAfterSeconds, retryAt } }`
+  (type `SharedStorageRateLimit` in `@civitai/app-sdk/blocks`) on the six write
+  replies.
+- `createMockHost({ shared: { rateLimitNext: 1, rateLimit: { retryAfterSeconds: 312 } } })`
+  refuses the next write this way, so you can test the branch locally
+  (`setScenario({ shared: { rateLimitNext } })` arms it mid-session).
+
 ### `useCheckpointPicker()`
 
 Drive the platform Checkpoint picker + persist a viewer override.
@@ -1140,9 +1397,10 @@ if (isModelSlotContext(context) && context.checkpoint) {
 ### `useResourcePicker()`
 
 Drive the platform resource picker for page blocks — `'Checkpoint' | 'LORA'`.
-The viewer searches in host chrome; the block only ever sees the one resource it
-picked. DISCOVERY ONLY — the returned `versionId` is re-validated + re-priced
-server-side at estimate/submit.
+The viewer searches in host chrome; the block only ever sees what the viewer
+picked: one resource, or with `multiple` the few LoRAs they chose. DISCOVERY
+ONLY — a returned `versionId` is re-validated + re-priced server-side at
+estimate/submit.
 
 🔴 **OMIT `baseModelGroup` BY DEFAULT, and never pass a HARDCODED ecosystem.** It
 is an ecosystem-family FILTER, not a label: the host hides every resource outside
@@ -1159,10 +1417,11 @@ a picker returned earlier.
 
 For a complete multi-LoRA app, see
 [`starters/examples/generate-studio`](https://github.com/civitai/civitai-app-starters/tree/main/starters/examples/generate-studio):
-`src/components/ModelSection.tsx` opens the picker once per LoRA slot, up to
+`src/components/ModelSection.tsx` fills one LoRA slot per picker session, up to
 `MAX_LORAS`, with a `baseModelGroup` derived from the selected checkpoint, and
 `keepCompatibleLoras` (`src/studio/setup.ts`) re-filters the stack when the
-checkpoint changes, dropping LoRAs made for another family.
+checkpoint changes, dropping LoRAs made for another family. To fill several
+slots in ONE session, use `multiple` (below).
 
 ```tsx
 const { open } = useResourcePicker();
@@ -1188,6 +1447,45 @@ if (checkpoint) {
 }
 ```
 
+**Several LoRAs in one session — `multiple: { max }`.** The viewer stages up to
+`max` LoRAs in the picker and confirms once; `open` resolves with a **list**, in
+the order the viewer picked them, instead of a single resource. Dismissing
+resolves with `[]`.
+
+```tsx
+const { open } = useResourcePicker();
+
+const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
+// [] when dismissed; otherwise up to 3 BlockResourceInfo, in pick order
+const additionalResources = loras.map((lora) => ({
+  modelVersionId: lora.versionId,
+  strength: lora.strength ?? 1,
+}));
+```
+
+- **LoRA only.** `multiple` with `resourceType: 'Checkpoint'` is a type error and
+  rejects at runtime — it is never quietly treated as a single pick.
+- **`max` is a whole number of at least 1, capped at 5** (the cap on
+  `additionalResources`, exported as `RESOURCE_PICKER_MULTIPLE_MAX`). A larger
+  value is clamped to 5; `0`, a negative or a fraction rejects.
+- **`baseModelGroup` works the same** — pass the family derived from the
+  checkpoint the block holds and every LoRA offered matches it.
+- **Each entry is the same `BlockResourceInfo`** a single pick returns, and every
+  id is still re-validated at estimate/submit.
+- **Without `multiple`, nothing changes**: `open` resolves with one resource or
+  `null`, exactly as before.
+- **On a host that predates multi-select** the viewer gets the single-pick
+  picker, and `open` still resolves with a list: of the one LoRA they picked, or
+  `[]`. The result does not say which kind of host answered, so a one-item
+  list is not a signal to open the picker again: on a current host it means the
+  viewer chose one. Let the viewer add more with their own action instead.
+
+With the mock host — `createMockHost` or `Harness` from
+`@civitai/blocks-react/testing` — a `multiple` request resolves with two curated
+LoRAs by default. Pass `cannedMultiPicks: [...]` to choose the list (it is cut to
+the request's `max`), or `cannedMultiPicks: null` for a dismissed picker. The mock
+answers a raw `multiple` + Checkpoint request with the host's error.
+
 ### `useImageUpload()`
 
 Host-mediated image upload — the host opens its native upload modal and the
@@ -1249,11 +1547,35 @@ neither an image nor an error. If no reply arrives within 10 minutes it
 rejects with a `RequestTimeoutError`; the host may still have stored the
 image, so retrying after a timeout can create a duplicate.
 
-🔴 **A host that predates this variant ignores `bytes` and opens its upload
-picker instead**, so the call settles on whatever the viewer picks. The hook
-needs civitai/civitai#5639 merged and deployed to civitai.com. That PR is still
-changing, so no intermediate head of it is enough. Do not ship a block that
-relies on `useUploadImageBytes()` before then.
+The hook ships in `@civitai/blocks-react` 0.67.0, and the `bytes` payload type
+it sends is in `@civitai/app-sdk` 0.62.0.
+
+What the upload does and does not give you on civitai.com:
+
+- 🔴 **Generation metadata embedded in the file is not read.** The posted
+  image has no generation details (prompt, resources, sampler settings),
+  whatever the PNG or JPEG carries. In the example below the healed pixels are
+  posted, and the metadata the app repaired is not shown on the post.
+- 🔴 **Each uploaded image goes into exactly one post.** Once a post holds it,
+  `createPost()` refuses that `imageId` with `an image is not available to post`.
+  To post the same picture again, upload it again.
+- **An uploaded image never appears in `useGatedImages()`.** That read returns
+  only what the app published with `usePublishGenerationOutputs()`. Keep the
+  `imageId` and `url` that `upload` resolves with if you need to show it.
+- **A post holds at most 20 images and names at most 10 sources.** Past 20
+  images the server refuses with `a post may contain at most 20 images`.
+- **Posting from apps is still being rolled out.** A viewer who does not have it
+  yet is refused with `posting from apps is not enabled`, and the refusal
+  arrives from `upload` as well as from `createPost()`. Handle it as an
+  ordinary error branch, not as a bug in your app.
+- **Creating the post needs an account with a verified email or a linked
+  sign-in provider.** Other account checks apply too: onboarding must be
+  finished, the account must not be brand new, and it must not be muted or
+  banned. `upload` refuses a banned account but checks none of the rest, so a
+  viewer can upload and then be refused at `createPost()`.
+- **Server-side limits also apply**, to the upload and to the post, beyond the
+  host's per-page window above. A `busy` reply or a rate-limit error such as
+  `Rate limit exceeded, please retry shortly.` means wait and retry.
 
 ```tsx
 import {
@@ -1499,13 +1821,60 @@ produces from the call a block actually makes.
 
 ### `useBlockAnalytics()`
 
-Fire-and-forget event tracking into the host's analytics pipeline.
+Custom events for your app's analytics panel. Fire-and-forget: no reply, no
+acknowledgement.
 
 ```tsx
 const { track } = useBlockAnalytics();
-track('generate_clicked', { modelId });
+track('generate_clicked', { mode: 'txt2img', batch: 4 });
+```
+
+🔴 **Only what your manifest DECLARES is recorded.** Declare every event, and
+every property it carries, under `analytics.events` in `block.manifest.json`.
+Events are accepted against the APPROVED manifest, so a reviewer sees what your
+app tracks:
+
+```json
+"analytics": {
+  "events": {
+    "generate_clicked": {
+      "description": "User pressed Generate",
+      "properties": {
+        "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+        "batch": { "type": "number" },
+        "advanced": { "type": "boolean" }
+      }
+    }
+  }
+}
 ```
 
+| You send | Production |
+|---|---|
+| A declared event, declared properties of the declared type | Recorded |
+| An event the manifest does not declare | Counted as a drop; its name and properties are not stored |
+| A property the event does not declare | Dropped; the rest of the event is recorded |
+| A value of the wrong type, or a string that is not one of the enum's values | Dropped; the rest of the event is recorded |
+
+- **Types are `enum`, `number` and `boolean`.** There is no free-text string, so
+  a prompt, an email or a username cannot be recorded. A `number` is not
+  range-limited: do not use one to carry an identifier.
+- **Names** are lowercase snake_case (a letter, then up to 63 of `a-z`, `0-9`,
+  `_`). At most 50 events per app and 10 properties per event.
+- **Limits.** Each mount of your app may send 10 events a second and 500 in
+  total, in bodies of at most 32 KiB. An event over a limit is dropped in the
+  browser and counted nowhere, so the panel's numbers are floors.
+- **Where.** Events are recorded only from the production site.
+- **What owners see.** Aggregates in the app's analytics panel: per declared
+  event, counts, unique signed-in viewers and property breakdowns. Signed-out
+  viewers are counted as events, never identified. The team's own activity is
+  excluded by default. Individual events are never shown.
+
+**Check it locally.** Pass your manifest to `createLiveHost` (see
+[`/live`](#in-a-devlive-harness)); in `dev:live` the console then warns once per
+undeclared event, undeclared property, or value of the wrong type. Every
+`starters/examples/*` harness does this.
+
 ### `useRequestSignIn()`
 
 Ask the host to open its sign-in flow for an ANONYMOUS viewer (fire-and-forget).
@@ -2243,7 +2612,7 @@ set, failing on growth and on shrinkage.
 | Export | What it is |
 |---|---|
 | `createLiveHost` | 🔴 **Real backend, real Buzz.** Installs a host that proxies the block's `postMessage` traffic to civitai.com using a dev block token. Returns a handle; call `.install()` and keep the teardown, exactly like `createMockHost`. |
-| `LiveHostOptions` *(type)* | Options for the above. `blockToken` is required; everything else (`backendBaseUrl`, `viewer`, `theme`, `context`, `onOutbound`, …) has a default. |
+| `LiveHostOptions` *(type)* | Options for the above. `blockToken` is required; everything else (`backendBaseUrl`, `viewer`, `theme`, `context`, `onOutbound`, `manifest`, …) has a default. Pass `manifest` to have `TRACK_EVENT` checked against `analytics.events`. |
 
 ### In a `dev:live` harness
 
@@ -2255,6 +2624,10 @@ import { createLiveHost, type LiveHostOptions } from '@civitai/blocks-react/live
 const options: LiveHostOptions = {
   blockToken: devBlockToken,
   theme: 'dark',
+  // Your block.manifest.json, as imported. Each `track()` is checked against its
+  // `analytics.events`, and the console warns once per undeclared event,
+  // undeclared property, or value of the wrong type — what production drops.
+  manifest,
 };
 
 const host = createLiveHost(options);

package/dist/hooks/useBatchEstimate.d.ts

@@ -0,0 +1,190 @@
+import type { BlockEstimateBatchAggregate, BlockWorkflowSnapshot, WorkflowBody } from '@civitai/app-sdk/blocks';
+import { WorkflowEstimateError } from './useBuzzWorkflow.js';
+export type { BlockEstimateBatchAggregate };
+/**
+ * The most bodies one {@link UseBatchEstimate.estimateBatch} call may carry.
+ *
+ * The host's own cap (`BLOCK_ESTIMATE_BATCH_MAX_CELLS` in civitai/civitai). The
+ * hook refuses a longer list before sending it, with the code the host would
+ * have answered with a round trip later. A larger grid is priced in several
+ * calls; each call is still one request against the estimate allowance.
+ */
+export declare const BATCH_ESTIMATE_MAX_CELLS = 16;
+/**
+ * The host's `snapshot.error` for a batch cell its time budget ran out on before
+ * the cell priced. The copy is the host's (`BLOCK_ESTIMATE_BATCH_TIMEOUT_ERROR`
+ * in civitai/civitai `src/server/routers/blocks.router.ts`). This is the ONE
+ * place the SDK spells it: the hook maps it to {@link BatchEstimateCell}'s
+ * `timedOut`, and the mock host answers with it. Not exported from the package:
+ * apps branch on `timedOut`, never on this string.
+ */
+export declare const BATCH_ESTIMATE_CELL_TIMEOUT_ERROR = "estimate timed out";
+/**
+ * Why a WHOLE batch estimate was refused. The stable branch target on
+ * {@link BatchEstimateError}.
+ *
+ * - `'unsupported'` — the host answered `unsupported on this host`: it knows the
+ *   message and has no handler for it on this surface. Nothing was priced. **Fall
+ *   back to one `useBuzzWorkflow().estimate()` per cell.**
+ * - `'timeout'` — no reply arrived in time. A host that supports the message
+ *   bounds its own work and replies well inside the default wait, marking any
+ *   cell it could not price in time as an `ok: false` cell with `timedOut:
+ *   true`, so this code usually means the host or its upstream is SLOW, not
+ *   that it is old. 🔴 Do NOT fall back to per-cell estimates here:
+ *   that sends up to 16 more estimates at an upstream that is already struggling.
+ *   Show the estimate as unavailable and let the viewer retry later. A host that
+ *   predates the message also ends here (it never replies); an app that must
+ *   tell the two apart can probe once with a one-body batch and a short explicit
+ *   `timeoutMs`, and treat only THAT probe's `'timeout'` as "no batch support".
+ * - `'invalid-request'` — the list is empty, is not an array, or holds more than
+ *   {@link BATCH_ESTIMATE_MAX_CELLS} bodies. Refused by the hook before sending,
+ *   or by the host. A per-cell fallback is pointless for an empty list and is the
+ *   wrong fix for an over-long one: split it.
+ * - `'failed'` — the host or the server refused the call for another reason (the
+ *   scope, the rate limit, review preview, no credential) or returned something
+ *   that is not a batch result. The reason is on
+ *   {@link BatchEstimateError.hostError}.
+ */
+export type BatchEstimateErrorCode = 'unsupported' | 'timeout' | 'invalid-request' | 'failed';
+/**
+ * Thrown by {@link UseBatchEstimate.estimateBatch} when the WHOLE call failed.
+ *
+ * One cell failing is NOT this: a cell that could not be priced comes back as an
+ * `ok: false` entry in {@link BatchEstimateResult.cells} and the call resolves.
+ *
+ * Same three-audience split as `WorkflowEstimateError`:
+ * - {@link BatchEstimateError.code} is what you branch on.
+ * - {@link BatchEstimateError.hostError} is the host's or server's own text. It
+ *   is server-authored and unsanitised: log it, never render it.
+ * - `message` is a generic developer-facing summary whose wording is not a
+ *   contract.
+ */
+export declare class BatchEstimateError extends Error {
+    readonly code: BatchEstimateErrorCode;
+    /** The host's or server's reason, verbatim, when it gave one. */
+    readonly hostError?: string;
+    constructor(code: BatchEstimateErrorCode, hostError?: string);
+}
+/**
+ * One cell of a batch estimate — the answer to the body at the same index.
+ *
+ * - `ok: true` — the cell priced. `cost` is the cost object a single
+ *   `estimate()` returns for that body, passed through untouched (`cost.total`
+ *   is the price shown before `submit()`).
+ * - `ok: false` — the cell did not price. `error` is the SAME
+ *   `WorkflowEstimateError` a single `estimate()` of that body would have
+ *   rejected with (`code: 'failed' | 'no-cost'`, the reason on
+ *   `error.snapshot.error`), so one function can turn either into viewer copy.
+ *   It is a value here, not a throw: the other cells are still usable.
+ * - `timedOut` (on `ok: false` only) — `true` when the host's time budget for
+ *   the call ran out before this cell priced (its `error.code` is `'failed'`).
+ *   Show it as unavailable and retry later rather than re-estimating it at once.
+ *   Branch on `timedOut`, never on `snapshot.error`: the host's wording is not a
+ *   contract, and the hook maps it here so no app has to match it.
+ *
+ * `snapshot` is the host's snapshot for the cell, verbatim, on both arms.
+ */
+export type BatchEstimateCell = {
+    ok: true;
+    cost: NonNullable<BlockWorkflowSnapshot['cost']>;
+    snapshot: BlockWorkflowSnapshot;
+} | {
+    ok: false;
+    error: WorkflowEstimateError;
+    /** `true` when the host's time budget for the call ran out before this cell priced. */
+    timedOut: boolean;
+    snapshot: BlockWorkflowSnapshot;
+};
+/** What {@link UseBatchEstimate.estimateBatch} resolves with. */
+export interface BatchEstimateResult {
+    /** One entry per body, in the order the bodies were given. */
+    cells: BatchEstimateCell[];
+    /**
+     * The host's run total over the cells that priced. It covers the whole list
+     * only when `aggregate.pricedCells === aggregate.cellCount`.
+     */
+    aggregate: BlockEstimateBatchAggregate;
+}
+/** Options for one {@link UseBatchEstimate.estimateBatch} call. */
+export interface EstimateBatchOptions {
+    /**
+     * How long to wait for the host's reply, in milliseconds. Default
+     * `WORKFLOW_REQUEST_TIMEOUT_MS` (120,000), the single estimate's bound.
+     *
+     * A host that supports the batch replies within its own time budget, well
+     * inside this default, so leave it unset for ordinary pricing. Pass a short
+     * value only for a deliberate old-host probe (a one-body batch, sent once):
+     * a host that predates the message never replies, and a short wait finds that
+     * out sooner. A short wait on a full grid gives up on slow but healthy batches.
+     */
+    timeoutMs?: number;
+}
+/** What {@link useBatchEstimate} returns. */
+export interface UseBatchEstimate {
+    /**
+     * Price several workflow bodies in one request. Resolves with one cell per
+     * body, in order, plus a run total; rejects with {@link BatchEstimateError}
+     * only when the whole call failed.
+     *
+     * 🔴 ESTIMATE ONLY. Nothing is submitted and no Buzz is held or spent. Submit
+     * each cell with `useBuzzWorkflow().submit()`, which asks the viewer and
+     * checks the budget per cell.
+     */
+    estimateBatch: (bodies: WorkflowBody[], options?: EstimateBatchOptions) => Promise<BatchEstimateResult>;
+    /** `true` while the most recent call is in flight. */
+    pending: boolean;
+    /**
+     * The most recent call's result, or `null` before the first one and after a
+     * call that failed — a failed call never leaves an earlier total on display.
+     */
+    result: BatchEstimateResult | null;
+    /** The most recent call's error, or `null`. */
+    error: BatchEstimateError | null;
+}
+/**
+ * Price a grid of generations in ONE request: a list of workflow bodies in, one
+ * result per body (a cost, or that cell's error) plus a run total out. Backed by
+ * the `ESTIMATE_WORKFLOW_BATCH` → `ESTIMATE_BATCH_RESULT` bridge.
+ *
+ * Use it where an app would otherwise call `useBuzzWorkflow().estimate()` once
+ * per cell. Every rule a single estimate enforces still applies to each cell;
+ * what changes is the accounting and the round trips:
+ *
+ * - **One request against the estimate allowance**, whatever the number of
+ *   cells. On a page app that allowance is shared by every viewer of the app and
+ *   by the host's other reads for it, so a 16-cell grid used to take 16 of it per
+ *   pricing pass.
+ * - **Cells are metered separately.** The host also counts the cells of every
+ *   batch against an allowance of their own, shared like the estimate allowance
+ *   (on a page app, by every viewer of the app), so a batch is not a way around
+ *   it. A call over either is refused whole (`code: 'failed'`, the host's
+ *   rate-limit text on `hostError`); retry in a few seconds.
+ * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
+ * - **`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()`.
+ *
+ * Like `estimate()`, this does NOT prompt for consent. It needs the
+ * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.
+ *
+ * @example
+ * const { estimateBatch } = useBatchEstimate();
+ * try {
+ *   const { cells, aggregate } = await estimateBatch(bodies);
+ *   // cells[i] answers bodies[i]; a cell with `!c.ok && c.timedOut` was not
+ *   // priced in time — show it as unavailable and retry later
+ * } catch (err) {
+ *   if (!(err instanceof BatchEstimateError)) throw err;
+ *   if (err.code === 'unsupported') {
+ *     // this host has no batch estimate — price each cell with estimate()
+ *   } else {
+ *     // 'timeout' (a slow host, not an old one) or 'failed': show the estimate
+ *     // as unavailable and retry later — never one estimate() per cell
+ *   }
+ * }
+ */
+export declare function useBatchEstimate(): UseBatchEstimate;
+//# sourceMappingURL=useBatchEstimate.d.ts.map