@storacha/md-merge 0.2.0 → 0.3.0

package/dist/codec.d.ts

@@ -0,0 +1,18 @@
+/**
+ * DAG-CBOR serialization for RGATree and RGAChangeSet.
+ *
+ * Tree-specific serialization wraps the generic RGA codec from crdt/codec.ts,
+ * adding recursive handling of nested RGA children in tree nodes.
+ */
+import { type RGAEvent, type EventComparator } from './crdt/rga.js';
+import type { RGATreeRoot, RGATreeNode } from './types.js';
+import type { RGAChangeSet } from './types.js';
+export { encodeRGA, decodeRGA } from './crdt/codec.js';
+export declare function encodeTree<E extends RGAEvent>(root: RGATreeRoot<E>): Promise<import("multiformats").BlockView<unknown, 113, 18, 1>>;
+export declare function decodeTree<E extends RGAEvent>(block: {
+    bytes: Uint8Array;
+}, parseEvent: (s: string) => E, fingerprintFn: (value: RGATreeNode<E>) => string, compareEvents: EventComparator<E>): Promise<RGATreeRoot<E>>;
+export declare function encodeChangeSet<E extends RGAEvent>(cs: RGAChangeSet<E>): Promise<import("multiformats").BlockView<unknown, 113, 18, 1>>;
+export declare function decodeChangeSet<E extends RGAEvent>(block: {
+    bytes: Uint8Array;
+}, parseEvent: (s: string) => E): Promise<RGAChangeSet<E>>;

package/dist/codec.js

@@ -0,0 +1,108 @@
+/**
+ * DAG-CBOR serialization for RGATree and RGAChangeSet.
+ *
+ * Tree-specific serialization wraps the generic RGA codec from crdt/codec.ts,
+ * adding recursive handling of nested RGA children in tree nodes.
+ */
+import { encode, decode } from 'multiformats/block';
+import { sha256 } from 'multiformats/hashes/sha2';
+import * as cbor from '@ipld/dag-cbor';
+import { RGA } from './crdt/rga.js';
+import { stripUndefined, serializeNodeId, deserializeNodeId, serializeRGA, deserializeRGA, } from './crdt/codec.js';
+// Re-export plain RGA codec
+export { encodeRGA, decodeRGA } from './crdt/codec.js';
+// ---- Tree-specific helpers ----
+function isRGAParentSerialized(node) {
+    return (node != null &&
+        typeof node === 'object' &&
+        'children' in node &&
+        typeof node.children === 'object' &&
+        node.children !== null &&
+        'nodes' in node.children);
+}
+function isRGAParentNode(node) {
+    return 'children' in node && node.children instanceof RGA;
+}
+// ---- RGATree serialization ----
+function serializeTreeNodeValue(node) {
+    if (isRGAParentNode(node)) {
+        const { children, ...rest } = node;
+        return { ...rest, children: serializeRGA(children, (n) => serializeTreeNodeValue(n)) };
+    }
+    return node;
+}
+function serializeTree(root) {
+    return {
+        type: 'root',
+        children: serializeRGA(root.children, (n) => serializeTreeNodeValue(n)),
+    };
+}
+function deserializeTreeNodeValue(raw, parseEvent, fingerprintFn, compareEvents) {
+    if (isRGAParentSerialized(raw)) {
+        const { children, ...rest } = raw;
+        return {
+            ...rest,
+            children: deserializeTreeRGA(children, parseEvent, fingerprintFn, compareEvents),
+        };
+    }
+    return raw;
+}
+function deserializeTreeRGA(raw, parseEvent, fingerprintFn, compareEvents) {
+    return deserializeRGA(raw, parseEvent, (v) => deserializeTreeNodeValue(v, parseEvent, fingerprintFn, compareEvents), fingerprintFn, compareEvents);
+}
+function deserializeTree(raw, parseEvent, fingerprintFn, compareEvents) {
+    return {
+        type: 'root',
+        children: deserializeTreeRGA(raw.children, parseEvent, fingerprintFn, compareEvents),
+    };
+}
+function serializeChangeSet(cs) {
+    return {
+        event: cs.event.toString(),
+        changes: cs.changes.map(c => ({
+            type: c.type,
+            parentPath: c.parentPath.map(serializeNodeId),
+            targetId: c.targetId ? serializeNodeId(c.targetId) : null,
+            afterId: c.afterId ? serializeNodeId(c.afterId) : null,
+            nodes: c.nodes,
+            before: c.before,
+        })),
+    };
+}
+function deserializeChangeSet(raw, parseEvent) {
+    return {
+        event: parseEvent(raw.event),
+        changes: raw.changes.map(c => {
+            const change = {
+                type: c.type,
+                parentPath: c.parentPath.map(id => deserializeNodeId(id, parseEvent)),
+            };
+            if (c.targetId)
+                change.targetId = deserializeNodeId(c.targetId, parseEvent);
+            if (c.afterId)
+                change.afterId = deserializeNodeId(c.afterId, parseEvent);
+            if (c.nodes)
+                change.nodes = c.nodes;
+            if (c.before)
+                change.before = c.before;
+            return change;
+        }),
+    };
+}
+// ---- Public API: encode/decode to DAG-CBOR blocks ----
+export async function encodeTree(root) {
+    const value = stripUndefined(serializeTree(root));
+    return encode({ value, codec: cbor, hasher: sha256 });
+}
+export async function decodeTree(block, parseEvent, fingerprintFn, compareEvents) {
+    const decoded = await decode({ bytes: block.bytes, codec: cbor, hasher: sha256 });
+    return deserializeTree(decoded.value, parseEvent, fingerprintFn, compareEvents);
+}
+export async function encodeChangeSet(cs) {
+    const value = stripUndefined(serializeChangeSet(cs));
+    return encode({ value, codec: cbor, hasher: sha256 });
+}
+export async function decodeChangeSet(block, parseEvent) {
+    const decoded = await decode({ bytes: block.bytes, codec: cbor, hasher: sha256 });
+    return deserializeChangeSet(decoded.value, parseEvent);
+}

