@civitai/blocks-react 0.56.0 → 0.57.0

package/dist/hooks/useGatedImages.d.ts

@@ -43,6 +43,14 @@ export interface UseGatedImages {
  * who can't see the image, and the block must render a placeholder for any
  * `hidden` entry.
  *
+ * 🔴 A `hidden` ENTRY IS NARROWED TO `{ imageId, status }` BEFORE IT REACHES
+ * HERE, and that is enforced in code rather than asserted in prose: the
+ * transport runs `projectInboundPayload` on every `IMAGES_RESULT` before
+ * delivery (`src/transport/validate.ts`), so a `previewUrl`, `src`, `imageUrl` or
+ * any other key a host attaches to a withheld image is DROPPED, not forwarded.
+ * Fields are dropped rather than the reply rejected so a future host-side field
+ * addition cannot hang this call — see `projectGatedImage`'s docblock.
+ *
  * 🔴 `nsfwLevel` AND `contentRating` ARE OPTIONAL, AND A MISSING ONE IS NOT "G".
  * They are absent exactly when `ratingPending` is present. Treating absent as a
  * safe default is the bug this state exists to stop: an image published seconds

package/dist/hooks/useGatedImages.js

@@ -1,6 +1,6 @@
 import { useCallback } 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';
 /**
  * Read per-viewer gated display data for a list of image ids via the
  * host-mediated `GET_IMAGES_BY_IDS` → `IMAGES_RESULT` bridge — the read side of
@@ -14,6 +14,14 @@ import { sendTypedRequest } from '../internal/transport.js';
  * who can't see the image, and the block must render a placeholder for any
  * `hidden` entry.
  *
+ * 🔴 A `hidden` ENTRY IS NARROWED TO `{ imageId, status }` BEFORE IT REACHES
+ * HERE, and that is enforced in code rather than asserted in prose: the
+ * transport runs `projectInboundPayload` on every `IMAGES_RESULT` before
+ * delivery (`src/transport/validate.ts`), so a `previewUrl`, `src`, `imageUrl` or
+ * any other key a host attaches to a withheld image is DROPPED, not forwarded.
+ * Fields are dropped rather than the reply rejected so a future host-side field
+ * addition cannot hang this call — see `projectGatedImage`'s docblock.
+ *
  * 🔴 `nsfwLevel` AND `contentRating` ARE OPTIONAL, AND A MISSING ONE IS NOT "G".
  * They are absent exactly when `ratingPending` is present. Treating absent as a
  * safe default is the bug this state exists to stop: an image published seconds

package/dist/hooks/useGenerationResources.d.ts

@@ -1,4 +1,8 @@
 import type { BlockResourceInfo } from '@civitai/app-sdk/blocks';
+/** What {@link useGenerationResources} returns. */
+export interface UseGenerationResources {
+    fetch: (versionIds: number[]) => Promise<BlockResourceInfo[]>;
+}
 /**
  * Rehydrate a saved set of generation resources by version id, WITHOUT
  * re-opening the resource picker. `fetch(versionIds)` GETs the block-token-gated
@@ -21,7 +25,5 @@ import type { BlockResourceInfo } from '@civitai/app-sdk/blocks';
  * const resources = await fetch([691639, 666002]);   // by saved versionIds
  * // resources[0].strength / .minStrength / .maxStrength / .trainedWords / .clipSkip
  */
-export declare function useGenerationResources(): {
-    fetch: (versionIds: number[]) => Promise<BlockResourceInfo[]>;
-};
+export declare function useGenerationResources(): UseGenerationResources;
 //# sourceMappingURL=useGenerationResources.d.ts.map

package/dist/hooks/useHostOrigin.d.ts

@@ -1,3 +1,9 @@
+/**
+ * What {@link useHostOrigin} returns: the validated host origin, or
+ * `undefined` before `BLOCK_INIT` lands. Named so a consumer can write it —
+ * see `./returnTypeLedger.js`.
+ */
+export type UseHostOrigin = string | undefined;
 /**
  * Returns the validated host (parent) origin the block may safely direct-fetch
  * the civitai App Blocks HTTP API against — `undefined` until the transport
@@ -30,5 +36,5 @@
  * same tick it applies `BLOCK_INIT`, so the hook re-renders with the origin the
  * moment init lands.
  */
-export declare function useHostOrigin(): string | undefined;
+export declare function useHostOrigin(): UseHostOrigin;
 //# sourceMappingURL=useHostOrigin.d.ts.map

package/dist/hooks/useHostOrigin.js

@@ -1,5 +1,5 @@
 import { useSyncExternalStore } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Returns the validated host (parent) origin the block may safely direct-fetch
  * the civitai App Blocks HTTP API against — `undefined` until the transport

package/dist/hooks/useImageUpload.d.ts

@@ -1,4 +1,45 @@
 import type { BlockGenerationSourceImageInfo, BlockImageScanResult, BlockPendingImageInfo, BlockUploadedImageInfo, BlockUploadPurpose } from '@civitai/app-sdk/blocks';
+/**
+ * What {@link useImageUpload} returns for the DEFAULT (`purpose: 'display'`,
+ * blocking-scan) call — `useImageUpload()` with no arguments.
+ *
+ * 🔴 THIS HOOK IS OVERLOADED, SO ITS RETURN TYPE IS A FAMILY, NOT A SINGLETON
+ * (#380). Each overload names its own: {@link UseImageUploadGenerationSource},
+ * {@link UseImageUploadAsyncScan}, and this one. A single union would be worse
+ * than the anonymous literals it replaces — it would hand every caller a
+ * `scanStatus` that only one overload actually provides.
+ */
+export interface UseImageUpload {
+    open: () => Promise<BlockUploadedImageInfo | null>;
+}
+/** What {@link useImageUpload} returns for `{ purpose: 'generationSource' }`. */
+export interface UseImageUploadGenerationSource {
+    open: () => Promise<BlockGenerationSourceImageInfo | null>;
+}
+/** What {@link useImageUpload} returns for `{ asyncScan: true }`. */
+export interface UseImageUploadAsyncScan {
+    /** Early-resolve handle (image persisted, NOT yet scanned) or `null` (dismissed). */
+    open: () => Promise<BlockPendingImageInfo | null>;
+    /**
+     * Resolve the async scan verdict for a handle returned by `open()`. Re-callable
+     * for retry: the host emits the verdict once and the hook buffers it, so a
+     * re-call after an `'error'`/timeout re-awaits (or immediately returns) the same
+     * verdict. An unknown/expired handle resolves to a retryable `'error'`, and so
+     * does a call that is still awaiting when the component UNMOUNTS — the promise
+     * always settles, never rejects, so no caller needs a `try`/`catch` (#393).
+     */
+    scanStatus: (handle: BlockPendingImageInfo) => Promise<BlockImageScanResult>;
+}
+/**
+ * The IMPLEMENTATION signature's return — not a call signature any consumer can
+ * reach, and deliberately not on the package entry. `scanStatus` is optional
+ * here so the two non-async overloads (which return `{ open }` only) stay
+ * compatible; the async overload types it required.
+ */
+export interface UseImageUploadImplementation {
+    open: () => Promise<BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo | null>;
+    scanStatus?: (handle: BlockPendingImageInfo) => Promise<BlockImageScanResult>;
+}
 /** Options for {@link useImageUpload}. */
 export interface UseImageUploadOptions {
     /**
@@ -79,26 +120,12 @@ export interface UseImageUploadOptions {
  */
 export declare function useImageUpload(options: {
     purpose: 'generationSource';
-}): {
-    open: () => Promise<BlockGenerationSourceImageInfo | null>;
-};
+}): UseImageUploadGenerationSource;
 export declare function useImageUpload(options: {
     purpose?: 'display';
     asyncScan: true;
-}): {
-    /** Early-resolve handle (image persisted, NOT yet scanned) or `null` (dismissed). */
-    open: () => Promise<BlockPendingImageInfo | null>;
-    /**
-     * Resolve the async scan verdict for a handle returned by `open()`. Re-callable
-     * for retry: the host emits the verdict once and the hook buffers it, so a
-     * re-call after an `'error'`/timeout re-awaits (or immediately returns) the same
-     * verdict. An unknown/expired handle resolves to a retryable `'error'`.
-     */
-    scanStatus: (handle: BlockPendingImageInfo) => Promise<BlockImageScanResult>;
-};
+}): UseImageUploadAsyncScan;
 export declare function useImageUpload(options?: {
     purpose?: 'display';
-}): {
-    open: () => Promise<BlockUploadedImageInfo | null>;
-};
+}): UseImageUpload;
 //# sourceMappingURL=useImageUpload.d.ts.map

