@civitai/app-sdk 0.46.0 → 0.48.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).
 >
@@ -89,7 +98,7 @@ interface BlockInitPayload {
   token: WrappedToken;                 // { raw, scopes[], expiresAt (ISO), buzzBudget? }
   context: BlockContext;               // { slotId, … } — narrow to ModelSlotContext
   settings: BlockSettings;             // { publisherSettings, userSettings }
-  viewer: ViewerInfo | null;           // null = anonymous
+  viewer: ViewerInfo | null;           // null = anonymous — gate with isSignedIn(viewer)
   theme: 'light' | 'dark';
   renderMode: 'iframe' | 'inline';
 }
@@ -103,9 +112,10 @@ 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. |
 | types | `BlockManifestV1`, `ManifestSettings` (+ field types), `BlockContext`, `ModelSlotContext`, `BlockCheckpointInfo`, `ShowcaseImage`, `BlockToken`, `WrappedToken`, `BlockSettings`, `ViewerInfo`, `Theme`, `WorkflowBody`, `BlockTextToImageParams`, `WorkflowBodyCustomComfy` (+ its two arms `WorkflowBodyCustomComfyRecipe` / `WorkflowBodyCustomComfyInline`, and `InlineComfyNode`), `WorkflowBodyStep` / `WorkflowBodyPassThroughStep` (the two arms of `kind: 'step'`), `BlockWorkflowSnapshot`, `WorkflowStatus`, `BlockInitPayload`, `ParentToBlockMessage`, `BlockToParentMessage`. |
 
 `WorkflowBody`'s `customComfy` member is a discriminated union on `mode`, mirroring
@@ -152,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`)
 
@@ -295,6 +341,7 @@ const tokens = await exchangeCode({
   redirectUri: 'https://your-app.com/api/auth/callback/civitai',
   code: codeFromQuery,
   codeVerifier: verifierFromSealedCookie,
+  fallbackScope: scope, // used if the response's `scope` is absent or unreadable
 });
 
 // 3. Store tokens in an encrypted httpOnly cookie
@@ -316,6 +363,46 @@ console.log(`Hi ${me.username}`);
 > explicit `baseUrl` to each call only when targeting a local / self-hosted
 > instance (e.g. a dev auth hub vs a dev main app).
 
+> **`fallbackScope`, and what happens to a `scope` we cannot read.** Civitai's
+> token endpoint returns `scope` as a decimal bitmask in a JSON *string*
+> (`"scope": "114689"` — see the
+> [endpoint reference](https://developer.civitai.com/site/oauth/endpoints)),
+> matching the decimal `scope` `buildAuthorizeUrl` puts on the authorize URL,
+> and that is what `exchangeCode` / `refreshToken` read. Anything that is not a
+> whole number in `[0, 2**31-1]` is **not** used: `Number()` of
+> [RFC 6749 §5.1](https://datatracker.ietf.org/doc/html/rfc6749#section-5.1)'s
+> space-delimited form is `NaN`, and `NaN & anything` is `0`, so `hasScope()`
+> would answer `false` for every scope and tell a user who just consented that
+> they granted nothing. A wrong *type* is rejected on the same grounds:
+> `Number(['65537'])` is `65537` and `Number(true)` is `1` (i.e.
+> `TokenScope.UserRead`), so an un-guarded coercion would invent a
+> valid-looking grant rather than fail. Such a value is replaced by
+> `fallbackScope` and a warning naming the value received — not an exception,
+> which on the token path would turn a degraded-but-working session into a hard
+> login failure.
+>
+> Pass `fallbackScope: REQUESTED_SCOPES` on exchange and
+> `fallbackScope: tokens.scope` on refresh — without it, either case resolves to
+> `0`, and a caller that persists the whole refreshed token blob would lock the
+> user out of features their token still grants. `fallbackScope` must itself be
+> a whole number in `[0, 2**31-1]`; `NaN` (what `Number(stored.scope)` gives you
+> on a half-populated store — and `??` does not catch it), a negative, a
+> fraction or an over-ceiling value is **discarded in favour of `0`** with its
+> own warning, rather than being handed back as the scope.
+>
+> **The two fallback paths are not equally sound.** An **omitted** `scope` is
+> not a fault at all: RFC 6749 §5.1/§6 make it optional *precisely when the
+> grant matches the request*, so the requested scope is the granted scope and
+> `fallbackScope` is exactly right — that path is silent. A **present but
+> unreadable** `scope` carries no such guarantee: the server is describing the
+> grant in terms this SDK cannot read, and it may be a *reduced* grant, so
+> falling back to the requested scope can **over-state** what the user granted.
+> All four starters render `scopesFromBitmask(tokens.scope)` to the user as
+> "Granted scopes", so the over-statement is user-visible. It is a deliberate
+> trade (`0` and a thrown error are both worse here), which is why this path
+> always warns — if you gate anything security-relevant on `tokens.scope`,
+> treat that warning as "re-authenticate", not as noise.
+
 ```ts
 
 // 5. Estimate cost, then submit

