@nubbin/core 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -1,369 +1,1394 @@
 import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
 
+/**
+ * What an editing surface renders a field as. `"unknown"` is the honest answer for a JSON
+ * Schema node carrying no type an inspector can render — a field the studio shows read-only
+ * rather than guessing at.
+ *
+ * - `"string"`, `"number"`, `"boolean"` — scalars; `integer` reports as `"number"`.
+ * - `"enum"` — a closed set, whose members arrive on `FieldNode.members`.
+ * - `"array"` — a list; the row shape is a separate `FieldNode` at `path[]`.
+ * - `"object"` — a nested shape, whose own fields follow it in the result.
+ * - `"union"` — one of several branches; each branch's fields are emitted under this path.
+ */
 type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
+/** One addressable field of a schema, in the dotted form a hint key uses. */
 interface FieldNode {
     /** Dotted path from the schema root, with `[]` for array members: `cta.label`, `items[].title`. */
     path: string;
+    /** What the field is, and so what an inspector renders for it. */
     kind: FieldKind;
+    /** `true` when the schema does not require the field. An array's row shape is never optional. */
     optional: boolean;
     /** Present only for `enum`. */
     members?: readonly string[];
 }
+/** The contract for reading a schema's field structure — what `defineCatalog` resolves hint
+ * paths through, and what an editing surface reads a block's fields from. */
 interface SchemaAdapter {
+    /**
+     * Describes every path a hint may target.
+     *
+     * @param schema - The schema to read. What counts as readable is the implementation's to
+     *   decide; `zodAdapter` accepts anything exposing the Standard JSON Schema converter.
+     * @returns One `FieldNode` per addressable path, parent before child. The schema root itself
+     *   has no path and no entry, so the result is exactly the set of paths a hint may name.
+     * @throws {NubbinError} Implementation-defined. `zodAdapter` refuses a schema with no
+     *   converter as `no-json-schema`; the converter itself throws on a type JSON Schema cannot
+     *   represent.
+     */
     describe(schema: unknown): FieldNode[];
 }
 
 /**
- * Reads a zod schema for the studio and hint resolution, entirely through the Standard JSON
- * Schema converter the schema itself carries — `core` imports nothing from zod to do it.
- * Validation never runs against this projection; it always runs `schema["~standard"].validate()`
- * on the real schema.
+ * The shipped `SchemaAdapter` — what `defineCatalog` resolves hint paths through, exported so an
+ * editing surface can describe a block's fields without loading the block's component.
+ *
+ * It is named for the reference validator but reads any schema exposing the Standard JSON Schema
+ * converter, `richText()` included.
+ *
+ * @example
+ * ```ts
+ * zodAdapter.describe(z.object({ title: z.string(), draft: z.boolean().optional() }));
+ * // [
+ * //   { path: "title", kind: "string", optional: false },
+ * //   { path: "draft", kind: "boolean", optional: true },
+ * // ]
+ *
+ * zodAdapter.describe(z.object({ items: z.array(z.object({ title: z.string() })) }))
+ *   .map((field) => field.path);
+ * // ["items", "items[]", "items[].title"]
+ *
+ * zodAdapter.describe(z.object({ tone: z.enum(["light", "dark"]) }));
+ * // [{ path: "tone", kind: "enum", optional: false, members: ["light", "dark"] }]
+ * ```
  */
 declare const zodAdapter: SchemaAdapter;
 
+/**
+ * Props as they stand before validation — what a document node carries and what a document
+ * operation writes. Every value is `unknown` until the block's schema has judged it.
+ *
+ * @example
+ * ```ts
+ * import type { UnknownProps } from "@nubbin/core";
+ *
+ * const draft: UnknownProps = { title: "Launch", tone: "light" };
+ * ```
+ */
 type UnknownProps = Record<string, unknown>;
 /**
- * A block's props, derived from its schema. The whole of invariant 1 in one type: there is no
- * second definition of a block's shape, so nothing can drift from it.
+ * The props a block's component receives — the output side of its schema, as `validate()`
+ * returned it. Type the component with this instead of writing an interface beside the schema:
+ * a field a transform reshaped arrives in its transformed form, not as the author typed it.
+ *
+ * @typeParam Schema - The block's schema. Pass `typeof mySchema`.
+ * @example
+ * ```ts
+ * import type { InferProps } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const heroSchema = z.object({
+ *   headline: z.string(),
+ *   tone: z.enum(["light", "dark"]),
+ * });
+ *
+ * type HeroProps = InferProps<typeof heroSchema>;
+ * // { headline: string; tone: "light" | "dark" }
  *
- * `InferOutput` rather than `InferInput` because a component receives what `validate()`
- * returned — compile freezes the validated value, so a field a transform reshaped reaches the
- * component in its output form, not as the author typed it.
+ * const Hero = ({ headline, tone }: HeroProps) => null;
+ * ```
  */
 type InferProps<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+/**
+ * What one slot accepts: which blocks may sit in it, and how many. `allow` is checked twice —
+ * its entries must name registered blocks, and every child a document puts here must be one of
+ * them. The bounds are checked when a document compiles.
+ *
+ * @example
+ * ```ts
+ * import type { SlotConstraint } from "@nubbin/core";
+ *
+ * const items: SlotConstraint = { allow: ["Card"], min: 1, max: 4 };
+ * const anything: SlotConstraint = {};
+ * ```
+ */
 interface SlotConstraint {
-    /** Block names permitted here, each resolved at registration. Omitted means any registered block. */
+    /**
+     * Block names permitted here, each resolved at registration. Omitted means any registered
+     * block. An entry naming no registered block fails `createRegistry` rather than silently
+     * rejecting every child; a child a listed name does not cover is a compile fault
+     * (`slot-not-allowed`).
+     */
     allow?: readonly string[];
+    /**
+     * Fewest children the slot must hold, checked at compile (`slot-min`). A declared slot the
+     * document never mentions counts as holding zero, so a `min` is enforced there too.
+     */
     min?: number;
+    /**
+     * Most children the slot may hold, checked at compile (`slot-max`). `defineBlock` refuses a
+     * `min` above it.
+     */
     max?: number;
 }
+/**
+ * One block as registered: the name documents resolve through, the schema its props are judged
+ * against, the component that renders it, and the slots it accepts children in. Build one with
+ * `defineBlock` rather than by hand — the object literal alone runs no checks.
+ *
+ * @typeParam Schema - The block's [Standard Schema](https://standardschema.dev).
+ * @typeParam Component - Whatever the consumer's renderer accepts.
+ * @example
+ * ```ts
+ * import type { Block } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const cardSchema = z.object({ title: z.string() });
+ *
+ * const card: Block<typeof cardSchema, null> = {
+ *   name: "Card",
+ *   schema: cardSchema,
+ *   component: null,
+ *   version: 2,
+ *   slots: {},
+ * };
+ * ```
+ */
 interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component = unknown> {
-    /** Stable identity, referenced by every node. Renaming it is a migration. */
+    /**
+     * Stable identity, referenced by every node. Renaming it is a migration. Unique across a
+     * registry — two blocks sharing a name are refused.
+     */
     name: string;
+    /**
+     * The schema props are validated against, through its own `~standard.validate`. It must answer
+     * synchronously; compile refuses a schema that returns a promise.
+     */
     schema: Schema;
-    /** Generic so core never imports a rendering library. */
+    /**
+     * What renders this block. `core` neither calls nor inspects it, which is why the component
+     * lives in the registry and never in the serializable catalog. `@nubbin/react` narrows it to a
+     * component type.
+     */
     component: Component;
-    /** Bumped when the schema changes incompatibly. */
+    /**
+     * Bumped when the schema changes incompatibly. An integer of 1 or more, stamped into the
+     * `blockVersions` of every artifact whose document uses the block — which is what
+     * `checkRollback` compares a stored artifact against.
+     */
     version: number;
+    /**
+     * Slot constraints keyed by slot name. A slot the document fills but the block does not declare
+     * is a compile error (`slot-not-allowed`).
+     */
     slots: Record<string, SlotConstraint>;
 }
 
+/**
+ * What a page says about itself. `compile` copies it into the artifact unchanged and Nubbin
+ * renders none of it — a framework binding decides what becomes a `<title>` or a meta tag.
+ */
 interface DocumentMeta {
+    /** The page's title. The one required field: every page is named, in an editor as much as in a tab. */
     title: string;
+    /** The page's description, for a meta tag. */
     description?: string;
+    /** A robots directive, verbatim — `noindex`, `noindex, nofollow`. Absent leaves it to the app's default. */
     robots?: string;
+    /** The page's canonical URL, absolute. `@nubbin/next` puts it where Next reads one. */
     canonical?: string;
 }
-/** The authoring shape: children are id references, so every editor operation is by id. */
+/**
+ * One element of a document: which block renders it, the props an author has typed, and the ids
+ * of what sits in each of its slots.
+ *
+ * @example
+ * ```ts
+ * const section: Node = {
+ *   id: crypto.randomUUID(),
+ *   block: "Hero",
+ *   props: { title: "Summer promotion", price: 10 },
+ *   slots: { items: ["card-1", "card-2"] },
+ * };
+ * ```
+ */
 interface Node {
+    /**
+     * Unique within the document, and the handle every operation takes. The caller mints it —
+     * `core` reaches no `crypto` builtin, and a generator inside these functions would make one
+     * composition produce a different document each time, which content addressing cannot tolerate.
+     */
     id: string;
+    /** The `name` of a registered block. `compile` refuses a name neither the registry nor the catalog holds. */
     block: string;
+    /**
+     * What the author typed, unvalidated. `compile` runs it through the block's schema and keeps
+     * what `validate()` returned — a coercion, a transform or a `.default()` reaches the artifact
+     * in its parsed form, and a key the schema did not keep is reported as `unknown-prop`.
+     */
     props: UnknownProps;
-    /** Slot name → ordered child ids. */
+    /**
+     * Slot name → ordered child ids. Order is the render order. An absent slot holds zero
+     * children, which a `min` of 1 or more refuses.
+     */
     slots?: Record<string, readonly string[]>;
 }