package/dist/hooks/useImageUpload.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest, subscribeTyped } from '../internal/transport.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest, subscribeTyped } from '../transport/transport.js';
 /**
  * Generous hook-side backstop for {@link BlockImageScanResult} delivery. The
  * host-side scan POLL budget is authoritative and the consuming app applies its
@@ -64,10 +64,30 @@ export function useImageUpload(options) {
         });
         return () => {
             unsubscribe();
+            // 🔴 #393 — SETTLE, DON'T JUST DISARM. This cleanup used to `clearTimeout`
+            // each waiter and stop there, which removed the ONLY remaining path to a
+            // settled promise: the listener is gone, so no verdict can ever arrive,
+            // and the backstop that would have resolved it has just been cancelled.
+            // An `await scanStatus(handle)` in flight at unmount therefore hung for
+            // the life of the page.
+            //
+            // RESOLVE, never reject: every other terminal path in this hook hands the
+            // caller a `BlockImageScanResult`, so rejecting here would be a new failure
+            // mode requiring a `try`/`catch` no existing caller has. `'error'` is the
+            // hook's RETRYABLE status, which is the honest verdict — the scan itself
+            // may well still be running server-side; this block just stopped watching.
             for (const entry of scans.values()) {
-                for (const w of entry.waiters)
+                for (const w of entry.waiters) {
                     clearTimeout(w.timeoutId);
+                    w.resolve({ status: 'error', message: 'scan status unavailable (the upload hook unmounted)' });
+                }
+                entry.waiters = [];
             }
+            // Drop the tracking map too, so a `scanStatus()` call made AFTER unmount
+            // takes the immediate unknown-handle path rather than registering a waiter
+            // against a listener that no longer exists (which would sit for the full
+            // SCAN_STATUS_TIMEOUT_MS — settled, but ten minutes late).
+            scans.clear();
         };
     }, []);
     const open = useCallback(async () => {

package/dist/hooks/usePublishGenerationOutputs.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';
 /**
  * Publish selected outputs of one of the calling app's OWN generations into bare,
  * real-scanned public `Image` rows via the host-mediated
@@ -37,7 +37,7 @@ export function usePublishGenerationOutputs() {
         // on screen. The generation was already billed and a dead publish
         // bridge has no refund path, so the charge stood and the outputs were
         // lost. Every human-gated request opts out the same way — the ledger is
-        // `HUMAN_GATED_REQUEST_TYPES` in `internal/requestTimeouts.ts`.
+        // `HUMAN_GATED_REQUEST_TYPES` in `transport/requestTimeouts.ts`.
         { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
         if (reply.error || !reply.result) {
             // `||`, not `??`: `isValidPublishResult` gates `error` on SHAPE only, so a

package/dist/hooks/useRequestConsent.d.ts

@@ -1,3 +1,9 @@
+/** What {@link useRequestConsent} returns. */
+export interface UseRequestConsent {
+    requestConsent: (payload?: {
+        scopes?: string[];
+    }) => void;
+}
 /**
  * Lazy consent. Asks the host to open civitai.com's consent UI when a
  * LOGGED-IN viewer clicks an action whose consent-gated scope the block token
@@ -39,9 +45,5 @@
  * // viewer is logged in but the token lacks the spend scopes:
  * requestConsent({ scopes: ['ai:write:budgeted', 'buzz:read:self'] });
  */
