roam-research-mcp 1.0.0 → 1.4.0

package/build/diff/diff.test.js

@@ -0,0 +1,202 @@
+import { describe, it, expect } from 'vitest';
+import { diffBlockTrees } from './diff.js';
+describe('diffBlockTrees', () => {
+    const pageUid = 'page123';
+    // Helper to create test blocks
+    function createExisting(uid, text, order, heading = null, children = []) {
+        return { uid, text, order, heading, children, parentUid: null };
+    }
+    function createNew(blockUid, text, order, heading = null) {
+        return {
+            ref: { blockUid },
+            text,
+            parentRef: { blockUid: pageUid },
+            order,
+            open: true,
+            heading,
+        };
+    }
+    describe('No changes scenario', () => {
+        it('returns empty diff when content is identical', () => {
+            const existing = [
+                createExisting('uid1', 'First', 0),
+                createExisting('uid2', 'Second', 1),
+            ];
+            const newBlocks = [createNew('new1', 'First', 0), createNew('new2', 'Second', 1)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.creates.length).toBe(0);
+            expect(diff.updates.length).toBe(0);
+            expect(diff.moves.length).toBe(0);
+            expect(diff.deletes.length).toBe(0);
+            expect(diff.preservedUids.size).toBe(2);
+        });
+    });
+    describe('Create operations', () => {
+        it('generates create actions for new blocks', () => {
+            const existing = [];
+            const newBlocks = [createNew('new1', 'New block', 0)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.creates.length).toBe(1);
+            expect(diff.creates[0].action).toBe('create-block');
+            expect(diff.creates[0].block.string).toBe('New block');
+        });
+        it('generates creates for unmatched new blocks', () => {
+            const existing = [createExisting('uid1', 'Existing', 0)];
+            const newBlocks = [
+                createNew('new1', 'Existing', 0),
+                createNew('new2', 'Brand new', 1),
+            ];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.creates.length).toBe(1);
+            expect(diff.creates[0].block.string).toBe('Brand new');
+        });
+    });
+    describe('Update operations', () => {
+        it('generates update when text changes', () => {
+            const existing = [createExisting('uid1', 'Old text', 0)];
+            // Position-based fallback will match with ≤3 blocks
+            const newBlocks = [createNew('new1', 'New text', 0)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.updates.length).toBe(1);
+            expect(diff.updates[0].action).toBe('update-block');
+            expect(diff.updates[0].block.uid).toBe('uid1');
+            expect(diff.updates[0].block.string).toBe('New text');
+        });
+        it('generates update when heading changes', () => {
+            const existing = [createExisting('uid1', 'Title', 0, null)];
+            const newBlocks = [createNew('new1', 'Title', 0, 2)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.updates.length).toBe(1);
+            expect(diff.updates[0].block.heading).toBe(2);
+        });
+        it('removes heading when changed to null', () => {
+            const existing = [createExisting('uid1', 'Title', 0, 2)];
+            const newBlocks = [createNew('new1', 'Title', 0, null)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.updates.length).toBe(1);
+            expect(diff.updates[0].block.heading).toBe(0); // 0 removes heading
+        });
+        it('does not generate update when content is same', () => {
+            const existing = [createExisting('uid1', 'Same', 0)];
+            const newBlocks = [createNew('new1', 'Same', 0)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.updates.length).toBe(0);
+        });
+    });
+    describe('Move operations', () => {
+        it('generates move when order changes', () => {
+            const existing = [
+                createExisting('uid1', 'First', 0),
+                createExisting('uid2', 'Second', 1),
+            ];
+            // Swap order
+            const newBlocks = [createNew('new1', 'Second', 0), createNew('new2', 'First', 1)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            // At least one move should be generated
+            expect(diff.moves.length).toBeGreaterThan(0);
+        });
+    });
+    describe('Delete operations', () => {
+        it('generates delete for removed blocks', () => {
+            const existing = [
+                createExisting('uid1', 'Keep', 0),
+                createExisting('uid2', 'Remove', 1),
+            ];
+            const newBlocks = [createNew('new1', 'Keep', 0)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.deletes.length).toBe(1);
+            expect(diff.deletes[0].action).toBe('delete-block');
+            expect(diff.deletes[0].block.uid).toBe('uid2');
+        });
+        it('generates deletes for all blocks when new content is empty', () => {
+            const existing = [
+                createExisting('uid1', 'First', 0),
+                createExisting('uid2', 'Second', 1),
+            ];
+            const newBlocks = [];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.deletes.length).toBe(2);
+        });
+    });
+    describe('Preserved UIDs', () => {
+        it('tracks preserved UIDs for matched blocks', () => {
+            const existing = [
+                createExisting('uid1', 'Matched', 0),
+                createExisting('uid2', 'Also matched', 1),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Matched', 0),
+                createNew('new2', 'Also matched', 1),
+            ];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.preservedUids.has('uid1')).toBe(true);
+            expect(diff.preservedUids.has('uid2')).toBe(true);
+        });
+        it('does not include unmatched blocks in preserved UIDs', () => {
+            const existing = [createExisting('uid1', 'Will be deleted', 0)];
+            const newBlocks = [createNew('new1', 'Completely different', 0)];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            // Position fallback matches these (≤3), so uid1 is preserved
+            expect(diff.preservedUids.has('uid1')).toBe(true);
+        });
+    });
+    describe('Mixed operations', () => {
+        it('handles text update with matching', () => {
+            const existing = [
+                createExisting('uid1', 'Keep this', 0),
+                createExisting('uid2', 'Update this', 1),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Keep this', 0),
+                createNew('new2', 'Update this - modified', 1),
+            ];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            // uid1 matches exactly, uid2 matched by position, gets updated
+            expect(diff.preservedUids.size).toBe(2);
+            expect(diff.updates.length).toBe(1);
+            expect(diff.updates[0].block.string).toBe('Update this - modified');
+        });
+        it('handles additions and deletions', () => {
+            // Use >3 blocks to avoid position fallback for unmatched
+            const existing = [
+                createExisting('uid1', 'Keep A', 0),
+                createExisting('uid2', 'Keep B', 1),
+                createExisting('uid3', 'Delete C', 2),
+                createExisting('uid4', 'Delete D', 3),
+                createExisting('uid5', 'Delete E', 4),
+                createExisting('uid6', 'Delete F', 5),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Keep A', 0),
+                createNew('new2', 'Keep B', 1),
+                createNew('new3', 'Add G', 2),
+                createNew('new4', 'Add H', 3),
+                createNew('new5', 'Add I', 4),
+                createNew('new6', 'Add J', 5),
+            ];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            // 2 matched (Keep A, Keep B), 4 new created, 4 old deleted
+            expect(diff.preservedUids.size).toBe(2);
+            expect(diff.creates.length).toBe(4);
+            expect(diff.deletes.length).toBe(4);
+        });
+        it('handles reordering with moves', () => {
+            const existing = [
+                createExisting('uid1', 'First', 0),
+                createExisting('uid2', 'Second', 1),
+                createExisting('uid3', 'Third', 2),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Third', 0), // uid3 -> 0
+                createNew('new2', 'First', 1), // uid1 -> 1
+                createNew('new3', 'Second', 2), // uid2 -> 2
+            ];
+            const diff = diffBlockTrees(existing, newBlocks, pageUid);
+            expect(diff.preservedUids.size).toBe(3);
+            expect(diff.creates.length).toBe(0);
+            expect(diff.deletes.length).toBe(0);
+            // At least some moves expected for reordering
+            expect(diff.moves.length).toBeGreaterThan(0);
+        });
+    });
+});

