@miaskiewicz/turbo-dom 0.1.31 → 0.1.33

package/README.md

@@ -14,9 +14,11 @@ npm install -D @miaskiewicz/turbo-dom
 
 - ✅ **More compatible than happy-dom** — 99.72% on html5lib-tests vs happy-dom's 37%.
   Runs React Testing Library, `user-event`, downshift, Radix UI, and Headless UI unmodified.
-- ⚡ **Faster than both** — ~120× jsdom / ~40× happy-dom on a realistic suite (parse-memoized repeated shells), 18–37× faster HTML parsing, and it beats happy-dom on repeated queries while staying 99.7% spec-correct.
-- 🎯 **Honest, not lying** — no fake layout numbers; `getBoundingClientRect()` is zeros and
-  `getComputedStyle` reflects only what you set. Geometry tests belong in a real browser.
+- ⚡ **Faster than both** — ~130× jsdom / ~45× happy-dom on a realistic suite (parse-memoized repeated shells), ~8–35× faster HTML parsing on real pages, and ~2.2× happy-dom on repeated queries while staying 99.7% spec-correct.
+- 🎯 **Honest, not lying** — no fake layout numbers; `getBoundingClientRect()` is zeros.
+  `getComputedStyle` runs a **partial cascade**: it resolves real injected `<style>` rules
+  (emotion/MUI `.css-HASH{…}`) + inline styles with proper specificity/source order — but only
+  ever returns values a real rule set, never invented layout. Geometry tests belong in a real browser.
 
 ## Quick start
 
@@ -90,7 +92,9 @@ parseFragment('<rect/>', 'svg path');              // fragment in a context elem
 | html5lib-tests conformance | **99.72%** | 37.35% | 97.03% |
 | @testing-library/dom + user-event | ✅ | ✅ | ✅ |
 | React + Radix / Headless UI / downshift | ✅ | partial | ✅ |
-| Real layout / `getComputedStyle` cascade | ❌ (honest stub) | partial | partial |
+| Real layout | ❌ (honest stub) | partial | partial |
+| `getComputedStyle` cascade | partial (real `<style>` + inline) | partial | partial |
+| Shadow DOM (attach, slots, event retargeting, scoped/`:host` CSS) | ✅ | ✅ | ✅ |
 
 turbo-dom inherits Servo's tree constructor, so the "messy input" cases hand-rolled parsers
 get wrong — adoption-agency reparenting (`<a><p></a></p>`), table foster-parenting, optional
@@ -105,16 +109,17 @@ the suite row (ms/file, lower = faster):
 
 | benchmark | turbo-dom | happy-dom | jsdom |
 |---|---:|---:|---:|
-| **realistic suite**, 200 files (ms/file) | **0.022** | 1.12 | 3.47 |
-| **per-file setup** (ops/s) | **~500k** | 396 | 144 |
-| **parse 56 KB SSR** (ops/s) | **478** | 43 | 26 |
-| **parse 20 KB real page** (ops/s) | **2,800** | 600 | 290 |
-| repeated query throughput (iters/s) | **994k** | 692k | 3k |
+| **realistic suite**, 200 files (ms/file) | **~0.025** | 1.13 | 3.40 |
+| **cold per-file construct + query** (ops/s) | **~200k** | 579 | 266 |
+| **parse 56 KB SSR** (ops/s) | **510** | 48 | 66 |
+| **parse 20 KB real page** (ops/s) | **3,628** | 161 | 105 |
+| repeated query throughput (iters/s) | **~1.5M** | 680k | 3.3k |
 | html5lib conformance | **99.72%** | 37.35% | 97.03% |
 
 On a realistic suite — 200 files of construct + queries + events — turbo-dom is
-**~40× happy-dom and ~120× jsdom**, edges happy-dom on repeated queries, and parses
-**18–37×** faster, all at 99.7% conformance.
+**~45× happy-dom and ~130× jsdom**, runs repeated queries **~2.2× happy-dom**
+(~460× jsdom), and parses real pages/SSR documents **~8–35×** faster, all at 99.7%
+conformance.
 
 The per-file setup number is so high because the parser **memoizes the read-only
 SoA buffer by HTML string**: a suite calls the env setup with the same document
@@ -123,7 +128,7 @@ go to per-Document overlays) is reused. The first parse of a given shell pays fu
 cost (the parse rows above); every reuse is near-free.
 
 **turbo-dom wins across the board on what test suites actually do**: per-file
