@civitai/blocks-react 0.56.0 → 0.57.0

package/README.md

@@ -1313,6 +1313,38 @@ For non-React or advanced use, the transport primitives are exported too:
 `readAllowedOriginsFromEnv`, `getTransport`, and `sendTypedRequest`. Hooks are the
 recommended surface; reach for these only when a hook doesn't fit.
 
+### How `allowedParentOrigins` entries are read
+
+Each entry is canonicalised with the URL parser before it is compared to
+`event.origin`, so these spellings all mean the same thing and all match a host
+frame at `https://civitai.com`:
+
+| Written as | Also matches |
+|---|---|
+| `https://civitai.com/` | trailing slash is ignored |
+| `HTTPS://CIVITAI.COM` | scheme and host are case-insensitive |
+| `https://civitai.com:443`, `http://x:80` | an explicit **default** port is ignored |
+| `https://пример.com` | normalised to the punycode a browser reports |
+
+These stay **significant** — they are different origins, not spellings:
+
+- a **non-default** port: `https://civitai.com:8443` does not match `https://civitai.com`
+- the scheme: `http://` never matches `https://`
+- a trailing-dot host: `https://civitai.com.` is its own origin
+- any host that merely *contains* an allowed one: `https://civitai.com.evil.com`
+  never matches `https://civitai.com`
+
+An entry that is not a bare origin **throws at construction** rather than being
+quietly skipped — no scheme (`civitai.com`), a path/query/fragment
+(`https://civitai.com/embed`), credentials (`https://u:p@civitai.com`), or a
+scheme with no origin of its own (`file://…`). A silently dropped entry is the
+failure this rule exists to prevent: the allowlist would be missing an origin
+you believe is on it.
+
+If `BLOCK_INIT` never lands, the 10s timeout error names the origins that
+actually arrived and were rejected, next to the allowlist it checked them
+against — start there.
+
 ## The `/testing` subexport
 
 `@civitai/blocks-react/testing` is the **host-simulation** entry point: it stands
@@ -1586,8 +1618,8 @@ Runnable, minimal blocks — one per feature, each with its own README:
 
 | `@civitai/blocks-react` | pairs with `@civitai/app-sdk` | adds |
 |---|---|---|
