@magic-marker/prosemirror-suggest-changes 0.4.1-wrap-unwrap.2 → 0.4.1-wrap-unwrap.3

package/dist/features/ensureValidSelection/ensureSelectionPlugin.js

@@ -36,6 +36,8 @@ export function ensureSelection() {
                 const newState = {
                     ...state
                 };
+                // remember if one of the keys we care about was pressed
+                // this is needed for appendTransaction
                 newState.handleKeyDown.backspace = event.key === "Backspace";
                 newState.handleKeyDown.delete = event.key === "Delete";
                 newState.handleKeyDown.arrowLeft = event.key === "ArrowLeft";
@@ -53,8 +55,10 @@ export function ensureSelection() {
                 return null;
             }
             if (isPosValid(newState.selection.$anchor) && isPosValid(newState.selection.$head)) {
+                // both selection positions are valid, no action needed
                 return null;
             }
+            // find new valid selection anchor and head
             // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
             if (TRACE_ENABLED) console.groupCollapsed("[ensureSelectionPlugin]", "appendTransaction");
             trace("appendTransaction", "search for new valid $anchor...");
@@ -71,6 +75,7 @@ export function ensureSelection() {
             $newHead = $newHead ?? newState.selection.$head;
             const newSelection = new TextSelection($newAnchor, $newHead);
             if (newSelection.anchor === newState.selection.anchor && newSelection.head === newState.selection.head) {
+                // new selection is the same as old selection, no action needed
                 trace("appendTransaction", "new selection is the same as old selection, skipping", {
                     $newAnchor,
                     $newHead,
@@ -106,11 +111,13 @@ function isPosValid($pos) {
 }
 function findNextValidPos($initialPos) {
     let $pos = $initialPos;
-    // to keep searching for the next valid pos we need non-null nodeAfter so we can go right or non-root depth so we can go up
+    // to keep searching for the next valid pos,
+    // we need a non-null nodeAfter so we can go right
+    // or a non-root depth so we can go up
     while(!isPosValid($pos) && ($pos.nodeAfter != null || $pos.depth > 0)){
         // first check if we can go into nodeAfter
         if ($pos.nodeAfter != null) {
-            // if nodeAfter is inline, we can step into it and search for the valid pos in it
+            // if nodeAfter is inline, we can step into it and search for the valid pos inside
             if ($pos.nodeAfter.isInline) {
                 // nodeAfter is inline - move in by one
                 $pos = $pos.doc.resolve($pos.pos + 1);
@@ -141,7 +148,9 @@ function findNextValidPos($initialPos) {
 }
 function findPreviousValidPos($initialPos) {
     let $pos = $initialPos;
-    // in order to be able to keep searching, we need either nodeBefore so we can go left, or non-root depth so we can go up
+    // in order to be able to keep searching,
+    // we need either a nodeBefore so we can go left,
+    // or a non-root depth so we can go up
     while(!isPosValid($pos) && ($pos.nodeBefore != null || $pos.depth > 0)){
         // first check if we can go into nodeBefore
         if ($pos.nodeBefore != null) {
@@ -159,7 +168,7 @@ function findPreviousValidPos($initialPos) {
                 });
                 if (localEndPos !== null) {
                     // we have a local ending position of the last inline descendant - convert it to global position
-                    // move pos to start of node before, add 1 to "enter" nodeBefore, then add local pos
+                    // move pos to start of nodeBefore, add 1 to "enter" nodeBefore, then add local pos
                     $pos = $pos.doc.resolve($pos.pos - $pos.nodeBefore.nodeSize + 1 + localEndPos);
                 } else {
                     // unable to find last inline descendant of nodeBefore - just skip nodeBefore altogether
@@ -173,11 +182,19 @@ function findPreviousValidPos($initialPos) {
     }
     return isPosValid($pos) ? $pos : null;
 }
-function findNearestValidPosInSameParent($initialPos) {
+/**
+ * Given a ResolvedPos, find closest valid pos within the same parent
+ *
+ * @param $initialPos
+ * @returns
+ */ function findNearestValidPosInSameParent($initialPos) {
     if (!$initialPos.parent.inlineContent) return null;
     const start = $initialPos.start();
     const end = $initialPos.end();
+    // take larger distance - either to the start or to the end of the parent node
     const maxDistance = Math.max($initialPos.pos - start, end - $initialPos.pos);
+    // for each distance in range [0, maxDistance],
+    // check if position within that distance from both sides is valid
     for(let distance = 0; distance <= maxDistance; distance++){
         const nextPos = $initialPos.pos + distance;
         if (nextPos <= end) {
@@ -196,6 +213,9 @@ function getNewValidPosInSelectionDestinationParent($oldPos, $newPos) {
     if (isPosValid($newPos)) return null;
     if ($oldPos.parent === $newPos.parent) return null;
     if (!$newPos.parent.inlineContent) return null;
+    // For selection-only transactions, keep the cursor inside the destination
+    // textblock when possible. Jumping across block boundaries makes arrow-key
+    // navigation feel like it skipped content.
     const $sameParentPos = findNearestValidPosInSameParent($newPos);
     trace("getNewValidPosInSelectionDestinationParent", "$sameParentPos", $sameParentPos?.pos, {
         $oldPos,
@@ -266,6 +286,9 @@ function getNewValidPos($oldPos, $newPos, isSelectionOnly, pluginState) {
     return $sameParentPos ?? getNewValidPosByDirection($newPos, getDirection($oldPos, $newPos, pluginState));
 }
 function getDirection($oldPos, $newPos, pluginState) {
+    // Position movement does not always reveal user intent. Backspace can leave
+    // the mapped selection at the same or unexpected position after suggestion
+    // markers are inserted, so preserve the keydown direction and search left.
     if (pluginState?.handleKeyDown.backspace) return "left";
     if ($newPos.pos > $oldPos.pos) return "right";
     if ($newPos.pos < $oldPos.pos) return "left";

package/dist/features/ensureValidSelection/selectionPosition.js

@@ -37,9 +37,9 @@ export function getInvalidSelectionPositionReason($pos) {
     if (insertionBefore && insertionAfter && isZWSPBefore && isZWSPAfter) {
         return "between-two-zwsp-insertions";
     }
-    if (insertionBefore && isZWSPBefore && $pos.nodeAfter == null && // A position like this:
-    // <p><insertion>ZWSP</insertion>|</p>
-    // because it means this paragraph was just created and it's empty.
+    if (insertionBefore && isZWSPBefore && $pos.nodeAfter == null && // A trailing inserted ZWSP is invalid only when it is acting as a boundary
+    // marker beside real content. In an otherwise empty paragraph it is the
+    // only editable anchor, so the cursor must be allowed there.
     $pos.parent.textContent.replace(ZWSP_REGEXP, "") !== "") {
         return "between-zwsp-insertion-and-right-node-boundary";
     }

package/dist/features/joinBlocks/index.js

@@ -40,9 +40,10 @@ export const joinBlocks = (trackedTransaction, stepFrom, stepTo, insertionMarkTy
             to: from + 1
         });
     }
+    // Join from the deepest/rightmost boundary first so earlier joins do not
+    // invalidate the recorded positions for later joins and insertion cleanup.
     pairs.reverse();
     insertedRanges.reverse();
-    // step 3: join blocks at multiple depths as needed
     for (const p of pairs){
         const fromPos = p.left?.pos;
         const toPos = p.right?.pos;
@@ -54,7 +55,9 @@ export const joinBlocks = (trackedTransaction, stepFrom, stepTo, insertionMarkTy
             trackedTransaction.join(pos, depth);
         }
     }
-    // step 4: remove inserted ranges
+    // Insertion-marked content is accepted by deletion, so it is physically
+    // removed after joins. Map through the join steps because those positions were
+    // collected in the pre-join document.
     const joinSteps = trackedTransaction.steps.slice(startStep);
     const joinMapping = new Mapping(joinSteps.map((s)=>s.getMap()));
     for (const range of insertedRanges){

package/dist/features/joinBlocks/utils/getZWSPPairsInRange.js

@@ -6,12 +6,13 @@ export const getZWSPPairsInRange = (doc, from, to, insertionMarkType)=>{
     const pairs = [];
     let currentEndingZWSP = previousZWSP;
     doc.nodesBetween(from, to, (node, pos, parent, index)=>{
-        // two cases: we have a left in currentPair and we're at 0 index
+        // A split block is represented by matching insertion ZWSP anchors at the
+        // end of the left block and the start of the right block. Pair only anchors
+        // with the same suggestion ID so unrelated insertion marks are not joined.
         const insertionMarkId = insertionMarkType.isInSet(node.marks)?.attrs["id"];
         if (currentEndingZWSP && index === 0 && node.text?.[0] === ZWSP && insertionMarkId && currentEndingZWSP.id === insertionMarkId && // Prevent self-pairing: don't pair a ZWSP with itself when both
         // the previousZWSP and the current node's ZWSP are at the same position
         currentEndingZWSP.pos !== pos) {
-            // maybe it's pos + 1
             pairs.push({
                 left: currentEndingZWSP,
                 right: {
@@ -21,11 +22,10 @@ export const getZWSPPairsInRange = (doc, from, to, insertionMarkType)=>{
                     id: insertionMarkId
                 }
             });
-        // don't return yet, we'll have to check if this text node contains
         }
         if (node.isText) {
-            // WE HAVE TO remove ending zwsp anyway. Either we found a pair, on the beginning of the next block
-            // or we did not, but then we don't have a matching pair on a block boundary.
+            // Once real text is encountered, the previous ending anchor can no longer
+            // describe the next block boundary.
             currentEndingZWSP = undefined;
         }
         const lastTextInParent = node.isText && parent?.childCount === index + 1;

package/dist/features/startToStartTextblockDeletion/index.js

@@ -16,6 +16,9 @@ export function adjustForStartToStartTextblockDeletion(selection, step, prevStep
             to: step.to
         };
     }
+    // ProseMirror can represent a start-to-start textblock selection as a block
+    // boundary deletion. The user-visible deletion ends at the selection head,
+    // not at the start token of the right textblock.
     const { $from, $to } = selection;
     if (!$from.parent.isTextblock || !$to.parent.isTextblock) {
         return {

package/dist/features/transactionShaping/detectSpecialTransactionShape.js

@@ -1,4 +1,5 @@
+import { detectProseMirrorSplitBlockAfterSelectionDelete } from "./proseMirrorSplitBlockAfterSelectionDelete/index.js";
 import { detectTipTapParagraphIntoListJoin } from "./tipTapParagraphIntoListJoin/detectTipTapParagraphIntoListJoin.js";
 export function detectSpecialTransactionShape(transaction) {
-    return detectTipTapParagraphIntoListJoin(transaction);
+    return detectProseMirrorSplitBlockAfterSelectionDelete(transaction) ?? detectTipTapParagraphIntoListJoin(transaction);
 }

package/dist/features/transactionShaping/index.js

@@ -1,5 +1,10 @@
+import { handleProseMirrorSplitBlockAfterSelectionDelete } from "./proseMirrorSplitBlockAfterSelectionDelete/index.js";
 import { handleTipTapParagraphIntoListJoin } from "./tipTapParagraphIntoListJoin/index.js";
 const specialTransactionShapeHandlers = [
+    // Handlers are ordered from most direct fallthrough to partial reshaping.
+    // A whole-transaction main-route escape should claim its shape before any
+    // handler tries to split a compound transaction into structure/main phases.
+    handleProseMirrorSplitBlockAfterSelectionDelete,
     handleTipTapParagraphIntoListJoin
 ];
 export function handleSpecialTransactionShape(args) {

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/detectProseMirrorSplitBlockAfterSelectionDelete.d.ts

@@ -0,0 +1,20 @@
+import { type Transaction } from "prosemirror-state";
+import { type ProseMirrorSplitBlockAfterSelectionDeleteShape } from "../types.js";
+/**
+ * Detect a Transaction of a certain shape
+ * The shape that occurs when there is a non empty selection across multiple nodes,
+ * followed by an Enter keypress
+ *
+ * A two-step transaction is produced - first step deletes the selection,
+ * second step splits the final selection-containing node
+ *
+ * That second split triggers the structure tracking code path - not the main code path
+ * which causes the selection deletion to be lost in time
+ *
+ * So we bail this transaction shape out of the structure tracking,
+ * and let the main code path handle it with deletion + insertion marks
+ *
+ * @param transaction
+ * @returns
+ */
+export declare function detectProseMirrorSplitBlockAfterSelectionDelete(transaction: Transaction): ProseMirrorSplitBlockAfterSelectionDeleteShape | null;

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/detectProseMirrorSplitBlockAfterSelectionDelete.js

@@ -0,0 +1,66 @@
+import { ReplaceStep, Transform } from "prosemirror-transform";
+import { getNodeId } from "../../wrapUnwrap/getNodeId.js";
+/**
+ * Detect a Transaction of a certain shape
+ * The shape that occurs when there is a non empty selection across multiple nodes,
+ * followed by an Enter keypress
+ *
+ * A two-step transaction is produced - first step deletes the selection,
+ * second step splits the final selection-containing node
+ *
+ * That second split triggers the structure tracking code path - not the main code path
+ * which causes the selection deletion to be lost in time
+ *
+ * So we bail this transaction shape out of the structure tracking,
+ * and let the main code path handle it with deletion + insertion marks
+ *
+ * @param transaction
+ * @returns
+ */ export function detectProseMirrorSplitBlockAfterSelectionDelete(transaction) {
+    // a 2-step transaction
+    if (transaction.steps.length !== 2) return null;
+    const [deleteStep, splitStep] = transaction.steps;
+    if (!(deleteStep instanceof ReplaceStep) || !(splitStep instanceof ReplaceStep)) {
+        return null;
+    }
+    // non-empty deletion step
+    if (deleteStep.from >= deleteStep.to) return null;
+    if (deleteStep.slice.content.size !== 0) return null;
+    if (hasStructureFlag(deleteStep)) return null;
+    // there is a docBefore, and step boundaries are in the different textblocks
+    const docBefore = transaction.docs[0];
+    if (!docBefore) return null;
+    if (!docBefore.resolve(deleteStep.from).parent.isTextblock) return null;
+    if (!docBefore.resolve(deleteStep.to).parent.isTextblock) return null;
+    // non empty split step
+    if (splitStep.from !== splitStep.to) return null;
+    // split step happens at the deletion step "from"
+    if (splitStep.from !== deleteStep.from) return null;
+    if (!hasStructureFlag(splitStep)) return null;
+    if (splitStep.slice.openStart !== 1 || splitStep.slice.openEnd !== 1) {
+        return null;
+    }
+    if (splitStep.slice.content.childCount !== 2) return null;
+    const leftSplitChild = splitStep.slice.content.child(0);
+    const rightSplitChild = splitStep.slice.content.child(1);
+    if (!leftSplitChild.isTextblock || !rightSplitChild.isTextblock) return null;
+    const leftSplitChildId = getNodeId(leftSplitChild);
+    if (!leftSplitChildId || getNodeId(rightSplitChild) !== leftSplitChildId) {
+        return null;
+    }
+    try {
+        const preview = new Transform(docBefore);
+        preview.step(deleteStep);
+        preview.step(splitStep);
+    } catch  {
+        return null;
+    }
+    return {
+        type: "proseMirrorSplitBlockAfterSelectionDelete",
+        deleteStep,
+        splitStep
+    };
+}
+function hasStructureFlag(step) {
+    return step.structure === true;
+}

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/detectProseMirrorSplitBlockAfterSelectionDelete.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/detectProseMirrorSplitBlockAfterSelectionDelete.test.js

@@ -0,0 +1,144 @@
+import { EditorState } from "prosemirror-state";
+import { Step } from "prosemirror-transform";
+import { describe, expect, it } from "vitest";
+import { createSchema } from "../../../testing/e2eTestSchema.js";
+import { detectProseMirrorSplitBlockAfterSelectionDelete } from "./detectProseMirrorSplitBlockAfterSelectionDelete.js";
+const schema = createSchema();
+const LIST_BOUNDARY_DOC = {
+    type: "doc",
+    content: [
+        {
+            type: "orderedList",
+            attrs: {
+                id: "node-0"
+            },
+            content: [
+                1,
+                2,
+                3,
+                4,
+                5
+            ].map((index)=>({
+                    type: "listItem",
+                    attrs: {
+                        id: `node-${String(index * 2 - 1)}`
+                    },
+                    content: [
+                        {
+                            type: "paragraph",
+                            attrs: {
+                                id: `node-${String(index * 2)}`
+                            },
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `Item ${String(index)}`
+                                }
+                            ]
+                        }
+                    ]
+                }))
+        }
+    ]
+};
+const DELETE_STEP = {
+    stepType: "replace",
+    from: 17,
+    to: 27
+};
+const SPLIT_STEP = {
+    stepType: "replace",
+    from: 17,
+    to: 17,
+    slice: {
+        content: [
+            {
+                type: "paragraph",
+                attrs: {
+                    id: "node-4"
+                }
+            },
+            {
+                type: "paragraph",
+                attrs: {
+                    id: "node-4"
+                }
+            }
+        ],
+        openStart: 1,
+        openEnd: 1
+    },
+    structure: true
+};
+function createTransaction(stepsJSON) {
+    const doc = schema.nodeFromJSON(LIST_BOUNDARY_DOC);
+    const transaction = EditorState.create({
+        doc
+    }).tr;
+    stepsJSON.forEach((stepJSON)=>{
+        transaction.step(Step.fromJSON(schema, stepJSON));
+    });
+    return transaction;
+}
+describe("detectProseMirrorSplitBlockAfterSelectionDelete", ()=>{
+    it("detects ProseMirror's deleteSelection plus splitBlock transaction shape", ()=>{
+        const transaction = createTransaction([
+            DELETE_STEP,
+            SPLIT_STEP
+        ]);
+        const shape = detectProseMirrorSplitBlockAfterSelectionDelete(transaction);
+        expect(shape).toMatchObject({
+            type: "proseMirrorSplitBlockAfterSelectionDelete",
+            deleteStep: {
+                from: 17,
+                to: 27
+            },
+            splitStep: {
+                from: 17,
+                to: 17
+            }
+        });
+    });
+    it("rejects the deletion half by itself", ()=>{
+        const transaction = createTransaction([
+            DELETE_STEP
+        ]);
+        expect(detectProseMirrorSplitBlockAfterSelectionDelete(transaction)).toBe(null);
+    });
+    it("rejects a split step that is not structural", ()=>{
+        const transaction = createTransaction([
+            DELETE_STEP,
+            {
+                ...SPLIT_STEP,
+                structure: false
+            }
+        ]);
+        expect(detectProseMirrorSplitBlockAfterSelectionDelete(transaction)).toBe(null);
+    });
+    it("rejects split children without a shared node id", ()=>{
+        const transaction = createTransaction([
+            DELETE_STEP,
+            {
+                ...SPLIT_STEP,
+                slice: {
+                    ...SPLIT_STEP.slice,
+                    content: [
+                        {
+                            type: "paragraph",
+                            attrs: {
+                                id: "node-4"
+                            }
+                        },
+                        {
+                            type: "paragraph",
+                            attrs: {
+                                id: "node-5"
+                            }
+                        }
+                    ]
+                }
+            }
+        ]);
+        expect(detectProseMirrorSplitBlockAfterSelectionDelete(transaction)).toBe(null);
+    });
+});

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/handleProseMirrorSplitBlockAfterSelectionDelete.d.ts

@@ -0,0 +1,3 @@
+import { type Transaction } from "prosemirror-state";
+import { type HandleSpecialTransactionShapeArgs } from "../types.js";
+export declare function handleProseMirrorSplitBlockAfterSelectionDelete(args: HandleSpecialTransactionShapeArgs): Transaction | null;

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/handleProseMirrorSplitBlockAfterSelectionDelete.js

@@ -0,0 +1,11 @@
+import { transformToSuggestionTransaction } from "../../../transformToSuggestionTransaction.js";
+import { detectProseMirrorSplitBlockAfterSelectionDelete } from "./detectProseMirrorSplitBlockAfterSelectionDelete.js";
+export function handleProseMirrorSplitBlockAfterSelectionDelete(args) {
+    if (!detectProseMirrorSplitBlockAfterSelectionDelete(args.transaction)) {
+        return null;
+    }
+    // Unlike the TipTap join shape, both steps belong to the main suggestion
+    // route: deletion marks preserve the selected content, and split handling
+    // marks the created split side. Structure tracking would drop the deletion.
+    return transformToSuggestionTransaction(args.transaction, args.state, args.generateId);
+}

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/index.d.ts

@@ -0,0 +1,2 @@
+export { detectProseMirrorSplitBlockAfterSelectionDelete } from "./detectProseMirrorSplitBlockAfterSelectionDelete.js";
+export { handleProseMirrorSplitBlockAfterSelectionDelete } from "./handleProseMirrorSplitBlockAfterSelectionDelete.js";

package/dist/features/transactionShaping/proseMirrorSplitBlockAfterSelectionDelete/index.js

@@ -0,0 +1,2 @@
+export { detectProseMirrorSplitBlockAfterSelectionDelete } from "./detectProseMirrorSplitBlockAfterSelectionDelete.js";
+export { handleProseMirrorSplitBlockAfterSelectionDelete } from "./handleProseMirrorSplitBlockAfterSelectionDelete.js";

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

@@ -10,7 +10,12 @@ export interface TipTapParagraphIntoListJoinShape {
     joinStep: ReplaceStep;
     movedNode: Node;
 }
-export type SpecialTransactionShape = TipTapParagraphIntoListJoinShape;
+export interface ProseMirrorSplitBlockAfterSelectionDeleteShape {
+    type: "proseMirrorSplitBlockAfterSelectionDelete";
+    deleteStep: ReplaceStep;
+    splitStep: ReplaceStep;
+}
+export type SpecialTransactionShape = TipTapParagraphIntoListJoinShape | ProseMirrorSplitBlockAfterSelectionDeleteShape;
 export interface HandleSpecialTransactionShapeArgs {
     transaction: Transaction;
     state: EditorState;

package/dist/features/wrapUnwrap/__tests__/boundarySelectionRevert.playwright.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/features/wrapUnwrap/buildMaterializedPaths.js

@@ -54,7 +54,8 @@ export function buildMaterializedPaths(doc) {
         const leftSiblingId = leftSibling ? getNodeId(leftSibling) : null;
         const rightSibling = parent.children[childIndex + 1];
         const rightSiblingId = rightSibling ? getNodeId(rightSibling) : null;
-        // (this node parent chain) is (parent chain of the parent node) + (the parent node itself)
+        // Store sibling IDs with each parent because revert needs an insertion
+        // anchor that survives unrelated edits better than a raw child index.
         const parentDesc = {
             nodeId: parentId,
             nodeType: parent.type.name,

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

@@ -5,7 +5,6 @@ function trace(...args) {
     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", {
@@ -14,6 +13,9 @@ export function deleteNodeUpwards(transform, node, pos) {
     });
     let deleteFrom = $mappedPos.pos;
     let deleteTo = $mappedPos.pos + node.nodeSize;
+    // Structure marks live on content nodes, but added wrappers can become empty
+    // after that content is removed. Delete upward until the next parent still has
+    // another child that should survive.
     while($mappedPos.depth > 0){
         const $nextMappedPos = transform.doc.resolve($mappedPos.before());
         if ($nextMappedPos.nodeAfter?.childCount !== 1) {

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

@@ -1,4 +1,6 @@
 import { deleteNodeUpwards } from "./deleteNodeUpwards.js";
 export function revertAddOp(_op, tr, node, pos) {
+    // A Structure add marks the content node, but reverting it may also need to
+    // remove now-empty structural parents that only existed to contain it.
     deleteNodeUpwards(tr, node, pos);
 }

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

@@ -1,6 +1,8 @@
 import { deleteNodeUpwards } from "./deleteNodeUpwards.js";
 import { getNodeId } from "../getNodeId.js";
 export function revertMoveOp(op, tr, node, pos) {
+    // The original parent chain may have been partially removed since the move.
+    // Reuse the deepest surviving parent and recreate only the missing wrappers.
     const parent = getDeepestSurvivingParent(op.from, tr.doc);
     const child = wrapNodeInParentChain(parent.remainingChain, node);
     const insertTo = findInsertionPos(parent.node, parent.pos, parent.parent, child);
@@ -100,8 +102,9 @@ export function findInsertionPos(node, pos, parent, child) {
         return false;
     });
     if (rightSibling != null) {
-        // special case: we need to insert as the first child, but the existing first child is an empty node of the same type
-        // in this case, we need to replace the existing first child with the new node
+        // If the original first-child slot is now occupied by an empty placeholder
+        // of the same type, replace it instead of inserting beside it. This avoids
+        // leaving a blank node where the moved content should be restored.
         const firstChild = node.children[0];
         if (parent.childSiblingIds[0] == null && firstChild?.type === child.type && firstChild.textContent === "") {
             const from = pos != null ? pos + 1 : 0;

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

@@ -154,6 +154,9 @@ function buildOrderedSuggestionIds(node, suggestionId, materializedPaths) {
     });
     const suggestionIds = new Set();
     suggestionIds.add(suggestionId);
+    // If this move is no longer at its expected destination, another Structure
+    // move must be reverted first. Build the dependency chain so reverts happen
+    // from the current outermost state back toward the requested suggestion.
     // find first mark that doesn't have a matching op.to
     const mismatch = markGroup.find((mark)=>{
         const nodeId = getNodeId(mark.node);

package/dist/features/wrapUnwrap/structureChangesPlugin.js

@@ -119,6 +119,9 @@ export function suggestStructureChanges(docBefore, docAfter, structuralContextPa
     });
     const transform = new Transform(docAfter);
     if (reason) {
+        // A reason is an intentional fallthrough, not an error. The Structure
+        // detector recognized a shape that should be handled by normal suggestion
+        // tracking.
         return {
             handled: false,
             transform,
@@ -147,6 +150,9 @@ function addMarks(ops, tr, suggestionId) {
         const op = ops.get(nodeId);
         if (op == null) return true;
         if (op.op === "move") {
+            // A provisional Structure add already means this node is not accepted yet.
+            // Moving it should not create a second review artifact until the add is
+            // accepted.
             if (hasStructureAddMark(node)) return true;
             const inverseMoveMark = findInverseStructureMoveMark(node, op);
             if (inverseMoveMark) {
@@ -259,6 +265,8 @@ function containsContiguousPath(chainNodeTypes, structuralContextPath) {
 // and see if it combines into a single node in the old document
 function isSplitDerivedAdd(newNodeId, beforePaths, afterPaths, contextNodeTypes) {
     const newNode = afterPaths.get(newNodeId)?.node;
+    // Empty after-only nodes are not considered split-derived in whole-doc diff
+    // mode. Without a step-local proof of a split, keep them as Structure adds.
     if (!newNode || newNode.textContent === "") return false;
     if (matchesSplitDerivedPair(newNodeId, newNode.textContent, beforePaths, afterPaths)) {
         return true;

package/dist/features/wrapUnwrap/uniqueNodeIdsPlugin.js

@@ -18,7 +18,8 @@ export function uniqueNodeIdsPlugin({ attributeName, generateID }) {
         appendTransaction (transactions, oldState, newState) {
             trace("appendTransaction");
             const pluginState = uniqueNodeIdsPluginKey.getState(newState);
-            // do nothing if doc hasn't changed (but make sure it runs initially)
+            // Structure tracking relies on stable node IDs even for the initial
+            // document. Run once without a doc change, then only rerun after edits.
             const docChanged = transactions.some((transaction)=>transaction.docChanged);
             if (!docChanged && pluginState?.completedInitialRun) {
                 trace("doc not changed, skipping", [
@@ -68,12 +69,13 @@ export function ensureUniqueNodeIds(_transactions, _oldDoc, newDoc, options) {
     tr.doc.descendants((node, pos)=>{
         if (node.isText) return false;
         const nodeId = getNodeId(node);
-        // nodeId is set and is not duplicated
         if (nodeId != null && !nodeIds.has(nodeId)) {
             nodeIds.add(nodeId);
             return true;
         }
-        // nodeId is set and it is duplicated
+        // ProseMirror commands such as split can copy attrs onto new nodes. Duplicates
+        // must be rewritten immediately or structure diffing cannot tell which node
+        // moved and which node was newly materialized.
         if (nodeId != null && nodeIds.has(nodeId)) {
             const id = options.generateID();
             nodeIds.add(id);

package/dist/withSuggestChanges.js

@@ -34,6 +34,10 @@ function trace(...args) {
             const docBefore = transaction.docs[0];
             const structuralContextPaths = opts?.experimental_trackStructureChanges ? getRequiredStructuralContextPaths(opts.experimental_trackStructures) : null;
             const ensureUniqueNodeIds = opts?.experimental_ensureUniqueNodeIds;
+            // Some editor commands emit compound transactions whose final doc diff looks
+            // structural, but whose user-visible edit needs normal suggestion tracking or
+            // a split structure/main route. Detect those before Structure tracking gets
+            // first claim on the transaction.
             const shapedTransaction = transaction.docChanged ? handleSpecialTransactionShape({
                 transaction,
                 state: this.state,
@@ -61,6 +65,9 @@ function trace(...args) {
                 trace("perf", "structure", "suggestStructureChanges took", Number((performance.now() - perfStructure).toFixed(2)), "ms");
                 trace("structure changes transform completed", structureChangesResult.transform);
                 if (structureChangesResult.handled) {
+                    // Structure tracking is exclusive: once it handles a transaction, the
+                    // main suggestion transformer will not run. Split-like false positives
+                    // must bail out before this branch.
                     uniqueNodeIdsTransform.steps.forEach((step)=>{
                         transaction.step(step);
                     });

package/package.json

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