@civitai/blocks-react 0.60.0 → 0.61.0

package/dist/hooks/useCheckpointPicker.d.ts

@@ -1,14 +1,40 @@
 import type { BlockCheckpointInfo } from '@civitai/app-sdk/blocks';
 /** What {@link useCheckpointPicker} returns. */
 export interface UseCheckpointPicker {
-    open: (opts: {
+    open: (opts?: {
         /**
-         * Ecosystem key (e.g. 'Flux1', 'SDXL'). Get it from
-         * `useBlockContext().context.checkpoint?.baseModel` — but for the
-         * picker filter the host will collapse to the ecosystem family, so
-         * any baseModel in the family works as a hint.
+         * 🔴 OMIT THIS BY DEFAULT. It is an ecosystem-family FILTER, not a label:
+         * the host HIDES every checkpoint outside the family you pass. Passing the
+         * family you are already in is therefore a trap — it makes the picker offer
+         * only the ecosystem the user is trying to leave, and every other family
+         * becomes unreachable for the life of the session.
+         *
+         * Omit it for an unconstrained pick: the host applies no base-model
+         * narrowing and offers every checkpoint the viewer can generate with.
+         *
+         * Pass it ONLY when the block must stay inside a family it already holds —
+         * a regenerate/variation flow pinned to one checkpoint's ecosystem, say —
+         * and then DERIVE it from that checkpoint (`checkpoint.baseModel`, or
+         * `useBlockContext().context.checkpoint?.baseModel`). Never a hardcoded
+         * ecosystem string: a literal pins every viewer of the app to whichever
+         * family the author happened to be testing with. Accepts an ecosystem key
+         * (e.g. 'Flux1', 'SDXL') or any baseModel name in the family; the host
+         * collapses either to the ecosystem family.
+         *
+         * An empty string is normalized to absent here and never reaches the wire,
+         * and `''` is **not** an escape hatch — it does not even mean the same thing
+         * on both hosts. On a **model slot** the host normalises whatever string you
+         * send, so `''` resolves to the real ecosystem key `Other` and NARROWS to
+         * that one family. On a **page** the host drops a zero-length value, so `''`
+         * behaves exactly like omitting it. Neither is what you meant on at least one
+         * surface: omit the key, or pass a family derived from a real checkpoint, and
+         * never `''`.
+         *
+         * A WHITESPACE-ONLY string narrows on BOTH hosts — the page host's guard is
+         * `length > 0`, which `'  '` passes — which is why this hook trims before
+         * deciding.
          */
-        baseModelGroup: string;
+        baseModelGroup?: string;
         /** Currently-selected versionId so the picker can pre-highlight it. */
         currentVersionId?: number;
     }) => Promise<{
@@ -19,9 +45,10 @@ export interface UseCheckpointPicker {
 /**
  * Drives the platform-side Checkpoint picker and the persist-override flow.
  *
- * `open` opens the host's Resource picker filtered to Checkpoints in the
- * given ecosystem; resolves with `{ selected }` (undefined when the user
- * dismissed without picking).
+ * `open` opens the host's Resource picker on Checkpoints and resolves with
+ * `{ selected }` (undefined when the user dismissed without picking). By
+ * default the pick is UNCONSTRAINED — every family the viewer can generate
+ * with. Pass `baseModelGroup` only to pin it to one ecosystem.
  *
  * `persist` writes the chosen versionId into `block_user_settings` via the
  * host. Pass `null` to clear the override and fall back to the publisher
@@ -33,9 +60,15 @@ export interface UseCheckpointPicker {
  * useBuzzWorkflow.
  *
  * @example
+ * // DEFAULT — no ecosystem. The viewer can reach every family.
  * const { open, persist } = useCheckpointPicker();
- * const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
+ * const { selected } = await open({ currentVersionId: checkpoint.versionId });
  * if (selected) await persist(selected.versionId);   // null clears the override
+ *
+ * @example
+ * // ONLY when the block must stay inside a family it already holds: derive the
+ * // filter from that checkpoint, never from a hardcoded ecosystem.
+ * const { selected } = await open({ baseModelGroup: checkpoint.baseModel });
  */
 export declare function useCheckpointPicker(): UseCheckpointPicker;
 //# sourceMappingURL=useCheckpointPicker.d.ts.map

package/dist/hooks/useCheckpointPicker.js

@@ -6,9 +6,10 @@ import { sendTypedRequest } from '../transport/transport.js';
 /**
  * Drives the platform-side Checkpoint picker and the persist-override flow.
  *
- * `open` opens the host's Resource picker filtered to Checkpoints in the
- * given ecosystem; resolves with `{ selected }` (undefined when the user
- * dismissed without picking).
+ * `open` opens the host's Resource picker on Checkpoints and resolves with
+ * `{ selected }` (undefined when the user dismissed without picking). By
+ * default the pick is UNCONSTRAINED — every family the viewer can generate
+ * with. Pass `baseModelGroup` only to pin it to one ecosystem.
  *
  * `persist` writes the chosen versionId into `block_user_settings` via the
  * host. Pass `null` to clear the override and fall back to the publisher
@@ -20,17 +21,47 @@ import { sendTypedRequest } from '../transport/transport.js';
  * useBuzzWorkflow.
  *
  * @example
+ * // DEFAULT — no ecosystem. The viewer can reach every family.
  * const { open, persist } = useCheckpointPicker();
- * const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
+ * const { selected } = await open({ currentVersionId: checkpoint.versionId });
  * if (selected) await persist(selected.versionId);   // null clears the override
+ *
+ * @example
+ * // ONLY when the block must stay inside a family it already holds: derive the
+ * // filter from that checkpoint, never from a hardcoded ecosystem.
+ * const { selected } = await open({ baseModelGroup: checkpoint.baseModel });
  */
 export function useCheckpointPicker() {
     const open = useCallback(async (opts) => {
+        // Both keys are spread conditionally, and an empty or whitespace-only
+        // family is normalized to absent.
+        //
+        // The distinction that matters is `''`/whitespace vs ABSENT — NOT
+        // explicit-`undefined` vs absent. The model-slot host branches on
+        // `typeof baseModelGroup === 'string'`, and `typeof undefined === 'string'`
+        // is false, so a present-and-undefined key takes exactly the same "no
+        // family" branch as an absent one on every host surface. A non-empty string
+        // does not: it IS a string, so it survives that branch, and
+        // `getBaseModelGroup` collapses an unrecognised value to the real ecosystem
+        // key 'Other' — which NARROWS the picker to that one family instead of
+        // widening it.
+        //
+        // 🔴 THE TWO SPELLINGS DIFFER BY HOST, so this normalization is doing two
+        // different jobs:
+        //   - `''` narrows on the MODEL SLOT (any string is normalised there) but
+        //     is already equivalent to omission on the PAGE host, whose resolver
+        //     drops a zero-length value before the lookup. Stripping it matters on
+        //     one surface and is a no-op on the other.
+        //   - a WHITESPACE-ONLY string narrows on BOTH: the page host's guard is
+        //     `length > 0`, which `'  '` passes. That is what `.trim()` is for, and
+        //     it is the half a test on `''` alone cannot see.
+        // Absence is the only spelling that means "unconstrained" on both surfaces.
+        const baseModelGroup = opts?.baseModelGroup?.trim();
         const { selected } = await sendTypedRequest(getTransport(), {
             type: 'OPEN_CHECKPOINT_PICKER',
             payload: {
-                baseModelGroup: opts.baseModelGroup,
-                ...(opts.currentVersionId != null
+                ...(baseModelGroup ? { baseModelGroup } : {}),
+                ...(opts?.currentVersionId != null
                     ? { currentVersionId: opts.currentVersionId }
                     : {}),
             },

package/dist/hooks/useCivitaiNavigate.d.ts

@@ -1,17 +1,68 @@
+import type { BlockNavigateScope } from '@civitai/app-sdk/blocks';
+/**
+ * Options for {@link UseCivitaiNavigate.navigate}.
+ *
+ * Passed as the SECOND argument, where a bare `'current' | 'new_tab'` string is
+ * also still accepted — see {@link UseCivitaiNavigate.navigate}.
+ */
+export interface UseCivitaiNavigateOptions {
+    /**
+     * Which SPACE `path` is resolved in. DEFAULTS to `'app'` — this app's own
+     * sub-paths, which is all `navigate` could reach before this field existed.
+     *
+     * 🔴 `'/models/12345'` WITHOUT a scope does NOT reach civitai's model page. A
+     * leading slash carries no meaning: the host normalises it away in both
+     * scopes, so that call is a request for `<this app>/models/12345`. To reach
+     * the civitai.com page, say `{ scope: 'site' }`.
+     */
+    scope?: BlockNavigateScope;
+    /** Where the host should open it. Defaults to `'current'`. */
+    target?: 'current' | 'new_tab';
+}
 /** What {@link useCivitaiNavigate} returns. */
 export interface UseCivitaiNavigate {
-    navigate: (path: string, target?: 'current' | 'new_tab') => void;
+    /**
+     * Requests a navigation. The second argument is either an options object or —
+     * for the call shape that predates `scope` — a bare target string.
+     */
+    navigate: (path: string, options?: 'current' | 'new_tab' | UseCivitaiNavigateOptions) => void;
 }
 /**
- * Requests a navigation within civitai.com. The host mediates — `target:
- * "current"` navigates the parent frame; `"new_tab"` opens a new tab (which
- * requires `allow-popups-to-escape-sandbox` in the manifest sandbox).
+ * Requests a navigation from the host: the hook sends a `NAVIGATE` message and
+ * returns. Fire-and-forget — the host doesn't reply, so the block never learns
+ * what the host did, including when the host REFUSES the request.
+ *
+ * 🔴 `scope` SELECTS THE SPACE, AND IT DEFAULTS TO `'app'`.
+ *
+ *  - `'app'` (default) — `path` is resolved under this app's OWN route, as a
+ *    sub-path of it, and pushed shallowly so the page stays mounted.
+ *  - `'site'` — `path` is resolved at the civitai.com root and the viewer leaves
+ *    the app. The host grants this per-surface and refuses it elsewhere.
+ *
+ * 🔴 A LEADING SLASH CARRIES NO MEANING — the host normalises it away in BOTH
+ * scopes, so `'/settings'` and `'settings'` are one request within whichever
+ * scope you chose. `navigate('/models/12345')` is therefore a request for THIS
+ * APP's `/models/12345`, not civitai's model page; that needs
+ * `{ scope: 'site' }`. (Both spellings were app-scoped before `scope` existed
+ * too, so no existing call changed meaning — which is the point of the default.)
+ *
+ * `target` is a REQUEST, not a guarantee. How the host acts on `'current'` vs
+ * `'new_tab'` is host-side behaviour, and the host is the authority on it; this
+ * package sends the message and makes no promise about the outcome.
  *
- * Fire-and-forget: the host doesn't reply with confirmation.
+ * 🔴 Nothing in your manifest enables `'new_tab'`. In particular, do NOT declare
+ * `allow-popups-to-escape-sandbox`: the host intersects a manifest's
+ * `iframe.sandbox` with a fixed allowlist that does not contain that token, so it
+ * is dropped for every block at every trust tier and declaring it has no effect.
+ * (Earlier versions of this doc said `"new_tab"` required it — that was wrong.)
  *
  * @example
  * const { navigate } = useCivitaiNavigate();
- * navigate('/models/12345', 'new_tab');   // 'new_tab' needs allow-popups* in the manifest sandbox
+ * navigate('settings');                                  // this app's own /settings
+ * navigate('/settings');                                 // identical — the slash means nothing
+ * navigate('models/12345', { scope: 'site' });           // civitai.com/models/12345
+ * navigate('models/12345', { scope: 'site', target: 'new_tab' });
+ * navigate('detail/7', 'new_tab');                       // the pre-`scope` shape, still app-scoped
  */
 export declare function useCivitaiNavigate(): UseCivitaiNavigate;
 //# sourceMappingURL=useCivitaiNavigate.d.ts.map

package/dist/hooks/useCivitaiNavigate.js

@@ -1,19 +1,62 @@
 import { useCallback } from 'react';
 import { getTransport } from '../transport/singleton.js';
 /**
- * Requests a navigation within civitai.com. The host mediates — `target:
- * "current"` navigates the parent frame; `"new_tab"` opens a new tab (which
- * requires `allow-popups-to-escape-sandbox` in the manifest sandbox).
+ * Requests a navigation from the host: the hook sends a `NAVIGATE` message and
+ * returns. Fire-and-forget — the host doesn't reply, so the block never learns
+ * what the host did, including when the host REFUSES the request.
  *
- * Fire-and-forget: the host doesn't reply with confirmation.
+ * 🔴 `scope` SELECTS THE SPACE, AND IT DEFAULTS TO `'app'`.
+ *
+ *  - `'app'` (default) — `path` is resolved under this app's OWN route, as a
+ *    sub-path of it, and pushed shallowly so the page stays mounted.
+ *  - `'site'` — `path` is resolved at the civitai.com root and the viewer leaves
+ *    the app. The host grants this per-surface and refuses it elsewhere.
+ *
+ * 🔴 A LEADING SLASH CARRIES NO MEANING — the host normalises it away in BOTH
+ * scopes, so `'/settings'` and `'settings'` are one request within whichever
+ * scope you chose. `navigate('/models/12345')` is therefore a request for THIS
+ * APP's `/models/12345`, not civitai's model page; that needs
+ * `{ scope: 'site' }`. (Both spellings were app-scoped before `scope` existed
+ * too, so no existing call changed meaning — which is the point of the default.)
+ *
+ * `target` is a REQUEST, not a guarantee. How the host acts on `'current'` vs
+ * `'new_tab'` is host-side behaviour, and the host is the authority on it; this
+ * package sends the message and makes no promise about the outcome.
+ *
+ * 🔴 Nothing in your manifest enables `'new_tab'`. In particular, do NOT declare
+ * `allow-popups-to-escape-sandbox`: the host intersects a manifest's
+ * `iframe.sandbox` with a fixed allowlist that does not contain that token, so it
+ * is dropped for every block at every trust tier and declaring it has no effect.
+ * (Earlier versions of this doc said `"new_tab"` required it — that was wrong.)
  *
  * @example
  * const { navigate } = useCivitaiNavigate();
- * navigate('/models/12345', 'new_tab');   // 'new_tab' needs allow-popups* in the manifest sandbox
+ * navigate('settings');                                  // this app's own /settings
+ * navigate('/settings');                                 // identical — the slash means nothing
+ * navigate('models/12345', { scope: 'site' });           // civitai.com/models/12345
+ * navigate('models/12345', { scope: 'site', target: 'new_tab' });
+ * navigate('detail/7', 'new_tab');                       // the pre-`scope` shape, still app-scoped
  */
 export function useCivitaiNavigate() {
-    const navigate = useCallback((path, target = 'current') => {
-        getTransport().sendMessage({ type: 'NAVIGATE', payload: { path, target } });
+    const navigate = useCallback((path, options = {}) => {
+        // A bare string is the pre-`scope` call shape (`navigate(path, 'new_tab')`)
+        // and stays supported: there are live callers, and the whole point of the
+        // `'app'` default is that none of them changes meaning. Widening the
+        // parameter rather than adding an overload keeps ONE published signature,
+        // so `UseCivitaiNavigate` still describes the hook exactly.
+        const opts = typeof options === 'string' ? { target: options } : options;
+        // `scope` is OMITTED, not sent as `undefined`, when the caller did not
+        // choose one — absent and `'app'` mean the same thing to the host, so the
+        // payload an unscoped call puts on the wire stays byte-identical to what
+        // every pre-`scope` build sent.
+        getTransport().sendMessage({
+            type: 'NAVIGATE',
+            payload: {
+                path,
+                ...(opts.scope ? { scope: opts.scope } : {}),
+                target: opts.target ?? 'current',
+            },
+        });
     }, []);
     return { navigate };
 }

package/dist/hooks/useCivitaiRoute.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What {@link useCivitaiRoute} returns. An alias — see `./returnTypeLedger.js`
+ * for why every hook on the entry has one of these.
+ */
+export type UseCivitaiRoute = string;
+/**
+ * The sub-path below your app's root that is CURRENTLY showing, kept live for
+ * the whole life of the block ON THE IFRAME TRANSPORT.
+ *
+ * The page surface owns the browser history; your block does not. You ask for a
+ * move with {@link useCivitaiNavigate} (`scope: 'app'`, the default), the host
+ * pushes it shallowly so your frame stays mounted — and this is how you learn
+ * where you ended up. It also reports the moves you did NOT ask for: the
+ * viewer's own back/forward, and a deep link the host resolved after init.
+ *
+ * Reads the SAME singleton transport snapshot {@link useBlockContext} does, so
+ * it re-renders when the value changes. Two things set it:
+ *
+ *  1. `BLOCK_INIT` — `context.subPath`, the host's value at mount. The FIRST
+ *     value always arrives here, never over a message;
+ *  2. `ROUTE_CHANGED`, the host's push on every later change.
+ *
+ * It is the same value as `useBlockContext().context.subPath` on a page slot —
+ * reach for this when the route is all you need, and because this hook's return
+ * type is a plain `string` rather than a field on a union you have to narrow.
+ *
+ * ```tsx
+ * const subPath = useCivitaiRoute();          // '' on your app's index
+ * const [view, id] = subPath.split('/');      // 'compare/42' → ['compare', '42']
+ * ```
+ *
+ * 🔴 `''` IS A REAL ROUTE — your app's own index — AND IT IS ALSO THE PRE-INIT
+ * SENTINEL. The two are indistinguishable from this hook alone, exactly as
+ * `'light'` is both a real theme and {@link useBlockTheme}'s pre-init value.
+ * Gate on `useBlockContext().ready` if your first paint must tell them apart.
+ *
+ * 🔴 NO LEADING SLASH, and no slash-tolerance to lean on. The host sends the
+ * segment below your app root — `'compare/42'`, not `'/compare/42'` — so
+ * `subPath === 'compare/42'` is the comparison that works and
+ * `subPath === '/compare/42'` is the one that silently never matches.
+ *
+ * 🔴 PAGE SLOT ONLY. A model-page slot has no route of its own, so this returns
+ * `''` there and never moves. It is not a defect to debug: the host's own
+ * `ROUTE_CHANGED` effect lives in `PageBlockHost`, and `ModelSlotContext` has no
+ * `subPath` field for it to update.
+ *
+ * 🔴 OLD HOST: a host that never sends `ROUTE_CHANGED` simply never moves the
+ * value — the hook degrades to the init sub-path, which is the behaviour every
+ * page block had before the message existed. Nothing here awaits a message, so
+ * there is no hang and no timeout.
+ *
+ * 🔴 INLINE TRANSPORT: the value is FROZEN at the init sub-path. v1 inline mode
+ * receives no host pushes at all (`InlineTransport.onMessage` is a stub and
+ * `subscribe` is a no-op, so nothing can emit), the same degradation as an old
+ * host, and it lifts when v2 inline mode lands.
+ *
+ * 🔴 READ IT ON EVERY RENDER. A block that copies the value into state once at
+ * mount — or routes imperatively in a mount-only effect — stays on the route it
+ * started with and reproduces the symptom this message exists to end: the URL
+ * moves and nothing renders.
+ */
+export declare function useCivitaiRoute(): UseCivitaiRoute;
+//# sourceMappingURL=useCivitaiRoute.d.ts.map

package/dist/hooks/useCivitaiRoute.js

@@ -0,0 +1,71 @@
+import { useTransportSnapshot } from './useBlockContext.js';
+/**
+ * The sub-path below your app's root that is CURRENTLY showing, kept live for
+ * the whole life of the block ON THE IFRAME TRANSPORT.
+ *
+ * The page surface owns the browser history; your block does not. You ask for a
+ * move with {@link useCivitaiNavigate} (`scope: 'app'`, the default), the host
+ * pushes it shallowly so your frame stays mounted — and this is how you learn
+ * where you ended up. It also reports the moves you did NOT ask for: the
+ * viewer's own back/forward, and a deep link the host resolved after init.
+ *
+ * Reads the SAME singleton transport snapshot {@link useBlockContext} does, so
+ * it re-renders when the value changes. Two things set it:
+ *
+ *  1. `BLOCK_INIT` — `context.subPath`, the host's value at mount. The FIRST
+ *     value always arrives here, never over a message;
+ *  2. `ROUTE_CHANGED`, the host's push on every later change.
+ *
+ * It is the same value as `useBlockContext().context.subPath` on a page slot —
+ * reach for this when the route is all you need, and because this hook's return
+ * type is a plain `string` rather than a field on a union you have to narrow.
+ *
+ * ```tsx
+ * const subPath = useCivitaiRoute();          // '' on your app's index
+ * const [view, id] = subPath.split('/');      // 'compare/42' → ['compare', '42']
+ * ```
+ *
+ * 🔴 `''` IS A REAL ROUTE — your app's own index — AND IT IS ALSO THE PRE-INIT
+ * SENTINEL. The two are indistinguishable from this hook alone, exactly as
+ * `'light'` is both a real theme and {@link useBlockTheme}'s pre-init value.
+ * Gate on `useBlockContext().ready` if your first paint must tell them apart.
+ *
+ * 🔴 NO LEADING SLASH, and no slash-tolerance to lean on. The host sends the
+ * segment below your app root — `'compare/42'`, not `'/compare/42'` — so
+ * `subPath === 'compare/42'` is the comparison that works and
+ * `subPath === '/compare/42'` is the one that silently never matches.
+ *
+ * 🔴 PAGE SLOT ONLY. A model-page slot has no route of its own, so this returns
+ * `''` there and never moves. It is not a defect to debug: the host's own
+ * `ROUTE_CHANGED` effect lives in `PageBlockHost`, and `ModelSlotContext` has no
+ * `subPath` field for it to update.
+ *
+ * 🔴 OLD HOST: a host that never sends `ROUTE_CHANGED` simply never moves the
+ * value — the hook degrades to the init sub-path, which is the behaviour every
+ * page block had before the message existed. Nothing here awaits a message, so
+ * there is no hang and no timeout.
+ *
+ * 🔴 INLINE TRANSPORT: the value is FROZEN at the init sub-path. v1 inline mode
+ * receives no host pushes at all (`InlineTransport.onMessage` is a stub and
+ * `subscribe` is a no-op, so nothing can emit), the same degradation as an old
+ * host, and it lifts when v2 inline mode lands.
+ *
+ * 🔴 READ IT ON EVERY RENDER. A block that copies the value into state once at
+ * mount — or routes imperatively in a mount-only effect — stays on the route it
+ * started with and reproduces the symptom this message exists to end: the URL
+ * moves and nothing renders.
+ */
+export function useCivitaiRoute() {
+    const context = useTransportSnapshot().context;
+    // A PRESENCE test, not a slot-id test, and not a cast. `BlockContext` is a
+    // union whose `UnknownSlotContext` arm declares `slotId` and nothing else, and
+    // the pre-init `EMPTY_SNAPSHOT.context` is exactly that shape — so there is
+    // genuinely no field to read before init, or on any slot but the page. The
+    // `typeof` half is not belt-and-braces either: `UnknownSlotContext` would let
+    // a host put any value on that key, and this hook's published return type is
+    // `string`.
+    if ('subPath' in context && typeof context.subPath === 'string')
+        return context.subPath;
+    return '';
+}
+//# sourceMappingURL=useCivitaiRoute.js.map

package/dist/hooks/useCreatePostFromApp.d.ts

@@ -1,4 +1,5 @@
 import type { BlockCreatePostHostError, BlockCreatePostRequest, BlockCreatePostResult, BlockPostSource } from '@civitai/app-sdk/blocks';
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 export type { BlockCreatePostHostError, BlockCreatePostRequest, BlockCreatePostResult, BlockPostSource, };
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
@@ -75,7 +76,7 @@ export interface UseCreatePostFromApp {
      * `declined`, which means the viewer dismissed the confirm and NO POST EXISTS.
      * Check `.declined` before rendering a failure.
      */
-    createPost: (args: BlockCreatePostRequest) => Promise<BlockCreatePostResult>;
+    createPost: (args: BlockCreatePostRequest, options?: ConsentRetryOptions) => Promise<BlockCreatePostResult>;
     /** `true` while a request is in flight (including the viewer's confirm). */
     pending: boolean;
     /**

package/dist/hooks/useCreatePostFromApp.js

@@ -1,7 +1,17 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { HUMAN_INTERACTION_TIMEOUT_MS } from '../transport/requestTimeouts.js';
 import { getTransport } from '../transport/singleton.js';
 import { RequestTimeoutError, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope this bridge requires — `posts:write:self`, named in
+ * `@civitai/app-sdk`'s own `CREATE_POST_FROM_APP` message docs ("Scope
+ * `posts:write:self` (NOT `ai:write:budgeted`), which is SENSITIVE and
+ * CONSENT-GATED"). From {@link BLOCK_SCOPES}, never a literal: a typo would not
+ * error, it would make the automatic consent prompt silently do nothing.
+ */
+const CREATE_POST_SCOPES = [BLOCK_SCOPES.POSTS_WRITE_SELF];
 /**
  * The closed set of HOST refusal codes, as a runtime Set.
  *
@@ -152,49 +162,92 @@ export function useCreatePostFromApp() {
             mountedRef.current = false;
         };
     }, []);
-    const createPost = useCallback(async (args) => {
+    /** ONE round-trip + its result contract. Re-invoked verbatim on a consent retry. */
+    const createPostOnce = useCallback(async (args) => {
+        const reply = await sendTypedRequest(getTransport(), {
+            type: 'CREATE_POST_FROM_APP',
+            payload: {
+                sources: args.sources,
+                ...(args.title !== undefined ? { title: args.title } : {}),
+                ...(args.detail !== undefined ? { detail: args.detail } : {}),
+                ...(args.tags !== undefined ? { tags: args.tags } : {}),
+                ...(args.modelVersionId !== undefined
+                    ? { modelVersionId: args.modelVersionId }
+                    : {}),
+            },
+        }, 'CREATE_POST_RESULT', 
+        // See the `'human'` bucketing in `transport/requestTimeouts.ts`: the
+        // host answers only when the viewer clicks or dismisses its confirm.
+        { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS }).catch((err) => {
+            // 🔴 THE `timedOut` STAMP LIVES HERE, INSIDE THE CLOSURE
+            // `withConsentRetry` RE-INVOKES — NOT IN `createPost`'s OUTER CATCH.
+            // That placement is the whole point and it is load-bearing: rule 4 of
+            // `internal/withConsentRetry.ts` ("never retry a keyless bridge's
+            // timeout") is read off THIS error, so a stamp applied outside the
+            // wrapper is invisible to it. Until #500 round 2 it was applied outside,
+            // and the consequence was exactly what `CreatePostError.timedOut`'s
+            // docstring exists to prevent: a raw `RequestTimeoutError` reached the
+            // helper carrying neither `declined` nor `timedOut`, so on a token
+            // lacking `posts:write:self` the SDK prompted and RE-SENT THE POST.
+            // `CREATE_POST_FROM_APP` has no `idempotencyKey` on the wire, so that
+            // second send is a genuine second write — a DUPLICATE PUBLIC POST under
+            // the viewer's name.
+            //
+            // Structural, not a message match — see `RequestTimeoutError`.
+            if (err instanceof RequestTimeoutError) {
+                throw new CreatePostError(err.message, { timedOut: true });
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        });
+        if (reply.error || !reply.result) {
+            // 🔴 `||`, NOT `??`. `isValidCreatePostResult` gates `error` on SHAPE
+            // only (it has to: the channel carries free-text server messages), so
+            // a host `error: ''` is a VALID reply that reaches here. `??` would
+            // then throw an Error with an EMPTY message for a public post, which
+            // renders as a blank failure. Fall through to a code that at least
+            // names a real outcome.
+            throw new CreatePostError(reply.error || 'no images to post');
+        }
+        return reply.result;
+    }, []);
+    const createPost = useCallback(async (args, options) => {
         if (mountedRef.current) {
             setPending(true);
             setError(null);
         }
         try {
-            const reply = await sendTypedRequest(getTransport(), {
-                type: 'CREATE_POST_FROM_APP',
-                payload: {
-                    sources: args.sources,
-                    ...(args.title !== undefined ? { title: args.title } : {}),
-                    ...(args.detail !== undefined ? { detail: args.detail } : {}),
-                    ...(args.tags !== undefined ? { tags: args.tags } : {}),
-                    ...(args.modelVersionId !== undefined
-                        ? { modelVersionId: args.modelVersionId }
-                        : {}),
-                },
-            }, 'CREATE_POST_RESULT', 
-            // See the `'human'` bucketing in `transport/requestTimeouts.ts`: the
-            // host answers only when the viewer clicks or dismisses its confirm.
-            { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
-            if (reply.error || !reply.result) {
-                // 🔴 `||`, NOT `??`. `isValidCreatePostResult` gates `error` on SHAPE
-                // only (it has to: the channel carries free-text server messages), so
-                // a host `error: ''` is a VALID reply that reaches here. `??` would
-                // then throw an Error with an EMPTY message for a public post, which
-                // renders as a blank failure. Fall through to a code that at least
-                // names a real outcome.
-                throw new CreatePostError(reply.error || 'no images to post');
-            }
-            return reply.result;
+            // 🔴 INSIDE the try, not around it: the wrapper must sit between the
+            // round-trip and the `setError` below, so a first attempt that is
+            // recovered by a consent grant never leaves a failure in `error` for the
+            // UI to render next to a post that succeeded.
+            //
+            // No idempotency key is involved — `CREATE_POST_FROM_APP` has none on the
+            // wire, which is exactly why a TIMEOUT here must never be retried: there
+            // is nothing for the server to dedupe a second send against, so the retry
+            // would be a second public post. `createPostOnce` stamps `timedOut` on
+            // its own error for that reason, INSIDE this closure where rule 4 can see
+            // it. The remaining duplicate-protection is the host's own per-post
+            // confirm, which a consent retry re-opens exactly once; and a `declined`
+            // (the viewer dismissing that confirm) is never retried at all.
+            return await withConsentRetry(getTransport(), CREATE_POST_SCOPES, () => createPostOnce(args), options, 
+            // Rule 3 in the time axis: a grant that lands after this component is
+            // gone must not publish a post nobody is left to see.
+            () => mountedRef.current);
         }
         catch (err) {
-            // A transport timeout arrives as a plain Error; wrap it so callers have
-            // ONE error type to test, with `.code` left undefined (it is not a host
-            // refusal). Re-wrapping our own error would lose `.code`, so pass it
-            // through.
+            // Wrap anything that is not already ours so callers have ONE error type
+            // to test, with `.code` left undefined (it is not a host refusal).
+            // Re-wrapping our own error would lose `.code` AND `.timedOut`, so pass
+            // it through.
+            //
+            // 🔴 NO `timedOut` STAMP HERE. It used to be applied at this line, which
+            // put it OUTSIDE `withConsentRetry` and made rule 4 unreachable for this
+            // bridge — the round-2 defect. `createPostOnce` owns the stamp now, so
+            // every transport timeout arrives here ALREADY a `CreatePostError` and
+            // takes the pass-through branch above.
             const wrapped = err instanceof CreatePostError
                 ? err
-                : new CreatePostError(err instanceof Error ? err.message : String(err), {
-                    // Structural, not a message match — see `RequestTimeoutError`.
-                    timedOut: err instanceof RequestTimeoutError,
-                });
+                : new CreatePostError(err instanceof Error ? err.message : String(err));
             if (mountedRef.current)
                 setError(wrapped);
             // 🔴 THROWN UNCONDITIONALLY, even when unmounted. The caller's `await`

package/dist/hooks/useGoodPurchase.d.ts

@@ -1,3 +1,4 @@
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 import type { Entitlement } from './useEntitlements.js';
 /** Which good to buy, and optionally the price the app showed the viewer. */
 export interface GoodPurchaseParams {
@@ -12,7 +13,7 @@ export interface GoodPurchaseParams {
     expectedPriceBuzz?: number;
 }
 /** Optional per-purchase controls. */
-export interface GoodPurchaseOptions {
+export interface GoodPurchaseOptions extends ConsentRetryOptions {
     /**
      * A STABLE idempotency key for this logical purchase. Reuse the SAME value
      * when RETRYING a purchase whose response was lost (timeout / network drop)