@civitai/blocks-react 0.72.3 → 0.73.0

package/README.md

@@ -7,6 +7,17 @@ Pairs with [`@civitai/app-sdk`](https://www.npmjs.com/package/@civitai/app-sdk)'
 `postMessage` contract. This package adds the transport that actually moves bytes
 and the React hooks block authors call.
 
+> **Starting a new block app? Start from
+> [`@civitai/sdk`](https://www.npmjs.com/package/@civitai/sdk).** The three
+> packages are layers over one host contract, and all three are supported:
+>
+> - **`@civitai/sdk`** is the client new block apps start on: `initialize()`,
+>   then `app.workflows`, `app.storage`, `app.site` and `app.host`.
+> - **`@civitai/app-sdk/blocks`** is the contract itself: the workflow body
+>   types, the manifest types and the host message shapes.
+> - **`@civitai/blocks-react`** (this package) is the React hook binding over
+>   that same contract.
+
 ## Install
 
 ```bash
@@ -2239,6 +2250,128 @@ unstamped) or an already-posted id is refused with
 rule, the scope check, the real scan, or an older host's picker. `dev:live` has
 no bytes path: `upload` rejects with `the host returned no uploaded image`.
 
+### `useImagePicker()`
+
+Let the viewer pick one of their **existing** Civitai images: the ones they have
+posted, and the ones they made with the Civitai generator. The host opens its own
+picker over the viewer's library, and your app receives only what the viewer
+picked. Returns `{ open }`. `open()` resolves with one image, or `null` if
+nothing was picked.
+
+```tsx
+const { open } = useImagePicker();
+
+const image = await open();   // BlockPickedImageInfo | null
+if (image) {
+  // image.source     'posted' | 'generated'
+  // image.url        a Civitai-hosted image URL
+  // image.width, image.height
+  // image.nsfwLevel  the image's rating; it can be a mature level
+  // image.imageId    set for a posted image, undefined for a generated one
+}
+```
+
+**Several images in one session: `multiple: { max }`.** `open` then resolves with
+a **list** of up to `max` images instead of a single image, or `[]` if nothing
+was picked.
+
+```tsx
+const { open } = useImagePicker();
+
+const images = await open({ multiple: { max: 5 } });
+// [] when nothing was picked; otherwise 1 to 5 images
+const urls = images.map((image) => image.url);
+```
+
+**One library only: `sources`.** Pass `['posted']` or `['generated']` to offer
+just that library. Leave it out to offer both.
+
+```tsx
+const { open } = useImagePicker();
+
+const output = await open({ sources: ['generated'] });
+// output?.imageId is always undefined here: a generator output has no image id
+```
+
+If your app decides at runtime whether to ask for one image or several, pass
+`multiple` as a value that may be `undefined`. The result is then either shape,
+so narrow it with `Array.isArray`:
+
+```tsx
+const { open } = useImagePicker();
+
+const picked = await open({ multiple: allowSeveral ? { max: 3 } : undefined });
+const images = Array.isArray(picked) ? picked : picked ? [picked] : [];
+```
+
+What the viewer can pick, and what you get back:
+
+- **The host decides what is pickable.** Posted images: the viewer's own, in a
+  published post, fully scanned, not flagged and rated. Generated images: the
+  viewer's own finished generator outputs that have a rating. In both cases the
+  viewer is offered only what their own browsing settings on Civitai allow them
+  to see. An unrated image is never offered. Images only, no video. Your app
+  never sees the rest of the library.
+- 🔴 **A pick can be a mature image.** `nsfwLevel` is the image's rating, and it
+  is never `0`. The image was offered to this viewer under this viewer's own
+  settings. That says nothing about anyone else. If your app shows a pick to
+  anybody other than the viewer who picked it (a shared board, a gallery, a
+  public post), it is your app's job to check `nsfwLevel` and decide who may
+  see it.
+- **`imageId` is set only on a posted image.** A generator output that was never
+  posted has no image id, so check `image.source` or `image.imageId` before you
+  use it.
+- **A posted pick's `url` is a resized copy, not the original file.** `width` and
+  `height` are the size that copy is requested at. The host chooses one with both
+  sides between 64 and 2048 pixels, and a small original is scaled up. The image
+  server normally returns exactly that size, but it can return the original
+  while the resized copy is still being produced. A posted image that has no
+  size in that range (a very long or very wide one) is not offered.
+- 🔴 **A generated pick's `url` is the generator's own output link and may stop
+  working after a while.** Use it soon after the pick and do not store it for
+  later. Its `width` and `height` are the output's own size.
+
+What `open` resolves and rejects with:
+
+- **`null` (or `[]` with `multiple`) means nothing was picked.** Usually the
+  viewer closed the picker. A signed-out viewer sees the picker with a sign-in
+  button, and closing it gives the same result. The host also answers this way
+  immediately, without showing a picker, while your app is being viewed in
+  review mode or is not ready yet.
+- **`max` is a whole number of at least 1, capped at 20** (exported as
+  `IMAGE_PICKER_MULTIPLE_MAX`). A larger value is clamped to 20. `0`, a negative
+  number or a fraction rejects before anything is sent, and so does an empty
+  `sources` or a value other than `'posted'` and `'generated'`.
+- **A refusal rejects.** If the host refuses the request, `open` rejects with an
+  `Error` carrying the host's message. It never resolves with `null` for a
+  refusal.
+- **Page apps only.** On any other surface the host answers at once and `open`
+  rejects with `unsupported on this host`.
+- **On a host that does not have the picker yet**, the request gets no answer and
+  `open` rejects with a `RequestTimeoutError` after 10 minutes.
+
+Using a pick as the source image of a generation: a pick's `url` is hosted by
+Civitai, so `{ url, width, height }` passes the address check a generation body
+makes on its `sourceImage`. That is the only thing this hook settles. The
+generation body has its own rules, including 64 to 2048 pixels per side. A posted
+pick is already within that range. A generated pick can be larger, and a
+generation body refuses a size above 2048.
+
+With the mock host (`createMockHost` or `Harness` from
+`@civitai/blocks-react/testing`) there is no picker to click through: `open`
+resolves at once. By default the mock holds one posted image and one generated
+image. Pass `cannedImagePicks: [...]` to set the viewer's library. The mock keeps
+only the images matching the request's `sources`, then answers a single pick with
+the first one and a `multiple` pick with the first `max`. `cannedImagePicks: null`
+is a viewer who always closes the picker. Like the host, the mock offers a
+repeated image once and drops an `imageId` from a generated image. It does not
+model browsing settings or ratings: it returns whatever `nsfwLevel` you give an
+image, so use that to test how your app handles a mature pick. The mock refuses
+an invalid `sources` or `multiple` with an error, and answers
+`unsupported on this host` when its `context` is a model slot. `dev:live` cannot
+list the viewer's images, so there `open` rejects with a message saying to use
+the mock host.
+
 ### `useSaveImage()`
 
 Ask the host to download a file to the viewer's device. **A block cannot

package/dist/hooks/useImagePicker.d.ts

@@ -0,0 +1,126 @@
+import type { BlockImagePickerSource, BlockPickedImageInfo } from '@civitai/app-sdk/blocks';
+/**
+ * The most images ONE multi pick `open({ multiple })` can return. A larger
+ * `multiple.max` is CLAMPED to this, here and again by the host.
+ */
+export declare const IMAGE_PICKER_MULTIPLE_MAX = 20;
+/** The options every {@link UseImagePicker} `open` call takes. All optional. */
+export interface ImagePickerOpenOptions {
+    /**
+     * Which of the viewer's libraries the picker offers: `'posted'` (images they
+     * posted to Civitai), `'generated'` (outputs they made with the Civitai
+     * generator), or both. OMIT it to offer both.
+     *
+     * An empty array or an unknown member rejects before anything is sent. A
+     * repeated member is harmless.
+     */
+    sources?: BlockImagePickerSource[];
+}
+/**
+ * Multi pick: let the viewer pick up to `max` images in ONE picker session.
+ *
+ * `max` is a whole number ≥ 1. Anything above
+ * {@link IMAGE_PICKER_MULTIPLE_MAX} (20) is CLAMPED to it; anything that is not
+ * a whole number ≥ 1 rejects before anything is sent.
+ */
+export interface ImagePickerMultiple {
+    max: number;
+}
+/**
+ * What `open({ multiple })` rejects with when the host's reply to a multi pick
+ * carries neither an image list nor an error. A multi pick is always answered
+ * with a list (`[]` when nothing was picked), so a reply without one is a
+ * malformed reply, not a dismiss.
+ */
+export declare const IMAGE_PICKER_NO_LIST_ERROR = "the host returned no image list";
+/** What {@link useImagePicker} returns. */
+export interface UseImagePicker {
+    open: {
+        /**
+         * Single pick. Resolves with the chosen image, or `null` when nothing was
+         * picked. Rejects when the host refuses the request.
+         */
+        (opts?: ImagePickerOpenOptions & {
+            multiple?: undefined;
+        }): Promise<BlockPickedImageInfo | null>;
+        /**
+         * Multi pick (see {@link ImagePickerMultiple}). Resolves with the picked
+         * images, never more than `max`, or `[]` when nothing was picked. Each
+         * entry is the same {@link BlockPickedImageInfo} a single pick returns.
+         * Rejects when the host refuses the request.
+         */
+        (opts: ImagePickerOpenOptions & {
+            multiple: ImagePickerMultiple;
+        }): Promise<BlockPickedImageInfo[]>;
+        /**
+         * A `multiple` decided at runtime, e.g.
+         * `open({ multiple: many ? { max: 3 } : undefined })`. The result is a list
+         * when `multiple` was set and a single image or `null` when it was not, so
+         * narrow it with `Array.isArray`.
+         */
+        (opts: ImagePickerOpenOptions & {
+            multiple?: ImagePickerMultiple | undefined;
+        }): Promise<BlockPickedImageInfo | BlockPickedImageInfo[] | null>;
+    };
+}
+/**
+ * Lets the viewer pick one or more of their EXISTING Civitai images: the ones
+ * they posted, and the ones they made with the Civitai generator.
+ *
+ * `open` asks the host to open its OWN picker over the viewer's library. The
+ * viewer browses in host chrome; the block never lists the library and receives
+ * only what the viewer picked, as {@link BlockPickedImageInfo}. That type's
+ * docblock is the one place that states what is pickable, what `url`, `width`
+ * and `height` mean for each library, and that a pick can be a mature image.
+ *
+ * - Single pick (the default) resolves with the image, or `null`.
+ * - `multiple: { max }` resolves with a LIST of up to `max` images (at most
+ *   {@link IMAGE_PICKER_MULTIPLE_MAX}), or `[]`.
+ * - `sources` narrows the picker to one library. Omit it for both.
+ *
+ * `null` / `[]` MEAN "NOTHING WAS PICKED", which is usually the viewer closing
+ * the picker (a signed-out viewer sees it with a sign-in button, and closing it
+ * is the same). The host also answers that way AT ONCE, without showing a
+ * picker, while the app is being viewed in review mode or is not ready yet.
+ *
+ * A REFUSAL REJECTS; it is never `null`. `open` rejects with the host's message
+ * when the host refuses the request, and with `unsupported on this host` on a
+ * surface that does not offer the picker (it is a page-app affordance). It also
+ * rejects, before sending anything, for an empty or unknown `sources` and for a
+ * `multiple.max` that is not a whole number ≥ 1. A multi pick whose reply
+ * carries no list rejects with {@link IMAGE_PICKER_NO_LIST_ERROR}.
+ *
+ * A host that predates the picker does not answer the request at all, so the
+ * call rejects with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * 🔴 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. The plain single pick is what most apps should copy, so
+ * it is last.
+ *
+ * @example
+ * // ONE LIBRARY — only the viewer's generator outputs.
+ * const { open } = useImagePicker();
+ * const output = await open({ sources: ['generated'] });
+ * // output?.imageId is undefined: a generator output has no image id
+ *
+ * @example
+ * // MULTI PICK — up to 5 images in one picker session.
+ * const { open } = useImagePicker();
+ * const images = await open({ multiple: { max: 5 } });
+ * // [] when nothing was picked; otherwise 1 to 5 picks
+ * const urls = images.map((image) => image.url);
+ *
+ * @example
+ * // THE DEFAULT — one image, from either library.
+ * const { open } = useImagePicker();
+ * const image = await open();
+ * if (image) {
+ *   // image.url, image.width, image.height, image.nsfwLevel, image.source
+ * }
+ */
+export declare function useImagePicker(): UseImagePicker;
+//# sourceMappingURL=useImagePicker.d.ts.map

package/dist/hooks/useImagePicker.js

@@ -0,0 +1,133 @@
+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';
+import { useTransportConnection } from './useTransportConnection.js';
+/**
+ * The most images ONE multi pick `open({ multiple })` can return. A larger
+ * `multiple.max` is CLAMPED to this, here and again by the host.
+ */
+export const IMAGE_PICKER_MULTIPLE_MAX = 20;
+/**
+ * What `open({ multiple })` rejects with when the host's reply to a multi pick
+ * carries neither an image list nor an error. A multi pick is always answered
+ * with a list (`[]` when nothing was picked), so a reply without one is a
+ * malformed reply, not a dismiss.
+ */
+export const IMAGE_PICKER_NO_LIST_ERROR = 'the host returned no image list';
+/** The two libraries the picker knows. Anything else is refused before sending. */
+const IMAGE_PICKER_SOURCES = new Set([
+    'posted',
+    'generated',
+]);
+/**
+ * Lets the viewer pick one or more of their EXISTING Civitai images: the ones
+ * they posted, and the ones they made with the Civitai generator.
+ *
+ * `open` asks the host to open its OWN picker over the viewer's library. The
+ * viewer browses in host chrome; the block never lists the library and receives
+ * only what the viewer picked, as {@link BlockPickedImageInfo}. That type's
+ * docblock is the one place that states what is pickable, what `url`, `width`
+ * and `height` mean for each library, and that a pick can be a mature image.
+ *
+ * - Single pick (the default) resolves with the image, or `null`.
+ * - `multiple: { max }` resolves with a LIST of up to `max` images (at most
+ *   {@link IMAGE_PICKER_MULTIPLE_MAX}), or `[]`.
+ * - `sources` narrows the picker to one library. Omit it for both.
+ *
+ * `null` / `[]` MEAN "NOTHING WAS PICKED", which is usually the viewer closing
+ * the picker (a signed-out viewer sees it with a sign-in button, and closing it
+ * is the same). The host also answers that way AT ONCE, without showing a
+ * picker, while the app is being viewed in review mode or is not ready yet.
+ *
+ * A REFUSAL REJECTS; it is never `null`. `open` rejects with the host's message
+ * when the host refuses the request, and with `unsupported on this host` on a
+ * surface that does not offer the picker (it is a page-app affordance). It also
+ * rejects, before sending anything, for an empty or unknown `sources` and for a
+ * `multiple.max` that is not a whole number ≥ 1. A multi pick whose reply
+ * carries no list rejects with {@link IMAGE_PICKER_NO_LIST_ERROR}.
+ *
+ * A host that predates the picker does not answer the request at all, so the
+ * call rejects with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * 🔴 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. The plain single pick is what most apps should copy, so
+ * it is last.
+ *
+ * @example
+ * // ONE LIBRARY — only the viewer's generator outputs.
+ * const { open } = useImagePicker();
+ * const output = await open({ sources: ['generated'] });
+ * // output?.imageId is undefined: a generator output has no image id
+ *
+ * @example
+ * // MULTI PICK — up to 5 images in one picker session.
+ * const { open } = useImagePicker();
+ * const images = await open({ multiple: { max: 5 } });
+ * // [] when nothing was picked; otherwise 1 to 5 picks
+ * const urls = images.map((image) => image.url);
+ *
+ * @example
+ * // THE DEFAULT — one image, from either library.
+ * const { open } = useImagePicker();
+ * const image = await open();
+ * if (image) {
+ *   // image.url, image.width, image.height, image.nsfwLevel, image.source
+ * }
+ */
+export function useImagePicker() {
+    useTransportConnection();
+    const open = useCallback(async (opts) => {
+        // Both checks run BEFORE anything is sent: the caller gets an error naming
+        // the mistake instead of the host's refusal a round-trip later.
+        const requestedSources = opts?.sources;
+        if (requestedSources != null) {
+            if (!Array.isArray(requestedSources) || requestedSources.length === 0) {
+                throw new Error("useImagePicker: `sources` must be a non-empty array of 'posted' and/or 'generated'. " +
+                    'Omit it to offer both.');
+            }
+            const unknown = requestedSources.find((source) => typeof source !== 'string' || !IMAGE_PICKER_SOURCES.has(source));
+            if (unknown !== undefined) {
+                throw new Error(`useImagePicker: unknown \`sources\` entry "${String(unknown)}". ` +
+                    "The picker offers 'posted' and 'generated'.");
+            }
+        }
+        // OMIT the key when it was not given: an absent `sources` is what means
+        // "both", and the wire stays the minimum the caller asked for.
+        const sources = requestedSources != null ? { sources: [...requestedSources] } : {};
+        if (opts?.multiple == null) {
+            const result = await sendTypedRequest(getTransport(), { type: 'OPEN_IMAGE_PICKER', payload: { ...sources } }, 'IMAGE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+            // 🔴 BEFORE reading `selected`. A refusal carries no `selected`, so
+            // without this a refused request (or `unsupported on this host`) would
+            // resolve `null` and read exactly like the viewer dismissing.
+            throwOnReplyError(result, 'The host refused the image picker request.');
+            // Normalize the "dismissed" case to an explicit null so callers can
+            // `if (!image) return;` without an `undefined` ambiguity.
+            return result.selected ?? null;
+        }
+        // ── Multi pick ────────────────────────────────────────────────────────
+        const requestedMax = opts.multiple.max;
+        if (typeof requestedMax !== 'number' || !Number.isInteger(requestedMax) || requestedMax < 1) {
+            throw new Error('useImagePicker: `multiple.max` must be a whole number of at least 1 ' +
+                `(values above ${IMAGE_PICKER_MULTIPLE_MAX} are clamped to ${IMAGE_PICKER_MULTIPLE_MAX}).`);
+        }
+        const max = Math.min(requestedMax, IMAGE_PICKER_MULTIPLE_MAX);
+        const result = await sendTypedRequest(getTransport(), { type: 'OPEN_IMAGE_PICKER', payload: { ...sources, multiple: { max } } }, 'IMAGE_PICKER_RESULT', { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        throwOnReplyError(result, 'The host refused the multi-pick image picker request.');
+        // A multi request is always answered with `selectedImages` (`[]` when
+        // nothing was picked). A reply without the list is malformed, so it is
+        // refused rather than read as "nothing picked".
+        const picked = result.selectedImages;
+        if (!Array.isArray(picked))
+            throw new Error(IMAGE_PICKER_NO_LIST_ERROR);
+        // Belt: never hand back more than was asked for.
+        return picked.slice(0, max);
+    }, []);
+    return { open };
+}
+//# sourceMappingURL=useImagePicker.js.map

