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

package/dist/__tests__/playwrightPage.d.ts

@@ -50,9 +50,7 @@ export declare class EditorPage {
      * editor.view.state is a different object (ProseMirror creates a new
      * immutable state on every transaction).
      */
-    insertText(text: string, opts?: {
-        waitForSelectionChange?: boolean;
-    }): Promise<void>;
+    insertText(text: string): Promise<void>;
     /**
      * Press a key multiple times, waiting for editor state update after each press.
      */
@@ -60,4 +58,9 @@ export declare class EditorPage {
         waitForSelectionChange?: boolean;
     }): Promise<void>;
     setNextNodeId(nextNodeId: number): Promise<void>;
+    enableTrackChanges(): Promise<void>;
+    disableTrackChanges(): Promise<void>;
+    focusEditor(): Promise<void>;
+    setCursorToStart(): Promise<void>;
+    setCursorToEnd(): Promise<void>;
 }

package/dist/{ensureSelectionPlugin.js → features/ensureValidSelection/ensureSelectionPlugin.js}

@@ -1,6 +1,5 @@
 import { Plugin, PluginKey, TextSelection } from "prosemirror-state";
-import { getSuggestionMarks } from "./utils.js";
-import { ZWSP } from "./constants.js";
+import { getInvalidSelectionPositionReason } from "./selectionPosition.js";
 const TRACE_ENABLED = false;
 function trace(...args) {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
@@ -37,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";
@@ -47,23 +48,26 @@ export function ensureSelection() {
                 }
             }
         },
