@miaskiewicz/turbo-dom 0.3.5 → 0.4.0

package/Cargo.lock

@@ -17,18 +17,40 @@ version = "2.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "84d7ced0ae9557296835c32bf1b1e02b44c746701f898460fb000d7eaa84f00a"
 
+[[package]]
+name = "borsh"
+version = "1.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2f3f6da4992df95bbcd9af42a6c7dcb994498fc9048230405f3b36ff7cd3f145"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.20.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
 
+[[package]]
+name = "bytes"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ae3f5d315924270530207e2a68396c3cc547f6dca3fbdca317cfb1a51edb593"
+
 [[package]]
 name = "cfg-if"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
 
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
 [[package]]
 name = "convert_case"
 version = "0.6.0"
@@ -442,6 +464,16 @@ version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
+[[package]]
+name = "smol_str"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4aaa7368fcf4852a4c2dd92df0cace6a71f2091ca0a23391ce7f3a31833f1523"
+dependencies = [
+ "borsh",
+ "serde_core",
+]
+
 [[package]]
 name = "string_cache"
 version = "0.9.0"
@@ -490,16 +522,18 @@ dependencies = [
 
 [[package]]
 name = "turbo-dom"
-version = "0.3.5"
+version = "0.4.0"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",
  "rustc-hash",
+ "smallvec",
+ "smol_str",
 ]
 
 [[package]]
 name = "turbo-dom-parser"
-version = "0.3.5"
+version = "0.4.0"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",

package/Cargo.toml

@@ -5,7 +5,7 @@ members = ["crates/turbo-dom"]
 
 [package]
 name = "turbo-dom-parser"
-version = "0.3.5"
+version = "0.4.0"
 edition = "2021"
 description = "html5ever-backed native parser for turbo-dom (Layer 1)"
 
@@ -36,12 +36,36 @@ 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 = []
+
+# Same clippy pedantic gate as the turbo-dom crate (crates/turbo-dom/Cargo.toml). The
+# allowed lints are intentional for a parser/marshaling layer that bridges f64 and integer
+# indices and hand-rolls hot loops — documented opt-outs, not silent suppression.
+[lints.clippy]
+pedantic = { level = "warn", priority = -1 }
+cast_possible_truncation = "allow"
+cast_precision_loss = "allow"
+cast_sign_loss = "allow"
+cast_possible_wrap = "allow"
+float_cmp = "allow"
+many_single_char_names = "allow"
+missing_panics_doc = "allow"
+missing_errors_doc = "allow"
+struct_excessive_bools = "allow"
+too_many_lines = "allow"
+implicit_hasher = "allow"
+# The #[napi]/#[wasm_bindgen] parse fns take owned `String` per FFI convention — the
+# marshaled JS string is owned at the boundary and the copy is negligible vs parse cost.
+needless_pass_by_value = "allow"
 
 [profile.release]
 lto = true
 opt-level = 3
+
+# Profiling profile: identical codegen to `release` (lto + opt-level 3) but with
+# debug symbols, so `sample`/Instruments can attribute self-time to source lines.
+# Kept SEPARATE from `[profile.release]` on purpose — the shipped crate stays lean
+# (no debuginfo bloat); this profile is only used by `cargo build --profile profiling`
+# for the CPU profiling harness (examples/churn_profile.rs).
+[profile.profiling]
+inherits = "release"
+debug = true

package/README.md

@@ -219,14 +219,13 @@ let id = dom.tree.get_attribute(cards[0], "id");            // Some("hero") —
 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`).
+- **crates.io:** [`turbo-dom`](https://crates.io/crates/turbo-dom) — the Rust DOM engine lives
+  here and only here (the workspace-member crate `crates/turbo-dom/`; there is no in-repo
+  `src/rtdom` copy and no `rust-runtime` cargo feature — an earlier feature gated a duplicate copy
+  that was consolidated away). Minimal deps (`html5ever` + `rustc-hash`, no napi/wasm), a runnable
+  `examples/crawl.rs`, 227 tests, 100% line coverage, and a direct html5lib-tests gate at
+  **99.75%**. From the repo: `npm run build:rtdom` (= `cargo build -p turbo-dom --release`),
+  `npm run test:rust` (= `cargo test -p turbo-dom`), `npm run conformance:rtdom`.
 
 ## Limitations (by design)
 
@@ -262,13 +261,13 @@ let style = cascade::computed_style(&dom.tree, cards[0]);   // partial honest ca
 
 ## Development
 
-Requires Node ≥ 18 and a Rust toolchain (`rustup`, stable).
+Requires Node ≥ 24 and a Rust toolchain (`rustup`, stable). `mise.toml` pins both.
 
 ```bash
 npm install
 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 test:rust       # Rust tests: parser core + the turbo-dom crate (cargo test -p turbo-dom)
 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
@@ -276,8 +275,8 @@ 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
+The JS runtime (`src/runtime/*.mjs`) and the Rust runtime (the `crates/turbo-dom` crate) 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.
 

package/index.d.ts

