@salve-software/react-native-nitro-jsdom 1.0.1 → 2.0.0

package/cpp/quickjs/bindings/TemplateBindings.hpp

@@ -0,0 +1,29 @@
+#pragma once
+
+#include "quickjs.h"
+
+namespace margelo::nitro::nitrojsdom {
+
+// Registers a `content` getter on Element.prototype, tag-checked for
+// "template" internally (mirroring FormBindings' tag-check pattern) —
+// returns the lxb_dom_document_fragment_t Lexbor already allocates as
+// lxb_html_template_element_t::content, for both parsed and
+// document.createElement()'d <template> elements. No custom parsing logic:
+// Lexbor's own HTML5 tree constructor already redirects a parsed
+// <template>'s children into that fragment instead of the template's own
+// light-DOM children (see packages/lexbor/.../tree/insertion_mode/in_template.c).
+// LexborDocument::setInnerHTMLOnEl() mirrors that for template.innerHTML=.
+//
+// Scope: the returned fragment is a generic Node wrapper (like
+// document.createDocumentFragment()), so it has childNodes/appendChild/etc.
+// but not querySelector(All) — same limitation createDocumentFragment()
+// already has. cloneNode() on a <template> does not specially deep-clone
+// `.content` (relies on Lexbor's own node clone, not verified against spec
+// for this case) — undocumented/untested edge case, not the golden path.
+//
+// Must run after ElementBindings (globalThis.Element, unwrap_element).
+struct TemplateBindings {
+  static void install(JSContext* ctx);
+};
+
+} // namespace margelo::nitro::nitrojsdom

package/cpp/quickjs/bindings/TextEncodingBindings.cpp

@@ -0,0 +1,117 @@
+#include "TextEncodingBindings.hpp"
+#include <cstring>
+
+namespace margelo::nitro::nitrojsdom {
+
+namespace {
+
+const char* kTextEncodingBootstrapScript = R"JS(
+(function() {
+  function TextEncoder() {
+    this.encoding = 'utf-8';
+  }
+  TextEncoder.prototype.encode = function(input) {
+    var str = String(input === undefined ? '' : input);
+    var bytes = [];
+    for (var i = 0; i < str.length; i++) {
+      var code = str.charCodeAt(i);
+      if (code >= 0xD800 && code <= 0xDBFF && i + 1 < str.length) {
+        var next = str.charCodeAt(i + 1);
+        if (next >= 0xDC00 && next <= 0xDFFF) {
+          code = ((code - 0xD800) << 10) + (next - 0xDC00) + 0x10000;
+          i++;
+        }
+      }
+      if (code < 0x80) {
+        bytes.push(code);
+      } else if (code < 0x800) {
+        bytes.push(0xC0 | (code >> 6), 0x80 | (code & 0x3F));
+      } else if (code < 0x10000) {
+        bytes.push(0xE0 | (code >> 12), 0x80 | ((code >> 6) & 0x3F), 0x80 | (code & 0x3F));
+      } else {
+        bytes.push(
+          0xF0 | (code >> 18),
+          0x80 | ((code >> 12) & 0x3F),
+          0x80 | ((code >> 6) & 0x3F),
+          0x80 | (code & 0x3F)
+        );
+      }
+    }
+    return new Uint8Array(bytes);
+  };
+  TextEncoder.prototype.encodeInto = function(input, dest) {
+    var encoded = this.encode(input);
+    var written = Math.min(encoded.length, dest.length);
+    for (var i = 0; i < written; i++) dest[i] = encoded[i];
+    return { read: written === encoded.length ? String(input).length : written, written: written };
+  };
+
+  function TextDecoder(label, options) {
+    this.encoding = label ? String(label).toLowerCase() : 'utf-8';
+    this.fatal = !!(options && options.fatal);
+    this.ignoreBOM = !!(options && options.ignoreBOM);
+  }
+  TextDecoder.prototype.decode = function(input) {
+    var bytes;
+    if (input === undefined) {
+      bytes = new Uint8Array(0);
+    } else if (input instanceof ArrayBuffer) {
+      bytes = new Uint8Array(input);
+    } else if (input && input.buffer !== undefined) {
+      bytes = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
+    } else {
+      bytes = new Uint8Array(0);
+    }
+
+    var result = '';
+    var i = 0;
+    while (i < bytes.length) {
+      var b0 = bytes[i];
+      var codepoint, len;
+      if (b0 < 0x80) { codepoint = b0; len = 1; }
+      else if ((b0 & 0xE0) === 0xC0) { codepoint = b0 & 0x1F; len = 2; }
+      else if ((b0 & 0xF0) === 0xE0) { codepoint = b0 & 0x0F; len = 3; }
+      else if ((b0 & 0xF8) === 0xF0) { codepoint = b0 & 0x07; len = 4; }
+      else {
+        if (this.fatal) throw new TypeError('The encoded data was not valid UTF-8.');
+        result += '�';
+        i++;
+        continue;
+      }
+      if (i + len > bytes.length) {
+        if (this.fatal) throw new TypeError('The encoded data was not valid UTF-8.');
+        result += '�';
+        break;
+      }
+      for (var k = 1; k < len; k++) {
+        codepoint = (codepoint << 6) | (bytes[i + k] & 0x3F);
+      }
+      if (codepoint > 0xFFFF) {
+        codepoint -= 0x10000;
+        result += String.fromCharCode(0xD800 + (codepoint >> 10), 0xDC00 + (codepoint & 0x3FF));
+      } else {
+        result += String.fromCharCode(codepoint);
+      }
+      i += len;
+    }
+    if (!this.ignoreBOM && result.charCodeAt(0) === 0xFEFF) result = result.slice(1);
+    return result;
+  };
+
+  globalThis.TextEncoder = TextEncoder;
+  globalThis.TextDecoder = TextDecoder;
+})();
+)JS";
+
+} // namespace
+
+void TextEncodingBindings::install(JSContext* ctx) {
+  JSValue result = JS_Eval(ctx, kTextEncodingBootstrapScript, strlen(kTextEncodingBootstrapScript),
+                            "<text-encoding-bootstrap>", JS_EVAL_TYPE_GLOBAL);
+  if (JS_IsException(result)) {
+    JS_FreeValue(ctx, JS_GetException(ctx));
+  }
+  JS_FreeValue(ctx, result);
+}
+
+} // namespace margelo::nitro::nitrojsdom