package/dist/blocks/appStorageLimits.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The App Storage ceilings the host enforces — **the only RUNTIME or
+ * DOCUMENTATION site in this repository that spells these numbers**.
+ *
+ * Every doc site, the mock host, the live dev host and the starter harnesses
+ * reference these constants. That is the point of the module: seven
+ * hand-copied literals is how the old figures came to agree with each other
+ * and disagree with the host by 25x on bytes and 1000x on rows, with nothing
+ * in any build, test or type-check able to notice.
+ *
+ * 🔴 **"Only site" is a claim about what is ENFORCED, and the enforcement is
+ * much narrower than the repo.** `tests/guards/app-storage-quota-literals.test.mjs`
+ * bans the OLD figures, and pins the derivation at each runtime site, over
+ * exactly this surface:
+ *
+ *   - this file and `messages.ts`, here in `src/blocks/`;
+ *   - `useAppStorage.ts`, `internal/mockHost.ts` and `internal/liveHost.ts` in
+ *     `packages/civitai-blocks-react` — NAMED FILES, not the package: the
+ *     banned numbers are the TRUE ceilings of neighbouring features there
+ *     (the shared-storage app-wide quota, the iframe frame cap, Buzz figures),
+ *     and a value ban over the package failed the build for saying so;
+ *   - all of `starters/examples/kv-storage`;
+ *   - and, in `packages/civitai-blocks-react/README.md`,
+ *     `packages/civitai-app-sdk/README.md` and `starters/examples/README.md`,
+ *     ONLY the App-Storage REGION — sections whose heading names App Storage,
+ *     plus lines that name it themselves. `### useSharedStorage()` in the same
+ *     file is not read.
+ *
+ * It does NOT scan, and the rule does not apply to: the guard itself (it spells
+ * every figure, as test data), `CHANGELOG.md` and `.changeset/*.md` (history,
+ * which must not be rewritten to satisfy a guard), `scripts/`, `tests/`,
+ * `claudedocs/`, the root README, other sections of the READMEs above, or any
+ * other file in any package. If you are re-deriving after a host move, do not
+ * assume those paths are empty — grep them.
+ *
+ * ## Provenance — measured, not assumed
+ *
+ * Read from `civitai/civitai` `main` on **2026-09-19** via `gh api` (not a
+ * local checkout, which can lag), file
+ * `src/server/routers/apps.router.ts`, blob `654f2d6`:
+ *
+ * ```ts
+ * const PER_VALUE_BYTE_CAP = 64 * 1024;          // :172
+ * const USER_QUOTA_BYTES   = 2 * 1024 * 1024;    // :204
+ * const USER_ROW_LIMIT     = 1_000;              // :205
+ * ```
+ *
+ * and the `getQuota` procedure returns `limitBytes: USER_QUOTA_BYTES,
+ * limitRows: USER_ROW_LIMIT` — so these are exactly the numbers a block reads
+ * back from {@link https://github.com/civitai/civitai-app-starters | `useAppStorage().getQuota()`}.
+ *
+ * Re-derive with:
+ *
+ * ```sh
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n 'USER_QUOTA_BYTES\|USER_ROW_LIMIT\|PER_VALUE_BYTE_CAP'
+ * ```
+ *
+ * 🔴 **DO NOT re-derive the numbers from this comment** — re-read the host.
+ * The per-user clamp was sized against a measured distribution (the host's own
+ * comment records: 2026-09-09, largest observed per-user footprint 0.65 MiB
+ * across 49 rows, `2 MiB` chosen for ~3.1x headroom) and is expected to move
+ * again when that distribution does.
+ *
+ * ## Which scope each number describes
+ *
+ * 🔴 **THE NAMESPACE AND THE BUDGET HAVE DIFFERENT SCOPES, and the docs used
+ * to quote one while naming the other.**
+ *
+ * - **Namespace** — rows are keyed `(block_instance_id, user_id, key)`. A key
+ *   written by one block instance is invisible to another. "Per (block
+ *   instance, viewer)" is correct, and unchanged.
+ * - **Budget** — {@link APP_STORAGE_MAX_BYTES} and
+ *   {@link APP_STORAGE_MAX_ROWS} are enforced per **(app, viewer)**: the host
+ *   counter is keyed `(app_block_id, user_id)`, so every block instance of the
+ *   same app draws on ONE budget for that viewer. An app with three instances
+ *   on a viewer's page shares 1,000 rows between them, not 3,000.
+ *
+ * A far larger app-wide umbrella also exists above both. It is deliberately
+ * NOT exported and its value is deliberately not written here: nothing reports
+ * an app's usage against it, so no block can render a meaningful "x of y" for
+ * it, and a constant nobody can act on is an invitation to build a UI that
+ * lies. The per-viewer clamp below is what a block will actually hit — it is
+ * orders of magnitude tighter.
+ */
+/**
+ * Largest single value one `set()` may send, in **wire** bytes
+ * (`JSON.stringify(value)` measured as UTF-8).
+ *
+ * 🔴 This bounds what one call SENDS, not what it STORES. The host checks it
+ * in the wire unit while the byte budget below is enforced in the stored unit,
+ * and they diverge: the host records that the largest value this cap admits
+ * (65,535 wire bytes) stores 2,911,582 bytes — 44x, and on its own past
+ * {@link APP_STORAGE_MAX_BYTES}. So passing this check is not evidence the
+ * write will land.
+ */
+export declare const APP_STORAGE_MAX_VALUE_BYTES: number;
+/**
+ * Total stored bytes one viewer may hold across **all instances of one app**.
+ *
+ * This is the value `getQuota().limitBytes` reports.
+ */
+export declare const APP_STORAGE_MAX_BYTES: number;
+/**
+ * Total rows one viewer may hold across **all instances of one app**.
+ *
+ * This is the value `getQuota().limitRows` reports. It is the ceiling most
+ * likely to surprise: a block caching one small row per item a viewer looks at
+ * reaches it after a thousand items while using ~0.3 MB — well under
+ * {@link APP_STORAGE_MAX_BYTES} — so a byte-only estimate will not predict it.
+ */
+export declare const APP_STORAGE_MAX_ROWS = 1000;
+//# sourceMappingURL=appStorageLimits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"appStorageLimits.d.ts","sourceRoot":"","sources":["../../src/blocks/appStorageLimits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,QAAY,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,QAAkB,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC"}