package/build/diff/index.js

@@ -0,0 +1,43 @@
+/**
+ * Smart Diff Algorithm
+ *
+ * This module provides a diff algorithm for computing minimal update operations
+ * when syncing markdown content to Roam Research. It preserves block UIDs where
+ * possible and generates efficient batch actions.
+ *
+ * Usage:
+ * ```typescript
+ * import {
+ *   parseExistingBlocks,
+ *   markdownToBlocks,
+ *   diffBlockTrees,
+ *   generateBatchActions,
+ *   getDiffStats
+ * } from './diff/index.js';
+ *
+ * // 1. Parse existing page data
+ * const existing = parseExistingBlocks(pageData);
+ *
+ * // 2. Convert new markdown to block structure
+ * const newBlocks = markdownToBlocks(markdown, pageUid);
+ *
+ * // 3. Compute diff
+ * const diff = diffBlockTrees(existing, newBlocks, pageUid);
+ *
+ * // 4. Generate ordered batch actions
+ * const actions = generateBatchActions(diff);
+ *
+ * // 5. Check stats
+ * const stats = getDiffStats(diff);
+ * console.log(`Preserved ${stats.preserved} UIDs`);
+ * ```
+ */
+export { getDiffStats, isDiffEmpty } from './types.js';
+// Parser
+export { parseExistingBlock, parseExistingBlocks, flattenExistingBlocks, markdownToBlocks, getBlockDepth, } from './parser.js';
+// Matcher
+export { normalizeText, normalizeForMatching, matchBlocks, groupByParent } from './matcher.js';
+// Diff
+export { diffBlockTrees, diffBlockLevel } from './diff.js';
+// Actions
+export { generateBatchActions, filterActions, groupActionsByType, summarizeActions, } from './actions.js';

