roam-research-mcp 1.3.2 → 1.4.0

package/README.md

@@ -179,6 +179,7 @@ The server provides powerful tools for interacting with Roam Research:
 17. `roam_datomic_query`: Execute a custom Datomic query on the Roam graph for advanced data retrieval beyond the available search tools. Now supports client-side regex filtering for enhanced post-query processing. Optimal for complex filtering (including regex), highly complex boolean logic, arbitrary sorting criteria, and proximity search.
 18. `roam_markdown_cheatsheet`: Provides the content of the Roam Markdown Cheatsheet resource, optionally concatenated with custom instructions if `CUSTOM_INSTRUCTIONS_PATH` environment variable is set.
 19. `roam_process_batch_actions`: Execute a sequence of low-level block actions (create, update, move, delete) in a single, non-transactional batch. Provides granular control for complex nesting like tables. **Now includes pre-validation** that catches errors before API execution, with structured error responses and automatic rate limit retry with exponential backoff. (Note: For actions on existing blocks or within a specific page context, it is often necessary to first obtain valid page or block UIDs using tools like `roam_fetch_page_by_title`.)
+20. `roam_update_page_markdown`: Update an existing page with new markdown content using smart diff. **Preserves block UIDs** where possible, keeping references intact across the graph. Uses three-phase matching (exact text → normalized → position fallback) to generate minimal operations. Supports `dry_run` mode to preview changes. Ideal for syncing external markdown files, AI-assisted content updates, and batch modifications without losing block references.
 
 **Deprecated Tools**:
 The following tools have been deprecated as of `v0.36.2` in favor of the more powerful and flexible `roam_process_batch_actions`:
@@ -289,6 +290,25 @@ This demonstrates creating a new page with both text blocks and a table in a sin
 - A conclusion section"
 ```
 
+### Example 6: Updating a Page with Smart Diff
+
+This demonstrates updating an existing page while preserving block UIDs (and therefore block references across the graph).
+
+```
+"Update the 'Project Alpha Planning' page with this revised content, preserving block references:
+- Overview (keep existing UID)
+  - Updated Goals section
+  - Revised Scope with new details
+- Team Members
+  - John Doe (Senior Dev)
+  - Jane Smith (PM)
+  - New hire: Bob Wilson
+- Updated Timeline
+- Remove the old 'Deadlines' section"
+```
+
+The tool will match existing blocks by content, update changed text, add new blocks, and remove deleted ones - all while keeping UIDs stable for blocks that still exist.
+
 ---
 
 ## Setup

package/build/Roam_Markdown_Cheatsheet.md

@@ -71,10 +71,13 @@ Source:: https://example.com
 | `Step 1:: Do this thing` | `**Step 1:** Do this thing` | Step numbers are page-specific, not queryable concepts |
 | `Note:: Some observation` | Just write the text, or use `#note` | One-off labels don't need attribute syntax |
 | `Summary:: The main point` | `**Summary:** The main point` | Section headers are formatting, not metadata |
-| `Definition:: Some text` | `**Term**:: Definition` | Only use for actual definitions you want to query |
+| `Definition:: Some text` | `Term:: Definition` | Only use for actual definitions you want to query |
+| `Implementation Tier 3 (Societal Restructuring):: Some text` | `** Implementation Tier 3 (Societal Restructuring)**: Some text` | Label is specific to current concept |
 
 ⚠️ **The Test**: Ask yourself: "Will I ever query for all blocks with this attribute across my graph?" If no, use **bold formatting** (`**Label:**`) instead of `::` syntax.
 
+NOTE: Never combine bold markdown formatting with `::`. Roam formats attributes in bold by default. ✅ `<attribute>::` ❌ `**<attribute>**::`
+
 ---
 
 ## Block Structures
@@ -328,7 +331,7 @@ Empty blocks and decorative dividers create clutter. Roam's outliner structure p
 
 ### Definitions
 ```
-**Term**:: Definition text #definition #[[domain]]
+Term:: Definition text #definition #[[domain]]
 ```
 
 ### Questions for Future