-export declare function useRequestConsent(): {
-    requestConsent: (payload?: {
-        scopes?: string[];
-    }) => void;
-};
+export declare function useRequestConsent(): UseRequestConsent;
 //# sourceMappingURL=useRequestConsent.d.ts.map

package/dist/hooks/useRequestConsent.js

@@ -1,6 +1,6 @@
 import { useCallback } from 'react';
 import { armConsentRefusalLatch } from '../internal/consentRefusalLatch.js';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Lazy consent. Asks the host to open civitai.com's consent UI when a
  * LOGGED-IN viewer clicks an action whose consent-gated scope the block token

package/dist/hooks/useRequestSequencer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ONE latest-wins guard for every hook that auto-issues a request and writes the
+ * reply into component state (#392).
+ *
+ * 🔴 WHY THIS IS A SHARED HELPER AND NOT A PATTERN TO COPY. Before it, eight
+ * hooks each open-coded a `mountedRef` and every one of them got the same thing
+ * wrong in the same direction: `mountedRef` answers "is this component still
+ * here?", which is not the question a reply has to pass. The question is "is
+ * this reply still the one I am waiting for?" — and a superseded request's reply
+ * passes the mount check every time, because nothing unmounted. A predicate
+ * duplicated across N call sites regenerates the same bug at N sites; this is
+ * the consolidation that makes it one site.
+ *
+ * THE FAILURE IT CLOSES. `refetch`'s identity changes (a `paramsKey` moves when
+ * the viewer clicks "next page"), the mount effect re-runs, and request B goes
+ * out while A is still in flight. B answers first and paints page 2. A answers
+ * second and — with only a mount guard — repaints page 1 *and* rewrites `cursor`
+ * to page 2's value, so "next" re-fetches the page already shown and the viewer
+ * is wedged. The transport correlates each reply to its own request correctly;
+ * the defect is purely in which reply the hook lets write state.
+ *
+ * WHAT IT SUPERSEDES. `isCurrent` is FALSE after unmount as well as for a
+ * superseded request, so it replaces `mountedRef` rather than sitting next to
+ * it — one predicate, one place, both hazards.
+ *
+ * ⚠️ HONEST LABEL ON THE MOUNT HALF: it is DEFENSIVE, not load-bearing, and no
+ * test in this package can kill it. Mutating `mountedRef.current && token ===
+ * latestRef.current` down to just the latest-wins half leaves 84 tests green,
+ * because on React 18+ a `setState` against an unmounted component is a silent
+ * no-op — there is no warning to catch and no render to observe. It is kept
+ * because it is what the hooks did before (it avoids the pointless work), NOT
+ * because anything measures it. The LATEST-WINS half is the one that carries
+ * weight: mutating THAT away reddens 24 cases.
+ *
+ * @example
+ * const seq = useRequestSequencer();
+ * const refetch = useCallback(() => {
+ *   const token = seq.begin();          // supersedes any earlier request
+ *   setLoading(true);
+ *   sendTypedRequest(...)
+ *     .then((reply) => {
+ *       if (!seq.isCurrent(token)) return;   // stale or unmounted — drop it
+ *       setData(reply.result);
+ *       setLoading(false);
+ *     });
+ * }, [seq, ...]);
+ */
+export interface RequestSequencer {
+    /**
+     * Open a new request and SUPERSEDE every earlier one. Returns the token that
+     * identifies it; hand that token to {@link RequestSequencer.isCurrent} before
+     * writing any state derived from the reply.
+     */
+    begin: () => number;
+    /**
+     * `true` only when `token` names the most recently begun request AND the
+     * component is still mounted. Every other case — a superseded request, a reply
+     * after unmount — is `false`.
+     */
+    isCurrent: (token: number) => boolean;
+}
+/**
+ * Create a {@link RequestSequencer} for one hook instance.
+ *
+ * The returned object is STABLE for the life of the component (both methods are
+ * `useCallback`-pinned with no dependencies, and the object itself is memoized),
+ * so a consumer can list it in a `useCallback` dependency array without
+ * retriggering the very effect it guards.
+ */
+export declare function useRequestSequencer(): RequestSequencer;
+//# sourceMappingURL=useRequestSequencer.d.ts.map

