@civitai/blocks-react 0.60.0 → 0.61.1

package/README.md

@@ -123,7 +123,9 @@ const { ready, context, viewer, theme, settings, blockId, blockInstanceId, appId
 ```
 
 - `context` — `BlockContext` (`{ slotId, … }`); narrow to `ModelSlotContext` for
-  model-page slots.
+  model-page slots. LIVE on a page slot: `context.subPath` starts at the
+  `BLOCK_INIT` value and then tracks the host's `ROUTE_CHANGED` push on every
+  navigation — see [`useCivitaiRoute()`](#usecivitairoute).
 - `viewer` — `ViewerInfo | null` (`null` = anonymous). **Gate sign-in with
   `isSignedIn(viewer)`** (from `@civitai/app-sdk/blocks`), never on
   `viewer.id`/`viewer.username` (both `@deprecated`). Don't open-code the gate:
@@ -961,10 +963,49 @@ await shared.withdraw(key);                            // remove my own entry
 
 Drive the platform Checkpoint picker + persist a viewer override.
 
+🔴 **OMIT `baseModelGroup` BY DEFAULT.** It is an ecosystem-family FILTER, not a
+label: the host HIDES every checkpoint outside the family you pass, so passing the
+family you are already in is a trap — the picker then offers only the ecosystem the
+user is trying to leave. Omit it for an unconstrained pick and the host applies no
+narrowing at all, offering every checkpoint the viewer can generate with. Pass it
+ONLY when the block must stay inside a family it already holds — a
+regenerate/variation flow, say — and then DERIVE it from that checkpoint, never a
+hardcoded ecosystem string: a literal pins every viewer to whichever family the
+author happened to test with. `''` is **not** an escape hatch — it does not even
+mean the same thing on both hosts. On a **model slot** the host normalises whatever
+string you send, so `''` resolves to the real ecosystem key `Other` and NARROWS to
+that one family. On a **page** the host drops a zero-length value, so `''` behaves
+exactly like omitting it. Neither is what you meant on at least one surface: omit
+the key, or pass a family derived from a real checkpoint, and never `''`.
+
+```tsx
+import { isModelSlotContext } from '@civitai/app-sdk/blocks';
+
+const { context } = useBlockContext();
+const { open, persist } = useCheckpointPicker();
+
+// DEFAULT — pass no baseModelGroup. The viewer can reach every family.
+if (isModelSlotContext(context) && context.checkpoint) {
+  const { selected } = await open({ currentVersionId: context.checkpoint.versionId });
+  if (selected) await persist(selected.versionId);   // null clears the override
+}
+```
+
+Pass `baseModelGroup` **only** when the block must stay inside a family it already
+holds — a regenerate or variation flow pinned to one checkpoint's ecosystem — and
+then derive it from that checkpoint, never from a literal:
+
 ```tsx
+import { isModelSlotContext } from '@civitai/app-sdk/blocks';
+
+const { context } = useBlockContext();
 const { open, persist } = useCheckpointPicker();
-const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
-if (selected) await persist(selected.versionId);   // null clears the override
+
+// ONLY to stay inside the family the block already holds — derived, never a literal.
+if (isModelSlotContext(context) && context.checkpoint) {
+  const { selected } = await open({ baseModelGroup: context.checkpoint.baseModel });
+  if (selected) await persist(selected.versionId);
+}
 ```
 
 ### `useResourcePicker()`
@@ -974,15 +1015,39 @@ 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.
 
+🔴 **Pass NO `baseModelGroup` by default.** It is an optional FILTER, and the host
+hides every resource outside the family you pass — so a hardcoded ecosystem makes
+the viewer's own valid LoRAs invisible and the picker look empty or broken. Omit
+it and the viewer sees everything of that type.
+
 ```tsx
 const { open } = useResourcePicker();
-const picked = await open({ resourceType: 'LORA', baseModelGroup: 'SDXL' });
+const picked = await open({ resourceType: 'LORA' });   // unconstrained — the default
 if (picked) {
   const versionId = picked.versionId;   // feed into body.additionalResources
   const weight = picked.strength;        // recommended default weight (may be undefined)
 }
 ```
 
+Constrain it **only** when the block already holds a chosen checkpoint the pick has
+to match — and then derive the family from that checkpoint, never from a literal.
+🔴 **This hook is PAGE-ONLY, and a page slot has no `context.checkpoint`** — that
+field lives on `ModelSlotContext` alone, so the family comes from
+`BlockResourceInfo.baseModel`, the `baseModel` of a Checkpoint this same picker
+returned earlier:
+
+```tsx
+const { open } = useResourcePicker();
+
+const checkpoint = await open({ resourceType: 'Checkpoint' });
+if (checkpoint) {
+  const matching = await open({
+    resourceType: 'LORA',
+    baseModelGroup: checkpoint.baseModel,   // from the pick above — BlockResourceInfo.baseModel
+  });
+}
+```
+
 ### `useImageUpload()`
 
 Host-mediated image upload — the host opens its native upload modal and the
@@ -1018,13 +1083,113 @@ const first = resources[0];             // .versionId / .strength / .trainedWord
 
 ### `useCivitaiNavigate()`
 
-Request a navigation within civitai.com (host-mediated; fire-and-forget).
+Request a navigation from the host. The hook sends a `NAVIGATE` message and
+returns — fire-and-forget, so the block never learns what the host did,
+including when the host **refuses** the request.
+
+`scope` selects the **space** `path` is resolved in, and it **defaults to
+`'app'`**:
+
+| `scope` | `path` resolves | The viewer |
+|---|---|---|
+| `'app'` *(default)* | under **this app's own route**, as a sub-path of it | stays in your app; the page stays mounted |
+| `'site'` | at the **civitai.com root** | leaves your app for a site page |
+
+> 🔴 **A leading slash carries no meaning.** The host normalises it away in
+> **both** scopes, so `'/settings'` and `'settings'` are one request within
+> whichever scope you chose. That means `navigate('/models/12345')` asks for
+> **your app's** `/models/12345` — *not* civitai's model page. To reach the
+> civitai.com page, say so: `navigate('models/12345', { scope: 'site' })`.
+>
+> Both spellings were app-scoped before `scope` existed, so no call you have
+> already written changed meaning — that is the point of the default.
+
+`'site'` is granted **per-surface**: the public run page and the dev tunnel allow
+it, and a private run or a moderator's review preview refuse it. A refusal is
+silent, so do not build a flow that needs to know it happened.
+
+`target` is a REQUEST, not a guarantee. How the host acts on `'current'` vs
+`'new_tab'` is host-side behaviour and the host is the authority on it; this
+package sends the message and makes no promise about the outcome.
+
+> 🔴 **Nothing in your manifest enables `'new_tab'`.** In particular, do **not**
+> declare `allow-popups-to-escape-sandbox`: the host intersects a manifest's
+> `iframe.sandbox` with a fixed allowlist that does not contain that token, so it
+> is dropped for every block at every trust tier and declaring it has no effect.
+> Earlier versions of this page said `'new_tab'` required it — that was wrong.
 
 ```tsx
 const { navigate } = useCivitaiNavigate();
-navigate('/models/12345', 'new_tab');   // 'new_tab' needs allow-popups* in the manifest sandbox
+
+// Your app's own pages — the default.
+navigate('settings');                    // this app's /settings
+navigate('/settings');                   // identical; the slash means nothing
+
+// A civitai.com page — needs an explicit scope.
+navigate('models/12345', { scope: 'site' });
+navigate('models/12345', { scope: 'site', target: 'new_tab' });
+
+// The pre-`scope` two-argument shape still works, and is still app-scoped.
+navigate('detail/7', 'new_tab');
 ```
 
+An app-scoped `navigate()` is **half** of a round trip. The host owns the
+history, so the way your block learns where it ended up is
+[`useCivitaiRoute()`](#usecivitairoute) — read that next if you are routing.
+
+### `useCivitaiRoute()`
+
+The sub-path below your app's root that is **currently showing**. This is the
+other half of an app-scoped [`useCivitaiNavigate()`](#usecivitainavigate): you
+ask the host to move, the host pushes it shallowly so your frame stays mounted,
+and this is how you find out where you went.
+
+```tsx
+function Router() {
+  const subPath = useCivitaiRoute(); // '' on your app's index
+  const [view, id] = subPath.split('/');
+  return view === 'compare' ? <Compare id={id} /> : <Index />;
+}
+```
+
+It also reports the moves you **did not** ask for: the viewer's own
+back/forward, and a deep link the host resolved after init.
+
+Two things set the value — `BLOCK_INIT`'s `context.subPath` at mount, and the
+host's `ROUTE_CHANGED` push on every later change. **The first value is never a
+message**, which is why this is a value hook rather than an `onRouteChanged`
+callback: a callback alone cannot see where the block started, and a change that
+lands before its subscription effect runs is lost. It is the same value as
+`useBlockContext().context.subPath` on a page slot — reach for this when the
+route is all you need, and because its return type is a plain `string` instead of
+a field on a union you have to narrow.
+
+> 🔴 **No leading slash.** The host sends the segment below your app root, so
+> `subPath === 'compare/42'` is the comparison that works and
+> `subPath === '/compare/42'` is the one that silently never matches.
+
+> 🔴 **`''` is a real route — your app's index — and it is also the pre-init
+> value.** The two are indistinguishable from this hook alone, exactly as
+> `'light'` is both a real theme and [`useBlockTheme()`](#useblocktheme)'s
+> pre-init value. Gate on `useBlockContext().ready` if your first paint must tell
+> them apart.
+
+> 🔴 **Read it on every render.** A block that copies the value into state once
+> at mount, or routes imperatively in a mount-only effect, stays on the route it
+> started with — the URL moves and nothing renders, which is the exact symptom
+> this message exists to end.
+
+**Page slot only.** A model-page slot has no route of its own, so this returns
+`''` there and never moves. Against a host that predates `ROUTE_CHANGED` the
+value simply stays at the init sub-path (the old behaviour); nothing awaits the
+message, so there is no hang either way.
+
+Exercise it locally with `pnpm dev:live`, where `navigate()` drives the real
+message end-to-end. `createMockHost` has **no** route control, deliberately: it
+does not handle `NAVIGATE` at all and has no URL to move, so a synthetic setter
+there would be a second, weaker way to produce a message the live host already
+produces from the call a block actually makes.
+
 ### `useBlockAnalytics()`
 
 Fire-and-forget event tracking into the host's analytics pipeline.
@@ -1045,8 +1210,97 @@ const { requestSignIn } = useRequestSignIn();
 requestSignIn();
 ```
 
+### Automatic consent prompt-and-retry (on by default)
+
+**You usually do not need to write any of this.** Since `1.0.0` the
+consent-gated calls below handle a missing scope themselves: the call fails, the
+SDK opens the host's consent dialog naming the scope the call needs, waits for
+the grant, and then **retries the original call once** so it resolves as if it
+had just worked.
+
+| Hook | Call | Scope it prompts for |
+|---|---|---|
+| `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
+| `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
+| `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
+| `useTip()` | `tip()` | `social:tip:self` |
+
+🔴 **`estimate()` is deliberately NOT in that table.** It is a price READ, and
+blocks call it from an effect keyed on the generation form — on mount, and again
+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.
+
+```tsx
+// This is the whole thing. No try/catch around a consent prompt, no watching
+// useBlockToken().scopes, no manual retry.
+const { submit } = useBuzzWorkflow();
+const snapshot = await submit(body);
+```
+
+🔴 **The retry re-sends the FIRST attempt's `idempotencyKey`.** That is what
+makes it safe on the money paths: `submit()`, `purchase()` and `tip()` mint the
+key once, before the first attempt, so however many attempts one call makes the
+server sees **one** logical operation and charges once. A retry with a fresh key
+would be a second reservation against the viewer's Buzz.
+
+It **never** retries when:
+
+- the token already holds every scope the call needs (so the failure was not
+  about consent — a rate limit, a 5xx, a bad body all behave exactly as before);
+- the call failed **before `BLOCK_INIT`** landed. There is no real token yet, so
+  "the token is missing this scope" is not a fact about consent;
+- the host has pushed `CONSENT_UNAVAILABLE` **naming a scope this call needs** —
+  that scope can never be granted here, so a retry is a guaranteed second
+  failure. A refusal that names *other* scopes leaves this call alone, and one
+  that names **none** (the payload's `scopes` is documented as advisory and may
+  be empty) is treated as covering everything, which is the safe reading;
+- the viewer dismissed a host confirm (`declined`), or there is no session to
+  grant anything to (`signInRequired` — route that into `useRequestSignIn()`);
+- the component **unmounted** — including *during* the 60 s wait, so a grant that
+  arrives after your component is gone does not spend anything;
+- the request timed out on a bridge with **no idempotency key** (`createPost()`,
+  collection follow) — the retry would be a genuine second write, i.e. a second
+  public post. A timeout on a call that HAS a key — `submit()`, `purchase()`,
+  `tip()` — *is* retried, because the retry re-sends that key and the server
+  collapses the two into one operation;
+- **a second time.** One retry, never a loop. A second consent failure surfaces
+  to you unchanged.
+
+If the viewer never answers the dialog, the **original** error is re-thrown after
+60 s and your `catch` sees exactly what it would have seen before.
+
+⚠️ **One failure is deliberately NOT excluded:** a host refusal about the
+*payload* rather than the token — `createPost()`'s `'no images to post'` — still
+prompts, because nothing distinguishes it structurally from a genuine consent
+failure without string-matching server copy. The cost is one needless dialog; the
+retry re-opens the host's own confirm and cannot publish anything new.
+
+**Concurrent callers share one dialog.** `N` calls that are in flight together and
+need the same scope post **one** `REQUEST_CONSENT` and wait on it together — a
+feed of tip buttons does not open a dialog per button. Each call still retries its
+**own** request with its **own** idempotency key, so *N* tips remain *N* transfers.
+⚠️ This is de-duplication of *concurrent* waits only: calls made one after another
+each get their own prompt, which is the shape that keeps `estimate()` out of the
+table above.
+
+Opt out per call — the same single option on every hook above:
+
+```tsx
+await submit(body, { autoRequestConsent: false });   // pre-1.0 behaviour
+```
+
+⚠️ **Not covered:** a scope your **manifest** never declared can never be granted
+either, and a block cannot see its own manifest at runtime — so that case is
+caught one round-trip late, by the host's `CONSENT_UNAVAILABLE`, rather than
+before the first attempt. Declare the scopes your app uses.
+
 ### `useRequestConsent()`
 
+The manual version of the above — still exported, still the right tool when you
+want to prompt *before* a call (e.g. on an onboarding screen) rather than after
+one fails.
+
 Lazy consent: ask the host to open its consent UI when a LOGGED-IN viewer takes
 an action whose consent-gated scope the block token is missing (e.g. Generate
 needs `ai:write:budgeted` but the viewer hasn't granted it). Fire-and-forget —

package/dist/hooks/consentRetryOptions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared, PUBLIC options for the SDK's automatic consent prompt-and-retry.
+ *
+ * Declared here rather than beside the mechanics in
+ * `internal/withConsentRetry.ts` for one structural reason: `src/index.ts` may
+ * not reach a module under `internal/` (#378, enforced by
+ * `tests/guards/blocks-react-entry-directory-names.test.mjs`, which follows
+ * re-export edges transitively). A caller has to be able to SPELL this type in
+ * its own signatures, so the type is public and the mechanics stay private.
+ *
+ * Every consent-gated call reaches this field through the ONE declaration here
+ * — `SubmitWorkflowOptions`, `GoodPurchaseOptions` and `TipOptions` EXTEND it
+ * (they have money fields of their own); `createPost()` takes it directly. A
+ * predicate — or an option name — open-coded at N sites is typically wrong at
+ * N-1 of them.
+ *
+ * 🔴 ONE FIELD, DELIBERATELY. A second, `consentTimeoutMs`, was cut in #500
+ * round 1: it had no consumer outside this package and its only demonstrated
+ * use was shortening the 60s wait inside a TEST. A test seam does not belong on
+ * five public signatures — the test now uses fake timers instead, and the wait
+ * bound is the non-public `CONSENT_GRANT_WAIT_MS`. Adding a knob here commits
+ * the package to it forever; do not add one without a caller that needs it.
+ */
+export interface ConsentRetryOptions {
+    /**
+     * Whether a consent-gated failure should automatically open the host's
+     * consent dialog and, on grant, retry the call ONCE.
+     *
+     * **Defaults to `true`** — the good behaviour is the default one. Set `false`
+     * to get the pre-1.0 behaviour: the original error is re-thrown unchanged
+     * and nothing is prompted.
+     *
+     * 🔴 THE RETRY REUSES THE FIRST ATTEMPT'S IDEMPOTENCY KEY on every money path
+     * that has one (`submit`, `purchase`, `tip`). That is what makes it safe: a
+     * retry with a FRESH key is a SECOND reservation against the viewer's Buzz.
+     * See `internal/withConsentRetry.ts`.
+     */
+    autoRequestConsent?: boolean;
+}
+//# sourceMappingURL=consentRetryOptions.d.ts.map

package/dist/hooks/consentRetryOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=consentRetryOptions.js.map

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,4 +1,5 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -393,7 +394,7 @@ export declare class WorkflowSubmitError extends Error {
     constructor(snapshot: BlockWorkflowSnapshot, code: WorkflowSubmitErrorCode);
 }
 /** Optional per-submit controls. */
-export interface SubmitWorkflowOptions {
+export interface SubmitWorkflowOptions extends ConsentRetryOptions {
     /**
      * A STABLE idempotency key for this logical submit. Reuse the SAME value when
      * RETRYING a submit whose response was lost (timeout / network drop) so the
@@ -405,6 +406,11 @@ export interface SubmitWorkflowOptions {
      * SAFE. That code means a workflow probably exists and its spend may already
      * be committed server-side; retrying WITHOUT reusing the key mints a fresh one
      * and therefore a SECOND reservation. See {@link WorkflowSubmitError.code}.
+     *
+     * The SDK's own automatic consent retry obeys this: whichever value ends up
+     * here — yours, or the one `submit()` mints — is the value BOTH of its
+     * attempts carry. So an error you receive may already be a second attempt's;
+     * if you then retry a third time by hand, reuse this key for that too.
      */
     idempotencyKey?: string;
 }
@@ -430,6 +436,13 @@ export interface UseBuzzWorkflow {
      * `result` is updated to the returned snapshot BEFORE any rejection, so a
      * failed estimate can never leave a previous, differently-configured
      * estimate's price sitting in `result` for a Confirm gate to read.
+     *
+     * 🔴 NO AUTOMATIC CONSENT PROMPT HERE, unlike {@link UseBuzzWorkflow.submit}.
+     * Blocks call `estimate()` from an effect keyed on the generation form, so it
+     * fires on mount and on every parameter change — prompting there would open a
+     * consent dialog with no user gesture behind it, once per edit. A missing
+     * scope surfaces as an ordinary rejection; show no price and let `submit()`
+     * do the asking.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -468,6 +481,15 @@ export interface UseBuzzWorkflow {
      *
      * `result` is updated to the returned snapshot BEFORE any rejection, so a
      * failed submit can never leave a previous submit's workflow in `result`.
+     *
+     * 🔴 CONSENT IS HANDLED FOR YOU. When the token lacks `ai:write:budgeted`,
+     * this opens the host's consent dialog, waits for the grant, and re-sends the
+     * submit ONCE — with the SAME {@link SubmitWorkflowOptions.idempotencyKey}, so
+     * the two attempts are one reservation, not two. Nothing else changes: a
+     * failure while the token DOES hold the scope is untouched, a
+     * `CONSENT_UNAVAILABLE` environment is never retried, and a second consent
+     * failure reaches you unchanged. Opt out with
+     * {@link ConsentRetryOptions.autoRequestConsent}`: false`.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,21 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
 import { generateIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope {@link UseBuzzWorkflow.submit} requires.
+ *
+ * 🔴 `submit()` ONLY. `estimate()` needs the same scope but is deliberately not
+ * routed through the automatic consent retry — see the comment on `estimate`
+ * below; it is an on-mount read with no gesture behind it.
+ *
+ * Named from {@link BLOCK_SCOPES}, never a string literal: this array is sent to
+ * the host as the `REQUEST_CONSENT` hint, and the host ignores a hint with no
+ * RECOGNISED non-empty name — so a typo here would not error, it would make the
+ * automatic prompt silently do nothing.
+ */
+const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -556,6 +571,50 @@ export function useBuzzWorkflow() {
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
     const [error, setError] = useState(null);
+    /**
+     * Whether this hook's component is still mounted.
+     *
+     * 🔴 ITS ONLY JOB IS THE CONSENT RETRY, and that is a MONEY gate rather than a
+     * setState-after-unmount tidy-up. `submit()` can sit in `withConsentRetry`'s
+     * 60s grant wait long after the component is gone, and nothing else can see
+     * that: this hook's calls go through the postMessage bridge, so there is no
+     * `AbortController` to fire and rule 3's `AbortError` path never triggers. A
+     * grant arriving after unmount would then RESERVE BUZZ for a generation nobody
+     * is left to watch. Read immediately before the retry, never cached.
+     */
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    /**
+     * 🔴 `estimate()` IS DELIBERATELY NOT ROUTED THROUGH `withConsentRetry`, and
+     * that exclusion is load-bearing rather than an oversight.
+     *
+     * The automatic prompt is for calls a PERSON just made. `estimate()` is not
+     * one: `starters/examples/buzz-workflow/src/App.tsx` calls it from a
+     * `useEffect` keyed on the form inputs, so it fires on mount and again on
+     * every parameter edit. Routing it would open a consent dialog with no gesture
+     * behind it and hold each call pending for the full 60s grant wait. That is the
+     * same reason the Buzz READS are excluded; `estimate()` just happens to live on
+     * a hook whose OTHER call moves money.
+     *
+     * ⚠️ The in-flight DE-DUPLICATION `withConsentRetry` gained in #500 round 2
+     * does not change this verdict, and reading it as a reason to route
+     * `estimate()` would be a mistake. It collapses CONCURRENT waits on the same
+     * scope set into one dialog; a form edited over several seconds produces
+     * SEQUENTIAL calls, each after the previous wait settled, so the N-dialogs
+     * problem survives for exactly this shape. The no-gesture objection is
+     * independent of it either way.
+     *
+     * A failed estimate keeps the behaviour that starter's own `catch` is written
+     * against: reject with the server's reason, and show no price, because a
+     * missing quote is not viewer-actionable copy. `submit()` IS routed, and that
+     * is where both the gesture and the charge are. Pinned by
+     * `test/withConsentRetry.test.tsx`.
+     */
     const estimate = useCallback(async (body) => {
         setError(null);
         setStatus('estimating');
@@ -606,62 +665,84 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
+    /**
+     * ONE submit round-trip AND its result contract.
+     *
+     * 🔴 `idempotencyKey` IS A PARAMETER, NOT MINTED HERE, AND THAT IS THE MONEY
+     * SAFETY PROPERTY OF THIS WHOLE FILE. `submit` mints it ONCE, above the
+     * consent retry, and passes the same value into both invocations of this
+     * function. Minting it here instead would give the automatic retry a FRESH
+     * key — a SECOND Buzz reservation for one logical submit, which is exactly
+     * what {@link SubmitWorkflowOptions.idempotencyKey}'s docs forbid.
+     */
+    const submitOnce = useCallback(async (body, idempotencyKey) => {
+        const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+        // 🔴 PUBLISH THE SNAPSHOT BEFORE THE REJECTION BELOW, for the same reason
+        // `estimate` does: a block may render from `result` rather than from the
+        // returned value, and jumping over this line would leave the PREVIOUS
+        // submit's snapshot in place — a live control pointing at a workflow THIS
+        // submit did not queue.
+        setResult(snapshot);
+        // 🔴 AN ERRORED SUBMIT MUST REJECT (civitai/civitai-app-starters#251, the
+        // `submit` half of civitai/civitai#4159). Two producers report
+        // `status:'failed'` and `status` separates neither:
+        //
+        //   - a budget / spend-cap REJECTION is an OUTCOME the block recovers from
+        //     (open a top-up flow). The server quotes the price it refused to
+        //     charge, so `cost.total` is present. It RESOLVES — turning this arm
+        //     into a throw is the one change that would break the recovery path.
+        //   - a failure-shaped reply with NO `cost` is not a usable outcome. It
+        //     REJECTS — and the `code` says which kind, because they differ on
+        //     whether money moved (see WorkflowSubmitError.code).
+        //
+        // BOTH clauses are load-bearing. Dropping `status === 'failed'` would
+        // reject every ordinary in-flight reply (`{status:'pending'}` is cost-less
+        // too); dropping the cost test would reject the budget rejection. And the
+        // test is `typeof … !== 'number'`, never `!snapshot.cost?.total`: `0` is a
+        // real price and falsy.
+        //
+        // 🔴 `status === 'failed'`, NOT `TERMINAL_STATUSES.has(status)`. Widening it
+        // would reject cost-less `succeeded`/`canceled`/`expired` replies, which are
+        // legitimate outcomes the server really does emit without a price
+        // (`snapshotFromWorkflow` omits `cost` on any non-numeric total). That
+        // WIDENING is invisible to a mutation sweep that only deletes clauses, so
+        // all three statuses are pinned by their own fixtures in the test file.
+        if (snapshot.status === 'failed' && typeof snapshot.cost?.total !== 'number') {
+            // 🔴 WHICH ARM: the host stamps its own synthesised failures with the
+            // `'failed'` sentinel, while a server-built reply carries `workflow.id`
+            // (or the `'whatif'` sentinel).
+            // Anything unrecognised falls to `'workflow-failed'`, the arm that assumes
+            // money MAY be committed — an unknown id must never buy the reassuring
+            // "nothing was charged" reading.
+            throw new WorkflowSubmitError(snapshot, snapshot.workflowId === HOST_SYNTHESISED_WORKFLOW_ID ? 'exception' : 'workflow-failed');
+        }
+        setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
+        return snapshot;
+    }, []);
     const submit = useCallback(async (body, options) => {
         setError(null);
         setStatus('submitting');
         // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz
         // charge), or mint a fresh one per call (each call is a new logical submit).
+        //
+        // 🔴 MINTED HERE, OUTSIDE THE CLOSURE `withConsentRetry` RE-INVOKES. Both
+        // attempts therefore carry the SAME key and the host+orchestrator collapse
+        // them to ONE reservation. Move this line inside `submitOnce` and an
+        // automatic retry double-reserves a real person's Buzz — the single
+        // regression this feature exists to not have.
         const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
         try {
-            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
-            // 🔴 PUBLISH THE SNAPSHOT BEFORE THE REJECTION BELOW, for the same reason
-            // `estimate` does: a block may render from `result` rather than from the
-            // returned value, and jumping over this line would leave the PREVIOUS
-            // submit's snapshot in place — a live control pointing at a workflow THIS
-            // submit did not queue.
-            setResult(snapshot);
-            // 🔴 AN ERRORED SUBMIT MUST REJECT (civitai/civitai-app-starters#251, the
-            // `submit` half of civitai/civitai#4159). Two producers report
-            // `status:'failed'` and `status` separates neither:
-            //
-            //   - a budget / spend-cap REJECTION is an OUTCOME the block recovers from
-            //     (open a top-up flow). The server quotes the price it refused to
-            //     charge, so `cost.total` is present. It RESOLVES — turning this arm
-            //     into a throw is the one change that would break the recovery path.
-            //   - a failure-shaped reply with NO `cost` is not a usable outcome. It
-            //     REJECTS — and the `code` says which kind, because they differ on
-            //     whether money moved (see WorkflowSubmitError.code).
-            //
-            // BOTH clauses are load-bearing. Dropping `status === 'failed'` would
-            // reject every ordinary in-flight reply (`{status:'pending'}` is cost-less
-            // too); dropping the cost test would reject the budget rejection. And the
-            // test is `typeof … !== 'number'`, never `!snapshot.cost?.total`: `0` is a
-            // real price and falsy.
-            //
-            // 🔴 `status === 'failed'`, NOT `TERMINAL_STATUSES.has(status)`. Widening it
-            // would reject cost-less `succeeded`/`canceled`/`expired` replies, which are
-            // legitimate outcomes the server really does emit without a price
-            // (`snapshotFromWorkflow` omits `cost` on any non-numeric total). That
-            // WIDENING is invisible to a mutation sweep that only deletes clauses, so
-            // all three statuses are pinned by their own fixtures in the test file.
-            if (snapshot.status === 'failed' && typeof snapshot.cost?.total !== 'number') {
-                // 🔴 WHICH ARM: the host stamps its own synthesised failures with the
-                // `'failed'` sentinel, while a server-built reply carries `workflow.id`
-                // (or the `'whatif'` sentinel).
-                // Anything unrecognised falls to `'workflow-failed'`, the arm that assumes
-                // money MAY be committed — an unknown id must never buy the reassuring
-                // "nothing was charged" reading.
-                throw new WorkflowSubmitError(snapshot, snapshot.workflowId === HOST_SYNTHESISED_WORKFLOW_ID ? 'exception' : 'workflow-failed');
-            }
-            setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
-            return snapshot;
+            return await withConsentRetry(getTransport(), WORKFLOW_SCOPES, () => submitOnce(body, idempotencyKey), options, 
+            // Rule 3 in the time axis — see `mountedRef` above for why this hook
+            // needs it even though it has no `AbortController`.
+            () => mountedRef.current);
         }
         catch (err) {
             setError(err);
             setStatus('error');
             throw err;
         }
-    }, []);
+    }, [submitOnce]);
     /**
      * ONE poll round-trip, with an optional long-poll hint. The single place that
      * builds a `POLL_WORKFLOW` message, so `poll` and `watch` cannot drift on the