package/dist/crdt/codec.d.ts

@@ -0,0 +1,33 @@
+/**
+ * DAG-CBOR serialization for plain RGA instances.
+ */
+import { RGA, type RGANodeId, type RGAEvent, type EventComparator } from './rga.js';
+/** Recursively strip `undefined` values (not IPLD-compatible). */
+export declare function stripUndefined(obj: unknown): unknown;
+export interface SerializedNodeId {
+    uuid: string;
+    event: string;
+}
+export interface SerializedRGANode<V = unknown> {
+    id: SerializedNodeId;
+    value: V;
+    afterId: SerializedNodeId | null;
+    tombstone: boolean;
+}
+export interface SerializedRGA<V = unknown> {
+    nodes: SerializedRGANode<V>[];
+}
+export declare function serializeNodeId<E extends RGAEvent>(id: RGANodeId<E>): SerializedNodeId;
+export declare function deserializeNodeId<E extends RGAEvent>(raw: SerializedNodeId, parseEvent: (s: string) => E): RGANodeId<E>;
+export declare function serializeRGA<T, E extends RGAEvent>(rga: RGA<T, E>, serializeValue?: (v: T) => unknown): SerializedRGA;
+export declare function deserializeRGA<T, E extends RGAEvent>(raw: SerializedRGA, parseEvent: (s: string) => E, deserializeValue: (v: unknown) => T, fingerprintFn: (value: T) => string, compareEvents: EventComparator<E>): RGA<T, E>;
+/**
+ * Encode a plain RGA as a DAG-CBOR block.
+ */
+export declare function encodeRGA<T, E extends RGAEvent>(rga: RGA<T, E>, serializeValue?: (v: T) => unknown): Promise<import("multiformats").BlockView<unknown, 113, 18, 1>>;
+/**
+ * Decode a plain RGA from a DAG-CBOR block.
+ */
+export declare function decodeRGA<T, E extends RGAEvent>(block: {
+    bytes: Uint8Array;
+}, parseEvent: (s: string) => E, deserializeValue: (v: unknown) => T, fingerprintFn: (value: T) => string, compareEvents: EventComparator<E>): Promise<RGA<T, E>>;

