@civitai/blocks-react 0.72.0 → 0.72.2

package/README.md

@@ -117,6 +117,33 @@ viewer's signed-in civitai.com session, which the local harness does not have, s
 host — `createMockHost` or `Harness` from `@civitai/blocks-react/testing`, with
 the `publishImageIds` / `publishError` options.
 
+### Required at mount: the host handshake
+
+The SDK must be **connected at mount**. When the transport is created it posts
+`BLOCK_HELLO` to the host, and it answers the host's first valid `BLOCK_INIT`
+with `BLOCK_READY`. The host waits **10 seconds** for that answer; without it,
+the viewer sees "This app didn't load in time", the host retries twice, and then
+gives up. `"bootSkeleton": true` only removes the host's loading cover — it does
+**not** extend or lift that deadline.
+
+You do not have to do anything for this: **every hook exported from the package
+root connects the transport when its component mounts**, so a block that calls
+any one of them — even only `useBuzzWorkflow()`, whose requests all happen in
+callbacks — answers the host before anyone clicks. (In earlier releases, request-only
+hooks connected lazily on their first call, so a block whose only SDK use was
+such a hook rendered fine and was then timed out by the host.)
+
+What this means for you:
+
+- A block that renders but uses **no** hook from this package never connects.
+  Call `useBlockContext()` at your root (you will want its `ready` gate anyway).
+- A dev harness that injects options with `getTransport({ allowedParentOrigins })`
+  must still do so **before** the first component that uses a hook mounts — only
+  the first call's options are honoured.
+- If no parent allowlist is configured, the mount-time connect logs one
+  `console.error` and the block keeps rendering; the first bridge call then
+  throws the same configuration error it always did.
+
 ### `useBlockContext()`
 
 The primary hook. Returns everything the host delivered in `BLOCK_INIT` plus a
@@ -546,6 +573,25 @@ try {
 - A refused `kind: 'workflow'` body sets its own codes, in the same shape — see
   the next section.
 
+#### A registered step with no price quote: `step_quote_*`
+
+A **registered** `kind: 'step'` body (one with a `step` id, such as
+`'chat-completion'` or `'convert-image'`) that the host has no price quote for
+fails on `estimate()` (`WorkflowEstimateError`) and as a batch-estimate cell,
+as `{ workflowId: 'failed', status: 'failed', error, errorCode }` with no
+`cost`. `submit()` of the same body is unchanged. The pass-through arm (a
+`$type`, no `step`) does not set these codes.
+
+| `errorCode` | Means | `error` | Retry the same body? |
+|---|---|---|---|
+| `'step_quote_rejected'` | the orchestrator refused the request | `No price quote for this step: the orchestrator rejected the request: <reason>` when the reason is safe to show, else `No price quote for this step: the orchestrator rejected the request; check the step inputs and references (retrying the same body will not help)` | no — change the body |
+| `'step_quote_unavailable'` | no usable answer (an outage, a timeout, a rate limit, …) | `No price quote for this step: none could be obtained; try again` | yes |
+| `'step_quote_unpriced'` | the orchestrator answered without a price | `No price quote for this step: the orchestrator answered without one` | not expected to help |
+
+An older host has none of the three: it resolves the estimate priced at the
+step's declared estimate. The mock host always quotes a registered step (at
+`generation.costPerGen`), so it never sends these codes.
+
 #### Several steps as one workflow: `kind: 'workflow'`
 
 A `kind: 'workflow'` body submits **several orchestrator steps as one

package/dist/hooks/useAppStorage.js

@@ -2,6 +2,7 @@ import { useMemo } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply, throwOnReplyError } from '../internal/replyError.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Per-(block instance, viewer) KV datastore. Calls flow through the host's
  * postMessage bridge — the block never sees the apps DB credentials.
