@civitai/blocks-react 0.61.1 → 0.63.0

package/dist/internal/mockHostIdempotency.js

@@ -0,0 +1,113 @@
+/**
+ * mockHostIdempotency.ts — the dev host's IDEMPOTENCY-KEY FORMAT GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-02). A character-sheet block sent an
+ * `idempotencyKey` of the form `sheetId:panelId:nonce`. It passed **201 local
+ * tests**, the dev harness and review. Every save in production failed:
+ *
+ *     { "code": "invalid_format", "format": "regex",
+ *       "pattern": "/^[A-Za-z0-9_-]{1,64}$/",
+ *       "path": ["idempotencyKey"],
+ *       "message": "Invalid string: must match pattern /^[A-Za-z0-9_-]{1,64}$/" }
+ *
+ * `BAD_REQUEST` / httpStatus 400 on path `blocks.submitWorkflow`.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE — the exact shape of
+ * #511's storage-scope gap, one surface over. `createMockHost` had **zero**
+ * occurrences of `idempotencyKey`: it accepted the field, forwarded nothing, and
+ * validated nothing, so the one submit failure mode that actually ships was the
+ * only one the mock could not produce. It models a caught server exception, a
+ * disallowed account pool, insufficient Buzz, a fail-rate dice roll and an
+ * induced transport failure — and not the input validator that runs before any
+ * of them.
+ *
+ * This is the missing arm of an existing simulation, not a new feature.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and why the refusal has THIS shape.
+ *
+ * The rule is a zod `.regex()` on the procedure INPUT
+ * (`blocks.router.ts:6227`), so it fires **before the procedure body runs** —
+ * ahead of every scenario, budget and balance decision the handler below would
+ * otherwise make. That ordering is modelled deliberately: the gate sits ahead of
+ * the message switch, so a malformed key is refused even when the scenario,
+ * the balance and the spend cap would all have allowed the submit, because
+ * production refuses it then too.
+ *
+ * A tRPC input rejection reaches the block as a host-synthesised failure
+ * snapshot, NOT as a thrown error — the reply crosses `postMessage`.
+ * `internal/liveHost.ts:298` is the mapping: `errorSnapshot(error)` →
+ * `{ workflowId: 'failed', status: 'failed', error }`, with **no `cost`**. That
+ * is byte-for-byte the shape the disallowed-account branch in `mockHost.ts`
+ * already emits, and it is what makes `useBuzzWorkflow().submit` reject with
+ * `WorkflowSubmitError` code `'exception'`. Emitting anything else here — a
+ * priced refusal, a thrown error, a silent drop — would model a host that does
+ * not exist.
+ *
+ * 🔴 ONE MESSAGE TYPE TODAY, AND A TABLE ANYWAY. `SUBMIT_WORKFLOW` is the only
+ * block→host message in `@civitai/app-sdk`'s protocol carrying an
+ * `idempotencyKey` (the tip and good-purchase paths are direct REST POSTs and
+ * never traverse the mock host, so they are covered by the hook-boundary guard
+ * alone — see `resolveIdempotencyKey`). The table is still the right shape: a
+ * future money message that gains the field is governed the moment it joins
+ * `IDEMPOTENT_MESSAGES`, rather than whenever someone remembers to copy a check
+ * into its handler. That is the property #511 bought on the storage side and the
+ * reason its gate sits ahead of the switch.
+ *
+ * 🔴 WHY THIS IS NOT REDUNDANT WITH THE HOOK GUARD. Two independent reachable
+ * paths bypass the hooks: a block may drive the transport directly
+ * (`getTransport().sendRequest({ type: 'SUBMIT_WORKFLOW', … })`, which the
+ * package exports), and the dev harness dispatches hand-built messages. The gate
+ * is also the arm that makes the DEV HARNESS and the TEST SUITE go red, which is
+ * what the original defect needed and did not have: a hook-side throw protects
+ * callers of that hook, while this protects the protocol.
+ */
+import { BLOCK_IDEMPOTENCY_KEY_REGEX, blockIdempotencyKeyRejection, } from '@civitai/app-sdk/blocks';
+/**
+ * Block→host message types whose payload carries an `idempotencyKey` the host
+ * validates. Exported for the ledger test, which fails when the set grows or
+ * shrinks — so a new money message cannot join the protocol ungated and a
+ * retired one cannot leave a dead row behind.
+ */
+export const IDEMPOTENT_MESSAGES = ['SUBMIT_WORKFLOW'];
+/** Does this gate govern `type`? */
+export function governsIdempotencyKey(type) {
+    return IDEMPOTENT_MESSAGES.includes(type);
+}
+/**
+ * The refusal text, modelled on the server's own `invalid_format` message so a
+ * developer grepping their production logs for the string finds the dev one too.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING and do not render it to a viewer.
+ * It is developer-facing: a malformed key is a defect in the block's code, so
+ * "please try again" is the wrong copy for it — no number of retries fixes it.
+ */
+export function idempotencyKeyDeniedMessage(reason) {
+    // 🔴 INTERPOLATED FROM THE VENDORED CONSTANT, NEVER RE-TYPED. The first draft
+    // of this line spelled the pattern out — and the single-source guard
+    // (`tests/guards/idempotency-key-rule-single-source.test.mjs`) caught it,
+    // which is the whole point of that guard: a second copy of a rule the host
+    // owns can only ever drift from it.
+    return `Invalid string: must match pattern ${String(BLOCK_IDEMPOTENCY_KEY_REGEX)} (idempotencyKey) — ${reason}`;
+}
+/**
+ * The reason `payload.idempotencyKey` is unacceptable, or `null` to proceed.
+ *
+ * 🔴 AN ABSENT KEY IS VALID AND MUST STAY VALID. The field is optional on the
+ * wire; `undefined` means "no dedupe", which is the ordinary case for every
+ * block that never passes one. Validating absence would refuse almost every
+ * submit in the suite — and would be a FALSE model, since the host's own schema
+ * is `.optional()` on this path.
+ *
+ * Note the asymmetry the host has and this cannot: the REST submit endpoint
+ * (`submit.ts:135`) makes the field REQUIRED. The mock serves the postMessage
+ * bridge, which is the `.optional()` arm, so absence is correct here.
+ */
+export function idempotencyKeyRefusal(payload) {
+    const key = payload?.idempotencyKey;
+    if (key === undefined)
+        return null;
+    return blockIdempotencyKeyRejection(key);
+}
+//# sourceMappingURL=mockHostIdempotency.js.map

