@civitai/blocks-react 0.36.1 → 0.38.0

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,7 +1,18 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
+/** Optional per-submit controls. */
+export interface SubmitWorkflowOptions {
+    /**
+     * A STABLE idempotency key for this logical submit. Reuse the SAME value when
+     * RETRYING a submit whose response was lost (timeout / network drop) so the
+     * host+orchestrator collapse it to ONE Buzz charge instead of double-charging.
+     * Omit → the hook generates a fresh key per `submit()` call (each call is a new
+     * logical submit); pass a stable id (e.g. a grid-cell id) to make a retry safe.
+     */
+    idempotencyKey?: string;
+}
 interface UseBuzzWorkflowReturn {
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
-    submit: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
+    submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     poll: (workflowId: string) => Promise<BlockWorkflowSnapshot>;
     /**
      * Cancel a running workflow on the orchestrator (a real server-side stop,

package/dist/hooks/useBuzzWorkflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BnG,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CAuFvD"}
+{"version":3,"file":"useBuzzWorkflow.d.ts","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AA8BnG,oCAAoC;AACpC,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,qBAAqB;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACjE,MAAM,EAAE,CACN,IAAI,EAAE,YAAY,EAClB,OAAO,CAAC,EAAE,qBAAqB,KAC5B,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7D;;;;;;OAMG;IACH,MAAM,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC/D,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACrC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,eAAe,IAAI,qBAAqB,CA0FvD"}

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,6 @@
 import { useCallback, useState } from 'react';
 import { getTransport } from '../internal/singleton.js';
-import { sendTypedRequest } from '../internal/transport.js';
+import { generateIdempotencyKey, sendTypedRequest } from '../internal/transport.js';
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -78,11 +78,14 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
-    const submit = useCallback(async (body) => {
+    const submit = useCallback(async (body, options) => {
         setError(null);
         setStatus('submitting');
+        // Idempotency: reuse a caller-supplied stable key across a retry (→ one Buzz
+        // charge), or mint a fresh one per call (each call is a new logical submit).
+        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
         try {
-            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
             setResult(snapshot);
             setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
             return snapshot;

package/dist/hooks/useBuzzWorkflow.js.map

@@ -1 +1 @@
-{"version":3,"file":"useBuzzWorkflow.js","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useBuzzWorkflow.js","sourceRoot":"","sources":["../../src/hooks/useBuzzWorkflow.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useSaveImage.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Input to {@link UseSaveImage.saveImage}. Exactly ONE of `url` / `imageId` is
+ * required — the two variants map to the host's two download paths:
+ *
+ *  - `{ 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
+ *    image/blob CDN and refuses an arbitrary host — a sandboxed block can't
+ *    coerce a host-side fetch of an attacker origin.
+ *  - `{ 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.
+ */
+export type SaveImageInput = {
+    url: string;
+    imageId?: never;
+    filename?: string;
+} | {
+    imageId: number;
+    url?: 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.
+     */
+    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.
+ *
+ * @example
+ * const { saveImage } = useSaveImage();
+ * // block's own generation output (origin-allowlisted host-side):
+ * 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 });
+ */
+export declare function useSaveImage(): UseSaveImage;
+//# sourceMappingURL=useSaveImage.d.ts.map

package/dist/hooks/useSaveImage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSaveImage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSaveImage.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExD,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,YAAY,CAiB3C"}

package/dist/hooks/useSaveImage.js

@@ -0,0 +1,27 @@
+import { useCallback } from 'react';
+import { getTransport } from '../internal/singleton.js';
+import { sendTypedRequest } from '../internal/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.
+ *
+ * @example
+ * const { saveImage } = useSaveImage();
+ * // block's own generation output (origin-allowlisted host-side):
+ * 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 });
+ */
+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 reply = await sendTypedRequest(getTransport(), { type: 'SAVE_IMAGE', payload }, 'SAVE_IMAGE_RESULT');
+        if (!reply.ok || reply.error) {
+            throw new Error(reply.error ?? 'failed to save image');
+        }
+    }, []);
+    return { saveImage };
+}
+//# sourceMappingURL=useSaveImage.js.map