package/dist/hooks/useRequestSequencer.js

@@ -0,0 +1,28 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+/**
+ * Create a {@link RequestSequencer} for one hook instance.
+ *
+ * The returned object is STABLE for the life of the component (both methods are
+ * `useCallback`-pinned with no dependencies, and the object itself is memoized),
+ * so a consumer can list it in a `useCallback` dependency array without
+ * retriggering the very effect it guards.
+ */
+export function useRequestSequencer() {
+    // Monotonic request counter. `0` is the "no request yet" value and is never
+    // handed out, so `isCurrent(0)` is false by construction.
+    const latestRef = useRef(0);
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const begin = useCallback(() => {
+        latestRef.current += 1;
+        return latestRef.current;
+    }, []);
+    const isCurrent = useCallback((token) => mountedRef.current && token === latestRef.current, []);
+    return useMemo(() => ({ begin, isCurrent }), [begin, isCurrent]);
+}
+//# sourceMappingURL=useRequestSequencer.js.map

package/dist/hooks/useRequestSignIn.d.ts

@@ -1,3 +1,9 @@
+/** What {@link useRequestSignIn} returns. */
+export interface UseRequestSignIn {
+    requestSignIn: (payload?: {
+        returnUrl?: string;
+    }) => void;
+}
 /**
  * Anonymous conversion. Asks the host to start civitai.com's login flow when a
  * logged-out viewer (`useBlockContext().viewer === null`) clicks an action that
@@ -16,9 +22,5 @@
  * const { requestSignIn } = useRequestSignIn();
  * if (viewer === null) return <button onClick={() => requestSignIn()}>Sign in</button>;
  */
