@civitai/blocks-react 0.74.1 → 0.76.0

package/README.md

@@ -675,6 +675,14 @@ showImages(done.imageUrls ?? []);
   KB (262144 bytes) for every step's `input` plus `arguments` together. An
   unknown key on the body or on a step is rejected. The app's velocity limit
   counts one unit per step, and a `repeat` step one per iteration instead.
+- **No inline media** in a step `input` or in `arguments` — here or in a
+  pass-through `kind: 'step'` body's `input`: no `data:image|video|audio` URI
+  and no raw base64 string of 4096+ characters, at any depth. Upload the image,
+  video or audio with [`useMediaUpload()`](#usemediaupload) (an image also works
+  with `useImageUpload({ purpose: 'generationSource' })` or `useImagePicker()`)
+  and pass the returned `url`. A body holding more than
+  262144 values in those fields is refused outright. `createMockHost` refuses
+  both as the host does, naming the path.
 - `suppressOutput: true` marks an intermediate step. Its images are left out of
   `snapshot.imageUrls` and out of its own `steps[i].imageUrls`. It still runs
   and is still charged.
@@ -1273,6 +1281,112 @@ async function toggle() {
 Most blocks want `<FollowButton>` from `@civitai/blocks-react/ui` instead, which
 wires all of the above.
 
+### `useReactions(entityType, ids, { tickets })`
+
+Read and set the **viewer's** reactions on images this app was served, over
+`GET_ENTITY_REACTIONS` / `SET_ENTITY_REACTION`. Returns
+`{ byId, unavailable, loading, error, toggle, pending }`.
+
+It reads on mount, then reads again only the images that need it: an id added
+to `ids`, or one whose ticket changed. An id that leaves `ids` costs nothing.
+Every read counts against the block instance's catalog rate limit on the host,
+which every viewer of a page app shares with its other catalog reads.
+
+A reaction made here **is** a reaction on civitai.com: it pays the reactor and
+the image owner exactly as the site's own button does, moves rankings, notifies,
+and lists the viewer among the reactors. It draws on the **same** per-viewer
+quota as the site. Apps may set `Like`, `Heart`, `Laugh` and `Cry`; never
+`Dislike`. Image is the only entity type today.
+
+🔴 **Scope `social:react:self`: consent-gated and sensitive.** Declare it with a
+`scopeJustifications` entry. Until the viewer grants it, every call fails with
+`needs-consent` (`err.needsConsent`): ask with `useRequestConsent()`. There is
+no per-tap confirm.
+
+🔴 **Tickets are required, and only the REST block endpoints supply them.** Each
+image that `/api/v1/blocks/images`, `/api/v1/blocks/gated-images` or
+`/api/v1/blocks/collections/{id}` serves, fetched with the block token for a
+signed-in viewer, carries a `reactTicket` signed for this app and this viewer
+for 24 hours. **No hook in this package supplies one yet:** `useGatedImages()`
+goes through the host bridge, whose reply carries no `reactTicket`
+([#687](https://github.com/civitai/civitai-app-starters/issues/687)). Pass the
+tickets as `tickets`, keyed by image id. An image without a valid one is not
+answered by the read (it lands in `unavailable`, which is **not** "not reacted")
+and a `toggle` on it is refused locally, before anything is sent.
+
+`toggle(id, reaction, reacted)` sets a **desired state**, moves `byId[id]`
+optimistically, and puts it back on failure. It rejects with a `ReactionError`:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.needsConsent` | the scope is not granted | `useRequestConsent()` |
+| `err.code === 'rate-limited'` | the viewer's reaction quota is spent | back off |
+| `err.code === 'entity-unavailable'` | no valid ticket, an image the viewer may not react to, the kill switch, or a network failure | retry later or give up |
+| `err.code` otherwise | `invalid-request` / `review-mode` / `not-ready` | a block bug, a review sandbox, or retry after `ready` |
+| `err.timedOut` | no reply within 30s | the write **may** have landed; the hook re-reads that image |
+| `err.busy` | the same image and reaction already has a request in flight. Rejects the call only: `error` is not set, because the write it collided with is still running | disable the control while `pending(id, reaction)` |
+
+🔴 **Bind `<civitai-reaction>` from `byId` on every render; never let it keep
+its own state.** The element flips `reacted` and `count` itself on a click. When
+the hook makes no optimistic move of its own (an image not read yet, or a
+refusal such as a missing ticket), `byId` does not change, so an element that
+only listens would keep showing a reaction that does not exist. Every rejected
+`toggle` re-renders the owner: a refusal or a failed write sets `error`, and a
+`busy` refusal is followed by the in-flight write's own settle, which clears
+`pending`. An element whose `reacted` and `count` come from `byId` on each
+render is then put back. Outside React, set the two properties back yourself
+after a rejection.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { isAppReaction } from '@civitai/app-sdk/blocks';
+import { useBlockToken, useHostOrigin, useReactions } from '@civitai/blocks-react';
+
+type ServedImage = { id: number; url: string; reactTicket?: string };
+
+function useReactableImages() {
+  const host = useHostOrigin();
+  const { raw } = useBlockToken();
+  const [images, setImages] = useState<ServedImage[]>([]);
+
+  // The tickets come from the REST endpoint, fetched with the block token.
+  useEffect(() => {
+    if (!host || !raw) return;
+    void fetch(`${host}/api/v1/blocks/images?limit=20`, {
+      headers: { Authorization: `Bearer ${raw}` },
+    })
+      .then((res) => res.json() as Promise<{ items: ServedImage[] }>)
+      .then((body) => setImages(body.items));
+  }, [host, raw]);
+
+  const reactions = useReactions(
+    'image',
+    images.map((image) => image.id),
+    { tickets: Object.fromEntries(images.map((image) => [image.id, image.reactTicket])) },
+  );
+
+  // Props for one `<civitai-reaction>` (e.g. `CivitaiReaction` from
+  // `@civitai/components-react`), derived from `byId` on every render.
+  const bind = (id: number, reaction: 'Like' | 'Heart' | 'Laugh' | 'Cry') => ({
+    reaction,
+    reacted: reactions.byId[id]?.viewerReactions.includes(reaction) ?? false,
+    count: reactions.byId[id]?.counts[reaction] ?? 0,
+    disabled: !reactions.byId[id] || reactions.pending(id, reaction),
+    onReact: (event: CustomEvent<{ reaction?: string; reacted: boolean }>) => {
+      const { reaction: which, reacted } = event.detail;
+      // `detail.reaction` is any string the element was given; narrow it.
+      if (!isAppReaction(which)) return;
+      // A rejection needs no handling here to put the element back: it
+      // re-renders, and `bind` reads `byId` again.
+      reactions.toggle(id, which, reacted).catch(() => {});
+    },
+  });
+
+  return { images, bind, error: reactions.error };
+}
+```
+
 ### `useCreatePostFromApp()`
 
 Publish a **real, published Post on the viewer's profile** from this app's own
@@ -2369,6 +2483,126 @@ an invalid `sources` or `multiple` with an error, and answers
 list the viewer's images, so there `open` rejects with a message saying to use
 the mock host.
 
+### `useMediaUpload()`
+
+**The way to pass any media (image, video or audio) into a workflow step.** The
+host refuses data URIs and inline base64 in step inputs, so upload the file
+with this hook and pass the `url` it returns into the step input. Returns
+`{ open, upload }`.
+
+- **`open({ kind })`** opens the host's own file picker for that kind. The
+  viewer picks a file, the host uploads it, and `open` resolves with the
+  upload, or `null` if nothing was uploaded.
+- **`upload({ kind, bytes, mimeType? })`** uploads media your app already
+  holds in the tab, with no picker: a canvas export, a crop, a `MediaRecorder`
+  recording. It resolves with the upload, and never resolves without one.
+
+```tsx
+import { useMediaUpload } from '@civitai/blocks-react';
+
+function UseRecording({ recording }: { recording: Blob }) {
+  const { upload } = useMediaUpload();
+
+  async function onClick() {
+    const audio = await upload({
+      kind: 'audio',
+      bytes: await recording.arrayBuffer(),
+      mimeType: recording.type, // optional; checked against the content
+    });
+    // audio.url goes into the step's audio input
+    startStep({ audioUrl: audio.url });
+  }
+
+  return <button onClick={onClick}>Use this recording</button>;
+}
+```
+
+```tsx
+const { open } = useMediaUpload();
+
+const video = await open({ kind: 'video' }); // BlockMediaUploadInfo | null
+if (video) {
+  // video.url, video.width, video.height, video.durationMs (when known)
+}
+```
+
+What each kind accepts, decided by the file's **content** (its first bytes),
+never by its name or declared type:
+
+| `kind` | Accepted | What you get back |
+|---|---|---|
+| `'image'` | PNG, JPEG, WebP | Resized so both sides are 64 to 2048 pixels and re-encoded as JPEG: `mimeType` is always `'image/jpeg'`, and `sizeBytes`, `width` and `height` describe that JPEG. |
+| `'video'` | MP4, WebM | Uploaded as sent. `width` and `height` are always set (a file with no video track is refused). `durationMs` when the browser reports a duration. |
+| `'audio'` | MP3, WAV, WebM | Uploaded as sent. No `width` or `height`. `durationMs` when the browser reports a duration: a `MediaRecorder` WebM often reports none, so do not rely on it. |
+
+- **At most 24 MB per image, and 64 MB per video or audio file.** The image
+  cap is lower because the host decodes an image in full before it resizes it.
+  `upload` refuses a larger buffer before sending it, with the host's own
+  message: `file exceeds the 24 MB image upload limit` or
+  `file exceeds the 64 MB upload limit`.
+- **`upload` is rate-limited:** at most 8 uploads and 128 MB per 60 seconds
+  per page. Past that the host replies `busy`; wait and retry. A refused upload
+  does not count. `open` is not limited this way, because a person picks each
+  file.
+- **`mimeType` is optional.** When you pass it (for example `blob.type`) it
+  must match the content, or the upload is refused with
+  `mimeType does not match the file's content`. Case and parameters such as
+  `;codecs=opus` are ignored, and `audio/x-wav` counts as `audio/wav`.
+- Pass an `ArrayBuffer` (`await blob.arrayBuffer()`). A `Blob`, a typed array
+  or an empty buffer is refused before sending with
+  `invalid media-upload request`. The buffer is copied, not transferred.
+- A file whose content is not one of its kind's types is refused with
+  `images must be PNG, JPEG or WebP`, `videos must be MP4 or WebM` or
+  `audio must be MP3, WAV or WebM`. The host also refuses a file it cannot
+  read (`could not read this video file`, `could not read this audio file`), a
+  video with no video track (`this file has no video track`), and an image too
+  small to resize to 64 pixels. A failed upload rejects with
+  `media upload failed — please try again`, and a file the upload service
+  refuses with `this video was refused by the upload service` or
+  `this audio was refused by the upload service`. A bytes upload made while
+  the host holds no block token rejects with `no block token`.
+
+What `open` and `upload` resolve and reject with:
+
+- **`open` resolves `null` when nothing was uploaded.** Usually the viewer
+  closed the picker. The host also answers that way at once, without showing a
+  picker, while your app is viewed in review mode or is not ready yet. A
+  problem with the picked file is shown in the picker, where the viewer can
+  pick another one.
+- **`upload` never resolves `null`.** When the host declines without
+  uploading (review mode, not ready), `upload` rejects with
+  `the host did not upload the media (the app is in review mode or not ready)`.
+- **A refusal rejects** with the host's message, in both modes. On a surface
+  other than a page app the host answers at once with
+  `unsupported on this host`.
+- **Both wait up to 10 minutes** for the host (a person picking a file, or a
+  large upload), then reject with a `RequestTimeoutError`.
+
+For images only, `useImageUpload().open({ purpose: 'generationSource' })` still
+works and returns `{ url, width, height }`. Use `useMediaUpload` for video,
+audio, or bytes your app made in the tab.
+
+🔴 **Needs a host that answers `OPEN_MEDIA_UPLOAD`** (civitai/civitai#6149).
+On a civitai.com that predates it, the request gets no answer and both calls reject with a
+`RequestTimeoutError` after 10 minutes.
+
+With the mock host (`createMockHost` or `Harness` from
+`@civitai/blocks-react/testing`) there is no picker: `open` resolves at once
+with a built-in upload for the kind. Set `cannedMediaUploads: { video: {...} }`
+to choose what a kind returns, or `{ audio: null }` for a viewer who closes
+that picker. `upload` runs the host's checks in the host's order (kind,
+purpose, an invalid buffer, the per-kind cap, the rate window, the content type,
+a mismatching `mimeType`) and answers with that kind's upload, carrying the
+sniffed `mimeType` and the buffer's size for video and audio. The mock cannot
+decode media, so it never produces the host's decode-time refusals (an
+unreadable file, no video track, an image too small, an upload failure): set
+`mediaUploadError: 'this file has no video track'` to force one.
+`mediaUploadError: 'no block token'` is checked where the host checks it: a
+bytes upload is refused before the cap and the window, and is not counted. A model-slot
+`context` answers `unsupported on this host`. `dev:live` cannot upload
+generation inputs, so there both calls reject 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
@@ -3318,6 +3552,8 @@ MockHost
 MockHostFailMode
 MockHostOptions
 MockHostScenarioPatch
+MockMediaUploads
+MockReactionSeed
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario

package/dist/hooks/useMediaUpload.d.ts

@@ -0,0 +1,97 @@
+import type { BlockMediaKind, BlockMediaUploadInfo } from '@civitai/app-sdk/blocks';
+/**
+ * What `upload()` rejects with when the host answers with neither a file nor
+ * an error. For a bytes upload that means the host DECLINED it without trying
+ * (the app is viewed in review mode, or is not ready yet). Nothing was
+ * uploaded, so it must never read as a success.
+ */
+export declare const MEDIA_UPLOAD_DECLINED_ERROR = "the host did not upload the media (the app is in review mode or not ready)";
+/** Options for {@link UseMediaUpload.open}. */
+export interface MediaUploadOpenOptions {
+    /** What the viewer picks: `'image'`, `'video'` or `'audio'`. */
+    kind: BlockMediaKind;
+}
+/** Options for {@link UseMediaUpload.upload}. */
+export interface MediaUploadBytesOptions {
+    /** What the bytes are: `'image'`, `'video'` or `'audio'`. */
+    kind: BlockMediaKind;
+    /**
+     * The file, as an `ArrayBuffer` (`await blob.arrayBuffer()`). At most 24 MB
+     * for an image and 64 MB for video or audio.
+     * Copied across `postMessage`, never transferred. A `Blob`, a typed array or
+     * an empty buffer is refused before sending.
+     */
+    bytes: ArrayBuffer;
+    /**
+     * Optional: the type you believe you are sending (`blob.type`). The host
+     * decides the type from the content; when this is given and disagrees, the
+     * upload is refused with `mimeType does not match the file's content`.
+     * Parameters (`;codecs=…`) and case are ignored.
+     */
+    mimeType?: string;
+}
+/** What {@link useMediaUpload} returns. */
+export interface UseMediaUpload {
+    /**
+     * PICKER mode: the host opens its own file picker for `kind`, uploads what
+     * the viewer picks, and resolves with it. Resolves `null` when nothing was
+     * uploaded: the viewer closed the picker, or the host declined at once
+     * (review mode, not ready). Rejects with the host's message on a refusal.
+     */
+    open: (options: MediaUploadOpenOptions) => Promise<BlockMediaUploadInfo | null>;
+    /**
+     * BYTES mode: upload media the block holds (a canvas export, a crop, a
+     * `MediaRecorder` recording) with no picker. Resolves with the uploaded
+     * file. Rejects with the host's message on every refusal or failure, and
+     * with {@link MEDIA_UPLOAD_DECLINED_ERROR} when the host declined without
+     * uploading. It never resolves without a file.
+     */
+    upload: (options: MediaUploadBytesOptions) => Promise<BlockMediaUploadInfo>;
+}
+/**
+ * Upload an image, video or audio file as a GENERATION INPUT, and get back a
+ * `url` to pass into a workflow step input.
+ *
+ * 🔴 THIS IS THE WAY TO PUT MEDIA INTO A STEP. The host refuses data URIs and
+ * inline base64 in step inputs, so upload the file here and pass the returned
+ * `url`.
+ *
+ * - `open({ kind })` lets the viewer pick a file in the host's own picker.
+ * - `upload({ kind, bytes, mimeType? })` uploads bytes the block made in the
+ *   tab, with no picker.
+ *
+ * The type is decided by the file's content: images PNG, JPEG or WebP (the
+ * host resizes them to 64–2048 px per side and re-encodes them as JPEG);
+ * videos MP4 or WebM; audio MP3, WAV or WebM. At most 24 MB per image (the
+ * host decodes it in full before resizing) and 64 MB per video or audio; bytes
+ * mode also allows at most 8 uploads and 128 MB per 60 s per page, and
+ * rejects `busy` past that (retry later).
+ *
+ * Refused BEFORE sending, with the host's own strings: an unknown `kind`, an
+ * `upload` whose `bytes` is not a non-empty `ArrayBuffer` (or whose `mimeType`
+ * is not a string), and a buffer over the kind's cap.
+ *
+ * Page apps only: a model-slot host rejects with `unsupported on this host`.
+ * A host that predates this message does not answer it, so the call rejects
+ * with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * For images, `useImageUpload().open({ purpose: 'generationSource' })` remains
+ * valid; this hook is the one that also takes video, audio and in-tab bytes.
+ *
+ * @example
+ * // A recording made in the tab, passed into a step.
+ * const { upload } = useMediaUpload();
+ * const audio = await upload({ kind: 'audio', bytes: await recording.arrayBuffer(), mimeType: recording.type });
+ * // audio.url goes into the step's audio input
+ *
+ * @example
+ * // The viewer picks a video.
+ * const { open } = useMediaUpload();
+ * const video = await open({ kind: 'video' });
+ * if (video) {
+ *   // video.url, video.width, video.height, video.durationMs
+ * }
+ */
+export declare function useMediaUpload(): UseMediaUpload;
+//# sourceMappingURL=useMediaUpload.d.ts.map

package/dist/hooks/useMediaUpload.js

@@ -0,0 +1,108 @@
+import { useCallback } from 'react';
+import { MEDIA_UPLOAD_INVALID_ERROR, MEDIA_UPLOAD_KIND_ERROR, isMediaKind, mediaUploadCap, } from '../internal/mediaUploadBytes.js';
+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';
+/**
+ * What `upload()` rejects with when the host answers with neither a file nor
+ * an error. For a bytes upload that means the host DECLINED it without trying
+ * (the app is viewed in review mode, or is not ready yet). Nothing was
+ * uploaded, so it must never read as a success.
+ */
+export const MEDIA_UPLOAD_DECLINED_ERROR = 'the host did not upload the media (the app is in review mode or not ready)';
+/**
+ * Upload an image, video or audio file as a GENERATION INPUT, and get back a
+ * `url` to pass into a workflow step input.
+ *
+ * 🔴 THIS IS THE WAY TO PUT MEDIA INTO A STEP. The host refuses data URIs and
+ * inline base64 in step inputs, so upload the file here and pass the returned
+ * `url`.
+ *
+ * - `open({ kind })` lets the viewer pick a file in the host's own picker.
+ * - `upload({ kind, bytes, mimeType? })` uploads bytes the block made in the
+ *   tab, with no picker.
+ *
+ * The type is decided by the file's content: images PNG, JPEG or WebP (the
+ * host resizes them to 64–2048 px per side and re-encodes them as JPEG);
+ * videos MP4 or WebM; audio MP3, WAV or WebM. At most 24 MB per image (the
+ * host decodes it in full before resizing) and 64 MB per video or audio; bytes
+ * mode also allows at most 8 uploads and 128 MB per 60 s per page, and
+ * rejects `busy` past that (retry later).
+ *
+ * Refused BEFORE sending, with the host's own strings: an unknown `kind`, an
+ * `upload` whose `bytes` is not a non-empty `ArrayBuffer` (or whose `mimeType`
+ * is not a string), and a buffer over the kind's cap.
+ *
+ * Page apps only: a model-slot host rejects with `unsupported on this host`.
+ * A host that predates this message does not answer it, so the call rejects
+ * with `RequestTimeoutError` after the human-interaction timeout
+ * ({@link HUMAN_INTERACTION_TIMEOUT_MS}, 10 minutes).
+ *
+ * For images, `useImageUpload().open({ purpose: 'generationSource' })` remains
+ * valid; this hook is the one that also takes video, audio and in-tab bytes.
+ *
+ * @example
+ * // A recording made in the tab, passed into a step.
+ * const { upload } = useMediaUpload();
+ * const audio = await upload({ kind: 'audio', bytes: await recording.arrayBuffer(), mimeType: recording.type });
+ * // audio.url goes into the step's audio input
+ *
+ * @example
+ * // The viewer picks a video.
+ * const { open } = useMediaUpload();
+ * const video = await open({ kind: 'video' });
+ * if (video) {
+ *   // video.url, video.width, video.height, video.durationMs
+ * }
+ */
+export function useMediaUpload() {
+    useTransportConnection();
+    const open = useCallback(async ({ kind }) => {
+        if (!isMediaKind(kind))
+            throw new Error(MEDIA_UPLOAD_KIND_ERROR);
+        const reply = await sendTypedRequest(getTransport(), { type: 'OPEN_MEDIA_UPLOAD', payload: { kind, purpose: 'generationSource' } }, 'MEDIA_UPLOAD_RESULT', 
+        // A person picks the file, and the reply waits for the upload.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        // 🔴 BEFORE reading `selected`: a refusal carries none, and would
+        // otherwise resolve `null` exactly like a dismiss.
+        throwOnReplyError(reply, 'media upload failed');
+        return reply.selected ?? null;
+    }, []);
+    const upload = useCallback(async ({ kind, bytes, mimeType }) => {
+        // The host's own refusals, in the host's order, raised here so a doomed
+        // buffer is never copied across postMessage.
+        if (!isMediaKind(kind))
+            throw new Error(MEDIA_UPLOAD_KIND_ERROR);
+        if (!(bytes instanceof ArrayBuffer) || bytes.byteLength === 0) {
+            throw new Error(MEDIA_UPLOAD_INVALID_ERROR);
+        }
+        if (mimeType !== undefined && typeof mimeType !== 'string') {
+            throw new Error(MEDIA_UPLOAD_INVALID_ERROR);
+        }
+        const cap = mediaUploadCap(kind);
+        if (bytes.byteLength > cap.maxBytes)
+            throw new Error(cap.error);
+        const reply = await sendTypedRequest(getTransport(), {
+            type: 'OPEN_MEDIA_UPLOAD',
+            payload: {
+                kind,
+                purpose: 'generationSource',
+                bytes,
+                ...(mimeType !== undefined ? { mimeType } : {}),
+            },
+        }, 'MEDIA_UPLOAD_RESULT', 
+        // `'human'` class: a 64 MB upload plus the host's retries can outlast
+        // the default protocol timeout.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        throwOnReplyError(reply, 'media upload failed');
+        // A bare reply is the host declining (review mode / not ready). Nothing
+        // was uploaded, so this is a failure, not a success.
+        if (!reply.selected)
+            throw new Error(MEDIA_UPLOAD_DECLINED_ERROR);
+        return reply.selected;
+    }, []);
+    return { open, upload };
+}
+//# sourceMappingURL=useMediaUpload.js.map

package/dist/hooks/useReactions.d.ts

@@ -0,0 +1,126 @@
+import type { BlockAppReaction, BlockEntityReactionErrorCode, BlockEntityReactionResult, BlockEntityReactionState, BlockReactionCounts, BlockReactionEntityType, BlockStoredReaction } from '@civitai/app-sdk/blocks';
+export type { BlockAppReaction, BlockEntityReactionErrorCode, BlockEntityReactionResult, BlockEntityReactionState, BlockReactionCounts, BlockReactionEntityType, BlockStoredReaction, };
+/**
+ * The reactions an app may set, as a runtime value: `Like`, `Heart`, `Laugh`,
+ * `Cry`. Never `Dislike` (the host refuses it).
+ *
+ * Declared here rather than value-imported from `@civitai/app-sdk/blocks` (where
+ * `APP_REACTIONS` holds the same list) so this hook does not raise the package's
+ * `@civitai/app-sdk` peer floor; see `PEER_FLOOR.md`. `test/useReactions.test.tsx`
+ * asserts the two lists are equal.
+ */
+export declare const REACTIONS: readonly ["Like", "Heart", "Laugh", "Cry"];
+/**
+ * The CLOSED set of codes `ENTITY_REACTION(S)_RESULT` carries, as a runtime
+ * value. Mirrors civitai's `ENTITY_REACTION_ERRORS` (and `@civitai/app-sdk`'s
+ * `ENTITY_REACTION_ERROR_CODES`); declared locally for the peer-floor reason on
+ * {@link REACTIONS}.
+ */
+export declare const REACTION_ERROR_CODES: readonly ["invalid-request", "sign-in-required", "review-mode", "not-ready", "needs-consent", "entity-unavailable", "rate-limited"];
+/** `true` when `error` is one of the closed {@link REACTION_ERROR_CODES}. */
+export declare function isReactionErrorCode(error: string): error is BlockEntityReactionErrorCode;
+/**
+ * A reaction read or write that did not succeed.
+ *
+ * `.code` is the host's closed code, or `undefined` for a transport timeout, a
+ * code a newer host added, or a local {@link ReactionError.busy} refusal.
+ * Check the flags before `.message`: only a `.code` is meant to be branched on,
+ * and none of these messages is written for a viewer.
+ */
+export declare class ReactionError extends Error {
+    readonly code?: BlockEntityReactionErrorCode;
+    /**
+     * No reply arrived in time. 🔴 The write MAY have landed: the host could have
+     * completed it and failed to deliver the reply. The hook reverts its
+     * optimistic state and re-reads that image, so `byId` converges on the truth.
+     */
+    readonly timedOut: boolean;
+    /**
+     * Refused locally because the same image and reaction already has a request
+     * in flight. Nothing was sent. Disable the control while
+     * `pending(id, reaction)` is true and this does not happen.
+     */
+    readonly busy: boolean;
+    /** No session. Route into `useRequestSignIn()`. */
+    readonly signInRequired: boolean;
+    /** The viewer has not granted `social:react:self`. Ask with `useRequestConsent()`. */
+    readonly needsConsent: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+        busy?: boolean;
+    });
+}
+/** Options for {@link useReactions}. */
+export interface UseReactionsOptions {
+    /**
+     * The `reactTicket` each image arrived with, keyed by image id. A block
+     * endpoint (`/api/v1/blocks/images`, `/gated-images`, a collection's images)
+     * attaches one per image for a signed-in viewer, signed for this app and this
+     * viewer, valid 24 hours.
+     *
+     * 🔴 REQUIRED, for reads and writes alike. The host answers no image without
+     * a valid ticket: a read lists it in `unavailable`, and `toggle` on it is
+     * refused here with `entity-unavailable` before anything is sent, because
+     * the server would refuse it only AFTER spending one of the viewer's
+     * reactions from the quota the site's own button shares.
+     */
+    tickets: Readonly<Record<number | string, string | undefined>>;
+}
+/** What {@link useReactions} returns. */
+export interface UseReactions {
+    /**
+     * The known state per image id: counts, the viewer's reactions, and
+     * `statsUnknown`. An id is absent until a read answers it, and stays absent
+     * if the host listed it in {@link UseReactions.unavailable}.
+     */
+    byId: Readonly<Record<number, BlockEntityReactionState>>;
+    /**
+     * Ids the host would not answer for want of a valid ticket. 🔴 These have NO
+     * known state; do not render them as "not reacted".
+     */
+    unavailable: readonly number[];
+    /** `true` while a read is in flight. */
+    loading: boolean;
+    /** The last failure of a read or a write, or `null`. Cleared by the next one. */
+    error: ReactionError | null;
+    /**
+     * Set the viewer's `reaction` on image `id` to `reacted`, and resolve with
+     * what the host reports.
+     *
+     * Optimistic: `byId[id]` moves at once and moves back if the write fails.
+     * REJECTS with a {@link ReactionError} on every failure. On success `byId[id]`
+     * adopts the host's `viewerReactions`, the truth read back after the write.
+     * When the host's `reacted` differs from the one asked for, a concurrent
+     * change won, and `byId` follows the host.
+     */
+    toggle: (id: number, reaction: BlockAppReaction, reacted: boolean) => Promise<BlockEntityReactionResult>;
+    /** `true` while a `toggle` for this image and reaction is in flight. */
+    pending: (id: number, reaction: BlockAppReaction) => boolean;
+}
+/**
+ * Read and set the VIEWER'S reactions on images this app was served, through
+ * the host's `GET_ENTITY_REACTIONS` and `SET_ENTITY_REACTION` bridge (scope
+ * `social:react:self`).
+ *
+ * A reaction made here is a reaction on civitai.com: it pays the reactor and
+ * the image owner exactly as the site's own button does, moves the image's
+ * rankings, notifies, and lists the viewer among the image's reactors. It draws
+ * on the SAME per-viewer quota as the site.
+ *
+ * 🔴 THE SCOPE IS CONSENT-GATED AND SENSITIVE. Declare `social:react:self` in
+ * the manifest with a `scopeJustifications` entry; until the viewer grants it,
+ * every call rejects with `needs-consent` (`.needsConsent`), which is the cue
+ * for `useRequestConsent()`. There is no per-tap confirm.
+ *
+ * Reads `ids` on mount in chunks of 100, then reads only what needs it: an id
+ * added to `ids`, or one whose ticket changed. Changing `entityType` re-reads
+ * nothing (image is the only type the host accepts today). After a write fails,
+ * an image is read again if the write timed out or the image has no state.
+ *
+ * @example
+ * const { byId, toggle, pending } = useReactions('image', images.map((i) => i.id), {
+ *   tickets: Object.fromEntries(images.map((i) => [i.id, i.reactTicket])),
+ * });
+ */
+export declare function useReactions(entityType: BlockReactionEntityType, ids: readonly number[], options: UseReactionsOptions): UseReactions;
+//# sourceMappingURL=useReactions.d.ts.map