@civitai/app-sdk 0.47.0 → 0.49.0

package/README.md

@@ -19,12 +19,19 @@ pnpm add @civitai/app-sdk
 | `cookies/*` — `sealCookie`, `unsealCookie`, `buildSetCookieHeader`, `readCookie` | AES-256-GCM authenticated cookie crypto. Use to seal a session blob (refresh token, expiry, scope) into an `httpOnly` cookie with zero external session store. |
 | `orchestrator/*` — `createOrchestratorClient`, `estimateWorkflow`, `submitWorkflow`, `getWorkflow`, `pollWorkflow`, `buildTextToImageBody`, `buildImageGenBody`, `buildWorkflowBody`, `WORKFLOW_STEP_TYPES`, `IMAGE_GEN_ENGINES`, `isTerminal`, `extractImageUrls`, `OrchestratorError`, `WorkflowSnapshot`, `GenerateInput`, `ImageGenInput`, `WorkflowStepType`, `ImageGenEngine`, `DEFAULT_MODEL_AIR` | Orchestrator workflow glue — types, body builders, raw HTTP, and long-poll helper. Client + server safe (fetch-only). `estimateWorkflow` calls `?whatif=true` to preview Buzz cost without spending. `pollWorkflow` long-polls to terminal status. `WORKFLOW_STEP_TYPES` is the catalog of every step `$type` the orchestrator accepts. |
 | `orchestrator/steps` — `WorkflowStepTemplates`, `WorkflowStepTemplateFor`, `WorkflowStepInputFor`, `AnyWorkflowStepTemplate`, `TypedWorkflowTemplate` | **Type-only** subpath (0 runtime bytes) keying the orchestrator's generated workflow-step shapes from `@civitai/client` by wire `$type`, so apps compose real step bodies against types that track the spec instead of hand-maintained copies. Requires the optional peer `@civitai/client@beta`. Type surface only — it grants no submit permission; see "Typed step shapes" below. |
