dommy 0.8.0 → 0.9.0

data/lib/dommy/document.rb

@@ -71,6 +71,8 @@ module Dommy
         @public_id
       when "systemId"
         @system_id
+      when "ownerDocument"
+        @owner_document
       end
     end
 
@@ -81,13 +83,16 @@ module Dommy
     end
 
     include Bridge::Methods
-    js_methods %w[isEqualNode isSameNode getRootNode hasChildNodes normalize compareDocumentPosition
+    js_methods %w[isEqualNode isSameNode getRootNode hasChildNodes normalize compareDocumentPosition contains
       appendChild insertBefore removeChild replaceChild before after replaceWith remove
       addEventListener removeEventListener dispatchEvent]
     def __js_call__(method, args)
       case method
       when "hasChildNodes"
         false
+      when "contains"
+        # A DocumentType is a leaf node: it contains only itself.
+        !args[0].nil? && is_same_node(args[0])
       when "isEqualNode"
         is_equal_node(args[0])
       when "isSameNode"
@@ -97,8 +102,12 @@ module Dommy
       when "compareDocumentPosition"
         compare_document_position(args[0])
       when "appendChild", "insertBefore"
+        raise Bridge::TypeError, "Argument is not a Node." unless args[0].is_a?(Dommy::Node)
+
         raise DOMException::HierarchyRequestError, "a DocumentType may not have children"
       when "removeChild", "replaceChild"
+        raise Bridge::TypeError, "Argument is not a Node." unless args[0].is_a?(Dommy::Node)
+
         raise DOMException::NotFoundError, "the node to be removed is not a child of this node"
       when "before"
         before(*args)
@@ -120,143 +129,22 @@ module Dommy
     end
   end
 
-  # ProcessingInstruction (`<?target data?>`) — a CharacterData-like node with a
-  # `target`; created via `document.createProcessingInstruction`.
-  class ProcessingInstruction
-    include Node
-
-    attr_reader :target
-
-    def initialize(target, data)
-      @target = target.to_s
-      @data = data.to_s
-    end
-
-    include EventTarget
-
-    def data = @data
-
-    def __js_get__(key)
-      case key
-      when "target"
-        @target
-      when "data", "nodeValue", "textContent"
-        @data
-      when "nodeName"
-        @target
-      when "nodeType"
-        7
-      when "length"
-        @data.length
-      end
-    end
-
-    def __js_set__(key, value)
-      case key
-      when "data", "nodeValue", "textContent"
-        @data = value.to_s
-      else
-        return Bridge::UNHANDLED
-      end
-      nil
-    end
-
-    # A PI is CharacterData: its data methods are string operations on @data.
-    def substring_data(offset, count)
-      o = offset.to_i
-      raise DOMException::IndexSizeError, "offset out of bounds" if o.negative? || o > @data.length
-
-      @data[o, count.to_i] || ""
-    end
-
-    def append_data(value)
-      @data += value.to_s
-      nil
-    end
-
-    def insert_data(offset, value)
-      o = offset.to_i
-      raise DOMException::IndexSizeError, "offset out of bounds" if o.negative? || o > @data.length
-
-      @data = @data[0, o].to_s + value.to_s + (@data[o..] || "")
-      nil
-    end
-
-    def delete_data(offset, count)
-      o = offset.to_i
-      raise DOMException::IndexSizeError, "offset out of bounds" if o.negative? || o > @data.length
-
-      @data = @data[0, o].to_s + (@data[(o + count.to_i)..] || "")
-      nil
-    end
-
-    def replace_data(offset, count, value)
-      delete_data(offset, count)
-      insert_data(offset, value)
-      nil
-    end
-
-    def __internal_event_parent__
-      nil
-    end
-
-    include Bridge::Methods
-    js_methods %w[isEqualNode isSameNode getRootNode normalize hasChildNodes
-      appendData insertData deleteData replaceData substringData compareDocumentPosition
-      appendChild insertBefore removeChild replaceChild before after replaceWith remove
-      addEventListener removeEventListener dispatchEvent]
-    def __js_call__(method, args)
-      case method
-      when "hasChildNodes"
-        false
-      when "isEqualNode"
-        is_equal_node(args[0])
-      when "isSameNode"
-        is_same_node(args[0])
-      when "getRootNode"
-        get_root_node(args[0])
-      when "compareDocumentPosition"
-        compare_document_position(args[0])
-      when "appendChild", "insertBefore"
-        raise DOMException::HierarchyRequestError, "a ProcessingInstruction may not have children"
-      when "removeChild", "replaceChild"
-        raise DOMException::NotFoundError, "the node to be removed is not a child of this node"
-      when "before", "after", "replaceWith", "remove"
-        # ChildNode mixin: a created PI has no parent, so these are no-ops per
-        # spec (they act only when the node is inserted in a tree).
-        nil
-      when "normalize"
-        nil
-      when "substringData"
-        substring_data(args[0], args[1])
-      when "appendData"
-        append_data(args[0])
-      when "insertData"
-        insert_data(args[0], args[1])
-      when "deleteData"
-        delete_data(args[0], args[1])
-      when "replaceData"
-        replace_data(args[0], args[1], args[2])
-      when "addEventListener"
-        add_event_listener(args[0], args[1], args[2])
-      when "removeEventListener"
-        remove_event_listener(args[0], args[1], args[2])
-      when "dispatchEvent"
-        dispatch_event(args[0])
-      end
-    end
-  end
-
-  # `document.implementation` — the DOMImplementation. Only the node factories
-  # WPT exercises are provided; createDocument/createHTMLDocument are not yet
-  # implemented (foreign documents).
+  # `document.implementation` — the DOMImplementation.
   class DOMImplementation
     def initialize(document)
       @document = document
     end
 
+    # A created DocumentType's node document is the implementation's document.
+    # (Qualified-name validation against the QName production is not enforced —
+    # a couple of invalid-name WPT cases stay as documented gaps.)
     def create_document_type(qualified_name, public_id, system_id)
-      DocumentType.new(qualified_name, public_id, system_id)
+      DocumentType.new(qualified_name, public_id, system_id, owner_document: @document)
+    end
+
+    # `hasFeature()` is a no-op that always returns true (DOM Standard).
+    def has_feature(*)
+      true
     end
 
     # createDocument(namespace, qualifiedName, doctype?) — a fresh XML document,
@@ -264,11 +152,21 @@ module Dommy
     # non-empty. (The doctype argument is accepted but not stored, as document
     # equality compares only structure that survives wrap_node.)
     def create_document(namespace, qualified_name, _doctype = nil)
-      doc = Document.new(nil, nokogiri_doc: Backend.document_class.new)
+      doc = Document.new(nil, backend_doc: Backend.empty_xml_document)
+      # createDocument's content type is keyed off the namespace. None is
+      # "text/html", so tagName keeps its case; xhtml+xml still routes
+      # createElement to the HTML namespace (so an XHTML document isEqualNode
+      # an HTML one).
+      doc.content_type =
+        case namespace.to_s
+        when Internal::Namespaces::HTML then "application/xhtml+xml"
+        when Internal::Namespaces::SVG then "image/svg+xml"
+        else "application/xml"
+        end
       qn = qualified_name.to_s
       unless qn.empty?
         el = doc.send(:create_element_ns, namespace, qualified_name)
-        doc.nokogiri_doc.root = el.__dommy_backend_node__
+        Backend.set_document_root(doc.backend_doc, el.__dommy_backend_node__)
       end
       doc
     end
@@ -276,15 +174,15 @@ module Dommy
     # createHTMLDocument(title?) — a fresh HTML document (doctype + html > head,
     # body), with an optional <title>.
     def create_html_document(title = nil)
-      doc = Document.new(nil, nokogiri_doc: Backend.parse("<!DOCTYPE html><html><head></head><body></body></html>"))
+      doc = Document.new(nil, backend_doc: Backend.parse("<!DOCTYPE html><html><head></head><body></body></html>"))
       doc.title = title.to_s unless title.nil? || title.equal?(Bridge::UNDEFINED)
       doc
     end
 
-    def __js_get__(_key) = nil
+    def __js_get__(_key) = Bridge::ABSENT # method-only; any property read is absent
 
     include Bridge::Methods
-    js_methods %w[createDocumentType createDocument createHTMLDocument]
+    js_methods %w[createDocumentType createDocument createHTMLDocument hasFeature]
     def __js_call__(method, args)
       case method
       when "createDocumentType"
@@ -293,6 +191,8 @@ module Dommy
         create_document(args[0], args[1], args[2])
       when "createHTMLDocument"
         create_html_document(args[0])
+      when "hasFeature"
+        has_feature
       end
     end
   end
@@ -304,13 +204,108 @@ module Dommy
     include EventTarget
     include Node
 
-    attr_reader :nokogiri_doc
+    attr_reader :backend_doc
     attr_accessor :default_view
+    # --- CSS cascade support (Internal::CSS) ---
+    # Monotonic counter bumped on every DOM mutation; the CSS layer
+    # invalidates its per-document style cache wholesale when it moves.
+    # The cache slot itself is owned by Internal::CSS::Cascade.
+    attr_accessor :__css_style_cache__
+
+    def style_generation
+      @style_generation || 0
+    end
+
+    def __internal_bump_style_generation__
+      @style_generation = style_generation + 1
+      nil
+    end
+
+    # A by-id/class/tag index of the backend element tree, memoized per DOM
+    # generation, for SelectorMatcher's document-scoped fast path (or nil to tell
+    # the caller to walk). Rebuilt lazily only after a mutation bumps
+    # style_generation, so it costs one tree walk per generation and pays off when
+    # several queries run before the next mutation.
+    #
+    # Adaptive bypass: if the index keeps getting invalidated after serving only a
+    # handful of queries (a mutation-between-every-query workload, where building
+    # it never pays back), stop building it and just walk — re-testing
+    # periodically. This keeps the worst case at walk speed rather than the ~15%
+    # regression an always-on index would add.
+    SELECTOR_INDEX_MIN_REUSE = 3   # queries an index must serve to have paid for its build
+    SELECTOR_INDEX_LOW_RUN_LIMIT = 8 # consecutive low-reuse generations before bypassing
+    SELECTOR_INDEX_RETEST_GAP = 64 # generations to wait before re-testing a bypass
+
+    def __internal_selector_index__
+      gen = style_generation
+      if @__sel_idx_gen != gen
+        if @__sel_idx
+          if @__sel_idx_served.to_i < SELECTOR_INDEX_MIN_REUSE
+            @__sel_idx_low = @__sel_idx_low.to_i + 1
+            @__sel_idx_bypass = true if @__sel_idx_low >= SELECTOR_INDEX_LOW_RUN_LIMIT
+          else
+            @__sel_idx_low = 0
+          end
+        end
+        if @__sel_idx_bypass && (@__sel_idx_retest = @__sel_idx_retest.to_i + 1) >= SELECTOR_INDEX_RETEST_GAP
+          @__sel_idx_bypass = false
+          @__sel_idx_low = 0
+          @__sel_idx_retest = 0
+        end
+        @__sel_idx = nil
+        @__sel_idx_served = 0
+        @__sel_idx_gen = gen
+      end
+      return nil if @__sel_idx_bypass
+
+      @__sel_idx ||= Internal::SelectorIndex.build(@backend_doc)
+      @__sel_idx_served += 1
+      @__sel_idx
+    end
+
+    # An element-scoped querySelector(All) result cache (the document-rooted one
+    # lives in NodeWrapperCache). jQuery `$(el).find(sel)` re-queries the same
+    # (element, selector) constantly between mutations; this memoizes the match
+    # set, keyed by [scope object_id, kind, selector] and tagged with the DOM
+    # generation, so a hit skips the whole combinator match. Capped, and a
+    # mutation (style_generation bump) makes every entry stale at once.
+    SCOPED_QUERY_CACHE_CAP = 4096
+
+    def __internal_scoped_query_get(key)
+      entry = (@__scoped_query_cache ||= {})[key]
+      entry && entry[0] == style_generation ? entry[1] : nil
+    end
+
+    def __internal_scoped_query_set(key, value)
+      cache = (@__scoped_query_cache ||= {})
+      cache.clear if cache.size >= SCOPED_QUERY_CACHE_CAP
+      cache[key] = [style_generation, value]
+      value
+    end
+
+    # A host-supplied `->(url) { css_text_or_nil }` resolving @import URLs to
+    # CSS (Dommy has no network of its own — same idea as <link> filling).
+    # Setting it invalidates cached styles so the next cascade picks up imports.
+    attr_reader :css_import_resolver
+
+    def css_import_resolver=(resolver)
+      @css_import_resolver = resolver
+      __internal_bump_style_generation__
+    end
     # content_type defaults to "text/html"; settable so an integration layer
     # can reflect the response Content-Type. Read-only over the JS bridge.
     attr_accessor :content_type
-
-    def initialize(host = nil, nokogiri_doc: nil, default_view: nil)
+    # A `->(source_text) {}` set by the JS layer to execute a classic <script>'s
+    # body when it's connected (Dommy has no JS engine of its own). nil = inert
+    # scripts (the default for a standalone DOM).
+    attr_accessor :script_runner
+    # A `->(element, src) {}` set by the integration layer to fetch + execute a
+    # classic `<script src>` that's dynamically inserted into the document (e.g.
+    # webpack/Vite loading an on-demand chunk via document.head.appendChild). It
+    # owns firing the element's load / error event. nil = such scripts are inert.
+    attr_accessor :external_script_runner
+
+    def initialize(host = nil, backend_doc: nil, default_view: nil)
       @host = host
       @default_view = default_view
       @node_wrapper_cache = Internal::NodeWrapperCache.new(self)
@@ -320,8 +315,15 @@ module Dommy
       @template_content_registry = Internal::TemplateContentRegistry.new(self)
       @mutation_coordinator = Internal::MutationCoordinator.new(self, @observer_manager)
       @node_iterators = []
-      @nokogiri_doc = nokogiri_doc || Backend.parse("<!doctype html><html><head></head><body></body></html>")
+      @backend_doc = backend_doc || Backend.parse("<!doctype html><html><head></head><body></body></html>")
       @content_type = "text/html"
+      # The document is fully parsed before scripts run (no incremental network
+      # parse), so it defaults to "complete" — ready-gated code takes the
+      # already-loaded path. An embedder can replay the real lifecycle
+      # ("loading" → "interactive" → "complete") via #__internal_set_ready_state__
+      # to drive code that waits on DOMContentLoaded / load.
+      @ready_state = "complete"
+      @__current_script__ = nil
     end
 
     # Whether this is an "HTML document" in the DOM sense (created by the HTML
@@ -339,7 +341,7 @@ module Dommy
     # public/system identifier) is no-quirks. (The full quirks algorithm keys off
     # specific legacy public ids; this covers the common cases.)
     def compat_mode
-      dt = @nokogiri_doc.internal_subset
+      dt = @backend_doc.internal_subset
       return "BackCompat" unless dt
       return "CSS1Compat" if dt.name.to_s.downcase == "html" && dt.external_id.nil?
 
@@ -358,11 +360,11 @@ module Dommy
 
     def document_element
       # The document's root element — `<html>` for HTML, the actual root for XML.
-      wrap_node(@nokogiri_doc.root)
+      wrap_node(@backend_doc.root)
     end
 
     def head
-      wrap_node(@nokogiri_doc.at_css("head"))
+      wrap_node(@backend_doc.at_css("head"))
     end
 
     # Resolve `body` fresh from the tree (not memoized) so it tracks a swapped
@@ -371,22 +373,34 @@ module Dommy
     # wrapper would keep returning the detached old body. wrap_node caches by
     # node, so identity (`document.body === document.body`) still holds.
     def body
-      wrap_node(@nokogiri_doc.at_css("body"))
+      wrap_node(@backend_doc.at_css("body"))
+    end
+
+    # The document's accessibility tree (built from <body>; the document itself
+    # has no accessible node). See Internal::AccessibilityTree.
+    def accessibility_tree
+      Internal::AccessibilityTree.build(self)
+    end
+    alias_method :aria_tree, :accessibility_tree
+
+    # A Playwright-compatible ARIA snapshot of the document.
+    def aria_snapshot
+      Internal::AriaSnapshot.serialize(accessibility_tree)
     end
 
     # Serialize the whole document to HTML (including the doctype).
     def to_html
-      @nokogiri_doc.to_html
+      @backend_doc.to_html
     end
 
     # XPath queries returning wrapped nodes (Element / TextNode / etc).
     def at_xpath(expression)
-      node = @nokogiri_doc.at_xpath(expression)
+      node = @backend_doc.at_xpath(expression)
       node && wrap_node(node)
     end
 
     def xpath(expression)
-      @nokogiri_doc.xpath(expression).map { |node| wrap_node(node) }
+      @backend_doc.xpath(expression).map { |node| wrap_node(node) }
     end
 
     # `document.URL` / `documentURI` — both return location.href in
@@ -404,7 +418,7 @@ module Dommy
     # ignore subsequent <base> elements; we mirror that.
     def base_uri
       doc_url = url
-      base_el = @nokogiri_doc.at_css("base[href]")
+      base_el = @backend_doc.at_css("base[href]")
       return doc_url unless base_el
 
       href = base_el["href"].to_s
@@ -445,25 +459,25 @@ module Dommy
     # document so post-mutation reads reflect the current state.
     def links
       HTMLCollection.new do
-        @nokogiri_doc.css("a[href], area[href]").map { |n| wrap_node(n) }.compact
+        @backend_doc.css("a[href], area[href]").map { |n| wrap_node(n) }.compact
       end
     end
 
     def forms
       HTMLCollection.new do
-        @nokogiri_doc.css("form").map { |n| wrap_node(n) }.compact
+        @backend_doc.css("form").map { |n| wrap_node(n) }.compact
       end
     end
 
     def scripts
       HTMLCollection.new do
-        @nokogiri_doc.css("script").map { |n| wrap_node(n) }.compact
+        @backend_doc.css("script").map { |n| wrap_node(n) }.compact
       end
     end
 
     def images
       HTMLCollection.new do
-        @nokogiri_doc.css("img").map { |n| wrap_node(n) }.compact
+        @backend_doc.css("img").map { |n| wrap_node(n) }.compact
       end
     end
 
@@ -471,7 +485,7 @@ module Dommy
     # in practice the `<html>` root).
     def children
       HTMLCollection.new do
-        root = @nokogiri_doc.root
+        root = @backend_doc.root
         root ? [wrap_node(root)].compact : []
       end
     end
@@ -481,7 +495,7 @@ module Dommy
     # `document.childNodes === document.childNodes` and mutations are reflected.
     def child_nodes
       @live_child_nodes ||= LiveNodeList.new do
-        @nokogiri_doc.children.map { |n| wrap_node(n) }.compact
+        @backend_doc.children.map { |n| wrap_node(n) }.compact
       end
     end
 
@@ -490,11 +504,11 @@ module Dommy
     end
 
     def first_element_child
-      wrap_node(@nokogiri_doc.root)
+      wrap_node(@backend_doc.root)
     end
 
     def last_element_child
-      wrap_node(@nokogiri_doc.root)
+      wrap_node(@backend_doc.root)
     end
 
     # Currently-focused element (or body if none). Updated via
@@ -511,13 +525,37 @@ module Dommy
       return false unless other.respond_to?(:__dommy_backend_node__)
 
       node = other.__dommy_backend_node__
-      node.document == @nokogiri_doc && node.ancestors.include?(@nokogiri_doc)
+      node.document == @backend_doc && node.ancestors.include?(@backend_doc)
     end
 
     def __internal_set_active_element__(el)
+      # Focus is selector-observable state (:focus / :focus-within rules), so
+      # a change invalidates computed styles.
+      __internal_bump_style_generation__ unless @active_element.equal?(el)
       @active_element = el
     end
 
+    # The explicitly focused element (nil when nothing holds focus) — what
+    # :focus matches. Distinct from #active_element, which falls back to
+    # <body> per spec.
+    def __internal_focused_element__
+      @active_element
+    end
+
+    # The element the (virtual) pointer hovers — :hover matches it and its
+    # ancestors. Set from tests or capybara-dommy's Node#hover; nil clears.
+    def __internal_hovered_element__
+      @hovered_element
+    end
+
+    def __internal_set_hovered_element__(el)
+      return if @hovered_element.equal?(el)
+
+      @hovered_element = el
+      __internal_bump_style_generation__
+      nil
+    end
+
     # Create a detached Attr. `setAttributeNode` attaches it to an
     # element. Per spec, name must match the XML Name production —
     # invalid names throw InvalidCharacterError.
@@ -534,7 +572,15 @@ module Dommy
     # Ruby Proc, a JS-bridge callable, or an object with
     # `accept_node` / `acceptNode`.
     def create_tree_walker(root, what_to_show = NodeFilter::SHOW_ALL, filter = nil)
-      TreeWalker.new(root, what_to_show, filter)
+      TreeWalker.new(require_node_root(root), what_to_show, filter)
+    end
+
+    # The `root` of a TreeWalker / NodeIterator is a non-nullable WebIDL `Node`:
+    # a null or non-Node argument is a TypeError before construction.
+    def require_node_root(root)
+      return root if root.is_a?(Dommy::Node)
+
+      raise Bridge::TypeError, "createTreeWalker/createNodeIterator root must be a Node"
     end
 
     # WebIDL `unsigned long whatToShow = 0xFFFFFFFF`: an omitted or `undefined`
@@ -576,25 +622,22 @@ module Dommy
       src.unlink if src.parent
 
       # Same document: just return the wrapper after the detach above.
-      return wrap_node(src) if src.document == @nokogiri_doc
+      return wrap_node(src) if src.document == @backend_doc
 
-      # Cross-document: Nokogiri reassigns `src.document` when src is
-      # added under a node owned by another document. We transiently
-      # attach to our root, then unlink so src ends up free-floating
-      # but now belongs to @nokogiri_doc. The underlying Ruby object
-      # identity is preserved.
+      # Cross-document: hand the detached source to the backend, which
+      # returns the node now owned by this document — an imported copy for
+      # Makiri (a node can't move between arenas). Drop the stale source
+      # wrapper, then reseat the caller's Dommy wrapper onto the adopted
+      # node so `adopt_node(x).equal?(x)` stays true across documents.
       src_doc_wrapper = node.instance_variable_get(:@document)
-      @nokogiri_doc.root.add_child(src)
-      src.unlink
+      adopted = Backend.adopt(src, @backend_doc)
 
-      # Move the caller's Dommy wrapper from the source document's
-      # wrapper cache into ours, and re-point its @document. This
-      # keeps `adopt_node(x).equal?(x)` true across documents.
-      node.instance_variable_set(:@document, self)
       if src_doc_wrapper.respond_to?(:__internal_reset_wrapper__)
         src_doc_wrapper.__internal_reset_wrapper__(src)
       end
-      @node_wrapper_cache.register(src, node)
+      node.instance_variable_set(:@document, self)
+      node.instance_variable_set(:@__node__, adopted)
+      @node_wrapper_cache.register(adopted, node)
       node
     end
 
@@ -670,13 +713,31 @@ module Dommy
     # `document.createNodeIterator(root, whatToShow?, filter?)` —
     # flat depth-first iteration.
     def create_node_iterator(root, what_to_show = NodeFilter::SHOW_ALL, filter = nil)
+      root = require_node_root(root)
       iterator = NodeIterator.new(root, what_to_show, filter)
-      # Track live iterators so node removal can run the "NodeIterator
-      # pre-removing steps" (adjusting referenceNode) before a node detaches.
-      @node_iterators << iterator
+      # The "NodeIterator pre-removing steps" run for iterators whose root's node
+      # document is the removed node's document. Track the iterator on the root's
+      # document — which is `self` for a same-document root, but a different
+      # document when the root came from elsewhere (e.g.
+      # implementation.createHTMLDocument), where the removal fires.
+      node_iterator_document(root).__internal_track_node_iterator__(iterator)
       iterator
     end
 
+    # The document that owns `root`'s subtree (where its removals fire), so a
+    # NodeIterator is tracked where its pre-removing steps will run. Falls back
+    # to `self` for a root with no resolvable document.
+    def node_iterator_document(root)
+      return root if root.is_a?(Dommy::Document)
+
+      doc = root.instance_variable_get(:@document)
+      doc.is_a?(Dommy::Document) ? doc : self
+    end
+
+    def __internal_track_node_iterator__(iterator)
+      @node_iterators << iterator
+    end
+
     # Minimal DocumentType — represents the `<!doctype html>` line.
     # Always present in HTML5 documents we parse, so we synthesize a
     # stub object whose only useful field is `name`. Tests just need
@@ -692,7 +753,7 @@ module Dommy
     end
 
     def create_processing_instruction(target, data)
-      ProcessingInstruction.new(target, data)
+      @node_wrapper_cache.create_processing_instruction(target, data)
     end
 
     # Append a node as a child of the document itself (e.g. a comment alongside
@@ -700,37 +761,38 @@ module Dommy
     def append_child(node)
       return node unless node.respond_to?(:__dommy_backend_node__)
 
-      @nokogiri_doc.add_child(node.__dommy_backend_node__)
+      # appendChild adopts a node from another document (per spec). Only needed on
+      # a backend that can't move a node across documents (Makiri).
+      if !Backend.moves_nodes_across_documents? && node.respond_to?(:document) && !node.document.equal?(self)
+        node = adopt_node(node)
+      end
+      @backend_doc.add_child(node.__dommy_backend_node__)
       node
     end
 
     # ParentNode / Node mutation on the document's direct children (the doctype
-    # and the document element). Operate on the Nokogiri document node; string
-    # arguments (which would need a text child the document can't hold) are
-    # ignored rather than raising.
+    # and the document element).
     def document_insert(args, prepend:)
       nodes = args.filter_map { |a| backend_node(a) }
-      if prepend && (first = @nokogiri_doc.children.first)
+      if prepend && (first = @backend_doc.children.first)
         nodes.reverse_each { |n| first.add_previous_sibling(n) }
       else
-        nodes.each { |n| @nokogiri_doc.add_child(n) }
+        nodes.each { |n| @backend_doc.add_child(n) }
       end
       nil
     end
 
     def document_replace_children(args)
-      @nokogiri_doc.children.each(&:unlink)
-      args.filter_map { |a| backend_node(a) }.each { |n| @nokogiri_doc.add_child(n) }
+      @backend_doc.children.each(&:unlink)
+      args.filter_map { |a| backend_node(a) }.each { |n| @backend_doc.add_child(n) }
       nil
     end
 
     def document_remove_child(node)
-      # The doctype is synthesized from the Nokogiri DTD rather than wrapped as a
-      # tree node, so remove the internal subset directly.
       return __internal_remove_doctype__(node) if node.is_a?(DocumentType)
 
       bn = backend_node(node)
-      raise DOMException::NotFoundError, "node is not a child of this document" unless bn && bn.parent == @nokogiri_doc
+      raise DOMException::NotFoundError, "node is not a child of this document" unless bn && bn.parent == @backend_doc
 
       bn.unlink
       node
@@ -741,17 +803,17 @@ module Dommy
       return node unless bn
 
       ref_node = ref && backend_node(ref)
-      if ref_node && ref_node.parent == @nokogiri_doc
+      if ref_node && ref_node.parent == @backend_doc
         ref_node.add_previous_sibling(bn)
       else
-        @nokogiri_doc.add_child(bn)
+        @backend_doc.add_child(bn)
       end
       node
     end
 
     def document_replace_child(new_child, old_child)
       old_bn = backend_node(old_child)
-      raise DOMException::NotFoundError, "node is not a child of this document" unless old_bn && old_bn.parent == @nokogiri_doc
+      raise DOMException::NotFoundError, "node is not a child of this document" unless old_bn && old_bn.parent == @backend_doc
 
       new_bn = backend_node(new_child)
       old_bn.add_previous_sibling(new_bn) if new_bn
@@ -763,7 +825,7 @@ module Dommy
     # remove the internal subset and mark it gone.
     def __internal_remove_doctype__(_doctype)
       @doctype_removed = true
-      @nokogiri_doc.internal_subset&.unlink
+      @backend_doc.internal_subset&.unlink
       nil
     end
 
@@ -772,20 +834,20 @@ module Dommy
     def __internal_insert_at_doctype__(nodes, after:)
       bns = nodes.filter_map { |n| backend_node(n) }
       if after
-        root = @nokogiri_doc.root
-        root ? bns.each { |n| root.add_previous_sibling(n) } : bns.each { |n| @nokogiri_doc.add_child(n) }
+        root = @backend_doc.root
+        root ? bns.each { |n| root.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
       else
-        first = @nokogiri_doc.children.first
-        first ? bns.reverse_each { |n| first.add_previous_sibling(n) } : bns.each { |n| @nokogiri_doc.add_child(n) }
+        first = @backend_doc.children.first
+        first ? bns.reverse_each { |n| first.add_previous_sibling(n) } : bns.each { |n| @backend_doc.add_child(n) }
       end
       nil
     end
 
     # `document.cloneNode(deep)` → a fresh Document over a (deep) copy of the
-    # Nokogiri tree, preserving the content type.
+    # Makiri tree, preserving the content type.
     def clone_node(deep)
-      copy = deep ? @nokogiri_doc.dup : Backend.document_class.new
-      Document.new(nil, nokogiri_doc: copy).tap { |d| d.content_type = @content_type }
+      copy = deep ? Backend.clone_document(@backend_doc) : Backend.empty_document_like(@backend_doc)
+      Document.new(nil, backend_doc: copy).tap { |d| d.content_type = @content_type }
     end
 
     def backend_node(node)
@@ -816,7 +878,7 @@ module Dommy
     end
 
     def get_elements_by_tag_name_ns(namespace, local_name)
-      HTMLCollection.elements_by_tag_name_ns(@nokogiri_doc, self, namespace, local_name)
+      HTMLCollection.elements_by_tag_name_ns(@backend_doc, self, namespace, local_name)
     end
 
     # `document.write(html)` — legacy API. Appends parsed nodes to the
@@ -824,7 +886,7 @@ module Dommy
     # this stub is enough for tests that fire write() during teardown.
     def write(*args)
       html = args.join
-      fragment = Parser.fragment(html, owner_doc: @nokogiri_doc)
+      fragment = Parser.fragment(html, owner_doc: @backend_doc)
       removed = []
       added = fragment.children.to_a
       body_node = body.__dommy_backend_node__
@@ -851,14 +913,22 @@ module Dommy
       __js_set__(key.to_s, value)
     end
 
-    # Create a Comment node. Wraps the Nokogiri comment so it flows
+    # Create a Comment node. Wraps the Makiri comment so it flows
     # through the same wrap_node identity machinery as Element / TextNode.
     def create_comment(text)
       @node_wrapper_cache.create_comment(text)
     end
 
     def create_cdata_section(text)
-      @node_wrapper_cache.create_cdata_section(text)
+      # WHATWG: createCDATASection throws NotSupportedError on an HTML document
+      # (CDATA sections exist only in XML). This also sidesteps Lexbor's HTML
+      # serializer, which can't emit a CDATA node.
+      raise DOMException::NotSupportedError, "createCDATASection is not supported on an HTML document" if html_document?
+
+      str = text.to_s
+      raise DOMException::InvalidCharacterError, "CDATA section data must not contain ']]>'" if str.include?("]]>")
+
+      @node_wrapper_cache.create_cdata_section(str)
     end
 
     def create_document_fragment
@@ -886,10 +956,10 @@ module Dommy
       when "fullscreenEnabled"
         true
       when "scrollingElement"
-        wrap_node(@nokogiri_doc.at_css("html"))
+        wrap_node(@backend_doc.at_css("html"))
       when "documentElement"
         # The document's root element — `<html>` for HTML, the actual root for XML.
-        wrap_node(@nokogiri_doc.root)
+        wrap_node(@backend_doc.root)
       when "title"
         read_title
       when "cookie"
@@ -921,11 +991,10 @@ module Dommy
       when "lastModified"
         @last_modified || "01/01/1970 00:00:00"
       when "readyState"
-        # The document is fully parsed by the time scripts run against it (there
-        # is no incremental network parse), so it is always "complete". Code that
-        # gates on `document.readyState === "loading"` (e.g. Turbo's preloader)
-        # therefore takes the already-loaded path.
-        "complete"
+        # "complete" by default (the document is fully parsed before scripts
+        # run); an embedder can replay "loading" → "interactive" → "complete"
+        # via #__internal_set_ready_state__.
+        @ready_state
       when "visibilityState"
         # There's no real viewport/tab; the document is treated as the visible,
         # foreground page (so `nextRepaint`-style code uses requestAnimationFrame,
@@ -943,18 +1012,23 @@ module Dommy
         forms
       when "scripts"
         scripts
+      when "currentScript"
+        # The <script> currently executing, set by the host around each script
+        # run (see #__internal_set_current_script__); null outside execution.
+        @__current_script__
       when "images"
         images
       when "embeds", "plugins"
         # Both reflect the same list of <embed> elements.
-        HTMLCollection.new { @nokogiri_doc.css("embed").map { |n| wrap_node(n) }.compact }
+        HTMLCollection.new { @backend_doc.css("embed").map { |n| wrap_node(n) }.compact }
+      when "applets"
+        # `<applet>` was removed from HTML, so this collection is always empty.
+        HTMLCollection.new { [] }
       when "anchors"
         # Historically `<a name>` (with a name attribute), not every link.
-        HTMLCollection.new { @nokogiri_doc.css("a[name]").map { |n| wrap_node(n) }.compact }
+        HTMLCollection.new { @backend_doc.css("a[name]").map { |n| wrap_node(n) }.compact }
       when "styleSheets"
-        # No CSS engine; expose an empty (but present + iterable) StyleSheetList
-        # so `document.styleSheets.length` / iteration don't blow up.
-        NodeList.new
+        style_sheets
       when "children"
         children
       when "childNodes"
@@ -976,7 +1050,7 @@ module Dommy
       when "nodeName"
         "#document"
       else
-        nil
+        Bridge::ABSENT # unknown property: JS undefined, `in` reports absent
       end
     end
 
@@ -1012,12 +1086,20 @@ module Dommy
       adoptNode hasFocus getSelection elementFromPoint queryCommandSupported addEventListener
       removeEventListener dispatchEvent write writeln open close isEqualNode appendChild
       hasChildNodes contains append prepend replaceChildren removeChild insertBefore replaceChild
-      cloneNode normalize
+      cloneNode normalize compareDocumentPosition getRootNode
     ]
     def __js_call__(method, args)
       case method
+      when "getRootNode"
+        # A document is its own root (no shadow tree above it), for any options.
+        # Exposing this is load-bearing: React's resource hoisting computes its
+        # "resource root" as `container.getRootNode()` and throws (#446) if the
+        # document lacks it, falling back to the document's null ownerDocument.
+        self
       when "hasChildNodes"
-        @nokogiri_doc.children.any?
+        @backend_doc.children.any?
+      when "compareDocumentPosition"
+        compare_document_position(args[0])
       when "contains"
         contains?(args[0])
       when "isEqualNode"
@@ -1129,6 +1211,36 @@ module Dommy
       @default_view
     end
 
+    # Replay a document-lifecycle transition: set readyState, fire
+    # `readystatechange`, then the milestone event for the new state —
+    # `DOMContentLoaded` (bubbles, dispatched on the document) when it becomes
+    # "interactive", and `load` (on the window) when it becomes "complete". Lets
+    # an embedder drive code that waits on the document lifecycle (Stimulus /
+    # Turbo startup, jQuery `ready`, …). No-op when already in `state`.
+    def __internal_set_ready_state__(state)
+      state = state.to_s
+      return if @ready_state == state
+
+      @ready_state = state
+      dispatch_event(Event.new("readystatechange"))
+      case state
+      when "interactive"
+        dispatch_event(Event.new("DOMContentLoaded", "bubbles" => true))
+      when "complete"
+        @default_view&.dispatch_event(Event.new("load"))
+      end
+      nil
+    end
+
+    # Set `document.currentScript` to the <script> element being executed (and
+    # back to nil afterward). The host (script boot) brackets each classic
+    # script run with this so code reading `document.currentScript` sees its own
+    # element, matching browser behavior.
+    def __internal_set_current_script__(element)
+      @__current_script__ = element
+      nil
+    end
+
     # Delegate node wrapping to NodeWrapperCache
     def wrap_node(node)
       @node_wrapper_cache.wrap(node)
@@ -1159,6 +1271,12 @@ module Dommy
       @shadow_registry.find_enclosing(node)
     end
 
+    # Every ShadowRoot attached in this document — the cascade collects each
+    # one's <style> sheets and scopes them to that shadow tree.
+    def __internal_all_shadow_roots__
+      @shadow_registry.all
+    end
+
     # Lifecycle callback dispatchers. Errors raised inside user
     # callbacks are swallowed so a single buggy custom element can't
     # break the whole mutation pipeline.
@@ -1273,6 +1391,16 @@ module Dommy
       @node_wrapper_cache.query_selector_all(selector)
     end
 
+    # `document.styleSheets` — the CSSStyleSheet of each <style> and
+    # <link rel=stylesheet> in document order (CSSOM). Computed on access so
+    # it reflects the current tree.
+    def style_sheets
+      sheets = query_selector_all("style, link").filter_map do |element|
+        element.sheet if element.respond_to?(:sheet)
+      end
+      NodeList.new(sheets)
+    end
+
     def get_element_by_id(id)
       @node_wrapper_cache.get_element_by_id(id)
     end
@@ -1301,25 +1429,38 @@ module Dommy
 
     private
 
-    # Build a Nokogiri copy of the given node inside our @nokogiri_doc.
+    # Build a Nokogiri copy of the given node inside our @backend_doc.
     # `deep: true` recurses into children. Used by importNode and
     # adoptNode for cross-document transfer.
     def clone_into_doc(source, deep)
       copy = if source.element?
-        new_el = Backend.create_element(source.name, @nokogiri_doc)
+        new_el = Backend.create_element(source.name, @backend_doc)
         Backend.attribute_nodes(source).each { |a| new_el[a.name] = a.value }
         new_el
       elsif source.text?
-        Backend.create_text(source.content, @nokogiri_doc)
+        Backend.create_text(source.content, @backend_doc)
       elsif source.is_a?(Backend.comment_class)
-        Backend.create_comment(source.content, @nokogiri_doc)
+        Backend.create_comment(source.content, @backend_doc)
+      elsif source.is_a?(Backend.document_fragment_class)
+        # A DocumentFragment clones to a fragment (its children are appended by
+        # the deep pass below), NOT to its first child — `importNode(<template>
+        # .content, true)` must return a fragment so `.firstElementChild` works
+        # (Vue/Alpine x-for clone template content this way). Built via the
+        # document's own `fragment` (as TemplateContentRegistry does) rather than
+        # `document_fragment_class.new`, so it works on backends whose fragment
+        # class isn't directly instantiable (Makiri).
+        @backend_doc.fragment("")
       else
         # Fallback: serialize + reparse via fragment for unusual types.
-        fragment = Parser.fragment(source.to_html, owner_doc: @nokogiri_doc)
-        fragment.children.first || Backend.create_text("", @nokogiri_doc)
+        fragment = Parser.fragment(source.to_html, owner_doc: @backend_doc)
+        fragment.children.first || Backend.create_text("", @backend_doc)
       end
 
-      if deep && source.respond_to?(:children)
+      if source.element? && source.name == "template"
+        # A <template>'s contents live in a separate content fragment, not its
+        # child list, so the generic deep pass over `children` misses them.
+        clone_template_content(source, copy) if deep
+      elsif deep && source.respond_to?(:children)
         source.children.each do |child|
           copy.add_child(clone_into_doc(child, true))
         end
@@ -1328,24 +1469,39 @@ module Dommy
       copy
     end
 
+    # Clone a <template>'s content into a fragment registered as `copy`'s
+    # template content. The source content lives backend-dependently — Makiri
+    # keeps it in a native content fragment, Nokogiri keeps it as direct children
+    # before migration and in the registry after — so source it from the registry
+    # fragment when migrated, else from Backend.template_content_nodes.
+    def clone_template_content(source, copy)
+      src_frag = @template_content_registry.raw_fragment_for(source)
+      content_nodes = src_frag ? src_frag.children.to_a : Backend.template_content_nodes(source)
+      return if content_nodes.empty?
+
+      frag = @backend_doc.fragment("")
+      content_nodes.each { |n| frag.add_child(clone_into_doc(n, true)) }
+      @template_content_registry.store(copy, frag)
+    end
+
     def read_title
-      head = @nokogiri_doc.at_css("head")
+      head = @backend_doc.at_css("head")
       title = head&.at_css("title")
       title ? title.text : ""
     end
 
     def write_title(value)
-      head = @nokogiri_doc.at_css("head")
+      head = @backend_doc.at_css("head")
       return unless head
 
       title = head.at_css("title")
       unless title
-        title = Backend.create_element("title", @nokogiri_doc)
+        title = Backend.create_element("title", @backend_doc)
         head.add_child(title)
       end
 
       title.children.each(&:unlink)
-      title.add_child(Backend.create_text(value, @nokogiri_doc))
+      title.add_child(Backend.create_text(value, @backend_doc))
     end
 
   end
@@ -1384,6 +1540,8 @@ module Dommy
         @ready
       when "updateCallbackDone"
         @update_callback_done
+      else
+        Bridge::ABSENT
       end
     end