Add NodeIterator for DOMPurify traversal

Author: wieslawsoltes

experiments/WebScene.NativeEngine.Probe/native/webscene_v8_runtime.cpp

@@ -2508,6 +2508,87 @@ struct v8_dom_runtime::implementation final {
               }
             }
 
+            class WebSceneNodeIterator {
+              constructor(root, whatToShow = nodeFilterConstants.SHOW_ALL, filter = null) {
+                if (!root || typeof root.nodeType !== 'number') {
+                  throw new TypeError('NodeIterator root must be a Node');
+                }
+                if (filter != null && typeof filter !== 'function'
+                    && typeof filter.acceptNode !== 'function') {
+                  throw new TypeError('NodeIterator filter must be callable');
+                }
+                Object.defineProperties(this, {
+                  root: { value: root, enumerable: true },
+                  whatToShow: {
+                    value: Number(whatToShow) >>> 0, enumerable: true
+                  },
+                  filter: { value: filter ?? null, enumerable: true }
+                });
+                this._nodes = [];
+                this._index = -1;
+                this._referenceNode = root;
+                this._pointerBeforeReferenceNode = true;
+
+                // Build one bounded document-order snapshot. This makes the
+                // DOMPurify traversal O(n), retains at most one reference per
+                // node below root, and remains safe when the sanitizer removes
+                // a node that the iterator has already returned.
+                const visit = node => {
+                  const mask = node.nodeType > 0 && node.nodeType <= 32
+                    ? (1 << (node.nodeType - 1)) >>> 0
+                    : 0;
+                  if ((this.whatToShow & mask) !== 0) {
+                    const callback = this.filter == null
+                      ? null
+                      : typeof this.filter === 'function'
+                        ? this.filter
+                        : this.filter.acceptNode;
+                    const decision = callback == null
+                      ? nodeFilterConstants.FILTER_ACCEPT
+                      : Number(callback.call(this.filter, node));
+                    if (decision === nodeFilterConstants.FILTER_ACCEPT) {
+                      this._nodes.push(node);
+                    }
+                  }
+                  // NodeIterator treats FILTER_REJECT like FILTER_SKIP: neither
+                  // result prunes descendants.
+                  for (let child = node.firstChild; child; child = child.nextSibling) {
+                    visit(child);
+                  }
+                };
+                visit(root);
+              }
+              get referenceNode() { return this._referenceNode; }
+              get pointerBeforeReferenceNode() {
+                return this._pointerBeforeReferenceNode;
+              }
+              nextNode() {
+                if (this._pointerBeforeReferenceNode && this._index >= 0) {
+                  this._pointerBeforeReferenceNode = false;
+                  return this._referenceNode;
+                }
+                const nextIndex = this._index + 1;
+                if (nextIndex >= this._nodes.length) return null;
+                this._index = nextIndex;
+                this._referenceNode = this._nodes[this._index];
+                this._pointerBeforeReferenceNode = false;
+                return this._referenceNode;
+              }
+              previousNode() {
+                if (!this._pointerBeforeReferenceNode && this._index >= 0) {
+                  this._pointerBeforeReferenceNode = true;
+                  return this._referenceNode;
+                }
+                const previousIndex = this._index - 1;
+                if (previousIndex < 0) return null;
+                this._index = previousIndex;
+                this._referenceNode = this._nodes[this._index];
+                this._pointerBeforeReferenceNode = true;
+                return this._referenceNode;
+              }
+              detach() {}
+            }
+
             const installTreeWalkerPlatform = () => {
               const createTreeWalker = function(
                   root,
@@ -2520,6 +2601,15 @@ struct v8_dom_runtime::implementation final {
               Object.defineProperty(documentPrototype, 'createTreeWalker', {
                 value: createTreeWalker, writable: true, configurable: true
               });
+              const createNodeIterator = function(
+                  root,
+                  whatToShow = nodeFilterConstants.SHOW_ALL,
+                  filter = null) {
+                return new WebSceneNodeIterator(root, whatToShow, filter);
+              };
+              Object.defineProperty(documentPrototype, 'createNodeIterator', {
+                value: createNodeIterator, writable: true, configurable: true
+              });
             };
             )JS",
             R"JS(
@@ -2862,6 +2952,9 @@ struct v8_dom_runtime::implementation final {
               },
               TreeWalker: {
                 value: WebSceneTreeWalker, writable: true, configurable: true
+              },
+              NodeIterator: {
+                value: WebSceneNodeIterator, writable: true, configurable: true
               }
             });
           })();

