@nubbin/core 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1531,6 +1531,27 @@ declare class NubbinError extends Error {
  */
 declare function parseMatchKind(route: string): RoutePointer["matchKind"];
 
+/** One value as it existed at a conflicting path. `present` distinguishes deletion from `undefined`. */
+interface ReconciliationValue {
+    readonly present: boolean;
+    readonly value?: unknown;
+}
+/** A path changed differently in both descendants of the same base. */
+interface DocumentConflict {
+    readonly path: readonly string[];
+    readonly base: ReconciliationValue;
+    readonly local: ReconciliationValue;
+    readonly remote: ReconciliationValue;
+}
+/** A local-first working copy plus every choice an author still has to make. */
+interface DocumentReconciliation {
+    readonly version: DocumentVersion;
+    readonly conflicts: readonly DocumentConflict[];
+}
+
+/** Reconciles two descendants of one document version without discarding either side's work. */
+declare function reconcileDocumentVersion(base: DocumentVersion, local: DocumentVersion, remote: DocumentVersion): DocumentReconciliation;
+
 /**
  * Throws the one-cause refusal almost every Nubbin surface raises, in one line rather than
  * assembling an issue array around it.
@@ -1591,6 +1612,9 @@ declare function refuse(code: NubbinIssue["code"], message: string, at?: string)
  */
 declare function removeNode(version: DocumentVersion, nodeId: string): DocumentVersion;
 
+/** Applies one explicit local-or-remote conflict choice to a reconciled working document. */
+declare function resolveDocumentConflict(version: DocumentVersion, conflict: DocumentConflict, choice: "local" | "remote"): DocumentVersion;
+
 /**
  * A schema `core` writes itself, such as the one `richText()` returns. It satisfies both
  * `StandardSchemaV1` and `StandardJSONSchemaV1`, so a block, a catalog entry or an adapter takes
@@ -1738,4 +1762,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 BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, type CompileResult, type DocumentMeta, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, NubbinError, type NubbinIssue, NubbinIssueCode, type PointerMove, RICH_TEXT_BLOCK_KINDS, RICH_TEXT_MARKS, 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, isRichTextBlockKind, isRichTextMark, moveNode, parseMatchKind, refuse, removeNode, richText, setAtPath, setNodeProp, zodAdapter };
+export { type Artifact, type ArtifactNode, type ArtifactStore, type Block, type BlockDrift, type BlockUi, type Catalog, type CatalogEntry, type CompatibilityReport, type CompileResult, type DocumentConflict, type DocumentMeta, type DocumentReconciliation, type DocumentVersion, type FieldHint, type FieldHintData, type FieldKind, type FieldNode, type Holes, type InferProps, type LiveRoute, type Manifest, type Node, NubbinError, type NubbinIssue, NubbinIssueCode, type PointerMove, RICH_TEXT_BLOCK_KINDS, RICH_TEXT_MARKS, type ReconciliationValue, 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, isRichTextBlockKind, isRichTextMark, moveNode, parseMatchKind, reconcileDocumentVersion, refuse, removeNode, resolveDocumentConflict, richText, setAtPath, setNodeProp, zodAdapter };

package/dist/index.js

@@ -883,7 +883,7 @@ function validateStructure(version, registry) {
 }
 
 // src/version.constants.ts
-var NUBBIN_VERSION = "0.4.0";
+var NUBBIN_VERSION = "0.5.0";
 
 // src/compile.ts
 function compile(version, catalog, registry, route) {
@@ -1112,6 +1112,97 @@ function parseMatchKind(route) {
   return "exact";
 }
 
+// src/reconciliationValueAt.ts
+function reconciliationValueAt(record, key) {
+  return Object.hasOwn(record, key) ? { present: true, value: record[key] } : { present: false };
+}
+
+// src/reconcileRecords.ts
+function reconcileRecords([base, local, remote], path, reconcile) {
+  const merged = {};
+  const conflicts = [];
+  const keys = /* @__PURE__ */ new Set([...Object.keys(base), ...Object.keys(local), ...Object.keys(remote)]);
+  for (const key of keys) {
+    const result = reconcile(
+      reconciliationValueAt(base, key),
+      reconciliationValueAt(local, key),
+      reconciliationValueAt(remote, key),
+      [...path, key]
+    );
+    if (result.value.present) merged[key] = result.value.value;
+    conflicts.push(...result.conflicts);
+  }
+  return { value: { present: true, value: merged }, conflicts };
+}
+
+// src/isPlainRecord.ts
+function isPlainRecord(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// src/sameReconciliationValue.ts
+function sameReconciliationValue(left, right) {
+  if (left.present !== right.present) return false;
+  if (!left.present) return true;
+  if (Object.is(left.value, right.value)) return true;
+  if (Array.isArray(left.value) && Array.isArray(right.value)) {
+    const leftArray = left.value;
+    const rightArray = right.value;
+    return leftArray.length === rightArray.length && leftArray.every(
+      (value, index) => sameReconciliationValue(
+        { present: true, value },
+        { present: true, value: rightArray[index] }
+      )
+    );
+  }
+  if (!isPlainRecord(left.value) || !isPlainRecord(right.value)) return false;
+  const leftRecord = left.value;
+  const rightRecord = right.value;
+  const leftKeys = Object.keys(leftRecord);
+  const rightKeys = Object.keys(rightRecord);
+  return leftKeys.length === rightKeys.length && leftKeys.every(
+    (key) => Object.hasOwn(rightRecord, key) && sameReconciliationValue(
+      { present: true, value: leftRecord[key] },
+      { present: true, value: rightRecord[key] }
+    )
+  );
+}
+
+// src/toPlainRecord.ts
+function toPlainRecord(value) {
+  return value.present && isPlainRecord(value.value) ? value.value : void 0;
+}
+
+// src/reconcileValue.ts
+function reconcileValue(base, local, remote, path = []) {
+  if (sameReconciliationValue(local, remote)) return { value: local, conflicts: [] };
+  if (sameReconciliationValue(local, base)) return { value: remote, conflicts: [] };
+  if (sameReconciliationValue(remote, base)) return { value: local, conflicts: [] };
+  const records = [toPlainRecord(base), toPlainRecord(local), toPlainRecord(remote)];
+  if (records.some((value) => value === void 0)) {
+    return { value: local, conflicts: [{ path, base, local, remote }] };
+  }
+  return reconcileRecords(records, path, reconcileValue);
+}
+
+// src/reconcileDocumentVersion.ts
+function reconcileDocumentVersion(base, local, remote) {
+  if (base.documentId !== local.documentId || base.documentId !== remote.documentId) {
+    throw new TypeError("cannot reconcile versions from different documents");
+  }
+  const result = reconcileValue(
+    { present: true, value: base },
+    { present: true, value: local },
+    { present: true, value: remote }
+  );
+  return {
+    version: result.value.value,
+    conflicts: result.conflicts
+  };
+}
+
 // src/removeNode.ts
 function removeNode(version, nodeId) {
   requireNode(version, nodeId);
@@ -1126,6 +1217,28 @@ function removeNode(version, nodeId) {
   return { ...detached, elements };
 }
 
+// src/withReconciliationValueAtPath.ts
+function withReconciliationValueAtPath(root, path, replacement) {
+  const [head, ...tail] = path;
+  if (head === void 0) return root;
+  const record = root;
+  const result = { ...record };
+  if (tail.length === 0) {
+    if (replacement.present) result[head] = replacement.value;
+    else delete result[head];
+    return result;
+  }
+  const child = record[head];
+  if (typeof child !== "object" || child === null || Array.isArray(child)) return root;
+  result[head] = withReconciliationValueAtPath(child, tail, replacement);
+  return result;
+}
+
+// src/resolveDocumentConflict.ts
+function resolveDocumentConflict(version, conflict, choice) {
+  return withReconciliationValueAtPath(version, conflict.path, conflict[choice]);
+}
+
 // src/defineStandardSchema.ts
 var STANDARD_SCHEMA_VERSION = 1;
 function defineStandardSchema(issuesOf, jsonSchemaOf) {
@@ -1296,8 +1409,10 @@ export {
   isRichTextMark,
   moveNode,
   parseMatchKind,
+  reconcileDocumentVersion,
   refuse,
   removeNode,
+  resolveDocumentConflict,
   richText,
   setAtPath,
   setNodeProp,

package/package.json

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