@@ -30,7 +30,7 @@ export declare function parse(html: string): JsNode
  */
 export declare function parseRaw(html: string): number
 /**
- * SoA flat buffer: structure as typed arrays, crossed once. JS inflates node
+ * `SoA` flat buffer: structure as typed arrays, crossed once. JS inflates node
  * objects lazily from this — no eager full-tree allocation. The fast path.
  */
 export interface JsSoa {
@@ -40,7 +40,7 @@ export interface JsSoa {
   strBlob: Uint8Array
   strMeta: Uint32Array
 }
-/** Parse a document into the SoA flat buffer (the fast runtime path). */
+/** Parse a document into the `SoA` flat buffer (the fast runtime path). */
 export declare function parseBuffer(html: string): JsSoa
 /**
  * Parse an HTML fragment (innerHTML-style). `context` is the context element:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miaskiewicz/turbo-dom",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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 --features rust-runtime",
+    "test:rust": "cargo test -p turbo-dom",
     "test:all": "npm run build && npm run test:rust && npm test",
     "prepare": "git config core.hooksPath .githooks || true",
     "conformance": "node harness/conformance.mjs",
@@ -91,10 +91,11 @@
     "test:jest": "jest -c test-jest/jest.config.cjs",
     "bench:query": "node bench/query.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",
+    "conformance:rtdom": "cargo test -p turbo-dom rtdom::conformance::rtdom_html5lib_conformance_full_document -- --nocapture",
+    "build:rtdom": "cargo build -p turbo-dom --release",
+    "profile:churn": "cargo build --profile profiling --example churn_profile -p turbo-dom && echo 'built — CPU-profile with:  ./target/profiling/examples/churn_profile & sample $! 20 -file target/churn.sample.txt'",
     "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"
+    "bench:compare:all": "RTDOM_JSON=\"$(cargo test -p turbo-dom --release 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/core.rs

@@ -2,13 +2,13 @@
 //! Both front-ends (napi-rs native, wasm-bindgen fallback) wrap this unchanged.
 //!
 //! Plan note: this is the "full marshaling" version — a *complete* tree.
-//! The SoA flat-buffer (architecture Layer 1) is a later optimization, gated on
+//! The `SoA` flat-buffer (architecture Layer 1) is a later optimization, gated on
 //! marshaling proving to be the actual cost. Do not SoA-ify here yet.
 
 use html5ever::driver::ParseOpts;
 use html5ever::tendril::TendrilSink;
 use html5ever::tree_builder::TreeBuilderOpts;
-use html5ever::{parse_document, parse_fragment, local_name, namespace_url, ns, LocalName, QualName};
+use html5ever::{parse_document, parse_fragment, ns, LocalName, QualName};
 use markup5ever_rcdom::{Handle, NodeData, RcDom};
 
 /// DOM nodeType constants (subset html5ever can emit).
@@ -59,6 +59,7 @@ fn opts() -> ParseOpts {
 }
 
 /// Parse a full HTML document. Always yields a Document root (nodeType 9).
+#[must_use]
 pub fn parse_html_document(html: &str) -> Node {
     let dom = parse_document(RcDom::default(), opts())
         .from_utf8()
@@ -186,7 +187,7 @@ impl SoaBuilder {
             }
             NodeData::ProcessingInstruction { target, contents } => {
                 self.soa.node_type[idx] = PROCESSING_INSTRUCTION_NODE;
-                let combined = format!("{} {}", target, contents);
+                let combined = format!("{target} {contents}");
                 self.soa.text_id[idx] = self.push_string(&combined);
             }
             NodeData::Element { name, attrs, template_contents, .. } => {
@@ -202,7 +203,7 @@ impl SoaBuilder {
                         self.soa.attr_name_id.push(nid);
                         let vid = self.intern_attr_value(&attr.value);
                         self.soa.attr_value_id.push(vid);
-                        let pfx = attr.name.prefix.as_ref().map(|p| p.to_string()).unwrap_or_default();
+                        let pfx = attr.name.prefix.as_ref().map(std::string::ToString::to_string).unwrap_or_default();
                         let pid = self.intern_attr_prefix(&pfx);
                         self.soa.attr_prefix_id.push(pid);
                     }
@@ -253,7 +254,8 @@ impl SoaBuilder {
     }
 }
 
-/// Parse a full document into the SoA flat buffer.
+/// Parse a full document into the `SoA` flat buffer.
+#[must_use]
 pub fn parse_html_soa(html: &str) -> Soa {
     let dom = parse_document(RcDom::default(), opts())
         .from_utf8()
@@ -263,10 +265,10 @@ pub fn parse_html_soa(html: &str) -> Soa {
         soa: Soa::default(),
         // pre-reserve typical intern-table sizes so the build loop doesn't rehash:
         // tag/attr-name sets are small + bounded; values vary more.
-        tag_map: rustc_hash::FxHashMap::with_capacity_and_hasher(32, Default::default()),
-        attr_name_map: rustc_hash::FxHashMap::with_capacity_and_hasher(64, Default::default()),
-        attr_prefix_map: rustc_hash::FxHashMap::with_capacity_and_hasher(8, Default::default()),
-        attr_value_map: rustc_hash::FxHashMap::with_capacity_and_hasher(128, Default::default()),
+        tag_map: rustc_hash::FxHashMap::with_capacity_and_hasher(32, rustc_hash::FxBuildHasher),
+        attr_name_map: rustc_hash::FxHashMap::with_capacity_and_hasher(64, rustc_hash::FxBuildHasher),
+        attr_prefix_map: rustc_hash::FxHashMap::with_capacity_and_hasher(8, rustc_hash::FxBuildHasher),
+        attr_value_map: rustc_hash::FxHashMap::with_capacity_and_hasher(128, rustc_hash::FxBuildHasher),
     };
     b.alloc(&dom.document, -1);
     b.soa
@@ -274,6 +276,7 @@ pub fn parse_html_soa(html: &str) -> Soa {
 
 /// Parse a document and return only the node count — no `core::Node` tree, no
 /// marshaling. Isolates raw html5ever parse cost from tree-build + boundary cost.
+#[must_use]
 pub fn parse_html_document_count(html: &str) -> u32 {
     let dom = parse_document(RcDom::default(), opts())
         .from_utf8()
@@ -288,12 +291,14 @@ fn count(handle: &Handle) -> u32 {
 
 /// Parse an HTML fragment (e.g. an `innerHTML=` set) in `<body>` context.
 /// Returns a synthetic Document-fragment-ish root whose children are the parsed nodes.
+#[must_use]
 pub fn parse_html_fragment(html: &str) -> Node {
     parse_html_fragment_in(html, "", "body")
 }
 
 /// Parse a fragment given an html5lib-style context string:
 /// "" / "body" / "td" (html ns) or "svg path" / "math ms" (foreign ns).
+#[must_use]
 pub fn parse_html_fragment_context(html: &str, context: &str) -> Node {
     let (ns, local) = match context {
         "" => ("", "body"),
@@ -309,6 +314,7 @@ pub fn parse_html_fragment_context(html: &str, context: &str) -> Node {
 
 /// Parse a fragment in an explicit context element.
 /// `context_ns`: "" (html), "svg", or "math"; `context_local`: the element local name.
+#[must_use]
 pub fn parse_html_fragment_in(html: &str, context_ns: &str, context_local: &str) -> Node {
     let ns = match context_ns {
         "svg" => ns!(svg),
@@ -383,7 +389,7 @@ fn walk(handle: &Handle) -> Node {
                 .map(|attr| Attr {
                     name: attr.name.local.to_string(),
                     value: attr.value.to_string(),
-                    prefix: attr.name.prefix.as_ref().map(|p| p.to_string()).unwrap_or_default(),
+                    prefix: attr.name.prefix.as_ref().map(std::string::ToString::to_string).unwrap_or_default(),
                 })
                 .collect();
             // html5lib short namespace form: "" (html), "svg", "math".
@@ -502,6 +508,6 @@ mod tests {
         let frag = parse_html_fragment_context("<rect/>", "svg path");
         // context is svg path, so a bare <rect> parses in the SVG namespace
         let rect = first(&frag, &|n| n.name == "rect");
-        assert!(rect.map(|n| n.namespace == "svg").unwrap_or(false));
+        assert!(rect.is_some_and(|n| n.namespace == "svg"));
     }
 }

package/src/lib.rs

@@ -1,16 +1,12 @@
 //! turbo-dom parser — Layer 1.
 //! One Rust core (`core`), two interchangeable front-ends selected by feature:
 //!   * `napi-bind`  → native Node addon (default, fast path)
-//!   * `wasm-bind`  → wasm32 fallback (StackBlitz / WebContainers / locked-down CI)
+//!   * `wasm-bind`  → wasm32 fallback (`StackBlitz` / `WebContainers` / locked-down CI)
+//!
 //! Both expose the same logical API: parse(html) -> tree, parseFragment(html) -> tree.
 
 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;
@@ -18,7 +14,10 @@ pub mod spike;
 // ---------------------------------------------------------------------------
 // napi-rs front-end (native addon)
 // ---------------------------------------------------------------------------
-#[cfg(feature = "napi-bind")]
+// `not(test)`: this is cdylib boundary glue, exercised by the JS integration
+// tests, never Rust-unit-tested. napi's export registration doesn't emit under
+// `cfg(test)`, so building it for `cargo test` only yields dead-code warnings.
+#[cfg(all(feature = "napi-bind", not(test)))]
 mod napi_front {
     use crate::core;
     use napi_derive::napi;
@@ -76,9 +75,9 @@ mod napi_front {
         core::parse_html_document_count(&html)
     }
 
-    use napi::bindgen_prelude::{Int32Array, Uint16Array, Uint32Array, Uint8Array};
+    use napi::bindgen_prelude::{Uint32Array, Uint8Array};
 
-    /// SoA flat buffer: structure as typed arrays, crossed once. JS inflates node
+    /// `SoA` flat buffer: structure as typed arrays, crossed once. JS inflates node
     /// objects lazily from this — no eager full-tree allocation. The fast path.
     // All numeric columns packed into ONE little-endian byte blob (1 ArrayBuffer +
     // zero-copy views in JS, vs 13 separate addon buffers + finalizers per parse).
@@ -106,14 +105,14 @@ mod napi_front {
             let n = s.node_type.len();
             let m = s.attr_name_id.len();
             let mut buf: Vec<u8> = Vec::with_capacity(36 * n + 12 * m);
-            for col in [&s.tag_id] { for v in col.iter() { buf.extend_from_slice(&v.to_le_bytes()); } }
+            for col in [&s.tag_id] { for v in col { buf.extend_from_slice(&v.to_le_bytes()); } }
             for col in [&s.parent, &s.first_child, &s.next_sib, &s.text_id, &s.pub_id, &s.sys_id, &s.attr_start] {
-                for v in col.iter() { buf.extend_from_slice(&v.to_le_bytes()); }
+                for v in col { buf.extend_from_slice(&v.to_le_bytes()); }
             }
             for col in [&s.attr_name_id, &s.attr_value_id, &s.attr_prefix_id] {
-                for v in col.iter() { buf.extend_from_slice(&v.to_le_bytes()); }
+                for v in col { buf.extend_from_slice(&v.to_le_bytes()); }
             }
-            for v in s.attr_count.iter() { buf.extend_from_slice(&v.to_le_bytes()); }
+            for v in &s.attr_count { buf.extend_from_slice(&v.to_le_bytes()); }
             buf.extend_from_slice(&s.node_type);
             buf.extend_from_slice(&s.ns);
             // pack all five string tables into one byte blob + meta (5 counts, then
@@ -121,12 +120,12 @@ mod napi_front {
             let tables: [&Vec<String>; 5] =
                 [&s.tag_names, &s.attr_names, &s.attr_prefixes, &s.attr_values, &s.strings];
             let total_strs: usize = tables.iter().map(|t| t.len()).sum();
-            let total_bytes: usize = tables.iter().flat_map(|t| t.iter()).map(|x| x.len()).sum();
+            let total_bytes: usize = tables.iter().flat_map(|t| t.iter()).map(std::string::String::len).sum();
             let mut str_blob: Vec<u8> = Vec::with_capacity(total_bytes);
             let mut str_meta: Vec<u32> = Vec::with_capacity(5 + total_strs);
             for t in &tables { str_meta.push(t.len() as u32); }
             for t in &tables {
-                for x in t.iter() {
+                for x in *t {
                     str_meta.push(x.len() as u32);
                     str_blob.extend_from_slice(x.as_bytes());
                 }
@@ -141,7 +140,7 @@ mod napi_front {
         }
     }
 
-    /// Parse a document into the SoA flat buffer (the fast runtime path).
+    /// Parse a document into the `SoA` flat buffer (the fast runtime path).
     #[napi(js_name = "parseBuffer")]
     pub fn parse_buffer(html: String) -> JsSoa {
         core::parse_html_soa(&html).into()

package/src/runtime/cascade.mjs

@@ -91,8 +91,14 @@ function parseStylesheet(css, startOrder, rules) {
   const n = css.length;
   while (i < n) {
     let j = i;
-    while (j < n && css[j] !== '{' && css[j] !== '}') j++;
+    while (j < n && css[j] !== '{' && css[j] !== '}' && css[j] !== ';') j++;
     if (j >= n) break;
+    // A `;` outside any block terminates a statement at-rule (@import/@charset/
+    // @namespace) or a stray semicolon — it has no block, so skip just the statement
+    // and keep scanning. Without this the statement is glued onto the following
+    // selector and (starting with `@`) drags that whole rule into the skip. Mirrors
+    // rtdom cascade::parse_stylesheet.
+    if (css[j] === ';') { order++; i = j + 1; continue; }
     if (css[j] === '}') { i = j + 1; continue; }
     const sel = css.slice(i, j).trim();
     let depth = 1, k = j + 1;

package/src/runtime/dom.mjs

@@ -298,6 +298,17 @@ Object.assign(Node.prototype, {
   DOCUMENT_POSITION_CONTAINED_BY: 16, DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC: 32,
 });
 
+// Viable next sibling (DOM spec): the first following sibling that is NOT itself
+// one of the nodes being inserted. Anchoring after()/replaceWith() on the raw
+// nextSibling breaks when that sibling is also an argument (e.g. a.after(b, c)
+// where b already follows a) — insertBefore(b, b) then throws NotFoundError.
+// Mirrors rtdom Tree::viable_next_sibling.
+function viableNextSibling(node, nodes) {
+  let s = node.nextSibling;
+  while (s && nodes.includes(s)) s = s.nextSibling;
+  return s;
+}
+
 // ----------------------------------------------------- CharacterData ----
 class CharacterData extends Node {
   constructor(ownerDocument, data) { super(ownerDocument); this._data = data ?? ''; }
@@ -314,8 +325,8 @@ class CharacterData extends Node {
   deleteData(offset, count) { this.data = this._data.slice(0, offset) + this._data.slice(offset + count); }
   replaceData(offset, count, s) { this.data = this._data.slice(0, offset) + s + this._data.slice(offset + count); }
   before(...nodes) { const p = this.parentNode; if (p) for (const n of nodes) p.insertBefore(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n, this); }
-  after(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; for (const n of nodes) p.insertBefore(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n, ref); }
-  replaceWith(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; this.remove(); for (const n of nodes) p.insertBefore(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n, ref); }
+  after(...nodes) { const p = this.parentNode; if (!p) return; const ref = viableNextSibling(this, nodes); for (const n of nodes) p.insertBefore(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n, ref); }
+  replaceWith(...nodes) { const p = this.parentNode; if (!p) return; const ref = viableNextSibling(this, nodes); for (const n of nodes) if (n !== this) p.insertBefore(typeof n === 'string' ? this.ownerDocument.createTextNode(n) : n, ref); this.remove(); }
 }
 
 export class Text extends CharacterData {
@@ -693,8 +704,8 @@ export class Element extends Node {
   append(...nodes) { for (const n of nodes) this.appendChild(toNode(this.ownerDocument, n)); }
   prepend(...nodes) { const first = this.firstChild; for (const n of nodes) this.insertBefore(toNode(this.ownerDocument, n), first); }
   before(...nodes) { const p = this.parentNode; if (!p) return; for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), this); }
-  after(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), ref); }
-  replaceWith(...nodes) { const p = this.parentNode; if (!p) return; const ref = this.nextSibling; this.remove(); for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), ref); }
+  after(...nodes) { const p = this.parentNode; if (!p) return; const ref = viableNextSibling(this, nodes); for (const n of nodes) p.insertBefore(toNode(this.ownerDocument, n), ref); }
+  replaceWith(...nodes) { const p = this.parentNode; if (!p) return; const ref = viableNextSibling(this, nodes); for (const n of nodes) if (n !== this) p.insertBefore(toNode(this.ownerDocument, n), ref); this.remove(); }
   replaceChildren(...nodes) { this.__kids = []; this.__touch(); for (const n of nodes) this.appendChild(toNode(this.ownerDocument, n)); }
 
   // ---- queries ----

package/src/runtime/selectors.mjs

@@ -1,86 +1,225 @@
 // Compact CSS selector engine. Correctness-first, right-to-left matching.
 // Supports: type, *, #id, .class, [attr], [attr op val] (= ^= $= *= ~= |=),
 // combinators (descendant ' ', child '>', adjacent '+', sibling '~'),
-// comma selector lists, and :not(), :first-child, :last-child, :only-child,
-// :empty, :root. Enough for React Testing Library usage.
+// comma selector lists, :not()/:is()/:where() (selector lists), the relational
+// :has(), :first-child, :last-child, :only-child, :empty, :root. Enough for React
+// Testing Library usage.
 
-const ATTR_RE = /\[\s*([^\]=~^$*|\s]+)\s*(?:([~^$*|]?=)\s*(?:"([^"]*)"|'([^']*)'|([^\]]*?))\s*)?\]/y;
+// ── Tokenizer + recursive-descent parser ─────────────────────────────────────
+// The selector string is first turned into a flat token stream by `tokenize`,
+// which centrally handles the two things an ad-hoc character scanner keeps
+// getting wrong: quoted strings and balanced `[]`/`()` runs. The grammar layer
+// (`parseCompound`/`parseComplexTokens`) then only ever sees whole tokens, so it
+// never has to re-discover where an attribute or pseudo argument ends. The AST it
+// emits — a Complex `{ first, rest: [{ combinator, compound }] }` (mirroring the
+// Rust port's "parse, don't validate" shape: no parallel head/tail arrays that can
+// desync) with the same compound/attr/pseudo object shapes — is exactly what the
+// matcher below consumes.
+//
+// Token kinds:
+//   { k:'comma' }                       a top-level ','
+//   { k:'ws' }                          a run of whitespace (a candidate descendant combinator)
+//   { k:'comb', v:'>'|'+'|'~' }         an explicit combinator
+//   { k:'star' }                        '*'
+//   { k:'type', v }                     a type/element name
+//   { k:'id',    v }                    '#name'
+//   { k:'class', v }                    '.name'
+//   { k:'attr', name, match }           '[ … ]' (match = { op:'present' } | { op, value })
+//   { k:'pseudo', name, arg }           ':name' / ':name( arg )' (arg null ⇒ no parens)
 
-function parseCompound(src, i) {
-  const compound = { tag: null, id: null, classes: [], attrs: [], pseudos: [] };
-  let matchedAny = false;
-  while (i < src.length) {
+const NAME_CHAR = /[a-zA-Z0-9_-]/;
+function isTypeStart(c) {
+  return (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z');
+}
+function isWs(c) {
+  return c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+}
+
+// Split a raw `[ … ]` interior into `{ name, match }`, where `match` FOLDS the
+// operator and value so an illegal state is unrepresentable: a presence test is
+// `{ op: 'present' }` (NO `value` key at all), and a valued test is
+// `{ op, value }` with op ∈ equals|includes|dash|prefix|suffix|substr (mirroring
+// the Rust `AttrMatch` variants). The first '=' (if any) splits name from value;
+// an operator char (~ | ^ $ *) immediately before it selects the operator. A
+// surrounding matching quote pair on the value is stripped. No '=' ⇒ presence.
+const ATTR_OP = { '~': 'includes', '|': 'dash', '^': 'prefix', $: 'suffix', '*': 'substr' };
+function parseAttr(inner) {
+  const eq = inner.indexOf('=');
+  if (eq === -1) return { name: inner.trim(), match: { op: 'present' } };
+  let name = inner.slice(0, eq);
+  let op = 'equals';
+  const last = name[name.length - 1];
+  if (ATTR_OP[last] !== undefined) {
+    op = ATTR_OP[last];
+    name = name.slice(0, -1);
+  }
+  let value = inner.slice(eq + 1).trim();
+  if (
+    value.length >= 2 &&
+    ((value[0] === '"' && value[value.length - 1] === '"') ||
+      (value[0] === "'" && value[value.length - 1] === "'"))
+  ) {
+    value = value.slice(1, -1);
+  }
+  return { name: name.trim(), match: { op, value } };
+}
+
+// Scan from `start` (just past an opening `open`) to its matching `close`,
+// honoring quotes and nesting. Returns { inner, end } where `end` is the index of
+// the closing delimiter (or src.length if unterminated). One shared scanner for
+// both `[...]` and `(...)`, mirroring the Rust `scan_balanced` — a `]`/`)` inside a
+// quoted value never terminates early, and `:not(:nth-child(2))` nests correctly.
+function scanBalanced(src, start, open, close) {
+  const n = src.length;
+  let depth = 1, i = start, quote = null;
+  for (; i < n; i++) {
+    const d = src[i];
+    if (quote) { if (d === quote) quote = null; continue; }
+    if (d === '"' || d === "'") quote = d;
+    else if (d === open) depth++;
+    else if (d === close) { depth--; if (depth === 0) break; }
+  }
+  return { inner: src.slice(start, i), end: i };
+}
+
+function tokenize(src) {
+  const tokens = [];
+  const n = src.length;
+  let i = 0;
+  while (i < n) {
     const c = src[i];
-    if (c === '*') { compound.tag = '*'; i++; matchedAny = true; continue; }
-    if (/[a-zA-Z]/.test(c) && compound.tag === null && compound.id === null && !compound.classes.length && !compound.attrs.length && !compound.pseudos.length) {
-      let j = i;
-      while (j < src.length && /[a-zA-Z0-9_-]/.test(src[j])) j++;
-      compound.tag = src.slice(i, j).toLowerCase();
-      i = j; matchedAny = true; continue;
+    if (isWs(c)) {
+      i++;
+      while (i < n && isWs(src[i])) i++;
+      tokens.push({ k: 'ws' });
+      continue;
     }
+    if (c === ',') { tokens.push({ k: 'comma' }); i++; continue; }
+    if (c === '>' || c === '+' || c === '~') { tokens.push({ k: 'comb', v: c }); i++; continue; }
+    if (c === '*') { tokens.push({ k: 'star' }); i++; continue; }
     if (c === '#') {
       let j = i + 1;
-      while (j < src.length && /[a-zA-Z0-9_-]/.test(src[j])) j++;
-      compound.id = src.slice(i + 1, j); i = j; matchedAny = true; continue;
+      while (j < n && NAME_CHAR.test(src[j])) j++;
+      tokens.push({ k: 'id', v: src.slice(i + 1, j) });
+      i = j; continue;
     }
     if (c === '.') {
       let j = i + 1;
-      while (j < src.length && /[a-zA-Z0-9_-]/.test(src[j])) j++;
-      compound.classes.push(src.slice(i + 1, j)); i = j; matchedAny = true; continue;
+      while (j < n && NAME_CHAR.test(src[j])) j++;
+      tokens.push({ k: 'class', v: src.slice(i + 1, j) });
+      i = j; continue;
     }
     if (c === '[') {
-      ATTR_RE.lastIndex = i;
-      const m = ATTR_RE.exec(src);
-      if (!m) throw new SyntaxError(`bad attribute selector at ${src.slice(i)}`);
-      compound.attrs.push({ name: m[1], op: m[2] || null, value: m[3] ?? m[4] ?? m[5] ?? null });
-      i = ATTR_RE.lastIndex; matchedAny = true; continue;
+      const { inner, end } = scanBalanced(src, i + 1, '[', ']');
+      if (end >= n) throw new SyntaxError(`unterminated attribute selector: ${src.slice(i)}`);
+      tokens.push({ k: 'attr', ...parseAttr(inner) });
+      i = end + 1; continue;
     }
     if (c === ':') {
       let j = i + 1;
-      while (j < src.length && /[a-zA-Z-]/.test(src[j])) j++;
+      while (j < n && (isTypeStart(src[j]) || src[j] === '-')) j++;
       const name = src.slice(i + 1, j);
       let arg = null;
-      if (src[j] === '(') {
-        let depth = 1, k = j + 1;
-        while (k < src.length && depth > 0) { if (src[k] === '(') depth++; else if (src[k] === ')') depth--; k++; }
-        arg = src.slice(j + 1, k - 1);
-        j = k;
+      if (j < n && src[j] === '(') {
+        // balanced parens (quotes respected) so a nested ':not(:nth-child(2))'
+        // or a quoted ')' survives intact for the recursive parse.
+        const { inner, end } = scanBalanced(src, j + 1, '(', ')');
+        arg = inner;
+        i = end < n ? end + 1 : n;
+      } else {
+        i = j;
       }
-      compound.pseudos.push({ name, arg });
-      i = j; matchedAny = true; continue;
+      tokens.push({ k: 'pseudo', name, arg });
+      continue;
+    }
+    if (isTypeStart(c)) {
+      let j = i + 1;
+      while (j < n && NAME_CHAR.test(src[j])) j++;
+      tokens.push({ k: 'type', v: src.slice(i, j) });
+      i = j; continue;
     }
-    break;
+    throw new SyntaxError(`unexpected '${c}' in selector`);
   }
-  if (!matchedAny) throw new SyntaxError(`empty compound at ${src.slice(i)}`);
-  return { compound, i };
+  return tokens;
 }
 
-// Parse one complex selector into compounds[] + combinators[] (combinator[k]
-// relates compounds[k] to compounds[k+1], left to right).
-function parseComplex(src) {
-  let i = 0;
-  const compounds = [];
-  const combinators = [];
-  src = src.trim();
-  while (i < src.length) {
-    while (src[i] === ' ') i++;
-    const r = parseCompound(src, i);
-    compounds.push(r.compound);
-    i = r.i;
-    // read optional combinator
-    let sawSpace = false;
-    while (src[i] === ' ') { sawSpace = true; i++; }
-    if (i >= src.length) break;
-    if (src[i] === '>' || src[i] === '+' || src[i] === '~') {
-      combinators.push(src[i]); i++;
-      while (src[i] === ' ') i++;
-    } else if (sawSpace) {
-      combinators.push(' ');
+// compound := [type|'*'] ( '#'id | '.'class | '['attr']' | ':'pseudo )*  — but
+// lenient: parts may appear in any order/multiplicity, and a redundant type/'*'
+// after the first is dropped (so `div[id=x]y` ≡ `div[id=x]`). Consuming an empty
+// compound (no parts at all, e.g. a leading combinator) is a SyntaxError.
+function parseCompound(tokens, pos, end) {
+  const compound = { tag: null, id: null, classes: [], attrs: [], pseudos: [] };
+  let matched = false;
+  while (pos < end) {
+    const t = tokens[pos];
+    if (t.k === 'star') { if (compound.tag === null) compound.tag = '*'; }
+    else if (t.k === 'type') { if (compound.tag === null) compound.tag = t.v.toLowerCase(); }
+    else if (t.k === 'id') { compound.id = t.v; }
+    else if (t.k === 'class') { compound.classes.push(t.v); }
+    else if (t.k === 'attr') { compound.attrs.push({ name: t.name, match: t.match }); }
+    else if (t.k === 'pseudo') { compound.pseudos.push({ name: t.name, arg: t.arg }); }
+    else break; // ws / comb / comma ends the compound
+    pos++; matched = true;
+  }
+  if (!matched) throw new SyntaxError(`empty compound at token ${pos}`);
+  return { compound, pos };
+}
+
+// Parse tokens[lo..hi) (one complex selector — commas already split out) into a
+// Complex `{ first, rest: [{ combinator, compound }] }`: `first` is the leftmost
+// compound and each `rest[i].combinator` connects `rest[i].compound` to the
+// compound on its LEFT (`rest[i-1].compound`, or `first` when i==0). Building the
+// pair only AFTER a trailing compound is read keeps combinator/compound in lockstep
+// — there is no way to represent a stray combinator (the parallel-array desync the
+// old shape allowed). An empty segment (no compound at all) returns `null`.
+function parseComplexTokens(tokens, lo, hi) {
+  // trim leading / trailing ws tokens (mirrors the old `src.trim()`)
+  let start = lo, end = hi;
+  while (start < end && tokens[start].k === 'ws') start++;
+  while (end > start && tokens[end - 1].k === 'ws') end--;
+  if (start >= end) return null; // empty segment ⇒ no compound (filtered by parseSelectorList)
+  let r = parseCompound(tokens, start, end);
+  const first = r.compound;
+  const rest = [];
+  let pos = r.pos;
+  while (pos < end) {
+    while (pos < end && tokens[pos].k === 'ws') pos++; // a ws run here ⇒ candidate descendant
+    const t = tokens[pos];
+    let combinator;
+    if (t.k === 'comb') {
+      combinator = t.v;
+      pos++;
+      while (pos < end && tokens[pos].k === 'ws') pos++;
+      if (pos >= end) break; // dangling combinator (`a >`) — drop it (no trailing compound to pair)
     } else {
-      throw new SyntaxError(`unexpected '${src[i]}' in selector`);
+      // the only token that can follow a compound after a ws run is the next
+      // compound's first part ⇒ a descendant combinator
+      combinator = ' ';
+    }
+    r = parseCompound(tokens, pos, end);
+    rest.push({ combinator, compound: r.compound });
+    pos = r.pos;
+  }
+  return { first, rest };
+}
+
+// Parse one complex selector STRING (no top-level comma). Exposed via `_internal`.
+// Returns the Complex `{ first, rest }` or `null` (empty selector).
+function parseComplex(src) {
+  const tokens = tokenize(src);
+  return parseComplexTokens(tokens, 0, tokens.length);
+}
+
+// Yield each top-level (comma-separated) segment of `tokens` as a `[lo, hi)` range.
+// One shared loop for both the selector-list and the relative-selector-list parses.
+function* splitTopLevelSegments(tokens) {
+  let start = 0;
+  for (let i = 0; i <= tokens.length; i++) {
+    if (i === tokens.length || tokens[i].k === 'comma') {
+      yield [start, i];
+      start = i + 1;
     }
   }
-  return { compounds, combinators };
 }
 
 // parsed-selector cache: querySelector(All)/matches re-run the same selector
@@ -90,38 +229,57 @@ const __selectorCache = new Map();
 export function parseSelectorList(selector) {
   const hit = __selectorCache.get(selector);
   if (hit !== undefined) return hit;
-  const parsed = splitTopLevel(selector, ',').map((s) => parseComplex(s.trim()));
+  const tokens = tokenize(selector);
+  const parsed = [];
+  for (const [lo, hi] of splitTopLevelSegments(tokens)) {
+    const cx = parseComplexTokens(tokens, lo, hi);
+    if (cx !== null) parsed.push(cx); // a Complex is always non-empty (empties dropped)
+  }
   if (__selectorCache.size > 10000) __selectorCache.clear();
   __selectorCache.set(selector, parsed);
   return parsed;
 }
 
-function splitTopLevel(s, sep) {
+// :has() relative-selector-list parse + cache. Each top-level comma segment may
+// begin with a combinator ('>'/'+'/'~'); absent ⇒ descendant. The remainder is a
+// normal complex (reused parseComplex). Segments yielding no complex are dropped.
+// Mirrors the Rust parse_relative_selector_list.
+const __relativeCache = new Map();
+function parseRelativeSelectorList(arg) {
+  const src = arg || '';
+  const hit = __relativeCache.get(src);
+  if (hit !== undefined) return hit;
+  const tokens = tokenize(src);
   const out = [];
-  let depth = 0, last = 0;
-  for (let i = 0; i < s.length; i++) {
-    const c = s[i];
-    if (c === '(' || c === '[') depth++;
-    else if (c === ')' || c === ']') depth--;
-    else if (c === sep && depth === 0) { out.push(s.slice(last, i)); last = i + 1; }
+  for (let [lo, hi] of splitTopLevelSegments(tokens)) {
+    while (lo < hi && tokens[lo].k === 'ws') lo++; // skip leading ws of the segment
+    let combinator = ' ';
+    if (lo < hi && tokens[lo].k === 'comb') {
+      combinator = tokens[lo].v;
+      lo++;
+    }
+    const complex = parseComplexTokens(tokens, lo, hi);
+    if (complex !== null) out.push({ combinator, complex });
   }
-  out.push(s.slice(last));
+  if (__relativeCache.size > 10000) __relativeCache.clear();
+  __relativeCache.set(src, out);
   return out;
 }
 
 function matchAttr(el, a) {
   const raw = el.getAttribute(a.name);   // single lookup (null = absent)
   if (raw === null) return false;
-  if (a.op === null) return true;
+  const m = a.match;
+  if (m.op === 'present') return true;   // presence carries no value
   const v = raw;
-  const t = a.value ?? '';
-  switch (a.op) {
-    case '=': return v === t;
-    case '^=': return t !== '' && v.startsWith(t);
-    case '$=': return t !== '' && v.endsWith(t);
-    case '*=': return t !== '' && v.includes(t);
-    case '~=': return v.split(/\s+/).includes(t);
-    case '|=': return v === t || v.startsWith(t + '-');
+  const t = m.value;
+  switch (m.op) {
+    case 'equals': return v === t;
+    case 'prefix': return t !== '' && v.startsWith(t);
+    case 'suffix': return t !== '' && v.endsWith(t);
+    case 'substr': return t !== '' && v.includes(t);
+    case 'includes': return v.split(/\s+/).includes(t);
+    case 'dash': return v === t || v.startsWith(t + '-');
     default: return false;
   }
 }
@@ -130,6 +288,16 @@ function matchPseudo(el, p) {
   switch (p.name) {
     case 'not':
       return !parseSelectorList(p.arg).some((cx) => matchComplex(el, cx));
+    // :is()/:where() — element matches if ANY complex in the list matches it
+    // (anchored at the element). :where matches identically to :is; the
+    // specificity difference is a cascade concern, out of scope here.
+    case 'is':
+    case 'where':
+      return parseSelectorList(p.arg).some((cx) => matchComplex(el, cx));
+    // :has() — relational. SOME relative selector finds a matching element
+    // reachable from `el` per its leading combinator, scoped to `el`.
+    case 'has':
+      return parseRelativeSelectorList(p.arg).some((rel) => hasMatch(el, rel));
     case 'first-child':
       return previousElement(el) === null;
     case 'last-child':
@@ -247,46 +415,114 @@ function matchCompound(el, compound) {
   return true;
 }
 
+// The k-th compound of a Complex, indexed left-to-right (0 = `first`, the leftmost).
+function compoundAt(cx, k) {
+  return k === 0 ? cx.first : cx.rest[k - 1].compound;
+}
+
 // Match a parsed complex selector against `el` (the rightmost compound applies to el).
+// The rightmost compound sits at index `cx.rest.length`.
 function matchComplex(el, cx) {
-  const { compounds, combinators } = cx;
-  const last = compounds.length - 1;
-  if (!matchCompound(el, compounds[last])) return false;
+  return matchChain(el, cx, cx.rest.length, null);
+}
 
-  // walk leftward
-  let idx = last - 1;
-  let current = el;
-  while (idx >= 0) {
-    const comb = combinators[idx]; // relation between compounds[idx] and compounds[idx+1]
-    const target = compounds[idx];
-    if (comb === ' ') {
-      let anc = current.parentNode;
-      let matched = false;
-      while (anc && anc.nodeType === 1) {
-        if (matchCompound(anc, target)) { current = anc; matched = true; break; }
-        anc = anc.parentNode;
-      }
-      if (!matched) return false;
-    } else if (comb === '>') {
-      const parent = current.parentNode;
-      if (!parent || parent.nodeType !== 1 || !matchCompound(parent, target)) return false;
-      current = parent;
-    } else if (comb === '+') {
-      const prev = previousElement(current);
-      if (!prev || !matchCompound(prev, target)) return false;
-      current = prev;
-    } else if (comb === '~') {
-      let prev = previousElement(current);
-      let matched = false;
-      while (prev) {
-        if (matchCompound(prev, target)) { current = prev; matched = true; break; }
-        prev = previousElement(prev);
-      }
-      if (!matched) return false;
+// Match compounds 0..=k of `cx` ending at `el`, recursing leftward. Descendant (' ')
+// and general-sibling ('~') combinators try EVERY candidate ancestor/sibling and
+// backtrack — committing to the nearest one (the old greedy walk) wrongly rejected
+// chains like `.a > .b .c` where a farther `.b` is the one that is a child of `.a`.
+// `cx.rest[k-1].combinator` is the relation between compounds k-1 and k.
+// `scope` supports `:has()`: when set to `{ comb, node }`, the LEFTMOST compound must,
+// in addition to matching, relate to the scope element `node` by `comb` (so a relative
+// selector's head is anchored to the `:has()` subject). `null` (what matchComplex and
+// plain matching pass) means the leftmost compound stands alone — one sentinel.
+function matchChain(el, cx, k, scope = null) {
+  if (!matchCompound(el, compoundAt(cx, k))) return false;
+  if (k === 0) return scope === null ? true : relatesToScope(el, scope.comb, scope.node);
+  const comb = cx.rest[k - 1].combinator; // relation between compounds k-1 and k
+  if (comb === '>') {
+    const p = el.parentNode;
+    return !!p && p.nodeType === 1 && matchChain(p, cx, k - 1, scope);
+  }
+  if (comb === '+') {
+    const prev = previousElement(el);
+    return !!prev && matchChain(prev, cx, k - 1, scope);
+  }
+  if (comb === ' ') {
+    let anc = el.parentNode;
+    while (anc && anc.nodeType === 1) {
+      if (matchChain(anc, cx, k - 1, scope)) return true;
+      anc = anc.parentNode;
     }
-    idx--;
+    return false;
   }
-  return true;
+  // '~' general sibling
+  let prev = previousElement(el);
+  while (prev) {
+    if (matchChain(prev, cx, k - 1, scope)) return true;
+    prev = previousElement(prev);
+  }
+  return false;
+}
+
+// Does `node` stand in relation `comb` to the `:has()` scope element `el`? This anchors
+// the leftmost compound of a relative selector: `> .a` means the `.a` head is a direct
+// child of the subject, `.a .b` means the `.a` head is a descendant, etc. The leading
+// combinator constrains the HEAD compound — NOT the whole complex (the bug in anchoring
+// the entire relative complex at a child/sibling candidate).
+function relatesToScope(node, comb, el) {
+  if (comb === '>') return node.parentNode === el;
+  if (comb === '+') return previousElement(node) === el;
+  if (comb === '~') { let p = previousElement(node); while (p) { if (p === el) return true; p = previousElement(p); } return false; }
+  // ' ' descendant: `el` is a proper ancestor of `node`
+  let a = node.parentNode;
+  while (a) { if (a === el) return true; a = a.parentNode; }
+  return false;
+}
+
+// :has() existence search. The relative complex must match some target element (its
+// rightmost compound) reachable from the subject `el`, with its HEAD compound related
+// to `el` by the leading combinator (enforced at k===0 via `relatesToScope`). Candidate
+// targets: descendants of `el` for `>`/descendant heads (the head, and thus the whole
+// match, lives in `el`'s subtree); a following-sibling subtree for `+`/`~` heads.
+// Mirrors the Rust has_match.
+function hasMatch(el, rel) {
+  const { combinator, complex } = rel;
+  const scope = { comb: combinator, node: el };
+  const test = (x) => matchChain(x, complex, complex.rest.length, scope);
+  if (combinator === '+') {
+    const sib = nextElement(el);
+    return !!sib && someSelfOrDescendant(sib, test);
+  }
+  if (combinator === '~') {
+    let sib = nextElement(el);
+    while (sib) {
+      if (someSelfOrDescendant(sib, test)) return true;
+      sib = nextElement(sib);
+    }
+    return false;
+  }
+  // '>' and descendant leading combinator: the head (hence every match) is within
+  // `el`'s subtree, so any descendant can be the target endpoint.
+  return someDescendant(el, test);
+}
+
+// Visit every descendant element of `node` (document order); short-circuit on the
+// first that satisfies `pred`. No filtered-copy allocation per level.
+function someDescendant(node, pred) {
+  const kids = rawChildren(node);
+  for (let i = 0; i < kids.length; i++) {
+    const c = kids[i];
+    if (c.nodeType !== 1) continue;
+    if (pred(c)) return true;
+    if (someDescendant(c, pred)) return true;
+  }
+  return false;
+}
+
+// `node` itself (if an element) or any of its descendants satisfies `pred`.
+function someSelfOrDescendant(node, pred) {
+  if (node.nodeType === 1 && pred(node)) return true;
+  return someDescendant(node, pred);
 }
 
 export function matchesSelector(el, selector) {

package/src/spike.rs

@@ -6,10 +6,10 @@
 //! 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;
+//!   * 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
+//!   * NAIVE — per-node string returns (`tag_name/get_attr` as String) to show the
 //!     cost the mitigations avoid.
 
 use crate::core::{self, Soa};
@@ -23,7 +23,7 @@ struct Doc {
 }
 
 thread_local! {
-    static DOCS: RefCell<Vec<Doc>> = RefCell::new(Vec::new());
+    static DOCS: RefCell<Vec<Doc>> = const { RefCell::new(Vec::new()) };
 }
 
 fn with_doc<R>(doc: u32, f: impl FnOnce(&Doc) -> R) -> R {
@@ -32,6 +32,7 @@ fn with_doc<R>(doc: u32, f: impl FnOnce(&Doc) -> R) -> R {
 
 /// Parse + register a document. Returns the doc handle. ONE crossing per parse.
 #[wasm_bindgen]
+#[must_use]
 pub fn create(html: &str) -> u32 {
     let soa = core::parse_html_soa(html);
     DOCS.with(|d| {
@@ -59,33 +60,40 @@ fn join_blob(v: &[String]) -> String {
 }
 
 #[wasm_bindgen]
+#[must_use]
 pub fn tag_names_blob(doc: u32) -> String {
     with_doc(doc, |d| join_blob(&d.soa.tag_names))
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn attr_names_blob(doc: u32) -> String {
     with_doc(doc, |d| join_blob(&d.soa.attr_names))
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn attr_values_blob(doc: u32) -> String {
     with_doc(doc, |d| join_blob(&d.soa.attr_values))
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn strings_blob(doc: u32) -> String {
     with_doc(doc, |d| join_blob(&d.soa.strings))
 }
 
 #[wasm_bindgen]
+#[must_use]
 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]
+#[must_use]
 pub fn node_type(doc: u32, h: u32) -> u8 {
     with_doc(doc, |d| d.soa.node_type[h as usize])
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn tag_id(doc: u32, h: u32) -> i32 {
     with_doc(doc, |d| {
         let i = h as usize;
@@ -93,32 +101,38 @@ pub fn tag_id(doc: u32, h: u32) -> i32 {
     })
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn parent(doc: u32, h: u32) -> i32 {
     with_doc(doc, |d| d.soa.parent[h as usize])
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn first_child(doc: u32, h: u32) -> i32 {
     with_doc(doc, |d| d.soa.first_child[h as usize])
 }
 #[wasm_bindgen]
+#[must_use]
 pub fn next_sib(doc: u32, h: u32) -> i32 {
     with_doc(doc, |d| d.soa.next_sib[h as usize])
 }
 #[wasm_bindgen]
+#[must_use]
 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).
+/// 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]
+#[must_use]
 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]
+#[must_use]
 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())
@@ -127,6 +141,7 @@ pub fn get_attr_str(doc: u32, h: u32, name: &str) -> Option<String> {
 
 /// NAIVE tagName: per-call String marshal.
 #[wasm_bindgen]
+#[must_use]
 pub fn tag_name_str(doc: u32, h: u32) -> Option<String> {
     with_doc(doc, |d| {
         let i = h as usize;
@@ -155,10 +170,11 @@ fn attr_value_id(soa: &Soa, i: usize, name: &str) -> Option<u32> {
 }
 
 /// 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
+/// [`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]
+#[must_use]
 pub fn node_record(doc: u32, h: u32) -> Vec<i32> {
     with_doc(doc, |d| {
         let i = h as usize;
@@ -183,6 +199,7 @@ pub fn node_record(doc: u32, h: u32) -> Vec<i32> {
 /// 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]
+#[must_use]
 pub fn dispatch_walk(doc: u32, h: u32) -> u32 {
     with_doc(doc, |d| {
         let mut len = 1u32; // target
@@ -286,6 +303,7 @@ fn matches(soa: &Soa, i: usize, c: &Compound) -> bool {
 }
 
 #[wasm_bindgen]
+#[must_use]
 pub fn qsa(doc: u32, selector: &str) -> Vec<u32> {
     with_doc(doc, |d| {
         let c = parse_compound(selector);