+/**
+ * One version of a page's composition — the input to `compile`, and what an editing session
+ * reads and rewrites. Flat by design: `elements` is an index keyed by id and a node's slots hold
+ * child ids, so every operation addresses a node directly rather than walking a tree to reach it.
+ *
+ * `setNodeProp`, `addNode`, `removeNode` and `moveNode` each return a new one, copy-on-write,
+ * with every untouched node kept by reference. None of them bumps `version`.
+ *
+ * @example
+ * ```ts
+ * const version: DocumentVersion = {
+ *   documentId: "d1",
+ *   version: 1,
+ *   roots: ["n1"],
+ *   elements: {
+ *     n1: { id: "n1", block: "Hero", props: { title: "T" }, slots: { items: ["n2"] } },
+ *     n2: { id: "n2", block: "Card", props: { label: "L" } },
+ *   },
+ *   meta: { title: "Summer promotion" },
+ *   createdAt: "2026-01-01T00:00:00Z",
+ *   createdBy: "studio",
+ * };
+ * ```
+ */
 interface DocumentVersion {
+    /** The page this is a version of, stable across every version of it. Stamped into the artifact. */
     documentId: string;
+    /** Which version of that page. Appending a version belongs to the authoring store, not to one edit. */
     version: number;
     /**
-     * Ordered entry elements — the artifact's tree is these, denormalized, in this order. See
-     * [A document has many roots](../../../docs/decisions/a-document-has-many-roots.md).
+     * Ordered entry elements — the artifact's tree is these, denormalized, in this order. An id
+     * with no element behind it is a `dangling-child`, and an empty list is `no-roots`. See
+     * [A document has many roots](https://github.com/effekt/nubbin/blob/main/docs/decisions/a-document-has-many-roots.md).
      */
     roots: readonly string[];
+    /**
+     * Every node in the document, keyed by its own `id`. A node no slot and no root reaches is
+     * `unreachable`, which `compile` refuses rather than dropping in silence.
+     */
     elements: Record<string, Node>;
+    /** What the page says about itself. Copied into the artifact unchanged. */
     meta: DocumentMeta;
+    /** When this version was authored, as an ISO 8601 timestamp. Not carried into the artifact. */
     createdAt: string;
+    /**
+     * Who authored it, in whatever identity the consumer's authoring surface uses. Not carried
+     * into the artifact either — both fields describe the draft, not the published page.
+     */
     createdBy: string;
 }
 
 /**
- * Places a node in a parent's slot: a new `DocumentVersion` with the node registered and the
- * slot's order rewritten, copy-on-write, every other node untouched by reference.
+ * Places a node in a parent's slot and registers it among the document's elements.
  *
- * `node.id` arrives already minted. `core` runs in a browser, a worker and a build step, and a
- * generator inside it would make the same composition produce a different document every time —
- * so the caller mints, and the two things this can still check are the parent it names and the
- * id it brings.
+ * The caller mints `node.id`; `crypto.randomUUID()` in the calling code is the usual source.
  *
- * Slot legality is not one of them. Whether the block belongs in that slot, and whether the slot
- * is now over its `max`, is `compile`'s judgment — the same division `setNodeProp` follows for a
- * prop's validity, and what lets a document be illegal between two edits that end legal.
+ * @param version - The document to edit. Read, never written.
+ * @param parentId - Id of the node whose slot receives the child. The document must already
+ *   hold it.
+ * @param slot - Slot name on that parent. A slot the parent has never filled is opened.
+ * @param node - The node to place. Its `id` must be one the document does not already hold.
+ * @param index - Position in the slot's child list as it stands before the insert. Omit to
+ *   append; an index past the end appends.
+ * @returns A new `DocumentVersion` with the node registered and the slot's order rewritten.
+ *   The argument is not mutated, `version.version` is not bumped, and every node the edit did
+ *   not touch is carried over by reference.
+ * @throws {NubbinError} `no-such-node` when `parentId` names a node the document does not
+ *   hold; `duplicate-node-id` when `node.id` is already in use, which would replace the node
+ *   holding it and redirect every slot that named it.
+ * @example
+ * ```ts
+ * const next = addNode(version, "stack", "sections", {
+ *   id: crypto.randomUUID(),
+ *   block: "Card",
+ *   props: { title: "New" },
+ * });
  *
- * `index` inserts; its absence appends.
+ * // Second in the slot rather than last.
+ * const inserted = addNode(version, "stack", "sections", card, 1);
+ * ```
  */
 declare function addNode(version: DocumentVersion, parentId: string, slot: string, node: Node, index?: number): DocumentVersion;
 
-/** How a field's value resolves at render. Absent means static — the value freezes into props. */
+/**
+ * How a field's value resolves at render. Absent means static — the value freezes into props.
+ * Present, it is left out of the compiled props and copied into the node's `holes` instead, for
+ * the consumer's resolver to fill on each render.
+ *
+ * @example
+ * ```ts
+ * import type { FieldHintData } from "@nubbin/core";
+ *
+ * const hourly: FieldHintData = { revalidate: 3600 };
+ * ```
+ */
 type FieldHintData = {
+    /** Seconds a resolved value may be reused before the resolver is asked for it again. */
     revalidate: number;
 };
 /**
- * Studio treatment for one schema path. Open by design: a consumer may carry keys core does not
- * read, and core reads exactly one — how the field resolves.
+ * How an editing surface should treat one field of a block's schema. `core` reads `data` and
+ * decides nothing else about the field.
+ *
+ * @example
+ * ```ts
+ * import type { FieldHint } from "@nubbin/core";
+ *
+ * const live: FieldHint = { data: { revalidate: 5 } };
+ * const frozen: FieldHint = {};
+ * ```
  */
 interface FieldHint {
+    /**
+     * Marks the field as resolved at render rather than frozen at compile. Legal only on a path
+     * addressing a single value — a path containing `[]`, or one nesting inside another `data`
+     * path, fails registration.
+     */
     data?: FieldHintData;
 }
+/**
+ * The editing half of a catalog entry: how the studio should treat this block's fields.
+ *
+ * @example
+ * ```ts
+ * import type { BlockUi } from "@nubbin/core";
+ *
+ * const ui: BlockUi = { fields: { "cta.label": { data: { revalidate: 60 } } } };
+ * ```
+ */
 interface BlockUi {
-    /** Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail registration. */
+    /**
+     * Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail
+     * registration, read through the schema's own JSON Schema converter rather than a validator.
+     */
     fields?: Record<string, FieldHint>;
 }
-/** Serializable data only — what the studio and CI read. Components live in the registry. */
+/**
+ * One block's registration data with no component attached — schema, editing hints and defaults.
+ * Serializable data only: what the studio and CI read. Components live in the registry.
+ *
+ * @example
+ * ```ts
+ * import type { CatalogEntry } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const hero: CatalogEntry = {
+ *   schema: z.object({ title: z.string() }),
+ *   defaults: { title: "Headline" },
+ *   ui: { fields: { title: {} } },
+ * };
+ * ```
+ */
 interface CatalogEntry {
+    /**
+     * The block's schema, the same one its `Block` carries. It is judged at registration rather
+     * than by the type: props and defaults run through `~standard.validate`, and hint paths are
+     * read through `~standard.jsonSchema`.
+     */
     schema: unknown;
+    /** Editing hints, keyed by schema path. Omit it and every field is treated as static. */
     ui?: BlockUi;
+    /**
+     * What a freshly dropped block renders with. Checked against `schema` at registration, because
+     * defaults that fail it produce a block invalid the instant it is placed.
+     */
     defaults?: UnknownProps;
 }
+/**
+ * Every block a project offers, keyed by the block name the registry resolves — the half a studio
+ * or a CI step can fetch, since it holds no components. Build one with `defineCatalog`; the object
+ * literal alone runs no checks.
+ *
+ * @example
+ * ```ts
+ * import type { Catalog } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const catalog: Catalog = {
+ *   Hero: { schema: z.object({ title: z.string() }) },
+ * };
+ * ```
+ */
 type Catalog = Record<string, CatalogEntry>;
 
-/** Field path → how the field resolves at render. */
+/**
+ * The fields on one node that the renderer resolves rather than reads, keyed by the dotted
+ * schema path the block's `ui.fields` hint named. The value carries how the field resolves;
+ * where it resolves from is the rendering adapter's business.
+ *
+ * @example
+ * ```ts
+ * const holes: Holes = { "cta.label": { revalidate: 60 } };
+ * ```
+ */
 type Holes = Record<string, FieldHintData>;
-/** Resolved — no lookups, no dangling references possible. */
+/**
+ * One node of a compiled tree. Children are the nodes themselves, so a renderer walks the tree
+ * without resolving an id against anything.
+ *
+ * @example
+ * ```tsx
+ * function render(node: ArtifactNode) {
+ *   const Block = components[node.block];
+ *   const children = Object.values(node.slots ?? {}).flat().map(render);
+ *   return <Block {...node.props}>{children}</Block>;
+ * }
+ * ```
+ */
 interface ArtifactNode {
+    /** The id of the document element this was compiled from — stable across recompiles. */
     id: string;
+    /** The block's registered name. Look it up in the registry to find the component. */
     block: string;
-    /** Frozen fields only — literal values. */
+    /**
+     * The props as compiled: literal values only, already validated against the block's schema.
+     * A field listed in `holes` is absent here.
+     */
     props: UnknownProps;
+    /** The fields left for the renderer to resolve. Absent when the node has none. */
     holes?: Holes;
+    /**
+     * Slot name → the nodes filling it, in order. Absent when the document element declared no
+     * slots; a declared slot with nothing in it is an empty array.
+     */
     slots?: Record<string, ArtifactNode[]>;
 }
