@civitai/blocks-react 0.67.1 → 0.68.0

package/dist/hooks/useSharedStorage.d.ts

@@ -1,4 +1,28 @@
 import type { SharedStorageValue } from '@civitai/app-sdk/blocks';
+/**
+ * A shared-storage write the server REFUSED because a per-(viewer, app) budget
+ * is empty — thrown by `append`, `update`, `vote`, `unvote`, `withdraw` and
+ * `report` when the host's refusal carries retry metadata.
+ *
+ * It EXTENDS `Error`, the class every other shared-storage refusal is thrown
+ * as, so existing `catch` code keeps working unchanged: `.message` is still the
+ * host's refusal text (for example `Too many submissions — retry in 312s`).
+ * Branch on `instanceof SharedStorageRateLimitError` to render the wait from
+ * {@link SharedStorageRateLimitError.retryAt} instead of parsing the message.
+ *
+ * Not thrown when the refusal carries no metadata — a host that predates it, or
+ * a refusal that is not a rate limit. Those stay a plain `Error`.
+ */
+export declare class SharedStorageRateLimitError extends Error {
+    /** Whole seconds until a retry can succeed, as of when the server refused. At least 1. */
+    readonly retryAfterSeconds: number;
+    /** ISO-8601 instant at which a retry can succeed. Prefer this for a countdown. */
+    readonly retryAt: string;
+    constructor(message: string, rateLimit: {
+        retryAfterSeconds: number;
+        retryAt: string;
+    });
+}
 /**
  * The value a viewer contributes to the SHARED store: a required `title`, an
  * optional long-form `body`, and an optional opaque app-owned `data` blob.

package/dist/hooks/useSharedStorage.js

@@ -2,6 +2,50 @@ import { useMemo } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply, throwOnReplyError } from '../internal/replyError.js';
 import { sendTypedRequest } from '../transport/transport.js';
+import { parseSharedStorageRateLimit } from '../transport/validate.js';
+/**
+ * A shared-storage write the server REFUSED because a per-(viewer, app) budget
+ * is empty — thrown by `append`, `update`, `vote`, `unvote`, `withdraw` and
+ * `report` when the host's refusal carries retry metadata.
+ *
+ * It EXTENDS `Error`, the class every other shared-storage refusal is thrown
+ * as, so existing `catch` code keeps working unchanged: `.message` is still the
+ * host's refusal text (for example `Too many submissions — retry in 312s`).
+ * Branch on `instanceof SharedStorageRateLimitError` to render the wait from
+ * {@link SharedStorageRateLimitError.retryAt} instead of parsing the message.
+ *
+ * Not thrown when the refusal carries no metadata — a host that predates it, or
+ * a refusal that is not a rate limit. Those stay a plain `Error`.
+ */
+export class SharedStorageRateLimitError extends Error {
+    /** Whole seconds until a retry can succeed, as of when the server refused. At least 1. */
+    retryAfterSeconds;
+    /** ISO-8601 instant at which a retry can succeed. Prefer this for a countdown. */
+    retryAt;
+    constructor(message, rateLimit) {
+        super(message);
+        this.name = 'SharedStorageRateLimitError';
+        this.retryAfterSeconds = rateLimit.retryAfterSeconds;
+        this.retryAt = rateLimit.retryAt;
+    }
+}
+/**
+ * Throw {@link SharedStorageRateLimitError} when a write reply is a refusal (a
+ * PRESENT `error`, the same test as `throwOnReplyError`) that carries valid
+ * `rateLimit`. Otherwise returns, and the caller's usual reply check throws the
+ * plain `Error` as before.
+ *
+ * Parses `rateLimit` rather than trusting it: the transport delivers it as the
+ * host sent it, so a malformed value is ignored here and the caller's plain
+ * `Error` is thrown instead.
+ */
+function throwOnSharedRateLimit(result, fallback) {
+    if (result.error === undefined)
+        return;
+    const rateLimit = parseSharedStorageRateLimit(result.rateLimit);
+    if (rateLimit)
+        throw new SharedStorageRateLimitError(result.error || fallback, rateLimit);
+}
 /**
  * App-scoped, append-only, community-votable SHARED datastore. Sibling of
  * {@link useAppStorage} (the per-viewer KV store) — same postMessage bridge,
@@ -15,6 +59,11 @@ import { sendTypedRequest } from '../transport/transport.js';
  * / `getCount(s)`) and a hard reject on mutations (`append`/`vote`/`unvote`/
  * `withdraw`).
  *
+ * Writes are budgeted per (viewer, app) server-side. A write refused for that
+ * reason rejects with {@link SharedStorageRateLimitError} (a subclass of the
+ * plain `Error` every other refusal is) carrying `retryAfterSeconds` and
+ * `retryAt`, whenever the host sends the metadata.
+ *
  * The hook is stable across renders — it returns the same object identity once
  * the transport singleton is created, so it's safe in `useEffect`/`useMemo`
  * dependency arrays.
@@ -71,6 +120,7 @@ export function useSharedStorage() {
             },
             async report(key, reason) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_REPORT', payload: { key, reason } }, 'SHARED_REPORT_RESULT');
+                throwOnSharedRateLimit(result, 'shared report failed');
                 throwOnFailedReply(result, 'shared report failed');
             },
             async getCount(key) {
@@ -85,25 +135,30 @@ export function useSharedStorage() {
             },
             async append(value) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_APPEND', payload: { value } }, 'SHARED_APPEND_RESULT');
+                throwOnSharedRateLimit(result, 'shared append failed');
                 throwOnReplyError(result, 'shared append failed');
                 return { key: result.key };
             },
             async update(key, value) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_UPDATE', payload: { key, value } }, 'SHARED_UPDATE_RESULT');
+                throwOnSharedRateLimit(result, 'shared update failed');
                 throwOnFailedReply(result, 'shared update failed');
             },
             async vote(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_VOTE', payload: { key } }, 'SHARED_VOTE_RESULT');
+                throwOnSharedRateLimit(result, 'shared vote failed');
                 throwOnReplyError(result, 'shared vote failed');
                 return result.count;
             },
             async unvote(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_UNVOTE', payload: { key } }, 'SHARED_UNVOTE_RESULT');
+                throwOnSharedRateLimit(result, 'shared unvote failed');
                 throwOnReplyError(result, 'shared unvote failed');
                 return result.count;
             },
             async withdraw(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_WITHDRAW', payload: { key } }, 'SHARED_WITHDRAW_RESULT');
+                throwOnSharedRateLimit(result, 'shared withdraw failed');
                 throwOnFailedReply(result, 'shared withdraw failed');
                 // `deleted` is optional on the wire type because an error reply omits
                 // it. On the success path the validator requires a boolean, so this is

package/dist/index.d.ts

@@ -27,6 +27,8 @@ export { useHostOrigin } from './hooks/useHostOrigin.js';
 export type { UseHostOrigin } from './hooks/useHostOrigin.js';
 export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, WorkflowSubmitError, } from './hooks/useBuzzWorkflow.js';
 export type { SubmitWorkflowOptions, UseBuzzWorkflow, WatchWorkflowOptions, WorkflowSubmitErrorCode, } from './hooks/useBuzzWorkflow.js';
+export { BATCH_ESTIMATE_MAX_CELLS, BatchEstimateError, useBatchEstimate, } from './hooks/useBatchEstimate.js';
+export type { BatchEstimateCell, BatchEstimateErrorCode, BatchEstimateResult, BlockEstimateBatchAggregate, EstimateBatchOptions, UseBatchEstimate, } from './hooks/useBatchEstimate.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export type { UseEntitlements, Entitlement } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
@@ -74,8 +76,8 @@ export type { UseRunTraining, QuotedTrainingBody, RunTrainingErrorCode, BlockRun
 export type { BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, AppWorkflowsParams, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, } from '@civitai/app-sdk/blocks';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export type { UseCheckpointPicker } from './hooks/useCheckpointPicker.js';
-export { useResourcePicker } from './hooks/useResourcePicker.js';
-export type { UseResourcePicker } from './hooks/useResourcePicker.js';
+export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';
+export type { UseResourcePicker, ResourcePickerOpenOptions, ResourcePickerMultiple, } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
 export type { UseImageUpload, UseImageUploadAsyncScan, UseImageUploadGenerationSource, UseImageUploadOptions, } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
@@ -108,6 +110,6 @@ export { useNestedDocument } from './hooks/useNestedDocument.js';
 export type { NestedDocumentStatus, UseNestedDocument, UseNestedDocumentOptions, } from './hooks/useNestedDocument.js';
 export { useAppStorage } from './hooks/useAppStorage.js';
 export type { AppStorageKeyEntry, AppStorageListResult, AppStorageQuota, UseAppStorage, } from './hooks/useAppStorage.js';
-export { useSharedStorage } from './hooks/useSharedStorage.js';
+export { useSharedStorage, SharedStorageRateLimitError } from './hooks/useSharedStorage.js';
 export type { SharedAppendValue, SharedListItem, SharedListResult, UseSharedStorage, } from './hooks/useSharedStorage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -31,6 +31,7 @@ export { useBlockSettings } from './hooks/useBlockSettings.js';
 export { useBlockToken } from './hooks/useBlockToken.js';
 export { useHostOrigin } from './hooks/useHostOrigin.js';
 export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, WorkflowSubmitError, } from './hooks/useBuzzWorkflow.js';
+export { BATCH_ESTIMATE_MAX_CELLS, BatchEstimateError, useBatchEstimate, } from './hooks/useBatchEstimate.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
 export { useTip } from './hooks/useTip.js';
@@ -62,7 +63,7 @@ export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreat
 export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
 export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
-export { useResourcePicker } from './hooks/useResourcePicker.js';
+export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
@@ -84,5 +85,5 @@ export { hostToRunUrl, DIRECT_LOAD_TIMEOUT_MS } from './transport/directLoad.js'
 // `@civitai/app-sdk`'s `src/blocks/nestedDocument.ts` header.
 export { useNestedDocument } from './hooks/useNestedDocument.js';
 export { useAppStorage } from './hooks/useAppStorage.js';
-export { useSharedStorage } from './hooks/useSharedStorage.js';
+export { useSharedStorage, SharedStorageRateLimitError } from './hooks/useSharedStorage.js';
 //# sourceMappingURL=index.js.map

package/dist/internal/liveHost.d.ts

@@ -46,8 +46,8 @@
  * --- BEGIN DERIVED ---
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
- * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 47, of which 10 REFUSE (enumerated under SCOPE below)
+ * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
+ * switch case labels .... 48, of which 10 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -83,6 +83,12 @@
  * the switch's `default: return` with no reply at all, so `useSharedStorage()`
  * hung to the 30s protocol timeout in dev:live for code that worked in dev:mock.
  *
+ * TRACK_EVENT: recorded only in production, so the live host forwards nothing
+ * and replies nothing (production replies nothing either). What it does is
+ * CHECK each event against the manifest passed as `options.manifest` and warn
+ * once per distinct problem production would silently drop — see
+ * `trackEventCheck.ts`.
+ *
  * 🔴 SCOPE — the capabilities live mode still cannot SERVE. Each REFUSES on its
  * own reply channel — `logOnce` (or `console.info`) plus an honest error, never
  * a fabricated success and never silence. Two guards stand behind this list:
@@ -186,6 +192,25 @@ export interface LiveHostOptions {
      * `dev:live` run this is omitted — the dev clicks a card in the overlay.
      */
     onPickerReady?: (handle: PickerOverlayHandle) => void;
