@civitai/blocks-react 0.62.0 → 0.63.0

package/dist/transport/transport.js

@@ -1,3 +1,4 @@
+import { BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH, BLOCK_IDEMPOTENCY_KEY_REGEX, blockIdempotencyKeyRejection, } from '@civitai/app-sdk/blocks';
 /**
  * Type-safe wrapper around `transport.sendRequest`. Hooks always go through
  * this so the response payload narrows based on `responseType`.
@@ -188,6 +189,81 @@ export function generateIdempotencyKey() {
         .toString(36)
         .slice(2, 12)}`;
 }
+/**
+ * A CALLER-SUPPLIED `idempotencyKey` that the host would reject. Thrown by
+ * `useBuzzWorkflow().submit`, `useTip().tip` and `useGoodPurchase().purchase`
+ * **before anything is sent**.
+ *
+ * 🔴 NOTHING WAS SENT AND NOTHING WAS SPENT — that is the whole reason this is a
+ * DISTINCT class rather than one of the existing money-path errors. Every other
+ * rejection on these hooks is money-AMBIGUOUS by design:
+ * `WorkflowSubmitError`'s own docs say its `'exception'` arm covers "a lost
+ * response or an in-progress idempotency conflict", and the abort/timeout
+ * rejections say in as many words that "the charge may or may not have landed".
+ * Reusing any of those for a key refused at the boundary would hand the caller
+ * an error whose documented contract is strictly weaker than the truth, and the
+ * repo's money rule runs the other way: never tell a caller money did not move
+ * unless you know it. Here we do know, structurally — the request never left the
+ * iframe — so the caller gets a type that says so.
+ *
+ * Two further reasons it is not a `WorkflowSubmitError`:
+ *   - that class REQUIRES a `snapshot`, which is the host's reply. There is no
+ *     reply. Synthesising one would be inventing a host message the host never
+ *     sent, and `workflowId: 'failed'` specifically means "the host had no
+ *     workflow to report" — a claim about the host we are not entitled to make.
+ *   - it is not a runtime OUTCOME at all. It is a defect in the calling block's
+ *     own code, in the same family as the existing
+ *     `'host origin not established yet'` throw: no retry fixes it, and the fix
+ *     is a source change.
+ *
+ * 🔴 THE KEY IS REFUSED, NEVER REWRITTEN. See `@civitai/app-sdk/blocks`'
+ * `idempotency.ts`: sanitising a caller's key would break the identity the key
+ * exists to carry — two distinct logical submits could collapse onto one slot,
+ * or a retry could be normalised differently from its first attempt and mint a
+ * SECOND reservation. A loud refusal is the only money-safe answer.
+ *
+ * Branch on `instanceof` or `name === 'InvalidIdempotencyKeyError'`; the
+ * `message` wording is developer-facing and is not a contract. Do NOT render it
+ * to a viewer — they cannot act on it.
+ */
+export class InvalidIdempotencyKeyError extends Error {
+    /** The rejected value, verbatim, for logging. The block's own construction. */
+    idempotencyKey;
+    /** Which hook refused it, e.g. `'useBuzzWorkflow.submit'`. */
+    source;
+    constructor(source, idempotencyKey, message) {
+        super(message);
+        this.name = 'InvalidIdempotencyKeyError';
+        this.source = source;
+        this.idempotencyKey = idempotencyKey;
+    }
+}
+/**
+ * Refuse a caller-supplied key, or mint one when the caller supplied none.
+ *
+ * 🔴 THE `undefined` CASE IS NOT VALIDATED, AND MUST NOT BE. `idempotencyKey` is
+ * optional on all three hooks; absent means "mint one for me", and the generated
+ * key conforms by construction. Routing `undefined` into the predicate would
+ * turn every ordinary keyless call into a refusal.
+ *
+ * Ordering is load-bearing: validation happens BEFORE the generator is consulted
+ * and before any transport/fetch work, so a bad key costs nothing and cannot
+ * race a send.
+ */
+export function resolveIdempotencyKey(source, supplied) {
+    if (supplied === undefined)
+        return generateIdempotencyKey();
+    const why = blockIdempotencyKeyRejection(supplied);
+    if (why !== null) {
+        throw new InvalidIdempotencyKeyError(source, supplied, `${source}: refusing to send a malformed idempotencyKey — ${why}. ` +
+            `Nothing was sent and nothing was spent. The host requires ` +
+            `${String(BLOCK_IDEMPOTENCY_KEY_REGEX)} and rejects anything else with a 400; ` +
+            `the key is NOT sanitised for you, because rewriting an idempotency key would ` +
+            `break the identity it exists to carry. Compose the key from letters, digits, ` +
+            `underscore and hyphen only, at most ${BLOCK_IDEMPOTENCY_KEY_MAX_LENGTH} characters.`);
+    }
+    return supplied;
+}
 /**
  * A request that got NO REPLY before its timeout elapsed.
  *

package/dist/ui/BlockGate.d.ts

@@ -31,8 +31,9 @@ export interface DirectLoadFallbackProps {
  *    "waiting for the Civitai host" card with a dev hint — NEVER a broken
  *    `apps/run/localhost` link.
  *
- * Theme-aware via `prefers-color-scheme` (there is no host `theme` on a direct
- * load) and styled with the `/ui` pack's tokens.
+ * Themed from the PAGE — `data-theme` on `<html>`, dark when absent — never
+ * from the OS preference (see {@link readDocumentTheme}), and styled with the
+ * `/ui` pack's tokens.
  */
 export declare function DirectLoadFallback({ hostname, autoRedirectMs, }: DirectLoadFallbackProps): React.JSX.Element;
 /**

package/dist/ui/BlockGate.js

@@ -1,52 +1,45 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import { hostToRunUrl } from '../transport/directLoad.js';
 import { useDirectLoad } from '../hooks/useDirectLoad.js';
 import { Card } from './Card.js';
 import { Stack } from './Stack.js';
 import { useBlocksStyles } from './styles.js';
 /**
- * Read the OS/browser color-scheme preference, live.
+ * The theme the PAGE is already painted in — never the OS preference.
  *
- * A directly-loaded block has NO `BLOCK_INIT`, so there is no host `theme` to
- * set `data-theme` from (the usual gotcha-#60 path). We fall back to
- * `prefers-color-scheme` so the fallback card still themes correctly in light
- * AND dark. Guarded for SSR / engines without `matchMedia`.
+ * A directly-loaded block has no host: no `BLOCK_INIT`, no `THEME_CHANGE`. The
+ * only theme signal that can reach this card is the one the document itself
+ * booted with — `data-theme` on `<html>`, which the scaffolded `index.html`
+ * sets pre-paint from the host fragment (`#civitai-block=v1&theme=…`). So the
+ * card follows the page instead of second-guessing it, and a block with no
+ * fragment boots dark like every other Civitai surface.
+ *
+ * `'light'` is the ONLY value that buys light — exactly the rule the pre-paint
+ * script applies. Absent, empty, `'auto'`, a typo, or no DOM at all (SSR) are
+ * all dark.
+ *
+ * Reading `prefers-color-scheme` here was the defect: on a light-OS machine it
+ * painted a LIGHT card on a deliberately DARK page.
+ *
+ * Setting the attribute explicitly, rather than inheriting it, keeps this card's
+ * theme a decision of this component rather than of whatever is above it.
+ *
+ * ⚠️ It used to be load-bearing for a stronger reason that no longer holds:
+ * `@civitai/theme` shipped
+ * `@media (prefers-color-scheme: dark) { :root:not([data-theme]) { … } }`, so a
+ * document carrying no `data-theme` handed its tokens back to the OS and only an
+ * explicit attribute could stop it. Since `@civitai/theme@0.5.0` the base is
+ * dark and that at-rule is gone, so inheriting would reach the same answer on a
+ * direct-load page. One real difference survives and is why this stays: the read
+ * below is `document.documentElement`, whereas inheritance takes the NEAREST
+ * `[data-theme]` ancestor. Those coincide on a direct load — no host, no wrapper
+ * — but that is a property of the deployment, not of this code.
  */
