@miaskiewicz/turbo-dom 0.2.5 → 0.3.1

package/Cargo.lock

@@ -488,9 +488,18 @@ dependencies = [
  "utf-8",
 ]
 
+[[package]]
+name = "turbo-dom"
+version = "0.3.1"
+dependencies = [
+ "html5ever",
+ "markup5ever_rcdom",
+ "rustc-hash",
+]
+
 [[package]]
 name = "turbo-dom-parser"
-version = "0.2.4"
+version = "0.3.1"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",

package/Cargo.toml

@@ -1,6 +1,11 @@
+[workspace]
+# The root package (turbo-dom-parser) plus the standalone Rust-native DOM runtime
+# crate published to crates.io as `turbo-dom`. The parser ships to npm.
+members = ["crates/turbo-dom"]
+
 [package]
 name = "turbo-dom-parser"
-version = "0.2.4"
+version = "0.3.1"
 edition = "2021"
 description = "html5ever-backed native parser for turbo-dom (Layer 1)"
 
@@ -29,6 +34,13 @@ napi-build = { version = "2", optional = true }
 default = ["napi-bind"]
 napi-bind = ["dep:napi", "dep:napi-derive", "dep:napi-build"]
 wasm-bind = ["dep:wasm-bindgen", "dep:serde", "dep:serde-wasm-bindgen"]
+# Phase-1 boundary spike: Rust DOM runtime over the SoA, exported to JS via wasm-bindgen.
+wasm-runtime = ["dep:wasm-bindgen"]
+# Pure-Rust DOM runtime (the `rtdom` module). Off by default so the published
+# napi `.node` + wasm parser artifacts stay lean — no JS consumer uses rtdom (a
+# JS-side WASM/napi boundary measured SLOWER than the JS runtime). A Rust consumer
+# adds this crate as a dep and enables this feature; deps are pure std + core.
+rust-runtime = []
 
 [profile.release]
 lto = true

package/README.md

@@ -188,6 +188,46 @@ The parser runs in Rust (compute-bound, one boundary crossing per parse). The DO
 JS (chatty, fine-grained) but pays only for what a test touches. Full design notes:
 [turbo-dom-spec.md](./turbo-dom-spec.md).
 