+    /**
+     * The app's manifest — pass `block.manifest.json` as the harness imported it.
+     * Used for one thing: each `TRACK_EVENT` is checked against its
+     * `analytics.events` declaration, and the console warns ONCE per distinct
+     * problem production would silently drop — an undeclared event, an
+     * undeclared property, a value that does not match the declared type or enum.
+     * A declared, valid event logs nothing. The check never throws, never blocks
+     * the block, and sends no reply (production sends none either). Omit it and
+     * the first `TRACK_EVENT` says the check is off.
+     *
+     * Typed `unknown` because an imported JSON file widens its string literals
+     * (`"type": "enum"` reads as `string`), which a stricter type would reject.
+     *
+     * @example
+     * // `manifest` = your block.manifest.json, imported as JSON — every
+     * // `starters/examples/*` harness does this.
+     * createLiveHost({ blockToken, manifest });
+     */
+    manifest?: unknown;
 }
 /**
  * The reply both training bridges get in dev:live — see their handlers. One

package/dist/internal/liveHost.js

@@ -46,8 +46,8 @@
  * --- BEGIN DERIVED ---
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
- * tRPC procedures ....... 28 = blocks.* (13) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 47, of which 10 REFUSE (enumerated under SCOPE below)
+ * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
+ * switch case labels .... 48, of which 10 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -83,6 +83,12 @@
  * the switch's `default: return` with no reply at all, so `useSharedStorage()`
  * hung to the 30s protocol timeout in dev:live for code that worked in dev:mock.
  *
+ * TRACK_EVENT: recorded only in production, so the live host forwards nothing
+ * and replies nothing (production replies nothing either). What it does is
+ * CHECK each event against the manifest passed as `options.manifest` and warn
+ * once per distinct problem production would silently drop — see
+ * `trackEventCheck.ts`.
+ *
  * 🔴 SCOPE — the capabilities live mode still cannot SERVE. Each REFUSES on its
  * own reply channel — `logOnce` (or `console.info`) plus an honest error, never
  * a fabricated success and never silence. Two guards stand behind this list:
@@ -129,6 +135,8 @@
 import { consentUnavailablePayload, resolveUngrantableConsentNotice } from './consent.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
+import { parseSharedStorageRateLimit } from '../transport/validate.js';
+import { createTrackEventChecker } from './trackEventCheck.js';
 import { openPickerOverlay, } from './pickerOverlay.js';
 /** Default civitai backend the live host forwards to. */
 const DEFAULT_BACKEND_BASE_URL = 'https://civitai.com';
