@civitai/blocks-react 0.60.0 → 0.61.0

package/dist/internal/liveHost.js

@@ -435,6 +435,19 @@ export function createLiveHost(options) {
     // the host that is otherwise the closest thing to prod.
     let currentTheme = theme;
     let pushToBlock = null;
+    // The sub-path the block has been TOLD about, and whether it has been told
+    // anything at all. Together these reproduce the production host's gate
+    // (`PageBlockHost.tsx`: `if (!initSentRef.current || status !== 'ready')
+    // return;` with deps `[subPath, status, send]`), which fires `ROUTE_CHANGED`
+    // only AFTER init and only when the resolved sub-path CHANGES.
+    //
+    // 🔴 SEEDED FROM THE INIT CONTEXT, NOT FROM `''`. The first value reaches the
+    // block in `BLOCK_INIT.context.subPath`, so a harness given
+    // `options.context: { …, subPath: 'compare/42' }` must not then push
+    // `ROUTE_CHANGED { subPath: 'compare/42' }` as if it were a change — the real
+    // host's effect does not fire for the value init already carried.
+    let currentSubPath = '';
+    let initDispatched = false;
     function install() {
         if (installed)
             return teardown;
@@ -523,6 +536,11 @@ export function createLiveHost(options) {
                 theme: currentTheme,
             };
             const context = hostContextWithTheme(baseContext, currentTheme);
+            // Seed the route ledger from what init actually carries, so the first
+            // `ROUTE_CHANGED` is a change rather than a restatement — see the
+            // declaration of `currentSubPath`.
+            currentSubPath =
+                'subPath' in context && typeof context.subPath === 'string' ? context.subPath : '';
             const initPayload = {
                 blockInstanceId: decoded.blockInstanceId ?? 'page_live',
                 blockId: decoded.blockId ?? 'live-block',
@@ -539,7 +557,61 @@ export function createLiveHost(options) {
                     : {}),
             };
             dispatchToBlock({ type: 'BLOCK_INIT', payload: initPayload });
+            initDispatched = true;
         }
+        /**
+         * Reflect a route move back into the block over `ROUTE_CHANGED`, the way
+         * `PageBlockHost` does — the second half of an app-scoped `NAVIGATE`, and
+         * the only way a block learns where a shallow push put it.
+         *
+         * 🔴 THIS REPLACED A SYNTHETIC `popstate`. The earlier shape of this handler
+         * dispatched `new PopStateEvent('popstate')` after `pushState`, which made a
+         * history-based router in the block re-render — in `dev:live` only. Nothing
+         * in production dispatches a `popstate` for a host-side shallow push, so a
+         * block that worked here still showed the wrong view on civitai.com: the
+         * #5209 symptom with its sign flipped, which is the shape that keeps a
+         * platform bug invisible. The message is the real channel; this emits it.
+         *
+         * Three gates, all mirroring the host's own effect:
+         *  - AFTER INIT. The initial sub-path travels in `BLOCK_INIT.context`, and a
+         *    push the transport receives before init has no `context.subPath` to
+         *    update, so it would be silently dropped anyway.
+         *  - ONLY ON A CHANGE. The host's effect is keyed on `[subPath, …]`, so a
+         *    navigation to the route already showing produces no message.
+         *  - CURRENT FRAME ONLY. A `new_tab` navigation does not move THIS frame's
+         *    route, so it must not emit — see the call sites.
+         */
+        const reflectRoute = (subPath) => {
+            if (!initDispatched)
+                return;
+            if (subPath === currentSubPath)
+                return;
+            currentSubPath = subPath;
+            dispatchToBlock({ type: 'ROUTE_CHANGED', payload: { subPath } });
+        };
+        /**
+         * The sub-path `win.location` currently names, in the shape the host sends:
+         * the segment below the app root, with no leading slash (`''` on the index).
+         *
+         * In `dev:live` the block IS the page, served at this dev origin's own root,
+         * so the app root is `/` and the whole pathname below it is the sub-path.
+         * That is the same mapping the app-scope branch of `NAVIGATE` applies in the
+         * other direction (`/<path>` on this origin), kept in ONE place so the two
+         * cannot disagree.
+         */
+        const subPathFromLocation = () => win.location.pathname.replace(/^\/+/, '');
+        // The viewer's OWN back/forward, which production reports too: the host's
+        // effect is keyed on the resolved `subPath`, so it fires for a history move
+        // nobody asked for exactly as it does for a `NAVIGATE`. Without this a block
+        // written against `useCivitaiRoute()` would follow its own navigations here
+        // and ignore the back button — a divergence in the opposite direction to the
+        // one this PR closes, but a divergence.
+        //
+        // `pushState` does NOT fire `popstate`, so our own pushes do not come back
+        // through here; the change gate in `reflectRoute` makes a double-fire inert
+        // regardless.
+        const onPopState = () => reflectRoute(subPathFromLocation());
+        win.addEventListener('popstate', onPopState);
         /**
          * Open the in-harness picker overlay and resolve it into a picker-result
          * message. `resultType` is the inbound message type the block awaits
@@ -1535,21 +1607,136 @@ export function createLiveHost(options) {
                         return;
                     }
                     case 'NAVIGATE': {
-                        const path = typed.payload?.path ?? '';
-                        const target = typed.payload?.target ?? 'current';
-                        // Resolve relative paths against the backend origin so an in-app
-                        // path (`/models/123`) opens on the real site.
-                        const url = /^https?:\/\//i.test(path) ? path : `${baseUrl}${path}`;
+                        // 🔴 THIS HANDLER USED TO SEND EVERY PATH TO THE REAL SITE, AND THAT
+                        // IS WHY `dev:live` AND PRODUCTION DISAGREED. It resolved any
+                        // relative path against `baseUrl` — "so an in-app path
+                        // (`/models/123`) opens on the real site" — while production
+                        // resolved the same call under the block's OWN route. So the docs
+                        // and the dev harness agreed with each other and production was the
+                        // odd one out, which is exactly the shape that makes a platform bug
+                        // look like a block bug (civitai#5209).
+                        //
+                        // It now mirrors the merged contract, DEFAULT INCLUDED:
+                        //   scope absent / anything but 'site'  → APP space (this dev origin)
+                        //   scope === 'site'                    → SITE space (`baseUrl`)
+                        // compared against the literal 'site' rather than validated against
+                        // the union, so an unknown value fails CLOSED onto the narrower
+                        // space — byte-for-byte the host's own test.
+                        //
+                        // 🔴 WHAT IS DELIBERATELY *NOT* MIRRORED: the host's hostile-path
+                        // battery (control characters, backslashes, `%2f`/`%5c`,
+                        // the resolved-vs-sent segment-structure rule, app containment).
+                        // Those guard an UNTRUSTED iframe. In `dev:live` there is no
+                        // untrusted party — the developer's own code, their own dev token,
+                        // their own browser — so copying ~200 lines of security-critical
+                        // resolver here would buy no safety and create a second, non-
+                        // authoritative copy of it to drift. What IS mirrored is the
+                        // CONTRACT a block author can be honestly wrong about: which space
+                        // a path lands in, the `'app'` default, and the two refusals the
+                        // published docs promise (a scheme, and `/api/*` in site scope).
+                        const payload = typed.payload ?? {};
+                        const rawPath = typeof payload.path === 'string' ? payload.path : '';
+                        const target = payload.target ?? 'current';
+                        const scope = payload.scope === 'site' ? 'site' : 'app';
+                        // A scheme or protocol-relative reference is refused by the host in
+                        // BOTH scopes — a block cannot move the host to another origin. This
+                        // harness used to pass an absolute URL straight through, so a
+                        // `navigate('https://example.com/x')` that production DROPS worked
+                        // here. Refuse it, and say so: a silent drop in a dev harness is the
+                        // thing a dev then blames on their own code.
+                        if (/^[a-zA-Z][a-zA-Z0-9+.\-]*:/.test(rawPath) || /^\/[/\\]/.test(rawPath)) {
+                            logOnce('navigate-off-origin', `NAVIGATE to ${JSON.stringify(rawPath)} was DROPPED: the host refuses any scheme ` +
+                                'or protocol-relative path, in either scope. Pass a path within a scope ' +
+                                "(`navigate('models/123', { scope: 'site' })`) instead of a full URL.");
+                            return;
+                        }
+                        // Leading slashes are normalised away in BOTH scopes — `scope`
+                        // already said which space this is, so the slash has nothing left to
+                        // mean. Do not reintroduce punctuation semantics here.
+                        const path = rawPath.replace(/^\/+/, '');
+                        if (scope === 'site') {
+                            // The host's one content-based refusal: `/api/*` is not a page
+                            // route, and `/api/auth/logout` takes a bare GET. Kept here because
+                            // it is part of the PUBLISHED contract, not because this harness is
+                            // a security boundary — a dev who hits it in production should hit
+                            // it in `dev:live` too.
+                            //
+                            // 🔴 BY DECODED VALUE, LIKE THE HOST — not by spelling. An earlier
+                            // revision compared `path.split('/')[0]` raw and said so in a
+                            // comment, which left `%61pi/auth/logout` refused in production and
+                            // followed here: the published contract mirrored with the one input
+                            // shape that defeats it. Deleting the branch instead was the other
+                            // coherent option and was rejected — the refusal is part of the
+                            // PUBLISHED contract (not of any security boundary this harness
+                            // pretends to be), so a dev who hits it in production should hit it
+                            // in `dev:live` too, and a mirror that is wrong for one input is
+                            // worse than either having it or not.
+                            //
+                            // This is NOT the host's "two spellings of one rule" case, which
+                            // deleted a `first.toLowerCase() === 'api'` fast path sitting
+                            // ALONGSIDE the decoded comparison and provably unable to reach a
+                            // verdict the survivor did not (`decodeURIComponent('api')` is
+                            // `'api'`; a mutation run showed it SURVIVED every test). There was
+                            // only ever one comparison here, and it was the wrong one.
+                            //
+                            // Both of the host's refusal channels, in its order
+                            // (`navigateSiteFirstSegmentIsRefused`): a first segment whose
+                            // meaning cannot be established — a malformed escape like `%zz` —
+                            // is refused too, because an undecodable segment is not evidence
+                            // that it is not `api`. Fails CLOSED, like the host.
+                            if (navigateSiteFirstSegmentIsRefused(path)) {
+                                logOnce('navigate-api', `NAVIGATE to ${JSON.stringify(rawPath)} was DROPPED: in site scope the host ` +
+                                    'refuses a first segment that decodes to `api`, and refuses one it cannot ' +
+                                    'decode at all. Only page routes are reachable.');
+                                return;
+                            }
+                            try {
+                                const url = `${baseUrl}/${path}`;
+                                if (target === 'new_tab') {
+                                    win.open(url, '_blank');
+                                }
+                                else {
+                                    win.location.assign(url);
+                                }
+                            }
+                            catch {
+                                /* navigation may be unavailable (tests) */
+                            }
+                            return;
+                        }
+                        // APP scope. Production resolves this under `<base>/<slug>/<path>`
+                        // and pushes it SHALLOWLY, keeping the page mounted. In `dev:live`
+                        // the block IS the page, served at this dev origin's own root, so the
+                        // faithful analogue is `/<path>` on THIS origin — and `pushState`
+                        // rather than `assign`, because a full load is precisely what
+                        // "shallow" excludes.
+                        //
+                        // 🔴 `reflectRoute` IS WHAT MAKES IT WORK rather than merely move the
+                        // URL bar — and it is the production channel, not a local analogue
+                        // of one. Production reflects the new sub-path back into the block
+                        // over `ROUTE_CHANGED`; so does this now. An earlier revision
+                        // dispatched a synthetic `popstate` here instead, "since this SDK
+                        // models no `ROUTE_CHANGED`" — which made a history router re-render
+                        // HERE and nowhere else, because no production host dispatches a
+                        // `popstate` for its own shallow push. That is the #5209 failure
+                        // class with its sign flipped, and a dev harness that is kinder than
+                        // production is how #5209 stayed invisible in the first place.
+                        //
+                        // Emitted only in the `current` arm: a `new_tab` navigation does not
+                        // move THIS frame's route, and the host's effect is keyed on the
+                        // sub-path of the page it is actually rendering.
                         try {
+                            const url = `${win.location.origin}/${path}`;
                             if (target === 'new_tab') {
                                 win.open(url, '_blank');
                             }
                             else {
-                                win.location.assign(url);
+                                win.history.pushState(null, '', url);
+                                reflectRoute(path);
                             }
                         }
                         catch {
-                            /* navigation may be unavailable (tests) */
+                            /* history/navigation may be unavailable (tests) */
                         }
                         return;
                     }