package/cpp/quickjs/bindings/TextEncodingBindings.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+#include "quickjs.h"
+
+namespace margelo::nitro::nitrojsdom {
+
+// Registers globalThis.TextEncoder/TextDecoder (UTF-8 only — the vast
+// majority of real-world usage — implemented in pure JS since encoding a
+// JS string's UTF-16 code units to UTF-8 bytes needs no native primitive).
+struct TextEncodingBindings {
+  static void install(JSContext* ctx);
+};
+
+} // namespace margelo::nitro::nitrojsdom

package/cpp/quickjs/bindings/TimerBindings.cpp

@@ -2,6 +2,7 @@
 #include "../DOMBindingsInternal.hpp"
 #include "../QuickJSRuntime.hpp"
 #include <chrono>
+#include <cstring>
 
 namespace margelo::nitro::nitrojsdom {
 
@@ -12,6 +13,17 @@ int64_t dom_now_ms() {
   return duration_cast<milliseconds>(steady_clock::now().time_since_epoch()).count();
 }
 
+double dom_now_high_res_ms() {
+  using namespace std::chrono;
+  return duration<double, std::milli>(steady_clock::now().time_since_epoch()).count();
+}
+
+JSValue js_native_now_ms(JSContext* ctx, JSValue, int, JSValue*) {
+  auto* rctx = get_ctx(ctx);
+  double origin = rctx ? rctx->time_origin_ms : 0.0;
+  return JS_NewFloat64(ctx, dom_now_high_res_ms() - origin);
+}
+
 JSValue js_setTimeout(JSContext* ctx, JSValue, int argc, JSValue* argv) {
   if (argc < 1 || !JS_IsFunction(ctx, argv[0])) return JS_NewInt32(ctx, 0);
   auto* rctx = get_ctx(ctx);
@@ -80,15 +92,123 @@ JSValue js_clearTimer(JSContext* ctx, JSValue, int argc, JSValue* argv) {
   return JS_UNDEFINED;
 }
 
+const char* kTimerBootstrapScript = R"JS(
+(function() {
+  globalThis.performance = globalThis.performance || {};
+  globalThis.performance.now = function() { return __nativeNowMs(); };
+
+  globalThis.requestAnimationFrame = function(callback) {
+    return setTimeout(function() { callback(performance.now()); }, 16);
+  };
+  globalThis.cancelAnimationFrame = function(id) {
+    clearTimeout(id);
+  };
+
+  globalThis.queueMicrotask = function(callback) {
+    Promise.resolve().then(function() { callback(); });
+  };
+
+  globalThis.requestIdleCallback = function(callback, options) {
+    var timeout = options && options.timeout;
+    return setTimeout(function() {
+      callback({
+        didTimeout: false,
+        timeRemaining: function() { return 50; },
+      });
+    }, typeof timeout === 'number' ? Math.min(timeout, 1) : 1);
+  };
+  globalThis.cancelIdleCallback = function(id) {
+    clearTimeout(id);
+  };
+
+  var __perfEntries = [];
+  function __perfFindMark(name) {
+    for (var i = __perfEntries.length - 1; i >= 0; i--) {
+      if (__perfEntries[i].name === name && __perfEntries[i].entryType === 'mark') return __perfEntries[i];
+    }
+    return null;
+  }
+  function __perfRequireMark(name) {
+    var entry = __perfFindMark(name);
+    if (!entry) {
+      throw new DOMException(
+        "Failed to execute 'measure' on 'Performance': The mark '" + name + "' does not exist.", 'SyntaxError');
+    }
+    return entry.startTime;
+  }
+  performance.mark = function(name, options) {
+    var entry = {
+      name: String(name),
+      entryType: 'mark',
+      startTime: (options && options.startTime !== undefined) ? options.startTime : performance.now(),
+      duration: 0,
+      detail: (options && options.detail !== undefined) ? options.detail : null,
+    };
+    __perfEntries.push(entry);
+    return entry;
+  };
+  performance.measure = function(name, startOrOptions, endMark) {
+    var startTime = 0;
+    var endTime = performance.now();
+    var detail = null;
+    if (typeof startOrOptions === 'string') {
+      startTime = __perfRequireMark(startOrOptions);
+      if (endMark !== undefined) endTime = __perfRequireMark(endMark);
+    } else if (startOrOptions && typeof startOrOptions === 'object') {
+      if (startOrOptions.detail !== undefined) detail = startOrOptions.detail;
+      if (startOrOptions.start !== undefined) {
+        startTime = typeof startOrOptions.start === 'string' ? __perfRequireMark(startOrOptions.start) : startOrOptions.start;
+      }
+      if (startOrOptions.end !== undefined) {
+        endTime = typeof startOrOptions.end === 'string' ? __perfRequireMark(startOrOptions.end) : startOrOptions.end;
+      } else if (startOrOptions.duration !== undefined) {
+        endTime = startTime + startOrOptions.duration;
+      }
+    }
+    var entry = { name: String(name), entryType: 'measure', startTime: startTime, duration: endTime - startTime, detail: detail };
+    __perfEntries.push(entry);
+    return entry;
+  };
+  performance.getEntries = function() { return __perfEntries.slice(); };
+  performance.getEntriesByType = function(type) {
+    return __perfEntries.filter(function(e) { return e.entryType === type; });
+  };
+  performance.getEntriesByName = function(name, type) {
+    return __perfEntries.filter(function(e) { return e.name === name && (!type || e.entryType === type); });
+  };
+  performance.clearMarks = function(name) {
+    __perfEntries = __perfEntries.filter(function(e) {
+      return e.entryType !== 'mark' || (name !== undefined && e.name !== name);
+    });
+  };
+  performance.clearMeasures = function(name) {
+    __perfEntries = __perfEntries.filter(function(e) {
+      return e.entryType !== 'measure' || (name !== undefined && e.name !== name);
+    });
+  };
+})();
+)JS";
+
 } // namespace
 
 void TimerBindings::install(JSContext* ctx) {
+  auto* rctx = get_ctx(ctx);
+  if (rctx) rctx->time_origin_ms = dom_now_high_res_ms();
+
   JSValue global = JS_GetGlobalObject(ctx);
   JS_SetPropertyStr(ctx, global, "setTimeout",    JS_NewCFunction(ctx, js_setTimeout,  "setTimeout",   2));
   JS_SetPropertyStr(ctx, global, "setInterval",   JS_NewCFunction(ctx, js_setInterval, "setInterval",  2));
   JS_SetPropertyStr(ctx, global, "clearTimeout",  JS_NewCFunction(ctx, js_clearTimer,  "clearTimeout", 1));
   JS_SetPropertyStr(ctx, global, "clearInterval", JS_NewCFunction(ctx, js_clearTimer,  "clearInterval",1));
+  JS_SetPropertyStr(ctx, global, "__nativeNowMs", JS_NewCFunction(ctx, js_native_now_ms, "__nativeNowMs", 0));
   JS_FreeValue(ctx, global);
+
+  JSValue result = JS_Eval(ctx, kTimerBootstrapScript, strlen(kTimerBootstrapScript),
+                            "<timer-bootstrap>", JS_EVAL_TYPE_GLOBAL);
+  if (JS_IsException(result)) {
+    JS_FreeValue(ctx, JS_GetException(ctx));
+  }
+  JS_FreeValue(ctx, result);
 }
 
 } // namespace margelo::nitro::nitrojsdom

