@storacha/md-merge 0.2.0 → 0.2.1

package/dist/codec.d.ts

@@ -0,0 +1,29 @@
+/**
+ * DAG-CBOR serialization for RGATree and RGAChangeSet.
+ *
+ * Converts RGA class instances (with Maps, nested RGAs) to plain
+ * CBOR-friendly objects and back.
+ */
+import { type RGAEvent, type EventComparator } from './crdt/rga.js';
+import type { RGATreeRoot, RGATreeNode } from './types.js';
+import type { RGAChangeSet } from './types.js';
+/**
+ * Encode an RGATree as a DAG-CBOR block.
+ */
+export declare function encodeTree<E extends RGAEvent>(root: RGATreeRoot<E>): Promise<import("multiformats").BlockView<unknown, 113, 18, 1>>;
+/**
+ * Decode an RGATree from a DAG-CBOR block.
+ */
+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>>;
+/**
+ * Encode an RGAChangeSet as a DAG-CBOR block.
+ */
+export declare function encodeChangeSet<E extends RGAEvent>(cs: RGAChangeSet<E>): Promise<import("multiformats").BlockView<unknown, 113, 18, 1>>;
+/**
+ * Decode an RGAChangeSet from a DAG-CBOR block.
+ */
+export declare function decodeChangeSet<E extends RGAEvent>(block: {
+    bytes: Uint8Array;
+}, parseEvent: (s: string) => E): Promise<RGAChangeSet<E>>;

package/dist/codec.js

@@ -0,0 +1,160 @@
+/**
+ * DAG-CBOR serialization for RGATree and RGAChangeSet.
+ *
+ * Converts RGA class instances (with Maps, nested RGAs) to plain
+ * CBOR-friendly objects and back.
+ */
+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';
+/** Recursively strip `undefined` values (not IPLD-compatible). */
+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 ----
+function serializeNodeId(id) {
+    return { uuid: id.uuid, event: id.event.toString() };
+}
+function deserializeNodeId(raw, parseEvent) {
+    return { uuid: raw.uuid, event: parseEvent(raw.event) };
+}
+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 serializeRGA(rga) {
+    const nodes = [];
+    for (const node of rga.nodes.values()) {
+        nodes.push({
+            id: serializeNodeId(node.id),
+            value: serializeTreeNodeValue(node.value),
+            afterId: node.afterId ? serializeNodeId(node.afterId) : null,
+            tombstone: node.tombstone,
+        });
+    }
+    return { nodes };
+}
+function serializeTreeNodeValue(node) {
+    if (isRGAParentNode(node)) {
+        const { children, ...rest } = node;
+        return { ...rest, children: serializeRGA(children) };
+    }
+    return node;
+}
+function serializeTree(root) {
+    return {
+        type: 'root',
+        children: serializeRGA(root.children),
+    };
+}
+function deserializeRGA(raw, parseEvent, 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 = deserializeTreeNodeValue(rawNode.value, parseEvent, fingerprintFn, compareEvents);
+        const key = `${id.uuid}:${id.event.toString()}`;
+        rga.nodes.set(key, { id, value, afterId, tombstone: rawNode.tombstone });
+    }
+    return rga;
+}
+function deserializeTreeNodeValue(raw, parseEvent, fingerprintFn, compareEvents) {
+    if (isRGAParentSerialized(raw)) {
+        const { children, ...rest } = raw;
+        return {
+            ...rest,
+            children: deserializeRGA(children, parseEvent, fingerprintFn, compareEvents),
+        };
+    }
+    return raw;
+}
+function deserializeTree(raw, parseEvent, fingerprintFn, compareEvents) {
+    return {
+        type: 'root',
+        children: deserializeRGA(raw.children, parseEvent, fingerprintFn, compareEvents),
+    };
+}
+// ---- RGAChangeSet serialization ----
+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 ----
+/**
+ * Encode an RGATree as a DAG-CBOR block.
+ */
+export async function encodeTree(root) {
+    const value = stripUndefined(serializeTree(root));
+    return encode({ value, codec: cbor, hasher: sha256 });
+}
+/**
+ * Decode an RGATree from a DAG-CBOR block.
+ */
+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);
+}
+/**
+ * Encode an RGAChangeSet as a DAG-CBOR block.
+ */
+export async function encodeChangeSet(cs) {
+    const value = stripUndefined(serializeChangeSet(cs));
+    return encode({ value, codec: cbor, hasher: sha256 });
+}
+/**
+ * Decode an RGAChangeSet from a DAG-CBOR block.
+ */
+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/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>;

package/dist/index.js