package/dist/blocks/appStorageLimits.js

@@ -0,0 +1,113 @@
+/**
+ * The App Storage ceilings the host enforces — **the only RUNTIME or
+ * DOCUMENTATION site in this repository that spells these numbers**.
+ *
+ * Every doc site, the mock host, the live dev host and the starter harnesses
+ * reference these constants. That is the point of the module: seven
+ * hand-copied literals is how the old figures came to agree with each other
+ * and disagree with the host by 25x on bytes and 1000x on rows, with nothing
+ * in any build, test or type-check able to notice.
+ *
+ * 🔴 **"Only site" is a claim about what is ENFORCED, and the enforcement is
+ * much narrower than the repo.** `tests/guards/app-storage-quota-literals.test.mjs`
+ * bans the OLD figures, and pins the derivation at each runtime site, over
+ * exactly this surface:
+ *
+ *   - this file and `messages.ts`, here in `src/blocks/`;
+ *   - `useAppStorage.ts`, `internal/mockHost.ts` and `internal/liveHost.ts` in
+ *     `packages/civitai-blocks-react` — NAMED FILES, not the package: the
+ *     banned numbers are the TRUE ceilings of neighbouring features there
+ *     (the shared-storage app-wide quota, the iframe frame cap, Buzz figures),
+ *     and a value ban over the package failed the build for saying so;
+ *   - all of `starters/examples/kv-storage`;
+ *   - and, in `packages/civitai-blocks-react/README.md`,
+ *     `packages/civitai-app-sdk/README.md` and `starters/examples/README.md`,
+ *     ONLY the App-Storage REGION — sections whose heading names App Storage,
+ *     plus lines that name it themselves. `### useSharedStorage()` in the same
+ *     file is not read.
+ *
+ * It does NOT scan, and the rule does not apply to: the guard itself (it spells
+ * every figure, as test data), `CHANGELOG.md` and `.changeset/*.md` (history,
+ * which must not be rewritten to satisfy a guard), `scripts/`, `tests/`,
+ * `claudedocs/`, the root README, other sections of the READMEs above, or any
+ * other file in any package. If you are re-deriving after a host move, do not
+ * assume those paths are empty — grep them.
+ *
+ * ## Provenance — measured, not assumed
+ *
+ * Read from `civitai/civitai` `main` on **2026-09-19** via `gh api` (not a
+ * local checkout, which can lag), file
+ * `src/server/routers/apps.router.ts`, blob `654f2d6`:
+ *
+ * ```ts
+ * const PER_VALUE_BYTE_CAP = 64 * 1024;          // :172
+ * const USER_QUOTA_BYTES   = 2 * 1024 * 1024;    // :204
+ * const USER_ROW_LIMIT     = 1_000;              // :205
+ * ```
+ *
+ * and the `getQuota` procedure returns `limitBytes: USER_QUOTA_BYTES,
+ * limitRows: USER_ROW_LIMIT` — so these are exactly the numbers a block reads
+ * back from {@link https://github.com/civitai/civitai-app-starters | `useAppStorage().getQuota()`}.
+ *
+ * Re-derive with:
+ *
+ * ```sh
+ * gh api repos/civitai/civitai/contents/src/server/routers/apps.router.ts \
+ *   --jq '.content' | base64 -d | grep -n 'USER_QUOTA_BYTES\|USER_ROW_LIMIT\|PER_VALUE_BYTE_CAP'
+ * ```
+ *
+ * 🔴 **DO NOT re-derive the numbers from this comment** — re-read the host.
+ * The per-user clamp was sized against a measured distribution (the host's own
+ * comment records: 2026-09-09, largest observed per-user footprint 0.65 MiB
+ * across 49 rows, `2 MiB` chosen for ~3.1x headroom) and is expected to move
+ * again when that distribution does.
+ *
+ * ## Which scope each number describes
+ *
+ * 🔴 **THE NAMESPACE AND THE BUDGET HAVE DIFFERENT SCOPES, and the docs used
+ * to quote one while naming the other.**
+ *
+ * - **Namespace** — rows are keyed `(block_instance_id, user_id, key)`. A key
+ *   written by one block instance is invisible to another. "Per (block
+ *   instance, viewer)" is correct, and unchanged.
+ * - **Budget** — {@link APP_STORAGE_MAX_BYTES} and
+ *   {@link APP_STORAGE_MAX_ROWS} are enforced per **(app, viewer)**: the host
+ *   counter is keyed `(app_block_id, user_id)`, so every block instance of the
+ *   same app draws on ONE budget for that viewer. An app with three instances
+ *   on a viewer's page shares 1,000 rows between them, not 3,000.
+ *
+ * A far larger app-wide umbrella also exists above both. It is deliberately
+ * NOT exported and its value is deliberately not written here: nothing reports
+ * an app's usage against it, so no block can render a meaningful "x of y" for
+ * it, and a constant nobody can act on is an invitation to build a UI that
+ * lies. The per-viewer clamp below is what a block will actually hit — it is
+ * orders of magnitude tighter.
+ */
+/**
+ * Largest single value one `set()` may send, in **wire** bytes
+ * (`JSON.stringify(value)` measured as UTF-8).
+ *
+ * 🔴 This bounds what one call SENDS, not what it STORES. The host checks it
+ * in the wire unit while the byte budget below is enforced in the stored unit,
+ * and they diverge: the host records that the largest value this cap admits
+ * (65,535 wire bytes) stores 2,911,582 bytes — 44x, and on its own past
+ * {@link APP_STORAGE_MAX_BYTES}. So passing this check is not evidence the
+ * write will land.
+ */
+export const APP_STORAGE_MAX_VALUE_BYTES = 64 * 1024;
+/**
+ * Total stored bytes one viewer may hold across **all instances of one app**.
+ *
+ * This is the value `getQuota().limitBytes` reports.
+ */
+export const APP_STORAGE_MAX_BYTES = 2 * 1024 * 1024;
+/**
+ * Total rows one viewer may hold across **all instances of one app**.
+ *
+ * This is the value `getQuota().limitRows` reports. It is the ceiling most
+ * likely to surprise: a block caching one small row per item a viewer looks at
+ * reaches it after a thousand items while using ~0.3 MB — well under
+ * {@link APP_STORAGE_MAX_BYTES} — so a byte-only estimate will not predict it.
+ */
+export const APP_STORAGE_MAX_ROWS = 1_000;
+//# sourceMappingURL=appStorageLimits.js.map