-/** The compiled result of one document version. Immutable and content-addressed. */
+/**
+ * One route's page, compiled and ready to render or store. Nothing mutates it — publishing a
+ * change compiles a new artifact and moves the route's pointer at it, so a hash that resolves
+ * once resolves to the same bytes forever.
+ *
+ * @example
+ * ```ts
+ * const { artifact } = compile(version, catalog, registry, "/pricing");
+ * await store.write(artifact);
+ * await store.publish(artifact.route, artifact.hash);
+ * ```
+ */
 interface Artifact {
-    /** Content address — the identity. */
+    /**
+     * The content address, and the name to read it back by. It is computed over every other field
+     * with object keys sorted first, so identical content lands at the same address however the
+     * compile happened to order it.
+     */
     hash: string;
+    /**
+     * The route this was compiled for. The CLI refuses to roll a route back to an artifact
+     * carrying a different one, however plausible the hash looks.
+     */
     route: string;
+    /** The document this is a compilation of. */
     documentId: string;
+    /** Which version of that document — the number on the `DocumentVersion` that was compiled. */
     documentVersion: number;
-    /** What this was compiled against — only the blocks the document uses. */
+    /**
+     * Block name → the version registered when this compiled, for the blocks the document uses and
+     * no others. `checkRollback` and `checkCompatibility` compare it against a live registry.
+     */
     blockVersions: Record<string, number>;
+    /** One tree per entry element, in the order the document version's `roots` names them. */
     tree: ArtifactNode[];
+    /** The document's metadata, carried through unchanged — the head a renderer emits. */
     meta: DocumentMeta;
+    /** The `@nubbin/core` version that compiled it. */
     compiledWith: string;
 }
-/** The only mutable state in the output layer — one independently-writable record per route. */
+/**
+ * What a route currently serves. This is the one record that changes in place: publishing,
+ * rolling back and unpublishing all move or remove a pointer, and touch nothing else.
+ *
+ * @example
+ * ```ts
+ * const pointer = await store.pointer("/pricing");
+ * const artifact = pointer === null ? null : await store.read(pointer.hash);
+ * ```
+ */
 interface RoutePointer {
+    /** The route served, exactly as it was published. */
     route: string;
+    /** How a request matches the route — derived from it by `parseMatchKind`, never supplied. */
     matchKind: "exact" | "param" | "prefix";
-    /** Artifact currently live at this route. */
+    /** The hash of the artifact serving this route right now. */
     hash: string;
+    /** When the pointer last moved, as an ISO-8601 timestamp. */
     updatedAt: string;
 }
-/** Advisory aggregation over every pointer, for the studio's route list and CI. */
+/**
+ * Every route pointer a store holds, gathered in one value — the route list an editing surface
+ * or a CI check reads. Derived on each call, so it is a snapshot rather than a stored document
+ * anything else depends on.
+ *
+ * @example
+ * ```ts
+ * const { routes } = await store.manifest();
+ * console.log(routes.map((pointer) => `${pointer.route} -> ${pointer.hash}`).join("\n"));
+ * ```
+ */
 interface Manifest {
+    /** One pointer per published route, in no guaranteed order. */
     routes: RoutePointer[];
+    /** When this snapshot was taken, as an ISO-8601 timestamp. */
     generatedAt: string;
 }
-/** The output layer's whole IO surface. Adapters implement it; core only returns values for it. */
+/** One pointer move, recorded by `publish` — only published states, so rollback can trust it. */
+interface PointerMove {
+    /** What the route was pointed at. */
+    hash: string;
+    /** The document version that compiled to that hash — what a rollback resolves by. */
+    documentVersion: number;
+    /** When the pointer moved, as an ISO-8601 timestamp. */
+    movedAt: string;
+}
+/**
+ * The storage contract behind publishing: implement it over Postgres, S3, or anything else, and
+ * every part of Nubbin that publishes, rolls back or checks routes works against it. Two kinds of
+ * state sit behind it — artifacts keyed by content hash, written once and never changed, and one
+ * pointer per route, which is the only thing that moves.
+ *
+ * Callers order the two: `write` the artifact, then `publish` the route at its hash. An
+ * implementation holds up its half by making absence a value rather than a failure, by taking a
+ * repeated `write` as a no-op and a repeated `publish` as an ordinary one so a retried publish
+ * succeeds, and by writing each pointer whole — two publishes racing for one route must leave one
+ * of them intact, never a blend. `@nubbin/store-fs` is the reference implementation, and
+ * `packages/store-fs/src/testing/runArtifactStoreContract.ts` is the suite every implementation
+ * is expected to pass.
+ *
+ * @example
+ * ```ts
+ * import { parseMatchKind } from "@nubbin/core";
+ * import type { ArtifactStore } from "@nubbin/core";
+ *
+ * const store: ArtifactStore = {
+ *   read: async (hash) => (await db.artifact(hash)) ?? null,
+ *   write: async (artifact) => { await db.putArtifactIfAbsent(artifact.hash, artifact); },
+ *   manifest: async () => ({ routes: await db.pointers(), generatedAt: new Date().toISOString() }),
+ *   pointer: async (route) => (await db.pointer(route)) ?? null,
+ *   publish: async (route, hash) => { await db.movePointer(route, hash, parseMatchKind(route)); },
+ *   unpublish: async (route) => { await db.deletePointer(route); },
+ * };
+ * ```
+ */
 interface ArtifactStore {
+    /**
+     * Reads one artifact by its content hash.
+     *
+     * @param hash - The `hash` of an artifact already written.
+     * @returns The artifact as written, or `null` when the store holds nothing at that hash.
+     * Absence is a value here — an unknown hash never throws.
+     * @example
+     * ```ts
+     * const artifact = await store.read("4a162726");
+     * ```
+     */
     read(hash: string): Promise<Artifact | null>;
+    /**
+     * Stores one artifact under its own hash. Write before publishing the route at it.
+     *
+     * @param artifact - A compiled artifact. `artifact.hash` is the key; nothing else is read.
+     * @returns Nothing. Writing a hash the store already holds is a no-op, so a publish retried
+     * after a timeout succeeds on its second attempt.
+     * @throws Whatever the underlying storage raises when the write itself fails.
+     * @example
+     * ```ts
+     * await store.write(compile(version, catalog, registry, "/pricing").artifact);
+     * ```
+     */
     write(artifact: Artifact): Promise<void>;
+    /**
+     * Lists every published route.
+     *
+     * @returns A snapshot of every pointer the store holds, with the time it was taken. An empty
+     * `routes` is a store with nothing published, not a failure.
+     * @example
+     * ```ts
+     * const { routes } = await store.manifest();
+     * ```
+     */
     manifest(): Promise<Manifest>;
+    /**
+     * Reads the pointer for one route.
+     *
+     * @param route - The route as it was published, matched exactly — `/pricing` does not find
+     * `/pricing/`, and a `param` or `prefix` pointer is found by its pattern, not by a path it
+     * would match.
+     * @returns The pointer, or `null` when nothing is published at that route.
+     * @example
+     * ```ts
+     * const pointer = await store.pointer("/guides/[city]");
+     * ```
+     */
     pointer(route: string): Promise<RoutePointer | null>;
+    /**
+     * Points a route at an artifact already in the store — the publish, and the rollback. The
+     * implementation derives `matchKind` with `parseMatchKind` and stamps `updatedAt` itself.
+     *
+     * @param route - The route to serve. It is validated on the way through `parseMatchKind`.
+     * @param hash - The artifact to serve there. It has to be written first.
+     * @returns Nothing. Publishing the same route and hash twice succeeds and leaves the route
+     *   where it already pointed, which is what makes a retry safe — it is not a no-op. The pointer
+     *   is rewritten and a store keeping history records a second move, since what is deduplicated
+     *   is the artifact rather than the act of publishing.
+     * @throws NubbinError with `code` `NubbinIssueCode.InvalidRoute` when the route is not
+     * addressable, from `parseMatchKind`. An implementation also rejects a hash it holds no
+     * artifact for, so no pointer can name one that was never written — `@nubbin/store-fs` refuses
+     * that with `NubbinIssueCode.ArtifactNotStored`.
+     * @example
+     * ```ts
+     * await store.write(artifact);
+     * await store.publish("/pricing", artifact.hash);
+     * ```
+     */
     publish(route: string, hash: string): Promise<void>;
+    /**
+     * Takes a route offline by removing its pointer. The artifact stays, so republishing it is
+     * another `publish` at the same hash.
+     *
+     * @param route - The route to stop serving.
+     * @returns Nothing. Unpublishing a route that has no pointer is a no-op.
+     * @example
+     * ```ts
+     * await store.unpublish("/pricing");
+     * ```
+     */
     unpublish(route: string): Promise<void>;
+    /**
+     * Every move `publish` made at this route, oldest first, surviving `unpublish`. Optional
+     * because a write-only blob store is still a valid adapter — a caller degrades with a
+     * message rather than requiring it.
+     *
+     * @param route - The route whose moves are read.
+     * @returns One entry per publish, oldest first, and an empty array for a route that has never
+     *   been published. A store that keeps no history omits the method rather than returning `[]`,
+     *   so a caller can tell "never published" from "not recorded".
+     * @example
+     * ```ts
+     * const moves = (await store.history?.("/pricing")) ?? [];
+     * moves.at(-1)?.hash; // what it points at now
+     * ```
+     */
+    history?(route: string): Promise<PointerMove[]>;
 }
 
-/** One route pointer and the artifact it names, as an adapter read them. */
+/**
+ * One live route, ready for `checkCompatibility`: a pointer and whatever the store returned for
+ * its hash. Build one per pointer in the manifest.
+ *
+ * @example
+ * ```ts
+ * import type { LiveRoute } from "@nubbin/core";
+ *
+ * const live: LiveRoute[] = await Promise.all(
+ *   routes.map(async (pointer) => ({ pointer, artifact: await store.read(pointer.hash) })),
+ * );
+ * ```
+ */
 interface LiveRoute {
+    /** The pointer as the store holds it — `route` and `hash` name the failure in the report. */
     pointer: RoutePointer;
-    /** `null` when the store holds no artifact at the pointer's hash — a pointer into nothing. */
+    /**
+     * What `store.read(pointer.hash)` returned. Pass the `null` through rather than skipping the
+     * route: an unresolvable hash is reported as its own kind of breakage.
+     */
     artifact: Artifact | null;
 }
