@civitai/blocks-react 0.59.0 → 0.61.0

package/dist/hooks/useCreatePostFromApp.js

@@ -1,7 +1,17 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope this bridge requires — `posts:write:self`, named in
+ * `@civitai/app-sdk`'s own `CREATE_POST_FROM_APP` message docs ("Scope
+ * `posts:write:self` (NOT `ai:write:budgeted`), which is SENSITIVE and
+ * CONSENT-GATED"). From {@link BLOCK_SCOPES}, never a literal: a typo would not
+ * error, it would make the automatic consent prompt silently do nothing.
+ */
+const CREATE_POST_SCOPES = [BLOCK_SCOPES.POSTS_WRITE_SELF];
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
  *
@@ -152,49 +162,92 @@ export function useCreatePostFromApp() {
             mountedRef.current = false;
         };
     }, []);
-    const createPost = useCallback(async (args) => {
+    /** ONE round-trip + its result contract. Re-invoked verbatim on a consent retry. */
+    const createPostOnce = useCallback(async (args) => {
+        const reply = await sendTypedRequest(getTransport(), {
+            type: 'CREATE_POST_FROM_APP',
+            payload: {
+                sources: args.sources,
+                ...(args.title !== undefined ? { title: args.title } : {}),
+                ...(args.detail !== undefined ? { detail: args.detail } : {}),
+                ...(args.tags !== undefined ? { tags: args.tags } : {}),
+                ...(args.modelVersionId !== undefined
+                    ? { modelVersionId: args.modelVersionId }
+                    : {}),
+            },
+        }, 'CREATE_POST_RESULT', 
+        // See the `'human'` bucketing in `transport/requestTimeouts.ts`: the
+        // host answers only when the viewer clicks or dismisses its confirm.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS }).catch((err) => {
+            // 🔴 THE `timedOut` STAMP LIVES HERE, INSIDE THE CLOSURE
+            // `withConsentRetry` RE-INVOKES — NOT IN `createPost`'s OUTER CATCH.
+            // That placement is the whole point and it is load-bearing: rule 4 of
+            // `internal/withConsentRetry.ts` ("never retry a keyless bridge's
+            // timeout") is read off THIS error, so a stamp applied outside the
+            // wrapper is invisible to it. Until #500 round 2 it was applied outside,
+            // and the consequence was exactly what `CreatePostError.timedOut`'s
+            // docstring exists to prevent: a raw `RequestTimeoutError` reached the
+            // helper carrying neither `declined` nor `timedOut`, so on a token
+            // lacking `posts:write:self` the SDK prompted and RE-SENT THE POST.
+            // `CREATE_POST_FROM_APP` has no `idempotencyKey` on the wire, so that
+            // second send is a genuine second write — a DUPLICATE PUBLIC POST under
+            // the viewer's name.
+            //
+            // Structural, not a message match — see `RequestTimeoutError`.
+            if (err instanceof RequestTimeoutError) {
+                throw new CreatePostError(err.message, { timedOut: true });
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        });
+        if (reply.error || !reply.result) {
+            // 🔴 `||`, NOT `??`. `isValidCreatePostResult` gates `error` on SHAPE
+            // only (it has to: the channel carries free-text server messages), so
+            // a host `error: ''` is a VALID reply that reaches here. `??` would
+            // then throw an Error with an EMPTY message for a public post, which
+            // renders as a blank failure. Fall through to a code that at least
+            // names a real outcome.
+            throw new CreatePostError(reply.error || 'no images to post');
+        }
+        return reply.result;
+    }, []);
+    const createPost = useCallback(async (args, options) => {
         if (mountedRef.current) {
             setPending(true);
             setError(null);
         }
         try {
-            const reply = await sendTypedRequest(getTransport(), {
-                type: 'CREATE_POST_FROM_APP',
-                payload: {
-                    sources: args.sources,
-                    ...(args.title !== undefined ? { title: args.title } : {}),
-                    ...(args.detail !== undefined ? { detail: args.detail } : {}),
-                    ...(args.tags !== undefined ? { tags: args.tags } : {}),
-                    ...(args.modelVersionId !== undefined
-                        ? { modelVersionId: args.modelVersionId }
-                        : {}),
-                },
-            }, 'CREATE_POST_RESULT', 
-            // See the `'human'` bucketing in `transport/requestTimeouts.ts`: the
-            // host answers only when the viewer clicks or dismisses its confirm.
-            { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
-            if (reply.error || !reply.result) {
-                // 🔴 `||`, NOT `??`. `isValidCreatePostResult` gates `error` on SHAPE
-                // only (it has to: the channel carries free-text server messages), so
-                // a host `error: ''` is a VALID reply that reaches here. `??` would
-                // then throw an Error with an EMPTY message for a public post, which
-                // renders as a blank failure. Fall through to a code that at least
-                // names a real outcome.
-                throw new CreatePostError(reply.error || 'no images to post');
-            }
-            return reply.result;
+            // 🔴 INSIDE the try, not around it: the wrapper must sit between the
+            // round-trip and the `setError` below, so a first attempt that is
+            // recovered by a consent grant never leaves a failure in `error` for the
+            // UI to render next to a post that succeeded.
+            //
+            // No idempotency key is involved — `CREATE_POST_FROM_APP` has none on the
+            // wire, which is exactly why a TIMEOUT here must never be retried: there
+            // is nothing for the server to dedupe a second send against, so the retry
+            // would be a second public post. `createPostOnce` stamps `timedOut` on
+            // its own error for that reason, INSIDE this closure where rule 4 can see
+            // it. The remaining duplicate-protection is the host's own per-post
+            // confirm, which a consent retry re-opens exactly once; and a `declined`
+            // (the viewer dismissing that confirm) is never retried at all.
+            return await withConsentRetry(getTransport(), CREATE_POST_SCOPES, () => createPostOnce(args), options, 
+            // Rule 3 in the time axis: a grant that lands after this component is
+            // gone must not publish a post nobody is left to see.
+            () => mountedRef.current);
         }
         catch (err) {
-            // A transport timeout arrives as a plain Error; wrap it so callers have
-            // ONE error type to test, with `.code` left undefined (it is not a host
-            // refusal). Re-wrapping our own error would lose `.code`, so pass it
-            // through.
+            // Wrap anything that is not already ours so callers have ONE error type
+            // to test, with `.code` left undefined (it is not a host refusal).
+            // Re-wrapping our own error would lose `.code` AND `.timedOut`, so pass
+            // it through.
+            //
+            // 🔴 NO `timedOut` STAMP HERE. It used to be applied at this line, which
+            // put it OUTSIDE `withConsentRetry` and made rule 4 unreachable for this
+            // bridge — the round-2 defect. `createPostOnce` owns the stamp now, so
+            // every transport timeout arrives here ALREADY a `CreatePostError` and
+            // takes the pass-through branch above.
             const wrapped = err instanceof CreatePostError
                 ? err
-                : new CreatePostError(err instanceof Error ? err.message : String(err), {
-                    // Structural, not a message match — see `RequestTimeoutError`.
-                    timedOut: err instanceof RequestTimeoutError,
-                });
+                : new CreatePostError(err instanceof Error ? err.message : String(err));
             if (mountedRef.current)
                 setError(wrapped);
             // 🔴 THROWN UNCONDITIONALLY, even when unmounted. The caller's `await`

package/dist/hooks/useGoodPurchase.d.ts

@@ -1,3 +1,4 @@
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 import type { Entitlement } from './useEntitlements.js';
 /** Which good to buy, and optionally the price the app showed the viewer. */
 export interface GoodPurchaseParams {
@@ -12,7 +13,7 @@ export interface GoodPurchaseParams {
     expectedPriceBuzz?: number;
 }
 /** Optional per-purchase controls. */
-export interface GoodPurchaseOptions {
+export interface GoodPurchaseOptions extends ConsentRetryOptions {
     /**
      * A STABLE idempotency key for this logical purchase. Reuse the SAME value
      * when RETRYING a purchase whose response was lost (timeout / network drop)

package/dist/hooks/useGoodPurchase.js

@@ -1,8 +1,22 @@
 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 } from '../transport/transport.js';
 import { useBlockToken } from './useBlockToken.js';
 import { useBuzzPurchase } from './useBuzzPurchase.js';
 import { useHostOrigin } from './useHostOrigin.js';
+/**
+ * The consent-gated scope a purchase needs.
+ *
+ * 🔴 `goods:purchase:self`, NEVER `goods:read:self` — `BLOCK_SCOPES`' own
+ * comment draws the line: the read is consent-EXEMPT (server-scoped to the
+ * calling app's own goods, so there is nothing third-party to consent to) while
+ * money out of the viewer's balance always needs an explicit grant. "Do not
+ * collapse the two." Prompting for the read would ask for the wrong thing and
+ * the wait below would never see it granted.
+ */
+const GOOD_PURCHASE_SCOPES = [BLOCK_SCOPES.GOODS_PURCHASE_SELF];
 /**
  * Backstop timeout for the direct REST purchase POST. Like {@link useTip} (and
  * unlike the postMessage hooks), this talks to the HTTP API directly, so it
@@ -95,10 +109,27 @@ export function useGoodPurchase() {
             timedOut = true;
             controller.abort();
         }, GOOD_PURCHASE_TIMEOUT_MS);
+        // 🔴 THE BEARER IS READ LIVE, NOT OUT OF THE RENDER CLOSURE — WITHOUT THIS
+        // THE AUTOMATIC CONSENT RETRY CANNOT WORK. A consent grant re-mints the
+        // token and pushes `TOKEN_REFRESH`; React then re-renders and `raw` gets a
+        // new value, but the in-flight `purchase` call is still holding the
+        // closure created at call time, whose `raw` is the PRE-grant token. Retry
+        // with that and the server sees the same scope-less token and refuses
+        // again — a retry that could never succeed, for a grant that did.
+        //
+        // ⚠️ `|| raw` CANNOT SUBSTITUTE A DIFFERENT VALUE, and an earlier version
+        // of this comment claimed it covered "the pre-init case" as though it
+        // could. `raw` comes from `useBlockToken()`, which returns
+        // `useTransportSnapshot().token` — the SAME snapshot this line reads, one
+        // render older. The token only ever goes sentinel-empty → real, so
+        // whenever the live read is empty the closure's `raw` is empty too. It is
+        // an equal-valued default, not a second source; the LIVE READ is the part
+        // that does the work.
+        const bearer = getTransport().getSnapshot().token.raw || raw;
         try {
             const res = await fetch(`${host}/api/v1/blocks/goods/purchase`, {
                 method: 'POST',
-                headers: { Authorization: `Bearer ${raw}`, 'Content-Type': 'application/json' },
+                headers: { Authorization: `Bearer ${bearer}`, 'Content-Type': 'application/json' },
                 body: JSON.stringify({
                     goodId: params.goodId,
                     ...(params.expectedPriceBuzz != null
@@ -216,26 +247,40 @@ export function useGoodPurchase() {
             setLoading(true);
             setError(null);
         }
+        // 🔴 MINTED ONCE, OUTSIDE BOTH RETRY MECHANISMS. The top-up retry below
+        // and the consent retry wrapped around it BOTH re-post with this exact
+        // value, so however many attempts a single `purchase()` makes, the server
+        // sees ONE logical purchase. Moving it inside either closure turns an
+        // automatic retry into a second charge.
         const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
         try {
-            try {
-                return await postOnce(params, idempotencyKey);
-            }
-            catch (first) {
-                const canTopUp = options?.topUpOnInsufficientFunds === true &&
-                    first instanceof GoodPurchaseRefusal &&
-                    first.reason === 'insufficient_funds';
-                if (!canTopUp)
-                    throw first;
-                // Only retry if the viewer ACTUALLY bought Buzz. `purchased: false`
-                // is the ordinary "they closed the modal" case, and retrying it would
-                // just reproduce the same refusal — so the original refusal is what
-                // the app should see.
-                const { purchased } = await openPurchaseModal(params.expectedPriceBuzz);
-                if (!purchased)
-                    throw first;
-                return await postOnce(params, idempotencyKey);
-            }
+            return await withConsentRetry(getTransport(), GOOD_PURCHASE_SCOPES, async () => {
+                try {
+                    return await postOnce(params, idempotencyKey);
+                }
+                catch (first) {
+                    const canTopUp = options?.topUpOnInsufficientFunds === true &&
+                        first instanceof GoodPurchaseRefusal &&
+                        first.reason === 'insufficient_funds';
+                    if (!canTopUp)
+                        throw first;
+                    // Only retry if the viewer ACTUALLY bought Buzz. `purchased: false`
+                    // is the ordinary "they closed the modal" case, and retrying it would
+                    // just reproduce the same refusal — so the original refusal is what
+                    // the app should see.
+                    const { purchased } = await openPurchaseModal(params.expectedPriceBuzz);
+                    if (!purchased)
+                        throw first;
+                    return await postOnce(params, idempotencyKey);
+                }
+            }, options, 
+            // 🔴 RULE 3 IN THE TIME AXIS, AND IT IS NOT COVERED BY THE UNMOUNT
+            // ABORT IN `postOnce`. During the 60s consent wait there is no
+            // in-flight request for the cleanup to abort, so no `AbortError` is
+            // produced and the grant drove a SECOND CHARGE against a component
+            // that no longer exists. `withConsentRetry` reads this immediately
+            // before the retry.
+            () => mountedRef.current);
         }
         catch (err) {
             const e = err instanceof Error ? err : new Error(String(err));

package/dist/hooks/useRequestConsent.js

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { armConsentRefusalLatch } from '../internal/consentRefusalLatch.js';
+import { sendRequestConsent } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
 /**
  * Lazy consent. Asks the host to open civitai.com's consent UI when a
@@ -44,17 +44,15 @@ import { getTransport } from '../transport/singleton.js';
  */
 export function useRequestConsent() {
     const requestConsent = useCallback((payload) => {
-        const transport = getTransport();
-        // Arm the refusal buffer BEFORE the request goes out. A `CONSENT_UNAVAILABLE`
-        // can only ever follow a `REQUEST_CONSENT`, and the transport drops an
-        // unsolicited push that has no listener at the instant it arrives — so this
-        // ordering is what lets a refusal survive until a `useConsentUnavailable()`
-        // mounts, instead of requiring one to already be mounted. Idempotent.
-        armConsentRefusalLatch(transport);
-        transport.sendMessage({
-            type: 'REQUEST_CONSENT',
-            ...(payload ? { payload } : {}),
-        });
+        // Single-sourced with the SDK's own automatic prompt-and-retry
+        // (`internal/withConsentRetry.ts`), which posts the identical message. The
+        // helper arms the refusal buffer BEFORE the request goes out: a
+        // `CONSENT_UNAVAILABLE` can only ever follow a `REQUEST_CONSENT`, and the
+        // transport drops an unsolicited push that has no listener at the instant it
+        // arrives — so that ordering is what lets a refusal survive until a
+        // `useConsentUnavailable()` mounts, instead of requiring one to already be
+        // mounted. Two spellings of "arm, then send" is how one of them forgets.
+        sendRequestConsent(getTransport(), payload);
     }, []);
     return { requestConsent };
 }

package/dist/hooks/useResourcePicker.d.ts

@@ -6,10 +6,35 @@ export interface UseResourcePicker {
          * host rejects any other type (the modal never opens). */
         resourceType: BlockResourcePickerType;
         /**
-         * Optional base-model family hint — an ecosystem key (e.g. 'Flux1', 'SDXL')
-         * OR a baseModel name (e.g. 'Flux.1 D'); the host collapses it to the
-         * ecosystem family. Use the chosen checkpoint's `baseModel` to constrain a
-         * LoRA pick to the same family. Omit for an unconstrained pick of the type.
+         * 🔴 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;
     }) => Promise<BlockResourceInfo | null>;
@@ -36,11 +61,35 @@ 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
+ * `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.
+ *
+ * @example
+ * // CONSTRAINED — only when the pick has to match a checkpoint the block
+ * // already holds. Derive the family from THAT checkpoint; a hardcoded
+ * // ecosystem here hides every resource outside it from the viewer. On a page
+ * // block the checkpoint comes from this same picker, not from the context.
+ * const { open } = useResourcePicker();
+ * const checkpoint = await open({ resourceType: 'Checkpoint' });
+ * if (checkpoint) {
+ *   const lora = await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+ *   // feed lora?.versionId into body.additionalResources and submit
+ * }
+ *
  * @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();
- * const picked = await open({ resourceType: 'LORA', baseModelGroup: 'SDXL' });
- * if (!picked) return;                 // user dismissed
- * // feed picked.versionId into body.additionalResources and submit
+ * const picked = await open({ resourceType: 'LORA' });
+ * if (picked) {
+ *   // feed picked.versionId into body.additionalResources and submit
+ * }
  */
 export declare function useResourcePicker(): UseResourcePicker;
 //# sourceMappingURL=useResourcePicker.d.ts.map

package/dist/hooks/useResourcePicker.js

@@ -24,11 +24,35 @@ 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
+ * `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.
+ *
+ * @example
+ * // CONSTRAINED — only when the pick has to match a checkpoint the block
+ * // already holds. Derive the family from THAT checkpoint; a hardcoded
+ * // ecosystem here hides every resource outside it from the viewer. On a page
+ * // block the checkpoint comes from this same picker, not from the context.
+ * const { open } = useResourcePicker();
+ * const checkpoint = await open({ resourceType: 'Checkpoint' });
+ * if (checkpoint) {
+ *   const lora = await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+ *   // feed lora?.versionId into body.additionalResources and submit
+ * }
+ *
  * @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();
- * const picked = await open({ resourceType: 'LORA', baseModelGroup: 'SDXL' });
- * if (!picked) return;                 // user dismissed
- * // feed picked.versionId into body.additionalResources and submit
+ * const picked = await open({ resourceType: 'LORA' });
+ * if (picked) {
+ *   // feed picked.versionId into body.additionalResources and submit
+ * }
  */
 export function useResourcePicker() {
     const open = useCallback(async (opts) => {

package/dist/hooks/useTip.d.ts

@@ -1,3 +1,4 @@
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 /** The tip target + amount. `entityType`/`entityId` are optional context. */
 export interface TipParams {
     toUserId: number;
@@ -6,7 +7,7 @@ export interface TipParams {
     entityId?: number;
 }
 /** Optional per-tip controls. */
-export interface TipOptions {
+export interface TipOptions extends ConsentRetryOptions {
     /**
      * A STABLE idempotency key for this logical tip. Reuse the SAME value when
      * RETRYING a tip whose response was lost (timeout / network drop) so the host

package/dist/hooks/useTip.js

@@ -1,7 +1,12 @@
 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 { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
 import { generateIdempotencyKey } from '../transport/transport.js';
+/** The consent-gated scope a tip needs (`social:tip:self`). */
+const TIP_SCOPES = [BLOCK_SCOPES.SOCIAL_TIP_SELF];
 /**
  * Backstop timeout for the direct REST tip POST. Like {@link useGenerationResources}
  * (and unlike the postMessage hooks), this talks to the HTTP API directly, so it
@@ -44,22 +49,47 @@ export function useTip() {
             controllers.clear();
         };
     }, []);
-    const tip = useCallback(async (params, options) => {
-        if (!host) {
-            throw new Error('useTip: host origin not established yet (wait for BLOCK_INIT).');
-        }
-        if (mountedRef.current) {
-            setLoading(true);
-            setError(null);
-        }
-        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+    /**
+     * ONE tip POST + its result contract. Re-invoked verbatim on a consent retry.
+     *
+     * 🔴 `idempotencyKey` IS A PARAMETER. `tip()` mints it once, above the retry,
+     * and hands the SAME value to both attempts — the property that turns a retry
+     * into a replay instead of a second transfer.
+     */
+    const postTipOnce = useCallback(async (params, idempotencyKey) => {
         const controller = new AbortController();
         inFlight.current.add(controller);
-        const timeoutId = setTimeout(() => controller.abort(), TIP_REQUEST_TIMEOUT_MS);
+        // 🔴 WHICH ABORT FIRED IS NOT RECOVERABLE FROM THE SIGNAL — the bound and
+        // the unmount cleanup both set `aborted` — so record it at the source.
+        // The two need OPPOSITE handling below, exactly as in `useGoodPurchase`:
+        // an unmount is a cancellation nothing may resurrect, while the bound
+        // elapsing is a real failure whose recovery IS the same-key retry.
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, TIP_REQUEST_TIMEOUT_MS);
+        // 🔴 THE BEARER IS READ LIVE, NOT OUT OF THE RENDER CLOSURE — WITHOUT THIS
+        // THE AUTOMATIC CONSENT RETRY CANNOT WORK. A consent grant re-mints the
+        // token and pushes `TOKEN_REFRESH`; React then re-renders and `raw` gets a
+        // new value, but the in-flight `purchase`/`tip` call is still holding the
+        // closure created at call time, whose `raw` is the PRE-grant token. Retry
+        // with that and the server sees the same scope-less token and refuses
+        // again — a retry that could never succeed, for a grant that did.
+        //
+        // ⚠️ `|| raw` CANNOT SUBSTITUTE A DIFFERENT VALUE, and an earlier version
+        // of this comment claimed it covered "the pre-init case" as though it
+        // could. `raw` comes from `useBlockToken()`, which returns
+        // `useTransportSnapshot().token` — the SAME snapshot this line reads, one
+        // render older. The token only ever goes sentinel-empty → real, so
+        // whenever the live read is empty the closure's `raw` is empty too. It is
+        // an equal-valued default, not a second source; the LIVE READ is the part
+        // that does the work.
+        const bearer = getTransport().getSnapshot().token.raw || raw;
         try {
             const res = await fetch(`${host}/api/v1/blocks/tip`, {
                 method: 'POST',
-                headers: { Authorization: `Bearer ${raw}`, 'Content-Type': 'application/json' },
+                headers: { Authorization: `Bearer ${bearer}`, 'Content-Type': 'application/json' },
                 body: JSON.stringify({
                     toUserId: params.toUserId,
                     amount: params.amount,
@@ -76,22 +106,71 @@ export function useTip() {
             return bodyJson;
         }
         catch (err) {
-            const e = controller.signal.aborted && !(err instanceof Error && err.message.startsWith('tip'))
-                ? new Error(`useTip: request aborted (timed out after ${TIP_REQUEST_TIMEOUT_MS}ms or the hook unmounted).`)
-                : err instanceof Error
-                    ? err
-                    : new Error(String(err));
-            if (mountedRef.current)
-                setError(e);
-            throw e;
+            // The `!… startsWith('tip')` half keeps a server refusal that was
+            // ALREADY read from being rewritten by an abort that raced it — the
+            // same precedence `useGoodPurchase` gives a `GoodPurchaseRefusal`.
+            if (controller.signal.aborted &&
+                !(err instanceof Error && err.message.startsWith('tip'))) {
+                if (timedOut) {
+                    // 🔴 THE BOUND FIRED, AND THIS ERROR IS DELIBERATELY RETRYABLE.
+                    // `name` stays `Error` (callers routinely ignore `AbortError` as
+                    // "we navigated away", and a silently-ignored money-path timeout is
+                    // the worst outcome here) and it carries NO `timedOut` flag, so the
+                    // automatic consent retry may re-send it. That is safe for exactly
+                    // one reason: this hook mints an `idempotencyKey` above the retry
+                    // and both POSTs carry it, so the server collapses them to ONE
+                    // transfer. See rule 4 in `internal/withConsentRetry.ts` — the flag
+                    // marks bridges with NO key to dedupe with, and this is not one.
+                    throw new Error(`useTip: request aborted (timed out after ${TIP_REQUEST_TIMEOUT_MS}ms). The transfer may or may not have landed — retry with the SAME idempotencyKey to find out safely.`);
+                }
+                // 🔴 UNMOUNT. `name = 'AbortError'` is what a caller discriminates on
+                // to IGNORE a rejection its component no longer cares about, and it
+                // is also what makes `withConsentRetry` rule 3 re-throw rather than
+                // resurrect work that was cancelled on purpose.
+                const aborted = new Error('useTip: request aborted (the hook unmounted before the response arrived). The transfer may or may not have landed — retry with the SAME idempotencyKey to find out safely.');
+                aborted.name = 'AbortError';
+                throw aborted;
+            }
+            throw err instanceof Error ? err : new Error(String(err));
         }
         finally {
             clearTimeout(timeoutId);
             inFlight.current.delete(controller);
+        }
+    }, [host, raw]);
+    const tip = useCallback(async (params, options) => {
+        if (!host) {
+            throw new Error('useTip: host origin not established yet (wait for BLOCK_INIT).');
+        }
+        if (mountedRef.current) {
+            setLoading(true);
+            setError(null);
+        }
+        // 🔴 MINTED ONCE, OUTSIDE the closure the consent retry re-invokes, so
+        // both POSTs carry the SAME key and the host collapses them to ONE
+        // transfer. Minting it inside would DOUBLE-TIP a real person.
+        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        try {
+            return await withConsentRetry(getTransport(), TIP_SCOPES, () => postTipOnce(params, idempotencyKey), options, 
+            // 🔴 RULE 3 IN THE TIME AXIS, AND IT IS NOT COVERED BY THE UNMOUNT
+            // ABORT ABOVE. During the 60s consent wait there is no in-flight
+            // request for the cleanup to abort, so no `AbortError` is produced and
+            // the grant drove a SECOND POST against a component that no longer
+            // exists — Buzz leaving the viewer's balance with no UI left to report
+            // it, and with `inFlight` already cleared that POST is not even
+            // abortable. `withConsentRetry` reads this immediately before the retry.
+            () => mountedRef.current);
+        }
+        catch (err) {
+            if (mountedRef.current)
+                setError(err);
+            throw err;
+        }
+        finally {
             if (mountedRef.current)
                 setLoading(false);
         }
-    }, [host, raw]);
+    }, [host, postTipOnce]);
     return { tip, loading, error };
 }
 //# sourceMappingURL=useTip.js.map

package/dist/index.d.ts

@@ -77,13 +77,16 @@ export type { UseGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';
 export type { RawGenerationResource, RawGenerationResourcesResponse, } from './api/generationResources.js';
 export { useCivitaiNavigate } from './hooks/useCivitaiNavigate.js';
-export type { UseCivitaiNavigate } from './hooks/useCivitaiNavigate.js';
+export type { UseCivitaiNavigate, UseCivitaiNavigateOptions, } from './hooks/useCivitaiNavigate.js';
+export { useCivitaiRoute } from './hooks/useCivitaiRoute.js';
+export type { UseCivitaiRoute } from './hooks/useCivitaiRoute.js';
 export { useRequestSignIn } from './hooks/useRequestSignIn.js';
 export type { UseRequestSignIn } from './hooks/useRequestSignIn.js';
 export { useRequestConsent } from './hooks/useRequestConsent.js';
 export type { UseRequestConsent } from './hooks/useRequestConsent.js';
 export { useConsentUnavailable } from './hooks/useConsentUnavailable.js';
 export type { UseConsentUnavailable, ConsentUnavailablePayload, } from './hooks/useConsentUnavailable.js';
+export type { ConsentRetryOptions } from './hooks/consentRetryOptions.js';
 export { useBlockAnalytics } from './hooks/useBlockAnalytics.js';
 export type { UseBlockAnalytics } from './hooks/useBlockAnalytics.js';
 export { useDomainMaturity } from './hooks/useDomainMaturity.js';

package/dist/index.js

@@ -53,6 +53,9 @@ export { useImageUpload } from './hooks/useImageUpload.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';
 export { useCivitaiNavigate } from './hooks/useCivitaiNavigate.js';
+// The other half of the `NAVIGATE` round trip: `useCivitaiNavigate` asks the
+// host to move, `useCivitaiRoute` is how the block learns where it now is.
+export { useCivitaiRoute } from './hooks/useCivitaiRoute.js';
 export { useRequestSignIn } from './hooks/useRequestSignIn.js';
 export { useRequestConsent } from './hooks/useRequestConsent.js';
 export { useConsentUnavailable } from './hooks/useConsentUnavailable.js';