@civitai/blocks-react 0.59.0 → 0.61.0

package/dist/hooks/useBuzzWorkflow.js

@@ -1,6 +1,21 @@
-import { useCallback, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { withConsentRetry } from '../internal/withConsentRetry.js';
 import { getTransport } from '../transport/singleton.js';
 import { generateIdempotencyKey, sendTypedRequest } from '../transport/transport.js';
+/**
+ * The consent-gated scope {@link UseBuzzWorkflow.submit} requires.
+ *
+ * 🔴 `submit()` ONLY. `estimate()` needs the same scope but is deliberately not
+ * routed through the automatic consent retry — see the comment on `estimate`
+ * below; it is an on-mount read with no gesture behind it.
+ *
+ * Named from {@link BLOCK_SCOPES}, never a string literal: this array is sent to
+ * the host as the `REQUEST_CONSENT` hint, and the host ignores a hint with no
+ * RECOGNISED non-empty name — so a typo here would not error, it would make the
+ * automatic prompt silently do nothing.
+ */
+const WORKFLOW_SCOPES = [BLOCK_SCOPES.AI_WRITE_BUDGETED];
 /**
  * Snapshot statuses that mean "no further polling is needed."
  * Used by both `submit` (a host can return an instant-fail / cached result)
@@ -556,6 +571,50 @@ export function useBuzzWorkflow() {
     const [status, setStatus] = useState('idle');
     const [result, setResult] = useState(null);
     const [error, setError] = useState(null);
+    /**
+     * Whether this hook's component is still mounted.
+     *
+     * 🔴 ITS ONLY JOB IS THE CONSENT RETRY, and that is a MONEY gate rather than a
+     * setState-after-unmount tidy-up. `submit()` can sit in `withConsentRetry`'s
+     * 60s grant wait long after the component is gone, and nothing else can see
+     * that: this hook's calls go through the postMessage bridge, so there is no
+     * `AbortController` to fire and rule 3's `AbortError` path never triggers. A
+     * grant arriving after unmount would then RESERVE BUZZ for a generation nobody
+     * is left to watch. Read immediately before the retry, never cached.
+     */
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    /**
+     * 🔴 `estimate()` IS DELIBERATELY NOT ROUTED THROUGH `withConsentRetry`, and
+     * that exclusion is load-bearing rather than an oversight.
+     *
+     * The automatic prompt is for calls a PERSON just made. `estimate()` is not
+     * one: `starters/examples/buzz-workflow/src/App.tsx` calls it from a
+     * `useEffect` keyed on the form inputs, so it fires on mount and again on
+     * every parameter edit. Routing it would open a consent dialog with no gesture
+     * behind it and hold each call pending for the full 60s grant wait. That is the
+     * same reason the Buzz READS are excluded; `estimate()` just happens to live on
+     * a hook whose OTHER call moves money.
+     *
+     * ⚠️ The in-flight DE-DUPLICATION `withConsentRetry` gained in #500 round 2
+     * does not change this verdict, and reading it as a reason to route
+     * `estimate()` would be a mistake. It collapses CONCURRENT waits on the same
+     * scope set into one dialog; a form edited over several seconds produces
+     * SEQUENTIAL calls, each after the previous wait settled, so the N-dialogs
+     * problem survives for exactly this shape. The no-gesture objection is
+     * independent of it either way.
+     *
+     * A failed estimate keeps the behaviour that starter's own `catch` is written
+     * against: reject with the server's reason, and show no price, because a
+     * missing quote is not viewer-actionable copy. `submit()` IS routed, and that
+     * is where both the gesture and the charge are. Pinned by
+     * `test/withConsentRetry.test.tsx`.
+     */
     const estimate = useCallback(async (body) => {
         setError(null);
         setStatus('estimating');
@@ -606,62 +665,84 @@ export function useBuzzWorkflow() {
             throw err;
         }
     }, []);
+    /**
+     * ONE submit round-trip AND its result contract.
+     *
+     * 🔴 `idempotencyKey` IS A PARAMETER, NOT MINTED HERE, AND THAT IS THE MONEY
+     * SAFETY PROPERTY OF THIS WHOLE FILE. `submit` mints it ONCE, above the
+     * consent retry, and passes the same value into both invocations of this
+     * function. Minting it here instead would give the automatic retry a FRESH
+     * key — a SECOND Buzz reservation for one logical submit, which is exactly
+     * what {@link SubmitWorkflowOptions.idempotencyKey}'s docs forbid.
+     */
+    const submitOnce = useCallback(async (body, idempotencyKey) => {
+        const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
+        // 🔴 PUBLISH THE SNAPSHOT BEFORE THE REJECTION BELOW, for the same reason
+        // `estimate` does: a block may render from `result` rather than from the
+        // returned value, and jumping over this line would leave the PREVIOUS
+        // submit's snapshot in place — a live control pointing at a workflow THIS
+        // submit did not queue.
+        setResult(snapshot);
+        // 🔴 AN ERRORED SUBMIT MUST REJECT (civitai/civitai-app-starters#251, the
+        // `submit` half of civitai/civitai#4159). Two producers report
+        // `status:'failed'` and `status` separates neither:
+        //
+        //   - a budget / spend-cap REJECTION is an OUTCOME the block recovers from
+        //     (open a top-up flow). The server quotes the price it refused to
+        //     charge, so `cost.total` is present. It RESOLVES — turning this arm
+        //     into a throw is the one change that would break the recovery path.
+        //   - a failure-shaped reply with NO `cost` is not a usable outcome. It
+        //     REJECTS — and the `code` says which kind, because they differ on
+        //     whether money moved (see WorkflowSubmitError.code).
+        //
+        // BOTH clauses are load-bearing. Dropping `status === 'failed'` would
+        // reject every ordinary in-flight reply (`{status:'pending'}` is cost-less
+        // too); dropping the cost test would reject the budget rejection. And the
+        // test is `typeof … !== 'number'`, never `!snapshot.cost?.total`: `0` is a
+        // real price and falsy.
+        //
+        // 🔴 `status === 'failed'`, NOT `TERMINAL_STATUSES.has(status)`. Widening it
+        // would reject cost-less `succeeded`/`canceled`/`expired` replies, which are
+        // legitimate outcomes the server really does emit without a price
+        // (`snapshotFromWorkflow` omits `cost` on any non-numeric total). That
+        // WIDENING is invisible to a mutation sweep that only deletes clauses, so
+        // all three statuses are pinned by their own fixtures in the test file.
+        if (snapshot.status === 'failed' && typeof snapshot.cost?.total !== 'number') {
+            // 🔴 WHICH ARM: the host stamps its own synthesised failures with the
+            // `'failed'` sentinel, while a server-built reply carries `workflow.id`
+            // (or the `'whatif'` sentinel).
+            // Anything unrecognised falls to `'workflow-failed'`, the arm that assumes
+            // money MAY be committed — an unknown id must never buy the reassuring
+            // "nothing was charged" reading.
+            throw new WorkflowSubmitError(snapshot, snapshot.workflowId === HOST_SYNTHESISED_WORKFLOW_ID ? 'exception' : 'workflow-failed');
+        }
+        setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
+        return snapshot;
+    }, []);
     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).