-/** One block's version delta between what a live artifact needs and what is registered now. */
+/**
+ * One block's version delta, as it appears under a `block-drift` incompatibility. Enough to act
+ * on without reading the artifact: the name, what the page needs, and what the registry holds.
+ *
+ * @example
+ * ```ts
+ * import type { BlockDrift } from "@nubbin/core";
+ *
+ * const drift: BlockDrift = { block: "Hero", live: 1, registered: 2 };
+ * ```
+ */
 interface BlockDrift {
+    /** The block's registered name, as `blockVersions` keys it. */
     block: string;
-    /** The version the artifact was compiled against. */
+    /** The version the live page needs — restore this to make the route renderable again. */
     live: number;
-    /** The version registered now — `null` when the registry no longer holds the block at all. */
+    /** The version the registry holds now, or `null` when the block is no longer registered. */
     registered: number | null;
 }
 /**
- * Why one live route would not render. `unreadable-artifact` is a pointer whose hash the store
- * cannot resolve, which breaks the route without any registry change at all.
+ * One route that would not render, and why. Discriminate on `reason`: `drifted` exists only on
+ * the `block-drift` branch, since an unresolvable hash has no versions to compare.
+ *
+ * @example
+ * ```ts
+ * for (const failure of report.incompatible) {
+ *   if (failure.reason === "unreadable-artifact") {
+ *     console.error(`${failure.route}: nothing stored at ${failure.hash}`);
+ *   } else {
+ *     console.error(`${failure.route}: ${failure.drifted.map((d) => d.block).join(", ")}`);
+ *   }
+ * }
+ * ```
  */
 type RouteIncompatibility = {
+    /** The route whose pointer was checked. */
     route: string;
+    /** The hash that pointer names. */
     hash: string;
+    /** The store returned nothing for the hash, so the route is broken with no drift involved. */
     reason: "unreadable-artifact";
 } | {
+    /** The route whose pointer was checked. */
     route: string;
+    /** The hash that pointer names — what would render, if its blocks still matched. */
     hash: string;
+    /** The artifact read cleanly, and at least one block it needs has moved. */
     reason: "block-drift";
+    /** Every moved block, one entry each. Blocks that still match are not listed. */
     drifted: BlockDrift[];
 };
-/** The verdict over every live pointer. `checked` is reported so a run over nothing cannot read as a pass. */
+/**
+ * What `checkCompatibility` returns over a whole set of live routes. Assert on `checked` before
+ * trusting `compatible` — a run that read no pointers is compatible with everything.
+ *
+ * @example
+ * ```ts
+ * const report = checkCompatibility(live, registry);
+ * if (report.checked === 0) throw new Error("no live pointers read — this gate checked nothing");
+ * process.exitCode = report.compatible ? 0 : 1;
+ * ```
+ */
 interface CompatibilityReport {
+    /** How many live routes were examined — the length of the `live` array passed in. */
     checked: number;
+    /** `true` when `incompatible` is empty, including when nothing was checked. */
     compatible: boolean;
+    /** One entry per route that would not render, in the order the routes were passed in. */
     incompatible: RouteIncompatibility[];
 }
 
+/**
+ * The resolved block set — what compile and a renderer ask when a node names a block. Build one
+ * with `createRegistry`; it holds a snapshot of the array it was given, so adding a block means
+ * building a new registry rather than writing into this one.
+ *
+ * @example
+ * ```ts
+ * import { createRegistry, defineBlock } from "@nubbin/core";
+ * import type { Registry } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const registry: Registry = createRegistry([
+ *   defineBlock({
+ *     name: "Hero",
+ *     schema: z.object({ title: z.string() }),
+ *     component: null,
+ *     version: 1,
+ *     slots: {},
+ *   }),
+ * ]);
+ *
+ * const hero = registry.get("Hero");
+ * if (hero !== undefined) {
+ *   hero.version; // 1
+ * }
+ * ```
+ */
 interface Registry {
+    /**
+     * Resolves one block by the name a document node carries.
+     *
+     * @param name - The block name, matched exactly — casing included.
+     * @returns The registered block, or `undefined` when nothing carries that name. An unknown name
+     *   is a value to handle here; compile is where it becomes an `unknown-block` fault.
+     */
     get(name: string): Block | undefined;
+    /**
+     * Lists what the registry holds — the names a palette or a compatibility check enumerates.
+     *
+     * @returns Every registered name, in the order the blocks were given to `createRegistry`. A
+     *   fresh array each call, so writing to it changes nothing.
+     */
     names(): string[];
 }
 
 /**
- * The guardrail's whole question: would this registry fail to render an artifact a live route
- * pointer currently references? `checkRollback` decides each route — one artifact against the
- * registry is the same comparison whether a pointer is moving or a registry is — and this walks
- * every pointer the caller read, so publishing and merging are held to one rule.
+ * Runs the rollback comparison over every live route at once, and reports each failure with the
+ * version delta behind it: which route, which artifact, which block, what the page needs, what is
+ * registered. Point a CI job at it before merging a registry change to learn which pages the
+ * change would break.
+ *
+ * @param live - Every pointer worth checking, each paired with the artifact its hash resolves to.
+ * Read them from an `ArtifactStore` — a pointer the store cannot resolve is passed as `null`
+ * rather than dropped, because that route is already broken. Nothing here reads the store itself,
+ * so a caller whose live state sits somewhere else can build the pairs by hand.
+ * @param registry - The registry to judge them against, from `createRegistry`.
+ * @returns A report over the whole set: how many pointers were examined, whether all of them
+ * cleared, and one entry per route that did not. A block the registry gained since publish is
+ * not drift, so an added block never appears.
+ * @example
+ * ```ts
+ * import { checkCompatibility, formatCompatibilityReport } from "@nubbin/core";
+ * import type { LiveRoute } from "@nubbin/core";
  *
- * Pure, and synchronous: the caller reads the store and hands over what it found, so this runs
- * in CI, in a worker, or in a browser studio unchanged.
+ * const { routes } = await store.manifest();
+ * const live: LiveRoute[] = await Promise.all(
+ *   routes.map(async (pointer) => ({ pointer, artifact: await store.read(pointer.hash) })),
+ * );
+ *
+ * const report = checkCompatibility(live, registry);
+ * console.log(formatCompatibilityReport(report));
+ * if (!report.compatible) process.exitCode = 1;
+ * ```
  */
 declare function checkCompatibility(live: readonly LiveRoute[], registry: Registry): CompatibilityReport;
 
