@nubbin/core 0.1.0-rc.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesse Wheeler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,219 @@
+import { StandardSchemaV1 } from '@standard-schema/spec';
+
+type UnknownProps = Record<string, unknown>;
+/**
+ * A block's props, derived from its schema. The whole of invariant 1 in one type: there is no
+ * second definition of a block's shape, so nothing can drift from it.
+ *
+ * `InferOutput` rather than `InferInput` because a component receives what `validate()`
+ * returned — compile freezes the validated value, so a field a transform reshaped reaches the
+ * component in its output form, not as the author typed it.
+ */
+type InferProps<Schema extends StandardSchemaV1> = StandardSchemaV1.InferOutput<Schema>;
+interface SlotConstraint {
+    /** Block names permitted here. Omitted means any registered block. */
+    allow?: readonly string[];
+    min?: number;
+    max?: number;
+}
+interface Block<Schema extends StandardSchemaV1 = StandardSchemaV1, Component = unknown> {
+    /** Stable identity, referenced by every node. Renaming it is a migration. */
+    name: string;
+    schema: Schema;
+    /** Generic so core never imports a rendering library. */
+    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>;
+    /** 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. */
+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;
+    robots?: string;
+    canonical?: string;
+}
+/** The authoring shape: children are id references, so every editor operation is by id. */
+interface Node {
+    id: string;
+    block: string;
+    props: UnknownProps;
+    /** Slot name → ordered child ids. */
+    slots?: Record<string, readonly string[]>;
+}
+interface DocumentVersion {
+    documentId: string;
+    version: number;
+    root: string;
+    elements: Record<string, Node>;
+    meta: DocumentMeta;
+    createdAt: string;
+    createdBy: string;
+}
+
+/** Field path → how the field resolves at render. */
+type Holes = Record<string, FieldHintData>;
+/** Resolved — no lookups, no dangling references possible. */
+interface ArtifactNode {
+    id: string;
+    block: string;
+    /** Frozen fields only — literal values. */
+    props: UnknownProps;
+    holes?: Holes;
+    slots?: Record<string, ArtifactNode[]>;
+}
+/** The compiled result of one document version. Immutable and content-addressed. */
+interface Artifact {
+    /** Content address — the identity. */
+    hash: string;
+    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[];
+    meta: DocumentMeta;
+    compiledWith: string;
+}
+/** The only mutable state in the output layer — one independently-writable record per route. */
+interface RoutePointer {
+    route: string;
+    matchKind: "exact" | "param" | "prefix";
+    /** Artifact currently live at this route. */
+    hash: string;
+    updatedAt: string;
+}
+/** Advisory aggregation over every pointer, for the studio's route list and CI. */
+interface Manifest {
+    routes: RoutePointer[];
+    generatedAt: string;
+}
+/** The output layer's whole IO surface. Adapters implement it; core only returns values for it. */
+interface ArtifactStore {
+    read(hash: string): Promise<Artifact | null>;
+    write(artifact: Artifact): Promise<void>;
+    manifest(): Promise<Manifest>;
+    pointer(route: string): Promise<RoutePointer | null>;
+    publish(route: string, hash: string): Promise<void>;
+    unpublish(route: string): Promise<void>;
+}
+
+type CompileIssueCode = "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[]);
+}
+
+interface Registry {
+    get(name: string): Block | undefined;
+    names(): string[];
+    /** Hash of every block name and version. Nothing else. */
+    fingerprint(): string;
+}
+
+type RollbackCheck = {
+    compatible: true;
+} | {
+    compatible: false;
+    drifted: string[];
+};
+
+/**
+ * Compares what the artifact was compiled against with the registry live now. A name the
+ * registry no longer holds is drift, not an absent check — a deleted block is exactly the
+ * failure a rollback must be warned about.
+ */
+declare function checkRollback(artifact: Artifact, registry: Registry): RollbackCheck;
+
+/**
+ * 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.
+ */
+declare function compile(version: DocumentVersion, catalog: Catalog, registry: Registry, route: string): Artifact;
+
+/**
+ * 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.
+ */
+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.
+ */
+declare function defineBlock<Schema extends StandardSchemaV1, Component>(block: Block<Schema, Component>): Block<Schema, Component>;
+
+/**
+ * The serializable half of the catalog/registry split: schema, ui, defaults, docs — no
+ * components. Everything checkable at registration is checked here, because a bad hint or
+ * bad defaults are silent at every later point.
+ */
+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[];
+}
+
+/**
+ * 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.
+ */
+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 };