package/dist/blocks/appStorageLimits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"appStorageLimits.js","sourceRoot":"","sources":["../../src/blocks/appStorageLimits.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,GAAG,IAAI,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAErD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC"}

package/dist/blocks/index.d.ts

@@ -1,20 +1,33 @@
 /**
  * `@civitai/app-sdk/blocks` — framework-agnostic contract for Civitai Apps.
  *
- * This subpath exports the manifest type, scope strings, postMessage protocol,
- * and the `defineBlock` validator. Hooks and transport implementations live in
- * a separate package (see `@civitai/blocks-react`) so this module stays usable
- * from any runtime — Node, browsers, workers — with no React dependency.
+ * This subpath exports the manifest type, scope strings and postMessage
+ * protocol. Hooks and transport implementations live in a separate package (see
+ * `@civitai/blocks-react`) so this module stays usable from any runtime — Node,
+ * browsers, workers — with no React dependency and no runtime dependencies at
+ * all. Build-time manifest validation lives at `@civitai/app-sdk/manifest`
+ * (node-only); see the note on `BlockManifestError` below.
  */
 import '../safe-storage/index.js';
 export { installSafeStorage, createMemoryStorage } from '../safe-storage/index.js';
 export type { SafeStorageInstallResult, SafeStorageName } from '../safe-storage/index.js';
