@civitai/blocks-react 0.74.0 → 0.75.0

package/dist/index.js

@@ -60,6 +60,7 @@ export { RequestTimeoutError } from './transport/transport.js';
 // spent", which is the one distinction the class exists to carry.
 export { InvalidIdempotencyKeyError } from './transport/transport.js';
 export { useCollectionFollow, CollectionFollowError, COLLECTION_FOLLOW_ERROR_CODES, isCollectionFollowErrorCode, } from './hooks/useCollectionFollow.js';
+export { useReactions, ReactionError, REACTIONS, REACTION_ERROR_CODES, isReactionErrorCode, } from './hooks/useReactions.js';
 export { useCreatePostFromApp, CreatePostError, CREATE_POST_ERROR_CODES, isCreatePostErrorCode, } from './hooks/useCreatePostFromApp.js';
 export { usePrepareTrainingDataset, PrepareTrainingDatasetError, PREPARE_TRAINING_DATASET_ERROR_CODES, isPrepareTrainingDatasetErrorCode, } from './hooks/usePrepareTrainingDataset.js';
 export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTrainingErrorCode, } from './hooks/useRunTraining.js';

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 .... 50, of which 12 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 52, of which 14 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -106,6 +106,11 @@
  *     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`.
+ *   • SET_ENTITY_REACTION — the server's reaction procedures take the viewer's
+ *     signed-in SESSION alongside the block token, and refuse any token as
+ *     authentication. Replies `entity-unavailable`.
+ *   • GET_ENTITY_REACTIONS — the same session-authed procedure pair. Replies
+ *     `entity-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
  *   • PREPARE_TRAINING_DATASET — the server refuses every `kind: 'training'`

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 .... 50, of which 12 REFUSE (enumerated under SCOPE below)
+ * switch case labels .... 52, of which 14 REFUSE (enumerated under SCOPE below)
  * --- END DERIVED ---
  *
  * PICKERS (Phase 1 of "make dev:live a faithful local host"): the live host