package/dist/index.d.ts

@@ -86,6 +86,8 @@ export { useImageUpload } from './hooks/useImageUpload.js';
 export type { UseImageUpload, UseImageUploadAsyncScan, UseImageUploadGenerationSource, UseImageUploadOptions, } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
 export type { UploadImageBytesOptions, UseUploadImageBytes, } from './hooks/useUploadImageBytes.js';
+export { useImagePicker, IMAGE_PICKER_MULTIPLE_MAX } from './hooks/useImagePicker.js';
+export type { UseImagePicker, ImagePickerOpenOptions, ImagePickerMultiple, } from './hooks/useImagePicker.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export type { UseGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';

package/dist/index.js

@@ -68,6 +68,7 @@ export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker, RESOURCE_PICKER_MULTIPLE_MAX } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
 export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
+export { useImagePicker, IMAGE_PICKER_MULTIPLE_MAX } from './hooks/useImagePicker.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';
 export { useCivitaiNavigate } from './hooks/useCivitaiNavigate.js';

package/dist/internal/liveHost.d.ts

@@ -47,7 +47,7 @@
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
  * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 49, of which 11 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 50, of which 12 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -127,6 +127,9 @@
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte
  *     pipeline. Replies DISMISSED (the hook resolves `null`).
+ *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted
+ *     images and generator outputs, read off their signed-in session; no
+ *     block-token endpoint lists either. Replies with a refusal.
  *   • SAVE_IMAGE — the download bridge is the production host's unsandboxed top
  *     frame plus its CDN origin allowlist / gated per-viewer read. Replies with
  *     a refusal (#386).
@@ -140,6 +143,11 @@
 import { type BlockContext, type ColorDomain, type Theme, type ViewerInfo } from '@civitai/app-sdk/blocks';
 import type { MockHost } from './mockHost.js';
 import { type PickerOverlayHandle } from './pickerOverlay.js';
+/**
+ * The `error` the live host answers `OPEN_IMAGE_PICKER` with. `useImagePicker()`
+ * rejects with it, so it says what to do instead.
+ */
+export declare const IMAGE_PICKER_UNSUPPORTED_ERROR = "the image picker is not supported in dev:live \u2014 use dev:mock";
 /**
  * Options for {@link createLiveHost}. Mirrors the {@link MockHost}-relevant
  * subset of `MockHostOptions`, plus the live-only `blockToken` / `backendBaseUrl`

package/dist/internal/liveHost.js

@@ -47,7 +47,7 @@
  * fetch chokepoints ..... 2
  * REST endpoints ........ GET /api/v1/blocks/me
  * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
- * switch case labels .... 49, of which 11 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 50, of which 12 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -127,6 +127,9 @@
  *     zip/yaml parse that lives in civitai, not this SDK. Replies `parse-failed`.
  *   • OPEN_IMAGE_UPLOAD — needs the host's native modal + session-authed byte
  *     pipeline. Replies DISMISSED (the hook resolves `null`).
+ *   • OPEN_IMAGE_PICKER — needs the host's picker over the viewer's own posted
+ *     images and generator outputs, read off their signed-in session; no
+ *     block-token endpoint lists either. Replies with a refusal.
  *   • SAVE_IMAGE — the download bridge is the production host's unsandboxed top
  *     frame plus its CDN origin allowlist / gated per-viewer read. Replies with
  *     a refusal (#386).
@@ -144,6 +147,11 @@ import { isRoutableRequestId } from '../transport/requestId.js';
 import { parseSharedStorageRateLimit } from '../transport/validate.js';
 import { createTrackEventChecker } from './trackEventCheck.js';
 import { openPickerOverlay, } from './pickerOverlay.js';
+/**
+ * The `error` the live host answers `OPEN_IMAGE_PICKER` with. `useImagePicker()`
+ * rejects with it, so it says what to do instead.
+ */
+export const IMAGE_PICKER_UNSUPPORTED_ERROR = 'the image picker is not supported in dev:live — use dev:mock';
 /** Default civitai backend the live host forwards to. */
 const DEFAULT_BACKEND_BASE_URL = 'https://civitai.com';
 /** The budgeted-spend scope the workflow procedures require. */
@@ -1343,6 +1351,26 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'OPEN_IMAGE_PICKER': {
+                        // REFUSED. The picker lists the viewer's own posted images and
+                        // generator outputs in host chrome, off the viewer's signed-in
+                        // session. A dev block token has no endpoint that lists either, and
+                        // this harness has no session, so there is nothing real to pick
+                        // from. Rather than let `useImagePicker()` hang to its 10-minute
+                        // timeout, or hand back an invented image, answer with an error
+                        // (the hook rejects) and log what to use instead.
+                        logOnce('open-image-picker', 'OPEN_IMAGE_PICKER received but live dev mode cannot list the viewer\'s own images ' +
+                            '— useImagePicker().open() REJECTS. Test the image picker against the real site, ' +
+                            'or use createMockHost({ cannedImagePicks }) in dev:mock.');
+                        // A refusal nobody can route is not worth sending.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        dispatchToBlock({
+                            type: 'IMAGE_PICKER_RESULT',
+                            payload: { requestId, error: IMAGE_PICKER_UNSUPPORTED_ERROR },
+                        });
+                        return;
+                    }
                     case 'SET_USER_CHECKPOINT': {
                         // 🔴 A PAGE REFUSES, ALWAYS, WITHOUT A BACKEND CALL — and the default
                         // context is a page. That is the production page host exactly: the

package/dist/internal/mockHost.d.ts

@@ -37,7 +37,7 @@
  * called). Only the postMessage bridge round-trips are exercised. Never import
  * this from production code.
  */