-        appendTransaction (_transactions, oldState, newState) {
+        appendTransaction (transactions, oldState, newState) {
             const pluginState = ensureSelectionKey.getState(newState);
+            const isSelectionOnly = transactions.every((tr)=>!tr.docChanged);
             if (!(newState.selection instanceof TextSelection)) {
                 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...");
-            let $newAnchor = getNewValidPos(newState.selection.$anchor, getDirection(oldState.selection.$anchor, newState.selection.$anchor, pluginState));
+            let $newAnchor = getNewValidPos(oldState.selection.$anchor, newState.selection.$anchor, isSelectionOnly, pluginState);
             trace("appendTransaction", "new valid $anchor", $newAnchor?.pos, {
                 $newAnchor
             });
             trace("appendTransaction", "search for new valid $head...");
-            let $newHead = newState.selection.empty ? $newAnchor : getNewValidPos(newState.selection.$head, getDirection(oldState.selection.$head, newState.selection.$head, pluginState));
+            let $newHead = newState.selection.empty ? $newAnchor : getNewValidPos(oldState.selection.$head, newState.selection.$head, isSelectionOnly, pluginState);
             trace("appendTransaction", "new valid $head", $newHead?.pos, {
                 $newHead
             });
@@ -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,
@@ -95,77 +100,9 @@ export function isEnsureSelectionEnabled() {
     return true;
 }
 function isPosValid($pos) {
-    // text selection is only valid in nodes that allow inline content
-    // https://github.com/ProseMirror/prosemirror-state/blob/1.4.4/src/selection.ts#L219
-    if (!$pos.parent.inlineContent) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: not in inlineContent node", {
-            $pos
-        });
-        return false;
-    }
-    const { deletion, insertion } = getSuggestionMarks($pos.doc.type.schema);
-    const deletionBefore = deletion.isInSet($pos.nodeBefore?.marks ?? []);
-    const deletionAfter = deletion.isInSet($pos.nodeAfter?.marks ?? []);
-    const isAnchorBefore = deletionBefore && deletionBefore.attrs["type"] === "anchor";
-    const isAnchorAfter = deletionAfter && deletionAfter.attrs["type"] === "anchor";
-    if (isAnchorBefore && deletionAfter && !isAnchorAfter) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between deletion anchor and non-anchor deletion", {
-            $pos
-        });
-        return false;
-    }
-    if (deletionBefore && deletionAfter && !isAnchorBefore && !isAnchorAfter) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between two non-anchor deletions", {
-            $pos
-        });
-        return false;
-    }
-    if ($pos.nodeBefore == null && deletionAfter && !isAnchorAfter) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between node boundary and non-anchor deletion", {
-            $pos
-        });
-        return false;
-    }
-    if (deletionBefore && $pos.nodeAfter == null && !isAnchorBefore) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between non-anchor deletion and node boundary", {
-            $pos
-        });
-        return false;
-    }
-    if (deletionBefore && !isAnchorBefore && $pos.nodeAfter == null) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between non-anchor deletion and node boundary", {
-            $pos
-        });
-        return false;
-    }
-    if (deletionBefore && !isAnchorBefore) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between non-anchor deletion and anything", {
-            $pos
-        });
-        return false;
-    }
-    const insertionBefore = insertion.isInSet($pos.nodeBefore?.marks ?? []);
-    const insertionAfter = insertion.isInSet($pos.nodeAfter?.marks ?? []);
-    const ZWSP_REGEXP = new RegExp(ZWSP, "g");
-    const isZWSPBefore = $pos.nodeBefore && $pos.nodeBefore.isText && $pos.nodeBefore.textContent.replace(ZWSP_REGEXP, "") === "";
-    const isZWSPAfter = $pos.nodeAfter && $pos.nodeAfter.isText && $pos.nodeAfter.textContent.replace(ZWSP_REGEXP, "") === "";
-    if (insertionBefore && insertionAfter && isZWSPBefore && isZWSPAfter) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between two ZWSP insertions", {
-            $pos
-        });
-        return false;
-    }
-    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
-    $pos.parent.textContent.replace(ZWSP_REGEXP, "") !== "") {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between ZWSP insertion and right node boundary", {
-            $pos
-        });
-        return false;
-    }
-    if (insertionAfter && isZWSPAfter && $pos.nodeBefore == null) {
-        trace("isPosValid", $pos.pos, "pos invalid", "reason: between ZWSP insertion and left node boundary", {
+    const invalidReason = getInvalidSelectionPositionReason($pos);
+    if (invalidReason) {
+        trace("isPosValid", $pos.pos, "pos invalid", `reason: ${invalidReason}`, {
             $pos
         });
         return false;
@@ -174,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);
@@ -209,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) {
@@ -227,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
@@ -241,7 +182,49 @@ function findPreviousValidPos($initialPos) {
     }
     return isPosValid($pos) ? $pos : null;
 }
-function getNewValidPos($pos, dir) {
+/**
+ * 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) {
+            const $nextPos = $initialPos.doc.resolve(nextPos);
+            if (isPosValid($nextPos)) return $nextPos;
+        }
+        const prevPos = $initialPos.pos - distance;
+        if (distance > 0 && prevPos >= start) {
+            const $prevPos = $initialPos.doc.resolve(prevPos);
+            if (isPosValid($prevPos)) return $prevPos;
+        }
+    }
+    return null;
+}
+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,
+        $newPos,
+        $sameParentPos
+    });
+    return $sameParentPos;
+}
+function getNewValidPosByDirection($pos, dir) {
     if (isPosValid($pos)) return $pos;
     trace("getNewValidPos for", $pos.pos, {
         $pos,
@@ -298,7 +281,14 @@ function getNewValidPos($pos, dir) {
     const prevDist = Math.abs($pos.pos - $prevValidPos.pos);
     return nextDist <= prevDist ? $nextValidPos : $prevValidPos;
 }
+function getNewValidPos($oldPos, $newPos, isSelectionOnly, pluginState) {
+    const $sameParentPos = isSelectionOnly ? getNewValidPosInSelectionDestinationParent($oldPos, $newPos) : null;
+    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/ensureSelectionPlugin.test.d.ts

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

package/dist/features/ensureValidSelection/ensureSelectionPlugin.test.js

@@ -0,0 +1,112 @@
+import { EditorState, NodeSelection, TextSelection } from "prosemirror-state";
+import { assert, describe, it } from "vitest";
+import { ZWSP } from "../../constants.js";
+import { testBuilders } from "../../testing/testBuilders.js";
+import { ensureSelection } from "./ensureSelectionPlugin.js";
+function createState(doc, selection) {
+    return EditorState.create({
+        doc,
+        selection,
+        plugins: [
+            ensureSelection()
+        ]
+    });
+}
+function applyTextSelection(state, anchor, head = anchor) {
+    const selection = TextSelection.create(state.doc, anchor, head);
+    const transaction = state.tr.setSelection(selection);
+    return state.apply(transaction);
+}
+function assertTextSelection(state, anchor, head = anchor) {
+    assert(state.selection instanceof TextSelection);
+    assert.equal(state.selection.anchor, anchor);
+    assert.equal(state.selection.head, head);
+}
+function getTag(doc, tag) {
+    const pos = doc.tag[tag];
+    assert(pos !== undefined, `Expected tag "${tag}" to exist`);
+    return pos;
+}
+describe("ensureSelection", ()=>{
+    it("leaves valid text selections unchanged", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("one<from>"), testBuilders.paragraph("two<to>"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "from")));
+        const nextState = applyTextSelection(state, getTag(doc, "to"));
+        assertTextSelection(nextState, getTag(doc, "to"));
+    });
+    it("ignores non-text selections", ()=>{
+        const doc = testBuilders.doc(testBuilders.image({
+            src: "https://example.com/image.png"
+        }), testBuilders.paragraph("after<cursor>"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "cursor")));
+        const nextState = state.apply(state.tr.setSelection(NodeSelection.create(doc, 0)));
+        assert(nextState.selection instanceof NodeSelection);
+        assert.equal(nextState.selection.anchor, 0);
+    });
+    it("prefers a valid position in the destination textblock for selection-only movement", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("Item 2<old>"), testBuilders.paragraph(testBuilders.insertion({
+            id: 1
+        }, "<invalid>" + ZWSP + "<valid>")), testBuilders.paragraph(testBuilders.insertion({
+            id: 1
+        }, ZWSP), "Item 3"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "valid"));
+    });
+    it("uses direction fallback when the transaction changes the document", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("<markStart>A<expected><markEnd>"), testBuilders.paragraph(testBuilders.insertion({
+            id: 1
+        }, "<invalid>" + ZWSP + "<sameParent>")), testBuilders.paragraph(testBuilders.insertion({
+            id: 1
+        }, ZWSP), "<old>Item 3"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const transaction = state.tr;
+        transaction.addMark(getTag(doc, "markStart"), getTag(doc, "markEnd"), testBuilders.schema.marks.strong.create());
+        transaction.setSelection(TextSelection.create(transaction.doc, getTag(doc, "invalid")));
+        const nextState = state.apply(transaction);
+        assertTextSelection(nextState, getTag(doc, "expected"));
+    });
+    it("uses direction fallback for invalid positions in the same textblock", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("A", testBuilders.deletion({
+            id: 1
+        }, "<expected>B<invalid>"), "C<old>"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "expected"));
+    });
+    it("keeps deletion anchor and non-anchor deletion positions continuous", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph(testBuilders.deletion({
+            id: 1,
+            type: "anchor"
+        }, "<expected>" + ZWSP + "<invalid>"), testBuilders.deletion({
+            id: 1
+        }, "deleted"), "visible<old>"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "expected"));
+    });
+    it("moves hidden-deletion-style boundary positions to visible content", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("before<old>"), testBuilders.paragraph(testBuilders.deletion({
+            id: 1
+        }, "<invalid>deleted"), "v<expected>isible"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "expected"));
+    });
+    it("keeps paired split marker positions attached to textblock boundaries", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("before<old>"), testBuilders.paragraph("content<expected>", testBuilders.insertion({
+            id: 1
+        }, ZWSP + "<invalid>")));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "expected"));
+    });
+    it("moves positions between adjacent insertion ZWSPs to a valid neighbor", ()=>{
+        const doc = testBuilders.doc(testBuilders.paragraph("before<old>", testBuilders.insertion({
+            id: 1
+        }, "<expected>" + ZWSP + "<invalid>" + ZWSP), "<valid>after"));
+        const state = createState(doc, TextSelection.create(doc, getTag(doc, "old")));
+        const nextState = applyTextSelection(state, getTag(doc, "invalid"));
+        assertTextSelection(nextState, getTag(doc, "valid"));
+    });
+});

package/dist/features/ensureValidSelection/selectionPosition.d.ts

@@ -0,0 +1,3 @@
+import { type ResolvedPos } from "prosemirror-model";
+export type InvalidSelectionPositionReason = "not-in-inline-content" | "between-deletion-anchor-and-non-anchor-deletion" | "between-two-non-anchor-deletions" | "between-node-boundary-and-non-anchor-deletion" | "between-non-anchor-deletion-and-node-boundary" | "between-non-anchor-deletion-and-anything" | "between-two-zwsp-insertions" | "between-zwsp-insertion-and-right-node-boundary" | "between-zwsp-insertion-and-left-node-boundary";
+export declare function getInvalidSelectionPositionReason($pos: ResolvedPos): InvalidSelectionPositionReason | null;

package/dist/features/ensureValidSelection/selectionPosition.js

@@ -0,0 +1,50 @@
+import { ZWSP } from "../../constants.js";
+import { getSuggestionMarks } from "../../utils.js";
+export function getInvalidSelectionPositionReason($pos) {
+    // Text selection is only valid in nodes that allow inline content.
+    // https://github.com/ProseMirror/prosemirror-state/blob/1.4.4/src/selection.ts#L219
+    if (!$pos.parent.inlineContent) {
+        return "not-in-inline-content";
+    }
+    const { deletion, insertion } = getSuggestionMarks($pos.doc.type.schema);
+    const deletionBefore = deletion.isInSet($pos.nodeBefore?.marks ?? []);
+    const deletionAfter = deletion.isInSet($pos.nodeAfter?.marks ?? []);
+    const isAnchorBefore = deletionBefore && deletionBefore.attrs["type"] === "anchor";
+    const isAnchorAfter = deletionAfter && deletionAfter.attrs["type"] === "anchor";
+    if (isAnchorBefore && deletionAfter && !isAnchorAfter) {
+        return "between-deletion-anchor-and-non-anchor-deletion";
+    }
+    if (deletionBefore && deletionAfter && !isAnchorBefore && !isAnchorAfter) {
+        return "between-two-non-anchor-deletions";
+    }
+    if ($pos.nodeBefore == null && deletionAfter && !isAnchorAfter) {
+        return "between-node-boundary-and-non-anchor-deletion";
+    }
+    if (deletionBefore && $pos.nodeAfter == null && !isAnchorBefore) {
+        return "between-non-anchor-deletion-and-node-boundary";
+    }
+    if (deletionBefore && !isAnchorBefore && $pos.nodeAfter == null) {
+        return "between-non-anchor-deletion-and-node-boundary";
+    }
+    if (deletionBefore && !isAnchorBefore) {
+        return "between-non-anchor-deletion-and-anything";
+    }
+    const insertionBefore = insertion.isInSet($pos.nodeBefore?.marks ?? []);
+    const insertionAfter = insertion.isInSet($pos.nodeAfter?.marks ?? []);
+    const ZWSP_REGEXP = new RegExp(ZWSP, "g");
+    const isZWSPBefore = $pos.nodeBefore && $pos.nodeBefore.isText && $pos.nodeBefore.textContent.replace(ZWSP_REGEXP, "") === "";
+    const isZWSPAfter = $pos.nodeAfter && $pos.nodeAfter.isText && $pos.nodeAfter.textContent.replace(ZWSP_REGEXP, "") === "";
+    if (insertionBefore && insertionAfter && isZWSPBefore && isZWSPAfter) {
+        return "between-two-zwsp-insertions";
+    }
+    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";
+    }
+    if (insertionAfter && isZWSPAfter && $pos.nodeBefore == null) {
+        return "between-zwsp-insertion-and-left-node-boundary";
+    }
+    return null;
+}

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/index.d.ts

@@ -2,7 +2,7 @@ export { addSuggestionMarks, insertion, deletion, modification, hiddenDeletion,
 export { selectSuggestion, revertSuggestion, revertSuggestions, applySuggestion, applySuggestions, enableSuggestChanges, disableSuggestChanges, toggleSuggestChanges, } from "./commands.js";
 export { suggestChanges, suggestChangesKey, isSuggestChangesEnabled, } from "./plugin.js";
 export { withSuggestChanges, transformToSuggestionTransaction, suggestStructureChanges as experimental_suggestStructureChanges, } from "./withSuggestChanges.js";
-export { ensureSelection as experimental_ensureSelection, ensureSelectionKey as experimental_ensureSelectionKey, isEnsureSelectionEnabled as experimental_isEnsureSelectionEnabled, } from "./ensureSelectionPlugin.js";
+export { ensureSelection as experimental_ensureSelection, ensureSelectionKey as experimental_ensureSelectionKey, isEnsureSelectionEnabled as experimental_isEnsureSelectionEnabled, } from "./features/ensureValidSelection/ensureSelectionPlugin.js";
 export { guardStructureMarkAttrs } from "./features/wrapUnwrap/types.js";
 export type { Op as StructureOp, StructureMarkAttrs, StructuralContextPath, } from "./features/wrapUnwrap/types.js";
 export { wrappingInputRule as experimental_wrappingInputRule } from "./wrappingInputRule.js";

package/dist/index.js

@@ -2,6 +2,6 @@ export { addSuggestionMarks, insertion, deletion, modification, hiddenDeletion,
 export { selectSuggestion, revertSuggestion, revertSuggestions, applySuggestion, applySuggestions, enableSuggestChanges, disableSuggestChanges, toggleSuggestChanges } from "./commands.js";
 export { suggestChanges, suggestChangesKey, isSuggestChangesEnabled } from "./plugin.js";
 export { withSuggestChanges, transformToSuggestionTransaction, suggestStructureChanges as experimental_suggestStructureChanges } from "./withSuggestChanges.js";
-export { ensureSelection as experimental_ensureSelection, ensureSelectionKey as experimental_ensureSelectionKey, isEnsureSelectionEnabled as experimental_isEnsureSelectionEnabled } from "./ensureSelectionPlugin.js";
+export { ensureSelection as experimental_ensureSelection, ensureSelectionKey as experimental_ensureSelectionKey, isEnsureSelectionEnabled as experimental_isEnsureSelectionEnabled } from "./features/ensureValidSelection/ensureSelectionPlugin.js";
 export { guardStructureMarkAttrs } from "./features/wrapUnwrap/types.js";
 export { wrappingInputRule as experimental_wrappingInputRule } from "./wrappingInputRule.js";

package/dist/testing/e2eTestSchema.d.ts

@@ -1,2 +1,2 @@
 import { Schema } from "prosemirror-model";
-export declare function createSchema(deletionMarksVisibility?: "hidden" | "visible"): Schema<"blockquote" | "text" | "doc" | "paragraph" | "horizontal_rule" | "heading" | "code_block" | "image" | "hard_break" | "orderedList" | "bulletList" | "listItem" | "hardBreak", "insertion" | "deletion" | "modification" | "structure" | "code" | "em" | "link" | "strong">;
+export declare function createSchema(deletionMarksVisibility?: "hidden" | "visible"): Schema<"blockquote" | "text" | "image" | "doc" | "orderedList" | "bulletList" | "listItem" | "paragraph" | "horizontal_rule" | "heading" | "code_block" | "hard_break" | "hardBreak", "insertion" | "deletion" | "modification" | "structure" | "code" | "em" | "link" | "strong">;

package/dist/testing/testBuilders.d.ts

@@ -1,6 +1,6 @@
 import { Schema, type Node } from "prosemirror-model";
 import { type MarkBuilder, type NodeBuilder } from "prosemirror-test-builder";
-export declare const schema: Schema<"blockquote" | "text" | "doc" | "paragraph" | "horizontal_rule" | "heading" | "code_block" | "image" | "hard_break" | "orderedList" | "bulletList" | "listItem", "insertion" | "deletion" | "modification" | "structure" | "code" | "em" | "link" | "strong" | "difficulty">;
+export declare const schema: Schema<"blockquote" | "text" | "image" | "doc" | "orderedList" | "bulletList" | "listItem" | "paragraph" | "horizontal_rule" | "heading" | "code_block" | "hard_break", "insertion" | "deletion" | "modification" | "structure" | "code" | "em" | "link" | "strong" | "difficulty">;
 export declare const testBuilders: { [NodeTypeName in keyof (typeof schema)["nodes"]]: NodeBuilder; } & { [MarkTypeName in keyof (typeof schema)["marks"]]: MarkBuilder; } & {
     schema: typeof schema;
 };

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.1",
+  "version": "0.4.1-wrap-unwrap.3",
   "license": "MIT",
   "type": "module",
   "module": "dist/index.js",