+/**
+ * What `checkRollback` reports about one artifact against one registry. Discriminate on
+ * `compatible` — the drifted names exist only on the failing branch, so a check narrows before
+ * anything can read them.
+ *
+ * @example
+ * ```ts
+ * import { checkRollback } from "@nubbin/core";
+ * import type { RollbackCheck } from "@nubbin/core";
+ *
+ * const verdict: RollbackCheck = checkRollback(artifact, registry);
+ * if (!verdict.compatible) {
+ *   console.error(`refusing the rollback: ${verdict.drifted.join(", ")} moved since compile`);
+ * }
+ * ```
+ */
 type RollbackCheck = {
+    /** Every block the artifact names is registered at the version it was compiled against. */
     compatible: true;
 } | {
+    /** At least one block the artifact names is registered at another version, or not at all. */
     compatible: false;
+    /**
+     * The names of the drifted blocks, in the order the artifact's `blockVersions` lists them.
+     * A block the registry no longer holds is named here too — deletion is drift.
+     */
     drifted: string[];
 };
 
 /**
- * Compares what the artifact was compiled against with the registry live now. A name the
- * registry no longer holds is drift, not an absent check — a deleted block is exactly the
- * failure a rollback must be warned about.
+ * Asks whether one stored artifact would still render against a registry — the question to
+ * settle before pointing a route back at it. Every name in the artifact's `blockVersions` has to
+ * be registered at the version recorded there; a different version, or no entry at all, is drift.
+ *
+ * @param artifact - The rollback target, as read back from the store. Only `blockVersions` is
+ * read, so an artifact hand-built for a test needs nothing else to be accurate.
+ * @param registry - The registry the running code holds now, from `createRegistry`.
+ * @returns `{ compatible: true }`, or `{ compatible: false, drifted }` naming every block that
+ * moved. Drift is a value, not a throw: whether it stops the rollback is the caller's call.
+ * @example
+ * ```ts
+ * import { checkRollback, createRegistry, defineBlock } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const heroAtV2 = defineBlock({
+ *   name: "Hero",
+ *   schema: z.object({ title: z.string() }),
+ *   component: null,
+ *   version: 2,
+ *   slots: {},
+ * });
+ *
+ * // artifact.blockVersions is { Hero: 1 }
+ * checkRollback(artifact, createRegistry([heroAtV2]));
+ * // { compatible: false, drifted: ["Hero"] }
+ * ```
  */
 declare function checkRollback(artifact: Artifact, registry: Registry): RollbackCheck;
 
 /**
- * Every reason Nubbin refuses something, as a value a consumer can key off rather than a string
- * they have to match. Each member's value is its own name in kebab-case, so a serialized issue
- * reads the same in a log as it does in code.
+ * Every reason Nubbin refuses something, as a value to branch on rather than a string to match.
+ * Compare it against `NubbinIssue.code` or `NubbinError.code`; a typo in a member name is a
+ * compile error, where a typo in a string literal is a branch that never runs.
  *
- * A const object rather than a TypeScript `enum`: it yields the same two things — a value to
- * branch on and a type to check against — without the runtime object an `enum` emits, and `core`
- * has to run unchanged in a browser, a worker and a build step.
+ * Each member's value is its own name in kebab-case, so a serialized issue reads the same in a
+ * log as it does in code. Scripts and editors match on these names, so every member below says
+ * what raises it and what has to change to satisfy it.
  *
- * Closed on purpose. A new refusal is a new member here, which is what makes the reference page
- * listing them checkable against this file.
+ * @example
+ * ```ts
+ * import { NubbinError, NubbinIssueCode } from "@nubbin/core";
+ *
+ * try {
+ *   addNode(version, "section-1", "items", node);
+ * } catch (error) {
+ *   if (error instanceof NubbinError && error.code === NubbinIssueCode.SlotMax) {
+ *     toast(`That slot is full: ${error.issues[0]?.at}`);
+ *   }
+ * }
+ * ```
  */
 declare const NubbinIssueCode: {
+    /** `defineBlock` was given a `version` that is not an integer of 1 or more. */
     readonly BlockVersion: "block-version";
+    /** `defineBlock` was given a slot whose `min` is above its `max`, which no composition satisfies. */
     readonly SlotBounds: "slot-bounds";
+    /** `createRegistry` found a slot's `allow` naming a block no registered block answers to. */
     readonly SlotAllowUnknown: "slot-allow-unknown";
+    /** `createRegistry` was given two blocks claiming one name — the identity every node resolves through. */
     readonly DuplicateBlockName: "duplicate-block-name";
+    /** `defineCatalog` found an entry's `defaults` do not satisfy that entry's own schema. */
     readonly InvalidDefaults: "invalid-defaults";
+    /** `defineCatalog` found `ui.fields` naming a path the schema does not define. Check the spelling against the schema. */
     readonly HintPathUnresolvable: "hint-path-unresolvable";
+    /**
+     * `defineCatalog` found a `data` hint with no single target: a path through `[]`, which names
+     * every member of an array, or two hints whose paths nest and would write one value twice.
+     */
     readonly HintNotAddressable: "hint-not-addressable";
+    /**
+     * A schema exposes no `~standard.validate`, or answers with a promise. Validation is
+     * synchronous at registration and at compile, so an async validator is refused rather than
+     * awaited.
+     */
     readonly NotStandardSchema: "not-standard-schema";
+    /**
+     * A schema exposes no Standard JSON Schema converter, which field introspection needs — the
+     * studio reads a block's fields through it.
+     */
     readonly NoJsonSchema: "no-json-schema";
+    /** The document's `roots` is empty, so it names no entry element and there is no tree to build. */
     readonly NoRoots: "no-roots";
+    /**
+     * A node names a block neither the registry nor the catalog holds. Register the block, or
+     * correct the node's `block`.
+     */
     readonly UnknownBlock: "unknown-block";
+    /** A slot or a `roots` entry references an id that `elements` does not hold. */
     readonly DanglingChild: "dangling-child";
+    /** A node reaches back to one of its own ancestors, so the graph cannot flatten into a tree. */
     readonly Cycle: "cycle";
+    /** No slot reaches the node from any root, so it would be dropped silently on compile. */
     readonly Unreachable: "unreachable";
+    /** A slot the block never declared, or a child the slot's `allow` list rejects. */
     readonly SlotNotAllowed: "slot-not-allowed";
+    /** A slot holds fewer children than its `min`. An omitted slot holds zero. */
     readonly SlotMin: "slot-min";
+    /** A slot holds more children than its `max`. */
     readonly SlotMax: "slot-max";
+    /**
+     * A node's props failed its schema, or parsed to something other than an object. `path` names
+     * the offending field.
+     */
     readonly InvalidProps: "invalid-props";
+    /**
+     * A key the author wrote and the schema did not keep — almost always a typo, `heading` where
+     * the schema says `headline`. **Returned in `CompileResult.issues`, never thrown:** the
+     * artifact is valid and publishable without that key.
+     */
     readonly UnknownProp: "unknown-prop";
+    /** `setNodeProp`, `addNode`, `removeNode` or `moveNode` named a node id no element backs. */
     readonly NoSuchNode: "no-such-node";
+    /**
+     * `addNode` was given an id the document already uses. Reusing one would replace a node and
+     * redirect every slot that named it.
+     */
     readonly DuplicateNodeId: "duplicate-node-id";
+    /**
+     * A prop path with no single target: an empty segment, an `[]`, or a descent into an array.
+     * Raised by `setAtPath` and by `setNodeProp`.
+     */
     readonly PathNotAddressable: "path-not-addressable";
+    /**
+     * A route no request could match — no leading slash, a trailing slash, an empty or malformed
+     * segment, or a `*` that is not the last one. Raised by `compile` and by `parseMatchKind`.
+     */
     readonly InvalidRoute: "invalid-route";
+    /** `@nubbin/react`: the block registry has no importer for a block the artifact names. */
     readonly BlockNotLoaded: "block-not-loaded";
+    /** `@nubbin/react`: a node declares holes and the render was given no `resolveHole`. */
     readonly NoHoleResolver: "no-hole-resolver";
+    /** `@nubbin/react`: a block returned a Fragment, a composite, or several roots where one host element is required. */
     readonly NotOneHostElement: "not-one-host-element";
+    /** A publish names a hash the store does not hold. Write the artifact before pointing a route at it. */
     readonly ArtifactNotStored: "artifact-not-stored";
 };
 /** The value of any member, for a consumer narrowing on `issue.code`. */
 type NubbinIssueCode = (typeof NubbinIssueCode)[keyof typeof NubbinIssueCode];
 
 /**
- * One reason Nubbin refused something. The shape every refusal takes, whether it was thrown or
- * returned, so a consumer writes one handler and serializes one thing.
+ * One reason Nubbin refused something. The shape every refusal takes, whether it arrives thrown
+ * inside a `NubbinError` or returned in `CompileResult.issues`, so a consumer writes one handler
+ * and serializes one thing.
  *
- * `code` is for branching and `message` is for reading — the prose says what a person needs and
- * the code says what a program can act on, and neither is asked to do the other's job.
+ * It is plain JSON: safe to log, store, or send across a wire without reshaping.
  *
- * `at` and `path` are two coordinates rather than one string because an editing surface needs
- * both: `at` names the thing to select — a node, a block, a route — and `path` names where
- * inside it to highlight. Joining them into prose would leave a studio parsing its own error
- * messages to find the field an author has to fix.
+ * @example Turn an issue into an editor selection
+ * ```ts
+ * function reveal(issue: NubbinIssue): void {
+ *   if (issue.at !== undefined) editor.select(issue.at);
+ *   if (issue.path !== undefined) editor.highlightField(issue.path);
+ *   editor.explain(issue.message);
+ * }
+ * ```
  */
 interface NubbinIssue {
+    /**
+     * Which refusal this is. Branch on it against `NubbinIssueCode` — never on `message`, which is
+     * prose and is reworded whenever a clearer wording is found.
+     */
     code: NubbinIssueCode;
+    /** Prose for a person, naming the specific value or id at fault. Not a stable contract. */
     message: string;
-    /** What it concerns: a node id, a block name, or a route. */
+    /** What it concerns: a node id, a block name, or a route. Absent when nothing names it. */
     at?: string;
-    /** Where within that: a dotted prop path, `slots.items`, or `block`. */
+    /**
+     * Where within that: a dotted prop path, `slots.items`, or `block`. Absent when the whole
+     * subject is at fault rather than one place inside it.
+     */
     path?: string;
 }
 
 /**
- * What `compile` produces: the artifact, and everything it has to say about the document that
- * did not stop it producing one.
+ * What `compile` returns whenever it produced an artifact. Receiving one of these means the
+ * document compiled; a document that did not reaches the caller as a thrown `NubbinError`
+ * instead.
+ *
+ * @example
+ * ```ts
+ * const { artifact, issues } = compile(version, catalog, registry, "/pricing");
+ *
+ * await store.write(artifact);
+ * await store.publish(artifact.route, artifact.hash);
  *
- * The two travel together because the split is not severity, it is whether an artifact exists.
- * A document the schema refuses has none, and `compile` throws; a document carrying a key the
- * schema did not declare has a perfectly good one, and what became of that key is the consumer's
- * to log, ship, or ignore.
+ * for (const issue of issues) {
+ *   logger.warn({ code: issue.code, at: issue.at, path: issue.path, message: issue.message });
+ * }
+ * ```
  */
 interface CompileResult {
+    /**
+     * The compiled document: immutable, addressed by its own `hash`, and ready to hand to a store.
+     * `tree` holds one denormalized tree per entry in the document's `roots`, in that order.
+     */
     artifact: Artifact;
+    /**
+     * Everything `compile` has to say about the document that did not stop it producing one. A key
+     * an author wrote and the schema did not keep arrives here as `unknown-prop`, naming the node
+     * in `at` and the dotted path in `path`. Empty means nothing was dropped.
+     *
+     * These do not change the content address: two documents differing only by a key the schema
+     * never kept compile to the same `hash`, because they render identically.
+     */
     issues: readonly NubbinIssue[];
 }
 
 /**
- * Orchestration only. Structure first, and stop there if it failed — prop validation on a
- * document with dangling references produces cascading noise that buries the real cause.
+ * Validates one document version and serializes it into an immutable, content-addressed
+ * {@link Artifact}. It reads nothing and writes nothing — fetching the document and storing the
+ * artifact belong to an adapter.
+ *
+ * Two passes, each collecting rather than stopping at the first fault. Structure comes first:
+ * every node names a registered block, every child id resolves, the graph flattens from `roots`
+ * without cycles, and every filled slot is declared and inside its `allow`, `min` and `max`.
+ * Props come second, each node's values run through its catalog entry's own schema. The second
+ * pass runs only when the first found nothing.
+ *
+ * Compiling the same document against the same catalog and registry yields the same
+ * `artifact.hash` every time — key order is normalized before hashing, so an insertion order
+ * cannot change the address.
+ *
+ * @param version - The document to compile. `roots` names the entry elements in order and
+ *   `elements` indexes every node by id. Both are read, neither is mutated.
+ * @param catalog - The serializable half of registration, keyed by block name: the schema each
+ *   node's props are judged by, and the `ui.fields` hints deciding which fields freeze into the
+ *   artifact and which become holes filled at render. A block a node names and the catalog omits
+ *   is a fault.
+ * @param registry - The registered blocks, keyed by name. It supplies the slot constraints the
+ *   structural pass judges against, and the version number each used block is stamped with in
+ *   `artifact.blockVersions`.
+ * @param route - Where the artifact is published. It is baked into the artifact and into the
+ *   content address, and it is judged before the document is looked at: absolute, no trailing
+ *   slash unless it is `/` itself, `[slug]` for a param segment, and `*` only as the final
+ *   segment.
+ *
+ * @returns The artifact, and the issues that did not stop one existing. A key an author wrote
+ *   and the schema did not keep comes back as `unknown-prop`, naming the node and the dotted
+ *   path — the artifact is publishable either way, so logging it, shipping it or ignoring it is
+ *   the caller's call.
+ *
+ * @throws {NubbinError} A `NubbinError` coded `invalid-route` when `route` addresses no page,
+ *   raised before anything in the document is read.
+ * @throws {NubbinError} One `NubbinError` carrying every structural fault at once, in `issues`:
+ *   `no-roots`, `unknown-block`, `dangling-child`, `cycle`, `unreachable`, `slot-not-allowed`,
+ *   `slot-min`, `slot-max`.
+ * @throws {NubbinError} One `NubbinError` carrying every prop fault at once: `invalid-props` for
+ *   a value a schema rejects or one that parses to something other than an object, and
+ *   `unknown-block` for a node whose block has no catalog entry.
+ * @throws {NubbinError} A `NubbinError` coded `not-standard-schema` when a catalog entry's schema
+ *   exposes no `~standard.validate`, or answers with a promise — compiling is synchronous.
+ *
+ * @example Compile a document and store what comes back
+ * ```ts
+ * import { compile, createRegistry, defineBlock, defineCatalog } from "@nubbin/core";
+ * import type { DocumentVersion } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const heroSchema = z.object({ title: z.string(), price: z.number() });
+ * const hero = defineBlock({
+ *   name: "Hero",
+ *   schema: heroSchema,
+ *   component: null,
+ *   version: 1,
+ *   slots: {},
+ * });
+ *
+ * const registry = createRegistry([hero]);
+ * const catalog = defineCatalog({
+ *   Hero: { schema: heroSchema, ui: { fields: { price: { data: { revalidate: 60 } } } } },
+ * });
  *
- * The route is judged before any of it, because it is baked into the artifact and into the
- * content address: an unaddressable route would otherwise compile, hash, and store cleanly, and
- * only fail to match a request once it was live.
+ * const version: DocumentVersion = {
+ *   documentId: "d1",
+ *   version: 1,
+ *   roots: ["n1"],
+ *   elements: { n1: { id: "n1", block: "Hero", props: { title: "T", price: 10 } } },
+ *   meta: { title: "Summer promotion" },
+ *   createdAt: "2026-01-01T00:00:00Z",
+ *   createdBy: "studio",
+ * };
+ *
+ * const { artifact, issues } = compile(version, catalog, registry, "/promotions/summer");
+ *
+ * artifact.tree[0]?.props;  // { title: "T" } — frozen into the artifact
+ * artifact.tree[0]?.holes;  // { price: { revalidate: 60 } } — resolved at render instead
+ * artifact.blockVersions;   // { Hero: 1 }
+ * issues;                   // [] — nothing the schema dropped
+ * ```
+ *
+ * @example Branch on a refusal rather than reading its prose
+ * ```ts
+ * import { NubbinError, NubbinIssueCode } from "@nubbin/core";
+ *
+ * try {
+ *   const { artifact } = compile(version, catalog, registry, route);
+ *   await store.write(artifact);
+ * } catch (error) {
+ *   if (!(error instanceof NubbinError)) throw error;
+ *   if (error.code === NubbinIssueCode.InvalidRoute) return rejectRoute(error.message);
+ *   for (const issue of error.issues) editor.mark(issue.at, issue.path, issue.message);
+ * }
+ * ```
  */
 declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): CompileResult;
 
 /**
- * Slot `allow` lists resolve once the whole array is ingested, so a block may name a sibling
- * registered after it.
+ * Turns the blocks an app ships into the lookup a renderer resolves nodes through: one name to
+ * one block, with every slot `allow` entry checked against the set. Hold the result for the life
+ * of the process — it reads a snapshot of the array and never re-reads it.
+ *
+ * @param blocks - Every block the app renders, each from `defineBlock`. Names must be unique
+ *   across the array, and order does not matter: a slot may name a block declared later.
+ * @returns A registry resolving a block by name and listing the names it holds, in the order the
+ *   blocks were given.
+ * @throws {NubbinError} `duplicate-block-name` when two blocks share a name, carrying the name in
+ *   `at`.
+ * @throws {NubbinError} `slot-allow-unknown` when a slot's `allow` names a block no entry defines.
+ *   Every bad entry is reported in one error as `"Name" (Block.slot)`, alongside the names that
+ *   are registered — two typos take one round trip, not two.
+ * @example
+ * ```ts
+ * import { createRegistry, defineBlock } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const pageBlock = defineBlock({
+ *   name: "Page",
+ *   schema: z.object({ title: z.string() }),
+ *   component: null,
+ *   version: 1,
+ *   slots: { items: { allow: ["Testimonial"] } },
+ * });
+ *
+ * const testimonialBlock = defineBlock({
+ *   name: "Testimonial",
+ *   schema: z.object({ quote: z.string() }),
+ *   component: null,
+ *   version: 1,
+ *   slots: {},
+ * });
+ *
+ * const registry = createRegistry([pageBlock, testimonialBlock]);
+ *
+ * registry.get("Page")?.name; // "Page"
+ * registry.get("Nope"); // undefined
+ * registry.names(); // ["Page", "Testimonial"]
+ * ```
  */
 declare function createRegistry(blocks: readonly Block[]): Registry;
 
 /**
- * Identity at runtime; its job is to fix the generic parameters at the call site so props are
- * inferred from the schema rather than declared beside it. The checks here are the ones the
- * type system cannot make — a version below 1, or a slot that no composition could satisfy.
+ * Declares a block — the name documents resolve through, the schema its props are validated
+ * against, the component that renders it, and the slots it accepts children in. The block comes
+ * back unchanged, with `Schema` and `Component` pinned at the call site so `InferProps` derives
+ * the component's props from the schema.
+ *
+ * @typeParam Schema - The block's [Standard Schema](https://standardschema.dev). Inferred from
+ *   `block.schema`; validation always runs its `~standard.validate`, which must answer
+ *   synchronously.
+ * @typeParam Component - Whatever the consumer's renderer accepts. `core` never inspects it.
+ * @param block - The block to declare. `version` must be an integer of 1 or more, and every slot
+ *   declaring both bounds must keep `min` at or below `max`. Names in a slot's `allow` are not
+ *   resolved here — `createRegistry` resolves them once every sibling is present.
+ * @returns The same object, typed `Block<Schema, Component>`.
+ * @throws {NubbinError} `block-version` when `version` is not an integer of 1 or more.
+ * @throws {NubbinError} `slot-bounds` when a slot's `min` exceeds its `max`, naming the block and
+ *   the slot in `at`.
+ * @example
+ * ```ts
+ * import { defineBlock } from "@nubbin/core";
+ * import type { InferProps } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const heroSchema = z.object({
+ *   headline: z.string(),
+ *   tone: z.enum(["light", "dark"]),
+ * });
+ *
+ * const Hero = (props: InferProps<typeof heroSchema>) => null;
+ *
+ * export const heroBlock = defineBlock({
+ *   name: "Hero",
+ *   schema: heroSchema,
+ *   component: Hero,
+ *   version: 1,
+ *   slots: { actions: { allow: ["CtaBanner"], max: 2 } },
+ * });
+ * ```
  */
 declare function defineBlock<Schema extends StandardSchemaV1, Component>(block: Block<Schema, Component>): Block<Schema, Component>;
 
 /**
- * The serializable half of the catalog/registry split: schema, ui, defaults, docs — no
- * components. Everything checkable at registration is checked here, because a bad hint or
- * bad defaults are silent at every later point.
+ * Declares the catalog — the component-free half of a block set, holding each block's schema,
+ * its editing hints and its defaults. Entries come back unchanged once every hint path and every
+ * set of defaults has been checked against the schema it belongs to.
+ *
+ * @param entries - Keyed by block name, matching the names `createRegistry` resolves. An entry
+ *   carrying only `schema` is stored as-is; `ui.fields` and `defaults` are each checked only when
+ *   present. Hint paths are read through the schema's own Standard JSON Schema converter, so an
+ *   entry with `ui.fields` needs a schema that exposes one.
+ * @returns The same object, typed `Catalog`.
+ * @throws {NubbinError} `hint-path-unresolvable` when a `ui.fields` key names a path the schema
+ *   does not define, naming the block, every unresolved path, and the paths the schema does
+ *   define.
+ * @throws {NubbinError} `hint-not-addressable` when a `data` hint sits on a path containing `[]`,
+ *   or when two `data` hints on one block nest — `cta` and `cta.label` write one value with no
+ *   defined order.
+ * @throws {NubbinError} `no-json-schema` when an entry carrying `ui.fields` has a schema without
+ *   the Standard JSON Schema converter (Standard Schema spec 1.1).
+ * @throws {NubbinError} `invalid-defaults` when `defaults` fail their entry's schema, carrying
+ *   every failing path and its message.
+ * @throws {NubbinError} `not-standard-schema` when an entry carrying `defaults` has a schema
+ *   without `~standard.validate`, or one that validates asynchronously.
+ * @throws {Error} From the schema's own JSON Schema converter, when a field has a type JSON
+ *   Schema cannot express — the converter runs with `unrepresentable: "throw"`.
+ * @example
+ * ```ts
+ * import { defineCatalog } from "@nubbin/core";
+ * import { z } from "zod";
+ *
+ * const liveBandSchema = z.object({
+ *   label: z.string(),
+ *   items: z.array(z.object({ text: z.string(), at: z.string() })),
+ * });
+ *
+ * export const catalog = defineCatalog({
+ *   LiveBand: {
+ *     schema: liveBandSchema,
+ *     defaults: { label: "On now", items: [] },
+ *     ui: { fields: { items: { data: { revalidate: 60 } } } },
+ *   },
+ * });
+ * ```
  */
 declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
 
 /**
- * The report as a CI log reads it. `checked` leads every line, including the passing one: a run
- * that found no pointers and a run that cleared eight are the same word otherwise, and the first
- * of those is a gate certifying nothing.
+ * Renders a report as the plain text a CI log or a terminal wants — one line when everything
+ * cleared, otherwise a counted heading followed by each broken route with its blocks indented
+ * beneath it. The count of pointers examined opens both forms, so a run that read an empty store
+ * cannot be mistaken for a run that cleared a full one.
+ *
+ * @param report - A report from `checkCompatibility`, or any value of that shape.
+ * @returns The whole report as one string, newline-separated and with no trailing newline. Split
+ * it on `\n` for a logger that takes lines.
+ * @example
+ * ```ts
+ * import { checkCompatibility, formatCompatibilityReport } from "@nubbin/core";
+ *
+ * formatCompatibilityReport(checkCompatibility(live, registry));
+ * // 1 of 8 live route pointer(s) are incompatible with this registry:
+ * //   /  (artifact 4a162726)
+ * //     Hero: page needs v1, no longer in the registry
+ * ```
  */
 declare function formatCompatibilityReport(report: CompatibilityReport): string;
 
 /**
- * Moves a node into a slot: a new `DocumentVersion` with the reference taken out of whatever held
- * it — a slot or the roots — and placed in the target, the node itself untouched by reference.
+ * Moves a node into a slot: the reference is taken out of whatever held it — a slot, or the
+ * document's roots — and placed in the target slot.
+ *
+ * A move rewrites references, never the node. Reordering within one slot is a move to the same
+ * parent and slot with a new `index`.
  *
- * `index` names a position in the target slot *as it stands after the node is taken out*, which
- * is the only reading under which "move it to the end" is the slot's length. Its absence appends.
+ * @param version - The document to edit. Read, never written.
+ * @param nodeId - Id of the node to move. The document must hold it.
+ * @param toParentId - Id of the node whose slot receives it. The document must hold it, and it
+ *   may be the parent the node already sits under.
+ * @param toSlot - Slot name on that parent. A slot the parent has never filled is opened.
+ * @param index - Position in the target slot as it stands *after* the node is taken out, so the
+ *   last position is that slot's length. Omit to append.
+ * @returns A new `DocumentVersion` with the reference moved. The argument is not mutated, the
+ *   moved node is carried over by reference along with every node the edit did not touch, and
+ *   `version.version` is not bumped.
+ * @throws {NubbinError} `no-such-node` when `nodeId` or `toParentId` names a node the document
+ *   does not hold.
+ * @example
+ * ```ts
+ * // sections: [a, b, c] → aside: [a]
+ * const next = moveNode(version, "a", "stack", "aside");
  *
- * It does not refuse a move into the node's own subtree. That makes a cycle and detaches the node
- * from the roots, and `compile` refuses both by name — judging it here would be a second opinion
- * on one question, which is the division every operation in this package follows.
+ * // Reorder inside one slot: [a, b, c] → [b, c, a]
+ * const last = moveNode(version, "a", "stack", "sections", 2);
+ *
+ * // A root becomes a child, and drops out of `roots`.
+ * const nested = moveNode(version, "loose", "stack", "sections");
+ * ```
  */
 declare function moveNode(version: DocumentVersion, nodeId: string, toParentId: string, toSlot: string, index?: number): DocumentVersion;
 
 /**
- * Every refusal Nubbin throws, carrying its causes as data rather than only as prose. One class
- * for the whole surface: a consumer writes one `catch`, reads `code` or `issues`, and ships that
- * shape to whatever tooling they keep — the package neither logs nor decides what a refusal
- * means to them.
+ * Every refusal Nubbin throws, from any package, carrying its causes as data rather than only as
+ * prose. One `catch` and one `instanceof` hold the whole surface.
+ *
+ * It extends `Error`, so a handler that only ever read `.message` keeps working. `message`
+ * summarises every cause: one issue reads as itself, several read as a count and a line each.
+ *
+ * @example
+ * ```ts
+ * import { NubbinError, NubbinIssueCode, compile } from "@nubbin/core";
+ *
+ * try {
+ *   const { artifact } = compile(version, catalog, registry, "/pricing");
+ *   await store.write(artifact);
+ * } catch (error) {
+ *   if (!(error instanceof NubbinError)) throw error;
  *
- * It extends `Error`, so a handler that only ever read `.message` keeps working.
+ *   if (error.code === NubbinIssueCode.InvalidRoute) {
+ *     return rejectRoute(error.message);
+ *   }
+ *   for (const issue of error.issues) {
+ *     editor.mark(issue.at, issue.path, issue.message);
+ *   }
+ * }
+ * ```
  */
 declare class NubbinError extends Error {
     /**
@@ -372,103 +1397,274 @@ declare class NubbinError extends Error {
      * Every refusal but `compile`'s carries exactly one issue; read `issues` for the rest.
      */
     readonly code: NubbinIssue["code"];
+    /**
+     * Every cause, in the order they were found, and never empty. This is what a log, a tracker or
+     * an editing surface serializes — each issue carries its own `code`, `at` and `path`.
+     */
     readonly issues: readonly NubbinIssue[];
+    /**
+     * @param issues - The causes, first one first. `code` is taken from `issues[0]` and `message`
+     *   is a summary of all of them.
+     * @throws {Error} A plain `Error`, not a `NubbinError`, when `issues` is empty — a refusal
+     *   with no cause names nothing.
+     */
     constructor(issues: readonly NubbinIssue[]);
 }
 
 /**
- * matchKind is parsed from the route at publish, never caller-supplied. It lives in core so
- * every adapter derives it from one implementation — a second parser is free to disagree.
+ * Derives the `matchKind` for a route pointer. An `ArtifactStore` implementation calls this
+ * inside `publish` and puts the result on the pointer it writes, so the caller of `publish` never
+ * supplies one.
  *
- * The route is judged before it is classified: this is the last point before a pointer is
- * written, so an adapter that never called `compile` still cannot publish an unaddressable one.
+ * @param route - The route the pointer will address: rooted at `/`, no trailing slash except at
+ * the root itself, `[bracketed]` param segments, and `*` only as the final segment.
+ * @returns `"prefix"` for a route ending in `/*`, `"param"` for one carrying a `[bracketed]`
+ * segment, and `"exact"` for anything else — `/` included.
+ * @throws NubbinError with `code` `NubbinIssueCode.InvalidRoute` when the route is not
+ * addressable: it does not start at `/`, it trails a slash, a segment is empty or carries a
+ * character a URL path cannot, a bracketed segment names nothing, or `*` sits mid-route. The
+ * `at` on the issue is the offending route.
+ * @example
+ * ```ts
+ * import { parseMatchKind } from "@nubbin/core";
+ *
+ * parseMatchKind("/about"); // "exact"
+ * parseMatchKind("/guides/[city]"); // "param"
+ * parseMatchKind("/collections/*"); // "prefix"
+ * parseMatchKind("pricing"); // throws NubbinError — a route starts at the root
+ * ```
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
 /**
- * Throws the one-cause refusal that almost every surface raises, so a site says what it refuses
- * and why in one line rather than assembling an issue array around it.
+ * Throws the one-cause refusal almost every Nubbin surface raises, in one line rather than
+ * assembling an issue array around it.
+ *
+ * It is exported so a consumer's own adapter — a store, a schema adapter, a framework binding —
+ * refuses in the shape core does, and a caller's single `catch (error) { if (error instanceof
+ * NubbinError) … }` still holds everything.
  *
- * `compile` is the exception and builds its own `NubbinError`, because it collects: an author
- * fixing six problems should see six, not the first.
+ * @param code - Which refusal this is, from `NubbinIssueCode`.
+ * @param message - Prose for a person, naming the specific value or id at fault.
+ * @param at - What the refusal concerns: a node id, a block name, or a route. Omit it and the
+ *   issue carries no `at` key at all, rather than one set to `undefined`.
+ * @returns Never. It always throws, so a caller needs no `return` after it for TypeScript's
+ *   narrowing to hold past the call.
+ * @throws {NubbinError} A `NubbinError` — always, carrying exactly one issue built from the
+ *   arguments.
  *
- * Returns `never`, so a caller need not `return` after it for the narrowing to hold.
+ * @example An adapter refusing in the same shape core does
+ * ```ts
+ * import { NubbinIssueCode, refuse } from "@nubbin/core";
+ * import type { Artifact } from "@nubbin/core";
+ *
+ * async function requireArtifact(hash: string): Promise<Artifact> {
+ *   const stored = await store.read(hash);
+ *   // `refuse` returns never, so `stored` is narrowed to Artifact below.
+ *   if (stored === null) {
+ *     refuse(NubbinIssueCode.ArtifactNotStored, `no artifact stored at ${hash}`, hash);
+ *   }
+ *   return stored;
+ * }
+ * ```
  */
 declare function refuse(code: NubbinIssue["code"], message: string, at?: string): never;
 
 /**
- * Removes a node and everything beneath it: a new `DocumentVersion` with the subtree gone, the
- * reference to it dropped from whatever held it, and every other node untouched by reference.
+ * Removes a node and everything beneath it, and drops the reference to it from whatever held it
+ * — a slot, or the document's roots.
+ *
+ * The cascade follows slot references from the named node, so a descendant that a second slot
+ * elsewhere also references goes with it.
  *
- * It cascades because removing a section means removing what was in it. Left behind, the children
- * would be unreachable — which `compile` already refuses — so the alternative is a document that
- * cannot compile until an author deletes each orphan by hand.
+ * @param version - The document to edit. Read, never written.
+ * @param nodeId - Id of the node to remove. The document must hold it.
+ * @returns A new `DocumentVersion` with the subtree gone from `elements` and its id gone from
+ *   every slot and from `roots`. The argument is not mutated, `version.version` is not bumped,
+ *   and every surviving node the edit did not touch is carried over by reference.
+ * @throws {NubbinError} `no-such-node` when `nodeId` names a node the document does not hold.
+ * @example
+ * ```ts
+ * // stack → [a, b]; a → [a1, a2]
+ * const next = removeNode(version, "a");
+ * next.elements.a1; // undefined — the cascade reached it
+ * next.elements.stack?.slots?.sections; // ["b"]
  *
- * Whether the slot it emptied is now below its `min` is `compile`'s judgment, as it is for every
- * other operation here.
+ * // Removing the last root leaves an empty document, which `compile` refuses as `no-roots`.
+ * removeNode(version, "stack").roots; // []
+ * ```
  */
 declare function removeNode(version: DocumentVersion, nodeId: string): DocumentVersion;
 
 /**
- * The inline emphasis a span may carry. Semantic, never stylistic, and closed: a construct
- * outside this set is added as a member deliberately, not smuggled in as markup.
+ * The inline emphasis a span may carry. A mark outside this set is a validation issue at the
+ * mark's own path, never a dropped value.
  */
 type RichTextMark = "strong" | "em" | "code";
