@civitai/blocks-react 0.71.0 → 0.72.2

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/index.d.ts

@@ -75,6 +75,8 @@ export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAININ
 export type { UsePrepareTrainingDataset, BlockPrepareTrainingDatasetHostError, BlockTrainingDatasetItem, BlockTrainingDatasetResult, BlockTrainingRejectionReason, } from './hooks/usePrepareTrainingDataset.js';
 export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
 export type { UseRunTraining, QuotedTrainingBody, RunTrainingErrorCode, BlockRunTrainingHostError, BlockTrainingQuote, WorkflowBodyTraining, } from './hooks/useRunTraining.js';
+export { useRunConfirmedStep, RunConfirmedStepError, RUN_CONFIRMED_STEP_ERROR_CODES, isRunConfirmedStepErrorCode, isStepQuoteId, } from './hooks/useRunConfirmedStep.js';
+export type { UseRunConfirmedStep, QuotedStepBody, RunConfirmedStepErrorCode, BlockRunConfirmedStepHostError, BlockStepQuote, WorkflowBodyPassThroughStep, } from './hooks/useRunConfirmedStep.js';
 export type { BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, AppWorkflowsParams, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, } from '@civitai/app-sdk/blocks';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export type { UseCheckpointPicker } from './hooks/useCheckpointPicker.js';

package/dist/index.js

@@ -63,6 +63,7 @@ export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_COD
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
 export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
 export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
+export { useRunConfirmedStep, RunConfirmedStepError, RUN_CONFIRMED_STEP_ERROR_CODES, isRunConfirmedStepErrorCode, isStepQuoteId, } from './hooks/useRunConfirmedStep.js';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';

package/dist/internal/hostSurface.d.ts

@@ -0,0 +1,37 @@
+/**
+ * hostSurface.ts — which production host a dev host stands in for.
+ *
+ * civitai.com has two hosts. A full-page app (`app.page`) is mounted by the page
+ * host; a block in a `model.*` slot is mounted by the model-slot host. They
+ * answer a few messages differently, so a dev host has to know which of the two
+ * it is imitating. Both dev hosts (`createMockHost`, `createLiveHost`) read it
+ * from the one place they already model it: the `BLOCK_INIT` context.
+ */
+import type { BlockContext } from '@civitai/app-sdk/blocks';
+/** The slot id of a full-page app. */
+export declare const PAGE_SLOT_ID = "app.page";
+/**
+ * Is this dev host standing in for the PAGE host?
+ *
+ * `context` is the `options.context` the harness passed. `undefined` is a page:
+ * both dev hosts default to a complete page context when none is given.
+ *
+ * Keyed on the slot id alone, not on `isPageSlotContext`. Production picks the
+ * host by the slot the app is mounted in, so an incomplete `{ slotId:
+ * 'app.page' }` context is still a page.
+ */
+export declare function emulatesPageHost(context: BlockContext | undefined): boolean;
+/**
+ * The `error` the page host answers `SET_USER_CHECKPOINT` with, verbatim.
+ *
+ * A page token is bound to no model, and the server writes a checkpoint override
+ * into the settings row of a model-bound install. The page host therefore
+ * refuses every such request with `USER_CHECKPOINT_SET { requestId, ok: false,
+ * error }`, whatever `versionId` was sent, and makes no server call.
+ *
+ * Read from `civitai/civitai` `main` at `c1fffa4d1f`
+ * (`src/components/AppBlocks/PageBlockHost.tsx`). It is host-authored text: show
+ * it or log it, do not branch on it.
+ */
+export declare const PAGE_CHECKPOINT_PERSIST_ERROR = "page blocks cannot persist a checkpoint override (no model binding)";
+//# sourceMappingURL=hostSurface.d.ts.map

package/dist/internal/hostSurface.js

