@nubbin/core 0.1.0-rc.5 → 0.1.0-rc.7

package/dist/index.js

@@ -1,3 +1,80 @@
+// src/NubbinIssueCode.ts
+var NubbinIssueCode = {
+  // Registration — a block, catalog or registry the developer wrote cannot be used as written.
+  BlockVersion: "block-version",
+  SlotBounds: "slot-bounds",
+  SlotAllowUnknown: "slot-allow-unknown",
+  DuplicateBlockName: "duplicate-block-name",
+  InvalidDefaults: "invalid-defaults",
+  HintPathUnresolvable: "hint-path-unresolvable",
+  HintNotAddressable: "hint-not-addressable",
+  // Schema — what the consumer brought does not answer the one door core reads a schema through.
+  NotStandardSchema: "not-standard-schema",
+  NoJsonSchema: "no-json-schema",
+  // Structure — the document's graph cannot become a tree.
+  NoRoots: "no-roots",
+  UnknownBlock: "unknown-block",
+  DanglingChild: "dangling-child",
+  Cycle: "cycle",
+  Unreachable: "unreachable",
+  SlotNotAllowed: "slot-not-allowed",
+  SlotMin: "slot-min",
+  SlotMax: "slot-max",
+  // Props — the values a node carries, judged against the block's schema.
+  InvalidProps: "invalid-props",
+  UnknownProp: "unknown-prop",
+  // Document operations — the caller named something the document does not hold.
+  NoSuchNode: "no-such-node",
+  DuplicateNodeId: "duplicate-node-id",
+  PathNotAddressable: "path-not-addressable",
+  InvalidRoute: "invalid-route",
+  // Render — the artifact and the registry serving it disagree.
+  BlockNotLoaded: "block-not-loaded",
+  NoHoleResolver: "no-hole-resolver",
+  NotOneHostElement: "not-one-host-element",
+  // Store — a write the store cannot honour.
+  ArtifactNotStored: "artifact-not-stored"
+};
+
+// src/summariseIssues.ts
+function summariseIssues(issues) {
+  const lines = issues.map(
+    (issue) => issue.at === void 0 ? `${issue.message} [${issue.code}]` : `${issue.at} [${issue.code}]: ${issue.message}`
+  );
+  const only = lines[0];
+  if (lines.length === 1 && only !== void 0) {
+    return only;
+  }
+  return `Refused with ${issues.length} issue(s):
+${lines.join("\n")}`;
+}
+
+// src/NubbinError.ts
+var NubbinError = class extends Error {
+  /**
+   * The first issue's code, so the common case reads as
+   * `error.code === NubbinIssueCode.UnknownProp` with no array to index and no string to typo.
+   * Every refusal but `compile`'s carries exactly one issue; read `issues` for the rest.
+   */
+  code;
+  issues;
+  constructor(issues) {
+    const first = issues[0];
+    if (first === void 0) {
+      throw new Error("NubbinError needs an issue \u2014 a refusal with no cause names nothing");
+    }
+    super(summariseIssues(issues));
+    this.name = "NubbinError";
+    this.code = first.code;
+    this.issues = issues;
+  }
+};
+
+// src/refuse.ts
+function refuse(code, message, at) {
+  throw new NubbinError([at === void 0 ? { code, message } : { code, message, at }]);
+}
+
 // src/adapters/isStandardJsonSchemaCapable.ts
 function isStandardJsonSchemaCapable(value) {
   if (typeof value !== "object" || value === null || !("~standard" in value)) return false;
@@ -16,7 +93,10 @@ var OPTIONS = {
 };
 function projectJsonSchema(schema) {
   if (!isStandardJsonSchemaCapable(schema)) {
-    throw new Error("Schema does not expose the Standard JSON Schema converter (spec >= 1.1)");
+    refuse(
+      NubbinIssueCode.NoJsonSchema,
+      "Schema does not expose the Standard JSON Schema converter (spec >= 1.1)"
+    );
   }
   return schema["~standard"].jsonSchema.input(OPTIONS);
 }
@@ -106,17 +186,47 @@ var zodAdapter = {
   }
 };
 
