@civitai/blocks-react 0.75.0 → 0.76.0

package/README.md

@@ -675,6 +675,14 @@ showImages(done.imageUrls ?? []);
   KB (262144 bytes) for every step's `input` plus `arguments` together. An
   unknown key on the body or on a step is rejected. The app's velocity limit
   counts one unit per step, and a `repeat` step one per iteration instead.
+- **No inline media** in a step `input` or in `arguments` — here or in a
+  pass-through `kind: 'step'` body's `input`: no `data:image|video|audio` URI
+  and no raw base64 string of 4096+ characters, at any depth. Upload the image,
+  video or audio with [`useMediaUpload()`](#usemediaupload) (an image also works
+  with `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`)
+  and pass the returned `url`. A body holding more than
+  262144 values in those fields is refused outright. `createMockHost` refuses
+  both as the host does, naming the path.
 - `suppressOutput: true` marks an intermediate step. Its images are left out of
   `snapshot.imageUrls` and out of its own `steps[i].imageUrls`. It still runs
   and is still charged.
@@ -2475,6 +2483,126 @@ an invalid `sources` or `multiple` with an error, and answers
 list the viewer's images, so there `open` rejects with a message saying to use
 the mock host.
 
+### `useMediaUpload()`
+
+**The way to pass any media (image, video or audio) into a workflow step.** The
+host refuses data URIs and inline base64 in step inputs, so upload the file
+with this hook and pass the `url` it returns into the step input. Returns
+`{ open, upload }`.
+
+- **`open({ kind })`** opens the host's own file picker for that kind. The
+  viewer picks a file, the host uploads it, and `open` resolves with the
+  upload, or `null` if nothing was uploaded.
+- **`upload({ kind, bytes, mimeType? })`** uploads media your app already
+  holds in the tab, with no picker: a canvas export, a crop, a `MediaRecorder`
+  recording. It resolves with the upload, and never resolves without one.
+
+```tsx
+import { useMediaUpload } from '@civitai/blocks-react';
+
+function UseRecording({ recording }: { recording: Blob }) {
+  const { upload } = useMediaUpload();
+
+  async function onClick() {
+    const audio = await upload({
+      kind: 'audio',
+      bytes: await recording.arrayBuffer(),
+      mimeType: recording.type, // optional; checked against the content
+    });
+    // audio.url goes into the step's audio input
+    startStep({ audioUrl: audio.url });
+  }
+
+  return <button onClick={onClick}>Use this recording</button>;
+}
+```
+
+```tsx
+const { open } = useMediaUpload();
+
+const video = await open({ kind: 'video' }); // BlockMediaUploadInfo | null
+if (video) {
+  // video.url, video.width, video.height, video.durationMs (when known)
+}
+```
+
+What each kind accepts, decided by the file's **content** (its first bytes),
+never by its name or declared type:
+
+| `kind` | Accepted | What you get back |
+|---|---|---|
+| `'image'` | PNG, JPEG, WebP | Resized so both sides are 64 to 2048 pixels and re-encoded as JPEG: `mimeType` is always `'image/jpeg'`, and `sizeBytes`, `width` and `height` describe that JPEG. |
+| `'video'` | MP4, WebM | Uploaded as sent. `width` and `height` are always set (a file with no video track is refused). `durationMs` when the browser reports a duration. |
+| `'audio'` | MP3, WAV, WebM | Uploaded as sent. No `width` or `height`. `durationMs` when the browser reports a duration: a `MediaRecorder` WebM often reports none, so do not rely on it. |
+
+- **At most 24 MB per image, and 64 MB per video or audio file.** The image
+  cap is lower because the host decodes an image in full before it resizes it.
+  `upload` refuses a larger buffer before sending it, with the host's own
+  message: `file exceeds the 24 MB image upload limit` or
+  `file exceeds the 64 MB upload limit`.
+- **`upload` is rate-limited:** at most 8 uploads and 128 MB per 60 seconds
+  per page. Past that the host replies `busy`; wait and retry. A refused upload
+  does not count. `open` is not limited this way, because a person picks each
+  file.
+- **`mimeType` is optional.** When you pass it (for example `blob.type`) it
+  must match the content, or the upload is refused with
+  `mimeType does not match the file's content`. Case and parameters such as
+  `;codecs=opus` are ignored, and `audio/x-wav` counts as `audio/wav`.
+- Pass an `ArrayBuffer` (`await blob.arrayBuffer()`). A `Blob`, a typed array
+  or an empty buffer is refused before sending with
+  `invalid media-upload request`. The buffer is copied, not transferred.
+- A file whose content is not one of its kind's types is refused with
+  `images must be PNG, JPEG or WebP`, `videos must be MP4 or WebM` or
+  `audio must be MP3, WAV or WebM`. The host also refuses a file it cannot
+  read (`could not read this video file`, `could not read this audio file`), a
+  video with no video track (`this file has no video track`), and an image too
+  small to resize to 64 pixels. A failed upload rejects with
+  `media upload failed — please try again`, and a file the upload service
+  refuses with `this video was refused by the upload service` or
+  `this audio was refused by the upload service`. A bytes upload made while
+  the host holds no block token rejects with `no block token`.
+
+What `open` and `upload` resolve and reject with:
+
+- **`open` resolves `null` when nothing was uploaded.** Usually the viewer
+  closed the picker. The host also answers that way at once, without showing a
+  picker, while your app is viewed in review mode or is not ready yet. A
+  problem with the picked file is shown in the picker, where the viewer can
+  pick another one.
+- **`upload` never resolves `null`.** When the host declines without
+  uploading (review mode, not ready), `upload` rejects with
+  `the host did not upload the media (the app is in review mode or not ready)`.
+- **A refusal rejects** with the host's message, in both modes. On a surface
+  other than a page app the host answers at once with
+  `unsupported on this host`.
+- **Both wait up to 10 minutes** for the host (a person picking a file, or a
+  large upload), then reject with a `RequestTimeoutError`.
+
+For images only, `useImageUpload().open({ purpose: 'generationSource' })` still
+works and returns `{ url, width, height }`. Use `useMediaUpload` for video,
+audio, or bytes your app made in the tab.
+
+🔴 **Needs a host that answers `OPEN_MEDIA_UPLOAD`** (civitai/civitai#6149).
+On a civitai.com that predates it, the request gets no answer and both calls reject with a
+`RequestTimeoutError` after 10 minutes.
+
+With the mock host (`createMockHost` or `Harness` from
+`@civitai/blocks-react/testing`) there is no picker: `open` resolves at once
+with a built-in upload for the kind. Set `cannedMediaUploads: { video: {...} }`
+to choose what a kind returns, or `{ audio: null }` for a viewer who closes
+that picker. `upload` runs the host's checks in the host's order (kind,
+purpose, an invalid buffer, the per-kind cap, the rate window, the content type,
+a mismatching `mimeType`) and answers with that kind's upload, carrying the
+sniffed `mimeType` and the buffer's size for video and audio. The mock cannot
+decode media, so it never produces the host's decode-time refusals (an
+unreadable file, no video track, an image too small, an upload failure): set
+`mediaUploadError: 'this file has no video track'` to force one.
+`mediaUploadError: 'no block token'` is checked where the host checks it: a
+bytes upload is refused before the cap and the window, and is not counted. A model-slot
+`context` answers `unsupported on this host`. `dev:live` cannot upload
+generation inputs, so there both calls reject with a message saying to use the
+mock host.
+
 ### `useSaveImage()`
 
 Ask the host to download a file to the viewer's device. **A block cannot