package/dist/crdt/codec.js

@@ -0,0 +1,69 @@
+/**
+ * DAG-CBOR serialization for plain RGA instances.
+ */
+import { encode, decode } from 'multiformats/block';
+import { sha256 } from 'multiformats/hashes/sha2';
+import * as cbor from '@ipld/dag-cbor';
+import { RGA } from './rga.js';
+/** Recursively strip `undefined` values (not IPLD-compatible). */
+export function stripUndefined(obj) {
+    if (obj === null || obj === undefined)
+        return null;
+    if (Array.isArray(obj))
+        return obj.map(stripUndefined);
+    if (typeof obj === 'object') {
+        const clean = {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (v !== undefined)
+                clean[k] = stripUndefined(v);
+        }
+        return clean;
+    }
+    return obj;
+}
+// ---- Helpers ----
+export function serializeNodeId(id) {
+    return { uuid: id.uuid, event: id.event.toString() };
+}
+export function deserializeNodeId(raw, parseEvent) {
+    return { uuid: raw.uuid, event: parseEvent(raw.event) };
+}
+// ---- Serialize / Deserialize ----
+export function serializeRGA(rga, serializeValue = (v) => v) {
+    const nodes = [];
+    for (const node of rga.nodes.values()) {
+        nodes.push({
+            id: serializeNodeId(node.id),
+            value: serializeValue(node.value),
+            afterId: node.afterId ? serializeNodeId(node.afterId) : null,
+            tombstone: node.tombstone,
+        });
+    }
+    return { nodes };
+}
+export function deserializeRGA(raw, parseEvent, deserializeValue, fingerprintFn, compareEvents) {
+    const rga = new RGA(fingerprintFn, compareEvents);
+    for (const rawNode of raw.nodes) {
+        const id = deserializeNodeId(rawNode.id, parseEvent);
+        const afterId = rawNode.afterId ? deserializeNodeId(rawNode.afterId, parseEvent) : undefined;
+        const value = deserializeValue(rawNode.value);
+        const key = `${id.uuid}:${id.event.toString()}`;
+        rga.nodes.set(key, { id, value, afterId, tombstone: rawNode.tombstone });
+    }
+    return rga;
+}
+// ---- Public API: encode/decode to DAG-CBOR blocks ----
+/**
+ * Encode a plain RGA as a DAG-CBOR block.
+ */
+export async function encodeRGA(rga, serializeValue = (v) => v) {
+    const value = stripUndefined(serializeRGA(rga, serializeValue));
+    return encode({ value, codec: cbor, hasher: sha256 });
+}
+/**
+ * Decode a plain RGA from a DAG-CBOR block.
+ */
+export async function decodeRGA(block, parseEvent, deserializeValue, fingerprintFn, compareEvents) {
+    const decoded = await decode({ bytes: block.bytes, codec: cbor, hasher: sha256 });
+    return deserializeRGA(decoded.value, parseEvent, deserializeValue, fingerprintFn, compareEvents);
+}

package/dist/crdt/rga.d.ts

