@civitai/blocks-react 0.56.1 → 0.57.0

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,6 +1,6 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
 /**
- * Default orchestrator-side hold per {@link UseBuzzWorkflowReturn.watch} poll,
+ * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
  *
  * 🔴 THE UNIT IS SECONDS, matching the orchestrator's `?wait=` parameter — not
@@ -16,9 +16,15 @@ import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civit
  *     its own ~12s ceiling, and the two are SEQUENTIAL — so the round trip's
  *     worst case is 15 + 12 = 27s, which must stay inside the host's own
  *     end-to-end response budget.
+ *
+ * 🔴 AND THE HOST ENFORCES THAT SAME 15 (#388) — `MAX_BLOCK_POLL_WAIT_SECONDS`
+ * in `civitai/civitai` @ `b0eb2820b5`. This default therefore sits exactly AT
+ * the host's cap, not under it: raising it here changes nothing on the wire,
+ * because the host clamps. See {@link WatchWorkflowOptions.waitSeconds} for the
+ * full measured contract, including the flooring.
  */
 export declare const DEFAULT_WATCH_WAIT_SECONDS = 15;
-/** Optional controls for {@link UseBuzzWorkflowReturn.watch}. */
+/** Optional controls for {@link UseBuzzWorkflow.watch}. */
 export interface WatchWorkflowOptions {
     /**
      * Called with EVERY snapshot the host returns, intermediate ones included, in
@@ -35,18 +41,48 @@ export interface WatchWorkflowOptions {
      *
      * 🔴 This does NOT cancel the workflow — it stops watching it. Buzz is already
      * spent and the orchestrator keeps running. To actually stop the work, call
-     * {@link UseBuzzWorkflowReturn.cancel}.
+     * {@link UseBuzzWorkflow.cancel}.
      */
     signal?: AbortSignal;
     /**
      * Orchestrator-side hold per poll, in **seconds**. Default
-     * {@link DEFAULT_WATCH_WAIT_SECONDS}. `0` disables long polling and falls back
-     * to a plain read per `intervalMs`.
+     * {@link DEFAULT_WATCH_WAIT_SECONDS}.
+     *
+     * 🔴 THE HOST HONOURS AND CLAMPS THIS — it is NOT advisory (#388). This
+     * docblock said "CURRENTLY ADVISORY … a host that does not yet read the field
+     * simply answers immediately, exactly as today", which was true when written
+     * and is not true of the deployed host. The contract, read off
+     * `civitai/civitai` at **`b0eb2820b5`** (5.1.120, `main`) — two files,
+     * because a constant that nothing calls is not a contract:
+     *
+     *   - `src/server/services/blocks/workflow.service.ts:1263` declares
+     *     `MAX_BLOCK_POLL_WAIT_SECONDS = 15`.
+     *   - `:1286-1292` `resolveBlockPollWaitSeconds(waitSeconds?: number)` applies
+     *     it, and `src/server/routers/blocks.router.ts:3965` is the call site.
      *
-     * 🔴 CURRENTLY ADVISORY. It travels on the `POLL_WORKFLOW` message and a host
-     * that does not yet read the field simply answers immediately, exactly as
-     * today — so `watch` is correct either way, it just polls more often. See the
-     * field's note on `BlockToParentMessage`.
+     * What that function does, in its own order:
+     *   1. a non-`number` or non-finite value → `undefined`, i.e. NO HOLD.
+     *   2. `Math.floor` FIRST. `0.9` is therefore not "a short hold" — it floors
+     *      to `0` and becomes no hold at all, which the host's own comment calls
+     *      out explicitly.
+     *   3. floored `<= 0` → `undefined` (no hold). So `0` — and any fraction
+     *      below 1 — disables long polling and `watch` falls back to a plain read
+     *      per `intervalMs`.
+     *   4. otherwise `Math.min(floored, 15)`. Asking for 60 gets you 15.
+     *
+     * Consequences worth planning for: only whole seconds are expressible, and no
+     * value above `MAX_BLOCK_POLL_WAIT_SECONDS` buys anything — `intervalMs` is
+     * still what bounds request rate, because a clamped hold returns sooner than
+     * the caller asked for.
+     *
+     * 🔴 THIS IS PROSE ABOUT ANOTHER REPO, AND NO GUARD IN THIS ONE CAN CHECK IT.
+     * The host checkout is not present in CI, so the honest check is a human
+     * reading the two files above at a named revision — which is why the sha is
+     * quoted rather than "as of today". A later reader comparing against a newer
+     * host should update the sha along with whatever moved. The `POLL_WORKFLOW`
+     * field's own note on `BlockToParentMessage` in `@civitai/app-sdk` covers the
+     * wire shape and the older-host case; this covers what the current host does
+     * with the value.
      */
     waitSeconds?: number;
     /**
@@ -72,7 +108,7 @@ export interface WatchWorkflowOptions {
     maxRetries?: number;
 }
 /**
- * Thrown by {@link UseBuzzWorkflowReturn.estimate} when the host's reply does not
+ * Thrown by {@link UseBuzzWorkflow.estimate} when the host's reply does not
  * carry a usable price — either because the estimate ERRORED, or because it came
  * back without a numeric `cost.total`.
  *
@@ -193,12 +229,12 @@ export declare class WorkflowEstimateError extends Error {
     constructor(snapshot: BlockWorkflowSnapshot, code: 'failed' | 'no-cost');
 }
 /**
- * Why {@link UseBuzzWorkflowReturn.submit} rejected. **The two differ on whether
+ * Why {@link UseBuzzWorkflow.submit} rejected. **The two differ on whether
  * money may already have moved** — see {@link WorkflowSubmitError.code}.
  */
 export type WorkflowSubmitErrorCode = 'exception' | 'workflow-failed';
 /**
- * Thrown by {@link UseBuzzWorkflowReturn.submit} when the host's reply carries no
+ * Thrown by {@link UseBuzzWorkflow.submit} when the host's reply carries no
  * usable workflow outcome — either the submit ERRORED before anything was queued,
  * or a workflow-shaped reply came back already failed with no price.
  *
@@ -334,7 +370,7 @@ export declare class WorkflowSubmitError extends Error {
      *   `'whatif'` lands here — correctly, because the cautious money reading still
      *   applies — but there is nothing to poll. Guard with
      *   `err.snapshot.workflowId !== 'whatif'` before calling
-     *   {@link UseBuzzWorkflowReturn.watch} / {@link UseBuzzWorkflowReturn.poll} to
+     *   {@link UseBuzzWorkflow.watch} / {@link UseBuzzWorkflow.poll} to
      *   learn the workflow's actual fate before spending again.
      *
      * A union rather than a boolean so a future producer gets its own code without
@@ -372,7 +408,7 @@ export interface SubmitWorkflowOptions {
      */
     idempotencyKey?: string;
 }
