@civitai/blocks-react 0.67.1 → 0.69.0

package/dist/hooks/useWorkflowBatch.js

@@ -0,0 +1,352 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useBuzzWorkflow } from './useBuzzWorkflow.js';
+/**
+ * The most workflows one {@link useWorkflowBatch} may watch.
+ *
+ * Derived from the host's poll allowance, not picked: one watched workflow makes
+ * at most 60 / 1.5 = 40 polls a minute (one poll in flight, `intervalMs` 1,500
+ * between polls), and the viewer's poll allowance is 1,200 per 60 s per block
+ * instance, so 1,200 / 40 = 30 workflows is the most one viewer can watch before
+ * polls start coming back as placeholders. The developer docs' limits table
+ * gives the same figure. A list longer than this throws, because an app that
+ * needs more cells needs a different plan than "watch them all at once".
+ */
+export const WORKFLOW_BATCH_MAX_CELLS = 30;
+/**
+ * How many `cancel()` requests {@link UseWorkflowBatch.cancelAll} keeps in flight.
+ *
+ * Cancels charge the ESTIMATE allowance (150 per 10 s per block instance). On a
+ * page app every viewer of the app shares that allowance, along with the host's
+ * other reads for the app (viewer, balance, image and model lookups). Four at a
+ * time keeps a 16-cell cancel-all from landing as one burst on an allowance other
+ * people are using. Not exported: it is a pacing detail, not a contract.
+ */
+const CANCEL_CONCURRENCY = 4;
+/** Statuses after which a workflow will not change again. */
+const TERMINAL = new Set([
+    'succeeded',
+    'failed',
+    'canceled',
+    'expired',
+]);
+/**
+ * Placeholder ids a resolved `submit()` can carry when no workflow was created
+ * (see `useBuzzWorkflow().submit`). There is nothing behind them to watch.
+ */
+const NON_WORKFLOW_IDS = new Set(['failed', 'whatif']);
+const FRESH = { snapshot: null, phase: 'watching', error: null, cancel: 'idle' };
+function validateIds(ids) {
+    if (ids.length > WORKFLOW_BATCH_MAX_CELLS) {
+        throw new RangeError(`useWorkflowBatch: ${ids.length} workflow ids, but at most ${WORKFLOW_BATCH_MAX_CELLS} can be watched at once`);
+    }
+    const seen = new Set();
+    for (const id of ids) {
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new TypeError('useWorkflowBatch: every workflow id must be a non-empty string');
+        }
+        if (NON_WORKFLOW_IDS.has(id)) {
+            throw new TypeError(`useWorkflowBatch: '${id}' is not a workflow id. A submit that resolved with it created nothing to watch`);
+        }
+        if (seen.has(id)) {
+            throw new TypeError(`useWorkflowBatch: workflow id '${id}' appears more than once`);
+        }
+        seen.add(id);
+    }
+}
+function summarise(cells) {
+    const summary = {
+        total: cells.length,
+        running: 0,
+        succeeded: 0,
+        failed: 0,
+        canceled: 0,
+        expired: 0,
+        stopped: 0,
+        realisedCost: 0,
+        costedCells: 0,
+        settled: true,
+    };
+    for (const cell of cells) {
+        const status = cell.snapshot?.status;
+        if (status === undefined || !TERMINAL.has(status)) {
+            summary.running += 1;
+            if (cell.phase === 'stopped')
+                summary.stopped += 1;
+            continue;
+        }
+        summary[status] += 1;
+        const total = cell.snapshot?.cost?.total;
+        if (typeof total === 'number' && Number.isFinite(total)) {
+            summary.realisedCost += total;
+            summary.costedCells += 1;
+        }
+    }
+    summary.settled = summary.running === 0;
+    return summary;
+}
+/**
+ * Watch a set of already-submitted workflows as one batch, with per-cell status,
+ * a summary, and cancel-all. For grid apps that submit N workflows one by one
+ * with `useBuzzWorkflow().submit()` (each with its own confirmation) and then
+ * have to follow all N.
+ *
+ * 🔴 THE APP OWNS THE LIST, AND THE LIST IS THE BATCH. Pass the workflow ids as
+ * an array: append each id as its `submit()` resolves, and persist the same
+ * array (it is plain strings) to re-attach after a reload by passing it back.
+ * There is no server-side batch id. The host knows nothing about the grouping,
+ * so nothing here changes what the host allows: every cell is one ordinary
+ * `watch()` and every cancel is one ordinary `cancel()`.
+ *
+ * What it guarantees, and the host limits behind each:
+ *
+ * - **One poll in flight per workflow.** Each cell is one `watch()` loop. When a
+ *   loop is restarted (the list changes, `rewatch()`, a React StrictMode
+ *   remount), the new loop waits for the old loop's in-flight poll to return
+ *   first, so two polls for one workflow never overlap.
+ * - **At most {@link WORKFLOW_BATCH_MAX_CELLS} workflows.** That is the poll
+ *   allowance (1,200 per 60 s, per block instance and viewer) divided by one
+ *   watch's 40 polls a minute. A longer list throws.
+ * - **Cancel-all is paced and stops on refusal.** Cancels charge the estimate
+ *   allowance (150 per 10 s per block instance, shared by every viewer of a page
+ *   app). At most four are in flight. When the host answers one with a
+ *   non-terminal snapshot (its answer when that allowance is used up), the rest
+ *   of the call is not sent and comes back as `notAttempted`. Nothing is retried
+ *   automatically. Call `cancelAll()` again after a few seconds.
+ * - **A host failure placeholder is not a workflow outcome.** When the host
+ *   fails a poll or a cancel it answers with `{ workflowId: 'failed', status:
+ *   'failed' }`. `watch()` and `cancel()` resolve with that, but it says nothing
+ *   about the workflow, which may still be running. This hook never counts it as
+ *   a failed cell: a poll placeholder stops the cell (phase `'stopped'`, with
+ *   `error` set), and a cancel placeholder is a `'failed'` cancel.
+ * - **Unmounting stops every poll.** No state updates happen after unmount. A
+ *   `cancelAll()` already running keeps sending, because the viewer asked for it.
+ *
+ * Throws (at render) when the list is longer than
+ * {@link WORKFLOW_BATCH_MAX_CELLS}, has a duplicate, has an empty id, or has the
+ * `'failed'` / `'whatif'` placeholder a refused `submit()` resolves with.
+ *
+ * Needs the same `ai:write:budgeted` scope as `submit()`. A viewer who submitted
+ * already has it.
+ *
+ * @example
+ * const { submit } = useBuzzWorkflow();
+ * const [ids, setIds] = useState<string[]>(() => loadSavedIds());
+ * const batch = useWorkflowBatch(ids);
+ *
+ * async function runCell(body: WorkflowBody, key: string) {
+ *   const snap = await submit(body, { idempotencyKey: key });
+ *   if (snap.workflowId !== 'failed') setIds((prev) => [...prev, snap.workflowId]);
+ * }
+ *
+ * useEffect(() => saveIds(ids), [ids]);
+ *
+ * // batch.summary.running, batch.summary.realisedCost, batch.cells[i].snapshot …
+ * const result = await batch.cancelAll();
+ * if (!result.complete) showRetryCancel(result);
+ */
+export function useWorkflowBatch(workflowIds, options) {
+    validateIds(workflowIds);
+    // A private `useBuzzWorkflow()` instance, so the app's own instance's
+    // `result`/`status` are not overwritten by 16 cells' updates.
+    const { watch, cancel } = useBuzzWorkflow();
+    const [states, setStates] = useState(() => new Map());
+    // Mirror of `states` for async code, which must not read a stale closure.
+    const statesRef = useRef(states);
+    statesRef.current = states;
+    const idsKey = workflowIds.join('\u0000');
+    const idsRef = useRef(workflowIds);
+    idsRef.current = workflowIds;
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const mountedRef = useRef(false);
+    /** Per workflow: the running loop's controller and a promise that settles when it ends. */
+    const loopsRef = useRef(new Map());
+    const cancelAllRef = useRef(null);
+    const patch = useCallback((workflowId, change) => {
+        if (!mountedRef.current)
+            return;
+        setStates((prev) => {
+            const next = new Map(prev);
+            next.set(workflowId, { ...(prev.get(workflowId) ?? FRESH), ...change });
+            return next;
+        });
+    }, []);
+    const startLoop = useCallback((workflowId) => {
+        const loops = loopsRef.current;
+        const previous = loops.get(workflowId);
+        previous?.controller.abort();
+        const controller = new AbortController();
+        // 🔴 CHAIN ON THE PREVIOUS LOOP. Aborting a `watch()` does not withdraw a
+        // poll already in flight (the host can hold it up to 15 s); the loop only
+        // sees the abort when that poll returns. Starting the new loop at once would
+        // put two polls for one workflow in flight.
+        const done = (previous?.done ?? Promise.resolve()).then(async () => {
+            if (controller.signal.aborted)
+                return;
+            try {
+                const final = await watch(workflowId, {
+                    ...optionsRef.current,
+                    signal: controller.signal,
+                    onUpdate: (snapshot) => {
+                        if (controller.signal.aborted || snapshot.workflowId !== workflowId)
+                            return;
+                        patch(workflowId, { snapshot });
+                    },
+                });
+                if (controller.signal.aborted)
+                    return;
+                if (final.workflowId !== workflowId) {
+                    patch(workflowId, {
+                        phase: 'stopped',
+                        error: new Error(`useWorkflowBatch: the host answered a poll for ${workflowId} with a failure placeholder, not the workflow's status`),
+                    });
+                    return;
+                }
+                patch(workflowId, {
+                    snapshot: final,
+                    phase: TERMINAL.has(final.status) ? 'settled' : 'stopped',
+                    error: null,
+                });
+            }
+            catch (err) {
+                if (controller.signal.aborted)
+                    return;
+                patch(workflowId, { phase: 'stopped', error: err instanceof Error ? err : new Error(String(err)) });
+            }
+        });
+        loops.set(workflowId, { controller, done });
+    }, [watch, patch]);
+    useEffect(() => {
+        mountedRef.current = true;
+        const loops = loopsRef.current;
+        return () => {
+            mountedRef.current = false;
+            for (const loop of loops.values())
+                loop.controller.abort();
+        };
+    }, []);
+    // Diff the list against the running loops: start new ids, stop removed ones.
+    useEffect(() => {
+        const loops = loopsRef.current;
+        const wanted = new Set(idsRef.current);
+        for (const [id, loop] of loops) {
+            // Abort, but KEEP the entry: its `done` is what a re-added id's new loop
+            // must wait on, because the aborted loop's poll may still be in flight.
+            if (!wanted.has(id))
+                loop.controller.abort();
+        }
+        for (const id of idsRef.current) {
+            const loop = loops.get(id);
+            if (loop && !loop.controller.signal.aborted)
+                continue;
+            const state = statesRef.current.get(id);
+            // A settled or stopped cell stays as it is until `rewatch()`.
+            if (state && state.phase !== 'watching')
+                continue;
+            startLoop(id);
+        }
+        setStates((prev) => {
+            let changed = false;
+            const next = new Map(prev);
+            for (const id of prev.keys()) {
+                if (!wanted.has(id)) {
+                    next.delete(id);
+                    changed = true;
+                }
+            }
+            return changed ? next : prev;
+        });
+        // `idsKey` stands for the list's contents; the list itself is read from the ref.
+    }, [idsKey, startLoop]);
+    const rewatch = useCallback(() => {
+        for (const id of idsRef.current) {
+            if (statesRef.current.get(id)?.phase !== 'stopped')
+                continue;
+            patch(id, { phase: 'watching', error: null });
+            startLoop(id);
+        }
+    }, [patch, startLoop]);
+    const cancelAll = useCallback(() => {
+        if (cancelAllRef.current)
+            return cancelAllRef.current;
+        const run = async () => {
+            const ids = [...idsRef.current];
+            const outcome = new Map();
+            const targets = [];
+            for (const id of ids) {
+                const status = statesRef.current.get(id)?.snapshot?.status;
+                if (status !== undefined && TERMINAL.has(status))
+                    outcome.set(id, 'alreadySettled');
+                else
+                    targets.push(id);
+            }
+            let refusedSeen = false;
+            let next = 0;
+            const worker = async () => {
+                for (let id = targets[next]; id !== undefined; id = targets[next]) {
+                    next += 1;
+                    if (refusedSeen) {
+                        outcome.set(id, 'notAttempted');
+                        patch(id, { cancel: 'refused' });
+                        continue;
+                    }
+                    patch(id, { cancel: 'pending' });
+                    let snapshot;
+                    try {
+                        snapshot = await cancel(id);
+                    }
+                    catch {
+                        outcome.set(id, 'failed');
+                        patch(id, { cancel: 'failed' });
+                        continue;
+                    }
+                    if (snapshot.workflowId !== id) {
+                        // The host's failure placeholder: the request failed, the workflow's
+                        // state is unknown.
+                        outcome.set(id, 'failed');
+                        patch(id, { cancel: 'failed' });
+                    }
+                    else if (TERMINAL.has(snapshot.status)) {
+                        outcome.set(id, snapshot.status === 'canceled' ? 'canceled' : 'alreadySettled');
+                        loopsRef.current.get(id)?.controller.abort();
+                        patch(id, { cancel: 'done', snapshot, phase: 'settled', error: null });
+                    }
+                    else {
+                        refusedSeen = true;
+                        outcome.set(id, 'refused');
+                        patch(id, { cancel: 'refused' });
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(CANCEL_CONCURRENCY, targets.length) }, () => worker()));
+            const result = {
+                canceled: [],
+                alreadySettled: [],
+                refused: [],
+                notAttempted: [],
+                failed: [],
+                complete: true,
+            };
+            for (const id of ids) {
+                const bucket = outcome.get(id);
+                if (bucket)
+                    result[bucket].push(id);
+            }
+            result.complete =
+                result.refused.length === 0 && result.notAttempted.length === 0 && result.failed.length === 0;
+            return result;
+        };
+        const promise = run().finally(() => {
+            cancelAllRef.current = null;
+        });
+        cancelAllRef.current = promise;
+        return promise;
+    }, [cancel, patch]);
+    const cells = useMemo(() => workflowIds.map((workflowId) => ({ workflowId, ...(states.get(workflowId) ?? FRESH) })), 
+    // `idsKey` stands for the list's contents, so a new array with the same ids
+    // does not rebuild the cells.
+    [idsKey, states]);
+    const summary = useMemo(() => summarise(cells), [cells]);
+    return { cells, summary, cancelAll, rewatch };
+}
+//# sourceMappingURL=useWorkflowBatch.js.map

package/dist/index.d.ts

@@ -27,6 +27,10 @@ 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 { WORKFLOW_BATCH_MAX_CELLS, useWorkflowBatch } from './hooks/useWorkflowBatch.js';
+export type { UseWorkflowBatch, WorkflowBatchCancelResult, WorkflowBatchCancelState, WorkflowBatchCell, WorkflowBatchCellPhase, WorkflowBatchOptions, WorkflowBatchSummary, } from './hooks/useWorkflowBatch.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export type { UseEntitlements, Entitlement } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
@@ -74,8 +78,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 +112,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,8 @@ 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 { WORKFLOW_BATCH_MAX_CELLS, useWorkflowBatch } from './hooks/useWorkflowBatch.js';
 export { useEntitlements } from './hooks/useEntitlements.js';
 export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
 export { useTip } from './hooks/useTip.js';
@@ -62,7 +64,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 +86,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