-// src/CompileError.ts
-var CompileError = class extends Error {
-  issues;
-  constructor(issues) {
-    const summary = issues.map((issue) => `${issue.nodeId} ${issue.path} [${issue.code}]: ${issue.message}`).join("\n");
-    super(`Compile failed with ${issues.length} issue(s):
-${summary}`);
-    this.name = "CompileError";
-    this.issues = issues;
+// src/requireNode.ts
+function requireNode(version, nodeId) {
+  const node = version.elements[nodeId];
+  if (node === void 0) {
+    refuse(
+      NubbinIssueCode.NoSuchNode,
+      `no node "${nodeId}" in document "${version.documentId}"`,
+      nodeId
+    );
   }
-};
+  return node;
+}
+
+// src/withElements.ts
+function withElements(version, ...nodes) {
+  const elements = { ...version.elements };
+  for (const node of nodes) {
+    elements[node.id] = node;
+  }
+  return { ...version, elements };
+}
+
+// src/withSlotChild.ts
+function withSlotChild(node, slot, childId, index) {
+  const children = [...node.slots?.[slot] ?? []];
+  children.splice(index ?? children.length, 0, childId);
+  return { ...node, slots: { ...node.slots, [slot]: children } };
+}
+
+// src/addNode.ts
+function addNode(version, parentId, slot, node, index) {
+  const parent = requireNode(version, parentId);
+  if (version.elements[node.id] !== void 0) {
+    refuse(
+      NubbinIssueCode.DuplicateNodeId,
+      `document "${version.documentId}" already holds a node "${node.id}"`,
+      node.id
+    );
+  }
+  return withElements(version, withSlotChild(parent, slot, node.id, index), node);
+}
 
 // src/checkRollback.ts
 function checkRollback(artifact, registry) {
@@ -152,6 +262,43 @@ function checkCompatibility(live, registry) {
   return { checked: live.length, compatible: incompatible.length === 0, incompatible };
 }
 
+// src/routeSegmentIssue.ts
+var SEGMENT = /^[A-Za-z0-9\-._~%!$&'()+,;=:@]+$/;
+var PARAM = /^\[[A-Za-z0-9_-]+\]$/;
+function routeSegmentIssue(segment, isLast) {
+  if (segment === "") {
+    return "a segment names nothing";
+  }
+  if (segment === "*") {
+    return isLast ? void 0 : "a prefix star is only the final segment";
+  }
+  if (segment.startsWith("[") || segment.endsWith("]")) {
+    return PARAM.test(segment) ? void 0 : `"${segment}" is not a param segment`;
+  }
+  return SEGMENT.test(segment) ? void 0 : `"${segment}" carries a character a route cannot`;
+}
+
+// src/assertValidRoute.ts
+function assertValidRoute(route) {
+  const unaddressable = (why) => refuse(NubbinIssueCode.InvalidRoute, `route "${route}" is not addressable: ${why}`, route);
+  if (!route.startsWith("/")) {
+    unaddressable("a route starts at the root, with a slash");
+  }
+  if (route === "/") {
+    return;
+  }
+  if (route.endsWith("/")) {
+    unaddressable("a trailing slash would key a second pointer to one page");
+  }
+  const segments = route.slice(1).split("/");
+  for (const [index, segment] of segments.entries()) {
+    const issue = routeSegmentIssue(segment, index === segments.length - 1);
+    if (issue !== void 0) {
+      unaddressable(issue);
+    }
+  }
+}
+
 // src/artifactNodeOf.ts
 function artifactNodeOf(node, resolve) {
   const { props, holes } = resolve(node);
@@ -191,7 +338,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();
@@ -204,22 +351,25 @@ 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
-var OFFSET_BASIS = 2166136261;
-var PRIME = 16777619;
+var OFFSET_BASIS = 14695981039346656037n;
+var PRIME = 1099511628211n;
+var MASK = 0xffffffffffffffffn;
 var HEX_RADIX = 16;
-var HEX_WIDTH = 8;
+var HEX_WIDTH = 16;
 function fnv1a(input) {
   let hash = OFFSET_BASIS;
   for (let index = 0; index < input.length; index += 1) {
-    hash ^= input.charCodeAt(index);
-    hash = Math.imul(hash, PRIME);
+    hash ^= BigInt(input.charCodeAt(index));
+    hash = hash * PRIME & MASK;
   }
-  return (hash >>> 0).toString(HEX_RADIX).padStart(HEX_WIDTH, "0");
+  return hash.toString(HEX_RADIX).padStart(HEX_WIDTH, "0");
 }
 
 // src/hashArtifact.ts
@@ -232,18 +382,66 @@ function hashArtifact(artifact) {
   return fnv1a(JSON.stringify(artifact, sortKeys));
 }
 
+// src/isUnknownProps.ts
+function isUnknownProps(value) {
+  if (typeof value !== "object") return false;
+  return value !== null && !Array.isArray(value);
+}
+
+// src/droppedKeyPaths.ts
+function droppedKeyPaths(written, parsed, prefix = "") {
+  const dropped = [];
+  for (const [key, value] of Object.entries(written)) {
+    const path = prefix === "" ? key : `${prefix}.${key}`;
+    if (!Object.hasOwn(parsed, key)) {
+      dropped.push(path);
+      continue;
+    }
+    const kept = parsed[key];
+    if (isUnknownProps(value) && isUnknownProps(kept)) {
+      dropped.push(...droppedKeyPaths(value, kept, path));
+    }
+  }
+  return dropped;
+}
+
+// src/splitPath.ts
+function splitPath(path) {
+  const [head, ...tail] = path.split(".");
+  if (head === void 0 || head === "" || head.includes("[]")) {
+    refuse(NubbinIssueCode.PathNotAddressable, `path "${path}" is not addressable`, path);
+  }
+  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 };
 }
@@ -256,12 +454,6 @@ function formatIssuePath(path) {
   ).join(".");
 }
 
-// src/isUnknownProps.ts
-function isUnknownProps(value) {
-  if (typeof value !== "object") return false;
-  return value !== null && !Array.isArray(value);
-}
-
 // src/isStandardSchema.ts
 function isStandardSchema(value) {
   if (typeof value !== "object" || value === null) return false;
@@ -274,11 +466,15 @@ function isStandardSchema(value) {
 // src/standardValidate.ts
 function standardValidate(schema, value) {
   if (!isStandardSchema(schema)) {
-    throw new Error("Schema does not implement Standard Schema (`~standard.validate`)");
+    refuse(
+      NubbinIssueCode.NotStandardSchema,
+      "Schema does not implement Standard Schema (`~standard.validate`)"
+    );
   }
   const result = schema["~standard"].validate(value);
   if (result instanceof Promise) {
-    throw new Error(
+    refuse(
+      NubbinIssueCode.NotStandardSchema,
       "Schema validates asynchronously; compile and registration require synchronous validation"
     );
   }
@@ -290,9 +486,9 @@ function validateNodeProps(node, schema) {
   const result = standardValidate(schema, node.props);
   if (result.issues !== void 0) {
     const issues = result.issues.map((issue) => ({
-      nodeId: node.id,
+      at: node.id,
       path: formatIssuePath(issue.path),
-      code: "invalid-props",
+      code: NubbinIssueCode.InvalidProps,
       message: issue.message
     }));
     return { issues };
@@ -301,9 +497,9 @@ function validateNodeProps(node, schema) {
     return {
       issues: [
         {
-          nodeId: node.id,
+          at: node.id,
           path: "",
-          code: "invalid-props",
+          code: NubbinIssueCode.InvalidProps,
           message: "block props must parse to an object"
         }
       ]
@@ -316,20 +512,29 @@ function validateNodeProps(node, schema) {
 function resolveAllProps(version, catalog) {
   const resolved = /* @__PURE__ */ new Map();
   const issues = [];
+  const reported = [];
   for (const node of Object.values(version.elements)) {
     const entry = catalog[node.block];
     if (entry === void 0) {
       const message = `"${node.block}" has no catalog entry, so its props cannot be validated`;
-      issues.push({ code: "unknown-block", message, nodeId: node.id, path: "block" });
+      issues.push({ code: NubbinIssueCode.UnknownBlock, message, at: node.id, path: "block" });
       continue;
     }
     const { value, issues: propIssues } = validateNodeProps(node, entry.schema);
     issues.push(...propIssues);
     if (value !== void 0) {
+      for (const path of droppedKeyPaths(node.props, value)) {
+        reported.push({
+          code: NubbinIssueCode.UnknownProp,
+          message: `"${path}" is not a field of ${node.block}, so the schema did not keep it`,
+          at: node.id,
+          path
+        });
+      }
       resolved.set(node.id, partitionProps(value, entry.ui));
     }
   }
-  return { resolved, issues };
+  return { resolved, issues, reported };
 }
 
 // src/usedBlockVersions.ts
@@ -352,12 +557,21 @@ 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/toIssue.ts
+function toIssue(code, message, at, path) {
+  return {
+    code,
+    message,
+    ...at === void 0 ? {} : { at },
+    ...path === void 0 ? {} : { path }
+  };
+}
+
+// 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;
@@ -369,12 +583,14 @@ function findCycles(version) {
     }
     frame.next += 1;
     if (state.get(edge.childId) === "visiting") {
-      issues.push({
-        nodeId: frame.id,
-        path: `slots.${edge.slot}`,
-        code: "cycle",
-        message: `"${frame.id}" reaches back to "${edge.childId}", so the graph cannot flatten into a tree`
-      });
+      issues.push(
+        toIssue(
+          NubbinIssueCode.Cycle,
+          `"${frame.id}" reaches back to "${edge.childId}", so the graph cannot flatten into a tree`,
+          frame.id,
+          `slots.${edge.slot}`
+        )
+      );
     } else if (!state.has(edge.childId)) {
       pushCycleFrame(stack, state, version, edge.childId);
     }
@@ -382,32 +598,58 @@ 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) {
-        issues.push({
-          nodeId: node.id,
-          path: `slots.${edge.slot}`,
-          code: "dangling-child",
-          message: `child "${edge.childId}" has no matching element`
-        });
+        issues.push(
+          toIssue(
+            NubbinIssueCode.DanglingChild,
+            `child "${edge.childId}" has no matching element`,
+            node.id,
+            `slots.${edge.slot}`
+          )
+        );
       }
     }
   }
   return issues;
 }
 
+// src/findRootIssues.ts
+function findRootIssues(version) {
+  if (version.roots.length === 0) {
+    return [
+      {
+        at: "",
+        path: "roots",
+        code: NubbinIssueCode.NoRoots,
+        message: "a document needs at least one root, and this one names none"
+      }
+    ];
+  }
+  return version.roots.flatMap(
+    (root) => version.elements[root] === void 0 ? [
+      {
+        at: root,
+        path: "roots",
+        code: NubbinIssueCode.DanglingChild,
+        message: `root "${root}" has no matching element`
+      }
+    ] : []
+  );
+}
+
 // src/disallowedChildren.ts
 function disallowedChildren(parent, path, childIds, allow, version) {
   if (allow === void 0) return [];
@@ -416,9 +658,9 @@ function disallowedChildren(parent, path, childIds, allow, version) {
     const child = version.elements[childId];
     if (child === void 0 || allow.includes(child.block)) continue;
     issues.push({
-      nodeId: childId,
+      at: childId,
       path,
-      code: "slot-not-allowed",
+      code: NubbinIssueCode.SlotNotAllowed,
       message: `"${child.block}" is not allowed in ${path} of "${parent.block}"; allowed: ${allow.join(", ")}`
     });
   }
@@ -430,20 +672,20 @@ function slotBoundIssues(parentId, path, count, constraint) {
   const { min, max } = constraint;
   const bounds = [
     {
-      code: "slot-min",
+      code: NubbinIssueCode.SlotMin,
       limit: min,
       breached: min !== void 0 && count < min,
       sense: "at least"
     },
     {
-      code: "slot-max",
+      code: NubbinIssueCode.SlotMax,
       limit: max,
       breached: max !== void 0 && count > max,
       sense: "at most"
     }
   ];
   return bounds.filter((bound) => bound.breached).map((bound) => ({
-    nodeId: parentId,
+    at: parentId,
     path,
     code: bound.code,
     message: `${path} holds ${count} of ${bound.sense} ${bound.limit}`
@@ -456,9 +698,9 @@ function slotIssuesAt(parent, slotName, childIds, constraint, version) {
   if (constraint === void 0) {
     return [
       {
-        nodeId: parent.id,
+        at: parent.id,
         path,
-        code: "slot-not-allowed",
+        code: NubbinIssueCode.SlotNotAllowed,
         message: `"${parent.block}" declares no slot "${slotName}"`
       }
     ];
@@ -485,28 +727,41 @@ function findSlotViolations(version, registry) {
 // src/findUnknownBlocks.ts
 function findUnknownBlocks(version, registry) {
   return Object.values(version.elements).filter((node) => registry.get(node.block) === void 0).map((node) => ({
-    nodeId: node.id,
+    at: node.id,
     path: "block",
-    code: "unknown-block",
+    code: NubbinIssueCode.UnknownBlock,
     message: `"${node.block}" is not a registered block`
   }));
 }
 
-// src/reachableIds.ts
-function reachableIds(version) {
-  const seen = /* @__PURE__ */ new Set([version.root]);
-  const queue = [version.root];
-  while (queue.length > 0) {
-    const id = queue.pop();
-    const node = id === void 0 ? void 0 : version.elements[id];
-    if (node === void 0) continue;
+// src/idsReachableFrom.ts
+function idsReachableFrom(elements, seeds) {
+  const found = /* @__PURE__ */ new Set();
+  const pending = [...seeds];
+  while (pending.length > 0) {
+    const id = pending.pop();
+    const node = id === void 0 ? void 0 : elements[id];
+    if (node === void 0) {
+      continue;
+    }
     for (const edge of slotEdges(node)) {
-      if (seen.has(edge.childId)) continue;
-      seen.add(edge.childId);
-      queue.push(edge.childId);
+      if (found.has(edge.childId)) {
+        continue;
+      }
+      found.add(edge.childId);
+      pending.push(edge.childId);
     }
   }
-  return seen;
+  return found;
+}
+
+// src/reachableIds.ts
+function reachableIds(version) {
+  const reached = idsReachableFrom(version.elements, version.roots);
+  for (const root of version.roots) {
+    reached.add(root);
+  }
+  return reached;
 }
 
 // src/findUnreachable.ts
@@ -516,10 +771,10 @@ function findUnreachable(version) {
   for (const node of Object.values(version.elements)) {
     if (reached.has(node.id)) continue;
     issues.push({
-      nodeId: node.id,
+      at: node.id,
       path: "",
-      code: "unreachable",
-      message: `no slot reaches "${node.id}" from the root`
+      code: NubbinIssueCode.Unreachable,
+      message: `no slot reaches "${node.id}" from any root`
     });
   }
   return issues;
@@ -527,8 +782,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),
@@ -537,26 +795,26 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.1.0-rc.5";
+var NUBBIN_VERSION = "0.1.0-rc.7";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
+  assertValidRoute(route);
   const structural = validateStructure(version, registry);
-  if (structural.length > 0) throw new CompileError(structural);
-  const { resolved, issues } = resolveAllProps(version, catalog);
-  if (issues.length > 0) throw new CompileError(issues);
+  if (structural.length > 0) throw new NubbinError(structural);
+  const { resolved, issues, reported } = resolveAllProps(version, catalog);
+  if (issues.length > 0) throw new NubbinError(issues);
   const tree = denormalize(version, (node) => resolved.get(node.id) ?? { props: {}, holes: {} });
   const content = {
     route,
     documentId: version.documentId,
     documentVersion: version.version,
-    registryFingerprint: registry.fingerprint(),
     blockVersions: usedBlockVersions(version, registry),
     tree,
     meta: version.meta,
     compiledWith: NUBBIN_VERSION
   };
-  return { ...content, hash: hashArtifact(content) };
+  return { artifact: { ...content, hash: hashArtifact(content) }, issues: reported };
 }
 
 // src/unknownAllowEntries.ts
@@ -571,7 +829,8 @@ function assertSlotAllows(blocks) {
   const known = new Set(blocks.map((block) => block.name));
   const unresolved = blocks.flatMap((block) => unknownAllowEntries(block, known));
   if (unresolved.length > 0) {
-    throw new Error(
+    refuse(
+      NubbinIssueCode.SlotAllowUnknown,
       `Slot allow lists name ${unresolved.join(", ")}, which no registered block defines. Registered blocks: ${[...known].sort().join(", ")}`
     );
   }
@@ -582,37 +841,25 @@ function createRegistry(blocks) {
   const byName = /* @__PURE__ */ new Map();
   for (const block of blocks) {
     if (byName.has(block.name)) {
-      throw new Error(
-        `Duplicate block name "${block.name}" \u2014 names are the identity nodes resolve through`
+      refuse(
+        NubbinIssueCode.DuplicateBlockName,
+        `Duplicate block name "${block.name}" \u2014 names are the identity nodes resolve through`,
+        block.name
       );
     }
     byName.set(block.name, block);
   }
   assertSlotAllows([...byName.values()]);
-  const signature = [...byName.values()].map((block) => `${block.name}@${block.version}`).sort().join("\n");
-  const fingerprint = fnv1a(signature);
   return {
     get: (name) => byName.get(name),
-    names: () => [...byName.keys()],
-    fingerprint: () => fingerprint
+    names: () => [...byName.keys()]
   };
 }
 
 // src/assertBlockVersion.ts
 function assertBlockVersion(name, version) {
   if (!Number.isInteger(version) || version < 1) {
-    throw new Error(`${name}: version must be an integer of 1 or more`);
-  }
-}
-
-// 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}`);
-    }
+    refuse(NubbinIssueCode.BlockVersion, "version must be an integer of 1 or more", name);
   }
 }
 
@@ -620,7 +867,7 @@ function assertMigrateKeys(name, version, migrate) {
 function assertSlotBounds(name, slots) {
   for (const [slot, { min, max }] of Object.entries(slots)) {
     if (min !== void 0 && max !== void 0 && min > max) {
-      throw new Error(`${name}: slot "${slot}" has min ${min} above max ${max}`);
+      refuse(NubbinIssueCode.SlotBounds, `min ${min} is above max ${max}`, `${name} slots.${slot}`);
     }
   }
 }
@@ -629,7 +876,6 @@ 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;
 }
 
@@ -638,20 +884,37 @@ function resolveHintPaths(blockName, schema, fields) {
   const known = new Set(zodAdapter.describe(schema).map((field) => field.path));
   const unresolved = Object.keys(fields).filter((path) => !known.has(path));
   if (unresolved.length > 0) {
-    throw new Error(
-      `${blockName}: ui.fields references ${unresolved.map((p) => `"${p}"`).join(", ")}, which the schema does not define. Known paths: ${[...known].join(", ")}`
+    refuse(
+      NubbinIssueCode.HintPathUnresolvable,
+      `ui.fields references ${unresolved.map((p) => `"${p}"`).join(", ")}, which the schema does not define. Known paths: ${[...known].join(", ")}`,
+      blockName
     );
   }
 }
 
 // src/assertDataHintAddressable.ts
 function assertDataHintAddressable(blockName, fields) {
+  const seen = [];
   for (const [path, hint] of Object.entries(fields)) {
-    if (hint.data !== void 0 && path.includes("[]")) {
-      throw new Error(
-        `${blockName}: ui.fields["${path}"] sets \`data\`, but a hole cannot address an array member \u2014 "[]" has no single target`
+    if (hint.data === void 0) continue;
+    if (path.includes("[]")) {
+      refuse(
+        NubbinIssueCode.HintNotAddressable,
+        `ui.fields["${path}"] sets \`data\`, but a hole cannot address an array member \u2014 "[]" has no single target`,
+        blockName
+      );
+    }
+    const nested = seen.find(
+      (other) => path.startsWith(`${other}.`) || other.startsWith(`${path}.`)
+    );
+    if (nested !== void 0) {
+      refuse(
+        NubbinIssueCode.HintNotAddressable,
+        `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`,
+        blockName
       );
     }
+    seen.push(path);
   }
 }
 
@@ -660,7 +923,11 @@ function assertValidDefaults(blockName, schema, defaults) {
   const result = standardValidate(schema, defaults);
   if (result.issues === void 0) return;
   const detail = result.issues.map((issue) => `${formatIssuePath(issue.path)}: ${issue.message}`).join("; ");
-  throw new Error(`${blockName}: defaults do not satisfy the schema \u2014 ${detail}`);
+  refuse(
+    NubbinIssueCode.InvalidDefaults,
+    `defaults do not satisfy the schema \u2014 ${detail}`,
+    blockName
+  );
 }
 
 // src/defineCatalog.ts
@@ -698,8 +965,40 @@ function formatCompatibilityReport(report) {
   return [summary, ...report.incompatible.map(formatRouteIncompatibility)].join("\n");
 }
 
+// src/withoutSlotChildren.ts
+function withoutSlotChildren(node, removed) {
+  const entries = Object.entries(node.slots ?? {});
+  const holdsRemoved = entries.some(([, children]) => children.some((id) => removed.has(id)));
+  if (!holdsRemoved) {
+    return node;
+  }
+  const slots = Object.fromEntries(
+    entries.map(([slot, children]) => [slot, children.filter((id) => !removed.has(id))])
+  );
+  return { ...node, slots };
+}
+
+// src/detachIds.ts
+function detachIds(version, ids) {
+  const elements = {};
+  for (const [id, node] of Object.entries(version.elements)) {
+    elements[id] = withoutSlotChildren(node, ids);
+  }
+  return { ...version, roots: version.roots.filter((id) => !ids.has(id)), elements };
+}
+
+// src/moveNode.ts
+function moveNode(version, nodeId, toParentId, toSlot, index) {
+  requireNode(version, nodeId);
+  requireNode(version, toParentId);
+  const detached = detachIds(version, /* @__PURE__ */ new Set([nodeId]));
+  const parent = requireNode(detached, toParentId);
+  return withElements(detached, withSlotChild(parent, toSlot, nodeId, index));
+}
+
 // src/parseMatchKind.ts
 function parseMatchKind(route) {
+  assertValidRoute(route);
   if (route.endsWith("/*")) {
     return "prefix";
   }
@@ -709,31 +1008,193 @@ function parseMatchKind(route) {
   return "exact";
 }
 
+// src/removeNode.ts
+function removeNode(version, nodeId) {
+  requireNode(version, nodeId);
+  const removed = idsReachableFrom(version.elements, [nodeId]).add(nodeId);
+  const detached = detachIds(version, removed);
+  const elements = {};
+  for (const [id, node] of Object.entries(detached.elements)) {
+    if (!removed.has(id)) {
+      elements[id] = node;
+    }
+  }
+  return { ...detached, elements };
+}
+
+// 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, ...rest] = path.split(".");
-  if (head === void 0 || head === "" || head.includes("[]")) {
-    throw new Error(`path "${path}" is not addressable`);
-  }
-  if (rest.length === 0) {
+  const { head, tail } = splitPath(path);
+  if (tail.length === 0) {
     return { ...target, [head]: value };
   }
   const child = target[head];
+  if (Array.isArray(child)) {
+    refuse(
+      NubbinIssueCode.PathNotAddressable,
+      `path "${path}" descends into an array at "${head}", which addresses no field`,
+      path
+    );
+  }
   const base = typeof child === "object" && child !== null ? child : {};
-  return { ...target, [head]: setAtPath(base, rest.join("."), value) };
+  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 } };
+  const node = requireNode(version, nodeId);
+  return withElements(version, { ...node, props: setAtPath(node.props, path, value) });
 }
 export {
-  CompileError,
+  NubbinError,
+  NubbinIssueCode,
+  addNode,
   checkCompatibility,
   checkRollback,
   compile,
@@ -741,7 +1202,11 @@ export {
   defineBlock,
   defineCatalog,
   formatCompatibilityReport,
+  moveNode,
   parseMatchKind,
+  refuse,
+  removeNode,
+  richText,
   setAtPath,
   setNodeProp,
   zodAdapter