package/dist/hooks/useSaveImage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSaveImage.js","sourceRoot":"","sources":["../../src/hooks/useSaveImage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAgC5D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,EAAE,KAAqB,EAAiB,EAAE;QAC3E,MAAM,OAAO,GACX,KAAK,IAAI,KAAK,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;YACvC,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE;YAC9C,CAAC,CAAC,EAAE,OAAO,EAAG,KAA6B,CAAC,OAAO,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC;QACpF,MAAM,KAAK,GAAG,MAAM,gBAAgB,CAClC,YAAY,EAAE,EACd,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,EAC/B,mBAAmB,CACpB,CAAC;QACF,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,KAAK,CAAC,KAAK,IAAI,sBAAsB,CAAC,CAAC;QACzD,CAAC;IACH,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/hooks/useSharedStorage.d.ts

@@ -20,6 +20,14 @@ export interface SharedListItem {
     count: number;
     createdAt: Date;
     updatedAt: Date;
+    /**
+     * Whether the current viewer has an active up-vote on this entry — hydrate the
+     * vote-button state from this on load instead of guessing (fixes the
+     * "double-click to unvote" bug). Anonymous viewers are always `false`. Defaults
+     * to `false` when talking to an older host that doesn't send it, so a new block
+     * on an old host degrades to today's behavior.
+     */
+    viewerVoted: boolean;
 }
 export interface SharedListResult {
     items: SharedListItem[];
@@ -36,6 +44,24 @@ export interface UseSharedStorage {
         limit?: number;
         cursor?: string;
     }): Promise<SharedListResult>;
+    /**
+     * Fetch ONE entry by its key — the single-row companion to {@link list} for
+     * resolving a `?g=<key>` deep-link to an item past the first page. Resolves
+     * with the full {@link SharedListItem} (incl. `count`/`viewerVoted`) or `null`
+     * when the key is missing / hidden (a withdrawn or moderated row is never
+     * leaked). Respects the same per-viewer visibility as `list`. Rejects with the
+     * host's `error` string on host-side failure.
+     */
+    get(key: string): Promise<SharedListItem | null>;
+    /**
+     * Report a posted entry for moderator review — the post-write abuse seam for a
+     * shared board. `reason` is optional free text. Resolves once the report is
+     * filed; rejects with the host's `error` string on failure (`NOT_FOUND` for a
+     * missing key, a trust/scope rejection, or when the viewer is anonymous).
+     * Filing a report does not hide the row — a moderator decides. Gated by the
+     * same `apps:storage:shared:write` trust boundary as {@link append}.
+     */
+    report(key: string, reason?: string): Promise<void>;
     /** Current vote total for a single entry (`0` when the key isn't present). */
     getCount(key: string): Promise<number>;
     /**
@@ -83,30 +109,5 @@ export interface UseSharedStorage {
         deleted: boolean;
     }>;
 }
-/**
- * App-scoped, append-only, community-votable SHARED datastore. Sibling of
- * {@link useAppStorage} (the per-viewer KV store) — same postMessage bridge,
- * same request/await/correlate-by-requestId mechanism — but the scope is the
- * APP (every viewer sees the same list) and entries are structured
- * `{ title, body? }` records that any viewer can vote on.
- *
- * Calls flow through the host's postMessage bridge; the block never sees the
- * datastore credentials and never sends its block token (the host injects both
- * the token and the viewer identity). Anonymous viewers get a read path (`list`
- * / `getCount(s)`) and a hard reject on mutations (`append`/`vote`/`unvote`/
- * `withdraw`).
- *
- * The hook is stable across renders — it returns the same object identity once
- * the transport singleton is created, so it's safe in `useEffect`/`useMemo`
- * dependency arrays.
- *
- * @example
- * const shared = useSharedStorage();
- * const { key } = await shared.append({ title: 'Add dark mode', body: '…' });
- * const { items } = await shared.list({ limit: 20 });   // newest-first
- * const count = await shared.vote(key);                 // idempotent up-vote
- * await shared.unvote(key);
- * await shared.withdraw(key);                            // remove my own entry
- */
 export declare function useSharedStorage(): UseSharedStorage;
 //# sourceMappingURL=useSharedStorage.d.ts.map