package/dist/internal/mockHostScopes.d.ts

@@ -0,0 +1,100 @@
+/**
+ * mockHostScopes.ts — the dev host's STORAGE SCOPE GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-01). An app was built from the documented
+ * onboarding prompt, shipped `useAppStorage()` for every save, and declared only
+ * `ai:write:budgeted` in its manifest. It passed **198 unit tests, the dev
+ * harness, `civitai app validate`, and a full submit** — then every save in
+ * production failed:
+ *
+ *     "message": "storage set requires the apps:storage:write scope",
+ *     "code": -32003,
+ *     "data": { "code": "FORBIDDEN", "httpStatus": 403, "path": "apps.storage.set" }
+ *
+ * which the viewer saw as *"Saving failed for an unknown reason… try again"*.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE. `createMockHost` served
+ * storage unconditionally — its own options doc said so in as many words
+ * ("`APP_STORAGE_*` is answered either way (the mock host always serves storage
+ * now)") — so the one failure mode that actually ships was the only storage
+ * failure mode the mock could not produce. It modelled the per-value cap, both
+ * per-viewer budgets, the row limit and an induced transport failure, and not
+ * the scope.
+ *
+ * So this is not a new feature so much as the missing arm of an existing
+ * simulation: the dev host already models `ai:write:budgeted` (it has a flag,
+ * a consent round-trip and an un-grantable case). Storage had nothing.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and what is inferred here.
+ *
+ * `BLOCK_SCOPES` in `@civitai/app-sdk` states the mechanism: the storage scopes
+ * "have no OAuth bit … the server gates them by presence in the block's
+ * APPROVED SCOPE SET, not a bitmask". Presence is therefore the whole test, and
+ * it is what {@link requiredStorageScope} models.
+ *
+ * 🔴 ONE ROW IS MEASURED; THE REST ARE INFERRED FROM THE SCOPE NAMES. The
+ * incident above is direct evidence for exactly one pair —
+ * `apps.storage.set` → `apps:storage:write` — because the server named both in
+ * its own refusal. Every other row below reads a `:read` scope onto a read op
+ * and a `:write` scope onto a write op, which is the only split the names admit
+ * but is still an inference about another service. Nothing in this repository
+ * can verify it: there is no op→scope table in `@civitai/app-sdk`, none in this
+ * package, and the server's own table is not vendored.
+ *
+ * The consequence matters because enforcement is ON by default: a row that is
+ * WRONG fails a CORRECT app's suite. If that happens, the row is the suspect —
+ * not the app. Fix the row and say what the server did instead.
+ *
+ * `SHARED_REPORT` is the row to doubt first. It is mapped to
+ * `apps:storage:shared:write` because `useSharedStorage().report()` files a row
+ * in the shared store, so it is a write by construction — but a server is also
+ * free to treat an abuse report as a moderation path outside the store's own
+ * gate, in which case this row over-gates and should be removed rather than
+ * weakened.
+ */
+/** Every message type this gate governs. Exported for the ledger test. */
+export declare function gatedStorageMessages(): string[];
+/**
+ * The scope `type` needs, or `null` when this gate does not govern it.
+ *
+ * `null` is the ordinary answer — the overwhelming majority of block→host
+ * messages are not storage.
+ */
+export declare function requiredStorageScope(type: string): string | null;
+/**
+ * The refusal text. Modelled on the server's own prose for the one case it was
+ * observed emitting: *"storage set requires the apps:storage:write scope"*.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING, and do not render it to a viewer.
+ * `@civitai/app-sdk`'s `appStorageErrors.ts` is explicit that host refusal prose
+ * is "not localized, not written for an end user, and free to change", and that
+ * an authorization failure deliberately classifies as `null` through
+ * `classifyAppStorageError` — which is exactly what this message does, matching
+ * production rather than inventing a classification the real host does not send.
+ * That `null` arm is also why *"please try again"* is the wrong copy for it: a
+ * missing scope is a manifest defect and no number of retries fixes it.
+ */
+export declare function storageScopeDeniedMessage(type: string, scope: string): string;
+/**
+ * The reply payload that refuses `type`, type-correct for that reply's own
+ * contract.
+ *
+ * 🔴 EVERY STORAGE REPLY CARRIES `error?`, AND A NON-EMPTY `error` IS THE REJECT
+ * SIGNAL — `@civitai/app-sdk`'s messages module calls it "the
+ * `APP_STORAGE_GET_RESULT` value-or-error convention: consumers treat a
+ * non-empty `error` as the failure signal". So a refusal does not need a new
+ * wire field, a new constant, or an `@civitai/app-sdk` change — which also
+ * means it needs no peer-range bump, the hazard that once left 27 of 43 test
+ * files collecting zero tests in this very package.
+ *
+ * The DATA fields are still required by each reply's type, so each arm supplies
+ * an empty-but-valid one rather than omitting it: a reply that fails its own
+ * contract risks being dropped by the host-message validator, which would
+ * present as a HANG rather than a refusal.
+ */
+export declare function storageScopeDeniedPayload(type: string, requestId: string | undefined, error: string): Record<string, unknown>;
+/** The reply type for a block→host storage message. Uniform across the family. */
+export declare function storageResultType(type: string): string;
+//# sourceMappingURL=mockHostScopes.d.ts.map