-import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockModel3dOutput, type BlockPublishedModel, type BlockRunConfirmedStepHostError, type BlockGatedImage, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockPrepareTrainingDatasetHostError, type BlockRunTrainingHostError, type BlockTrainingRejectionReason, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
+import { type BlockContext, type BlockResourceInfo, type BlockResourcePickerType, type BlockUploadedImageInfo, type BlockGenerationSourceImageInfo, type BuzzAccountType, type BlockBuzzTransaction, type BlockBuzzAccount, type BlockDailyCompensationResource, type BlockViewer, type BlockWildcardPack, type BlockWildcardPackErrorCode, type AppWorkflow, type BlockModel3dOutput, type BlockPublishedModel, type BlockRunConfirmedStepHostError, type BlockGatedImage, type BlockPickedImageInfo, type BlockCollectionFollowErrorCode, type BlockCreatePostHostError, type BlockCreatePostResult, type BlockPrepareTrainingDatasetHostError, type BlockRunTrainingHostError, type BlockTrainingRejectionReason, type ColorDomain, type SharedStorageValue, type Theme, type ViewerInfo, type WorkflowBody } from '@civitai/app-sdk/blocks';
 import { type MockWorkflowQuoteFailure } from './mockWorkflowGraph.js';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
@@ -716,6 +716,33 @@ export interface MockHostOptions {
      * or a `max` that is not a whole number ≥ 1, is answered with an `error`.
      */
     cannedMultiPicks?: CannedPick[] | null;
+    /**
+     * The viewer's pickable images, as `OPEN_IMAGE_PICKER` answers from them
+     * (what `useImagePicker().open()` resolves with). The mock has no picker UI:
+     * it answers at once, as if the viewer picked from the top of this list.
+     *
+     * The list is first FILTERED to the request's `sources` (all of it when the
+     * request names none). A single pick then answers with the first image left,
+     * and a multi pick (`multiple: { max }`) with the first `max` of them (`max`
+     * itself clamped to 20). When nothing is left the reply is a dismiss. `null`
+     * or `[]` simulates a viewer who dismisses every time.
+     *
+     * As on the real host, an entry repeating an earlier one (same `source` and
+     * `url`) is offered once, and an `imageId` on a `'generated'` entry is
+     * dropped. Nothing else is checked: the mock does not model browsing levels
+     * or ratings, so it hands back whatever `nsfwLevel` an entry carries.
+     *
+     * Defaults to one posted image (with an `imageId`) and one generated image
+     * (without one), so both libraries answer out of the box.
+     *
+     * The mock applies the real host's refusals too: a `sources` that is not a
+     * non-empty array of `'posted'` / `'generated'`, or a `multiple` that is
+     * not `{ max }` with a whole number ≥ 1, is answered with an `error`, and so
+     * is any request on a
+     * model-slot `context` (`unsupported on this host`: the picker is a page-app
+     * affordance). Live-tunable via {@link MockHost.setScenario}.
+     */
+    cannedImagePicks?: BlockPickedImageInfo[] | null;
     /**
      * The canned moderated image returned from `OPEN_IMAGE_UPLOAD` when the block
      * requests `purpose:'display'` (the default) — what `useImageUpload().open()`
@@ -1341,7 +1368,7 @@ export interface MockHostOptions {
  * {@link MockHost.setTheme}, which pushes a real `THEME_CHANGE` — the mock of
  * the viewer toggling dark mode with the block already mounted.)
  */
-export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedMultiPicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'runConfirmedStepError' | 'runConfirmedStepCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes' | 'saveImageError' | 'uploadImageBytesResult' | 'uploadImageBytesError'>;
+export type MockHostScenarioPatch = Pick<MockHostOptions, 'consentGrantable' | 'failMode' | 'cost' | 'pollsUntilDone' | 'cannedPicks' | 'cannedMultiPicks' | 'cannedImagePicks' | 'cannedImageUpload' | 'cannedGenerationSourceUpload' | 'cannedImageScan' | 'generation' | 'buzz' | 'storage' | 'shared' | 'buzzBalanceError' | 'viewerResult' | 'viewerError' | 'buzzTransactions' | 'buzzAccounts' | 'dailyCompensation' | 'buzzReadError' | 'wildcardPack' | 'wildcardPackError' | 'collectionFollowError' | 'createPostResult' | 'createPostError' | 'trainingDatasetRejected' | 'trainingDatasetError' | 'trainingQuoteTotal' | 'runTrainingError' | 'runTrainingCapRefusal' | 'runConfirmedStepError' | 'runConfirmedStepCapRefusal' | 'appWorkflows' | 'appWorkflowsError' | 'publishImageIds' | 'publishError' | 'gatedImages' | 'gatedImagesError' | 'disallowedAccountTypes' | 'saveImageError' | 'uploadImageBytesResult' | 'uploadImageBytesError'>;
 /** Runtime Buzz-balance handle exposed on {@link MockHost.buzz}. */
 export interface MockBuzzHandle {
     /** Current simulated balance, or `undefined` when balance isn't simulated. */

package/dist/internal/mockHost.js

@@ -415,6 +415,53 @@ const DEFAULT_SECOND_LORA_PICK = {
 };
 /** The multi-select cap — the real host's, and `additionalResources`'. */
 const MOCK_RESOURCE_PICKER_MULTI_MAX = 5;
+/** The multi-pick cap of `OPEN_IMAGE_PICKER`, the real host's. */
+const MOCK_IMAGE_PICKER_MULTI_MAX = 20;
+/** The libraries `OPEN_IMAGE_PICKER` knows. */
+const MOCK_IMAGE_PICKER_SOURCES = ['posted', 'generated'];
+/** The host's refusal for a bad `sources`, and for a bad `multiple`. */
+const MOCK_IMAGE_PICKER_SOURCES_ERROR = 'OPEN_IMAGE_PICKER: sources must be a non-empty list of "posted" and/or "generated".';
+const MOCK_IMAGE_PICKER_MULTIPLE_ERROR = 'OPEN_IMAGE_PICKER: multiple.max must be a whole number of at least 1.';
+/**
+ * A canned pick as the host puts it on the wire: the contract's fields only,
+ * and `imageId` only on a posted pick (a generator output has no image id, so
+ * one set on a canned `'generated'` entry is dropped).
+ */
+function toWireImagePick(image) {
+    const { source, url, width, height, nsfwLevel, imageId } = image;
+    return {
+        source,
+        url,
+        width,
+        height,
+        nsfwLevel,
+        ...(source === 'posted' && typeof imageId === 'number' ? { imageId } : {}),
+    };
+}
+/**
+ * The images the mock host answers `OPEN_IMAGE_PICKER` from when
+ * {@link MockHostOptions.cannedImagePicks} is omitted: one per library, and
+ * every field differs between them so a block that mixes two picks up shows
+ * it. The generated one has NO `imageId`, as on the real host, and the posted
+ * one's `url` is a resized rendition, not the original file.
+ */
+const DEFAULT_IMAGE_PICKS = [
+    {
+        source: 'posted',
+        url: 'https://image.civitai.com/mock/width=832/dev-posted-image.jpeg',
+        width: 832,
+        height: 1216,
+        nsfwLevel: 1,
+        imageId: 12345801,
+    },
+    {
+        source: 'generated',
+        url: 'https://image.civitai.com/mock/original=true/dev-generated-image.jpeg',
+        width: 1024,
+        height: 768,
+        nsfwLevel: 2,
+    },
+];
 /**
  * The canned image the mock host "returns" from `OPEN_IMAGE_UPLOAD`. Mirrors the
  * host's moderated {@link BlockUploadedImageInfo} projection (imageId/nsfwLevel/
@@ -1010,6 +1057,8 @@ export function createMockHost(options = {}) {
     // Canned MULTI-select picks. `undefined` = derive from the single LoRA pick
     // (see the option's docs); `null` = dismissed.
     let cannedMultiPicks = options.cannedMultiPicks;
+    // The viewer's pickable images for OPEN_IMAGE_PICKER. `null` = dismisses.
+    let cannedImagePicks = options.cannedImagePicks === undefined ? DEFAULT_IMAGE_PICKS : options.cannedImagePicks;
     // Canned image-upload result. `null` = dismissed; undefined = default image.
     let cannedImageUpload = options.cannedImageUpload === undefined ? DEFAULT_IMAGE_UPLOAD : options.cannedImageUpload;
     // Canned generationSource-upload result (purpose:'generationSource').
@@ -2876,6 +2925,75 @@ export function createMockHost(options = {}) {
                         });
                         return;
                     }
+                    case 'OPEN_IMAGE_PICKER': {
+                        // The viewer picking from their own images. No picker UI here: the
+                        // mock answers at once from `cannedImagePicks`, with the real
+                        // host's rules in the real host's order. A request nobody can
+                        // route is dropped, as the host drops it.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        const refuse = (error) => dispatchToBlock({ type: 'IMAGE_PICKER_RESULT', payload: { requestId, error } });
+                        // A page-app affordance: every other surface answers the generic
+                        // refusal.
+                        if (!emulatesPageHost(options.context)) {
+                            refuse('unsupported on this host');
+                            return;
+                        }
+                        const pickerPayload = (typed.payload ?? {});
+                        // `sources`: omitted = both. Otherwise a non-empty array of known
+                        // members; repeats are harmless.
+                        let wanted = MOCK_IMAGE_PICKER_SOURCES;
+                        if (pickerPayload.sources !== undefined) {
+                            const requested = pickerPayload.sources;
+                            if (!Array.isArray(requested) ||
+                                requested.length === 0 ||
+                                !requested.every((s) => MOCK_IMAGE_PICKER_SOURCES.includes(s))) {
+                                refuse(MOCK_IMAGE_PICKER_SOURCES_ERROR);
+                                return;
+                            }
+                            wanted = requested;
+                        }
+                        // `multiple`: ANY present value asks for a multi pick, so `null` and
+                        // a non-object are refused, as the host refuses them. Checked
+                        // before the library is read, in the host's order.
+                        const multiple = pickerPayload.multiple;
+                        let max = null;
+                        if (multiple !== undefined) {
+                            const requestedMax = multiple && typeof multiple === 'object'
+                                ? multiple.max
+                                : undefined;
+                            if (typeof requestedMax !== 'number' ||
+                                !Number.isInteger(requestedMax) ||
+                                requestedMax < 1) {
+                                refuse(MOCK_IMAGE_PICKER_MULTIPLE_ERROR);
+                                return;
+                            }
+                            max = Math.min(requestedMax, MOCK_IMAGE_PICKER_MULTI_MAX);
+                        }
+                        // The library, narrowed to the requested sources, with a repeated
+                        // image (same source and url) collapsed onto its first occurrence.
+                        const available = [];
+                        for (const image of cannedImagePicks ?? []) {
+                            if (!wanted.includes(image.source))
+                                continue;
+                            if (available.some((kept) => kept.source === image.source && kept.url === image.url))
+                                continue;
+                            available.push(image);
+                        }
+                        if (max !== null) {
+                            dispatchToBlock({
+                                type: 'IMAGE_PICKER_RESULT',
+                                payload: { requestId, selectedImages: available.slice(0, max).map(toWireImagePick) },
+                            });
+                            return;
+                        }
+                        const first = available[0];
+                        dispatchToBlock({
+                            type: 'IMAGE_PICKER_RESULT',
+                            payload: { requestId, ...(first ? { selected: toWireImagePick(first) } : {}) },
+                        });
+                        return;
+                    }
                     case 'OPEN_IMAGE_UPLOAD': {
                         // Host-chrome image upload: return the canned result keyed by the
                         // requested `purpose` (mirrors the real host's IMAGE_UPLOAD_RESULT).
@@ -3598,6 +3716,11 @@ export function createMockHost(options = {}) {
         // `null` is a meaningful value (dismissed), so check for the KEY's presence.
         if ('cannedMultiPicks' in patch)
             cannedMultiPicks = patch.cannedMultiPicks;
+        // `null` is a meaningful value (dismisses), and `undefined` restores the
+        // defaults, so check for the KEY's presence.
+        if ('cannedImagePicks' in patch)
+            cannedImagePicks =
+                patch.cannedImagePicks === undefined ? DEFAULT_IMAGE_PICKS : patch.cannedImagePicks;
         // `null` is a meaningful value (dismissed), so check for the KEY's presence.
         if ('cannedImageUpload' in patch)
             cannedImageUpload = patch.cannedImageUpload ?? null;

package/dist/transport/requestTimeouts.js

@@ -68,6 +68,7 @@ const REQUEST_TIMEOUT_CLASS = {
     // ── Gated on a human ────────────────────────────────────────────────────
     OPEN_BUZZ_PURCHASE: 'human', //          viewer walks a purchase flow
     OPEN_CHECKPOINT_PICKER: 'human', //      viewer browses + picks
+    OPEN_IMAGE_PICKER: 'human', //           viewer browses their images + picks
     OPEN_IMAGE_UPLOAD: 'human', //           viewer chooses a file
     OPEN_RESOURCE_PICKER: 'human', //        viewer browses + picks
     PUBLISH_GENERATION_OUTPUTS: 'human', //  viewer answers a consent confirm (#4158)

package/dist/transport/validate.d.ts

@@ -564,6 +564,23 @@ export declare function isValidCheckpointPickerResult(p: unknown): boolean;
  * a reply carrying only `{ requestId, error }` must reach it.
  */
 export declare function isValidResourcePickerResult(p: unknown): boolean;
+/**
+ * Reply to `OPEN_IMAGE_PICKER`.
+ *
+ * Single pick: `selected` is ABSENT on dismiss (the hook resolves `null`); when
+ * present it is a `BlockPickedImageInfo`.
+ *
+ * Multi pick: `selectedImages` is an array of the same shape (`[]` on dismiss).
+ * ONE malformed entry drops the whole reply: handing the caller the
+ * well-formed remainder would silently change which images it goes on to use.
+ *
+ * `error` (a refusal) must be a string when present, and a reply carrying one
+ * is accepted without looking further: `useImagePicker` throws on a PRESENT
+ * `error` before it reads `selected` / `selectedImages`. 🔴 Accepting it is
+ * load-bearing: dropping `{ requestId, error }` would leave the hook waiting
+ * out its whole human-interaction timeout on a refusal the host already sent.
+ */
+export declare function isValidImagePickerResult(p: unknown): boolean;
 /**
  * Reply to `SET_USER_CHECKPOINT`. `ok` is required on the success path; the
  * hook throws on `!ok || error !== undefined` — presence, not truthiness, so an

package/dist/transport/validate.js

@@ -1978,6 +1978,69 @@ export function isValidResourcePickerResult(p) {
     }
     return true;
 }
+const IMAGE_PICKER_SOURCES = new Set(['posted', 'generated']);
+/**
+ * One `BlockPickedImageInfo`: `source` one of the two libraries, a non-empty
+ * `url`, finite positive `width`/`height`, a finite `nsfwLevel`, and an
+ * `imageId` that is either ABSENT (a generated output has none) or a positive
+ * integer. Shared by the single-pick `selected` and every entry of the
+ * multi-pick `selectedImages`, so the two cannot drift on what a well-formed
+ * image is.
+ */
+function isValidPickedImage(s) {
+    if (!isObject(s))
+        return false;
+    if (typeof s.source !== 'string' || !IMAGE_PICKER_SOURCES.has(s.source))
+        return false;
+    if (!isNonEmptyString(s.url))
+        return false;
+    if (!isFiniteNumber(s.width) || s.width <= 0)
+        return false;
+    if (!isFiniteNumber(s.height) || s.height <= 0)
+        return false;
+    if (!isFiniteNumber(s.nsfwLevel))
+        return false;
+    if (s.imageId !== undefined) {
+        if (typeof s.imageId !== 'number' || !Number.isInteger(s.imageId) || s.imageId <= 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Reply to `OPEN_IMAGE_PICKER`.
+ *
+ * Single pick: `selected` is ABSENT on dismiss (the hook resolves `null`); when
+ * present it is a `BlockPickedImageInfo`.
+ *
+ * Multi pick: `selectedImages` is an array of the same shape (`[]` on dismiss).
+ * ONE malformed entry drops the whole reply: handing the caller the
+ * well-formed remainder would silently change which images it goes on to use.
+ *
+ * `error` (a refusal) must be a string when present, and a reply carrying one
+ * is accepted without looking further: `useImagePicker` throws on a PRESENT
+ * `error` before it reads `selected` / `selectedImages`. 🔴 Accepting it is
+ * load-bearing: dropping `{ requestId, error }` would leave the hook waiting
+ * out its whole human-interaction timeout on a refusal the host already sent.
+ */
+export function isValidImagePickerResult(p) {
+    if (!isObject(p))
+        return false;
+    if (!isWireRequestIdShape(p.requestId))
+        return false;
+    if (p.error !== undefined && typeof p.error !== 'string')
+        return false;
+    if (p.error !== undefined)
+        return true; // hook throws before reading a pick
+    if (p.selected !== undefined && !isValidPickedImage(p.selected))
+        return false;
+    if (p.selectedImages !== undefined) {
+        if (!Array.isArray(p.selectedImages))
+            return false;
+        if (!p.selectedImages.every(isValidPickedImage))
+            return false;
+    }
+    return true;
+}
 /**
  * Reply to `SET_USER_CHECKPOINT`. `ok` is required on the success path; the
  * hook throws on `!ok || error !== undefined` — presence, not truthiness, so an
@@ -2158,6 +2221,8 @@ export function payloadValidatorFor(type) {
             return isValidCheckpointPickerResult;
         case 'RESOURCE_PICKER_RESULT':
             return isValidResourcePickerResult;
+        case 'IMAGE_PICKER_RESULT':
+            return isValidImagePickerResult;
         case 'USER_CHECKPOINT_SET':
             return isValidUserCheckpointSetResult;
         case 'SUSPEND':

package/dist/version.generated.d.ts

@@ -1,3 +1,3 @@
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export declare const VERSION = "0.72.3";
+export declare const VERSION = "0.73.0";
 //# sourceMappingURL=version.generated.d.ts.map

package/dist/version.generated.js

@@ -1,4 +1,4 @@
 /* AUTOGENERATED from package.json by scripts/gen-version.mjs. DO NOT EDIT. */
 /** This package's version, reported to the host as `sdkVersion` in `BLOCK_READY`. */
-export const VERSION = "0.72.3";
+export const VERSION = "0.73.0";
 //# sourceMappingURL=version.generated.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/blocks-react",
-  "version": "0.72.3",
+  "version": "0.73.0",
   "description": "React hooks and iframe transport for Civitai Apps. Pairs with @civitai/app-sdk/blocks.",
   "license": "MIT",
   "type": "module",
@@ -37,8 +37,8 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@civitai/components": "^0.9.3",
-    "@civitai/theme": "^0.5.2"
+    "@civitai/theme": "^0.5.2",
+    "@civitai/components": "^0.9.3"
   },
   "comment-peerDependencies": "This floor is DERIVED, not chosen — the lowest published app-sdk that exports every symbol this package imports. Do not edit it without reading ./PEER_FLOOR.md (in-repo, unpublished) and tests/guards/blocks-react-peer-floor.test.mjs.",
   "peerDependencies": {
@@ -58,7 +58,7 @@
     "typescript": "^5.9.2",
     "vite": "^8.0.14",
     "vitest": "^4.1.11",
-    "@civitai/app-sdk": "^0.69.0"
+    "@civitai/app-sdk": "^0.70.0"
   },
   "publishConfig": {
     "access": "public"