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

package/dist/index.d.ts

@@ -45,41 +45,9 @@ interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component =
     component: Component;
     /** Bumped when the schema changes incompatibly. */
     version: number;
-    /** A deprecated block still resolves; the studio hides it from the palette. */
-    status?: "active" | "deprecated";
     slots: Record<string, SlotConstraint>;
 }
 
-/** How a field's value resolves at render. Absent means static — the value freezes into props. */
-type FieldHintData = "request" | {
-    revalidate: number;
-};
-/**
- * Studio treatment for one schema path. Open by design: control resolution ranks testers over
- * these hints, so a consumer can carry keys core does not read.
- */
-interface FieldHint {
-    label?: string;
-    control?: string;
-    data?: FieldHintData;
-}
-interface BlockUi {
-    /** Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail registration. */
-    fields?: Record<string, FieldHint>;
-}
-interface BlockDocs {
-    summary?: string;
-    usage?: string;
-}
-/** Serializable data only — what the studio and CI read. Components live in the registry. */
-interface CatalogEntry {
-    schema: unknown;
-    ui?: BlockUi;
-    defaults?: UnknownProps;
-    docs?: BlockDocs;
-}
-type Catalog = Record<string, CatalogEntry>;
-
 interface DocumentMeta {
     title: string;
     description?: string;
@@ -108,6 +76,46 @@ interface DocumentVersion {
     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.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ * `index` inserts; its absence appends.
+ */
+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. */
+type FieldHintData = {
+    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.
+ */
+interface FieldHint {
+    data?: FieldHintData;
+}
+interface BlockUi {
+    /** Keyed by schema path (`title`, `cta.label`, `items[].icon`). Unresolvable paths fail registration. */
+    fields?: Record<string, FieldHint>;
+}
+/** Serializable data only — what the studio and CI read. Components live in the registry. */
+interface CatalogEntry {
+    schema: unknown;
+    ui?: BlockUi;
+    defaults?: UnknownProps;
+}
+type Catalog = Record<string, CatalogEntry>;
+
 /** Field path → how the field resolves at render. */
 type Holes = Record<string, FieldHintData>;
 /** Resolved — no lookups, no dangling references possible. */
@@ -126,7 +134,6 @@ interface Artifact {
     route: string;
     documentId: string;
     documentVersion: number;
-    registryFingerprint: string;
     /** What this was compiled against — only the blocks the document uses. */
     blockVersions: Record<string, number>;
     tree: ArtifactNode[];
@@ -156,21 +163,6 @@ interface ArtifactStore {
     unpublish(route: string): Promise<void>;
 }
 
-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. */
-    path: string;
-    code: CompileIssueCode;
-    message: string;
-}
-
-/** Carries every issue found in one pass, so an author fixing six problems sees six. */
-declare class CompileError extends Error {
-    readonly issues: readonly CompileIssue[];
-    constructor(issues: readonly CompileIssue[]);
-}
-
 /** One route pointer and the artifact it names, as an adapter read them. */
 interface LiveRoute {
     pointer: RoutePointer;
@@ -209,8 +201,6 @@ interface CompatibilityReport {
 interface Registry {
     get(name: string): Block | undefined;
     names(): string[];
-    /** Hash of every block name and version. Nothing else. */
-    fingerprint(): string;
 }
 
 /**
@@ -238,17 +228,96 @@ type RollbackCheck = {
  */
 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.
+ *
+ * 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.
+ *
+ * Closed on purpose. A new refusal is a new member here, which is what makes the reference page
+ * listing them checkable against this file.
+ */
+declare const NubbinIssueCode: {
+    readonly BlockVersion: "block-version";
+    readonly SlotBounds: "slot-bounds";
+    readonly SlotAllowUnknown: "slot-allow-unknown";
+    readonly DuplicateBlockName: "duplicate-block-name";
+    readonly InvalidDefaults: "invalid-defaults";
+    readonly HintPathUnresolvable: "hint-path-unresolvable";
+    readonly HintNotAddressable: "hint-not-addressable";
+    readonly NotStandardSchema: "not-standard-schema";
+    readonly NoJsonSchema: "no-json-schema";
+    readonly NoRoots: "no-roots";
+    readonly UnknownBlock: "unknown-block";
+    readonly DanglingChild: "dangling-child";
+    readonly Cycle: "cycle";
+    readonly Unreachable: "unreachable";
+    readonly SlotNotAllowed: "slot-not-allowed";
+    readonly SlotMin: "slot-min";
+    readonly SlotMax: "slot-max";
+    readonly InvalidProps: "invalid-props";
+    readonly UnknownProp: "unknown-prop";
+    readonly NoSuchNode: "no-such-node";
+    readonly DuplicateNodeId: "duplicate-node-id";
+    readonly PathNotAddressable: "path-not-addressable";
+    readonly InvalidRoute: "invalid-route";
+    readonly BlockNotLoaded: "block-not-loaded";
+    readonly NoHoleResolver: "no-hole-resolver";
+    readonly NotOneHostElement: "not-one-host-element";
+    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.
+ *
+ * `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.
+ *
+ * `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.
+ */
+interface NubbinIssue {
+    code: NubbinIssueCode;
+    message: string;
+    /** What it concerns: a node id, a block name, or a route. */
+    at?: string;
+    /** Where within that: a dotted prop path, `slots.items`, or `block`. */
+    path?: string;
+}
+
+/**
+ * What `compile` produces: the artifact, and everything it has to say about the document that
+ * did not stop it producing one.
+ *
+ * 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.
+ */
+interface CompileResult {
+    artifact: Artifact;
+    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.
+ *
+ * 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.
  */
-declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): Artifact;
+declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): CompileResult;
 
 /**
- * Sorted by name so registration order cannot change the fingerprint, and built from name and
- * version alone so unrelated edits — a slot constraint, a deprecation — do not invalidate every
- * artifact compiled before them.
- *
  * Slot `allow` lists resolve once the whole array is ingested, so a block may name a sibling
  * registered after it.
  */
@@ -275,12 +344,71 @@ declare function defineCatalog(entries: Record<string, CatalogEntry>): Catalog;
  */
 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.
+ *
+ * `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.
+ *
+ * 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.
+ */
+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.
+ *
+ * It extends `Error`, so a handler that only ever read `.message` keeps working.
+ */
+declare class NubbinError 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.
+     */
+    readonly code: NubbinIssue["code"];
+    readonly issues: readonly NubbinIssue[];
+    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.
+ *
+ * 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.
  */
 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.
+ *
+ * `compile` is the exception and builds its own `NubbinError`, because it collects: an author
+ * fixing six problems should see six, not the first.
+ *
+ * Returns `never`, so a caller need not `return` after it for the narrowing to hold.
+ */
+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.
+ *
+ * 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.
+ *
+ * Whether the slot it emptied is now below its `min` is `compile`'s judgment, as it is for every
+ * other operation here.
+ */
+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.
@@ -343,4 +471,4 @@ declare function setAtPath(target: Record<string, unknown>, path: string, value:
  */
 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 };
+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 };

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);
@@ -211,17 +358,18 @@ function denormalize(version, resolve) {
 }
 
 // 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
@@ -234,11 +382,34 @@ 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("[]")) {
-    throw new Error(`path "${path}" is not addressable`);
+    refuse(NubbinIssueCode.PathNotAddressable, `path "${path}" is not addressable`, path);
   }
   return { head, tail };
 }
@@ -283,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;
@@ -301,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"
     );
   }
@@ -317,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 };
@@ -328,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"
         }
       ]
@@ -343,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
@@ -379,6 +557,16 @@ function pushCycleFrame(stack, state, version, id) {
   stack.push({ id, edges: slotEdges(node), next: 0 });
 }
 
+// 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 = [];
@@ -395,12 +583,14 @@ function findCyclesFrom(version, root, state) {
     }
     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);
     }
@@ -422,12 +612,14 @@ function findDanglingChildren(version) {
   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}`
+          )
+        );
       }
     }
   }
