@civitai/blocks-react 0.77.0 → 0.78.0

package/README.md

@@ -1229,6 +1229,67 @@ if (error instanceof WildcardPackError && error.code === 'busy') void refetch();
 if (!loading && pack) console.log(Object.keys(pack.lists));
 ```
 
+### `useResourceFile(modelVersionId, fileId?)`
+
+Read a resource file's parsed JSON — for a workflow, its graphs — by model
+version. The host resolves, fetches, unzips and parses the file **in the
+viewer's own page session**, enforcing the real download gates, so the iframe
+never sees the session, a signed URL or the raw bytes. No block scope is needed.
+Returns `{ file, loading, error, refetch }`.
+
+- `file.meta` names what was served (`modelId`, `modelVersionId`, `fileId`,
+  `fileName`, `modelName`, `versionName`, `creatorUsername`).
+- `file.entries` holds one `{ path, format, graph }` per JSON document: one for a
+  plain `.json`, several for a `.zip` (non-JSON entries are skipped). `format`
+  is `'ui'` (a `nodes` array), `'api'` (every top-level value has `class_type`
+  and `inputs`) or `'unknown'`; check it before treating `graph` as a graph.
+  `file.truncated` is `true` when an entry was dropped: past 20 entries, over
+  the 4 MB per-entry or 16 MB total cap, unreadable, or not valid JSON.
+- Pass `fileId` to pin one file of a multi-file version. Without it the host
+  picks one.
+- Changing `modelVersionId` or `fileId` resets `file` and `error` to `null`
+  before the new fetch, so a file never shows for ids it does not belong to.
+- The request waits up to 120 s, because the host downloads and unzips the file.
+
+On failure `error` is a `ResourceFileError` whose `code` is one of a closed set:
+
+| `code` | Means | Retry? |
+|---|---|---|
+| `not-found` | No such version or file, not a workflow, or not downloadable for free (see below) | No |
+| `forbidden` | Above the viewer's maturity ceiling on this site, or the app is in review preview | No |
+| `unauthorized` | The viewer is signed out | No |
+| `too-large` | Over 32 MB, or every entry was over a size cap (4 MB per entry, 16 MB in total) | No |
+| `parse-failed` | Not a `.json`/`.zip`, corrupt, or no valid JSON — **or** the host's catch-all: a network error, a failed fetch, no answer within its 110 s deadline, a transient storage failure, or another server error | Once, maybe: it can be transient |
+| `busy` | Three fetches already in flight in this tab | Yes |
+| `rate-limited` | The viewer's 30-a-minute budget is spent | Yes, later |
+
+🔴 **Full-page app hosts only — not the model-page slot, not `dev:live`.** The
+model-page slot does not answer it (the request times out), and `dev:live`
+replies `parse-failed`. Develop against `dev:mock`: `createMockHost` takes a
+`resourceFile` (the canned reply) and a `resourceFileError` (force a code);
+`setScenario({ resourceFileError: undefined })` clears the forced error.
+
+🔴 **Only free, public versions are served.** An unpublished draft (the owner's
+included) and an early-access or paid version answer `not-found` — even for a
+viewer who bought it. Only the owner gets their own published early-access
+version. A POI model, or a model or version whose availability is not `Public`
+or `Unsearchable` (e.g. `Private`), is refused to everyone but the owner,
+moderators included.
+
+```tsx
+const { file, loading, error, refetch } = useResourceFile(modelVersionId);
+// Retry a retryable code from an effect, after a delay — never during render.
+const retryable =
+  error instanceof ResourceFileError && (error.code === 'busy' || error.code === 'rate-limited');
+useEffect(() => {
+  if (!retryable) return;
+  const t = setTimeout(refetch, 2_000);
+  return () => clearTimeout(t);
+}, [retryable, refetch]);
+const graphs = file?.entries.filter((e) => e.format !== 'unknown') ?? [];
+if (!loading && file) console.log(file.meta.fileName, graphs.length, file.truncated);
+```
+
 ### `useCollectionFollow()`
 
 Follow / unfollow a collection **for the viewer**, host-mediated over
@@ -3830,6 +3891,7 @@ Runnable, minimal blocks — one per feature, each with its own README:
 
 | `@civitai/blocks-react` | pairs with `@civitai/app-sdk` | adds |
 |---|---|---|
+| `0.78.x` | `^0.79.0` | `useResourceFile()` (`GET_RESOURCE_FILE`). Its types (`BlockResourceFile` and friends) come from the SDK's `0.79.0`; the hook imports no SDK value, so the declared peer floor is unchanged. |
 | `0.50.x` | `^0.40.0` | `useCreatePostFromApp()` (`CREATE_POST_FROM_APP`) + the `posts:write:self` scope. Pairing `0.50.x` with an SDK below `0.40.0` fails at `tsc` with `Cannot find name 'BlockCreatePostHostError'`, not at install. |
 | `0.48.x` | `^0.38.0` | `useCollectionFollow()` + `<FollowButton>` / `<TipButton>` (`SET_COLLECTION_FOLLOW`). Pairing `0.48.x` with an SDK below `0.38.0` fails at `tsc` with `Cannot find name 'BlockCollectionFollowErrorCode'`, not at install — the floor those releases declared was deliberately wide (#206 — a per-minor floor forced a major on consumers). |
 | `0.36.x` | `^0.27.0` | auto-installs the SDK's opaque-origin web-storage shim (`@civitai/app-sdk/safe-storage`) on import |

package/dist/hooks/useResourceFile.d.ts

@@ -0,0 +1,71 @@
+import type { BlockResourceFile, BlockResourceFileEntry, BlockResourceFileEntryFormat, BlockResourceFileErrorCode, BlockResourceFileMeta } from '@civitai/app-sdk/blocks';
+export type { BlockResourceFile, BlockResourceFileEntry, BlockResourceFileEntryFormat, BlockResourceFileErrorCode, BlockResourceFileMeta, };
+/**
+ * A resource-file read failure. The host returns one code from a CLOSED set, and
+ * this error carries it on `.code` so a block can branch on the exact reason:
+ * `busy` and `rate-limited` are retryable; `not-found`, `forbidden`,
+ * `unauthorized`, `too-large` and `parse-failed` are terminal. `.message` equals
+ * the code.
+ */
+export declare class ResourceFileError extends Error {
+    readonly code: BlockResourceFileErrorCode;
+    constructor(code: BlockResourceFileErrorCode);
+}
+/**
+ * What {@link useResourceFile} returns.
+ */
+export interface UseResourceFile {
+    /**
+     * The parsed file for the CURRENT `modelVersionId` / `fileId`, or `null` until
+     * it loads. Reset to `null` the moment either id changes, so a file is never
+     * shown for an id it does not belong to. A `refetch()` of the same ids keeps it
+     * while reloading.
+     */
+    file: BlockResourceFile | null;
+    /** `true` while a fetch (initial or `refetch`) is in flight. */
+    loading: boolean;
+    /**
+     * The last fetch's failure as a {@link ResourceFileError} (`.code` is the
+     * reason), or a plain `Error` (a `RequestTimeoutError`) when the host never
+     * answered. Cleared at the start of the next fetch, and when either id changes.
+     */
+    error: Error | null;
+    /** Re-request the file. */
+    refetch: () => void;
+}
+/**
+ * Read a resource file's parsed JSON (for a workflow: its graphs) by model-version
+ * id, through the host-mediated `GET_RESOURCE_FILE` → `RESOURCE_FILE_RESULT`
+ * bridge. TOKEN-INDEPENDENT (no block scope): the host resolves, fetches, unzips
+ * and parses the file in the viewer's own page session, enforcing the real
+ * download gates, and returns only the parsed JSON. The iframe never sees the
+ * session, the signed URL or the raw bytes.
+ *
+ * Pass `fileId` to pin one file of a multi-file version; without it the host
+ * picks one. Only free, public versions are served: an unpublished draft or an
+ * early-access / paid version answers `not-found`, even for a viewer who bought
+ * it. Full-page app hosts only — the model-page slot does not answer it, and
+ * `dev:live` replies `parse-failed`; use `dev:mock` to develop against it.
+ *
+ * Fetches on mount and whenever `modelVersionId` or `fileId` changes; a change
+ * clears `file` and `error` first. A non-positive or non-integer
+ * `modelVersionId` (or `fileId`, when given) fetches nothing. The request waits
+ * up to 120 s (`RESOURCE_FILE_REQUEST_TIMEOUT_MS`), since the host downloads and
+ * unzips the file; a host that never answers surfaces as a `RequestTimeoutError`
+ * after that. Only the LATEST request may write state: a superseded or
+ * post-unmount reply is dropped (#392).
+ *
+ * @example
+ * const { file, loading, error, refetch } = useResourceFile(modelVersionId);
+ * // Retry a retryable code from an effect, after a delay — never during render.
+ * const retryable =
+ *   error instanceof ResourceFileError && (error.code === 'busy' || error.code === 'rate-limited');
+ * useEffect(() => {
+ *   if (!retryable) return;
+ *   const t = setTimeout(refetch, 2_000);
+ *   return () => clearTimeout(t);
+ * }, [retryable, refetch]);
+ * const graphs = file?.entries.filter((e) => e.format !== 'unknown') ?? [];
+ */
+export declare function useResourceFile(modelVersionId: number, fileId?: number): UseResourceFile;
+//# sourceMappingURL=useResourceFile.d.ts.map

package/dist/hooks/useResourceFile.js

@@ -0,0 +1,113 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { RESOURCE_FILE_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
+import { useTransportConnection } from './useTransportConnection.js';
+/**
+ * A resource-file read failure. The host returns one code from a CLOSED set, and
+ * this error carries it on `.code` so a block can branch on the exact reason:
+ * `busy` and `rate-limited` are retryable; `not-found`, `forbidden`,
+ * `unauthorized`, `too-large` and `parse-failed` are terminal. `.message` equals
+ * the code.
+ */
+export class ResourceFileError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.name = 'ResourceFileError';
+        this.code = code;
+    }
+}
+/**
+ * Read a resource file's parsed JSON (for a workflow: its graphs) by model-version
+ * id, through the host-mediated `GET_RESOURCE_FILE` → `RESOURCE_FILE_RESULT`
+ * bridge. TOKEN-INDEPENDENT (no block scope): the host resolves, fetches, unzips
+ * and parses the file in the viewer's own page session, enforcing the real
+ * download gates, and returns only the parsed JSON. The iframe never sees the
+ * session, the signed URL or the raw bytes.
+ *
+ * Pass `fileId` to pin one file of a multi-file version; without it the host
+ * picks one. Only free, public versions are served: an unpublished draft or an
+ * early-access / paid version answers `not-found`, even for a viewer who bought
+ * it. Full-page app hosts only — the model-page slot does not answer it, and
+ * `dev:live` replies `parse-failed`; use `dev:mock` to develop against it.
+ *
+ * Fetches on mount and whenever `modelVersionId` or `fileId` changes; a change
+ * clears `file` and `error` first. A non-positive or non-integer
+ * `modelVersionId` (or `fileId`, when given) fetches nothing. The request waits
+ * up to 120 s (`RESOURCE_FILE_REQUEST_TIMEOUT_MS`), since the host downloads and
+ * unzips the file; a host that never answers surfaces as a `RequestTimeoutError`
+ * after that. Only the LATEST request may write state: a superseded or
+ * post-unmount reply is dropped (#392).
+ *
+ * @example
+ * const { file, loading, error, refetch } = useResourceFile(modelVersionId);
+ * // Retry a retryable code from an effect, after a delay — never during render.
+ * const retryable =
+ *   error instanceof ResourceFileError && (error.code === 'busy' || error.code === 'rate-limited');
+ * useEffect(() => {
+ *   if (!retryable) return;
+ *   const t = setTimeout(refetch, 2_000);
+ *   return () => clearTimeout(t);
+ * }, [retryable, refetch]);
+ * const graphs = file?.entries.filter((e) => e.format !== 'unknown') ?? [];
+ */
+export function useResourceFile(modelVersionId, fileId) {
+    useTransportConnection();
+    const [file, setFile] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const seq = useRequestSequencer();
+    // The ids the current `file` / `error` belong to. A fetch for different ids
+    // clears both first, so `{ file: A, error: B }` can never be returned.
+    const key = `${modelVersionId}|${fileId ?? ''}`;
+    const keyRef = useRef(null);
+    const isPositiveInt = (n) => Number.isInteger(n) && n > 0;
+    const valid = isPositiveInt(modelVersionId) && (fileId === undefined || isPositiveInt(fileId));
+    const refetch = useCallback(() => {
+        // `begin()` runs BEFORE the validity gate, as in `useWildcardPack`: moving to
+        // an invalid id must also supersede an in-flight request for the old one.
+        const token = seq.begin();
+        if (keyRef.current !== key) {
+            keyRef.current = key;
+            setFile(null);
+            setError(null);
+        }
+        if (!valid) {
+            setLoading(false);
+            return;
+        }
+        setLoading(true);
+        setError(null);
+        sendTypedRequest(getTransport(), {
+            type: 'GET_RESOURCE_FILE',
+            payload: fileId === undefined ? { modelVersionId } : { modelVersionId, fileId },
+        }, 'RESOURCE_FILE_RESULT', { timeoutMs: RESOURCE_FILE_REQUEST_TIMEOUT_MS })
+            .then((result) => {
+            if (!seq.isCurrent(token))
+                return;
+            if (result.error || !result.file) {
+                // `??`, as in `useWildcardPack`: `isValidResourceFileResult` admits only
+                // the closed code set, so `error: ''` never reaches here. The fallback
+                // covers only a reply with neither field, which the validator drops too.
+                setError(new ResourceFileError(result.error ?? 'parse-failed'));
+                setLoading(false);
+                return;
+            }
+            setFile(result.file);
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (!seq.isCurrent(token))
+                return;
+            setError(err instanceof Error ? err : new Error(String(err)));
+            setLoading(false);
+        });
+    }, [valid, key, modelVersionId, fileId, seq]);
+    useEffect(() => {
+        refetch();
+    }, [refetch]);
+    return { file, loading, error, refetch };
+}
+//# sourceMappingURL=useResourceFile.js.map

package/dist/index.d.ts

@@ -57,6 +57,8 @@ export { useDailyCompensation } from './hooks/useDailyCompensation.js';
 export type { UseDailyCompensation } from './hooks/useDailyCompensation.js';
 export { useWildcardPack, WildcardPackError } from './hooks/useWildcardPack.js';
 export type { UseWildcardPack } from './hooks/useWildcardPack.js';
+export { useResourceFile, ResourceFileError } from './hooks/useResourceFile.js';
+export type { UseResourceFile } from './hooks/useResourceFile.js';
 export { useAppWorkflows } from './hooks/useAppWorkflows.js';
 export type { UseAppWorkflows } from './hooks/useAppWorkflows.js';
 export { usePublishGenerationOutputs } from './hooks/usePublishGenerationOutputs.js';
@@ -77,7 +79,7 @@ export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTraini
 export type { UseRunTraining, QuotedTrainingBody, RunTrainingErrorCode, BlockRunTrainingHostError, BlockTrainingQuote, BlockTrainingDatasetItem, 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, BlockAppReaction, BlockStoredReaction, BlockReactionEntityType, BlockEntityReactionErrorCode, BlockReactionCounts, BlockEntityReactionState, BlockEntityReactionResult, BlockEntityReactionsResult, } from '@civitai/app-sdk/blocks';
+export type { BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockWildcardPack, BlockWildcardPackErrorCode, BlockResourceFile, BlockResourceFileEntry, BlockResourceFileEntryFormat, BlockResourceFileErrorCode, BlockResourceFileMeta, AppWorkflow, AppWorkflowImage, AppWorkflowsParams, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockAppReaction, BlockStoredReaction, BlockReactionEntityType, BlockEntityReactionErrorCode, BlockReactionCounts, BlockEntityReactionState, BlockEntityReactionResult, BlockEntityReactionsResult, } from '@civitai/app-sdk/blocks';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export type { UseCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';

package/dist/index.js

@@ -46,6 +46,7 @@ export { useBuzzTransactions } from './hooks/useBuzzTransactions.js';
 export { useBuzzAccounts } from './hooks/useBuzzAccounts.js';
 export { useDailyCompensation } from './hooks/useDailyCompensation.js';
 export { useWildcardPack, WildcardPackError } from './hooks/useWildcardPack.js';
+export { useResourceFile, ResourceFileError } from './hooks/useResourceFile.js';
 export { useAppWorkflows } from './hooks/useAppWorkflows.js';
 export { usePublishGenerationOutputs } from './hooks/usePublishGenerationOutputs.js';
 export { useGatedImages } from './hooks/useGatedImages.js';

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 .... 52, of which 14 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 53, of which 15 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -127,6 +127,9 @@
  *     `publishError` options. Replies with a refusal.
  *   • GET_WILDCARD_PACK — needs the session-authed resolve plus the in-tab
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
+ *   • GET_RESOURCE_FILE — the same session-authed resolve plus in-tab
+ *     fetch/unzip/parse, and only full-page app hosts answer it. Replies
+ *     `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte
  *     pipeline. Replies DISMISSED (the hook resolves `null`).
  *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted

package/dist/internal/liveHost.js

@@ -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 .... 52, of which 14 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 53, of which 15 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -127,6 +127,9 @@
  *     `publishError` options. Replies with a refusal.
  *   • GET_WILDCARD_PACK — needs the session-authed resolve plus the in-tab
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
+ *   • GET_RESOURCE_FILE — the same session-authed resolve plus in-tab
+ *     fetch/unzip/parse, and only full-page app hosts answer it. Replies
+ *     `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte
  *     pipeline. Replies DISMISSED (the hook resolves `null`).
  *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted
@@ -1207,6 +1210,26 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'GET_RESOURCE_FILE': {
+                        // UNSUPPORTED in live v1, for the same reason as GET_WILDCARD_PACK
+                        // directly above: the real host resolves the file through a
+                        // SESSION-authed procedure and fetches + unzips + parses it in the
+                        // viewer's page tab. A liveHost holds a BLOCK token, not a session,
+                        // so it cannot resolve the file. Reply with an honest `parse-failed`
+                        // (never a fabricated file) so the hook surfaces a typed error rather
+                        // than hanging. The closed error set has no "unsupported" code, and
+                        // `parse-failed` is the one the wildcard refusal already uses.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('resource-file', 'GET_RESOURCE_FILE is not supported in dev:live (it needs the session-authed ' +
+                            'resolve + in-tab fetch and unzip, on a full-page app host). Replying ' +
+                            '`parse-failed`. Use dev:mock to exercise the resource-file path.');
+                        dispatchToBlock({
+                            type: 'RESOURCE_FILE_RESULT',
+                            payload: { requestId, error: 'parse-failed' },
+                        });
+                        return;
+                    }
                     case 'QUERY_APP_WORKFLOWS': {
                         // App generator SUBQUEUE read via the token-bound
                         // `blocks.queryAppWorkflows` MUTATION (POST). params (cursor/limit) are

package/dist/internal/mockHost.d.ts

@@ -37,7 +37,7 @@
  * called). Only the postMessage bridge round-trips are exercised. Never import
  * this from production code.
  */
-import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockModel3dOutput, type BlockPublishedModel, type BlockRunConfirmedStepHostError, type BlockGatedImage, type BlockPickedImageInfo, type BlockCollectionFollowErrorCode, type BlockEntityReactionErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockRunTrainingHostError, type BlockTrainingDataImage, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
+import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type BlockResourceFile, type BlockResourceFileErrorCode, type AppWorkflow, type BlockModel3dOutput, type BlockPublishedModel, type BlockRunConfirmedStepHostError, type BlockGatedImage, type BlockPickedImageInfo, type BlockCollectionFollowErrorCode, type BlockEntityReactionErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockRunTrainingHostError, type BlockTrainingDataImage, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
 import { type MockMediaUploads } from './mediaUploadBytes.js';
 import { type MockWorkflowQuoteFailure } from './mockWorkflowGraph.js';
 import { type MockReactionSeed } from './mockHostReactions.js';
@@ -931,6 +931,21 @@ export interface MockHostOptions {
      * returned. Live-tunable via {@link MockHost.setScenario}.
      */
     wildcardPackError?: BlockWildcardPackErrorCode;
+    /**
+     * The parsed file returned from `GET_RESOURCE_FILE` (what `useResourceFile`
+     * reads). Absent → {@link DEFAULT_RESOURCE_FILE}, one UI-format graph. Ignored
+     * when {@link resourceFileError} is set. The mock returns it whatever
+     * `modelVersionId` / `fileId` the block asks for.
+     */
+    resourceFile?: BlockResourceFile;
+    /**
+     * Force `GET_RESOURCE_FILE` to reply with this code from the CLOSED set
+     * (`not-found` | `forbidden` | `unauthorized` | `too-large` | `parse-failed` |
+     * `busy` | `rate-limited`) instead of a file — exercises `useResourceFile`'s
+     * error UI. Absent → a file is returned. Live-tunable via
+     * {@link MockHost.setScenario}, where passing the key as `undefined` clears it.
+     */
+    resourceFileError?: BlockResourceFileErrorCode;
     /**
      * Force `SET_COLLECTION_FOLLOW` to reply with an `error` instead of writing —
      * exercises `useCollectionFollow`'s refusal handling. Pass a
@@ -1424,7 +1439,7 @@ export interface MockHostOptions {
  * {@link MockHost.setTheme}, which pushes a real `THEME_CHANGE` — the mock of
  * the viewer toggling dark mode with the block already mounted.)
  */
-export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedMultiPicks' | 'cannedImagePicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'reactionStates' | 'reactionError' | 'createPostResult' | 'createPostError' | 'cannedTrainingDataUpload' | 'trainingDataNotUploadedHere' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'runConfirmedStepError' | 'runConfirmedStepCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes' | 'saveImageError' | 'uploadImageBytesResult' | 'uploadImageBytesError' | 'cannedMediaUploads' | 'mediaUploadError'>;
+export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedMultiPicks' | 'cannedImagePicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'resourceFile' | 'resourceFileError' | 'collectionFollowError' | 'reactionStates' | 'reactionError' | 'createPostResult' | 'createPostError' | 'cannedTrainingDataUpload' | 'trainingDataNotUploadedHere' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'runConfirmedStepError' | 'runConfirmedStepCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes' | 'saveImageError' | 'uploadImageBytesResult' | 'uploadImageBytesError' | 'cannedMediaUploads' | 'mediaUploadError'>;
 /** Runtime Buzz-balance handle exposed on {@link MockHost.buzz}. */
 export interface MockBuzzHandle {
     /** Current simulated balance, or `undefined` when balance isn't simulated. */
@@ -1440,6 +1455,7 @@ export interface MockBuzzHandle {
  *
  * After install, a harness UI can drive scenarios live:
  *  - `setScenario(patch)` — merge new generation/buzz/storage/failMode controls.
+ *    `setScenario({ resourceFileError: undefined })` clears a forced resource-file error.
  *  - `setTheme('light' | 'dark')` — flip the site theme and push `THEME_CHANGE`.
  *  - `buzz.setBalance(n)` / `buzz.getBalance()` — flip the simulated wallet.
  *

package/dist/internal/mockHost.js

@@ -752,6 +752,38 @@ const DEFAULT_WILDCARD_PACK = {
     truncatedLists: [],
     maturity: { browsingLevel: SFW_LEVELS, sfwOnly: true },
 };
+/**
+ * Default file reported on `GET_RESOURCE_FILE`: one plain `.json` workflow in the
+ * ComfyUI UI format (a `nodes` array), so a block renders a graph out of the box.
+ */
+const DEFAULT_RESOURCE_FILE = {
+    meta: {
+        modelId: 618700,
+        modelVersionId: 691700,
+        fileId: 591700,
+        fileName: 'sample-workflow.json',
+        modelName: 'Sample Workflow',
+        versionName: 'v1.0',
+        creatorUsername: 'creator',
+    },
+    entries: [
+        {
+            path: 'sample-workflow.json',
+            format: 'ui',
+            graph: {
+                last_node_id: 2,
+                last_link_id: 1,
+                nodes: [
+                    { id: 1, type: 'CheckpointLoaderSimple', inputs: [], outputs: [{ name: 'MODEL', links: [1] }] },
+                    { id: 2, type: 'KSampler', inputs: [{ name: 'model', link: 1 }], outputs: [] },
+                ],
+                links: [[1, 1, 0, 2, 0, 'MODEL']],
+                version: 0.4,
+            },
+        },
+    ],
+    truncated: false,
+};
 /**
  * Default app generator SUBQUEUE page reported on `QUERY_APP_WORKFLOWS`. A small
  * mixed-status list (a done gen with two images, one still processing) so a block
@@ -1136,6 +1168,9 @@ export function createMockHost(options = {}) {
     // Wildcard-pack bridge data + forced discriminated-error knob.
     let wildcardPack = options.wildcardPack ?? DEFAULT_WILDCARD_PACK;
     let wildcardPackError = options.wildcardPackError;
+    // Resource-file bridge data + forced closed-set error knob.
+    let resourceFile = options.resourceFile ?? DEFAULT_RESOURCE_FILE;
+    let resourceFileError = options.resourceFileError;
     // Collection-follow bridge.
     //
     // 🔴 THERE IS DELIBERATELY NO FOLLOW-STATE MAP HERE, and an earlier version's
@@ -2616,6 +2651,25 @@ export function createMockHost(options = {}) {
                         });
                         return;
                     }
+                    case 'GET_RESOURCE_FILE': {
+                        // Token-INDEPENDENT read, like GET_WILDCARD_PACK. A forced error
+                        // replies with the closed-set code (never free text), as the real
+                        // host does. The canned file is returned for any version / file id.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        if (resourceFileError !== undefined) {
+                            dispatchToBlock({
+                                type: 'RESOURCE_FILE_RESULT',
+                                payload: { requestId, error: resourceFileError },
+                            });
+                            return;
+                        }
+                        dispatchToBlock({
+                            type: 'RESOURCE_FILE_RESULT',
+                            payload: { requestId, file: resourceFile },
+                        });
+                        return;
+                    }
                     case 'QUERY_APP_WORKFLOWS': {
                         // App generator SUBQUEUE read. Drop a request with no requestId
                         // (unroutable). A forced error replies with the FREE-TEXT error
@@ -3921,6 +3975,11 @@ export function createMockHost(options = {}) {
             wildcardPack = patch.wildcardPack;
         if (patch.wildcardPackError !== undefined)
             wildcardPackError = patch.wildcardPackError;
+        if (patch.resourceFile !== undefined)
+            resourceFile = patch.resourceFile;
+        // Key PRESENCE, not value: `{ resourceFileError: undefined }` clears it.
+        if ('resourceFileError' in patch)
+            resourceFileError = patch.resourceFileError;
         if (patch.collectionFollowError !== undefined)
             collectionFollowError = patch.collectionFollowError;
         if (patch.reactionStates !== undefined || patch.reactionError !== undefined) {

package/dist/transport/requestTimeouts.d.ts

@@ -59,6 +59,19 @@ export declare const TRAINING_DATA_UPLOAD_TIMEOUT_MS: number;
  * caller shares the number instead of re-typing it.
  */
 export declare const WORKFLOW_REQUEST_TIMEOUT_MS = 120000;
+/**
+ * The bound for `GET_RESOURCE_FILE` (`hooks/useResourceFile.ts`), a `'protocol'`
+ * request whose HOST work is slow: a session-authed resolve, a fetch of the
+ * signed URL (up to 32 MB), then an unzip and parse of up to 16 MB in the
+ * viewer's tab. The host bounds all three with ONE 110 s deadline
+ * (civitai/civitai#6818 `RESOURCE_FILE_DEADLINE_MS`), after which it replies
+ * `parse-failed`. At {@link DEFAULT_REQUEST_TIMEOUT_MS} a large file on a slow
+ * connection would time out on the block while the host was still working, and
+ * the host's valid reply would be dropped as unroutable. 120 s leaves the host's
+ * 110 s deadline room to answer first. Same number as
+ * {@link WORKFLOW_REQUEST_TIMEOUT_MS}.
+ */
+export declare const RESOURCE_FILE_REQUEST_TIMEOUT_MS = 120000;
 /** Which bound a block→parent message is answered under. */
 export type RequestTimeoutClass = 
 /** Reply waits on a PERSON — must pass {@link HUMAN_INTERACTION_TIMEOUT_MS}. */

package/dist/transport/requestTimeouts.js

@@ -58,6 +58,19 @@ export const TRAINING_DATA_UPLOAD_TIMEOUT_MS = 60 * 60_000;
  * caller shares the number instead of re-typing it.
  */
 export const WORKFLOW_REQUEST_TIMEOUT_MS = 120_000;
+/**
+ * The bound for `GET_RESOURCE_FILE` (`hooks/useResourceFile.ts`), a `'protocol'`
+ * request whose HOST work is slow: a session-authed resolve, a fetch of the
+ * signed URL (up to 32 MB), then an unzip and parse of up to 16 MB in the
+ * viewer's tab. The host bounds all three with ONE 110 s deadline
+ * (civitai/civitai#6818 `RESOURCE_FILE_DEADLINE_MS`), after which it replies
+ * `parse-failed`. At {@link DEFAULT_REQUEST_TIMEOUT_MS} a large file on a slow
+ * connection would time out on the block while the host was still working, and
+ * the host's valid reply would be dropped as unroutable. 120 s leaves the host's
+ * 110 s deadline room to answer first. Same number as
+ * {@link WORKFLOW_REQUEST_TIMEOUT_MS}.
+ */
+export const RESOURCE_FILE_REQUEST_TIMEOUT_MS = 120_000;
 /**
  * 🔴 THE TOTALITY GATE — every block→parent message type, bucketed.
  *
@@ -158,6 +171,10 @@ const REQUEST_TIMEOUT_CLASS = {
     GET_IMAGES_BY_IDS: 'protocol',
     GET_VIEWER: 'protocol',
     GET_WILDCARD_PACK: 'protocol',
+    // No person in the loop, so `'protocol'` — but sent under its own longer
+    // `RESOURCE_FILE_REQUEST_TIMEOUT_MS`: the host's resolve + fetch + unzip run
+    // under a 110 s deadline, which the 30 s default would cut short.
+    GET_RESOURCE_FILE: 'protocol',
     QUERY_APP_WORKFLOWS: 'protocol',
     REQUEST_TOKEN: 'protocol',
     // The host fetches the blob and triggers the browser's own download; it replies

package/dist/transport/validate.d.ts

@@ -347,6 +347,17 @@ export declare function isValidDailyCompensationResult(p: unknown): boolean;
  * reply, mirroring the host's enum contract.
  */
 export declare function isValidWildcardPackResult(p: unknown): boolean;
+/**
+ * Reply to a block-initiated `GET_RESOURCE_FILE`. Same contract shape as
+ * {@link isValidWildcardPackResult}: EITHER a `file` OR an `error` that is one of
+ * {@link RESOURCE_FILE_ERROR_CODES}; a free-text or unknown `error`, or a reply
+ * with neither, is malformed and dropped. The `file` is checked field by field —
+ * `meta` ids positive integers, names strings, `creatorUsername` a string or
+ * `null`, `truncated` a boolean, and EVERY entry an object with a string `path`,
+ * a known `format` and a `graph` key. `graph` itself is the host's parsed JSON
+ * and may be any JSON value.
+ */
+export declare function isValidResourceFileResult(p: unknown): boolean;
 /**
  * Reply to a block-initiated `QUERY_APP_WORKFLOWS`. A well-formed reply carries
  * EITHER a `result` ({ workflows: AppWorkflow[], cursor: string | null }) OR a

package/dist/transport/validate.js

@@ -1040,6 +1040,80 @@ export function isValidWildcardPackResult(p) {
         return false;
     return true;
 }
+/**
+ * The CLOSED `RESOURCE_FILE_RESULT` error set, mirroring
+ * `BlockResourceFileErrorCode` (civitai/civitai-app-starters#664).
+ */
+const RESOURCE_FILE_ERROR_CODES = new Set([
+    'not-found',
+    'forbidden',
+    'unauthorized',
+    'too-large',
+    'parse-failed',
+    'busy',
+    'rate-limited',
+]);
+const RESOURCE_FILE_ENTRY_FORMATS = new Set(['ui', 'api', 'unknown']);
+/**
+ * Reply to a block-initiated `GET_RESOURCE_FILE`. Same contract shape as
+ * {@link isValidWildcardPackResult}: EITHER a `file` OR an `error` that is one of
+ * {@link RESOURCE_FILE_ERROR_CODES}; a free-text or unknown `error`, or a reply
+ * with neither, is malformed and dropped. The `file` is checked field by field —
+ * `meta` ids positive integers, names strings, `creatorUsername` a string or
+ * `null`, `truncated` a boolean, and EVERY entry an object with a string `path`,
+ * a known `format` and a `graph` key. `graph` itself is the host's parsed JSON
+ * and may be any JSON value.
+ */
+export function isValidResourceFileResult(p) {
+    if (!isObject(p))
+        return false;
+    if (!isWireRequestIdShape(p.requestId))
+        return false;
+    if (p.error !== undefined) {
+        if (typeof p.error !== 'string' || !RESOURCE_FILE_ERROR_CODES.has(p.error))
+            return false;
+    }
+    if (p.file !== undefined) {
+        const file = p.file;
+        if (!isObject(file))
+            return false;
+        const meta = file.meta;
+        if (!isObject(meta))
+            return false;
+        if (!isPositiveInteger(meta.modelId))
+            return false;
+        if (!isPositiveInteger(meta.modelVersionId))
+            return false;
+        if (!isPositiveInteger(meta.fileId))
+            return false;
+        if (typeof meta.fileName !== 'string')
+            return false;
+        if (typeof meta.modelName !== 'string')
+            return false;
+        if (typeof meta.versionName !== 'string')
+            return false;
+        if (meta.creatorUsername !== null && typeof meta.creatorUsername !== 'string')
+            return false;
+        if (typeof file.truncated !== 'boolean')
+            return false;
+        if (!Array.isArray(file.entries))
+            return false;
+        for (const entry of file.entries) {
+            if (!isObject(entry))
+                return false;
+            if (typeof entry.path !== 'string')
+                return false;
+            if (typeof entry.format !== 'string' || !RESOURCE_FILE_ENTRY_FORMATS.has(entry.format)) {
+                return false;
+            }
+            if (!('graph' in entry))
+                return false;
+        }
+    }
+    if (p.file === undefined && p.error === undefined)
+        return false;
+    return true;
+}
 // ============================================================
 // App generator SUBQUEUE reply validators
 // ============================================================
@@ -2302,6 +2376,8 @@ export function payloadValidatorFor(type) {
             return isValidDailyCompensationResult;
         case 'WILDCARD_PACK_RESULT':
             return isValidWildcardPackResult;
+        case 'RESOURCE_FILE_RESULT':
+            return isValidResourceFileResult;
         case 'APP_WORKFLOWS_RESULT':
             return isValidAppWorkflowsResult;
         case 'CANCEL_APP_WORKFLOW_RESULT':

package/dist/version.generated.d.ts

@@ -1,3 +1,3 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.77.0";
+export declare const VERSION = "0.78.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -1,4 +1,4 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.77.0";
+export const VERSION = "0.78.0";
 //# sourceMappingURL=version.generated.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.77.0",
+  "version": "0.78.0",
   "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.77.0"
+    "@civitai/app-sdk": "^0.79.0"
   },
   "publishConfig": {
     "access": "public"