package/cpp/quickjs/bindings/TreeWalkerBindings.cpp

@@ -0,0 +1,306 @@
+#include "TreeWalkerBindings.hpp"
+#include <cstring>
+
+namespace margelo::nitro::nitrojsdom {
+
+namespace {
+
+const char* kTreeWalkerBootstrapScript = R"JS(
+(function() {
+  var FILTER_ACCEPT = 1, FILTER_REJECT = 2, FILTER_SKIP = 3;
+
+  var NodeFilter = {
+    FILTER_ACCEPT: FILTER_ACCEPT,
+    FILTER_REJECT: FILTER_REJECT,
+    FILTER_SKIP: FILTER_SKIP,
+    SHOW_ALL: 0xFFFFFFFF,
+    SHOW_ELEMENT: 0x1,
+    SHOW_ATTRIBUTE: 0x2,
+    SHOW_TEXT: 0x4,
+    SHOW_CDATA_SECTION: 0x8,
+    SHOW_ENTITY_REFERENCE: 0x10,
+    SHOW_ENTITY: 0x20,
+    SHOW_PROCESSING_INSTRUCTION: 0x40,
+    SHOW_COMMENT: 0x80,
+    SHOW_DOCUMENT: 0x100,
+    SHOW_DOCUMENT_TYPE: 0x200,
+    SHOW_DOCUMENT_FRAGMENT: 0x400,
+    SHOW_NOTATION: 0x800,
+  };
+  globalThis.NodeFilter = NodeFilter;
+
+  function normalizeFilter(filter) {
+    if (filter === undefined || filter === null) return null;
+    if (typeof filter === 'function') return filter;
+    if (typeof filter.acceptNode === 'function') {
+      return function(node) { return filter.acceptNode(node); };
+    }
+    return null;
+  }
+
+  // Shared by TreeWalker and NodeIterator — both store whatToShow/_filterFn/
+  // _active the same way, so this reads `this` structurally rather than
+  // needing a common base class.
+  function applyFilter(walker, node) {
+    if (walker._active) {
+      throw new DOMException('Recursive node filtering', 'InvalidStateError');
+    }
+    var n = node.nodeType - 1;
+    if (!((1 << n) & walker.whatToShow)) return FILTER_SKIP;
+    if (walker._filterFn === null) return FILTER_ACCEPT;
+    walker._active = true;
+    var result;
+    try {
+      result = walker._filterFn(node);
+    } finally {
+      walker._active = false;
+    }
+    return result;
+  }
+
+  // ── TreeWalker ───────────────────────────────────────────────────────
+  // Ported from jsdom's TreeWalker-impl.js — see header comment.
+
+  function TreeWalker(root, whatToShow, filter) {
+    this.root = root;
+    this.whatToShow = whatToShow === undefined ? NodeFilter.SHOW_ALL : (whatToShow >>> 0);
+    this.filter = filter === undefined ? null : filter;
+    this._filterFn = normalizeFilter(filter);
+    this._active = false;
+    this._currentNode = root;
+  }
+  Object.defineProperty(TreeWalker.prototype, 'currentNode', {
+    get: function() { return this._currentNode; },
+    set: function(node) {
+      if (node === null || node === undefined) {
+        throw new DOMException('Cannot set currentNode to null', 'NotSupportedError');
+      }
+      this._currentNode = node;
+    },
+    enumerable: true,
+  });
+
+  TreeWalker.prototype.parentNode = function() {
+    var node = this._currentNode;
+    while (node !== null && node !== this.root) {
+      node = node.parentNode;
+      if (node !== null && applyFilter(this, node) === FILTER_ACCEPT) {
+        this._currentNode = node;
+        return node;
+      }
+    }
+    return null;
+  };
+
+  function traverseChildren(walker, forward) {
+    var node = walker._currentNode;
+    node = forward ? node.firstChild : node.lastChild;
+    if (node === null) return null;
+
+    mainLoop:
+    for (;;) {
+      var result = applyFilter(walker, node);
+      if (result === FILTER_ACCEPT) {
+        walker._currentNode = node;
+        return node;
+      }
+      if (result === FILTER_SKIP) {
+        var child = forward ? node.firstChild : node.lastChild;
+        if (child !== null) { node = child; continue mainLoop; }
+      }
+      for (;;) {
+        var sibling = forward ? node.nextSibling : node.previousSibling;
+        if (sibling !== null) { node = sibling; continue mainLoop; }
+        var parent = node.parentNode;
+        if (parent === null || parent === walker.root || parent === walker._currentNode) return null;
+        node = parent;
+      }
+    }
+  }
+  TreeWalker.prototype.firstChild = function() { return traverseChildren(this, true); };
+  TreeWalker.prototype.lastChild = function() { return traverseChildren(this, false); };
+
+  function traverseSiblings(walker, forward) {
+    var node = walker._currentNode;
+    if (node === walker.root) return null;
+
+    for (;;) {
+      var sibling = forward ? node.nextSibling : node.previousSibling;
+      while (sibling !== null) {
+        node = sibling;
+        var result = applyFilter(walker, node);
+        if (result === FILTER_ACCEPT) {
+          walker._currentNode = node;
+          return node;
+        }
+        sibling = forward ? node.firstChild : node.lastChild;
+        if (result === FILTER_REJECT || sibling === null) {
+          sibling = forward ? node.nextSibling : node.previousSibling;
+        }
+      }
+      node = node.parentNode;
+      if (node === null || node === walker.root) return null;
+      if (applyFilter(walker, node) === FILTER_ACCEPT) return null;
+    }
+  }
+  TreeWalker.prototype.previousSibling = function() { return traverseSiblings(this, false); };
+  TreeWalker.prototype.nextSibling = function() { return traverseSiblings(this, true); };
+
+  TreeWalker.prototype.previousNode = function() {
+    var node = this._currentNode;
+    while (node !== this.root) {
+      var sibling = node.previousSibling;
+      while (sibling !== null) {
+        node = sibling;
+        var result = applyFilter(this, node);
+        while (result !== FILTER_REJECT && node.firstChild !== null) {
+          node = node.lastChild;
+          result = applyFilter(this, node);
+        }
+        if (result === FILTER_ACCEPT) {
+          this._currentNode = node;
+          return node;
+        }
+        sibling = node.previousSibling;
+      }
+      if (node === this.root || node.parentNode === null) return null;
+      node = node.parentNode;
+      if (applyFilter(this, node) === FILTER_ACCEPT) {
+        this._currentNode = node;
+        return node;
+      }
+    }
+    return null;
+  };
+
+  TreeWalker.prototype.nextNode = function() {
+    var node = this._currentNode;
+    var result = FILTER_ACCEPT;
+    for (;;) {
+      while (result !== FILTER_REJECT && node.firstChild !== null) {
+        node = node.firstChild;
+        result = applyFilter(this, node);
+        if (result === FILTER_ACCEPT) {
+          this._currentNode = node;
+          return node;
+        }
+      }
+      var sibling = null;
+      do {
+        if (node === this.root) return null;
+        sibling = node.nextSibling;
+        if (sibling !== null) { node = sibling; break; }
+        node = node.parentNode;
+      } while (node !== null);
+      if (node === null) return null;
+      result = applyFilter(this, node);
+      if (result === FILTER_ACCEPT) {
+        this._currentNode = node;
+        return node;
+      }
+    }
+  };
+
+  globalThis.TreeWalker = TreeWalker;
+
+  // ── NodeIterator ─────────────────────────────────────────────────────
+  // Ported from jsdom's NodeIterator-impl.js, with domSymbolTree.following()/
+  // preceding() replaced by direct tree-order walks over the same node
+  // properties TreeWalker uses.
+
+  function followingNode(node, root) {
+    if (node.firstChild !== null) return node.firstChild;
+    var cur = node;
+    while (cur !== null && cur !== root) {
+      if (cur.nextSibling !== null) return cur.nextSibling;
+      cur = cur.parentNode;
+    }
+    return null;
+  }
+  function lastInclusiveDescendant(node) {
+    while (node.lastChild !== null) node = node.lastChild;
+    return node;
+  }
+  function precedingNode(node, root) {
+    if (node === root) return null;
+    var sibling = node.previousSibling;
+    if (sibling !== null) return lastInclusiveDescendant(sibling);
+    return node.parentNode;
+  }
+
+  function NodeIterator(root, whatToShow, filter) {
+    this.root = root;
+    this.whatToShow = whatToShow === undefined ? NodeFilter.SHOW_ALL : (whatToShow >>> 0);
+    this.filter = filter === undefined ? null : filter;
+    this._filterFn = normalizeFilter(filter);
+    this._active = false;
+    this._referenceNode = root;
+    this._pointerBeforeReferenceNode = true;
+  }
+  Object.defineProperty(NodeIterator.prototype, 'referenceNode', {
+    get: function() { return this._referenceNode; },
+    enumerable: true,
+  });
+  Object.defineProperty(NodeIterator.prototype, 'pointerBeforeReferenceNode', {
+    get: function() { return this._pointerBeforeReferenceNode; },
+    enumerable: true,
+  });
+
+  function iteratorTraverse(it, forward) {
+    var node = it._referenceNode;
+    var beforeNode = it._pointerBeforeReferenceNode;
+    for (;;) {
+      if (forward) {
+        if (!beforeNode) {
+          node = followingNode(node, it.root);
+          if (node === null) return null;
+        }
+        beforeNode = false;
+      } else {
+        if (beforeNode) {
+          node = precedingNode(node, it.root);
+          if (node === null) return null;
+        }
+        beforeNode = true;
+      }
+      if (applyFilter(it, node) === FILTER_ACCEPT) break;
+    }
+    it._referenceNode = node;
+    it._pointerBeforeReferenceNode = beforeNode;
+    return node;
+  }
+
+  NodeIterator.prototype.nextNode = function() { return iteratorTraverse(this, true); };
+  NodeIterator.prototype.previousNode = function() { return iteratorTraverse(this, false); };
+  NodeIterator.prototype.detach = function() {};
+
+  globalThis.NodeIterator = NodeIterator;
+
+  // ── document.createTreeWalker / createNodeIterator ──────────────────
+  document.createTreeWalker = function(root, whatToShow, filter) {
+    if (!(root instanceof Node)) {
+      throw new TypeError("Failed to execute 'createTreeWalker' on 'Document': parameter 1 is not of type 'Node'.");
+    }
+    return new TreeWalker(root, whatToShow, filter);
+  };
+  document.createNodeIterator = function(root, whatToShow, filter) {
+    if (!(root instanceof Node)) {
+      throw new TypeError("Failed to execute 'createNodeIterator' on 'Document': parameter 1 is not of type 'Node'.");
+    }
+    return new NodeIterator(root, whatToShow, filter);
+  };
+})();
+)JS";
+
+} // namespace
+
+void TreeWalkerBindings::install(JSContext* ctx) {
+  JSValue result = JS_Eval(ctx, kTreeWalkerBootstrapScript, strlen(kTreeWalkerBootstrapScript),
+                            "<tree-walker-bootstrap>", JS_EVAL_TYPE_GLOBAL);
+  if (JS_IsException(result)) {
+    JS_FreeValue(ctx, JS_GetException(ctx));
+  }
+  JS_FreeValue(ctx, result);
+}
+
+} // namespace margelo::nitro::nitrojsdom

