blockprint 0.2.1 → 0.3.0

package/README.md

@@ -58,6 +58,14 @@ Renders a config against a registry. `config` is `unknown` on purpose — the ou
 
 The default fallback renders a warning box in development and `null` in production — a page that wants visible failure in production must pass its own `fallback`.
 
+Fail-soft options:
+
+- `onFallback={(info) => …}` — telemetry hook for entries that fall back (reason, type, props, index). Invoked synchronously so it works in Server Components, and deduped per Renderer instance on `(reason, type, index)` — unstable config identities don't re-fire it. Expect one call per environment (server + hydration) and possible doubling under StrictMode in development.
+- `invalidConfigFallback={<ErrorState />}` — rendered instead of throwing when the outer config shape is invalid. Without it the Renderer throws `ConfigError`, so boundary-less apps fail loudly rather than silently blank.
+- `catchBlockErrors` — wraps each block in an error boundary: a block that throws while rendering becomes a `render-error` fallback instead of taking the page down, and recovers when its entry changes. **Client-side containment only**: React error boundaries do not catch during server rendering and do not exist in Server Components (enabling this there throws a descriptive error); SSR totality remains your blocks' responsibility.
+
+> **Upgrading from ≤ 0.2**: `FallbackProps` gained a third member, `{ reason: "render-error", error }`. Custom fallbacks that narrowed with a two-way ternary must handle it — switch on `reason` exhaustively. See [CHANGELOG](https://github.com/terzidest/blockprint/blob/main/CHANGELOG.md).
+
 The optional `wrapBlock={(node, entry, index) => …}` prop wraps every rendered entry — blocks and fallbacks alike — with access to the config entry and its index. This is the hook point for visual-editing overlays, analytics boundaries, or per-block chrome.
 
 A common recipe — shared section chrome, deep-link anchors, and analytics attributes in one place instead of repeated in every block:
@@ -84,6 +92,58 @@ Rendering and schema validation are memoised per `(config, registry)` identity
 
 The boundary validator, exported for consumers who want to fail at fetch time rather than render time. Throws `ConfigError` with the entry index and reason.
 
+### Manifests — block definitions without components
+
+When more than one app needs to know your blocks (an admin, a server, tests), define them once, component-free, and join components only where rendering happens:
+
+```ts
+// packages/blocks-contract — imports blockprint/config only, no React
+import { defineBlock } from "blockprint/config";
+
+export const hero = defineBlock({
+  schema: heroSchema,                       // required; the manifest's reason to exist
+  label: "Hero",
+  defaults: { title: "A headline…" },       // typed as the schema's INPUT
+  summary: (props) => props.title,          // receives the schema's OUTPUT
+  fields: { title: { label: "Headline" } }, // shallow editor metadata, uninterpreted
+});
+
+export const manifest = { hero, categoryTiles, productStrip };
+```
+
+```tsx
+// the rendering app — the only place components exist
+import { createRegistry } from "blockprint";
+import { manifest } from "@yours/blocks-contract";
+
+const registry = createRegistry(manifest, {
+  hero: Hero,
+  categoryTiles: CategoryTiles,
+  productStrip: ProductStrip,
+});
+```
+
+The join is checked per key: a component requiring a prop its schema doesn't produce, a missing component, or an extra component are all compile errors on the offending key. Editors and servers import the manifest (labels, defaults, summaries, `InputOf`/`OutputOf` types) and never touch component modules.
+
+### `validateConfig(manifest, config)` — headless, total
+
+Per-entry validation for save endpoints, tests, loaders, and editors. **Never throws:**
+
+```ts
+import { validateConfig } from "blockprint/config";
+
+const report = validateConfig(manifest, untrustedInput);
+report.ok;           // outer shape valid and no entry failed validation
+report.error;        // outer-shape failure message, if any
+report.entries;      // per entry: { ok: true, value } | { ok: false, reason, issues? }
+report.unknownTypes; // distinct unregistered types — NOT counted as failure:
+                     // unknown blocks are the renderer's fallback case, and
+                     // whether to accept them is the caller's policy
+report.duplicateIds; // ids appearing more than once
+```
+
+The Renderer applies the same per-entry semantics, so what validates at save time is what renders.
+
 ### `blockprint/config` — the React-free entry point
 
 Backends that store and validate configs want exactly `parseConfig` and nothing React-shaped. The `blockprint/config` subpath exports `parseConfig`, `ConfigError`, and the `BlockConfig` / `StandardSchemaV1` types with **no React requirement** (the React peer dependency is marked optional):

package/dist/Renderer.d.ts

@@ -1,5 +1,8 @@
 import type { ComponentType, ReactNode } from "react";
 import type { BlockConfig, BlocksShape, FallbackProps, Registry } from "./types.js";
+export type FallbackInfo = FallbackProps & {
+    index: number;
+};
 export interface RendererProps<T extends BlocksShape> {
     /** Untrusted input; the outer shape is validated internally. */
     config: unknown;
@@ -11,5 +14,29 @@ export interface RendererProps<T extends BlocksShape> {
      * overlays, analytics boundaries, or per-block chrome.
      */
     wrapBlock?: (node: ReactNode, entry: BlockConfig, index: number) => ReactNode;
+    /**
+     * Telemetry hook for entries that resolve to a fallback (and render errors
+     * caught by catchBlockErrors). Invoked synchronously so it works in Server
+     * Components, and deduped per Renderer instance on (reason, type, index) —
+     * so unstable config identities don't re-fire it. Expect one call per
+     * environment (server render + client hydration), and possible doubling
+     * under StrictMode in development.
+     */
+    onFallback?: (info: FallbackInfo) => void;
+    /**
+     * Rendered instead of throwing when the outer config shape is invalid.
+     * Without it, invalid outer shape throws ConfigError (the default, so
+     * boundary-less apps fail loudly rather than silently blank).
+     */
+    invalidConfigFallback?: ReactNode;
+    /**
+     * Wrap every block in an error boundary: a block that throws while
+     * rendering becomes a `render-error` fallback instead of taking the page
+     * down, and recovers when the entry changes. Client-side containment only —
+     * React error boundaries do not catch during server rendering, and class
+     * boundaries do not exist in Server Components, so enabling this outside a
+     * client environment throws a descriptive error.
+     */
+    catchBlockErrors?: boolean;
 }
-export declare function Renderer<T extends BlocksShape>({ config, registry, fallback, wrapBlock, }: RendererProps<T>): ReactNode;
+export declare function Renderer<T extends BlocksShape>({ config, registry, fallback, wrapBlock, onFallback, invalidConfigFallback, catchBlockErrors, }: RendererProps<T>): ReactNode;

package/dist/Renderer.js

@@ -1,10 +1,16 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Fragment, useMemo } from "react";
-import { parseConfig } from "./parseConfig.js";
+// Namespace import: React.Component must only be touched lazily — the
+// react-server condition's build exports useMemo/Fragment but NOT Component,
+// and the main entry must stay loadable from Server Components.
+import * as React from "react";
+import { parseConfig, ConfigError } from "./parseConfig.js";
+import { validateProps } from "./validateProps.js";
 import { DefaultFallback } from "./fallback.js";
 import { isDev } from "./env.js";
-// StrictMode double-invokes render (and therefore the memo) in development;
-// remember what we've already warned about so each duplicate id logs once.
+// Module-global on purpose: this is a config-authoring diagnostic, not a
+// per-instance signal — a second Renderer repeating the same duplicate id
+// will not re-warn. StrictMode double-invokes are deduped by the same set.
 const warnedDuplicateIds = new Set();
 // `memo`/`forwardRef` components are exotic objects, not functions, so the
 // bare-vs-definition split must discriminate on the `component` key.
@@ -14,7 +20,7 @@ function resolveDef(def) {
     }
     return { component: def };
 }