@@ -0,0 +1,41 @@
+/**
+ * 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 { parse, stringify } from "./parse.js";
+import { toRGATree, toMdast, generateRGAChangeSet, applyRGAChangeSet, } from "./rga-tree.js";
+// Re-exports
+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 { RGA } from "./types.js";
+/**
+ * Compute an RGA-addressed changeset between an existing RGA tree and new markdown.
+ */
+export function computeChangeSet(existing, newMarkdown, event) {
+    const newRoot = parse(newMarkdown);
+    return generateRGAChangeSet(existing, newRoot, event);
+}
+/**
+ * Apply an RGA changeset to an RGA tree, returning updated tree + markdown.
+ */
+export function applyToTree(tree, changeset, compareEvents) {
+    const updated = applyRGAChangeSet(tree, changeset, compareEvents);
+    return { tree: updated, markdown: stringify(toMdast(updated)) };
+}
+/**
+ * Apply an RGA changeset and return just the markdown string.
+ */
+export function applyToMarkdown(tree, changeset, compareEvents) {
+    return applyToTree(tree, changeset, compareEvents).markdown;
+}
+/**
+ * Bootstrap: create an RGA tree from a markdown string.
+ */
+export function fromMarkdown(markdown, event, compareEvents) {
+    const root = parse(markdown);
+    return toRGATree(root, event, compareEvents);
+}

package/dist/parse.d.ts

@@ -0,0 +1,9 @@
+import type { Root, RootContent } from 'mdast';
+/** Parse markdown string into mdast Root */
+export declare function parse(markdown: string): Root;
+/** Stringify an mdast Root back to markdown */
+export declare function stringify(root: Root): string;
+/** Stringify a single mdast node by wrapping in a temporary root */
+export declare function stringifyNode(node: RootContent): string;
+/** Fingerprint a top-level mdast node by stringifying it */
+export declare function fingerprint(node: RootContent): string;

package/dist/parse.js

@@ -0,0 +1,22 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkStringify from 'remark-stringify';
+const parser = unified().use(remarkParse);
+const stringifier = unified().use(remarkStringify);
+/** Parse markdown string into mdast Root */
+export function parse(markdown) {
+    return parser.parse(markdown);
+}
+/** Stringify an mdast Root back to markdown */
+export function stringify(root) {
+    return stringifier.stringify(root);
+}
+/** Stringify a single mdast node by wrapping in a temporary root */
+export function stringifyNode(node) {
+    const tempRoot = { type: 'root', children: [node] };
+    return stringify(tempRoot).trim();
+}
+/** Fingerprint a top-level mdast node by stringifying it */
+export function fingerprint(node) {
+    return stringifyNode(node);
+}

package/dist/rga-tree.d.ts

@@ -0,0 +1,32 @@
+/**
+ * RGA-backed mdast tree.
+ *
+ * Every ordered `children` array in the mdast tree is replaced with an RGA,
+ * giving us CRDT merge semantics at every level.
+ */
+import type { RGAChangeSet, RGAEvent, RGATreeRoot, EventComparator } from "./types.js";
+import type { Root } from "mdast";
+export declare function toRGATree<E extends RGAEvent>(root: Root, event: E, compareEvents: EventComparator<E>): RGATreeRoot<E>;
+export declare function toMdast<E extends RGAEvent>(rgaRoot: RGATreeRoot<E>): Root;
+/**
+ * Apply a new mdast document to an existing RGA tree, preserving existing
+ * RGA node IDs where nodes haven't changed.
+ *
+ * Generates an RGAChangeSet from the diff, then applies it.
+ */
+export declare function applyMdastToRGATree<E extends RGAEvent>(existing: RGATreeRoot<E>, newRoot: Root, event: E, compareEvents: EventComparator<E>): RGATreeRoot<E>;
+/**
+ * Generate an RGA-addressed changeset by diffing an existing RGA tree against
+ * a new mdast document.
+ *
+ * 1. Convert RGA tree → plain mdast
+ * 2. Diff old mdast vs new mdast → index-based ChangeSet
+ * 3. Convert each index-based Change to an RGAChange by resolving indices
+ *    to RGA node IDs via idAtIndex / predecessorForIndex
+ */
+export declare function generateRGAChangeSet<E extends RGAEvent>(existing: RGATreeRoot<E>, newRoot: Root, event: E): RGAChangeSet<E>;
+/**
+ * Apply an RGA-addressed changeset to an RGA tree.
+ * Navigates by node IDs at every level — no index dependency.
+ */
+export declare function applyRGAChangeSet<E extends RGAEvent>(root: RGATreeRoot<E>, changeset: RGAChangeSet<E>, compareEvents: EventComparator<E>): RGATreeRoot<E>;

package/dist/rga-tree.js

