@civitai/blocks-react 0.59.0 → 0.61.0

package/dist/internal/popoverShim.js

@@ -0,0 +1,181 @@
+/**
+ * A minimal stand-in for the HTML popover API, for NON-BROWSER DOMs.
+ *
+ * WHY IT EXISTS (#485). `jsdom` and `happy-dom` do not implement the popover
+ * API at ANY version we could find: `showPopover`, `hidePopover` and
+ * `togglePopover` are `undefined` on happy-dom 20.x and on jsdom 25 and 30 alike.
+ * `:popover-open` is worse than absent — it is unreliable in a way that is NOT a
+ * property of the runner's version: under jsdom it resolves through `nwsapi`, so
+ * the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+ * and returns `false` depending on which `nwsapi` a lockfile pulled in (measured
+ * `false` on nwsapi 2.2.28). Anything that calls into that API therefore explodes,
+ * or lies, in the one environment an App Block's own test suite runs in.
+ *
+ * 🔴 WHAT THIS DOES **NOT** DO, and you must read this before using it.
+ *
+ * It does not make a shadow-DOM component fully driveable under happy-dom.
+ * Measured on happy-dom 20.9.0: a click on a light-DOM child assigned to a
+ * `<slot>` bubbles to the HOST (a listener there fires 1x) but a listener on the
+ * `<slot>` ELEMENT ITSELF fires **0x**. Lit binds `@click` to the `<slot>`, so
+ * `<civitai-menu>`'s trigger click is SILENT there: no throw, no open, nothing.
+ * That is a property of happy-dom's event path through the flattened tree and
+ * this shim cannot fix it — installing it changes the count from 0 to 0. (jsdom
+ * 25 and 30 both DO deliver it, which is why this is probed rather than asserted.)
+ *
+ * So under a shimmed DOM you must drive overlay elements through their METHODS
+ * (`menu.show()` / `menu.hide()`), never by clicking the trigger. {@link
+ * installPopoverShim} PROBES for this on install and returns the result as
+ * {@link PopoverShimHandle.slottedClicksReachSlots}, warning loudly when it is
+ * false, because a shim that quietly made `show()` work while `click()` no-ops
+ * would read as "this element is testable now" while delivering half of it.
+ *
+ * Other deliberate deviations from the platform, all of them narrow:
+ *   - `toggle` is dispatched in a MICROTASK, where the platform queues a task.
+ *     A microtask flushes before the next `await`, which is what makes it
+ *     observable after `await el.updateComplete` in a test; a real task would
+ *     need a `setTimeout` round-trip. `beforetoggle` is not dispatched at all.
+ *   - There is no top layer, no anchor positioning, and no LIGHT DISMISS: a
+ *     click outside a shown popover does not close it. Those need layout and a
+ *     hit-testing event path, neither of which a non-browser DOM has. Light
+ *     dismiss is one of the two reasons `<civitai-menu>` uses popover at all, so
+ *     if that is what you are testing, use a real browser.
+ *   - `popover="manual"` vs `"auto"` is not distinguished (there being no light
+ *     dismiss to distinguish them by).
+ */
+/** The marker attribute a shown popover carries. Internal to the shim. */
+const SHOWN_ATTR = 'data-civitai-popover-open';
+/**
+ * Does a click on a slotted child reach a listener bound to the `<slot>`?
+ *
+ * Built as its own throwaway tree rather than asked of the component under test,
+ * so the answer is about the DOM implementation and not about one element's
+ * wiring. Returns `false` if anything in the probe is unsupported — an
+ * environment that cannot even run the probe certainly cannot deliver the event.
+ */
+function probeSlottedClickReachesSlot(doc) {
+    let host;
+    try {
+        host = doc.createElement('div');
+        const root = host.attachShadow({ mode: 'open' });
+        const slot = doc.createElement('slot');
+        root.append(slot);
+        const child = doc.createElement('button');
+        host.append(child);
+        doc.body.append(host);
+        let slotSaw = 0;
+        slot.addEventListener('click', () => {
+            slotSaw += 1;
+        });
+        child.click();
+        return slotSaw > 0;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        host?.remove();
+    }
+}
+/**
+ * Install the popover shim on the current global DOM. Call it once, in a vitest
+ * `setupFiles` entry or at the top of a test file, BEFORE the elements render.
+ *
+ * Safe and inert in a real browser: it detects a working popover API and patches
+ * nothing (`installed: false`).
+ *
+ * @example
+ * ```ts
+ * import { installPopoverShim } from '@civitai/blocks-react/testing';
+ *
+ * const shim = installPopoverShim();
+ * // Drive overlay elements through their methods — NOT by clicking the trigger.
+ * menu.show();
+ * await menu.updateComplete;
+ * ```
+ */
+export function installPopoverShim(options = {}) {
+    const doc = globalThis.document;
+    const win = globalThis;
+    if (!doc || !win.Element || !win.HTMLElement) {
+        throw new Error('installPopoverShim() needs a DOM. Run it under a vitest `environment` of ' +
+            '`happy-dom` or `jsdom`, not `node`.');
+    }
+    const slottedClicksReachSlots = probeSlottedClickReachesSlot(doc);
+    if (!slottedClicksReachSlots && !options.quiet) {
+        // Loud on purpose. The popover half being fixed is what makes this the
+        // remaining reason a test "does nothing", and a silent no-op click is a far
+        // worse diagnostic than a throw.
+        console.warn('[civitai] popover shim installed, but THIS DOM DOES NOT DELIVER CLICKS ON SLOTTED ' +
+            'CONTENT TO LISTENERS ON THE <slot> (measured on install; happy-dom 20.x behaves this ' +
+            'way). Clicking a component\'s trigger will do nothing at all — no throw, no state ' +
+            'change. Drive overlay elements through their methods instead: `menu.show()` / ' +
+            '`menu.hide()`. See @civitai/blocks-react README § "Testing overlay elements".');
+    }
+    const proto = win.HTMLElement.prototype;
+    const already = typeof proto.showPopover === 'function';
+    if (already) {
+        return { installed: false, slottedClicksReachSlots, uninstall: () => { } };
+    }
+    const shown = new WeakSet();
+    const fireToggle = (el, from, to) => {
+        queueMicrotask(() => {
+            // `ToggleEvent` is undefined in both jsdom and happy-dom, so the two state
+            // fields are attached to a plain Event. Consumers read `event.newState`,
+            // which is what `<civitai-menu>`'s own handler does.
+            const event = new Event('toggle', { bubbles: false, cancelable: false });
+            event.oldState = from;
+            event.newState = to;
+            el.dispatchEvent(event);
+        });
+    };
+    function assertPopover(el) {
+        if (!el.hasAttribute('popover')) {
+            throw new Error('InvalidStateError: showPopover/hidePopover called on an element without a `popover` attribute');
+        }
+    }
+    proto.showPopover = function showPopover() {
+        assertPopover(this);
+        if (shown.has(this))
+            throw new Error('InvalidStateError: popover is already showing');
+        shown.add(this);
+        this.setAttribute(SHOWN_ATTR, '');
+        fireToggle(this, 'closed', 'open');
+    };
+    proto.hidePopover = function hidePopover() {
+        assertPopover(this);
+        if (!shown.has(this))
+            throw new Error('InvalidStateError: popover is not showing');
+        shown.delete(this);
+        this.removeAttribute(SHOWN_ATTR);
+        fireToggle(this, 'open', 'closed');
+    };
+    proto.togglePopover = function togglePopover(force) {
+        const want = force ?? !shown.has(this);
+        if (want && !shown.has(this))
+            this.showPopover();
+        else if (!want && shown.has(this))
+            this.hidePopover();
+        return shown.has(this);
+    };
+    // `:popover-open` is a SELECTOR, so it cannot be shimmed by adding a method —
+    // it has to be rewritten before the engine sees it. `matches` is the entry
+    // point the pseudo-class is reached through in practice; the marker attribute
+    // the two methods above maintain is what it rewrites to, which makes
+    // `:not(:popover-open)` work for free.
+    const nativeMatches = win.Element.prototype.matches;
+    const POPOVER_OPEN = /:popover-open\b/g;
+    win.Element.prototype.matches = function matches(selector) {
+        return nativeMatches.call(this, selector.replace(POPOVER_OPEN, `[${SHOWN_ATTR}]`));
+    };
+    return {
+        installed: true,
+        slottedClicksReachSlots,
+        uninstall() {
+            delete proto.showPopover;
+            delete proto.hidePopover;
+            delete proto.togglePopover;
+            win.Element.prototype.matches = nativeMatches;
+        },
+    };
+}
+//# sourceMappingURL=popoverShim.js.map

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