@civitai/blocks-react 0.69.0 → 0.70.0

package/README.md

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

package/dist/hooks/useWorkflowBatch.d.ts

@@ -135,7 +135,7 @@ export interface UseWorkflowBatch {
 /**
  * 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
+ * with `useBuzzWorkflow().submit()` (one submit per cell) and then
  * have to follow all N.
  *
  * 🔴 THE APP OWNS THE LIST, AND THE LIST IS THE BATCH. Pass the workflow ids as

package/dist/hooks/useWorkflowBatch.js

@@ -87,7 +87,7 @@ function summarise(cells) {
 /**
  * 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
+ * with `useBuzzWorkflow().submit()` (one submit per cell) and then
  * have to follow all N.
  *
  * 🔴 THE APP OWNS THE LIST, AND THE LIST IS THE BATCH. Pass the workflow ids as

package/dist/internal/mockHost.d.ts

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

package/dist/internal/mockHost.js

@@ -173,8 +173,14 @@ function isValidTrainingDatasetItems(items) {
             caption.length <= MOCK_TRAINING_BOUNDS.captionMaxChars);
     });
 }
-/** The real server's refusal for a training request from a token without the spend scope. */
-export const MOCK_TRAINING_SCOPE_ERROR = 'block lacks ai:write:budgeted scope';
+/**
+ * The real server's refusal for ANY money call from a token without the spend
+ * scope: civitai's `estimateWorkflow`, `estimateWorkflowBatch`, `submitWorkflow`
+ * and the training procedures all throw `FORBIDDEN` with exactly this message
+ * BEFORE any pricing, rate-limit or budget work. ONE constant for every mock
+ * path that refuses on `consentGranted === false`, so the copies cannot drift.
+ */
+export const MOCK_SPEND_SCOPE_ERROR = 'block lacks ai:write:budgeted scope';
 /** The real server's refusal for an unknown, expired or spent quote on `RUN_TRAINING`. */
 export const MOCK_TRAINING_QUOTE_GONE_ERROR = 'training quote not found, expired or already used — estimate again';
 /** The real server's refusal for a training estimate naming a dataset it does not hold. */
@@ -1262,20 +1268,39 @@ export function createMockHost(options = {}) {
                         // two to diagnose from the block side.
                         return { workflowId: 'wf_estimate', status: 'pending' };
                     }
+                    // 🔴 THE SPEND-SCOPE GATE — EVERY body kind, not just training.
+                    // civitai's `estimateWorkflow` throws `FORBIDDEN` with exactly this
+                    // message as its FIRST act after authenticating the token, before any
+                    // pricing, and the page host catches the throw into
+                    // `failureSnapshot(err)` — the `'failed'` sentinel id, no `cost`. That
+                    // is the signal a block answers with `requestConsent(...)` and a retry.
+                    // Until #608 only the training arm checked it, so the refusal → consent
+                    // → retry loop was unreachable for every other estimate in `pnpm dev`.
+                    //
+                    // Sits AFTER the `failEstimate` knobs on purpose: an explicitly forced
+                    // failure is what the author asked to see, and `estimate()` is not
+                    // consent-retried, so a scope refusal ahead of it would hide the knob
+                    // behind a message the author never asked for.
+                    //
+                    // The batch path refuses the WHOLE call before it reaches this function
+                    // (see ESTIMATE_WORKFLOW_BATCH), so this branch is the single-estimate
+                    // one in practice.
+                    if (!consentGranted) {
+                        return { workflowId: 'failed', status: 'failed', error: MOCK_SPEND_SCOPE_ERROR };
+                    }
                     // TRAINING ESTIMATE — KIND-FAITHFUL, the one exception to the
                     // kind-agnostic rule above, because the real arm is not a priced
-                    // pass-through: it needs the spend scope, names a dataset the server
-                    // must hold, refuses a price above the per-run ceiling, and STORES a
-                    // quote the run is later checked against. Each refusal is the
-                    // server's message in the host's `failureSnapshot` shape.
+                    // pass-through: it names a dataset the server must hold, refuses a
+                    // price above the per-run ceiling, and STORES a quote the run is later
+                    // checked against. (The spend scope is checked above, for every kind.)
+                    // Each refusal is the server's message in the host's `failureSnapshot`
+                    // shape.
                     if (body.kind === 'training') {
                         const refuse = (error) => ({
                             workflowId: 'failed',
                             status: 'failed',
                             error,
                         });
-                        if (!consentGranted)
-                            return refuse(MOCK_TRAINING_SCOPE_ERROR);
                         const imageCount = trainingDatasets.get(body.datasetId);
                         if (imageCount === undefined)
                             return refuse(MOCK_TRAINING_DATASET_GONE_ERROR);
@@ -1458,6 +1483,21 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        // 🔴 THE SPEND-SCOPE GATE, WHOLE-CALL. civitai's
+                        // `estimateWorkflowBatch` throws `FORBIDDEN` before pricing a single
+                        // cell, and the host (`estimateBatchGate.ts`) catches the throw into
+                        // `{ requestId, error: err.message }` — NOT a per-cell failure, and
+                        // no `snapshots`/`aggregate`. The SDK surfaces it as
+                        // `BatchEstimateError` code `'failed'` with this text on `hostError`.
+                        // After the request-shape checks above, because those are the host's
+                        // own gate and run before the server is consulted.
+                        if (!consentGranted) {
+                            dispatchToBlock({
+                                type: 'ESTIMATE_BATCH_RESULT',
+                                payload: { requestId, error: MOCK_SPEND_SCOPE_ERROR },
+                            });
+                            return;
+                        }
                         const snapshots = bodies.map((cell, index) => {
                             // The host's snapshot for a cell its call budget ran out on.
                             if (gen.batchEstimateTimedOutCells?.includes(index)) {
@@ -1510,13 +1550,14 @@ export function createMockHost(options = {}) {
                         // the largest-wallet stamp. No recipe-registry validation.
                         submitCount += 1;
                         const body = typed.payload?.body ?? {};
-                        // A `kind: 'training'` body is never started by SUBMIT_WORKFLOW: the
-                        // server charges a training run only against a quote a signed-in
-                        // session confirmed, which only RUN_TRAINING's dialog records. The
-                        // server's own refusal, in the host's `failureSnapshot` shape.
-                        // (`useBuzzWorkflow().submit()` refuses before sending; this covers a
-                        // raw transport send.)
-                        if (body.kind === 'training') {
+                        // CAUGHT-SERVER-EXCEPTION simulation (`generation.failSubmitException`).
+                        // Reproduces the host's `failureSnapshot(err)` byte-for-byte: the
+                        // 'failed' sentinel id and NO `cost`, which is what separates an
+                        // errored submit from a priced budget rejection
+                        // (civitai/civitai-app-starters#251). Checked FIRST — a forced
+                        // host-side throw pre-empts every server-side decision below,
+                        // including the spend-scope gate.
+                        if (gen.failSubmitException === true) {
                             dispatchToBlock({
                                 type: 'WORKFLOW_SUBMITTED',
                                 payload: {
@@ -1524,22 +1565,39 @@ export function createMockHost(options = {}) {
                                     snapshot: {
                                         workflowId: 'failed',
                                         status: 'failed',
-                                        error: 'this training run has not been confirmed by the viewer in this session',
+                                        error: gen.failSubmitExceptionMessage ?? 'mock: submit failed',
                                     },
                                 },
                             });
                             return;
                         }
-                        const cost = costFor(body);
-                        // What the viewer pays: the generation plus the app fee.
-                        const charged = cost + (authorFeeFor(body) ?? 0);
-                        // CAUGHT-SERVER-EXCEPTION simulation (`generation.failSubmitException`).
-                        // Reproduces the host's `failureSnapshot(err)` byte-for-byte: the
-                        // 'failed' sentinel id and NO `cost`, which is what separates an
-                        // errored submit from a priced budget rejection
-                        // (civitai/civitai-app-starters#251). Checked FIRST — a host-side
-                        // throw pre-empts every server-side decision below.
-                        if (gen.failSubmitException === true) {
+                        // 🔴 THE SPEND-SCOPE GATE. civitai's `submitWorkflow` throws
+                        // `FORBIDDEN` with this message as its first act after
+                        // authenticating the token — before the budget, the training
+                        // confirmation, the currency resolution and any debit — and the page
+                        // host's SUBMIT_WORKFLOW handler catches the rejected mutation into
+                        // `failureSnapshot(err)`: the `'failed'` sentinel, NO `cost`. So
+                        // `submit()` rejects as `'exception'`, and `withConsentRetry` (the
+                        // token lacks `ai:write:budgeted`) prompts, this mock grants and
+                        // pushes TOKEN_REFRESH, and the SAME-KEY retry lands below. Nothing
+                        // is debited and no workflow is recorded on this arm.
+                        if (!consentGranted) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_SUBMITTED',
+                                payload: {
+                                    requestId,
+                                    snapshot: { workflowId: 'failed', status: 'failed', error: MOCK_SPEND_SCOPE_ERROR },
+                                },
+                            });
+                            return;
+                        }
+                        // A `kind: 'training'` body is never started by SUBMIT_WORKFLOW: the
+                        // server charges a training run only against a quote a signed-in
+                        // session confirmed, which only RUN_TRAINING's dialog records. The
+                        // server's own refusal, in the host's `failureSnapshot` shape.
+                        // (`useBuzzWorkflow().submit()` refuses before sending; this covers a
+                        // raw transport send.)
+                        if (body.kind === 'training') {
                             dispatchToBlock({
                                 type: 'WORKFLOW_SUBMITTED',
                                 payload: {
@@ -1547,12 +1605,15 @@ export function createMockHost(options = {}) {
                                     snapshot: {
                                         workflowId: 'failed',
                                         status: 'failed',
-                                        error: gen.failSubmitExceptionMessage ?? 'mock: submit failed',
+                                        error: 'this training run has not been confirmed by the viewer in this session',
                                     },
                                 },
                             });
                             return;
                         }
+                        const cost = costFor(body);
+                        // What the viewer pays: the generation plus the app fee.
+                        const charged = cost + (authorFeeFor(body) ?? 0);
                         // Disallowed-account path (content-rating clamp): the real backend
                         // rejects a picked pool outside the app's maturity policy at the
                         // currency-resolution boundary — BEFORE any Buzz spend — so this is
@@ -2111,7 +2172,7 @@ export function createMockHost(options = {}) {
                             return reply({ error: 'invalid training dataset' });
                         }
                         if (!consentGranted)
-                            return reply({ error: MOCK_TRAINING_SCOPE_ERROR });
+                            return reply({ error: MOCK_SPEND_SCOPE_ERROR });
                         if (trainingDatasetError !== undefined)
                             return reply({ error: trainingDatasetError });
                         const named = new Set(items.map((it) => it.imageId));
@@ -2154,7 +2215,7 @@ export function createMockHost(options = {}) {
                             return reply({ error: 'invalid training request' });
                         }
                         if (!consentGranted)
-                            return reply({ error: MOCK_TRAINING_SCOPE_ERROR });
+                            return reply({ error: MOCK_SPEND_SCOPE_ERROR });
                         const quote = trainingQuotes.get(b.quoteId);
                         if (!quote || quote.spent || Date.now() >= quote.expiresAtMs) {
                             return reply({ error: MOCK_TRAINING_QUOTE_GONE_ERROR });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.69.0",
+  "version": "0.70.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.65.0"
+    "@civitai/app-sdk": "^0.65.1"
   },
   "publishConfig": {
     "access": "public"