-export declare function useRequestSignIn(): {
-    requestSignIn: (payload?: {
-        returnUrl?: string;
-    }) => void;
-};
+export declare function useRequestSignIn(): UseRequestSignIn;
 //# sourceMappingURL=useRequestSignIn.d.ts.map

package/dist/hooks/useRequestSignIn.js

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Anonymous conversion. Asks the host to start civitai.com's login flow when a
  * logged-out viewer (`useBlockContext().viewer === null`) clicks an action that

package/dist/hooks/useResourcePicker.d.ts

@@ -1,4 +1,19 @@
 import type { BlockResourceInfo, BlockResourcePickerType } from '@civitai/app-sdk/blocks';
+/** What {@link useResourcePicker} returns. */
+export interface UseResourcePicker {
+    open: (opts: {
+        /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
+         * 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.
+         */
+        baseModelGroup?: string;
+    }) => Promise<BlockResourceInfo | null>;
+}
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
  * host-chrome). Generalizes {@link useCheckpointPicker} from Checkpoint-only to
@@ -27,18 +42,5 @@ import type { BlockResourceInfo, BlockResourcePickerType } from '@civitai/app-sd
  * if (!picked) return;                 // user dismissed
  * // feed picked.versionId into body.additionalResources and submit
  */
-export declare function useResourcePicker(): {
-    open: (opts: {
-        /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
-         * 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.
-         */
-        baseModelGroup?: string;
-    }) => Promise<BlockResourceInfo | null>;
-};
+export declare function useResourcePicker(): UseResourcePicker;
 //# sourceMappingURL=useResourcePicker.d.ts.map