@@ -439,9 +631,9 @@ function findRootIssues(version) {
   if (version.roots.length === 0) {
     return [
       {
-        nodeId: "",
+        at: "",
         path: "roots",
-        code: "no-roots",
+        code: NubbinIssueCode.NoRoots,
         message: "a document needs at least one root, and this one names none"
       }
     ];
@@ -449,9 +641,9 @@ function findRootIssues(version) {
   return version.roots.flatMap(
     (root) => version.elements[root] === void 0 ? [
       {
-        nodeId: root,
+        at: root,
         path: "roots",
-        code: "dangling-child",
+        code: NubbinIssueCode.DanglingChild,
         message: `root "${root}" has no matching element`
       }
     ] : []
@@ -466,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(", ")}`
     });
   }
@@ -480,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}`
@@ -506,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}"`
       }
     ];
@@ -535,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 = 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];
-    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
@@ -566,9 +771,9 @@ 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",
+      code: NubbinIssueCode.Unreachable,
       message: `no slot reaches "${node.id}" from any root`
     });
   }
@@ -590,26 +795,26 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.1.0-rc.6";
+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
@@ -624,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(", ")}`
     );
   }
@@ -635,26 +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`);
+    refuse(NubbinIssueCode.BlockVersion, "version must be an integer of 1 or more", name);
   }
 }
 
@@ -662,7 +867,7 @@ function assertBlockVersion(name, version) {
 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}`);
     }
   }
 }
@@ -679,8 +884,10 @@ 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
     );
   }
 }
@@ -691,16 +898,20 @@ function assertDataHintAddressable(blockName, fields) {
   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`
+      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) {
-      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`
+      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);
@@ -712,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
@@ -750,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";
   }
@@ -761,6 +1008,20 @@ 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) {
@@ -914,21 +1175,26 @@ function setAtPath(target, path, value) {
     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, 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,
@@ -936,7 +1202,10 @@ export {
   defineBlock,
   defineCatalog,
   formatCompatibilityReport,
+  moveNode,
   parseMatchKind,
+  refuse,
+  removeNode,
   richText,
   setAtPath,
   setNodeProp,

package/package.json

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