@civitai/blocks-react 0.70.0 → 0.72.0

package/dist/internal/mockHost.d.ts

@@ -37,7 +37,8 @@
  * called). Only the postMessage bridge round-trips are exercised. Never import
  * this from production code.
  */
-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';
+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 BlockModel3dOutput, type BlockPublishedModel, type BlockRunConfirmedStepHostError, 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';
+import { type MockWorkflowQuoteFailure } from './mockWorkflowGraph.js';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
  * = every submit fails as if the viewer were OUT OF BUZZ, until an
@@ -77,7 +78,22 @@ export type MockCannedImageScan = 'scanned' | {
  * A per-generation cost: a fixed number, or a function of the submitted
  * {@link WorkflowBody} (so a dev can vary cost by model / step count).
  */
-export type CostSpec = number | ((req: WorkflowBody) => number);
+export type CostSpec = number | ((req: WorkflowBody, step?: MockWorkflowStepInfo) => number);
+/**
+ * The step a {@link CostSpec} function is pricing, passed as its SECOND
+ * argument when the body is `kind: 'workflow'`: the mock calls
+ * {@link MockGenerationScenario.costPerGen} once per step and sums the results.
+ * `undefined` for every other kind, which is priced with one call.
+ */
+export type { MockWorkflowQuoteFailure };
+export interface MockWorkflowStepInfo {
+    /** Zero-based position in the body's `steps`. */
+    index: number;
+    /** The step's `name`, or `'$<index>'` for an unnamed step. */
+    name: string;
+    $type: string;
+    input: Record<string, unknown>;
+}
 /**
  * A result image url: a fixed string, or a function of the submitted body
  * (so a dev can echo the prompt into a placeholder).
@@ -91,6 +107,12 @@ export interface MockGenerationScenario {
     /**
      * Cost reported on `ESTIMATE_RESULT` + the succeeded snapshot. A number, or
      * a `(body) => number`. Overrides the legacy top-level `cost`. Default `8`.
+     *
+     * A `kind: 'workflow'` body is priced PER STEP: this is called once for each
+     * step (a function receives the step as its second argument, see
+     * {@link MockWorkflowStepInfo}), multiplied by that step's generations (a
+     * `repeat` counts its iterations, nested repeats multiplied), and summed, so a
+     * plain number prices an N-step workflow with no `repeat` at N times it.
      */
     costPerGen?: CostSpec;
     /**
@@ -100,9 +122,10 @@ export interface MockGenerationScenario {
      * real host does. A number, or a `(body) => number`. Default `0`, which is
      * reported as `authorFee: 0` ("no fee on this request").
      *
-     * Like the real host, only a `textToImage` or registered-`step` body is
-     * itemised; `customComfy`, pass-through `step` and `training` quotes carry no
-     * `authorFee`. The succeeded snapshot's `cost.total` stays {@link costPerGen}
+     * Like the real host, only a `textToImage`, registered-`step` or `workflow`
+     * body is itemised; `customComfy`, pass-through `step` and `training` quotes
+     * carry no `authorFee`. A `workflow` body is charged this ONCE, however many
+     * steps it has. The succeeded snapshot's `cost.total` stays {@link costPerGen}
      * (a submitted workflow reports the generation's own cost), while a simulated
      * {@link MockBuzzScenario.balance} is debited `costPerGen + authorFee`.
      *
@@ -265,7 +288,54 @@ export interface MockGenerationScenario {
      * Default: unset.
      */
     submitCapRefusal?: string | true;
-    /** A single result image url (or `(body) => url`). */
+    /**
+     * Make ONE step of a `kind: 'workflow'` run fail, so a block can exercise a
+     * PARTIAL failure. Name the step as its snapshot entry names it: its `name`,
+     * or `'$<index>'` for a step the body left unnamed. The poll that finishes
+     * the workflow then answers `status: 'failed'` with:
+     *  - `steps`: every step before it `'succeeded'`, the named step `'failed'`
+     *    with an `error`, every step after it `'canceled'`;
+     *  - `cost.total`: the sum of the steps that succeeded (they stay charged), so
+     *    it is `> 0` unless the FIRST step is the one that fails;
+     *  - `imageUrls`: the images of the succeeded steps that did not set
+     *    `suppressOutput`.
+     *
+     * What the real orchestrator reports for the steps AFTER a failed one is its
+     * own business; `'canceled'` here is the mock's stand-in for "did not run".
+     *
+     * Ignored by every other kind, and when no step matches. Takes precedence
+     * over {@link workflowOutcome} for the workflow it applies to. Live-tunable
+     * via `setScenario({ generation: { failWorkflowStep } })`. Default: unset.
+     */
+    failWorkflowStep?: string;
+    /**
+     * Simulate the host getting NO price quote for a `kind: 'workflow'` body, and
+     * say why: `'rejected'` (the orchestrator refused the body), `'unavailable'`
+     * (no usable answer — the one cause a retry can clear) or `'unpriced'` (an
+     * answer without a price). `true` means `'unavailable'`.
+     *
+     *  - A workflow with a training step (`errorCode: 'training-quote-<cause>'`)
+     *    or a `repeat` step at any depth (`'workflow_repeat_unbounded'`) is
+     *    refused on BOTH `estimate()` and `submit()`, before any reservation.
+     *  - Any other workflow: `estimate()` FAILS with `'workflow_quote_<cause>'`
+     *    and no `cost`, while `submit()` still PROCEEDS, reserved at the CEILING —
+     *    {@link MockHostOptions.buzzBudget} × the number of steps — with no author
+     *    fee (no quote, no fee base). A failed estimate does not predict a refused
+     *    submit.
+     *
+     * `error` is the host's sentence for the cause. The mock has no orchestrator
+     * reason to pass on, so `'rejected'` always reads the host's reason-less form.
+     * Ignored by every other kind. Live-tunable via
+     * `setScenario({ generation: { workflowUnpriced } })`. Default: unset (every
+     * workflow is quoted at its per-step `costPerGen`).
+     */
+    workflowUnpriced?: boolean | MockWorkflowQuoteFailure;
+    /**
+     * A single result image url (or `(body) => url`). For a `kind: 'workflow'`
+     * run this (and {@link images}) is the LAST step that did not set
+     * `suppressOutput`; each earlier visible step gets its own labelled
+     * placeholder.
+     */
     image?: ImageSpec;
     /**
      * Multiple result image urls (or `(body) => url[]`). Takes precedence over
@@ -313,6 +383,22 @@ export interface MockGenerationScenario {
      * `appWorkflows`.
      */
     trainingPublishedModel?: BlockPublishedModel;
+    /**
+     * The 3D models a succeeded PASS-THROUGH step reports on
+     * {@link BlockWorkflowSnapshot.model3dOutputs} — what a `polyGen` job returns.
+     * As on the real host, every labelled `url` is ALSO in the snapshot's
+     * `imageUrls`: when set, the mock answers with exactly these urls there, in
+     * this order, unless {@link images} / {@link image} say otherwise (then the
+     * labels are sent as given and it is on you to keep the two consistent).
+     *
+     * Applies only to a pass-through `{ kind: 'step', $type }` body — the only arm
+     * the host labels. Default: unset, and the field is OMITTED, as the host omits
+     * it for a workflow that produced no 3D model.
+     *
+     * Snapshot-only, like {@link trainedEpochs}: for the app-queue read put
+     * `model3dOutputs` on the rows you pass as {@link MockHostOptions.appWorkflows}.
+     */
+    model3dOutputs?: BlockModel3dOutput[];
 }
 /**
  * The training bounds the mock enforces — COPIES of `@civitai/app-sdk/blocks`'s
@@ -347,6 +433,41 @@ 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";
+/**
+ * The per-job ceiling of a confirmed step — a COPY of `@civitai/app-sdk/blocks`'s
+ * `BLOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB`, not value-imported for the reason
+ * given on {@link MOCK_TRAINING_BOUNDS}. Pinned to the SDK's value by
+ * `test/confirmedStepFlow.test.tsx`, which imports both.
+ */
+export declare const MOCK_CONFIRMED_STEP_MAX_BUZZ_PER_JOB = 5000;
+/**
+ * The real server's refusal when the host reads back a step quote it does not
+ * hold — unknown, expired, or already used by an earlier run. This is the
+ * PREVIEW's message, which is the one `RUN_CONFIRMED_STEP` reaches first.
+ */
+export declare const MOCK_STEP_QUOTE_GONE_ERROR = "step quote not found or expired";
+/** The real server's refusal for a confirmed run whose body is not the quoted one. */
+export declare const MOCK_STEP_BODY_MISMATCH_ERROR = "the step body differs from the one that was quoted \u2014 estimate again";
+/**
+ * The real server's refusal for a `quoteId` body sent as a plain
+ * `SUBMIT_WORKFLOW`: nothing but `RUN_CONFIRMED_STEP`'s dialog records the
+ * viewer's confirmation.
+ */
+export declare const MOCK_STEP_NOT_CONFIRMED_ERROR = "this step has not been confirmed by the viewer in this session";
+/**
+ * The real server's refusal for a TRAINING `$type` (`training`,
+ * `imageResourceTraining`) on the confirmed-step path — at the estimate, where a
+ * quote would otherwise be granted, and at the confirmed submit. Training runs
+ * have their own kind.
+ */
+export declare const MOCK_STEP_TRAINING_TYPE_ERROR = "a training step type cannot run as a confirmed step \u2014 use kind:'training'";
+/**
+ * The fixed PREFIX of the real server's refusal for a confirmed-step body whose
+ * `input` is not plain JSON. The full message continues with the offending path
+ * and what was found there (`body.input.when is a Date`), which varies — match on
+ * this prefix.
+ */
+export declare const MOCK_STEP_NON_JSON_INPUT_ERROR_PREFIX = "a confirmed step needs plain JSON input (objects, arrays, strings, finite numbers, booleans, null) \u2014 ";
 /**
  * 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
@@ -910,6 +1031,51 @@ export interface MockHostOptions {
      * `setScenario({ runTrainingCapRefusal: undefined })` clears it.
      */
     runTrainingCapRefusal?: string;