package/dist/hooks/useResourcePicker.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';
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
  * host-chrome). Generalizes {@link useCheckpointPicker} from Checkpoint-only to

package/dist/hooks/useSaveImage.js

@@ -1,7 +1,7 @@
 import { useCallback } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { sendTypedRequest } from '../transport/transport.js';
 /**
  * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
  * bridge. See {@link SaveImageInput} for the url-vs-id security posture.

package/dist/hooks/useSharedStorage.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';
 /**
  * App-scoped, append-only, community-votable SHARED datastore. Sibling of
  * {@link useAppStorage} (the per-viewer KV store) — same postMessage bridge,

package/dist/hooks/useTip.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
-import { generateIdempotencyKey } from '../internal/transport.js';
+import { generateIdempotencyKey } from '../transport/transport.js';
 /**
  * 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

package/dist/hooks/useTipAllowance.d.ts

@@ -15,7 +15,14 @@ export interface UseTipAllowance {
     allowance: TipAllowance | null;
     /** `true` while a fetch (initial or `refetch`) is in flight. */
     loading: boolean;
-    /** The last fetch's failure, or `null`. Cleared at the start of the next fetch. */
+    /**
+     * The last fetch's failure, or `null`. Cleared at the start of the next fetch.
+     *
+     * Also carries the NO-HOST-ORIGIN terminal state (#398): if `BLOCK_INIT` never
+     * lands — a direct/unembedded load, or `InlineTransport` before bootstrap —
+     * `loading` drops to `false` and this becomes a named `Error` after
+     * {@link HOST_ORIGIN_WAIT_MS}, instead of the hook spinning forever.
+     */
     error: Error | null;
     /** Re-read the allowance (e.g. after the viewer tips). */
     refetch: () => void;
