@civitai/blocks-react 0.67.0 → 0.68.0

package/dist/internal/mockHost.js

@@ -43,6 +43,7 @@ import { requiredStorageScope, storageResultType, storageScopeDeniedMessage, sto
 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 { BATCH_ESTIMATE_CELL_TIMEOUT_ERROR } from '../hooks/useBatchEstimate.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
@@ -195,6 +196,15 @@ export const MOCK_TRAINING_NONE_IMPORTED_ERROR = 'none of the requested images c
  * server made AFTER its claim, so it consumes the quote.
  */
 const PRE_CLAIM_RUN_TRAINING_ERRORS = new Set(RUN_TRAINING_ERROR_CODES.filter((c) => c !== 'submission-unconfirmed'));
+/**
+ * The host's cell cap for one `ESTIMATE_WORKFLOW_BATCH` (civitai/civitai
+ * `BLOCK_ESTIMATE_BATCH_MAX_CELLS`). The hook's `BATCH_ESTIMATE_MAX_CELLS` is the
+ * same number; the mock keeps its own copy so it refuses exactly as the host does
+ * when a block bypasses the hook.
+ */
+const MOCK_ESTIMATE_BATCH_MAX_CELLS = 16;
+/** The server's per-cell refusal of a `kind: 'training'` body inside a batch. */
+const MOCK_TRAINING_IN_BATCH_ERROR = 'a training estimate cannot be part of a batch — estimate it on its own';
 /** Default quote total for a `kind: 'training'` estimate when {@link MockHostOptions.trainingQuoteTotal} is unset. */
 const DEFAULT_TRAINING_QUOTE_TOTAL = 500;
 /** The real quote lifetime (`BLOCK_TRAINING_QUOTE_TTL_SECONDS`, 15 min). */
@@ -229,6 +239,24 @@ const DEFAULT_LORA_PICK = {
     trainedWords: ['sinfully stylish'],
     clipSkip: null,
 };
+// The second curated LoRA a MULTI-select request returns after
+// DEFAULT_LORA_PICK. Every field differs from the first so a block that mixes
+// two picks up (or renders one twice) shows it.
+const DEFAULT_SECOND_LORA_PICK = {
+    versionId: 777003,
+    modelId: 555003,
+    modelName: 'Ink Wash Lines',
+    versionName: 'v1.1',
+    baseModel: 'SDXL 1.0',
+    modelType: 'LORA',
+    strength: 0.8,
+    minStrength: -1,
+    maxStrength: 2,
+    trainedWords: ['ink wash'],
+    clipSkip: null,
+};
+/** The multi-select cap — the real host's, and `additionalResources`'. */
+const MOCK_RESOURCE_PICKER_MULTI_MAX = 5;
 /**
  * The canned image the mock host "returns" from `OPEN_IMAGE_UPLOAD`. Mirrors the
  * host's moderated {@link BlockUploadedImageInfo} projection (imageId/nsfwLevel/
@@ -601,7 +629,7 @@ 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`
+ * Layer-1 additions: `?balance/?latency/?costPerGen/?authorFee/?failNext/?failRate/?seed`
  * 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}.
@@ -693,6 +721,15 @@ export function readMockHostUrlOptions(win = globalThis
     if (costPerGen !== null && Number.isFinite(Number(costPerGen))) {
         generation.costPerGen = Number(costPerGen);
     }
+    // `?authorFee=<n>` itemises an app fee on the quote; `?authorFee=off`
+    // simulates a host that predates the field.
+    const authorFee = params.get('authorFee');
+    if (authorFee === 'off') {
+        generation.authorFee = false;
+    }
+    else if (authorFee !== null && authorFee !== '' && Number.isFinite(Number(authorFee))) {
+        generation.authorFee = Number(authorFee);
+    }
     const failNext = params.get('failNext');
     if (failNext !== null && Number.isInteger(Number(failNext))) {
         generation.failNext = Number(failNext);
@@ -799,6 +836,9 @@ export function createMockHost(options = {}) {
     // Legacy `cost` feeds costPerGen unless the scenario set its own.
     let legacyCost = options.cost ?? 8;
     let cannedPicks = options.cannedPicks ?? { Checkpoint: DEFAULT_CHECKPOINT_PICK, LORA: DEFAULT_LORA_PICK };
+    // Canned MULTI-select picks. `undefined` = derive from the single LoRA pick
+    // (see the option's docs); `null` = dismissed.
+    let cannedMultiPicks = options.cannedMultiPicks;
     // Canned image-upload result. `null` = dismissed; undefined = default image.
     let cannedImageUpload = options.cannedImageUpload === undefined ? DEFAULT_IMAGE_UPLOAD : options.cannedImageUpload;
     // Canned generationSource-upload result (purpose:'generationSource').
@@ -899,6 +939,25 @@ export function createMockHost(options = {}) {
     const sharedStore = new Map();
     let sharedSeq = 0;
     let sharedFailNext = sharedScenario.failNext ?? 0;
+    let sharedRateLimitNext = sharedScenario.rateLimitNext ?? 0;
+    let sharedRateLimitMeta = sharedScenario.rateLimit;
+    /**
+     * When a {@link MockSharedScenario.rateLimitNext} refusal is pending, consume
+     * one and return the reply's error fields; otherwise `null`. The message
+     * matches the platform's wording per write family
+     * (`apps-shared.router.ts`: submissions / votes / withdrawals / reports).
+     */
+    const takeSharedRateLimit = (noun) => {
+        if (sharedRateLimitNext <= 0)
+            return null;
+        sharedRateLimitNext -= 1;
+        const retryAfterSeconds = sharedRateLimitMeta?.retryAfterSeconds ?? 60;
+        const retryAt = sharedRateLimitMeta?.retryAt ?? new Date(Date.now() + retryAfterSeconds * 1000).toISOString();
+        return {
+            error: `Too many ${noun} — retry in ${retryAfterSeconds}s`,
+            rateLimit: { retryAfterSeconds, retryAt },
+        };
+    };
     const sharedNow = new Date().toISOString();
     // Seed newest-LAST so the last-listed seed has the highest seq (newest-first).
     for (const s of sharedScenario.seed ?? []) {
@@ -929,6 +988,24 @@ export function createMockHost(options = {}) {
         const spec = gen.costPerGen ?? legacyCost;
         return typeof spec === 'function' ? spec(body) : (spec ?? legacyCost);
     };
+    // `null` = this quote is not itemised (a fee-less kind, or `authorFee: false`).
+    const authorFeeFor = (body) => {
+        if (gen.authorFee === false)
+            return null;
+        // A REGISTERED step is keyed on the VALUE of `step`, as the host keys it —
+        // never `'step' in body`: `{ kind: 'step', step: undefined, ... }` is a legal
+        // pass-through body, and a pass-through quote prices no fee.
+        const quotesFee = body.kind === 'textToImage' || (body.kind === 'step' && typeof body.step === 'string');
+        if (!quotesFee)
+            return null;
+        const spec = gen.authorFee ?? 0;
+        return typeof spec === 'function' ? spec(body) : spec;
+    };
+    /** The `cost` of a QUOTE: the fee is inside `total` and itemised beside it. */
+    const quotedCost = (body) => {
+        const fee = authorFeeFor(body);
+        return fee === null ? { total: costFor(body) } : { total: costFor(body) + fee, authorFee: fee };
+    };
     const latencyFor = () => {
         const l = gen.latencyMs;
         if (l === undefined)
@@ -1156,6 +1233,79 @@ export function createMockHost(options = {}) {
                         return;
                     }
                 }
+                /**
+                 * The snapshot ONE estimate of `body` replies with. Shared by
+                 * ESTIMATE_WORKFLOW and ESTIMATE_WORKFLOW_BATCH so a batch cell is priced
+                 * exactly as a single estimate of the same body.
+                 */
+                const estimateSnapshotFor = (body) => {
+                    // UNUSABLE-ESTIMATE simulation (`generation.failEstimate`). Reproduces
+                    // the two real producers byte-for-byte so a block's `catch` around
+                    // `estimate()` is exercisable locally — see the knob's docs for why
+                    // that was previously impossible (civitai/civitai#4159).
+                    if (gen.failEstimate === 'failed') {
+                        // Mirrors the host's `failureSnapshot(err)` exactly: the 'failed'
+                        // sentinel id (a real one would be empty and get dropped by the
+                        // inbound validator), no `cost`.
+                        return {
+                            workflowId: 'failed',
+                            status: 'failed',
+                            error: gen.failEstimateMessage ?? 'mock: estimate failed',
+                        };
+                    }
+                    if (gen.failEstimate === 'no-cost') {
+                        // A SUCCESSFUL snapshot that simply has no price — no `error` to
+                        // explain it, which is what makes this producer the harder of the
+                        // two to diagnose from the block side.
+                        return { workflowId: 'wf_estimate', status: 'pending' };
+                    }
+                    // TRAINING ESTIMATE — KIND-FAITHFUL, the one exception to the
+                    // kind-agnostic rule above, because the real arm is not a priced
+                    // pass-through: it needs the spend scope, names a dataset the server
+                    // must hold, refuses a price above the per-run ceiling, and STORES a
+                    // quote the run is later checked against. Each refusal is the
+                    // server's message in the host's `failureSnapshot` shape.
+                    if (body.kind === 'training') {
+                        const refuse = (error) => ({
+                            workflowId: 'failed',
+                            status: 'failed',
+                            error,
+                        });
+                        if (!consentGranted)
+                            return refuse(MOCK_TRAINING_SCOPE_ERROR);
+                        const imageCount = trainingDatasets.get(body.datasetId);
+                        if (imageCount === undefined)
+                            return refuse(MOCK_TRAINING_DATASET_GONE_ERROR);
+                        const total = trainingQuoteTotal;
+                        if (total > MOCK_TRAINING_BOUNDS.maxBuzzPerRun) {
+                            return refuse(`this training run costs ${total} Buzz, above the per-run limit of ${MOCK_TRAINING_BOUNDS.maxBuzzPerRun} for apps`);
+                        }
+                        const quoteId = trainingHandle('tq_');
+                        const expiresAtMs = Date.now() + TRAINING_QUOTE_TTL_MS;
+                        trainingQuotes.set(quoteId, {
+                            datasetId: body.datasetId,
+                            total,
+                            expiresAtMs,
+                            spent: false,
+                        });
+                        return {
+                            workflowId: 'wf_estimate',
+                            status: 'pending',
+                            cost: { total },
+                            trainingQuote: {
+                                quoteId,
+                                total,
+                                imageCount,
+                                expiresAt: new Date(expiresAtMs).toISOString(),
+                            },
+                        };
+                    }
+                    return {
+                        workflowId: 'wf_estimate',
+                        status: 'pending',
+                        cost: quotedCost(body),
+                    };
+                };
                 switch (typed.type) {
                     case 'REQUEST_TOKEN':
                         dispatchToBlock({
@@ -1263,94 +1413,86 @@ export function createMockHost(options = {}) {
                         // a registry (that's server-only); the mock accepts any id, fail-open. The
                         // sentinel `workflowId` is non-empty so the snapshot survives the
                         // SDK inbound validator (which drops empty-workflowId snapshots).
+                        // The pricing itself is `estimateSnapshotFor`, shared with the batch.
                         const body = typed.payload?.body ?? {};
-                        // UNUSABLE-ESTIMATE simulation (`generation.failEstimate`). Reproduces
-                        // the two real producers byte-for-byte so a block's `catch` around
-                        // `estimate()` is exercisable locally — see the knob's docs for why
-                        // that was previously impossible (civitai/civitai#4159).
-                        if (gen.failEstimate === 'failed') {
+                        dispatchToBlock({
+                            type: 'ESTIMATE_RESULT',
+                            payload: { requestId, snapshot: estimateSnapshotFor(body) },
+                        });
+                        return;
+                    }
+                    case 'ESTIMATE_WORKFLOW_BATCH': {
+                        // The batch twin of ESTIMATE_WORKFLOW, in the host's order: the
+                        // request shape, then the list, then each cell through
+                        // `estimateSnapshotFor` — the function ESTIMATE_WORKFLOW prices with,
+                        // so a cell is priced exactly as one estimate of that body would be.
+                        // Nothing is submitted and no Buzz moves.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        const mode = gen.batchEstimate ?? 'supported';
+                        // A host that predates the message sends nothing at all.
+                        if (mode === 'silent')
+                            return;
+                        if (mode === 'unsupported') {
                             dispatchToBlock({
-                                type: 'ESTIMATE_RESULT',
-                                payload: {
-                                    requestId,
-                                    // Mirrors the host's `failureSnapshot(err)` exactly: the
-                                    // 'failed' sentinel id (a real one would be empty and get
-                                    // dropped by the inbound validator), no `cost`.
-                                    snapshot: {
-                                        workflowId: 'failed',
-                                        status: 'failed',
-                                        error: gen.failEstimateMessage ?? 'mock: estimate failed',
-                                    },
-                                },
+                                type: 'ESTIMATE_BATCH_RESULT',
+                                payload: { requestId, error: 'unsupported on this host' },
                             });
                             return;
                         }
-                        if (gen.failEstimate === 'no-cost') {
+                        const bodies = typed.payload?.bodies;
+                        if (!Array.isArray(bodies) || bodies.length === 0) {
                             dispatchToBlock({
-                                type: 'ESTIMATE_RESULT',
-                                // A SUCCESSFUL snapshot that simply has no price — no `error` to
-                                // explain it, which is what makes this producer the harder of the
-                                // two to diagnose from the block side.
-                                payload: { requestId, snapshot: { workflowId: 'wf_estimate', status: 'pending' } },
+                                type: 'ESTIMATE_BATCH_RESULT',
+                                payload: { requestId, error: 'invalid estimate batch' },
                             });
                             return;
                         }
-                        // TRAINING ESTIMATE — KIND-FAITHFUL, the one exception to the
-                        // kind-agnostic rule above, because the real arm is not a priced
-                        // pass-through: it needs the spend scope, names a dataset the server
-                        // must hold, refuses a price above the per-run ceiling, and STORES a
-                        // quote the run is later checked against. Each refusal is the
-                        // server's message in the host's `failureSnapshot` shape.
-                        if (body.kind === 'training') {
-                            const refuse = (error) => dispatchToBlock({
-                                type: 'ESTIMATE_RESULT',
-                                payload: { requestId, snapshot: { workflowId: 'failed', status: 'failed', error } },
-                            });
-                            if (!consentGranted)
-                                return refuse(MOCK_TRAINING_SCOPE_ERROR);
-                            const imageCount = trainingDatasets.get(body.datasetId);
-                            if (imageCount === undefined)
-                                return refuse(MOCK_TRAINING_DATASET_GONE_ERROR);
-                            const total = trainingQuoteTotal;
-                            if (total > MOCK_TRAINING_BOUNDS.maxBuzzPerRun) {
-                                return refuse(`this training run costs ${total} Buzz, above the per-run limit of ${MOCK_TRAINING_BOUNDS.maxBuzzPerRun} for apps`);
-                            }
-                            const quoteId = trainingHandle('tq_');
-                            const expiresAtMs = Date.now() + TRAINING_QUOTE_TTL_MS;
-                            trainingQuotes.set(quoteId, {
-                                datasetId: body.datasetId,
-                                total,
-                                expiresAtMs,
-                                spent: false,
-                            });
+                        if (bodies.length > MOCK_ESTIMATE_BATCH_MAX_CELLS) {
                             dispatchToBlock({
-                                type: 'ESTIMATE_RESULT',
-                                payload: {
-                                    requestId,
-                                    snapshot: {
-                                        workflowId: 'wf_estimate',
-                                        status: 'pending',
-                                        cost: { total },
-                                        trainingQuote: {
-                                            quoteId,
-                                            total,
-                                            imageCount,
-                                            expiresAt: new Date(expiresAtMs).toISOString(),
-                                        },
-                                    },
-                                },
+                                type: 'ESTIMATE_BATCH_RESULT',
+                                payload: { requestId, error: 'estimate batch too large' },
                             });
                             return;
                         }
+                        const snapshots = bodies.map((cell, index) => {
+                            // The host's snapshot for a cell its call budget ran out on.
+                            if (gen.batchEstimateTimedOutCells?.includes(index)) {
+                                return {
+                                    workflowId: 'failed',
+                                    status: 'failed',
+                                    error: BATCH_ESTIMATE_CELL_TIMEOUT_ERROR,
+                                };
+                            }
+                            // The server refuses a training cell in a batch: a training
+                            // estimate stores the quote the viewer later confirms, so it is
+                            // estimated on its own. Refused BEFORE `estimateSnapshotFor`, which
+                            // would store one.
+                            if (cell?.kind === 'training') {
+                                return {
+                                    workflowId: 'failed',
+                                    status: 'failed',
+                                    error: MOCK_TRAINING_IN_BATCH_ERROR,
+                                };
+                            }
+                            return estimateSnapshotFor(cell ?? {});
+                        });
+                        // The server's aggregate rule: the cells that priced, i.e. not
+                        // `'failed'` and carrying a numeric `cost.total`.
+                        let total = 0;
+                        let pricedCells = 0;
+                        for (const snapshot of snapshots) {
+                            if (snapshot.status === 'failed' || typeof snapshot.cost?.total !== 'number')
+                                continue;
+                            total += snapshot.cost.total;
+                            pricedCells += 1;
+                        }
                         dispatchToBlock({
-                            type: 'ESTIMATE_RESULT',
+                            type: 'ESTIMATE_BATCH_RESULT',
                             payload: {
                                 requestId,
-                                snapshot: {
-                                    workflowId: 'wf_estimate',
-                                    status: 'pending',
-                                    cost: { total: costFor(body) },
-                                },
+                                snapshots,
+                                aggregate: { total, pricedCells, cellCount: snapshots.length },
                             },
                         });
                         return;
@@ -1386,6 +1528,8 @@ export function createMockHost(options = {}) {
                             return;
                         }
                         const cost = costFor(body);
+                        // What the viewer pays: the generation plus the app fee.
+                        const charged = cost + (authorFeeFor(body) ?? 0);
                         // CAUGHT-SERVER-EXCEPTION simulation (`generation.failSubmitException`).
                         // Reproduces the host's `failureSnapshot(err)` byte-for-byte: the
                         // 'failed' sentinel id and NO `cost`, which is what separates an
@@ -1453,7 +1597,7 @@ export function createMockHost(options = {}) {
                                         // 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 },
+                                        cost: quotedCost(body),
                                         error: gen.submitCapRefusal === true
                                             ? DEFAULT_SUBMIT_CAP_REFUSAL
                                             : gen.submitCapRefusal,
@@ -1468,7 +1612,7 @@ export function createMockHost(options = {}) {
                         const insufficient = failMode === 'all' ||
                             failMode === 'insufficient' ||
                             buzz.insufficient === true ||
-                            (balanceSimulated && buzz.balance < cost);
+                            (balanceSimulated && buzz.balance < charged);
                         // Generic generation failure: failNext countdown, failRate dice, or
                         // the legacy 'some' (~1 in 3) mode.
                         let genericFail = false;
@@ -1548,7 +1692,7 @@ export function createMockHost(options = {}) {
                         }
                         // Success path: debit the simulated balance + remember body/cost.
                         if (balanceSimulated)
-                            buzz.balance = buzz.balance - cost;
+                            buzz.balance = buzz.balance - charged;
                         const workflowId = `wf_${submitCount}_${Date.now()}`;
                         workflows.set(workflowId, { polls: 0, cost, body });
                         dispatchToBlock({
@@ -2065,6 +2209,37 @@ export function createMockHost(options = {}) {
                     }
                     case 'OPEN_RESOURCE_PICKER': {
                         const rtype = typed.payload?.resourceType;
+                        // MULTI-select (`multiple: { max }`) — the real host's rules, in the
+                        // real host's order: LoRA family only, `max` a whole number ≥ 1
+                        // (clamped to 5), and a LIST reply (`selectedResources`, `[]` when
+                        // dismissed) with no `selected`. A request WITHOUT the key falls
+                        // through to the single-pick reply below, unchanged.
+                        const multiple = typed.payload?.multiple;
+                        if (multiple !== undefined && multiple !== null) {
+                            const refuse = (error) => dispatchToBlock({ type: 'RESOURCE_PICKER_RESULT', payload: { requestId, error } });
+                            if (!['lora', 'locon', 'dora'].includes(String(rtype).trim().toLowerCase())) {
+                                refuse(`OPEN_RESOURCE_PICKER: multiple is only supported for LoRA-family resource types, not ${String(rtype)}.`);
+                                return;
+                            }
+                            const max = typeof multiple === 'object' ? multiple.max : undefined;
+                            if (typeof max !== 'number' || !Number.isInteger(max) || max < 1) {
+                                refuse('OPEN_RESOURCE_PICKER: multiple.max must be a whole number of at least 1.');
+                                return;
+                            }
+                            const picks = cannedMultiPicks !== undefined
+                                ? (cannedMultiPicks ?? [])
+                                : cannedPicks.LORA
+                                    ? [cannedPicks.LORA, DEFAULT_SECOND_LORA_PICK]
+                                    : [];
+                            dispatchToBlock({
+                                type: 'RESOURCE_PICKER_RESULT',
+                                payload: {
+                                    requestId,
+                                    selectedResources: picks.slice(0, Math.min(max, MOCK_RESOURCE_PICKER_MULTI_MAX)),
+                                },
+                            });
+                            return;
+                        }
                         const selected = rtype ? cannedPicks[rtype] : undefined;
                         dispatchToBlock({
                             type: 'RESOURCE_PICKER_RESULT',
@@ -2355,6 +2530,14 @@ export function createMockHost(options = {}) {
                         return;
                     }
                     case 'SHARED_APPEND': {
+                        const appendLimited = takeSharedRateLimit('submissions');
+                        if (appendLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_APPEND_RESULT',
+                                payload: { requestId, key: '', ...appendLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2397,6 +2580,14 @@ export function createMockHost(options = {}) {
                     }
                     case 'SHARED_VOTE': {
                         const key = typed.payload?.key ?? '';
+                        const voteLimited = takeSharedRateLimit('votes');
+                        if (voteLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_VOTE_RESULT',
+                                payload: { requestId, count: 0, ...voteLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2424,6 +2615,14 @@ export function createMockHost(options = {}) {
                     }
                     case 'SHARED_UNVOTE': {
                         const key = typed.payload?.key ?? '';
+                        const unvoteLimited = takeSharedRateLimit('votes');
+                        if (unvoteLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_UNVOTE_RESULT',
+                                payload: { requestId, count: 0, ...unvoteLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2450,6 +2649,14 @@ export function createMockHost(options = {}) {
                     }
                     case 'SHARED_WITHDRAW': {
                         const key = typed.payload?.key ?? '';
+                        const withdrawLimited = takeSharedRateLimit('withdrawals');
+                        if (withdrawLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_WITHDRAW_RESULT',
+                                payload: { requestId, ok: false, deleted: false, ...withdrawLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2467,6 +2674,14 @@ export function createMockHost(options = {}) {
                     }
                     case 'SHARED_UPDATE': {
                         const key = typed.payload?.key ?? '';
+                        const updateLimited = takeSharedRateLimit('submissions');
+                        if (updateLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_UPDATE_RESULT',
+                                payload: { requestId, ok: false, ...updateLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2537,6 +2752,14 @@ export function createMockHost(options = {}) {
                     }
                     case 'SHARED_REPORT': {
                         const key = typed.payload?.key ?? '';
+                        const reportLimited = takeSharedRateLimit('reports');
+                        if (reportLimited) {
+                            dispatchToBlock({
+                                type: 'SHARED_REPORT_RESULT',
+                                payload: { requestId, ok: false, ...reportLimited },
+                            });
+                            return;
+                        }
                         if (sharedFailNext > 0) {
                             sharedFailNext -= 1;
                             dispatchToBlock({
@@ -2725,6 +2948,9 @@ export function createMockHost(options = {}) {
         if (patch.cannedPicks !== undefined)
             cannedPicks = patch.cannedPicks;
         // `null` is a meaningful value (dismissed), so check for the KEY's presence.
+        if ('cannedMultiPicks' in patch)
+            cannedMultiPicks = patch.cannedMultiPicks;
+        // `null` is a meaningful value (dismissed), so check for the KEY's presence.
         if ('cannedImageUpload' in patch)
             cannedImageUpload = patch.cannedImageUpload ?? null;
         if ('cannedGenerationSourceUpload' in patch)
@@ -2804,10 +3030,14 @@ export function createMockHost(options = {}) {
                 storageFailNext = patch.storage.failNext;
         }
         if (patch.shared !== undefined) {
-            // Only `failNext` is live-tunable; `seed` is install-time (re-install to
-            // change the backing store).
+            // `failNext`, `rateLimitNext` and `rateLimit` are live-tunable; `seed` is
+            // install-time (re-install to change the backing store).
             if (patch.shared.failNext !== undefined)
                 sharedFailNext = patch.shared.failNext;
+            if (patch.shared.rateLimitNext !== undefined)
+                sharedRateLimitNext = patch.shared.rateLimitNext;
+            if (patch.shared.rateLimit !== undefined)
+                sharedRateLimitMeta = patch.shared.rateLimit;
         }
     }
     const buzzHandle = {

package/dist/internal/pickerOverlay.d.ts

@@ -69,6 +69,15 @@ export type PickerSelection = {
 } | {
     channel: 'RESOURCE_PICKER_RESULT';
     selected: BlockResourceInfo;
+}
+/**
+ * MULTI-select (`OPEN_RESOURCE_PICKER` with `multiple`): the staged resources
+ * in the order they were staged. Only ever produced when
+ * {@link OpenPickerOptions.multiple} is set.
+ */
+ | {
+    channel: 'RESOURCE_PICKER_RESULT';
+    selectedResources: BlockResourceInfo[];
 };
 export interface OpenPickerOptions {
     /**
@@ -104,6 +113,16 @@ export interface OpenPickerOptions {
     baseModelGroup?: string;
     /** Currently-selected versionId so the overlay can pre-highlight it. */
     currentVersionId?: number;
+    /**
+     * MULTI-select mode (`OPEN_RESOURCE_PICKER` with `multiple: { max }`). A card
+     * click STAGES (or un-stages) that resource instead of resolving; the "Add"
+     * button resolves with everything staged, in staging order, as
+     * `selectedResources`. At most `max` can be staged. Only meaningful on the
+     * `RESOURCE_PICKER_RESULT` channel — the checkpoint channel has no list reply.
+     */
+    multiple?: {
+        max: number;
+    };
     /** Advisory-SFW for the PUBLIC fallback read. Defaults true (fail-closed SFW). */
     anonSfwOnly?: boolean;
     /** The document to mount into. Defaults to `globalThis.document`. */
@@ -129,6 +148,19 @@ export interface PickerOverlayHandle {
     selectByVersionId(versionId: number): void;
     /** Dismiss without a selection. Resolves `null` + tears down. */
     dismiss(): void;
+    /**
+     * MULTI-select only: stage the card with this versionId, or un-stage it if it
+     * already is. No-op when absent, when not in multi-select mode, or when
+     * staging would exceed `max`. Does NOT resolve.
+     */
+    toggleStagedByVersionId(versionId: number): void;
+    /** MULTI-select only: the staged versionIds, in staging order. */
+    readonly stagedVersionIds: readonly number[];
+    /**
+     * MULTI-select only: resolve with everything staged (in staging order) and
+     * tear down. No-op while nothing is staged, or outside multi-select mode.
+     */
+    commitStaged(): void;
     /** Force teardown (host teardown path). Resolves `null` if not already resolved. */
     close(): void;
     /** True once the overlay has resolved (selection or dismissal). */