@civitai/blocks-react 0.67.0 → 0.68.0

package/dist/hooks/useBatchEstimate.js

@@ -0,0 +1,195 @@
+import { useCallback, useState } from 'react';
+import { WORKFLOW_REQUEST_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+import { WorkflowEstimateError } from './useBuzzWorkflow.js';
+import { useRequestSequencer } from './useRequestSequencer.js';
+/**
+ * The most bodies one {@link UseBatchEstimate.estimateBatch} call may carry.
+ *
+ * The host's own cap (`BLOCK_ESTIMATE_BATCH_MAX_CELLS` in civitai/civitai). The
+ * hook refuses a longer list before sending it, with the code the host would
+ * have answered with a round trip later. A larger grid is priced in several
+ * calls; each call is still one request against the estimate allowance.
+ */
+export const BATCH_ESTIMATE_MAX_CELLS = 16;
+/**
+ * The host's generic reply to a request it registers no handler for. The copy is
+ * the host's (`BRIDGE_NACK_NO_HANDLER` in civitai/civitai), matched here ONCE so
+ * no app has to match it: branch on {@link BatchEstimateError.code} instead.
+ */
+const HOST_UNSUPPORTED_REPLY = 'unsupported on this host';
+/**
+ * The host's `snapshot.error` for a batch cell its time budget ran out on before
+ * the cell priced. The copy is the host's (`BLOCK_ESTIMATE_BATCH_TIMEOUT_ERROR`
+ * in civitai/civitai `src/server/routers/blocks.router.ts`). This is the ONE
+ * place the SDK spells it: the hook maps it to {@link BatchEstimateCell}'s
+ * `timedOut`, and the mock host answers with it. Not exported from the package:
+ * apps branch on `timedOut`, never on this string.
+ */
+export const BATCH_ESTIMATE_CELL_TIMEOUT_ERROR = 'estimate timed out';
+/**
+ * Thrown by {@link UseBatchEstimate.estimateBatch} when the WHOLE call failed.
+ *
+ * One cell failing is NOT this: a cell that could not be priced comes back as an
+ * `ok: false` entry in {@link BatchEstimateResult.cells} and the call resolves.
+ *
+ * Same three-audience split as `WorkflowEstimateError`:
+ * - {@link BatchEstimateError.code} is what you branch on.
+ * - {@link BatchEstimateError.hostError} is the host's or server's own text. It
+ *   is server-authored and unsanitised: log it, never render it.
+ * - `message` is a generic developer-facing summary whose wording is not a
+ *   contract.
+ */
+export class BatchEstimateError extends Error {
+    code;
+    /** The host's or server's reason, verbatim, when it gave one. */
+    hostError;
+    constructor(code, hostError) {
+        super(`batch estimate failed (${code})${hostError === undefined ? '' : ' — reason on .hostError'}`);
+        this.name = 'BatchEstimateError';
+        this.code = code;
+        if (hostError !== undefined)
+            this.hostError = hostError;
+    }
+}
+function toCell(snapshot) {
+    // The rule `useBuzzWorkflow().estimate()` applies to one reply, per cell.
+    if (snapshot.status === 'failed') {
+        return {
+            ok: false,
+            error: new WorkflowEstimateError(snapshot, 'failed'),
+            // The one place the host's per-cell timeout string is matched.
+            timedOut: snapshot.error === BATCH_ESTIMATE_CELL_TIMEOUT_ERROR,
+            snapshot,
+        };
+    }
+    const cost = snapshot.cost;
+    if (!cost || typeof cost.total !== 'number') {
+        return {
+            ok: false,
+            error: new WorkflowEstimateError(snapshot, 'no-cost'),
+            timedOut: false,
+            snapshot,
+        };
+    }
+    return { ok: true, cost, snapshot };
+}
+function toBatchEstimateError(err) {
+    if (err instanceof BatchEstimateError)
+        return err;
+    // Structural, not a message match — see `RequestTimeoutError`.
+    if (err instanceof RequestTimeoutError)
+        return new BatchEstimateError('timeout', err.message);
+    return new BatchEstimateError('failed', err instanceof Error ? err.message : String(err));
+}
+/**
+ * Price a grid of generations in ONE request: a list of workflow bodies in, one
+ * result per body (a cost, or that cell's error) plus a run total out. Backed by
+ * the `ESTIMATE_WORKFLOW_BATCH` → `ESTIMATE_BATCH_RESULT` bridge.
+ *
+ * Use it where an app would otherwise call `useBuzzWorkflow().estimate()` once
+ * per cell. Every rule a single estimate enforces still applies to each cell;
+ * what changes is the accounting and the round trips:
+ *
+ * - **One request against the estimate allowance**, whatever the number of
+ *   cells. On a page app that allowance is shared by every viewer of the app and
+ *   by the host's other reads for it, so a 16-cell grid used to take 16 of it per
+ *   pricing pass.
+ * - **Cells are metered separately.** The host also counts the cells of every
+ *   batch against an allowance of their own, shared like the estimate allowance
+ *   (on a page app, by every viewer of the app), so a batch is not a way around
+ *   it. A call over either is refused whole (`code: 'failed'`, the host's
+ *   rate-limit text on `hostError`); retry in a few seconds.
+ * - **At most {@link BATCH_ESTIMATE_MAX_CELLS} bodies per call.**
+ * - **`kind: 'training'` bodies are refused per cell.** Estimate a training run
+ *   with `useBuzzWorkflow().estimate()`.
+ *
+ * 🔴 ESTIMATE ONLY. There is no batch submit, watch or cancel and no id for the
+ * list. The total is a quote: nothing reserves it and each cell is priced again
+ * at `submit()`.
+ *
+ * Like `estimate()`, this does NOT prompt for consent. It needs the
+ * `ai:write:budgeted` scope; without it the call rejects with `code: 'failed'`.
+ *
+ * @example
+ * const { estimateBatch } = useBatchEstimate();
+ * try {
+ *   const { cells, aggregate } = await estimateBatch(bodies);
+ *   // cells[i] answers bodies[i]; a cell with `!c.ok && c.timedOut` was not
+ *   // priced in time — show it as unavailable and retry later
+ * } catch (err) {
+ *   if (!(err instanceof BatchEstimateError)) throw err;
+ *   if (err.code === 'unsupported') {
+ *     // this host has no batch estimate — price each cell with estimate()
+ *   } else {
+ *     // 'timeout' (a slow host, not an old one) or 'failed': show the estimate
+ *     // as unavailable and retry later — never one estimate() per cell
+ *   }
+ * }
+ */
+export function useBatchEstimate() {
+    const [pending, setPending] = useState(false);
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(null);
+    // Latest call wins: an app re-prices on a form edit, so an older reply landing
+    // after a newer one must not put the older total back on display.
+    const sequencer = useRequestSequencer();
+    const estimateBatch = useCallback(async (bodies, options) => {
+        const call = sequencer.begin();
+        if (sequencer.isCurrent(call)) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            if (!Array.isArray(bodies) || bodies.length === 0) {
+                throw new BatchEstimateError('invalid-request', 'invalid estimate batch');
+            }
+            if (bodies.length > BATCH_ESTIMATE_MAX_CELLS) {
+                throw new BatchEstimateError('invalid-request', 'estimate batch too large');
+            }
+            const reply = await sendTypedRequest(getTransport(), { type: 'ESTIMATE_WORKFLOW_BATCH', payload: { bodies } }, 'ESTIMATE_BATCH_RESULT', 
+            // Server-bound like the single estimate, and slower: up to 16 cost
+            // quotes behind one reply.
+            { timeoutMs: options?.timeoutMs ?? WORKFLOW_REQUEST_TIMEOUT_MS });
+            if (reply.error !== undefined) {
+                if (reply.error === HOST_UNSUPPORTED_REPLY) {
+                    throw new BatchEstimateError('unsupported', reply.error);
+                }
+                if (reply.error === 'invalid estimate batch' ||
+                    reply.error === 'estimate batch too large') {
+                    throw new BatchEstimateError('invalid-request', reply.error);
+                }
+                throw new BatchEstimateError('failed', reply.error);
+            }
+            const { snapshots, aggregate } = reply;
+            if (!snapshots || !aggregate || snapshots.length !== bodies.length) {
+                // A reply that does not answer every body cannot be lined up with the
+                // grid, so it is refused rather than shown shifted by a cell.
+                throw new BatchEstimateError('failed', 'the host returned a malformed batch estimate');
+            }
+            const next = { cells: snapshots.map(toCell), aggregate };
+            if (sequencer.isCurrent(call))
+                setResult(next);
+            return next;
+        }
+        catch (err) {
+            const wrapped = toBatchEstimateError(err);
+            if (sequencer.isCurrent(call)) {
+                setError(wrapped);
+                // Fail closed: a confirm gate reading `result` must not keep quoting the
+                // previous list's total after this one failed.
+                setResult(null);
+            }
+            // Thrown even when superseded or unmounted — the caller's `await` is not
+            // the component.
+            throw wrapped;
+        }
+        finally {
+            if (sequencer.isCurrent(call))
+                setPending(false);
+        }
+    }, [sequencer]);
+    return { estimateBatch, pending, result, error };
+}
+//# sourceMappingURL=useBatchEstimate.js.map

