blockprint 0.2.0 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@
 
 **Live demo: [blockprint.terzidest.com](https://blockprint.terzidest.com)** — three completely different pages (commerce, SaaS, editorial) from one renderer and one registry, plus a deliberately broken config showing graceful fallback. · [GitHub](https://github.com/terzidest/blockprint)
 
+In production at [ethereal_nature](https://github.com/terzidest/ethereal_nature): storefront pages from DB-stored configs, an admin page editor, and server-side validation via `blockprint/config`.
+
 ## The problem
 
 Content teams compose pages from a fixed set of block types; your app receives JSON like `[{ "type": "hero", "props": { … } }, …]`. Consuming that in React usually collapses into a `switch` on `block.type` — every block imported into every page, props typed `any`, unknown types crashing the page.
@@ -56,12 +58,92 @@ 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:
+
+```tsx
+<Renderer
+  config={config}
+  registry={registry}
+  wrapBlock={(node, entry) => (
+    <section
+      id={entry.id != null ? String(entry.id) : undefined} // anchor: /page#hero-1
+      data-block={entry.type}                        // analytics / e2e hooks
+      className="mx-auto max-w-5xl px-6 py-10"
+    >
+      {node}
+    </section>
+  )}
+/>
+```
+
+Rendering and schema validation are memoised per `(config, registry)` identity — keep the config referentially stable across renders (state, loader data, `useMemo`) to benefit. Duplicate `id`s warn in development and render under collision-safe keys.
+
 ### `parseConfig(input)`
 
 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.ts";
+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,7 +1,17 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { Fragment } from "react";
-import { parseConfig } from "./parseConfig.js";
+import { Fragment, useMemo } from "react";
+// 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";
+// 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.
 function resolveDef(def) {
@@ -10,37 +20,132 @@ function resolveDef(def) {
     }
     return { component: def };
 }
-export function Renderer({ config, registry, fallback, wrapBlock, }) {
-    const Fallback = fallback ?? DefaultFallback;
+function prepare(config, registry, emitFallback) {
     const entries = parseConfig(config);
+    const seenKeys = new Set();
     return entries.map((entry, index) => {
-        const key = entry.id ?? `${entry.type}-${index}`;
-        const node = renderEntry(entry, registry, Fallback);
-        // The key lives on a Fragment so it survives whatever wrapBlock returns.
-        return (_jsx(Fragment, { children: wrapBlock ? wrapBlock(node, entry, index) : node }, key));
+        let key = entry.id ?? `${entry.type}-${index}`;
+        if (seenKeys.has(key)) {
+            if (isDev() && !warnedDuplicateIds.has(key)) {
+                warnedDuplicateIds.add(key);
+                console.warn(`blockprint: duplicate block id "${key}" at config[${index}]; ids should be unique per config`);
+            }
+            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 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, 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,
+            });
+        }
+        return { key, entry, kind: "block", component, props: validation.value };
     });
 }
-function renderEntry(entry, registry, Fallback) {
-    if (!Object.hasOwn(registry.blocks, entry.type)) {
-        return (_jsx(Fallback, { reason: "unknown-type", type: entry.type, props: entry.props }));
+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 };
+        }
+        componentDidCatch(error) {
+            this.props.onError?.(error);
+        }
+        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;
+        }
     }
-    const { component: Component, schema } = resolveDef(registry.blocks[entry.type]);
-    let props = entry.props;
-    if (schema) {
-        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 (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: [
-                    {
-                        message: "schema validated asynchronously; blockprint only supports synchronous schemas",
-                    },
-                ] }));
-        }
-        if (result.issues) {
-            return (_jsx(Fallback, { reason: "invalid-props", type: entry.type, props: entry.props, issues: result.issues }));
-        }
-        props = result.value;
+    LazyBoundary = BlockBoundary;
+    return LazyBoundary;
+}
+export function Renderer({ config, registry, fallback, wrapBlock, onFallback, invalidConfigFallback, catchBlockErrors, }) {
+    const Fallback = fallback ?? DefaultFallback;
+    // 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;
     }