-function prepare(config, registry) {
+function prepare(config, registry, emitFallback) {
     const entries = parseConfig(config);
     const seenKeys = new Set();
     return entries.map((entry, index) => {
@@ -27,78 +33,118 @@ function prepare(config, registry) {
             key = `${key}__dup${index}`;
         }
         seenKeys.add(key);
+        const toFallback = (fallbackProps) => {
+            emitFallback({ ...fallbackProps, index });
+            return { key, entry, kind: "fallback", fallbackProps };
+        };
         if (!Object.hasOwn(registry.blocks, entry.type)) {
-            return {
-                key,
-                entry,
-                kind: "fallback",
-                fallbackProps: {
-                    reason: "unknown-type",
-                    type: entry.type,
-                    props: entry.props,
-                },
-            };
+            return toFallback({
+                reason: "unknown-type",
+                type: entry.type,
+                props: entry.props,
+            });
         }
         const { component, schema } = resolveDef(registry.blocks[entry.type]);
         if (!schema) {
-            return {
-                key,
-                entry,
-                kind: "block",
-                component,
+            return { key, entry, kind: "block", component, props: entry.props };
+        }
+        const validation = validateProps(schema, entry.props);
+        if (!validation.ok) {
+            return toFallback({
+                reason: "invalid-props",
+                type: entry.type,
                 props: entry.props,
-            };
+                issues: validation.issues,
+            });
         }
-        const result = schema["~standard"].validate(entry.props);
-        // React render is synchronous; async schemas are a config mistake and
-        // are contained like any other invalid block.
-        if (result instanceof Promise) {
-            return {
-                key,
-                entry,
-                kind: "fallback",
-                fallbackProps: {
-                    reason: "invalid-props",
-                    type: entry.type,
-                    props: entry.props,
-                    issues: [
-                        {
-                            message: "schema validated asynchronously; blockprint only supports synchronous schemas",
-                        },
-                    ],
-                },
-            };
+        return { key, entry, kind: "block", component, props: validation.value };
+    });
+}
+let LazyBoundary;
+/**
+ * The boundary class is created on first use so React.Component is never
+ * touched at module load — the react-server build doesn't export it.
+ */
+function getBlockBoundary() {
+    if (LazyBoundary)
+        return LazyBoundary;
+    const Base = React.Component;
+    if (typeof Base !== "function") {
+        throw new Error("blockprint: catchBlockErrors requires a client React environment — error boundaries are not available in Server Components");
+    }
+    class BlockBoundary extends Base {
+        state = { hasError: false };
+        static getDerivedStateFromError(error) {
+            return { hasError: true, error };
         }
-        if (result.issues) {
-            return {
-                key,
-                entry,
-                kind: "fallback",
-                fallbackProps: {
-                    reason: "invalid-props",
-                    type: entry.type,
-                    props: entry.props,
-                    issues: result.issues,
-                },
-            };
+        componentDidCatch(error) {
+            this.props.onError?.(error);
         }
-        return {
-            key,
-            entry,
-            kind: "block",
-            component,
-            props: result.value,
-        };
-    });
+        componentDidUpdate(previous) {
+            if (this.state.hasError && previous.resetKey !== this.props.resetKey) {
+                this.setState({ hasError: false, error: undefined });
+            }
+        }
+        render() {
+            return this.state.hasError
+                ? this.props.renderFallback(this.state.error)
+                : this.props.children;
+        }
+    }
+    LazyBoundary = BlockBoundary;
+    return LazyBoundary;
 }
-export function Renderer({ config, registry, fallback, wrapBlock, }) {
+export function Renderer({ config, registry, fallback, wrapBlock, onFallback, invalidConfigFallback, catchBlockErrors, }) {
     const Fallback = fallback ?? DefaultFallback;
-    // Parsing and schema validation run once per (config, registry) identity,
-    // not on every render; a consumer recreating the config array each render
-    // opts out of the caching, not the correctness.
-    const prepared = useMemo(() => prepare(config, registry), [config, registry]);
-    return prepared.map((item, index) => {
-        const node = item.kind === "block" ? (_jsx(item.component, { ...item.props })) : (_jsx(Fallback, { ...item.fallbackProps }));
+    // Per-instance dedupe for onFallback: unstable config identities (inline
+    // arrays, `x ?? []`) re-run the memo, but telemetry fires at most once per
+    // (reason, type, index) for the life of this Renderer instance.
+    const firedFallbacks = useMemo(() => new Set(), []);
+    // Parsing and schema validation run once per (config, registry) identity.
+    // onFallback is deliberately not a dependency: it is only invoked inside a
+    // recompute, which always closes over the current render's value — listing
+    // it would defeat the memo for inline callbacks.
+    const prepared = useMemo(() => {
+        const emitFallback = (info) => {
+            const dedupeKey = `${info.reason}:${info.type}:${info.index}`;
+            if (firedFallbacks.has(dedupeKey))
+                return;
+            firedFallbacks.add(dedupeKey);
+            onFallback?.(info);
+        };
+        try {
+            return { entries: prepare(config, registry, emitFallback) };
+        }
+        catch (error) {
+            if (error instanceof ConfigError)
+                return { configError: error };
+            throw error;
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [config, registry]);
+    if ("configError" in prepared) {
+        if (invalidConfigFallback !== undefined)
+            return invalidConfigFallback;
+        throw prepared.configError;
+    }
+    const Boundary = catchBlockErrors ? getBlockBoundary() : undefined;
+    return prepared.entries.map((item, index) => {
+        let node = item.kind === "block" ? (_jsx(item.component, { ...item.props })) : (_jsx(Fallback, { ...item.fallbackProps }));
+        if (Boundary && item.kind === "block") {
+            node = (_jsx(Boundary, { resetKey: item.entry, renderFallback: (error) => (_jsx(Fallback, { reason: "render-error", type: item.entry.type, props: item.entry.props, error: error })), onError: (error) => {
+                    const dedupeKey = `render-error:${item.entry.type}:${index}`;
+                    if (firedFallbacks.has(dedupeKey))
+                        return;
+                    firedFallbacks.add(dedupeKey);
+                    onFallback?.({
+                        reason: "render-error",
+                        type: item.entry.type,
+                        props: item.entry.props,
+                        error,
+                        index,
+                    });
+                }, children: node }));
+        }
         // The key lives on a Fragment so it survives whatever wrapBlock returns.
         return (_jsx(Fragment, { children: wrapBlock ? wrapBlock(node, item.entry, index) : node }, item.key));
     });

package/dist/block-config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * React-free config types. Everything reachable from the `blockprint/config`
+ * entry must resolve without React's type definitions installed — keep this
+ * module (and its importers in config land) free of react imports, even
+ * type-only ones.
+ */
+/**
+ * A single entry as it arrives from a CMS. Deliberately open: `type` is any
+ * string, because untrusted configs may contain types the registry has never
+ * seen — those route to the fallback instead of crashing.
+ */
+export interface BlockConfig {
+    type: string;
+    props?: unknown;
+    id?: string | number;
+}

package/dist/block-config.js

@@ -0,0 +1,7 @@
+/**
+ * React-free config types. Everything reachable from the `blockprint/config`
+ * entry must resolve without React's type definitions installed — keep this
+ * module (and its importers in config land) free of react imports, even
+ * type-only ones.
+ */
+export {};

package/dist/config.d.ts

@@ -1,9 +1,13 @@
 /**
- * React-free entry point (`blockprint/config`): the boundary validator and
- * config types, importable from Node backends without a React peer. Keep
- * this module (and its imports) free of React — servers validating stored
- * configs want exactly this and nothing more.
+ * React-free entry point (`blockprint/config`): the boundary validator, the
+ * manifest system, and headless config validation — importable from Node
+ * backends and editor apps without a React peer. Keep this module's import
+ * graph free of React, including type-only imports.
  */
 export { parseConfig, ConfigError } from "./parseConfig.js";
-export type { BlockConfig } from "./types.js";
+export { defineBlock } from "./manifest.js";
+export type { BlockDefinition, FieldMeta, FieldsFor, InputOf, Manifest, OutputOf, } from "./manifest.js";
+export { validateConfig } from "./validateConfig.js";
+export type { ValidatedEntry, ValidationReport } from "./validateConfig.js";
+export type { BlockConfig } from "./block-config.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/config.js

@@ -1,7 +1,9 @@
 /**
- * React-free entry point (`blockprint/config`): the boundary validator and
- * config types, importable from Node backends without a React peer. Keep
- * this module (and its imports) free of React — servers validating stored
- * configs want exactly this and nothing more.
+ * React-free entry point (`blockprint/config`): the boundary validator, the
+ * manifest system, and headless config validation — importable from Node
+ * backends and editor apps without a React peer. Keep this module's import
+ * graph free of React, including type-only imports.
  */
 export { parseConfig, ConfigError } from "./parseConfig.js";
+export { defineBlock } from "./manifest.js";
+export { validateConfig } from "./validateConfig.js";

package/dist/createRegistry.d.ts

@@ -1,6 +1,7 @@
 import type { ComponentType } from "react";
 import type { StandardSchemaV1 } from "./standard-schema.js";
 import type { BlocksShape, Registry } from "./types.js";
+import type { Manifest, OutputOf } from "./manifest.js";
 /**
  * Maps every compatible entry to `unknown` (an identity when intersected) and
  * every entry whose schema output is not assignable to its component's props
@@ -15,4 +16,23 @@ export type ValidateBlocks<T extends BlocksShape> = {
         schema: `schema output is not assignable to props of '${K & string}'`;
     } : unknown;
 };
+/**
+ * One component per manifest key, each able to accept its schema's output.
+ * Contravariance does the per-key checking: a component requiring a prop the
+ * schema doesn't produce fails on that key.
+ */
+export type ComponentsFor<M extends Manifest> = {
+    [K in keyof M]: ComponentType<OutputOf<M[K]>>;
+};
+/** Rejects component keys that have no manifest entry. */
+export type NoExtraComponents<C, M> = {
+    [K in Exclude<keyof C, keyof M>]: never;
+};
+export type JoinedShape<M extends Manifest, C extends ComponentsFor<M>> = {
+    [K in keyof M]: {
+        component: C[K];
+        schema: M[K]["schema"];
+    };
+};
 export declare function createRegistry<T extends BlocksShape>(blocks: T & ValidateBlocks<T>): Registry<T>;
+export declare function createRegistry<M extends Manifest, C extends ComponentsFor<M>>(manifest: M, components: C & NoExtraComponents<C, M>): Registry<JoinedShape<M, C>>;

package/dist/createRegistry.js

@@ -1,3 +1,17 @@
-export function createRegistry(blocks) {
+export function createRegistry(first, components) {
+    if (components === undefined) {
+        return { blocks: first };
+    }
+    const blocks = {};
+    for (const key of Object.keys(first)) {
+        const component = components[key];
+        if (component === undefined) {
+            throw new Error(`createRegistry: no component provided for manifest block '${key}'`);
+        }
+        blocks[key] = {
+            component,
+            schema: first[key].schema,
+        };
+    }
     return { blocks: blocks };
 }

package/dist/env.d.ts

@@ -1,5 +1,7 @@
 /**
  * True outside production builds. Guarded so a browser without a bundler
- * defining `process` gets `false` instead of a ReferenceError.
+ * defining `process` gets `false` instead of a ReferenceError — deliberately
+ * fail-quiet: a bundler-less browser is treated as production (silent
+ * default fallback, no dev warnings).
  */
 export declare function isDev(): boolean;

package/dist/env.js

@@ -1,6 +1,8 @@
 /**
  * True outside production builds. Guarded so a browser without a bundler
- * defining `process` gets `false` instead of a ReferenceError.
+ * defining `process` gets `false` instead of a ReferenceError — deliberately
+ * fail-quiet: a bundler-less browser is treated as production (silent
+ * default fallback, no dev warnings).
  */
 export function isDev() {
     return typeof process !== "undefined" && process.env.NODE_ENV !== "production";

package/dist/fallback.js

@@ -6,7 +6,11 @@ export function DefaultFallback(props) {
     }
     const detail = props.reason === "invalid-props"
         ? props.issues.map((issue) => issue.message).join("; ")
-        : "no component registered for this type";
+        : props.reason === "render-error"
+            ? props.error instanceof Error
+                ? props.error.message
+                : String(props.error)
+            : "no component registered for this type";
     return (_jsxs("div", { role: "note", style: {
             border: "1px dashed #c00",
             borderRadius: 4,

package/dist/index.d.ts

@@ -1,6 +1,11 @@
 export { createRegistry } from "./createRegistry.js";
 export { Renderer } from "./Renderer.js";
-export type { RendererProps } from "./Renderer.js";
+export type { RendererProps, FallbackInfo } from "./Renderer.js";
 export { parseConfig, ConfigError } from "./parseConfig.js";
+export { defineBlock } from "./manifest.js";
+export type { BlockDefinition, FieldMeta, FieldsFor, InputOf, Manifest, OutputOf, } from "./manifest.js";
+export { validateConfig } from "./validateConfig.js";
+export type { ValidatedEntry, ValidationReport } from "./validateConfig.js";
+export type { ComponentsFor, JoinedShape } from "./createRegistry.js";
 export type { BlockConfig, BlockDef, BlocksShape, ConfigFor, FallbackProps, InputFor, PropsFor, Registry, } from "./types.js";
 export type { StandardSchemaV1 } from "./standard-schema.js";

package/dist/index.js

@@ -1,3 +1,5 @@
 export { createRegistry } from "./createRegistry.js";
 export { Renderer } from "./Renderer.js";
 export { parseConfig, ConfigError } from "./parseConfig.js";
+export { defineBlock } from "./manifest.js";
+export { validateConfig } from "./validateConfig.js";

package/dist/manifest.d.ts

@@ -0,0 +1,43 @@
+import type { StandardSchemaV1 } from "./standard-schema.js";
+/**
+ * Editor metadata for one field of a block's input. blockprint stores this
+ * and does not interpret it — form generation decides what the keys mean.
+ * Shallow by design: nested paths are out of scope.
+ */
+export interface FieldMeta {
+    label?: string;
+    help?: string;
+    widget?: string;
+    [key: string]: unknown;
+}
+export type FieldsFor<S extends StandardSchemaV1> = StandardSchemaV1.InferInput<S> extends Record<string, any> ? {
+    [K in keyof StandardSchemaV1.InferInput<S> & string]?: FieldMeta;
+} : never;
+/**
+ * A component-free block definition: everything an admin, a server, or a
+ * test needs to know about a block, importable without the component.
+ */
+export interface BlockDefinition<S extends StandardSchemaV1 = StandardSchemaV1> {
+    readonly schema: S;
+    /** Display name; falls back to the manifest key. */
+    readonly label?: string;
+    /** Starting props for a newly inserted block, in the schema's INPUT shape. */
+    readonly defaults?: StandardSchemaV1.InferInput<S>;
+    /** One-line description of an instance, from the schema's OUTPUT shape. */
+    readonly summary?: (props: StandardSchemaV1.InferOutput<S>) => string;
+    readonly fields?: FieldsFor<S>;
+    /** Reserved for future migration tooling. */
+    readonly version?: number;
+}
+export type Manifest = Record<string, BlockDefinition<any>>;
+/** The rendered/validated props of a definition (schema OUTPUT). */
+export type OutputOf<D extends BlockDefinition<any>> = StandardSchemaV1.InferOutput<D["schema"]>;
+/** The authorable props of a definition (schema INPUT; defaults optional). */
+export type InputOf<D extends BlockDefinition<any>> = StandardSchemaV1.InferInput<D["schema"]>;
+/**
+ * Identity at runtime; the generic captures the schema so defaults check
+ * against the schema's input and summary receives its output.
+ */
+export declare function defineBlock<S extends StandardSchemaV1>(definition: BlockDefinition<S> & {
+    schema: S;
+}): BlockDefinition<S>;

package/dist/manifest.js

@@ -0,0 +1,7 @@
+/**
+ * Identity at runtime; the generic captures the schema so defaults check
+ * against the schema's input and summary receives its output.
+ */
+export function defineBlock(definition) {
+    return definition;
+}

package/dist/parseConfig.d.ts

@@ -1,4 +1,4 @@
-import type { BlockConfig } from "./types.js";
+import type { BlockConfig } from "./block-config.js";
 export declare class ConfigError extends Error {
     constructor(message: string);
 }

package/dist/types.d.ts

@@ -18,16 +18,7 @@ export type PropsOfDef<D> = D extends {
 export interface Registry<T extends BlocksShape> {
     readonly blocks: T;
 }
-/**
- * A single entry as it arrives from a CMS. Deliberately open: `type` is any
- * string, because untrusted configs may contain types the registry has never
- * seen — those route to the fallback instead of crashing.
- */
-export interface BlockConfig {
-    type: string;
-    props?: unknown;
-    id?: string | number;
-}
+export type { BlockConfig } from "./block-config.js";
 /**
  * The props a consumer may author for a definition. With a schema this is the
  * schema's INPUT type — authored configs are pre-validation data, so fields
@@ -69,4 +60,10 @@ export type FallbackProps = {
     type: string;
     props: unknown;
     issues: ReadonlyArray<StandardSchemaV1.Issue>;
+} | {
+    /** A block component threw while rendering (catchBlockErrors only). */
+    reason: "render-error";
+    type: string;
+    props: unknown;
+    error: unknown;
 };

package/dist/validateConfig.d.ts

@@ -0,0 +1,43 @@
+import type { BlockConfig } from "./block-config.js";
+import type { Manifest } from "./manifest.js";
+import type { StandardSchemaV1 } from "./standard-schema.js";
+export type ValidatedEntry = {
+    index: number;
+    entry: BlockConfig;
+    ok: true;
+    value: unknown;
+} | {
+    index: number;
+    entry: BlockConfig;
+    ok: false;
+    reason: "unknown-type";
+} | {
+    index: number;
+    entry: BlockConfig;
+    ok: false;
+    reason: "invalid-props" | "async-schema";
+    issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};
+export interface ValidationReport {
+    /**
+     * Outer shape valid and no entry failed validation. Unknown types do NOT
+     * flip this — they are the renderer's fallback case and whether they are
+     * acceptable is the caller's policy (check `unknownTypes` for strictness).
+     */
+    ok: boolean;
+    /** Outer-shape failure; when present, `entries` is empty. */
+    error?: {
+        message: string;
+    };
+    entries: ValidatedEntry[];
+    /** Distinct types with no manifest entry, in order of first appearance. */
+    unknownTypes: string[];
+    /** Ids appearing more than once, in order of first duplication. */
+    duplicateIds: Array<string | number>;
+}
+/**
+ * Total, headless validation of an untrusted config against a manifest —
+ * never throws. One function for save-time validation, tests, loaders, and
+ * editors; the Renderer applies the same per-entry semantics.
+ */
+export declare function validateConfig(manifest: Manifest, config: unknown): ValidationReport;

package/dist/validateConfig.js

@@ -0,0 +1,53 @@
+import { parseConfig, ConfigError } from "./parseConfig.js";
+import { validateProps } from "./validateProps.js";
+/**
+ * Total, headless validation of an untrusted config against a manifest —
+ * never throws. One function for save-time validation, tests, loaders, and
+ * editors; the Renderer applies the same per-entry semantics.
+ */
+export function validateConfig(manifest, config) {
+    let parsed;
+    try {
+        parsed = parseConfig(config);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: {
+                message: error instanceof ConfigError ? error.message : String(error),
+            },
+            entries: [],
+            unknownTypes: [],
+            duplicateIds: [],
+        };
+    }
+    const unknownTypes = [];
+    const duplicateIds = [];
+    const seenIds = new Set();
+    const entries = parsed.map((entry, index) => {
+        if (entry.id !== undefined) {
+            if (seenIds.has(entry.id) && !duplicateIds.includes(entry.id)) {
+                duplicateIds.push(entry.id);
+            }
+            seenIds.add(entry.id);
+        }
+        if (!Object.hasOwn(manifest, entry.type)) {
+            if (!unknownTypes.includes(entry.type))
+                unknownTypes.push(entry.type);
+            return { index, entry, ok: false, reason: "unknown-type" };
+        }
+        const validation = validateProps(manifest[entry.type].schema, entry.props);
+        if (!validation.ok) {
+            return {
+                index,
+                entry,
+                ok: false,
+                reason: validation.reason,
+                issues: validation.issues,
+            };
+        }
+        return { index, entry, ok: true, value: validation.value };
+    });
+    const ok = entries.every((item) => item.ok || item.reason === "unknown-type");
+    return { ok, entries, unknownTypes, duplicateIds };
+}

package/dist/validateProps.d.ts

@@ -0,0 +1,15 @@
+import type { StandardSchemaV1 } from "./standard-schema.js";
+export type PropsValidation = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    reason: "invalid-props" | "async-schema";
+    issues: ReadonlyArray<StandardSchemaV1.Issue>;
+};
+/**
+ * The single semantics for validating one block's props against its schema,
+ * shared by the Renderer and the headless validateConfig. Synchronous by
+ * contract: an async schema is a config mistake, reported as such.
+ */
+export declare function validateProps(schema: StandardSchemaV1<unknown, any>, props: unknown): PropsValidation;

package/dist/validateProps.js

@@ -0,0 +1,23 @@
+/**
+ * The single semantics for validating one block's props against its schema,
+ * shared by the Renderer and the headless validateConfig. Synchronous by
+ * contract: an async schema is a config mistake, reported as such.
+ */
+export function validateProps(schema, props) {
+    const result = schema["~standard"].validate(props);
+    if (result instanceof Promise) {
+        return {
+            ok: false,
+            reason: "async-schema",
+            issues: [
+                {
+                    message: "schema validated asynchronously; blockprint only supports synchronous schemas",
+                },
+            ],
+        };
+    }
+    if (result.issues) {
+        return { ok: false, reason: "invalid-props", issues: result.issues };
+    }
+    return { ok: true, value: result.value };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockprint",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Typed, config-driven block renderer for React. Render arbitrary UI trees from untrusted JSON with compile-time registry safety and runtime schema validation.",
   "license": "MIT",
   "homepage": "https://blockprint.terzidest.com",