@civitai/blocks-react 0.65.2 → 0.67.0

package/README.md

@@ -106,7 +106,7 @@ the package's type declarations (IDE hover / autocomplete on the package root) a
 the authoritative list of what exists.
 
 Exported from the package root with no snippet in this section, as of this
-writing: `useGatedImages()`, `usePublishGenerationOutputs()`, `useSaveImage()`,
+writing: `useGatedImages()`, `usePublishGenerationOutputs()`,
 `useTip()` and `useTipAllowance()` — for the tip pair, the
 [`TipButton`](#the-ui-subexport) row documents the intended usage and the
 allowance-sharing rule. `useDirectLoad()` is covered under
@@ -687,7 +687,8 @@ publish another.
 
 🔴 **No arm of `sources` takes a URL.** Name a workflow from this app's own
 subqueue plus indexes into its outputs, or `Image` ids from a previous
-`usePublishGenerationOutputs()` publish. The server re-verifies both — ownership,
+`usePublishGenerationOutputs()` publish or `useUploadImageBytes()` upload. The
+server re-verifies both — ownership,
 this app's provenance marker, and that the image is not already in a post.
 
 ⚠️ **Posting a published image removes it from this app's own grid.** The
@@ -1208,6 +1209,173 @@ if (img) {
 }
 ```
 
+### `useUploadImageBytes()`
+
+Upload an image the block **produced in the tab** (a healed PNG, an edited
+render), with no picker, so the app can then post it. Returns `{ upload }`.
+`upload(bytes, { filename? })` resolves with the same moderated image a picked
+`useImageUpload()` upload returns (`imageId`, `nsfwLevel`, `contentRating`,
+`url`). That `imageId` is postable by this app through
+`useCreatePostFromApp()` as a `{ kind: 'published', imageIds }` source.
+
+- 🔴 **Page apps only.** A slot (model) block's host has no handler for it. The
+  host answers an unhandled request at once with its generic refusal, so on a
+  slot `upload` rejects immediately with `unsupported on this host` rather than
+  waiting out the 10-minute timeout.
+- 🔴 **Requires `posts:write:self`.** The server refuses the upload without
+  it, and this hook does not prompt. Ask for the scope first with
+  `useRequestConsent()` and upload only once `useBlockToken().scopes` holds it
+  (the example below), because the upload runs before the `createPost()` call
+  that would otherwise prompt.
+- **Images only:** PNG, WebP or JPEG by magic bytes. Anything else is refused
+  with `file type is not allowed`. The host names the stored file from the
+  sniffed type, whatever `filename` says.
+- **The cap is 40 MiB.** The hook refuses a larger buffer before sending it,
+  with the host's error `file exceeds the maximum upload size`. The host also
+  allows at most 3 uploads and 80 MiB per 60 seconds per page, and replies
+  `busy` past that.
+- **The upload is blocking.** The host replies once the image is scanned, so
+  allow for a wait of up to a few minutes. An image above the SFW ceiling or
+  flagged by the scan is refused with the scan's message.
+- Pass an `ArrayBuffer` (`await blob.arrayBuffer()`). A `Blob`, a
+  `Uint8Array` or an empty buffer is refused with
+  `invalid image-upload request`. The buffer is copied, not transferred.
+
+`upload` **rejects** with the host's error string on every refusal: the ones
+above, `no block token`, or a server message passed through verbatim (the
+missing scope, the posting flag, page-only, a rate limit, the scan). It
+rejects with `the host returned no uploaded image` if the reply carries
+neither an image nor an error. If no reply arrives within 10 minutes it
+rejects with a `RequestTimeoutError`; the host may still have stored the
+image, so retrying after a timeout can create a duplicate.
+
+🔴 **A host that predates this variant ignores `bytes` and opens its upload
+picker instead**, so the call settles on whatever the viewer picks. The hook
+needs civitai/civitai#5639 merged and deployed to civitai.com. That PR is still
+changing, so no intermediate head of it is enough. Do not ship a block that
+relies on `useUploadImageBytes()` before then.
+
+```tsx
+import {
+  CreatePostError,
+  useBlockToken,
+  useCreatePostFromApp,
+  useRequestConsent,
+  useUploadImageBytes,
+} from '@civitai/blocks-react';
+
+function PostHealedButton({ healed }: { healed: Blob }) {
+  const { scopes } = useBlockToken();
+  const { requestConsent } = useRequestConsent();
+  const { upload } = useUploadImageBytes();
+  const { createPost } = useCreatePostFromApp();
+  const canPost = scopes.includes('posts:write:self');
+
+  async function onClick() {
+    if (!canPost) {
+      // Fire-and-forget: this opens the host's consent dialog and returns
+      // nothing. On a grant the host pushes a new token, `scopes` updates and
+      // the button re-renders as "Post". Never upload before that: the server
+      // refuses the upload without the scope.
+      requestConsent({ scopes: ['posts:write:self'] });
+      return;
+    }
+    try {
+      // 1. Bytes made in the tab, uploaded and scanned by the host.
+      const image = await upload(await healed.arrayBuffer(), { filename: 'healed.png' });
+      // 2. Posted through the existing bridge, with its own confirm.
+      const post = await createPost({
+        sources: [{ kind: 'published', imageIds: [image.imageId] }],
+        title: 'Fixed with Metadata Healer',
+      });
+      showToast(`Posted! ${post.url}`);
+    } catch (err) {
+      if (err instanceof CreatePostError && err.declined) return; // the viewer said no
+      showToast((err as Error).message); // e.g. 'busy', 'file type is not allowed'
+    }
+  }
+
+  return <button onClick={onClick}>{canPost ? 'Post' : 'Allow posting'}</button>;
+}
+```
+
+Under `createMockHost` / `Harness` the host's checks run in the host's order:
+the cap, then the window, then the type. `uploadImageBytesResult` sets the
+image an accepted upload returns, `uploadImageBytesError` forces a refusal
+(for example `block lacks posts:write:self scope`), and `onUploadImageBytes`
+reports what was accepted. The mock's `CREATE_POST_FROM_APP` checks a
+`published` source with the server's rule and refusal strings, but not its
+data. Production accepts the viewer's own images that this app stamped and that
+are not in a post yet, including ones from earlier sessions. The mock has no
+earlier sessions, so it accepts only ids it issued as postable in this session
+(an accepted bytes upload, or a `PUBLISH_GENERATION_OUTPUTS` reply) plus the
+ids you seed with `createMockHost({ postableImageIds: [...] })`, each in one
+post only. Any other id, a picked `useImageUpload()` id (production leaves it
+unstamped) or an already-posted id is refused with
+`an image is not available to post`. The mock does not model the page-only
+rule, the scope check, the real scan, or an older host's picker. `dev:live` has
+no bytes path: `upload` rejects with `the host returned no uploaded image`.
+
+### `useSaveImage()`
+
+Ask the host to download a file to the viewer's device. **A block cannot
+download anything itself.** Its sandbox lacks `allow-downloads`, and the
+validator refuses that token for unverified blocks, so an
+`<a href="blob:…" download>` click silently does nothing. 🔴 **This hook is the
+sanctioned way to deliver a file**, including one the block produced in the tab.
+Pass exactly ONE of three inputs, each gated differently by the host:
+
+- **`{ url }`**: the block's own generation output. The host allowlists the
+  origin to the civitai image CDN and refuses any other.
+- **`{ imageId }`**: an image from another user, read through the same
+  per-viewer gate as `useGatedImages()`. A withheld image is never saved.
+- **`{ bytes }`**: an `ArrayBuffer` the block made in the tab, such as a healed
+  image or a JSON sidecar. 🔴 **Page apps only.** The host classifies it by
+  CONTENT. It accepts PNG, WebP and JPEG by magic bytes. Anything else must be
+  valid UTF-8 with no NUL byte: it is saved as JSON when it parses and
+  `filename` ends `.json` (any case) once the host has replaced each `?` and
+  `#` with `_`, and as plain text otherwise. A GIF, a zip
+  or other binary is refused with `file type is not allowed`. The host forces
+  the extension from the classified type. The cap is 50 MiB, and the hook
+  refuses a larger buffer before sending it: `file exceeds the maximum save
+  size`. The buffer is copied, not transferred, so you can keep displaying it.
+
+🔴 **On a host that predates the `bytes` variant, `saveImage({ bytes })` rejects
+with `invalid save-image request`.** The host also replies that when the input
+is not exactly one variant, or when `bytes` is empty or not an `ArrayBuffer`.
+Pass `await blob.arrayBuffer()`, not the `Blob` or a `Uint8Array`. The promise
+resolves once the host has started the download. On any refusal it rejects with
+the host's error string, which can also be `busy` when too many saves are in
+flight.
+
+```tsx
+import { useSaveImage } from '@civitai/blocks-react';
+
+const { saveImage } = useSaveImage();
+
+// A file healed in the tab. It never leaves the device except to the viewer's disk.
+const healed: Blob = await healPngMetadata(file);
+await saveImage({ bytes: await healed.arrayBuffer(), filename: 'healed.png' });
+
+// Its JSON sidecar. The .json filename makes valid JSON save as .json rather than .txt.
+const sidecar = new TextEncoder().encode(JSON.stringify(metadata, null, 2));
+try {
+  await saveImage({ bytes: sidecar.slice().buffer, filename: 'healed.json' });
+} catch (err) {
+  // 'invalid save-image request' here means this host cannot save bytes yet.
+  setStatus(`Could not save the sidecar: ${(err as Error).message}`);
+}
+
+// The block's own generation output, or another user's image.
+await saveImage({ url: output.url, filename: 'render.png' });
+await saveImage({ imageId: cell.imageId });
+```
+
+Under `createMockHost` / `Harness` the `bytes` variant is classified the same
+way. `onSaveBytes` reports what would have been downloaded, and `saveImageError`
+forces a refusal. Pass `saveImageError: 'invalid save-image request'` to test a
+host without the variant. `dev:live` refuses every save.
+
 ### `useGenerationResources()`
 
 Rehydrate a saved set of generation resources by version id — WITHOUT re-opening

package/dist/hooks/useCreatePostFromApp.d.ts

@@ -113,7 +113,8 @@ export interface UseCreatePostFromApp {
  *
  * 🔴 NO ARM OF `sources` TAKES A URL. Name a workflow from this app's own
  * subqueue plus indexes into its outputs, or `Image` ids from a previous
- * `usePublishGenerationOutputs()` publish. The server re-verifies both.
+ * `usePublishGenerationOutputs()` publish or `useUploadImageBytes()` upload.
+ * The server re-verifies both.
  *
  * ⚠️ POSTING A PUBLISHED IMAGE REMOVES IT FROM THIS APP'S OWN GRID. The
  * app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`,

package/dist/hooks/useCreatePostFromApp.js

@@ -121,7 +121,8 @@ export class CreatePostError extends Error {
  *
  * 🔴 NO ARM OF `sources` TAKES A URL. Name a workflow from this app's own
  * subqueue plus indexes into its outputs, or `Image` ids from a previous
- * `usePublishGenerationOutputs()` publish. The server re-verifies both.
+ * `usePublishGenerationOutputs()` publish or `useUploadImageBytes()` upload.
+ * The server re-verifies both.
  *
  * ⚠️ POSTING A PUBLISHED IMAGE REMOVES IT FROM THIS APP'S OWN GRID. The
  * app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`,

package/dist/hooks/useSaveImage.d.ts

@@ -1,6 +1,7 @@
 /**
- * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` is
- * required — the two variants map to the host's two download paths:
+ * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` /
+ * `bytes` is required — the three variants map to the host's three download
+ * paths, each with its own security gate:
  *
  *  - `{ url }` — the block's OWN fresh output (e.g. an orchestration blob it has
  *    no `imageId` for yet). The host ALLOWLISTS the URL's origin to the civitai
@@ -9,32 +10,70 @@
  *  - `{ imageId }` — a cross-user grid image (e.g. a benchmark cell). The host
  *    resolves it through the SAME per-viewer gated read that backs
  *    `useGatedImages()`, so a withheld/above-ceiling image can never be saved.
+ *  - `{ bytes }` — a file the block PRODUCED IN THE VIEWER'S TAB (a healed
+ *    image, a JSON sidecar, a text export) that exists nowhere else. 🔴 **This
+ *    is the sanctioned way for an in-tab tool to deliver a file.** A blob-anchor
+ *    `<a download>` does nothing in a block — its sandbox lacks
+ *    `allow-downloads`, and the validator refuses that token for unverified
+ *    blocks — so do not build one. 🔴 **Page apps only**: a slot (model) block's
+ *    host has no `SAVE_IMAGE` handler, so its generic unhandled-request reply
+ *    answers at once and the call rejects with `unsupported on this host`.
+ *
+ *    The host classifies by CONTENT and never trusts `filename` to make a file
+ *    acceptable: PNG / WebP / JPEG by magic bytes; otherwise valid UTF-8 with
+ *    no NUL byte, saved as JSON when it parses AND `filename` ends `.json`
+ *    (case-insensitive) after the host replaces each `?` and `#` with `_` (so
+ *    `data.json?v=2` saves as text), else as text/plain. Anything else — a GIF, a zip,
+ *    random binary — is refused with `file type is not allowed`, and an empty
+ *    buffer with `invalid save-image request`. The saved extension is forced
+ *    from the classified type, whatever `filename` says. The cap is 50 MiB of
+ *    raw bytes.
+ *    The buffer is COPIED across `postMessage`, never transferred, so the block
+ *    can keep displaying it.
  */
 export type SaveImageInput = {
     url: string;
     imageId?: never;
+    bytes?: never;
     filename?: string;
 } | {
     imageId: number;
     url?: never;
+    bytes?: never;
+    filename?: string;
+} | {
+    bytes: ArrayBuffer;
+    url?: never;
+    imageId?: never;
     filename?: string;
 };
 export interface UseSaveImage {
     /**
-     * Ask the host to DOWNLOAD an image the block already displays — the host
-     * fetches the blob in its unsandboxed top frame and triggers the browser
-     * "Save As". A sandboxed opaque-origin block lacks `allow-downloads`, so it
-     * otherwise can only copy a URL; this bridge is the only way to save a paid
-     * output. Resolves once the host has started the download; rejects with the
-     * host's error string on failure (a disallowed URL origin, a withheld image,
-     * an over-size blob, or a fetch failure), or the transport timeout — the hook
-     * never hangs.
+     * Ask the host to DOWNLOAD a file — an image the block already displays, or
+     * bytes it produced in the tab — in the host's unsandboxed top frame, which
+     * triggers the browser "Save As". A sandboxed opaque-origin block lacks
+     * `allow-downloads`, so this bridge is the only way a block can save a file.
+     * Resolves once the host has started the download; rejects with the host's
+     * error string on failure (a disallowed URL origin, a withheld image, a
+     * disallowed file type, an over-size file, a fetch failure, or `busy`), or
+     * the transport timeout — the hook never hangs.
+     *
+     * 🔴 One call is refused BEFORE sending, with the host's own string: a
+     * `bytes` buffer over the 50 MiB cap rejects with `file exceeds the maximum
+     * save size`, so it is never copied across `postMessage` just to be refused.
+     * Everything else is forwarded and judged by the host, which replies
+     * `invalid save-image request` to a request that is not exactly one variant,
+     * to a `bytes` that is not a non-empty `ArrayBuffer` (pass
+     * `await blob.arrayBuffer()`, or `view.slice().buffer` for a typed array —
+     * not the `Uint8Array` or `Blob` itself), and, on a host that predates the
+     * `bytes` variant, to every `bytes` save; treat that string as "this host
+     * cannot save bytes yet".
      */
     saveImage: (input: SaveImageInput) => Promise<void>;
 }
 /**
- * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
- * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ * Download a file via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the security posture of each variant.
  *
  * @example
  * const { saveImage } = useSaveImage();
@@ -42,6 +81,8 @@ export interface UseSaveImage {
  * await saveImage({ url: output.url, filename: 'my-render.png' });
  * // a cross-user grid cell (routed through the gated per-viewer read):
  * await saveImage({ imageId: cell.imageId });
+ * // a file produced in the tab (classified by content host-side; page apps only):
+ * await saveImage({ bytes: healedPng, filename: 'healed.png' });
  */
 export declare function useSaveImage(): UseSaveImage;
 //# sourceMappingURL=useSaveImage.d.ts.map

package/dist/hooks/useSaveImage.js

@@ -1,10 +1,36 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 import { throwOnFailedReply } from '../internal/replyError.js';
+import { SAVE_BYTES_MAX_BYTES, SAVE_BYTES_TOO_LARGE_ERROR } from '../internal/saveBytes.js';
 import { sendTypedRequest } from '../transport/transport.js';
 /**
- * Download an image via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
- * bridge. See {@link SaveImageInput} for the url-vs-id security posture.
+ * Build the wire payload. The ONLY client-side refusal is the cap, so an
+ * over-cap buffer is never copied across `postMessage` just to be refused.
+ * Everything else is forwarded as given and the host judges it: a `bytes`
+ * input is sent with whatever `url` / `imageId` came with it (the host refuses
+ * the mix), and a `url` / `imageId` input keeps its pre-`bytes` behaviour
+ * (`url` wins when both are set).
+ */
+function toWirePayload(input) {
+    const raw = input;
+    if (raw.bytes !== undefined) {
+        if (raw.bytes instanceof ArrayBuffer && raw.bytes.byteLength > SAVE_BYTES_MAX_BYTES) {
+            throw new Error(SAVE_BYTES_TOO_LARGE_ERROR);
+        }
+        const payload = { bytes: raw.bytes, filename: raw.filename };
+        if (raw.url !== undefined)
+            payload.url = raw.url;
+        if (raw.imageId !== undefined)
+            payload.imageId = raw.imageId;
+        return payload;
+    }
+    return 'url' in input && input.url !== undefined
+        ? { url: input.url, filename: input.filename }
+        : { imageId: input.imageId, filename: input.filename };
+}
+/**
+ * Download a file via the host-mediated `SAVE_IMAGE` → `SAVE_IMAGE_RESULT`
+ * bridge. See {@link SaveImageInput} for the security posture of each variant.
  *
  * @example
  * const { saveImage } = useSaveImage();
@@ -12,12 +38,12 @@ import { sendTypedRequest } from '../transport/transport.js';
  * await saveImage({ url: output.url, filename: 'my-render.png' });
  * // a cross-user grid cell (routed through the gated per-viewer read):
  * await saveImage({ imageId: cell.imageId });
+ * // a file produced in the tab (classified by content host-side; page apps only):
+ * await saveImage({ bytes: healedPng, filename: 'healed.png' });
  */
 export function useSaveImage() {
     const saveImage = useCallback(async (input) => {
-        const payload = 'url' in input && input.url !== undefined
-            ? { url: input.url, filename: input.filename }
-            : { imageId: input.imageId, filename: input.filename };
+        const payload = toWirePayload(input);
         const reply = await sendTypedRequest(getTransport(), { type: 'SAVE_IMAGE', payload }, 'SAVE_IMAGE_RESULT');
         throwOnFailedReply(reply, 'failed to save image');
     }, []);

package/dist/hooks/useUploadImageBytes.d.ts

@@ -0,0 +1,84 @@
+import type { BlockUploadedImageInfo } from '@civitai/app-sdk/blocks';
+/**
+ * The SDK's own rejection when a reply carries neither an image nor an
+ * `error`. A host that predates the `bytes` variant opens its picker instead,
+ * and a dismissed picker replies this way; so does any reply whose `selected`
+ * is not the moderated `display` shape.
+ */
+export declare const UPLOAD_IMAGE_BYTES_NO_IMAGE_ERROR = "the host returned no uploaded image";
+/** Options for {@link UseUploadImageBytes.upload}. */
+export interface UploadImageBytesOptions {
+    /**
+     * Advisory name for the stored image. The host sanitises it with the same
+     * rules as a `useSaveImage()` bytes name, forces the extension from the
+     * sniffed type, and caps it at 255 characters.
+     */
+    filename?: string;
+}
+/** What {@link useUploadImageBytes} returns. */
+export interface UseUploadImageBytes {
+    /**
+     * Upload an image the block produced in the tab, with no picker, and resolve
+     * with the moderated image: the same {@link BlockUploadedImageInfo} a picked
+     * `useImageUpload()` upload returns. Its `imageId` is postable by THIS app
+     * through `useCreatePostFromApp()` as `{ kind: 'published', imageIds }`.
+     *
+     * REJECTS with the host's error string on every refusal or failure:
+     * `invalid image-upload request` (not a non-empty `ArrayBuffer`),
+     * `file exceeds the maximum upload size`, `file type is not allowed`,
+     * `busy` (the host's rolling window is full; retry later), `no block token`,
+     * or a server message passed through verbatim (a missing `posts:write:self`
+     * scope, the posting flag, page-only, a rate limit, a scan refusal or
+     * timeout), or `unsupported on this host` on a slot (model) host, which has
+     * no handler and answers at once with its generic refusal. Rejects with
+     * `the host returned no uploaded image` when a reply carries neither an image
+     * nor an error.
+     *
+     * 🔴 With NO reply inside the 10-minute bound it rejects with a
+     * `RequestTimeoutError` instead, and the work may have completed: the host
+     * may have stored and scanned the image. Retrying after a timeout can create
+     * a duplicate image.
+     *
+     * 🔴 One call is refused BEFORE sending, with the host's own string: a buffer
+     * over the 40 MiB cap rejects with `file exceeds the maximum upload size`,
+     * so it is never copied across `postMessage` just to be refused.
+     */
+    upload: (bytes: ArrayBuffer, options?: UploadImageBytesOptions) => Promise<BlockUploadedImageInfo>;
+}
+/**
+ * Upload an image the block PRODUCED IN THE VIEWER'S TAB (a healed PNG, an
+ * edited render) through the host's `OPEN_IMAGE_UPLOAD { bytes }` bridge, so
+ * the app can then post it. No picker opens; the host runs the same store
+ * upload → persist → scan pipeline as a picked `display` upload and replies
+ * only once the scan settles.
+ *
+ * - 🔴 **Page apps only** (a slot host rejects at once with
+ *   `unsupported on this host`), and the token needs **`posts:write:self`**
+ *   (the server refuses the persist without it). This hook does not prompt for the
+ *   scope, so ask for it first with `useRequestConsent()`: the upload runs
+ *   before any `useCreatePostFromApp()` call that would otherwise prompt.
+ * - **Images only:** PNG, WebP or JPEG by magic bytes. The cap is 40 MiB, and
+ *   the host also allows at most 3 uploads and 80 MiB per 60 s per page.
+ * - The buffer is COPIED across `postMessage`, never transferred, so the block
+ *   can keep displaying it. Pass an `ArrayBuffer` (`await blob.arrayBuffer()`),
+ *   not a `Blob` or a typed array, which the host refuses.
+ * - 🔴 **A host that predates the variant ignores `bytes` and opens its picker.**
+ *   Then the promise settles on whatever the viewer picks, or rejects with
+ *   `the host returned no uploaded image` on a dismiss. It needs
+ *   civitai/civitai#5639 merged and deployed to civitai.com; that PR is still
+ *   changing, so no intermediate head of it is enough. Do not ship a block
+ *   relying on this before then.
+ *
+ * Under `createMockHost` / `Harness` the host's admission rules are modelled
+ * (see `MockHostOptions.uploadImageBytesResult`). `dev:live` has no bytes
+ * path: it replies dismissed, so `upload` rejects with
+ * `the host returned no uploaded image`.
+ *
+ * @example
+ * const { upload } = useUploadImageBytes();
+ * const { createPost } = useCreatePostFromApp();
+ * const image = await upload(await healed.arrayBuffer(), { filename: 'healed.png' });
+ * await createPost({ sources: [{ kind: 'published', imageIds: [image.imageId] }] });
+ */
+export declare function useUploadImageBytes(): UseUploadImageBytes;
+//# sourceMappingURL=useUploadImageBytes.d.ts.map

package/dist/hooks/useUploadImageBytes.js

@@ -0,0 +1,77 @@
+import { useCallback } from 'react';
+import { throwOnReplyError } from '../internal/replyError.js';
+import { UPLOAD_BYTES_MAX_BYTES, UPLOAD_BYTES_TOO_LARGE_ERROR } from '../internal/uploadBytes.js';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
+import { getTransport } from '../transport/singleton.js';
+import { sendTypedRequest } from '../transport/transport.js';
+/**
+ * The SDK's own rejection when a reply carries neither an image nor an
+ * `error`. A host that predates the `bytes` variant opens its picker instead,
+ * and a dismissed picker replies this way; so does any reply whose `selected`
+ * is not the moderated `display` shape.
+ */
+export const UPLOAD_IMAGE_BYTES_NO_IMAGE_ERROR = 'the host returned no uploaded image';
+/**
+ * Upload an image the block PRODUCED IN THE VIEWER'S TAB (a healed PNG, an
+ * edited render) through the host's `OPEN_IMAGE_UPLOAD { bytes }` bridge, so
+ * the app can then post it. No picker opens; the host runs the same store
+ * upload → persist → scan pipeline as a picked `display` upload and replies
+ * only once the scan settles.
+ *
+ * - 🔴 **Page apps only** (a slot host rejects at once with
+ *   `unsupported on this host`), and the token needs **`posts:write:self`**
+ *   (the server refuses the persist without it). This hook does not prompt for the
+ *   scope, so ask for it first with `useRequestConsent()`: the upload runs
+ *   before any `useCreatePostFromApp()` call that would otherwise prompt.
+ * - **Images only:** PNG, WebP or JPEG by magic bytes. The cap is 40 MiB, and
+ *   the host also allows at most 3 uploads and 80 MiB per 60 s per page.
+ * - The buffer is COPIED across `postMessage`, never transferred, so the block
+ *   can keep displaying it. Pass an `ArrayBuffer` (`await blob.arrayBuffer()`),
+ *   not a `Blob` or a typed array, which the host refuses.
+ * - 🔴 **A host that predates the variant ignores `bytes` and opens its picker.**
+ *   Then the promise settles on whatever the viewer picks, or rejects with
+ *   `the host returned no uploaded image` on a dismiss. It needs
+ *   civitai/civitai#5639 merged and deployed to civitai.com; that PR is still
+ *   changing, so no intermediate head of it is enough. Do not ship a block
+ *   relying on this before then.
+ *
+ * Under `createMockHost` / `Harness` the host's admission rules are modelled
+ * (see `MockHostOptions.uploadImageBytesResult`). `dev:live` has no bytes
+ * path: it replies dismissed, so `upload` rejects with
+ * `the host returned no uploaded image`.
+ *
+ * @example
+ * const { upload } = useUploadImageBytes();
+ * const { createPost } = useCreatePostFromApp();
+ * const image = await upload(await healed.arrayBuffer(), { filename: 'healed.png' });
+ * await createPost({ sources: [{ kind: 'published', imageIds: [image.imageId] }] });
+ */
+export function useUploadImageBytes() {
+    const upload = useCallback(async (bytes, options) => {
+        // The ONLY client-side refusal, mirroring `useSaveImage`'s cap pre-check:
+        // everything else is forwarded and judged by the host.
+        if (bytes instanceof ArrayBuffer && bytes.byteLength > UPLOAD_BYTES_MAX_BYTES) {
+            throw new Error(UPLOAD_BYTES_TOO_LARGE_ERROR);
+        }
+        const reply = await sendTypedRequest(getTransport(), {
+            type: 'OPEN_IMAGE_UPLOAD',
+            payload: {
+                bytes,
+                ...(options?.filename !== undefined ? { filename: options.filename } : {}),
+            },
+        }, 'IMAGE_UPLOAD_RESULT', 
+        // `OPEN_IMAGE_UPLOAD` is bucketed `'human'` (transport/requestTimeouts.ts),
+        // and this variant needs the long bound too: the host replies only after
+        // the store upload, the persist and a scan poll of up to three minutes,
+        // and a host that predates `bytes` opens a picker a person must close.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+        // No `ok` on this reply, so the presence-based helper (internal/replyError.ts).
+        throwOnReplyError(reply, 'image upload failed');
+        const selected = reply.selected;
+        if (selected && !('status' in selected) && 'imageId' in selected)
+            return selected;
+        throw new Error(UPLOAD_IMAGE_BYTES_NO_IMAGE_ERROR);
+    }, []);
+    return { upload };
+}
+//# sourceMappingURL=useUploadImageBytes.js.map

package/dist/index.d.ts

@@ -78,6 +78,8 @@ export { useResourcePicker } from './hooks/useResourcePicker.js';
 export type { UseResourcePicker } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
 export type { UseImageUpload, UseImageUploadAsyncScan, UseImageUploadGenerationSource, UseImageUploadOptions, } from './hooks/useImageUpload.js';
+export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
+export type { UploadImageBytesOptions, UseUploadImageBytes, } from './hooks/useUploadImageBytes.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export type { UseGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';

package/dist/index.js

@@ -64,6 +64,7 @@ export { useRunTraining, RunTrainingError, RUN_TRAINING_ERROR_CODES, isRunTraini
 export { useCheckpointPicker } from './hooks/useCheckpointPicker.js';
 export { useResourcePicker } from './hooks/useResourcePicker.js';
 export { useImageUpload } from './hooks/useImageUpload.js';
+export { useUploadImageBytes } from './hooks/useUploadImageBytes.js';
 export { useGenerationResources } from './hooks/useGenerationResources.js';
 export { GENERATION_RESOURCES_API_BASE, MAX_GENERATION_RESOURCE_IDS, buildGenerationResourcesUrl, responseToResources, } from './api/generationResources.js';
 export { useCivitaiNavigate } from './hooks/useCivitaiNavigate.js';

package/dist/internal/liveHost.js

@@ -1174,9 +1174,21 @@ export function createLiveHost(options) {
                         // the hook resolves to `null`) and log an actionable message. Honest-
                         // by-design — never fabricate a moderated image id. Mirrors the
                         // OPEN_BUZZ_PURCHASE "no headless contract" pattern.
-                        logOnce('open-image-upload', 'OPEN_IMAGE_UPLOAD received but live dev mode cannot serve the native upload ' +
-                            'modal — resolving the upload as dismissed (null). Test the image-upload flow ' +
-                            'against the real site, or use createMockHost({ cannedImageUpload }) in dev:mock.');
+                        //
+                        // The `bytes` variant (`useUploadImageBytes()`) gets the same reply,
+                        // but that hook has no "dismissed" outcome: it REJECTS with its
+                        // no-image error. So it gets its own message, naming its mock option.
+                        if (typed.payload != null && 'bytes' in typed.payload) {
+                            logOnce('open-image-upload-bytes', 'OPEN_IMAGE_UPLOAD { bytes } received but live dev mode has no bytes upload path — ' +
+                                'useUploadImageBytes().upload() REJECTS with "the host returned no uploaded image". ' +
+                                'Test the bytes upload against the real site, or use ' +
+                                'createMockHost({ uploadImageBytesResult }) in dev:mock.');
+                        }
+                        else {
+                            logOnce('open-image-upload', 'OPEN_IMAGE_UPLOAD received but live dev mode cannot serve the native upload ' +
+                                'modal — resolving the upload as dismissed (null). Test the image-upload flow ' +
+                                'against the real site, or use createMockHost({ cannedImageUpload }) in dev:mock.');
+                        }
                         dispatchToBlock({
                             type: 'IMAGE_UPLOAD_RESULT',
                             payload: { requestId: requestId ?? '' },
@@ -1640,8 +1652,14 @@ export function createLiveHost(options) {
                         //   • `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.
+                        //   • `bytes` (#583) — refused here too. Its gate (content
+                        //     classification, the cap) is reproducible, and `createMockHost`
+                        //     reproduces it; but a dev:live "download" would be this
+                        //     harness's tab saving a file, which proves nothing about the
+                        //     production host's page-only rule or its top-frame download.
+                        //     One honest refusal for every variant keeps this branch simple.
                         //
-                        // This harness has NEITHER gate. The allowlist is the production
+                        // This harness has NEITHER of the url / imageId gates. 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