@civitai/blocks-react 0.65.2 → 0.67.0

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;
@@ -574,8 +619,9 @@ export interface MockHostOptions {
     /**
      * The bare (post-less) scanned `Image` row ids returned from
      * `PUBLISH_GENERATION_OUTPUTS` (what `usePublishGenerationOutputs().publish()`
-     * resolves with). Absent → {@link DEFAULT_PUBLISH_IMAGE_IDS}. Live-tunable via
-     * {@link MockHost.setScenario}.
+     * resolves with). Absent → {@link DEFAULT_PUBLISH_IMAGE_IDS}. Each reply makes
+     * these ids postable once in a `CREATE_POST_FROM_APP` `published` source (see
+     * {@link createPostResult}). Live-tunable via {@link MockHost.setScenario}.
      */
     publishImageIds?: number[];
     /**
@@ -636,6 +682,21 @@ export interface MockHostOptions {
      * `useCreatePostFromApp().createPost()` resolves with). Absent →
      * {@link DEFAULT_CREATE_POST_RESULT}. Ignored when {@link createPostError} is
      * set. Live-tunable via {@link MockHost.setScenario}.
+     *
+     * A `{ kind: 'published', imageIds }` source is checked as the server's
+     * `resolveAppPublishedImages` checks it (civitai/civitai#5639). Production
+     * accepts the viewer's own images that this app stamped and that are not in a
+     * post yet, from this session or an earlier one. The mock has no earlier
+     * sessions, so it accepts ONLY ids issued as postable on this mock instance
+     * (an accepted `OPEN_IMAGE_UPLOAD { bytes }` reply,
+     * {@link uploadImageBytesResult}, or a `PUBLISH_GENERATION_OUTPUTS` reply,
+     * {@link publishImageIds}) plus the ids seeded with {@link postableImageIds}.
+     * Any other id, a picked `useImageUpload()` id (production leaves it
+     * unstamped) or an id a previous post already adopted is refused with
+     * `an image is not available to post`, and a source with no positive integer
+     * id with `no valid image ids in a published source`. A refused post adopts
+     * nothing. `workflow` sources are not checked. The mock does not model the
+     * scan wait, the viewer's ceiling or the server's input schema.
      */
     createPostResult?: BlockCreatePostResult;
     /**
@@ -731,6 +792,104 @@ 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;
+    /**
+     * The moderated image an ACCEPTED `OPEN_IMAGE_UPLOAD { bytes }` replies with
+     * (what `useUploadImageBytes().upload()` resolves with). Absent →
+     * {@link DEFAULT_IMAGE_BYTES_UPLOAD}, whose `imageId` differs from
+     * {@link DEFAULT_IMAGE_UPLOAD}'s so a block that confuses a picked upload
+     * with an uploaded one is visible. Each accepted upload makes its `imageId`
+     * postable ONCE in a `CREATE_POST_FROM_APP` `{ kind: 'published', imageIds }`
+     * source on this same mock instance, as the real host allows for the app that
+     * uploaded it; see {@link createPostResult} for what the mock refuses.
+     * Live-tunable via {@link MockHost.setScenario}.
+     *
+     * The `bytes` variant runs the host's admission rules
+     * (civitai/civitai#5639, `imageUploadBytes.ts`) in the host's order: not a
+     * non-empty `ArrayBuffer`, or `purpose: 'generationSource'` →
+     * `invalid image-upload request`; over 40 MiB →
+     * `file exceeds the maximum upload size` (checked FIRST); a full rolling
+     * window (3 uploads or 80 MiB per 60 s, per install) → `busy`; not PNG /
+     * WebP / JPEG by magic bytes → `file type is not allowed`; then
+     * {@link uploadImageBytesError}, standing in for the server persist and the
+     * scan. 🔴 What the mock cannot model: that the variant is PAGE-ONLY, the
+     * `posts:write:self` scope check (force `block lacks posts:write:self scope`
+     * with {@link uploadImageBytesError}), the real scan, the no-reply for a
+     * `requestId` reused while in flight (the mock replies at once), and that a
+     * host OLDER than the variant opens its picker instead.
+     */
+    uploadImageBytesResult?: BlockUploadedImageInfo;
+    /**
+     * Force an `OPEN_IMAGE_UPLOAD { bytes }` that passed the admission rules
+     * above to reply with this `error`: a server refusal the real host forwards
+     * (`block lacks posts:write:self scope`,
+     * `Rate limit exceeded, please retry shortly.`, a scan refusal, …), or
+     * `busy` / `no block token`. The upload still counts against the window, as
+     * on the host. Absent → it succeeds. Live-tunable via
+     * {@link MockHost.setScenario}; `undefined` clears it.
+     */
+    uploadImageBytesError?: string;
+    /**
+     * Called with each `bytes` upload the mock ACCEPTS: the sniffed `mimeType`
+     * (`image/png`, `image/webp` or `image/jpeg`), the `filename` as the host
+     * stores it (the `useSaveImage()` bytes cleaning, the sniffed extension, at
+     * most 255 characters), and a copy of the `bytes`.
+     */
+    onUploadImageBytes?: (file: {
+        bytes: ArrayBuffer;
+        mimeType: string;
+        filename: string;
+    }) => void;
+    /**
+     * Image ids the mock treats as already issued and postable when the host is
+     * created, as production treats an image this app stamped for the viewer in
+     * an EARLIER session that is not in a post yet. Each seeded id may be posted
+     * ONCE in a `CREATE_POST_FROM_APP` `{ kind: 'published', imageIds }` source;
+     * see {@link createPostResult} for what the mock refuses. Use it for a test
+     * that posts an image the block uploaded before the test started, instead of
+     * driving an upload or `PUBLISH_GENERATION_OUTPUTS` first. Absent → none.
+     * Read once at creation; not live-tunable.
+     */
+    postableImageIds?: number[];
     /**
      * 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 +1054,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' | 'uploadImageBytesResult' | 'uploadImageBytesError'>;
 /** Runtime Buzz-balance handle exposed on {@link MockHost.buzz}. */
 export interface MockBuzzHandle {
     /** Current simulated balance, or `undefined` when balance isn't simulated. */
@@ -941,8 +1100,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 +1147,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();
  */