@magic-marker/prosemirror-suggest-changes 0.3.3-wrap-unwrap.10 → 0.3.3-wrap-unwrap.12

package/dist/__tests__/playwrightPage.d.ts

@@ -8,6 +8,7 @@ export declare class EditorPage {
     getParagraphText(index: number): Promise<string>;
     getParagraphCount(): Promise<number>;
     getProseMirrorMarkCount(name: string): Promise<number>;
+    getProseMirrorMarksJSON(): Promise<unknown[]>;
     getProseMirrorSelection(): Promise<{
         anchor: number;
         head: number;
@@ -19,4 +20,5 @@ export declare class EditorPage {
         expectedDoc: import("prosemirror-model").Node;
     }>;
     revertAll(): Promise<void>;
+    applyAll(): Promise<void>;
 }

package/dist/features/wrapUnwrap/revert/deleteNodeUpwards.js

@@ -1,31 +1,37 @@
+import { getNodeId } from "../getNodeId.js";
+const TRACE_ENABLED = true;
+function trace(...args) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!TRACE_ENABLED) return;
+    console.log("[deleteNodeUpwards]", "\n", ...args);
+}
 // delete a given node, and traverse upwards deleting parent nodes if they are now empty
 export function deleteNodeUpwards(transform, node, pos) {
     let $mappedPos = transform.doc.resolve(pos);
+    trace("attempting to delete node", node.type.name, getNodeId(node), "\n", "node subtree:\n", node.toString(), "\n", "node parent:", $mappedPos.parent.type.name, getNodeId($mappedPos.parent), "\n", {
+        node,
+        parent: $mappedPos.parent
+    });
     let deleteFrom = $mappedPos.pos;
     let deleteTo = $mappedPos.pos + node.nodeSize;
-    console.log("deleteNodeUpwards", "initial delete range covers node", node.toString(), {
-        deleteFrom,
-        deleteTo,
-        $mappedPos
-    });
     while($mappedPos.depth > 0){
         const $nextMappedPos = transform.doc.resolve($mappedPos.before());
-        console.log("deleteNodeUpwards", "considering", $nextMappedPos.nodeAfter?.toString(), "for deletion", "childCount is", $nextMappedPos.nodeAfter?.childCount);
-        if ($nextMappedPos.nodeAfter?.childCount !== 1) break;
-        console.log("deleteNodeUpwards", "expanding to deleting node", $nextMappedPos.nodeAfter.toString());
+        if ($nextMappedPos.nodeAfter?.childCount !== 1) {
+            trace("stopping deletion at non-empty node:", $nextMappedPos.nodeAfter?.type.name, $nextMappedPos.nodeAfter == null ? null : getNodeId($nextMappedPos.nodeAfter), "\n", "non-empty node parent:", $nextMappedPos.parent.type.name, getNodeId($nextMappedPos.parent), "\n", "non-empty node subtree:\n", $nextMappedPos.nodeAfter?.toString(), "\n", "non-empty node subtree direct children:\n", $nextMappedPos.nodeAfter?.children.map((child)=>`${child.type.name} ${getNodeId(child) ?? "null"}`).join(", "), {
+                nonEmptyNode: $nextMappedPos.nodeAfter,
+                nonEmptyNodeParent: $nextMappedPos.parent
+            });
+            break;
+        }
         $mappedPos = $nextMappedPos;
         deleteFrom = $nextMappedPos.pos;
         deleteTo = $nextMappedPos.pos + $nextMappedPos.nodeAfter.nodeSize;
-        console.log("deleteNodeUpwards", "expanded delete range to cover node", $nextMappedPos.nodeAfter.toString(), {
-            deleteFrom,
-            deleteTo,
-            $mappedPos: $nextMappedPos
-        });
     }
-    console.log("deleteNodeUpwards", "final delete range covers node", $mappedPos.nodeAfter?.toString(), {
-        deleteFrom,
-        deleteTo,
-        $mappedPos
+    trace("deleting subtree:\n", $mappedPos.nodeAfter?.toString(), "\n", "subtree root node:", $mappedPos.nodeAfter?.type.name, $mappedPos.nodeAfter == null ? null : getNodeId($mappedPos.nodeAfter), "\n", "subtree root parent node:", $mappedPos.parent.type.name, getNodeId($mappedPos.parent), "\n", "non-empty node subtree direct children:\n", $mappedPos.nodeAfter?.children.map((child)=>`${child.type.name} (${getNodeId(child) ?? "null"}`).join(", "), "\n", {
+        node: $mappedPos.nodeAfter,
+        parent: $mappedPos.parent,
+        $deleteFrom: $mappedPos.doc.resolve(deleteFrom),
+        $deleteTo: $mappedPos.doc.resolve(deleteTo)
     });
     transform.delete(deleteFrom, deleteTo);
 }

package/dist/features/wrapUnwrap/revert/index.d.ts

@@ -1,5 +1,5 @@
 import { Transform } from "prosemirror-transform";
 import { type Node } from "prosemirror-model";
 import { type SuggestionId } from "../../../generateId.js";
-export declare function revertAllStructureSuggestions(node: Node, from?: number, to?: number): Transform;
-export declare function revertStructureSuggestion(node: Node, suggestionId: SuggestionId): Transform;
+export declare function revertAllStructureSuggestions(doc: Node, from?: number, to?: number): Transform;
+export declare function revertStructureSuggestion(doc: Node, suggestionId: SuggestionId): Transform;

package/dist/features/wrapUnwrap/revert/index.js

@@ -1,20 +1,18 @@
 import { Transform } from "prosemirror-transform";
-import { revertStructureSuggestionsInNode } from "./revertStructureSuggestions.js";
-export function revertAllStructureSuggestions(node, from, to) {
-    const tr = new Transform(node);
-    revertStructureSuggestionsInNode({
+import { revertStructureSuggestionsInDoc } from "./revertStructureSuggestions.js";
+export function revertAllStructureSuggestions(doc, from, to) {
+    const tr = new Transform(doc);
+    revertStructureSuggestionsInDoc({
         tr,
-        node: tr.doc,
         from,
         to
     });
     return tr;
 }
-export function revertStructureSuggestion(node, suggestionId) {
-    const tr = new Transform(node);
-    revertStructureSuggestionsInNode({
+export function revertStructureSuggestion(doc, suggestionId) {
+    const tr = new Transform(doc);
+    revertStructureSuggestionsInDoc({
         tr,
-        node: tr.doc,
         suggestionId
     });
     return tr;

package/dist/features/wrapUnwrap/revert/revertAddOp.d.ts

@@ -1,4 +1,4 @@
 import { type Transform } from "prosemirror-transform";
 import { type AddOp } from "../types.js";
 import { type Node } from "prosemirror-model";
-export declare function revertAddOp(op: AddOp, tr: Transform, node: Node, pos: number): void;
+export declare function revertAddOp(_op: AddOp, tr: Transform, node: Node, pos: number): void;

package/dist/features/wrapUnwrap/revert/revertAddOp.js

@@ -1,9 +1,4 @@
 import { deleteNodeUpwards } from "./deleteNodeUpwards.js";
-export function revertAddOp(op, tr, node, pos) {
-    console.log("revertAddOp", "node", node.toString(), "was added at", pos, {
-        op,
-        node,
-        pos
-    });
+export function revertAddOp(_op, tr, node, pos) {
     deleteNodeUpwards(tr, node, pos);
 }

package/dist/features/wrapUnwrap/revert/revertMoveOp.js

@@ -1,14 +1,7 @@
 import { deleteNodeUpwards } from "./deleteNodeUpwards.js";
 import { getNodeId } from "../getNodeId.js";
 export function revertMoveOp(op, tr, node, pos) {
-    console.log("revertMoveOp", "node", node.toString(), "was moved from", op.from, {
-        op,
-        node
-    });
     const parent = getDeepestSurvivingParent(op.from, tr.doc);
-    console.log("revertMoveOp", "deepest surviving parent is", parent.node.toString(), {
-        parent
-    });
     const child = wrapNodeInParentChain(parent.remainingChain, node);
     const insertTo = findInsertionPos(parent.node, parent.pos, parent.parent, child);
     if (typeof insertTo === "number") {

package/dist/features/wrapUnwrap/revert/revertStructureSuggestions.d.ts

@@ -1,10 +1,8 @@
-import { type Node } from "prosemirror-model";
 import { type Mark } from "prosemirror-model";
 import { Transform } from "prosemirror-transform";
 import { type SuggestionId } from "../../../generateId.js";
-export declare function revertStructureSuggestionsInNode({ tr, node, suggestionId, from, to, }: {
+export declare function revertStructureSuggestionsInDoc({ tr, suggestionId, from, to, }: {
     tr: Transform;
-    node: Node;
     suggestionId?: SuggestionId;
     from?: number | undefined;
     to?: number | undefined;

package/dist/features/wrapUnwrap/revert/revertStructureSuggestions.js

@@ -6,52 +6,78 @@ import { sameParentChain } from "../sameParentChain.js";
 import { buildMaterializedPaths } from "../buildMaterializedPaths.js";
 import { revertAddOp } from "./revertAddOp.js";
 import { revertMoveOp } from "./revertMoveOp.js";
-export function revertStructureSuggestionsInNode({ tr, node, suggestionId, from, to }) {
-    const { structure } = getSuggestionMarks(node.type.schema);
-    // collect all structure mark ids
-    const suggestionIds = new Set();
-    node.descendants((node, pos)=>{
-        if (from !== undefined && pos < from) {
+const TRACE_ENABLED = true;
+function trace(...args) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (!TRACE_ENABLED) return;
+    console.log("[revertStructureSuggestions]", ...args);
+}
+export function revertStructureSuggestionsInDoc({ tr, suggestionId, from, to }) {
+    if (suggestionId) {
+        // when suggestionId is given, just revert it, no other logic required
+        revertStructureSuggestionWithPrerequisites(tr, suggestionId);
+        return;
+    }
+    if (from || to) {
+        // when range is given, find suggestion ids inside that range,
+        // but make sure to revert furthermost suggestions first
+        // todo: most likely a better strategy would be to search for the next suggestion in the updated doc after each reversal (and map from and to)
+        const { structure } = getSuggestionMarks(tr.doc.type.schema);
+        const structureMarks = [];
+        tr.doc.descendants((node, pos)=>{
+            if (from !== undefined && pos < from) {
+                return true;
+            }
+            if (to !== undefined && pos > to) {
+                return false;
+            }
+            if (node.isText) return true;
+            if (!structure.isInSet(node.marks)) return true;
+            node.marks.forEach((mark)=>{
+                if (mark.type !== structure) return;
+                structureMarks.push({
+                    mark,
+                    node,
+                    pos
+                });
+            });
             return true;
-        }
-        if (to !== undefined && pos > to) {
-            return false;
-        }
-        if (node.isText) return true;
-        if (!structure.isInSet(node.marks)) return true;
-        node.marks.forEach((mark)=>{
-            if (mark.type !== structure) return;
-            const markSuggestionId = mark.attrs["id"];
-            if (suggestionId != null && markSuggestionId !== suggestionId) return;
-            suggestionIds.add(markSuggestionId);
         });
-        return true;
-    });
-    for (const suggestionId of suggestionIds){
-        revertStructureSuggestionWithPrerequisites(tr, suggestionId);
+        structureMarks.sort((a, b)=>b.pos - a.pos);
+        const suggestionIds = new Set();
+        structureMarks.forEach(({ mark })=>{
+            suggestionIds.add(mark.attrs["id"]);
+        });
+        for (const suggestionId of suggestionIds){
+            revertStructureSuggestionWithPrerequisites(tr, suggestionId);
+        }
+        return;
+    }
+    // if no suggestion id nor range is given, revert all suggestions one by one, always take furthermost first
+    // after each reversal, the next suggestion is searched in the new doc after the previous reversal
+    let nextSuggestionId = findNextStructureSuggestion(tr.doc);
+    while(nextSuggestionId != null){
+        revertStructureSuggestionWithPrerequisites(tr, nextSuggestionId);
+        nextSuggestionId = findNextStructureSuggestion(tr.doc);
     }
 }
 function revertStructureSuggestionWithPrerequisites(tr, suggestionId) {
-    console.group("revertStructureMarkGroupInOrder", "reverting structure mark group", suggestionId);
     const suggestionIds = buildOrderedSuggestionIds(tr.doc, suggestionId, buildMaterializedPaths(tr.doc));
-    console.log("revertStructureMarkGroupInOrder", "suggestion groups to revert", suggestionIds);
+    trace("reverting structure suggestions: ", suggestionIds);
     for (const suggestionId of suggestionIds){
         revertOneStructureSuggestion(tr, suggestionId);
     }
-    console.groupEnd();
 }
 function revertOneStructureSuggestion(tr, suggestionId) {
-    console.group("revertStructureSuggestion", "reverting structure suggestion", suggestionId);
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (TRACE_ENABLED) console.group("reverting structure suggestion: ", suggestionId);
     let structureMark = findNextStructureMark(tr.doc, suggestionId);
     while(structureMark !== null){
-        console.groupCollapsed("revertStructureSuggestion", "reverting structure mark", structureMark.mark.attrs["id"], "at pos", structureMark.pos, "at node", structureMark.node.toString(), {
-            structureMark
-        });
         revertStructureMark(tr, structureMark.mark, structureMark.pos);
-        console.groupEnd();
         structureMark = findNextStructureMark(tr.doc, suggestionId);
     }
-    console.groupEnd();
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    if (TRACE_ENABLED) console.groupEnd();
 }
 export function revertStructureMark(tr, mark, pos) {
     const transform = new Transform(tr.doc);
@@ -60,11 +86,6 @@ export function revertStructureMark(tr, mark, pos) {
     if (!node) {
         throw new Error(`Node not found at position ${String(pos)}`);
     }
-    console.log("revertStructureMark", mark.attrs["id"], "at node", node.toString(), {
-        node,
-        mark,
-        pos
-    });
     const attrs = mark.attrs;
     if (!guardStructureMarkAttrs(attrs)) {
         console.warn("revertStructureMark", "invalid shape of structure mark attrs", {
@@ -73,6 +94,12 @@ export function revertStructureMark(tr, mark, pos) {
         return;
     }
     const op = attrs.data.op;
+    trace("reverting structure mark with suggestion id", attrs.id, "at node", node.toString(), "at pos", pos, "with op", op.op, {
+        mark,
+        node,
+        $pos: transform.doc.resolve(pos),
+        op
+    });
     switch(op.op){
         case "add":
             {
@@ -134,7 +161,6 @@ function buildOrderedSuggestionIds(node, suggestionId, materializedPaths) {
     if (mismatch == null) {
         return Array.from(suggestionIds).reverse();
     }
-    console.log("findOrderedSuggestionIdsToRevert", "suggestion", suggestionId, "contains mark with a mismatched 'to':", mismatch, "searching a different suggestion with the matching 'to'...");
     // find first mark on the node that does have a matching op.to
     const match = mismatch.node.marks.find((mark)=>{
         if (mark.type !== structure) return false;
@@ -148,25 +174,55 @@ function buildOrderedSuggestionIds(node, suggestionId, materializedPaths) {
         return sameParentChain(attrs.data.op.to, parentChain.chain);
     });
     if (match) {
-        console.log("findOrderedSuggestionIdsToRevert", "found suggestin with matching 'to'", match);
         suggestionIds.add(match.attrs["id"]);
     }
     return Array.from(suggestionIds).reverse();
 }
+function findNextStructureSuggestion(doc) {
+    const { structure } = getSuggestionMarks(doc.type.schema);
+    const structureMarks = [];
+    doc.descendants((node, pos)=>{
+        if (node.isText) return true;
+        if (!structure.isInSet(node.marks)) return true;
+        node.marks.forEach((mark)=>{
+            if (mark.type !== structure) return;
+            structureMarks.push({
+                mark,
+                node,
+                pos
+            });
+        });
+        return true;
+    });
+    structureMarks.sort((a, b)=>b.pos - a.pos);
+    return structureMarks[0]?.mark.attrs["id"];
+}
+// given a suggestion id, find next structure mark to revert that belongs to that suggestion
+// always take furthermost mark first
 function findNextStructureMark(node, suggestionId) {
     const { structure } = getSuggestionMarks(node.type.schema);
     const structureMarks = [];
     node.descendants((descendant, pos)=>{
+        // the assumption here is that a single node cannot have multiple structure marks with the same suggestion id
+        // check the invariant
+        const suggestionIds = new Set();
+        descendant.marks.forEach((mark)=>{
+            if (mark.type !== structure) return;
+            const markSuggestionId = mark.attrs["id"];
+            if (suggestionIds.has(markSuggestionId)) {
+                console.warn("node", node, "has multiple structure marks with the same suggestion id", markSuggestionId);
+            }
+            suggestionIds.add(markSuggestionId);
+        });
         const mark = descendant.marks.find((mark)=>mark.type === structure && mark.attrs["id"] === suggestionId);
         if (mark == null) return true;
         structureMarks.push({
             mark,
             node: descendant,
-            pos,
-            $pos: node.resolve(pos)
+            pos
         });
         return true;
     });
-    structureMarks.sort((a, b)=>b.$pos.depth - a.$pos.depth);
+    structureMarks.sort((a, b)=>b.pos - a.pos);
     return structureMarks[0] ?? null;
 }

package/dist/features/wrapUnwrap/structureChangesPlugin.d.ts

@@ -4,4 +4,7 @@ import { type SuggestionId } from "../../generateId.js";
 import { Transform } from "prosemirror-transform";
 export declare const structureChangesKey: PluginKey<any>;
 export declare function structureChangesPlugin(generateId?: (schema: Schema, doc?: Node) => SuggestionId): Plugin<any>;
-export declare function suggestStructureChanges(docBefore: Node, docAfter: Node, generateId?: (schema: Schema, doc?: Node) => SuggestionId): Transform;
+export declare function suggestStructureChanges(docBefore: Node, docAfter: Node, generateId?: (schema: Schema, doc?: Node) => SuggestionId): {
+    handled: boolean;
+    transform: Transform;
+};

package/dist/features/wrapUnwrap/structureChangesPlugin.js

@@ -2,6 +2,7 @@ import { Plugin, PluginKey } from "prosemirror-state";
 import { getSuggestionMarks } from "../../utils.js";
 import { generateNextNumberId } from "../../generateId.js";
 import { getNodeId } from "./getNodeId.js";
+import { guardStructureMarkAttrs } from "./types.js";
 import { LIST_NODES, STRUCTURE_CHANGES_ADD_MARKS } from "./constants.js";
 import { Transform } from "prosemirror-transform";
 import { isSuggestChangesEnabled, suggestChangesKey } from "../../plugin.js";
@@ -91,7 +92,7 @@ export function structureChangesPlugin(generateId) {
             trace("structureChangesPlugin", "appendTransaction", [
                 ...transactions
             ]);
-            const transform = suggestStructureChanges(oldDoc, newDoc, generateId);
+            const { transform } = suggestStructureChanges(oldDoc, newDoc, generateId);
             const tr = newState.tr;
             transform.steps.forEach((step)=>{
                 tr.step(step);
@@ -121,7 +122,10 @@ export function suggestStructureChanges(docBefore, docAfter, generateId) {
     });
     const transform = new Transform(docAfter);
     addMarks(ops, transform, suggestionId);
-    return transform;
+    return {
+        handled: ops.size > 0,
+        transform
+    };
 }
 function addMarks(ops, tr, suggestionId) {
     const perfAddMarks = performance.now();
@@ -132,6 +136,14 @@ function addMarks(ops, tr, suggestionId) {
         if (nodeId == null) return true;
         const op = ops.get(nodeId);
         if (op == null) return true;
+        if (op.op === "move") {
+            if (hasStructureAddMark(node)) return true;
+            const inverseMoveMark = findInverseStructureMoveMark(node, op);
+            if (inverseMoveMark) {
+                tr.removeNodeMark(pos, inverseMoveMark);
+                return true;
+            }
+        }
         tr.addNodeMark(pos, structure.create({
             id: suggestionId,
             data: {
@@ -142,6 +154,24 @@ function addMarks(ops, tr, suggestionId) {
     });
     trace("perf", "addMarks", "took", Number((performance.now() - perfAddMarks).toFixed(2)), "ms");
 }
+function findInverseStructureMoveMark(node, op) {
+    const { structure } = getSuggestionMarks(node.type.schema);
+    return node.marks.find((mark)=>{
+        if (mark.type !== structure) return false;
+        if (!guardStructureMarkAttrs(mark.attrs)) return false;
+        const existingOp = mark.attrs.data.op;
+        if (existingOp.op !== "move") return false;
+        return sameParentChain(existingOp.from, op.to) && sameParentChain(existingOp.to, op.from);
+    });
+}
+function hasStructureAddMark(node) {
+    const { structure } = getSuggestionMarks(node.type.schema);
+    return node.marks.some((mark)=>{
+        if (mark.type !== structure) return false;
+        if (!guardStructureMarkAttrs(mark.attrs)) return false;
+        return mark.attrs.data.op.op === "add";
+    });
+}
 function getOps(beforePaths, afterPaths) {
     const ops = new Map();
     // first take care of nodes that exist in both

package/dist/features/wrapUnwrap/types.d.ts

@@ -1,4 +1,5 @@
 import { type Attrs } from "prosemirror-model";
+import { type SuggestionId } from "../../generateId.js";
 interface NodeParent {
     nodeId: string;
     nodeType: string;
@@ -8,6 +9,7 @@ interface NodeParent {
     childIndex: number;
 }
 export interface StructureMarkAttrs {
+    id: SuggestionId;
     data: {
         op: Op;
     };

package/dist/withSuggestChanges.js

@@ -119,7 +119,7 @@ function getStepHandler(step) {
         const isEnabled = isSuggestChangesEnabled(this.state) && !tr.getMeta("history$") && !tr.getMeta("collab$") && !ySyncMeta.isUndoRedoOperation && !ySyncMeta.isChangeOrigin && !("skip" in (tr.getMeta(suggestChangesKey) ?? {}));
         let transaction = tr;
         if (isEnabled) {
-            let structureChangesTransform = null;
+            let structureChangesResult = null;
             const docBefore = transaction.docs[0];
             if (transaction.docChanged && docBefore && opts?.experimental_trackStructureChanges && typeof opts.experimental_ensureUniqueNodeIds === "function") {
                 trace("trying to track structure changes first...");
@@ -137,20 +137,20 @@ function getStepHandler(step) {
                 // if handled, then ignore the main plugin
                 // otherwise use the main plugin
                 const perfStructure = performance.now();
-                structureChangesTransform = suggestStructureChanges(docBefore, docAfter, generateId);
+                structureChangesResult = suggestStructureChanges(docBefore, docAfter, generateId);
                 trace("perf", "structure", "suggestStructureChanges took", Number((performance.now() - perfStructure).toFixed(2)), "ms");
-                trace("structure changes transform completed", structureChangesTransform);
-                if (structureChangesTransform.steps.length > 0) {
+                trace("structure changes transform completed", structureChangesResult.transform);
+                if (structureChangesResult.handled) {
                     uniqueNodeIdsTransform.steps.forEach((step)=>{
                         transaction.step(step);
                     });
-                    structureChangesTransform.steps.forEach((step)=>{
+                    structureChangesResult.transform.steps.forEach((step)=>{
                         transaction.step(step);
                     });
                     trace("applied unique id transform and structure changes transform to the transaction", transaction);
                 }
             }
-            if (transaction.docChanged && (structureChangesTransform == null || structureChangesTransform.steps.length === 0)) {
+            if (transaction.docChanged && structureChangesResult?.handled !== true) {
                 trace("running the main suggestions plugin...");
                 const perfSuggestions = performance.now();
                 transaction = transformToSuggestionTransaction(tr, this.state, generateId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magic-marker/prosemirror-suggest-changes",
-  "version": "0.3.3-wrap-unwrap.10",
+  "version": "0.3.3-wrap-unwrap.12",
   "license": "MIT",
   "type": "module",
   "module": "dist/index.js",

package/src/features/wrapUnwrap/README.md

@@ -1,127 +0,0 @@
-# ProseMirror Structure Changes Tracking
-
-Detect structural changes to list hierarchies and stores revertible operations
-as node marks — enabling suggestion mode for structural edits like wrapping,
-outdenting, and moving items between lists.
-
-## Prerequisites
-
-- All block nodes must have stable, unique string IDs via an `id` attribute.
-- Lists must follow `ListNode → ListItemNode → ContentNode[]` structure.
-- List item children must be block nodes, not text.
-- Nested lists are supported.
-
-## Core Idea
-
-The plugin compares two documents and determines what happened to each content
-node by comparing its **materialized path** — its full ancestor chain from
-immediate parent up to the document root.
-
-Marks are placed on **content nodes** (paragraphs, headings), not on lists or
-list items. Content nodes are the invariant — they survive wrapping and
-unwrapping. Lists and list items are created and destroyed around them, making
-them unsuitable as mark targets.
-
-Each `Parent` entry in the chain stores the parent's ID, type, attrs, marks,
-sibling IDs, and child index — enough to recreate the parent node during
-reversal and place the child at the correct position.
-
-## Detection
-
-The plugin builds materialized paths for the before-doc and after-doc, then
-cross-references them:
-
-- **Node in both, chain changed, list involved** → `move` op. Stores the
-  before-chain.
-- **Node only in after-doc, list involved** → `add` op. No positional data.
-- **Node only in before-doc** → deleted, no action.
-
-Chain equality means same length and matching node IDs at every level. Sibling
-or index changes alone don't count as a move — this avoids false positives from
-index compaction when a neighbor is removed.
-
-All ops from the same transaction share a suggestion ID for grouped revert.
-
-## Reversal
-
-### Reverting `move`
-
-1. Walk the stored before-chain top-down, verifying each ancestor exists **in
-   the correct parent** (not just anywhere in the doc). Stop at the first
-   mismatch — that's the deepest surviving ancestor.
-2. Recreate missing ancestors below the survivor using stored type/attrs/marks.
-3. Insert the reconstructed subtree into the survivor, positioned using stored
-   sibling IDs (right sibling first, then left, then end of parent as fallback).
-4. Delete the content node from its current location and prune empty ancestors
-   upward.
-
-### Reverting `add`
-
-Delete the node and prune empty ancestors.
-
-### Empty ancestor pruning
-
-After deletion, walk upward. At each level, if the parent has exactly one child
-(the one being removed), expand the deletion to include that parent. This avoids
-leaving behind empty list items or lists, and sidesteps ProseMirror's schema
-constraint that list items must have content.
-
-## Performance
-
-### Mark application
-
-Materialized path construction, operation derivation, and mark application are
-each O(N) where N is the number of nodes in the document. Can be potentially
-improved by not going into textblock nodes (to make sure text nodes are not
-visited). Parent chain comparison at each node is O(D) for nesting depth D
-(practically ≤ 10). **Effectively O(N) - linear.** Skipped entirely when
-`docChanged` is false.
-
-### Suggestion revert (explicit user action)
-
-**O(M × N)** where M is marks in the group. The dominant cost is rebuilding the
-node-to-children map and rescanning for the next mark after each individual
-revert. Negligible for typical documents; cacheable if needed for large docs
-with many grouped marks.
-
-## Known Limitations
-
-- **No reorder detection.** Same-list reordering is not tracked yet. The data is
-  stored (sibling IDs and indices), but detection requires comparing relative
-  order of surviving peers, not raw indices. Planned.
-
-- **No topological sorting of reverts.** Marks are reverted in document order.
-  If mark A depends on mark B recreating a needed ancestor first, A's revert
-  fails gracefully. Future improvement: build a dependency graph and
-  topologically sort before reverting.
-
-- **However**, a basic single-step dependency check is implemented. When the
-  plugin is asked to revert a suggestion X, it will verify that every structure
-  mark of this suggestion group has a destination parent chain that matches the
-  current parent chain of the node. If mismatch is found, it searches for a
-  different structure mark on the same node that has a matching parent chain. If
-  such mark is found, it's whole suggestion group Y will be reverted before
-  suggestion X. This one-level dependency check is limited (what if there are
-  multiple matching marks on the same node? What if the reversal destination is
-  unavailable?). A complete topological sort solution is required for that.
-
-- **Schema violations fail silently.** If a stored node type no longer accepts
-  the child being inserted (e.g., a list changed type), the ProseMirror step
-  fails and no rollback is attempted.
-
-## Design Decisions
-
-**Materialized paths over step interpretation.** ProseMirror's `ReplaceStep` and
-`ReplaceAroundStep` encode positional mutations, not semantic intent. A list
-split is a single `ReplaceStep` that's hard to decompose into "item X was
-outdented." Comparing ancestor chains gives direct semantic answers.
-
-**Materialized paths over JSON tree diffing.** Early design explored diffing
-list subtrees with jsondiffpatch. Abandoned because patch paths require
-interpretation to determine affected content nodes, cross-list moves appear as
-unrelated remove/add patches needing correlation, and map comparison answers
-"where was node X" directly.
-
-**Sibling IDs over indices for positioning.** Indices shift when neighbors
-change. Sibling IDs are stable. Index is stored alongside for future reorder
-detection but unused during revert.