@civitai/blocks-react 0.76.1 → 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
@@ -1463,43 +1524,55 @@ options drive both arms (including `declined`). **`dev:live` refuses this bridge
 it has no civitai chrome to render the server-resolved confirm in, and driving
 the write without it would let dev prove out a flow production does not have.
 
-### `usePrepareTrainingDataset()` and `useRunTraining()` — LoRA training
-
-Train a LoRA with the ai-toolkit engine on the **viewer's own images**, from
-inside a page app — the App Blocks `kind: 'training'` flow. Four steps, three
-hooks:
-
-1. **Dataset** — `usePrepareTrainingDataset().prepareDataset([{ imageId, caption }])`
-   (`PREPARE_TRAINING_DATASET`). Only the viewer's own scanned, unflagged images
-   within the page's maturity ceiling are admitted; the rest come back in
-   `rejected` with a reason (`unavailable`, `unsupported-media`, `not-eligible`,
-   `pending-scan`, `import-failed`, `import-unavailable`; `pending-scan` and
-   `import-unavailable` are retryable). You get an opaque `datasetId` and the
-   admitted `count`, always at least 1 — if **nothing** is admitted the call
-   rejects with the server's message instead. 1–50 images, captions up to 1,000 characters; captions are
-   moderated. No dialog, no charge.
+### `useImageUpload({ purpose: 'trainingData' })` and `useRunTraining()` — LoRA training
+
+Train a LoRA with the ai-toolkit engine on **images the viewer uploads**, from
+inside a page app — the App Blocks `kind: 'training'` flow, with the same upload
+path and `{ air, caption }` dataset shape as Civitai's own training form. Four
+steps, three hooks:
+
+1. **Upload** — `useImageUpload({ purpose: 'trainingData' }).open()`
+   (`OPEN_IMAGE_UPLOAD { purpose: 'trainingData' }`). Civitai opens an upload
+   modal in **its own chrome**; the viewer picks up to 50 PNG, JPEG or WebP
+   images, and each is uploaded as a private blob (not published). `open()`
+   resolves with every image that uploaded, `[{ url, air }]`, or `null` when
+   the viewer cancels. Pair each `air` with your caption — captions up to 8,192
+   characters, one blob at most once. The host answers only when its modal
+   closes, after every original has uploaded, so `open()` waits up to an hour,
+   not the ten minutes the other pickers use.
 2. **Quote** — `useBuzzWorkflow().estimate(body)` with a `WorkflowBodyTraining`
-   (`kind: 'training'`, no `quoteId`). The reply carries `trainingQuote:
-   { quoteId, total, imageCount, expiresAt }` — the orchestrator's own price for
-   exactly this run, stored server-side for 15 minutes.
+   (`kind: 'training'`, `items: [{ air, caption }]`, no `quoteId`). The reply
+   carries `trainingQuote: { quoteId, total, imageCount, expiresAt }` — the
+   orchestrator's own price for exactly this run, stored server-side for 15
+   minutes.
 3. **Run** — `useRunTraining().runTraining({ ...body, quoteId })` (`RUN_TRAINING`).
    **Civitai shows the viewer a consent dialog in its own chrome** — price, base
    model, length and dataset size, all read back from the server, never from
-   your body — and submits only on their click. Change nothing in the body
-   between the estimate and the run; the server checks it against the quoted one.
+   your body, with the host's own copies of the uploads as thumbnails — and
+   submits only on their click. Change nothing in the body between the estimate
+   and the run; the server checks it against the quoted one.
 4. **Follow** — `useBuzzWorkflow().watch(workflowId)`. Once the run's moderation
    status is approved, `trainedEpochs` lists the epochs whose checkpoint is
    ready; send the viewer to the publish wizard with one of them (see
    `trainedEpochs` on `BlockWorkflowSnapshot`).
 
+🔴 **Upload and run in the same page session.** The host remembers the blobs
+its own upload modal uploaded for this block, and **refuses a quote naming any
+other** with `training data not uploaded here` — before any dialog, so no run
+and no charge. A page reload forgets the uploads: ask the viewer to upload
+again, then estimate again.
+
 🔴 **Availability.** Behind the host flag **`app-blocks-training-kind`**, which
 ships **off** and is evaluated per viewer. **Page apps only** — the model slot