package/dist/hooks/useSharedStorage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSharedStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAKlE;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,IAAI,gBAAgB,CAkGnD"}
+{"version":3,"file":"useSharedStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAyB,MAAM,yBAAyB,CAAC;AAKzF;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,kBAAkB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB;;;;;;OAMG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE;QACV,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAC9B;;;;;;;OAOG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACjD;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3D;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3D;;;;;;;;;OASG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7D;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC;;;OAGG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrC;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACnE;AA8CD,wBAAgB,gBAAgB,IAAI,gBAAgB,CA8GnD"}

package/dist/hooks/useSharedStorage.js

@@ -26,6 +26,24 @@ import { sendTypedRequest } from '../internal/transport.js';
  * await shared.unvote(key);
  * await shared.withdraw(key);                            // remove my own entry
  */
+/**
+ * Rehydrate one wire item (ISO date strings) into a public {@link SharedListItem}
+ * (`Date`s). `viewerVoted` defaults to `false` when a host predating the field
+ * omits it, so a new block on an old host degrades to today's behavior. Shared by
+ * {@link UseSharedStorage.list} and {@link UseSharedStorage.get} so the two stay
+ * in lockstep.
+ */
+function rehydrateSharedItem(item) {
+    return {
+        key: item.key,
+        authorUserId: item.authorUserId,
+        value: item.value,
+        count: item.count,
+        createdAt: new Date(item.createdAt),
+        updatedAt: new Date(item.updatedAt),
+        viewerVoted: item.viewerVoted ?? false,
+    };
+}
 export function useSharedStorage() {
     return useMemo(() => {
         const transport = getTransport();
@@ -42,17 +60,22 @@ export function useSharedStorage() {
                 if (result.error)
                     throw new Error(result.error);
                 return {
-                    items: result.items.map((item) => ({
-                        key: item.key,
-                        authorUserId: item.authorUserId,
-                        value: item.value,
-                        count: item.count,
-                        createdAt: new Date(item.createdAt),
-                        updatedAt: new Date(item.updatedAt),
-                    })),
+                    items: result.items.map(rehydrateSharedItem),
                     nextCursor: result.nextCursor,
                 };
             },
+            async get(key) {
+                const result = await sendTypedRequest(transport, { type: 'SHARED_GET', payload: { key } }, 'SHARED_GET_RESULT');
+                if (result.error)
+                    throw new Error(result.error);
+                return result.item ? rehydrateSharedItem(result.item) : null;
+            },
+            async report(key, reason) {
+                const result = await sendTypedRequest(transport, { type: 'SHARED_REPORT', payload: { key, reason } }, 'SHARED_REPORT_RESULT');
+                if (!result.ok || result.error) {
+                    throw new Error(result.error ?? 'shared report failed');
+                }
+            },
             async getCount(key) {
                 const result = await sendTypedRequest(transport, { type: 'SHARED_GET_COUNT', payload: { key } }, 'SHARED_GET_COUNT_RESULT');
                 if (result.error)

package/dist/hooks/useSharedStorage.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSharedStorage.js","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSharedStorage.js","sourceRoot":"","sources":["../../src/hooks/useSharedStorage.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useTip.d.ts

@@ -0,0 +1,62 @@
+/** The tip target + amount. `entityType`/`entityId` are optional context. */
+export interface TipParams {
+    toUserId: number;
+    amount: number;
+    entityType?: 'Image' | 'Collection' | 'User';
+    entityId?: number;
+}
+/** Optional per-tip controls. */
+export interface TipOptions {
+    /**
+     * A STABLE idempotency key for this logical tip. Reuse the SAME value when
+     * RETRYING a tip whose response was lost (timeout / network drop) so the host
+     * collapses it to ONE transfer instead of DOUBLE-TIPPING. Omit → the hook mints
+     * a fresh key per `tip()` call (each call is a new logical tip).
+     */
+    idempotencyKey?: string;
+}
+/** The successful tip echo the endpoint returns. */
+export interface TipResult {
+    ok: true;
+    tip: {
+        toUserId: number;
+        amount: number;
+        entityType: string | null;
+        entityId: number | null;
+    };
+}
+export interface UseTip {
+    /**
+     * Send a Buzz tip from the viewer to `toUserId`. Resolves with the server's
+     * echo on success; REJECTS with an `Error` (carrying the server message) on any
+     * 4xx/5xx — including a `409` if a tip with the same idempotency key is still in
+     * flight. A lost-response retry with the SAME `options.idempotencyKey` is
+     * collapsed server-side to the first result (no double-tip).
+     */
+    tip: (params: TipParams, options?: TipOptions) => Promise<TipResult>;
+    /** `true` while a tip POST is in flight. */
+    loading: boolean;
+    /** The last tip's failure, or `null`. Cleared at the start of the next `tip()`. */
+    error: Error | null;
+}
+/**
+ * Send a Buzz TIP from the viewer through the block-token-gated
+ * `POST /api/v1/blocks/tip` REST endpoint (scope `social:tip:self`).
+ *
+ * Direct-fetch (bypasses the postMessage bridge) against the VALIDATED host
+ * origin (`useHostOrigin()`) with the block bearer token (`useBlockToken().raw`)
+ * — the same security-reviewed pattern as {@link useGenerationResources}. The
+ * SENDER is always the token subject (server self-binds it); the block never
+ * supplies a `fromUserId`.
+ *
+ * IDEMPOTENCY: pass a stable `options.idempotencyKey` to make a retry-after-
+ * timeout safe (the server replays the first terminal result). Omitting it mints
+ * a fresh key per call, so each call is a distinct logical tip.
+ *
+ * @example
+ * const { tip, loading, error } = useTip();
+ * const key = React.useId(); // stable across this component's retries
+ * await tip({ toUserId: 123, amount: 50, entityType: 'Image', entityId: 99 }, { idempotencyKey: key });
+ */
+export declare function useTip(): UseTip;
+//# sourceMappingURL=useTip.d.ts.map

package/dist/hooks/useTip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTip.d.ts","sourceRoot":"","sources":["../../src/hooks/useTip.ts"],"names":[],"mappings":"AAaA,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,GAAG,YAAY,GAAG,MAAM,CAAC;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,oDAAoD;AACpD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,IAAI,CAAC;IACT,GAAG,EAAE;QACH,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,CAAC;CACH;AAED,MAAM,WAAW,MAAM;IACrB;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,UAAU,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACrE,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAwE/B"}

package/dist/hooks/useTip.js

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useHostOrigin } from './useHostOrigin.js';
+import { useBlockToken } from './useBlockToken.js';
+import { generateIdempotencyKey } from '../internal/transport.js';
+/**
+ * Backstop timeout for the direct REST tip POST. Like {@link useGenerationResources}
+ * (and unlike the postMessage hooks), this talks to the HTTP API directly, so it
+ * needs its OWN bound — otherwise a hung request never rejects.
+ */
+const TIP_REQUEST_TIMEOUT_MS = 30_000;
+/**
+ * Send a Buzz TIP from the viewer through the block-token-gated
+ * `POST /api/v1/blocks/tip` REST endpoint (scope `social:tip:self`).
+ *
+ * Direct-fetch (bypasses the postMessage bridge) against the VALIDATED host
+ * origin (`useHostOrigin()`) with the block bearer token (`useBlockToken().raw`)
+ * — the same security-reviewed pattern as {@link useGenerationResources}. The
+ * SENDER is always the token subject (server self-binds it); the block never
+ * supplies a `fromUserId`.
+ *
+ * IDEMPOTENCY: pass a stable `options.idempotencyKey` to make a retry-after-
+ * timeout safe (the server replays the first terminal result). Omitting it mints
+ * a fresh key per call, so each call is a distinct logical tip.
+ *
+ * @example
+ * const { tip, loading, error } = useTip();
+ * const key = React.useId(); // stable across this component's retries
+ * await tip({ toUserId: 123, amount: 50, entityType: 'Image', entityId: 99 }, { idempotencyKey: key });
+ */
+export function useTip() {
+    const host = useHostOrigin();
+    const { raw } = useBlockToken();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    const inFlight = useRef(new Set());
+    useEffect(() => {
+        mountedRef.current = true;
+        const controllers = inFlight.current;
+        return () => {
+            mountedRef.current = false;
+            for (const c of controllers)
+                c.abort();
+            controllers.clear();
+        };
+    }, []);
+    const tip = useCallback(async (params, options) => {
+        if (!host) {
+            throw new Error('useTip: host origin not established yet (wait for BLOCK_INIT).');
+        }
+        if (mountedRef.current) {
+            setLoading(true);
+            setError(null);
+        }
+        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        const controller = new AbortController();
+        inFlight.current.add(controller);
+        const timeoutId = setTimeout(() => controller.abort(), TIP_REQUEST_TIMEOUT_MS);
+        try {
+            const res = await fetch(`${host}/api/v1/blocks/tip`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${raw}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    toUserId: params.toUserId,
+                    amount: params.amount,
+                    ...(params.entityType ? { entityType: params.entityType } : {}),
+                    ...(params.entityId != null ? { entityId: params.entityId } : {}),
+                    idempotencyKey,
+                }),
+                signal: controller.signal,
+            });
+            const bodyJson = (await res.json().catch(() => null));
+            if (!res.ok) {
+                throw new Error(bodyJson?.error ?? `tip request failed (${res.status})`);
+            }
+            return bodyJson;
+        }
+        catch (err) {
+            const e = controller.signal.aborted && !(err instanceof Error && err.message.startsWith('tip'))
+                ? new Error(`useTip: request aborted (timed out after ${TIP_REQUEST_TIMEOUT_MS}ms or the hook unmounted).`)
+                : err instanceof Error
+                    ? err
+                    : new Error(String(err));
+            if (mountedRef.current)
+                setError(e);
+            throw e;
+        }
+        finally {
+            clearTimeout(timeoutId);
+            inFlight.current.delete(controller);
+            if (mountedRef.current)
+                setLoading(false);
+        }
+    }, [host, raw]);
+    return { tip, loading, error };
+}
+//# sourceMappingURL=useTip.js.map

