@civitai/blocks-react 0.65.1 → 0.66.0

package/README.md

@@ -106,7 +106,7 @@ the package's type declarations (IDE hover / autocomplete on the package root) a
 the authoritative list of what exists.
 
 Exported from the package root with no snippet in this section, as of this
-writing: `useGatedImages()`, `usePublishGenerationOutputs()`, `useSaveImage()`,
+writing: `useGatedImages()`, `usePublishGenerationOutputs()`,
 `useTip()` and `useTipAllowance()` — for the tip pair, the
 [`TipButton`](#the-ui-subexport) row documents the intended usage and the
 allowance-sharing rule. `useDirectLoad()` is covered under
@@ -1143,10 +1143,25 @@ The viewer searches in host chrome; the block only ever sees the one resource it
 picked. DISCOVERY ONLY — the returned `versionId` is re-validated + re-priced
 server-side at estimate/submit.
 
-🔴 **Pass NO `baseModelGroup` by default.** It is an optional FILTER, and the host
-hides every resource outside the family you pass — so a hardcoded ecosystem makes
-the viewer's own valid LoRAs invisible and the picker look empty or broken. Omit
-it and the viewer sees everything of that type.
+🔴 **OMIT `baseModelGroup` BY DEFAULT, and never pass a HARDCODED ecosystem.** It
+is an ecosystem-family FILTER, not a label: the host hides every resource outside
+the family you pass, so a literal ecosystem string makes the viewer's own valid
+LoRAs invisible and the picker look empty or broken. Omit it for an unconstrained
+pick and the viewer sees everything of that type. Pass it ONLY when the block
+already holds a chosen checkpoint the pick has to match, and then DERIVE it from
+that checkpoint (`checkpoint.baseModel`). For stack and matrix apps that pair
+LoRAs with a checkpoint, this is the recommended pattern: a derived family keeps
+incompatible LoRAs out of the picker. This hook is PAGE-ONLY, and a page slot has
+no `context.checkpoint` (that field lives on `ModelSlotContext` alone), so the
+family comes from `BlockResourceInfo.baseModel`, the `baseModel` of a Checkpoint
+a picker returned earlier.
+
+For a complete multi-LoRA app, see
+[`starters/examples/generate-studio`](https://github.com/civitai/civitai-app-starters/tree/main/starters/examples/generate-studio):
+`src/components/ModelSection.tsx` opens the picker once per LoRA slot, up to
+`MAX_LORAS`, with a `baseModelGroup` derived from the selected checkpoint, and
+`keepCompatibleLoras` (`src/studio/setup.ts`) re-filters the stack when the
+checkpoint changes, dropping LoRAs made for another family.
 
 ```tsx
 const { open } = useResourcePicker();
@@ -1157,12 +1172,8 @@ if (picked) {
 }
 ```
 
-Constrain it **only** when the block already holds a chosen checkpoint the pick has
-to match — and then derive the family from that checkpoint, never from a literal.
-🔴 **This hook is PAGE-ONLY, and a page slot has no `context.checkpoint`** — that
-field lives on `ModelSlotContext` alone, so the family comes from
-`BlockResourceInfo.baseModel`, the `baseModel` of a Checkpoint this same picker
-returned earlier:
+Constrained to the family of a checkpoint the block already holds, derived from
+that checkpoint, never from a literal:
 
 ```tsx
 const { open } = useResourcePicker();
@@ -1197,6 +1208,66 @@ if (img) {
 }
 ```
 
+### `useSaveImage()`
+
+Ask the host to download a file to the viewer's device. **A block cannot
+download anything itself.** Its sandbox lacks `allow-downloads`, and the
+validator refuses that token for unverified blocks, so an
+`<a href="blob:…" download>` click silently does nothing. 🔴 **This hook is the
+sanctioned way to deliver a file**, including one the block produced in the tab.
+Pass exactly ONE of three inputs, each gated differently by the host:
+
+- **`{ url }`**: the block's own generation output. The host allowlists the
+  origin to the civitai image CDN and refuses any other.
+- **`{ imageId }`**: an image from another user, read through the same
+  per-viewer gate as `useGatedImages()`. A withheld image is never saved.
+- **`{ bytes }`**: an `ArrayBuffer` the block made in the tab, such as a healed
+  image or a JSON sidecar. 🔴 **Page apps only.** The host classifies it by
+  CONTENT. It accepts PNG, WebP and JPEG by magic bytes. Anything else must be
+  valid UTF-8 with no NUL byte: it is saved as JSON when it parses and
+  `filename` ends `.json` (any case) once the host has replaced each `?` and
+  `#` with `_`, and as plain text otherwise. A GIF, a zip
+  or other binary is refused with `file type is not allowed`. The host forces
+  the extension from the classified type. The cap is 50 MiB, and the hook
+  refuses a larger buffer before sending it: `file exceeds the maximum save
+  size`. The buffer is copied, not transferred, so you can keep displaying it.
+
+🔴 **On a host that predates the `bytes` variant, `saveImage({ bytes })` rejects
+with `invalid save-image request`.** The host also replies that when the input
+is not exactly one variant, or when `bytes` is empty or not an `ArrayBuffer`.
+Pass `await blob.arrayBuffer()`, not the `Blob` or a `Uint8Array`. The promise
+resolves once the host has started the download. On any refusal it rejects with
+the host's error string, which can also be `busy` when too many saves are in
+flight.
+
+```tsx
+import { useSaveImage } from '@civitai/blocks-react';
+
+const { saveImage } = useSaveImage();
+
+// A file healed in the tab. It never leaves the device except to the viewer's disk.
+const healed: Blob = await healPngMetadata(file);
+await saveImage({ bytes: await healed.arrayBuffer(), filename: 'healed.png' });
+
+// Its JSON sidecar. The .json filename makes valid JSON save as .json rather than .txt.
+const sidecar = new TextEncoder().encode(JSON.stringify(metadata, null, 2));
+try {
+  await saveImage({ bytes: sidecar.slice().buffer, filename: 'healed.json' });
+} catch (err) {
+  // 'invalid save-image request' here means this host cannot save bytes yet.
+  setStatus(`Could not save the sidecar: ${(err as Error).message}`);
+}
+
+// The block's own generation output, or another user's image.
+await saveImage({ url: output.url, filename: 'render.png' });
+await saveImage({ imageId: cell.imageId });
+```
+
+Under `createMockHost` / `Harness` the `bytes` variant is classified the same
+way. `onSaveBytes` reports what would have been downloaded, and `saveImageError`
+forces a refusal. Pass `saveImageError: 'invalid save-image request'` to test a
+host without the variant. `dev:live` refuses every save.
+
 ### `useGenerationResources()`
 
 Rehydrate a saved set of generation resources by version id — WITHOUT re-opening

package/dist/hooks/useSaveImage.d.ts

@@ -1,6 +1,7 @@
 /**
- * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` is
- * required — the two variants map to the host's two download paths:
+ * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` /
+ * `bytes` is required — the three variants map to the host's three download
+ * paths, each with its own security gate:
  *
  *  - `{ url }` — the block's OWN fresh output (e.g. an orchestration blob it has
  *    no `imageId` for yet). The host ALLOWLISTS the URL's origin to the civitai
@@ -9,32 +10,70 @@
  *  - `{ imageId }` — a cross-user grid image (e.g. a benchmark cell). The host
  *    resolves it through the SAME per-viewer gated read that backs
  *    `useGatedImages()`, so a withheld/above-ceiling image can never be saved.
+ *  - `{ bytes }` — a file the block PRODUCED IN THE VIEWER'S TAB (a healed
+ *    image, a JSON sidecar, a text export) that exists nowhere else. 🔴 **This
+ *    is the sanctioned way for an in-tab tool to deliver a file.** A blob-anchor
+ *    `<a download>` does nothing in a block — its sandbox lacks
+ *    `allow-downloads`, and the validator refuses that token for unverified
+ *    blocks — so do not build one. 🔴 **Page apps only**: a slot (model) block's
+ *    host has no `SAVE_IMAGE` handler, so its generic unhandled-request reply
+ *    answers at once and the call rejects with `unsupported on this host`.
+ *
+ *    The host classifies by CONTENT and never trusts `filename` to make a file
+ *    acceptable: PNG / WebP / JPEG by magic bytes; otherwise valid UTF-8 with
+ *    no NUL byte, saved as JSON when it parses AND `filename` ends `.json`
+ *    (case-insensitive) after the host replaces each `?` and `#` with `_` (so
+ *    `data.json?v=2` saves as text), else as text/plain. Anything else — a GIF, a zip,
+ *    random binary — is refused with `file type is not allowed`, and an empty
+ *    buffer with `invalid save-image request`. The saved extension is forced
+ *    from the classified type, whatever `filename` says. The cap is 50 MiB of
+ *    raw bytes.
+ *    The buffer is COPIED across `postMessage`, never transferred, so the block
+ *    can keep displaying it.
  */
 export type SaveImageInput = {
     url: string;
     imageId?: never;
+    bytes?: never;
     filename?: string;
 } | {
     imageId: number;
     url?: never;
+    bytes?: never;
+    filename?: string;
+} | {
+    bytes: ArrayBuffer;
+    url?: never;
+    imageId?: never;
     filename?: string;
 };
 export interface UseSaveImage {
     /**
-     * Ask the host to DOWNLOAD an image the block already displays — the host
-     * fetches the blob in its unsandboxed top frame and triggers the browser
-     * "Save As". A sandboxed opaque-origin block lacks `allow-downloads`, so it
-     * otherwise can only copy a URL; this bridge is the only way to save a paid
-     * output. Resolves once the host has started the download; rejects with the
-     * host's error string on failure (a disallowed URL origin, a withheld image,
-     * an over-size blob, or a fetch failure), or the transport timeout — the hook
-     * never hangs.
+     * Ask the host to DOWNLOAD a file — an image the block already displays, or
+     * bytes it produced in the tab — in the host's unsandboxed top frame, which
+     * triggers the browser "Save As". A sandboxed opaque-origin block lacks
+     * `allow-downloads`, so this bridge is the only way a block can save a file.
+     * Resolves once the host has started the download; rejects with the host's
+     * error string on failure (a disallowed URL origin, a withheld image, a
+     * disallowed file type, an over-size file, a fetch failure, or `busy`), or
+     * the transport timeout — the hook never hangs.
+     *
+     * 🔴 One call is refused BEFORE sending, with the host's own string: a
+     * `bytes` buffer over the 50 MiB cap rejects with `file exceeds the maximum
+     * save size`, so it is never copied across `postMessage` just to be refused.
+     * Everything else is forwarded and judged by the host, which replies
+     * `invalid save-image request` to a request that is not exactly one variant,
+     * to a `bytes` that is not a non-empty `ArrayBuffer` (pass
+     * `await blob.arrayBuffer()`, or `view.slice().buffer` for a typed array —
+     * not the `Uint8Array` or `Blob` itself), and, on a host that predates the
+     * `bytes` variant, to every `bytes` save; treat that string as "this host
+     * cannot save bytes yet".
      */
     saveImage: (input: SaveImageInput) => Promise<void>;
 }
 /**
- * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
- * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ * Download a file via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the security posture of each variant.
  *
  * @example
  * const { saveImage } = useSaveImage();
@@ -42,6 +81,8 @@ export interface UseSaveImage {
  * await saveImage({ url: output.url, filename: 'my-render.png' });
  * // a cross-user grid cell (routed through the gated per-viewer read):
  * await saveImage({ imageId: cell.imageId });
+ * // a file produced in the tab (classified by content host-side; page apps only):
+ * await saveImage({ bytes: healedPng, filename: 'healed.png' });
  */
 export declare function useSaveImage(): UseSaveImage;
 //# sourceMappingURL=useSaveImage.d.ts.map

package/dist/hooks/useSaveImage.js

@@ -1,10 +1,36 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
+import { SAVE_BYTES_MAX_BYTES, SAVE_BYTES_TOO_LARGE_ERROR } from '../internal/saveBytes.js';
 import { sendTypedRequest } from '../transport/transport.js';
 /**
- * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
- * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ * Build the wire payload. The ONLY client-side refusal is the cap, so an
+ * over-cap buffer is never copied across `postMessage` just to be refused.
+ * Everything else is forwarded as given and the host judges it: a `bytes`
+ * input is sent with whatever `url` / `imageId` came with it (the host refuses
+ * the mix), and a `url` / `imageId` input keeps its pre-`bytes` behaviour
+ * (`url` wins when both are set).
+ */
+function toWirePayload(input) {
+    const raw = input;
+    if (raw.bytes !== undefined) {
+        if (raw.bytes instanceof ArrayBuffer && raw.bytes.byteLength > SAVE_BYTES_MAX_BYTES) {
+            throw new Error(SAVE_BYTES_TOO_LARGE_ERROR);
+        }
+        const payload = { bytes: raw.bytes, filename: raw.filename };
+        if (raw.url !== undefined)
+            payload.url = raw.url;
+        if (raw.imageId !== undefined)
+            payload.imageId = raw.imageId;
+        return payload;
+    }
+    return 'url' in input && input.url !== undefined
+        ? { url: input.url, filename: input.filename }
+        : { imageId: input.imageId, filename: input.filename };
+}
+/**
+ * Download a file via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the security posture of each variant.
  *
  * @example
  * const { saveImage } = useSaveImage();
@@ -12,12 +38,12 @@ import { sendTypedRequest } from '../transport/transport.js';
  * await saveImage({ url: output.url, filename: 'my-render.png' });
  * // a cross-user grid cell (routed through the gated per-viewer read):
  * await saveImage({ imageId: cell.imageId });
+ * // a file produced in the tab (classified by content host-side; page apps only):
+ * await saveImage({ bytes: healedPng, filename: 'healed.png' });
  */
 export function useSaveImage() {
     const saveImage = useCallback(async (input) => {
-        const payload = 'url' in input && input.url !== undefined
-            ? { url: input.url, filename: input.filename }
-            : { imageId: input.imageId, filename: input.filename };
+        const payload = toWirePayload(input);
         const reply = await sendTypedRequest(getTransport(), { type: 'SAVE_IMAGE', payload }, 'SAVE_IMAGE_RESULT');
         throwOnFailedReply(reply, 'failed to save image');
     }, []);

package/dist/internal/liveHost.js

@@ -1640,8 +1640,14 @@ export function createLiveHost(options) {
                         //   • `imageId` — the host resolves it through the SAME per-viewer
                         //     gated read that backs GET_IMAGES_BY_IDS, so a withheld or
                         //     above-ceiling image can never be coerced into a download.
+                        //   • `bytes` (#583) — refused here too. Its gate (content
+                        //     classification, the cap) is reproducible, and `createMockHost`
+                        //     reproduces it; but a dev:live "download" would be this
+                        //     harness's tab saving a file, which proves nothing about the
+                        //     production host's page-only rule or its top-frame download.
+                        //     One honest refusal for every variant keeps this branch simple.
                         //
-                        // This harness has NEITHER gate. The allowlist is the production
+                        // This harness has NEITHER of the url / imageId gates. The allowlist is the production
                         // host's, not this SDK's — there is no origin set here to check
                         // against — so a dev-side "download it anyway" would accept URLs
                         // production refuses and let a block ship having never once handled

package/dist/internal/mockHost.d.ts

@@ -40,14 +40,17 @@
 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 BlockPublishedModel, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockPrepareTrainingDatasetHostError, type BlockRunTrainingHostError, type BlockTrainingRejectionReason, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
- * = every submit RESOLVES an insufficient-Buzz `failed` snapshot, priced
- * (exercises the per-cell Top-Up CTA); `'some'` = ~1 in 3 submits fail.
+ * = every submit fails as if the viewer were OUT OF BUZZ, until an
+ * `OPEN_BUZZ_PURCHASE` resets the mode to `'none'`; `'some'` = ~1 in 3
+ * submits fail with a generic error.
  *
- * 🔴 THE TWO OUTCOMES ARE NO LONGER THE SAME SHAPE (civitai/civitai-app-starters#251).
- * `'all'`/`'insufficient'` RESOLVE — they carry a `cost`, so they are a budget
- * OUTCOME. `'some'` **REJECTS** with `code: 'exception'` — it emits the host's
- * cost-less `failureSnapshot(err)`. A mixed grid therefore needs both a
- * `snap.status` branch and a `catch`.
+ * 🔴 EVERY FAILING MODE **REJECTS** with `WorkflowSubmitError` code
+ * `'exception'` — each emits the host's cost-less `failureSnapshot(err)`. That
+ * includes `'all'`/`'insufficient'`, which until this was fixed RESOLVED a
+ * priced `failed` snapshot. Production never does that for an empty wallet: the
+ * orchestrator refuses the debit, the server throws, and the host replies with
+ * `failureSnapshot(err)` (no `cost`). See {@link MockBuzzScenario}. A priced,
+ * RESOLVING refusal is a spend CAP — {@link MockGenerationScenario.submitCapRefusal}.
  */
 export type MockHostFailMode = 'none' | 'some' | 'all' | 'insufficient';
 /**
@@ -152,15 +155,15 @@ export interface MockGenerationScenario {
      * error }` with **no `cost`**. `useBuzzWorkflow().submit()` rejects with a
      * `WorkflowSubmitError` whose `code` is `'exception'`.
      *
-     * 🔴 THIS IS THE PRODUCER THE OTHER SUBMIT KNOBS DO NOT SIMULATE, and that gap
-     * is how civitai/civitai-app-starters#251 stayed invisible: the balance /
-     * `insufficient` knobs model a budget REJECTION (a priced outcome the block
-     * recovers from with a top-up), so a block author testing "what if submit goes
-     * wrong" only ever saw the arm that resolves. The `failEstimate` knob is the
-     * estimate-side twin of this one.
+     * This knob was added for civitai/civitai-app-starters#251, when no other submit
+     * knob produced a rejection at all. The out-of-Buzz knobs
+     * ({@link MockBuzzScenario}) now emit this same shape, because production does;
+     * this one stays as the way to inject an arbitrary server message with the
+     * wallet untouched. The `failEstimate` knob is the estimate-side twin of this
+     * one.
      *
-     * Checked FIRST, before the disallowed-account / insufficient-Buzz / generic
-     * paths: a host-side throw pre-empts every server-side decision.
+     * Checked FIRST, before the disallowed-account / spend-cap / out-of-Buzz /
+     * generic paths: a host-side throw pre-empts every server-side decision.
      *
      * Default: unset (submits behave normally).
      */
@@ -171,6 +174,28 @@ export interface MockGenerationScenario {
      * check how your block's developer-facing error surface renders one.
      */
     failSubmitExceptionMessage?: string;
+    /**
+     * Make every SUBMIT come back as a server SPEND-CAP refusal — the priced,
+     * RESOLVING shape `{ workflowId:'failed', status:'failed', cost:{ total }, error }`,
+     * where `total` is this generation's cost. `useBuzzWorkflow().submit()`
+     * RESOLVES it (no rejection); the block reads `status === 'failed'`.
+     *
+     * This is what the real submit returns when a cap stops the run before
+     * anything is spent: the app's per-generation budget, the viewer's daily (or
+     * private-run) cap, the per-app consent budget, the app's spend or rate limit,
+     * or a dev-session cap. 🔴 **Buying Buzz fixes none of them**, so a block must
+     * not offer a top-up for this reply. Running OUT of Buzz is a different shape —
+     * a rejection; see {@link MockBuzzScenario}.
+     *
+     * Pass the server's text (e.g. `'insufficient buzz budget: estimate 600 exceeds
+     * budget 200'`), or `true` for a default message. Checked after the
+     * disallowed-account path and before the out-of-Buzz path, matching the real
+     * ordering: the caps are checked before the orchestrator is asked to debit.
+     * Live-tunable via `setScenario({ generation: { submitCapRefusal } })`; set it
+     * to `undefined` there to clear it. URL: `?capRefusal=1` (or `=<text>`).
+     * Default: unset.
+     */
+    submitCapRefusal?: string | true;
     /** A single result image url (or `(body) => url`). */
     image?: ImageSpec;
     /**
@@ -248,24 +273,43 @@ export declare const MOCK_TRAINING_DATASET_GONE_ERROR = "training dataset not fo
 export declare const MOCK_TRAINING_NONE_ELIGIBLE_ERROR = "none of the requested images can be used for training";
 export declare const MOCK_TRAINING_NONE_IMPORTED_ERROR = "none of the requested images could be prepared for training";
 /**
- * BUZZ scenario controls — simulate a balance so the insufficient-Buzz / top-up
- * UX is exercisable. The mock host treats `balance` as a spendable wallet:
- * each succeeding generation DEBITS its cost; a submit whose cost would exceed
- * the remaining balance resolves to an insufficient-Buzz `failed` snapshot
- * (exercising the Top-Up CTA), and `OPEN_BUZZ_PURCHASE` REFILLS the balance.
+ * BUZZ scenario controls — simulate a viewer who runs out of Buzz. The mock host
+ * treats `balance` as a spendable wallet: each succeeding generation DEBITS its
+ * cost, a submit whose cost would exceed the remaining balance fails as
+ * OUT OF BUZZ, and `OPEN_BUZZ_PURCHASE` REFILLS the balance.
+ *
+ * 🔴 OUT OF BUZZ **REJECTS** — `useBuzzWorkflow().submit()` throws a
+ * `WorkflowSubmitError` with code `'exception'`, the reason on
+ * `err.snapshot.error`. That is what production does. The orchestrator refuses
+ * the debit (HTTP 403), the server turns that into a thrown `BAD_REQUEST`, and
+ * the host replies with its cost-less `failureSnapshot(err)`. These knobs used to
+ * RESOLVE a priced `failed` snapshot instead, so a block tested against the mock
+ * could build a "resolved refusal → top-up" flow that production never reaches.
+ *
+ * Nothing structural tells this rejection apart from other `'exception'`s (the
+ * server message is upstream text, not a contract). To decide whether to offer
+ * a top-up, compare the viewer's spendable balance (`useBuzzBalance()`) with the
+ * quoted cost — never the error text. In the mock, that balance is
+ * {@link MockHostOptions.buzzBalance}, which is separate from `balance` below.
+ *
+ * A priced, RESOLVING refusal is a spend CAP, which a top-up cannot fix — see
+ * {@link MockGenerationScenario.submitCapRefusal}.
  */
 export interface MockBuzzScenario {
     /**
      * Simulated spendable balance. When set, generations debit against it and a
-     * gen that would exceed it returns an insufficient-Buzz outcome. When
-     * `undefined`, balance is NOT simulated (back-compat: only the legacy
-     * `failMode` drives insufficiency).
+     * gen that would exceed it is refused as out of Buzz (a REJECTION, see above).
+     * When `undefined`, balance is NOT simulated (back-compat: only the legacy
+     * `failMode` and {@link insufficient} drive the out-of-Buzz path).
      */
     balance?: number;
     /**
-     * Force every submit down the insufficient-Buzz path regardless of balance.
-     * Equivalent to the legacy `failMode: 'insufficient'`; provided here so the
-     * insufficient UX is reachable from the `buzz` group alone.
+     * Force every submit down the out-of-Buzz path regardless of balance — it
+     * REJECTS with code `'exception'` (see above). Equivalent to the legacy
+     * `failMode: 'insufficient'`; provided here so the path is reachable from the
+     * `buzz` group alone. `OPEN_BUZZ_PURCHASE` clears it — and clears
+     * `failMode: 'insufficient' | 'all'` too (back to `'none'`), so a top-up
+     * followed by a retry succeeds whichever knob forced the out-of-Buzz state.
      */
     insufficient?: boolean;
 }
@@ -423,8 +467,8 @@ export interface MockHostOptions {
     consentGrantable?: boolean;
     /**
      * How submits behave. Default `'none'` (all succeed). See
-     * {@link MockHostFailMode} — `'some'` REJECTS while `'all'`/`'insufficient'`
-     * RESOLVE, since #251.
+     * {@link MockHostFailMode} — every failing mode REJECTS with code
+     * `'exception'`; `'all'`/`'insufficient'` model an out-of-Buzz viewer.
      */
     failMode?: MockHostFailMode;
     /**
@@ -476,8 +520,8 @@ export interface MockHostOptions {
      */
     generation?: MockGenerationScenario;
     /**
-     * BUZZ scenario: simulated balance + force-insufficient. See
-     * {@link MockBuzzScenario}.
+     * BUZZ scenario: simulated balance + force-out-of-Buzz. Both REJECT the
+     * submit, as production does. See {@link MockBuzzScenario}.
      */
     buzz?: MockBuzzScenario;
     /**
@@ -485,8 +529,9 @@ export interface MockHostOptions {
      * block via the host-mediated `GET_BUZZ_BALANCE` → `BUZZ_BALANCE_RESULT`
      * bridge (what the `useBuzzBalance` hook reads). Distinct from the
      * {@link MockBuzzScenario.balance} spendable-wallet knob, which only drives
-     * the insufficient-Buzz / top-up SUBMIT path — this is the displayable
-     * per-pool balance. Absent → {@link DEFAULT_BUZZ_BALANCE} (a plausible
+     * the out-of-Buzz SUBMIT rejection — this is the displayable per-pool balance,
+     * and the number a block should compare with the quoted cost to decide on a
+     * top-up. Set both when exercising that flow. Absent → {@link DEFAULT_BUZZ_BALANCE} (a plausible
      * non-zero wallet, so a block shows a balance out of the box).
      */
     buzzBalance?: MockBuzzBalance;
@@ -731,6 +776,46 @@ export interface MockHostOptions {
      * `setScenario({ runTrainingCapRefusal: undefined })` clears it.
      */
     runTrainingCapRefusal?: string;
+    /**
+     * Force `SAVE_IMAGE` to reply with this `error` instead of saving — any of
+     * the host's free-text refusals (`'image url is not allowed'`,
+     * `'image is not available'`, `'busy'`, …), or
+     * `'invalid save-image request'` to model a host that PREDATES the `bytes`
+     * variant (what production replies to `saveImage({ bytes })` until the host
+     * ships it). Applies to every variant; checked after the request-shape gate,
+     * so an invalid request still gets `invalid save-image request`. Absent →
+     * the save succeeds (subject to the `bytes` classification below).
+     * Live-tunable via {@link MockHost.setScenario}; `undefined` clears it.
+     *
+     * The `bytes` variant is classified exactly as the host's contract says
+     * (civitai/civitai-app-starters#583): PNG / WebP / JPEG by magic bytes, else
+     * UTF-8 text with no NUL (JSON when it parses and the CLEANED `filename` —
+     * `?`/`#` replaced with `_`, path dropped — ends `.json`, case-insensitive),
+     * else `file type is not allowed`; an empty buffer,
+     * `invalid save-image request`; over the host's byte cap,
+     * `file exceeds the maximum save size`. 🔴 What the mock cannot model: that
+     * the variant is PAGE-ONLY (it does not know which surface the block renders
+     * on; a slot host has no `SAVE_IMAGE` handler and rejects it with
+     * `unsupported on this host`),
+     * the host's concurrency and per-window rate limits (`busy` — force it
+     * here), and the real browser
+     * download. {@link onSaveBytes} reports what would have been saved.
+     */
+    saveImageError?: string;
+    /**
+     * Called with each `bytes` save the mock ACCEPTS — the classified `mimeType`
+     * (one of `image/png`, `image/webp`, `image/jpeg`, `application/json`,
+     * `text/plain`), the download `filename` exactly as the host cleans it (the
+     * same character rules, then the extension forced from that type), and the
+     * `bytes` themselves.
+     * The mock cannot trigger a browser download, so this is the observable a
+     * test or harness asserts on.
+     */
+    onSaveBytes?: (file: {
+        bytes: ArrayBuffer;
+        mimeType: string;
+        filename: string;
+    }) => void;
     /**
      * Buzz pools a `SUBMIT_WORKFLOW` must REJECT when named in `body.accountType`
      * — simulates the real backend's content-rating clamp. The real host throws a
@@ -895,7 +980,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' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes'>;
+export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes' | 'saveImageError'>;
 /** Runtime Buzz-balance handle exposed on {@link MockHost.buzz}. */
 export interface MockBuzzHandle {
     /** Current simulated balance, or `undefined` when balance isn't simulated. */
@@ -941,8 +1026,9 @@ export declare function disallowedAccountError(accountType: BuzzAccountType): st
  * Reads the URL query toggles the gen-matrix dev harness uses, so a starter's
  * dev harness keeps working with `?viewer/?consent/?fail/?theme/?pick/?pickCkpt`.
  * Layer-1 additions: `?balance/?latency/?costPerGen/?failNext/?failRate/?seed`
- * map onto the new scenario groups so a dev can flip insufficient-buzz /
- * failures / latency without editing code.
+ * map onto the new scenario groups so a dev can flip out-of-Buzz /
+ * failures / latency without editing code. `?capRefusal=1` (or `=<text>`) sets
+ * {@link MockGenerationScenario.submitCapRefusal}.
  *
  * Returns a partial overlay applied ON TOP of explicit {@link MockHostOptions}
  * (URL wins — it's the interactive dev knob). No-op outside a browser.
@@ -987,7 +1073,7 @@ export declare function readMockHostUrlOptions(win?: (Window & typeof globalThis
  * const host = createMockHost({ generation: { failNext: 1, latencyMs: 1500 }, buzz: { balance: 5 } });
  * const uninstall = host.install();
  * // … drive the block / assertions …
- * host.buzz.setBalance(0);       // flip to insufficient mid-session
+ * host.buzz.setBalance(0);       // out of Buzz mid-session: submit() now rejects ('exception')
  * host.setScenario({ generation: { failRate: 1 } });
  * uninstall();
  */

package/dist/internal/mockHost.js

@@ -41,6 +41,7 @@ import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED
 import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
 import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, storageScopeDeniedPayload, } from './mockHostScopes.js';
 import { governsIdempotencyKey, idempotencyKeyDeniedMessage, idempotencyKeyRefusal, } from './mockHostIdempotency.js';
+import { SAVE_IMAGE_INVALID_REQUEST_ERROR, prepareSaveBytes, saveImageRequestKind, } from './saveBytes.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
@@ -279,8 +280,15 @@ const DEFAULT_GENERATION_SOURCE_UPLOAD = {
  * `test/blockInitV2.test.ts` — they are one key set in four places.
  */
 const DEFAULT_VIEWER = { id: 2, username: 'dev-viewer', signedIn: true };
+/**
+ * The out-of-Buzz rejection's `error`. Production's text is whatever the
+ * orchestrator's 403 said (or the server's generic insufficient-funds default),
+ * so neither this string nor the real one is a contract — never branch on it.
+ */
 const INSUFFICIENT_BUZZ_ERROR = 'Insufficient Buzz to run this generation.';
 const GENERIC_GEN_ERROR = 'Generation failed (simulated).';
+/** Default `error` for `generation.submitCapRefusal: true`. */
+const DEFAULT_SUBMIT_CAP_REFUSAL = 'Buzz spend cap reached (simulated).';
 /** Default message for a simulated balance-read failure ({@link MockHostOptions.buzzBalanceError}). */
 const DEFAULT_BUZZ_BALANCE_ERROR = 'balance unavailable';
 /**
@@ -582,8 +590,9 @@ function jsonByteSize(value) {
  * Reads the URL query toggles the gen-matrix dev harness uses, so a starter's
  * dev harness keeps working with `?viewer/?consent/?fail/?theme/?pick/?pickCkpt`.
  * Layer-1 additions: `?balance/?latency/?costPerGen/?failNext/?failRate/?seed`
- * map onto the new scenario groups so a dev can flip insufficient-buzz /
- * failures / latency without editing code.
+ * map onto the new scenario groups so a dev can flip out-of-Buzz /
+ * failures / latency without editing code. `?capRefusal=1` (or `=<text>`) sets
+ * {@link MockGenerationScenario.submitCapRefusal}.
  *
  * Returns a partial overlay applied ON TOP of explicit {@link MockHostOptions}
  * (URL wins — it's the interactive dev knob). No-op outside a browser.
@@ -680,6 +689,13 @@ export function readMockHostUrlOptions(win = globalThis
     if (failRate !== null && Number.isFinite(Number(failRate))) {
         generation.failRate = Number(failRate);
     }
+    // ?capRefusal=1|true → the default cap message; any other non-empty value is
+    // used as the server text verbatim.
+    const capRefusal = params.get('capRefusal');
+    if (capRefusal !== null && capRefusal.trim() !== '') {
+        generation.submitCapRefusal =
+            capRefusal === '1' || capRefusal === 'true' ? true : capRefusal;
+    }
     if (Object.keys(generation).length > 0)
         out.generation = generation;
     if (Object.keys(buzz).length > 0)
@@ -736,7 +752,7 @@ export function readMockHostUrlOptions(win = globalThis
  * const host = createMockHost({ generation: { failNext: 1, latencyMs: 1500 }, buzz: { balance: 5 } });
  * const uninstall = host.install();
  * // … drive the block / assertions …
- * host.buzz.setBalance(0);       // flip to insufficient mid-session
+ * host.buzz.setBalance(0);       // out of Buzz mid-session: submit() now rejects ('exception')
  * host.setScenario({ generation: { failRate: 1 } });
  * uninstall();
  */
@@ -813,6 +829,8 @@ export function createMockHost(options = {}) {
     let trainingDatasetError = options.trainingDatasetError;
     let trainingQuoteTotal = options.trainingQuoteTotal ?? DEFAULT_TRAINING_QUOTE_TOTAL;
     let runTrainingError = options.runTrainingError;
+    // SAVE_IMAGE: a forced-refusal knob (see `saveImageError`).
+    let saveImageError = options.saveImageError;
     let runTrainingCapRefusal = options.runTrainingCapRefusal;
     // App-subqueue bridge data + forced free-text-error knob. `appWorkflows` is
     // MUTABLE — CANCEL_APP_WORKFLOW marks the matching row canceled in place so a
@@ -1391,8 +1409,36 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
-                        // Insufficient-Buzz path: legacy failMode, the buzz scenario's
-                        // force flag, OR a simulated balance that can't cover this gen.
+                        // Spend-CAP refusal (`generation.submitCapRefusal`). The server
+                        // checks its caps (per-call budget, daily, consent, per-app, dev
+                        // session) BEFORE it asks the orchestrator to debit, so this comes
+                        // ahead of the out-of-Buzz path below.
+                        if (gen.submitCapRefusal !== undefined) {
+                            dispatchToBlock({
+                                type: 'WORKFLOW_SUBMITTED',
+                                payload: {
+                                    requestId,
+                                    snapshot: {
+                                        // The server stamps this `'failed'` sentinel on every cap
+                                        // refusal (a refused submit has no orchestrator id).
+                                        workflowId: 'failed',
+                                        status: 'failed',
+                                        // 🔴 THE PRICE IS LOAD-BEARING. The real server quotes the
+                                        // cost it refused to charge at every cap exit, and `cost`
+                                        // presence is what makes `submit()` RESOLVE this rather than
+                                        // reject it as an errored submit
+                                        // (civitai/civitai-app-starters#251). Do not drop it.
+                                        cost: { total: cost },
+                                        error: gen.submitCapRefusal === true
+                                            ? DEFAULT_SUBMIT_CAP_REFUSAL
+                                            : gen.submitCapRefusal,
+                                    },
+                                },
+                            });
+                            return;
+                        }
+                        // OUT-OF-BUZZ path: legacy failMode, the buzz scenario's force
+                        // flag, OR a simulated balance that can't cover this gen.
                         const balanceSimulated = typeof buzz.balance === 'number';
                         const insufficient = failMode === 'all' ||
                             failMode === 'insufficient' ||
@@ -1421,25 +1467,24 @@ export function createMockHost(options = {}) {
                                     snapshot: {
                                         workflowId: 'failed',
                                         status: 'failed',
-                                        // The `'failed'` id above matches the server, which stamps
-                                        // that same sentinel on every budget/cap refusal (a refused
-                                        // submit has no orchestrator id). Nothing here depends on the
-                                        // id — the price below is what makes this arm RESOLVE — but
-                                        // the mock must not teach a shape the wire never carries.
+                                        // 🔴 DELIBERATELY NO `cost` — the host's `failureSnapshot(err)`
+                                        // shape exactly, so `submit()` REJECTS with code
+                                        // `'exception'`. That is what production sends when a viewer
+                                        // is out of Buzz. The orchestrator answers the real submit
+                                        // with a 403. civitai's `throwOrchestratorFailure` maps that
+                                        // to `throwInsufficientFundsError`, a thrown `BAD_REQUEST`.
+                                        // `blocks.submitWorkflow`'s catch refunds the reservation and
+                                        // rethrows it, and the iframe host's SUBMIT_WORKFLOW handler
+                                        // catches the mutation's rejection into `failureSnapshot(err)`,
+                                        // which has no `cost`.
                                         //
-                                        // 🔴 THE PRICE IS LOAD-BEARING, NOT COSMETIC. The real server
-                                        // quotes the cost it refused to charge at EVERY budget/cap
-                                        // exit on the submit path — the per-call `buzzBudget` gate,
-                                        // the per-user daily cap, the per-app aggregate/velocity cap
-                                        // and the dev-tunnel session cap, on all three body kinds —
-                                        // and `cost` presence is exactly what tells a priced
-                                        // REJECTION apart from an errored submit
-                                        // (civitai/civitai-app-starters#251). Omitting it here made
-                                        // the mock's top-up path indistinguishable from a server
-                                        // exception, so `submit()` would reject it and the top-up UX
-                                        // would be unreachable in the harness that exists to
-                                        // exercise it. Do not drop this field.
-                                        cost: { total: cost },
+                                        // This arm used to carry `cost` and RESOLVE, on the theory
+                                        // that out-of-Buzz was one of the server's priced cap
+                                        // refusals. It is not: those caps compare against a budget,
+                                        // not the wallet, and only they quote a price. A block
+                                        // tested against the old shape built a "resolved refusal →
+                                        // top-up" flow that production never reaches. Do not add a
+                                        // `cost` back; the priced arm is `submitCapRefusal` above.
                                         error: INSUFFICIENT_BUZZ_ERROR,
                                     },
                                 },
@@ -1467,8 +1512,9 @@ export function createMockHost(options = {}) {
                                         // failed". The backend DOES have generic transient submit
                                         // failures — a fail-closed `unavailable` deny and a
                                         // missing-price-quote exit — but it returns those as PRICED,
-                                        // RESOLVING snapshots, which is a shape this mock does not
-                                        // yet simulate. Do not read this branch as covering them.
+                                        // RESOLVING snapshots. Simulate those with `submitCapRefusal`
+                                        // and the server's text; do not read this branch as covering
+                                        // them.
                                         error: GENERIC_GEN_ERROR,
                                     },
                                 },
@@ -1530,7 +1576,14 @@ export function createMockHost(options = {}) {
                         const newBalance = typeof buzz.balance === 'number' ? buzz.balance + 1000 : 1000;
                         if (typeof buzz.balance === 'number')
                             buzz.balance = newBalance;
+                        // A purchase ends EVERY forced out-of-Buzz state, not just the `buzz`
+                        // group's flag: `failMode: 'insufficient' | 'all'` is documented as
+                        // the same knob, and leaving it set made `?fail=insufficient` loop
+                        // reject → top-up → reject. `'some'` is a generic failure, not a
+                        // wallet, so a purchase leaves it alone.
                         buzz.insufficient = false;
+                        if (failMode === 'insufficient' || failMode === 'all')
+                            failMode = 'none';
                         dispatchToBlock({
                             type: 'BUZZ_PURCHASE_RESULT',
                             payload: { requestId, purchased: true, newBalance },
@@ -2430,23 +2483,42 @@ export function createMockHost(options = {}) {
                         return;
                     }
                     case 'SAVE_IMAGE': {
-                        // The mock host can't trigger a real browser download; it just
-                        // validates the request shape and acks so `useSaveImage()` resolves.
-                        // Exactly one of url / imageId must be present.
-                        const hasUrl = typeof typed.payload?.url === 'string' && typed.payload.url.length > 0;
-                        const hasId = typeof typed.payload?.imageId === 'number';
-                        if (hasUrl === hasId) {
-                            dispatchToBlock({
-                                type: 'SAVE_IMAGE_RESULT',
-                                payload: { requestId, ok: false, error: 'INVALID_REQUEST' },
-                            });
+                        // The mock host can't trigger a real browser download; it applies
+                        // the host's request-shape gate and, for `bytes`, the host's
+                        // CONTENT classifier (./saveBytes.ts), then acks so `useSaveImage()`
+                        // resolves. Exactly one of url / imageId / bytes must be present —
+                        // the same rule and string as the real host.
+                        if (!isRoutableRequestId(requestId))
                             return;
+                        const p = typed.payload ?? {};
+                        const saveReply = (r) => dispatchToBlock({ type: 'SAVE_IMAGE_RESULT', payload: { requestId, ...r } });
+                        // The host's exact shape predicate (./saveBytes.ts) — including that
+                        // a non-empty-ArrayBuffer `bytes` is required, and that ANY non-null
+                        // url/imageId beside a `bytes` is ambiguous.
+                        const kind = saveImageRequestKind(p);
+                        if (kind === 'invalid') {
+                            return saveReply({ ok: false, error: SAVE_IMAGE_INVALID_REQUEST_ERROR });
                         }
-                        dispatchToBlock({
-                            type: 'SAVE_IMAGE_RESULT',
-                            payload: { requestId, ok: true },
-                        });
-                        return;
+                        if (saveImageError !== undefined)
+                            return saveReply({ ok: false, error: saveImageError });
+                        if (kind === 'bytes' && p.bytes instanceof ArrayBuffer) {
+                            // The host's `prepareSaveBytes` (./saveBytes.ts): size cap, clean
+                            // the name, classify on the CLEANED name, force the extension.
+                            const prepared = prepareSaveBytes({
+                                bytes: p.bytes,
+                                filename: typeof p.filename === 'string' ? p.filename : undefined,
+                            });
+                            if (!prepared.ok)
+                                return saveReply(prepared);
+                            // A COPY, as production's structured-clone `postMessage` delivers
+                            // it — the block keeps (and may keep mutating) its own buffer.
+                            options.onSaveBytes?.({
+                                bytes: p.bytes.slice(0),
+                                mimeType: prepared.type,
+                                filename: prepared.filename,
+                            });
+                        }
+                        return saveReply({ ok: true });
                     }
                     case 'SET_USER_CHECKPOINT': {
                         // Persist the checkpoint override (mirrors the real host's
@@ -2620,6 +2692,8 @@ export function createMockHost(options = {}) {
             trainingQuoteTotal = patch.trainingQuoteTotal;
         if ('runTrainingError' in patch)
             runTrainingError = patch.runTrainingError;
+        if ('saveImageError' in patch)
+            saveImageError = patch.saveImageError;
         if ('runTrainingCapRefusal' in patch)
             runTrainingCapRefusal = patch.runTrainingCapRefusal;
         if (patch.appWorkflows !== undefined) {

package/dist/internal/saveBytes.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The `bytes` variant of `SAVE_IMAGE` — the strings both sides of the bridge
+ * agree on, and the mock host's copy of the host's CONTENT classifier.
+ *
+ * The contract is civitai/civitai-app-starters#583. The host owns the real
+ * classifier; this one exists so `createMockHost` (and so `dev:harness` and
+ * every block test) accepts and refuses the same buffers production does. Keep
+ * it exactly as narrow as the contract — a mock that accepts a GIF teaches a
+ * block that GIFs save.
+ */
+/**
+ * The cap on a `bytes` payload: 50 MiB of raw bytes (`ArrayBuffer.byteLength`,
+ * so a text or JSON payload is counted after UTF-8 encoding).
+ *
+ * 🔴 The host spells its OWN copy of this number (civitai/civitai,
+ * `saveImageDownload.ts`), and the two MUST match. Nothing in this repository
+ * can read the host's value, so a drift is invisible here until a block hits
+ * the host's refusal on a buffer this hook let through, or the hook refuses one
+ * the host would have saved. Kept local to this package (not exported from
+ * `@civitai/app-sdk`) so the hook needs no newer app-sdk peer.
+ */
+export declare const SAVE_BYTES_MAX_BYTES: number;
+/** Host refusal for a buffer over `SAVE_BYTES_MAX_BYTES`. Also the hook's own pre-send refusal. */
+export declare const SAVE_BYTES_TOO_LARGE_ERROR = "file exceeds the maximum save size";
+/** Host refusal for bytes that classify as none of PNG / WebP / JPEG / UTF-8 text. */
+export declare const SAVE_BYTES_TYPE_NOT_ALLOWED_ERROR = "file type is not allowed";
+/**
+ * Host refusal for a request that is not exactly one of `url` / `imageId` /
+ * `bytes`, for a `bytes` that is not a non-empty `ArrayBuffer`, and what a host
+ * that predates the `bytes` variant replies to one.
+ */
+export declare const SAVE_IMAGE_INVALID_REQUEST_ERROR = "invalid save-image request";
+/**
+ * Which `SAVE_IMAGE` variant a payload is, by the host's exact predicate
+ * (civitai/civitai `saveImageDownload.ts`, `resolveSaveImageRequest`). A
+ * non-null `bytes` wins the dispatch: ANY non-null `url` / `imageId` beside it
+ * (even `''` or `'5'`) is ambiguous and invalid, and `bytes` must be a
+ * non-empty `ArrayBuffer`. Without `bytes` (`null` or absent) exactly one of a
+ * non-empty string `url` / a positive-integer `imageId` must be present.
+ */
+export declare function saveImageRequestKind(p: {
+    url?: unknown;
+    imageId?: unknown;
+    bytes?: unknown;
+}): 'url' | 'id' | 'bytes' | 'invalid';
+/** The five types the host can classify a `bytes` payload as. */
+export type SaveBytesType = 'image/png' | 'image/webp' | 'image/jpeg' | 'application/json' | 'text/plain';
+/** The extension the host forces for each classified type. */
+export declare const SAVE_BYTES_EXTENSION: Record<SaveBytesType, string>;
+/**
+ * Classify a `bytes` payload by CONTENT — the host's `classifySaveBytes`.
+ * `filename` is the only hint and must already be CLEANED
+ * ({@link sanitizeSaveBytesFilename}): a name ending `.json` (case-insensitive)
+ * chooses JSON over text/plain for bytes that already parse as JSON, and it can
+ * never make a binary payload acceptable. Returns `null` for anything the host
+ * refuses (`file type is not allowed`).
+ */
+export declare function classifySaveBytes(bytes: ArrayBuffer, filename?: string): SaveBytesType | null;
+/**
+ * Clean a block-supplied `bytes` filename BEFORE classification reads its
+ * `.json` suffix. The name is not a URL, so every `?` and `#` is REPLACED with
+ * `_` (not cut at): `issue#42.json` → `issue_42.json` (still JSON),
+ * `data.json?v=2` → `data.json_v=2` (no longer `.json`, so text). Then: keep
+ * the text after the last `/` or `\`, collapse a repeated trailing extension,
+ * trim; absent or empty → `download`.
+ */
+export declare function sanitizeSaveBytesFilename(name: string | undefined | null): string;
+/**
+ * Replace the extension of a cleaned name with the classified type's own. First
+ * deletes every control and format character (`\p{Cc}` / `\p{Cf}`: bidi
+ * overrides, zero-width marks), trims, empty → `download`; then replaces a
+ * trailing `.<1–5 ASCII letters/digits>` that follows a non-empty base, or
+ * appends the extension when there is none (`.env` → `.env.txt`,
+ * `notes.markdown` → `notes.markdown.txt`).
+ */
+export declare function forceSaveBytesExtension(filename: string, type: SaveBytesType): string;
+/**
+ * Size-cap, clean the name, classify on the CLEANED name, and force the
+ * extension — the host's `prepareSaveBytes`, in its order. Every refusal is the
+ * reply's error string.
+ */
+export declare function prepareSaveBytes(req: {
+    bytes: ArrayBuffer;
+    filename?: string;
+}): {
+    ok: true;
+    type: SaveBytesType;
+    filename: string;
+} | {
+    ok: false;
+    error: string;
+};
+//# sourceMappingURL=saveBytes.d.ts.map

package/dist/internal/saveBytes.js

@@ -0,0 +1,175 @@
+/**
+ * The `bytes` variant of `SAVE_IMAGE` — the strings both sides of the bridge
+ * agree on, and the mock host's copy of the host's CONTENT classifier.
+ *
+ * The contract is civitai/civitai-app-starters#583. The host owns the real
+ * classifier; this one exists so `createMockHost` (and so `dev:harness` and
+ * every block test) accepts and refuses the same buffers production does. Keep
+ * it exactly as narrow as the contract — a mock that accepts a GIF teaches a
+ * block that GIFs save.
+ */
+/**
+ * The cap on a `bytes` payload: 50 MiB of raw bytes (`ArrayBuffer.byteLength`,
+ * so a text or JSON payload is counted after UTF-8 encoding).
+ *
+ * 🔴 The host spells its OWN copy of this number (civitai/civitai,
+ * `saveImageDownload.ts`), and the two MUST match. Nothing in this repository
+ * can read the host's value, so a drift is invisible here until a block hits
+ * the host's refusal on a buffer this hook let through, or the hook refuses one
+ * the host would have saved. Kept local to this package (not exported from
+ * `@civitai/app-sdk`) so the hook needs no newer app-sdk peer.
+ */
+export const SAVE_BYTES_MAX_BYTES = 50 * 1024 * 1024;
+/** Host refusal for a buffer over `SAVE_BYTES_MAX_BYTES`. Also the hook's own pre-send refusal. */
+export const SAVE_BYTES_TOO_LARGE_ERROR = 'file exceeds the maximum save size';
+/** Host refusal for bytes that classify as none of PNG / WebP / JPEG / UTF-8 text. */
+export const SAVE_BYTES_TYPE_NOT_ALLOWED_ERROR = 'file type is not allowed';
+/**
+ * Host refusal for a request that is not exactly one of `url` / `imageId` /
+ * `bytes`, for a `bytes` that is not a non-empty `ArrayBuffer`, and what a host
+ * that predates the `bytes` variant replies to one.
+ */
+export const SAVE_IMAGE_INVALID_REQUEST_ERROR = 'invalid save-image request';
+/**
+ * Which `SAVE_IMAGE` variant a payload is, by the host's exact predicate
+ * (civitai/civitai `saveImageDownload.ts`, `resolveSaveImageRequest`). A
+ * non-null `bytes` wins the dispatch: ANY non-null `url` / `imageId` beside it
+ * (even `''` or `'5'`) is ambiguous and invalid, and `bytes` must be a
+ * non-empty `ArrayBuffer`. Without `bytes` (`null` or absent) exactly one of a
+ * non-empty string `url` / a positive-integer `imageId` must be present.
+ */
+export function saveImageRequestKind(p) {
+    if (p.bytes != null) {
+        if (p.url != null || p.imageId != null)
+            return 'invalid';
+        if (!(p.bytes instanceof ArrayBuffer) || p.bytes.byteLength === 0)
+            return 'invalid';
+        return 'bytes';
+    }
+    const hasUrl = typeof p.url === 'string' && p.url.length > 0;
+    const hasId = typeof p.imageId === 'number' && Number.isInteger(p.imageId) && p.imageId > 0;
+    if (hasUrl === hasId)
+        return 'invalid';
+    return hasUrl ? 'url' : 'id';
+}
+/** The extension the host forces for each classified type. */
+export const SAVE_BYTES_EXTENSION = {
+    'image/png': '.png',
+    'image/webp': '.webp',
+    'image/jpeg': '.jpg',
+    'application/json': '.json',
+    'text/plain': '.txt',
+};
+function startsWith(view, sig, offset = 0) {
+    if (view.length < offset + sig.length)
+        return false;
+    for (let i = 0; i < sig.length; i++) {
+        if (view[offset + i] !== sig[i])
+            return false;
+    }
+    return true;
+}
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG = [0xff, 0xd8, 0xff];
+const RIFF = [0x52, 0x49, 0x46, 0x46]; // "RIFF"
+const WEBP = [0x57, 0x45, 0x42, 0x50]; // "WEBP" at offset 8
+/**
+ * Classify a `bytes` payload by CONTENT — the host's `classifySaveBytes`.
+ * `filename` is the only hint and must already be CLEANED
+ * ({@link sanitizeSaveBytesFilename}): a name ending `.json` (case-insensitive)
+ * chooses JSON over text/plain for bytes that already parse as JSON, and it can
+ * never make a binary payload acceptable. Returns `null` for anything the host
+ * refuses (`file type is not allowed`).
+ */
+export function classifySaveBytes(bytes, filename = '') {
+    const view = new Uint8Array(bytes);
+    if (startsWith(view, PNG))
+        return 'image/png';
+    if (startsWith(view, RIFF) && startsWith(view, WEBP, 8))
+        return 'image/webp';
+    if (startsWith(view, JPEG))
+        return 'image/jpeg';
+    if (view.includes(0))
+        return null;
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(view);
+    }
+    catch {
+        return null; // not valid UTF-8 — random binary, a GIF, a zip, …
+    }
+    if (filename.toLowerCase().endsWith('.json')) {
+        try {
+            JSON.parse(text);
+            return 'application/json';
+        }
+        catch {
+            // A `.json` name on text that does not parse saves as text, not a refusal.
+        }
+    }
+    return 'text/plain';
+}
+/*
+ * 🔴 The three functions below are a LINE-FOR-LINE port of the host's bytes
+ * filename rules (civitai/civitai `src/components/AppBlocks/saveImageDownload.ts`:
+ * `sanitizeDownloadFilename`, `sanitizeSaveBytesFilename`,
+ * `forceSaveBytesExtension`, `prepareSaveBytes`, as of civitai/civitai#5616 head
+ * 745624bc). Change them only together with the host, and keep
+ * test/saveBytesParity.test.ts — the host's own cases — green.
+ */
+/** The host's shared url/imageId download-name cleaner, used here only with a string name. */
+function sanitizeDownloadFilename(name) {
+    // Drop any directory component / traversal.
+    let clean = name.split(/[\\/]/).pop() ?? name;
+    // The host's query/fragment cut — a no-op for a bytes name, whose `?`/`#` are already replaced.
+    clean = clean.split('?')[0].split('#')[0];
+    // Collapse a duplicated trailing extension, preserving base dots.
+    const extMatch = clean.match(/\.([a-zA-Z0-9]{2,5})$/);
+    if (extMatch) {
+        const ext = extMatch[1];
+        clean = clean.replace(new RegExp(`(\\.${ext})+$`), `.${ext}`);
+    }
+    clean = clean.trim();
+    return clean.length > 0 ? clean : 'download';
+}
+/**
+ * Clean a block-supplied `bytes` filename BEFORE classification reads its
+ * `.json` suffix. The name is not a URL, so every `?` and `#` is REPLACED with
+ * `_` (not cut at): `issue#42.json` → `issue_42.json` (still JSON),
+ * `data.json?v=2` → `data.json_v=2` (no longer `.json`, so text). Then: keep
+ * the text after the last `/` or `\`, collapse a repeated trailing extension,
+ * trim; absent or empty → `download`.
+ */
+export function sanitizeSaveBytesFilename(name) {
+    return sanitizeDownloadFilename((name ?? 'download').replace(/[?#]/g, '_'));
+}
+/**
+ * Replace the extension of a cleaned name with the classified type's own. First
+ * deletes every control and format character (`\p{Cc}` / `\p{Cf}`: bidi
+ * overrides, zero-width marks), trims, empty → `download`; then replaces a
+ * trailing `.<1–5 ASCII letters/digits>` that follows a non-empty base, or
+ * appends the extension when there is none (`.env` → `.env.txt`,
+ * `notes.markdown` → `notes.markdown.txt`).
+ */
+export function forceSaveBytesExtension(filename, type) {
+    const cleaned = filename.replace(/[\p{Cc}\p{Cf}]/gu, '').trim();
+    const name = cleaned.length > 0 ? cleaned : 'download';
+    const m = name.match(/^(.+)\.([a-zA-Z0-9]{1,5})$/);
+    return `${m ? m[1] : name}${SAVE_BYTES_EXTENSION[type]}`;
+}
+/**
+ * Size-cap, clean the name, classify on the CLEANED name, and force the
+ * extension — the host's `prepareSaveBytes`, in its order. Every refusal is the
+ * reply's error string.
+ */
+export function prepareSaveBytes(req) {
+    if (req.bytes.byteLength > SAVE_BYTES_MAX_BYTES) {
+        return { ok: false, error: SAVE_BYTES_TOO_LARGE_ERROR };
+    }
+    const filename = sanitizeSaveBytesFilename(req.filename);
+    const type = classifySaveBytes(req.bytes, filename);
+    if (!type)
+        return { ok: false, error: SAVE_BYTES_TYPE_NOT_ALLOWED_ERROR };
+    return { ok: true, type, filename: forceSaveBytesExtension(filename, type) };
+}
+//# sourceMappingURL=saveBytes.js.map

package/dist/transport/validate.d.ts

@@ -474,7 +474,7 @@ export declare function isValidSharedReportResult(p: unknown): boolean;
 /**
  * Reply to `SAVE_IMAGE` (host download bridge). On success `ok` is a boolean;
  * `error` is a free-text host-side failure (disallowed origin / withheld image
- * / over-size / fetch failure). Uniform `{ ok, error }` contract (module
+ * / disallowed `bytes` type / over-size / fetch failure / `busy`). Uniform `{ ok, error }` contract (module
  * header) — same shape as `isValidSharedReportResult`.
  */
 export declare function isValidSaveImageResult(p: unknown): boolean;

package/dist/transport/validate.js

@@ -1584,7 +1584,7 @@ export function isValidSharedReportResult(p) {
 /**
  * Reply to `SAVE_IMAGE` (host download bridge). On success `ok` is a boolean;
  * `error` is a free-text host-side failure (disallowed origin / withheld image
- * / over-size / fetch failure). Uniform `{ ok, error }` contract (module
+ * / disallowed `bytes` type / over-size / fetch failure / `busy`). Uniform `{ ok, error }` contract (module
  * header) — same shape as `isValidSharedReportResult`.
  */
 export function isValidSaveImageResult(p) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.65.1",
+  "version": "0.66.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.59.0"
+    "@civitai/app-sdk": "^0.61.0"
   },
   "publishConfig": {
     "access": "public"