@@ -32,6 +39,11 @@ export interface UseTipAllowance {
  * (`localStorage` is inert in the opaque-origin sandbox). Fetches once on mount
  * and exposes `refetch` (call it after a successful `useTip().tip(...)`).
  *
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch` — or one that lands after unmount — is dropped (#392). If the host
+ * origin never arrives the hook reaches a TERMINAL state rather than spinning:
+ * see `error` above (#398).
+ *
  * @example
  * const { allowance, refetch } = useTipAllowance();
  * // allowance?.remaining — Buzz the viewer may still tip today

package/dist/hooks/useTipAllowance.js

@@ -1,11 +1,28 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
 /**
  * Backstop timeout for the direct REST allowance GET (see {@link useTip} /
  * {@link useGenerationResources} for why direct-fetch hooks need their own bound).
  */
 const TIP_ALLOWANCE_TIMEOUT_MS = 30_000;
+/**
+ * How long the hook waits for `useHostOrigin()` before declaring the block
+ * un-embedded (#398).
+ *
+ * 🔴 A BOUND, NOT AN IMMEDIATE ERROR, AND THE DIFFERENCE MATTERS. The host
+ * origin is absent on EVERY boot — it lands a tick or two after mount, with
+ * `BLOCK_INIT` — so erroring on the first `!host` would flash a spurious error
+ * on every healthy embedded block. Only its CONTINUED absence is the fault, and
+ * that is what this measures.
+ *
+ * Equal to {@link TIP_ALLOWANCE_TIMEOUT_MS} by coincidence, not by derivation:
+ * this bounds a wait for the HOST to introduce itself, that one bounds a request
+ * already in flight. Two independent questions, so two constants — tuning either
+ * must not silently retune the other.
+ */
+const HOST_ORIGIN_WAIT_MS = 30_000;
 /**
  * Read the viewer's REAL remaining daily tip allowance `{ cap, spent, remaining }`
  * through the block-token-gated `GET /api/v1/blocks/tip-allowance` REST endpoint
@@ -18,6 +35,11 @@ const TIP_ALLOWANCE_TIMEOUT_MS = 30_000;
  * (`localStorage` is inert in the opaque-origin sandbox). Fetches once on mount
  * and exposes `refetch` (call it after a successful `useTip().tip(...)`).
  *
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch` — or one that lands after unmount — is dropped (#392). If the host
+ * origin never arrives the hook reaches a TERMINAL state rather than spinning:
+ * see `error` above (#398).
+ *
  * @example
  * const { allowance, refetch } = useTipAllowance();
  * // allowance?.remaining — Buzz the viewer may still tip today
@@ -28,26 +50,42 @@ export function useTipAllowance() {
     const [allowance, setAllowance] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
-    const mountedRef = useRef(true);
+    // 🔴 `inFlight` IS NOT A SEQUENCING GUARD, and #392's triage note read it as
+    // one. It is drained only by the unmount cleanup below, so two overlapping
+    // `refetch()`es neither abort each other nor correlate their replies — the
+    // slower one simply wrote last. `useRequestSequencer` is what supplies the
+    // latest-wins predicate; this set exists to abort on unmount and to let a
+    // superseded request's socket be closed rather than left running.
     const inFlight = useRef(new Set());
+    const seq = useRequestSequencer();
     useEffect(() => {
-        mountedRef.current = true;
         const controllers = inFlight.current;
         return () => {
-            mountedRef.current = false;
             for (const c of controllers)
                 c.abort();
             controllers.clear();
         };
     }, []);
+    // #398 — bounded wait for the host origin. Re-armed whenever `host` changes,
+    // and cleared the moment one arrives, so the terminal error is reachable ONLY
+    // when the origin is still absent a full HOST_ORIGIN_WAIT_MS after mount.
+    useEffect(() => {
+        if (host)
+            return;
+        const id = setTimeout(() => {
+            setLoading(false);
+            setError(new Error(`useTipAllowance: host origin not established after ${HOST_ORIGIN_WAIT_MS}ms (no BLOCK_INIT — the block is probably not embedded).`));
+        }, HOST_ORIGIN_WAIT_MS);
+        return () => clearTimeout(id);
+    }, [host, seq]);
     const refetch = useCallback(() => {
-        // Wait for the host origin (established at BLOCK_INIT) before the first fetch.
+        // Wait for the host origin (established at BLOCK_INIT) before the first
+        // fetch. The effect above is what stops this from being an eternal spinner.
         if (!host)
             return;
-        if (mountedRef.current) {
-            setLoading(true);
-            setError(null);
-        }
+        const token = seq.begin();
+        setLoading(true);
+        setError(null);
         const controller = new AbortController();
         inFlight.current.add(controller);
         const timeoutId = setTimeout(() => controller.abort(), TIP_ALLOWANCE_TIMEOUT_MS);
@@ -57,7 +95,7 @@ export function useTipAllowance() {
         })
             .then(async (res) => {
             const body = (await res.json().catch(() => null));
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             if (!res.ok || body == null || typeof body.remaining !== 'number') {
                 setError(new Error(body?.error ?? `tip-allowance request failed (${res.status})`));
@@ -68,7 +106,7 @@ export function useTipAllowance() {
             setLoading(false);
         })
             .catch((err) => {
-            if (!mountedRef.current)
+            if (!seq.isCurrent(token))
                 return;
             setError(controller.signal.aborted
                 ? new Error(`useTipAllowance: request aborted (timed out after ${TIP_ALLOWANCE_TIMEOUT_MS}ms or the hook unmounted).`)
@@ -81,7 +119,7 @@ export function useTipAllowance() {
             clearTimeout(timeoutId);
             inFlight.current.delete(controller);
         });
-    }, [host, raw]);
+    }, [host, raw, seq]);
     useEffect(() => {
         refetch();
     }, [refetch]);

package/dist/hooks/useViewer.d.ts

@@ -32,8 +32,9 @@ export interface UseViewer {
  *
  * Fetches once on mount and exposes `refetch` for on-demand refreshes. 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).
+ * 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 { viewer, loading, error, refetch } = useViewer();