package/dist/internal/mockHostScopes.js

@@ -0,0 +1,171 @@
+/**
+ * mockHostScopes.ts — the dev host's STORAGE SCOPE GATE.
+ *
+ * THE MOTIVATING FAILURE (2026-10-01). An app was built from the documented
+ * onboarding prompt, shipped `useAppStorage()` for every save, and declared only
+ * `ai:write:budgeted` in its manifest. It passed **198 unit tests, the dev
+ * harness, `civitai app validate`, and a full submit** — then every save in
+ * production failed:
+ *
+ *     "message": "storage set requires the apps:storage:write scope",
+ *     "code": -32003,
+ *     "data": { "code": "FORBIDDEN", "httpStatus": 403, "path": "apps.storage.set" }
+ *
+ * which the viewer saw as *"Saving failed for an unknown reason… try again"*.
+ *
+ * 🔴 THE REASON IT GOT THAT FAR IS THIS FILE'S ABSENCE. `createMockHost` served
+ * storage unconditionally — its own options doc said so in as many words
+ * ("`APP_STORAGE_*` is answered either way (the mock host always serves storage
+ * now)") — so the one failure mode that actually ships was the only storage
+ * failure mode the mock could not produce. It modelled the per-value cap, both
+ * per-viewer budgets, the row limit and an induced transport failure, and not
+ * the scope.
+ *
+ * So this is not a new feature so much as the missing arm of an existing
+ * simulation: the dev host already models `ai:write:budgeted` (it has a flag,
+ * a consent round-trip and an un-grantable case). Storage had nothing.
+ *
+ * ---
+ *
+ * WHAT THE SERVER ACTUALLY DOES, and what is inferred here.
+ *
+ * `BLOCK_SCOPES` in `@civitai/app-sdk` states the mechanism: the storage scopes
+ * "have no OAuth bit … the server gates them by presence in the block's
+ * APPROVED SCOPE SET, not a bitmask". Presence is therefore the whole test, and
+ * it is what {@link requiredStorageScope} models.
+ *
+ * 🔴 ONE ROW IS MEASURED; THE REST ARE INFERRED FROM THE SCOPE NAMES. The
+ * incident above is direct evidence for exactly one pair —
+ * `apps.storage.set` → `apps:storage:write` — because the server named both in
+ * its own refusal. Every other row below reads a `:read` scope onto a read op
+ * and a `:write` scope onto a write op, which is the only split the names admit
+ * but is still an inference about another service. Nothing in this repository
+ * can verify it: there is no op→scope table in `@civitai/app-sdk`, none in this
+ * package, and the server's own table is not vendored.
+ *
+ * The consequence matters because enforcement is ON by default: a row that is
+ * WRONG fails a CORRECT app's suite. If that happens, the row is the suspect —
+ * not the app. Fix the row and say what the server did instead.
+ *
+ * `SHARED_REPORT` is the row to doubt first. It is mapped to
+ * `apps:storage:shared:write` because `useSharedStorage().report()` files a row
+ * in the shared store, so it is a write by construction — but a server is also
+ * free to treat an abuse report as a moderation path outside the store's own
+ * gate, in which case this row over-gates and should be removed rather than
+ * weakened.
+ */
+import { BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+/**
+ * Block→host message type → the scope the server requires to answer it.
+ *
+ * Only storage surfaces appear here. The money path keeps its own flag
+ * (`consentGranted`) in `mockHost.ts`, deliberately: `buzzBudget` is conditional
+ * on it and `setScenario` can toggle it mid-session, so folding it in here would
+ * give one scope two sources of truth.
+ */
+const STORAGE_SCOPE_BY_MESSAGE = {
+    // Per-app, per-viewer KV store.
+    APP_STORAGE_GET: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_LIST: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_QUOTA: BLOCK_SCOPES.APPS_STORAGE_READ,
+    APP_STORAGE_SET: BLOCK_SCOPES.APPS_STORAGE_WRITE, // ← the MEASURED row
+    APP_STORAGE_DELETE: BLOCK_SCOPES.APPS_STORAGE_WRITE,
+    // Shared, cross-user store.
+    SHARED_LIST: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET_COUNT: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_GET_COUNTS: BLOCK_SCOPES.APPS_STORAGE_SHARED_READ,
+    SHARED_APPEND: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_VOTE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_UNVOTE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_WITHDRAW: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_UPDATE: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE,
+    SHARED_REPORT: BLOCK_SCOPES.APPS_STORAGE_SHARED_WRITE, // ← doubt this one first
+};
+/** Every message type this gate governs. Exported for the ledger test. */
+export function gatedStorageMessages() {
+    return Object.keys(STORAGE_SCOPE_BY_MESSAGE).sort();
+}
+/**
+ * The scope `type` needs, or `null` when this gate does not govern it.
+ *
+ * `null` is the ordinary answer — the overwhelming majority of block→host
+ * messages are not storage.
+ */
+export function requiredStorageScope(type) {
+    return STORAGE_SCOPE_BY_MESSAGE[type] ?? null;
+}
+/**
+ * The refusal text. Modelled on the server's own prose for the one case it was
+ * observed emitting: *"storage set requires the apps:storage:write scope"*.
+ *
+ * 🔴 DO NOT LET A BLOCK BRANCH ON THIS STRING, and do not render it to a viewer.
+ * `@civitai/app-sdk`'s `appStorageErrors.ts` is explicit that host refusal prose
+ * is "not localized, not written for an end user, and free to change", and that
+ * an authorization failure deliberately classifies as `null` through
+ * `classifyAppStorageError` — which is exactly what this message does, matching
+ * production rather than inventing a classification the real host does not send.
+ * That `null` arm is also why *"please try again"* is the wrong copy for it: a
+ * missing scope is a manifest defect and no number of retries fixes it.
+ */
+export function storageScopeDeniedMessage(type, scope) {
+    return `${verbFor(type)} requires the ${scope} scope`;
+}
+/**
+ * The server names the OPERATION, not the message type, in its refusal
+ * (`storage set …`, on path `apps.storage.set`). Mirror that so a developer
+ * grepping their logs for the production string finds the dev one too.
+ */
+function verbFor(type) {
+    const shared = type.startsWith('SHARED_');
+    const op = type
+        .replace(/^APP_STORAGE_/, '')
+        .replace(/^SHARED_/, '')
+        .toLowerCase()
+        .replace(/_/g, ' ');
+    return shared ? `shared storage ${op}` : `storage ${op}`;
+}
+/**
+ * The reply payload that refuses `type`, type-correct for that reply's own
+ * contract.
+ *
+ * 🔴 EVERY STORAGE REPLY CARRIES `error?`, AND A NON-EMPTY `error` IS THE REJECT
+ * SIGNAL — `@civitai/app-sdk`'s messages module calls it "the
+ * `APP_STORAGE_GET_RESULT` value-or-error convention: consumers treat a
+ * non-empty `error` as the failure signal". So a refusal does not need a new
+ * wire field, a new constant, or an `@civitai/app-sdk` change — which also
+ * means it needs no peer-range bump, the hazard that once left 27 of 43 test
+ * files collecting zero tests in this very package.
+ *
+ * The DATA fields are still required by each reply's type, so each arm supplies
+ * an empty-but-valid one rather than omitting it: a reply that fails its own
+ * contract risks being dropped by the host-message validator, which would
+ * present as a HANG rather than a refusal.
+ */
+export function storageScopeDeniedPayload(type, requestId, error) {
+    switch (type) {
+        // ---- reads: data field + error ----
+        case 'APP_STORAGE_GET':
+            return { requestId, value: null, error };
+        case 'APP_STORAGE_LIST':
+            return { requestId, keys: [], error };
+        case 'APP_STORAGE_QUOTA':
+            return { requestId, usedBytes: 0, rowCount: 0, limitBytes: 0, limitRows: 0, error };
+        case 'SHARED_LIST':
+            return { requestId, items: [], error };
+        case 'SHARED_GET':
+            return { requestId, item: null, error };
+        case 'SHARED_GET_COUNT':
+            return { requestId, count: 0, error };
+        case 'SHARED_GET_COUNTS':
+            return { requestId, counts: {}, error };
+        // ---- writes: ok:false + error ----
+        default:
+            return { requestId, ok: false, error };
+    }
+}
+/** The reply type for a block→host storage message. Uniform across the family. */
+export function storageResultType(type) {
+    return `${type}_RESULT`;
+}
+//# sourceMappingURL=mockHostScopes.js.map

package/dist/transport/transport.d.ts

@@ -232,6 +232,63 @@ export declare function nextRequestId(): string;
  * string where it is unavailable (older webviews / non-secure contexts / test).
  */
 export declare function generateIdempotencyKey(): string;
+/**
+ * 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 declare class InvalidIdempotencyKeyError extends Error {
+    /** The rejected value, verbatim, for logging. The block's own construction. */
+    readonly idempotencyKey: unknown;
+    /** Which hook refused it, e.g. `'useBuzzWorkflow.submit'`. */
+    readonly source: string;
+    constructor(source: string, idempotencyKey: unknown, message: string);
+}
+/**
+ * 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 declare function resolveIdempotencyKey(source: string, supplied: string | undefined): string;
 /**
  * A request that got NO REPLY before its timeout elapsed.
  *

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(() => {