@@ -3424,6 +3552,7 @@ MockHost
 MockHostFailMode
 MockHostOptions
 MockHostScenarioPatch
+MockMediaUploads
 MockReactionSeed
 MockSharedScenario
 MockSharedSeed

package/dist/hooks/useMediaUpload.d.ts

@@ -0,0 +1,97 @@
+import type { BlockMediaKind, BlockMediaUploadInfo } from '@civitai/app-sdk/blocks';
+/**
+ * What `upload()` rejects with when the host answers with neither a file nor
+ * an error. For a bytes upload that means the host DECLINED it without trying
+ * (the app is viewed in review mode, or is not ready yet). Nothing was
+ * uploaded, so it must never read as a success.
+ */
+export declare const MEDIA_UPLOAD_DECLINED_ERROR = "the host did not upload the media (the app is in review mode or not ready)";
+/** Options for {@link UseMediaUpload.open}. */
+export interface MediaUploadOpenOptions {
+    /** What the viewer picks: `'image'`, `'video'` or `'audio'`. */
+    kind: BlockMediaKind;
+}
+/** Options for {@link UseMediaUpload.upload}. */
+export interface MediaUploadBytesOptions {
+    /** What the bytes are: `'image'`, `'video'` or `'audio'`. */
+    kind: BlockMediaKind;
+    /**
+     * The file, as an `ArrayBuffer` (`await blob.arrayBuffer()`). At most 24 MB
+     * for an image and 64 MB for video or audio.
+     * Copied across `postMessage`, never transferred. A `Blob`, a typed array or
+     * an empty buffer is refused before sending.
+     */
+    bytes: ArrayBuffer;
+    /**
+     * Optional: the type you believe you are sending (`blob.type`). The host
+     * decides the type from the content; when this is given and disagrees, the
+     * upload is refused with `mimeType does not match the file's content`.
+     * Parameters (`;codecs=…`) and case are ignored.
+     */
+    mimeType?: string;
+}
+/** What {@link useMediaUpload} returns. */
+export interface UseMediaUpload {
+    /**
+     * PICKER mode: the host opens its own file picker for `kind`, uploads what
+     * the viewer picks, and resolves with it. Resolves `null` when nothing was
+     * uploaded: the viewer closed the picker, or the host declined at once
+     * (review mode, not ready). Rejects with the host's message on a refusal.
+     */
+    open: (options: MediaUploadOpenOptions) => Promise<BlockMediaUploadInfo | null>;
+    /**
+     * BYTES mode: upload media the block holds (a canvas export, a crop, a
+     * `MediaRecorder` recording) with no picker. Resolves with the uploaded
+     * file. Rejects with the host's message on every refusal or failure, and
+     * with {@link MEDIA_UPLOAD_DECLINED_ERROR} when the host declined without
+     * uploading. It never resolves without a file.
+     */
+    upload: (options: MediaUploadBytesOptions) => Promise<BlockMediaUploadInfo>;
+}
+/**
+ * Upload an image, video or audio file as a GENERATION INPUT, and get back a
+ * `url` to pass into a workflow step input.
+ *
+ * 🔴 THIS IS THE WAY TO PUT MEDIA INTO A STEP. The host refuses data URIs and
+ * inline base64 in step inputs, so upload the file here and pass the returned
+ * `url`.
+ *
+ * - `open({ kind })` lets the viewer pick a file in the host's own picker.
+ * - `upload({ kind, bytes, mimeType? })` uploads bytes the block made in the
+ *   tab, with no picker.
+ *
+ * The type is decided by the file's content: images PNG, JPEG or WebP (the
+ * host resizes them to 64–2048 px per side and re-encodes them as JPEG);
+ * videos MP4 or WebM; audio MP3, WAV or WebM. At most 24 MB per image (the
+ * host decodes it in full before resizing) and 64 MB per video or audio; bytes
+ * mode also allows at most 8 uploads and 128 MB per 60 s per page, and
+ * rejects `busy` past that (retry later).
+ *
+ * Refused BEFORE sending, with the host's own strings: an unknown `kind`, an
+ * `upload` whose `bytes` is not a non-empty `ArrayBuffer` (or whose `mimeType`
+ * is not a string), and a buffer over the kind's cap.
+ *
+ * Page apps only: a model-slot host rejects with `unsupported on this host`.
+ * A host that predates this message does not answer it, so the call rejects
+ * with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * For images, `useImageUpload().open({ purpose: 'generationSource' })` remains
+ * valid; this hook is the one that also takes video, audio and in-tab bytes.
+ *
+ * @example
+ * // A recording made in the tab, passed into a step.
+ * const { upload } = useMediaUpload();
+ * const audio = await upload({ kind: 'audio', bytes: await recording.arrayBuffer(), mimeType: recording.type });
+ * // audio.url goes into the step's audio input
+ *
+ * @example
+ * // The viewer picks a video.
+ * const { open } = useMediaUpload();
+ * const video = await open({ kind: 'video' });
+ * if (video) {
+ *   // video.url, video.width, video.height, video.durationMs
+ * }
+ */
+export declare function useMediaUpload(): UseMediaUpload;
+//# sourceMappingURL=useMediaUpload.d.ts.map

