@civitai/blocks-react 0.59.0 → 0.61.0

package/README.md

@@ -123,7 +123,9 @@ const { ready, context, viewer, theme, settings, blockId, blockInstanceId, appId
 ```
 
 - `context` — `BlockContext` (`{ slotId, … }`); narrow to `ModelSlotContext` for
-  model-page slots.
+  model-page slots. LIVE on a page slot: `context.subPath` starts at the
+  `BLOCK_INIT` value and then tracks the host's `ROUTE_CHANGED` push on every
+  navigation — see [`useCivitaiRoute()`](#usecivitairoute).
 - `viewer` — `ViewerInfo | null` (`null` = anonymous). **Gate sign-in with
   `isSignedIn(viewer)`** (from `@civitai/app-sdk/blocks`), never on
   `viewer.id`/`viewer.username` (both `@deprecated`). Don't open-code the gate:
@@ -961,10 +963,31 @@ await shared.withdraw(key);                            // remove my own entry
 
 Drive the platform Checkpoint picker + persist a viewer override.
 
+🔴 **`baseModelGroup` is a FILTER — derive it, never hardcode it.** The host hides
+every checkpoint outside the family you pass, so a literal ecosystem pins every
+viewer to whichever family the author happened to test with. Read it from the
+checkpoint the block already holds. The parameter is currently **required** by
+this hook's type, and `''` is **not** an escape hatch — it does not even mean the
+same thing on both hosts. On a **model slot** the host normalises whatever string
+you send, so `''` resolves to the real ecosystem key `Other` and NARROWS to that
+one family. On a **page** the host drops a zero-length value, so `''` behaves
+exactly like omitting it. Neither is what you meant on at least one surface:
+pass a family derived from a real checkpoint, and never `''`.
+
 ```tsx
+import { isModelSlotContext } from '@civitai/app-sdk/blocks';
+
+const { context } = useBlockContext();
 const { open, persist } = useCheckpointPicker();
-const { selected } = await open({ baseModelGroup: 'SDXL', currentVersionId });
-if (selected) await persist(selected.versionId);   // null clears the override
+
+// Derive the family from the checkpoint the block already holds — never a literal.
+if (isModelSlotContext(context) && context.checkpoint) {
+  const { selected } = await open({
+    baseModelGroup: context.checkpoint.baseModel,
+    currentVersionId: context.checkpoint.versionId,
+  });
+  if (selected) await persist(selected.versionId);   // null clears the override
+}
 ```
 
 ### `useResourcePicker()`
@@ -974,15 +997,39 @@ The viewer searches in host chrome; the block only ever sees the one resource it
 picked. DISCOVERY ONLY — the returned `versionId` is re-validated + re-priced
 server-side at estimate/submit.
 
+🔴 **Pass NO `baseModelGroup` by default.** It is an optional FILTER, and the host
+hides every resource outside the family you pass — so a hardcoded ecosystem makes
+the viewer's own valid LoRAs invisible and the picker look empty or broken. Omit
+it and the viewer sees everything of that type.
+
 ```tsx
 const { open } = useResourcePicker();
-const picked = await open({ resourceType: 'LORA', baseModelGroup: 'SDXL' });
+const picked = await open({ resourceType: 'LORA' });   // unconstrained — the default
 if (picked) {
   const versionId = picked.versionId;   // feed into body.additionalResources
   const weight = picked.strength;        // recommended default weight (may be undefined)
 }
 ```
 
+Constrain it **only** when the block already holds a chosen checkpoint the pick has
+to match — and then derive the family from that checkpoint, never from a literal.
+🔴 **This hook is PAGE-ONLY, and a page slot has no `context.checkpoint`** — that
+field lives on `ModelSlotContext` alone, so the family comes from
+`BlockResourceInfo.baseModel`, the `baseModel` of a Checkpoint this same picker
+returned earlier:
+
+```tsx
+const { open } = useResourcePicker();
+
+const checkpoint = await open({ resourceType: 'Checkpoint' });
+if (checkpoint) {
+  const matching = await open({
+    resourceType: 'LORA',
+    baseModelGroup: checkpoint.baseModel,   // from the pick above — BlockResourceInfo.baseModel
+  });
+}
+```
+
 ### `useImageUpload()`
 
 Host-mediated image upload — the host opens its native upload modal and the
@@ -1018,13 +1065,113 @@ const first = resources[0];             // .versionId / .strength / .trainedWord
 
 ### `useCivitaiNavigate()`
 
-Request a navigation within civitai.com (host-mediated; fire-and-forget).
+Request a navigation from the host. The hook sends a `NAVIGATE` message and
+returns — fire-and-forget, so the block never learns what the host did,
+including when the host **refuses** the request.
+
+`scope` selects the **space** `path` is resolved in, and it **defaults to
+`'app'`**:
+
+| `scope` | `path` resolves | The viewer |
+|---|---|---|
+| `'app'` *(default)* | under **this app's own route**, as a sub-path of it | stays in your app; the page stays mounted |
+| `'site'` | at the **civitai.com root** | leaves your app for a site page |
+
+> 🔴 **A leading slash carries no meaning.** The host normalises it away in
+> **both** scopes, so `'/settings'` and `'settings'` are one request within
+> whichever scope you chose. That means `navigate('/models/12345')` asks for
+> **your app's** `/models/12345` — *not* civitai's model page. To reach the
+> civitai.com page, say so: `navigate('models/12345', { scope: 'site' })`.
+>
+> Both spellings were app-scoped before `scope` existed, so no call you have
+> already written changed meaning — that is the point of the default.
+
+`'site'` is granted **per-surface**: the public run page and the dev tunnel allow
+it, and a private run or a moderator's review preview refuse it. A refusal is
+silent, so do not build a flow that needs to know it happened.
+
+`target` is a REQUEST, not a guarantee. How the host acts on `'current'` vs
+`'new_tab'` is host-side behaviour and the host is the authority on it; this
+package sends the message and makes no promise about the outcome.
+
+> 🔴 **Nothing in your manifest enables `'new_tab'`.** In particular, do **not**
+> declare `allow-popups-to-escape-sandbox`: the host intersects a manifest's
+> `iframe.sandbox` with a fixed allowlist that does not contain that token, so it
+> is dropped for every block at every trust tier and declaring it has no effect.
+> Earlier versions of this page said `'new_tab'` required it — that was wrong.
 
 ```tsx
 const { navigate } = useCivitaiNavigate();
-navigate('/models/12345', 'new_tab');   // 'new_tab' needs allow-popups* in the manifest sandbox
+
+// Your app's own pages — the default.
+navigate('settings');                    // this app's /settings
+navigate('/settings');                   // identical; the slash means nothing
+
+// A civitai.com page — needs an explicit scope.
+navigate('models/12345', { scope: 'site' });
+navigate('models/12345', { scope: 'site', target: 'new_tab' });
+
+// The pre-`scope` two-argument shape still works, and is still app-scoped.
+navigate('detail/7', 'new_tab');
+```
+
+An app-scoped `navigate()` is **half** of a round trip. The host owns the
+history, so the way your block learns where it ended up is
+[`useCivitaiRoute()`](#usecivitairoute) — read that next if you are routing.
+
+### `useCivitaiRoute()`
+
+The sub-path below your app's root that is **currently showing**. This is the
+other half of an app-scoped [`useCivitaiNavigate()`](#usecivitainavigate): you
+ask the host to move, the host pushes it shallowly so your frame stays mounted,
+and this is how you find out where you went.
+
+```tsx
+function Router() {
+  const subPath = useCivitaiRoute(); // '' on your app's index
+  const [view, id] = subPath.split('/');
+  return view === 'compare' ? <Compare id={id} /> : <Index />;
+}
 ```
 
+It also reports the moves you **did not** ask for: the viewer's own
+back/forward, and a deep link the host resolved after init.
+
+Two things set the value — `BLOCK_INIT`'s `context.subPath` at mount, and the
+host's `ROUTE_CHANGED` push on every later change. **The first value is never a
+message**, which is why this is a value hook rather than an `onRouteChanged`
+callback: a callback alone cannot see where the block started, and a change that
+lands before its subscription effect runs is lost. It is the same value as
+`useBlockContext().context.subPath` on a page slot — reach for this when the
+route is all you need, and because its return type is a plain `string` instead of
+a field on a union you have to narrow.
+
+> 🔴 **No leading slash.** The host sends the segment below your app root, so
+> `subPath === 'compare/42'` is the comparison that works and
+> `subPath === '/compare/42'` is the one that silently never matches.
+
+> 🔴 **`''` is a real route — your app's index — and it is also the pre-init
+> value.** The two are indistinguishable from this hook alone, exactly as
+> `'light'` is both a real theme and [`useBlockTheme()`](#useblocktheme)'s
+> pre-init value. Gate on `useBlockContext().ready` if your first paint must tell
+> them apart.
+
+> 🔴 **Read it on every render.** A block that copies the value into state once
+> at mount, or routes imperatively in a mount-only effect, stays on the route it
+> started with — the URL moves and nothing renders, which is the exact symptom
+> this message exists to end.
+
+**Page slot only.** A model-page slot has no route of its own, so this returns
+`''` there and never moves. Against a host that predates `ROUTE_CHANGED` the
+value simply stays at the init sub-path (the old behaviour); nothing awaits the
+message, so there is no hang either way.
+
+Exercise it locally with `pnpm dev:live`, where `navigate()` drives the real
+message end-to-end. `createMockHost` has **no** route control, deliberately: it
+does not handle `NAVIGATE` at all and has no URL to move, so a synthetic setter
+there would be a second, weaker way to produce a message the live host already
+produces from the call a block actually makes.
+
 ### `useBlockAnalytics()`
 
 Fire-and-forget event tracking into the host's analytics pipeline.
@@ -1045,8 +1192,97 @@ const { requestSignIn } = useRequestSignIn();
 requestSignIn();
 ```
 
+### Automatic consent prompt-and-retry (on by default)
+
+**You usually do not need to write any of this.** Since `1.0.0` the
+consent-gated calls below handle a missing scope themselves: the call fails, the
+SDK opens the host's consent dialog naming the scope the call needs, waits for
+the grant, and then **retries the original call once** so it resolves as if it
+had just worked.
+
+| Hook | Call | Scope it prompts for |
+|---|---|---|
+| `useBuzzWorkflow()` | `submit()` | `ai:write:budgeted` |
+| `useCreatePostFromApp()` | `createPost()` | `posts:write:self` |
+| `useGoodPurchase()` | `purchase()` | `goods:purchase:self` |
+| `useTip()` | `tip()` | `social:tip:self` |
+
+🔴 **`estimate()` is deliberately NOT in that table.** It is a price READ, and
+blocks call it from an effect keyed on the generation form — on mount, and again
+on every parameter change. Prompting there would open a consent dialog with no
+user gesture behind it, once per edit. A failed `estimate()` rejects exactly as
+it always has; show no price and let `submit()` do the asking.
+
+```tsx
+// This is the whole thing. No try/catch around a consent prompt, no watching
+// useBlockToken().scopes, no manual retry.
+const { submit } = useBuzzWorkflow();
+const snapshot = await submit(body);
+```
+
+🔴 **The retry re-sends the FIRST attempt's `idempotencyKey`.** That is what
+makes it safe on the money paths: `submit()`, `purchase()` and `tip()` mint the
+key once, before the first attempt, so however many attempts one call makes the
+server sees **one** logical operation and charges once. A retry with a fresh key
+would be a second reservation against the viewer's Buzz.
+
+It **never** retries when:
+
+- the token already holds every scope the call needs (so the failure was not
+  about consent — a rate limit, a 5xx, a bad body all behave exactly as before);
+- the call failed **before `BLOCK_INIT`** landed. There is no real token yet, so
+  "the token is missing this scope" is not a fact about consent;
+- the host has pushed `CONSENT_UNAVAILABLE` **naming a scope this call needs** —
+  that scope can never be granted here, so a retry is a guaranteed second
+  failure. A refusal that names *other* scopes leaves this call alone, and one
+  that names **none** (the payload's `scopes` is documented as advisory and may
+  be empty) is treated as covering everything, which is the safe reading;
+- the viewer dismissed a host confirm (`declined`), or there is no session to
+  grant anything to (`signInRequired` — route that into `useRequestSignIn()`);
+- the component **unmounted** — including *during* the 60 s wait, so a grant that
+  arrives after your component is gone does not spend anything;
+- the request timed out on a bridge with **no idempotency key** (`createPost()`,
+  collection follow) — the retry would be a genuine second write, i.e. a second
+  public post. A timeout on a call that HAS a key — `submit()`, `purchase()`,
+  `tip()` — *is* retried, because the retry re-sends that key and the server
+  collapses the two into one operation;
+- **a second time.** One retry, never a loop. A second consent failure surfaces
+  to you unchanged.
+
+If the viewer never answers the dialog, the **original** error is re-thrown after
+60 s and your `catch` sees exactly what it would have seen before.
+
+⚠️ **One failure is deliberately NOT excluded:** a host refusal about the
+*payload* rather than the token — `createPost()`'s `'no images to post'` — still
+prompts, because nothing distinguishes it structurally from a genuine consent
+failure without string-matching server copy. The cost is one needless dialog; the
+retry re-opens the host's own confirm and cannot publish anything new.
+
+**Concurrent callers share one dialog.** `N` calls that are in flight together and
+need the same scope post **one** `REQUEST_CONSENT` and wait on it together — a
+feed of tip buttons does not open a dialog per button. Each call still retries its
+**own** request with its **own** idempotency key, so *N* tips remain *N* transfers.
+⚠️ This is de-duplication of *concurrent* waits only: calls made one after another
+each get their own prompt, which is the shape that keeps `estimate()` out of the
+table above.
+
+Opt out per call — the same single option on every hook above:
+
+```tsx
+await submit(body, { autoRequestConsent: false });   // pre-1.0 behaviour
+```
+
+⚠️ **Not covered:** a scope your **manifest** never declared can never be granted
+either, and a block cannot see its own manifest at runtime — so that case is
+caught one round-trip late, by the host's `CONSENT_UNAVAILABLE`, rather than
+before the first attempt. Declare the scopes your app uses.
+
 ### `useRequestConsent()`
 
+The manual version of the above — still exported, still the right tool when you
+want to prompt *before* a call (e.g. on an onboarding screen) rather than after
+one fails.
+
 Lazy consent: ask the host to open its consent UI when a LOGGED-IN viewer takes
 an action whose consent-gated scope the block token is missing (e.g. Generate
 needs `ai:write:budgeted` but the viewer hasn't granted it). Fire-and-forget —
@@ -1445,6 +1681,7 @@ what went stale in [#334](https://github.com/civitai/civitai-app-starters/issues
 | `createMockHost` | A framework-agnostic fake of the embedding host — answers every `*_RESULT` message, with knobs for generation cost/latency/failure, Buzz balance, app + shared storage, consent, maturity. Returns a `MockHost`; call `.install()` and keep the returned teardown. **No network, no Buzz.** |
 | `readMockHostUrlOptions` | Reads the harness URL toggles (`?viewer` `?consent` `?fail` `?theme` `?pick` `?balance` `?latency` `?seed` …) into a `Partial<MockHostOptions>`. `Harness` applies it for you; call it directly only in a hand-rolled harness. |
 | `Harness` | The React wrapper: installs a `createMockHost` on mount, tears it down on unmount, and renders an optional on-screen outbound-message log. Takes every `MockHostOptions` field plus `applyUrlToggles` and `showLog`. |
+| `installPopoverShim` | Stands in for the HTML popover API, which neither `jsdom` nor `happy-dom` implements at any version. Needed only if your own code calls `showPopover`/`hidePopover`/`togglePopover` or queries `:popover-open` — `@civitai/components`' own elements do not. Returns a `PopoverShimHandle`; inert (`installed: false`) in a real browser. **Read [Testing overlay elements](#testing-overlay-elements) first: it does not make trigger clicks work.** |
 
 <!-- TESTING-SURFACE:VALUES:END -->
 
@@ -1472,6 +1709,8 @@ MockHostScenarioPatch
 MockSharedScenario
 MockSharedSeed
 MockStorageScenario
+PopoverShimHandle
+PopoverShimOptions
 ```
 
 <!-- TESTING-SURFACE:TYPES:END -->
@@ -1501,6 +1740,57 @@ host.setScenario({ failMode: 'none' });   // live-tune mid-test
 uninstall();
 ```
 
+### Testing overlay elements
+
+`<civitai-menu>`, and anything else that opens a panel, live in an environment
+that is **incomplete** rather than merely different. Two facts, both measured on
+happy-dom 20.9.0; neither is a bug in the components.
+
+**1. There is no popover API.** `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**, and the unreliability is not a
+property of your runner's version. It resolves through `nwsapi` under jsdom, so
+the same jsdom 25.0.1 both throws `DOMException: unknown pseudo-class selector`
+and returns `false` depending on which `nwsapi` your lockfile pulled in
+(measured: `false` on nwsapi 2.2.28). `@civitai/components`' own elements no
+longer read it, which is what takes that variable off the table for them. Install
+the shim if **your** code touches the API:
+
+```ts
+import { installPopoverShim } from '@civitai/blocks-react/testing';
+
+const shim = installPopoverShim();
+// …
+shim.uninstall();
+```
+
+It is inert in a real browser (`installed: false`), so it is safe to call from a
+setup file shared between a happy-dom project and a browser-mode project.
+
+**2. 🔴 UNDER happy-dom A TRIGGER CLICK DOES NOTHING, and the shim does not change
+that.** A click on light-DOM content assigned to a `<slot>` reaches the **host** (a
+listener there fires once) but **not** a listener on the `<slot>` element — and
+that is the node Lit binds `@click` to. So the click dispatches, bubbles, and
+then the handler is never called: no throw, no state change, a test that quietly
+does nothing. jsdom (25 and 30) *does* deliver it, so this one is happy-dom's
+alone — which is exactly why the shim **measures** it rather than asserting it:
+`installPopoverShim` probes on install, reports the answer as
+`handle.slottedClicksReachSlots`, and `console.warn`s when it is `false`.
+
+**Drive overlay elements through their methods:**
+
+```ts
+menu.show();                 // ✅ works in every DOM
+await menu.updateComplete;
+
+triggerButton.click();       // ❌ silently does nothing under happy-dom
+```
+
+Also absent, because they need layout and a hit-testing event path: the top
+layer, anchor positioning, and **light dismiss** (a click outside a shown panel
+does not close it). If what you are testing is one of those, use a real browser —
+this repo's own `browser` vitest project is the worked example.
+
 ### In a dev harness
 
 ```tsx

package/dist/hooks/consentRetryOptions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared, PUBLIC options for the SDK's automatic consent prompt-and-retry.
+ *
+ * Declared here rather than beside the mechanics in
+ * `internal/withConsentRetry.ts` for one structural reason: `src/index.ts` may
+ * not reach a module under `internal/` (#378, enforced by
+ * `tests/guards/blocks-react-entry-directory-names.test.mjs`, which follows
+ * re-export edges transitively). A caller has to be able to SPELL this type in
+ * its own signatures, so the type is public and the mechanics stay private.
+ *
+ * Every consent-gated call reaches this field through the ONE declaration here
+ * — `SubmitWorkflowOptions`, `GoodPurchaseOptions` and `TipOptions` EXTEND it
+ * (they have money fields of their own); `createPost()` takes it directly. A
+ * predicate — or an option name — open-coded at N sites is typically wrong at
+ * N-1 of them.
+ *
+ * 🔴 ONE FIELD, DELIBERATELY. A second, `consentTimeoutMs`, was cut in #500
+ * round 1: it had no consumer outside this package and its only demonstrated
+ * use was shortening the 60s wait inside a TEST. A test seam does not belong on
+ * five public signatures — the test now uses fake timers instead, and the wait
+ * bound is the non-public `CONSENT_GRANT_WAIT_MS`. Adding a knob here commits
+ * the package to it forever; do not add one without a caller that needs it.
+ */
+export interface ConsentRetryOptions {
+    /**
+     * Whether a consent-gated failure should automatically open the host's
+     * consent dialog and, on grant, retry the call ONCE.
+     *
+     * **Defaults to `true`** — the good behaviour is the default one. Set `false`
+     * to get the pre-1.0 behaviour: the original error is re-thrown unchanged
+     * and nothing is prompted.
+     *
+     * 🔴 THE RETRY REUSES THE FIRST ATTEMPT'S IDEMPOTENCY KEY on every money path
+     * that has one (`submit`, `purchase`, `tip`). That is what makes it safe: a
+     * retry with a FRESH key is a SECOND reservation against the viewer's Buzz.
+     * See `internal/withConsentRetry.ts`.
+     */
+    autoRequestConsent?: boolean;
+}
+//# sourceMappingURL=consentRetryOptions.d.ts.map

package/dist/hooks/consentRetryOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=consentRetryOptions.js.map

package/dist/hooks/useBuzzWorkflow.d.ts

@@ -1,4 +1,5 @@
 import type { BlockWorkflowSnapshot, WorkflowBody, WorkflowStatus } from '@civitai/app-sdk/blocks';
+import type { ConsentRetryOptions } from './consentRetryOptions.js';
 /**
  * Default orchestrator-side hold per {@link UseBuzzWorkflow.watch} poll,
  * in SECONDS.
@@ -393,7 +394,7 @@ export declare class WorkflowSubmitError extends Error {
     constructor(snapshot: BlockWorkflowSnapshot, code: WorkflowSubmitErrorCode);
 }
 /** Optional per-submit controls. */
-export interface SubmitWorkflowOptions {
+export interface SubmitWorkflowOptions extends ConsentRetryOptions {
     /**
      * A STABLE idempotency key for this logical submit. Reuse the SAME value when
      * RETRYING a submit whose response was lost (timeout / network drop) so the
@@ -405,6 +406,11 @@ export interface SubmitWorkflowOptions {
      * SAFE. That code means a workflow probably exists and its spend may already
      * be committed server-side; retrying WITHOUT reusing the key mints a fresh one
      * and therefore a SECOND reservation. See {@link WorkflowSubmitError.code}.
+     *
+     * The SDK's own automatic consent retry obeys this: whichever value ends up
+     * here — yours, or the one `submit()` mints — is the value BOTH of its
+     * attempts carry. So an error you receive may already be a second attempt's;
+     * if you then retry a third time by hand, reuse this key for that too.
      */
     idempotencyKey?: string;
 }
@@ -430,6 +436,13 @@ export interface UseBuzzWorkflow {
      * `result` is updated to the returned snapshot BEFORE any rejection, so a
      * failed estimate can never leave a previous, differently-configured
      * estimate's price sitting in `result` for a Confirm gate to read.
+     *
+     * 🔴 NO AUTOMATIC CONSENT PROMPT HERE, unlike {@link UseBuzzWorkflow.submit}.
+     * Blocks call `estimate()` from an effect keyed on the generation form, so it
+     * fires on mount and on every parameter change — prompting there would open a
+     * consent dialog with no user gesture behind it, once per edit. A missing
+     * scope surfaces as an ordinary rejection; show no price and let `submit()`
+     * do the asking.
      */
     estimate: (body: WorkflowBody) => Promise<BlockWorkflowSnapshot>;
     /**
@@ -468,6 +481,15 @@ export interface UseBuzzWorkflow {
      *
      * `result` is updated to the returned snapshot BEFORE any rejection, so a
      * failed submit can never leave a previous submit's workflow in `result`.
+     *
+     * 🔴 CONSENT IS HANDLED FOR YOU. When the token lacks `ai:write:budgeted`,
+     * this opens the host's consent dialog, waits for the grant, and re-sends the
+     * submit ONCE — with the SAME {@link SubmitWorkflowOptions.idempotencyKey}, so
+     * the two attempts are one reservation, not two. Nothing else changes: a
+     * failure while the token DOES hold the scope is untouched, a
+     * `CONSENT_UNAVAILABLE` environment is never retried, and a second consent
+     * failure reaches you unchanged. Opt out with
+     * {@link ConsentRetryOptions.autoRequestConsent}`: false`.
      */
     submit: (body: WorkflowBody, options?: SubmitWorkflowOptions) => Promise<BlockWorkflowSnapshot>;
     /**