-export { defineBlock, BlockManifestError } from './defineBlock.js';
-export type { DefineBlockConfig } from './defineBlock.js';
+/**
+ * `defineBlock` MOVED to `@civitai/app-sdk/manifest` (a NODE-ONLY subpath) in
+ * the release that closed #330. It now validates by compiling the vendored
+ * canonical schema with Ajv instead of maintaining a hand-written mirror of it,
+ * which needs `node:fs` and a runtime dependency — neither of which belongs on
+ * this browser-facing, zero-dependency surface. Most callers want the Vite
+ * plugin at `@civitai/app-sdk/vite` rather than the function.
+ *
+ * `BlockManifestError` stays exported here, from its own module, so
+ * `instanceof` means the same thing on both subpaths.
+ */
+export { BlockManifestError } from './manifestError.js';
 export { BLOCK_SCOPES, BLOCK_SCOPE_PATTERN, BLOCK_CATEGORIES, BLOCK_TAGLINE_MAX_LENGTH, } from './scopes.js';
 export type { BlockScope, BlockScopeKey, BlockCategory } from './scopes.js';
 export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, effectiveBrowsingCeiling, } from './browsingLevel.js';
 export type { BrowsingLevelKey, BrowsingLevelBit, ColorDomain } from './browsingLevel.js';