-interface UseBuzzWorkflowReturn {
+export interface UseBuzzWorkflow {
     /**
      * Price a workflow without queueing it. Resolves ONLY with a snapshot that
      * carries a numeric `cost.total`.
@@ -436,7 +472,7 @@ interface UseBuzzWorkflowReturn {
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**
      * ONE host round-trip. The low-level pull primitive — you almost certainly
-     * want {@link UseBuzzWorkflowReturn.watch} instead, which owns the loop.
+     * want {@link UseBuzzWorkflow.watch} instead, which owns the loop.
      */
     poll: (workflowId: string) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -444,7 +480,7 @@ interface UseBuzzWorkflowReturn {
      * `onUpdate` with every intermediate snapshot along the way.
      *
      * This is the replacement for the `useEffect` + `setTimeout` backoff every
-     * block used to hand-write around {@link UseBuzzWorkflowReturn.poll}. The app
+     * block used to hand-write around {@link UseBuzzWorkflow.poll}. The app
      * consumes a promise and/or a callback; the loop lives here.
      *
      * 🔴 THE LOOP IS SEQUENTIAL AND NON-OVERLAPPING BY CONSTRUCTION — each poll is
@@ -507,16 +543,23 @@ interface UseBuzzWorkflowReturn {
  * enabled.
  *
  * `estimate`/`submit` take a full {@link WorkflowBody} — the discriminated
- * union keyed by `kind`, with THREE members as of `@civitai/app-sdk@0.30.0`:
- * a `textToImage` body (`{ kind, modelId, modelVersionId, params }`), a
- * `customComfy` body (`kind: 'customComfy'`), or a `step` body
- * (`{ kind: 'step', step, params }` — a server-registered orchestrator step
- * such as `'chat-completion'`), never a bare `{ prompt }`. The hook forwards
- * the body to the host verbatim and never reads variant-specific fields, so
- * every member flows through unchanged, including any member added later.
+ * union keyed by `kind`, never a bare `{ prompt }`. The hook forwards the body
+ * to the host verbatim and never reads variant-specific fields, so every member
+ * flows through unchanged, including any member added later.
+ *
+ * 🔴 THIS COMMENT DELIBERATELY DOES NOT SAY HOW MANY MEMBERS THERE ARE, OR NAME
+ * THEM (#381). It used to open "with THREE members as of
+ * `@civitai/app-sdk@0.30.0`" and close by certifying the list "otherwise
+ * unchanged" — while the union had FOUR, `WorkflowBodyPassThroughStep` having
+ * arrived in 583e8ba (#310). The sentence whose only job was to vouch for the
+ * list was the sentence that went stale. `{@link WorkflowBody}`'s own docblock
+ * is the single description of the member set; the machine-checked copy is
+ * {@link WorkflowBodyArms} below, which fails `tsc` when the union changes in
+ * either direction. A count re-typed here could only ever repeat the defect.
  *
  * 🔴 `customComfy` IS ITSELF A UNION, on `mode` — an app CAN ship its own
- * ComfyUI graph. `WorkflowBodyCustomComfyRecipe` (`mode` omitted or `'recipe'`)
+ * ComfyUI graph, which is a CAPABILITY claim, not a member count, and so is
+ * stated here. `WorkflowBodyCustomComfyRecipe` (`mode` omitted or `'recipe'`)
  * names a server-registered recipe; `WorkflowBodyCustomComfyInline`
  * (`mode: 'inline'`) carries the graph itself, plus its declared AIR
  * `resources` and a `maxBuzz` bound. The inline arm is LIVE in production
@@ -524,8 +567,9 @@ interface UseBuzzWorkflowReturn {
  * recipe-only `{ kind, recipe, params }` shape — written when that was true and
  * never revisited once the arm shipped. A developer working against the live
  * feature read the equivalent claim on the type, believed it over their own
- * instinct, and concluded the capability did not exist. `@civitai/app-sdk`
- * 0.30.0 predates the inline arm; the union above is otherwise unchanged.
+ * instinct, and concluded the capability did not exist. That is the SAME defect
+ * the paragraph above records, one member over: an incomplete description of a
+ * union, trusted because it read as authoritative.
  *
  * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
@@ -590,6 +634,5 @@ interface UseBuzzWorkflowReturn {
  *   }
  * }
  */
-export declare function useBuzzWorkflow(): UseBuzzWorkflowReturn;
-export {};
+export declare function useBuzzWorkflow(): UseBuzzWorkflow;
 //# sourceMappingURL=useBuzzWorkflow.d.ts.map

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,6 @@
 import { useCallback, useState } from 'react';
-import { getTransport } from '../internal/singleton.js';
-import { generateIdempotencyKey, sendTypedRequest } from '../internal/transport.js';
+import { getTransport } from '../transport/singleton.js';
+import { generateIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -25,7 +25,7 @@ const TERMINAL_STATUSES = new Set([
  */
 const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
 /**
- * Default orchestrator-side hold per {@link UseBuzzWorkflowReturn.watch} poll,
+ * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
  *
  * 🔴 THE UNIT IS SECONDS, matching the orchestrator's `?wait=` parameter — not
@@ -41,6 +41,12 @@ const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
  *     its own ~12s ceiling, and the two are SEQUENTIAL — so the round trip's
  *     worst case is 15 + 12 = 27s, which must stay inside the host's own
  *     end-to-end response budget.
+ *
+ * 🔴 AND THE HOST ENFORCES THAT SAME 15 (#388) — `MAX_BLOCK_POLL_WAIT_SECONDS`
+ * in `civitai/civitai` @ `b0eb2820b5`. This default therefore sits exactly AT
+ * the host's cap, not under it: raising it here changes nothing on the wire,
+ * because the host clamps. See {@link WatchWorkflowOptions.waitSeconds} for the
+ * full measured contract, including the flooring.
  */
 export const DEFAULT_WATCH_WAIT_SECONDS = 15;
 /** Gap between `watch` polls, in ms. See {@link WatchWorkflowOptions.intervalMs}. */
@@ -73,7 +79,7 @@ function sleep(ms, signal) {
     });
 }
 /**
- * Thrown by {@link UseBuzzWorkflowReturn.estimate} when the host's reply does not
+ * Thrown by {@link UseBuzzWorkflow.estimate} when the host's reply does not
  * carry a usable price — either because the estimate ERRORED, or because it came
  * back without a numeric `cost.total`.
  *
@@ -244,7 +250,7 @@ export class WorkflowEstimateError extends Error {
  */
 const HOST_SYNTHESISED_WORKFLOW_ID = 'failed';
 /**
- * Thrown by {@link UseBuzzWorkflowReturn.submit} when the host's reply carries no
+ * Thrown by {@link UseBuzzWorkflow.submit} when the host's reply carries no
  * usable workflow outcome — either the submit ERRORED before anything was queued,
  * or a workflow-shaped reply came back already failed with no price.
  *
@@ -380,7 +386,7 @@ export class WorkflowSubmitError extends Error {
      *   `'whatif'` lands here — correctly, because the cautious money reading still
      *   applies — but there is nothing to poll. Guard with
      *   `err.snapshot.workflowId !== 'whatif'` before calling
-     *   {@link UseBuzzWorkflowReturn.watch} / {@link UseBuzzWorkflowReturn.poll} to
+     *   {@link UseBuzzWorkflow.watch} / {@link UseBuzzWorkflow.poll} to
      *   learn the workflow's actual fate before spending again.
      *
      * A union rather than a boolean so a future producer gets its own code without
@@ -452,16 +458,23 @@ export class WorkflowSubmitError extends Error {
  * enabled.
  *
  * `estimate`/`submit` take a full {@link WorkflowBody} — the discriminated
- * union keyed by `kind`, with THREE members as of `@civitai/app-sdk@0.30.0`:
- * a `textToImage` body (`{ kind, modelId, modelVersionId, params }`), a
- * `customComfy` body (`kind: 'customComfy'`), or a `step` body
- * (`{ kind: 'step', step, params }` — a server-registered orchestrator step
- * such as `'chat-completion'`), never a bare `{ prompt }`. The hook forwards
- * the body to the host verbatim and never reads variant-specific fields, so
- * every member flows through unchanged, including any member added later.
+ * union keyed by `kind`, never a bare `{ prompt }`. The hook forwards the body
+ * to the host verbatim and never reads variant-specific fields, so every member
+ * flows through unchanged, including any member added later.
+ *
+ * 🔴 THIS COMMENT DELIBERATELY DOES NOT SAY HOW MANY MEMBERS THERE ARE, OR NAME
+ * THEM (#381). It used to open "with THREE members as of
+ * `@civitai/app-sdk@0.30.0`" and close by certifying the list "otherwise
+ * unchanged" — while the union had FOUR, `WorkflowBodyPassThroughStep` having
+ * arrived in 583e8ba (#310). The sentence whose only job was to vouch for the
+ * list was the sentence that went stale. `{@link WorkflowBody}`'s own docblock
+ * is the single description of the member set; the machine-checked copy is
+ * {@link WorkflowBodyArms} below, which fails `tsc` when the union changes in
+ * either direction. A count re-typed here could only ever repeat the defect.
  *
  * 🔴 `customComfy` IS ITSELF A UNION, on `mode` — an app CAN ship its own
- * ComfyUI graph. `WorkflowBodyCustomComfyRecipe` (`mode` omitted or `'recipe'`)
+ * ComfyUI graph, which is a CAPABILITY claim, not a member count, and so is
+ * stated here. `WorkflowBodyCustomComfyRecipe` (`mode` omitted or `'recipe'`)
  * names a server-registered recipe; `WorkflowBodyCustomComfyInline`
  * (`mode: 'inline'`) carries the graph itself, plus its declared AIR
  * `resources` and a `maxBuzz` bound. The inline arm is LIVE in production
@@ -469,8 +482,9 @@ export class WorkflowSubmitError extends Error {
  * recipe-only `{ kind, recipe, params }` shape — written when that was true and
  * never revisited once the arm shipped. A developer working against the live
  * feature read the equivalent claim on the type, believed it over their own
- * instinct, and concluded the capability did not exist. `@civitai/app-sdk`
- * 0.30.0 predates the inline arm; the union above is otherwise unchanged.
+ * instinct, and concluded the capability did not exist. That is the SAME defect
+ * the paragraph above records, one member over: an incomplete description of a
+ * union, trusted because it read as authoritative.
  *
  * @returns `{ estimate, submit, poll, watch, cancel, status, result, error }`.
  *
@@ -669,7 +683,7 @@ export function useBuzzWorkflow() {
         //
         // 🔴 NOT CLAIMED TO BE REACHABLE THROUGH `IframeTransport`, WHICH ALREADY
         // FAIL-CLOSES THIS. Its `payloadValidatorFor('WORKFLOW_STATUS')`
-        // (internal/validate.ts) drops a reply whose `snapshot.status` is absent
+        // (transport/validate.ts) drops a reply whose `snapshot.status` is absent
         // or outside the known set, so the request never resolves at all and
         // times out instead. This guard covers the OTHER transports
         // `sendTypedRequest` accepts (mock/test hosts, `dev:live`), and is kept as

package/dist/hooks/useCheckpointPicker.d.ts

@@ -1,4 +1,21 @@
 import type { BlockCheckpointInfo } from '@civitai/app-sdk/blocks';
+/** What {@link useCheckpointPicker} returns. */
+export interface UseCheckpointPicker {
+    open: (opts: {
+        /**
+         * Ecosystem key (e.g. 'Flux1', 'SDXL'). Get it from
+         * `useBlockContext().context.checkpoint?.baseModel` — but for the
+         * picker filter the host will collapse to the ecosystem family, so
+         * any baseModel in the family works as a hint.
+         */
+        baseModelGroup: string;
+        /** Currently-selected versionId so the picker can pre-highlight it. */
+        currentVersionId?: number;
+    }) => Promise<{
+        selected?: BlockCheckpointInfo;
+    }>;
+    persist: (versionId: number | null) => Promise<void>;
+}
 /**
  * Drives the platform-side Checkpoint picker and the persist-override flow.
  *
@@ -20,20 +37,5 @@ import type { BlockCheckpointInfo } from '@civitai/app-sdk/blocks';
  * const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
  * if (selected) await persist(selected.versionId);   // null clears the override
  */
-export declare function useCheckpointPicker(): {
-    open: (opts: {
-        /**
-         * Ecosystem key (e.g. 'Flux1', 'SDXL'). Get it from
-         * `useBlockContext().context.checkpoint?.baseModel` — but for the
-         * picker filter the host will collapse to the ecosystem family, so
-         * any baseModel in the family works as a hint.
-         */
-        baseModelGroup: string;
-        /** Currently-selected versionId so the picker can pre-highlight it. */
-        currentVersionId?: number;
-    }) => Promise<{
-        selected?: BlockCheckpointInfo;
-    }>;
-    persist: (versionId: number | null) => Promise<void>;
-};
+export declare function useCheckpointPicker(): UseCheckpointPicker;
 //# sourceMappingURL=useCheckpointPicker.d.ts.map

package/dist/hooks/useCheckpointPicker.js

@@ -1,8 +1,8 @@
 import { useCallback } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
-import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
 /**
  * Drives the platform-side Checkpoint picker and the persist-override flow.
  *

package/dist/hooks/useCivitaiNavigate.d.ts

@@ -1,3 +1,7 @@
+/** What {@link useCivitaiNavigate} returns. */
+export interface UseCivitaiNavigate {
+    navigate: (path: string, target?: 'current' | 'new_tab') => void;
+}
 /**
  * Requests a navigation within civitai.com. The host mediates — `target:
  * "current"` navigates the parent frame; `"new_tab"` opens a new tab (which
@@ -9,7 +13,5 @@
  * const { navigate } = useCivitaiNavigate();
  * navigate('/models/12345', 'new_tab');   // 'new_tab' needs allow-popups* in the manifest sandbox
  */
-export declare function useCivitaiNavigate(): {
-    navigate: (path: string, target?: 'current' | 'new_tab') => void;
-};
+export declare function useCivitaiNavigate(): UseCivitaiNavigate;
 //# sourceMappingURL=useCivitaiNavigate.d.ts.map

package/dist/hooks/useCivitaiNavigate.js

@@ -1,5 +1,5 @@
 import { useCallback } from 'react';
-import { getTransport } from '../internal/singleton.js';
+import { getTransport } from '../transport/singleton.js';
 /**
  * Requests a navigation within civitai.com. The host mediates — `target:
  * "current"` navigates the parent frame; `"new_tab"` opens a new tab (which

package/dist/hooks/useCollectionFollow.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
-import { getTransport } from '../internal/singleton.js';
-import { RequestTimeoutError, sendTypedRequest } from '../internal/transport.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
  *
@@ -158,7 +158,7 @@ export function useCollectionFollow() {
                 type: 'SET_COLLECTION_FOLLOW',
                 payload: { collectionId: args.collectionId, follow: args.follow },
             }, 'COLLECTION_FOLLOW_RESULT', 
-            // See the `'human'` bucketing in `internal/requestTimeouts.ts`: the
+            // 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) {

package/dist/hooks/useConsentUnavailable.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useState } from 'react';
 import { armConsentRefusalLatch, clearConsentRefusalLatch, readConsentRefusalLatch, } from '../internal/consentRefusalLatch.js';
-import { getTransport } from '../internal/singleton.js';
-import { subscribeTyped } from '../internal/transport.js';
+import { getTransport } from '../transport/singleton.js';
+import { subscribeTyped } from '../transport/transport.js';
 /**
  * Subscribe to the host's `CONSENT_UNAVAILABLE` push — the signal that a
  * `REQUEST_CONSENT` this block sent can **never** be granted in this

package/dist/hooks/useCreatePostFromApp.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
-import { getTransport } from '../internal/singleton.js';
-import { RequestTimeoutError, sendTypedRequest } from '../internal/transport.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
  *
@@ -170,7 +170,7 @@ export function useCreatePostFromApp() {
                         : {}),
                 },
             }, 'CREATE_POST_RESULT', 
-            // See the `'human'` bucketing in `internal/requestTimeouts.ts`: the
+            // 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) {

package/dist/hooks/useDailyCompensation.d.ts

@@ -34,8 +34,10 @@ export interface UseDailyCompensation {
  * `blocks.getMyDailyCompensation` mutation (scope `buzz:read:self`).
  *
  * Fetches on mount and whenever `params` change (by value), and exposes `refetch`.
- * A host that never answers surfaces as an `error` after the transport timeout;
- * late post-unmount responses are ignored.
+ * A host that never answers surfaces as an `error` after the transport timeout.
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch` / params change — or one that lands after unmount — is dropped
+ * (#392).
  *
  * @example
  * const { resources, hasPublishedResources } = useDailyCompensation({ date: '2026-07-01' });

package/dist/hooks/useDailyCompensation.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-modelVersion generation compensation for the
  * MONTH containing `params.date`, through the host-mediated
@@ -9,8 +10,10 @@ import { sendTypedRequest } from '../internal/transport.js';
  * `blocks.getMyDailyCompensation` mutation (scope `buzz:read:self`).
  *
  * Fetches on mount and whenever `params` change (by value), and exposes `refetch`.
- * A host that never answers surfaces as an `error` after the transport timeout;
- * late post-unmount responses are ignored.
+ * A host that never answers surfaces as an `error` after the transport timeout.
+ * Only the LATEST request may write state: a reply superseded by a newer
+ * `refetch` / params change — or one that lands after unmount — is dropped
+ * (#392).
  *
  * @example
  * const { resources, hasPublishedResources } = useDailyCompensation({ date: '2026-07-01' });
@@ -20,23 +23,22 @@ export function useDailyCompensation(params) {
     const [hasPublishedResources, setHasPublishedResources] = 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 request's slow reply overwrite newer
+    // state — nothing unmounted, so it passes.
+    const seq = useRequestSequencer();
     // Stable params key so `refetch`'s identity only changes when the params VALUE
     // changes; the callback re-parses it so it closes over nothing but the key.
     const paramsKey = JSON.stringify(params);
     const refetch = useCallback(() => {
+        const token = seq.begin();
         setLoading(true);
         setError(null);
         const parsed = JSON.parse(paramsKey);
         sendTypedRequest(getTransport(), { type: 'GET_DAILY_COMPENSATION', payload: { params: parsed } }, 'DAILY_COMPENSATION_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
@@ -51,12 +53,12 @@ export function useDailyCompensation(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/useDirectLoad.d.ts

@@ -1,3 +1,9 @@
+/**
+ * What {@link useDirectLoad} returns: `true` once the block is known to be
+ * loaded directly rather than embedded. #380 — the options type has been
+ * exported since this hook shipped; the RETURN type had no name at all.
+ */
+export type UseDirectLoad = boolean;
 export interface UseDirectLoadOptions {
     /**
      * Milliseconds to wait for `BLOCK_INIT` before treating a top-level load as a
@@ -28,5 +34,5 @@ export interface UseDirectLoadOptions {
  * Once `ready` flips it stays authoritative: this can never return `true` while
  * `ready` is `true`, so a late init can't leave a stuck fallback.
  */
-export declare function useDirectLoad(options?: UseDirectLoadOptions): boolean;
+export declare function useDirectLoad(options?: UseDirectLoadOptions): UseDirectLoad;
 //# sourceMappingURL=useDirectLoad.d.ts.map

package/dist/hooks/useDirectLoad.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { DIRECT_LOAD_TIMEOUT_MS } from '../internal/directLoad.js';
+import { DIRECT_LOAD_TIMEOUT_MS } from '../transport/directLoad.js';
 import { useTransportSnapshot } from './useBlockContext.js';
 /**
  * True iff the current window is the TOP-LEVEL browsing context — i.e. the

package/dist/hooks/useDomainMaturity.d.ts

@@ -1,7 +1,11 @@
 import type { ColorDomain } from '@civitai/app-sdk/blocks';
 /**
- * What {@link useDomainMaturity} returns.
+ * What {@link useDomainMaturity} returns. An alias for the long-standing
+ * {@link DomainMaturity} name, which stays exported and unchanged — see
+ * `./returnTypeLedger.js`.
  */
+export type UseDomainMaturity = DomainMaturity;
+/** The domain/viewer maturity projection {@link useDomainMaturity} exposes. */
 export interface DomainMaturity {
     /**
      * The color-domain the block is rendered inside (`green`|`blue`|`red`), or
@@ -92,5 +96,5 @@ export interface DomainMaturity {
  * const { maxBrowsingLevel, effectiveBrowsingLevel } = useDomainMaturity();
  * const hiddenByYourSettings = effectiveBrowsingLevel !== maxBrowsingLevel;
  */
-export declare function useDomainMaturity(): DomainMaturity;
+export declare function useDomainMaturity(): UseDomainMaturity;
 //# sourceMappingURL=useDomainMaturity.d.ts.map

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