package/dist/hooks/useBlockAnalytics.d.ts

@@ -1,15 +1,57 @@
 /** What {@link useBlockAnalytics} returns. */
 export interface UseBlockAnalytics {
+    /**
+     * Send one custom event. Fire-and-forget: returns nothing, and nothing tells
+     * you whether it was recorded. See {@link useBlockAnalytics}
+     * for what is kept.
+     */
     track: (eventName: string, properties?: Record<string, unknown>) => void;
 }
 /**
- * Fire-and-forget analytics tracking. The host forwards events to its
- * analytics pipeline (ClickHouse in production); the block doesn't see
- * acknowledgements and shouldn't block on them.
+ * Custom events for your app's analytics panel. Fire-and-forget: the host
+ * forwards the event and the block gets no acknowledgement, so never wait on
+ * one or branch on it.
+ *
+ * 🔴 **Only what your manifest DECLARES is recorded.** Declare every event, and
+ * every property it carries, under `analytics.events` in `block.manifest.json`.
+ * The declaration is reviewed with the rest of the manifest, and events are
+ * accepted against the APPROVED version:
+ *
+ * - **An undeclared event** is counted as dropped. Its name and properties are
+ *   not stored; the owner sees only a count of drops.
+ * - **A declared event keeps only its declared properties**, each only when the
+ *   value has the declared type. An undeclared property, or a value of the
+ *   wrong type, is dropped and the rest of the event is kept.
+ * - **Property types are `enum`, `number` and `boolean`.** There is no free-text
+ *   string: a string is kept only when it is one of the enum's declared values.
+ *   So a prompt, an email or a username cannot be recorded. A `number` is not
+ *   range-limited, so do not use one to carry an identifier.
+ * - Names are lowercase snake_case: a letter, then up to 63 of `a-z`, `0-9`, `_`.
+ *   At most 50 events per app and 10 properties per event.
+ *
+ * **Limits.** Each mount of your app may send at most 10 events per second and
+ * 500 in total; the host batches events into bodies of at most 32 KiB. An event
+ * over a limit is dropped in the browser and is not counted anywhere, so the
+ * panel's numbers are floors. Events are recorded only from the production
+ * site.
+ *
+ * **What owners see.** Aggregates in the app's analytics panel: per declared
+ * event, the count, unique signed-in viewers, and the declared properties'
+ * breakdowns. Signed-out viewers are counted as events but never identified,
+ * and the team's own activity is excluded by default. Individual events are
+ * never shown.
+ *
+ * **Check locally.** In `dev:live`, pass your manifest to `createLiveHost`
+ * (`createLiveHost({ blockToken, manifest })`) and the console warns once per
+ * undeclared event, undeclared property, or value of the wrong type.
  *
  * @example
+ * // block.manifest.json
+ * // "analytics": { "events": { "generate_clicked": { "properties": {
+ * //   "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+ * //   "batch": { "type": "number" } } } } }
  * const { track } = useBlockAnalytics();
- * track('generate_clicked', { modelId });
+ * track('generate_clicked', { mode: 'txt2img', batch: 4 });
  */
 export declare function useBlockAnalytics(): UseBlockAnalytics;
 //# sourceMappingURL=useBlockAnalytics.d.ts.map