@@ -456,6 +459,11 @@ When a tag would awkwardly affect sentence capitalization:
 [Cognitive biases]([[cognitive biases]]) affect decision-making...
 ```
 
+### Definitions (OVERRIDE)
+```
+#def [[<term>]] : <definition>
+```
+
 ---
 
 ## Constraints & Guardrails
@@ -465,6 +473,7 @@ When a tag would awkwardly affect sentence capitalization:
 - **Tag obvious/redundant** — If parent block is tagged, children inherit context
 - **Use inconsistent capitalization** — Tags are lowercase unless proper nouns
 - **Create orphan tags** — Check if existing page/tag serves the purpose
+- **Bold Attributes** - ❌ `**Attribute**::`, ✅ `Attribute::` (Roam auto-formats)
 
 ### DO
 - **Think retrieval-first** — How will you search for this later?

package/build/diff/actions.js

@@ -0,0 +1,93 @@
+/**
+ * Action Generator
+ *
+ * Generates correctly ordered batch actions from a DiffResult.
+ * The order is critical for Roam API correctness:
+ * 1. Creates (top-down to ensure parents exist before children)
+ * 2. Moves (reposition existing blocks)
+ * 3. Updates (text/heading changes)
+ * 4. Deletes (bottom-up; reverse order to delete children before parents)
+ */
+/**
+ * Generate a correctly ordered array of batch actions from a DiffResult.
+ *
+ * The ordering ensures:
+ * - Parent blocks are created before their children
+ * - Blocks are moved before text updates (in case moves affect siblings)
+ * - Children are deleted before their parents
+ *
+ * @param diff - The DiffResult containing categorized actions
+ * @returns Ordered array of batch actions ready for Roam API
+ */
+export function generateBatchActions(diff) {
+    const actions = [];
+    // 1. Creates (in markdown order, parents before children)
+    // The creates are already in the correct order from diffBlockTrees
+    actions.push(...diff.creates);
+    // 2. Moves (reposition existing blocks)
+    actions.push(...diff.moves);
+    // 3. Updates (text/heading changes)
+    actions.push(...diff.updates);
+    // 4. Deletes (reversed to delete children before parents)
+    // This is important because Roam will fail if you try to delete
+    // a parent block while it still has children
+    actions.push(...[...diff.deletes].reverse());
+    return actions;
+}
+/**
+ * Filter actions to only include specific action types.
+ * Useful for dry-run analysis or debugging.
+ */
+export function filterActions(actions, types) {
+    const typeSet = new Set(types);
+    return actions.filter((a) => typeSet.has(a.action));
+}
+/**
+ * Group actions by their type for analysis.
+ */
+export function groupActionsByType(actions) {
+    const creates = [];
+    const updates = [];
+    const moves = [];
+    const deletes = [];
+    for (const action of actions) {
+        switch (action.action) {
+            case 'create-block':
+                creates.push(action);
+                break;
+            case 'update-block':
+                updates.push(action);
+                break;
+            case 'move-block':
+                moves.push(action);
+                break;
+            case 'delete-block':
+                deletes.push(action);
+                break;
+        }
+    }
+    return { creates, updates, moves, deletes };
+}
+/**
+ * Summarize actions for logging purposes.
+ */
+export function summarizeActions(actions) {
+    const grouped = groupActionsByType(actions);
+    const parts = [];
+    if (grouped.creates.length > 0) {
+        parts.push(`${grouped.creates.length} create(s)`);
+    }
+    if (grouped.moves.length > 0) {
+        parts.push(`${grouped.moves.length} move(s)`);
+    }
+    if (grouped.updates.length > 0) {
+        parts.push(`${grouped.updates.length} update(s)`);
+    }
+    if (grouped.deletes.length > 0) {
+        parts.push(`${grouped.deletes.length} delete(s)`);
+    }
+    if (parts.length === 0) {
+        return 'No changes';
+    }
+    return parts.join(', ');
+}

package/build/diff/actions.test.js

@@ -0,0 +1,125 @@
+import { describe, it, expect } from 'vitest';
+import { generateBatchActions, filterActions, groupActionsByType, summarizeActions, } from './actions.js';
+describe('generateBatchActions', () => {
+    function createDiffResult(creates = [], updates = [], moves = [], deletes = []) {
+        return {
+            creates,
+            updates,
+            moves,
+            deletes,
+            preservedUids: new Set(),
+        };
+    }
+    it('returns actions in correct order: creates, moves, updates, deletes', () => {
+        const diff = createDiffResult([{ action: 'create-block', block: { string: 'new' }, location: { 'parent-uid': 'p', order: 0 } }], [{ action: 'update-block', block: { uid: 'u1', string: 'updated' } }], [{ action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } }], [{ action: 'delete-block', block: { uid: 'u3' } }]);
+        const actions = generateBatchActions(diff);
+        expect(actions[0].action).toBe('create-block');
+        expect(actions[1].action).toBe('move-block');
+        expect(actions[2].action).toBe('update-block');
+        expect(actions[3].action).toBe('delete-block');
+    });
+    it('reverses delete order for child-before-parent deletion', () => {
+        const diff = createDiffResult([], [], [], [
+            { action: 'delete-block', block: { uid: 'parent' } },
+            { action: 'delete-block', block: { uid: 'child' } },
+        ]);
+        const actions = generateBatchActions(diff);
+        // Deletes should be reversed
+        expect(actions[0].block.uid).toBe('child');
+        expect(actions[1].block.uid).toBe('parent');
+    });
+    it('returns empty array for empty diff', () => {
+        const diff = createDiffResult();
+        const actions = generateBatchActions(diff);
+        expect(actions).toEqual([]);
+    });
+    it('preserves all actions without modification', () => {
+        const createAction = {
+            action: 'create-block',
+            block: { uid: 'new1', string: 'Test', heading: 2 },
+            location: { 'parent-uid': 'page', order: 0 },
+        };
+        const diff = createDiffResult([createAction]);
+        const actions = generateBatchActions(diff);
+        expect(actions[0]).toEqual(createAction);
+    });
+});
+describe('filterActions', () => {
+    const allActions = [
+        { action: 'create-block', block: { string: 'new' }, location: { 'parent-uid': 'p', order: 0 } },
+        { action: 'update-block', block: { uid: 'u1', string: 'updated' } },
+        { action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } },
+        { action: 'delete-block', block: { uid: 'u3' } },
+    ];
+    it('filters to only specified action types', () => {
+        const creates = filterActions(allActions, ['create-block']);
+        expect(creates.length).toBe(1);
+        expect(creates[0].action).toBe('create-block');
+    });
+    it('supports multiple action types', () => {
+        const modifying = filterActions(allActions, ['create-block', 'update-block']);
+        expect(modifying.length).toBe(2);
+    });
+    it('returns empty array when no matches', () => {
+        const emptyActions = [];
+        const result = filterActions(emptyActions, ['create-block']);
+        expect(result).toEqual([]);
+    });
+});
+describe('groupActionsByType', () => {
+    it('groups actions by their type', () => {
+        const actions = [
+            { action: 'create-block', block: { string: 'a' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'create-block', block: { string: 'b' }, location: { 'parent-uid': 'p', order: 1 } },
+            { action: 'update-block', block: { uid: 'u1', string: 'c' } },
+            { action: 'delete-block', block: { uid: 'u2' } },
+        ];
+        const grouped = groupActionsByType(actions);
+        expect(grouped.creates.length).toBe(2);
+        expect(grouped.updates.length).toBe(1);
+        expect(grouped.moves.length).toBe(0);
+        expect(grouped.deletes.length).toBe(1);
+    });
+    it('returns empty arrays for missing types', () => {
+        const actions = [];
+        const grouped = groupActionsByType(actions);
+        expect(grouped.creates).toEqual([]);
+        expect(grouped.updates).toEqual([]);
+        expect(grouped.moves).toEqual([]);
+        expect(grouped.deletes).toEqual([]);
+    });
+});
+describe('summarizeActions', () => {
+    it('summarizes action counts', () => {
+        const actions = [
+            { action: 'create-block', block: { string: 'a' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'create-block', block: { string: 'b' }, location: { 'parent-uid': 'p', order: 1 } },
+            { action: 'update-block', block: { uid: 'u1', string: 'c' } },
+            { action: 'delete-block', block: { uid: 'u2' } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('2 create(s), 1 update(s), 1 delete(s)');
+    });
+    it('returns "No changes" for empty actions', () => {
+        const summary = summarizeActions([]);
+        expect(summary).toBe('No changes');
+    });
+    it('only includes non-zero counts', () => {
+        const actions = [
+            { action: 'update-block', block: { uid: 'u1', string: 'updated' } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('1 update(s)');
+        expect(summary).not.toContain('create');
+        expect(summary).not.toContain('move');
+        expect(summary).not.toContain('delete');
+    });
+    it('includes moves when present', () => {
+        const actions = [
+            { action: 'move-block', block: { uid: 'u1' }, location: { 'parent-uid': 'p', order: 0 } },
+            { action: 'move-block', block: { uid: 'u2' }, location: { 'parent-uid': 'p', order: 1 } },
+        ];
+        const summary = summarizeActions(actions);
+        expect(summary).toBe('2 move(s)');
+    });
+});

package/build/diff/diff.js

@@ -0,0 +1,155 @@
+/**
+ * Diff Computation
+ *
+ * Computes the minimal set of batch actions needed to transform
+ * existing blocks into the desired new block structure.
+ */
+import { flattenExistingBlocks } from './parser.js';
+import { matchBlocks, normalizeText } from './matcher.js';
+/**
+ * Compute the diff between existing blocks and desired new blocks.
+ *
+ * This function:
+ * 1. Matches new blocks to existing blocks by content similarity
+ * 2. For matched blocks: generates update/move actions as needed
+ * 3. For unmatched new blocks: generates create actions
+ * 4. For unmatched existing blocks: generates delete actions
+ *
+ * @param existing - Array of existing block trees
+ * @param newBlocks - Flat array of new blocks (desired state)
+ * @param parentUid - UID of the parent page/block
+ * @returns DiffResult with categorized actions
+ */
+export function diffBlockTrees(existing, newBlocks, parentUid) {
+    const result = {
+        creates: [],
+        updates: [],
+        moves: [],
+        deletes: [],
+        preservedUids: new Set(),
+    };
+    // Flatten existing blocks for matching
+    const existingFlat = flattenExistingBlocks(existing);
+    // Step 1: Match blocks by content
+    const matches = matchBlocks(existingFlat, newBlocks);
+    // Build uid -> ExistingBlock mapping
+    const existingByUid = new Map(existingFlat.map((eb) => [eb.uid, eb]));
+    /**
+     * Resolve the desired parent UID for a new block.
+     * If the parent was matched to an existing block, use that UID.
+     */
+    function desiredParentUid(newBlock) {
+        if (!newBlock.parentRef)
+            return parentUid;
+        const parentNewUid = newBlock.parentRef.blockUid;
+        if (parentNewUid === parentUid)
+            return parentUid;
+        // If parent is matched, target the existing parent UID
+        return matches.get(parentNewUid) ?? parentNewUid;
+    }
+    // Build desired structure: map each new block to its desired parent
+    // and group siblings by their desired parent
+    const newUidToDesiredParent = new Map();
+    const siblingsByDesiredParent = new Map();
+    for (const newBlock of newBlocks) {
+        const newUid = newBlock.ref.blockUid;
+        const targetUid = matches.get(newUid) ?? newUid;
+        const dParent = desiredParentUid(newBlock);
+        newUidToDesiredParent.set(newUid, dParent);
+        if (!siblingsByDesiredParent.has(dParent)) {
+            siblingsByDesiredParent.set(dParent, []);
+        }
+        siblingsByDesiredParent.get(dParent).push(targetUid);
+    }
+    // Step 2: Process each new block
+    for (const newBlock of newBlocks) {
+        const newUid = newBlock.ref.blockUid;
+        if (matches.has(newUid)) {
+            // Block matched to an existing block
+            const existUid = matches.get(newUid);
+            const existBlock = existingByUid.get(existUid);
+            const currentParent = existBlock.parentUid ?? parentUid;
+            const dParent = newUidToDesiredParent.get(newUid);
+            result.preservedUids.add(existUid);
+            // Check for text/heading changes -> update-block
+            let needsUpdate = false;
+            const updateAction = {
+                action: 'update-block',
+                block: { uid: existUid },
+            };
+            if (normalizeText(newBlock.text) !== normalizeText(existBlock.text)) {
+                updateAction.block.string = newBlock.text;
+                needsUpdate = true;
+            }
+            if (newBlock.heading !== existBlock.heading) {
+                if (newBlock.heading !== null) {
+                    updateAction.block.heading = newBlock.heading;
+                    needsUpdate = true;
+                }
+                else if (existBlock.heading !== null) {
+                    // Remove heading by setting to 0
+                    updateAction.block.heading = 0;
+                    needsUpdate = true;
+                }
+            }
+            if (needsUpdate) {
+                result.updates.push(updateAction);
+            }
+            // Check for parent/order changes -> move-block
+            const desiredSiblings = siblingsByDesiredParent.get(dParent) ?? [];
+            const desiredOrder = desiredSiblings.indexOf(existUid);
+            if (currentParent !== dParent || existBlock.order !== desiredOrder) {
+                result.moves.push({
+                    action: 'move-block',
+                    block: { uid: existUid },
+                    location: { 'parent-uid': dParent, order: desiredOrder },
+                });
+            }
+        }
+        else {
+            // No match -> create-block
+            const dParent = newUidToDesiredParent.get(newUid);
+            const desiredSiblings = siblingsByDesiredParent.get(dParent) ?? [];
+            const desiredOrder = desiredSiblings.indexOf(newUid);
+            const createAction = {
+                action: 'create-block',
+                location: {
+                    'parent-uid': dParent,
+                    order: desiredOrder >= 0 ? desiredOrder : 'last',
+                },
+                block: {
+                    uid: newBlock.ref.blockUid,
+                    string: newBlock.text,
+                },
+            };
+            if (newBlock.heading !== null) {
+                createAction.block.heading = newBlock.heading;
+            }
+            if (newBlock.open !== undefined) {
+                createAction.block.open = newBlock.open;
+            }
+            result.creates.push(createAction);
+        }
+    }
+    // Step 3: Find unmatched existing blocks -> delete
+    const matchedExistingUids = new Set(matches.values());
+    for (const existBlock of existingFlat) {
+        if (!matchedExistingUids.has(existBlock.uid)) {
+            result.deletes.push({
+                action: 'delete-block',
+                block: { uid: existBlock.uid },
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Diff blocks at a specific level (for hierarchical diffing).
+ * Used internally for recursive tree comparison.
+ */
+export function diffBlockLevel(existing, newBlocks, parentUid) {
+    // Filter to only blocks at this level (direct children of parentUid)
+    const existingAtLevel = existing.filter((e) => e.parentUid === parentUid || e.parentUid === null);
+    const newAtLevel = newBlocks.filter((n) => n.parentRef?.blockUid === parentUid || (!n.parentRef && parentUid === parentUid));
+    return diffBlockTrees(existingAtLevel, newAtLevel, parentUid);
+}

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);
+        });
+    });
+});