+## Rust-native DOM runtime (`rtdom`) — for Rust consumers
+
+Everything above is the **JS-consumer** path: the DOM is JS objects, so React/RTL touch it with
+zero boundary — that's why it's fast for vitest/jest. A **Rust** consumer (crawler, extractor,
+server-side scraper) wants the opposite: the DOM in-process in Rust, no JS at all. For that there's
+**`rtdom`** — a pure-Rust port of the runtime (lazy copy-on-write tree over the same SoA buffer,
+version-cached queries, partial `getComputedStyle`, events, shadow DOM, serialize).
+
+Why a separate runtime instead of exposing this one to Rust via WASM? Measured: a Rust-DOM-in-WASM
+called *from JS* is **~0.55×** the JS runtime (the boundary crossing dominates — exactly what the
+[spec §3](./turbo-dom-spec.md) predicted), while `rtdom` run **in-process from Rust** is **~2.7×**
+the JS runtime on the same chatty workload (zero boundary). So: JS consumers keep the JS runtime,
+Rust consumers use `rtdom`.
+
+Add it to a Rust project from crates.io (the `turbo-dom` crate is the Rust-native
+runtime; the npm `@miaskiewicz/turbo-dom` is the JS path):
+
+```bash
+cargo add turbo-dom
+```
+
+```rust
+use turbo_dom::{Dom, DocumentExt};
+use turbo_dom::rtdom::cascade;
+
+let mut dom = Dom::parse("<main class=grid><div class=card id=hero>hi</div></main>");
+let cards = dom.tree.query_selector_all("div.card");        // version-cached, in-process
+let id = dom.tree.get_attribute(cards[0], "id");            // Some("hero") — plain Rust call
+let style = cascade::computed_style(&dom.tree, cards[0]);   // partial honest cascade
+```
+
+- **crates.io:** [`turbo-dom`](https://crates.io/crates/turbo-dom) — the self-contained,
+  publishable crate (workspace member `crates/turbo-dom/`) with minimal deps
+  (`html5ever` + `rustc-hash`, no napi/wasm) and a runnable `examples/crawl.rs`. 192 tests.
+- **In this repo (parser crate):** the same runtime also lives at `src/rtdom/` behind an
+  off-by-default `rust-runtime` cargo feature, so the published npm `.node`/wasm parser artifacts
+  stay lean. Build it with `npm run build:rtdom`
+  (= `cargo build --release --no-default-features --features rust-runtime`). 100% line coverage,
+  a direct html5lib-tests gate at **99.75%** (`npm run conformance:rtdom`).
+
 ## Limitations (by design)
 
 - **No layout.** `getBoundingClientRect()` returns zeros; `getClientRects()` is empty.
@@ -226,14 +266,21 @@ Requires Node ≥ 18 and a Rust toolchain (`rustup`, stable).
 
 ```bash
 npm install
-npm run build          # native addon (.node)
-npm test               # JS suite (unit, conformance, differential, gauntlets)
-npm run test:rust      # Rust core tests
-npm run conformance    # html5lib-tests report
-npm run bench:all      # benchmarks
-npm run build:wasm     # wasm32 fallback
+npm run build           # native addon (.node) + wasm — the JS-consumer artifacts
+npm test                # JS suite (unit, conformance, differential, gauntlets)
+npm run test:rust       # Rust tests: parser core + rtdom (uses --features rust-runtime)
+npm run conformance     # html5lib-tests report (parser)
+npm run conformance:rtdom  # html5lib-tests gate run through the rtdom tree
+npm run bench:all       # JS-runtime benchmarks
+npm run build:wasm      # wasm32 parser fallback
+npm run build:rtdom     # pure-Rust DOM runtime (no napi/wasm) — the Rust-consumer build
 ```
 
+The JS runtime (`src/runtime/*.mjs`) and the Rust runtime (`src/rtdom/`, gated behind
+`rust-runtime`) are independent — touching one never affects the other. See
+[RUST_PORT_PLAN.md](./RUST_PORT_PLAN.md) for the dual-runtime architecture and
+[RUST_PORT_PERF_HISTORY.md](./RUST_PORT_PERF_HISTORY.md) for how each JS perf win maps to Rust.
+
 Contributions welcome — issues and PRs at
 [github.com/miaskiewicz/turbo-dom](https://github.com/miaskiewicz/turbo-dom).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miaskiewicz/turbo-dom",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Faster, more spec-correct DOM for test runners — native html5ever (Rust/WASM) parser + lazy copy-on-write DOM. A drop-in-style alternative to jsdom/happy-dom for vitest & jest.",
   "license": "MIT",
   "main": "index.js",
@@ -76,7 +76,7 @@
     "build:wasm:web": "wasm-pack build --target web --out-dir pkg-web --no-default-features --features wasm-bind",
     "test": "node --test 'test/*.mjs'",
     "test:cov": "node --test --experimental-test-coverage --test-coverage-include='src/runtime/**' --test-coverage-lines=99 --test-coverage-functions=95 --test-coverage-branches=95 'test/*.mjs'",
-    "test:rust": "cargo test --lib",
+    "test:rust": "cargo test --lib --features rust-runtime",
     "test:all": "npm run build && npm run test:rust && npm test",
     "prepare": "git config core.hooksPath .githooks || true",
     "conformance": "node harness/conformance.mjs",
@@ -90,7 +90,11 @@
     "test:vitest": "vitest run -c test-vitest/vitest.config.mjs",
     "test:jest": "jest -c test-jest/jest.config.cjs",
     "bench:query": "node bench/query.mjs",
-    "bench:scorecard": "node bench/scorecard.mjs"
+    "bench:scorecard": "node bench/scorecard.mjs",
+    "conformance:rtdom": "cargo test --lib --features rust-runtime rtdom::conformance::rtdom_html5lib_conformance_full_document -- --nocapture",
+    "build:rtdom": "cargo build --release --no-default-features --features rust-runtime",
+    "bench:compare": "node bench/dom-compare.mjs",
+    "bench:compare:all": "RTDOM_JSON=\"$(cargo test --release --lib --features rust-runtime rtdom::bench::compare_all -- --ignored --nocapture 2>/dev/null | sed -n 's/.*RTDOM_JSON //p')\" node --expose-gc --max-old-space-size=8192 bench/compare-all.mjs"
   },
   "keywords": [
     "dom",

package/src/lib.rs

@@ -6,6 +6,15 @@
 
 pub mod core;
 
+// Pure-Rust DOM runtime (native Rust API; no wasm-bindgen / napi). Off by default
+// so shipped parser artifacts stay lean — a Rust consumer enables `rust-runtime`.
+#[cfg(feature = "rust-runtime")]
+pub mod rtdom;
+
+// Phase-1 boundary spike (Rust DOM runtime exported to JS via wasm-bindgen).
+#[cfg(feature = "wasm-runtime")]
+pub mod spike;
+
 // ---------------------------------------------------------------------------
 // napi-rs front-end (native addon)
 // ---------------------------------------------------------------------------

package/src/spike.rs

@@ -0,0 +1,301 @@
+//! Phase-1 boundary spike (feature = "wasm-runtime"). NOT the final runtime.
+//!
+//! Goal: measure the JS<->WASM boundary cost of a Rust-core DOM accessed from JS
+//! on the chattiest hot paths (querySelectorAll + getAttribute + parent-walk +
+//! listener-less dispatch walk), vs the current pure-JS runtime. Read-only tree
+//! over `core::Soa` (handle = node index) — no mutation/COW needed for the gate.
+//!
+//! Two access shapes are exported so the bench can A/B them:
+//!   * MITIGATED (Option A) — qsa returns a packed Uint32Array in ONE crossing;
+//!     structure reads return ints (handles/ids); strings resolved JS-side from
+//!     bulk blobs pulled once. Boundary crossings ~ O(results), not O(nodes*fields).
+//!   * NAIVE — per-node string returns (tag_name/get_attr as String) to show the
+//!     cost the mitigations avoid.
+
+use crate::core::{self, Soa};
+use std::cell::RefCell;
+use wasm_bindgen::prelude::*;
+
+const ELEMENT_NODE: u8 = 1;
+
+struct Doc {
+    soa: Soa,
+}
+
+thread_local! {
+    static DOCS: RefCell<Vec<Doc>> = RefCell::new(Vec::new());
+}
+
+fn with_doc<R>(doc: u32, f: impl FnOnce(&Doc) -> R) -> R {
+    DOCS.with(|d| f(&d.borrow()[doc as usize]))
+}
+
+/// Parse + register a document. Returns the doc handle. ONE crossing per parse.
+#[wasm_bindgen]
+pub fn create(html: &str) -> u32 {
+    let soa = core::parse_html_soa(html);
+    DOCS.with(|d| {
+        let mut v = d.borrow_mut();
+        v.push(Doc { soa });
+        (v.len() - 1) as u32
+    })
+}
+
+/// Drop a doc (free reset path).
+#[wasm_bindgen]
+pub fn destroy(doc: u32) {
+    DOCS.with(|d| {
+        let mut v = d.borrow_mut();
+        if (doc as usize) < v.len() {
+            v[doc as usize] = Doc { soa: core::parse_html_soa("") };
+        }
+    });
+}
+
+// --- bulk string blobs: pulled ONCE per doc, split JS-side into a string table ---
+// `\u{1f}` (unit separator) join — safe vs HTML text which never contains it.
+fn join_blob(v: &[String]) -> String {
+    v.join("\u{1f}")
+}
+
+#[wasm_bindgen]
+pub fn tag_names_blob(doc: u32) -> String {
+    with_doc(doc, |d| join_blob(&d.soa.tag_names))
+}
+#[wasm_bindgen]
+pub fn attr_names_blob(doc: u32) -> String {
+    with_doc(doc, |d| join_blob(&d.soa.attr_names))
+}
+#[wasm_bindgen]
+pub fn attr_values_blob(doc: u32) -> String {
+    with_doc(doc, |d| join_blob(&d.soa.attr_values))
+}
+#[wasm_bindgen]
+pub fn strings_blob(doc: u32) -> String {
+    with_doc(doc, |d| join_blob(&d.soa.strings))
+}
+
+#[wasm_bindgen]
+pub fn node_count(doc: u32) -> u32 {
+    with_doc(doc, |d| d.soa.node_type.len() as u32)
+}
+
+// --- MITIGATED per-node structure reads (ints only, no string marshaling) ---
+#[wasm_bindgen]
+pub fn node_type(doc: u32, h: u32) -> u8 {
+    with_doc(doc, |d| d.soa.node_type[h as usize])
+}
+#[wasm_bindgen]
+pub fn tag_id(doc: u32, h: u32) -> i32 {
+    with_doc(doc, |d| {
+        let i = h as usize;
+        if d.soa.node_type[i] == ELEMENT_NODE { d.soa.tag_id[i] as i32 } else { -1 }
+    })
+}
+#[wasm_bindgen]
+pub fn parent(doc: u32, h: u32) -> i32 {
+    with_doc(doc, |d| d.soa.parent[h as usize])
+}
+#[wasm_bindgen]
+pub fn first_child(doc: u32, h: u32) -> i32 {
+    with_doc(doc, |d| d.soa.first_child[h as usize])
+}
+#[wasm_bindgen]
+pub fn next_sib(doc: u32, h: u32) -> i32 {
+    with_doc(doc, |d| d.soa.next_sib[h as usize])
+}
+#[wasm_bindgen]
+pub fn text_id(doc: u32, h: u32) -> i32 {
+    with_doc(doc, |d| d.soa.text_id[h as usize])
+}
+
+/// MITIGATED getAttribute: returns the interned attr_value id (-1 if absent).
+/// JS resolves the id against the attr_values string table (no per-call string).
+/// `name` still crosses as &str (RTL passes a literal) — small inbound cost.
+#[wasm_bindgen]
+pub fn get_attr_id(doc: u32, h: u32, name: &str) -> i32 {
+    with_doc(doc, |d| attr_value_id(&d.soa, h as usize, name).map_or(-1, |v| v as i32))
+}
+
+/// NAIVE getAttribute: returns the value String (per-call UTF-8 marshal).
+#[wasm_bindgen]
+pub fn get_attr_str(doc: u32, h: u32, name: &str) -> Option<String> {
+    with_doc(doc, |d| {
+        attr_value_id(&d.soa, h as usize, name).map(|v| d.soa.attr_values[v as usize].clone())
+    })
+}
+
+/// NAIVE tagName: per-call String marshal.
+#[wasm_bindgen]
+pub fn tag_name_str(doc: u32, h: u32) -> Option<String> {
+    with_doc(doc, |d| {
+        let i = h as usize;
+        if d.soa.node_type[i] == ELEMENT_NODE {
+            Some(d.soa.tag_names[d.soa.tag_id[i] as usize].clone())
+        } else {
+            None
+        }
+    })
+}
+
+fn attr_value_id(soa: &Soa, i: usize, name: &str) -> Option<u32> {
+    let start = soa.attr_start[i];
+    if start < 0 {
+        return None;
+    }
+    let start = start as usize;
+    let count = soa.attr_count[i] as usize;
+    for j in start..start + count {
+        let nid = soa.attr_name_id[j] as usize;
+        if soa.attr_names[nid] == name {
+            return Some(soa.attr_value_id[j]);
+        }
+    }
+    None
+}
+
+/// MITIGATED+: prefetch a node's whole record in ONE crossing. Layout:
+/// [tag_id, parent, attr_count, (name_id, value_id)*]. JS caches it on the wrapper
+/// and serves tagName/getAttribute/parentNode from the cache (0 further crossings
+/// until the version bumps). This is the Option-A "cache scalars on the wrapper" path.
+#[wasm_bindgen]
+pub fn node_record(doc: u32, h: u32) -> Vec<i32> {
+    with_doc(doc, |d| {
+        let i = h as usize;
+        let tag = if d.soa.node_type[i] == ELEMENT_NODE { d.soa.tag_id[i] as i32 } else { -1 };
+        let start = d.soa.attr_start[i];
+        let count = if start < 0 { 0 } else { d.soa.attr_count[i] as usize };
+        let mut out = Vec::with_capacity(3 + count * 2);
+        out.push(tag);
+        out.push(d.soa.parent[i]);
+        out.push(count as i32);
+        if start >= 0 {
+            let s = start as usize;
+            for j in s..s + count {
+                out.push(d.soa.attr_name_id[j] as i32);
+                out.push(d.soa.attr_value_id[j] as i32);
+            }
+        }
+        out
+    })
+}
+
+/// Listener-less dispatch path: walk ancestors to the root, return path length.
+/// Models the single ancestor-walk dispatch does (no JS callbacks crossed).
+#[wasm_bindgen]
+pub fn dispatch_walk(doc: u32, h: u32) -> u32 {
+    with_doc(doc, |d| {
+        let mut len = 1u32; // target
+        let mut cur = d.soa.parent[h as usize];
+        while cur >= 0 {
+            len += 1;
+            cur = d.soa.parent[cur as usize];
+        }
+        len
+    })
+}
+
+// --- MITIGATED querySelectorAll: matched entirely Rust-side, ONE crossing out ---
+// Minimal selector support for the spike: a compound `tag`, `.class`, `#id`, or any
+// concatenation (`div.card`, `.a.b`, `#id.x`). No combinators (enough for `div.card`).
+struct Compound<'a> {
+    tag: Option<&'a str>,
+    id: Option<&'a str>,
+    classes: Vec<&'a str>,
+}
+
+fn parse_compound(sel: &str) -> Compound<'_> {
+    let s = sel.trim();
+    let mut c = Compound { tag: None, id: None, classes: Vec::new() };
+    let mut i = 0;
+    let bytes = s.as_bytes();
+    // leading type selector
+    if i < bytes.len() && bytes[i] != b'.' && bytes[i] != b'#' {
+        let start = i;
+        while i < bytes.len() && bytes[i] != b'.' && bytes[i] != b'#' {
+            i += 1;
+        }
+        c.tag = Some(&s[start..i]);
+    }
+    while i < bytes.len() {
+        let kind = bytes[i];
+        i += 1;
+        let start = i;
+        while i < bytes.len() && bytes[i] != b'.' && bytes[i] != b'#' {
+            i += 1;
+        }
+        let tok = &s[start..i];
+        match kind {
+            b'.' => c.classes.push(tok),
+            b'#' => c.id = Some(tok),
+            _ => {}
+        }
+    }
+    c
+}
+
+/// whole-word class scan (alloc-free) — mirrors the JS `hasClass` discipline.
+fn has_class(class_attr: &str, cls: &str) -> bool {
+    if cls.is_empty() {
+        return false;
+    }
+    let mut rest = class_attr;
+    loop {
+        match rest.find(cls) {
+            None => return false,
+            Some(pos) => {
+                let before_ok = pos == 0 || rest.as_bytes()[pos - 1].is_ascii_whitespace();
+                let end = pos + cls.len();
+                let after_ok = end == rest.len() || rest.as_bytes()[end].is_ascii_whitespace();
+                if before_ok && after_ok {
+                    return true;
+                }
+                rest = &rest[end..];
+            }
+        }
+    }
+}
+
+fn matches(soa: &Soa, i: usize, c: &Compound) -> bool {
+    if soa.node_type[i] != ELEMENT_NODE {
+        return false;
+    }
+    if let Some(tag) = c.tag {
+        if soa.tag_names[soa.tag_id[i] as usize] != tag {
+            return false;
+        }
+    }
+    if let Some(id) = c.id {
+        match attr_value_id(soa, i, "id") {
+            Some(v) if soa.attr_values[v as usize] == id => {}
+            _ => return false,
+        }
+    }
+    if !c.classes.is_empty() {
+        let cv = match attr_value_id(soa, i, "class") {
+            Some(v) => &soa.attr_values[v as usize],
+            None => return false,
+        };
+        for cls in &c.classes {
+            if !has_class(cv, cls) {
+                return false;
+            }
+        }
+    }
+    true
+}
+
+#[wasm_bindgen]
+pub fn qsa(doc: u32, selector: &str) -> Vec<u32> {
+    with_doc(doc, |d| {
+        let c = parse_compound(selector);
+        let n = d.soa.node_type.len();
+        let mut out = Vec::new();
+        for i in 0..n {
+            if matches(&d.soa, i, &c) {
+                out.push(i as u32);
+            }
+        }
+        out
+    })
+}