package/cpp/quickjs/bindings/TreeWalkerBindings.hpp

@@ -0,0 +1,28 @@
+#pragma once
+
+// NodeFilter, TreeWalker, NodeIterator, and document.createTreeWalker() /
+// createNodeIterator(). Pure JS on top of the Node traversal properties
+// ElementBindings already exposes (firstChild/lastChild/nextSibling/
+// previousSibling/parentNode/nodeType) — no Lexbor access needed.
+//
+// The traversal algorithms (TreeWalker.previousSibling()/nextSibling() in
+// particular — they can descend into an accepted-skip subtree looking for a
+// matching descendant, then ascend) are subtle enough that this is a direct
+// port of jsdom's TreeWalker-impl.js/NodeIterator-impl.js/helpers.js, not a
+// from-scratch implementation, to avoid a plausible-looking-but-wrong
+// backtracking bug. NodeIterator's `_referenceNode`/`_pointerBeforeReferenceNode`
+// walk uses simple tree-order successor/predecessor helpers here in place of
+// jsdom's domSymbolTree.following()/preceding() dependency.
+//
+// Must run after ElementBindings (globalThis.Element/Node) and
+// DocumentBindings (globalThis.document).
+
+#include "quickjs.h"
+
+namespace margelo::nitro::nitrojsdom {
+
+struct TreeWalkerBindings {
+  static void install(JSContext* ctx);
+};
+
+} // namespace margelo::nitro::nitrojsdom