@@ -0,0 +1,218 @@
+import { RGA } from "./types.js";
+import { fingerprint } from "./parse.js";
+import { diff as mdastDiff } from "./diff.js";
+// ---- Helpers ----
+function isParent(node) {
+    return "children" in node && Array.isArray(node.children);
+}
+function fpNode(node) {
+    if (isRGAParent(node)) {
+        const { children, ...rest } = node;
+        return JSON.stringify(rest);
+    }
+    return fingerprint(node);
+}
+function isRGAParent(node) {
+    return "children" in node && node.children instanceof RGA;
+}
+// ---- Conversion: mdast → RGA Tree ----
+export function toRGATree(root, event, compareEvents) {
+    return {
+        type: "root",
+        children: childrenToRGA(root.children, event, compareEvents),
+    };
+}
+function childrenToRGA(children, event, compareEvents) {
+    const converted = children.map((child) => convertNode(child, event, compareEvents));
+    return RGA.fromArray(converted, event, (n) => fpNode(n), compareEvents);
+}
+function convertNode(node, event, compareEvents) {
+    if (!isParent(node)) {
+        return node;
+    }
+    const { children, ...rest } = node;
+    return {
+        ...rest,
+        children: childrenToRGA(children, event, compareEvents),
+    };
+}
+// ---- Conversion: RGA Tree → mdast ----
+export function toMdast(rgaRoot) {
+    return {
+        type: "root",
+        children: rgaToChildren(rgaRoot.children),
+    };
+}
+function rgaToChildren(rga) {
+    return rga.toArray().map(revertNode);
+}
+function revertNode(node) {
+    if (!isRGAParent(node)) {
+        return node;
+    }
+    const { children, ...rest } = node;
+    return {
+        ...rest,
+        children: rgaToChildren(children),
+    };
+}
+// ---- Apply new mdast to existing RGA tree ----
+/**
+ * Apply a new mdast document to an existing RGA tree, preserving existing
+ * RGA node IDs where nodes haven't changed.
+ *
+ * Generates an RGAChangeSet from the diff, then applies it.
+ */
+export function applyMdastToRGATree(existing, newRoot, event, compareEvents) {
+    const changeset = generateRGAChangeSet(existing, newRoot, event);
+    return applyRGAChangeSet(existing, changeset, compareEvents);
+}
+/**
+ * Deep clone an RGA and all nested RGA children.
+ */
+function cloneRGA(rga) {
+    const clone = new RGA(rga.fingerprintFn, rga.compareEvents);
+    for (const [key, node] of rga.nodes) {
+        clone.nodes.set(key, {
+            ...node,
+            value: isRGAParent(node.value)
+                ? {
+                    ...node.value,
+                    children: cloneRGA(node.value.children),
+                }
+                : node.value,
+        });
+    }
+    return clone;
+}
+// ---- Generate RGA ChangeSet from mdast ----
+/**
+ * Generate an RGA-addressed changeset by diffing an existing RGA tree against
+ * a new mdast document.
+ *
+ * 1. Convert RGA tree → plain mdast
+ * 2. Diff old mdast vs new mdast → index-based ChangeSet
+ * 3. Convert each index-based Change to an RGAChange by resolving indices
+ *    to RGA node IDs via idAtIndex / predecessorForIndex
+ */
+export function generateRGAChangeSet(existing, newRoot, event) {
+    const oldMdast = toMdast(existing);
+    const changeset = mdastDiff(oldMdast, newRoot);
+    const rgaChanges = [];
+    for (const change of changeset.changes) {
+        const path = change.path;
+        // path = [...parentIndices, targetIndex]
+        // parentIndices navigate into nested RGAs, targetIndex is the operation target
+        const parentIndices = path.slice(0, -1);
+        const targetIndex = path[path.length - 1];
+        // Walk the RGA tree to resolve parent path to node IDs and find the target RGA
+        const parentIds = [];
+        let currentRGA = existing.children;
+        let valid = true;
+        for (const idx of parentIndices) {
+            const nodeId = currentRGA.idAtIndex(idx);
+            if (!nodeId) {
+                valid = false;
+                break;
+            }
+            parentIds.push(nodeId);
+            // Navigate into this node's children RGA
+            const nodeKey = `${nodeId.uuid}:${nodeId.event.toString()}`;
+            const node = currentRGA.nodes.get(nodeKey);
+            if (!node || !isRGAParent(node.value)) {
+                valid = false;
+                break;
+            }
+            currentRGA = node.value.children;
+        }
+        if (!valid)
+            continue;
+        // Now currentRGA is the RGA where the operation happens, resolve target/after IDs
+        switch (change.type) {
+            case "delete": {
+                const targetId = currentRGA.idAtIndex(targetIndex);
+                if (targetId) {
+                    rgaChanges.push({
+                        type: "delete",
+                        parentPath: parentIds,
+                        targetId,
+                    });
+                }
+                break;
+            }
+            case "insert": {
+                const afterId = currentRGA.predecessorForIndex(targetIndex);
+                rgaChanges.push({
+                    type: "insert",
+                    parentPath: parentIds,
+                    afterId,
+                    nodes: change.nodes,
+                });
+                break;
+            }
+            case "modify": {
+                const targetId = currentRGA.idAtIndex(targetIndex);
+                const afterId = currentRGA.predecessorForIndex(targetIndex);
+                if (targetId) {
+                    rgaChanges.push({
+                        type: "modify",
+                        parentPath: parentIds,
+                        targetId,
+                        afterId,
+                        nodes: change.nodes,
+                        before: change.before,
+                    });
+                }
+                break;
+            }
+        }
+    }
+    return { event, changes: rgaChanges };
+}
+/**
+ * Apply an RGA-addressed changeset to an RGA tree.
+ * Navigates by node IDs at every level — no index dependency.
+ */
+export function applyRGAChangeSet(root, changeset, compareEvents) {
+    const updatedChildren = cloneRGA(root.children);
+    for (const change of changeset.changes) {
+        // Navigate to the target RGA using parentPath node IDs
+        let currentRGA = updatedChildren;
+        let valid = true;
+        for (const parentId of change.parentPath) {
+            const nodeKey = `${parentId.uuid}:${parentId.event.toString()}`;
+            const node = currentRGA.nodes.get(nodeKey);
+            if (!node || !isRGAParent(node.value)) {
+                valid = false;
+                break;
+            }
+            currentRGA = node.value.children;
+        }
+        if (!valid)
+            continue;
+        switch (change.type) {
+            case "delete": {
+                if (change.targetId)
+                    currentRGA.delete(change.targetId);
+                break;
+            }
+            case "insert": {
+                for (const node of change.nodes ?? []) {
+                    const rgaNode = convertNode(node, changeset.event, compareEvents);
+                    currentRGA.insert(change.afterId, rgaNode, changeset.event);
+                }
+                break;
+            }
+            case "modify": {
+                if (change.targetId)
+                    currentRGA.delete(change.targetId);
+                for (const node of change.nodes ?? []) {
+                    const rgaNode = convertNode(node, changeset.event, compareEvents);
+                    currentRGA.insert(change.afterId, rgaNode, changeset.event);
+                }
+                break;
+            }
+        }
+    }
+    return { type: "root", children: updatedChildren };
+}

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+import type { RootContent, Parent } from "mdast";
+import { RGA, type RGANodeId, type RGAEvent, type EventComparator } from "./crdt/rga.js";
+export { RGA, type RGANodeId, type RGAEvent, type EventComparator };
+/** A changeset describing diffs between two mdast versions */
+export interface ChangeSet {
+    changes: Change[];
+}
+/** A single change at any depth in the mdast tree */
+export interface Change {
+    type: "insert" | "delete" | "modify";
+    /** Path into the tree, e.g. [2, 1, 0] = root.children[2].children[1].children[0] */
+    path: number[];
+    /** For insert/modify: the new mdast node(s) */
+    nodes?: RootContent[];
+    /** For modify: what it was before (for conflict detection) */
+    before?: RootContent[];
+}
+/** An RGA-addressed changeset — uses node IDs instead of indices */
+export interface RGAChangeSet<E extends RGAEvent = RGAEvent> {
+    event: E;
+    changes: RGAChange<E>[];
+}
+/** A single RGA-addressed change at any depth in the RGA tree */
+export interface RGAChange<E extends RGAEvent = RGAEvent> {
+    type: "insert" | "delete" | "modify";
+    /** Path of RGA node IDs from root to the parent containing this change (empty = root level) */
+    parentPath: RGANodeId<E>[];
+    /** For delete/modify: the target node to act on */
+    targetId?: RGANodeId<E>;
+    /** For insert/modify: insert after this node (undefined = insert at start) */
+    afterId?: RGANodeId<E>;
+    /** For insert/modify: the new mdast node(s) */
+    nodes?: RootContent[];
+    /** For modify: what it was before (for conflict detection) */
+    before?: RootContent[];
+}
+export type RGATreeNode<E extends RGAEvent = RGAEvent> = RGAParentNode<E> | RGALeafNode;
+export type RGALeafNode = Exclude<RootContent, Parent>;
+export interface RGAParentNode<E extends RGAEvent = RGAEvent> {
+    type: string;
+    children: RGA<RGATreeNode<E>, E>;
+    [key: string]: unknown;
+}
+export interface RGATreeRoot<E extends RGAEvent = RGAEvent> {
+    type: "root";
+    children: RGA<RGATreeNode<E>, E>;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+import { RGA, } from "./crdt/rga.js";
+export { RGA };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storacha/md-merge",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",