package/dist/hooks/useTip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTip.js","sourceRoot":"","sources":["../../src/hooks/useTip.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useTipAllowance.d.ts

@@ -0,0 +1,40 @@
+/** The viewer's daily tip allowance, in Buzz. */
+export interface TipAllowance {
+    /** The per-user daily tip ceiling. */
+    cap: number;
+    /**
+     * Net Buzz reserved toward tips today (reservation-based, so it can briefly
+     * over-count between a reserve and its refund — the safe direction).
+     */
+    spent: number;
+    /** `cap - spent`, clamped at 0 — the amount the viewer may still tip today. */
+    remaining: number;
+}
+export interface UseTipAllowance {
+    /** The current allowance, or `null` until the first successful fetch. */
+    allowance: TipAllowance | null;
+    /** `true` while a fetch (initial or `refetch`) is in flight. */
+    loading: boolean;
+    /** The last fetch's failure, or `null`. Cleared at the start of the next fetch. */
+    error: Error | null;
+    /** Re-read the allowance (e.g. after the viewer tips). */
+    refetch: () => void;
+}
+/**
+ * Read the viewer's REAL remaining daily tip allowance `{ cap, spent, remaining }`
+ * through the block-token-gated `GET /api/v1/blocks/tip-allowance` REST endpoint
+ * (scope `social:tip:self` — the SAME scope the app already holds to tip, so no
+ * manifest change). Direct-fetch against the validated host origin with the block
+ * bearer token, the same pattern as {@link useGenerationResources}.
+ *
+ * Lets a block show a genuinely-tracked remaining allowance and disable the tip
+ * button at the true ceiling — instead of a dead client-side full-cap guess
+ * (`localStorage` is inert in the opaque-origin sandbox). Fetches once on mount
+ * and exposes `refetch` (call it after a successful `useTip().tip(...)`).
+ *
+ * @example
+ * const { allowance, refetch } = useTipAllowance();
+ * // allowance?.remaining — Buzz the viewer may still tip today
+ */
+export declare function useTipAllowance(): UseTipAllowance;
+//# sourceMappingURL=useTipAllowance.d.ts.map