-/** The block kinds rich text is built from. Closed for the same reason the marks are. */
+/** The block kinds rich text is built from. A renderer maps each to an element it chooses. */
 type RichTextBlockKind = "paragraph" | "listItem";
 /** A run of text and what is true of it. Inert: nothing here is parsed or evaluated at render. */
 interface RichTextSpan {
+    /** The literal text of the run. Never markup — a tag here renders as the characters typed. */
     text: string;
+    /** Emphasis over the whole run. Absent and empty mean the same thing: plain text. */
     marks?: readonly RichTextMark[];
+    /** Link target for the whole run. Absent leaves the run unlinked. */
     href?: string;
 }
 /** One block of a rich-text value: its kind, and the ordered spans it reads as. */
 interface RichTextBlock {
+    /** What the block is, which decides how a renderer wraps its spans. */
     kind: RichTextBlockKind;
+    /** The runs the block reads as, in order. An empty array is a block with no text. */
     spans: readonly RichTextSpan[];
 }
-/** An ordered array of blocks — the whole value a `richText()` field holds. */
+/**
+ * An ordered array of blocks — the whole value a `richText()` field holds. An empty array is a
+ * valid empty document.
+ */
 type RichText = readonly RichTextBlock[];
 
 /**
- * A schema `core` hand-writes rather than one a validator brings. Narrower than
- * `StandardSchemaV1` in the two ways that matter to a consumer hosting it: `validate` is
- * synchronous, which compile requires anyway, and the JSON Schema converter is always there,
- * so the studio can read the field tree without testing for it.
+ * A schema `core` writes itself, such as the one `richText()` returns. It satisfies both
+ * `StandardSchemaV1` and `StandardJSONSchemaV1`, so a block, a catalog entry or an adapter takes
+ * it wherever either is accepted — while guaranteeing two things the interfaces leave open.
+ *
+ * @typeParam Value - What a successful `validate` yields, and so what a component receives for
+ *   the field.
  */
 interface StandardDataSchema<Value> {
+    /** The Standard Schema entry point. Everything a consumer reads about the schema is here. */
     readonly "~standard": {
+        /** The Standard Schema version this shape speaks. */
         readonly version: 1;
+        /** Who wrote the schema, for a tool reporting where a field's rules came from. */
         readonly vendor: string;
+        /**
+         * Checks a value, synchronously — never a promise, which is what `compile` requires of any
+         * schema it runs. A refusal comes back as `issues` on the result rather than as a throw.
+         */
         readonly validate: (value: unknown) => StandardSchemaV1.Result<Value>;
+        /**
+         * The JSON Schema projection, present rather than optional — what `zodAdapter.describe`
+         * walks to reach the field tree an editing surface renders.
+         */
         readonly jsonSchema: StandardJSONSchemaV1.Converter;
     };
 }
 
 /**
- * The rich-text field type: an ordered array of blocks, each an ordered array of inert spans,
- * over closed mark and kind sets. Nothing in the value is parsed or evaluated at render, so an
- * artifact carrying it is as inert as one carrying a string.
+ * The schema for a rich-text field: an ordered array of blocks, each an ordered array of spans,
+ * over closed mark and kind sets. Declare it as a block's field to give an author inline
+ * emphasis and links without giving anyone markup.
+ *
+ * Nothing in the value is parsed or evaluated at render, so an artifact carrying one is as inert
+ * as an artifact carrying a string. Both sets and both object shapes are closed: a key the shape
+ * does not declare is reported, never dropped.
+ *
+ * @returns The rich-text schema — a `StandardDataSchema<RichText>` whose `~standard.validate` is
+ *   synchronous and whose `~standard.jsonSchema` converter is always present. Every call yields
+ *   the same value, so a registry keyed by schema identity sees one schema across every field
+ *   that declares it.
+ * @example
+ * ```ts
+ * const schema = richText();
+ *
+ * const body: RichText = [
+ *   {
+ *     kind: "paragraph",
+ *     spans: [
+ *       { text: "How we keep that safe is on our " },
+ *       { text: "security page", href: "/security" },
+ *       { text: ", not in a PDF.", marks: ["strong", "em"] },
+ *     ],
+ *   },
+ *   { kind: "listItem", spans: [{ text: "encrypted", marks: ["code"] }] },
+ * ];
+ *
+ * schema["~standard"].validate(body).issues; // undefined
+ *
+ * // A refusal names the offending path rather than throwing.
+ * schema["~standard"].validate([{ kind: "heading", spans: [] }]).issues;
+ * // [{ path: [0, "kind"], message: 'unknown kind "heading"; expected one of paragraph, listItem' }]
+ * ```
+ * @example
+ * Seating it in a validator that will not hold a foreign schema — zod rejects one inside an
+ * object shape, so the field is carried as `unknown` and `core` decides what is valid:
+ * ```ts
+ * const spec = richText();
  *
- * A call rather than a bare value, so a field declaration reads the way the rest of a block's
- * schema does and so options can arrive without changing call sites that pass none. A scan for
- * this call finds every rich-text field in a registry.
+ * const body = z
+ *   .unknown()
+ *   .check((ctx) => {
+ *     for (const issue of spec["~standard"].validate(ctx.value).issues ?? []) {
+ *       ctx.issues.push({ code: "custom", message: issue.message, input: ctx.value });
+ *     }
+ *   })
+ *   .pipe(z.custom<RichText>())
+ *   .meta(spec["~standard"].jsonSchema.input({ target: "draft-2020-12" }));
+ * ```
  */
 declare function richText(): StandardDataSchema<RichText>;
 