-answers both messages with an error. The manifest must declare
+answers `RUN_TRAINING` with an error. The manifest must declare
 **`ai:write:budgeted`** and the viewer must be signed in and have granted it.
 **Refused from `dev:live` and from review sessions** (the server refuses
 development and review tokens); build the flow against the mock host. Requires a
 civitai.com host carrying civitai/civitai#5434 (`kind: 'training'`,
-`RUN_TRAINING`) and civitai/civitai#5438 (`PREPARE_TRAINING_DATASET`).
+`RUN_TRAINING`) and civitai/civitai#6461 (uploaded blobs as the dataset). The
+server-prepared dataset this flow used before #6461 (`usePrepareTrainingDataset`,
+`PREPARE_TRAINING_DATASET`) is **removed**; a host carrying #6461 answers that
+message with the error `removed`.
 
 🔴 **Money.** There is no `maxBuzz` and no timeout knob — the price is the quote.
 A confirmed run may cost more than the token's per-call `buzzBudget` (the viewer
@@ -1516,32 +1589,26 @@ saying anything about money:
 | `err.declined` | the viewer dismissed the dialog — **no run was submitted** | revert, say nothing |
 | `err.unconfirmed` | `submission-unconfirmed`, or no reply within the 10-min bound (`err.timedOut`) — the run **may be running and charged** | 🔴 **never retry automatically**: check the viewer's trainings first (`useAppWorkflows()` lists this app's runs). Re-running the same body after the server did start it is a **second, separately charged run** |
 | `err.refused` (`code: 'refused'`) | the server refused the submit after the viewer confirmed — a **spend cap** (their daily or private-run Buzz cap, the per-app consent budget, the app's daily spend or rate limit, a dev-session cap) or a **temporary-availability** deny. Refunded: **no run, nothing charged**; the quote is used up | show `err.message` (the server's reason, e.g. `daily Buzz cap reached: …`); estimate again before any retry — buying Buzz does not lift these caps |
+| `err.trainingDataNotUploaded` (`code: 'training data not uploaded here'`) | the quote names an image this host did not upload for this block (typically after a reload) — refused before any dialog: **no run, nothing charged** | ask the viewer to upload the images again, then estimate and run the new quote |
 | `err.signInRequired` | no session | route into `useRequestSignIn()` |
 | `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `invalid training request` / `no block token`) | show or ignore per case |
-| `err.code === undefined`, no flag | a server refusal before any submit (expired or used quote, changed body, ineligible image) | estimate again, then retry |
+| `err.code === undefined`, no flag | a server refusal before any submit (expired or used quote, changed body) | estimate again, then retry |
 
-`prepareDataset` rejects with a `PrepareTrainingDatasetError` (`.code` for the
-host's refusals — `review-mode`, `block is not ready`, `sign in to train`,
-`invalid training dataset`, `no block token` — plus `.signInRequired` and
-`.timedOut`). Preparing charges nothing, so none of them cost Buzz. It prompts
-for `ai:write:budgeted` and retries once on a grant (see the table below);
-`runTraining` deliberately does not — it carries no idempotency key and has an
-outcome where a run may exist, so it never re-sends.
+`runTraining` never prompts for `ai:write:budgeted` or re-sends — it carries no
+idempotency key and has an outcome where a run may exist.
 
 ```tsx
-const { prepareDataset } = usePrepareTrainingDataset();
+const { open } = useImageUpload({ purpose: 'trainingData' });
 const { estimate, watch } = useBuzzWorkflow();
 const { runTraining } = useRunTraining();
 
