@civitai/blocks-react 0.65.2 → 0.67.0

package/dist/internal/mockHost.js

@@ -41,6 +41,8 @@ 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 { UPLOAD_BYTES_INVALID_ERROR, admitUploadBytes, resolveUploadBytesRequest, } from './uploadBytes.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
@@ -247,6 +249,17 @@ const DEFAULT_IMAGE_UPLOAD = {
  * — no imageId/nsfwLevel). `null` simulates a user-dismissed modal. The url is a
  * Civitai-hosted image so a dev can feed it straight into a `sourceImage` body.
  */
+/**
+ * The moderated image the mock host returns from an accepted
+ * `OPEN_IMAGE_UPLOAD { bytes }` when {@link MockHostOptions.uploadImageBytesResult}
+ * is omitted. Its `imageId` deliberately differs from {@link DEFAULT_IMAGE_UPLOAD}'s.
+ */
+const DEFAULT_IMAGE_BYTES_UPLOAD = {
+    imageId: 12345701,
+    nsfwLevel: 1,
+    contentRating: 'pg',
+    url: 'https://image.civitai.com/mock/original=true/dev-bytes-upload.png',
+};
 const DEFAULT_GENERATION_SOURCE_UPLOAD = {
     url: 'https://image.civitai.com/mock/original=true/dev-generation-source.jpeg',
     width: 1024,
@@ -279,8 +292,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 +602,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 +701,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 +764,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 +841,21 @@ 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;
+    // OPEN_IMAGE_UPLOAD { bytes }: the canned result, a forced-refusal knob, and
+    // the host's rolling window (per install, like the host's per mount).
+    let uploadImageBytesResult = options.uploadImageBytesResult ?? DEFAULT_IMAGE_BYTES_UPLOAD;
+    let uploadImageBytesError = options.uploadImageBytesError;
+    let uploadBytesWindow = [];
+    // The ids a `CREATE_POST_FROM_APP` `{ kind: 'published' }` source may name:
+    // ONLY ids this mock itself issued as postable (an accepted bytes upload, or a
+    // PUBLISH_GENERATION_OUTPUTS reply) plus the seeded `postableImageIds` (an
+    // earlier session's stamped, unposted images), and only until a post adopts
+    // them. Mirrors the host's `resolveAppPublishedImages` (civitai/civitai#5639):
+    // this app's provenance stamp and `postId IS NULL`. A picked `useImageUpload()`
+    // image is never added: production leaves it unstamped, so it is not postable.
+    const postableImageIds = new Set(options.postableImageIds ?? []);
     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 +1434,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 +1492,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 +1537,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 +1601,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 },