-| `blocks/*` — `defineBlock`, `BlockManifestError`, `BLOCK_SCOPES`, `BLOCK_SCOPE_PATTERN`, `isMessage`, types (`BlockManifestV1`, `BlockContext`, `BlockToken`, `BlockSettings`, `ViewerInfo`, `ThemeInfo`, `BlockWorkflowSnapshot`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`, …) | Framework-agnostic contract for [Civitai Apps](https://github.com/civitai/civitai-app-starters/blob/main/docs/build-your-first-app-block.md). `defineBlock(config)` validates a `BlockManifestV1` at startup so authoring mistakes surface in `pnpm dev` instead of at `civitai app validate`/submit. Ships a byte-identical copy of the server-published canonical JSON Schema (draft 2020-12, https://civitai.com/schemas/app-block/v1.json) at the `./schemas/app-block/v1.json` subpath for offline validation; a CI drift-check keeps it in sync. Runtime-agnostic — no React or DOM types. Hooks and the iframe transport live in a separate package. |
+| `blocks/*` — `BlockManifestError`, `BLOCK_SCOPES`, `BLOCK_SCOPE_PATTERN`, `isMessage`, types (`BlockManifestV1`, `BlockContext`, `BlockToken`, `BlockSettings`, `ViewerInfo`, `ThemeInfo`, `BlockWorkflowSnapshot`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`, …) | Framework-agnostic contract for [Civitai Apps](https://github.com/civitai/civitai-app-starters/blob/main/docs/build-your-first-app-block.md). Ships a byte-identical copy of the server-published canonical JSON Schema (draft 2020-12, https://civitai.com/schemas/app-block/v1.json) at the `./schemas/app-block/v1.json` subpath for offline validation; a CI drift-check keeps it in sync. Runtime-agnostic and **zero runtime dependencies** — no React, no DOM types, nothing in your install graph. Hooks and the iframe transport live in a separate package. |
+| `manifest/*` — `defineBlock`, `SCHEMA_DIVERGENCES`, `KNOWN_GAPS` (**Node only**) | Build-time manifest validation. `defineBlock(config)` compiles the vendored canonical schema with [Ajv](https://ajv.js.org) and validates a `BlockManifestV1` against it, so authoring mistakes surface in `pnpm dev` instead of at `civitai app validate`/submit. It is **derived from the schema, not a hand-written mirror of it** — that mirror is what produced [#330](https://github.com/civitai/civitai-app-starters/issues/330). Needs `node:fs` and the optional peer `ajv`, which is why it is not on the browser-facing `./blocks` surface. |
+| `vite/*` — `blockManifestPlugin` (**Node only**) | A Vite plugin wrapping `defineBlock`, firing from `configResolved` — the one hook Vite calls on both the dev-server and the build path. Every block scaffold registers it, so `pnpm dev`, `pnpm dev:harness` and `pnpm build` all fail on a bad manifest with the offending field path. Optional peers: `ajv` (runtime) and `vite` (types only). |
 
 ## Subpath imports
 
 ```ts
-import { defineBlock, BLOCK_SCOPES } from '@civitai/app-sdk/blocks';
+import { BLOCK_SCOPES, isSignedIn } from '@civitai/app-sdk/blocks';
+// Build-time manifest validation (NODE ONLY — needs the optional peer `ajv`).
+// Most projects want the Vite plugin below rather than calling this directly:
+import { defineBlock } from '@civitai/app-sdk/manifest';
+// The same gate as a Vite plugin (NODE ONLY — optional peers `ajv` + `vite`):
+import { blockManifestPlugin } from '@civitai/app-sdk/vite';
 // Type-only: the orchestrator's generated per-step shapes. Needs the optional
 // peer `@civitai/client@beta` — see "Typed step shapes" below:
 import type { TypedWorkflowTemplate } from '@civitai/app-sdk/orchestrator/steps';
@@ -37,9 +44,11 @@ import manifestSchema from '@civitai/app-sdk/schemas/app-block/v1.json' with { t
 ## Civitai Apps contract (`@civitai/app-sdk/blocks`)
 
 > Building a **Civitai App** (an iframe-embedded UI on a civitai.com page)? This
-> subpath is the framework-agnostic contract — manifest types, scope strings,
-> the `postMessage` protocol, and the `defineBlock` validator. The React hooks +
-> transport that consume it live in
+> subpath is the framework-agnostic contract — manifest types, scope strings and
+> the `postMessage` protocol. (The `defineBlock` validator moved to the node-only
+> [`@civitai/app-sdk/manifest`](#defineblock-validator-rules) subpath; `./blocks`
+> keeps zero runtime dependencies.) The React hooks + transport that consume it
+> live in
 > [`@civitai/blocks-react`](https://www.npmjs.com/package/@civitai/blocks-react).
 > Start from the runnable [examples](https://github.com/civitai/civitai-app-starters/tree/main/starters/examples).
 >
@@ -103,8 +112,7 @@ interface BlockInitPayload {
 
 | Export | What |
 |---|---|
-| `defineBlock({ manifest })` | Validates a `BlockManifestV1` (subset of the server checks) and returns it. Call at module scope so authoring mistakes throw before mount. Throws `BlockManifestError` (has a `.field` dot-path). |
-| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | The 15 known block scope strings (the authoritative enum `defineBlock` validates against) + the `domain:verb:target` format-helper regex. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
+| `BLOCK_SCOPES` / `BLOCK_SCOPE_PATTERN` | The 15 known block scope strings (the authoritative enum the canonical schema validates `scopes` against) + the `domain:verb:target` format-helper regex. A scope is valid only if it's a member of `BLOCK_SCOPES`, matching the [canonical schema](https://civitai.com/schemas/app-block/v1.json). |
 | `isMessage(data, type)` | Discriminator-only message narrowing (see above). |
 | `isModelSlotContext(ctx)` / `isPageSlotContext(ctx)` | Runtime narrowing for the `slotId`-discriminated `BlockContext` union. Real checks on a value that crossed a `postMessage` boundary — they verify every field they assert, not just `slotId`. |
 | `isSignedIn(viewer)` | **The sign-in gate.** `isSignedIn(useBlockContext().viewer)` — do not open-code it as `viewer !== null` or `viewer?.signedIn === true`. Which of those is correct has already changed once with the host contract, and this is the one place it is decided. It reads neither `viewer.id` nor `viewer.username` (both `@deprecated`), so nothing written through it changes when those are removed. Need the identity rather than the presence? `useViewer()` — scope-gated and audited per call. |
@@ -154,31 +162,67 @@ const body: WorkflowBody = {
 
 ### `defineBlock` validator rules
 
-Mirrors a strict subset of the civitai/civitai server gate. It throws on:
-
-- A missing **required** field: `$schema`, `appId`, `blockId`, `version`, `name`,
-  `type`, `targets`, `scopes`, `iframe`, `contentRating`, `minApiVersion`.
-- `$schema` ≠ `https://civitai.com/schemas/app-block/v1.json`.
-- `blockId` not matching the canonical `/^[a-z][a-z0-9-]*[a-z0-9]$/` (DNS-subdomain-safe:
-  lowercase, starts with a letter, ends alphanumeric) or outside 3–40 chars —
-  the blockId becomes `<blockId>.civit.ai`; `version` not semver; `name` > 80 chars.
-- `type` not `block` | `embed`; `contentRating` not `g|pg|pg13|r|x`.
-- **Empty `scopes`** (must be a non-empty array) or any scope that isn't one of
-  the 15 known block scopes (`BLOCK_SCOPES`). The [canonical schema](https://civitai.com/schemas/app-block/v1.json)
-  validates `scopes` by **enum membership**, so a well-formed but unknown scope
-  (e.g. `models:read:all`) is rejected; PascalCase like `ModelsReadSelf` gets a
-  pointed error.
-- **Empty `targets`**, or a target with a non-string `slotId` / non-integer `priority`.
-- `iframe.src` not https (http only for `localhost`/`127.0.0.1`/`[::1]`/`*.localhost`);
-  a banned sandbox token (`allow-same-origin`, any `allow-top-navigation*`);
-  non-positive integer `minHeight`; bad `maxHeight`; non-boolean `resizable`.
-- `settings` with a bad key (must be `snake_case`), > 32 fields, or a field
-  missing/mis-typed `scope` / `type` / `label` / `description`.
-
-> The validator does **not** check that `iframe.src` hostname equals
-> `<blockId>.<APPS_DOMAIN>` or that the path is root — those are enforced
-> **server-side** at submit time (gotcha #33). Keep `iframe.src` =
-> `https://<blockId>.civit.ai/` (root, no path prefix) and your Vite `base: '/'`.
+**There is no rule list here, and that is the point.** `defineBlock` does not
+maintain one: it compiles the vendored copy of the
+[canonical schema](https://civitai.com/schemas/app-block/v1.json) with
+[Ajv](https://ajv.js.org) and validates against **that**. Every `required`,
+`enum`, `pattern`, bound, `additionalProperties` and `allOf` the canonical
+expresses is enforced, and moves when the canonical moves. The schema is the
+rule list; read it, or read the errors.
+
+That is [#330](https://github.com/civitai/civitai-app-starters/issues/330)'s own
+proposed fix. The previous implementation hand-mirrored the schema, and the
+mirror diverged exactly as the issue predicted: it required 11 fields where the
+canonical requires **five** (`blockId`, `version`, `name`, `contentRating`,
+`scopes`), required `appId` — not a canonical property at all — and *required*
+the SERVER-OWNED `iframe.src` that `civitai app submit` refuses, so it rejected
+every `block.manifest.json` this repo ships.
+
+On top of the schema, `defineBlock` applies exactly five extra rules, each
+mirroring a server rejection the canonical states only in **prose**:
+
+| Rule | The canonical prose it mirrors |
+|---|---|
+| a dev-set **`iframe.src`** is rejected | *"SERVER-OWNED. Do NOT set `iframe.src` — the platform assigns it."* The JSON-Schema `not` is deliberately absent; the top-level `allOf` `$comment` says the platform validator and the Go CLI reject it instead. |
+| a dev-set **`trustTier`** is rejected | *"SERVER-OWNED … the platform assigns the trust tier during review."* Same shape. |
+| **`iframe.sandbox`** rejects `allow-same-origin` and every `allow-top-navigation*` token | *"Never combine allow-same-origin with allow-scripts."* Top-navigation is refused because a block must route navigation through the `NAVIGATE` postMessage. |
+| every **`scopeJustifications`** key must be a scope in `scopes` | *"The requirement is enforced imperatively by the manifest validator (not expressed as JSON-Schema conditionals here)."* |
+| **`settings`** is validated against the W3 settings meta-schema | Not in the app-block schema at all — settings are validated server-side by `manifest-settings.meta.schema.ts`. |
+
+Each is **strictly additive**: it can only reject a manifest Ajv accepted, never
+relax a canonical rule. `test/manifest/divergences.test.ts` asserts exactly that
+per entry — the fixture must be schema-VALID and `defineBlock`-REJECTED — and the
+table and the fixture set must be the same set, so a sixth hand-written rule with
+no entry fails the suite.
+
+> **Passing is necessary, not sufficient**, and it is **not** a replacement for
+> `civitai app validate` (the Go CLI's local pre-check against the same
+> canonical). Run that before `civitai app submit`. `KNOWN_GAPS` in
+> `src/manifest/defineBlock.ts` names each thing only the server can check —
+> including one that cuts the *other* way: the canonical's sandbox description is
+> an **allowlist** (*"Unverified tier allows only: allow-scripts, allow-forms"*)
+> while the rule above is a denylist, so `allow-popups`, `allow-modals` and
+> `allow-downloads` **pass here and may be refused at review**. The tier is
+> assigned server-side, so it cannot be enforced locally.
+
+**Where it runs.** Every scaffold that ships a `block.manifest.json`
+(`starters/civitai-block-starter` and all six `starters/examples/*`) registers
+`blockManifestPlugin` from `@civitai/app-sdk/vite` in its `vite.config.ts`. It
+fires from Vite's `configResolved`, the one hook called on both the dev-server
+and the build path — so `pnpm dev`, `pnpm dev:harness` and `pnpm build` all fail
+loudly on a bad manifest, with the offending field path in the message. Add
+`ajv` to your devDependencies (it is an optional peer):
+
+```bash
+pnpm add -D ajv
+```
+
+```ts
+// vite.config.ts — drop this into your existing `defineConfig({ plugins: [...] })`.
+import { blockManifestPlugin } from '@civitai/app-sdk/vite';
+
+const plugins = [blockManifestPlugin()];
+```
 
 ### Web storage in a block (`@civitai/app-sdk/safe-storage`)
 

package/dist/blocks/appStorageErrors.d.ts

@@ -0,0 +1,390 @@
+/**
+ * The App Storage rejection MESSAGES the host puts on the wire — the only site
+ * in this repository that spells them **in executable code**, sibling of
+ * `appStorageLimits.ts`, which owns the numbers.
+ *
+ * 🔴 **"IN EXECUTABLE CODE" IS THE WHOLE CLAIM — do not read it wider.** What
+ * `tests/guards/app-storage-error-strings.test.mjs` actually enforces is
+ * narrower still: every `error:` value inside an `APP_STORAGE_*_RESULT` payload
+ * in the scanned mocks must NAME a constant from this module. It sees nothing
+ * else. Hand-typed copies of these six strings live today in
+ * `mockHost.ts`'s option docblocks (which ship in the published `.d.ts`),
+ * in `blocks-react/test/validate.test.ts`'s fixture, in this guard's own
+ * control assertions, and in both READMEs — and every one of them is invisible
+ * to the guard. If the host rewords a message they go stale silently. Grep the
+ * literal, not just the identifier, when a message moves.
+ *
+ * 🔴 **THE WIRE CARRIES A MESSAGE, NOT A CODE.** The host's router throws a
+ * `TRPCError` that has BOTH: `code: 'PAYLOAD_TOO_LARGE'` and a per-site
+ * `message`. The bridge that answers `APP_STORAGE_SET` forwards
+ * **`err.message`** and never the code, so `PAYLOAD_TOO_LARGE` is a string a
+ * block CANNOT receive. `createMockHost` emitted it anyway for three releases:
+ * a block that branched on it took the actionable branch under `dev:mock` and
+ * the generic one in production, and nothing local could see the difference.
+ * That is civitai/civitai-app-starters#343, and this module is its fix — one
+ * spelling, shared by the mock, the example harness and any block matcher.
+ *
+ * ## 🔴 There is NO list here of "every string a block can receive" — on purpose
+ *
+ * **This is the THIRD attempt at this section, and the absence of that list is
+ * what the first two attempts cost. It is not an omission to be helpfully
+ * filled in.** Both earlier drafts shipped, and each was wrong by more than its
+ * author had checked:
+ *
+ *   1. **Draft 1 (RETRACTED)** presented six strings as "every storage-rejection
+ *      string the host can put on the wire". It had read only the
+ *      `PAYLOAD_TOO_LARGE` sites, so it missed the entire authorization family.
+ *   2. **Draft 2 (RETRACTED)** kept the six, added a table of eight
+ *      authorization messages "measured in the same read", and presented THAT
+ *      as the surface. Also wrong. It missed, in the same file: `Apps are not
+ *      enabled`, thrown from TWO different gates with one spelling — the
+ *      `enforceAppBlocksFlag` middleware (defined `:249`, throws at `:255`
+ *      query / `:257` mutation), which is `.use()`d on all five storage
+ *      procedures at `:470`, `:509`, `:938`, `:1022`, `:1106` BEFORE their
+ *      `.input()`, so it fires before anything else on every call; and
+ *      `assertAppBlocksEnabledForTokenUser` (`:139-155`, throwing at `:153`),
+ *      reached from `resolveStorageContext`. Grepping `enforceAppBlocksFlag`
+ *      will NOT find `:153`. Also missed: `block token subject could
+ *      not be resolved` (`:148`, called unconditionally from
+ *      `resolveStorageContext`), `review token subject could not be resolved`
+ *      (`:82`) and `Apps authoring is not enabled for this account` (`:89`).
+ *      `Apps are not enabled` is a feature-flag kill switch — neither a ceiling
+ *      nor an authorization failure, so it fit neither published table.
+ *
+ * Each enumeration was wider than the last and each was still short; the
+ * router carries **21** `throw new TRPCError` sites and **17** distinct
+ * messages, against draft 2's 14. A third list would be the same defect a third
+ * time.
+ *
+ * 🔴 **The completeness claim is the wrong SHAPE, not merely a stale list.** The
+ * failure is not "this might go out of date" — it is that "the set of strings a
+ * block can receive" is the host's whole error surface, which this repository
+ * does not own, cannot observe from here, and has now mis-measured twice while
+ * believing otherwise. Do not soften this into "the list below may be
+ * incomplete" and restore one. What replaces it needs no completeness at all:
+ *
+ * - **This module classifies the `PAYLOAD_TOO_LARGE` family plus the bridge's
+ *   fallback — a set THIS REPOSITORY CHOSE, not a set the host guarantees
+ *   closed.** It is the five `PAYLOAD_TOO_LARGE` throws in `apps.router.ts`
+ *   (`:568`, `:783`, `:791`, `:845`, `:853`) and the `'storage request failed'`
+ *   literal at `IframeHost.tsx:287`. Naming what it classifies is a decision
+ *   about scope; it needs no completeness claim to be useful, and it must not
+ *   be dressed as one. 🔴 **A ceiling the host enforces OUTSIDE that family
+ *   already exists** — see "Ceilings outside this set" below.
+ * - **Every OTHER host rejection reaches a block on the same `error` field and
+ *   classifies `null`.** This is the whole of what a block author needs, it
+ *   requires no enumeration, and it stays true when the host adds, rewords or
+ *   deletes a message. It holds STRUCTURALLY, from two facts rather than from a
+ *   survey: the bridge's catch arms are **blanket** `catch (err)` with no code
+ *   filter (`IframeHost.tsx:2395` GET, `:2427` SET, `:2458` DELETE, `:2508`
+ *   LIST, `:2535` QUOTA), each forwarding `err.message` verbatim via
+ *   `storageErrorMessage()`; and {@link classifyAppStorageError} answers `null`
+ *   for everything outside the ceiling patterns, which is checkable in this
+ *   file without consulting the host at all.
+ * - **The RECIPE beats any prose in this repository — and is still NOT a
+ *   completeness check.** It is strictly wider than every list anyone has
+ *   written: it found all 21 `TRPCError` sites, including the four draft 2
+ *   missed. It is NECESSARY, NOT SUFFICIENT — see "What the recipe cannot
+ *   see" under "Re-deriving it".
+ *
+ * ## Ceilings outside this set
+ *
+ * 🔴 **The host enforces size ceilings that are NOT `TRPCError` throws and are
+ * therefore invisible to both the recipe and this module.** They are zod
+ * `.max()` bounds on the procedures' `.input()` schemas, so tRPC refuses the
+ * call with `BAD_REQUEST` before any handler runs. Measured in
+ * `apps.router.ts` on `civitai/civitai` `main`, 2026-09-21:
+ *
+ *   - `const keyInput = z.string().min(1).max(200)` (`:460`) — the `key`
+ *     argument of `get` (`:471`), `set` (`:511`) and `delete` (`:939`);
+ *   - `list` (`:1025-1027`): `prefix: z.string().max(200)`,
+ *     `cursor: z.string().max(400)`, `limit: …int().min(1).max(200)`.
+ *
+ * 🔴 **The 200-character KEY cap is the one a real block hits with no local
+ * warning.** Derive a key from a URL, a model name or a title and 201
+ * characters is ordinary. Nothing in this repository caps it: `useAppStorage`
+ * and `createMockHost` forward the key verbatim and the mock enforces no length
+ * gate (civitai/civitai-app-starters#370), so the write succeeds under
+ * `dev:mock` and fails forever in production. The zod refusal arrives on the
+ * same `error` field as everything else, so {@link classifyAppStorageError}
+ * answers `null` — and the recommended `null` copy ("try reloading the page")
+ * is WRONG for it: reloading re-mints the token and the write fails
+ * identically. If a block builds keys from untrusted-length input, cap or hash
+ * them at the block, and do not rely on a local run to tell you.
+ *
+ * 🔴 **So: wherever a list of host strings still appears — in this repo's
+ * READMEs, in the changeset, in `messages.ts`, in `@civitai/blocks-react`'s
+ * `src/hooks/useAppStorage.ts`, in the `kv-storage` example's `src/App.tsx`
+ * (which is where the "try reloading" copy lives), or in
+ * `test/blocks/appStorageErrors.test.ts` — it is ILLUSTRATIVE, NOT EXHAUSTIVE,
+ * and must be labelled as such.** Its job is to show a reader what the `null`
+ * bucket typically contains, never to bound it.
+ *
+ * ## Re-deriving it
+ *
+ * 🔴 **Not a `PAYLOAD_TOO_LARGE`-only grep** — that is structurally incapable of
+ * seeing anything but the ceiling family, and is how draft 1 came to claim a
+ * completeness it had not measured.
+ *
+ * ```sh
+ * # EVERY throw, not one code. Read the whole output; do not count from memory.
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n "new TRPCError" -A4
+ * # …and confirm the catch arms are still blanket (no code filter), which is
+ * # what makes "everything else classifies null" true:
+ * gh api repos/civitai/civitai/contents/src/components/AppBlocks/IframeHost.tsx \
+ *   --jq '.content' | base64 -d | grep -n "storageErrorMessage" -B12
+ * # …and the zod caps, which throw no TRPCError and so appear in NEITHER of the
+ * # two commands above:
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n "z\.string()\|z\.number()\|\.max("
+ * ```
+ *
+ * ### What the recipe cannot see
+ *
+ * 🔴 **A clean run of the three commands above is NOT proof of completeness —
+ * do not treat it as one.** Measured blind spots, both of which bit this file:
+ *
+ *   - **zod-enforced caps.** They are `.input()` bounds, not throws, so
+ *     `grep "new TRPCError"` cannot see them at all. That is why the third
+ *     command exists — and why "a new ceiling can only arrive as a new
+ *     `PAYLOAD_TOO_LARGE` throw" was deleted from this header: it was false
+ *     when it was written. See "Ceilings outside this set" above.
+ *   - **the bridge's own literal.** `'storage request failed'` is at
+ *     `IframeHost.tsx:287`, and `grep … -B12` prints the twelve lines BEFORE
+ *     each match — for the definition at `:282` that is 270–282, so line 287
+ *     never appears in the output. The recipe enumerates the CALL SITES of
+ *     `storageErrorMessage`, not its fallback. Read the function body.
+ *
+ * 🔴 **DO NOT re-derive the ceiling strings from this comment** — re-read the
+ * host. These are prose a server engineer wrote, not a published contract: they
+ * can be reworded in any deploy, and nothing will tell you. Which is also why
+ * {@link classifyAppStorageError} answers `null` rather than guessing, and why
+ * a block must branch on the CLASSIFICATION and render its OWN copy — see the
+ * warning on that function.
+ *
+ * One consequence worth stating plainly: `null` is a **BUSY** bucket, and its
+ * dominant real-world occupant is an expired or revoked token, not a rare
+ * unknown. Do not write a `default:` arm that assumes `null` means "transient,
+ * retry" — see the warning on {@link classifyAppStorageError}.
+ *
+ * ## Which ceiling each message names
+ *
+ * Two scopes, and the remedies differ:
+ *
+ * - **per-user** (`'per-user storage quota exceeded'`, `'per-user row limit
+ *   exceeded'`) — this viewer has filled their own budget for this app. The
+ *   ceilings are `APP_STORAGE_MAX_BYTES` / `APP_STORAGE_MAX_ROWS`;
+ *   the viewer can free space by deleting their own rows.
+ * - **app-wide** (`'app quota exceeded'`, `'app row limit exceeded'`) — the
+ *   app has filled a far larger umbrella shared across every viewer. One
+ *   viewer's delete will not reliably clear it; this is the developer's
+ *   problem, and `appStorageLimits.ts` deliberately does not export the
+ *   umbrella's value because nothing reports usage against it.
+ *
+ * A block will normally hit the per-user pair. Both are reachable, so a
+ * matcher that handles only one is a matcher with a silent hole.
+ */
+/**
+ * The host's per-value-cap message, as a function of the cap — a mirror of the
+ * template literal at `apps.router.ts:569`, which divides by 1024 and appends
+ * `KB cap`.
+ *
+ * 🔴 **THIS IS A TEMPLATE ON THE HOST, SO IT IS A TEMPLATE HERE.** Writing
+ * `'value exceeds 64KB cap'` as a literal would be true only while the cap is
+ * 64KB, and a string that silently stops matching the host the day the cap
+ * moves is the exact defect #343 is about — one spelling that drifts, with
+ * nothing able to notice. Derived from {@link APP_STORAGE_MAX_VALUE_BYTES} so
+ * the two move together.
+ *
+ * Exported from this module (not from `@civitai/app-sdk/blocks`) so a test can
+ * feed it a cap the constant cannot equal and watch the output move. Blocks
+ * want {@link APP_STORAGE_ERROR_VALUE_TOO_LARGE}.
+ */
+export declare function appStorageValueTooLargeMessage(capBytes?: number): string;
+/**
+ * A single value exceeded the per-value wire cap
+ * ({@link APP_STORAGE_MAX_VALUE_BYTES}). `apps.router.ts:568-569`.
+ *
+ * The only one of the six ceiling messages that is not a fixed string on the
+ * host — see {@link appStorageValueTooLargeMessage}.
+ */
+export declare const APP_STORAGE_ERROR_VALUE_TOO_LARGE: string;
+/** The APP-wide byte umbrella is full. `apps.router.ts:782-785`. */
+export declare const APP_STORAGE_ERROR_APP_QUOTA_EXCEEDED = "app quota exceeded";
+/** The APP-wide row umbrella is full. `apps.router.ts:790-793`. */
+export declare const APP_STORAGE_ERROR_APP_ROW_LIMIT = "app row limit exceeded";
+/**
+ * This viewer's byte budget for this app (`APP_STORAGE_MAX_BYTES`) is
+ * full. `apps.router.ts:844-847`.
+ */
+export declare const APP_STORAGE_ERROR_USER_QUOTA_EXCEEDED = "per-user storage quota exceeded";
+/**
+ * This viewer's row budget for this app (`APP_STORAGE_MAX_ROWS`) is
+ * full. `apps.router.ts:852-855`.
+ *
+ * The ceiling a block reaches first in practice: rows run out long before
+ * bytes do.
+ */
+export declare const APP_STORAGE_ERROR_USER_ROW_LIMIT = "per-user row limit exceeded";
+/**
+ * The bridge's fallback, used for any storage failure whose error carries no
+ * usable message — a transport fault, a non-`Error` throw, an upstream 5xx.
+ * `IframeHost.tsx:287`.
+ *
+ * 🔴 It is NOT specific to writes. Every `APP_STORAGE_*` catch arm goes
+ * through the same helper, so a `get`, `delete`, `list` or `getQuota` can
+ * reject with it too. Retryable, unlike the five ceilings.
+ */
+export declare const APP_STORAGE_ERROR_REQUEST_FAILED = "storage request failed";
+/**
+ * The **`PAYLOAD_TOO_LARGE` family** — one string per `PAYLOAD_TOO_LARGE` site
+ * in `apps.router.ts` — plus the bridge's fallback, as of the measurement in
+ * this file's header.
+ *
+ * 🔴 **NOT "every ceiling string the host can put on the wire", and NOT "every
+ * string a block can receive".** Two separate reasons, and both are load-
+ * bearing:
+ *
+ *   - The bridge's catch arms are blanket, so every other rejection the host
+ *     raises arrives on the SAME field and is absent here on purpose. `invalid
+ *     block token`, `block instance revoked`, `Apps are not enabled` and the
+ *     `storage … scope` template are examples of what that covers —
+ *     **illustrations, not a bound.** See this file's header for why no list
+ *     of them lives in this repository.
+ *   - 🔴 The host also enforces **size ceilings zod-side** (`key` capped at 200
+ *     characters on the `.input()` schema, and three more on `list`). Those
+ *     throw no `TRPCError`, so they are invisible to the re-derivation recipe
+ *     AND absent from this array, while being ceilings in every sense a block
+ *     cares about. See "Ceilings outside this set" in this file's header.
+ *
+ * This is the set `createMockHost` and the starter harnesses must draw from —
+ * enforced by `tests/guards/app-storage-error-strings.test.mjs`, so a
+ * hand-typed string cannot reappear at a mock rejection site.
+ *
+ * 🔴 **NOT RE-EXPORTED FROM `@civitai/app-sdk/blocks`, ON PURPOSE.** Publishing
+ * this array invites `APP_STORAGE_HOST_ERROR_MESSAGES.includes(err.message)`,
+ * which is EQUALITY against a frozen snapshot — narrower than
+ * {@link isAppStorageHostErrorMessage}, and narrower than
+ * {@link classifyAppStorageError}, by exactly the per-value message, whose cap
+ * the host is free to move. That is the matcher shape #343 exists to
+ * eliminate, so it must not become public API. Reach it by file path from a
+ * test or a guard; a block branches on the classifier's reason.
+ *
+ * 🔴 **A CLOSED SET IS A CLAIM ABOUT A MEASUREMENT, NOT A CONTRACT — and this
+ * measurement is narrow by construction, not merely stale.** Three separate
+ * gaps, and only the first is about the future:
+ *
+ *   1. The host can add a `PAYLOAD_TOO_LARGE` site or reword an existing one
+ *      in any deploy, and nothing here will notice.
+ *   2. **Today, already**, every non-ceiling rejection the host raises reaches
+ *      the block on the same field and is not in this array. 🔴 This is not a
+ *      hole to be filled — two drafts tried and both came up short (see this
+ *      file's header). Those strings are the host's session, approval and
+ *      feature-flag prose, not ceiling vocabulary, and enumerating them here
+ *      would invite exactly the equality matching the rest of this comment
+ *      argues against.
+ *   3. 🔴 **Today, already, a SIZE ceiling the host enforces is missing from
+ *      here too** — the zod caps, which are not `TRPCError` throws at all.
+ *      Unlike gap 2 this one IS ceiling vocabulary, which is why the array's
+ *      scope is spelled as "the `PAYLOAD_TOO_LARGE` family" above rather than
+ *      as "the ceilings". See "Ceilings outside this set" in this file's
+ *      header.
+ *
+ * So an unrecognised string is "some storage failure, unknown which" — NOT
+ * "some ceiling", and never "impossible".
+ */
+export declare const APP_STORAGE_HOST_ERROR_MESSAGES: readonly [string, "app quota exceeded", "app row limit exceeded", "per-user storage quota exceeded", "per-user row limit exceeded", "storage request failed"];
+/**
+ * Which rejection site a storage failure came from, as a closed set. `null`
+ * means the string matched nothing known — see {@link classifyAppStorageError}.
+ */
+export type AppStorageRejectionReason = 'value-too-large' | 'app-quota-exceeded' | 'app-row-limit' | 'user-quota-exceeded' | 'user-row-limit' | 'request-failed';
+/**
+ * Turn a rejection — the `Error` `useAppStorage().set()` throws, or its raw
+ * message — into the rejection site it came from, or `null` when the string
+ * matches nothing this SDK version knows about.
+ *
+ * Branch on the RESULT; render your OWN copy.
+ *
+ * 🔴 **NEVER RENDER THE MESSAGE ITSELF TO A VIEWER.** It is host-authored
+ * server prose in the same class as a workflow `snapshot.error`: not
+ * localized, not written for an end user, and free to change. Log it for
+ * yourself (`console.warn`) and show copy your app owns.
+ *
+ * 🔴 **`null` IS A REAL OUTCOME, NOT AN ERROR IN YOUR CODE — AND IT DOES NOT
+ * MEAN "TRANSIENT".** THREE different things land here, and only one is a
+ * retry:
+ *
+ *   - a ceiling message this SDK version has not seen (the host reworded one,
+ *     or added a site, and your block compiled against an older SDK);
+ *   - 🔴 **and, far more often in production, an authorization or kill-switch
+ *     failure.** The bridge's catch arms are blanket, so every other rejection
+ *     the host raises arrives on the same field and classifies `null` — for
+ *     example `invalid block token` (an expired token mid-session), `block
+ *     instance revoked`, `storage set requires the apps:storage:write scope`,
+ *     or `Apps are not enabled` (the feature flag, which fires before anything
+ *     else on every storage call). 🔴 **Those are ILLUSTRATIONS, not the set**:
+ *     see this module's header for why no list of them lives here.
+ *   - 🔴 **and a zod INPUT-VALIDATION refusal, which never reaches a handler at
+ *     all.** tRPC parses `.input()` before the procedure body, so a bound
+ *     violated there is a `BAD_REQUEST` with a zod-generated message — no
+ *     `TRPCError` anywhere in the router, and nothing this module classifies.
+ *     The one a real block hits: the host caps `key` at **200 characters**
+ *     (`z.string().min(1).max(200)`), and neither `useAppStorage` nor
+ *     `createMockHost` caps it locally, so a key derived from a URL or a model
+ *     name can save fine under `dev:mock` and fail forever in production. 🔴
+ *     **A RELOAD DOES NOT FIX THAT ONE** — see "Ceilings outside this set" in
+ *     this module's header.
+ *
+ * So **"Please try again" is the wrong copy for the `null` arm.** Retrying an
+ * expired token forever is the failure this warning exists to prevent. Write a
+ * generic arm that offers a RELOAD (which re-mints the token, and also covers
+ * a genuine transport blip) and concedes that saving may be unavailable — and
+ * keep `'request-failed'` separate if you want honest retry copy, since that
+ * reason really is the transport one.
+ *
+ * @example
+ * try {
+ *   await storage.set(key, note);
+ * } catch (err) {
+ *   console.warn('[my-app] save failed:', err);
+ *   switch (classifyAppStorageError(err)) {
+ *     case 'value-too-large':
+ *       return 'That note is too long to save. Try shortening it.';
+ *     case 'user-row-limit':
+ *     case 'app-row-limit':
+ *       return 'You have no note slots left. Delete one to make room.';
+ *     case 'request-failed':
+ *       // The bridge's fallback: genuinely a transport fault. Retry is honest.
+ *       return 'Could not save that note. Please try again.';
+ *     default:
+ *       // `null`: an unknown ceiling OR — usually — an expired/revoked token.
+ *       return 'Could not save that note. Try reloading the page; if it keeps ' +
+ *         'happening, saving may be unavailable for this app right now.';
+ *   }
+ * }
+ */
+export declare function classifyAppStorageError(error: unknown): AppStorageRejectionReason | null;
+/**
+ * Is `message` one of the `PAYLOAD_TOO_LARGE`-family strings above (or the
+ * bridge's fallback)?
+ *
+ * 🔴 Not "a string the host can produce", and not "a ceiling" either — it
+ * answers `false` for every non-ceiling rejection the host raises, all of which
+ * the host produces and the bridge forwards on the same field, AND for the
+ * host's zod-enforced size caps, which are ceilings it does not know about (see
+ * "Ceilings outside this set" in this file's header). It is a membership test
+ * over {@link APP_STORAGE_HOST_ERROR_MESSAGES}, nothing wider.
+ *
+ * Wider than `APP_STORAGE_HOST_ERROR_MESSAGES.includes(…)` by exactly one
+ * case: the per-value message is a template on the host, so any cap spelling
+ * is admitted — see {@link classifyAppStorageError}.
+ *
+ * Module-internal, like the array: it is a `classifyAppStorageError(…) !== null`
+ * convenience for `tests/guards/app-storage-error-strings.test.mjs`, which
+ * imports this file by PATH. A block wants the classifier's reason, not a
+ * yes/no on host prose.
+ */
+export declare function isAppStorageHostErrorMessage(message: unknown): message is string;
+//# sourceMappingURL=appStorageErrors.d.ts.map

package/dist/blocks/appStorageErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appStorageErrors.d.ts","sourceRoot":"","sources":["../../src/blocks/appStorageErrors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0LG;AAIH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,GAAE,MAAoC,GAC7C,MAAM,CAER;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iCAAiC,QAAmC,CAAC;AAElF,oEAAoE;AACpE,eAAO,MAAM,oCAAoC,uBAAuB,CAAC;AAEzE,mEAAmE;AACnE,eAAO,MAAM,+BAA+B,2BAA2B,CAAC;AAExE;;;GAGG;AACH,eAAO,MAAM,qCAAqC,oCAAoC,CAAC;AAEvF;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,gCAAgC,2BAA2B,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,eAAO,MAAM,+BAA+B,+JAOlC,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,oBAAoB,GACpB,eAAe,GACf,qBAAqB,GACrB,gBAAgB,GAChB,gBAAgB,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CA4BxF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,MAAM,CAEhF"}