package/build/diff/matcher.js

@@ -0,0 +1,118 @@
+/**
+ * Block Matcher
+ *
+ * Matches new blocks to existing blocks using a three-phase strategy:
+ * 1. Exact text match
+ * 2. Normalized text match (removes list prefixes)
+ * 3. Position-based fallback (conservative, only for small sets)
+ */
+/**
+ * Normalize text for exact matching.
+ * Trims whitespace only.
+ */
+export function normalizeText(text) {
+    return text.trim();
+}
+/**
+ * Normalize text for fuzzy matching.
+ * Removes list prefixes (1. , 2. , etc.) in addition to trimming.
+ */
+export function normalizeForMatching(text) {
+    return text.trim().replace(/^\d+\.\s+/, '');
+}
+/**
+ * Match new blocks to existing blocks using a three-phase strategy.
+ *
+ * Phase 1: Exact text match
+ * - Compare normalized text (trimmed whitespace)
+ * - When multiple candidates exist, prefer the one closest to same position
+ *
+ * Phase 2: Normalized text match
+ * - Remove list prefixes before matching
+ * - Handles cases where markdown adds numbering that Roam doesn't have
+ *
+ * Phase 3: Position-based fallback
+ * - Only used when ≤3 unmatched blocks remain on each side
+ * - Conservative to avoid incorrect matches
+ *
+ * @param existing - Flat array of existing blocks
+ * @param newBlocks - Array of new blocks to match
+ * @returns Map of newUid -> existingUid for matched blocks
+ */
+export function matchBlocks(existing, newBlocks) {
+    const matches = new Map(); // newUid -> existingUid
+    const usedExisting = new Set();
+    // Build indices for efficient lookups
+    const existingByText = new Map();
+    const existingByNormalized = new Map();
+    for (const eb of existing) {
+        // Index by exact normalized text
+        const normText = normalizeText(eb.text);
+        if (!existingByText.has(normText)) {
+            existingByText.set(normText, []);
+        }
+        existingByText.get(normText).push(eb);
+        // Index by matching-normalized text (without list prefixes)
+        const matchText = normalizeForMatching(eb.text);
+        if (!existingByNormalized.has(matchText)) {
+            existingByNormalized.set(matchText, []);
+        }
+        existingByNormalized.get(matchText).push(eb);
+    }
+    // Phase 1: Exact text matches
+    newBlocks.forEach((newBlock, idx) => {
+        const normText = normalizeText(newBlock.text);
+        const candidates = (existingByText.get(normText) ?? []).filter((e) => !usedExisting.has(e.uid));
+        if (candidates.length > 0) {
+            // Prefer candidate closest to same position
+            const best = candidates.reduce((a, b) => Math.abs(a.order - idx) < Math.abs(b.order - idx) ? a : b);
+            matches.set(newBlock.ref.blockUid, best.uid);
+            usedExisting.add(best.uid);
+        }
+    });
+    // Phase 2: Normalized text matches (without list prefixes)
+    newBlocks.forEach((newBlock, idx) => {
+        if (matches.has(newBlock.ref.blockUid))
+            return;
+        const matchText = normalizeForMatching(newBlock.text);
+        const candidates = (existingByNormalized.get(matchText) ?? []).filter((e) => !usedExisting.has(e.uid));
+        if (candidates.length > 0) {
+            const best = candidates.reduce((a, b) => Math.abs(a.order - idx) < Math.abs(b.order - idx) ? a : b);
+            matches.set(newBlock.ref.blockUid, best.uid);
+            usedExisting.add(best.uid);
+        }
+    });
+    // Phase 3: Position-based fallback (conservative)
+    const unmatchedNew = newBlocks.filter((b) => !matches.has(b.ref.blockUid));
+    const unmatchedExisting = existing.filter((e) => !usedExisting.has(e.uid));
+    // Only use position matching when few blocks remain (avoid false matches)
+    if (unmatchedNew.length <= 3 && unmatchedExisting.length <= 3) {
+        const sortedExisting = [...unmatchedExisting].sort((a, b) => a.order - b.order);
+        unmatchedNew.forEach((newBlock, idx) => {
+            if (idx < sortedExisting.length) {
+                const existBlock = sortedExisting[idx];
+                matches.set(newBlock.ref.blockUid, existBlock.uid);
+                usedExisting.add(existBlock.uid);
+            }
+        });
+    }
+    return matches;
+}
+/**
+ * Group blocks by their parent UID for sibling analysis.
+ */
+export function groupByParent(blocks) {
+    const groups = new Map();
+    for (const block of blocks) {
+        const parentKey = block.parentUid;
+        if (!groups.has(parentKey)) {
+            groups.set(parentKey, []);
+        }
+        groups.get(parentKey).push(block);
+    }
+    // Sort each group by order
+    for (const [, siblings] of groups) {
+        siblings.sort((a, b) => a.order - b.order);
+    }
+    return groups;
+}