+export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
 export { BLOCK_INIT_FRAGMENT_MARKER_KEY, BLOCK_INIT_FRAGMENT_VERSION, BLOCK_INIT_FRAGMENT_KEYS, encodeBlockInitFragment, parseBlockInitFragment, stripBlockInitFragment, } from './initFragment.js';
 export type { BlockInitFragment } from './initFragment.js';
 export { isMessage, BLOCK_TO_PARENT_MESSAGE_TYPES, OTHER_MESSAGE_TYPE_LABEL, boundBlockToParentMessageType, } from './messages.js';
@@ -25,5 +38,11 @@ export type { BlockInitPayload, BlockToParentMessage, BlockToParentMessageType,
  * static shape is a claim the guard is what actually checks.
  */
 export { isModelSlotContext, isPageSlotContext } from './types.js';
-export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestAsset, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
+/**
+ * The sign-in gate, spelled once. Blocks, docs and starters call this instead
+ * of open-coding `viewer !== null` or `viewer?.signedIn === true`; see its doc
+ * in `types.ts` for which of the two it uses and why.
+ */
+export { isSignedIn } from './types.js';
+export type { BlockContext, KnownSlotId, ModelSlotId, PageSlotContext, PageSlotId, UnknownSlotContext, BlockManifest, BlockManifestV1, BlockSettings, BlockToken, ContentRating, ManifestBooleanField, ManifestIframe, ManifestNumberField, ManifestPage, ManifestPreview, ManifestSettingField, ManifestSettings, ManifestStringField, ManifestTarget, ModelSlotContext, SettingScope, SettingWidget, Theme, ViewerInfo, BlockCheckpointInfo, BlockResourceInfo, BlockResourcePickerType, BlockSourceImage, BlockUploadedImageInfo, BlockGenerationSourceImageInfo, BlockPendingImageInfo, BlockImageScanResult, BlockUploadPurpose, BlockTextToImageParams, BlockWorkflowSnapshot, BuzzAccountType, ShowcaseImage, WorkflowBody, WorkflowBodyTextToImage, WorkflowBodyCustomComfy, WorkflowBodyCustomComfyRecipe, WorkflowBodyCustomComfyInline, InlineComfyNode, WorkflowBodyStep, WorkflowBodyPassThroughStep, WorkflowStatus, BlockBuzzTransaction, BlockBuzzAccount, BlockDailyCompensationResource, BlockViewer, BlockWildcardPack, BlockWildcardPackErrorCode, AppWorkflow, AppWorkflowImage, BlockGatedImage, BlockCollectionFollowErrorCode, BlockCollectionFollowResult, BlockPostSource, BlockCreatePostRequest, BlockCreatePostResult, BlockCreatePostHostError, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACnF,YAAY,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE1F,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1F,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EACL,SAAS,EACT,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE,YAAY,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,EACb,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,8BAA8B,EAC9B,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,8BAA8B,EAC9B,WAAW,EACX,iBAAiB,EACjB,0BAA0B,EAC1B,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,8BAA8B,EAC9B,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAQH,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACnF,YAAY,EAAE,wBAAwB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE1F;;;;;;;;;;GAUG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5E,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAE1F,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EACL,SAAS,EACT,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,oBAAoB,EACpB,wBAAwB,EACxB,qBAAqB,EACrB,kBAAkB,EAClB,YAAY,EACZ,2BAA2B,EAC3B,4BAA4B,EAC5B,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,YAAY,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,eAAe,EACf,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,aAAa,EACb,UAAU,EACV,aAAa,EACb,oBAAoB,EACpB,cAAc,EACd,mBAAmB,EACnB,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,KAAK,EACL,UAAU,EACV,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,8BAA8B,EAC9B,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,YAAY,EACZ,uBAAuB,EACvB,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,cAAc,EACd,oBAAoB,EACpB,gBAAgB,EAChB,8BAA8B,EAC9B,WAAW,EACX,iBAAiB,EACjB,0BAA0B,EAC1B,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,8BAA8B,EAC9B,2BAA2B,EAC3B,eAAe,EACf,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,YAAY,CAAC"}

package/dist/blocks/index.js

@@ -1,10 +1,12 @@
 /**
  * `@civitai/app-sdk/blocks` — framework-agnostic contract for Civitai Apps.
  *
- * This subpath exports the manifest type, scope strings, postMessage protocol,
- * and the `defineBlock` validator. Hooks and transport implementations live in
- * a separate package (see `@civitai/blocks-react`) so this module stays usable
- * from any runtime — Node, browsers, workers — with no React dependency.
+ * This subpath exports the manifest type, scope strings and postMessage
+ * protocol. Hooks and transport implementations live in a separate package (see
+ * `@civitai/blocks-react`) so this module stays usable from any runtime — Node,
+ * browsers, workers — with no React dependency and no runtime dependencies at
+ * all. Build-time manifest validation lives at `@civitai/app-sdk/manifest`
+ * (node-only); see the note on `BlockManifestError` below.
  */
 // FIRST import, on purpose. Blocks are framed at an opaque origin (sandbox
 // without `allow-same-origin`), where touching `localStorage`/`sessionStorage`
@@ -14,9 +16,21 @@
 // or is absent (Node/SSR/workers); see `../safe-storage/index.ts`.
 import '../safe-storage/index.js';
 export { installSafeStorage, createMemoryStorage } from '../safe-storage/index.js';
-export { defineBlock, BlockManifestError } from './defineBlock.js';
+/**
+ * `defineBlock` MOVED to `@civitai/app-sdk/manifest` (a NODE-ONLY subpath) in
+ * the release that closed #330. It now validates by compiling the vendored
+ * canonical schema with Ajv instead of maintaining a hand-written mirror of it,
+ * which needs `node:fs` and a runtime dependency — neither of which belongs on
+ * this browser-facing, zero-dependency surface. Most callers want the Vite
+ * plugin at `@civitai/app-sdk/vite` rather than the function.
+ *
+ * `BlockManifestError` stays exported here, from its own module, so
+ * `instanceof` means the same thing on both subpaths.
+ */
+export { BlockManifestError } from './manifestError.js';
 export { BLOCK_SCOPES, BLOCK_SCOPE_PATTERN, BLOCK_CATEGORIES, BLOCK_TAGLINE_MAX_LENGTH, } from './scopes.js';
 export { BrowsingLevel, SFW_LEVELS, NSFW_LEVELS, isSfwCeiling, isLevelAllowed, effectiveBrowsingCeiling, } from './browsingLevel.js';
+export { APP_STORAGE_MAX_VALUE_BYTES, APP_STORAGE_MAX_BYTES, APP_STORAGE_MAX_ROWS, } from './appStorageLimits.js';
 export { BLOCK_INIT_FRAGMENT_MARKER_KEY, BLOCK_INIT_FRAGMENT_VERSION, BLOCK_INIT_FRAGMENT_KEYS, encodeBlockInitFragment, parseBlockInitFragment, stripBlockInitFragment, } from './initFragment.js';
 export { isMessage, BLOCK_TO_PARENT_MESSAGE_TYPES, OTHER_MESSAGE_TYPE_LABEL, boundBlockToParentMessageType, } from './messages.js';
 /**
@@ -25,4 +39,10 @@ export { isMessage, BLOCK_TO_PARENT_MESSAGE_TYPES, OTHER_MESSAGE_TYPE_LABEL, bou
  * static shape is a claim the guard is what actually checks.
  */
 export { isModelSlotContext, isPageSlotContext } from './types.js';
+/**
+ * The sign-in gate, spelled once. Blocks, docs and starters call this instead
+ * of open-coding `viewer !== null` or `viewer?.signedIn === true`; see its doc
+ * in `types.ts` for which of the two it uses and why.
+ */
+export { isSignedIn } from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/blocks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,mEAAmE;AACnE,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGnF,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAGnE,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AAiBvB;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/blocks/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,2EAA2E;AAC3E,+EAA+E;AAC/E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,mEAAmE;AACnE,OAAO,0BAA0B,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAGnF;;;;;;;;;;GAUG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,cAAc,EACd,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,SAAS,EACT,6BAA6B,EAC7B,wBAAwB,EACxB,6BAA6B,GAC9B,MAAM,eAAe,CAAC;AAiBvB;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEnE;;;;GAIG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}

package/dist/blocks/manifestError.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The manifest-validation error type, in its own zero-dependency module.
+ *
+ * It lives here rather than beside `defineBlock` because `defineBlock` now
+ * lives at the node-only `@civitai/app-sdk/manifest` subpath (it reads the
+ * vendored canonical schema off disk and compiles it with Ajv). The error class
+ * has to stay importable from the browser-safe `./blocks` surface so that
+ * `instanceof BlockManifestError` means the same thing on both sides — one
+ * class, one module, no duplicate identity.
+ */
+/** Thrown by `defineBlock` for any manifest violation. */
+export declare class BlockManifestError extends Error {
+    /** Dot-path to the offending field, e.g. `iframe.sandbox`. */
+    readonly field?: string | undefined;
+    readonly name = "BlockManifestError";
+    constructor(message: string, 
+    /** Dot-path to the offending field, e.g. `iframe.sandbox`. */
+    field?: string | undefined);
+}
+//# sourceMappingURL=manifestError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifestError.d.ts","sourceRoot":"","sources":["../../src/blocks/manifestError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0DAA0D;AAC1D,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,8DAA8D;IAC9D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM;IAJzB,SAAkB,IAAI,wBAAwB;gBAE5C,OAAO,EAAE,MAAM;IACf,8DAA8D;IACrD,KAAK,CAAC,EAAE,MAAM,YAAA;CAI1B"}

package/dist/blocks/manifestError.js

@@ -0,0 +1,22 @@
+/**
+ * The manifest-validation error type, in its own zero-dependency module.
+ *
+ * It lives here rather than beside `defineBlock` because `defineBlock` now
+ * lives at the node-only `@civitai/app-sdk/manifest` subpath (it reads the
+ * vendored canonical schema off disk and compiles it with Ajv). The error class
+ * has to stay importable from the browser-safe `./blocks` surface so that
+ * `instanceof BlockManifestError` means the same thing on both sides — one
+ * class, one module, no duplicate identity.
+ */
+/** Thrown by `defineBlock` for any manifest violation. */
+export class BlockManifestError extends Error {
+    field;
+    name = 'BlockManifestError';
+    constructor(message, 
+    /** Dot-path to the offending field, e.g. `iframe.sandbox`. */
+    field) {
+        super(message);
+        this.field = field;
+    }
+}
+//# sourceMappingURL=manifestError.js.map