package/dist/hooks/useTipAllowance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTipAllowance.d.ts","sourceRoot":"","sources":["../../src/hooks/useTipAllowance.ts"],"names":[],"mappings":"AAWA,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,SAAS,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B,gEAAgE;IAChE,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAsEjD"}

package/dist/hooks/useTipAllowance.js

@@ -0,0 +1,90 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useHostOrigin } from './useHostOrigin.js';
+import { useBlockToken } from './useBlockToken.js';
+/**
+ * Backstop timeout for the direct REST allowance GET (see {@link useTip} /
+ * {@link useGenerationResources} for why direct-fetch hooks need their own bound).
+ */
+const TIP_ALLOWANCE_TIMEOUT_MS = 30_000;
+/**
+ * Read the viewer's REAL remaining daily tip allowance `{ cap, spent, remaining }`
+ * through the block-token-gated `GET /api/v1/blocks/tip-allowance` REST endpoint
+ * (scope `social:tip:self` — the SAME scope the app already holds to tip, so no
+ * manifest change). Direct-fetch against the validated host origin with the block
+ * bearer token, the same pattern as {@link useGenerationResources}.
+ *
+ * Lets a block show a genuinely-tracked remaining allowance and disable the tip
+ * button at the true ceiling — instead of a dead client-side full-cap guess
+ * (`localStorage` is inert in the opaque-origin sandbox). Fetches once on mount
+ * and exposes `refetch` (call it after a successful `useTip().tip(...)`).
+ *
+ * @example
+ * const { allowance, refetch } = useTipAllowance();
+ * // allowance?.remaining — Buzz the viewer may still tip today
+ */
+export function useTipAllowance() {
+    const host = useHostOrigin();
+    const { raw } = useBlockToken();
+    const [allowance, setAllowance] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    const inFlight = useRef(new Set());
+    useEffect(() => {
+        mountedRef.current = true;
+        const controllers = inFlight.current;
+        return () => {
+            mountedRef.current = false;
+            for (const c of controllers)
+                c.abort();
+            controllers.clear();
+        };
+    }, []);
+    const refetch = useCallback(() => {
+        // Wait for the host origin (established at BLOCK_INIT) before the first fetch.
+        if (!host)
+            return;
+        if (mountedRef.current) {
+            setLoading(true);
+            setError(null);
+        }
+        const controller = new AbortController();
+        inFlight.current.add(controller);
+        const timeoutId = setTimeout(() => controller.abort(), TIP_ALLOWANCE_TIMEOUT_MS);
+        fetch(`${host}/api/v1/blocks/tip-allowance`, {
+            headers: { Authorization: `Bearer ${raw}` },
+            signal: controller.signal,
+        })
+            .then(async (res) => {
+            const body = (await res.json().catch(() => null));
+            if (!mountedRef.current)
+                return;
+            if (!res.ok || body == null || typeof body.remaining !== 'number') {
+                setError(new Error(body?.error ?? `tip-allowance request failed (${res.status})`));
+                setLoading(false);
+                return;
+            }
+            setAllowance({ cap: body.cap ?? 0, spent: body.spent ?? 0, remaining: body.remaining });
+            setLoading(false);
+        })
+            .catch((err) => {
+            if (!mountedRef.current)
+                return;
+            setError(controller.signal.aborted
+                ? new Error(`useTipAllowance: request aborted (timed out after ${TIP_ALLOWANCE_TIMEOUT_MS}ms or the hook unmounted).`)
+                : err instanceof Error
+                    ? err
+                    : new Error(String(err)));
+            setLoading(false);
+        })
+            .finally(() => {
+            clearTimeout(timeoutId);
+            inFlight.current.delete(controller);
+        });
+    }, [host, raw]);
+    useEffect(() => {
+        refetch();
+    }, [refetch]);
+    return { allowance, loading, error, refetch };
+}
+//# sourceMappingURL=useTipAllowance.js.map

package/dist/hooks/useTipAllowance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTipAllowance.js","sourceRoot":"","sources":["../../src/hooks/useTipAllowance.ts"],"names":[],"mappings":"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"}