package/dist/index.js

@@ -0,0 +1,639 @@
+// 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/checkRollback.ts
+function checkRollback(artifact, registry) {
+  const drifted = Object.entries(artifact.blockVersions).filter(([name, version]) => registry.get(name)?.version !== version).map(([name]) => name);
+  return drifted.length === 0 ? { compatible: true } : { compatible: false, drifted };
+}
+
+// src/artifactNodeOf.ts
+function artifactNodeOf(node, resolve) {
+  const { props, holes } = resolve(node);
+  const artifactNode = { id: node.id, block: node.block, props };
+  if (Object.keys(holes).length > 0) {
+    artifactNode.holes = holes;
+  }
+  return artifactNode;
+}
+
+// src/slotEdges.ts
+function slotEdges(node) {
+  const edges = [];
+  for (const [slot, children] of Object.entries(node.slots ?? {})) {
+    for (const childId of children) {
+      edges.push({ slot, childId });
+    }
+  }
+  return edges;
+}
+
+// src/wireSlots.ts
+function wireSlots(version, built) {
+  for (const [id, artifactNode] of built) {
+    const source = version.elements[id];
+    if (source?.slots === void 0) continue;
+    const slots = {};
+    for (const [slotName, childIds] of Object.entries(source.slots)) {
+      slots[slotName] = childIds.flatMap((childId) => {
+        const child = built.get(childId);
+        return child === void 0 ? [] : [child];
+      });
+    }
+    artifactNode.slots = slots;
+  }
+}
+
+// src/denormalize.ts
+function denormalize(version, resolve) {
+  const pending = [version.root];
+  const built = /* @__PURE__ */ new Map();
+  while (pending.length > 0) {
+    const id = pending.pop();
+    if (id === void 0) break;
+    const node = version.elements[id];
+    if (built.has(id) || node === void 0) continue;
+    built.set(id, artifactNodeOf(node, resolve));
+    for (const edge of slotEdges(node)) {
+      pending.push(edge.childId);
+    }
+  }
+  wireSlots(version, built);
+  const root = built.get(version.root);
+  return root === void 0 ? [] : [root];
+}
+
+// src/fnv1a.ts
+var OFFSET_BASIS = 2166136261;
+var PRIME = 16777619;
+var HEX_RADIX = 16;
+var HEX_WIDTH = 8;
+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);
+  }
+  return (hash >>> 0).toString(HEX_RADIX).padStart(HEX_WIDTH, "0");
+}
+
+// src/hashArtifact.ts
+function hashArtifact(artifact) {
+  const sortKeys = (_key, value) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) return value;
+    const entries = Object.entries(value).sort(([left], [right]) => left < right ? -1 : 1);
+    return Object.fromEntries(entries);
+  };
+  return fnv1a(JSON.stringify(artifact, sortKeys));
+}
+
+// src/partitionProps.ts
+function partitionProps(validated, hints) {
+  const props = {};
+  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;
+    }
+  }
+  return { props, holes };
+}
+
+// src/formatIssuePath.ts
+function formatIssuePath(path) {
+  if (path === void 0) return "";
+  return path.map(
+    (segment) => typeof segment === "object" && segment !== null ? String(segment.key) : String(segment)
+  ).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;
+  if (!("~standard" in value)) return false;
+  const contract = value["~standard"];
+  if (typeof contract !== "object" || contract === null) return false;
+  return "validate" in contract && typeof contract.validate === "function";
+}
+
+// src/standardValidate.ts
+function standardValidate(schema, value) {
+  if (!isStandardSchema(schema)) {
+    throw new Error("Schema does not implement Standard Schema (`~standard.validate`)");
+  }
+  const result = schema["~standard"].validate(value);
+  if (result instanceof Promise) {
+    throw new Error(
+      "Schema validates asynchronously; compile and registration require synchronous validation"
+    );
+  }
+  return result;
+}
+
+// src/validateNodeProps.ts
+function validateNodeProps(node, schema) {
+  const result = standardValidate(schema, node.props);
+  if (result.issues !== void 0) {
+    const issues = result.issues.map((issue) => ({
+      nodeId: node.id,
+      path: formatIssuePath(issue.path),
+      code: "invalid-props",
+      message: issue.message
+    }));
+    return { issues };
+  }
+  if (!isUnknownProps(result.value)) {
+    return {
+      issues: [
+        {
+          nodeId: node.id,
+          path: "",
+          code: "invalid-props",
+          message: "block props must parse to an object"
+        }
+      ]
+    };
+  }
+  return { value: result.value, issues: [] };
+}
+
+// src/resolveAllProps.ts
+function resolveAllProps(version, catalog) {
+  const resolved = /* @__PURE__ */ new Map();
+  const issues = [];
+  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" });
+      continue;
+    }
+    const { value, issues: propIssues } = validateNodeProps(node, entry.schema);
+    issues.push(...propIssues);
+    if (value !== void 0) {
+      resolved.set(node.id, partitionProps(value, entry.ui));
+    }
+  }
+  return { resolved, issues };
+}
+
+// src/usedBlockVersions.ts
+function usedBlockVersions(version, registry) {
+  const versions = {};
+  for (const node of Object.values(version.elements)) {
+    const block = registry.get(node.block);
+    if (block !== void 0) {
+      versions[node.block] = block.version;
+    }
+  }
+  return versions;
+}
+
+// src/pushCycleFrame.ts
+function pushCycleFrame(stack, state, version, id) {
+  const node = version.elements[id];
+  if (node === void 0) return;
+  state.set(id, "visiting");
+  stack.push({ id, edges: slotEdges(node), next: 0 });
+}
+
+// src/findCycles.ts
+function findCycles(version) {
+  const state = /* @__PURE__ */ new Map();
+  const stack = [];
+  const issues = [];
+  pushCycleFrame(stack, state, version, version.root);
+  while (stack.length > 0) {
+    const frame = stack.at(-1);
+    if (frame === void 0) break;
+    const edge = frame.edges[frame.next];
+    if (edge === void 0) {
+      state.set(frame.id, "done");
+      stack.pop();
+      continue;
+    }
+    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`
+      });
+    } else if (!state.has(edge.childId)) {
+      pushCycleFrame(stack, state, version, edge.childId);
+    }
+  }
+  return issues;
+}
+
+// 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`
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+// src/disallowedChildren.ts
+function disallowedChildren(parent, path, childIds, allow, version) {
+  if (allow === void 0) return [];
+  const issues = [];
+  for (const childId of childIds) {
+    const child = version.elements[childId];
+    if (child === void 0 || allow.includes(child.block)) continue;
+    issues.push({
+      nodeId: childId,
+      path,
+      code: "slot-not-allowed",
+      message: `"${child.block}" is not allowed in ${path} of "${parent.block}"; allowed: ${allow.join(", ")}`
+    });
+  }
+  return issues;
+}
+
+// src/slotBoundIssues.ts
+function slotBoundIssues(parentId, path, count, constraint) {
+  const { min, max } = constraint;
+  const bounds = [
+    {
+      code: "slot-min",
+      limit: min,
+      breached: min !== void 0 && count < min,
+      sense: "at least"
+    },
+    {
+      code: "slot-max",
+      limit: max,
+      breached: max !== void 0 && count > max,
+      sense: "at most"
+    }
+  ];
+  return bounds.filter((bound) => bound.breached).map((bound) => ({
+    nodeId: parentId,
+    path,
+    code: bound.code,
+    message: `${path} holds ${count} of ${bound.sense} ${bound.limit}`
+  }));
+}
+
+// src/slotIssuesAt.ts
+function slotIssuesAt(parent, slotName, childIds, constraint, version) {
+  const path = `slots.${slotName}`;
+  if (constraint === void 0) {
+    return [
+      {
+        nodeId: parent.id,
+        path,
+        code: "slot-not-allowed",
+        message: `"${parent.block}" declares no slot "${slotName}"`
+      }
+    ];
+  }
+  return [
+    ...slotBoundIssues(parent.id, path, childIds.length, constraint),
+    ...disallowedChildren(parent, path, childIds, constraint.allow, version)
+  ];
+}
+
+// src/findSlotViolations.ts
+function findSlotViolations(version, registry) {
+  return Object.values(version.elements).flatMap((node) => {
+    const block = registry.get(node.block);
+    if (block === void 0) return [];
+    const filled = node.slots ?? {};
+    const names = /* @__PURE__ */ new Set([...Object.keys(block.slots), ...Object.keys(filled)]);
+    return [...names].flatMap(
+      (slotName) => slotIssuesAt(node, slotName, filled[slotName] ?? [], block.slots[slotName], version)
+    );
+  });
+}
+
+// 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,
+    path: "block",
+    code: "unknown-block",
+    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;
+    for (const edge of slotEdges(node)) {
+      if (seen.has(edge.childId)) continue;
+      seen.add(edge.childId);
+      queue.push(edge.childId);
+    }
+  }
+  return seen;
+}
+
+// src/findUnreachable.ts
+function findUnreachable(version) {
+  const reached = reachableIds(version);
+  const issues = [];
+  for (const node of Object.values(version.elements)) {
+    if (reached.has(node.id)) continue;
+    issues.push({
+      nodeId: node.id,
+      path: "",
+      code: "unreachable",
+      message: `no slot reaches "${node.id}" from the root`
+    });
+  }
+  return issues;
+}
+
+// src/validateStructure.ts
+function validateStructure(version, registry) {
+  return [
+    ...findUnknownBlocks(version, registry),
+    ...findDanglingChildren(version),
+    ...findCycles(version),
+    ...findUnreachable(version),
+    ...findSlotViolations(version, registry)
+  ];
+}
+
+// src/version.constants.ts
+var NUBBIN_VERSION = "0.0.0";
+
+// src/compile.ts
+function compile(version, catalog, registry, 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);
+  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) };
+}
+
+// src/createRegistry.ts
+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`
+      );
+    }
+    byName.set(block.name, block);
+  }
+  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
+  };
+}
+
+// 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}`);
+    }
+  }
+}
+
+// src/assertSlotBounds.ts
+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}`);
+    }
+  }
+}
+
+// src/defineBlock.ts
+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));
+  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(", ")}`
+    );
+  }
+}
+
+// src/assertValidDefaults.ts
+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}`);
+}
+
+// src/defineCatalog.ts
+function defineCatalog(entries) {
+  for (const [blockName, entry] of Object.entries(entries)) {
+    if (entry.ui?.fields !== void 0) {
+      resolveHintPaths(blockName, entry.schema, entry.ui.fields);
+    }
+    if (entry.defaults !== void 0) {
+      assertValidDefaults(blockName, entry.schema, entry.defaults);
+    }
+  }
+  return entries;
+}
+
+// src/parseMatchKind.ts
+function parseMatchKind(route) {
+  if (route.endsWith("/*")) {
+    return "prefix";
+  }
+  if (/\[[^/]+\]/.test(route)) {
+    return "param";
+  }
+  return "exact";
+}
+export {
+  CompileError,
+  checkRollback,
+  compile,
+  createRegistry,
+  defineBlock,
+  defineCatalog,
+  parseMatchKind
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@nubbin/core",
+  "version": "0.1.0-rc.0",
+  "description": "The Nubbin contract: define blocks, split catalog from registry, and compile a page document into an immutable artifact.",
+  "keywords": [
+    "nubbin",
+    "page-builder",
+    "cms",
+    "standard-schema",
+    "content"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/effekt/nubbin.git",
+    "directory": "packages/core"
+  },
+  "homepage": "https://effekt.github.io/nubbin/",
+  "bugs": "https://github.com/effekt/nubbin/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@standard-schema/spec": "1.1.0"
+  },
+  "devDependencies": {
+    "tsup": "8.5.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10",
+    "zod": "4.4.3"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}