@@ -1787,6 +1865,32 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        // `published` sources: the server's `resolveAppPublishedImages`
+                        // refusals, verbatim. Ids are de-duplicated and non-positive /
+                        // non-integer ones dropped first; none left → `no valid image ids
+                        // in a published source`. Then ONE message for "unknown", "not this
+                        // app's" (a picked upload is unstamped) and "already in a post", so
+                        // the reply is no existence oracle. Refused, never skipped.
+                        const adopted = [];
+                        for (const source of sources) {
+                            if (source?.kind !== 'published')
+                                continue;
+                            const raw = Array.isArray(source.imageIds) ? source.imageIds : [];
+                            const ids = [...new Set(raw)].filter((n) => typeof n === 'number' && Number.isInteger(n) && n > 0);
+                            const refusal = ids.length === 0
+                                ? 'no valid image ids in a published source'
+                                : ids.some((id) => !postableImageIds.has(id))
+                                    ? 'an image is not available to post'
+                                    : undefined;
+                            if (refusal !== undefined) {
+                                dispatchToBlock({ type: 'CREATE_POST_RESULT', payload: { requestId, error: refusal } });
+                                return;
+                            }
+                            adopted.push(...ids);
+                        }
+                        // Posted: the adopted images now have a `postId`, so never again.
+                        for (const id of adopted)
+                            postableImageIds.delete(id);
                         dispatchToBlock({
                             type: 'CREATE_POST_RESULT',
                             payload: { requestId, result: { ...createPostResult } },
@@ -1909,6 +2013,8 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
+                        for (const id of publishImageIds)
+                            postableImageIds.add(id);
                         dispatchToBlock({
                             type: 'PUBLISH_RESULT',
                             payload: { requestId, result: { imageIds: [...publishImageIds] } },
@@ -1972,6 +2078,31 @@ export function createMockHost(options = {}) {
                         //   • 'generationSource' → the UNSCANNED source { url, width, height }
                         //   • 'display' (default / absent) → the MODERATED image
                         // `null` → dismissed (no `selected`), so the hook resolves to null.
+                        // The `bytes` variant (civitai/civitai#5639): no picker, the host's
+                        // admission rules in the host's order (./uploadBytes.ts), then the
+                        // forced refusal standing in for the server persist + scan.
+                        const bytesReq = resolveUploadBytesRequest(typed.payload ?? {});
+                        if (bytesReq.kind !== 'none') {
+                            if (!isRoutableRequestId(requestId))
+                                return;
+                            const reply = (p) => dispatchToBlock({ type: 'IMAGE_UPLOAD_RESULT', payload: { requestId, ...p } });
+                            if (bytesReq.kind === 'invalid')
+                                return reply({ error: UPLOAD_BYTES_INVALID_ERROR });
+                            const admitted = admitUploadBytes(bytesReq, uploadBytesWindow, Date.now());
+                            uploadBytesWindow = admitted.recent;
+                            if (!admitted.result.ok)
+                                return reply({ error: admitted.result.error });
+                            if (uploadImageBytesError !== undefined)
+                                return reply({ error: uploadImageBytesError });
+                            // A COPY, as production's structured-clone `postMessage` delivers it.
+                            options.onUploadImageBytes?.({
+                                bytes: bytesReq.bytes.slice(0),
+                                mimeType: admitted.result.type,
+                                filename: admitted.result.filename,
+                            });
+                            postableImageIds.add(uploadImageBytesResult.imageId);
+                            return reply({ selected: { ...uploadImageBytesResult } });
+                        }
                         const isGenerationSource = typed.payload?.purpose === 'generationSource';
                         // NON-BLOCKING display path (asyncScan:true): early-resolve with a
                         // PENDING handle, then stream the canned scan verdict on a later tick.
@@ -2430,23 +2561,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 +2770,13 @@ export function createMockHost(options = {}) {
             trainingQuoteTotal = patch.trainingQuoteTotal;
         if ('runTrainingError' in patch)
             runTrainingError = patch.runTrainingError;
+        if ('saveImageError' in patch)
+            saveImageError = patch.saveImageError;
+        if (patch.uploadImageBytesResult !== undefined) {
+            uploadImageBytesResult = patch.uploadImageBytesResult;
+        }
+        if ('uploadImageBytesError' in patch)
+            uploadImageBytesError = patch.uploadImageBytesError;
         if ('runTrainingCapRefusal' in patch)
             runTrainingCapRefusal = patch.runTrainingCapRefusal;
         if (patch.appWorkflows !== undefined) {

package/dist/internal/saveBytes.d.ts

@@ -0,0 +1,102 @@
+/**
+ * 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>;
+/** The three image types the host recognises by magic bytes. */
+export type SniffedImageType = 'image/png' | 'image/webp' | 'image/jpeg';
+/**
+ * PNG / WebP / JPEG by magic bytes — the host's shared sniffer
+ * (`sniffSaveBytesImage`: the full 8-byte PNG signature, no GIF). Both `bytes`
+ * bridges use it: `SAVE_IMAGE` before its text fallback, and
+ * `OPEN_IMAGE_UPLOAD`, which accepts images only.
+ */
+export declare function sniffImageBytes(view: Uint8Array): SniffedImageType | null;
+/**
+ * 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,187 @@
+/**
+ * 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
+/**
+ * PNG / WebP / JPEG by magic bytes — the host's shared sniffer
+ * (`sniffSaveBytesImage`: the full 8-byte PNG signature, no GIF). Both `bytes`
+ * bridges use it: `SAVE_IMAGE` before its text fallback, and
+ * `OPEN_IMAGE_UPLOAD`, which accepts images only.
+ */
+export function sniffImageBytes(view) {
+    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';
+    return null;
+}
+/**
+ * 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);
+    const image = sniffImageBytes(view);
+    if (image)
+        return image;
+    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