@@ -0,0 +1,53 @@
+/** Interface for event types used in RGA node IDs */
+export interface RGAEvent {
+    toString(): string;
+}
+/** Structured identifier for RGA nodes */
+export interface RGANodeId<E extends RGAEvent> {
+    uuid: string;
+    event: E;
+}
+/** An element in the RGA */
+export interface RGANode<T, E extends RGAEvent> {
+    id: RGANodeId<E>;
+    value: T;
+    afterId: RGANodeId<E> | undefined;
+    tombstone: boolean;
+}
+/** Comparator for events — determines precedence for concurrent inserts */
+export type EventComparator<E extends RGAEvent> = (a: E, b: E) => number;
+/**
+ * RGA (Replicated Growable Array) — a CRDT for ordered sequences.
+ *
+ * Each element has a unique ID (UUID + Event) and a pointer to its predecessor.
+ * Concurrent inserts after the same predecessor are ordered by event comparator (then uuid).
+ * Deletes are tombstoned.
+ */
+export declare class RGA<T, E extends RGAEvent = RGAEvent> {
+    nodes: Map<string, RGANode<T, E>>;
+    fingerprintFn: (value: T) => string;
+    compareEvents: EventComparator<E>;
+    constructor(fingerprintFn: (value: T) => string, compareEvents: EventComparator<E>);
+    /** Compare two node IDs: primary by event, secondary by uuid */
+    private compareIds;
+    /** Insert a new element after the given predecessor. Returns the new node's ID. */
+    insert(afterId: RGANodeId<E> | undefined, value: T, event: E): RGANodeId<E>;
+    /** Mark an element as deleted (tombstone). */
+    delete(id: RGANodeId<E>): void;
+    /** Rebuild the ordered array from the graph, excluding tombstones. */
+    toArray(): T[];
+    /** Rebuild ordered nodes (including tombstones for internal use). */
+    private allOrdered;
+    /** Get ordered non-tombstoned nodes. */
+    toNodes(): RGANode<T, E>[];
+    /** Get all ordered nodes including tombstones. */
+    toAllNodes(): RGANode<T, E>[];
+    /** Merge another RGA into this one. Union of all nodes; tombstones win. */
+    merge(other: RGA<T, E>): void;
+    /** Create an RGA from an array of items. Each item is inserted sequentially. */
+    static fromArray<T, E extends RGAEvent>(items: T[], event: E, fingerprintFn: (value: T) => string, compareEvents: EventComparator<E>): RGA<T, E>;
+    /** Get the node ID at a given index (among non-tombstoned nodes). */
+    idAtIndex(index: number): RGANodeId<E> | undefined;
+    /** Get the afterId for inserting at a given index. */
+    predecessorForIndex(index: number): RGANodeId<E> | undefined;
+}

package/dist/crdt/rga.js