+    /**
+     * Force `RUN_CONFIRMED_STEP` to reply with an `error` instead of starting the
+     * job — a {@link BlockRunConfirmedStepHostError} or any other string for a
+     * server message. Absent → the viewer "confirms" and the job starts.
+     *
+     *  - `'declined'` — the viewer dismissed the confirm. No job.
+     *  - `'daily-limit-exceeded'` — the job would exceed the viewer's own daily
+     *    Buzz limit for the app. No job; the real host explains it in its chrome.
+     *  - `'submission-unconfirmed'` — the job MAY exist.
+     *
+     * A CONFIRMED STEP IS QUOTED BY THE ESTIMATE, with no knob of its own: a
+     * pass-through `{ kind: 'step', $type }` estimate carries
+     * {@link BlockWorkflowSnapshot.stepQuote} whenever the mock's price for it
+     * ({@link MockGenerationScenario.costPerGen}, or `cost`) is above the token's
+     * per-call budget ({@link MockHostOptions.buzzBudget}, default 200) and at most
+     * 5,000, for a signed-in viewer. So `generation: { costPerGen: 800 }` is all it
+     * takes to reach this path. ONLY a single `ESTIMATE_WORKFLOW` quotes one: a
+     * batch-estimate cell never carries `stepQuote`, as on the server. And where a
+     * quote would be granted, two bodies make the estimate FAIL instead, with the
+     * server's message: a training `$type` (`training`, `imageResourceTraining`,
+     * in any casing), and an `input` that is not plain JSON (a `Date`, `Map`,
+     * `Set`, `BigInt`, `NaN`, an empty slot in a sparse array, …).
+     *
+     * Whether the QUOTE survives follows the real flow: the host's own gate,
+     * dialog and daily-limit codes settle before the server claims the quote, so
+     * it stays runnable; `submission-unconfirmed` and any server message settle
+     * after the claim, so it is used up — running it again gets the quote-gone
+     * error. Live-tunable via {@link MockHost.setScenario}; `undefined` clears it.
+     * URL: `?confirmedStep=declined|daily-limit|unconfirmed`.
+     *
+     * 🔴 Same real gap as {@link runTrainingError}: the confirm is HOST chrome, so
+     * the mock settles immediately where the real host waits on a click. The mock
+     * also prices every estimate as FIXED — the real host gives a variable or
+     * metered price no `stepQuote` at all.
+     */
+    runConfirmedStepError?: BlockRunConfirmedStepHostError | string;
+    /**
+     * Make `RUN_CONFIRMED_STEP` resolve the server's spend-cap refusal instead of
+     * a job: a snapshot `{ workflowId: 'failed', status: 'failed', cost: { total:
+     * <quote> }, error: <this string> }` (refunded, no job).
+     * `useRunConfirmedStep()` rejects it with `.refused`. 🔴 The quote is CONSUMED,
+     * as on the server. Absent → the job starts. Live-tunable via
+     * {@link MockHost.setScenario}; `undefined` clears it.
+     */
+    runConfirmedStepCapRefusal?: 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'`,
@@ -1098,6 +1264,9 @@ export interface MockHostOptions {
      * shape carries the field, so a context you pass WITHOUT a `theme` key still
      * gets the harness theme (and still follows a later `setTheme`). Only a slot
      * this SDK has no shape for is left alone — there is no `theme` field to set.
+     *
+     * The slot also decides `SET_USER_CHECKPOINT`, as in production: refused on
+     * `app.page` (the default), persisted on a model slot.
      */
     context?: BlockContext;
     /**
@@ -1172,7 +1341,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' | 'cannedMultiPicks' | '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'>;
+export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedMultiPicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'runConfirmedStepError' | 'runConfirmedStepCapRefusal' | '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. */
@@ -1221,6 +1390,8 @@ export declare function disallowedAccountError(accountType: BuzzAccountType): st
  * 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}.
+ * `?confirmedStep=declined|daily-limit|unconfirmed` sets
+ * {@link MockHostOptions.runConfirmedStepError}.
  *
  * Returns a partial overlay applied ON TOP of explicit {@link MockHostOptions}
  * (URL wins — it's the interactive dev knob). No-op outside a browser.