@@ -106,6 +106,11 @@
  *     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`.
+ *   • SET_ENTITY_REACTION — the server's reaction procedures take the viewer's
+ *     signed-in SESSION alongside the block token, and refuse any token as
+ *     authentication. Replies `entity-unavailable`.
+ *   • GET_ENTITY_REACTIONS — the same session-authed procedure pair. Replies
+ *     `entity-unavailable`.
  *   • CREATE_POST_FROM_APP — needs the server-resolved preview plus host-chrome
  *     confirm before a PUBLIC post is written. Replies with a refusal.
  *   • PREPARE_TRAINING_DATASET — the server refuses every `kind: 'training'`
@@ -147,6 +152,10 @@ import { isRoutableRequestId } from '../transport/requestId.js';
 import { parseSharedStorageRateLimit } from '../transport/validate.js';
 import { createTrackEventChecker } from './trackEventCheck.js';
 import { openPickerOverlay, } from './pickerOverlay.js';
+/** Logged once when a block sends either reaction message to the live host. */
+const REACTIONS_UNSUPPORTED_LOG = 'SET_ENTITY_REACTION / GET_ENTITY_REACTIONS are not supported in dev:live (the reaction ' +
+    'procedures need the signed-in civitai.com session). Replying `entity-unavailable`. Use ' +
+    'dev:mock to exercise the reaction bridge.';
 /**
  * The `error` the live host answers `OPEN_IMAGE_PICKER` with. `useImagePicker()`
  * rejects with it, so it says what to do instead.
@@ -1052,6 +1061,40 @@ export function createLiveHost(options) {
                         });
                         return;
                     }
+                    case 'SET_ENTITY_REACTION': {
+                        // UNSUPPORTED in live: `blocks.setReactionFromApp` /
+                        // `blocks.getReactionsForApp` are session procedures marked
+                        // `blockApiKeys`, so the server refuses ANY token as the caller's
+                        // authentication and then checks that the block token's subject IS
+                        // the session user. A liveHost holds a token and no session.
+                        //
+                        // `entity-unavailable`: the closed code that already means "this
+                        // request cannot be served, nothing was written". `sign-in-required`
+                        // would send the block into a REQUEST_SIGN_IN loop against a harness
+                        // with no sign-in; `needs-consent` into a consent ask that cannot
+                        // help. Use dev:mock (`reactionStates` / `reactionError`, with
+                        // `social:react:self` in `declaredScopes`) to exercise the bridge.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('entity-reaction', REACTIONS_UNSUPPORTED_LOG);
+                        dispatchToBlock({
+                            type: 'ENTITY_REACTION_RESULT',
+                            payload: { requestId, error: 'entity-unavailable' },
+                        });
+                        return;
+                    }
+                    case 'GET_ENTITY_REACTIONS': {
+                        // UNSUPPORTED in live, for the reason on SET_ENTITY_REACTION directly
+                        // above: the read is the same session-authed procedure pair.
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        logOnce('entity-reaction', REACTIONS_UNSUPPORTED_LOG);
+                        dispatchToBlock({
+                            type: 'ENTITY_REACTIONS_RESULT',
+                            payload: { requestId, error: 'entity-unavailable' },
+                        });
+                        return;
+                    }
                     case 'CREATE_POST_FROM_APP': {
                         // UNSUPPORTED in live v1, for a STRONGER version of the
                         // SET_COLLECTION_FOLLOW reason directly above. The real host makes

package/dist/internal/mockHost.d.ts

@@ -37,8 +37,9 @@
  * 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 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 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 BlockEntityReactionErrorCode, 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';
+import { type MockReactionSeed } from './mockHostReactions.js';
 /**
  * How submits behave. `'none'` = everything succeeds; `'all'` / `'insufficient'`
  * = every submit fails as if the viewer were OUT OF BUZZ, until an
@@ -945,6 +946,33 @@ export interface MockHostOptions {
      * handling is only exercised by `declined`, never by the timing.
      */
     collectionFollowError?: BlockCollectionFollowErrorCode | string;
+    /**
+     * The images `GET_ENTITY_REACTIONS` / `SET_ENTITY_REACTION` know, keyed by
+     * image id: counts and the viewer's existing reactions. An id that is not
+     * seeded starts with zero counts and no reactions. Writes persist for the
+     * life of the mock. Live-tunable via {@link MockHost.setScenario} (a new seed
+     * REPLACES the state).
+     *
+     * 🔴 BOTH MESSAGES ARE SCOPE-GATED HERE, as on the real host: unless
+     * {@link MockHostOptions.declaredScopes} includes `social:react:self`, every
+     * call replies `needs-consent`. A `null` {@link MockHostOptions.viewer}
+     * replies `sign-in-required`. Any well-formed ticket is accepted — a real one
+     * is an HMAC this mock cannot verify — but an image WITHOUT one is refused,
+     * as production refuses it. See `./mockHostReactions.ts`.
+     */
+    reactionStates?: Record<number, MockReactionSeed>;
+    /**
+     * Force both reaction messages to reply with this `error` once the request
+     * would otherwise proceed — one of `REACTION_ERROR_CODES` (`rate-limited`,
+     * `entity-unavailable`, `review-mode`, `not-ready`…) or any string for a code
+     * a newer host might add. Absent → the request succeeds. Live-tunable via
+     * {@link MockHost.setScenario}; pass `null` there to clear it.
+     *
+     * `review-mode` and `not-ready` are answered FIRST, ahead of the sign-in,
+     * payload and scope checks, because the real host's gate checks them first;
+     * every other code is answered only once those pass, as a server answer is.
+     */
+    reactionError?: BlockEntityReactionErrorCode | string | null;
     /**
      * The post reported on `CREATE_POST_FROM_APP` (what
      * `useCreatePostFromApp().createPost()` resolves with). Absent →
@@ -1370,7 +1398,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' | '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'>;
+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' | 'reactionStates' | 'reactionError' | '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

@@ -48,6 +48,7 @@ import { mockUnpricedWorkflowRefusal, mockUnquotedWorkflowEstimateRefusal, mockW
 import { BATCH_ESTIMATE_CELL_TIMEOUT_ERROR } from '../hooks/useBatchEstimate.js';
 import { RUN_CONFIRMED_STEP_ERROR_CODES, STEP_QUOTE_ID_PATTERN, } from '../hooks/useRunConfirmedStep.js';
 import { RUN_TRAINING_ERROR_CODES } from '../hooks/useRunTraining.js';
+import { createMockReactions, REACTION_SCOPE, } from './mockHostReactions.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
 /**
@@ -1092,6 +1093,16 @@ export function createMockHost(options = {}) {
     // survived review. There is no READ op on this bridge for such a map to feed,
     // so the honest shape is not to offer one.
     let collectionFollowError = options.collectionFollowError;
+    // App reactions: per-image state + a forced-error knob, owned by
+    // `./mockHostReactions.ts`. The scope test is PRESENCE in the manifest's
+    // declared scopes, the same set the storage gate reads.
+    const reactionScopeDeclared = (options.declaredScopes ?? []).includes(REACTION_SCOPE);
+    const reactions = createMockReactions({
+        seed: options.reactionStates,
+        error: options.reactionError ?? undefined,
+        signedIn: () => viewer !== null,
+        hasScope: () => reactionScopeDeclared,
+    });
     // App Blocks → Post bridge: the canned post + a forced-refusal knob.
     let createPostResult = options.createPostResult ?? DEFAULT_CREATE_POST_RESULT;
     let createPostError = options.createPostError;
@@ -2582,6 +2593,27 @@ export function createMockHost(options = {}) {
                         });
                         return;
                     }
+                    case 'SET_ENTITY_REACTION': {
+                        // App reactions. Every path with a routable requestId replies exactly
+                        // once; the decision order is the real host's (see
+                        // `./mockHostReactions.ts`).
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        dispatchToBlock({
+                            type: 'ENTITY_REACTION_RESULT',
+                            payload: { requestId, ...reactions.set(typed.payload) },
+                        });
+                        return;
+                    }
+                    case 'GET_ENTITY_REACTIONS': {
+                        if (!isRoutableRequestId(requestId))
+                            return;
+                        dispatchToBlock({
+                            type: 'ENTITY_REACTIONS_RESULT',
+                            payload: { requestId, ...reactions.get(typed.payload) },
+                        });
+                        return;
+                    }
                     case 'CREATE_POST_FROM_APP': {
                         // Publish a REAL Post on the viewer's profile from the app's own
                         // outputs. Drop a request with no requestId (unroutable) — same as
@@ -3754,6 +3786,9 @@ export function createMockHost(options = {}) {
             wildcardPackError = patch.wildcardPackError;
         if (patch.collectionFollowError !== undefined)
             collectionFollowError = patch.collectionFollowError;
+        if (patch.reactionStates !== undefined || patch.reactionError !== undefined) {
+            reactions.configure({ seed: patch.reactionStates, error: patch.reactionError });
+        }
         if (patch.createPostResult !== undefined)
             createPostResult = patch.createPostResult;
         if (patch.createPostError !== undefined)

package/dist/internal/mockHostReactions.d.ts

@@ -0,0 +1,62 @@
+/**
+ * mockHostReactions.ts — the dev host's half of `SET_ENTITY_REACTION` /
+ * `GET_ENTITY_REACTIONS` (app reactions, civitai/civitai#6144).
+ *
+ * It mirrors the REAL host's decision order, from civitai's `reactionGate.ts`
+ * and `blocks.setReactionFromApp` / `blocks.getReactionsForApp`:
+ *
+ *   1. no usable `requestId` → dropped (nothing to reply to);
+ *   1b. a forced `review-mode` / `not-ready` (`reactionError`) → that code,
+ *      since the host's preflight checks both before anything else;
+ *   2. no viewer → `sign-in-required` (identity before payload);
+ *   3. malformed payload, or a reaction apps may not set (`Dislike`) →
+ *      `invalid-request`;
+ *   4. `social:react:self` not among the manifest's declared scopes →
+ *      `needs-consent`;
+ *   5. the forced-error knob, when set;
+ *   6. a write without a ticket → `entity-unavailable`; a read answers only
+ *      ticketed ids and lists the rest in `unavailable`.
+ *
+ * 🔴 WHAT THIS CANNOT CHECK: whether a ticket is GENUINE. A real ticket is an
+ * HMAC the server signs with a secret no block holds, so this mock accepts any
+ * well-formed one (1 to 256 characters). A block that invents tickets passes
+ * here and fails in production with `entity-unavailable`; the tickets a block
+ * passes should be the `reactTicket` fields its images arrived with.
+ *
+ * The mock never produces `review-mode` or `not-ready` on its own; force them
+ * with `reactionError`, and they are answered at step 1b, as the host would.
+ */
+import type { BlockEntityReactionResult, BlockEntityReactionsResult, BlockReactionCounts, BlockStoredReaction } from '@civitai/app-sdk/blocks';
+/** The scope both messages need. */
+export declare const REACTION_SCOPE = "social:react:self";
+/** A seeded image for the mock. Every field is optional; absent counts are 0. */
+export interface MockReactionSeed {
+    counts?: Partial<BlockReactionCounts>;
+    viewerReactions?: BlockStoredReaction[];
+    /** Report this image's counts as unknown, as the real metric store sometimes does. */
+    statsUnknown?: boolean;
+}
+/** The reply payload, minus `requestId`. */
+export type MockReactionReply<T> = {
+    result: T;
+} | {
+    error: string;
+};
+export interface MockReactions {
+    set(payload: unknown): MockReactionReply<BlockEntityReactionResult>;
+    get(payload: unknown): MockReactionReply<BlockEntityReactionsResult>;
+    /** Replace the seed and the forced error, as `setScenario` does. */
+    configure(patch: {
+        seed?: Record<number, MockReactionSeed>;
+        error?: string | null;
+    }): void;
+}
+export declare function createMockReactions(opts: {
+    seed?: Record<number, MockReactionSeed>;
+    error?: string;
+    /** Is a viewer signed in? Read on every call. */
+    signedIn: () => boolean;
+    /** Does the manifest declare the scope? Read on every call. */
+    hasScope: () => boolean;
+}): MockReactions;
+//# sourceMappingURL=mockHostReactions.d.ts.map

package/dist/internal/mockHostReactions.js

@@ -0,0 +1,166 @@
+/**
+ * mockHostReactions.ts — the dev host's half of `SET_ENTITY_REACTION` /
+ * `GET_ENTITY_REACTIONS` (app reactions, civitai/civitai#6144).
+ *
+ * It mirrors the REAL host's decision order, from civitai's `reactionGate.ts`
+ * and `blocks.setReactionFromApp` / `blocks.getReactionsForApp`:
+ *
+ *   1. no usable `requestId` → dropped (nothing to reply to);
+ *   1b. a forced `review-mode` / `not-ready` (`reactionError`) → that code,
+ *      since the host's preflight checks both before anything else;
+ *   2. no viewer → `sign-in-required` (identity before payload);
+ *   3. malformed payload, or a reaction apps may not set (`Dislike`) →
+ *      `invalid-request`;
+ *   4. `social:react:self` not among the manifest's declared scopes →
+ *      `needs-consent`;
+ *   5. the forced-error knob, when set;
+ *   6. a write without a ticket → `entity-unavailable`; a read answers only
+ *      ticketed ids and lists the rest in `unavailable`.
+ *
+ * 🔴 WHAT THIS CANNOT CHECK: whether a ticket is GENUINE. A real ticket is an
+ * HMAC the server signs with a secret no block holds, so this mock accepts any
+ * well-formed one (1 to 256 characters). A block that invents tickets passes
+ * here and fails in production with `entity-unavailable`; the tickets a block
+ * passes should be the `reactTicket` fields its images arrived with.
+ *
+ * The mock never produces `review-mode` or `not-ready` on its own; force them
+ * with `reactionError`, and they are answered at step 1b, as the host would.
+ */
+import { REACTIONS } from '../hooks/useReactions.js';
+/** The scope both messages need. */
+export const REACTION_SCOPE = 'social:react:self';
+const MAX_IDS = 100;
+const MAX_TICKET = 256;
+const isPositiveInt = (v) => typeof v === 'number' && Number.isInteger(v) && v > 0;
+const isTicket = (v) => typeof v === 'string' && v.length > 0 && v.length <= MAX_TICKET;
+const isAppReaction = (v) => typeof v === 'string' && REACTIONS.includes(v);
+function zeroCounts() {
+    return { Like: 0, Heart: 0, Laugh: 0, Cry: 0 };
+}
+export function createMockReactions(opts) {
+    const states = new Map();
+    let forcedError = opts.error;
+    const seedWith = (seed) => {
+        states.clear();
+        for (const [key, value] of Object.entries(seed ?? {})) {
+            states.set(Number(key), {
+                counts: { ...zeroCounts(), ...(value.counts ?? {}) },
+                viewerReactions: [...(value.viewerReactions ?? [])],
+                statsUnknown: value.statsUnknown === true,
+            });
+        }
+    };
+    seedWith(opts.seed);
+    const stateOf = (id) => states.get(id) ?? { counts: zeroCounts(), viewerReactions: [], statsUnknown: false };
+    /** Steps 2 to 5; `null` when the request may proceed. */
+    const refuse = (validPayload) => {
+        // The host's own preflight refusals come before everything else
+        // (`reactionGate.ts`: review mode, then the handshake, then the viewer), so
+        // a forced one is answered first. Every other forced code stands for a
+        // SERVER answer, which only a request past the host's gate can get.
+        if (forcedError === 'review-mode' || forcedError === 'not-ready')
+            return forcedError;
+        if (!opts.signedIn())
+            return 'sign-in-required';
+        if (!validPayload)
+            return 'invalid-request';
+        if (!opts.hasScope())
+            return 'needs-consent';
+        if (forcedError !== undefined)
+            return forcedError;
+        return null;
+    };
+    return {
+        set(payload) {
+            const p = (payload ?? {});
+            const valid = p.entityType === 'image' &&
+                isPositiveInt(p.entityId) &&
+                isAppReaction(p.reaction) &&
+                typeof p.reacted === 'boolean' &&
+                (p.ticket === undefined || isTicket(p.ticket));
+            const refusal = refuse(valid);
+            if (refusal !== null)
+                return { error: refusal };
+            if (!isTicket(p.ticket))
+                return { error: 'entity-unavailable' };
+            const id = p.entityId;
+            const reaction = p.reaction;
+            const reacted = p.reacted;
+            const before = stateOf(id);
+            const holds = before.viewerReactions.includes(reaction);
+            const changed = holds !== reacted;
+            const after = changed
+                ? {
+                    counts: {
+                        ...before.counts,
+                        [reaction]: Math.max(0, before.counts[reaction] + (reacted ? 1 : -1)),
+                    },
+                    viewerReactions: reacted
+                        ? [...before.viewerReactions, reaction]
+                        : before.viewerReactions.filter((r) => r !== reaction),
+                    statsUnknown: before.statsUnknown,
+                }
+                : before;
+            states.set(id, after);
+            return {
+                result: {
+                    entityType: 'image',
+                    entityId: id,
+                    reaction,
+                    reacted,
+                    changed,
+                    counts: { ...after.counts },
+                    viewerReactions: [...after.viewerReactions],
+                    statsUnknown: after.statsUnknown,
+                },
+            };
+        },
+        get(payload) {
+            const p = (payload ?? {});
+            const ids = p.ids;
+            const ticketsOk = p.tickets === undefined ||
+                (typeof p.tickets === 'object' && p.tickets !== null && !Array.isArray(p.tickets));
+            const valid = p.entityType === 'image' &&
+                Array.isArray(ids) &&
+                ids.length > 0 &&
+                ids.length <= MAX_IDS &&
+                ids.every(isPositiveInt) &&
+                ticketsOk;
+            if (valid && p.tickets !== undefined) {
+                // The real gate refuses a malformed ticket for a REQUESTED id, and
+                // ignores the tickets for ids it was not asked about.
+                const wanted = new Set(ids.map(String));
+                for (const [key, value] of Object.entries(p.tickets)) {
+                    if (wanted.has(key) && !isTicket(value))
+                        return { error: refuse(false) ?? 'invalid-request' };
+                }
+            }
+            const refusal = refuse(valid);
+            if (refusal !== null)
+                return { error: refusal };
+            const tickets = (p.tickets ?? {});
+            const byId = {};
+            const unavailable = [];
+            for (const id of new Set(ids)) {
+                if (!isTicket(tickets[String(id)])) {
+                    unavailable.push(id);
+                    continue;
+                }
+                const s = stateOf(id);
+                byId[String(id)] = {
+                    counts: { ...s.counts },
+                    viewerReactions: [...s.viewerReactions],
+                    statsUnknown: s.statsUnknown,
+                };
+            }
+            return { result: { entityType: 'image', byId, unavailable } };
+        },
+        configure(patch) {
+            if (patch.seed !== undefined)
+                seedWith(patch.seed);
+            if (patch.error !== undefined)
+                forcedError = patch.error ?? undefined;
+        },
+    };
+}
+//# sourceMappingURL=mockHostReactions.js.map

package/dist/testing.d.ts

@@ -22,6 +22,7 @@ import { type MockHostOptions } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
 export { installPopoverShim, type PopoverShimHandle, type PopoverShimOptions, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type MockWorkflowStepInfo, type MockWorkflowQuoteFailure, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
+export { type MockReactionSeed } from './internal/mockHostReactions.js';
 export { fakeResourceSource, type FakeResourceCanned, type FakeResourceSource, } from './internal/fakeResourceSource.js';
 /**
  * Props for the dev {@link Harness}.

package/dist/transport/requestTimeouts.js

@@ -159,6 +159,12 @@ const REQUEST_TIMEOUT_CLASS = {
     // whether a human is involved. Not reclassified here.
     SAVE_IMAGE: 'protocol',
     SET_USER_CHECKPOINT: 'protocol',
+    // App reactions. `'protocol'`, NOT `'human'`, and that is a decision rather
+    // than an omission: unlike SET_COLLECTION_FOLLOW there is no host confirm to
+    // wait on. The consent is the `social:react:self` grant, made beforehand; a
+    // host without it refuses `needs-consent` at once.
+    SET_ENTITY_REACTION: 'protocol',
+    GET_ENTITY_REACTIONS: 'protocol',
     SHARED_APPEND: 'protocol',
     SHARED_GET: 'protocol',
     SHARED_GET_COUNT: 'protocol',

package/dist/transport/validate.d.ts

@@ -395,6 +395,30 @@ export declare function isValidImagesResult(p: unknown): boolean;
  * reach a consumer keying UI state by id.
  */
 export declare function isValidCollectionFollowResult(p: unknown): boolean;
+/**
+ * Reply to a block-initiated `SET_ENTITY_REACTION`. A well-formed reply carries
+ * EITHER a `result` OR an `error`; one with neither is malformed and dropped.
+ *
+ * `error` is SHAPE-CHECKED ONLY, although the host's set is closed
+ * (`ENTITY_REACTION_ERROR_CODES`): a code a newer host adds must still reach
+ * the block as a rejection. A membership check would drop it, and a dropped
+ * reply on a request-style message does not reject, it waits out the timeout.
+ * `useReactions` turns an unknown string into a `ReactionError` with no `code`.
+ *
+ * `result` is checked as far as a consumer reads it: `entityId` a positive
+ * integer (state is keyed by it), `reaction` a non-empty string, `reacted` and
+ * `changed` booleans, plus the state fields.
+ */
+export declare function isValidEntityReactionResult(p: unknown): boolean;
+/**
+ * Reply to a block-initiated `GET_ENTITY_REACTIONS`. Same one-of and shape-only
+ * `error` contract as {@link isValidEntityReactionResult}.
+ *
+ * `result.byId` must be an object whose every key is a positive-integer id
+ * spelled as a string and whose every value is a valid state;
+ * `result.unavailable` an array of positive-integer ids.
+ */
+export declare function isValidEntityReactionsResult(p: unknown): boolean;
 /**
  * Reply to a block-initiated `CREATE_POST_FROM_APP`. A well-formed reply carries
  * EITHER a `result` (`{ postId: positive int, url: non-empty string, imageIds:

package/dist/transport/validate.js

@@ -1368,6 +1368,121 @@ export function isValidCollectionFollowResult(p) {
         return false;
     return true;
 }
+/** A positive integer id: what a reaction reply keys UI state by. */
+function isPositiveIntId(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0;
+}
+/**
+ * One image's reaction state inside an `ENTITY_REACTION(S)_RESULT`: `counts` an
+ * object of finite numbers, `viewerReactions` an array of strings,
+ * `statsUnknown` a boolean.
+ *
+ * 🔴 The reaction NAMES are not membership-checked, in `counts` or in
+ * `viewerReactions`. The site stores five reactions and may add a sixth; a
+ * reply naming one this SDK does not know is still a true statement about the
+ * viewer, and dropping it would hang the request to its timeout instead.
+ */
+function isValidEntityReactionState(v) {
+    if (!isObject(v))
+        return false;
+    if (!isObject(v.counts))
+        return false;
+    for (const n of Object.values(v.counts)) {
+        if (!isFiniteNumber(n))
+            return false;
+    }
+    if (!Array.isArray(v.viewerReactions))
+        return false;
+    for (const r of v.viewerReactions) {
+        if (typeof r !== 'string')
+            return false;
+    }
+    if (typeof v.statsUnknown !== 'boolean')
+        return false;
+    return true;
+}
+/**
+ * Reply to a block-initiated `SET_ENTITY_REACTION`. A well-formed reply carries
+ * EITHER a `result` OR an `error`; one with neither is malformed and dropped.
+ *
+ * `error` is SHAPE-CHECKED ONLY, although the host's set is closed
+ * (`ENTITY_REACTION_ERROR_CODES`): a code a newer host adds must still reach
+ * the block as a rejection. A membership check would drop it, and a dropped
+ * reply on a request-style message does not reject, it waits out the timeout.
+ * `useReactions` turns an unknown string into a `ReactionError` with no `code`.
+ *
+ * `result` is checked as far as a consumer reads it: `entityId` a positive
+ * integer (state is keyed by it), `reaction` a non-empty string, `reacted` and
+ * `changed` booleans, plus the state fields.
+ */
+export function isValidEntityReactionResult(p) {
+    if (!isObject(p))
+        return false;
+    if (!isWireRequestIdShape(p.requestId))
+        return false;
+    if (p.error !== undefined && typeof p.error !== 'string')
+        return false;
+    if (p.result !== undefined) {
+        const r = p.result;
+        if (!isObject(r))
+            return false;
+        if (!isNonEmptyString(r.entityType))
+            return false;
+        if (!isPositiveIntId(r.entityId))
+            return false;
+        if (!isNonEmptyString(r.reaction))
+            return false;
+        if (typeof r.reacted !== 'boolean')
+            return false;
+        if (typeof r.changed !== 'boolean')
+            return false;
+        if (!isValidEntityReactionState(r))
+            return false;
+    }
+    if (p.result === undefined && p.error === undefined)
+        return false;
+    return true;
+}
+/**
+ * Reply to a block-initiated `GET_ENTITY_REACTIONS`. Same one-of and shape-only
+ * `error` contract as {@link isValidEntityReactionResult}.
+ *
+ * `result.byId` must be an object whose every key is a positive-integer id
+ * spelled as a string and whose every value is a valid state;
+ * `result.unavailable` an array of positive-integer ids.
+ */
+export function isValidEntityReactionsResult(p) {
+    if (!isObject(p))
+        return false;
+    if (!isWireRequestIdShape(p.requestId))
+        return false;
+    if (p.error !== undefined && typeof p.error !== 'string')
+        return false;
+    if (p.result !== undefined) {
+        const r = p.result;
+        if (!isObject(r))
+            return false;
+        if (!isNonEmptyString(r.entityType))
+            return false;
+        if (!isObject(r.byId))
+            return false;
+        for (const [key, state] of Object.entries(r.byId)) {
+            if (!/^[1-9][0-9]*$/.test(key))
+                return false;
+            if (!isValidEntityReactionState(state))
+                return false;
+        }
+        if (!Array.isArray(r.unavailable))
+            return false;
+        for (const id of r.unavailable) {
+            if (!isPositiveIntId(id))
+                return false;
+        }
+    }
+    if (p.result === undefined && p.error === undefined)
+        return false;
+    return true;
+}
 /**
  * Reply to a block-initiated `CREATE_POST_FROM_APP`. A well-formed reply carries
  * EITHER a `result` (`{ postId: positive int, url: non-empty string, imageIds:
@@ -2167,6 +2282,10 @@ export function payloadValidatorFor(type) {
             return isValidImagesResult;
         case 'COLLECTION_FOLLOW_RESULT':
             return isValidCollectionFollowResult;
+        case 'ENTITY_REACTION_RESULT':
+            return isValidEntityReactionResult;
+        case 'ENTITY_REACTIONS_RESULT':
+            return isValidEntityReactionsResult;
         // 🔴 PRESENCE of this entry IS compiler-enforced (the `never` bind in
         // `default:`); WHICH validator it names is not. This reply settles a PUBLIC
         // POST, so the identity is pinned by test as well — see the mapping pin in