-    return _jsx(Component, { ...props });
+    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.ts";
-export type { BlockConfig } from "./types.ts";
-export type { StandardSchemaV1 } from "./standard-schema.ts";
+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 { 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.ts";
-import type { BlocksShape, Registry } from "./types.ts";
+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

@@ -0,0 +1,7 @@
+/**
+ * True outside production builds. Guarded so a browser without a bundler
+ * 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

@@ -0,0 +1,9 @@
+/**
+ * True outside production builds. Guarded so a browser without a bundler
+ * 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.d.ts

@@ -1,2 +1,2 @@
-import type { FallbackProps } from "./types.ts";
+import type { FallbackProps } from "./types.js";
 export declare function DefaultFallback(props: FallbackProps): import("react").JSX.Element | null;

package/dist/fallback.js

@@ -1,11 +1,16 @@
 import { jsxs as _jsxs } from "react/jsx-runtime";
+import { isDev } from "./env.js";
 export function DefaultFallback(props) {
-    if (process.env.NODE_ENV === "production") {
+    if (!isDev()) {
         return null;
     }
     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.ts";
-export { Renderer } from "./Renderer.tsx";
-export type { RendererProps } from "./Renderer.tsx";
-export { parseConfig, ConfigError } from "./parseConfig.ts";
-export type { BlockConfig, BlockDef, BlocksShape, ConfigFor, FallbackProps, InputFor, PropsFor, Registry, } from "./types.ts";
-export type { StandardSchemaV1 } from "./standard-schema.ts";
+export { createRegistry } from "./createRegistry.js";
+export { Renderer } 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.ts";
+import type { BlockConfig } from "./block-config.js";
 export declare class ConfigError extends Error {
     constructor(message: string);
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentType } from "react";
-import type { StandardSchemaV1 } from "./standard-schema.ts";
+import type { StandardSchemaV1 } from "./standard-schema.js";
 export type AnyComponent = ComponentType<any>;
 export type BlockDef = AnyComponent | {
     component: AnyComponent;
@@ -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.0",
+  "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",
@@ -43,6 +43,7 @@
   "devDependencies": {
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.1.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "typescript": "^7.0.2",
@@ -55,7 +56,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "node -e \"fs.rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node scripts/fix-dts.mjs",
     "typecheck": "tsc",
     "test": "vitest run"
   }

package/dist/chunk-4JB5QQUK.js

@@ -1,37 +0,0 @@
-// src/parseConfig.ts
-var ConfigError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "ConfigError";
-  }
-};
-function parseConfig(input) {
-  if (!Array.isArray(input)) {
-    throw new ConfigError(
-      `config must be an array, received ${input === null ? "null" : typeof input}`
-    );
-  }
-  return input.map((entry, index) => {
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-      throw new ConfigError(`config[${index}] must be an object`);
-    }
-    const { type, props, id } = entry;
-    if (typeof type !== "string" || type.length === 0) {
-      throw new ConfigError(
-        `config[${index}].type must be a non-empty string`
-      );
-    }
-    if (id !== void 0 && typeof id !== "string" && typeof id !== "number") {
-      throw new ConfigError(
-        `config[${index}].id must be a string or number when present`
-      );
-    }
-    return id === void 0 ? { type, props } : { type, props, id };
-  });
-}
-
-export {
-  ConfigError,
-  parseConfig
-};
-//# sourceMappingURL=chunk-4JB5QQUK.js.map

package/dist/chunk-4JB5QQUK.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/parseConfig.ts"],"sourcesContent":["import type { BlockConfig } from \"./types\";\n\nexport class ConfigError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ConfigError\";\n  }\n}\n\n/**\n * The single boundary where untrusted input becomes a typed config. Validates\n * the outer shape only; per-block props are validated against their registered\n * schema at render time.\n */\nexport function parseConfig(input: unknown): BlockConfig[] {\n  if (!Array.isArray(input)) {\n    throw new ConfigError(\n      `config must be an array, received ${input === null ? \"null\" : typeof input}`,\n    );\n  }\n\n  return input.map((entry, index) => {\n    if (typeof entry !== \"object\" || entry === null || Array.isArray(entry)) {\n      throw new ConfigError(`config[${index}] must be an object`);\n    }\n    const { type, props, id } = entry as Record<string, unknown>;\n    if (typeof type !== \"string\" || type.length === 0) {\n      throw new ConfigError(\n        `config[${index}].type must be a non-empty string`,\n      );\n    }\n    if (id !== undefined && typeof id !== \"string\" && typeof id !== \"number\") {\n      throw new ConfigError(\n        `config[${index}].id must be a string or number when present`,\n      );\n    }\n    return id === undefined ? { type, props } : { type, props, id };\n  });\n}\n"],"mappings":";AAEO,IAAM,cAAN,cAA0B,MAAM;AAAA,EACrC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAOO,SAAS,YAAY,OAA+B;AACzD,MAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;AACzB,UAAM,IAAI;AAAA,MACR,qCAAqC,UAAU,OAAO,SAAS,OAAO,KAAK;AAAA,IAC7E;AAAA,EACF;AAEA,SAAO,MAAM,IAAI,CAAC,OAAO,UAAU;AACjC,QAAI,OAAO,UAAU,YAAY,UAAU,QAAQ,MAAM,QAAQ,KAAK,GAAG;AACvE,YAAM,IAAI,YAAY,UAAU,KAAK,qBAAqB;AAAA,IAC5D;AACA,UAAM,EAAE,MAAM,OAAO,GAAG,IAAI;AAC5B,QAAI,OAAO,SAAS,YAAY,KAAK,WAAW,GAAG;AACjD,YAAM,IAAI;AAAA,QACR,UAAU,KAAK;AAAA,MACjB;AAAA,IACF;AACA,QAAI,OAAO,UAAa,OAAO,OAAO,YAAY,OAAO,OAAO,UAAU;AACxE,YAAM,IAAI;AAAA,QACR,UAAU,KAAK;AAAA,MACjB;AAAA,IACF;AACA,WAAO,OAAO,SAAY,EAAE,MAAM,MAAM,IAAI,EAAE,MAAM,OAAO,GAAG;AAAA,EAChE,CAAC;AACH;","names":[]}

package/dist/config.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/createRegistry.ts","../src/Renderer.tsx","../src/fallback.tsx"],"sourcesContent":["import type { ComponentType } from \"react\";\nimport type { StandardSchemaV1 } from \"./standard-schema\";\nimport type { BlocksShape, Registry } from \"./types\";\n\n/**\n * Maps every compatible entry to `unknown` (an identity when intersected) and\n * every entry whose schema output is not assignable to its component's props\n * to an impossible shape — so the type error lands on the offending key with\n * a message naming it.\n */\nexport type ValidateBlocks<T extends BlocksShape> = {\n  [K in keyof T]: T[K] extends {\n    component: ComponentType<infer P>;\n    schema: StandardSchemaV1<unknown, infer S>;\n  }\n    ? [S] extends [P]\n      ? unknown\n      : {\n          schema: `schema output is not assignable to props of '${K & string}'`;\n        }\n    : unknown;\n};\n\nexport function createRegistry<T extends BlocksShape>(\n  blocks: T & ValidateBlocks<T>,\n): Registry<T> {\n  return { blocks: blocks as T };\n}\n","import { Fragment } from \"react\";\nimport type { ComponentType, ReactNode } from \"react\";\nimport type { StandardSchemaV1 } from \"./standard-schema\";\nimport type {\n  AnyComponent,\n  BlockConfig,\n  BlocksShape,\n  FallbackProps,\n  Registry,\n} from \"./types\";\nimport { parseConfig } from \"./parseConfig\";\nimport { DefaultFallback } from \"./fallback\";\n\nexport interface RendererProps<T extends BlocksShape> {\n  /** Untrusted input; the outer shape is validated internally. */\n  config: unknown;\n  registry: Registry<T>;\n  fallback?: ComponentType<FallbackProps>;\n  /**\n   * Wraps every rendered entry — blocks and fallbacks alike — with access to\n   * the config entry and its index. The hook point for visual-editing\n   * overlays, analytics boundaries, or per-block chrome.\n   */\n  wrapBlock?: (node: ReactNode, entry: BlockConfig, index: number) => ReactNode;\n}\n\ninterface ResolvedDef {\n  component: AnyComponent;\n  schema?: StandardSchemaV1<unknown, any>;\n}\n\n// `memo`/`forwardRef` components are exotic objects, not functions, so the\n// bare-vs-definition split must discriminate on the `component` key.\nfunction resolveDef(def: BlocksShape[string]): ResolvedDef {\n  if (typeof def === \"object\" && def !== null && \"component\" in def) {\n    return def;\n  }\n  return { component: def };\n}\n\nexport function Renderer<T extends BlocksShape>({\n  config,\n  registry,\n  fallback,\n  wrapBlock,\n}: RendererProps<T>): ReactNode {\n  const Fallback = fallback ?? DefaultFallback;\n  const entries = parseConfig(config);\n\n  return entries.map((entry, index) => {\n    const key = entry.id ?? `${entry.type}-${index}`;\n    const node = renderEntry(entry, registry, Fallback);\n    // The key lives on a Fragment so it survives whatever wrapBlock returns.\n    return (\n      <Fragment key={key}>\n        {wrapBlock ? wrapBlock(node, entry, index) : node}\n      </Fragment>\n    );\n  });\n}\n\nfunction renderEntry(\n  entry: BlockConfig,\n  registry: Registry<BlocksShape>,\n  Fallback: ComponentType<FallbackProps>,\n): ReactNode {\n  if (!Object.hasOwn(registry.blocks, entry.type)) {\n    return (\n      <Fallback reason=\"unknown-type\" type={entry.type} props={entry.props} />\n    );\n  }\n\n  const { component: Component, schema } = resolveDef(\n    registry.blocks[entry.type] as BlocksShape[string],\n  );\n\n  let props = entry.props;\n  if (schema) {\n    const result = schema[\"~standard\"].validate(entry.props);\n    // React render is synchronous; async schemas are a config mistake and\n    // are contained like any other invalid block.\n    if (result instanceof Promise) {\n      return (\n        <Fallback\n          reason=\"invalid-props\"\n          type={entry.type}\n          props={entry.props}\n          issues={[\n            {\n              message:\n                \"schema validated asynchronously; blockprint only supports synchronous schemas\",\n            },\n          ]}\n        />\n      );\n    }\n    if (result.issues) {\n      return (\n        <Fallback\n          reason=\"invalid-props\"\n          type={entry.type}\n          props={entry.props}\n          issues={result.issues}\n        />\n      );\n    }\n    props = result.value;\n  }\n\n  return <Component {...(props as object | undefined)} />;\n}\n","import type { FallbackProps } from \"./types\";\n\n// Ambient declaration instead of @types/node: bundlers replace\n// process.env.NODE_ENV statically, and the library has no other Node surface.\ndeclare const process: { env: { NODE_ENV?: string } };\n\nexport function DefaultFallback(props: FallbackProps) {\n  if (process.env.NODE_ENV === \"production\") {\n    return null;\n  }\n\n  const detail =\n    props.reason === \"invalid-props\"\n      ? props.issues.map((issue) => issue.message).join(\"; \")\n      : \"no component registered for this type\";\n\n  return (\n    <div\n      role=\"note\"\n      style={{\n        border: \"1px dashed #c00\",\n        borderRadius: 4,\n        padding: \"8px 12px\",\n        fontFamily: \"monospace\",\n        fontSize: 13,\n        color: \"#c00\",\n      }}\n    >\n      blockprint: block &quot;{props.type}&quot; not rendered ({props.reason}):{\" \"}\n      {detail}\n    </div>\n  );\n}\n"],"mappings":";;;;;;AAuBO,SAAS,eACd,QACa;AACb,SAAO,EAAE,OAAoB;AAC/B;;;AC3BA,SAAS,gBAAgB;;;ACiBrB;AAXG,SAAS,gBAAgB,OAAsB;AACpD,MAAI,QAAQ,IAAI,aAAa,cAAc;AACzC,WAAO;AAAA,EACT;AAEA,QAAM,SACJ,MAAM,WAAW,kBACb,MAAM,OAAO,IAAI,CAAC,UAAU,MAAM,OAAO,EAAE,KAAK,IAAI,IACpD;AAEN,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,OAAO;AAAA,QACL,QAAQ;AAAA,QACR,cAAc;AAAA,QACd,SAAS;AAAA,QACT,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,OAAO;AAAA,MACT;AAAA,MACD;AAAA;AAAA,QAC0B,MAAM;AAAA,QAAK;AAAA,QAAsB,MAAM;AAAA,QAAO;AAAA,QAAG;AAAA,QACzE;AAAA;AAAA;AAAA,EACH;AAEJ;;;ADsBM;AArBN,SAAS,WAAW,KAAuC;AACzD,MAAI,OAAO,QAAQ,YAAY,QAAQ,QAAQ,eAAe,KAAK;AACjE,WAAO;AAAA,EACT;AACA,SAAO,EAAE,WAAW,IAAI;AAC1B;AAEO,SAAS,SAAgC;AAAA,EAC9C;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAAgC;AAC9B,QAAM,WAAW,YAAY;AAC7B,QAAM,UAAU,YAAY,MAAM;AAElC,SAAO,QAAQ,IAAI,CAAC,OAAO,UAAU;AACnC,UAAM,MAAM,MAAM,MAAM,GAAG,MAAM,IAAI,IAAI,KAAK;AAC9C,UAAM,OAAO,YAAY,OAAO,UAAU,QAAQ;AAElD,WACE,oBAAC,YACE,sBAAY,UAAU,MAAM,OAAO,KAAK,IAAI,QADhC,GAEf;AAAA,EAEJ,CAAC;AACH;AAEA,SAAS,YACP,OACA,UACA,UACW;AACX,MAAI,CAAC,OAAO,OAAO,SAAS,QAAQ,MAAM,IAAI,GAAG;AAC/C,WACE,oBAAC,YAAS,QAAO,gBAAe,MAAM,MAAM,MAAM,OAAO,MAAM,OAAO;AAAA,EAE1E;AAEA,QAAM,EAAE,WAAW,WAAW,OAAO,IAAI;AAAA,IACvC,SAAS,OAAO,MAAM,IAAI;AAAA,EAC5B;AAEA,MAAI,QAAQ,MAAM;AAClB,MAAI,QAAQ;AACV,UAAM,SAAS,OAAO,WAAW,EAAE,SAAS,MAAM,KAAK;AAGvD,QAAI,kBAAkB,SAAS;AAC7B,aACE;AAAA,QAAC;AAAA;AAAA,UACC,QAAO;AAAA,UACP,MAAM,MAAM;AAAA,UACZ,OAAO,MAAM;AAAA,UACb,QAAQ;AAAA,YACN;AAAA,cACE,SACE;AAAA,YACJ;AAAA,UACF;AAAA;AAAA,MACF;AAAA,IAEJ;AACA,QAAI,OAAO,QAAQ;AACjB,aACE;AAAA,QAAC;AAAA;AAAA,UACC,QAAO;AAAA,UACP,MAAM,MAAM;AAAA,UACZ,OAAO,MAAM;AAAA,UACb,QAAQ,OAAO;AAAA;AAAA,MACjB;AAAA,IAEJ;AACA,YAAQ,OAAO;AAAA,EACjB;AAEA,SAAO,oBAAC,aAAW,GAAI,OAA8B;AACvD;","names":[]}