package/build/diff/matcher.test.js

@@ -0,0 +1,198 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeText, normalizeForMatching, matchBlocks, groupByParent } from './matcher.js';
+describe('normalizeText', () => {
+    it('trims whitespace', () => {
+        expect(normalizeText('  hello  ')).toBe('hello');
+        expect(normalizeText('\thello\n')).toBe('hello');
+    });
+    it('preserves internal whitespace', () => {
+        expect(normalizeText('hello world')).toBe('hello world');
+    });
+    it('handles empty strings', () => {
+        expect(normalizeText('')).toBe('');
+        expect(normalizeText('   ')).toBe('');
+    });
+});
+describe('normalizeForMatching', () => {
+    it('removes numbered list prefixes', () => {
+        expect(normalizeForMatching('1. First item')).toBe('First item');
+        expect(normalizeForMatching('2. Second item')).toBe('Second item');
+        expect(normalizeForMatching('10. Tenth item')).toBe('Tenth item');
+    });
+    it('preserves non-list text', () => {
+        expect(normalizeForMatching('Regular text')).toBe('Regular text');
+        expect(normalizeForMatching('- Bullet point')).toBe('- Bullet point');
+    });
+    it('trims whitespace', () => {
+        expect(normalizeForMatching('  1. Item  ')).toBe('Item');
+    });
+});
+describe('matchBlocks', () => {
+    // Helper to create test blocks
+    function createExisting(uid, text, order) {
+        return { uid, text, order, heading: null, children: [], parentUid: null };
+    }
+    function createNew(blockUid, text, order) {
+        return {
+            ref: { blockUid },
+            text,
+            parentRef: null,
+            order,
+            open: true,
+            heading: null,
+        };
+    }
+    describe('Phase 1: Exact text match', () => {
+        it('matches blocks with identical text', () => {
+            const existing = [createExisting('uid1', 'Hello world', 0)];
+            const newBlocks = [createNew('new1', 'Hello world', 0)];
+            const matches = matchBlocks(existing, newBlocks);
+            expect(matches.get('new1')).toBe('uid1');
+        });
+        it('matches multiple blocks with same text by position', () => {
+            const existing = [
+                createExisting('uid1', 'Item', 0),
+                createExisting('uid2', 'Item', 1),
+                createExisting('uid3', 'Item', 2),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Item', 0),
+                createNew('new2', 'Item', 1),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            // Should prefer position-closest matches
+            expect(matches.get('new1')).toBe('uid1');
+            expect(matches.get('new2')).toBe('uid2');
+        });
+        it('handles no matches when too many unmatched for position fallback', () => {
+            // Need >3 on each side to avoid position-based fallback
+            const existing = [
+                createExisting('uid1', 'A', 0),
+                createExisting('uid2', 'B', 1),
+                createExisting('uid3', 'C', 2),
+                createExisting('uid4', 'D', 3),
+            ];
+            const newBlocks = [
+                createNew('new1', 'W', 0),
+                createNew('new2', 'X', 1),
+                createNew('new3', 'Y', 2),
+                createNew('new4', 'Z', 3),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            expect(matches.size).toBe(0);
+        });
+        it('uses position fallback when ≤3 unmatched on each side', () => {
+            const existing = [createExisting('uid1', 'Hello', 0)];
+            const newBlocks = [createNew('new1', 'Goodbye', 0)];
+            const matches = matchBlocks(existing, newBlocks);
+            // Position fallback matches by position
+            expect(matches.size).toBe(1);
+            expect(matches.get('new1')).toBe('uid1');
+        });
+    });
+    describe('Phase 2: Normalized text match', () => {
+        it('matches blocks when list prefix differs', () => {
+            const existing = [createExisting('uid1', 'First item', 0)];
+            const newBlocks = [createNew('new1', '1. First item', 0)];
+            const matches = matchBlocks(existing, newBlocks);
+            expect(matches.get('new1')).toBe('uid1');
+        });
+        it('matches numbered list items to plain text', () => {
+            const existing = [
+                createExisting('uid1', 'Apple', 0),
+                createExisting('uid2', 'Banana', 1),
+            ];
+            const newBlocks = [
+                createNew('new1', '1. Apple', 0),
+                createNew('new2', '2. Banana', 1),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            expect(matches.get('new1')).toBe('uid1');
+            expect(matches.get('new2')).toBe('uid2');
+        });
+    });
+    describe('Phase 3: Position-based fallback', () => {
+        it('matches by position when few unmatched blocks remain', () => {
+            const existing = [
+                createExisting('uid1', 'Completely different', 0),
+                createExisting('uid2', 'Also different', 1),
+            ];
+            const newBlocks = [
+                createNew('new1', 'Brand new text', 0),
+                createNew('new2', 'Another new text', 1),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            // With ≤3 unmatched on each side, should use position fallback
+            expect(matches.get('new1')).toBe('uid1');
+            expect(matches.get('new2')).toBe('uid2');
+        });
+        it('does not use position fallback when too many unmatched', () => {
+            const existing = [
+                createExisting('uid1', 'A', 0),
+                createExisting('uid2', 'B', 1),
+                createExisting('uid3', 'C', 2),
+                createExisting('uid4', 'D', 3),
+            ];
+            const newBlocks = [
+                createNew('new1', 'W', 0),
+                createNew('new2', 'X', 1),
+                createNew('new3', 'Y', 2),
+                createNew('new4', 'Z', 3),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            // With >3 unmatched, should not use position fallback
+            expect(matches.size).toBe(0);
+        });
+    });
+    describe('Mixed matching scenarios', () => {
+        it('prioritizes exact match over normalized match', () => {
+            const existing = [
+                createExisting('uid1', '1. Item', 0),
+                createExisting('uid2', 'Item', 1),
+            ];
+            const newBlocks = [createNew('new1', 'Item', 0)];
+            const matches = matchBlocks(existing, newBlocks);
+            // Should match exact text 'Item' not normalized '1. Item'
+            expect(matches.get('new1')).toBe('uid2');
+        });
+        it('uses each existing block only once', () => {
+            const existing = [createExisting('uid1', 'Same text', 0)];
+            const newBlocks = [
+                createNew('new1', 'Same text', 0),
+                createNew('new2', 'Same text', 1),
+            ];
+            const matches = matchBlocks(existing, newBlocks);
+            // Only one match should occur
+            expect(matches.size).toBe(1);
+            expect(matches.get('new1')).toBe('uid1');
+            expect(matches.has('new2')).toBe(false);
+        });
+    });
+});
+describe('groupByParent', () => {
+    function createExisting(uid, order, parentUid) {
+        return { uid, text: '', order, heading: null, children: [], parentUid };
+    }
+    it('groups blocks by parent UID', () => {
+        const blocks = [
+            createExisting('a', 0, null),
+            createExisting('b', 1, null),
+            createExisting('c', 0, 'parent1'),
+            createExisting('d', 1, 'parent1'),
+            createExisting('e', 0, 'parent2'),
+        ];
+        const groups = groupByParent(blocks);
+        expect(groups.get(null)?.map((b) => b.uid)).toEqual(['a', 'b']);
+        expect(groups.get('parent1')?.map((b) => b.uid)).toEqual(['c', 'd']);
+        expect(groups.get('parent2')?.map((b) => b.uid)).toEqual(['e']);
+    });
+    it('sorts blocks within each group by order', () => {
+        const blocks = [
+            createExisting('a', 2, null),
+            createExisting('b', 0, null),
+            createExisting('c', 1, null),
+        ];
+        const groups = groupByParent(blocks);
+        expect(groups.get(null)?.map((b) => b.uid)).toEqual(['b', 'c', 'a']);
+    });
+});

package/build/diff/parser.js

@@ -0,0 +1,114 @@
+/**
+ * Block Parser
+ *
+ * Parses Roam API block data into ExistingBlock structures
+ * and provides utilities for flattening block trees.
+ */
+import { generateBlockUid, parseMarkdown } from '../markdown-utils.js';
+/**
+ * Parse a raw Roam API block into an ExistingBlock structure.
+ * Recursively processes children and sorts them by order.
+ *
+ * @param roamBlock - Raw block data from Roam API
+ * @param parentUid - UID of the parent block (null for page-level blocks)
+ * @returns Parsed ExistingBlock with normalized structure
+ */
+export function parseExistingBlock(roamBlock, parentUid = null) {
+    const childrenRaw = roamBlock[':block/children'] ?? [];
+    const childrenSorted = [...childrenRaw].sort((a, b) => (a[':block/order'] ?? 0) - (b[':block/order'] ?? 0));
+    const uid = roamBlock[':block/uid'] ?? '';
+    const children = childrenSorted.map((c) => parseExistingBlock(c, uid));
+    return {
+        uid,
+        text: roamBlock[':block/string'] ?? '',
+        order: roamBlock[':block/order'] ?? 0,
+        heading: roamBlock[':block/heading'] ?? null,
+        children,
+        parentUid,
+    };
+}
+/**
+ * Parse all top-level blocks from a Roam page into ExistingBlock structures.
+ *
+ * @param pageData - Raw page data from Roam API (with :block/children)
+ * @returns Array of ExistingBlock for all top-level blocks
+ */
+export function parseExistingBlocks(pageData) {
+    const childrenRaw = pageData[':block/children'] ?? [];
+    const childrenSorted = [...childrenRaw].sort((a, b) => (a[':block/order'] ?? 0) - (b[':block/order'] ?? 0));
+    return childrenSorted.map((c) => parseExistingBlock(c, null));
+}
+/**
+ * Flatten a tree of existing blocks into a single array.
+ * Preserves parent-child relationships through parentUid property.
+ *
+ * @param blocks - Array of ExistingBlock trees
+ * @returns Flat array of all blocks in depth-first order
+ */
+export function flattenExistingBlocks(blocks) {
+    const result = [];
+    function flatten(block) {
+        result.push(block);
+        for (const child of block.children) {
+            flatten(child);
+        }
+    }
+    for (const block of blocks) {
+        flatten(block);
+    }
+    return result;
+}
+/**
+ * Convert markdown content into NewBlock structures ready for diffing.
+ *
+ * @param markdown - GFM markdown content
+ * @param pageUid - UID of the page (used as root parent)
+ * @returns Array of NewBlock structures representing desired state
+ */
+export function markdownToBlocks(markdown, pageUid) {
+    // Parse markdown into nested structure
+    const nodes = parseMarkdown(markdown);
+    const blocks = [];
+    // Track parent refs by level for nesting
+    const parentRefByLevel = [null];
+    /**
+     * Recursively convert markdown nodes to NewBlock structures.
+     */
+    function processNode(node, parentRef, siblingIndex) {
+        const blockUid = generateBlockUid();
+        const ref = { blockUid };
+        const newBlock = {
+            ref,
+            text: node.content,
+            parentRef,
+            order: siblingIndex,
+            open: true,
+            heading: node.heading_level ?? null,
+        };
+        blocks.push(newBlock);
+        // Process children with this block as parent
+        node.children.forEach((child, idx) => {
+            processNode(child, ref, idx);
+        });
+    }
+    // Process all root nodes
+    nodes.forEach((node, idx) => {
+        processNode(node, { blockUid: pageUid }, idx);
+    });
+    return blocks;
+}
+/**
+ * Get the depth of a block in the tree (0 for root blocks).
+ */
+export function getBlockDepth(block, blocks) {
+    let depth = 0;
+    let current = block;
+    while (current.parentRef) {
+        const parent = blocks.find((b) => b.ref.blockUid === current.parentRef?.blockUid);
+        if (!parent || parent === current)
+            break;
+        depth++;
+        current = parent;
+    }
+    return depth;
+}