@@ -0,0 +1,38 @@
+/**
+ * hostSurface.ts — which production host a dev host stands in for.
+ *
+ * civitai.com has two hosts. A full-page app (`app.page`) is mounted by the page
+ * host; a block in a `model.*` slot is mounted by the model-slot host. They
+ * answer a few messages differently, so a dev host has to know which of the two
+ * it is imitating. Both dev hosts (`createMockHost`, `createLiveHost`) read it
+ * from the one place they already model it: the `BLOCK_INIT` context.
+ */
+/** The slot id of a full-page app. */
+export const PAGE_SLOT_ID = 'app.page';
+/**
+ * Is this dev host standing in for the PAGE host?
+ *
+ * `context` is the `options.context` the harness passed. `undefined` is a page:
+ * both dev hosts default to a complete page context when none is given.
+ *
+ * Keyed on the slot id alone, not on `isPageSlotContext`. Production picks the
+ * host by the slot the app is mounted in, so an incomplete `{ slotId:
+ * 'app.page' }` context is still a page.
+ */
+export function emulatesPageHost(context) {
+    return (context?.slotId ?? PAGE_SLOT_ID) === PAGE_SLOT_ID;
+}
+/**
+ * The `error` the page host answers `SET_USER_CHECKPOINT` with, verbatim.
+ *
+ * A page token is bound to no model, and the server writes a checkpoint override
+ * into the settings row of a model-bound install. The page host therefore
+ * refuses every such request with `USER_CHECKPOINT_SET { requestId, ok: false,
+ * error }`, whatever `versionId` was sent, and makes no server call.
+ *
+ * Read from `civitai/civitai` `main` at `c1fffa4d1f`
+ * (`src/components/AppBlocks/PageBlockHost.tsx`). It is host-authored text: show
+ * it or log it, do not branch on it.
+ */
+export const PAGE_CHECKPOINT_PERSIST_ERROR = 'page blocks cannot persist a checkpoint override (no model binding)';
+//# sourceMappingURL=hostSurface.js.map

package/dist/internal/liveHost.d.ts

@@ -47,7 +47,7 @@
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
  * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 48, of which 10 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 49, of which 11 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -70,11 +70,12 @@
  * and row budgets enforced per (app, user) — with the REAL ceilings, so a
  * write this host accepts is one production would accept.
  *
- * SET_USER_CHECKPOINT (Phase 4): FORWARDED (faithful) to the block-token
- * `blocks.updateUserSettings` mutation — never fabricated. The default page
- * setup mints a PAGE token which lacks `ctx.modelId`, so the backend returns the
- * honest error "block token lacks modelId context"; that real outcome is
- * surfaced to the block. With a model-slot token it persists for real.
+ * SET_USER_CHECKPOINT (Phase 4): answered as the production host for the slot
+ * would. On a PAGE context (the default; dev-token mints page tokens) it is
+ * refused locally with the page host's own reply — `ok: false` and the same
+ * error text — and no backend call, because the page host makes none. On a
+ * model-slot context it is FORWARDED to the block-token
+ * `blocks.updateUserSettings` mutation, never fabricated.
  *
  * SHARED STORAGE (#386): the live host SERVES all TEN `SHARED_*` bridges —
  * `apps.shared.{list,get,getCount,getCounts,append,update,vote,unvote,withdraw,
@@ -113,6 +114,10 @@
  *   • RUN_TRAINING — the same dev-token refusal, plus the host-chrome consent
  *     dialog a run is confirmed in, which this harness does not have. Replies
  *     with a refusal.
+ *   • RUN_CONFIRMED_STEP — the server refuses a confirmed step from a dev token
+ *     and the estimate never returns a `stepQuote` for one, and the price is
+ *     confirmed in host chrome this harness does not have. Replies with a
+ *     refusal.
  *   • PUBLISH_GENERATION_OUTPUTS — publishing requires the viewer's signed-in
  *     civitai.com session, which the local harness does not have; test
  *     publishing against the mock host — `createMockHost` or `Harness` from
@@ -217,6 +222,10 @@ export interface LiveHostOptions {
  * string so the two cannot drift.
  */
 export declare const TRAINING_UNSUPPORTED_ERROR = "training is not supported in dev:live \u2014 use dev:mock";
+/**
+ * The reply `RUN_CONFIRMED_STEP` gets in dev:live — see its handler.
+ */
+export declare const CONFIRMED_STEP_UNSUPPORTED_ERROR = "confirmed steps are not supported in dev:live \u2014 use dev:mock";
 /**
  * Decoded payload of a block-token JWT (the claims `BlockTokenService.sign`
  * stamps — see civitai `block-token.service.ts`). Everything is optional/unknown