-construction (~40× happy-dom, ~120× jsdom on a repeated-shell suite), parsing,
+construction (~45× happy-dom, ~130× jsdom on a repeated-shell suite), parsing,
 spec-correctness (99.7% vs 37%), **and** repeated queries.
 
 How the query speed holds up against happy-dom (whose whole design trades correctness
@@ -151,10 +156,24 @@ JS (chatty, fine-grained) but pays only for what a test touches. Full design not
 ## Limitations (by design)
 
 - **No layout.** `getBoundingClientRect()` returns zeros; `getClientRects()` is empty.
-- **`getComputedStyle` is inline-only** — it reflects the `style` attribute and explicitly
-  set properties, never an invented cascade. Style/geometry assertions belong in a real
-  browser (Playwright/WebDriver).
+- **`getComputedStyle` is a partial cascade** — it resolves REAL injected `<style>` rules
+  (emotion/MUI `.css-HASH{…}`) plus inline `style`, applying specificity and source order
+  (inline wins). It expands common shorthands to longhands (`margin`/`padding`/`border`/single-token
+  `background`), serializes bare `0` as `0px` for length props, and normalizes `font-family`
+  comma spacing to match browser output. Out of scope (returns `''`): `@media`/`@supports`/
+  `@keyframes`, `:hover`/state pseudo-classes, pseudo-elements, full inheritance, CSS custom
+  properties, and length-unit conversion (`em`/`rem`→`px`). Only ever returns values from a
+  matched rule or inline declaration — never an invented one. Style/geometry assertions belong
+  in a real browser (Playwright/WebDriver).
 - Canvas, `<select>` rendering, and similar visual APIs are honest no-op stubs.
+- **Shadow DOM** is supported and pay-for-what-you-use — every event/query/cascade hot path
+  is unchanged until the first `attachShadow` flips a per-document flag. Covered: `attachShadow`
+  (open/closed), encapsulated `querySelector`/`getElementById`, `getRootNode({composed})`,
+  full event propagation with `target`/`relatedTarget` retargeting and `composed` boundary
+  crossing, `<slot>` `assignedNodes`/`assignedElements`/`assignedSlot`, scoped `getComputedStyle`
+  with `:host`/`:host(...)`/`::slotted(...)` and inheritance across the boundary, and declarative
+  `<template shadowrootmode>` promotion. Out of scope (honest): flattened-tree layout, `slotchange`
+  events, and the cascade caveats above (`@media`/state/pseudo-elements) inside shadow trees.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miaskiewicz/turbo-dom",
-  "version": "0.1.31",
+  "version": "0.1.33",
   "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",
@@ -56,8 +56,10 @@
     "build:wasm": "cargo build --release --no-default-features --features wasm-bind --target wasm32-unknown-unknown",
     "build:wasm:pkg": "wasm-pack build --target nodejs --out-dir pkg --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=87 --test-coverage-branches=87 'test/*.mjs'",
     "test:rust": "cargo test --lib",
     "test:all": "npm run build && npm run test:rust && npm test",
+    "prepare": "git config core.hooksPath .githooks || true",
     "conformance": "node harness/conformance.mjs",
     "conformance:delta": "node harness/delta.mjs",
     "bench": "node bench/parse.mjs",

package/src/runtime/cascade.mjs

@@ -106,35 +106,77 @@ function parseStylesheet(css, startOrder, rules) {
   return order;
 }
 
-function buildIndex(document) {
-  const styles = document.getElementsByTagName('style');
+function buildIndex(scope) {
+  // scope is always a Document or ShadowRoot — both expose getElementsByTagName.
+  const styles = scope.getElementsByTagName('style');
   const rules = [];
   let order = 0;
   for (let i = 0; i < styles.length; i++) order = parseStylesheet(styles[i].textContent || '', order, rules);
   return rules;
 }
 
-function getIndex(doc, v) {
-  const cached = doc.__styleIndex;
+// `scope` is the Document (light DOM) or a ShadowRoot (encapsulated). Both hold
+// their own __styleIndex; the version key is the Document version (shadow style
+// mutations bump it too), so either cache auto-invalidates on any mutation.
+function getIndex(scope, v) {
+  const cached = scope.__styleIndex;
   if (cached && cached.v === v) return cached.rules;
-  const rules = buildIndex(doc);
-  doc.__styleIndex = { v, rules };
+  const rules = buildIndex(scope);
+  scope.__styleIndex = { v, rules };
   return rules;
 }
 
-function resolve(el, rules) {
-  const out = new Map();
-  const matched = [];
+const HOST_RE = /^:host(?:\((.*)\))?$/;        // :host or :host(sel)
+const SLOTTED_RE = /::slotted\(([^)]*)\)/;      // ::slotted(sel)
+
+// Collect rules from one index that apply to `el` under a given `kind`:
+//  'normal'  — el matched against the selector (skips :host/::slotted rules)
+//  'host'    — el is a shadow host; match the inner of a :host[(sel)] rule
+//  'slotted' — el is a slotted light node; match the inner of ::slotted(sel)
+function collectMatched(el, rules, kind, into) {
   for (let i = 0; i < rules.length; i++) {
     const r = rules[i];
-    try { if (matchesSelector(el, r.selector)) matched.push(r); } catch { /* unsupported selector → skip */ }
+    const sel = r.selector;
+    const hostM = HOST_RE.exec(sel);
+    const slotM = SLOTTED_RE.exec(sel);
+    if (kind === 'normal') {
+      if (hostM || slotM) continue; // shadow-only selectors never match plain elements
+      try { if (matchesSelector(el, sel)) into.push(r); } catch { /* unsupported → skip */ }
+    } else if (kind === 'host') {
+      if (!hostM) continue;
+      const inner = hostM[1];
+      if (inner === undefined) into.push(r);
+      else try { if (matchesSelector(el, inner.trim())) into.push(r); } catch { /* skip */ }
+    } else { // slotted
+      if (!slotM) continue;
+      const inner = (slotM[1] || '*').trim() || '*';
+      try { if (matchesSelector(el, inner)) into.push(r); } catch { /* skip */ }
+    }
   }
+}
+
+// Inheritable properties we propagate across the shadow boundary into shadow
+// content (curated; matches the common inherited set). Honest partial: only
+// these inherit, and only INTO shadow trees — light DOM stays inheritance-free.
+const INHERITED = new Set([
+  'color', 'cursor', 'direction', 'font', 'font-family', 'font-size', 'font-style',
+  'font-variant', 'font-weight', 'letter-spacing', 'line-height', 'list-style',
+  'list-style-type', 'text-align', 'text-indent', 'text-transform', 'visibility',
+  'white-space', 'word-spacing', 'quotes',
+]);
+
+// Flattened-tree parent for inheritance: the DOM parent, hopping shadow-root→host
+// at the boundary; null if there is no element parent.
+function flattenedParent(el) {
+  const p = el.parentNode;
+  if (!p) return null;
+  if (p.__isShadowRoot) return p.host;
+  return p.nodeType === 1 ? p : null;
+}
+
+function applyMatched(matched, out) {
   matched.sort((x, y) => x.spec - y.spec || x.order - y.order);
   for (const r of matched) for (const [k, val] of r.decls) out.set(k, val);
-  // inline style wins over stylesheet rules
-  const inline = el.getAttribute && el.getAttribute('style');
-  if (inline) parseDecls(inline, out);
-  return out;
 }
 
 function lookup(map, prop) {
@@ -172,15 +214,56 @@ function makeProxy(map, v) {
 // getComputedStyle(el): resolves cascade, memoized per element on the current
 // Document.__version (any style/DOM mutation bumps it → cache auto-invalidates).
 export function makeGetComputedStyle() {
-  return (el) => {
+  const gcs = (el) => {
     if (!el) return makeProxy(new Map(), -1);
     const doc = el.ownerDocument;
     const v = doc ? (doc.__version || 0) : 0;
     const cached = el.__computedStyle;
     if (cached && cached.__v === v) return cached;
-    const map = doc ? resolve(el, getIndex(doc, v)) : new Map();
+
+    const map = new Map();
+    if (!doc) { const p = makeProxy(map, v); el.__computedStyle = p; return p; }
+
+    // Encapsulation: an element inside a shadow tree resolves against that
+    // shadow root's own <style> rules, not the document's (and vice-versa).
+    // Gated on __hasShadow so the no-shadow path keeps resolving against doc.
+    let scope = doc, inShadow = false;
+    if (doc.__hasShadow) {
+      const root = el.getRootNode && el.getRootNode();
+      if (root && root.__isShadowRoot) { scope = root; inShadow = true; }
+    }
+
+    const matched = [];
+    collectMatched(el, getIndex(scope, v), 'normal', matched);
+    if (doc.__hasShadow) {
+      // shadow host: overlay :host rules from its OWN shadow root's stylesheet
+      if (el.__shadow) collectMatched(el, getIndex(el.__shadow, v), 'host', matched);
+      // slotted light node: overlay ::slotted rules from the slot's shadow root
+      const slot = el.assignedSlot;
+      if (slot) { const sr = slot.getRootNode(); if (sr.__isShadowRoot) collectMatched(el, getIndex(sr, v), 'slotted', matched); }
+    }
+    applyMatched(matched, map);
+
+    // inline style wins over stylesheet rules
+    const inline = el.getAttribute && el.getAttribute('style');
+    if (inline) parseDecls(inline, map);
+
+    // Inheritance INTO shadow content only: an element inside a shadow tree
+    // inherits unset inheritable props from its flattened parent (crossing the
+    // host boundary). Light-DOM elements stay inheritance-free (honest).
+    if (inShadow) {
+      const parent = flattenedParent(el);
+      if (parent) {
+        const ps = gcs(parent); // recursive, memoized, terminates at the light-DOM host
+        for (const prop of INHERITED) {
+          if (!map.has(prop)) { const pv = ps.getPropertyValue(prop); if (pv) map.set(prop, pv); }
+        }
+      }
+    }
+
     const proxy = makeProxy(map, v);
     el.__computedStyle = proxy;
     return proxy;
   };
+  return gcs;
 }

package/src/runtime/collections.mjs

@@ -2,7 +2,11 @@
 // reflect mutations immediately — the exact place happy-dom bleeds liveness bugs.
 
 function makeLive(getArray, extra = {}) {
-  const target = function () {};
+  // Plain-object target: it has no non-configurable own keys, so ownKeys can
+  // report indices + length without tripping the proxy invariant (a function
+  // target carries a non-configurable `prototype`, which made Object.keys(coll)
+  // throw and `typeof coll` wrongly 'function' — HTMLCollection is an object).
+  const target = {};
   return new Proxy(target, {
     get(_t, key) {
       if (typeof key === 'string') {

package/src/runtime/dom.mjs

@@ -181,11 +181,24 @@ export class Node extends EventTarget {
 
   get isConnected() {
     let n = this;
-    while (n.parentNode) n = n.parentNode;
-    return n.nodeType === DOCUMENT_NODE;
+    for (;;) {
+      while (n.parentNode) n = n.parentNode;
+      // a node inside a shadow tree is connected iff its host is connected
+      if (n.__isShadowRoot) { n = n.host; continue; }
+      return n.nodeType === DOCUMENT_NODE;
+    }
   }
-  getRootNode() {
+  getRootNode(options) {
     let n = this;
+    if (options && options.composed) {
+      // climb through shadow boundaries to the topmost root (document/detached)
+      for (;;) {
+        while (n.parentNode) n = n.parentNode;
+        if (n.__isShadowRoot) { n = n.host; continue; }
+        return n;
+      }
+    }
+    // non-composed: stop at the enclosing shadow root if there is one
     while (n.parentNode) n = n.parentNode;
     return n;
   }
@@ -245,6 +258,10 @@ export class Node extends EventTarget {
   // insertBefore/removeChild.
   __touch() { const d = this.ownerDocument; if (d) d.__version = (d.__version || 0) + 1; }
 
+  // Element/Document/Fragment nodeValue is null per spec (CharacterData overrides).
+  get nodeValue() { return null; }
+  set nodeValue(_v) { /* no-op for non-CharacterData nodes, per spec */ }
+
   // window/document path for event propagation past the document
   get __owner() { return null; }
 }
@@ -454,7 +471,11 @@ export class Element extends Node {
       return list.length && !this.multiple ? list[0].value : '';
     }
     if (t === 'option') return this.hasAttribute('value') ? this.getAttribute('value') : this.textContent;
-    if (t === 'input' || t === 'textarea') return this.__value !== undefined ? this.__value : (this.getAttribute('value') ?? '');
+    // textarea has no value attribute — its raw value defaults to the child text
+    // content (the WHATWG "default value") until edited; input falls back to the
+    // value attribute (defaultValue).
+    if (t === 'textarea') return this.__value !== undefined ? this.__value : this.textContent;
+    if (t === 'input') return this.__value !== undefined ? this.__value : (this.getAttribute('value') ?? '');
     return undefined;
   }
   set value(x) {
@@ -786,18 +807,47 @@ export class Element extends Node {
   getContext(type) { return this.localName === 'canvas' ? (this.__ctx ||= makeCanvasStub()) : null; }
   toDataURL() { return 'data:,'; }
 
-  // shadow DOM (open by default; a detached fragment with a host back-reference)
+  // shadow DOM. Flipping doc.__hasShadow arms the gated slow paths (event
+  // retargeting in events.mjs, scoped cascade in cascade.mjs); before the first
+  // attachShadow every benchmarked path runs exactly as it did with no shadow code.
   attachShadow(init = {}) {
-    const root = new DocumentFragment(this.ownerDocument);
-    root.host = this;
-    root.mode = init.mode || 'open';
-    root.querySelector = (s) => qsel(root, s);
-    root.querySelectorAll = (s) => qselAll(root, s);
+    if (this.__shadow) throw new Error('NotSupportedError: shadow root already attached');
+    const root = new ShadowRoot(this, init.mode || 'open', init.delegatesFocus);
     this.__shadow = root;
     if (root.mode === 'open') this.shadowRoot = root;
+    const doc = this.ownerDocument;
+    if (doc) doc.__hasShadow = true;
     return root;
   }
 
+  // ---- <slot> projection (all on-demand; never touched by parse/query/events) ----
+  // A light-DOM child's assigned slot: the matching <slot> in its parent host's
+  // shadow tree, or null when the parent isn't a shadow host / no slot matches.
+  get assignedSlot() {
+    const host = this.parentNode;
+    if (!host || !host.__shadow) return null;
+    return findSlot(host.__shadow, this.getAttribute('slot') || '');
+  }
+  // <slot>.assignedNodes(): the host's light children routed to this slot by name
+  // (default slot ← unnamed children + text). With {flatten:true} an empty slot
+  // falls back to its own children (the slot's default content).
+  assignedNodes(options) {
+    if (this.localName !== 'slot') return [];
+    const root = this.getRootNode();
+    if (!root.__isShadowRoot) return [];
+    const slotName = this.getAttribute('name') || '';
+    const out = [];
+    for (const c of root.host.__children()) {
+      if (c.nodeType === ELEMENT_NODE) { if ((c.getAttribute('slot') || '') === slotName) out.push(c); }
+      else if (c.nodeType === TEXT_NODE && slotName === '') out.push(c); // text routes only to the default slot
+    }
+    if (out.length === 0 && options && options.flatten) {
+      return this.__children().filter((n) => n.nodeType === ELEMENT_NODE || n.nodeType === TEXT_NODE);
+    }
+    return out;
+  }
+  assignedElements(options) { return this.assignedNodes(options).filter((n) => n.nodeType === ELEMENT_NODE); }
+
   // forms
   get form() { return this.closest ? this.closest('form') : null; }
   get elements() {
@@ -837,9 +887,73 @@ export class DocumentFragment extends Node {
   cloneNode(deep = false) { const f = new DocumentFragment(this.ownerDocument); if (deep) for (const c of this.__children()) f.appendChild(c.cloneNode(true)); return f; }
 }
 
+// A real shadow root: a detached document-fragment subtree with a back-reference
+// to its host element. `__isShadowRoot` is the duck-typed flag events.mjs and
+// Node.getRootNode/isConnected branch on (no import cycle). Encapsulation is free
+// — the host's __children() never includes this subtree, so querySelector /
+// getElementsBy* / matching never reach in.
+export class ShadowRoot extends DocumentFragment {
+  constructor(host, mode = 'open', delegatesFocus = false) {
+    super(host.ownerDocument);
+    this.host = host;
+    this.mode = mode;
+    this.delegatesFocus = !!delegatesFocus;
+    this.__isShadowRoot = true;
+  }
+  get nodeName() { return '#document-fragment'; }
+  get innerHTML() { return serializeInner(this); }
+  set innerHTML(html) {
+    const frag = native.parseFragment(String(html), ''); // empty context → body
+    this.__kids = [];
+    this.__touch();
+    for (const rawChild of frag.children) {
+      if (rawChild.nodeType === DOCUMENT_FRAGMENT_NODE && rawChild.name === 'content') continue;
+      const child = this.ownerDocument.__inflateNested(rawChild);
+      child.parentNode = this;
+      this.__kids.push(child);
+    }
+  }
+  getElementById(id) {
+    let found = null;
+    const visit = (node) => {
+      const kids = node.__children();
+      for (let i = 0; i < kids.length; i++) {
+        const c = kids[i];
+        if (c.nodeType !== ELEMENT_NODE) continue;
+        if (c.getAttribute('id') === id) { found = c; return; }
+        visit(c);
+        if (found) return;
+      }
+    };
+    visit(this);
+    return found;
+  }
+  getElementsByTagName(tag) { const self = this; return liveHTMLCollection(() => collectByTag(self, tag.toLowerCase())); }
+  getElementsByClassName(cls) { const self = this; const classes = splitClasses(cls); return liveHTMLCollection(() => collectByClass(self, classes)); }
+  // the topmost root of any node within is this shadow root, never the document
+  get activeElement() { return null; }
+}
+
 // ------------------------------------------------------------ helpers ----
 function toNode(doc, n) { return typeof n === 'string' ? doc.createTextNode(n) : n; }
 
+// First <slot> within a shadow tree whose name matches (default slot: name '').
+function findSlot(shadowRoot, name) {
+  let found = null;
+  const visit = (node) => {
+    const kids = node.__children();
+    for (let i = 0; i < kids.length; i++) {
+      const c = kids[i];
+      if (c.nodeType !== ELEMENT_NODE) continue;
+      if (c.localName === 'slot' && (c.getAttribute('name') || '') === name) { found = c; return; }
+      visit(c);
+      if (found) return;
+    }
+  };
+  visit(shadowRoot);
+  return found;
+}
+
 function collectByTag(root, tag) {
   const out = [];
   const all = tag === '*';
@@ -889,7 +1003,16 @@ function zeroRect() {
   return { x: 0, y: 0, top: 0, left: 0, right: 0, bottom: 0, width: 0, height: 0, toJSON() { return this; } };
 }
 
-// Range — functional enough for selection bookkeeping (user-event), zero geometry.
+// child index of `node` within its parent (per spec: the node's "index")
+function nodeIndex(node) {
+  const p = node.parentNode;
+  if (!p) return 0;
+  return p.__children().indexOf(node);
+}
+
+// Range — functional DOM Range. Tree-mutating ops (extract/clone/delete/insert/
+// surround) implement the common case (a single container with element/text
+// children, offsets as child indices). Zero geometry (no layout).
 class Range {
   constructor(doc) {
     this.__doc = doc;
@@ -898,42 +1021,106 @@ class Range {
   }
   setStart(node, offset) { this.startContainer = node; this.startOffset = offset; this.__sync(); }
   setEnd(node, offset) { this.endContainer = node; this.endOffset = offset; this.__sync(); }
-  setStartBefore(node) { this.setStart(node.parentNode, 0); }
-  setStartAfter(node) { this.setStart(node.parentNode, 0); }
-  setEndBefore(node) { this.setEnd(node.parentNode, 0); }
-  setEndAfter(node) { this.setEnd(node.parentNode, 0); }
-  selectNode(node) { this.startContainer = this.endContainer = node; this.__sync(); }
-  selectNodeContents(node) { this.startContainer = this.endContainer = node; this.startOffset = 0; this.endOffset = node.childNodes ? node.childNodes.length : 0; this.__sync(); }
+  setStartBefore(node) { this.setStart(node.parentNode, nodeIndex(node)); }
+  setStartAfter(node) { this.setStart(node.parentNode, nodeIndex(node) + 1); }
+  setEndBefore(node) { this.setEnd(node.parentNode, nodeIndex(node)); }
+  setEndAfter(node) { this.setEnd(node.parentNode, nodeIndex(node) + 1); }
+  // selectNode: container is the node's parent, offsets bracket the node.
+  selectNode(node) { const p = node.parentNode, i = nodeIndex(node); this.startContainer = this.endContainer = p; this.startOffset = i; this.endOffset = i + 1; this.__sync(); }
+  selectNodeContents(node) { this.startContainer = this.endContainer = node; this.startOffset = 0; this.endOffset = node.nodeType === TEXT_NODE || node.nodeType === COMMENT_NODE ? node.length : node.__children().length; this.__sync(); }
   collapse(toStart) { if (toStart) { this.endContainer = this.startContainer; this.endOffset = this.startOffset; } else { this.startContainer = this.endContainer; this.startOffset = this.endOffset; } this.collapsed = true; }
   __sync() { this.collapsed = this.startContainer === this.endContainer && this.startOffset === this.endOffset; }
-  get commonAncestorContainer() { return this.startContainer; }
-  cloneRange() { const r = new Range(this.__doc); Object.assign(r, this); return r; }
-  cloneContents() { return this.__doc.createDocumentFragment(); }
-  deleteContents() {}
-  insertNode(node) { if (this.startContainer && this.startContainer.insertBefore) this.startContainer.insertBefore(node, this.startContainer.childNodes[this.startOffset] ?? null); }
-  surroundContents(node) { this.insertNode(node); }
+  // common ancestor: walk up from start until it contains end (per spec).
+  get commonAncestorContainer() {
+    let container = this.startContainer;
+    while (container && !(container === this.endContainer || (container.contains && container.contains(this.endContainer)))) {
+      container = container.parentNode;
+    }
+    return container || this.startContainer;
+  }
+  cloneRange() { const r = new Range(this.__doc); r.startContainer = this.startContainer; r.endContainer = this.endContainer; r.startOffset = this.startOffset; r.endOffset = this.endOffset; r.collapsed = this.collapsed; return r; }
+  // The common single-container case: start === end container, offsets are child
+  // indices (element children) or string offsets (a text/comment container).
+  __sameContainerKids() { return this.startContainer === this.endContainer; }
+  cloneContents() {
+    const frag = this.__doc.createDocumentFragment();
+    const c = this.startContainer;
+    if (this.__sameContainerKids() && c && c.nodeType !== TEXT_NODE && c.nodeType !== COMMENT_NODE && c.__children) {
+      const kids = c.__children();
+      for (let i = this.startOffset; i < this.endOffset && i < kids.length; i++) frag.appendChild(kids[i].cloneNode(true));
+    }
+    return frag;
+  }
+  extractContents() {
+    const frag = this.__doc.createDocumentFragment();
+    const c = this.startContainer;
+    if (this.__sameContainerKids() && c && c.nodeType !== TEXT_NODE && c.nodeType !== COMMENT_NODE && c.__children) {
+      const kids = c.__children().slice(this.startOffset, this.endOffset);
+      for (const k of kids) frag.appendChild(k); // moves out of the tree
+    }
+    this.collapse(true);
+    return frag;
+  }
+  deleteContents() {
+    const c = this.startContainer;
+    if (this.__sameContainerKids() && c && c.nodeType !== TEXT_NODE && c.nodeType !== COMMENT_NODE && c.__children) {
+      const kids = c.__children().slice(this.startOffset, this.endOffset);
+      for (const k of kids) c.removeChild(k);
+    }
+    this.collapse(true);
+  }
+  insertNode(node) { if (this.startContainer && this.startContainer.insertBefore) this.startContainer.insertBefore(node, this.startContainer.__children ? (this.startContainer.__children()[this.startOffset] ?? null) : null); }
+  surroundContents(node) {
+    const frag = this.extractContents();
+    this.insertNode(node);
+    node.appendChild(frag);
+  }
+  // textual content of the range: the common single-container case.
+  toString() {
+    const c = this.startContainer;
+    if (c && (c.nodeType === TEXT_NODE || c.nodeType === COMMENT_NODE)) {
+      if (this.__sameContainerKids()) return c.data.slice(this.startOffset, this.endOffset);
+      return c.data.slice(this.startOffset);
+    }
+    if (this.__sameContainerKids() && c && c.__children) {
+      let s = '';
+      const kids = c.__children();
+      for (let i = this.startOffset; i < this.endOffset && i < kids.length; i++) s += kids[i].textContent;
+      return s;
+    }
+    return '';
+  }
   getBoundingClientRect() { return zeroRect(); }
   getClientRects() { return []; }
   detach() {}
 }
 
-function makeSelection() {
+function makeSelection(doc) {
   let ranges = [];
-  return {
+  const sel = {
     get rangeCount() { return ranges.length; },
-    get isCollapsed() { return ranges.every((r) => r.collapsed); },
+    get isCollapsed() { return ranges.length === 0 || ranges.every((r) => r.collapsed); },
     get anchorNode() { return ranges[0] ? ranges[0].startContainer : null; },
     get focusNode() { return ranges[0] ? ranges[0].endContainer : null; },
     get anchorOffset() { return ranges[0] ? ranges[0].startOffset : 0; },
     get focusOffset() { return ranges[0] ? ranges[0].endOffset : 0; },
-    get type() { return ranges.length ? 'Range' : 'None'; },
+    get type() { return ranges.length === 0 ? 'None' : ranges[0].collapsed ? 'Caret' : 'Range'; },
     addRange(r) { ranges.push(r); },
     removeAllRanges() { ranges = []; },
     removeRange(r) { ranges = ranges.filter((x) => x !== r); },
     getRangeAt(i) { return ranges[i]; },
-    collapse() {}, extend() {}, selectAllChildren() {}, setBaseAndExtent() {}, empty() { ranges = []; },
-    toString() { return ''; },
+    // collapse(node, offset): a single collapsed range at the point.
+    collapse(node, offset = 0) { if (node == null) { ranges = []; return; } const r = new Range(doc); r.setStart(node, offset); r.setEnd(node, offset); ranges = [r]; },
+    collapseToStart() { if (ranges[0]) ranges[0].collapse(true); },
+    collapseToEnd() { if (ranges[0]) ranges[0].collapse(false); },
+    // extend(node, offset): move the focus (range end) to the new point.
+    extend(node, offset = 0) { if (!ranges[0]) ranges = [new Range(doc)]; ranges[0].setEnd(node, offset); },
+    selectAllChildren(node) { const r = new Range(doc); r.selectNodeContents(node); ranges = [r]; },
+    setBaseAndExtent(anchorNode, anchorOffset, focusNode, focusOffset) { const r = new Range(doc); r.setStart(anchorNode, anchorOffset); r.setEnd(focusNode, focusOffset); ranges = [r]; },
+    empty() { ranges = []; },
+    toString() { return ranges[0] ? ranges[0].toString() : ''; },
   };
+  return sel;
 }
 
 // TreeWalker / NodeIterator over the DOM (doubles for both — common subset).
@@ -1299,8 +1486,7 @@ export class Document extends Node {
   }
   createRange() { return new Range(this); }
   createAttribute(name) { return { name, value: '', ownerElement: null }; }
-  createComment(data) { return new Comment(this, String(data)); }
-  getSelection() { if (!this.__selection) this.__selection = makeSelection(); return this.__selection; }
+  getSelection() { if (!this.__selection) this.__selection = makeSelection(this); return this.__selection; }
   importNode(node, deep) { return node.cloneNode(deep); }
   adoptNode(node) { if (node.parentNode) node.parentNode.removeChild(node); adoptInto(node, this); return node; }
 

package/src/runtime/events.mjs

@@ -112,6 +112,33 @@ function normalizeOptions(options) {
   return { capture: !!options.capture, once: !!options.once, passive: !!options.passive };
 }
 
+// ---- shadow DOM event support ----
+// Duck-typed (ShadowRoot sets `__isShadowRoot`/`host`) to avoid a dom.mjs import
+// cycle. NONE of this runs unless the document has a shadow root attached — the
+// hot dispatch path branches on `doc.__hasShadow` and skips it entirely.
+function treeRootOf(node) { let n = node; while (n.parentNode) n = n.parentNode; return n; }
+// Is `b` a shadow-including inclusive descendant of tree-root `root`? Walks up
+// through parentNode, hopping shadow-root→host at each boundary.
+function shadowInclusiveDescendant(b, root) {
+  let n = b;
+  while (n) {
+    if (n === root) return true;
+    n = n.parentNode || (n.__isShadowRoot ? n.host : null); // hop boundary, else stop
+  }
+  return false;
+}
+// WHATWG retarget(A, B): the version of A visible to a listener whose
+// currentTarget is B. If A lives in a shadow tree that B is outside of, A is
+// reported as that tree's host (and recursively, for nested shadows). The loop
+// always terminates — each hop climbs one shadow boundary toward the document.
+function retarget(a, b) {
+  for (;;) {
+    const r = treeRootOf(a);
+    if (!r.__isShadowRoot || shadowInclusiveDescendant(b, r)) return a;
+    a = r.host;
+  }
+}
+
 export class EventTarget {
   constructor() {
     // type -> array of { callback, capture, once, passive }. Lazily created on
@@ -153,7 +180,8 @@ export class EventTarget {
 
   dispatchEvent(event) {
     if (!(event instanceof Event)) throw new TypeError('dispatchEvent requires an Event');
-    event.target = this;
+    const target = this;
+    event.target = target;
 
     // Single ancestor walk: build the path AND note whether any node on it has a
     // listener for this type. React fires thousands of events with zero matching
@@ -161,11 +189,32 @@ export class EventTarget {
     const type = event.type;
     const path = [];
     let hasListener = false;
-    let node = this;
-    while (node) {
-      path.push(node);
-      if (!hasListener) { const l = node.__listeners && node.__listeners.get(type); if (l && l.length) hasListener = true; }
-      node = node.parentNode || node.__owner || null;
+    // Pay-for-what-you-use: the shadow-aware walk + per-invoke retargeting only
+    // runs when a shadow root exists in this document. Otherwise the original
+    // flat walk runs byte-for-byte (one boolean read, predicted false).
+    const doc = this.ownerDocument || this;
+    const useShadow = !!(doc && doc.__hasShadow);
+    if (!useShadow) {
+      let node = this;
+      while (node) {
+        path.push(node);
+        if (!hasListener) { const l = node.__listeners && node.__listeners.get(type); if (l && l.length) hasListener = true; }
+        node = node.parentNode || node.__owner || null;
+      }
+    } else {
+      const targetRoot = treeRootOf(target);
+      let node = this;
+      while (node) {
+        path.push(node);
+        if (!hasListener) { const l = node.__listeners && node.__listeners.get(type); if (l && l.length) hasListener = true; }
+        if (node.__isShadowRoot) {
+          // a non-composed event stops at the shadow boundary enclosing its
+          // target; a composed event continues up through the host.
+          node = (!event.composed && node === targetRoot) ? null : (node.host || null);
+        } else {
+          node = node.parentNode || node.__owner || null;
+        }
+      }
     }
     event._path = path;
 
@@ -176,11 +225,19 @@ export class EventTarget {
       activation = this.__preClickActivation();
     }
 
+    // relatedTarget (focus/mouseenter/mouseleave) is retargeted per listener
+    // exactly like target. Only relevant under shadow with a non-null value.
+    const relatedTarget = useShadow ? event.relatedTarget : null;
     const invoke = (node, phase) => {
       const list = node.__listeners && node.__listeners.get(event.type);
       if (!list || list.length === 0) return;
       event.currentTarget = node;
       event.eventPhase = phase;
+      // present `target`/`relatedTarget` retargeted to the listener's tree
+      if (useShadow) {
+        event.target = retarget(target, node);
+        if (relatedTarget != null) event.relatedTarget = retarget(relatedTarget, node);
+      }
       // snapshot — listeners added during dispatch don't fire this round
       for (const l of list.slice()) {
         if (phase === PHASE_CAPTURING && !l.capture) continue;
@@ -221,6 +278,10 @@ export class EventTarget {
 
     event.eventPhase = PHASE_NONE;
     event.currentTarget = null;
+    if (useShadow) { // restore from any retargeting
+      event.target = target;
+      if (relatedTarget != null) event.relatedTarget = relatedTarget;
+    }
 
     // canceled activation: undo the pre-click toggle if default was prevented.
     // Otherwise a checkbox/radio toggle fires input then change (activation

package/src/runtime/index.mjs

@@ -38,13 +38,34 @@ function parseBufferCached(html) {
   return soa;
 }
 
+// Declarative Shadow DOM: promote every `<template shadowrootmode="open|closed">`
+// into a real ShadowRoot on its parent (content moved in, template removed). This
+// is a DOM walk, so it's gated by a cheap substring check on the HTML source in
+// createEnvironment/reset — a document with no declarative shadow root pays
+// nothing (the walk never runs).
+function promoteDeclarativeShadowRoots(document) {
+  for (const tpl of Array.from(document.getElementsByTagName('template'))) {
+    const mode = tpl.getAttribute('shadowrootmode');
+    if (mode !== 'open' && mode !== 'closed') continue;
+    const host = tpl.parentNode;
+    if (!host || host.nodeType !== 1 || host.__shadow) continue;
+    const root = host.attachShadow({ mode, delegatesFocus: tpl.hasAttribute('shadowrootdelegatesfocus') });
+    if (tpl.content) for (const c of tpl.content.__children().slice()) root.appendChild(c);
+    host.removeChild(tpl);
+  }
+}
+
 export function createEnvironment(html = '<!doctype html><html><head></head><body></body></html>', options = {}) {
   // Layer 1: native parse → immutable SoA buffer (typed arrays, one boundary copy).
-  let soa = parseBufferCached(String(html));
+  let currentHtml = String(html);
+  let soa = parseBufferCached(currentHtml);
 
   // Layer 2: Document over the buffer (nodes inflate lazily from the arrays).
   const document = new Document();
+  // declarative shadow roots only when the source even mentions them (cheap gate)
+  const maybePromote = () => { if (currentHtml.includes('shadowroot')) promoteDeclarativeShadowRoots(document); };
   document.__load(soa);
+  maybePromote();
 
   // Layer 3: lazy window.
   const win = createWindow(document, options);
@@ -58,8 +79,9 @@ export function createEnvironment(html = '<!doctype html><html><head></head><bod
     // Layer 5: arena-style reset. Re-point at the (re)parsed buffer, drop the
     // owned overlay + node cache + materialized globals. Class machinery stays warm.
     reset(nextHtml) {
-      if (nextHtml !== undefined) soa = parseBufferCached(String(nextHtml));
+      if (nextHtml !== undefined) { currentHtml = String(nextHtml); soa = parseBufferCached(currentHtml); }
       document.__load(soa);       // drops __cache + __kids overlay, keeps the buffer if reused
+      maybePromote();
       win.resetGlobals();
       document.__active = null;
       document.__cookieJar = null;

package/src/runtime/selectors.mjs

@@ -109,11 +109,6 @@ function splitTopLevel(s, sep) {
   return out;
 }
 
-function elementChildren(node) {
-  const kids = typeof node.__children === 'function' ? node.__children() : Array.from(node.childNodes || []);
-  return kids.filter((n) => n.nodeType === 1);
-}
-
 function matchAttr(el, a) {
   const raw = el.getAttribute(a.name);   // single lookup (null = absent)
   if (raw === null) return false;

package/src/runtime/window.mjs

@@ -13,7 +13,7 @@ import {
 import { makeGetComputedStyle } from './cascade.mjs';
 import {
   Node, Element, Text, Comment, Document, DocumentFragment, DocumentType, Event, CustomEvent,
-  MutationObserver, DOMParser, XMLSerializer,
+  MutationObserver, DOMParser, XMLSerializer, ShadowRoot,
 } from './dom.mjs';
 import {
   EventTarget,
@@ -244,6 +244,7 @@ function makeXHR() {
 const STATIC_BASE = {
   // DOM + event constructors (cheap class refs)
   Node, Element, Text, Comment, Document, DocumentFragment, DocumentType, EventTarget,
+  ShadowRoot,
   Event, CustomEvent,
   UIEvent, MouseEvent, PointerEvent, KeyboardEvent, InputEvent, FocusEvent,
   CompositionEvent, WheelEvent, TouchEvent, DragEvent, ProgressEvent, ClipboardEvent,
@@ -302,7 +303,7 @@ const STATIC_BASE = {
   HTMLHeadElement: tagClass('head'), HTMLHtmlElement: tagClass('html'),
   HTMLDataElement: tagClass('data'), HTMLTimeElement: tagClass('time'),
   HTMLSlotElement: tagClass('slot'), HTMLMenuElement: tagClass('menu'),
-  HTMLDocument: Document, ShadowRoot: DocumentFragment,
+  HTMLDocument: Document,
   MutationObserver, DOMParser, XMLSerializer,
   URL: TURBO_URL, URLSearchParams,
   Blob: globalThis.Blob, File: TURBO_FILE, FileReader,