@@ -0,0 +1,118 @@
+import { randomUUID } from 'node:crypto';
+/** Serialize an RGANodeId for use as a Map key */
+function serializeId(id) {
+    return `${id.uuid}:${id.event.toString()}`;
+}
+/**
+ * RGA (Replicated Growable Array) — a CRDT for ordered sequences.
+ *
+ * Each element has a unique ID (UUID + Event) and a pointer to its predecessor.
+ * Concurrent inserts after the same predecessor are ordered by event comparator (then uuid).
+ * Deletes are tombstoned.
+ */
+export class RGA {
+    nodes = new Map();
+    fingerprintFn;
+    compareEvents;
+    constructor(fingerprintFn, compareEvents) {
+        this.fingerprintFn = fingerprintFn;
+        this.compareEvents = compareEvents;
+    }
+    /** Compare two node IDs: primary by event, secondary by uuid */
+    compareIds(a, b) {
+        const cmp = this.compareEvents(a.event, b.event);
+        if (cmp !== 0)
+            return cmp;
+        if (a.uuid < b.uuid)
+            return -1;
+        if (a.uuid > b.uuid)
+            return 1;
+        return 0;
+    }
+    /** Insert a new element after the given predecessor. Returns the new node's ID. */
+    insert(afterId, value, event) {
+        const id = { uuid: randomUUID(), event };
+        this.nodes.set(serializeId(id), { id, value, afterId, tombstone: false });
+        return id;
+    }
+    /** Mark an element as deleted (tombstone). */
+    delete(id) {
+        const node = this.nodes.get(serializeId(id));
+        if (node)
+            node.tombstone = true;
+    }
+    /** Rebuild the ordered array from the graph, excluding tombstones. */
+    toArray() {
+        return this.toNodes().map(n => n.value);
+    }
+    /** Rebuild ordered nodes (including tombstones for internal use). */
+    allOrdered() {
+        const ROOT_KEY = '__ROOT__';
+        const children = new Map();
+        for (const node of this.nodes.values()) {
+            const key = node.afterId ? serializeId(node.afterId) : ROOT_KEY;
+            let list = children.get(key);
+            if (!list) {
+                list = [];
+                children.set(key, list);
+            }
+            list.push(node);
+        }
+        for (const list of children.values()) {
+            list.sort((a, b) => this.compareIds(a.id, b.id));
+        }
+        const result = [];
+        const visit = (parentKey) => {
+            const kids = children.get(parentKey);
+            if (!kids)
+                return;
+            for (const kid of kids) {
+                result.push(kid);
+                visit(serializeId(kid.id));
+            }
+        };
+        visit(ROOT_KEY);
+        return result;
+    }
+    /** Get ordered non-tombstoned nodes. */
+    toNodes() {
+        return this.allOrdered().filter(n => !n.tombstone);
+    }
+    /** Get all ordered nodes including tombstones. */
+    toAllNodes() {
+        return this.allOrdered();
+    }
+    /** Merge another RGA into this one. Union of all nodes; tombstones win. */
+    merge(other) {
+        for (const [key, node] of other.nodes) {
+            const existing = this.nodes.get(key);
+            if (!existing) {
+                this.nodes.set(key, { ...node });
+            }
+            else if (node.tombstone) {
+                existing.tombstone = true;
+            }
+        }
+    }
+    /** Create an RGA from an array of items. Each item is inserted sequentially. */
+    static fromArray(items, event, fingerprintFn, compareEvents) {
+        const rga = new RGA(fingerprintFn, compareEvents);
+        let afterId = undefined;
+        for (const item of items) {
+            afterId = rga.insert(afterId, item, event);
+        }
+        return rga;
+    }
+    /** Get the node ID at a given index (among non-tombstoned nodes). */
+    idAtIndex(index) {
+        const nodes = this.toNodes();
+        return index < nodes.length ? nodes[index].id : undefined;
+    }
+    /** Get the afterId for inserting at a given index. */
+    predecessorForIndex(index) {
+        const nodes = this.toNodes();
+        if (index <= 0)
+            return undefined;
+        return nodes[index - 1].id;
+    }
+}

package/dist/diff.d.ts

@@ -0,0 +1,11 @@
+import type { Root } from "mdast";
+import type { ChangeSet } from "./types.js";
+/**
+ * Diff two mdast Root nodes recursively.
+ */
+export declare function diff(oldRoot: Root, newRoot: Root): ChangeSet;
+/**
+ * Apply a changeset to a root, producing a new root.
+ * Deep-clones the tree, then applies changes deepest-first to avoid index shifting.
+ */
+export declare function applyChangeSet(root: Root, changeset: ChangeSet): Root;

package/dist/diff.js

