@civitai/app-sdk 0.75.0 → 0.76.0

package/README.md

@@ -32,7 +32,7 @@ pnpm add @civitai/app-sdk
 | `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/*` — `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). |
+| `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. On the dev server only, it also exposes the manifest's `scopes` + `storage` to `@civitai/sdk` for a dev-tunnel local preview. Optional peers: `ajv` (runtime) and `vite` (types only). |
 
 ## Entry points, and what the root barrel is
 
@@ -407,6 +407,15 @@ import { blockManifestPlugin } from '@civitai/app-sdk/vite';
 const plugins = [blockManifestPlugin()];
 ```
 
+**On the dev server only**, the plugin also puts the manifest's `scopes` and
+`storage` on the page (a `<script>` at the end of `index.html`'s `<head>`; `vite build` never
+emits it). `@civitai/sdk` reads it in a dev-tunnel preview, where the host marks the
+frame `storageMode: 'local-preview'` and `app.storage.collection(name)` is served by
+an in-memory store that enforces these declarations — see "In a dev-tunnel preview"
+in `@civitai/sdk`'s README. Nothing else of the manifest is exposed. Without the
+plugin, a preview's document store refuses every call `local_preview_no_manifest`:
+this plugin is the only way the manifest reaches `@civitai/sdk`.
+
 ### Web storage in a block (`@civitai/app-sdk/safe-storage`)
 
 Block iframes are sandboxed **without `allow-same-origin`**, so the document has

package/dist/blocks/messages.d.ts

@@ -218,6 +218,21 @@ export interface BlockInitPayload {
      * them — ship without React.
      */
     effectiveBrowsingLevel?: number;
+    /**
+     * `'local-preview'` when the host mounted this frame as a DEV-TUNNEL preview,
+     * which has no server-side storage namespace. The host sets it from the
+     * surface it mounted — never from the token's scopes, and never from anything
+     * the block sent. Absent on every other surface.
+     *
+     * `@civitai/sdk`'s `initialize()` reads it once and serves
+     * `app.storage.collection(name)` from an in-memory store in the tab
+     * (`app.storage.mode === 'local-preview'`). Nothing in this package or in
+     * `@civitai/blocks-react` acts on it: their storage hooks keep the real routes.
+     *
+     * ADDITIVE + OPTIONAL. A host that predates it omits the field; a value other
+     * than the exact string must be treated as absent.
+     */
+    storageMode?: 'local-preview';
 }
 /**
  * The freeform value carried by one SHARED-storage entry. Unlike the per-user

package/dist/vite/index.d.ts

@@ -1,4 +1,5 @@
 import type { Plugin } from 'vite';
+import type { BlockManifest } from '../blocks/types.js';
 export interface BlockManifestPluginOptions {
     /**
      * Path to the manifest. Relative paths resolve against `root`, which defaults
@@ -9,6 +10,34 @@ export interface BlockManifestPluginOptions {
     /** Overrides the Vite project root used to resolve a relative `manifestPath`. */
     root?: string;
 }
+/**
+ * The global the dev server's HTML sets for `@civitai/sdk` to read. Spelled again
+ * in `packages/civitai-sdk/src/doc-store/local-preview.ts` (the two packages share
+ * no code); `tests/guards/local-preview-manifest-global.test.mjs` pins the two equal.
+ *
+ * WHY A GLOBAL, set by a `<script>` the plugin adds to `index.html`, rather than
+ * the alternatives:
+ * - a VIRTUAL MODULE needs `@civitai/sdk` to import it, which fails to resolve in
+ *   every bundle not built by this plugin — production included;
+ * - a `define` substitution has to reach `@civitai/sdk` inside `node_modules`,
+ *   where it depends on how the dependency optimizer pre-bundles it, and it would
+ *   rewrite production builds too;
+ * - an `initialize()` option needs every app to import its manifest and pass it,
+ *   and would be public API.
+ * The `<script>` is added on the DEV SERVER only (`vite build` never emits it),
+ * needs no change in an app that registers this plugin, and the SDK reads it only
+ * when the host marks the frame a local preview. It is the ONLY way the manifest
+ * reaches the SDK, so an app that does NOT register the plugin gets the SDK's
+ * `local_preview_no_manifest` error. Every scaffold in this repo that ships a
+ * manifest registers it; not every scaffold elsewhere does (the CLI's
+ * `page-money` template, for one, does not), and those apps must add it.
+ */
+export declare const LOCAL_PREVIEW_MANIFEST_GLOBAL = "__CIVITAI_LOCAL_PREVIEW_MANIFEST__";
+/**
+ * The classic `<script>` body: only `scopes` and `storage`, as JSON with `<`
+ * escaped so no value can close the element.
+ */
+export declare function localPreviewManifestScript(manifest: Pick<BlockManifest, 'scopes' | 'storage'>): string;
 export declare function blockManifestPlugin(options?: BlockManifestPluginOptions): Plugin;
 export { BlockManifestError } from '../blocks/manifestError.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/vite/index.js

@@ -18,6 +18,13 @@
  * pre-check against the same canonical). It exists so a manifest mistake
  * surfaces in the dev loop rather than at submit time.
  *
+ * DEV SERVER ONLY, it also hands the manifest's `scopes` and `storage` to
+ * `@civitai/sdk`, for a dev-tunnel preview. A preview has no server-side storage,
+ * so when the host marks the frame `storageMode: 'local-preview'` the SDK serves
+ * `app.storage.collection(name)` from an in-memory store that enforces THESE
+ * declarations — the ones of the code being previewed, which the server has
+ * never seen. See {@link LOCAL_PREVIEW_MANIFEST_GLOBAL} for why it is a global.
+ *
  * PEERS: `ajv` (used at runtime by `@civitai/app-sdk/manifest`) and `vite`
  * (types only). Both are optional peers of `@civitai/app-sdk`; a scaffold using
  * this plugin needs both in its devDependencies.
@@ -25,7 +32,60 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { BlockManifestError, defineBlock } from '../manifest/index.js';
+/**
+ * The global the dev server's HTML sets for `@civitai/sdk` to read. Spelled again
+ * in `packages/civitai-sdk/src/doc-store/local-preview.ts` (the two packages share
+ * no code); `tests/guards/local-preview-manifest-global.test.mjs` pins the two equal.
+ *
+ * WHY A GLOBAL, set by a `<script>` the plugin adds to `index.html`, rather than
+ * the alternatives:
+ * - a VIRTUAL MODULE needs `@civitai/sdk` to import it, which fails to resolve in
+ *   every bundle not built by this plugin — production included;
+ * - a `define` substitution has to reach `@civitai/sdk` inside `node_modules`,
+ *   where it depends on how the dependency optimizer pre-bundles it, and it would
+ *   rewrite production builds too;
+ * - an `initialize()` option needs every app to import its manifest and pass it,
+ *   and would be public API.
+ * The `<script>` is added on the DEV SERVER only (`vite build` never emits it),
+ * needs no change in an app that registers this plugin, and the SDK reads it only
+ * when the host marks the frame a local preview. It is the ONLY way the manifest
+ * reaches the SDK, so an app that does NOT register the plugin gets the SDK's
+ * `local_preview_no_manifest` error. Every scaffold in this repo that ships a
+ * manifest registers it; not every scaffold elsewhere does (the CLI's
+ * `page-money` template, for one, does not), and those apps must add it.
+ */
+export const LOCAL_PREVIEW_MANIFEST_GLOBAL = '__CIVITAI_LOCAL_PREVIEW_MANIFEST__';
+/** Reads and validates the manifest, throwing the message Vite should print. */
+function loadManifest(manifestPath) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`block.manifest.json could not be read or parsed (${manifestPath}): ${err.message}`);
+    }
+    try {
+        defineBlock({ manifest });
+    }
+    catch (err) {
+        // Re-thrown with the field path up front: Vite prints the message, not
+        // the error's own properties, so `.field` would otherwise be invisible.
+        const field = err instanceof BlockManifestError && err.field ? ` [${err.field}]` : '';
+        throw new Error(`block.manifest.json is invalid${field}: ${err.message}`);
+    }
+    return manifest;
+}
+/**
+ * The classic `<script>` body: only `scopes` and `storage`, as JSON with `<`
+ * escaped so no value can close the element.
+ */
+export function localPreviewManifestScript(manifest) {
+    const exposed = JSON.stringify({ scopes: manifest.scopes, storage: manifest.storage }).replace(/</g, '\\u003c');
+    return `globalThis[${JSON.stringify(LOCAL_PREVIEW_MANIFEST_GLOBAL)}] = ${exposed};`;
+}
 export function blockManifestPlugin(options = {}) {
+    let manifestPath = '';
+    let serving = false;
     return {
         name: 'civitai-block-manifest',
         // `enforce: 'pre'` so the manifest error is the FIRST thing reported rather
@@ -36,23 +96,27 @@ export function blockManifestPlugin(options = {}) {
             // this module's own location — this file now lives inside the installed
             // package, not next to the consumer's manifest.
             const root = options.root ?? config?.root ?? process.cwd();
-            const manifestPath = resolve(root, options.manifestPath ?? './block.manifest.json');
-            let manifest;
-            try {
-                manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
-            }
-            catch (err) {
-                throw new Error(`block.manifest.json could not be read or parsed (${manifestPath}): ${err.message}`);
-            }
-            try {
-                defineBlock({ manifest });
-            }
-            catch (err) {
-                // Re-thrown with the field path up front: Vite prints the message, not
-                // the error's own properties, so `.field` would otherwise be invisible.
-                const field = err instanceof BlockManifestError && err.field ? ` [${err.field}]` : '';
-                throw new Error(`block.manifest.json is invalid${field}: ${err.message}`);
-            }
+            manifestPath = resolve(root, options.manifestPath ?? './block.manifest.json');
+            serving = config?.command === 'serve';
+            loadManifest(manifestPath);
+        },
+        transformIndexHtml() {
+            // Dev server only: a build never carries the manifest into the page.
+            if (!serving)
+                return undefined;
+            // Re-read per page load, so an edited manifest takes effect on reload.
+            const manifest = loadManifest(manifestPath);
+            return [
+                {
+                    tag: 'script',
+                    // End of <head>, NOT `head-prepend`: prepended, a large `storage` block
+                    // could push `<meta charset>` past the 1024-byte prescan. Nothing needs
+                    // it earlier: the SDK reads the global inside `initialize()`, after
+                    // BLOCK_INIT, and a classic script still runs before any module script.
+                    injectTo: 'head',
+                    children: localPreviewManifestScript(manifest),
+                },
+            ];
         },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@civitai/app-sdk",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "OAuth + PKCE, encrypted-cookie sessions, scopes, and orchestrator helpers for building third-party Civitai apps.",
   "license": "MIT",
   "type": "module",