-/** Copy-on-write down one dotted path. Paths address object fields only; `[]` has no single target. */
+/**
+ * Writes a value at a dotted path in a plain object, copying every level the path passes
+ * through. `setNodeProp` edits props with it, and the renderer fills a resolved hole with it.
+ *
+ * The path is `.`-separated object keys — `price`, `cta.link.label`. Each segment names a key,
+ * never an array index: a numeric segment is the key `"0"`, and an array met on the way down is
+ * refused rather than descended into. The last segment is written wholesale, so an array or
+ * object already sitting there is replaced entire. An intermediate key holding no object — a
+ * missing key, `null`, a string, a number — is replaced by a fresh object.
+ *
+ * @param target - The object to write into. Read, never written.
+ * @param path - Dotted path of object keys. Every segment must be non-empty and free of `[]`.
+ * @param value - What to write at the path. Anything, including `undefined`.
+ * @returns A new record with the path written. The argument is not mutated: each level along
+ *   the path is a fresh object, and every key off the path is carried over by reference.
+ * @throws {NubbinError} `path-not-addressable` when a segment is empty, carries `[]` — which
+ *   names every member of an array rather than one target — or descends into an array.
+ * @example
+ * ```ts
+ * setAtPath({ title: "T", price: 0 }, "price", 42); // { title: "T", price: 42 }
+ * setAtPath({}, "cta.price", 42); // { cta: { price: 42 } } — intermediates are created
+ * setAtPath({ cta: "text" }, "cta.price", 42); // { cta: { price: 42 } } — the string is gone
+ * setAtPath({ items: ["a", "b"] }, "items", ["c"]); // { items: ["c"] } — a whole-field write
+ *
+ * setAtPath({ items: ["a", "b"] }, "items.0", "X"); // throws — `items` is an array
+ * setAtPath({}, "items[].price", 42); // throws — `[]` names every member, not one
+ * ```
+ */
 declare function setAtPath(target: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
 
 /**
- * The first document operation: a new `DocumentVersion` with one prop set on one node,
- * copy-on-write, every other node untouched by reference. It lives beside `compile` so any
- * caller — an editor, a script, an agent — writes a document the same way
- * ([#134](https://github.com/effekt/nubbin/issues/134)).
+ * Sets one prop on one node, addressed by a dotted path into that node's `props`.
+ *
+ * The value is not checked against the block's schema here. `compile` reports a bad one as an
+ * `invalid-props` issue at the offending path, so a document may hold a value its schema
+ * rejects between two edits that end valid.
+ *
+ * @param version - The document to edit. Read, never written.
+ * @param nodeId - Id of the node whose props are rewritten. The document must hold it.
+ * @param path - Dotted path into the node's props, in the syntax `setAtPath` defines:
+ *   `headline`, `cta.label`. Missing intermediate objects are created; `items[]` is refused.
+ * @param value - What to write at that path. Unvalidated, and replaces whatever sits there.
+ * @returns A new `DocumentVersion` carrying a new `Node` for `nodeId` with the prop set. The
+ *   argument is not mutated, `version.version`, `roots`, `meta` and `createdAt` are untouched,
+ *   and every other node is carried over by reference.
+ * @throws {NubbinError} `no-such-node` when `nodeId` names a node the document does not hold;
+ *   `path-not-addressable` when the path names no single field — an `items[]` segment, an empty
+ *   segment, or a descent into an array.
+ * @example
+ * ```ts
+ * const next = setNodeProp(version, "hero", "headline", "After");
+ * next.elements.hero?.props.headline; // "After"
  *
- * It does not validate the value (that is `compile`'s job at the next compile) and does not
- * bump `version` — appending a version is the authoring store's concern
- * ([#11](https://github.com/effekt/nubbin/issues/11)), not a property of one edit.
+ * // A dotted path reaches inside an object prop, leaving its siblings in place.
+ * setNodeProp(version, "hero", "cta.label", "Buy").elements.hero?.props.cta;
+ * // { label: "Buy", href: "/" }
+ * ```
  */
 declare function setNodeProp(version: DocumentVersion, nodeId: string, path: string, value: unknown): DocumentVersion;
 
-export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, type CompileResult, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, NubbinError, type NubbinIssue, NubbinIssueCode, type Registry, type RichText, type RichTextBlock, type RichTextBlockKind, type RichTextMark, type RichTextSpan, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type StandardDataSchema, type UnknownProps, addNode, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, moveNode, parseMatchKind, refuse, removeNode, richText, setAtPath, setNodeProp, zodAdapter };
+export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, type CompileResult, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, NubbinError, type NubbinIssue, NubbinIssueCode, type PointerMove, type Registry, type RichText, type RichTextBlock, type RichTextBlockKind, type RichTextMark, type RichTextSpan, type RollbackCheck, type RouteIncompatibility, type RoutePointer, type SchemaAdapter, type SlotConstraint, type StandardDataSchema, type UnknownProps, addNode, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, moveNode, parseMatchKind, refuse, removeNode, richText, setAtPath, setNodeProp, zodAdapter };