experiments/WebScene.NativeEngine.Probe/tests/native_v8_runtime_browser_dom_tests.inc

@@ -1140,6 +1140,124 @@ void test_node_filter_tree_walker_focus_navigation(webscene_engine* engine)
         "NodeFilter/TreeWalker focus navigation regressed: " + result);
 }
 
+void test_node_iterator_dompurify_traversal(webscene_engine* engine)
+{
+    const auto result = evaluate(engine, R"JS(
+        (() => {
+          document.body.innerHTML = '<main id="root">before<!--comment--><section><span>inside</span></section>after</main>';
+          const root = document.getElementById('root');
+          const mask = NodeFilter.SHOW_ELEMENT
+            | NodeFilter.SHOW_TEXT
+            | NodeFilter.SHOW_COMMENT;
+          let filterCalls = 0;
+          const iterator = document.createNodeIterator(root, mask, {
+            acceptNode(node) {
+              ++filterCalls;
+              return node.nodeType === Node.ELEMENT_NODE
+                  && node.localName === 'section'
+                ? NodeFilter.FILTER_REJECT
+                : NodeFilter.FILTER_ACCEPT;
+            }
+          });
+          const forward = [];
+          for (let node = iterator.nextNode(); node; node = iterator.nextNode()) {
+            forward.push(node.nodeType === Node.ELEMENT_NODE
+              ? node.localName
+              : node.nodeType === Node.COMMENT_NODE
+                ? `#comment:${node.data}`
+                : `#text:${node.data}`);
+          }
+          const endState = [
+            iterator.referenceNode.nodeName,
+            iterator.pointerBeforeReferenceNode
+          ];
+          const backwards = [
+            iterator.previousNode()?.nodeName ?? null,
+            iterator.previousNode()?.nodeName ?? null,
+            iterator.nextNode()?.nodeName ?? null
+          ];
+
+          const functionFilter = document.createNodeIterator(
+            root,
+            NodeFilter.SHOW_ELEMENT,
+            node => node.localName === 'span'
+              ? NodeFilter.FILTER_ACCEPT
+              : NodeFilter.FILTER_SKIP);
+          const functionFiltered = [];
+          for (let node = functionFilter.nextNode(); node;
+               node = functionFilter.nextNode()) {
+            functionFiltered.push(node.localName);
+          }
+
+          const fragment = document.createDocumentFragment();
+          const detached = document.createElement('strong');
+          fragment.appendChild(detached);
+          const detachedIterator = document.createNodeIterator(
+            fragment, NodeFilter.SHOW_ALL);
+
+          let invalidRoot = false;
+          let invalidFilter = false;
+          try { document.createNodeIterator(null); } catch (error) {
+            invalidRoot = error instanceof TypeError;
+          }
+          try { document.createNodeIterator(root, mask, {}); } catch (error) {
+            invalidFilter = error instanceof TypeError;
+          }
+
+          return {
+            instance: iterator instanceof NodeIterator,
+            root: iterator.root === root,
+            whatToShow: iterator.whatToShow,
+            filterCalls,
+            forward,
+            endState,
+            backwards,
+            functionFiltered,
+            detached: [
+              detachedIterator.nextNode() === fragment,
+              detachedIterator.nextNode() === detached,
+              detachedIterator.nextNode()
+            ],
+            invalidRoot,
+            invalidFilter
+          };
+        })()
+    )JS", "native-node-iterator-dompurify.js");
+    require(
+        result == R"JSON({"instance":true,"root":true,"whatToShow":133,"filterCalls":7,"forward":["main","#text:before","#comment:comment","span","#text:inside","#text:after"],"endState":["#text",false],"backwards":["#text","#text","#text"],"functionFiltered":["span"],"detached":[true,true,null],"invalidRoot":true,"invalidFilter":true})JSON",
+        "NodeIterator DOMPurify traversal regressed: " + result);
+}
+
+void test_node_iterator_linear_performance_gate(webscene_engine* engine)
+{
+    const auto result = evaluate(engine, R"JS(
+        (() => {
+          document.body.innerHTML = `<div id="iterator-root">${'<i></i>'.repeat(50000)}</div>`;
+          const root = document.getElementById('iterator-root');
+          let filterCalls = 0;
+          const started = performance.now();
+          const iterator = document.createNodeIterator(
+            root,
+            NodeFilter.SHOW_ELEMENT,
+            () => {
+              ++filterCalls;
+              return NodeFilter.FILTER_ACCEPT;
+            });
+          let visited = 0;
+          while (iterator.nextNode()) ++visited;
+          const elapsed = performance.now() - started;
+          return {
+            visited,
+            filterCalls,
+            underFiveSeconds: elapsed < 5000
+          };
+        })()
+    )JS", "native-node-iterator-performance.js");
+    require(
+        result == R"JSON({"visited":50001,"filterCalls":50001,"underFiveSeconds":true})JSON",
+        "50,000-node NodeIterator linear performance gate failed: " + result);
+}
+
 void test_animation_frame_dispatch_is_attributed()
 {
     auto* engine = webscene_engine_create(0);

experiments/WebScene.NativeEngine.Probe/tests/native_v8_runtime_tests.cpp

@@ -818,6 +818,8 @@ int main()
     test_event_listener_options_reach_native_input_and_resize(engine);
     test_listener_added_during_dispatch_waits_for_next_event(engine);
     test_node_filter_tree_walker_focus_navigation(engine);
+    test_node_iterator_dompurify_traversal(engine);
+    test_node_iterator_linear_performance_gate(engine);
     test_table_cell_click_copies_text_to_host();
     test_synthetic_window_resize_dispatch_uses_outer_listener_registry(engine);
     test_document_create_event_and_init_event(engine);

tests/WebPlatformSubset/capabilities.json

@@ -302,11 +302,11 @@
     },
     {
       "family": "dom-tree-traversal",
-      "required": ["NodeFilter constants", "Document.createTreeWalker", "whatToShow element filtering", "function and object acceptNode filters", "FILTER_ACCEPT inclusion", "FILTER_SKIP descendant traversal", "FILTER_REJECT subtree pruning", "root and mutable currentNode identity", "parent, child, sibling, and document-order navigation"],
+      "required": ["NodeFilter constants", "Document.createTreeWalker", "Document.createNodeIterator", "whatToShow element filtering", "function and object acceptNode filters", "FILTER_ACCEPT inclusion", "FILTER_SKIP descendant traversal", "FILTER_REJECT subtree pruning", "root and mutable currentNode identity", "parent, child, sibling, and document-order navigation", "root-inclusive NodeIterator element/text/comment traversal", "NodeIterator forward/reverse reference state", "linear bounded DOMPurify traversal snapshot"],
       "candidate": [],
       "productEvidence": ["order-menu focus management", "fixed-position menu portal activation"],
-      "coverage": ["contracts/dom-treewalker-nodefilter-focus-navigation.html", "test_node_filter_tree_walker_focus_navigation", "NativeTradingViewTerminal --headless-proof --open-overlay order-menu"],
-      "gap": "The product-neutral contract passes all four assertions and covers the SHOW_ELEMENT, accept/skip/reject, currentNode/root boundaries, child/sibling/document-order paths used by TradingView's focus-navigation utility. The actual hosted bundle opens its order menu without a script error and retains a visible fixed-position portal. NodeIterator, the complete Web IDL prototype/constructor surface, traversal of non-element node kinds, and mutation-during-traversal conformance remain outside this bounded implementation."
+      "coverage": ["contracts/dom-treewalker-nodefilter-focus-navigation.html", "test_node_filter_tree_walker_focus_navigation", "test_node_iterator_dompurify_traversal", "test_node_iterator_linear_performance_gate", "NativeTradingViewTerminal --headless-proof --open-overlay order-menu"],
+      "gap": "The product-neutral contract covers the SHOW_ELEMENT, accept/skip/reject, currentNode/root boundaries, child/sibling/document-order paths used by TradingView's focus-navigation utility, plus the root-inclusive element/text/comment NodeIterator path captured by DOMPurify in Code OSS. The actual hosted bundle opens its order menu without a script error and retains a visible fixed-position portal. NodeIterator uses one O(n), root-bounded snapshot so sanitizer removals cannot make traversal quadratic; live mutation adjustment, the complete Web IDL prototype/constructor surface, and every node-kind edge case remain outside this bounded implementation."
     },
     {
       "family": "system-ui-text-paint",

tests/WebPlatformSubset/contracts/dom-treewalker-nodefilter-focus-navigation.html

@@ -76,6 +76,28 @@
     assert(walker.nextSibling() === null, "nextSibling escaped the TreeWalker root");
   });
 
