@civitai/blocks-react 0.59.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/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