@civitai/blocks-react 0.56.0 → 0.57.0

package/dist/internal/liveHost.js

@@ -24,12 +24,31 @@
  *     viewer, decodes the token JWT payload for the block identity / scopes /
  *     budget / maturity, and dispatches `BLOCK_INIT`.
  *
- * REAL NETWORK, REAL MONEY: unlike the mock host, this calls `fetch`. The only
- * network it does is (a) `GET /api/v1/blocks/me` and (b) the four
- * `blocks.{estimate,submit,poll,cancel}Workflow` tRPC mutations — each with the
- * Bearer dev token. A successful submit SPENDS the dev's OWN real Buzz against
- * real compute. The token's per-call budget + the per-user daily cap are the
- * server-side bounds (scope doc §4).
+ * REAL NETWORK, REAL MONEY: unlike the mock host, this calls `fetch`. Every
+ * call is Bearer-authed with the dev token and leaves this file through one of
+ * exactly two chokepoints — {@link rawTrpcCall} (every tRPC procedure) and the
+ * `/api/v1/blocks/me` viewer read in `resolveViewer`. A successful submit
+ * SPENDS the dev's OWN real Buzz against real compute. The token's per-call
+ * budget + the per-user daily cap are the server-side bounds (scope doc §4).
+ * (The picker overlay does its own catalog fetch — that lives in
+ * `pickerOverlay.ts`, not here; see PICKERS below.)
+ *
+ * 🔴 THE BLOCK BELOW IS DERIVED FROM THIS FILE. DO NOT HAND-EDIT IT — and do
+ * not re-introduce a typed "the only X is …" list anywhere in this header.
+ * This file grew from 5 network calls to 30 and from 1 refusal to 7 while the
+ * header still said "the only network it does is … the four `blocks.*Workflow`
+ * mutations" and "the ONE capability live mode cannot SERVE" (#387, #14). An
+ * exhaustive count typed into a 2,100-line file that grows every release is a
+ * claim nobody re-measures. So it is measured:
+ * `tests/guards/livehost-header-enumerations.test.mjs` regenerates the block
+ * from the code and fails with the exact replacement text when it drifts.
+ *
+ * --- BEGIN DERIVED ---
+ * fetch chokepoints ..... 2
+ * REST endpoints ........ GET /api/v1/blocks/me
+ * tRPC procedures ....... 29 = blocks.* (14) + apps.shared.* (10) + apps.storage.* (5)
+ * switch case labels .... 45, of which 7 REFUSE (enumerated under SCOPE below)
+ * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
  * SERVES the resource pickers locally. On `OPEN_CHECKPOINT_PICKER` /
@@ -57,14 +76,48 @@
  * honest error "block token lacks modelId context"; that real outcome is
  * surfaced to the block. With a model-slot token it persists for real.
  *