+        //
+        // 🔴 MINTED HERE, OUTSIDE THE CLOSURE `withConsentRetry` RE-INVOKES. Both
+        // attempts therefore carry the SAME key and the host+orchestrator collapse
+        // them to ONE reservation. Move this line inside `submitOnce` and an
+        // automatic retry double-reserves a real person's Buzz — the single
+        // regression this feature exists to not have.
         const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
         try {
-            const { snapshot } = await sendTypedRequest(getTransport(), { type: 'SUBMIT_WORKFLOW', payload: { body, idempotencyKey } }, 'WORKFLOW_SUBMITTED', { timeoutMs: WORKFLOW_REQUEST_TIMEOUT_MS });
-            // 🔴 PUBLISH THE SNAPSHOT BEFORE THE REJECTION BELOW, for the same reason
-            // `estimate` does: a block may render from `result` rather than from the
-            // returned value, and jumping over this line would leave the PREVIOUS
-            // submit's snapshot in place — a live control pointing at a workflow THIS
-            // submit did not queue.
-            setResult(snapshot);
-            // 🔴 AN ERRORED SUBMIT MUST REJECT (civitai/civitai-app-starters#251, the
-            // `submit` half of civitai/civitai#4159). Two producers report
-            // `status:'failed'` and `status` separates neither:
-            //
-            //   - a budget / spend-cap REJECTION is an OUTCOME the block recovers from
-            //     (open a top-up flow). The server quotes the price it refused to
-            //     charge, so `cost.total` is present. It RESOLVES — turning this arm
-            //     into a throw is the one change that would break the recovery path.
-            //   - a failure-shaped reply with NO `cost` is not a usable outcome. It
-            //     REJECTS — and the `code` says which kind, because they differ on
-            //     whether money moved (see WorkflowSubmitError.code).
-            //
-            // BOTH clauses are load-bearing. Dropping `status === 'failed'` would
-            // reject every ordinary in-flight reply (`{status:'pending'}` is cost-less
-            // too); dropping the cost test would reject the budget rejection. And the
-            // test is `typeof … !== 'number'`, never `!snapshot.cost?.total`: `0` is a
-            // real price and falsy.
-            //
-            // 🔴 `status === 'failed'`, NOT `TERMINAL_STATUSES.has(status)`. Widening it
-            // would reject cost-less `succeeded`/`canceled`/`expired` replies, which are
-            // legitimate outcomes the server really does emit without a price
-            // (`snapshotFromWorkflow` omits `cost` on any non-numeric total). That
-            // WIDENING is invisible to a mutation sweep that only deletes clauses, so
-            // all three statuses are pinned by their own fixtures in the test file.
-            if (snapshot.status === 'failed' && typeof snapshot.cost?.total !== 'number') {
-                // 🔴 WHICH ARM: the host stamps its own synthesised failures with the
-                // `'failed'` sentinel, while a server-built reply carries `workflow.id`
-                // (or the `'whatif'` sentinel).
-                // Anything unrecognised falls to `'workflow-failed'`, the arm that assumes
-                // money MAY be committed — an unknown id must never buy the reassuring
-                // "nothing was charged" reading.
-                throw new WorkflowSubmitError(snapshot, snapshot.workflowId === HOST_SYNTHESISED_WORKFLOW_ID ? 'exception' : 'workflow-failed');
-            }
-            setStatus(TERMINAL_STATUSES.has(snapshot.status) ? 'done' : 'polling');
-            return snapshot;
+            return await withConsentRetry(getTransport(), WORKFLOW_SCOPES, () => submitOnce(body, idempotencyKey), options, 
+            // Rule 3 in the time axis — see `mountedRef` above for why this hook
+            // needs it even though it has no `AbortController`.
+            () => mountedRef.current);
         }
         catch (err) {
             setError(err);
             setStatus('error');
             throw err;
         }
-    }, []);
+    }, [submitOnce]);
     /**
      * ONE poll round-trip, with an optional long-poll hint. The single place that
      * builds a `POLL_WORKFLOW` message, so `poll` and `watch` cannot drift on the

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;
     /**