-async function train(images: Array<{ id: number; caption: string }>) {
-  // Rejects (no `.code`) when NOTHING is admitted, e.g. "none of the requested
-  // images can be used for training"; a resolved dataset always has count >= 1.
-  const dataset = await prepareDataset(images.map((i) => ({ imageId: i.id, caption: i.caption })));
-  if (dataset.rejected.length > 0) showNotice(`${dataset.rejected.length} image(s) left out`);
+async function train(captionFor: (image: BlockTrainingDataImage) => string) {
+  const images = await open();
+  if (!images) return; // the viewer cancelled
 
   const body: WorkflowBodyTraining = {
     kind: 'training',
-    datasetId: dataset.datasetId,
+    items: images.map((image) => ({ air: image.air, caption: captionFor(image) })),
     engine: 'ai-toolkit',
     model: baseModelKey, // a key from Civitai's training catalog
     params: aiToolkitParams, // AiToolkitTrainingParams
@@ -1561,6 +1628,7 @@ async function train(images: Array<{ id: number; caption: string }>) {
     if (err.declined) return; // no run
     if (err.unconfirmed) return showCheckYourTrainings(); // may be running — never auto-retry
     if (err.refused) return showError(err.message); // a cap / availability refusal; no run, nothing charged
+    if (err.trainingDataNotUploaded) return showError('Upload the images again.'); // no run
     if (err.signInRequired) return requestSignIn();
     showError('Could not start training. Get a new price and try again.');
   }
@@ -1569,19 +1637,22 @@ async function train(images: Array<{ id: number; caption: string }>) {
 
 With the mock host — `createMockHost` or `Harness` from
 `@civitai/blocks-react/testing` — the training path is **kind-faithful**: it
-holds the datasets it prepared and the quotes it stored, refuses an unknown
-dataset, a dataset with nothing admitted, a quote above 5,000 and a quote run
-twice, and needs
-`ai:write:budgeted` on the token and a signed-in viewer. Its knobs are
-`trainingDatasetRejected`, `trainingDatasetError`, `trainingQuoteTotal`,
-`runTrainingError` (`'declined'`, `'submission-unconfirmed'`, or any server
-message), `runTrainingCapRefusal` (the server's resolved cap / availability refusal, which consumes the quote →
+remembers the blob keys its uploads handed out and refuses a run naming any
+other (`training data not uploaded here`, quote kept), refuses items outside the
+server's schema at the estimate, a quote above 5,000, a quote run twice and a
+body that differs from the quoted one, and needs `ai:write:budgeted` on the
+token and a signed-in viewer. Its knobs are `cannedTrainingDataUpload` (the
+images an upload returns; default three fresh ones per upload, `null` for a
+cancel), `trainingDataNotUploadedHere` (refuse every run as a host that forgot
+its uploads would), `trainingQuoteTotal`, `runTrainingError` (`'declined'`,
+`'submission-unconfirmed'`, or any server message), `runTrainingCapRefusal` (the
+server's resolved cap / availability refusal, which consumes the quote →
 `err.refused`) and `generation.trainedEpochs` for the finished run. It has no
-consent dialog, so `runTraining` settles at once where the real host waits on a
-click, and it checks a run's body against its quote by `datasetId` only — the
-server compares the whole body.
-**`dev:live` refuses both bridges**, because the server refuses every training
-request from a dev token.
+upload modal and no consent dialog, so `open()` and `runTraining` settle at once
+where the real host waits on the viewer; and it accepts any https blob url as an
+`air`, where the server accepts only Civitai-hosted ones — name items by `air`.
+**`dev:live` refuses the run** (the server refuses every training request from a
+dev token) and answers the upload as a cancel.
 
 ### `useRunConfirmedStep()` — one job above the per-call budget
 
@@ -2213,8 +2284,10 @@ answers a raw `multiple` + Checkpoint request with the host's error.
 
 Host-mediated image upload — the host opens its native upload modal and the
 iframe never handles the bytes. Resolves with a moderated image (or `null` on
-dismiss); pass `{ purpose: 'generationSource' }` for an unscanned img2img source
-or `{ asyncScan: true }` for the early-resolve + `scanStatus()` flow.
+dismiss); pass `{ purpose: 'generationSource' }` for an unscanned img2img source,
+`{ purpose: 'trainingData' }` for several private training images in one call
+(`[{ url, air }] | null` — see the LoRA training section), or
+`{ asyncScan: true }` for the early-resolve + `scanStatus()` flow.
 
 ```tsx
 const { open } = useImageUpload();
@@ -2863,7 +2936,6 @@ had just worked.
 |---|---|---|
 | `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
 | `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
-| `usePrepareTrainingDataset()` | `prepareDataset()` | `ai:write:budgeted` |
 | `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
 | `useTip()` | `tip()` | `social:tip:self` |
 
@@ -3819,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/useImageUpload.d.ts

@@ -1,11 +1,12 @@
-import type { BlockGenerationSourceImageInfo, BlockImageScanResult, BlockPendingImageInfo, BlockUploadedImageInfo, BlockUploadPurpose } from '@civitai/app-sdk/blocks';
+import type { BlockGenerationSourceImageInfo, BlockImageScanResult, BlockPendingImageInfo, BlockTrainingDataImage, BlockUploadedImageInfo, BlockUploadPurpose } from '@civitai/app-sdk/blocks';
+export type { BlockTrainingDataImage };
 /**
  * What {@link useImageUpload} returns for the DEFAULT (`purpose: 'display'`,
  * blocking-scan) call — `useImageUpload()` with no arguments.
  *
  * 🔴 THIS HOOK IS OVERLOADED, SO ITS RETURN TYPE IS A FAMILY, NOT A SINGLETON
  * (#380). Each overload names its own: {@link UseImageUploadGenerationSource},
- * {@link UseImageUploadAsyncScan}, and this one. A single union would be worse
+ * {@link UseImageUploadTrainingData}, {@link UseImageUploadAsyncScan}, and this one. A single union would be worse
  * than the anonymous literals it replaces — it would hand every caller a
  * `scanStatus` that only one overload actually provides.
  */
@@ -16,6 +17,14 @@ export interface UseImageUpload {
 export interface UseImageUploadGenerationSource {
     open: () => Promise<BlockGenerationSourceImageInfo | null>;
 }
+/** What {@link useImageUpload} returns for `{ purpose: 'trainingData' }`. */
+export interface UseImageUploadTrainingData {
+    /**
+     * Every image the viewer uploaded, in the host's order, or `null` when they
+     * cancelled. Each `air` is what a `BlockTrainingDatasetItem` names.
+     */
+    open: () => Promise<BlockTrainingDataImage[] | null>;
+}
 /** What {@link useImageUpload} returns for `{ asyncScan: true }`. */
 export interface UseImageUploadAsyncScan {
     /** Early-resolve handle (image persisted, NOT yet scanned) or `null` (dismissed). */
@@ -37,7 +46,7 @@ export interface UseImageUploadAsyncScan {
  * compatible; the async overload types it required.
  */
 export interface UseImageUploadImplementation {
-    open: () => Promise<BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo | null>;
+    open: () => Promise<BlockUploadedImageInfo | BlockGenerationSourceImageInfo | BlockPendingImageInfo | BlockTrainingDataImage[] | null>;
     scanStatus?: (handle: BlockPendingImageInfo) => Promise<BlockImageScanResult>;
 }
 /** Options for {@link useImageUpload}. */
@@ -49,14 +58,18 @@ export interface UseImageUploadOptions {
      *  - `'generationSource'` — a PRIVATE img2img source; UNSCANNED, so the host
      *    returns ONLY the source shape {@link BlockGenerationSourceImageInfo}
      *    (`{ url, width, height }`).
+     *  - `'trainingData'` — PRIVATE training images for a `kind: 'training'` run
+     *    (page apps only): up to 50 picked in one host modal, returned together as
+     *    {@link BlockTrainingDataImage}`[]`.
      */
     purpose?: BlockUploadPurpose;
     /**
      * Opt in to the NON-BLOCKING `'display'` flow. When `true`, `open()` resolves
      * EARLY (on persist) with a {@link BlockPendingImageInfo} and the scan verdict
      * is delivered separately via `scanStatus()` (see the async overload). Only
-     * meaningful for `'display'`; ignored for `'generationSource'` (that path has
-     * no host-side scan). Absent/`false` keeps the legacy blocking behavior.
+     * meaningful for `'display'`; ignored for `'generationSource'` and
+     * `'trainingData'` (neither has a host-side scan). Absent/`false` keeps the
+     * legacy blocking behavior.
      */
     asyncScan?: boolean;
 }
@@ -82,9 +95,20 @@ export interface UseImageUploadOptions {
  *    {@link BlockGenerationSourceImageInfo} (`{ url, width, height }`, UNSCANNED —
  *    the orchestrator scans it at gen time), or `null` on dismiss. Feed it
  *    straight into a `WorkflowBody.sourceImage` for an img2img graph.
+ *  - `'trainingData'` → resolves with EVERY image the viewer uploaded,
+ *    {@link BlockTrainingDataImage}`[]` (`{ url, air }` each), or `null` on
+ *    cancel. Step 1 of a `kind: 'training'` run: pair each `air` with a caption
+ *    for `WorkflowBodyTraining.items`. The host remembers the keys it uploaded
+ *    for this block and refuses a run naming any other
+ *    (`training data not uploaded here`), so upload and run in the same page
+ *    session. A host that predates the purpose answers with one display image,
+ *    which this resolves as `null` — never as a list it did not upload.
  *
  * Human-interactive, so it uses the same generous {@link HUMAN_INTERACTION_TIMEOUT_MS}
- * as the pickers (the host still resolves earlier on upload/dismiss/close).
+ * as the pickers (the host still resolves earlier on upload/dismiss/close) — except
+ * `'trainingData'`, which waits up to {@link TRAINING_DATA_UPLOAD_TIMEOUT_MS} (one
+ * hour): the host replies only after uploading up to 50 originals, which can take
+ * longer than ten minutes.
  * Host-mediated, same trust model as `useResourcePicker` / `useBuzzWorkflow`.
  *
  * Backward-compatible: when `purpose` is omitted the hook sends NO `purpose`
@@ -117,10 +141,20 @@ export interface UseImageUploadOptions {
  * if (!src) return;
  * await submit({ kind: 'textToImage', modelId, modelVersionId,
  *   sourceImage: src, params: { prompt } });
+ *
+ * @example
+ * // trainingData (private training images, several in one reply)
+ * const { open } = useImageUpload({ purpose: 'trainingData' });
+ * const images = await open();            // [{ url, air }, …] | null
+ * if (!images) return;
+ * const items = images.map((img) => ({ air: img.air, caption: captionFor(img) }));
  */
 export declare function useImageUpload(options: {
     purpose: 'generationSource';
 }): UseImageUploadGenerationSource;
+export declare function useImageUpload(options: {
+    purpose: 'trainingData';
+}): UseImageUploadTrainingData;
 export declare function useImageUpload(options: {
     purpose?: 'display';
     asyncScan: true;

package/dist/hooks/useImageUpload.js

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef } from 'react';
-import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS, TRAINING_DATA_UPLOAD_TIMEOUT_MS, } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest, subscribeTyped } from '../transport/transport.js';
 import { useTransportConnection } from './useTransportConnection.js';
@@ -31,7 +31,7 @@ function isTerminalVerdict(v) {
 export function useImageUpload(options) {
     useTransportConnection();
     const purpose = options?.purpose;
-    const asyncScan = options?.asyncScan === true && purpose !== 'generationSource';
+    const asyncScan = options?.asyncScan === true && (purpose === undefined || purpose === 'display');
     // Per-instance scan tracking, keyed by imageId. Persists across renders; a
     // verdict is correlated back to its upload by imageId + the generated requestId.
     const scansRef = useRef(new Map());
@@ -129,6 +129,19 @@ export function useImageUpload(options) {
             // payload) → treat as dismissed rather than fabricate a handle.
             return null;
         }
+        if (purpose === 'trainingData') {
+            const { selected } = await sendTypedRequest(getTransport(), { type: 'OPEN_IMAGE_UPLOAD', payload: { purpose } }, 'IMAGE_UPLOAD_RESULT', 
+            // NOT the 10-minute human bound: the host answers only after uploading
+            // every original, which can outlast it — see TRAINING_DATA_UPLOAD_TIMEOUT_MS.
+            { timeoutMs: TRAINING_DATA_UPLOAD_TIMEOUT_MS });
+            // Only the multi-image shape is an answer to THIS purpose. A host that
+            // predates `trainingData` normalises it to `display` and replies with one
+            // moderated image — nothing a training item can name — so that, an empty
+            // list and a cancel all resolve `null` rather than a fabricated list.
+            if (!selected || !('images' in selected) || selected.images.length === 0)
+                return null;
+            return selected.images.map(({ url, air }) => ({ url, air }));
+        }
         // ---- Existing BLOCKING behavior (unchanged) ----
         // Omit `purpose` for the default/display mode so the wire stays
         // byte-compatible with an older host that predates the field.
@@ -136,7 +149,10 @@ export function useImageUpload(options) {
         const { selected } = await sendTypedRequest(getTransport(), { type: 'OPEN_IMAGE_UPLOAD', payload }, 'IMAGE_UPLOAD_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
         // Normalize the "dismissed" case to an explicit null so callers can
         // `if (!img) return;` without an `undefined` ambiguity.
-        return selected ?? null;
+        // A multi-image training reply is not an answer to a single-image purpose.
+        if (!selected || 'images' in selected)
+            return null;
+        return selected;
     }, [asyncScan, purpose]);
     const scanStatus = useCallback((handle) => {
         const entry = scansRef.current.get(handle.imageId);

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