@@ -1622,6 +1809,14 @@ export function createLiveHost(options) {
             torn = true;
             installed = false;
             pushToBlock = null;
+            // Symmetric with the `addEventListener` in `install` — a listener that
+            // outlived the host would keep pushing `ROUTE_CHANGED` at a block whose
+            // host is gone (and, across a re-install, from two hosts at once).
+            win.removeEventListener('popstate', onPopState);
+            // The next install re-dispatches BLOCK_INIT and re-seeds the route from
+            // its context, so neither piece of route state may survive this teardown.
+            initDispatched = false;
+            currentSubPath = '';
             for (const t of timers)
                 clearTimeout(t);
             timers.clear();
@@ -1686,6 +1881,42 @@ export function createLiveHost(options) {
 function anonFallbackViewer() {
     return { id: 0, username: 'dev-live', signedIn: true };
 }
+/**
+ * SITE-scope refusal on a path's FIRST segment, by DECODED value — the dev-host
+ * mirror of the host's own `navigateSiteFirstSegmentIsRefused`
+ * (civitai/civitai `src/components/AppBlocks/pageBlockHostLogic.ts`).
+ *
+ * `path` arrives already stripped of leading slashes by the caller, so segment 0
+ * is `path.split('/')[0]`.
+ *
+ * TWO CHANNELS, and the second is the reason the host named the function
+ * "…IsRefused" rather than "…IsApi":
+ *  1. the segment DECODES to `api` (case-insensitively) — the `/api/*` rule the
+ *     published docs promise, which `%61pi` must not evade;
+ *  2. the segment cannot be decoded at all (`%zz`, a bare `%`) — its meaning
+ *     cannot be established, so it is not pushed. A deliberate fail-closed
+ *     decision, and it means this returns `true` for a segment that is not `api`.
+ *
+ * ⚠️ IT IS THE CONTRACT MIRROR, NOT A SECURITY BOUNDARY. The host's hostile-path
+ * battery (control characters, backslashes, `%2f`/`%5c`, the resolved-vs-sent
+ * segment-structure rule, app containment) is deliberately NOT mirrored in this
+ * harness — see the `NAVIGATE` case — so unlike the host, this cannot rely on
+ * `%2f` already being refused and a decode here CAN introduce a separator
+ * (`a%2fb` decodes to `a/b`). That costs nothing for the question being asked:
+ * only whether segment 0 means `api`, and a decode that produces a separator
+ * cannot turn a non-`api` segment into an `api` one.
+ */
+function navigateSiteFirstSegmentIsRefused(path) {
+    const first = path.split('/')[0] ?? '';
+    let decoded;
+    try {
+        decoded = decodeURIComponent(first);
+    }
+    catch {
+        return true;
+    }
+    return decoded.toLowerCase() === 'api';
+}
 /**
  * Extract the `snapshot` from a tRPC response. Handles the superjson
  * `{ result: { data: { json: T } } }` envelope AND the transformer-less

package/dist/internal/mockHost.js

@@ -38,7 +38,7 @@
  * this from production code.
  */
 import { APP_STORAGE_ERROR_REQUEST_FAILED, APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED, APP_STORAGE_ERROR_USER_ROW_LIMIT, APP_STORAGE_ERROR_VALUE_TOO_LARGE, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, APP_STORAGE_MAX_VALUE_BYTES, BrowsingLevel, SFW_LEVELS, } from '@civitai/app-sdk/blocks';
-import { consentUnavailablePayload, resolveUngrantableConsentNotice } from './consent.js';
+import { consentUnavailablePayload, isKnownBlockScope, resolveUngrantableConsentNotice, } from './consent.js';
 import { hostContextWithTheme } from '../transport/transport.js';
 import { isRoutableRequestId } from '../transport/requestId.js';
 /**
@@ -831,6 +831,29 @@ export function createMockHost(options = {}) {
         const parentOrigin = win.location.origin;
         const originalParent = win.parent;
         let consentGranted = !!options.consentGranted;
+        /**
+         * Scopes granted by a `REQUEST_CONSENT` round-trip OTHER than
+         * `ai:write:budgeted` (which keeps its own flag, because `buzzBudget` is
+         * conditional on it and `setScenario` can toggle it).
+         *
+         * 🔴 WHY THIS EXISTS. The grant branch used to hand back exactly
+         * `[BUDGETED_SCOPE]` and nothing else, so on this host NO consent-gated
+         * scope but the money one could EVER appear on a token. That was invisible
+         * while nothing waited on a grant; it stops being invisible the moment the
+         * SDK does (`internal/withConsentRetry.ts`), because a block asking for
+         * `posts:write:self` would be "granted" a token that still lacks it and
+         * would sit out the full wait on a host that had already said yes. The real
+         * host grants the missing set it computed from the manifest, so modelling it
+         * as "grant what was asked for, filtered to the known vocabulary" is closer
+         * than the constant was — and a dev host that quietly diverges here is
+         * precisely what `./consent.js`'s header warns about.
+         */
+        const extraGrantedScopes = new Set();
+        /** Everything the CURRENT token carries. One reader, so the two cannot drift. */
+        const currentScopes = () => [
+            ...(consentGranted ? [BUDGETED_SCOPE] : []),
+            ...extraGrantedScopes,
+        ];
         let tokenSerial = 0;
         let submitCount = 0;
         // body + cost remembered per workflow so the succeeded snapshot can echo them.
@@ -851,7 +874,7 @@ export function createMockHost(options = {}) {
             tokenSerial += 1;
             return {
                 raw: `${DEV_TOKEN}.${tokenSerial}`,
-                scopes: consentGranted ? [BUDGETED_SCOPE] : [],
+                scopes: currentScopes(),
                 expiresAt: new Date(Date.now() + 15 * 60_000).toISOString(),
                 ...(consentGranted ? { buzzBudget } : {}),
             };
@@ -913,11 +936,11 @@ export function createMockHost(options = {}) {
                             // `createLiveHost` via ./consent.js so dev and prod cannot drift
                             // on when this fires or what it names.
                             const notice = resolveUngrantableConsentNotice(typed.payload?.scopes, 
-                            // The scopes the CURRENT token carries. Computed inline rather
-                            // than read off `nextToken()` — that helper MINTS (it bumps
-                            // `tokenSerial`), so calling it here would burn a serial on a
-                            // path that issues no token.
-                            consentGranted ? [BUDGETED_SCOPE] : [], 
+                            // The scopes the CURRENT token carries. Read through
+                            // `currentScopes()` rather than `nextToken()` — that helper MINTS
+                            // (it bumps `tokenSerial`), so calling it here would burn a
+                            // serial on a path that issues no token.
+                            currentScopes(), 
                             // Nothing is grantable — that is what `consentGrantable:false`
                             // MEANS. Passing the empty set here (rather than short-circuiting)
                             // keeps this call identical in shape to the host's.
@@ -934,10 +957,45 @@ export function createMockHost(options = {}) {
                             });
                             return;
                         }
-                        // Lazy-consent round-trip: grant the scope, then push a
+                        // Lazy-consent round-trip: grant what the hint named, then push a
                         // host-initiated TOKEN_REFRESH carrying it (the App's auto-resume
                         // depends on seeing the new scope on its token).
-                        consentGranted = true;
+                        //
+                        // `scopes` is untrusted block input (it is where markup and 5 KB
+                        // strings arrive), so it is filtered to the known vocabulary exactly
+                        // as the refusal payload is — `isKnownBlockScope` is the same
+                        // predicate both branches use.
+                        //
+                        // 🔴 `consentGranted` IS THE MONEY FLAG, SO IT IS GRANTED ONLY WHEN
+                        // ASKED FOR. It puts `ai:write:budgeted` AND `buzzBudget` on every
+                        // token this host mints from here on. Setting it unconditionally
+                        // meant a `posts:write:self` request also handed out the money
+                        // scope, which made the PARTIAL-GRANT case — the viewer granting the
+                        // one permission the block asked for and nothing else — unreachable
+                        // in `pnpm dev`, so every local run exercised the one shape that
+                        // hides a missing-scope bug.
+                        //
+                        // ⚠️ THE `!granted.length` FALLBACK IS LOAD-BEARING, not tidiness:
+                        // `requestConsent()` with NO payload is documented as legitimate (the
+                        // real host already knows the missing set it computed at mint), and
+                        // so is a hint that survives no filtering. Both must keep granting
+                        // the default money scope, which is the pre-existing behaviour — a
+                        // grant branch that granted nothing at all would be a silent dead
+                        // end of exactly the kind `consentGrantable` was added to remove.
+                        {
+                            const hint = typed.payload
+                                ?.scopes;
+                            const granted = Array.isArray(hint)
+                                ? hint.filter((s) => typeof s === 'string' && isKnownBlockScope(s))
+                                : [];
+                            if (granted.length === 0 || granted.includes(BUDGETED_SCOPE)) {
+                                consentGranted = true;
+                            }
+                            for (const s of granted) {
+                                if (s !== BUDGETED_SCOPE)
+                                    extraGrantedScopes.add(s);
+                            }
+                        }
                         after(0, () => {
                             dispatchToBlock({ type: 'TOKEN_REFRESH', payload: { token: nextToken() } });
                         });

package/dist/internal/withConsentRetry.d.ts

@@ -0,0 +1,239 @@
+import type { ConsentRetryOptions } from '../hooks/consentRetryOptions.js';
+import type { BlockTransport } from '../transport/transport.js';
+/**
+ * THE ONE PLACE consent prompt-and-retry lives.
+ *
+ * ## The problem it exists to remove
+ *
+ * A block calls a capability whose consent-gated scope its token was minted
+ * without. The call fails. Before this module every hook re-threw, and the app
+ * had to write the prompt-then-retry dance itself:
+ *
+ * ```ts
+ * try {
+ *   await submit(body);
+ * } catch {
+ *   requestConsent({ scopes: ['ai:write:budgeted'] });
+ *   // …now watch useBlockToken().scopes, and retry — with the SAME key.
+ * }
+ * ```
+ *
+ * Almost nobody wrote it — so a working app looked broken. This module makes
+ * prompt-and-retry the DEFAULT, and every consent-gated hook routes through it
+ * rather than open-coding its own copy (a predicate duplicated at N call sites
+ * is typically wrong at N-1 of them, in the same direction).
+ *
+ * ## 🔴 THE MONEY RULE — READ THIS BEFORE CHANGING ANYTHING HERE
+ *
+ * `withConsentRetry` RE-INVOKES A CALLER-SUPPLIED CLOSURE. It does not build
+ * the request, and it deliberately cannot: the idempotency key is minted by the
+ * caller BEFORE the first attempt and captured in that closure, so both
+ * attempts carry the SAME value. `useBuzzWorkflow`'s own docs are explicit —
+ * *"A retry is a SECOND reservation unless you reuse the same idempotencyKey…
+ * `submit()` mints a fresh key per call by default, so an automatic retry
+ * double-reserves."* A version of this helper that took `(body, options)` and
+ * re-sent the message itself would mint a second key and double-charge a real
+ * person.
+ *
+ * So the contract for every call site is one line long: **mint the key outside
+ * the closure.** `test/withConsentRetry.test.tsx` asserts the literal key value
+ * on BOTH wire calls, and that assertion is mutation-checked.
+ *
+ * ## The predicate: STRUCTURAL, not a string match
+ *
+ * "Was this a consent failure?" cannot be answered from the error. Almost every
+ * bridge in this package reports host-side failure as a FREE-TEXT string the
+ * host forwards verbatim (`BUZZ_BALANCE_RESULT`, `PUBLISH_RESULT`,
+ * `APP_WORKFLOWS_RESULT`, … all say so in `messages.ts`), so a
+ * `/insufficient.scope/i` test would be a guess about server copy that can
+ * change without notice — the "spelled rather than structural" guard shape.
+ *
+ * The test used instead is a property of the TOKEN, read at the moment of
+ * failure: **does the token still lack a scope this operation requires?** That
+ * is true by definition for every genuine consent failure (a consent gate IS an
+ * absent scope) and false for the overwhelming majority of everything else — a
+ * rate limit, a 5xx, a malformed body all happen while the token HOLDS the
+ * scope, so those re-throw untouched with no prompt and no retry.
+ *
+ * ⚠️ It is a necessary condition, not a sufficient one. A NON-consent failure
+ * that happens while the token is ALSO missing the scope (a 500 on a submit
+ * from an un-granted token) will prompt and retry. That is the deliberate
+ * direction to be wrong in: the call needed that scope anyway, so the prompt is
+ * correct, and the retry is same-key. The inverse — string-matching, and so
+ * silently failing to prompt when a host reworded its error — is the failure
+ * this shape cannot have.
+ *
+ * ## The three hard rules
+ *
+ *  1. **EXACTLY ONE RETRY.** There is no loop, and adding one would be a defect
+ *     rather than a tuning choice: a second consent failure means the grant did
+ *     not fix the problem, so a third attempt is a third money reservation for
+ *     nothing. The second failure propagates to the caller verbatim.
+ *  2. **NEVER RETRY THROUGH A `CONSENT_UNAVAILABLE` FOR THE SCOPES IT NAMED.**
+ *     That push means the scope was clamped or withheld at mint and NO consent
+ *     round-trip in this environment can ever add it, so a retry is a guaranteed
+ *     second failure. Read via `readConsentRefusalLatch` — the existing buffer —
+ *     rather than a second subscription, so there is one source of truth for
+ *     "has the host refused". Checked BEFORE the prompt, and again as the wait's
+ *     own losing arm (a refusal that arrives in answer to THIS prompt).
+ *
+ *     🔴 **THE LATCH READ IS SCOPE-AWARE, NOT TRANSPORT-GLOBAL — see
+ *     {@link isRefusalFinalFor}.** The latch is one slot per transport, so
+ *     treating any refusal as final disabled prompt-and-retry for EVERY hook and
+ *     EVERY scope until the token rotated (~13 min). The justification does not
+ *     reach that far: "clamped at mint" is a claim about the REFUSED scopes, and
+ *     a retry for a scope the host never refused is not a guaranteed second
+ *     failure.
+ *
+ *     ⚠️ THE WAIT'S LOSING ARM IS NOT SCOPE-CHECKED, deliberately. A
+ *     `CONSENT_UNAVAILABLE` arriving *during* the wait ends it whatever it names.
+ *     The prompt that opened this wait asked for exactly `missing`, so in
+ *     practice a refusal answering it is about those scopes; the only way to be
+ *     wrong is a concurrent prompt for a DIFFERENT scope set being refused at the
+ *     same moment, and being wrong there costs one needlessly-surfaced original
+ *     error — never a spend, never a duplicate write. Scope-checking it would add
+ *     a way to be wrong in the OTHER direction (waiting on past a real refusal),
+ *     which is the expensive one.
+ *  3. **NEVER RETRY AN ABORT, OR A CALLER THAT WENT AWAY DURING THE WAIT.** An
+ *     `AbortError` means the caller's component unmounted or its own bound
+ *     elapsed — work that was cancelled on purpose must not be silently
+ *     resurrected, least of all on a money path.
+ *
+ *     🔴 **AN UNMOUNT LANDING IN THE 60s WAIT IS THE SAME RULE IN THE TIME
+ *     AXIS, and it needs its own check** (`isActive`, below): there is no
+ *     in-flight request to abort at that point, so nothing produces an
+ *     `AbortError` and the grant drove a second `attempt()` against a component
+ *     that no longer exists. On `useTip` that meant a transfer left the viewer's
+ *     balance with no UI left to report it — and with the hook's `inFlight` set
+ *     already cleared, that second POST was not even abortable.
+ *  4. **NEVER RETRY A VIEWER REFUSAL, A SIGN-IN REQUIREMENT, OR A KEYLESS
+ *     BRIDGE'S TIMEOUT.** `CreatePostError` and `CollectionFollowError` both
+ *     carry `declined === true` when the person dismissed the host's own
+ *     per-action confirm — an answer, not a failure; re-opening the dialog they
+ *     just closed is nagging. `CreatePostError` also carries
+ *     `signInRequired === true`, which is un-retryable for a stronger reason: no
+ *     amount of scope granting gives a signed-OUT viewer a session, so the
+ *     dialog is one the viewer cannot act on at all and `useRequestSignIn()` is
+ *     what they need — 60s sooner. The same two classes carry
+ *     `timedOut === true`, and `CreatePostError.timedOut`'s own docs say why it
+ *     must not be retried:
+ *     *"the write may have LANDED and only the reply failed to arrive — and here
+ *     the write is a PUBLIC POST under the viewer's name… never retry
+ *     automatically, which is how a duplicate post happens."* Both are keyed on
+ *     the properties those classes already single-source, so a third such error
+ *     joins the rule by declaring them.
+ *
+ *     🔴 **THE RULE `timedOut` ENCODES, IN ONE SENTENCE: a timeout is retryable
+ *     IFF the call carries an idempotency key.** That is a mechanical property,
+ *     not a preference. A timed-out request may have landed server-side; with a
+ *     key the server collapses the re-send into the first result, so the retry
+ *     is a REPLAY. Without one it is a genuine second write — a second public
+ *     post, a second follow. So a hook stamps `timedOut` exactly when its wire
+ *     message has no `idempotencyKey` field: `CREATE_POST_FROM_APP` and the
+ *     collection-follow bridge do, and they stamp it.
+ *
+ *     🔴 **WHERE A HOOK STAMPS IT IS PART OF THE RULE, NOT AN IMPLEMENTATION
+ *     DETAIL — THE STAMP MUST BE INSIDE THE `attempt` CLOSURE.** Until #500
+ *     round 2 `useCreatePostFromApp` applied it in the catch WRAPPED AROUND this
+ *     helper, so the raw `RequestTimeoutError` arrived here carrying neither
+ *     flag, `isCallerMarkedFinal` returned false, and a `posts:write:self`-less
+ *     token got a prompt and a SECOND POST. Rule 4 was unreachable for the one
+ *     bridge it was written for, and `flags.timedOut === true` was dead code:
+ *     deleting that arm left the whole suite green. A stamp applied outside the
+ *     closure is invisible to every rule in this module.
+ *
+ *     The three money paths — `useBuzzWorkflow.submit`, `useGoodPurchase` and
+ *     `useTip` — all mint a key ABOVE the retry and hand the same value to both
+ *     attempts, so none of them stamps it and all three retry a timeout. Their
+ *     own docs prescribe that same-key retry as the recovery. (`useTip` stamped
+ *     it until #500 round 1, which made it the only keyed hook that did not
+ *     retry; that inconsistency is what this paragraph exists to have settled.)
+ *
+ *     ⚠️ An UNMOUNT is a different thing and is covered by rule 3, not this one:
+ *     `useTip` and `useGoodPurchase` both name their unmount abort `AbortError`
+ *     and leave the bound-elapsed timeout a plain `Error`, so the two arms reach
+ *     opposite outcomes here.
+ *
+ * ## What it CANNOT detect: a scope absent from the MANIFEST
+ *
+ * A scope the app never declared can never be granted either, and detecting
+ * that BEFORE the first attempt is not possible from inside a block today: the
+ * manifest is a build-time artifact, `BlockSnapshot` carries no `scopes`
+ * declaration (only the token's GRANTED set), and no bridge message exposes
+ * one. What covers it at runtime is rule 2 — the host computes its grantable
+ * set from the manifest, so an undeclared scope is un-grantable and comes back
+ * as `CONSENT_UNAVAILABLE`, which stops the retry. The cost is that this is
+ * paid ONE request/refusal round-trip late rather than pre-flight. Making it
+ * pre-flight needs the manifest on the wire, which is a host change.
+ */
+/**
+ * How long to wait for the viewer to answer the consent dialog.
+ *
+ * 🔴 DELIBERATELY NOT `HUMAN_INTERACTION_TIMEOUT_MS` (10 min), and the
+ * difference is not a preference — it is a property of the message. Every OTHER
+ * human-gated request in this package is a REQUEST the host REPLIES to, so a
+ * dismissal arrives as an answer and the 10-minute ceiling only ever bounds a
+ * dialog nobody touched. `REQUEST_CONSENT` is FIRE-AND-FORGET: it carries no
+ * `requestId`, the host sends nothing on dismiss, and `CONSENT_UNAVAILABLE`
+ * covers only the can-NEVER-be-granted case. So "the viewer closed the dialog"
+ * and "the viewer has not clicked yet" are THE SAME OBSERVABLE — silence — and
+ * whatever this number is, a dismissal costs the caller exactly that long with a
+ * promise still pending. At 10 minutes an app that showed a spinner shows it for
+ * ten minutes, which is a second way to look broken.
+ *
+ * 60s is sized for the thing actually being waited on: a person noticing a modal
+ * the host just opened and pressing a button in it. Past that, the ORIGINAL
+ * error surfaces, the app is responsive again, and a viewer who grants late
+ * loses nothing — their next call sees the scope on the token and never enters
+ * this path at all.
+ *
+ * 🔴 NOT CONFIGURABLE, and that is a decision rather than an omission. A public
+ * `consentTimeoutMs` shipped on five signatures in the first draft of #500 with
+ * no consumer outside this package — its only demonstrated use was shortening
+ * this wait inside one test, which fake timers do without widening the API. If
+ * a real caller ever needs a different bound, that is the moment to add one.
+ */
+export declare const CONSENT_GRANT_WAIT_MS = 60000;
+/**
+ * Post a `REQUEST_CONSENT` with a scopes hint.
+ *
+ * 🔴 Single-sourced with {@link useRequestConsent}, which calls straight into
+ * this function. Two spellings of "arm the latch, then send" is exactly the
+ * shape that lets one of them forget the arming — and a `CONSENT_UNAVAILABLE`
+ * with no listener at the instant it lands falls through the transport's no-op
+ * tail and is gone forever (see `consentRefusalLatch.ts`).
+ */
+export declare function sendRequestConsent(transport: BlockTransport, payload?: {
+    scopes?: string[];
+}): void;
+/**
+ * Which of `required` the transport's CURRENT token does not carry.
+ *
+ * Reads the live snapshot every call rather than closing over a value: a
+ * `TOKEN_REFRESH` can land at any moment, and the whole point of the wait below
+ * is that this answer CHANGES.
+ */
+export declare function missingScopes(transport: BlockTransport, required: readonly string[]): string[];
+/**
+ * Run `attempt`; on a consent-shaped failure, prompt the viewer and run it
+ * EXACTLY ONCE more.
+ *
+ * @param transport the singleton transport (snapshot + consent channel).
+ * @param requiredScopes the consent-gated scopes this operation needs. MUST be
+ *   real {@link BLOCK_SCOPES} values — they are sent to the host as the
+ *   `REQUEST_CONSENT` hint, which is silently ignored unless it holds at least
+ *   one non-empty recognised name. An empty array disables the behaviour.
+ * @param attempt the operation, re-invoked verbatim on retry. 🔴 Mint any
+ *   idempotency key OUTSIDE this closure — see the module header. 🔴 And stamp
+ *   any final-error flag (`timedOut`, `declined`, `signInRequired`) INSIDE it,
+ *   or rule 4 cannot see it.
+ * @param options caller opt-out. One field, `autoRequestConsent` — the 60s wait
+ *   is NOT configurable, see {@link CONSENT_GRANT_WAIT_MS}.
+ * @param isActive rule 3 in the time axis — read IMMEDIATELY BEFORE the retry,
+ *   never cached. A hook passes `() => mountedRef.current`; returning `false`
+ *   re-throws the original error instead of re-invoking `attempt`. Optional so a
+ *   caller with no component to outlive (a plain function, a test) needs nothing,
+ *   and absent means "always active" — the pre-#500-round-2 behaviour.
+ */
+export declare function withConsentRetry<T>(transport: BlockTransport, requiredScopes: readonly string[], attempt: () => Promise<T>, options?: ConsentRetryOptions, isActive?: () => boolean): Promise<T>;
+//# sourceMappingURL=withConsentRetry.d.ts.map