@@ -0,0 +1,214 @@
+import { fingerprint } from "./parse.js";
+/** Check if a node has children */
+function hasChildren(node) {
+    return (node != null &&
+        typeof node === "object" &&
+        "children" in node &&
+        Array.isArray(node.children));
+}
+function nodeType(node) {
+    return node.type;
+}
+/**
+ * Compute LCS table for two string arrays.
+ */
+function lcsTable(a, b) {
+    const m = a.length;
+    const n = b.length;
+    const table = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            if (a[i - 1] === b[j - 1]) {
+                table[i][j] = table[i - 1][j - 1] + 1;
+            }
+            else {
+                table[i][j] = Math.max(table[i - 1][j], table[i][j - 1]);
+            }
+        }
+    }
+    return table;
+}
+/**
+ * Extract LCS matches from the table.
+ * Returns array of [oldIndex, newIndex] pairs.
+ */
+function lcsMatches(aFp, bFp, table) {
+    const matches = [];
+    let i = aFp.length;
+    let j = bFp.length;
+    while (i > 0 && j > 0) {
+        if (aFp[i - 1] === bFp[j - 1]) {
+            matches.push([i - 1, j - 1]);
+            i--;
+            j--;
+        }
+        else if (table[i - 1][j] >= table[i][j - 1]) {
+            i--;
+        }
+        else {
+            j--;
+        }
+    }
+    matches.reverse();
+    return matches;
+}
+function fpChild(node) {
+    return fingerprint(node);
+}
+/**
+ * Diff the gap between LCS matches: unmatched old/new nodes.
+ * Pairs same-type nodes for recursive descent; remainder are insert/delete.
+ */
+function diffGap(oldNodes, newNodes, oldStartIdx, newStartIdx, pathPrefix) {
+    const changes = [];
+    // Try to pair same-type nodes sequentially for recursive diffing
+    let oi = 0;
+    let ni = 0;
+    while (oi < oldNodes.length && ni < newNodes.length) {
+        const oldNode = oldNodes[oi];
+        const newNode = newNodes[ni];
+        if (nodeType(oldNode) === nodeType(newNode) &&
+            hasChildren(oldNode) &&
+            hasChildren(newNode)) {
+            // Same type with children — recurse
+            const childChanges = diffChildren(oldNode.children, newNode.children, [
+                ...pathPrefix,
+                newStartIdx + ni,
+            ]);
+            changes.push(...childChanges);
+            oi++;
+            ni++;
+        }
+        else if (nodeType(oldNode) === nodeType(newNode)) {
+            // Same type leaf but different content — modify
+            changes.push({
+                type: "modify",
+                path: [...pathPrefix, newStartIdx + ni],
+                nodes: [newNode],
+                before: [oldNode],
+            });
+            oi++;
+            ni++;
+        }
+        else {
+            // Different types — delete old, insert new
+            changes.push({
+                type: "delete",
+                path: [...pathPrefix, oldStartIdx + oi],
+                nodes: [oldNode],
+            });
+            oi++;
+        }
+    }
+    // Remaining old = deletes
+    while (oi < oldNodes.length) {
+        changes.push({
+            type: "delete",
+            path: [...pathPrefix, oldStartIdx + oi],
+            nodes: [oldNodes[oi]],
+        });
+        oi++;
+    }
+    // Remaining new = inserts
+    while (ni < newNodes.length) {
+        changes.push({
+            type: "insert",
+            path: [...pathPrefix, newStartIdx + ni],
+            nodes: [newNodes[ni]],
+        });
+        ni++;
+    }
+    return changes;
+}
+/**
+ * Recursively diff two arrays of child nodes at a given path prefix.
+ */
+function diffChildren(oldChildren, newChildren, pathPrefix) {
+    const oldFp = oldChildren.map(fpChild);
+    const newFp = newChildren.map(fpChild);
+    const table = lcsTable(oldFp, newFp);
+    const matches = lcsMatches(oldFp, newFp, table);
+    const changes = [];
+    // Process gaps between matches
+    let prevOld = 0;
+    let prevNew = 0;
+    for (const [oi, ni] of matches) {
+        // Gap before this match
+        if (oi > prevOld || ni > prevNew) {
+            const oldGap = oldChildren.slice(prevOld, oi);
+            const newGap = newChildren.slice(prevNew, ni);
+            changes.push(...diffGap(oldGap, newGap, prevOld, prevNew, pathPrefix));
+        }
+        // Matched node — identical fingerprints, no changes needed
+        prevOld = oi + 1;
+        prevNew = ni + 1;
+    }
+    // Trailing gap after last match
+    if (prevOld < oldChildren.length || prevNew < newChildren.length) {
+        const oldGap = oldChildren.slice(prevOld);
+        const newGap = newChildren.slice(prevNew);
+        changes.push(...diffGap(oldGap, newGap, prevOld, prevNew, pathPrefix));
+    }
+    return changes;
+}
+/**
+ * Diff two mdast Root nodes recursively.
+ */
+export function diff(oldRoot, newRoot) {
+    const changes = diffChildren(oldRoot.children, newRoot.children, []);
+    return { changes };
+}
+function comparePaths(a, b) {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+        if (a[i] !== b[i])
+            return a[i] - b[i];
+    }
+    return a.length - b.length;
+}
+function navigateToParent(root, path) {
+    if (path.length === 0)
+        return null;
+    let current = root;
+    for (let i = 0; i < path.length - 1; i++) {
+        if (!hasChildren(current))
+            return null;
+        current = current.children[path[i]];
+    }
+    if (!hasChildren(current))
+        return null;
+    return {
+        siblings: current.children,
+        index: path[path.length - 1],
+    };
+}
+/**
+ * Apply a changeset to a root, producing a new root.
+ * Deep-clones the tree, then applies changes deepest-first to avoid index shifting.
+ */
+export function applyChangeSet(root, changeset) {
+    const newRoot = JSON.parse(JSON.stringify(root));
+    // Sort: deepest first, then higher indices first to avoid shifting
+    const sorted = [...changeset.changes].sort((a, b) => {
+        if (a.path.length !== b.path.length)
+            return b.path.length - a.path.length;
+        return -comparePaths(a.path, b.path);
+    });
+    for (const change of sorted) {
+        const nav = navigateToParent(newRoot, change.path);
+        if (!nav)
+            continue;
+        const { siblings, index } = nav;
+        switch (change.type) {
+            case "insert":
+                siblings.splice(index, 0, ...(change.nodes ?? []));
+                break;
+            case "delete":
+                siblings.splice(index, 1);
+                break;
+            case "modify":
+                siblings.splice(index, 1, ...(change.nodes ?? []));
+                break;
+        }
+    }
+    return newRoot;
+}

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * UCN integration — types and helpers for using md-merge with @storacha/ucn.
+ *
+ * Operations are stored as RGAChangeSets (RGA-addressed, index-free) so they
+ * compose via CRDT merge rather than requiring three-way diff.
+ */
+import type { RGAChangeSet, RGATreeRoot } from "./types.js";
+import type { RGAEvent, EventComparator } from "./crdt/rga.js";
+export { parse, stringify, stringifyNode, fingerprint } from "./parse.js";
+export { diff, applyChangeSet } from "./diff.js";
+export { toRGATree, toMdast, applyMdastToRGATree, generateRGAChangeSet, applyRGAChangeSet, } from "./rga-tree.js";
+export { encodeTree, decodeTree, encodeChangeSet, decodeChangeSet } from "./codec.js";
+export type { ChangeSet, Change, RGAChangeSet, RGAChange, RGATreeRoot, RGATreeNode, RGAParentNode, RGALeafNode, } from "./types.js";
+export { RGA, type RGAEvent, type RGANodeId, type EventComparator } from "./types.js";
+/**
+ * Compute an RGA-addressed changeset between an existing RGA tree and new markdown.
+ */
+export declare function computeChangeSet<E extends RGAEvent>(existing: RGATreeRoot<E>, newMarkdown: string, event: E): RGAChangeSet<E>;
+/**
+ * Apply an RGA changeset to an RGA tree, returning updated tree + markdown.
+ */
+export declare function applyToTree<E extends RGAEvent>(tree: RGATreeRoot<E>, changeset: RGAChangeSet<E>, compareEvents: EventComparator<E>): {
+    tree: RGATreeRoot<E>;
+    markdown: string;
+};
+/**
+ * Apply an RGA changeset and return just the markdown string.
+ */
+export declare function applyToMarkdown<E extends RGAEvent>(tree: RGATreeRoot<E>, changeset: RGAChangeSet<E>, compareEvents: EventComparator<E>): string;
+/**
+ * Bootstrap: create an RGA tree from a markdown string.
+ */
+export declare function fromMarkdown<E extends RGAEvent>(markdown: string, event: E, compareEvents: EventComparator<E>): RGATreeRoot<E>;