package/dist/hooks/useBlockAnalytics.js

@@ -1,13 +1,50 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 /**
- * Fire-and-forget analytics tracking. The host forwards events to its
- * analytics pipeline (ClickHouse in production); the block doesn't see
- * acknowledgements and shouldn't block on them.
+ * Custom events for your app's analytics panel. Fire-and-forget: the host
+ * forwards the event and the block gets no acknowledgement, so never wait on
+ * one or branch on it.
+ *
+ * 🔴 **Only what your manifest DECLARES is recorded.** Declare every event, and
+ * every property it carries, under `analytics.events` in `block.manifest.json`.
+ * The declaration is reviewed with the rest of the manifest, and events are
+ * accepted against the APPROVED version:
+ *
+ * - **An undeclared event** is counted as dropped. Its name and properties are
+ *   not stored; the owner sees only a count of drops.
+ * - **A declared event keeps only its declared properties**, each only when the
+ *   value has the declared type. An undeclared property, or a value of the
+ *   wrong type, is dropped and the rest of the event is kept.
+ * - **Property types are `enum`, `number` and `boolean`.** There is no free-text
+ *   string: a string is kept only when it is one of the enum's declared values.
+ *   So a prompt, an email or a username cannot be recorded. A `number` is not
+ *   range-limited, so do not use one to carry an identifier.
+ * - Names are lowercase snake_case: a letter, then up to 63 of `a-z`, `0-9`, `_`.
+ *   At most 50 events per app and 10 properties per event.
+ *
+ * **Limits.** Each mount of your app may send at most 10 events per second and
+ * 500 in total; the host batches events into bodies of at most 32 KiB. An event
+ * over a limit is dropped in the browser and is not counted anywhere, so the
+ * panel's numbers are floors. Events are recorded only from the production
+ * site.
+ *
+ * **What owners see.** Aggregates in the app's analytics panel: per declared
+ * event, the count, unique signed-in viewers, and the declared properties'
+ * breakdowns. Signed-out viewers are counted as events but never identified,
+ * and the team's own activity is excluded by default. Individual events are
+ * never shown.
+ *
+ * **Check locally.** In `dev:live`, pass your manifest to `createLiveHost`
+ * (`createLiveHost({ blockToken, manifest })`) and the console warns once per
+ * undeclared event, undeclared property, or value of the wrong type.
  *
  * @example
+ * // block.manifest.json
+ * // "analytics": { "events": { "generate_clicked": { "properties": {
+ * //   "mode": { "type": "enum", "values": ["txt2img", "img2img"] },
+ * //   "batch": { "type": "number" } } } } }
  * const { track } = useBlockAnalytics();
- * track('generate_clicked', { modelId });
+ * track('generate_clicked', { mode: 'txt2img', batch: 4 });
  */
 export function useBlockAnalytics() {
     const track = useCallback((eventName, properties) => {

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -207,7 +207,10 @@ export declare class WorkflowEstimateError extends Error {
      * rather than on prose. It is the ONLY stable branch target here:
      * `snapshot.error` is server-authored and can change without notice, and
      * {@link WorkflowEstimateError.message} is a generic developer-facing summary
-     * whose exact wording is not a contract either.
+     * whose exact wording is not a contract either. The one carve-out is a batch
+     * cell the host's time budget ran out on: it keeps `code: 'failed'`, and its
+     * stable signal is `timedOut: true` on the `useBatchEstimate()` cell, never a
+     * match on `snapshot.error`.
      *
      * 🔴 THIS IS WHAT A VIEWER-FACING MESSAGE MUST BE DERIVED FROM. Branch on
      * `code` and return a string your app owns and localises; never render

package/dist/hooks/useBuzzWorkflow.js

@@ -191,7 +191,10 @@ export class WorkflowEstimateError extends Error {
      * rather than on prose. It is the ONLY stable branch target here:
      * `snapshot.error` is server-authored and can change without notice, and
      * {@link WorkflowEstimateError.message} is a generic developer-facing summary
-     * whose exact wording is not a contract either.
+     * whose exact wording is not a contract either. The one carve-out is a batch
+     * cell the host's time budget ran out on: it keeps `code: 'failed'`, and its
+     * stable signal is `timedOut: true` on the `useBatchEstimate()` cell, never a
+     * match on `snapshot.error`.
      *
      * 🔴 THIS IS WHAT A VIEWER-FACING MESSAGE MUST BE DERIVED FROM. Branch on
      * `code` and return a string your app owns and localises; never render

package/dist/hooks/useResourcePicker.d.ts

@@ -1,43 +1,87 @@
 import type { BlockResourceInfo, BlockResourcePickerType } from '@civitai/app-sdk/blocks';
+/**
+ * The most resources ONE multi-select `open({ multiple })` can return — the
+ * same cap the generation body puts on `additionalResources`, so a full batch
+ * is always one a submit accepts. A larger `multiple.max` is CLAMPED to this.
+ */
+export declare const RESOURCE_PICKER_MULTIPLE_MAX = 5;
+/** The options every {@link UseResourcePicker} `open` call takes. */
+export interface ResourcePickerOpenOptions {
+    /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
+     * host rejects any other type (the modal never opens). */
+    resourceType: BlockResourcePickerType;
+    /**
+     * 🔴 OMIT THIS BY DEFAULT. It is an optional base-model family FILTER, not a
+     * label: whatever you pass, the host HIDES every resource outside that
+     * ecosystem, so the viewer's own perfectly valid LoRAs simply do not appear
+     * and the picker looks empty or broken. Omitting it is an unconstrained pick
+     * of the type — every resource the viewer can reach.
+     *
+     * Pass it ONLY when the block already holds a chosen checkpoint the pick has
+     * to match, and then DERIVE it from that checkpoint. Never a hardcoded
+     * ecosystem string: a literal pins every viewer of the app to whichever
+     * family the author happened to be testing with. Nor a literal reached
+     * through a fallback — `checkpoint?.baseModel ?? 'SDXL'` re-pins every viewer
+     * who has not picked yet, which is the same defect wearing a default.
+     *
+     * 🔴 WHERE THE FAMILY COMES FROM ON THIS HOOK'S ONLY SURFACE. This hook is
+     * PAGE-ONLY (`OPEN_RESOURCE_PICKER` is a page affordance; the model slot has
+     * the narrower `useCheckpointPicker` instead), and a page slot carries no
+     * checkpoint: `checkpoint` exists on `ModelSlotContext` alone, and
+     * `BlockContext` is a union with no index signature, so
+     * `useBlockContext().context.checkpoint` does not even typecheck. The source
+     * is {@link BlockResourceInfo}`.baseModel` — the `baseModel` of a Checkpoint
+     * THIS picker returned earlier:
+     *
+     *     const checkpoint = await open({ resourceType: 'Checkpoint' });
+     *     if (checkpoint) await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+     *
+     * Accepts an ecosystem key (e.g. 'Flux1', 'SDXL') OR a baseModel name (e.g.
+     * 'Flux.1 D'); the host collapses either to the ecosystem family. `''` is not
+     * a way to widen: the page host drops a zero-length value, so it is only ever
+     * a confusing spelling of omitting the key.
+     */
+    baseModelGroup?: string;
+}
+/**
+ * Multi-select: let the viewer pick up to `max` resources in ONE picker session.
+ *
+ * - **LoRA only.** `open({ resourceType: 'Checkpoint', multiple })` is a type
+ *   error, and at runtime it REJECTS — it is never quietly treated as a single
+ *   pick. A generation takes one checkpoint and a list of LoRAs.
+ * - **`max` is a whole number ≥ 1.** Anything above
+ *   {@link RESOURCE_PICKER_MULTIPLE_MAX} (5) is CLAMPED to it; anything that is
+ *   not a whole number ≥ 1 rejects.
+ * - `baseModelGroup` works exactly as it does for a single pick.
+ */
+export interface ResourcePickerMultiple {
+    max: number;
+}
 /** What {@link useResourcePicker} returns. */
 export interface UseResourcePicker {
-    open: (opts: {
-        /** Which resource type to pick. v1: `'Checkpoint' | 'LORA'` only — the
-         * host rejects any other type (the modal never opens). */
-        resourceType: BlockResourcePickerType;
+    open: {
         /**
-         * 🔴 OMIT THIS BY DEFAULT. It is an optional base-model family FILTER, not a
-         * label: whatever you pass, the host HIDES every resource outside that
-         * ecosystem, so the viewer's own perfectly valid LoRAs simply do not appear
-         * and the picker looks empty or broken. Omitting it is an unconstrained pick
-         * of the type — every resource the viewer can reach.
-         *
-         * Pass it ONLY when the block already holds a chosen checkpoint the pick has
-         * to match, and then DERIVE it from that checkpoint. Never a hardcoded
-         * ecosystem string: a literal pins every viewer of the app to whichever
-         * family the author happened to be testing with. Nor a literal reached
-         * through a fallback — `checkpoint?.baseModel ?? 'SDXL'` re-pins every viewer
-         * who has not picked yet, which is the same defect wearing a default.
-         *
-         * 🔴 WHERE THE FAMILY COMES FROM ON THIS HOOK'S ONLY SURFACE. This hook is
-         * PAGE-ONLY (`OPEN_RESOURCE_PICKER` is a page affordance; the model slot has
-         * the narrower `useCheckpointPicker` instead), and a page slot carries no
-         * checkpoint: `checkpoint` exists on `ModelSlotContext` alone, and
-         * `BlockContext` is a union with no index signature, so
-         * `useBlockContext().context.checkpoint` does not even typecheck. The source
-         * is {@link BlockResourceInfo}`.baseModel` — the `baseModel` of a Checkpoint
-         * THIS picker returned earlier:
-         *
-         *     const checkpoint = await open({ resourceType: 'Checkpoint' });
-         *     if (checkpoint) await open({ resourceType: 'LORA', baseModelGroup: checkpoint.baseModel });
+         * Single pick. Resolves with the chosen resource, or `null` when the viewer
+         * dismissed the picker.
+         */
+        (opts: ResourcePickerOpenOptions & {
+            multiple?: undefined;
+        }): Promise<BlockResourceInfo | null>;
+        /**
+         * Multi-select (see {@link ResourcePickerMultiple}). Resolves with the
+         * picked resources IN THE ORDER THE VIEWER PICKED THEM — never more than
+         * `max` — or `[]` when the viewer dismissed. Each entry is the same
+         * {@link BlockResourceInfo} a single pick returns.
          *
-         * Accepts an ecosystem key (e.g. 'Flux1', 'SDXL') OR a baseModel name (e.g.
-         * 'Flux.1 D'); the host collapses either to the ecosystem family. `''` is not
-         * a way to widen: the page host drops a zero-length value, so it is only ever
-         * a confusing spelling of omitting the key.
+         * Against a host that predates multi-select the viewer gets the single-pick
+         * picker, and this still resolves with a list: of the one resource they
+         * picked, or `[]`.
          */
-        baseModelGroup?: string;
-    }) => Promise<BlockResourceInfo | null>;
+        (opts: ResourcePickerOpenOptions & {
+            resourceType: 'LORA';
+            multiple: ResourcePickerMultiple;
+        }): Promise<BlockResourceInfo[]>;
+    };
 }
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
@@ -51,6 +95,13 @@ export interface UseResourcePicker {
  * pick. Resolves with the chosen {@link BlockResourceInfo}, or `null` when the
  * user dismissed without picking.
  *
+ * MULTI-SELECT: pass `multiple: { max }` with `resourceType: 'LORA'` and the
+ * viewer picks up to `max` LoRAs (at most {@link RESOURCE_PICKER_MULTIPLE_MAX})
+ * in ONE picker session. `open` then resolves with a LIST — the picks in the
+ * order the viewer made them, `[]` on dismiss — instead of a single resource.
+ * See {@link ResourcePickerMultiple}. Without `multiple`, nothing about a
+ * single pick changes.
+ *
  * DISCOVERY ONLY: the returned `versionId` is a hint, never an entitlement.
  * Feed it into `body.modelVersionId` (Checkpoint) or
  * `body.additionalResources` (LoRA) and submit — the host re-validates every id
@@ -61,14 +112,14 @@ export interface UseResourcePicker {
  * Host-mediated, same trust model as `useCheckpointPicker` / `useBuzzWorkflow`:
  * the block never touches the picker UI directly.
  *
- * 🔴 THE ORDER OF THE TWO `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT SWAP
- * THEM. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
+ * 🔴 THE ORDER OF THE `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT MOVE
+ * THE LAST ONE. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
  * `jsdocExample` inside its tag loop, so on a hook with several `@example` tags
  * the LAST one wins and becomes the single published example whenever the README
  * fence is unavailable (renamed heading, dropped fence). The unconstrained call
  * is what every agent should copy, so it is last. The constrained variant is
  * first, where a human reading top-down still meets the exception before the
- * default it excepts.
+ * default it excepts; the multi-select variant sits between them.
  *
  * @example
  * // CONSTRAINED — only when the pick has to match a checkpoint the block
@@ -83,6 +134,16 @@ export interface UseResourcePicker {
  * }
  *
  * @example
+ * // MULTI-SELECT — several LoRAs in one picker session, in pick order.
+ * const { open } = useResourcePicker();
+ * const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
+ * // [] when dismissed; otherwise up to 3 picks, in the order the viewer chose
+ * const additionalResources = loras.map((lora) => ({
+ *   modelVersionId: lora.versionId,
+ *   strength: lora.strength ?? 1,
+ * }));
+ *
+ * @example
  * // THE DEFAULT — no ecosystem filter at all. The viewer sees every LoRA they
  * // can reach, which is almost always what you want.
  * const { open } = useResourcePicker();

package/dist/hooks/useResourcePicker.js

@@ -1,7 +1,21 @@
 import { useCallback } from 'react';
+import { throwOnReplyError } from '../internal/replyError.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { sendTypedRequest } from '../transport/transport.js';
+/**
+ * The most resources ONE multi-select `open({ multiple })` can return — the
+ * same cap the generation body puts on `additionalResources`, so a full batch
+ * is always one a submit accepts. A larger `multiple.max` is CLAMPED to this.
+ */
+export const RESOURCE_PICKER_MULTIPLE_MAX = 5;
+/**
+ * The LoRA family, lower-cased. The host's picker accepts `LoCon` and `DoRA`
+ * beside `LORA` and matches case-insensitively, so the runtime check here does
+ * too — a caller reaching those through a cast is not refused by the SDK for
+ * something the host allows.
+ */
+const MULTIPLE_RESOURCE_TYPES = new Set(['lora', 'locon', 'dora']);
 /**
  * Drives the platform-side resource picker for PAGE App Blocks (Design 1 —
  * host-chrome). Generalizes {@link useCheckpointPicker} from Checkpoint-only to
@@ -14,6 +28,13 @@ import { sendTypedRequest } from '../transport/transport.js';
  * pick. Resolves with the chosen {@link BlockResourceInfo}, or `null` when the
  * user dismissed without picking.
  *
+ * MULTI-SELECT: pass `multiple: { max }` with `resourceType: 'LORA'` and the
+ * viewer picks up to `max` LoRAs (at most {@link RESOURCE_PICKER_MULTIPLE_MAX})
+ * in ONE picker session. `open` then resolves with a LIST — the picks in the
+ * order the viewer made them, `[]` on dismiss — instead of a single resource.
+ * See {@link ResourcePickerMultiple}. Without `multiple`, nothing about a
+ * single pick changes.
+ *
  * DISCOVERY ONLY: the returned `versionId` is a hint, never an entitlement.
  * Feed it into `body.modelVersionId` (Checkpoint) or
  * `body.additionalResources` (LoRA) and submit — the host re-validates every id
@@ -24,14 +45,14 @@ import { sendTypedRequest } from '../transport/transport.js';
  * Host-mediated, same trust model as `useCheckpointPicker` / `useBuzzWorkflow`:
  * the block never touches the picker UI directly.
  *
- * 🔴 THE ORDER OF THE TWO `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT SWAP
- * THEM. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
+ * 🔴 THE ORDER OF THE `@example` BLOCKS BELOW IS LOAD-BEARING — DO NOT MOVE
+ * THE LAST ONE. `<civitai-developer-docs>/scripts/gen-appblocks-hooks.mjs` assigns
  * `jsdocExample` inside its tag loop, so on a hook with several `@example` tags
  * the LAST one wins and becomes the single published example whenever the README
  * fence is unavailable (renamed heading, dropped fence). The unconstrained call
  * is what every agent should copy, so it is last. The constrained variant is
  * first, where a human reading top-down still meets the exception before the
- * default it excepts.
+ * default it excepts; the multi-select variant sits between them.
  *
  * @example
  * // CONSTRAINED — only when the pick has to match a checkpoint the block
@@ -46,6 +67,16 @@ import { sendTypedRequest } from '../transport/transport.js';
  * }
  *
  * @example
+ * // MULTI-SELECT — several LoRAs in one picker session, in pick order.
+ * const { open } = useResourcePicker();
+ * const loras = await open({ resourceType: 'LORA', multiple: { max: 3 } });
+ * // [] when dismissed; otherwise up to 3 picks, in the order the viewer chose
+ * const additionalResources = loras.map((lora) => ({
+ *   modelVersionId: lora.versionId,
+ *   strength: lora.strength ?? 1,
+ * }));
+ *
+ * @example
  * // THE DEFAULT — no ecosystem filter at all. The viewer sees every LoRA they
  * // can reach, which is almost always what you want.
  * const { open } = useResourcePicker();
@@ -56,16 +87,55 @@ import { sendTypedRequest } from '../transport/transport.js';
  */
 export function useResourcePicker() {
     const open = useCallback(async (opts) => {
-        const { selected } = await sendTypedRequest(getTransport(), {
+        if (opts.multiple == null) {
+            const { selected } = await sendTypedRequest(getTransport(), {
+                type: 'OPEN_RESOURCE_PICKER',
+                payload: {
+                    resourceType: opts.resourceType,
+                    ...(opts.baseModelGroup != null ? { baseModelGroup: opts.baseModelGroup } : {}),
+                },
+            }, 'RESOURCE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+            // Normalize the "dismissed" case to an explicit null so callers can
+            // `if (!picked) return;` without an `undefined` ambiguity.
+            return selected ?? null;
+        }
+        // ── Multi-select ──────────────────────────────────────────────────────
+        // Refused HERE, before anything is sent, for two reasons: the caller gets
+        // an error naming the mistake instead of a picker that never opens, and a
+        // host that predates multi-select never sees a request it would answer
+        // with the wrong thing (it ignores `multiple` and would happily open a
+        // single CHECKPOINT pick).
+        if (!MULTIPLE_RESOURCE_TYPES.has(String(opts.resourceType).trim().toLowerCase())) {
+            throw new Error(`useResourcePicker: \`multiple\` is only supported for LoRA picks, not ` +
+                `resourceType "${String(opts.resourceType)}". Call open() without \`multiple\` for a single pick.`);
+        }
+        const requestedMax = opts.multiple.max;
+        if (typeof requestedMax !== 'number' || !Number.isInteger(requestedMax) || requestedMax < 1) {
+            throw new Error('useResourcePicker: `multiple.max` must be a whole number of at least 1 ' +
+                `(values above ${RESOURCE_PICKER_MULTIPLE_MAX} are clamped to ${RESOURCE_PICKER_MULTIPLE_MAX}).`);
+        }
+        const max = Math.min(requestedMax, RESOURCE_PICKER_MULTIPLE_MAX);
+        const result = await sendTypedRequest(getTransport(), {
             type: 'OPEN_RESOURCE_PICKER',
             payload: {
                 resourceType: opts.resourceType,
                 ...(opts.baseModelGroup != null ? { baseModelGroup: opts.baseModelGroup } : {}),
+                multiple: { max },
             },
         }, 'RESOURCE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
-        // Normalize the "dismissed" case to an explicit null so callers can
-        // `if (!picked) return;` without an `undefined` ambiguity.
-        return selected ?? null;
+        // The host answers a multi request it will not open with `{ error }`.
+        throwOnReplyError(result, 'The host refused the multi-select resource picker request.');
+        // A host that knows multi-select answers `selectedResources` (`[]` on
+        // dismiss). One that predates it ignored `multiple`, opened a single pick
+        // and answered `selected` (or nothing, on dismiss) — still a list here, of
+        // one or none, so the caller has ONE result shape to handle either way.
+        const picked = Array.isArray(result.selectedResources)
+            ? result.selectedResources
+            : result.selected
+                ? [result.selected]
+                : [];
+        // Belt: never hand back more than was asked for.
+        return picked.slice(0, max);
     }, []);
     return { open };
 }