package/dist/hooks/useMediaUpload.js

@@ -0,0 +1,108 @@
+import { useCallback } from 'react';
+import { MEDIA_UPLOAD_INVALID_ERROR, MEDIA_UPLOAD_KIND_ERROR, isMediaKind, mediaUploadCap, } from '../internal/mediaUploadBytes.js';
+import { throwOnReplyError } from '../internal/replyError.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+import { useTransportConnection } from './useTransportConnection.js';
+/**
+ * What `upload()` rejects with when the host answers with neither a file nor
+ * an error. For a bytes upload that means the host DECLINED it without trying
+ * (the app is viewed in review mode, or is not ready yet). Nothing was
+ * uploaded, so it must never read as a success.
+ */
+export const MEDIA_UPLOAD_DECLINED_ERROR = 'the host did not upload the media (the app is in review mode or not ready)';
+/**
+ * Upload an image, video or audio file as a GENERATION INPUT, and get back a
+ * `url` to pass into a workflow step input.
+ *
+ * 🔴 THIS IS THE WAY TO PUT MEDIA INTO A STEP. The host refuses data URIs and
+ * inline base64 in step inputs, so upload the file here and pass the returned
+ * `url`.
+ *
+ * - `open({ kind })` lets the viewer pick a file in the host's own picker.
+ * - `upload({ kind, bytes, mimeType? })` uploads bytes the block made in the
+ *   tab, with no picker.
+ *
+ * The type is decided by the file's content: images PNG, JPEG or WebP (the
+ * host resizes them to 64–2048 px per side and re-encodes them as JPEG);
+ * videos MP4 or WebM; audio MP3, WAV or WebM. At most 24 MB per image (the
+ * host decodes it in full before resizing) and 64 MB per video or audio; bytes
+ * mode also allows at most 8 uploads and 128 MB per 60 s per page, and
+ * rejects `busy` past that (retry later).
+ *
+ * Refused BEFORE sending, with the host's own strings: an unknown `kind`, an
+ * `upload` whose `bytes` is not a non-empty `ArrayBuffer` (or whose `mimeType`
+ * is not a string), and a buffer over the kind's cap.
+ *
+ * Page apps only: a model-slot host rejects with `unsupported on this host`.
+ * A host that predates this message does not answer it, so the call rejects
+ * with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * For images, `useImageUpload().open({ purpose: 'generationSource' })` remains
+ * valid; this hook is the one that also takes video, audio and in-tab bytes.
+ *
+ * @example
+ * // A recording made in the tab, passed into a step.
+ * const { upload } = useMediaUpload();
+ * const audio = await upload({ kind: 'audio', bytes: await recording.arrayBuffer(), mimeType: recording.type });
+ * // audio.url goes into the step's audio input
+ *
+ * @example
+ * // The viewer picks a video.
+ * const { open } = useMediaUpload();
+ * const video = await open({ kind: 'video' });
+ * if (video) {
+ *   // video.url, video.width, video.height, video.durationMs
+ * }
+ */
+export function useMediaUpload() {
+    useTransportConnection();
+    const open = useCallback(async ({ kind }) => {
+        if (!isMediaKind(kind))
+            throw new Error(MEDIA_UPLOAD_KIND_ERROR);
+        const reply = await sendTypedRequest(getTransport(), { type: 'OPEN_MEDIA_UPLOAD', payload: { kind, purpose: 'generationSource' } }, 'MEDIA_UPLOAD_RESULT', 
+        // A person picks the file, and the reply waits for the upload.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        // 🔴 BEFORE reading `selected`: a refusal carries none, and would
+        // otherwise resolve `null` exactly like a dismiss.
+        throwOnReplyError(reply, 'media upload failed');
+        return reply.selected ?? null;
+    }, []);
+    const upload = useCallback(async ({ kind, bytes, mimeType }) => {
+        // The host's own refusals, in the host's order, raised here so a doomed
+        // buffer is never copied across postMessage.
+        if (!isMediaKind(kind))
+            throw new Error(MEDIA_UPLOAD_KIND_ERROR);
+        if (!(bytes instanceof ArrayBuffer) || bytes.byteLength === 0) {
+            throw new Error(MEDIA_UPLOAD_INVALID_ERROR);
+        }
+        if (mimeType !== undefined && typeof mimeType !== 'string') {
+            throw new Error(MEDIA_UPLOAD_INVALID_ERROR);
+        }
+        const cap = mediaUploadCap(kind);
+        if (bytes.byteLength > cap.maxBytes)
+            throw new Error(cap.error);
+        const reply = await sendTypedRequest(getTransport(), {
+            type: 'OPEN_MEDIA_UPLOAD',
+            payload: {
+                kind,
+                purpose: 'generationSource',
+                bytes,
+                ...(mimeType !== undefined ? { mimeType } : {}),
+            },
+        }, 'MEDIA_UPLOAD_RESULT', 
+        // `'human'` class: a 64 MB upload plus the host's retries can outlast
+        // the default protocol timeout.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        throwOnReplyError(reply, 'media upload failed');
+        // A bare reply is the host declining (review mode / not ready). Nothing
+        // was uploaded, so this is a failure, not a success.
+        if (!reply.selected)
+            throw new Error(MEDIA_UPLOAD_DECLINED_ERROR);
+        return reply.selected;
+    }, []);
+    return { open, upload };
+}
+//# sourceMappingURL=useMediaUpload.js.map

package/dist/index.d.ts

@@ -88,6 +88,8 @@ export { useImageUpload } from './hooks/useImageUpload.js';
 export type { UseImageUpload, UseImageUploadAsyncScan, UseImageUploadGenerationSource, UseImageUploadOptions, } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
 export type { UploadImageBytesOptions, UseUploadImageBytes, } from './hooks/useUploadImageBytes.js';
+export { useMediaUpload } from './hooks/useMediaUpload.js';
+export type { UseMediaUpload, MediaUploadOpenOptions, MediaUploadBytesOptions, } from './hooks/useMediaUpload.js';
 export { useImagePicker, IMAGE_PICKER_MULTIPLE_MAX } from './hooks/useImagePicker.js';
 export type { UseImagePicker, ImagePickerOpenOptions, ImagePickerMultiple, } from './hooks/useImagePicker.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';

package/dist/index.js

@@ -69,6 +69,7 @@ export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
+export { useMediaUpload } from './hooks/useMediaUpload.js';
 export { useImagePicker, IMAGE_PICKER_MULTIPLE_MAX } from './hooks/useImagePicker.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.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
@@ -135,6 +135,9 @@
  *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted
  *     images and generator outputs, read off their signed-in session; no
  *     block-token endpoint lists either. Replies with a refusal.
+ *   • OPEN_MEDIA_UPLOAD — the generation-input upload runs in the host with the
+ *     viewer's signed-in session, which the local harness does not have.
+ *     Replies with a refusal.
  *   • SAVE_IMAGE — the download bridge is the production host's unsandboxed top
  *     frame plus its CDN origin allowlist / gated per-viewer read. Replies with
  *     a refusal (#386).
@@ -153,6 +156,11 @@ import { type PickerOverlayHandle } from './pickerOverlay.js';
  * rejects with it, so it says what to do instead.
  */
 export declare const IMAGE_PICKER_UNSUPPORTED_ERROR = "the image picker is not supported in dev:live \u2014 use dev:mock";
+/**
+ * The `error` the live host answers `OPEN_MEDIA_UPLOAD` with. `useMediaUpload()`
+ * rejects with it, so it says what to do instead.
+ */
+export declare const MEDIA_UPLOAD_UNSUPPORTED_ERROR = "media upload is not supported in dev:live \u2014 use dev:mock";
 /**
  * Options for {@link createLiveHost}. Mirrors the {@link MockHost}-relevant
  * subset of `MockHostOptions`, plus the live-only `blockToken` / `backendBaseUrl`

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
@@ -135,6 +135,9 @@
  *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted
  *     images and generator outputs, read off their signed-in session; no
  *     block-token endpoint lists either. Replies with a refusal.
+ *   • OPEN_MEDIA_UPLOAD — the generation-input upload runs in the host with the
+ *     viewer's signed-in session, which the local harness does not have.
+ *     Replies with a refusal.
  *   • SAVE_IMAGE — the download bridge is the production host's unsandboxed top
  *     frame plus its CDN origin allowlist / gated per-viewer read. Replies with
  *     a refusal (#386).
@@ -161,6 +164,11 @@ const REACTIONS_UNSUPPORTED_LOG = 'SET_ENTITY_REACTION / GET_ENTITY_REACTIONS ar
  * rejects with it, so it says what to do instead.
  */
 export const IMAGE_PICKER_UNSUPPORTED_ERROR = 'the image picker is not supported in dev:live — use dev:mock';
+/**
+ * The `error` the live host answers `OPEN_MEDIA_UPLOAD` with. `useMediaUpload()`
+ * rejects with it, so it says what to do instead.
+ */
+export const MEDIA_UPLOAD_UNSUPPORTED_ERROR = 'media upload is not supported in dev:live — use dev:mock';
 /** Default civitai backend the live host forwards to. */
 const DEFAULT_BACKEND_BASE_URL = 'https://civitai.com';
 /** The budgeted-spend scope the workflow procedures require. */
@@ -1414,6 +1422,24 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'OPEN_MEDIA_UPLOAD': {
+                        // REFUSED. The host uploads the file with the viewer's signed-in
+                        // session; this harness has none, and nothing a dev block token can
+                        // call takes the upload. Rather than let `useMediaUpload()` hang to
+                        // its 10-minute timeout, or hand back an invented URL a step would
+                        // then fail on, answer with an error (the hook rejects).
+                        logOnce('open-media-upload', 'OPEN_MEDIA_UPLOAD received but live dev mode cannot upload generation inputs ' +
+                            '— useMediaUpload() REJECTS. Test it against the real site, ' +
+                            'or use createMockHost({ cannedMediaUploads }) in dev:mock.');
+                        // A refusal nobody can route is not worth sending.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        dispatchToBlock({
+                            type: 'MEDIA_UPLOAD_RESULT',
+                            payload: { requestId, error: MEDIA_UPLOAD_UNSUPPORTED_ERROR },
+                        });
+                        return;
+                    }
                     case 'SET_USER_CHECKPOINT': {
                         // 🔴 A PAGE REFUSES, ALWAYS, WITHOUT A BACKEND CALL — and the default
                         // context is a page. That is the production page host exactly: the

package/dist/internal/mediaUploadBytes.d.ts

@@ -0,0 +1,169 @@
+/**
+ * `OPEN_MEDIA_UPLOAD`: the strings and limits both sides of the bridge agree
+ * on, the content sniffers, and the mock host's copy of the host's admission
+ * rules for BYTES mode.
+ *
+ * The host owns the real rules. This copy exists so `createMockHost` (and so
+ * `dev:harness` and every block test) accepts and refuses the same buffers
+ * production does, and so `useMediaUpload` can refuse locally what the host
+ * would refuse anyway. Keep it exactly as narrow as the contract: a mock that
+ * accepts a GIF as an image teaches a block that GIFs upload.
+ *
+ * 🔴 The host spells its OWN copy of every constant and string here, and the
+ * two MUST match. Nothing in this repository can read the host's values, so a
+ * drift is invisible here until a block hits a refusal the SDK did not
+ * predict. Kept local to this package (not exported from `@civitai/app-sdk`).
+ *
+ * WHAT THIS CANNOT MODEL: the host decodes the media before it uploads.
+ * Its decode-time refusals (`could not read this video file`,
+ * `could not read this audio file`, `this file has no video track`, an image
+ * too small to resize to at least 64 px, and upload failures) need a real
+ * decoder and network, so the mock never produces them.
+ */
+import type { BlockMediaKind, BlockMediaUploadInfo } from '@civitai/app-sdk/blocks';
+/** The cap on one VIDEO or AUDIO upload: 64 MiB of raw bytes (the consumer-blob upload cap). */
+export declare const MEDIA_UPLOAD_MAX_BYTES: number;
+/**
+ * The cap on one IMAGE upload: 24 MiB. Lower than {@link MEDIA_UPLOAD_MAX_BYTES}
+ * because the host decodes an image in full before it resizes it.
+ */
+export declare const MEDIA_UPLOAD_IMAGE_MAX_BYTES: number;
+/** The bytes-mode rolling window: per this many milliseconds, per mounted page host… */
+export declare const MEDIA_UPLOAD_WINDOW_MS = 60000;
+/** …at most this many admitted bytes uploads… */
+export declare const MEDIA_UPLOAD_MAX_PER_WINDOW = 8;
+/** …and this many admitted bytes. */
+export declare const MEDIA_UPLOAD_MAX_BYTES_PER_WINDOW: number;
+/** `bytes` is not a non-empty `ArrayBuffer`, or `mimeType` is present but not a string. */
+export declare const MEDIA_UPLOAD_INVALID_ERROR = "invalid media-upload request";
+export declare const MEDIA_UPLOAD_KIND_ERROR = "kind must be 'image', 'video' or 'audio'";
+export declare const MEDIA_UPLOAD_PURPOSE_ERROR = "purpose must be 'generationSource'";
+/** Over {@link MEDIA_UPLOAD_MAX_BYTES} (video, audio). */
+export declare const MEDIA_UPLOAD_TOO_LARGE_ERROR = "file exceeds the 64 MB upload limit";
+/** Over {@link MEDIA_UPLOAD_IMAGE_MAX_BYTES} (image). */
+export declare const MEDIA_UPLOAD_IMAGE_TOO_LARGE_ERROR = "file exceeds the 24 MB image upload limit";
+/** Bytes mode only: the host holds no block token. Checked before the cap and the window. */
+export declare const MEDIA_UPLOAD_NO_TOKEN_ERROR = "no block token";
+/** The sniffed content is not one of the requested kind's types. */
+export declare const MEDIA_UPLOAD_TYPE_ERROR: Readonly<Record<BlockMediaKind, string>>;
+export declare const MEDIA_UPLOAD_MIME_MISMATCH_ERROR = "mimeType does not match the file's content";
+/** The bytes-mode window is full. Retryable. */
+export declare const MEDIA_UPLOAD_BUSY_ERROR = "busy";
+/** The kinds the bridge knows. */
+export declare const MEDIA_UPLOAD_KINDS: readonly BlockMediaKind[];
+export declare function isMediaKind(v: unknown): v is BlockMediaKind;
+/** The per-file cap for a kind, and the refusal past it. */
+export declare function mediaUploadCap(kind: BlockMediaKind): {
+    maxBytes: number;
+    error: string;
+};
+/** One admitted bytes upload in the window: when, and how many bytes. */
+export type MediaUploadWindowEntry = {
+    at: number;
+    size: number;
+};
+/**
+ * The content type of `bytes` WITHIN the requested kind, by magic bytes, or
+ * `null` when the content is none of that kind's types (a PNG sent as `audio`
+ * is `null`: a type refusal). WebM is `video/webm` under `video` and
+ * `audio/webm` under `audio`.
+ */
+export declare function sniffMediaBytes(kind: BlockMediaKind, u8: Uint8Array): string | null;
+/** A declared MIME type as the host compares it: lowercased, `;params` cut, `audio/x-wav` read as `audio/wav`. */
+export declare function normaliseMediaMimeType(mimeType: string): string;
+/**
+ * The host's decision for one `OPEN_MEDIA_UPLOAD`, in the host's order, from
+ * step 4 of the contract on (the caller has already dropped an unroutable
+ * `requestId`; review mode and readiness do not exist in the mock):
+ *   1. `kind` not known → kind error; `purpose` not `'generationSource'` →
+ *      purpose error;
+ *   2. no `bytes` (absent or `null`) → PICKER mode (not windowed: a human
+ *      picks);
+ *   3. `bytes` not a non-empty `ArrayBuffer`, or a non-string `mimeType` →
+ *      invalid;
+ *   4. no block token (`opts.noToken`) → `no block token`, before the cap
+ *      and the window;
+ *   5. over the kind's cap ({@link mediaUploadCap}: 24 MiB for an image,
+ *      64 MiB for video and audio) → too large, before the window, so an
+ *      over-cap file is never `busy` (a retry could never succeed);
+ *   6. the window, NOT recording, so a full window refuses `busy` before any
+ *      sniffing;
+ *   7. the sniffed content in the kind's set → else the kind's type error;
+ *   8. a present `mimeType` (normalised) equal to the sniffed type → else
+ *      mismatch;
+ *   9. record the upload in the window. Only an upload that will run counts.
+ * Returns the pruned window to store back.
+ */
+export declare function admitMediaUpload(raw: {
+    kind?: unknown;
+    purpose?: unknown;
+    bytes?: unknown;
+    mimeType?: unknown;
+}, recent: readonly MediaUploadWindowEntry[], now: number, opts?: {
+    noToken?: boolean;
+}): {
+    result: {
+        ok: true;
+        mode: 'picker';
+        kind: BlockMediaKind;
+    } | {
+        ok: true;
+        mode: 'bytes';
+        kind: BlockMediaKind;
+        bytes: ArrayBuffer;
+        mimeType: string;
+    } | {
+        ok: false;
+        error: string;
+    };
+    recent: MediaUploadWindowEntry[];
+};
+/**
+ * The mock host's canned uploads, one per kind. A kind left out answers
+ * {@link DEFAULT_MOCK_MEDIA_UPLOADS}; `null` for a kind = the viewer closes that
+ * picker (bytes mode, which has no picker, then answers the default).
+ */
+export type MockMediaUploads = Partial<Record<BlockMediaKind, BlockMediaUploadInfo | null>>;
+/**
+ * What the mock host answers when no canned upload is configured for a kind.
+ * Every field differs between kinds, so a block that mixes two up shows it.
+ * The URLs are deliberately unresolvable: the mock uploads nothing.
+ */
+export declare const DEFAULT_MOCK_MEDIA_UPLOADS: Readonly<Record<BlockMediaKind, BlockMediaUploadInfo>>;
+/**
+ * The mock host's whole answer to one routable `OPEN_MEDIA_UPLOAD`, on a page
+ * surface: {@link admitMediaUpload}, then
+ *  - picker mode: the canned upload for the kind, or a bare reply (dismissed)
+ *    when that kind is canned `null`;
+ *  - bytes mode: the canned upload for the kind (the default when it is
+ *    `null`: there is no viewer to dismiss), carrying what the host would
+ *    report for THESE bytes: the sniffed `mimeType` and the buffer's size for
+ *    video and audio; `image/jpeg` and the canned size for an image, which the
+ *    host re-encodes;
+ *  - `forcedError`, when set, replaces a success: the stand-in for the
+ *    decode and upload failures the mock cannot produce. A bytes upload it
+ *    fails has still been admitted, so it still counts against the window, as
+ *    on the host. ONE value is placed where the host checks it instead:
+ *    `no block token` refuses a bytes upload right after the buffer check,
+ *    before the cap and the window, and is not counted.
+ */
+export declare function mockMediaUploadReply(args: {
+    payload: {
+        kind?: unknown;
+        purpose?: unknown;
+        bytes?: unknown;
+        mimeType?: unknown;
+    };
+    canned: MockMediaUploads;
+    forcedError: string | undefined;
+    recent: readonly MediaUploadWindowEntry[];
+    now: number;
+}): {
+    reply: {
+        selected: BlockMediaUploadInfo;
+    } | {
+        error: string;
+    } | Record<string, never>;
+    recent: MediaUploadWindowEntry[];
+};
+//# sourceMappingURL=mediaUploadBytes.d.ts.map