+  test("NodeIterator provides root-bounded DOMPurify traversal", () => {
+    const iterator = document.createNodeIterator(
+      root,
+      NodeFilter.SHOW_ELEMENT,
+      node => node.matches("button, #deep")
+        ? NodeFilter.FILTER_ACCEPT
+        : node.classList.contains("reject")
+          ? NodeFilter.FILTER_REJECT
+          : NodeFilter.FILTER_SKIP);
+    assert(iterator instanceof NodeIterator,
+      "createNodeIterator did not return a NodeIterator");
+    assert(iterator.root === root, "NodeIterator root identity changed");
+    const ids = [];
+    for (let node = iterator.nextNode(); node; node = iterator.nextNode()) ids.push(node.id);
+    assert(ids.join(",") === "first,nested,rejected,last,deep",
+      `NodeIterator order was ${ids.join(",")}`);
+    assert(iterator.previousNode()?.id === "deep",
+      "NodeIterator did not reverse from the end boundary");
+    assert(iterator.previousNode()?.id === "last",
+      "NodeIterator reverse order was incorrect");
+  });
+
   const failure = state.results.find(result => result.status !== "PASS");
   state.harness = failure
     ? { status: 1, message: failure.message, stack: failure.stack }

tests/WebPlatformSubset/webscene-component-profile.json