-| `0.50.x` | `^0.40.0` | `useCreatePostFromApp()` (`CREATE_POST_FROM_APP`) + the `posts:write:self` scope. 🔴 Same wide `peerDependencies` floor as the row below, so **npm will not warn you**: pairing this with an SDK below `0.40.0` fails at `tsc` with `Cannot find name 'BlockCreatePostHostError'`, not at install. |
-| `0.48.x` | `^0.38.0` | `useCollectionFollow()` + `<FollowButton>` / `<TipButton>` (`SET_COLLECTION_FOLLOW`). 🔴 The `peerDependencies` floor stays the deliberately-wide `>=0.29.0 <1.0.0` (#206 — a per-minor floor forced a major on consumers), so **npm will not warn you**: pairing this with an SDK below `0.38.0` fails at `tsc` with `Cannot find name 'BlockCollectionFollowErrorCode'`, not at install. |
+| `0.50.x` | `^0.40.0` | `useCreatePostFromApp()` (`CREATE_POST_FROM_APP`) + the `posts:write:self` scope. Pairing `0.50.x` with an SDK below `0.40.0` fails at `tsc` with `Cannot find name 'BlockCreatePostHostError'`, not at install. |
+| `0.48.x` | `^0.38.0` | `useCollectionFollow()` + `<FollowButton>` / `<TipButton>` (`SET_COLLECTION_FOLLOW`). Pairing `0.48.x` with an SDK below `0.38.0` fails at `tsc` with `Cannot find name 'BlockCollectionFollowErrorCode'`, not at install — the floor those releases declared was deliberately wide (#206 — a per-minor floor forced a major on consumers). |
 | `0.36.x` | `^0.27.0` | auto-installs the SDK's opaque-origin web-storage shim (`@civitai/app-sdk/safe-storage`) on import |
 | `0.29.x` | `^0.24.0` | `useAppWorkflows()` — app generator subqueue read + cancel (`QUERY_APP_WORKFLOWS` / `CANCEL_APP_WORKFLOW`) |
 | `0.27.x`–`0.28.x` | `^0.23.0` | async-scan image upload; transport validators for all `SHARED_*` / `APP_STORAGE_*` / picker replies |

package/dist/api/generationResources.d.ts

@@ -30,7 +30,8 @@ export declare const MAX_GENERATION_RESOURCE_IDS = 30;
  * Pure + deterministic. `base` defaults to {@link GENERATION_RESOURCES_API_BASE}.
  */
 export declare function buildGenerationResourcesUrl(versionIds: number[], base?: string): string;
-interface RawGenerationResource {
+/** One row of the rehydrate response. See the note above: wire shape, not a contract. */
+export interface RawGenerationResource {
     versionId?: number;
     modelId?: number;
     modelName?: string;
@@ -43,7 +44,8 @@ interface RawGenerationResource {
     trainedWords?: string[];
     clipSkip?: number | null;
 }
-interface RawGenerationResourcesResponse {
+/** The rehydrate response body — the parameter {@link responseToResources} takes. */
+export interface RawGenerationResourcesResponse {
     items?: RawGenerationResource[];
     maturity?: {
         browsingLevel?: number;
@@ -58,5 +60,4 @@ interface RawGenerationResourcesResponse {
  * `projectSafeGenerationResource`. Never throws.
  */
 export declare function responseToResources(raw: RawGenerationResourcesResponse | null | undefined): BlockResourceInfo[];
-export {};
 //# sourceMappingURL=generationResources.d.ts.map

package/dist/hooks/returnTypeLedger.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=returnTypeLedger.d.ts.map

package/dist/hooks/returnTypeLedger.js

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

package/dist/hooks/useAppStorage.js

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply, throwOnReplyError } from '../internal/replyError.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { sendTypedRequest } from '../transport/transport.js';
 /**
  * Per-(block instance, viewer) KV datastore. Calls flow through the host's
  * postMessage bridge — the block never sees the apps DB credentials.

package/dist/hooks/useAppWorkflows.d.ts

@@ -43,8 +43,11 @@ export interface UseAppWorkflows {
  *
  * Fetches on mount and whenever `params` change (by value), and exposes `refetch`.
  * A host that never answers surfaces as an `error` after the transport's request
- * timeout — the hook never hangs. Late responses that arrive after unmount are
- * ignored.
+ * timeout — the hook never hangs. Only the LATEST list request may write state:
+ * a reply superseded by a newer `refetch` / params change — or one that lands
+ * after unmount — is dropped (#392). `cancel` is caller-driven and keeps its own
+ * mount guard: its functional `setWorkflows` splice is order-independent, so it
+ * is not a sequencing hazard.
  *
  * @example
  * const { workflows, cursor, loading, error, cancel } = useAppWorkflows({ limit: 20 });

package/dist/hooks/useAppWorkflows.js

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
 /**
  * Read (and cancel within) the calling app's OWN generator SUBQUEUE — the
  * tag-scoped list of generations THIS app produced for the viewer, newest-first —
@@ -12,8 +13,11 @@ import { sendTypedRequest } from '../internal/transport.js';
  *
  * Fetches on mount and whenever `params` change (by value), and exposes `refetch`.
  * A host that never answers surfaces as an `error` after the transport's request
- * timeout — the hook never hangs. Late responses that arrive after unmount are
- * ignored.
+ * timeout — the hook never hangs. Only the LATEST list request may write state:
+ * a reply superseded by a newer `refetch` / params change — or one that lands
+ * after unmount — is dropped (#392). `cancel` is caller-driven and keeps its own
+ * mount guard: its functional `setWorkflows` splice is order-independent, so it
+ * is not a sequencing hazard.
  *
  * @example
  * const { workflows, cursor, loading, error, cancel } = useAppWorkflows({ limit: 20 });
@@ -24,6 +28,9 @@ export function useAppWorkflows(params) {
     const [cursor, setCursor] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
+    // `cancel` is caller-driven, not auto-issued, and its state write is a
+    // functional splice that is safe in any order — so it keeps a plain mount
+    // guard rather than joining the list request's sequence.
     const mountedRef = useRef(true);
     useEffect(() => {
         mountedRef.current = true;
@@ -31,18 +38,22 @@ export function useAppWorkflows(params) {
             mountedRef.current = false;
         };
     }, []);
+    // Latest-wins + unmount guard for the LIST request (#392): a reply may write
+    // state only if it answers the request this hook is CURRENTLY waiting for.
+    const seq = useRequestSequencer();
     // Serialize the params to a stable key so `refetch`'s identity only changes
     // when the params VALUE changes (not on every render's fresh object). The
     // callback re-parses the key so it closes over NOTHING but the key.
     const paramsKey = params ? JSON.stringify(params) : '';
     const refetch = useCallback(() => {
+        const token = seq.begin();
         setLoading(true);
         setError(null);
         const parsed = paramsKey ? JSON.parse(paramsKey) : undefined;
         const payload = parsed ? { params: parsed } : {};
         sendTypedRequest(getTransport(), { type: 'QUERY_APP_WORKFLOWS', payload }, 'APP_WORKFLOWS_RESULT')
             .then((result) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             if (result.error || !result.result) {
                 // `||`, not `??`: the reply validator gates `error` on SHAPE only, so a
@@ -57,12 +68,12 @@ export function useAppWorkflows(params) {
             setLoading(false);
         })
             .catch((err) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             setError(err instanceof Error ? err : new Error(String(err)));
             setLoading(false);
         });
-    }, [paramsKey]);
+    }, [paramsKey, seq]);
     useEffect(() => {
         refetch();
     }, [refetch]);

package/dist/hooks/useBlockAnalytics.d.ts

@@ -1,3 +1,7 @@
+/** What {@link useBlockAnalytics} returns. */
+export interface UseBlockAnalytics {
+    track: (eventName: string, properties?: Record<string, unknown>) => void;
+}
 /**
  * Fire-and-forget analytics tracking. The host forwards events to its
  * analytics pipeline (ClickHouse in production); the block doesn't see
@@ -7,7 +11,5 @@
  * const { track } = useBlockAnalytics();
  * track('generate_clicked', { modelId });
  */
-export declare function useBlockAnalytics(): {
-    track: (eventName: string, properties?: Record<string, unknown>) => void;
-};
+export declare function useBlockAnalytics(): UseBlockAnalytics;
 //# sourceMappingURL=useBlockAnalytics.d.ts.map

package/dist/hooks/useBlockAnalytics.js

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Fire-and-forget analytics tracking. The host forwards events to its
  * analytics pipeline (ClickHouse in production); the block doesn't see

package/dist/hooks/useBlockBreakpoint.d.ts

@@ -23,6 +23,12 @@ export type BlockSizeTier = 'base' | BreakpointKey;
  * `display: none` ancestor) resolves to `'base'` — the most conservative tier.
  */
 export declare function resolveBlockTier(width: number): BlockSizeTier;
+/**
+ * What {@link useBlockBreakpoint} returns. An alias for the long-standing
+ * {@link BlockBreakpoint} name, which stays exported and unchanged — see
+ * `./returnTypeLedger.js`.
+ */
+export type UseBlockBreakpoint = BlockBreakpoint;
 export interface BlockBreakpoint {
     /**
      * The current tier. `'base'` while unmeasured — see `measured`.
@@ -88,5 +94,5 @@ export interface BlockBreakpoint {
  *   </div>
  * );
  */
-export declare function useBlockBreakpoint(ref?: RefObject<HTMLElement | null>): BlockBreakpoint;
+export declare function useBlockBreakpoint(ref?: RefObject<HTMLElement | null>): UseBlockBreakpoint;
 //# sourceMappingURL=useBlockBreakpoint.d.ts.map

package/dist/hooks/useBlockContext.d.ts

@@ -1,9 +1,20 @@
-import type { BlockSnapshot } from '../internal/transport.js';
+import type { BlockSnapshot } from '../transport/transport.js';
 /**
  * Subscribe a hook to the singleton transport. All hooks build on this —
  * `useSyncExternalStore` gives concurrent-mode safety and minimal re-renders.
  */
 declare function useTransportSnapshot(): BlockSnapshot;
+/**
+ * What {@link useBlockContext} returns — the projection of {@link BlockSnapshot}
+ * the hook exposes.
+ *
+ * 🔴 DERIVED FROM `BlockSnapshot`, NOT RETYPED. A hand-written copy of these ten
+ * fields would drift silently the first time the snapshot's shape moved; the
+ * `Pick` re-resolves against the transport's own type on every build. Before
+ * #380 this expression was written inline on the hook's return annotation, so
+ * a consumer wrapping `useBlockContext()` had nothing to name.
+ */
+export type UseBlockContext = Pick<BlockSnapshot, 'ready' | 'renderMode' | 'context' | 'token' | 'settings' | 'viewer' | 'theme' | 'blockId' | 'blockInstanceId' | 'appId'>;
 /**
  * Primary hook for a block app. Returns the full per-instance context
  * delivered by the host plus a `ready` gate the UI should respect — fields
@@ -34,7 +45,7 @@ declare function useTransportSnapshot(): BlockSnapshot;
  * // scheduled for removal. This snippet used to do exactly that.
  * return <div data-theme={theme}>{isSignedIn(viewer) ? 'Hi there' : 'Hi anon'}</div>;
  */
-export declare function useBlockContext(): Pick<BlockSnapshot, 'ready' | 'renderMode' | 'context' | 'token' | 'settings' | 'viewer' | 'theme' | 'blockId' | 'blockInstanceId' | 'appId'>;
+export declare function useBlockContext(): UseBlockContext;
 /** Re-exported so other hooks in this package can share the subscription. */
 export { useTransportSnapshot };
 //# sourceMappingURL=useBlockContext.d.ts.map

package/dist/hooks/useBlockContext.js

@@ -1,5 +1,5 @@
 import { useSyncExternalStore } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Subscribe a hook to the singleton transport. All hooks build on this —
  * `useSyncExternalStore` gives concurrent-mode safety and minimal re-renders.

package/dist/hooks/useBlockResize.d.ts

@@ -1,4 +1,10 @@
 import { type RefObject } from 'react';
+/**
+ * What {@link useBlockResize} returns: nothing. It is named anyway so the
+ * convention has NO exceptions to remember — see `./returnTypeLedger.js`. A wrapper
+ * that forwards this hook's result can still annotate it.
+ */
+export type UseBlockResize = void;
 /**
  * Observes the referenced element's height and asks the host to resize on
  * every change. Attach to the block's root DOM element.
@@ -42,5 +48,5 @@ import { type RefObject } from 'react';
  * if (!ready) return <div>Loading…</div>;   // no ref needed on this branch
  * return <div ref={rootRef}>…</div>;
  */
-export declare function useBlockResize(ref: RefObject<HTMLElement | null>): void;
+export declare function useBlockResize(ref: RefObject<HTMLElement | null>): UseBlockResize;
 //# sourceMappingURL=useBlockResize.d.ts.map

package/dist/hooks/useBlockResize.js

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Observes the referenced element's height and asks the host to resize on
  * every change. Attach to the block's root DOM element.

package/dist/hooks/useBlockSettings.d.ts

@@ -1,4 +1,9 @@
 import type { BlockSettings } from '@civitai/app-sdk/blocks';
+/**
+ * What {@link useBlockSettings} returns. An alias — see
+ * `./returnTypeLedger.js` for why every hook on the entry has one of these.
+ */
+export type UseBlockSettings = BlockSettings;
 /**
  * Shorthand for `useBlockContext().settings`. Returns the publisher- and
  * user-controlled settings the host forwarded at init. Read-only from the
@@ -8,5 +13,5 @@ import type { BlockSettings } from '@civitai/app-sdk/blocks';
  * @example
  * const { publisherSettings, userSettings } = useBlockSettings();
  */
-export declare function useBlockSettings(): BlockSettings;
+export declare function useBlockSettings(): UseBlockSettings;
 //# sourceMappingURL=useBlockSettings.d.ts.map

package/dist/hooks/useBlockTheme.d.ts

@@ -1,4 +1,9 @@
 import type { Theme } from '@civitai/app-sdk/blocks';
+/**
+ * What {@link useBlockTheme} returns. An alias — see `./returnTypeLedger.js` for why
+ * every hook on the entry has one of these.
+ */
+export type UseBlockTheme = Theme;
 /**
  * The host's CURRENT site theme (`'light' | 'dark'`), kept live for the whole
  * life of the block ON THE IFRAME TRANSPORT.
@@ -35,5 +40,5 @@ import type { Theme } from '@civitai/app-sdk/blocks';
  * const theme = useBlockTheme();
  * return <div data-theme={theme}>…</div>;
  */
-export declare function useBlockTheme(): Theme;
+export declare function useBlockTheme(): UseBlockTheme;
 //# sourceMappingURL=useBlockTheme.d.ts.map

package/dist/hooks/useBlockToken.d.ts

@@ -1,4 +1,11 @@
 import type { BlockToken } from '@civitai/app-sdk/blocks';
+/**
+ * What {@link useBlockToken} returns: the live block token plus a manual
+ * `refresh`. See `./returnTypeLedger.js`.
+ */
+export type UseBlockToken = BlockToken & {
+    refresh: () => Promise<void>;
+};
 /**
  * Returns the current block-scoped JWT and keeps it fresh.
  *
@@ -17,9 +24,7 @@ import type { BlockToken } from '@civitai/app-sdk/blocks';
  * const { raw, scopes, expiresAt, buzzBudget, refresh } = useBlockToken();
  * // after a 401: await refresh(); then retry the request once with the new `raw`.
  */
-export declare function useBlockToken(): BlockToken & {
-    refresh: () => Promise<void>;
-};
+export declare function useBlockToken(): UseBlockToken;
 /**
  * Mint/await a token refresh for one block instance, coalescing concurrent calls
  * for the SAME `blockInstanceId`. Exported for the inline-mode multi-instance

package/dist/hooks/useBlockToken.js

@@ -1,6 +1,6 @@
 import { useEffect } from 'react';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
 import { useTransportSnapshot } from './useBlockContext.js';
 /** Refresh fires `REFRESH_LEAD_MS` before the token's `expiresAt`. */
 const REFRESH_LEAD_MS = 2 * 60 * 1000;

package/dist/hooks/useBuzzAccounts.d.ts

@@ -29,8 +29,9 @@ export interface UseBuzzAccounts {
  * the creator payout pools — as `{ accountType, balance }` rows.
  *
  * Fetches once on mount and exposes `refetch`. A host that never answers surfaces
- * as an `error` after the transport timeout; late post-unmount responses are
- * ignored.
+ * as an `error` after the transport timeout. Only the LATEST request may write
+ * state: a reply superseded by a newer `refetch` — or one that lands after
+ * unmount — is dropped (#392).
  *
  * @example
  * const { accounts, loading, error } = useBuzzAccounts();

package/dist/hooks/useBuzzAccounts.js

@@ -1,6 +1,7 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { useCallback, useEffect, useState } from 'react';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
 /**
  * Read the signed-in viewer's ALL-pool Buzz balances through the host-mediated
  * `GET_BUZZ_ACCOUNTS` → `BUZZ_ACCOUNTS_RESULT` bridge. Token-bound: the host
@@ -10,8 +11,9 @@ import { sendTypedRequest } from '../internal/transport.js';
  * the creator payout pools — as `{ accountType, balance }` rows.
  *
  * Fetches once on mount and exposes `refetch`. A host that never answers surfaces
- * as an `error` after the transport timeout; late post-unmount responses are
- * ignored.
+ * as an `error` after the transport timeout. Only the LATEST request may write
+ * state: a reply superseded by a newer `refetch` — or one that lands after
+ * unmount — is dropped (#392).
  *
  * @example
  * const { accounts, loading, error } = useBuzzAccounts();
@@ -20,19 +22,18 @@ export function useBuzzAccounts() {
     const [accounts, setAccounts] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
-    const mountedRef = useRef(true);
-    useEffect(() => {
-        mountedRef.current = true;
-        return () => {
-            mountedRef.current = false;
-        };
-    }, []);
+    // Latest-wins + unmount guard in one predicate (#392): a reply may write state
+    // only if it answers the request this hook is CURRENTLY waiting for. A bare
+    // mount check would let a superseded `refetch`'s slow reply overwrite newer
+    // state — nothing unmounted, so it passes.
+    const seq = useRequestSequencer();
     const refetch = useCallback(() => {
+        const token = seq.begin();
         setLoading(true);
         setError(null);
         sendTypedRequest(getTransport(), { type: 'GET_BUZZ_ACCOUNTS', payload: {} }, 'BUZZ_ACCOUNTS_RESULT')
             .then((result) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             if (result.error || !result.result) {
                 // `||`, not `??`: the reply validator gates `error` on SHAPE only, so a
@@ -46,12 +47,12 @@ export function useBuzzAccounts() {
             setLoading(false);
         })
             .catch((err) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             setError(err instanceof Error ? err : new Error(String(err)));
             setLoading(false);
         });
-    }, []);
+    }, [seq]);
     useEffect(() => {
         refetch();
     }, [refetch]);

package/dist/hooks/useBuzzBalance.d.ts

@@ -35,8 +35,9 @@ export interface UseBuzzBalance {
  *
  * Fetches once on mount and exposes `refetch` for on-demand refreshes (e.g.
  * after a generation debits the balance). A host that never answers surfaces as
- * an `error` after the transport's request timeout — the hook never hangs. Late
- * responses that arrive after unmount are ignored (no state update).
+ * an `error` after the transport's request timeout — the hook never hangs. Only
+ * the LATEST request may write state: a reply superseded by a newer `refetch` —
+ * or one that lands after unmount — is dropped (#392).
  *
  * @example
  * const { balance, loading, error, refetch } = useBuzzBalance();

package/dist/hooks/useBuzzBalance.js

@@ -1,6 +1,7 @@
-import { useCallback, useEffect, useRef, useState } from 'react';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { useCallback, useEffect, useState } from 'react';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
 /**
  * Read the signed-in viewer's per-pool Buzz balance ({ blue, green, yellow })
  * through the host-mediated `GET_BUZZ_BALANCE` → `BUZZ_BALANCE_RESULT` bridge.
@@ -11,8 +12,9 @@ import { sendTypedRequest } from '../internal/transport.js';
  *
  * Fetches once on mount and exposes `refetch` for on-demand refreshes (e.g.
  * after a generation debits the balance). A host that never answers surfaces as
- * an `error` after the transport's request timeout — the hook never hangs. Late
- * responses that arrive after unmount are ignored (no state update).
+ * an `error` after the transport's request timeout — the hook never hangs. Only
+ * the LATEST request may write state: a reply superseded by a newer `refetch` —
+ * or one that lands after unmount — is dropped (#392).
  *
  * @example
  * const { balance, loading, error, refetch } = useBuzzBalance();
@@ -24,22 +26,18 @@ export function useBuzzBalance() {
     const [balance, setBalance] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
-    // Guards against a late response resolving after the component unmounted
-    // (React would warn about a state update on an unmounted component, and the
-    // work is wasted anyway).
-    const mountedRef = useRef(true);
-    useEffect(() => {
-        mountedRef.current = true;
-        return () => {
-            mountedRef.current = false;
-        };
-    }, []);
+    // Latest-wins + unmount guard in one predicate (#392): a reply may write state
+    // only if it answers the request this hook is CURRENTLY waiting for. A bare
+    // mount check would let a superseded `refetch`'s slow reply overwrite newer
+    // state — nothing unmounted, so it passes.
+    const seq = useRequestSequencer();
     const refetch = useCallback(() => {
+        const token = seq.begin();
         setLoading(true);
         setError(null);
         sendTypedRequest(getTransport(), { type: 'GET_BUZZ_BALANCE', payload: {} }, 'BUZZ_BALANCE_RESULT')
             .then((result) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             if (result.error || !result.balance) {
                 // `||`, not `??`: the reply validator gates `error` on SHAPE only, so a
@@ -53,12 +51,12 @@ export function useBuzzBalance() {
             setLoading(false);
         })
             .catch((err) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             setError(err instanceof Error ? err : new Error(String(err)));
             setLoading(false);
         });
-    }, []);
+    }, [seq]);
     useEffect(() => {
         refetch();
     }, [refetch]);

package/dist/hooks/useBuzzPurchase.d.ts

@@ -1,3 +1,10 @@
+/** What {@link useBuzzPurchase} returns. */
+export interface UseBuzzPurchase {
+    openPurchaseModal: (suggestedAmount?: number) => Promise<{
+        purchased: boolean;
+        newBalance?: number;
+    }>;
+}
 /**
  * Opens the Civitai Buzz purchase modal on the host. Resolves with the
  * outcome when the user closes the modal — `purchased: true` means the
@@ -15,10 +22,5 @@
  * const { purchased, newBalance } = await openPurchaseModal(suggestedAmount);
  * if (purchased) { /* retry the generation *\/ }
  */
-export declare function useBuzzPurchase(): {
-    openPurchaseModal: (suggestedAmount?: number) => Promise<{
-        purchased: boolean;
-        newBalance?: number;
-    }>;
-};
+export declare function useBuzzPurchase(): UseBuzzPurchase;
 //# sourceMappingURL=useBuzzPurchase.d.ts.map

package/dist/hooks/useBuzzPurchase.js

@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
 /**
  * Opens the Civitai Buzz purchase modal on the host. Resolves with the
  * outcome when the user closes the modal — `purchased: true` means the

package/dist/hooks/useBuzzTransactions.d.ts

@@ -41,8 +41,10 @@ export interface UseBuzzTransactions {
  *
  * Fetches on mount and whenever `params` change (by value), and exposes `refetch`.
  * A host that never answers surfaces as an `error` after the transport's request
- * timeout — the hook never hangs. Late responses that arrive after unmount are
- * ignored. Transaction `date`s are rehydrated to `Date`; `cursor` is normalized
+ * timeout — the hook never hangs. Only the LATEST request may write state: page
+ * 1's slow reply cannot repaint (or rewind `cursor` behind) the page 2 a newer
+ * request already painted, and a reply that lands after unmount is dropped
+ * (#392). Transaction `date`s are rehydrated to `Date`; `cursor` is normalized
  * to an ISO string for round-tripping.
  *
  * @example