@@ -47,6 +48,7 @@ import { sendTypedRequest } from '../transport/transport.js';
  * const quota = await storage.getQuota();       // { usedBytes, rowCount, limitBytes, limitRows }
  */
 export function useAppStorage() {
+    useTransportConnection();
     return useMemo(() => {
         const transport = getTransport();
         return {

package/dist/hooks/useAppWorkflows.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.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 —
@@ -24,6 +25,7 @@ import { useRequestSequencer } from './useRequestSequencer.js';
  * // …render each workflow's images; await cancel(w.workflowId) on a Cancel click.
  */
 export function useAppWorkflows(params) {
+    useTransportConnection();
     const [workflows, setWorkflows] = useState([]);
     const [cursor, setCursor] = useState(null);
     const [loading, setLoading] = useState(true);

package/dist/hooks/useBatchEstimate.js

@@ -4,6 +4,7 @@ import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
 import { WorkflowEstimateError } from './useBuzzWorkflow.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The most bodies one {@link UseBatchEstimate.estimateBatch} call may carry.
  *
@@ -134,6 +135,7 @@ function toBatchEstimateError(err) {
  * }
  */
 export function useBatchEstimate() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [result, setResult] = useState(null);
     const [error, setError] = useState(null);

package/dist/hooks/useBlockAnalytics.js

@@ -1,5 +1,6 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Custom events for your app's analytics panel. Fire-and-forget: the host
  * forwards the event and the block gets no acknowledgement, so never wait on
@@ -47,6 +48,7 @@ import { getTransport } from '../transport/singleton.js';
  * track('generate_clicked', { mode: 'txt2img', batch: 4 });
  */
 export function useBlockAnalytics() {
+    useTransportConnection();
     const track = useCallback((eventName, properties) => {
         getTransport().sendMessage({ type: 'TRACK_EVENT', payload: { eventName, properties } });
     }, []);

package/dist/hooks/useBlockBreakpoint.js

@@ -1,5 +1,6 @@
 import { BREAKPOINT_KEYS, breakpoints } from '@civitai/theme';
 import { useEffect, useMemo, useRef, useState } from 'react';
+import { useTransportConnection } from './useTransportConnection.js';
 /** Ascending tier order. `base` first; the rest follow `BREAKPOINT_KEYS`. */
 const TIER_ORDER = ['base', ...BREAKPOINT_KEYS];
 /**
@@ -66,6 +67,7 @@ export function resolveBlockTier(width) {
  * );
  */
 export function useBlockBreakpoint(ref) {
+    useTransportConnection();
     // `null` means UNMEASURED — distinct from a measured `'base'`. See `measured`.
     const [tier, setTier] = useState(null);
     // 🔴 THE EFFECT MUST NOT DEPEND ON THE REF WRAPPER'S IDENTITY. Unlike

package/dist/hooks/useBlockContext.js

@@ -1,5 +1,6 @@
 import { useSyncExternalStore } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Subscribe a hook to the singleton transport. All hooks build on this —
  * `useSyncExternalStore` gives concurrent-mode safety and minimal re-renders.
@@ -42,6 +43,7 @@ function useTransportSnapshot() {
  * return <div data-theme={theme}>{isSignedIn(viewer) ? 'Hi there' : 'Hi anon'}</div>;
  */
 export function useBlockContext() {
+    useTransportConnection();
     const snap = useTransportSnapshot();
     return {
         ready: snap.ready,

package/dist/hooks/useBlockResize.js

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Observes the referenced element's height and asks the host to resize on
  * every change. Attach to the block's root DOM element.
@@ -44,6 +45,7 @@ import { getTransport } from '../transport/singleton.js';
  * return <div ref={rootRef}>…</div>;
  */
 export function useBlockResize(ref) {
+    useTransportConnection();
     /** The element the live observer is watching. `null` = watching nothing. */
     const observedRef = useRef(null);
     const observerRef = useRef(null);

package/dist/hooks/useBlockSettings.js

@@ -1,4 +1,5 @@
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Shorthand for `useBlockContext().settings`. Returns the publisher- and
  * user-controlled settings the host forwarded at init. Read-only from the
@@ -19,6 +20,7 @@ import { useTransportSnapshot } from './useBlockContext.js';
  * const { publisherSettings, userSettings } = useBlockSettings();
  */
 export function useBlockSettings() {
+    useTransportConnection();
     return useTransportSnapshot().settings;
 }
 //# sourceMappingURL=useBlockSettings.js.map

package/dist/hooks/useBlockTheme.js

@@ -1,4 +1,5 @@
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The host's CURRENT site theme (`'light' | 'dark'`), kept live for the whole
  * life of the block ON THE IFRAME TRANSPORT.
@@ -36,6 +37,7 @@ import { useTransportSnapshot } from './useBlockContext.js';
  * return <div data-theme={theme}>…</div>;
  */
 export function useBlockTheme() {
+    useTransportConnection();
     return useTransportSnapshot().theme;
 }
 //# sourceMappingURL=useBlockTheme.js.map

package/dist/hooks/useBlockToken.js

@@ -2,6 +2,7 @@ import { useEffect } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /** Refresh fires `REFRESH_LEAD_MS` before the token's `expiresAt`. */
 const REFRESH_LEAD_MS = 2 * 60 * 1000;
 /**
@@ -37,6 +38,7 @@ const REFRESH_LEAD_MS = 2 * 60 * 1000;
  * }
  */
 export function useBlockToken() {
+    useTransportConnection();
     const snap = useTransportSnapshot();
     const token = snap.token;
     const instanceId = snap.blockInstanceId;

package/dist/hooks/useBuzzAccounts.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.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
@@ -19,6 +20,7 @@ import { useRequestSequencer } from './useRequestSequencer.js';
  * const { accounts, loading, error } = useBuzzAccounts();
  */
 export function useBuzzAccounts() {
+    useTransportConnection();
     const [accounts, setAccounts] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);

package/dist/hooks/useBuzzBalance.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.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.
@@ -23,6 +24,7 @@ import { useRequestSequencer } from './useRequestSequencer.js';
  * return <span>Yellow: {balance?.yellow ?? 0}</span>;
  */
 export function useBuzzBalance() {
+    useTransportConnection();
     const [balance, setBalance] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);

package/dist/hooks/useBuzzPurchase.js

@@ -2,6 +2,7 @@ import { useCallback } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Opens the Civitai Buzz purchase modal on the host. Resolves with the
  * outcome when the user closes the modal — `purchased: true` means the
@@ -22,6 +23,7 @@ import { sendTypedRequest } from '../transport/transport.js';
  * if (purchased) { /* retry the generation *\/ }
  */
 export function useBuzzPurchase() {
+    useTransportConnection();
     const openPurchaseModal = useCallback(async (suggestedAmount) => {
         const { purchased, newBalance } = await sendTypedRequest(getTransport(), { type: 'OPEN_BUZZ_PURCHASE', payload: { suggestedAmount } }, 'BUZZ_PURCHASE_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
         return { purchased, newBalance };

package/dist/hooks/useBuzzTransactions.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /** Rehydrate the host's `date`/`cursor` (a `Date` instance OR an ISO string). */
 function toDate(v) {
     return v instanceof Date ? v : new Date(v);
@@ -31,6 +32,7 @@ function toIso(v) {
  * const { transactions, cursor, loading, error } = useBuzzTransactions({ type: 'Tip', limit: 20 });
  */
 export function useBuzzTransactions(params) {
+    useTransportConnection();
     const [transactions, setTransactions] = useState(null);
     const [cursor, setCursor] = useState(null);
     const [loading, setLoading] = useState(true);

package/dist/hooks/useBuzzWorkflow.js

@@ -4,6 +4,7 @@ import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { resolveIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The consent-gated scope {@link UseBuzzWorkflow.submit} requires.
  *
@@ -622,6 +623,7 @@ export class WorkflowSubmitError extends Error {
  * }
  */
 export function useBuzzWorkflow() {
+    useTransportConnection();
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
     const [error, setError] = useState(null);

package/dist/hooks/useCheckpointPicker.js

@@ -3,6 +3,7 @@ import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Drives the platform-side Checkpoint picker and the persist-override flow.
  *
@@ -34,6 +35,7 @@ import { sendTypedRequest } from '../transport/transport.js';
  * const { selected } = await open({ baseModelGroup: checkpoint.baseModel });
  */
 export function useCheckpointPicker() {
+    useTransportConnection();
     const open = useCallback(async (opts) => {
         // Both keys are spread conditionally, and an empty or whitespace-only
         // family is normalized to absent.

package/dist/hooks/useCivitaiNavigate.js

@@ -1,5 +1,6 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Requests a navigation from the host: the hook sends a `NAVIGATE` message and
  * returns. Fire-and-forget — the host doesn't reply, so the block never learns
@@ -38,6 +39,7 @@ import { getTransport } from '../transport/singleton.js';
  * navigate('detail/7', 'new_tab');                       // the pre-`scope` shape, still app-scoped
  */
 export function useCivitaiNavigate() {
+    useTransportConnection();
     const navigate = useCallback((path, options = {}) => {
         // A bare string is the pre-`scope` call shape (`navigate(path, 'new_tab')`)
         // and stays supported: there are live callers, and the whole point of the

package/dist/hooks/useCivitaiRoute.js

@@ -1,4 +1,5 @@
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The sub-path below your app's root that is CURRENTLY showing, kept live for
  * the whole life of the block ON THE IFRAME TRANSPORT.
@@ -56,6 +57,7 @@ import { useTransportSnapshot } from './useBlockContext.js';
  * moves and nothing renders.
  */
 export function useCivitaiRoute() {
+    useTransportConnection();
     const context = useTransportSnapshot().context;
     // A PRESENCE test, not a slot-id test, and not a cast. `BlockContext` is a
     // union whose `UnknownSlotContext` arm declares `slotId` and nothing else, and

package/dist/hooks/useCollectionFollow.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
  *
@@ -134,6 +135,7 @@ export class CollectionFollowError extends Error {
  * };
  */
 export function useCollectionFollow() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [error, setError] = useState(null);
     // Same guard as `useTip`/`useWildcardPack`: this request can outlive the

package/dist/hooks/useConsentUnavailable.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { armConsentRefusalLatch, clearConsentRefusalLatch, readConsentRefusalLatch, } from '../internal/consentRefusalLatch.js';
 import { getTransport } from '../transport/singleton.js';
 import { subscribeTyped } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Subscribe to the host's `CONSENT_UNAVAILABLE` push — the signal that a
  * `REQUEST_CONSENT` this block sent can **never** be granted in this
@@ -62,6 +63,7 @@ import { subscribeTyped } from '../transport/transport.js';
  * return <button onClick={() => requestConsent({ scopes: ['ai:write:budgeted'] })}>Generate</button>;
  */
 export function useConsentUnavailable() {
+    useTransportConnection();
     const [refusal, setRefusal] = useState(null);
     useEffect(() => {
         const transport = getTransport();

package/dist/hooks/useCreatePostFromApp.js

@@ -4,6 +4,7 @@ import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The consent-gated scope this bridge requires — `posts:write:self`, named in
  * `@civitai/app-sdk`'s own `CREATE_POST_FROM_APP` message docs ("Scope
@@ -156,6 +157,7 @@ export class CreatePostError extends Error {
  * };
  */
 export function useCreatePostFromApp() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [error, setError] = useState(null);
     // Same guard as `useCollectionFollow`: this request can outlive the component

package/dist/hooks/useDailyCompensation.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Read the signed-in viewer's per-modelVersion generation compensation for the
  * MONTH containing `params.date`, through the host-mediated
@@ -19,6 +20,7 @@ import { useRequestSequencer } from './useRequestSequencer.js';
  * const { resources, hasPublishedResources } = useDailyCompensation({ date: '2026-07-01' });
  */
 export function useDailyCompensation(params) {
+    useTransportConnection();
     const [resources, setResources] = useState(null);
     const [hasPublishedResources, setHasPublishedResources] = useState(null);
     const [loading, setLoading] = useState(true);

package/dist/hooks/useDirectLoad.js

@@ -1,6 +1,7 @@
 import { useEffect, useState } from 'react';
 import { DIRECT_LOAD_TIMEOUT_MS } from '../transport/directLoad.js';
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * True iff the current window is the TOP-LEVEL browsing context — i.e. the
  * block is NOT running inside an iframe.
@@ -47,6 +48,7 @@ function isTopLevel() {
  * `ready` is `true`, so a late init can't leave a stuck fallback.
  */
 export function useDirectLoad(options) {
+    useTransportConnection();
     const timeoutMs = options?.timeoutMs ?? DIRECT_LOAD_TIMEOUT_MS;
     const ready = useTransportSnapshot().ready;
     // Sampled once per mount — top-level-ness doesn't change during a page's life.

package/dist/hooks/useDomainMaturity.js

@@ -1,5 +1,6 @@
 import { effectiveBrowsingCeiling, isSfwCeiling, isLevelAllowed as isLevelAllowedCeiling, } from '@civitai/app-sdk/blocks';
 import { useTransportSnapshot } from './useBlockContext.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Read the maturity ceiling in force for the current viewer, as the host
  * projects it into `BLOCK_INIT`, so a block can hide/blur mature affordances.
@@ -40,6 +41,7 @@ import { useTransportSnapshot } from './useBlockContext.js';
  * const hiddenByYourSettings = effectiveBrowsingLevel !== maxBrowsingLevel;
  */
 export function useDomainMaturity() {
+    useTransportConnection();
     const snap = useTransportSnapshot();
     const maxBrowsingLevel = snap.maxBrowsingLevel;
     // The one number every gate below is computed from. `effectiveBrowsingCeiling`

package/dist/hooks/useEntitlements.js

@@ -4,6 +4,7 @@ import { useBlockContext } from './useBlockContext.js';
 import { useBlockToken } from './useBlockToken.js';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Backstop timeout for the direct REST entitlements GET (see {@link useTip} /
  * {@link useGenerationResources} for why direct-fetch hooks need their own bound).
@@ -51,6 +52,7 @@ const HOST_ORIGIN_WAIT_MS = 30_000;
  * return owns('extra-slots') ? <Unlocked /> : <BuyButton onDone={refetch} />;
  */
 export function useEntitlements() {
+    useTransportConnection();
     const host = useHostOrigin();
     const { raw } = useBlockToken();
     const { ready, viewer } = useBlockContext();

package/dist/hooks/useGatedImages.js

@@ -1,6 +1,7 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.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
@@ -39,6 +40,7 @@ import { sendTypedRequest } from '../transport/transport.js';
  * }
  */
 export function useGatedImages() {
+    useTransportConnection();
     const getImages = useCallback(async (imageIds) => {
         const reply = await sendTypedRequest(getTransport(), { type: 'GET_IMAGES_BY_IDS', payload: { imageIds } }, 'IMAGES_RESULT');
         if (reply.error || !reply.result) {

package/dist/hooks/useGenerationResources.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { buildGenerationResourcesUrl, responseToResources, } from '../api/generationResources.js';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Backstop timeout for the direct REST fetch. Unlike the postMessage hooks
  * (which inherit the transport's 30s request timeout), this hook talks to the
@@ -32,6 +33,7 @@ const GENERATION_RESOURCES_TIMEOUT_MS = 30_000;
  * // resources[0].strength / .minStrength / .maxStrength / .trainedWords / .clipSkip
  */
 export function useGenerationResources() {
+    useTransportConnection();
     const host = useHostOrigin();
     const { raw } = useBlockToken();
     // In-flight AbortControllers, aborted on unmount so a pending fetch never

package/dist/hooks/useGoodPurchase.js

@@ -6,6 +6,7 @@ import { resolveIdempotencyKey } from '../transport/transport.js';
 import { useBlockToken } from './useBlockToken.js';
 import { useBuzzPurchase } from './useBuzzPurchase.js';
 import { useHostOrigin } from './useHostOrigin.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The consent-gated scope a purchase needs.
  *
@@ -80,6 +81,7 @@ export class GoodPurchaseRefusal extends Error {
  * );
  */
 export function useGoodPurchase() {
+    useTransportConnection();
     const host = useHostOrigin();
     const { raw } = useBlockToken();
     const { openPurchaseModal } = useBuzzPurchase();

package/dist/hooks/useHostOrigin.js

@@ -1,5 +1,6 @@
 import { useSyncExternalStore } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Returns the validated host (parent) origin the block may safely direct-fetch
  * the civitai App Blocks HTTP API against — `undefined` until the transport
@@ -33,6 +34,7 @@ import { getTransport } from '../transport/singleton.js';
  * moment init lands.
  */
 export function useHostOrigin() {
+    useTransportConnection();
     const transport = getTransport();
     const origin = useSyncExternalStore((cb) => transport.subscribe(cb), () => transport.getHostOrigin(), 
     // Server snapshot: no host origin is known before hydration.

package/dist/hooks/useImageUpload.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest, subscribeTyped } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Generous hook-side backstop for {@link BlockImageScanResult} delivery. The
  * host-side scan POLL budget is authoritative and the consuming app applies its
@@ -28,6 +29,7 @@ function isTerminalVerdict(v) {
     return v.status === 'scanned' || v.status === 'blocked';
 }
 export function useImageUpload(options) {
+    useTransportConnection();
     const purpose = options?.purpose;
     const asyncScan = options?.asyncScan === true && purpose !== 'generationSource';
     // Per-instance scan tracking, keyed by imageId. Persists across renders; a

package/dist/hooks/useNestedDocument.js

@@ -1,5 +1,6 @@
 import { useEffect, useState } from 'react';
 import { fetchNestedDocument } from '@civitai/app-sdk/blocks';
+import { useTransportConnection } from './useTransportConnection.js';
 const IDLE = { status: 'idle', srcDoc: null, error: null };
 const LOADING = { status: 'loading', srcDoc: null, error: null };
 /**
@@ -61,6 +62,7 @@ const NESTED_DOCUMENT_TIMEOUT_MS = 30_000;
  * ```
  */
 export function useNestedDocument(options) {
+    useTransportConnection();
     const src = options?.src;
     const baseUrl = options?.baseUrl;
     const [state, setState] = useState(src ? LOADING : IDLE);

package/dist/hooks/usePrepareTrainingDataset.js

@@ -4,6 +4,7 @@ import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The consent-gated scope the training flow requires — `ai:write:budgeted`. The
  * server refuses a dataset request from a token without it (it is the spend
@@ -101,6 +102,7 @@ export class PrepareTrainingDatasetError extends Error {
  * }
  */
 export function usePrepareTrainingDataset() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [error, setError] = useState(null);
     // The consent wait can outlive the component; see `useCreatePostFromApp`.

package/dist/hooks/usePublishGenerationOutputs.js

@@ -2,6 +2,7 @@ import { useCallback } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Publish selected outputs of one of the calling app's OWN generations into bare,
  * real-scanned public `Image` rows via the host-mediated
@@ -28,6 +29,7 @@ import { sendTypedRequest } from '../transport/transport.js';
  * // …store imageIds via useSharedStorage() so the grid can read them back gated.
  */
 export function usePublishGenerationOutputs() {
+    useTransportConnection();
     const publish = useCallback(async (args) => {
         const reply = await sendTypedRequest(getTransport(), {
             type: 'PUBLISH_GENERATION_OUTPUTS',

package/dist/hooks/useRequestConsent.js

@@ -1,6 +1,7 @@
 import { useCallback } from 'react';
 import { sendRequestConsent } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.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
@@ -43,6 +44,7 @@ import { getTransport } from '../transport/singleton.js';
  * requestConsent({ scopes: ['ai:write:budgeted', 'buzz:read:self'] });
  */
 export function useRequestConsent() {
+    useTransportConnection();
     const requestConsent = useCallback((payload) => {
         // Single-sourced with the SDK's own automatic prompt-and-retry
         // (`internal/withConsentRetry.ts`), which posts the identical message. The

package/dist/hooks/useRequestSignIn.js

@@ -1,5 +1,6 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
+import { useTransportConnection } from './useTransportConnection.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
@@ -19,6 +20,7 @@ import { getTransport } from '../transport/singleton.js';
  * if (viewer === null) return <button onClick={() => requestSignIn()}>Sign in</button>;
  */
 export function useRequestSignIn() {
+    useTransportConnection();
     const requestSignIn = useCallback((payload) => {
         getTransport().sendMessage({
             type: 'REQUEST_SIGN_IN',

package/dist/hooks/useResourcePicker.js

@@ -3,6 +3,7 @@ import { throwOnReplyError } from '../internal/replyError.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The most resources ONE multi-select `open({ multiple })` can return — the
  * same cap the generation body puts on `additionalResources`, so a full batch
@@ -86,6 +87,7 @@ const MULTIPLE_RESOURCE_TYPES = new Set(['lora', 'locon', 'dora']);
  * }
  */
 export function useResourcePicker() {
+    useTransportConnection();
     const open = useCallback(async (opts) => {
         if (opts.multiple == null) {
             const { selected } = await sendTypedRequest(getTransport(), {

package/dist/hooks/useRunConfirmedStep.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The host's CLOSED refusal codes for `RUN_CONFIRMED_STEP`, as a runtime list.
  * Mirrors civitai/civitai's `RUN_CONFIRMED_STEP_HOST_ERRORS`.
@@ -209,6 +210,7 @@ export class RunConfirmedStepError extends Error {
  * }
  */
 export function useRunConfirmedStep() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [error, setError] = useState(null);
     // This request can outlive the component by up to ten minutes (the dialog may

package/dist/hooks/useRunTraining.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The host's CLOSED refusal codes for `RUN_TRAINING`, as a runtime list. Mirrors
  * civitai/civitai's `RUN_TRAINING_HOST_ERRORS`.
@@ -145,6 +146,7 @@ export class RunTrainingError extends Error {
  * }
  */
 export function useRunTraining() {
+    useTransportConnection();
     const [pending, setPending] = useState(false);
     const [error, setError] = useState(null);
     // This request can outlive the component by up to ten minutes (the dialog may

package/dist/hooks/useSaveImage.js

@@ -3,6 +3,7 @@ import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
 import { SAVE_BYTES_MAX_BYTES, SAVE_BYTES_TOO_LARGE_ERROR } from '../internal/saveBytes.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Build the wire payload. The ONLY client-side refusal is the cap, so an
  * over-cap buffer is never copied across `postMessage` just to be refused.
@@ -42,6 +43,7 @@ function toWirePayload(input) {
  * await saveImage({ bytes: healedPng, filename: 'healed.png' });
  */
 export function useSaveImage() {
+    useTransportConnection();
     const saveImage = useCallback(async (input) => {
         const payload = toWirePayload(input);
         const reply = await sendTypedRequest(getTransport(), { type: 'SAVE_IMAGE', payload }, 'SAVE_IMAGE_RESULT');

package/dist/hooks/useSharedStorage.js

@@ -3,6 +3,7 @@ import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply, throwOnReplyError } from '../internal/replyError.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { parseSharedStorageRateLimit } from '../transport/validate.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * A shared-storage write the server REFUSED because a per-(viewer, app) budget
  * is empty — thrown by `append`, `update`, `vote`, `unvote`, `withdraw` and
@@ -95,6 +96,7 @@ function rehydrateSharedItem(item) {
     };
 }
 export function useSharedStorage() {
+    useTransportConnection();
     return useMemo(() => {
         const transport = getTransport();
         return {

package/dist/hooks/useTip.js

@@ -5,6 +5,7 @@ import { getTransport } from '../transport/singleton.js';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
 import { resolveIdempotencyKey } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /** The consent-gated scope a tip needs (`social:tip:self`). */
 const TIP_SCOPES = [BLOCK_SCOPES.SOCIAL_TIP_SELF];
 /**
@@ -60,6 +61,7 @@ const TIP_REQUEST_TIMEOUT_MS = 30_000;
  * await tip({ toUserId: 123, amount: 50 }, { idempotencyKey: keyRef.current });
  */
 export function useTip() {
+    useTransportConnection();
     const host = useHostOrigin();
     const { raw } = useBlockToken();
     const [loading, setLoading] = useState(false);

package/dist/hooks/useTipAllowance.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { useHostOrigin } from './useHostOrigin.js';
 import { useBlockToken } from './useBlockToken.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Backstop timeout for the direct REST allowance GET (see {@link useTip} /
  * {@link useGenerationResources} for why direct-fetch hooks need their own bound).
@@ -45,6 +46,7 @@ const HOST_ORIGIN_WAIT_MS = 30_000;
  * // allowance?.remaining — Buzz the viewer may still tip today
  */
 export function useTipAllowance() {
+    useTransportConnection();
     const host = useHostOrigin();
     const { raw } = useBlockToken();
     const [allowance, setAllowance] = useState(null);

package/dist/hooks/useTransportConnection.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Connects the block to its host at MOUNT. Internal — every public hook calls
+ * it, and it is deliberately not exported from the package entry.
+ *
+ * 🔴 WHY EVERY HOOK, AND WHY AT MOUNT. The host waits 10 s for the block's
+ * handshake — `BLOCK_HELLO` on transport construction, `BLOCK_READY` on the
+ * first valid `BLOCK_INIT` — and then shows "This app didn't load in time",
+ * retries twice and gives up (`bootSkeleton` hides the cover, not the
+ * deadline). Both messages are sent by the transport, and the transport is a
+ * lazy singleton: nothing goes out until something calls `getTransport()`.
+ * Request-only hooks (`useBuzzWorkflow`, `useTip`, …) used to call it only
+ * inside their callbacks, so an app whose only SDK use was one of them never
+ * answered the host and was torn down before anyone could click. Calling this
+ * from every public hook makes "uses any SDK hook" imply "is connected".
+ * `test/connectsAtMount.test.tsx` pins it over the whole exported hook set.
+ *
+ * 🔴 IT IS CALLED EVEN WHERE IT IS REDUNDANT, ON PURPOSE. About half the hooks
+ * already reach `getTransport()` at render or in a mount fetch; they call this
+ * anyway so the rule is "every public hook", which needs no case analysis. A
+ * mount fetch can be conditional (`useWildcardPack` skips it for an invalid id),
+ * so "it already fetches on mount" is not a safe reason to leave one out.
+ *
+ * 🔴 WHY AN EFFECT, NOT RENDER. `useBlockContext` constructs during render, and
+ * that is fine for it — but a render-time call throws during SSR (the iframe
+ * transport refuses to construct without a `window`), and these hooks have
+ * always been safe to render on a server. An effect never runs there, and on
+ * the client it runs at mount, long before the host's deadline.
+ *
+ * 🔴 WHY NOT AT MODULE LOAD. `getTransport(opts)` honours only its FIRST call;
+ * dev harnesses and tests inject their allowlist (`installDevTransport()`,
+ * `getTransport({ allowedParentOrigins })`) after importing this package and
+ * before the first hook runs. Constructing on import would win that race and
+ * silently discard their options.
+ *
+ * 🔴 WHY A FAILURE IS LOGGED, NOT THROWN. Construction throws when no parent
+ * allowlist is configured. Before this hook existed, such an app still rendered
+ * and only failed on its first bridge call — and it still does: `getTransport()`
+ * caches nothing on a throw, so that call throws the same error as before. This
+ * hook only ADDS the connection; it must not turn a misconfigured block that
+ * renders into one that crashes on mount.
+ */
+export declare function useTransportConnection(): void;
+//# sourceMappingURL=useTransportConnection.d.ts.map

package/dist/hooks/useTransportConnection.js

@@ -0,0 +1,59 @@
+import { useEffect } from 'react';
+import { claimConnectFailureReport, getTransport } from '../transport/singleton.js';
+/**
+ * Connects the block to its host at MOUNT. Internal — every public hook calls
+ * it, and it is deliberately not exported from the package entry.
+ *
+ * 🔴 WHY EVERY HOOK, AND WHY AT MOUNT. The host waits 10 s for the block's
+ * handshake — `BLOCK_HELLO` on transport construction, `BLOCK_READY` on the
+ * first valid `BLOCK_INIT` — and then shows "This app didn't load in time",
+ * retries twice and gives up (`bootSkeleton` hides the cover, not the
+ * deadline). Both messages are sent by the transport, and the transport is a
+ * lazy singleton: nothing goes out until something calls `getTransport()`.
+ * Request-only hooks (`useBuzzWorkflow`, `useTip`, …) used to call it only
+ * inside their callbacks, so an app whose only SDK use was one of them never
+ * answered the host and was torn down before anyone could click. Calling this
+ * from every public hook makes "uses any SDK hook" imply "is connected".
+ * `test/connectsAtMount.test.tsx` pins it over the whole exported hook set.
+ *
+ * 🔴 IT IS CALLED EVEN WHERE IT IS REDUNDANT, ON PURPOSE. About half the hooks
+ * already reach `getTransport()` at render or in a mount fetch; they call this
+ * anyway so the rule is "every public hook", which needs no case analysis. A
+ * mount fetch can be conditional (`useWildcardPack` skips it for an invalid id),
+ * so "it already fetches on mount" is not a safe reason to leave one out.
+ *
+ * 🔴 WHY AN EFFECT, NOT RENDER. `useBlockContext` constructs during render, and
+ * that is fine for it — but a render-time call throws during SSR (the iframe
+ * transport refuses to construct without a `window`), and these hooks have
+ * always been safe to render on a server. An effect never runs there, and on
+ * the client it runs at mount, long before the host's deadline.
+ *
+ * 🔴 WHY NOT AT MODULE LOAD. `getTransport(opts)` honours only its FIRST call;
+ * dev harnesses and tests inject their allowlist (`installDevTransport()`,
+ * `getTransport({ allowedParentOrigins })`) after importing this package and
+ * before the first hook runs. Constructing on import would win that race and
+ * silently discard their options.
+ *
+ * 🔴 WHY A FAILURE IS LOGGED, NOT THROWN. Construction throws when no parent
+ * allowlist is configured. Before this hook existed, such an app still rendered
+ * and only failed on its first bridge call — and it still does: `getTransport()`
+ * caches nothing on a throw, so that call throws the same error as before. This
+ * hook only ADDS the connection; it must not turn a misconfigured block that
+ * renders into one that crashes on mount.
+ */
+export function useTransportConnection() {
+    useEffect(() => {
+        try {
+            getTransport();
+        }
+        catch (err) {
+            // One console line per transport lifecycle, not one per hook instance:
+            // a block calling ten hooks would otherwise log ten identical errors.
+            if (claimConnectFailureReport()) {
+                // eslint-disable-next-line no-console -- developer-facing diagnostic; the host will time this block out
+                console.error('@civitai/blocks-react: could not connect to the host at mount.', err);
+            }
+        }
+    }, []);
+}
+//# sourceMappingURL=useTransportConnection.js.map

package/dist/hooks/useUploadImageBytes.js

@@ -4,6 +4,7 @@ import { UPLOAD_BYTES_MAX_BYTES, UPLOAD_BYTES_TOO_LARGE_ERROR } from '../interna
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The SDK's own rejection when a reply carries neither an image nor an
  * `error`. A host that predates the `bytes` variant opens its picker instead,
@@ -43,6 +44,7 @@ export const UPLOAD_IMAGE_BYTES_NO_IMAGE_ERROR = 'the host returned no uploaded
  * await createPost({ sources: [{ kind: 'published', imageIds: [image.imageId] }] });
  */
 export function useUploadImageBytes() {
+    useTransportConnection();
     const upload = useCallback(async (bytes, options) => {
         // The ONLY client-side refusal, mirroring `useSaveImage`'s cap pre-check:
         // everything else is forwarded and judged by the host.

package/dist/hooks/useViewer.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * Read the signed-in viewer (id / username / status + optional buzzBudget)
  * through the host-mediated `GET_VIEWER` → `VIEWER_RESULT` bridge. Token-bound:
@@ -29,6 +30,7 @@ import { useRequestSequencer } from './useRequestSequencer.js';
  * return <span>{viewer?.username}</span>;
  */
 export function useViewer() {
+    useTransportConnection();
     const [viewer, setViewer] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);

package/dist/hooks/useWildcardPack.js

@@ -2,6 +2,7 @@ import { useCallback, useEffect, useState } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
 import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * A wildcard-pack import failure. Unlike the buzz bridges' free-text errors, the
  * host returns a DISCRIMINATED code — this error carries it on `.code` so a block
@@ -37,6 +38,7 @@ export class WildcardPackError extends Error {
  * if (error instanceof WildcardPackError && error.code === 'busy') return <RetryLater />;
  */
 export function useWildcardPack(modelVersionId) {
+    useTransportConnection();
     const [pack, setPack] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);

package/dist/hooks/useWorkflowBatch.js

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useBuzzWorkflow } from './useBuzzWorkflow.js';
+import { useTransportConnection } from './useTransportConnection.js';
 /**
  * The most workflows one {@link useWorkflowBatch} may watch.
  *
@@ -145,6 +146,7 @@ function summarise(cells) {
  * if (!result.complete) showRetryCancel(result);
  */
 export function useWorkflowBatch(workflowIds, options) {
+    useTransportConnection();
     validateIds(workflowIds);
     // A private `useBuzzWorkflow()` instance, so the app's own instance's
     // `result`/`status` are not overwritten by 16 cells' updates.

package/dist/transport/iframeTransport.js

@@ -130,6 +130,19 @@ export class IframeTransport {
             this.resolveInit = resolve;
             this.rejectInit = reject;
         });
+        // 🔴 THE TRANSPORT HANDLES ITS OWN INIT TIMEOUT. Every hook connects the
+        // transport at mount, and most blocks never call `waitForInit()`, so without
+        // a handler here the 10s timeout is an UNHANDLED rejection. That fails the
+        // Vitest run of any block app whose tests mount a hook with no host. This
+        // handler makes the rejection handled and keeps the diagnostic (it names the
+        // configured and observed origins) on the console as a warning. It is a
+        // separate branch of the promise: `waitForInit()` still returns
+        // `initPromise` itself, so its callers still receive the rejection.
+        // Pinned by `test/initTimeoutUnhandled.test.tsx`.
+        this.initPromise.catch((err) => {
+            // eslint-disable-next-line no-console -- developer-facing diagnostic; the host shows its own fallback
+            console.warn(err instanceof Error ? err.message : err);
+        });
         this.initTimeoutId = setTimeout(() => {
             if (!this.initResolved) {
                 this.initResolved = true;

package/dist/transport/singleton.d.ts

@@ -1,5 +1,11 @@
 import { type DetectOptions } from './detector.js';
 import type { BlockTransport } from './transport.js';
+/**
+ * Returns true the FIRST time it is called in this transport lifecycle, false
+ * after. Internal — used by `useTransportConnection` to log a failed connect
+ * once instead of once per hook instance.
+ */
+export declare function claimConnectFailureReport(): boolean;
 /**
  * Returns the process-wide transport, instantiating it on first call.
  *

package/dist/transport/singleton.js

@@ -1,5 +1,24 @@
 import { BlockTransportDetector } from './detector.js';
 let cached = null;
+/**
+ * Whether a failed MOUNT-TIME connect (`useTransportConnection`) has already been
+ * logged. Lives here, not in the hook, so `__resetTransport()` clears it with the
+ * transport it describes: one log per transport lifecycle — once per page in
+ * production, once per reset in tests. A latch that outlived the reset would
+ * silence every misconfigured case in a test worker after the first.
+ */
+let connectFailureReported = false;
+/**
+ * Returns true the FIRST time it is called in this transport lifecycle, false
+ * after. Internal — used by `useTransportConnection` to log a failed connect
+ * once instead of once per hook instance.
+ */
+export function claimConnectFailureReport() {
+    if (connectFailureReported)
+        return false;
+    connectFailureReported = true;
+    return true;
+}
 /**
  * Returns the process-wide transport, instantiating it on first call.
  *
@@ -24,5 +43,6 @@ export function __resetTransport() {
     const disposable = cached;
     disposable?.dispose?.();
     cached = null;
+    connectFailureReported = false;
 }
 //# sourceMappingURL=singleton.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.72.0",
+  "version": "0.72.2",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -58,7 +58,7 @@
     "typescript": "^5.9.2",
     "vite": "^8.0.14",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.67.0"
+    "@civitai/app-sdk": "^0.68.0"
   },
   "publishConfig": {
     "access": "public"