Cover more NodeTraversor mutation cases and tighten recovery

I found some additional mutation cases around root detachment, unwrap(), and count-changing sibling edits.

Tightened traversal recovery so it stays within the original root boundary, continues correctly from the former sibling position, and add regression
tests with full branch coverage.

Related to #2742

Author: jhy

CHANGES.md

@@ -4,7 +4,7 @@
 
 ### Bug Fixes
 * Android (R8/ProGuard): added a rule to ignore the optional `re2j` dependency when not present. [#2459](https://github.com/jhy/jsoup/issues/2459)
-* In `NodeTraversor`, removing or replacing the current node during `head()` no longer re-visits the replacement node, preventing loops. Also clarified in documentation the which inserted nodes are visited during the current traversal. [#2472](https://github.com/jhy/jsoup/issues/2472)
+* In `NodeTraversor`, removing or replacing the current node during `head()` no longer re-visits the replacement node, preventing loops. Traversal now continues correctly from nodes that occupy the original position after mutation, and will not advance past the original root subtree. Also, clarified in the documentation which inserted nodes are visited during the current traversal. [#2472](https://github.com/jhy/jsoup/issues/2472)
 
 ## 1.22.1 (2026-Jan-01)
 

src/main/java/org/jsoup/select/NodeTraversor.java

@@ -10,7 +10,7 @@
  order. The {@link NodeVisitor#head(Node, int)} and {@link NodeVisitor#tail(Node, int)} methods will be called for
  each node.
  <p>During the <code>head()</code> visit, DOM structural changes around the node currently being visited are
- supported, including e.g. {@link Node#replaceWith(Node)} and {@link Node#remove()}. See
+ supported, including {@link Node#replaceWith(Node)} and {@link Node#remove()}. See
  {@link NodeVisitor#head(Node, int) head()} for the traversal contract after mutation. Other non-structural node
  changes are also supported.</p>
  <p>DOM structural changes to the current node are not supported during the <code>tail()</code> visit.</p>
@@ -31,35 +31,40 @@ public static void traverse(NodeVisitor visitor, Node root) {
         Validate.notNull(visitor);
         Validate.notNull(root);
         Node node = root;
+        final Node rootNext = root.nextSibling(); // don't traverse siblings beyond the original root
         int depth = 0;
         byte state = VisitHead;
 
-        while (node != null) {
+        while (true) {
             if (state == VisitHead) {
                 // snapshot the current cursor position so we can recover if head() structurally changes it:
-                Node parent    = node.parentNode();
-                Node nextSib   = node.nextSibling();
-                int sibIndex   = parent != null ? node.siblingIndex()    : 0;
-                int childCount = parent != null ? parent.childNodeSize() : 0;
+                Node parent   = node.parentNode();
+                Node next     = node.nextSibling();
+                int  sibIndex = parent != null ? node.siblingIndex() : 0;
 
                 visitor.head(node, depth);
 
                 // any structural changes?
-                if (parent != null && !node.hasParent()) {      // node was removed from parent; try to recover by sibling index
-                    if (parent.childNodeSize() == childCount) { // current slot is still occupied
-                        node = parent.childNode(sibIndex);
-                        state = AfterHead;                      // continue from that slot without re-heading it
-                    } else if (nextSib != null) {               // removed; resume from the original next
-                        node = nextSib;
-                    } else {                                    // removed last child; tail the parent next
+                if (parent != null && node.parentNode() != parent) { // removed / replaced / moved
+                    Node occupant = sibIndex < parent.childNodeSize() ? parent.childNode(sibIndex) : null;
+                    // ^^ the node now at this node's former position
+                    Node boundary = depth == 0 ? rootNext : next;   // don't advance beyond this node when resuming
+                    if (occupant != null && occupant != boundary) {
+                        node = occupant;
+                        state = AfterHead;                          // continue from that slot without re-heading it
+                    } else if (depth == 0) {                        // root detached or replaced
+                        break;
+                    } else if (next != null && next.parentNode() == parent) {
+                        node = next;                                // old slot is empty or shifted to the original next, visit
+                    } else {                                        // removed last child; tail the parent next
                         node = parent;
                         depth--;
                         state = VisitTail;
                     }
                 } else {
                     state = AfterHead;
                 }
-                continue;                                       // next loop handles the updated node/state
+                continue;                                           // next loop handles the updated node/state
             }
 
             if (state == AfterHead && node.childNodeSize() > 0) { // descend into current children
@@ -71,10 +76,12 @@ public static void traverse(NodeVisitor visitor, Node root) {
 
             visitor.tail(node, depth);
 
-            if (node == root) break; // done
-
             Node next = node.nextSibling();
-            if (next != null) {     // traverse siblings
+            if (depth == 0) {
+                if (next == null || next == rootNext) break; // done with the original root range
+                node = next;
+                state = VisitHead;
+            } else if (next != null) { // traverse siblings
                 node = next;
                 state = VisitHead;
             } else {                // no siblings left, ascend

src/main/java/org/jsoup/select/NodeVisitor.java

@@ -40,6 +40,8 @@ <p>The node may be modified (for example via {@link Node#attr(String)}), removed
      <li>If the current node was detached and no node occupies its former sibling position, the current node is not
      passed to {@code tail()}, and traversal resumes at the node that originally followed it.</li>
      </ul>
+     <p>Traversal never advances outside the original root subtree. If the traversal root is detached during
+     {@code head()}, traversal stops at the original root boundary.</p>
 
      @param node the node being visited.
      @param depth the depth of the node, relative to the root node. E.g., the root node has depth 0, and a child node

src/test/java/org/jsoup/select/TraversorTest.java

@@ -372,6 +372,180 @@ void visitsChildrenInsertedInHead() {
         assertEquals("<div><p><span>child</span></p></div>", TextUtil.stripNewlines(doc.body().html()));
     }
 
+    @Test
+    void removingTraversalRootInHeadDoesNotEscapeOriginalSubtree() {
+        Document doc = Jsoup.parseBodyFragment("<div>a</div><p>b</p>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node == root)
+                    node.remove();
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;", headOrder.toString());
+        assertEquals("", tailOrder.toString());
+        assertEquals("<p>b</p>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void removingOnlyTraversalRootInHeadStopsWhenOriginalSlotIsEmpty() {
+        Document doc = Jsoup.parseBodyFragment("<div>a</div>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node == root)
+                    node.remove();
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;", headOrder.toString());
+        assertEquals("", tailOrder.toString());
+        assertEquals("", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void replacingTraversalRootInHeadStaysWithinReplacementSubtree() {
+        Document doc = Jsoup.parseBodyFragment("<div><span>x</span></div><p>y</p>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node == root) {
+                    Element replacement = new Element("section").insertChildren(0, node.childNodes());
+                    node.replaceWith(replacement);
+                }
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;span;x;", headOrder.toString());
+        assertEquals("x;span;section;", tailOrder.toString());
+        assertEquals("<section><span>x</span></section><p>y</p>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void unwrappingTraversalRootInHeadVisitsExposedTopLevelNodesUntilOriginalBoundary() {
+        Document doc = Jsoup.parseBodyFragment("<div><b>x</b><i>y</i></div><p>z</p>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node == root)
+                    node.unwrap();
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;x;i;y;", headOrder.toString());
+        assertEquals("x;b;y;i;", tailOrder.toString());
+        assertEquals("<b>x</b><i>y</i><p>z</p>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void unwrapInHeadContinuesFromExposedChildren() {
+        Document doc = Jsoup.parseBodyFragment("<div><span><b>x</b><i>y</i></span><u>z</u></div>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node instanceof Element && node.nameIs("span"))
+                    node.unwrap();
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;span;x;i;y;u;z;", headOrder.toString());
+        assertEquals("x;b;y;i;z;u;div;", tailOrder.toString());
+        assertEquals("<div><b>x</b><i>y</i><u>z</u></div>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void removingCurrentAndOriginalNextInHeadTailsParent() {
+        Document doc = Jsoup.parseBodyFragment("<div>a<em>Two</em></div>");
+        Element root = doc.expectFirst("div");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node instanceof TextNode && ((TextNode) node).text().equals("a")) {
+                    node.nextSibling().remove();
+                    node.remove();
+                }
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, root);
+
+        assertEquals("div;a;", headOrder.toString());
+        assertEquals("div;", tailOrder.toString());
+        assertEquals("<div></div>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
+    @Test
+    void beforeAfterRemoveInHeadTailsCurrentSlotAndHeadsFutureSiblings() {
+        Document doc = Jsoup.parse("<div><p>One</p>a<em>Two</em></div>");
+        StringBuilder headOrder = new StringBuilder();
+        StringBuilder tailOrder = new StringBuilder();
+
+        NodeTraversor.traverse(new NodeVisitor() {
+            @Override public void head(Node node, int depth) {
+                trackSeen(node, headOrder);
+                if (node instanceof TextNode && ((TextNode) node).text().equals("a")) {
+                    node.before(new TextNode("b"));
+                    node.after(new TextNode("c"));
+                    node.remove();
+                }
+            }
+
+            @Override public void tail(Node node, int depth) {
+                trackSeen(node, tailOrder);
+            }
+        }, doc);
+
+        assertEquals("#root;html;head;body;div;p;One;a;c;em;Two;", headOrder.toString());
+        assertEquals("head;One;p;b;c;Two;em;div;body;html;#root;", tailOrder.toString());
+        assertEquals("<div><p>One</p>bc<em>Two</em></div>", TextUtil.stripNewlines(doc.body().html()));
+    }
+
     @Test void elementFunctionalTraverse() {
         Document doc = Jsoup.parse("<div><p>1<p>2<p>3");
         Element body = doc.body();