@@ -755,9 +755,9 @@
     {
       "path": "contracts/dom-treewalker-nodefilter-focus-navigation.html",
       "type": "contract",
-      "capabilities": ["nodefilter-constants", "document-create-tree-walker", "treewalker-filter-semantics", "focus-navigation-tree-traversal"],
-      "evidence": ["browser-authorized-order-menu-focus-management", "native-treewalker-regression", "actual-tradingview-order-menu-proof"],
-      "reason": "Product-neutral reduction of the focus-navigation primitive used by the TradingView order-menu portal. It verifies SHOW_ELEMENT filtering, FILTER_ACCEPT/SKIP/REJECT subtree semantics, currentNode/root identity and boundaries, document-order traversal, sibling navigation across skipped wrappers, and the lastChild/previousNode pattern used to locate focusable descendants."
+      "capabilities": ["nodefilter-constants", "document-create-tree-walker", "document-create-node-iterator", "treewalker-filter-semantics", "node-iterator-dompurify-traversal", "focus-navigation-tree-traversal"],
+      "evidence": ["browser-authorized-order-menu-focus-management", "native-treewalker-regression", "native-node-iterator-regression", "actual-tradingview-order-menu-proof"],
+      "reason": "Product-neutral reduction of the focus-navigation primitive used by the TradingView order-menu portal and the DOMPurify traversal used by Code OSS chat rendering. It verifies SHOW_ELEMENT filtering, FILTER_ACCEPT/SKIP/REJECT semantics, currentNode/root identity and boundaries, TreeWalker navigation across skipped wrappers, and root-inclusive NodeIterator forward/reverse document-order traversal."
     },
     {
       "path": "contracts/dom-scope-descendant-selector.html",