@civitai/blocks-react 0.58.1 → 0.60.0

package/dist/hooks/useGoodPurchase.js

@@ -0,0 +1,253 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { generateIdempotencyKey } from '../transport/transport.js';
+import { useBlockToken } from './useBlockToken.js';
+import { useBuzzPurchase } from './useBuzzPurchase.js';
+import { useHostOrigin } from './useHostOrigin.js';
+/**
+ * Backstop timeout for the direct REST purchase POST. Like {@link useTip} (and
+ * unlike the postMessage hooks), this talks to the HTTP API directly, so it
+ * needs its OWN bound — otherwise a hung request never rejects.
+ */
+const GOOD_PURCHASE_TIMEOUT_MS = 30_000;
+/**
+ * A refusal the server produced deliberately, as opposed to a transport
+ * failure.
+ *
+ * `reason` is the machine-readable discriminator where one exists — branch on it
+ * rather than on `message`, which is viewer-facing copy and will be reworded.
+ *
+ * 🔴 `reason` IS OFTEN `undefined`, AND A CONSUMER MUST HANDLE THAT. Only the
+ * SERVICE-level refusals carry one (`insufficient_funds`, `ledger_conflict`,
+ * `charge_failed`, `charge_unknown`, the price-disagreement and
+ * already-owned cases). The ENDPOINT's own refusals return `{ error }` alone:
+ * the 404 for an unavailable good, the 429 rate limit, the daily-cap 400 and
+ * every idempotency refusal (409 / 422 / 503). So a `switch (reason)` with no
+ * default silently swallows a material fraction of real failures — always fall
+ * back to `status` plus `message`.
+ */
+export class GoodPurchaseRefusal extends Error {
+    status;
+    reason;
+    constructor(message, status, reason) {
+        super(message);
+        this.name = 'GoodPurchaseRefusal';
+        this.status = status;
+        this.reason = reason;
+    }
+}
+/**
+ * Buy a DIGITAL GOOD for the viewer through the block-token-gated
+ * `POST /api/v1/blocks/goods/purchase` REST endpoint (scope
+ * `goods:purchase:self`).
+ *
+ * Direct-fetch against the VALIDATED host origin (`useHostOrigin()`) with the
+ * block bearer token, the same security-reviewed pattern as {@link useTip}. The
+ * BUYER is always the token subject — the server self-binds it and the block
+ * never supplies a user id, so there is no client-supplied value on the money
+ * path.
+ *
+ * 🔴 BUYING A GOOD AND BUYING BUZZ ARE OPPOSITE DIRECTIONS, AND THIS HOOK
+ * TOUCHES BOTH. A good is Buzz flowing FROM the viewer TO the app owner. The
+ * top-up modal this hook can open ({@link useBuzzPurchase}) is fiat flowing INTO
+ * the viewer's balance. They are different rails with different ledgers; the
+ * only thing they share is that one can unblock the other.
+ *
+ * ⚠️ THE PLATFORM RENDERS NO CONFIRMATION FOR THE PURCHASE ITSELF. This is a
+ * plain authed POST, so whatever confirm UI the viewer sees is the APP's. Spend
+ * is bounded by the good's manifest-reviewed price and the viewer's daily cap,
+ * but a good can be priced near that cap where a tip cannot — so show the price
+ * and get an explicit action before calling this.
+ *
+ * @example
+ * const { purchase, loading, error } = useGoodPurchase();
+ * const { entitlement } = await purchase(
+ *   { goodId: 'extra-slots', expectedPriceBuzz: 250 },
+ *   { topUpOnInsufficientFunds: true },
+ * );
+ */
+export function useGoodPurchase() {
+    const host = useHostOrigin();
+    const { raw } = useBlockToken();
+    const { openPurchaseModal } = useBuzzPurchase();
+    const [loading, setLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const mountedRef = useRef(true);
+    const inFlight = useRef(new Set());
+    useEffect(() => {
+        mountedRef.current = true;
+        const controllers = inFlight.current;
+        return () => {
+            mountedRef.current = false;
+            for (const c of controllers)
+                c.abort();
+            controllers.clear();
+        };
+    }, []);
+    const postOnce = useCallback(async (params, idempotencyKey) => {
+        const controller = new AbortController();
+        inFlight.current.add(controller);
+        // Which abort fired is not recoverable from the signal — both a timeout
+        // and the unmount cleanup set `aborted` — so record it at the source.
+        // The two need OPPOSITE handling below, and conflating them is how a
+        // money-path timeout gets swallowed by an unmount-ignoring caller.
+        let timedOut = false;
+        const timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, GOOD_PURCHASE_TIMEOUT_MS);
+        try {
+            const res = await fetch(`${host}/api/v1/blocks/goods/purchase`, {
+                method: 'POST',
+                headers: { Authorization: `Bearer ${raw}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    goodId: params.goodId,
+                    ...(params.expectedPriceBuzz != null
+                        ? { expectedPriceBuzz: params.expectedPriceBuzz }
+                        : {}),
+                    idempotencyKey,
+                }),
+                signal: controller.signal,
+            });
+            // 🔴 AN ABORT DURING THE BODY READ MUST NOT BE SWALLOWED AS "no body".
+            // With a real `fetch` the response headers can arrive and the BODY still
+            // be in flight; aborting then rejects `res.json()` with an `AbortError`.
+            // A blanket `.catch(() => null)` turned that into `bodyJson === null`,
+            // and the classification below — which reads the BODY rather than the
+            // abort state — then produced exactly the wrong answer twice:
+            //
+            //   200 + unmount mid-body → a `malformed_success` refusal saying "the
+            //   charge may have landed", reported to a caller the docs told to
+            //   IGNORE navigate-away aborts. A purchase that SUCCEEDED, surfaced as
+            //   a possible-charge failure.
+            //
+            //   4xx + timeout mid-body → `purchase request failed (<status>)` with
+            //   `reason` lost, so the documented timeout error and its same-key
+            //   retry advice never reached the caller.
+            //
+            // So a parse failure is only "no body" when the request was NOT aborted;
+            // otherwise it is rethrown and the `catch` below classifies it by the
+            // abort state, which is the only thing that can tell a timeout from an
+            // unmount. A genuinely unparseable body on a live request still yields
+            // `null` and the malformed/refusal handling below is unchanged.
+            const bodyJson = (await res.json().catch((err) => {
+                if (controller.signal.aborted)
+                    throw err;
+                return null;
+            }));
+            if (!res.ok) {
+                throw new GoodPurchaseRefusal(bodyJson?.error ?? `purchase request failed (${res.status})`, res.status, bodyJson?.reason);
+            }
+            // 🔴 VALIDATE THE 2xx, because the declared return type promises an
+            // entitlement. Without this an unparseable 200 resolved as `null` and a
+            // wrong-shaped one resolved with `entitlement === undefined` — and the
+            // documented usage destructures it, so both surfaced as a TypeError in
+            // the app rather than as a failed purchase. On this hook the body IS the
+            // granted entitlement, so a caller cannot recover from a silent absence.
+            // `useEntitlements` in this same package performs the equivalent check.
+            //
+            // 🔴 `purchase` IS CHECKED TOO, and for the same reason `entitlement` is:
+            // `GoodPurchaseResult` declares it REQUIRED, so `result.purchase.id` is
+            // typed as safe and a body of `{ ok: true, entitlement }` alone would
+            // resolve and then TypeError at the dereference. The live 200 path
+            // (`src/pages/api/v1/blocks/goods/purchase.ts`) always sends all three,
+            // so this is the type's promise being kept rather than a reachable
+            // server bug — but an `as`-cast past an unvalidated required field is
+            // exactly how the `entitlement` case reached an app in the first place.
+            if (bodyJson == null ||
+                bodyJson.ok !== true ||
+                bodyJson.entitlement == null ||
+                bodyJson.purchase == null) {
+                throw new GoodPurchaseRefusal(`purchase succeeded (${res.status}) but the response was not a purchase result — the charge may have landed; do not retry without the same idempotency key`, res.status, 'malformed_success');
+            }
+            return bodyJson;
+        }
+        catch (err) {
+            // A timeout or an unmount surfaces as a bare `AbortError`, which on a
+            // money path is the least informative wording available: the caller
+            // cannot tell it from a refusal, and the charge may have landed. Named
+            // and bounded, as `useTip` and `useEntitlements` both do.
+            //
+            // 🔴 THE `!(err instanceof GoodPurchaseRefusal)` HALF IS NOT DEFENSIVE
+            // PADDING — but it does NOT cover a refusal cut off mid-parse, which an
+            // earlier version of this comment claimed. That case no longer reaches
+            // here at all: an abort during the body read is rethrown above and
+            // classified as an abort, because a body nobody could read carries no
+            // `reason` to preserve.
+            //
+            // What it does cover is the race the other way round: the body had
+            // ALREADY ARRIVED and parsed into an `insufficient_funds` 400 when the
+            // abort fired underneath it — the 30s bound elapsing in the same tick
+            // the refusal was thrown, or an unmount landing there. `signal.aborted`
+            // is then true while we hold a complete, deliberate server refusal.
+            // Rewriting it into the abort `Error` would strip `reason`, so the
+            // top-up branch in `purchase` below would stop recognising it and the
+            // viewer would be shown a raw failure instead of the Buzz modal. A
+            // refusal we actually read always wins over an abort that raced it.
+            if (controller.signal.aborted && !(err instanceof GoodPurchaseRefusal)) {
+                if (timedOut) {
+                    // The BOUND fired. This is a real failure the caller must handle,
+                    // so it deliberately does NOT get the `AbortError` name below:
+                    // callers routinely ignore `AbortError` as "we navigated away", and
+                    // a silently-ignored money-path timeout is the worst outcome here.
+                    throw new Error(`useGoodPurchase: request aborted (timed out after ${GOOD_PURCHASE_TIMEOUT_MS}ms). The charge may or may not have landed — retry with the SAME idempotencyKey to find out safely.`);
+                }
+                // 🔴 UNMOUNT. `name` stays `AbortError` on purpose: that is the
+                // discriminator a caller uses to IGNORE a rejection its component no
+                // longer cares about, and flattening it to a plain `Error` turns every
+                // navigate-away into a reported failure. The MESSAGE still says what
+                // happened — informative wording and a usable `name` are not a
+                // trade-off. `useBuzzWorkflow`'s `watch()` does the same.
+                const aborted = new Error('useGoodPurchase: request aborted (the hook unmounted before the response arrived). The charge may or may not have landed — retry with the SAME idempotencyKey to find out safely.');
+                aborted.name = 'AbortError';
+                throw aborted;
+            }
+            throw err;
+        }
+        finally {
+            clearTimeout(timeoutId);
+            inFlight.current.delete(controller);
+        }
+    }, [host, raw]);
+    const purchase = useCallback(async (params, options) => {
+        if (!host) {
+            throw new Error('useGoodPurchase: host origin not established yet (wait for BLOCK_INIT).');
+        }
+        if (mountedRef.current) {
+            setLoading(true);
+            setError(null);
+        }
+        const idempotencyKey = options?.idempotencyKey ?? generateIdempotencyKey();
+        try {
+            try {
+                return await postOnce(params, idempotencyKey);
+            }
+            catch (first) {
+                const canTopUp = options?.topUpOnInsufficientFunds === true &&
+                    first instanceof GoodPurchaseRefusal &&
+                    first.reason === 'insufficient_funds';
+                if (!canTopUp)
+                    throw first;
+                // Only retry if the viewer ACTUALLY bought Buzz. `purchased: false`
+                // is the ordinary "they closed the modal" case, and retrying it would
+                // just reproduce the same refusal — so the original refusal is what
+                // the app should see.
+                const { purchased } = await openPurchaseModal(params.expectedPriceBuzz);
+                if (!purchased)
+                    throw first;
+                return await postOnce(params, idempotencyKey);
+            }
+        }
+        catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (mountedRef.current)
+                setError(e);
+            throw e;
+        }
+        finally {
+            if (mountedRef.current)
+                setLoading(false);
+        }
+    }, [host, openPurchaseModal, postOnce]);
+    return { purchase, loading, error };
+}
+//# sourceMappingURL=useGoodPurchase.js.map

package/dist/index.d.ts

@@ -26,6 +26,10 @@ export { useHostOrigin } from './hooks/useHostOrigin.js';
 export type { UseHostOrigin } from './hooks/useHostOrigin.js';
 export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, WorkflowSubmitError, } from './hooks/useBuzzWorkflow.js';
 export type { SubmitWorkflowOptions, UseBuzzWorkflow, WatchWorkflowOptions, WorkflowSubmitErrorCode, } from './hooks/useBuzzWorkflow.js';
+export { useEntitlements } from './hooks/useEntitlements.js';
+export type { UseEntitlements, Entitlement } from './hooks/useEntitlements.js';
+export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
+export type { UseGoodPurchase, GoodPurchaseParams, GoodPurchaseOptions, GoodPurchaseResult, } from './hooks/useGoodPurchase.js';
 export { useTip } from './hooks/useTip.js';
 export type { TipParams, TipOptions, TipResult, UseTip } from './hooks/useTip.js';
 export { useTipAllowance } from './hooks/useTipAllowance.js';

package/dist/index.js

@@ -24,6 +24,8 @@ export { useBlockSettings } from './hooks/useBlockSettings.js';
 export { useBlockToken } from './hooks/useBlockToken.js';
 export { useHostOrigin } from './hooks/useHostOrigin.js';
 export { DEFAULT_WATCH_WAIT_SECONDS, useBuzzWorkflow, WorkflowEstimateError, WorkflowSubmitError, } from './hooks/useBuzzWorkflow.js';
+export { useEntitlements } from './hooks/useEntitlements.js';
+export { useGoodPurchase, GoodPurchaseRefusal } from './hooks/useGoodPurchase.js';
 export { useTip } from './hooks/useTip.js';
 export { useTipAllowance } from './hooks/useTipAllowance.js';
 export { useBlockResize } from './hooks/useBlockResize.js';

package/dist/internal/popoverShim.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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).
+ */
+/** What {@link installPopoverShim} hands back. */
+export interface PopoverShimHandle {
+    /**
+     * `true` when this shim was needed — i.e. the DOM did not already have a
+     * popover API. `false` means nothing was patched, which is the correct result
+     * in a real browser, and makes the call safe to make unconditionally in a
+     * setup file shared between a happy-dom project and a browser-mode project.
+     */
+    installed: boolean;
+    /**
+     * 🔴 Whether a click on a slotted light-DOM element reaches a listener on the
+     * `<slot>` it is assigned to — measured, on install, with a throwaway element.
+     *
+     * `true` in a real browser. `false` on happy-dom 20.9.0, and while it is
+     * `false` an element that binds its handlers to a `<slot>` (every Lit
+     * component that does, `<civitai-menu>`'s trigger included) cannot be driven
+     * by clicking. Drive it through its methods instead.
+     */
+    slottedClicksReachSlots: boolean;
+    /** Restores whatever was on the prototypes before. Idempotent. */
+    uninstall(): void;
+}
+/** Options for {@link installPopoverShim}. */
+export interface PopoverShimOptions {
+    /**
+     * Suppress the `console.warn` fired when slotted clicks do not reach slot
+     * listeners. The measurement is still returned on the handle. Default `false`
+     * — the warning is the point, so silence it only once you have read it.
+     */
+    quiet?: boolean;
+}
+/**
+ * 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 declare function installPopoverShim(options?: PopoverShimOptions): PopoverShimHandle;
+//# sourceMappingURL=popoverShim.d.ts.map

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/testing.d.ts

@@ -20,6 +20,7 @@ import { type ReactNode } from 'react';
 import { __resetTransport } from './transport/singleton.js';
 import { type MockHostOptions } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
+export { installPopoverShim, type PopoverShimHandle, type PopoverShimOptions, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, type MockHost, type MockHostOptions, type MockHostFailMode, type MockHostScenarioPatch, type MockGenerationScenario, type MockBuzzScenario, type MockBuzzBalance, type MockBuzzHandle, type MockStorageScenario, type MockSharedScenario, type MockSharedSeed, type MockCannedImageScan, type CostSpec, type ImageSpec, type CannedPick, } from './internal/mockHost.js';
 /**
  * Props for the dev {@link Harness}.

package/dist/testing.js

@@ -21,6 +21,7 @@ import { useEffect, useRef, useState } from 'react';
 import { __resetTransport } from './transport/singleton.js';
 import { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js';
 export { __resetTransport as resetTransport };
+export { installPopoverShim, } from './internal/popoverShim.js';
 export { createMockHost, readMockHostUrlOptions, } from './internal/mockHost.js';
 /**
  * What the harness chrome's `consent=` readout says, from the TWO INDEPENDENT