@nubbin/core 0.1.0-rc.4 → 0.1.0-rc.6

package/dist/index.d.ts

@@ -1,4 +1,25 @@
-import { StandardSchemaV1 } from '@standard-schema/spec';
+import { StandardSchemaV1, StandardJSONSchemaV1 } from '@standard-schema/spec';
+
+type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
+interface FieldNode {
+    /** Dotted path from the schema root, with `[]` for array members: `cta.label`, `items[].title`. */
+    path: string;
+    kind: FieldKind;
+    optional: boolean;
+    /** Present only for `enum`. */
+    members?: readonly string[];
+}
+interface SchemaAdapter {
+    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.
+ */
+declare const zodAdapter: SchemaAdapter;
 
 type UnknownProps = Record<string, unknown>;
 /**
@@ -27,8 +48,6 @@ interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component =
     /** A deprecated block still resolves; the studio hides it from the palette. */
     status?: "active" | "deprecated";
     slots: Record<string, SlotConstraint>;
-    /** Same-node prop reshaping only. It cannot touch slots, or split or delete a block. */
-    migrate?: Record<number, (props: UnknownProps) => UnknownProps>;
 }
 
 /** How a field's value resolves at render. Absent means static — the value freezes into props. */
@@ -78,7 +97,11 @@ interface Node {
 interface DocumentVersion {
     documentId: string;
     version: number;
-    root: string;
+    /**
+     * 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).
+     */
+    roots: readonly string[];
     elements: Record<string, Node>;
     meta: DocumentMeta;
     createdAt: string;
@@ -133,7 +156,7 @@ interface ArtifactStore {
     unpublish(route: string): Promise<void>;
 }
 
-type CompileIssueCode = "unknown-block" | "dangling-child" | "cycle" | "unreachable" | "slot-not-allowed" | "slot-min" | "slot-max" | "invalid-props";
+type CompileIssueCode = "no-roots" | "unknown-block" | "dangling-child" | "cycle" | "unreachable" | "slot-not-allowed" | "slot-min" | "slot-max" | "invalid-props";
 interface CompileIssue {
     nodeId: string;
     /** Where in the node the problem sits: `block`, `slots.items`, or a dotted prop path. */
@@ -148,6 +171,41 @@ declare class CompileError extends Error {
     constructor(issues: readonly CompileIssue[]);
 }
 
+/** One route pointer and the artifact it names, as an adapter read them. */
+interface LiveRoute {
+    pointer: RoutePointer;
+    /** `null` when the store holds no artifact at the pointer's hash — a pointer into nothing. */
+    artifact: Artifact | null;
+}
+/** One block's version delta between what a live artifact needs and what is registered now. */
+interface BlockDrift {
+    block: string;
+    /** The version the artifact was compiled against. */
+    live: number;
+    /** The version registered now — `null` when the registry no longer holds the block at all. */
+    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.
+ */
+type RouteIncompatibility = {
+    route: string;
+    hash: string;
+    reason: "unreadable-artifact";
+} | {
+    route: string;
+    hash: string;
+    reason: "block-drift";
+    drifted: BlockDrift[];
+};
+/** The verdict over every live pointer. `checked` is reported so a run over nothing cannot read as a pass. */
+interface CompatibilityReport {
+    checked: number;
+    compatible: boolean;
+    incompatible: RouteIncompatibility[];
+}
+
 interface Registry {
     get(name: string): Block | undefined;
     names(): string[];
@@ -155,6 +213,17 @@ interface Registry {
     fingerprint(): 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.
+ *
+ * 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.
+ */
+declare function checkCompatibility(live: readonly LiveRoute[], registry: Registry): CompatibilityReport;
+
 type RollbackCheck = {
     compatible: true;
 } | {
@@ -188,8 +257,7 @@ 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 slot that no composition could satisfy, or a migration keyed to
- * a version this block never reaches.
+ * type system cannot make — a version below 1, or a slot that no composition could satisfy.
  */
 declare function defineBlock<Schema extends StandardSchemaV1, Component>(block: Block<Schema, Component>): Block<Schema, Component>;
 
@@ -200,18 +268,12 @@ declare function defineBlock<Schema extends StandardSchemaV1, Component>(block:
  */
 declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
 
-type FieldKind = "string" | "number" | "boolean" | "enum" | "array" | "object" | "union" | "unknown";
-interface FieldNode {
-    /** Dotted path from the schema root, with `[]` for array members: `cta.label`, `items[].title`. */
-    path: string;
-    kind: FieldKind;
-    optional: boolean;
-    /** Present only for `enum`. */
-    members?: readonly string[];
-}
-interface SchemaAdapter {
-    describe(schema: unknown): FieldNode[];
-}
+/**
+ * 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.
+ */
+declare function formatCompatibilityReport(report: CompatibilityReport): string;
 
 /**
  * matchKind is parsed from the route at publish, never caller-supplied. It lives in core so
@@ -219,4 +281,66 @@ interface SchemaAdapter {
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
-export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDocs, type BlockUi, type Catalog, type CatalogEntry, CompileError, type CompileIssue, type CompileIssueCode, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type Manifest, type Node, type Registry, type RollbackCheck, type RoutePointer, type SchemaAdapter, type SlotConstraint, type UnknownProps, checkRollback, compile, createRegistry, defineBlock, defineCatalog, parseMatchKind };
+/**
+ * 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.
+ */
+type RichTextMark = "strong" | "em" | "code";
+/** The block kinds rich text is built from. Closed for the same reason the marks are. */
+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 {
+    text: string;
+    marks?: readonly RichTextMark[];
+    href?: string;
+}
+/** One block of a rich-text value: its kind, and the ordered spans it reads as. */
+interface RichTextBlock {
+    kind: RichTextBlockKind;
+    spans: readonly RichTextSpan[];
+}
+/** An ordered array of blocks — the whole value a `richText()` field holds. */
+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.
+ */
+interface StandardDataSchema<Value> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => StandardSchemaV1.Result<Value>;
+        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.
+ *
+ * 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.
+ */
+declare function richText(): StandardDataSchema<RichText>;
+
+/** Copy-on-write down one dotted path. Paths address object fields only; `[]` has no single target. */
+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)).
+ *
+ * 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.
+ */
+declare function setNodeProp(version: DocumentVersion, nodeId: string, path: string, value: unknown): DocumentVersion;
+
+export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDocs, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, CompileError, type CompileIssue, type CompileIssueCode, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, 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, checkCompatibility, checkRollback, compile, createRegistry, defineBlock, defineCatalog, formatCompatibilityReport, parseMatchKind, richText, setAtPath, setNodeProp, zodAdapter };

package/dist/index.js

@@ -1,3 +1,111 @@
+// src/adapters/isStandardJsonSchemaCapable.ts
+function isStandardJsonSchemaCapable(value) {
+  if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
+  const props = value["~standard"];
+  if (typeof props !== "object" || props === null || !("jsonSchema" in props)) return false;
+  const converter = props.jsonSchema;
+  if (typeof converter !== "object" || converter === null || !("input" in converter)) return false;
+  return typeof converter.input === "function";
+}
+
+// src/adapters/projectJsonSchema.ts
+var OPTIONS = {
+  target: "draft-2020-12",
+  /** zod's option name: a type JSON Schema cannot express throws here, at registration. */
+  libraryOptions: { unrepresentable: "throw" }
+};
+function projectJsonSchema(schema) {
+  if (!isStandardJsonSchemaCapable(schema)) {
+    throw new Error("Schema does not expose the Standard JSON Schema converter (spec >= 1.1)");
+  }
+  return schema["~standard"].jsonSchema.input(OPTIONS);
+}
+
+// src/adapters/kindOfJsonSchema.ts
+function kindOfJsonSchema(node) {
+  if (Array.isArray(node.enum)) return "enum";
+  if (Array.isArray(node.oneOf) || Array.isArray(node.anyOf)) return "union";
+  switch (node.type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+
+// src/adapters/fieldNodeAt.ts
+function fieldNodeAt(path, node, optional) {
+  const kind = kindOfJsonSchema(node);
+  if (kind === "enum" && Array.isArray(node.enum)) {
+    return { path, kind, optional, members: node.enum.map(String) };
+  }
+  return { path, kind, optional };
+}
+
+// src/adapters/isJsonSchemaNode.ts
+function isJsonSchemaNode(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/adapters/walkArrayItems.ts
+function walkArrayItems(arrayNode, path, descend) {
+  if (!isJsonSchemaNode(arrayNode.items)) return [];
+  const itemPath = `${path}[]`;
+  return [fieldNodeAt(itemPath, arrayNode.items, false), ...descend(arrayNode.items, itemPath)];
+}
+
+// src/adapters/walkObjectProperties.ts
+function walkObjectProperties(objectNode, basePath, descend) {
+  const { properties, required } = objectNode;
+  if (!isJsonSchemaNode(properties)) return [];
+  const requiredNames = Array.isArray(required) ? required : [];
+  const fields = [];
+  for (const [name, child] of Object.entries(properties)) {
+    if (!isJsonSchemaNode(child)) continue;
+    const path = basePath === "" ? name : `${basePath}.${name}`;
+    fields.push(fieldNodeAt(path, child, !requiredNames.includes(name)));
+    fields.push(...descend(child, path));
+  }
+  return fields;
+}
+
+// src/adapters/walkUnionBranches.ts
+function walkUnionBranches(unionNode, path, descend) {
+  const branches = [unionNode.oneOf, unionNode.anyOf].filter(Array.isArray).flat();
+  return branches.flatMap((branch) => isJsonSchemaNode(branch) ? descend(branch, path) : []);
+}
+
+// src/adapters/walkJsonSchema.ts
+function walkJsonSchema(node, basePath) {
+  const kind = kindOfJsonSchema(node);
+  if (kind === "object") return walkObjectProperties(node, basePath, walkJsonSchema);
+  if (kind === "array") return walkArrayItems(node, basePath, walkJsonSchema);
+  if (kind === "union") return walkUnionBranches(node, basePath, walkJsonSchema);
+  return [];
+}
+
+// src/adapters/zodAdapter.ts
+var zodAdapter = {
+  describe(schema) {
+    const fields = walkJsonSchema(projectJsonSchema(schema), "");
+    const seen = /* @__PURE__ */ new Set();
+    return fields.filter((field) => {
+      if (seen.has(field.path)) return false;
+      seen.add(field.path);
+      return true;
+    });
+  }
+};
+
 // src/CompileError.ts
 var CompileError = class extends Error {
   issues;
@@ -16,6 +124,34 @@ function checkRollback(artifact, registry) {
   return drifted.length === 0 ? { compatible: true } : { compatible: false, drifted };
 }
 
+// src/describeDrift.ts
+function describeDrift(artifact, registry, drifted) {
+  return drifted.flatMap((block) => {
+    const live = artifact.blockVersions[block];
+    return live === void 0 ? [] : [{ block, live, registered: registry.get(block)?.version ?? null }];
+  });
+}
+
+// src/checkCompatibility.ts
+function checkCompatibility(live, registry) {
+  const incompatible = live.flatMap(({ pointer, artifact }) => {
+    const { route, hash } = pointer;
+    if (artifact === null) {
+      return [{ route, hash, reason: "unreadable-artifact" }];
+    }
+    const check = checkRollback(artifact, registry);
+    return check.compatible ? [] : [
+      {
+        route,
+        hash,
+        reason: "block-drift",
+        drifted: describeDrift(artifact, registry, check.drifted)
+      }
+    ];
+  });
+  return { checked: live.length, compatible: incompatible.length === 0, incompatible };
+}
+
 // src/artifactNodeOf.ts
 function artifactNodeOf(node, resolve) {
   const { props, holes } = resolve(node);
@@ -55,7 +191,7 @@ function wireSlots(version, built) {
 
 // src/denormalize.ts
 function denormalize(version, resolve) {
-  const pending = [version.root];
+  const pending = [...version.roots];
   const built = /* @__PURE__ */ new Map();
   while (pending.length > 0) {
     const id = pending.pop();
@@ -68,8 +204,10 @@ function denormalize(version, resolve) {
     }
   }
   wireSlots(version, built);
-  const root = built.get(version.root);
-  return root === void 0 ? [] : [root];
+  return version.roots.flatMap((id) => {
+    const root = built.get(id);
+    return root === void 0 ? [] : [root];
+  });
 }
 
 // src/fnv1a.ts
@@ -96,18 +234,43 @@ function hashArtifact(artifact) {
   return fnv1a(JSON.stringify(artifact, sortKeys));
 }
 
+// src/splitPath.ts
+function splitPath(path) {
+  const [head, ...tail] = path.split(".");
+  if (head === void 0 || head === "" || head.includes("[]")) {
+    throw new Error(`path "${path}" is not addressable`);
+  }
+  return { head, tail };
+}
+
+// src/takeAtPath.ts
+function takeAtPath(target, path) {
+  const { head, tail } = splitPath(path);
+  if (!Object.hasOwn(target, head)) return { rest: target, taken: false };
+  if (tail.length === 0) {
+    const remaining = { ...target };
+    delete remaining[head];
+    return { rest: remaining, taken: true };
+  }
+  const child = target[head];
+  if (typeof child !== "object" || child === null || Array.isArray(child)) {
+    return { rest: target, taken: false };
+  }
+  const inner = takeAtPath(child, tail.join("."));
+  if (!inner.taken) return { rest: target, taken: false };
+  return { rest: { ...target, [head]: inner.rest }, taken: true };
+}
+
 // src/partitionProps.ts
 function partitionProps(validated, hints) {
-  const props = {};
+  let props = { ...validated };
   const holes = {};
-  const fields = hints?.fields ?? {};
-  for (const [key, value] of Object.entries(validated)) {
-    const data = fields[key]?.data;
-    if (data === void 0) {
-      props[key] = value;
-    } else {
-      holes[key] = data;
-    }
+  for (const [path, hint] of Object.entries(hints?.fields ?? {})) {
+    if (hint.data === void 0) continue;
+    const { rest, taken } = takeAtPath(props, path);
+    if (!taken) continue;
+    props = rest;
+    holes[path] = hint.data;
   }
   return { props, holes };
 }
@@ -216,12 +379,11 @@ function pushCycleFrame(stack, state, version, id) {
   stack.push({ id, edges: slotEdges(node), next: 0 });
 }
 
-// src/findCycles.ts
-function findCycles(version) {
-  const state = /* @__PURE__ */ new Map();
+// src/findCyclesFrom.ts
+function findCyclesFrom(version, root, state) {
   const stack = [];
   const issues = [];
-  pushCycleFrame(stack, state, version, version.root);
+  pushCycleFrame(stack, state, version, root);
   while (stack.length > 0) {
     const frame = stack.at(-1);
     if (frame === void 0) break;
@@ -246,17 +408,17 @@ function findCycles(version) {
   return issues;
 }
 
+// src/findCycles.ts
+function findCycles(version) {
+  const state = /* @__PURE__ */ new Map();
+  return version.roots.flatMap(
+    (root) => state.has(root) ? [] : findCyclesFrom(version, root, state)
+  );
+}
+
 // src/findDanglingChildren.ts
 function findDanglingChildren(version) {
   const issues = [];
-  if (version.elements[version.root] === void 0) {
-    issues.push({
-      nodeId: version.root,
-      path: "root",
-      code: "dangling-child",
-      message: `root "${version.root}" has no matching element`
-    });
-  }
   for (const node of Object.values(version.elements)) {
     for (const edge of slotEdges(node)) {
       if (version.elements[edge.childId] === void 0) {
@@ -272,6 +434,30 @@ function findDanglingChildren(version) {
   return issues;
 }
 
+// src/findRootIssues.ts
+function findRootIssues(version) {
+  if (version.roots.length === 0) {
+    return [
+      {
+        nodeId: "",
+        path: "roots",
+        code: "no-roots",
+        message: "a document needs at least one root, and this one names none"
+      }
+    ];
+  }
+  return version.roots.flatMap(
+    (root) => version.elements[root] === void 0 ? [
+      {
+        nodeId: root,
+        path: "roots",
+        code: "dangling-child",
+        message: `root "${root}" has no matching element`
+      }
+    ] : []
+  );
+}
+
 // src/disallowedChildren.ts
 function disallowedChildren(parent, path, childIds, allow, version) {
   if (allow === void 0) return [];
@@ -358,8 +544,8 @@ function findUnknownBlocks(version, registry) {
 
 // src/reachableIds.ts
 function reachableIds(version) {
-  const seen = /* @__PURE__ */ new Set([version.root]);
-  const queue = [version.root];
+  const seen = new Set(version.roots);
+  const queue = [...version.roots];
   while (queue.length > 0) {
     const id = queue.pop();
     const node = id === void 0 ? void 0 : version.elements[id];
@@ -383,7 +569,7 @@ function findUnreachable(version) {
       nodeId: node.id,
       path: "",
       code: "unreachable",
-      message: `no slot reaches "${node.id}" from the root`
+      message: `no slot reaches "${node.id}" from any root`
     });
   }
   return issues;
@@ -391,8 +577,11 @@ function findUnreachable(version) {
 
 // src/validateStructure.ts
 function validateStructure(version, registry) {
+  const rootIssues = findRootIssues(version);
+  if (version.roots.length === 0) return rootIssues;
   return [
     ...findUnknownBlocks(version, registry),
+    ...rootIssues,
     ...findDanglingChildren(version),
     ...findCycles(version),
     ...findUnreachable(version),
@@ -401,7 +590,7 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.1.0-rc.4";
+var NUBBIN_VERSION = "0.1.0-rc.6";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -469,17 +658,6 @@ function assertBlockVersion(name, version) {
   }
 }
 
-// src/assertMigrateKeys.ts
-var FIRST_MIGRATABLE_VERSION = 2;
-function assertMigrateKeys(name, version, migrate) {
-  for (const key of Object.keys(migrate ?? {})) {
-    const target = Number(key);
-    if (target < FIRST_MIGRATABLE_VERSION || target > version) {
-      throw new Error(`${name}: migrate key ${key} is outside the reachable range 2..${version}`);
-    }
-  }
-}
-
 // src/assertSlotBounds.ts
 function assertSlotBounds(name, slots) {
   for (const [slot, { min, max }] of Object.entries(slots)) {
@@ -493,118 +671,9 @@ function assertSlotBounds(name, slots) {
 function defineBlock(block) {
   assertBlockVersion(block.name, block.version);
   assertSlotBounds(block.name, block.slots);
-  assertMigrateKeys(block.name, block.version, block.migrate);
   return block;
 }
 
-// src/adapters/isStandardJsonSchemaCapable.ts
-function isStandardJsonSchemaCapable(value) {
-  if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
-  const props = value["~standard"];
-  if (typeof props !== "object" || props === null || !("jsonSchema" in props)) return false;
-  const converter = props.jsonSchema;
-  if (typeof converter !== "object" || converter === null || !("input" in converter)) return false;
-  return typeof converter.input === "function";
-}
-
-// src/adapters/projectJsonSchema.ts
-var OPTIONS = {
-  target: "draft-2020-12",
-  /** zod's option name: a type JSON Schema cannot express throws here, at registration. */
-  libraryOptions: { unrepresentable: "throw" }
-};
-function projectJsonSchema(schema) {
-  if (!isStandardJsonSchemaCapable(schema)) {
-    throw new Error("Schema does not expose the Standard JSON Schema converter (spec >= 1.1)");
-  }
-  return schema["~standard"].jsonSchema.input(OPTIONS);
-}
-
-// src/adapters/kindOfJsonSchema.ts
-function kindOfJsonSchema(node) {
-  if (Array.isArray(node.enum)) return "enum";
-  if (Array.isArray(node.oneOf) || Array.isArray(node.anyOf)) return "union";
-  switch (node.type) {
-    case "string":
-      return "string";
-    case "number":
-    case "integer":
-      return "number";
-    case "boolean":
-      return "boolean";
-    case "array":
-      return "array";
-    case "object":
-      return "object";
-    default:
-      return "unknown";
-  }
-}
-
-// src/adapters/fieldNodeAt.ts
-function fieldNodeAt(path, node, optional) {
-  const kind = kindOfJsonSchema(node);
-  if (kind === "enum" && Array.isArray(node.enum)) {
-    return { path, kind, optional, members: node.enum.map(String) };
-  }
-  return { path, kind, optional };
-}
-
-// src/adapters/isJsonSchemaNode.ts
-function isJsonSchemaNode(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-// src/adapters/walkArrayItems.ts
-function walkArrayItems(arrayNode, path, descend) {
-  if (!isJsonSchemaNode(arrayNode.items)) return [];
-  const itemPath = `${path}[]`;
-  return [fieldNodeAt(itemPath, arrayNode.items, false), ...descend(arrayNode.items, itemPath)];
-}
-
-// src/adapters/walkObjectProperties.ts
-function walkObjectProperties(objectNode, basePath, descend) {
-  const { properties, required } = objectNode;
-  if (!isJsonSchemaNode(properties)) return [];
-  const requiredNames = Array.isArray(required) ? required : [];
-  const fields = [];
-  for (const [name, child] of Object.entries(properties)) {
-    if (!isJsonSchemaNode(child)) continue;
-    const path = basePath === "" ? name : `${basePath}.${name}`;
-    fields.push(fieldNodeAt(path, child, !requiredNames.includes(name)));
-    fields.push(...descend(child, path));
-  }
-  return fields;
-}
-
-// src/adapters/walkUnionBranches.ts
-function walkUnionBranches(unionNode, path, descend) {
-  const branches = [unionNode.oneOf, unionNode.anyOf].filter(Array.isArray).flat();
-  return branches.flatMap((branch) => isJsonSchemaNode(branch) ? descend(branch, path) : []);
-}
-
-// src/adapters/walkJsonSchema.ts
-function walkJsonSchema(node, basePath) {
-  const kind = kindOfJsonSchema(node);
-  if (kind === "object") return walkObjectProperties(node, basePath, walkJsonSchema);
-  if (kind === "array") return walkArrayItems(node, basePath, walkJsonSchema);
-  if (kind === "union") return walkUnionBranches(node, basePath, walkJsonSchema);
-  return [];
-}
-
-// src/adapters/zodAdapter.ts
-var zodAdapter = {
-  describe(schema) {
-    const fields = walkJsonSchema(projectJsonSchema(schema), "");
-    const seen = /* @__PURE__ */ new Set();
-    return fields.filter((field) => {
-      if (seen.has(field.path)) return false;
-      seen.add(field.path);
-      return true;
-    });
-  }
-};
-
 // src/adapters/resolveHintPaths.ts
 function resolveHintPaths(blockName, schema, fields) {
   const known = new Set(zodAdapter.describe(schema).map((field) => field.path));
@@ -616,6 +685,28 @@ function resolveHintPaths(blockName, schema, fields) {
   }
 }
 
+// src/assertDataHintAddressable.ts
+function assertDataHintAddressable(blockName, fields) {
+  const seen = [];
+  for (const [path, hint] of Object.entries(fields)) {
+    if (hint.data === void 0) continue;
+    if (path.includes("[]")) {
+      throw new Error(
+        `${blockName}: ui.fields["${path}"] sets \`data\`, but a hole cannot address an array member \u2014 "[]" has no single target`
+      );
+    }
+    const nested = seen.find(
+      (other) => path.startsWith(`${other}.`) || other.startsWith(`${path}.`)
+    );
+    if (nested !== void 0) {
+      throw new Error(
+        `${blockName}: ui.fields["${nested}"] and ui.fields["${path}"] both set \`data\`, but their paths overlap \u2014 two holes over one value have no defined order of application`
+      );
+    }
+    seen.push(path);
+  }
+}
+
 // src/assertValidDefaults.ts
 function assertValidDefaults(blockName, schema, defaults) {
   const result = standardValidate(schema, defaults);
@@ -629,6 +720,7 @@ function defineCatalog(entries) {
   for (const [blockName, entry] of Object.entries(entries)) {
     if (entry.ui?.fields !== void 0) {
       resolveHintPaths(blockName, entry.schema, entry.ui.fields);
+      assertDataHintAddressable(blockName, entry.ui.fields);
     }
     if (entry.defaults !== void 0) {
       assertValidDefaults(blockName, entry.schema, entry.defaults);
@@ -637,6 +729,27 @@ function defineCatalog(entries) {
   return entries;
 }
 
+// src/formatBlockDrift.ts
+function formatBlockDrift(drift) {
+  return drift.registered === null ? `${drift.block}: page needs v${drift.live}, no longer in the registry` : `${drift.block}: page needs v${drift.live}, registry has v${drift.registered}`;
+}
+
+// src/formatRouteIncompatibility.ts
+function formatRouteIncompatibility(incompatibility) {
+  const heading = `  ${incompatibility.route}  (artifact ${incompatibility.hash})`;
+  const reasons = incompatibility.reason === "unreadable-artifact" ? ["the store holds no artifact at this hash"] : incompatibility.drifted.map(formatBlockDrift);
+  return [heading, ...reasons.map((reason) => `    ${reason}`)].join("\n");
+}
+
+// src/formatCompatibilityReport.ts
+function formatCompatibilityReport(report) {
+  if (report.compatible) {
+    return `${report.checked} live route pointer(s) checked; every one is compatible with this registry.`;
+  }
+  const summary = `${report.incompatible.length} of ${report.checked} live route pointer(s) are incompatible with this registry:`;
+  return [summary, ...report.incompatible.map(formatRouteIncompatibility)].join("\n");
+}
+
 // src/parseMatchKind.ts
 function parseMatchKind(route) {
   if (route.endsWith("/*")) {
@@ -647,12 +760,185 @@ function parseMatchKind(route) {
   }
   return "exact";
 }
+
+// src/defineStandardSchema.ts
+var STANDARD_SCHEMA_VERSION = 1;
+function defineStandardSchema(issuesOf, jsonSchemaOf) {
+  return {
+    "~standard": {
+      version: STANDARD_SCHEMA_VERSION,
+      vendor: "nubbin",
+      validate: (value) => {
+        const issues = issuesOf(value);
+        return issues.length > 0 ? { issues } : { value };
+      },
+      jsonSchema: { input: jsonSchemaOf, output: jsonSchemaOf }
+    }
+  };
+}
+
+// src/richText.constants.ts
+var RICH_TEXT_MARKS = ["strong", "em", "code"];
+var RICH_TEXT_BLOCK_KINDS = ["paragraph", "listItem"];
+var RICH_TEXT_SPAN_KEYS = ["text", "marks", "href"];
+var RICH_TEXT_BLOCK_KEYS = ["kind", "spans"];
+
+// src/isRichTextBlockKind.ts
+function isRichTextBlockKind(value) {
+  return RICH_TEXT_BLOCK_KINDS.some((kind) => kind === value);
+}
+
+// src/nestedSchemaIssues.ts
+function nestedSchemaIssues(schema, value, prefix) {
+  const result = standardValidate(schema, value);
+  if (result.issues === void 0) return [];
+  return result.issues.map((issue) => ({
+    message: issue.message,
+    path: [...prefix, ...issue.path ?? []]
+  }));
+}
+
+// src/isRichTextMark.ts
+function isRichTextMark(value) {
+  return RICH_TEXT_MARKS.some((mark) => mark === value);
+}
+
+// src/richTextMarkIssues.ts
+function richTextMarkIssues(marks) {
+  if (marks === void 0) return [];
+  if (!Array.isArray(marks)) return [{ message: "marks must be an array", path: ["marks"] }];
+  return marks.flatMap(
+    (mark, index) => isRichTextMark(mark) ? [] : [
+      {
+        message: `unknown mark ${JSON.stringify(mark)}; expected one of ${RICH_TEXT_MARKS.join(", ")}`,
+        path: ["marks", index]
+      }
+    ]
+  );
+}
+
+// src/unexpectedKeyIssues.ts
+function unexpectedKeyIssues(value, allowed) {
+  return Object.keys(value).filter((key) => !allowed.includes(key)).map((key) => ({ message: `unexpected key "${key}"`, path: [key] }));
+}
+
+// src/richTextSpanIssues.ts
+function richTextSpanIssues(value) {
+  if (!isUnknownProps(value)) return [{ message: "a span must be an object", path: [] }];
+  const issues = [];
+  if (typeof value.text !== "string") {
+    issues.push({ message: "text must be a string", path: ["text"] });
+  }
+  issues.push(...richTextMarkIssues(value.marks));
+  if (value.href !== void 0 && typeof value.href !== "string") {
+    issues.push({ message: "href must be a string", path: ["href"] });
+  }
+  issues.push(...unexpectedKeyIssues(value, RICH_TEXT_SPAN_KEYS));
+  return issues;
+}
+
+// src/richTextSpanSchema.ts
+var richTextSpanSchema = defineStandardSchema(richTextSpanIssues, () => ({
+  type: "object",
+  properties: {
+    text: { type: "string" },
+    marks: { type: "array", items: { type: "string", enum: [...RICH_TEXT_MARKS] } },
+    href: { type: "string" }
+  },
+  required: ["text"],
+  additionalProperties: false
+}));
+
+// src/richTextBlockIssues.ts
+function richTextBlockIssues(value) {
+  if (!isUnknownProps(value)) return [{ message: "a block must be an object", path: [] }];
+  const issues = [];
+  if (!isRichTextBlockKind(value.kind)) {
+    issues.push({
+      message: `unknown kind ${JSON.stringify(value.kind)}; expected one of ${RICH_TEXT_BLOCK_KINDS.join(", ")}`,
+      path: ["kind"]
+    });
+  }
+  if (Array.isArray(value.spans)) {
+    issues.push(
+      ...value.spans.flatMap(
+        (span, index) => nestedSchemaIssues(richTextSpanSchema, span, ["spans", index])
+      )
+    );
+  } else {
+    issues.push({ message: "spans must be an array", path: ["spans"] });
+  }
+  issues.push(...unexpectedKeyIssues(value, RICH_TEXT_BLOCK_KEYS));
+  return issues;
+}
+
+// src/richTextBlockSchema.ts
+var richTextBlockSchema = defineStandardSchema(
+  richTextBlockIssues,
+  (options) => ({
+    type: "object",
+    properties: {
+      kind: { type: "string", enum: [...RICH_TEXT_BLOCK_KINDS] },
+      spans: { type: "array", items: richTextSpanSchema["~standard"].jsonSchema.input(options) }
+    },
+    required: ["kind", "spans"],
+    additionalProperties: false
+  })
+);
+
+// src/richTextIssues.ts
+function richTextIssues(value) {
+  if (!Array.isArray(value)) {
+    return [{ message: "rich text must be an array of blocks", path: [] }];
+  }
+  return value.flatMap(
+    (block, index) => nestedSchemaIssues(richTextBlockSchema, block, [index])
+  );
+}
+
+// src/richTextSchema.ts
+var richTextSchema = defineStandardSchema(richTextIssues, (options) => ({
+  type: "array",
+  items: richTextBlockSchema["~standard"].jsonSchema.input(options)
+}));
+
+// src/richText.ts
+function richText() {
+  return richTextSchema;
+}
+
+// src/setAtPath.ts
+function setAtPath(target, path, value) {
+  const { head, tail } = splitPath(path);
+  if (tail.length === 0) {
+    return { ...target, [head]: value };
+  }
+  const child = target[head];
+  const base = typeof child === "object" && child !== null ? child : {};
+  return { ...target, [head]: setAtPath(base, tail.join("."), value) };
+}
+
+// src/setNodeProp.ts
+function setNodeProp(version, nodeId, path, value) {
+  const node = version.elements[nodeId];
+  if (node === void 0) {
+    throw new Error(`no node "${nodeId}" in document "${version.documentId}"`);
+  }
+  const edited = { ...node, props: setAtPath(node.props, path, value) };
+  return { ...version, elements: { ...version.elements, [nodeId]: edited } };
+}
 export {
   CompileError,
+  checkCompatibility,
   checkRollback,
   compile,
   createRegistry,
   defineBlock,
   defineCatalog,
-  parseMatchKind
+  formatCompatibilityReport,
+  parseMatchKind,
+  richText,
+  setAtPath,
+  setNodeProp,
+  zodAdapter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/core",
-  "version": "0.1.0-rc.4",
+  "version": "0.1.0-rc.6",
   "description": "The Nubbin contract: define blocks, split catalog from registry, and compile a page document into an immutable artifact.",
   "keywords": [
     "nubbin",