-function usePrefersColorScheme() {
-    const [dark, setDark] = useState(() => {
-        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
-            return false;
-        try {
-            return window.matchMedia('(prefers-color-scheme: dark)').matches;
-        }
-        catch {
-            return false;
-        }
-    });
-    useEffect(() => {
-        if (typeof window === 'undefined' || typeof window.matchMedia !== 'function')
-            return;
-        let mql;
-        try {
-            mql = window.matchMedia('(prefers-color-scheme: dark)');
-        }
-        catch {
-            return;
-        }
-        const onChange = (e) => setDark(e.matches);
-        // Modern browsers: addEventListener. Older Safari: addListener.
-        if (typeof mql.addEventListener === 'function') {
-            mql.addEventListener('change', onChange);
-            return () => mql.removeEventListener('change', onChange);
-        }
-        if (typeof mql.addListener === 'function') {
-            mql.addListener(onChange);
-            return () => mql.removeListener(onChange);
-        }
-        return;
-    }, []);
-    return dark ? 'dark' : 'light';
+function readDocumentTheme() {
+    if (typeof document === 'undefined')
+        return 'dark';
+    return document.documentElement?.dataset?.theme === 'light' ? 'light' : 'dark';
 }
 const wrapperStyle = {
     minHeight: '100%',
@@ -87,12 +80,13 @@ const bodyStyle = {
  *    "waiting for the Civitai host" card with a dev hint — NEVER a broken
  *    `apps/run/localhost` link.
  *
- * Theme-aware via `prefers-color-scheme` (there is no host `theme` on a direct
- * load) and styled with the `/ui` pack's tokens.
+ * Themed from the PAGE — `data-theme` on `<html>`, dark when absent — never
+ * from the OS preference (see {@link readDocumentTheme}), and styled with the
+ * `/ui` pack's tokens.
  */
 export function DirectLoadFallback({ hostname, autoRedirectMs, }) {
     useBlocksStyles();
-    const theme = usePrefersColorScheme();
+    const theme = readDocumentTheme();
     const resolvedHost = hostname ?? (typeof window !== 'undefined' ? window.location?.hostname : undefined);
     const runUrl = hostToRunUrl(resolvedHost);
     useEffect(() => {

package/dist/ui/TipButton.d.ts

@@ -73,6 +73,44 @@ export interface TipButtonProps {
      */
     'data-testid'?: string;
 }
+/**
+ * Compose this control's idempotency key from the tip's full identity.
+ *
+ * 🔴 EXTRACTED SO THE REACT-VERSION DIMENSION IS TESTABLE AT ALL, and that is
+ * the whole reason it is not inline. `useId()`'s FORMAT differs by React
+ * version, and this package's peer range admits `^18.0.0 || ^19.0.0`:
+ * React 18.3.1 returns `":R0:"`, early React 19 a guillemet-wrapped id, and
+ * React 19.2.6 (resolved here today) `"_r_0_"`. Only the last of those clears
+ * the host charset on its own.
+ *
+ * While the composition was inline the suite was STRUCTURALLY BLIND to that
+ * dimension: the installed React happens to produce a conforming seed, so
+ * deleting the normalisation below changed nothing any test could see — it was
+ * run as a mutation and SURVIVED a fully green file. A pure function can be fed
+ * the OTHER versions' shapes without installing them, which is what turns
+ * "passes here" into "passes across the range we declare".
+ *
+ * 🔴 NORMALISING THIS SEED IS NOT SANITISING A CALLER'S KEY. The repo-wide rule
+ * is REFUSE-never-rewrite for a key a BLOCK supplies, because that key is an
+ * identity its author chose and rewriting it breaks idempotency. This seed is
+ * the opposite: an opaque uniqueness token this component mints itself, whose
+ * only contract is "distinct per mount". Normalising characters React may change
+ * between versions is correct handling for a value we own — and the result is
+ * still validated by `useTip`, which refuses it rather than repairing it if this
+ * composition is ever wrong again.
+ *
+ * 🔴 THE DELIMITER IS `_`, AND A COLON HERE WAS A LIVE PRODUCTION DEFECT. This
+ * used to join with ':'. The host enforces `^[A-Za-z0-9_-]{1,64}$` on
+ * `idempotencyKey` at `/api/v1/blocks/tip`, so EVERY tip this button posted was
+ * rejected with `invalid_format` / 400 — and it always supplies a key, so there
+ * was no unkeyed path that happened to work.
+ *
+ * INJECTIVITY is preserved, which is what the colon was chosen for: after
+ * normalisation the seed contains only `[A-Za-z0-9_-]`, `toUserId`/`amount`/
+ * `entityId` are numbers, and `entityType` is one of three `_`-free literals —
+ * so distinct tip identities still yield distinct keys. Pinned by a test.
+ */
+export declare function composeTipIdempotencyKey(seed: string, toUserId: number, amount: number, entityType: 'Image' | 'Collection' | 'User' | undefined, entityId: number | undefined): string;
 /**
  * Send a Buzz tip, behind an in-block two-step confirm.
  *

package/dist/ui/TipButton.js

@@ -9,6 +9,47 @@ const NOTE_STYLE = {
     lineHeight: 1.45,
     color: 'var(--civitai-color-text-dimmed)',
 };
+/**
+ * Compose this control's idempotency key from the tip's full identity.
+ *
+ * 🔴 EXTRACTED SO THE REACT-VERSION DIMENSION IS TESTABLE AT ALL, and that is
+ * the whole reason it is not inline. `useId()`'s FORMAT differs by React
+ * version, and this package's peer range admits `^18.0.0 || ^19.0.0`:
+ * React 18.3.1 returns `":R0:"`, early React 19 a guillemet-wrapped id, and
+ * React 19.2.6 (resolved here today) `"_r_0_"`. Only the last of those clears
+ * the host charset on its own.
+ *
+ * While the composition was inline the suite was STRUCTURALLY BLIND to that
+ * dimension: the installed React happens to produce a conforming seed, so
+ * deleting the normalisation below changed nothing any test could see — it was
+ * run as a mutation and SURVIVED a fully green file. A pure function can be fed
+ * the OTHER versions' shapes without installing them, which is what turns
+ * "passes here" into "passes across the range we declare".
+ *
+ * 🔴 NORMALISING THIS SEED IS NOT SANITISING A CALLER'S KEY. The repo-wide rule
+ * is REFUSE-never-rewrite for a key a BLOCK supplies, because that key is an
+ * identity its author chose and rewriting it breaks idempotency. This seed is
+ * the opposite: an opaque uniqueness token this component mints itself, whose
+ * only contract is "distinct per mount". Normalising characters React may change
+ * between versions is correct handling for a value we own — and the result is
+ * still validated by `useTip`, which refuses it rather than repairing it if this
+ * composition is ever wrong again.
+ *
+ * 🔴 THE DELIMITER IS `_`, AND A COLON HERE WAS A LIVE PRODUCTION DEFECT. This
+ * used to join with ':'. The host enforces `^[A-Za-z0-9_-]{1,64}$` on
+ * `idempotencyKey` at `/api/v1/blocks/tip`, so EVERY tip this button posted was
+ * rejected with `invalid_format` / 400 — and it always supplies a key, so there
+ * was no unkeyed path that happened to work.
+ *
+ * INJECTIVITY is preserved, which is what the colon was chosen for: after
+ * normalisation the seed contains only `[A-Za-z0-9_-]`, `toUserId`/`amount`/
+ * `entityId` are numbers, and `entityType` is one of three `_`-free literals —
+ * so distinct tip identities still yield distinct keys. Pinned by a test.
+ */
+export function composeTipIdempotencyKey(seed, toUserId, amount, entityType, entityId) {
+    const safeSeed = seed.replace(/[^A-Za-z0-9_-]/g, '_');
+    return `${safeSeed}_${toUserId}_${amount}_${entityType ?? '-'}_${entityId ?? '-'}`;
+}
 /**
  * Send a Buzz tip, behind an in-block two-step confirm.
  *
@@ -107,8 +148,38 @@ export function TipButton({ toUserId, amount, entityType, entityId, noun, tipped
      * on the first landed transfer for a given key, and a repeat under the SAME
      * key is that same transfer. Change either and rotate.
      */
-    const keySeed = useId();
-    const idempotencyKey = `${keySeed}:${toUserId}:${amount}:${entityType ?? '-'}:${entityId ?? '-'}`;
+    /**
+     * 🔴 THE DELIMITER IS `_`, AND A COLON HERE WAS A LIVE PRODUCTION DEFECT.
+     * This component used to compose the key with ':' separators. The host
+     * enforces `^[A-Za-z0-9_-]{1,64}$` on `idempotencyKey` at
+     * `/api/v1/blocks/tip`, so EVERY tip this button posted was rejected with
+     * `invalid_format` / 400 — and `TipButton` always supplies a key, so there was
+     * no unkeyed path that happened to work. Measured 2026-10-02 under React 19:
+     * `useId()` returns `_r_0_` (which clears the charset on its own), while the
+     * composed `_r_0_:123:50:Image:99` does not — so under the React resolved here
+     * the DELIMITERS were the whole fault. Reported separately and not measured by
+     * this change: React 18.3.1 returns `":R0:"` and early React 19 a
+     * guillemet-wrapped id, both of which fail the charset on their own. The peer
+     * range is `^18.0.0 || ^19.0.0`, so the seed must be normalised regardless of
+     * which arm a consumer is on.
+     *
+     * `_` is a safe delimiter and the composition stays INJECTIVE, which is the
+     * property the colon was chosen for: after the sanitisation below the seed
+     * cannot contain `_`-ambiguity it did not already have, `toUserId`/`amount`/
+     * `entityId` are numbers (digits only), and `entityType` is one of the three
+     * literals `'Image' | 'Collection' | 'User'` — none contains `_`. So distinct
+     * tip identities still produce distinct keys.
+     *
+     * 🔴 SANITISING THE SEED IS NOT SANITISING A CALLER'S KEY. The repo-wide rule
+     * is REFUSE-never-rewrite for a key the BLOCK supplies, because that key is an
+     * identity its author chose. This seed is the opposite: an opaque uniqueness
+     * token this component mints itself, whose only contract is "distinct per
+     * mount". Normalising characters React's own format may change between major
+     * versions is the correct handling for a value we own — and the result is
+     * still validated by `useTip`, which refuses it rather than fixing it if this
+     * composition is ever wrong again.
+     */
+    const idempotencyKey = composeTipIdempotencyKey(useId(), toUserId, amount, entityType, entityId);
     const settled = done || tipped;
     // Both guards are about a NUMBER reaching a money path, and both were once
     // missing: `amount={0}` rendered "Tip 0" and posted it, and an unusable