@@ -225,6 +233,9 @@ function errorSnapshot(error) {
  * deploy (the dev token is fine; the pod just hasn't loaded the verifier yet) —
  * the exact blip the round-5 dogfood hit. Anything ≥ 500, plus 408 (timeout)
  * and 429 (rate-limit), is also transient.
+ *
+ * Only {@link pollWithRetry} reads `transient`; a shared-storage 429 is a
+ * write-budget refusal whose wait is minutes, so it must never be retried.
  */
 function isTransientHttpStatus(status) {
     return status >= 500 || status === 408 || status === 429 || status === 401;
@@ -323,6 +334,8 @@ export function createLiveHost(options) {
             'likely minted from an OAuth login. Real generation needs a full-scope personal API key: ' +
             '`civitai login --token <key>` (https://civitai.com/user/account), then re-mint the dev token.');
     }
+    // `TRACK_EVENT` vs the manifest's `analytics.events`; dedupes its own warnings.
+    const trackEventChecker = createTrackEventChecker(options.manifest);
     // One-time "not supported in live v1" log gating per capability.
     const loggedOnce = new Set();
     const logOnce = (key, message) => {
@@ -377,7 +390,12 @@ export function createLiveHost(options) {
             }
             if (!res.ok) {
                 const msg = extractTrpcError(parsed) ?? `${procedure} failed: HTTP ${res.status}`;
-                return { error: msg, transient: isTransientHttpStatus(res.status) };
+                const rateLimit = parseSharedStorageRateLimit(extractTrpcErrorData(parsed)?.rateLimit);
+                return {
+                    error: msg,
+                    transient: isTransientHttpStatus(res.status),
+                    ...(rateLimit ? { rateLimit } : {}),
+                };
             }
             return { parsed };
         }
@@ -411,8 +429,13 @@ export function createLiveHost(options) {
      */
     async function callTrpcData(procedure, input, method) {
         const raw = await rawTrpcCall(procedure, input, method);
-        if (raw.error !== undefined)
-            return { error: raw.error, transient: raw.transient };
+        if (raw.error !== undefined) {
+            return {
+                error: raw.error,
+                transient: raw.transient,
+                ...(raw.rateLimit ? { rateLimit: raw.rateLimit } : {}),
+            };
+        }
         const data = extractData(raw.parsed);
         if (data === undefined) {
             return { error: `${procedure}: malformed response (no data)` };
@@ -659,16 +682,32 @@ export function createLiveHost(options) {
                 fetchImpl,
                 ...(params.baseModelGroup != null ? { baseModelGroup: params.baseModelGroup } : {}),
                 ...(params.currentVersionId != null ? { currentVersionId: params.currentVersionId } : {}),
+                ...(params.multiple ? { multiple: params.multiple } : {}),
                 ...(win.document ? { document: win.document } : {}),
                 ...(options.onPickerReady ? { onReady: options.onPickerReady } : {}),
                 onResolve: (selection) => {
                     openOverlays.delete(handle);
                     if (torn)
                         return;
+                    if (params.multiple) {
+                        // MULTI-select: the reply shape follows the REQUEST — always a list,
+                        // `[]` on dismissal, and never `selected` (the production contract).
+                        dispatchToBlock({
+                            type: resultType,
+                            payload: {
+                                requestId,
+                                selectedResources: selection && 'selectedResources' in selection ? selection.selectedResources : [],
+                            },
+                        });
+                        return;
+                    }
                     dispatchToBlock({
                         type: resultType,
                         // A dismissal omits `selected` (the hooks resolve to undefined/null).
-                        payload: { requestId, ...(selection ? { selected: selection.selected } : {}) },
+                        payload: {
+                            requestId,
+                            ...(selection && 'selected' in selection ? { selected: selection.selected } : {}),
+                        },
                     });
                 },
             });
@@ -723,6 +762,27 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'ESTIMATE_WORKFLOW_BATCH': {
+                        // Forwarded to the token-bound `blocks.estimateWorkflowBatch`, the
+                        // batch twin of the estimate above. Its reply is a plain
+                        // `{ snapshots, aggregate }` (unwrapped with `callTrpcData`); a
+                        // whole-call failure is FREE-TEXT `error`, a per-cell failure rides in
+                        // `snapshots`. Estimate only — nothing is submitted. Unroutable
+                        // without a requestId. Against a civitai that predates the procedure
+                        // the server's own not-found error comes back here as `error`.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        void callTrpcData('blocks.estimateWorkflowBatch', { blockToken: rawToken, bodies: typed.payload?.bodies }, 'POST').then((r) => {
+                            const data = r.data;
+                            dispatchToBlock({
+                                type: 'ESTIMATE_BATCH_RESULT',
+                                payload: data && Array.isArray(data.snapshots) && data.aggregate
+                                    ? { requestId, snapshots: data.snapshots, aggregate: data.aggregate }
+                                    : { requestId, error: r.error ?? 'batch estimate failed' },
+                            });
+                        });
+                        return;
+                    }
                     case 'SUBMIT_WORKFLOW': {
                         const body = typed.payload?.body;
                         // 🔴 KNOWN GAP, DELIBERATELY NOT CHANGED HERE — see below before
@@ -1158,11 +1218,37 @@ export function createLiveHost(options) {
                         // (or no `selected` on dismissal). DISCOVERY ONLY — re-priced +
                         // re-validated server-side at estimate/submit.
                         const resourceType = typed.payload?.resourceType === 'Checkpoint' ? 'Checkpoint' : 'LORA';
+                        // MULTI-select (`multiple: { max }`) — the production host's rules:
+                        // LoRA only, `max` a whole number ≥ 1 clamped to 5, and a refusal is
+                        // ANSWERED with `error` (the hook throws on it) rather than opening
+                        // a single-pick overlay the block did not ask for.
+                        const rawMultiple = typed.payload?.multiple;
+                        let multiple;
+                        if (rawMultiple !== undefined && rawMultiple !== null) {
+                            const max = typeof rawMultiple === 'object' ? rawMultiple.max : undefined;
+                            const refusal = resourceType === 'Checkpoint'
+                                ? 'OPEN_RESOURCE_PICKER: multiple is only supported for LoRA-family resource types, not Checkpoint.'
+                                : typeof max !== 'number' || !Number.isInteger(max) || max < 1
+                                    ? 'OPEN_RESOURCE_PICKER: multiple.max must be a whole number of at least 1.'
+                                    : null;
+                            if (refusal !== null) {
+                                // A refusal nobody can route is not worth sending.
+                                if (!isRoutableRequestId(requestId))
+                                    return;
+                                dispatchToBlock({
+                                    type: 'RESOURCE_PICKER_RESULT',
+                                    payload: { requestId, error: refusal },
+                                });
+                                return;
+                            }
+                            multiple = { max: Math.min(max, 5) };
+                        }
                         openPicker({
                             type: resourceType,
                             ...(typeof typed.payload?.baseModelGroup === 'string'
                                 ? { baseModelGroup: typed.payload.baseModelGroup }
                                 : {}),
+                            ...(multiple ? { multiple } : {}),
                         }, 'RESOURCE_PICKER_RESULT', requestId ?? '');
                         return;
                     }
@@ -1523,7 +1609,7 @@ export function createLiveHost(options) {
                             if (r.error) {
                                 dispatchToBlock({
                                     type: 'SHARED_APPEND_RESULT',
-                                    payload: { requestId: requestId ?? '', key: '', error: r.error },
+                                    payload: { requestId: requestId ?? '', key: '', ...sharedRefusal(r) },
                                 });
                                 return;
                             }
@@ -1542,7 +1628,7 @@ export function createLiveHost(options) {
                             dispatchToBlock({
                                 type: 'SHARED_UPDATE_RESULT',
                                 payload: r.error
-                                    ? { requestId: requestId ?? '', ok: false, error: r.error }
+                                    ? { requestId: requestId ?? '', ok: false, ...sharedRefusal(r) }
                                     : { requestId: requestId ?? '', ok: true },
                             });
                         });
@@ -1554,7 +1640,7 @@ export function createLiveHost(options) {
                             if (r.error) {
                                 dispatchToBlock({
                                     type: 'SHARED_VOTE_RESULT',
-                                    payload: { requestId: requestId ?? '', count: 0, error: r.error },
+                                    payload: { requestId: requestId ?? '', count: 0, ...sharedRefusal(r) },
                                 });
                                 return;
                             }
@@ -1572,7 +1658,7 @@ export function createLiveHost(options) {
                             if (r.error) {
                                 dispatchToBlock({
                                     type: 'SHARED_UNVOTE_RESULT',
-                                    payload: { requestId: requestId ?? '', count: 0, error: r.error },
+                                    payload: { requestId: requestId ?? '', count: 0, ...sharedRefusal(r) },
                                 });
                                 return;
                             }
@@ -1594,7 +1680,7 @@ export function createLiveHost(options) {
                                         requestId: requestId ?? '',
                                         ok: false,
                                         deleted: false,
-                                        error: r.error,
+                                        ...sharedRefusal(r),
                                     },
                                 });
                                 return;
@@ -1632,7 +1718,7 @@ export function createLiveHost(options) {
                             dispatchToBlock({
                                 type: 'SHARED_REPORT_RESULT',
                                 payload: r.error
-                                    ? { requestId: requestId ?? '', ok: false, error: r.error }
+                                    ? { requestId: requestId ?? '', ok: false, ...sharedRefusal(r) }
                                     : { requestId: requestId ?? '', ok: true },
                             });
                         });
@@ -1865,9 +1951,19 @@ export function createLiveHost(options) {
                         return;
                     }
                     case 'TRACK_EVENT':
+                        // Fire-and-forget, no reply — as in production, where the host
+                        // forwards it and the ingest keeps only what the manifest's
+                        // `analytics.events` declares. Nothing is sent anywhere from here;
+                        // the only effect is a once-per-problem console warning for what
+                        // production would drop (see `trackEventCheck.ts`).
+                        for (const message of trackEventChecker.check(typed.payload)) {
+                            // eslint-disable-next-line no-console
+                            console.warn(`[createLiveHost] ${message}`);
+                        }
+                        return;
                     case 'REQUEST_SIGN_IN':
                     case 'BLOCK_ERROR':
-                        // No-op. TRACK_EVENT/BLOCK_ERROR are fire-and-forget; REQUEST_SIGN_IN
+                        // No-op. BLOCK_ERROR is fire-and-forget; REQUEST_SIGN_IN
                         // can't open a login in dev (the viewer comes from the token — a
                         // failed viewer fetch already warns in resolveViewer).
                         return;
@@ -2051,6 +2147,21 @@ function extractData(parsed) {
  * `{ error: { message } }`. Returns undefined when no message is found.
  */
 function extractTrpcError(parsed) {
+    const message = trpcErrorShape(parsed)?.message;
+    return typeof message === 'string' ? message : undefined;
+}
+/**
+ * The `data` object of a tRPC error response (`{ error: { json: { data } } }`
+ * or `{ error: { data } }`), or undefined. The platform's error formatter puts
+ * machine-readable refusal fields here — `rateLimit` on a rate-limited
+ * shared-storage write — which {@link extractTrpcError} alone dropped.
+ */
+function extractTrpcErrorData(parsed) {
+    const data = trpcErrorShape(parsed)?.data;
+    return typeof data === 'object' && data !== null ? data : undefined;
+}
+/** The unwrapped tRPC error shape (superjson `{ json }` or plain), or undefined. */
+function trpcErrorShape(parsed) {
     if (typeof parsed !== 'object' || parsed === null)
         return undefined;
     const error = parsed.error;
@@ -2059,7 +2170,14 @@ function extractTrpcError(parsed) {
     const inner = 'json' in error ? error.json : error;
     if (typeof inner !== 'object' || inner === null)
         return undefined;
-    const message = inner.message;
-    return typeof message === 'string' ? message : undefined;
+    return inner;
+}
+/**
+ * The error fields of a shared-storage WRITE reply — `error`, plus `rateLimit`
+ * only when the refusal carried it. The dev-host twin of the production host's
+ * `sharedStorageErrorReply`, so the six write bridges build the refusal one way.
+ */
+function sharedRefusal(r) {
+    return { error: r.error ?? '', ...(r.rateLimit ? { rateLimit: r.rateLimit } : {}) };
 }
 //# sourceMappingURL=liveHost.js.map

package/dist/internal/mockHost.d.ts

@@ -93,6 +93,23 @@ export interface MockGenerationScenario {
      * a `(body) => number`. Overrides the legacy top-level `cost`. Default `8`.
      */
     costPerGen?: CostSpec;
+    /**
+     * The app author's per-generation fee, itemised as `cost.authorFee` on a
+     * QUOTE — the `ESTIMATE_RESULT` and the {@link submitCapRefusal} reply — and
+     * added into that quote's `cost.total` on top of {@link costPerGen}, as the
+     * 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}
+     * (a submitted workflow reports the generation's own cost), while a simulated
+     * {@link MockBuzzScenario.balance} is debited `costPerGen + authorFee`.
+     *
+     * `false` simulates a host that PREDATES the field: `authorFee` is omitted
+     * everywhere and no fee is added — use it to test your "not itemised" branch.
+     */
+    authorFee?: CostSpec | false;
     /**
      * Synthetic latency before the SUBMITTED→succeeded transition lands, in ms.
      * A single number, or a `[min, max]` range (uniform random). Applied to the
@@ -149,6 +166,35 @@ export interface MockGenerationScenario {
      * resource-compatibility rejection) to check how your block renders one.
      */
     failEstimateMessage?: string;
+    /**
+     * How the mock answers `ESTIMATE_WORKFLOW_BATCH` (`useBatchEstimate()`), so a
+     * block can exercise its per-cell fallback locally.
+     *
+     * - `'supported'` (default) — prices each cell exactly as an
+     *   `ESTIMATE_WORKFLOW` of that body would be priced (`costPerGen`,
+     *   `failEstimate` and the training rules all apply per cell) and replies with
+     *   the snapshots in order plus the host's aggregate.
+     * - `'unsupported'` — replies `{ error: 'unsupported on this host' }`, the
+     *   host's generic answer for a message it has no handler for.
+     *   `estimateBatch()` rejects with `BatchEstimateError` code `'unsupported'`.
+     * - `'silent'` — never replies, which is what a host that PREDATES the message
+     *   does. `estimateBatch()` rejects with code `'timeout'` once its wait ends;
+     *   pass a short `timeoutMs` to it in a test.
+     *
+     * Live-tunable via `setScenario({ generation: { batchEstimate } })`.
+     */
+    batchEstimate?: 'supported' | 'unsupported' | 'silent';
+    /**
+     * Indices of batch cells the mock answers as NOT PRICED IN TIME — the snapshot
+     * the host returns for a cell when the call's time budget runs out before that
+     * cell priced: `{ workflowId:'failed', status:'failed', error:'estimate timed out' }`
+     * (the host's string, held once in `BATCH_ESTIMATE_CELL_TIMEOUT_ERROR`).
+     * The other cells price normally and the call still resolves, so this tests a
+     * PARTIAL grid: the cell is `ok: false`, `timedOut: true`, with
+     * `WorkflowEstimateError` code `'failed'`. Applies only with
+     * `batchEstimate: 'supported'`. Default: unset (no cell times out).
+     */
+    batchEstimateTimedOutCells?: number[];
     /**
      * Force every SUBMIT to come back as a caught server EXCEPTION — the host's
      * real `failureSnapshot(err)` shape: `{ workflowId:'failed', status:'failed',
@@ -424,6 +470,27 @@ export interface MockSharedScenario {
      * error UX.
      */
     failNext?: number;
+    /**
+     * Refuse the next N shared WRITES (`append`/`update`/`vote`/`unvote`/
+     * `withdraw`/`report`) as RATE-LIMITED (counts down), the way the platform
+     * does when a per-(viewer, app) budget is empty: the reply carries the
+     * server's refusal text plus `rateLimit` metadata, so the hook rejects with
+     * `SharedStorageRateLimitError`. Checked before {@link failNext}, as the
+     * server checks the budget before attempting the write. Live-tunable via
+     * `setScenario({ shared: { rateLimitNext } })`.
+     */
+    rateLimitNext?: number;
+    /**
+     * The metadata a {@link rateLimitNext} refusal carries. `retryAfterSeconds`
+     * defaults to 60; `retryAt` defaults to now + `retryAfterSeconds`, computed
+     * when each refusal is sent. Pass a malformed value to exercise a block's
+     * fallback: the hook parses it, ignores the malformed value and throws a plain
+     * `Error`.
+     */
+    rateLimit?: {
+        retryAfterSeconds?: number;
+        retryAt?: string;
+    };
 }
 /**
  * Drives `createMockHost`. Every field is optional with a sensible default so
@@ -477,6 +544,18 @@ export interface MockHostOptions {
      * for that type. Defaults to a curated Checkpoint + LoRA pick.
      */
     cannedPicks?: Partial<Record<BlockResourcePickerType, CannedPick | null>>;
+    /**
+     * What a MULTI-select `OPEN_RESOURCE_PICKER` (`multiple: { max }`, LoRA only)
+     * answers with: these picks, in this order, cut to the request's `max` (itself
+     * clamped to 5) — the real host's `selectedResources`. `null` or `[]`
+     * simulates a dismissed picker (→ an empty list). Defaults to two curated
+     * LoRAs, or to `[]` when `cannedPicks.LORA` is `null`, so one "the viewer
+     * dismissed" setting covers both pick modes.
+     *
+     * The mock applies the real host's refusals too: `multiple` with a Checkpoint,
+     * or a `max` that is not a whole number ≥ 1, is answered with an `error`.
+     */
+    cannedMultiPicks?: CannedPick[] | null;
     /**
      * The canned moderated image returned from `OPEN_IMAGE_UPLOAD` when the block
      * requests `purpose:'display'` (the default) — what `useImageUpload().open()`
@@ -1054,7 +1133,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' | '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' | '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. */
@@ -1099,7 +1178,7 @@ 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`
+ * 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}.