- * SCOPE — the ONE capability live mode still cannot SERVE is OPEN_BUZZ_PURCHASE:
- * there is NO headless / block-token Buzz-purchase path (buying Buzz strictly
- * requires the interactive Stripe/Paddle host chrome). So it deep-links the real
- * purchase page and replies `purchased: false` — honest-by-design, never a
- * fabricated success. See the per-message handlers below.
+ * SHARED STORAGE (#386): the live host SERVES all TEN `SHARED_*` bridges —
+ * `apps.shared.{list,get,getCount,getCounts,append,update,vote,unvote,withdraw,
+ * report}` — on the same block-token convention as APP_STORAGE. `SHARED_GET`
+ * and `SHARED_REPORT` were the last two missing; until #386 they fell through
+ * 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.
+ *
+ * 🔴 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:
+ * `tests/guards/livehost-message-coverage.test.mjs` asserts that no block→parent
+ * type is left without a case at all (the failure mode a refusal is NOT), and
+ * `tests/guards/livehost-header-enumerations.test.mjs` derives the refusal set
+ * from the handlers below and asserts these bullets are exactly it — so the
+ * list cannot silently go stale again the way it did through #14/#387. Add a
+ * refusal handler without a bullet, or leave a bullet whose handler now serves,
+ * and that guard fails naming the difference.
+ *
+ *   • OPEN_BUZZ_PURCHASE — no headless / block-token Buzz-purchase path (buying
+ *     Buzz strictly requires the interactive Stripe/Paddle host chrome). Deep-
+ *     links the real purchase page and replies `purchased: false`.
+ *   • SET_COLLECTION_FOLLOW — needs the session-authed follow procedures plus
+ *     host-chrome consent. Replies `collection-unavailable`.
+ *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
+ *     confirm before a PUBLIC post is written. Replies with a refusal.
+ *   • GET_WILDCARD_PACK — needs the session-authed resolve plus the in-tab
+ *     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`).
+ *   • 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).
+ *   • REQUEST_CONSENT — live mode cannot grant a scope the token does not carry.
+ *     Pushes `CONSENT_UNAVAILABLE` when the ask is genuinely ungrantable.
+ *
+ * In every case REFUSING IS THE POINT: serving a weakened local imitation would
+ * let a block prove out a flow production does not have, and ship having never
+ * handled the refusal. Use dev:mock for those paths. See the handlers below.
  */
 import { consentUnavailablePayload, resolveUngrantableConsentNotice } from './consent.js';
-import { hostContextWithTheme } from './transport.js';
+import { hostContextWithTheme } from '../transport/transport.js';
+import { isRoutableRequestId } from '../transport/requestId.js';
 import { openPickerOverlay, } from './pickerOverlay.js';
 /** Default civitai backend the live host forwards to. */
 const DEFAULT_BACKEND_BASE_URL = 'https://civitai.com';
@@ -165,6 +218,35 @@ function isTransientHttpStatus(status) {
  * block's own poll loop tries again.
  */
 const POLL_RETRY_BACKOFF_MS = [250, 500, 1000];
+/**
+ * Map ONE raw `apps.shared.*` row → the `SharedStorageItemWire` shape the
+ * protocol puts on `SHARED_LIST_RESULT.items` and `SHARED_GET_RESULT.item`.
+ *
+ * ONE mapper, not one per case: the two reads return the same row and the
+ * fields are lenient-by-default (a missing `authorUserId`/`count` becomes `0`,
+ * dates are ISO-normalized whether the transport handed back a `Date` or a
+ * string). A second open-coded copy is how the two reads drift.
+ *
+ * `viewerVoted` is forwarded ONLY when the server actually sent a boolean —
+ * the field is OPTIONAL and additive, and the block-side hook defaults a
+ * missing value to `false`. Omitting it when the server omits it keeps a host
+ * that predates the field indistinguishable from today's behaviour; forwarding
+ * it when the server sends it is what lets a `?g=<key>` deep-link hydrate its
+ * vote button instead of guessing.
+ */
+function sharedItemWireFrom(raw) {
+    const e = raw;
+    const iso = (d) => (d instanceof Date ? d.toISOString() : String(d));
+    return {
+        key: String(e.key),
+        authorUserId: typeof e.authorUserId === 'number' ? e.authorUserId : 0,
+        value: e.value,
+        count: typeof e.count === 'number' ? e.count : 0,
+        createdAt: iso(e.createdAt),
+        updatedAt: iso(e.updatedAt),
+        ...(typeof e.viewerVoted === 'boolean' ? { viewerVoted: e.viewerVoted } : {}),
+    };
+}
 /**
  * Create a LIVE host that forwards the App-Block postMessage protocol to the
  * real Civitai backend. Returns the same {@link MockHost} interface as
@@ -472,6 +554,14 @@ export function createLiveHost(options) {
         const openPicker = (params, resultType, requestId) => {
             const handle = openPickerOverlay({
                 type: params.type,
+                // 🔴 THE REPLY CHANNEL TRAVELS WITH THE REQUEST (#391). It used to stop
+                // here: the overlay only received `params.type` and branched its
+                // converter on THAT, so an `OPEN_RESOURCE_PICKER` asking for a
+                // Checkpoint replied on `RESOURCE_PICKER_RESULT` with the CHECKPOINT
+                // projection — no `modelType`, which `BlockResourceInfo` requires.
+                // Two independent facts (what was asked for, what channel replies) were
+                // conflated into one; passing the channel down is what separates them.
+                resultChannel: resultType,
                 baseUrl,
                 token: rawToken,
                 fetchImpl,
@@ -522,7 +612,7 @@ export function createLiveHost(options) {
                         dispatchToBlock({
                             type: 'TOKEN_REFRESH_RESPONSE',
                             payload: {
-                                ...(requestId ? { requestId } : {}),
+                                ...(isRoutableRequestId(requestId) ? { requestId } : {}),
                                 token: wrappedTokenFrom(rawToken ?? '', decoded),
                             },
                         });
@@ -655,7 +745,7 @@ export function createLiveHost(options) {
                         // Mirrors the `APP_STORAGE_SET` value-or-error convention. Drop a
                         // request with no `requestId` — the block correlates the reply by it,
                         // so a reply without one is unroutable.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getMyBuzzBalance', { blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -676,7 +766,7 @@ export function createLiveHost(options) {
                         // TEXT error on failure (anon / banned viewer). Drop a request with
                         // no `requestId` — the block correlates the reply by it, so a reply
                         // without one is unroutable.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getMyViewer', { blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -693,7 +783,7 @@ export function createLiveHost(options) {
                         // MUTATION (POST). params are spread FIRST so the host-authoritative
                         // `blockToken` (spread LAST) can never be overridden — mirrors the
                         // real host. FREE-TEXT error on failure. Unroutable without requestId.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getMyBuzzTransactions', { ...(typed.payload?.params ?? {}), blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -706,7 +796,7 @@ export function createLiveHost(options) {
                         return;
                     }
                     case 'GET_BUZZ_ACCOUNTS': {
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getMyBuzzAccounts', { blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -719,7 +809,7 @@ export function createLiveHost(options) {
                         return;
                     }
                     case 'GET_DAILY_COMPENSATION': {
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getMyDailyCompensation', { ...(typed.payload?.params ?? {}), blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -753,7 +843,7 @@ export function createLiveHost(options) {
                         // loop against a harness that has no sign-in. Use dev:mock (its
                         // `collectionFollowError` knob covers `declined` and the rest) to
                         // exercise the real refusal set.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         logOnce('collection-follow', 'SET_COLLECTION_FOLLOW is not supported in dev:live (it needs the session-authed ' +
                             'follow procedures plus host-chrome consent). Replying `collection-unavailable`. ' +
@@ -786,7 +876,7 @@ export function createLiveHost(options) {
                         // surfaces it as `.code === undefined`, i.e. a message worth showing.
                         // Use dev:mock (its `createPostError` knob covers `declined` and the
                         // rest) to exercise the refusal set.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         logOnce('create-post', 'CREATE_POST_FROM_APP is not supported in dev:live (it needs the server-resolved ' +
                             'preview plus host-chrome consent). Replying with a refusal. Use dev:mock to ' +
@@ -809,7 +899,7 @@ export function createLiveHost(options) {
                         // honest `parse-failed` (never a fabricated pack) so the block's hook
                         // surfaces a typed error rather than hanging. Use dev:mock for the
                         // full wildcard-import path.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         logOnce('wildcard-pack', 'GET_WILDCARD_PACK is not supported in dev:live (it needs the session-authed ' +
                             'resolve + in-tab zip parse). Replying `parse-failed`. Use dev:mock to exercise ' +
@@ -828,7 +918,7 @@ export function createLiveHost(options) {
                         // per-app tag filter server-side (the input carries no `tags`). It
                         // returns a plain `{ workflows, cursor }`, unwrapped with `callTrpcData`.
                         // FREE-TEXT error on failure. Unroutable without requestId.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.queryAppWorkflows', { ...(typed.payload?.params ?? {}), blockToken: rawToken }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -847,7 +937,7 @@ export function createLiveHost(options) {
                         // terminal projection), unwrapped with `callTrpcData`. FREE-TEXT error
                         // on failure (FORBIDDEN / transport). Drop a request with no requestId
                         // or a missing/empty workflowId (mirrors the real host).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         const cancelId = typed.payload?.workflowId;
                         if (typeof cancelId !== 'string' || cancelId.length === 0)
@@ -870,7 +960,7 @@ export function createLiveHost(options) {
                         // re-derives ownership, re-uploads + FULL-scans server-side. Returns a
                         // plain `{ imageIds }`, unwrapped with `callTrpcData`. FREE-TEXT error
                         // on failure. Unroutable without requestId.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.publishGenerationOutputs', {
                             blockToken: rawToken,
@@ -895,7 +985,7 @@ export function createLiveHost(options) {
                         // browsing-level clamp server-side and returns a plain `{ images }`
                         // (`BlockGatedImage[]` — visible/hidden), unwrapped with `callTrpcData`.
                         // FREE-TEXT error on failure. Unroutable without requestId.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         void callTrpcData('blocks.getImagesByIds', { blockToken: rawToken, imageIds: typed.payload?.imageIds ?? [] }, 'POST').then((r) => {
                             dispatchToBlock({
@@ -1173,18 +1263,7 @@ export function createLiveHost(options) {
                                 return;
                             }
                             const rawItems = r.data?.items;
-                            const items = (Array.isArray(rawItems) ? rawItems : []).map((it) => {
-                                const e = it;
-                                const iso = (d) => d instanceof Date ? d.toISOString() : String(d);
-                                return {
-                                    key: String(e.key),
-                                    authorUserId: typeof e.authorUserId === 'number' ? e.authorUserId : 0,
-                                    value: e.value,
-                                    count: typeof e.count === 'number' ? e.count : 0,
-                                    createdAt: iso(e.createdAt),
-                                    updatedAt: iso(e.updatedAt),
-                                };
-                            });
+                            const items = (Array.isArray(rawItems) ? rawItems : []).map(sharedItemWireFrom);
                             const nextCursor = r.data?.nextCursor;
                             dispatchToBlock({
                                 type: 'SHARED_LIST_RESULT',
@@ -1238,6 +1317,56 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'SHARED_GET': {
+                        // SERVED, not refused (#386): this is the single-row companion to
+                        // SHARED_LIST's paged read and forwards to the SAME block-token
+                        // procedure family the other eight `SHARED_*` bridges already use.
+                        // Nothing about it needs host chrome or a session — so refusing it
+                        // would be a limitation this host does not actually have.
+                        //
+                        // Before this case existed the message fell through `default:
+                        // return` with NO reply, so `useSharedStorage().get(key)` sat for
+                        // the full 30s protocol timeout and then threw a generic
+                        // RequestTimeoutError — while the identical call resolved under
+                        // dev:mock.
+                        //
+                        // `item: null` on a miss (never an error): the protocol makes a
+                        // missing / hidden / withdrawn row resolve cleanly to "not found"
+                        // so a `?g=` deep-link to a moderated row cannot distinguish it
+                        // from an absent one. Only a HOST-SIDE failure sets `error`.
+                        const key = typed.payload?.key ?? '';
+                        void callTrpcData('apps.shared.get', { blockToken: rawToken, key }, 'GET').then((r) => {
+                            if (r.error) {
+                                dispatchToBlock({
+                                    type: 'SHARED_GET_RESULT',
+                                    payload: { requestId: requestId ?? '', item: null, error: r.error },
+                                });
+                                return;
+                            }
+                            // ENVELOPE-LENIENT. The sibling reads are not consistent about
+                            // this — `getCount` returns `{ count }` and `list` returns
+                            // `{ items }`, but `withdraw` returns the bare `{ deleted }` —
+                            // and an envelope guess that is wrong would turn every hit into
+                            // a silent `null`, i.e. "the row does not exist" for a row that
+                            // does. So accept `{ item: <row> }` OR the bare row, identified
+                            // by carrying a `key`. Anything else is a genuine miss.
+                            const data = r.data;
+                            const envelope = data?.item;
+                            const rawItem = envelope && typeof envelope === 'object'
+                                ? envelope
+                                : data && typeof data.key === 'string'
+                                    ? data
+                                    : null;
+                            dispatchToBlock({
+                                type: 'SHARED_GET_RESULT',
+                                payload: {
+                                    requestId: requestId ?? '',
+                                    item: rawItem ? sharedItemWireFrom(rawItem) : null,
+                                },
+                            });
+                        });
+                        return;
+                    }
                     case 'SHARED_APPEND': {
                         const value = typed.payload?.value;
                         void callTrpcData('apps.shared.append', { blockToken: rawToken, value }, 'POST').then((r) => {
@@ -1331,6 +1460,80 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'SHARED_REPORT': {
+                        // SERVED, not refused (#386): same block-token procedure family as
+                        // the other `SHARED_*` bridges — the trust gate and the rate limit
+                        // are SERVER-side, so forwarding here exercises the real bounds
+                        // rather than a local imitation of them. Nothing needs host chrome.
+                        //
+                        // Before this case existed the message fell through `default:
+                        // return` with NO reply, so `useSharedStorage().report(key, reason)`
+                        // sat for the full 30s protocol timeout.
+                        //
+                        // `reason` is OPTIONAL free text — forwarded only when the block
+                        // actually sent a string, so an omitted reason stays omitted rather
+                        // than becoming `''` (the server bounds it either way).
+                        const key = typed.payload?.key ?? '';
+                        const reportInput = { blockToken: rawToken, key };
+                        if (typeof typed.payload?.reason === 'string') {
+                            reportInput.reason = typed.payload.reason;
+                        }
+                        void callTrpcData('apps.shared.report', reportInput, 'POST').then((r) => {
+                            dispatchToBlock({
+                                type: 'SHARED_REPORT_RESULT',
+                                payload: r.error
+                                    ? { requestId: requestId ?? '', ok: false, error: r.error }
+                                    : { requestId: requestId ?? '', ok: true },
+                            });
+                        });
+                        return;
+                    }
+                    case 'SAVE_IMAGE': {
+                        // 🔴 REFUSED, and refusing is the POINT — the same reasoning as
+                        // CREATE_POST_FROM_APP above, one step stronger.
+                        //
+                        // The real bridge is a SECURITY boundary, not a convenience: the
+                        // host fetches the blob in its UNSANDBOXED top frame, and the two
+                        // request variants are gated differently.
+                        //   • `url` — the host ALLOWLISTS the origin to the civitai
+                        //     image/blob CDN and REFUSES an arbitrary host, because an
+                        //     unverified block's `url` is untrusted input to a host-side
+                        //     fetch.
+                        //   • `imageId` — the host resolves it through the SAME per-viewer
+                        //     gated read that backs GET_IMAGES_BY_IDS, so a withheld or
+                        //     above-ceiling image can never be coerced into a download.
+                        //
+                        // This harness has NEITHER gate. The allowlist is the production
+                        // host's, not this SDK's — there is no origin set here to check
+                        // against — so a dev-side "download it anyway" would accept URLs
+                        // production refuses and let a block ship having never once handled
+                        // the refusal. Inventing a divergent allowlist is worse than having
+                        // none: it would be a security posture nobody reviewed, only ever
+                        // exercised in dev.
+                        //
+                        // So: an honest, IMMEDIATE refusal on the type's own channel rather
+                        // than the silent 30s hang this case replaces (#386). FREE TEXT,
+                        // not a host code — `SAVE_IMAGE_RESULT.error` is an open string and
+                        // `useSaveImage()` surfaces it verbatim; none of the host's real
+                        // failure strings ("disallowed origin", "hidden") would be true
+                        // here. Use dev:mock to exercise the resolve path, and the real
+                        // site to exercise the gates.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('save-image', 'SAVE_IMAGE is not supported in dev:live (the download bridge is the production ' +
+                            "host's unsandboxed top frame plus its CDN origin allowlist / gated per-viewer " +
+                            'read — neither of which this harness has). Replying with a refusal. Use dev:mock ' +
+                            'to exercise the save path.');
+                        dispatchToBlock({
+                            type: 'SAVE_IMAGE_RESULT',
+                            payload: {
+                                requestId,
+                                ok: false,
+                                error: 'saving images is not supported in dev:live — use dev:mock',
+                            },
+                        });
+                        return;
+                    }
                     case 'NAVIGATE': {
                         const path = typed.payload?.path ?? '';
                         const target = typed.payload?.target ?? 'current';

package/dist/internal/mockHost.js

@@ -39,7 +39,8 @@
  */
 import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED, APP_STORAGE_ERROR_USER_ROW_LIMIT, APP_STORAGE_ERROR_VALUE_TOO_LARGE, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, APP_STORAGE_MAX_VALUE_BYTES, BrowsingLevel, SFW_LEVELS, } from '@civitai/app-sdk/blocks';
 import { consentUnavailablePayload, resolveUngrantableConsentNotice } from './consent.js';
-import { hostContextWithTheme } from './transport.js';
+import { hostContextWithTheme } from '../transport/transport.js';
+import { isRoutableRequestId } from '../transport/requestId.js';
 /**
  * The block's preferred Buzz pool. On a `textToImage` {@link WorkflowBody} it's
  * the top-level `accountType`; on a `customComfy` RECIPE body it lives under
@@ -891,7 +892,7 @@ export function createMockHost(options = {}) {
                     case 'REQUEST_TOKEN':
                         dispatchToBlock({
                             type: 'TOKEN_REFRESH_RESPONSE',
-                            payload: { ...(requestId ? { requestId } : {}), token: nextToken() },
+                            payload: { ...(isRoutableRequestId(requestId) ? { requestId } : {}), token: nextToken() },
                         });
                         return;
                     case 'REQUEST_CONSENT': {
@@ -1215,7 +1216,7 @@ export function createMockHost(options = {}) {
                         // exactly. Drop a request with no requestId — the block correlates
                         // the reply by it, so a reply without one is unroutable (matches
                         // the sibling request cases + createLiveHost).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         // Simulated read failure: reply with the error shape
                         // (`{ requestId, error }`, no `balance`) — byte-for-byte
@@ -1239,7 +1240,7 @@ export function createMockHost(options = {}) {
                         // with no requestId — the block correlates the reply by it, so a
                         // reply without one is unroutable (matches the sibling request cases
                         // + createLiveHost).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         // Simulated read failure: reply with the error shape
                         // (`{ requestId, error }`, no `viewer`) — byte-for-byte
@@ -1261,7 +1262,7 @@ export function createMockHost(options = {}) {
                         // Buzz-dashboard ledger read. Drop a request with no requestId
                         // (unroutable). A forced read error replies with the FREE-TEXT error
                         // variant (mirrors the real host forwarding err.message).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (buzzReadError !== undefined) {
                             dispatchToBlock({
@@ -1285,7 +1286,7 @@ export function createMockHost(options = {}) {
                         return;
                     }
                     case 'GET_BUZZ_ACCOUNTS': {
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (buzzReadError !== undefined) {
                             dispatchToBlock({
@@ -1301,7 +1302,7 @@ export function createMockHost(options = {}) {
                         return;
                     }
                     case 'GET_DAILY_COMPENSATION': {
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (buzzReadError !== undefined) {
                             dispatchToBlock({
@@ -1325,7 +1326,7 @@ export function createMockHost(options = {}) {
                     case 'GET_WILDCARD_PACK': {
                         // Token-INDEPENDENT import. A forced error replies with the
                         // DISCRIMINATED enum code (NOT free-text) — mirrors the real host.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (wildcardPackError !== undefined) {
                             dispatchToBlock({
@@ -1344,7 +1345,7 @@ export function createMockHost(options = {}) {
                         // App generator SUBQUEUE read. Drop a request with no requestId
                         // (unroutable). A forced error replies with the FREE-TEXT error
                         // variant (mirrors the real host forwarding err.message).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (appWorkflowsError !== undefined) {
                             dispatchToBlock({
@@ -1367,7 +1368,7 @@ export function createMockHost(options = {}) {
                         // requestId or a missing/empty workflowId (mirrors the real host
                         // dropping those without a reply). A forced error replies with the
                         // FREE-TEXT error variant (mirrors a FORBIDDEN / transport failure).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         const cancelId = typed.payload?.workflowId;
                         if (typeof cancelId !== 'string' || cancelId.length === 0)
@@ -1400,7 +1401,7 @@ export function createMockHost(options = {}) {
                     case 'SET_COLLECTION_FOLLOW': {
                         // Follow / unfollow a collection for the viewer. Drop a request with
                         // no requestId (unroutable) — same as every REQUEST-style handler.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (collectionFollowError !== undefined) {
                             dispatchToBlock({
@@ -1437,7 +1438,7 @@ export function createMockHost(options = {}) {
                         // outputs. Drop a request with no requestId (unroutable) — same as
                         // every REQUEST-style handler, and the ONLY safe drop: after the id
                         // is known, every path must reply or the block hangs TEN MINUTES.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (createPostError !== undefined) {
                             dispatchToBlock({
@@ -1470,7 +1471,7 @@ export function createMockHost(options = {}) {
                         // real-scanned public Image rows. Drop a request with no requestId
                         // (unroutable). A forced error replies with the FREE-TEXT error variant
                         // (mirrors the real host forwarding err.message).
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (publishError !== undefined) {
                             dispatchToBlock({
@@ -1491,7 +1492,7 @@ export function createMockHost(options = {}) {
                         // (mirrors the real host forwarding err.message). The canned images
                         // include at least one `hidden` (no-url) entry so the block's
                         // blurred/placeholder path is exercised.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         if (gatedImagesError !== undefined) {
                             dispatchToBlock({
@@ -2024,7 +2025,7 @@ export function createMockHost(options = {}) {
                         // explicit null (clear); anything else is a bad-input NACK, same as
                         // the real IframeHost. Without this reply `useCheckpointPicker().
                         // persist()` hung to its 30s timeout under the mock host.
-                        if (typeof requestId !== 'string')
+                        if (!isRoutableRequestId(requestId))
                             return;
                         const rawVersionId = typed.payload?.versionId;
                         const versionId = rawVersionId === null

package/dist/internal/pickerOverlay.d.ts

@@ -28,17 +28,65 @@
  */
 import { type CatalogCard, type CatalogModelType } from './catalog.js';
 import type { BlockCheckpointInfo, BlockResourceInfo } from '@civitai/app-sdk/blocks';
-/** What the overlay resolves with — the production picker's `selected` shape. */
+/**
+ * The inbound message type a picker's result is dispatched on. TWO CHANNELS,
+ * TWO CONTRACTS — `CHECKPOINT_PICKER_RESULT.selected` is a
+ * {@link BlockCheckpointInfo}, `RESOURCE_PICKER_RESULT.selected` is a
+ * {@link BlockResourceInfo} (which additionally REQUIRES `modelType`).
+ */
+export type PickerResultChannel = 'CHECKPOINT_PICKER_RESULT' | 'RESOURCE_PICKER_RESULT';
+/**
+ * What the overlay resolves with — the production picker's `selected` shape,
+ * KEYED TO THE REPLY CHANNEL.
+ *
+ * 🔴 DISCRIMINATED BY `channel`, NOT BY THE REQUESTED MODEL TYPE (#391). Those
+ * are two independent facts and conflating them was the bug: a block asking for
+ * a `Checkpoint`-typed resource on `OPEN_RESOURCE_PICKER` got a
+ * `cardToCheckpoint()` projection — five fields, no `modelType` — dispatched on
+ * `RESOURCE_PICKER_RESULT`, where every consumer reads `resource.modelType` and
+ * found `undefined`. `tsc` could not see it: the branch was a runtime string
+ * comparison on `opts.type` and the two converters return different declared
+ * types, so no call site was ever checked against the channel it replies on.
+ *
+ * Keying the union to the channel is what turns THAT pairing into a COMPILE
+ * error: `{ channel: 'RESOURCE_PICKER_RESULT', selected: cardToCheckpoint(…) }`
+ * now fails `tsc` with "Property 'modelType' is missing in type
+ * 'BlockCheckpointInfo' but required in type 'BlockResourceInfo'". Measured by
+ * reapplying the original branch.
+ *
+ * 🔴 ONE DIRECTION ONLY, and the docblock said otherwise until it was checked.
+ * The MIRROR pairing — a `BlockResourceInfo` on `CHECKPOINT_PICKER_RESULT` — is
+ * structurally assignable (`BlockResourceInfo` has every `BlockCheckpointInfo`
+ * field plus more, and the value is not a fresh object literal, so no
+ * excess-property check applies). Measured: `tsc` reports ZERO errors for it.
+ * That half is pinned by a runtime test in `liveHost.test.tsx` asserting the
+ * checkpoint-channel payload carries exactly its five keys — do not read this
+ * union as covering it.
+ */
 export type PickerSelection = {
-    kind: 'Checkpoint';
+    channel: 'CHECKPOINT_PICKER_RESULT';
     selected: BlockCheckpointInfo;
 } | {
-    kind: 'LORA';
+    channel: 'RESOURCE_PICKER_RESULT';
     selected: BlockResourceInfo;
 };
 export interface OpenPickerOptions {
-    /** Which model type the picker is filtered to. */
+    /**
+     * Which model type the picker is FILTERED to — a catalog query parameter, and
+     * the `modelType` fallback when a card's own REST type is blank.
+     *
+     * 🔴 NOT the thing that decides the reply shape. See {@link resultChannel}.
+     */
     type: CatalogModelType;
+    /**
+     * Which message the host will dispatch this pick on — REQUIRED, because it is
+     * the only fact that determines the `selected` shape the block's consumers
+     * expect (#391). A `Checkpoint`-typed request can arrive on EITHER channel:
+     * `OPEN_CHECKPOINT_PICKER` (→ `BlockCheckpointInfo`) and
+     * `OPEN_RESOURCE_PICKER` with `resourceType: 'Checkpoint'`
+     * (→ `BlockResourceInfo`, `modelType` included).
+     */
+    resultChannel: PickerResultChannel;
     /** Backend origin the catalog resolves against (live host's `baseUrl`). */
     baseUrl: string;
     /** The dev block token — authoritative `/blocks/models` read (page token can read it). */